fix(metadata): read a view container's own object in the artifact/HMR loader

[os-musk]

Fixes #13912

MetadataPlugin._parseAndRegisterArtifact — the artifact/HMR loader, one of the two SOURCE view registrars — derives which object an aggregated defineView container binds to at two sites, and both walked exactly two levels, never consulting the container's own top-level object. That is the field ViewSchema.object documents as the authorial signal, in a .describe() that names its own readers: "Object this container binds to — how a stack-level views: [...] entry says which object its views belong to; read by getViewsByObject() / GET /meta/view?object=".

A package-shipped defineView({ object: 'crm_lead', list: { columns: [...] } }) therefore registered nothing at all through this path: the first site's if (!viewObject) continue dropped the container before any registration, so list('view') never returned it, the #13913 read backstop had nothing to expand, and getViewsByObject('crm_lead') / GET /meta/view?object=crm_lead answered empty for that object via this path. Restores declared = enforced; the accept set and the public surface are unchanged.

Both sites, before and after

packages/metadata/src/plugin.ts, the aggregated-container branch (was :933-936):

// before
const viewObject =
    (item as any)?.list?.data?.object
    ?? (item as any)?.form?.data?.object;
if (!viewObject) continue;

// after
const viewObject = deriveViewContainerObject(item);
if (!viewObject) continue;

packages/metadata/src/plugin.ts, the fall-through registrar (was :973-975):

// before
let name = (item as any)?.name;
if (!name) {
    if (metaType === 'view') {
        name =
            (item as any)?.list?.data?.object
            ?? (item as any)?.form?.data?.object;
    }
}

// after
let name = (item as any)?.name;
if (!name) {
    if (metaType === 'view') {
        name = deriveViewContainerObject(item);
    }
}

deriveViewContainerObject is object then list.data.object then form.data.object then the row's own name — the order #13407 settled at the runtime door. On the second site its last term is vacuous by construction: that branch is reached only when item.name is falsy, so what the call adds there is exactly the leading object term. On the first site the name term is new; it is what every sibling derivation already does, and no container in this repo reaches it (measured below).

Why a call and not a third local copy — the dependency-direction reading

Both packages' manifests, read from source:

• packages/metadata-protocol/package.json dependencies includes "@objectstack/metadata": "workspace:*".
• packages/metadata/package.json dependencies does not include @objectstack/metadata-protocol (it is core, metadata-core, metadata-fs, platform-objects, spec, types, plus chokidar/glob/js-yaml/zod).

So importing the protocol's expandRuntimeViewContainer into plugin.ts would invert an existing edge and close a cycle, and promoting that private method to a public export would widen metadata-protocol's surface while still being unreachable from here. No new cross-package export is proposed.

It turns out none is needed. packages/metadata/src/view-container-expansion.ts — landed with #13913, inside this package — already exports deriveViewContainerObject, and its header states the intent verbatim: the reusable substance is the derivation chain, "which is exactly the part that has silently drifted three ways (the ObjectQL boot loop keys off the registration name, plugin.ts walks two levels, and protocol.ts walks four since #13407). deriveViewContainerObject is the one spelling of it for this package, so the drift has a single place to be repaired rather than a third private copy to fall behind." Calling it is the repair that header was written for; restating the chain inline would have produced a fourth distinct order (object then list then form, no name), which is what the card's fence forbids.

Only the derivation is shared. Expansion, per-item applyProtection with the manifest's package coordinates, and the expansion-warning logging stay in plugin.ts — they differ from expandRuntimeViewContainer's container-provenance stamping and are this registrar's own contract.

