@sequenceholdings/orm 2.0.0 → 2.1.1

package/dist/cli.js

@@ -6,8 +6,8 @@ import { createJiti } from 'jiti';
 import { createHash } from 'crypto';
 import { z } from 'zod';
 import { sql } from 'drizzle-orm';
-import { pgSchema, PgDialect, QueryBuilder, getViewConfig, extractUsedTable, primaryKey, uniqueIndex, index, foreignKey, jsonb, date, timestamp, boolean, doublePrecision, numeric, bigint, integer, text, uuid } from 'drizzle-orm/pg-core';
-import { buildSchema, parse, validate, Kind, valueFromASTUntyped, print } from 'graphql';
+import { pgSchema, PgDialect, QueryBuilder, getViewConfig, extractUsedTable, check, foreignKey, uniqueIndex, index, primaryKey, jsonb, date, timestamp, boolean, doublePrecision, numeric, bigint, integer, text, uuid } from 'drizzle-orm/pg-core';
+import { buildSchema, parse, validate, Kind, valueFromASTUntyped, visit, print } from 'graphql';
 import { generateDrizzleJson, upPgSnapshot, generateMigration } from 'drizzle-kit/api';
 import { load } from 'js-yaml';
 import { capabilityPinsSchema, customRolesBlockSchema, validateCapabilityPins } from '@sequenceholdings/custom-roles-manifest';
@@ -36,9 +36,519 @@ var PredicateParseError = class extends Error {
   }
   name = "PredicateParseError";
 };
+
+// src/compiler/sql.ts
+var CLAIMS_SETTING = "request.jwt.claims";
+var CAPABILITIES_CLAIM_KEY = "capabilities";
+var quoteIdentifier = (name) => `"${name.replaceAll('"', '""')}"`;
+var quoteLiteral = (value) => `'${value.replaceAll("'", "''")}'`;
+var CLAIMS_SOURCE = `nullif(current_setting('${CLAIMS_SETTING}', true), '')::jsonb`;
+var claimExpression = (key) => `(${CLAIMS_SOURCE} ->> ${quoteLiteral(key)})`;
+var capabilityExpression = (key) => `coalesce(${CLAIMS_SOURCE} -> '${CAPABILITIES_CLAIM_KEY}' ? ${quoteLiteral(key)}, false)`;
+
+// src/checks/compile.ts
+function tokenize(source) {
+  const tokens = [];
+  for (let position = 0; position < source.length; ) {
+    const char = source[position];
+    if (/\s/.test(char)) {
+      position++;
+      continue;
+    }
+    if (char === "(" || char === ")" || char === ",") {
+      tokens.push({ kind: char === "(" ? "lparen" : char === ")" ? "rparen" : "comma", value: char, position });
+      position++;
+      continue;
+    }
+    if (char === "'") {
+      const start = position++;
+      let value = "";
+      let closed = false;
+      while (position < source.length) {
+        if (source[position] !== "'") {
+          value += source[position++];
+          continue;
+        }
+        if (source[position + 1] === "'") {
+          value += "'";
+          position += 2;
+          continue;
+        }
+        position++;
+        closed = true;
+        break;
+      }
+      if (!closed) throw new Error(`unterminated string at position ${start}`);
+      if (/[\x00-\x1f\x7f]/.test(value)) throw new Error(`control character in string at position ${start}`);
+      tokens.push({ kind: "string", value, position: start });
+      continue;
+    }
+    const operator = /^(<=|>=|<>|!=|!~|=|<|>|~)/.exec(source.slice(position));
+    if (operator) {
+      tokens.push({ kind: "operator", value: operator[0] === "<>" ? "!=" : operator[0], position });
+      position += operator[0].length;
+      continue;
+    }
+    const number = /^-?\d+(?:\.\d+)?/.exec(source.slice(position));
+    if (number) {
+      tokens.push({ kind: "number", value: number[0], position });
+      position += number[0].length;
+      continue;
+    }
+    const identifier3 = /^[a-zA-Z_][a-zA-Z_0-9]*/.exec(source.slice(position));
+    if (identifier3) {
+      tokens.push({ kind: "identifier", value: identifier3[0], position });
+      position += identifier3[0].length;
+      continue;
+    }
+    throw new Error(`unexpected character '${char}' at position ${position}`);
+  }
+  tokens.push({ kind: "end", value: "", position: source.length });
+  if (tokens.length > 256) throw new Error("check expression exceeds 256 tokens");
+  return tokens;
+}
+var Parser = class {
+  constructor(tokens, columns) {
+    this.tokens = tokens;
+    this.columns = /* @__PURE__ */ new Map();
+    for (const column of columns) {
+      for (const alias of [column.name, column.columnName]) {
+        const previous = this.columns.get(alias);
+        if (previous && previous.columnName !== column.columnName) {
+          throw new Error(`ambiguous check column '${alias}'`);
+        }
+        this.columns.set(alias, column);
+      }
+    }
+  }
+  index = 0;
+  depth = 0;
+  columns;
+  parse() {
+    const expression = this.parseOr();
+    this.expect("end", "end of expression");
+    return expression;
+  }
+  parseOr() {
+    let left = this.parseAnd();
+    while (this.matchKeyword("or")) left = `(${left} OR ${this.parseAnd()})`;
+    return left;
+  }
+  parseAnd() {
+    let left = this.parseNot();
+    while (this.matchKeyword("and")) left = `(${left} AND ${this.parseNot()})`;
+    return left;
+  }
+  parseNot() {
+    if (this.matchKeyword("not")) return `(NOT ${this.parseNot()})`;
+    return this.parsePrimary();
+  }
+  parsePrimary() {
+    if (this.peek().kind === "lparen") {
+      if (++this.depth > 32) throw new Error("check expression nesting exceeds 32 levels");
+      this.advance();
+      const expression = this.parseOr();
+      this.expect("rparen", "')'");
+      this.depth--;
+      return `(${expression})`;
+    }
+    return this.parseComparison();
+  }
+  parseComparison() {
+    const left = this.parseValue();
+    if (this.matchKeyword("is")) {
+      const negate = this.matchKeyword("not");
+      this.expectKeyword("null");
+      return `${left.sql} IS ${negate ? "NOT " : ""}NULL`;
+    }
+    if (this.matchKeyword("between")) {
+      const lower = this.parseValue();
+      this.expectKeyword("and");
+      const upper = this.parseValue();
+      return `${left.sql} BETWEEN ${lower.sql} AND ${upper.sql}`;
+    }
+    if (this.matchKeyword("in")) {
+      this.expect("lparen", "'(' after IN");
+      const values = [this.parseValue()];
+      while (this.peek().kind === "comma") {
+        this.advance();
+        values.push(this.parseValue());
+      }
+      this.expect("rparen", "')' after IN values");
+      if (values.some((value) => !value.literal)) throw new Error("IN values must be literals");
+      return `${left.sql} IN (${values.map((value) => value.sql).join(", ")})`;
+    }
+    const operator = this.expect("operator", "a comparison operator");
+    const right = this.parseValue();
+    if (operator.value === "~" || operator.value === "!~") {
+      if (left.column && left.column.type !== "text") throw new Error("regex checks require a text column");
+      if (!right.literal) throw new Error("regex pattern must be a literal");
+    }
+    return `${left.sql} ${operator.value} ${right.sql}`;
+  }
+  parseValue() {
+    const token = this.advance();
+    if (token.kind === "string") return { sql: quoteLiteral(token.value), literal: true };
+    if (token.kind === "number") {
+      const number = Number(token.value);
+      if (!Number.isFinite(number) || Number.isInteger(number) && !Number.isSafeInteger(number)) {
+        throw new Error(`unsafe numeric literal at position ${token.position}`);
+      }
+      return { sql: token.value, literal: true };
+    }
+    if (token.kind !== "identifier") throw new Error(`expected a column or literal at position ${token.position}`);
+    const keyword = token.value.toLowerCase();
+    if (keyword === "true" || keyword === "false" || keyword === "null") return { sql: keyword.toUpperCase(), literal: true };
+    if (keyword === "btrim") {
+      this.expect("lparen", "'(' after btrim");
+      const column2 = this.parseColumn();
+      this.expect("rparen", "')' after btrim column");
+      if (column2.type !== "text") throw new Error("btrim requires a text column");
+      return { sql: `btrim(${quoteIdentifier(column2.columnName)})`, column: column2 };
+    }
+    const column = this.columns.get(token.value);
+    if (!column) throw new Error(`unknown check column '${token.value}'`);
+    return { sql: quoteIdentifier(column.columnName), column };
+  }
+  parseColumn() {
+    const token = this.expect("identifier", "a column name");
+    const column = this.columns.get(token.value);
+    if (!column) throw new Error(`unknown check column '${token.value}'`);
+    return column;
+  }
+  peek() {
+    return this.tokens[this.index];
+  }
+  advance() {
+    const token = this.peek();
+    if (token.kind !== "end") this.index++;
+    return token;
+  }
+  matchKeyword(keyword) {
+    if (this.peek().kind !== "identifier" || this.peek().value.toLowerCase() !== keyword) return false;
+    this.advance();
+    return true;
+  }
+  expectKeyword(keyword) {
+    if (!this.matchKeyword(keyword)) throw new Error(`expected '${keyword}' at position ${this.peek().position}`);
+  }
+  expect(kind, description) {
+    const token = this.peek();
+    if (token.kind !== kind) throw new Error(`expected ${description} at position ${token.position}`);
+    return this.advance();
+  }
+};
+function compileCheckExpression(source, columns) {
+  return new Parser(tokenize(source), columns).parse();
+}
+
+// src/constants.ts
+var NAMESPACE_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
+var IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;
+var COLUMN_IDENTIFIER_PATTERN = /^_?[a-z][a-z0-9_]*$/;
+var MAX_IDENTIFIER_LENGTH = 63;
+var CAPABILITY_KEY_PATTERN = /^(?:org\/|app\/[a-z][a-z0-9-]{0,63}\/)?[a-z0-9-]{1,64}$/;
+var CLAIM_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+var QUALIFIED_TABLE_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
+var SYNCED_SOURCE_PATTERN = /^gold\.[a-z][a-z0-9_]*$/;
+var ORM_SCHEMA_PREFIX = "orm_";
+var CONSUMER_ROLE_SUFFIX = "_consumer";
+var ormSchemaName = (namespace) => `${ORM_SCHEMA_PREFIX}${namespace}`;
+var consumerRoleName = (namespace) => `${ORM_SCHEMA_PREFIX}${namespace}${CONSUMER_ROLE_SUFFIX}`;
+var DEFINITION_FILE_EXTENSIONS = [".yml", ".yaml"];
+var NAMESPACE_CONFIG_FILENAMES = /* @__PURE__ */ new Set(["namespace.yaml", "namespace.yml"]);
+var HASH_DOMAIN = "sequence-orm-definitions\0";
+var MAX_DEFINITION_FILE_BYTES = 1024 * 1024;
+var MAX_GENERATED_SDL_BYTES = 16 * 1024 * 1024;
+var ORM_REGISTRATION_MAX_BYTES = 64 * 1024 * 1024;
+var RESERVED_TABLE_NAMES = /* @__PURE__ */ new Set(["actions", "query"]);
+var RESERVED_COLUMN_NAMES = /* @__PURE__ */ new Set(["select", "order", "limit", "offset"]);
+var CELL_PARTS = ["at", "by", "rev", "source", "conflicts"];
+var CELL_PART_SUFFIX = {
+  at: "__at",
+  by: "__by",
+  rev: "__rev",
+  source: "__src",
+  conflicts: "__lost"
+};
+var MAX_TRACKED_COLUMN_NAME = MAX_IDENTIFIER_LENGTH - 6;
+var CELLS_FIELD = "cells";
+function cellColumnName(column, part) {
+  return `${column}${CELL_PART_SUFFIX[part]}`;
+}
+var MATERIALIZE_ACTOR = "orm:materialize";
+var MATERIALIZE_CLAIMS_JSON = JSON.stringify({ sub: MATERIALIZE_ACTOR, org: null, roles: [], capabilities: [] });
+function materializedRefreshFunctionName(table) {
+  return `${table}__refresh`;
+}
+function materializeLockKey(schema, table) {
+  return `orm:materialize:${schema}.${table}`;
+}
+var policyVariantSchema = z.object({
+  /** Claims-only guard (capability()/role()/claim() comparisons — no columns). */
+  when: z.string().min(1).max(1e3),
+  /** Exactly one of: allow-all bypass, or a row predicate. */
+  allow: z.literal(true).optional(),
+  policy: z.string().min(1).max(2e3).optional()
+}).refine((v) => v.allow === true !== (typeof v.policy === "string"), {
+  message: "A variant declares exactly one of allow: true or policy"
+});
+var policyExpressionSchema = z.union([
+  z.string().min(1).max(2e3),
+  z.object({
+    default: z.string().min(1).max(2e3),
+    variants: z.array(policyVariantSchema).max(10).default([])
+  })
+]);
+function parseDurationMs(input) {
+  if (typeof input === "number") return Number.isInteger(input) && input > 0 ? input : void 0;
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(input);
+  if (!match) return void 0;
+  const factor = match[2] === "ms" ? 1 : match[2] === "s" ? 1e3 : 6e4;
+  const value = Math.round(Number(match[1]) * factor);
+  return value > 0 ? value : void 0;
+}
+var identifier = z.string().min(1).max(63).regex(/^[a-z][a-z0-9_]*$/);
+var durationMs = z.number().int().positive().max(24 * 60 * 60 * 1e3);
+var RESOLVED_VIEW_SYSTEM_COLUMNS = {
+  writebackStatus: { name: "writebackStatus", columnName: "_writeback_status", type: "text" },
+  writebackError: { name: "writebackError", columnName: "_writeback_error", type: "text" }
+};
+var RESOLVED_SOURCE_SYSTEM_COLUMNS = {
+  tombstoned: { name: "sysTombstoned", columnName: "_tombstoned" },
+  fetchedAt: { name: "sysFetchedAt", columnName: "_fetched_at" },
+  writebackStatus: { name: "sysWritebackStatus", columnName: "_writeback_status" },
+  writebackError: { name: "sysWritebackError", columnName: "_writeback_error" },
+  writebackAt: { name: "sysWritebackAt", columnName: "_writeback_at" }
+};
+var RESOLVED_VIEW_CELL_PARTS = ["source", "at", "by", "conflicts"];
+/* @__PURE__ */ new Set([
+  ...Object.values(RESOLVED_VIEW_SYSTEM_COLUMNS).flatMap((c) => [c.name, c.columnName]),
+  ...Object.values(RESOLVED_SOURCE_SYSTEM_COLUMNS).flatMap((c) => [c.name, c.columnName])
+]);
+var COMPARATORS = ["latest", "highest", "lowest", "priority", "nonNullFirst", "custom"];
+var canonicalFunctionRefSchema = z.object({
+  /** `managed` = a Managed Function id/slug; `native` = an in-process Atlas function (reserved). */
+  kind: z.enum(["managed", "native"]),
+  id: z.string().min(1).max(200)
+}).strict();
+var canonicalFetchShapeSchema = z.union([
+  z.object({ shape: z.literal("single") }).strict(),
+  z.object({ shape: z.literal("batch"), maxKeys: z.number().int().min(2).max(500) }).strict()
+]);
+var canonicalResolvedSourceSchema = z.object({
+  name: identifier,
+  kind: z.enum(["manual", "etl", "prefetch"]),
+  /** Backing relation in this namespace: an internal table (manual/prefetch) or a synced table (etl). */
+  table: identifier,
+  /** Resolved columns (logical names) this source supplies — the primary key is implicit. */
+  columns: z.array(z.string().min(1).max(63)).min(1).max(500),
+  /** etl: logical timestamptz/date column on the synced table used as every cell's updated_at. */
+  updatedAt: z.string().min(1).max(63).optional(),
+  /** prefetch: resolved column holding the source system's key (may be the primary key). */
+  key: z.string().min(1).max(63).optional(),
+  fetch: canonicalFetchShapeSchema.optional(),
+  function: canonicalFunctionRefSchema.optional(),
+  prefetchDefaults: z.object({
+    maxStalenessMs: durationMs,
+    timeoutMs: durationMs,
+    onError: z.enum(["fallback", "fail"])
+  }).strict().optional(),
+  writeback: z.object({
+    columns: z.array(z.string().min(1).max(63)).min(1).max(500),
+    defaultMode: z.enum(["sync", "async"]),
+    timeoutMs: durationMs,
+    /** Remove confirmed cells from the manual source so a stale edit cannot shadow the source. */
+    clearManualOnConfirm: z.boolean()
+  }).strict().optional()
+}).strict();
+var canonicalResolveRuleSchema = z.object({
+  column: z.string().min(1).max(63),
+  comparator: z.enum(COMPARATORS),
+  /** Source names, in tie-break order. */
+  candidates: z.array(identifier).min(1).max(16),
+  /** custom only: SQL ORDER BY key over value / updated_at / source / actor / ord. */
+  orderBy: z.string().min(1).max(2e3).optional()
+}).strict();
+var canonicalResolvedSchema = z.object({
+  sources: z.array(canonicalResolvedSourceSchema).min(1).max(16),
+  /** One rule per resolved (non-pk) column; documents the generated view for tooling. */
+  resolve: z.array(canonicalResolveRuleSchema).max(500),
+  /** Sources whose tombstone hides the resolved row (v1: the manual source only). */
+  deletedBy: z.array(identifier).max(1).default([]),
+  /**
+   * Materialized: the view reads an indexed internal table (`table`) that the
+   * data plane keeps in step with `compute`, the internal view holding the
+   * resolution query. Omitted when the view computes on read.
+   */
+  materialized: z.object({ table: identifier, compute: identifier }).strict().optional(),
+  /** Write policies evaluated against the RESOLVED row (reads use the view's read policy). */
+  policies: z.object({
+    write: policyExpressionSchema.optional(),
+    insert: policyExpressionSchema.optional(),
+    update: policyExpressionSchema.optional()
+  }).strict().default({})
+}).strict();
+function validateResolvedView({ view, tables, views = [] }) {
+  const resolved = view.resolved;
+  if (!resolved) return [];
+  const errors = [];
+  const fail3 = (message) => errors.push(`resolved table '${view.view}': ${message}`);
+  const pkColumn = view.primaryKey?.length === 1 ? view.columns.find((c) => c.columnName === view.primaryKey?.[0]) : void 0;
+  if (!pkColumn) {
+    fail3("requires exactly one primary-key column");
+    return errors;
+  }
+  const systemNames = new Set(Object.values(RESOLVED_VIEW_SYSTEM_COLUMNS).map((c) => c.name));
+  const scope = {
+    view,
+    resolved,
+    pkColumn,
+    dataColumns: new Map(view.columns.filter((c) => !systemNames.has(c.name) && c.cell === void 0).map((c) => [c.name, c])),
+    sourceByName: /* @__PURE__ */ new Map(),
+    fail: fail3
+  };
+  if (resolved.sources.filter((source) => source.kind === "manual").length !== 1) fail3("requires exactly one manual source");
+  const tableByName = new Map(tables.map((table) => [table.table, table]));
+  for (const source of resolved.sources) {
+    if (scope.sourceByName.has(source.name)) fail3(`duplicate source '${source.name}'`);
+    scope.sourceByName.set(source.name, source);
+    const table = tableByName.get(source.table);
+    if (!table) fail3(`source '${source.name}' references unknown table '${source.table}'`);
+    else validateSource({ scope, source, table });
+  }
+  validateRules(scope);
+  validateViewCells(scope);
+  if (resolved.materialized) validateMaterialized({ scope, tableByName, views });
+  for (const name of resolved.deletedBy) {
+    if (scope.sourceByName.get(name)?.kind !== "manual") fail3(`deletedBy '${name}' must be the manual source`);
+  }
+  return errors;
+}
+function validateSource({ scope, source, table }) {
+  const { fail: fail3 } = scope;
+  if (source.kind === "etl" && table.source === void 0) fail3(`etl source '${source.name}' must reference a synced table`);
+  if (source.kind !== "etl" && (table.internal !== true || table.cellMetadata !== true)) {
+    fail3(`${source.kind} source '${source.name}' must reference an internal table with cell metadata`);
+  }
+  const hasRev = table.columns.some((column) => column.cell?.part === "rev");
+  if (source.kind === "manual" && !hasRev) fail3(`manual source '${source.name}' must carry '__rev' cell columns`);
+  if (source.kind === "prefetch" && hasRev) fail3(`prefetch source '${source.name}' must not carry '__rev' cell columns`);
+  const byName = new Map(table.columns.map((c) => [c.name, c]));
+  validateSourceColumns({ scope, source, byName });
+  if (source.kind === "etl") {
+    const updatedAt = source.updatedAt === void 0 ? void 0 : byName.get(source.updatedAt);
+    if (source.updatedAt !== void 0 && updatedAt?.type !== "timestamptz" && updatedAt?.type !== "date") {
+      fail3(`etl source '${source.name}' updatedAt must name a timestamptz/date column on '${source.table}'`);
+    }
+  }
+  validatePrefetchFields({ scope, source });
+}
+function validatePrefetchFields({ scope, source }) {
+  const { fail: fail3, pkColumn } = scope;
+  if (source.kind !== "prefetch") {
+    if (source.key || source.fetch || source.function || source.prefetchDefaults || source.writeback) {
+      fail3(`only prefetch sources may declare key/fetch/function/prefetchDefaults/writeback ('${source.name}')`);
+    }
+    return;
+  }
+  if (!source.key || !source.fetch || !source.function || !source.prefetchDefaults) {
+    fail3(`prefetch source '${source.name}' requires key, fetch, function and prefetchDefaults`);
+  } else if (source.key !== pkColumn.name && !source.columns.includes(source.key)) {
+    fail3(`prefetch source '${source.name}' key '${source.key}' must be the primary key or one of its columns`);
+  }
+  for (const column of source.writeback?.columns ?? []) {
+    if (!source.columns.includes(column)) fail3(`prefetch source '${source.name}' writes back '${column}', which it does not supply`);
+  }
+}
+function validateSourceColumns({ scope, source, byName }) {
+  const { fail: fail3, pkColumn, dataColumns } = scope;
+  for (const column of [pkColumn.name, ...source.columns]) {
+    const own = column === pkColumn.name ? pkColumn : dataColumns.get(column);
+    const theirs = byName.get(column);
+    if (!own) fail3(`source '${source.name}' supplies unknown column '${column}'`);
+    else if (!theirs) fail3(`source '${source.name}' table '${source.table}' has no column '${column}'`);
+    else if (JSON.stringify(theirs.type) !== JSON.stringify(own.type)) fail3(`column '${column}' has a different type on source '${source.name}'`);
+  }
+}
+function validateRules({ resolved, pkColumn, dataColumns, sourceByName, fail: fail3 }) {
+  const ruled = /* @__PURE__ */ new Set();
+  for (const rule of resolved.resolve) {
+    if (!dataColumns.has(rule.column) || rule.column === pkColumn.name) {
+      fail3(`resolve rule targets unknown column '${rule.column}'`);
+      continue;
+    }
+    if (ruled.has(rule.column)) fail3(`column '${rule.column}' has more than one resolve rule`);
+    ruled.add(rule.column);
+    if (rule.comparator === "custom" !== (rule.orderBy !== void 0)) {
+      fail3(`column '${rule.column}': orderBy is required for custom comparators and only allowed there`);
+    }
+    if (new Set(rule.candidates).size !== rule.candidates.length) fail3(`column '${rule.column}' repeats a candidate`);
+    for (const candidate of rule.candidates) {
+      const source = sourceByName.get(candidate);
+      if (!source) fail3(`column '${rule.column}' names unknown candidate source '${candidate}'`);
+      else if (!source.columns.includes(rule.column)) fail3(`column '${rule.column}' candidate '${candidate}' does not supply it`);
+    }
+  }
+  for (const column of dataColumns.keys()) {
+    if (column !== pkColumn.name && !ruled.has(column)) fail3(`column '${column}' has no resolve rule`);
+  }
+}
+var VIEW_CELL_TYPES = {
+  source: "text",
+  at: "timestamptz",
+  by: "text",
+  conflicts: "jsonb"
+};
+function validateViewCells({ view, dataColumns, pkColumn, fail: fail3 }) {
+  const expected = /* @__PURE__ */ new Map();
+  for (const column of dataColumns.values()) {
+    if (column.name === pkColumn.name) continue;
+    for (const part of RESOLVED_VIEW_CELL_PARTS) {
+      expected.set(cellColumnName(column.name, part), { part, columnName: cellColumnName(column.columnName, part) });
+    }
+  }
+  for (const column of view.columns) {
+    if (!column.cell) continue;
+    const want = expected.get(column.name);
+    if (!want || want.part !== column.cell.part || want.columnName !== column.columnName || cellColumnName(column.cell.of, column.cell.part) !== column.name) {
+      fail3(`unexpected cell column '${column.name}'`);
+      continue;
+    }
+    if (column.type !== VIEW_CELL_TYPES[column.cell.part]) fail3(`cell column '${column.name}' must be ${VIEW_CELL_TYPES[column.cell.part]}`);
+    expected.delete(column.name);
+  }
+  for (const name of expected.keys()) fail3(`missing cell column '${name}'`);
+}
+var columnSignature = (columns) => JSON.stringify(columns.map((column) => [column.name, column.columnName, column.type]));
+function validateMaterialized({ scope, tableByName, views }) {
+  const { view, resolved, fail: fail3 } = scope;
+  const { table: tableName, compute: computeName } = resolved.materialized;
+  const table = tableByName.get(tableName);
+  if (!table || table.internal !== true || table.materializes !== view.view) {
+    fail3(`materialized table '${tableName}' must be an internal table that materializes '${view.view}'`);
+  } else {
+    if (columnSignature(table.columns) !== columnSignature(view.columns)) fail3(`materialized table '${tableName}' must have exactly the view's columns`);
+    if (JSON.stringify(table.primaryKey ?? []) !== JSON.stringify(view.primaryKey ?? [])) fail3(`materialized table '${tableName}' must share the view's primary key`);
+  }
+  const compute = views.find((candidate) => candidate.view === computeName);
+  if (!compute || compute.internal !== true) fail3(`compute view '${computeName}' must be an internal view`);
+  else if (columnSignature(compute.columns) !== columnSignature(view.columns)) fail3(`compute view '${computeName}' must have exactly the view's columns`);
+  for (const source of resolved.sources) {
+    if (source.kind !== "etl") continue;
+    const read = tableByName.get(source.table)?.policies?.read;
+    const unconditional = typeof read === "string" ? read.trim() === "true" : read !== void 0 && read.default.trim() === "true" && read.variants.length === 0;
+    if (!unconditional) {
+      fail3(`etl source '${source.name}' must have read policy 'true' to be materialized (the copy is shared by every caller)`);
+    }
+  }
+}
+
+// src/canonical/v2.ts
 var CANONICAL_FORMAT = 2;
 var IDENTIFIER_RE = /^[a-z][a-z0-9_]*$/;
