@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/src/ledger.ts

@@ -0,0 +1,419 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+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 { Approver, Principal } from "./define.ts";
+import { type ErrorInfo, isFinal, keepCode } from "./errors.ts";
+import { shown, warn } from "./log.ts";
+import type { Effect } from "./op.ts";
+import type { RecordedDecision } from "./policy.ts";
+import type { Run } from "./run.ts";
+import { errorMessage } from "./shared.ts";
+
+/**
+ * The audit record of a run: who started it, every operation call with the policy's
+ * decision, every approval, and how it ended. Records are append-only.
+ *
+ * `id` is deterministic (`<runId>:<type>:<seq>`, `<runId>:<type>:<approvalId>` for an
+ * approval requested or decided, `<runId>:approval.refused:<approvalId>:refused:<n>` for
+ * the nth message an approval ignored) so that when DBOS replays a run after a restart,
+ * the records it writes again have the same ids and the store skips them. `seq` orders a
+ * run's records. `v` is the record format's version; `app` is the config's `appName`.
+ */
+export type LedgerRecord = {
+  v: 1;
+  app: string;
+  id: string;
+  runId: string;
+  seq: number;
+  at: number;
+  actor: Principal;
+  workflow: string;
+  /** Set on every record written while a `ctx.all` member runs; absent outside one. */
+  group?: LedgerGroup;
+} & (
+  | { type: "run.started"; input: unknown }
+  | {
+      type: "op.called";
+      op: string;
+      /**
+       * The outline node of the call that made it (`OutlineNode.path`): where the step is in the
+       * code. Absent in records written before the worker placed calls (ledgers from 0.1).
+       */
+      node?: string;
+      /**
+       * The step's name: the one the call gave (`{ name }`), or the operation's id. Absent in
+       * records written before steps had names.
+       */
+      name?: string;
+      effect: Effect;
+      input: unknown;
+      /** The policy's decision, with its `reasons` and the policy's `policyVersion` when there are any. */
+      decision: RecordedDecision;
+      output?: unknown;
+      /**
+       * Why the call failed: `{ code?, name, message }`, and the vendor's `status`, `vendorCode`
+       * and `retryable` from a `DriverError`, or the `data` of one of the runtime's errors.
+       */
+      error?: ErrorInfo;
+      durationMs: number;
+      /** Which try produced the output or the final error, from 1. Idempotent operations are retried. */
+      attempt?: number;
+      /** The approval that held the call, when its rejection stopped it. */
+      approval?: string;
+    }
+  | {
+      type: "approval.requested";
+      approval: string;
+      /** The outline node of the `ctx.approval` call, or of the held operation's call for a policy request; as for `op.called`. */
+      node?: string;
+      /** The step's name: the title for a `ctx.approval`, the held call's name for a policy request; as for `op.called`. */
+      name?: string;
+      title: string;
+      approver: Approver;
+      requestedBy: "workflow" | "policy";
+      /** The operations the approval stands for, by id. */
+      covers: string[];
+      /** The operation call held, for a policy request. */
+      op?: string;
+      /** The held call's `seq`, which its `op.called` record has, for a policy request. */
+      opSeq?: number;
+    }
+  /** 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 }
+  /**
+   * 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 time already past too, which waits not at all.
+   */
+  | {
+      type: "sleep.started";
+      node?: string;
+      /** The step's name: the one the call gave (`{ name }`), or `Sleep`; as for `op.called`. */
+      name?: string;
+      until: number;
+    }
+  /**
+   * A sandbox run seeded its fakes from the scenario named: each `Given` operation called
+   * through its fake, with what the fake returned, and each `Given` resource (by its type's id
+   * and its import id) put with its fields or removed (`gone`). Follows `run.started`.
+   */
+  | {
+      type: "scenario.seeded";
+      scenario: string;
+      seeds: (
+        | { op: string; input: unknown; output: unknown }
+        | { resource: string; name: string; fields: Record<string, unknown> }
+        | { resource: string; name: string; gone: true }
+      )[];
+    }
+  | { type: "run.finished"; output: unknown }
+  /** `error` as for `op.called`. */
+  | { type: "run.failed"; error: ErrorInfo }
+);
+
+/**
+ * The `ctx.all` member a record was written in. `id` is `all:<seq>`, the run's next `seq` when
+ * the `ctx.all` began, so a replay names it the same; `index` is the member's position, `size`
+ * the member count and `node` the `ctx.all` call's outline node.
+ */
+export interface LedgerGroup {
+  id: string;
+  index: number;
+  size: number;
+  /** The outline node of the `ctx.all` call; as for `op.called`'s. */
+  node?: string;
+}
+
+/**
+ * The `ctx.all` member a call was made in. Each member runs inside `currentGroup.run`, and a
+ * queued call keeps the context it was queued in, so a call made outside the member meanwhile
+ * (one the workflow did not await) is not tagged as the member's.
+ */
+export const currentGroup = new AsyncLocalStorage<LedgerGroup>();
+
+export interface LedgerStore {
+  /**
+   * Adds a record, unless one with the same id is already stored. A failed append is tried
+   * again, up to three times. A store throws an error with `retryable: false` for a failure
+   * that must not be retried because it would only happen again, such as a corrupt file or a
+   * record that can't be written as JSON.
+   */
+  append(record: LedgerRecord): Promise<void>;
+  /** A run's records in `seq` order. */
+  read(runId: string): Promise<LedgerRecord[]>;
+  /**
+   * Releases what the store holds (a connection pool), for good. Called by the one owner of the
+   * store: the worker's `stop` and `SanomaClient.close` close the Postgres store each made for a
+   * config without a `ledger` (`ownedLedger`); a store a config gives is its own to close.
+   */
+  close?(): Promise<void>;
+}
+
+/** The store a worker or client runs on, and `close`, which ends it only when it was made for them. */
+export interface OwnedLedger {
+  store: LedgerStore;
+  close(): Promise<void>;
+}
+
+/**
+ * The config's `ledger`, which stays the config's to close, or `postgresLedger` on its database,
+ * made here for the caller, and so the caller's to close: the worker and the client each make
+ * their own, and close it with themselves. Two of them on one database share the table, not a pool.
+ */
+export function ownedLedger(config: { ledger?: LedgerStore; databaseUrl: string }): OwnedLedger {
+  if (config.ledger) return { store: config.ledger, close: async () => undefined };
+  const store = postgresLedger(config.databaseUrl);
+  return { store, close: () => store.close() };
+}
+
+const bySeq = (a: LedgerRecord, b: LedgerRecord) => a.seq - b.seq;
+
+/** An error that trying again would only repeat. */
+const final = (message: string, cause: unknown) => Object.assign(new Error(message, { cause }), { retryable: false });
+
+/** JSON for a record, or an error that names the record when it can't be written as JSON (a BigInt, a cycle). */
+function serialize(record: LedgerRecord): string {
+  try {
+    return JSON.stringify(record);
+  } catch (cause) {
+    const op = record.type === "op.called" ? ` (${record.op})` : "";
+    throw final(`Ledger record ${record.id}${op} can't be written as JSON: ${errorMessage(cause)}`, cause);
+  }
+}
+
+/** The line `jsonlLedger` writes for a record: its JSON and a newline. */
+const lineOf = (record: LedgerRecord) => `${serialize(record)}\n`;
+
+const COMPARED = ["type", "input", "decision", "error", "output"] as const;
+
+/**
+ * The first record with an id stands. Says so when a later one with that id differs where it
+ * matters, showing both, so a replay that went another way can be told from a retry. Compared
+ * as values, not text: a store may give the kept record's keys back in another order (`jsonb`).
+ */
+function warnIfDifferent(stored: LedgerRecord, line: string) {
+  const later = JSON.parse(line) as Record<string, unknown>;
+  const differs = COMPARED.flatMap((k) => {
+    const kept = (stored as Record<string, unknown>)[k];
+    const sent = later[k];
+    return isDeepStrictEqual(kept, sent) ? [] : [`${k} (kept ${shown(kept, 200)}, later ${shown(sent, 200)})`];
+  });
+  if (differs.length) {
+    warn(`ledger: kept the first record ${stored.id}; a later write differed in ${differs.join("; ")}`);
+  }
+}
+
+/** The file's complete records, and the length of its complete lines when a cut-off line follows them. */
+async function load(path: string): Promise<{ records: LedgerRecord[]; tornAt?: number }> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return { records: [] };
+    throw err;
+  }
+  const complete = text.slice(0, text.lastIndexOf("\n") + 1);
+  const records: LedgerRecord[] = [];
+  complete.split("\n").forEach((line, i) => {
+    if (!line.trim()) return;
+    try {
+      records.push(JSON.parse(line) as LedgerRecord);
+    } catch (cause) {
+      throw final(`${path}:${i + 1}: corrupt ledger line`, cause);
+    }
+  });
+  return complete.length < text.length ? { records, tornAt: Buffer.byteLength(complete) } : { records };
+}
+
+/**
+ * Keeps each run's records in `<dir>/<runId>.jsonl`, one JSON object per line. A run with no
+ * file, or a directory not yet created, reads as no records.
+ *
+ * A line with no newline at the end of a file is a write that was cut off (the process
+ * died mid-append): reads ignore it, and the next append removes it before writing.
+ * A line that isn't JSON anywhere else is corruption, and reads throw.
+ */
+export function jsonlLedger(dir: string): LedgerStore {
+  const root = resolve(dir);
+  const file = (runId: string) => join(root, `${encodeURIComponent(runId)}.jsonl`);
+  // Appends to one file are serialized, so the id check and the write can't interleave.
+  const queues = new Map<string, Promise<unknown>>();
+
+  return {
+    append(record) {
+      const path = file(record.runId);
+      const next = (queues.get(path) ?? Promise.resolve())
+        .catch(() => {})
+        .then(async () => {
+          const line = lineOf(record);
+          const { records, tornAt } = await load(path);
+          const stored = records.find((r) => r.id === record.id);
+          if (stored) return warnIfDifferent(stored, line);
+          await mkdir(root, { recursive: true });
+          if (tornAt !== undefined) {
+            warn(`ledger: ${path} ended in a cut-off line; removed it before appending ${record.id}`);
+            await truncate(path, tornAt);
+          }
+          await appendFile(path, line);
+        });
+      queues.set(path, next);
+      const forget = () => {
+        if (queues.get(path) === next) queues.delete(path);
+      };
+      next.then(forget, forget);
+      return next;
+    },
+    async read(runId) {
+      const path = file(runId);
+      await queues.get(path)?.catch(() => {});
+      // A missing directory, like a missing file, means nothing has been recorded there yet:
+      // `load` reads either as no records. Any other failure is thrown.
+      // A case-insensitive file system can map two run ids to one file.
+      return (await load(path)).records.filter((r) => r.runId === runId).toSorted(bySeq);
+    },
+  };
+}
+
+/** Postgres's class for a value it cannot store (a string with a NUL in `jsonb`): trying again would only repeat it. */
+const DATA_EXCEPTION = /^22/;
+
+/**
+ * Keeps records in the `sanoma_ledger` table of the database at `databaseUrl`, beside DBOS's
+ * tables: the default store, which the worker, the app and the client share through Postgres.
+ * The database and the table are made on first use when they are not there (`prepareDatabase`).
+ * The pool is opened on first use and ended by `close()`, after which the store refuses use.
+ */
+export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Promise<void> } {
+  const pool = lazyPool(databaseUrl, "ledger");
+
+  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;
+      // 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);
+    },
+    async read(runId) {
+      const { rows } = await (
+        await pool.db()
+      ).query<{ record: LedgerRecord }>(`SELECT record FROM ${TABLE} WHERE run_id = $1 ORDER BY seq, n`, [runId]);
+      // In seq order, as the other stores read; two records of one seq in write order.
+      return rows.map((r) => r.record);
+    },
+    close: pool.close,
+  };
+}
+
+/** Keeps records in memory, for tests. */
+export function memoryLedger(): LedgerStore {
+  const runs = new Map<string, Map<string, LedgerRecord>>();
+  return {
+    async append(record) {
+      const line = serialize(record);
+      let run = runs.get(record.runId);
+      if (!run) runs.set(record.runId, (run = new Map()));
+      const stored = run.get(record.id);
+      if (stored) warnIfDifferent(stored, line);
+      else run.set(record.id, JSON.parse(line));
+    },
+    async read(runId) {
+      return [...(runs.get(runId)?.values() ?? [])].map((r) => structuredClone(r)).toSorted(bySeq);
+    },
+  };
+}
+
+type Common = "v" | "app" | "id" | "runId" | "seq" | "at" | "actor" | "workflow" | "group";
+
+/** What one kind of record says, without what every record carries: `type` and its own fields. */
+export type LedgerBody = LedgerRecord extends infer R ? (R extends LedgerRecord ? Omit<R, Common> : never) : never;
+
+/** A record of the run, with the next `seq` unless one is given, tagged with the `ctx.all` member it is written in. */
+export function entry(
+  run: Run,
+  body: LedgerBody,
+  opts: { seq?: number; key?: string; at?: number } = {},
+): LedgerRecord {
+  const seq = opts.seq ?? run.seq++;
+  const record = {
+    v: 1,
+    app: run.state.app,
+    id: `${run.id}:${body.type}:${opts.key ?? seq}`,
+    runId: run.id,
+    seq,
+    at: opts.at ?? Date.now(),
+    actor: run.actor,
+    workflow: run.workflow,
+    ...body,
+  } as LedgerRecord;
+  const group = currentGroup.getStore();
+  if (group) record.group = group;
+  return record;
+}
+
+// Waits between tries of a failed append. Safe to repeat: append is idempotent by id.
+const RETRY_DELAYS_MS = [50, 200, 800];
+
+async function append(run: Run, record: LedgerRecord) {
+  for (let i = 0; ; i++) {
+    try {
+      return await run.state.ledger.append(record);
+    } catch (err) {
+      const wait = RETRY_DELAYS_MS[i];
+      if (wait === undefined || isFinal(err)) throw err;
+      warn(`ledger: appending ${record.id} failed (${errorMessage(err)}); trying again in ${wait} ms`);
+      await delay(wait);
+    }
+  }
+}
+
+/*
+ * Every ledger write happens outside DBOS steps. When DBOS replays a run after a restart,
+ * it re-runs the workflow function and these writes happen again with the same ids, so
+ * the store keeps one of each and fills in any the interrupted run never got to write.
+ */
+export async function write(run: Run, record: LedgerRecord) {
+  await append(run, record);
+}
+
+/**
+ * Records a failure. If the ledger fails too, throws both, so neither is lost, with the
+ * original's code: the run still fails the way it did.
+ */
+export async function writeFailure(run: Run, record: LedgerRecord, original: unknown) {
+  try {
+    await append(run, record);
+  } catch (ledgerError) {
+    throw keepCode(
+      new AggregateError(
+        [original, ledgerError],
+        `${errorMessage(original)} (and the ledger could not record ${record.id}: ${errorMessage(ledgerError)})`,
+        { cause: ledgerError },
+      ),
+      original,
+    );
+  }
+}
+
+/** Says that a record was deliberately not written, and why. */
+export function skipped(record: LedgerRecord, why: string) {
+  warn(`did not write ${record.type} ${record.id}: ${why}`);
+}

