@metaobjectsdev/metadata 0.16.0 → 0.17.0-rc.1

package/dist/persistence/source/validate-source-escapes.js

@@ -0,0 +1,115 @@
+// Validation pass: DDL-ownership escape valves (#208) — @sql / @unmanaged on
+// source.rdb. Sibling of validate-source-roles.ts / validate-source-physical-names.ts.
+//
+// #208 gives source.rdb two mutually exclusive, non-default DDL-ownership
+// markers: @sql (a hand-written body the tool registers/fingerprints/drift-
+// checks but never authors) and @unmanaged (this object's DDL is owned
+// elsewhere — the tool never touches it). This pass enforces the six
+// fail-closed rules from the design doc (§5):
+//
+//   R1  @sql AND @unmanaged on the SAME source          → ERR_SQL_BODY_WITH_UNMANAGED
+//   R2  @sql on a writable @kind ("table", the default)  → ERR_SQL_BODY_ON_WRITABLE_KIND
+//   R3  @sql present but empty / whitespace-only         → ERR_BAD_ATTR_VALUE
+//   R4  origin.*-bearing field under an @sql host         → ERR_ORIGIN_UNDER_SQL_BODY
+//   R5  object.projection @filter (#207) + @sql host      → ERR_ORIGIN_UNDER_SQL_BODY
+//   R6  origin.*-bearing field under an @unmanaged host    → WARN_ORIGIN_UNDER_UNMANAGED
+//
+// R1–R3 are per-source (declaration-layer). R4–R6 are per-host-object: a host
+// with ANY own source.rdb carrying @sql/@unmanaged is judged against its own
+// fields (and, for R5, its own @filter). The asymmetry between R4 (hard error)
+// and R6 (warn) is deliberate (design doc §5.6): @sql is a second body (two
+// sources of truth for the SAME data); @unmanaged acts on nothing, so a
+// documented-but-unacted-on lineage is benign.
+import { ParseError } from "../../errors.js";
+import { TYPE_OBJECT, TYPE_SOURCE, TYPE_FIELD } from "../../shared/base-types.js";
+import { OBJECT_SUBTYPE_PROJECTION, OBJECT_PROJECTION_ATTR_FILTER } from "../../core/object/object-constants.js";
+import { MetaSource } from "./meta-source.js";
+import { MetaField } from "../../core/field/meta-field.js";
+import { SOURCE_ATTR_SQL, SOURCE_SUBTYPE_RDB } from "./source-constants.js";
+export function validateSourceEscapes(root) {
+    const errors = [];
+    const warnings = [];
+    // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+    for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
+        // ADR-0039: own — declaration-layer source iteration (mirrors validateSourceRoles /
+        // validateSourceParameterRef): R1–R3 judge markers DECLARED on this object's own sources.
+        const sources = obj
+            .ownChildren()
+            .filter((c) => c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_RDB && c instanceof MetaSource);
+        let hasSqlHost = false;
+        let hasUnmanagedHost = false;
+        for (const source of sources) {
+            // ADR-0039: resolving — @sql/@unmanaged are inheritable (follow the
+            // @role/effectiveKind precedent — sources are inheritable, NOT the
+            // @dbColumnType own-only exception).
+            const sqlSet = source.sqlBody !== undefined;
+            const unmanagedSet = source.isUnmanaged;
+            // R1 — contradictory DDL owners on the same source.
+            if (sqlSet && unmanagedSet) {
+                errors.push(new ParseError(`source.rdb on object "${obj.name}" declares both @sql and @unmanaged — these are the ` +
+                    `mutually exclusive non-default states of one DDL-ownership axis (an author-supplied body ` +
+                    `contradicts "someone else owns this DDL")`, { code: "ERR_SQL_BODY_WITH_UNMANAGED", source: source.source }));
+            }
+            // R2 — @sql on a writable kind would bypass the column-diff machinery;
+            // tables are fully modeled or @unmanaged, never opaque-bodied.
+            if (sqlSet && source.isWritable()) {
+                errors.push(new ParseError(`source.rdb on object "${obj.name}" declares @sql with a writable @kind ("${source.effectiveKind}") — ` +
+                    `@sql is legal only on a read-only kind (view/materializedView/storedProc/tableFunction); ` +
+                    `a writable table is either fully modeled or marked @unmanaged, never opaque-bodied`, { code: "ERR_SQL_BODY_ON_WRITABLE_KIND", source: source.source }));
+            }
+            // R3 — @sql present but empty/whitespace. MUST read the raw attr, not
+            // the sqlBody accessor: sqlBody already narrows an empty string to
+            // undefined, which would make a present-but-empty @sql indistinguishable
+            // from an absent one.
+            const rawSql = source.attr(SOURCE_ATTR_SQL);
+            if (rawSql !== undefined && (typeof rawSql !== "string" || rawSql.trim() === "")) {
+                errors.push(new ParseError(`source.rdb on object "${obj.name}" sets @sql to an empty/whitespace-only value; ` +
+                    `@sql requires a non-empty SQL body`, { code: "ERR_BAD_ATTR_VALUE", source: source.source }));
+            }
+            if (sqlSet)
+                hasSqlHost = true;
+            if (unmanagedSet)
+                hasUnmanagedHost = true;
+        }
+        if (!hasSqlHost && !hasUnmanagedHost)
+            continue;
+        // R4 / R6 — origin.*-bearing (derived) own fields under an @sql / @unmanaged
+        // host. ADR-0039: own — origin.* never inherits (ADR-0029), so isDerived()
+        // is own-only by policy (mirrors validateDerivedFieldProvidability).
+        // @sql (hard error) takes priority over @unmanaged (warn) when a host
+        // happens to declare both markers across different sources.
+        for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD && c instanceof MetaField)) {
+            if (!field.isDerived())
+                continue;
+            if (hasSqlHost) {
+                errors.push(new ParseError(`field "${obj.name}.${field.name}" carries an origin.* (derived) child, but "${obj.name}" has a ` +
+                    `read source carrying @sql — the synthesized derivation and the author's verbatim SQL are two ` +
+                    `sources of truth for the same body`, { code: "ERR_ORIGIN_UNDER_SQL_BODY", source: field.source }));
+            }
+            else {
+                warnings.push({
+                    code: "WARN_ORIGIN_UNDER_UNMANAGED",
+                    message: `field "${obj.name}.${field.name}" carries an origin.* (derived) child, but "${obj.name}" has a ` +
+                        `source marked @unmanaged — the tool never touches this object's DDL, so the derivation is ` +
+                        `documented lineage only (not acted on); this is informational, not an error`,
+                    source: field.source,
+                });
+            }
+        }
+        // R5 — a projection's row-scope @filter (#207) lowers to the outer WHERE
+        // of a TOOL-SYNTHESIZED body; with @sql the author owns the body (and its
+        // WHERE), so wrapping it is deferred cleverness (design doc D5) — reject.
+        if (hasSqlHost && obj.subType === OBJECT_SUBTYPE_PROJECTION) {
+            // ADR-0039: own — the @filter is declared locally on this projection
+            // (mirrors validateProjectionFilter).
+            const filter = obj.ownAttr(OBJECT_PROJECTION_ATTR_FILTER);
+            if (filter !== undefined) {
+                errors.push(new ParseError(`projection "${obj.name}" declares both @filter and an @sql read source — a view-level @filter ` +
+                    `lowers to the outer WHERE of a synthesized body; with @sql the author owns the body (and its ` +
+                    `WHERE), so the two cannot be combined`, { code: "ERR_ORIGIN_UNDER_SQL_BODY", source: obj.source }));
+            }
+        }
+    }
+    return { errors, warnings };
+}
+//# sourceMappingURL=validate-source-escapes.js.map

