@sequenceholdings/orm 2.8.4 → 2.9.0

package/dist/cli.d.cts

@@ -1,6 +1,15 @@
 /** Set by the seq-studio delegate; direct users export them. */
 declare const BASE_URL_ENV = "SEQUENCE_ORM_BASE_URL";
 declare const TOKEN_ENV = "SEQUENCE_ORM_TOKEN";
+/** JSON `{repository_id, commit, path, dirty?}` naming the Git Service source of this apply; set by the seq-studio delegate. */
+declare const SOURCE_ENV = "SEQUENCE_ORM_SOURCE";
+/** Namespace-admin override reason for an apply whose source does not verify; set by `seq-studio orm apply --unverified-source`. */
+declare const UNVERIFIED_SOURCE_REASON_ENV = "SEQUENCE_ORM_UNVERIFIED_SOURCE_REASON";
+/** The apply body's `source` claim, when the delegate supplied one. Atlas verifies it; it never authorizes anything. */
+declare function applySourceFromEnv(env?: NodeJS.ProcessEnv): {
+    source?: Record<string, unknown>;
+    unverified_source_reason?: string;
+};
 /**
  * Test/dev hook mirroring `LoadNamespaceOptions.ormModulePath`: when set, bare
  * `'@sequenceholdings/orm'` imports in consumer files resolve to this path
@@ -12,6 +21,8 @@ type TokenProvider = () => Promise<string | null>;
 /** Hand the CLI a refreshing token source (used by the seq-studio delegate). */
 declare function setTokenProvider(provider: TokenProvider): void;
 declare function runCli(argv: readonly string[]): Promise<number>;
