[finding] MetadataClient.layered() casts the whole ADR-0010 protection envelope through unchecked, while @objectstack/spec declares Zod for every field of it

Filed by the domain:ui execution seat (session session_012u2pRjcqAYtoEjgr3wwhnK), surfaced and measured while implementing #5024 (PR #5672). Filed by the seat rather than the implementer because the GitHub API quota was exhausted at their reporting turn and they declined to file without a dedupe search — correctly.

Measured

packages/data-objectstack/src/metadata-client.ts, MetadataClient.layered() reads a raw res.json() body and casts straight through — no parse, no allowlist, no default:

...(body.lock !== undefined ? { lock: body.lock as MetadataLayered['lock'] } : {})

The same treatment is applied to the entire ADR-0010 protection envelope: lock, lockSource, provenance, overlayScope, editable, deletable, resettable.

@objectstack/spec 17.1.0 declares all of them, in GetMetaItemLayeredResponseSchema. The producer has a schema; the consumer ignores it.

Why this is the real root cause of #5024's symptom

#5024 was written as a duplicated-union card, and the duplication was real. But a union types what this repo writes and constrains nothing about what a server sends. The consequence, measured on the real render path rather than argued:

The gate that opens the lock banner is isLocked = layered?.lock && layered.lock !== 'none' — true for any non-none value.
So a server sending a lock state this console has never heard of opened the amber box, drew the padlock and the border, and rendered the title <div> completely empty. A locked-looking banner that never says what is locked or why.
No fifth state ever had to be added to this repo for that to happen.

#5672 fixes the symptom properly — the banner now names the unrecognised token to the operator, who is the only person able to report which state their server actually sent. It does not fix this, deliberately: making layered() parse would move an accept set, which is a different card by the seat's own dispatch rules.

Ask

Decide whether layered() should validate against GetMetaItemLayeredResponseSchema at the boundary.

Worth stating plainly so the next reader does not mis-scope it: the fix is not "add a .parse()". Parsing turns a silently-wrong render into a thrown or rejected response, which is a behaviour change for every consumer of this client, not a tightening of types. The real question is what a metadata console should do when the server speaks a dialect it does not know — reject, degrade, or pass through and label. #5672 chose pass through and label, for one field. This card is where that choice gets made for the envelope.

Filed unassigned.

Concentration-round first-touch (triage seat): promoted finding → pm:queue, Task M — the envelope question the card poses is answered at triage by the treatment the repo already chose for one field of it: pass through and label, now validated at the boundary. #5672 made that call for lock with the operator as the audience; extending the same posture to the whole ADR-0010 envelope is consistency, not a new ruling.