-var identifier = z.string().min(1).max(63).regex(IDENTIFIER_RE);
+var identifier2 = 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",
@@ -53,59 +563,71 @@ var COLUMN_TYPES = [
 ];
 var columnTypeSchema = z.enum(COLUMN_TYPES);
 var canonicalEnumSchema = z.object({
-  name: identifier,
+  name: identifier2,
   values: z.array(z.string().min(1).max(63)).min(1).max(100)
 });
 var canonicalColumnSchema = z.object({
   /** Property name in TS (camelCase); columnName is the Postgres name. */
   name: z.string().min(1).max(63),
-  columnName: identifier,
-  type: z.union([columnTypeSchema, z.object({ enum: identifier })]),
+  columnName: columnIdentifier,
+  type: z.union([columnTypeSchema, z.object({ enum: identifier2 })]),
   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)
+  deprecated: z.boolean().default(false),
+  /**
+   * Marks a system cell-metadata column (see CELL_PARTS in constants): part
+   * `part` of the cell of logical column `of`. Synthesized by authoring,
+   * never client-writable, absent from GraphQL scalar fields. Omitted on
+   * ordinary columns so their hashes are unchanged.
+   */
+  cell: z.object({ of: z.string().min(1).max(63), part: z.enum(CELL_PARTS) }).strict().optional()
+}).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),
   kind: z.enum(["toOne", "toMany", "toPlatformUser"]),
   /** Target table name (namespace-local). Absent for toPlatformUser. */
-  target: identifier.optional(),
+  target: identifier2.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),
+  onDelete: z.enum(["cascade", "restrict", "no action", "set null", "set default"]).optional(),
+  onUpdate: z.enum(["cascade", "restrict", "no action", "set null", "set default"]).optional(),
   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()
+  name: identifier2.optional()
 });
-var policyVariantSchema = z.object({
-  /** Claims-only guard (capability()/role()/claim() comparisons — no columns). */
-  when: z.string().min(1).max(1e3),
-  /** Exactly one of: allow-all bypass, or a row predicate. */
-  allow: z.literal(true).optional(),
-  policy: z.string().min(1).max(2e3).optional()
-}).refine((v) => v.allow === true !== (typeof v.policy === "string"), {
-  message: "A variant declares exactly one of allow: true or policy"
-});
-var policyExpressionSchema = z.union([
-  z.string().min(1).max(2e3),
-  z.object({
-    default: z.string().min(1).max(2e3),
-    variants: z.array(policyVariantSchema).max(10).default([])
-  })
-]);
+var canonicalCheckSchema = z.object({
+  name: identifier2,
+  expression: z.string().min(1).max(2e3)
+}).strict();
 var canonicalPoliciesSchema = z.object({
   read: policyExpressionSchema.optional(),
   write: policyExpressionSchema.optional(),
@@ -293,7 +815,7 @@ var VIEW_QUERY_FUNCTION_ALLOWLIST = [
   "width_bucket"
 ];
 var canonicalActionSchema = z.object({
-  name: identifier,
+  name: identifier2,
   requires: z.string().max(1e3).optional(),
   params: z.record(z.string(), z.object({
     type: columnTypeSchema,
@@ -305,9 +827,9 @@ var canonicalActionSchema = z.object({
 });
 var canonicalCowMutationSchema = z.object({
   kind: z.enum(["override", "revert"]),
-  name: identifier,
+  name: identifier2,
   /** Synced table (same namespace) the overlay copies from / falls back to. */
-  synced: identifier,
+  synced: identifier2,
   /** Single-column primary key PROPERTY (TS camelCase, like column `name`) shared by overlay and synced. */
   pk: z.string().min(1).max(63),
   /** Override: contract properties copied INSERT…SELECT from synced (pk included). Empty for revert. */
@@ -334,17 +856,28 @@ var canonicalCowMutationSchema = z.object({
     }
   }
 });
+var canonicalForeignKeySchema = z.object({
+  name: identifier2,
+  columns: z.array(columnIdentifier).min(1).max(8),
+  target: identifier2,
+  references: z.array(columnIdentifier).min(1).max(8),
+  deferrable: z.enum(["initially-immediate", "initially-deferred"]).optional(),
+  onDelete: z.enum(["cascade", "restrict", "no action", "set null", "set default"]).optional(),
+  onUpdate: z.enum(["cascade", "restrict", "no action", "set null", "set default"]).optional()
+}).strict();
 var canonicalTableSchema = z.object({
-  table: identifier,
+  table: identifier2,
   description: z.string().max(2e3).optional(),
   /** Table-level rename hint (new in v2). */
-  renamedFrom: identifier.optional(),
+  renamedFrom: identifier2.optional(),
   /** 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([]),
+  /** Omitted by old definitions, preserving their existing content hashes. */
+  checks: z.array(canonicalCheckSchema).max(100).optional(),
   policies: canonicalPoliciesSchema.default({}),
   /**
    * v1-conversion carry-over only. v2 has no action surface — the runtime
@@ -353,26 +886,64 @@ 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(),
+  /**
+   * Per-cell edit metadata (`cellMetadata: true` in authoring): every tracked
+   * column `c` carries typed `c__at` / `c__by` system columns (plus `c__rev`
+   * on a resolved table's internal sources), listed explicitly in `columns`
+   * with a `cell` marker so DDL and migrations treat them as ordinary columns.
+   * Omitted when off so existing definitions hash unchanged.
+   */
+  cellMetadata: z.literal(true).optional(),
+  /**
+   * System-owned backing table of a resolved table (its manual or prefetch
+   * source). Internal tables get DDL and IR metadata but no GraphQL surface;
+   * only the data plane writes them. Omitted when false.
+   */
+  internal: z.literal(true).optional(),
+  /**
+   * The materialized copy of resolved table `materializes` (internal): the
+   * same columns as that view, including its cell parts, maintained by the
+   * data plane. Omitted otherwise.
+   */
+  materializes: identifier2.optional()
 });
+var MAX_VIEW_QUERY = 1e5;
+var MAX_RESOLVED_VIEW_QUERY = 5e6;
 var canonicalViewSchema = z.object({
-  view: identifier,
+  view: identifier2,
   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, {
+  query: z.string().min(1).max(MAX_RESOLVED_VIEW_QUERY).refine(isSingleViewQuerySql, {
     message: "view query must be one SELECT/WITH statement without comments or dollar-quoted bodies"
   }),
   /** Namespace-local logical relation names, sorted for deterministic hashing. */
-  dependencies: z.array(identifier).max(500)
+  dependencies: z.array(identifier2).max(500),
+  /**
+   * Present when this view is a resolved table (defineResolvedTable): the
+   * multi-source metadata behind its generated query. Omitted otherwise so
+   * existing views hash unchanged.
+   */
+  resolved: canonicalResolvedSchema.optional(),
+  /** System-owned view (a materialized resolved table's compute view): no GraphQL surface. */
+  internal: z.literal(true).optional()
 }).superRefine((view, ctx) => {
+  if (view.resolved === void 0 && view.query.length > MAX_VIEW_QUERY) {
+    ctx.addIssue({ code: "custom", path: ["query"], message: `view query must be at most ${MAX_VIEW_QUERY} characters` });
+  }
   for (const [index3, column] of view.columns.entries()) {
     if (column.default !== void 0 || column.defaultFn !== void 0) {
       ctx.addIssue({ code: "custom", path: ["columns", index3], message: `view column '${column.name}' cannot declare a default` });
     }
+    if (column.onUpdateFn !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["columns", index3], message: `view column '${column.name}' cannot declare onUpdateFn` });
+    }
     if (column.unique) {
       ctx.addIssue({ code: "custom", path: ["columns", index3], message: `view column '${column.name}' cannot declare unique` });
     }
@@ -380,15 +951,82 @@ var canonicalViewSchema = z.object({
       ctx.addIssue({ code: "custom", path: ["columns", index3], message: `view column '${column.name}' cannot declare migration hints` });
     }
   }
+  if (view.resolved === void 0 && view.internal !== true) {
+    for (const [index3, column] of view.columns.entries()) {
+      if (column.cell) ctx.addIssue({ code: "custom", path: ["columns", index3], message: `only resolved tables carry cell columns ('${column.name}')` });
+    }
+  }
   for (const [index3, link] of view.links.entries()) {
     if (link.enforce) {
       ctx.addIssue({ code: "custom", path: ["links", index3, "enforce"], message: `view link '${link.name}' cannot enforce a foreign key` });
     }
+    if (link.onDelete !== void 0 || link.onUpdate !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["links", index3], message: `view link '${link.name}' cannot declare referential actions` });
+    }
   }
 });
+var CELL_PART_TYPES = {
+  at: "timestamptz",
+  by: "text",
+  rev: "uuid",
+  source: "text",
+  conflicts: "jsonb"
+};
+function trackedCellColumns(table) {
+  const pk = new Set(table.primaryKey ?? []);
+  return table.columns.filter((column) => column.cell === void 0 && !pk.has(column.columnName) && column.onUpdateFn === void 0);
+}
+var SUFFIXES = Object.values(CELL_PART_SUFFIX);
+function validateCellMetadata(table, index3, ctx) {
+  const fail3 = (message, path = ["tables", index3]) => ctx.addIssue({ code: "custom", path, message });
+  const cells = table.columns.flatMap((column, position) => column.cell ? [{ column, position, cell: column.cell }] : []);
+  if (table.materializes !== void 0) return;
+  if (table.cellMetadata !== true) {
+    for (const { position } of cells) fail3(`cell-metadata columns require cellMetadata on table '${table.table}'`, ["tables", index3, "columns", position]);
+    return;
+  }
+  if (table.source !== void 0) {
+    fail3(`synced table '${table.table}' cannot track cell metadata`);
+    return;
+  }
+  const tracked = trackedCellColumns(table);
+  const byName = new Map(tracked.map((column) => [column.name, column]));
+  const withRev = cells.some(({ cell }) => cell.part === "rev");
+  if (withRev && table.internal !== true) fail3(`only a resolved table's internal sources carry '__rev' cell columns ('${table.table}')`);
+  const seen = /* @__PURE__ */ new Set();
+  for (const { column, position, cell } of cells) {
+    const path = ["tables", index3, "columns", position];
+    const owner = byName.get(cell.of);
+    if (!owner) {
+      fail3(`cell column '${column.name}' belongs to '${cell.of}', which is not a tracked column`, path);
+      continue;
+    }
+    if (cell.part !== "at" && cell.part !== "by" && cell.part !== "rev") fail3(`a table cell column must be part at/by/rev, not '${cell.part}'`, path);
+    if (column.name !== cellColumnName(owner.name, cell.part) || column.columnName !== cellColumnName(owner.columnName, cell.part)) {
+      fail3(`cell column for '${owner.name}' ${cell.part} must be named '${cellColumnName(owner.name, cell.part)}' / '${cellColumnName(owner.columnName, cell.part)}'`, path);
+    }
+    if (column.type !== CELL_PART_TYPES[cell.part] || !column.nullable || column.unique || column.default !== void 0 || column.defaultFn !== void 0) {
+      fail3(`cell column '${column.name}' must be a nullable, default-less ${CELL_PART_TYPES[cell.part]}`, path);
+    }
+    const key = `${cell.of}:${cell.part}`;
+    if (seen.has(key)) fail3(`duplicate cell column '${column.name}'`, path);
+    seen.add(key);
+  }
+  for (const column of tracked) {
+    if (column.columnName.length > MAX_TRACKED_COLUMN_NAME) {
+      fail3(`column '${column.columnName}' is too long to track cell metadata (max ${MAX_TRACKED_COLUMN_NAME} characters)`);
+    }
+    if (SUFFIXES.some((suffix) => column.columnName.endsWith(suffix))) {
+      fail3(`column '${column.columnName}' ends in a reserved cell-metadata suffix (${SUFFIXES.join(", ")})`);
+    }
+    for (const part of withRev ? ["at", "by", "rev"] : ["at", "by"]) {
+      if (!seen.has(`${column.name}:${part}`)) fail3(`tracked column '${column.name}' is missing its '${cellColumnName(column.columnName, part)}' cell column`);
+    }
+  }
+}
 var canonicalDefinitionSchema = z.object({
   definition_format: z.literal(CANONICAL_FORMAT),
-  namespace: identifier.max(41),
+  namespace: identifier2.max(41),
   description: z.string().max(2e3).optional(),
   enums: z.array(canonicalEnumSchema).default([]),
   tables: z.array(canonicalTableSchema).min(0).max(500),
@@ -406,6 +1044,74 @@ var canonicalDefinitionSchema = z.object({
       ctx.addIssue({ code: "custom", path: ["tables", index3, "table"], message: `duplicate relation '${table.table}'` });
     }
     seen.add(table.table);
+    validateCellMetadata(table, index3, ctx);
+    if (table.source !== void 0) {
+      for (const [columnIndex, column] of table.columns.entries()) {
+        if (column.onUpdateFn !== void 0) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["tables", index3, "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 [index3, link] of table.links.entries()) {
+      if ((link.onDelete !== void 0 || link.onUpdate !== void 0) && (!link.enforce || link.kind !== "toOne")) {
+        ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "links", index3], message: "referential actions require an enforced toOne link" });
+      }
+      if (link.onDelete === "set null" || link.onUpdate === "set null") {
+        const source = table.columns.find((column) => column.columnName === link.on);
+        if (source?.nullable === false || table.primaryKey?.includes(link.on)) ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "links", index3], message: "SET NULL requires a nullable source column" });
+      }
+    }
+    for (const [index3, check] of (table.checks ?? []).entries()) {
+      const fail3 = (message) => ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "checks", index3], message });
+      if (table.source) fail3("synced tables cannot declare checks");
+      if (names.has(check.name)) fail3(`duplicate constraint '${check.name}'`);
+      names.add(check.name);
+      try {
+        compileCheckExpression(check.expression, table.columns);
+      } catch (error) {
+        fail3(error instanceof Error ? error.message : String(error));
+      }
+    }
+    for (const [index3, fk] of (table.foreignKeys ?? []).entries()) {
+      const fail3 = (message) => ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "foreignKeys", index3], message });
+      if (names.has(fk.name)) fail3(`duplicate foreign key '${fk.name}'`);
+      names.add(fk.name);
+      const target = fkTables.get(fk.target);
+      if (table.source || !target || target.source) {
+        fail3("foreign keys must connect owned tables in the same namespace");
+        continue;
+      }
+      if (fk.columns.length !== fk.references.length) fail3("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) fail3("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) fail3("foreign key references an unknown column");
+        else if (JSON.stringify(sourceColumn.type) !== JSON.stringify(targetColumn.type)) fail3("foreign key column types must match");
+      }
+      if (fk.onDelete === "set null" || fk.onUpdate === "set null") {
+        if (fk.columns.some((name) => table.columns.find((column) => column.columnName === name)?.nullable === false || table.primaryKey?.includes(name))) fail3("SET NULL requires nullable source columns");
+      }
+      const uniqueKeys = [target.primaryKey ?? [], ...target.indexes.filter((index4) => index4.unique).map((index4) => index4.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)))) fail3("foreign key target columns must form a unique key");
+    }
+  }
+  for (const [viewIndex, view] of (definition.views ?? []).entries()) {
+    for (const message of validateResolvedView({ view, tables: definition.tables, views: definition.views ?? [] })) {
+      ctx.addIssue({ code: "custom", path: ["views", viewIndex, "resolved"], message });
+    }
   }
   const tableByName = new Map(definition.tables.map((table) => [table.table, table]));
   for (const [tableIndex, table] of definition.tables.entries()) {
@@ -501,7 +1207,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;
@@ -515,12 +1221,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) => ({
@@ -530,8 +1236,12 @@ function canonicalRelations(definition) {
     ...view.primaryKey !== void 0 ? { primaryKey: view.primaryKey } : {},
     links: view.links,
     indexes: [],
-    policies: { read: view.policies.read },
-    actions: []
+    // A resolved table's write policies (evaluated against the resolved row)
+    // ride alongside the view's read policy.
+    policies: { read: view.policies.read, ...view.resolved?.policies ?? {} },
+    actions: [],
+    ...view.resolved !== void 0 ? { resolved: view.resolved } : {},
+    ...view.internal ? { internal: true } : {}
   }));
   return [...definition.tables, ...views].sort((a, b) => a.table.localeCompare(b.table));
 }
