@sequenceholdings/orm 2.8.4 → 2.9.0

package/dist/{constants-Dou1RkTo.d.cts → constants-D2o0vK6U.d.cts}

@@ -100,5 +100,12 @@ declare function materializedRefreshFunctionName(table: string): string;
  * a full refresh never reads a snapshot older than a write it then overwrites.
  */
 declare function materializeLockKey(schema: string, table: string): string;
+/**
+ * Committed copy of the exact operation documents a package registers —
+ * GraphQL text and SQL operations already materialized as inert JSON. Atlas
+ * recompiles it to check that a registered operation set is what a commit holds.
+ */
+declare const OPERATION_DOCUMENTS_FILE = "operations.documents.json";
+declare const OPERATION_DOCUMENTS_VERSION: 1;
 
-export { CELLS_FIELD as C, DEFINITION_FILE_EXTENSIONS as D, HASH_DOMAIN as H, IDENTIFIER_PATTERN as I, MATERIALIZE_ACTOR as M, NAMESPACE_PATTERN as N, ORM_DATA_TOKEN_HEADER as O, QUALIFIED_TABLE_PATTERN as Q, RESERVED_COLUMN_NAMES as R, SYNCED_SOURCE_PATTERN as S, CELL_PARTS as a, type CellPart as b, cellColumnName as c, ORM_SERVICE_DATA_TOKEN_HEADER as d, CAPABILITY_KEY_PATTERN as e, CELL_PART_SUFFIX as f, CLAIM_KEY_PATTERN as g, COLUMN_IDENTIFIER_PATTERN as h, CONSUMER_ROLE_SUFFIX as i, MATERIALIZE_CLAIMS_JSON as j, MAX_DEFINITION_FILE_BYTES as k, MAX_GENERATED_SDL_BYTES as l, MAX_IDENTIFIER_LENGTH as m, MAX_PERSISTED_READ_ROWS as n, MAX_TRACKED_COLUMN_NAME as o, NAMESPACE_CONFIG_FILENAMES as p, ORM_REGISTRATION_MAX_BYTES as q, ORM_SCHEMA_PREFIX as r, RESERVED_TABLE_NAMES as s, consumerRoleName as t, materializeLockKey as u, materializedRefreshFunctionName as v, ormSchemaName as w };
+export { CELLS_FIELD as C, DEFINITION_FILE_EXTENSIONS as D, HASH_DOMAIN as H, IDENTIFIER_PATTERN as I, MATERIALIZE_ACTOR as M, NAMESPACE_PATTERN as N, ORM_DATA_TOKEN_HEADER as O, QUALIFIED_TABLE_PATTERN as Q, RESERVED_COLUMN_NAMES as R, SYNCED_SOURCE_PATTERN as S, CELL_PARTS as a, type CellPart as b, cellColumnName as c, ORM_SERVICE_DATA_TOKEN_HEADER as d, CAPABILITY_KEY_PATTERN as e, CELL_PART_SUFFIX as f, CLAIM_KEY_PATTERN as g, COLUMN_IDENTIFIER_PATTERN as h, CONSUMER_ROLE_SUFFIX as i, MATERIALIZE_CLAIMS_JSON as j, MAX_DEFINITION_FILE_BYTES as k, MAX_GENERATED_SDL_BYTES as l, MAX_IDENTIFIER_LENGTH as m, MAX_PERSISTED_READ_ROWS as n, MAX_TRACKED_COLUMN_NAME as o, NAMESPACE_CONFIG_FILENAMES as p, OPERATION_DOCUMENTS_FILE as q, OPERATION_DOCUMENTS_VERSION as r, ORM_REGISTRATION_MAX_BYTES as s, ORM_SCHEMA_PREFIX as t, RESERVED_TABLE_NAMES as u, consumerRoleName as v, materializeLockKey as w, materializedRefreshFunctionName as x, ormSchemaName as y };

package/dist/{constants-Dou1RkTo.d.ts → constants-D2o0vK6U.d.ts}

@@ -100,5 +100,12 @@ declare function materializedRefreshFunctionName(table: string): string;
  * a full refresh never reads a snapshot older than a write it then overwrites.
  */
 declare function materializeLockKey(schema: string, table: string): string;
+/**
+ * Committed copy of the exact operation documents a package registers —
+ * GraphQL text and SQL operations already materialized as inert JSON. Atlas
+ * recompiles it to check that a registered operation set is what a commit holds.
+ */
+declare const OPERATION_DOCUMENTS_FILE = "operations.documents.json";
+declare const OPERATION_DOCUMENTS_VERSION: 1;
 
