@metaobjectsdev/metadata 0.24.4 → 0.25.0

package/dist/naming.d.ts

@@ -1,4 +1,5 @@
 import type { MetaData } from "./shared/meta-data.js";
+import type { MetaSource } from "./persistence/source/meta-source.js";
 /**
  * Strip the package prefix from a metadata-qualified name
  * (e.g. "pkg::Name" → "Name"). Returns the input unchanged if no
@@ -22,8 +23,100 @@ export type ColumnNamingStrategy = "snake_case" | "literal" | "kebab-case";
 export declare const DEFAULT_COLUMN_NAMING_STRATEGY: ColumnNamingStrategy;
 export declare function applyColumnNamingStrategy(name: string, strategy: ColumnNamingStrategy): string;
 export declare function pluralize(s: string): string;
+/**
+ * THE `@role: primary` source lookup for this package — and the one place the
+ * primary-source DIVERGENCE refusal lives, so that every caller inherits it.
+ *
+ * Effective children (own + inherited via the super chain) so a TPH SUBTYPE —
+ * which declares no source of its own and inherits the discriminator base's
+ * single table (FR-017) — resolves to that base source rather than to nothing.
+ * For an entity declaring its own source, own shadows inherited, so the result
+ * is unchanged. Returns `undefined` when `entity` declares no primary source at
+ * all: #248, participation in persistence derives from a declared source, never
+ * from the object subtype, so an `object.value` and a sourceless
+ * `object.projection` both land here rather than being special-cased.
+ *
+ * `isMetaSource`, not `instanceof`: under two physical copies of this package a
+ * class check is false for a real primary source, and the failure is SILENT —
+ * the object reads as "not backed by any store".
+ *
+ * ## The refusal
+ *
+ * An object whose `@role: primary` sources resolve to MORE THAN ONE physical
+ * name has no single answer to give, so this throws rather than picking one.
+ * The shape loads with ZERO errors: `validateSourceRoles` enforces "exactly one
+ * primary" over `ownChildren()` only, and `_effectiveChildren` shadows an own
+ * child over a super child only on a (type, name) match — so two `source.rdb`
+ * nodes with DIFFERENT explicit names at two levels of an `extends` chain never
+ * collide, and both land on the child's effective `children()`.
+ *
+ * It lives HERE rather than in any one consumer because every consumer binds
+ * ONE name unconditionally. It used to live only in codegen-ts's
+ * `resolveObjectNames`, which runs only when the `names` generator is in the
+ * run — so with `namesFile()` unwired `meta migrate` emitted DDL against the
+ * PARENT's table (via `resolveTableName` → `buildExpectedSchema`) and
+ * `ObjectManager` read and wrote it, silently, on every run. A refusal that
+ * depends on which consumer asked is not a refusal. Mirrors Python's
+ * `source_resolution.primary_rdb_source`, whose codegen, api-docs and runtime
+ * callers all inherit it for free.
+ *
+ * DIRECTION-BLIND: it compares every primary against every other, so it does
+ * not matter which of them is writable nor which was declared first. Comparing
+ * against the first primary WRITABLE source can only see a divergence when one
+ * of the two is read-only — and, since `children()` places inherited entries
+ * first, only when the read-only one is the inherited one.
+ *
+ * Two primaries AGREEING on a name is not a divergence and stays legal: the
+ * invariant is that an object has ONE physical name, not that it declares one
+ * source. A read-only primary beside a non-primary REPLICA does not reach it
+ * either — a replica is not `role === "primary"`.
+ */
+export declare function primaryRdbSource(entity: MetaData): MetaSource | undefined;
 export declare function resolveTableName(entity: MetaData): string;
 export declare function resolveColumnName(field: MetaData, strategy?: ColumnNamingStrategy): string;
