@metaobjectsdev/metadata 0.5.0 → 0.6.0-rc.1

package/dist/template/template-constants.js

@@ -0,0 +1,46 @@
+// template.* subtype vocabulary + reserved attribute names (FR-004, R1).
+//
+// `template` is the fourth-pillar base type: a renderable text artifact bound to
+// a typed payload. Two subtypes (by audience/structure, NOT by format):
+//   - prompt: LLM-targeted; carries the prompt-overlay attrs and is the home for
+//     future structured-prompt (role/turn/tool) divergence.
+//   - output: every other rendered artifact (email, export, docs, config).
+//
+// Format is the @format ATTRIBUTE (closed set below), never a subtype — the
+// render engine keys its escaper off @format, so a new format costs one escaper
+// + one enum value, not a new subtype + cross-language port.
+import { SUBTYPE_BASE } from "../shared/base-types.js";
+export const TEMPLATE_SUBTYPE_PROMPT = "prompt";
+export const TEMPLATE_SUBTYPE_OUTPUT = "output";
+export const TEMPLATE_SUBTYPES = [
+    SUBTYPE_BASE,
+    TEMPLATE_SUBTYPE_PROMPT,
+    TEMPLATE_SUBTYPE_OUTPUT,
+];
+// Generic reserved attrs (both subtypes). The "@" is applied at wire time.
+export const TEMPLATE_ATTR_PAYLOAD_REF = "payloadRef";
+export const TEMPLATE_ATTR_TEXT_REF = "textRef";
+export const TEMPLATE_ATTR_FORMAT = "format";
+export const TEMPLATE_ATTR_MAX_CHARS = "maxChars";
+export const TEMPLATE_ATTR_OWNER = "owner";
+export const TEMPLATE_ATTR_SINCE = "since";
+// Output tags the rendered text must contain (drives the verify output-tag check).
+// Generic — not prompt-only: any rendered artifact (email, export, prompt) can
+// carry a tag contract a downstream parser depends on.
+export const TEMPLATE_ATTR_REQUIRED_TAGS = "requiredTags";
+// Prompt-overlay attrs (template.prompt only).
+export const TEMPLATE_ATTR_MAX_TOKENS = "maxTokens";
+export const TEMPLATE_ATTR_REQUIRED_SLOTS = "requiredSlots";
+export const TEMPLATE_ATTR_MODEL = "model";
+// Closed format set — escaping/whitespace behavior is keyed off this in the
+// render engine's escaper registry (FR-004 R7).
+export const TEMPLATE_FORMATS = [
+    "text",
+    "html",
+    "xml",
+    "csv",
+    "json",
+    "markdown",
+    "spreadsheet",
+];
+//# sourceMappingURL=template-constants.js.map

package/dist/template/template-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-constants.js","sourceRoot":"","sources":["../../src/template/template-constants.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,EAAE;AACF,iFAAiF;AACjF,wEAAwE;AACxE,iFAAiF;AACjF,4DAA4D;AAC5D,2EAA2E;AAC3E,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,6DAA6D;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,MAAM,CAAC,MAAM,uBAAuB,GAAG,QAAQ,CAAC;AAChD,MAAM,CAAC,MAAM,uBAAuB,GAAG,QAAQ,CAAC;AAEhD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,YAAY;IACZ,uBAAuB;IACvB,uBAAuB;CACf,CAAC;AAGX,2EAA2E;AAC3E,MAAM,CAAC,MAAM,yBAAyB,GAAG,YAAY,CAAC;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAC7C,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC;AAClD,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAC3C,mFAAmF;AACnF,+EAA+E;AAC/E,uDAAuD;AACvD,MAAM,CAAC,MAAM,2BAA2B,GAAG,cAAc,CAAC;AAE1D,+CAA+C;AAC/C,MAAM,CAAC,MAAM,wBAAwB,GAAG,WAAW,CAAC;AACpD,MAAM,CAAC,MAAM,4BAA4B,GAAG,eAAe,CAAC;AAC5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C,4EAA4E;AAC5E,gDAAgD;AAChD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,MAAM;IACN,MAAM;IACN,KAAK;IACL,KAAK;IACL,MAAM;IACN,UAAU;IACV,aAAa;CACL,CAAC"}

