fix(metadata-protocol): a package's list slot serves the stored row getMetaItem naming that package serves, in every row order (#21804)

[objectstack-fleet]

Fixes #21804
Clause-②: no

What changes

A package's slot in the metadata list now serves the stored row that getMetaItem naming that package serves, whatever order the store returns the rows in.

• One resolution, two readers. The order is one function, servedOverlayRowCandidates(address) in packages/metadata-protocol/src/protocol.ts. Its input is the address { organizationId, packageId }. It returns the ordered candidates { scope, organizationId, spelling, packageId }: the organization's scope, then env-wide (ADR-0005); within each, the canonical spelling, then the other (meta overlays: unnormalized type segment creates phantom rows that shadow the code-authored listing and cannot be deleted #4432); within each, the package's own row, then the package-less row, never another package's (ADR-0048). With no package, any row.
  • findServedOverlayRow (getMetaItem, its draft-preview arm, getMetaItemLayered) reads it from the store: one findOne per candidate, first hit served. This is the same findOne sequence as before, now spelled once.
  • mergePackageAwareOverlay reads it over the rows the list already holds (servedStoredRow). Each stored row travels into the merge with its place (stored: { organizationId, type }), and the caller passes rowsRead: { organizationId }. The list's active-overlay merge and its previewDrafts merge both pass them.
  • No second resolver: the list iterates the same candidate list; it does not restate the order.
