@sequenceholdings/orm 0.1.3 → 2.1.0

package/dist/index.cjs

@@ -36,6 +36,7 @@ var ColumnBuilder = class {
       hasDefault: false,
       defaultValue: void 0,
       defaultFn: void 0,
+      onUpdateFn: void 0,
       description: void 0,
       renamedFrom: void 0,
       cast: void 0,
@@ -71,6 +72,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;
@@ -114,6 +124,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;
@@ -141,6 +152,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";
@@ -156,6 +168,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"]);
 
@@ -264,10 +278,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
     );
   }
@@ -288,7 +302,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(
@@ -328,7 +342,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) {
@@ -417,7 +432,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);
@@ -866,6 +881,7 @@ function scalarColumnType(table, property, helper) {
 var CANONICAL_FORMAT = 2;
 var IDENTIFIER_RE = /^[a-z][a-z0-9_]*$/;
 var identifier = zod.z.string().min(1).max(63).regex(IDENTIFIER_RE);
+var columnIdentifier = zod.z.string().min(1).max(63).regex(COLUMN_IDENTIFIER_PATTERN);
 var COLUMN_TYPES = [
   "uuid",
   "text",
@@ -886,18 +902,33 @@ var canonicalEnumSchema = zod.z.object({
 var canonicalColumnSchema = zod.z.object({
   /** Property name in TS (camelCase); columnName is the Postgres name. */
   name: zod.z.string().min(1).max(63),
-  columnName: identifier,
+  columnName: columnIdentifier,
   type: zod.z.union([columnTypeSchema, zod.z.object({ enum: identifier })]),
   nullable: zod.z.boolean().default(true),
   unique: zod.z.boolean().default(false),
   /** Literal default, or one of the allowlisted SQL functions. */
   default: zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean(), zod.z.null()]).optional(),
   defaultFn: zod.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: zod.z.enum(["now()"]).optional(),
   description: zod.z.string().max(500).optional(),
   /** Migration hints — same semantics as v1. */
-  renamedFrom: identifier.optional(),
+  renamedFrom: columnIdentifier.optional(),
   cast: zod.z.string().max(200).optional(),
   deprecated: zod.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 = zod.z.object({
   name: zod.z.string().min(1).max(63),
@@ -905,15 +936,15 @@ var canonicalLinkSchema = zod.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: zod.z.boolean().default(false),
   description: zod.z.string().max(500).optional()
 });
 var canonicalIndexSchema = zod.z.object({
-  columns: zod.z.array(identifier).min(1),
+  columns: zod.z.array(columnIdentifier).min(1),
   unique: zod.z.boolean().default(false),
   name: identifier.optional()
 });
@@ -1161,6 +1192,13 @@ var canonicalCowMutationSchema = zod.z.object({
     }
   }
 });
+var canonicalForeignKeySchema = zod.z.object({
+  name: identifier,
+  columns: zod.z.array(columnIdentifier).min(1).max(8),
+  target: identifier,
+  references: zod.z.array(columnIdentifier).min(1).max(8),
+  deferrable: zod.z.enum(["initially-immediate", "initially-deferred"]).optional()
+}).strict();
 var canonicalTableSchema = zod.z.object({
   table: identifier,
   description: zod.z.string().max(2e3).optional(),
@@ -1169,7 +1207,7 @@ var canonicalTableSchema = zod.z.object({
   /** Synced/reflected read-only tables (`source: gold.*`) — v1 semantics. */
   source: zod.z.string().regex(/^gold\.[a-z][a-z0-9_]*$/).optional(),
   columns: zod.z.array(canonicalColumnSchema).default([]),
-  primaryKey: zod.z.array(identifier).min(1).max(8).optional(),
+  primaryKey: zod.z.array(columnIdentifier).min(1).max(8).optional(),
   links: zod.z.array(canonicalLinkSchema).default([]),
   indexes: zod.z.array(canonicalIndexSchema).default([]),
   policies: canonicalPoliciesSchema.default({}),
@@ -1180,14 +1218,16 @@ var canonicalTableSchema = zod.z.object({
    */
   actions: zod.z.array(canonicalActionSchema).default([]),
   /** Optional (not defaulted) so pre-CoW canonical documents keep byte-identical hashes. */
-  cowMutations: zod.z.array(canonicalCowMutationSchema).optional()
+  cowMutations: zod.z.array(canonicalCowMutationSchema).optional(),
+  /** Omitted by old definitions, preserving their existing content hashes. */
+  foreignKeys: zod.z.array(canonicalForeignKeySchema).max(100).optional()
 });
 var canonicalViewSchema = zod.z.object({
   view: identifier,
   description: zod.z.string().max(2e3).optional(),
   columns: zod.z.array(canonicalColumnSchema).min(1),
   /** Logical identity for GraphQL only; PostgreSQL views have no PK constraint. */
-  primaryKey: zod.z.array(identifier).min(1).max(8).optional(),
+  primaryKey: zod.z.array(columnIdentifier).min(1).max(8).optional(),
   links: zod.z.array(canonicalLinkSchema).default([]),
   policies: zod.z.object({ read: policyExpressionSchema }).strict(),
   query: zod.z.string().min(1).max(1e5).refine(isSingleViewQuerySql, {
@@ -1200,6 +1240,9 @@ var canonicalViewSchema = zod.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` });
     }
@@ -1233,6 +1276,45 @@ var canonicalDefinitionSchema = zod.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()) {
@@ -1368,12 +1450,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) } : {}
       };
@@ -1647,6 +1730,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" }))
@@ -1699,6 +1798,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);
     }
@@ -1957,7 +2062,16 @@ async function loadNamespaceFromDir(dir, options = {}) {
   const jiti$1 = jiti.createJiti((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)), {
     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": module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))).resolve("drizzle-orm"),
+        "@sequenceholdings/orm": options.ormModulePath,
+        "@sequenceholdings/orm/authoring": options.ormModulePath
+      }
+    } : {}
   });
   const context = beginAuthoringContext();
   try {
@@ -2516,8 +2630,8 @@ var actionSchema = zod.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)];
 }
@@ -2674,8 +2788,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);
@@ -2840,8 +2954,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}`);
     });
   }
@@ -3295,7 +3409,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));
@@ -3329,8 +3444,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}`
     );
@@ -3619,7 +3736,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 = pgCore.pgSchema(schemaName);
   const imports = { [SCHEMA_IMPORT_KEY2]: schema };
@@ -3634,11 +3751,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 })])
@@ -3706,18 +3831,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 === "-") {
@@ -3737,7 +3862,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" };
@@ -3756,9 +3881,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] ?? "" };
@@ -3790,8 +3915,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;
         }
@@ -3813,7 +3938,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;
@@ -3857,15 +3982,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;
   });
@@ -3876,15 +4001,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 = api.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()])
       )
@@ -3902,7 +4028,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`);
@@ -3918,13 +4044,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 pgCore.foreignKey({
+        name: fk.name,
+        columns: fk.columns.map((column) => self[column]),
+        foreignColumns: fk.references.map((column) => target[column])
+      });
+    })
   ]);
   return drizzleTable.enableRLS();
 }
