@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/dist/worker.d.ts

@@ -0,0 +1,34 @@
+import { type SanomaConfig } from "./config.ts";
+export interface Worker {
+    /**
+     * The vendors whose drivers could not run when the worker started, in the config's order: a
+     * live call to one fails, saying why (`unconfigured` in env.ts), until its variables are set.
+     * The worker names them in one line at start, unless started `quiet`.
+     */
+    readonly unconfigured: readonly string[];
+    stop(): Promise<void>;
+}
+export interface WorkerOptions {
+    /** The least severe level of the runtime's and DBOS's messages to show, for the whole process: `warn` by default. */
+    logLevel?: string;
+    /**
+     * Start without naming the vendors not configured yet (`unconfigured` still does): for a worker
+     * whose runs use the fakes alone, as `runScenarios`'s.
+     */
+    quiet?: boolean;
+    /**
+     * Make this worker's version the app's latest, so runs queued without a version come here.
+     * A brand-new version becomes the latest on its own; set this only when deliberately starting
+     * a worker on a version seen before (a rollback). Off by default, because an old instance
+     * restarting during a rolling deploy would otherwise take the new workers' runs.
+     */
+    promote?: boolean;
+}
+/**
+ * Registers the workflows, connects to Postgres and recovers any runs that were interrupted.
+ * When a driver declares variables the environment leaves unset, it first loads their stored
+ * values into `process.env` and keeps them current while it runs. It starts whether or not they
+ * are all there: it prints one line naming the vendors that lack one (`unconfigured`), and a live
+ * call to such a vendor fails, saying why, as the call's own final failure, until they are set.
+ */
+export declare function startWorker(config: SanomaConfig, options?: WorkerOptions): Promise<Worker>;

package/dist/worker.js

