@sanoma-ai/workflows 0.1.0 → 0.4.0

package/src/expectations.ts

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import type { Approver } from "./define.ts";
+import type { ApplyReport } from "./apply.ts";
 import type { DriftReport, DriftResult } from "./drift.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { RecordedDecision } from "./policy.ts";
@@ -82,9 +83,13 @@ const words = (d: RecordedDecision) =>
 /** What the policy decided for the calls, each decision once: `allowed and held for finance`. */
 const decisions = (calls: CallRecord[]) => [...new Set(calls.map((r) => words(r.decision)))].join(" and ");
 
-/** True when `who` names the approver: a person by id, or a group by its name. */
-const isApprover = (approver: Approver, who: string) =>
-  typeof approver === "string" ? approver === who : approver.group === who;
+/** True when `who` names the approver: a person by id, or a group by its name; `{ group }` the group alone. */
+const isApprover = (approver: Approver, who: Approver) =>
+  typeof who !== "string"
+    ? typeof approver !== "string" && approver.group === who.group
+    : typeof approver === "string"
+      ? approver === who
+      : approver.group === who;
 
 /** How a drift report found a resource, as words: `clean`, `gone`, `drifted in has_wiki, topics`. */
 const found = (r: DriftResult) =>
@@ -99,7 +104,7 @@ type Unstepped<T> = T extends unknown ? Omit<T, "step"> : never;
  * output, or undefined when the report found the resource as expected.
  */
 function driftDetail(
-  e: Extract<CoreExpectation, { declared: string }>,
+  e: Extract<CoreExpectation, { status: string }>,
   end: Extract<LedgerRecord, { type: "run.finished" }>,
 ): string | undefined {
   const report = end.output as Partial<DriftReport> | null | undefined;
@@ -115,14 +120,38 @@ function driftDetail(
   return `${e.declared} is ${found(resource)}, not ${e.status === "drifted" ? `drifted in ${e.field}` : e.status}`;
 }
 
+/**
+ * Why an apply expectation fails against the report a finished apply run returned as its output:
+ * the resource `created` (a step that created it, done), or `bound` to an object in the lockfile it ended with.
+ */
+function applyDetail(
+  e: Extract<CoreExpectation, { created: true } | { bound: string }>,
+  end: Extract<LedgerRecord, { type: "run.finished" }>,
+): string | undefined {
+  const report = end.output as Partial<ApplyReport> | null | undefined;
+  if (!Array.isArray(report?.results) || !report.lockfile) return "the run's output is not an apply report";
+  if ("bound" in e) {
+    const binding = report.lockfile.bindings[e.declared];
+    if (binding?.id === e.bound) return undefined;
+    return binding ? `${e.declared} is bound to ${binding.id}, not ${e.bound}` : `${e.declared} is not bound`;
+  }
+  const result = report.results.find((r) => r.id === e.declared);
+  // A gone object recreated is bound again; one forgotten is not.
+  const created =
+    result?.status === "done" && (result.action === "create" || (result.action === "gone" && !!result.binding));
+  if (created) return undefined;
+  if (!result) return `apply did nothing with ${e.declared}`;
+  return `apply's ${result.action} of ${e.declared} ${result.status === "failed" ? `failed: ${result.error}` : `was ${result.status}`}`;
+}
+
 /**
  * Why an expectation of the generic steps does not hold against a run's ledger records, or
  * undefined when it does. A call is an `op.called` record without an `error`; one with an error
  * (a policy denial, a rejected approval, a vendor's final failure) was attempted, not made. An
- * operation `was denied` when the policy's decision on some call to it is `deny`, and `was held
- * for` an approver when an approval for that approver holds it: one the policy asked for on its
- * call, or one that `covers` it. A drift expectation reads the report a finished drift run
- * returned. A step named in the workflow's outline is read by the `name` its records carry
+ * operation `was denied` when the policy's decision on some call to it is `deny` (for the `reason`
+ * expected, when there is one), and `was held for` an approver (a group alone, as `{ group }`) when
+ * an approval for that approver holds it: one the policy asked for on its call, or one that `covers` it. A drift or apply expectation reads the report a finished run
+ * of it returned. A step named in the workflow's outline is read by the `name` its records carry
  * (its calls made, and `waitsOf`); a record written before steps had names has none.
  */
 export function detailOf(e: CoreExpectation, records: readonly LedgerRecord[]): string | undefined {
@@ -133,13 +162,18 @@ export function detailOf(e: CoreExpectation, records: readonly LedgerRecord[]):
   if ("decision" in e) {
     const tries = callsTo(e.op);
     if (e.decision === "denied") {
-      if (tries.some((r) => r.decision.kind === "deny")) return undefined;
+      const denials = tries.flatMap(({ decision: d }) => (d.kind === "deny" ? [d.reason] : []));
+      if (denials.some((reason) => e.reason === undefined || reason === e.reason)) return undefined;
+      if (denials.length) {
+        const said = [...new Set(denials)].map((reason) => JSON.stringify(reason)).join(" and ");
+        return `${e.op} was denied with ${said}, not ${JSON.stringify(e.reason)}`;
+      }
       return tries.length ? `${e.op} was ${decisions(tries)}, not denied` : `no call to ${e.op}`;
     }
     const holds = records.filter(isRequest).filter((r) => r.op === e.op || r.covers.includes(e.op));
     if (holds.some((r) => isApprover(r.approver, e.approver))) return undefined;
     return holds.length
-      ? `${e.op} was held for ${[...new Set(holds.map((r) => approverLabel(r.approver)))].join(" and ")}, not ${e.approver}`
+      ? `${e.op} was held for ${[...new Set(holds.map((r) => approverLabel(r.approver)))].join(" and ")}, not ${approverLabel(e.approver)}`
       : tries.length
         ? `${e.op} was ${decisions(tries)}, not held`
         : `no call to ${e.op}`;
@@ -161,5 +195,6 @@ export function detailOf(e: CoreExpectation, records: readonly LedgerRecord[]):
   }
   // A finished run: what `the run succeeds` expects, and what a drift expectation reads its report from.
   if (end.type === "run.failed") return `the run failed: ${end.error.message}`;
-  return "declared" in e ? driftDetail(e, end) : undefined;
+  if (!("declared" in e)) return undefined;
+  return "status" in e ? driftDetail(e, end) : applyDetail(e, end);
 }

package/src/host.ts

@@ -0,0 +1,96 @@
+import type { z } from "zod";
+
+// The `Host` contract: what a resource type that runs the company (a container, a Render service,
+// a Fly app) declares about itself, so hosts are swappable and one conformance kit decides
+// whether one works. A host is a resource type like any other; this is what sets it apart.
+
+/** How a host keeps the runtime up: `long-lived`, or (later) woken on a schedule. */
+export type HostLifetime = "long-lived" | "wake-on-schedule";
+
+/** What a host can do, for choosing one. */
+export interface HostCapabilities {
+  lifetime: HostLifetime;
+  /** Its `url` is reachable from the internet, not only from this machine. */
+  publicUrl: boolean;
+  /** It builds the repository from git itself, at the revision apply gives it. */
+  buildsFromGit: boolean;
+  /** Its outbound connections come from fixed addresses, for a vendor's allow-list. */
+  staticEgress: boolean;
+}
+
+/** What a host's state says of it: where the app answers, which commit it runs, and whether it is up. */
+export interface HostOutputs {
+  url: string;
+  /** The commit it runs, when its state says. */
+  revision?: string;
+  healthy: boolean;
+}
+
+/**
+ * A resource type's `host`: the fields it takes the runtime's inputs in, by dotted path into its
+ * declared fields, and how its state reads as `HostOutputs`. A host is drifted when
+ * `outputs(state).revision` differs from what `sanoma.source.resolve` says `ref` is now.
+ */
+export interface HostSpec {
+  capabilities: HostCapabilities;
+  inputs: {
+    /** The repository's clone URL, or a reference to a declared repository whose state holds one (a `by` field). */
+    source: string;
+    /** The branch (or tag) it runs: `main`, never a commit. */
+    ref: string;
+    /** The secrets it passes the runtime (`SANOMA_DATABASE_URL`, `SANOMA_SECRETS_KEY`): a write-only field. */
+    secrets: string;
+    /** The port the app listens on. */
+    port: string;
+  };
+  /**
+   * The field apply fills with the commit `ref` resolves to, before it plans: hidden, as a data
+   * file may not declare it, so a merge to `ref` is a change to the host.
+   */
+  revision: string;
+  outputs: (state: Record<string, unknown>) => HostOutputs;
+}
+
+const LIFETIMES: readonly HostLifetime[] = ["long-lived", "wake-on-schedule"];
+
+/** True when `schema` has a field at the dotted `path`, looking through optional, nullable and default wrappers. */
+function hasPath(schema: z.ZodType, path: string): boolean {
+  let at: z.ZodType | undefined = schema;
+  for (const key of path.split(".")) {
+    at = unwrap(at);
+    const shape = (at as Partial<z.ZodObject>).shape;
+    at = shape?.[key];
+    if (!at) return false;
+  }
+  return true;
+}
+
+function unwrap(schema: z.ZodType): z.ZodType {
+  let at = schema;
+  while ("unwrap" in at && typeof at.unwrap === "function") at = at.unwrap() as z.ZodType;
+  return at;
+}
+
+/**
+ * Throws what is wrong with a resource type's `host`: an input or `revision` that names no field,
+ * `secrets` that is not write-only, a `revision` that is, an unknown lifetime, a type apply cannot
+ * change (not `writable`).
+ */
+export function checkHost(
+  what: string,
+  host: HostSpec,
+  type: { schema: z.ZodObject; fields: { writeOnly: readonly string[] }; writable?: boolean },
+): void {
+  const problems: string[] = [];
+  if (!type.writable) problems.push("it must be writable, so apply can create and update it");
+  if (!LIFETIMES.includes(host.capabilities?.lifetime)) {
+    problems.push(`capabilities.lifetime is one of ${LIFETIMES.join(", ")}`);
+  }
+  for (const [input, path] of [...Object.entries(host.inputs ?? {}), ["revision", host.revision] as const]) {
+    if (typeof path !== "string" || !hasPath(type.schema, path)) problems.push(`${input} names no field (${path})`);
+  }
+  if (!type.fields.writeOnly.includes(host.inputs?.secrets)) problems.push("inputs.secrets must be a write-only field");
+  if (type.fields.writeOnly.includes(host.revision)) problems.push("revision must not be write-only: drift reads it");
+  if (typeof host.outputs !== "function") problems.push("outputs must be a function of the state");
+  if (problems.length) throw new Error(`${what}: its host: ${problems.join("; ")}`);
+}

package/src/index.ts

@@ -38,14 +38,30 @@ export {
   defineResource,
   diffDeclared,
   type FieldReference,
+  type PlanAction,
   type References,
   type Resource,
   type ResourceFields,
   type ResourceOps,
   type ResourceSpec,
+  withoutWriteOnly,
 } from "./resource.ts";
 export { defineConfig, resolveConfig, resolveDatabaseUrl, type ResolvedConfig, type SanomaConfig } from "./config.ts";
+// `sanoma` itself (the people types' constructors) is at `@sanoma-ai/workflows/resources`, for data files.
+// `collection()` itself is at `@sanoma-ai/workflows/data`, for `resources/data.ts`; this tells one apart, as the launcher does.
+export { isCollection } from "./collection.ts";
 export { type CredentialStatus, credentialsOf } from "./env.ts";
+export {
+  APPLY_WORKFLOW,
+  ApplyInput,
+  type ApplyPlan,
+  type ApplyReport,
+  type ApplyResult,
+  type PlanAnswer,
+  type PlanStep,
+} from "./apply.ts";
+export { CALL_WORKFLOW, CallInput } from "./call-workflow.ts";
+export { isDirect } from "./direct.ts";
 export {
   DRIFT_WORKFLOW,
   type DriftDeclared,
@@ -62,20 +78,32 @@ export {
   approve,
   approvedFor,
   type Decision,
-  definePolicy,
   deny,
   type Policy,
   type PolicyCall,
   type PolicyOp,
   policyOpOf,
+  type PreviewAnswer,
+  type PreviewRequest,
   type RecordedDecision,
 } from "./policy.ts";
 export {
+  cedarPolicy,
+  type CedarPolicySource,
+  loadPolicies,
+  POLICIES_DIR,
+  type PolicyProblem,
+  readPolicyFiles,
+  validatePolicies,
+} from "./cedar.ts";
+export {
+  ApprovalPendingError,
   errorCode,
   type ErrorCode,
   type ErrorInfo,
   type InputIssue,
   invalidInput,
+  NotAdmittedError,
   PolicyDeniedError,
   RejectedError,
   SanomaError,
@@ -93,12 +121,38 @@ export { ApprovalMessage, APPROVALS_EVENT, decisionEventOf } from "./approvals.t
 export { RUNTIME_VERSION } from "./version.ts";
 export type { RunArgs } from "./run.ts";
 export { startWorker, type Worker, type WorkerOptions } from "./worker.ts";
-export { SanomaClient, type RunsFilter, type RunSummary, type StartOptions } from "./client.ts";
+// `secret` itself is at `@sanoma-ai/workflows/resources`, for data files; this is the drivers' side.
+export {
+  generateSecret,
+  isSecret,
+  memorySecrets,
+  type Resolved,
+  resolveSecrets,
+  type Secret,
+  type Secrets,
+} from "./secret.ts";
+export { resolveRevision, SOURCE_RESOLVE, type Source } from "./source.ts";
+export type { HostCapabilities, HostLifetime, HostOutputs, HostSpec } from "./host.ts";
+export {
+  type CallOptions,
+  SanomaClient,
+  type RunsFilter,
+  type RunSummary,
+  type StartOptions,
+  type StoredSecret,
+} from "./client.ts";
 // A raw DBOS client on the runtime's database, for tests and tools that read DBOS directly.
 export { dbosClient } from "./db.ts";
 // Also at `@sanoma-ai/workflows/shared`, which a browser bundle can import.
 export {
+  AGENTS,
   approverLabel,
+  approverOf,
+  declaresPeople,
+  type PeopleResource,
+  personOf,
+  principalOf,
+  RUNTIME_AGENTS,
   credentialReady,
   DEFAULT_SLEEP_NAME,
   ENDED_STATUSES,

package/src/ledger.ts

@@ -3,7 +3,7 @@ import { appendFile, mkdir, readFile, truncate } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { isDeepStrictEqual } from "node:util";
-import { LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.ts";
+import { type Db, LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.ts";
 import type { Approver, Principal } from "./define.ts";
 import { type ErrorInfo, isFinal, keepCode } from "./errors.ts";
 import { shown, warn } from "./log.ts";
@@ -80,13 +80,23 @@ export type LedgerRecord = {
       op?: string;
       /** The held call's `seq`, which its `op.called` record has, for a policy request. */
       opSeq?: number;
+      /** The policies that held the call, by id, for a policy request whose policy names them. */
+      reasons?: string[];
     }
   /** A message the approval ignored: from someone other than the approver, or not a decision. */
   | { type: "approval.refused"; approval: string; by?: string; reason: string }
-  | { type: "approval.decided"; approval: string; decision: "approve" | "reject"; by: string; note?: string }
+  | {
+      type: "approval.decided";
+      approval: string;
+      decision: "approve" | "reject";
+      by: string;
+      note?: string;
+      /** Set when `by` started the run: nobody else could decide (`mayDecide`). */
+      alone?: true;
+    }
   /**
    * A `ctx.sleep` began; `until` is when it ends, in ms since the epoch: the time asked for, or
-   * for a duration the time the sleep started plus the duration, as the runtime saw it. Written
+   * for a duration the record's `at` plus the duration, as the runtime saw it. Written
    * for a time already past too, which waits not at all.
    */
   | {
@@ -292,25 +302,13 @@ export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Pr
 
   return {
     async append(record) {
-      const line = lineOf(record);
       const conn = await pool.db();
-      const inserted = await conn
-        .query(
-          `INSERT INTO ${TABLE} (id, run_id, seq, record) VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT (id) DO NOTHING RETURNING n`,
-          [record.id, record.runId, record.seq, line],
-        )
-        .catch((err: unknown) => {
-          if (DATA_EXCEPTION.test(pgCode(err))) {
-            throw final(`Ledger record ${record.id} can't be stored: ${errorMessage(err)}`, err);
-          }
-          throw err;
-        });
-      if (inserted.rows.length) return;
+      if (await insertRecord(conn, record)) return;
       // Another write of the id was first: the record it stored stands.
       const { rows } = await conn.query<{ record: LedgerRecord }>(`SELECT record FROM ${TABLE} WHERE id = $1`, [
         record.id,
       ]);
-      if (rows[0]) warnIfDifferent(rows[0].record, line);
+      if (rows[0]) warnIfDifferent(rows[0].record, lineOf(record));
     },
     async read(runId) {
       const { rows } = await (
@@ -323,6 +321,26 @@ export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Pr
   };
 }
 
+/**
+ * Stores the record in the Postgres ledger's table through `db`, unless one with its id is
+ * stored: true when this one was. What `postgresLedger` appends with, and a direct write
+ * (`SanomaClient.call`) inside the transaction that saves its record.
+ */
+export async function insertRecord(db: Db, record: LedgerRecord): Promise<boolean> {
+  const inserted = await db
+    .query(
+      `INSERT INTO ${TABLE} (id, run_id, seq, record) VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT (id) DO NOTHING RETURNING n`,
+      [record.id, record.runId, record.seq, lineOf(record)],
+    )
+    .catch((err: unknown) => {
+      if (DATA_EXCEPTION.test(pgCode(err))) {
+        throw final(`Ledger record ${record.id} can't be stored: ${errorMessage(err)}`, err);
+      }
+      throw err;
+    });
+  return inserted.rows.length > 0;
+}
+
 /** Keeps records in memory, for tests. */
 export function memoryLedger(): LedgerStore {
   const runs = new Map<string, Map<string, LedgerRecord>>();

package/src/lint.ts

@@ -1,6 +1,7 @@
+import { realpathSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { byPosition, childrenOf, type LintProblem, type Node, parsed, type SourceFile } from "./ast.ts";
-import { readDataFile } from "./datafile.ts";
+import { COLLECTIONS_FILE, readDataFile } from "./datafile.ts";
 import { constsOf, outlineBody, workflowLiterals } from "./outline.ts";
 import { inside, nearestDir, RELATIVE } from "./paths.ts";
 // From src/ and from dist/ alike, the package's own oxlint.json: the one list of allowed names.
@@ -33,7 +34,7 @@ const REFUSED_PACKAGES: [RegExp, string][] = [
 ];
 
 /**
- * What a workflow or policy may import from an author package, besides types: the one list,
+ * What a workflow may import from an author package, besides types: the one list,
  * `allowImportNames` of oxlint.json's `@sanoma-ai/workflows` entry (`sanoma`'s generated
  * `oxlint.json` derives its own entry from it). Everything else is
  * refused: the client, the worker and the app could start runs or approve the run's own
@@ -46,7 +47,7 @@ const WORKFLOW_IMPORTS: readonly string[] =
 const ALLOWED_NAMES = new Set(WORKFLOW_IMPORTS);
 
 const NOT_ALLOWED =
-  `a workflow or policy imports only ${WORKFLOW_IMPORTS.join(", ")} and types from ` +
+  `a workflow imports only ${WORKFLOW_IMPORTS.join(", ")} and types from ` +
   `${AUTHOR_PACKAGES.join(" or ")}: the rest could start runs, approve its own approvals, forge the ledger or read credentials`;
 
 /**
@@ -57,11 +58,12 @@ const NOT_ALLOWED =
 const ERROR_CLASSES = new Set(["DriverError", "SanomaError", "PolicyDeniedError", "RejectedError"]);
 
 /**
- * Checks a workflow or policy file. Imports allowed: the names in `WORKFLOW_IMPORTS` and any
+ * Checks a workflow file. Imports allowed: the names in `WORKFLOW_IMPORTS` and any
  * type from `@sanoma-ai/workflows` or `sanoma`, `@sanoma-ai/connector-<vendor>`, `zod`, and relative files. With
- * `filename`, a relative import must stay inside the file's nearest `workflows/` or `policies/`
- * directory, or its own directory when it has neither. No `instanceof` against the runtime's
- * error classes: read `errorCode(err)`.
+ * `filename`, a relative import must stay inside the file's nearest `workflows/` directory, or its
+ * own directory when it has none; the one file outside it a workflow may import is the company's
+ * `resources/data.ts`, its collections (by real path). No
+ * `instanceof` against the runtime's error classes: read `errorCode(err)`.
  *
  * In each workflow's `run` (the literal `defineWorkflow` is called with), it reports what the
  * outline cannot draw, as the worker refuses to start with (`outlineBody`): `ctx` used other
@@ -82,7 +84,7 @@ export function lintWorkflow(input: string | SourceFile, path?: string): LintPro
   const read = typeof input === "string" ? parsed(input, filename ?? "workflow.ts") : input;
   const { program, at } = read;
   const problems = [...read.problems];
-  const root = filename === undefined ? undefined : nearestDir(filename, ["workflows", "policies"]);
+  const root = filename === undefined ? undefined : nearestDir(filename, ["workflows"]);
 
   const checkSource = (node: Node) => {
     const spec: string = node.source.value;
@@ -197,12 +199,27 @@ type RestrictedPath = { name: string; allowImportNames?: string[] };
 
 function whyRefused(spec: string, filename: string | undefined, root: string | undefined): string | undefined {
   if (RELATIVE.test(spec)) {
-    if (filename === undefined || root === undefined || inside(root, join(dirname(filename), spec))) return undefined;
-    const where =
-      basename(root) === "workflows" || basename(root) === "policies" ? `${basename(root)}/` : "this directory";
-    return `it reaches outside ${where}, toward the config and its drivers; ${THROUGH_CTX}`;
+    if (filename === undefined || root === undefined) return undefined;
+    const target = join(dirname(filename), spec);
+    if (inside(root, target)) return undefined;
+    const tree = basename(root) === "workflows";
+    // The collections, which a workflow names in `uses`: the one data file the runtime imports too.
+    if (tree && realPath(target) === realPath(join(dirname(root), "resources", COLLECTIONS_FILE))) return undefined;
+    return (
+      `it reaches outside ${tree ? `${basename(root)}/` : "this directory"}, toward the config and its drivers; ${THROUGH_CTX}` +
+      (tree ? "; of the files outside it, only resources/data.ts (the collections) may be imported" : "")
+    );
   }
   for (const [pattern, reason] of REFUSED_PACKAGES) if (pattern.test(spec)) return reason;
   if (ALLOWED_PACKAGE.test(spec)) return undefined;
   return "import only from `sanoma` (or `@sanoma-ai/workflows`), a `@sanoma-ai/connector-*` package, zod, or a file beside this one";
 }
+
+/** A path's real path, or the path itself when it does not exist. */
+function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}

package/src/lockfile.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import type { ResourceProblem } from "./resources.ts";
+
+// The lockfile: which vendor object each declaration means, kept apart from the data files (which
+// hold intent only), as `package-lock.json` is from `package.json`. Only apply writes it.
+
+/** Where the lockfile is, relative to the config's root. */
+export const LOCKFILE = "resources/sanoma.lock.json";
+
+/** Which vendor object a declaration means: its `<vendor>.<type>` and the vendor's stable id for it. */
+export interface Binding {
+  type: string;
+  id: string;
+}
+
+/** The lockfile's content: by declaration key, `<file>#<export>` (the file relative to the config's root, with `/`). */
+export type Bindings = Record<string, Binding>;
+
+const lockfile = z.record(
+  z.string().regex(/^resources\/[^#]+#[^#]+$/),
+  z.strictObject({ type: z.string().regex(/^[^.\s]+\.[^.\s]+$/), id: z.string().min(1) }),
+);
+
+/**
+ * The lockfile under `root`: no bindings when there is none, and no bindings with a problem when
+ * it is not JSON or not a map of `<file>#<export>` to `{ type, id }`.
+ */
+export function readLockfile(root: string): { bindings: Bindings; problems: ResourceProblem[] } {
+  const path = join(root, LOCKFILE);
+  if (!existsSync(path)) return { bindings: {}, problems: [] };
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    return { bindings: {}, problems: [{ file: LOCKFILE, message: `not JSON: ${(e as Error).message}` }] };
+  }
+  const parsed = lockfile.safeParse(json);
+  if (!parsed.success) {
+    // One line: zod's own spans lines.
+    return {
+      bindings: {},
+      problems: [{ file: LOCKFILE, message: z.prettifyError(parsed.error).replaceAll(/\s*\n\s*/g, " ") }],
+    };
+  }
+  return { bindings: parsed.data, problems: [] };
+}
+
+/** The lockfile's text for `bindings`: keys sorted, two-space JSON, a trailing newline, so a diff shows only what changed. */
+export function serializeLockfile(bindings: Bindings): string {
+  const sorted = Object.entries(bindings)
+    .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, { type, id }]) => [key, { type, id }]);
+  return `${JSON.stringify(Object.fromEntries(sorted), null, 2)}\n`;
+}
+
+/** Writes the lockfile under `root` whole or not at all: to a file beside it, then renamed over it. Apply only. */
+export function writeLockfile(root: string, bindings: Bindings): void {
+  const path = join(root, LOCKFILE);
+  const temporary = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporary, serializeLockfile(bindings));
+    renameSync(temporary, path);
+  } catch (err) {
+    rmSync(temporary, { force: true });
+    throw err;
+  }
+}
+
+/**
+ * One change to the lockfile: a declaration bound for the first time (`bind`, `to`), pointed at
+ * another object (`rebind`, `from` and `to`), or no longer bound (`unbind`, `from`). `type` is
+ * the binding's `<vendor>.<type>`, the new one's for a rebind.
+ */
+export interface Rebind {
+  key: string;
+  type: string;
+  kind: "bind" | "rebind" | "unbind";
+  from?: string;
+  to?: string;
+}
+
+/** What changed from `before` to `after`, by key, sorted. */
+export function diffLockfiles(before: Bindings, after: Bindings): Rebind[] {
+  const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].toSorted();
+  return keys.flatMap((key): Rebind[] => {
+    const was = before[key];
+    const now = after[key];
+    if (!now) return was ? [{ key, type: was.type, kind: "unbind", from: was.id }] : [];
+    if (!was) return [{ key, type: now.type, kind: "bind", to: now.id }];
+    if (was.id === now.id && was.type === now.type) return [];
+    return [{ key, type: now.type, kind: "rebind", from: was.id, to: now.id }];
+  });
+}

package/src/op.ts

@@ -1,5 +1,6 @@
 import type { z } from "zod";
 import type { Fake } from "./fake.ts";
+import type { Secrets } from "./secret.ts";
 import type { Steps } from "./steps.ts";
 
 /**
@@ -235,6 +236,14 @@ export interface CallContext {
   opId: string;
   /** 1 on the first try; retries count up (idempotent operations only). */
   attempt: number;
+  /** The secrets store, for the values `secret()` markers name: `resolveSecrets(input, call.secrets)`. In memory for a fake. */
+  secrets: Secrets;
+  /**
+   * Who the call is made as: `run:<runId>` for a call in a run; the person's id for a direct call
+   * (`SanomaClient.call`) and in a run of the built-in `call` workflow. A collection's save
+   * records it as the record's `updatedBy`.
+   */
+  by?: string;
 }
 
 export type DriverFn<I = any, O = unknown> = (input: I, call: CallContext) => Promise<O>;

package/src/outline.ts

@@ -576,7 +576,7 @@ function ctxPath(callee: Node, ctx: string): string[] | undefined {
 }
 
 /** A string literal's value, or a template literal's with nothing interpolated. */
-function stringValue(node: Node): string | undefined {
+export function stringValue(node: Node): string | undefined {
   const n = unwrap(node);
   if (n?.type === "Literal" && typeof n.value === "string") return n.value;
   if (n?.type === "TemplateLiteral" && n.expressions.length === 0) return n.quasis[0]?.value.cooked ?? undefined;

package/src/paths.ts

@@ -1,7 +1,9 @@
-import { basename, dirname, isAbsolute, relative, sep } from "node:path";
+import { readdirSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 
-// Where an import may reach, as the lints and the data-file reader all decide it, and the one
-// walk up the directories. Node's `path` only, no parser: the oxlint plugin loads it.
+// Where an import may reach, as the lints and the data-file reader all decide it, the one walk up
+// the directories and the one walk down (`filesUnder`). Node's `path` and `fs` only, no parser:
+// the oxlint plugin loads it.
 
 /** A relative import specifier: `./x.ts`, `../y.ts`. */
 export const RELATIVE = /^\.\.?\//;
@@ -30,3 +32,16 @@ export function inside(dir: string, path: string): boolean {
   const rel = relative(dir, path);
   return rel === "" || (rel.split(sep)[0] !== ".." && !isAbsolute(rel));
 }
+
+/** True when `path` is a directory. */
+export const isDirectory = (path: string): boolean => statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
+
+/** The files under `dir` whose name `keep` takes, sorted, outside `node_modules`; none when `dir` is not a directory. */
+export function filesUnder(dir: string, keep: (name: string) => boolean): string[] {
+  if (!isDirectory(dir)) return [];
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((d) => d.isFile() && keep(d.name))
+    .map((d) => join(d.parentPath, d.name))
+    .filter((path) => !relative(dir, path).split(sep).includes("node_modules"))
+    .toSorted();
+}