-export { CELLS_FIELD as C, DEFINITION_FILE_EXTENSIONS as D, HASH_DOMAIN as H, IDENTIFIER_PATTERN as I, MATERIALIZE_ACTOR as M, NAMESPACE_PATTERN as N, ORM_DATA_TOKEN_HEADER as O, QUALIFIED_TABLE_PATTERN as Q, RESERVED_COLUMN_NAMES as R, SYNCED_SOURCE_PATTERN as S, CELL_PARTS as a, type CellPart as b, cellColumnName as c, ORM_SERVICE_DATA_TOKEN_HEADER as d, CAPABILITY_KEY_PATTERN as e, CELL_PART_SUFFIX as f, CLAIM_KEY_PATTERN as g, COLUMN_IDENTIFIER_PATTERN as h, CONSUMER_ROLE_SUFFIX as i, MATERIALIZE_CLAIMS_JSON as j, MAX_DEFINITION_FILE_BYTES as k, MAX_GENERATED_SDL_BYTES as l, MAX_IDENTIFIER_LENGTH as m, MAX_PERSISTED_READ_ROWS as n, MAX_TRACKED_COLUMN_NAME as o, NAMESPACE_CONFIG_FILENAMES as p, ORM_REGISTRATION_MAX_BYTES as q, ORM_SCHEMA_PREFIX as r, RESERVED_TABLE_NAMES as s, consumerRoleName as t, materializeLockKey as u, materializedRefreshFunctionName as v, ormSchemaName as w };
+export { CELLS_FIELD as C, DEFINITION_FILE_EXTENSIONS as D, HASH_DOMAIN as H, IDENTIFIER_PATTERN as I, MATERIALIZE_ACTOR as M, NAMESPACE_PATTERN as N, ORM_DATA_TOKEN_HEADER as O, QUALIFIED_TABLE_PATTERN as Q, RESERVED_COLUMN_NAMES as R, SYNCED_SOURCE_PATTERN as S, CELL_PARTS as a, type CellPart as b, cellColumnName as c, ORM_SERVICE_DATA_TOKEN_HEADER as d, CAPABILITY_KEY_PATTERN as e, CELL_PART_SUFFIX as f, CLAIM_KEY_PATTERN as g, COLUMN_IDENTIFIER_PATTERN as h, CONSUMER_ROLE_SUFFIX as i, MATERIALIZE_CLAIMS_JSON as j, MAX_DEFINITION_FILE_BYTES as k, MAX_GENERATED_SDL_BYTES as l, MAX_IDENTIFIER_LENGTH as m, MAX_PERSISTED_READ_ROWS as n, MAX_TRACKED_COLUMN_NAME as o, NAMESPACE_CONFIG_FILENAMES as p, OPERATION_DOCUMENTS_FILE as q, OPERATION_DOCUMENTS_VERSION as r, ORM_REGISTRATION_MAX_BYTES as s, ORM_SCHEMA_PREFIX as t, RESERVED_TABLE_NAMES as u, consumerRoleName as v, materializeLockKey as w, materializedRefreshFunctionName as x, ormSchemaName as y };

package/dist/dynamic-input.d.cts

@@ -1,6 +1,6 @@
 import { CmpOp, TableMetaIr } from './ir.cjs';
 import 'zod';
-import './constants-Dou1RkTo.cjs';
+import './constants-D2o0vK6U.cjs';
 
 /**
  * §4f dynamic-input validators — PURE, data-only functions the data plane

package/dist/dynamic-input.d.ts

@@ -1,6 +1,6 @@
 import { CmpOp, TableMetaIr } from './ir.js';
 import 'zod';
-import './constants-Dou1RkTo.js';
+import './constants-D2o0vK6U.js';
 
 /**
  * §4f dynamic-input validators — PURE, data-only functions the data plane

package/dist/index.cjs

@@ -205,6 +205,8 @@ function materializedRefreshFunctionName(table) {
 function materializeLockKey(schema, table) {
   return `orm:materialize:${schema}.${table}`;
 }
+var OPERATION_DOCUMENTS_FILE = "operations.documents.json";
+var OPERATION_DOCUMENTS_VERSION = 1;
 
 // src/errors.ts
 var OrmDefinitionError = class extends Error {
@@ -1189,6 +1191,48 @@ var policyExpressionSchema = zod.z.union([
     variants: zod.z.array(policyVariantSchema).max(10).default([])
   })
 ]);
+
+// src/canonical/resolved-rows.ts
+function logicalKey(table) {
+  return (table.primaryKey ?? []).map((columnName) => table.columns.find((c) => c.columnName === columnName)?.name ?? columnName);
+}
+function sameKey(key, expected) {
+  return key.length === expected.length && key.every((name2) => expected.includes(name2));
+}
+function validateRowIdentity(input) {
+  validateExistsIn(input);
+  if (input.keys.length > 1) validateCompositeKey(input);
+}
+function validateExistsIn({ resolved, sourceByName, fail: fail3 }) {
+  const name2 = resolved.existsIn?.[0];
+  if (name2 === void 0) return;
+  if (sourceByName.get(name2)?.kind !== "etl") fail3(`existsIn '${name2}' must be an etl source`);
+  if (resolved.policies.insert !== void 0 || resolved.policies.write !== void 0) {
+    fail3("existsIn allows only an update policy: rows come from the etl source");
+  }
+}
+function validateCompositeKey({ resolved, keys, tableByName, fail: fail3 }) {
+  const keyList = `(${keys.join(", ")})`;
+  if (resolved.existsIn === void 0) {
+    fail3(`requires exactly one primary-key column: composite key ${keyList} requires existsIn`);
+    return;
+  }
+  const writes = ["insert", "update", "write"].filter((kind) => resolved.policies[kind] !== void 0);
+  if (writes.length > 0) fail3(`composite key ${keyList} requires a read-only table: remove the ${writes.join("/")} policy`);
+  if (resolved.materialized) fail3(`composite key ${keyList} cannot be materialized`);
+  for (const source of resolved.sources) {
+    if (source.kind === "prefetch") {
+      fail3(`composite key ${keyList} cannot have prefetch source '${source.name}'`);
+      continue;
+    }
+    const table = tableByName.get(source.table);
+    if (table && !sameKey(logicalKey(table), keys)) {
+      fail3(`composite key ${keyList} requires ${source.kind} source '${source.name}' to be keyed by it; table '${source.table}' is keyed by (${logicalKey(table).join(", ")})`);
+    }
+  }
+}
+
+// src/canonical/resolved.ts
 function parseDurationMs(input) {
   if (typeof input === "number") return Number.isInteger(input) && input > 0 ? input : void 0;
   const match = /^(\d+(?:\.\d+)?)(ms|s|m)$/.exec(input);
@@ -1265,6 +1309,13 @@ var canonicalResolvedSchema = zod.z.object({
   resolve: zod.z.array(canonicalResolveRuleSchema).max(500),
   /** Sources whose tombstone hides the resolved row (v1: the manual source only). */
   deletedBy: zod.z.array(identifier).max(1).default([]),