+/** Where the live version came from: `live since <time> from <commit> on <branch> at <path> by <actor>`. */
+declare function describeActivation(activation: RegistryActivation): string;
 interface ApplyWait {
     wait: boolean;
     timeoutMs: number;
@@ -24,5 +35,16 @@ declare function parseApplyWait(rest: readonly string[]): ApplyWait;
  * details name the variable, column, constraint, or requirement at fault.
  */
 declare function errorDetail(payload: unknown): string | null;
+/** One row of the namespace's activation history, as the detail route returns it (absent on older Atlas). */
+interface RegistryActivation {
+    id: string;
+    provenance_class: string;
+    source_commit: string | null;
+    source_branch: string | null;
+    source_path: string | null;
+    reported_source: Record<string, unknown> | null;
+    actor_sub: string;
+    activated_at: string;
+}
 
-export { BASE_URL_ENV, ORM_MODULE_PATH_ENV, TOKEN_ENV, errorDetail, parseApplyWait, runCli, setTokenProvider };
+export { BASE_URL_ENV, ORM_MODULE_PATH_ENV, type RegistryActivation, SOURCE_ENV, TOKEN_ENV, UNVERIFIED_SOURCE_REASON_ENV, applySourceFromEnv, describeActivation, errorDetail, parseApplyWait, runCli, setTokenProvider };

package/dist/cli.d.ts

@@ -1,6 +1,15 @@
 /** Set by the seq-studio delegate; direct users export them. */
 declare const BASE_URL_ENV = "SEQUENCE_ORM_BASE_URL";
 declare const TOKEN_ENV = "SEQUENCE_ORM_TOKEN";
+/** JSON `{repository_id, commit, path, dirty?}` naming the Git Service source of this apply; set by the seq-studio delegate. */
+declare const SOURCE_ENV = "SEQUENCE_ORM_SOURCE";
+/** Namespace-admin override reason for an apply whose source does not verify; set by `seq-studio orm apply --unverified-source`. */
+declare const UNVERIFIED_SOURCE_REASON_ENV = "SEQUENCE_ORM_UNVERIFIED_SOURCE_REASON";
+/** The apply body's `source` claim, when the delegate supplied one. Atlas verifies it; it never authorizes anything. */
+declare function applySourceFromEnv(env?: NodeJS.ProcessEnv): {
+    source?: Record<string, unknown>;
+    unverified_source_reason?: string;
+};
 /**
  * Test/dev hook mirroring `LoadNamespaceOptions.ormModulePath`: when set, bare
  * `'@sequenceholdings/orm'` imports in consumer files resolve to this path
@@ -12,6 +21,8 @@ type TokenProvider = () => Promise<string | null>;
 /** Hand the CLI a refreshing token source (used by the seq-studio delegate). */
 declare function setTokenProvider(provider: TokenProvider): void;
 declare function runCli(argv: readonly string[]): Promise<number>;
+/** Where the live version came from: `live since <time> from <commit> on <branch> at <path> by <actor>`. */
+declare function describeActivation(activation: RegistryActivation): string;
 interface ApplyWait {
     wait: boolean;
     timeoutMs: number;
@@ -24,5 +35,16 @@ declare function parseApplyWait(rest: readonly string[]): ApplyWait;
  * details name the variable, column, constraint, or requirement at fault.
  */
 declare function errorDetail(payload: unknown): string | null;
+/** One row of the namespace's activation history, as the detail route returns it (absent on older Atlas). */
+interface RegistryActivation {
+    id: string;
+    provenance_class: string;
+    source_commit: string | null;
+    source_branch: string | null;
+    source_path: string | null;
+    reported_source: Record<string, unknown> | null;
+    actor_sub: string;
+    activated_at: string;
+}
 
-export { BASE_URL_ENV, ORM_MODULE_PATH_ENV, TOKEN_ENV, errorDetail, parseApplyWait, runCli, setTokenProvider };
+export { BASE_URL_ENV, ORM_MODULE_PATH_ENV, type RegistryActivation, SOURCE_ENV, TOKEN_ENV, UNVERIFIED_SOURCE_REASON_ENV, applySourceFromEnv, describeActivation, errorDetail, parseApplyWait, runCli, setTokenProvider };

package/dist/cli.js

@@ -102,6 +102,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/hash.ts
 function stableJson(value) {
@@ -412,6 +414,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((name2) => expected.includes(name2));
+}
+function validateRowIdentity(input) {
+  validateExistsIn(input);
+  if (input.keys.length > 1) validateCompositeKey(input);
+}
+function validateExistsIn({ resolved, sourceByName, fail: fail4 }) {
+  const name2 = resolved.existsIn?.[0];
+  if (name2 === void 0) return;
+  if (sourceByName.get(name2)?.kind !== "etl") fail4(`existsIn '${name2}' must be an etl source`);
+  if (resolved.policies.insert !== void 0 || resolved.policies.write !== void 0) {
+    fail4("existsIn allows only an update policy: rows come from the etl source");
+  }
+}
+function validateCompositeKey({ resolved, keys, tableByName, fail: fail4 }) {
+  const keyList = `(${keys.join(", ")})`;
+  if (resolved.existsIn === void 0) {
+    fail4(`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) fail4(`composite key ${keyList} requires a read-only table: remove the ${writes.join("/")} policy`);
+  if (resolved.materialized) fail4(`composite key ${keyList} cannot be materialized`);
+  for (const source of resolved.sources) {
+    if (source.kind === "prefetch") {
+      fail4(`composite key ${keyList} cannot have prefetch source '${source.name}'`);
+      continue;
+    }
+    const table = tableByName.get(source.table);
+    if (table && !sameKey(logicalKey(table), keys)) {
+      fail4(`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);
@@ -488,6 +532,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
@@ -506,8 +557,8 @@ function validateResolvedView({ view, tables, views = [] }) {
   if (!resolved) return [];
   const errors = [];
   const fail4 = (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) {
     fail4("requires exactly one primary-key column");
     return errors;
   }
@@ -515,7 +566,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: fail4
@@ -529,6 +580,7 @@ function validateResolvedView({ view, tables, views = [] }) {
     if (!table) fail4(`source '${source.name}' references unknown table '${source.table}'`);
     else validateSource({ scope, source, table });
   }
+  validateRowIdentity({ resolved, keys: [...scope.keys.keys()], sourceByName: scope.sourceByName, tableByName, fail: fail4 });
   validateRules(scope);
   validateViewCells(scope);
   if (resolved.materialized) validateMaterialized({ scope, tableByName, views });
@@ -558,7 +610,7 @@ function validateSource({ scope, source, table }) {
   validatePrefetchFields({ scope, source });
 }
 function validatePrefetchFields({ scope, source }) {
-  const { fail: fail4, pkColumn } = scope;
+  const { fail: fail4, keys } = scope;
   if (source.kind !== "prefetch") {
     if (source.key || source.fetch || source.function || source.prefetchDefaults || source.writeback) {
       fail4(`only prefetch sources may declare key/fetch/function/prefetchDefaults/writeback ('${source.name}')`);
@@ -567,7 +619,7 @@ function validatePrefetchFields({ scope, source }) {
   }
   if (!source.key || !source.fetch || !source.function || !source.prefetchDefaults) {
     fail4(`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)) {
     fail4(`prefetch source '${source.name}' key '${source.key}' must be the primary key or one of its columns`);
   }
   for (const column of source.writeback?.columns ?? []) {
@@ -575,19 +627,19 @@ function validatePrefetchFields({ scope, source }) {
   }
 }
 function validateSourceColumns({ scope, source, byName }) {
-  const { fail: fail4, pkColumn, dataColumns } = scope;
-  for (const column of [pkColumn.name, ...source.columns]) {
-    const own = column === pkColumn.name ? pkColumn : dataColumns.get(column);
+  const { fail: fail4, 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) fail4(`source '${source.name}' supplies unknown column '${column}'`);
     else if (!theirs) fail4(`source '${source.name}' table '${source.table}' has no column '${column}'`);
     else if (JSON.stringify(theirs.type) !== JSON.stringify(own.type)) fail4(`column '${column}' has a different type on source '${source.name}'`);
   }
 }
-function validateRules({ resolved, pkColumn, dataColumns, sourceByName, fail: fail4 }) {
+function validateRules({ resolved, keys, dataColumns, sourceByName, fail: fail4 }) {
   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)) {
       fail4(`resolve rule targets unknown column '${rule.column}'`);
       continue;
     }
@@ -604,7 +656,7 @@ function validateRules({ resolved, pkColumn, dataColumns, sourceByName, fail: fa
     }
   }
   for (const column of dataColumns.keys()) {
-    if (column !== pkColumn.name && !ruled.has(column)) fail4(`column '${column}' has no resolve rule`);
+    if (!keys.has(column) && !ruled.has(column)) fail4(`column '${column}' has no resolve rule`);
   }
 }
 var VIEW_CELL_TYPES = {
@@ -613,10 +665,10 @@ var VIEW_CELL_TYPES = {
   by: "text",
   conflicts: "jsonb"
 };
-function validateViewCells({ view, dataColumns, pkColumn, fail: fail4 }) {
+function validateViewCells({ view, dataColumns, keys, fail: fail4 }) {
   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) });
     }
@@ -1842,8 +1894,13 @@ var resolvedSourceIrSchema = z.object({
   }).optional()
 });
 var resolvedMetaIrSchema = z.object({
-  /** Logical pk column of the resolved view (single-column). */
-  pk: 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: z.string().optional(),
   /** Source name of the manual source. */
   manual: z.string(),
   sources: z.array(resolvedSourceIrSchema),
@@ -3268,7 +3325,7 @@ function buildCompileContext(rawCanonical) {
       appendable: readOnly ? [] : active.filter((c) => c.type === "jsonb").map((c) => c.name),
       ...touchOnUpdate.length > 0 ? { touchOnUpdate } : {},
       ...cells ? { cells } : {},
-      ...resolved ? { resolved: resolvedMeta({ resolved, pk: primaryKey2[0] }) } : {},
+      ...resolved ? { resolved: resolvedMeta({ resolved, primaryKey: primaryKey2 }) } : {},
       constraints: isView ? [] : constraints,
       dynamicFilterMaxDepth: 6,
       dynamicFilterMaxNodes: 64
@@ -3550,10 +3607,10 @@ function resolvedWritable(entries) {
   const system = new Set(Object.values(RESOLVED_VIEW_SYSTEM_COLUMNS).map((column) => column.name));
   return entries.filter((entry) => !entry.deprecated && !system.has(entry.name)).map((entry) => entry.name);
 }
-function resolvedMeta({ resolved, pk }) {
+function resolvedMeta({ resolved, primaryKey: primaryKey2 }) {
   const manual = resolved.sources.find((source) => source.kind === "manual");
   return {
-    pk,
+    ...primaryKey2.length === 1 ? { pk: primaryKey2[0] } : {},
     manual: manual?.name ?? "",
     deletedBy: [...resolved.deletedBy],
     ...resolved.materialized ? { materialized: { ...resolved.materialized } } : {},
@@ -3679,7 +3736,9 @@ function applyPrefetchDirectives({ node, root, meta }) {
     if (directive.maxStaleness !== void 0 && maxStalenessMs === void 0) {
       fail(`@prefetch(maxStaleness: "${directive.maxStaleness}") must look like '500ms', '30s' or '5m'`, "invalid-source-directive");
     }
-    const key = root.kind === "byPk" ? { one: root.pk[0].value } : selectKey({ where: root.where, pk: meta.resolved.pk, source, alias: root.alias });
+    const pk = meta.resolved?.pk;
+    if (pk === void 0) return fail(`@prefetch on '${root.alias}' needs a single-column primary key`, "invalid-source-directive");
+    const key = root.kind === "byPk" ? { one: root.pk[0].value } : selectKey({ where: root.where, pk, source, alias: root.alias });
     return { source: source.name, ...maxStalenessMs !== void 0 ? { maxStalenessMs } : {}, key };
   });
   return { ...root, prefetch: plans };
@@ -6575,6 +6634,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
   };
@@ -10285,6 +10345,42 @@ async function readSnapshot(dir, ordinal) {
   const path = join(dir, MIGRATIONS_DIRNAME, META_DIRNAME, `${pad(ordinal)}.snapshot.json`);
   return parseJson(path, 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 sql4 = await readMigrationSql(dir, entry);
+    if (checksumOf(sql4) !== 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 = join(dir, MIGRATIONS_DIRNAME, META_DIRNAME, `${pad(ordinal)}.snapshot.json`);
+  return readFile(path, "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 = join(dir, MIGRATIONS_DIRNAME, `${entry.name}.sql`);
   return readFile(path, "utf8").catch(() => {
@@ -10445,30 +10541,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 sql4 = await readMigrationSql(dir, entry);
-    if (checksumOf(sql4) !== 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`);
@@ -11347,6 +11423,22 @@ function parseArgs(argv) {
 // src/cli.ts
 var BASE_URL_ENV = "SEQUENCE_ORM_BASE_URL";
 var TOKEN_ENV = "SEQUENCE_ORM_TOKEN";
+var SOURCE_ENV = "SEQUENCE_ORM_SOURCE";
+var UNVERIFIED_SOURCE_REASON_ENV = "SEQUENCE_ORM_UNVERIFIED_SOURCE_REASON";
+function applySourceFromEnv(env = process.env) {
+  const reason = env[UNVERIFIED_SOURCE_REASON_ENV]?.trim();
+  const override = reason ? { unverified_source_reason: reason } : {};
+  const raw = env[SOURCE_ENV];
+  if (!raw) return override;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${SOURCE_ENV} is not valid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error(`${SOURCE_ENV} must be a JSON object`);
+  return { source: Object.fromEntries(Object.entries(parsed)), ...override };
+}
 var ORM_MODULE_PATH_ENV = "SEQUENCE_ORM_MODULE_PATH";
 var USAGE = `usage:
   seq-studio orm init <dir>              scaffold a namespace package (v2: TypeScript schema + persisted operations)
@@ -11664,15 +11756,21 @@ async function generateCommand(rest) {
   await writeGenerateOutputs(dir, compiled.project);
   const { loaded, manifest } = compiled.project;
   console.log(
-    `wrote ${SCHEMA_GRAPHQL_FILE}, ${OPERATIONS_MANIFEST_FILE}, ${TYPE_POLICIES_FILE}, sql-operations.gen.ts, namespace.contract.json (${loaded.canonical.tables.length} table(s), ${loaded.canonical.views?.length ?? 0} view(s), ${Object.keys(manifest.operations).length} operation(s))`
+    `wrote ${SCHEMA_GRAPHQL_FILE}, ${OPERATIONS_MANIFEST_FILE}, ${OPERATION_DOCUMENTS_FILE}, ${TYPE_POLICIES_FILE}, sql-operations.gen.ts, namespace.contract.json (${loaded.canonical.tables.length} table(s), ${loaded.canonical.views?.length ?? 0} view(s), ${Object.keys(manifest.operations).length} operation(s))`
   );
   return runConsumerCodegen(dir);
 }
 async function writeGenerateOutputs(dir, project) {
-  const { loaded, sdl, manifest } = project;
+  const { loaded, sdl, manifest, documents } = project;
   await writeFile(join(dir, SCHEMA_GRAPHQL_FILE), sdl);
   await writeFile(join(dir, "namespace.contract.json"), `${JSON.stringify(loaded.canonical, null, 2)}
 `);
+  const sortedDocuments = [...documents].sort((a, b) => a.path.localeCompare(b.path)).map(({ path, contents }) => ({ path, contents }));
+  await writeFile(
+    join(dir, OPERATION_DOCUMENTS_FILE),
+    `${JSON.stringify({ documentsVersion: OPERATION_DOCUMENTS_VERSION, documents: sortedDocuments }, null, 2)}
+`
+  );
   const operations = Object.entries(manifest.operations).map(([name2, op]) => ({
     name: name2,
     kind: op.kind,
@@ -11878,8 +11976,20 @@ function reportRegistryState(registry) {
   if (match && match.id === registry.activeVersionId) console.log("-- registry: this content is the ACTIVE version");
   else if (match) console.log(`-- registry: registered (status ${match.status}), not active`);
   else console.log(`-- registry: new content (active is ${active ? active.content_hash.slice(0, 12) : "none"})`);
+  if (registry.activeActivation) console.log(`-- registry: ${describeActivation(registry.activeActivation)}`);
   return 0;
 }
+function describeActivation(activation) {
+  const since = `live since ${activation.activated_at.slice(0, 16).replace("T", " ")}Z`;
+  const by = `by ${activation.actor_sub.replace(/^google-apps\|/, "")}`;
+  if (activation.source_commit && activation.source_branch) {
+    const at = activation.source_path ? ` at ${activation.source_path}` : "";
+    return `${since} from ${activation.source_commit.slice(0, 12)} on ${activation.source_branch}${at} (${activation.provenance_class}) ${by}`;
+  }
+  const failure = activation.reported_source?.verification_failure;
+  const why = typeof failure === "string" ? `: ${failure}` : "";
+  return `${since} from an untraced source (${activation.provenance_class}${why}) ${by}`;
+}
 var META_DIRNAME2 = "meta";
 var JOURNAL_FILENAME2 = "journal.json";
 var padOrdinal = (ordinal) => String(ordinal).padStart(4, "0");
@@ -11967,30 +12077,10 @@ async function checkWorkspaceV2({
     log(`no committed migrations for '${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 sql4 = await readMigrationSql(dir, entry);
-    if (checksumOf(sql4) !== 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.hash) {
     log(`definitions changed since ${tip.name} \u2014 run \`seq-studio orm diff\` and commit the new migration`);
@@ -12104,7 +12194,8 @@ async function applyV2Command(rest, dir) {
   const applied = await apiRequestStrict("POST", `/api/orm/namespaces/${namespace}/apply`, {
     version_id: registered.version_id,
     ...allowDestructive ? { allow_destructive: true } : {},
-    ...schemaAlreadyActive && registered.operation_set_id ? { operation_set_id: registered.operation_set_id } : {}
+    ...schemaAlreadyActive && registered.operation_set_id ? { operation_set_id: registered.operation_set_id } : {},
+    ...applySourceFromEnv()
   });
   const live = { namespace, contentHash: registered.content_hash };
   if ("ops_only" in applied) {
@@ -12561,7 +12652,8 @@ async function applyCommand(rest) {
   if (dryRun) return dryRunRehearsal({ namespace, versionId: registered.version_id, contentHash: registered.content_hash });
   const applied = await apiRequestStrict("POST", `/api/orm/namespaces/${namespace}/apply`, {
     version_id: registered.version_id,
-    ...allowDestructive ? { allow_destructive: true } : {}
+    ...allowDestructive ? { allow_destructive: true } : {},
+    ...applySourceFromEnv()
   });
   if ("status" in applied) {
     const verdict = await awaitQueuedApply({ dir, namespace, contentHash: registered.content_hash, runId: applied.run_id, applyWait });
@@ -12741,11 +12833,13 @@ async function apiRequestStrict(method, path, body) {
 }
 async function fetchRegistryState(namespace, contentHash) {
   if (!process.env[BASE_URL_ENV]?.trim() || !await resolveToken()) return { kind: "offline" };
-  const body = await apiRequest("GET", `/api/orm/namespaces/${namespace}?hash=${encodeURIComponent(contentHash)}`, void 0, { allow404: true });
+  const body = await apiRequest("GET", `/api/orm/namespaces/${namespace}?hash=${encodeURIComponent(contentHash)}&activations_limit=1`, void 0, { allow404: true });
   if (!body) return { kind: "missing" };
+  const latest = body.activations?.[0];
   return {
     kind: "found",
     activeVersionId: body.namespace.active_version_id,
+    activeActivation: latest && latest.id === body.namespace.active_activation_id ? latest : null,
     versions: body.versions,
     hashVersion: body.hash_version ?? null
   };
@@ -12760,6 +12854,6 @@ function positional(rest) {
 }
 var firstLine2 = (sql4) => sql4.split("\n")[0] ?? sql4;
 
-export { BASE_URL_ENV, ORM_MODULE_PATH_ENV, TOKEN_ENV, errorDetail, parseApplyWait, runCli, setTokenProvider };
+export { BASE_URL_ENV, ORM_MODULE_PATH_ENV, SOURCE_ENV, TOKEN_ENV, UNVERIFIED_SOURCE_REASON_ENV, applySourceFromEnv, describeActivation, errorDetail, parseApplyWait, runCli, setTokenProvider };
 //# sourceMappingURL=cli.js.map
 //# sourceMappingURL=cli.js.map