fix(metadata-protocol): the read envelope's lock / editable / deletable report the write doors' locked-base verdict

[objectstack-fleet]

Fixes #21670

Clause-②: no

What was wrong

Both metadata reads publish the ADR-0010 protection envelope beside the item: getMetaItem, and getMetaItemLayered, which serves GET /api/v1/meta/:type/:name/layers and its deprecated ?layers=true spelling. That envelope was resolveLockState(document), built from the item's own _lock and nothing else.

The write doors also refuse a second kind of item: one a code package ships, on a type with no per-org overlay channel. They answer 403 NOT_OVERRIDABLE, or ITEM_LOCKED when the write names the read-only package. So packaged flows and actions read lock: "none", editable: true and deletable: true while every door refused them in place. So did the packaged items of 21 other types.

Trace

• Producer. packages/metadata-protocol/src/protocol.ts has two call sites of resolveLockState, one in getMetaItem and one in getMetaItemLayered. The spec declares the fields once, in MetadataProtectionEnvelopeFields (packages/spec/src/api/protocol.zod.ts), and both responses share them.

• The doors' predicate. packagedBaseRefusal is public on the same class. It holds refusePackagedBaseOverride and refusePackagedBaseRemoval, both lifted out of saveMetaItem / deleteMetaItem, and the /automation doors already ask it. It does not depend on topology:

  • on an environment kernel, the protocol throws the refusal;
  • on a host-config kernel (the showcase), SysMetadataRepository.assertAllowed / assertDeleteAllowed throws the same refusal at the write.

  The table below measures both kernels. They agree on every type.

The change

One private derivation, servedLockState, which both reads now call:

• editable is the _lock verdict AND packagedBaseRefusal(save) === null.
• deletable is the _lock verdict AND packagedBaseRefusal(delete) === null.
• lock is the ADR-0010 state whose evaluateLockForWrite / evaluateLockForDelete verdicts are exactly those two booleans. It is read off the lock algebra, so there is no second table. The spec's declared algebra therefore still holds: editable is false iff lock is no-overlay or full, and deletable is false iff lock is no-delete or full.
• An item's own _lock and the package verdict join; neither replaces the other.
• lockReason, lockSource and lockDocsUrl are unchanged: they are still only what the document declares.
• No write door changes.

Spec wording. The lock field's .describe() said it refuses "with 403 ITEM_LOCKED" and is "Resolved from the document's _lock". This change makes both statements false for package-door locks, so the description now names both refusals. This is wording only: no key, type, optionality or accept set moves (Clause-② no). check:generated --fix regenerated content/docs/references/api/protocol.mdx, one line.

Beyond the claimed file surface: the spec description edit and its regenerated reference line, and scripts/engine-double-contract.pinned.json, where the gate records the new test's engine double.

Measured: every registry type, both kernels

Packaged item with no _lock. Each read was none / true / true before this change. The environment kernel and the host-config kernel gave identical rows for all types (0 differ).

types	save door	delete door	read now (lock / editable / deletable)
view, dashboard, report, translation, email_template	admitted	admitted	none / true / true (unchanged)
page, app, dataset, book, permission, position, tool, skill	403 NOT_OVERRIDABLE	admitted (the supportsOverlay overlay-removal carve-out)	no-overlay / false / true
object, field, hook, seed, picklist, mapping, action, flow, job, datasource, external_catalog, api, doc, capability, agent	403 NOT_OVERRIDABLE	403 NOT_OVERRIDABLE	full / false / false

An org-owned item is a stored row that no package ships. For the 22 types that can be created at runtime, both doors admit it on both kernels, and it reads none / true / true (unchanged).

Pins

The new file packages/metadata-protocol/src/protocol.read-lock-flags-write-door.test.ts holds 107 cases.

• Packaged flow and action: lock is not none, editable: false, deletable: false, on both reads and both kernels.
• Org-owned flow and action: read none / true / true.
• The table: 100 rows, made of 28 types × 2 kernels for packaged items plus 22 × 2 for org-owned items. Each row asserts three things: read equals door, the spec's algebra holds, and the by-name read equals the layered read.
  • On the environment kernel the door is saveMetaItem / deleteMetaItem, end to end. An admission counts only if it reached the _lock gate and that gate answered null.
  • On the host-config kernel the door is the repository gate. An admission means the engine was touched, which only happens past the gate.
