@metaobjectsdev/metadata 0.5.0-rc.3 → 0.6.0-rc.1

package/src/loader/validation-passes.ts

@@ -4,7 +4,8 @@
 // warnings. No loader state is read or written — these are pure functions.
 //
 // Exported: validateDataGridSortFields, validateFilterableHasIndex,
-//           validateOriginPaths  (called by MetaDataLoader.load() in order).
+//           validateOriginPaths, validateDataGridFilterValues,
+//           validateFieldObjectStorage  (called by MetaDataLoader.load() in order).
 // Private:  _findObject, _findField, _findRelationship,
 //           _validateFromPath, _validateViaPath  (helpers, not exported).
 
@@ -17,7 +18,12 @@ import {
   TYPE_IDENTITY,
   TYPE_ORIGIN,
   TYPE_RELATIONSHIP,
+  TYPE_TEMPLATE,
 } from "../shared/base-types.js";
+import {
+  TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_REQUIRED_SLOTS,
+} from "../template/template-constants.js";
 import {
   LAYOUT_SUBTYPE_DATA_GRID,
   LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD,
@@ -25,6 +31,9 @@ import {
 } from "../presentation/layout/layout-constants.js";
 import {
   FIELD_ATTR_FILTERABLE,
+  FIELD_ATTR_OBJECT_REF,
+  FIELD_ATTR_STORAGE,
+  STORAGE_FLATTENED,
 } 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";
@@ -72,6 +81,52 @@ export function validateDataGridSortFields(root: MetaData): ParseError[] {
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// template.* @payloadRef / @requiredSlots validation (FR-004 Plan #3, T2)
+//
+// Metadata-internal half of `verify` — runs at load time (no provider needed):
+//   - @payloadRef resolves to a known object (the payload view-object)
+//   - every @requiredSlots entry is a real field on that payload
+// The template-text half (every {{var}} resolves to a payload field) needs the
+// external template text via a provider, so it lives in the build-time
+// `meta verify` step, not here.
+// ---------------------------------------------------------------------------
+
+export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const tmpl of root.ownChildren().filter((c) => c.type === TYPE_TEMPLATE)) {
+    const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
+    if (typeof payloadRef !== "string") continue; // absence handled by the required-attr schema check
+    const payload = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === payloadRef);
+    if (!payload) {
+      errors.push(
+        new ParseError(
+          `template "${tmpl.name}" @payloadRef "${payloadRef}" does not resolve to a known object in this model`,
+          { code: "ERR_INVALID_TEMPLATE" },
+        ),
+      );
+      continue;
+    }
+    const fieldNames = new Set(
+      payload.children().filter((c) => c.type === TYPE_FIELD).map((f) => f.name),
+    );
+    const slots = tmpl.ownAttr(TEMPLATE_ATTR_REQUIRED_SLOTS);
+    const slotList = Array.isArray(slots) ? slots : typeof slots === "string" ? [slots] : [];
+    for (const slot of slotList) {
+      if (typeof slot === "string" && !fieldNames.has(slot)) {
+        errors.push(
+          new ParseError(
+            `template "${tmpl.name}" @requiredSlots "${slot}" is not a field on payload "${payloadRef}". ` +
+            `Available fields: ${[...fieldNames].join(", ")}`,
+            { code: "ERR_INVALID_TEMPLATE" },
+          ),
+        );
+      }
+    }
+  }
+  return errors;
+}
+
 // ---------------------------------------------------------------------------
 // @filterable without index validation
 // ---------------------------------------------------------------------------