+  /**
+   * `rows.existsIn`: the one etl source whose rows are the table's rows (read
+   * directly as the row source). Only an update policy may write. It is also
+   * what admits a composite primary key: a read-only table keyed exactly like
+   * that source.
+   */
+  existsIn: zod.z.array(identifier).length(1).optional(),
   /**
    * Materialized: the view reads an indexed internal table (`table`) that the
    * data plane keeps in step with `compute`, the internal view holding the
@@ -1283,8 +1334,8 @@ function validateResolvedView({ view, tables, views = [] }) {
   if (!resolved) return [];
   const errors = [];
   const fail3 = (message) => errors.push(`resolved table '${view.view}': ${message}`);
-  const pkColumn = view.primaryKey?.length === 1 ? view.columns.find((c) => c.columnName === view.primaryKey?.[0]) : void 0;
-  if (!pkColumn) {
+  const keyColumns = (view.primaryKey ?? []).map((columnName) => view.columns.find((c) => c.columnName === columnName)).filter((column) => column !== void 0);
+  if (keyColumns.length === 0 || keyColumns.length !== view.primaryKey?.length) {
     fail3("requires exactly one primary-key column");
     return errors;
   }
@@ -1292,7 +1343,7 @@ function validateResolvedView({ view, tables, views = [] }) {
   const scope = {
     view,
     resolved,
-    pkColumn,
+    keys: new Map(keyColumns.map((column) => [column.name, column])),
     dataColumns: new Map(view.columns.filter((c) => !systemNames.has(c.name) && c.cell === void 0).map((c) => [c.name, c])),
     sourceByName: /* @__PURE__ */ new Map(),
     fail: fail3
@@ -1306,6 +1357,7 @@ function validateResolvedView({ view, tables, views = [] }) {
     if (!table) fail3(`source '${source.name}' references unknown table '${source.table}'`);
     else validateSource({ scope, source, table });
   }
+  validateRowIdentity({ resolved, keys: [...scope.keys.keys()], sourceByName: scope.sourceByName, tableByName, fail: fail3 });
   validateRules(scope);
   validateViewCells(scope);
   if (resolved.materialized) validateMaterialized({ scope, tableByName, views });
