Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 7b43319

Browse files
os-justinclaude
andauthored
fix(data-objectstack): one spelling for the publish route's wire envelope (#8618)
`MetadataClient.publishDraft` unwrapped a `{ success, data }` envelope while `MetadataClient.publish` — the same route, ~250 lines down — did not. The route was measured at the producer rather than inferred from `PublishMetaItemResponseSchema`, which the card explicitly forbade acting on: - `POST /api/v1/meta/:type/:name/publish` has ONE mount, `rest-server.ts`, ending `res.json(await p.publishMetaItem(publishRequest))` — verbatim, no envelope branch. The project-scoped base re-mounts the same handler. - The envelope's one producer, `HttpDispatcher.success()`, does not serve this route: no publish branch in runtime's `/meta` domain, no row in its route ledger, and a three-segment `/meta` path that is not `/published` ends in `routeNotFound` — dispatcher-only Hono adapter included. - `packages/spec` states the split: `PublishMetaItemResponseSchema` documents "the FULL body"; the batch sibling documents one answered "inside the dispatcher's `{ success, data }` envelope". So the tolerance was a dialect with no producer (Commandment #0.1), failing in the direction that hides the problem: an enveloped body is one this door did not serve, and unwrapping it reads as a successful promotion. Pins go on the only input that separates the two spellings — an envelope-shaped body — and assert both methods return it verbatim and agree, while `version` / `seq` / `seedApplied` stay readable off both on a normal response. Two fixtures that pinned the deleted branch are replaced rather than re-spelled. Claude-Session: https://claude.ai/code/session_01YBWFb5YgMU5dw8p2VKj16S Co-authored-by: Claude <noreply@anthropic.com>
1 parent 968dc1e commit 7b43319

5 files changed

Lines changed: 370 additions & 19 deletions

File tree

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
'@object-ui/data-objectstack': patch
3+
---
4+
5+
**Fix:** `MetadataClient.publishDraft` no longer unwraps a `{ success, data }`
6+
envelope, so it and `MetadataClient.publish` hold ONE belief about the route
7+
they share (objectui#6962).
8+
9+
The two methods sit ~250 lines apart in `metadata-client.ts` and both POST
10+
`/api/v1/meta/:type/:name/publish`. `publishDraft` tolerated a dispatcher-shaped
11+
envelope and returned the inner object; `publish` returned the body as parsed.
12+
Nothing said which was right, and the card explicitly refused to settle it from
13+
`PublishMetaItemResponseSchema` alone — an inference from a declaration is not a
14+
measurement of the server.
15+
16+
So the producer was read instead, in the framework checkout:
17+
18+
- `POST /api/v1/meta/:type/:name/publish` has exactly ONE mount,
19+
`packages/rest/src/rest-server.ts`, whose handler ends
20+
`res.json(await p.publishMetaItem(publishRequest))` — the protocol object
21+
verbatim, no envelope branch on any arm. The ADR-0006 project-scoped base
22+
re-mounts that same handler.
23+
- The `{ success, data }` envelope has ONE producer, `HttpDispatcher.success()`,
24+
and it does not serve this route: no publish branch in `runtime`'s `/meta`
25+
domain (its three-segment arm is `/published`, GET only), no row in the
26+
dispatcher's route ledger, and a three-segment `/meta` path that is not
27+
`/published` terminates in a located `routeNotFound`. That holds for the
28+
dispatcher-only Hono adapter as much as for a full `rest` +
29+
`plugin-hono-server` boot, where the REST mount shadows the catch-all.
30+
- `packages/spec` declares the split in so many words:
31+
`PublishMetaItemResponseSchema` documents "the FULL body" of this route and
32+
records that the REST route hands the producer's object to `res.json()`
33+
verbatim, while the batch sibling `PublishPackageDraftsResponseSchema`
34+
documents a body answered "inside the dispatcher's `{ success, data }`
35+
envelope".
36+
37+
The route never envelopes, so the tolerance was a dialect with no producer —
38+
Commandment #0.1's lenient fallback, and the kind that fails in the direction
39+
that hides the problem: a body arriving enveloped is one this door did not
40+
serve, and unwrapping it presents that as a successful promotion.
41+
42+
**Behaviour delta, stated plainly.** Handed an enveloped body, `publishDraft`
43+
used to return the inner object and now returns the body as-is. Graded `patch`
44+
because that input is not one any measured configuration emits: on a conformant
45+
response — which has no `data` member at all — the removed branch was already a
46+
no-op, so `seedApplied`, `version` and `seq` read off both methods exactly as
47+
before. Sibling tolerances in the same file are untouched and still correct:
48+
`listDrafts` reads `data?.data?.drafts` because `GET /meta/_drafts` really is a
49+
dispatcher route, and `publishHealthFromResponse` unwraps because the batch
50+
publish door really is enveloped. The rule is per-route, not per-file.

‎packages/data-objectstack/src/metadata-client.publishAdvisories.test.ts‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -267,10 +267,23 @@ describe('MetadataClient.publishDraft — the same door, so the same report', ()
267267
expect(events[0]!.advisories).toEqual([PURGE_ADVISORY]);
268268
});
269269

270-
it('reads them through the dispatcher `{ success, data }` envelope it already unwraps', async () => {
271-
// This method tolerates an enveloped body and returns the inner object, so
272-
// it must read the advisories from the same place — otherwise the report
273-
// would depend on which of two equivalent server shapes answered.
270+
/**
271+
* REPLACED, not merely re-spelled (objectui#6962). This case used to pin the
272+
* `{ success, data }` unwrapping this method carried and `publish()` did
273+
* not, and it kept passing for the wrong reason: what it proved was that a
274+
* dialect stayed consistent with itself, on a body no server on this route
275+
* emits. The route was measured at the producer — one REST mount answering
276+
* `res.json(protocol.publishMetaItem(...))` verbatim, and no dispatcher
277+
* branch, ledger row or spec declaration putting an envelope on it — so the
278+
* unwrapping is gone and both doors read the top level.
279+
*
280+
* What replaces it asserts the same thing the old case was reaching for —
281+
* "the report does not depend on which shape answered" — in the direction
282+
* that is now true: an enveloped body reports NOTHING, identically at both
283+
* doors. The full shape-agreement pins live in
284+
* `metadata-client.publishEnvelope.test.ts`.
285+
*/
286+
it('reports nothing for an enveloped body, and returns it verbatim', async () => {
274287
const events: MetadataSaveAdvisoryEvent[] = [];
275288
const client = clientWith(
276289
{ success: true, data: { ...CLEAN_BODY, advisories: [PURGE_ADVISORY] } },
@@ -279,10 +292,13 @@ describe('MetadataClient.publishDraft — the same door, so the same report', ()
279292

280293
const result = await client.publishDraft('flow', 'nightly_purge');
281294

282-
expect(events).toHaveLength(1);
283-
expect(events[0]!.advisories).toEqual([PURGE_ADVISORY]);
284-
// and the unwrapping itself is unchanged
285-
expect((result as { seq?: number }).seq).toBe(7);
295+
// `advisories` is declared at the TOP LEVEL of `PublishMetaItemResponse`;
296+
// an enveloped body has none there, and nothing digs for one.
297+
expect(events).toEqual([]);
298+
// The body comes back untouched — no hoisting, so a caller can still see
299+
// it is not the shape this door declares.
300+
expect(result).toEqual({ success: true, data: { ...CLEAN_BODY, advisories: [PURGE_ADVISORY] } });
301+
expect((result as { seq?: number }).seq).toBeUndefined();
286302
});
287303

288304
it('says nothing on a clean by-reference publish', async () => {
Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
/**
2+
* ObjectUI
3+
* Copyright (c) 2024-present ObjectStack Inc.
4+
*
5+
* This source code is licensed under the MIT license found in the
6+
* LICENSE file in the root directory of this source tree.
7+
*/
8+
9+
/**
10+
* `publish` and `publishDraft` hit ONE route and must hold ONE belief about
11+
* its wire shape (objectui#6962).
12+
*
13+
* ## What was measured, because this card forbids inferring it
14+
*
15+
* The card's own triage refused to act on `PublishMetaItemResponseSchema`
16+
* alone — "an inference from the declaration, not a measurement of the
17+
* server". So the producer was read instead, in the framework checkout:
18+
*
19+
* - `POST /api/v1/meta/:type/:name/publish` is mounted in exactly one place,
20+
* `packages/rest/src/rest-server.ts`, and that handler ends
21+
* `res.json(await p.publishMetaItem(publishRequest))` — the protocol's own
22+
* object, verbatim, with no envelope branch on any arm. The ADR-0006
23+
* project-scoped base re-mounts the same handler.
24+
* - The `{ success, data }` envelope has ONE producer, `HttpDispatcher`
25+
* (`runtime/src/http-dispatcher.ts`, `success()` → `{ success, data, meta }`),
26+
* and it does not serve this route. `runtime/src/domains/meta.ts` has no
27+
* publish branch — its three-segment arm matches `/published` on GET only —
28+
* and `runtime/src/route-ledger.ts` carries no row for a publish POST, so a
29+
* dispatcher-fronted host answers this path with `routeNotFound`, never with
30+
* a payload. That holds for the dispatcher-only Hono adapter
31+
* (`adapters/hono`, whose `${prefix}/*` catch-all IS `dispatch()`) as much
32+
* as for a full `rest` + `plugin-hono-server` boot, where the REST mount
33+
* shadows that catch-all.
34+
* - `packages/spec` declares the split explicitly rather than by omission:
35+
* `PublishMetaItemResponseSchema` documents "the FULL body" of this route,
36+
* while its batch sibling `PublishPackageDraftsResponseSchema` documents a
37+
* body answered "inside the dispatcher's `{ success, data }` envelope".
38+
*
39+
* ⇒ The route never envelopes, so the tolerance `publishDraft` carried was a
40+
* dialect with no producer, and Commandment #0.1 says it goes.
41+
*
42+
* ## Why these pins use an envelope-shaped INPUT, and why that is the point
43+
*
44+
* A pin asserting only "publish returns the body" is worthless here: it passes
45+
* on a method that returns the body AND on one that would have unwrapped an
46+
* envelope it never receives. Those two spellings differ on exactly one input,
47+
* so that input is what gets driven. `expect(result).toEqual(ENVELOPED)` goes
48+
* RED the moment either method starts unwrapping again — which is the whole
49+
* caricature this card has to exclude (both unwrap, or the two disagree).
50+
*
51+
* ⚠️ Read the assertions as pinning ONE ANSWER FOR TWO METHODS, not as a
52+
* blessing of the enveloped body. Nothing serves it. If a server ever does,
53+
* that is a producer defect to file upstream — the answer is not a second
54+
* unwrapping site here, and the `version` assertion below says why: unwrapping
55+
* would let a body this door never served read as a successful promotion.
56+
*/
57+
58+
import { describe, it, expect, vi } from 'vitest';
59+
import { PublishMetaItemResponseSchema } from '@objectstack/spec/api';
60+
import { MetadataClient, type MetadataSaveAdvisoryEvent } from './metadata-client';
61+
62+
/** The three keys `PublishMetaItemResponseSchema` states as REQUIRED, plus its receipt. */
63+
const BARE_BODY = {
64+
success: true,
65+
version: 'sha256:0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0',
66+
seq: 7,
67+
message: 'Published draft — type=view, name=cases [seq=7]',
68+
};
69+
70+
/**
71+
* The discriminating input: the dispatcher-shaped envelope nobody serves on
72+
* this route. Deliberately carries the SAME payload as {@link BARE_BODY} one
73+
* level down, so an unwrapping method and a verbatim one return values that
74+
* differ only in the nesting — which is precisely what the pins read.
75+
*/
76+
const ENVELOPED_BODY = { success: true, data: { ...BARE_BODY } };
77+
78+
function response(body: unknown): Response {
79+
return new Response(JSON.stringify(body), {
80+
status: 200,
81+
headers: { 'content-type': 'application/json' },
82+
});
83+
}
84+
85+
function clientWith(body: unknown, onSaveAdvisory?: (ev: MetadataSaveAdvisoryEvent) => void) {
86+
return new MetadataClient({
87+
baseUrl: 'http://test.local',
88+
fetch: vi.fn(async () => response(body)) as unknown as typeof fetch,
89+
...(onSaveAdvisory ? { onSaveAdvisory } : {}),
90+
});
91+
}
92+
93+
/**
94+
* The premise, asserted against the INSTALLED spec rather than quoted from the
95+
* card: the declared body carries its keys at the TOP LEVEL and declares no
96+
* envelope, so `data` is not a member a conformant publish response can have.
97+
*
98+
* The reverse probe is what makes it a reading rather than a restatement: the
99+
* enveloped shape must be REJECTED by the same schema, or "the bare shape
100+
* parses" would prove only that the schema accepts anything.
101+
*/
102+
describe('the declared publish body (objectstack#7294), read off the installed spec', () => {
103+
it('declares `success` / `version` / `seq` at the top level, with no envelope', () => {
104+
const bare = PublishMetaItemResponseSchema.safeParse(BARE_BODY);
105+
expect(bare.success).toBe(true);
106+
expect(bare.success && bare.data.version).toBe(BARE_BODY.version);
107+
// `data` is not a declared member, so an object schema STRIPS it — the
108+
// discriminating reading is that it does not survive the parse.
109+
const withData = PublishMetaItemResponseSchema.safeParse({ ...BARE_BODY, data: { seq: 99 } });
110+
expect(withData.success && Object.prototype.hasOwnProperty.call(withData.data, 'data')).toBe(
111+
false,
112+
);
113+
});
114+
115+
it('refuses the enveloped shape outright — `version` and `seq` are missing from it', () => {
116+
const enveloped = PublishMetaItemResponseSchema.safeParse(ENVELOPED_BODY);
117+
expect(enveloped.success).toBe(false);
118+
});
119+
});
120+
121+
/**
122+
* THE CARD. One route, one spelling — driven on the only input that can tell
123+
* the two spellings apart.
124+
*/
125+
describe('publish and publishDraft answer the same route the same way (#6962)', () => {
126+
it('publishDraft returns an envelope-shaped body VERBATIM — it no longer unwraps', async () => {
127+
const result = await clientWith(ENVELOPED_BODY).publishDraft('view', 'cases');
128+
129+
// The whole assertion: the envelope is still an envelope on the way out.
130+
expect(result).toEqual(ENVELOPED_BODY);
131+
// Spelled out, because `toEqual` on a two-key object is easy to misread:
132+
// the payload stays NESTED and is not hoisted to the top level.
133+
expect((result as { data?: unknown }).data).toEqual(BARE_BODY);
134+
expect((result as { version?: unknown }).version).toBeUndefined();
135+
expect((result as { seq?: unknown }).seq).toBeUndefined();
136+
});
137+
138+
it('publish returns the same envelope-shaped body verbatim, as it always did', async () => {
139+
const result = await clientWith(ENVELOPED_BODY).publish<Record<string, unknown>>('view', 'cases');
140+
141+
expect(result).toEqual(ENVELOPED_BODY);
142+
expect(result.version).toBeUndefined();
143+
});
144+
145+
it('the two methods return DEEP-EQUAL values for one response — the disagreement is gone', async () => {
146+
// The card itself: same route, same bytes, two methods. Compared as
147+
// values rather than asserted twice, so a future edit that changes one
148+
// method's shape cannot leave the other silently behind.
149+
const viaPublish = await clientWith(ENVELOPED_BODY).publish('view', 'cases');
150+
const viaDraft = await clientWith(ENVELOPED_BODY).publishDraft('view', 'cases');
151+
expect(viaDraft).toEqual(viaPublish);
152+
153+
const bareViaPublish = await clientWith(BARE_BODY).publish('view', 'cases');
154+
const bareViaDraft = await clientWith(BARE_BODY).publishDraft('view', 'cases');
155+
expect(bareViaDraft).toEqual(bareViaPublish);
156+
});
157+
158+
/**
159+
* ⚠️ The `undefined === undefined` trap this card is actually about.
160+
*
161+
* `version` reading `undefined` IS the failure mode under investigation, so
162+
* a pin that merely compared it to `undefined` would prove nothing. Both
163+
* legs below therefore assert a CONCRETE token, and the enveloped leg above
164+
* asserts the absence separately — the two together are what separate "the
165+
* OCC token is readable" from "both sides are blank".
166+
*/
167+
it('keeps the ADR-0008 `version` / `seq` readable off BOTH methods on a normal response', async () => {
168+
const viaPublish = await clientWith(BARE_BODY).publish<typeof BARE_BODY>('view', 'cases');
169+
const viaDraft = await clientWith(BARE_BODY).publishDraft('view', 'cases');
170+
171+
expect(viaPublish.version).toBe(BARE_BODY.version);
172+
expect((viaDraft as { version?: string }).version).toBe(BARE_BODY.version);
173+
expect(viaPublish.seq).toBe(7);
174+
expect((viaDraft as { seq?: number }).seq).toBe(7);
175+
});
176+
177+
it('leaves the unenveloped path — the one every server actually serves — untouched', async () => {
178+
// The non-regression axis: the plausible WRONG fix over-tightens and
179+
// breaks the shape existing callers read. `usePublishAllDrafts` reads
180+
// `seedApplied` off `publishDraft`'s return, so the whole body must
181+
// survive, not just the three required keys.
182+
const withSeed = { ...BARE_BODY, seedApplied: { success: false, inserted: 0, updated: 0, error: 'no rows' } };
183+
const result = await clientWith(withSeed).publishDraft('seed', 'demo_rows');
184+
185+
expect(result).toEqual(withSeed);
186+
expect(result.seedApplied).toEqual({ success: false, inserted: 0, updated: 0, error: 'no rows' });
187+
});
188+
});
189+
190+
/**
191+
* The advisory channel follows the same object, on both doors — PR #6961's
192+
* presentation reads whatever each method treats as the response, so it stays
193+
* correct without a second decision (the scope fence this card adopted).
194+
*/
195+
describe('advisory reporting reads the same object both methods return (#6962)', () => {
196+
/**
197+
* FULLY shaped, and that is load-bearing rather than tidy: `readSaveAdvisories`
198+
* requires all six string keys and silently DROPS a finding missing any of
199+
* them. A half-shaped fixture would make the "reports NOTHING" case below
200+
* pass for the wrong reason — an empty sink proving only that the fixture was
201+
* malformed. Measured: with three keys, the positive control below went red
202+
* (`expected [] to have a length of 1`) while the absence case stayed green.
203+
*/
204+
const ADVISORY = {
205+
severity: 'warning' as const,
206+
rule: 'flow/delete-without-filter',
207+
where: 'flow "nightly_purge" · node "purge old rows"',
208+
path: 'flows[0].nodes[2].config.filters',
209+
message: 'this delete_record node sets multi: true with no filter',
210+
hint: 'add a filter, or set multi: false to delete a single record',
211+
};
212+
213+
it('reports top-level advisories through both doors', async () => {
214+
const body = { ...BARE_BODY, advisories: [ADVISORY] };
215+
216+
const viaPublish: MetadataSaveAdvisoryEvent[] = [];
217+
await clientWith(body, (e) => viaPublish.push(e)).publish('flow', 'nightly_purge');
218+
const viaDraft: MetadataSaveAdvisoryEvent[] = [];
219+
await clientWith(body, (e) => viaDraft.push(e)).publishDraft('flow', 'nightly_purge');
220+
221+
expect(viaPublish).toHaveLength(1);
222+
expect(viaDraft).toEqual(viaPublish);
223+
expect(viaDraft[0]!.advisories).toEqual([ADVISORY]);
224+
});
225+
226+
it('reports NOTHING for an enveloped body — through both doors, identically', async () => {
227+
// The honest consequence of the ruling, pinned rather than left implicit:
228+
// advisories are declared at the top level, an enveloped body has none
229+
// there, and neither door goes hunting one level down for them. Pinned as
230+
// an absence so a "helpful" traversal cannot be re-added silently.
231+
const enveloped = { success: true, data: { ...BARE_BODY, advisories: [ADVISORY] } };
232+
233+
const viaPublish: MetadataSaveAdvisoryEvent[] = [];
234+
await clientWith(enveloped, (e) => viaPublish.push(e)).publish('flow', 'nightly_purge');
235+
const viaDraft: MetadataSaveAdvisoryEvent[] = [];
236+
await clientWith(enveloped, (e) => viaDraft.push(e)).publishDraft('flow', 'nightly_purge');
237+
238+
expect(viaPublish).toEqual([]);
239+
expect(viaDraft).toEqual([]);
240+
});
241+
});

‎packages/data-objectstack/src/metadata-client.test.ts‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -218,8 +218,12 @@ describe('MetadataClient', () => {
218218
await expect(c.publishDraft('view', 'x')).rejects.toBeTruthy();
219219
});
220220

221-
it('publishDraft returns the result (incl. seedApplied) and unwraps the {data} envelope', async () => {
222-
// Flat shape (rest-server passes protocol result through).
221+
it('publishDraft returns the result (incl. seedApplied) verbatim — no {data} unwrapping', async () => {
222+
// The shape the route actually serves, and the ONLY one it serves: the
223+
// single REST mount answers `res.json(protocol.publishMetaItem(...))`
224+
// straight through, and the `{ success, data }` envelope's one producer
225+
// (the runtime dispatcher) does not serve this path at all — no publish
226+
// branch in its `/meta` domain, no row in its route ledger (objectui#6962).
223227
const flat = new MetadataClient({
224228
baseUrl: '',
225229
fetch: mockFetch(async () =>
@@ -228,14 +232,18 @@ describe('MetadataClient', () => {
228232
const r1 = await flat.publishDraft('seed', 'job_sample');
229233
expect(r1.seedApplied).toEqual({ success: false, error: 'no readable seed bodies' });
230234

231-
// Dispatcher `{ success, data: {...} }` envelope.
235+
// The unwrapping this method used to carry is GONE, so the enveloped body
236+
// comes back as it arrived. This half used to assert the opposite; it was
237+
// pinning a dialect with no producer, against `publish()` — the same route,
238+
// a couple of hundred lines down — which never unwrapped at all.
232239
const enveloped = new MetadataClient({
233240
baseUrl: '',
234241
fetch: mockFetch(async () =>
235242
jsonResponse({ success: true, data: { success: true, seedApplied: { success: true, inserted: 6, updated: 0 } } })),
236243
});
237244
const r2 = await enveloped.publishDraft('seed', 'candidate_sample');
238-
expect(r2.seedApplied).toEqual({ success: true, inserted: 6, updated: 0 });
245+
expect(r2.seedApplied).toBeUndefined();
246+
expect(r2).toEqual({ success: true, data: { success: true, seedApplied: { success: true, inserted: 6, updated: 0 } } });
239247
});
240248
});
241249

0 commit comments

Comments
 (0)