protocol.ts reconciliation reading (triage's open question)

Triage (comment 5486856691) recorded two opposite orders inside packages/metadata-protocol/src/protocol.ts and asked the implementer to re-check whether #13929 settled it. Re-measured at origin/main 1dcb995f2:

Expansion path, expandRuntimeViewContainer (protocol.ts:13513):

const viewObject =
    (typeof container.object === 'string' && container.object ? container.object : undefined)
    ?? container?.list?.data?.object
    ?? container?.form?.data?.object
    ?? (typeof container.name === 'string' ? container.name : undefined);

Diagnostic path (protocol.ts:7514):

const sourceObject = viewDoc?.object
    ?? viewDoc?.data?.object
    ?? viewDoc?.objectName
    ?? viewDoc?.list?.data?.object;

Both are object-first, so the opposite-order defect triage flagged is reconciled — #13929 supplied the leading term the expansion path was missing. The tail terms still differ, and that is a difference of INPUT rather than of ordering: the diagnostic path reads a decorated served item (an expanded ViewItem, or an overlay row carrying data.object / objectName), the expansion path reads an aggregated container. Nothing filed for it, and protocol.ts is untouched here.

One residual divergence was found and is filed unassigned as #14399: the two SOURCE registrars put the row's own name in opposite positions — first in packages/objectql/src/engine.ts's resolveMetadataItemName, last in deriveViewContainerObject — so a container whose name is not its bound object expands under different keys depending on which registrar loaded it. Out of scope here, un-rehearsed in both directions, nothing shipped moves today.

Repro, controls and ablation

New pin: packages/metadata/src/plugin-artifact-view-container-object.test.ts. Every case drives the real door (_parseAndRegisterArtifact, shared by the boot artifact load and the HMR reload) with a bare ObjectStackDefinition, so each fixture also passes the door's strict parse.

That last point is load-bearing and was measured, not assumed: ObjectListViewSchema.data requires object when data is present at all, so a container carrying list: { data: { provider: 'object' } } with no object is refused by the door before this code runs (views.0.list.data.object: Invalid input: expected string, received undefined). The reachable failing shape is the natural one — the binding declared once at the top, with the view arms carrying no data at all — and that is what the fixture uses. A pin written on the refused shape would have been testing the schema, not this registrar.

• Repro — container with object: 'crm_lead' and no data.object anywhere: the container registers under crm_lead, the expansion crm_lead.default / crm_lead.hot / crm_lead.edit registers (4 items total), and getViewsByObject('crm_lead') answers with those three and never with the container itself ([finding] the nested-plugin seam does not expand an aggregated views container — a nested plugin's per-view items never reach the registry, so getViewsByObject() / GET /meta/view?object= answer with the container alone #7163).
• Ordering pin — a container setting BOTH object: 'crm_lead' and a disagreeing list.data.object: 'crm_account' registers under crm_lead, and nothing lands under crm_account. No container shipped in this repo sets both (measured: zero top-level object keys across all 13 defineView call sites in examples/, packages/lint and packages/qa), so nothing existing moves — the pin exists so the derivations cannot drift apart again.
• CONTROL — a container bound only through list.data.object still registers and expands unchanged.
• CONTROL — a container with no derivable binding at all (no object, no data.object, no name) is still skipped, and nothing is registered. The fix widens where a binding may be declared; it does not invent one.

Ablation (both derivation sites reverted to the pre-fix two-deep chain, run on the final HEAD 6f581cb60). Direction predicted before the run and matched exactly: 5 failed | 3 passed (8) — the five cases that depend on the container's own object go red, while the fixture premise guard and both CONTROLs stay green. The mutation was proved on disk before measuring (2 injected old-chain occurrences, 0 remaining deriveViewContainerObject(item) call sites, on-disk blob hash 67c8a807 differing from the HEAD blob 0b22c5f2), and the restore was proved after (on-disk hash back to 0b22c5f2, git diff HEAD empty). No rebuild leg is owed on either side: the pin imports ./plugin.js and plugin.ts imports ./view-container-expansion.js, both relative, and this package's vitest aliases redirect only @objectstack/core and @objectstack/spec to their own src — no dist is in the resolution path.

Verification

All of the following ran on 6f581cb60, the branch head after origin/main (1dcb995f2, PR #14340 included) was merged in.

• pnpm --filter @objectstack/metadata test — 42 files / 663 tests passed.
• pnpm --filter @objectstack/metadata-protocol --filter @objectstack/runtime run test (the two consumer packages that boot this door) — metadata-protocol 153 passed | 2 skipped, 2107 tests; runtime 207 files / 3061 tests passed.
• pnpm exec turbo run build --filter='./packages/*' --filter='./packages/*/*' — 70/70 successful.
• pnpm lint (repo-wide eslint . --no-inline-config, not narrowed) — exit 0.
• tsc --noEmit -p packages/metadata/tsconfig.json --listFiles: the new test file is in the program, and so is src/plugin.ts; 89 errors total, exactly the pre-existing count ([finding] @objectstack/metadata has no typecheck script, and its own tsconfig program does not compile: 89 pre-existing errors across 12 test files, checked by nothing #14342), none of them naming either file.
• The 36 gate families node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack derives for this diff, re-derived after the final commit with no paths passed: 34 green, and 2 reporting PREREQUISITE NOT MET (exit 3) rather than a finding — check-test-completeness.mjs (needs a saved turbo run test log CI tees; its own text says "the local reading for this gate is NOT MEASURED... it is not a red") and check-half-states.mjs (repo-scoped REST is 403 in this container; "nothing was swept"). Both readings are NOT MEASURED, not passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/ai/agents.mdx _(via crm_lead (literal, a string literal in parseAndRegisterArtifact))
• content/docs/api/client-sdk.mdx _(via crm_lead (literal, a string literal in parseAndRegisterArtifact))
• content/docs/api/error-catalog.mdx _(via crm_lead (literal, a string literal in parseAndRegisterArtifact))
• content/docs/data-modeling/index.mdx _(via crm_lead (literal, a string literal in parseAndRegisterArtifact))
• content/docs/deployment/validating-metadata.mdx _(via crm_lead (literal, a string literal in parseAndRegisterArtifact))
• content/docs/permissions/authorization.mdx _(via crm_lead (literal, a string literal in parseAndRegisterArtifact))
• content/docs/ui/index.mdx _(via crm_lead (literal, a string literal in parseAndRegisterArtifact))

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

• content/docs/releases/v13.mdx _(via crm_lead (literal, a string literal in parseAndRegisterArtifact))

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 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 12 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 5c9e40ad91028b57b0748e3ea0347189bac72ce9 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 5c9e40ad91028b57b0748e3ea0347189bac72ce9

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

[os-musk]

Enqueue provenance (domain:engine execution seat, session_0112hMx9hjJ9BgB28X97DS68): ACCEPT on #13912 (comment 5504343166) → at 04:43Z every check run on head 6f581cb60 was completed with success or skipped (33 runs; Lint & Repo Gates finished 04:41Z), governed-surface test on the three changed paths: NOT governed, mergeable_state not dirty → marked ready and auto-merge (squash) enabled. Landing is by the merge queue; the engine seat follows it to MERGED.

---

Generated by Claude Code