@voltro/workflow 0.33.0 → 0.35.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';
@@ -100,6 +101,15 @@ export declare interface AdmissionDrainDeps {
         readonly executionId: string;
         readonly startedAt: number;
     }>>;
+    /**
+     * EVERY registered workflow name — not just the controlled ones in
+     * `controls`. A `mode: 'delayed'` row is legitimate for a workflow with NO
+     * flow control, so "missing from `controls`" cannot mean "orphan" for it the
+     * way it does for a debounce row. Absent → a delayed row is assumed
+     * registered, and an unknown name surfaces as a per-row failure (attempts +
+     * lastError climb on the row) instead of a silent abandon.
+     */
+    readonly registeredWorkflows?: ReadonlySet<string>;
     readonly log?: DrainLogger;
     readonly now?: () => number;
 }
@@ -446,6 +456,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 +717,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 +778,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 +813,44 @@ 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;
+
+/**
+ * Default threshold: a wait DECLARED longer than this suggests the suspending
+ * variant. Five minutes — well above any interactive approval, well below the
+ * hours-long HITL waits the suspending variant is for; the poll's own backoff
+ * (≤ 5 s) makes the polling cost of a shorter wait negligible.
+ */
+export declare const DEFAULT_SUSPEND_HINT_MS: number;
+
+/** 24 h — see {@link WorkflowScheduleDeclaration.maxRuntime}. */
+export declare const DEFAULT_WORKFLOW_SCHEDULE_MAX_RUNTIME_MS: number;
+
 export declare type DeferMode = DeferringControl | 'paused';
 
 /**
@@ -901,6 +1025,9 @@ export declare const getCurrentWorkflowRunId: () => Effect.Effect<string | undef
  *  the path it took before this feature existed. */
 export declare const getWorkflowFlowControl: (value: unknown) => ResolvedFlowControl | undefined;
 
+/** The resolved schedule attached to a workflow definition, or undefined. */
+export declare const getWorkflowSchedule: (value: unknown) => ResolvedWorkflowSchedule | undefined;
+
 export declare const getWorkflowVersionMetadata: (value: unknown) => WorkflowVersionMetadata;
 
 /** `true` when this workflow declares at least one `cancelOn` entry — i.e. when
@@ -917,6 +1044,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,10 +1153,28 @@ 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;
 
+/**
+ * Emit the steering hint when a polling `awaitSignal` declares a wait longer
+ * than the threshold. Returns `true` when it hinted — the testable fact; the
+ * once-per-name set is module state on purpose (one process, one hint).
+ */
+export declare const maybeHintSuspendingSignal: (input: SuspendHintInput) => boolean;
+
 /** The newest event instant in a batch, or `undefined` for an empty one.
  *  The watermark advances to THIS, never to `now`: advancing to wall-clock
  *  would skip anything written with an older `occurredAt` by a transaction
@@ -1051,6 +1203,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 +1227,99 @@ 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>;
 
+/**
+ * Park a `start(name, payload, { at })` as a DURABLE pending row.
+ *
+ * A delayed start that only exists in a `setTimeout` dies with the process, so
+ * it is a row in `_voltro_workflow_pending` (`mode: 'delayed'`) that the
+ * coordinated drainer fires when `dueAt` arrives. Each call is its OWN row —
+ * two delayed starts never collapse, because unlike debounce nothing about
+ * `{ at }` says the second supersedes the first.
+ *
+ * What happens at `dueAt` is an ARRIVAL, not a bypass: the drainer hands the
+ * row to the same `admitStart` a live `ctx.workflows.start` goes through, so a
+ * workflow's declared debounce/singleton/rateLimit judge the start as of the
+ * moment it comes due. `{ at }` delays the arrival; it never outranks a control.
+ */
+export declare const parkDelayedStart: (input: ParkDelayedStartInput) => Promise<{
+    readonly intentId: string;
+    readonly dueAt: number;
+}>;
+
+export declare interface ParkDelayedStartInput {
+    readonly store: AdmissionDataStore;
+    readonly workflowName: string;
+    readonly payload: unknown;
+    readonly callerContext: unknown;
+    readonly tenantId: string | null;
+    /** Epoch ms the start becomes an ARRIVAL. Must be in the future — the facade
+     *  starts a past-`at` immediately and never calls in here. */
+    readonly at: number;
+    readonly now: number;
+}
+
+/**
+ * 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,13 +1329,27 @@ 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;
     readonly tenantId: string | null;
     readonly workflowName: string;
     readonly controlKey: string;
-    readonly mode: 'debounce' | 'batch' | 'throttle' | 'concurrency' | 'paused';
+    readonly mode: 'debounce' | 'batch' | 'throttle' | 'concurrency' | 'paused' | 'delayed';
     readonly payload: unknown;
     readonly callerContext: unknown;
     readonly priority: number;
@@ -1295,6 +1564,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 +1611,37 @@ 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>;
+
+/** Test seam: forget which (workflow, signal) pairs have been hinted. */
+export declare const resetSuspendHintsForTest: () => void;
+
 /** Resolve every declared key against one payload. Pure; throws only
  *  {@link FlowControlKeyError}. */
 export declare const resolveAdmissionKeys: (control: ResolvedFlowControl, payload: unknown) => AdmissionKeys;
