fix(metadata-protocol): a packaged item's save answers the package door before the checks that judge its body, on every kernel topology

[objectstack-fleet]

Fixes #22220
Clause-②: no

What changes

saveMetaItem's package door (refusePackagedBaseOverride) is now asked on every kernel topology, at the position it already had on an environment kernel: after the code-only and organization-scope refusals, before the item lock and before every check that reads the body or the store. It used to sit behind environmentId !== undefined. A host-config kernel (the CLI's assembler, the showcase's boot shape, OS_MODE=off) met the same predicate only at SysMetadataRepository.assertAllowed, the first statement of repo.put, which is the method's last act. So on that kernel every refusal in between answered first.

• packages/metadata-protocol/src/protocol.ts: the environmentId wrapper around the door is removed. The _lock gate's guard packagedBaseRefusal(...) === null (its hand-written deferral to the door on host-config) always answered "no refusal" once the door runs first on every kernel, so it is removed. The invariant comment on that gate is extended, and the door's call site records why no acceptance set moves. Two TSDoc paragraphs that said the door is environment-only are corrected.
• New pins: packages/metadata-protocol/src/protocol.package-door-before-gates.test.ts (one table over both kernel topologies, code + status per row).
• Three downstream test files pinned the old host-config ordering and are updated (below).
• scripts/engine-double-contract.pinned.json: the new pin file's findOne double, recorded by check-engine-double-contract.mjs --write.
• .changeset/22220-package-door-before-gates.md: @objectstack/metadata-protocol patch.

Door table, live (base 4e4111ca05 vs head 9e763ec0bc, both built and booted before the main merge)

Seeded admin, default composition, OS_METADATA_WRITABLE unset. Bodies: served = the GET item; gate-refused = served plus one autonumber field whose format names a missing field (autonumber-references-unknown-field); spec-refused = served plus an undeclared top-level key (unrecognized_keys). Every cell is status code.

