fix(metadata-protocol)!: refuse the per-item publish and a package-less save over a binding to an uninstalled package - #27084

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol, touching 4 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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin f5e0fade3745c9b9433908f8de67710adb7e10ec && git checkout f5e0fade3745c9b9433908f8de67710adb7e10ec
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin cbb3a1a1a5f858d2f34fcf874fc631b158fae9d1 6135db9b7195db854bb91580bdf51952e60aaf8d && git checkout -B drift-repro cbb3a1a1a5f858d2f34fcf874fc631b158fae9d1 && git merge --no-ff 6135db9b7195db854bb91580bdf51952e60aaf8d

node scripts/docs-audit/affected-docs.mjs --json cbb3a1a1a5f858d2f34fcf874fc631b158fae9d1

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 cbb3a1a1a5f858d2f34fcf874fc631b158fae9d1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

席位核对

ACCEPT · domain:server seat 2 · os-project-manager · session_0186vfjHHMsRXC9EUT9hTFMo · 2026-10-28T05:06Z · head 6135db9b · #26921

The maintainer's standing authorisation for landing reviewed PRs, verbatim: 「按照 pm-dispatch 规则复核过的都授权」.

1. Shape:
   • A draft against main, assignee os-project-manager. The body carries Fixes #26921, with Clause-②: yes (narrowing), Metadata-protocol: none and the Skills-docs: line, all line-initial.
   • The changeset is a patch, with ADR-0087 not required (no migration prescription). The docs paragraph in metadata-lifecycle.mdx is updated.
   • check-governed-merges --pr 27084 reads NOT governed, 507 changed lines.
   • The claim (6458205156) names this PR's branch.
2. Against triage (6454567658) and the order:
   • Measure first held. On a pre-fix(metadata-protocol,runtime,app-shell)!: refuse a save or draft publish naming a package that is not installed #26920 database, a published phantom row can still be removed: a DELETE with or without ?package=, and a draft discard. It becomes editable again once a package with that id is created. The inherit arm therefore does not strand a row, and both arms landed.
   • One rule. Both doors ask the one uninstalledNamedBaseRefusal. It gains a how { verb, inherited } parameter that changes only the sentence. The answer is 422 WRITABLE_PACKAGE_REQUIRED, with no new code and no spec change.
   • The inherited and publish sentences name the real ways out: create the package, or delete or discard the bound rows. They do not offer "save without a package", because that save inherits the binding.
   • The per-item publish is refused before the draft is read, named or not.
   • The inherited save is refused for a publish-mode save through its resolved package and for a draft save through its draft address. An ambiguous address is still left to the repository's 409.
   • A save that names a package, and the server-stated rewrites, are unchanged.
   • The draft-address read moved out of the object-only branch so that both gates read one address. A package-less draft save now makes that one read for every type.
   • Nothing is migrated or deleted.
