fix(metadata-protocol)!: an item's lock is the strictest among the installed packages that ship its name (#21803)

[objectstack-fleet]

Fixes #21803
Clause-②: no (narrowing)

What changes

Two installed code packages may ship one (type, name) (ADR-0048 §3.4). The ADR-0010 _lock gate looked the packaged artifact up with no package, so it bound the first package registered. getMetaItem, getMetaItemLayered, the list and the getMetaDiagnostics tile looked it up with the request's package. So one item had two lock answers, and the door's answer depended on registration order. Measured on the real SchemaRegistry (H1 below), the defect runs in both directions:

• B ships _lock: 'full', A ships no lock, B registered first: a read naming A says none while the door refuses. This is the card's case: it fails closed.
• Same arrangement, A registered first: a read naming B says full while the door admits. This one fails open, because B's packaged lock is not enforced at all.

Now:

• One selection of the artifact layer. resolveArtifactLockLayer(address, artifactsOf) in packages/metadata-protocol/src/item-lock.ts returns the artifact of every installed package that ships the name, with the address's own package first and then the others by package id. The protocol's reader is shippedArtifactsOf, wrapped per address as artifactLockLayerAt. The gate's artifact limb, both reads, the list items and the diagnostics tile all take the layer there. No caller picks an artifact for the lock.
• The lock is the strictest per-package answer. resolveItemLock reads the layers once per shipping package: that package's artifact over the stored rows in scope, first binding layer wins, exactly the rule as before. The item's lock is the strictest of those answers. With one package shipping the name, or none, the answer is unchanged.
• Content stays prefer-local. A read naming A is still served A's artifact under A's provenance; only its lock family follows the binding package.
• The served body states the resolution's answer (withItemLockFamily, which replaces withOverlayLockFamily). That means the binding layer's lock family, and no _lock* key when nothing binds. This also settles the position folded in from 5988387087 (H6 below).
• The overlay rows are read lazily as before: only when some shipping package's artifact declares no lock, or no package ships the name.

Rulings honoured, and the one mechanism hypothesis falsified

• Triage's direction (5987395126, restated in 5987813232): strictest among the installed packages that ship the name, never a widening, one resolution for the gate and both reads, no prefer-local artifact lock at the door. All honoured.
• H3, taken literally, widens, so the route changed. The hypothesis was to make the artifact layer the strictest artifact, then keep "first binding layer wins". The BASE census shows a cell where that admits a save the door refused. A ships no lock, B ships no-delete, and the env-wide row declares no-overlay. With A registered first, the door at BASE refuses the save, because A's artifact does not bind and the row's no-overlay does. A strictest artifact layer would bind B's no-delete and admit it. So the resolution takes the strictest per-package answer instead. That is the ruling's own wording read per package, and its "never a widening" holds by construction: the artifact the gate bound before is always one of the shipping packages. That cell now refuses both verbs under both orders (pin 9).

H1: the artifact lookups at BASE c4d57131b5, on the real SchemaRegistry

B ships _lock: 'full', A ships no lock. Each call is listed with which package's artifact it bound.

order	request	gate (getEffectiveLock)	save / delete	getMetaItem = getMetaItemLayered	list slots	tile locked
B first	no package	B: full	refused / refused	B: full	B full, A none	1 of 2
B first	naming A	B: full	refused / refused	A: none	A none	0 of 1
B first	naming B	B: full	refused / refused	B: full	B full	1 of 1
A first	no package	A: none	admitted / admitted	A: none	A none, B full	1 of 2
A first	naming A	A: none	admitted / admitted	A: none	A none	0 of 1
A first	naming B	A: none	admitted / admitted	B: full	B full	1 of 1

The call sites:

• The gate's artifact limb (lookupArtifactItem(canonicalType, name)) binds the first package registered, whatever the request names.
• getMetaItem and getMetaItemLayered (lookupArtifactItem(type, name, packageId)) bind the named package's artifact, or the first registered when no package is named.
• The list items and the diagnostics tile (packageId ?? item._packageId) bind each slot's own package.
• mergeArtifactProtection put whatever its caller had looked up.

With B disabled, the gate bound B only when B was registered first, while a read naming A said none under both orders. After the change, every row above reads full with B's prose, is refused on both verbs, and keeps prefer-local content.

H2: what the registry enumerates

SchemaRegistry.getArtifactItem(type, name, packageId?) answers one entry: the asked package's own, else the first composite registered. The registry has no method that returns them all. The reader composes existing public methods only, so no new public surface:

