@sequenceholdings/orm 2.0.0 → 2.1.1

package/dist/sdl.js

@@ -1,10 +1,481 @@
 import { z } from 'zod';
 import { createHash } from 'crypto';
 
+// src/canonical/v2.ts
+var quoteIdentifier = (name) => `"${name.replaceAll('"', '""')}"`;
+var quoteLiteral = (value) => `'${value.replaceAll("'", "''")}'`;
+
+// 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 COLUMN_IDENTIFIER_PATTERN = /^_?[a-z][a-z0-9_]*$/;
+var MAX_IDENTIFIER_LENGTH = 63;
+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";
+JSON.stringify({ sub: MATERIALIZE_ACTOR, org: null, roles: [], capabilities: [] });
+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 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 fail = (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) {
+    fail("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
+  };
+  if (resolved.sources.filter((source) => source.kind === "manual").length !== 1) fail("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)) fail(`duplicate source '${source.name}'`);
+    scope.sourceByName.set(source.name, source);
+    const table = tableByName.get(source.table);
+    if (!table) fail(`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") fail(`deletedBy '${name}' must be the manual source`);
+  }
+  return errors;
+}
+function validateSource({ scope, source, table }) {
+  const { fail } = scope;
+  if (source.kind === "etl" && table.source === void 0) fail(`etl source '${source.name}' must reference a synced table`);
+  if (source.kind !== "etl" && (table.internal !== true || table.cellMetadata !== true)) {
+    fail(`${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) fail(`manual source '${source.name}' must carry '__rev' cell columns`);
+  if (source.kind === "prefetch" && hasRev) fail(`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") {
+      fail(`etl source '${source.name}' updatedAt must name a timestamptz/date column on '${source.table}'`);
+    }
+  }
+  validatePrefetchFields({ scope, source });
+}
+function validatePrefetchFields({ scope, source }) {
+  const { fail, pkColumn } = scope;
+  if (source.kind !== "prefetch") {
+    if (source.key || source.fetch || source.function || source.prefetchDefaults || source.writeback) {
+      fail(`only prefetch sources may declare key/fetch/function/prefetchDefaults/writeback ('${source.name}')`);
+    }
+    return;
+  }
+  if (!source.key || !source.fetch || !source.function || !source.prefetchDefaults) {
+    fail(`prefetch source '${source.name}' requires key, fetch, function and prefetchDefaults`);
+  } else if (source.key !== pkColumn.name && !source.columns.includes(source.key)) {
+    fail(`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)) fail(`prefetch source '${source.name}' writes back '${column}', which it does not supply`);
+  }
+}
+function validateSourceColumns({ scope, source, byName }) {
+  const { fail, 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) fail(`source '${source.name}' supplies unknown column '${column}'`);
+    else if (!theirs) fail(`source '${source.name}' table '${source.table}' has no column '${column}'`);
+    else if (JSON.stringify(theirs.type) !== JSON.stringify(own.type)) fail(`column '${column}' has a different type on source '${source.name}'`);
+  }
+}
+function validateRules({ resolved, pkColumn, dataColumns, sourceByName, fail }) {
+  const ruled = /* @__PURE__ */ new Set();
+  for (const rule of resolved.resolve) {
+    if (!dataColumns.has(rule.column) || rule.column === pkColumn.name) {
+      fail(`resolve rule targets unknown column '${rule.column}'`);
+      continue;
+    }
+    if (ruled.has(rule.column)) fail(`column '${rule.column}' has more than one resolve rule`);
+    ruled.add(rule.column);
+    if (rule.comparator === "custom" !== (rule.orderBy !== void 0)) {
+      fail(`column '${rule.column}': orderBy is required for custom comparators and only allowed there`);
+    }
+    if (new Set(rule.candidates).size !== rule.candidates.length) fail(`column '${rule.column}' repeats a candidate`);
+    for (const candidate of rule.candidates) {
+      const source = sourceByName.get(candidate);
+      if (!source) fail(`column '${rule.column}' names unknown candidate source '${candidate}'`);
+      else if (!source.columns.includes(rule.column)) fail(`column '${rule.column}' candidate '${candidate}' does not supply it`);
+    }
+  }
+  for (const column of dataColumns.keys()) {
+    if (column !== pkColumn.name && !ruled.has(column)) fail(`column '${column}' has no resolve rule`);
+  }
+}
+var VIEW_CELL_TYPES = {
+  source: "text",
+  at: "timestamptz",
+  by: "text",
+  conflicts: "jsonb"
+};
+function validateViewCells({ view, dataColumns, pkColumn, fail }) {
+  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) {
+      fail(`unexpected cell column '${column.name}'`);
+      continue;
+    }
+    if (column.type !== VIEW_CELL_TYPES[column.cell.part]) fail(`cell column '${column.name}' must be ${VIEW_CELL_TYPES[column.cell.part]}`);
+    expected.delete(column.name);
+  }
+  for (const name of expected.keys()) fail(`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 } = scope;
+  const { table: tableName, compute: computeName } = resolved.materialized;
+  const table = tableByName.get(tableName);
+  if (!table || table.internal !== true || table.materializes !== view.view) {
+    fail(`materialized table '${tableName}' must be an internal table that materializes '${view.view}'`);
+  } else {
+    if (columnSignature(table.columns) !== columnSignature(view.columns)) fail(`materialized table '${tableName}' must have exactly the view's columns`);
+    if (JSON.stringify(table.primaryKey ?? []) !== JSON.stringify(view.primaryKey ?? [])) fail(`materialized table '${tableName}' must share the view's primary key`);
+  }
+  const compute = views.find((candidate) => candidate.view === computeName);
+  if (!compute || compute.internal !== true) fail(`compute view '${computeName}' must be an internal view`);
+  else if (columnSignature(compute.columns) !== columnSignature(view.columns)) fail(`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) {
+      fail(`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",
@@ -19,59 +490,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(),
@@ -102,7 +585,7 @@ function isSingleViewQuerySql(value) {
   return state === "normal" && !/\$[a-z_0-9]*\$/i.test(query);
 }
 var canonicalActionSchema = z.object({
-  name: identifier,
+  name: identifier2,
   requires: z.string().max(1e3).optional(),
   params: z.record(z.string(), z.object({
     type: columnTypeSchema,
@@ -114,9 +597,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. */
@@ -143,17 +626,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
@@ -162,26 +656,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 [index, column] of view.columns.entries()) {
     if (column.default !== void 0 || column.defaultFn !== void 0) {
       ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare a default` });
     }
+    if (column.onUpdateFn !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare onUpdateFn` });
+    }
     if (column.unique) {
       ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare unique` });
     }
@@ -189,15 +721,82 @@ var canonicalViewSchema = z.object({
       ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare migration hints` });
     }
   }
+  if (view.resolved === void 0 && view.internal !== true) {
+    for (const [index, column] of view.columns.entries()) {
+      if (column.cell) ctx.addIssue({ code: "custom", path: ["columns", index], message: `only resolved tables carry cell columns ('${column.name}')` });
+    }
+  }
   for (const [index, link] of view.links.entries()) {
     if (link.enforce) {
       ctx.addIssue({ code: "custom", path: ["links", index, "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", index], 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, index, ctx) {
+  const fail = (message, path = ["tables", index]) => 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) fail(`cell-metadata columns require cellMetadata on table '${table.table}'`, ["tables", index, "columns", position]);
+    return;
+  }
+  if (table.source !== void 0) {
+    fail(`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) fail(`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", index, "columns", position];
+    const owner = byName.get(cell.of);
+    if (!owner) {
+      fail(`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") fail(`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)) {
+      fail(`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) {
+      fail(`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)) fail(`duplicate cell column '${column.name}'`, path);
+    seen.add(key);
+  }
+  for (const column of tracked) {
+    if (column.columnName.length > MAX_TRACKED_COLUMN_NAME) {
+      fail(`column '${column.columnName}' is too long to track cell metadata (max ${MAX_TRACKED_COLUMN_NAME} characters)`);
+    }
+    if (SUFFIXES.some((suffix) => column.columnName.endsWith(suffix))) {
+      fail(`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}`)) fail(`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),
@@ -215,6 +814,74 @@ var canonicalDefinitionSchema = z.object({
       ctx.addIssue({ code: "custom", path: ["tables", index, "table"], message: `duplicate relation '${table.table}'` });
     }
     seen.add(table.table);
+    validateCellMetadata(table, index, 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", index, "columns", columnIndex],
+            message: `synced table '${table.table}' column '${column.name}' cannot declare onUpdateFn`
+          });
+        }
+      }
+    }
+  }
+  const fkTables = new Map(definition.tables.map((table) => [table.table, table]));
+  for (const [tableIndex, table] of definition.tables.entries()) {
+    const names = /* @__PURE__ */ new Set([
+      ...table.primaryKey?.length ? [`${table.table}_pkey`] : [],
+      ...table.columns.filter((column) => column.unique && !(table.primaryKey?.length === 1 && table.primaryKey[0] === column.columnName)).map((column) => `${table.table}_${column.columnName}_unique`),
+      ...table.links.filter((link) => link.enforce).map((link) => `fk_${table.table}_${link.name}`)
+    ]);
+    for (const [index, 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", index], 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", index], message: "SET NULL requires a nullable source column" });
+      }
+    }
+    for (const [index, check] of (table.checks ?? []).entries()) {
+      const fail = (message) => ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "checks", index], message });
+      if (table.source) fail("synced tables cannot declare checks");
+      if (names.has(check.name)) fail(`duplicate constraint '${check.name}'`);
+      names.add(check.name);
+      try {
+        compileCheckExpression(check.expression, table.columns);
+      } catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+      }
+    }
+    for (const [index, fk] of (table.foreignKeys ?? []).entries()) {
+      const fail = (message) => ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "foreignKeys", index], message });
+      if (names.has(fk.name)) fail(`duplicate foreign key '${fk.name}'`);
+      names.add(fk.name);
+      const target = fkTables.get(fk.target);
+      if (table.source || !target || target.source) {
+        fail("foreign keys must connect owned tables in the same namespace");
+        continue;
+      }
+      if (fk.columns.length !== fk.references.length) fail("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) fail("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) fail("foreign key references an unknown column");
+        else if (JSON.stringify(sourceColumn.type) !== JSON.stringify(targetColumn.type)) fail("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))) fail("SET NULL requires nullable source columns");
+      }
+      const uniqueKeys = [target.primaryKey ?? [], ...target.indexes.filter((index2) => index2.unique).map((index2) => index2.columns), ...target.columns.filter((column) => column.unique).map((column) => [column.columnName])];
+      if (!uniqueKeys.some((key) => key.length === fk.references.length && key.every((column) => fk.references.includes(column)))) fail("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()) {
@@ -339,8 +1006,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));
 }
@@ -350,12 +1021,14 @@ function normalizeCanonical(definition) {
     ...definition,
     enums: sortByName(definition.enums),
     tables: [...definition.tables].sort((a, b) => a.table.localeCompare(b.table)).map((t) => {
-      const { cowMutations, ...rest } = t;
+      const { cowMutations, foreignKeys, checks, ...rest } = t;
       return {
         ...rest,
         links: sortByName(t.links),
         indexes: [...t.indexes].sort((a, b) => (a.name ?? a.columns.join("_")).localeCompare(b.name ?? b.columns.join("_"))),
         actions: sortByName(t.actions),
+        ...foreignKeys?.length ? { foreignKeys: sortByName(foreignKeys) } : {},
+        ...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) } : {}
       };
@@ -444,6 +1117,8 @@ var ORDER_BY_ENUM_VALUES = [
   "DESC_NULLS_LAST"
 ];
 var PLATFORM_USER_TYPENAME = "PlatformUser";
+var DATE_BUCKET_ENUM = "DateBucket";
+var BUCKETABLE_COLUMN_TYPES = ["timestamptz", "date"];
 function tableNames(table) {
   const root = camelCase(table);
   const rootPascal = pascalCase(table);
@@ -459,6 +1134,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`,
@@ -476,9 +1152,426 @@ 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`;
+}
+var IR_VERSION = 2;
+var LEGACY_IR_VERSION = 1;
+var irVersionSchema = z.union([z.literal(LEGACY_IR_VERSION), z.literal(IR_VERSION)]);
+z.object({ irVersion: irVersionSchema });
+var scalarLiteral = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+var valueIrSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("literal"), value: z.union([scalarLiteral, z.array(scalarLiteral)]) }),
+  z.object({ kind: z.literal("variable"), name: z.string() }),
+  z.object({ kind: z.literal("claim"), key: z.enum(["sub", "org"]) })
+]);
+var CMP_OPS = [
+  "eq",
+  "neq",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "in",
+  "nin",
+  "like",
+  "ilike",
+  "isNull",
+  "contains",
+  "hasKey"
+];
+var predIrSchema = z.lazy(
+  () => z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("and"), operands: z.array(predIrSchema).min(1) }),
+    z.object({ kind: z.literal("or"), operands: z.array(predIrSchema).min(1) }),
+    z.object({ kind: z.literal("not"), operand: predIrSchema }),
+    z.object({ kind: z.literal("cmp"), op: z.enum(CMP_OPS), column: z.string(), value: valueIrSchema }),
+    z.object({ kind: z.literal("exists"), link: z.string(), where: predIrSchema }),
+    z.object({
+      kind: z.literal("aggPredicate"),
+      link: z.string(),
+      fn: z.literal("count"),
+      op: z.enum(["eq", "neq", "gt", "gte", "lt", "lte"]),
+      value: z.number(),
+      where: predIrSchema.optional()
+    }),
+    z.object({ kind: z.literal("capability"), key: z.string() }),
+    z.object({ kind: z.literal("role"), key: z.string() }),
+    z.object({ kind: z.literal("dynamicFilter"), slot: z.string() }),
+    z.object({ kind: z.literal("const"), value: z.boolean() })
+  ])
+);
+var orderIrSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("column"),
+    column: z.string(),
+    /** Order through a to-one link: `link` is set and `column` is on the target. */
+    link: z.string().optional(),
+    direction: z.enum(["asc", "desc"]),
+    nulls: z.enum(["first", "last"]).optional()
+  }),
+  /** §4f: `$orderBy: [FooOrderBy!]` variable — validated + lowered at runtime. */
+  z.object({ kind: z.literal("dynamic"), slot: z.string() })
+]);
+var limitIrSchema = z.object({
+  /** Fixed value or a variable, clamped to [1, max]; absent → default. */
+  variable: z.string().optional(),
+  value: z.number().int().positive().optional(),
+  default: z.number().int().positive(),
+  max: z.number().int().positive()
+});
+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(),
+      selection: selectionIrSchema,
+      where: predIrSchema.optional(),
+      orderBy: z.array(orderIrSchema).optional(),
+      limit: limitIrSchema.optional(),
+      offset: z.object({ variable: z.string().optional(), value: z.number().int().optional() }).optional()
+    })),
+    aggregates: z.array(z.object({
+      alias: z.string(),
+      link: z.string().optional(),
+      where: predIrSchema.optional(),
+      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(),
+      nodes: selectionIrSchema.optional()
+    }))
+  })
+);
+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(),
+  table: z.string(),
+  selection: selectionIrSchema,
+  /** Composed at compile time: AND(policy, documentWhere?, dynamicFilter?). */
+  where: predIrSchema,
+  orderBy: z.array(orderIrSchema).default([]),
+  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(),
+  prefetch: z.array(prefetchPlanIrSchema).optional()
+});
+var byPkRootSchema = z.object({
+  kind: z.literal("byPk"),
+  alias: z.string(),
+  table: z.string(),
+  selection: selectionIrSchema,
+  pk: z.array(z.object({ column: z.string(), value: valueIrSchema })).min(1),
+  /** Policy predicate — ANDed with the PK match. */
+  where: predIrSchema,
+  includeIf: includeIfSchema.optional(),
+  prefetch: z.array(prefetchPlanIrSchema).optional()
+});
+var aggregateRootSchema = z.object({
+  kind: z.literal("aggregate"),
+  alias: z.string(),
+  table: z.string(),
+  where: predIrSchema,
+  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(),
+  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 })) })
+]);
+var onConflictIrSchema = z.union([
+  z.object({ slot: z.string() }),
+  z.object({ constraint: z.string(), updateColumns: z.array(z.string()) })
+]);
+var mutationRootSchema = z.object({
+  kind: z.literal("mutation"),
+  /**
+   * CRUD verbs plus the structured copy-on-write ops. `cowOverride` copies the
+   * synced row into the overlay (INSERT…SELECT, ON CONFLICT DO NOTHING) then
+   * applies `set` — both statements generated by the executor from this
+   * metadata, never authored SQL. `cowRevert` deletes the override so the
+   * 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", "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). */
+  cowSynced: z.string().optional(),
+  /** cowOverride: logical properties copied INSERT…SELECT from synced (pk included). */
+  cowCopyColumns: z.array(z.string()).optional(),
+  /** cowOverride: insert-policy WITH CHECK evaluated over the copied rows. */
+  cowCopyCheck: predIrSchema.optional(),
+  /** insert/insertOne: rows come from a slot ($object/$objects) or literals. */
+  objects: z.union([
+    z.object({ slot: z.string() }),
+    z.object({ rows: z.array(z.array(z.object({ column: z.string(), value: valueIrSchema }))) })
+  ]).optional(),
+  /** Server-pinned columns (e.g. author_sub ← claim('sub')) merged into every inserted row. */
+  pinnedColumns: z.array(z.object({ column: z.string(), value: valueIrSchema })).default([]),
+  onConflict: onConflictIrSchema.optional(),
+  set: writeValuesSchema.optional(),
+  append: writeValuesSchema.optional(),
+  inc: writeValuesSchema.optional(),
+  /** update/delete row filter: AND(writePolicy, documentWhere/pk, dynamicFilter?). */
+  where: predIrSchema.optional(),
+  pk: z.array(z.object({ column: z.string(), value: valueIrSchema })).optional(),
+  /** WITH CHECK analogue evaluated against NEW row values (insert/update). */
+  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 = [
+  "boolExp",
+  "orderBy",
+  "selectColumn",
+  "insertInput",
+  "setInput",
+  "appendInput",
+  "onConflict"
+];
+var variableDefaultIrSchema = z.object({
+  value: z.union([scalarLiteral, z.array(scalarLiteral)])
+});
+var variableIrSchema = z.object({
+  name: z.string(),
+  type: z.union([
+    z.object({ kind: z.literal("scalar"), scalar: z.enum(COLUMN_TYPES) }),
+    /** `values` is the declared membership whitelist — the executor validates against it. */
+    z.object({ kind: z.literal("enum"), name: z.string(), values: z.array(z.string()).min(1) }),
+    /** §4f dynamic slot: validated against `tables[table]` whitelists at runtime. */
+    z.object({ kind: z.literal("inputRef"), input: z.enum(INPUT_REF_KINDS), table: z.string() })
+  ]),
+  nullable: z.boolean(),
+  list: z.boolean(),
+  /** Absent = no default declared; see {@link variableDefaultIrSchema}. */
+  defaultValue: variableDefaultIrSchema.optional()
+});
+var compiledOperationSchema = z.object({
+  irVersion: irVersionSchema,
+  name: z.string(),
+  opHash: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+  kind: z.enum(["query", "mutation"]),
+  requires: z.object({
+    capability: z.string().optional(),
+    role: z.string().optional()
+  }).nullable(),
+  variables: z.array(variableIrSchema),
+  /** Every table the op touches — data-token scoping + audit. */
+  tableSet: z.array(z.string()).min(1),
+  roots: z.array(rootIrSchema).min(1)
+}).superRefine((operation, ctx) => {
+  for (const [index, root] of operation.roots.entries()) {
+    if (root.kind !== "mutation" || root.assertAffectedRows === void 0) continue;
+    if (operation.irVersion < 2 || operation.kind !== "mutation" || root.includeIf !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["roots", index], message: "affected-row assertions require unconditional mutation roots and IR v2" });
+    }
+  }
+});
+var 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(),
+  schema: z.string(),
+  typename: z.string(),
+  /**
+   * True when statements over this relation evaluate a claims-gated synced
+   * view: synced twins (`source: gold.*`) materialize as views whose baked
+   * policy reads `current_setting('request.jwt.claims')`, and namespace views
+   * inherit the gate transitively through their declared dependencies. The
+   * executor must stamp that GUC (transaction-scoped) before any statement
+   * touching such a relation, or the synced arm yields zero rows regardless
+   * of the compiled predicates.
+   */
+  claimsGated: z.boolean().default(false),
+  columns: z.array(z.object({
+    name: z.string(),
+    columnName: z.string(),
+    type: z.union([z.enum(COLUMN_TYPES), z.object({ enum: z.string(), values: z.array(z.string()) })]),
+    nullable: z.boolean()
+  })),
+  /** Empty for keyless read-only views; keyed tables and views list logical columns. */
+  primaryKey: z.array(z.string()),
+  links: z.array(z.object({
+    name: z.string(),
+    kind: z.enum(["toOne", "toMany", "toPlatformUser"]),
+    target: z.string(),
+    on: z.string(),
+    references: z.string()
+  })),
+  /** §4f whitelists: what dynamic inputs may reference. */
+  filterable: z.array(z.string()),
+  orderable: z.array(z.string()),
+  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)
+});
+z.object({
+  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" });
+    }
+  }
+});
 
 // src/sdl/generate.ts
 var SdlGenerationError = class extends Error {
@@ -501,7 +1594,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.`
@@ -557,8 +1652,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 scalar of CUSTOM_SCALARS) blocks.push(`scalar ${scalar}`);
+  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;
@@ -581,16 +1682,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_RE.test(value) || RESERVED_ENUM_VALUES.has(value)) {
     throw new SdlGenerationError(
@@ -656,6 +1773,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`;
 }
@@ -664,10 +1827,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;
   });
@@ -676,10 +1839,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);
@@ -689,11 +1854,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;
 }
@@ -716,6 +1919,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") {
@@ -784,7 +1991,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;
@@ -816,6 +2026,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 [
@@ -841,12 +2077,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) {
@@ -862,7 +2101,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} {
@@ -889,7 +2128,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} {
@@ -921,6 +2160,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");
@@ -936,6 +2178,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}`];
@@ -1069,13 +2315,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);
     });
@@ -1093,6 +2339,6 @@ ${body}
 `;
 }
 
-export { CUSTOM_SCALARS, MANIFEST_VERSION, NUMERICISH_COLUMN_TYPES, ORDER_BY_ENUM, ORDER_BY_ENUM_VALUES, PLATFORM_USER_TYPENAME, SdlGenerationError, VARIABLE_SCALAR_NAMES, buildOperationsManifest, camelCase, columnTypeForScalar, comparisonExpName, enumTypeName, fieldName, generateSdl, generateTypePolicies, graphqlScalarFor, manifestOperationSchema, manifestRequiresSchema, operationsManifestSchema, pascalCase, tableNames, typeName };
+export { BUCKETABLE_COLUMN_TYPES, CELL_TYPENAMES, CUSTOM_SCALARS, DATE_BUCKET_ENUM, MANIFEST_VERSION, NUMERICISH_COLUMN_TYPES, ORDER_BY_ENUM, ORDER_BY_ENUM_VALUES, PLATFORM_USER_TYPENAME, SdlGenerationError, VARIABLE_SCALAR_NAMES, buildOperationsManifest, camelCase, cellsTypename, columnTypeForScalar, comparisonExpName, enumTypeName, fieldName, generateSdl, generateTypePolicies, graphqlScalarFor, manifestOperationSchema, manifestRequiresSchema, operationsManifestSchema, pascalCase, resolvedWritableColumns, tableNames, typeName };
 //# sourceMappingURL=sdl.js.map
 //# sourceMappingURL=sdl.js.map