gemi 0.117.0 → 0.118.0

package/dist/services/queue/workflow/Step.d.ts

@@ -0,0 +1,202 @@
+import { type BatchStatus } from "../batch";
+import type { EnqueueBatch } from "../QueueDriver";
+import type { Job } from "../Job";
+import { type Duration } from "./duration";
+import { type StepRecord, type WorkflowStore } from "./WorkflowStore";
+/** What a `step.run` function is handed. */
+export type StepContext = {
+    /**
+     * `<workflow id>:<step key>`: the same on every attempt of this step, and
+     * different for every other step. Pass it to a payment provider, say, so
+     * that an attempt repeated after a crash is not charged twice.
+     */
+    idempotencyKey: string;
+    /** Which attempt this is, counting from 1. */
+    attempt: number;
+    /**
+     * Aborted when the step's `timeout` passes or the workflow is cancelled.
+     * Pass it to `fetch` and friends. The workflow stops waiting for the step
+     * at that moment, whether or not the function notices.
+     */
+    signal: AbortSignal;
+};
+export type StepRunOptions = {
+    /** How many attempts the step gets, counting the first. Default 3. */
+    attempts?: number;
+    /**
+     * Milliseconds to wait before each retry: one number for every retry, or
+     * one per retry with the last repeated, as `Job.backoff`. Default 0. A
+     * retry with a delay suspends the workflow until it is due.
+     */
+    backoff?: number | number[];
+    /** How long one attempt may take before it counts as failed. */
+    timeout?: Duration;
+};
+export type StepWaitOptions = {
+    /**
+     * How long to wait for the signal. Past it, `waitFor` throws a
+     * `WaitTimeoutError`. Without it, the workflow waits until it is signalled
+     * or cancelled.
+     */
+    timeout?: Duration;
+};
+export type StepBatchOptions = {
+    /** A label kept with the batch. Default `workflow:<id>:<key>`. */
+    name?: string;
+    /**
+     * Whether a failed job leaves the rest running. Default `false`: the first
+     * dead-lettered job cancels the batch and `step.batch` throws a
+     * `StepFailedError`. With `true`, `step.batch` returns the status, failed
+     * jobs and all.
+     */
+    allowFailures?: boolean;
+};
+/** A step that ran out of attempts, or a batch that failed. */
+export declare class StepFailedError extends Error {
+    /** The step's key. */
+    readonly step: string;
+    /** The batch's final status, for a `step.batch` that failed. */
+    readonly batch?: BatchStatus;
+    constructor(
+    /** The step's key. */
+    step: string, message: string, 
+    /** The batch's final status, for a `step.batch` that failed. */
+    batch?: BatchStatus);
+}
+/** A `step.waitFor` whose `timeout` passed before the signal arrived. */
+export declare class WaitTimeoutError extends Error {
+    readonly step: string;
+    constructor(step: string);
+}
+/** Why a step's `ctx.signal` was aborted by its `timeout`. */
+export declare class StepTimeoutError extends Error {
+    constructor(step: string, timeoutMs: number);
+}
+/** Why a step's `ctx.signal` was aborted by `Workflow.cancel`. */
+export declare class WorkflowCancelledError extends Error {
+    constructor(id: string);
+}
+/**
+ * Thrown through the workflow's code when a step cannot finish in this tick
+ * (a sleep, a wait, a batch, a retry with a delay), so the tick can end and
+ * the workflow resume later. Not exported: code that catches everything
+ * should rethrow what it does not know, and the tick treats the workflow as
+ * suspended even if this is swallowed.
+ */
+export declare class WorkflowSuspended extends Error {
+    constructor();
+}
+/** What the runtime gives the steps of one tick. */
+export type StepTick = {
+    workflowId: string;
+    /** The tick's hold on the workflow; every write is fenced by it. */
+    owner: string;
+    store: WorkflowStore;
+    /** The steps as they were when the tick took the workflow. */
+    steps: StepRecord[];
+    /** This tick runs `onCancel`, not `run`. */
+    cancelling: boolean;
+    findBatch(id: string): Promise<BatchStatus | null>;
+    buildBatch(job: new () => Job, args: ReadonlyArray<ReadonlyArray<unknown>>, options: {
+        name: string;
+        allowFailures: boolean;
+    }): EnqueueBatch;
+    /** Jobs were recorded: wake the queue. */
+    scheduled(): void;
+    /** How often a running step checks whether the workflow was cancelled. */
+    cancelCheckMs: number;
+};
+/** Why a tick stopped where it did. */
+export type Suspension = {
+    status: "sleeping" | "waiting";
+    /** When a tick is needed to continue; none for a wait on a signal or batch. */
+    wakes: number[];
+};
+/**
+ * What `run` receives as its first argument. Every method takes a **key**,
+ * unique within the workflow and the same on every pass: a step whose key has
+ * a stored result returns it without running again, which is how a workflow
+ * resumes where it stopped. Code outside the steps runs again on every pass.
+ */
+export declare class Step {
+    private readonly tick;
+    /** The workflow's id. */
+    readonly workflowId: string;
+    private readonly steps;
+    private readonly seen;
+    private readonly pending;
+    /** @internal Why the tick stopped, once a step suspended it. */
+    suspension: Suspension | undefined;
+    /** @internal The tick lost its hold on the workflow. */
+    lost: boolean;
+    /** The workflow was cancelled during this tick. */
+    private cancelled;
+    /** @internal The step the workflow is on, for its status. */
+    current: string | null;
+    /** @internal Built by the workflow runtime, once per tick. */
+    constructor(tick: StepTick);
+    /**
+     * Runs `fn` once and stores what it returns, as JSON; on every later pass
+     * the stored value is returned without running it again. A throw is retried
+     * up to `attempts`, after which the step fails and this throws a
+     * `StepFailedError`, which the workflow may catch. The value comes back as
+     * JSON makes it, the first time too: a `Date` becomes a string.
+     *
+     * At least once: a process that dies after `fn` and before its result is
+     * stored runs it again. Use `ctx.idempotencyKey` for anything that must not
+     * happen twice, or `attempts: 1`.
+     */
+    run<T>(key: string, fn: (ctx: StepContext) => T | Promise<T>, options?: StepRunOptions): Promise<Awaited<T>>;
+    /** Suspends the workflow for `duration`, without holding a process. */
+    sleep(key: string, duration: Duration): Promise<void>;
+    /**
+     * Suspends the workflow until `Workflow.signal(id, key, payload)` and
+     * returns the payload. A signal that arrives before the workflow gets here
+     * is kept, and returned at once.
+     */
+    waitFor<T = unknown>(key: string, options?: StepWaitOptions): Promise<T>;
+    /**
+     * Dispatches `job` once per argument tuple as a batch (`Job.dispatchBatch`)
+     * and suspends the workflow until every job has ended; then returns the
+     * batch's status. The step is recorded and the batch dispatched in one
+     * atomic write, so a crash cannot dispatch it twice.
+     */
+    batch<J extends Job>(key: string, job: new () => J, args: ReadonlyArray<Readonly<Parameters<J["run"]>>>, options?: StepBatchOptions): Promise<BatchStatus>;
+    /**
+     * Sets the workflow's `progress`, 0 to 1. Not a step: it writes on every
+     * pass that reaches it.
+     */
+    progress(value: number): Promise<void>;
+    /** @internal Waits for every step this tick started, however each ended. */
+    settled(): Promise<void>;
+    private track;
+    private remember;
+    /** Once suspended, nothing else may start in this tick. */
+    private assertRunning;
+    private suspend;
+    /**
+     * One atomic write, fenced by the tick's hold. A workflow that is being
+     * cancelled takes no new work from `run`: the write is skipped and the
+     * tick suspended, so `onCancel` runs next.
+     */
+    private write;
+    private record;
+    private mismatch;
+    private runStep;
+    /**
+     * One attempt of a `step.run` function, abandoned when its timeout passes
+     * or the workflow is cancelled meanwhile.
+     */
+    private execute;
+    private sleepStep;
+    private waitStep;
+    private batchStep;
+}
+/**
+ * A value as stored: JSON, or `null` for `undefined`. Refused past
+ * `WORKFLOW_OUTPUT_LIMIT`, and for what JSON cannot carry.
+ */
+export declare function encode(value: unknown, what: string): string | null;
+export declare function decode(output: string | null): unknown;
+export declare function describe(error: unknown): string;
+//# sourceMappingURL=Step.d.ts.map

