@sequenceholdings/orm 0.1.3 → 2.1.0

package/dist/cli.cjs

@@ -39,9 +39,34 @@ var PredicateParseError = class extends Error {
   }
   name = "PredicateParseError";
 };
+
+// src/constants.ts
+var NAMESPACE_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
+var IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;
+var COLUMN_IDENTIFIER_PATTERN = /^_?[a-z][a-z0-9_]*$/;
+var MAX_IDENTIFIER_LENGTH = 63;
+var CAPABILITY_KEY_PATTERN = /^(?:org\/)?[a-z0-9-]{1,64}$/;
+var CLAIM_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+var QUALIFIED_TABLE_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
+var SYNCED_SOURCE_PATTERN = /^gold\.[a-z][a-z0-9_]*$/;
+var ORM_SCHEMA_PREFIX = "orm_";
+var CONSUMER_ROLE_SUFFIX = "_consumer";
+var ormSchemaName = (namespace) => `${ORM_SCHEMA_PREFIX}${namespace}`;
+var consumerRoleName = (namespace) => `${ORM_SCHEMA_PREFIX}${namespace}${CONSUMER_ROLE_SUFFIX}`;
+var DEFINITION_FILE_EXTENSIONS = [".yml", ".yaml"];
+var NAMESPACE_CONFIG_FILENAMES = /* @__PURE__ */ new Set(["namespace.yaml", "namespace.yml"]);
+var HASH_DOMAIN = "sequence-orm-definitions\0";
+var MAX_DEFINITION_FILE_BYTES = 1024 * 1024;
+var MAX_GENERATED_SDL_BYTES = 16 * 1024 * 1024;
+var ORM_REGISTRATION_MAX_BYTES = 64 * 1024 * 1024;
+var RESERVED_TABLE_NAMES = /* @__PURE__ */ new Set(["actions", "query"]);
+var RESERVED_COLUMN_NAMES = /* @__PURE__ */ new Set(["select", "order", "limit", "offset"]);
+
+// src/canonical/v2.ts
 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",
@@ -62,18 +87,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),
@@ -81,15 +121,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()
 });
@@ -337,6 +377,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(),
@@ -345,7 +392,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({}),
@@ -356,14 +403,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, {
@@ -376,6 +425,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` });
     }
@@ -409,6 +461,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 fail2 = (message) => ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "foreignKeys", index3], message });
+      if (names.has(fk.name)) fail2(`duplicate foreign key '${fk.name}'`);
+      names.add(fk.name);
+      const target = fkTables.get(fk.target);
+      if (table.source || !target || target.source) {
+        fail2("foreign keys must connect owned tables in the same namespace");
+        continue;
+      }
+      if (fk.columns.length !== fk.references.length) fail2("foreign key columns and references must have the same number of columns");
+      if (new Set(fk.columns).size !== fk.columns.length || new Set(fk.references).size !== fk.references.length) fail2("foreign key columns must not repeat");
+      for (const [position, name] of fk.columns.entries()) {
+        const sourceColumn = table.columns.find((column) => column.columnName === name);
+        const targetColumn = target.columns.find((column) => column.columnName === fk.references[position]);
+        if (!sourceColumn || !targetColumn) fail2("foreign key references an unknown column");
+        else if (JSON.stringify(sourceColumn.type) !== JSON.stringify(targetColumn.type)) fail2("foreign key column types must match");
+      }
+      const uniqueKeys = [target.primaryKey ?? [], ...target.indexes.filter((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)))) fail2("foreign key target columns must form a unique key");
+    }
   }
   const tableByName = new Map(definition.tables.map((table) => [table.table, table]));
   for (const [tableIndex, table] of definition.tables.entries()) {
@@ -504,7 +595,7 @@ var canonicalDefinitionSchema = zod.z.object({
   const visiting = /* @__PURE__ */ new Set();
   const visited = /* @__PURE__ */ new Set();
   let cycleReported = false;
-  const visit = (name, path) => {
+  const visit2 = (name, path) => {
     if (visited.has(name) || cycleReported) return;
     if (visiting.has(name)) {
       cycleReported = true;
@@ -518,12 +609,12 @@ var canonicalDefinitionSchema = zod.z.object({
     visiting.add(name);
     const view = viewByName.get(name);
     for (const dependency of view?.dependencies ?? []) {
-      if (viewByName.has(dependency)) visit(dependency, [...path, name]);
+      if (viewByName.has(dependency)) visit2(dependency, [...path, name]);
     }
     visiting.delete(name);
     visited.add(name);
   };
-  for (const view of views) visit(view.view, []);
+  for (const view of views) visit2(view.view, []);
 });
 function canonicalRelations(definition) {
   const views = (definition.views ?? []).map((view) => ({
@@ -544,12 +635,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) } : {}
       };
@@ -564,25 +656,6 @@ function normalizeCanonical(definition) {
   }
   return normalized;
 }
-
-// src/constants.ts
-var NAMESPACE_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
-var IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;
-var MAX_IDENTIFIER_LENGTH = 63;
-var CAPABILITY_KEY_PATTERN = /^(?:org\/)?[a-z0-9-]{1,64}$/;
-var CLAIM_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
-var QUALIFIED_TABLE_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
-var SYNCED_SOURCE_PATTERN = /^gold\.[a-z][a-z0-9_]*$/;
-var ORM_SCHEMA_PREFIX = "orm_";
-var CONSUMER_ROLE_SUFFIX = "_consumer";
-var ormSchemaName = (namespace) => `${ORM_SCHEMA_PREFIX}${namespace}`;
-var consumerRoleName = (namespace) => `${ORM_SCHEMA_PREFIX}${namespace}${CONSUMER_ROLE_SUFFIX}`;
-var DEFINITION_FILE_EXTENSIONS = [".yml", ".yaml"];
-var NAMESPACE_CONFIG_FILENAMES = /* @__PURE__ */ new Set(["namespace.yaml", "namespace.yml"]);
-var HASH_DOMAIN = "sequence-orm-definitions\0";
-var MAX_DEFINITION_FILE_BYTES = 1024 * 1024;
-var RESERVED_TABLE_NAMES = /* @__PURE__ */ new Set(["actions", "query"]);
-var RESERVED_COLUMN_NAMES = /* @__PURE__ */ new Set(["select", "order", "limit", "offset"]);
 function stableJson(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
   if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
@@ -1008,6 +1081,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" }))
@@ -1060,6 +1149,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);
     }
@@ -1222,7 +1317,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('cli.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('cli.cjs', document.baseURI).href))).resolve("drizzle-orm"),
+        "@sequenceholdings/orm": options.ormModulePath,
+        "@sequenceholdings/orm/authoring": options.ormModulePath
+      }
+    } : {}
   });
   const context = beginAuthoringContext();
   try {
@@ -1313,7 +1417,7 @@ var manifestOperationSchema = zod.z.object({
   kind: zod.z.enum(["query", "mutation"]),
   requires: manifestRequiresSchema
 });
-zod.z.object({
+var operationsManifestSchema = zod.z.object({
   manifestVersion: zod.z.literal(MANIFEST_VERSION),
   schemaHash: zod.z.string().min(1),
   opsHash: zod.z.string().regex(OP_HASH_RE),
@@ -1432,6 +1536,7 @@ var ORDER_BY_ENUM_VALUES = [
   "DESC_NULLS_LAST"
 ];
 var PLATFORM_USER_TYPENAME = "PlatformUser";
+var DATE_BUCKET_ENUM = "DateBucket";
 function tableNames(table) {
   const root = camelCase(table);
   const rootPascal = pascalCase(table);
@@ -1464,7 +1569,12 @@ function tableNames(table) {
     sumFields: `${type}SumFields`,
     avgFields: `${type}AvgFields`,
     aggregateBoolExp: `${type}AggregateBoolExp`,
-    aggregateBoolExpCount: `${type}AggregateBoolExpCount`
+    aggregateBoolExpCount: `${type}AggregateBoolExpCount`,
+    aggregateGroupsRoot: `${root}AggregateGroups`,
+    groupByColumnEnum: `${type}GroupByColumn`,
+    groupByInput: `${type}GroupBy`,
+    groupKey: `${type}GroupKey`,
+    aggregateGroup: `${type}AggregateGroup`
   };
 }
 
@@ -1497,7 +1607,18 @@ ${body}
 }
 `;
 }