@@ -0,0 +1,219 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { buildCtx, isInfrastructureError } from "./call.js";
+import { dbosStatusesOf } from "./client.js";
+import { resolveConfig } from "./config.js";
+import { watchCredentials } from "./credentials.js";
+import { DBOS_DATABASE_OPTIONS, prepareDatabase } from "./db.js";
+import { credentialsOf, unconfigured, unconfiguredSummary } from "./env.js";
+import { errorInfo, parseOrThrow } from "./errors.js";
+import { entry, ownedLedger, skipped, write, writeFailure } from "./ledger.js";
+import { dbosLogger, quietIfSandbox, setLogLevel, warn } from "./log.js";
+import { lineStartsOf, readSource } from "./ast.js";
+import { callsOf, outlineWithSource } from "./outline.js";
+import { errorMessage } from "./shared.js";
+// DBOS registrations are process-wide and survive shutdown, so a name is registered once, and
+// its function reads the state of the worker running when a run starts, definition and all; the
+// run keeps that state.
+let current;
+const registered = new Set();
+/**
+ * Registers the workflows, connects to Postgres and recovers any runs that were interrupted.
+ * When a driver declares variables the environment leaves unset, it first loads their stored
+ * values into `process.env` and keeps them current while it runs. It starts whether or not they
+ * are all there: it prints one line naming the vendors that lack one (`unconfigured`), and a live
+ * call to such a vendor fails, saying why, as the call's own final failure, until they are set.
+ */
+export async function startWorker(config, options = {}) {
+    // Check everything before touching the state a running worker reads.
+    const resolved = resolveConfig(config);
+    setLogLevel(options.logLevel);
+    // The config's own, or a Postgres store made for this worker, which `stop` then closes.
+    const ledger = ownedLedger(resolved);
+    const state = {
+        app: resolved.appName,
+        ops: resolved.ops,
+        drivers: resolved.drivers,
+        fakes: resolved.fakes,
+        ...(resolved.scenarios && { scenarios: resolved.scenarios }),
+        types: resolved.types,
+        steps: resolved.steps,
+        policy: resolved.policy,
+        ledger: ledger.store,
+        workflows: resolved.workflows,
+        outlines: new Map([...resolved.workflows].map(([name, wf]) => [name, outlineOf(wf)])),
+        stopped: false,
+    };
+    const credentials = await watchCredentials(resolved.databaseUrl, resolved.driversByVendor);
+    const worker = {
+        unconfigured: [...credentialsOf(resolved.driversByVendor, (name) => process.env[name])]
+            .filter(([vendor, statuses]) => unconfigured(vendor, statuses))
+            .map(([vendor]) => vendor),
+        async stop() {
+            state.stopped = true;
+            // Each is closed whatever the one before did; the first failure is what stop throws.
+            let failed;
+            for (const close of [() => DBOS.shutdown(), () => credentials.close(), () => ledger.close()]) {
+                await close().catch((error) => (failed ??= { error }));
+            }
+            if (failed)
+                throw failed.error;
+        },
+    };
+    // Runs recovered during launch start before it returns, so they must already find this
+    // state. If starting fails, a worker still running in the process gets its own back, once
+    // DBOS has stopped: until then a run DBOS dispatches finds this state stopped, and is refused.
+    const previous = current;
+    let launched = false;
+    try {
+        for (const name of resolved.workflows.keys()) {
+            if (!registered.has(name)) {
+                register(name);
+                registered.add(name);
+            }
+        }
+        current = state;
+        // Before DBOS's pool connects, so its connections start with the database's idle-transaction
+        // timeout (`DBOS_DATABASE_OPTIONS`); once per process and database.
+        await prepareDatabase(resolved.databaseUrl);
+        DBOS.setConfig({
+            name: resolved.appName,
+            systemDatabaseUrl: resolved.databaseUrl,
+            ...DBOS_DATABASE_OPTIONS,
+            // A logger of our own replaces DBOS's OTLP log export, so only while DBOS exports none (it
+            // does on DBOS Cloud); its level is then the threshold `setLogLevel` set, DBOS's own `logLevel` unread.
+            ...(process.env.DBOS__CLOUD === "true" ? { logLevel: options.logLevel ?? "warn" } : { logger: dbosLogger }),
+            applicationVersion: resolved.version,
+        });
+        await DBOS.launch();
+        launched = true;
+        // DBOS gives runs queued without a version only to the app's latest version, which is the
+        // newest one registered. A worker started on code seen before (a rollback) is not it.
+        const latest = (await DBOS.getLatestApplicationVersion()).versionName;
+        if (latest !== resolved.version) {
+            if (options.promote)
+                await DBOS.setLatestApplicationVersion(resolved.version);
+            else {
+                warn(`this worker runs version ${resolved.version} but the app's latest is ${latest}; ` +
+                    "runs queued without a version go to the latest. Start with { promote: true } to take them here");
+            }
+        }
+        await DBOS.registerQueue(resolved.queueName);
+        await warnAboutStrandedRuns(resolved);
+        const summary = unconfiguredSummary(worker.unconfigured, resolved.driversByVendor.size);
+        if (summary && !options.quiet)
+            warn(summary);
+    }
+    catch (err) {
+        // Once DBOS is launched, the caller gets no worker to stop: stop it here, so no run goes on
+        // in a worker nobody holds, and the next startWorker launches afresh.
+        let stopFailed;
+        if (launched)
+            await worker.stop().catch((error) => (stopFailed = { error }));
+        else {
+            await credentials
+                .close()
+                .catch((e) => warn(`closing the credentials listener failed: ${errorMessage(e)}`));
+        }
+        current = previous;
+        if (stopFailed) {
+            throw new AggregateError([err, stopFailed.error], `${errorMessage(err)} (and stopping DBOS failed too: ${errorMessage(stopFailed.error)})`, { cause: err });
+        }
+        throw err;
+    }
+    return worker;
+}
+/**
+ * The workflow's outline, read from its file, which every run is held to. A workflow whose
+ * outline cannot be read does not start: nothing could say where its calls are.
+ */
+function outlineOf(wf) {
+    const { outline, source } = outlineWithSource(wf, readSource(wf.file));
+    if ("error" in outline) {
+        throw new Error(`Workflow "${wf.name}" cannot be outlined, so its runs could not be held to its code: ${outline.error}`);
+    }
+    return { file: outline.file, lineStarts: lineStartsOf(source), calls: callsOf(outline.nodes) };
+}
+/**
+ * Warns about unfinished runs this worker will never pick up: started on another version of
+ * the app, or queued on another queue (such as the single "sanoma" queue before queues were
+ * named per app, or the sandbox queue before sandbox runs went on the app's).
+ */
+async function warnAboutStrandedRuns({ appName, version, queueName }) {
+    const runs = await DBOS.listWorkflows({
+        status: dbosStatusesOf("queued", "running"),
+        applicationName: appName,
+        loadInput: false,
+        loadOutput: false,
+    });
+    const otherVersion = runs.filter((r) => r.applicationVersion && r.applicationVersion !== version);
+    // Recovery moves a worker's own runs to DBOS's internal queues, which are fine.
+    const otherQueue = runs.filter((r) => !otherVersion.includes(r) && r.queueName && r.queueName !== queueName && !r.queueName.startsWith("_dbos_"));
+    if (!otherVersion.length && !otherQueue.length)
+        return;
+    const ids = [...otherVersion, ...otherQueue].map((r) => r.workflowID);
+    warn(`${otherVersion.length} unfinished run(s) of "${appName}" belong to another version and ${otherQueue.length} ` +
+        `wait on another queue, so this worker (version ${version}, queue ${queueName}) will not run them: ` +
+        `${ids.slice(0, 5).join(", ")}${ids.length > 5 ? ", …" : ""}. Run the version that started them, or move each ` +
+        `with DBOSClient.forkWorkflow(id, step, { applicationVersion: "${version}", queueName: "${queueName}" }) ` +
+        `and cancel the original; resumeWorkflow(id, { queueName: "${queueName}" }) moves a run on this version to this queue.`);
+}
+/** Registers the name with DBOS: its runs take the definition of that name from the running worker. */
+function register(name) {
+    DBOS.registerWorkflow((args) => quietIfSandbox(args.sandbox !== undefined, () => runWorkflow(name, args)), {
+        name,
+    });
+}
+/** One run of the workflow registered as `name`, on the state of the worker running when it starts. */
+async function runWorkflow(name, { input, startedBy, sandbox }) {
+    const state = current;
+    // A stopped worker's state stays current while DBOS shuts down.
+    if (!state || state.stopped)
+        throw new Error(`Run of "${name}" started with no worker running`);
+    const wf = state.workflows.get(name);
+    const outline = state.outlines.get(name);
+    // Registered by an earlier worker in this process, whose config had it; this one's has not.
+    if (!wf || !outline)
+        throw new Error(`Run of "${name}" refused: this worker's config has no workflow of that name`);
+    const run = {
+        id: DBOS.workflowID,
+        workflow: wf.name,
+        actor: startedBy,
+        ...(sandbox === undefined ? {} : { sandbox }),
+        approvals: [],
+        seq: 0,
+        tail: Promise.resolve(),
+        inAll: false,
+        ended: false,
+        outline,
+        state,
+    };
+    await write(run, entry(run, { type: "run.started", input }));
+    let output;
+    try {
+        try {
+            // The one parse of the input: the client checked it, but sent it as given.
+            const parsed = parseOrThrow(wf.input, input, `The input does not match ${wf.name}'s schema`);
+            if (sandbox !== undefined) {
+                // Imported here, so a live worker never loads the Gherkin parser or faker.
+                const { seedSandbox } = await import("./sandbox.js");
+                await seedSandbox(run, sandbox);
+            }
+            output = await wf.run(buildCtx(wf, run), parsed);
+        }
+        finally {
+            // Before the outcome is written: a call still queued must find the run ended.
+            run.ended = true;
+        }
+    }
+    catch (err) {
+        const record = entry(run, { type: "run.failed", error: errorInfo(err) });
+        if (isInfrastructureError(err, state))
+            skipped(record, `the run was interrupted (${errorMessage(err)})`);
+        else
+            await writeFailure(run, record, err);
+        throw err;
+    }
+    await write(run, entry(run, { type: "run.finished", output }));
+    return output;
+}
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}