package/dist/persistence/source/validate-source-escapes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-source-escapes.js","sourceRoot":"","sources":["../../../src/persistence/source/validate-source-escapes.ts"],"names":[],"mappings":"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"}

package/package.json

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

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

@@ -14,6 +14,9 @@ export const ATTR_SUBTYPE_BOOLEAN = "boolean";
 export const ATTR_SUBTYPE_CLASS = "class";
 export const ATTR_SUBTYPE_PROPERTIES = "properties";
 export const ATTR_SUBTYPE_FILTER = "filter";
+// #195 — a structured expression tree over a base entity's own fields (backs
+// origin.computed). Object-shaped; a closed node grammar (see meta-attr-expression.ts).
+export const ATTR_SUBTYPE_EXPRESSION = "expression";
 
 /**
  * The retired `stringarray` array attr subtype. It is NO LONGER a registered
@@ -37,6 +40,7 @@ export const ATTR_SUBTYPES = [
   ATTR_SUBTYPE_CLASS,
   ATTR_SUBTYPE_PROPERTIES,
   ATTR_SUBTYPE_FILTER,
+  ATTR_SUBTYPE_EXPRESSION,
 ] as const;
 export type AttrSubType =
   | (typeof ATTR_SUBTYPES)[number]

package/src/core/attr/attr-definition.embedded.ts

@@ -62,6 +62,12 @@ export const ATTR_DEFINITION: ProviderDefinition = {
       "subType": "filter",
       "dataType": "object",
       "description": "A filter-expression-valued metadata attribute. Object-shaped value that desugars a preset filter to the canonical { field: { op: value } } form (scalar→eq, array→in, null→isNull; or/and recurse)."
+    },
+    {
+      "type": "attr",
+      "subType": "expression",
+      "dataType": "object",
+      "description": "A structured expression tree over a base entity's own fields (closed node grammar: field/value refs, comparisons sharing the filter op vocabulary, isNull/isNotNull, and/or/not, coalesce). Backs origin.computed; a filter object embeds canonically. Additive node kinds (arithmetic/case/via-joined refs) are #159."
     }
   ]
 };

package/src/core/attr/meta-attr-expression.ts

@@ -0,0 +1,230 @@
+// attr.expression — the closed structured-expression node grammar backing
+// origin.computed (#195). A row-level value computed from a base entity's own
+// fields. Deliberately NOT a raw-SQL string: a declarative, backend-agnostic
+// tree that any lowering (SQL view DDL, an in-process evaluator, a document
+// store) can walk.
+//
+// It shares the FILTER op vocabulary and per-subtype legality bands
+// (query-constants.ts) so the two languages stay ONE vocabulary, and a canonical
+// filter object embeds into it (`filterToExpr`) — so each port implements one
+// expression engine and the filter renderers become thin adapters. The filter's
+// leaves are `field → {op: literal}` and cannot hold a value tree (field-vs-field,
+// coalesce), which is why the expression tree is its own grammar rather than a
+// reused filter object.
+//
+// This module exposes the STANDALONE grammar (validate / infer / embed) AND the
+// `attr.expression` MetaAttr registration. The registration is only live once the
+// subtype is in ATTR_SUBTYPES + the canonical spec (a COORDINATED cross-port step,
+// since the registry manifest is a single shared byte-matched file) — #195.
+
+import {
+  FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE,
+  FILTER_OP_IS_NULL, FILTER_COMPOSE_AND, FILTER_COMPOSE_OR,
+  opsForSubType, type FilterOp,
+} from "../query/query-constants.js";
+import {
+  FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_BOOLEAN,
+} from "../field/field-constants.js";
+import { MetaAttr, type ValueError, runtimeTypeName } from "./meta-attr.js";
+import { type AttrValue } from "../../shared/meta-data.js";
+import { DATA_TYPE_OBJECT, type DataType } from "../../data-type.js";
+import { ATTR_SUBTYPE_EXPRESSION } from "./attr-constants.js";
+import { registerAttrClass } from "../../attr-class-map.js";
+
+// --- Expression-only op/fn names (the comparison + and/or/isNull names are the
+// --- shared filter vocabulary above; these three are new). ---
+export const EXPR_OP_IS_NOT_NULL = "isNotNull";
+export const EXPR_OP_NOT = "not";
+export const EXPR_FN_COALESCE = "coalesce";
+
+const COMPARISON_OPS: ReadonlySet<string> = new Set([
+  FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE,
+]);
+const NULL_OPS: ReadonlySet<string> = new Set([FILTER_OP_IS_NULL, EXPR_OP_IS_NOT_NULL]);
+const VARIADIC_LOGIC_OPS: ReadonlySet<string> = new Set([FILTER_COMPOSE_AND, FILTER_COMPOSE_OR]);
+
+export type ExprLiteral = string | number | boolean | null;
+export type ExprNode =
+  | { field: string }
+  | { value: ExprLiteral }
+  | { op: string; left: ExprNode; right: ExprNode }   // comparison
+  | { op: string; arg: ExprNode }                     // isNull / isNotNull / not
+  | { op: string; args: ExprNode[] }                  // and / or
+  | { fn: string; args: ExprNode[] };                 // coalesce
+
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Structural well-formedness of an expression tree (known node kinds, ops, arity).
+ *  Returns [] when valid. No entity/type context — see `inferExprType` for typing. */
+export function validateExprNode(node: unknown): string[] {
+  if (!isObj(node)) return [`expression node must be an object, got ${node === null ? "null" : Array.isArray(node) ? "array" : typeof node}`];
+  if ("field" in node) {
+    return typeof node.field === "string" && node.field.length > 0 ? [] : ["expression 'field' must be a non-empty string"];
+  }
+  if ("value" in node) {
+    const v = node.value;
+    return v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean"
+      ? [] : ["expression 'value' must be a scalar literal (string/number/boolean/null)"];
+  }
+  if ("fn" in node) {
+    if (node.fn !== EXPR_FN_COALESCE) return [`unknown expression fn '${String(node.fn)}'`];
+    return Array.isArray(node.args) && node.args.length >= 1
+      ? node.args.flatMap(validateExprNode) : [`'${EXPR_FN_COALESCE}' requires a non-empty args array`];
+  }
+  if ("op" in node) {
+    const op = node.op;
+    if (typeof op !== "string") return ["expression 'op' must be a string"];
+    if (COMPARISON_OPS.has(op)) {
+      return "left" in node && "right" in node
+        ? [...validateExprNode(node.left), ...validateExprNode(node.right)]
+        : [`comparison op '${op}' requires 'left' and 'right'`];
+    }
+    if (NULL_OPS.has(op) || op === EXPR_OP_NOT) {
+      return "arg" in node ? validateExprNode(node.arg) : [`op '${op}' requires 'arg'`];
+    }
+    if (VARIADIC_LOGIC_OPS.has(op)) {
+      return Array.isArray(node.args) && node.args.length >= 1
+        ? node.args.flatMap(validateExprNode) : [`op '${op}' requires a non-empty args array`];
+    }
+    return [`unknown expression op '${op}'`];
+  }
+  return ["expression node must be one of {field}, {value}, {op,…}, {fn,…}"];
+}
+
+/** The subtype of a scalar literal (coarse: an integer number → int, else double). */
+function literalType(v: ExprLiteral): string | undefined {
+  if (typeof v === "string") return FIELD_SUBTYPE_STRING;
+  if (typeof v === "boolean") return FIELD_SUBTYPE_BOOLEAN;
+  if (typeof v === "number") return Number.isInteger(v) ? FIELD_SUBTYPE_INT : FIELD_SUBTYPE_DOUBLE;
+  return undefined; // null literal
+}
+
+export interface InferResult {
+  /** The inferred field subType of the expression's root, or undefined if untypable. */
+  type: string | undefined;
+  /** Type/resolution/op-legality errors (empty when the tree types cleanly). */
+  errors: string[];
+}
+
+/**
+ * Bottom-up type inference for a computed expression. `resolveField(name)` returns
+ * the subType of a base-entity field ref (undefined = unresolvable). Comparisons /
+ * null-tests / logic → boolean; a field ref → its subType; coalesce → the unified
+ * arg subType. Also enforces per-operand op legality against `OPS_BY_SUBTYPE`
+ * (the same bands filters use), so e.g. `gt` on a boolean operand is rejected.
+ */
+export function inferExprType(node: ExprNode, resolveField: (name: string) => string | undefined): InferResult {
+  const structural = validateExprNode(node);
+  if (structural.length) return { type: undefined, errors: structural };
+  const n = node as Record<string, unknown>;
+
+  if ("field" in n) {
+    const t = resolveField(n.field as string);
+    return t === undefined
+      ? { type: undefined, errors: [`expression field '${String(n.field)}' does not resolve to a base entity field`] }
+      : { type: t, errors: [] };
+  }
+  if ("value" in n) return { type: literalType(n.value as ExprLiteral), errors: [] };
+
+  if ("fn" in n) { // coalesce
+    const argResults = (n.args as ExprNode[]).map((a) => inferExprType(a, resolveField));
+    const errors = argResults.flatMap((a) => a.errors);
+    const argTypes = argResults.map((a) => a.type).filter((t): t is string => t !== undefined);
+    const unified = argTypes[0];
+    if (unified !== undefined && argTypes.some((t) => t !== unified)) {
+      errors.push(`'${EXPR_FN_COALESCE}' arguments have differing types (${[...new Set(argTypes)].join(", ")})`);
+    }
+    return { type: unified, errors };
+  }
+
+  const op = n.op as string;
+  if (COMPARISON_OPS.has(op)) {
+    const l = inferExprType(n.left as ExprNode, resolveField);
+    const r = inferExprType(n.right as ExprNode, resolveField);
+    const errors = [...l.errors, ...r.errors];
+    if (l.type !== undefined && !opsForSubType(l.type).includes(op as FilterOp)) {
+      errors.push(`op '${op}' is not legal for a ${l.type} operand`);
+    }
+    return { type: FIELD_SUBTYPE_BOOLEAN, errors };
+  }
+  if (NULL_OPS.has(op)) {
+    return { type: FIELD_SUBTYPE_BOOLEAN, errors: inferExprType(n.arg as ExprNode, resolveField).errors };
+  }
+  if (op === EXPR_OP_NOT || VARIADIC_LOGIC_OPS.has(op)) {
+    const kids = op === EXPR_OP_NOT ? [n.arg as ExprNode] : (n.args as ExprNode[]);
+    const errors: string[] = [];
+    for (const k of kids) {
+      const kt = inferExprType(k, resolveField);
+      errors.push(...kt.errors);
+      if (kt.type !== undefined && kt.type !== FIELD_SUBTYPE_BOOLEAN) {
+        errors.push(`op '${op}' requires boolean operands, got ${kt.type}`);
+      }
+    }
+    return { type: FIELD_SUBTYPE_BOOLEAN, errors };
+  }
+  return { type: undefined, errors: [`unknown expression op '${op}'`] };
+}
+
+/**
+ * Embed a CANONICAL filter object (`{ field: { op: value } }` with `and`/`or`
+ * composition — the desugared `attr.filter` form) into an expression tree, so the
+ * two languages share one evaluator. `isNull: false` becomes `isNotNull`.
+ */
+export function filterToExpr(filter: Record<string, unknown>): ExprNode {
+  const clauses: ExprNode[] = [];
+  for (const [key, raw] of Object.entries(filter)) {
+    if (key === FILTER_COMPOSE_AND || key === FILTER_COMPOSE_OR) {
+      const subs = (raw as Record<string, unknown>[]).map(filterToExpr);
+      clauses.push({ op: key, args: subs });
+      continue;
+    }
+    const opObj = raw as Record<string, ExprLiteral>;
+    for (const [op, val] of Object.entries(opObj)) {
+      if (op === FILTER_OP_IS_NULL) {
+        clauses.push(val === false
+          ? { op: EXPR_OP_IS_NOT_NULL, arg: { field: key } }
+          : { op: FILTER_OP_IS_NULL, arg: { field: key } });
+      } else {
+        clauses.push({ op, left: { field: key }, right: { value: val } });
+      }
+    }
+  }
+  const [only] = clauses;
+  return clauses.length === 1 && only !== undefined ? only : { op: FILTER_COMPOSE_AND, args: clauses };
+}
+
+/**
+ * ExpressionAttr — attr subtype `expression`. Object-shaped value holding a
+ * closed expression tree (`@expr` on origin.computed). Stored verbatim (no
+ * desugar); `validateValue` enforces STRUCTURAL well-formedness of the node
+ * grammar (a fail-closed unknown op/fn/kind is a load error, ADR-0023). Entity-
+ * aware TYPE inference (`inferExprType` → ERR_COMPUTED_TYPE_MISMATCH) runs later
+ * in the projection validation pass, where the base entity's fields are known.
+ */
+export class ExpressionAttr extends MetaAttr {
+  override get dataType(): DataType {
+    return DATA_TYPE_OBJECT;
+  }
+
+  override coerce(raw: unknown): AttrValue {
+    // The expression tree is the canonical shape; pass a non-object through so
+    // validateValue rejects it.
+    return raw as AttrValue;
+  }
+
+  override validateValue(value: AttrValue): ValueError[] {
+    // Only shape (must be an object) is checked here — the CLOSED node grammar
+    // (fail-closed unknown op/fn/kind → ERR_UNKNOWN_EXPR_NODE) and entity-aware
+    // type inference are validated in the origin.computed validation pass, where
+    // the base entity's fields are known. Keeping the deep check out of the attr
+    // class matches the cross-port contract (C#/Java/Python store @expr verbatim)
+    // and mirrors FilterAttr, which likewise validates only shape.
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? []
+      : [{ message: `attribute '@${this.name}' must be of type 'expression' but got ${runtimeTypeName(value)}` }];
+  }
+}
+
+registerAttrClass(ATTR_SUBTYPE_EXPRESSION, ExpressionAttr);

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