@@ -1335,7 +1387,7 @@ function validateSource({ scope, source, table }) {
   validatePrefetchFields({ scope, source });
 }
 function validatePrefetchFields({ scope, source }) {
-  const { fail: fail3, pkColumn } = scope;
+  const { fail: fail3, keys } = scope;
   if (source.kind !== "prefetch") {
     if (source.key || source.fetch || source.function || source.prefetchDefaults || source.writeback) {
       fail3(`only prefetch sources may declare key/fetch/function/prefetchDefaults/writeback ('${source.name}')`);
@@ -1344,7 +1396,7 @@ function validatePrefetchFields({ scope, source }) {
   }
   if (!source.key || !source.fetch || !source.function || !source.prefetchDefaults) {
     fail3(`prefetch source '${source.name}' requires key, fetch, function and prefetchDefaults`);
-  } else if (source.key !== pkColumn.name && !source.columns.includes(source.key)) {
+  } else if (!keys.has(source.key) && !source.columns.includes(source.key)) {
     fail3(`prefetch source '${source.name}' key '${source.key}' must be the primary key or one of its columns`);
   }
   for (const column of source.writeback?.columns ?? []) {
@@ -1352,19 +1404,19 @@ function validatePrefetchFields({ scope, source }) {
   }
 }
 function validateSourceColumns({ scope, source, byName }) {
-  const { fail: fail3, pkColumn, dataColumns } = scope;
-  for (const column of [pkColumn.name, ...source.columns]) {
-    const own = column === pkColumn.name ? pkColumn : dataColumns.get(column);
+  const { fail: fail3, keys, dataColumns } = scope;
+  for (const column of [...keys.keys(), ...source.columns]) {
+    const own = keys.get(column) ?? dataColumns.get(column);
     const theirs = byName.get(column);
     if (!own) fail3(`source '${source.name}' supplies unknown column '${column}'`);
     else if (!theirs) fail3(`source '${source.name}' table '${source.table}' has no column '${column}'`);
     else if (JSON.stringify(theirs.type) !== JSON.stringify(own.type)) fail3(`column '${column}' has a different type on source '${source.name}'`);
   }
 }
-function validateRules({ resolved, pkColumn, dataColumns, sourceByName, fail: fail3 }) {
+function validateRules({ resolved, keys, dataColumns, sourceByName, fail: fail3 }) {
   const ruled = /* @__PURE__ */ new Set();
   for (const rule of resolved.resolve) {
-    if (!dataColumns.has(rule.column) || rule.column === pkColumn.name) {
+    if (!dataColumns.has(rule.column) || keys.has(rule.column)) {
       fail3(`resolve rule targets unknown column '${rule.column}'`);
       continue;
     }
@@ -1381,7 +1433,7 @@ function validateRules({ resolved, pkColumn, dataColumns, sourceByName, fail: fa
     }
   }
   for (const column of dataColumns.keys()) {
-    if (column !== pkColumn.name && !ruled.has(column)) fail3(`column '${column}' has no resolve rule`);
+    if (!keys.has(column) && !ruled.has(column)) fail3(`column '${column}' has no resolve rule`);
   }
 }
 var VIEW_CELL_TYPES = {
@@ -1390,10 +1442,10 @@ var VIEW_CELL_TYPES = {
   by: "text",
   conflicts: "jsonb"
 };
-function validateViewCells({ view, dataColumns, pkColumn, fail: fail3 }) {
+function validateViewCells({ view, dataColumns, keys, fail: fail3 }) {
   const expected = /* @__PURE__ */ new Map();
   for (const column of dataColumns.values()) {
-    if (column.name === pkColumn.name) continue;
+    if (keys.has(column.name)) continue;
     for (const part of RESOLVED_VIEW_CELL_PARTS) {
       expected.set(cellColumnName(column.name, part), { part, columnName: cellColumnName(column.columnName, part) });
     }
@@ -2266,8 +2318,9 @@ function planSource(input) {
 }
 var tombstoned = () => t.boolean(RESOLVED_SOURCE_SYSTEM_COLUMNS.tombstoned.columnName).notNull().default(false);
 function internalTable(input, supplied, system, options = {}) {
-  const { viewName, sourceName, columns, pk, pkBuilder } = input;
-  const tableColumns = { [pk]: cloneColumn({ builder: pkBuilder, property: pk, notNull: true, primaryKey: true }) };
+  const { viewName, sourceName, columns, keys } = input;
+  const tableColumns = {};
+  for (const key of keys) tableColumns[key] = cloneColumn({ builder: columns[key], property: key, notNull: true, primaryKey: true });
   for (const property of supplied) {
     tableColumns[property] = cloneColumn({ builder: columns[property], property, notNull: false, primaryKey: false });
   }
@@ -2284,12 +2337,14 @@ function assertColumns(input, list2, what) {
   for (const column of list2) if (!input.dataColumns.includes(column)) input.fail(`${what} names unknown column "${column}"`);
 }
 function planEtl(input, source) {
-  const { sourceName, pk, dataColumns, fail: fail3 } = input;
+  const { sourceName, keys, dataColumns, fail: fail3 } = input;
   const table = typeof source.table === "function" ? source.table() : source.table;
   if (!isSeqTable(table) || table.source === void 0) fail3(`etl source "${sourceName}" must reference a defineSyncedTable`);
   const synced = table;
   if (synced.config.primaryKey?.length === 0) fail3(`etl source "${sourceName}" cannot use an unkeyed synced table for resolved row identity`);
-  if (!(pk in synced.columns)) fail3(`etl source "${sourceName}" table "${synced.tableName}" has no "${pk}" column`);
+  for (const key of keys) {
+    if (!(key in synced.columns)) fail3(`etl source "${sourceName}" table "${synced.tableName}" has no "${key}" column`);
+  }
   const supplied = source.columns ? [...source.columns] : dataColumns.filter((column) => column in synced.columns);
   assertColumns(input, supplied, `etl source "${sourceName}"`);
   if (source.updatedAt !== void 0 && !(source.updatedAt in synced.columns)) {
@@ -2298,9 +2353,9 @@ function planEtl(input, source) {
   return { name: sourceName, kind: "etl", table: synced, columns: supplied, ...source.updatedAt ? { updatedAt: source.updatedAt } : {} };
 }
 function planPrefetch(input, source) {
-  const { sourceName, pk, fail: fail3 } = input;
+  const { sourceName, keys, fail: fail3 } = input;
   assertColumns(input, source.columns, `prefetch source "${sourceName}"`);
-  if (source.key !== pk && !source.columns.includes(source.key)) {
+  if (!keys.includes(source.key) && !source.columns.includes(source.key)) {
     fail3(`prefetch source "${sourceName}" key "${source.key}" must be the primary key or one of its columns`);
   }
   for (const column of source.writeback?.columns ?? []) {
@@ -2353,7 +2408,7 @@ var PG_TYPE = {
 var ident = (value) => `"${value.replace(/"/g, '""')}"`;
 var literal = (value) => `'${value.replace(/'/g, "''")}'`;
 var physical = ({ source, property }) => source.table.columns[property].columnNameFor(property);
-function candidateSql({ source, column, pk, pgType }) {
+function candidateSql({ source, column, key, pgType }) {
   const a = ident(`s_${source.name}`);
   const name2 = physical({ source, property: column });
   const value = `CAST(${a}.${ident(name2)} AS ${pgType})`;
@@ -2361,7 +2416,7 @@ function candidateSql({ source, column, pk, pgType }) {
     return {
       source: source.name,
       value,
-      has: `(${a}.${ident(physical({ source, property: pk }))} IS NOT NULL)`,
+      has: `(${a}.${ident(physical({ source, property: key }))} IS NOT NULL)`,
       at: source.updatedAt ? `CAST(${a}.${ident(physical({ source, property: source.updatedAt }))} AS timestamptz)` : "CAST(NULL AS timestamptz)",
       by: "CAST(NULL AS text)"
     };
@@ -2449,39 +2504,44 @@ function customCell({ candidates, orderBy, index: index3 }) {
 }
 function buildResolvedQuery({ context, plan }) {
   const { qb, relation } = context;
-  const pkColumn = plan.columns[plan.pk].columnNameFor(plan.pk);
+  const keyColumns = plan.keys.map((key) => plan.columns[key].columnNameFor(key));
   const alias = (source) => ident(`s_${source}`);
   const tombstoned2 = RESOLVED_SOURCE_SYSTEM_COLUMNS.tombstoned.columnName;
   const sourceByName = new Map(plan.plans.map((source) => [source.name, source]));
   const schema = pgCore.getTableConfig(relation(plan.plans[0].table)).schema;
   const keySource = plan.existsIn === void 0 ? void 0 : sourceByName.get(plan.existsIn);
-  const keyRef = keySource ? `${alias(keySource.name)}.${ident(physical({ source: keySource, property: plan.pk }))}` : `"k".${ident(pkColumn)}`;
+  const keyRefs = plan.keys.map((key, index3) => keySource ? `${alias(keySource.name)}.${ident(physical({ source: keySource, property: key }))}` : `"k".${ident(keyColumns[index3])}`);
   const keyBranches = plan.plans.map((source) => {
     const where = source.kind === "prefetch" ? drizzleOrm.sql.raw(` WHERE NOT ${ident(tombstoned2)}`) : drizzleOrm.sql.raw("");
-    const sourcePk = ident(physical({ source, property: plan.pk }));
-    const selectedPk = sourcePk === ident(pkColumn) ? sourcePk : `${sourcePk} AS ${ident(pkColumn)}`;
-    return drizzleOrm.sql`SELECT ${drizzleOrm.sql.raw(selectedPk)} FROM ${relation(source.table)}${where}`;
+    const selectedKey = plan.keys.map((key, index3) => {
+      const sourceKey = ident(physical({ source, property: key }));
+      return sourceKey === ident(keyColumns[index3]) ? sourceKey : `${sourceKey} AS ${ident(keyColumns[index3])}`;
+    });
+    return drizzleOrm.sql`SELECT ${drizzleOrm.sql.raw(selectedKey.join(", "))} FROM ${relation(source.table)}${where}`;
   });
   const base2 = keySource ? drizzleOrm.sql`${relation(keySource.table)} AS ${drizzleOrm.sql.raw(alias(keySource.name))}` : drizzleOrm.sql`(${drizzleOrm.sql.join(keyBranches, drizzleOrm.sql.raw(" UNION "))}) AS "k"`;
-  const joins = plan.plans.filter((source) => source !== keySource).map(
-    (source) => drizzleOrm.sql` LEFT JOIN ${relation(source.table)} AS ${drizzleOrm.sql.raw(alias(source.name))} ON ${drizzleOrm.sql.raw(`${alias(source.name)}.${ident(physical({ source, property: plan.pk }))} = ${keyRef}`)}`
-  );
+  const joins = plan.plans.filter((source) => source !== keySource).map((source) => {
+    const on = plan.keys.map((key, index3) => `${alias(source.name)}.${ident(physical({ source, property: key }))} = ${keyRefs[index3]}`);
+    return drizzleOrm.sql` LEFT JOIN ${relation(source.table)} AS ${drizzleOrm.sql.raw(alias(source.name))} ON ${drizzleOrm.sql.raw(on.join(" AND "))}`;
+  });
   const cells = /* @__PURE__ */ new Map();
   plan.rules.forEach((rule, index3) => {
     const canonical = plan.columns[rule.column].toCanonicalColumn(rule.column);
     const pgType = typeof canonical.type === "string" ? PG_TYPE[canonical.type] : `${schema === void 0 ? "" : `${ident(schema)}.`}${ident(canonical.type.enum)}`;
-    const candidates = rule.candidates.map((name2) => candidateSql({ source: sourceByName.get(name2), column: rule.column, pk: plan.pk, pgType }));
+    const candidates = rule.candidates.map((name2) => candidateSql({ source: sourceByName.get(name2), column: rule.column, key: plan.keys[0], pgType }));
     cells.set(rule.column, keySource && rule.candidates.length === 1 && rule.candidates[0] === keySource.name ? existsInCell(candidates[0]) : rule.comparator === "custom" ? customCell({ candidates, orderBy: rule.orderBy, index: index3 }) : builtinCell({ comparator: rule.comparator, candidates }));
   });
   const laterals = [...cells.values()].flatMap((cell) => cell.lateral ? [drizzleOrm.sql.raw(cell.lateral)] : []);
   const from = drizzleOrm.sql.join([base2, ...joins, ...laterals], drizzleOrm.sql.raw(""));
-  const selected = {
-    [plan.pk]: drizzleOrm.sql.raw(keyRef).as(pkColumn)
-  };
+  const selected = {};
   for (const [property, builder] of Object.entries(plan.columns)) {
-    if (property === plan.pk) continue;
-    const cell = cells.get(property);
     const columnName = builder.columnNameFor(property);
+    const keyIndex = plan.keys.indexOf(property);
+    if (keyIndex !== -1) {
+      selected[property] = drizzleOrm.sql.raw(keyRefs[keyIndex]).as(columnName);
+      continue;
+    }
+    const cell = cells.get(property);
     selected[property] = drizzleOrm.sql.raw(cell.value).as(columnName);
     for (const [part, expression] of Object.entries(cell.parts)) {
       selected[cellColumnName(property, part)] = drizzleOrm.sql.raw(expression).as(cellColumnName(columnName, part));
@@ -2495,6 +2555,44 @@ function buildResolvedQuery({ context, plan }) {
   const query = qb.select(selected).from(from);
   return hidden.length > 0 ? query.where(drizzleOrm.sql.raw(hidden.join(" AND "))) : query;
 }
+
+// src/authoring/resolved-rows.ts
+function planKeys({ columns, config, fail: fail3 }) {
+  const keys = Object.entries(columns).filter(([, builder]) => builder.isPrimaryKey).map(([property]) => property);
+  if (keys.length === 0) fail3("declare exactly one .primaryKey() column");
+  if (keys.length === 1) return keys;
+  const key = `(${keys.join(", ")})`;
+  if (config.rows?.existsIn === void 0) fail3(`declare exactly one .primaryKey() column: composite key ${key} requires rows.existsIn`);
+  const writes = ["insert", "update", "write"].filter((kind) => config.policies[kind] !== void 0);
+  if (writes.length > 0) fail3(`composite key ${key} requires a read-only table: remove the ${writes.join("/")} policy`);
+  if (config.materialize) fail3(`composite key ${key} cannot be materialized`);
+  const prefetch = Object.entries(config.sources).find(([, source]) => source.kind === "prefetch");
+  if (prefetch) fail3(`composite key ${key} cannot have prefetch source "${prefetch[0]}"`);
+  return keys;
+}
+function assertCompositeSourceKeys({ keys, plans, fail: fail3 }) {
+  if (keys.length === 1) return;
+  for (const plan of plans) {
+    if (plan.kind !== "etl") continue;
+    const sourceKey = declaredPrimaryKeyProperties(plan.table);
+    if (sourceKey.length !== keys.length || !keys.every((key) => sourceKey.includes(key))) {
+      fail3(`composite key (${keys.join(", ")}) requires etl source "${plan.name}" to be keyed by it; table "${plan.table.tableName}" is keyed by (${sourceKey.join(", ")})`);
+    }
+  }
+}
+function planExistsIn({ config, plans, fail: fail3 }) {
+  const names = config.rows?.existsIn;
+  if (names === void 0) return void 0;
+  if (names.length !== 1) fail3("rows.existsIn names exactly one etl source");
+  const source = plans.find((plan) => plan.name === names[0]);
+  if (source?.kind !== "etl") return fail3(`rows.existsIn "${names[0]}" must be an etl source`);
+  if (config.policies.insert !== void 0 || config.policies.write !== void 0) fail3("rows.existsIn allows only an update policy: rows come from the etl source");
+  return source;
+}
+function inheritedNotNullColumns({ existsIn, rules }) {
+  if (!existsIn) return /* @__PURE__ */ new Set();
+  return new Set(rules.filter((rule) => rule.candidates.length === 1 && rule.candidates[0] === existsIn.name).map((rule) => rule.column).filter((column) => existsIn.table.columns[column]?.toCanonicalColumn(column).nullable === false));
+}
 function managedFn(id) {
   return { kind: "managed", id };
 }
@@ -2533,28 +2631,28 @@ function defineResolvedTable(name2, columns, config) {
       fail3(`column "${property}" is too long for a resolved table (max ${MAX_TRACKED_COLUMN_NAME} characters, room for cell parts)`);
     }
   }
-  const pkEntries = Object.entries(columns).filter(([, builder]) => builder.isPrimaryKey);
-  if (pkEntries.length !== 1) fail3("declare exactly one .primaryKey() column");
-  const [pk, pkBuilder] = pkEntries[0];
-  const dataColumns = Object.keys(columns).filter((property) => property !== pk);
+  const keys = planKeys({ columns, config, fail: fail3 });
+  const dataColumns = Object.keys(columns).filter((property) => !keys.includes(property));
   if (dataColumns.length === 0) fail3("declare at least one non-key column");
   const sourceEntries = Object.entries(config.sources);
   if (sourceEntries.filter(([, source]) => source.kind === "manual").length !== 1) fail3("declare exactly one manualSource()");
   const plans = sourceEntries.map(
-    ([sourceName, input]) => planSource({ viewName: name2, sourceName, input, columns, pk, pkBuilder, dataColumns, fail: fail3 })
+    ([sourceName, input]) => planSource({ viewName: name2, sourceName, input, columns, keys, dataColumns, fail: fail3 })
   );
   const rules = planRules({ config, plans, dataColumns, fail: fail3 });
   const deletedBy = [...config.rows?.deletedBy ?? []];
   for (const source of deletedBy) {
     if (plans.find((plan) => plan.name === source)?.kind !== "manual") fail3(`rows.deletedBy "${source}" must be the manual source`);
   }
+  assertCompositeSourceKeys({ keys, plans, fail: fail3 });
   const existsIn = planExistsIn({ config, plans, fail: fail3 });
-  const notNullColumns = existsIn ? inheritedNotNullColumns({ existsIn, rules }) : /* @__PURE__ */ new Set();
+  const notNullColumns = inheritedNotNullColumns({ existsIn, rules });
   const partType = { source: t.text, at: t.timestamptz, by: t.text, conflicts: t.jsonb };
   const viewColumns = {};
   for (const [property, builder] of Object.entries(columns)) {
-    viewColumns[property] = cloneColumn({ builder, property, notNull: property === pk || notNullColumns.has(property), primaryKey: property === pk });
-    if (property === pk) continue;
+    const isKey = keys.includes(property);
+    viewColumns[property] = cloneColumn({ builder, property, notNull: isKey || notNullColumns.has(property), primaryKey: isKey });
+    if (isKey) continue;
     const columnName = builder.columnNameFor(property);
     for (const part of RESOLVED_VIEW_CELL_PARTS) {
       viewColumns[cellColumnName(property, part)] = partType[part](cellColumnName(columnName, part)).cellPart(property, part);
@@ -2567,9 +2665,10 @@ function defineResolvedTable(name2, columns, config) {
     sources: plans,
     rules,
     deletedBy,
+    ...existsIn ? { existsIn: [existsIn.name] } : {},
     policies: writePolicies
   };
-  const queryPlan = { columns, pk, plans, rules, deletedBy, ...existsIn ? { existsIn: existsIn.name } : {} };
+  const queryPlan = { columns, keys, plans, rules, deletedBy, ...existsIn ? { existsIn: existsIn.name } : {} };
   const typedColumns = viewColumns;
   const surface = {
     ...config.description !== void 0 ? { description: config.description } : {},
@@ -2611,18 +2710,6 @@ function defineResolvedTable(name2, columns, config) {
     }
   });
 }
-function planExistsIn({ config, plans, fail: fail3 }) {
-  const names = config.rows?.existsIn;
-  if (names === void 0) return void 0;
-  if (names.length !== 1) fail3("rows.existsIn names exactly one etl source");
-  const source = plans.find((plan) => plan.name === names[0]);
-  if (source?.kind !== "etl") fail3(`rows.existsIn "${names[0]}" must be an etl source`);
-  if (config.policies.insert !== void 0 || config.policies.write !== void 0) fail3("rows.existsIn allows only an update policy: rows come from the etl source");
-  return source;
-}
-function inheritedNotNullColumns({ existsIn, rules }) {
-  return new Set(rules.filter((rule) => rule.candidates.length === 1 && rule.candidates[0] === existsIn.name).map((rule) => rule.column).filter((column) => existsIn.table.columns[column]?.toCanonicalColumn(column).nullable === false));
-}
 function planRules({ config, plans, dataColumns, fail: fail3 }) {
   const kindOrder = { manual: 0, prefetch: 1, etl: 2 };
   const fallback = config.default ?? priority([...plans].sort((a, b) => kindOrder[a.kind] - kindOrder[b.kind]).map((plan) => plan.name));
@@ -3222,6 +3309,7 @@ function buildCanonicalResolved(resolved) {
     })),
     resolve: resolved.rules.map((rule) => ({ ...rule, candidates: [...rule.candidates] })),
     deletedBy: [...resolved.deletedBy],
+    ...resolved.existsIn !== void 0 ? { existsIn: [...resolved.existsIn] } : {},
     ...resolved.materialized ? { materialized: { ...resolved.materialized } } : {},
     policies
   };
@@ -7147,8 +7235,13 @@ var resolvedSourceIrSchema = zod.z.object({
   }).optional()
 });
 var resolvedMetaIrSchema = zod.z.object({
-  /** Logical pk column of the resolved view (single-column). */
-  pk: zod.z.string(),
+  /**
+   * Logical pk column of the resolved view. Absent for a composite key, which
+   * only a read-only `existsIn` table may declare: it has no writes, prefetch
+   * or materialization (the paths that address one key column), and its reads
+   * use the view's `primaryKey` like any keyed view.
+   */
+  pk: zod.z.string().optional(),
   /** Source name of the manual source. */
   manual: zod.z.string(),
   sources: zod.z.array(resolvedSourceIrSchema),
@@ -7543,6 +7636,42 @@ async function readSnapshot(dir, ordinal) {
   const path$1 = path.join(dir, MIGRATIONS_DIRNAME, META_DIRNAME, `${pad(ordinal)}.snapshot.json`);
   return parseJson(path$1, await readSnapshotText(dir, ordinal));
 }
+async function verifyCommittedLedger(dir, entries) {
+  const firstRequiredSnapshot = entries.length - 2;
+  let previousId3;
+  let previousSnapshotPresent = false;
+  let previousHash = null;
+  for (const [index3, entry] of entries.entries()) {
+    const sql7 = await readMigrationSql(dir, entry);
+    if (checksumOf(sql7) !== entry.checksum) {
+      return `${MIGRATIONS_DIRNAME}/${entry.name}.sql does not match its journal checksum \u2014 committed migrations must not be edited`;
+    }
+    const snapshotText = index3 >= firstRequiredSnapshot ? await readSnapshotText(dir, entry.ordinal) : await readPrunableSnapshotText(dir, entry.ordinal);
+    if (snapshotText !== void 0) {
+      if (checksumOf(snapshotText) !== entry.snapshot_checksum) {
+        return `the snapshot for ${entry.name} does not match its journal checksum \u2014 committed snapshots must not be edited (the next diff builds on it)`;
+      }
+      const snapshot = JSON.parse(snapshotText);
+      if (previousSnapshotPresent && snapshot.prevId !== previousId3) {
+        return `snapshot chain broken at ${entry.name} \u2014 regenerate the workspace with \`seq-studio orm diff\``;
+      }
+      previousId3 = snapshot.id;
+    }
+    previousSnapshotPresent = snapshotText !== void 0;
+    if (entry.previous_content_hash !== previousHash) {
+      return `content-hash chain broken at ${entry.name} \u2014 migrations must be appended in order by \`seq-studio orm diff\``;
+    }
+    previousHash = entry.content_hash;
+  }
+  return void 0;
+}
+async function readPrunableSnapshotText(dir, ordinal) {
+  const path$1 = path.join(dir, MIGRATIONS_DIRNAME, META_DIRNAME, `${pad(ordinal)}.snapshot.json`);
+  return promises.readFile(path$1, "utf8").catch((error) => {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+    throw error;
+  });
+}
 async function readMigrationSql(dir, entry) {
   const path$1 = path.join(dir, MIGRATIONS_DIRNAME, `${entry.name}.sql`);
   return promises.readFile(path$1, "utf8").catch(() => {
@@ -7703,30 +7832,10 @@ async function checkWorkspace({
     log(`no committed migrations for '${loaded.definition.namespace}' \u2014 run \`seq-studio orm diff\` and commit the result`);
     return 1;
   }
-  let previousId3;
-  let previousHash = null;
-  for (const entry of workspace.journal.entries) {
-    const sql7 = await readMigrationSql(dir, entry);
-    if (checksumOf(sql7) !== entry.checksum) {
-      log(`${MIGRATIONS_DIRNAME}/${entry.name}.sql does not match its journal checksum \u2014 committed migrations must not be edited`);
-      return 1;
-    }
-    const snapshotText = await readSnapshotText(dir, entry.ordinal);
-    if (checksumOf(snapshotText) !== entry.snapshot_checksum) {
-      log(`the snapshot for ${entry.name} does not match its journal checksum \u2014 committed snapshots must not be edited (the next diff builds on it)`);
-      return 1;
-    }
-    const snapshot = JSON.parse(snapshotText);
-    if (entry.ordinal > 1 && snapshot.prevId !== previousId3) {
-      log(`snapshot chain broken at ${entry.name} \u2014 regenerate the workspace with \`seq-studio orm diff\``);
-      return 1;
-    }
-    if (entry.previous_content_hash !== previousHash) {
-      log(`content-hash chain broken at ${entry.name} \u2014 migrations must be appended in order by \`seq-studio orm diff\``);
-      return 1;
-    }
-    previousId3 = snapshot.id;
-    previousHash = entry.content_hash;
+  const broken = await verifyCommittedLedger(dir, workspace.journal.entries);
+  if (broken) {
+    log(broken);
+    return 1;
   }
   if (tip.content_hash !== loaded.contentHash) {
     log(`definitions changed since ${tip.name} \u2014 run \`seq-studio orm diff\` and commit the new migration`);
@@ -8550,6 +8659,8 @@ exports.NAMESPACE_CONFIG_BRAND = NAMESPACE_CONFIG_BRAND;
 exports.NAMESPACE_CONFIG_FILE = NAMESPACE_CONFIG_FILE;
 exports.NAMESPACE_CONFIG_FILENAMES = NAMESPACE_CONFIG_FILENAMES;
 exports.NAMESPACE_PATTERN = NAMESPACE_PATTERN;
+exports.OPERATION_DOCUMENTS_FILE = OPERATION_DOCUMENTS_FILE;
+exports.OPERATION_DOCUMENTS_VERSION = OPERATION_DOCUMENTS_VERSION;
 exports.ORM_DATA_TOKEN_HEADER = ORM_DATA_TOKEN_HEADER;
 exports.ORM_MIGRATION_EXPORT_FILE = ORM_MIGRATION_EXPORT_FILE;
 exports.ORM_MIGRATION_EXPORT_MAX_BYTES = ORM_MIGRATION_EXPORT_MAX_BYTES;