@sequenceholdings/orm 0.1.3 → 2.1.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { sql, eq, notExists } from 'drizzle-orm';
+import { sql, eq, notExists, is, SQL } from 'drizzle-orm';
 import { pgSchema, uniqueIndex, index, foreignKey, primaryKey, PgDialect, QueryBuilder, getViewConfig, extractUsedTable, jsonb, date, timestamp, boolean, doublePrecision, numeric, bigint, integer, text, uuid } from 'drizzle-orm/pg-core';
 import { createHash } from 'crypto';
 import { z } from 'zod';
@@ -34,6 +34,7 @@ var ColumnBuilder = class {
       hasDefault: false,
       defaultValue: void 0,
       defaultFn: void 0,
+      onUpdateFn: void 0,
       description: void 0,
       renamedFrom: void 0,
       cast: void 0,
@@ -69,6 +70,15 @@ var ColumnBuilder = class {
     this.state.defaultFn = void 0;
     return this;
   }
+  /**
+   * Stamp this column with Postgres `now()` on every UPDATE. Only valid on
+   * timestamptz/date; the compiler drops it from SetInput so callers cannot
+   * supply a value.
+   */
+  onUpdate(value) {
+    this.state.onUpdateFn = value;
+    return this;
+  }
   description(text4) {
     this.state.description = text4;
     return this;
@@ -112,6 +122,7 @@ var ColumnBuilder = class {
     };
     if (this.state.hasDefault) column.default = this.state.defaultValue ?? null;
     if (this.state.defaultFn !== void 0) column.defaultFn = this.state.defaultFn;
+    if (this.state.onUpdateFn !== void 0) column.onUpdateFn = this.state.onUpdateFn;
     if (this.state.description !== void 0) column.description = this.state.description;
     if (this.state.renamedFrom !== void 0) column.renamedFrom = this.state.renamedFrom;
     if (this.state.cast !== void 0) column.cast = this.state.cast;
@@ -139,6 +150,7 @@ var t = {
 // 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 ORM_DATA_TOKEN_HEADER = "x-sequence-data-token";
 var ORM_SERVICE_DATA_TOKEN_HEADER = "x-sequence-data-token-service";
@@ -154,6 +166,8 @@ 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"]);
 
@@ -262,10 +276,10 @@ function isSeqLink(value) {
 function isSeqTable(value) {
   return typeof value === "object" && value !== null && value.kind === TABLE_BRAND;
 }
-function assertIdentifier({ value, what, file }) {
-  if (!IDENTIFIER_PATTERN.test(value) || value.length > MAX_IDENTIFIER_LENGTH) {
+function assertIdentifier({ value, what, file, pattern = IDENTIFIER_PATTERN }) {
+  if (!pattern.test(value) || value.length > MAX_IDENTIFIER_LENGTH) {
     throw new OrmDefinitionError(
-      `${what} "${value}" must match ${IDENTIFIER_PATTERN} and be at most ${MAX_IDENTIFIER_LENGTH} characters`,
+      `${what} "${value}" must match ${pattern} and be at most ${MAX_IDENTIFIER_LENGTH} characters`,
       file
     );
   }
@@ -286,7 +300,7 @@ function defineTable(name, columns, config = {}) {
       );
     }
     const columnName = builder.columnNameFor(propertyName);
-    assertIdentifier({ value: columnName, what: `table "${name}": column "${propertyName}" column name`, file });
+    assertIdentifier({ value: columnName, what: `table "${name}": column "${propertyName}" column name`, file, pattern: COLUMN_IDENTIFIER_PATTERN });
     const existing = seenColumnNames.get(columnName);
     if (existing !== void 0) {
       throw new OrmDefinitionError(
@@ -326,7 +340,8 @@ function defineSyncedTable(name, columnsOrConfig, maybeConfig) {
     assertIdentifier({
       value: columnName,
       what: `synced table "${name}": column "${propertyName}" column name`,
-      file
+      file,
+      pattern: COLUMN_IDENTIFIER_PATTERN
     });
     const existing = seenColumnNames.get(columnName);
     if (existing !== void 0) {
@@ -415,7 +430,7 @@ function defineView(name, columns, config) {
       );
     }
     const columnName = builder.columnNameFor(propertyName);
-    if (!IDENTIFIER_PATTERN.test(columnName) || columnName.length > MAX_IDENTIFIER_LENGTH) {
+    if (!COLUMN_IDENTIFIER_PATTERN.test(columnName) || columnName.length > MAX_IDENTIFIER_LENGTH) {
       throw new OrmDefinitionError(`view "${name}": column "${propertyName}" has invalid column name "${columnName}"`, file);
     }
     const existing = seenColumnNames.get(columnName);
@@ -864,6 +879,7 @@ function scalarColumnType(table, property, helper) {
 var CANONICAL_FORMAT = 2;
 var IDENTIFIER_RE = /^[a-z][a-z0-9_]*$/;
 var identifier = z.string().min(1).max(63).regex(IDENTIFIER_RE);
+var columnIdentifier = z.string().min(1).max(63).regex(COLUMN_IDENTIFIER_PATTERN);
 var COLUMN_TYPES = [
   "uuid",
   "text",
@@ -884,18 +900,33 @@ var canonicalEnumSchema = z.object({
 var canonicalColumnSchema = z.object({
   /** Property name in TS (camelCase); columnName is the Postgres name. */
   name: z.string().min(1).max(63),
-  columnName: identifier,
+  columnName: columnIdentifier,
   type: z.union([columnTypeSchema, z.object({ enum: identifier })]),
   nullable: z.boolean().default(true),
   unique: z.boolean().default(false),
   /** Literal default, or one of the allowlisted SQL functions. */
   default: z.union([z.string(), z.number(), z.boolean(), z.null()]).optional(),
   defaultFn: z.enum(["gen_random_uuid()", "now()"]).optional(),
+  /**
+   * Stamp this column from the database clock on UPDATE (`now()`). The
+   * column stays insertable (defaults fill gaps) but is omitted from
+   * SetInput / settable so callers cannot backdate it.
+   */
+  onUpdateFn: z.enum(["now()"]).optional(),
   description: z.string().max(500).optional(),
   /** Migration hints — same semantics as v1. */
-  renamedFrom: identifier.optional(),
+  renamedFrom: columnIdentifier.optional(),
   cast: z.string().max(200).optional(),
   deprecated: z.boolean().default(false)
+}).superRefine((column, ctx) => {
+  if (column.onUpdateFn === void 0) return;
+  if (typeof column.type !== "string" || column.type !== "timestamptz" && column.type !== "date") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["onUpdateFn"],
+      message: `onUpdateFn '${column.onUpdateFn}' is only valid on timestamptz/date columns`
+    });
+  }
 });
 var canonicalLinkSchema = z.object({
   name: z.string().min(1).max(63),
@@ -903,15 +934,15 @@ var canonicalLinkSchema = z.object({
   /** Target table name (namespace-local). Absent for toPlatformUser. */
   target: identifier.optional(),
   /** FK column on the owning side (toOne/toPlatformUser: on this table; toMany: on the target). */
-  on: identifier,
+  on: columnIdentifier,
   /** Referenced column on the target (default: target's PK / platform user `sub`). */
-  references: identifier.optional(),
+  references: columnIdentifier.optional(),
   /** enforce: true emits a real FK constraint (same-namespace toOne only). */
   enforce: z.boolean().default(false),
   description: z.string().max(500).optional()
 });
 var canonicalIndexSchema = z.object({
-  columns: z.array(identifier).min(1),
+  columns: z.array(columnIdentifier).min(1),
   unique: z.boolean().default(false),
   name: identifier.optional()
 });
@@ -1159,6 +1190,13 @@ var canonicalCowMutationSchema = z.object({
     }
   }
 });
+var canonicalForeignKeySchema = z.object({
+  name: identifier,
+  columns: z.array(columnIdentifier).min(1).max(8),
+  target: identifier,
+  references: z.array(columnIdentifier).min(1).max(8),
+  deferrable: z.enum(["initially-immediate", "initially-deferred"]).optional()
+}).strict();
 var canonicalTableSchema = z.object({
   table: identifier,
   description: z.string().max(2e3).optional(),
@@ -1167,7 +1205,7 @@ var canonicalTableSchema = z.object({
   /** Synced/reflected read-only tables (`source: gold.*`) — v1 semantics. */
   source: z.string().regex(/^gold\.[a-z][a-z0-9_]*$/).optional(),
   columns: z.array(canonicalColumnSchema).default([]),
-  primaryKey: z.array(identifier).min(1).max(8).optional(),
+  primaryKey: z.array(columnIdentifier).min(1).max(8).optional(),
   links: z.array(canonicalLinkSchema).default([]),
   indexes: z.array(canonicalIndexSchema).default([]),
   policies: canonicalPoliciesSchema.default({}),
@@ -1178,14 +1216,16 @@ var canonicalTableSchema = z.object({
    */
   actions: z.array(canonicalActionSchema).default([]),
   /** Optional (not defaulted) so pre-CoW canonical documents keep byte-identical hashes. */
-  cowMutations: z.array(canonicalCowMutationSchema).optional()
+  cowMutations: z.array(canonicalCowMutationSchema).optional(),
+  /** Omitted by old definitions, preserving their existing content hashes. */
+  foreignKeys: z.array(canonicalForeignKeySchema).max(100).optional()
 });
 var canonicalViewSchema = z.object({
   view: identifier,
   description: z.string().max(2e3).optional(),
   columns: z.array(canonicalColumnSchema).min(1),
   /** Logical identity for GraphQL only; PostgreSQL views have no PK constraint. */
-  primaryKey: z.array(identifier).min(1).max(8).optional(),
+  primaryKey: z.array(columnIdentifier).min(1).max(8).optional(),
   links: z.array(canonicalLinkSchema).default([]),
   policies: z.object({ read: policyExpressionSchema }).strict(),
   query: z.string().min(1).max(1e5).refine(isSingleViewQuerySql, {
@@ -1198,6 +1238,9 @@ var canonicalViewSchema = z.object({
     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` });
     }
@@ -1231,6 +1274,45 @@ var canonicalDefinitionSchema = z.object({
       ctx.addIssue({ code: "custom", path: ["tables", index3, "table"], message: `duplicate relation '${table.table}'` });
     }
     seen.add(table.table);
+    if (table.source !== void 0) {
+      for (const [columnIndex, column] of table.columns.entries()) {
+        if (column.onUpdateFn !== void 0) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["tables", 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, fk] of (table.foreignKeys ?? []).entries()) {
+      const fail = (message) => ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "foreignKeys", index3], 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");
+      }
+      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)))) fail("foreign key target columns must form a unique key");
+    }
   }
   const tableByName = new Map(definition.tables.map((table) => [table.table, table]));
   for (const [tableIndex, table] of definition.tables.entries()) {
@@ -1366,12 +1448,13 @@ 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, ...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) } : {},
         // Omitted entirely when absent/empty so pre-CoW documents hash unchanged.
         ...cowMutations !== void 0 && cowMutations.length > 0 ? { cowMutations: sortByName(cowMutations) } : {}
       };
@@ -1645,6 +1728,22 @@ function buildCanonicalTable({ table, relationsByName, enumsByName }) {
   } else if (columnLevelPk.length > 0) {
     candidate.primaryKey = columnLevelPk;
   }
+  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 } : {}
+      };
+    });
+  }
   for (const index3 of table.config.indexes ?? []) {
     const entry = {
       columns: index3.columns.map((ref) => resolveColumnRef({ relation: table, ref, role: "index" }))
@@ -1697,6 +1796,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);
     }
@@ -1955,7 +2060,16 @@ async function loadNamespaceFromDir(dir, options = {}) {
   const jiti = createJiti(import.meta.url, {
     interopDefault: true,
     fsCache: false,
-    ...options.ormModulePath !== void 0 ? { alias: { "@sequenceholdings/orm": options.ormModulePath } } : {}
+    ...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
+      }
+    } : {}
   });
   const context = beginAuthoringContext();
   try {
@@ -2514,8 +2628,8 @@ var actionSchema = z.strictObject({
     }
   }
 });
-function extractNamedParams(sql4) {
-  const withoutStrings = sql4.replace(QUOTED_STRING_PATTERN, "''");
+function extractNamedParams(sql5) {
+  const withoutStrings = sql5.replace(QUOTED_STRING_PATTERN, "''");
   const names = [...withoutStrings.matchAll(NAMED_PARAM_PATTERN)].map((match) => match[1]);
   return [...new Set(names)];
 }
@@ -2672,8 +2786,8 @@ var actionParamArg = (name) => `p_${name}`;
 function compileActionStatements(action, renderParam = actionParamArg) {
   return actionStatementSources(action.executes).map((statement) => compileStatement(statement, renderParam));
 }
-function compileStatement(sql4, renderParam) {
-  const compiled = sql4.replace(TOKEN_PATTERN, (token, claimKey, capabilityKey, paramName) => {
+function compileStatement(sql5, renderParam) {
+  const compiled = sql5.replace(TOKEN_PATTERN, (token, claimKey, capabilityKey, paramName) => {
     if (claimKey !== void 0) {
       if (!CLAIM_KEY_PATTERN.test(claimKey)) throw new OrmDefinitionError(`invalid claim key in executes: ${token}`);
       return claimExpression(claimKey);
@@ -2838,8 +2952,8 @@ function actionPrepareChecks(definition) {
     const order = actionParamOrder(action);
     const signature = order.length > 0 ? ` (${order.map((param) => sqlTypeName(action.params[param].type)).join(", ")})` : "";
     const compiled = compileActionStatements(action, (param) => `$${order.indexOf(param) + 1}`);
-    compiled.forEach((sql4, index3) => {
-      const checked = action.returns && index3 === compiled.length - 1 ? returnProjection(action.returns, sql4) : sql4;
+    compiled.forEach((sql5, index3) => {
+      const checked = action.returns && index3 === compiled.length - 1 ? returnProjection(action.returns, sql5) : sql5;
       statements.push(`PREPARE ${quoteIdentifier(`orm_check_${name}_${index3}`)}${signature} AS ${checked}`);
     });
   }
@@ -3293,7 +3407,8 @@ function syncedViewStatements({
   readPolicyIrByTable,
   columnNamesByTable,
   columnTypesByTable,
-  executionOwnerRole = SYNCED_VIEW_EXECUTION_OWNER_ROLE
+  executionOwnerRole = SYNCED_VIEW_EXECUTION_OWNER_ROLE,
+  backingPrivileges = "grant"
 }) {
   const schema = quoteIdentifier(ormSchemaName(definition.namespace));
   const role = quoteIdentifier(consumerRoleName(definition.namespace));
@@ -3327,8 +3442,10 @@ function syncedViewStatements({
       columnTypes,
       columnNames: columnNamesByTable?.get(table.table)
     })}` : readPolicy ? ` WHERE ${compilePredicate(readPolicy.ast, narrowToV1ColumnTypes(columnTypes))}` : " WHERE false";
-    statements.push(`GRANT USAGE ON SCHEMA ${quoteIdentifier(physical.schema)} TO ${owner}`);
-    statements.push(`GRANT SELECT ON ${physicalTarget} TO ${owner}`);
+    if (backingPrivileges === "grant") {
+      statements.push(`GRANT USAGE ON SCHEMA ${quoteIdentifier(physical.schema)} TO ${owner}`);
+      statements.push(`GRANT SELECT ON ${physicalTarget} TO ${owner}`);
+    }
     statements.push(
       `CREATE OR REPLACE VIEW ${viewName} AS SELECT * FROM ${physicalTarget}${whereClause}`
     );
@@ -3617,7 +3734,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 };
@@ -3632,11 +3749,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 })])
@@ -3704,18 +3829,18 @@ function rewriteSyncedSourceRelationsInViewQuery({
     return rewritten;
   });
 }
-function transformSqlOutsideLiterals(sql4, transform) {
+function transformSqlOutsideLiterals(sql5, transform) {
   const out = [];
   let state = { kind: "normal" };
   let i = 0;
   let codeStart = 0;
   const emitCode = (end) => {
-    if (end > codeStart) out.push(transform(sql4.slice(codeStart, end)));
+    if (end > codeStart) out.push(transform(sql5.slice(codeStart, end)));
     codeStart = end;
   };
-  while (i < sql4.length) {
-    const c = sql4[i];
-    const next = i + 1 < sql4.length ? sql4[i + 1] : "";
+  while (i < sql5.length) {
+    const c = sql5[i];
+    const next = i + 1 < sql5.length ? sql5[i + 1] : "";
     switch (state.kind) {
       case "normal": {
         if (c === "-" && next === "-") {
@@ -3735,7 +3860,7 @@ function transformSqlOutsideLiterals(sql4, transform) {
           break;
         }
         if ((c === "E" || c === "e") && next === "'") {
-          const prev = i > 0 ? sql4[i - 1] : "";
+          const prev = i > 0 ? sql5[i - 1] : "";
           if (!/[A-Za-z0-9_]/.test(prev)) {
             emitCode(i);
             state = { kind: "e-single" };
@@ -3754,9 +3879,9 @@ function transformSqlOutsideLiterals(sql4, transform) {
           break;
         }
         if (c === "$") {
-          const prev = i > 0 ? sql4[i - 1] : "";
+          const prev = i > 0 ? sql5[i - 1] : "";
           if (!/[A-Za-z0-9_$]/.test(prev)) {
-            const tagMatch = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql4.slice(i));
+            const tagMatch = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql5.slice(i));
             if (tagMatch) {
               emitCode(i);
               state = { kind: "dollar", tag: tagMatch[1] ?? "" };
@@ -3788,8 +3913,8 @@ function transformSqlOutsideLiterals(sql4, transform) {
         break;
       }
       case "e-single": {
-        if (c === "\\" && i + 1 < sql4.length) {
-          out.push(c, sql4[i + 1]);
+        if (c === "\\" && i + 1 < sql5.length) {
+          out.push(c, sql5[i + 1]);
           i += 2;
           break;
         }
@@ -3811,7 +3936,7 @@ function transformSqlOutsideLiterals(sql4, transform) {
       }
       case "dollar": {
         const closer = `$${state.tag}$`;
-        if (sql4.startsWith(closer, i)) {
+        if (sql5.startsWith(closer, i)) {
           out.push(closer);
           state = { kind: "normal" };
           i += closer.length;
@@ -3855,15 +3980,15 @@ function transformSqlOutsideLiterals(sql4, transform) {
       }
     }
   }
-  emitCode(sql4.length);
+  emitCode(sql5.length);
   return out.join("");
 }
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function sqlReferencesQualifiedRelation(sql4, sourceSchema, sourceName) {
+function sqlReferencesQualifiedRelation(sql5, sourceSchema, sourceName) {
   let referenced = false;
-  transformSqlOutsideLiterals(sql4, (segment) => {
+  transformSqlOutsideLiterals(sql5, (segment) => {
     if (qualifiedRelationPattern(sourceSchema, sourceName).test(segment)) referenced = true;
     return segment;
   });
@@ -3874,15 +3999,16 @@ function qualifiedRelationPattern(sourceSchema, sourceName) {
   const namePattern = `(?:"${escapeRegExp(sourceName)}"|${escapeRegExp(sourceName)})`;
   return new RegExp(`(?<![\\w."])${schemaPattern}\\.${namePattern}(?![\\w"])`, "g");
 }
-function replaceQualifiedRelation(sql4, sourceSchema, sourceName, boundSchema, boundTable) {
-  return sql4.replace(qualifiedRelationPattern(sourceSchema, sourceName), `"${boundSchema}"."${boundTable}"`);
+function replaceQualifiedRelation(sql5, sourceSchema, sourceName, boundSchema, boundTable) {
+  return sql5.replace(qualifiedRelationPattern(sourceSchema, sourceName), `"${boundSchema}"."${boundTable}"`);
 }
 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;
     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)]))) } : {},
       viewDependencies: Object.fromEntries(
         (definition.views ?? []).map((view) => [view.view, [...view.dependencies].sort()])
       )
@@ -3900,7 +4026,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 primaryKeyColumns = table.primaryKey ?? [];
   if (primaryKeyColumns.length === 0) {
     throw new OrmDefinitionError(`table '${table.table}' declares no primaryKey`);
@@ -3916,13 +4042,22 @@ 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, primaryKeyColumns, self),
     ...buildIndexes2(table, self),
-    ...buildForeignKeys2(table, self, built, byName)
+    ...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}'`);
+      return foreignKey({
+        name: fk.name,
+        columns: fk.columns.map((column) => self[column]),
+        foreignColumns: fk.references.map((column) => target[column])
+      });
+    })
   ]);
   return drizzleTable.enableRLS();
 }
@@ -3939,7 +4074,8 @@ function buildColumnV2({
   column,
   singlePrimaryKey,
   compositeMembers,
-  enums
+  enums,
+  introspection
 }) {
   const factory = resolveColumnFactory(table, column, enums);
   let builder = factory(column.columnName);
@@ -3960,7 +4096,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;
 }
@@ -4145,7 +4281,8 @@ async function planMigrationV2({
   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);
@@ -4182,6 +4319,7 @@ 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((sql5) => ({ kind: "ddl", sql: sql5 })),
     ...createOrder.map((name) => ({ kind: "ddl", sql: requiredViewStatement(createDdl, name, schema, "CREATE") })),
     ...createOrder.map((name) => {
       const view = currentViewDefinitions.get(name);
@@ -4191,6 +4329,29 @@ async function planMigrationV2({
   ];
   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,
@@ -4445,7 +4606,63 @@ async function pendingKitStatementsV2({
   canonical,
   db
 }) {
-  return pendingStatements({ entities: buildDrizzleEntitiesV2(canonical), db, owned: V2_OWNED_STATEMENT });
+  const { desired, defaultDrift } = await normalizeJsonDefaultsForIntrospection(canonical, db);
+  const entities = buildDrizzleEntitiesV2(desired, { introspection: true });
+  const pending = await pendingStatements({ entities, db, owned: V2_OWNED_STATEMENT });
+  return [...orderForeignKeyAdditions(canonical, pending), ...defaultDrift, ...await pendingForeignKeyTimingStatements(canonical, db)];
+}
+async function normalizeJsonDefaultsForIntrospection(canonical, db) {
+  const defaults = canonical.tables.flatMap((table, tableIndex) => table.source ? [] : table.columns.flatMap((column, columnIndex) => column.type === "jsonb" && typeof column.default === "string" ? [{ tableIndex, columnIndex, table: table.table, column: column.columnName, value: column.default }] : []));
+  if (defaults.length === 0) return { desired: canonical, defaultDrift: [] };
+  const array = (values) => sql`ARRAY[${sql.join(values.map((value) => sql`${value}`), sql`, `)}]::text[]`;
+  const schema = ormSchemaName(canonical.namespace);
+  const result = await shimExecute(db).execute(sql`
+    SELECT desired.ordinal, desired.value::jsonb::text AS normalized,
+      attribute.attnum IS NOT NULL AS column_exists,
+      coalesce(pg_get_expr(ad.adbin, ad.adrelid) = quote_literal(desired.value::jsonb::text) || '::jsonb', false) AS matches
+    FROM unnest(${array(defaults.map((item) => item.table))}, ${array(defaults.map((item) => item.column))}, ${array(defaults.map((item) => item.value))})
+      WITH ORDINALITY AS desired(table_name, column_name, value, ordinal)
+    LEFT JOIN pg_catalog.pg_namespace namespace ON namespace.nspname = ${schema}
+    LEFT JOIN pg_catalog.pg_class relation ON relation.relnamespace = namespace.oid AND relation.relname = desired.table_name
+    LEFT JOIN pg_catalog.pg_attribute attribute ON attribute.attrelid = relation.oid AND attribute.attname = desired.column_name AND NOT attribute.attisdropped
+    LEFT JOIN pg_catalog.pg_attrdef ad ON ad.adrelid = relation.oid AND ad.adnum = attribute.attnum
+    ORDER BY desired.ordinal
+  `);
+  const rows = result.rows;
+  if (!Array.isArray(rows) || rows.length !== defaults.length || rows.some((row, index3) => Number(row.ordinal) !== index3 + 1 || typeof row.normalized !== "string" || typeof row.column_exists !== "boolean" || typeof row.matches !== "boolean")) {
+    throw new Error("invalid JSON default introspection result");
+  }
+  const desired = structuredClone(canonical);
+  const defaultDrift = [];
+  defaults.forEach((item, index3) => {
+    const row = rows[index3];
+    desired.tables[item.tableIndex].columns[item.columnIndex].default = JSON.stringify(JSON.parse(row.normalized));
+    if (row.column_exists && !row.matches) defaultDrift.push(
+      `ALTER TABLE ${quoteIdentifier(schema)}.${quoteIdentifier(item.table)} ALTER COLUMN ${quoteIdentifier(item.column)} SET DEFAULT ${quoteLiteral(item.value)}::jsonb;`
+    );
+  });
+  return { desired, defaultDrift };
+}
+async function pendingForeignKeyTimingStatements(canonical, db) {
+  const keys = canonical.tables.flatMap((table) => (table.foreignKeys ?? []).map((fk) => ({ table: table.table, fk })));
+  if (keys.length === 0) return [];
+  const schema = ormSchemaName(canonical.namespace);
+  const result = await shimExecute(db).execute(sql`
+    SELECT relation.relname AS table_name, constraint_row.conname AS name,
+      constraint_row.condeferrable AS deferrable, constraint_row.condeferred AS deferred
+    FROM pg_catalog.pg_constraint AS constraint_row
+    JOIN pg_catalog.pg_class AS relation ON relation.oid = constraint_row.conrelid
+    JOIN pg_catalog.pg_namespace AS namespace ON namespace.oid = relation.relnamespace
+    WHERE namespace.nspname = ${schema} AND constraint_row.contype = 'f'
+  `);
+  const rows = result.rows;
+  return keys.flatMap(({ table, fk }) => {
+    const actual = rows.find((row) => row.table_name === table && row.name === fk.name);
+    const deferrable = fk.deferrable !== void 0;
+    const deferred = fk.deferrable === "initially-deferred";
+    if (actual ? actual.deferrable === deferrable && actual.deferred === deferred : !deferrable) return [];
+    return [foreignKeyTimingSql(schema, table, fk.name, fk.deferrable)];
+  });
 }
 async function pendingStatements({
   entities,
@@ -4458,11 +4675,31 @@ async function pendingStatements({
   );
   return statementsToExecute.filter((statement) => !owned.test(statement));
 }
+function correctIntrospectionQuery(query) {
+  if (!is(query, SQL)) return query;
+  const compiled = new PgDialect().sqlToQuery(query);
+  let text4 = compiled.sql;
+  const indexJoin = "pg_constraint con ON con.conindid = idx.indexrelid";
+  if (text4.includes("AS generated_by_constraint") && text4.includes(indexJoin)) {
+    text4 = text4.replace(indexJoin, `${indexJoin} AND con.contype IN ('p', 'u', 'x')`);
+  }
+  const sourceJoin = "LEFT JOIN pg_catalog.pg_attribute att ON att.attnum = ANY (con.conkey)";
+  const targetJoin = "LEFT JOIN pg_catalog.pg_attribute fatt ON fatt.attnum = ANY (con.confkey)";
+  if (text4.includes(sourceJoin) && text4.includes(targetJoin) && text4.includes("AND con.contype IN ('f')")) {
+    text4 = text4.replace(
+      sourceJoin,
+      "JOIN LATERAL unnest(con.conkey, con.confkey) WITH ORDINALITY AS fk_key(source_num, target_num, ordinal) ON true LEFT JOIN pg_catalog.pg_attribute att ON att.attnum = fk_key.source_num"
+    ).replace(targetJoin, "LEFT JOIN pg_catalog.pg_attribute fatt ON fatt.attnum = fk_key.target_num").replace(/;\s*$/, "") + " ORDER BY con.conname, fk_key.ordinal";
+  }
+  if (text4 === compiled.sql) return query;
+  if (compiled.params.length !== 0) throw new Error("parameterized Drizzle catalog query cannot be normalized");
+  return sql.raw(text4);
+}
 function shimExecute(db) {
   const execute = db.execute.bind(db);
   return {
     execute: async (query) => {
-      const result = await execute(query);
+      const result = await execute(correctIntrospectionQuery(query));
       if (result && typeof result === "object" && "rows" in result) return result;
       return { rows: result };
     }
@@ -4502,21 +4739,73 @@ async function planMigration({
   const ddl = await diffStatements(hints.adjusted, snapshot);
   const policyDrops = policyDropStatements(schema, snapshotTableNames(previous, schema));
   const statements = [
-    ...policyDrops.map((sql4) => ({ kind: "security", sql: sql4 })),
-    ...hints.statements.map((sql4) => ({ kind: "hint", sql: sql4 })),
-    ...ddl.map((sql4) => ({ kind: "ddl", sql: sql4.replace(/;\s*$/, "") })),
-    ...securityStatements(definition).map((sql4) => ({ kind: "security", sql: sql4 })),
+    ...policyDrops.map((sql5) => ({ kind: "security", sql: sql5 })),
+    ...hints.statements.map((sql5) => ({ kind: "hint", sql: sql5 })),
+    ...ddl.map((sql5) => ({ kind: "ddl", sql: sql5.replace(/;\s*$/, "") })),
+    ...securityStatements(definition).map((sql5) => ({ kind: "security", sql: sql5 })),
     // PREPARE each action's executes first (plpgsql bodies don't check columns
     // at CREATE), then create the functions. Both reference the tables the DDL
     // above creates, so they close the plan.
-    ...actionPrepareChecks(definition).map((sql4) => ({ kind: "function", sql: sql4 })),
-    ...actionFunctionStatements(definition).map((sql4) => ({ kind: "function", sql: sql4 }))
+    ...actionPrepareChecks(definition).map((sql5) => ({ kind: "function", sql: sql5 })),
+    ...actionFunctionStatements(definition).map((sql5) => ({ kind: "function", sql: sql5 }))
   ];
   return { namespace: definition.namespace, schema, statements, snapshot };
 }
 var compileNamespace = (definition) => planMigration({ definition });
 var previousId2 = (snapshot) => snapshot.id;
-var IR_VERSION = 1;
+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();
+var ormMigrationExportSchema = 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 parseOrmMigrationExport(text4) {
+  if (Buffer.byteLength(text4, "utf8") > ORM_MIGRATION_EXPORT_MAX_BYTES) throw new Error("ORM migration export exceeds the size limit");
+  const exported = ormMigrationExportSchema.parse(JSON.parse(text4));
+  const { checksum: expected, ...contents } = exported;
+  if (checksum(contents) !== expected) throw new Error("ORM migration export checksum mismatch; regenerate and commit it");
+  return exported;
+}
+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;
+}
+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?",
@@ -4643,6 +4932,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 })) })
@@ -4688,12 +5004,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 = [
@@ -4723,7 +5042,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"]),
@@ -4735,6 +5054,13 @@ var compiledOperationSchema = z.object({
   /** Every table the op touches — data-token scoping + audit. */
   tableSet: z.array(z.string()).min(1),
   roots: z.array(rootIrSchema).min(1)
+}).superRefine((operation, ctx) => {
+  for (const [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 tableMetaIrSchema = z.object({
   table: z.string(),
@@ -4771,18 +5097,29 @@ var tableMetaIrSchema = z.object({
   insertable: z.array(z.string()),
   settable: z.array(z.string()),
   appendable: z.array(z.string()),
+  /**
+   * Logical columns stamped with Postgres `now()` on UPDATE (canonical
+   * `onUpdateFn`). Omitted when empty so pre-onUpdate artifacts still parse.
+   */
+  touchOnUpdate: z.array(z.string()).optional(),
   constraints: z.array(z.object({ name: z.string(), columns: z.array(z.string()) })),
   /** Depth/node caps for dynamic filter trees on this table. */
   dynamicFilterMaxDepth: z.number().int().positive().default(6),
   dynamicFilterMaxNodes: z.number().int().positive().default(64)
 });
 var compiledArtifactSchema = z.object({
-  irVersion: z.literal(IR_VERSION),
+  irVersion: irVersionSchema,
   namespace: z.string(),
   schemaHash: z.string(),
   opsHash: z.string(),
   tables: z.record(z.string(), tableMetaIrSchema),
   operations: z.record(z.string(), compiledOperationSchema)
+}).superRefine((artifact, ctx) => {
+  for (const [name, operation] of Object.entries(artifact.operations)) {
+    if (operation.irVersion > artifact.irVersion) {
+      ctx.addIssue({ code: "custom", path: ["operations", name, "irVersion"], message: "operation requires a newer IR version than its artifact" });
+    }
+  }
 });
 var IrVersionError = class extends Error {
   constructor(found) {
@@ -4793,7 +5130,7 @@ 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);
 }
 function indexByHash(artifact) {
@@ -5109,12 +5446,12 @@ async function writeMigration({
   const tip = workspace.journal.entries.at(-1);
   const ordinal = (tip?.ordinal ?? 0) + 1;
   const name = migrationName(ordinal, contentHash);
-  const sql4 = renderMigrationSql({ name, namespace: workspace.journal.namespace, contentHash, plan });
+  const sql5 = renderMigrationSql({ name, namespace: workspace.journal.namespace, contentHash, plan });
   const metaDir = join(dir, MIGRATIONS_DIRNAME, META_DIRNAME);
   await mkdir(metaDir, { recursive: true });
   const snapshotText = `${JSON.stringify(plan.snapshot, null, 2)}
 `;
-  await writeFile(join(dir, MIGRATIONS_DIRNAME, `${name}.sql`), sql4);
+  await writeFile(join(dir, MIGRATIONS_DIRNAME, `${name}.sql`), sql5);
   await writeFile(join(metaDir, `${pad(ordinal)}.snapshot.json`), snapshotText);
   const journal = {
     ...workspace.journal,
@@ -5125,7 +5462,7 @@ async function writeMigration({
         name,
         content_hash: contentHash,
         previous_content_hash: tip?.content_hash ?? null,
-        checksum: checksumOf(sql4),
+        checksum: checksumOf(sql5),
         snapshot_checksum: checksumOf(snapshotText),
         destructive
       }
@@ -5240,8 +5577,8 @@ async function checkWorkspace({
   let previousId3;
   let previousHash = null;
   for (const entry of workspace.journal.entries) {
-    const sql4 = await readMigrationSql(dir, entry);
-    if (checksumOf(sql4) !== entry.checksum) {
+    const sql5 = await readMigrationSql(dir, entry);
+    if (checksumOf(sql5) !== entry.checksum) {
       log(`${MIGRATIONS_DIRNAME}/${entry.name}.sql does not match its journal checksum \u2014 committed migrations must not be edited`);
       return 1;
     }
@@ -5281,7 +5618,7 @@ async function checkWorkspace({
   log(`migrations in sync \u2014 ${workspace.journal.entries.length} committed, tip ${tip.name}`);
   return 0;
 }
-var firstLine = (sql4) => sql4.split("\n")[0] ?? sql4;
+var firstLine = (sql5) => sql5.split("\n")[0] ?? sql5;
 
 // src/migrations/from-yaml.ts
 function convertV1DefinitionToCanonical(definition) {
@@ -5387,7 +5724,7 @@ function buildRebaseJournalEntry({ namespace, previousHash, newHash, ordinal, sn
     throw new OrmDefinitionError(`rebase ordinal must be an integer \u2265 2 (a rebase sits on an existing journal tip); got ${ordinal}`);
   }
   const name = migrationName(ordinal, newHash);
-  const sql4 = renderRebaseMigrationSql({ name, namespace, previousHash, newHash });
+  const sql5 = renderRebaseMigrationSql({ name, namespace, previousHash, newHash });
   const snapshotText = `${JSON.stringify(snapshot, null, 2)}
 `;
   const entry = {
@@ -5395,11 +5732,11 @@ function buildRebaseJournalEntry({ namespace, previousHash, newHash, ordinal, sn
     name,
     content_hash: newHash,
     previous_content_hash: previousHash,
-    checksum: checksumOf(sql4),
+    checksum: checksumOf(sql5),
     snapshot_checksum: checksumOf(snapshotText),
     destructive: false
   };
-  return { name, entry, sql: sql4, snapshotText };
+  return { name, entry, sql: sql5, snapshotText };
 }
 function renderRebaseMigrationSql({
   name,
@@ -5497,6 +5834,6 @@ function canonicalActions(value) {
   );
 }
 
-export { ACTION_REQUIRES_DENIED_SQLSTATE, ACTION_VALIDATES_FAILED_SQLSTATE, AUDIT_ACTIONS, CANONICAL_FORMAT, CAPABILITIES_CLAIM_KEY, CAPABILITY_KEY_PATTERN, CLAIMS_CONTRACT, CLAIMS_SETTING, CLAIM_KEY_PATTERN, CMP_OPS, COLUMN_BRAND, COLUMN_DEFAULT_FNS, COLUMN_TYPES2 as COLUMN_TYPES, COMPARE_OPS, CONSUMER_ROLE_SUFFIX, ColumnBuilder, DEFINITION_FILE_EXTENSIONS, ENUM_BRAND, HASH_DOMAIN, IDENTIFIER_PATTERN, IDENTIFIER_RE, INPUT_REF_KINDS, IR_VERSION, IrVersionError, LINK_BRAND, MAX_DEFINITION_FILE_BYTES, MAX_IDENTIFIER_LENGTH, MIGRATIONS_DIRNAME, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, NAMESPACE_CONFIG_FILENAMES, NAMESPACE_PATTERN, ORM_DATA_TOKEN_HEADER, ORM_SCHEMA_PREFIX, ORM_SERVICE_DATA_TOKEN_HEADER, ORM_TO_PIPELINE_TYPE, OrmDefinitionError, PredicateParseError, QUALIFIED_TABLE_PATTERN, RESERVED_COLUMN_NAMES, RESERVED_TABLE_NAMES, ROLES_CLAIM_KEY, SCHEMA_DIR, STATEMENT_KINDS, SYNCED_CONTRACT_HASH_DOMAIN, SYNCED_SOURCE_PATTERN, SYNCED_VIEW_EXECUTION_OWNER_ROLE, TABLE_BRAND, VIEW_BRAND, actionFunctionName, actionFunctionStatements, actionParamArg, actionParamOrder, actionParamSchema, actionPrepareChecks, actionSchema, actionWriteTargets, actionsInterfaceName, activeAuthoringContext, applyMigrationHints, applyMigrationHintsV2, beginAuthoringContext, buildActionParamsSchema, buildDrizzleEntities, buildDrizzleEntitiesV2, buildNamespaceDefinition, buildRebaseJournalEntry, canonicalActionSchema, canonicalColumnSchema, canonicalDefinitionSchema, canonicalEnumSchema, canonicalIndexSchema, canonicalLinkSchema, canonicalPoliciesSchema, canonicalRelations, canonicalTableSchema, canonicalViewSchema, canonicalizeDefinition, capabilityExpression, castParts, checksumOf, claimExpression, classifyDestructive, columnSchema, columnTypeSchema2 as columnTypeSchema, compileActionRequires, compileActionStatements, compileNamespace, compilePredIrToSql, compilePredicate, compiledArtifactSchema, compiledOperationSchema, computeCanonicalHash, computeDefinitionHash, computeSyncedContractHash, consumerRoleName, convertV1DefinitionToCanonical, declaredCapabilityKeys, defineEnum, defineNamespace, defineSyncedTable, defineTable, defineView, deriveColumnName, diffCommand, diffStatements, emptyJournal, emptySnapshot, endAuthoringContext, extractNamedParams, extractOrmSyncedTableContract, generateNamespaceTypes, generateSnapshot, generateSnapshotV2, identifierSchema, indexByHash, isColumnBuilder, isEnumRef, isFunctionDefault, isOwnedStatement, isOwnedStatementV2, isQualifiedReference, isSeqLink, isSeqNamespaceConfig, isSeqTable, isSeqView, limitIrSchema, loadCommittedMigrations, loadCommittedTipMigration, loadNamespaceDefinition, loadNamespaceFromDir, migrationName, namespaceConfigSchema, namespaceSchema, normalizeCanonical, normalizeIr, normalizeSnapshot, orderIrSchema, ormSchemaName, overlayWinsUnion, overrideRowMutation, parseCanonicalDefinition, parseDefinitionSources, parsePredicate, parseTableFile, parsedPredicateSchema, pendingKitStatements, pendingKitStatementsV2, planMigration, planMigrationV2, policyExpressionSchema, policyVariantSchema, predIrSchema, predicateOperands, quoteIdentifier, quoteLiteral, readMigrationSql, readMigrationWorkspace, readSnapshot, rebaseViolations, referencedCapabilities, referencedColumns, renderMigrationSql, revertOverlayMutation, rewriteSyncedSourceRelationsInViewQuery, roleExpression, rootIrSchema, securityStatements, selectionIrSchema, serializeNamespace, sqlTypeName, stableJson, syncedBackingRevokeStatements, syncedContractSurface, syncedTables, syncedViewDropStatements, syncedViewStatements, t, tableFileSchema, tableMetaIrSchema, tableReferenceSchema, toMany, toOne, toPlatformUser, typesInterfaceName, validateViewCatalogStatement, valueIrSchema, variableDefaultIrSchema, variableIrSchema, verifyRebaseIsNoop, walkPredicate, writeMigration };
+export { ACTION_REQUIRES_DENIED_SQLSTATE, ACTION_VALIDATES_FAILED_SQLSTATE, AUDIT_ACTIONS, CANONICAL_FORMAT, CAPABILITIES_CLAIM_KEY, CAPABILITY_KEY_PATTERN, CLAIMS_CONTRACT, CLAIMS_SETTING, CLAIM_KEY_PATTERN, CMP_OPS, COLUMN_BRAND, COLUMN_DEFAULT_FNS, COLUMN_IDENTIFIER_PATTERN, COLUMN_TYPES2 as COLUMN_TYPES, COMPARE_OPS, CONSUMER_ROLE_SUFFIX, ColumnBuilder, DATE_BUCKETS, DEFINITION_FILE_EXTENSIONS, ENUM_BRAND, HASH_DOMAIN, IDENTIFIER_PATTERN, IDENTIFIER_RE, INPUT_REF_KINDS, IR_VERSION, IrVersionError, LEGACY_IR_VERSION, LINK_BRAND, MAX_DEFINITION_FILE_BYTES, MAX_GENERATED_SDL_BYTES, MAX_IDENTIFIER_LENGTH, MIGRATIONS_DIRNAME, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, NAMESPACE_CONFIG_FILENAMES, NAMESPACE_PATTERN, ORM_DATA_TOKEN_HEADER, ORM_MIGRATION_EXPORT_FILE, ORM_MIGRATION_EXPORT_MAX_BYTES, ORM_REGISTRATION_MAX_BYTES, ORM_SCHEMA_PREFIX, ORM_SERVICE_DATA_TOKEN_HEADER, ORM_TO_PIPELINE_TYPE, OrmDefinitionError, PredicateParseError, QUALIFIED_TABLE_PATTERN, RESERVED_COLUMN_NAMES, RESERVED_TABLE_NAMES, ROLES_CLAIM_KEY, SCHEMA_DIR, STATEMENT_KINDS, SYNCED_CONTRACT_HASH_DOMAIN, SYNCED_SOURCE_PATTERN, SYNCED_VIEW_EXECUTION_OWNER_ROLE, TABLE_BRAND, VIEW_BRAND, actionFunctionName, actionFunctionStatements, actionParamArg, actionParamOrder, actionParamSchema, actionPrepareChecks, actionSchema, actionWriteTargets, actionsInterfaceName, activeAuthoringContext, applyMigrationHints, applyMigrationHintsV2, beginAuthoringContext, buildActionParamsSchema, buildDrizzleEntities, buildDrizzleEntitiesV2, buildNamespaceDefinition, buildRebaseJournalEntry, canonicalActionSchema, canonicalColumnSchema, canonicalDefinitionSchema, canonicalEnumSchema, canonicalIndexSchema, canonicalLinkSchema, canonicalPoliciesSchema, canonicalRelations, canonicalTableSchema, canonicalViewSchema, canonicalizeDefinition, capabilityExpression, castParts, checksumOf, claimExpression, classifyDestructive, columnSchema, columnTypeSchema2 as columnTypeSchema, compileActionRequires, compileActionStatements, compileNamespace, compilePredIrToSql, compilePredicate, compiledArtifactSchema, compiledOperationSchema, computeCanonicalHash, computeDefinitionHash, computeSyncedContractHash, consumerRoleName, convertV1DefinitionToCanonical, createOrmMigrationExport, declaredCapabilityKeys, defineEnum, defineNamespace, defineSyncedTable, defineTable, defineView, deriveColumnName, diffCommand, diffStatements, emptyJournal, emptySnapshot, endAuthoringContext, extractNamedParams, extractOrmSyncedTableContract, generateNamespaceTypes, generateSnapshot, generateSnapshotV2, identifierSchema, indexByHash, isColumnBuilder, isEnumRef, isFunctionDefault, isOwnedStatement, isOwnedStatementV2, isQualifiedReference, isSeqLink, isSeqNamespaceConfig, isSeqTable, isSeqView, limitIrSchema, loadCommittedMigrations, loadCommittedTipMigration, loadNamespaceDefinition, loadNamespaceFromDir, migrationName, namespaceConfigSchema, namespaceSchema, normalizeCanonical, normalizeIr, normalizeSnapshot, orderIrSchema, ormMigrationExportSchema, ormSchemaName, overlayWinsUnion, overrideRowMutation, parseCanonicalDefinition, parseDefinitionSources, parseOrmMigrationExport, parsePredicate, parseTableFile, parsedPredicateSchema, pendingKitStatements, pendingKitStatementsV2, planMigration, planMigrationV2, policyExpressionSchema, policyVariantSchema, predIrSchema, predicateOperands, quoteIdentifier, quoteLiteral, readMigrationSql, readMigrationWorkspace, readSnapshot, rebaseViolations, referencedCapabilities, referencedColumns, renderMigrationSql, renderOrmMigrationExport, requiredArtifactIrVersion, revertOverlayMutation, rewriteSyncedSourceRelationsInViewQuery, roleExpression, rootIrSchema, securityStatements, selectionIrSchema, serializeNamespace, sqlTypeName, stableJson, syncedBackingRevokeStatements, syncedContractSurface, syncedTables, syncedViewDropStatements, syncedViewStatements, t, tableFileSchema, tableMetaIrSchema, tableReferenceSchema, toMany, toOne, toPlatformUser, typesInterfaceName, validateViewCatalogStatement, valueIrSchema, variableDefaultIrSchema, variableIrSchema, verifyRebaseIsNoop, walkPredicate, writeMigration };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map