@demlik/tea 0.1.0 → 0.1.2

package/dist/workflow/index.d.ts

@@ -0,0 +1,450 @@
+import { D as DeliveryId, E as EffectLedgerEvent } from '../durable-effects-CO9Uh971.js';
+export { a as EffectConfirmed, b as EffectOwed, e as emptyLedger } from '../durable-effects-CO9Uh971.js';
+import { C as Cmd } from '../core-BoB6t7dB.js';
+
+/**
+ * @demlik/tea/workflow — the durable-workflow runtime core (#124, the first
+ * Phase-1 slice of the Temporal-style durable-workflow engine, epic #118).
+ *
+ * A workflow is a long-running, multi-step transaction whose every step (an
+ * **activity**) is a side effect that may evict the actor mid-flight. The
+ * substrate already solves "a state survives eviction" (the event-sourced
+ * store) and "an owed effect survives eviction" (the `do/` pending-effects
+ * ledger, #67). This module composes those two into the third primitive: a
+ * **pure TEA reducer over a workflow's progress**, where each step is dispatched
+ * as a durable owed effect and the next step is decided only after the previous
+ * one's result is folded back in. That is exactly Temporal's contract — a
+ * deterministic workflow function whose activities are the only impurity, so a
+ * replay of the event log re-decides every step identically.
+ *
+ * The mapping onto TEA, mirroring `../raft`:
+ *
+ *   - **Reducer** — {@link createWorkflow}'s verbs (`init`, `onActivityOk`,
+ *     `onActivityErr`) are the transition function over {@link WorkflowState}.
+ *     PURE: they read no clock and no RNG. Wall time, randomness, retries — all
+ *     impurity lives in the consumer's injected *interpret cell* (the thing that
+ *     actually performs the activity `Cmd` and dispatches its result `Msg`).
+ *     A workflow driven by a recorded result schedule re-decides bit-for-bit —
+ *     the headline replay-determinism payoff (acceptance criterion 4).
+ *   - **Cmd** — the activity dispatch is an {@link ActivityCmd}, recorded on the
+ *     #67 ledger as an `effect_owed` BEFORE it is performed and `effect_confirmed`
+ *     on its result. This module emits the Cmd literals; it performs NO side
+ *     effects. The owed/confirmed events are persisted into the same log the
+ *     reducer folds, so the ledger (and thus "which activity is still owed")
+ *     rebuilds for free on cold wake — re-emit-on-wake is idempotent by the
+ *     ledger's monotonic delivery id (acceptance criterion 3).
+ *   - **Msg** — an activity result (`activity_ok` / `activity_err`) is a `Msg`
+ *     the consumer routes back into a verb. The verb folds the result, records
+ *     the completed step, and advances to the next activity (or to `completed`
+ *     when the sequence is exhausted).
+ *
+ * **Invalid states unrepresentable.** The in-flight activity (`current`, with
+ * its delivery id) lives ONLY on the `running` variant of {@link WorkflowState}.
+ * A `completed` workflow carries its final output and no current activity; a
+ * `failed` one carries its failure and no current activity. So "the current
+ * activity exists only while running" is a type-level guarantee, not a runtime
+ * convention (acceptance criterion 1).
+ *
+ * **Boundary with `@demlik/tea/saga` — the compensation test.** Both drive an
+ * ordered multi-step transaction with reverse-order compensation (#125 here);
+ * the line between them is whether every step carries a true inverse. Here
+ * {@link WorkflowStep.compensation} is OPTIONAL — an irreversible step (a sent
+ * email) is simply SKIPPED during the unwind, and the run still reaches a
+ * terminal state. Saga's `SagaStep<D, U>` REQUIRES both `do` and `undo` — a
+ * step without its inverse is unrepresentable, so full reversibility is a
+ * type-level guarantee. Pick by the test: **every step must be reversible →
+ * saga; some steps are irreversible but the run must finish → workflow.**
+ * Cross to saga when you want the type system to enforce that every step can
+ * be undone; stay here when the transaction includes steps that can't be.
+ *
+ * This module is the pure reducer only — like `../raft/index.ts` is the pure
+ * Raft reducer with the DO grain deferred to its `./do` sibling (here #126).
+ *
+ * Generic over three opaque payloads, like raft's command generic: the activity
+ * descriptor `A` (what a step asks to do — the consumer's interpret cell knows
+ * how to perform it), the activity result `R`, and the failure `F`. The reducer
+ * never inspects them; it only sequences them.
+ *
+ * NOT a substrate primitive: it depends only on the core `Cmd` type and the
+ * sibling `../do` durable-effects ledger. Consumers reach it via the
+ * `@demlik/tea/workflow` subpath.
+ */
+
+/**
+ * One step of a workflow: a named activity descriptor. `A` is the opaque
+ * payload the consumer's interpret cell knows how to perform (an HTTP call, a
+ * sibling-grain message, a tool round-trip). The reducer never inspects
+ * `activity` — it only sequences the steps and correlates results.
+ *
+ * A step may declare a **compensation** — the inverse activity that undoes the
+ * forward one (cancel the reservation, refund the charge). Compensation is the
+ * `{ do, undo }` pair of `@demlik/tea/saga` mapped onto the workflow: the step's
+ * `activity` is the `do`, its `compensation` is the `undo`. The pair is the unit
+ * of reversibility — a step that completed (its forward activity succeeded) is
+ * exactly a step whose `compensation` must run, in reverse order, if a LATER
+ * step fails (#125). A step WITHOUT a compensation contributes nothing to the
+ * unwind: it is skipped during the reverse walk (an irreversible step — a sent
+ * email — that the saga model treats as a no-op `undo`).
+ */
+interface WorkflowStep<A> {
+    /** Stable, human-readable step name — appears in the completed-step record. */
+    readonly name: string;
+    /** The opaque activity this step performs. Interpreted by the consumer. */
+    readonly activity: A;
+    /**
+     * The opaque compensating (inverse) activity, performed in reverse order on a
+     * downstream failure (#125). Optional: a step with no compensation is skipped
+     * during the unwind. Interpreted by the consumer's interpret cell, exactly
+     * like {@link activity}.
+     */
+    readonly compensation?: A;
+}
+/**
+ * A completed step: the step that ran plus the result its activity produced.
+ * The `running` state accumulates these in execution order, so the full
+ * forward history is available to the consumer (and to #125's compensation,
+ * which will walk it in reverse).
+ */
+interface CompletedStep<A, R> {
+    readonly step: WorkflowStep<A>;
+    readonly result: R;
+}
+/** The activity currently in flight on a `running` workflow. */
+interface InFlightActivity<A> {
+    /** The 0-based index of this step in the workflow's step sequence. */
+    readonly index: number;
+    /** The step whose activity is in flight. */
+    readonly step: WorkflowStep<A>;
+    /** The #67 ledger delivery id this activity was owed under (the dedup key). */
+    readonly id: DeliveryId;
+}
+/**
+ * The compensation currently in flight on a `compensating` workflow (#125). The
+ * mirror of {@link InFlightActivity} for the reverse walk: exactly one
+ * compensation is owed at a time, on the SAME #67 ledger, with its own monotonic
+ * delivery id. `index` is the index (into `completed`/`steps`) of the step being
+ * undone — the unwind walks these from high to low (strict reverse order).
+ */
+interface InFlightCompensation<A> {
+    /** The 0-based index (into the step sequence) of the step being compensated. */
+    readonly index: number;
+    /** The step whose compensation is in flight. */
+    readonly step: WorkflowStep<A>;
+    /** The #67 ledger delivery id this compensation was owed under (the dedup key). */
+    readonly id: DeliveryId;
+}
+/**
+ * A workflow in progress. Carries the ordered `completed` steps (forward
+ * history), the `steps` it is sequencing, and the `current` in-flight activity
+ * (with its ledger delivery id). `completed.length === current.index` always
+ * holds — the current activity is the next step after the last completed one.
+ */
+interface RunningWorkflow<A, R> {
+    readonly status: "running";
+    /** The full, static step sequence this workflow runs. */
+    readonly steps: readonly WorkflowStep<A>[];
+    /** Steps that have produced a result, in execution order. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The single activity in flight right now. */
+    readonly current: InFlightActivity<A>;
+}
+/**
+ * A workflow that ran every step to completion. `output` is the result of the
+ * final step — the workflow's overall output. No activity is in flight.
+ */
+interface CompletedWorkflow<A, R> {
+    readonly status: "completed";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** Every step, in execution order, with its result. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The final step's result — the workflow's output. */
+    readonly output: R;
+}
+/**
+ * A workflow that failed on an activity with NOTHING to compensate — the
+ * forward failure happened with zero completed steps (the first activity
+ * failed). `failedStep` is the step whose activity reported the failure;
+ * `failure` is the opaque failure payload. `completed` is empty by construction:
+ * a failure WITH completed steps pivots into {@link CompensatingWorkflow}
+ * instead, so `failed` is precisely the empty-rollback terminal (the analogue
+ * of saga's `aborted` reached straight from the first step). No activity is in
+ * flight; this is terminal (#125 acceptance criterion 3).
+ */
+interface FailedWorkflow<A, R, F> {
+    readonly status: "failed";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** Empty by construction — a failure with completed steps compensates instead. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The step whose activity failed. */
+    readonly failedStep: WorkflowStep<A>;
+    /** The opaque failure the activity reported. */
+    readonly failure: F;
+}
+/**
+ * A workflow unwinding after a forward failure (#125): the compensations of the
+ * `completed` steps are being emitted in STRICT REVERSE order, one at a time, on
+ * the same #67 ledger. The analogue of saga's `compensating` phase.
+ *
+ * `current` is the single compensation in flight (the mirror of `running`'s
+ * in-flight activity). `compensated` records, in unwind order, the completed
+ * steps whose compensation has confirmed — the reverse-walk's progress log, so
+ * a cold wake resumes mid-rollback exactly. `failedStep`/`failure` carry the
+ * forward failure that triggered the unwind (verbatim, never interpreted),
+ * preserved for the consumer to read and to fold onto the terminal state.
+ *
+ * Invariant: the unwind walks `completed` from its tail toward index 0, skipping
+ * steps with no compensation, so `current.index` is strictly below the index of
+ * every entry in `compensated`.
+ */
+interface CompensatingWorkflow<A, R, F> {
+    readonly status: "compensating";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** The completed forward steps, in execution order — the history being unwound. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The step whose forward activity failed, triggering the unwind. */
+    readonly failedStep: WorkflowStep<A>;
+    /** The opaque forward failure that triggered the unwind. Carried, never interpreted. */
+    readonly failure: F;
+    /** The single compensation in flight right now. */
+    readonly current: InFlightCompensation<A>;
+    /** Completed steps whose compensation has confirmed, in unwind (reverse) order. */
+    readonly compensated: readonly CompletedStep<A, R>[];
+}
+/**
+ * A workflow that failed forward and then fully unwound: every completed step's
+ * compensation confirmed, in reverse order. Terminal. The analogue of saga's
+ * `aborted` (fully unwound) — named `failed_compensated` to align with #125's
+ * vocabulary. No activity or compensation is in flight.
+ */
+interface FailedCompensatedWorkflow<A, R, F> {
+    readonly status: "failed_compensated";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** The forward steps that completed (and were each compensated), in execution order. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The step whose forward activity failed, triggering the (now-finished) unwind. */
+    readonly failedStep: WorkflowStep<A>;
+    /** The opaque forward failure that triggered compensation. Carried, never interpreted. */
+    readonly failure: F;
+}
+/**
+ * A workflow whose ROLLBACK itself failed: a compensation activity reported a
+ * failure mid-unwind. Terminal, PARTIALLY unwound — the analogue of saga's
+ * `compensation_failed`. A failed compensation is a real-world fact (a refund
+ * that bounced, a hold that won't release) that must become visible terminal
+ * state, never a workflow wedged in `compensating` forever.
+ *
+ * `compensated` is left intact (the steps already rolled back); `uncompensated`
+ * is the step whose compensation bounced PLUS the steps still owed a
+ * compensation behind it — exactly what the consumer must reconcile by hand.
+ * `compensationFailure` is the rollback failure (distinct from `failure`, the
+ * forward failure that started the unwind), carried verbatim.
+ */
+interface CompensationFailedWorkflow<A, R, F> {
+    readonly status: "compensation_failed";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** The full completed-forward history, in execution order. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The step whose forward activity failed, triggering the unwind. */
+    readonly failedStep: WorkflowStep<A>;
+    /** The opaque forward failure that triggered compensation. Carried, never interpreted. */
+    readonly failure: F;
+    /** Completed steps successfully compensated before the rollback broke, in unwind order. */
+    readonly compensated: readonly CompletedStep<A, R>[];
+    /** The step whose compensation bounced. Its forward effect stands un-reversed. */
+    readonly failedCompensationStep: WorkflowStep<A>;
+    /** The opaque rollback failure (distinct from {@link failure}). Carried, never interpreted. */
+    readonly compensationFailure: F;
+}
+/**
+ * The workflow's state — a discriminated union on `status`. The current
+ * in-flight activity is reachable ONLY through `running`, and the in-flight
+ * compensation ONLY through `compensating`, making "an in-flight effect exists
+ * only while the workflow is actively driving one" unrepresentable to violate.
+ */
+type WorkflowState<A, R, F> = RunningWorkflow<A, R> | CompletedWorkflow<A, R> | FailedWorkflow<A, R, F> | CompensatingWorkflow<A, R, F> | FailedCompensatedWorkflow<A, R, F> | CompensationFailedWorkflow<A, R, F>;
+/**
+ * Dispatch the in-flight activity. Routed through the consumer's `interpret`
+ * over an injected activity port. The reducer emits this literal; it performs
+ * no side effect. The result MUST be dispatched back as a Msg carrying `id`.
+ */
+interface ActivityCmd<A> extends Cmd<"workflow_activity"> {
+    /** The 0-based step index this activity belongs to. */
+    readonly index: number;
+    /** The #67 delivery id the result Msg must echo (the dedup key). */
+    readonly id: DeliveryId;
+    /** The opaque activity to perform. */
+    readonly activity: A;
+}
+/**
+ * Dispatch a compensation (#125). Same shape + ledger discipline as
+ * {@link ActivityCmd} — a compensation is just another durable owed effect on
+ * the same #67 ledger, with its own delivery id — but the consumer's interpret
+ * cell performs the inverse `compensation` payload, and the result is dispatched
+ * back as a {@link CompensationOk}/{@link CompensationErr} carrying the SAME id.
+ * Distinguished by `type` so the consumer routes forward vs. inverse work to the
+ * right port, and the re-emit-on-wake stays type-correct.
+ */
+interface CompensationCmd<A> extends Cmd<"workflow_compensation"> {
+    /** The 0-based step index whose compensation this is. */
+    readonly index: number;
+    /** The #67 delivery id the result Msg must echo (the dedup key). */
+    readonly id: DeliveryId;
+    /** The opaque compensating (inverse) activity to perform. */
+    readonly compensation: A;
+}
+/** The Cmd union this module emits: forward activity dispatches AND (#125)
+ *  reverse compensation dispatches. The owed/confirmed ledger events are not
+ *  `WorkflowCmd`s — they are Msg variants persisted into the event log (see
+ *  {@link EffectLedgerEvent}); the {@link WorkflowStep0} tuple carries them out
+ *  alongside the dispatch Cmd so the host persists owed-before-dispatch. Both
+ *  Cmd kinds are owed effects on the same ledger, so `survivingActivities`
+ *  re-emits either kind on cold wake. */
+type WorkflowCmd<A> = ActivityCmd<A> | CompensationCmd<A>;
+/** An activity succeeded: `id` echoes the {@link ActivityCmd} it answers; the
+ *  reducer matches it against `current.id`, records the completed step, and
+ *  advances. */
+interface ActivityOk<R> {
+    readonly type: "activity_ok";
+    readonly id: DeliveryId;
+    readonly result: R;
+}
+/** An activity failed (retries already exhausted by the consumer's interpret
+ *  cell — this module does not retry). `id` echoes the {@link ActivityCmd};
+ *  the reducer begins compensation (or settles `failed` when nothing has
+ *  completed). */
+interface ActivityErr<F> {
+    readonly type: "activity_err";
+    readonly id: DeliveryId;
+    readonly failure: F;
+}
+/** A compensation succeeded (#125): the inverse activity took. `id` echoes the
+ *  {@link CompensationCmd} it answers; the reducer matches it against the
+ *  in-flight compensation's id, records the step as compensated, and either
+ *  emits the next compensation (continuing in reverse) or settles
+ *  `failed_compensated` when the unwind is complete. A compensation produces no
+ *  result the workflow carries — its only signal is "the undo took". */
+interface CompensationOk {
+    readonly type: "compensation_ok";
+    readonly id: DeliveryId;
+}
+/** A compensation itself failed (#125): the inverse activity bounced (a refund
+ *  that won't go through). `id` echoes the {@link CompensationCmd}; the reducer
+ *  halts the rollback at the terminal `compensation_failed` state — never wedged
+ *  in `compensating` forever. */
+interface CompensationErr<F> {
+    readonly type: "compensation_err";
+    readonly id: DeliveryId;
+    readonly failure: F;
+}
+/** The Msg union the reducer folds: forward activity results AND (#125) reverse
+ *  compensation results. */
+type WorkflowMsg<R, F> = ActivityOk<R> | ActivityErr<F> | CompensationOk | CompensationErr<F>;
+/** A workflow reducer step: the next state, the ledger events to persist
+ *  (owed-before-dispatch), and the activity Cmds to dispatch. */
+interface WorkflowStep0<A, R, F> {
+    readonly state: WorkflowState<A, R, F>;
+    /** Ledger events to persist into the event log, in order, BEFORE `cmds`. */
+    readonly ledger: readonly EffectLedgerEvent<WorkflowCmd<A>>[];
+    /** Activity dispatch Cmds, after the ledger events are durable. */
+    readonly cmds: readonly WorkflowCmd<A>[];
+}
+/** The hook bag returned by {@link createWorkflow}. Spread its verbs into a
+ *  machine; `init(steps)` seeds a fresh workflow and emits the first activity,
+ *  the verbs fold results and advance, and `survivingActivities` re-emits the
+ *  owed-but-unconfirmed dispatch on cold wake (idempotent by delivery id). */
+interface Workflow<A, R, F> {
+    /**
+     * Seed a fresh workflow over `steps` and dispatch its first activity.
+     *
+     * - Empty `steps` ⇒ a workflow with nothing to do completes only when it has
+     *   an output; with no steps there is no output, so an empty sequence is
+     *   rejected as a misuse (a workflow must have at least one step). The reducer
+     *   never reaches `completed` without a final result to carry.
+     * - Otherwise → `running` with `current` = step 0, owed on the ledger.
+     */
+    init(steps: readonly WorkflowStep<A>[]): WorkflowStep0<A, R, F>;
+    /**
+     * Fold an activity success. If `msg.id` does not match the in-flight
+     * activity's id (a stale/duplicate result from re-emit-on-wake, or a result
+     * for an already-advanced step), the state is returned UNCHANGED with no
+     * effects — idempotent by delivery id (acceptance criterion 3). Otherwise:
+     * record the completed step, confirm the owed activity on the ledger, and
+     * either advance to the next step (owing its activity) or transition to
+     * `completed` carrying the final result.
+     *
+     * Only meaningful on `running`; a result arriving for a terminal workflow is
+     * a no-op (the workflow is done — at-least-once tolerates the late echo).
+     */
+    onActivityOk(state: WorkflowState<A, R, F>, msg: ActivityOk<R>): WorkflowStep0<A, R, F>;
+    /**
+     * Fold an activity failure (#125). Same id-match idempotency guard as
+     * {@link onActivityOk}. On a match: confirm the owed activity on the ledger,
+     * then PIVOT into compensation — walk the completed-step history in strict
+     * reverse and owe the first declared compensation as a durable effect on the
+     * same ledger, transitioning to `compensating`. If NO completed step declares
+     * a compensation (the empty-rollback edge — the first activity failed, or
+     * every completed step is irreversible), settle `failed` directly with
+     * nothing to unwind.
+     */
+    onActivityErr(state: WorkflowState<A, R, F>, msg: ActivityErr<F>): WorkflowStep0<A, R, F>;
+    /**
+     * Fold a compensation success (#125). Same id-match idempotency guard against
+     * the in-flight compensation. On a match: confirm the owed compensation,
+     * record the step as compensated, and continue the reverse walk — owe the
+     * next declared compensation strictly below the step just undone, or settle
+     * `failed_compensated` when the unwind is complete. Only meaningful on
+     * `compensating`; a result for a terminal/forward workflow is a no-op.
+     */
+    onCompensationOk(state: WorkflowState<A, R, F>, msg: CompensationOk): WorkflowStep0<A, R, F>;
+    /**
+     * Fold a compensation failure (#125). Same id-match idempotency guard. On a
+     * match: confirm the owed compensation and HALT the rollback at the terminal
+     * `compensation_failed` state — a bounced compensation is visible terminal
+     * state to reconcile by hand, never a workflow wedged in `compensating`
+     * forever. Mirrors `@demlik/tea/saga`'s `undoErr`.
+     */
+    onCompensationErr(state: WorkflowState<A, R, F>, msg: CompensationErr<F>): WorkflowStep0<A, R, F>;
+    /**
+     * The owed-but-unconfirmed dispatch(es) to re-emit on activation — a forward
+     * activity OR (#125) a compensation, rebuilt by folding the persisted ledger
+     * events. On a fresh / fully-settled workflow this is empty. The re-fired Cmd
+     * carries the SAME delivery id, so a duplicate result is a no-op at the
+     * reducer (the id-match guard). This is the cold-wake re-emit that makes both
+     * activities AND compensations exactly-once-observable despite the
+     * at-least-once transport (acceptance criterion 2 & 3) — including a
+     * compensation owed mid-rollback when the actor was evicted.
+     */
+    survivingActivities(ledgerEvents: Iterable<EffectLedgerEvent<WorkflowCmd<A>>>): readonly WorkflowCmd<A>[];
+}
+/**
+ * Build a workflow hook bag. The factory captures NO clock and NO RNG — pure
+ * bookkeeping over the injected #67 recorder, exactly like
+ * `pendingEffectsLedger`. `restore` rehydrates the monotonic delivery-id
+ * counter from the persisted ledger events on cold wake, so re-dispatched
+ * activities resume their ids without gaps.
+ *
+ * @param restore - the persisted ledger events (read back from the log) and/or
+ *   the last issued delivery id, so the id counter resumes gap-free. Omit for a
+ *   fresh workflow.
+ */
+declare function createWorkflow<A, R, F>(restore?: {
+    readonly events?: Iterable<EffectLedgerEvent<WorkflowCmd<A>>>;
+    readonly lastId?: DeliveryId;
+}): Workflow<A, R, F>;
+/**
+ * Replay a workflow from its event log: seed over `steps`, then fold each
+ * activity-result `Msg` in order. Returns the final {@link WorkflowState}.
+ *
+ * Determinism: a freshly-constructed {@link createWorkflow} reissues delivery
+ * ids monotonically from 0, and the reducer reads no ambient state — so two
+ * calls with the same `steps` + `msgs` return deeply-equal states (and equal
+ * `JSON.stringify`). This is the byte-identity property #124 pins.
+ *
+ * Note this folds ONLY the result Msgs; the `init` dispatch + per-step
+ * owe/confirm ledger events are an internal effect channel reconstructed by the
+ * fresh recorder, not part of the replayed Msg log — exactly as the activity
+ * results are the only thing the consumer records and replays.
+ */
+declare function foldWorkflow<A, R, F>(steps: readonly WorkflowStep<A>[], msgs: Iterable<WorkflowMsg<R, F>>): WorkflowState<A, R, F>;
+
+export { type ActivityCmd, type ActivityErr, type ActivityOk, type CompensatingWorkflow, type CompensationCmd, type CompensationErr, type CompensationFailedWorkflow, type CompensationOk, type CompletedStep, type CompletedWorkflow, DeliveryId, EffectLedgerEvent, type FailedCompensatedWorkflow, type FailedWorkflow, type InFlightActivity, type InFlightCompensation, type RunningWorkflow, type Workflow, type WorkflowCmd, type WorkflowMsg, type WorkflowState, type WorkflowStep, type WorkflowStep0, createWorkflow, foldWorkflow };

