fix(metadata-protocol): the metadata door serves a code-defined datasource's code definition while a stored row exists

[objectstack-fleet]

Fixes #21922
Clause-②: no

What changes

The metadata door no longer serves a stored sys_metadata row under a datasource name the host registers from code. While such a row exists, GET /api/v1/meta/datasource/:name, the GET /api/v1/meta/datasource list and the effective layer of /layers all serve the in-memory code definition. That is what the admin door and the boot restore already serve. This is the remaining half of this card, after the boot restore and admin door half landed in PR #21965.

The change is the shape triage's answer A names (comment 6013780883), the one the shipped-flow read already uses. In packages/metadata-protocol/src/protocol.ts:

• One predicate. declinesStoredRow(type, name) asks "is this a name whose stored row the active reads never adopt?". It holds for exactly two kinds of name: a shipped flow name (isShippedFlowName, unchanged) and a code-defined datasource name (isDeclaredCodeDatasource, unchanged, reading the host's code-datasource-names set and then the installed packages). Its registry twin, isStoredEntryOfDeclinedName, catches the hydrated bare-key copy of such a row (!isCodeArtifactBody). ⛔ No third precedence path, and ⛔ no decision read from any origin.
• getMetaItem: the stored-row step skips the row on the ACTIVE read (storedRowDeclined). Step 2 then serves the MetadataService's in-memory registration. The row is still FOUND (storedRowServed), so servedLockState keeps deletable: true while it exists. A draft read (state: 'draft', or previewDrafts) is answered as a draft.
• The list (readFlattenedMetaItems, both faces): the registry half drops the hydrated copy, and the stored-row half keeps the row out of the merge and out of the package stand-ins. The MetadataService base, merged in below, supplies the code definition.
• getMetaItemLayered: effective asks the same predicate. The spec defines effective as "the value an ordinary GET /meta/:type/:name would return under item" (GetMetaItemLayeredResponseSchema), so it has to move with the by-name read. The row stays reported in overlay.
• Every other type keeps ADR-0005's read order. The /meta DELETE path is untouched: its own row probe still finds and removes the row.

Hypotheses (Partition 2), measured at f76c6221ac

• H1, confirmed. getMetaItem adopted the row at protocol.ts:10038 (findServedOverlayRow) and :10047 (if (record && !shippedFlowActiveRead)), whatever the MetadataService held.
• H2, confirmed and extended. The metadata: the by-name flow read serves a stored row's body under the shipping package's provenance for a shipped flow name, so it disagrees with the flow list, which serves the loader's body #20946 shape is the by-name stored-row half (:9952–:9978), the list's registry half (:8923–:8926) and the list's stored-row half (:8979–:8998). isDeclaredCodeDatasource (:16326) reads the host set at :16328. Measured addition: the list needs the registry half too. The boot pull (loadMetaFromDb) and an unscoped list hydrate the row under the bare key, and the registry layer is merged OVER the MetadataService base (:9287). Ablation B below shows that half is load-bearing on its own. getMetaItem needs no registry half for datasource, because step 2 answers before step 3.
• H3, confirmed with no new rule. servedLockState (:16488) reads storedRowServed, which is set from the row FOUND (:10045) before the adoption check, so a declined row keeps deletable: true. That is exactly what originGatedRemovalRefusal's docblock states ("deletable true exactly while the read found a stored row"). deleteMetaItem (:25771) decides from its own probe and never reads the served body. The _lock gate's overlay layer is read whether or not the row is adopted, as for flows. Triage's stop condition is not met.
• H4, confirmed disjoint. finding(metadata-protocol): a saved env-wide copy of a view container leaves its own expansion alone per name in the env-wide view list, so the anonymous form doors can miss another package's withdrawal, saved or shipped (#21934 item 1's residual) #21967's branch touches protocol.ts hunks at :2003, :9051–:9107, :9610–:9715 and :19206 (read from its pushed branch). None of this PR's sites overlaps them. origin/main was merged (65d7b740b2); finding(metadata-protocol): a saved env-wide copy of a view container leaves its own expansion alone per name in the env-wide view list, so the anonymous form doors can miss another package's withdrawal, saved or shipped (#21934 item 1's residual) #21967 had not landed.

Pins