@@ -16,7 +16,7 @@ import {
   DATA_TYPE_OBJECT,
 } from "../../data-type.js";
 import { convertToDataType } from "../../data-converter.js";
-import { TYPE_VALIDATOR, TYPE_VIEW, SUBTYPE_BASE } from "../../shared/base-types.js";
+import { TYPE_VALIDATOR, TYPE_VIEW, TYPE_ORIGIN, SUBTYPE_BASE } from "../../shared/base-types.js";
 import {
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_INT,
@@ -196,6 +196,18 @@ export class MetaField extends MetaData implements DataTypeAware {
     );
   }
 
+  /**
+   * True when this field carries an `origin.*` child (passthrough / aggregate /
+   * computed / first): its value is DERIVED from other data, not stored in the
+   * object's own writable table. A derived field is read-only wherever it lives
+   * (ADR-0028) — excluded from the write-table DDL, the ORM table def, and the
+   * Insert/Update codecs; it exists only on the read (view) side. `origin.*` never
+   * inherits (ADR-0029), so the check is own-only (category 4). */
+  isDerived(): boolean {
+    // ADR-0039 own (category 4): origin.* never inherits (ADR-0029) — own by policy.
+    return this.ownChildren().some((c) => c.type === TYPE_ORIGIN);
+  }
+
   /** The typed supertype field if `extends:` resolved, else undefined. */
   resolveSuper(): MetaField | undefined {
     return this.superData as MetaField | undefined;

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

@@ -39,3 +39,13 @@ export const OBJECT_ATTR_DISCRIMINATOR = "discriminator";
 /** FR-014: on a subtype of an entity with @discriminator: the value that
  *  identifies rows of this subtype in the shared discriminator field. */
 export const OBJECT_ATTR_DISCRIMINATOR_VALUE = "discriminatorValue";
+
+// ---------------------------------------------------------------------------
+// #207 — projection row-scope @filter (view-level WHERE)
+// ---------------------------------------------------------------------------
+/** #207: an optional row-scope predicate on an object.projection (an attr.filter
+ *  object) selecting which rows the derived view returns — lowered to an outer
+ *  SQL WHERE. Mirrors origin.aggregate's @filter placement (attr.filter subType),
+ *  but resolves against the projection's OWN declared fields rather than one
+ *  aggregated entity. An aggregate-derived field is not addressable (fail-closed). */
+export const OBJECT_PROJECTION_ATTR_FILTER = "filter";

package/src/core/object/object-definition.embedded.ts

@@ -121,7 +121,17 @@ export const OBJECT_DEFINITION: ProviderDefinition = {
       "extendsBase": true,
       "description": "A derived read-only representation of entities. Its fields are extends-bound / origin-derived / self-declared-under-external-assembly, all read-only at the subtype level. Identity is optional and MUST extend an entity identity; sources are restricted to read-only @kinds. The declared field set IS the exposure (inclusive, fail-closed).",
       "whenToUse": "You need a derived, read-only view over entities — a report, summary, or joined/aggregated read model. Declare it (with origin.* children) instead of hand-writing the SELECT/joins; it stays read-only and regenerates.",
-      "rules": "object.projection is a derived read-only representation: every field is extends-bound, origin-derived, or self-declared-under-external-assembly, and all are read-only at the subtype level. Identity is optional and, when present, MUST extend an entity identity. Sources are restricted to read-only @kinds. The declared field set IS the exposure — an inclusive list, fail-closed. A projection NEVER declares relationships (derivation is expressed via @via, not a relationship child) and NEVER co-locates templates — hence its child set omits both relationship and template. See ADR-0028 (object taxonomy, projection)."
+      "rules": "object.projection is a derived read-only representation: every field is extends-bound, origin-derived, or self-declared-under-external-assembly, and all are read-only at the subtype level. Identity is optional and, when present, MUST extend an entity identity. Sources are restricted to read-only @kinds. The declared field set IS the exposure — an inclusive list, fail-closed. A projection NEVER declares relationships (derivation is expressed via @via, not a relationship child) and NEVER co-locates templates — hence its child set omits both relationship and template. See ADR-0028 (object taxonomy, projection).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "filter",
+          "name": "filter",
+          "min": 0,
+          "max": 1,
+          "description": "Optional row-scope predicate (a portable attr.filter object: eq/ne/gt/gte/lt/lte/like/in/isNull with and/or, desugared to { field: { op: value } } at parse time) selecting which rows the view returns — lowered to an outer SQL WHERE. Resolves against the projection's own declared fields; an aggregate-derived field is not addressable (fail-closed)."
+        }
+      ]
     }
   ]
 };

