fix(objectql,metadata): derive a view container's object through the shared helper, so the row's own name is LAST at every SOURCE registrar (#14399)

The ObjectQL boot-loop registrar read a container's own `name` FIRST, while
`deriveViewContainerObject` (@objectstack/metadata) and
`expandRuntimeViewContainer` (@objectstack/metadata-protocol) read it LAST. A
container written as `{ name: 'lead_views', object: 'crm_lead', list: { … } }`
was therefore keyed `lead_views` by one SOURCE registrar and `crm_lead` by the
others, expansion included — and `getViewsByObject()` / `GET /meta/view?object=`
filter on the expanded items' `object`, so which registrar loaded the document
decided whether the views were addressable under the object at all.

The boot loop's container branch now calls `deriveViewContainerObject` by
import; a fourth hand-copy of the chain was the defect, not the repair.
`deriveViewContainerObject` moves onto `@objectstack/metadata`'s root entry to
make that import legal without reaching into another package's `src/`.

Only the CONTAINER branch moves, gated on `isAggregatedViewContainer`; the
assembled `viewItems:` channel still keys by its own `name` first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68

Author: claude

.changeset/view-container-object-derivation-name-last.md

@@ -0,0 +1,61 @@
+---
+"@objectstack/metadata": minor
+"@objectstack/objectql": patch
+---
+
+fix(objectql,metadata): the ObjectQL boot loop derives a view container's object through the shared `deriveViewContainerObject`, so the row's own `name` is the LAST term at every SOURCE registrar (#14399)
+
+Three sites derive "which object does an aggregated `defineView` container bind
+to". After #13407 / #13913 / #13912 all three read the container's own top-level
+`object` before the `list.data.object` chain, but they still disagreed about the
+row's own `name`:
+
+- `packages/objectql/src/engine.ts` `resolveMetadataItemName('views', item)` —
+  the boot-loop SOURCE registrar — read `name` FIRST, before `object`;
+- `deriveViewContainerObject` (`@objectstack/metadata`, used by the artifact/HMR
+  SOURCE registrar and by `getViewsByObject()`) and `expandRuntimeViewContainer`
+  (`@objectstack/metadata-protocol`, the runtime door) both read `name` LAST.
+
+A container written as `{ name: 'lead_views', object: 'crm_lead', list: { … } }`
+therefore registered under `lead_views` through the boot loop and under
+`crm_lead` everywhere else, with the whole expansion (`<object>.<key>`) carried
+along — and since `getViewsByObject()` / `GET /meta/view?object=` filter the
+expanded items by their `object`, which registrar loaded the document decided
+whether the views were addressable under the object at all. No error, no
+diagnostic.
+
+The boot loop's container branch now calls `deriveViewContainerObject` — by
+import, not by re-spelling: a fourth hand-copy of the chain was the defect, not
+the repair. The direction is the 2026-08-07 meta-rule rather than taste (one
+operation, two inconsistent implementations, the side bound by a DECLARATION
+wins): `ViewSchema.object`'s own `.describe()` names its readers, while the boot
+loop's order argued from item identity, which declares nothing about the
+binding. The two sites that already held the winning order are untouched.
+
+**`@objectstack/metadata` — new public export (`minor`).**
+`deriveViewContainerObject` was module-local; it is now on the package's root
+entry, because `packages/objectql` is a SOURCE registrar for the same containers
+and has to mint the same key. `packages/objectql` already declares
+`@objectstack/metadata` as a dependency and nothing in `packages/metadata`
+depends on `objectql`, so the import adds no cycle.
+
+**Scope of the behaviour change.** Only the `views` CONTAINER branch moves, gated
+on `isAggregatedViewContainer`: the assembled `viewItems:` channel (standalone
+ViewItems and flattened overlays, every member of `AssembledViewArtifactSchema`
+requiring `viewKind`) still keys by its own `name` first, which is its identity
+and not a binding. `item.id` is untouched and cannot fire for a container —
+`ViewSchema` is a `strictObject` declaring `name` and `object` and no `id`.
+
+**No migration surface.** No container in this repo carries a `name` that differs
+from its `object`, and none existed when the divergence was filed — every
+in-tree container derived identically at all three sites before this change and
+does after it. What moves is the latent shape only.
+
+⚠️ One card premise was measured false and is recorded in the new pin rather
+than quietly dropped: the artifact/HMR registrar does not silently mint a second
+key for a divergent container. It derives `crm_lead` correctly and then refuses
+the whole artifact load — `assertMetadataRegisterContract` (#7378 row 1),
+`VALIDATION_ERROR` / 400 — because the document's own `data.name` still reads
+`lead_views`. The boot loop reconciles that field and the artifact door does
+not; that residual asymmetry is a separate defect at a separate site and is
+filed as its own card.

packages/metadata/src/index.ts

@@ -39,6 +39,22 @@ export { YAMLSerializer } from './serializers/yaml-serializer.js';
 export * as Migration from './migration/index.js';
 export { TypeScriptSerializer } from './serializers/typescript-serializer.js';
 
+// View container binding
+//
+// [#14399] `deriveViewContainerObject` is this package's ONE spelling of "which
+// object does an aggregated `defineView` container bind to" — the container's
+// own top-level `object` first, then `list.data.object`, `form.data.object`,
+// and the row's own `name` last (its own docblock carries the ruling). It is
+// published here because the ObjectQL boot-loop registrar
+// (`packages/objectql/src/engine.ts`, `resolveMetadataItemName`) is a SOURCE
+// registrar for the same containers and has to mint the same registry key: it
+// used to consult the row's `name` FIRST, so a container whose `name` differs
+// from its `object` registered under two different keys depending on which
+// registrar loaded it. `packages/objectql` already declares this package as a
+// dependency and nothing here depends on it, so the import is the repair — a
+// fifth hand-copy of the chain is the defect, not the fix.
+export { deriveViewContainerObject } from './view-container-expansion.js';
+
 // Re-export types from spec
 export type {
   MetadataFormat,

packages/objectql/src/engine.ts

@@ -185,6 +185,11 @@ import {
   AssembledViewArtifactSchema,
   isViewContainerShaped,
 } from '@objectstack/spec';
+// [#14399] The ONE spelling of "which object does an aggregated `defineView`
+// container bind to", imported rather than re-spelled. See
+// `resolveMetadataItemName` below for why this registrar had a fourth copy and
+// why it lost it.
+import { deriveViewContainerObject } from '@objectstack/metadata';
 import { bindHooksToEngine } from './hook-binder.js';
 import { validateRecord, normalizeMultiValueFields, coerceBooleanFields, ValidationError, buildFieldError, resolveFieldLabel, valueShapePostureSetByEnv, mediaPostureSetByEnv, isScannableValueShapeField, valueShapeStrictEffective, mediaStrictEffective } from './validation/record-validator.js';
 import type { AdmittedValueShapeViolation, AdmittedValueShapeViolationSink } from './validation/record-validator.js';
@@ -2014,28 +2019,67 @@ const METADATA_ARRAY_KEYS = [
  *
  * Most metadata items expose a top-level `name` (or `id`). The `View`
  * container defined by `@objectstack/spec/ui` is special: it aggregates
- * `list / form / listViews / formViews` for a single object and is
- * keyed implicitly by its target object name (see `data.object`).
+ * `list / form / listViews / formViews` for a single object and is keyed by
+ * the OBJECT it binds to, not by its own row identity — which is what
+ * `/api/v1/meta/views/:object`, `getViewsByObject()` and
+ * `GET /meta/view?object=` all address it by.
  *
- * Per spec, `ViewSchema` does NOT have a top-level `name` field
- * (view.zod.ts), so we resolve it from the inner data source. This
- * matches the server-side metadata API contract (`/api/v1/meta/views/:object`).
+ * ⚠️ [#14399] The sentence that used to stand here — "per spec, `ViewSchema`
+ * does NOT have a top-level `name` field" — is measurably false and was the
+ * premise for consulting `item.name` first. `ViewSchema` declares an optional
+ * `name` (`view.zod.ts`), described there as "supplied by the metadata door;
+ * for an object-scoped container it is the object name". "Is the object name"
+ * is a CONVENTION the door does not enforce, so the two never actually had to
+ * agree — and where they disagreed, this registrar and the other two picked
+ * different keys for the same document.
  */
 function resolveMetadataItemName(key: string, item: any): string | undefined {
   if (!item) return undefined;
+  // [#14399] The aggregated `views` CONTAINER branch, taken FIRST and answered
+  // by the shared derivation. Everything below is unchanged.
+  //
+  // This registrar used to consult `item.name` before anything else, for every
+  // key including this one — so a container written as
+  // `{ name: 'lead_views', object: 'crm_lead', list: {…} }` registered under
+  // `lead_views` here while the artifact/HMR SOURCE registrar
+  // (`MetadataPlugin._parseAndRegisterArtifact`) and the runtime door
+  // (`expandRuntimeViewContainer`) both registered it under `crm_lead`. Same
+  // document, two source registrars, two registry keys and two sets of expanded
+  // item names, with `getViewsByObject()` / `GET /meta/view?object=` answering
+  // for the object only when the right registrar happened to load it.
+  //
+  // The 2026-08-07 meta-rule settles the direction rather than taste: one
+  // operation with two inconsistent implementations, the side bound by a
+  // DECLARATION wins. `ViewSchema.object`'s own `.describe()` names its readers
+  // (`getViewsByObject()` / `GET /meta/view?object=`); this loop's old order
+  // argued from item identity, which declares nothing about the binding. So the
+  // container branch adopts `deriveViewContainerObject` — by import, because a
+  // fourth hand-copy of a chain that already exists three times is the defect
+  // this repair exists to close, not the repair.
+  //
+  // The gate is `isAggregatedViewContainer`, which is what makes this the
+  // CONTAINER branch and nothing wider: it is false for every artifact carrying
+  // a `viewKind`, so the assembled `viewItems:` channel below (standalone
+  // ViewItems and flattened list/form overlays — every member of
+  // `AssembledViewArtifactSchema` requires `viewKind`) still resolves by its own
+  // `name` first, which is its identity and not a binding.
+  //
+  // `item.id` is untouched and stays reachable for every other key. It cannot
+  // fire for a spec-valid container: `ViewSchema` is a `strictObject` that
+  // declares `name` and `object` and no `id`, so an `id` on a container is
+  // refused at the authoring and metadata doors before this seam sees it.
+  if (key === 'views' && isAggregatedViewContainer(item)) {
+    return deriveViewContainerObject(item);
+  }
   if (item.name) return item.name;
   if (item.id) return item.id;
   if (key === 'views') {
-    // Independent ViewItems ("Object has-many View") carry a top-level `name`
-    // (handled above) and bind to their object via `object`. The aggregated
-    // container has no top-level name/object, so fall back to its inner data
-    // source — matching the loader's expansion key.
-    return (
-      item?.object ||
-      item?.list?.data?.object ||
-      item?.form?.data?.object ||
-      undefined
-    );
+    // A `views` entry that is NOT an aggregated container and carries neither
+    // `name` nor `id` — e.g. a flattened overlay whose optional `name` was
+    // omitted. Same derivation, and identical to the chain that used to be
+    // written out here: with `item.name` already known falsy, the helper's
+    // trailing `name` term contributes nothing.
+    return deriveViewContainerObject(item);
   }
   return undefined;
 }