• listItems(type), indexed by name, gives the packages whose entries ship each name. It hides a disabled package's entries.
• getAllPackages() plus isPackageDisabled(id) add the disabled packages, probed for every name.
• getArtifactItem(type, name, P) per candidate package, kept only when it is P's own (_packageId === P). Line 17607's view-expansion code already uses this idiom.
• The package-less getArtifactItem(type, name) is always in the set. It is the old gate's answer, and the only way to reach a plain-key artifact.
• An object has one owner (ADR-0029 D3), so its single owner-layer lookup is the whole set.
• A registry whose listing throws contributes no package ids, so the set falls back to the package-less lookup. That is never looser than the old gate (pinned by protocol.runtime-authoring-gate.test.ts).

H4: census, before and after, on the real SchemaRegistry

There are 2000 door verdicts, from A's lock (5 values) × B's lock (5) × the env-wide row (5) × registration order (2) × request shape (save naming none, A or B; delete naming none) × B enabled or disabled. Every verdict comes from the real gate (getEffectiveLock).

transition	cells
refused → admitted (widenings)	0
admitted → refused (narrowings)	416
unchanged	1584

Verdicts that depend on registration order: 416 of 1000 cell pairs before, 0 after. The narrowings split evenly, 26 per (enabled or disabled × order × shape × verb) group.

H5: the family's enumeration pin

protocol.lock-one-resolution.test.ts pin 1 is now the family's enumeration:

• Positions. Each position is a layer of ITEM_LOCK_LAYERS × a family axis (topology, organization, package), with the table axes that open it and the card that measured it.
• Completeness check, failing by name, when:
  • a layer × family axis has no position;
  • a position is opened by no slice;
  • an axis of the table belongs to no position;
  • an ITEM_ADDRESS_FIELDS field has no axis.
• Rows. The union of three slices, each a full product: 24 000 rows in all, each run under both stored-row orders and both registration orders.
  • The family product: PR fix(metadata-protocol)!: an item's lock is the strictest lock among the stored rows in scope for its address (#21761) #21801's 16 320 rows. It is checked against a frozen copy of their own titles, so no row is lost.
  • The artifact layer × package (7 200 rows): another installed package ships the name at each lock level, crossed with the package's own artifact, the env-wide row's lock, every request shape (no package, the package, the other package), both organization scopes, both topologies and both spellings.
  • The stored rows × organization × package (480 rows): the organization holds only another package's row.
• Every row asserts that both reads report the oracle's lock, that the door's verdict matches, that the door agrees with the envelope (bar the one declared spelling difference), and that a served body states the envelope's lock.
• Named pins:
  • pin 8, the card's case under both orders, for reads naming A, B or no package, plus the list and the tile;
  • pin 9, the never-widening join;
  • pin 10, a disabled package;
  • pin 11, the folded position.
• The same case runs on the real SchemaRegistry in packages/objectql/src/protocol-lock-artifact-package-axis.test.ts, because @objectstack/metadata-protocol cannot import objectql.

H6: the folded position (5988387087)

This is fixed without a ruling. Only the served body disagreed: the envelope and the door already agreed on none. withItemLockFamily writes the resolution's answer onto the body and removes any _lock* key the answer does not carry. Pin 11 covers it; the layered read still reports the stored layer as stored. Slice 3 of the pin carries the same position.

Reverse verification (one-shot, committed state)

• Gate limb. At 323ab0b07a, through scripts/ablation-replace.mjs in wrap mode, the gate's artifact limb was put back to the package-agnostic first artifact ([this.lookupArtifactItem(canonicalType, name)]). The anchor went 1 → 0 and the blob 182c6677 → c3840b80.
  • The pin file went 2506 red / 21538 green.
  • Pin 8 is red under "package A registered first" for all three request shapes, and green under "B registered first".
  • Also red: pin 9 (6), pin 10 (1), and 2496 rows of the artifact × package slice. Nothing red outside rows where another package ships the name.
  • Restored with git checkout HEAD -- PATH: the blob equals HEAD (182c6677) and git diff HEAD is empty.
• H6 body clearing. Ablated the same way: 14 red (the 12 slice-3 cells of the folded arrangement, plus pin 11 × 2). Restored, with git diff HEAD empty.

Tests

• pnpm --filter @objectstack/metadata-protocol test at 323ab0b07a: 214 files passed (3 skipped), 27 745 tests passed (19 skipped).
• objectql, the 30 test files that touch locks or read envelopes (the new one included), at 323ab0b07a: 940 passed. The real-registry file again at d1551fde71: 14 of 14 (the last commit only made its find double hold limit).
• typecheck for both packages at 323ab0b07a: clean. objectql's test layer (check:test-typecheck) compiles the new file, with no new debt.

Gates, at d1551fde71

