@voltro/workflow 0.29.0 → 0.30.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { Context } from 'effect';
 import { DurableClock as durableClock } from '@effect/workflow';
 import { DurableQueue as durableQueueModule } from '@effect/workflow';
 import { DurableRateLimiter as durableRateLimiterModule } from '@effect/workflow';
+import { Duration } from 'effect';
 import { Effect } from 'effect';
 import { FiberRef } from 'effect';
 import { Layer } from 'effect';
@@ -18,6 +19,309 @@ import { WorkflowEngine } from '@effect/workflow';
 import { Workflow as workflowModule } from '@effect/workflow';
 import { WorkflowParentClosePolicy } from '@voltro/protocol';
 
+/** The narrow slice of `DataStore` flow control needs. */
+export declare interface AdmissionDataStore {
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
+    insert(table: string, row: Row): Promise<Row>;
+    update(table: string, primaryKey: string, patch: Readonly<Record<string, unknown>>): Promise<Row | null>;
+    delete(table: string, primaryKey: string): Promise<boolean>;
+    upsert(table: string, row: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
+    }): Promise<Row>;
+}
+
+export declare type AdmissionDecision = {
+    readonly kind: 'admit';
+    readonly reason: AdmitReason;
+    readonly keys: AdmissionKeys;
+    /** Cancel this run as part of admitting — `singleton: { mode: 'cancel' }`.
+     *  Only ever present on an `admit`; see the module header. */
+    readonly evict?: AdmissionIncumbent;
+} | {
+    readonly kind: 'defer';
+    readonly mode: DeferMode;
+    /** Epoch ms: the earliest moment this may be admitted. */
+    readonly dueAt: number;
+    /** Epoch ms: debounce's hard cap, measured from the first start. */
+    readonly deadlineAt?: number;
+    /** `'replace'` — one pending row per key, newest payload wins (debounce).
+     *  `'append'`  — one row per item, they accumulate (batch).
+     *  `'hold'`    — the row already exists and only its `dueAt` moves
+     *                (throttle / concurrency / paused re-checks). */
+    readonly collapse: 'replace' | 'append' | 'hold';
+    readonly keys: AdmissionKeys;
+} | {
+    readonly kind: 'drop';
+    readonly reason: 'rate-limit';
+    readonly retryAfterMs: number;
+    readonly keys: AdmissionKeys;
+} | {
+    readonly kind: 'skip';
+    readonly incumbent: AdmissionIncumbent;
+    readonly keys: AdmissionKeys;
+};
+
+export declare interface AdmissionDrainDeps {
+    readonly store: AdmissionDataStore;
+    /** Resolved flow control per workflow name. A name missing from this map has
+     *  no controls, so any pending row under it is an orphan — see `drainTick`. */
+    readonly controls: ReadonlyMap<string, ResolvedFlowControl>;
+    /** Actually start the workflow. Injected, because the engine lives in the CLI
+     *  layer and this package must not reach for it. */
+    readonly startAdmitted: (workflowName: string, payload: unknown, callerContext: unknown) => Promise<AdmittedStart>;
+    /** Cancel a run — used by singleton eviction and by `timeouts.finish`. */
+    readonly cancelRun: (workflowName: string, executionId: string) => Promise<void>;
+    /**
+     * A start that will never happen: `timeouts.start` elapsed, or the workflow
+     * was deleted while its intents were queued. Wired to the same `onFailure`
+     * path an exhausted retry takes — a job that silently did not happen is the
+     * failure this whole feature exists to remove, so it must not be the one
+     * outcome with no notification.
+     */
+    readonly onAbandoned: (input: {
+        readonly workflowName: string;
+        readonly payload: unknown;
+        readonly callerContext: unknown;
+        readonly reason: string;
+    }) => Promise<void>;
+    /** Runs of a controlled workflow that are still running, for `timeouts.finish`. */
+    readonly listRunningRuns?: (workflowName: string) => Promise<ReadonlyArray<{
+        readonly executionId: string;
+        readonly startedAt: number;
+    }>>;
+    readonly log?: DrainLogger;
+    readonly now?: () => number;
+}
+
+/** The run currently holding a singleton key. */
+export declare interface AdmissionIncumbent {
+    readonly executionId: string;
+    readonly runId: string;
+    /** Epoch ms, for the "how long has it held this" the ledger reports. */
+    readonly admittedAt: number;
+}
+
+/** Every flow-control key resolved against ONE concrete payload. */
+export declare interface AdmissionKeys {
+    readonly debounceKey?: string;
+    readonly singletonKey?: string;
+    readonly concurrencyKey?: string;
+    readonly throttleKey?: string;
+    readonly rateLimitKey?: string;
+    readonly batchKey?: string;
+    readonly priority: number;
+}
+
+export declare const ADMISSIONS_TABLE = "_voltro_workflow_admissions";
+
+/** What the store observed for these keys. Every field optional: the store only
+ *  queries for controls this workflow actually declares, so an undeclared
+ *  control costs no round trip. */
+export declare interface AdmissionState {
+    /** Operator pause (`voltro workflows pause <name>`). */
+    readonly paused?: boolean;
+    /** An existing pending row under `debounceKey`. */
+    readonly debouncePending?: {
+        readonly firstSeenAt: number;
+        readonly collapsed: number;
+        /** Already-computed hard cap, carried on the row so the deadline is
+         *  measured from the FIRST start and survives a replica change. */
+        readonly deadlineAt?: number;
+    };
+    /** Items already accumulated under `batchKey`. */
+    readonly batchPending?: {
+        readonly count: number;
+        readonly firstSeenAt: number;
+    };
+    readonly singletonHolder?: AdmissionIncumbent;
+    /** Runs in flight under `concurrencyKey` (leases held, not yet released). */
+    readonly inFlight?: number;
+    /** Admission timestamps inside the throttle / rate-limit window,
+     *  NEWEST FIRST. Derived from the admissions ledger — see the note on
+     *  {@link nextSlotAt} for why a ledger read beats a counter column. */
+    readonly recentAdmissions?: ReadonlyArray<number>;
+}
+
+/** What the caller learns about a start that went through flow control. */
+export declare type AdmissionVerdict = {
+    /** Start it now. The ledger row is already written; call `linkExecution`
+     *  once the engine hands back an execution id. */
+    readonly kind: 'start';
+    readonly ledgerId: string | undefined;
+    readonly keys: AdmissionKeys;
+    /**
+     * What to start the workflow WITH.
+     *
+     * Almost always the caller's own payload — except for a batch that filled
+     * up on THIS arrival, where it is `{ items: [...] }` carrying every item
+     * already accumulated plus the arriving one. Returning it explicitly rather
+     * than letting the caller assume its own payload is the fix for a real
+     * defect: the arriving item alone would start the run, and the three items
+     * already queued would sit in the table until their timeout fired a SECOND
+     * run. One batch in, two runs out, and the first one short.
+     */
+    readonly payload: unknown;
+    /** Pending rows this start consumes — delete them once it succeeds. Empty
+     *  for an ordinary start. */
+    readonly consume: ReadonlyArray<string>;
+    /** Starts folded into this run, for the ledger. */
+    readonly collapsed: number;
+    /** Cancel this run first — `singleton: { mode: 'cancel' }`. */
+    readonly evict?: {
+        readonly executionId: string;
+        readonly runId: string;
+    };
+} | {
+    /** Queued. The run will happen later; `start()` returns a handle whose
+     *  status says so rather than a fake execution id. */
+    readonly kind: 'queued';
+    readonly intentId: string;
+    readonly mode: string;
+    readonly dueAt: number;
+} | {
+    /** Over a `rateLimit` cap. The work will NOT happen. */
+    readonly kind: 'dropped';
+    readonly retryAfterMs: number;
+} | {
+    /** `singleton: { mode: 'skip' }` — the incumbent's handle is the answer. */
+    readonly kind: 'skipped';
+    readonly executionId: string;
+    readonly runId: string;
+};
+
+export declare type AdmitReason = 'no-controls' | 'under-limits' | 'debounce-elapsed' | 'debounce-deadline' | 'batch-full' | 'batch-timeout';
+
+/**
+ * Decide, persist, and report — the whole arrival path in one call.
+ *
+ * Note what it does NOT do: start the workflow. The engine call stays with the
+ * facade, because the facade is the only thing that knows how to talk to it,
+ * and because a `kind: 'start'` verdict with an eviction attached has to
+ * cancel the incumbent in the right order relative to the new start.
+ */
+export declare const admitStart: (input: AdmitStartInput) => Promise<AdmissionVerdict>;
+
+export declare interface AdmitStartInput {
+    readonly store: AdmissionDataStore;
+    readonly control: ResolvedFlowControl;
+    readonly payload: unknown;
+    readonly callerContext: unknown;
+    readonly tenantId: string | null;
+    readonly paused: boolean;
+    readonly now: number;
+    /**
+     * `true` when the caller is BLOCKING for the result (`ctx.workflows.run`, or
+     * `start({ wait: true })`).
+     *
+     * A deferring control has no coherent answer for such a caller — there is no
+     * result to return for a start that was collapsed into a future run — so the
+     * facade rejects that combination before calling in here. This flag is
+     * carried so the ledger records WHY a run bypassed the queue, not to change
+     * the decision.
+     */
+    readonly waiting: boolean;
+}
+
+export declare interface AdmittedStart {
+    readonly executionId: string;
+    readonly runId?: string;
+}
+
+/** Every pending row, for the inspect surface — including not-yet-due ones,
+ *  because "what is waiting and for how long" is the question being asked. */
+export declare const allIntents: (store: AdmissionDataStore, limit: number) => Promise<ReadonlyArray<PendingIntent>>;
+
+/**
+ * Assert every workflow sharing a `concurrency.pool` declares the SAME limit.
+ *
+ * Called at BOOT, with every registered workflow's resolved control — the one
+ * moment all declarations are visible in one place. `validateFlowControl` runs
+ * per declaration and structurally cannot see a sibling file, so without this
+ * check two limits for one budget would not fail anywhere: admission would
+ * enforce whichever workflow's limit the arriving start happened to carry, and
+ * the pool would bound to 5 or 10 depending on WHO asked. A limit that varies
+ * by asker is not a limit.
+ *
+ * A boot error rather than a warning, for the same reason `singleton.mode` has
+ * no default: both declared numbers are somebody's intent, and picking either
+ * one silently enforces a budget the other author never wrote.
+ */
+export declare const assertConsistentPools: (controls: ReadonlyArray<ResolvedFlowControl | undefined>) => void;
+
+/**
+ * Wait for a domain event correlated with this run.
+ *
+ * ```ts
+ * const change = yield* awaitEvent(ctx, {
+ *   event: 'jira.issue.changed',
+ *   schema: JiraIssueChanged,
+ *   match: (e) => e.issueKey === input.issueKey,
+ *   since: 'run-start',
+ *   timeoutMs: 30 * 60_000,
+ * })
+ * ```
+ *
+ * Journaled like every other activity: once it has matched, a replay returns the
+ * matched event from the journal without re-reading anything.
+ */
+export declare const awaitEvent: <A>(ctx: AwaitEventCtx, options: AwaitEventOptions<A>) => Effect.Effect<A, Cause.UnknownException | ParseResult.ParseError>;
+
+/** The slice of `ctx.store` this needs — the same shape `awaitSignal` takes, so
+ *  a full `AppContext` store is assignable without a cast. */
+export declare interface AwaitEventCtx {
+    readonly store: {
+        readonly query: (descriptor: QueryDescriptor) => Promise<ReadonlyArray<unknown>>;
+    };
+}
+
+export declare interface AwaitEventOptions<A> {
+    /**
+     * The event NAME, exactly as `ctx.events.publish` / `emit` writes it.
+     *
+     * Also used to name the journal entry, so two `awaitEvent` calls for
+     * different events in one body are distinct activities and replay
+     * independently.
+     */
+    readonly event: string;
+    /** Parsed against the event's payload. A parse failure fails the activity
+     *  rather than matching — a correlated event whose SHAPE is wrong is a bug in
+     *  the publisher, and silently skipping it would hide that. */
+    readonly schema: Schema.Schema<A, any>;
+    /**
+     * Does this event belong to this run?
+     *
+     * Ordinary JavaScript over the decoded event payload. Return `true` for the
+     * one you are waiting for. Called for every candidate event in the window, so
+     * keep it cheap and pure — it may run many times across polls, and a
+     * predicate with side effects would perform them repeatedly.
+     */
+    readonly match: (event: A) => boolean;
+    /**
+     * Which events are eligible.
+     *
+     * `'wait-start'` (default) — only events that arrived after this call. Matches
+     * what every durable-execution engine does, and carries the same RACE: an
+     * event published between the previous step finishing and this call beginning
+     * is missed, and the wait then runs to its timeout. That window is small but
+     * real, and it is the single most likely reason an `awaitEvent` "never fires".
+     *
+     * `'run-start'` — every event since the run began. Closes the race at the cost
+     * of possibly matching something that arrived while an earlier step was still
+     * running. Prefer it whenever the event is a REPLY to something an earlier
+     * step in this same workflow sent, which is most of the time.
+     */
+    readonly since?: 'wait-start' | 'run-start';
+    readonly pollIntervalMs?: number;
+    readonly maxPollIntervalMs?: number;
+    /** Default 24 h. `Number.POSITIVE_INFINITY` for unbounded. */
+    readonly timeoutMs?: number;
+    /** How many candidate events one poll reads. Default 500. A correlation that
+     *  needs more than this in one window is one whose `event` name is too broad
+     *  — narrow the name rather than raising this. */
+    readonly take?: number;
+}
+
 /**
  * Wait inside a workflow body for an externally-injected signal.
  *
@@ -132,6 +436,144 @@ export declare interface AwaitUpdateOptions<A, B = A> {
     readonly timeoutMs?: number;
 }
 
+export declare const CANCEL_ON_WATERMARK = "cancelOn";
+
+export declare interface CancelDecision {
+    readonly runId: string;
+    readonly executionId: string;
+    readonly reason: string;
+    readonly event: string;
+    readonly eventId: string;
+}
+
+/** A start still sitting in the admission queue. */
+export declare interface CancellableIntent {
+    readonly intentId: string;
+    readonly payload: unknown;
+    readonly firstSeenAt: Date;
+}
+
+/** A live run that a matching event could cancel. */
+export declare interface CancellableRun {
+    readonly runId: string;
+    readonly executionId: string;
+    /** As stored in `_voltro_workflow_runs.payload` — ENCODED. Decoded with the
+     *  workflow's own payload schema before `match` sees it. */
+    readonly payload: unknown;
+    readonly startedAt: Date;
+}
+
+/** The narrow store slice this needs. Structural, like `AdmissionDataStore`. */
+export declare interface CancelOnDataStore {
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
+    upsert(table: string, row: Row, options: {
+        conflictColumns: ReadonlyArray<string>;
+        update?: ReadonlyArray<string> | ((existing: Row) => Readonly<Record<string, unknown>>);
+    }): Promise<Row>;
+}
+
+export declare interface CancelOnPlan {
+    readonly cancels: ReadonlyArray<CancelDecision>;
+    readonly discards: ReadonlyArray<DiscardDecision>;
+    readonly problems: ReadonlyArray<CancelProblem>;
+}
+
+export declare interface CancelOnPlanInput {
+    readonly workflowName: string;
+    readonly entries: ReadonlyArray<ResolvedCancelOn>;
+    /** The workflow's own payload schema. When absent the stored payload is
+     *  handed to `match` as-is — correct for JSON-shaped payloads and the honest
+     *  fallback when a definition cannot be resolved. */
+    readonly payloadSchema?: Schema.Schema.Any | undefined;
+    readonly events: ReadonlyArray<DomainEventRow>;
+    readonly runs: ReadonlyArray<CancellableRun>;
+    readonly intents: ReadonlyArray<CancellableIntent>;
+}
+
+export declare interface CancelOnSweepDeps {
+    readonly store: CancelOnDataStore;
+    /** Cancel a live run. MUST be idempotent — the boundary instant is re-read
+     *  every tick, so a cancel can legitimately be issued twice. */
+    readonly cancelRun: (input: {
+        readonly workflowName: string;
+        readonly runId: string;
+        readonly executionId: string;
+        readonly reason: string;
+        readonly event: string;
+    }) => Promise<void>;
+    /** Discard a queued admission intent. Also idempotent. */
+    readonly discardIntent: (input: {
+        readonly workflowName: string;
+        readonly intentId: string;
+        readonly reason: string;
+        readonly event: string;
+    }) => 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 CancelOnSweepOptions {
+    readonly workflows: ReadonlyArray<CancelOnWorkflow>;
+    readonly coldLookbackMs?: number;
+    readonly batch?: number;
+    readonly runPage?: number;
+}
+
+export declare interface CancelOnSweepResult {
+    /**
+     * `false` when nothing declares `cancelOn` — the sweep did not look.
+     *
+     * Distinct from an all-zero sweep that examined a hundred events and matched
+     * nothing. Rendering the two identically is the recurring way a dashboard
+     * turns "this feature is not wired" into "this feature found nothing".
+     */
+    readonly examined: boolean;
+    readonly events: number;
+    readonly cancelled: number;
+    readonly discarded: number;
+    /** The batch filled up: more events are waiting and the next tick will read
+     *  them. Reported because a permanently-catching-up sweep means cancellation
+     *  is running late, which is invisible from the counts alone. */
+    readonly catchingUp: boolean;
+    /** A workflow's live-run page filled up, so this tick examined only its
+     *  oldest `runPage` runs. Reported rather than inferred from the counts,
+     *  which cannot distinguish it from "nothing else matched". */
+    readonly sawFullRunPage: boolean;
+    readonly problems: ReadonlyArray<CancelProblem>;
+    readonly failures: ReadonlyArray<{
+        readonly subject: string;
+        readonly detail: string;
+    }>;
+    readonly watermark: Date | undefined;
+}
+
+/** One workflow's cancellation declaration, as the sweep needs it. */
+export declare interface CancelOnWorkflow {
+    readonly workflowName: string;
+    readonly entries: ReadonlyArray<ResolvedCancelOn>;
+    readonly payloadSchema?: Schema.Schema.Any | undefined;
+}
+
+/**
+ * Something the sweep could not evaluate.
+ *
+ * Reported rather than swallowed, and NEVER treated as a match. A `cancelOn`
+ * that silently stops firing because a publisher changed the event's shape is
+ * the failure this type exists to make visible — the run keeps going, which is
+ * the safe direction, but nothing about the run says the cancellation was
+ * attempted and failed.
+ */
+export declare interface CancelProblem {
+    readonly kind: 'event-decode' | 'payload-decode' | 'match-threw';
+    readonly workflowName: string;
+    readonly event: string;
+    readonly subject: string;
+    readonly detail: string;
+}
+
 export declare const closeWorkflowChildrenForParent: (options: CloseWorkflowChildrenForParentOptions) => Promise<ReadonlyArray<WorkflowParentCloseDecision>>;
 
 export declare interface CloseWorkflowChildrenForParentOptions {
@@ -145,6 +587,26 @@ export declare interface CloseWorkflowChildrenForParentOptions {
     readonly interruptChild: (workflowName: string, executionId: string, policy: Exclude<WorkflowParentClosePolicy, 'abandon'>) => Promise<void>;
 }
 
+/**
+ * Order pending rows for admission.
+ *
+ * `priority` DESC, then arrival ASC. The arrival tiebreak is not cosmetic: with
+ * every workflow on the default priority of 0 the whole queue is one tie, and
+ * without a second key the order would be whatever the dialect's planner felt
+ * like — reproducible on postgres, different on MariaDB, and the kind of
+ * difference that only shows up as "our staging box drains fairly and
+ * production does not".
+ */
+export declare const comparePendingOrder: (a: {
+    readonly priority: number;
+    readonly firstSeenAt: number;
+    readonly id: string;
+}, b: {
+    readonly priority: number;
+    readonly firstSeenAt: number;
+    readonly id: string;
+}) => number;
+
 /**
  * Externally complete a suspending signal wait, resuming the parked run with
  * `payload`. The counterpart to {@link awaitSignalSuspending} and the
@@ -192,6 +654,173 @@ export declare const CurrentWorkflowExecutionId: FiberRef.FiberRef<string | unde
  *  `Effect.locally(CurrentWorkflowRunId, runId)`. */
 export declare const CurrentWorkflowRunId: FiberRef.FiberRef<string | undefined>;
 
+/**
+ * Decide what happens to one start. Pure.
+ *
+ * Called on arrival with `reconsidering: false`, and by the drainer with
+ * `reconsidering: true` and freshly-read state. Both get the same answer for
+ * the same inputs, by construction.
+ */
+export declare const decideAdmission: (input: DecideAdmissionInput) => AdmissionDecision;
+
+declare interface DecideAdmissionInput {
+    readonly control: ResolvedFlowControl;
+    readonly keys: AdmissionKeys;
+    readonly state: AdmissionState;
+    readonly now: number;
+    /**
+     * `true` when this call is the drainer reconsidering an already-pending row,
+     * `false` on first arrival.
+     *
+     * It changes exactly one thing, and only for debounce: on ARRIVAL the quiet
+     * period restarts (that is what debounce is); on a DRAIN pass it must not,
+     * or a row would push its own deadline out every time the drainer looked at
+     * it and never run. This flag existing is the reason the two paths can share
+     * one function at all.
+     */
+    readonly reconsidering: boolean;
+}
+
+/** The DECODED payload type. Mirrors `Workflow.make`'s own `idempotencyKey`
+ *  parameter, so the two never disagree about what a payload is. */
+declare type DecodedPayload<P> = P extends Schema.Struct.Fields ? Schema.Struct.Type<P> : P extends {
+    readonly Type: infer T;
+} ? T : never;
+
+/** 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
+ *  finished long ago. */
+export declare const DEFAULT_COLD_LOOKBACK_MS: number;
+
+/** How many pending rows one tick will process. Bounded because the tick is
+ *  serial by necessity (see the header); the order guarantees the overflow is
+ *  the tail, not a random sample. */
+export declare const DEFAULT_DRAIN_BATCH = 200;
+
+/** Events read per tick. A deployment publishing more than this per tick falls
+ *  behind by design rather than by surprise: the watermark advances to the
+ *  newest event in the batch, so the next tick continues where this one
+ *  stopped. `catchingUp` in the result says when that is happening. */
+export declare const DEFAULT_EVENT_BATCH = 500;
+
+/**
+ * How long an admission lease survives with nothing releasing it — 24 hours.
+ *
+ * This is a CRASH BACKSTOP, not a run deadline: a slot is normally freed the
+ * moment the run reaches a terminal state. It is deliberately generous, because
+ * the two failure modes are not symmetric. Expiring early hands a live run's
+ * concurrency slot to a second run — the exact thing the limit was declared to
+ * prevent, and silent. Expiring late leaves a dead replica's slot occupied for
+ * a while, which is visible in the dashboard and self-heals. Declare
+ * `timeouts.finish` to make the backstop tight; that is what it is for.
+ */
+export declare const DEFAULT_LEASE_MS: number;
+
+export declare type DeferMode = DeferringControl | 'paused';
+
+/**
+ * Controls that can DEFER a start rather than answer it immediately.
+ *
+ * The distinction matters at exactly one place: `ctx.workflows.run(...)` and
+ * `start(..., { wait: true })` block for the run's RESULT. There is no coherent
+ * result to return for a start that was collapsed into a future run, so those
+ * two callers reject a deferring control loudly instead of doing something
+ * surprising. Admission controls that have a synchronous answer — singleton,
+ * rate limit — still apply on every path.
+ */
+export declare const DEFERRING_CONTROLS: readonly ["debounce", "batch", "throttle", "concurrency"];
+
+export declare type DeferringControl = (typeof DEFERRING_CONTROLS)[number];
+
+/** Which deferring controls this workflow declares, in a stable order. */
+export declare const deferringControlsOf: (control: ResolvedFlowControl | undefined) => ReadonlyArray<DeferringControl>;
+
+/** Remove a pending row that has been ADMITTED. The admission is already in the
+ *  ledger, so this deletion is a bookkeeping step and needs no record of its
+ *  own. Use {@link discardIntent} for a start that is being dropped. */
+export declare const deleteIntent: (store: AdmissionDataStore, id: string) => Promise<boolean>;
+
+export declare interface DiscardDecision {
+    readonly intentId: string;
+    readonly reason: string;
+    readonly event: string;
+    readonly eventId: string;
+}
+
+/**
+ * Drop a queued start WITHOUT running it, and write down that it happened.
+ *
+ * The ledger row is the whole point. A pending row deleted on purpose and a
+ * pending row that silently vanished are the same observation from the outside
+ * — a row that is no longer there — and "every admission decision is recorded"
+ * is the claim the whole panel rests on. Both discard paths (an operator's
+ * button, a `cancelOn` event) go through here so neither can be the one that
+ * leaves no trace.
+ *
+ * The row is written BEFORE the delete: the other order leaves a window where
+ * the start is gone and nothing says why, which is precisely the state being
+ * ruled out. A duplicate ledger row from a retry is a far cheaper failure.
+ */
+export declare const discardIntent: (store: AdmissionDataStore, intentId: string, reason: string, now: number) => Promise<boolean>;
+
+/** A row of `_voltro_workflow_events` — a published DOMAIN event. */
+export declare interface DomainEventRow {
+    readonly id: string;
+    readonly name: string;
+    readonly payload: unknown;
+    readonly occurredAt: Date;
+}
+
+declare interface DrainLogger {
+    readonly info?: (message: string, meta?: Record<string, unknown>) => void;
+    readonly warn?: (message: string, meta?: Record<string, unknown>) => void;
+}
+
+export declare interface DrainOutcome {
+    readonly scanned: number;
+    readonly admitted: number;
+    readonly deferred: number;
+    readonly dropped: number;
+    readonly skipped: number;
+    readonly expired: number;
+    readonly evicted: number;
+    readonly failed: number;
+    /** Runs cancelled by `timeouts.finish` on this tick. */
+    readonly timedOut: number;
+    /**
+     * `true` when the tick genuinely examined the queue.
+     *
+     * A drain that read nothing and a drain that found nothing due produce the
+     * same counters, and the framework has been bitten enough times by a check
+     * that reports success about a non-event. The inspect surface renders these
+     * differently because of this flag.
+     */
+    readonly examined: boolean;
+}
+
+/**
+ * One drain pass. Safe to call on a timer; never throws.
+ */
+export declare const drainTick: (deps: AdmissionDrainDeps, options?: DrainTickOptions) => Promise<DrainOutcome>;
+
+declare interface DrainTickOptions {
+    readonly batchSize?: number;
+}
+
+/**
+ * The drainer's read: pending rows whose `dueAt` has arrived, in admission
+ * order.
+ *
+ * Ordered in SQL by `(priority DESC, firstSeenAt ASC)` AND re-sorted in JS by
+ * `comparePendingOrder`. The second pass is not redundant — it adds the id
+ * tiebreak, which SQL cannot express portably without making `id` part of every
+ * index, and without which two rows created in the same millisecond have an
+ * order the dialect picks. Fair on postgres, arbitrary on MariaDB, and visible
+ * only as "staging drains fairly and production does not".
+ */
+export declare const dueIntents: (store: AdmissionDataStore, now: number, limit: number) => Promise<ReadonlyArray<PendingIntent>>;
+
 export { durableClock }
 
 /** Define a durable queue for concurrency-controlled side work. */
@@ -201,6 +830,42 @@ export { durableQueueModule }
 
 export { durableRateLimiterModule }
 
+/**
+ * Read the state and decide — the ONE composition both callers use.
+ *
+ * Exported as a pair rather than left to each caller because the failure it
+ * prevents has no symptom: an arrival path that read one column set and a drain
+ * path that read another would produce different answers for the same row, and
+ * the disagreement surfaces as a workflow that ran twice under a limit of one,
+ * on a replica nobody was watching, under load.
+ */
+export declare const evaluateAdmission: (input: EvaluateInput) => Promise<AdmissionDecision>;
+
+declare interface EvaluateInput {
+    readonly store: AdmissionDataStore;
+    readonly control: ResolvedFlowControl;
+    readonly keys: AdmissionKeys;
+    readonly paused: boolean;
+    readonly now: number;
+    readonly reconsidering: boolean;
+}
+
+export declare const EVENTS_TABLE = "_voltro_workflow_events";
+
+/** Raised when a user-supplied key function throws. Named separately because
+ *  the alternative — letting it escape — surfaces as an opaque failure inside
+ *  `start()` with no hint that the app's own lambda produced it. */
+export declare class FlowControlKeyError extends Error {
+    readonly workflowName: string;
+    readonly field: string;
+    constructor(workflowName: string, field: string, cause: unknown);
+}
+
+/** A duration in any shape Effect accepts: `'15 minutes'`, `900_000`,
+ *  `Duration.minutes(15)`. Same input type `sleep({ duration })` takes, so
+ *  there is one duration vocabulary in the whole workflow surface. */
+export declare type FlowDuration = Duration.DurationInput;
+
 /** Try to read the current workflow execution id. Returns undefined
  *  when called outside a recorded workflow body. */
 export declare const getCurrentWorkflowExecutionId: () => Effect.Effect<string | undefined>;
@@ -210,8 +875,27 @@ export declare const getCurrentWorkflowExecutionId: () => Effect.Effect<string |
  *  framework's wrapper, e.g. in a unit test). */
 export declare const getCurrentWorkflowRunId: () => Effect.Effect<string | undefined>;
 
+/** The resolved flow-control declaration attached to a workflow definition, or
+ *  `undefined` when it declares none — in which case every start takes exactly
+ *  the path it took before this feature existed. */
+export declare const getWorkflowFlowControl: (value: unknown) => ResolvedFlowControl | undefined;
+
 export declare const getWorkflowVersionMetadata: (value: unknown) => WorkflowVersionMetadata;
 
+/** `true` when this workflow declares at least one `cancelOn` entry — i.e. when
+ *  the cancellation sweep has anything to do for it. */
+export declare const hasCancelOn: (control: ResolvedFlowControl | undefined) => boolean;
+
+/** `true` when at least one control is declared — i.e. when this workflow needs
+ *  the admission boundary at all. A workflow with none must take the exact same
+ *  code path it took before this feature existed.
+ *
+ *  `cancelOn` is deliberately NOT in this list: it is evaluated by a sweep
+ *  against live runs, never at the start boundary. Including it would route
+ *  every start of a cancel-only workflow through the admission ledger, paying
+ *  two writes per start for a decision that is always "admit". */
+export declare const hasFlowControl: (control: ResolvedFlowControl | undefined) => boolean;
+
 export declare interface InMemoryRecorder {
     readonly layer: Layer.Layer<WorkflowRunRecorder>;
     readonly readSteps: () => ReadonlyArray<RecordedStep>;
@@ -273,14 +957,79 @@ export declare interface InspectStore {
  */
 export declare const inspectWorkflow: (idOrExecutionId: string, store: InspectStore) => Promise<InspectedWorkflow | null>;
 
+/**
+ * Has an admitted run outlived `timeouts.finish`?
+ *
+ * Deliberately NOT symmetrical with the pending-row check: a run's clock starts
+ * when it was admitted, and a run that has already reached a terminal state is
+ * never overdue no matter how long it took. The caller passes `startedAt` from
+ * the run row, so a run adopted by a different replica is measured on the same
+ * basis as one that stayed put.
+ */
+export declare const isFinishExpired: (control: ResolvedFlowControl, run: {
+    readonly startedAt: number;
+    readonly terminal: boolean;
+}, now: number) => boolean;
+
+/**
+ * Has a pending row outlived `timeouts.start`?
+ *
+ * Measured from `firstSeenAt` — the moment the FIRST start in the group
+ * arrived, not the last. A debounce that keeps collapsing new starts is exactly
+ * the case this bound exists for; measuring from the most recent arrival would
+ * make an unbounded burst immortal, which is the thing being bounded.
+ */
+export declare const isStartExpired: (control: ResolvedFlowControl, pending: {
+    readonly firstSeenAt: number;
+}, now: number) => boolean;
+
 export declare const isWorkflowWorkerLayer: (value: unknown) => value is WorkflowWorkerLayerBrand;
 
+/**
+ * Attach the engine's execution id to the ledger row written by
+ * {@link admitStart}.
+ *
+ * Best-effort by design: the run has already started, and failing the caller
+ * because an audit column could not be filled in would be the wrong trade. But
+ * an unlinked row is a real (small) cost — its lease expires on the backstop
+ * rather than on the run's terminal state — so the caller logs it.
+ */
+export declare const linkExecution: (store: AdmissionDataStore, ledgerId: string, executionId: string, runId: string | null) => Promise<void>;
+
 export declare const makeInMemoryRecorder: () => InMemoryRecorder;
 
 export declare const makeWorkflowRunRecorder: (options: WorkflowRunRecorderOptions) => WorkflowRunRecorderService;
 
 export declare const makeWorkflowUpdateId: () => string;
 
+/** 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
+ *  that committed late. */
+export declare const newestEventAt: (events: ReadonlyArray<DomainEventRow>) => Date | undefined;
+
+/**
+ * When does a window with `limit` slots over `periodMs` free up next, given the
+ * admissions inside it (newest first)?
+ *
+ * A SLIDING window, computed from the admissions ledger rather than from a
+ * counter column, and that choice is deliberate:
+ *
+ *   • A counter drifts. It is incremented next to the admission, not by it, so
+ *     a crash between the two leaves the two facts disagreeing forever — and the
+ *     disagreement is invisible, because the counter is the only thing anyone
+ *     reads.
+ *   • The ledger is the audit trail anyway. Deriving the limit from the same
+ *     rows the dashboard shows means "why was this dropped" is answerable by
+ *     looking, not by trusting.
+ *   • It is exact. A fixed window lets 2×limit through across a boundary; this
+ *     does not.
+ *
+ * The cost is a `COUNT`-shaped read bounded by `limit` rows, which is why
+ * `limit` is documented as a throughput knob and not a place to put 10^6.
+ */
+export declare const nextSlotAt: (recentAdmissions: ReadonlyArray<number>, limit: number, periodMs: number, now: number) => number | undefined;
+
 declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefined> = {
     readonly signals: M extends {
         readonly signals: infer Signals;
@@ -293,9 +1042,111 @@ declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefi
     } ? NonNullable<Queries> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
 };
 
+export declare const noteIntentAttempt: (store: AdmissionDataStore, intent: PendingIntent, error: string, now: number) => Promise<void>;
+
+export declare const PAUSES_TABLE = "_voltro_workflow_pauses";
+
+export declare const pauseWorkflow: (store: AdmissionDataStore, workflowName: string, by: string | null, reason: string | null) => Promise<void>;
+
+/** The SCHEMA a payload input denotes — `Fields` lifted into a `Struct`. */
+declare type PayloadSchemaOf<P> = P extends Schema.Struct.Fields ? Schema.Struct<P> : P;
+
+export declare const PENDING_TABLE = "_voltro_workflow_pending";
+
+/** 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 payload: unknown;
+    readonly callerContext: unknown;
+    readonly priority: number;
+    readonly dueAt: number;
+    readonly deadlineAt: number | undefined;
+    readonly collapsed: number;
+    readonly firstSeenAt: number;
+    readonly attempts: number;
+    /** Last drain error. A row whose attempts climb with a repeated message is a
+     *  poison intent, and a poison intent that only ever manifested as "nothing
+     *  ran" is the failure this column removes. */
+    readonly lastError: string | null;
+}
+
+/**
+ * The deterministic pending-row id for a COLLAPSING control.
+ *
+ * A hash, and the reason is length rather than secrecy: `id()` is VARCHAR(64) on
+ * MySQL/MariaDB, and a key built by concatenating a workflow name with an
+ * app-supplied control key would silently exceed it — an insert that fails on
+ * one dialect and not another, discovered in production. A hash is fixed-width
+ * whatever the app puts in a key.
+ *
+ * sha256 rather than a cheap non-crypto hash because a collision here MERGES
+ * TWO UNRELATED DEBOUNCE GROUPS: one row, one run, and the other group's work
+ * silently never happens. That is not a class of bug worth trading for a few
+ * microseconds.
+ */
+export declare const pendingSlotId: (workflowName: string, mode: string, controlKey: string) => string;
+
+/**
+ * Write (or collapse into) the pending row a `defer` decision calls for.
+ * Returns the row id, so the caller can report it and the drainer can find it.
+ */
+export declare const persistDefer: (input: PersistDeferInput) => Promise<string>;
+
+declare interface PersistDeferInput {
+    readonly store: AdmissionDataStore;
+    readonly control: ResolvedFlowControl;
+    readonly decision: Extract<AdmissionDecision, {
+        kind: 'defer';
+    }>;
+    readonly payload: unknown;
+    readonly callerContext: unknown;
+    readonly tenantId: string | null;
+    readonly now: number;
+    /** Set when the drainer is re-deferring a row it already holds. */
+    readonly existingId?: string;
+}
+
+/**
+ * Which runs and intents a batch of events cancels.
+ *
+ * Deterministic and total: every event is compared against every entry naming
+ * it, and a run is cancelled at most once even when several entries match it —
+ * the first match wins, so the recorded reason is stable rather than dependent
+ * on iteration order across dialects.
+ */
+export declare const planCancellations: (input: CancelOnPlanInput) => CancelOnPlan;
+
+/**
+ * The stored spelling of a concurrency key, pool-aware.
+ *
+ * `\u0000` separators, because the prefix must be unforgeable BY ACCIDENT: an
+ * app's key function returning a string that collides with a pooled spelling
+ * would silently count that run into another pool's budget. No app key
+ * legitimately contains NUL, and a key function constructing this exact shape
+ * on purpose is sabotage, not a typo. Kept human-readable (not hashed) so a
+ * ledger row's key still SAYS which pool it held — "why was this dropped" must
+ * stay answerable by looking.
+ */
+export declare const pooledConcurrencyKey: (pool: string | undefined, rawKey: string) => string;
+
 /** Enqueue work and await the durable queue worker's result. */
 export declare const processQueue: typeof durableQueueModule.process;
 
+/**
+ * Prune ledger rows past a retention window.
+ *
+ * Only rows whose lease is RELEASED — an unreleased `admitted` row is a live
+ * concurrency slot and a live singleton holder, and deleting it silently raises
+ * both limits. That is the one deletion in this feature that could corrupt
+ * behaviour rather than merely lose history, which is why it is a predicate and
+ * not a date range alone.
+ */
+export declare const pruneAdmissions: (store: AdmissionDataStore, olderThan: Date, limit?: number) => Promise<number>;
+
 /** Start a durable queue worker layer with bounded concurrency.
  *
  *  `DurableQueue.worker` is itself generic (`<Payload, Success, Error, R>`), so
@@ -308,6 +1159,68 @@ export declare const queueWorker: typeof durableQueueModule.worker;
 /** Durable rate limiter activity. Delays through the workflow clock. */
 export declare const rateLimit: typeof durableRateLimiterModule.rateLimit;
 
+/**
+ * Read exactly the state the declared controls need — no more.
+ *
+ * An undeclared control costs ZERO round trips. That is not an optimisation
+ * detail: a workflow that declares only `debounce` must not pay for a
+ * concurrency-lease scan, or adopting one cheap control would quietly buy the
+ * cost of all six.
+ */
+export declare const readAdmissionState: (input: ReadStateInput) => Promise<AdmissionState>;
+
+/**
+ * Every workflow name currently paused.
+ *
+ * Read as a SET, on the drainer's tick, rather than per start. A pause is an
+ * operator action measured in minutes; paying a database round trip on every
+ * single start to notice one a second sooner is the wrong trade, and it would
+ * put a query on the hot path of workflows that declare no controls at all —
+ * which must keep costing exactly what they cost before this feature existed.
+ *
+ * The consequence is stated rather than hidden: a pause takes effect on the
+ * pausing replica immediately and on the others within one drainer tick
+ * (`VOLTRO_WORKFLOW_DRAIN_MS`, default 1000).
+ */
+export declare const readPausedWorkflows: (store: AdmissionDataStore) => Promise<ReadonlySet<string>>;
+
+declare interface ReadStateInput {
+    readonly store: AdmissionDataStore;
+    readonly control: ResolvedFlowControl;
+    readonly keys: AdmissionKeys;
+    readonly now: number;
+    readonly paused: boolean;
+}
+
+/** Read the stored position for a sweep consumer. */
+export declare const readWatermark: (store: CancelOnDataStore, name: string) => Promise<Date | undefined>;
+
+/**
+ * Append one ledger row. Also the lease, when the outcome is `admitted`.
+ *
+ * Never throws into the caller: a start must not fail because its audit row
+ * could not be written. But it must not be SILENT either — the caller passes an
+ * `onError` so the failure lands in the log rather than in nothing. A ledger
+ * that quietly stops recording is a rate limiter that quietly stops limiting,
+ * because the limit is derived from these rows.
+ */
+export declare const recordAdmission: (input: RecordAdmissionInput) => Promise<string | undefined>;
+
+declare interface RecordAdmissionInput {
+    readonly store: AdmissionDataStore;
+    readonly control: ResolvedFlowControl;
+    readonly keys: AdmissionKeys;
+    readonly outcome: 'admitted' | 'dropped' | 'skipped' | 'evicted' | 'expired' | 'discarded';
+    readonly mode: string | null;
+    readonly reason: string | null;
+    readonly collapsed: number;
+    readonly waitedMs: number | null;
+    readonly executionId: string | null;
+    readonly runId: string | null;
+    readonly tenantId: string | null;
+    readonly now: number;
+}
+
 /** One recorded run-event — mirrors a `_voltro_workflow_run_events` row. */
 export declare interface RecordedEvent {
     readonly id: string;
@@ -342,8 +1255,79 @@ export declare interface RecordedStep {
     durationMs: number | null;
 }
 
+/**
+ * Free the slot an execution holds. Called when a run reaches a terminal state.
+ *
+ * Idempotent by construction: setting `releasedAt` twice is the same as setting
+ * it once, and a run that never took a lease finds no row. That matters because
+ * the terminal transition is recorded by the run recorder, which retries.
+ */
+export declare const releaseLease: (store: AdmissionDataStore, executionId: string, now: number) => Promise<boolean>;
+
+/** Resolve every declared key against one payload. Pure; throws only
+ *  {@link FlowControlKeyError}. */
+export declare const resolveAdmissionKeys: (control: ResolvedFlowControl, payload: unknown) => AdmissionKeys;
+
+/** One resolved `cancelOn` entry. The schema is kept (not pre-compiled into a
+ *  decoder) so the sweeper can report a decode failure naming the event, which
+ *  is the difference between "the predicate said no" and "we could not read the
+ *  event at all". */
+export declare interface ResolvedCancelOn {
+    readonly event: string;
+    readonly schema: Schema.Schema.Any;
+    readonly match: (event: unknown, payload: unknown) => boolean;
+    readonly withinMs?: number;
+    readonly reason: string;
+}
+
+/** The declaration with its durations resolved to milliseconds and its
+ *  defaults filled in — what the decision engine actually reads. Key functions
+ *  stay as functions; they are applied against a concrete payload at start. */
+export declare interface ResolvedFlowControl {
+    readonly workflowName: string;
+    readonly debounce?: {
+        readonly key: (payload: unknown) => string;
+        readonly periodMs: number;
+        readonly timeoutMs?: number;
+    };
+    readonly singleton?: {
+        readonly key: (payload: unknown) => string;
+        readonly mode: 'skip' | 'cancel';
+    };
+    readonly concurrency?: {
+        readonly limit: number;
+        readonly key?: (payload: unknown) => string;
+        readonly pool?: string;
+    };
+    readonly throttle?: {
+        readonly limit: number;
+        readonly periodMs: number;
+        readonly key?: (payload: unknown) => string;
+    };
+    readonly rateLimit?: {
+        readonly limit: number;
+        readonly periodMs: number;
+        readonly key?: (payload: unknown) => string;
+    };
+    readonly batch?: {
+        readonly key?: (payload: unknown) => string;
+        readonly maxSize: number;
+        readonly timeoutMs: number;
+    };
+    readonly priority?: (payload: unknown) => number;
+    readonly timeouts?: {
+        readonly startMs?: number;
+        readonly finishMs?: number;
+    };
+    readonly onFailure?: string;
+    readonly encryptSteps?: boolean;
+    readonly cancelOn?: ReadonlyArray<ResolvedCancelOn>;
+}
+
 export declare const resolveWorkflowMessageRun: (store: WorkflowMessageStore, target: WorkflowMessageTarget) => Promise<WorkflowResolvedRun>;
 
+export declare const resumeWorkflow: (store: AdmissionDataStore, workflowName: string) => Promise<boolean>;
+
 export declare const sendWorkflowSignal: (input: {
     readonly store: WorkflowMessageStore;
     readonly recorder: WorkflowRunRecorderService;
@@ -379,6 +1363,32 @@ export declare const serialiseWorkflowRowForWire: (row: Record<string, unknown>)
  */
 export declare const sleep: typeof durableClock.sleep;
 
+/**
+ * Durable sleep until an ABSOLUTE instant.
+ *
+ * Not sugar for `sleep({ duration: target - Date.now() })`, and the difference
+ * is the whole reason it exists.
+ *
+ * A delta is computed from the clock of whichever attempt computed it. Compute
+ * it in the body and the value is baked into a replay: a run that suspends for
+ * six hours and resumes replays the body, recomputes `target - Date.now()`
+ * against the NEW now, and sleeps the full period again — from a moment that is
+ * already past the target. The wait doubles, silently, and only for runs that
+ * happened to be interrupted.
+ *
+ * So the INSTANT is journaled first, by an activity, and the sleep is derived
+ * from the journaled value on every attempt. A replay after the target has
+ * passed sleeps zero and continues, which is what "until" means.
+ *
+ * ```ts
+ * yield* sleepUntil({ name: 'until-window-opens', until: order.deliverAfter })
+ * ```
+ */
+export declare const sleepUntil: (options: {
+    readonly name: string;
+    readonly until: Date | number;
+}) => Effect.Effect<void, never, never>;
+
 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>>;
 
 /**
@@ -489,8 +1499,69 @@ export declare interface StepRetryPolicy {
  */
 export declare const suspendingSignalDeferredName: (workflowName: string, signalName: string) => string;
 
+/**
+ * One cancellation tick. Never throws.
+ *
+ * A sweep that can throw takes the whole scheduled tick down with it, which
+ * means one malformed event stops cancellation for every workflow until someone
+ * notices. Failures are collected and reported instead — and the watermark
+ * still advances, because re-reading an event that has already failed to
+ * evaluate would fail identically forever.
+ */
+export declare const sweepCancelOn: (deps: CancelOnSweepDeps, options: CancelOnSweepOptions) => Promise<CancelOnSweepResult>;
+
 export declare const truncateWorkflowValue: (value: unknown, bytes?: number) => unknown;
 
+/**
+ * Validate + resolve a declaration. Throws at DEFINITION time (module load,
+ * i.e. boot) with a message naming the workflow and the field.
+ *
+ * Boot is the only honest place for these errors. A `limit: 0` that surfaces as
+ * "nothing ever runs" three hours into a deployment is the same defect class as
+ * a rate cap that drops silently — the system is behaving exactly as configured
+ * and nothing says so.
+ */
+export declare const validateFlowControl: (input: ValidateFlowControlInput) => ResolvedFlowControl | undefined;
+
+export declare interface ValidateFlowControlInput {
+    readonly workflowName: string;
+    readonly payloadSchema?: unknown;
+    readonly control: (WorkflowFlowControl<never> & WorkflowCancelOnDeclared) | undefined;
+}
+
+/**
+ * `_voltro_workflow_admissions` — append-only ledger, and the lease register.
+ *
+ * Never updated except to set `releasedAt` (a run reached a terminal state) —
+ * so a row is evidence of what the deployment decided, at the moment it decided
+ * it.
+ */
+export declare const _voltroWorkflowAdmissionsTable: SchemaTable;
+
+/**
+ * `_voltro_workflow_pauses` — one row per PAUSED workflow. Absent ⇒ running.
+ *
+ * A pause makes starts COLLECT rather than fail, so the operator who paused a
+ * workflow to ship a fix finds a backlog waiting rather than a hole in the
+ * data. That is the only behaviour that makes pause safe to reach for.
+ *
+ * The workflow name is the primary key directly — the same shape
+ * `_voltro_wakeups` uses for its natural key. Workflow names are identifiers
+ * (they are also cluster entity types), so they are comfortably inside the
+ * VARCHAR(64) an `id()` column is on MySQL/MariaDB; the bound is pinned by test
+ * rather than assumed.
+ */
+export declare const _voltroWorkflowPausesTable: SchemaTable;
+
+/**
+ * `_voltro_workflow_pending` — starts that have been accepted but not admitted.
+ *
+ * Deleted on admission. A row here is an intent the deployment OWES someone; if
+ * rows accumulate, work is not happening, and that is exactly what the
+ * `firstSeenAt` / `collapsed` / `attempts` columns exist to make visible.
+ */
+export declare const _voltroWorkflowPendingTable: SchemaTable;
+
 export declare const _voltroWorkflowRunEventsTable: SchemaTable;
 
 export declare const _voltroWorkflowRunsTable: SchemaTable;
@@ -499,6 +1570,10 @@ export declare const _voltroWorkflowRunStepsTable: SchemaTable;
 
 export declare const _voltroWorkflowStartContextsTable: TableLike;
 
+export declare const _voltroWorkflowWatermarksTable: SchemaTable;
+
+export declare const WATERMARKS_TABLE = "_voltro_workflow_watermarks";
+
 /**
  * Add compensating (rollback) logic to a top-level effect in a workflow
  * body. The finalizer runs if the WHOLE workflow later fails — use it for
@@ -518,9 +1593,228 @@ export declare const _voltroWorkflowStartContextsTable: TableLike;
  */
 export declare const withCompensation: typeof workflowModule.withCompensation;
 
-/** Define a durable workflow. Adds Voltro version metadata on top of `Workflow.make`. */
+/**
+ * Define a durable workflow.
+ *
+ * ── `idempotencyKey` is the execution's IDENTITY, permanently ──────────────
+ *
+ * Read this before choosing one. It is the single most expensive
+ * misunderstanding this API has produced — a downstream team lost a day and
+ * shipped a design around the wrong model, and the wording they read
+ * ("deduplicates concurrent invocations with the same input") is what led them
+ * there. It sounds like a WINDOW: dedupe while a run is in flight. It is not.
+ *
+ * The key IS the execution. A second start with the same key REPLAYS the first
+ * run's journaled result — forever, not just while it is running. Once the run
+ * completes the key is SPENT: a later, genuinely new invocation under that key
+ * is a silent no-op that returns the old output. Nothing errors and nothing
+ * logs, because from the engine's point of view you asked for a run it already
+ * has.
+ *
+ * ```ts
+ * const a = yield* wf.execute({ id: 'same' })
+ * const b = yield* wf.execute({ id: 'same' })   // ← does NOT run; replays `a`
+ * ```
+ *
+ * So a key must be **unique per unit of work you want to happen**, not per
+ * logical subject. `tour:${rowId}` is wrong if the tour can be re-narrated;
+ * `tour:${rowId}:${updatedAt}` is right, because every edit is a new unit of
+ * work with its own identity.
+ *
+ * ── And a flow-control key is a DIFFERENT thing ────────────────────────────
+ *
+ * The two get conflated, and conflating them is what makes "I need to re-arm a
+ * key" feel like a missing feature. It is not missing; it is two fields:
+ *
+ *   • `idempotencyKey` — the execution's identity. Vary it per unit of work.
+ *   • `debounce.key` / `singleton.key` / `concurrency.key` — the RESOURCE runs
+ *     compete for. Keep it stable.
+ *
+ * "One job, fifteen minutes after the last edit, latest state wins" is then:
+ *
+ * ```ts
+ * workflow({
+ *   name: 'tourNarration',
+ *   payload: TourPayload,
+ *   idempotencyKey: ({ rowId, editedAt }) => `tour:${rowId}:${editedAt}`, // varies
+ *   debounce: { key: (p) => `tour:${p.rowId}`, period: '15 minutes' },    // stable
+ * })
+ * ```
+ *
+ * Twenty edits mint twenty identities; exactly one is ever admitted. There is
+ * no `restart: true` and no generation counter in this API because separating
+ * the two keys is the mechanism those would have been.
+ */
 export declare const workflow: WorkflowFn;
 
+declare type WorkflowBaseOptions = Parameters<WorkflowMake>[0];
+
+/**
+ * Collect many starts into ONE run over an array of items.
+ *
+ * A hundred issue-changed events in a minute become one run over a hundred
+ * keys, not a hundred runs. The workflow's `payload` must be the BATCH shape —
+ * a struct with an `items` array — while callers `start()` it with a SINGLE
+ * item. `validateFlowControl` asserts that shape at declaration time, because
+ * the alternative is a decode failure at admission on a replica somebody else
+ * is watching.
+ */
+export declare interface WorkflowBatch<Item> {
+    /** Schema of ONE item, i.e. what a caller passes to `start()`. The workflow's
+     *  own `payload` schema describes `{ items: Array<item> }`. */
+    readonly item: unknown;
+    /** Groups items. Omit to batch everything for this workflow together. */
+    readonly key?: (item: Item) => string;
+    /** Admit as soon as this many items have accumulated. */
+    readonly maxSize: number;
+    /** Admit this long after the FIRST item, however few arrived. Unlike
+     *  debounce's period this does NOT reset — a batch is a deadline, not a quiet
+     *  period, or a steady trickle would never flush. */
+    readonly timeout: FlowDuration;
+}
+
+/**
+ * Cancel this workflow's in-flight work when a correlated domain event arrives.
+ *
+ * ── Why this is a DECLARATION and not `awaitEvent` + a race ─────────────────
+ *
+ * You can express "stop when the issue is deleted" inside the body: race the
+ * real work against an `awaitEvent`, and interrupt on the first to settle. That
+ * works while the body is RUNNING. It does not work while the run is sleeping
+ * for six hours, suspended on a signal, or still sitting in the admission
+ * queue — which is the whole reason you wanted cancellation. The event has to
+ * be able to reach a run whose fiber is not currently executing anything, and
+ * only something OUTSIDE the body can do that.
+ *
+ * So it is swept: a coordinated tick reads events published since a durable
+ * watermark, resolves each declaring workflow's live runs, evaluates `match`
+ * against the run's own decoded payload, and cancels the ones that correlate.
+ *
+ * ── What it cancels, which is more than the run ─────────────────────────────
+ *
+ * A matching event also DISCARDS queued intents of that workflow. Cancelling
+ * only the running one leaves a debounced or concurrency-queued duplicate to
+ * start seconds later, against the row that just got deleted — the exact
+ * outcome the declaration was meant to prevent, arriving late enough that
+ * nobody connects the two.
+ *
+ * ```ts
+ * cancelOn: [{
+ *   event: 'jira.issue.deleted',
+ *   schema: JiraIssueDeleted,
+ *   match: (e, payload) => e.issueKey === payload.issueKey,
+ * }],
+ * ```
+ */
+export declare interface WorkflowCancelOn<EventSchema extends Schema.Schema.Any, Payload> {
+    /** The event NAME, exactly as `ctx.events.publish` writes it. */
+    readonly event: string;
+    /** Decoded before `match` sees it, so the predicate reads the domain type
+     *  rather than whatever JSON came off the wire. A publisher shipping the
+     *  wrong shape is reported, and does NOT count as a match — cancelling on an
+     *  event you could not read is cancelling blind. */
+    readonly schema: EventSchema;
+    /**
+     * Does this event cancel THIS run?
+     *
+     * Required, with no default, for the same reason `singleton.mode` has none:
+     * the omitted case is not harmless. A missing predicate would mean "cancel
+     * every live run of this workflow", which is a legitimate thing to want and a
+     * catastrophic thing to get by forgetting a line. Write `match: () => true`
+     * when you mean it.
+     */
+    readonly match: (event: Schema.Schema.Type<EventSchema>, payload: Payload) => boolean;
+    /**
+     * Only cancel runs that started within this window before the event.
+     *
+     * Bounds the blast radius of a broad predicate — an event correlating on a
+     * tenant id would otherwise reach a run that has been alive for a week.
+     */
+    readonly within?: FlowDuration;
+    /** Recorded on the run's `run-cancelled` event and shown in the dashboard.
+     *  Defaults to `cancelOn:<event>`. */
+    readonly reason?: string;
+}
+
+/** The erased `cancelOn` shape the implementation reads. The DECLARED type is
+ *  the per-entry-inferred {@link WorkflowCancelOnList}; this is what survives
+ *  erasure, and it is deliberately not the public spelling. */
+export declare interface WorkflowCancelOnDeclared {
+    readonly cancelOn?: ReadonlyArray<WorkflowCancelOn<Schema.Schema.Any, never>>;
+}
+
+/** The `cancelOn` array as declared, with each entry's event type inferred
+ *  from its own `schema`. The tuple type parameter is what makes that
+ *  per-entry inference work — a plain `ReadonlyArray<WorkflowCancelOn<…>>`
+ *  collapses every entry's event to the constraint (`any`), which is how the
+ *  predicate silently stops being checked. */
+export declare type WorkflowCancelOnList<Cancels extends ReadonlyArray<Schema.Schema.Any>, Payload> = {
+    readonly [I in keyof Cancels]: WorkflowCancelOn<Cancels[I], Payload>;
+};
+
+/**
+ * At most `limit` runs in flight at once, per key.
+ *
+ * The limit spans every replica — it is enforced through the shared admissions
+ * ledger, so three replicas with `limit: 5` are five runs, not fifteen. (An
+ * earlier draft offered `scope: 'replica'` for a per-process budget; it is
+ * gone, and deliberately: excess starts queue in the SHARED pending table and
+ * are drained by whichever replica has capacity, so a per-process count has no
+ * coherent meaning in this model — the replica that counted is not the replica
+ * that drains.)
+ */
+export declare interface WorkflowConcurrency<Payload> {
+    readonly limit: number;
+    /** Partitions the limit. Omit for one deployment-wide pool. */
+    readonly key?: (payload: Payload) => string;
+    /**
+     * Share the limit ACROSS workflows.
+     *
+     * Without `pool`, the limit bounds THIS workflow's runs. With it, every
+     * workflow declaring the same pool name competes for ONE budget — the shape
+     * a rate-limited provider forces: five workflows that each call OpenAI must
+     * share ten slots, not hold ten each. `key` still partitions within the
+     * pool (all members' key functions feed the same buckets, so
+     * `(p) => p.tenantId` in each member yields a per-tenant shared budget).
+     *
+     * Every member of a pool must declare the SAME `limit` — the boot fails
+     * otherwise, because two limits for one budget is a contradiction, and
+     * silently picking one would enforce a number somebody did not write.
+     */
+    readonly pool?: string;
+}
+
+/**
+ * Collapse a burst of starts into ONE run, `period` after the last one.
+ *
+ * The LATEST payload wins. That is what debounce means — "fifteen minutes after
+ * the last edit, narrate what settled" wants the state as of the last edit, not
+ * the first. Stated explicitly because "first wins" is a defensible alternative
+ * and a caller must not have to guess which they got.
+ */
+export declare interface WorkflowDebounce<Payload> {
+    /** Groups the burst. Starts sharing a key collapse into one pending run. */
+    readonly key: (payload: Payload) => string;
+    /** Quiet period after the last start before the run is admitted. */
+    readonly period: FlowDuration;
+    /**
+     * Hard cap measured from the FIRST start in the burst — the run is admitted
+     * at `timeout` even if starts keep arriving.
+     *
+     * Optional, and uncapped when unset. That is deliberate and it is a real
+     * trade: an unbroken stream of starts arriving faster than `period` will
+     * defer the run forever. We do not invent a default cap (any number would be
+     * arbitrary), and we do not warn (a warning at boot rots into noise). Instead
+     * the starvation is a NUMBER you can see: the pending row carries
+     * `firstSeenAt` and `collapsed`, both surfaced by
+     * `/_voltro/inspect/workflows/flow-control` and the dashboard's Flow Control
+     * panel. A pending age climbing past a few multiples of `period` is the
+     * signal; set `timeout` when you see it, or from the start if the burst is
+     * user-driven and unbounded.
+     */
+    readonly timeout?: FlowDuration;
+}
+
 export declare interface WorkflowExecuteRecordingOptions extends WorkflowRunRecorderOptions {
     readonly name: string;
     readonly subject?: unknown;
@@ -539,14 +1833,175 @@ export declare interface WorkflowExecuteRecordingOptions extends WorkflowRunReco
     }) => Promise<void>;
     readonly recorder?: WorkflowRunRecorderService;
     readonly pluginWorkflowStepLayer?: Layer.Layer<any, never, never>;
+    /**
+     * A run reached a TERMINAL state — supplied by the CLI wiring so this package
+     * needs no knowledge of flow control.
+     *
+     * It exists to free the run's admission lease. That lease is what a
+     * `concurrency` limit counts, so a terminal transition that does not release
+     * it does not error, log, or fail a test — the limit simply admits one fewer
+     * run, permanently, and then one fewer again. A deployment that slowly stops
+     * doing work with nothing pointing at why.
+     *
+     * Called on success AND on failure, and DELIBERATELY not on suspend: a
+     * suspended run is still holding the resource it was admitted for.
+     */
+    readonly onTerminal?: (input: {
+        readonly workflowName: string;
+        readonly executionId: string;
+        readonly runId?: string;
+        readonly status: 'succeeded' | 'failed';
+    }) => Promise<void>;
 }
 
-/** Callable shape of `workflow`: the raw `Workflow.make` surface PLUS the
- *  Voltro-typed overload that threads the message-schema metadata onto the
- *  returned definition. Explicit alias so the `.d.ts` names this type by its
- *  own alias — the inferred `Workflow.make` type references internal `@effect`
- *  modules via `.pnpm` paths and is not portable (TS2742) when re-emitted. */
-declare type WorkflowFn = WorkflowMake & (<const Options extends WorkflowOptions>(options: Options) => ReturnType<WorkflowMake> & WorkflowMessagesCarrier<NormaliseWorkflowMessages<Options['messages']>>);
+/**
+ * What an `onFailure` workflow receives. Declare it as that workflow's
+ * `payload` schema — the framework validates against it like any other start,
+ * so a mismatch is a decode error naming the field rather than a silent drop.
+ */
+export declare interface WorkflowFailureReport {
+    /** The workflow that failed. */
+    readonly workflow: string;
+    /** Its payload, as it was started with. Null when the failure happened before
+     *  a payload existed (a `timeouts.finish` sweep reads the run row, not the
+     *  intent). */
+    readonly payload: unknown;
+    /** Tagged error name, when the failure carried one. */
+    readonly errorTag: string | null;
+    readonly errorMessage: string | null;
+    /** `_voltro_workflow_runs.id`, when a run existed. */
+    readonly runId: string | null;
+    readonly executionId: string | null;
+    /** Human-readable, always present: which of the four paths this was. */
+    readonly reason: string;
+    /** Epoch ms. */
+    readonly failedAt: number;
+}
+
+/** Every flow-control field, as declared on `workflow({...})`. */
+export declare interface WorkflowFlowControl<Payload> {
+    readonly debounce?: WorkflowDebounce<Payload>;
+    readonly singleton?: WorkflowSingleton<Payload>;
+    readonly concurrency?: WorkflowConcurrency<Payload>;
+    readonly throttle?: WorkflowThrottle<Payload>;
+    readonly rateLimit?: WorkflowRateLimit<Payload>;
+    readonly batch?: WorkflowBatch<Payload>;
+    /** Higher runs first out of the pending queue. Ties break by arrival, so an
+     *  all-default deployment is FIFO rather than nondeterministic. */
+    readonly priority?: (payload: Payload) => number;
+    readonly timeouts?: WorkflowTimeouts;
+    /**
+     * The NAME of a workflow to run when this one does not complete.
+     *
+     * A durable run that exhausts its retries currently ends and says nothing.
+     * The alternative people reach for is a cron over
+     * `listRuns({ status: 'failed' })` — a sweep where a signal belongs, and the
+     * shape this framework keeps trying to remove.
+     *
+     * A NAME, not a function, and that is the whole design decision. A closure
+     * cannot be journaled: the failure may be noticed by a different replica than
+     * the one that ran the workflow, minutes later, after the process that held
+     * the closure is gone. A workflow name resolves anywhere, is itself durable,
+     * retries on its own terms, and shows up in the run list like everything else.
+     *
+     * It fires for EVERY way a run fails to deliver, not only an exhausted retry:
+     *   • the body failed and retries are spent
+     *   • `timeouts.finish` cancelled an overrunning run
+     *   • `timeouts.start` expired an intent that never got a slot
+     *   • the workflow was renamed away while intents were queued
+     *
+     * Its payload is {@link WorkflowFailureReport}. Declare that as its `payload`
+     * schema. A handler that itself fails is recorded and NOT re-notified —
+     * there is no `onFailure` for the `onFailure`, deliberately: the alternative
+     * is a loop that produces one run per failure per level, forever.
+     */
+    readonly onFailure?: string;
+    /**
+     * Encrypt this workflow's journaled step `input` / `output` / `errorCause`.
+     *
+     * `step({ input })` is written to `_voltro_workflow_run_steps` and rendered in
+     * the dashboard — a feature, and the reason people pass rich input. For a step
+     * carrying personal data it is also a SECOND COPY, outside the `.encrypted()`
+     * boundary the governance plugin establishes for tables. An app that carefully
+     * encrypted a column and then handed the same value to a step has it in
+     * plaintext one table over.
+     *
+     * Reuses the cipher `governancePlugin({ fieldEncryption })` already registers,
+     * so there is ONE key and one rotation story rather than a second scheme that
+     * only workflows know about. It is therefore a BOOT ERROR to declare this
+     * without that plugin configured: silently falling back to plaintext would be
+     * the worst outcome available — the declaration reads as protection and the
+     * rows are readable.
+     *
+     * Only the journal is affected. The values the workflow BODY sees are
+     * unchanged, and the durable execution journal `@effect/workflow` keeps is
+     * untouched (encrypting that would break replay).
+     */
+    readonly encryptSteps?: boolean;
+}
+
+/** Where the RESOLVED flow-control declaration hangs off a definition. A
+ *  string property rather than a symbol, matching `WorkflowMessagesProperty`,
+ *  because the CLI's discovery reads it off a module that crossed a bundler
+ *  boundary and symbols do not survive every one of those. */
+export declare const WorkflowFlowControlProperty = "__voltroWorkflowFlowControl";
+
+/**
+ * Callable shape of `workflow` — ONE signature mirroring `Workflow.make`'s own
+ * generics, plus Voltro's version metadata, message schemas and flow control.
+ *
+ * ── Why one signature and not an intersection ─────────────────────────────
+ *
+ * This used to be `WorkflowMake & (<Options>(options: Options) => …)`: the raw
+ * effect signature first for a precise return type, ours second for the extras.
+ * That shape cannot carry flow control, and the way it fails is silent.
+ *
+ * `debounce.key: (payload) => string` must receive the workflow's own payload
+ * type. That is most of what the declaration buys over a hand-rolled debounce:
+ * a lambda typed `any` compiles, runs, and is wrong only once somebody renames
+ * a field — at which point the key becomes the string `"undefined"` and every
+ * row in the deployment collapses into one bucket, which looks exactly like a
+ * working debounce until you count the runs.
+ *
+ * Three attempts got there and were measured, not assumed:
+ *
+ *   1. `<Options extends WorkflowOptions>(o: Options & WorkflowFlowControl<
+ *      PayloadTypeOf<Options>>)` — TypeScript types the key lambdas while it is
+ *      still inferring `Options`, so the payload type resolves against the
+ *      CONSTRAINT. With `WorkflowFlowControl<never>` in it, `never` wins the
+ *      contextual-type merge and the parameters fall back to implicit `any`.
+ *   2. Taking it out of the constraint was not enough: `Options` is a NAKED
+ *      type parameter inside the parameter's intersection, and TypeScript does
+ *      not push contextual types through an intersection it cannot decompose.
+ *   3. Spelling the parameter out concretely fixed THAT, and the call still
+ *      typed the lambda as `any` — because `workflow` was still an
+ *      INTERSECTION of two call signatures, and overload resolution types
+ *      context-sensitive arguments before it fixes type parameters.
+ *
+ * So: no intersection. The generics below are `Workflow.make`'s own, which is
+ * what makes a single signature able to accept everything it accepted. The
+ * return type improves as a side effect — it was `ReturnType<WorkflowMake>`
+ * (i.e. `Workflow<any, any, any>`) for any workflow that declared `messages`,
+ * because such a call fell through to the second overload.
+ *
+ * `flowControl.test-d.ts` pins the result, including a `@ts-expect-error` on a
+ * misspelled payload field. That assertion is the one that silently stops
+ * meaning anything if this ever regresses to `any` — which is precisely what
+ * all three failed attempts did.
+ */
+declare type WorkflowFn = <const Name extends string, Payload extends WorkflowPayloadInput, Success extends Schema.Schema.Any = typeof Schema.Void, Error extends Schema.Schema.All = typeof Schema.Never, const Messages extends WorkflowMessageSchemas | undefined = undefined, Cancels extends ReadonlyArray<Schema.Schema.Any> = readonly []>(options: {
+    readonly name: Name;
+    readonly payload: Payload;
+    readonly idempotencyKey: (payload: DecodedPayload<Payload>) => string;
+    readonly success?: Success;
+    readonly error?: Error;
+    /** Cancel live runs when a correlated event arrives. Each entry's event
+     *  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>>;
+} & Omit<WorkflowBaseOptions, 'name' | 'payload' | 'idempotencyKey' | 'success' | 'error'> & WorkflowVersionOptions & {
+    readonly messages?: Messages;
+} & WorkflowFlowControl<DecodedPayload<Payload>>) => workflowModule.Workflow<Name, PayloadSchemaOf<Payload>, Success, Error> & WorkflowMessagesCarrier<NormaliseWorkflowMessages<Messages>>;
 
 declare type WorkflowMake = typeof workflowModule.make;
 
@@ -589,10 +2044,6 @@ export declare interface WorkflowMessageTarget {
 
 export { workflowModule }
 
-declare type WorkflowOptions = Parameters<WorkflowMake>[0] & WorkflowVersionOptions & {
-    readonly messages?: WorkflowMessageSchemas;
-};
-
 export declare interface WorkflowParentCloseDecision {
     readonly runId: string;
     readonly workflowName: string;
@@ -620,6 +2071,26 @@ export declare interface WorkflowParentCloseStore {
     update(table: string, id: string, patch: unknown): Promise<unknown | null>;
 }
 
+/** Everything `Workflow.make` accepts for `payload`: a struct Schema, or bare
+ *  `Fields`. Both stay supported — a key lambda must not silently degrade to
+ *  `any` because the workflow spelled its payload the shorter way. */
+declare type WorkflowPayloadInput = WorkflowBaseOptions['payload'];
+
+/**
+ * Hard cap: starts beyond `limit` per `period` are DROPPED, not queued.
+ *
+ * A dropped start is reported — `start()` resolves to a handle with
+ * `status: 'dropped'` and a `retryAfterMs`, and the drop is a row in the
+ * admissions ledger with its key and reason. It is never silent. A cap that
+ * discards work without saying so is indistinguishable from a bug, which is
+ * exactly the failure this framework keeps writing guards against.
+ */
+export declare interface WorkflowRateLimit<Payload> {
+    readonly limit: number;
+    readonly period: FlowDuration;
+    readonly key?: (payload: Payload) => string;
+}
+
 export declare interface WorkflowRecordingEmitter {
     emit(channel: 'workflowRuns' | 'workflowSteps' | 'workflowEvents', event: {
         readonly op: 'insert' | 'update';
@@ -734,6 +2205,26 @@ export declare interface WorkflowRunRecorderOptions {
      *  per run at a TERMINAL outcome (succeeded/failed), never on suspend. Absent →
      *  no metrics, zero overhead. */
     readonly recordRun?: (outcome: WorkflowRunOutcome) => void;
+    /**
+     * Encrypt the `input` / `output` / `errorCause` a step journals.
+     *
+     * `step({ input })` is written to `_voltro_workflow_run_steps` and shown in
+     * the dashboard, which is a feature and the reason people pass rich input. For
+     * a step carrying personal data it is also a SECOND COPY, outside the
+     * `.encrypted()` boundary the governance plugin establishes for tables — so an
+     * app that carefully encrypted a column then handed the same value to a step
+     * has it in plaintext one table over.
+     *
+     * Supplied by the CLI from the cipher `governancePlugin({ fieldEncryption })`
+     * already registers, so there is ONE key and one rotation story rather than a
+     * second scheme for workflows. Absent → plaintext, exactly as before.
+     *
+     * Encryption happens on the WRITE and decryption on the inspect read, so the
+     * dashboard is unchanged for a viewer who is allowed to see it and the value
+     * at rest is not. A ciphertext that cannot be decrypted renders as a marker
+     * rather than as garbage — see `inspectWorkflow`.
+     */
+    readonly encryptStepPayload?: (value: unknown) => unknown;
 }
 
 /** Per-step lifecycle hooks. Implementations should not throw —
@@ -806,6 +2297,29 @@ export declare interface WorkflowRunRecorderService {
     }>;
 }
 
+/**
+ * At most one run per key. The newcomer either stands down or evicts.
+ *
+ * `key` is the RESOURCE, not the identity — see the module header. Two starts
+ * with different `idempotencyKey`s can absolutely collide here, and that is the
+ * point.
+ */
+export declare interface WorkflowSingleton<Payload> {
+    readonly key: (payload: Payload) => string;
+    /**
+     * `'skip'`   — a start arriving while the key is held returns the INCUMBENT's
+     *              handle. No new run, no error. Use when the work in flight is
+     *              as good as the work you were about to ask for.
+     * `'cancel'` — the incumbent is cancelled and the newcomer runs. Use when the
+     *              newcomer carries fresher input and the incumbent's partial
+     *              work is worthless.
+     *
+     * There is no default: the two answers are opposite and picking one for you
+     * would silently discard either the new request or the running one.
+     */
+    readonly mode: 'skip' | 'cancel';
+}
+
 /**
  * Per-step plugin interceptor. Plugins can wrap every `step()`
  * (== `Activity.make`) invocation with observability, suppress /
@@ -843,6 +2357,37 @@ export declare class WorkflowStepInterceptorTag extends WorkflowStepInterceptorT
 
 declare const WorkflowStepInterceptorTag_base: Context.TagClass<WorkflowStepInterceptorTag, "@voltro/WorkflowStepInterceptor", WorkflowStepInterceptorService>;
 
+/**
+ * Smooth throughput: excess starts QUEUE and are admitted as capacity frees up.
+ *
+ * The counterpart to {@link WorkflowRateLimit}, which DROPS the excess. Reach
+ * for throttle when every start must eventually run and you only care that they
+ * do not run all at once; reach for rate limit when the excess is genuinely
+ * surplus and running it late is worse than not running it.
+ */
+export declare interface WorkflowThrottle<Payload> {
+    readonly limit: number;
+    readonly period: FlowDuration;
+    readonly key?: (payload: Payload) => string;
+}
+
+/**
+ * Wall-clock bounds on a run, distinct from a step's retry policy.
+ *
+ * `start` bounds how long a run may sit in the admission queue — a debounced or
+ * concurrency-queued run that never gets a slot is a job that silently did not
+ * happen. `finish` bounds the run itself once admitted.
+ *
+ * Both expire into the SAME path as an exhausted retry: the run is recorded
+ * `failed` with an `errorTag` naming which bound was hit, and `onFailure` fires.
+ * A timeout that expired quietly would be the sweep-instead-of-signal shape this
+ * whole feature exists to remove.
+ */
+export declare interface WorkflowTimeouts {
+    readonly start?: FlowDuration;
+    readonly finish?: FlowDuration;
+}
+
 export declare interface WorkflowUpdateResult {
     readonly eventId: string;
     readonly updateId: string;
@@ -920,4 +2465,15 @@ export declare const WorkflowWorkerLayerTypeId: unique symbol;
 
 export declare const wrapWorkflowExecuteWithRunRecording: (options: WorkflowExecuteRecordingOptions, userExecute: (payload: unknown, executionId: string) => Effect.Effect<unknown, unknown, never>) => (payload: unknown, executionId: string) => Effect.Effect<unknown, unknown, never>;
 
+/**
+ * Advance the stored position.
+ *
+ * Never moves BACKWARDS. The update function compares against the row as it is
+ * at write time, so a slow replica finishing an old batch cannot rewind a
+ * faster one and cause the window in between to be swept twice — or, worse,
+ * cause a `discardIntent` on an intent that has since been legitimately
+ * re-queued.
+ */
+export declare const writeWatermark: (store: CancelOnDataStore, name: string, at: Date) => Promise<void>;
+
 export { }