@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/src/expectations.ts

@@ -0,0 +1,191 @@
+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";
+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, { status: 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 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 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 {
+  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}`;
+  if (!("declared" in e)) return undefined;
+  return "status" in e ? driftDetail(e, end) : applyDetail(e, end);
+}

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/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

@@ -0,0 +1,143 @@
+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 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";
+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 {
+  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";
+// `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 { 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 {
+  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.