@metaobjectsdev/metadata 0.8.1 → 0.9.0-rc.1

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

@@ -1,6 +1,46 @@
 // DB concern constants — physical DB column attr keys.
 
+import {
+  FIELD_SUBTYPE_STRING,
+  FIELD_SUBTYPE_TIMESTAMP,
+} from "../../core/field/field-constants.js";
+
 /** 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";
+
+/**
+ * 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
+ * native binding (ADR-0013 — the canonical physical escape hatch). Registered
+ * by the dbProvider, validated as a (logical subtype × value) pairing.
+ */
+export const FIELD_ATTR_DB_COLUMN_TYPE = "dbColumnType";
+
+/** `@dbColumnType: uuid` — native Postgres `uuid` column (legal on field.string). */
+export const DB_COLUMN_TYPE_UUID = "uuid";
+/** `@dbColumnType: jsonb` — genuinely-open `jsonb` column (legal on field.string). */
+export const DB_COLUMN_TYPE_JSONB = "jsonb";
+/** `@dbColumnType: timestamp_with_tz` — `timestamp with time zone` (legal on field.timestamp). */
+export const DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ = "timestamp_with_tz";
+
+/** The closed set of legal `@dbColumnType` values (raw-dialect passthrough deferred). */
+export const DB_COLUMN_TYPE_VALUES = [
+  DB_COLUMN_TYPE_UUID,
+  DB_COLUMN_TYPE_JSONB,
+  DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ,
+] as const;
+export type DbColumnTypeValue = (typeof DB_COLUMN_TYPE_VALUES)[number];
+
+/**
+ * Legal `@dbColumnType` value → the field subtypes it may be applied to (ADR-0013,
+ * R6 Plan 2b). Any other (subtype × value) pairing — or an unrecognized value — is
+ * an ERR_BAD_ATTR_VALUE. Keyed by value; the value-set is enforced by membership in
+ * this map. Subtype names are the bare FIELD_SUBTYPE_* constants (string / timestamp).
+ */
+export const DB_COLUMN_TYPE_LEGAL_SUBTYPES: Readonly<Record<DbColumnTypeValue, readonly string[]>> = {
+  [DB_COLUMN_TYPE_UUID]: [FIELD_SUBTYPE_STRING],
+  [DB_COLUMN_TYPE_JSONB]: [FIELD_SUBTYPE_STRING],
+  [DB_COLUMN_TYPE_TIMESTAMP_WITH_TZ]: [FIELD_SUBTYPE_TIMESTAMP],
+} as const;

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

@@ -8,18 +8,18 @@ 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 } from "./db-schema.js";
+import { columnSchema, dbIndexedSchema, dbColumnTypeSchema } 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 — @column / @db.indexed on fields, @table/@kind/@role/@schema on source.rdb.",
+    "DB-domain attributes — @column / @db.indexed / @dbColumnType 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: [columnSchema, dbIndexedSchema],
+        attributes: [columnSchema, dbIndexedSchema, dbColumnTypeSchema],
       });
     }
     // source.rdb — @table/@kind/@role/@schema attrs.

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

