@metaobjectsdev/metadata 0.16.0 → 0.17.0-rc.1

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

@@ -49,9 +49,9 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
     {
       "type": "origin",
       "subType": "aggregate",
-      "description": "A count/sum/avg/min/max (@agg) computed over a column (@of) reached along a relationship path (@via) from the base entity.",
-      "whenToUse": "A projection needs a derived count/sum/avg/min/max over related rows. Declare it instead of hand-writing the aggregate query — it stays consistent and regenerates.",
-      "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly.",
+      "description": "A value reduced from the related row-set reached along a relationship path (@via) from the base entity: count/sum/avg/min/max over a column (@of); any/all predicate quantifiers over a @filter; or collect (an array rollup of @of).",
+      "whenToUse": "A projection needs a value derived by reducing related rows — a count/sum/avg/min/max, a 'did any/every related row match' flag, or an array of collected values. Declare it instead of hand-writing the aggregate query — it stays consistent and regenerates.",
+      "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly. @of is required for count/sum/avg/min/max/collect and forbidden for any/all (which quantify over rows via @filter, not a column). @filter is required for any/all. The field must be isArray:true for collect and isArray:false for every other @agg. @distinct and @orderBy are collect-only.",
       "children": [
         {
           "type": "attr",
@@ -64,17 +64,20 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
             "sum",
             "avg",
             "min",
-            "max"
+            "max",
+            "any",
+            "all",
+            "collect"
           ],
-          "description": "Aggregate function applied over the relationship path: count, sum, avg, min, or max."
+          "description": "The reducing function applied over the related row-set: count/sum/avg/min/max (numeric/ordinal reduces over @of); any/all (predicate quantifiers over @filter — @of forbidden; empty set → any=false, all=true); collect (array rollup of @of — the field must be isArray)."
         },
         {
           "type": "attr",
           "subType": "string",
           "name": "of",
-          "min": 1,
+          "min": 0,
           "max": 1,
-          "description": "Dotted Entity.field reference identifying the column being aggregated (e.g. 'Week.durationMinutes')."
+          "description": "Dotted Entity.field reference identifying the column being aggregated (e.g. 'Week.durationMinutes'). Required for count/sum/avg/min/max/collect; forbidden for any/all (which quantify over rows via @filter, not a column)."
         },
         {
           "type": "attr",
@@ -90,7 +93,24 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
           "name": "filter",
           "min": 0,
           "max": 1,
-          "description": "Optional structured predicate scoping which related rows the aggregate spans. A portable attr.filter object (eq/ne/in/isNull with and/or), desugared to canonical { field: { op: value } } at parse time; codegen renders it per target (e.g. SQL FILTER (WHERE ...) or SQLite CASE WHEN for a relational view)."
+          "description": "Optional structured predicate scoping which related rows the aggregate spans (required for any/all, where it is the quantified predicate). A portable attr.filter object (eq/ne/in/isNull with and/or), desugared to canonical { field: { op: value } } at parse time; codegen renders it per target (e.g. SQL FILTER (WHERE ...) or SQLite CASE WHEN for a relational view)."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "distinct",
+          "min": 0,
+          "max": 1,
+          "description": "Set (collect-only) to dedupe collected values (set semantics)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "orderBy",
+          "isArray": true,
+          "min": 0,
+          "max": 1,
+          "description": "Ordering keys as 'field[:asc|desc]' (default asc) over the related entity's fields; nulls sort last. On @agg:collect sets element order (non-distinct only); on origin.first (required) selects the row. Semantic — carries no SQL syntax."
         }
       ]
     },
@@ -109,6 +129,64 @@ export const ORIGIN_DEFINITION: ProviderDefinition = {
           "description": "Dotted relationship path the collection walks to produce an array of nested view-objects (e.g. 'Author.posts'), or a wildcard selector for a package-spanning collection (e.g. '*.User')."
         }
       ]