package/src/core-types.ts

@@ -18,6 +18,7 @@ import { attrClassFor, type NodeConstructor } from "./attr-class-map.js";
 import "./core/attr/meta-attr-stringarray.js";
 import "./core/attr/meta-attr-filter.js";
 import "./core/attr/meta-attr-properties.js";
+import "./core/attr/meta-attr-expression.js";
 import {
   MetaValidator,
   MetaRequiredValidator,
@@ -36,7 +37,7 @@ 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, MetaCollectionOrigin } from "./persistence/origin/meta-origin.js";
+import { MetaOrigin, MetaPassthroughOrigin, MetaAggregateOrigin, MetaCollectionOrigin, MetaComputedOrigin, MetaFirstOrigin } from "./persistence/origin/meta-origin.js";
 import { defineProviderFromData, type FactoryMap } from "./provider-data.js";
 import { FIELD_DEFINITION } from "./core/field/field-definition.embedded.js";
 import { OBJECT_DEFINITION } from "./core/object/object-definition.embedded.js";
@@ -98,6 +99,8 @@ import {
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
   ORIGIN_SUBTYPE_COLLECTION,
+  ORIGIN_SUBTYPE_COMPUTED,
+  ORIGIN_SUBTYPE_FIRST,
 } from "./persistence/origin/origin-constants.js";
 
 // ---------------------------------------------------------------------------
