@metaobjectsdev/metadata 0.10.0 → 0.11.0

package/src/core/identity/identity-constants.ts

@@ -28,6 +28,10 @@ export const IDENTITY_REFERENCE_ATTR_REFERENCES = "references";
 /** Identity-reference attr: physical-enforcement flag. Default true → hard FK constraint; false → logical-only reference. */
 export const IDENTITY_REFERENCE_ATTR_ENFORCE = "enforce";
 
+// NOTE: physical RDB-only identity attrs (@constraintName on identity.reference;
+// @orders / @where on identity.secondary) are NOT core — they are contributed by
+// the db provider and declared in persistence/db/db-constants.ts.
+
 // ---------------------------------------------------------------------------
 // Identity generation strategies (values for IDENTITY_ATTR_GENERATION)
 // ---------------------------------------------------------------------------

package/src/core/identity/identity-definition.embedded.ts

@@ -13,6 +13,8 @@ export const IDENTITY_DEFINITION: ProviderDefinition = {
       "type": "identity",
       "subType": "primary",
       "description": "The primary key — one per entity; @fields names its column(s), @generation the value strategy.",
+      "maxOccurs": 1,
+      "defaultName": "primary",
       "children": [
         {
           "type": "attr",

package/src/core/identity/meta-identity.ts

@@ -136,7 +136,14 @@ export class MetaReferenceIdentity extends MetaIdentity {
 
     const targetName = this.targetEntity;
     if (targetName === undefined) return undefined;
-    const targetObj = root.findObject(targetName);
+    // targetEntity may be package-qualified (FQN); findObject is keyed by bare
+    // name, so fall back to the bare suffix after the last "::". Mirrors the
+    // resolveTargetTable fix; without it a cross-package reference resolves no
+    // target and the PK column wrongly defaults to "id".
+    const targetObj = root.findObject(targetName)
+      ?? (targetName.includes("::")
+        ? root.findObject(targetName.slice(targetName.lastIndexOf("::") + 2))
+        : undefined);
     if (!targetObj) return undefined;
 
     const primary = targetObj.primaryIdentity();

package/src/core/validator/validator-constants.ts

@@ -3,7 +3,7 @@
 import { SUBTYPE_BASE } from "../../shared/base-types.js";
 
 // ---------------------------------------------------------------------------
-// Validator subtypes (6)
+// Validator subtypes (10)
 // ---------------------------------------------------------------------------
 
 export const VALIDATOR_SUBTYPE_REQUIRED = "required";
@@ -11,6 +11,11 @@ export const VALIDATOR_SUBTYPE_LENGTH = "length";
 export const VALIDATOR_SUBTYPE_REGEX = "regex";
 export const VALIDATOR_SUBTYPE_NUMERIC = "numeric";
 export const VALIDATOR_SUBTYPE_ARRAY = "array";
+// Cross-field validators — entity-scoped, reference sibling fields by name.
+export const VALIDATOR_SUBTYPE_COMPARISON = "comparison";
+export const VALIDATOR_SUBTYPE_REQUIRED_WHEN = "requiredWhen";
+export const VALIDATOR_SUBTYPE_PRESENT_IFF = "presentIff";
+export const VALIDATOR_SUBTYPE_AT_LEAST_ONE = "atLeastOne";
 
 export const VALIDATOR_SUBTYPES = [
   SUBTYPE_BASE,
@@ -19,6 +24,10 @@ export const VALIDATOR_SUBTYPES = [
   VALIDATOR_SUBTYPE_REGEX,
   VALIDATOR_SUBTYPE_NUMERIC,
   VALIDATOR_SUBTYPE_ARRAY,
+  VALIDATOR_SUBTYPE_COMPARISON,
+  VALIDATOR_SUBTYPE_REQUIRED_WHEN,
+  VALIDATOR_SUBTYPE_PRESENT_IFF,
+  VALIDATOR_SUBTYPE_AT_LEAST_ONE,
 ] as const;
 export type ValidatorSubType = (typeof VALIDATOR_SUBTYPES)[number];
 
@@ -29,3 +38,15 @@ export type ValidatorSubType = (typeof VALIDATOR_SUBTYPES)[number];
 export const VALIDATOR_ATTR_PATTERN = "pattern";
 export const VALIDATOR_ATTR_MIN = "min";
 export const VALIDATOR_ATTR_MAX = "max";
+// Cross-field validator attrs (field references by name + operator/value).
+export const VALIDATOR_ATTR_LEFT = "left";
+export const VALIDATOR_ATTR_OP = "op";
+export const VALIDATOR_ATTR_RIGHT = "right";
+export const VALIDATOR_ATTR_FIELD = "field";
+export const VALIDATOR_ATTR_WHEN = "when";
+export const VALIDATOR_ATTR_EQUALS = "equals";
+export const VALIDATOR_ATTR_FIELDS = "fields";
+
+// Comparison operators (@op allowed values) → relational operator.
+export const VALIDATOR_COMPARISON_OPS = ["gt", "gte", "lt", "lte", "ne", "eq"] as const;
+export type ComparisonOp = (typeof VALIDATOR_COMPARISON_OPS)[number];

package/src/core/validator/validator-definition.embedded.ts

@@ -136,6 +136,127 @@ export const VALIDATOR_DEFINITION: ProviderDefinition = {
           "description": "Maximum allowed value (length, numeric value, or array element count depending on the validator subtype)."
         }
       ]
+    },
+    {
+      "type": "validator",
+      "subType": "comparison",
+      "description": "Cross-field ordering: requires two sibling fields of the owning entity stand in a relational order (@left @op @right), e.g. current_hp <= max_hp or expires_at > created_at. Entity-scoped; references fields by name. Backends derive the rule (CHECK constraint, cross-field assertion) — no raw expression is stored.",
+      "rules": "@left and @right must name fields of the owning entity. @op is one of gt/gte/lt/lte/ne/eq. The comparison is null-tolerant where the backend's relational operator is (SQL: a NULL operand yields no violation).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "left",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the left-hand field of the owning entity."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "op",
+          "min": 1,
+          "max": 1,
+          "allowedValues": [
+            "gt",
+            "gte",
+            "lt",
+            "lte",
+            "ne",
+            "eq"
+          ],
+          "description": "Relational operator: gt (>), gte (>=), lt (<), lte (<=), ne (<>), eq (=)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "right",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the right-hand field of the owning entity."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "requiredWhen",
+      "description": "One-directional conditional presence: when the gating field (@when) equals @equals, the target field (@field) must be present (NOT NULL); otherwise @field is unconstrained. Mirrors JSON Schema dependentRequired / Rails validates_presence_of :x, if:. Entity-scoped; references fields by name.",
+      "rules": "@field and @when must name fields of the owning entity. @equals is the gating value, compared against @when's value (rendered per @when's field subtype — boolean true/false, enum/string literal, numeric literal).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "field",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the field that becomes required when the condition holds."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "when",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the gating field whose value triggers the requirement."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "equals",
+          "min": 1,
+          "max": 1,
+          "description": "The gating value; when @when equals this, @field must be present."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "presentIff",
+      "description": "Biconditional presence: the target field (@field) is present (NOT NULL) if and only if the gating field (@when) equals @equals. Models paired flag/companion-column invariants, e.g. used_at present iff is_used=true. Entity-scoped; references fields by name.",
+      "rules": "@field and @when must name fields of the owning entity. @equals is rendered per @when's field subtype. Stricter than requiredWhen — also forbids @field when the condition is false.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "field",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the field whose presence is governed by the condition."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "when",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the gating field."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "equals",
+          "min": 1,
+          "max": 1,
+          "description": "The gating value; @field is present exactly when @when equals this."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "atLeastOne",
+      "description": "Cardinality of presence: at least one of the named fields (@fields) must be present (NOT NULL). Entity-scoped; references fields by name (same @fields-by-name pattern as identity.*).",
+      "rules": "@fields names two or more fields of the owning entity. Satisfied when any one of them is non-null.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "fields",
+          "isArray": true,
+          "min": 1,
+          "max": 1,
+          "description": "Names of the candidate fields; at least one must be present."
+        }
+      ]
     }
   ]
 };