-var IR_VERSION = 1;
+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?",
@@ -1624,6 +1745,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 })) })
@@ -1669,12 +1817,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 = [
@@ -1704,7 +1855,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"]),
@@ -1716,6 +1867,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(),
@@ -1752,18 +1910,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) {
@@ -1774,19 +1943,19 @@ var IrVersionError = class extends Error {
 function normalizeIr(raw) {
   if (!raw || typeof raw !== "object") throw new IrVersionError(void 0);
   const version = raw.irVersion;
-  if (version !== IR_VERSION) throw new IrVersionError(version);
+  if (version !== LEGACY_IR_VERSION && version !== IR_VERSION) throw new IrVersionError(version);
   return compiledArtifactSchema.parse(raw);
 }
 
 // src/predicate-v2/ast.ts
 var POLICY_COMPARE_OPS = ["=", "!=", "<", "<=", ">", ">="];
-function walkPolicy(node, visit) {
-  visit(node);
+function walkPolicy(node, visit2) {
+  visit2(node);
   if (node.kind === "and" || node.kind === "or") {
-    for (const operand of node.operands) walkPolicy(operand, visit);
+    for (const operand of node.operands) walkPolicy(operand, visit2);
   }
-  if (node.kind === "not") walkPolicy(node.operand, visit);
-  if (node.kind === "exists") walkPolicy(node.where, visit);
+  if (node.kind === "not") walkPolicy(node.operand, visit2);
+  if (node.kind === "exists") walkPolicy(node.where, visit2);
 }
 
 // src/predicate-v2/errors.ts
@@ -1924,6 +2093,10 @@ var Parser = class {
       this.expect("rparen", "')'");
       return inner;
     }
+    if (this.peekKeyword("true") || this.peekKeyword("false")) {
+      const token = this.advance();
+      return { kind: "literal", value: token.value === "true" };
+    }
     if (this.peekKeyword("capability") || this.peekKeyword("role")) {
       const fn = this.peek().value;
       const node = this.parseBooleanCall(fn);
@@ -2107,6 +2280,8 @@ var PolicyCompiler = class {
   }
   compile(node, table, depth) {
     switch (node.kind) {
+      case "literal":
+        return { kind: "const", value: node.value };
       case "and":
       case "or":
         return { kind: node.kind, operands: node.operands.map((operand) => this.compile(operand, table, depth)) };
@@ -2286,21 +2461,21 @@ function andPred(...preds) {
   if (operands.length === 1) return operands[0];
   return { kind: "and", operands };
 }
-function walkPred(pred, visit) {
-  visit(pred);
+function walkPred(pred, visit2) {
+  visit2(pred);
   switch (pred.kind) {
     case "and":
     case "or":
-      for (const operand of pred.operands) walkPred(operand, visit);
+      for (const operand of pred.operands) walkPred(operand, visit2);
       return;
     case "not":
-      walkPred(pred.operand, visit);
+      walkPred(pred.operand, visit2);
       return;
     case "exists":
-      walkPred(pred.where, visit);
+      walkPred(pred.where, visit2);
       return;
     case "aggPredicate":
-      if (pred.where) walkPred(pred.where, visit);
+      if (pred.where) walkPred(pred.where, visit2);
       return;
     default:
       return;
@@ -2317,12 +2492,12 @@ function predContainsExists(pred) {
 // src/compiler-gql/inject.ts
 function collectPinnedColumns(writePolicy) {
   const key = (pin) => `${pin.column}\0${pin.claim}`;
-  const visit = (node) => {
+  const visit2 = (node) => {
     if (node.kind === "and") {
       const merged = [];
       const seen2 = /* @__PURE__ */ new Set();
       for (const operand of node.operands) {
-        for (const pin of visit(operand)) {
+        for (const pin of visit2(operand)) {
           if (seen2.has(key(pin))) continue;
           seen2.add(key(pin));
           merged.push(pin);
@@ -2333,9 +2508,9 @@ function collectPinnedColumns(writePolicy) {
     if (node.kind === "or") {
       const [first, ...rest] = node.operands;
       if (first === void 0) return [];
-      let common = visit(first);
+      let common = visit2(first);
       for (const operand of rest) {
-        const branch = new Set(visit(operand).map(key));
+        const branch = new Set(visit2(operand).map(key));
         common = common.filter((pin) => branch.has(key(pin)));
         if (common.length === 0) break;
       }
@@ -2347,7 +2522,7 @@ function collectPinnedColumns(writePolicy) {
     return [];
   };
   const seen = /* @__PURE__ */ new Set();
-  return visit(writePolicy).filter((pin) => {
+  return visit2(writePolicy).filter((pin) => {
     if (seen.has(pin.column)) return false;
     seen.add(pin.column);
     return true;
@@ -2441,6 +2616,11 @@ var PolicyInjector = class {
           where: andPred(this.read(root.table), this.injectDocPred(root.where, root.table)),
           ...root.nodes ? { nodes: this.injectSelection(root.nodes, root.table) } : {}
         };
+      case "aggregateGroups":
+        return {
+          ...root,
+          where: andPred(this.read(root.table), this.injectDocPred(root.where, root.table))
+        };
       case "mutation":
         return this.injectMutation(root);
     }
@@ -2533,20 +2713,33 @@ function collectTableSet(roots, ctx) {
   };
   for (const root of roots) {
     tables.add(root.table);
-    if (root.kind === "select" || root.kind === "byPk") {
-      visitPred(root.where, root.table);
-      visitSelection(root.selection, root.table);
-    }
-    if (root.kind === "aggregate") {
-      visitPred(root.where, root.table);
-      if (root.nodes) visitSelection(root.nodes, root.table);
-    }
-    if (root.kind === "mutation") {
-      if (root.cowSynced !== void 0) tables.add(root.cowSynced);
-      if (root.where) visitPred(root.where, root.table);
-      if (root.insertCheck) visitPred(root.insertCheck, root.table);
-      if (root.cowCopyCheck) visitPred(root.cowCopyCheck, root.table);
-      if (root.returning) visitSelection(root.returning, root.table);
+    switch (root.kind) {
+      case "select":
+      case "byPk":
+        visitPred(root.where, root.table);
+        visitSelection(root.selection, root.table);
+        break;
+      case "aggregate":
+        visitPred(root.where, root.table);
+        if (root.nodes) visitSelection(root.nodes, root.table);
+        break;
+      case "aggregateGroups":
+        visitPred(root.where, root.table);
+        break;
+      case "mutation":
+        if (root.cowSynced !== void 0) tables.add(root.cowSynced);
+        if (root.where) visitPred(root.where, root.table);
+        if (root.insertCheck) visitPred(root.insertCheck, root.table);
+        if (root.cowCopyCheck) visitPred(root.cowCopyCheck, root.table);
+        if (root.returning) visitSelection(root.returning, root.table);
+        break;
+      default: {
+        const exhausted = root;
+        throw new DocumentCompileError(
+          `internal: unhandled root kind in tableSet collection ${JSON.stringify(exhausted)}`,
+          "internal"
+        );
+      }
     }
   }
   return [...tables].sort();
@@ -2564,7 +2757,12 @@ function typeNameForTable(table) {
 }
 function queryRootNames(table) {
   const names = tableNames(table);
-  return { select: names.selectRoot, byPk: names.byPkRoot, aggregate: names.aggregateRoot };
+  return {
+    select: names.selectRoot,
+    byPk: names.byPkRoot,
+    aggregate: names.aggregateRoot,
+    aggregateGroups: names.aggregateGroupsRoot
+  };
 }
 function mutationRootNames(table) {
   const names = tableNames(table);
@@ -2645,7 +2843,14 @@ function resolveColumnEntries(table, enums, diagnostics) {
         type = { enum: enumDef.name, values: [...enumDef.values] };
       }
     }
-    return { name: column.name, columnName: column.columnName, type, nullable: column.nullable, deprecated: column.deprecated };
+    return {
+      name: column.name,
+      columnName: column.columnName,
+      type,
+      nullable: column.nullable,
+      deprecated: column.deprecated,
+      onUpdateFn: column.onUpdateFn !== void 0
+    };
   });
 }
 function logicalColumn(entries, ref) {
@@ -2694,6 +2899,7 @@ function buildCompileContext(rawCanonical) {
       primaryKey2.push(resolved);
     }
     const active = entries.filter((c) => !c.deprecated);
+    const touchOnUpdate = isView ? [] : active.filter((c) => c.onUpdateFn).map((c) => c.name);
     const constraints = [];
     if (primaryKey2.length > 0) constraints.push({ name: `${table.table}_pkey`, columns: [...primaryKey2] });
     for (const column of table.columns) {
@@ -2714,14 +2920,15 @@ function buildCompileContext(rawCanonical) {
       // Synced twins (and views reading them, resolved transitively below)
       // are claims-gated — see tableMetaIrSchema.claimsGated.
       claimsGated: relationIsClaimsGated(table.table),
-      columns: entries.map(({ deprecated: _deprecated, ...column }) => column),
+      columns: entries.map(({ deprecated: _deprecated, onUpdateFn: _onUpdateFn, ...column }) => column),
       primaryKey: isView ? primaryKey2 : primaryKey2.length > 0 ? primaryKey2 : ["id"],
       links: [],
       filterable: entries.map((c) => c.name),
       orderable: entries.filter((c) => c.type !== "jsonb").map((c) => c.name),
       insertable: isView ? [] : active.map((c) => c.name),
-      settable: isView ? [] : active.map((c) => c.name),
+      settable: isView ? [] : active.filter((c) => !c.onUpdateFn).map((c) => c.name),
       appendable: isView ? [] : active.filter((c) => c.type === "jsonb").map((c) => c.name),
+      ...touchOnUpdate.length > 0 ? { touchOnUpdate } : {},
       constraints: isView ? [] : constraints,
       dynamicFilterMaxDepth: 6,
       dynamicFilterMaxNodes: 64
@@ -2742,7 +2949,7 @@ function buildCompileContext(rawCanonical) {
         });
         continue;
       }
-      const targetEntries = targetName === PLATFORM_USER_TABLE ? target.columns.map((c) => ({ ...c, deprecated: false })) : columnEntries.get(targetName);
+      const targetEntries = targetName === PLATFORM_USER_TABLE ? target.columns.map((c) => ({ ...c, deprecated: false, onUpdateFn: false })) : columnEntries.get(targetName);
       const onEntries = link.kind === "toMany" ? targetEntries : entries;
       const referencesEntries = link.kind === "toMany" ? entries : targetEntries;
       const on = logicalColumn(onEntries, link.on);
@@ -2839,6 +3046,9 @@ function buildCompileContext(rawCanonical) {
       queryRoots.set(roots.byPk, { kind: "byPk", table: table.table });
     }
     queryRoots.set(roots.aggregate, { kind: "aggregate", table: table.table });
+    if (table.columns.some((column) => column.type !== "jsonb")) {
+      queryRoots.set(roots.aggregateGroups, { kind: "aggregateGroups", table: table.table });
+    }
     const hasWritePolicy = table.policies.write !== void 0 || table.policies.insert !== void 0 || table.policies.update !== void 0;
     if (!viewNames.has(table.table) && table.source === void 0 && hasWritePolicy) {
       for (const [op, field] of Object.entries(mutationRootNames(table.table))) {
@@ -2974,6 +3184,16 @@ function computeOpsHash(opHashes) {
 }
 var DEFAULT_LIMIT = 100;
 var MAX_LIMIT = 1e3;
+var MAX_GROUPS = 1e3;
+var DATE_BUCKET_BY_ENUM = {
+  YEAR: "year",
+  QUARTER: "quarter",
+  MONTH: "month",
+  WEEK: "week",
+  DAY: "day",
+  HOUR: "hour"
+};
+var BUCKETABLE_TYPES = /* @__PURE__ */ new Set(["timestamptz", "date"]);
 var BOOLEXP_OPS = {
   _eq: "eq",
   _neq: "neq",
@@ -3005,6 +3225,14 @@ function fail(message, code, candidates = []) {
 function argsByName(field) {
   return new Map((field.arguments ?? []).map((arg) => [arg.name.value, arg]));
 }
+function* aggregateBlockFields(selectionSet) {
+  for (const node of selectionSet.selections) {
+    if (node.kind !== graphql.Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+    if (node.name.value === "__typename") continue;
+    if (node.alias) fail(`aliases are not supported inside aggregate blocks ('${node.alias.value}')`, "invalid-aggregate");
+    yield node;
+  }
+}
 function assertKnownArgs(field, allowed) {
   for (const arg of field.arguments ?? []) {
     if (!allowed.includes(arg.name.value)) {
@@ -3305,11 +3533,8 @@ var OperationLowerer = class {
   lowerAggregateSelection(selectionSet, table) {
     const result = {};
     let sawAggregate = false;
-    for (const node of selectionSet.selections) {
-      if (node.kind !== graphql.Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+    for (const node of aggregateBlockFields(selectionSet)) {
       const name = node.name.value;
-      if (name === "__typename") continue;
-      if (node.alias) fail(`aliases are not supported inside aggregate blocks ('${node.alias.value}')`, "invalid-aggregate");
       if (name === "nodes") {
         if (!node.selectionSet) fail("'nodes' needs a selection set", "invalid-aggregate");
         result.nodes = this.lowerSelection(node.selectionSet, table);
@@ -3319,48 +3544,116 @@ var OperationLowerer = class {
       if (sawAggregate) fail("one aggregate block per field \u2014 alias the root instead", "invalid-aggregate");
       sawAggregate = true;
       if (!node.selectionSet) fail("'aggregate' needs a selection set", "invalid-aggregate");
-      for (const aggField of node.selectionSet.selections) {
-        if (aggField.kind !== graphql.Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
-        const aggName = aggField.name.value;
-        if (aggName === "__typename") continue;
-        if (aggField.alias) fail(`aliases are not supported inside aggregate blocks ('${aggField.alias.value}')`, "invalid-aggregate");
-        if (aggName === "count") {
-          assertKnownArgs(aggField, ["columns", "distinct"]);
-          const args = argsByName(aggField);
-          const count = {};
-          const columns = args.get("columns");
-          if (columns) count.columns = this.lowerDistinctOn(columns.value, table);
-          const distinct = args.get("distinct");
-          if (distinct) {
-            if (distinct.value.kind !== graphql.Kind.BOOLEAN) fail("count(distinct:) must be a boolean literal", "invalid-aggregate");
-            count.distinct = distinct.value.value;
-          }
-          result.count = count;
-          continue;
+      Object.assign(result, this.lowerAggregateFields(node.selectionSet, table));
+    }
+    if (!sawAggregate && !result.nodes) fail("aggregate selection needs an aggregate or nodes block", "invalid-aggregate");
+    return result;
+  }
+  /**
+   * The `{ key {…} aggregate {…} }` block of a grouped aggregate root. Same
+   * `aggregate` sub-block as the ungrouped shape (shared via
+   * `lowerAggregateFields`), but `key` replaces `nodes` — see the IR comment on
+   * `aggregateGroupsRootSchema` for why grouped roots have no `nodes`.
+   */
+  lowerGroupedAggregateSelection(selectionSet, table, groupBy) {
+    const groupColumns = new Set(groupBy.map((entry) => entry.column));
+    const result = { key: [] };
+    let sawAggregate = false;
+    let sawKey = false;
+    for (const node of aggregateBlockFields(selectionSet)) {
+      const name = node.name.value;
+      if (name === "key") {
+        if (sawKey) fail("one key block per grouped aggregate", "invalid-aggregate");
+        sawKey = true;
+        if (!node.selectionSet) fail("'key' needs a selection set", "invalid-aggregate");
+        result.key = this.lowerGroupKeySelection(node.selectionSet, table, groupColumns);
+        continue;
+      }
+      if (name === "nodes") {
+        fail("'nodes' is not available on a grouped aggregate \u2014 query the rows separately", "invalid-aggregate", ["key", "aggregate"]);
+      }
+      if (name !== "aggregate") fail(`unknown grouped-aggregate field '${name}'`, "invalid-aggregate", ["key", "aggregate"]);
+      if (sawAggregate) fail("one aggregate block per field \u2014 alias the root instead", "invalid-aggregate");
+      sawAggregate = true;
+      if (!node.selectionSet) fail("'aggregate' needs a selection set", "invalid-aggregate");
+      Object.assign(result, this.lowerAggregateFields(node.selectionSet, table));
+    }
+    const rendersAggregate = result.count !== void 0 || (result.sum?.length ?? 0) > 0 || (result.avg?.length ?? 0) > 0;
+    if (result.key.length === 0 && !rendersAggregate) {
+      fail(
+        "grouped aggregate needs at least one key column or an aggregate \u2014 a block selecting only __typename produces nothing",
+        "invalid-aggregate",
+        ["key", "aggregate"]
+      );
+    }
+    return result;
+  }
+  /**
+   * `key { month officer }` → the projected group columns. Every field must be
+   * one of the query's own group keys: any other column is indeterminate
+   * within a group, so selecting it is a document error rather than an
+   * arbitrary pick.
+   */
+  lowerGroupKeySelection(selectionSet, table, groupColumns) {
+    const key = [];
+    for (const node of selectionSet.selections) {
+      if (node.kind !== graphql.Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+      const name = node.name.value;
+      if (name === "__typename") continue;
+      if (!this.column(table, name)) {
+        fail(`unknown key column '${name}' on '${table}'`, "unknown-column", [...groupColumns]);
+      }
+      if (!groupColumns.has(name)) {
+        fail(
+          `key column '${name}' is not one of this query's groupBy keys \u2014 it has no single value within a group`,
+          "invalid-group-key",
+          [...groupColumns]
+        );
+      }
+      key.push({ alias: node.alias?.value ?? name, column: name });
+    }
+    return key;
+  }
+  /** The `count` / `sum {…}` / `avg {…}` fields inside an `aggregate { … }` block. */
+  lowerAggregateFields(selectionSet, table) {
+    const result = {};
+    for (const aggField of aggregateBlockFields(selectionSet)) {
+      const aggName = aggField.name.value;
+      if (aggName === "count") {
+        assertKnownArgs(aggField, ["columns", "distinct"]);
+        const args = argsByName(aggField);
+        const count = {};
+        const columns = args.get("columns");
+        if (columns) count.columns = this.lowerDistinctOn(columns.value, table);
+        const distinct = args.get("distinct");
+        if (distinct) {
+          if (distinct.value.kind !== graphql.Kind.BOOLEAN) fail("count(distinct:) must be a boolean literal", "invalid-aggregate");
+          count.distinct = distinct.value.value;
         }
-        if (aggName === "sum" || aggName === "avg") {
-          if (!aggField.selectionSet) fail(`'${aggName}' needs a column selection`, "invalid-aggregate");
-          const columns = [];
-          for (const columnField of aggField.selectionSet.selections) {
-            if (columnField.kind !== graphql.Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
-            if (columnField.name.value === "__typename") continue;
-            const column = this.column(table, columnField.name.value);
-            if (!column || typeof column.type !== "string" || !NUMERIC_TYPES.has(column.type)) {
-              fail(
-                `'${aggName}' supports numeric columns only, got '${columnField.name.value}' on '${table}'`,
-                "invalid-aggregate",
-                this.meta(table).columns.filter((c) => typeof c.type === "string" && NUMERIC_TYPES.has(c.type)).map((c) => c.name)
-              );
-            }
-            columns.push(columnField.name.value);
+        result.count = count;
+        continue;
+      }
+      if (aggName === "sum" || aggName === "avg") {
+        if (!aggField.selectionSet) fail(`'${aggName}' needs a column selection`, "invalid-aggregate");
+        const columns = [];
+        for (const columnField of aggField.selectionSet.selections) {
+          if (columnField.kind !== graphql.Kind.FIELD) fail("fragments must be flattened before lowering", "internal");
+          if (columnField.name.value === "__typename") continue;
+          const column = this.column(table, columnField.name.value);
+          if (!column || typeof column.type !== "string" || !NUMERIC_TYPES.has(column.type)) {
+            fail(
+              `'${aggName}' supports numeric columns only, got '${columnField.name.value}' on '${table}'`,
+              "invalid-aggregate",
+              this.meta(table).columns.filter((c) => typeof c.type === "string" && NUMERIC_TYPES.has(c.type)).map((c) => c.name)
+            );
           }
-          result[aggName] = columns;
-          continue;
+          columns.push(columnField.name.value);
         }
-        fail(`aggregate '${aggName}' is not supported in v2.0 (count/sum/avg only)`, "invalid-aggregate", ["count", "sum", "avg"]);
+        result[aggName] = columns;
+        continue;
       }
+      fail(`aggregate '${aggName}' is not supported in v2.0 (count/sum/avg only)`, "invalid-aggregate", ["count", "sum", "avg"]);
     }
-    if (!sawAggregate && !result.nodes) fail("aggregate selection needs an aggregate or nodes block", "invalid-aggregate");
     return result;
   }
   // -------------------------------------------------------------------------
@@ -3370,19 +3663,49 @@ var OperationLowerer = class {
     const roots = [];
     for (const node of operation.selectionSet.selections) {
       if (node.kind !== graphql.Kind.FIELD) fail("fragments are not supported at the operation root", "invalid-root");
+      if (node.selectionSet) graphql.visit(node.selectionSet, {
+        Directive(directive) {
+          if (directive.name.value === "assertAffectedRows") {
+            fail("@assertAffectedRows is supported on mutation roots only", "invalid-affected-row-assertion");
+          }
+        }
+      });
+      const assertion = this.parseAffectedRowAssertion(node, kind);
       const gate = this.parseRootDirectives(node);
       if (gate.omit) continue;
       const root = kind === "query" ? this.lowerQueryRoot(node) : this.lowerMutationRoot(node);
-      roots.push(gate.includeIf ? { ...root, includeIf: gate.includeIf } : root);
+      const guarded = root.kind === "mutation" && assertion !== void 0 ? { ...root, assertAffectedRows: assertion } : root;
+      roots.push(gate.includeIf ? { ...guarded, includeIf: gate.includeIf } : guarded);
     }
     if (roots.length === 0) fail("operation has no roots (all statically skipped?)", "invalid-root");
     return roots;
   }
+  parseAffectedRowAssertion(node, kind) {
+    const assertions = node.directives?.filter((directive) => directive.name.value === "assertAffectedRows") ?? [];
+    if (!assertions.length) return void 0;
+    if (kind !== "mutation" || assertions.length !== 1) {
+      fail("@assertAffectedRows is supported once per mutation root", "invalid-affected-row-assertion");
+    }
+    if (node.directives?.some((directive) => ["include", "skip"].includes(directive.name.value))) {
+      fail("an @assertAffectedRows root cannot use @include or @skip", "invalid-affected-row-assertion");
+    }
+    const args = assertions[0].arguments;
+    const arg = args?.[0];
+    if (args?.length !== 1 || arg?.name.value !== "exactly" || arg.value.kind !== graphql.Kind.INT) {
+      fail("@assertAffectedRows(exactly:) requires a document-authored nonnegative Int literal", "invalid-affected-row-assertion");
+    }
+    const count = Number(arg.value.value);
+    if (!Number.isInteger(count) || count < 0 || count > 2147483647) {
+      fail("@assertAffectedRows(exactly:) must be between 0 and 2147483647", "invalid-affected-row-assertion");
+    }
+    return count;
+  }
   parseRootDirectives(node) {
     let includeIf;
     let omit = false;
     for (const directive of node.directives ?? []) {
       const name = directive.name.value;
+      if (name === "assertAffectedRows") continue;
       if (name !== "include" && name !== "skip") {
         fail(`directive @${name} is not supported on fields`, "unknown-directive", ["include", "skip"]);
       }
@@ -3431,6 +3754,9 @@ var OperationLowerer = class {
       const pk = this.lowerPkArgs(node, table);
       return { kind: "byPk", alias, table, selection: this.lowerSelection(node.selectionSet, table), pk, where: CONST_TRUE };
     }
+    if (rootInfo.kind === "aggregateGroups") {
+      return this.lowerAggregateGroupsRoot(node, { alias, table });
+    }
     assertKnownArgs(node, ["where"]);
     if (!node.selectionSet) fail(`'${name}' needs a selection set`, "invalid-selection");
     const whereArg = args.get("where");
@@ -3443,6 +3769,108 @@ var OperationLowerer = class {
       ...aggregate
     };
   }
+  /** `<t>AggregateGroups(where:, groupBy:, limit:, offset:)` → an aggregateGroups root. */
+  lowerAggregateGroupsRoot(node, { alias, table }) {
+    assertKnownArgs(node, ["where", "groupBy", "limit", "offset"]);
+    if (!node.selectionSet) fail(`'${node.name.value}' needs a selection set`, "invalid-selection");
+    const args = argsByName(node);
+    const groupByArg = args.get("groupBy");
+    if (!groupByArg) fail(`'${node.name.value}' requires a 'groupBy' argument`, "missing-group-by");
+    const whereArg = args.get("where");
+    const groupBy = this.lowerGroupBy(groupByArg.value, table);
+    const aggregate = this.lowerGroupedAggregateSelection(node.selectionSet, table, groupBy);
+    const offset = this.lowerOffset(args.get("offset")?.value);
+    return {
+      kind: "aggregateGroups",
+      alias,
+      table,
+      where: whereArg ? this.lowerBoolExp(whereArg.value, table) : CONST_TRUE,
+      groupBy,
+      key: aggregate.key,
+      ...aggregate.count ? { count: aggregate.count } : {},
+      ...aggregate.sum ? { sum: aggregate.sum } : {},
+      ...aggregate.avg ? { avg: aggregate.avg } : {},
+      limit: this.lowerGroupLimit(args.get("limit")?.value),
+      ...offset ? { offset } : {}
+    };
+  }
+  /**
+   * `groupBy: [{ column: startedAt, bucket: MONTH }, …]` → GroupByKeyIr[].
+   *
+   * Document-authored only: a whole-argument variable is rejected rather than
+   * becoming a §4f slot. Group keys choose which expressions reach GROUP BY,
+   * and dynamic-input.ts refuses aggregation shapes from client input on the
+   * same reasoning — `where` stays dynamic, which is what runtime filtering
+   * actually needs.
+   */
+  lowerGroupBy(node, table) {
+    if (node.kind === graphql.Kind.VARIABLE) {
+      fail(
+        `groupBy on '${table}' must be written in the document \u2014 it cannot come from a variable`,
+        "dynamic-group-by"
+      );
+    }
+    const items = node.kind === graphql.Kind.LIST ? node.values : [node];
+    if (items.length === 0) fail(`groupBy on '${table}' needs at least one key`, "invalid-group-by");
+    const seen = /* @__PURE__ */ new Set();
+    return items.map((item) => {
+      if (item.kind !== graphql.Kind.OBJECT) {
+        fail(`groupBy entries on '${table}' must be objects like { column: foo }`, "invalid-group-by");
+      }
+      const fields = new Map(item.fields.map((field) => [field.name.value, field.value]));
+      for (const key of fields.keys()) {
+        if (key !== "column" && key !== "bucket") {
+          fail(`unknown groupBy field '${key}' on '${table}'`, "invalid-group-by", ["column", "bucket"]);
+        }
+      }
+      const columnNode = fields.get("column");
+      if (!columnNode) fail(`groupBy entries on '${table}' need a 'column'`, "invalid-group-by");
+      if (columnNode.kind !== graphql.Kind.ENUM) {
+        fail(`groupBy column on '${table}' must be a group-by column enum value`, "invalid-group-by");
+      }
+      const column = this.column(table, columnNode.value);
+      if (!column) {
+        fail(`unknown groupBy column '${columnNode.value}' on '${table}'`, "unknown-column", this.meta(table).columns.map((c) => c.name));
+      }
+      if (column.type === "jsonb") {
+        fail(`groupBy column '${table}.${columnNode.value}' is jsonb and cannot be a group key`, "invalid-group-by");
+      }
+      const bucketNode = fields.get("bucket");
+      let bucket;
+      if (bucketNode) {
+        if (bucketNode.kind !== graphql.Kind.ENUM) {
+          fail(`groupBy bucket on '${table}.${columnNode.value}' must be a DateBucket enum value`, "invalid-group-by", Object.keys(DATE_BUCKET_BY_ENUM));
+        }
+        bucket = DATE_BUCKET_BY_ENUM[bucketNode.value];
+        if (!bucket) {
+          fail(`unknown DateBucket '${bucketNode.value}'`, "invalid-group-by", Object.keys(DATE_BUCKET_BY_ENUM));
+        }
+        if (typeof column.type !== "string" || !BUCKETABLE_TYPES.has(column.type)) {
+          fail(
+            `groupBy bucket is only valid on date/timestamptz columns \u2014 '${table}.${columnNode.value}' is ${typeof column.type === "string" ? column.type : "an enum"}`,
+            "invalid-group-by"
+          );
+        }
+      }
+      if (seen.has(columnNode.value)) {
+        fail(`duplicate groupBy column '${columnNode.value}' on '${table}'`, "invalid-group-by");
+      }
+      seen.add(columnNode.value);
+      return bucket ? { column: columnNode.value, bucket } : { column: columnNode.value };
+    });
+  }
+  /** Like lowerLimit, but bounded by MAX_GROUPS and defaulting to it. */
+  lowerGroupLimit(node) {
+    const base = { default: MAX_GROUPS, max: MAX_GROUPS };
+    if (!node) return base;
+    if (node.kind === graphql.Kind.VARIABLE) return { ...base, variable: node.name.value };
+    if (node.kind === graphql.Kind.INT) {
+      const value = Number(node.value);
+      if (value < 1) fail("limit must be a positive integer", "invalid-limit");
+      return { ...base, value: Math.min(value, MAX_GROUPS) };
+    }
+    fail("limit must be an integer literal or a variable", "invalid-limit");
+  }
   /** byPk-style pk arguments: one argument per primary-key column, exactly. */
   lowerPkArgs(node, table) {
     const meta = this.meta(table);
@@ -3952,7 +4380,7 @@ function compileNamespace({ canonical, sdl, documents }) {
         const loweredRoots = lowerOperation({ restricted: { ...restricted, definition: flattened }, ctx });
         const { roots, tableSet } = injectPolicies({ roots: loweredRoots, ctx });
         operations[restricted.name] = {
-          irVersion: IR_VERSION,
+          irVersion: roots.some((root) => root.kind === "mutation" && root.assertAffectedRows !== void 0) ? IR_VERSION : LEGACY_IR_VERSION,
           name: restricted.name,
           opHash: computeOpHash({ definition: flattened, schemaHash }),
           kind: restricted.kind,
@@ -3979,7 +4407,7 @@ function compileNamespace({ canonical, sdl, documents }) {
   }
   if (diagnostics.some((d) => d.severity === "error")) return { ok: false, diagnostics };
   const artifact = {
-    irVersion: IR_VERSION,
+    irVersion: requiredArtifactIrVersion(Object.values(operations)),
     namespace: ctx.namespace,
     schemaHash,
     opsHash: computeOpsHash(Object.values(operations).map((op) => op.opHash)),
@@ -4179,12 +4607,12 @@ function castParts(cast) {
 
 // src/predicate/ast.ts
 var COMPARE_OPS = ["=", "!=", "<", "<=", ">", ">="];
-function walkPredicate(predicate, visit) {
-  visit(predicate);
+function walkPredicate(predicate, visit2) {
+  visit2(predicate);
   if (predicate.kind === "and" || predicate.kind === "or") {
-    for (const operand of predicate.operands) walkPredicate(operand, visit);
+    for (const operand of predicate.operands) walkPredicate(operand, visit2);
   }
-  if (predicate.kind === "not") walkPredicate(predicate.operand, visit);
+  if (predicate.kind === "not") walkPredicate(predicate.operand, visit2);
 }
 function predicateOperands(predicate) {
   const operands = [];
@@ -5159,7 +5587,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 };
@@ -5174,11 +5602,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 })])
@@ -5422,9 +5858,10 @@ function replaceQualifiedRelation(sql4, sourceSchema, sourceName, boundSchema, b
 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()])
       )
@@ -5442,7 +5879,7 @@ function buildViewColumnV2({
   if (!column.nullable) builder = builder.notNull();
   return builder;
 }
-function buildTable2(schema, table, built, enums, byName) {
+function buildTable2(schema, table, built, enums, byName, introspection) {
   const primaryKeyColumns2 = table.primaryKey ?? [];
   if (primaryKeyColumns2.length === 0) {
     throw new OrmDefinitionError(`table '${table.table}' declares no primaryKey`);
@@ -5458,13 +5895,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, primaryKeyColumns2, 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();
 }
@@ -5481,7 +5927,8 @@ function buildColumnV2({
   column,
   singlePrimaryKey,
   compositeMembers,
-  enums
+  enums,
+  introspection
 }) {
   const factory = resolveColumnFactory(table, column, enums);
   let builder = factory(column.columnName);
@@ -5502,7 +5949,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;
 }
@@ -5687,7 +6134,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);
@@ -5724,6 +6172,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((sql4) => ({ kind: "ddl", sql: sql4 })),
     ...createOrder.map((name) => ({ kind: "ddl", sql: requiredViewStatement(createDdl, name, schema, "CREATE") })),
     ...createOrder.map((name) => {
       const view = currentViewDefinitions.get(name);
@@ -5733,6 +6182,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,
@@ -6853,8 +7325,12 @@ function generateSdl(canonical, options = {}) {
     '"""Gates an operation behind a platform capability or custom role \u2014 checked by the data plane before execution."""\ndirective @requires(capability: String, role: String) on QUERY | MUTATION'
   );
   blocks.push("directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT");
+  blocks.push(
+    '"""Abort the entire mutation unless this root affects exactly the document-authored number of rows. Mutation roots only; cannot be conditional."""\ndirective @assertAffectedRows(exactly: Int!) on FIELD'
+  );
   for (const scalar2 of CUSTOM_SCALARS) blocks.push(`scalar ${scalar2}`);
   blocks.push(renderEnum(ORDER_BY_ENUM, [...ORDER_BY_ENUM_VALUES]));
+  blocks.push(renderEnum(DATE_BUCKET_ENUM, DATE_BUCKETS.map((bucket) => bucket.toUpperCase())));
   for (const enumName of [...usedEnums].sort()) {
     const entry = enumByName.get(enumName);
     if (!entry) continue;
@@ -6884,9 +7360,24 @@ function generateSdl(canonical, options = {}) {
   blocks.push(renderQueryRoot(tables, namesByTable));
   const mutationRoot = renderMutationRoot(tables, namesByTable);
   if (mutationRoot !== null) blocks.push(mutationRoot);
+  assertNoDuplicateTypeNames(blocks);
   return `${blocks.join("\n\n")}
 `;
 }
+var TYPE_DECLARATION_RE = /^(?:type|input|enum|scalar|interface|union)\s+([_A-Za-z][_0-9A-Za-z]*)/;
+function assertNoDuplicateTypeNames(blocks) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const block of blocks) {
+    const declared = TYPE_DECLARATION_RE.exec(block)?.[1];
+    if (declared === void 0) continue;
+    if (seen.has(declared)) {
+      throw new SdlGenerationError(
+        `Generated schema declares "${declared}" twice. A canonical enum or table name is PascalCased into this GraphQL type name and collides with another declaration (for example an enum named "date_bucket" renders as "DateBucket", the shared bucket enum). Rename the offending enum or table.`
+      );
+    }
+    seen.add(declared);
+  }
+}
 function assertEnumValue(value, context) {
   if (!GRAPHQL_NAME_RE2.test(value) || RESERVED_ENUM_VALUES.has(value)) {
     throw new SdlGenerationError(
@@ -6975,7 +7466,8 @@ function renderTableBlocks(ctx) {
     renderSelectColumnEnum(ctx),
     renderOrderByInput(ctx),
     renderBoolExp(ctx),
-    ...renderAggregateTypes(ctx)
+    ...renderAggregateTypes(ctx),
+    ...renderGroupByTypes(ctx)
   ];
   if (ctx.emitAggregateBoolExp) blocks.push(...renderAggregateBoolExp(ctx));
   const pk = primaryKeyColumns(table);
@@ -7112,6 +7604,32 @@ ${sumLines.join("\n")}
   }
   return blocks;
 }
+function groupableColumns(table) {
+  return table.columns.filter((column) => column.type !== "jsonb");
+}
+function renderGroupByTypes(ctx) {
+  const { table, names } = ctx;
+  const groupable = groupableColumns(table);
+  if (groupable.length === 0) return [];
+  const keyLines = groupable.map((column) => `  ${fieldName(column.name)}: ${columnGqlTypeOf(table, column)}`);
+  return [
+    renderEnum(names.groupByColumnEnum, groupable.map((column) => fieldName(column.name))),
+    `input ${names.groupByInput} {
+  column: ${names.groupByColumnEnum}!
+  bucket: ${DATE_BUCKET_ENUM}
+}`,
+    `type ${names.groupKey} {
+${keyLines.join("\n")}
+}`,
+    `type ${names.aggregateGroup} {
+  key: ${names.groupKey}!
+  aggregate: ${names.aggregateFields}
+}`
+  ];
+}
+function groupRootArgs(names) {
+  return `where: ${names.boolExp}, groupBy: [${names.groupByInput}!]!, limit: Int, offset: Int`;
+}
 function renderAggregateBoolExp(ctx) {
   const { names } = ctx;
   return [
@@ -7137,6 +7655,9 @@ function constraintValues(table) {
   }
   return [...values].sort();
 }
+function clientSettableColumns(table) {
+  return table.columns.filter((column) => column.onUpdateFn === void 0);
+}
 function renderWriteBlocks(ctx, access) {
   const { table, names, pinned } = ctx;
   const blocks = [];
@@ -7158,7 +7679,7 @@ ${insertLines.join("\n")}
 }`);
   }
   if (access.update) {
-    const setLines = table.columns.map(
+    const setLines = clientSettableColumns(table).map(
       (column) => `  ${fieldName(column.name)}: ${columnGqlTypeOf(table, column)}`
     );
     blocks.push(`input ${names.setInput} {
@@ -7185,7 +7706,7 @@ ${incLines.join("\n")}
   if (access.insert && allowsOnConflict(table) && constraints.length > 0) {
     for (const value of constraints) assertEnumValue(value, `constraint enum for table "${table.table}"`);
     blocks.push(renderEnum(names.constraintEnum, constraints));
-    const updateColumns = table.columns.map((column) => fieldName(column.name));
+    const updateColumns = clientSettableColumns(table).map((column) => fieldName(column.name));
     blocks.push(renderEnum(names.updateColumnEnum, updateColumns));
     blocks.push(
       `input ${names.onConflict} {
@@ -7217,6 +7738,9 @@ function renderQueryRoot(tables, namesByTable) {
       lines.push(`  ${names.byPkRoot}(${args}): ${names.typename}`);
     }
     lines.push(`  ${names.aggregateRoot}(${rootArgs(names)}): ${names.aggregate}!`);
+    if (groupableColumns(table).length > 0) {
+      lines.push(`  ${names.aggregateGroupsRoot}(${groupRootArgs(names)}): [${names.aggregateGroup}!]!`);
+    }
   }
   lines.push("}");
   return lines.join("\n");
@@ -7285,6 +7809,40 @@ function renderCowMutationFields(table, names) {
   }
   return lines;
 }
+var ORM_MIGRATION_EXPORT_FILE = "orm.migration.json";
+var ORM_MIGRATION_EXPORT_MAX_BYTES = ORM_REGISTRATION_MAX_BYTES;
+var hash = 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();
+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 renderOrmMigrationExport(exported) {
+  const text4 = `${JSON.stringify(exported, null, 2)}
+`;
+  if (Buffer.byteLength(text4, "utf8") > ORM_MIGRATION_EXPORT_MAX_BYTES) throw new Error("ORM migration export exceeds the size limit");
+  return text4;
+}
 
 // src/cli.ts
 var BASE_URL_ENV = "SEQUENCE_ORM_BASE_URL";
@@ -7293,11 +7851,15 @@ var ORM_MODULE_PATH_ENV = "SEQUENCE_ORM_MODULE_PATH";
 var USAGE = `usage:
   seq-studio orm init <dir>              scaffold a namespace package (v2: TypeScript schema + GraphQL documents)
   seq-studio orm generate [dir]          write schema.graphql + operations.manifest.json + typePolicies.gen.ts (+ consumer graphql-codegen when codegen.ts is present)
+  seq-studio orm generate [dir] --migration-export [--check]
+                                        export reviewed ORM inputs for a coordinated pipeline migration; --check verifies without writing
   seq-studio orm validate [dir]          parse + validate definitions and verify committed migrations are in sync
   seq-studio orm plan [dir] -e <env>     offline dry run: compile definitions and diff against the registry (no database, no writes)
   seq-studio orm apply [dir] -e <env>    author the migration, register, apply, and refresh the generated outputs (the everyday command)
   seq-studio orm apply --dry-run -e <env>  rehearse the migration on a copy of the environment's real data, then discard it (no real apply)
   seq-studio orm apply --no-create -e <env>  apply only if the namespace is already registered (CI guard; never provisions a new namespace)
+  seq-studio orm execute <operation> [dir] --variables-file <file> -e <env>
+                                        execute one named persisted operation as the signed-in caller
   seq-studio orm diff [dir]              write/verify the committed migration standalone (--check is the offline CI gate; --allow-destructive consents; --rebase records a v1 -> v2 conversion as a verified no-op)
   seq-studio orm migrate-from-yaml <dir> convert a v1 YAML namespace to the v2 TypeScript format (migrations/ preserved)
 
@@ -7305,6 +7867,8 @@ var USAGE = `usage:
   v2 = sequence.config.ts + schema/*.ts + graphql/**; v1 (legacy) = one <table>.yaml per table.
   Environments: see \`seq-studio envs list\` (discovered after you authenticate).
   Authenticate with: seq-studio login
+  Execute endpoint rollout: SEQUENCE_ORM_ATLAS_EXECUTE_V2=1 opts into /api/data/v2;
+  otherwise execute uses /_data/v2. Server rollout and authorization still apply.
 `;
 var tokenProvider = null;
 function setTokenProvider(provider) {
@@ -7321,6 +7885,10 @@ async function runCli(argv) {
     console.log(USAGE);
     return command ? 0 : 1;
   }
+  if (rest.includes("--help") || rest.includes("-h")) {
+    console.log(USAGE);
+    return 0;
+  }
   try {
     switch (command) {
       case "init":
@@ -7358,6 +7926,8 @@ async function runCli(argv) {
         const dir = positional(rest) ?? ".";
         return await detectProjectFormat(dir) === "v2" ? await applyV2Command(rest, dir) : await applyCommand(rest);
       }
+      case "execute":
+        return await executeV2Command(rest);
       default:
         console.error(`unknown command: ${command}`);
         console.log(USAGE);
@@ -7368,13 +7938,14 @@ async function runCli(argv) {
     return 1;
   }
 }
+var NON_DEFINITION_YAML_FILES = /* @__PURE__ */ new Set(["pnpm-lock.yaml", "pnpm-workspace.yaml"]);
 async function detectProjectFormat(dir) {
   const entries = await promises.readdir(dir, { withFileTypes: true }).catch(() => {
     throw new OrmDefinitionError(`namespace directory not found: ${dir}`);
   });
   const hasConfig = entries.some((entry) => entry.isFile() && entry.name === NAMESPACE_CONFIG_FILE);
   const hasYaml = entries.some(
-    (entry) => entry.isFile() && DEFINITION_FILE_EXTENSIONS.some((extension) => entry.name.endsWith(extension))
+    (entry) => entry.isFile() && !NON_DEFINITION_YAML_FILES.has(entry.name) && DEFINITION_FILE_EXTENSIONS.some((extension) => entry.name.endsWith(extension))
   );
   if (hasConfig && hasYaml) {
     throw new OrmDefinitionError(
@@ -7512,6 +8083,12 @@ function printDiagnostics(diagnostics) {
 }
 async function generateCommand(rest) {
   const dir = positional(rest) ?? ".";
+  const migrationExport = rest.includes("--migration-export");
+  const check = rest.includes("--check");
+  if (check && !migrationExport) {
+    console.error("generate --check requires --migration-export");
+    return 1;
+  }
   if (await detectProjectFormat(dir) === "v1") {
     console.error(`generate needs a v2 project (${NAMESPACE_CONFIG_FILE}) \u2014 convert with: seq-studio orm migrate-from-yaml ${dir}`);
     return 1;
@@ -7519,6 +8096,36 @@ async function generateCommand(rest) {
   const compiled = await compileV2Project(dir);
   printDiagnostics(compiled.ok ? compiled.project.diagnostics : compiled.diagnostics);
   if (!compiled.ok) return 1;
+  if (migrationExport) {
+    if (await validateV2Command(dir) !== 0) return 1;
+    const { loaded: loaded2, sdl, documents, manifest: manifest2 } = compiled.project;
+    const workspace = await readMigrationWorkspace(dir, loaded2.canonical.namespace);
+    const migration = await loadCommittedTipMigrationV2({ dir, loaded: loaded2, workspace });
+    const exported = createOrmMigrationExport({ schemaHash: manifest2.schemaHash, payload: {
+      canonical_definition: loaded2.canonical,
+      documents,
+      sdl,
+      client_manifest: { ops_hash: manifest2.opsHash, operations: Object.fromEntries(Object.entries(manifest2.operations).map(([name, operation]) => [name, operation.opHash])) },
+      schema_snapshot: workspace.tipSnapshot,
+      ...migration ? { migration } : {}
+    } });
+    const text4 = renderOrmMigrationExport(exported);
+    const path$1 = path.join(dir, ORM_MIGRATION_EXPORT_FILE);
+    if (check) {
+      const committed = await promises.readFile(path$1, "utf8").catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+        throw error;
+      });
+      if (committed !== text4) {
+        console.error(`${ORM_MIGRATION_EXPORT_FILE} is missing or stale; run seq-studio orm generate ${dir} --migration-export and commit it`);
+        return 1;
+      }
+      console.log(`${ORM_MIGRATION_EXPORT_FILE} matches the current definitions, operations, and committed migration`);
+      return 0;
+    }
+    await promises.writeFile(path$1, text4);
+    console.log(`wrote ${ORM_MIGRATION_EXPORT_FILE} (${exported.checksum.slice(0, 12)})`);
+  }
   await writeGenerateOutputs(dir, compiled.project);
   const { loaded, manifest } = compiled.project;
   console.log(
@@ -7569,6 +8176,80 @@ async function runConsumerCodegen(dir) {
   console.log(`ran consumer graphql-codegen (${CODEGEN_CONFIG_FILE})`);
   return 0;
 }
+function isVariablesObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseExecuteArgs(rest) {
+  const args = [...rest];
+  const variablesIndex = args.indexOf("--variables-file");
+  if (variablesIndex === -1) {
+    throw new OrmDefinitionError("execute requires --variables-file <file>");
+  }
+  const variablesFile = args[variablesIndex + 1];
+  if (!variablesFile) {
+    throw new OrmDefinitionError("execute requires --variables-file <file>");
+  }
+  args.splice(variablesIndex, 2);
+  const envIndex = args.indexOf("--env");
+  if (envIndex !== -1) args.splice(envIndex, 2);
+  if (args.some((arg) => arg.startsWith("-"))) {
+    throw new OrmDefinitionError("execute accepts only <operation>, [dir], --variables-file, and --env");
+  }
+  const operation = args[0];
+  if (!operation || args.length > 2) {
+    throw new OrmDefinitionError("usage: seq-studio orm execute <operation> [dir] --variables-file <file> -e <env>");
+  }
+  return {
+    operation,
+    dir: args[1] ?? ".",
+    variablesFile
+  };
+}
+async function readExecuteVariables(variablesFile) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await promises.readFile(path.resolve(variablesFile), "utf8"));
+  } catch (error) {
+    throw new OrmDefinitionError(
+      `could not read JSON variables from ${variablesFile}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!isVariablesObject(parsed)) {
+    throw new OrmDefinitionError("--variables-file must contain a JSON object");
+  }
+  return parsed;
+}
+async function executeV2Command(rest) {
+  const { dir, operation, variablesFile } = parseExecuteArgs(rest);
+  if (await detectProjectFormat(dir) !== "v2") {
+    throw new OrmDefinitionError("execute supports TypeScript ORM v2 namespaces only");
+  }
+  const loaded = await loadV2(dir);
+  const manifestPath = path.join(dir, OPERATIONS_MANIFEST_FILE);
+  let manifest;
+  try {
+    manifest = operationsManifestSchema.parse(JSON.parse(await promises.readFile(manifestPath, "utf8")));
+  } catch (error) {
+    throw new OrmDefinitionError(
+      `could not read ${OPERATIONS_MANIFEST_FILE}: ${error instanceof Error ? error.message : String(error)} \u2014 run \`seq-studio orm generate ${dir}\` first`
+    );
+  }
+  const selected = manifest.operations[operation];
+  if (!selected) {
+    throw new OrmDefinitionError(
+      `operation "${operation}" is not in ${OPERATIONS_MANIFEST_FILE}; run \`seq-studio orm generate ${dir}\` after editing GraphQL documents`
+    );
+  }
+  const variables = await readExecuteVariables(variablesFile);
+  const executePrefix = process.env["SEQUENCE_ORM_ATLAS_EXECUTE_V2"] === "1" ? "/api/data/v2" : "/_data/v2";
+  const response = await apiRequestStrict(
+    "POST",
+    `${executePrefix}/${loaded.canonical.namespace}`,
+    { op: selected.hash, variables }
+  );
+  console.log(JSON.stringify(response, null, 2));
+  return 0;
+}
 async function validateV2Command(dir) {
   const compiled = await compileV2Project(dir);
   printDiagnostics(compiled.ok ? compiled.project.diagnostics : compiled.diagnostics);
@@ -8078,6 +8759,7 @@ function columnProperty(table, column, singlePrimaryKey) {
     }
     chain += `.default(${JSON.stringify(column.default)})`;
   }
+  if (column.onUpdateFn !== void 0) chain += `.onUpdate(${quote(column.onUpdateFn)})`;
   if (column.description !== void 0) chain += `.description(${quote(column.description)})`;
   if (column.renamedFrom !== void 0) chain += `.renamedFrom(${quote(column.renamedFrom)})`;
   if (column.cast !== void 0) chain += `.cast(${quote(column.cast)})`;