@@ -291,6 +346,48 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// @storage cross-attribute validation
+//
+// Rules:
+//   1. @storage requires @objectRef to be present (storage is meaningless
+//      without a referenced object type).
+//   2. @storage "flattened" requires isArray to be absent or false (cannot
+//      flatten a variable-length array into a fixed column set).
+//
+// Only field.object nodes carry @storage in practice, but the check is applied
+// to every field node that has @storage set — matching the permissive "check
+// what's there" model used by the other validation passes.
+// ---------------------------------------------------------------------------
+
+export function validateFieldObjectStorage(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+      const storage = field.ownAttr(FIELD_ATTR_STORAGE);
+      if (storage === undefined || storage === null) continue;
+      const objectRef = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+      if (typeof objectRef !== "string" || objectRef.length === 0) {
+        errors.push(
+          new ParseError(
+            `field "${obj.name}.${field.name}" sets @storage but has no @objectRef`,
+            { code: "ERR_STORAGE_WITHOUT_OBJECT_REF" },
+          ),
+        );
+      }
+      if (storage === STORAGE_FLATTENED && field.isArray === true) {
+        errors.push(
+          new ParseError(
+            `field "${obj.name}.${field.name}" sets @storage "flattened" with isArray=true; flattened storage requires a single nested value`,
+            { code: "ERR_STORAGE_FLATTENED_ARRAY" },
+          ),
+        );
+      }
+    }
+  }
+  return errors;
+}
+
 // ---------------------------------------------------------------------------
 // Layout dataGrid @filter value validation
 //

package/src/naming.ts

@@ -1,13 +1,12 @@
 import type { MetaData } from "./shared/meta-data.js";
-import { TYPE_FIELD, TYPE_SOURCE } from "./shared/base-types.js";
+import { TYPE_FIELD } from "./shared/base-types.js";
 import { PACKAGE_SEPARATOR } from "./shared/structural.js";
-import { FIELD_ATTR_DB_COLUMN } from "./persistence/db/db-constants.js";
+import { FIELD_ATTR_COLUMN } from "./persistence/db/db-constants.js";
 import {
-  SOURCE_SUBTYPE_DB_TABLE,
-  SOURCE_SUBTYPE_DB_VIEW,
-  SOURCE_DB_TABLE_ATTR_NAME,
   SOURCE_ATTR_SCHEMA,
+  SOURCE_ROLE_PRIMARY,
 } from "./persistence/source/source-constants.js";