@@ -161,6 +164,8 @@ const ORIGIN_CLASS_MAP = new Map<string, NodeConstructor>([
   [ORIGIN_SUBTYPE_PASSTHROUGH, MetaPassthroughOrigin],
   [ORIGIN_SUBTYPE_AGGREGATE, MetaAggregateOrigin],
   [ORIGIN_SUBTYPE_COLLECTION, MetaCollectionOrigin],
+  [ORIGIN_SUBTYPE_COMPUTED, MetaComputedOrigin],
+  [ORIGIN_SUBTYPE_FIRST, MetaFirstOrigin],
 ]);
 
 // ATTR_CLASS_MAP + attrClassFor live in the leaf module ./attr-class-map.ts

package/src/errors.ts

@@ -170,6 +170,27 @@ export const ERROR_CODES = [
   // index.lookup field-resolution: @fields is empty or names a field that does
   // not exist on the owning entity's effective (resolved via extends) field set.
   "ERR_INVALID_INDEX",
+  // #195 — origin.computed @expr: the expression tree's inferred root type does
+  // not equal the carrying field's declared field.<subType>. A computed column's
+  // type is DERIVED from its expression, never asserted (no @convert escape),
+  // so a mismatch is a hard load error (sibling of ERR_PASSTHROUGH_TYPE_MISMATCH).
+  "ERR_COMPUTED_TYPE_MISMATCH",
+  // #195 — origin.computed @expr contains a node whose kind/op/fn is not in the
+  // closed expression grammar (ADR-0023 fail-closed). Detail names the bad token.
+  "ERR_UNKNOWN_EXPR_NODE",
+  // #208 — a source.rdb declares BOTH @sql (author-supplied body) and
+  // @unmanaged (DDL owned elsewhere). The two markers are the mutually
+  // exclusive non-default states of one "who owns this DDL" axis.
+  "ERR_SQL_BODY_WITH_UNMANAGED",
+  // #208 — a source.rdb declares @sql with a writable @kind ("table", the
+  // default). A hand-written CREATE TABLE would bypass the column-diff
+  // machinery; tables are fully modeled or @unmanaged, never opaque-bodied.
+  "ERR_SQL_BODY_ON_WRITABLE_KIND",
+  // #208 — a host object whose read source carries @sql also declares an
+  // origin.*-bearing (derived) field, or (on object.projection) an @filter —
+  // two sources of truth for the same body (the synthesized derivation/WHERE
+  // vs. the author's verbatim SQL). Fail-closed.
+  "ERR_ORIGIN_UNDER_SQL_BODY",
   "ERR_UNKNOWN",
 ] as const;
 
