@sequenceholdings/orm 2.0.0 → 2.1.0

package/README.md

@@ -5,12 +5,18 @@ namespaces. You define tables, policies, and named GraphQL operations in source
 control; the platform compiles them into persisted operations and enforces the
 caller's access on every execution.
 
+Sequence ORM is a workflow-agnostic platform primitive. The compiler and
+runtime own generic schema, policy, migration, and execution contracts;
+deployed namespaces own domain tables and operations. Primitive code must not
+branch on a namespace or product identity. See
+[Platform primitive boundaries](../../../docs/platform/platform-primitives.md).
+
 ## Install
 
 Install the CLI and SDK together:
 
 ```bash
-pnpm add -g @sequenceholdings/studio-cli@0.1.27 @sequenceholdings/orm@2.0.0
+pnpm add -g @sequenceholdings/studio-cli@0.1.35 @sequenceholdings/orm@2.1.0
 ```
 
 Create a namespace project:
@@ -32,7 +38,12 @@ seq-studio orm apply . -e <environment-name>
 ```
 
 `generate` writes `schema.graphql`, `operations.manifest.json`, cache policies,
-and typed consumer modules. Commit generated outputs and migrations with the
+and typed consumer modules. Generated SDL may contain up to 16 MiB of UTF-8
+text for the complete namespace; individual authored files retain a 1 MiB cap.
+Registration and reviewed migration exports are bounded to 64 MiB including
+canonical metadata, snapshots, documents, and migration statements.
+
+Commit generated outputs and migrations with the
 source that produced them.
 
 Use `apply --dry-run` to rehearse a migration against a disposable copy of the
@@ -41,6 +52,46 @@ namespace, which is useful for deployment checks.
 
 ## Execute persisted operations
 
+### Guard dependent writes
+
+Mutation roots run in one transaction. To require a conditional write to
+succeed before committing dependent roots, add a fixed row-count assertion:
+
+```graphql
+mutation SaveDeal($id: uuid!, $revision: Int!, $title: String!) {
+  updateDeals(
+    where: { id: { _eq: $id }, revision: { _eq: $revision } }
+    _set: { title: $title }
+    _inc: { revision: 1 }
+  ) @assertAffectedRows(exactly: 1) {
+    returning { id revision }
+  }
+}
+```
+
+This example assumes a `deals` table with `id`, `title`, and integer `revision`
+columns and suitable write policies. The assertion uses the actual SQL write
+count even when `affectedRows` is not selected. A mismatch rolls back **all**
+roots and the operation journal with HTTP 409 `MUTATION_PRECONDITION_FAILED`.
+Missing, policy-hidden, and stale matches receive the same generic error.
+Ordinary mutations without this directive keep zero-match success semantics.
+
+`exactly` must be a literal integer from 0 through 2147483647. It cannot be a
+caller variable. Only mutation root fields may carry the directive, and a
+guarded root cannot also use `@include` or `@skip`. Policy and constraint
+failures retain their existing errors. This does not add automatic retries:
+when the domain permits retry, reread authorized state and recompute the write.
+Every writer affecting the invariant must participate in the revision protocol.
+
+Guarded operations use **IR v2**; older runtimes reject them. Upgrade the host
+compiler and executor together before registering guarded documents, regenerate
+SDL with the matching SDK, and only then activate consumers. Existing unguarded
+operations keep their IR v1 and operation hashes. This source addition requires
+a matching SDK release and host rollout; it is not a claim that the published
+Preview version already supports it.
+
+### Execute by name
+
 Operations execute by their generated manifest name, never by sending GraphQL
 text or SQL:
 
@@ -53,6 +104,10 @@ seq-studio orm execute GetOpenDeals . \
 `variables.json` must contain a JSON object. The platform validates variables,
 operation requirements, and row policies as the signed-in caller.
 
+Execute uses the `/_data/v2` endpoint by default. Set
+`SEQUENCE_ORM_ATLAS_EXECUTE_V2=1` to opt into Atlas's `/api/data/v2` endpoint.
+This client rollout switch does not bypass server feature flags or authorization.
+
 ## Public exports
 
 - `@sequenceholdings/orm/authoring` — namespace, table, policy, and view DSL

package/dist/authoring.cjs

@@ -33,6 +33,7 @@ var ColumnBuilder = class {
       hasDefault: false,
       defaultValue: void 0,
       defaultFn: void 0,
+      onUpdateFn: void 0,
       description: void 0,
       renamedFrom: void 0,
       cast: void 0,
@@ -68,6 +69,15 @@ var ColumnBuilder = class {
     this.state.defaultFn = void 0;
     return this;
   }
+  /**
+   * Stamp this column with Postgres `now()` on every UPDATE. Only valid on
+   * timestamptz/date; the compiler drops it from SetInput so callers cannot
+   * supply a value.
+   */
+  onUpdate(value) {
+    this.state.onUpdateFn = value;
+    return this;
+  }
   description(text2) {
     this.state.description = text2;
     return this;
@@ -111,6 +121,7 @@ var ColumnBuilder = class {
     };
     if (this.state.hasDefault) column.default = this.state.defaultValue ?? null;
     if (this.state.defaultFn !== void 0) column.defaultFn = this.state.defaultFn;
+    if (this.state.onUpdateFn !== void 0) column.onUpdateFn = this.state.onUpdateFn;
     if (this.state.description !== void 0) column.description = this.state.description;
     if (this.state.renamedFrom !== void 0) column.renamedFrom = this.state.renamedFrom;
     if (this.state.cast !== void 0) column.cast = this.state.cast;
@@ -138,6 +149,7 @@ var t = {
 // src/constants.ts
 var NAMESPACE_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;
 var IDENTIFIER_PATTERN = /^[a-z][a-z0-9_]*$/;
+var COLUMN_IDENTIFIER_PATTERN = /^_?[a-z][a-z0-9_]*$/;
 var MAX_IDENTIFIER_LENGTH = 63;
 var SYNCED_SOURCE_PATTERN = /^gold\.[a-z][a-z0-9_]*$/;
 var HASH_DOMAIN = "sequence-orm-definitions\0";
@@ -240,10 +252,10 @@ function isSeqLink(value) {
 function isSeqTable(value) {
   return typeof value === "object" && value !== null && value.kind === TABLE_BRAND;
 }
-function assertIdentifier({ value, what, file }) {
-  if (!IDENTIFIER_PATTERN.test(value) || value.length > MAX_IDENTIFIER_LENGTH) {
+function assertIdentifier({ value, what, file, pattern = IDENTIFIER_PATTERN }) {
+  if (!pattern.test(value) || value.length > MAX_IDENTIFIER_LENGTH) {
     throw new OrmDefinitionError(
-      `${what} "${value}" must match ${IDENTIFIER_PATTERN} and be at most ${MAX_IDENTIFIER_LENGTH} characters`,
+      `${what} "${value}" must match ${pattern} and be at most ${MAX_IDENTIFIER_LENGTH} characters`,
       file
     );
   }
@@ -264,7 +276,7 @@ function defineTable(name, columns, config = {}) {
       );
     }
     const columnName = builder.columnNameFor(propertyName);
-    assertIdentifier({ value: columnName, what: `table "${name}": column "${propertyName}" column name`, file });
+    assertIdentifier({ value: columnName, what: `table "${name}": column "${propertyName}" column name`, file, pattern: COLUMN_IDENTIFIER_PATTERN });
     const existing = seenColumnNames.get(columnName);
     if (existing !== void 0) {
       throw new OrmDefinitionError(
@@ -304,7 +316,8 @@ function defineSyncedTable(name, columnsOrConfig, maybeConfig) {
     assertIdentifier({
       value: columnName,
       what: `synced table "${name}": column "${propertyName}" column name`,
-      file
+      file,
+      pattern: COLUMN_IDENTIFIER_PATTERN
     });
     const existing = seenColumnNames.get(columnName);
     if (existing !== void 0) {
@@ -393,7 +406,7 @@ function defineView(name, columns, config) {
       );
     }
     const columnName = builder.columnNameFor(propertyName);
-    if (!IDENTIFIER_PATTERN.test(columnName) || columnName.length > MAX_IDENTIFIER_LENGTH) {
+    if (!COLUMN_IDENTIFIER_PATTERN.test(columnName) || columnName.length > MAX_IDENTIFIER_LENGTH) {
       throw new OrmDefinitionError(`view "${name}": column "${propertyName}" has invalid column name "${columnName}"`, file);
     }
     const existing = seenColumnNames.get(columnName);
@@ -842,6 +855,7 @@ function scalarColumnType(table, property, helper) {
 var CANONICAL_FORMAT = 2;
 var IDENTIFIER_RE = /^[a-z][a-z0-9_]*$/;
 var identifier = zod.z.string().min(1).max(63).regex(IDENTIFIER_RE);
+var columnIdentifier = zod.z.string().min(1).max(63).regex(COLUMN_IDENTIFIER_PATTERN);
 var COLUMN_TYPES = [
   "uuid",
   "text",
@@ -862,18 +876,33 @@ var canonicalEnumSchema = zod.z.object({
 var canonicalColumnSchema = zod.z.object({
   /** Property name in TS (camelCase); columnName is the Postgres name. */
   name: zod.z.string().min(1).max(63),
-  columnName: identifier,
+  columnName: columnIdentifier,
   type: zod.z.union([columnTypeSchema, zod.z.object({ enum: identifier })]),
   nullable: zod.z.boolean().default(true),
   unique: zod.z.boolean().default(false),
   /** Literal default, or one of the allowlisted SQL functions. */
   default: zod.z.union([zod.z.string(), zod.z.number(), zod.z.boolean(), zod.z.null()]).optional(),
   defaultFn: zod.z.enum(["gen_random_uuid()", "now()"]).optional(),
+  /**
+   * Stamp this column from the database clock on UPDATE (`now()`). The
+   * column stays insertable (defaults fill gaps) but is omitted from
+   * SetInput / settable so callers cannot backdate it.
+   */
+  onUpdateFn: zod.z.enum(["now()"]).optional(),
   description: zod.z.string().max(500).optional(),
   /** Migration hints — same semantics as v1. */
-  renamedFrom: identifier.optional(),
+  renamedFrom: columnIdentifier.optional(),
   cast: zod.z.string().max(200).optional(),
   deprecated: zod.z.boolean().default(false)
+}).superRefine((column, ctx) => {
+  if (column.onUpdateFn === void 0) return;
+  if (typeof column.type !== "string" || column.type !== "timestamptz" && column.type !== "date") {
+    ctx.addIssue({
+      code: "custom",
+      path: ["onUpdateFn"],
+      message: `onUpdateFn '${column.onUpdateFn}' is only valid on timestamptz/date columns`
+    });
+  }
 });
 var canonicalLinkSchema = zod.z.object({
   name: zod.z.string().min(1).max(63),
@@ -881,15 +910,15 @@ var canonicalLinkSchema = zod.z.object({
   /** Target table name (namespace-local). Absent for toPlatformUser. */
   target: identifier.optional(),
   /** FK column on the owning side (toOne/toPlatformUser: on this table; toMany: on the target). */
-  on: identifier,
+  on: columnIdentifier,
   /** Referenced column on the target (default: target's PK / platform user `sub`). */
-  references: identifier.optional(),
+  references: columnIdentifier.optional(),
   /** enforce: true emits a real FK constraint (same-namespace toOne only). */
   enforce: zod.z.boolean().default(false),
   description: zod.z.string().max(500).optional()
 });
 var canonicalIndexSchema = zod.z.object({
-  columns: zod.z.array(identifier).min(1),
+  columns: zod.z.array(columnIdentifier).min(1),
   unique: zod.z.boolean().default(false),
   name: identifier.optional()
 });
@@ -980,6 +1009,13 @@ var canonicalCowMutationSchema = zod.z.object({
     }
   }
 });
+var canonicalForeignKeySchema = zod.z.object({
+  name: identifier,
+  columns: zod.z.array(columnIdentifier).min(1).max(8),
+  target: identifier,
+  references: zod.z.array(columnIdentifier).min(1).max(8),
+  deferrable: zod.z.enum(["initially-immediate", "initially-deferred"]).optional()
+}).strict();
 var canonicalTableSchema = zod.z.object({
   table: identifier,
   description: zod.z.string().max(2e3).optional(),
@@ -988,7 +1024,7 @@ var canonicalTableSchema = zod.z.object({
   /** Synced/reflected read-only tables (`source: gold.*`) — v1 semantics. */
   source: zod.z.string().regex(/^gold\.[a-z][a-z0-9_]*$/).optional(),
   columns: zod.z.array(canonicalColumnSchema).default([]),
-  primaryKey: zod.z.array(identifier).min(1).max(8).optional(),
+  primaryKey: zod.z.array(columnIdentifier).min(1).max(8).optional(),
   links: zod.z.array(canonicalLinkSchema).default([]),
   indexes: zod.z.array(canonicalIndexSchema).default([]),
   policies: canonicalPoliciesSchema.default({}),
@@ -999,14 +1035,16 @@ var canonicalTableSchema = zod.z.object({
    */
   actions: zod.z.array(canonicalActionSchema).default([]),
   /** Optional (not defaulted) so pre-CoW canonical documents keep byte-identical hashes. */
-  cowMutations: zod.z.array(canonicalCowMutationSchema).optional()
+  cowMutations: zod.z.array(canonicalCowMutationSchema).optional(),
+  /** Omitted by old definitions, preserving their existing content hashes. */
+  foreignKeys: zod.z.array(canonicalForeignKeySchema).max(100).optional()
 });
 var canonicalViewSchema = zod.z.object({
   view: identifier,
   description: zod.z.string().max(2e3).optional(),
   columns: zod.z.array(canonicalColumnSchema).min(1),
   /** Logical identity for GraphQL only; PostgreSQL views have no PK constraint. */
-  primaryKey: zod.z.array(identifier).min(1).max(8).optional(),
+  primaryKey: zod.z.array(columnIdentifier).min(1).max(8).optional(),
   links: zod.z.array(canonicalLinkSchema).default([]),
   policies: zod.z.object({ read: policyExpressionSchema }).strict(),
   query: zod.z.string().min(1).max(1e5).refine(isSingleViewQuerySql, {
@@ -1019,6 +1057,9 @@ var canonicalViewSchema = zod.z.object({
     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.onUpdateFn !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare onUpdateFn` });
