@sanoma-ai/workflows 0.6.0 → 0.7.1

package/src/deadlines.ts

@@ -0,0 +1,228 @@
+import { randomUUID } from "node:crypto";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { dbosStatusesOf } from "./client.ts";
+import type { Db } from "./db.ts";
+import { recordWakeupError, recordWakeupRegistration, recordWakeupStop } from "./db.ts";
+import type { ResolvedConfig } from "./config.ts";
+import { warn } from "./log.ts";
+import type { CallContext, DriverFn, Op } from "./op.ts";
+import type { Secrets } from "./secret.ts";
+import { errorMessage, WAKEUP_AGENT } from "./shared.ts";
+import type { WakeupRegistration } from "./wakeup.ts";
+
+// What a worker knows of its own runs that DBOS cannot tell it: which are executing and which are
+// blocked in a `ctx` wait, and until when. DBOS sees both as PENDING. A worker that registers a
+// wakeup stops itself once nothing can run before the next deadline (`stopWhenIdle`).
+
+/** What a run blocked in a `ctx` wait waits for: a sleep, until its deadline, or an approval's decision, which has none. */
+export type Wait = { kind: "sleep"; until: number } | { kind: "approval" };
+
+/** A deadline besides the sleeping runs', such as a schedule's next fire; undefined for none. */
+export type DeadlineSource = () => Date | undefined;
+
+/** What a worker shows of its runs' deadlines (`Worker.deadlines`). */
+export interface Deadlines {
+  /**
+   * Adds a deadline besides the sleeping runs', read each time `nextDeadline` is: a fixed time
+   * (a schedule's next fire), never one counted from now, which would never let the worker stop.
+   */
+  addSource(source: DeadlineSource): void;
+  /** The earliest deadline: a sleeping run's `until`, or a source's. Undefined when there is none. */
+  nextDeadline(): Date | undefined;
+  /** How many runs are inside their body and in no wrapped wait: executing, or replaying. */
+  readonly busy: number;
+  /** What the run waits for while it is blocked in a wrapped wait; undefined otherwise. */
+  waitOf(runId: string): Wait | undefined;
+}
+
+/** The registry a worker's runs report to, through `running` and `waiting`. */
+export interface DeadlineRegistry extends Deadlines {
+  /** Runs a run's body, counted busy but while it is in `waiting`. */
+  running<T>(runId: string, body: () => Promise<T>): Promise<T>;
+  /** Runs `fn`, the live wait itself (`DBOS.sleep`, `DBOS.recv`), with the run counted as waiting for `wait`. */
+  waiting<T>(runId: string, wait: Wait, fn: () => Promise<T>): Promise<T>;
+}
+
+/** A registry of its own for each worker: two copies of the package in one process never share one. */
+export function deadlineRegistry(): DeadlineRegistry {
+  // Each run inside its body, with what it waits for while it is blocked.
+  const runs = new Map<string, Wait | undefined>();
+  const sources: DeadlineSource[] = [];
+  return {
+    addSource(source) {
+      sources.push(source);
+    },
+    nextDeadline() {
+      const times = [
+        ...[...runs.values()].flatMap((wait) => (wait?.kind === "sleep" ? [wait.until] : [])),
+        ...sources.flatMap((source) => source()?.getTime() ?? []),
+      ];
+      return times.length ? new Date(Math.min(...times)) : undefined;
+    },
+    get busy() {
+      return [...runs.values()].filter((wait) => wait === undefined).length;
+    },
+    waitOf: (runId) => runs.get(runId),
+    async running(runId, body) {
+      runs.set(runId, undefined);
+      try {
+        return await body();
+      } finally {
+        runs.delete(runId);
+      }
+    },
+    async waiting(runId, wait, fn) {
+      // Every wait is inside a run's body; one outside is left uncounted rather than counted busy for good.
+      if (!runs.has(runId)) return fn();
+      runs.set(runId, wait);
+      try {
+        return await fn();
+      } finally {
+        if (runs.has(runId)) runs.set(runId, undefined);
+      }
+    },
+  };
+}
+
+/** The worker `idle` asks about: the app, the version it runs, and its queue. */
+export type IdleScope = Pick<ResolvedConfig, "appName" | "version" | "queueName">;
+
+/**
+ * True when a run on `queue` (none for a run started outside a queue) is this worker's to run: on
+ * its own queue, or on one of DBOS's, where recovery puts runs.
+ */
+export const onOwnQueue = (queue: string | undefined, queueName: string): boolean =>
+  !queue || queue === queueName || queue.startsWith("_dbos_");
+
+/**
+ * True when nothing this worker would run can run within `horizonMs`: no run of its is executing
+ * or replaying; none of its version is queued (or queued without one, while it is the latest) on
+ * its queue or DBOS's own (recovery queues there); each PENDING run of its version is blocked in
+ * a wrapped wait; and the next deadline is past the horizon. A run of another version or queue
+ * is not this worker's to run, so it never holds the worker up.
+ */
+export async function idle(deadlines: Deadlines, scope: IdleScope, horizonMs: number): Promise<boolean> {
+  if (deadlines.busy > 0) return false;
+  const next = deadlines.nextDeadline();
+  if (next && next.getTime() <= Date.now() + horizonMs) return false;
+  const runs = await DBOS.listWorkflows({
+    applicationName: scope.appName,
+    status: dbosStatusesOf("queued", "running"),
+    loadInput: false,
+    loadOutput: false,
+  });
+  const ours = runs.filter((r) => onOwnQueue(r.queueName, scope.queueName));
+  if (
+    ours.some(
+      (r) => r.status === "PENDING" && r.applicationVersion === scope.version && !deadlines.waitOf(r.workflowID),
+    )
+  )
+    return false;
+  const queued = ours.filter((r) => r.status !== "PENDING");
+  if (queued.some((r) => r.applicationVersion === scope.version)) return false;
+  // DBOS gives a run queued without a version to the app's latest version.
+  if (!queued.some((r) => !r.applicationVersion)) return true;
+  return (await DBOS.getLatestApplicationVersion()).versionName !== scope.version;
+}
+
+/** What `onStopped` hears when the worker stopped itself: the deadline it registered, null for none. */
+export interface SelfStop {
+  at: string | null;
+}
+
+/** What the stop rule acts on: the wakeup row, the wakeup's register operation, and the worker. */
+export interface StopRule {
+  /** The wakeup row's database. */
+  db: () => Promise<Db>;
+  /** The declared wakeup's binding, else its declaration's id: what scopes a registration's idempotency key to this instance. */
+  wakeup: string;
+  /** The wakeup type's register operation, and its driver (none when the connector attaches none). */
+  register: { op: Op; fn: DriverFn | undefined };
+  secrets: Secrets;
+  deadlines: Deadlines;
+  idle: () => Promise<boolean>;
+  everyMs: number;
+  /** Stops the worker (`Worker.stop`). */
+  stop: () => Promise<void>;
+  onStopped?: ((stopped: SelfStop) => void) | undefined;
+}
+
+/**
+ * Checks every `everyMs` whether the worker is `idle`; when it is, registers the next deadline
+ * with the wakeup, replacing what it held (none when there is no deadline at all), and stops the
+ * worker, then tells `onStopped`. A failed registration is recorded on the row and logged once for
+ * each new message, and the worker keeps running: the next check tries again. A run that arrives
+ * while it registers keeps the worker up, since the worker must be idle twice, with the same
+ * deadline, before it stops. `close` ends the checks.
+ */
+export function stopWhenIdle(rule: StopRule): { close(): void } {
+  let closed = false;
+  let timer: NodeJS.Timeout | undefined;
+  let lastProblem: string | undefined;
+  const problem = (message: string) => {
+    if (message !== lastProblem) warn(message);
+    lastProblem = message;
+  };
+
+  const tryStop = async (): Promise<boolean> => {
+    if (!(await rule.idle())) return false;
+    const next = rule.deadlines.nextDeadline();
+    const at = next?.toISOString() ?? null;
+    const db = await rule.db();
+    if (at !== null) {
+      try {
+        await registerWakeup(rule, { at });
+      } catch (err) {
+        const message = errorMessage(err);
+        await recordWakeupError(db, message);
+        problem(`could not register the wakeup at ${at}, so the worker keeps running: ${message}`);
+        return false;
+      }
+      await recordWakeupRegistration(db, at);
+    }
+    lastProblem = undefined;
+    if (closed || !(await rule.idle()) || rule.deadlines.nextDeadline()?.toISOString() !== next?.toISOString())
+      return false;
+    await recordWakeupStop(db);
+    await rule.stop().catch((err: unknown) => warn(`the worker could not stop cleanly: ${errorMessage(err)}`));
+    rule.onStopped?.({ at });
+    return true;
+  };
+
+  const check = async () => {
+    timer = undefined;
+    if (closed) return;
+    const stopped = await tryStop().catch((err: unknown) => {
+      problem(`could not check whether the worker may stop: ${errorMessage(err)}`);
+      return false;
+    });
+    if (!stopped && !closed) schedule();
+  };
+  const schedule = () => {
+    timer = setTimeout(() => void check(), rule.everyMs);
+    timer.unref();
+  };
+  schedule();
+  return {
+    close() {
+      closed = true;
+      clearTimeout(timer);
+    },
+  };
+}
+
+/**
+ * Calls the wakeup's register operation, as `SanomaClient.call` calls a driver: its input parsed,
+ * a `CallContext` of the runtime's, and no ledger record, which is a run's.
+ */
+export async function registerWakeup(
+  { register: { op, fn }, secrets, wakeup }: Pick<StopRule, "register" | "secrets" | "wakeup">,
+  registration: WakeupRegistration,
+) {
+  if (!fn) throw new Error(`${op.id} has no driver: the connector package must attach one`);
+  // Fresh each time: a repeat of an earlier `at` after another registration must re-arm it, so no
+  // two registrations share a key (real drivers never dedupe on it anyway).
+  const key = `wakeup:${wakeup}:${randomUUID()}`;
+  const context: CallContext = { idempotencyKey: key, runId: key, opId: op.id, attempt: 1, secrets, by: WAKEUP_AGENT };
+  await fn(op.input.parse(registration), context);
+}

