@metaobjectsdev/metadata 0.5.0 → 0.6.0-rc.1

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

@@ -36,3 +36,23 @@ export const CARDINALITY_MANY = "many";
 
 export const CARDINALITY_VALUES = [CARDINALITY_ONE, CARDINALITY_MANY] as const;
 export type CardinalityValue = (typeof CARDINALITY_VALUES)[number];
+
+// ---------------------------------------------------------------------------
+// Referential action attrs (@onDelete / @onUpdate)
+// ---------------------------------------------------------------------------
+
+export const RELATIONSHIP_ATTR_ON_DELETE = "onDelete";
+export const RELATIONSHIP_ATTR_ON_UPDATE = "onUpdate";
+
+/** Referential actions — the canonical cross-language set (kebab-case, no setDefault).
+ *  MUST equal migrate-ts's FkAction union (server/typescript/packages/migrate-ts/src/types.ts). */
+export const REFERENTIAL_ACTIONS = ["cascade", "set-null", "restrict", "no-action"] as const;
+export type ReferentialAction = (typeof REFERENTIAL_ACTIONS)[number];
+
+/** Default @onDelete per relationship subtype (rollout decided defaults). */
+export const ON_DELETE_DEFAULT_BY_SUBTYPE: Readonly<Record<string, ReferentialAction>> = {
+  [RELATIONSHIP_SUBTYPE_COMPOSITION]: "cascade",
+  [RELATIONSHIP_SUBTYPE_AGGREGATION]: "set-null",
+  [RELATIONSHIP_SUBTYPE_ASSOCIATION]: "restrict",
+};
+export const ON_UPDATE_DEFAULT: ReferentialAction = "cascade";

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

@@ -11,6 +11,9 @@ import {
   RELATIONSHIP_ATTR_OBJECT_REF,
   RELATIONSHIP_ATTR_JOIN_ENTITY,
   RELATIONSHIP_ATTR_JOIN_FIELDS,
+  RELATIONSHIP_ATTR_ON_DELETE,
+  RELATIONSHIP_ATTR_ON_UPDATE,
+  REFERENTIAL_ACTIONS,
 } from "./relationship-constants.js";
 
 /** Attrs common to every relationship subtype. */
@@ -46,4 +49,19 @@ export const relationshipAttrs: AttrSchema[] = [
     required: false,
     description: "Join-table column names for N:M relationships.",
   },
+  {
+    name: RELATIONSHIP_ATTR_ON_DELETE,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    allowedValues: [...REFERENTIAL_ACTIONS],
+    description:
+      "Referential action on parent delete. Default derives from subtype (composition→cascade, aggregation→set-null, association→restrict).",
+  },
+  {
+    name: RELATIONSHIP_ATTR_ON_UPDATE,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    allowedValues: [...REFERENTIAL_ACTIONS],
+    description: "Referential action on key update. Default cascade.",
+  },
 ];

package/src/core/yaml-desugar.ts

@@ -2,37 +2,71 @@
 //
 // desugar() turns the sugared authoring object (from yaml.parse) into the
 // canonical-shaped object that buildTree (parser-core.ts) consumes. It applies
-// the four format-spec sugar rules:
+// the five format-spec sugar rules (ADR-0006):
 //   1. Fused key, subType omittable — a bare `type` key resolves to the type's
 //      registry default subType.
 //   2. Scalar-or-map body — a scalar body becomes { name: <scalar> }.
 //   3. Omit empties — absent keys stay absent; the desugar invents nothing.
 //   4. `[]` arrays — a trailing `[]` on the key strips to isArray: true.
+//   5. Sigil-free attributes (ADR-0006 D1) — every body key not in
+//      RESERVED_KEYS is treated as an inline attribute and re-prefixed with `@`
+//      when lowering to canonical JSON. Keys already prefixed with `@` are
+//      left as-is (backward-compat). Reserved structural keywords (name,
+//      package, extends, abstract, overlay, isArray, children, value) stay
+//      bare. Note: an already-`@`-prefixed reserved word remains an error
+//      downstream — parser-core's ERR_RESERVED_ATTR check fires.
 //