package/dist/template/template-schema.d.ts

@@ -0,0 +1,3 @@
+import type { AttrSchema } from "../registry.js";
+export declare const TEMPLATE_ATTRS_MAP: Map<string, AttrSchema[]>;
+//# sourceMappingURL=template-schema.d.ts.map

package/dist/template/template-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-schema.d.ts","sourceRoot":"","sources":["../../src/template/template-schema.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AA6FjD,eAAO,MAAM,kBAAkB,2BAI7B,CAAC"}

package/dist/template/template-schema.js

@@ -0,0 +1,84 @@
+// Reserved-attribute schemas per template subtype (FR-004, R1).
+//
+// Both subtypes share the generic attrs; @format is a closed enum (allowedValues)
+// that the render engine keys its escaper off. template.prompt additionally
+// carries the LLM-overlay attrs. References (@payloadRef, @textRef) are plain
+// strings here — resolution against a real payload / text source is render-time
+// `verify` scope (Plan #3), not load-time validation.
+import { ATTR_SUBTYPE_STRING, ATTR_SUBTYPE_INT, ATTR_SUBTYPE_STRINGARRAY, } from "../core/attr/attr-constants.js";
+import { SUBTYPE_BASE } from "../shared/base-types.js";
+import { TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_FORMAT, TEMPLATE_ATTR_MAX_CHARS, TEMPLATE_ATTR_OWNER, TEMPLATE_ATTR_SINCE, TEMPLATE_ATTR_REQUIRED_TAGS, TEMPLATE_ATTR_MAX_TOKENS, TEMPLATE_ATTR_REQUIRED_SLOTS, TEMPLATE_ATTR_MODEL, TEMPLATE_FORMATS, } from "./template-constants.js";
+// Generic attrs shared by template.prompt and template.output.
+const genericAttrs = [
+    {
+        name: TEMPLATE_ATTR_PAYLOAD_REF,
+        valueType: ATTR_SUBTYPE_STRING,
+        required: true,
+        description: "Reference to the payload (a view-object / projection) this template renders against.",
+    },
+    {
+        name: TEMPLATE_ATTR_TEXT_REF,
+        valueType: ATTR_SUBTYPE_STRING,
+        required: true,
+        description: "2-layer logical reference (group/source) to the body text, resolved by a provider at render time.",
+    },
+    {
+        name: TEMPLATE_ATTR_FORMAT,
+        valueType: ATTR_SUBTYPE_STRING,
+        required: false,
+        default: "text",
+        allowedValues: [...TEMPLATE_FORMATS],
+        description: "Output format; drives the render engine's escaping/whitespace behavior.",
+    },
+    {
+        name: TEMPLATE_ATTR_MAX_CHARS,
+        valueType: ATTR_SUBTYPE_INT,
+        required: false,
+        description: "Size budget for the rendered output, in characters.",
+    },
+    {
+        name: TEMPLATE_ATTR_OWNER,
+        valueType: ATTR_SUBTYPE_STRING,
+        required: false,
+        description: "Governance: the owner of this template.",
+    },
+    {
+        name: TEMPLATE_ATTR_SINCE,
+        valueType: ATTR_SUBTYPE_STRING,
+        required: false,
+        description: "Governance: the version this template was introduced in.",
+    },
+    {
+        name: TEMPLATE_ATTR_REQUIRED_TAGS,
+        valueType: ATTR_SUBTYPE_STRINGARRAY,
+        required: false,
+        description: "Output tags the rendered text must contain (drives the verify output-tag check).",
+    },
+];
+// LLM-overlay attrs (template.prompt only).
+const promptOverlayAttrs = [
+    {
+        name: TEMPLATE_ATTR_MAX_TOKENS,
+        valueType: ATTR_SUBTYPE_INT,
+        required: false,
+        description: "Token budget for the rendered prompt (LLM-specific).",
+    },
+    {
+        name: TEMPLATE_ATTR_REQUIRED_SLOTS,
+        valueType: ATTR_SUBTYPE_STRINGARRAY,
+        required: false,
+        description: "Slots that must resolve at render time (drives the verify check).",
+    },
+    {
+        name: TEMPLATE_ATTR_MODEL,
+        valueType: ATTR_SUBTYPE_STRING,
+        required: false,
+        description: "Target model id (LLM-specific).",
+    },
+];
+export const TEMPLATE_ATTRS_MAP = new Map([
+    [SUBTYPE_BASE, []],
+    [TEMPLATE_SUBTYPE_PROMPT, [...genericAttrs, ...promptOverlayAttrs]],
+    [TEMPLATE_SUBTYPE_OUTPUT, [...genericAttrs]],
+]);
+//# sourceMappingURL=template-schema.js.map