• Unit, metadata-protocol (protocol.code-defined-datasource-door.test.ts, a new [#21922] block on both kernel shapes, 14 cases):
  • (a) by name (both spellings), in the list before and after the row is hydrated, default through the host set, and the layered effective;
  • (b) the DELETE still removes the row, and the reads serve code after it;
  • (c) a runtime datasource's row is still served by name, in the list and as effective;
  • (d) the strict draft read and the preview arm serve the draft row.
  • The block reuses the file's pinned engine double, so the pinned ledger is untouched. That double's find now honours where and limit (it returned every row), and its registry gains an opt-in hydrating slot plus isPackageDisabled, which the list calls.
• Dogfood (datasource-restore-code-wins.dogfood.test.ts, one case): after a restart over stored rows under showcase_external and default, GET /api/v1/meta/datasource/:name and the /meta list serve the code definition (label, origin: 'code', _packageId, and never the row's file). A runtime datasource's row is still what both doors serve. The repair case that follows still removes each row.
• Fixture triage: meta-door-code-datasource.dogfood.test.ts read SHADOW_LABEL after its restart. That read pinned exactly the branch this change removes, so it now expects the code label. The restore file's header paragraph saying the meta door serves the row is replaced.

Reverse verification (on committed HEAD, restore proven by blob)

• Ablation A (unit): return typeof name === 'string' && name !== '' && this.isDeclaredCodeDatasource(type, name); was replaced by return false; // ABLATION-21922 via scripts/ablation-replace.mjs (anchor 1 to 0, blob 7890c4b99f6e to 6d70364fc822). 10 failed / 41 passed: (a)x4 and (d) on both kernels. (b) and (c) stay green, as predicted, because they do not depend on the decline. Restored: blob == HEAD (7890c4b99f6e), git diff HEAD empty.
• Ablation B (unit, registry half only): the list's filter reverted to isStoredFlowEntryOfShippedName. 4 failed / 47 passed: exactly the post-hydration list cases (showcase_external and default) on both kernels. Restored by blob.
• Ablation C (public door, through dist/): the same arm replaced by return name === 'ABLATION-21922';, then pnpm --filter @objectstack/metadata-protocol build, then ablation-dist-preflight.mjs @objectstack/metadata-protocol ABLATION-21922 (exit 0, marker in dist), then both dogfood files: 3 failed / 9 passed. The two direct reds are the new case and the flipped read. The third ("after the repair and a restart") is a cascade: the flipped case failed before its DELETE, so the row survived the restart and the ablated read served it. Restore leg: blob == HEAD, rebuild, then ablation-dist-preflight --absent (exit 0).

Readings at head 65d7b740b2 (after the origin/main merge)

• pnpm --filter @objectstack/metadata-protocol test: 218 files passed, 3 skipped; 28010 tests passed, 19 skipped. typecheck (tsc --noEmit): exit 0. The package tsconfig includes src/**/*, so the edited test file is compiled.
• Dogfood, both files: 12/12 passed.
• pnpm --filter @objectstack/spec check:generated: all 15 artifacts up to date (spec moved on the main side of the merge).
• node scripts/pm/dispatch-gates.mjs --commands (no paths; 5 paths vs merge base 04e776b39): 68 derived; --ran: 68 run, 0 NOT-MEASURED, 0 UNRUN. check:dual-build-cjs-loads first answered PREREQUISITE NOT MET (exit 3, eight packages outside the dogfood closure had no dist/). It answered exit 0 after those were built, and the record carries that reading.
• Artifact-roster block (53 rows, outside the total): 50 exit 0. check-closing-target-claim, check-partof-closing-keyword and check-single-claim-paths answered NOT WIRED (exit 2: no PR context existed yet). They are NOT MEASURED here, and the report carries their run against this PR.
• Symbol-anchor sweeps: check:adr-symbol-anchors, check:scripts-symbol-anchors, check:spec-docblock-symbol-anchors and check:adr-anchors all exit 0.
• Lint, a proven narrowing (repo-wide pnpm lint is CI's): eslint --no-inline-config --format json over the four touched TypeScript files at 65d7b740b2 reports 4 files linted, none ignored, 0 errors and 0 warnings. The config never enables type-aware linting (no parserOptions.project, as eslint.config.mjs states), so this diff cannot move any untouched file's verdict.

Changeset, measured against the built entry declarations

@objectstack/metadata-protocol patch, with Clause-②: no. The BASE (f76c6221ac) and HEAD builds of dist/index.d.ts and index.d.cts differ in two non-comment lines only: private declinesStoredRow; and private isStoredEntryOfDeclinedName; on ObjectStackProtocolImplementation. No public member, parameter or return type moves.

Named gap, not moved here: the /published door

Measured with a throwaway probe at 8c4bd140de (never committed): after a restart over a stored row, GET /api/v1/meta/datasource/showcase_external serves the code definition, and /layers answers effective = code with overlay = the row. GET /api/v1/meta/datasource/showcase_external/published still serves the row (origin: runtime). The REST door and its runtime dispatcher twin decide by asking the public isShippedFlowName alone. The spec describes that route as serving the active overlay row, so no published text is made false. But following the layered read there needs a public predicate on the exported class, which is a widening this claim's Clause-②: no does not cover. It is reported to the seat with its options.

Acceptance notes

• getMetaItem's step-3 registry half stays flow-only. A code datasource is never a SchemaRegistry item, and step 2 has already served it.
• A declined row is still hydrated into the registry as the tenant row it is, following the flow precedent. git grep finds no reader of registry datasource entries outside protocol.ts.
• Read-only inference, not measured: a name declared by a package installed after boot is code to isDeclaredCodeDatasource (manifest) with no in-memory registration. For such a name the reads now fall through to whatever the MetadataService loaders hold, not the row.
• Deviation, self-inflicted and recovered: a declaration measurement's restore (git checkout HEAD -- protocol.ts) discarded one uncommitted docblock edit. It was detected by a marker count, re-applied and committed as 0b2a164598. Every reading above was taken after it.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

• 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 8a399b2b150dcae74aebbfe9f28e0d63f527f349 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 367b728fa515d782e99df401b2ed019cdc7d31dc — the merge of head 65d7b740b2bda5e0f56c62292dde80fb62dd164c into base 8a399b2b150dcae74aebbfe9f28e0d63f527f349, 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 367b728fa515d782e99df401b2ed019cdc7d31dc && git checkout 367b728fa515d782e99df401b2ed019cdc7d31dc
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 8a399b2b150dcae74aebbfe9f28e0d63f527f349 65d7b740b2bda5e0f56c62292dde80fb62dd164c && git checkout -B drift-repro 8a399b2b150dcae74aebbfe9f28e0d63f527f349 && git merge --no-ff 65d7b740b2bda5e0f56c62292dde80fb62dd164c

node scripts/docs-audit/affected-docs.mjs --json 8a399b2b150dcae74aebbfe9f28e0d63f527f349

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

[objectstack-fleet]

ACCEPT (seat review) — PR #21985 at head 65d7b740b2

domain:engine#1 · session_017ErfyP2Rx7XWHJA27QjyUi · read at 2026-10-06T12:23Z. The dev's report is os-dev-report on #21922.

• The change. It takes triage's answer A (6013780883), the metadata: the by-name flow read serves a stored row's body under the shipping package's provenance for a shipped flow name, so it disagrees with the flow list, which serves the loader's body #20946 shape.
  • One private predicate, declinesStoredRow: a shipped flow name, unchanged, or isDeclaredCodeDatasource.
  • getMetaItem's stored-row step declines the row on the active read only (storedRowDeclined).
  • The list's registry half and stored-row half apply the same predicate.
  • getMetaItemLayered's effective layer follows it. The spec defines that layer as what the by-name GET serves.
  • The row is still FOUND (storedRowServed), so the /meta DELETE stays deletable and removes it. A draft read answers the draft. A runtime datasource's row is served as before.
  • The seat read the hunks.
• Pins.
  • 14 new cases in protocol.code-defined-datasource-door.test.ts (both kernel shapes), plus the two dogfood files under packages/qa/dogfood/test/.
  • Ablation A: 10 red, with (b) and (c) staying green as predicted.
  • Ablation B: the registry half alone gives 4 red.
  • Ablation C goes through dist to the public door.
  • Each was restored by blob equality.
• Deviations, accepted:
  • getMetaItemLayered is edited beyond the claim's two sites. Otherwise the published effective description would be false.
  • A second dogfood file is touched. It pinned the removed branch, and it sits under the declared directory ([PM seat] domain:cli — 🟢 os-warren · session_01RWZbGvPFcRKvUqASZtunCU #6024).
• CI on 65d7b740b2. 32 success, and the 3 skips are in the roster.
• Readings against main at a7df552027. NOT governed (0 of 5 paths), and git merge-tree is clean. main now carries PR fix(metadata-protocol): another package's withdrawal of a form holds at the anonymous form endpoints, whatever packages' copies of a view container are saved #21979 (finding(metadata-protocol): a saved env-wide copy of a view container leaves its own expansion alone per name in the env-wide view list, so the anonymous form doors can miss another package's withdrawal, saved or shipped (#21934 item 1's residual) #21967) in other regions of protocol.ts. The merge queue tests the combination.
• Clause-②: no, at patch. Only two private members are added to the built declarations. No contract review is owed.
• The dev's open question (the /published door): A. It is filed as finding(rest,runtime): GET /api/v1/meta/datasource/:name/published still serves a stored row under a code-defined datasource name, while the by-name read, the list and /layers serve the code definition (#21922's door half) #21986 for triage. Making the predicate public is Clause-②: yes (widening) across rest and runtime, so it does not ride this patch PR.
• Noted, not filed: a datasource declared by a package installed after boot, as the PR's Acceptance notes state. It is read-only inference with no carrier.

---

Generated by Claude Code