package/dist/services/queue/workflow/Step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Step.d.ts","sourceRoot":"","sources":["../../../../services/queue/workflow/Step.ts"],"names":[],"mappings":"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"}

package/dist/services/queue/workflow/Workflow.d.ts

@@ -0,0 +1,124 @@
+import type { Step } from "./Step";
+import type { StepRunStatus, WorkflowRunStatus } from "./WorkflowStore";
+/** The arguments `start` takes: `run`'s, after `step`. */
+export type WorkflowArgs<T extends Workflow> = Parameters<T["run"]> extends [
+    any,
+    ...infer Rest
+] ? Rest : never;
+/** What `Workflow.find` resolves to. Times are epoch milliseconds. */
+export type WorkflowStatus = {
+    id: string;
+    /** The workflow class's `static name`. */
+    name: string;
+    status: WorkflowRunStatus;
+    /** The `run` arguments after `step`. */
+    args: unknown[];
+    /** The key of the step it is on, or `null`. */
+    currentStep: string | null;
+    /** 0 to 1, as `step.progress` last set it; 1 once completed. */
+    progress: number;
+    /** What `run` returned, once completed. */
+    result: unknown;
+    /** Why it failed; for a cancelled one, why `onCancel` failed. */
+    error: string | null;
+    /** Every step recorded so far, in the order they were first reached. */
+    steps: WorkflowStepStatus[];
+    createdAt: number;
+    updatedAt: number;
+};
+export type WorkflowStepStatus = {
+    key: string;
+    status: StepRunStatus;
+    /** Attempts started; `step.run` only. */
+    attempt: number;
+    error: string | null;
+    /** The batch a `step.batch` dispatched. */
+    batchId: string | null;
+    /** The batch's progress, 0 to 1, for a `step.batch`. */
+    progress?: number;
+    /** When a sleep ends, a wait times out, or a retry is due. */
+    wakeAt: number | null;
+    startedAt: number | null;
+    finishedAt: number | null;
+};
+/**
+ * A durable workflow (#846): a `run` method made of steps, which survives
+ * restarts and deploys, sleeps and waits without holding a process, and can
+ * be cancelled.
+ *
+ * ```ts
+ * export class ImportSiteWorkflow extends Workflow {
+ *   static name = "ImportSiteWorkflow";
+ *
+ *   async run(step: Step, importId: string) {
+ *     const pages = await step.run("discover", () => crawl(importId));
+ *     const chosen = await step.waitFor<string[]>("pages-chosen", { timeout: "7d" });
+ *     await step.run("charge", (ctx) => charge(importId, ctx.idempotencyKey), { attempts: 1 });
+ *     const builds = await step.batch("build", BuildPageJob,
+ *       chosen.map((id) => [id, importId] as const), { allowFailures: true });
+ *     await step.sleep("settle", "30s");
+ *     return step.run("report", () => report(importId, builds.failedJobIds));
+ *   }
+ *
+ *   async onCancel(step: Step, importId: string) {
+ *     await step.run("refund", () => refundUnbuilt(importId));
+ *   }
+ * }
+ * ```
+ *
+ * ### How it runs
+ *
+ * Each pass calls `run` from the top, inside an internal queue job (a
+ * *tick*), so leases, heartbeats and crash recovery are the queue's. A step
+ * whose result is stored returns it without running; the first one without
+ * one runs and its result is stored before the code goes on. A step that
+ * cannot finish now (a sleep, a wait, a batch, a retry with a delay) ends the
+ * pass, and a later tick picks it up. **Code outside the steps runs again on
+ * every pass**, so it must be cheap and give the same answer each time: put
+ * anything with a side effect, anything slow and anything random or
+ * time-dependent inside `step.run`.
+ *
+ * Step keys are the identity of a step: unique within the workflow, and the
+ * same on every pass. Adding or removing a step between deploys is safe; a
+ * renamed step runs again.
+ */
+export declare class Workflow {
+    static name: string;
+    /**
+     * The workflow's body. Its return value, as JSON, is the workflow's
+     * `result`. A throw that escapes it fails the workflow.
+     */
+    run(_step: Step, ..._args: any[]): unknown;
+    /**
+     * Runs once after `Workflow.cancel`, in place of `run`, with the same
+     * arguments: the place to undo what the steps did. Its steps are memoized
+     * like `run`'s (use keys of their own), so it may sleep or retry too.
+     */
+    onCancel(_step: Step, ..._args: any[]): unknown;
+    /**
+     * Starts a workflow and resolves to its id. The workflow and its first tick
+     * are recorded in one atomic write. Inside an ORM transaction it belongs to
+     * the transaction, as a dispatch does: recorded with it, or held until it
+     * commits and dropped if it rolls back.
+     */
+    static start<T extends Workflow>(this: new () => T, ...args: WorkflowArgs<T>): Promise<string>;
+    /**
+     * Delivers `payload` to the workflow's `step.waitFor(key)`, and resolves to
+     * whether it was taken: `false` for an unknown or ended workflow, and for a
+     * key that was already signalled. A signal that arrives before the workflow
+     * reaches its `waitFor` is kept until it does.
+     */
+    static signal(id: string, key: string, payload?: unknown): Promise<boolean>;
+    /** The workflow's status, or `null` for an unknown id. */
+    static find(id: string): Promise<WorkflowStatus | null>;
+    /**
+     * Cancels a workflow that has not ended, and resolves to whether it did.
+     * A running `step.batch` is cancelled with it, a running `step.run` is told
+     * through `ctx.signal`, and `onCancel` then runs once.
+     */
+    static cancel(id: string): Promise<boolean>;
+}
+export type WorkflowClass = (new () => Workflow) & {
+    name: string;
+};
+//# sourceMappingURL=Workflow.d.ts.map