3. Red first (the dev's):
   • The new protocol suite, with protocol.ts at its base blob, failed 11 of 16; the 5 controls passed. It is green at 16 of 16.
   • Live REST on one pre-fix(metadata-protocol,runtime,app-shell)!: refuse a save or draft publish naming a package that is not installed #26920 snapshot: base answered 200 on a package-less PUT (active and draft) over a phantom row, and on POST /meta/dashboard/NAME/publish with and without ?package=. The branch answers 422 on all four with the rows unchanged. The installed-package and package-less controls answer 200 on both.
4. Tests:
   • On the head: metadata-protocol 21,749 passed and objectql 8,893 passed.
   • On the same source: runtime 8,529, rest 6,827, client 678, plugin-security 5,049 and cli 4,951.
   • Fixture fallout was fixed by installing packages; no rule was widened.
   • Both type-checks exit 0.
5. Dogfood (owed by the narrowing): 346 files and 2,794 tests passed on 16162380. The only later commit adds three rows to the engine-double ledger JSON, which no dogfood test reads.
6. Gates:
   • Locally 101 of 101 derived commands exit 0, with 0 NOT-MEASURED.
   • CI on head 6135db9b: 37 success, 11 skipped, 0 red.
7. Overlap: git merge-tree reports no conflict against main fbc16563.
8. Noted, not filed: Studio shows "Package not found" for a phantom id, so the named ways out are REST or SDK acts. A phantom id that the install door refuses as a package id (for example, one with underscores) cannot be brought back by creating the package, but its rows can still be deleted or discarded.

Generated by Claude Code

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6135db9b7195db854bb91580bdf51952e60aaf8d
Local-runs: none
Scope: packages/metadata-protocol/src/protocol.ts, scripts/engine-double-contract.pinned.json, packages/metadata-protocol/src/protocol.named-base-stored-binding.test.ts, packages/metadata-protocol/src/protocol.package-closure-gate.test.ts, packages/metadata-protocol/src/protocol.batch-verb-driver-code.test.ts, packages/metadata-protocol/src/protocol.batch-verb-driver-text.test.ts, packages/metadata-protocol/src/protocol.destructive-409-face-inventory.test.ts, packages/objectql/src/protocol-sentinel-owner-draft-save-address.test.ts + packages/metadata-protocol/src/protocol-write-package-scope.ts (resolveWritePackageScope, the installed-or-not predicate the rule asks), packages/metadata-protocol/src/protocol-lock-version-gates.ts (packagelessDraftAddress, the into the inherited arm judges), scripts/check-engine-double-contract.mjs (the gate the ledger rows feed), packages/rest/src/error-response.ts (CLIENT_MESSAGE_MAX = 500), .changeset/26708-named-base-every-type.md on origin/main (the precedent declaration pair)

Face: narrowing (Clause-②: yes (narrowing) on the PR body and the changeset). Net diff read against merge-base 3230bdbf (head vs the merge commit 6845035c's first parent d7f76b6d): 10 files, +473/-34, byte-equal to the PR's file list. Card #26921 read in full: body, triage 6454567658, claim 6458205156, os-dev-report 6460881887, landed 6462047952; PR body, ACCEPT 6461156816, docs-drift bot comment. Check-runs on the head: 50, 39 success, 11 skipped (all UI / opt-in / live-DB families with no path hit), 0 failure; the eight required contexts, Dogfood Regression Gate and the engine-double gate's job are among the successes. This record was asked after the merge (landed 2026-10-28T06:03Z); it is the record of record for the head.

① Derived judgments

Accept-set changes the diff implies, each judged against the triage ruling (per-item publish refuses with the ONE rule; inherit arm leans refuse after measure-first; no migration, no deletion, no second copy, no new code, no packages/spec):

1. PUT /meta/:type/:name naming no package, publish mode, over active rows bound to one package id the registry does not hold: 200 → 422 WRITABLE_PACKAGE_REQUIRED with packageId = that id, before any write. Right. saveMetaItem resolves the address once (packagelessAddress, rewriting request.packageId), and the new block reads that resolved id under namedNoPackage (captured before the rewrite), so the ask is about the inherited binding only; a save that names a package was already judged as named two gates up; source set (migrate-stored) and writeFace: 'package-duplicate' are exempted exactly as the named ask exempts them.
2. The same save in draft mode, over an active row bound to such an id, or over a lone draft bound to it: 200 → 422. Right. packagelessDraftAddress answers into = own for an item bound to one package (draft present or not, lines 478-480 of the moved body) and into = key for the lone-draft case (line 486), so the judged id is the package the draft would be written under. An ambiguous address passes null to the rule and falls through to the repository's 409, unchanged.
3. POST /meta/:type/:name/publish, named (?package=ID) or not, whose promotion lands in such an id: 200 → 422, before the draft is read. Right. The ask is on promoteInto (the caller's key, or the address's into), after the lock refusal and the address refusal keep their order. publishPackageDrafts reaches the same method with packageId stated; its door already refuses an uninstalled id, and an installed id passes resolveWritePackageScope, so the batch publish's accept set does not move.
4. The sys_metadata sentinel and a null binding return null from the helper first; package-less items and items bound to installed packages are untouched. Right, and pinned by the 5 controls in the new file.
5. Fail direction on a registry with no getPackage: the per-item publish naming a package, or inheriting one, is now refused on such a double, the closed direction metadata: the save door and the package publish door accept a package id that is not installed (object, dashboard, page …), storing and even publishing items into a phantom package; Studio renders a writable builder for it #26708 took for the save door. Right, and the three metadata-protocol fixtures plus the objectql boot now install the package their rows bind to; no fixture widens the rule (each getPackage answers only the seeded id). Test Core 8/8 green says no other double in the repo was left behind.
6. protocol.package-closure-gate.test.ts: the pin "narrows NOTHING when the registry cannot produce the written package" asserted exactly the promotion this card refuses (success: true after the package left the registry). Replacing it with the 422 assertion and keeping the installed leg's closure refusal as the discriminating control is right: the state it pinned is no longer reachable through a promotion. Minor, not blocking: resolveWritePackageScope's docblock still lists "the registry cannot produce the package" as a way the closure gate sees the whole collection; that sentence is still true of the function and now describes no promotion path.
7. scripts/engine-double-contract.pinned.json: three rows (delete, findOne, update, pinned 1 each) for the new test file, whose double routes those three verbs through assertEngineDeleteDispatch / assertEngineFindOnePredicate / assertEngineUpdateDispatch from @objectstack/metadata-core (not objectql, which depends on this package). The gate's SLICES are exactly those three verbs; the rows are the RETAINED enumeration the gate's header asks for a newly pinned double. Right; the gate's job is green on the head.
8. Sentences: the helper's third (named-save) sentence and the flow arm are byte-unchanged (diff read). The two new sentences measure 423 (inherited) and 422 (publish) characters for the PR's own names and 478 / 482 with a 14-character type and 40-character name and id, under the REST door's CLIENT_MESSAGE_MAX = 500, as the PR claims. They name only ways out that exist (create the package; delete naming the id; discard-drafts), never "save without a package", which would inherit the binding.
9. Public surface: uninstalledNamedBaseRefusal is private and its new how parameter defaults to {}, so every existing caller is source-compatible; no export, no Zod face, no error code, no packages/spec file moves (check:api-surface green). The inherited draft-address read now runs for every type's package-less draft save, two sys_metadata reads the repository's resolveWriteHead already makes for the same save; declared in the PR's Acceptance notes, a cost, not a contract change.
10. Measure-first stop condition (triage): the PR records on a pre-fix(metadata-protocol,runtime,app-shell)!: refuse a save or draft publish naming a package that is not installed #26920 snapshot that a published phantom row is still deletable (DELETE with and without ?package=), its draft discardable, and the item editable again after POST /packages with that id (201). The new file pins the delete leg. The arm was implemented, not handed back, as the ruling allows.

② Semver level

.changeset/26921-named-base-stored-binding.md: '@objectstack/metadata-protocol': patch, BREAKING banner, Clause-②: yes (narrowing), Metadata-protocol: none, one ADR-0087 marker not-required (no-migration-prescription), and the FROM → TO remedy (create the package, or delete / discard-drafts and save again). The level matches what the diff publishes: the only package whose source moves is @objectstack/metadata-protocol (objectql and scripts change tests and a ledger, which publish nothing); the kind is none, since what is refused is a request's binding and no key, value or metadata type an author writes changes, so none takes patch, and a narrowing non-protocol change ships patch with its banner and disposition. This is the pair the precedent .changeset/26708-named-base-every-type.md on origin/main carries for the same rule one door over. The Clause-②: line is yes (narrowing) on the PR body and the changeset, line-initial in both, and the face it declares is the one the diff has: two 200s become 422s. Check Changeset and Lint & Repo Gates (which carries check:adr-0087-registration) are green on the head. Match.

③ Boundary flags

• open_questions: [] in the os-dev-report. None to answer.
• Dev note 1 (no class): Studio shows "Package not found" for a phantom id, so the ways out the new sentences name are REST / SDK acts. Answered: carried in the PR's Acceptance notes, inherited from metadata: the save door and the package publish door accept a package id that is not installed (object, dashboard, page …), storing and even publishing items into a phantom package; Studio renders a writable builder for it #26708's own note, and the triage asked for refusal naming the way out. Not a FAIL. The seat should weigh a Studio follow-up card: a Studio author on a pre-fix(metadata-protocol,runtime,app-shell)!: refuse a save or draft publish naming a package that is not installed #26920 database now meets a 422 whose prescription Studio cannot perform.
• Dev note 2 (no class): a phantom id the install door refuses as a package id cannot be brought back by creating the package; its rows can still be deleted and discarded. Answered: the sentence's "or remove the rows bound to it" covers it; note-only is right.
• Dev deviation: commits carry Claude-Session plus Co-authored-by: Claude instead of the harness reminder's model-named line. Answered: that pair is the form AGENTS.md prescribes and the pre-push hook enforces, so this is compliance, not a deviation; the merge commit 16162380 carries no trailer, which is ordinary for a git merge origin/main commit. Nothing owed.
• Skills-docs line: present on the PR body; git grep on skills/ for the per-item publish and the package-less save over a bound item finds no teaching page beyond the publish-drafts event row, which this change does not alter. Held.
• Governed surfaces: none of the ten paths is in GOVERNED_SURFACES (register read); Governed Surface Queue Guard green; 507 changed lines, under 3,000.

Implemented-by: claude/project-thread-66cy4b
Reviewed-by: session_0186vfjHHMsRXC9EUT9hTFMo

VERDICT: PASS

Generated by Claude Code