fix(objectql,spec): rule the name argument as IMetadataService's effective key (#7378)

.changeset/metadata-facade-roundtrip-ruling.md

@@ -0,0 +1,45 @@
+---
+"@objectstack/objectql": patch
+"@objectstack/spec": patch
+---
+
+fix(objectql,spec): the `name` argument is `IMetadataService`'s effective key (#7378)
+
+`register(type, name, data)` → `get(type, name)` now holds on `MetadataFacade`
+for every `data`, which is what the other four measured implementations
+(`MetadataManager` with and without a writable loader, `createMemoryMetadata`,
+and the contract's own reference double) already did. Maintainer ruling of
+2026-08-11 on #7378, option (a): **the argument is the effective key and
+`data.name` never overrides it.**
+
+**Contract (`@objectstack/spec`).** `IMetadataService.register` and `.get` now
+state the rule instead of leaving it to the `@param` names — including for a
+`data` that is not an object and so has no `name` to derive, since `data` is
+declared `unknown`. `METADATA_ROUNDTRIP_CASES` gains an `array-data-roundtrips`
+row: an array passes a `typeof data === 'object'` guard, so a store that keys by
+spreading the document corrupts `[a, b]` into `{ 0: a, 1: b }` — the sibling of
+the primitive row's silent loss.
+
+**Behaviour change (`@objectstack/objectql`).** Two `MetadataFacade.register`
+paths that derived the storage key from the document now derive it from the
+argument:
+
+- a document whose own `name` (or `id`) disagreed with the `name` argument was
+  filed under the document's spelling, so `get`/`exists` missed it and
+  `listNames` reported the other name. It is now stored, read, listed and
+  unregistered under the argument, with the stored `name` reconciled to it.
+- a non-object `data` — a string, number, boolean, array or `null` — was
+  accepted with no throw and then filed under the literal key `undefined`,
+  readable back through no member of the class. It is now boxed as
+  `{ name, content }`, the shape this class's own reads already unwrap, and
+  round-trips unchanged.
+
+A host that relied on `MetadataFacade.register` keying by `data.name` or
+`data.id` rather than by the argument it passed will see items move to the
+argument's key. No in-tree caller does; the class reaches hosts only through the
+package's root and `core` exports.
+
+Not ruled and deliberately unchanged: the plural `objects` type alias (that
+alias is `SchemaRegistry`'s own read-side special-case, and its conformance pin
+stays a measured divergence with the escalation recorded on #7378), and the
+loud-refusal option (c), parked as a v18 strictness candidate.

packages/objectql/src/metadata-facade.ts

@@ -21,6 +21,51 @@ function isObjectType(type: string): boolean {
  */
 const RUNTIME_AUTHORED_PACKAGE_ID = 'sys_metadata';
 
+/**
+ * [#7378] Reconcile a `register(type, name, data)` payload to the key the
+ * contract says it is stored under: **the `name` ARGUMENT**.
+ *
+ * `IMetadataService.register` (`@objectstack/spec/contracts`) rules that the
+ * argument is the effective key and `data.name` never overrides it (maintainer
+ * ruling 2026-08-11 on #7378, option (a)). Every store this class writes into
+ * derives its key from the DOCUMENT — `SchemaRegistry.registerItem` reads
+ * `item[keyField]`, `registerObject` keys `objectContributors` on the schema's
+ * own `name` — so the only way to honour the argument here is to reconcile the
+ * document to it before either store sees it. Two shapes, one rule:
+ *
+ *  - **An object document** keeps every key it was authored with, with `name`
+ *    set to the argument. This is the same normalization
+ *    `ObjectQL.registerMetadataCollections` already applies on the plugin
+ *    ingest path (`item.name === itemName ? item : { ...item, name: itemName }`,
+ *    engine.ts), so a facade write and a plugin write agree about identity
+ *    rather than each keying on a different field. It is also the only
+ *    coherent answer for the `object` type specifically: an object's `name` IS
+ *    its identity to `getObject`, to the data plane and to every driver, so a
+ *    body whose `name` disagreed with its registry key would be dispatched on
+ *    under one spelling and addressable under the other.
+ *  - **Anything else** — a string, a number, a boolean, an array, `null` — is
+ *    boxed as `{ name, content }`. `data` is declared `unknown`, not `object`,
+ *    and a primitive has no `name` to key on: the previous code passed it
+ *    through untouched, `registerItem` read `item['name']` off a string, and
+ *    the value was filed under the literal key `undefined` — accepted with no
+ *    throw and readable back through no member of this class (#7378 cell 3).
+ *    The box is not a new convention: this class's own reads already unwrap it
+ *    (`get`/`list` return `item?.content ?? item`, `listNames` reads
+ *    `item?.name`), so the write half now produces exactly what the read half
+ *    was already prepared to consume. Arrays are boxed rather than spread for
+ *    the same reason — `{ ...[1, 2] }` is `{ 0: 1, 1: 2 }`, which is the same
+ *    silent corruption one shape over.
+ *
+ * ⛔ Not a ruling on the DISAGREEMENT itself. Refusing `data.name !== name`
+ * loudly (option (c)) is recorded on #7378 as the v18 strictness candidate and
+ * is deliberately NOT implemented here.
+ */
+function toKeyedDefinition(name: string, data: unknown): any {
+  return typeof data === 'object' && data !== null && !Array.isArray(data)
+    ? { ...(data as Record<string, unknown>), name }
+    : { name, content: data };
+}
+
 /**
  * MetadataFacade
  *
@@ -39,12 +84,15 @@ export class MetadataFacade {
   constructor(private registry: SchemaRegistry) {}
 
   /**
-   * Register a metadata item
+   * Register a metadata item under the `name` ARGUMENT.
+   *
+   * [#7378] The argument is the effective key and `data.name` never overrides
+   * it — the contract's ruling, and what {@link toKeyedDefinition} exists to
+   * honour against two document-keyed stores. Read that helper before changing
+   * either branch below.
    */
   async register(type: string, name: string, data: any): Promise<void> {
-    const definition = typeof data === 'object' && data !== null
-      ? { ...data, name: data.name ?? name }
-      : data;
+    const definition = toKeyedDefinition(name, data);
     // Pass through the item's own source package id (when stamped by an
     // artifact loader) so provenance survives re-registration. Never
     // synthesize one here — unstamped items are runtime-authored by
@@ -54,7 +102,12 @@ export class MetadataFacade {
     if (isObjectType(type)) {
       this.registerObjectBothPlaces(type, definition, packageId);
     } else {
-      this.registry.registerItem(type, definition, definition.id ? 'id' as any : 'name' as any, packageId);
+      // Always keyed on `name` — which {@link toKeyedDefinition} has just set
+      // to the argument. The former `definition.id ? 'id' : 'name'` keyField
+      // was the same defect as `data.name ?? name` one field over: a document
+      // carrying an `id` was filed under THAT, so `get(type, name)` missed it
+      // whenever the two disagreed (#7378).
+      this.registry.registerItem(type, definition, 'name' as any, packageId);
     }
   }