feat(metadata-protocol): an unmanaged install copies no protection lock, and names each one it drops - #23075

📓 Docs Drift Check

This PR changes 4 package(s): @objectstack/cli, @objectstack/cloud-connection, @objectstack/metadata-protocol, @objectstack/spec, touching 24 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/spec/authorable-surface/api.json, packages/spec/src/kernel/manifest.zod.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/api/error-handling-server.mdx (via safeParse (symbol, a method of interface DeclaredValueJudge))
• content/docs/automation/jobs.mdx (via os package install (command, read off packages/cli/src/commands/package/install.ts))
• content/docs/concepts/metadata-lifecycle.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class))
• content/docs/deployment/cli.mdx (via MarketplaceInstallLocalPlugin (symbol, a top-level class), os package install (command, read off packages/cli/src/commands/package/install.ts))
• content/docs/deployment/publish-and-preview.mdx (via os package install (command, read off packages/cli/src/commands/package/install.ts))
• content/docs/protocol/kernel/index.mdx (via os package install (command, read off packages/cli/src/commands/package/install.ts))
• content/docs/protocol/kernel/lifecycle.mdx (via os package install (command, read off packages/cli/src/commands/package/install.ts))
• content/docs/protocol/kernel/metadata-service.mdx (via os package install (command, read off packages/cli/src/commands/package/install.ts))
• content/docs/protocol/kernel/plugin-spec.mdx (via os package install (command, read off packages/cli/src/commands/package/install.ts))

⛔ 5 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), lock (symbol, a field of const object STRIPPED_ENVELOPE_KEYS), os package install (command, read off packages/cli/src/commands/package/install.ts))
• content/docs/releases/v17/17-5.mdx (via safeParse (symbol, a method of interface DeclaredValueJudge))
• content/docs/releases/v17/17-6.mdx (via os package install (command, read off packages/cli/src/commands/package/install.ts))
• content/docs/releases/v17/17-7.mdx _(via lock (symbol, a field of const object STRIPPED_ENVELOPE_KEYS), os package install (command, read off packages/cli/src/commands/package/install.ts))

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 85f41ef4183bc50018fb8ed525b5e5f2c7f4d516 && git checkout 85f41ef4183bc50018fb8ed525b5e5f2c7f4d516
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 038d4c958837fb42e71842c18f062f37bd866811 58984f5c5baf2eb298c8346f1a05ddf8e8d885a6 && git checkout -B drift-repro 038d4c958837fb42e71842c18f062f37bd866811 && git merge --no-ff 58984f5c5baf2eb298c8346f1a05ddf8e8d885a6

node scripts/docs-audit/affected-docs.mjs --json 038d4c958837fb42e71842c18f062f37bd866811

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

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 58984f5c5baf2eb298c8346f1a05ddf8e8d885a6
Local-runs: none