• What stays. The lower layer (registry artifact) still loses to any stored row of the package or package-less. A package with no row of its own still falls back to the package-less row, stamped as the package's. The MetadataService merge, whose records are already-resolved items, keeps its latest-wins rule. The list item's lock still comes from resolveOverlayLockLayer ([finding] lock family, package axis: a read naming a package serves that package's row and reports its lock, while the _lock gate's overlay read selects without a package #21761); that block is untouched.
• Landing point, as the claim said: mergePackageAwareOverlay in readFlattenedMetaItems. StoredOverlayEntry gains type (the row's stored spelling). No packages/spec change.

H1: the two resolutions at the merge base (18c2ddc1ec)

• findServedOverlayRow: per scope (org, then env), per spelling, findOne with package_id = the package, then package_id = null. First hit served.
• mergePackageAwareOverlay: per slot and per package P, the LATEST contribution (registry items first, then the stored rows in row order) whose package is P or none. The stored rows come from readActiveOverlayRows: env rows, then the org's, merged by (package, name) with an org row replacing an env row in place. So "latest" depended on the store's order and on that map's insertion order.
• Slot body for package A, engine double, unscoped list, env-wide rows:
  • A's row and the package-less row, order [package-less, A]: A's row. Order [A, package-less]: the package-less row, stamped A. getMetaItem naming A: A's row in both orders.
  • Only A's row: A's row. Only the package-less row (under A's artifact): the package-less row, stamped A. Both agree with getMetaItem naming A.

Census: list slot vs getMetaItem, base vs this head

Engine double, view rows. 16 arrangements over five rows (env package-less, env A, env B, org package-less, org A, including no row, one row, both, and a third package), every row order, with and without A's artifact. Each case compares the list's slot for A with getMetaItem naming A.

list request	disagreements at 18c2ddc1ec	at this head
no package, no organization	39 / 120	0 / 120
organization	41 / 120	0 / 120
package A	5 / 120	5 / 120
organization + package A	20 / 120	20 / 120

The 25 that remain are all in a list scoped to one package. That is the row read, not this merge (Acceptance notes, first item).

H3: everything else in the list is unchanged

• Content dumps. Over those arrangements, orders and artifacts, with five list requests (no package, package A, package B, organization, organization + package A) and two getMetaItem requests per case: 840 dumps. Base vs head: 748 byte-identical, 92 differ.
  • All 92 are in the two unscoped lists (no package: 45, organization: 47).
  • Every one is a package slot moving to the row getMetaItem naming that package serves:
    • A: package-less → A's row, 42;
    • B: package-less → B's row, 12;
    • org package-less → org A, 26;
    • env package-less → org A, 6;
    • env A → org package-less, 6.
  • Outside package slots: 0 differences. Slot count changes: 0. getMetaItem dumps: 0 differences.
• Lock family. Same arrangements with every lock level on two of the rows: 4032 dumps of each list item's _lock family and each getMetaItem envelope. 4014 identical, 18 differ. All 18 are the organization list over [org package-less, env package-less, env A]. There the base list item stated env A's _lock (no-overlay, no-delete or full, 6 each) while the item's envelope said none, because the org's package-less row is the scope. At this head the list item says none. The envelopes are identical at base and head.
  • Across all 992 slot comparisons at this head, the list item's _lock equals getMetaItem's envelope lock (base: 18 disagree).
  • The lock is still selected by resolveOverlayLockLayer. What moved is the body it is laid over when no overlay row binds.

H4: organization scope

The organization's rows come before the env-wide rows, then the package's own row. The org list and getMetaItem with an organization agree in every order: 0 / 120 above, and pin 3.

Pins (protocol.list-slot-prefer-local.test.ts, 85 tests)

1. Generated: every subset of the five rows, every row order, with and without an organization, on dashboard (per-organization overridable, no list expansion of its own). For package A and package B, the list's slot serves the row an oracle written from the rule names, and getMetaItem naming the package serves the same row. A package with no row in scope has no slot.
2. A's row beside the package-less row, both env-wide, both orders, with and without A's artifact, on dashboard and view: the slot is A's row, listed once.
3. Organization scope, every order: the org's package-less row beats an env-wide row of A; the org's row of A beats the env-wide package-less row.
4. Control: only the package-less row, under A's artifact. The slot falls back to it, stamped A, as getMetaItem does. Lit control: the artifact alone is served as itself.
5. The draft preview: A's draft and a package-less draft, both orders. The previewed slot is A's draft, as getMetaItem with previewDrafts serves.

Reverse verification

• Committed first (5c7330e64b). The row-order pick was restored through scripts/ablation-replace.mjs (wrap mode, trap armed): the latest-wins loop back in place of the served-row call. Anchor 1 → 0, replacement 0 → 1, blob c3958342651e → 5261196669fb.
• The tests resolve ./protocol.js from src, so no dist was involved.
• Predicted, then measured on the pin file: 36 failed / 49 passed of 85.
  • Pin 2: red when A's row comes back first, green when the package-less row does, on both types and both artifact states (4 red / 4 green).
  • Pin 3, org package-less over env A: 3 red / 3 green. Pin 3, org A over env package-less: green in both orders (the org's rows are read after the env rows, so "latest" happened to coincide).
  • Pin 4: green. Pin 5: 1 red / 1 green. Pin 1: 28 red / 37 green.
• Restored with git checkout HEAD -- ABS_PATH (the tool, and the trap): blob after = blob at HEAD = c3958342651e; git diff HEAD empty.

Tests

At 978945aecd (after merging origin/main at 75ddcd1b41, which touches cloud-connection, metadata-core's protocol handshake and runtime; install refreshed and the workspace rebuilt):

• pnpm --filter @objectstack/metadata-protocol exec vitest run --maxWorkers=2: 214 files passed, 3 skipped; 20 037 tests passed, 19 skipped.
• pnpm --filter @objectstack/metadata-protocol typecheck: exit 0. tsc --listFiles includes the new test file.
• objectql, against the rebuilt metadata-protocol dist: the 20 test files that call getMetaItems, 343 tests passed.

Gates

All at 978945aecd, after the final commit.

• node scripts/pm/dispatch-gates.mjs --commands (no paths) derived 72 commands. All 72 ran, plus the 54-row artifact-roster block (53 beyond the derived set; check:engine-double-contract is in both) and the four symbol-anchor sweeps. 129 commands, 126 exit 0.
• dispatch-gates --ran: "72 derived famil(ies) accounted for — 72 run, 0 NOT-MEASURED (a DERIVED zero — all 72 recorded an exit code and none of them is 3)".
• The three non-zero results are roster gates that read a pull request, which a local run has none of (exit 2, not wired):
  • check-partof-closing-keyword: re-run with this body as PR_BODY;
  • check-closing-target-claim and check-single-claim-paths: NOT MEASURED locally (each needs a PR number and a token); their guard workflows run on this PR.
• Named readings:
  • check:engine-double-contract: OK, after recording the new pinned row through its own --write (740c063f1f).
  • check:durability-log-level, check:nul-bytes, check:dual-build-cjs-loads, check:lean-entry-closure, check:adr-0087-registration: green. The last three ran after the full build; the first pass at 5c7330e64b read PREREQUISITE NOT MET (exit 3) on the two build readers, and that pass is not counted.
  • The four symbol-anchor sweeps (check:adr-symbol-anchors, check:scripts-symbol-anchors, check:spec-docblock-symbol-anchors, check:adr-anchors): green.
• Lint, a proven narrowing.
  • Command: eslint --no-inline-config --format json over the 2 touched .ts files, at 978945aecd: 2 files, 0 errors, 0 warnings.
  • Population, read from eslint's own calculateConfigForFile / isPathIgnored: both are linted (neither ignored).
  • Invariance: no type-aware linting (parserOptions.project and projectService read null for both), so this diff cannot move any untouched file's verdict.
  • The repo-wide pnpm lint is CI's.
• NOT MEASURED here, CI's: Test Core shards beyond the two packages above; Temporal Conformance, Dogfood, Build Core; the workspace type-check lane.

Acceptance notes

• A list scoped to one package never falls back to the package-less row. getMetaItems({ type, packageId: A }) (GET /meta/:type?package=A) reads only A's rows (readActiveOverlayRows), so a package-less row never reaches the merge.
  • Under A's artifact with only the package-less row stored, that list serves A's artifact while getMetaItem naming A serves the package-less row.
  • With an org: the org's package-less row against an env row of A, the scoped org list serves env A while getMetaItem serves the org's package-less row.
  • These are the 25 census rows left. mergePackageAwareOverlay's docblock scopes its promise to the unscoped list, and ADR-0048 states no package-scoped list rule, so whether a package-filtered list should show package-less stand-ins is a semantics question. Unchanged here.
• view folds two packages' same-name slots into one. The list's view-container expansion (rest/meta: getViewsByObject / GET /meta/view?object= omits a runtime-authored view CONTAINER — #7163/#7736 expansion fix does not cover this path #13407) upserts every item by bare name, after the merge. With env rows of A and B for one view name, the unscoped list holds only B's. That is why pin 1 runs on dashboard. Measured on the engine double; not changed here.
• A served body can state a lock its envelope does not report. Engine double, at 18c2ddc1ec and at this head alike. The organization holds only package B's row; an env-wide row of A declares full. getMetaItem naming A in that organization answers lock: none, editable: true, and the served body (env A's row) carries _lock: full. The content scope and the lock scope ([finding] lock family, package axis: a read naming a package serves that package's row and reports its lock, while the _lock gate's overlay read selects without a package #21761) differ there, and withOverlayLockFamily leaves the body unchanged when no overlay row binds. Reported to the seat; not changed here.
• Spelling. The list's other-spelling fallback is per type and scope (readActiveOverlayRows), the by-name read's per item. The candidate order is shared; the list holds one spelling per scope, so the spelling step never splits a list slot. Unchanged.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

31 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 18c7dfd2e68cd2630420080b49a5f6a62fe60a6a.

⛔ 11 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 1 cross-cutting symbol(s) contributed no route anchor: organizationId (5 routes)
• 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 — 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 18c7dfd2e68cd2630420080b49a5f6a62fe60a6a → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 6cdf4411818e095fe62e046cecce51acc882be23 — the merge of head 978945aecdf8e6077ebddde9b04a6e6df0ae7fbc into base 18c7dfd2e68cd2630420080b49a5f6a62fe60a6a, 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 6cdf4411818e095fe62e046cecce51acc882be23 && git checkout 6cdf4411818e095fe62e046cecce51acc882be23
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 18c7dfd2e68cd2630420080b49a5f6a62fe60a6a 978945aecdf8e6077ebddde9b04a6e6df0ae7fbc && git checkout -B drift-repro 18c7dfd2e68cd2630420080b49a5f6a62fe60a6a && git merge --no-ff 978945aecdf8e6077ebddde9b04a6e6df0ae7fbc

node scripts/docs-audit/affected-docs.mjs --json 18c7dfd2e68cd2630420080b49a5f6a62fe60a6a

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

[objectstack-fleet]

ACCEPT (seat review) — PR #21815 at head 978945aecd

domain:engine#1 · session_017ErfyP2Rx7XWHJA27QjyUi · read at 2026-10-05T04:58Z. The os-dev report is on #21804 (5988348230). Judged against GitHub and the branch, not against the report.

• Shape: draft, base main, assignee os-project-manager.
  • The first lines are Fixes #21804 and Clause-②: no.
  • The closing-keyword scan finds #21804 only.
• Scope: 4 files, +494/-55: metadata-protocol's protocol.ts, the new pin file, one engine-double-contract row (written by the gate's own --write), and the changeset. NOT governed, and no packages/spec/src/** path. No export moves, so no is right and no contract review is owed.
• The diff, read: triage's direction (5987404976), as ruled.
  • servedOverlayRowCandidates(address) is the one candidate order: the organization's rows, then the env-wide rows; within each, the canonical spelling, then the other; within each, the package's own row, then the package-less row, never another package's.
  • findServedOverlayRow iterates it against the store. That is the same findOne sequence as before; I re-derived it against the base's inScope/lookup pair.
  • mergePackageAwareOverlay iterates it over the rows the list already holds (servedStoredRow). Each stored row now carries its organization and type spelling. It does so in the active merge and in the previewDrafts merge.
  • ⛔ No second resolver. The list item's lock still comes from resolveOverlayLockLayer (PR fix(metadata-protocol)!: an item's lock is the strictest lock among the stored rows in scope for its address (#21761) #21801).
• Measured:
  • List-versus-getMetaItem disagreements in the unscoped lists fell from 39/120 to 0/120 with no organization, and from 41/120 to 0/120 with one.
  • Of 840 content dumps, 92 moved. All of them are inside a package slot of an unscoped list, and each moved to the row getMetaItem naming that package serves. Nothing changed outside package slots, and no slot count changed.
  • 18 list lock-family dumps moved, each to agree with its envelope.
• Pins (protocol.list-slot-prefer-local.test.ts, 85 tests):
  • pin 1: a generated pin over 32 row subsets × 2 organization states, with a completeness check;
  • pin 2: both row orders on dashboard and view;
  • pin 3: organization scope (H4);
  • pin 4: the package-less fallback control;
  • pin 5: the previewDrafts merge.
• Reverse verification: from committed 5c7330e64b, the latest-wins loop was put back. It gave 36 failed / 49 passed: pin 2 red only under the package-row-first order, and pin 4 green. The restore was proved by blob equality and an empty git diff HEAD.
• Changeset, checked sentence by sentence:
  • patch for @objectstack/metadata-protocol, with Clause-②: no.
  • The candidate-order sentence matches servedOverlayRowCandidates.
  • The previewDrafts sentence matches pin 5, and the fallback sentence matches pin 4.
  • "the lock … is unchanged" matches the untouched resolveOverlayLockLayer.
  • "A list request scoped to one package … is unchanged" is true, and it is the subject of [finding] getMetaItems scoped to a package reads only that package's rows, so it never falls back to the package-less row that getMetaItem naming the package serves #21817 below.
• Evidence:
  • metadata-protocol: 20037 tests pass in 214 files.
  • objectql against the rebuilt dist: 343 tests pass in the 20 files that call getMetaItems.
  • The typecheck is green, and --listFiles compiles the new pin.
• Gates:
  • dispatch-gates --ran: 72 of 72 exit 0. The roster and the four symbol-anchor sweeps are green.
  • The two PR-context guards not measured locally are CI's on this PR.
• Deviations, read:
  • Pin 1 runs on dashboard, because view's container expansion folds same-name slots after the merge. Pin 2 covers view.
  • One command was refused by the dev session's safety check (a bash -c wrapper). The dev re-ran the ablation without the wrapper. The seat redid nothing.
• CI: read at landing.

Out-of-scope findings, carried by the seat:

• [finding] getMetaItems scoped to a package reads only that package's rows, so it never falls back to the package-less row that getMetaItem naming the package serves #21817 (filed): a list scoped to one package reads only that package's rows, so it never falls back to the package-less row that getMetaItem naming the package serves. That is 25 of 240 scoped comparisons. Triage is to rule whether it is a defect or a scope to state.
• Folded into [finding] lock family, artifact layer × package axis: the _lock gate looks up the packaged artifact with no package while both reads look it up with the request's package #21803 (5988387087), the lock family's closing card: a served body can carry an env row's _lock while the envelope reports the organization scope's none. This happens where the content scope and the lock scope part.
• Recorded, not filed: view's container expansion folds two packages' same-name slots. No real producer is named.

---

Generated by Claude Code