+    }
     if (column.unique) {
       ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare unique` });
     }
@@ -1052,6 +1093,45 @@ var canonicalDefinitionSchema = zod.z.object({
       ctx.addIssue({ code: "custom", path: ["tables", index, "table"], message: `duplicate relation '${table.table}'` });
     }
     seen.add(table.table);
+    if (table.source !== void 0) {
+      for (const [columnIndex, column] of table.columns.entries()) {
+        if (column.onUpdateFn !== void 0) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["tables", index, "columns", columnIndex],
+            message: `synced table '${table.table}' column '${column.name}' cannot declare onUpdateFn`
+          });
+        }
+      }
+    }
+  }
+  const fkTables = new Map(definition.tables.map((table) => [table.table, table]));
+  for (const [tableIndex, table] of definition.tables.entries()) {
+    const names = /* @__PURE__ */ new Set([
+      ...table.primaryKey?.length ? [`${table.table}_pkey`] : [],
+      ...table.columns.filter((column) => column.unique && !(table.primaryKey?.length === 1 && table.primaryKey[0] === column.columnName)).map((column) => `${table.table}_${column.columnName}_unique`),
+      ...table.links.filter((link) => link.enforce).map((link) => `fk_${table.table}_${link.name}`)
+    ]);
+    for (const [index, fk] of (table.foreignKeys ?? []).entries()) {
+      const fail = (message) => ctx.addIssue({ code: "custom", path: ["tables", tableIndex, "foreignKeys", index], message });
+      if (names.has(fk.name)) fail(`duplicate foreign key '${fk.name}'`);
+      names.add(fk.name);
+      const target = fkTables.get(fk.target);
+      if (table.source || !target || target.source) {
+        fail("foreign keys must connect owned tables in the same namespace");
+        continue;
+      }
+      if (fk.columns.length !== fk.references.length) fail("foreign key columns and references must have the same number of columns");
+      if (new Set(fk.columns).size !== fk.columns.length || new Set(fk.references).size !== fk.references.length) fail("foreign key columns must not repeat");
+      for (const [position, name] of fk.columns.entries()) {
+        const sourceColumn = table.columns.find((column) => column.columnName === name);
+        const targetColumn = target.columns.find((column) => column.columnName === fk.references[position]);
+        if (!sourceColumn || !targetColumn) fail("foreign key references an unknown column");
+        else if (JSON.stringify(sourceColumn.type) !== JSON.stringify(targetColumn.type)) fail("foreign key column types must match");
+      }
+      const uniqueKeys = [target.primaryKey ?? [], ...target.indexes.filter((index2) => index2.unique).map((index2) => index2.columns), ...target.columns.filter((column) => column.unique).map((column) => [column.columnName])];
+      if (!uniqueKeys.some((key) => key.length === fk.references.length && key.every((column) => fk.references.includes(column)))) fail("foreign key target columns must form a unique key");
+    }
   }
   const tableByName = new Map(definition.tables.map((table) => [table.table, table]));
   for (const [tableIndex, table] of definition.tables.entries()) {
@@ -1174,12 +1254,13 @@ function normalizeCanonical(definition) {
     ...definition,
     enums: sortByName(definition.enums),
     tables: [...definition.tables].sort((a, b) => a.table.localeCompare(b.table)).map((t2) => {
-      const { cowMutations, ...rest } = t2;
+      const { cowMutations, foreignKeys, ...rest } = t2;
       return {
         ...rest,
         links: sortByName(t2.links),
         indexes: [...t2.indexes].sort((a, b) => (a.name ?? a.columns.join("_")).localeCompare(b.name ?? b.columns.join("_"))),
         actions: sortByName(t2.actions),
+        ...foreignKeys?.length ? { foreignKeys: sortByName(foreignKeys) } : {},
         // Omitted entirely when absent/empty so pre-CoW documents hash unchanged.
         ...cowMutations !== void 0 && cowMutations.length > 0 ? { cowMutations: sortByName(cowMutations) } : {}
       };
@@ -1375,6 +1456,22 @@ function buildCanonicalTable({ table, relationsByName, enumsByName }) {
   } else if (columnLevelPk.length > 0) {
     candidate.primaryKey = columnLevelPk;
   }
+  if (table.config.foreignKeys?.length) {
+    if (table.source) throw new OrmDefinitionError(`synced table "${table.tableName}" cannot enforce foreign keys`, table.file);
+    candidate.foreignKeys = table.config.foreignKeys.map((fk) => {
+      const target = resolveRelationRef({ ref: fk.target, fail: (message) => {
+        throw new OrmDefinitionError(message, table.file);
+      } });
+      if (!isSeqTable(target) || !relationsByName.has(target.tableName)) throw new OrmDefinitionError("foreign key target must be a table in this namespace", table.file);
+      return {
+        name: fk.name,
+        columns: fk.columns.map((ref) => resolveColumnRef({ relation: table, ref, role: `foreign key "${fk.name}" column` })),
+        target: target.tableName,
+        references: fk.references.map((ref) => resolveColumnRef({ relation: target, ref, role: `foreign key "${fk.name}" reference` })),
+        ...fk.deferrable ? { deferrable: fk.deferrable } : {}
+      };
+    });
+  }
   for (const index of table.config.indexes ?? []) {
     const entry = {
       columns: index.columns.map((ref) => resolveColumnRef({ relation: table, ref, role: "index" }))
@@ -1427,6 +1524,12 @@ function buildCanonicalView({
     if (column.default !== void 0 || column.defaultFn !== void 0) {
       throw new OrmDefinitionError(`view "${view.viewName}": column "${propertyName}" cannot declare a default`, view.file);
     }
+    if (column.onUpdateFn !== void 0) {
+      throw new OrmDefinitionError(
+        `view "${view.viewName}": column "${propertyName}" cannot declare onUpdateFn`,
+        view.file
+      );
+    }
     if (column.unique) {
       throw new OrmDefinitionError(`view "${view.viewName}": column "${propertyName}" cannot declare unique`, view.file);
     }
@@ -1687,6 +1790,10 @@ async function loadNamespaceFromDir(dir, options = {}) {
     fsCache: false,
     ...options.ormModulePath !== void 0 ? {
       alias: {
+        // The public /drizzle barrel re-exports this pinned dependency.
+        // Explicitly map it before the root alias: otherwise jiti appends
+        // "/drizzle" to the overridden module's filename.
+        "@sequenceholdings/orm/drizzle": module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('authoring.cjs', document.baseURI).href))).resolve("drizzle-orm"),
         "@sequenceholdings/orm": options.ormModulePath,
         "@sequenceholdings/orm/authoring": options.ormModulePath
       }