@metaobjectsdev/metadata 0.9.0 → 0.11.0-rc.1

package/src/naming-refs.ts

@@ -0,0 +1,162 @@
+// FR-032 (ADR-0032) — canonical reference expansion.
+//
+// `expandRef(raw, packageContext)` is the SINGLE ref-expansion primitive. It
+// lowers an authored metadata reference to its fully-qualified canonical form
+// per ADR-0032 §2.1 — deterministically, with NO root fallback:
+//
+//   bare `Name` (no `::`, no leading `.`)  → `<P>::Name` (current package only;
+//                                            stays bare when P is empty/root).
+//   qualified `pkg::Name` (contains `::`,  → unchanged (absolute from root).
+//     NOT leading `::`)
+//   `::Rest` (leading `::`)                → strip the leading `::`; the
+//                                            remainder is absolute from root
+//                                            (so `::a::b::C` ≡ `a::b::C`,
+//                                            `::Apple` = root-level Apple).
+//   `..::Rest` (one or more leading `..::`) → drop one package segment from P
+//                                            per `..::`, then resolve Rest
+//                                            (itself bare/qualified) against the
+//                                            reduced package. Over-drop (more
+//                                            `..::` than P has segments) throws.
+//
+// The trailing FR-024 DOTTED CHILD suffix (`.child` / `.child.grandchild`) is
+// PRESERVED verbatim: only the OWNER part (everything before the first `.` in
+// the final `::`-segment) is expanded; the `.child...` tail is reattached.
+//
+// The desugar runs this on every ref-bearing attr so canonical JSON is FQN-only
+// (ADR-0032 §2.2/§2.3); the resolution layer then does pure FQN matching. The
+// `package` attribute is NEVER expanded — it is the node's identity.
+
+import type { MetaData } from "./shared/meta-data.js";
+import { PACKAGE_SEPARATOR, PACKAGE_PARENT, CHILD_REF_SEPARATOR } from "./shared/structural.js";
+import { RELATIONSHIP_ATTR_OBJECT_REF } from "./core/relationship/relationship-constants.js";
+import { FIELD_ATTR_OBJECT_REF } from "./core/field/field-constants.js";
+import { IDENTITY_REFERENCE_ATTR_REFERENCES } from "./core/identity/identity-constants.js";
+import {
+  ORIGIN_PASSTHROUGH_ATTR_FROM,
+  ORIGIN_PASSTHROUGH_ATTR_VIA,
+  ORIGIN_AGGREGATE_ATTR_OF,
+  ORIGIN_AGGREGATE_ATTR_VIA,
+  ORIGIN_COLLECTION_ATTR_VIA,
+} from "./persistence/origin/origin-constants.js";
+import { SOURCE_ATTR_PARAMETER_REF } from "./persistence/source/source-constants.js";
+import { TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_RESPONSE_REF } from "./template/template-constants.js";
+
+const PARENT_PREFIX = PACKAGE_PARENT + PACKAGE_SEPARATOR; // "..::"
+
+/**
+ * The inline (`@`-prefixed) attribute names whose VALUE is a metadata reference
+ * subject to FR-032 expansion/guarding (ADR-0032 §3). The structural `extends`
+ * key is handled separately (it is not `@`-prefixed). `@objectRef`/`@references`
+ * are pure object refs; `@from`/`@of`/`@via` carry an entity HEAD (possibly with
+ * a dotted relationship/field tail — expandRef preserves the tail);
+ * `@parameterRef`/`@payloadRef`/`@responseRef` reference value-objects. These are
+ * expanded by the YAML desugar and rejected (when still relative) by the
+ * canonical-JSON guard. `@sourceRefField` (a FK FIELD name, not an object ref)
+ * and `@through` are intentionally NOT in this set (out of scope for FR-032 T-slice).
+ */
+export const REF_BEARING_ATTR_NAMES: ReadonlySet<string> = new Set<string>([
+  RELATIONSHIP_ATTR_OBJECT_REF, // = FIELD_ATTR_OBJECT_REF (same spelling "objectRef")
+  FIELD_ATTR_OBJECT_REF,
+  IDENTITY_REFERENCE_ATTR_REFERENCES,
+  ORIGIN_PASSTHROUGH_ATTR_FROM,
+  ORIGIN_PASSTHROUGH_ATTR_VIA, // = ORIGIN_AGGREGATE_ATTR_VIA = ORIGIN_COLLECTION_ATTR_VIA ("via")
+  ORIGIN_AGGREGATE_ATTR_OF,
+  ORIGIN_AGGREGATE_ATTR_VIA,
+  ORIGIN_COLLECTION_ATTR_VIA,
+  SOURCE_ATTR_PARAMETER_REF,
+  TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_RESPONSE_REF,
+]);
+
+/**
+ * True when `raw` is a relative reference form (`::Rest` or `..::Rest`) that the
+ * YAML desugar must expand before canonical JSON. Canonical JSON must be FQN; a
+ * relative ref surviving into it is `ERR_RELATIVE_REF_IN_CANONICAL`.
+ */
+export function isRelativeRef(raw: string): boolean {
+  return raw.startsWith(PACKAGE_SEPARATOR) || raw.startsWith(PARENT_PREFIX);
+}
+
+/**
+ * Split a ref into its owner part (the object reference) and any FR-024 dotted
+ * child tail. The `.` that marks a child can only appear in the FINAL
+ * `::`-segment (package separators never follow a child dot), so the owner ends
+ * at the first `.` AFTER the last `::`. Returns `{ owner, tail }` where `tail`
+ * includes the leading `.` (or is "" when there is no child suffix).
+ */
+function splitChildTail(raw: string): { owner: string; tail: string } {
+  const lastSep = raw.lastIndexOf(PACKAGE_SEPARATOR);
+  const segStart = lastSep === -1 ? 0 : lastSep + PACKAGE_SEPARATOR.length;
+  const dotInSeg = raw.indexOf(CHILD_REF_SEPARATOR, segStart);
+  if (dotInSeg === -1) return { owner: raw, tail: "" };
+  return { owner: raw.slice(0, dotInSeg), tail: raw.slice(dotInSeg) };
+}
+
+/**
+ * Expand an authored reference's OWNER part (no child tail) to its FQN per
+ * ADR-0032 §2.1. Throws on parent-relative over-drop.
+ */
+function expandOwner(owner: string, packageContext: string): string {
+  // root-absolute: leading "::" → strip; the remainder is absolute from root.
+  if (owner.startsWith(PACKAGE_SEPARATOR)) {
+    return owner.slice(PACKAGE_SEPARATOR.length);
+  }
+
+  // parent-relative: one or more leading "..::".
+  if (owner.startsWith(PARENT_PREFIX)) {
+    let rest = owner;
+    let levels = 0;
+    while (rest.startsWith(PARENT_PREFIX)) {
+      levels++;
+      rest = rest.slice(PARENT_PREFIX.length);
+    }
+    const pkgParts = packageContext !== "" ? packageContext.split(PACKAGE_SEPARATOR) : [];
+    if (levels > pkgParts.length) {
+      throw new Error(
+        `Relative reference '${owner}' over-drops: ${levels} parent level(s) ` +
+          `but the package context '${packageContext}' has only ${pkgParts.length} segment(s)`,
+      );
+    }
+    const reducedPkg = pkgParts.slice(0, pkgParts.length - levels).join(PACKAGE_SEPARATOR);
+    // `rest` is itself bare/qualified — resolve it against the reduced package.
+    // (A qualified remainder still resolves bare-in-the-reduced-package per the
+    // §2.1 example `..::veg::Carrot` → `acme::veg::Carrot`.)
+    return reducedPkg !== "" ? `${reducedPkg}${PACKAGE_SEPARATOR}${rest}` : rest;
+  }
+
+  // qualified: contains "::" (not leading) → absolute, unchanged.
+  if (owner.includes(PACKAGE_SEPARATOR)) {
+    return owner;
+  }
+
+  // bare name → current package (only). Stays bare when context is empty/root.
+  return packageContext !== "" ? `${packageContext}${PACKAGE_SEPARATOR}${owner}` : owner;
+}
+
+/**
+ * Expand an authored reference to its fully-qualified canonical form per
+ * ADR-0032 §2.1, preserving any FR-024 dotted child suffix. The package context
+ * `P` is the declaring node's effective package (its own `package` or the
+ * file-default). Throws on parent-relative over-drop — the caller emits an error.
+ */
+export function expandRef(raw: string, packageContext: string): string {
+  const { owner, tail } = splitChildTail(raw);
+  return expandOwner(owner, packageContext) + tail;
+}
+
+/**
+ * FR-032 — does a root-level object `node` satisfy an (already-expanded)
+ * object reference `ref`? After the YAML desugar + corpus sweep every ref is
+ * fully qualified, so resolution is a pure FQN match. Objects keep a BARE
+ * `fqn()` per the FR5d cross-port contract, so the canonical FQN accessor is
+ * `resolutionKey()` (`<package | fileDefaultPackage>::<name>`) — this mirrors
+ * `super-resolve`'s `findInTree`. The bare `name`/`fqn()` arms cover legacy
+ * same-tree refs and root-level (empty-package) objects.
+ *
+ * This is the single matcher the non-super resolvers (origin `@from`/`@of`/
+ * `@via` heads, template `@payloadRef`/`@responseRef`, source `@parameterRef`)
+ * share, so FQN matching behaves identically everywhere a ref resolves.
+ */
+export function refMatchesObject(node: MetaData, ref: string): boolean {
+  return node.resolutionKey() === ref || node.fqn() === ref || node.name === ref;
+}