+    },
+    {
+      "type": "origin",
+      "subType": "computed",
+      "description": "A row-level value computed from the base entity's own fields via a structured expression tree (@expr). No related rows, no @via. Read-only; the expression's inferred type must equal the field's declared subType.",
+      "whenToUse": "A projection field is a cheap derived value over the base row itself (e.g. 'payload IS NOT NULL' to avoid shipping a heavy column). Declare the expression tree instead of hand-writing the derived SELECT column.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "expression",
+          "name": "expr",
+          "min": 1,
+          "max": 1,
+          "description": "The structured expression tree computing this field's value from the base entity's own fields (closed node grammar; shares the filter op vocabulary). Its inferred root type must equal the field's declared subType (ERR_COMPUTED_TYPE_MISMATCH)."
+        }
+      ]
+    },
+    {
+      "type": "origin",
+      "subType": "first",
+      "description": "The single related row selected by @orderBy along @via, projecting its @of column (argmax then project). Latest = @orderBy desc. Read-only; empty related set (after @filter) → null, so the field must not be @required.",
+      "whenToUse": "A projection needs one related row's column chosen by an ordering — 'the latest child's status', 'the earliest event's timestamp'. Declare @via + @of + @orderBy instead of hand-writing the correlated ORDER BY … LIMIT 1 subquery.",
+      "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (FR-024, ADR-0029). The related entity's primary key ascending is always appended as the final ordering tie-breaker so the selection is deterministic.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "of",
+          "min": 1,
+          "max": 1,
+          "description": "Dotted Entity.field reference identifying the column projected from the selected row (e.g. 'ChildA.label'). Type-preserving: the field's declared subType must equal this column's subType (#185 doctrine)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "via",
+          "min": 0,
+          "max": 1,
+          "description": "Dotted relationship path from the base entity to the related rows (e.g. 'Parent.childAs'). May be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (FR-024, ADR-0029)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "orderBy",
+          "isArray": true,
+          "min": 1,
+          "max": 1,
+          "description": "Ordering keys as 'field[:asc|desc]' (default asc) over the related entity's fields; nulls sort last. Selects the single row (the first after ordering). The related PK ascending is appended as the deterministic tie-breaker. Semantic — carries no SQL syntax."
+        },
+        {
+          "type": "attr",
+          "subType": "filter",
+          "name": "filter",
+          "min": 0,
+          "max": 1,
+          "description": "Optional structured predicate scoping which related rows are eligible for selection. A portable attr.filter object (eq/ne/in/isNull with and/or), desugared to canonical { field: { op: value } } at parse time."
+        }
+      ]
     }
   ]
 };

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

@@ -15,6 +15,8 @@ import {
   SOURCE_ATTR_FUNCTION,
   SOURCE_ATTR_KIND,
   SOURCE_ATTR_ROLE,
+  SOURCE_ATTR_SQL,
+  SOURCE_ATTR_UNMANAGED,
   SOURCE_READ_ONLY_KINDS,
   DEFAULT_SOURCE_KIND,
   DEFAULT_SOURCE_ROLE,
@@ -59,6 +61,27 @@ export class MetaSource extends MetaData {
     return typeof v === "string" && v !== "" ? v : DEFAULT_SOURCE_ROLE;
   }
 
+  /**
+   * FR-024/#208 — the hand-written SQL body for this source's DB object, when
+   * declared via `@sql`. The tool registers + fingerprints + drift-checks this
+   * body but never authors or parses it.
+   */
+  get sqlBody(): string | undefined {
+    // ADR-0039: resolving — an inherited source's @sql lives on the super node.
+    const v = this.attr(SOURCE_ATTR_SQL);
+    return typeof v === "string" && v !== "" ? v : undefined;
+  }
+
+  /**
+   * FR-024/#208 — true when this source's DB object is managed elsewhere
+   * (Flyway / a hand-migration owns its DDL); `meta migrate` does not
+   * create/drop/drift-check it.
+   */
+  get isUnmanaged(): boolean {
+    // ADR-0039: resolving — an inherited source's @unmanaged lives on the super node.
+    return this.attr(SOURCE_ATTR_UNMANAGED) === true;
+  }
+
   /**
    * True when this source's effective kind is read-only (view, materializedView,
    * storedProc, tableFunction). Derived from the @kind attr on source.rdb.

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

@@ -64,6 +64,16 @@ export const SOURCE_ATTR_ROLE = "role";
  *  new parameter.* node type. */
 export const SOURCE_ATTR_PARAMETER_REF = "parameterRef";
 
+/** FR-024/#208 escape valve — a hand-written SQL body the tool REGISTERS +
+ *  fingerprints + drift-checks but never authors or parses. Legal only on a
+ *  read-only @kind (not "table"). Mutually exclusive with @unmanaged; forbids
+ *  origin.* children. */
+export const SOURCE_ATTR_SQL = "sql";
+/** FR-024/#208 escape valve — this DB object is managed elsewhere (Flyway / a
+ *  hand-migration owns its DDL); meta migrate does not create/drop/drift-check
+ *  it. Legal on any @kind including "table". Mutually exclusive with @sql. */
+export const SOURCE_ATTR_UNMANAGED = "unmanaged";
+
 export const SOURCE_KIND_TABLE              = "table";
 export const SOURCE_KIND_VIEW               = "view";
 export const SOURCE_KIND_MATERIALIZED_VIEW  = "materializedView";

package/src/persistence/source/validate-source-escapes.ts

@@ -0,0 +1,158 @@
+// 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 type { MetaData } from "../../shared/meta-data.js";
+import { ParseError } from "../../errors.js";
+import type { LoaderWarning } from "../../source.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 interface SourceEscapeValidationResult {
+  errors: ParseError[];
+  warnings: LoaderWarning[];
+}
+
+export function validateSourceEscapes(root: MetaData): SourceEscapeValidationResult {
+  const errors: ParseError[] = [];
+  const warnings: LoaderWarning[] = [];
+
+  // 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 is MetaSource =>
+          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 is MetaField => 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 };
+}