@@ -1376,6 +1714,35 @@ export declare interface ResolvedFlowControl {
     readonly cancelOn?: ReadonlyArray<ResolvedCancelOn>;
 }
 
+/** The declaration with defaults filled in — what the CLI lowering reads. */
+export declare interface ResolvedWorkflowSchedule {
+    readonly cron: string;
+    readonly timezone: string;
+    readonly payload?: unknown | ((fire: {
+        readonly scheduledAt: Date;
+    }) => unknown | Promise<unknown>);
+    readonly onOverlap: WorkflowScheduleOverlap;
+    readonly backfill: 'skip' | 'latest' | 'all';
+    readonly maxRuntimeMs: number;
+}
+
+/**
+ * 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;
+};
+
+/** Env (operator, no rebuild) → config (project) → default. */
+export declare const resolveSuspendHintMs: () => number;
+
 export declare const resolveWorkflowMessageRun: (store: WorkflowMessageStore, target: WorkflowMessageTarget) => Promise<WorkflowResolvedRun>;
 
 export declare const resumeWorkflow: (store: AdmissionDataStore, workflowName: string) => Promise<boolean>;
@@ -1401,6 +1768,15 @@ export declare const sendWorkflowUpdate: (input: {
 
 export declare const serialiseWorkflowRowForWire: (row: Record<string, unknown>) => Record<string, unknown>;
 
+/**
+ * Set the threshold from `app.config.ts` (`workflows.suspendSignalHintMs`).
+ * Called by the framework boot (both paths, through `wireFlowControl`); the
+ * env override below still wins, per the standing tunables rule.
+ * Non-positive/non-finite values are ignored; `0` cannot silence the hint —
+ * pass a very large threshold to effectively disable it.
+ */
+export declare const setSuspendSignalHintMs: (ms: number | undefined) => void;
+
 /**
  * Durable sleep — wake time journaled in the cluster. Wrapper around
  * `DurableClock.sleep` that emits `timer-set` / `timer-fired` events
@@ -1441,6 +1817,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 +1995,72 @@ 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>;
+}
+
+export declare interface SuspendHintInput {
+    /** Undefined outside an engine context — the hint then keys on the signal
+     *  name alone, which still fires once rather than never. */
+    readonly workflowName: string | undefined;
+    readonly signalName: string;
+    /** The wait's DECLARED timeout, ms. */
+    readonly timeoutMs: number;
+    readonly warn?: (message: string) => void;
+}
+
 /**
  * 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 +2080,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 +2108,22 @@ export declare interface ValidateFlowControlInput {
     readonly control: (WorkflowFlowControl<never> & WorkflowCancelOnDeclared) | undefined;
 }
 
+/**
+ * Validate at DEFINITION time — module load, i.e. boot — with a message naming
+ * the workflow and the field. Same posture as `validateFlowControl` and
+ * `defineSchedule`: a cron typo that surfaces as "never fired" three days in
+ * is the failure class this repo keeps paying for.
+ */
+export declare const validateWorkflowSchedule: (workflowName: string, declaration: WorkflowScheduleDeclaration<never> | undefined) => ResolvedWorkflowSchedule | 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 +2447,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;
 }
 
 /**
@@ -2051,6 +2625,12 @@ declare type WorkflowFn = <const Name extends string, Payload extends WorkflowPa
      *  type comes from its OWN `schema` — see {@link WorkflowCancelOnList} for
      *  why that needs a tuple type parameter rather than a plain array. */
     readonly cancelOn?: WorkflowCancelOnList<Cancels, DecodedPayload<Payload>>;
+    /** Run this workflow on a cron — the workflow-side spelling of a
+     *  `defineSchedule({ workflow })` target, with Temporal's overlap
+     *  vocabulary (`skip` / `buffer` / `cancelOther`). Lowered by the CLI into
+     *  a real schedule named `workflow:<name>`; see
+     *  {@link WorkflowScheduleDeclaration}. */
+    readonly schedule?: WorkflowScheduleDeclaration<DecodedPayload<Payload>>;
 } & Omit<WorkflowBaseOptions, 'name' | 'payload' | 'idempotencyKey' | 'success' | 'error'> & WorkflowVersionOptions & {
     readonly messages?: Messages;
 } & WorkflowFlowControl<DecodedPayload<Payload>>) => workflowModule.Workflow<Name, PayloadSchemaOf<Payload>, Success, Error> & WorkflowMessagesCarrier<NormaliseWorkflowMessages<Messages>>;