package/dist/services/queue/workflow/Workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Workflow.d.ts","sourceRoot":"","sources":["../../../../services/queue/workflow/Workflow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAExE,0DAA0D;AAC1D,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,QAAQ,IAAI,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS;IAC1E,GAAG;IACH,GAAG,MAAM,IAAI;CACd,GACG,IAAI,GACJ,KAAK,CAAC;AAEV,sEAAsE;AACtE,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;IAC1B,wCAAwC;IACxC,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;IAChB,iEAAiE;IACjE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,wEAAwE;IACxE,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,aAAa,CAAC;IACtB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,QAAQ;IACnB,MAAM,CAAC,IAAI,SAAW;IAEtB;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,GAAG,OAAO;IAI1C;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,GAAG,OAAO;IAI/C;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,QAAQ,EAC7B,IAAI,EAAE,UAAU,CAAC,EACjB,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3E,0DAA0D;IAC1D,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAIvD;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAG5C;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,UAAU,QAAQ,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/services/queue/workflow/WorkflowRuntime.d.ts

@@ -0,0 +1,60 @@
+import { Job } from "../Job";
+import type { QueueManager } from "../QueueManager";
+import type { WorkflowClass, WorkflowStatus } from "./Workflow";
+import { type WorkflowStore } from "./WorkflowStore";
+/**
+ * The queue's half of workflows: the registry of workflow classes, what
+ * `Workflow.start`, `signal`, `find` and `cancel` do, and the tick.
+ *
+ * ### The tick
+ *
+ * A workflow advances only inside its tick job, which takes the workflow
+ * from the store for a lease (the queue's `visibilityTimeout`, renewed while
+ * it runs), runs one pass of `run`, and lets go with the outcome written in
+ * the same step. Every write of the pass is fenced by that hold, so a tick
+ * that lost it (it was too slow and another took over) changes nothing.
+ *
+ * A tick that finds the workflow held by another is dropped, after marking
+ * the workflow so the holder enqueues a fresh tick when it lets go: a signal
+ * that lands mid-pass is never lost, and two passes of one workflow never
+ * overlap. A tick that failed or died holds the workflow under its job's id,
+ * so its own retry takes it straight back.
+ */
+export declare class WorkflowRuntime {
+    private readonly queue;
+    private registry;
+    private storeInstance;
+    private tickClass;
+    private readonly reportedNames;
+    constructor(queue: QueueManager);
+    /** The workflow classes this process can run, by `static name`. */
+    get workflows(): Readonly<Record<string, WorkflowClass>>;
+    /** Replaces the registry. The first class to claim a name wins. */
+    use(workflows: readonly WorkflowClass[]): void;
+    /** The internal job a workflow's passes run in, one class per manager. */
+    get tickJob(): new () => Job;
+    get store(): WorkflowStore;
+    start(workflow: WorkflowClass, args: unknown[]): Promise<string>;
+    signal(id: string, key: string, payload?: unknown): Promise<boolean>;
+    cancel(id: string): Promise<boolean>;
+    find(id: string): Promise<WorkflowStatus | null>;
+    /** One pass of the workflow `id`, run by its tick job. */
+    tick(id: string, job: Job): Promise<void>;
+    /** The tick's last write: the pass's outcome, and letting go. */
+    private finish;
+    /**
+     * A tick for a workflow this process has no class for. During a
+     * blue/green ramp that is usually one only the other release has, so on a
+     * shared driver it goes back for another replica until `unknownJobGrace`
+     * has passed since the workflow started; then it fails.
+     */
+    private unknown;
+    /**
+     * The tick job ran out of attempts, which only a store that stayed
+     * unreachable causes. Fails the workflow if it still can, so it does not
+     * sit in `running` with nothing left to advance it.
+     */
+    /** @internal */
+    tickDeadLettered(id: string, error: Error): void;
+}
+//# sourceMappingURL=WorkflowRuntime.d.ts.map