examples/app-crm, PUT /api/v1/meta/object/crm_account (packaged under com.example.crm; object is allowOrgOverride: false). Environment kernel = pnpm dev:crm -- --fresh (env_local). Host-config kernel = the same stack under OS_MODE=off (the lightweight assembler, environmentId undefined; confirmed by the repository's sentence on the base row).

body, mode	env kernel, base	env kernel, head	host-config, base	host-config, head
served, publish	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE
served, draft	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE
gate-refused, publish	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	422 INVALID_METADATA	403 NOT_OVERRIDABLE
gate-refused, draft	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE
spec-refused, publish	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	422 INVALID_METADATA	403 NOT_OVERRIDABLE
spec-refused, draft	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	422 INVALID_METADATA	403 NOT_OVERRIDABLE
permission/crm_sales_user, spec-refused, publish	not measured	403 NOT_OVERRIDABLE	422 INVALID_METADATA	403 NOT_OVERRIDABLE
position/sales_rep, spec-refused, publish	not measured	403 NOT_OVERRIDABLE	422 INVALID_METADATA	403 NOT_OVERRIDABLE
control: env-local zz_local_obj, gate-refused, publish	422 INVALID_METADATA	422 INVALID_METADATA	422 INVALID_METADATA	422 INVALID_METADATA
control: env-local zz_local_obj, spec-refused, publish	422 INVALID_METADATA	422 INVALID_METADATA	422 INVALID_METADATA	422 INVALID_METADATA

At head the host-config 403 carries the environment kernel's sentence: the two crm_account gate-refused publish bodies compare byte-equal. At base the host-config 403s carried the repository's sentence ('object' is not allowOrgOverride in the registry ...), and a packaged permission's plain publish carried plugin-security's lock sentence. The environment kernel's code path is unchanged by this diff, which is why its two unmeasured base cells are left unmeasured rather than inferred.

The card's own composition, examples/app-showcase (pnpm dev -- --fresh, host-config), PUT /api/v1/meta/object/showcase_task: base answered 422 for gate-refused publish and for spec-refused publish and draft, 403 for the rest; head answers 403 NOT_OVERRIDABLE for all six rows, and the env-local controls answer 422 INVALID_METADATA.

Door table, unit pins (both kernels; base = protocol.ts at the merge base, head = this branch)

Measured through the real saveMetaItem over an engine double (the new pin file's harness). "gate reached" = assertRuntimeAuthoringRules was called.

request	env base	env head	host-config base	host-config head
object, served body, publish	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE, gate reached	403 NOT_OVERRIDABLE
object, gate-refused, publish	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	422 INVALID_METADATA, gate reached	403 NOT_OVERRIDABLE
object, gate-refused, draft	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE, gate reached	403 NOT_OVERRIDABLE
object, spec-refused, publish	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	422 INVALID_METADATA	403 NOT_OVERRIDABLE
object, spec-refused, draft	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	422 INVALID_METADATA	403 NOT_OVERRIDABLE
object, ?package= naming its read-only package, gate-refused, publish	403 ITEM_LOCKED	403 ITEM_LOCKED	422 INVALID_METADATA, gate reached	403 ITEM_LOCKED
object, fields dropped (destructive), publish	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	409 DESTRUCTIVE_CHANGE	403 NOT_OVERRIDABLE
position, spec-refused, publish	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	422 INVALID_METADATA	403 NOT_OVERRIDABLE
permission, spec-refused, publish	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	422 INVALID_METADATA	403 NOT_OVERRIDABLE
control: env-local object, gate-refused, publish	422, gate reached	422, gate reached	422, gate reached	422, gate reached
control: env-local object, spec-refused, publish	422 INVALID_METADATA	422 INVALID_METADATA	422 INVALID_METADATA	422 INVALID_METADATA
control: packaged view (allowOrgOverride: true), spec-refused	422 INVALID_METADATA	422 INVALID_METADATA	422 INVALID_METADATA	422 INVALID_METADATA

Registry-wide (a packaged pkg_TYPE with a spec-refused body, publish, every type in DEFAULT_METADATA_TYPE_REGISTRY): at base the host-config kernel answered differently from the environment kernel for 15 types (object 409 DESTRUCTIVE_CHANGE; hook, seed, mapping, page, app, action, dataset, datasource, doc, book, permission, position, tool, skill 422 INVALID_METADATA). At head both kernels give the same envelope for every type, and every type the door governs (allowOrgOverride: false, allowRuntimeCreate: true) answers 403 NOT_OVERRIDABLE. The other 13 types answered alike on both kernels at base and at head.

The window the door now precedes (M2)

Refusals saveMetaItem could answer on a host-config kernel between the door's position and repo.put, for a packaged allowOrgOverride: false save:

• the ADR-0010 _lock gate, 403 ITEM_LOCKED (already deferred to the door by hand; that guard is removed);
• the ADR-0029 D9.9 package mismatch, 422 OBJECT_OVERLAY_PACKAGE_MISMATCH;
• the destructive diff, 409 DESTRUCTIVE_CHANGE (measured above);
• the layered-envelope refusal, 422 INVALID_METADATA; the save-name refusal, 400 VALIDATION_ERROR;
• the flow conversion conflict, 409 FLOW_CONVERSION_CONFLICT;
• the spec-conformance parse, 422 INVALID_METADATA, draft and publish (measured);
• the stored-hook body refusal, 400 VALIDATION_ERROR;
• the runtime authoring gate, 422 INVALID_METADATA, publish only (measured);
• the domain plugins' authoring gates: plugin-security's permission-set lock (403 NOT_OVERRIDABLE, its own error class and sentence; measured live) and its object posture gate R1 (403, wire code PERMISSION_DENIED, declaredCode owd_widening_forbidden).

The view-container collision refusal also sits there but judges only view, which allows overlays, so the door never precedes it. ADR-0070 D1 (WRITABLE_PACKAGE_REQUIRED) judges only runtime-only writes, which the door never refuses.

Mechanism assumptions, as measured

• M1 reproduced at base on both compositions above. The authoring-gate body was built from what main refuses (autonumber-references-unknown-field); no pass-4 lift was needed.
• M2 the spec parse also answers 422 ahead of the door on host-config, in draft and publish mode; the full window is listed above.
• M3 the predicate is refusePackagedBaseOverride's own, already topology-independent (packagedBaseRefusal asks it on every topology for the /automation doors). It and assertAllowed read the same registry-derived allowOrgOverride set, the same OS_METADATA_WRITABLE hatch and the same isWritablePackage (package-writability.ts), and both throw the same readOnlyBaseOverrideError for a named read-only base. They differ only in the fallback sentence for a type with no ADR-0126 regime row.
• M4 read 0b997ea447. The door's input is isArtifactBacked, the same input the repository's intent uses, so stack-declared positions are refused by the door on both kernels (measured live for position/sales_rep). The security-domain types are permission, position and capability; capability is code-only and answers the code-only refusal ahead of the door, unchanged.
• M5 held: a draft is still not judged by the authoring gate; env-local bodies still answer 422 on both kernels; a packaged view and a packaged object with the hatch open are still judged by the gates.

What does not move (Clause-② measurement, on this head)

• Accept sets. The door refuses exactly when artifactBacked && !isOverlayAllowed(type). repo.put runs assertAllowed with intent override-artifact whenever artifactBacked, and that refuses on the same predicate, on every topology. saveMetaItem has no success return before repo.put (the one return in that window is inside a closure). So a request the door refuses was refused before, and a request it admits meets the same checks as before. The unit tables above show every measured row refused at base and at head.
• Built entry declarations. dist/index.d.ts and dist/index.d.cts of @objectstack/metadata-protocol, built from this head and from the merge base's protocol.ts (fe98cc63a4): the only differences are the two TSDoc paragraphs corrected above. No declaration line changes.
• Wire. For a packaged allowOrgOverride: false save on a host-config kernel that one of the checks above refused, the answer is now 403 NOT_OVERRIDABLE (or 403 ITEM_LOCKED for a named read-only base) with the door's sentence, which is what an environment kernel already answered.

Downstream pins that encoded the old host-config order

Each relied on the host-config kernel skipping the door. Each now reaches the check it tests the way an environment kernel always had to.

• packages/objectql/src/protocol-destructive.test.ts: saved a destructive edit of a packaged object with no environmentId "to bypass the overlay opt-in gate". It now opens OS_METADATA_WRITABLE=object, the one route by which a packaged object's write reaches the destructive diff. Expectations unchanged.
• packages/rest/src/meta-object-owd-gate.test.ts: the lint-before-R1 order case and the two R1 refusals drove a packaged-object overlay with the hatch shut. They now open the hatch (the path R1's docblock names). Expectations unchanged. Two comments that said the door was environment-scoped are corrected.
• packages/plugins/plugin-security/src/packaged-permission-set-lock-gate.test.ts: the hatch-closed case pinned the lock's error class on host-config. With the hatch closed the door now answers first there, as on an environment kernel, so the case asserts the same NOT_OVERRIDABLE / 403 envelope and that the class is not the lock's. The hatch-open cases still pin the lock's class.

Verification

• Reverse verification: the new pin file run against the merge base's protocol.ts (swapped on disk, blob-verified, restored by trap to the HEAD blob): 23 failed / 26 passed of 49, every failure a host-config row or a registry row; at head 49/49.
• pnpm --filter @objectstack/metadata-protocol exec vitest run: 222 files passed, 3 skipped; 28329 tests passed (at 9e763ec0bc, before the main merge, which touched only the seed loader in this package).
• At 81a42b1203, after git merge origin/main and a rebuild: the new pin file 49/49; objectql protocol-destructive.test.ts 7/7; plugin-security packaged-permission-set-lock-gate.test.ts 7/7; rest meta-object-owd-gate.test.ts 14/14; the five qa/dogfood files that drive saveMetaItem 27/27. typecheck (with check:test-typecheck where the package has it) green for metadata-protocol, objectql, plugin-security and rest.
• Before the merge: objectql full --project local (383 files passed; the 3 failures were protocol-destructive.test.ts, updated above), plugin-security full (181 files passed; the 1 failure was the lock-gate case updated above), the 35 runtime files and 24 rest files that call saveMetaItem (all green except the 3 meta-object-owd-gate cases updated above).
• Gates: node scripts/pm/dispatch-gates.mjs --commands derives 78 commands on 81a42b1203. 70 ran on 32d94c2d00 (the merge commit; the one later commit only adds the ledger row); the 8 that row adds, the changeset gates and the ratchet families re-ran on 81a42b1203. 77 exited 0; --ran reconciles 78 derived, 77 run, 1 unrun. check:engine-double-contract first exited 1 for the missing ledger row and exits 0 with it recorded. check:type-check-debt (a repository-wide re-measure) hit a 400 s local timeout: NOT MEASURED, left to CI.
• Lint, narrowed: ESLint's own config matches 5 of the 7 changed paths (the changeset and the JSON ledger answer "no matching configuration"); --format json reports 5 files, 0 errors, 0 warnings. This config enables no type-aware linting, so the diff cannot move a verdict on an untouched file.

Serial notes

• PR fix(spec,service-automation)!: an undeclared config key on 10 more builtin node types is refused at the build doors; one judge per type #22319 edits saveMetaItem's flow canonicalization and spec-parse region; this diff stays out of those lines.
• PR feat(spec, metadata-protocol): each _drafts row carries the draft body's own label, or null #22323 edits protocol.ts around the drafts listing and sys-metadata-repository.ts; no overlap with this diff.

Acceptance notes

• packages/metadata-protocol/src/protocol.read-lock-flags-write-door.test.ts's hostConfigDoor docblock still says saveMetaItem skips its package door on host-config. The test measures repo.put directly and stays correct; only that sentence is now stale. Not edited here (outside the claimed file surface).
• packaged-base-regime.ts and sys-metadata-repository.ts describe the protocol door as environment-scoped (incomplete now, not false). Not edited here, for the same reason.
• ADR-0005 §"Whitelist enforcement" still says single-kernel deployments keep "any type writable". The repository's assertAllowed has refused these writes on those kernels since before this change; this diff moves no acceptance set, so it reverses no ADR decision. The ADR text is stale relative to shipped behaviour, not to this change.
• deleteMetaItem keeps its own environmentId-scoped removal door; this card is about the save door only.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol, touching 2 documentable anchor(s).

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class), saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/deployment/validating-metadata.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/kernel/cluster.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/kernel/services-checklist.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/permissions/authorization.mdx (via saveMetaItem (symbol, a method of class ObjectStackProtocolImplementation))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class))
• content/docs/releases/v17/17-0.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 11 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 28bff18d0c4013db86d61eba87c739c3145e17fd → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 51bcfc4e3ad7dd71a269695ffc1ac1323d6db922 — the merge of head 81a42b120377e6108fe1dd0eb606ca75c930baf1 into base 28bff18d0c4013db86d61eba87c739c3145e17fd, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 51bcfc4e3ad7dd71a269695ffc1ac1323d6db922 && git checkout 51bcfc4e3ad7dd71a269695ffc1ac1323d6db922
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 28bff18d0c4013db86d61eba87c739c3145e17fd 81a42b120377e6108fe1dd0eb606ca75c930baf1 && git checkout -B drift-repro 28bff18d0c4013db86d61eba87c739c3145e17fd && git merge --no-ff 81a42b120377e6108fe1dd0eb606ca75c930baf1

node scripts/docs-audit/affected-docs.mjs --json 28bff18d0c4013db86d61eba87c739c3145e17fd

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 28bff18d0c4013db86d61eba87c739c3145e17fd → pass the list as
args.docs, on the commit named under Which tree this was computed on.