package/dist/workflow/index.js

@@ -0,0 +1,225 @@
+import { pendingEffectsLedger, foldLedger, survivingEffects } from '../chunk-3545BOYL.js';
+export { emptyLedger } from '../chunk-3545BOYL.js';
+
+// src/workflow/index.ts
+function createWorkflow(restore) {
+  const recorder = pendingEffectsLedger(restore);
+  function stepAt(steps, index) {
+    const step = steps[index];
+    if (step === void 0) {
+      throw new Error(
+        `createWorkflow: step index ${index} out of range (length ${steps.length}) \u2014 a reducer bounds proof was violated.`
+      );
+    }
+    return step;
+  }
+  function oweOnLedger(build) {
+    const id = recorder.lastId() + 1;
+    const cmd = build(id);
+    const { id: issued, event } = recorder.owe(cmd);
+    if (issued !== id) {
+      throw new Error(
+        `createWorkflow: delivery-id prediction (${id}) diverged from the recorder's issued id (${issued}). The #67 recorder's monotonic counter is not gap-free as assumed \u2014 this is a substrate invariant violation, not a recoverable condition.`
+      );
+    }
+    return { id, owed: event, cmd };
+  }
+  function oweActivity(step, index) {
+    const { id, owed, cmd } = oweOnLedger((id2) => ({
+      type: "workflow_activity",
+      index,
+      id: id2,
+      activity: step.activity
+    }));
+    const current = { index, step, id };
+    return { current, owed, cmd };
+  }
+  function oweCompensation(step, compensation, index) {
+    const { id, owed, cmd } = oweOnLedger((id2) => ({
+      type: "workflow_compensation",
+      index,
+      id: id2,
+      compensation
+    }));
+    const current = { index, step, id };
+    return { current, owed, cmd };
+  }
+  function oweNextCompensation(completed, belowIndex) {
+    for (let i = belowIndex - 1; i >= 0; i--) {
+      const entry = completed[i];
+      if (entry !== void 0 && entry.step.compensation !== void 0) {
+        return oweCompensation(entry.step, entry.step.compensation, i);
+      }
+    }
+    return null;
+  }
+  return {
+    init(steps) {
+      if (steps.length === 0) {
+        throw new Error(
+          "createWorkflow.init: a workflow must have at least one step. An empty step sequence has no final result to carry into `completed`, so it is unrepresentable as a completed workflow \u2014 reject it at the boundary rather than admit a resultless terminal state."
+        );
+      }
+      const { current, owed, cmd } = oweActivity(stepAt(steps, 0), 0);
+      const state = {
+        status: "running",
+        steps,
+        completed: [],
+        current
+      };
+      return { state, ledger: [owed], cmds: [cmd] };
+    },
+    onActivityOk(state, msg) {
+      if (state.status !== "running" || msg.id !== state.current.id) {
+        return { state, ledger: [], cmds: [] };
+      }
+      const confirmed = confirm(state.current.id);
+      const completedStep = {
+        step: state.current.step,
+        result: msg.result
+      };
+      const completed = [...state.completed, completedStep];
+      const nextIndex = state.current.index + 1;
+      if (nextIndex >= state.steps.length) {
+        const done = {
+          status: "completed",
+          steps: state.steps,
+          completed,
+          output: msg.result
+        };
+        return { state: done, ledger: [confirmed], cmds: [] };
+      }
+      const { current, owed, cmd } = oweActivity(
+        stepAt(state.steps, nextIndex),
+        nextIndex
+      );
+      const running = {
+        status: "running",
+        steps: state.steps,
+        completed,
+        current
+      };
+      return { state: running, ledger: [confirmed, owed], cmds: [cmd] };
+    },
+    onActivityErr(state, msg) {
+      if (state.status !== "running" || msg.id !== state.current.id) {
+        return { state, ledger: [], cmds: [] };
+      }
+      const confirmed = confirm(state.current.id);
+      const next = oweNextCompensation(state.completed, state.completed.length);
+      if (next === null) {
+        const failed = {
+          status: "failed",
+          steps: state.steps,
+          completed: state.completed,
+          failedStep: state.current.step,
+          failure: msg.failure
+        };
+        return { state: failed, ledger: [confirmed], cmds: [] };
+      }
+      const compensating = {
+        status: "compensating",
+        steps: state.steps,
+        completed: state.completed,
+        failedStep: state.current.step,
+        failure: msg.failure,
+        current: next.current,
+        compensated: []
+      };
+      return {
+        state: compensating,
+        ledger: [confirmed, next.owed],
+        cmds: [next.cmd]
+      };
+    },
+    onCompensationOk(state, msg) {
+      if (state.status !== "compensating" || msg.id !== state.current.id) {
+        return { state, ledger: [], cmds: [] };
+      }
+      const confirmed = confirm(state.current.id);
+      const undoneStep = state.completed[state.current.index];
+      if (undoneStep === void 0) {
+        throw new Error(
+          `createWorkflow.onCompensationOk: compensation index ${state.current.index} has no completed step \u2014 a reverse-walk bounds proof was violated.`
+        );
+      }
+      const compensated = [...state.compensated, undoneStep];
+      const next = oweNextCompensation(state.completed, state.current.index);
+      if (next === null) {
+        const settled = {
+          status: "failed_compensated",
+          steps: state.steps,
+          completed: state.completed,
+          failedStep: state.failedStep,
+          failure: state.failure
+        };
+        return { state: settled, ledger: [confirmed], cmds: [] };
+      }
+      const compensating = {
+        status: "compensating",
+        steps: state.steps,
+        completed: state.completed,
+        failedStep: state.failedStep,
+        failure: state.failure,
+        current: next.current,
+        compensated
+      };
+      return {
+        state: compensating,
+        ledger: [confirmed, next.owed],
+        cmds: [next.cmd]
+      };
+    },
+    onCompensationErr(state, msg) {
+      if (state.status !== "compensating" || msg.id !== state.current.id) {
+        return { state, ledger: [], cmds: [] };
+      }
+      const confirmed = confirm(state.current.id);
+      const halted = {
+        status: "compensation_failed",
+        steps: state.steps,
+        completed: state.completed,
+        failedStep: state.failedStep,
+        failure: state.failure,
+        compensated: state.compensated,
+        failedCompensationStep: state.current.step,
+        compensationFailure: msg.failure
+      };
+      return { state: halted, ledger: [confirmed], cmds: [] };
+    },
+    survivingActivities(ledgerEvents) {
+      const ledger = foldLedger(ledgerEvents);
+      return survivingEffects(ledger).map((owed) => owed.effect);
+    }
+  };
+  function confirm(id) {
+    return recorder.confirm(id).event;
+  }
+}
+function foldWorkflow(steps, msgs) {
+  const wf = createWorkflow();
+  let { state } = wf.init(steps);
+  for (const msg of msgs) {
+    let step;
+    switch (msg.type) {
+      case "activity_ok":
+        step = wf.onActivityOk(state, msg);
+        break;
+      case "activity_err":
+        step = wf.onActivityErr(state, msg);
+        break;
+      case "compensation_ok":
+        step = wf.onCompensationOk(state, msg);
+        break;
+      case "compensation_err":
+        step = wf.onCompensationErr(state, msg);
+        break;
+    }
+    state = step.state;
+  }
+  return state;
+}
+
+export { createWorkflow, foldWorkflow };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map