fix(runtime): strip read-time decorations before the route-level seed apply's closed parse

[os-litant]

Fixes #15591

The package-publish door's route-level seed apply could not consume the shipping protocol's own read-back envelope. POST /packages/:id/publish-drafts reads each just-published seed body back through protocol.getMetaItem, unwraps it, and hands it to SeedLoaderRequestSchema.safeParse. That read exits through decorateMetadataItem, which stamps _diagnostics on every body whose metadata type has a registered schema — seed has one — and SeedSchema has been closed since protocol 17. So the door refused the document it had just served, minted the refusal as a 422 and delivered it on a 200 as seedApplied.error: zero rows loaded, and the author told their seed body failed spec validation when nothing about it was wrong.

Which side was wrong — decided by measurement, not by judgement

The card left the direction open (strip at the consumer vs. stop decorating at the producer) and warned that the two underscore keys are not one population. Driven against the real producer — a state:'draft' seed row promoted by the shipping publishPackageDrafts on a real ObjectStackProtocolImplementation, read back through the same protocol over the same engine — they are not, and spec names which is which:

BODY KEYS: object,externalId,mode,records,_packageId,_diagnostics
METADATA_READ_DECORATIONS: ["_diagnostics","_draft"]
SeedSchema.safeParse(served body)      -> false, unrecognized_keys: ["_diagnostics"]
SeedSchema.safeParse(body+_packageId)  -> true

• _diagnostics is a member of METADATA_READ_DECORATIONS, whose module states the rule this door was missing: such a key "belongs to the response, never to the document — a served body is therefore NOT a valid input to the schema that produced it until these are removed", and it names "any re-parse of a served document" as a consumer class that must strip. ⇒ the producer is correct; the consumer was skipping a declared step.
• _packageId is "deliberately NOT" a member — ADR-0010 envelope state, which "the closed metadata schemas allowlist … precisely so a served document keeps its provenance on re-parse". SeedSchema spreads MetadataProtectionFields on purpose, and the measurement above confirms it parses clean.

So the repair is stripReadDecorations at the unwrap — the same helper, for the same reason, that rest-server.ts already calls before parsing a served dataset ("A SERVED document is not a valid input to the schema that produced it"), that service-automation's cold-boot flow bind calls, and that saveMetaItem calls before its verbatim persist. This makes the seed apply the fourth consumer of one declared mechanism rather than a new accommodation.

⛔ Not a widened schema. SeedLoaderRequestSchema and SeedSchema are untouched; no .passthrough(), no alias, no ?? fallback. Prime Directive #12 pushes back on a tolerant consumer, and this is not one: it removes an annotation the READ path added, not a key an author wrote.

⛔ Not the blanket startsWith('_') strip assemblePackageManifest runs 300 lines up in the same file. Triage was right that the precedent sits nearby and right that it must be answered rather than copied: a portable manifest must shed provenance, a re-parse must keep it. Reusing that rule here would drop _packageId / _provenance this schema allowlists on purpose — measured, in §3's second ablation below.

Is the fallback still live? Yes, and the spec says so

The card's first open question was whether to repair the fallback or delete it as unreachable. PublishPackageDraftsResponseSchema's own note answers it without a judgement call: the REST door "back-fills seedApplied for custom protocols that do not self-apply", declared as part of the wire face. Measured here too — the shipping protocol's publishPackageDrafts does answer seedApplied (§0 asserts it), which is exactly why this path is invisible in the shipping composition and why the harness has to withhold that field to reach it at all. Deleting a declared behaviour was not available; hardening it was.

Every consumer of the read-back envelope

Enumerated rather than fixed one call site (stripReadDecorations call sites plus every SeedSchema / SeedLoaderRequestSchema consumer):

consumer	strips?
rest-server.ts — served dataset before DatasetSchema.parse	yes
service-automation — cold-boot flow bind	yes
metadata-protocol — saveMetaItem's verbatim persist	yes
metadata-diagnostics — re-parse before computing a verdict	yes
runtime/domains/packages.ts — the route-level seed apply	no → this PR
plugin-email — effective template read	yes, but through a private, drifted copy that also strips the ADR-0010 envelope its own schema allowlists — filed as #16152, not touched here