package/dist/services/queue/workflow/WorkflowRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkflowRuntime.d.ts","sourceRoot":"","sources":["../../../../services/queue/workflow/WorkflowRuntime.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAQpD,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAYzB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAe;IAMd,OAAO,CAAC,QAAQ,CAAC,KAAK;IALlC,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEtB,KAAK,EAAE,YAAY;IAEhD,mEAAmE;IACnE,IAAI,SAAS,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAEvD;IAED,mEAAmE;IACnE,GAAG,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE;IAoBvC,0EAA0E;IAC1E,IAAI,OAAO,IAAI,UAAU,GAAG,CAG3B;IAED,IAAI,KAAK,IAAI,aAAa,CAYzB;IAED,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAoC1D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAuCpE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBpC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAuCtD,0DAA0D;IACpD,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA0G/C,iEAAiE;IACjE,OAAO,CAAC,MAAM;IA4Dd;;;;;OAKG;YACW,OAAO;IAgCrB;;;;OAIG;IACH,gBAAgB;IAChB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAiB1C"}

package/dist/services/queue/workflow/WorkflowStore.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Where workflows are kept (#846), and the one atomic operation everything a
+ * workflow does is built from.
+ *
+ * A store belongs to a queue driver (`QueueDriver.workflowStore`), because a
+ * workflow's writes and the jobs they schedule must commit together: a step
+ * that sleeps records the sleep and enqueues the tick that wakes it in one
+ * step, and `step.batch` records the step and dispatches the batch in one
+ * step, so a crash between the two can neither lose the wake-up nor fan out
+ * twice. The memory driver does each change synchronously; the database driver
+ * does it in a transaction that locks the workflow's row first.
+ *
+ * A store only keeps records. What a change means (when a step is done, when
+ * a workflow sleeps) is decided by the runtime, in the `decide` callback of
+ * `update`, while the store holds the workflow exclusively.
+ */
+import type { EnqueueBatch } from "../QueueDriver";
+/** The registered name the internal tick job runs under. */
+export declare const WORKFLOW_TICK_JOB = "gemi.WorkflowTick";
+/**
+ * The most a step's output, a signal's payload or a workflow's result may be,
+ * as JSON, in bytes. Store an id for anything larger.
+ */
+export declare const WORKFLOW_OUTPUT_LIMIT: number;
+/**
+ * Where a workflow stands.
+ *
+ * - `running`: a tick is running it, or one is queued to.
+ * - `sleeping`: waiting for a `step.sleep` or a step's retry backoff.
+ * - `waiting`: waiting for a signal (`step.waitFor`) or a batch (`step.batch`).
+ * - `cancelling`: `cancel` was accepted, and `onCancel` has not finished yet.
+ * - `completed`, `failed`, `cancelled`: final.
+ */
+export type WorkflowRunStatus = "running" | "sleeping" | "waiting" | "completed" | "failed" | "cancelling" | "cancelled";
+/**
+ * Where one step stands. `signalled` is a signal that arrived before its
+ * `step.waitFor`, kept until the workflow gets there.
+ */
+export type StepRunStatus = "running" | "retrying" | "completed" | "failed" | "sleeping" | "waiting" | "signalled" | "timed_out" | "batching";
+/** A workflow's row. Times are epoch milliseconds. */
+export type WorkflowRecord = {
+    id: string;
+    /** The workflow class's `static name`. */
+    name: string;
+    /** The `run` arguments after `step`, as JSON. */
+    args: string;
+    status: WorkflowRunStatus;
+    /** The key of the step it is on, or `null`. */
+    currentStep: string | null;
+    /** 0 to 1, as `step.progress` last set it; 1 once completed. */
+    progress: number;
+    /** What `run` returned, as JSON, once completed. `null` for `undefined`. */
+    result: string | null;
+    error: string | null;
+    /** When the next tick that was scheduled for a wake-up is due, or `null`. */
+    wakeAt: number | null;
+    /** The tick holding the workflow, and until when (on the store's clock). */
+    lockedBy: string | null;
+    lockedUntil: number | null;
+    /** Another tick arrived while one held the workflow; see `update`'s `unlock`. */
+    retick: boolean;
+    createdAt: number;
+    updatedAt: number;
+};
+/** A step's row, unique per workflow and key. */
+export type StepRecord = {
+    workflowId: string;
+    key: string;
+    status: StepRunStatus;
+    /** Attempts started, counting from 1. */
+    attempt: number;
+    /** The step's result or the signal's payload, as JSON. `null` for `undefined`. */
+    output: string | null;
+    error: string | null;
+    /** The batch a `step.batch` dispatched. */
+    batchId: string | null;
+    /** When a sleep ends, a wait times out, or a retry is due. */
+    wakeAt: number | null;
+    startedAt: number | null;
+    finishedAt: number | null;
+    createdAt: number;
+    updatedAt: number;
+};
+/** A workflow and its steps, in the order the steps were first recorded. */
+export type WorkflowState = {
+    workflow: WorkflowRecord;
+    steps: StepRecord[];
+};
+export type AcquireResult = {
+    kind: "missing";
+}
+/** Another tick holds it; `retick` is set, so that tick runs it again. */
+ | {
+    kind: "busy";
+} | ({
+    kind: "acquired";
+} & WorkflowState);
+/** What `update`'s `decide` sees, read while the workflow is held. */
+export type WorkflowSnapshot = {
+    workflow: WorkflowRecord;
+    /** The step `key` names, or `null` when there is none (or no key was given). */
+    step: StepRecord | null;
+    /** Every step, when `allSteps` was asked for; otherwise empty. */
+    steps: StepRecord[];
+    /** This process's clock, for the wake-up times the runtime computes. */
+    now: number;
+};
+/** What `decide` wants written, all in the same atomic step. */
+export type WorkflowChange<T> = {
+    /** What `update` resolves to. */
+    result: T;
+    workflow?: Partial<Pick<WorkflowRecord, "status" | "currentStep" | "progress" | "result" | "error" | "wakeAt">>;
+    /** The step's new row: inserted, or replacing the one under its key. */
+    step?: StepRecord;
+    /** A batch to dispatch, as `QueueDriver.enqueueBatch` would. */
+    batch?: EnqueueBatch;
+    /** Batches to cancel, as `QueueDriver.cancelBatch` would. */
+    cancelBatches?: string[];
+    /** Enqueue a tick for this workflow, claimable after `delayMs`. */
+    tick?: {
+        delayMs: number;
+    };
+    /**
+     * Release the tick's hold on the workflow. When another tick arrived while
+     * it was held (`retick`), a new tick is enqueued in the same step, so a
+     * signal that landed mid-tick is never lost.
+     */
+    unlock?: boolean;
+};
+/**
+ * Whether two holds are attempts of the same tick job. A tick holds the
+ * workflow as `<tick job id>:<attempt>`, so a retry of a tick that failed or
+ * died takes the workflow straight back instead of waiting out the lease,
+ * and the earlier attempt's writes are refused from then on.
+ */
+export declare function sameTick(a: string, b: string): boolean;
+export declare class WorkflowLeaseLostError extends Error {
+    constructor(id: string);
+}
+export interface WorkflowStore {
+    /**
+     * Records a new workflow and enqueues its first tick, in one atomic step.
+     * Like `QueueDriver.enqueue`, a store that answers `joinsTransaction`
+     * writes on the caller's ORM transaction.
+     */
+    create(workflow: {
+        id: string;
+        name: string;
+        args: string;
+    }): Promise<void>;
+    /** Whether `create` would write on the caller's open ORM transaction. */
+    joinsTransaction?(): boolean;
+    /** The workflow, and its steps unless `steps: false`, or `null`. */
+    find(id: string, options?: {
+        steps?: boolean;
+    }): Promise<WorkflowState | null>;
+    /**
+     * Takes the workflow for one tick, for `leaseMs` on the store's clock, and
+     * returns its state. A workflow another tick holds under a live lease is
+     * `busy`, and is marked to be ticked again when that tick lets go; one held
+     * by an earlier attempt of the same tick job (see `sameTick`) is taken over.
+     */
+    acquire(id: string, owner: string, leaseMs: number): Promise<AcquireResult>;
+    /** Extends the tick's lease, and resolves to whether it still held it. */
+    renew(id: string, owner: string, leaseMs: number): Promise<boolean>;
+    /**
+     * Reads the workflow (and the step `key`, or every step with `allSteps`)
+     * while holding it exclusively, calls `decide`, and writes what it returns,
+     * all in one atomic step. With `owner`, the write is refused with a
+     * `WorkflowLeaseLostError` unless that tick still holds the workflow.
+     * Resolves to `undefined` for an unknown workflow.
+     */
+    update<T>(id: string, options: {
+        owner?: string;
+        key?: string;
+        allSteps?: boolean;
+    }, decide: (snapshot: WorkflowSnapshot) => WorkflowChange<T>): Promise<T | undefined>;
+    /**
+     * Deletes workflows that ended (completed, failed or cancelled) more than
+     * `olderThanMs` ago, with their steps, and resolves to how many.
+     */
+    prune?(olderThanMs: number): Promise<number>;
+}
+//# sourceMappingURL=WorkflowStore.d.ts.map

package/dist/services/queue/workflow/WorkflowStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkflowStore.d.ts","sourceRoot":"","sources":["../../../../services/queue/workflow/WorkflowStore.ts"],"names":[],"mappings":"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"}

package/dist/services/queue/workflow/duration.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A length of time: milliseconds as a number, or a number and a unit, such as
+ * `"500ms"`, `"30s"`, `"5m"`, `"2h"`, `"7d"` or `"1w"`.
+ */
+export type Duration = number | `${number}${"ms" | "s" | "m" | "h" | "d" | "w"}`;
+/** A `Duration` in milliseconds. Throws for anything else, on the caller's stack. */
+export declare function toMilliseconds(duration: Duration): number;
+//# sourceMappingURL=duration.d.ts.map

package/dist/services/queue/workflow/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../../../services/queue/workflow/duration.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,GAAG,MAAM,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC;AAWjF,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAezD"}

package/dist/services/queue/workflow/workflowContract.d.ts

@@ -0,0 +1,30 @@
+import type { QueueDriver } from "../QueueDriver";
+/**
+ * What workflows promise on every driver that keeps them, as a suite a
+ * driver's test file runs against itself:
+ *
+ *     workflowContract("MemoryQueueDriver", async () => {
+ *       const driver = new MemoryQueueDriver();
+ *       return { driver: () => driver, dispose: async () => {} };
+ *     });
+ *
+ * `storage` makes fresh, empty storage for one test. Its `driver()` returns
+ * a driver over it, a new one per call where the storage is shared (a
+ * database), so that two managers on two drivers are two processes. The
+ * workflows run end to end, through `QueueManager`s that claim the ticks.
+ *
+ * Not a `*.test.ts` file, so vitest never runs it on its own.
+ */
+export declare function workflowContract(name: string, storage: () => Promise<{
+    driver(): QueueDriver;
+    dispose(): Promise<void>;
+}>, features?: {
+    /**
+     * Runs the test with two managers ticking the same workflows. Off for
+     * SQLite files: two clients in one thread are not two processes there,
+     * because SQLite's busy handler sleeps the very thread the lock holder
+     * needs to finish its transaction.
+     */
+    concurrentWorkers?: boolean;
+}): void;
+//# sourceMappingURL=workflowContract.d.ts.map

package/dist/services/queue/workflow/workflowContract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflowContract.d.ts","sourceRoot":"","sources":["../../../../services/queue/workflow/workflowContract.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAMlD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,OAAO,CAAC;IAAE,MAAM,IAAI,WAAW,CAAC;IAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,EAC3E,QAAQ,GAAE;IACR;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACC,QAogBhC"}

package/dist/stats/route-table.js

@@ -1,4 +1,4 @@
 // @bun
-import"../chunk-dcgvq79a.js";import M from"path";import{writeFileSync as Q}from"fs";var L=new Set(["FILE","REDIRECT"]);function H(j){return j.run(()=>{let x=[];for(let{group:z,view:D}of j.domains().viewGroups())for(let[G,B]of Object.entries(D.flatViewRoutes)){let C=D.routeManifest[G]??B.segments.map((K)=>K.viewPath);if(C.length===0||L.has(C.at(-1)))continue;x.push({path:G,group:z,views:C,...B.static?{static:B.static.layout?{layout:B.static.layout}:{}}:{}})}return x})}var J=process.argv[2];async function U(){if(!J)throw Error("usage: route-table <out.json>");let j=M.resolve(process.cwd(),"app/kernel/Kernel.ts"),x=await import(j);if(typeof x.default!=="function")throw Error(`${j} has no default export (the Kernel subclass).`);let z=new x.default;z.boot();try{Q(J,JSON.stringify(H(z)))}finally{z.destroy()}}U().then(()=>process.exit(0),(j)=>{console.error(j?.stack??String(j)),process.exit(1)});
+import"../chunk-hm9cjxy2.js";import M from"path";import{writeFileSync as Q}from"fs";var L=new Set(["FILE","REDIRECT"]);function H(j){return j.run(()=>{let x=[];for(let{group:z,view:D}of j.domains().viewGroups())for(let[G,B]of Object.entries(D.flatViewRoutes)){let C=D.routeManifest[G]??B.segments.map((K)=>K.viewPath);if(C.length===0||L.has(C.at(-1)))continue;x.push({path:G,group:z,views:C,...B.static?{static:B.static.layout?{layout:B.static.layout}:{}}:{}})}return x})}var J=process.argv[2];async function U(){if(!J)throw Error("usage: route-table <out.json>");let j=M.resolve(process.cwd(),"app/kernel/Kernel.ts"),x=await import(j);if(typeof x.default!=="function")throw Error(`${j} has no default export (the Kernel subclass).`);let z=new x.default;z.boot();try{Q(J,JSON.stringify(H(z)))}finally{z.destroy()}}U().then(()=>process.exit(0),(j)=>{console.error(j?.stack??String(j)),process.exit(1)});
 
 //# debugId=2C354352EBF6475164756E2164756E21