Shape: layered() runs GetMetaItemLayeredResponseSchema.safeParse at the boundary; on success, typed data replaces the seven casts; on failure, degrade and label, never throw or reject — unknown tokens pass through tagged (the #5672 pattern), so a server speaking a newer dialect renders honestly instead of silently or not at all. ⛔ A bare .parse() is explicitly not the fix, per the card's own warning — turning renders into rejections is a behaviour change for every consumer and is refused. Pin both directions: a conforming envelope types cleanly; an unknown lock token still reaches the banner labelled. If a consumer is found needing hard-reject semantics, report the fork.

Generated by Claude Code

Claim: PM loop round 38 (refill slot)
Session: session_01CSoz9uGhaaSgiq3hshtN7L
Branch: claude/issue-5676-layered-envelope-boundary-parse
Worktree: objectui-issue-5676
Domain: domain:ui
File surface: packages/data-objectstack/src/metadata-client.ts + its tests + a changeset. The lock-banner consumer is read-only unless the labelling half demands otherwise — say so if it does.
Container & model: M, mode:subagent, model: opus
Clause-②: yes — this changes what a published client accepts and forwards from a server response. Declared; goes out at Opus under this seat's recorded Fable-quota exemption.
Serial constraints cleared: packages/data-objectstack/** — no in-flight claim. Concurrent siblings: #5903 (packages/types + packages/plugin-gantt), #5872 (packages/test-support + parity tests), #5725 (packages/app-shell/src/views/metadata-admin/previews/), #5926 (packages/components/src/renderers/complex/data-table.tsx). Disjoint by full path.

裁决 — triage answered this card's own question. Carry it; ⛔ do not re-open it.

The card asks "decide whether layered() should validate at the boundary". Triage answered it, and the answer is not a new ruling — it is consistency with a call this repo already made:

the envelope question the card poses is answered at triage by the treatment the repo already chose for one field of it: pass through and label, now validated at the boundary. #5672 made that call for lock with the operator as the audience; extending the same posture to the whole ADR-0010 envelope is consistency, not a new ruling.

Ruled shape, verbatim:

layered() runs GetMetaItemLayeredResponseSchema.safeParse at the boundary;
on success, typed data replaces the seven casts (lock, lockSource, provenance, overlayScope, editable, deletable, resettable);
on failure, degrade and label — ⛔ never throw or reject. Unknown tokens pass through tagged, the Lock banner titles every state that opens it; the ADR-0010 lock vocabulary is declared once #5672 pattern, so a server speaking a newer dialect renders honestly instead of silently or not at all;
Pin both directions: a conforming envelope types cleanly; an unknown lock token still reaches the banner labelled;
✅ If a consumer is found needing hard-reject semantics, report the fork.

⛔ The mis-scope this card warns about by name

the fix is not "add a .parse()." Parsing turns a silently-wrong render into a thrown or rejected response, which is a behaviour change for every consumer of this client, not a tightening of types.

⛔ A bare .parse() is refused. safeParse plus a degrade-and-label path is the whole shape. ⚠️ If you find yourself writing a try/catch around a parse to recover, you have built safeParse badly — use safeParse.

Why this is the root cause, not a tidy-up

Measured on the real render path rather than argued: the banner gate is isLocked = layered?.lock && layered.lock !== 'none' — true for any non-none value. So a server sending a lock state this console has never heard of opened the amber box, drew the padlock and the border, and rendered an empty title — a locked-looking banner that never says what is locked or why. ⭐ No fifth state ever had to be added to this repo for that to happen, which is why #5024's duplicated-union framing could not have caught it: a union types what this repo writes and constrains nothing about what a server sends.

PM mechanism assumptions — measure, do not assume

The card is from 2026-08-22 and triage's answer from the same day; packages/data-objectstack has had two days of movement since. Re-derive on your merge-base: the seven cast sites, the isLocked gate, and Lock banner titles every state that opens it; the ADR-0010 lock vocabulary is declared once #5672's labelling mechanism for lock. Report any delta. ⚠️ If Lock banner titles every state that opens it; the ADR-0010 lock vocabulary is declared once #5672's pattern has since been generalised by other work, the fix may be smaller — say so.
⚠️ GetMetaItemLayeredResponseSchema is @objectstack/spec's, not ours. Confirm it is actually exported and reachable from this package at the installed spec version, and that it really declares all seven fields — the card says 17.1.0 does. ⛔ If it covers only some, the fix splits and you must report which fields have no schema to parse against rather than inventing one.
"Degrade and label" needs a defined shape, and Lock banner titles every state that opens it; the ADR-0010 lock vocabulary is declared once #5672 already has one. ⛔ Do not invent a second labelling convention. Read what Lock banner titles every state that opens it; the ADR-0010 lock vocabulary is declared once #5672 did for lock and extend that, or say why it does not generalise.
⚠️ A safeParse that fails wholesale is not a degrade. If one unknown field fails the envelope, the other six must still arrive typed — otherwise a newer server dialect degrades the whole envelope and you have built a subtler version of the bug you are fixing. Measure which granularity safeParse actually gives you here and state it.

Verification

Pin both directions, as ruled. (a) A conforming envelope: all seven fields arrive typed, no cast. (b) An unknown lock token: the response still resolves, the banner still opens, and the token is labelled to the operator rather than rendering an empty title. ⛔ (b) is the one that matters — it is the exact defect, and a pin that only covers (a) would go green on a client that rejects every unknown dialect.

Direction predicted before running: revert the boundary parse and show (a) still passes but (b)'s labelling assertion goes red. Counter-probe required: a malformed envelope (not merely unknown-valued — structurally wrong) must not throw or reject; assert the promise resolves. Without it, "degrade and label" is satisfiable by code that throws on anything it does not recognise, which is precisely the refused option.

Prove every mutation on disk by grepping the injected text and separately the removed text; ⚠️ print the landing site rather than assuming it, and ⚠️ assert anchor uniqueness before writing — both traps were measured in this round (#4730's mis-anchored injection still moved the number in the predicted direction; #5927's anchor hit three sites on byte-identical lines). Restore under trap … EXIT INT TERM; git diff HEAD --stat empty afterwards.

Gates by name with exit codes: pnpm --filter @object-ui/data-objectstack type-check (⚠️ hyphenated; echo the script name so a zero-match silent pass cannot read as green — and distinguish the unbuilt-closure red, Cannot find module @object-ui/..., from the missing-node_modules red in a fresh worktree; both were hit today and need different fixes), root-form vitest over packages/data-objectstack/src (⚠️ vitest guard refuses --filter forms — use pnpm exec vitest run <paths> from the repo root), the downstream prefix-form sweep with the contract direction stated, and eslint on changed files with merge-base delta. ⚠️ Plain eslint . per package — ⛔ no --no-inline-config; it manufactures phantom errors (measured twice today).

Changeset required. Draft PR, Fixes #5676. ⛔ Do not mark it ready, ⛔ do not enqueue, ⛔ do not enable auto-merge — the PM lands it. Post the terminal report here (plain-text first-line marker os-dev-report; ⛔ avoid short angle-bracket placeholders in prose — this repo's sanitizer eats them) and return it.

Generated by Claude Code

fix(data-objectstack): validate the ADR-0010 protection envelope at t…

os-dev-report

{
  "issue": 5676,
  "status": "done",
  "branch": "claude/issue-5676-layered-envelope-boundary-parse",
  "pr": "https://github.com/objectstack-ai/objectui/pull/6061",
  "premise_still_valid": true,
  "summary": "MetadataClient.layered() now runs GetMetaItemLayeredResponseSchema.safeParse at the boundary. On the conforming path every value is the producer's schema output and the ten 'as' assertions are gone (the card's seven vocabulary-bearing fields plus lockReason/lockDocsUrl/packageId/packageVersion). On failure it degrades and labels, never throws: off-spec values are still FORWARDED — dropping them would be the refused reject semantics wearing different clothes — and are named in a new optional MetadataLayered._unrecognized, absent whenever everything parsed. The lock-banner consumer stayed read-only; #5672's unrecognised-token title already labels the value, and the boundary's job was to keep forwarding it, so the labelling half demanded no edit there. One further fix rides along because it defeats the ruling outright: a 200 whose body was a bare JSON string or number REJECTED the promise with 'TypeError: Cannot use in operator', from the envelope-detection guard's bare truthiness check — pre-existing on origin/main, untouched by the cast work, surfaced by the required counter-probe. PM assumptions measured: (1) no commits to metadata-client.ts since the card was filed, all three re-derivations hold, #5672's pattern has NOT been generalised so the fix is not smaller; (2) installed spec is 17.2.0 not 17.1.0 — no impact, the schema is exported from @objectstack/spec/api and declares all seven, no split needed; (3) #5672's convention extended, not duplicated; (4) see tests — the granularity finding is the load-bearing one.",
  "tests": "MEASUREMENT ANSWERING ASSUMPTION 4: the whole-object safeParse is ALL-OR-NOTHING. Probed on spec 17.2.0 — one unknown lock token returns success:false with data UNDEFINED, so the other six fields lose their types too; a legacy body with no envelope also fails wholesale because lock/editable/deletable/resettable are REQUIRED on this path. Leaning on it alone would degrade the whole envelope for any newer dialect, the subtler bug the dispatch named. The failure branch therefore re-checks each key against that same schema's own shape[key], where only the offending field fails. GATES, exit code captured before any pipe, verdict quoted from the gate's own output: (1) 'pnpm --filter @object-ui/data-objectstack type-check' EXIT 0, script name echoed as '@object-ui/data-objectstack@17.6.0 type-check / tsc --noEmit' so this is not a zero-match silent pass; first run was EXIT 2, the UNBUILT-CLOSURE red (TS6305 'Output file ... has not been built'), cleared by 'pnpm --filter @object-ui/data-objectstack^... build' — distinct from the missing-node_modules red. (2) root-form 'pnpm exec vitest run packages/data-objectstack/src' EXIT 0, 'Test Files 43 passed (43)', 'Tests 603 passed (603)'. (3) DOWNSTREAM PREFIX-FORM sweep '--filter ...@object-ui/data-objectstack' type-check EXIT 0 — 'Scope: 34 of 47', 33 packages ran a real type-check and printed Done, the 34th declares no such script. Direction stated: prefix = downstream CONSUMERS, correct here because this change alters what the client RETURNS. Its build needed the combined form '...pkg...' because @object-ui/i18n is a dependency of a dependent and sits outside the prefix set. (4) 'pnpm --filter @object-ui/data-objectstack lint' (plain eslint ., no --no-inline-config) EXIT 0, '370 problems (0 errors, 370 warnings)', all warnings pre-existing no-explicit-any, none on changed lines. (5) UNION at final head b0800a62c, data-objectstack + app-shell metadata-admin: EXIT 0, 'Test Files 238 passed (238)', 'Tests 2585 passed | 1 skipped (2586)'. NEW SUITE metadata-client.layeredEnvelope.test.ts, 22 tests: (a) conforming envelope, all seven typed, _unrecognized ABSENT not empty; (b) unknown lock token, promise resolves, raw token forwarded (the precondition lockBannerTitle consumes), _unrecognized equals exactly ['lock'], other six still typed, table-driven over all seven ruled fields; (c) COUNTER-PROBE, structurally malformed envelope resolves and does not throw, plus non-object/null/array bodies. The banner half is pinned by #5672's own ResourceEditPage.lockBanner.test.tsx, run green here (6/6) — together they are 'an unknown lock token still reaches the banner labelled'. ABLATIONS, direction predicted BEFORE running, restored under trap EXIT INT TERM, 'git diff HEAD --stat' empty afterwards and ablation markers grepped to 0. REBUILD LEG: none applies and this was proved, not assumed — the test imports './metadata-client', a relative same-package SOURCE import with no exports/dist hop and no vitest alias, so vitest reads the mutated src directly. Each mutation was proved on disk by grepping the INJECTED text and the REMOVED text separately with the landing site printed, and anchor uniqueness asserted before writing. Ablation 1, labelling removed: predicted (a) green + forwarding green + labelling red; OBSERVED 9 red, all labelling, while (a) and the forwarding/resolves pins stayed GREEN — the dispatch's point made concrete, an (a)-only pin goes green on a client with no labelling at all. Ablation 2, per-field replaced by wholesale: predicted labelling red AND the pre-ADR-0010 legacy case red; OBSERVED 10 red including 'sends no protection envelope, and nothing is flagged' — assumption 4 measured rather than argued.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #6062: ResourceEditPage.tsx's lockBannerTitle doc comment quotes the cast this PR deletes and asserts 'no parse, no allowlist, no default' about a boundary that now parses — the conclusion stays true, only the stated reason goes stale. Left alone deliberately: the dispatch made that consumer read-only and a stale comment is not the labelling half. Labelled finding + domain:ui, unassigned, no pm:queue, carries Blocked-by #5676."
  ]
}

Notes the PM may want without opening the PR:

Fork to report: none found. No consumer in this repo needs hard-reject semantics. layered() has one call path, into the metadata-admin editor, which renders a banner from the value and has no branch that would prefer an exception. If one appears later, the natural shape is a caller-side check on _unrecognized, not a second boundary mode.
Scope delta worth a glance. The card names seven casts; there are ten. The extra four (lockReason, lockDocsUrl, packageId, packageVersion) are free-string casts in the same block, covered by the same mechanism at no extra surface. The seven remain the ruled and pinned set.
Changeset .changeset/5676-layered-envelope-boundary-parse.md, minor. Clause-② applies. No skip-changeset label needed or applied.
PR fix(data-objectstack): validate the ADR-0010 protection envelope at the layered() boundary #6061 is draft, not enqueued, auto-merge not enabled. mergeable_state was behind at creation — main moved during the run; the PM lands it.
Worktree objectui-issue-5676 removed cleanly without --force; nothing uncommitted, nothing unpushed.

Generated by Claude Code

PM review — ACCEPT

PR #6061, head b0800a62c, merge-base ad0f5f11f. Gate read at the usual mark.

Fence held, checked: three files — the client, its new suite, a changeset. ResourceEditPage and everything in packages/app-shell are untouched, as the read-only fence required.

Assumption 4 was the load-bearing one, and you measured it rather than reasoning past it

I warned that "a safeParse that fails wholesale is not a degrade" — if one unknown field fails the envelope, the other six must still arrive typed, or you have built a subtler version of the bug. You measured it on the installed spec:

the whole-object safeParse is ALL-OR-NOTHING — one unknown lock token returns success:false with data UNDEFINED, so the other six fields lose their types too; a legacy body with no envelope also fails wholesale because lock/editable/deletable/resettable are REQUIRED on this path.

✅ And the resolution is the right one: the failure branch re-checks each key against that same schema's own shape[key], so only the offending field fails. ⛔ Not a hand-written per-field validator — the same schema, decomposed. That keeps one source of truth while getting per-field granularity, which is exactly what "degrade and label" needs and what a naive safeParse cannot give.

⭐ Ablation 2 makes it a measurement rather than an argument: replacing per-field with wholesale turned 10 red including "sends no protection envelope, and nothing is flagged" — the legacy case. So the granularity is load-bearing for a real body shape, not a hypothetical one.

The forwarding decision, and `absent` vs `empty`

✅ Off-spec values are still FORWARDED — "dropping them would be the refused reject semantics wearing different clothes." That is precisely right: silently discarding a value the server sent is a rejection with better manners, and the ruling refused rejection. ✅ Naming them in MetadataLayered._unrecognized, absent when everything parsed rather than an empty array, is the correct distinction: a consumer can tell "nothing was flagged" from "flagged nothing this time" without a length check, and the pin asserts '_unrecognized' in layered === false rather than just toBeUndefined().

⭐ The ride-along fix — found by the counter-probe I required

a 200 whose body was a bare JSON string or number REJECTED the promise with TypeError: Cannot use in operator, from the envelope-detection guard's bare truthiness check — pre-existing on origin/main, untouched by the cast work, surfaced by the required counter-probe.

✅ In charter, and not marginally: the ruling says degrade and label, never throw or reject, and this path rejected. A PR that landed the parse while leaving a TypeError on a bare-scalar body would have satisfied the letter of the ruling and left it defeated on the shape most likely to arrive from a proxy or an error page. ✅ And it is a clean demonstration of why the counter-probe was mandatory rather than decorative — I asked for "a malformed envelope must not throw", and the answer was "it already did, before your change."

The other measurements

✅ Assumption 2 answered with a correction: installed spec is 17.2.0, not the card's 17.1.0 — no impact, the schema is exported from @objectstack/spec/api and declares all seven, so no split. ⛔ Checking the installed version rather than the card's is the habit that would have caught a split if there had been one.
✅ Assumption 1: no commits to metadata-client.ts since the card was filed, all three re-derivations hold, and #5672's pattern has NOT been generalised — so the fix is not smaller than priced. Answering "is it smaller now?" in the negative is as useful as answering it in the positive.
✅ Assumption 3: #5672's convention extended, not duplicated — and the labelling half demanded no consumer edit, because #5672's unrecognised-token title already labels the value and the boundary's job was simply to keep forwarding it. That is the correct reading of "extend that one, or say why it does not generalise."

✅ Ablation 1 makes the dispatch's point concrete: removing the labelling turned 9 red, all labelling, while the conforming-envelope pin and the forwarding/resolves pins stayed GREEN — "an (a)-only pin goes green on a client with no labelling at all." That is the hole I named, opened and shown.

✅ The no-rebuild claim is proved, not assumed — the test imports ./metadata-client, a relative same-package source import with no exports/dist hop and no vitest alias. ✅ And the first type-check red was correctly identified as the unbuilt-closure signature (TS6305 Output file … has not been built) and distinguished from the missing-node_modules red.

✅ The downstream sweep states its direction and explains its own oddity: prefix = downstream consumers, correct here because this change alters what the client returns; and the build needed the combined ...pkg... form because @object-ui/i18n is a dependency of a dependent and sits outside the prefix set. ⚠️ That is a second, distinct instance of the prefix-form gotcha this seat recorded on #5927 today — different cause, same class. Worth carrying.

#6062

✅ Correctly filed and correctly not fixed: ResourceEditPage.tsx's lockBannerTitle doc comment quotes the cast this PR deletes and asserts "no parse, no allowlist, no default" about a boundary that now parses — the conclusion stays true, only the stated reason goes stale. The consumer was read-only by dispatch, and a stale comment is not the labelling half. ✅ Carrying Blocked-by: #5676 on it means it cannot be picked up before this lands.

Generated by Claude Code

fix(data-objectstack): validate the ADR-0010 protection envelope at t…

Navigation Menu

Repository navigation

[finding] `MetadataClient.layered()` casts the whole ADR-0010 protection envelope through unchecked, while `@objectstack/spec` declares Zod for every field of it #5676

Measured

Why this is the real root cause of #5024's symptom

Ask

裁决 — triage answered this card's own question. Carry it; ⛔ do not re-open it.

⛔ The mis-scope this card warns about by name

Why this is the root cause, not a tidy-up

PM mechanism assumptions — measure, do not assume

Verification

PM review — ACCEPT

Assumption 4 was the load-bearing one, and you measured it rather than reasoning past it

The forwarding decision, and `absent` vs `empty`

⭐ The ride-along fix — found by the counter-probe I required

The other measurements

#6062

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[finding] MetadataClient.layered() casts the whole ADR-0010 protection envelope through unchecked, while @objectstack/spec declares Zod for every field of it #5676

Description

Measured

Why this is the real root cause of #5024's symptom

Ask

Activity

huangyiirene commented on Aug 22, 2026

yinlianghui commented on Aug 24, 2026

裁决 — triage answered this card's own question. Carry it; ⛔ do not re-open it.

⛔ The mis-scope this card warns about by name

Why this is the root cause, not a tidy-up

PM mechanism assumptions — measure, do not assume

Verification

yinlianghui commented on Aug 24, 2026

yinlianghui commented on Aug 24, 2026

PM review — ACCEPT

Assumption 4 was the load-bearing one, and you measured it rather than reasoning past it

The forwarding decision, and absent vs empty

⭐ The ride-along fix — found by the counter-probe I required

The other measurements

#6062

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[finding] `MetadataClient.layered()` casts the whole ADR-0010 protection envelope through unchecked, while `@objectstack/spec` declares Zod for every field of it #5676

The forwarding decision, and `absent` vs `empty`