@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/src/errors.ts

@@ -0,0 +1,202 @@
+import { Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
+import type { z } from "zod";
+import type { Principal } from "./define.ts";
+import { errorMessage } from "./shared.ts";
+
+const CODES = [
+  "policy_denied",
+  "approval_rejected",
+  "not_approver",
+  "no_pending_approval",
+  "already_decided",
+  "run_not_found",
+  "driver_failed",
+  "invalid_input",
+  "run_ended",
+  "run_running",
+  "call_not_in_outline",
+] as const;
+
+/**
+ * Why something failed, as a stable string a caller can branch on. Messages are for people
+ * and may change; codes are the contract.
+ */
+export type ErrorCode = (typeof CODES)[number];
+
+const KNOWN = new Set<string>(CODES);
+
+/**
+ * An error with a `code` and plain-JSON `data`, both own enumerable properties, so they survive
+ * the trip through DBOS: a run's error is stored serialized and comes back as a new object that
+ * is not an instance of this class. Read the code with `errorCode`, never `instanceof`.
+ */
+export class SanomaError extends Error {
+  readonly code: ErrorCode;
+  readonly data: Record<string, unknown>;
+
+  constructor(code: ErrorCode, message: string, data: Record<string, unknown> = {}, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "SanomaError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/** The error's code, read from its own `code` property, or undefined when it has none of ours. */
+export function errorCode(e: unknown): ErrorCode | undefined {
+  const code = own<string>(e, "code", "string");
+  return code !== undefined && KNOWN.has(code) ? (code as ErrorCode) : undefined;
+}
+
+/**
+ * True when the error says trying again would only repeat it (`retryable: false`), as a
+ * `DriverError` for a vendor's final answer or a ledger store for a corrupt file does. Read as
+ * a property, never `instanceof`: the error may come from another copy of this package.
+ */
+export const isFinal = (err: unknown): boolean => (err as { retryable?: unknown } | null)?.retryable === false;
+
+/** The error and the ones it was caused by, a few deep. */
+export function causes(err: unknown): Error[] {
+  const out: Error[] = [];
+  for (let e = err; e instanceof Error && out.length < 5; e = e.cause) out.push(e);
+  return out;
+}
+
+/**
+ * True for a failure that ends the run rather than one call: anything DBOS throws (it cancelled
+ * the run, another process took it over, the worker is shutting down, the run is not
+ * deterministic) and `run_ended` (a call queued after the run's body ended). Looked for in the
+ * error and its causes. A workflow that goes on past a failed call, as `drift` does, rethrows these.
+ */
+export const isRunControlError = (err: unknown): boolean =>
+  causes(err).some((e) => e instanceof DBOSErrors.DBOSError || errorCode(e) === "run_ended");
+
+/** Thrown into the run when the policy denies an operation call. The run fails with it. */
+export class PolicyDeniedError extends SanomaError {
+  constructor(op: string, reason: string) {
+    super("policy_denied", `${op} was denied by policy: ${reason}`, { op, reason });
+    this.name = "PolicyDeniedError";
+  }
+}
+
+/** Thrown into the run when an approver rejects. The run fails with it. */
+export class RejectedError extends SanomaError {
+  /**
+   * @param title The approval's title.
+   * @param by Who rejected it.
+   * @param approvalId The approval's id in the run, such as "approval-2".
+   */
+  constructor(title: string, by: Principal, note: string | undefined, approvalId: string) {
+    super("approval_rejected", `"${title}" was rejected by ${by.id}${note ? `: ${note}` : ""}`, {
+      title,
+      by,
+      ...(note === undefined ? {} : { note }),
+      approvalId,
+    });
+    this.name = "RejectedError";
+  }
+}
+
+/**
+ * The wrapper, given the original's own `code` and `data` when it has one of our codes, so
+ * `errorCode` reads the same through it: a denied call whose ledger write failed too is still
+ * `policy_denied`.
+ */
+export function keepCode<E extends Error>(wrapper: E, original: unknown): E {
+  const code = errorCode(original);
+  if (code === undefined) return wrapper;
+  const data = own<Record<string, unknown>>(original, "data", "object");
+  return Object.assign(wrapper, { code }, data === undefined ? {} : { data });
+}
+
+/** A zod issue as the ledger and an API can carry it: no symbols in the path. */
+export interface InputIssue {
+  path: (string | number)[];
+  message: string;
+  code: string;
+}
+
+/** The value, parsed by the schema, or an `invalid_input` error carrying zod's issues and `data`. */
+export function parseOrThrow<T extends z.ZodType>(
+  schema: T,
+  value: unknown,
+  what: string,
+  data?: Record<string, unknown>,
+): z.output<T> {
+  const parsed = schema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  throw invalidInput(what, parsed.error.issues, data);
+}
+
+/** An `invalid_input` error from zod issues, with the issues in `data` and a one-line message. */
+export function invalidInput(
+  what: string,
+  zodIssues: readonly { path: PropertyKey[]; message: string; code: string }[],
+  data: Record<string, unknown> = {},
+): SanomaError {
+  const issues: InputIssue[] = zodIssues.map(({ path, message, code }) => ({
+    path: path.filter((p): p is string | number => typeof p !== "symbol"),
+    message,
+    code,
+  }));
+  const said = issues.map((i) => (i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message)).join("; ");
+  return new SanomaError("invalid_input", `${what}: ${said}`, { ...data, issues });
+}
+
+/**
+ * What the ledger keeps of an error. `status`, `vendorCode` and `retryable` are a
+ * `DriverError`'s account of the vendor's answer; `data` is one of the runtime's errors'. Each is
+ * there only when the error has it, and `data`, `status` and `vendorCode` only from those errors.
+ */
+export interface ErrorInfo {
+  code?: ErrorCode;
+  name: string;
+  message: string;
+  /** The vendor's HTTP status, from a `DriverError`. */
+  status?: number;
+  /** The vendor's own error code, from a `DriverError`. */
+  vendorCode?: string;
+  /** Whether trying again could succeed, from a `DriverError` or a ledger store. */
+  retryable?: boolean;
+  /** A `SanomaError`'s `data`: the operation, the approval, the issues. */
+  data?: Record<string, unknown>;
+}
+
+/** The error's own property `key`, when it is of the type given. Own: a copy from DBOS has no prototype to read. */
+function own<T>(err: unknown, key: string, type: "number" | "string" | "boolean" | "object"): T | undefined {
+  if (typeof err !== "object" || err === null || !Object.hasOwn(err, key)) return undefined;
+  const value = (err as Record<string, unknown>)[key];
+  return typeof value === type && value !== null ? (value as T) : undefined;
+}
+
+const fromDriver = (code: ErrorCode | undefined) => code === "driver_failed";
+const fromRuntime = (code: ErrorCode | undefined) => code !== undefined;
+const fromAny = () => true;
+
+/**
+ * The fields `errorInfo` copies, with their types, and from which errors. Only the runtime's
+ * errors give `data`, and only a `DriverError` the vendor's `status` and `vendorCode`: an error
+ * a driver lets escape (an HTTP client's) may carry the vendor's whole response under those
+ * names. `retryable` is anyone's, a ledger store's included.
+ */
+const KEPT = [
+  ["status", "number", fromDriver],
+  ["vendorCode", "string", fromDriver],
+  ["retryable", "boolean", fromAny],
+  ["data", "object", fromRuntime],
+] as const;
+
+export function errorInfo(err: unknown): ErrorInfo {
+  const code = errorCode(err);
+  const info: ErrorInfo = {
+    ...(code === undefined ? {} : { code }),
+    name: err instanceof Error ? err.name : "Error",
+    message: errorMessage(err),
+  };
+  for (const [key, type, keeps] of KEPT) {
+    const value = keeps(code) ? own(err, key, type) : undefined;
+    if (value !== undefined) Object.assign(info, { [key]: value });
+  }
+  if (info.data && Object.keys(info.data).length === 0) delete info.data;
+  return info;
+}

package/src/expectations.ts

@@ -0,0 +1,165 @@
+import { isDeepStrictEqual } from "node:util";
+import type { Approver } from "./define.ts";
+import type { DriftReport, DriftResult } from "./drift.ts";
+import type { LedgerRecord } from "./ledger.ts";
+import type { RecordedDecision } from "./policy.ts";
+import type { Expectation } from "./scenario.ts";
+import { approverLabel } from "./shared.ts";
+
+/*
+ * What the generic `Then` steps check against a run's ledger records: pure, and internal to
+ * `scenario.ts`, whose steps call it (its tests do too).
+ */
+
+/** A call in a run: an `op.called` record. */
+export type CallRecord = Extract<LedgerRecord, { type: "op.called" }>;
+type Request = Extract<LedgerRecord, { type: "approval.requested" }>;
+
+export const isCall = (r: LedgerRecord): r is CallRecord => r.type === "op.called";
+const isRequest = (r: LedgerRecord): r is Request => r.type === "approval.requested";
+
+/** True when `actual` has every key `expected` has, with an equal value, at every depth. */
+export function contains(actual: unknown, expected: unknown): boolean {
+  if (typeof expected !== "object" || expected === null || Array.isArray(expected)) {
+    return isDeepStrictEqual(actual, expected);
+  }
+  if (typeof actual !== "object" || actual === null || Array.isArray(actual)) return false;
+  return Object.entries(expected).every(([k, v]) => contains((actual as Record<string, unknown>)[k], v));
+}
+
+/**
+ * The records of the step named `name` that are not calls: its sleeps, and the approvals the
+ * workflow asked for by that title. A policy's hold carries the held call's name, and is that
+ * call's, not a run of its own.
+ */
+const waitsOf = (records: readonly LedgerRecord[], name: string) =>
+  records.filter(
+    (r) =>
+      (r.type === "sleep.started" || (r.type === "approval.requested" && r.requestedBy === "workflow")) &&
+      r.name === name,
+  );
+
+/**
+ * Why a call expected (`what`) is missing: that, the calls made among `tries` (with their
+ * inputs), and the ones attempted, failed (denied, rejected, or failed at the vendor for good).
+ */
+function missing(what: string, tries: CallRecord[]): string {
+  const made = tries.filter((r) => !r.error);
+  const tried = tries.flatMap(({ error }) => (error ? [`${error.code ?? error.name}: ${error.message}`] : []));
+  return [
+    what,
+    ...(made.length ? [`its calls had ${inputs(made)}`] : []),
+    ...(tried.length ? [`attempted: ${tried.join(", ")}`] : []),
+  ].join("; ");
+}
+
+/** `once`, `twice`, `3 times`. */
+const times = (n: number) => (n === 1 ? "once" : n === 2 ? "twice" : `${n} times`);
+
+/** Why an expectation about a named step does not hold against a run's records, or undefined when it does. */
+function namedDetail(e: Extract<CoreExpectation, { name: string }>, records: readonly LedgerRecord[]) {
+  const tries = records.filter(isCall).filter((r) => r.name === e.name);
+  const calls = tries.filter((r) => !r.error);
+  const runs = calls.length + waitsOf(records, e.name).length;
+  const step = `step "${e.name}"`;
+  if ("times" in e) return runs === e.times ? undefined : `${step} ran ${times(runs)}, not ${times(e.times)}`;
+  const matched = e.input === undefined ? runs : calls.filter((r) => contains(r.input, e.input)).length;
+  if (matched > 0 === e.called) return undefined;
+  if (!e.called) return calls.length ? `${step} was called with ${inputs(calls)}` : `${step} ran ${times(runs)}`;
+  return missing(
+    e.input === undefined ? `${step} was not called` : `${step} was not called with ${JSON.stringify(e.input)}`,
+    tries,
+  );
+}
+
+/** The inputs of the calls, as JSON, for a detail. */
+const inputs = (list: CallRecord[]) => list.map((r) => JSON.stringify(r.input)).join(", ");
+
+/** A policy's decision as words: `allowed`, `denied`, `held for finance`. */
+const words = (d: RecordedDecision) =>
+  d.kind === "allow" ? "allowed" : d.kind === "deny" ? "denied" : `held for ${approverLabel(d.approver)}`;
+
+/** 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;
+
+/** How a drift report found a resource, as words: `clean`, `gone`, `drifted in has_wiki, topics`. */
+const found = (r: DriftResult) =>
+  r.status === "drifted" ? `drifted in ${r.fields.map((f) => f.path).join(", ")}` : r.status;
+
+/** An expectation of the generic steps, without its step's text. */
+export type CoreExpectation = Unstepped<Exclude<Expectation, { custom: true }>>;
+type Unstepped<T> = T extends unknown ? Omit<T, "step"> : never;
+
+/**
+ * Why a drift expectation fails against the report a finished drift run returned as its
+ * output, or undefined when the report found the resource as expected.
+ */
+function driftDetail(
+  e: Extract<CoreExpectation, { declared: string }>,
+  end: Extract<LedgerRecord, { type: "run.finished" }>,
+): string | undefined {
+  const report = end.output as Partial<DriftReport> | null | undefined;
+  if (!Array.isArray(report?.resources)) return "the run's output is not a drift report";
+  const resource = report.resources.find((r) => r.id === e.declared);
+  if (!resource) {
+    return `no resource ${e.declared} in the report; it has ${report.resources.map((r) => r.id).join(", ") || "none"}`;
+  }
+  if (resource.status === "error") return `${e.declared} could not be read: ${resource.error}`;
+  const ok =
+    resource.status === e.status && (e.status !== "drifted" || resource.fields.some((f) => f.path === e.field));
+  if (ok) return undefined;
+  return `${e.declared} is ${found(resource)}, not ${e.status === "drifted" ? `drifted in ${e.field}` : e.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
+ * (its calls made, and `waitsOf`); a record written before steps had names has none.
+ */
+export function detailOf(e: CoreExpectation, records: readonly LedgerRecord[]): string | undefined {
+  if ("name" in e) return namedDetail(e, records);
+  const end = records.find((r) => r.type === "run.finished" || r.type === "run.failed");
+  const calls = records.filter(isCall);
+  const callsTo = (op: string) => calls.filter((r) => r.op === op);
+  if ("decision" in e) {
+    const tries = callsTo(e.op);
+    if (e.decision === "denied") {
+      if (tries.some((r) => r.decision.kind === "deny")) return undefined;
+      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}`
+      : tries.length
+        ? `${e.op} was ${decisions(tries)}, not held`
+        : `no call to ${e.op}`;
+  }
+  if ("called" in e) {
+    const tries = callsTo(e.op);
+    const made = tries.filter((r) => !r.error);
+    const matching = made.filter((r) => e.input === undefined || contains(r.input, e.input));
+    if (matching.length > 0 === e.called) return undefined;
+    if (!e.called) return `${e.op} was called with ${inputs(matching)}`;
+    return missing(`no call to ${e.input === undefined ? e.op : `${e.op} with ${JSON.stringify(e.input)}`}`, tries);
+  }
+  // The rest read how the run ended.
+  if (!end) return "run not ended";
+  if ("outcome" in e && e.outcome === "failed") {
+    if (end.type !== "run.failed") return "the run finished";
+    if (e.code === undefined || end.error.code === e.code) return undefined;
+    return `the run failed with ${end.error.code ?? "no code"}: ${end.error.message}`;
+  }
+  // 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;
+}

package/src/fake.ts

@@ -0,0 +1,156 @@
+import {
+  type Connector,
+  defineDriver,
+  type Driver,
+  type DriverFn,
+  type DriverImpl,
+  DriverError,
+  type OpIdOf,
+  type Specs,
+} from "./op.ts";
+
+/*
+ * Fake vendors for tests, at `@sanoma-ai/workflows/fake`. Kept off the main entry so the
+ * runtime bundle carries no test tooling, and so the lint can refuse it in workflow files.
+ */
+
+/** One call a fake received. */
+export interface FakeCall {
+  op: string;
+  input: unknown;
+  /** When the call arrived, as an ISO timestamp. */
+  at: string;
+  idempotencyKey: string;
+  attempt: number;
+}
+
+export interface FakeOptions {
+  /** Log calls into this array instead of the fake's own, so several fakes share one ordered log. */
+  calls?: FakeCall[];
+}
+
+/** An in-memory vendor for tests, with faults a test can inject into its next calls. */
+export interface Fake<T, Id extends string = string> {
+  driver: Driver;
+  /** The vendor's state. */
+  readonly state: T;
+  /** Empties the state, the remembered replies and the pending faults, and drops this fake's calls from the log. */
+  reset(): void;
+  /** Changes the vendor's state as someone at the vendor would, so the next call sees it. */
+  update(change: (state: T) => void): void;
+  /** Every call received, in order, including failed ones and repeats of an idempotency key. */
+  calls: FakeCall[];
+  /** The next call to `opId` throws `err` (default: a retryable `DriverError`) and changes nothing. */
+  failNext(opId: Id, err?: unknown): void;
+  /** The next call to `opId` takes effect, then throws once, as if its reply was lost. */
+  loseReply(opId: Id): void;
+  /** The next call to `opId` throws a retryable `DriverError` with status 429 and changes nothing. */
+  rateLimit(opId: Id): void;
+  /** The next call to `opId` waits, before it takes effect, until the returned function is called. */
+  hold(opId: Id): () => void;
+}
+
+/**
+ * A fake that holds its vendor's objects by resource type (`repository`) and import id, as
+ * `@sanoma-ai/bridge`'s `tfFake` does, with fields in the resource's shape: what a scenario's
+ * resource steps seed on a sandbox run's own fake. `put` sets the fields over the object there, or
+ * makes one; `remove` deletes it, and is nothing when there is none.
+ */
+export interface ResourceFake {
+  override(type: string, id: string, fields: Record<string, unknown>): void;
+  put(type: string, id: string, fields: Record<string, unknown>): void;
+  remove(type: string, id: string): void;
+}
+
+type Fault =
+  | { kind: "fail"; error: unknown }
+  | { kind: "loseReply" }
+  | { kind: "rateLimit" }
+  | { kind: "hold"; released: Promise<void> };
+
+/**
+ * Builds a fake vendor for a connector, for tests and demos. `ops` implements the operations
+ * against `state`, typed by the connector as `defineDriver` does. The fake adds what a real
+ * vendor does around them: a repeated idempotency key gets the first reply and changes
+ * nothing. A test can make the next call fail, lose its reply, hit a rate limit or wait.
+ */
+export function defineFake<V extends string, S extends Specs, T extends Record<string, unknown>>(
+  connector: Connector<V, S>,
+  definition: { initial: () => T; ops: (state: T) => DriverImpl<S> },
+  options: FakeOptions = {},
+): Fake<T, OpIdOf<V, S>> {
+  const state = definition.initial();
+  let replies: Record<string, unknown> = {};
+  // Replaced in place, so the object `ops` closes over stays the live state.
+  const replace = (next: T) => {
+    for (const key of Object.keys(state)) delete state[key];
+    Object.assign(state, next);
+  };
+
+  const inner = defineDriver(connector, definition.ops(state));
+  const { vendor } = inner;
+  const calls = options.calls ?? [];
+  const faults = new Map<string, Fault[]>();
+  const inject = (opId: string, fault: Fault) => {
+    if (!opId.startsWith(`${vendor}.`) || !Object.hasOwn(inner.ops, opId.slice(vendor.length + 1))) {
+      throw new Error(`fake ${vendor}: no operation ${opId}`);
+    }
+    faults.set(opId, [...(faults.get(opId) ?? []), fault]);
+  };
+
+  const ops: Record<string, DriverFn> = {};
+  for (const [key, fn] of Object.entries(inner.ops)) {
+    const opId = `${vendor}.${key}`;
+    ops[key] = async (input, call) => {
+      const { idempotencyKey, attempt } = call;
+      calls.push({ op: opId, input, at: new Date().toISOString(), idempotencyKey, attempt });
+      const fault = faults.get(opId)?.shift();
+      if (fault?.kind === "fail") throw fault.error;
+      if (fault?.kind === "rateLimit") {
+        throw new DriverError(`fake ${vendor}: ${opId} was rate limited`, {
+          retryable: true,
+          status: 429,
+          vendorCode: "rate_limited",
+        });
+      }
+      if (fault?.kind === "hold") await fault.released;
+      if (Object.hasOwn(replies, idempotencyKey)) return structuredClone(replies[idempotencyKey]);
+      const output = await fn(input, call);
+      replies[idempotencyKey] = output;
+      if (fault?.kind === "loseReply") {
+        throw new DriverError(`fake ${vendor}: the reply to ${opId} was lost`, { retryable: true });
+      }
+      return output;
+    };
+  }
+
+  return {
+    driver: { vendor, ops },
+    state,
+    update(change) {
+      change(state);
+    },
+    reset() {
+      replace(definition.initial());
+      replies = {};
+      faults.clear();
+      for (let i = calls.length - 1; i >= 0; i--) if (calls[i]?.op.startsWith(`${vendor}.`)) calls.splice(i, 1);
+    },
+    calls,
+    failNext(opId, err) {
+      const error = err ?? new DriverError(`fake ${vendor}: ${opId} failed`, { retryable: true });
+      inject(opId, { kind: "fail", error });
+    },
+    loseReply(opId) {
+      inject(opId, { kind: "loseReply" });
+    },
+    rateLimit(opId) {
+      inject(opId, { kind: "rateLimit" });
+    },
+    hold(opId) {
+      let release!: () => void;
+      inject(opId, { kind: "hold", released: new Promise<void>((resolve) => (release = resolve)) });
+      return release;
+    },
+  };
+}

package/src/fill.ts

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+import { faker } from "@faker-js/faker";
+import { fake, seed, setFaker } from "zod-schema-faker/v4";
+import { z } from "zod";
+
+// Made-up values for zod schemas: scenarios' inputs. Internal.
+
+setFaker(faker);
+
+/** Seeds the generator from a name, so one name always makes up the same values. */
+export const seedFrom = (name: string) => seed(createHash("sha256").update(name).digest().readUInt32BE(0));
+
+/** The schema's value with every field `given` does not set made up, parsed by the schema. */
+export function fill(schema: z.ZodType, given: Record<string, unknown>): unknown {
+  return schema.parse({ ...(fake(schema) as object), ...given });
+}
+
+/** An object schema's fields by name; none for any other schema. */
+export const shapeOf = (schema: z.ZodType): Record<string, z.ZodType> =>
+  schema instanceof z.ZodObject ? schema.shape : {};
+
+/** A mistake in code (ours, or a fake's), not in what it was given: thrown as it is, never reported as data. */
+export const isBug = (err: unknown) =>
+  err instanceof TypeError || err instanceof RangeError || err instanceof ReferenceError;

package/src/index.ts

@@ -0,0 +1,120 @@
+export {
+  type CallContext,
+  type Connector,
+  type ConnectorSetup,
+  type ConnectorVendor,
+  type Driver,
+  type DriverEnv,
+  type DriverFn,
+  defineConnector,
+  DriverError,
+  type Effect,
+  isOp,
+  type Op,
+  type OpSpec,
+  type ResourceGroup,
+  retryableStatus,
+  type VendorInfo,
+  withSetup,
+} from "./op.ts";
+export {
+  defineWorkflow,
+  Principal,
+  type ApprovalRequest,
+  type ApprovalResult,
+  type ApprovalState,
+  type Approver,
+  type Builtin,
+  type Ctx,
+  type SleepRequest,
+  type StepOptions,
+  type Use,
+  type WorkflowDefinition,
+} from "./define.ts";
+export {
+  compareDeclared,
+  type Declared,
+  type Declaring,
+  defineResource,
+  diffDeclared,
+  type FieldReference,
+  type References,
+  type Resource,
+  type ResourceFields,
+  type ResourceOps,
+  type ResourceSpec,
+} from "./resource.ts";
+export { defineConfig, resolveConfig, resolveDatabaseUrl, type ResolvedConfig, type SanomaConfig } from "./config.ts";
+export { type CredentialStatus, credentialsOf } from "./env.ts";
+export {
+  DRIFT_WORKFLOW,
+  type DriftDeclared,
+  type DriftField,
+  type DriftReport,
+  type DriftResult,
+  type DriftStatus,
+} from "./drift.ts";
+// readResources, which parses data files, is at `@sanoma-ai/workflows/describe`.
+export type { DeclaredResource, ResourceProblem } from "./resources.ts";
+export {
+  allow,
+  allowAll,
+  approve,
+  approvedFor,
+  type Decision,
+  definePolicy,
+  deny,
+  type Policy,
+  type PolicyCall,
+  type PolicyOp,
+  policyOpOf,
+  type RecordedDecision,
+} from "./policy.ts";
+export {
+  errorCode,
+  type ErrorCode,
+  type ErrorInfo,
+  type InputIssue,
+  invalidInput,
+  PolicyDeniedError,
+  RejectedError,
+  SanomaError,
+} from "./errors.ts";
+export {
+  jsonlLedger,
+  memoryLedger,
+  postgresLedger,
+  type LedgerBody,
+  type LedgerGroup,
+  type LedgerRecord,
+  type LedgerStore,
+} from "./ledger.ts";
+export { ApprovalMessage, APPROVALS_EVENT, decisionEventOf } from "./approvals.ts";
+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";
+// 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 {
+  approverLabel,
+  credentialReady,
+  DEFAULT_SLEEP_NAME,
+  ENDED_STATUSES,
+  errorMessage,
+  isEnded,
+  isLoopback,
+  mayDecide,
+  problemAt,
+  problemLine,
+  RUN_STATUSES,
+  type RunStatus,
+} from "./shared.ts";
+// describeConfig, with the outline and every problem lintWorkflow finds, lives at
+// `@sanoma-ai/workflows/describe`: what a UI renders from, apart from what runs. The worker reads
+// each workflow's outline too, to hold its runs to it.
+export { defineDriver, type DriverImpl, type OpIdOf } from "./op.ts";
+// Steps for Gherkin tests, as data; Cucumber runs them from `@sanoma-ai/workflows/scenario`.
+export { defineSteps, type Expect, type RunView, type Seed, type Steps } from "./steps.ts";
+// defineFake lives at `@sanoma-ai/workflows/fake`: test tooling, not runtime.