package/src/lint.ts

@@ -0,0 +1,208 @@
+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 { 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.
+import oxlint from "../oxlint.json" with { type: "json" };
+
+export type { LintProblem } from "./ast.ts";
+
+/**
+ * A workflow must call vendors through `ctx`, so the policy sees every call. These are the
+ * import rules oxlint's built-in rules cannot express; the clock, randomness, the network
+ * and the environment are oxlint's (the package's `oxlint.json`).
+ */
+const THROUGH_CTX = "a workflow must call vendors through ctx, so the policy sees every call";
+
+/**
+ * The packages the author surface is imported from, each allowing the same names: `sanoma`
+ * re-exports what `@sanoma-ai/workflows` allows (and `z`). Adding one here accepts it.
+ */
+const AUTHOR_PACKAGES: readonly string[] = ["@sanoma-ai/workflows", "sanoma"];
+
+/** The packages a workflow may import from at all: the author packages, connectors and zod. */
+const ALLOWED_PACKAGE = new RegExp(`^(${[...AUTHOR_PACKAGES, "@sanoma-ai/connector-[a-z0-9-]+", "zod"].join("|")})$`);
+
+/** Packages refused by name, with the reason. */
+const REFUSED_PACKAGES: [RegExp, string][] = [
+  [/^@sanoma-ai\/testing(\/|$)/, `fakes and test helpers belong in tests; ${THROUGH_CTX}`],
+  [/^@sanoma-ai\/app(\/|$)/, "the app starts runs and decides approvals, so a workflow could approve itself"],
+  [/^@sanoma-ai\/connector-[^/]+\/(fake|driver)(\/|$)/, `${THROUGH_CTX}; import the connector itself`],
+  [/^sanoma\//, "`sanoma` has no entry points for a workflow: import its names from `sanoma` itself"],
+];
+
+/**
+ * What a workflow or policy 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
+ * approvals, a ledger store could forge the audit record (a store keeps the first record per
+ * id), and config helpers can read credentials.
+ */
+const WORKFLOW_IMPORTS: readonly string[] =
+  restrictedImports(oxlint).find((p) => p.name === "@sanoma-ai/workflows")?.allowImportNames ?? [];
+
+const ALLOWED_NAMES = new Set(WORKFLOW_IMPORTS);
+
+const NOT_ALLOWED =
+  `a workflow or policy 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`;
+
+/**
+ * Error classes a run must not test with `instanceof`: on a replay DBOS rethrows a serialized
+ * copy, which is no instance of them, so a branch on it goes another way than the first time
+ * and the run's steps fall out of step. Read the code with `errorCode(err)` instead.
+ */
+const ERROR_CLASSES = new Set(["DriverError", "SanomaError", "PolicyDeniedError", "RejectedError"]);
+
+/**
+ * Checks a workflow or policy 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)`.
+ *
+ * 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
+ * than called directly (passed on, aliased, destructured), a function defined in `run` that uses
+ * `ctx` where the outline does not read it, `ctx` in a `finally`, a step name that is no literal
+ * and two calls with one step name, and in `run` and the callbacks it reads, a `return` before
+ * the end, a `throw` outside a `catch`, a `break` out of a loop and `continue`. Each message
+ * names what to write instead.
+ *
+ * It guards against accidental non-determinism and accidental ways around the policy; it is
+ * not a sandbox, and code written to get around it can.
+ */
+export function lintWorkflow(source: string, filename?: string): LintProblem[];
+/** The same, over a file `readSource` read: the reading `describeConfig` shares with the outline. */
+export function lintWorkflow(file: SourceFile): LintProblem[];
+export function lintWorkflow(input: string | SourceFile, path?: string): LintProblem[] {
+  const filename = typeof input === "string" ? path : input.file;
+  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 checkSource = (node: Node) => {
+    const spec: string = node.source.value;
+    const refusal = whyRefused(spec, filename, root);
+    if (refusal) {
+      problems.push({ ...at(node.source.start), message: `import "${spec}" is not allowed in a workflow: ${refusal}` });
+      return;
+    }
+    if (!AUTHOR_PACKAGES.includes(spec)) return;
+    if (node.type === "ExportAllDeclaration") {
+      problems.push({
+        ...at(node.start),
+        message: `export * from "${spec}" is not allowed in a workflow: it would re-export what a workflow may not import`,
+      });
+    }
+    for (const s of node.specifiers ?? []) {
+      if (s.type === "ImportNamespaceSpecifier") {
+        problems.push({
+          ...at(s.start),
+          message: `import * from "${spec}" is not allowed in a workflow: import the names you use, so the rest stays out`,
+        });
+        continue;
+      }
+      // `import type { X }`, `import { type X }` and `export type { X }` bring in no values.
+      if (
+        node.importKind === "type" ||
+        node.exportKind === "type" ||
+        s.importKind === "type" ||
+        s.exportKind === "type"
+      ) {
+        continue;
+      }
+      // What the module exports under: `imported` for an import, `local` for a re-export.
+      const named = s.imported ?? s.local;
+      const imported: string = s.type === "ImportDefaultSpecifier" ? "default" : (named?.name ?? named?.value);
+      if (!ALLOWED_NAMES.has(imported)) {
+        problems.push({ ...at(s.start), message: `${imported} is not allowed in a workflow: ${NOT_ALLOWED}` });
+      }
+    }
+  };
+
+  const visit = (node: Node) => {
+    if (!node) return;
+    if (
+      (node.type === "ImportDeclaration" ||
+        node.type === "ExportNamedDeclaration" ||
+        node.type === "ExportAllDeclaration") &&
+      node.source
+    ) {
+      checkSource(node);
+    } else if (node.type === "ImportExpression") {
+      problems.push({ ...at(node.start), message: "dynamic import is not allowed in a workflow" });
+    } else if (node.type === "BinaryExpression" && node.operator === "instanceof") {
+      checkInstanceof(node);
+    }
+    for (const child of childrenOf(node)) visit(child);
+  };
+
+  // A workflow imports none of these classes, so they are refused by the name they have.
+  const checkInstanceof = (node: Node) => {
+    const right = node.right;
+    const name: string | undefined =
+      right?.type === "Identifier"
+        ? right.name
+        : right?.type === "MemberExpression" && !right.computed
+          ? right.property?.name
+          : undefined;
+    if (name !== undefined && ERROR_CLASSES.has(name)) {
+      problems.push({
+        ...at(node.start),
+        message:
+          `instanceof ${name} is not allowed in a workflow: on a replay DBOS rethrows a copy of the error, ` +
+          "which is no instance of it, so the run would take another branch; read `errorCode(err)`",
+      });
+    }
+  };
+
+  visit(program);
+  // Each workflow's `run` as the worker reads it when it starts: what the outline cannot draw,
+  // the worker refuses to start with. One reading, so the lint and the worker agree.
+  const outlined = { consts: constsOf(program), source: typeof input === "string" ? input : input.source };
+  for (const { run } of workflowLiterals(program))
+    for (const { start, message } of outlineBody(run, outlined).problems) problems.push({ ...at(start), message });
+  return byPosition(problems);
+}
+
+/**
+ * Checks a data file under `resources/`: only named imports (a connector's constructors from its
+ * `…/resources` entry, and resources from other data files inside the same `resources/`
+ * directory), `export const <name> = <vendor>.<type>({ … })` with literal fields and names of
+ * declared resources, and `export default [ … ]`. Each message says what to write instead.
+ * It is the subset `readResources` reads (`readDataFile`), without the config: whether the
+ * connector, the type and the values are known is the reader's to say.
+ */
+export function lintResources(source: string, filename: string): LintProblem[] {
+  const { program, problems, at } = parsed(source, filename);
+  for (const p of readDataFile(program, filename).problems) problems.push({ ...at(p.start), message: p.message });
+  return byPosition(problems);
+}
+
+/** The `paths` of oxlint.json's `no-restricted-imports` rule. */
+function restrictedImports(config: typeof oxlint): RestrictedPath[] {
+  // JSON types the rule's [severity, options] as an array of either.
+  return config.overrides.flatMap((o) =>
+    "no-restricted-imports" in o.rules
+      ? (o.rules["no-restricted-imports"] as [string, { paths: RestrictedPath[] }])[1].paths
+      : [],
+  );
+}
+
+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}`;
+  }
+  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";
+}