package/src/define.ts

@@ -92,12 +92,23 @@ export interface ApprovalState extends Omit<ApprovalRequest, "covers"> {
   input?: unknown;
   /** For a policy request: the policies that held the call, by id, when the policy names them. */
   reasons?: string[];
-  status: "pending" | "approved" | "rejected";
+  /**
+   * `withdrawn`: it no longer stands, as when its change got a new commit. A pending approval is
+   * withdrawn by a message (`SanomaClient.withdraw`), an approved one by its run
+   * (`withdrawApprovals`); either way it lets nothing through and takes no decision.
+   */
+  status: "pending" | "approved" | "rejected" | "withdrawn";
+  /** Why it was withdrawn, once it is. */
+  withdrawnReason?: string;
+  /** When it was withdrawn, once it is. */
+  withdrawnAt?: number;
+  /** Who withdrew it, when someone did rather than its run (`withdrawApprovals`). */
+  withdrawnBy?: string;
   requestedAt: number;
   decidedBy?: string;
   decidedAt?: number;
   note?: string;
-  /** The `id` of the decision message the run decided with, when it had one. */
+  /** The `id` of the decision or withdrawal message the run decided with, when it had one. */
   decidedWith?: string;
   /** Set when the run's own actor decided it: nobody else could (`mayDecide`). */
   alone?: true;
@@ -174,7 +185,7 @@ type CtxOps<O extends Op> = {
 };
 
 interface ApprovalCtx {
-  /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection. */
+  /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection, `WithdrawnError` on a withdrawal. */
   approval(title: string, request: ApprovalRequest): Promise<ApprovalResult>;
 }
 
@@ -235,11 +246,19 @@ export function jsonSchemaOf(
   });
 }
 