+/**
+ * An index's DATABASE name — for an `identity.secondary` (a unique alternate key) or an
+ * `index.lookup` (a non-unique retrieval index).
+ *
+ * These nodes carry no `@column`-style physical spelling: the database name IS the
+ * metamodel `name`. That is precisely why the answer must live in a function rather than
+ * at each call site. It was spelled independently in three places — the Drizzle emitter,
+ * migrate's expected-schema (twice) and the Kotlin Exposed emitter — and agreed only by
+ * coincidence; `fdb4118f1` is what that coincidence lapsing looks like, with codegen
+ * declaring `idx_<table>_<col>` while the index in the database was `identity.name`.
+ *
+ * Two rules the single door now owns, neither of which any call site had:
+ *
+ * - **Package qualifier stripped — and the reason first given for this was WRONG.** It was
+ *   justified here as compensating for the JVM loader package-qualifying a nested index
+ *   name (`acme::demo::by_name`), which `KotlinExposedTableGenerator` mirrored with
+ *   `shortName ?: name`. Measured against the real JVM loader, that does not happen: a
+ *   nested `identity.secondary` or `index.lookup` is named flat, including when inherited
+ *   across packages via `extends`. Only a ROOT-level node takes the file's package, and an
+ *   unnamed `view` child gets a synthesised FQN — the likeliest source of the belief. The
+ *   JVM's local strip had been a no-op for its whole life while reading as the site that
+ *   owned the rule. Pinned now on that side by `IndexNamingTest`.
+ *
+ *   The strip stays, on the honest reason rather than the invented one: it is a no-op on
+ *   every name either loader produces, which is what a rule that holds without a per-port
+ *   branch looks like, and it costs one `lastIndexOf`. A normalisation nobody has to
+ *   remember is worth more than a claim nobody checked.
+ * - **An empty name is REFUSED**, and the gap it closes is exactly one node type wide.
+ *   An `identity.secondary` with an empty name is already refused by the LOADER in strict
+ *   and lax mode alike (identity nodes carry an FR-024 name check so a dotted `extends`
+ *   ref can address them). An `index.lookup` is not addressable that way and carries no
+ *   such check, so `{"index.lookup": {"name": ""}}` loads with zero errors in both modes
+ *   and reaches the emitters, which produce `index("")`: SQL no engine accepts, from a
+ *   model that passed every gate. Refusing at the shared door closes it for codegen and
+ *   migrate at once, without touching the byte-gated registry `rules` prose a loader-side
+ *   fix would need. Measured, not assumed — `resolve-index-name.test.ts` asserts both
+ *   arms, because "the loader already handles it" is the belief that would delete this.
+ */
+export declare function resolveIndexName(node: {
+    readonly name: string;
+    readonly type: string;
+    readonly subType: string;
+}): string;
 /**
  * Returns the DB schema declared on an entity's primary source child, or undefined
  * when no @schema attr is set or no source child exists. @schema is paradigm-agnostic

package/dist/naming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAiBtD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI7D;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK7C;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,SAAS,GAAG,YAAY,CAAC;AAE3E,sDAAsD;AACtD,eAAO,MAAM,8BAA8B,EAAE,oBAAmC,CAAC;AAEjF,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAM9F;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3C;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAiBzD;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,QAAQ,EACf,QAAQ,GAAE,oBAAqD,GAC9D,MAAM,CAKR;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAUvE;AAED,2GAA2G;AAC3G,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,QAAQ,EAChB,QAAQ,GAAE,oBAAqD,GAC9D,aAAa,CAYf"}
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAQtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAWtE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAI7D;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK7C;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,SAAS,GAAG,YAAY,CAAC;AAE3E,sDAAsD;AACtD,eAAO,MAAM,8BAA8B,EAAE,oBAAmC,CAAC;AAEjF,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAM9F;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAgBzE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CASzD;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,QAAQ,EACf,QAAQ,GAAE,oBAAqD,GAC9D,MAAM,CAKR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,gBAAgB,CAK9B,IAAI,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/E,MAAM,CASR;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAWvE;AAED,2GAA2G;AAC3G,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,QAAQ,EAChB,QAAQ,GAAE,oBAAqD,GAC9D,aAAa,CAYf"}

package/dist/naming.js

@@ -2,13 +2,15 @@ import { TYPE_FIELD } from "./shared/base-types.js";
 import { PACKAGE_SEPARATOR } from "./shared/structural.js";
 import { FIELD_ATTR_COLUMN } from "./persistence/db/db-constants.js";
 import { SOURCE_ATTR_SCHEMA, SOURCE_ROLE_PRIMARY, } from "./persistence/source/source-constants.js";
-// isMetaSource, not `instanceof`: unlike the loader-internal validators, these two
-// are EXPORTED helpers that run on a caller-supplied node — migrate-ts calls both
-// on nodes the CLI's loader built. Under a split @metaobjectsdev/metadata tree the
-// class check would be false for a real primary source, and resolveTableName would
-// silently fall through to the entity-name fallback: a DIFFERENT table name, which
-// migrate then emits as a rename against a live database.
+// isMetaSource, not `instanceof`: unlike the loader-internal validators, the source
+// lookups below are EXPORTED helpers that run on a caller-supplied node — migrate-ts
+// calls them on nodes the CLI's loader built. Under a split @metaobjectsdev/metadata
+// tree the class check would be false for a real primary source, and resolveTableName
+// would silently fall through to the entity-name fallback: a DIFFERENT table name,
+// which migrate then emits as a rename against a live database. (The same split would
+// also make the divergence refusal see no primaries at all, and say nothing.)
 import { isMetaSource } from "./shared/node-guards.js";
+import { MetaModelError } from "./errors.js";
 /**
  * Strip the package prefix from a metadata-qualified name
  * (e.g. "pkg::Name" → "Name"). Returns the input unchanged if no
@@ -47,19 +49,75 @@ export function pluralize(s) {
         return s.slice(0, -1) + "ies";
     return s + "s";
 }
+/**
+ * THE `@role: primary` source lookup for this package — and the one place the
+ * primary-source DIVERGENCE refusal lives, so that every caller inherits it.
+ *
+ * Effective children (own + inherited via the super chain) so a TPH SUBTYPE —
+ * which declares no source of its own and inherits the discriminator base's
+ * single table (FR-017) — resolves to that base source rather than to nothing.
+ * For an entity declaring its own source, own shadows inherited, so the result
+ * is unchanged. Returns `undefined` when `entity` declares no primary source at
+ * all: #248, participation in persistence derives from a declared source, never
+ * from the object subtype, so an `object.value` and a sourceless
+ * `object.projection` both land here rather than being special-cased.
+ *
+ * `isMetaSource`, not `instanceof`: under two physical copies of this package a
+ * class check is false for a real primary source, and the failure is SILENT —
+ * the object reads as "not backed by any store".
+ *
+ * ## The refusal
+ *
+ * An object whose `@role: primary` sources resolve to MORE THAN ONE physical
+ * name has no single answer to give, so this throws rather than picking one.
+ * The shape loads with ZERO errors: `validateSourceRoles` enforces "exactly one
+ * primary" over `ownChildren()` only, and `_effectiveChildren` shadows an own
+ * child over a super child only on a (type, name) match — so two `source.rdb`
+ * nodes with DIFFERENT explicit names at two levels of an `extends` chain never
+ * collide, and both land on the child's effective `children()`.
+ *
+ * It lives HERE rather than in any one consumer because every consumer binds
+ * ONE name unconditionally. It used to live only in codegen-ts's
+ * `resolveObjectNames`, which runs only when the `names` generator is in the
+ * run — so with `namesFile()` unwired `meta migrate` emitted DDL against the
+ * PARENT's table (via `resolveTableName` → `buildExpectedSchema`) and
+ * `ObjectManager` read and wrote it, silently, on every run. A refusal that
+ * depends on which consumer asked is not a refusal. Mirrors Python's
+ * `source_resolution.primary_rdb_source`, whose codegen, api-docs and runtime
+ * callers all inherit it for free.
+ *
+ * DIRECTION-BLIND: it compares every primary against every other, so it does
+ * not matter which of them is writable nor which was declared first. Comparing
+ * against the first primary WRITABLE source can only see a divergence when one
+ * of the two is read-only — and, since `children()` places inherited entries
+ * first, only when the read-only one is the inherited one.
+ *
+ * Two primaries AGREEING on a name is not a divergence and stays legal: the
+ * invariant is that an object has ONE physical name, not that it declares one
+ * source. A read-only primary beside a non-primary REPLICA does not reach it
+ * either — a replica is not `role === "primary"`.
+ */
+export function primaryRdbSource(entity) {
+    const primaries = entity.children().filter((c) => isMetaSource(c) && c.role === SOURCE_ROLE_PRIMARY);
+    if (primaries.length === 0)
+        return undefined;
+    const distinct = [...new Set(primaries.map((s) => s.physicalName))].sort();
+    if (distinct.length > 1) {
+        // Sorted, so the message is identical in every port regardless of children() order.
+        const joined = distinct.map((n) => `"${n}"`).join(", ");
+        throw new MetaModelError(`${entity.name}: role=primary sources disagree on the object's physical name — ` +
+            `${joined}. Every consumer binds ONE name. Give them matching physical names, ` +
+            `or drop the extra role=primary declaration.`);
+    }
+    return primaries[0];
+}
 export function resolveTableName(entity) {
     // FR-016: primary source's `physicalName` implements the four-step rule
     // (kind-matching alias → legacy @table → source.name → entity-name fallback),
     // so this helper now just delegates. Writability (table vs view/storedProc/
     // tableFunction) only affects write-routing — for SELECT-side name resolution,
     // a read-only primary source is the right answer.
-    //
-    // Effective children (own + inherited via the super chain) so a TPH SUBTYPE
-    // — which declares no source of its own and inherits the discriminator base's
-    // single table (FR-017) — resolves to that base table rather than the
-    // entity-name fallback. For an entity declaring its own source, own shadows
-    // inherited, so the result is unchanged.
-    const source = entity.children().find((c) => isMetaSource(c) && c.role === SOURCE_ROLE_PRIMARY);
+    const source = primaryRdbSource(entity);
     if (source !== undefined)
         return source.physicalName;
     return pluralize(toSnakeCase(entity.name));
@@ -71,6 +129,57 @@ export function resolveColumnName(field, strategy = DEFAULT_COLUMN_NAMING_STRATE
         return col;
     return applyColumnNamingStrategy(field.name, strategy);
 }
+/**
+ * An index's DATABASE name — for an `identity.secondary` (a unique alternate key) or an
+ * `index.lookup` (a non-unique retrieval index).
+ *
+ * These nodes carry no `@column`-style physical spelling: the database name IS the
+ * metamodel `name`. That is precisely why the answer must live in a function rather than
+ * at each call site. It was spelled independently in three places — the Drizzle emitter,
+ * migrate's expected-schema (twice) and the Kotlin Exposed emitter — and agreed only by
+ * coincidence; `fdb4118f1` is what that coincidence lapsing looks like, with codegen
+ * declaring `idx_<table>_<col>` while the index in the database was `identity.name`.
+ *
+ * Two rules the single door now owns, neither of which any call site had:
+ *
+ * - **Package qualifier stripped — and the reason first given for this was WRONG.** It was
+ *   justified here as compensating for the JVM loader package-qualifying a nested index
+ *   name (`acme::demo::by_name`), which `KotlinExposedTableGenerator` mirrored with
+ *   `shortName ?: name`. Measured against the real JVM loader, that does not happen: a
+ *   nested `identity.secondary` or `index.lookup` is named flat, including when inherited
+ *   across packages via `extends`. Only a ROOT-level node takes the file's package, and an
+ *   unnamed `view` child gets a synthesised FQN — the likeliest source of the belief. The
+ *   JVM's local strip had been a no-op for its whole life while reading as the site that
+ *   owned the rule. Pinned now on that side by `IndexNamingTest`.
+ *
+ *   The strip stays, on the honest reason rather than the invented one: it is a no-op on
+ *   every name either loader produces, which is what a rule that holds without a per-port
+ *   branch looks like, and it costs one `lastIndexOf`. A normalisation nobody has to
+ *   remember is worth more than a claim nobody checked.
+ * - **An empty name is REFUSED**, and the gap it closes is exactly one node type wide.
+ *   An `identity.secondary` with an empty name is already refused by the LOADER in strict
+ *   and lax mode alike (identity nodes carry an FR-024 name check so a dotted `extends`
+ *   ref can address them). An `index.lookup` is not addressable that way and carries no
+ *   such check, so `{"index.lookup": {"name": ""}}` loads with zero errors in both modes
+ *   and reaches the emitters, which produce `index("")`: SQL no engine accepts, from a
+ *   model that passed every gate. Refusing at the shared door closes it for codegen and
+ *   migrate at once, without touching the byte-gated registry `rules` prose a loader-side
+ *   fix would need. Measured, not assumed — `resolve-index-name.test.ts` asserts both
+ *   arms, because "the loader already handles it" is the belief that would delete this.
+ */
+export function resolveIndexName(
+// The narrow structural shape rather than `MetaData`: this reads three properties, and
+// every caller that has a real node satisfies it, while the Drizzle emitter's local
+// duck-typed index node does not need a cast to pass one. A cast here would be the
+// usual way a `never` slips past the compiler into a runtime property read.
+node) {
+    const short = stripPackage(node.name);
+    if (short === "") {
+        throw new MetaModelError(`${node.type}.${node.subType} declares an empty name; an index's database name IS ` +
+            `its metamodel name, so there is nothing to emit. Give it a name.`);
+    }
+    return short;
+}
 /**
  * Returns the DB schema declared on an entity's primary source child, or undefined
  * when no @schema attr is set or no source child exists. @schema is paradigm-agnostic
@@ -80,7 +189,10 @@ export function resolveColumnName(field, strategy = DEFAULT_COLUMN_NAMING_STRATE
  */
 export function resolveTableSchema(entity) {
     // ADR-0039: resolving — a concrete entity may inherit its source.rdb via extends.
-    const source = entity.children().find((c) => isMetaSource(c) && c.role === SOURCE_ROLE_PRIMARY);
+    // primaryRdbSource, not a second hand-rolled scan: a lookup written twice is a
+    // lookup that can disagree with itself, and only one of the two copies would
+    // carry the divergence refusal.
+    const source = primaryRdbSource(entity);
     if (!source)
         return undefined;
     // ADR-0039: resolving — an inherited source's @schema lives on the super node.

package/dist/naming.js.map

@@ -1 +1 @@
-{"version":3,"file":"naming.js","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"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"}

package/dist/parser-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser-core.d.ts","sourceRoot":"","sources":["../src/parser-core.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAU,YAAY,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAkB,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,aAAa,EAAoB,MAAM,aAAa,CAAC;AAyCrG,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB;;;;;;OAMG;IACH,gBAAgB,EAAE,aAAa,EAAE,CAAC;CACnC;AAYD,wBAAgB,SAAS,IAAI,WAAW,CAuBvC;AAwMD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,GAAG,WAAW,CAmJ1E"}
+{"version":3,"file":"parser-core.d.ts","sourceRoot":"","sources":["../src/parser-core.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAU,YAAY,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAkB,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,aAAa,EAAoB,MAAM,aAAa,CAAC;AAyCrG,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB;;;;;;OAMG;IACH,gBAAgB,EAAE,aAAa,EAAE,CAAC;CACnC;AAYD,wBAAgB,SAAS,IAAI,WAAW,CAuBvC;AA6QD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,GAAG,WAAW,CAiL1E"}

package/dist/parser-core.js

@@ -28,7 +28,7 @@ import { MetaAttr } from "./core/attr/meta-attr.js";
 import { canonicalSerialize, inferAttrSubType } from "./serializer-json.js";
 import { ParseError } from "./errors.js";
 // #337 — see retired-vocabulary.ts. Diagnostic only; no load outcome changes.
-import { retiredSubType, retirementHint } from "./retired-vocabulary.js";
+import { retiredSubType, retirementHint, retirementSuggestions } from "./retired-vocabulary.js";
 import { resolvedSource } from "./source.js";
 import { semanticDiff } from "./semantic-diff.js";
 import { resolveSuperRef, isChildTargetingRef, extendsTargetCompatible, EXTENDS_TARGET_MISMATCH_RULE, } from "./super-resolve.js";
@@ -112,19 +112,82 @@ function guardRelativeRefInCanonical(refLabel, rawValue, strict, warnings, path)
         warnings.push(msg);
     }
 }
+// ---------------------------------------------------------------------------
+// The one message for an authored `<type>.base`, so both doors say the same thing.
+//
+// Every registered `base` subtype is an ABSTRACT REGISTRY ANCHOR: the shared root that
+// concrete subtypes inherit their attrs and child rules from. It has no runtime semantics
+// and no concrete representation — `spec/metamodel/object.json` says so in as many words
+// ("Has no runtime semantics of its own; not authored directly"), and every `base` entry's
+// description opens with "Abstract".
+//
+// The JVM enforced this by accident (its impl classes are `public abstract`, so
+// instantiation fails); TypeScript, C# and Python accepted it. The same document therefore
+// loaded on three ports and failed to load on two — the cross-port conformance gap the
+// corpora exist to catch, and it survived because every `*.base` subtype sits in the
+// registry corpus's own `untestedSubTypes` list.
+/**
+ * Is `<type>.base` an ABSTRACT ANCHOR for this type — i.e. does the type register at least one
+ * OTHER subtype for it to anchor?
+ *
+ * Registry-driven, not name-driven, and the distinction is load-bearing. All ten core anchors
+ * have concrete siblings (`object.base` beside entity/value/projection, `source.base` beside
+ * rdb, …), so the rule catches every one. A third-party provider may register `base` as a
+ * type's ONLY member — the SDK's forge `convention`/`glossary`/`failure` do — and there it is
+ * not anchoring anything: refusing it would leave the type unauthorable, which is a
+ * capability removal the contract never asked for. The manifest describes the CORE registry;
+ * this predicate is how that scope is expressed without hardcoding the core's type list.
+ */
+function isAbstractAnchorFor(type, registry) {
+    return registry.allSubTypesOf(type).some((sub) => sub !== SUBTYPE_BASE);
+}
+function abstractSubtypeMessage(type) {
+    return (`"${type}.${SUBTYPE_BASE}" may not be authored — every "${SUBTYPE_BASE}" subtype is an ` +
+        `abstract registry anchor that concrete subtypes inherit from, with no runtime ` +
+        `semantics of its own. Declare a concrete ${type} subtype instead.`);
+}
+// The same rule reached by the OTHER spelling: a BARE wrapper key (`{"field": …}`, no fused
+// subType) whose registry default resolves to the abstract anchor. The author did not type
+// `.base`, so this is a MISSING subtype rather than an authored-anchor error — and
+// ERR_MISSING_SUBTYPE is the shared code already chartered for it ("a node omits subType and
+// the type has no default subType").
+//
+// Python has always emitted it here; TypeScript, C# and the JVM did not, so a bare key was a
+// SECOND way one document got two verdicts: TS and C# resolved it to the anchor and loaded,
+// the JVM resolved it identically and then failed to instantiate with a message naming a
+// missing constructor. Closing the authored spelling alone would have left the rule half
+// true, reachable by dropping four characters.
+//
+// Scoped to "the default IS the anchor", never to bare keys as such: a type that declares a
+// CONCRETE default keeps resolving through it, which is the door a future default-subtype
+// decision walks through (ADR-0054's closing section).
+function missingSubtypeMessage(type) {
+    return (`type "${type}" has no default subType; write the full "${type}.<subType>"`);
+}
+/**
+ * The subType a BARE wrapper key (`{"object": …}`) resolves to: the type's DECLARED default,
+ * or `undefined` when it declares none.
+ *
+ * `registry.defaultSubTypeOf` is the same accessor the YAML desugar consults, and the shared
+ * corpus already pins the contract (`fixtures/yaml-conformance/yaml-bare-default-subtypes`:
+ * bare `object:` becomes `object.entity`). This used to guess instead — `allSubTypesOf()[0]`,
+ * i.e. registration order, falling back to `base` — so the two layers answered the same
+ * question two different ways. Registration order put `base` first, so a bare key in JSON
+ * resolved to the abstract anchor: it loaded here and in C#, while the JVM resolved it
+ * identically and then failed to INSTANTIATE, because its impl classes are abstract.
+ *
+ * A name resolved twice by two different functions is a name that can disagree with itself —
+ * the defect class this file's own header exists to prevent, reached through the one door
+ * nobody had pointed at the registry.
+ */
 function defaultSubTypeFor(type, registry) {
-    const subs = registry.allSubTypesOf(type);
-    const candidate = subs.length > 0 ? subs[0] : SUBTYPE_BASE;
-    if (!registry.has(type, candidate) && registry.has(type, SUBTYPE_BASE)) {
-        return SUBTYPE_BASE;
-    }
-    return candidate;
+    return registry.defaultSubTypeOf(type);
 }
 function splitTypeKey(key, registry) {
     const dotIdx = key.indexOf(TYPE_SUBTYPE_SEPARATOR);
     if (dotIdx < 0) {
         // Bare type, no fused subType — resolve via the registry default.
-        return { type: key, subType: defaultSubTypeFor(key, registry), explicit: false };
+        return { type: key, subType: defaultSubTypeFor(key, registry) ?? "", explicit: false };
     }
     const type = key.slice(0, dotIdx);
     const subType = key.slice(dotIdx + TYPE_SUBTYPE_SEPARATOR.length);
@@ -283,7 +346,29 @@ export function buildTree(parsed, opts) {
             throw new ParseError(`Top-level wrapper "${rootKey}" must contain an object`, { code: "ERR_TOP_LEVEL_NOT_OBJECT", source: src });
         }
         const rootDataObj = rootData;
-        const { type: rootType, subType: rootSubType } = splitTypeKey(rootKey, opts.registry);
+        const { type: rootType, subType: rootSubType, explicit: rootExplicit } = splitTypeKey(rootKey, opts.registry);
+        // A `<type>.base` node may not be AUTHORED — see abstractSubtypeMessage. This is the
+        // ROOT door; the child door is in the child loop below. One rule, both doors: a check
+        // on one of two entry points is a rule that is only half true.
+        // Registration first: an UNREGISTERED type has no default either, so without this a typo'd
+        // root key is diagnosed as a registered type that merely lacks a default. The registration
+        // check below owns that case and phrases it correctly.
+        if (opts.registry.allSubTypesOf(rootType).length > 0
+            && ((rootSubType === SUBTYPE_BASE && isAbstractAnchorFor(rootType, opts.registry))
+                || (!rootExplicit && rootSubType === ""))) {
+            _currentPath.pushKey(rootKey);
+            const src = errSource();
+            _currentPath.pop();
+            throw rootExplicit
+                ? new ParseError(abstractSubtypeMessage(rootType), {
+                    code: "ERR_ABSTRACT_SUBTYPE_AUTHORED",
+                    source: src,
+                })
+                : new ParseError(missingSubtypeMessage(rootType), {
+                    code: "ERR_MISSING_SUBTYPE",
+                    source: src,
+                });
+        }
         // Check root type is registered (always throw — can't skip the root)
         if (!opts.registry.has(rootType, rootSubType)) {
             const rootTypeCode = opts.registry.allSubTypesOf(rootType).length > 0
@@ -297,7 +382,13 @@ export function buildTree(parsed, opts) {
             // other" is how a rule ends up half-true and passing every probe.
             const retiredRoot = retiredSubType(rootType, rootSubType);
             throw new ParseError(`Unknown root type "${rootType}.${rootSubType}" — ` +
-                (retiredRoot !== undefined ? retirementHint(retiredRoot) : "not registered"), { code: rootTypeCode, source: src });
+                (retiredRoot !== undefined ? retirementHint(retiredRoot) : "not registered"), {
+                code: rootTypeCode,
+                source: src,
+                ...(retiredRoot !== undefined
+                    ? { suggestions: retirementSuggestions(retiredRoot) }
+                    : {}),
+            });
         }
         // FR5a — push the wrapper-key segment onto the JSONPath stack so all
         // descendants emit jsonPath strings rooted at "$.<rootKey>". The merge-mode
@@ -938,11 +1029,33 @@ function processChildren(parent, nodeData, accumRoot, inheritedContextPkg, regis
         }
         const childDataObj = childData;
         const { type: childType, subType: childSubTypeRaw, explicit } = splitTypeKey(childKey, registry);
+        let childSubType = childSubTypeRaw;
+        // A `<type>.base` may not be AUTHORED, and a bare key for a type with no declared default
+        // is a MISSING subType. BEFORE the registered-type check below, matching the root door and
+        // the JVM: run it after, and a bare key for a type that registers no `base` at all
+        // (identity, index, requirement) falls into that check's else-arm first and is reported as
+        // an UNKNOWN TYPE — a message asserting the type does not exist, about a type that does,
+        // with its name mangled to `"identity."`. Order is the whole rule here.
+        if ((childSubType === SUBTYPE_BASE && isAbstractAnchorFor(childType, registry))
+            || (!explicit && childSubType === "")) {
+            errors.push(explicit
+                ? new ParseError(abstractSubtypeMessage(childType), {
+                    code: "ERR_ABSTRACT_SUBTYPE_AUTHORED",
+                    source: errSource(),
+                })
+                : new ParseError(missingSubtypeMessage(childType), {
+                    code: "ERR_MISSING_SUBTYPE",
+                    source: errSource(),
+                }));
+            _currentPath?.pop(); // pop child wrapper key
+            _currentPath?.pop(); // pop array index
+            _currentYamlPosition = savedYamlPosition; // FR5b — restore parent's pos
+            continue; // skip this child
+        }
         // --- Check if this child type is registered ---
         // An EXPLICIT unknown subType (fused into the key) is an error — never
         // silently downgraded to base. An OMITTED subType that resolves to an
         // unregistered default falls back to base.
-        let childSubType = childSubTypeRaw;
         if (!registry.has(childType, childSubType)) {
             if (!explicit && registry.has(childType, SUBTYPE_BASE)) {
                 childSubType = SUBTYPE_BASE;
@@ -962,6 +1075,12 @@ function processChildren(parent, nodeData, accumRoot, inheritedContextPkg, regis
                 continue; // skip this child
             }
         }
+        // A `<type>.base` child may not be AUTHORED — the CHILD door (the root door is above).
+        // Gated on `explicit`, deliberately: `base` is also this parser's fallback for an
+        // OMITTED subtype whose registry default is unregistered (the branch directly above),
+        // and refusing that would break every node relying on the default. Placed before the
+        // attr branch so `attr.base` is covered by the same rule — an authored untyped attr is
+        // the same mistake as an authored untyped field.
         // --- Special handling for "attr" child nodes ---
         if (childType === TYPE_ATTR) {
             parseAttrChild(parent, childType, childSubType, childDataObj, registry, warnings, strict, source, childNodePath);