@@ -189,6 +210,13 @@ export const WARNING_CODES = [
   // implication does not apply to value-objects; the attr is retained for
   // language-specific record/struct treatment (e.g. Kotlin `val` vs `var`).
   "WARN_READONLY_VALUE_OBJECT",
+  // #208 — a host object whose source carries @unmanaged also declares an
+  // origin.*-bearing (derived) field. Deliberate asymmetry with
+  // ERR_ORIGIN_UNDER_SQL_BODY: @unmanaged acts on nothing (the tool never
+  // touches the object's DDL), so a documented-but-unacted-on lineage is
+  // benign — a WARN preserves the matview symmetry and lets an author
+  // document lineage for future in-process evaluation (#211).
+  "WARN_ORIGIN_UNDER_UNMANAGED",
 ] as const;
 export type WarningCode = (typeof WARNING_CODES)[number];
 

package/src/index.ts

@@ -107,6 +107,8 @@ export {
   MetaPassthroughOrigin,
   MetaAggregateOrigin,
   MetaCollectionOrigin,
+  MetaComputedOrigin,
+  MetaFirstOrigin,
 } from "./persistence/origin/meta-origin.js";
 // Template: single class backs both subtypes (FR-004)
 export { MetaTemplate } from "./template/meta-template.js";

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

