@sequenceholdings/orm 0.1.2 → 0.1.3

package/dist/compiler.js

@@ -88,8 +88,33 @@ var policyExpressionSchema = z.union([
 ]);
 var canonicalPoliciesSchema = z.object({
   read: policyExpressionSchema.optional(),
-  write: policyExpressionSchema.optional()
+  write: policyExpressionSchema.optional(),
+  insert: policyExpressionSchema.optional(),
+  update: policyExpressionSchema.optional()
 });
+function isSingleViewQuerySql(value) {
+  const query = value.trim();
+  if (!/^\(*(?:select|with)\b/i.test(query) || query.includes("\0")) return false;
+  let state = "normal";
+  for (let index = 0; index < query.length; index += 1) {
+    const char = query[index];
+    const next = query[index + 1];
+    if (state === "single") {
+      if (char === "'" && next === "'") index += 1;
+      else if (char === "'") state = "normal";
+      continue;
+    }
+    if (state === "double") {
+      if (char === '"' && next === '"') index += 1;
+      else if (char === '"') state = "normal";
+      continue;
+    }
+    if (char === "'") state = "single";
+    else if (char === '"') state = "double";
+    else if (char === ";" || char === "-" && next === "-" || char === "/" && next === "*") return false;
+  }
+  return state === "normal" && !/\$[a-z_0-9]*\$/i.test(query);
+}
 var canonicalActionSchema = z.object({
   name: identifier,
   requires: z.string().max(1e3).optional(),
@@ -101,6 +126,37 @@ var canonicalActionSchema = z.object({
   returns: z.enum(["rows", "rowsAffected", "scalar"]).default("rowsAffected"),
   audit: z.object({ action: z.string(), resource: z.string() }).optional()
 });
+var canonicalCowMutationSchema = z.object({
+  kind: z.enum(["override", "revert"]),
+  name: identifier,
+  /** Synced table (same namespace) the overlay copies from / falls back to. */
+  synced: identifier,
+  /** Single-column primary key PROPERTY (TS camelCase, like column `name`) shared by overlay and synced. */
+  pk: z.string().min(1).max(63),
+  /** Override: contract properties copied INSERT…SELECT from synced (pk included). Empty for revert. */
+  copy: z.array(z.string().min(1).max(63)).default([]),
+  /** Override: overlay properties written by the UPDATE (never the pk). Empty for revert. */
+  set: z.array(z.string().min(1).max(63)).default([])
+}).superRefine((mutation, ctx) => {
+  if (mutation.kind === "override") {
+    if (mutation.set.length === 0) {
+      ctx.addIssue({ code: "custom", path: ["set"], message: "override mutations must set at least one column" });
+    }
+    if (!mutation.copy.includes(mutation.pk)) {
+      ctx.addIssue({ code: "custom", path: ["copy"], message: "override copy list must include the pk" });
+    }
+  } else if (mutation.set.length > 0 || mutation.copy.length > 0) {
+    ctx.addIssue({ code: "custom", path: ["set"], message: "revert mutations take no copy/set columns" });
+  }
+  if (mutation.set.includes(mutation.pk)) {
+    ctx.addIssue({ code: "custom", path: ["set"], message: "set must not include the pk \u2014 identity columns are pinned" });
+  }
+  for (const [field, values] of [["copy", mutation.copy], ["set", mutation.set]]) {
+    if (new Set(values).size !== values.length) {
+      ctx.addIssue({ code: "custom", path: [field], message: `${field} must not contain duplicate columns` });
+    }
+  }
+});
 var canonicalTableSchema = z.object({
   table: identifier,
   description: z.string().max(2e3).optional(),
@@ -113,7 +169,45 @@ var canonicalTableSchema = z.object({
   links: z.array(canonicalLinkSchema).default([]),
   indexes: z.array(canonicalIndexSchema).default([]),
   policies: canonicalPoliciesSchema.default({}),
-  actions: z.array(canonicalActionSchema).default([])
+  /**
+   * v1-conversion carry-over only. v2 has no action surface — the runtime
+   * neither compiles nor executes these; writes are mutations. Kept parseable
+   * so stored definitions and their content hashes stay stable.
+   */
+  actions: z.array(canonicalActionSchema).default([]),
+  /** Optional (not defaulted) so pre-CoW canonical documents keep byte-identical hashes. */
+  cowMutations: z.array(canonicalCowMutationSchema).optional()
+});
+var canonicalViewSchema = z.object({
+  view: identifier,
+  description: z.string().max(2e3).optional(),
+  columns: z.array(canonicalColumnSchema).min(1),
+  /** Logical identity for GraphQL only; PostgreSQL views have no PK constraint. */
+  primaryKey: z.array(identifier).min(1).max(8).optional(),
+  links: z.array(canonicalLinkSchema).default([]),
+  policies: z.object({ read: policyExpressionSchema }).strict(),
+  query: z.string().min(1).max(1e5).refine(isSingleViewQuerySql, {
+    message: "view query must be one SELECT/WITH statement without comments or dollar-quoted bodies"
+  }),
+  /** Namespace-local logical relation names, sorted for deterministic hashing. */
+  dependencies: z.array(identifier).max(500)
+}).superRefine((view, ctx) => {
+  for (const [index, column] of view.columns.entries()) {
+    if (column.default !== void 0 || column.defaultFn !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare a default` });
+    }
+    if (column.unique) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare unique` });
+    }
+    if (column.renamedFrom !== void 0 || column.cast !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare migration hints` });
+    }
+  }
+  for (const [index, link] of view.links.entries()) {
+    if (link.enforce) {
+      ctx.addIssue({ code: "custom", path: ["links", index, "enforce"], message: `view link '${link.name}' cannot enforce a foreign key` });
+    }
+  }
 });
 var canonicalDefinitionSchema = z.object({
   definition_format: z.literal(CANONICAL_FORMAT),
@@ -121,24 +215,174 @@ var canonicalDefinitionSchema = z.object({
   description: z.string().max(2e3).optional(),
   enums: z.array(canonicalEnumSchema).default([]),
   tables: z.array(canonicalTableSchema).min(0).max(500),
+  /** Optional to preserve byte-identical hashes for pre-view canonical v2 documents. */
+  views: z.array(canonicalViewSchema).max(500).optional(),
   /** Verbatim custom-roles grammar (@sequenceholdings/custom-roles-manifest). */
   capabilities: z.object({
     roles: z.unknown().optional(),
     uses: z.array(z.string()).default([])
   }).default({ uses: [] })
+}).superRefine((definition, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, table] of definition.tables.entries()) {
+    if (seen.has(table.table)) {
+      ctx.addIssue({ code: "custom", path: ["tables", index, "table"], message: `duplicate relation '${table.table}'` });
+    }
+    seen.add(table.table);
+  }
+  const tableByName = new Map(definition.tables.map((table) => [table.table, table]));
+  for (const [tableIndex, table] of definition.tables.entries()) {
+    const cowMutations = table.cowMutations ?? [];
+    if (cowMutations.length === 0) continue;
+    const path = (index, ...rest) => ["tables", tableIndex, "cowMutations", index, ...rest];
+    if (table.source !== void 0) {
+      ctx.addIssue({ code: "custom", path: path(0), message: `synced table '${table.table}' cannot declare cow mutations \u2014 it is read-only` });
+      continue;
+    }
+    for (const [index, mutation] of cowMutations.entries()) {
+      const synced = tableByName.get(mutation.synced);
+      if (!synced || synced.source === void 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: path(index, "synced"),
+          message: `cow mutation '${mutation.name}' references '${mutation.synced}', which is not a synced table in this namespace`
+        });
+        continue;
+      }
+      const overlayColumnsByName = new Map(table.columns.map((column) => [column.name, column]));
+      const syncedColumnsByName = new Map(synced.columns.map((column) => [column.name, column]));
+      let columnsExist = true;
+      for (const property of [mutation.pk, ...mutation.copy, ...mutation.set]) {
+        if (!overlayColumnsByName.has(property)) {
+          columnsExist = false;
+          ctx.addIssue({ code: "custom", path: path(index), message: `cow mutation '${mutation.name}': column '${property}' does not exist on overlay '${table.table}'` });
+        }
+      }
+      for (const property of [mutation.pk, ...mutation.copy]) {
+        if (!syncedColumnsByName.has(property)) {
+          columnsExist = false;
+          ctx.addIssue({ code: "custom", path: path(index), message: `cow mutation '${mutation.name}': column '${property}' does not exist on synced '${mutation.synced}'` });
+        }
+      }
+      if (!columnsExist) continue;
+      const overlayPk = table.primaryKey ?? [];
+      const syncedPk = synced.primaryKey ?? [];
+      if (overlayPk.length !== 1 || overlayPk[0] !== mutation.pk || syncedPk.length !== 1 || syncedPk[0] !== mutation.pk) {
+        ctx.addIssue({
+          code: "custom",
+          path: path(index, "pk"),
+          message: `cow mutation '${mutation.name}': pk '${mutation.pk}' must be the single-column primary key on both '${table.table}' and '${mutation.synced}'`
+        });
+      }
+      for (const property of [mutation.pk, ...mutation.copy]) {
+        const overlayColumn = overlayColumnsByName.get(property);
+        const syncedColumn = syncedColumnsByName.get(property);
+        if (!overlayColumn || !syncedColumn) continue;
+        if (JSON.stringify(overlayColumn.type) !== JSON.stringify(syncedColumn.type)) {
+          ctx.addIssue({
+            code: "custom",
+            path: path(index),
+            message: `cow mutation '${mutation.name}': column '${property}' must have the same type on overlay and synced`
+          });
+        }
+        if (overlayColumn.columnName !== syncedColumn.columnName) {
+          ctx.addIssue({
+            code: "custom",
+            path: path(index),
+            message: `cow mutation '${mutation.name}': column '${property}' maps to different Postgres names on overlay ('${overlayColumn.columnName}') and synced ('${syncedColumn.columnName}')`
+          });
+        }
+        if (syncedColumn.nullable !== false && overlayColumn.nullable === false) {
+          ctx.addIssue({
+            code: "custom",
+            path: path(index),
+            message: `cow mutation '${mutation.name}': column '${property}' is nullable on synced but NOT NULL on overlay \u2014 a NULL synced value would fail the copy`
+          });
+        }
+      }
+    }
+  }
+  for (const [index, view] of (definition.views ?? []).entries()) {
+    if (seen.has(view.view)) {
+      ctx.addIssue({ code: "custom", path: ["views", index, "view"], message: `duplicate relation '${view.view}'` });
+    }
+    seen.add(view.view);
+  }
+  const views = definition.views ?? [];
+  const viewByName = new Map(views.map((view) => [view.view, view]));
+  for (const [viewIndex, view] of views.entries()) {
+    for (const [dependencyIndex, dependency] of view.dependencies.entries()) {
+      if (!seen.has(dependency)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["views", viewIndex, "dependencies", dependencyIndex],
+          message: `view '${view.view}' depends on unknown relation '${dependency}'`
+        });
+      }
+    }
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  let cycleReported = false;
+  const visit = (name, path) => {
+    if (visited.has(name) || cycleReported) return;
+    if (visiting.has(name)) {
+      cycleReported = true;
+      ctx.addIssue({
+        code: "custom",
+        path: ["views"],
+        message: `view dependencies form a cycle: ${[...path, name].join(" -> ")}`
+      });
+      return;
+    }
+    visiting.add(name);
+    const view = viewByName.get(name);
+    for (const dependency of view?.dependencies ?? []) {
+      if (viewByName.has(dependency)) visit(dependency, [...path, name]);
+    }
+    visiting.delete(name);
+    visited.add(name);
+  };
+  for (const view of views) visit(view.view, []);
 });
+function canonicalRelations(definition) {
+  const views = (definition.views ?? []).map((view) => ({
+    table: view.view,
+    ...view.description !== void 0 ? { description: view.description } : {},
+    columns: view.columns,
+    ...view.primaryKey !== void 0 ? { primaryKey: view.primaryKey } : {},
+    links: view.links,
+    indexes: [],
+    policies: { read: view.policies.read },
+    actions: []
+  }));
+  return [...definition.tables, ...views].sort((a, b) => a.table.localeCompare(b.table));
+}
 function normalizeCanonical(definition) {
   const sortByName = (items) => [...items].sort((a, b) => a.name.localeCompare(b.name));
-  return {
+  const normalized = {
     ...definition,
     enums: sortByName(definition.enums),
-    tables: [...definition.tables].sort((a, b) => a.table.localeCompare(b.table)).map((t) => ({
-      ...t,
-      links: sortByName(t.links),
-      indexes: [...t.indexes].sort((a, b) => (a.name ?? a.columns.join("_")).localeCompare(b.name ?? b.columns.join("_"))),
-      actions: sortByName(t.actions)
-    }))
+    tables: [...definition.tables].sort((a, b) => a.table.localeCompare(b.table)).map((t) => {
+      const { cowMutations, ...rest } = t;
+      return {
+        ...rest,
+        links: sortByName(t.links),
+        indexes: [...t.indexes].sort((a, b) => (a.name ?? a.columns.join("_")).localeCompare(b.name ?? b.columns.join("_"))),
+        actions: sortByName(t.actions),
+        // Omitted entirely when absent/empty so pre-CoW documents hash unchanged.
+        ...cowMutations !== void 0 && cowMutations.length > 0 ? { cowMutations: sortByName(cowMutations) } : {}
+      };
+    })
   };
+  if (definition.views !== void 0) {
+    normalized.views = [...definition.views].sort((a, b) => a.view.localeCompare(b.view)).map((view) => ({
+      ...view,
+      links: sortByName(view.links),
+      dependencies: [...view.dependencies].sort()
+    }));
+  }
+  return normalized;
 }
 
 // src/ir/index.ts
@@ -279,9 +523,23 @@ var onConflictIrSchema = z.union([
 ]);
 var mutationRootSchema = z.object({
   kind: z.literal("mutation"),
-  op: z.enum(["insert", "insertOne", "update", "updateByPk", "delete", "deleteByPk"]),
+  /**
+   * CRUD verbs plus the structured copy-on-write ops. `cowOverride` copies the
+   * synced row into the overlay (INSERT…SELECT, ON CONFLICT DO NOTHING) then
+   * applies `set` — both statements generated by the executor from this
+   * metadata, never authored SQL. `cowRevert` deletes the override so the
+   * coalesce view falls back to synced. Both are gated on a matching synced
+   * row and carry the write policy in `where` like update/delete.
+   */
+  op: z.enum(["insert", "insertOne", "update", "updateByPk", "delete", "deleteByPk", "cowOverride", "cowRevert"]),
   alias: z.string(),
   table: z.string(),
+  /** CoW ops: logical name of the synced twin (read through its policy-filtered view). */
+  cowSynced: z.string().optional(),
+  /** cowOverride: logical properties copied INSERT…SELECT from synced (pk included). */
+  cowCopyColumns: z.array(z.string()).optional(),
+  /** cowOverride: insert-policy WITH CHECK evaluated over the copied rows. */
+  cowCopyCheck: predIrSchema.optional(),
   /** insert/insertOne: rows come from a slot ($object/$objects) or literals. */
   objects: z.union([
     z.object({ slot: z.string() }),
@@ -302,19 +560,11 @@ var mutationRootSchema = z.object({
   affectedRows: z.boolean().default(false),
   includeIf: includeIfSchema.optional()
 });
-var actionRootSchema = z.object({
-  kind: z.literal("action"),
-  alias: z.string(),
-  name: z.string(),
-  params: z.array(z.object({ name: z.string(), value: valueIrSchema })),
-  returns: z.enum(["rows", "rowsAffected", "scalar"])
-});
 var rootIrSchema = z.discriminatedUnion("kind", [
   selectRootSchema,
   byPkRootSchema,
   aggregateRootSchema,
-  mutationRootSchema,
-  actionRootSchema
+  mutationRootSchema
 ]);
 var INPUT_REF_KINDS = [
   "boolExp",
@@ -346,7 +596,7 @@ var compiledOperationSchema = z.object({
   irVersion: z.literal(IR_VERSION),
   name: z.string(),
   opHash: z.string().regex(/^sha256:[0-9a-f]{64}$/),
-  kind: z.enum(["query", "mutation", "action"]),
+  kind: z.enum(["query", "mutation"]),
   requires: z.object({
     capability: z.string().optional(),
     role: z.string().optional()
@@ -360,13 +610,24 @@ var tableMetaIrSchema = z.object({
   table: z.string(),
   schema: z.string(),
   typename: z.string(),
+  /**
+   * True when statements over this relation evaluate a claims-gated synced
+   * view: synced twins (`source: gold.*`) materialize as views whose baked
+   * policy reads `current_setting('request.jwt.claims')`, and namespace views
+   * inherit the gate transitively through their declared dependencies. The
+   * executor must stamp that GUC (transaction-scoped) before any statement
+   * touching such a relation, or the synced arm yields zero rows regardless
+   * of the compiled predicates.
+   */
+  claimsGated: z.boolean().default(false),
   columns: z.array(z.object({
     name: z.string(),
     columnName: z.string(),
     type: z.union([z.enum(COLUMN_TYPES), z.object({ enum: z.string(), values: z.array(z.string()) })]),
     nullable: z.boolean()
   })),
-  primaryKey: z.array(z.string()).min(1),
+  /** Empty for keyless read-only views; keyed tables and views list logical columns. */
+  primaryKey: z.array(z.string()),
   links: z.array(z.object({
     name: z.string(),
     kind: z.enum(["toOne", "toMany", "toPlatformUser"]),
@@ -905,6 +1166,7 @@ var NamespaceCompileError = class extends Error {
 
 // src/compiler-gql/pred-utils.ts
 var CONST_TRUE = { kind: "const", value: true };
+var CONST_FALSE = { kind: "const", value: false };
 function andPred(...preds) {
   const operands = preds.filter(
     (pred) => pred !== void 0 && !(pred.kind === "const" && pred.value)
@@ -998,6 +1260,12 @@ var PolicyInjector = class {
   write(table) {
     return this.ctx.writePolicies.get(table) ?? { kind: "const", value: true };
   }
+  insert(table) {
+    return this.ctx.insertPolicies.get(table) ?? this.write(table);
+  }
+  update(table) {
+    return this.ctx.updatePolicies.get(table) ?? this.write(table);
+  }
   linkTarget(table, link) {
     const meta = this.ctx.tables[table];
     const resolved = meta?.links.find((l) => l.name === link);
@@ -1072,31 +1340,50 @@ var PolicyInjector = class {
         };
       case "mutation":
         return this.injectMutation(root);
-      case "action":
-        return root;
     }
   }
   injectMutation(root) {
     const table = root.table;
-    const writePolicy = this.write(table);
     const returning = root.returning ? this.injectSelection(root.returning, table) : root.returning;
     if (root.op === "insert" || root.op === "insertOne") {
-      if (predContainsExists(writePolicy)) {
+      const insertPolicy = this.insert(table);
+      if (predContainsExists(insertPolicy)) {
         throw new DocumentCompileError(
-          `table '${table}' cannot be inserted into: v2.0 insert checks are claims + inserted-values only, but its write policy traverses a link (exists)`,
+          `table '${table}' cannot be inserted into: v2.0 insert checks are claims + inserted-values only, but its insert policy traverses a link (exists)`,
           "insert-check-unrepresentable"
         );
       }
       const pins = (this.ctx.pins.get(table) ?? []).map(
         (pin) => ({ column: pin.column, value: { kind: "claim", key: pin.claim } })
       );
-      return { ...root, pinnedColumns: pins, insertCheck: writePolicy, returning };
+      if (root.onConflict && this.ctx.splitWritePolicyTables.has(table)) {
+        throw new DocumentCompileError(
+          `table '${table}' cannot use onConflict while insert and update policies are split \u2014 use separate insert and update mutations`,
+          "on-conflict-split-policies"
+        );
+      }
+      return { ...root, pinnedColumns: pins, insertCheck: insertPolicy, returning };
     }
-    const where = andPred(writePolicy, root.where ? this.injectDocPred(root.where, table) : void 0);
+    const updatePolicy = this.update(table);
+    const where = andPred(updatePolicy, root.where ? this.injectDocPred(root.where, table) : void 0);
     if (root.op === "update" || root.op === "updateByPk") {
-      const check = predContainsExists(writePolicy) ? {} : { insertCheck: writePolicy };
+      const check = predContainsExists(updatePolicy) ? {} : { insertCheck: updatePolicy };
       return { ...root, where, ...check, returning };
     }
+    if (root.op === "cowOverride") {
+      const insertPolicy = this.insert(table);
+      if (predContainsExists(insertPolicy)) {
+        throw new DocumentCompileError(
+          `table '${table}' cannot be copy-on-write overridden: v2.0 insert checks are claims + inserted-values only, but its insert policy traverses a link (exists)`,
+          "insert-check-unrepresentable"
+        );
+      }
+      const pins = (this.ctx.pins.get(table) ?? []).map(
+        (pin) => ({ column: pin.column, value: { kind: "claim", key: pin.claim } })
+      );
+      const check = predContainsExists(updatePolicy) ? {} : { insertCheck: updatePolicy };
+      return { ...root, pinnedColumns: pins, cowCopyCheck: insertPolicy, where, ...check, returning };
+    }
     return { ...root, where, returning };
   }
 };
@@ -1142,7 +1429,6 @@ function collectTableSet(roots, ctx) {
     }
   };
   for (const root of roots) {
-    if (root.kind === "action") continue;
     tables.add(root.table);
     if (root.kind === "select" || root.kind === "byPk") {
       visitPred(root.where, root.table);
@@ -1153,8 +1439,10 @@ function collectTableSet(roots, ctx) {
       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);
     }
   }
@@ -1325,6 +1613,7 @@ function platformUserMeta() {
     table: "users_directory",
     schema: "platform",
     typename: PLATFORM_USER_TYPENAME,
+    claimsGated: false,
     columns: columns.map((c) => ({ ...c })),
     primaryKey: ["sub"],
     links: [],
@@ -1367,15 +1656,30 @@ function buildCompileContext(rawCanonical) {
   const canonical = normalizeCanonical(canonicalDefinitionSchema.parse(rawCanonical));
   const diagnostics = [];
   const enums = new Map(canonical.enums.map((e) => [e.name, e]));
+  const relations = canonicalRelations(canonical);
+  const viewNames = new Set((canonical.views ?? []).map((view) => view.view));
   const columnEntries = /* @__PURE__ */ new Map();
   const tables = {};
-  const usesPlatformUsers = canonical.tables.some((t) => t.links.some((l) => l.kind === "toPlatformUser"));
+  const usesPlatformUsers = relations.some((t) => t.links.some((l) => l.kind === "toPlatformUser"));
   const platformMeta = usesPlatformUsers ? platformUserMeta() : void 0;
   if (platformMeta) tables[PLATFORM_USER_TABLE] = platformMeta;
-  for (const table of canonical.tables) {
+  const syncedTableNames = new Set(canonical.tables.filter((t) => t.source !== void 0).map((t) => t.table));
+  const viewDependencies = new Map((canonical.views ?? []).map((view) => [view.view, view.dependencies]));
+  const claimsGatedMemo = /* @__PURE__ */ new Map();
+  const relationIsClaimsGated = (name) => {
+    if (syncedTableNames.has(name)) return true;
+    const memo = claimsGatedMemo.get(name);
+    if (memo !== void 0) return memo;
+    claimsGatedMemo.set(name, false);
+    const gated = (viewDependencies.get(name) ?? []).some(relationIsClaimsGated);
+    claimsGatedMemo.set(name, gated);
+    return gated;
+  };
+  for (const table of relations) {
+    const isView = viewNames.has(table.table);
     const entries = resolveColumnEntries(table, enums, diagnostics);
     columnEntries.set(table.table, entries);
-    const pkRefs = table.primaryKey ?? ["id"];
+    const pkRefs = table.primaryKey ?? (isView ? [] : ["id"]);
     const primaryKey = [];
     for (const ref of pkRefs) {
       const resolved = logicalColumn(entries, ref);
@@ -1396,7 +1700,7 @@ function buildCompileContext(rawCanonical) {
     for (const column of table.columns) {
       if (column.unique) {
         const logical = logicalColumn(entries, column.columnName);
-        constraints.push({ name: `${table.table}_${column.columnName}_key`, columns: [logical] });
+        constraints.push({ name: `${table.table}_${column.columnName}_unique`, columns: [logical] });
       }
     }
     for (const index of table.indexes) {
@@ -1408,20 +1712,23 @@ function buildCompileContext(rawCanonical) {
       table: table.table,
       schema: ormSchemaName(canonical.namespace),
       typename: typeNameForTable(table.table),
+      // 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),
-      primaryKey: primaryKey.length > 0 ? primaryKey : ["id"],
+      primaryKey: isView ? primaryKey : primaryKey.length > 0 ? primaryKey : ["id"],
       links: [],
       filterable: entries.map((c) => c.name),
       orderable: entries.filter((c) => c.type !== "jsonb").map((c) => c.name),
-      insertable: active.map((c) => c.name),
-      settable: active.map((c) => c.name),
-      appendable: active.filter((c) => c.type === "jsonb").map((c) => c.name),
-      constraints,
+      insertable: isView ? [] : active.map((c) => c.name),
+      settable: isView ? [] : active.map((c) => c.name),
+      appendable: isView ? [] : active.filter((c) => c.type === "jsonb").map((c) => c.name),
+      constraints: isView ? [] : constraints,
       dynamicFilterMaxDepth: 6,
       dynamicFilterMaxNodes: 64
     };
   }
-  for (const table of canonical.tables) {
+  for (const table of relations) {
     const meta = tables[table.table];
     const entries = columnEntries.get(table.table);
     for (const link of table.links) {
@@ -1456,17 +1763,17 @@ function buildCompileContext(rawCanonical) {
   }
   const readPolicies = /* @__PURE__ */ new Map();
   const writePolicies = /* @__PURE__ */ new Map();
+  const insertPolicies = /* @__PURE__ */ new Map();
+  const updatePolicies = /* @__PURE__ */ new Map();
   const pins = /* @__PURE__ */ new Map();
+  const splitWritePolicyTables = /* @__PURE__ */ new Set();
   const resolver = { tables };
-  for (const table of canonical.tables) {
-    for (const [access, store] of [
-      ["read", readPolicies],
-      ["write", writePolicies]
-    ]) {
+  for (const table of relations) {
+    const isView = viewNames.has(table.table);
+    const compilePolicyFor = (access, store) => {
       const expression = table.policies[access];
       if (expression === void 0) {
-        store.set(table.table, CONST_TRUE);
-        continue;
+        return;
       }
       try {
         store.set(table.table, compilePolicy({ expression, table: table.table, resolver }));
@@ -1479,37 +1786,117 @@ function buildCompileContext(rawCanonical) {
             table: table.table
           });
           store.set(table.table, CONST_TRUE);
-          continue;
+          return;
         }
         throw error;
       }
+    };
+    compilePolicyFor("read", readPolicies);
+    compilePolicyFor("write", writePolicies);
+    compilePolicyFor("insert", insertPolicies);
+    compilePolicyFor("update", updatePolicies);
+    if (isView) {
+      writePolicies.set(table.table, CONST_FALSE);
+      insertPolicies.set(table.table, CONST_FALSE);
+      updatePolicies.set(table.table, CONST_FALSE);
+      pins.set(table.table, []);
+      continue;
+    }
+    if (table.policies.insert !== void 0 || table.policies.update !== void 0) {
+      splitWritePolicyTables.add(table.table);
+    }
+    const fallbackWrite = writePolicies.get(table.table);
+    const hasSplitPolicy = table.policies.insert !== void 0 || table.policies.update !== void 0;
+    if (!insertPolicies.has(table.table)) {
+      if (fallbackWrite !== void 0) insertPolicies.set(table.table, fallbackWrite);
+      else if (hasSplitPolicy) insertPolicies.set(table.table, CONST_FALSE);
+      else insertPolicies.set(table.table, CONST_TRUE);
     }
-    const tablePins = collectPinnedColumns(writePolicies.get(table.table));
+    if (!updatePolicies.has(table.table)) {
+      if (fallbackWrite !== void 0) updatePolicies.set(table.table, fallbackWrite);
+      else if (hasSplitPolicy) updatePolicies.set(table.table, CONST_FALSE);
+      else updatePolicies.set(table.table, CONST_TRUE);
+    }
+    const tablePins = collectPinnedColumns(insertPolicies.get(table.table));
     pins.set(table.table, tablePins);
     const pinned = new Set(tablePins.map((pin) => pin.column));
     const meta = tables[table.table];
     meta.insertable = meta.insertable.filter((column) => !pinned.has(column));
-    meta.settable = meta.settable.filter((column) => !pinned.has(column));
   }
   if (platformMeta) {
     readPolicies.set(PLATFORM_USER_TABLE, CONST_TRUE);
     writePolicies.set(PLATFORM_USER_TABLE, { kind: "const", value: false });
+    insertPolicies.set(PLATFORM_USER_TABLE, { kind: "const", value: false });
+    updatePolicies.set(PLATFORM_USER_TABLE, { kind: "const", value: false });
     pins.set(PLATFORM_USER_TABLE, []);
   }
   const tableByTypename = new Map(Object.entries(tables).map(([key, meta]) => [meta.typename, key]));
   const queryRoots = /* @__PURE__ */ new Map();
   const mutationRoots = /* @__PURE__ */ new Map();
-  for (const table of canonical.tables) {
+  for (const table of relations) {
     const roots = queryRootNames(table.table);
     queryRoots.set(roots.select, { kind: "select", table: table.table });
-    queryRoots.set(roots.byPk, { kind: "byPk", table: table.table });
+    if ((tables[table.table]?.primaryKey.length ?? 0) > 0) {
+      queryRoots.set(roots.byPk, { kind: "byPk", table: table.table });
+    }
     queryRoots.set(roots.aggregate, { kind: "aggregate", table: table.table });
-    if (table.source === void 0) {
+    const hasWritePolicy = table.policies.write !== void 0 || table.policies.insert !== void 0 || table.policies.update !== void 0;
+    if (!viewNames.has(table.table) && table.source === void 0 && hasWritePolicy) {
       for (const [op, field] of Object.entries(mutationRootNames(table.table))) {
         mutationRoots.set(field, { op, table: table.table });
       }
     }
   }
+  for (const table of relations) {
+    for (const mutation of table.cowMutations ?? []) {
+      const hasWritePolicy = table.policies.write !== void 0 || table.policies.insert !== void 0 || table.policies.update !== void 0;
+      if (!hasWritePolicy) {
+        diagnostics.push({
+          severity: "error",
+          code: "cow-mutation-unpoliced",
+          message: `cow mutation '${mutation.name}' on '${table.table}' requires a write (or insert/update) policy on the overlay table`,
+          table: table.table
+        });
+        continue;
+      }
+      const field = camelCase(mutation.name);
+      if (mutationRoots.has(field) || queryRoots.has(field)) {
+        diagnostics.push({
+          severity: "error",
+          code: "cow-mutation-name-collision",
+          message: `cow mutation '${mutation.name}' on '${table.table}' collides with the generated root '${field}'`,
+          table: table.table
+        });
+        continue;
+      }
+      if (mutation.kind === "override") {
+        const pinned = new Set((pins.get(table.table) ?? []).map((pin) => pin.column));
+        const covered = /* @__PURE__ */ new Set([mutation.pk, ...mutation.copy, ...pinned]);
+        const gaps = table.columns.filter((column) => {
+          if (covered.has(column.name)) return false;
+          const hasDefault = column.default !== void 0 || column.defaultFn !== void 0;
+          return column.nullable === false && !hasDefault;
+        });
+        if (gaps.length > 0) {
+          diagnostics.push({
+            severity: "error",
+            code: "cow-copy-uncovered-column",
+            message: `cow mutation '${mutation.name}' on '${table.table}': overlay-only column(s) ${gaps.map((column) => `'${column.name}'`).join(", ")} are NOT NULL without a default, a policy pin, or a synced contract column \u2014 the copy insert cannot populate them`,
+            table: table.table
+          });
+          continue;
+        }
+      }
+      mutationRoots.set(field, {
+        op: mutation.kind === "override" ? "cowOverride" : "cowRevert",
+        table: table.table,
+        synced: mutation.synced,
+        pk: mutation.pk,
+        set: mutation.set,
+        copyColumns: mutation.copy
+      });
+    }
+  }
   const enumsByTypeName = new Map(canonical.enums.map((e) => [enumTypeName(e.name), e]));
   return {
     ctx: {
@@ -1521,7 +1908,10 @@ function buildCompileContext(rawCanonical) {
       enumsByTypeName,
       readPolicies,
       writePolicies,
-      pins
+      insertPolicies,
+      updatePolicies,
+      pins,
+      splitWritePolicyTables
     },
     diagnostics
   };
@@ -2073,6 +2463,9 @@ var OperationLowerer = class {
     const alias = node.alias?.value ?? name;
     const rootInfo = this.ctx.mutationRoots.get(name);
     if (!rootInfo) fail(`unknown mutation root '${name}'`, "unknown-root", [...this.ctx.mutationRoots.keys()]);
+    if (rootInfo.op === "cowOverride" || rootInfo.op === "cowRevert") {
+      return this.lowerCowRoot(node, rootInfo);
+    }
     const { op, table } = rootInfo;
     const args = argsByName(node);
     if (!node.selectionSet) fail(`'${name}' needs a selection set`, "invalid-selection");
@@ -2142,6 +2535,55 @@ var OperationLowerer = class {
       }
     }
   }
+  /**
+   * Copy-on-write roots: flat args — the pk plus (override only) every
+   * declared set column. Overrides are full snapshots of the set columns, so
+   * every set argument must be supplied explicitly (pass null to clear a
+   * nullable column); the executor generates the copy/update/delete SQL from
+   * the structured fields, never from authored statements.
+   */
+  lowerCowRoot(node, rootInfo) {
+    const name = node.name.value;
+    const alias = node.alias?.value ?? name;
+    const { table } = rootInfo;
+    if (!node.selectionSet) fail(`'${name}' needs a selection set`, "invalid-selection");
+    const meta = this.meta(table);
+    const args = argsByName(node);
+    const pkArg = args.get(rootInfo.pk);
+    if (!pkArg) fail(`'${name}' is missing primary-key argument '${rootInfo.pk}'`, "missing-pk-argument", [rootInfo.pk]);
+    const pk = [{ column: rootInfo.pk, value: this.lowerValue(pkArg.value) }];
+    const base = {
+      kind: "mutation",
+      op: rootInfo.op,
+      alias,
+      table,
+      pinnedColumns: [],
+      affectedRows: false,
+      pk,
+      cowSynced: rootInfo.synced,
+      returning: this.lowerSelection(node.selectionSet, table)
+    };
+    if (rootInfo.op === "cowRevert") {
+      assertKnownArgs(node, [rootInfo.pk]);
+      return base;
+    }
+    assertKnownArgs(node, [rootInfo.pk, ...rootInfo.set]);
+    const entries = rootInfo.set.map((column) => {
+      const arg = args.get(column);
+      if (!arg) {
+        fail(
+          `'${name}' is missing set argument '${column}' \u2014 a cow override writes every declared set column (pass null to clear a nullable one)`,
+          "missing-argument",
+          [...rootInfo.set]
+        );
+      }
+      if (!meta.settable.includes(column)) {
+        fail(`column '${table}.${column}' is not updatable (pinned by the write policy or deprecated)`, "column-not-settable", meta.settable);
+      }
+      return { column, value: this.lowerValue(arg.value) };
+    });
+    return { ...base, set: { entries }, cowCopyColumns: [...rootInfo.copyColumns] };
+  }
   lowerMutationResponse(selectionSet, table) {
     let affectedRows = false;
     let returning = null;
@@ -2617,6 +3059,13 @@ function allowedOps(type) {
       return ["eq", "neq", "contains", "hasKey", "isNull"];
   }
 }
+var CMP_OP_TO_BOOLEXP_KEY = Object.fromEntries(
+  Object.entries(BOOLEXP_OPS2).map(([key, op]) => [op, key])
+);
+function allowedBoolExpOperators(type) {
+  return allowedOps(type).map((op) => CMP_OP_TO_BOOLEXP_KEY[op] ?? `_${op}`);
+}
+var ORDER_BY_DIRECTIONS = Object.keys(ORDER_DIRECTIONS2);
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -2942,6 +3391,6 @@ function validateOnConflictInput({
   return finish(collector, { constraint, updateColumns });
 }
 
-export { COMPILER_MAJOR, CONST_TRUE, DEFAULT_LIMIT, DocumentCompileError, MAX_LIMIT, NamespaceCompileError, OperationLowerer, PLATFORM_USER_TABLE, PLATFORM_USER_TYPENAME, POLICY_COMPARE_OPS, POLICY_MAX_LINK_DEPTH, PolicyCompileError, PolicyParseError, andPred, assertClaimsOnlyWhen, buildCompileContext, camelCase, canonicalOperationText, classifyInputType, collectPinnedColumns, compileNamespace, compileNamespaceOrThrow, compilePolicy, compilePredicateV2, computeOpHash, computeOpsHash, computePinnedColumnsByTable, computeSchemaHash, enumTypeName, flattenOperation, injectPolicies, inputTypeName, lowerOperation, mutationRootNames, parseDocuments, parsePolicy, parseSdl, pascalCase, platformUserMeta, predContains, predContainsExists, queryRootNames, restrictOperation, typeNameForTable, validateAppendInput, validateBoolExpInput, validateInsertInput, validateOnConflictInput, validateOrderByInput, validateSelectColumns, validateSetInput, walkPolicy, walkPred };
+export { COMPILER_MAJOR, CONST_TRUE, DEFAULT_LIMIT, DocumentCompileError, MAX_LIMIT, NamespaceCompileError, ORDER_BY_DIRECTIONS, OperationLowerer, PLATFORM_USER_TABLE, PLATFORM_USER_TYPENAME, POLICY_COMPARE_OPS, POLICY_MAX_LINK_DEPTH, PolicyCompileError, PolicyParseError, allowedBoolExpOperators, allowedOps, andPred, assertClaimsOnlyWhen, buildCompileContext, camelCase, canonicalOperationText, classifyInputType, collectPinnedColumns, compileNamespace, compileNamespaceOrThrow, compilePolicy, compilePredicateV2, computeOpHash, computeOpsHash, computePinnedColumnsByTable, computeSchemaHash, enumTypeName, flattenOperation, injectPolicies, inputTypeName, lowerOperation, mutationRootNames, parseDocuments, parsePolicy, parseSdl, pascalCase, platformUserMeta, predContains, predContainsExists, queryRootNames, restrictOperation, typeNameForTable, validateAppendInput, validateBoolExpInput, validateInsertInput, validateOnConflictInput, validateOrderByInput, validateSelectColumns, validateSetInput, walkPolicy, walkPred };
 //# sourceMappingURL=compiler.js.map
 //# sourceMappingURL=compiler.js.map