@@ -3941,7 +4076,8 @@ function buildColumnV2({
   column,
   singlePrimaryKey,
   compositeMembers,
-  enums
+  enums,
+  introspection
 }) {
   const factory = resolveColumnFactory(table, column, enums);
   let builder = factory(column.columnName);
@@ -3962,7 +4098,7 @@ function buildColumnV2({
     }
     builder = builder.default(drizzleOrm.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(drizzleOrm.sql.raw(`${quoteLiteral(column.default)}::jsonb`)) : builder.default(column.default);
   }
   return builder;
 }
@@ -4147,7 +4283,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);
@@ -4184,6 +4321,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);
@@ -4193,6 +4331,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,
@@ -4447,7 +4608,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) => drizzleOrm.sql`ARRAY[${drizzleOrm.sql.join(values.map((value) => drizzleOrm.sql`${value}`), drizzleOrm.sql`, `)}]::text[]`;
+  const schema = ormSchemaName(canonical.namespace);
+  const result = await shimExecute(db).execute(drizzleOrm.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(drizzleOrm.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,
@@ -4460,11 +4677,31 @@ async function pendingStatements({
   );
   return statementsToExecute.filter((statement) => !owned.test(statement));
 }
+function correctIntrospectionQuery(query) {
+  if (!drizzleOrm.is(query, drizzleOrm.SQL)) return query;
+  const compiled = new pgCore.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 drizzleOrm.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 };
     }
@@ -4504,21 +4741,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 = zod.z.string().regex(/^sha256:[0-9a-f]{64}$/);
+var ormMigrationPayloadSchema = zod.z.object({
+  canonical_definition: canonicalDefinitionSchema,
+  documents: zod.z.array(zod.z.object({ path: zod.z.string().min(1).max(2048), contents: zod.z.string().max(1e6) }).strict()).max(5e3),
+  client_manifest: zod.z.object({ ops_hash: hash, operations: zod.z.record(zod.z.string(), hash) }).strict(),
+  sdl: zod.z.string().refine((value) => Buffer.byteLength(value, "utf8") <= MAX_GENERATED_SDL_BYTES, {
+    message: `sdl exceeds ${MAX_GENERATED_SDL_BYTES} bytes`
+  }),
+  schema_snapshot: zod.z.json(),
+  // The existing ORM committed-migration validator and replay engine remain
+  // authoritative. This envelope hashes the provenance, never authorizes SQL.
+  migration: zod.z.json().optional()
+}).strict();
+var ormMigrationExportSchema = zod.z.object({
+  schema_version: zod.z.literal(1),
+  schema_hash: hash,
+  payload: ormMigrationPayloadSchema,
+  checksum: zod.z.string().regex(/^[0-9a-f]{64}$/)
+}).strict();
+function checksum(value) {
+  return crypto.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 = zod.z.union([zod.z.literal(LEGACY_IR_VERSION), zod.z.literal(IR_VERSION)]);
+var operationVersionSchema = zod.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?",
@@ -4645,6 +4934,33 @@ var aggregateRootSchema = zod.z.object({
   nodes: selectionIrSchema.optional(),
   includeIf: includeIfSchema.optional()
 });
+var DATE_BUCKETS = ["year", "quarter", "month", "week", "day", "hour"];
+var groupByKeyIrSchema = zod.z.object({
+  column: zod.z.string(),
+  bucket: zod.z.enum(DATE_BUCKETS).optional()
+});
+var aggregateGroupsRootSchema = zod.z.object({
+  kind: zod.z.literal("aggregateGroups"),
+  alias: zod.z.string(),
+  table: zod.z.string(),
+  /** Composed at compile time: AND(policy, documentWhere?, dynamicFilter?). */
+  where: predIrSchema,
+  groupBy: zod.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: zod.z.array(zod.z.object({ alias: zod.z.string(), column: zod.z.string() })).default([]),
+  count: zod.z.object({ columns: zod.z.array(zod.z.string()).optional(), distinct: zod.z.boolean().optional() }).optional(),
+  sum: zod.z.array(zod.z.string()).optional(),
+  avg: zod.z.array(zod.z.string()).optional(),
+  /** Bounds the GROUP count, not the scanned rows — see MAX_GROUPS. */
+  limit: limitIrSchema,
+  offset: zod.z.object({ variable: zod.z.string().optional(), value: zod.z.number().int().optional() }).optional(),
+  includeIf: includeIfSchema.optional()
+});
 var writeValuesSchema = zod.z.union([
   zod.z.object({ slot: zod.z.string() }),
   zod.z.object({ entries: zod.z.array(zod.z.object({ column: zod.z.string(), value: valueIrSchema })) })
@@ -4690,12 +5006,15 @@ var mutationRootSchema = zod.z.object({
   insertCheck: predIrSchema.optional(),
   returning: selectionIrSchema.nullable(),
   affectedRows: zod.z.boolean().default(false),
+  /** v2: abort the transaction when the actual write count differs, regardless of selection. */
+  assertAffectedRows: zod.z.number().int().min(0).max(2147483647).optional(),
   includeIf: includeIfSchema.optional()
 });
 var rootIrSchema = zod.z.discriminatedUnion("kind", [
   selectRootSchema,
   byPkRootSchema,
   aggregateRootSchema,
+  aggregateGroupsRootSchema,
   mutationRootSchema
 ]);
 var INPUT_REF_KINDS = [
@@ -4725,7 +5044,7 @@ var variableIrSchema = zod.z.object({
   defaultValue: variableDefaultIrSchema.optional()
 });
 var compiledOperationSchema = zod.z.object({
-  irVersion: zod.z.literal(IR_VERSION),
+  irVersion: irVersionSchema,
   name: zod.z.string(),
   opHash: zod.z.string().regex(/^sha256:[0-9a-f]{64}$/),
   kind: zod.z.enum(["query", "mutation"]),
@@ -4737,6 +5056,13 @@ var compiledOperationSchema = zod.z.object({
   /** Every table the op touches — data-token scoping + audit. */
   tableSet: zod.z.array(zod.z.string()).min(1),
   roots: zod.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 = zod.z.object({
   table: zod.z.string(),
@@ -4773,18 +5099,29 @@ var tableMetaIrSchema = zod.z.object({
   insertable: zod.z.array(zod.z.string()),
   settable: zod.z.array(zod.z.string()),
   appendable: zod.z.array(zod.z.string()),
+  /**
+   * Logical columns stamped with Postgres `now()` on UPDATE (canonical
+   * `onUpdateFn`). Omitted when empty so pre-onUpdate artifacts still parse.
+   */
+  touchOnUpdate: zod.z.array(zod.z.string()).optional(),
   constraints: zod.z.array(zod.z.object({ name: zod.z.string(), columns: zod.z.array(zod.z.string()) })),
   /** Depth/node caps for dynamic filter trees on this table. */
   dynamicFilterMaxDepth: zod.z.number().int().positive().default(6),
   dynamicFilterMaxNodes: zod.z.number().int().positive().default(64)
 });
 var compiledArtifactSchema = zod.z.object({
-  irVersion: zod.z.literal(IR_VERSION),
+  irVersion: irVersionSchema,
   namespace: zod.z.string(),
   schemaHash: zod.z.string(),
   opsHash: zod.z.string(),
   tables: zod.z.record(zod.z.string(), tableMetaIrSchema),
   operations: zod.z.record(zod.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) {
@@ -4795,7 +5132,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) {
@@ -5111,12 +5448,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 = path.join(dir, MIGRATIONS_DIRNAME, META_DIRNAME);
   await promises.mkdir(metaDir, { recursive: true });
   const snapshotText = `${JSON.stringify(plan.snapshot, null, 2)}
 `;
-  await promises.writeFile(path.join(dir, MIGRATIONS_DIRNAME, `${name}.sql`), sql4);
+  await promises.writeFile(path.join(dir, MIGRATIONS_DIRNAME, `${name}.sql`), sql5);
   await promises.writeFile(path.join(metaDir, `${pad(ordinal)}.snapshot.json`), snapshotText);
   const journal = {
     ...workspace.journal,
@@ -5127,7 +5464,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
       }
@@ -5242,8 +5579,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;
     }
@@ -5283,7 +5620,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) {
@@ -5389,7 +5726,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 = {
@@ -5397,11 +5734,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,
@@ -5531,10 +5868,12 @@ exports.CLAIM_KEY_PATTERN = CLAIM_KEY_PATTERN;
 exports.CMP_OPS = CMP_OPS;
 exports.COLUMN_BRAND = COLUMN_BRAND;
 exports.COLUMN_DEFAULT_FNS = COLUMN_DEFAULT_FNS;
+exports.COLUMN_IDENTIFIER_PATTERN = COLUMN_IDENTIFIER_PATTERN;
 exports.COLUMN_TYPES = COLUMN_TYPES2;
 exports.COMPARE_OPS = COMPARE_OPS;
 exports.CONSUMER_ROLE_SUFFIX = CONSUMER_ROLE_SUFFIX;
 exports.ColumnBuilder = ColumnBuilder;
+exports.DATE_BUCKETS = DATE_BUCKETS;
 exports.DEFINITION_FILE_EXTENSIONS = DEFINITION_FILE_EXTENSIONS;
 exports.ENUM_BRAND = ENUM_BRAND;
 exports.HASH_DOMAIN = HASH_DOMAIN;
@@ -5543,8 +5882,10 @@ exports.IDENTIFIER_RE = IDENTIFIER_RE;
 exports.INPUT_REF_KINDS = INPUT_REF_KINDS;
 exports.IR_VERSION = IR_VERSION;
 exports.IrVersionError = IrVersionError;
+exports.LEGACY_IR_VERSION = LEGACY_IR_VERSION;
 exports.LINK_BRAND = LINK_BRAND;
 exports.MAX_DEFINITION_FILE_BYTES = MAX_DEFINITION_FILE_BYTES;
+exports.MAX_GENERATED_SDL_BYTES = MAX_GENERATED_SDL_BYTES;
 exports.MAX_IDENTIFIER_LENGTH = MAX_IDENTIFIER_LENGTH;
 exports.MIGRATIONS_DIRNAME = MIGRATIONS_DIRNAME;
 exports.NAMESPACE_CONFIG_BRAND = NAMESPACE_CONFIG_BRAND;
@@ -5552,6 +5893,9 @@ exports.NAMESPACE_CONFIG_FILE = NAMESPACE_CONFIG_FILE;
 exports.NAMESPACE_CONFIG_FILENAMES = NAMESPACE_CONFIG_FILENAMES;
 exports.NAMESPACE_PATTERN = NAMESPACE_PATTERN;
 exports.ORM_DATA_TOKEN_HEADER = ORM_DATA_TOKEN_HEADER;
+exports.ORM_MIGRATION_EXPORT_FILE = ORM_MIGRATION_EXPORT_FILE;
+exports.ORM_MIGRATION_EXPORT_MAX_BYTES = ORM_MIGRATION_EXPORT_MAX_BYTES;
+exports.ORM_REGISTRATION_MAX_BYTES = ORM_REGISTRATION_MAX_BYTES;
 exports.ORM_SCHEMA_PREFIX = ORM_SCHEMA_PREFIX;
 exports.ORM_SERVICE_DATA_TOKEN_HEADER = ORM_SERVICE_DATA_TOKEN_HEADER;
 exports.ORM_TO_PIPELINE_TYPE = ORM_TO_PIPELINE_TYPE;
@@ -5616,6 +5960,7 @@ exports.computeDefinitionHash = computeDefinitionHash;
 exports.computeSyncedContractHash = computeSyncedContractHash;
 exports.consumerRoleName = consumerRoleName;
 exports.convertV1DefinitionToCanonical = convertV1DefinitionToCanonical;
+exports.createOrmMigrationExport = createOrmMigrationExport;
 exports.declaredCapabilityKeys = declaredCapabilityKeys;
 exports.defineEnum = defineEnum;
 exports.defineNamespace = defineNamespace;
@@ -5657,11 +6002,13 @@ exports.normalizeCanonical = normalizeCanonical;
 exports.normalizeIr = normalizeIr;
 exports.normalizeSnapshot = normalizeSnapshot;
 exports.orderIrSchema = orderIrSchema;
+exports.ormMigrationExportSchema = ormMigrationExportSchema;
 exports.ormSchemaName = ormSchemaName;
 exports.overlayWinsUnion = overlayWinsUnion;
 exports.overrideRowMutation = overrideRowMutation;
 exports.parseCanonicalDefinition = parseCanonicalDefinition;
 exports.parseDefinitionSources = parseDefinitionSources;
+exports.parseOrmMigrationExport = parseOrmMigrationExport;
 exports.parsePredicate = parsePredicate;
 exports.parseTableFile = parseTableFile;
 exports.parsedPredicateSchema = parsedPredicateSchema;
@@ -5682,6 +6029,8 @@ exports.rebaseViolations = rebaseViolations;
 exports.referencedCapabilities = referencedCapabilities;
 exports.referencedColumns = referencedColumns;
 exports.renderMigrationSql = renderMigrationSql;
+exports.renderOrmMigrationExport = renderOrmMigrationExport;
+exports.requiredArtifactIrVersion = requiredArtifactIrVersion;
 exports.revertOverlayMutation = revertOverlayMutation;
 exports.rewriteSyncedSourceRelationsInViewQuery = rewriteSyncedSourceRelationsInViewQuery;
 exports.roleExpression = roleExpression;