package/src/core-types.ts

@@ -84,8 +84,9 @@ import {
   IDENTITY_SUBTYPE_PRIMARY,
   IDENTITY_SUBTYPE_SECONDARY,
   IDENTITY_SUBTYPE_REFERENCE,
+  IDENTITY_REFERENCE_ATTR_REFERENCES,
 } from "./core/identity/identity-constants.js";
-import { RELATIONSHIP_SUBTYPES } from "./core/relationship/relationship-constants.js";
+import { RELATIONSHIP_SUBTYPES, RELATIONSHIP_ATTR_OBJECT_REF } from "./core/relationship/relationship-constants.js";
 import { LAYOUT_SUBTYPES } from "./presentation/layout/layout-constants.js";
 import { SOURCE_SUBTYPES } from "./persistence/source/source-constants.js";
 import {
@@ -462,6 +463,30 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     registry.register(relationshipDef);
   }
 
+  // Declare the core cross-references ON their TypeDefinitions, so the loader's
+  // registry-derived validation resolves them generically (a dangling target fails the
+  // load). Set on the concrete subtypes the parser produces. (Production moves these into
+  // the embedded spec/metamodel JSON once every port's spec reader carries the field.)
+  for (const subType of RELATIONSHIP_SUBTYPES) {
+    const def = registry.find(TYPE_RELATIONSHIP, subType);
+    if (def) {
+      def.references = [
+        { attr: RELATIONSHIP_ATTR_OBJECT_REF, targetType: TYPE_OBJECT, errorCode: "ERR_INVALID_RELATIONSHIP" },
+      ];
+    }
+  }
+  const idRefDef = registry.find(TYPE_IDENTITY, IDENTITY_SUBTYPE_REFERENCE);
+  if (idRefDef) {
+    idRefDef.references = [
+      {
+        attr: IDENTITY_REFERENCE_ATTR_REFERENCES,
+        targetType: TYPE_OBJECT,
+        dottedFieldPath: true,
+        errorCode: "ERR_INVALID_REFERENCE",
+      },
+    ];
+  }
+
   // Default subTypes for YAML authoring sugar: a bare `metadata:` / `object:`
   // key resolves to these. `metadata` has exactly one subtype (root) so the
   // default is unambiguous; `object` defaults to `entity`, the common case.