@@ -2066,16 +2646,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 +2812,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
@@ -2277,6 +2881,23 @@ export declare interface WorkflowRunRecorderOptions {
      * rather than as garbage — see `inspectWorkflow`.
      */
     readonly encryptStepPayload?: (value: unknown) => unknown;
+    /**
+     * How much this recorder writes per STEP — `'full'` (default) or `'coarse'`.
+     *
+     * `'coarse'` makes `startStep` answer "not recording this step" (the
+     * contract callers already handle) and `endStep*` no-ops, removing the two
+     * fire-and-forget store writes every step otherwise costs. Run rows and
+     * `recordEvent` (signals, timers, cancels, stall reports) are DELIBERATELY
+     * unaffected: they are per-run, not per-step, and they are what the
+     * dead-letter view and the cancel/staleness sweeps read. The engine's own
+     * durable journal is not touched either way — this is the introspection
+     * copy, never replay state.
+     *
+     * App-facing spelling: `workflows.recording` in `app.config.ts`, env
+     * override `VOLTRO_WORKFLOW_RECORDING` (resolved by the CLI, threaded to
+     * BOTH boot paths through one resolver).
+     */
+    readonly recording?: 'full' | 'coarse';
 }
 
 /** Per-step lifecycle hooks. Implementations should not throw —
@@ -2349,6 +2970,68 @@ export declare interface WorkflowRunRecorderService {
     }>;
 }
 
+export declare interface WorkflowScheduleDeclaration<Payload> {
+    /** Standard cron expression — 5-field or 6-field (leading seconds). */
+    readonly cron: string;
+    /** IANA timezone the expression is interpreted in. REQUIRED, like
+     *  `defineSchedule` — server-local time in a container is a bug factory. */
+    readonly timezone: string;
+    /**
+     * The payload each firing starts the workflow with. A value, or a function
+     * of the firing (`({ scheduledAt }) => …`) for payloads that carry the slot
+     * — a backfilled firing then computes against ITS instant, not "now".
+     * Omitted ⇒ `{}`, which only typechecks for workflows whose payload has no
+     * required fields; a mismatch fails the start with `WorkflowPayloadError`
+     * naming the missing fields, same as any other start.
+     */
+    readonly payload?: Payload | ((fire: {
+        readonly scheduledAt: Date;
+    }) => Payload | Promise<Payload>);
+    /** Default `'skip'` — Temporal's default too, and the only answer that is
+     *  safe for every job shape. */
+    readonly onOverlap?: WorkflowScheduleOverlap;
+    /** Boot catch-up policy for firings missed during downtime — the scheduler's
+     *  own vocabulary, unchanged. Default `'skip'`. For a RANGE older than boot
+     *  backfill reaches, use `voltro schedule backfill`. */
+    readonly backfill?: 'skip' | 'latest' | 'all';
+    /**
+     * Watchdog on ONE firing — which, for a workflow schedule, INCLUDES the
+     * awaited run (that await is what makes `onOverlap` bind on the run's
+     * duration). Default 24 hours rather than `defineSchedule`'s 30 minutes,
+     * because a durable run legitimately outlives a handler; set it above your
+     * slowest expected run. Past it the FIRING records `failed`/timeout and
+     * releases the overlap guard — the workflow run itself is NOT cancelled
+     * (declare flow-control `timeouts.finish` to bound the run).
+     */
+    readonly maxRuntime?: FlowDuration;
+}
+
+/**
+ * What happens when a firing arrives while the RUN from the previous firing is
+ * still going — Temporal Schedules' overlap vocabulary, applied to the
+ * workflow run (not merely to the handler invocation):
+ *
+ *   `'skip'`        — the new firing stands down; recorded as `skipped`.
+ *   `'buffer'`      — the new firing waits and runs after the previous one
+ *                     finishes; firings serialize, none is lost.
+ *   `'cancelOther'` — the new firing CANCELS the still-running previous run
+ *                     and starts fresh — for "recompute the latest state"
+ *                     jobs where the old run's partial work is worthless.
+ *
+ * The first two lower into the scheduler's own `onOverlap: 'skip' | 'queue'`;
+ * what makes them bind on the RUN's duration is that the synthesised handler
+ * AWAITS the workflow run to completion, so the schedule-run row is `running`
+ * for exactly as long as the workflow is.
+ */
+export declare type WorkflowScheduleOverlap = 'skip' | 'buffer' | 'cancelOther';
+
+/** Attached via `defineProperty` like the flow-control carrier — the value's
+ *  TYPE does not know about it, and the web bundle never reads it. A STRING
+ *  property rather than a symbol for the same reason as
+ *  `WorkflowFlowControlProperty`: the CLI's discovery reads it off a module
+ *  that crossed a bundler boundary, and symbols do not survive every one. */
+export declare const WorkflowScheduleProperty = "__voltroWorkflowSchedule";
+
 /**
  * At most one run per key. The newcomer either stands down or evicts.
  *
@@ -2461,6 +3144,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