@sequenceholdings/orm 2.8.3 → 2.8.5

package/dist/canonical.d.cts

@@ -103,8 +103,8 @@ declare const canonicalResolvedSourceSchema: z.ZodObject<{
     name: z.ZodString;
     kind: z.ZodEnum<{
         manual: "manual";
-        prefetch: "prefetch";
         etl: "etl";
+        prefetch: "prefetch";
     }>;
     table: z.ZodString;
     columns: z.ZodArray<z.ZodString>;
@@ -161,8 +161,8 @@ declare const canonicalResolvedSchema: z.ZodObject<{
         name: z.ZodString;
         kind: z.ZodEnum<{
             manual: "manual";
-            prefetch: "prefetch";
             etl: "etl";
+            prefetch: "prefetch";
         }>;
         table: z.ZodString;
         columns: z.ZodArray<z.ZodString>;
@@ -213,6 +213,7 @@ declare const canonicalResolvedSchema: z.ZodObject<{
         orderBy: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
     materialized: z.ZodOptional<z.ZodObject<{
         table: z.ZodString;
         compute: z.ZodString;
@@ -302,7 +303,7 @@ declare function validateResolvedView({ view, tables, views }: {
  * server-side), and the SDL generator / GraphQL compiler / migration engine
  * all consume it.
  *
- * FROZEN CONTRACT (week 1): downstream tracks build against these shapes.
+ * FROZEN CONTRACT: downstream consumers build against these shapes.
  * Additive evolution only; `definition_format` discriminates on the wire.
  */
 
@@ -807,8 +808,8 @@ declare const canonicalViewSchema: z.ZodObject<{
             name: z.ZodString;
             kind: z.ZodEnum<{
                 manual: "manual";
-                prefetch: "prefetch";
                 etl: "etl";
+                prefetch: "prefetch";
             }>;
             table: z.ZodString;
             columns: z.ZodArray<z.ZodString>;
@@ -859,6 +860,7 @@ declare const canonicalViewSchema: z.ZodObject<{
             orderBy: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
         deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
         materialized: z.ZodOptional<z.ZodObject<{
             table: z.ZodString;
             compute: z.ZodString;
@@ -1213,8 +1215,8 @@ declare const localDefinitionSchema: z.ZodObject<{
                 name: z.ZodString;
                 kind: z.ZodEnum<{
                     manual: "manual";
-                    prefetch: "prefetch";
                     etl: "etl";
+                    prefetch: "prefetch";
                 }>;
                 table: z.ZodString;
                 columns: z.ZodArray<z.ZodString>;
@@ -1265,6 +1267,7 @@ declare const localDefinitionSchema: z.ZodObject<{
                 orderBy: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
             deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
             materialized: z.ZodOptional<z.ZodObject<{
                 table: z.ZodString;
                 compute: z.ZodString;
@@ -1602,8 +1605,8 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                 name: z.ZodString;
                 kind: z.ZodEnum<{
                     manual: "manual";
-                    prefetch: "prefetch";
                     etl: "etl";
+                    prefetch: "prefetch";
                 }>;
                 table: z.ZodString;
                 columns: z.ZodArray<z.ZodString>;
@@ -1654,6 +1657,7 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                 orderBy: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
             deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
             materialized: z.ZodOptional<z.ZodObject<{
                 table: z.ZodString;
                 compute: z.ZodString;
@@ -1990,8 +1994,8 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                     name: z.ZodString;
                     kind: z.ZodEnum<{
                         manual: "manual";
-                        prefetch: "prefetch";
                         etl: "etl";
+                        prefetch: "prefetch";
                     }>;
                     table: z.ZodString;
                     columns: z.ZodArray<z.ZodString>;
@@ -2042,6 +2046,7 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                     orderBy: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>>;
                 deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 materialized: z.ZodOptional<z.ZodObject<{
                     table: z.ZodString;
                     compute: z.ZodString;

package/dist/canonical.d.ts

@@ -103,8 +103,8 @@ declare const canonicalResolvedSourceSchema: z.ZodObject<{
     name: z.ZodString;
     kind: z.ZodEnum<{
         manual: "manual";
-        prefetch: "prefetch";
         etl: "etl";
+        prefetch: "prefetch";
     }>;
     table: z.ZodString;
     columns: z.ZodArray<z.ZodString>;
@@ -161,8 +161,8 @@ declare const canonicalResolvedSchema: z.ZodObject<{
         name: z.ZodString;
         kind: z.ZodEnum<{
             manual: "manual";
-            prefetch: "prefetch";
             etl: "etl";
+            prefetch: "prefetch";
         }>;
         table: z.ZodString;
         columns: z.ZodArray<z.ZodString>;
@@ -213,6 +213,7 @@ declare const canonicalResolvedSchema: z.ZodObject<{
         orderBy: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
     materialized: z.ZodOptional<z.ZodObject<{
         table: z.ZodString;
         compute: z.ZodString;
@@ -302,7 +303,7 @@ declare function validateResolvedView({ view, tables, views }: {
  * server-side), and the SDL generator / GraphQL compiler / migration engine
  * all consume it.
  *
- * FROZEN CONTRACT (week 1): downstream tracks build against these shapes.
+ * FROZEN CONTRACT: downstream consumers build against these shapes.
  * Additive evolution only; `definition_format` discriminates on the wire.
  */
 
@@ -807,8 +808,8 @@ declare const canonicalViewSchema: z.ZodObject<{
             name: z.ZodString;
             kind: z.ZodEnum<{
                 manual: "manual";
-                prefetch: "prefetch";
                 etl: "etl";
+                prefetch: "prefetch";
             }>;
             table: z.ZodString;
             columns: z.ZodArray<z.ZodString>;
@@ -859,6 +860,7 @@ declare const canonicalViewSchema: z.ZodObject<{
             orderBy: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
         deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
         materialized: z.ZodOptional<z.ZodObject<{
             table: z.ZodString;
             compute: z.ZodString;
@@ -1213,8 +1215,8 @@ declare const localDefinitionSchema: z.ZodObject<{
                 name: z.ZodString;
                 kind: z.ZodEnum<{
                     manual: "manual";
-                    prefetch: "prefetch";
                     etl: "etl";
+                    prefetch: "prefetch";
                 }>;
                 table: z.ZodString;
                 columns: z.ZodArray<z.ZodString>;
@@ -1265,6 +1267,7 @@ declare const localDefinitionSchema: z.ZodObject<{
                 orderBy: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
             deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
             materialized: z.ZodOptional<z.ZodObject<{
                 table: z.ZodString;
                 compute: z.ZodString;
@@ -1602,8 +1605,8 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                 name: z.ZodString;
                 kind: z.ZodEnum<{
                     manual: "manual";
-                    prefetch: "prefetch";
                     etl: "etl";
+                    prefetch: "prefetch";
                 }>;
                 table: z.ZodString;
                 columns: z.ZodArray<z.ZodString>;
@@ -1654,6 +1657,7 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                 orderBy: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
             deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
             materialized: z.ZodOptional<z.ZodObject<{
                 table: z.ZodString;
                 compute: z.ZodString;
@@ -1990,8 +1994,8 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                     name: z.ZodString;
                     kind: z.ZodEnum<{
                         manual: "manual";
-                        prefetch: "prefetch";
                         etl: "etl";
+                        prefetch: "prefetch";
                     }>;
                     table: z.ZodString;
                     columns: z.ZodArray<z.ZodString>;
@@ -2042,6 +2046,7 @@ declare const canonicalDefinitionSchema: z.ZodObject<{
                     orderBy: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>>;
                 deletedBy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                existsIn: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 materialized: z.ZodOptional<z.ZodObject<{
                     table: z.ZodString;
                     compute: z.ZodString;

package/dist/canonical.js

@@ -252,6 +252,48 @@ var policyExpressionSchema = z.union([
     variants: 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((name) => expected.includes(name));
+}
+function validateRowIdentity(input) {
+  validateExistsIn(input);
+  if (input.keys.length > 1) validateCompositeKey(input);
+}
+function validateExistsIn({ resolved, sourceByName, fail }) {
+  const name = resolved.existsIn?.[0];
+  if (name === void 0) return;
+  if (sourceByName.get(name)?.kind !== "etl") fail(`existsIn '${name}' must be an etl source`);
+  if (resolved.policies.insert !== void 0 || resolved.policies.write !== void 0) {
+    fail("existsIn allows only an update policy: rows come from the etl source");
+  }
+}
+function validateCompositeKey({ resolved, keys, tableByName, fail }) {
+  const keyList = `(${keys.join(", ")})`;
+  if (resolved.existsIn === void 0) {
+    fail(`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) fail(`composite key ${keyList} requires a read-only table: remove the ${writes.join("/")} policy`);
+  if (resolved.materialized) fail(`composite key ${keyList} cannot be materialized`);
+  for (const source of resolved.sources) {
+    if (source.kind === "prefetch") {
+      fail(`composite key ${keyList} cannot have prefetch source '${source.name}'`);
+      continue;
+    }
+    const table = tableByName.get(source.table);
+    if (table && !sameKey(logicalKey(table), keys)) {
+      fail(`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);
@@ -329,6 +371,13 @@ var canonicalResolvedSchema = z.object({
   resolve: z.array(canonicalResolveRuleSchema).max(500),
   /** Sources whose tombstone hides the resolved row (v1: the manual source only). */
   deletedBy: 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: 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
@@ -347,8 +396,8 @@ function validateResolvedView({ view, tables, views = [] }) {
   if (!resolved) return [];
   const errors = [];
   const fail = (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) {
     fail("requires exactly one primary-key column");
     return errors;
   }
@@ -356,7 +405,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
@@ -370,6 +419,7 @@ function validateResolvedView({ view, tables, views = [] }) {
     if (!table) fail(`source '${source.name}' references unknown table '${source.table}'`);
     else validateSource({ scope, source, table });
   }
+  validateRowIdentity({ resolved, keys: [...scope.keys.keys()], sourceByName: scope.sourceByName, tableByName, fail });
   validateRules(scope);
   validateViewCells(scope);
   if (resolved.materialized) validateMaterialized({ scope, tableByName, views });
@@ -399,7 +449,7 @@ function validateSource({ scope, source, table }) {
   validatePrefetchFields({ scope, source });
 }
 function validatePrefetchFields({ scope, source }) {
-  const { fail, pkColumn } = scope;
+  const { fail, keys } = scope;
   if (source.kind !== "prefetch") {
     if (source.key || source.fetch || source.function || source.prefetchDefaults || source.writeback) {
       fail(`only prefetch sources may declare key/fetch/function/prefetchDefaults/writeback ('${source.name}')`);
@@ -408,7 +458,7 @@ function validatePrefetchFields({ scope, source }) {
   }
   if (!source.key || !source.fetch || !source.function || !source.prefetchDefaults) {
     fail(`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)) {
     fail(`prefetch source '${source.name}' key '${source.key}' must be the primary key or one of its columns`);
   }
   for (const column of source.writeback?.columns ?? []) {
@@ -416,19 +466,19 @@ function validatePrefetchFields({ scope, source }) {
   }
 }
 function validateSourceColumns({ scope, source, byName }) {
-  const { fail, pkColumn, dataColumns } = scope;
-  for (const column of [pkColumn.name, ...source.columns]) {
-    const own = column === pkColumn.name ? pkColumn : dataColumns.get(column);
+  const { fail, 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) fail(`source '${source.name}' supplies unknown column '${column}'`);
     else if (!theirs) fail(`source '${source.name}' table '${source.table}' has no column '${column}'`);
     else if (JSON.stringify(theirs.type) !== JSON.stringify(own.type)) fail(`column '${column}' has a different type on source '${source.name}'`);
   }
 }
-function validateRules({ resolved, pkColumn, dataColumns, sourceByName, fail }) {
+function validateRules({ resolved, keys, dataColumns, sourceByName, fail }) {
   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)) {
       fail(`resolve rule targets unknown column '${rule.column}'`);
       continue;
     }
@@ -445,7 +495,7 @@ function validateRules({ resolved, pkColumn, dataColumns, sourceByName, fail })
     }
   }
   for (const column of dataColumns.keys()) {
-    if (column !== pkColumn.name && !ruled.has(column)) fail(`column '${column}' has no resolve rule`);
+    if (!keys.has(column) && !ruled.has(column)) fail(`column '${column}' has no resolve rule`);
   }
 }
 var VIEW_CELL_TYPES = {
@@ -454,10 +504,10 @@ var VIEW_CELL_TYPES = {
   by: "text",
   conflicts: "jsonb"
 };
-function validateViewCells({ view, dataColumns, pkColumn, fail }) {
+function validateViewCells({ view, dataColumns, keys, fail }) {
   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) });
     }
@@ -825,7 +875,7 @@ var canonicalTableSchema = z.object({
   table: identifier2,
   displayName: z.string().trim().min(1).max(120).optional(),
   description: z.string().max(2e3).optional(),
-  /** Table-level rename hint (new in v2). */
+  /** Table-level rename hint. */
   renamedFrom: identifier2.optional(),
   /** Synced/reflected read-only tables (`source: schema.table`) — v1 semantics. */
   source: z.string().regex(QUALIFIED_TABLE_PATTERN).optional(),