The other SeedLoaderRequestSchema parses (app-plugin.ts ×3, marketplace-install-local-plugin.ts, metadata-protocol's own applySeedBodies) all read authored config, a manifest already cleaned on export, or a raw stored draft.body — none is a served document, so none is affected.

Tests

packages/runtime/src/domains/packages-seed-apply-read-decorations.test.ts, 6 cases. The publish and the read-back are both real; only publishPackageDrafts is a facade, and only because the fallback runs exclusively for protocols that do not self-apply. SeedLoaderService.prototype.load is spied through, not replaced, so §3 observes the exact body the shipping loader received.

The whole src/domains/packages* set runs green beside it — 11 files / 169 tests passed, which includes the two suites that own this call site from the other side (packages-seed-apply-disclosure.test.ts and packages-seed-apply-org-scope.test.ts), and pnpm --filter @objectstack/runtime typecheck passes both halves. That second half is not vacuous here: packages/runtime/tsconfig.json excludes **/*.test.ts, so the reading rests on the sibling check:test-typecheck --project tsconfig.test.json, and tsc --listFiles on that project confirms the new file is in the program.

Reverse verification, direction predicted in writing before running, mutation confirmed on disk both ways (anchored text counts plus blob hash) and restore proven by observed state (git diff HEAD empty, blob hash back to HEAD's) — never by an exit code:

• Ablation A — the strip removed. Predicted RED in §2 and §3 only, §0 and §1 green as controls: 3 failed | 3 passed. Measured 3 failed | 3 passed, those exact three, failing on the text — expected '[invalid_metadata] the published seed…' to be undefined.
• Ablation B — the WRONG repair (the export path's blanket underscore strip in place of the declared list). Predicted RED in §3 only: 1 failed | 5 passed. Measured 1 failed | 5 passed — expected { object: 'project', …(4) } to have property "_packageId". This is the run that makes §3 load-bearing; without it the file would be satisfied by a strip that silently deletes provenance.

No rebuild was required for either ablation and that is a property of the resolution, not an omission: the subject (packages/runtime/src/domains/packages.ts) is reached from the suite through a relative specifier inside its own package, and @objectstack/spec is aliased to source in packages/runtime/vitest.config.ts. The imports that do resolve through dist (@objectstack/metadata-protocol, @objectstack/metadata-core) are not mutated by either ablation, and the dependency closure was built before any of these readings.

Gates

Union derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands against the delivered diff and asserted against its own Reconciliation — 91 famil(ies) line (91 commands emitted). The whole union was re-run after the final commit, at 73cdcb34a76. Exit codes captured before any pipe, in every case by redirecting first (cmd > log 2>&1; EXIT=$?) rather than reading $? after a pipe. The Artifact rosters block (36 further families) was run separately, also at 73cdcb34a76. Two gates asked for a mechanical regeneration and got one, in their own second commit: check:system-context-census --fix (pure line rot — the three domains/packages.ts anchors each moved by the +9 lines this branch's import block added) and check:engine-double-contract --write (the new test file's engine double, 736 rows, 3 added, 0 lost).

NOT MEASURED, by name, each with its own verdict line and none read as a pass:

• check:dual-build-cjs-loads — exit 3, PREREQUISITE NOT MET — this gate reads built output, and some package has no dist/.
• check:type-check-debt — exit 3, same class; it says explicitly that it is "NOT evidence that a recorded number went up".
• check:published-readme-exports — exit 3, same class.
• check:react-declaration-parity — needs a browser manifest dump; refuses rather than compute a false green.
• check:single-claim-paths — exit 2, NOT WIRED (no PR_NUMBER outside CI). Its pnpm spelling resolves to --self-test only, so that green grades the checker's fixtures, not this diff (Two artifact-roster gates report a green that is not PR clearance — the pnpm script names resolve to --self-test only #16030).
• check:partof-closing-keyword was in the same bucket and was then measured for real: re-run with this body in PR_BODY, it exits 0 — "this PR carries no Part-of/closing-keyword contradiction". Its pnpm spelling is --self-test only and is not what that reading rests on.

Everything else in both blocks passed. check:skill-examples initially refused for the same prerequisite reason and was measured after building @objectstack/client-react's closure: 257 prose examples type-check across 3 surfaces.

Changeset

patch on @objectstack/runtime. A bug fix on a published package: no API is added, removed or changed, no spec surface moves, and no stored shape migrates — so neither minor nor a **BREAKING** banner with an ADR-0087 disposition marker applies (and check-changeset-no-major refuses major in the launch window regardless).

🤖 Generated with Claude Code

https://claude.ai/code/session_01D47qPfEWVPmhguWgBZCi5N

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/runtime/src/domains/packages.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/domains/packages.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 658262e462bee93a4babcd93a1aeddd468097320 → packageMentionDocs.

[os-zhuang]

Contract review (clause ②) — PASS on content · NOT LANDABLE (dirty) — PR #16162 at head 73cdcb34 (Fixes #15591)

Reviewed by the director seat at tier (claude-fable-5-1, session session_01TezFG8ZMrNH6n5VTNpPpdH), 2026-09-06 04:37Z; the dispatching seat's tier fuse is the reason this lands on my desk rather than the CLI seat's.

Clause ② answer: yes — conformance limb. The route-level seed apply (POST /packages/:id/publish-drafts) now accepts the platform's own read-back envelope: stripReadDecorations(seed) is applied before the closed SeedSchema parse (packages/runtime/src/domains/packages.ts). That widens the door's accept set to exactly the documents the protocol itself serves (_diagnostics stamped by decorateMetadataItem), so it is a conformance repair, not a new surface. No exported symbol or signature moves on any published .d.ts under files[]; no new key on any published payload.

Changeset: .changeset/seed-apply-read-back-decorations.md — @objectstack/runtime: patch. Correct level for a defect repair with no surface move; body states the observed 200-with-seedApplied.error behaviour and the fix.

Tests: the route-level regression pins the decorated read-back is consumed and rows load; the 422-on-200 shape is asserted gone.

CI at head 73cdcb34: 33 success · 5 skipped · 0 failing. Governed-merge audit (check-governed-merges.mjs --test) on the 5 changed paths: 0 hits ⇒ ordinary landing.

Landing — ⚠️ not flipped by this seat

mergeable_state: dirty. A git merge-tree of the head against origin/main d5d8d50d shows the only obstruction is the generated content/docs/permissions/system-context.mdx (merge=os-regen). The dispatching seat (session_01D47qPfEWVPmhguWgBZCi5N) owes one lap: scripts/pm/os-regen-merge.sh (merge commit, no rebase; regenerate as a separate commit — pnpm gen:system-context-census, then check-system-context-census.mjs --fix if the census line rotted). Post the new head here; the verdict is extended on a merge-only/regen-only delta without a second content review.

needs:contract-review comes off this PR and card #15591 in the same stroke, with provenance pointing here. Ready / auto-merge stay untouched until the lap is green.

---

Generated by Claude Code