@@ -541,12 +1251,14 @@ function normalizeCanonical(definition) {
     ...definition,
     enums: sortByName(definition.enums),
     tables: [...definition.tables].sort((a, b) => a.table.localeCompare(b.table)).map((t2) => {
-      const { cowMutations, ...rest } = t2;
+      const { cowMutations, foreignKeys, checks, ...rest } = t2;
       return {
         ...rest,
         links: sortByName(t2.links),
         indexes: [...t2.indexes].sort((a, b) => (a.name ?? a.columns.join("_")).localeCompare(b.name ?? b.columns.join("_"))),
         actions: sortByName(t2.actions),
+        ...foreignKeys?.length ? { foreignKeys: sortByName(foreignKeys) } : {},
+        ...checks?.length ? { checks: sortByName(checks) } : {},
         // Omitted entirely when absent/empty so pre-CoW documents hash unchanged.
         ...cowMutations !== void 0 && cowMutations.length > 0 ? { cowMutations: sortByName(cowMutations) } : {}
       };
@@ -561,25 +1273,6 @@ function normalizeCanonical(definition) {
   }
   return normalized;
 }
-
-// src/constants.ts
-var NAMESPACE_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
-var IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;
-var MAX_IDENTIFIER_LENGTH = 63;
-var CAPABILITY_KEY_PATTERN = /^(?:org\/)?[a-z0-9-]{1,64}$/;
-var CLAIM_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
-var QUALIFIED_TABLE_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
-var SYNCED_SOURCE_PATTERN = /^gold\.[a-z][a-z0-9_]*$/;
-var ORM_SCHEMA_PREFIX = "orm_";
-var CONSUMER_ROLE_SUFFIX = "_consumer";
-var ormSchemaName = (namespace) => `${ORM_SCHEMA_PREFIX}${namespace}`;
-var consumerRoleName = (namespace) => `${ORM_SCHEMA_PREFIX}${namespace}${CONSUMER_ROLE_SUFFIX}`;
-var DEFINITION_FILE_EXTENSIONS = [".yml", ".yaml"];
-var NAMESPACE_CONFIG_FILENAMES = /* @__PURE__ */ new Set(["namespace.yaml", "namespace.yml"]);
-var HASH_DOMAIN = "sequence-orm-definitions\0";
-var MAX_DEFINITION_FILE_BYTES = 1024 * 1024;
-var RESERVED_TABLE_NAMES = /* @__PURE__ */ new Set(["actions", "query"]);
-var RESERVED_COLUMN_NAMES = /* @__PURE__ */ new Set(["select", "order", "limit", "offset"]);
 function stableJson(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
@@ -852,8 +1545,19 @@ function isSeqNamespaceConfig(value) {
   return typeof value === "object" && value !== null && value.kind === NAMESPACE_CONFIG_BRAND;
 }
 function serializeNamespace(input) {
-  const { config, tables } = input;
-  const views = input.views ?? [];
+  const { config } = input;
+  const views = [...input.views ?? []];
+  const tables = [...input.tables];
+  for (const view of views) {
+    for (const internal of view.config.resolved?.internalTables ?? []) {
+      if (!tables.includes(internal)) tables.push(internal);
+    }
+  }
+  for (const view of [...views]) {
+    for (const internal of view.config.resolved?.internalViews ?? []) {
+      if (!views.includes(internal)) views.push(internal);
+    }
+  }
   const enums = input.enums ?? [];
   const tablesByName = /* @__PURE__ */ new Map();
   for (const table of tables) {
@@ -955,6 +1659,9 @@ function buildCanonicalTable({ table, relationsByName, enumsByName }) {
   if (table.config.renamedFrom !== void 0) candidate.renamedFrom = table.config.renamedFrom;
   if (table.source !== void 0) candidate.source = table.source;
   if (table.source !== void 0) {
+    if (table.config.checks?.length) {
+      throw new OrmDefinitionError(`synced table "${table.tableName}" is system-owned; checks are not allowed`, table.file);
+    }
     if (table.config.indexes !== void 0 && table.config.indexes.length > 0) {
       throw new OrmDefinitionError(
         `synced table "${table.tableName}" is system-owned; indexes are not allowed`,
@@ -992,6 +1699,11 @@ function buildCanonicalTable({ table, relationsByName, enumsByName }) {
     if (builder.isPrimaryKey) columnLevelPk.push(column.columnName);
     candidate.columns?.push(column);
   }
+  if (table.config.internal === true) candidate.internal = true;
+  if (table.config.materializes !== void 0) candidate.materializes = table.config.materializes;
+  if (table.config.cellMetadata === true && table.source !== void 0) {
+    throw new OrmDefinitionError(`synced table "${table.tableName}" cannot track cell metadata \u2014 its DDL is owned by the sync`, table.file);
+  }
   if (table.config.primaryKey !== void 0) {
     if (columnLevelPk.length > 0) {
       throw new OrmDefinitionError(
@@ -1005,6 +1717,45 @@ function buildCanonicalTable({ table, relationsByName, enumsByName }) {
   } else if (columnLevelPk.length > 0) {
     candidate.primaryKey = columnLevelPk;
   }
+  if (table.config.cellMetadata === true) {
+    candidate.cellMetadata = true;
+    const parts = table.config.cellRevisions === true ? ["at", "by", "rev"] : ["at", "by"];
+    const tracked = trackedCellColumns({ columns: candidate.columns ?? [], primaryKey: candidate.primaryKey });
+    for (const column of tracked) {
+      for (const part of parts) {
+        candidate.columns?.push({
+          name: cellColumnName(column.name, part),
+          columnName: cellColumnName(column.columnName, part),
+          type: CELL_PART_TYPES[part],
+          nullable: true,
+          unique: false,
+          deprecated: false,
+          cell: { of: column.name, part }
+        });
+      }
+    }
+  }
+  if (table.config.foreignKeys?.length) {
+    if (table.source) throw new OrmDefinitionError(`synced table "${table.tableName}" cannot enforce foreign keys`, table.file);
+    candidate.foreignKeys = table.config.foreignKeys.map((fk) => {
+      const target = resolveRelationRef({ ref: fk.target, fail: (message) => {
+        throw new OrmDefinitionError(message, table.file);
+      } });
+      if (!isSeqTable(target) || !relationsByName.has(target.tableName)) throw new OrmDefinitionError("foreign key target must be a table in this namespace", table.file);
+      return {
+        name: fk.name,
+        columns: fk.columns.map((ref) => resolveColumnRef({ relation: table, ref, role: `foreign key "${fk.name}" column` })),
+        target: target.tableName,
+        references: fk.references.map((ref) => resolveColumnRef({ relation: target, ref, role: `foreign key "${fk.name}" reference` })),
+        ...fk.deferrable ? { deferrable: fk.deferrable } : {},
+        ...fk.onDelete ? { onDelete: fk.onDelete } : {},
+        ...fk.onUpdate ? { onUpdate: fk.onUpdate } : {}
+      };
+    });
+  }
+  if (table.config.checks?.length) {
+    candidate.checks = table.config.checks.map((check) => ({ name: check.name, expression: check.expression }));
+  }
   for (const index3 of table.config.indexes ?? []) {
     const entry = {
       columns: index3.columns.map((ref) => resolveColumnRef({ relation: table, ref, role: "index" }))
@@ -1057,6 +1808,12 @@ function buildCanonicalView({
     if (column.default !== void 0 || column.defaultFn !== void 0) {
       throw new OrmDefinitionError(`view "${view.viewName}": column "${propertyName}" cannot declare a default`, view.file);
     }
+    if (column.onUpdateFn !== void 0) {
+      throw new OrmDefinitionError(
+        `view "${view.viewName}": column "${propertyName}" cannot declare onUpdateFn`,
+        view.file
+      );
+    }
     if (column.unique) {
       throw new OrmDefinitionError(`view "${view.viewName}": column "${propertyName}" cannot declare unique`, view.file);
     }
@@ -1094,7 +1851,33 @@ function buildCanonicalView({
     columns,
     ...primaryKey2 !== void 0 ? { primaryKey: primaryKey2 } : {},
     links,
-    policies: { read: toCanonicalPolicy(view.config.policies.read) }
+    policies: { read: toCanonicalPolicy(view.config.policies.read) },
+    ...view.config.resolved !== void 0 ? { resolved: buildCanonicalResolved(view.config.resolved) } : {},
+    ...view.config.internal === true ? { internal: true } : {}
+  };
+}
+function buildCanonicalResolved(resolved) {
+  const policies = {};
+  if (resolved.policies.write !== void 0) policies.write = toCanonicalPolicy(resolved.policies.write);
+  if (resolved.policies.insert !== void 0) policies.insert = toCanonicalPolicy(resolved.policies.insert);
+  if (resolved.policies.update !== void 0) policies.update = toCanonicalPolicy(resolved.policies.update);
+  return {
+    sources: resolved.sources.map((source) => ({
+      name: source.name,
+      kind: source.kind,
+      table: source.table.tableName,
+      columns: [...source.columns],
+      ...source.updatedAt !== void 0 ? { updatedAt: source.updatedAt } : {},
+      ...source.key !== void 0 ? { key: source.key } : {},
+      ...source.fetch !== void 0 ? { fetch: source.fetch } : {},
+      ...source.function !== void 0 ? { function: { ...source.function } } : {},
+      ...source.prefetchDefaults !== void 0 ? { prefetchDefaults: { ...source.prefetchDefaults } } : {},
+      ...source.writeback !== void 0 ? { writeback: { ...source.writeback, columns: [...source.writeback.columns] } } : {}
+    })),
+    resolve: resolved.rules.map((rule) => ({ ...rule, candidates: [...rule.candidates] })),
+    deletedBy: [...resolved.deletedBy],
+    ...resolved.materialized ? { materialized: { ...resolved.materialized } } : {},
+    policies
   };
 }
 function buildCanonicalLink({
@@ -1105,14 +1888,17 @@ function buildCanonicalLink({
 }) {
   const ownerKind = relationKind(relation);
   const ownerName = relationName(relation);
-  const fail2 = (message) => {
+  const fail3 = (message) => {
     throw new OrmDefinitionError(`${ownerKind} "${ownerName}": link "${linkName}" ${message}`, relation.file);
   };
   if (link.enforce && link.linkKind !== "toOne") {
-    return fail2("sets enforce: true, which is only supported on toOne links");
+    return fail3("sets enforce: true, which is only supported on toOne links");
+  }
+  if ((link.onDelete !== void 0 || link.onUpdate !== void 0) && !link.enforce) {
+    return fail3("sets a referential action without enforce: true");
   }
   if (link.linkKind === "toPlatformUser") {
-    if (link.target !== void 0) return fail2("is toPlatformUser and must not declare a target table");
+    if (link.target !== void 0) return fail3("is toPlatformUser and must not declare a target table");
     return {
       name: linkName,
       kind: "toPlatformUser",
@@ -1122,13 +1908,13 @@ function buildCanonicalLink({
       ...link.description !== void 0 ? { description: link.description } : {}
     };
   }
-  const target = resolveRelationRef({ ref: link.target, fail: fail2 });
+  const target = resolveRelationRef({ ref: link.target, fail: fail3 });
   const targetName = relationName(target);
   if (!relationsByName.has(targetName)) {
-    return fail2(`targets ${relationKind(target)} "${targetName}" which is not part of this namespace`);
+    return fail3(`targets ${relationKind(target)} "${targetName}" which is not part of this namespace`);
   }
   if (link.enforce && (!isSeqTable(relation) || !isSeqTable(target))) {
-    return fail2("cannot enforce a PostgreSQL foreign key involving a view");
+    return fail3("cannot enforce a PostgreSQL foreign key involving a view");
   }
   const owningSide = link.linkKind === "toOne" ? relation : target;
   const referencedSide = link.linkKind === "toOne" ? target : relation;
@@ -1139,22 +1925,24 @@ function buildCanonicalLink({
     on: resolveColumnRef({ relation: owningSide, ref: link.on, role: `link "${linkName}" on` }),
     ...link.references !== void 0 ? { references: resolveColumnRef({ relation: referencedSide, ref: link.references, role: `link "${linkName}" references` }) } : {},
     enforce: link.enforce,
+    ...link.onDelete !== void 0 ? { onDelete: link.onDelete } : {},
+    ...link.onUpdate !== void 0 ? { onUpdate: link.onUpdate } : {},
     ...link.description !== void 0 ? { description: link.description } : {}
   };
 }
-function resolveRelationRef({ ref, fail: fail2 }) {
-  if (ref === void 0) return fail2("declares no target relation");
+function resolveRelationRef({ ref, fail: fail3 }) {
+  if (ref === void 0) return fail3("declares no target relation");
   if (typeof ref !== "function") return ref;
   let resolved;
   try {
     resolved = ref();
   } catch (error) {
-    return fail2(
+    return fail3(
       `target thunk threw (${error instanceof Error ? error.message : String(error)}) \u2014 lazy refs resolve at serialize time; make sure the target module ran`
     );
   }
   if (!isSeqTable(resolved) && !isSeqView(resolved)) {
-    return fail2("target thunk did not return a relation defined with defineTable/defineView");
+    return fail3("target thunk did not return a relation defined with defineTable/defineView");
   }
   return resolved;
 }
@@ -1221,6 +2009,10 @@ async function loadNamespaceFromDir(dir, options = {}) {
     fsCache: false,
     ...options.ormModulePath !== void 0 ? {
       alias: {
+        // The public /drizzle barrel re-exports this pinned dependency.
+        // Explicitly map it before the root alias: otherwise jiti appends
+        // "/drizzle" to the overridden module's filename.
+        "@sequenceholdings/orm/drizzle": createRequire(import.meta.url).resolve("drizzle-orm"),
         "@sequenceholdings/orm": options.ormModulePath,
         "@sequenceholdings/orm/authoring": options.ormModulePath
       }
@@ -1434,6 +2226,7 @@ var ORDER_BY_ENUM_VALUES = [
   "DESC_NULLS_LAST"
 ];
 var PLATFORM_USER_TYPENAME = "PlatformUser";
+var DATE_BUCKET_ENUM = "DateBucket";
 function tableNames(table) {
   const root = camelCase(table);
   const rootPascal = pascalCase(table);
@@ -1449,6 +2242,7 @@ function tableNames(table) {
     updateByPkRoot: `update${rootPascal}ByPk`,
     deleteRoot: `delete${rootPascal}`,
     deleteByPkRoot: `delete${rootPascal}ByPk`,
+    revertByPkRoot: `revert${rootPascal}ByPk`,
     boolExp: `${type}BoolExp`,
     orderBy: `${type}OrderBy`,
     selectColumn: `${type}SelectColumn`,
@@ -1466,9 +2260,25 @@ 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`
   };
 }
+var CELL_TYPENAMES = {
+  /** A plain table's cell: when and by whom it was last written. */
+  stamp: "CellStamp",
+  /** A resolved table's cell: which source won, when, by whom, and newer losers. */
+  resolved: "ResolvedCell",
+  /** A newer candidate that lost to the column's rule. */
+  conflict: "CellConflict"
+};
+function cellsTypename(typename) {
+  return `${typename}Cells`;
+}
 
 // src/codegen-gql/type-policies.ts
 function generateTypePolicies(canonical) {
@@ -1476,13 +2286,13 @@ function generateTypePolicies(canonical) {
   const entries = [];
   let hasPlatformUser = false;
   for (const table of canonicalRelations(def)) {
-    if (table.source !== void 0) continue;
+    if (table.source !== void 0 || table.internal === true) continue;
     if (table.links.some((link) => link.kind === "toPlatformUser")) hasPlatformUser = true;
     if (!table.primaryKey || table.primaryKey.length === 0) continue;
-    const keyFields = table.primaryKey.map((identifier2) => {
-      const column = table.columns.find((c) => c.columnName === identifier2 || c.name === identifier2);
+    const keyFields = table.primaryKey.map((identifier3) => {
+      const column = table.columns.find((c) => c.columnName === identifier3 || c.name === identifier3);
       if (!column) {
-        throw new CodegenGqlError(`Primary key column "${identifier2}" not found on relation "${table.table}".`);
+        throw new CodegenGqlError(`Primary key column "${identifier3}" not found on relation "${table.table}".`);
       }
       return fieldName(column.name);
     });
@@ -1499,7 +2309,100 @@ ${body}
 }
 `;
 }
-var IR_VERSION = 1;
+
+// src/codegen-gql/source-contracts.ts
+var TS_TYPE = {
+  uuid: "string",
+  text: "string",
+  integer: "number",
+  bigint: "number | string",
+  numeric: "number | string",
+  double: "number | string",
+  boolean: "boolean",
+  timestamptz: "string",
+  date: "string",
+  jsonb: "unknown"
+};
+function tsType(column, enums) {
+  if (typeof column.type === "string") return TS_TYPE[column.type] ?? "unknown";
+  const values = enums.get(column.type.enum) ?? [];
+  return values.length > 0 ? values.map((value) => JSON.stringify(value)).join(" | ") : "string";
+}
+function generateSourceContracts(canonical) {
+  const def = normalizeCanonical(canonicalDefinitionSchema.parse(canonical));
+  const enums = new Map(def.enums.map((entry) => [entry.name, entry.values]));
+  const blocks = [];
+  for (const view of def.views ?? []) {
+    for (const source of view.resolved?.sources ?? []) {
+      if (source.kind !== "prefetch") continue;
+      const name = `${pascalCase(view.view)}${pascalCase(source.name)}`;
+      const byName = new Map(view.columns.map((column) => [column.name, column]));
+      const key = byName.get(source.key ?? "");
+      const valueLines = source.columns.map((column) => {
+        const def2 = byName.get(column);
+        return `  ${column}?: ${def2 ? tsType(def2, enums) : "unknown"} | null`;
+      });
+      const writable = source.writeback?.columns ?? [];
+      blocks.push([
+        `/** ${view.view} \u2190 ${source.name} (${source.function?.kind ?? "managed"} function '${source.function?.id ?? ""}'). */`,
+        `export type ${name}Key = ${key ? tsType(key, enums) : "string"}`,
+        `export interface ${name}Values {
+${valueLines.join("\n")}
+}`,
+        `export interface ${name}PrefetchRequest {
+  action: 'prefetch'
+  namespace: string
+  table: '${view.view}'
+  source: '${source.name}'
+  keys: ${name}Key[]
+  columns: string[]
+  actor: { sub: string }
+}`,
+        `export interface ${name}PrefetchResponse {
+  rows: Array<{ key: ${name}Key; values: ${name}Values; cells?: Partial<Record<keyof ${name}Values, string>>; sourceUpdatedAt?: string }>
+  missing?: ${name}Key[]
+}`,
+        ...writable.length > 0 ? [
+          `export type ${name}WritebackColumn = ${writable.map((column) => JSON.stringify(column)).join(" | ")}`,
+          `export interface ${name}WritebackRequest {
+  action: 'writeback'
+  namespace: string
+  table: '${view.view}'
+  source: '${source.name}'
+  key: ${name}Key
+  changes: Partial<Pick<${name}Values, ${name}WritebackColumn>>
+  before: Partial<Pick<${name}Values, ${name}WritebackColumn>>
+  idempotencyKey: string
+  actor: { sub: string }
+}`,
+          `/** Respond 200 with this; respond 400/409/422 with { detail } when the source system refuses the change. */
+export interface ${name}WritebackResponse {
+  values?: ${name}Values
+  cells?: Partial<Record<keyof ${name}Values, string>>
+  sourceUpdatedAt?: string
+}`
+        ] : []
+      ].join("\n\n"));
+    }
+  }
+  if (blocks.length === 0) return null;
+  return `/* Generated by @sequenceholdings/orm \u2014 resolved-table source function contracts. Do not edit. */
+
+${blocks.join("\n\n")}
+`;
+}
+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?",
@@ -1571,6 +2474,21 @@ var selectionIrSchema = z.lazy(
   () => z.object({
     typename: z.string(),
     columns: z.array(z.object({ alias: z.string(), column: z.string() })),
+    cells: z.object({
+      alias: z.string(),
+      typename: z.string(),
+      fields: z.array(z.object({
+        alias: z.string(),
+        column: z.string(),
+        typename: z.string(),
+        parts: z.array(z.object({
+          alias: z.string(),
+          part: z.enum(["source", "at", "by", "conflicts"]),
+          fields: z.array(z.object({ alias: z.string(), field: z.enum(["source", "at", "value"]) })).optional(),
+          typename: z.string().optional()
+        }))
+      }))
+    }).optional(),
     relations: z.array(z.object({
       alias: z.string(),
       link: z.string(),
@@ -1592,6 +2510,11 @@ var selectionIrSchema = z.lazy(
   })
 );
 var includeIfSchema = z.object({ variable: z.string(), negated: z.boolean() });
+var prefetchPlanIrSchema = z.object({
+  source: z.string(),
+  maxStalenessMs: z.number().int().positive().optional(),
+  key: z.union([z.object({ one: valueIrSchema }), z.object({ many: valueIrSchema })])
+});
 var selectRootSchema = z.object({
   kind: z.literal("select"),
   alias: z.string(),
@@ -1603,7 +2526,8 @@ var selectRootSchema = z.object({
   distinctOn: z.union([z.array(z.string()), z.object({ slot: z.string() })]).optional(),
   limit: limitIrSchema,
   offset: z.object({ variable: z.string().optional(), value: z.number().int().optional() }).optional(),
-  includeIf: includeIfSchema.optional()
+  includeIf: includeIfSchema.optional(),
+  prefetch: z.array(prefetchPlanIrSchema).optional()
 });
 var byPkRootSchema = z.object({
   kind: z.literal("byPk"),
@@ -1613,7 +2537,8 @@ var byPkRootSchema = z.object({
   pk: z.array(z.object({ column: z.string(), value: valueIrSchema })).min(1),
   /** Policy predicate — ANDed with the PK match. */
   where: predIrSchema,
-  includeIf: includeIfSchema.optional()
+  includeIf: includeIfSchema.optional(),
+  prefetch: z.array(prefetchPlanIrSchema).optional()
 });
 var aggregateRootSchema = z.object({
   kind: z.literal("aggregate"),
@@ -1626,6 +2551,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 })) })
@@ -1644,7 +2596,20 @@ var mutationRootSchema = z.object({
    * coalesce view falls back to synced. Both are gated on a matching synced
    * row and carry the write policy in `where` like update/delete.
    */
-  op: z.enum(["insert", "insertOne", "update", "updateByPk", "delete", "deleteByPk", "cowOverride", "cowRevert"]),
+  op: z.enum(["insert", "insertOne", "update", "updateByPk", "delete", "deleteByPk", "cowOverride", "cowRevert", "resolvedWrite"]),
+  /**
+   * resolvedWrite: a write to a resolved table (`table` is its view). The
+   * executor gates on the resolved row (write policy in `where`), writes only
+   * the touched cells into the manual source, then re-checks `insertCheck`
+   * against the resolved row. `revert` clears `revertColumns` from the manual
+   * source; `delete` tombstones the row there.
+   */
+  resolvedAction: z.enum(["insert", "update", "delete", "revert"]).optional(),
+  revertColumns: z.array(z.string()).optional(),
+  /** `@writeback(source:, mode:)` directives on this root. */
+  writeback: z.array(z.object({ source: z.string(), mode: z.enum(["sync", "async"]) })).optional(),
+  /** `@localOnly(source:)` — writeback columns deliberately kept local for these sources. */
+  localOnly: z.array(z.string()).optional(),
   alias: z.string(),
   table: z.string(),
   /** CoW ops: logical name of the synced twin (read through its policy-filtered view). */
@@ -1671,12 +2636,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 = [
@@ -1706,7 +2674,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"]),
@@ -1718,6 +2686,50 @@ 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 [index3, 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", index3], message: "affected-row assertions require unconditional mutation roots and IR v2" });
+    }
+  }
+});
+var resolvedSourceIrSchema = z.object({
+  name: z.string(),
+  kind: z.enum(["manual", "etl", "prefetch"]),
+  /** Logical table key of the backing relation. */
+  table: z.string(),
+  columns: z.array(z.string()),
+  key: z.string().optional(),
+  fetch: z.union([
+    z.object({ shape: z.literal("single") }),
+    z.object({ shape: z.literal("batch"), maxKeys: z.number().int().positive() })
+  ]).optional(),
+  function: z.object({ kind: z.enum(["managed", "native"]), id: z.string() }).optional(),
+  prefetchDefaults: z.object({
+    maxStalenessMs: z.number().int().positive(),
+    timeoutMs: z.number().int().positive(),
+    onError: z.enum(["fallback", "fail"])
+  }).optional(),
+  writeback: z.object({
+    columns: z.array(z.string()),
+    defaultMode: z.enum(["sync", "async"]),
+    timeoutMs: z.number().int().positive(),
+    clearManualOnConfirm: z.boolean()
+  }).optional()
+});
+var resolvedMetaIrSchema = z.object({
+  /** Logical pk column of the resolved view (single-column). */
+  pk: z.string(),
+  /** Source name of the manual source. */
+  manual: z.string(),
+  sources: z.array(resolvedSourceIrSchema),
+  deletedBy: z.array(z.string()),
+  /**
+   * Materialized: the view reads `table`, which the data plane refreshes from
+   * the `compute` view (claims-gated) whenever it writes a source row.
+   */
+  materialized: z.object({ table: z.string(), compute: z.string() }).optional()
 });
 var tableMetaIrSchema = z.object({
   table: z.string(),
@@ -1754,18 +2766,45 @@ 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(),
+  /**
+   * Per-cell metadata: logical column → the logical names of its cell-part
+   * columns (which are listed in `columns`, but never filterable, orderable or
+   * writable). Tables stamp `at`/`by` (and a manual source `rev`) on every
+   * write; resolved views expose `source`/`at`/`by`/`conflicts`. Omitted when
+   * the relation tracks no cells.
+   */
+  cells: z.record(z.string(), z.object({
+    at: z.string().optional(),
+    by: z.string().optional(),
+    rev: z.string().optional(),
+    source: z.string().optional(),
+    conflicts: z.string().optional()
+  }).strict()).optional(),
+  /** Resolved-table view metadata (sources, prefetch/writeback config) for the data plane. */
+  resolved: resolvedMetaIrSchema.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) {
@@ -1776,19 +2815,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
@@ -1816,7 +2855,7 @@ var IDENTIFIER_CHAR = /[a-zA-Z0-9_]/;
 var NUMBER_PATTERN = /^-?\d+(\.\d+)?/;
 var SCALAR_CLAIM_KEYS = Object.entries(CLAIMS_CONTRACT).filter(([, type]) => !type.endsWith("[]")).map(([key]) => key);
 var ARRAY_CLAIM_KEYS = Object.entries(CLAIMS_CONTRACT).filter(([, type]) => type.endsWith("[]")).map(([key]) => key);
-function tokenize(source) {
+function tokenize2(source) {
   const tokens = [];
   let position = 0;
   while (position < source.length) {
@@ -1895,7 +2934,7 @@ function readString(source, start) {
   }
   throw new PolicyParseError("unterminated string literal", start);
 }
-var Parser = class {
+var Parser2 = class {
   constructor(tokens) {
     this.tokens = tokens;
   }
@@ -2069,7 +3108,7 @@ var Parser = class {
 function parsePolicy(source) {
   const trimmed = source.trim();
   if (trimmed.length === 0) throw new PolicyParseError("empty policy expression", 0);
-  return { source: trimmed, ast: new Parser(tokenize(trimmed)).parse() };
+  return { source: trimmed, ast: new Parser2(tokenize2(trimmed)).parse() };
 }
 
 // src/predicate-v2/compile.ts
@@ -2294,21 +3333,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;
@@ -2325,12 +3364,12 @@ function predContainsExists(pred) {
 // 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);
@@ -2341,9 +3380,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;
       }
@@ -2355,7 +3394,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;
@@ -2449,6 +3488,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);
     }
@@ -2456,6 +3500,7 @@ var PolicyInjector = class {
   injectMutation(root) {
     const table = root.table;
     const returning = root.returning ? this.injectSelection(root.returning, table) : root.returning;
+    if (root.op === "resolvedWrite") return this.injectResolvedWrite(root, returning);
     if (root.op === "insert" || root.op === "insertOne") {
       const insertPolicy = this.insert(table);
       if (predContainsExists(insertPolicy)) {
@@ -2497,6 +3542,24 @@ var PolicyInjector = class {
     }
     return { ...root, where, returning };
   }
+  /**
+   * Resolved writes are policed against the RESOLVED row, not the sparse
+   * manual row: `where` gates the existing row (update/revert/delete) and
+   * `insertCheck` is re-evaluated as a SELECT over the view after the write,
+   * so link-traversing (exists) policies are representable here.
+   */
+  injectResolvedWrite(root, returning) {
+    const table = root.table;
+    if (root.resolvedAction === "insert") {
+      const pins = (this.ctx.pins.get(table) ?? []).map(
+        (pin) => ({ column: pin.column, value: { kind: "claim", key: pin.claim } })
+      );
+      return { ...root, pinnedColumns: pins, insertCheck: this.insert(table), returning };
+    }
+    const updatePolicy = this.update(table);
+    const where = andPred(updatePolicy, root.where ? this.injectDocPred(root.where, table) : void 0);
+    return root.resolvedAction === "delete" ? { ...root, where, returning } : { ...root, where, insertCheck: updatePolicy, returning };
+  }
 };
 function collectTableSet(roots, ctx) {
   const tables = /* @__PURE__ */ new Set();
@@ -2541,20 +3604,34 @@ 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);
+        for (const source of ctx.tables[root.table]?.resolved?.sources ?? []) tables.add(source.table);
+        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();
@@ -2572,7 +3649,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);
@@ -2653,7 +3735,15 @@ 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,
+      ...column.cell ? { cell: column.cell } : {}
+    };
   });
 }
 function logicalColumn(entries, ref) {
@@ -2689,8 +3779,8 @@ function buildCompileContext(rawCanonical) {
     const pkRefs = table.primaryKey ?? (isView ? [] : ["id"]);
     const primaryKey2 = [];
     for (const ref of pkRefs) {
-      const resolved = logicalColumn(entries, ref);
-      if (!resolved) {
+      const resolved2 = logicalColumn(entries, ref);
+      if (!resolved2) {
         diagnostics.push({
           severity: "error",
           code: "unknown-pk-column",
@@ -2699,9 +3789,13 @@ function buildCompileContext(rawCanonical) {
         });
         continue;
       }
-      primaryKey2.push(resolved);
+      primaryKey2.push(resolved2);
     }
-    const active = entries.filter((c) => !c.deprecated);
+    const resolved = isView ? table.resolved : void 0;
+    const data = entries.filter((c) => c.cell === void 0);
+    const cells = cellMap(entries);
+    const active = data.filter((c) => !c.deprecated);
+    const touchOnUpdate = isView ? [] : active.filter((c) => c.onUpdateFn).map((c) => c.name);
     const constraints = [];
     if (primaryKey2.length > 0) constraints.push({ name: `${table.table}_pkey`, columns: [...primaryKey2] });
     for (const column of table.columns) {
@@ -2722,14 +3816,17 @@ 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 ? primaryKey2 : primaryKey2.length > 0 ? primaryKey2 : ["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),
+      filterable: data.map((c) => c.name),
+      orderable: data.filter((c) => c.type !== "jsonb").map((c) => c.name),
+      insertable: resolved ? resolvedWritable(data) : isView ? [] : active.map((c) => c.name),
+      settable: resolved ? resolvedWritable(data).filter((name) => !primaryKey2.includes(name)) : 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 } : {},
+      ...cells ? { cells } : {},
+      ...resolved ? { resolved: resolvedMeta({ resolved, pk: primaryKey2[0] }) } : {},
       constraints: isView ? [] : constraints,
       dynamicFilterMaxDepth: 6,
       dynamicFilterMaxNodes: 64
@@ -2750,7 +3847,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);
@@ -2802,7 +3899,7 @@ function buildCompileContext(rawCanonical) {
     compilePolicyFor("write", writePolicies);
     compilePolicyFor("insert", insertPolicies);
     compilePolicyFor("update", updatePolicies);
-    if (isView) {
+    if (isView && table.resolved === void 0) {
       writePolicies.set(table.table, CONST_FALSE);
       insertPolicies.set(table.table, CONST_FALSE);
       updatePolicies.set(table.table, CONST_FALSE);
@@ -2841,18 +3938,23 @@ function buildCompileContext(rawCanonical) {
   const queryRoots = /* @__PURE__ */ new Map();
   const mutationRoots = /* @__PURE__ */ new Map();
   for (const table of relations) {
+    if (table.internal === true) continue;
     const roots = queryRootNames(table.table);
     queryRoots.set(roots.select, { kind: "select", table: table.table });
     if ((tables[table.table]?.primaryKey.length ?? 0) > 0) {
       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))) {
         mutationRoots.set(field, { op, table: table.table });
       }
     }
+    if (table.resolved !== void 0) registerResolvedRoots({ table, mutationRoots });
   }
   for (const table of relations) {
     for (const mutation of table.cowMutations ?? []) {
@@ -2923,6 +4025,49 @@ function buildCompileContext(rawCanonical) {
     diagnostics
   };
 }
+function registerResolvedRoots({ table, mutationRoots }) {
+  const names = tableNames(table.table);
+  const canInsert = table.policies.write !== void 0 || table.policies.insert !== void 0;
+  const canUpdate = table.policies.write !== void 0 || table.policies.update !== void 0;
+  const add = (field, action) => mutationRoots.set(field, { op: "resolvedWrite", action, table: table.table });
+  if (canInsert) add(names.insertOneRoot, "insert");
+  if (canUpdate) {
+    add(names.updateByPkRoot, "update");
+    add(names.revertByPkRoot, "revert");
+    if ((table.resolved?.deletedBy.length ?? 0) > 0) add(names.deleteByPkRoot, "delete");
+  }
+}
+function cellMap(entries) {
+  const cells = {};
+  for (const entry of entries) {
+    if (entry.cell) cells[entry.cell.of] = { ...cells[entry.cell.of], [entry.cell.part]: entry.name };
+  }
+  return Object.keys(cells).length > 0 ? cells : void 0;
+}
+function resolvedWritable(entries) {
+  const system = new Set(Object.values(RESOLVED_VIEW_SYSTEM_COLUMNS).map((column) => column.name));
+  return entries.filter((entry) => !entry.deprecated && !system.has(entry.name)).map((entry) => entry.name);
+}
+function resolvedMeta({ resolved, pk }) {
+  const manual = resolved.sources.find((source) => source.kind === "manual");
+  return {
+    pk,
+    manual: manual?.name ?? "",
+    deletedBy: [...resolved.deletedBy],
+    ...resolved.materialized ? { materialized: { ...resolved.materialized } } : {},
+    sources: resolved.sources.map((source) => ({
+      name: source.name,
+      kind: source.kind,
+      table: source.table,
+      columns: [...source.columns],
+      ...source.key !== void 0 ? { key: source.key } : {},
+      ...source.fetch !== void 0 ? { fetch: source.fetch } : {},
+      ...source.function !== void 0 ? { function: source.function } : {},
+      ...source.prefetchDefaults !== void 0 ? { prefetchDefaults: source.prefetchDefaults } : {},
+      ...source.writeback !== void 0 ? { writeback: source.writeback } : {}
+    }))
+  };
+}
 function flattenSelectionSet(selectionSet, fragments, stack) {
   const selections = [];
   for (const selection of selectionSet.selections) {
@@ -2980,8 +4125,148 @@ function computeOpsHash(opHashes) {
   const digest = createHash("sha256").update(OPS_HASH_DOMAIN).update([...opHashes].sort().join("\n")).digest("hex");
   return `sha256:${digest}`;
 }
+var SOURCE_DIRECTIVES = /* @__PURE__ */ new Set(["prefetch", "writeback", "localOnly"]);
+var fail = (message, code) => {
+  throw new DocumentCompileError(message, code);
+};
+function readArgs(node, name) {
+  return (node.directives ?? []).filter((directive) => directive.name.value === name).map((directive) => {
+    const args = {};
+    for (const arg of directive.arguments ?? []) {
+      const key = arg.name.value;
+      if (key === "source" || key === "maxStaleness") {
+        if (arg.value.kind !== Kind.STRING) fail(`@${name}(${key}:) must be a string literal`, "invalid-source-directive");
+        args[key] = arg.value.value;
+      } else if (key === "mode" && name === "writeback") {
+        if (arg.value.kind !== Kind.ENUM || !["SYNC", "ASYNC"].includes(arg.value.value)) {
+          fail("@writeback(mode:) must be SYNC or ASYNC", "invalid-source-directive");
+        }
+        args.mode = arg.value.value === "SYNC" ? "sync" : "async";
+      } else {
+        fail(`@${name} does not take argument '${key}'`, "invalid-source-directive");
+      }
+    }
+    if (!args.source) fail(`@${name} needs a source: argument`, "invalid-source-directive");
+    return args;
+  });
+}
+function prefetchSourceFor({ resolved, name, directive, table }) {
+  if (!resolved) return fail(`@${directive} is only valid on resolved tables \u2014 '${table}' is not one`, "invalid-source-directive");
+  const source = resolved.sources.find((entry) => entry.name === name);
+  if (!source || source.kind !== "prefetch") {
+    const options = resolved.sources.filter((entry) => entry.kind === "prefetch").map((entry) => entry.name);
+    return fail(`@${directive}(source: "${name}") on '${table}' must name a prefetch source (${options.join(", ") || "none declared"})`, "invalid-source-directive");
+  }
+  return source;
+}
+function applyPrefetchDirectives({ node, root, meta }) {
+  const directives = readArgs(node, "prefetch");
+  for (const name of ["writeback", "localOnly"]) {
+    if (readArgs(node, name).length > 0) fail(`@${name} is only valid on resolved-table mutation roots`, "invalid-source-directive");
+  }
+  if (directives.length === 0) return root;
+  if (root.kind !== "select" && root.kind !== "byPk") {
+    return fail(`@prefetch is only valid on select and byPk roots, not '${root.alias}'`, "invalid-source-directive");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const plans = directives.map((directive) => {
+    const source = prefetchSourceFor({ resolved: meta.resolved, name: directive.source, directive: "prefetch", table: root.table });
+    if (seen.has(source.name)) fail(`@prefetch(source: "${source.name}") appears twice on '${root.alias}'`, "invalid-source-directive");
+    seen.add(source.name);
+    const maxStalenessMs = directive.maxStaleness === void 0 ? void 0 : parseDurationMs(directive.maxStaleness);
+    if (directive.maxStaleness !== void 0 && maxStalenessMs === void 0) {
+      fail(`@prefetch(maxStaleness: "${directive.maxStaleness}") must look like '500ms', '30s' or '5m'`, "invalid-source-directive");
+    }
+    const key = root.kind === "byPk" ? { one: root.pk[0].value } : selectKey({ where: root.where, pk: meta.resolved.pk, source, alias: root.alias });
+    return { source: source.name, ...maxStalenessMs !== void 0 ? { maxStalenessMs } : {}, key };
+  });
+  return { ...root, prefetch: plans };
+}
+function selectKey({ where, pk, source, alias }) {
+  const leaves = where.kind === "and" ? where.operands : [where];
+  const pinned = leaves.find((leaf) => leaf.kind === "cmp" && leaf.column === pk && (leaf.op === "eq" || leaf.op === "in"));
+  const shape = source.fetch?.shape ?? "single";
+  if (!pinned || pinned.kind !== "cmp") {
+    return fail(
+      `@prefetch(source: "${source.name}") on '${alias}': the root is not key-addressed \u2014 its where must pin '${pk}' with _eq${shape === "batch" ? " or _in" : ""} (${source.name} supports ${shape === "batch" ? "batch" : "single-key"} fetch)`,
+      "prefetch-shape-mismatch"
+    );
+  }
+  if (pinned.op === "in" && shape !== "batch") {
+    return fail(`@prefetch(source: "${source.name}") on '${alias}': ${source.name} only supports single-key fetch, but the root selects '${pk}' with _in`, "prefetch-shape-mismatch");
+  }
+  return pinned.op === "eq" ? { one: pinned.value } : { many: pinned.value };
+}
+function applyWritebackDirectives({ node, root, meta }) {
+  if (readArgs(node, "prefetch").length > 0) fail("@prefetch is only valid on query roots", "invalid-source-directive");
+  const writebacks = readArgs(node, "writeback");
+  const localOnly = readArgs(node, "localOnly");
+  if (root.kind !== "mutation" || root.op !== "resolvedWrite" || !meta.resolved) {
+    if (writebacks.length + localOnly.length > 0) fail("@writeback/@localOnly are only valid on resolved-table mutation roots", "invalid-source-directive");
+    return root;
+  }
+  const resolved = meta.resolved;
+  const declared = /* @__PURE__ */ new Map();
+  const bindings = [];
+  for (const directive of writebacks) {
+    const source = prefetchSourceFor({ resolved, name: directive.source, directive: "writeback", table: root.table });
+    if (!source.writeback) fail(`@writeback(source: "${source.name}"): source '${source.name}' declares no writeback columns`, "invalid-source-directive");
+    if (root.resolvedAction !== "update") {
+      fail(`@writeback on '${root.alias}': only update roots write back in v1 (use @localOnly for ${root.resolvedAction ?? "this"} roots)`, "writeback-shape-mismatch");
+    }
+    if (declared.has(source.name)) fail(`source '${source.name}' is declared twice on '${root.alias}'`, "invalid-source-directive");
+    declared.set(source.name, "writeback");
+    bindings.push({ source: source.name, mode: directive.mode ?? source.writeback.defaultMode });
+  }
+  for (const directive of localOnly) {
+    const source = prefetchSourceFor({ resolved, name: directive.source, directive: "localOnly", table: root.table });
+    if (declared.has(source.name)) fail(`source '${source.name}' is declared twice on '${root.alias}'`, "invalid-source-directive");
+    declared.set(source.name, "localOnly");
+  }
+  assertWritebacksDeclared({ root, meta, resolved, declared });
+  return {
+    ...root,
+    ...bindings.length > 0 ? { writeback: bindings } : {},
+    ...localOnly.length > 0 ? { localOnly: localOnly.map((directive) => directive.source) } : {}
+  };
+}
+function assertWritebacksDeclared({ root, meta, resolved, declared }) {
+  const written = writtenColumns({ root, meta });
+  for (const source of resolved.sources) {
+    const columns = source.writeback?.columns.filter((column) => written.has(column)) ?? [];
+    if (columns.length > 0 && !declared.has(source.name)) {
+      fail(
+        `'${root.alias}' sets ${columns.map((column) => `'${column}'`).join(", ")}, which source '${source.name}' writes back \u2014 add @writeback(source: "${source.name}") to push the change or @localOnly(source: "${source.name}") to keep it local`,
+        "writeback-undeclared"
+      );
+    }
+  }
+}
+function writtenColumns({ root, meta }) {
+  if (root.resolvedAction === "update") {
+    if (!root.set || "slot" in root.set) return new Set(meta.settable);
+    return new Set(root.set.entries.map((entry) => entry.column));
+  }
+  if (root.resolvedAction === "insert") {
+    if (!root.objects || "slot" in root.objects) return new Set(meta.insertable);
+    return new Set(root.objects.rows.flatMap((row) => row.map((entry) => entry.column)));
+  }
+  return /* @__PURE__ */ new Set();
+}
+
+// src/compiler-gql/lower.ts
 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",
@@ -3007,16 +4292,24 @@ var ORDER_DIRECTIONS = {
   DESC_NULLS_LAST: { direction: "desc", nulls: "last" }
 };
 var NUMERIC_TYPES = /* @__PURE__ */ new Set(["integer", "bigint", "numeric", "double"]);
-function fail(message, code, candidates = []) {
+function fail2(message, code, candidates = []) {
   throw new DocumentCompileError(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) fail2("fragments must be flattened before lowering", "internal");
+    if (node.name.value === "__typename") continue;
+    if (node.alias) fail2(`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)) {
-      fail(`argument '${arg.name.value}' on '${field.name.value}' is not supported in v2.0`, "unsupported-argument", allowed);
+      fail2(`argument '${arg.name.value}' on '${field.name.value}' is not supported in v2.0`, "unsupported-argument", allowed);
     }
   }
 }
@@ -3029,8 +4322,11 @@ var OperationLowerer = class {
   meta(table) {
     return this.ctx.tables[table];
   }
+  /** A data column — cell-metadata columns are reachable only through `cells { … }`. */
   column(table, name) {
-    return this.meta(table).columns.find((c) => c.name === name);
+    const meta = this.meta(table);
+    const column = meta.columns.find((c) => c.name === name);
+    return column && !isCellColumn(meta, name) ? column : void 0;
   }
   link(table, name) {
     return this.meta(table).links.find((l) => l.name === name);
@@ -3038,7 +4334,8 @@ var OperationLowerer = class {
   fieldCandidates(table) {
     const meta = this.meta(table);
     return [
-      ...meta.columns.map((c) => c.name),
+      ...meta.columns.filter((c) => !isCellColumn(meta, c.name)).map((c) => c.name),
+      ...meta.cells ? [CELLS_FIELD] : [],
       ...meta.links.map((l) => l.name),
       ...meta.links.filter((l) => l.kind === "toMany").map((l) => `${l.name}Aggregate`)
     ];
@@ -3047,7 +4344,7 @@ var OperationLowerer = class {
   slot(name, input, table) {
     const variable = this.variables.get(name);
     if (!variable || variable.type.kind !== "inputRef" || variable.type.input !== input || variable.type.table !== table) {
-      fail(`variable $${name} must be declared as the ${input} input type for table '${table}'`, "slot-mismatch");
+      fail2(`variable $${name} must be declared as the ${input} input type for table '${table}'`, "slot-mismatch");
     }
     return name;
   }
@@ -3072,14 +4369,14 @@ var OperationLowerer = class {
         const items = node.values.map((item) => {
           const lowered = this.lowerValue(item);
           if (lowered.kind !== "literal" || Array.isArray(lowered.value)) {
-            fail("list literals must contain scalar literals only \u2014 pass the whole list as a variable instead", "unsupported-literal");
+            fail2("list literals must contain scalar literals only \u2014 pass the whole list as a variable instead", "unsupported-literal");
           }
           return lowered.value;
         });
         return { kind: "literal", value: items };
       }
       case Kind.OBJECT:
-        fail("literal JSON objects are not supported in documents \u2014 pass the value via a variable", "unsupported-literal");
+        fail2("literal JSON objects are not supported in documents \u2014 pass the value via a variable", "unsupported-literal");
     }
   }
   // -------------------------------------------------------------------------
@@ -3089,7 +4386,7 @@ var OperationLowerer = class {
     if (node.kind === Kind.VARIABLE) {
       return { kind: "dynamicFilter", slot: this.slot(node.name.value, "boolExp", table) };
     }
-    if (node.kind !== Kind.OBJECT) fail(`a boolean expression on '${table}' must be an object or a variable`, "invalid-boolexp");
+    if (node.kind !== Kind.OBJECT) fail2(`a boolean expression on '${table}' must be an object or a variable`, "invalid-boolexp");
     const operands = [];
     for (const field of node.fields) {
       const key = field.name.value;
@@ -3120,45 +4417,45 @@ var OperationLowerer = class {
           continue;
         }
       }
-      fail(`unknown field '${key}' in a boolean expression on '${table}'`, "unknown-column", this.fieldCandidates(table));
+      fail2(`unknown field '${key}' in a boolean expression on '${table}'`, "unknown-column", this.fieldCandidates(table));
     }
     if (operands.length === 0) return CONST_TRUE;
     return operands.length === 1 ? operands[0] : { kind: "and", operands };
   }
   lowerComparison(node, column, table) {
     if (node.kind !== Kind.OBJECT) {
-      fail(`comparison on '${table}.${column}' must be an object like { _eq: \u2026 }`, "invalid-comparison", Object.keys(BOOLEXP_OPS));
+      fail2(`comparison on '${table}.${column}' must be an object like { _eq: \u2026 }`, "invalid-comparison", Object.keys(BOOLEXP_OPS));
     }
     return node.fields.map((field) => {
       const op = BOOLEXP_OPS[field.name.value];
       if (!op) {
-        fail(`unknown comparison operator '${field.name.value}' on '${table}.${column}'`, "unknown-operator", Object.keys(BOOLEXP_OPS));
+        fail2(`unknown comparison operator '${field.name.value}' on '${table}.${column}'`, "unknown-operator", Object.keys(BOOLEXP_OPS));
       }
       return { kind: "cmp", op, column, value: this.lowerValue(field.value) };
     });
   }
   /** Hasura aggregation predicate: `{ count: { predicate: { _gt: 2 }, filter: {…} } }`. */
   lowerAggPredicate(node, link, target) {
-    if (node.kind !== Kind.OBJECT) fail(`aggregate predicate through '${link}' must be an object`, "invalid-agg-predicate");
+    if (node.kind !== Kind.OBJECT) fail2(`aggregate predicate through '${link}' must be an object`, "invalid-agg-predicate");
     const countField = node.fields.find((f) => f.name.value === "count");
     if (!countField || node.fields.length !== 1) {
-      fail(`aggregate predicates support { count: \u2026 } only in v2.0 (through '${link}')`, "invalid-agg-predicate", ["count"]);
+      fail2(`aggregate predicates support { count: \u2026 } only in v2.0 (through '${link}')`, "invalid-agg-predicate", ["count"]);
     }
-    if (countField.value.kind !== Kind.OBJECT) fail(`count predicate through '${link}' must be an object`, "invalid-agg-predicate");
+    if (countField.value.kind !== Kind.OBJECT) fail2(`count predicate through '${link}' must be an object`, "invalid-agg-predicate");
     let predicate;
     let where;
     for (const field of countField.value.fields) {
       if (field.name.value === "predicate") {
         if (field.value.kind !== Kind.OBJECT || field.value.fields.length !== 1) {
-          fail(`count predicate through '${link}' needs exactly one operator`, "invalid-agg-predicate", [...AGG_PREDICATE_OPS]);
+          fail2(`count predicate through '${link}' needs exactly one operator`, "invalid-agg-predicate", [...AGG_PREDICATE_OPS]);
         }
         const opField = field.value.fields[0];
         const opName = opField.name.value;
         if (!AGG_PREDICATE_OPS.includes(opName)) {
-          fail(`aggregate count predicates support ${AGG_PREDICATE_OPS.join("/")} only, got '${opName}'`, "invalid-agg-predicate");
+          fail2(`aggregate count predicates support ${AGG_PREDICATE_OPS.join("/")} only, got '${opName}'`, "invalid-agg-predicate");
         }
         if (opField.value.kind !== Kind.INT) {
-          fail(`aggregate count predicate value must be an integer literal`, "invalid-agg-predicate");
+          fail2(`aggregate count predicate value must be an integer literal`, "invalid-agg-predicate");
         }
         predicate = { op: opName.slice(1), value: Number(opField.value.value) };
         continue;
@@ -3167,9 +4464,9 @@ var OperationLowerer = class {
         where = this.lowerBoolExp(field.value, target);
         continue;
       }
-      fail(`unknown key '${field.name.value}' in a count predicate`, "invalid-agg-predicate", ["predicate", "filter"]);
+      fail2(`unknown key '${field.name.value}' in a count predicate`, "invalid-agg-predicate", ["predicate", "filter"]);
     }
-    if (!predicate) fail(`count predicate through '${link}' needs a { predicate: { _gt: n } }`, "invalid-agg-predicate");
+    if (!predicate) fail2(`count predicate through '${link}' needs a { predicate: { _gt: n } }`, "invalid-agg-predicate");
     return { kind: "aggPredicate", link, fn: "count", op: predicate.op, value: predicate.value, ...where ? { where } : {} };
   }
   lowerOrderBy(node, table) {
@@ -3179,7 +4476,7 @@ var OperationLowerer = class {
     const items = node.kind === Kind.LIST ? node.values : [node];
     const lowered = [];
     for (const item of items) {
-      if (item.kind !== Kind.OBJECT) fail(`orderBy entries on '${table}' must be objects`, "invalid-orderby");
+      if (item.kind !== Kind.OBJECT) fail2(`orderBy entries on '${table}' must be objects`, "invalid-orderby");
       for (const field of item.fields) {
         const key = field.name.value;
         const column = this.column(table, key);
@@ -3190,25 +4487,25 @@ var OperationLowerer = class {
         const link = this.link(table, key);
         if (link && link.kind !== "toMany") {
           if (field.value.kind !== Kind.OBJECT || field.value.fields.length !== 1) {
-            fail(`orderBy through '${key}' needs exactly one target column`, "invalid-orderby");
+            fail2(`orderBy through '${key}' needs exactly one target column`, "invalid-orderby");
           }
           const inner = field.value.fields[0];
           const targetColumn = this.column(link.target, inner.name.value);
           if (!targetColumn) {
-            fail(`unknown column '${inner.name.value}' on '${link.target}' in orderBy`, "unknown-column", this.meta(link.target).columns.map((c) => c.name));
+            fail2(`unknown column '${inner.name.value}' on '${link.target}' in orderBy`, "unknown-column", this.meta(link.target).columns.map((c) => c.name));
           }
           lowered.push({ kind: "column", column: inner.name.value, link: key, ...this.lowerDirection(inner.value, link.target, inner.name.value) });
           continue;
         }
-        fail(`unknown orderBy key '${key}' on '${table}' (to-one links only)`, "invalid-orderby", this.fieldCandidates(table));
+        fail2(`unknown orderBy key '${key}' on '${table}' (to-one links only)`, "invalid-orderby", this.fieldCandidates(table));
       }
     }
     return lowered;
   }
   lowerDirection(node, table, column) {
-    if (node.kind !== Kind.ENUM) fail(`orderBy direction on '${table}.${column}' must be a direction enum`, "invalid-orderby", Object.keys(ORDER_DIRECTIONS));
+    if (node.kind !== Kind.ENUM) fail2(`orderBy direction on '${table}.${column}' must be a direction enum`, "invalid-orderby", Object.keys(ORDER_DIRECTIONS));
     const direction = ORDER_DIRECTIONS[node.value];
-    if (!direction) fail(`unknown orderBy direction '${node.value}'`, "invalid-orderby", Object.keys(ORDER_DIRECTIONS));
+    if (!direction) fail2(`unknown orderBy direction '${node.value}'`, "invalid-orderby", Object.keys(ORDER_DIRECTIONS));
     return direction.nulls ? { direction: direction.direction, nulls: direction.nulls } : { direction: direction.direction };
   }
   lowerDistinctOn(node, table) {
@@ -3217,9 +4514,9 @@ var OperationLowerer = class {
     }
     const items = node.kind === Kind.LIST ? node.values : [node];
     return items.map((item) => {
-      if (item.kind !== Kind.ENUM) fail(`distinctOn entries on '${table}' must be select-column enum values`, "invalid-distinct-on");
+      if (item.kind !== Kind.ENUM) fail2(`distinctOn entries on '${table}' must be select-column enum values`, "invalid-distinct-on");
       if (!this.column(table, item.value)) {
-        fail(`unknown distinctOn column '${item.value}' on '${table}'`, "unknown-column", this.meta(table).columns.map((c) => c.name));
+        fail2(`unknown distinctOn column '${item.value}' on '${table}'`, "unknown-column", this.meta(table).columns.map((c) => c.name));
       }
       return item.value;
     });
@@ -3230,16 +4527,16 @@ var OperationLowerer = class {
     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");
+      if (value < 1) fail2("limit must be a positive integer", "invalid-limit");
       return { ...base, value: Math.min(value, MAX_LIMIT) };
     }
-    fail("limit must be an integer literal or a variable", "invalid-limit");
+    fail2("limit must be an integer literal or a variable", "invalid-limit");
   }
   lowerOffset(node) {
     if (!node) return void 0;
     if (node.kind === Kind.VARIABLE) return { variable: node.name.value };
     if (node.kind === Kind.INT) return { value: Number(node.value) };
-    fail("offset must be an integer literal or a variable", "invalid-offset");
+    fail2("offset must be an integer literal or a variable", "invalid-offset");
   }
   // -------------------------------------------------------------------------
   // Selections
@@ -3248,9 +4545,9 @@ var OperationLowerer = class {
     const meta = this.meta(table);
     const selection = { typename: meta.typename, columns: [], relations: [], aggregates: [] };
     for (const node of selectionSet.selections) {
-      if (node.kind !== Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+      if (node.kind !== Kind.FIELD) fail2("fragments must be flattened before lowering", "internal");
       if (node.directives && node.directives.length > 0) {
-        fail(`@include/@skip are supported on root fields only ('${node.name.value}' is nested)`, "nested-directive");
+        fail2(`@include/@skip are supported on root fields only ('${node.name.value}' is nested)`, "nested-directive");
       }
       const name = node.name.value;
       if (name === "__typename") continue;
@@ -3258,14 +4555,19 @@ var OperationLowerer = class {
       const column = this.column(table, name);
       if (column) {
         if (node.arguments !== void 0 && node.arguments.length > 0 || node.selectionSet !== void 0) {
-          fail(`column '${table}.${name}' takes no arguments or sub-selection`, "invalid-selection");
+          fail2(`column '${table}.${name}' takes no arguments or sub-selection`, "invalid-selection");
         }
         selection.columns.push({ alias, column: name });
         continue;
       }
+      if (name === CELLS_FIELD && meta.cells) {
+        if (selection.cells) fail2(`'${CELLS_FIELD}' may be selected once per object`, "invalid-selection");
+        selection.cells = this.lowerCells(node, table, alias);
+        continue;
+      }
       const link = this.link(table, name);
       if (link) {
-        if (!node.selectionSet) fail(`link '${table}.${name}' needs a selection set`, "invalid-selection");
+        if (!node.selectionSet) fail2(`link '${table}.${name}' needs a selection set`, "invalid-selection");
         const relation = {
           alias,
           link: name,
@@ -3284,7 +4586,7 @@ var OperationLowerer = class {
             if (offset) relation.offset = offset;
           }
         } else if (node.arguments && node.arguments.length > 0) {
-          fail(`to-one link '${table}.${name}' takes no arguments`, "invalid-selection");
+          fail2(`to-one link '${table}.${name}' takes no arguments`, "invalid-selection");
         }
         selection.relations.push(relation);
         continue;
@@ -3292,7 +4594,7 @@ var OperationLowerer = class {
       if (name.endsWith("Aggregate")) {
         const aggLink = this.link(table, name.slice(0, -"Aggregate".length));
         if (aggLink && aggLink.kind === "toMany") {
-          if (!node.selectionSet) fail(`'${name}' needs a selection set`, "invalid-selection");
+          if (!node.selectionSet) fail2(`'${name}' needs a selection set`, "invalid-selection");
           assertKnownArgs(node, ["where"]);
           const whereArg = argsByName(node).get("where");
           const aggregate = this.lowerAggregateSelection(node.selectionSet, aggLink.target);
@@ -3305,70 +4607,182 @@ var OperationLowerer = class {
           continue;
         }
       }
-      fail(`unknown field '${name}' on '${table}'`, "unknown-field", this.fieldCandidates(table));
+      fail2(`unknown field '${name}' on '${table}'`, "unknown-field", this.fieldCandidates(table));
+    }
+    return selection;
+  }
+  /**
+   * `cells { <column> { at by … } }` — typed per-cell metadata. Plain tables
+   * offer `at`/`by`; resolved tables add the winning `source` and newer
+   * `conflicts { source at value }`.
+   */
+  lowerCells(node, table, alias) {
+    const meta = this.meta(table);
+    const cells = meta.cells ?? {};
+    if (node.arguments && node.arguments.length > 0) fail2(`'${CELLS_FIELD}' takes no arguments`, "invalid-selection");
+    if (!node.selectionSet) fail2(`'${CELLS_FIELD}' needs a selection set`, "invalid-selection");
+    const fields = [];
+    for (const cellNode of fieldNodes(node.selectionSet)) {
+      const column = cellNode.name.value;
+      const parts = cells[column];
+      if (!parts || parts.at === void 0 && parts.source === void 0) {
+        fail2(`unknown cell '${column}' on '${table}'`, "unknown-field", Object.keys(cells));
+      }
+      if (!cellNode.selectionSet) fail2(`cell '${column}' needs a selection set`, "invalid-selection");
+      const resolved = parts.source !== void 0;
+      const allowed = resolved ? ["source", "at", "by", "conflicts"] : ["at", "by"];
+      const selected = [];
+      for (const partNode of fieldNodes(cellNode.selectionSet)) {
+        const part = partNode.name.value;
+        if (!allowed.includes(part)) fail2(`unknown field '${part}' on cell '${column}'`, "unknown-field", allowed);
+        const partAlias = partNode.alias?.value ?? part;
+        if (part !== "conflicts") {
+          if (partNode.selectionSet) fail2(`cell field '${part}' takes no sub-selection`, "invalid-selection");
+          selected.push({ alias: partAlias, part });
+          continue;
+        }
+        if (!partNode.selectionSet) fail2(`'conflicts' needs a selection set`, "invalid-selection");
+        const conflictFields = fieldNodes(partNode.selectionSet).map((fieldNode) => {
+          const field = fieldNode.name.value;
+          if (field !== "source" && field !== "at" && field !== "value") fail2(`unknown field '${field}' on a cell conflict`, "unknown-field", ["source", "at", "value"]);
+          return { alias: fieldNode.alias?.value ?? field, field };
+        });
+        selected.push({ alias: partAlias, part: "conflicts", fields: conflictFields, typename: CELL_TYPENAMES.conflict });
+      }
+      fields.push({
+        alias: cellNode.alias?.value ?? column,
+        column,
+        typename: resolved ? CELL_TYPENAMES.resolved : CELL_TYPENAMES.stamp,
+        parts: selected
+      });
+    }
+    return { alias, typename: cellsTypename(meta.typename), fields };
+  }
+  /** The `{ aggregate { count sum {…} avg {…} } nodes {…} }` block shared by roots and relations. */
+  lowerAggregateSelection(selectionSet, table) {
+    const result = {};
+    let sawAggregate = false;
+    for (const node of aggregateBlockFields(selectionSet)) {
+      const name = node.name.value;
+      if (name === "nodes") {
+        if (!node.selectionSet) fail2("'nodes' needs a selection set", "invalid-aggregate");
+        result.nodes = this.lowerSelection(node.selectionSet, table);
+        continue;
+      }
+      if (name !== "aggregate") fail2(`unknown aggregate field '${name}'`, "invalid-aggregate", ["aggregate", "nodes"]);
+      if (sawAggregate) fail2("one aggregate block per field \u2014 alias the root instead", "invalid-aggregate");
+      sawAggregate = true;
+      if (!node.selectionSet) fail2("'aggregate' needs a selection set", "invalid-aggregate");
+      Object.assign(result, this.lowerAggregateFields(node.selectionSet, table));
+    }
+    if (!sawAggregate && !result.nodes) fail2("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) fail2("one key block per grouped aggregate", "invalid-aggregate");
+        sawKey = true;
+        if (!node.selectionSet) fail2("'key' needs a selection set", "invalid-aggregate");
+        result.key = this.lowerGroupKeySelection(node.selectionSet, table, groupColumns);
+        continue;
+      }
+      if (name === "nodes") {
+        fail2("'nodes' is not available on a grouped aggregate \u2014 query the rows separately", "invalid-aggregate", ["key", "aggregate"]);
+      }
+      if (name !== "aggregate") fail2(`unknown grouped-aggregate field '${name}'`, "invalid-aggregate", ["key", "aggregate"]);
+      if (sawAggregate) fail2("one aggregate block per field \u2014 alias the root instead", "invalid-aggregate");
+      sawAggregate = true;
+      if (!node.selectionSet) fail2("'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) {
+      fail2(
+        "grouped aggregate needs at least one key column or an aggregate \u2014 a block selecting only __typename produces nothing",
+        "invalid-aggregate",
+        ["key", "aggregate"]
+      );
     }
-    return selection;
+    return result;
   }
-  /** The `{ aggregate { count sum {…} avg {…} } nodes {…} }` block shared by roots and relations. */
-  lowerAggregateSelection(selectionSet, table) {
-    const result = {};
-    let sawAggregate = false;
+  /**
+   * `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");
+      if (node.kind !== Kind.FIELD) fail2("fragments must be flattened before lowering", "internal");
       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);
-        continue;
+      if (!this.column(table, name)) {
+        fail2(`unknown key column '${name}' on '${table}'`, "unknown-column", [...groupColumns]);
       }
-      if (name !== "aggregate") fail(`unknown aggregate field '${name}'`, "invalid-aggregate", ["aggregate", "nodes"]);
-      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;
+      if (!groupColumns.has(name)) {
+        fail2(
+          `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) fail2("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) fail2(`'${aggName}' needs a column selection`, "invalid-aggregate");
+        const columns = [];
+        for (const columnField of aggField.selectionSet.selections) {
+          if (columnField.kind !== Kind.FIELD) fail2("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)) {
+            fail2(
+              `'${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;
       }
+      fail2(`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;
   }
   // -------------------------------------------------------------------------
@@ -3377,32 +4791,65 @@ var OperationLowerer = class {
   lowerRoots(operation, kind) {
     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.kind !== Kind.FIELD) fail2("fragments are not supported at the operation root", "invalid-root");
+      if (node.selectionSet) visit(node.selectionSet, {
+        Directive(directive) {
+          if (directive.name.value === "assertAffectedRows") {
+            fail2("@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 lowered = kind === "query" ? this.lowerQueryRoot(node) : this.lowerMutationRoot(node);
+      const meta = this.meta(lowered.table);
+      const root = kind === "query" ? applyPrefetchDirectives({ node, root: lowered, meta }) : applyWritebackDirectives({ node, root: lowered, meta });
+      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");
+    if (roots.length === 0) fail2("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) {
+      fail2("@assertAffectedRows is supported once per mutation root", "invalid-affected-row-assertion");
+    }
+    if (node.directives?.some((directive) => ["include", "skip"].includes(directive.name.value))) {
+      fail2("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) {
+      fail2("@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) {
+      fail2("@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 (SOURCE_DIRECTIVES.has(name)) continue;
       if (name !== "include" && name !== "skip") {
-        fail(`directive @${name} is not supported on fields`, "unknown-directive", ["include", "skip"]);
+        fail2(`directive @${name} is not supported on fields`, "unknown-directive", ["include", "skip"]);
       }
       const ifArg = directive.arguments?.find((a) => a.name.value === "if");
-      if (!ifArg) fail(`@${name} needs an if: argument`, "invalid-directive");
+      if (!ifArg) fail2(`@${name} needs an if: argument`, "invalid-directive");
       if (ifArg.value.kind === Kind.BOOLEAN) {
         const keep = name === "include" ? ifArg.value.value : !ifArg.value.value;
         if (!keep) omit = true;
         continue;
       }
-      if (ifArg.value.kind !== Kind.VARIABLE) fail(`@${name}(if:) must be a boolean literal or variable`, "invalid-directive");
-      if (includeIf) fail("at most one of @include/@skip per root field", "invalid-directive");
+      if (ifArg.value.kind !== Kind.VARIABLE) fail2(`@${name}(if:) must be a boolean literal or variable`, "invalid-directive");
+      if (includeIf) fail2("at most one of @include/@skip per root field", "invalid-directive");
       includeIf = { variable: ifArg.value.name.value, negated: name === "skip" };
     }
     return omit ? { omit: true } : { includeIf, omit: false };
@@ -3411,12 +4858,12 @@ var OperationLowerer = class {
     const name = node.name.value;
     const alias = node.alias?.value ?? name;
     const rootInfo = this.ctx.queryRoots.get(name);
-    if (!rootInfo) fail(`unknown query root '${name}'`, "unknown-root", [...this.ctx.queryRoots.keys()]);
+    if (!rootInfo) fail2(`unknown query root '${name}'`, "unknown-root", [...this.ctx.queryRoots.keys()]);
     const { table } = rootInfo;
     const args = argsByName(node);
     if (rootInfo.kind === "select") {
       assertKnownArgs(node, ["where", "orderBy", "distinctOn", "limit", "offset"]);
-      if (!node.selectionSet) fail(`'${name}' needs a selection set`, "invalid-selection");
+      if (!node.selectionSet) fail2(`'${name}' needs a selection set`, "invalid-selection");
       const where = args.get("where");
       const orderBy = args.get("orderBy");
       const distinctOn = args.get("distinctOn");
@@ -3435,12 +4882,15 @@ var OperationLowerer = class {
       };
     }
     if (rootInfo.kind === "byPk") {
-      if (!node.selectionSet) fail(`'${name}' needs a selection set`, "invalid-selection");
+      if (!node.selectionSet) fail2(`'${name}' needs a selection set`, "invalid-selection");
       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");
+    if (!node.selectionSet) fail2(`'${name}' needs a selection set`, "invalid-selection");
     const whereArg = args.get("where");
     const aggregate = this.lowerAggregateSelection(node.selectionSet, table);
     return {
@@ -3451,6 +4901,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) fail2(`'${node.name.value}' needs a selection set`, "invalid-selection");
+    const args = argsByName(node);
+    const groupByArg = args.get("groupBy");
+    if (!groupByArg) fail2(`'${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) {
+      fail2(
+        `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) fail2(`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) {
+        fail2(`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") {
+          fail2(`unknown groupBy field '${key}' on '${table}'`, "invalid-group-by", ["column", "bucket"]);
+        }
+      }
+      const columnNode = fields.get("column");
+      if (!columnNode) fail2(`groupBy entries on '${table}' need a 'column'`, "invalid-group-by");
+      if (columnNode.kind !== Kind.ENUM) {
+        fail2(`groupBy column on '${table}' must be a group-by column enum value`, "invalid-group-by");
+      }
+      const column = this.column(table, columnNode.value);
+      if (!column) {
+        fail2(`unknown groupBy column '${columnNode.value}' on '${table}'`, "unknown-column", this.meta(table).columns.map((c) => c.name));
+      }
+      if (column.type === "jsonb") {
+        fail2(`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) {
+          fail2(`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) {
+          fail2(`unknown DateBucket '${bucketNode.value}'`, "invalid-group-by", Object.keys(DATE_BUCKET_BY_ENUM));
+        }
+        if (typeof column.type !== "string" || !BUCKETABLE_TYPES.has(column.type)) {
+          fail2(
+            `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)) {
+        fail2(`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) fail2("limit must be a positive integer", "invalid-limit");
+      return { ...base, value: Math.min(value, MAX_GROUPS) };
+    }
+    fail2("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);
@@ -3458,7 +5010,7 @@ var OperationLowerer = class {
     assertKnownArgs(node, meta.primaryKey);
     return meta.primaryKey.map((column) => {
       const arg = args.get(column);
-      if (!arg) fail(`'${node.name.value}' is missing primary-key argument '${column}'`, "missing-pk-argument", meta.primaryKey);
+      if (!arg) fail2(`'${node.name.value}' is missing primary-key argument '${column}'`, "missing-pk-argument", meta.primaryKey);
       return { column, value: this.lowerValue(arg.value) };
     });
   }
@@ -3469,19 +5021,22 @@ var OperationLowerer = class {
     const name = node.name.value;
     const alias = node.alias?.value ?? name;
     const rootInfo = this.ctx.mutationRoots.get(name);
-    if (!rootInfo) fail(`unknown mutation root '${name}'`, "unknown-root", [...this.ctx.mutationRoots.keys()]);
+    if (!rootInfo) fail2(`unknown mutation root '${name}'`, "unknown-root", [...this.ctx.mutationRoots.keys()]);
     if (rootInfo.op === "cowOverride" || rootInfo.op === "cowRevert") {
       return this.lowerCowRoot(node, rootInfo);
     }
+    if (rootInfo.op === "resolvedWrite") {
+      return this.lowerResolvedRoot(node, rootInfo);
+    }
     const { op, table } = rootInfo;
     const args = argsByName(node);
-    if (!node.selectionSet) fail(`'${name}' needs a selection set`, "invalid-selection");
+    if (!node.selectionSet) fail2(`'${name}' needs a selection set`, "invalid-selection");
     const base = { kind: "mutation", op, alias, table, pinnedColumns: [], affectedRows: false };
     switch (op) {
       case "insert": {
         assertKnownArgs(node, ["objects", "onConflict"]);
         const objects = args.get("objects");
-        if (!objects) fail(`'${name}' needs objects:`, "missing-argument");
+        if (!objects) fail2(`'${name}' needs objects:`, "missing-argument");
         const response = this.lowerMutationResponse(node.selectionSet, table);
         return {
           ...base,
@@ -3493,7 +5048,7 @@ var OperationLowerer = class {
       case "insertOne": {
         assertKnownArgs(node, ["object", "onConflict"]);
         const object = args.get("object");
-        if (!object) fail(`'${name}' needs object:`, "missing-argument");
+        if (!object) fail2(`'${name}' needs object:`, "missing-argument");
         return {
           ...base,
           objects: this.lowerInsertObjects(object.value, table, { list: false }),
@@ -3504,7 +5059,7 @@ var OperationLowerer = class {
       case "update": {
         assertKnownArgs(node, ["where", "_set", "_append", "_inc"]);
         const where = args.get("where");
-        if (!where) fail(`'${name}' needs where: (bulk updates without a filter are not allowed)`, "missing-argument");
+        if (!where) fail2(`'${name}' needs where: (bulk updates without a filter are not allowed)`, "missing-argument");
         return {
           ...base,
           ...this.lowerMutationResponse(node.selectionSet, table),
@@ -3515,7 +5070,7 @@ var OperationLowerer = class {
       case "updateByPk": {
         assertKnownArgs(node, ["pkColumns", "_set", "_append", "_inc"]);
         const pkColumns = args.get("pkColumns");
-        if (!pkColumns) fail(`'${name}' needs pkColumns:`, "missing-argument");
+        if (!pkColumns) fail2(`'${name}' needs pkColumns:`, "missing-argument");
         return {
           ...base,
           pk: this.lowerPkColumnsArg(pkColumns.value, table),
@@ -3526,7 +5081,7 @@ var OperationLowerer = class {
       case "delete": {
         assertKnownArgs(node, ["where"]);
         const where = args.get("where");
-        if (!where) fail(`'${name}' needs where: (bulk deletes without a filter are not allowed)`, "missing-argument");
+        if (!where) fail2(`'${name}' needs where: (bulk deletes without a filter are not allowed)`, "missing-argument");
         return {
           ...base,
           ...this.lowerMutationResponse(node.selectionSet, table),
@@ -3553,11 +5108,11 @@ var OperationLowerer = class {
     const name = node.name.value;
     const alias = node.alias?.value ?? name;
     const { table } = rootInfo;
-    if (!node.selectionSet) fail(`'${name}' needs a selection set`, "invalid-selection");
+    if (!node.selectionSet) fail2(`'${name}' needs a selection set`, "invalid-selection");
     const meta = this.meta(table);
     const args = argsByName(node);
     const pkArg = args.get(rootInfo.pk);
-    if (!pkArg) fail(`'${name}' is missing primary-key argument '${rootInfo.pk}'`, "missing-pk-argument", [rootInfo.pk]);
+    if (!pkArg) fail2(`'${name}' is missing primary-key argument '${rootInfo.pk}'`, "missing-pk-argument", [rootInfo.pk]);
     const pk = [{ column: rootInfo.pk, value: this.lowerValue(pkArg.value) }];
     const base = {
       kind: "mutation",
@@ -3578,24 +5133,78 @@ var OperationLowerer = class {
     const entries = rootInfo.set.map((column) => {
       const arg = args.get(column);
       if (!arg) {
-        fail(
+        fail2(
           `'${name}' is missing set argument '${column}' \u2014 a cow override writes every declared set column (pass null to clear a nullable one)`,
           "missing-argument",
           [...rootInfo.set]
         );
       }
       if (!meta.settable.includes(column)) {
-        fail(`column '${table}.${column}' is not updatable (pinned by the write policy or deprecated)`, "column-not-settable", meta.settable);
+        fail2(`column '${table}.${column}' is not updatable (pinned by the write policy or deprecated)`, "column-not-settable", meta.settable);
       }
       return { column, value: this.lowerValue(arg.value) };
     });
     return { ...base, set: { entries }, cowCopyColumns: [...rootInfo.copyColumns] };
   }
+  /**
+   * Resolved-table roots: insertOne(object), updateByPk(pkColumns, _set),
+   * deleteByPk(pk…), revertByPk(pkColumns, columns). The executor writes only
+   * the touched cells into the manual source; `returning` reads the view.
+   */
+  lowerResolvedRoot(node, rootInfo) {
+    const name = node.name.value;
+    const alias = node.alias?.value ?? name;
+    const { table, action } = rootInfo;
+    if (!node.selectionSet) fail2(`'${name}' needs a selection set`, "invalid-selection");
+    const args = argsByName(node);
+    const base = {
+      kind: "mutation",
+      op: "resolvedWrite",
+      resolvedAction: action,
+      alias,
+      table,
+      pinnedColumns: [],
+      affectedRows: false,
+      returning: this.lowerSelection(node.selectionSet, table)
+    };
+    switch (action) {
+      case "insert": {
+        assertKnownArgs(node, ["object"]);
+        const object = args.get("object");
+        if (!object) fail2(`'${name}' needs object:`, "missing-argument");
+        return { ...base, objects: this.lowerInsertObjects(object.value, table, { list: false }) };
+      }
+      case "update": {
+        assertKnownArgs(node, ["pkColumns", "_set"]);
+        const pkColumns = args.get("pkColumns");
+        if (!pkColumns || !args.get("_set")) fail2(`'${name}' needs pkColumns: and _set:`, "missing-argument");
+        return { ...base, pk: this.lowerPkColumnsArg(pkColumns.value, table), ...this.lowerWriteValues(args, table) };
+      }
+      case "delete":
+        return { ...base, pk: this.lowerPkArgs(node, table) };
+      case "revert": {
+        assertKnownArgs(node, ["pkColumns", "columns"]);
+        const pkColumns = args.get("pkColumns");
+        const columns = args.get("columns");
+        if (!pkColumns || !columns) fail2(`'${name}' needs pkColumns: and columns:`, "missing-argument");
+        const items = columns.value.kind === Kind.LIST ? columns.value.values : [columns.value];
+        const meta = this.meta(table);
+        const revertColumns = items.map((item) => {
+          if (item.kind !== Kind.ENUM || !meta.settable.includes(item.value)) {
+            fail2(`'${name}' columns: must list update-column enum values written in the document`, "invalid-revert-columns", meta.settable);
+          }
+          return item.value;
+        });
+        if (revertColumns.length === 0) fail2(`'${name}' columns: must name at least one column`, "invalid-revert-columns");
+        return { ...base, pk: this.lowerPkColumnsArg(pkColumns.value, table), revertColumns: [...new Set(revertColumns)] };
+      }
+    }
+  }
   lowerMutationResponse(selectionSet, table) {
     let affectedRows = false;
     let returning = null;
     for (const node of selectionSet.selections) {
-      if (node.kind !== Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+      if (node.kind !== Kind.FIELD) fail2("fragments must be flattened before lowering", "internal");
       const name = node.name.value;
       if (name === "__typename") continue;
       if (name === "affectedRows") {
@@ -3603,34 +5212,34 @@ var OperationLowerer = class {
         continue;
       }
       if (name === "returning") {
-        if (!node.selectionSet) fail("'returning' needs a selection set", "invalid-selection");
+        if (!node.selectionSet) fail2("'returning' needs a selection set", "invalid-selection");
         returning = this.lowerSelection(node.selectionSet, table);
         continue;
       }
-      fail(`unknown mutation-response field '${name}'`, "invalid-selection", ["affectedRows", "returning"]);
+      fail2(`unknown mutation-response field '${name}'`, "invalid-selection", ["affectedRows", "returning"]);
     }
     return { affectedRows, returning };
   }
   lowerInsertObjects(node, table, { list }) {
     if (node.kind === Kind.VARIABLE) return { slot: this.slot(node.name.value, "insertInput", table) };
     if (list) {
-      if (node.kind !== Kind.LIST) fail(`objects: must be a list literal or a variable`, "invalid-insert");
+      if (node.kind !== Kind.LIST) fail2(`objects: must be a list literal or a variable`, "invalid-insert");
       return { rows: node.values.map((item) => this.lowerInsertRow(item, table)) };
     }
     return { rows: [this.lowerInsertRow(node, table)] };
   }
   lowerInsertRow(node, table) {
-    if (node.kind !== Kind.OBJECT) fail(`insert rows on '${table}' must be objects`, "invalid-insert");
+    if (node.kind !== Kind.OBJECT) fail2(`insert rows on '${table}' must be objects`, "invalid-insert");
     const meta = this.meta(table);
     return node.fields.map((field) => {
       const key = field.name.value;
       if (this.link(table, key)) {
-        fail(`nested inserts are not supported in v2.0 \u2014 '${key}' is a link on '${table}'`, "nested-insert-unsupported");
+        fail2(`nested inserts are not supported in v2.0 \u2014 '${key}' is a link on '${table}'`, "nested-insert-unsupported");
       }
       if (!meta.insertable.includes(key)) {
         const column = this.column(table, key);
-        if (column) fail(`column '${table}.${key}' is not insertable (pinned by the write policy or deprecated)`, "column-not-insertable", meta.insertable);
-        fail(`unknown column '${key}' in an insert on '${table}'`, "unknown-column", meta.insertable);
+        if (column) fail2(`column '${table}.${key}' is not insertable (pinned by the write policy or deprecated)`, "column-not-insertable", meta.insertable);
+        fail2(`unknown column '${key}' in an insert on '${table}'`, "unknown-column", meta.insertable);
       }
       return { column: key, value: this.lowerValue(field.value) };
     });
@@ -3639,32 +5248,32 @@ var OperationLowerer = class {
     if (!arg) return {};
     const node = arg.value;
     if (node.kind === Kind.VARIABLE) return { onConflict: { slot: this.slot(node.name.value, "onConflict", table) } };
-    if (node.kind !== Kind.OBJECT) fail("onConflict: must be an object literal or a variable", "invalid-on-conflict");
+    if (node.kind !== Kind.OBJECT) fail2("onConflict: must be an object literal or a variable", "invalid-on-conflict");
     const meta = this.meta(table);
     let constraint;
     const updateColumns = [];
     for (const field of node.fields) {
       if (field.name.value === "constraint") {
-        if (field.value.kind !== Kind.ENUM) fail("onConflict.constraint must be a constraint enum value", "invalid-on-conflict");
+        if (field.value.kind !== Kind.ENUM) fail2("onConflict.constraint must be a constraint enum value", "invalid-on-conflict");
         constraint = field.value.value;
         continue;
       }
       if (field.name.value === "updateColumns") {
         const items = field.value.kind === Kind.LIST ? field.value.values : [field.value];
         for (const item of items) {
-          if (item.kind !== Kind.ENUM) fail("onConflict.updateColumns must be update-column enum values", "invalid-on-conflict");
+          if (item.kind !== Kind.ENUM) fail2("onConflict.updateColumns must be update-column enum values", "invalid-on-conflict");
           if (!meta.settable.includes(item.value)) {
-            fail(`onConflict.updateColumns: '${item.value}' is not updatable on '${table}'`, "invalid-on-conflict", meta.settable);
+            fail2(`onConflict.updateColumns: '${item.value}' is not updatable on '${table}'`, "invalid-on-conflict", meta.settable);
           }
           updateColumns.push(item.value);
         }
         continue;
       }
-      fail(`unknown onConflict key '${field.name.value}'`, "invalid-on-conflict", ["constraint", "updateColumns"]);
+      fail2(`unknown onConflict key '${field.name.value}'`, "invalid-on-conflict", ["constraint", "updateColumns"]);
     }
-    if (!constraint) fail("onConflict needs a constraint", "invalid-on-conflict", meta.constraints.map((c) => c.name));
+    if (!constraint) fail2("onConflict needs a constraint", "invalid-on-conflict", meta.constraints.map((c) => c.name));
     if (!meta.constraints.some((c) => c.name === constraint)) {
-      fail(`unknown constraint '${constraint}' on '${table}'`, "invalid-on-conflict", meta.constraints.map((c) => c.name));
+      fail2(`unknown constraint '${constraint}' on '${table}'`, "invalid-on-conflict", meta.constraints.map((c) => c.name));
     }
     return { onConflict: { constraint, updateColumns } };
   }
@@ -3682,36 +5291,36 @@ var OperationLowerer = class {
     const inc = args.get("_inc");
     if (inc) {
       if (inc.value.kind === Kind.VARIABLE) {
-        fail("_inc has no dynamic input type \u2014 inline the columns with variable leaf values", "invalid-inc");
+        fail2("_inc has no dynamic input type \u2014 inline the columns with variable leaf values", "invalid-inc");
       }
       const numeric4 = meta.columns.filter((c) => typeof c.type === "string" && NUMERIC_TYPES.has(c.type) && meta.settable.includes(c.name)).map((c) => c.name);
       result.inc = { entries: this.lowerColumnEntries(inc.value, table, numeric4, "_inc") };
     }
     if (!result.set && !result.append && !result.inc) {
-      fail(`an update on '${table}' needs at least one of _set/_append/_inc`, "missing-argument");
+      fail2(`an update on '${table}' needs at least one of _set/_append/_inc`, "missing-argument");
     }
     return result;
   }
   lowerColumnEntries(node, table, whitelist, argName) {
-    if (node.kind !== Kind.OBJECT) fail(`${argName} on '${table}' must be an object literal or a variable`, "invalid-write-values");
+    if (node.kind !== Kind.OBJECT) fail2(`${argName} on '${table}' must be an object literal or a variable`, "invalid-write-values");
     return node.fields.map((field) => {
       const key = field.name.value;
       if (!whitelist.includes(key)) {
-        fail(`${argName}: column '${key}' is not allowed on '${table}'`, "column-not-settable", [...whitelist]);
+        fail2(`${argName}: column '${key}' is not allowed on '${table}'`, "column-not-settable", [...whitelist]);
       }
       return { column: key, value: this.lowerValue(field.value) };
     });
   }
   lowerPkColumnsArg(node, table) {
-    if (node.kind !== Kind.OBJECT) fail(`pkColumns on '${table}' must be an object literal`, "invalid-pk-columns");
+    if (node.kind !== Kind.OBJECT) fail2(`pkColumns on '${table}' must be an object literal`, "invalid-pk-columns");
     const meta = this.meta(table);
     const provided = new Map(node.fields.map((field) => [field.name.value, field.value]));
     for (const key of provided.keys()) {
-      if (!meta.primaryKey.includes(key)) fail(`pkColumns: '${key}' is not a primary-key column of '${table}'`, "invalid-pk-columns", meta.primaryKey);
+      if (!meta.primaryKey.includes(key)) fail2(`pkColumns: '${key}' is not a primary-key column of '${table}'`, "invalid-pk-columns", meta.primaryKey);
     }
     return meta.primaryKey.map((column) => {
       const value = provided.get(column);
-      if (!value) fail(`pkColumns is missing '${column}'`, "invalid-pk-columns", meta.primaryKey);
+      if (!value) fail2(`pkColumns is missing '${column}'`, "invalid-pk-columns", meta.primaryKey);
       return { column, value: this.lowerValue(value) };
     });
   }
@@ -3720,6 +5329,19 @@ function lowerOperation({ restricted, ctx }) {
   const lowerer = new OperationLowerer(ctx, restricted);
   return lowerer.lowerRoots(restricted.definition, restricted.kind);
 }
+function isCellColumn(meta, name) {
+  if (!meta.cells) return false;
+  return Object.values(meta.cells).some((parts) => Object.values(parts).includes(name));
+}
+function fieldNodes(selectionSet) {
+  const out = [];
+  for (const node of selectionSet.selections) {
+    if (node.kind !== Kind.FIELD) fail2("fragments must be flattened before lowering", "internal");
+    if (node.directives && node.directives.length > 0) fail2(`@include/@skip are supported on root fields only ('${node.name.value}' is nested)`, "nested-directive");
+    if (node.name.value !== "__typename") out.push(node);
+  }
+  return out;
+}
 function parseSdl(sdl) {
   return buildSchema(sdl);
 }
@@ -3960,7 +5582,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,
@@ -3987,7 +5609,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)),
@@ -4096,15 +5718,6 @@ function columnWireType(column) {
   const notNull = column.primary_key === true || column.nullable === false;
   return notNull || base === "unknown" ? base : `${base} | null`;
 }
-
-// src/compiler/sql.ts
-var CLAIMS_SETTING = "request.jwt.claims";
-var CAPABILITIES_CLAIM_KEY = "capabilities";
-var quoteIdentifier = (name) => `"${name.replaceAll('"', '""')}"`;
-var quoteLiteral = (value) => `'${value.replaceAll("'", "''")}'`;
-var CLAIMS_SOURCE = `nullif(current_setting('${CLAIMS_SETTING}', true), '')::jsonb`;
-var claimExpression = (key) => `(${CLAIMS_SOURCE} ->> ${quoteLiteral(key)})`;
-var capabilityExpression = (key) => `coalesce(${CLAIMS_SOURCE} -> '${CAPABILITIES_CLAIM_KEY}' ? ${quoteLiteral(key)}, false)`;
 var identifierSchema = z.string().max(MAX_IDENTIFIER_LENGTH).regex(IDENTIFIER_PATTERN, "must be a lowercase identifier (a-z, 0-9, _)");
 var namespaceSchema = z.string().regex(NAMESPACE_PATTERN, "must be lowercase, start with a letter, and be at most 41 characters");
 var tableReferenceSchema = z.string().refine(
@@ -4187,12 +5800,12 @@ function castParts(cast) {
 
 // src/predicate/ast.ts
 var COMPARE_OPS = ["=", "!=", "<", "<=", ">", ">="];
-function walkPredicate(predicate, visit) {
-  visit(predicate);
+function walkPredicate(predicate, visit2) {
+  visit2(predicate);
   if (predicate.kind === "and" || predicate.kind === "or") {
-    for (const operand of predicate.operands) walkPredicate(operand, visit);
+    for (const operand of predicate.operands) walkPredicate(operand, visit2);
   }
-  if (predicate.kind === "not") walkPredicate(predicate.operand, visit);
+  if (predicate.kind === "not") walkPredicate(predicate.operand, visit2);
 }
 function predicateOperands(predicate) {
   const operands = [];
@@ -4221,7 +5834,7 @@ var OPERATOR_PATTERN2 = /^(!=|<=|>=|<>|=|<|>)/;
 var IDENTIFIER_START2 = /[a-z_]/;
 var IDENTIFIER_CHAR2 = /[a-z0-9_.-]/;
 var NUMBER_PATTERN2 = /^-?\d+(\.\d+)?/;
-function tokenize2(source) {
+function tokenize3(source) {
   const tokens = [];
   let position = 0;
   while (position < source.length) {
@@ -4295,7 +5908,7 @@ function readString2(source, start) {
   }
   throw new PredicateParseError("unterminated string literal", start);
 }
-var Parser2 = class {
+var Parser3 = class {
   constructor(tokens) {
     this.tokens = tokens;
   }
@@ -4427,7 +6040,7 @@ var Parser2 = class {
 function parsePredicate(source) {
   const trimmed = source.trim();
   if (trimmed.length === 0) throw new PredicateParseError("empty predicate", 0);
-  return { source: trimmed, ast: new Parser2(tokenize2(trimmed)).parse() };
+  return { source: trimmed, ast: new Parser3(tokenize3(trimmed)).parse() };
 }
 
 // src/schema/predicates.ts
@@ -5149,6 +6762,88 @@ function snapshotTableNames(snapshot, schema) {
   return Object.values(tables).filter((entry) => entry.schema === schema).map((entry) => entry.name);
 }
 
+// src/engine/materialized-refresh.ts
+function materializedRefreshFunctions(canonical) {
+  const schema = ormSchemaName(canonical.namespace);
+  const functions = /* @__PURE__ */ new Map();
+  for (const view of canonical.views ?? []) {
+    const materialized = view.resolved?.materialized;
+    if (!materialized) continue;
+    const table = canonical.tables.find((candidate) => candidate.table === materialized.table);
+    const pk = view.primaryKey ?? [];
+    if (!table || pk.length === 0) {
+      throw new OrmDefinitionError(`materialized resolved table '${view.view}' needs its table and primary key`);
+    }
+    functions.set(view.view, refreshFunctionSql({
+      schema,
+      name: view.view,
+      table: materialized.table,
+      compute: materialized.compute,
+      columns: table.columns.map((column) => column.columnName),
+      pk
+    }));
+  }
+  return functions;
+}
+function refreshFunctionSql({ schema, name, table, compute, columns, pk }) {
+  const fn = `${quoteIdentifier(schema)}.${quoteIdentifier(materializedRefreshFunctionName(name))}`;
+  const target = `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+  const source = `${quoteIdentifier(schema)}.${quoteIdentifier(compute)}`;
+  const list = columns.map(quoteIdentifier).join(", ");
+  const others = columns.filter((column) => !pk.includes(column));
+  const keys = pk.map(quoteIdentifier).join(", ");
+  const matches = pk.map((column) => `c.${quoteIdentifier(column)} = m.${quoteIdentifier(column)}`).join(" AND ");
+  const onConflict = others.length === 0 ? "DO NOTHING" : `DO UPDATE SET ${others.map((column) => `${quoteIdentifier(column)} = EXCLUDED.${quoteIdentifier(column)}`).join(", ")}
+      WHERE (${others.map((column) => `m.${quoteIdentifier(column)}`).join(", ")}) IS DISTINCT FROM (${others.map((column) => `EXCLUDED.${quoteIdentifier(column)}`).join(", ")})`;
+  const lockKey = quoteLiteral(materializeLockKey(schema, name));
+  return `CREATE OR REPLACE FUNCTION ${fn}(wait boolean DEFAULT false)
+RETURNS TABLE(upserted bigint, deleted bigint, locked boolean)
+LANGUAGE plpgsql
+SECURITY INVOKER
+SET search_path = pg_catalog, pg_temp
+AS $orm_refresh$
+#variable_conflict use_column
+DECLARE
+  caller_claims text := current_setting('request.jwt.claims', true);
+BEGIN
+  IF wait THEN
+    PERFORM pg_advisory_xact_lock(hashtext(${lockKey}));
+  ELSIF NOT pg_try_advisory_xact_lock(hashtext(${lockKey})) THEN
+    RETURN QUERY SELECT 0::bigint, 0::bigint, false;
+    RETURN;
+  END IF;
+  PERFORM set_config('request.jwt.claims', ${quoteLiteral(MATERIALIZE_CLAIMS_JSON)}, true);
+  RETURN QUERY
+    WITH up AS (
+      INSERT INTO ${target} AS m (${list})
+      SELECT ${list} FROM ${source}
+      ON CONFLICT (${keys}) ${onConflict}
+      RETURNING 1
+    ), gone AS (
+      DELETE FROM ${target} AS m
+      WHERE NOT EXISTS (SELECT 1 FROM ${source} AS c WHERE ${matches})
+      RETURNING 1
+    )
+    SELECT (SELECT count(*) FROM up), (SELECT count(*) FROM gone), true;
+  -- NULL resets to the session value when the caller had none.
+  PERFORM set_config('request.jwt.claims', caller_claims, true);
+END
+$orm_refresh$`;
+}
+function refreshFunctionStatements({ namespace, previous, current }) {
+  const schema = quoteIdentifier(ormSchemaName(namespace));
+  const statements = [];
+  for (const name of Object.keys(previous).sort()) {
+    if (!current.has(name)) statements.push(`DROP FUNCTION IF EXISTS ${schema}.${quoteIdentifier(materializedRefreshFunctionName(name))}(boolean)`);
+  }
+  for (const [name, create] of [...current].sort(([a], [b]) => a.localeCompare(b))) {
+    if (previous[name] === create) continue;
+    const fn = `${schema}.${quoteIdentifier(materializedRefreshFunctionName(name))}(boolean)`;
+    statements.push(create, `REVOKE ALL ON FUNCTION ${fn} FROM PUBLIC`);
+  }
+  return statements;
+}
+
 // src/engine/canonical2.ts
 var FACTORIES2 = {
   uuid: (name) => uuid(name),
@@ -5167,7 +6862,7 @@ var FACTORIES2 = {
 var SCHEMA_IMPORT_KEY2 = "$schema";
 var enumImportKey = (name) => `$enum_${name}`;
 var columnTablesV2 = (definition) => definition.tables.filter((table) => !table.source);
-function buildDrizzleEntitiesV2(definition) {
+function buildDrizzleEntitiesV2(definition, options = {}) {
   const schemaName = ormSchemaName(definition.namespace);
   const schema = pgSchema(schemaName);
   const imports = { [SCHEMA_IMPORT_KEY2]: schema };
@@ -5182,11 +6877,19 @@ function buildDrizzleEntitiesV2(definition) {
   }
   const byName = new Map(definition.tables.map((table) => [table.table, table]));
   for (const table of sortByEnforcedLinks2(columnTablesV2(definition))) {
-    const drizzleTable = buildTable2(schema, table, built, enums, byName);
+    const drizzleTable = buildTable2(schema, table, built, enums, byName, options.introspection ?? false);
     built.set(table.table, drizzleTable);
     imports[table.table] = drizzleTable;
     tables[table.table] = drizzleTable;
   }
+  if (options.introspection) {
+    for (const table of definition.tables.filter((table2) => table2.source)) {
+      const columns = Object.fromEntries(
+        table.columns.map((column) => [column.columnName, buildViewColumnV2({ view: table.table, column, enums })])
+      );
+      imports[table.table] = schema.view(table.table, columns).existing();
+    }
+  }
   for (const view of definition.views ?? []) {
     const columns = Object.fromEntries(
       view.columns.map((column) => [column.columnName, buildViewColumnV2({ view: view.view, column, enums })])
@@ -5430,9 +7133,12 @@ function replaceQualifiedRelation(sql4, sourceSchema, sourceName, boundSchema, b
 function generateSnapshotV2(definition, previousId3) {
   const { imports, schemaName } = buildDrizzleEntitiesV2(definition);
   const snapshot = generateDrizzleJson(imports, previousId3, [schemaName]);
-  if ((definition.views?.length ?? 0) > 0) {
+  if ((definition.views?.length ?? 0) > 0 || definition.tables.some((table) => table.foreignKeys?.length)) {
     const extended = snapshot;
+    const refreshFunctions = materializedRefreshFunctions(definition);
     extended._sequenceOrm = {
+      ...definition.tables.some((table) => table.foreignKeys?.length) ? { foreignKeys: Object.fromEntries(definition.tables.flatMap((table) => (table.foreignKeys ?? []).map((fk) => [`${table.table}.${fk.name}`, structuredClone(fk)]))) } : {},
+      ...refreshFunctions.size > 0 ? { refreshFunctions: Object.fromEntries(refreshFunctions) } : {},
       viewDependencies: Object.fromEntries(
         (definition.views ?? []).map((view) => [view.view, [...view.dependencies].sort()])
       )
@@ -5450,7 +7156,7 @@ function buildViewColumnV2({
   if (!column.nullable) builder = builder.notNull();
   return builder;
 }
-function buildTable2(schema, table, built, enums, byName) {
+function buildTable2(schema, table, built, enums, byName, introspection) {
   const primaryKeyColumns2 = table.primaryKey ?? [];
   if (primaryKeyColumns2.length === 0) {
     throw new OrmDefinitionError(`table '${table.table}' declares no primaryKey`);
@@ -5466,13 +7172,26 @@ function buildTable2(schema, table, built, enums, byName) {
   const columns = Object.fromEntries(
     table.columns.map((column) => [
       column.columnName,
-      buildColumnV2({ table: table.table, column, singlePrimaryKey, compositeMembers, enums })
+      buildColumnV2({ table: table.table, column, singlePrimaryKey, compositeMembers, enums, introspection })
     ])
   );
   const drizzleTable = schema.table(table.table, columns, (self) => [
     ...buildCompositePrimaryKey(table, primaryKeyColumns2, self),
     ...buildIndexes2(table, self),
-    ...buildForeignKeys2(table, self, built, byName)
+    ...(table.checks ?? []).map((check$1) => check(check$1.name, sql.raw(compileCheckExpression(check$1.expression, table.columns)))),
+    ...buildForeignKeys2(table, self, built, byName),
+    ...(table.foreignKeys ?? []).map((fk) => {
+      const target = fk.target === table.table ? self : built.get(fk.target);
+      if (!target) throw new OrmDefinitionError(`foreign key '${fk.name}' has no target '${fk.target}'`);
+      let constraint = foreignKey({
+        name: fk.name,
+        columns: fk.columns.map((column) => self[column]),
+        foreignColumns: fk.references.map((column) => target[column])
+      });
+      if (fk.onDelete !== void 0) constraint = constraint.onDelete(fk.onDelete);
+      if (fk.onUpdate !== void 0) constraint = constraint.onUpdate(fk.onUpdate);
+      return constraint;
+    })
   ]);
   return drizzleTable.enableRLS();
 }
@@ -5489,7 +7208,8 @@ function buildColumnV2({
   column,
   singlePrimaryKey,
   compositeMembers,
-  enums
+  enums,
+  introspection
 }) {
   const factory = resolveColumnFactory(table, column, enums);
   let builder = factory(column.columnName);
@@ -5510,7 +7230,7 @@ function buildColumnV2({
     }
     builder = builder.default(sql.raw(column.defaultFn));
   } else if (column.default !== void 0 && column.default !== null) {
-    builder = builder.default(column.default);
+    builder = introspection && column.type === "jsonb" && typeof column.default === "string" ? builder.default(sql.raw(`${quoteLiteral(column.default)}::jsonb`)) : builder.default(column.default);
   }
   return builder;
 }
@@ -5561,11 +7281,14 @@ function buildForeignKeys2(table, self, built, byName) {
         `enforced link '${link.name}' on '${table.table}' references unknown column '${targetColumn ? link.on : referencedColumn}'`
       );
     }
-    return foreignKey({
+    let constraint = foreignKey({
       name: foreignKeyName(table.table, link.name),
       columns: [sourceColumn],
       foreignColumns: [targetColumn]
     });
+    if (link.onDelete !== void 0) constraint = constraint.onDelete(link.onDelete);
+    if (link.onUpdate !== void 0) constraint = constraint.onUpdate(link.onUpdate);
+    return constraint;
   });
 }
 var singlePrimaryKeyOf = (table) => table.primaryKey?.length === 1 ? table.primaryKey[0] : void 0;
@@ -5686,16 +7409,31 @@ function findTable2(snapshot, schema, table) {
   const tables = snapshot.tables ?? {};
   return Object.values(tables).find((entry) => entry.schema === schema && entry.name === table);
 }
-async function planMigrationV2({
+function planMigrationV2(input) {
+  return planWithViewRecreation({ ...input, viewRecreation: "affected" });
+}
+async function planCommittedMigrationV2({
   canonical,
-  previousSnapshot
+  previousSnapshot,
+  reproduces
+}) {
+  const current = await planMigrationV2({ canonical, previousSnapshot });
+  if (reproduces(current)) return { plan: current, reproduced: true };
+  const legacy = await planWithViewRecreation({ canonical, previousSnapshot, viewRecreation: "all-on-base-change" });
+  return reproduces(legacy) ? { plan: legacy, reproduced: true } : { plan: current, reproduced: false };
+}
+async function planWithViewRecreation({
+  canonical,
+  previousSnapshot,
+  viewRecreation
 }) {
   const schema = ormSchemaName(canonical.namespace);
   const previous = previousSnapshot ? normalizeSnapshot(previousSnapshot) : emptySnapshot(canonical.namespace);
   assertValidViewDependencies(canonical);
   const hints = applyMigrationHintsV2(previous, canonical);
   const snapshot = generateSnapshotV2(canonical, previousId(previous));
-  const baseDdl = await diffStatements(withoutViews(hints.adjusted), withoutViews(snapshot));
+  const generatedBaseDdl = await diffStatements(withoutViews(hints.adjusted), withoutViews(snapshot));
+  const baseDdl = orderForeignKeyAdditions(canonical, generatedBaseDdl);
   const previousViews = snapshotViews(hints.adjusted);
   const currentViews = snapshotViews(snapshot);
   const previousDependencies = snapshotViewDependencies(hints.adjusted);
@@ -5705,7 +7443,14 @@ async function planMigrationV2({
     currentViews,
     previousDependencies,
     currentDependencies,
-    baseChanged: hints.statements.length > 0 || baseDdl.length > 0
+    reach: viewReach({
+      viewRecreation,
+      hintStatements: hints.statements,
+      baseDdl,
+      previous,
+      adjusted: hints.adjusted,
+      current: snapshot
+    })
   });
   const dropOrder = topologicalViewNames(
     new Set([...affected].filter((name) => previousViews.has(name))),
@@ -5732,15 +7477,44 @@ async function planMigrationV2({
     ...dropOrder.map((name) => ({ kind: "ddl", sql: requiredViewStatement(dropDdl, name, schema, "DROP") })),
     ...hints.statements.map((statement) => ({ kind: "hint", sql: statement })),
     ...baseDdl.map((statement) => ({ kind: "ddl", sql: statement.replace(/;\s*$/, "") })),
+    ...foreignKeyTimingStatements(canonical, previous, baseDdl).map((sql4) => ({ kind: "ddl", sql: sql4 })),
     ...createOrder.map((name) => ({ kind: "ddl", sql: requiredViewStatement(createDdl, name, schema, "CREATE") })),
     ...createOrder.map((name) => {
       const view = currentViewDefinitions.get(name);
       if (!view) throw new OrmDefinitionError(`missing canonical definition for view '${name}'`);
       return { kind: "ddl", sql: validateViewCatalogStatement({ canonical, view, schema }) };
-    })
+    }),
+    ...refreshFunctionStatements({
+      namespace: canonical.namespace,
+      previous: previous._sequenceOrm?.refreshFunctions ?? {},
+      current: materializedRefreshFunctions(canonical)
+    }).map((sql4) => ({ kind: "ddl", sql: sql4 }))
   ];
   return { namespace: canonical.namespace, schema, statements, snapshot };
 }
+function orderForeignKeyAdditions(canonical, statements) {
+  if (!canonical.tables.some((table) => table.foreignKeys?.length)) return [...statements];
+  const addsForeignKey = (statement) => /^ALTER TABLE[\s\S]* ADD CONSTRAINT[\s\S]* FOREIGN KEY\b/.test(statement);
+  return [...statements.filter((statement) => !addsForeignKey(statement)), ...statements.filter(addsForeignKey)];
+}
+function foreignKeyTimingStatements(canonical, previous, baseDdl) {
+  const prior = previous._sequenceOrm?.foreignKeys ?? {};
+  const result = [];
+  for (const table of canonical.tables) {
+    for (const fk of table.foreignKeys ?? []) {
+      const before = prior[`${table.table}.${fk.name}`];
+      const recreated = baseDdl.some((statement) => statement.includes(`ALTER TABLE ${quoteIdentifier(ormSchemaName(canonical.namespace))}.${quoteIdentifier(table.table)} ADD CONSTRAINT ${quoteIdentifier(fk.name)}`));
+      if (fk.deferrable ? !before || before.deferrable !== fk.deferrable || recreated : before?.deferrable && !recreated) {
+        result.push(foreignKeyTimingSql(ormSchemaName(canonical.namespace), table.table, fk.name, fk.deferrable));
+      }
+    }
+  }
+  return result;
+}
+function foreignKeyTimingSql(schema, table, name, timing) {
+  const clause = timing === void 0 ? "NOT DEFERRABLE" : timing === "initially-deferred" ? "DEFERRABLE INITIALLY DEFERRED" : "DEFERRABLE INITIALLY IMMEDIATE";
+  return `ALTER TABLE ${quoteIdentifier(schema)}.${quoteIdentifier(table)} ALTER CONSTRAINT ${quoteIdentifier(name)} ${clause}`;
+}
 function validateViewCatalogStatement({
   canonical,
   view,
@@ -5868,20 +7642,102 @@ function withoutViews(snapshot) {
   delete clone._sequenceOrm;
   return clone;
 }
+var DROPS_TYPE = /^\s*DROP\s+TYPE\b/i;
+function viewReach({
+  viewRecreation,
+  hintStatements,
+  baseDdl,
+  previous,
+  adjusted,
+  current
+}) {
+  if (hintStatements.length === 0 && baseDdl.length === 0) return /* @__PURE__ */ new Set();
+  if (viewRecreation === "all-on-base-change") return "all";
+  if (baseDdl.some((statement) => DROPS_TYPE.test(statement))) return "all";
+  const dependencies = snapshotViewDependencies(adjusted);
+  if ([...snapshotViews(adjusted).keys()].some((name) => dependencies[name] === void 0)) return "all";
+  return baseChangesReachingViews({ previous, adjusted, current });
+}
+var SNAPSHOT_BOOKKEEPING = /* @__PURE__ */ new Set(["id", "prevId", "version", "dialect", "_meta", "views", "_sequenceOrm", "enums"]);
+var VIEW_SAFE_TABLE_FIELDS = /* @__PURE__ */ new Set([
+  "indexes",
+  "foreignKeys",
+  "uniqueConstraints",
+  "checkConstraints",
+  "policies",
+  "isRLSEnabled"
+]);
+var VIEW_SAFE_COLUMN_FIELDS = /* @__PURE__ */ new Set(["notNull", "default", "isUnique", "uniqueName", "nullsNotDistinct"]);
+function baseChangesReachingViews({
+  previous,
+  adjusted,
+  current
+}) {
+  const before = adjusted;
+  const after = current;
+  for (const section of /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (SNAPSHOT_BOOKKEEPING.has(section) || section === "tables") continue;
+    if (stableJson(before[section]) !== stableJson(after[section])) return "all";
+  }
+  const relations = /* @__PURE__ */ new Set();
+  const previousTables = snapshotTables(previous);
+  const adjustedTables = snapshotTables(adjusted);
+  for (const key of changedEntryKeys(previousTables, adjustedTables)) {
+    const table = previousTables[key] ?? adjustedTables[key];
+    if (table) relations.add(table.name);
+  }
+  const currentTables = snapshotTables(current);
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(adjustedTables), ...Object.keys(currentTables)])) {
+    const was = adjustedTables[key];
+    const is = currentTables[key];
+    if (!was || !is) {
+      const table = was ?? is;
+      if (table) relations.add(table.name);
+    } else if (tableChangeReachesViews({ was, is })) {
+      relations.add(is.name);
+    }
+  }
+  return relations;
+}
+function tableChangeReachesViews({ was, is }) {
+  for (const field of /* @__PURE__ */ new Set([...Object.keys(was), ...Object.keys(is)])) {
+    if (field === "columns" || VIEW_SAFE_TABLE_FIELDS.has(field)) continue;
+    if (stableJson(was[field]) !== stableJson(is[field])) return true;
+  }
+  return Object.entries(was.columns).some(([name, column]) => {
+    const next = is.columns[name];
+    if (!next) return true;
+    return [.../* @__PURE__ */ new Set([...Object.keys(column), ...Object.keys(next)])].some(
+      (field) => !VIEW_SAFE_COLUMN_FIELDS.has(field) && stableJson(column[field]) !== stableJson(next[field])
+    );
+  });
+}
+function changedEntryKeys(before, after) {
+  return new Set(
+    [.../* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])].filter(
+      (key) => stableJson(before[key]) !== stableJson(after[key])
+    )
+  );
+}
+function snapshotTables(snapshot) {
+  return snapshot.tables ?? {};
+}
 function affectedViewNames({
   previousViews,
   currentViews,
   previousDependencies,
   currentDependencies,
-  baseChanged
+  reach
 }) {
   const allNames = /* @__PURE__ */ new Set([...previousViews.keys(), ...currentViews.keys()]);
-  if (baseChanged) return allNames;
+  if (reach === "all") return allNames;
+  const dependenciesOf = (name) => /* @__PURE__ */ new Set([...previousDependencies[name] ?? [], ...currentDependencies[name] ?? []]);
   const affected = new Set(
     [...allNames].filter((name) => {
       const before = previousViews.get(name);
       const after = currentViews.get(name);
-      return before === void 0 || after === void 0 || stableJson(before) !== stableJson(after);
+      if (before === void 0 || after === void 0 || stableJson(before) !== stableJson(after)) return true;
+      return [...dependenciesOf(name)].some((dependency) => reach.has(dependency));
     })
   );
   let grew = true;
@@ -5889,8 +7745,7 @@ function affectedViewNames({
     grew = false;
     for (const name of allNames) {
       if (affected.has(name)) continue;
-      const dependencies = /* @__PURE__ */ new Set([...previousDependencies[name] ?? [], ...currentDependencies[name] ?? []]);
-      if ([...dependencies].some((dependency) => affected.has(dependency))) {
+      if ([...dependenciesOf(name)].some((dependency) => affected.has(dependency))) {
         affected.add(name);
         grew = true;
       }
@@ -6805,7 +8660,9 @@ var PLATFORM_USER_FIELDS = [
 ];
 function generateSdl(canonical, options = {}) {
   const def = normalizeCanonical(canonicalDefinitionSchema.parse(canonical));
-  const tables = canonicalRelations(def).filter((table) => table.source === void 0);
+  const exposed = canonicalRelations(def).filter((table) => table.source === void 0 && table.internal !== true);
+  const cellsByTable = new Map(exposed.map((table) => [table.table, trackedCells(table)]));
+  const tables = exposed.map((table) => ({ ...table, columns: table.columns.filter((column) => column.cell === void 0) }));
   if (tables.length === 0) {
     throw new SdlGenerationError(
       `Namespace "${def.namespace}" exposes no relations (synced tables are excluded from SDL in v2.0) \u2014 nothing to generate.`
@@ -6861,8 +8718,14 @@ function generateSdl(canonical, options = {}) {
     '"""Gates an operation behind a platform capability or custom role \u2014 checked by the data plane before execution."""\ndirective @requires(capability: String, role: String) on QUERY | MUTATION'
   );
   blocks.push("directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT");
+  blocks.push(
+    '"""Abort the entire mutation unless this root affects exactly the document-authored number of rows. Mutation roots only; cannot be conditional."""\ndirective @assertAffectedRows(exactly: Int!) on FIELD'
+  );
+  if (tables.some((table) => table.resolved !== void 0)) blocks.push(...RESOLVED_DIRECTIVE_BLOCKS);
   for (const scalar2 of CUSTOM_SCALARS) blocks.push(`scalar ${scalar2}`);
+  blocks.push(...renderSharedCellTypes([...cellsByTable.values()]));
   blocks.push(renderEnum(ORDER_BY_ENUM, [...ORDER_BY_ENUM_VALUES]));
+  blocks.push(renderEnum(DATE_BUCKET_ENUM, DATE_BUCKETS.map((bucket) => bucket.toUpperCase())));
   for (const enumName of [...usedEnums].sort()) {
     const entry = enumByName.get(enumName);
     if (!entry) continue;
@@ -6885,16 +8748,32 @@ function generateSdl(canonical, options = {}) {
         names,
         namesByTable,
         emitAggregateBoolExp: aggregateBoolExpTargets.has(table.table),
-        pinned: options.pinnedColumns?.[table.table] ?? []
+        pinned: options.pinnedColumns?.[table.table] ?? [],
+        cells: cellsByTable.get(table.table) ?? null
       })
     );
   }
   blocks.push(renderQueryRoot(tables, namesByTable));
   const mutationRoot = renderMutationRoot(tables, namesByTable);
   if (mutationRoot !== null) blocks.push(mutationRoot);
+  assertNoDuplicateTypeNames(blocks);
   return `${blocks.join("\n\n")}
 `;
 }
+var TYPE_DECLARATION_RE = /^(?:type|input|enum|scalar|interface|union)\s+([_A-Za-z][_0-9A-Za-z]*)/;
+function assertNoDuplicateTypeNames(blocks) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const block of blocks) {
+    const declared = TYPE_DECLARATION_RE.exec(block)?.[1];
+    if (declared === void 0) continue;
+    if (seen.has(declared)) {
+      throw new SdlGenerationError(
+        `Generated schema declares "${declared}" twice. A canonical enum or table name is PascalCased into this GraphQL type name and collides with another declaration (for example an enum named "date_bucket" renders as "DateBucket", the shared bucket enum). Rename the offending enum or table.`
+      );
+    }
+    seen.add(declared);
+  }
+}
 function assertEnumValue(value, context) {
   if (!GRAPHQL_NAME_RE2.test(value) || RESERVED_ENUM_VALUES.has(value)) {
     throw new SdlGenerationError(
@@ -6960,6 +8839,52 @@ ${orderFields}
 }`
   ];
 }
+var RESOLVED_DIRECTIVE_BLOCKS = [
+  '"""Refresh this resolved-table root from a prefetch source before reading. Key-addressed roots only; the source must support the root shape."""\ndirective @prefetch(source: String!, maxStaleness: String) repeatable on FIELD',
+  renderEnum("WritebackMode", ["SYNC", "ASYNC"]),
+  '"""Write this resolved-table mutation back to a prefetch source (SYNC rolls back on failure; ASYNC queues)."""\ndirective @writeback(source: String!, mode: WritebackMode) repeatable on FIELD',
+  '"""Declare that this mutation deliberately keeps writeback columns local to the named source."""\ndirective @localOnly(source: String!) repeatable on FIELD'
+];
+function trackedCells(table) {
+  const columns = [...new Set(table.columns.flatMap((column) => column.cell ? [column.cell.of] : []))];
+  if (columns.length === 0) return null;
+  return { resolved: table.columns.some((column) => column.cell?.part === "source"), columns };
+}
+function renderSharedCellTypes(all) {
+  const present = all.filter((cells) => cells !== null);
+  const blocks = [];
+  if (present.some((cells) => !cells.resolved)) {
+    blocks.push(`"""When, and by whom, a cell was last written."""
+type ${CELL_TYPENAMES.stamp} {
+  at: timestamptz!
+  by: String
+}`);
+  }
+  if (present.some((cells) => cells.resolved)) {
+    blocks.push(`"""A newer candidate value that lost to the column's resolve rule."""
+type ${CELL_TYPENAMES.conflict} {
+  source: String!
+  at: timestamptz
+  value: jsonb
+}`);
+    blocks.push(`"""How a resolved cell was decided: the winning source, its time and actor, and newer losers."""
+type ${CELL_TYPENAMES.resolved} {
+  source: String!
+  at: timestamptz
+  by: String
+  conflicts: [${CELL_TYPENAMES.conflict}!]!
+}`);
+  }
+  return blocks;
+}
+function renderCellsType(ctx) {
+  if (!ctx.cells) return [];
+  const cellType = ctx.cells.resolved ? CELL_TYPENAMES.resolved : CELL_TYPENAMES.stamp;
+  const lines = ctx.cells.columns.map((column) => `  ${fieldName(column)}: ${cellType}`);
+  return [`type ${cellsTypename(ctx.names.typename)} {
+${lines.join("\n")}
+}`];
+}
 function relationArgs(target) {
   return `where: ${target.boolExp}, orderBy: [${target.orderBy}!], limit: Int, offset: Int`;
 }
@@ -6968,10 +8893,10 @@ function rootArgs(names) {
 }
 function primaryKeyColumns(table) {
   if (!table.primaryKey || table.primaryKey.length === 0) return [];
-  return table.primaryKey.map((identifier2) => {
-    const column = table.columns.find((c) => c.columnName === identifier2 || c.name === identifier2);
+  return table.primaryKey.map((identifier3) => {
+    const column = table.columns.find((c) => c.columnName === identifier3 || c.name === identifier3);
     if (!column) {
-      throw new SdlGenerationError(`Primary key column "${identifier2}" not found on table "${table.table}".`);
+      throw new SdlGenerationError(`Primary key column "${identifier3}" not found on table "${table.table}".`);
     }
     return column;
   });
@@ -6980,10 +8905,12 @@ function renderTableBlocks(ctx) {
   const { table, names } = ctx;
   const blocks = [
     renderObjectType(ctx),
+    ...renderCellsType(ctx),
     renderSelectColumnEnum(ctx),
     renderOrderByInput(ctx),
     renderBoolExp(ctx),
-    ...renderAggregateTypes(ctx)
+    ...renderAggregateTypes(ctx),
+    ...renderGroupByTypes(ctx)
   ];
   if (ctx.emitAggregateBoolExp) blocks.push(...renderAggregateBoolExp(ctx));
   const pk = primaryKeyColumns(table);
@@ -6993,11 +8920,49 @@ function renderTableBlocks(ctx) {
 ${fields}
 }`);
   }
-  if (allowsInsert(table) || allowsUpdate(table)) {
+  if (ctx.table.resolved !== void 0) {
+    blocks.push(...renderResolvedWriteBlocks(ctx));
+  } else if (allowsInsert(table) || allowsUpdate(table)) {
     blocks.push(...renderWriteBlocks(ctx, { insert: allowsInsert(table), update: allowsUpdate(table) }));
   }
   return blocks;
 }
+function resolvedWritableColumns(table) {
+  const system = new Set(Object.values(RESOLVED_VIEW_SYSTEM_COLUMNS).map((column) => column.name));
+  return table.columns.filter((column) => !system.has(column.name));
+}
+function renderResolvedWriteBlocks(ctx) {
+  const { table, names } = ctx;
+  const writable = resolvedWritableColumns(table);
+  const pk = new Set(table.primaryKey ?? []);
+  const settable = writable.filter((column) => !pk.has(column.columnName));
+  const line = (column) => `  ${fieldName(column.name)}: ${columnGqlTypeOf(table, column)}`;
+  const blocks = [];
+  if (allowsInsert(table)) blocks.push(`input ${names.insertInput} {
+${writable.map(line).join("\n")}
+}`);
+  if (allowsUpdate(table)) {
+    blocks.push(`input ${names.setInput} {
+${settable.map(line).join("\n")}
+}`);
+    blocks.push(renderEnum(names.updateColumnEnum, settable.map((column) => fieldName(column.name))));
+  }
+  return blocks;
+}
+function renderResolvedMutationFields(table, names) {
+  const lines = [];
+  const pk = primaryKeyColumns(table);
+  if (allowsInsert(table)) lines.push(`  ${names.insertOneRoot}(object: ${names.insertInput}!): ${names.typename}`);
+  if (allowsUpdate(table) && pk.length > 0) {
+    lines.push(`  ${names.updateByPkRoot}(pkColumns: ${names.pkColumnsInput}!, _set: ${names.setInput}!): ${names.typename}`);
+    lines.push(`  ${names.revertByPkRoot}(pkColumns: ${names.pkColumnsInput}!, columns: [${names.updateColumnEnum}!]!): ${names.typename}`);
+    if ((table.resolved?.deletedBy.length ?? 0) > 0) {
+      const args = pk.map((column) => `${fieldName(column.name)}: ${columnGqlTypeOf(table, column)}!`).join(", ");
+      lines.push(`  ${names.deleteByPkRoot}(${args}): ${names.typename}`);
+    }
+  }
+  return lines;
+}
 function allowsInsert(table) {
   return table.policies.write !== void 0 || table.policies.insert !== void 0;
 }
@@ -7020,6 +8985,10 @@ function renderObjectType(ctx) {
     const deprecated = column.deprecated ? " @deprecated" : "";
     lines.push(`  ${fieldName(column.name)}: ${columnGqlTypeOf(table, column)}${bang}${deprecated}`);
   }
+  if (ctx.cells) {
+    lines.push('  """Per-cell metadata: when each field was last written, and by whom."""');
+    lines.push(`  ${CELLS_FIELD}: ${cellsTypename(names.typename)}!`);
+  }
   for (const link of table.links) {
     if (link.description !== void 0) lines.push(...descriptionLines(link.description, "  "));
     if (link.kind === "toPlatformUser") {
@@ -7088,7 +9057,10 @@ function numericishColumns(table) {
   return table.columns.filter((column) => typeof column.type !== "object" && NUMERICISH.has(column.type));
 }
 function jsonbColumns(table) {
-  return table.columns.filter((column) => column.type === "jsonb");
+  return clientWritableColumns(table).filter((column) => column.type === "jsonb");
+}
+function clientWritableColumns(table) {
+  return table.columns;
 }
 function renderAggregateTypes(ctx) {
   const { table, names } = ctx;
@@ -7120,6 +9092,32 @@ ${sumLines.join("\n")}
   }
   return blocks;
 }
+function groupableColumns(table) {
+  return table.columns.filter((column) => column.type !== "jsonb");
+}
+function renderGroupByTypes(ctx) {
+  const { table, names } = ctx;
+  const groupable = groupableColumns(table);
+  if (groupable.length === 0) return [];
+  const keyLines = groupable.map((column) => `  ${fieldName(column.name)}: ${columnGqlTypeOf(table, column)}`);
+  return [
+    renderEnum(names.groupByColumnEnum, groupable.map((column) => fieldName(column.name))),
+    `input ${names.groupByInput} {
+  column: ${names.groupByColumnEnum}!
+  bucket: ${DATE_BUCKET_ENUM}
+}`,
+    `type ${names.groupKey} {
+${keyLines.join("\n")}
+}`,
+    `type ${names.aggregateGroup} {
+  key: ${names.groupKey}!
+  aggregate: ${names.aggregateFields}
+}`
+  ];
+}
+function groupRootArgs(names) {
+  return `where: ${names.boolExp}, groupBy: [${names.groupByInput}!]!, limit: Int, offset: Int`;
+}
 function renderAggregateBoolExp(ctx) {
   const { names } = ctx;
   return [
@@ -7145,12 +9143,15 @@ function constraintValues(table) {
   }
   return [...values].sort();
 }
+function clientSettableColumns(table) {
+  return clientWritableColumns(table).filter((column) => column.onUpdateFn === void 0);
+}
 function renderWriteBlocks(ctx, access) {
   const { table, names, pinned } = ctx;
   const blocks = [];
   if (access.insert) {
     const pinnedSet = new Set(pinned);
-    const insertable = table.columns.filter(
+    const insertable = clientWritableColumns(table).filter(
       (column) => !pinnedSet.has(column.name) && !pinnedSet.has(column.columnName)
     );
     if (insertable.length === 0) {
@@ -7166,7 +9167,7 @@ ${insertLines.join("\n")}
 }`);
   }
   if (access.update) {
-    const setLines = table.columns.map(
+    const setLines = clientSettableColumns(table).map(
       (column) => `  ${fieldName(column.name)}: ${columnGqlTypeOf(table, column)}`
     );
     blocks.push(`input ${names.setInput} {
@@ -7193,7 +9194,7 @@ ${incLines.join("\n")}
   if (access.insert && allowsOnConflict(table) && constraints.length > 0) {
     for (const value of constraints) assertEnumValue(value, `constraint enum for table "${table.table}"`);
     blocks.push(renderEnum(names.constraintEnum, constraints));
-    const updateColumns = table.columns.map((column) => fieldName(column.name));
+    const updateColumns = clientSettableColumns(table).map((column) => fieldName(column.name));
     blocks.push(renderEnum(names.updateColumnEnum, updateColumns));
     blocks.push(
       `input ${names.onConflict} {
@@ -7225,6 +9226,9 @@ function renderQueryRoot(tables, namesByTable) {
       lines.push(`  ${names.byPkRoot}(${args}): ${names.typename}`);
     }
     lines.push(`  ${names.aggregateRoot}(${rootArgs(names)}): ${names.aggregate}!`);
+    if (groupableColumns(table).length > 0) {
+      lines.push(`  ${names.aggregateGroupsRoot}(${groupRootArgs(names)}): [${names.aggregateGroup}!]!`);
+    }
   }
   lines.push("}");
   return lines.join("\n");
@@ -7240,6 +9244,10 @@ function renderMutationRoot(tables, namesByTable) {
     if (!canInsert && !canUpdate) continue;
     const names = namesByTable.get(table.table);
     if (!names) continue;
+    if (table.resolved !== void 0) {
+      lines.push(...renderResolvedMutationFields(table, names));
+      continue;
+    }
     const constraints = constraintValues(table);
     const onConflictArg = canInsert && allowsOnConflict(table) && constraints.length > 0 ? `, onConflict: ${names.onConflict}` : "";
     const updateArgs = [`_set: ${names.setInput}`];
@@ -7293,6 +9301,92 @@ function renderCowMutationFields(table, names) {
   }
   return lines;
 }
+var ORM_MIGRATION_EXPORT_FILE = "orm.migration.json";
+var ORM_MIGRATION_EXPORT_MAX_BYTES = ORM_REGISTRATION_MAX_BYTES;
+var hash = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+var ormMigrationPayloadSchema = z.object({
+  canonical_definition: canonicalDefinitionSchema,
+  documents: z.array(z.object({ path: z.string().min(1).max(2048), contents: z.string().max(1e6) }).strict()).max(5e3),
+  client_manifest: z.object({ ops_hash: hash, operations: z.record(z.string(), hash) }).strict(),
+  sdl: z.string().refine((value) => Buffer.byteLength(value, "utf8") <= MAX_GENERATED_SDL_BYTES, {
+    message: `sdl exceeds ${MAX_GENERATED_SDL_BYTES} bytes`
+  }),
+  schema_snapshot: z.json(),
+  // The existing ORM committed-migration validator and replay engine remain
+  // authoritative. This envelope hashes the provenance, never authorizes SQL.
+  migration: z.json().optional()
+}).strict();
+z.object({
+  schema_version: z.literal(1),
+  schema_hash: hash,
+  payload: ormMigrationPayloadSchema,
+  checksum: z.string().regex(/^[0-9a-f]{64}$/)
+}).strict();
+function checksum(value) {
+  return createHash("sha256").update(stableJson(value)).digest("hex");
+}
+function createOrmMigrationExport({ schemaHash, payload }) {
+  const contents = { schema_version: 1, schema_hash: hash.parse(schemaHash), payload: ormMigrationPayloadSchema.parse(payload) };
+  return { ...contents, checksum: checksum(contents) };
+}
+function renderOrmMigrationExport(exported) {
+  const text4 = `${JSON.stringify(exported, null, 2)}
+`;
+  if (Buffer.byteLength(text4, "utf8") > ORM_MIGRATION_EXPORT_MAX_BYTES) throw new Error("ORM migration export exceeds the size limit");
+  return text4;
+}
+
+// src/compiler-gql/role-warnings.ts
+var ROLE_CHECK = /\brole\(\s*['"]([^'"]+)['"]\s*\)/g;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function roleKeysIn(value) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const match of JSON.stringify(value ?? null).matchAll(ROLE_CHECK)) {
+    if (match[1]) keys.add(match[1]);
+  }
+  return [...keys].sort();
+}
+function roleWarnings({
+  canonical,
+  manifest
+}) {
+  const warnings = [];
+  const roles = canonical.capabilities.roles;
+  const defined = isRecord(roles) && isRecord(roles.definitions) ? Object.keys(roles.definitions).sort() : [];
+  if (defined.length > 0) {
+    warnings.push({
+      severity: "warning",
+      code: "deprecated-role-definitions",
+      message: `The namespace defines roles (${defined.join(", ")}). Role definitions here are a deprecated one-time seed: apply creates any that don't exist yet and never updates them after. Create and edit roles in Atlas; keep declaring the capabilities your policies check.`
+    });
+  }
+  const relations = [
+    ...canonical.tables,
+    ...(canonical.views ?? []).map((view) => ({ table: view.view, policies: view.policies, resolved: view.resolved }))
+  ];
+  for (const relation of relations) {
+    const keys = roleKeysIn([relation.policies, relation.resolved]);
+    if (keys.length === 0) continue;
+    warnings.push({
+      severity: "warning",
+      code: "role-check",
+      table: relation.table,
+      message: `Policy checks ${keys.map((key) => `role('${key}')`).join(", ")}. Roles are defined in Atlas and can be renamed or removed there; check the capability the role grants with capability('\u2026') instead.`
+    });
+  }
+  for (const [operation, entry] of Object.entries(manifest.operations).sort(([a], [b]) => a.localeCompare(b))) {
+    if (!entry.requires?.role) continue;
+    warnings.push({
+      severity: "warning",
+      code: "role-requires",
+      operation,
+      message: `@requires(role: "${entry.requires.role}") gates on a role Atlas can rename or remove; use @requires(capability: "\u2026") with the capability the role grants.`
+    });
+  }
+  return warnings;
+}
 
 // src/cli.ts
 var BASE_URL_ENV = "SEQUENCE_ORM_BASE_URL";
@@ -7300,7 +9394,9 @@ var TOKEN_ENV = "SEQUENCE_ORM_TOKEN";
 var ORM_MODULE_PATH_ENV = "SEQUENCE_ORM_MODULE_PATH";
 var USAGE = `usage:
   seq-studio orm init <dir>              scaffold a namespace package (v2: TypeScript schema + GraphQL documents)
-  seq-studio orm generate [dir]          write schema.graphql + operations.manifest.json + typePolicies.gen.ts (+ consumer graphql-codegen when codegen.ts is present)
+  seq-studio orm generate [dir]          write schema.graphql + operations.manifest.json + typePolicies.gen.ts (+ sources.gen.ts for resolved-table sources, + consumer graphql-codegen when codegen.ts is present)
+  seq-studio orm generate [dir] --migration-export [--check]
+                                        export reviewed ORM inputs for a coordinated pipeline migration; --check verifies without writing
   seq-studio orm validate [dir]          parse + validate definitions and verify committed migrations are in sync
   seq-studio orm plan [dir] -e <env>     offline dry run: compile definitions and diff against the registry (no database, no writes)
   seq-studio orm apply [dir] -e <env>    author the migration, register, apply, and refresh the generated outputs (the everyday command)
@@ -7315,6 +9411,8 @@ var USAGE = `usage:
   v2 = sequence.config.ts + schema/*.ts + graphql/**; v1 (legacy) = one <table>.yaml per table.
   Environments: see \`seq-studio envs list\` (discovered after you authenticate).
   Authenticate with: seq-studio login
+  Execute endpoint rollout: SEQUENCE_ORM_ATLAS_EXECUTE_V2=1 opts into /api/data/v2;
+  otherwise execute uses /_data/v2. Server rollout and authorization still apply.
 `;
 var tokenProvider = null;
 function setTokenProvider(provider) {
@@ -7467,6 +9565,7 @@ async function walkFiles(root, prefix = "") {
 var SCHEMA_GRAPHQL_FILE = "schema.graphql";
 var OPERATIONS_MANIFEST_FILE = "operations.manifest.json";
 var TYPE_POLICIES_FILE = "typePolicies.gen.ts";
+var SOURCE_CONTRACTS_FILE = "sources.gen.ts";
 var GRAPHQL_DIRNAME = "graphql";
 var CODEGEN_CONFIG_FILE = "codegen.ts";
 function ormLoadOptions() {
@@ -7486,9 +9585,10 @@ async function compileV2Project(dir) {
   const documents = await collectGraphqlDocuments(dir);
   const result = compileNamespace({ canonical: loaded.canonical, sdl, documents });
   if (!result.ok) return { ok: false, diagnostics: result.diagnostics };
+  const diagnostics = [...result.diagnostics, ...roleWarnings({ canonical: loaded.canonical, manifest: result.manifest })];
   return {
     ok: true,
-    project: { loaded, sdl, documents, manifest: result.manifest, diagnostics: result.diagnostics }
+    project: { loaded, sdl, documents, manifest: result.manifest, diagnostics }
   };
 }
 var GQL_TEMPLATE_RE = /(?:\bgql|\/\*\s*GraphQL\s*\*\/)\s*`([^`]*)`/g;
@@ -7529,6 +9629,12 @@ function printDiagnostics(diagnostics) {
 }
 async function generateCommand(rest) {
   const dir = positional(rest) ?? ".";
+  const migrationExport = rest.includes("--migration-export");
+  const check = rest.includes("--check");
+  if (check && !migrationExport) {
+    console.error("generate --check requires --migration-export");
+    return 1;
+  }
   if (await detectProjectFormat(dir) === "v1") {
     console.error(`generate needs a v2 project (${NAMESPACE_CONFIG_FILE}) \u2014 convert with: seq-studio orm migrate-from-yaml ${dir}`);
     return 1;
@@ -7536,6 +9642,36 @@ async function generateCommand(rest) {
   const compiled = await compileV2Project(dir);
   printDiagnostics(compiled.ok ? compiled.project.diagnostics : compiled.diagnostics);
   if (!compiled.ok) return 1;
+  if (migrationExport) {
+    if (await validateV2Command(dir) !== 0) return 1;
+    const { loaded: loaded2, sdl, documents, manifest: manifest2 } = compiled.project;
+    const workspace = await readMigrationWorkspace(dir, loaded2.canonical.namespace);
+    const migration = await loadCommittedTipMigrationV2({ dir, loaded: loaded2, workspace });
+    const exported = createOrmMigrationExport({ schemaHash: manifest2.schemaHash, payload: {
+      canonical_definition: loaded2.canonical,
+      documents,
+      sdl,
+      client_manifest: { ops_hash: manifest2.opsHash, operations: Object.fromEntries(Object.entries(manifest2.operations).map(([name, operation]) => [name, operation.opHash])) },
+      schema_snapshot: workspace.tipSnapshot,
+      ...migration ? { migration } : {}
+    } });
+    const text4 = renderOrmMigrationExport(exported);
+    const path = join(dir, ORM_MIGRATION_EXPORT_FILE);
+    if (check) {
+      const committed = await readFile(path, "utf8").catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+        throw error;
+      });
+      if (committed !== text4) {
+        console.error(`${ORM_MIGRATION_EXPORT_FILE} is missing or stale; run seq-studio orm generate ${dir} --migration-export and commit it`);
+        return 1;
+      }
+      console.log(`${ORM_MIGRATION_EXPORT_FILE} matches the current definitions, operations, and committed migration`);
+      return 0;
+    }
+    await writeFile(path, text4);
+    console.log(`wrote ${ORM_MIGRATION_EXPORT_FILE} (${exported.checksum.slice(0, 12)})`);
+  }
   await writeGenerateOutputs(dir, compiled.project);
   const { loaded, manifest } = compiled.project;
   console.log(
@@ -7556,6 +9692,8 @@ async function writeGenerateOutputs(dir, project) {
   await writeFile(join(dir, OPERATIONS_MANIFEST_FILE), `${JSON.stringify(manifestFile, null, 2)}
 `);
   await writeFile(join(dir, TYPE_POLICIES_FILE), generateTypePolicies(loaded.canonical));
+  const sourceContracts = generateSourceContracts(loaded.canonical);
+  if (sourceContracts !== null) await writeFile(join(dir, SOURCE_CONTRACTS_FILE), sourceContracts);
 }
 async function runConsumerCodegen(dir) {
   const codegenPath = join(dir, CODEGEN_CONFIG_FILE);
@@ -7651,9 +9789,10 @@ async function executeV2Command(rest) {
     );
   }
   const variables = await readExecuteVariables(variablesFile);
+  const executePrefix = process.env["SEQUENCE_ORM_ATLAS_EXECUTE_V2"] === "1" ? "/api/data/v2" : "/_data/v2";
   const response = await apiRequestStrict(
     "POST",
-    `/_data/v2/${loaded.canonical.namespace}`,
+    `${executePrefix}/${loaded.canonical.namespace}`,
     { op: selected.hash, variables }
   );
   console.log(JSON.stringify(response, null, 2));
@@ -7822,16 +9961,28 @@ async function checkWorkspaceV2({
     return 1;
   }
   const previousSnapshot = tip.ordinal > 1 ? await readSnapshot(dir, tip.ordinal - 1) : void 0;
-  const plan = await planMigrationV2({ canonical: loaded.canonical, previousSnapshot });
-  const regenerated = renderMigrationSql({ name: tip.name, namespace, contentHash: loaded.hash, plan });
   const committed = await readMigrationSql(dir, tip);
-  if (regenerated !== committed && !matchesRebaseTip({ committed, tip, namespace, plan })) {
+  const { reproduced } = await planCommittedTipV2({ loaded, tip, previousSnapshot, committed });
+  if (!reproduced) {
     log(`${MIGRATIONS_DIRNAME}/${tip.name}.sql does not regenerate from the definitions \u2014 re-run \`seq-studio orm diff\``);
     return 1;
   }
   log(`migrations in sync \u2014 ${workspace.journal.entries.length} committed, tip ${tip.name}`);
   return 0;
 }
+function planCommittedTipV2({
+  loaded,
+  tip,
+  previousSnapshot,
+  committed
+}) {
+  const namespace = loaded.canonical.namespace;
+  return planCommittedMigrationV2({
+    canonical: loaded.canonical,
+    previousSnapshot,
+    reproduces: (plan) => renderMigrationSql({ name: tip.name, namespace, contentHash: loaded.hash, plan }) === committed || matchesRebaseTip({ committed, tip, namespace, plan })
+  });
+}
 function matchesRebaseTip({
   committed,
   tip,
@@ -7934,7 +10085,6 @@ async function loadCommittedTipMigrationV2({
   loaded,
   workspace
 }) {
-  const namespace = loaded.canonical.namespace;
   const tip = workspace.journal.entries.at(-1);
   if (!tip) return void 0;
   if (tip.content_hash !== loaded.hash) {
@@ -7944,10 +10094,9 @@ async function loadCommittedTipMigrationV2({
     );
   }
   const previousSnapshot = tip.ordinal > 1 ? await readSnapshot(dir, tip.ordinal - 1) : void 0;
-  const plan = await planMigrationV2({ canonical: loaded.canonical, previousSnapshot });
   const committed = await readMigrationSql(dir, tip);
-  const regenerated = renderMigrationSql({ name: tip.name, namespace, contentHash: loaded.hash, plan });
-  if (regenerated !== committed && !matchesRebaseTip({ committed, tip, namespace, plan })) {
+  const { plan, reproduced } = await planCommittedTipV2({ loaded, tip, previousSnapshot, committed });
+  if (!reproduced) {
     throw new OrmDefinitionError(
       `${tip.name}.sql does not regenerate from the definitions \u2014 run \`seq-studio orm diff --check\``,
       MIGRATIONS_DIRNAME
@@ -8168,6 +10317,7 @@ function columnProperty(table, column, singlePrimaryKey) {
     }
     chain += `.default(${JSON.stringify(column.default)})`;
   }
+  if (column.onUpdateFn !== void 0) chain += `.onUpdate(${quote(column.onUpdateFn)})`;
   if (column.description !== void 0) chain += `.description(${quote(column.description)})`;
   if (column.renamedFrom !== void 0) chain += `.renamedFrom(${quote(column.renamedFrom)})`;
   if (column.cast !== void 0) chain += `.cast(${quote(column.cast)})`;