package/src/naming.ts

@@ -65,7 +65,13 @@ export function resolveTableName(entity: MetaData): string {
   // 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.
-  const source = entity.ownChildren().find(
+  //
+  // 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 => c instanceof MetaSource && c.role === SOURCE_ROLE_PRIMARY,
   );
   if (source !== undefined) return source.physicalName;
@@ -111,7 +117,9 @@ export function buildNameMap(
 ): EntityNameMap {
   const jsToDb = new Map<string, string>();
   const dbToJs = new Map<string, string>();
-  for (const child of entity.ownChildren()) {
+  // Effective children so a TPH subtype's name map covers inherited base
+  // fields + its own (FR-017); own shadows inherited on a name conflict.
+  for (const child of entity.children()) {
     if (child.type !== TYPE_FIELD) continue;
     const dbCol = resolveColumnName(child, strategy);
     jsToDb.set(child.name, dbCol);

package/src/parser-core.ts

@@ -31,7 +31,7 @@ import { canonicalSerialize, inferAttrSubType } from "./serializer-json.js";
 import { ParseError, type ErrorCode } from "./errors.js";
 import { resolvedSource, type ErrorSource, type LoaderWarning, type Contributor } from "./source.js";
 import { semanticDiff } from "./semantic-diff.js";
-import { resolveSuperRef } from "./super-resolve.js";
+import { resolveSuperRef, isChildTargetingRef } from "./super-resolve.js";
 import { JsonPathBuilder } from "./json-path.js";
 import { getYamlPosition, type YamlPosition } from "./core/yaml-positions.js";
 import {
@@ -56,8 +56,10 @@ import {
   TYPE_SUBTYPE_SEPARATOR,
   PACKAGE_SEPARATOR,
 } from "./shared/structural.js";
-import { ATTR_SUBTYPE_PROPERTIES } from "./core/attr/attr-constants.js";
+import { ATTR_SUBTYPE_PROPERTIES, ATTR_SUBTYPE_STRINGARRAY } from "./core/attr/attr-constants.js";
+import { attrClassFor } from "./attr-class-map.js";
 import type { AttrValue } from "./shared/meta-data.js";
+import { isRelativeRef, REF_BEARING_ATTR_NAMES } from "./naming-refs.js";
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -158,6 +160,44 @@ function reportProblem(
   warnings.push(msg);
 }
 
+// ---------------------------------------------------------------------------
+// FR-032 (ADR-0032) — canonical-JSON ref guard.
+//
+// Canonical JSON is the self-contained interchange form: every ref-bearing attr
+// MUST be fully-qualified. A relative authoring form (leading `::` or `..::`)
+// surviving into canonical JSON is `ERR_RELATIVE_REF_IN_CANONICAL`. The guard
+// fires ONLY for JSON-format input — YAML-format input has already been
+// desugar-expanded via expandRef (so any `::`/`..::` there is correct authoring
+// that was lowered to FQN before buildTree sees it). Like ERR_RESERVED_ATTR,
+// this is a hard error routed through the loader's error sink even in lax mode.
+// ---------------------------------------------------------------------------
+
+function guardRelativeRefInCanonical(
+  refLabel: string,
+  rawValue: unknown,
+  strict: boolean,
+  warnings: string[],
+  path: string,
+): void {
+  if (_currentFormat !== "json") return;
+  if (typeof rawValue !== "string") return;
+  if (!isRelativeRef(rawValue)) return;
+  const msg =
+    `Relative reference '${rawValue}' on ${refLabel} at ${path} is not allowed in ` +
+    `canonical JSON — canonical JSON must be fully-qualified. Relative forms ` +
+    `(leading '::' or '..::') are YAML-authoring sugar that the desugar expands.`;
+  if (strict) {
+    throw new ParseError(msg, { code: "ERR_RELATIVE_REF_IN_CANONICAL", source: errSource() });
+  }
+  if (_currentErrors !== undefined) {
+    _currentErrors.push(
+      new ParseError(msg, { code: "ERR_RELATIVE_REF_IN_CANONICAL", source: errSource() }),
+    );
+  } else {
+    warnings.push(msg);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Internal helper — split a fused wrapper key into (type, subType).
 //
@@ -479,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
@@ -530,8 +579,25 @@ function parseNodeFresh(
   // (Skipped when deferSuperResolution is true — the loader resolves after
   // all input files have been parsed, so cross-file super refs work.)
   if (model.superRef !== undefined && accumRoot !== undefined && !_deferSuperResolution) {
-    const superModel = resolveSuperRef(model.superRef, effectivePkg, accumRoot);
+    // FR-024: thread the referrer's type so dotted `Entity.child` refs resolve
+    // type-scoped — kept consistent with the deferred path (super-resolve.ts).
+    const superModel = resolveSuperRef(model.superRef, effectivePkg, accumRoot, { type: model.type });
     if (superModel !== undefined) {
+      // FR-024 — a dotted child-targeting ref must resolve to a node of the
+      // SAME type and subtype as the extending node. Dotted-only check; the
+      // shipped top-level extends behavior is unchanged.
+      if (
+        isChildTargetingRef(model.superRef) &&
+        (superModel.type !== model.type || superModel.subType !== model.subType)
+      ) {
+        throw new ParseError(
+          `the extends target '${model.superRef}' is ${superModel.type}.${superModel.subType} but the extending node '${model.fqn()}' is ${model.type}.${model.subType} — a dotted extends must target a node of the same type and subtype`,
+          {
+            code: "ERR_EXTENDS_TARGET_MISMATCH",
+            source: resolvedSource(errSource(), model.fqn(), model.superRef),
+          },
+        );
+      }
       model.setSuperResolved(superModel);
     } else {
       // FR5d — emit format=resolved with referrer + target. referrer is the
@@ -887,6 +953,9 @@ function applyReservedKeys(
     if (typeof rawExtends !== "string") {
       reportProblem(`"${RESERVED_KEY_EXTENDS}" must be a string at ${path}`, strict, warnings, "ERR_UNRESOLVED_SUPER");
     } else {
+      // FR-032: canonical JSON `extends` must be FQN; reject a surviving
+      // relative form (no-op for YAML-format input, which was desugar-expanded).
+      guardRelativeRefInCanonical(`"${RESERVED_KEY_EXTENDS}"`, rawExtends, strict, warnings, path);
       model.setSuper(rawExtends);
     }
   }
@@ -974,6 +1043,13 @@ function applyInlineAttrsAndUnknownKeys(
 
     const rawVal = nodeData[key];
 
+    // FR-032: a ref-bearing inline attr (@objectRef/@references/@from/@of/@via/
+    // @parameterRef/@payloadRef/@responseRef) in canonical JSON must be FQN —
+    // reject a surviving relative form. No-op for YAML-format input.
+    if (REF_BEARING_ATTR_NAMES.has(attrName)) {
+      guardRelativeRefInCanonical(`${ATTR_PREFIX}${attrName}`, rawVal, strict, warnings, path);
+    }
+
     try {
       const attr = materializeAttr(model, attrName, rawVal, registry);
       model.setMetaAttr(attr);
@@ -1004,16 +1080,27 @@ function materializeAttr(
   const perTypeSpec = registry.attrsOf(owner.type, owner.subType).find((s) => s.name === attrName);
   const attrSpec = perTypeSpec ?? registry.getCommonAttrs().find((s) => s.name === attrName);
   let subType: string;
-  if (attrSpec !== undefined && attrSpec.valueType !== undefined) {
+  if (attrSpec !== undefined && attrSpec.isArray === true) {
+    // An array-flagged attr (`string` + `isArray`): array-ness is the orthogonal
+    // axis the `stringarray` subtype was retired in favor of. Coerce through the
+    // array string-attr class (bare-string → one-element array) keyed off the
+    // retired-as-a-subtype-but-kept-as-a-coercion `stringarray` class-map entry.
+    subType = ATTR_SUBTYPE_STRINGARRAY;
+  } else if (attrSpec !== undefined && attrSpec.valueType !== undefined) {
     subType = attrSpec.valueType;
   } else {
     // Undeclared or declared-but-untyped (@default): preserve the author's shape.
     subType = inferUndeclaredAttrSubType(rawVal);
   }
-  const def = registry.find(TYPE_ATTR, subType);
-  const node = (def !== undefined
-    ? def.factory(def.typeId, attrName)
-    : new MetaAttr(new TypeId(TYPE_ATTR, subType), attrName)) as MetaAttr;
+  // The array-coercion class is no longer a registered (attr, subType); resolve
+  // it through the dependency-free attr-class-map (which still carries it).
+  const def = subType === ATTR_SUBTYPE_STRINGARRAY ? undefined : registry.find(TYPE_ATTR, subType);
+  const Ctor = subType === ATTR_SUBTYPE_STRINGARRAY ? attrClassFor(subType) : undefined;
+  const node = (Ctor !== undefined
+    ? new Ctor(new TypeId(TYPE_ATTR, subType), attrName)
+    : def !== undefined
+      ? def.factory(def.typeId, attrName)
+      : new MetaAttr(new TypeId(TYPE_ATTR, subType), attrName)) as MetaAttr;
   const coerced = node.coerce(rawVal);
   const desugared = node.desugar(coerced);
   node.setAttr(RESERVED_KEY_VALUE, desugared);

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

@@ -0,0 +1,234 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/db.json
+// Regenerate: bun run scripts/generate-embedded-metamodel.ts
+//
+// Embeds the canonical FR-033 ProviderDefinition so the provider can register
+// itself wherever the on-disk spec/ tree is unavailable (bundled builds).
+import type { ProviderDefinition } from "../../provider-data.js";
+
+export const DB_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-db",
+  "extends": [
+    {
+      "type": "field",
+      "subType": "*",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "column",
+          "min": 0,
+          "max": 1,
+          "description": "Physical column name for this field on an rdb source. Defaults to the field name via columnNamingStrategy."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "db.indexed",
+          "min": 0,
+          "max": 1,
+          "description": "When true, suppress the @filterable-without-index Loader warning (the field is indexed by other means)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "dbColumnType",
+          "min": 0,
+          "max": 1,
+          "description": "Physical DB column-type override (ADR-0013 escape hatch). Legal values are uuid | jsonb | timestamp_with_tz, each legal only on a specific logical field subtype (uuid/jsonb on field.string, timestamp_with_tz on field.timestamp). The logical field type and its native binding are unchanged."
+        }
+      ]
+    },
+    {
+      "type": "field",
+      "subType": "object",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "storage",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "flattened",
+            "jsonb",
+            "subdocument"
+          ],
+          "description": "Storage strategy for an object-typed field (set with @objectRef). \"flattened\" expands the nested value into prefixed columns on the parent table. \"jsonb\" stores the structured value in a single jsonb column (supports isArray=true for arrays of values). \"subdocument\" is a hint for document-store codegen targets and emits no Postgres column."
+        }
+      ]
+    },
+    {
+      "type": "field",
+      "subType": [
+        "date",
+        "time",
+        "timestamp"
+      ],
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "autoSet",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "onCreate",
+            "onUpdate"
+          ],
+          "description": "Auto-set semantics for timestamp-like fields: 'onCreate' stamps on insert, 'onUpdate' stamps on every write."
+        }
+      ]
+    },
+    {
+      "type": "source",
+      "subType": "rdb",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "table",
+          "min": 0,
+          "max": 1,
+          "description": "Physical SQL table name for source.rdb @kind: \"table\" (default). FR-016: Defaults from the source's bare structural `name` via the project's columnNamingStrategy when omitted, then from the owning entity's name. Pre-1.0 legacy spelling for view/materializedView/storedProc/tableFunction kinds during the transition; canonical-serializer rewrites to the kind-matching alias."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "view",
+          "min": 0,
+          "max": 1,
+          "description": "Physical SQL view name for source.rdb @kind: \"view\". Same internal slot as @table."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "materializedView",
+          "min": 0,
+          "max": 1,
+          "description": "Physical SQL materialized-view name for source.rdb @kind: \"materializedView\". Same internal slot as @table."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "proc",
+          "min": 0,
+          "max": 1,
+          "description": "Physical SQL stored-procedure name for source.rdb @kind: \"storedProc\". Same internal slot as @table."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "function",
+          "min": 0,
+          "max": 1,
+          "description": "Physical SQL table-function name for source.rdb @kind: \"tableFunction\". Same internal slot as @table."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "kind",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "table",
+            "view",
+            "materializedView",
+            "storedProc",
+            "tableFunction"
+          ],
+          "description": "The kind of database object this source represents: table (default, writable), view, materializedView, storedProc, or tableFunction. Non-table kinds are read-only."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "role",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "primary",
+            "replica",
+            "index",
+            "cache",
+            "publish",
+            "mirror"
+          ],
+          "description": "Role this source plays when an object has multiple sources: primary (default, system of record), replica, index, cache, publish, or mirror."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "schema",
+          "min": 0,
+          "max": 1,
+          "description": "Optional database schema name (e.g. 'catalog', 'public'). Postgres defaults to 'public'; SQLite rejects any non-default value."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "parameterRef",
+          "min": 0,
+          "max": 1,
+          "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/persistence/db/db-provider.ts

@@ -1,30 +1,25 @@
 // dbProvider — the DB-domain MetaDataTypeProvider. Registers the DB-domain
-// attributes (@column / @db.indexed on fields; @table/@kind/@role/@schema on
-// source.rdb) by extending the core-registered types. Mirrors Java's
-// CoreDBMetaDataProvider (com.metaobjects.database).
+// attributes (@column / @db.indexed / @dbColumnType + @storage on field.object,
+// @autoSet on temporal fields; @table/@kind/@role/@schema/... on source.rdb) by
+// EXTENDING the core-registered types. Mirrors Java's CoreDBMetaDataProvider
+// (com.metaobjects.database).
+//
+// FR-033 S1.5-A: the attrs + their descriptions are now DATA — read from
+// spec/metamodel/db.json (embedded as DB_DEFINITION) via the unified
+// applyProviderDefinition apply path's `extends` handling. The provider declares
+// no new types, so the factory map is empty.
 
 import type { MetaDataTypeProvider } from "../../provider.js";
 import type { TypeRegistry } from "../../registry.js";
-import { TYPE_FIELD, TYPE_SOURCE } from "../../shared/base-types.js";
-import { FIELD_SUBTYPES } from "../../core/field/field-constants.js";
-import { SOURCE_SUBTYPE_RDB } from "../source/source-constants.js";
-import { columnSchema, dbIndexedSchema, dbColumnTypeSchema } from "./db-schema.js";
-import { sourceRdbAttrs } from "../source/source-schema.js";
+import { applyProviderDefinition } from "../../provider-data.js";
+import { DB_DEFINITION } from "./db-definition.embedded.js";
 
 export const dbProvider: MetaDataTypeProvider = {
   id: "metaobjects-db",
   dependencies: ["metaobjects-core-types"],
   description:
-    "DB-domain attributes — @column / @db.indexed / @dbColumnType on fields, @table/@kind/@role/@schema on source.rdb.",
+    "DB-domain attributes — @column / @db.indexed / @dbColumnType on every field, @storage on field.object, @autoSet on temporal fields, @table/@kind/@role/@schema on source.rdb.",
   registerTypes(registry: TypeRegistry): void {
-    for (const subType of FIELD_SUBTYPES) {
-      registry.extend(TYPE_FIELD, subType, {
-        attributes: [columnSchema, dbIndexedSchema, dbColumnTypeSchema],
-      });
-    }
-    // source.rdb — @table/@kind/@role/@schema attrs.
-    registry.extend(TYPE_SOURCE, SOURCE_SUBTYPE_RDB, {
-      attributes: [...sourceRdbAttrs],
-    });
+    applyProviderDefinition(registry, DB_DEFINITION, {});
   },
 };