@@ -18,9 +18,10 @@ import { ParseError } from "../errors.js";
 import type { LoaderWarning } from "../source.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
-import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateIndexLookupFields } from "./validation-passes.js";
+import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateIndexLookupFields, validateProjectionFilter } from "./validation-passes.js";
 import { runRegisteredValidation } from "./validation-registry.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
+import { validateSourceEscapes } from "../persistence/source/validate-source-escapes.js";
 import { validateSourcePhysicalNames } from "../persistence/source/validate-source-physical-names.js";
 import { validateSourceParameterRef } from "../persistence/source/validate-source-parameter-ref.js";
 import { validateFieldReadOnly } from "../core/field/validate-field-readonly.js";
@@ -589,6 +590,11 @@ export class MetaDataLoader {
       // Seventh pass: @filter value validation — fields filterable + ops allowed per subtype.
       errors.push(...validateDataGridFilterValues(root));
 
+      // #207 — a projection's row-scope @filter (view-level WHERE) must reference the
+      // projection's own declared, WHERE-addressable fields (passthrough/computed/plain);
+      // an aggregate-derived or dangling ref is fail-closed (ERR_BAD_ATTR_FILTER).
+      errors.push(...validateProjectionFilter(root));
+
       // FR-017 — M:N relationship validation (deferred-resolution): @through names a
       // junction declaring two identity.reference children; @sourceRefField matches one;
       // @symmetric is self-join-only + mutually exclusive with @sourceRefField; M:N attrs
@@ -630,6 +636,13 @@ export class MetaDataLoader {
       // ERR_SOURCE_MULTIPLE_PRIMARY).
       errors.push(...validateSourceRoles(root));
 
+      // #208 — DDL-ownership escape valves: source.rdb @sql / @unmanaged
+      // fail-closed rules (ERR_SQL_BODY_WITH_UNMANAGED / ERR_SQL_BODY_ON_WRITABLE_KIND /
+      // ERR_BAD_ATTR_VALUE / ERR_ORIGIN_UNDER_SQL_BODY / WARN_ORIGIN_UNDER_UNMANAGED).
+      const sourceEscapeResult = validateSourceEscapes(root);
+      errors.push(...sourceEscapeResult.errors);
+      envelopeWarnings.push(...sourceEscapeResult.warnings);
+
       // FR-016 / ADR-0018 — per-kind physical-name alias validation on
       // source.rdb (kind-matching alias, no multiples, legacy @table warning).
       const physicalNameResult = validateSourcePhysicalNames(root);