package/oxlint.json

@@ -0,0 +1,128 @@
+{
+  "overrides": [
+    {
+      "files": ["workflows/**", "policies/**"],
+      "rules": {
+        "no-restricted-globals": [
+          "error",
+          {
+            "name": "Date",
+            "message": "Workflows are replayed: use `await ctx.now()` for the time and `ctx.sleep({ until })` to wait for a date."
+          },
+          {
+            "name": "fetch",
+            "message": "A workflow must call vendors through ctx, so the policy sees every call: use a connector operation listed in `uses`."
+          },
+          {
+            "name": "WebSocket",
+            "message": "A workflow must call vendors through ctx, so the policy sees every call: use a connector operation listed in `uses`."
+          },
+          {
+            "name": "XMLHttpRequest",
+            "message": "A workflow must call vendors through ctx, so the policy sees every call: use a connector operation listed in `uses`."
+          },
+          { "name": "setTimeout", "message": "Workflows are replayed: use `ctx.sleep`." },
+          { "name": "setInterval", "message": "Workflows are replayed: use `ctx.sleep` in a loop." },
+          { "name": "setImmediate", "message": "Workflows are replayed: use `ctx.sleep`." },
+          { "name": "queueMicrotask", "message": "Workflows are replayed: await the work directly." },
+          { "name": "performance", "message": "Workflows are replayed: use `await ctx.now()`." },
+          {
+            "name": "process",
+            "message": "Workflows are replayed: pass configuration as workflow input; drivers read the environment."
+          },
+          { "name": "crypto", "message": "Workflows are replayed: derive ids from `ctx.runId`." },
+          {
+            "name": "require",
+            "message": "Import from `@sanoma-ai/workflows`, a `@sanoma-ai/connector-*` package, zod or a file in this directory."
+          },
+          { "name": "eval", "message": "Not allowed in a workflow or policy." },
+          { "name": "Function", "message": "Not allowed in a workflow or policy." },
+          {
+            "name": "globalThis",
+            "message": "Reaching globals through globalThis would bypass these rules: use `ctx`."
+          },
+          { "name": "global", "message": "Reaching globals through global would bypass these rules: use `ctx`." }
+        ],
+        "no-restricted-properties": [
+          "error",
+          {
+            "object": "Math",
+            "property": "random",
+            "message": "Workflows are replayed: derive values from `ctx.runId` or the input."
+          },
+          {
+            "object": "Promise",
+            "property": "all",
+            "message": "Calls through ctx run one at a time; declare a fan-out with `ctx.all([...])` so the ledger and the graph show it."
+          },
+          {
+            "object": "Promise",
+            "property": "allSettled",
+            "message": "Calls through ctx run one at a time; declare a fan-out with `ctx.all([...])` so the ledger and the graph show it."
+          },
+          {
+            "object": "Promise",
+            "property": "race",
+            "message": "Calls through ctx run one at a time, so nothing races: pick one call, or sleep and then check."
+          },
+          {
+            "object": "Promise",
+            "property": "any",
+            "message": "Calls through ctx run one at a time, so nothing races: pick one call, or sleep and then check."
+          }
+        ],
+        "no-restricted-imports": [
+          "error",
+          {
+            "paths": [
+              {
+                "name": "@sanoma-ai/testing",
+                "message": "Fakes and test helpers belong in tests. A workflow must call vendors through ctx, so the policy sees every call."
+              },
+              {
+                "name": "@sanoma-ai/app",
+                "message": "The app starts runs and decides approvals: a workflow could approve itself."
+              },
+              {
+                "name": "@sanoma-ai/workflows",
+                "allowImportNames": [
+                  "defineWorkflow",
+                  "definePolicy",
+                  "allow",
+                  "deny",
+                  "approve",
+                  "approvedFor",
+                  "allowAll",
+                  "mayDecide",
+                  "errorCode",
+                  "z"
+                ],
+                "allowTypeImports": true,
+                "message": "A workflow or policy imports only these and types from @sanoma-ai/workflows: the rest (SanomaClient, startWorker, the ledger stores, config helpers) could start runs, approve its own approvals, forge the ledger or read credentials. Ask for approval with `ctx.approval`."
+              }
+            ],
+            "patterns": [
+              {
+                "group": [
+                  "@sanoma-ai/connector-*/fake",
+                  "@sanoma-ai/connector-*/driver",
+                  "@sanoma-ai/workflows/describe",
+                  "@sanoma-ai/workflows/fake",
+                  "@sanoma-ai/workflows/plugin",
+                  "@sanoma-ai/workflows/scenario",
+                  "@sanoma-ai/workflows/scenarios"
+                ],
+                "message": "A workflow must call vendors through ctx, so the policy sees every call: import the connector itself, `@sanoma-ai/connector-<vendor>`."
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "files": ["resources/**"],
+      "jsPlugins": ["./dist/plugin.js"],
+      "rules": { "sanoma/data-file": "error" }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@sanoma-ai/workflows",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Business processes as TypeScript functions, run durably on DBOS",
+  "keywords": [
+    "approvals",
+    "business-as-code",
+    "dbos",
+    "durable-execution",
+    "sanoma",
+    "workflows"
+  ],
+  "homepage": "https://github.com/Sanoma-AI/sanoma/tree/main/packages/workflows#readme",
+  "bugs": "https://github.com/Sanoma-AI/sanoma/issues",
+  "license": "FSL-1.1-ALv2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sanoma-AI/sanoma.git",
+    "directory": "packages/workflows"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/AGENTS.md",
+    "oxlint.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./describe": {
+      "types": "./dist/describe.d.ts",
+      "default": "./dist/describe.js"
+    },
+    "./fake": {
+      "types": "./dist/fake.d.ts",
+      "default": "./dist/fake.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./scenario": {
+      "types": "./dist/scenario.d.ts",
+      "default": "./dist/scenario.js"
+    },
+    "./scenarios": {
+      "types": "./dist/scenarios.d.ts",
+      "default": "./dist/scenarios.js"
+    },
+    "./shared": {
+      "types": "./dist/shared.d.ts",
+      "default": "./dist/shared.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cucumber/cucumber": "13.3.0",
+    "@cucumber/cucumber-expressions": "^20.1.0",
+    "@cucumber/messages": "^34.2.1",
+    "@cucumber/query": "16.1.1",
+    "@dbos-inc/dbos-sdk": "^5.2.11",
+    "@faker-js/faker": "^10.6.0",
+    "oxc-parser": "^0.153.0",
+    "pg": "^8.23.1",
+    "randexp": "^0.5.3",
+    "zod-schema-faker": "^2.1.2"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.23.1",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "zod": "^4"
+  },
+  "engines": {
+    "node": "24 || >=26"
+  },
+  "//": "randexp is a dependency only because zod-schema-faker, which makes up scenario inputs, needs it as a peer.",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "watch": "tsc -p tsconfig.build.json --watch --preserveWatchOutput"
+  }
 }

package/src/approvals.ts

@@ -0,0 +1,157 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { z } from "zod";
+import { type ApprovalRequest, type ApprovalResult, type ApprovalState, notApprover, Principal } from "./define.ts";
+import { RejectedError } from "./errors.ts";
+import { entry, write } from "./ledger.ts";
+import { warn } from "./log.ts";
+import type { Placed } from "./call.ts";
+import type { Run } from "./run.ts";
+import { approverLabel, mayDecide } from "./shared.ts";
+
+// The wire contract between a run waiting on approvals and whoever decides them. The client
+// imports this file and never the worker's.
+
+/** The DBOS event a run publishes its approvals on, as `ApprovalState[]`. */
+export const APPROVALS_EVENT = "approvals";
+/** The `recv` topic a decision on an approval is sent to. */
+export const topicOf = (approvalId: string) => approvalId;
+/** The DBOS event an approval's decision is published on, as its decided `ApprovalState`, once made. */
+export const decisionEventOf = (approvalId: string) => `approval:${approvalId}`;
+/**
+ * The idempotency key a decision message is sent with, so a retried send queues it once. DBOS
+ * scopes the key per run, not per topic, so it names the approval too: one message id reused
+ * for two approvals of a run would otherwise drop the second send.
+ */
+export const messageKeyOf = (approvalId: string, messageId: string) => `${approvalId}:${messageId}`;
+
+/**
+ * A decision, as sent to a run. `id` names the message, so whoever sent it can tell whether
+ * the run decided with it or with another; `SanomaClient.decide` sets one.
+ */
+export const ApprovalMessage = z.object({
+  id: z.string().optional(),
+  decision: z.enum(["approve", "reject"]),
+  by: Principal,
+  note: z.string().optional(),
+});
+export type ApprovalMessage = z.infer<typeof ApprovalMessage>;
+
+const statusOf = (decision: ApprovalMessage["decision"]) => (decision === "approve" ? "approved" : "rejected");
+
+/** The sender's id, from a message that may not be a valid decision. */
+function senderOf(raw: unknown): string | undefined {
+  const by = typeof raw === "object" && raw !== null ? (raw as { by?: unknown }).by : undefined;
+  const id = typeof by === "object" && by !== null ? (by as { id?: unknown }).id : undefined;
+  return typeof id === "string" && id ? id : undefined;
+}
+
+/** An approval request as checked: who may decide it, and the operations it covers, by id. */
+export interface CheckedApproval extends Omit<ApprovalRequest, "covers"> {
+  covers: string[];
+}
+
+/** A policy's hold: the call held, and the ledger `seq` its `op.called` record takes. */
+export interface HeldCall {
+  op: string;
+  seq: number;
+  input: unknown;
+}
+
+/**
+ * Waits, durably, for a decision from someone who may make it. Throws `RejectedError` on a
+ * rejection. Without `held`, the workflow asked (`ctx.approval`); with it, the policy did, and
+ * `place` is the held call's outline node and name.
+ */
+export async function awaitApproval(
+  run: Run,
+  title: string,
+  req: CheckedApproval,
+  place: Placed,
+  held?: HeldCall,
+): Promise<ApprovalResult> {
+  const { covers } = req;
+  const all = run.approvals;
+  const state: ApprovalState = {
+    id: `approval-${all.length + 1}`,
+    title,
+    approver: req.approver,
+    ...(req.links === undefined ? {} : { links: req.links }),
+    ...(req.details === undefined ? {} : { details: req.details }),
+    requestedBy: held ? "policy" : "workflow",
+    covers,
+    ...(held ? { op: held.op, opSeq: held.seq, input: held.input } : {}),
+    status: "pending",
+    requestedAt: 0,
+    refused: [],
+  };
+  all.push(state);
+  state.requestedAt = await DBOS.now();
+  await DBOS.setEvent(APPROVALS_EVENT, all);
+  await write(
+    run,
+    entry(
+      run,
+      {
+        type: "approval.requested",
+        approval: state.id,
+        ...place,
+        title,
+        approver: state.approver,
+        requestedBy: state.requestedBy,
+        covers,
+        ...(held ? { op: held.op, opSeq: held.seq } : {}),
+      },
+      { key: state.id, at: state.requestedAt },
+    ),
+  );
+  for (;;) {
+    const raw = await DBOS.recv<unknown>(topicOf(state.id), { timeoutSeconds: 24 * 60 * 60 });
+    if (raw === null || raw === undefined) {
+      warn(`run ${run.id}: approval ${state.id} ("${title}") is still waiting for ${approverLabel(state.approver)}`);
+      continue;
+    }
+    const at = await DBOS.now();
+    const parsed = ApprovalMessage.safeParse(raw);
+    const msg = parsed.success ? parsed.data : undefined;
+    if (!msg || !mayDecide(state, msg.by)) {
+      const by = msg?.by.id ?? senderOf(raw);
+      const reason = msg ? notApprover(state, msg.by) : "not a valid decision message";
+      state.refused.push({
+        ...(by === undefined ? {} : { by }),
+        ...(msg?.id === undefined ? {} : { id: msg.id }),
+        at,
+        reason,
+      });
+      await DBOS.setEvent(APPROVALS_EVENT, all);
+      await write(
+        run,
+        entry(
+          run,
+          { type: "approval.refused", approval: state.id, ...(by === undefined ? {} : { by }), reason },
+          { key: `${state.id}:refused:${state.refused.length}`, at },
+        ),
+      );
+      continue;
+    }
+    Object.assign(state, {
+      status: statusOf(msg.decision),
+      decidedBy: msg.by.id,
+      decidedAt: at,
+      note: msg.note,
+      decidedWith: msg.id,
+    });
+    // The list first, then the ledger, then the decision event: whoever sees the event sees both.
+    await DBOS.setEvent(APPROVALS_EVENT, all);
+    await write(
+      run,
+      entry(
+        run,
+        { type: "approval.decided", approval: state.id, decision: msg.decision, by: msg.by.id, note: msg.note },
+        { key: state.id, at },
+      ),
+    );
+    await DBOS.setEvent(decisionEventOf(state.id), state);
+    if (msg.decision === "reject") throw new RejectedError(title, msg.by, msg.note, state.id);
+    return { approvedBy: msg.by.id, at, note: msg.note };
+  }
+}