@metaobjectsdev/metadata 0.24.5 → 1.0.0-rc.1

package/src/errors.ts

@@ -6,7 +6,6 @@ import type { ErrorSource, LoaderError, NodeContext } from "./source.js";
 // NOTE: The following codes are forward-declared (no emitting site in the current
 // TS parser/loader — the condition is not yet detected):
 //   - ERR_DUPLICATE_NAME: parser silently reuses existing same-name nodes (find-or-create).
-//   - ERR_MISSING_SUBTYPE: missing subType is resolved to the registry default, never an error.
 //   - ERR_INVALID_SUBTYPE_CHILD: no child-rule validation pass exists yet.
 // Cross-language conformance consumers should not expect these codes from the TS adapter.
 //
@@ -20,6 +19,17 @@ export const ERROR_CODES = [
   "ERR_TOP_LEVEL_NOT_OBJECT",
   "ERR_UNKNOWN_TYPE",
   "ERR_UNKNOWN_SUBTYPE",
+  // A document AUTHORS a `<type>.base` node. Every registered `base` subtype is an
+  // abstract registry anchor — the shared root concrete subtypes inherit from, with no
+  // runtime semantics of its own (spec/metamodel/object.json says so in as many words:
+  // "not authored directly"). The JVM enforced this by accident, because its impl
+  // classes are `public abstract`; TypeScript, C# and Python accepted it, so the same
+  // document loaded on three ports and failed on two.
+  //
+  // Scoped to an EXPLICITLY authored subtype. `base` is also the parser's own fallback
+  // for an OMITTED subtype whose registry default is unregistered, and that path is
+  // untouched — refusing it would break every node that relies on the default.
+  "ERR_ABSTRACT_SUBTYPE_AUTHORED",
   "ERR_MISSING_SUBTYPE",
   "ERR_DUPLICATE_NAME",
   "ERR_UNRESOLVED_SUPER",

package/src/index.ts

@@ -178,6 +178,11 @@ export { validateConstraints } from "./constraint-validate.js";
 
 // Registry conformance manifest (SP-G) — the canonical logical-vocabulary serializer.
 export { buildRegistryManifest, emitRegistryManifest, classifyPerTypeAttr, METAMODEL_VERSION } from "./registry-manifest.js";
+// #357 — the AUTHORING-facing twin of buildRegistryManifest: every registered
+// (type, subType) this port accepts, with the cross-port carve-outs MARKED rather
+// than dropped. `meta types` reads this; the five-port byte gate reads the manifest.
+export { buildVocabularyCatalog } from "./vocabulary-catalog.js";
+export type { VocabularyCatalog, VocabularyType } from "./vocabulary-catalog.js";
 export type { AttrClassification } from "./registry-manifest.js";
 export { ExclusionReason } from "./registry-manifest-exclusions.js";
 
@@ -282,7 +287,8 @@ export type { AttrSchemaValidationResult } from "./attr-schema-validate.js";
 export {
   toSnakeCase, toKebabCase, pluralize,
   applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY,
-  resolveTableName, resolveColumnName, resolveTableSchema,
+  resolveTableName, resolveColumnName, resolveTableSchema, resolveIndexName,
+  primaryRdbSource, sourceAddressKey,
   buildNameMap,
   stripPackage,
 } from "./naming.js";
@@ -297,6 +303,7 @@ export {
   retiredAttrValue,
   retiredSubType,
   retirementHint,
+  retirementSuggestions,
 } from "./retired-vocabulary.js";
 export type { RetirementNote, RetiredEntry, VocabularyRewrite } from "./retired-vocabulary.js";
 // Its sibling: pairs of LIVE attributes that may not sit on one node. Same two consumers,

package/src/naming.ts

@@ -7,13 +7,15 @@ import {
   SOURCE_ROLE_PRIMARY,
 } from "./persistence/source/source-constants.js";
 import type { MetaSource } from "./persistence/source/meta-source.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
@@ -66,21 +68,109 @@ export function pluralize(s: string): string {
   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
+ * ADDRESS has no single answer to give, so this throws rather than picking one.
+ * The address is `(kind, schema, physical name)` — see `sourceAddressKey`. It was
+ * once the bare physical name, which was a WEAKER key than any consumer's: migrate
+ * keys every table it compares by schema-or-default + name, Postgres DDL is
+ * `CREATE TABLE "s"."t"`, and since 0.25.0 generated code binds the schema half too
+ * (`pgSchema(...).table(...)`, `[Table(..., Schema = ...)]`). Two primaries agreeing
+ * on `@table` and disagreeing on `@schema` therefore passed here and were refused by
+ * the names artifact, so `meta gen` failed on a model every other door admitted.
+ *
+ * What decided it was not the asymmetry but WHICH source the weaker key returned:
+ * `primaries[0]` is the INHERITED source in TS/C#/Python (`children()` puts the
+ * super's entries first) and the OWN source on the JVM, so such a model silently
+ * bound one schema in three ports and the other in two — one document, two verdicts
+ * depending on which toolchain read it.
+ * 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 an address is not a divergence and stays legal: the
+ * invariant is that an object has ONE address, 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 sourceAddressKey(source: MetaSource): string {
+  // The RESOLVED address, and the same three parts the names artifact compares — so the
+  // shared authority and the generated artifact cannot answer "is this one object?"
+  // differently. Rendered rather than structural because every port has to produce a
+  // byte-identical message from it.
+  //
+  // RAW, deliberately: an absent `@schema` is NOT folded into a dialect default. On
+  // Postgres absent and "public" address the same relation, but on SQLite/D1 they do
+  // not — `migrate-ts`'s expected-schema builder throws on ANY declared schema, "public"
+  // included, while an absent one is fine. `resolveTableSchema` already documents that
+  // deciding what "undefined" means belongs to the caller's dialect, not to this layer,
+  // so normalizing here would import one dialect's rule into a dialect-free tier.
+  const schema = source.attr(SOURCE_ATTR_SCHEMA);
+  const qualifier = typeof schema === "string" && schema !== "" ? `"${schema}".` : "";
+  return `${qualifier}"${source.physicalName}" (${source.effectiveKind})`;
+}
+
+export function primaryRdbSource(entity: MetaData): MetaSource | undefined {
+  const primaries = entity.children().filter(
+    (c): c is MetaSource => isMetaSource(c) && c.role === SOURCE_ROLE_PRIMARY,
+  );
+  if (primaries.length === 0) return undefined;
+  const distinct = [...new Set(primaries.map(sourceAddressKey))].sort();
+  if (distinct.length > 1) {
+    // Sorted, so the message is identical in every port regardless of children() order.
+    const joined = distinct.join(" vs ");
+    throw new MetaModelError(
+      `${entity.name}: role=primary sources disagree on the object's physical address — ` +
+      `${joined}. Every consumer binds ONE address. Give them a matching @kind, @schema ` +
+      `and physical name, or drop the extra role=primary declaration.`,
+    );
+  }
+  return primaries[0];
+}
+
 export function resolveTableName(entity: MetaData): string {
   // 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): c is MetaSource => isMetaSource(c) && c.role === SOURCE_ROLE_PRIMARY,
-  );
+  const source = primaryRdbSource(entity);
   if (source !== undefined) return source.physicalName;
   return pluralize(toSnakeCase(entity.name));
 }
@@ -95,6 +185,61 @@ export function resolveColumnName(
   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: { readonly name: string; readonly type: string; readonly subType: string },
+): string {
+  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
@@ -104,9 +249,10 @@ export function resolveColumnName(
  */
 export function resolveTableSchema(entity: MetaData): string | undefined {
   // ADR-0039: resolving — a concrete entity may inherit its source.rdb via extends.
-  const source = entity.children().find(
-    (c): c is MetaSource => 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.
   const schema = source.attr(SOURCE_ATTR_SCHEMA);

package/src/parser-core.ts

@@ -30,7 +30,7 @@ import { MetaAttr } from "./core/attr/meta-attr.js";
 import { canonicalSerialize, inferAttrSubType } from "./serializer-json.js";
 import { ParseError, type ErrorCode } 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, type ErrorSource, type LoaderWarning, type Contributor } from "./source.js";
 import { semanticDiff } from "./semantic-diff.js";
 import {
@@ -206,6 +206,64 @@ function guardRelativeRefInCanonical(
 }
 
 // ---------------------------------------------------------------------------
+// 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: string, registry: TypeRegistry): boolean {
+  return registry.allSubTypesOf(type).some((sub) => sub !== SUBTYPE_BASE);
+}
+
+function abstractSubtypeMessage(type: string): string {
+  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: string): string {
+  return (
+    `type "${type}" has no default subType; write the full "${type}.<subType>"`
+  );
+}
+
 // Internal helper — split a fused wrapper key into (type, subType).
 //
 // Canonical JSON always writes the full `type.subType`. An omitted subType
@@ -220,20 +278,31 @@ interface SplitKey {
   explicit: boolean;
 }
 
-function defaultSubTypeFor(type: string, registry: TypeRegistry): string {
-  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;
+/**
+ * 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: string, registry: TypeRegistry): string | undefined {
+  return registry.defaultSubTypeOf(type);
 }
 
 function splitTypeKey(key: string, registry: TypeRegistry): SplitKey {
   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);
@@ -419,7 +488,31 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
     }
 
     const rootDataObj = rootData as Record<string, unknown>;
-    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)) {
@@ -436,7 +529,13 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
       throw new ParseError(
         `Unknown root type "${rootType}.${rootSubType}" — ` +
           (retiredRoot !== undefined ? retirementHint(retiredRoot) : "not registered"),
-        { code: rootTypeCode, source: src },
+        {
+          code: rootTypeCode,
+          source: src,
+          ...(retiredRoot !== undefined
+            ? { suggestions: retirementSuggestions(retiredRoot) }
+            : {}),
+        },
       );
     }
 
@@ -1259,11 +1358,36 @@ function processChildren(
     const childDataObj = childData as Record<string, unknown>;
     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;
@@ -1288,6 +1412,12 @@ function processChildren(
       }
     }
 
+    // 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);

package/src/persistence/origin/origin-definition.embedded.ts

@@ -12,7 +12,7 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
     {
       "type": "origin",
       "subType": "base",
-      "description": "Abstract base origin — the shared root subtype for field-level provenance. A field carrying any origin.* is derived ⇒ read-only wherever it lives. The base carries no attrs of its own; concrete subtypes add their provenance attrs."
+      "description": "Abstract base origin — the shared root subtype for field-level provenance. A field carrying any origin.* is derived ⇒ read-only wherever it lives. The base carries no attrs of its own; concrete subtypes add their provenance attrs. Not authored directly: a `origin.base` node fails to load (ERR_ABSTRACT_SUBTYPE_AUTHORED) — this subtype is a registry anchor concrete subtypes inherit from, never a node in a document."
     },
     {
       "type": "origin",

package/src/persistence/source/source-definition.embedded.ts

@@ -12,7 +12,7 @@ export const SOURCE_DEFINITION: ProviderDefinition = {
     {
       "type": "source",
       "subType": "base",
-      "description": "Abstract base source — the shared root subtype for declaring where an object's data lives (Project E). The base carries no attrs of its own; the concrete paradigm subtype (rdb) carries the physical-storage attrs, which are contributed by the db domain provider."
+      "description": "Abstract base source — the shared root subtype for declaring where an object's data lives (Project E). The base carries no attrs of its own; the concrete paradigm subtype (rdb) carries the physical-storage attrs, which are contributed by the db domain provider. Not authored directly: a `source.base` node fails to load (ERR_ABSTRACT_SUBTYPE_AUTHORED) — this subtype is a registry anchor concrete subtypes inherit from, never a node in a document."
     },
     {
       "type": "source",

package/src/presentation/layout/layout-definition.embedded.ts

@@ -12,7 +12,7 @@ export const LAYOUT_DEFINITION: ProviderDefinition = {
     {
       "type": "layout",
       "subType": "base",
-      "description": "Abstract base layout — the shared root subtype for object-level UI surfaces. A layout attaches a presentation concern (grids, forms, tabs, cards) to an object. The base carries no attrs of its own; concrete subtypes add their presentation attrs."
+      "description": "Abstract base layout — the shared root subtype for object-level UI surfaces. A layout attaches a presentation concern (grids, forms, tabs, cards) to an object. The base carries no attrs of its own; concrete subtypes add their presentation attrs. Not authored directly: a `layout.base` node fails to load (ERR_ABSTRACT_SUBTYPE_AUTHORED) — this subtype is a registry anchor concrete subtypes inherit from, never a node in a document."
     },
     {
       "type": "layout",

package/src/presentation/view/view-definition.embedded.ts

@@ -12,7 +12,7 @@ export const VIEW_DEFINITION: ProviderDefinition = {
     {
       "type": "view",
       "subType": "base",
-      "description": "Abstract view base — the shared root subtype for field-level UI/render hints. A view declares how a field's value is rendered or edited; the base carries no attrs of its own."
+      "description": "Abstract view base — the shared root subtype for field-level UI/render hints. A view declares how a field's value is rendered or edited; the base carries no attrs of its own. Not authored directly: a `view.base` node fails to load (ERR_ABSTRACT_SUBTYPE_AUTHORED) — this subtype is a registry anchor concrete subtypes inherit from, never a node in a document."
     },
     {
       "type": "view",

package/src/registry-coverage.ts

@@ -23,6 +23,7 @@ import {
   RESERVED_KEYS,
   TYPE_SUBTYPE_SEPARATOR,
 } from "./shared/structural.js";
+import { SUBTYPE_BASE } from "./shared/base-types.js";
 
 // ---------------------------------------------------------------------------
 // Manifest shape (a structural subset of fixtures/registry-conformance schema)
@@ -249,15 +250,35 @@ function compareStrings(a: string, b: string): number {
  * @param manifest the parsed registry manifest (the registered vocabulary)
  * @param roots    fixture-corpus directory roots to scan for usage
  */
+/**
+ * True for a `<type>.base` registry entry — an ABSTRACT ANCHOR, excluded from the coverage
+ * universe entirely.
+ *
+ * A `base` subtype is the shared root that concrete subtypes inherit their attrs and child
+ * rules from. It has no runtime semantics and no concrete representation, and authoring one
+ * is now a load error (ERR_ABSTRACT_SUBTYPE_AUTHORED), so no fixture can ever exercise it.
+ * Listing all ten as "untested vocabulary" described them as a backlog somebody could work
+ * off; they are the contract instead.
+ *
+ * Excluding them also keeps the attr accounting honest. The attrs a `base` entry declares
+ * are the ones its CONCRETE subtypes inherit — `@required` is declared on `field.base` and
+ * set on a `field.string` — so measuring them against fixtures that name `field.base` would
+ * report every shared field attr as untested the moment one negative fixture mentioned the
+ * subtype, which is what the corpus fixture for the new rule did.
+ */
+function isAbstractAnchor(type: { readonly subType: string }): boolean {
+  return type.subType === SUBTYPE_BASE;
+}
+
 export function computeCoverage(
   manifest: RegistryManifest,
   roots: readonly string[],
 ): CoverageReport {
   const usage = scanFixtureUsage(roots);
 
-  const registeredKeys = manifest.types.map(
-    (t) => `${t.type}${TYPE_SUBTYPE_SEPARATOR}${t.subType}`,
-  );
+  const registeredKeys = manifest.types
+    .filter((t) => !isAbstractAnchor(t))
+    .map((t) => `${t.type}${TYPE_SUBTYPE_SEPARATOR}${t.subType}`);
 
   const untestedSubTypes = registeredKeys
     .filter((key) => !usage.subTypes.has(key))
@@ -268,6 +289,7 @@ export function computeCoverage(
   // Per EXERCISED subtype, which declared attrs no fixture sets.
   const untestedAttrsByExercisedSubType: UntestedAttrs[] = [];
   for (const t of manifest.types) {
+    if (isAbstractAnchor(t)) continue; // abstract anchor — see isAbstractAnchor
     const key = `${t.type}${TYPE_SUBTYPE_SEPARATOR}${t.subType}`;
     if (!usage.subTypes.has(key)) continue; // skip untested subtypes (all-untested by definition)
     if (t.attrs.length === 0) continue;

package/src/registry-manifest.ts

@@ -37,7 +37,7 @@ import {
 } from "./registry-manifest-exclusions.js";
 
 /** One attribute in the manifest — the logical, cross-port-identical facet. */
-interface ManifestAttr {
+export interface ManifestAttr {
   name: string;
   /** The attr's SCALAR value-type subtype, or null for a polymorphic/untyped attr (e.g. @default). */
   valueType: string | null;
@@ -63,7 +63,7 @@ interface ManifestAttr {
 }
 
 /** One structural child rule of a type (FR-033 constraint graph). */
-interface ManifestChild {
+export interface ManifestChild {
   /** The admitted child `type` (`"*"` = any). */
   childType: string;
   /** The admitted child subType — a single subtype, `"*"` (any), or a list of admitted subtypes. */
@@ -79,7 +79,7 @@ interface ManifestChild {
 }
 
 /** One registered (type, subType) in the manifest, with its docs + attrs + constraint graph. */
-interface ManifestType {
+export interface ManifestType {
   type: string;
   subType: string;
   /** FR-033 — human/AI-facing description of the type/subType (required, non-empty). */
@@ -112,7 +112,7 @@ interface ManifestType {
  * constant read `"0.10"`). Bump with that script — never by hand — so the manifest and
  * all four port constants move together.
  */
-export const METAMODEL_VERSION = "0.13";
+export const METAMODEL_VERSION = "1.0";
 
 /** The full canonical manifest. All collections are sorted for byte-stability. */
 interface RegistryManifest {
@@ -124,7 +124,7 @@ interface RegistryManifest {
 }
 
 /** ASCII-string compare so the sort is locale-independent and byte-stable across ports. */
-function compareStrings(a: string, b: string): number {
+export function compareStrings(a: string, b: string): number {
   return a < b ? -1 : a > b ? 1 : 0;
 }
 
@@ -195,7 +195,7 @@ function toManifestChild(rule: ChildRule): ManifestChild {
 }
 
 /** Sort the constraint graph by (childType, childSubTypeKey, childName) — ASCII. */
-function sortedChildren(rules: readonly ChildRule[]): ManifestChild[] {
+export function sortedChildren(rules: readonly ChildRule[]): ManifestChild[] {
   return rules
     .map(toManifestChild)
     .sort(
@@ -207,7 +207,7 @@ function sortedChildren(rules: readonly ChildRule[]): ManifestChild[] {
 }
 
 /** Sort attrs by name (ascending, ASCII). */
-function sortedAttrs(attrs: readonly AttrSchema[]): ManifestAttr[] {
+export function sortedAttrs(attrs: readonly AttrSchema[]): ManifestAttr[] {
   return attrs
     .map(toManifestAttr)
     .sort((a, b) => compareStrings(a.name, b.name));
@@ -260,7 +260,8 @@ function sortedPerTypeAttrs(
  * judge a carve-out "dead" — that is a cross-port property, asserted by the
  * shared byte-canonical, not here.
  */
-const INCLUDED = "included" as const;
+/** The classifier's "this is logical cross-port vocabulary" verdict. */
+export const INCLUDED = "included" as const;
 export type AttrClassification = ExclusionReason | typeof INCLUDED;
 
 export function classifyPerTypeAttr(name: string): AttrClassification {