Rendered 2026-10-12T21:06Z by the isolated at-tier reviewer subagent of domain:spec seat 1 (seat post #6017, account os-warren) on PR #23075 (Part of #15213, the _lock strip). Read-only: the PR body, its 14-file list and the net diff against main (804 changed lines, read against the merge base the PR body's affected-closure measurement names), card #15213's body and all 46 comments, ruling 6119681934 on #22971 and its close 6119699999, and the check-runs on this head. Nothing built, run or re-run; the fork PR test is moot (head repo is the base repo). The head sha was confirmed from the REST read of the PR before anything else was read.

① Derived judgments

The published surface this diff implies, judged line by line against the diff:

1. @objectstack/spec — ImportUnmanagedPackageResponseSchema gains the required field strippedLocks (packages/spec/src/api/package-lifecycle.zod.ts): an array of { type, name, lock, reason? }, lock taken as MetadataLockSchema.exclude(['none']) from the one lock declaration in kernel/metadata-protection.zod.ts, never restated. Right. This is the ruling's "the import result names each stripped lock together with the vendor's reason", declared exactly once; the only non-test producer on main is importUnmanagedPackage (protocol.ts), and at this head it states the field. The three generated artifacts moved with it and nothing else: authorable-surface/api.json (+1 key), content/docs/references/api/package-lifecycle.mdx (the field and its nested shape), the strictness ledger count 437 → 438. No export was added or removed in spec, so no api-surface shard moves. A required field on a z.input response type is a widening for its producer; no code in the repo parses another runtime's answer with this schema, and the CLI reads the field through Array.isArray so a runtime that predates it prints nothing. (widening) is the right arm.
2. packages/spec/src/kernel/manifest.zod.ts — the INSTALL_MODES TSDoc only. No shape moves. Right.
3. @objectstack/metadata-protocol — the import's behaviour: every planned item is written without _lock, _lockReason, _lockSource, _lockDocsUrl and, on a type whose schema declares the key, without its protection block; the plan carries strippedLocks in write order and the verb returns it. Right. The published surface of the package does not move: src/index.ts at this head exports neither stripUnmanagedImportLock, overlaySchemaDeclaredKey, UnmanagedImportStrippedLock nor DeclaredValueJudge (it names only unmanagedInstallPostureRefusal from the pure module and a closed list from protocol.ts), and package.json's exports map has the single . entry. The verb's return type is spec's, so the one published change is item 1. The dev's acceptance note that the two new exports are module-level for the tests only is confirmed on the head.
4. Refusals of the unmanaged import — unchanged. Confirmed in the head's package-unmanaged-install.ts: the key dispositions (UNMANAGED_INSTALL_KEY_DISPOSITIONS) are judged on the manifest's collection keys before enumerateItems, and the strip runs on the enumerated items after the sort; stripUnmanagedImportLock hands the body back untouched when any envelope key fails its own declaration (MetadataProtectionFields) or the block fails the type's own protection schema, and it leaves a protection block on a type whose schema declares none, so the save door refuses those exactly as on main (422 INVALID_METADATA, rolled back; pinned at the unit level for _lock: 'locked' and for a page carrying the block, and the every-type ablation turned the page pin red). Nothing previously refused is accepted and nothing previously accepted is refused. Right. The one corner the dev flagged — envelope keys plus a block on a non-declaring type — ends in the door's refusal and a rollback, so no answer and no strippedLocks is ever returned for that body.
5. The entry for an item carrying both spellings is the lock a managed install binds. Confirmed against packages/spec/src/shared/protection.zod.ts: applyProtection writes the block's lock and reason over _lock / _lockReason when the block states them, so the strip's scratch-copy translation reports one entry with the block's values and 'none' reports nothing. The dogfood lock control measures the same on a real managed install. Right — the report is the managed binding, not a second rule.
6. Seat decision 1 (6128999134): strip the protection block on declaring types and report it — judged WITHIN ruling A's text, not beyond it. Ruling A's operative sentences are "the unmanaged import strips every lock from each copied item, and the import result names each stripped lock together with the vendor's reason" and "Visible, not silent". Its bullet names _lock / _lockReason / _lockSource on a stated premise — "whether the lock was authored per item or resolved from metadataDefaults.lock by the loader (both arrive as the same L3 shape)" — that is, the ruling meant to reach every lock a package ships and believed all of them arrive as the L3 envelope. That premise is measured false on both halves (no schema declares metadataDefaults; the protection block arrives untranslated). ADR-0010 Phase 4.3 defines protection as the public author surface that "translates into the private _lock envelope at load time" — the same lock in its authored spelling, and the spelling the guidance tells authors to write. Under the ruling's own rationale ("a lock whose source is the package has nothing to stand on once the package is no longer the authority"), the block is a package lock; keeping it inert on the copy would be the silent loss the ruling forbids and a declared-but-unenforced block in the row (Prime Directive chore: version packages #10); stripping it on every type would move a refusal, which the ruling costs no gate for. Stripping it only where the type's own schema declares it, reported in the ruling's entry shape, with no new field, no new gate and no refusal moved, is the ruling applied to the spelling its premise mis-described. It is not a new product decision and needs no decision-box entry; the seat recorded the maintainer's veto window on it, which is the right form.
7. Seat decision 2 (6128999134): strip _lockDocsUrl with the other three keys, no new report field — judged WITHIN ruling A's text. It is the fourth member of the one declared envelope (MetadataProtectionFields in spec; LOCK_FAMILY_KEYS in item-lock.ts); applyProtection writes it as part of the same translation; once _lock is gone it is served nowhere and binds nothing, so leaving it would leave an orphan lock-family key in the row. "Strips every lock" takes the lock's whole envelope. The option that would have gone beyond — a docsUrl field on each entry — was not taken.
8. The install door (@objectstack/cloud-connection) relays result.strippedLocks as the verb states it, and the managed branch's answer carries no such key (pinned in dogfood). Right. The door's unmanaged answer has no spec declaration of its own on main (a pre-existing fact of S2's landing, not moved here), so there is no second declaration owed.
9. The CLI prints each entry as TYPE.NAME: LOCK — REASON, the dash and reason absent when the package gave none, and prints no lock line for an empty list or an answer without one. Right — this is the ruling's own spelling, rendered from the structured field, which is the correct form for a machine-read answer.
10. The changeset supersedes the two _lock sentences of the pending 15213-install-modes entry by statement rather than by editing it; that entry is still pending on origin/main and says the copy keeps an authored _lock. Right — both ship in one release, so no published version ever carried the kept-lock behaviour; nothing is removed or narrowed, and check:adr-0087-registration owes no marker.
11. Governed surfaces: none of the 14 paths hits a GOVERNED_SURFACES row; docs/audits/** is not one. The review is owed on the Clause-②: yes and packages/spec/src/** faces, which this record serves; Governed Surface Queue Guard is green on the head.

Check-runs on this head (the gate verdicts): 48 check runs, 41 success, 7 skipped, 0 failure. The seven required contexts: Lint & Repo Gates, TypeScript Type Check, Test Core (and its six shards), Dogfood Regression Gate, Build Core and Governed Surface Queue Guard succeeded; Temporal Conformance (live PG + MySQL) was skipped by its own paths filter, as were the dogfood matrix shards, Console Pin Gate, Dogfood Verify CLI and the opt-in packed-tarball smoke. The PR reads mergeable: true, mergeable_state: clean, draft, auto-merge not armed, no review submitted.

② Semver level

• @objectstack/spec: minor — one new required field on a published response declaration; no export added or removed. Matches the changeset.
• @objectstack/metadata-protocol: minor — the verb's answer gains the field and the copy no longer carries a lock; the package index publishes nothing new. Matches.
• @objectstack/cloud-connection: minor — the unmanaged answer gains the field. Matches.
• @objectstack/cli: minor — new output lines. Matches.
• The declaration agrees across the claim (6126585884), the PR body and the changeset: Clause-②: yes (widening: the new response field strippedLocks on ImportUnmanagedPackageResponseSchema, relayed on the install-local answer for installMode unmanaged). yes takes at least minor — held; the (widening) arm is the right one and owes no ADR-0087 disposition marker. Check Changeset and Lint & Repo Gates are green on the head. The superseded sentences live only in the pending 15213-install-modes entry, so nothing released is narrowed and no migration text is owed.

③ Boundary flags

Round 1 report 6128963245, deviations:

1. A2 falsified, metadataDefaults pinned as refused 422 UNMANAGED_INSTALL_UNCOPYABLE instead of stripped — answered, right: no schema declares the key, the pin is in the diff and reddens the day the key is declared and classified.
2. protection not stripped in round 1 — superseded by seat decision 1, implemented at this head (① item 6).
3. _lockDocsUrl left in round 1 — superseded by seat decision 2, implemented at this head (① item 7).
4. origin/main merged once mid-stage, no conflicts — answered: that merge is the merge base this record's diff was read against.
5. The dogfood managed-control red on base was a fixture bug in reading the GET /meta envelope, corrected in the PR — answered: a fixture correction inside this diff; the head's fixture reads data ?? body.
6. Model-free commit trailers — answered: the form AGENTS.md requires.
7. Session-URL footer on the PR body — answered: the form AGENTS.md requires; the body carries exactly one footer.

Round 1 open questions (both): decided by the seat in 6128999134 and built in round 2; judged in ① items 6 and 7 as within the ruling.

Round 1 out-of-scope finding (class c, the protection block stored and never bound on an environment item): answered — a save-door defect outside this diff, which the PR correctly does not fix; the ACCEPT 6132465308 records it filed as #23096. That issue was not read here (outside this record's input set).

Round 2 report 6132411048, deviations:

1. PR body not edited by the dev, the replacement handed to the seat — answered: the PR body read here is that replacement, one footer.
2. @objectstack/cli's integration project left to CI — answered: Test Core 1–6 are green on the head.
3. Lock-holder load on the shared verify lock — answered: a process note with no contract bearing.
4. The first check:generated --fix timed out on the lock; the one stale artifact was regenerated with gen:docs and the rerun read all 14 current — answered: the TypeScript Type Check job, which runs the spec check:* gates, is green on the head.
5. Envelope keys plus a protection block on a non-declaring type: envelope stripped, block left, door refuses 422 — answered, right: judged in ① item 4; nothing new is accepted and no answer is returned for that body.
6. Model-free commit trailers — answered, as above.

Round 2 open questions: none.

Round 2 out-of-scope findings:

1. The Studio save door accepts, stores, serves and never binds a hand-authored protection block on an environment item (class c; the Seam is ViewSchema.protection and siblings to saveMetaItem / item-lock.ts) — answered: outside this diff; carried by metadata-protocol: the Studio save door stores a hand-authored protection block on an environment item verbatim and never binds it, though the spec says the block is translated into _lock and stripped before persistence #23096 per the ACCEPT; this PR leaves it alone and, for declaring types, no longer writes such a block itself.
2. A managed dataset's GET /meta/dataset/:name answers without the top-level lock envelope that GET /meta/dashboard/:name answers (uninvestigated) — answered: an observation on the read path, which this diff does not touch, so it bears on no contract here. One records gap for the seat: the ACCEPT says "Acceptance notes, carrier none", but the PR body's acceptance notes do not carry it — it lives only in the report and the ACCEPT. Under Prime Directive chore: version packages #10 the seat owes it a carrier: a line in the PR body's acceptance notes, or an issue once it reproduces. Not verdict-bearing.
3. S3 (the authoring page) states that an unmanaged copy keeps no lock in either spelling and that the install lists each lock it drops — answered: matches the seat's carry; S3 and S4 stay on the card, and the PR says Part of #15213 with no closing keyword.

No flag is escalated: neither seat decision goes beyond ruling A, no refusal moved, and the one defect found is carried by its own issue.

Implemented-by: claude/issue-15213-lock-strip
Reviewed-by: session_019G5ZnRrTMiwcHG6iZM19zf

VERDICT: PASS