-// Pure and total: it never throws. Malformed fragments are collected as error
-// strings and a safe placeholder is substituted so buildTree does not
-// double-report.
+// In addition, the desugar runs the ADR-0006 D2 type-coercion guard: for every
+// inline attr whose owning (type, subType) has a declared schema, if the raw
+// JS value's type does not match the declared valueType AND the JS value is
+// one of YAML 1.2's silently coerced shapes (boolean/number/null), the
+// desugar collects an ERR_YAML_COERCION error telling the author to quote the
+// value. The check protects against the classic YAML footgun (e.g. an unquoted
+// `column: TRUE` becoming the boolean `true` instead of the string "TRUE").
+//
+// Pure and total: it never throws. Malformed fragments are collected as
+// CollectedError entries (a string message + optional stable error code) and a
+// safe placeholder is substituted so buildTree does not double-report.
 
-import type { TypeRegistry } from "../registry.js";
+import type { TypeRegistry, AttrSchema } from "../registry.js";
+import type { ErrorCode } from "../errors.js";
 import {
+  ATTR_PREFIX,
+  RESERVED_KEYS,
   RESERVED_KEY_CHILDREN,
   RESERVED_KEY_NAME,
   RESERVED_KEY_IS_ARRAY,
   TYPE_SUBTYPE_SEPARATOR,
 } from "../shared/structural.js";
+import {
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_CLASS,
+  ATTR_SUBTYPE_INT,
+  ATTR_SUBTYPE_LONG,
+  ATTR_SUBTYPE_DOUBLE,
+  ATTR_SUBTYPE_BOOLEAN,
+  ATTR_SUBTYPE_STRINGARRAY,
+} from "./attr/attr-constants.js";
 
 const ARRAY_SUFFIX = "[]";
 
+/** A collected desugar problem — message plus optional stable error code. */
+export interface CollectedError {
+  message: string;
+  /** Optional stable code; absent values map to ERR_MALFORMED_YAML in parser-yaml.ts. */
+  code?: ErrorCode;
+}
+
 export interface DesugarResult {
   /** The canonical-shaped object; `{}` when the document was unusable. */
   canonical: Record<string, unknown>;
   /** Collected desugar problems (never thrown). */
-  errors: string[];
+  errors: CollectedError[];
 }
 
 /** Desugar a parsed-YAML authoring document into a canonical-shaped object. */
 export function desugar(input: unknown, registry: TypeRegistry): DesugarResult {
-  const errors: string[] = [];
+  const errors: CollectedError[] = [];
   const node = desugarNode(input, registry, errors, "<root>");
   return { canonical: node ?? {}, errors };
 }