@@ -9,6 +9,8 @@ import {
 import {
   FIELD_ATTR_COLUMN,
   FIELD_ATTR_DB_INDEXED,
+  FIELD_ATTR_DB_COLUMN_TYPE,
+  DB_COLUMN_TYPE_VALUES,
 } from "./db-constants.js";
 
 /** `@column` — column-name override on every field subtype (source.rdb). */
@@ -28,3 +30,21 @@ export const dbIndexedSchema: AttrSchema = {
   description:
     "When true, suppress the @filterable-without-index Loader warning (the field is indexed by other means).",
 };
+
+/**
+ * R6 Plan 2b: `@dbColumnType` — physical DB column-type override on every field
+ * subtype. The legal value depends on the field's logical subtype, so the
+ * subtype × value pairing is validated own-only by the loader
+ * (validateAttrSchema → ERR_BAD_ATTR_VALUE), not by a flat `allowedValues` set.
+ * The string valueType keeps the schema's type check intact.
+ */
+export const dbColumnTypeSchema: AttrSchema = {
+  name: FIELD_ATTR_DB_COLUMN_TYPE,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  description:
+    "Physical DB column-type override (ADR-0013 escape hatch). Legal values are " +
+    `${DB_COLUMN_TYPE_VALUES.join(" | ")}, 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.",
+};

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

@@ -1,21 +1,40 @@
 // MetaSource — concrete node class for type=source nodes.
 // Declares where an object's data lives (Project E).
-// source.rdb uses @table/@kind/@role/@schema; read-only is derived from @kind.
+// source.rdb uses kind-aware physical-name aliases + @kind/@role/@schema;
+// read-only-ness is derived from @kind.
 //
 // Extends MetaData directly: no model wrapper, no metaOf() indirection.
 
 import { MetaData } from "../../shared/meta-data.js";
+import { pluralize, toSnakeCase } from "../../naming.js";
 import {
   SOURCE_ATTR_TABLE,
+  SOURCE_ATTR_VIEW,
+  SOURCE_ATTR_MATERIALIZED_VIEW,
+  SOURCE_ATTR_PROC,
+  SOURCE_ATTR_FUNCTION,
   SOURCE_ATTR_KIND,
   SOURCE_ATTR_ROLE,
   SOURCE_READ_ONLY_KINDS,
   DEFAULT_SOURCE_KIND,
   DEFAULT_SOURCE_ROLE,
+  PHYSICAL_NAME_ATTR_BY_KIND,
 } from "./source-constants.js";
 
+/** Every kind-aware physical-name alias key, ordered for deterministic
+ *  iteration (matches the SOURCE_RDB_KINDS order). */
+const ALL_PHYSICAL_NAME_ALIASES = [
+  SOURCE_ATTR_TABLE,
+  SOURCE_ATTR_VIEW,
+  SOURCE_ATTR_MATERIALIZED_VIEW,
+  SOURCE_ATTR_PROC,
+  SOURCE_ATTR_FUNCTION,
+] as const;
+
 export class MetaSource extends MetaData {
-  /** Physical SQL table/view name from @table (source.rdb). */
+  /** Physical SQL table/view name from the legacy @table attr. Kept as a
+   *  back-compat accessor that reads ONLY the @table slot — callers should
+   *  use physicalName for the FR-016 four-step rule. */
   get tableName(): string | undefined {
     const v = this.ownAttr(SOURCE_ATTR_TABLE);
     return typeof v === "string" && v !== "" ? v : undefined;
@@ -48,4 +67,47 @@ export class MetaSource extends MetaData {
   isWritable(): boolean {
     return !this.isReadOnly();
   }
+
+  /**
+   * Resolved physical SQL name for this source, following the FR-016 / ADR-0018
+   * four-step rule:
+   *   1. Kind-matching alias (e.g. @proc when @kind: "storedProc").
+   *   2. Legacy @table for non-table kind (pre-1.0 fallback).
+   *   3. Source's bare structural `name` via snake_case.
+   *   4. Owning entity's name via pluralize(snake_case).
+   *
+   * Callers needing the legacy raw @table slot only should use `tableName`;
+   * codegen / migrate / runtime should use `physicalName`.
+   */
+  get physicalName(): string {
+    const kind = this.effectiveKind;
+
+    // Step 1: kind-matching alias.
+    const canonicalAttr = PHYSICAL_NAME_ATTR_BY_KIND.get(kind);
+    if (canonicalAttr !== undefined) {
+      const v = this.ownAttr(canonicalAttr);
+      if (typeof v === "string" && v !== "") return v;
+    }
+
+    // Step 2: legacy @table for non-table kind.
+    if (canonicalAttr !== SOURCE_ATTR_TABLE) {
+      const legacy = this.ownAttr(SOURCE_ATTR_TABLE);
+      if (typeof legacy === "string" && legacy !== "") return legacy;
+    }
+
+    // Step 3: source's structural `name` via snake_case (no pluralization —
+    // the source's name IS the logical name).
+    if (this.name !== "") {
+      return toSnakeCase(this.name);
+    }
+
+    // Step 4: owning entity's name via pluralize(snake_case). The MetaData
+    // parent of a source is always the entity that declared it.
+    const owner = this.parent;
+    if (owner !== undefined && owner.name !== "") {
+      return pluralize(toSnakeCase(owner.name));
+    }
+
+    return "";
+  }
 }

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

@@ -30,13 +30,40 @@ export const DEFAULT_DB_SCHEMA_POSTGRES = "public";
 // Source v2 (ADR-0007) — rdb paradigm: kind, role, physical table name.
 // ---------------------------------------------------------------------------
 
-/** Physical table/view name on source.rdb. */
+// FR-016 / ADR-0007 point 2: the source's "logical name" is the structural
+// `name` field every MetaData node already carries — accessed via `source.name`,
+// NOT an @-attr. (An @-attr would conflict with the ERR_RESERVED_ATTR rule for
+// the reserved structural key `name`.) See the four-step physical-name
+// resolution rule on MetaSource.physicalName.
+
+// --- Per-kind physical-name aliases (FR-016 / ADR-0018) -----------------------
+// One canonical attr key per rdb @kind. The single internal physical-name
+// "slot" on the source is filled by whichever alias matches @kind; the
+// canonical serializer emits the kind-matching alias regardless of which
+// spelling was on input.
+/** Physical SQL table name. Canonical attr for @kind: "table" (default). */
 export const SOURCE_ATTR_TABLE = "table";
+/** Physical SQL view name. Canonical attr for @kind: "view". */
+export const SOURCE_ATTR_VIEW = "view";
+/** Physical SQL materialized-view name. Canonical attr for @kind: "materializedView". */
+export const SOURCE_ATTR_MATERIALIZED_VIEW = "materializedView";
+/** Physical SQL stored-procedure name. Canonical attr for @kind: "storedProc". */
+export const SOURCE_ATTR_PROC = "proc";
+/** Physical SQL table-function name. Canonical attr for @kind: "tableFunction". */
+export const SOURCE_ATTR_FUNCTION = "function";
+
 /** Object kind within the rdb paradigm; read-only-ness is derived from it. */
 export const SOURCE_ATTR_KIND = "kind";
 /** Multi-source role; exactly one primary per object. */
 export const SOURCE_ATTR_ROLE = "role";
 
+/** FR-015: reference to an object.value describing the input shape of a callable
+ *  source. Required for @kind: "storedProc" | "tableFunction" that take args;
+ *  ignored for non-callable kinds. Wire-format symmetric with template.@payloadRef
+ *  (FR-004) — the typed-input pattern reuses object.value rather than minting a
+ *  new parameter.* node type. */
+export const SOURCE_ATTR_PARAMETER_REF = "parameterRef";
+
 export const SOURCE_KIND_TABLE              = "table";
 export const SOURCE_KIND_VIEW               = "view";
 export const SOURCE_KIND_MATERIALIZED_VIEW  = "materializedView";
@@ -52,6 +79,18 @@ export const SOURCE_RDB_KINDS = [
 ] as const;
 export type SourceRdbKind = (typeof SOURCE_RDB_KINDS)[number];
 
+/** Map @kind → canonical kind-aware physical-name attr key (FR-016 / ADR-0018).
+ *  Drives the four-step physical-name resolution rule and the canonical-serializer
+ *  per-kind rewrite. The single internal physical-name "slot" on a source is the
+ *  value of whichever alias matches the source's @kind. */
+export const PHYSICAL_NAME_ATTR_BY_KIND: ReadonlyMap<string, string> = new Map([
+  [SOURCE_KIND_TABLE,             SOURCE_ATTR_TABLE],
+  [SOURCE_KIND_VIEW,              SOURCE_ATTR_VIEW],
+  [SOURCE_KIND_MATERIALIZED_VIEW, SOURCE_ATTR_MATERIALIZED_VIEW],
+  [SOURCE_KIND_STORED_PROC,       SOURCE_ATTR_PROC],
+  [SOURCE_KIND_TABLE_FUNCTION,    SOURCE_ATTR_FUNCTION],
+]);
+
 /** rdb @kind default when omitted (writable table). */
 export const DEFAULT_SOURCE_KIND = SOURCE_KIND_TABLE;
 

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

@@ -5,20 +5,67 @@ import type { AttrSchema } from "../../registry.js";
 import { ATTR_SUBTYPE_STRING } from "../../core/attr/attr-constants.js";
 import {
   SOURCE_ATTR_TABLE,
+  SOURCE_ATTR_VIEW,
+  SOURCE_ATTR_MATERIALIZED_VIEW,
+  SOURCE_ATTR_PROC,
+  SOURCE_ATTR_FUNCTION,
   SOURCE_ATTR_KIND,
   SOURCE_ATTR_ROLE,
   SOURCE_ATTR_SCHEMA,
+  SOURCE_ATTR_PARAMETER_REF,
   SOURCE_RDB_KINDS,
   SOURCE_ROLES,
 } from "./source-constants.js";
 
-/** `@table` — physical SQL table or view name for source.rdb. */
+/** `@table` — physical SQL table name for @kind: "table" (default). FR-016: one
+ *  of five kind-aware physical-name aliases; all write to the same internal slot.
+ *  Pre-1.0 legacy: also accepted with non-table @kind (canonical-serializer
+ *  rewrites; loader emits WARN_LEGACY_PHYSICAL_NAME_ALIAS). */
 const tableSchema: AttrSchema = {
   name: SOURCE_ATTR_TABLE,
   valueType: ATTR_SUBTYPE_STRING,
   required: false,
   description:
-    "Physical SQL table or view name for this rdb source. Defaults to the object name run through the project's columnNamingStrategy when omitted.",
+    "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.",
+};
+
+/** `@view` — physical SQL view name for @kind: "view" (FR-016 / ADR-0018). */
+const viewSchema: AttrSchema = {
+  name: SOURCE_ATTR_VIEW,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  description: "Physical SQL view name for source.rdb @kind: \"view\". Same internal slot as @table.",
+};
+
+/** `@materializedView` — physical SQL materialized-view name for @kind: "materializedView". */
+const materializedViewSchema: AttrSchema = {
+  name: SOURCE_ATTR_MATERIALIZED_VIEW,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  description:
+    "Physical SQL materialized-view name for source.rdb @kind: \"materializedView\". Same internal slot as @table.",
+};
+
+/** `@proc` — physical SQL stored-procedure name for @kind: "storedProc". */
+const procSchema: AttrSchema = {
+  name: SOURCE_ATTR_PROC,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  description:
+    "Physical SQL stored-procedure name for source.rdb @kind: \"storedProc\". Same internal slot as @table.",
+};
+
+/** `@function` — physical SQL table-function name for @kind: "tableFunction". */
+const functionSchema: AttrSchema = {
+  name: SOURCE_ATTR_FUNCTION,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  description:
+    "Physical SQL table-function name for source.rdb @kind: \"tableFunction\". Same internal slot as @table.",
 };
 
 /** `@kind` — object kind within the rdb paradigm; drives read-only derivation. */
@@ -50,5 +97,33 @@ const schemaSchema: AttrSchema = {
     "Optional database schema name (e.g. 'catalog', 'public'). Postgres defaults to 'public'; SQLite rejects any non-default value.",
 };
 
+/** `@parameterRef` — name or FQN of an object.value describing the input shape
+ *  of a callable source (FR-015). Required when @kind is "storedProc" or
+ *  "tableFunction" and the proc takes args; ignored for non-callable kinds.
+ *  Mirrors template.@payloadRef from FR-004. */
+const parameterRefSchema: AttrSchema = {
+  name: SOURCE_ATTR_PARAMETER_REF,
+  valueType: ATTR_SUBTYPE_STRING,
+  required: false,
+  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.",
+};
+
 /** All attr schemas for source.rdb, to be registered via registry.extend. */
-export const sourceRdbAttrs: AttrSchema[] = [tableSchema, kindSchema, roleSchema, schemaSchema];
+export const sourceRdbAttrs: AttrSchema[] = [
+  tableSchema,
+  viewSchema,
+  materializedViewSchema,
+  procSchema,
+  functionSchema,
+  kindSchema,
+  roleSchema,
+  schemaSchema,
+  parameterRefSchema,
+];

package/src/persistence/source/validate-source-parameter-ref.ts

@@ -0,0 +1,143 @@
+// Validation pass: source.rdb @parameterRef typed-input rules (FR-015).
+//
+// Codes:
+//   ERR_PARAMETER_REF_UNRESOLVED         — @parameterRef names a non-existent object.
+//   ERR_PARAMETER_REF_NOT_VALUE_OBJECT   — @parameterRef points at an object.entity
+//                                          instead of object.value.
+//   ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND
+//                                        — @parameterRef set with @kind: "table" /
+//                                          "view" / "materializedView". Only the
+//                                          callable kinds (storedProc, tableFunction)
+//                                          accept parameters.
+//   ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH
+//                                        — a parameter field uses origin.passthrough
+//                                          @from: "Entity.field" but the parameter's
+//                                          subtype does not match the referenced
+//                                          field's subtype.
+
+import type { MetaData } from "../../shared/meta-data.js";
+import { ParseError } from "../../errors.js";
+import {
+  TYPE_OBJECT,
+  TYPE_SOURCE,
+  TYPE_FIELD,
+  TYPE_ORIGIN,
+} from "../../shared/base-types.js";
+import {
+  OBJECT_SUBTYPE_VALUE,
+  OBJECT_SUBTYPE_ENTITY,
+} from "../../core/object/object-constants.js";
+import { PACKAGE_SEPARATOR } from "../../shared/structural.js";
+import { MetaSource } from "./meta-source.js";
+import {
+  SOURCE_ATTR_PARAMETER_REF,
+  SOURCE_SUBTYPE_RDB,
+  SOURCE_KIND_STORED_PROC,
+  SOURCE_KIND_TABLE_FUNCTION,
+} from "./source-constants.js";
+import {
+  ORIGIN_SUBTYPE_PASSTHROUGH,
+  ORIGIN_PASSTHROUGH_ATTR_FROM,
+} from "../../persistence/origin/origin-constants.js";
+
+const CALLABLE_KINDS = new Set<string>([
+  SOURCE_KIND_STORED_PROC,
+  SOURCE_KIND_TABLE_FUNCTION,
+]);
+
+export function validateSourceParameterRef(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+
+  // Pre-index every object by name AND fqn so resolution costs O(1) per source.
+  const objectIndex = new Map<string, MetaData>();
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    objectIndex.set(obj.name, obj);
+    const fqn = obj.package !== undefined && obj.package !== ""
+      ? `${obj.package}${PACKAGE_SEPARATOR}${obj.name}`
+      : obj.name;
+    objectIndex.set(fqn, obj);
+  }
+
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    for (const source of obj.ownChildren().filter(
+      (c): c is MetaSource =>
+        c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_RDB && c instanceof MetaSource,
+    )) {
+      const ref = source.ownAttr(SOURCE_ATTR_PARAMETER_REF);
+      if (typeof ref !== "string" || ref === "") continue;
+
+      // ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND — checked even before resolution
+      // so authoring mistakes on the wrong kind surface immediately.
+      if (!CALLABLE_KINDS.has(source.effectiveKind)) {
+        errors.push(
+          new ParseError(
+            `source.rdb on object "${obj.name}" has @parameterRef but @kind is "${source.effectiveKind}"; ` +
+              `only "storedProc" or "tableFunction" accept parameters`,
+            { code: "ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND", source: source.source },
+          ),
+        );
+        continue;
+      }
+
+      const target = objectIndex.get(ref);
+      if (target === undefined) {
+        errors.push(
+          new ParseError(
+            `source.rdb on object "${obj.name}" @parameterRef = "${ref}" does not resolve to any known object`,
+            { code: "ERR_PARAMETER_REF_UNRESOLVED", source: source.source },
+          ),
+        );
+        continue;
+      }
+
+      if (target.subType !== OBJECT_SUBTYPE_VALUE) {
+        const reason = target.subType === OBJECT_SUBTYPE_ENTITY
+          ? "an object.entity (entities have identity; parameter shapes are value-objects)"
+          : `an object.${target.subType}`;
+        errors.push(
+          new ParseError(
+            `source.rdb on object "${obj.name}" @parameterRef = "${ref}" resolves to ${reason}; ` +
+              `use an object.value`,
+            { code: "ERR_PARAMETER_REF_NOT_VALUE_OBJECT", source: source.source },
+          ),
+        );
+        continue;
+      }
+
+      // ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH — every parameter field
+      // with origin.passthrough must have a subtype matching the referenced
+      // field. The origin path validation pass checks the from-path resolves;
+      // here we just check the subtype alignment.
+      for (const paramField of target.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+        const passthrough = paramField.ownChildren().find(
+          (c) => c.type === TYPE_ORIGIN && c.subType === ORIGIN_SUBTYPE_PASSTHROUGH,
+        );
+        if (passthrough === undefined) continue;
+        const from = passthrough.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM);
+        if (typeof from !== "string" || from === "") continue;
+        const dot = from.indexOf(".");
+        if (dot < 0) continue;
+        const targetEntityName = from.slice(0, dot);
+        const targetFieldName = from.slice(dot + 1);
+        const targetEntity = objectIndex.get(targetEntityName);
+        if (targetEntity === undefined) continue; // origin-paths pass surfaces this
+        const targetField = targetEntity.ownChildren().find(
+          (c) => c.type === TYPE_FIELD && c.name === targetFieldName,
+        );
+        if (targetField === undefined) continue;
+        if (paramField.subType !== targetField.subType) {
+          errors.push(
+            new ParseError(
+              `parameter field "${paramField.name}" (field.${paramField.subType}) on @parameterRef ` +
+                `"${ref}" uses origin.passthrough @from: "${from}", but ` +
+                `${targetEntity.name}.${targetFieldName} is field.${targetField.subType}; types must match`,
+              { code: "ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH", source: paramField.source },
+            ),
+          );
+        }
+      }
+    }
+  }
+
+  return errors;
+}

package/src/persistence/source/validate-source-physical-names.ts

@@ -0,0 +1,123 @@
+// Validation pass: per-kind physical-name aliases on source.rdb (FR-016 / ADR-0018).
+//
+// Each source.rdb may declare at most one of @table / @view / @materializedView /
+// @proc / @function. The chosen alias must match the source's @kind, with one
+// pre-1.0 legacy exception: @table is also accepted for non-table kinds (e.g.
+// @kind: "storedProc" + @table: "fn_x"), which emits a WARN_LEGACY_PHYSICAL_NAME_ALIAS.
+//
+// Codes:
+//   ERR_PHYSICAL_NAME_MULTIPLE      — two or more kind-aware aliases on one source.
+//   ERR_PHYSICAL_NAME_KIND_MISMATCH — alias other than @table set with a non-matching @kind.
+//   WARN_LEGACY_PHYSICAL_NAME_ALIAS — @table set with a non-table @kind (legacy spelling).
+
+import type { MetaData } from "../../shared/meta-data.js";
+import { ParseError } from "../../errors.js";
+import type { LoaderWarning } from "../../source.js";
+import { TYPE_OBJECT, TYPE_SOURCE } from "../../shared/base-types.js";
+import { MetaSource } from "./meta-source.js";
+import {
+  SOURCE_ATTR_TABLE,
+  SOURCE_ATTR_VIEW,
+  SOURCE_ATTR_MATERIALIZED_VIEW,
+  SOURCE_ATTR_PROC,
+  SOURCE_ATTR_FUNCTION,
+  SOURCE_SUBTYPE_RDB,
+  PHYSICAL_NAME_ATTR_BY_KIND,
+} from "./source-constants.js";
+
+const ALL_PHYSICAL_NAME_ALIASES = [
+  SOURCE_ATTR_TABLE,
+  SOURCE_ATTR_VIEW,
+  SOURCE_ATTR_MATERIALIZED_VIEW,
+  SOURCE_ATTR_PROC,
+  SOURCE_ATTR_FUNCTION,
+] as const;
+
+export interface PhysicalNameValidationResult {
+  errors: ParseError[];
+  warnings: LoaderWarning[];
+}
+
+export function validateSourcePhysicalNames(root: MetaData): PhysicalNameValidationResult {
+  const errors: ParseError[] = [];
+  const warnings: LoaderWarning[] = [];
+
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    const sources = obj
+      .ownChildren()
+      .filter(
+        (c): c is MetaSource =>
+          c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_RDB && c instanceof MetaSource,
+      );
+
+    for (const source of sources) {
+      // Empty-string check first — explicit "" is meaningless and an
+      // authoring error regardless of which alias was used.
+      for (const attr of ALL_PHYSICAL_NAME_ALIASES) {
+        const v = source.ownAttr(attr);
+        if (typeof v === "string" && v === "") {
+          errors.push(
+            new ParseError(
+              `source.rdb on object "${obj.name}" sets @${attr} to an empty string; physical name attrs require a non-empty value`,
+              { code: "ERR_BAD_ATTR_VALUE", source: source.source },
+            ),
+          );
+        }
+      }
+
+      const setAliases = ALL_PHYSICAL_NAME_ALIASES.filter((attr) => {
+        const v = source.ownAttr(attr);
+        return typeof v === "string" && v !== "";
+      });
+
+      if (setAliases.length > 1) {
+        errors.push(
+          new ParseError(
+            `source.rdb on object "${obj.name}" declares multiple physical-name aliases (${setAliases
+              .map((a) => `@${a}`)
+              .join(", ")}); set exactly one`,
+            { code: "ERR_PHYSICAL_NAME_MULTIPLE", source: source.source },
+          ),
+        );
+        continue;
+      }
+
+      if (setAliases.length === 0) continue;
+
+      const chosenAlias = setAliases[0]!;
+      const expectedAlias = PHYSICAL_NAME_ATTR_BY_KIND.get(source.effectiveKind);
+
+      if (chosenAlias === expectedAlias) continue;
+
+      // Legacy: @table is permitted for non-table kinds with a warning.
+      if (chosenAlias === SOURCE_ATTR_TABLE) {
+        warnings.push({
+          code: "WARN_LEGACY_PHYSICAL_NAME_ALIAS",
+          message:
+            `source.rdb on object "${obj.name}" uses @table with @kind: "${source.effectiveKind}"; ` +
+            `prefer the kind-matching alias @${expectedAlias} (ADR-0018)`,
+          source: source.source,
+        });
+        continue;
+      }
+
+      // Any other mismatch is a hard error.
+      errors.push(
+        new ParseError(
+          `source.rdb on object "${obj.name}" uses @${chosenAlias} with @kind: "${source.effectiveKind}"; ` +
+            `@${chosenAlias} is only valid for @kind: "${kindForAlias(chosenAlias)}"`,
+          { code: "ERR_PHYSICAL_NAME_KIND_MISMATCH", source: source.source },
+        ),
+      );
+    }
+  }
+
+  return { errors, warnings };
+}
+
+function kindForAlias(alias: string): string {
+  for (const [kind, attr] of PHYSICAL_NAME_ATTR_BY_KIND.entries()) {
+    if (attr === alias) return kind;
+  }
+  return "(unknown)";
+}