@voltro/workflow 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Cause } from 'effect';
 import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
 import { DurableClock as durableClock } from '@effect/workflow';
 import { DurableQueue as durableQueueModule } from '@effect/workflow';
 import { DurableRateLimiter as durableRateLimiterModule } from '@effect/workflow';
@@ -446,6 +447,54 @@ export declare interface AwaitUpdateOptions<A, B = A> {
     readonly timeoutMs?: number;
 }
 
+export declare const BUDGET_HOLDS_TABLE = "_voltro_budget_holds";
+
+/** Raised into the workflow when a hold outlived its ceiling. */
+export declare class BudgetHoldExpired extends Error {
+    readonly budget: string;
+    readonly holdKey: string;
+    constructor(budget: string, holdKey: string, timeoutMs: number);
+}
+
+/** How many holds this (execution, step, budget) has already taken. */
+export declare const budgetHoldGeneration: (store: DataStore, input: {
+    readonly executionId: string;
+    readonly stepName: string;
+    readonly budget: string;
+}) => Promise<number>;
+
+/**
+ * The replay-stable identity of one hold within one run.
+ *
+ * The `generation` is the part that is easy to leave out and fatal to leave out.
+ * A run can be held MORE THAN ONCE at the same step: it is released, the body
+ * replays, it re-reads the counter, and the budget is still over — because the
+ * window rolled for a tenant that immediately spent again, or because an
+ * operator lifted the wrong hold. With a generation-free key the second park
+ * would await the deferred the FIRST release had already completed, get an
+ * instant resolution, and spend straight through a budget that was still
+ * exceeded — the AI-Flows constant-signal-name collision, one level up and with
+ * money on the other side of it.
+ *
+ * `generation` is the number of holds already recorded for this
+ * (execution, step, budget), which is durable, monotone, and unchanged by a
+ * crash-replay that took no new hold — so it is stable exactly when replay
+ * safety needs it to be and different exactly when correctness needs it to be.
+ */
+export declare const budgetHoldKey: (input: {
+    readonly executionId: string;
+    readonly stepName: string;
+    readonly budget: string;
+    readonly generation: number;
+}) => string;
+
+/**
+ * The signal name ONE hold parks on. Derived from the hold key, so the releaser
+ * reconstructs it from the row with no shared state — the same discipline
+ * `suspendingSignalDeferredName` and `humanResponseSignalName` follow.
+ */
+export declare const budgetHoldSignalName: (holdKey: string) => string;
+
 export declare const CANCEL_ON_WATERMARK = "cancelOn";
 
 export declare interface CancelDecision {
@@ -659,6 +708,29 @@ export declare interface CompleteSuspendingSignalInput {
  *  engine-assigned executionId, not our row id. */
 export declare const CurrentWorkflowExecutionId: FiberRef.FiberRef<string | undefined>;
 
+/**
+ * FiberRef carrying the patch markers that were declared on the workflow at the
+ * moment THIS RUN STARTED — read back from `_voltro_workflow_runs.
+ * workflowPatches` on a resume, taken from the current declaration on a first
+ * start. This is what makes `patch('id')` (see `primitives.ts`) answer the
+ * Temporal question "was this marker in effect when this execution began?"
+ * rather than "is it in the code I am running now".
+ *
+ * Empty outside a recorded workflow body, so `patch()` is `false` there — the
+ * safe direction: an un-recorded context gets the PRE-patch branch.
+ */
+export declare const CurrentWorkflowPatches: FiberRef.FiberRef<readonly string[]>;
+
+/**
+ * The tracker for the CURRENT body entry, or `undefined` when there is nothing
+ * to compare against.
+ *
+ * Installed by `wrapWorkflowExecuteWithRunRecording` ONLY on a re-entry (a run
+ * whose row already exists). A first entry has no prior shape, so the whole
+ * mechanism costs one `FiberRef` read per step and nothing else.
+ */
+export declare const CurrentWorkflowReplayShape: FiberRef.FiberRef<ReplayShapeTracker | undefined>;
+
 /** FiberRef carrying the active workflow run's id. The outer
  *  `wrapWithRunRecording` in dev.ts sets it via
  *  `Effect.locally(CurrentWorkflowRunId, runId)`. */
@@ -697,6 +769,11 @@ declare type DecodedPayload<P> = P extends Schema.Struct.Fields ? Schema.Struct.
     readonly Type: infer T;
 } ? T : never;
 
+/** Default ceiling on a hold — 7 days, matching the HITL park bound. The wait
+ *  itself is free (no worker is held), and a run that gives up on a monthly
+ *  budget after an hour is a run somebody has to re-drive by hand. */
+export declare const DEFAULT_BUDGET_HOLD_TIMEOUT_MS: number;
+
 /** How far back a COLD start looks when no watermark exists yet — one hour.
  *  Not the whole journal: a first boot against an old deployment would
  *  otherwise read every event ever published to decide about runs that mostly
@@ -727,6 +804,33 @@ export declare const DEFAULT_EVENT_BATCH = 500;
  */
 export declare const DEFAULT_LEASE_MS: number;
 
+/** Consecutive runner deaths a single run may cost before it is parked. Three,
+ *  not one: a single crash is frequently the node and not the payload, and
+ *  parking on it would turn every spot-instance eviction into an operator
+ *  ticket. Three in a row is a property of the work. */
+export declare const DEFAULT_MAX_RUN_RECLAIMS = 3;
+
+/** Recorded step rows the replay-shape snapshot will load for one run. */
+export declare const DEFAULT_REPLAY_SHAPE_LIMIT = 2000;
+
+/** How long a live run may make no progress before it is reported.
+ *
+ *  Thirty minutes, not five: the population this must not drown in is
+ *  long-running steps (a big import, a slow provider), and a threshold under
+ *  the longest legitimate step turns the feature into noise. Runs that wait
+ *  legitimately for HOURS wait on a durable timer, which is excluded outright,
+ *  so the threshold only has to clear the slowest single step. */
+export declare const DEFAULT_STALL_AFTER_MS: number;
+
+/** Lifecycle events read per candidate. Enough to see the timer handshake and
+ *  a prior `run-stalled` on a run that is, by construction, not doing much. */
+export declare const DEFAULT_STALL_EVENT_LOOKBACK = 20;
+
+/** Live runs examined per tick. Bounded for the reason every sweep here is:
+ *  oldest-first, so a deployment past the bound makes progress on the next
+ *  tick instead of re-reading the same page. */
+export declare const DEFAULT_STALL_RUN_PAGE = 200;
+
 export declare type DeferMode = DeferringControl | 'paused';
 
 /**
@@ -917,6 +1021,13 @@ export declare const hasCancelOn: (control: ResolvedFlowControl | undefined) =>
  *  two writes per start for a decision that is always "admit". */
 export declare const hasFlowControl: (control: ResolvedFlowControl | undefined) => boolean;
 
+/** The distinct budgets currently holding at least one run — what a poller
+ *  iterates so it asks about nothing else. */
+export declare const heldBudgets: (store: DataStore) => Promise<ReadonlyArray<{
+    readonly budget: string;
+    readonly tenantId: string | null;
+}>>;
+
 export declare interface InMemoryRecorder {
     readonly layer: Layer.Layer<WorkflowRunRecorder>;
     readonly readSteps: () => ReadonlyArray<RecordedStep>;
@@ -1019,6 +1130,17 @@ export declare const linkExecution: (store: AdmissionDataStore, ledgerId: string
 
 export declare const makeInMemoryRecorder: () => InMemoryRecorder;
 
+/**
+ * Build a tracker from the step rows this run recorded on EARLIER body entries.
+ *
+ * Pass the rows as they are: one row per step ATTEMPT, so a step that retried
+ * three times contributes three. Counting rows rather than distinct names is
+ * what makes the per-name sequence rule work, and the asymmetry is deliberate —
+ * only reaching a name MORE often than recorded is a finding. Fewer is normal
+ * (a crash mid-step records two rows for one logical reach).
+ */
+export declare const makeReplayShapeTracker: (recordedRows: ReadonlyArray<RecordedStepShape>) => ReplayShapeTracker;
+
 export declare const makeWorkflowRunRecorder: (options: WorkflowRunRecorderOptions) => WorkflowRunRecorderService;
 
 export declare const makeWorkflowUpdateId: () => string;
@@ -1051,6 +1173,23 @@ export declare const newestEventAt: (events: ReadonlyArray<DomainEventRow>) => D
  */
 export declare const nextSlotAt: (recentAdmissions: ReadonlyArray<number>, limit: number, periodMs: number, now: number) => number | undefined;
 
+/** The `nondeterminism-suspected` event body. Kept here so the two emit sites
+ *  (the step wrapper, and the run wrapper's `settle`) cannot drift. */
+export declare const nondeterminismEventPayload: (finding: NondeterminismFinding) => Record<string, unknown>;
+
+export declare interface NondeterminismFinding {
+    readonly kind: NondeterminismKind;
+    readonly stepName: string;
+    /** How many rows this run recorded for `stepName` on EARLIER body entries. */
+    readonly recorded: number;
+    /** How many times the CURRENT body entry reached it. */
+    readonly reached: number;
+    /** One sentence an operator can act on, without opening the code. */
+    readonly detail: string;
+}
+
+export declare type NondeterminismKind = 'unreached-step' | 'extra-step-occurrence';
+
 declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefined> = {
     readonly signals: M extends {
         readonly signals: infer Signals;
@@ -1058,13 +1197,68 @@ declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefi
     readonly updates: M extends {
         readonly updates: infer Updates;
     } ? NonNullable<Updates> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
-    readonly queries: M extends {
-        readonly queries: infer Queries;
-    } ? NonNullable<Queries> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
 };
 
+/** `workflowPatches` comes back off a `json()` column, so it is whatever the
+ *  dialect's driver decoded — an array, a JSON string, or null. Anything that
+ *  is not a list of strings means "no markers", which is the safe answer:
+ *  `patch()` then reports the PRE-patch branch. */
+export declare const normaliseWorkflowPatches: (value: unknown) => ReadonlyArray<string> | undefined;
+
 export declare const noteIntentAttempt: (store: AdmissionDataStore, intent: PendingIntent, error: string, now: number) => Promise<void>;
 
+/**
+ * Is a named change marker in effect for the run currently executing?
+ *
+ * This is the escape valve for the versioning trap. `compatibleWith` is
+ * all-or-nothing: leave an old version out and every in-flight run on it is
+ * terminally failed; leave it in and the old runs replay against the new body
+ * with no detection. `patch` is the third option — the body itself branches, so
+ * runs that started BEFORE the change keep taking the old path to completion
+ * while new runs take the new one.
+ *
+ * ```ts
+ * export const Charge = workflow({
+ *   name: 'billing.charge',
+ *   payload: { orderId: Schema.String },
+ *   idempotencyKey: ({ orderId }) => `billing.charge:${orderId}`,
+ *   patches: ['split-tax-calculation'],       // ← declare it
+ * })
+ *
+ * // inside the body:
+ * if (yield* patch('split-tax-calculation')) {
+ *   const net = yield* step({ name: 'net-total', execute })
+ *   const tax = yield* step({ name: 'tax', execute })
+ *   return net + tax
+ * }
+ * return yield* step({ name: 'total', execute })   // the pre-patch path
+ * ```
+ *
+ * ── The answer is pinned to the RUN, not to the code ────────────────────────
+ *
+ * `patches` is stamped onto `_voltro_workflow_runs.workflowPatches` when the
+ * run starts and read back from that row on every resume. So a run started
+ * before you added the marker answers `false` for the rest of its life,
+ * however many times it replays and whatever the deployed code says — which is
+ * the property that makes the branch deterministic across a redeploy.
+ *
+ * Under `@effect/workflow` the naive implementation does the opposite: an
+ * activity that is ABSENT from an old run's journal EXECUTES on replay (the
+ * journal is keyed name/attempt), so a marker journaled by an activity would
+ * answer `true` for exactly the old runs it must answer `false` for. Reading
+ * the run row sidesteps that entirely.
+ *
+ * ── Retiring a patch ───────────────────────────────────────────────────────
+ *
+ * Once no run predating the marker can still be in flight, delete the old
+ * branch and the entry from `patches`. Runs that stamped it keep the marker on
+ * their row for the audit trail; `patch()` simply stops being called.
+ *
+ * Outside a recorded workflow body (a unit test, a bare `step()` call) this is
+ * `false` — the pre-patch branch, which is the safe direction.
+ */
+export declare const patch: (id: string) => Effect.Effect<boolean>;
+
 export declare const PAUSES_TABLE = "_voltro_workflow_pauses";
 
 export declare const pauseWorkflow: (store: AdmissionDataStore, workflowName: string, by: string | null, reason: string | null) => Promise<void>;
@@ -1074,6 +1268,20 @@ declare type PayloadSchemaOf<P> = P extends Schema.Struct.Fields ? Schema.Struct
 
 export declare const PENDING_TABLE = "_voltro_workflow_pending";
 
+/** Every hold currently parked — the operator's view, and the poller's input. */
+export declare const pendingBudgetHolds: (store: DataStore, options?: {
+    readonly budget?: string;
+}) => Promise<ReadonlyArray<{
+    readonly id: string;
+    readonly holdKey: string;
+    readonly budget: string;
+    readonly tenantId: string | null;
+    readonly executionId: string;
+    readonly workflowName: string;
+    readonly stepName: string;
+    readonly heldAt: string;
+}>>;
+
 /** A pending row in domain shape. */
 export declare interface PendingIntent {
     readonly id: string;
@@ -1295,6 +1503,44 @@ export declare interface RecordedStep {
     durationMs: number | null;
 }
 
+/** The slice of a `_voltro_workflow_run_steps` row this needs. */
+export declare interface RecordedStepShape {
+    readonly stepName: string;
+}
+
+/**
+ * Resume every run parked on `budget`.
+ *
+ * Requires the `WorkflowEngine` — run it through the same runner that executes
+ * workflows (`workflowRuntime.runPromise`), exactly like `completeSuspendingSignal`.
+ *
+ * A release WAKES a run; it does not authorise a spend. The resumed body
+ * re-reads the budget and parks again on a fresh generation if it is still over
+ * — see `suspendForBudget`. So this is safe to call optimistically (on a
+ * `recovered` signal, or from an operator's console) without knowing whether
+ * every held run will actually proceed.
+ *
+ * The row is closed BEFORE the deferred is completed, deliberately: the resumed
+ * body counts existing holds to derive its next generation, and a row still
+ * reading `releasedAt: null` would make the re-park collide with the hold it was
+ * just released from.
+ */
+export declare const releaseBudgetHolds: (input: ReleaseBudgetHoldsInput) => Effect.Effect<{
+    readonly released: number;
+}, never, WorkflowEngine.WorkflowEngine>;
+
+export declare interface ReleaseBudgetHoldsInput {
+    readonly store: DataStore;
+    /** Which budget regained headroom. */
+    readonly budget: string;
+    /** Restrict to one tenant. Omitted → every tenant held on this budget (a
+     *  window rollover is per-tenant in the accountant but the counter key rotates
+     *  for everyone, so both shapes are legitimate). */
+    readonly tenantId?: string | null | undefined;
+    /** `released` = the budget itself recovered; `lifted` = an operator decided. */
+    readonly outcome?: 'released' | 'lifted';
+}
+
 /**
  * Free the slot an execution holds. Called when a run reaches a terminal state.
  *
@@ -1304,6 +1550,34 @@ export declare interface RecordedStep {
  */
 export declare const releaseLease: (store: AdmissionDataStore, executionId: string, now: number) => Promise<boolean>;
 
+export declare interface ReplayShapeTracker {
+    /**
+     * The body reached `stepName`. Returns a finding the FIRST time that reach
+     * is anomalous, `undefined` otherwise — so a step in a hot loop reports once
+     * rather than once per iteration.
+     */
+    readonly reach: (stepName: string) => NondeterminismFinding | undefined;
+    /**
+     * The body ran to a COMPLETE outcome. Returns the set-membership findings —
+     * recorded names the body never reached.
+     *
+     * Call this ONLY on success/failure, never on a suspend: a suspended body
+     * stopped partway through on purpose, so everything after the suspension
+     * point is legitimately unreached.
+     */
+    readonly settle: () => ReadonlyArray<NondeterminismFinding>;
+}
+
+/**
+ * Emit findings from INSIDE the workflow body, where the run id and the
+ * recorder are only reachable through the fiber context.
+ *
+ * Best-effort in the strongest sense: no recorder, no run id, or a rejecting
+ * write all resolve to "nothing happened". A tripwire that can break the run it
+ * is watching is not a tripwire.
+ */
+export declare const reportNondeterminism: (findings: ReadonlyArray<NondeterminismFinding>) => Effect.Effect<void>;
+
 /** Resolve every declared key against one payload. Pure; throws only
  *  {@link FlowControlKeyError}. */
 export declare const resolveAdmissionKeys: (control: ResolvedFlowControl, payload: unknown) => AdmissionKeys;
@@ -1376,6 +1650,20 @@ export declare interface ResolvedFlowControl {
     readonly cancelOn?: ReadonlyArray<ResolvedCancelOn>;
 }
 
+/**
+ * Read the run-guard knobs from the environment, for the boot paths to spread
+ * into {@link wrapWorkflowExecuteWithRunRecording}. Mirrors
+ * `resolveFailoverTuning` in `clusterLayer.ts` — same shape, same
+ * malformed-value-is-ignored rule, so an operator learns one convention:
+ *
+ * - `VOLTRO_WORKFLOW_MAX_RECLAIMS` (→ `maxRunReclaims`, default 3)
+ * - `VOLTRO_WORKFLOW_REPLAY_SHAPE_LIMIT` (→ `replayShapeLimit`, default 2000)
+ */
+export declare const resolveRunGuardTuning: () => {
+    maxRunReclaims?: number;
+    replayShapeLimit?: number;
+};
+
 export declare const resolveWorkflowMessageRun: (store: WorkflowMessageStore, target: WorkflowMessageTarget) => Promise<WorkflowResolvedRun>;
 
 export declare const resumeWorkflow: (store: AdmissionDataStore, workflowName: string) => Promise<boolean>;
@@ -1441,6 +1729,82 @@ export declare const sleepUntil: (options: {
     readonly until: Date | number;
 }) => Effect.Effect<void, never, never>;
 
+/** The narrow store slice this needs. Structural, like `CancelOnDataStore`. */
+export declare interface StalenessDataStore {
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
+}
+
+export declare interface StalenessSweepDeps {
+    readonly store: StalenessDataStore;
+    /**
+     * Record the `run-stalled` event. Wired to the run recorder's `recordEvent`.
+     * Absent → detection without a durable trace (the handler still fires), which
+     * is the right shape for a `voltro doctor` style one-shot check.
+     */
+    readonly recordEvent?: (input: {
+        readonly runId: string;
+        readonly eventType: 'run-stalled';
+        readonly payload: Record<string, unknown>;
+    }) => Promise<unknown>;
+    /** App-supplied reaction — page someone, open a ticket. Must not throw;
+     *  a rejection is collected as a failure and the sweep continues. */
+    readonly onStalled?: (run: StalledRun) => Promise<void>;
+    readonly now?: () => number;
+    readonly log?: {
+        readonly info: (message: string, fields?: Record<string, unknown>) => void;
+        readonly warn: (message: string, fields?: Record<string, unknown>) => void;
+    };
+}
+
+export declare interface StalenessSweepOptions {
+    readonly stallAfterMs?: number;
+    readonly runPage?: number;
+    readonly eventLookback?: number;
+}
+
+export declare interface StalenessSweepResult {
+    /** Live runs old enough to be worth examining. */
+    readonly examined: number;
+    /** Newly reported this tick. */
+    readonly stalled: ReadonlyArray<StalledRun>;
+    /** Stalled, but already reported since their last progress — reported
+     *  separately rather than folded into `stalled`, so a caller can tell "the
+     *  wedge persists" from "nothing is stuck". */
+    readonly alreadyReported: number;
+    /** Excluded because they are inside a durable timer that has not come due. */
+    readonly waitingOnTimer: number;
+    /** The candidate page filled up: more live old runs exist and the next tick
+     *  will reach them. Reported rather than inferred — the counts alone cannot
+     *  distinguish it from "nothing else was old". */
+    readonly sawFullRunPage: boolean;
+    readonly failures: ReadonlyArray<{
+        readonly subject: string;
+        readonly detail: string;
+    }>;
+}
+
+export declare interface StalledRun {
+    readonly runId: string;
+    readonly tag: string;
+    readonly executionId: string;
+    readonly status: string;
+    readonly lastProgressAt: Date;
+    readonly idleMs: number;
+    readonly reason: StallReason;
+}
+
+/** Why the sweep believes this run is not moving. Diagnostic, not a taxonomy
+ *  the caller should branch on for correctness. */
+export declare type StallReason = 
+/** Suspended with a `signal-awaited` outstanding — the classic wedge: the
+*  sender never came. */
+'awaiting-signal'
+/** Suspended, but not on a signal and not on a timer. */
+| 'suspended'
+/** Status `running` with no step or event movement — a step that never
+*  returns, or a runner that vanished without the reclaim path noticing. */
+| 'no-progress';
+
 export declare const step: <R, Success extends Schema.Schema.Any = typeof Schema.Void, Error extends Schema.Schema.All = typeof Schema.Never>(options: StepOptions<R, Success, Error>) => ReturnType<typeof stepModule.make<R, Success, Error>>;
 
 /**
@@ -1543,6 +1907,62 @@ export declare interface StepRetryPolicy {
     readonly note?: string;
 }
 
+/**
+ * Park the run until the budget has headroom.
+ *
+ * Returns (successfully) only when `hasHeadroom` answers true — so the caller
+ * can spend immediately afterwards without a second check of its own. Fails with
+ * `BudgetHoldExpired` once the total `timeoutMs` is used up, having spent
+ * nothing.
+ *
+ * ── Why it is a LOOP, and why the loop is not a spin ─────────────────────────
+ *
+ * Two independent things can end one park: an external release, and the
+ * recheck clock. Neither proves there is headroom (a window can roll over for a
+ * tenant that immediately spends again; an operator can lift the wrong hold), so
+ * each wake re-reads and — if still over — parks AGAIN, on a FRESH generation.
+ *
+ * It is not a spin because every iteration is a real `Workflow.suspend`: the
+ * fiber is released, the wake is a `DurableClock`, and the minimum time between
+ * two iterations is `recheckEveryMs`. The generation is what makes that true —
+ * re-parking on the SAME key would await a deferred the previous release had
+ * already completed, return instantly, and turn this loop into exactly the
+ * busy-wait it looks like.
+ *
+ * The deadline is evaluated against the WALL CLOCK at each wake, from the FIRST
+ * hold's durable `heldAt` rather than a captured `Date.now()`. A replay reading a
+ * later clock therefore gives up sooner-or-equal, never later — which is the
+ * safe direction for a control whose purpose is to stop spending.
+ */
+export declare const suspendForBudget: (options: SuspendForBudgetOptions) => Effect.Effect<void, BudgetHoldExpired>;
+
+export declare interface SuspendForBudgetOptions {
+    readonly store: DataStore;
+    readonly budget: string;
+    readonly tenantId: string | null;
+    readonly executionId: string;
+    readonly workflowName: string;
+    readonly stepName: string;
+    readonly spentMicroUsd?: number | undefined;
+    readonly limitMicroUsd?: number | undefined;
+    /** Total time the run may stay held across ALL parks. Default 7 days;
+     *  `Number.POSITIVE_INFINITY` waits forever (a legitimate choice for a
+     *  monthly cap). */
+    readonly timeoutMs?: number | undefined;
+    /** Self-recheck cadence. Default 15 minutes. */
+    readonly recheckEveryMs?: number | undefined;
+    /**
+     * Does the budget have headroom NOW?
+     *
+     * Re-read on every wake, and it is the only thing that ends the hold. A
+     * release — from an operator, or from the finops accountant's `recovered`
+     * signal — WAKES the run; it does not authorise the spend. Those are different
+     * facts, and conflating them is how a run resumes into a budget that is still
+     * exceeded and spends anyway.
+     */
+    readonly hasHeadroom: Effect.Effect<boolean>;
+}
+
 /**
  * The stable `DurableDeferred` name for a suspending signal wait. It is a pure
  * function of the workflow name + the signal name, so the awaiting body and an
@@ -1562,6 +1982,15 @@ export declare const suspendingSignalDeferredName: (workflowName: string, signal
  */
 export declare const sweepCancelOn: (deps: CancelOnSweepDeps, options: CancelOnSweepOptions) => Promise<CancelOnSweepResult>;
 
+/**
+ * One staleness tick. Never throws.
+ *
+ * Same contract as `sweepCancelOn`: one malformed row must not take the whole
+ * scheduled tick down and stop detection for every workflow until somebody
+ * notices. Failures are collected and reported.
+ */
+export declare const sweepStalledRuns: (deps: StalenessSweepDeps, options?: StalenessSweepOptions) => Promise<StalenessSweepResult>;
+
 export declare const truncateWorkflowValue: (value: unknown, bytes?: number) => unknown;
 
 /**
@@ -1581,6 +2010,14 @@ export declare interface ValidateFlowControlInput {
     readonly control: (WorkflowFlowControl<never> & WorkflowCancelOnDeclared) | undefined;
 }
 
+/**
+ * One parked run, waiting on budget headroom.
+ *
+ * Reactive so a dashboard can show "3 runs held on `ai-usd`" without polling —
+ * which is the operator's entry point to lifting one.
+ */
+export declare const _voltroBudgetHoldsTable: TableLike;
+
 /**
  * `_voltro_workflow_admissions` — append-only ledger, and the lease register.
  *
@@ -1904,6 +2341,37 @@ export declare interface WorkflowExecuteRecordingOptions extends WorkflowRunReco
         readonly runId?: string;
         readonly status: 'succeeded' | 'failed';
     }) => Promise<void>;
+    /**
+     * CRASH-LOOP BREAKER — how many CONSECUTIVE runner deaths this run may cost
+     * the fleet before it is parked instead of reclaimed again.
+     *
+     * The failure it bounds has no error to catch: a step that kills the process
+     * (OOM, a native crash, a `process.exit` in a dependency) leaves the shard
+     * lease to age out, a survivor claims it, and executes the same payload —
+     * forever, across every replica in turn. Poison handling exists at ADMISSION
+     * (`admissionTables.ts`), which is the wrong side of the boundary: the run
+     * was admitted long ago and dies on the way out.
+     *
+     * At the cap the run becomes `suspended` with a `run-crashlooped` event, the
+     * body is NOT entered, and the fleet stops rotating. An operator resume
+     * re-arms it — and any clean re-entry (a durable sleep waking, a redrive)
+     * resets the counter to 0, so this measures a loop, not a lifetime.
+     *
+     * Default {@link DEFAULT_MAX_RUN_RECLAIMS}; `VOLTRO_WORKFLOW_MAX_RECLAIMS`
+     * overrides it via {@link resolveRunGuardTuning}.
+     */
+    readonly maxRunReclaims?: number;
+    /**
+     * Step rows read to build the replay-shape snapshot for the nondeterminism
+     * tripwire. A run with more recorded steps than this SKIPS the tripwire
+     * entirely rather than comparing against a truncated history — a partial
+     * prior shape would report the steps it failed to load as `unreached-step`,
+     * which is a false positive manufactured by the bound itself.
+     *
+     * Default {@link DEFAULT_REPLAY_SHAPE_LIMIT};
+     * `VOLTRO_WORKFLOW_REPLAY_SHAPE_LIMIT` overrides it.
+     */
+    readonly replayShapeLimit?: number;
 }
 
 /**
@@ -2066,16 +2534,24 @@ export declare interface WorkflowMessagesCarrier<M extends WorkflowMessagesMetad
     readonly [WorkflowMessagesProperty]: M;
 }
 
+/**
+ * The message channels a workflow declares.
+ *
+ * TWO, not three. `queries` used to sit here as a third channel and there was
+ * never a send path for it — no `sendWorkflowQuery`, no `awaitQuery`, nothing
+ * to receive one. It was normalised into metadata, projected into the generated
+ * rpcGroup and carried on the client's `WorkflowState`, so a user got a fully
+ * typed record they could not invoke from anywhere. Signals (fire-and-forget)
+ * and updates (synchronous, with a result) are the channels that exist.
+ */
 export declare interface WorkflowMessageSchemas {
     readonly signals?: Readonly<Record<string, Schema.Schema.Any>>;
     readonly updates?: Readonly<Record<string, WorkflowMessagePairSchemas>>;
-    readonly queries?: Readonly<Record<string, WorkflowMessagePairSchemas>>;
 }
 
 export declare interface WorkflowMessagesMetadata {
     readonly signals: Readonly<Record<string, Schema.Schema.Any>>;
     readonly updates: Readonly<Record<string, WorkflowMessagePairSchemas>>;
-    readonly queries: Readonly<Record<string, WorkflowMessagePairSchemas>>;
 }
 
 export declare const WorkflowMessagesProperty = "__voltroWorkflowMessages";
@@ -2224,7 +2700,23 @@ export declare type WorkflowRunEventType = 'run-started' | 'run-suspended' | 'ru
 /** Emitted by `awaitUpdate(...)` when schema validation or the
 *  update handler fails. `payload` carries `{ updateId, updateName,
 *  errorTag, errorMessage }`; the caller's update promise rejects. */
-| 'update-failed';
+| 'update-failed'
+/** The replay tripwire fired: this run is re-executing against a body whose
+*  step shape no longer matches what the run journaled. `payload` carries
+*  `{ kind, stepName, recorded, reached, detail }` — see
+*  `nondeterminism.ts`. NEVER accompanied by a state change: the run keeps
+*  going, because a false positive that killed a run would be worse than the
+*  divergence it suspects. */
+| 'nondeterminism-suspected'
+/** The crash-loop breaker parked this run: its runner died mid-body
+*  `maxRunReclaims` times in a row and a survivor reclaimed it each time.
+*  `payload` carries `{ reclaimCount, maxRunReclaims }`. The run row is
+*  `suspended` — an operator resume re-arms it with a fresh budget. */
+| 'run-crashlooped'
+/** The staleness sweep saw no progress on a live run for longer than the
+*  configured threshold. `payload` carries `{ idleMs, stallAfterMs,
+*  lastProgressAt, reason }`. Diagnostic only — the run is untouched. */
+| 'run-stalled';
 
 /** A workflow run's TERMINAL outcome, handed to the metrics hook. Kept local to
  *  this package (structurally matching `@voltro/runtime`'s `WorkflowRunRecord`) so
@@ -2461,6 +2953,17 @@ export declare interface WorkflowVersionMetadata {
 export declare interface WorkflowVersionOptions {
     readonly version?: string | number;
     readonly compatibleWith?: ReadonlyArray<string | number>;
+    /**
+     * Named change markers this workflow's body may branch on, via
+     * {@link patch}. Declaring one here is what makes `yield* patch('id')`
+     * answer `true` for runs started from now on and `false` for runs that were
+     * already in flight — see {@link patch} for the semantics and the worked
+     * example.
+     *
+     * The declared set is stamped onto `_voltro_workflow_runs.workflowPatches`
+     * at run start and read back from THERE on every resume, so the answer is
+     * pinned to the run and cannot change under a redeploy.
+     */
     readonly patches?: ReadonlyArray<string>;
     /**
      * When `true`, a workflow whose top-level body FAILS does not become a