@metaobjectsdev/metadata 0.16.0 → 0.17.0-rc.1

package/src/loader/validation-passes.ts

@@ -49,6 +49,7 @@ import {
   OBJECT_SUBTYPE_ENTITY,
   OBJECT_SUBTYPE_VALUE,
   OBJECT_SUBTYPE_PROJECTION,
+  OBJECT_PROJECTION_ATTR_FILTER,
 } from "../core/object/object-constants.js";
 import { MetaSource } from "../persistence/source/meta-source.js";
 import {
@@ -72,6 +73,7 @@ import {
   FIELD_SUBTYPE_ENUM,
   FIELD_SUBTYPE_OBJECT,
   FIELD_SUBTYPE_MAP,
+  FIELD_ATTR_REQUIRED,
   FIELD_ATTR_VALUE_TYPE,
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_DATE,
@@ -88,12 +90,31 @@ import {
 import {
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
+  ORIGIN_SUBTYPE_COMPUTED,
+  ORIGIN_SUBTYPE_FIRST,
   ORIGIN_PASSTHROUGH_ATTR_FROM,
   ORIGIN_PASSTHROUGH_ATTR_VIA,
   ORIGIN_PASSTHROUGH_ATTR_CONVERT,
+  ORIGIN_AGGREGATE_ATTR_AGG,
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
+  ORIGIN_AGGREGATE_ATTR_FILTER,
+  ORIGIN_ATTR_DISTINCT,
+  ORIGIN_ATTR_ORDER_BY,
+  ORIGIN_COMPUTED_ATTR_EXPR,
+  ORIGIN_FIRST_ATTR_OF,
+  ORIGIN_FIRST_ATTR_VIA,
+  ORIGIN_FIRST_ATTR_FILTER,
+  AGG_ANY,
+  AGG_ALL,
+  AGG_COLLECT,
 } from "../persistence/origin/origin-constants.js";
+import {
+  inferExprType,
+  validateExprNode,
+  type ExprNode,
+} from "../core/attr/meta-attr-expression.js";
+import { SORT_ORDER_VALUES } from "../core/query/query-constants.js";
 import {
   RELATIONSHIP_ATTR_OBJECT_REF,
   RELATIONSHIP_ATTR_CARDINALITY,
@@ -959,6 +980,49 @@ function _checkPassthroughType(
   );
 }
 
+/**
+ * #195 — validate `@orderBy` keys ('field[:asc|desc]') resolve against the
+ * RELATED entity's effective fields (the entity reached via `@via`/`@of`), and
+ * that any direction suffix is `asc`/`desc`. Null placement is pinned (nulls-last)
+ * and carries no vocabulary. Shared by `@agg:collect` (element order) and
+ * `origin.first` (row selection). A missing related entity means a prior error
+ * already fired — skip silently.
+ */
+function _validateOrderByKeys(
+  orderBy: unknown,
+  relatedEntity: MetaData | undefined,
+  obj: MetaData,
+  fieldName: string,
+  label: string,
+  originSource: ErrorSource,
+  errors: ParseError[],
+): void {
+  if (!Array.isArray(orderBy) || relatedEntity === undefined) return;
+  for (const raw of orderBy) {
+    if (typeof raw !== "string") continue;
+    const colonIdx = raw.indexOf(":");
+    const key = colonIdx === -1 ? raw : raw.slice(0, colonIdx);
+    const dir = colonIdx === -1 ? undefined : raw.slice(colonIdx + 1);
+    // ADR-0039: resolving — an ordering key may target an inherited field.
+    const target = relatedEntity.children().find((f) => f.type === TYPE_FIELD && f.name === key);
+    if (target === undefined) {
+      errors.push(
+        new ParseError(
+          `${label} on ${obj.name}.${fieldName}: @orderBy key "${raw}" — no such field "${key}" on ${relatedEntity.name}.`,
+          { code: "ERR_INVALID_ORIGIN", source: originSource },
+        ),
+      );
+    } else if (dir !== undefined && !(SORT_ORDER_VALUES as readonly string[]).includes(dir)) {
+      errors.push(
+        new ParseError(
+          `${label} on ${obj.name}.${fieldName}: @orderBy key "${raw}" — direction must be one of ${SORT_ORDER_VALUES.join("|")}.`,
+          { code: "ERR_INVALID_ORIGIN", source: originSource },
+        ),
+      );
+    }
+  }
+}
+
 export function validateOriginPaths(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
   // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
@@ -1020,26 +1084,106 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
           }
         } else if (origin.subType === ORIGIN_SUBTYPE_AGGREGATE) {
           // ADR-0039: own — origin.* never inherits (ADR-0029).
+          const src = origin.source;
+          const agg = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_AGG);
           const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
-          if (typeof of_ !== "string" || of_ === "") {
-            errors.push(
-              new ParseError(
-                `origin.aggregate on ${obj.name}.${field.name}: missing @of.`,
-                { code: "ERR_INVALID_ORIGIN", source: origin.source },
-              ),
-            );
+          const ofPresent = typeof of_ === "string" && of_ !== "";
+          const hasFilter = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_FILTER) !== undefined;
+          const hasDistinct = origin.ownAttr(ORIGIN_ATTR_DISTINCT) !== undefined;
+          const orderBy = origin.ownAttr(ORIGIN_ATTR_ORDER_BY);
+          const hasOrderBy = orderBy !== undefined;
+          const isPredicate = agg === AGG_ANY || agg === AGG_ALL;
+          const isCollect = agg === AGG_COLLECT;
+
+          // --- #195 field-shape rules ---
+          // collect ⇒ the carrying field is an array (it produces a list); every
+          // other @agg reduces to a scalar (the inverse rule closes a latent hole).
+          if (isCollect && !field.resolvedIsArray()) {
+            errors.push(new ParseError(
+              `origin.aggregate @agg:collect on ${obj.name}.${field.name}: the carrying field must be isArray:true (collect produces a list).`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+          } else if (!isCollect && field.resolvedIsArray()) {
+            errors.push(new ParseError(
+              `origin.aggregate @agg:${String(agg)} on ${obj.name}.${field.name}: a non-collect aggregate reduces to a scalar — the field must be isArray:false.`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+          }
+          // any/all yield a boolean.
+          if (isPredicate && field.subType !== FIELD_SUBTYPE_BOOLEAN) {
+            errors.push(new ParseError(
+              `origin.aggregate @agg:${String(agg)} on ${obj.name}.${field.name}: a predicate quantifier yields a boolean — the field must be field.boolean.`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+          }
+
+          // --- #195 attr-presence rules ---
+          if (hasDistinct && !isCollect) {
+            errors.push(new ParseError(
+              `origin.aggregate on ${obj.name}.${field.name}: @distinct is valid only on @agg:collect.`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+          }
+          if (hasOrderBy && !isCollect) {
+            errors.push(new ParseError(
+              `origin.aggregate on ${obj.name}.${field.name}: @orderBy is valid only on @agg:collect.`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+          }
+          if (isCollect && hasDistinct && hasOrderBy) {
+            errors.push(new ParseError(
+              `origin.aggregate @agg:collect on ${obj.name}.${field.name}: @orderBy and @distinct are mutually exclusive — a distinct collect uses value-ascending order (explicit element order is meaningful only without dedupe).`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+          }
+
+          if (isPredicate) {
+            // --- any/all: @filter REQUIRED, @of FORBIDDEN, @via REQUIRED (no @of
+            // to infer the path from) + must be to-many. ---
+            if (!hasFilter) {
+              errors.push(new ParseError(
+                `origin.aggregate @agg:${String(agg)} on ${obj.name}.${field.name}: a predicate quantifier requires @filter (the quantified predicate); "does any related row exist" is @agg:count.`,
+                { code: "ERR_INVALID_ORIGIN", source: src }));
+            }
+            if (ofPresent) {
+              errors.push(new ParseError(
+                `origin.aggregate @agg:${String(agg)} on ${obj.name}.${field.name}: @of is forbidden — a quantifier ranges over rows, not a column (the predicate is @filter).`,
+                { code: "ERR_INVALID_ORIGIN", source: src }));
+            }
+            const via = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
+            if (typeof via !== "string" || via === "") {
+              errors.push(new ParseError(
+                `origin.aggregate @agg:${String(agg)} on ${obj.name}.${field.name}: requires an explicit @via (a quantifier has no @of to infer the path from).`,
+                { code: "ERR_INVALID_ORIGIN", source: src }));
+            } else {
+              const hops = _validateViaPath(via, root, obj, field.name, src, errors);
+              if (hops !== undefined) _checkAggregateCardinality(hops, obj, field.name, src, errors);
+            }
+            continue;
+          }
+
+          // --- count/sum/avg/min/max/collect: @of REQUIRED ---
+          if (!ofPresent) {
+            errors.push(new ParseError(
+              `origin.aggregate on ${obj.name}.${field.name}: missing @of.`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
             continue;
           }
           // NOTE (FR-024 B6): NO extends/origin agreement check on aggregates —
           // an aggregate computes something new (count/sum/…); spec §4 defines
           // agreement for passthrough only.
-          const ofTarget = _validateFromPath(of_, root, obj, field.name, origin.source, errors, "origin.aggregate.@of");
+          const ofTarget = _validateFromPath(of_, root, obj, field.name, src, errors, "origin.aggregate.@of");
+          // #195 — collect preserves the element type: the array field's own subType
+          // must equal the @of column's subType (the #185 doctrine on the element).
+          if (isCollect && ofTarget !== undefined && field.subType !== ofTarget.field.subType) {
+            errors.push(new ParseError(
+              `origin.aggregate @agg:collect on ${obj.name}.${field.name}: field element type field.${field.subType} does not match the @of column type field.${ofTarget.field.subType} — collect preserves the element type.`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+          }
+          // @orderBy keys (collect only, non-distinct) resolve against the @of entity.
+          if (isCollect && hasOrderBy && !hasDistinct) {
+            _validateOrderByKeys(orderBy, ofTarget?.entity, obj, field.name, "origin.aggregate @agg:collect", src, errors);
+          }
           // ADR-0039: own — origin.* never inherits (ADR-0029).
           const via = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
-            const hops = _validateViaPath(via, root, obj, field.name, origin.source, errors);
+            const hops = _validateViaPath(via, root, obj, field.name, src, errors);
             if (hops !== undefined) {
-              _checkAggregateCardinality(hops, obj, field.name, origin.source, errors);
+              _checkAggregateCardinality(hops, obj, field.name, src, errors);
             }
             continue;
           }
@@ -1051,29 +1195,110 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             errors.push(
               new ParseError(
                 `origin.aggregate on ${obj.name}.${field.name}: missing @via (aggregates require a relationship path).`,
-                { code: "ERR_INVALID_ORIGIN", source: origin.source },
+                { code: "ERR_INVALID_ORIGIN", source: src },
               ),
             );
             continue;
           }
-          const base = _deriveBaseEntity(obj, root, field.name, origin.source, errors);
+          const base = _deriveBaseEntity(obj, root, field.name, src, errors);
           if (base === undefined) continue; // base underivable — error already pushed
           if (_isBaseRelationTarget(ofTarget.entity, base, obj)) {
             errors.push(
               new ParseError(
                 `origin.aggregate on ${obj.name}.${field.name}: missing @via (aggregates require a relationship path).`,
-                { code: "ERR_INVALID_ORIGIN", source: origin.source },
+                { code: "ERR_INVALID_ORIGIN", source: src },
               ),
             );
             continue;
           }
           const hops = _inferViaSingleHop(
             base, ofTarget.entity, obj, field.name, of_,
-            "origin.aggregate.@of", origin.source, errors,
+            "origin.aggregate.@of", src, errors,
           );
           if (hops !== undefined) {
-            _checkAggregateCardinality(hops, obj, field.name, origin.source, errors);
+            _checkAggregateCardinality(hops, obj, field.name, src, errors);
+          }
+        } else if (origin.subType === ORIGIN_SUBTYPE_COMPUTED) {
+          // #195 — a row-level expression over the base entity's OWN fields. No
+          // @via/@of (strict scoping already rejects them as ERR_UNKNOWN_ATTR).
+          const src = origin.source;
+          const expr = origin.ownAttr(ORIGIN_COMPUTED_ATTR_EXPR);
+          if (typeof expr !== "object" || expr === null) continue; // schema requires @expr (ERR_MISSING_REQUIRED_ATTR)
+          // Structural grammar (fail-closed unknown node) is validated HERE, not in
+          // the attr class, so every port validates the closed grammar identically
+          // (the other ports store @expr verbatim; C#/Python/Java mirror this pass).
+          const structural = validateExprNode(expr as ExprNode);
+          if (structural.length > 0) {
+            for (const m of structural) {
+              errors.push(new ParseError(
+                `origin.computed on ${obj.name}.${field.name}: ${m}`,
+                { code: "ERR_UNKNOWN_EXPR_NODE", source: src }));
+            }
+            continue;
+          }
+          // Type inference against the base entity's EFFECTIVE fields (ADR-0039).
+          const base = _deriveBaseEntity(obj, root, field.name, src, errors);
+          if (base === undefined) continue;
+          const resolveField = (name: string): string | undefined =>
+            base.children().find((f) => f.type === TYPE_FIELD && f.name === name)?.subType;
+          const inferred = inferExprType(expr as ExprNode, resolveField);
+          if (inferred.errors.length > 0) {
+            for (const m of inferred.errors) {
+              errors.push(new ParseError(
+                `origin.computed on ${obj.name}.${field.name}: ${m}`,
+                { code: "ERR_INVALID_ORIGIN", source: src }));
+            }
+            continue;
+          }
+          if (inferred.type !== undefined && inferred.type !== field.subType) {
+            errors.push(new ParseError(
+              `origin.computed on ${obj.name}.${field.name}: @expr infers field.${inferred.type} but the field is declared field.${field.subType} — a computed column's type is derived from its expression and must match (no @convert escape).`,
+              { code: "ERR_COMPUTED_TYPE_MISMATCH", source: src }));
           }
+        } else if (origin.subType === ORIGIN_SUBTYPE_FIRST) {
+          // #195 — pick one related row by @orderBy along @via, project @of.
+          const src = origin.source;
+          const of_ = origin.ownAttr(ORIGIN_FIRST_ATTR_OF);
+          const ofPresent = typeof of_ === "string" && of_ !== "";
+          if (!ofPresent) {
+            errors.push(new ParseError(
+              `origin.first on ${obj.name}.${field.name}: missing @of.`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+            continue;
+          }
+          // The carrying field must NOT be @required — an empty related set (after
+          // @filter) selects no row, so the value is null. ADR-0039: resolving.
+          if (field.attr(FIELD_ATTR_REQUIRED) === true) {
+            errors.push(new ParseError(
+              `origin.first on ${obj.name}.${field.name}: the field must not be @required — an empty related set (after @filter) yields null.`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+          }
+          const ofTarget = _validateFromPath(of_, root, obj, field.name, src, errors, "origin.first.@of");
+          // #185 type-preservation: first projects the @of column unchanged, so the
+          // field's subType must equal the @of column's subType (first is scalar).
+          if (ofTarget !== undefined && field.subType !== ofTarget.field.subType) {
+            errors.push(new ParseError(
+              `origin.first on ${obj.name}.${field.name}: field field.${field.subType} does not match the @of column field.${ofTarget.field.subType} — first projects the column unchanged, so the types must match.`,
+              { code: "ERR_INVALID_ORIGIN", source: src }));
+          }
+          // @via — explicit (validated + cardinality) or single-hop-unique inferred.
+          const via = origin.ownAttr(ORIGIN_FIRST_ATTR_VIA);
+          if (typeof via === "string" && via !== "") {
+            const hops = _validateViaPath(via, root, obj, field.name, src, errors);
+            if (hops !== undefined) _checkAggregateCardinality(hops, obj, field.name, src, errors);
+          } else if (ofTarget !== undefined && !isValueHost) {
+            const base = _deriveBaseEntity(obj, root, field.name, src, errors);
+            if (base !== undefined && !_isBaseRelationTarget(ofTarget.entity, base, obj)) {
+              const hops = _inferViaSingleHop(
+                base, ofTarget.entity, obj, field.name, of_,
+                "origin.first.@of", src, errors);
+              if (hops !== undefined) _checkAggregateCardinality(hops, obj, field.name, src, errors);
+            }
+          }
+          // @orderBy keys resolve against the related (@of) entity.
+          _validateOrderByKeys(
+            origin.ownAttr(ORIGIN_ATTR_ORDER_BY), ofTarget?.entity,
+            obj, field.name, "origin.first", src, errors);
         }
       }
     }
@@ -1658,3 +1883,133 @@ function checkFilterClauses(
     }
   }
 }
+
+// ---------------------------------------------------------------------------
+// #207 — projection row-scope @filter (view-level WHERE) reference validation
+//
+// A projection's @filter (a portable attr.filter object) scopes which rows the
+// derived view returns. Its field refs must name the projection's OWN declared
+// fields, and each must be ADDRESSABLE in a WHERE:
+//   - a plain (extends-bound / no-origin) or origin.passthrough or origin.computed
+//     field → addressable (a base/joined column, or an inlined row-level expression).
+//   - an aggregate-derived field (origin.aggregate — count/sum/…/any/all/collect —
+//     or origin.first / origin.collection) → NOT addressable: a WHERE runs before
+//     aggregation, so it cannot see an aggregate (post-aggregate filtering is HAVING,
+//     a separate later extension). Fail-closed → ERR_BAD_ATTR_FILTER.
+//   - a ref naming no declared field → dangling → ERR_BAD_ATTR_FILTER.
+//
+// Own-attrs only: the @filter is declared locally, and is registered on
+// object.projection alone — a write-through entity read-view (object.entity,
+// isWriteThrough) can never carry one, so filtered replicas (which would break
+// read-your-writes totality) are excluded by construction (v1 scope).
+// ---------------------------------------------------------------------------
+
+/** A projection field addressable by a @filter: its aggregate-derived-ness + its
+ *  op-band (by declared subType). Mirrors the dataGrid allowlist shape. */
+interface ProjectionFilterField {
+  readonly derived: boolean;
+  readonly ops: readonly string[];
+}
+
+export function validateProjectionFilter(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  // 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 && c.subType === OBJECT_SUBTYPE_PROJECTION)) {
+    // ADR-0039: own — the @filter is declared locally on this projection.
+    const filter = obj.ownAttr(OBJECT_PROJECTION_ATTR_FILTER);
+    // Non-object shapes are rejected by the attr schema check (FilterAttr.validateValue).
+    if (typeof filter !== "object" || filter === null || Array.isArray(filter)) continue;
+
+    // Classify the projection's OWN fields (the declared set IS the exposure —
+    // FR-024/ADR-0028): aggregate-derived-ness + the op-band legal for the field's
+    // declared subType. origin.* never inherits (ADR-0029), so the origin reads
+    // below are own (category 4).
+    const fields = new Map<string, ProjectionFilterField>();
+    for (const f of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+      const origin = f.ownChildren().find((c) => c.type === TYPE_ORIGIN);
+      const derived =
+        origin !== undefined &&
+        origin.subType !== ORIGIN_SUBTYPE_PASSTHROUGH &&
+        origin.subType !== ORIGIN_SUBTYPE_COMPUTED;
+      fields.set(f.name, { derived, ops: opsForSubType(f.subType) });
+    }
+    checkProjectionFilterRefs(filter as Record<string, unknown>, fields, obj.name, obj.source, errors);
+  }
+  return errors;
+}
+
+// Validates a projection @filter fail-closed at load — mirrors the dataGrid sibling
+// checkFilterClauses (which validates both field refs AND ops). A malformation that
+// slips through here lowers to a silently-wrong or no WHERE, or crashes `meta migrate`
+// / emits invalid CREATE VIEW SQL, so every branch that isn't a valid clause errors.
+function checkProjectionFilterRefs(
+  filter: Record<string, unknown>,
+  fields: ReadonlyMap<string, ProjectionFilterField>,
+  projectionName: string,
+  source: ErrorSource,
+  errors: ParseError[],
+): void {
+  const err = (message: string): void => {
+    errors.push(new ParseError(message, { code: "ERR_BAD_ATTR_FILTER", source }));
+  };
+  for (const [key, clause] of Object.entries(filter)) {
+    if (key === FILTER_COMPOSE_OR || key === FILTER_COMPOSE_AND) {
+      // Fail-closed: a compose key MUST hold an ARRAY of sub-clause objects. A non-array
+      // (a common object-vs-array authoring slip, e.g. `and: { … }`) would otherwise
+      // collapse to no WHERE at lowering — a soft-delete filter silently returning every
+      // row. Reject it, and any non-object element, here.
+      if (!Array.isArray(clause)) {
+        err(`projection "${projectionName}" @filter "${key}" must be an array of sub-clauses.`);
+        continue;
+      }
+      for (const sub of clause) {
+        if (typeof sub === "object" && sub !== null && !Array.isArray(sub)) {
+          checkProjectionFilterRefs(sub as Record<string, unknown>, fields, projectionName, source, errors);
+        } else {
+          err(`projection "${projectionName}" @filter "${key}" contains a non-object sub-clause.`);
+        }
+      }
+      continue;
+    }
+    const field = fields.get(key);
+    if (field === undefined) {
+      err(
+        `projection "${projectionName}" @filter references "${key}", which is not a declared field of the ` +
+          `projection. A view-level @filter may only reference the projection's own declared fields.`,
+      );
+      continue;
+    }
+    if (field.derived) {
+      err(
+        `projection "${projectionName}" @filter references "${key}", an aggregate-derived field. A view-level ` +
+          `WHERE runs before aggregation, so it cannot filter on an aggregate (post-aggregate filtering is a ` +
+          `separate HAVING extension). Filter on a passthrough or computed field instead.`,
+      );
+      continue;
+    }
+    // After parse-time desugaring (FilterAttr.desugar) every field clause is a canonical
+    // { op: value } object; a non-object or empty op-set would silently drop the predicate.
+    if (typeof clause !== "object" || clause === null || Array.isArray(clause)) {
+      err(`projection "${projectionName}" @filter on "${key}" must be an { op: value } object.`);
+      continue;
+    }
+    const ops = Object.keys(clause as Record<string, unknown>);
+    if (ops.length === 0) {
+      err(`projection "${projectionName}" @filter on "${key}" declares no operator.`);
+      continue;
+    }
+    // Every op must be legal for the field's subType — an unknown op (e.g. a typo
+    // `contains`) or a subtype-illegal op (e.g. `like` on a boolean) would otherwise
+    // crash the view synthesizer or emit invalid SQL at CREATE VIEW.
+    for (const op of ops) {
+      if (!field.ops.includes(op)) {
+        err(
+          `projection "${projectionName}" @filter on "${key}" uses op "${op}", which is not allowed for its ` +
+            `type. Allowed ops: ${field.ops.join(", ") || "(none)"}.`,
+        );
+      }
+    }
+  }
+}

package/src/persistence/db/db-definition.embedded.ts

@@ -181,6 +181,22 @@ export const DB_DEFINITION: ProviderDefinition = {
           "max": 1,
           "description": "Optional database schema name (e.g. 'catalog', 'public'). Postgres defaults to 'public'; SQLite rejects any non-default value."
         },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "sql",
+          "min": 0,
+          "max": 1,
+          "description": "FR-024/#208 escape valve — a hand-written SQL body the tool REGISTERS + fingerprints + drift-checks but never authors or parses. The body goes INSIDE `CREATE <kind> <physicalName> AS …` (never the CREATE wrapper, never the object name). Legal only on a read-only kind (not @kind: table); migrate lowers it on @kind: view (matview/proc/tableFunction: registered but not yet migrate-managed). Mutually exclusive with @unmanaged; forbids origin.* children (two sources of truth)."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "unmanaged",
+          "min": 0,
+          "max": 1,
+          "description": "FR-024/#208 escape valve — this DB object is managed elsewhere (Flyway / a hand-migration owns its DDL). meta migrate does NOT create, drop, or drift-check it; verify --db reports it as external (declared). Legal on any @kind including table (the externally-managed-entity case). Mutually exclusive with @sql."
+        },
         {
           "type": "attr",
           "subType": "string",

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

@@ -15,8 +15,13 @@ import {
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
   ORIGIN_COLLECTION_ATTR_VIA,
-  type AggregateFunction,
+  ORIGIN_COMPUTED_ATTR_EXPR,
+  ORIGIN_FIRST_ATTR_OF,
+  ORIGIN_FIRST_ATTR_VIA,
+  ORIGIN_ATTR_ORDER_BY,
+  type OriginAggValue,
 } from "./origin-constants.js";
+import type { ExprNode } from "../../core/attr/meta-attr-expression.js";
 
 export class MetaOrigin extends MetaData {}
 
@@ -50,11 +55,11 @@ export class MetaPassthroughOrigin extends MetaOrigin {
  * Carries `@agg`, `@of`, and `@via` (all required).
  */
 export class MetaAggregateOrigin extends MetaOrigin {
-  /** The aggregate function (count | sum | avg | min | max). */
-  get agg(): AggregateFunction | undefined {
+  /** The reducing function (count | sum | avg | min | max | any | all | collect). */
+  get agg(): OriginAggValue | undefined {
     // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
     const v = this.ownAttr(ORIGIN_AGGREGATE_ATTR_AGG);
-    return typeof v === "string" ? (v as AggregateFunction) : undefined;
+    return typeof v === "string" ? (v as OriginAggValue) : undefined;
   }
 
   /** The dotted-path target of the aggregate (e.g. "Week.id"). */
@@ -86,3 +91,49 @@ export class MetaCollectionOrigin extends MetaOrigin {
     return typeof v === "string" ? v : undefined;
   }
 }
+
+/**
+ * Computed origin (#195) — a row-level value computed from the base entity's own
+ * fields via a structured expression tree (`@expr`). No related rows, no `@via`.
+ * The expression's inferred type must equal the carrying field's declared subType
+ * (ERR_COMPUTED_TYPE_MISMATCH).
+ */
+export class MetaComputedOrigin extends MetaOrigin {
+  /** The structured expression tree computing this field's value. */
+  get expr(): ExprNode | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
+    const v = this.ownAttr(ORIGIN_COMPUTED_ATTR_EXPR);
+    return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as ExprNode) : undefined;
+  }
+}
+
+/**
+ * First origin (#195) — the single related row selected by `@orderBy` along
+ * `@via`, projecting its `@of` column (argmax-then-project). Empty related set
+ * (after `@filter`) → null, so the carrying field must not be `@required`.
+ *
+ * Carries `@of` (required, type-preserving), `@via` (optional; single-hop-unique
+ * inference), `@orderBy` (required), and an optional `@filter`.
+ */
+export class MetaFirstOrigin extends MetaOrigin {
+  /** The dotted Entity.field reference projected from the selected row (e.g. "ChildA.label"). */
+  get of(): string | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
+    const v = this.ownAttr(ORIGIN_FIRST_ATTR_OF);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  /** The dotted relationship path to the related rows (e.g. "Parent.childAs"). */
+  get via(): string | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
+    const v = this.ownAttr(ORIGIN_FIRST_ATTR_VIA);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  /** The ordering keys ('field[:asc|desc]') selecting the single row. */
+  get orderBy(): string[] | undefined {
+    // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct.
+    const v = this.ownAttr(ORIGIN_ATTR_ORDER_BY);
+    return Array.isArray(v) ? (v as string[]) : undefined;
+  }
+}

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

@@ -14,12 +14,19 @@ 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";
+// #195 — computed: a row-level value from the base entity's own fields via a
+// structured @expr tree (no related rows). first: the single related row picked
+// by @orderBy along @via, projecting @of (argmax-then-project).
+export const ORIGIN_SUBTYPE_COMPUTED    = "computed";
+export const ORIGIN_SUBTYPE_FIRST       = "first";
 
 export const ORIGIN_SUBTYPES = [
   SUBTYPE_BASE,
   ORIGIN_SUBTYPE_PASSTHROUGH,
   ORIGIN_SUBTYPE_AGGREGATE,
   ORIGIN_SUBTYPE_COLLECTION,
+  ORIGIN_SUBTYPE_COMPUTED,
+  ORIGIN_SUBTYPE_FIRST,
 ] as const;
 export type OriginSubType = (typeof ORIGIN_SUBTYPES)[number];
 
@@ -28,7 +35,7 @@ export const ORIGIN_PASSTHROUGH_ATTR_FROM = "from";
 export const ORIGIN_PASSTHROUGH_ATTR_VIA  = "via";
 // @convert (boolean): acknowledges a deliberate type change vs the @from source
 // (#185). Suppresses ERR_PASSTHROUGH_TYPE_MISMATCH. Acknowledgement only — it
-// does NOT generate a cast; real type-converting projections are origin.expression (#159).
+// does NOT generate a cast; real type-converting projections are origin.computed (#195/#159).
 export const ORIGIN_PASSTHROUGH_ATTR_CONVERT = "convert";
 
 // collection attrs — a relationship-derived array of nested view-objects
@@ -43,9 +50,44 @@ export const ORIGIN_AGGREGATE_ATTR_VIA = "via";
 // @filter (attr.filter object): an optional PORTABLE structured predicate scoping
 // which related rows the aggregate spans (same shape as a preset filter). Codegen
 // renders it per target — the projection view emitter turns it into SQL
-// FILTER (WHERE …) / SQLite CASE WHEN.
+// FILTER (WHERE …) / SQLite CASE WHEN. On @agg:any|all it is the QUANTIFIED
+// predicate (required there); on origin.first it scopes the eligible rows.
 export const ORIGIN_AGGREGATE_ATTR_FILTER = "filter";
+// #195 — shared origin attrs. @distinct (collect-only) applies set semantics;
+// @orderBy carries ordering keys ('field[:asc|desc]', nulls-last) used by
+// @agg:collect (element order) and required by origin.first (row selection).
+export const ORIGIN_ATTR_DISTINCT  = "distinct";
+export const ORIGIN_ATTR_ORDER_BY  = "orderBy";
 
-// aggregate function vocabulary
+// computed attrs — @expr is the structured expression tree (attr.expression).
+export const ORIGIN_COMPUTED_ATTR_EXPR = "expr";
+
+// first attrs — reuse the same physical names as aggregate (@of/@via/@filter)
+// plus the required @orderBy above.
+export const ORIGIN_FIRST_ATTR_OF     = "of";
+export const ORIGIN_FIRST_ATTR_VIA    = "via";
+export const ORIGIN_FIRST_ATTR_FILTER = "filter";
+
+// aggregate function vocabulary.
+//
+// AGGREGATE_FUNCTIONS is the NUMERIC/ORDINAL reduce set — each maps directly to a
+// SQL aggregate over the @of column and to the codegen `aggregate` SelectColumn
+// kind. The predicate quantifiers (any/all) and the array rollup (collect) are
+// distinct reducing behaviors handled by their own view-synthesis column kinds,
+// so they are NOT in this set; the full @agg vocabulary is ORIGIN_AGG_VALUES.
 export const AGGREGATE_FUNCTIONS = ["count", "sum", "avg", "min", "max"] as const;
 export type AggregateFunction = (typeof AGGREGATE_FUNCTIONS)[number];
+
+// #195 — the predicate-quantifier + array-rollup @agg values.
+export const AGG_ANY     = "any";
+export const AGG_ALL     = "all";
+export const AGG_COLLECT = "collect";
+
+/** The full @agg attribute vocabulary (matches origin.json allowedValues). */
+export const ORIGIN_AGG_VALUES = [
+  ...AGGREGATE_FUNCTIONS,
+  AGG_ANY,
+  AGG_ALL,
+  AGG_COLLECT,
+] as const;
+export type OriginAggValue = (typeof ORIGIN_AGG_VALUES)[number];