+/**
+ * How a workflow starts: `manual` (by hand, or from code), or on a schedule, `schedule` a cron
+ * expression of five fields (minute, hour, day of month, month, day of week) read in `timezone`,
+ * an IANA time zone (`Europe/Amsterdam`), UTC without one. A scheduled run is started by the
+ * runtime's `schedule` agent with the input `{}`, as the policy allows; it can still be started by hand.
+ */
+export type Trigger = "manual" | { readonly schedule: string; readonly timezone?: string };
+
 export interface WorkflowDefinition<U extends readonly Use[] = readonly Use[], S extends z.ZodType = z.ZodType> {
   readonly kind: "workflow";
   readonly name: string;
   readonly title?: string;
-  readonly trigger: "manual";
+  readonly trigger: Trigger;
   readonly input: S;
   /** Every operation and built-in the workflow may call. `ctx` is built from this list and nothing else. */
   readonly uses: U;
@@ -260,6 +279,13 @@ export function defineWorkflow<const U extends readonly Use[], S extends z.ZodTy
   if (!/^[a-z][a-z0-9-]*$/.test(def.name)) {
     throw new Error(`Workflow name "${def.name}" must be lowercase letters, digits and dashes`);
   }
+  checkTrigger(def.name, def.trigger);
+  // A scheduled run starts with no input of its own.
+  if (def.trigger !== "manual" && !acceptsEmpty(def.input)) {
+    throw new Error(
+      `Workflow "${def.name}": a scheduled run starts with the input {}, which its input schema refuses: make each field optional or give it a default`,
+    );
+  }
   const file = callerFile();
   if (file === undefined) {
     throw new Error(
@@ -270,6 +296,47 @@ export function defineWorkflow<const U extends readonly Use[], S extends z.ZodTy
   return Object.freeze({ kind: "workflow", ...def, file });
 }
 
+/** True when `{}` parses: a schema zod can check only asynchronously is taken as accepting it, and the run parses it. */
+function acceptsEmpty(schema: z.ZodType): boolean {
+  try {
+    return schema.safeParse({}).success;
+  } catch {
+    return true;
+  }
+}
+
+/** Throws what is wrong with a workflow's `trigger`: not `manual` or a schedule, five fields, in a time zone there is. */
+function checkTrigger(name: string, trigger: unknown): void {
+  if (trigger === "manual") return;
+  const { schedule, timezone } = (typeof trigger === "object" && trigger !== null ? trigger : {}) as {
+    schedule?: unknown;
+    timezone?: unknown;
+  };
+  if (typeof schedule !== "string") {
+    throw new Error(`Workflow "${name}": its trigger is "manual" or { schedule, timezone? }`);
+  }
+  if (schedule.trim().split(/\s+/).length !== 5) {
+    throw new Error(
+      `Workflow "${name}": its schedule "${schedule}" is a cron expression of five fields: minute, hour, day of month, month, day of week`,
+    );
+  }
+  if (timezone !== undefined && !isTimeZone(timezone)) {
+    throw new Error(
+      `Workflow "${name}": its timezone "${String(timezone)}" is no IANA time zone, such as "Europe/Amsterdam"`,
+    );
+  }
+}
+
+const isTimeZone = (zone: unknown): boolean => {
+  // An offset (`+05:30`), which Intl takes too, is no IANA zone name.
+  if (typeof zone !== "string" || /^[+-]/.test(zone)) return false;
+  try {
+    return Boolean(new Intl.DateTimeFormat("en", { timeZone: zone }));
+  } catch {
+    return false;
+  }
+};
+
 /**
  * The file of the code that called the function calling this one (`defineWorkflow`'s caller),
  * from V8's call sites, as a path; undefined where there is none.

package/src/demo.ts

@@ -0,0 +1,87 @@
+import type { SanomaClient } from "./client.ts";
+import type { ResolvedConfig } from "./config.ts";
+import { DATA_TABLE } from "./db.ts";
+import { applyGivens } from "./sandbox.ts";
+import { loadScenarios, type Moment } from "./scenario.ts";
+import { memorySecrets } from "./secret.ts";
+import { errorMessage } from "./shared.ts";
+
+/*
+ * A demo: a company repo run on its connectors' fakes, with the world its scenarios describe.
+ * Re-exported from `@sanoma-ai/workflows/scenarios`, server-side, since it loads Cucumber.
+ */
+
+/** What the last `reseed` of an instance did: what the demo's banner shows. */
+export interface DemoState {
+  /** When it was seeded, as an ISO timestamp. */
+  seededAt: string;
+  /** The worlds applied, by scenario name. */
+  worlds: string[];
+  /** Each moment started and left waiting: who it is for, where they land, its scenario and its run. */
+  moments: (Moment & { scenario: string; runId: string })[];
+  /** What could not be done, one line each: a feature file that did not load, a world or a moment that failed. */
+  problems: string[];
+}
+
+/** Each instance's last reseed, by its resolution. */
+const states = new WeakMap<ResolvedConfig, DemoState>();
+
+/**
+ * Seeds the demo instance afresh: empties the collections' table, resets the instance's fakes,
+ * applies every world (a scenario with no `When`) to the instance (`applyGivens`: its records
+ * saved through the collections' driver, its vendor objects put in the fakes), then starts each
+ * moment as a sandbox run by its person, left undriven, so its first approval waits for them.
+ * `resolved` is the resolution the worker and `client` run on, made with `fakes: "instance"`.
+ * A world or a moment that fails is a problem in the state it returns, and the rest go on.
+ */
+export async function reseed(client: SanomaClient, resolved: ResolvedConfig): Promise<DemoState> {
+  const fakes = resolved.instanceFakes;
+  if (!fakes) throw new Error('reseed seeds an instance on fakes: resolve its config with `fakes: "instance"`');
+  // Read first, so scenarios that cannot be read at all leave the instance as it was.
+  const { scenarios, errors } = await loadScenarios(resolved);
+  if (resolved.dataStore) await (await resolved.dataStore.db()).query(`TRUNCATE ${DATA_TABLE}`);
+  for (const fake of fakes.values()) fake.reset();
+  const state: DemoState = {
+    seededAt: new Date().toISOString(),
+    worlds: [],
+    moments: [],
+    problems: errors.map((e) => e.message),
+  };
+  const secrets = memorySecrets();
+  for (const world of scenarios.filter((s) => s.workflow === undefined)) {
+    try {
+      await applyGivens(world, {
+        kind: "instance",
+        drivers: resolved.drivers,
+        fakes,
+        ops: resolved.ops,
+        call: (i, opId) => ({
+          idempotencyKey: `world:${world.name}:${i}`,
+          runId: `world:${world.name}`,
+          opId,
+          attempt: 1,
+          secrets,
+          // Who its records are by: whoever it says is acting, else the runtime's own agent.
+          by: world.startedBy ?? "scenarios",
+        }),
+      });
+      state.worlds.push(world.name);
+    } catch (err) {
+      state.problems.push(`world "${world.name}": ${errorMessage(err)}`);
+    }
+  }
+  for (const s of scenarios) {
+    if (!s.moment || s.workflow === undefined) continue;
+    try {
+      const runId = await client.start(s.workflow, s.input, { sandbox: s.name, startedBy: s.moment.person });
+      state.moments.push({ ...s.moment, scenario: s.name, runId });
+    } catch (err) {
+      state.problems.push(`moment "${s.name}": ${errorMessage(err)}`);
+    }
+  }
+  states.set(resolved, state);
+  return state;
+}
+
+/** What the instance's last `reseed` did, or undefined before its first. */
+export const demoState = (resolved: ResolvedConfig): DemoState | undefined => states.get(resolved);

package/src/describe.ts

@@ -3,7 +3,7 @@ import type { z } from "zod";
 import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
 import { type Field, recordSchemaOf } from "./collection.ts";
 import { connectorsOf, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
-import { type Builtin, jsonSchemaOf, opIdsOf, type Use } from "./define.ts";
+import { type Builtin, jsonSchemaOf, opIdsOf, type Trigger, type Use } from "./define.ts";
 import { isDirect } from "./direct.ts";
 import { lintWorkflow } from "./lint.ts";
 import { type Effect, VENDOR, type VendorInfo } from "./op.ts";
@@ -68,6 +68,9 @@ export { readSites, type SiteCall, type SiteEntry, type SitePage, siteContentPag
 export { API_FILE, generateApi, writeApi, writeGenerated } from "./sdk.ts";
 // The Cedar schema, `.sanoma/schema.cedarschema`: what a company's policies are validated and decided against.
 export { SCHEMA_FILE, schemaOf, schemaText, type CedarSchemaJson } from "./schema.ts";
+// The Permissions grid: the app's page and `sanoma check`'s `checked` event compute it the one way.
+export { columnPrincipal, permissionsGrid, type PermissionsGrid, type PermissionsRow } from "./grid.ts";
+export { previewRequests } from "./shared.ts";
 // The apply workflow's plan and report, which the app renders.
 export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 
@@ -75,7 +78,8 @@ export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanS
 export interface WorkflowEntry {
   name: string;
   title?: string;
-  trigger: "manual";
+  /** `manual`, or the schedule it starts on (`defineWorkflow`'s `trigger`). */
+  trigger: Trigger;
   /**
    * Set for a workflow the runtime adds itself, `drift`, `apply` or `call`, rather than the config: a label. It
    * starts like any other.
@@ -359,14 +363,22 @@ function domainProblems(
       const others = `${names.length === 2 ? "both " : ""}${names.slice(0, -1).join(", ")}`;
       messages.push(`${domain} is the domain of ${others} and ${names.at(-1)}`);
     }
-    if (!messages.length || root === undefined) continue;
-    const file = read(join(root, resource.file));
-    const at = typeof file === "string" ? {} : file.at(resource.span[0]);
-    for (const message of messages) problems.push({ file: resource.file, ...at, message });
+    if (root !== undefined) problems.push(...messages.map((message) => problemAt(root, resource, read, message)));
   }
   return problems;
 }
 
+/** `message` at a declaration's `export const`. */
+function problemAt(
+  root: string,
+  resource: DeclaredResource,
+  read: (path: string) => SourceFile | string,
+  message: string,
+): ResourceProblem {
+  const file = read(join(root, resource.file));
+  return { file: resource.file, ...(typeof file === "string" ? {} : file.at(resource.span[0])), message };
+}
+
 /**
  * A site's `api` names each workflow `apiNameOf(name)` beside the vendors' operations and the
  * collections (`api.data`), so a workflow whose name comes out as another's, a vendor's id or

package/src/errors.ts

@@ -6,6 +6,7 @@ import { CALL_WORKFLOW, errorMessage } from "./shared.ts";
 const CODES = [
   "policy_denied",
   "approval_rejected",
+  "approval_withdrawn",
   "not_approver",
   "no_pending_approval",
   "already_decided",
@@ -132,6 +133,19 @@ export class RejectedError extends SanomaError {
   }
 }
 
+/** Thrown into the run when the approval it waits on is withdrawn. The run fails with it unless it catches it. */
+export class WithdrawnError extends SanomaError {
+  /**
+   * @param title The approval's title.
+   * @param approvalId The approval's id in the run, such as "approval-2".
+   * @param reason Why it was withdrawn.
+   */
+  constructor(title: string, approvalId: string, reason: string) {
+    super("approval_withdrawn", `"${title}" was withdrawn: ${reason}`, { title, approvalId, reason });
+    this.name = "WithdrawnError";
+  }
+}
+
 /**
  * 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

package/src/fake.ts

@@ -7,7 +7,11 @@ import {
   DriverError,
   type OpIdOf,
   type Specs,
+  withSetup,
 } from "./op.ts";
+import { fail, type Instance, UNREGISTERED, type WakeupApi, wakeupCalls } from "./wakeup-driver.ts";
+import { INSTANCE_TOKEN, instanceUrl } from "./wakeup-service.ts";
+import { wakeupOps } from "./wakeup-type.ts";
 
 /*
  * Fake vendors for tests, at `@sanoma-ai/workflows/fake`. Kept off the main entry so the
@@ -154,3 +158,148 @@ export function defineFake<V extends string, S extends Specs, T extends Record<s
     },
   };
 }
+
+/**
+ * `connector` set up with this fake instead of the one its package attaches, for a test or a demo
+ * that seeds or reads the fake its runs call: live runs call its driver, and sandbox runs call it
+ * too, since its maker gives this very one. A driver swap alone is `withSetup(connector, { driver })`,
+ * which keeps the package's fake, so each sandbox run has one of its own. The operations are the
+ * same.
+ */
+export function withFake<C extends Connector<any, any>>(connector: C, fake: Fake<any, any>): C {
+  return withSetup(connector, { driver: () => fake.driver, fake: () => fake });
+}
+
+// The built-in `sanoma.wakeup`'s fake: an in-memory wakeup service that calls the host's `/wake`.
+
+/** An instance of the fake wakeup service, as it keeps one. */
+interface FakeInstance extends Instance {
+  token: string;
+}
+
+interface FakeWakeupState extends Record<string, unknown> {
+  seq: number;
+  instances: Record<string, FakeInstance>;
+}
+
+/** How long the fake waits before it sends a wake again that the host did not answer. */
+const RETRY_MS = 250;
+/** setTimeout's longest delay: a longer one fires at once. */
+const MAX_DELAY_MS = 2 ** 31 - 1;
+
+/** The URL as the service keeps it (`instanceUrl`, its own rule), or the service's 400. */
+function checkedUrl(value: string): string {
+  const checked = instanceUrl(value);
+  if ("error" in checked) throw fail(checked.error, 400);
+  return checked.url;
+}
+
+/**
+ * An in-memory wakeup service for tests, as `sanoma wakeup` answers: instances in
+ * `state.instances`, ids made in order (UUID-shaped), each named by the token it was posted with
+ * (the call's `SANOMA_WAKEUP_TOKEN`), so posting it again moves it. `register` takes only the
+ * instance's own token and replaces the wake it had; it then sends `GET {host}/wake` at `at`,
+ * again every 250 ms until the host answers 2xx. `fire()` sends every armed wake now; `close()`
+ * (and `reset()`) disarms them.
+ */
+export function fakeSanomaWakeup(options: FakeOptions = {}) {
+  /** The wake each instance waits to send, by its id. */
+  const armed = new Map<string, { at: number; url: string; timeout?: NodeJS.Timeout; sending?: boolean }>();
+  const disarm = (id: string) => {
+    clearTimeout(armed.get(id)?.timeout);
+    armed.delete(id);
+  };
+  /** Sends `id`'s armed wake once it is due, while it is still the one armed, until the host answers. */
+  const send = async (id: string, pending = armed.get(id)) => {
+    // One request at a time: the one in flight sends again if it is not answered.
+    if (!pending || armed.get(id) !== pending || pending.sending) return;
+    const due = pending.at - Date.now();
+    if (due > 0) {
+      pending.timeout = setTimeout(() => void send(id, pending), Math.min(due, MAX_DELAY_MS)).unref();
+      return;
+    }
+    pending.sending = true;
+    const answered = await fetch(`${pending.url}/wake`).then(
+      (res) => res.ok,
+      () => false,
+    );
+    pending.sending = false;
+    if (armed.get(id) !== pending) return;
+    if (answered) armed.delete(id);
+    else pending.timeout = setTimeout(() => void send(id, pending), RETRY_MS).unref();
+  };
+
+  const api = (state: FakeWakeupState): WakeupApi => ({
+    async put(url, token) {
+      const checked = checkedUrl(url);
+      if (!INSTANCE_TOKEN.test(token)) throw fail("token must be an instance's token", 400);
+      const mine = Object.values(state.instances).find((i) => i.token === token);
+      if (mine) {
+        // The same instance, moved: its wake there forgotten.
+        if (mine.url !== checked) {
+          Object.assign(mine, { url: checked, ...UNREGISTERED });
+          disarm(mine.id);
+        }
+        return { id: mine.id };
+      }
+      const id = `00000000-0000-4000-8000-${String(++state.seq).padStart(12, "0")}`;
+      state.instances[id] = { id, url: checked, ...UNREGISTERED, token };
+      return { id };
+    },
+    async get(id) {
+      const found = state.instances[id];
+      if (!found) return undefined;
+      const { token: _, ...shown } = found;
+      return shown;
+    },
+    async remove(id) {
+      delete state.instances[id];
+      disarm(id);
+    },
+    async wake({ at }, token) {
+      // The token names the instance.
+      const mine = Object.values(state.instances).find((i) => i.token === token);
+      if (!mine) throw fail("the token is no instance's", 401);
+      Object.assign(mine, { at: new Date(at).toISOString(), lastError: null });
+      disarm(mine.id);
+      armed.set(mine.id, { at: Date.parse(at), url: mine.url });
+      void send(mine.id);
+    },
+  });
+
+  const fake = defineFake(
+    wakeupOps,
+    {
+      initial: (): FakeWakeupState => ({ seq: 0, instances: {} }),
+      ops: (state) => ({ wakeup: wakeupCalls(() => api(state)) }),
+    },
+    options,
+  );
+  const close = () => {
+    for (const id of armed.keys()) disarm(id);
+  };
+  const { reset } = fake;
+  return Object.assign(fake, {
+    /** Sends every armed wake now, whatever its `at`; resolves once the hosts answered them, or fails after 60 s. */
+    async fire() {
+      const fired = [...armed].map(([id, pending]) => {
+        clearTimeout(pending.timeout);
+        pending.at = 0;
+        void send(id, pending);
+        return pending;
+      });
+      const until = Date.now() + 60_000;
+      while (fired.some((p) => [...armed.values()].includes(p))) {
+        if (Date.now() > until) throw new Error("sanoma.wakeup fake: a fired wake was not answered in 60 s");
+        await new Promise((r) => setTimeout(r, 50));
+      }
+    },
+    /** Disarms every armed wake. */
+    close,
+    /** Empties the state and disarms every armed wake. */
+    reset() {
+      close();
+      reset();
+    },
+  });
+}