• node scripts/pm/dispatch-gates.mjs --commands derived 74 commands, and the artifact-roster block printed 54 more outside that total. With the four symbol-anchor sweeps (check:adr-symbol-anchors, check:scripts-symbol-anchors, check:spec-docblock-symbol-anchors, check:adr-anchors) that makes 131 commands: 128 exit 0.
• 3 are NOT MEASURED locally (NOT WIRED: they need a pull request context): check-closing-target-claim, check-partof-closing-keyword and check-single-claim-paths. Their guard workflows run them on this PR.
• --ran reconciliation: 74 derived, 74 run, 0 NOT-MEASURED, 0 UNRUN, with every exit code recorded.
• check:engine-double-contract asked for one pin row for the new objectql double. It was recorded through its own --write.

Lint (a proven narrowing; the repo-wide pnpm lint is CI's run)

Run: eslint --no-inline-config --format json over the four touched TS files: 4 files, 0 errors, 0 warnings.

• Population. Read from eslint's own config: isPathIgnored is false for all four.
• Count. Read from the JSON output.
• Invariance. eslint.config.mjs never enables type-aware linting (no parserOptions.project, no typed rules), and its plugins are local per-file AST rules with no import resolution. The one removed export (withOverlayLockFamily) has zero remaining references. So this diff cannot move any untouched file's verdict.

Landing points

• packages/metadata-protocol/src/item-lock.ts and protocol.ts, as the claim's file surface said.
• The pin (protocol.lock-one-resolution.test.ts) and the changeset.
• Outside that surface:
  • packages/objectql/src/protocol-lock-artifact-package-axis.test.ts: the real-registry pin, since the protocol package cannot import objectql.
  • scripts/engine-double-contract.pinned.json: the gate's own --write.
• No packages/spec/src/**, no governed surface, no new public export: item-lock.ts is not re-exported from the package entry.

Acceptance notes

• packagedArtifactOwner (the ADR-0126 flow-owner classification) and isArtifactBacked still take the package-less first artifact. They classify owner and existence, not a lock: existence does not depend on order, but the reported owner of a flow name two packages ship is the first registered. This is not a lock-family position; noted, not filed. Carrier: none.
• A read can report a lock with no body served: content never serves another package's row, while the lock's scope includes it. The envelope and the door agree there, so the pin asserts the body only when one is served.
• A served body's lock family is now normalized through extractProtection. An explicit _lock: 'none' is no longer kept on a body, and a _lockSource outside the spec's enum is not echoed. The full metadata-protocol suite and the objectql envelope tests stay green.
• Cost: the list and the tile read the registry's listing once per type and probe only the packages that ship each name (commit f38762577c). The gate reads the listing once per write.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/api/error-catalog.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/api/index.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/automation/flows.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/concepts/metadata-lifecycle.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class), getMetaItemLayered (symbol, a method of class ObjectStackProtocolImplementation), sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/data-modeling/drivers.mdx (via getMetaItem (symbol, a method of class ObjectStackProtocolImplementation), sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/data-modeling/objects.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/deployment/cli.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/deployment/environment-variables.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/deployment/validating-metadata.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/kernel/cluster.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/kernel/contracts/metadata-service.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf), 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), sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/permissions/authorization.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/permissions/permission-sets.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/plugins/packages.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))

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

• content/docs/releases/implementation-status.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/releases/v16.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class), sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/releases/v17/17-0.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class), sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/releases/v17/17-1.mdx (via getMetaDiagnostics (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/releases/v17/17-3.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf), /:type/:name/published (route, bridged from symbol getMetaItemLayered — its route source's handler names it))
• content/docs/releases/v17/17-5.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))
• content/docs/releases/v17/17-6.mdx (via sys_metadata (literal, a string literal in shippingPackagesOf))

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

• 2 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 — 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 27991556788f1936c2ccae9aaed54996bac168b7 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 26da9bcb70d6e8d5fd4f68184b7e350e7fdc207f — the merge of head d1551fde71a93240fd98bc7e7eec6812dd9c9206 into base 27991556788f1936c2ccae9aaed54996bac168b7, 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 26da9bcb70d6e8d5fd4f68184b7e350e7fdc207f && git checkout 26da9bcb70d6e8d5fd4f68184b7e350e7fdc207f
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 27991556788f1936c2ccae9aaed54996bac168b7 d1551fde71a93240fd98bc7e7eec6812dd9c9206 && git checkout -B drift-repro 27991556788f1936c2ccae9aaed54996bac168b7 && git merge --no-ff d1551fde71a93240fd98bc7e7eec6812dd9c9206

node scripts/docs-audit/affected-docs.mjs --json 27991556788f1936c2ccae9aaed54996bac168b7

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

[objectstack-fleet]

ACCEPT (seat review) — PR #21844 at head d1551fde71

domain:engine#1 · session_017ErfyP2Rx7XWHJA27QjyUi · read at 2026-10-05T08:31Z. The os-dev report is on #21803 (5990899051). Judged against GitHub and the branch, not against the report.

• Shape: draft, base main, assignee os-project-manager.
  • The first lines are Fixes #21803 and Clause-②: no (narrowing).
  • The closing-keyword scan finds #21803 only.
• Scope: 6 files, +1151/-208: metadata-protocol's item-lock.ts and protocol.ts, the family pin, a real-registry twin in objectql, one engine-double-contract row (written by the gate's own --write), and the changeset.
  • NOT governed, and no packages/spec/src/** path.
  • item-lock.ts is not reached from the package entry: index.ts does not re-export it, and exports maps "." only. So renaming withOverlayLockFamily to withItemLockFamily moves no public surface.
  • Clause-②: no (narrowing) is right, and no contract review is owed.
• The diff, read: triage's direction (5987395126, restated by 5987813232).
  • shippedArtifactsOf enumerates every installed package that ships the name, a disabled one included, from existing registry methods. resolveArtifactLockLayer orders them: the request's package first, then by package id.
  • resolveItemLock takes, per shipping package, that package's artifact over the stored rows in scope: the first binding layer, as before. The item's lock is the strictest of those answers.
  • The artifact the door bound before is always one of those packages. So the result is never more permissive than the old door, by construction.
  • resolveItemLockLazily reads the stored rows only when some package's artifact does not bind.
  • Every lock caller takes it from artifactLockLayerAt: the _lock gate's artifact limb, getMetaItem, getMetaItemLayered, the list items and getMetaDiagnostics. ⛔ No prefer-local artifact lock at the door. Content stays prefer-local.
• H3 falsified, route switched within the ruling. Taken literally (the strictest artifact layer, then the first binding layer), H3 admits one cell the base door refused: A ships no lock, B ships no-delete, and the row declares no-overlay. The per-package rule closes it. "Never a widening" is the ruling's governing word, so this is the ruling applied.
• Measured on the real SchemaRegistry:
  • Of 2000 door cells, 0 widenings and 416 narrowings.
  • Order-dependent cell pairs fell from 416 of 1000 to 0 of 1000.
  • At the base, one arrangement failed open: A registered first, a save naming B was admitted while the read said full. That is closed now.
• The folded position (5988387087), fixed without a ruling. The envelope and the door already agreed. withItemLockFamily now writes the resolution's answer onto a served body and removes a _lock family nothing binds. The changeset states the visible effect: an explicit _lock: 'none' is no longer echoed on a body.
• Pins:
  • The family enumeration pin: 24000 rows over positions × slices, each under both stored-row orders and both registration orders. Completeness fails by name for a missing position, axis or address field. PR fix(metadata-protocol)!: an item's lock is the strictest lock among the stored rows in scope for its address (#21761) #21801's 16320 rows are kept, checked against their frozen titles.
  • Named pins 8 to 11.
  • objectql's real-registry twin: 14 tests.
• Reverse verification:
  • Restoring the gate's package-agnostic first artifact gave 2506 failed / 21538 passed. Pin 8 went red only under "package A registered first", and nothing went red outside rows where another package ships the name.
  • The H6 ablation turned exactly its 14 cells red.
  • Both restores were proved by blob equality and an empty git diff HEAD.
• Changeset, checked sentence by sentence:
  • minor, ! title, Clause-②: no (narrowing), ADR-0087 not-required (no-migration-prescription).
  • The three "what moves" bullets match H4's narrowing classes.
  • "No write the door refused before is admitted now" matches 0 of 2000.
  • The served-body paragraph matches pin 11.
• Evidence:
  • metadata-protocol: 27745 tests pass in 214 files.
  • The objectql envelope files pass: 940 tests in 30 files.
  • Both typechecks are green.
• Gates:
  • dispatch-gates --ran: 74 of 74 exit 0.
  • The roster and the four symbol-anchor sweeps pass.
  • check:objectql-double-limit was red on the first pass and green at d1551fde71, with the union re-run there.
• CI: read at landing.

Recorded, not filed: packagedArtifactOwner / isArtifactBacked still read the first registered artifact for a flow two packages ship. That is classification, and the door and the reads agree on it. It is in the PR's Acceptance notes.

Cross-lane: domain:services' #21789 holds its metadata-protocol half until this PR lands (5989615497, 5990896826).

---

Generated by Claude Code