package/dist/template/template-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-schema.js","sourceRoot":"","sources":["../../src/template/template-schema.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,kFAAkF;AAClF,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,sDAAsD;AAGtD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC3B,wBAAwB,EACxB,4BAA4B,EAC5B,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,+DAA+D;AAC/D,MAAM,YAAY,GAAiB;IACjC;QACE,IAAI,EAAE,yBAAyB;QAC/B,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,sFAAsF;KACpG;IACD;QACE,IAAI,EAAE,sBAAsB;QAC5B,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,mGAAmG;KACjH;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,MAAM;QACf,aAAa,EAAE,CAAC,GAAG,gBAAgB,CAAC;QACpC,WAAW,EAAE,yEAAyE;KACvF;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,SAAS,EAAE,gBAAgB;QAC3B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,qDAAqD;KACnE;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,yCAAyC;KACvD;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,0DAA0D;KACxE;IACD;QACE,IAAI,EAAE,2BAA2B;QACjC,SAAS,EAAE,wBAAwB;QACnC,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,kFAAkF;KAChG;CACF,CAAC;AAEF,4CAA4C;AAC5C,MAAM,kBAAkB,GAAiB;IACvC;QACE,IAAI,EAAE,wBAAwB;QAC9B,SAAS,EAAE,gBAAgB;QAC3B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,sDAAsD;KACpE;IACD;QACE,IAAI,EAAE,4BAA4B;QAClC,SAAS,EAAE,wBAAwB;QACnC,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,mEAAmE;KACjF;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,SAAS,EAAE,mBAAmB;QAC9B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,iCAAiC;KAC/C;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAuB;IAC9D,CAAC,YAAY,EAAE,EAAE,CAAC;IAClB,CAAC,uBAAuB,EAAE,CAAC,GAAG,YAAY,EAAE,GAAG,kBAAkB,CAAC,CAAC;IACnE,CAAC,uBAAuB,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC;CAC7C,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/metadata",
-  "version": "0.5.0",
+  "version": "0.6.0-rc.1",
   "description": "Metamodel loader, types, and constants for the MetaObjects standard.",
   "type": "module",
   "main": "./dist/index.js",

package/src/attr-schema-validate.ts

@@ -30,6 +30,12 @@
 import type { MetaData } from "./shared/meta-data.js";
 import { ParseError } from "./errors.js";
 import type { AttrSchema, TypeRegistry } from "./registry.js";