package/src/errors.ts

@@ -30,6 +30,9 @@ export const ERROR_CODES = [
   // author-chosen (e.g. "id"), so the dotted by-name extends form can
   // address them.
   "ERR_IDENTITY_NAME_REQUIRED",
+  // A `type.subType` declared with `maxOccurs` (e.g. identity.primary,
+  // maxOccurs:1) appears more times than allowed under one parent.
+  "ERR_TOO_MANY_OCCURRENCES",
   // FR-024 — an identity.* on an object.projection lacks `extends`; a
   // projection identity is a pass-through of an entity identity.
   "ERR_PROJECTION_IDENTITY_NOT_EXTENDED",
@@ -95,6 +98,9 @@ export const ERROR_CODES = [
   // junction declaring two identity.reference children; @sourceRefField must match
   // one of them; M:N attrs are invalid on a 1:N (@cardinality:one / no @through).
   "ERR_INVALID_RELATIONSHIP",
+  // identity.reference @references names an FK target that does not resolve to any
+  // object in the loaded tree (a dangling cross-reference between metadata).
+  "ERR_INVALID_REFERENCE",
   "ERR_VAR_NOT_ON_PAYLOAD",
   "ERR_PARTIAL_UNRESOLVED",
   "ERR_REQUIRED_SLOT_UNUSED",
@@ -189,7 +195,10 @@ export type ErrorCode = (typeof ERROR_CODES)[number];
  * envelope's `jsonPath` and `files` and have been dropped — see CHANGELOG.
  */
 export class ParseError extends Error implements LoaderError {
-  readonly code: ErrorCode;
+  // Widened from the core ErrorCode union so a DOWNSTREAM provider's validator can emit its
+  // own codes (LoaderError.code is `string`; the envelope compares codes as strings). Known
+  // core codes still surface in editor suggestions via the `string & {}` idiom.
+  readonly code: ErrorCode | (string & {});
   readonly source: ErrorSource;
   readonly suggestions?: string[];
   readonly fixture?: string;
@@ -198,7 +207,7 @@ export class ParseError extends Error implements LoaderError {
   constructor(
     message: string,
     opts: {
-      code: ErrorCode;
+      code: ErrorCode | (string & {});
       source: ErrorSource;
       suggestions?: string[];
       fixture?: string;

package/src/loader/meta-data-loader.ts

@@ -18,6 +18,7 @@ import type { LoaderWarning } from "../source.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
 import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships } from "./validation-passes.js";
+import { runRegisteredValidation } from "./validation-registry.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { validateSourcePhysicalNames } from "../persistence/source/validate-source-physical-names.js";
 import { validateSourceParameterRef } from "../persistence/source/validate-source-parameter-ref.js";
@@ -25,6 +26,7 @@ import { validateFieldReadOnly } from "../core/field/validate-field-readonly.js"
 import { validateDiscriminator } from "../core/object/validate-discriminator.js";
 import { resolveDeferredSupers } from "../super-resolve.js";
 import { validateSubtypeRules } from "../subtype-rules.js";
+import { validateMaxOccurs } from "../validate-max-occurs.js";
 import { validateIdentityPassthrough } from "../core/identity/validate-identity-passthrough.js";
 import { validateAttrSchema } from "../attr-schema-validate.js";
 import type { MetaDataFormat, MetaDataSource } from "./meta-data-source.js";
@@ -452,6 +454,10 @@ export class MetaDataLoader {
       errors.push(...ruleResult.errors);
       warnings.push(...ruleResult.warnings);
 
+      // maxOccurs enforcement (config-driven singleton constraint, e.g. one
+      // identity.primary per entity) — the safety complement to defaultName.
+      errors.push(...validateMaxOccurs(root, this._registry));
+
       // FR-024 B3 — projection identity pass-through + key correspondence
       // (ERR_PROJECTION_IDENTITY_NOT_EXTENDED / ERR_IDENTITY_KEY_MISMATCH).
       errors.push(...validateIdentityPassthrough(root));
@@ -485,6 +491,12 @@ export class MetaDataLoader {
       // are invalid on a 1:N relationship.
       errors.push(...validateRelationships(root));
 
+      // Phase 2 — validation DERIVED FROM THE TYPE REGISTRY: each node's TypeDefinition
+      // carries its reference descriptors + imperative validator, run as one recursive walk
+      // over a built-once symbol table. A downstream provider's custom type validates itself
+      // simply by being in this registry — no separate wiring.
+      errors.push(...runRegisteredValidation(root, this._registry));
+
       // template.* validation — @payloadRef resolves to a known object;
       // @requiredSlots are real fields on it (FR-004 Plan #3, T2).
       errors.push(...validateTemplatePayloadRefs(root));

package/src/loader/validation-passes.ts

@@ -66,7 +66,10 @@ import {
   FIELD_SUBTYPE_OBJECT,
 } from "../core/field/field-constants.js";
 import { FIELD_ATTR_DB_INDEXED } from "../persistence/db/db-constants.js";
-import { IDENTITY_ATTR_FIELDS } from "../core/identity/identity-constants.js";
+import {
+  IDENTITY_ATTR_FIELDS,
+  IDENTITY_SUBTYPE_REFERENCE,
+} from "../core/identity/identity-constants.js";
 import {
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
@@ -1199,6 +1202,10 @@ export function validateRelationships(root: MetaData): ParseError[] {
       const isMany = cardinality === CARDINALITY_MANY;
       const isM2M = hasThrough && isMany;
 
+      // NOTE: @objectRef existence resolution moved to the validation registry
+      // (defaultValidationRegistry → a declarative reference descriptor). The M:N
+      // slim-vocabulary rules below stay here for now (Phase 3 migrates them too).
+
       // Rule (d): M:N-only attrs on a non-M:N relationship.
       if (!isM2M) {
         if (hasThrough) {
@@ -1292,6 +1299,9 @@ export function validateRelationships(root: MetaData): ParseError[] {
   return errors;
 }
 
+// NOTE: identity.reference @references resolution moved to the validation registry
+// (defaultValidationRegistry → a declarative reference descriptor with dottedFieldPath).
+
 function checkFilterClauses(
   filter: Record<string, unknown>,
   allow: Map<string, readonly string[]>,

package/src/loader/validation-registry.ts

@@ -0,0 +1,93 @@
+// The validation walk — implementation of the contract in ../validation-types.ts.
+//
+// Validation is DERIVED FROM THE TYPE REGISTRY: each node's TypeDefinition carries its
+// reference descriptors + imperative validator, so a downstream provider's type validates
+// itself with no separate registry and no core changes. One recursive walk over a
+// built-once symbol table: per node, apply declared references, invoke the type's
+// validator, recurse. See docs/superpowers/specs/2026-06-19-metadata-validation-architecture-design.md.
+
+import type { MetaData } from "../shared/meta-data.js";
+import { ParseError } from "../errors.js";
+import { refMatchesObject } from "../naming-refs.js";
+import { TYPE_OBJECT } from "../shared/base-types.js";
+import type { TypeRegistry } from "../registry.js";
+import type { LoaderCode, SymbolTable, ValidationContext } from "../validation-types.js";
+
+/** A symbol table of every top-level object, built once per load (the binder analogue). */
+class SymbolTableImpl implements SymbolTable {
+  private readonly byRef = new Map<string, MetaData>();
+
+  static build(root: MetaData): SymbolTableImpl {
+    const t = new SymbolTableImpl();
+    for (const child of root.ownChildren()) {
+      if (child.type !== TYPE_OBJECT) continue;
+      if (child.name) t.byRef.set(child.name, child);
+      t.byRef.set(child.fqn(), child);
+      t.byRef.set(child.resolutionKey(), child);
+    }
+    return t;
+  }
+
+  resolveObject(ref: string): MetaData | undefined {
+    const hit = this.byRef.get(ref);
+    if (hit) return hit;
+    for (const obj of this.byRef.values()) {
+      if (refMatchesObject(obj, ref)) return obj;
+    }
+    return undefined;
+  }
+}
+
+class ValidationContextImpl implements ValidationContext {
+  readonly errors: ParseError[] = [];
+  constructor(readonly symbols: SymbolTable) {}
+  error(code: LoaderCode, node: MetaData, message: string): void {
+    this.errors.push(new ParseError(message, { code, source: node.source }));
+  }
+}
+
+/**
+ * Run validation derived from `registry` over the tree. Per node: look up its
+ * TypeDefinition, apply its declared reference descriptors (resolve against the symbol
+ * table), invoke its imperative validator, then recurse into own children.
+ */
+export function runRegisteredValidation(root: MetaData, registry: TypeRegistry): ParseError[] {
+  const ctx = new ValidationContextImpl(SymbolTableImpl.build(root));
+  walk(root);
+  return ctx.errors;
+
+  function walk(node: MetaData): void {
+    const def = registry.find(node.type, node.subType);
+    if (def) {
+      for (const desc of def.references ?? []) {
+        const raw = node.ownAttr(desc.attr);
+        if (typeof raw !== "string" || raw === "") continue; // absence is the required-attr pass's job
+        const entityRef = desc.dottedFieldPath ? (raw.split(".")[0] ?? raw) : raw;
+        const target = ctx.symbols.resolveObject(entityRef);
+        // Qualify the node name with its owning entity (e.g. "Order.items") so the error is
+        // locatable from the message alone, not just the source envelope.
+        const qname = node.parent?.name ? `${node.parent.name}.${node.name}` : node.name;
+        if (!target) {
+          ctx.error(
+            desc.errorCode,
+            node,
+            `${node.type}.${node.subType} "${qname}" @${desc.attr} "${raw}" does not resolve to an object.`,
+          );
+        } else if (
+          target.type !== desc.targetType ||
+          (desc.targetSubType !== undefined && target.subType !== desc.targetSubType)
+        ) {
+          const want = desc.targetSubType ? `${desc.targetType}.${desc.targetSubType}` : desc.targetType;
+          ctx.error(
+            desc.errorCode,
+            node,
+            `${node.type}.${node.subType} "${qname}" @${desc.attr} "${raw}" resolves to ` +
+              `${target.type}.${target.subType}, not a ${want}.`,
+          );
+        }
+      }
+      def.validate?.(node, ctx);
+    }
+    for (const child of node.ownChildren()) walk(child);
+  }
+}

package/src/parser-core.ts

@@ -519,10 +519,19 @@ function parseNodeFresh(
 
   // --- Determine name ---
   const rawName = nodeData[RESERVED_KEY_NAME];
-  const name = typeof rawName === "string" ? rawName : "";
+  let name = typeof rawName === "string" ? rawName : "";
 
   // --- Create the model ---
   const def = registry.find(type, subType)!;
+  // Config-driven default name for a SINGLETON child type: when the node is
+  // declared with no name and its type definition is `maxOccurs: 1` with a
+  // `defaultName`, assign it (e.g. identity.primary → "primary"). Safe by
+  // construction — maxOccurs===1 guarantees no sibling can collide — and keeps
+  // the one-and-only node addressable. Multi-cardinality types carry no
+  // defaultName, so they still require an explicit name (FR-024).
+  if (name === "" && def.maxOccurs === 1 && def.defaultName !== undefined) {
+    name = def.defaultName;
+  }
   const model = def.factory(def.typeId, name);
   // FR5a — stamp the source provenance envelope using the parser's current
   // JSONPath stack + source id. setSource happens BEFORE freeze (the parser

package/src/persistence/db/db-constants.ts

@@ -10,6 +10,22 @@ export const FIELD_ATTR_COLUMN = "column";
 /** When true, suppress the @filterable-without-index Loader warning (Project D drift check). */
 export const FIELD_ATTR_DB_INDEXED = "db.indexed";
 
+// --- Physical RDB index/constraint attrs the db provider adds to identity.* ---
+// These EXTEND core identity subtypes (via registry.extend) rather than living on
+// core, because they are pure physical-storage concerns (index ordering, partial-
+// index predicate, FK constraint naming) with no logical-model meaning.
+
+/** identity.secondary: per-field index-key sort direction array ('asc' | 'desc'), positional to @fields. Drives DESC-ordered index keys. */
+export const IDENTITY_ATTR_ORDERS = "orders";
+/** identity.secondary: a partial-index predicate (raw SQL). When set, the index covers only matching rows. */
+export const IDENTITY_ATTR_WHERE = "where";
+/** identity.secondary: a raw key EXPRESSION for a functional/expression index (e.g. "lower(email)"); used instead of @fields. */
+export const IDENTITY_ATTR_EXPR = "expr";
+/** identity.secondary: index access method (e.g. "gin", "gist"); default "btree", which is not rendered. */
+export const IDENTITY_ATTR_USING = "using";
+/** identity.reference: physical FK constraint-name override. Absent → the auto-derived `<table>_<firstFkColumn>_fk`. */
+export const IDENTITY_ATTR_CONSTRAINT_NAME = "constraintName";
+
 /**
  * R6 Plan 2b: `@dbColumnType` — physical DB column-type override on a field.
  * Selects the DB column type WITHOUT changing the logical field type or its

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

@@ -172,6 +172,63 @@ export const DB_DEFINITION: ProviderDefinition = {
           "description": "FR-015: name or FQN of an object.value describing the input shape of this source's callable interface. Permitted on @kind: \"storedProc\" / \"tableFunction\"; rejected on non-callable kinds (table / view / materializedView). Field children of the referenced object.value become the call-site parameter list in declaration order. Symmetric with template.@payloadRef in FR-004 — the typed-input pattern reuses object.value rather than minting a new parameter.* node type."
         }
       ]
+    },
+    {
+      "type": "identity",
+      "subType": "secondary",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "orders",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "asc",
+            "desc"
+          ],
+          "description": "Physical index-key sort direction, positional to @fields ('asc' | 'desc'). Omit for all-ascending (the default); a shorter array leaves trailing keys ascending. Drives DESC-ordered index keys (e.g. a recency index on a timestamp). RDB-physical — contributed by the db provider, not core identity."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "where",
+          "min": 0,
+          "max": 1,
+          "description": "Partial-index predicate (raw SQL, e.g. \"delivered_at IS NULL\"). When set, the index covers only rows matching the predicate — smaller and cheaper for queries that always filter on it. Absent = a full index over every row. RDB-physical — contributed by the db provider."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "expr",
+          "min": 0,
+          "max": 1,
+          "description": "Raw key EXPRESSION for a functional/expression index (e.g. \"lower(email)\"). Used INSTEAD of @fields — the index key is the expression rather than plain columns. RDB-physical — contributed by the db provider."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "using",
+          "min": 0,
+          "max": 1,
+          "description": "Index access method (e.g. \"gin\", \"gist\", \"hash\"); default \"btree\" (not rendered). Pair with @expr for e.g. a GIN index over an array/jsonb expression. RDB-physical — contributed by the db provider."
+        }
+      ]
+    },
+    {
+      "type": "identity",
+      "subType": "reference",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "constraintName",
+          "min": 0,
+          "max": 1,
+          "description": "Physical foreign-key constraint name override. Absent → the backend's auto-derived default (e.g. `<table>_<firstFkColumn>_fk`). Lets a model adopt an existing database whose FK constraints follow a different naming convention without a destructive rename. RDB-physical — contributed by the db provider."
+        }
+      ]
     }
   ]
 };

package/src/provider-data.ts

@@ -97,6 +97,21 @@ export interface TypeDef {
    * registered output change) under S0.
    */
   extendsBase?: boolean;
+  /**
+   * Max number of children of this `type.subType` permitted under one parent.
+   * `1` marks a singleton child (e.g. `identity.primary` — one per entity). The
+   * loader enforces it. A singleton is the ONLY place a static `defaultName` is
+   * safe (no sibling can collide), so `defaultName` is honored only when
+   * `maxOccurs === 1`. Absent = unbounded.
+   */
+  maxOccurs?: number;
+  /**
+   * Author-omittable name for a singleton child. When a node of this type is
+   * declared with no `name` AND `maxOccurs === 1`, the loader assigns
+   * `defaultName` (e.g. `identity.primary` → `"primary"`). Keeps the one-and-only
+   * node addressable (`Entity.primary`) without forcing a hand-written name.
+   */
+  defaultName?: string;
 }
 
 /**
@@ -240,6 +255,8 @@ export function defineProviderFromData(
       ...(t.rules !== undefined ? { rules: t.rules } : {}),
       ...(t.example !== undefined ? { example: t.example } : {}),
       ...(t.whenToUse !== undefined ? { whenToUse: t.whenToUse } : {}),
+      ...(t.maxOccurs !== undefined ? { maxOccurs: t.maxOccurs } : {}),
+      ...(t.defaultName !== undefined ? { defaultName: t.defaultName } : {}),
     };
   });
 }

package/src/registry.ts

@@ -3,6 +3,7 @@ import { SUBTYPE_BASE, TYPE_ATTR } from "./shared/base-types.js";
 import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
 import { type AttrSubType } from "./core/attr/attr-constants.js";
 import type { DataType } from "./data-type.js";
+import type { ReferenceDescriptor, NodeValidator } from "./validation-types.js";
 import { MetaModelError } from "./errors.js";
 
 export class TypeId {
@@ -107,6 +108,21 @@ export interface TypeDefinition {
   example?: string;
   /** FR-033 — guidance on when to reach for this type/subType. Optional. */
   whenToUse?: string;
+  /** Max children of this type.subType per parent (`1` = singleton). Loader-enforced. */
+  maxOccurs?: number;
+  /** Default name for a singleton (`maxOccurs===1`) child declared with no name. */
+  defaultName?: string;
+  /**
+   * Cross-references this node's attrs declare — resolved generically against the symbol
+   * table (a dangling/kind-mismatched target fails the load). Carried by the type's
+   * registration, so a downstream provider's references validate with no core changes.
+   */
+  references?: ReferenceDescriptor[];
+  /**
+   * The type's imperative validator (logic config can't express). Invoked by the recursive
+   * validation walk. Owned by the provider that owns the type.
+   */
+  validate?: NodeValidator;
 }
 
 export class TypeRegistry {