+import { MetaSource } from "./persistence/source/meta-source.js";
 
 /**
  * Strip the package prefix from a metadata-qualified name
@@ -36,30 +35,33 @@ export function pluralize(s: string): string {
 }
 
 export function resolveTableName(entity: MetaData): string {
+  // Primary writable source carries the physical table name (@table).
   const source = entity.ownChildren().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);
+  const name = source?.tableName;
   if (typeof name === "string" && name !== "") return name;
   return pluralize(toSnakeCase(entity.name));
 }
 
 export function resolveColumnName(field: MetaData): string {
-  const attr = field.ownAttr(FIELD_ATTR_DB_COLUMN);
-  if (typeof attr === "string") return attr;
+  const col = field.ownAttr(FIELD_ATTR_COLUMN);
+  if (typeof col === "string" && col) return col;
   return toSnakeCase(field.name);
 }
 
 /**
- * Returns the DB schema declared on an entity's source[dbTable] or source[dbView] child,
- * or undefined if no @schema attr is set or no source child exists. Callers decide what
+ * Returns the DB schema declared on an entity's primary source child, or undefined
+ * when no @schema attr is set or no source child exists. @schema is paradigm-agnostic
+ * (works for writable tables and read-only views/projections alike). Callers decide what
  * "undefined" means for their dialect — Postgres treats it as the default public schema,
  * SQLite treats it as the only allowed value (no schema concept).
  */
 export function resolveTableSchema(entity: MetaData): string | undefined {
   const source = entity.ownChildren().find(
-    (c) => c.type === TYPE_SOURCE
-        && (c.subType === SOURCE_SUBTYPE_DB_TABLE || c.subType === SOURCE_SUBTYPE_DB_VIEW),
+    (c): c is MetaSource =>
+      c instanceof MetaSource && c.role === SOURCE_ROLE_PRIMARY,
   );
   if (!source) return undefined;
   const schema = source.ownAttr(SOURCE_ATTR_SCHEMA);

package/src/parser-core.ts

@@ -188,6 +188,14 @@ function expandPackageForPath(basePkg: string, pkgPath: string): string {
 // a single parse call. Set at buildTree entry, read deep in the call tree.
 let _deferSuperResolution = false;
 
+// Module-level hard-error sink for inline @-attr checks (used by
+// applyInlineAttrsAndUnknownKeys). Set at buildTree entry alongside the
+// errors[] aggregator so a reserved-word-as-attr violation lands in the
+// loader's errors[] without changing the helper's signature.
+// Safe because buildTree is synchronous — same reentrancy argument as
+// _deferSuperResolution.
+let _currentErrors: ParseError[] | undefined;
+
 /**
  * buildTree — the shared registry-driven tree-builder.
  *
@@ -205,94 +213,100 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
   const strict = opts.strict ?? false;
   const source = opts.sourceName;
   _deferSuperResolution = opts.deferSuperResolution === true;
+  _currentErrors = errors;
 
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new ParseError("Top-level metadata must be an object", { ...errOpts(source), code: "ERR_TOP_LEVEL_NOT_OBJECT" });
-  }
+  try {
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new ParseError("Top-level metadata must be an object", { ...errOpts(source), code: "ERR_TOP_LEVEL_NOT_OBJECT" });
+    }
 
-  const topLevel = parsed as Record<string, unknown>;
+    const topLevel = parsed as Record<string, unknown>;
 
-  // --- Find the wrapper key (skip $schema) ---
-  const wrapperKeys = Object.keys(topLevel).filter((k) => k !== JSON_KEY_SCHEMA);
+    // --- Find the wrapper key (skip $schema) ---
+    const wrapperKeys = Object.keys(topLevel).filter((k) => k !== JSON_KEY_SCHEMA);
 
-  if (wrapperKeys.length === 0) {
-    throw new ParseError("Top-level metadata object has no type wrapper key", { ...errOpts(source), code: "ERR_TOP_LEVEL_NOT_OBJECT" });
-  }
-  if (wrapperKeys.length > 1) {
-    throw new ParseError(
-      `Top-level metadata object must have exactly one wrapper key (found: ${wrapperKeys.join(", ")})`,
-      { ...errOpts(source), code: "ERR_TOP_LEVEL_NOT_OBJECT" },
-    );
-  }
+    if (wrapperKeys.length === 0) {
+      throw new ParseError("Top-level metadata object has no type wrapper key", { ...errOpts(source), code: "ERR_TOP_LEVEL_NOT_OBJECT" });
+    }
+    if (wrapperKeys.length > 1) {
+      throw new ParseError(
+        `Top-level metadata object must have exactly one wrapper key (found: ${wrapperKeys.join(", ")})`,
+        { ...errOpts(source), code: "ERR_TOP_LEVEL_NOT_OBJECT" },
+      );
+    }
 
-  const rootKey = wrapperKeys[0]!;
-  const rootData = topLevel[rootKey];
+    const rootKey = wrapperKeys[0]!;
+    const rootData = topLevel[rootKey];
 
-  if (typeof rootData !== "object" || rootData === null || Array.isArray(rootData)) {
-    throw new ParseError(
-      `Top-level wrapper "${rootKey}" must contain an object`,
-      { ...errOpts(source, rootKey), code: "ERR_TOP_LEVEL_NOT_OBJECT" },
-    );
-  }
+    if (typeof rootData !== "object" || rootData === null || Array.isArray(rootData)) {
+      throw new ParseError(
+        `Top-level wrapper "${rootKey}" must contain an object`,
+        { ...errOpts(source, rootKey), code: "ERR_TOP_LEVEL_NOT_OBJECT" },
+      );
+    }
 
-  const rootDataObj = rootData as Record<string, unknown>;
-  const { type: rootType, subType: rootSubType } = splitTypeKey(rootKey, opts.registry);
-
-  // Check root type is registered (always throw — can't skip the root)
-  if (!opts.registry.has(rootType, rootSubType)) {
-    const rootTypeCode = opts.registry.allSubTypesOf(rootType).length > 0
-      ? "ERR_UNKNOWN_SUBTYPE" as const
-      : "ERR_UNKNOWN_TYPE" as const;
-    throw new ParseError(
-      `Unknown root type "${rootType}.${rootSubType}" — not registered`,
-      { ...errOpts(source, rootKey), code: rootTypeCode },
-    );
-  }
+    const rootDataObj = rootData as Record<string, unknown>;
+    const { type: rootType, subType: rootSubType } = splitTypeKey(rootKey, opts.registry);
 
-  if (opts.intoRoot !== undefined) {
-    // --- Merge mode: parse root's attrs/children into the existing root ---
-    // The JSON root's own package/super/reserved-keys are not re-applied to the
-    // existing root. BUT: children from the NEW JSON should inherit from the
-    // NEW root's package, not the existing root's.
-    const newRootPkg = rootDataObj[RESERVED_KEY_PACKAGE];
-    const contextPkg = (typeof newRootPkg === "string" ? newRootPkg : opts.intoRoot.package) ?? "";
-    parseNodeInto(
+    // Check root type is registered (always throw — can't skip the root)
+    if (!opts.registry.has(rootType, rootSubType)) {
+      const rootTypeCode = opts.registry.allSubTypesOf(rootType).length > 0
+        ? "ERR_UNKNOWN_SUBTYPE" as const
+        : "ERR_UNKNOWN_TYPE" as const;
+      throw new ParseError(
+        `Unknown root type "${rootType}.${rootSubType}" — not registered`,
+        { ...errOpts(source, rootKey), code: rootTypeCode },
+      );
+    }
+
+    if (opts.intoRoot !== undefined) {
+      // --- Merge mode: parse root's attrs/children into the existing root ---
+      // The JSON root's own package/super/reserved-keys are not re-applied to the
+      // existing root. BUT: children from the NEW JSON should inherit from the
+      // NEW root's package, not the existing root's.
+      const newRootPkg = rootDataObj[RESERVED_KEY_PACKAGE];
+      const contextPkg = (typeof newRootPkg === "string" ? newRootPkg : opts.intoRoot.package) ?? "";
+      parseNodeInto(
+        rootDataObj,
+        opts.intoRoot,
+        opts.intoRoot, // accumulating root for super resolution
+        contextPkg,
+        opts.registry,
+        warnings,
+        errors,
+        strict,
+        source,
+        rootKey,
+      );
+      return { root: opts.intoRoot, warnings, errors };
+    }
+
+    // --- Fresh root mode: create a new root from the JSON ---
+    // The cast is safe within the core provider: `metadata.root` is the only
+    // registered `metadata` subtype, and its factory unconditionally produces a
+    // MetaRoot (see core-types.ts). A registry that registered a second
+    // `metadata.*` subtype backed by a non-MetaRoot factory would break this
+    // cast — a known limitation of the `TypeDefinition.factory: => MetaData`
+    // signature. `parseNodeFresh` is a general node parser, so MetaData is its
+    // correct return type; this top-level callsite is where the doc-root invariant holds.
+    const root = parseNodeFresh(
+      rootType,
+      rootSubType,
       rootDataObj,
-      opts.intoRoot,
-      opts.intoRoot, // accumulating root for super resolution
-      contextPkg,
+      undefined, // no accumulating root yet — built as we go
+      "",        // no inherited context pkg yet for the root itself
       opts.registry,
       warnings,
       errors,
       strict,
       source,
       rootKey,
-    );
-    return { root: opts.intoRoot, warnings, errors };
+    ) as MetaRoot;
+    return { root, warnings, errors };
+  } finally {
+    _deferSuperResolution = false;
+    _currentErrors = undefined;
   }
-
-  // --- Fresh root mode: create a new root from the JSON ---
-  // The cast is safe within the core provider: `metadata.root` is the only
-  // registered `metadata` subtype, and its factory unconditionally produces a
-  // MetaRoot (see core-types.ts). A registry that registered a second
-  // `metadata.*` subtype backed by a non-MetaRoot factory would break this
-  // cast — a known limitation of the `TypeDefinition.factory: => MetaData`
-  // signature. `parseNodeFresh` is a general node parser, so MetaData is its
-  // correct return type; this top-level callsite is where the doc-root invariant holds.
-  const root = parseNodeFresh(
-    rootType,
-    rootSubType,
-    rootDataObj,
-    undefined, // no accumulating root yet — built as we go
-    "",        // no inherited context pkg yet for the root itself
-    opts.registry,
-    warnings,
-    errors,
-    strict,
-    source,
-    rootKey,
-  ) as MetaRoot;
-  return { root, warnings, errors };
 }
 
 // ---------------------------------------------------------------------------
@@ -580,6 +594,34 @@ function applyInlineAttrsAndUnknownKeys(
 
     // Inline attribute (@-prefixed) — materialize into a MetaAttr instance.
     const attrName = key.slice(ATTR_PREFIX.length);
+
+    // Reserved structural keys (name/package/extends/abstract/overlay/isArray
+    // /children/value) must NOT be @-prefixed — they're written bare. An
+    // @-prefixed reserved word is always a metadata-author error (e.g.
+    // "@isArray" instead of bare "isArray") and is reported as a hard error
+    // regardless of strict mode so downstream code never sees a bogus
+    // MetaAttr named after a reserved word.
+    if (RESERVED_KEYS.has(attrName)) {
+      const displayName =
+        model.name !== "" ? `${model.type}.${model.subType} '${model.name}'` : `${model.type}.${model.subType}`;
+      const msg =
+        `Reserved structural key '${attrName}' must not be ${ATTR_PREFIX}-prefixed ` +
+        `on ${displayName} at ${path} (write it bare)`;
+      if (strict) {
+        throw new ParseError(msg, { ...errOpts(source, path), code: "ERR_RESERVED_ATTR" });
+      }
+      // Lax mode: route through the module-level errors sink so the loader
+      // sees this as a hard error (parity with attr-schema-validate's
+      // ERR_BAD_ATTR_VALUE direct pushes). Falls back to warnings only if
+      // _currentErrors isn't bound (unreachable when called from buildTree).
+      if (_currentErrors !== undefined) {
+        _currentErrors.push(new ParseError(msg, { ...errOpts(source, path), code: "ERR_RESERVED_ATTR" }));
+      } else {
+        warnings.push(msg);
+      }
+      continue;
+    }
+
     const rawVal = nodeData[key];
 
     try {
@@ -606,7 +648,11 @@ function materializeAttr(
   rawVal: unknown,
   registry: TypeRegistry,
 ): MetaAttr {
-  const attrSpec = registry.attrsOf(owner.type, owner.subType).find((s) => s.name === attrName);
+  // Resolve attr spec: per-type attrs take precedence over common attrs.
+  // Common attrs are consulted as a fallback so they get the correct MetaAttr
+  // subclass (and thus the right coerce/validateValue) at parse time.
+  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) {
     subType = attrSpec.valueType;

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

@@ -1,6 +1,6 @@
 // DB concern constants — physical DB column attr keys.
 
-/** Custom DB column name override on a field (maps to @dbColumn in metadata). */
-export const FIELD_ATTR_DB_COLUMN = "dbColumn";
+/** Column name override on a field (maps to @column in metadata). */
+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";

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

@@ -1,36 +1,30 @@
 // dbProvider — the DB-domain MetaDataTypeProvider. Registers the DB-domain
-// attributes (@dbColumn, @db.indexed on fields; @name on source.dbTable /
-// source.dbView) by extending the core-registered types. Mirrors Java's
+// 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).
 
 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_DB_TABLE,
-  SOURCE_SUBTYPE_DB_VIEW,
-} from "../source/source-constants.js";
-import { dbColumnSchema, dbIndexedSchema, sourceNameSchema } from "./db-schema.js";
+import { SOURCE_SUBTYPE_RDB } from "../source/source-constants.js";
+import { columnSchema, dbIndexedSchema } from "./db-schema.js";
+import { sourceRdbAttrs } from "../source/source-schema.js";
 
 export const dbProvider: MetaDataTypeProvider = {
   id: "metaobjects-db",
   dependencies: ["metaobjects-core-types"],
   description:
-    "DB-domain attributes — @dbColumn / @db.indexed on fields, @name on source.dbTable / source.dbView.",
+    "DB-domain attributes — @column / @db.indexed on fields, @table/@kind/@role/@schema on source.rdb.",
   registerTypes(registry: TypeRegistry): void {
     for (const subType of FIELD_SUBTYPES) {
       registry.extend(TYPE_FIELD, subType, {
-        attributes: [dbColumnSchema, dbIndexedSchema],
+        attributes: [columnSchema, dbIndexedSchema],
       });
     }
-    // Two explicit calls (not a loop) — dbTable and dbView are the only DB
-    // source subtypes, and there is no DB_SOURCE_SUBTYPES constant to loop.
-    registry.extend(TYPE_SOURCE, SOURCE_SUBTYPE_DB_TABLE, {
-      attributes: [sourceNameSchema],
-    });
-    registry.extend(TYPE_SOURCE, SOURCE_SUBTYPE_DB_VIEW, {
-      attributes: [sourceNameSchema],
+    // source.rdb — @table/@kind/@role/@schema attrs.
+    registry.extend(TYPE_SOURCE, SOURCE_SUBTYPE_RDB, {
+      attributes: [...sourceRdbAttrs],
     });
   },
 };

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

@@ -7,18 +7,17 @@ import {
   ATTR_SUBTYPE_BOOLEAN,
 } from "../../core/attr/attr-constants.js";
 import {
-  FIELD_ATTR_DB_COLUMN,
+  FIELD_ATTR_COLUMN,
   FIELD_ATTR_DB_INDEXED,
 } from "./db-constants.js";
-import { SOURCE_ATTR_NAME } from "../source/source-constants.js";
 
-/** `@dbColumn` — column-name override; on every field subtype. */
-export const dbColumnSchema: AttrSchema = {
-  name: FIELD_ATTR_DB_COLUMN,
+/** `@column` — column-name override on every field subtype (source.rdb). */
+export const columnSchema: AttrSchema = {
+  name: FIELD_ATTR_COLUMN,
   valueType: ATTR_SUBTYPE_STRING,
   required: false,
   description:
-    "Override the generated SQL column name for this field. Defaults to the field name run through the project's columnNamingStrategy.",
+    "Physical column name for this field on an rdb source. Defaults to the field name via columnNamingStrategy.",
 };
 
 /** `@db.indexed` — suppress the @filterable-without-index warning; on every field subtype. */
@@ -29,12 +28,3 @@ export const dbIndexedSchema: AttrSchema = {
   description:
     "When true, suppress the @filterable-without-index Loader warning (the field is indexed by other means).",
 };
-
-/** `@name` — the SQL table/view identifier; on source.dbTable and source.dbView. */
-export const sourceNameSchema: AttrSchema = {
-  name: SOURCE_ATTR_NAME,
-  valueType: ATTR_SUBTYPE_STRING,
-  required: false,
-  description:
-    "The SQL table or view name for this source. Defaults to the object name run through the columnNamingStrategy when omitted.",
-};

package/src/persistence/origin/meta-origin.ts

@@ -14,6 +14,7 @@ import {
   ORIGIN_AGGREGATE_ATTR_AGG,
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
+  ORIGIN_COLLECTION_ATTR_VIA,
   type AggregateFunction,
 } from "./origin-constants.js";
 
@@ -65,3 +66,17 @@ export class MetaAggregateOrigin extends MetaOrigin {
     return typeof v === "string" ? v : undefined;
   }
 }
+
+/**
+ * Collection origin — the (array) field's value is a relationship-derived
+ * array of nested view-objects (FR-004 R4). Carries `@via` (required): the
+ * dotted relationship path the collection walks (e.g. "Author.posts"), or a
+ * wildcard-prefixed selector for a package-spanning collection (e.g. "*.User").
+ */
+export class MetaCollectionOrigin extends MetaOrigin {
+  /** The dotted relationship path (or wildcard selector) this collection is sourced from. */
+  get via(): string | undefined {
+    const v = this.ownAttr(ORIGIN_COLLECTION_ATTR_VIA);
+    return typeof v === "string" ? v : undefined;
+  }
+}

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

@@ -13,11 +13,13 @@ import { SUBTYPE_BASE } from "../../shared/base-types.js";
 
 export const ORIGIN_SUBTYPE_PASSTHROUGH = "passthrough";
 export const ORIGIN_SUBTYPE_AGGREGATE   = "aggregate";
+export const ORIGIN_SUBTYPE_COLLECTION  = "collection";
 
 export const ORIGIN_SUBTYPES = [
   SUBTYPE_BASE,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
+  ORIGIN_SUBTYPE_COLLECTION,
 ] as const;
 export type OriginSubType = (typeof ORIGIN_SUBTYPES)[number];
 
@@ -25,6 +27,11 @@ export type OriginSubType = (typeof ORIGIN_SUBTYPES)[number];
 export const ORIGIN_PASSTHROUGH_ATTR_FROM = "from";
 export const ORIGIN_PASSTHROUGH_ATTR_VIA  = "via";
 
+// collection attrs — a relationship-derived array of nested view-objects
+// (FR-004 R4). @via is the dotted relationship path (optionally wildcard-
+// prefixed, e.g. "*.User", for a package-spanning collection).
+export const ORIGIN_COLLECTION_ATTR_VIA = "via";
+
 // aggregate attrs
 export const ORIGIN_AGGREGATE_ATTR_AGG = "agg";
 export const ORIGIN_AGGREGATE_ATTR_OF  = "of";

package/src/persistence/origin/origin-schema.ts

@@ -7,11 +7,13 @@ import { SUBTYPE_BASE } from "../../shared/base-types.js";
 import {
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
+  ORIGIN_SUBTYPE_COLLECTION,
   ORIGIN_PASSTHROUGH_ATTR_FROM,
   ORIGIN_PASSTHROUGH_ATTR_VIA,
   ORIGIN_AGGREGATE_ATTR_AGG,
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
+  ORIGIN_COLLECTION_ATTR_VIA,
   AGGREGATE_FUNCTIONS,
 } from "./origin-constants.js";
 
@@ -58,9 +60,21 @@ const aggregateOriginAttrs: AttrSchema[] = [
   },
 ];
 
-/** Attrs per origin subtype. base has none; passthrough and aggregate carry their respective attrs. */
+/** Attrs on origin.collection — @via (the relationship path) is required. */
+const collectionOriginAttrs: AttrSchema[] = [
+  {
+    name: ORIGIN_COLLECTION_ATTR_VIA,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: true,
+    description:
+      "Dotted relationship path the collection walks to produce an array of nested view-objects (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection (e.g. '*.User').",
+  },
+];
+
+/** Attrs per origin subtype. base has none; the others carry their respective attrs. */
 export const ORIGIN_ATTRS_MAP = new Map<string, AttrSchema[]>([
   [SUBTYPE_BASE, []],
   [ORIGIN_SUBTYPE_PASSTHROUGH, [...passthroughOriginAttrs]],
   [ORIGIN_SUBTYPE_AGGREGATE, [...aggregateOriginAttrs]],
+  [ORIGIN_SUBTYPE_COLLECTION, [...collectionOriginAttrs]],
 ]);