• Lit control:
  • the roster equals DEFAULT_METADATA_TYPE_REGISTRY, with a floor of 28;
  • each verb was both refused and admitted on each kernel;
  • all three lock states appeared.
• Controls:
  • with OS_METADATA_WRITABLE=flow,action, the read is none / true / true and the door admits;
  • a packaged view with _lock: 'no-delete' reads no-delete, and its delete door refuses with ITEM_LOCKED;
  • a packaged flow with _lock: 'no-delete' reads full, which shows the two verdicts join rather than replace.

Evidence

• Red first. At 515955b905 (the pin alone, on main's code): 50 failed / 57 passed of 107. The failures read expected 'none' not to be 'none' and expected { editable: true, deletable: true } to deeply equal { editable: false, deletable: false }.

• Green with the fix: 107 / 107.

• Ablation. With the fix committed, scripts/ablation-replace.mjs replaced return { ...declared, lock, editable, deletable }; with return declared;.

  • The mutation landed: anchor count 1 → 0, marker 0 → 1, blob c462702ad973 → f61b76d75c58.
  • Result: 50 failed / 57 passed, read from the vitest summary line.
  • Restored by blob hash: c462702ad973 equals the HEAD blob, and git diff HEAD is empty.
  • A first attempt was a no-op: its replacement still contained the anchor, so the tool refused it and no test ran.

• @objectstack/metadata-protocol. tsc --noEmit exits 0, and the new test is in the program (--listFiles count 1). vitest run: 210 files, 3570 passed, 19 skipped.

• Consumer sweep (downstream readers of the envelope that drive a real protocol or pass it through):

  package	files	result
  objectql src/protocol-*	39	612 passed
  plugin-security permission-set and packaged tests	13	191 passed
  rest src/meta-*	49	1077 passed
  runtime src/domains/meta-*	19	1048 passed

• Gates. dispatch-gates --commands at 017a2c7599 derives 120 commands. --ran reconciles 118 run, all at exit 0, and two not measured. Both are declared to CI:

  • check:dual-build-cjs-loads exits 3: it needs every package built. This diff adds no module to any entry's import closure: MetadataLockSchema comes from @objectstack/spec/kernel, which protocol.ts already imports.
  • check:type-check-debt hit the foreground cap. It re-measures the DEBT-ledger packages repo-wide. metadata-protocol has no DEBT entry and its own tsc is clean, and the spec edit is describe text only.

• Re-run at the final head 017a2c7599:

  • check:engine-double-contract (the new double is recorded in the pinned ledger)
  • check:objectql-double-limit
  • check:nul-bytes
  • check:cross-package-test-inputs
  • check:test-source-alias
  • check:type-check-coverage
  • check:durability-log-level
  • the changeset gates
  • spec check:generated: "All 15 generated artifacts are up to date"

Acceptance notes

• Host-config DELETE. On a host-config kernel, a DELETE of a packaged flow or action that has NO overlay row still answers 200 "No customization overlay found ... already at artifact default". That is the reset door's no-op, and nothing is removed. deletable: false is the base-removal verdict, which the predicate's own docblock states for every topology, so the two do not contradict. On an environment kernel the same DELETE answers 403 NOT_OVERRIDABLE.
• Who sees the change. The Setup metadata admin's resource page (objectui ResourceEditPage) reads layered.editable, deletable and lock.
  • Packaged items in the two locked groups will now draw its lock banner. Their write affordances were already off, by type (canWriteByType).
  • The no-overlay group keeps its reset / delete button (deletable is true).
  • Studio's designers read GET /api/v1/packages writable, which is unchanged.
• Observation, not filed: _lock on host-config. On a host-config kernel the item-level _lock gate (lockWriteRefusal, assertLockAllowsDelete) returns no refusal while environmentId is undefined. So an overlay-type item that declares _lock reads editable: false there, while the /meta save admits it. The read is stricter than the door. This PR leaves it alone, because the doors' policy is outside this card. No shipped producer was found: the protection.lock declarations in platform-objects are all on object, which the package door refuses anyway. Carrier: none.
• Observation, not filed: diagnostics count. getMetaDiagnostics().stats[type].locked counts declared _lock only, not package-door locks. Carrier: none.
• Boundary: code-only types. field, picklist, job, api, capability and agent have no org-owned arm in the table. No runtime door can author one (NOT_CREATABLE), and that refusal is not the locked-base predicate. Their packaged arm is in the table.
• Not merged with main. origin/main has moved 2 commits since 7d0781482d, touching the organizations plugin and sdui-parser. Both are disjoint from this diff.
• No live boot. The REST layered door passes the protocol's answer through unchanged (createMetaLayeredAnswer spreads it), so the protocol pin and the REST / runtime sweep stand in. No showcase boot was run.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

4 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), getMetaItemLayered (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/data-modeling/drivers.mdx (via getMetaItem (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/kernel/contracts/metadata-service.mdx (via getPublished (sdk, the bare tail of client method meta.getPublished, bound to GET /api/v1/meta/:type/:name/published; the bare tail of client method meta.getPublished, bound to GET /meta/:type/:name/published))
• content/docs/kernel/services-checklist.mdx (via getMetaItem (symbol, a method of class ObjectStackProtocolImplementation))

⛔ 3 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/v17/17-3.mdx (via /:type/:name/published (route, bridged from symbol getMetaItemLayered — its route source's handler names it))

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

• 1 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 139 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 251a7dd4b491d1f216e8a470d0efd0dc7e8ac5e8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 4f238ed6aa4e29e260f76e8ddd2d93448fa915fd — the merge of head 017a2c7599cb7946e118e2e8600acc5b5432c9bd into base 251a7dd4b491d1f216e8a470d0efd0dc7e8ac5e8, 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 4f238ed6aa4e29e260f76e8ddd2d93448fa915fd && git checkout 4f238ed6aa4e29e260f76e8ddd2d93448fa915fd
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 251a7dd4b491d1f216e8a470d0efd0dc7e8ac5e8 017a2c7599cb7946e118e2e8600acc5b5432c9bd && git checkout -B drift-repro 251a7dd4b491d1f216e8a470d0efd0dc7e8ac5e8 && git merge --no-ff 017a2c7599cb7946e118e2e8600acc5b5432c9bd

node scripts/docs-audit/affected-docs.mjs --json 251a7dd4b491d1f216e8a470d0efd0dc7e8ac5e8

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 017a2c7599cb7946e118e2e8600acc5b5432c9bd
Local-runs: none

Inputs read: #21670's body, triage 5976009143, claim 5976826510, the dev report 5977264927 (read as claims), PR #21693's body, its 6 files and its diff, and the head's check-runs. Read-only: nothing was built, run or re-run.

Gates at review time: 18 completed success, 2 skipped (Console Pin Gate, Packed-tarball smoke, both opt-in), and 12 still in_progress: Lint & Repo Gates, Test Core 1/6 to 6/6, Type Check · workspace, Type Check · consumer gates, Dogfood Regression Gate 2/3 and 3/3, Temporal Conformance. Those 12 have no verdict yet. This review does not stand in for them, and the merge waits for them.

① Derived judgments

servedLockState: same predicate, no second table. Holds.

• It takes declared = resolveLockState(document, artifactBacked), which is the _lock verdict, unchanged.
• editable is declared.editable && packagedBaseRefusal({type, name, operation: 'save'}) === null, and deletable is the same with 'delete'.
• packagedBaseRefusal turns the throws of refusePackagedBaseOverride / refusePackagedBaseRemoval into a value. saveMetaItem and deleteMetaItem call those same two functions at their package doors, and the /automation doors already ask packagedBaseRefusal.
• So the predicate is asked, not copied, and no type list or policy table is added.
• The read omits packageId. That does not change the boolean: a named read-only base re-codes the refusal to ITEM_LOCKED, and a named writable base still falls through to NOT_OVERRIDABLE. The verdict is refused either way, and only the code differs.

lock is read off the ADR-0010 algebra. Holds.

• MetadataLockSchema is a plain z.enum of none, no-overlay, no-delete and full.
• evaluateLockForWrite refuses no-overlay and full. evaluateLockForDelete refuses no-delete and full.
• The four states map one-to-one onto the four (editable, deletable) pairs, so find always returns the one state whose verdicts equal the booleans.
• The spec's invariants therefore hold by construction: editable is false iff lock is no-overlay or full, and deletable is false iff lock is no-delete or full.
• lockReason, lockSource, lockDocsUrl and resettable pass through unchanged. That matches their declarations: "present only when declared", and "true iff artifact-backed".

The unreachable throw is sound. It can fire only if the algebra stops covering a pair, and then it fails loudly instead of publishing a lock that disagrees with the booleans.

• Non-blocking: the comment says a state added without an answer must fail here. In fact an added state gets null from both evaluators, matches none's pair, and find returns none first. So the throw guards a pair left uncovered, not an addition. Either way the published invariant cannot break.

Both reads call it.

• getMetaItem (line 9741) and getMetaItemLayered (line 10195) are the only two producers of editable / deletable / lock at the head.
• resolveLockState( has no other non-test caller in packages/. The runtime meta.ts mention is a comment, and the REST layered door spreads the protocol answer.
• No read exit publishing these flags is left unaligned.
• The diagnostics count (stats[type].locked) is a separate aggregate. It is filed in finding(metadata-protocol): two lock reports the #21670 read fix left unaligned — a host-config kernel's _lock gate admits a save the read now calls non-editable, and getMetaDiagnostics().stats[type].locked counts declared _lock only #21694 (see ③).

Published values are true to their doors. I checked against DEFAULT_METADATA_TYPE_REGISTRY at the head.

• The save door refuses when the item is artifact-backed and isOverlayAllowed is false: 23 types. The delete door adds the mergesOverlayAtRead carve-out, so it refuses 15 of them.
• 15 types read full / false / false. These are object, field, hook, seed, picklist, mapping, action, flow, job, datasource, external_catalog, api, doc, capability and agent. Each has allowOrgOverride false and supportsOverlay false, so both doors refuse.
• 8 types read no-overlay / false / true. These are page, app, dataset, book, permission, position, tool and skill. Each has allowOrgOverride false and supportsOverlay true, so save refuses and the A legacy env overlay on an artifact-backed item of a rolled-back type can no longer be REMOVED through the ordinary delete path (403) — only via OS_METADATA_WRITABLE #6960 overlay-removal repair is admitted.
• 5 overlay types are unchanged: view, dashboard, report, translation and email_template.
• 15 + 8 + 5 = 28, the registry roster.
• Org-owned items are unchanged. They are not artifact-backed, so packagedBaseRefusal answers null and the read is exactly resolveLockState as before.
• The OS_METADATA_WRITABLE hatch folds into isOverlayAllowed, so the read opens with the door, and a control pins this.

packages/spec change: wording only. Confirmed.

• In protocol.zod.ts, the expression lock: MetadataLockSchema.optional() is untouched. Only the .describe() string and the module-local TSDoc above MetadataProtectionEnvelopeFields change.
• No key, type, enum member, optionality or accept set moves. editable, deletable and resettable are byte-identical.
• The regenerated protocol.mdx line equals the concatenated new describe string. No other committed copy of the old sentence remains at the head.
• Spec property liveness and Build Docs are green.
• Non-blocking: the TSDoc says the _lock join produces all three verdicts, but resettable is not joined (it stays artifactBacked). It is imprecise, not false.

engine-double-contract.pinned.json: legitimate.

• The file is GENERATED, and it is the coverage ledger, which may only grow.
• The one added row is (protocol.read-lock-flags-write-door.test.ts, findOne, 1), in sorted position.
• The new test's findOne doubles route through assertEngineFindOnePredicate.
• It is additive, and no row is removed. The gate that owns this file (Lint & Repo Gates) is still in_progress.

The pin test: not weakened.

• 107 cases: 4 flow and action cases (2 kernels × 2 arms), 100 table rows (28 × 2 packaged, 22 × 2 org-owned), 1 lit control and 2 controls.
• It compares the read to the doors, never to the predicate.
  • On the environment kernel, the door is saveMetaItem / deleteMetaItem end to end. An admission counts only if the spied _lock gate was reached once and answered null.
  • On the host-config kernel, the door is SysMetadataRepository.put / delete. That is an independent implementation, and an admission must reach the engine.
  • Each row also asserts the spec algebra, and that the by-name read equals the layered read.
• Red first. The claimed 50 of 107 is consistent: 2 flow and action cases, 46 table rows (23 types × 2 kernels), the lit control's three-state set, and the _lock join control.
• Ablation. return declared; reproduces the same 50, and the fix is restored by its blob hash.
• Lit control:
  • the roster equals the registry, with a floor of 28;
  • refusals and admissions both appeared, for both verbs on both kernels;
  • all three lock states appeared.
• Non-blocking: the _lock controls run on the environment kernel only. That leaves the host-config _lock asymmetry out of the pin, consistently with its being filed separately rather than hidden.

② Semver level

Correct.

• @objectstack/metadata-protocol patch. A published read value is corrected to the refusal the server already enforces. No door, key or accept set changes.
• @objectstack/spec patch. Describe and TSDoc text only. No schema shape moves.
• Clause-②: no is right. The claim's own reasoning ("no accept set and no published key moves") holds at the head, and the stop condition (a spec shape that must change) was not met.
• The observable change is narrower. Clients gating affordances on editable / deletable now hide writes the server already answers with 403. That is a bug fix, and the changeset says so.
• Check Changeset is green. The changeset-no-major gate falls under Lint & Repo Gates, which is still in_progress.

③ Boundary flags

Stop valve: the seat's ruling A is upheld.

• The valve stops the dev only if the declared shape must change. It did not.
• The old describe ("refuse ... with 403 ITEM_LOCKED", "Resolved from the document's _lock") became false the moment the fix landed.
• Option B would publish a false field description for the time between landings. Option C would publish it indefinitely. Both contradict "declared is enforced".
• Keeping the wording edit in the same changeset is the correct reading.

Out-of-scope findings, filed as #21694 (open, bug, domain:engine). Both are carried accurately.

• The host-config _lock gate admits what the read calls non-editable. This is pre-existing: resolveLockState already reported the declared _lock before this PR. The read is stricter than the door, which is the safe direction, and no shipped producer exists. Not a blocker.
• getMetaDiagnostics().stats[type].locked counts declared _lock only. It is an aggregate and not the item envelope. Not a blocker.
• Nit: finding(metadata-protocol): two lock reports the #21670 read fix left unaligned — a host-config kernel's _lock gate admits a save the read now calls non-editable, and getMetaDiagnostics().stats[type].locked counts declared _lock only #21694's phrase "after PR fix(metadata-protocol): the read envelope's lock / editable / deletable report the write doors' locked-base verdict #21693, which reports the declared lock" reads as if this PR introduced finding 1. It did not.

Deviations.

• The file surface is wider than the claim. Three files are added beyond it:

  • packages/spec/src/api/protocol.zod.ts (describe and TSDoc);
  • content/docs/references/api/protocol.mdx (one generated line);
  • scripts/engine-double-contract.pinned.json (a gate-written row).

  Each is the mechanical consequence of the in-scope change: a describe made false, its generated twin, and the ledger row for the new double. None widens behaviour. The single-writer, same-issue, card-claims-branch and Governed Surface Queue Guard checks are green.

• The PR assignee was not set, because the auto-mode classifier refused it. That is the seat's housekeeping, not a contract matter.

• Not run by the dev: a live showcase boot, check:dual-build-cjs-loads and check:type-check-debt, all declared to CI. Type Check · debt ledger has since gone green, and Build Core is green.

• Main has moved since merge-base 7d0781482d. No commit on main touches the three code and ledger files in this diff.

Implemented-by: claude/issue-21670-layered-lock-flags
Reviewed-by: session_016tKoy8NJa35Yih1FdzrVmn

VERDICT: PASS