@@ -43,21 +77,22 @@ export function desugar(input: unknown, registry: TypeRegistry): DesugarResult {
 function desugarNode(
   input: unknown,
   registry: TypeRegistry,
-  errors: string[],
+  errors: CollectedError[],
   path: string,
 ): Record<string, unknown> | undefined {
   if (typeof input !== "object" || input === null || Array.isArray(input)) {
-    errors.push(`Node at ${path} must be a mapping with one type key`);
+    errors.push({ message: `Node at ${path} must be a mapping with one type key` });
     return undefined;
   }
 
   const entries = Object.keys(input as Record<string, unknown>);
   if (entries.length !== 1) {
-    errors.push(
-      `Node at ${path} must have exactly one type key (found: ${
-        entries.length === 0 ? "none" : entries.join(", ")
-      })`,
-    );
+    errors.push({
+      message:
+        `Node at ${path} must have exactly one type key (found: ${
+          entries.length === 0 ? "none" : entries.join(", ")
+        })`,
+    });
     return undefined;
   }
 
@@ -76,7 +111,7 @@ function desugarNode(
   const canonicalKey = resolveKey(key, registry, errors, path);
 
   // Rule 2: a scalar body → { name: <scalar> }.
-  const body = desugarBody(rawBody, errors, path);
+  const body = desugarBody(rawBody, registry, canonicalKey, errors, path);
 
   // Rule 4 (cont.): stamp isArray onto the canonical body.
   if (isArray) body[RESERVED_KEY_IS_ARRAY] = true;
@@ -103,25 +138,36 @@ function desugarNode(
 function resolveKey(
   key: string,
   registry: TypeRegistry,
-  errors: string[],
+  errors: CollectedError[],
   path: string,
 ): string {
   if (key.includes(TYPE_SUBTYPE_SEPARATOR)) return key; // already fused
   const subType = registry.defaultSubTypeOf(key);
   if (subType === undefined) {
-    errors.push(
-      `Cannot resolve subType for bare type key '${key}' at ${path} — ` +
+    errors.push({
+      message:
+        `Cannot resolve subType for bare type key '${key}' at ${path} — ` +
         `type '${key}' has no default subType; write the full 'type.subType'`,
-    );
+    });
     return key; // pass through; buildTree reports the unknown type
   }
   return `${key}${TYPE_SUBTYPE_SEPARATOR}${subType}`;
 }
 
-// Rule 2 — normalize a node body into a canonical mapping.
+// Rule 2 + 5 — normalize a node body into a canonical mapping. Reserved
+// structural keys stay bare; every other key is treated as an inline attribute
+// and `@`-prefixed (Rule 5 / ADR-0006 D1). Keys already starting with `@` are
+// kept as-authored so the awkward "@column: foo" form remains accepted.
+//
+// Also runs the D2 type-coercion guard: for each inline attr that the owning
+// (type, subType) declares with a typed `valueType`, if the raw JS value's
+// type was silently coerced by YAML 1.2 to something incompatible (e.g. a
+// `boolean` for a `string`-declared attr), an ERR_YAML_COERCION is collected.
 function desugarBody(
   rawBody: unknown,
-  errors: string[],
+  registry: TypeRegistry,
+  canonicalKey: string,
+  errors: CollectedError[],
   path: string,
 ): Record<string, unknown> {
   if (
@@ -136,10 +182,146 @@ function desugarBody(
     return {};
   }
   if (Array.isArray(rawBody)) {
-    errors.push(`Node body at ${path} must be a scalar or mapping, not a list`);
+    errors.push({
+      message: `Node body at ${path} must be a scalar or mapping, not a list`,
+    });
     return {};
   }
   // A mapping — shallow-copy so isArray / children replacement do not mutate
-  // the caller's parsed-YAML object.
-  return { ...(rawBody as Record<string, unknown>) };
+  // the caller's parsed-YAML object, AND apply Rule 5 (sigil-free attrs) +
+  // Rule D2 (type-coercion guard).
+  const src = rawBody as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  const schemaIndex = attrSchemaIndex(registry, canonicalKey);
+  for (const key of Object.keys(src)) {
+    if (RESERVED_KEYS.has(key) || key.startsWith(ATTR_PREFIX)) {
+      out[key] = src[key];
+      // D2 also applies to author-written @-keys (the awkward form).
+      const attrName = key.startsWith(ATTR_PREFIX) ? key.slice(ATTR_PREFIX.length) : "";
+      if (attrName !== "" && !RESERVED_KEYS.has(attrName)) {
+        checkCoercion(attrName, src[key], schemaIndex, errors, path);
+      }
+    } else {
+      out[`${ATTR_PREFIX}${key}`] = src[key];
+      checkCoercion(key, src[key], schemaIndex, errors, path);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// D2 — YAML type-coercion guard
+// ---------------------------------------------------------------------------
+
+// Build a name → AttrSchema map for the given canonical key (type.subType).
+// Returns undefined when the key has no declared attrs (open schema).
+function attrSchemaIndex(
+  registry: TypeRegistry,
+  canonicalKey: string,
+): Map<string, AttrSchema> | undefined {
+  // canonicalKey is "type.subType" — split on the FIRST dot only so a subType
+  // that happens to contain a dot still works.
+  const dot = canonicalKey.indexOf(TYPE_SUBTYPE_SEPARATOR);
+  if (dot < 0) return undefined;
+  const type = canonicalKey.slice(0, dot);
+  const subType = canonicalKey.slice(dot + 1);
+  const schema = registry.attrsOf(type, subType);
+  if (schema.length === 0) return undefined;
+  const idx = new Map<string, AttrSchema>();
+  for (const spec of schema) idx.set(spec.name, spec);
+  return idx;
+}
+
+// Check a single attr value against its declared schema's `valueType`. Emits
+// an ERR_YAML_COERCION when the JS type was silently changed by YAML 1.2's
+// core schema (boolean/number/null where a string/stringarray was declared,
+// or vice versa for booleans/numbers).
+function checkCoercion(
+  attrName: string,
+  raw: unknown,
+  schemaIndex: Map<string, AttrSchema> | undefined,
+  errors: CollectedError[],
+  path: string,
+): void {
+  if (schemaIndex === undefined) return;
+  const spec = schemaIndex.get(attrName);
+  if (spec === undefined || spec.valueType === undefined) return;
+
+  switch (spec.valueType) {
+    case ATTR_SUBTYPE_STRING:
+    case ATTR_SUBTYPE_CLASS:
+      if (typeof raw !== "string") emitCoercion(attrName, raw, "string", errors, path);
+      return;
+    case ATTR_SUBTYPE_BOOLEAN:
+      if (typeof raw !== "boolean") emitCoercion(attrName, raw, "boolean", errors, path);
+      return;
+    case ATTR_SUBTYPE_INT:
+    case ATTR_SUBTYPE_LONG:
+    case ATTR_SUBTYPE_DOUBLE:
+      if (typeof raw !== "number") emitCoercion(attrName, raw, "number", errors, path);
+      return;
+    case ATTR_SUBTYPE_STRINGARRAY:
+      // A bare string at the value position is the legitimate one-element
+      // authoring shorthand for a string-array attr (StringArrayAttr.coerce
+      // wraps it into a one-element array). It is NOT a coercion. A
+      // non-string non-array scalar (boolean/number/null), however, is.
+      if (typeof raw === "string") return;
+      if (!Array.isArray(raw)) {
+        emitCoercion(attrName, raw, "string-array (or single string)", errors, path);
+        return;
+      }
+      // For an array, check every element. A non-string element is a YAML
+      // coercion (e.g. unquoted `true` in a string-array list).
+      for (let i = 0; i < raw.length; i++) {
+        if (typeof raw[i] !== "string") {
+          emitCoercion(
+            `${attrName}[${i}]`,
+            raw[i],
+            "string (in string-array)",
+            errors,
+            path,
+          );
+        }
+      }
+      return;
+    default:
+      // Object-shaped attrs (properties, filter) — accept any object/array,
+      // no YAML coercion path applies.
+      return;
+  }
+}
+
+// Build the "quote this value" error. The shape is intentionally explicit so
+// AI authors can act on it: it identifies the attr, the (coerced) JS value,
+// its JS type, the declared expected type, and a one-line fix hint.
+function emitCoercion(
+  attrName: string,
+  raw: unknown,
+  expected: string,
+  errors: CollectedError[],
+  path: string,
+): void {
+  const actualType = coercedTypeName(raw);
+  const literal = literalRepr(raw);
+  errors.push({
+    message:
+      `Attribute '@${attrName}' at ${path}: expected ${expected} but got ${actualType} (${literal}). ` +
+      `YAML 1.2 silently coerced an unquoted value — quote it in YAML: ` +
+      `'@${attrName}: "${literal}"' not '@${attrName}: ${literal}'.`,
+    code: "ERR_YAML_COERCION",
+  });
+}
+
+function coercedTypeName(raw: unknown): string {
+  if (raw === null) return "null";
+  if (Array.isArray(raw)) return "array";
+  return typeof raw;
+}
+
+function literalRepr(raw: unknown): string {
+  if (raw === null) return "null";
+  if (typeof raw === "boolean") return raw ? "true" : "false";
+  if (typeof raw === "number") return String(raw);
+  if (typeof raw === "string") return raw;
+  return JSON.stringify(raw);
 }

package/src/core-types.ts

@@ -2,6 +2,7 @@
 import { TypeId, type AttrSchema, type ChildRule, type TypeDefinition, TypeRegistry } from "./registry.js";
 import type { MetaDataTypeProvider } from "./provider.js";
 import { dbProvider } from "./persistence/db/db-provider.js";
+import { docProvider } from "./core/documentation/doc-provider.js";
 import { type DataType } from "./data-type.js";
 import type { MetaData } from "./shared/meta-data.js";
 import { MetaRoot } from "./shared/meta-root.js";
@@ -33,8 +34,8 @@ import {
 import { MetaRelationship } from "./core/relationship/meta-relationship.js";
 import { MetaLayout } from "./presentation/layout/meta-layout.js";
 import { MetaSource } from "./persistence/source/meta-source.js";
-import { MetaOrigin, MetaPassthroughOrigin, MetaAggregateOrigin } from "./persistence/origin/meta-origin.js";
-import { commonFieldAttrs, currencyFieldAttr } from "./core/field/field-schema.js";
+import { MetaOrigin, MetaPassthroughOrigin, MetaAggregateOrigin, MetaCollectionOrigin } from "./persistence/origin/meta-origin.js";
+import { commonFieldAttrs, currencyFieldAttr, enumFieldAttr } from "./core/field/field-schema.js";
 import { objectAttrs } from "./core/object/object-schema.js";
 import { relationshipAttrs } from "./core/relationship/relationship-schema.js";
 import { identityFieldsAttr, IDENTITY_ATTRS_MAP } from "./core/identity/identity-schema.js";
@@ -42,6 +43,9 @@ import { VALIDATOR_ATTRS_MAP } from "./core/validator/validator-schema.js";
 import { currencyViewAttrs } from "./presentation/view/view-schema.js";
 import { dataGridLayoutAttrs } from "./presentation/layout/layout-schema.js";
 import { ORIGIN_ATTRS_MAP } from "./persistence/origin/origin-schema.js";
+import { MetaTemplate } from "./template/meta-template.js";
+import { TEMPLATE_ATTRS_MAP } from "./template/template-schema.js";
+import { TEMPLATE_SUBTYPES } from "./template/template-constants.js";
 import {
   TYPE_METADATA,
   TYPE_OBJECT,
@@ -54,11 +58,12 @@ import {
   TYPE_LAYOUT,
   TYPE_SOURCE,
   TYPE_ORIGIN,
+  TYPE_TEMPLATE,
   SUBTYPE_ROOT,
 } from "./shared/base-types.js";
 import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
 import { OBJECT_SUBTYPES, OBJECT_SUBTYPE_ENTITY } from "./core/object/object-constants.js";
-import { FIELD_SUBTYPES, FIELD_SUBTYPE_CURRENCY } from "./core/field/field-constants.js";
+import { FIELD_SUBTYPES, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_ENUM } from "./core/field/field-constants.js";
 import { ATTR_SUBTYPES } from "./core/attr/attr-constants.js";
 import {
   VALIDATOR_SUBTYPES,
@@ -85,6 +90,7 @@ import {
   ORIGIN_SUBTYPES,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
+  ORIGIN_SUBTYPE_COLLECTION,
 } from "./persistence/origin/origin-constants.js";
 
 // ---------------------------------------------------------------------------
@@ -146,6 +152,7 @@ const IDENTITY_CLASS_MAP = new Map<string, NodeConstructor>([
 const ORIGIN_CLASS_MAP = new Map<string, NodeConstructor>([
   [ORIGIN_SUBTYPE_PASSTHROUGH, MetaPassthroughOrigin],
   [ORIGIN_SUBTYPE_AGGREGATE, MetaAggregateOrigin],
+  [ORIGIN_SUBTYPE_COLLECTION, MetaCollectionOrigin],
 ]);
 
 // ATTR_CLASS_MAP + attrClassFor live in the leaf module ./attr-class-map.ts
@@ -161,6 +168,7 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
       wildcard(TYPE_FIELD),
       wildcard(TYPE_ATTR),
       wildcard(TYPE_VALIDATOR),
+      wildcard(TYPE_TEMPLATE),
     ], MetaRoot),
   );
 
@@ -188,12 +196,14 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     wildcard(TYPE_ORIGIN),
   ];
   for (const subType of FIELD_SUBTYPES) {
-    // field.currency additionally carries @currency; all other field subtypes
-    // share the common codegen/filter attrs only.
+    // field.currency additionally carries @currency; field.enum additionally
+    // carries @values; all other field subtypes share the common attrs only.
     const fieldAttrs =
       subType === FIELD_SUBTYPE_CURRENCY
         ? [...commonFieldAttrs, { ...currencyFieldAttr }]
-        : [...commonFieldAttrs];
+        : subType === FIELD_SUBTYPE_ENUM
+          ? [...commonFieldAttrs, { ...enumFieldAttr }]
+          : [...commonFieldAttrs];
     registry.register(
       def(TYPE_FIELD, subType, `Field of type ${subType}`, fieldRules, MetaField, fieldAttrs,
         new MetaField(new TypeId(TYPE_FIELD, subType), "").dataType),
@@ -247,9 +257,10 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     );
   }
 
-  // source — declares where an object's data lives (dbTable, dbView, ...).
+  // source — declares where an object's data lives (rdb, ... per ADR-0007).
   // Only attr children; sources carry only configuration, never nested structure.
-  // DB-domain attrs (@name) are added by dbProvider via TypeRegistry.extend.
+  // Per-subtype attrs (@table/@kind/@role/@schema for rdb) are added by
+  // dbProvider via TypeRegistry.extend.
   for (const subType of SOURCE_SUBTYPES) {
     registry.register(
       def(TYPE_SOURCE, subType, `Source (${subType})`, [wildcard(TYPE_ATTR)], MetaSource, []),
@@ -268,6 +279,17 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     );
   }
 
+  // template — renderable text artifacts (FR-004). prompt + output; attr-only
+  // children. A single MetaTemplate class backs both subtypes (mirrors source);
+  // per-subtype attr schemas drive validation (both require @payloadRef +
+  // @textRef; @format is a closed enum; template.prompt adds the LLM overlay).
+  for (const subType of TEMPLATE_SUBTYPES) {
+    const templateAttrs = TEMPLATE_ATTRS_MAP.get(subType) ?? [];
+    registry.register(
+      def(TYPE_TEMPLATE, subType, `Template (${subType})`, [wildcard(TYPE_ATTR)], MetaTemplate, templateAttrs),
+    );
+  }
+
   // identity — 2 subtypes (no base; Java doesn't register one).
   // Subtype→class dispatch for TYPE_IDENTITY (formerly handled by metaOf()):
   //   primary → MetaPrimaryIdentity, secondary → MetaSecondaryIdentity,
@@ -318,7 +340,7 @@ export const coreTypesProvider: MetaDataTypeProvider = {
 
 /** The default provider bundle — core metamodel types plus DB-domain attrs.
  *  Spread it to add more: `[...coreProviders, mine]`. */
-export const coreProviders: readonly MetaDataTypeProvider[] = [coreTypesProvider, dbProvider];
+export const coreProviders: readonly MetaDataTypeProvider[] = [coreTypesProvider, dbProvider, docProvider];
 
 /**
  * Register the core metamodel into an existing registry. Thin convenience

package/src/errors.ts

@@ -7,6 +7,13 @@
 //   - ERR_MISSING_SUBTYPE: missing subType is resolved to the registry default, never an error.
 //   - ERR_INVALID_SUBTYPE_CHILD: no child-rule validation pass exists yet.
 // Cross-language conformance consumers should not expect these codes from the TS adapter.
+//
+// FR-004 build-time `verify` codes (ERR_VAR_NOT_ON_PAYLOAD, ERR_PARTIAL_UNRESOLVED,
+// ERR_REQUIRED_SLOT_UNUSED, ERR_OUTPUT_TAG_MISSING) are emitted by `meta verify` / the
+// zero-core-dependency @metaobjectsdev/render engine — NOT by the loader. They are
+// registered here (and in fixtures/conformance/ERROR-CODES.json) only to keep the code
+// vocabulary single-sourced across languages; render re-declares them locally to avoid
+// importing this package.
 export const ERROR_CODES = [
   "ERR_TOP_LEVEL_NOT_OBJECT",
   "ERR_UNKNOWN_TYPE",
@@ -28,7 +35,21 @@ export const ERROR_CODES = [
   "ERR_OVERLAY_NO_TARGET",
   "ERR_MALFORMED_YAML",
   "ERR_INVALID_ORIGIN",
+  "ERR_INVALID_TEMPLATE",
+  "ERR_VAR_NOT_ON_PAYLOAD",
+  "ERR_PARTIAL_UNRESOLVED",
+  "ERR_REQUIRED_SLOT_UNUSED",
+  "ERR_OUTPUT_TAG_MISSING",
   "ERR_BAD_ATTR_FILTER",
+  "ERR_STORAGE_FLATTENED_ARRAY",
+  "ERR_STORAGE_WITHOUT_OBJECT_REF",
+  // Source v2 (ADR-0007) error codes — enforcement added during the source-v2 rollout.
+  "ERR_RESERVED_ATTR",
+  "ERR_SOURCE_NO_PRIMARY",
+  "ERR_SOURCE_MULTIPLE_PRIMARY",
+  // ADR-0006 D2 — YAML type-coercion guard. Emitted by every port's YAML
+  // loader when a coerced scalar mismatches the schema-declared type.
+  "ERR_YAML_COERCION",
   "ERR_UNKNOWN",
 ] as const;
 

package/src/index.ts

@@ -27,12 +27,14 @@ export * from "./shared/structural.js";
 export * from "./core/object/object-constants.js";
 export * from "./core/field/field-constants.js";
 export * from "./core/attr/attr-constants.js";
+export * from "./core/documentation/doc-constants.js";
 export * from "./core/validator/validator-constants.js";
 export * from "./core/identity/identity-constants.js";
 export * from "./core/relationship/relationship-constants.js";
 export * from "./core/query/query-constants.js";
 export * from "./persistence/source/source-constants.js";
 export * from "./persistence/origin/origin-constants.js";
+export * from "./template/template-constants.js";
 export * from "./persistence/db/db-constants.js";
 export * from "./presentation/view/view-constants.js";
 export * from "./presentation/layout/layout-constants.js";
@@ -78,7 +80,10 @@ export {
   MetaOrigin,
   MetaPassthroughOrigin,
   MetaAggregateOrigin,
+  MetaCollectionOrigin,
 } from "./persistence/origin/meta-origin.js";
+// Template: single class backs both subtypes (FR-004)
+export { MetaTemplate } from "./template/meta-template.js";
 
 // Presentation node classes
 export { MetaView } from "./presentation/view/meta-view.js";
@@ -108,6 +113,8 @@ export { TypeId, TypeRegistry, childRuleMatches } from "./registry.js";
 export type { AttrSchema, ChildRule, TypeDefinition } from "./registry.js";
 export { registerCoreTypes, coreTypesProvider, coreProviders } from "./core-types.js";
 export { dbProvider } from "./persistence/db/db-provider.js";
+export { commonDocAttrs } from "./core/documentation/doc-schema.js";
+export { docProvider } from "./core/documentation/doc-provider.js";
 
 // Type provider model
 export { composeRegistry } from "./provider.js";

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

@@ -15,7 +15,8 @@ import { composeRegistry } from "../provider.js";
 import { TYPE_METADATA, SUBTYPE_ROOT } from "../shared/base-types.js";
 import { ParseError } from "../errors.js";
 import { parseJson } from "../parser-json.js";
-import { validateDataGridSortFields, validateFilterableHasIndex, validateOriginPaths, validateDataGridFilterValues } from "./validation-passes.js";
+import { validateDataGridSortFields, validateFilterableHasIndex, validateOriginPaths, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs } from "./validation-passes.js";
+import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { resolveDeferredSupers } from "../super-resolve.js";
 import { validateSubtypeRules } from "../subtype-rules.js";
 import { validateAttrSchema } from "../attr-schema-validate.js";
@@ -278,12 +279,25 @@ export class MetaDataLoader {
       // Seventh pass: @filter value validation — fields filterable + ops allowed per subtype.
       errors.push(...validateDataGridFilterValues(root));
 
+      // template.* validation — @payloadRef resolves to a known object;
+      // @requiredSlots are real fields on it (FR-004 Plan #3, T2).
+      errors.push(...validateTemplatePayloadRefs(root));
+
       // Eighth pass: attribute-schema validation (Phase A3) — checks each
       // node's @-attributes against its (type, subType) AttrSchema: required
       // attrs present, declared attrs well-typed, allowedValues honored.
       const attrSchemaResult = validateAttrSchema(root, this._registry);
       errors.push(...attrSchemaResult.errors);
       warnings.push(...attrSchemaResult.warnings);
+
+      // Ninth pass: @storage cross-attribute validation — @storage requires
+      // @objectRef, and @storage "flattened" forbids isArray=true.
+      errors.push(...validateFieldObjectStorage(root));
+
+      // Tenth pass: one-primary multi-source rule — if an object has ≥1 source,
+      // exactly one must carry role "primary" (ERR_SOURCE_NO_PRIMARY /
+      // ERR_SOURCE_MULTIPLE_PRIMARY).
+      errors.push(...validateSourceRoles(root));
     }
 
     // If nothing parsed successfully, synthesize an empty root so callers