@sequenceholdings/orm 0.1.3 → 2.1.0

package/dist/compiler.js

@@ -1,10 +1,11 @@
 import { createHash } from 'crypto';
 import { z } from 'zod';
-import { Kind, print, buildSchema, parse, validate, valueFromASTUntyped } from 'graphql';
+import { Kind, print, visit, buildSchema, parse, validate, valueFromASTUntyped } from 'graphql';
 
 // src/compiler-gql/artifact.ts
 
 // src/constants.ts
+var COLUMN_IDENTIFIER_PATTERN = /^_?[a-z][a-z0-9_]*$/;
 var CAPABILITY_KEY_PATTERN = /^(?:org\/)?[a-z0-9-]{1,64}$/;
 var ORM_SCHEMA_PREFIX = "orm_";
 var ormSchemaName = (namespace) => `${ORM_SCHEMA_PREFIX}${namespace}`;
@@ -19,6 +20,7 @@ function stableJson(value) {
 var CANONICAL_FORMAT = 2;
 var IDENTIFIER_RE = /^[a-z][a-z0-9_]*$/;
 var identifier = z.string().min(1).max(63).regex(IDENTIFIER_RE);
+var columnIdentifier = z.string().min(1).max(63).regex(COLUMN_IDENTIFIER_PATTERN);
 var COLUMN_TYPES = [
   "uuid",
   "text",
@@ -39,18 +41,33 @@ var canonicalEnumSchema = z.object({
 var canonicalColumnSchema = z.object({
   /** Property name in TS (camelCase); columnName is the Postgres name. */
   name: z.string().min(1).max(63),
-  columnName: identifier,
+  columnName: columnIdentifier,
   type: z.union([columnTypeSchema, z.object({ enum: identifier })]),
   nullable: z.boolean().default(true),
   unique: z.boolean().default(false),
   /** Literal default, or one of the allowlisted SQL functions. */
   default: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
   defaultFn: z.enum(["gen_random_uuid()", "now()"]).optional(),
+  /**
+   * Stamp this column from the database clock on UPDATE (`now()`). The
+   * column stays insertable (defaults fill gaps) but is omitted from
+   * SetInput / settable so callers cannot backdate it.
+   */
+  onUpdateFn: z.enum(["now()"]).optional(),
   description: z.string().max(500).optional(),
   /** Migration hints — same semantics as v1. */
-  renamedFrom: identifier.optional(),
+  renamedFrom: columnIdentifier.optional(),
   cast: z.string().max(200).optional(),
   deprecated: z.boolean().default(false)
+}).superRefine((column, ctx) => {
+  if (column.onUpdateFn === void 0) return;
+  if (typeof column.type !== "string" || column.type !== "timestamptz" && column.type !== "date") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["onUpdateFn"],
+      message: `onUpdateFn '${column.onUpdateFn}' is only valid on timestamptz/date columns`
+    });
+  }
 });
 var canonicalLinkSchema = z.object({
   name: z.string().min(1).max(63),
@@ -58,15 +75,15 @@ var canonicalLinkSchema = z.object({
   /** Target table name (namespace-local). Absent for toPlatformUser. */
   target: identifier.optional(),
   /** FK column on the owning side (toOne/toPlatformUser: on this table; toMany: on the target). */
-  on: identifier,
+  on: columnIdentifier,
   /** Referenced column on the target (default: target's PK / platform user `sub`). */
-  references: identifier.optional(),
+  references: columnIdentifier.optional(),
   /** enforce: true emits a real FK constraint (same-namespace toOne only). */
   enforce: z.boolean().default(false),
   description: z.string().max(500).optional()
 });
 var canonicalIndexSchema = z.object({
-  columns: z.array(identifier).min(1),
+  columns: z.array(columnIdentifier).min(1),
   unique: z.boolean().default(false),
   name: identifier.optional()
 });
@@ -157,6 +174,13 @@ var canonicalCowMutationSchema = z.object({
     }
   }
 });
+var canonicalForeignKeySchema = z.object({
+  name: identifier,
+  columns: z.array(columnIdentifier).min(1).max(8),
+  target: identifier,
+  references: z.array(columnIdentifier).min(1).max(8),
+  deferrable: z.enum(["initially-immediate", "initially-deferred"]).optional()
+}).strict();
 var canonicalTableSchema = z.object({
   table: identifier,
   description: z.string().max(2e3).optional(),
@@ -165,7 +189,7 @@ var canonicalTableSchema = z.object({
   /** Synced/reflected read-only tables (`source: gold.*`) — v1 semantics. */
   source: z.string().regex(/^gold\.[a-z][a-z0-9_]*$/).optional(),
   columns: z.array(canonicalColumnSchema).default([]),
-  primaryKey: z.array(identifier).min(1).max(8).optional(),
+  primaryKey: z.array(columnIdentifier).min(1).max(8).optional(),
   links: z.array(canonicalLinkSchema).default([]),
   indexes: z.array(canonicalIndexSchema).default([]),
   policies: canonicalPoliciesSchema.default({}),
@@ -176,14 +200,16 @@ var canonicalTableSchema = z.object({
    */
   actions: z.array(canonicalActionSchema).default([]),
   /** Optional (not defaulted) so pre-CoW canonical documents keep byte-identical hashes. */
-  cowMutations: z.array(canonicalCowMutationSchema).optional()
+  cowMutations: z.array(canonicalCowMutationSchema).optional(),
+  /** Omitted by old definitions, preserving their existing content hashes. */
+  foreignKeys: z.array(canonicalForeignKeySchema).max(100).optional()
 });
 var canonicalViewSchema = z.object({
   view: identifier,
   description: z.string().max(2e3).optional(),
   columns: z.array(canonicalColumnSchema).min(1),
   /** Logical identity for GraphQL only; PostgreSQL views have no PK constraint. */
-  primaryKey: z.array(identifier).min(1).max(8).optional(),
+  primaryKey: z.array(columnIdentifier).min(1).max(8).optional(),
   links: z.array(canonicalLinkSchema).default([]),
   policies: z.object({ read: policyExpressionSchema }).strict(),
   query: z.string().min(1).max(1e5).refine(isSingleViewQuerySql, {
@@ -196,6 +222,9 @@ var canonicalViewSchema = z.object({
     if (column.default !== void 0 || column.defaultFn !== void 0) {
       ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare a default` });
     }
+    if (column.onUpdateFn !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare onUpdateFn` });
+    }
     if (column.unique) {
       ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare unique` });
     }
@@ -229,6 +258,45 @@ var canonicalDefinitionSchema = z.object({
       ctx.addIssue({ code: "custom", path: ["tables", index, "table"], message: `duplicate relation '${table.table}'` });
     }
     seen.add(table.table);
+    if (table.source !== void 0) {
+      for (const [columnIndex, column] of table.columns.entries()) {
+        if (column.onUpdateFn !== void 0) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["tables", index, "columns", columnIndex],
+            message: `synced table '${table.table}' column '${column.name}' cannot declare onUpdateFn`
+          });
+        }
+      }
+    }
+  }
+  const fkTables = new Map(definition.tables.map((table) => [table.table, table]));
+  for (const [tableIndex, table] of definition.tables.entries()) {
+    const names = /* @__PURE__ */ new Set([
+      ...table.primaryKey?.length ? [`${table.table}_pkey`] : [],
+      ...table.columns.filter((column) => column.unique && !(table.primaryKey?.length === 1 && table.primaryKey[0] === column.columnName)).map((column) => `${table.table}_${column.columnName}_unique`),
+      ...table.links.filter((link) => link.enforce).map((link) => `fk_${table.table}_${link.name}`)
+    ]);
+    for (const [index, fk] of (table.foreignKeys ?? []).entries()) {
+      const fail2 = (message) => ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "foreignKeys", index], message });
+      if (names.has(fk.name)) fail2(`duplicate foreign key '${fk.name}'`);
+      names.add(fk.name);
+      const target = fkTables.get(fk.target);
+      if (table.source || !target || target.source) {
+        fail2("foreign keys must connect owned tables in the same namespace");
+        continue;
+      }
+      if (fk.columns.length !== fk.references.length) fail2("foreign key columns and references must have the same number of columns");
+      if (new Set(fk.columns).size !== fk.columns.length || new Set(fk.references).size !== fk.references.length) fail2("foreign key columns must not repeat");
+      for (const [position, name] of fk.columns.entries()) {
+        const sourceColumn = table.columns.find((column) => column.columnName === name);
+        const targetColumn = target.columns.find((column) => column.columnName === fk.references[position]);
+        if (!sourceColumn || !targetColumn) fail2("foreign key references an unknown column");
+        else if (JSON.stringify(sourceColumn.type) !== JSON.stringify(targetColumn.type)) fail2("foreign key column types must match");
+      }
+      const uniqueKeys = [target.primaryKey ?? [], ...target.indexes.filter((index2) => index2.unique).map((index2) => index2.columns), ...target.columns.filter((column) => column.unique).map((column) => [column.columnName])];
+      if (!uniqueKeys.some((key) => key.length === fk.references.length && key.every((column) => fk.references.includes(column)))) fail2("foreign key target columns must form a unique key");
+    }
   }
   const tableByName = new Map(definition.tables.map((table) => [table.table, table]));
   for (const [tableIndex, table] of definition.tables.entries()) {
@@ -324,7 +392,7 @@ var canonicalDefinitionSchema = z.object({
   const visiting = /* @__PURE__ */ new Set();
   const visited = /* @__PURE__ */ new Set();
   let cycleReported = false;
-  const visit = (name, path) => {
+  const visit2 = (name, path) => {
     if (visited.has(name) || cycleReported) return;
     if (visiting.has(name)) {
       cycleReported = true;
@@ -338,12 +406,12 @@ var canonicalDefinitionSchema = z.object({
     visiting.add(name);
     const view = viewByName.get(name);
     for (const dependency of view?.dependencies ?? []) {
-      if (viewByName.has(dependency)) visit(dependency, [...path, name]);
+      if (viewByName.has(dependency)) visit2(dependency, [...path, name]);
     }
     visiting.delete(name);
     visited.add(name);
   };
-  for (const view of views) visit(view.view, []);
+  for (const view of views) visit2(view.view, []);
 });
 function canonicalRelations(definition) {
   const views = (definition.views ?? []).map((view) => ({
@@ -364,12 +432,13 @@ function normalizeCanonical(definition) {
     ...definition,
     enums: sortByName(definition.enums),
     tables: [...definition.tables].sort((a, b) => a.table.localeCompare(b.table)).map((t) => {
-      const { cowMutations, ...rest } = t;
+      const { cowMutations, foreignKeys, ...rest } = t;
       return {
         ...rest,
         links: sortByName(t.links),
         indexes: [...t.indexes].sort((a, b) => (a.name ?? a.columns.join("_")).localeCompare(b.name ?? b.columns.join("_"))),
         actions: sortByName(t.actions),
+        ...foreignKeys?.length ? { foreignKeys: sortByName(foreignKeys) } : {},
         // Omitted entirely when absent/empty so pre-CoW documents hash unchanged.
         ...cowMutations !== void 0 && cowMutations.length > 0 ? { cowMutations: sortByName(cowMutations) } : {}
       };
@@ -386,7 +455,18 @@ function normalizeCanonical(definition) {
 }
 
 // src/ir/index.ts
-var IR_VERSION = 1;
+var IR_VERSION = 2;
+var LEGACY_IR_VERSION = 1;
+var irVersionSchema = z.union([z.literal(LEGACY_IR_VERSION), z.literal(IR_VERSION)]);
+var operationVersionSchema = z.object({ irVersion: irVersionSchema });
+function requiredArtifactIrVersion(operations) {
+  let required = LEGACY_IR_VERSION;
+  for (const operation of operations) {
+    const { irVersion } = operationVersionSchema.parse(operation);
+    if (irVersion > required) required = irVersion;
+  }
+  return required;
+}
 var CLAIMS_CONTRACT = {
   sub: "string",
   org: "string?",
@@ -513,6 +593,33 @@ var aggregateRootSchema = z.object({
   nodes: selectionIrSchema.optional(),
   includeIf: includeIfSchema.optional()
 });
+var DATE_BUCKETS = ["year", "quarter", "month", "week", "day", "hour"];
+var groupByKeyIrSchema = z.object({
+  column: z.string(),
+  bucket: z.enum(DATE_BUCKETS).optional()
+});
+var aggregateGroupsRootSchema = z.object({
+  kind: z.literal("aggregateGroups"),
+  alias: z.string(),
+  table: z.string(),
+  /** Composed at compile time: AND(policy, documentWhere?, dynamicFilter?). */
+  where: predIrSchema,
+  groupBy: z.array(groupByKeyIrSchema).min(1),
+  /**
+   * The `key { … }` projection: which group columns appear in each entry's key
+   * object, in selection order. A subset of `groupBy` (the compiler rejects a
+   * key field that is not a group key — it would be indeterminate within the
+   * group). Empty when the document selects only `aggregate`.
+   */
+  key: z.array(z.object({ alias: z.string(), column: z.string() })).default([]),
+  count: z.object({ columns: z.array(z.string()).optional(), distinct: z.boolean().optional() }).optional(),
+  sum: z.array(z.string()).optional(),
+  avg: z.array(z.string()).optional(),
+  /** Bounds the GROUP count, not the scanned rows — see MAX_GROUPS. */
+  limit: limitIrSchema,
+  offset: z.object({ variable: z.string().optional(), value: z.number().int().optional() }).optional(),
+  includeIf: includeIfSchema.optional()
+});
 var writeValuesSchema = z.union([
   z.object({ slot: z.string() }),
   z.object({ entries: z.array(z.object({ column: z.string(), value: valueIrSchema })) })
@@ -558,12 +665,15 @@ var mutationRootSchema = z.object({
   insertCheck: predIrSchema.optional(),
   returning: selectionIrSchema.nullable(),
   affectedRows: z.boolean().default(false),
+  /** v2: abort the transaction when the actual write count differs, regardless of selection. */
+  assertAffectedRows: z.number().int().min(0).max(2147483647).optional(),
   includeIf: includeIfSchema.optional()
 });
 var rootIrSchema = z.discriminatedUnion("kind", [
   selectRootSchema,
   byPkRootSchema,
   aggregateRootSchema,
+  aggregateGroupsRootSchema,
   mutationRootSchema
 ]);
 var INPUT_REF_KINDS = [
@@ -593,7 +703,7 @@ var variableIrSchema = z.object({
   defaultValue: variableDefaultIrSchema.optional()
 });
 var compiledOperationSchema = z.object({
-  irVersion: z.literal(IR_VERSION),
+  irVersion: irVersionSchema,
   name: z.string(),
   opHash: z.string().regex(/^sha256:[0-9a-f]{64}$/),
   kind: z.enum(["query", "mutation"]),
@@ -605,6 +715,13 @@ var compiledOperationSchema = z.object({
   /** Every table the op touches — data-token scoping + audit. */
   tableSet: z.array(z.string()).min(1),
   roots: z.array(rootIrSchema).min(1)
+}).superRefine((operation, ctx) => {
+  for (const [index, root] of operation.roots.entries()) {
+    if (root.kind !== "mutation" || root.assertAffectedRows === void 0) continue;
+    if (operation.irVersion < 2 || operation.kind !== "mutation" || root.includeIf !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["roots", index], message: "affected-row assertions require unconditional mutation roots and IR v2" });
+    }
+  }
 });
 var tableMetaIrSchema = z.object({
   table: z.string(),
@@ -641,18 +758,29 @@ var tableMetaIrSchema = z.object({
   insertable: z.array(z.string()),
   settable: z.array(z.string()),
   appendable: z.array(z.string()),
+  /**
+   * Logical columns stamped with Postgres `now()` on UPDATE (canonical
+   * `onUpdateFn`). Omitted when empty so pre-onUpdate artifacts still parse.
+   */
+  touchOnUpdate: z.array(z.string()).optional(),
   constraints: z.array(z.object({ name: z.string(), columns: z.array(z.string()) })),
   /** Depth/node caps for dynamic filter trees on this table. */
   dynamicFilterMaxDepth: z.number().int().positive().default(6),
   dynamicFilterMaxNodes: z.number().int().positive().default(64)
 });
 var compiledArtifactSchema = z.object({
-  irVersion: z.literal(IR_VERSION),
+  irVersion: irVersionSchema,
   namespace: z.string(),
   schemaHash: z.string(),
   opsHash: z.string(),
   tables: z.record(z.string(), tableMetaIrSchema),
   operations: z.record(z.string(), compiledOperationSchema)
+}).superRefine((artifact, ctx) => {
+  for (const [name, operation] of Object.entries(artifact.operations)) {
+    if (operation.irVersion > artifact.irVersion) {
+      ctx.addIssue({ code: "custom", path: ["operations", name, "irVersion"], message: "operation requires a newer IR version than its artifact" });
+    }
+  }
 });
 var IrVersionError = class extends Error {
   constructor(found) {
@@ -663,19 +791,19 @@ var IrVersionError = class extends Error {
 function normalizeIr(raw) {
   if (!raw || typeof raw !== "object") throw new IrVersionError(void 0);
   const version = raw.irVersion;
-  if (version !== IR_VERSION) throw new IrVersionError(version);
+  if (version !== LEGACY_IR_VERSION && version !== IR_VERSION) throw new IrVersionError(version);
   return compiledArtifactSchema.parse(raw);
 }
 
 // src/predicate-v2/ast.ts
 var POLICY_COMPARE_OPS = ["=", "!=", "<", "<=", ">", ">="];
-function walkPolicy(node, visit) {
-  visit(node);
+function walkPolicy(node, visit2) {
+  visit2(node);
   if (node.kind === "and" || node.kind === "or") {
-    for (const operand of node.operands) walkPolicy(operand, visit);
+    for (const operand of node.operands) walkPolicy(operand, visit2);
   }
-  if (node.kind === "not") walkPolicy(node.operand, visit);
-  if (node.kind === "exists") walkPolicy(node.where, visit);
+  if (node.kind === "not") walkPolicy(node.operand, visit2);
+  if (node.kind === "exists") walkPolicy(node.where, visit2);
 }
 
 // src/predicate-v2/errors.ts
@@ -813,6 +941,10 @@ var Parser = class {
       this.expect("rparen", "')'");
       return inner;
     }
+    if (this.peekKeyword("true") || this.peekKeyword("false")) {
+      const token = this.advance();
+      return { kind: "literal", value: token.value === "true" };
+    }
     if (this.peekKeyword("capability") || this.peekKeyword("role")) {
       const fn = this.peek().value;
       const node = this.parseBooleanCall(fn);
@@ -996,6 +1128,8 @@ var PolicyCompiler = class {
   }
   compile(node, table, depth) {
     switch (node.kind) {
+      case "literal":
+        return { kind: "const", value: node.value };
       case "and":
       case "or":
         return { kind: node.kind, operands: node.operands.map((operand) => this.compile(operand, table, depth)) };
@@ -1175,21 +1309,21 @@ function andPred(...preds) {
   if (operands.length === 1) return operands[0];
   return { kind: "and", operands };
 }
-function walkPred(pred, visit) {
-  visit(pred);
+function walkPred(pred, visit2) {
+  visit2(pred);
   switch (pred.kind) {
     case "and":
     case "or":
-      for (const operand of pred.operands) walkPred(operand, visit);
+      for (const operand of pred.operands) walkPred(operand, visit2);
       return;
     case "not":
-      walkPred(pred.operand, visit);
+      walkPred(pred.operand, visit2);
       return;
     case "exists":
-      walkPred(pred.where, visit);
+      walkPred(pred.where, visit2);
       return;
     case "aggPredicate":
-      if (pred.where) walkPred(pred.where, visit);
+      if (pred.where) walkPred(pred.where, visit2);
       return;
     default:
       return;
@@ -1214,12 +1348,12 @@ function predContains(haystack, needle) {
 // src/compiler-gql/inject.ts
 function collectPinnedColumns(writePolicy) {
   const key = (pin) => `${pin.column}\0${pin.claim}`;
-  const visit = (node) => {
+  const visit2 = (node) => {
     if (node.kind === "and") {
       const merged = [];
       const seen2 = /* @__PURE__ */ new Set();
       for (const operand of node.operands) {
-        for (const pin of visit(operand)) {
+        for (const pin of visit2(operand)) {
           if (seen2.has(key(pin))) continue;
           seen2.add(key(pin));
           merged.push(pin);
@@ -1230,9 +1364,9 @@ function collectPinnedColumns(writePolicy) {
     if (node.kind === "or") {
       const [first, ...rest] = node.operands;
       if (first === void 0) return [];
-      let common = visit(first);
+      let common = visit2(first);
       for (const operand of rest) {
-        const branch = new Set(visit(operand).map(key));
+        const branch = new Set(visit2(operand).map(key));
         common = common.filter((pin) => branch.has(key(pin)));
         if (common.length === 0) break;
       }
@@ -1244,7 +1378,7 @@ function collectPinnedColumns(writePolicy) {
     return [];
   };
   const seen = /* @__PURE__ */ new Set();
-  return visit(writePolicy).filter((pin) => {
+  return visit2(writePolicy).filter((pin) => {
     if (seen.has(pin.column)) return false;
     seen.add(pin.column);
     return true;
@@ -1338,6 +1472,11 @@ var PolicyInjector = class {
           where: andPred(this.read(root.table), this.injectDocPred(root.where, root.table)),
           ...root.nodes ? { nodes: this.injectSelection(root.nodes, root.table) } : {}
         };
+      case "aggregateGroups":
+        return {
+          ...root,
+          where: andPred(this.read(root.table), this.injectDocPred(root.where, root.table))
+        };
       case "mutation":
         return this.injectMutation(root);
     }
@@ -1430,20 +1569,33 @@ function collectTableSet(roots, ctx) {
   };
   for (const root of roots) {
     tables.add(root.table);
-    if (root.kind === "select" || root.kind === "byPk") {
-      visitPred(root.where, root.table);
-      visitSelection(root.selection, root.table);
-    }
-    if (root.kind === "aggregate") {
-      visitPred(root.where, root.table);
-      if (root.nodes) visitSelection(root.nodes, root.table);
-    }
-    if (root.kind === "mutation") {
-      if (root.cowSynced !== void 0) tables.add(root.cowSynced);
-      if (root.where) visitPred(root.where, root.table);
-      if (root.insertCheck) visitPred(root.insertCheck, root.table);
-      if (root.cowCopyCheck) visitPred(root.cowCopyCheck, root.table);
-      if (root.returning) visitSelection(root.returning, root.table);
+    switch (root.kind) {
+      case "select":
+      case "byPk":
+        visitPred(root.where, root.table);
+        visitSelection(root.selection, root.table);
+        break;
+      case "aggregate":
+        visitPred(root.where, root.table);
+        if (root.nodes) visitSelection(root.nodes, root.table);
+        break;
+      case "aggregateGroups":
+        visitPred(root.where, root.table);
+        break;
+      case "mutation":
+        if (root.cowSynced !== void 0) tables.add(root.cowSynced);
+        if (root.where) visitPred(root.where, root.table);
+        if (root.insertCheck) visitPred(root.insertCheck, root.table);
+        if (root.cowCopyCheck) visitPred(root.cowCopyCheck, root.table);
+        if (root.returning) visitSelection(root.returning, root.table);
+        break;
+      default: {
+        const exhausted = root;
+        throw new DocumentCompileError(
+          `internal: unhandled root kind in tableSet collection ${JSON.stringify(exhausted)}`,
+          "internal"
+        );
+      }
     }
   }
   return [...tables].sort();
@@ -1542,7 +1694,12 @@ function tableNames(table) {
     sumFields: `${type}SumFields`,
     avgFields: `${type}AvgFields`,
     aggregateBoolExp: `${type}AggregateBoolExp`,
-    aggregateBoolExpCount: `${type}AggregateBoolExpCount`
+    aggregateBoolExpCount: `${type}AggregateBoolExpCount`,
+    aggregateGroupsRoot: `${root}AggregateGroups`,
+    groupByColumnEnum: `${type}GroupByColumn`,
+    groupByInput: `${type}GroupBy`,
+    groupKey: `${type}GroupKey`,
+    aggregateGroup: `${type}AggregateGroup`
   };
 }
 
@@ -1553,7 +1710,12 @@ function typeNameForTable(table) {
 }
 function queryRootNames(table) {
   const names = tableNames(table);
-  return { select: names.selectRoot, byPk: names.byPkRoot, aggregate: names.aggregateRoot };
+  return {
+    select: names.selectRoot,
+    byPk: names.byPkRoot,
+    aggregate: names.aggregateRoot,
+    aggregateGroups: names.aggregateGroupsRoot
+  };
 }
 function mutationRootNames(table) {
   const names = tableNames(table);
@@ -1646,7 +1808,14 @@ function resolveColumnEntries(table, enums, diagnostics) {
         type = { enum: enumDef.name, values: [...enumDef.values] };
       }
     }
-    return { name: column.name, columnName: column.columnName, type, nullable: column.nullable, deprecated: column.deprecated };
+    return {
+      name: column.name,
+      columnName: column.columnName,
+      type,
+      nullable: column.nullable,
+      deprecated: column.deprecated,
+      onUpdateFn: column.onUpdateFn !== void 0
+    };
   });
 }
 function logicalColumn(entries, ref) {
@@ -1695,6 +1864,7 @@ function buildCompileContext(rawCanonical) {
       primaryKey.push(resolved);
     }
     const active = entries.filter((c) => !c.deprecated);
+    const touchOnUpdate = isView ? [] : active.filter((c) => c.onUpdateFn).map((c) => c.name);
     const constraints = [];
     if (primaryKey.length > 0) constraints.push({ name: `${table.table}_pkey`, columns: [...primaryKey] });
     for (const column of table.columns) {
@@ -1715,14 +1885,15 @@ function buildCompileContext(rawCanonical) {
       // Synced twins (and views reading them, resolved transitively below)
       // are claims-gated — see tableMetaIrSchema.claimsGated.
       claimsGated: relationIsClaimsGated(table.table),
-      columns: entries.map(({ deprecated: _deprecated, ...column }) => column),
+      columns: entries.map(({ deprecated: _deprecated, onUpdateFn: _onUpdateFn, ...column }) => column),
       primaryKey: isView ? primaryKey : primaryKey.length > 0 ? primaryKey : ["id"],
       links: [],
       filterable: entries.map((c) => c.name),
       orderable: entries.filter((c) => c.type !== "jsonb").map((c) => c.name),
       insertable: isView ? [] : active.map((c) => c.name),
-      settable: isView ? [] : active.map((c) => c.name),
+      settable: isView ? [] : active.filter((c) => !c.onUpdateFn).map((c) => c.name),
       appendable: isView ? [] : active.filter((c) => c.type === "jsonb").map((c) => c.name),
+      ...touchOnUpdate.length > 0 ? { touchOnUpdate } : {},
       constraints: isView ? [] : constraints,
       dynamicFilterMaxDepth: 6,
       dynamicFilterMaxNodes: 64
@@ -1743,7 +1914,7 @@ function buildCompileContext(rawCanonical) {
         });
         continue;
       }
-      const targetEntries = targetName === PLATFORM_USER_TABLE ? target.columns.map((c) => ({ ...c, deprecated: false })) : columnEntries.get(targetName);
+      const targetEntries = targetName === PLATFORM_USER_TABLE ? target.columns.map((c) => ({ ...c, deprecated: false, onUpdateFn: false })) : columnEntries.get(targetName);
       const onEntries = link.kind === "toMany" ? targetEntries : entries;
       const referencesEntries = link.kind === "toMany" ? entries : targetEntries;
       const on = logicalColumn(onEntries, link.on);
@@ -1840,6 +2011,9 @@ function buildCompileContext(rawCanonical) {
       queryRoots.set(roots.byPk, { kind: "byPk", table: table.table });
     }
     queryRoots.set(roots.aggregate, { kind: "aggregate", table: table.table });
+    if (table.columns.some((column) => column.type !== "jsonb")) {
+      queryRoots.set(roots.aggregateGroups, { kind: "aggregateGroups", table: table.table });
+    }
     const hasWritePolicy = table.policies.write !== void 0 || table.policies.insert !== void 0 || table.policies.update !== void 0;
     if (!viewNames.has(table.table) && table.source === void 0 && hasWritePolicy) {
       for (const [op, field] of Object.entries(mutationRootNames(table.table))) {
@@ -1975,6 +2149,16 @@ function computeOpsHash(opHashes) {
 }
 var DEFAULT_LIMIT = 100;
 var MAX_LIMIT = 1e3;
+var MAX_GROUPS = 1e3;
+var DATE_BUCKET_BY_ENUM = {
+  YEAR: "year",
+  QUARTER: "quarter",
+  MONTH: "month",
+  WEEK: "week",
+  DAY: "day",
+  HOUR: "hour"
+};
+var BUCKETABLE_TYPES = /* @__PURE__ */ new Set(["timestamptz", "date"]);
 var BOOLEXP_OPS = {
   _eq: "eq",
   _neq: "neq",
@@ -2006,6 +2190,14 @@ function fail(message, code, candidates = []) {
 function argsByName(field) {
   return new Map((field.arguments ?? []).map((arg) => [arg.name.value, arg]));
 }
+function* aggregateBlockFields(selectionSet) {
+  for (const node of selectionSet.selections) {
+    if (node.kind !== Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+    if (node.name.value === "__typename") continue;
+    if (node.alias) fail(`aliases are not supported inside aggregate blocks ('${node.alias.value}')`, "invalid-aggregate");
+    yield node;
+  }
+}
 function assertKnownArgs(field, allowed) {
   for (const arg of field.arguments ?? []) {
     if (!allowed.includes(arg.name.value)) {
@@ -2306,11 +2498,8 @@ var OperationLowerer = class {
   lowerAggregateSelection(selectionSet, table) {
     const result = {};
     let sawAggregate = false;
-    for (const node of selectionSet.selections) {
-      if (node.kind !== Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+    for (const node of aggregateBlockFields(selectionSet)) {
       const name = node.name.value;
-      if (name === "__typename") continue;
-      if (node.alias) fail(`aliases are not supported inside aggregate blocks ('${node.alias.value}')`, "invalid-aggregate");
       if (name === "nodes") {
         if (!node.selectionSet) fail("'nodes' needs a selection set", "invalid-aggregate");
         result.nodes = this.lowerSelection(node.selectionSet, table);
@@ -2320,48 +2509,116 @@ var OperationLowerer = class {
       if (sawAggregate) fail("one aggregate block per field \u2014 alias the root instead", "invalid-aggregate");
       sawAggregate = true;
       if (!node.selectionSet) fail("'aggregate' needs a selection set", "invalid-aggregate");
-      for (const aggField of node.selectionSet.selections) {
-        if (aggField.kind !== Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
-        const aggName = aggField.name.value;
-        if (aggName === "__typename") continue;
-        if (aggField.alias) fail(`aliases are not supported inside aggregate blocks ('${aggField.alias.value}')`, "invalid-aggregate");
-        if (aggName === "count") {
-          assertKnownArgs(aggField, ["columns", "distinct"]);
-          const args = argsByName(aggField);
-          const count = {};
-          const columns = args.get("columns");
-          if (columns) count.columns = this.lowerDistinctOn(columns.value, table);
-          const distinct = args.get("distinct");
-          if (distinct) {
-            if (distinct.value.kind !== Kind.BOOLEAN) fail("count(distinct:) must be a boolean literal", "invalid-aggregate");
-            count.distinct = distinct.value.value;
-          }
-          result.count = count;
-          continue;
+      Object.assign(result, this.lowerAggregateFields(node.selectionSet, table));
+    }
+    if (!sawAggregate && !result.nodes) fail("aggregate selection needs an aggregate or nodes block", "invalid-aggregate");
+    return result;
+  }
+  /**
+   * The `{ key {…} aggregate {…} }` block of a grouped aggregate root. Same
+   * `aggregate` sub-block as the ungrouped shape (shared via
+   * `lowerAggregateFields`), but `key` replaces `nodes` — see the IR comment on
+   * `aggregateGroupsRootSchema` for why grouped roots have no `nodes`.
+   */
+  lowerGroupedAggregateSelection(selectionSet, table, groupBy) {
+    const groupColumns = new Set(groupBy.map((entry) => entry.column));
+    const result = { key: [] };
+    let sawAggregate = false;
+    let sawKey = false;
+    for (const node of aggregateBlockFields(selectionSet)) {
+      const name = node.name.value;
+      if (name === "key") {
+        if (sawKey) fail("one key block per grouped aggregate", "invalid-aggregate");
+        sawKey = true;
+        if (!node.selectionSet) fail("'key' needs a selection set", "invalid-aggregate");
+        result.key = this.lowerGroupKeySelection(node.selectionSet, table, groupColumns);
+        continue;
+      }
+      if (name === "nodes") {
+        fail("'nodes' is not available on a grouped aggregate \u2014 query the rows separately", "invalid-aggregate", ["key", "aggregate"]);
+      }
+      if (name !== "aggregate") fail(`unknown grouped-aggregate field '${name}'`, "invalid-aggregate", ["key", "aggregate"]);
+      if (sawAggregate) fail("one aggregate block per field \u2014 alias the root instead", "invalid-aggregate");
+      sawAggregate = true;
+      if (!node.selectionSet) fail("'aggregate' needs a selection set", "invalid-aggregate");
+      Object.assign(result, this.lowerAggregateFields(node.selectionSet, table));
+    }
+    const rendersAggregate = result.count !== void 0 || (result.sum?.length ?? 0) > 0 || (result.avg?.length ?? 0) > 0;
+    if (result.key.length === 0 && !rendersAggregate) {
+      fail(
+        "grouped aggregate needs at least one key column or an aggregate \u2014 a block selecting only __typename produces nothing",
+        "invalid-aggregate",
+        ["key", "aggregate"]
+      );
+    }
+    return result;
+  }
+  /**
+   * `key { month officer }` → the projected group columns. Every field must be
+   * one of the query's own group keys: any other column is indeterminate
+   * within a group, so selecting it is a document error rather than an
+   * arbitrary pick.
+   */
+  lowerGroupKeySelection(selectionSet, table, groupColumns) {
+    const key = [];
+    for (const node of selectionSet.selections) {
+      if (node.kind !== Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+      const name = node.name.value;
+      if (name === "__typename") continue;
+      if (!this.column(table, name)) {
+        fail(`unknown key column '${name}' on '${table}'`, "unknown-column", [...groupColumns]);
+      }
+      if (!groupColumns.has(name)) {
+        fail(
+          `key column '${name}' is not one of this query's groupBy keys \u2014 it has no single value within a group`,
+          "invalid-group-key",
+          [...groupColumns]
+        );
+      }
+      key.push({ alias: node.alias?.value ?? name, column: name });
+    }
+    return key;
+  }
+  /** The `count` / `sum {…}` / `avg {…}` fields inside an `aggregate { … }` block. */
+  lowerAggregateFields(selectionSet, table) {
+    const result = {};
+    for (const aggField of aggregateBlockFields(selectionSet)) {
+      const aggName = aggField.name.value;
+      if (aggName === "count") {
+        assertKnownArgs(aggField, ["columns", "distinct"]);
+        const args = argsByName(aggField);
+        const count = {};
+        const columns = args.get("columns");
+        if (columns) count.columns = this.lowerDistinctOn(columns.value, table);
+        const distinct = args.get("distinct");
+        if (distinct) {
+          if (distinct.value.kind !== Kind.BOOLEAN) fail("count(distinct:) must be a boolean literal", "invalid-aggregate");
+          count.distinct = distinct.value.value;
         }
-        if (aggName === "sum" || aggName === "avg") {
-          if (!aggField.selectionSet) fail(`'${aggName}' needs a column selection`, "invalid-aggregate");
-          const columns = [];
-          for (const columnField of aggField.selectionSet.selections) {
-            if (columnField.kind !== Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
-            if (columnField.name.value === "__typename") continue;
-            const column = this.column(table, columnField.name.value);
-            if (!column || typeof column.type !== "string" || !NUMERIC_TYPES.has(column.type)) {
-              fail(
-                `'${aggName}' supports numeric columns only, got '${columnField.name.value}' on '${table}'`,
-                "invalid-aggregate",
-                this.meta(table).columns.filter((c) => typeof c.type === "string" && NUMERIC_TYPES.has(c.type)).map((c) => c.name)
-              );
-            }
-            columns.push(columnField.name.value);
+        result.count = count;
+        continue;
+      }
+      if (aggName === "sum" || aggName === "avg") {
+        if (!aggField.selectionSet) fail(`'${aggName}' needs a column selection`, "invalid-aggregate");
+        const columns = [];
+        for (const columnField of aggField.selectionSet.selections) {
+          if (columnField.kind !== Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+          if (columnField.name.value === "__typename") continue;
+          const column = this.column(table, columnField.name.value);
+          if (!column || typeof column.type !== "string" || !NUMERIC_TYPES.has(column.type)) {
+            fail(
+              `'${aggName}' supports numeric columns only, got '${columnField.name.value}' on '${table}'`,
+              "invalid-aggregate",
+              this.meta(table).columns.filter((c) => typeof c.type === "string" && NUMERIC_TYPES.has(c.type)).map((c) => c.name)
+            );
           }
-          result[aggName] = columns;
-          continue;
+          columns.push(columnField.name.value);
         }
-        fail(`aggregate '${aggName}' is not supported in v2.0 (count/sum/avg only)`, "invalid-aggregate", ["count", "sum", "avg"]);
+        result[aggName] = columns;
+        continue;
       }
+      fail(`aggregate '${aggName}' is not supported in v2.0 (count/sum/avg only)`, "invalid-aggregate", ["count", "sum", "avg"]);
     }
-    if (!sawAggregate && !result.nodes) fail("aggregate selection needs an aggregate or nodes block", "invalid-aggregate");
     return result;
   }
   // -------------------------------------------------------------------------
@@ -2371,19 +2628,49 @@ var OperationLowerer = class {
     const roots = [];
     for (const node of operation.selectionSet.selections) {
       if (node.kind !== Kind.FIELD) fail("fragments are not supported at the operation root", "invalid-root");
+      if (node.selectionSet) visit(node.selectionSet, {
+        Directive(directive) {
+          if (directive.name.value === "assertAffectedRows") {
+            fail("@assertAffectedRows is supported on mutation roots only", "invalid-affected-row-assertion");
+          }
+        }
+      });
+      const assertion = this.parseAffectedRowAssertion(node, kind);
       const gate = this.parseRootDirectives(node);
       if (gate.omit) continue;
       const root = kind === "query" ? this.lowerQueryRoot(node) : this.lowerMutationRoot(node);
-      roots.push(gate.includeIf ? { ...root, includeIf: gate.includeIf } : root);
+      const guarded = root.kind === "mutation" && assertion !== void 0 ? { ...root, assertAffectedRows: assertion } : root;
+      roots.push(gate.includeIf ? { ...guarded, includeIf: gate.includeIf } : guarded);
     }
     if (roots.length === 0) fail("operation has no roots (all statically skipped?)", "invalid-root");
     return roots;
   }
+  parseAffectedRowAssertion(node, kind) {
+    const assertions = node.directives?.filter((directive) => directive.name.value === "assertAffectedRows") ?? [];
+    if (!assertions.length) return void 0;
+    if (kind !== "mutation" || assertions.length !== 1) {
+      fail("@assertAffectedRows is supported once per mutation root", "invalid-affected-row-assertion");
+    }
+    if (node.directives?.some((directive) => ["include", "skip"].includes(directive.name.value))) {
+      fail("an @assertAffectedRows root cannot use @include or @skip", "invalid-affected-row-assertion");
+    }
+    const args = assertions[0].arguments;
+    const arg = args?.[0];
+    if (args?.length !== 1 || arg?.name.value !== "exactly" || arg.value.kind !== Kind.INT) {
+      fail("@assertAffectedRows(exactly:) requires a document-authored nonnegative Int literal", "invalid-affected-row-assertion");
+    }
+    const count = Number(arg.value.value);
+    if (!Number.isInteger(count) || count < 0 || count > 2147483647) {
+      fail("@assertAffectedRows(exactly:) must be between 0 and 2147483647", "invalid-affected-row-assertion");
+    }
+    return count;
+  }
   parseRootDirectives(node) {
     let includeIf;
     let omit = false;
     for (const directive of node.directives ?? []) {
       const name = directive.name.value;
+      if (name === "assertAffectedRows") continue;
       if (name !== "include" && name !== "skip") {
         fail(`directive @${name} is not supported on fields`, "unknown-directive", ["include", "skip"]);
       }
@@ -2432,6 +2719,9 @@ var OperationLowerer = class {
       const pk = this.lowerPkArgs(node, table);
       return { kind: "byPk", alias, table, selection: this.lowerSelection(node.selectionSet, table), pk, where: CONST_TRUE };
     }
+    if (rootInfo.kind === "aggregateGroups") {
+      return this.lowerAggregateGroupsRoot(node, { alias, table });
+    }
     assertKnownArgs(node, ["where"]);
     if (!node.selectionSet) fail(`'${name}' needs a selection set`, "invalid-selection");
     const whereArg = args.get("where");
@@ -2444,6 +2734,108 @@ var OperationLowerer = class {
       ...aggregate
     };
   }
+  /** `<t>AggregateGroups(where:, groupBy:, limit:, offset:)` → an aggregateGroups root. */
+  lowerAggregateGroupsRoot(node, { alias, table }) {
+    assertKnownArgs(node, ["where", "groupBy", "limit", "offset"]);
+    if (!node.selectionSet) fail(`'${node.name.value}' needs a selection set`, "invalid-selection");
+    const args = argsByName(node);
+    const groupByArg = args.get("groupBy");
+    if (!groupByArg) fail(`'${node.name.value}' requires a 'groupBy' argument`, "missing-group-by");
+    const whereArg = args.get("where");
+    const groupBy = this.lowerGroupBy(groupByArg.value, table);
+    const aggregate = this.lowerGroupedAggregateSelection(node.selectionSet, table, groupBy);
+    const offset = this.lowerOffset(args.get("offset")?.value);
+    return {
+      kind: "aggregateGroups",
+      alias,
+      table,
+      where: whereArg ? this.lowerBoolExp(whereArg.value, table) : CONST_TRUE,
+      groupBy,
+      key: aggregate.key,
+      ...aggregate.count ? { count: aggregate.count } : {},
+      ...aggregate.sum ? { sum: aggregate.sum } : {},
+      ...aggregate.avg ? { avg: aggregate.avg } : {},
+      limit: this.lowerGroupLimit(args.get("limit")?.value),
+      ...offset ? { offset } : {}
+    };
+  }
+  /**
+   * `groupBy: [{ column: startedAt, bucket: MONTH }, …]` → GroupByKeyIr[].
+   *
+   * Document-authored only: a whole-argument variable is rejected rather than
+   * becoming a §4f slot. Group keys choose which expressions reach GROUP BY,
+   * and dynamic-input.ts refuses aggregation shapes from client input on the
+   * same reasoning — `where` stays dynamic, which is what runtime filtering
+   * actually needs.
+   */
+  lowerGroupBy(node, table) {
+    if (node.kind === Kind.VARIABLE) {
+      fail(
+        `groupBy on '${table}' must be written in the document \u2014 it cannot come from a variable`,
+        "dynamic-group-by"
+      );
+    }
+    const items = node.kind === Kind.LIST ? node.values : [node];
+    if (items.length === 0) fail(`groupBy on '${table}' needs at least one key`, "invalid-group-by");
+    const seen = /* @__PURE__ */ new Set();
+    return items.map((item) => {
+      if (item.kind !== Kind.OBJECT) {
+        fail(`groupBy entries on '${table}' must be objects like { column: foo }`, "invalid-group-by");
+      }
+      const fields = new Map(item.fields.map((field) => [field.name.value, field.value]));
+      for (const key of fields.keys()) {
+        if (key !== "column" && key !== "bucket") {
+          fail(`unknown groupBy field '${key}' on '${table}'`, "invalid-group-by", ["column", "bucket"]);
+        }
+      }
+      const columnNode = fields.get("column");
+      if (!columnNode) fail(`groupBy entries on '${table}' need a 'column'`, "invalid-group-by");
+      if (columnNode.kind !== Kind.ENUM) {
+        fail(`groupBy column on '${table}' must be a group-by column enum value`, "invalid-group-by");
+      }
+      const column = this.column(table, columnNode.value);
+      if (!column) {
+        fail(`unknown groupBy column '${columnNode.value}' on '${table}'`, "unknown-column", this.meta(table).columns.map((c) => c.name));
+      }
+      if (column.type === "jsonb") {
+        fail(`groupBy column '${table}.${columnNode.value}' is jsonb and cannot be a group key`, "invalid-group-by");
+      }
+      const bucketNode = fields.get("bucket");
+      let bucket;
+      if (bucketNode) {
+        if (bucketNode.kind !== Kind.ENUM) {
+          fail(`groupBy bucket on '${table}.${columnNode.value}' must be a DateBucket enum value`, "invalid-group-by", Object.keys(DATE_BUCKET_BY_ENUM));
+        }
+        bucket = DATE_BUCKET_BY_ENUM[bucketNode.value];
+        if (!bucket) {
+          fail(`unknown DateBucket '${bucketNode.value}'`, "invalid-group-by", Object.keys(DATE_BUCKET_BY_ENUM));
+        }
+        if (typeof column.type !== "string" || !BUCKETABLE_TYPES.has(column.type)) {
+          fail(
+            `groupBy bucket is only valid on date/timestamptz columns \u2014 '${table}.${columnNode.value}' is ${typeof column.type === "string" ? column.type : "an enum"}`,
+            "invalid-group-by"
+          );
+        }
+      }
+      if (seen.has(columnNode.value)) {
+        fail(`duplicate groupBy column '${columnNode.value}' on '${table}'`, "invalid-group-by");
+      }
+      seen.add(columnNode.value);
+      return bucket ? { column: columnNode.value, bucket } : { column: columnNode.value };
+    });
+  }
+  /** Like lowerLimit, but bounded by MAX_GROUPS and defaulting to it. */
+  lowerGroupLimit(node) {
+    const base = { default: MAX_GROUPS, max: MAX_GROUPS };
+    if (!node) return base;
+    if (node.kind === Kind.VARIABLE) return { ...base, variable: node.name.value };
+    if (node.kind === Kind.INT) {
+      const value = Number(node.value);
+      if (value < 1) fail("limit must be a positive integer", "invalid-limit");
+      return { ...base, value: Math.min(value, MAX_GROUPS) };
+    }
+    fail("limit must be an integer literal or a variable", "invalid-limit");
+  }
   /** byPk-style pk arguments: one argument per primary-key column, exactly. */
   lowerPkArgs(node, table) {
     const meta = this.meta(table);
@@ -2953,7 +3345,7 @@ function compileNamespace({ canonical, sdl, documents }) {
         const loweredRoots = lowerOperation({ restricted: { ...restricted, definition: flattened }, ctx });
         const { roots, tableSet } = injectPolicies({ roots: loweredRoots, ctx });
         operations[restricted.name] = {
-          irVersion: IR_VERSION,
+          irVersion: roots.some((root) => root.kind === "mutation" && root.assertAffectedRows !== void 0) ? IR_VERSION : LEGACY_IR_VERSION,
           name: restricted.name,
           opHash: computeOpHash({ definition: flattened, schemaHash }),
           kind: restricted.kind,
@@ -2980,7 +3372,7 @@ function compileNamespace({ canonical, sdl, documents }) {
   }
   if (diagnostics.some((d) => d.severity === "error")) return { ok: false, diagnostics };
   const artifact = {
-    irVersion: IR_VERSION,
+    irVersion: requiredArtifactIrVersion(Object.values(operations)),
     namespace: ctx.namespace,
     schemaHash,
     opsHash: computeOpsHash(Object.values(operations).map((op) => op.opHash)),