+import { TYPE_FIELD } from "./shared/base-types.js";
+import {
+  FIELD_SUBTYPE_ENUM,
+  FIELD_ATTR_VALUES,
+  ENUM_MEMBER_PATTERN,
+} from "./core/field/field-constants.js";
 
 export interface AttrSchemaValidationResult {
   errors: ParseError[];
@@ -45,7 +51,11 @@ export function validateAttrSchema(
   registry: TypeRegistry,
 ): AttrSchemaValidationResult {
   const errors: ParseError[] = [];
-  walk(root, registry, errors);
+  // Tracks (type.subType) pairs for which ERR_PROVIDER_ATTR_CONFLICT has already
+  // been emitted. The conflict is a registry-state condition, not a per-node
+  // condition — emit it once per (type, subType), not once per node instance.
+  const reportedConflicts = new Set<string>();
+  walk(root, registry, errors, reportedConflicts);
   return { errors, warnings: [] };
 }
 
@@ -53,10 +63,11 @@ function walk(
   node: MetaData,
   registry: TypeRegistry,
   errors: ParseError[],
+  reportedConflicts: Set<string>,
 ): void {
-  validateNode(node, registry, errors);
+  validateNode(node, registry, errors, reportedConflicts);
   for (const child of node.ownChildren()) {
-    walk(child, registry, errors);
+    walk(child, registry, errors, reportedConflicts);
   }
 }
 
@@ -70,13 +81,36 @@ function validateNode(
   node: MetaData,
   registry: TypeRegistry,
   errors: ParseError[],
+  reportedConflicts: Set<string>,
 ): void {
-  const schema = registry.attrsOf(node.type, node.subType);
-  if (schema.length === 0) return;
-
-  // Index the schema by attr name for the declared-attr checks below.
+  // Build the effective schema in a single pass: per-type attrs win on name
+  // collision; common attrs fill in for unclaimed names. Surface common-vs-per-type
+  // collisions in the same pass — a name in both lists means a provider tried to
+  // overload a declared attr. The conflict is registry-state (not per-node), so
+  // emit ONE error per (type, subType), tracked via `reportedConflicts`.
+  // Even when a conflict exists, the per-type attr still wins (the common attr
+  // for that name is suppressed) so type-checking proceeds normally for everything else.
   const byName = new Map<string, AttrSchema>();
-  for (const spec of schema) byName.set(spec.name, spec);
+  for (const spec of registry.attrsOf(node.type, node.subType)) byName.set(spec.name, spec);
+
+  const typeKey = `${node.type}.${node.subType}`;
+  for (const ca of registry.getCommonAttrs()) {
+    if (byName.has(ca.name)) {
+      if (!reportedConflicts.has(typeKey)) {
+        errors.push(
+          new ParseError(
+            `Common attr '${ca.name}' conflicts with per-type attr on ${typeKey}`,
+            { code: "ERR_PROVIDER_ATTR_CONFLICT" },
+          ),
+        );
+        reportedConflicts.add(typeKey);
+      }
+      continue; // per-type wins
+    }
+    byName.set(ca.name, ca);
+  }
+
+  if (byName.size === 0) return;
 
   // --- Check 1: required attrs present ---
   //
@@ -87,7 +121,7 @@ function validateNode(
   // were already validated on the node that declared them, so re-checking would
   // double-report. This mirrors the effective-vs-own split in subtype-rules.ts.
   const effective = node.attrs();
-  for (const spec of schema) {
+  for (const spec of byName.values()) {
     if (spec.required && !effective.has(spec.name)) {
       errors.push(
         new ParseError(
@@ -131,4 +165,50 @@ function validateNode(
       }
     }
   }
+
+  // --- Check 4: field.enum @values content rules ---
+  //
+  // Only for field.enum nodes that carry an own @values attr (concrete or
+  // abstract). Concrete fields that extend an abstract enum inherit @values
+  // from the super; the super was already validated when it was declared, so
+  // only own @values need checking here (mirrors the own-attrs-only policy of
+  // Checks 2+3 above — inherited attrs were validated on the declaring node).
+  if (node.type === TYPE_FIELD && node.subType === FIELD_SUBTYPE_ENUM) {
+    const rawValues = node.ownAttrs().get(FIELD_ATTR_VALUES);
+    if (Array.isArray(rawValues)) {
+      if (rawValues.length === 0) {
+        errors.push(
+          new ParseError(
+            `${nodeLabel(node)} must declare at least one value in '@${FIELD_ATTR_VALUES}'.`,
+            { code: "ERR_BAD_ATTR_VALUE" },
+          ),
+        );
+      } else {
+        // rawValues is the only array variant of AttrValue, so each member is a
+        // string (StringArrayAttr.coerce stringifies every element on load).
+        const seen = new Set<string>();
+        for (const member of rawValues) {
+          if (!ENUM_MEMBER_PATTERN.test(member)) {
+            errors.push(
+              new ParseError(
+                `${nodeLabel(node)} attribute '@${FIELD_ATTR_VALUES}' member '${member}' ` +
+                  `is not a valid identifier (must match ${ENUM_MEMBER_PATTERN.source}). ` +
+                  `Non-identifier-safe member strings require a symbol↔value mapping (deferred).`,
+                { code: "ERR_BAD_ATTR_VALUE" },
+              ),
+            );
+          } else if (seen.has(member)) {
+            errors.push(
+              new ParseError(
+                `${nodeLabel(node)} attribute '@${FIELD_ATTR_VALUES}' has duplicate member '${member}'.`,
+                { code: "ERR_BAD_ATTR_VALUE" },
+              ),
+            );
+          } else {
+            seen.add(member);
+          }
+        }
+      }
+    }
+  }
 }

package/src/core/documentation/doc-constants.ts

@@ -0,0 +1,22 @@
+// Documentation common-attr constants. Bare names — the @-prefix is added by
+// the serializer per ADR-0006.
+
+export const DOC_ATTR_DESCRIPTION = "description";
+export const DOC_ATTR_TITLE = "title";
+export const DOC_ATTR_NOTES = "notes";
+export const DOC_ATTR_DEPRECATED = "deprecated";
+export const DOC_ATTR_REPLACED_BY = "replacedBy";
+export const DOC_ATTR_SEE_ALSO = "seeAlso";
+export const DOC_ATTR_ALIASES = "aliases";
+
+/** All 7 documentation common-attr names in declaration order. */
+export const DOC_ATTR_NAMES = [
+  DOC_ATTR_DESCRIPTION,
+  DOC_ATTR_TITLE,
+  DOC_ATTR_NOTES,
+  DOC_ATTR_DEPRECATED,
+  DOC_ATTR_REPLACED_BY,
+  DOC_ATTR_SEE_ALSO,
+  DOC_ATTR_ALIASES,
+] as const;
+export type DocAttrName = (typeof DOC_ATTR_NAMES)[number];

package/src/core/documentation/doc-provider.ts

@@ -0,0 +1,12 @@
+import type { MetaDataTypeProvider } from "../../provider.js";
+import type { TypeRegistry } from "../../registry.js";
+import { commonDocAttrs } from "./doc-schema.js";
+
+export const docProvider: MetaDataTypeProvider = {
+  id: "metaobjects-documentation",
+  dependencies: ["metaobjects-core-types"],
+  description: "Universal documentation common attrs (description / title / notes / deprecated / replacedBy / seeAlso / aliases) accepted on every metatype.",
+  registerTypes(registry: TypeRegistry): void {
+    registry.registerCommonAttrs(commonDocAttrs);
+  },
+};

package/src/core/documentation/doc-schema.ts

@@ -0,0 +1,64 @@
+import { type AttrSchema } from "../../registry.js";
+import {
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_STRINGARRAY,
+} from "../attr/attr-constants.js";
+import {
+  DOC_ATTR_ALIASES,
+  DOC_ATTR_DEPRECATED,
+  DOC_ATTR_DESCRIPTION,
+  DOC_ATTR_NOTES,
+  DOC_ATTR_REPLACED_BY,
+  DOC_ATTR_SEE_ALSO,
+  DOC_ATTR_TITLE,
+} from "./doc-constants.js";
+
+/**
+ * The 7 universal documentation common attrs. Registered via the
+ * registry.registerCommonAttrs() hook by the documentation provider.
+ * Per ADR-0006, attr names are bare here; the serializer prefixes with @.
+ */
+export const commonDocAttrs: AttrSchema[] = [
+  {
+    name: DOC_ATTR_DESCRIPTION,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Free-form user-facing prose. Markdown allowed, multi-line via YAML '|' block scalar. Flows into doc-gen surfaces (JSDoc / XML-doc / Postgres COMMENT / Mermaid prose).",
+  },
+  {
+    name: DOC_ATTR_TITLE,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Short single-line human label (e.g. 'Email' for a `field.string email`). Optional supplement to description.",
+  },
+  {
+    name: DOC_ATTR_NOTES,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Internal-only rationale. Stays in metadata; never emitted to user-facing docs.",
+  },
+  {
+    name: DOC_ATTR_DEPRECATED,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Text reason for deprecation. Presence ⇒ deprecated. Codegen emits @deprecated / [Obsolete] with this reason.",
+  },
+  {
+    name: DOC_ATTR_REPLACED_BY,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "FQN reference to the replacement element. Only meaningful with `deprecated`. Codegen appends 'Replaced by <ref>' to deprecation messages.",
+  },
+  {
+    name: DOC_ATTR_SEE_ALSO,
+    valueType: ATTR_SUBTYPE_STRINGARRAY,
+    required: false,
+    description: "External documentation URLs. Codegen emits @see / <seealso href=...>.",
+  },
+  {
+    name: DOC_ATTR_ALIASES,
+    valueType: ATTR_SUBTYPE_STRINGARRAY,
+    required: false,
+    description: "Alternate names for this element. Aids AI authoring disambiguation, search, migration.",
+  },
+];

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

@@ -3,7 +3,7 @@
 import { SUBTYPE_BASE } from "../../shared/base-types.js";
 
 // ---------------------------------------------------------------------------
-// Field subtypes (15)
+// Field subtypes (16)
 // ---------------------------------------------------------------------------
 
 export const FIELD_SUBTYPE_STRING = "string";
@@ -21,6 +21,7 @@ export const FIELD_SUBTYPE_TIMESTAMP = "timestamp";
 export const FIELD_SUBTYPE_OBJECT = "object";
 export const FIELD_SUBTYPE_CLASS = "class";
 export const FIELD_SUBTYPE_CURRENCY = "currency";
+export const FIELD_SUBTYPE_ENUM = "enum";
 
 export const FIELD_SUBTYPES = [
   SUBTYPE_BASE,
@@ -39,6 +40,7 @@ export const FIELD_SUBTYPES = [
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_CLASS,
   FIELD_SUBTYPE_CURRENCY,
+  FIELD_SUBTYPE_ENUM,
 ] as const;
 export type FieldSubType = (typeof FIELD_SUBTYPES)[number];
 
@@ -63,6 +65,30 @@ export const FIELD_ATTR_AUTO_SET = "autoSet";
  *  spelling as the relationship `@objectRef` — Java's single ATTR_OBJECT_REF. */
 export const FIELD_ATTR_OBJECT_REF = "objectRef";
 
+/** Storage strategy for an object-typed field. Meaningful only when @objectRef is set.
+ *  Cross-language metamodel attr — every port must accept and round-trip it. */
+export const FIELD_ATTR_STORAGE = "storage";
+
+/** @storage "flattened" — nested object's columns expand into the parent table,
+ *  each prefixed by the parent field's DB name (EF OwnsOne pattern). Requires
+ *  the parent field.object to have isArray=false; arrays-of-values must use jsonb. */
+export const STORAGE_FLATTENED = "flattened";
+
+/** @storage "jsonb" — the nested value (or array of values when isArray=true) lives
+ *  in a single jsonb column. The structure is typed by metadata; storage is opaque. */
+export const STORAGE_JSONB = "jsonb";
+
+/** @storage "subdocument" — document-store-native nested document. No Postgres
+ *  column is emitted for this; codegen targets like Mongo render it inline. */
+export const STORAGE_SUBDOCUMENT = "subdocument";
+
+export const STORAGE_VALUES = [
+  STORAGE_FLATTENED,
+  STORAGE_JSONB,
+  STORAGE_SUBDOCUMENT,
+] as const;
+export type StorageValue = (typeof STORAGE_VALUES)[number];
+
 export const AUTO_SET_ON_CREATE = "onCreate";
 export const AUTO_SET_ON_UPDATE = "onUpdate";
 
@@ -77,3 +103,17 @@ export type AutoSetValue = (typeof AUTO_SET_VALUES)[number];
 export const FIELD_ATTR_CURRENCY = "currency";
 /** Default ISO 4217 currency code when @currency is omitted on a currency field. */
 export const FIELD_ATTR_CURRENCY_DEFAULT = "USD";
+
+// ---------------------------------------------------------------------------
+// Enum attrs (on enum-subtype fields)
+// ---------------------------------------------------------------------------
+
+/** Member symbols of an enum-subtype field. Required, string array. */
+export const FIELD_ATTR_VALUES = "values";
+
+/**
+ * Pattern every enum member must satisfy: a legal identifier in all target
+ * languages (TS union member, Java/C#/Python enum member). Ensures symbol ==
+ * stored string with no name↔value divergence.
+ */
+export const ENUM_MEMBER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;

package/src/core/field/field-schema.ts

@@ -6,10 +6,13 @@ import {
   ATTR_SUBTYPE_STRING,
   ATTR_SUBTYPE_INT,
   ATTR_SUBTYPE_BOOLEAN,
+  ATTR_SUBTYPE_STRINGARRAY,
 } from "../attr/attr-constants.js";
 import { SORT_ORDER_VALUES } from "../query/query-constants.js";
 import {
   FIELD_ATTR_OBJECT_REF,
+  FIELD_ATTR_STORAGE,
+  STORAGE_VALUES,
   FIELD_ATTR_REQUIRED,
   FIELD_ATTR_UNIQUE,
   FIELD_ATTR_DEFAULT,
@@ -23,6 +26,7 @@ import {
   FIELD_ATTR_CURRENCY_DEFAULT,
   FIELD_ATTR_AUTO_SET,
   AUTO_SET_VALUES,
+  FIELD_ATTR_VALUES,
 } from "./field-constants.js";
 
 /** Attrs common to every field subtype (codegen-ts column mapper + Project D filter/sort). */
@@ -34,6 +38,18 @@ export const commonFieldAttrs: AttrSchema[] = [
     description:
       "Name (or FQN) of the target object an object-typed field nests — drives nested-object (de)serialization.",
   },
+  {
+    name: FIELD_ATTR_STORAGE,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    allowedValues: [...STORAGE_VALUES],
+    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.",
+  },
   {
     name: FIELD_ATTR_REQUIRED,
     valueType: ATTR_SUBTYPE_BOOLEAN,
@@ -119,3 +135,12 @@ export const currencyFieldAttr: AttrSchema = {
   description:
     "ISO 4217 currency code for a currency-subtype field. Storage is integer minor units; defaults to 'USD' when omitted.",
 };
+
+/** The @values attr — only on field.enum. Required string array. */
+export const enumFieldAttr: AttrSchema = {
+  name: FIELD_ATTR_VALUES,
+  valueType: ATTR_SUBTYPE_STRINGARRAY,
+  required: true,
+  description:
+    "Member symbols of an enum-subtype field. Declaration order is significant; each is a legal identifier and its own stored string.",
+};

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

@@ -33,6 +33,7 @@ import {
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_OBJECT,
+  FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_REQUIRED,
   FIELD_ATTR_UNIQUE,
   FIELD_ATTR_DEFAULT,
@@ -41,7 +42,7 @@ import {
   FIELD_ATTR_SCALE,
   FIELD_ATTR_OBJECT_REF,
 } from "./field-constants.js";
-import { FIELD_ATTR_DB_COLUMN } from "../../persistence/db/db-constants.js";
+import { FIELD_ATTR_COLUMN } from "../../persistence/db/db-constants.js";
 import { VALIDATOR_SUBTYPE_REQUIRED } from "../validator/validator-constants.js";
 import type { MetaValidator } from "../validator/meta-validator.js";
 import type { MetaView } from "../../presentation/view/meta-view.js";
@@ -57,6 +58,7 @@ const FIELD_DATA_TYPE: Readonly<Record<string, DataType>> = {
   [FIELD_SUBTYPE_BYTE]: DATA_TYPE_INT,
   [FIELD_SUBTYPE_LONG]: DATA_TYPE_LONG,
   [FIELD_SUBTYPE_CURRENCY]: DATA_TYPE_LONG,
+  [FIELD_SUBTYPE_ENUM]: DATA_TYPE_STRING,
   [FIELD_SUBTYPE_DOUBLE]: DATA_TYPE_DOUBLE,
   [FIELD_SUBTYPE_FLOAT]: DATA_TYPE_DOUBLE,
   [FIELD_SUBTYPE_DECIMAL]: DATA_TYPE_DOUBLE,
@@ -84,8 +86,9 @@ export class MetaField extends MetaData implements DataTypeAware {
     return typeof v === "string" ? v : undefined;
   }
 
-  get dbColumn(): string | undefined {
-    const v = this.ownAttr(FIELD_ATTR_DB_COLUMN);
+  /** Physical column name override (`@column` attr). */
+  get column(): string | undefined {
+    const v = this.ownAttr(FIELD_ATTR_COLUMN);
     return typeof v === "string" ? v : undefined;
   }
 

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

@@ -9,13 +9,12 @@ import {
   TYPE_IDENTITY,
   TYPE_RELATIONSHIP,
   TYPE_VALIDATOR,
-  TYPE_SOURCE,
   TYPE_LAYOUT,
 } from "../../shared/base-types.js";
 import {
-  SOURCE_SUBTYPE_DB_TABLE,
-  SOURCE_DB_TABLE_ATTR_NAME,
+  SOURCE_ROLE_PRIMARY,
 } from "../../persistence/source/source-constants.js";
+import { MetaSource } from "../../persistence/source/meta-source.js";
 import {
   OBJECT_SUBTYPE_ENTITY,
   OBJECT_SUBTYPE_VALUE,
@@ -34,11 +33,12 @@ import type { MetaValidator } from "../validator/meta-validator.js";
 export class MetaObject extends MetaData {
   get dbTable(): string | undefined {
     return this.cached("dbTable", () => {
+      // The primary writable source carries the physical table name (@table).
       const source = this.children().find(
-        (c) => c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_DB_TABLE,
+        (c): c is MetaSource =>
+          c instanceof MetaSource && c.isWritable() && c.role === SOURCE_ROLE_PRIMARY,
       );
-      const name = source?.ownAttr(SOURCE_DB_TABLE_ATTR_NAME);
-      return typeof name === "string" && name !== "" ? name : undefined;
+      return source?.tableName;
     });
   }
 

package/src/core/parser-yaml.ts

@@ -34,17 +34,25 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   // If the desugar could not produce a usable document at all, surface the
   // first desugar error as a throw — parallels parseJson's top-level throws.
   if (Object.keys(canonical).length === 0) {
+    const first = desugarErrors[0]!;
     throw new ParseError(
-      desugarErrors[0]!,
-      { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" },
+      first.message,
+      { ...errOpts(opts.sourceName), code: first.code ?? "ERR_MALFORMED_YAML" },
     );
   }
 
   const result = buildTree(canonical, opts);
 
   // Merge collected desugar errors ahead of buildTree's own collected errors.
+  // Each CollectedError carries its own stable code when set (e.g.
+  // ERR_YAML_COERCION from the D2 type-coercion guard); the malformed-document
+  // shape errors fall back to ERR_MALFORMED_YAML.
   const desugarParseErrors = desugarErrors.map(
-    (msg) => new ParseError(msg, { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" }),
+    (e) =>
+      new ParseError(e.message, {
+        ...errOpts(opts.sourceName),
+        code: e.code ?? "ERR_MALFORMED_YAML",
+      }),
   );
   return {
     root: result.root,

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

@@ -8,6 +8,8 @@ import {
   RELATIONSHIP_ATTR_OBJECT_REF,
   RELATIONSHIP_ATTR_JOIN_ENTITY,
   RELATIONSHIP_ATTR_JOIN_FIELDS,
+  RELATIONSHIP_ATTR_ON_DELETE,
+  RELATIONSHIP_ATTR_ON_UPDATE,
 } from "./relationship-constants.js";
 
 export class MetaRelationship extends MetaData {
@@ -33,4 +35,16 @@ export class MetaRelationship extends MetaData {
     const f = this.ownAttr(RELATIONSHIP_ATTR_JOIN_FIELDS);
     return Array.isArray(f) ? (f as string[]) : [];
   }
+
+  /** Referential action on parent delete. Undefined when not explicitly set (default derives from subtype). */
+  get onDelete(): string | undefined {
+    const v = this.ownAttr(RELATIONSHIP_ATTR_ON_DELETE);
+    return typeof v === "string" && v !== "" ? v : undefined;
+  }
+
+  /** Referential action on key update. Undefined when not explicitly set (default: cascade). */
+  get onUpdate(): string | undefined {
+    const v = this.ownAttr(RELATIONSHIP_ATTR_ON_UPDATE);
+    return typeof v === "string" && v !== "" ? v : undefined;
+  }
 }