@voltro/workflow 0.29.0 → 0.30.1

package/dist/primitives.d.ts

@@ -1,11 +1,52 @@
 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 { Schema } from 'effect';
 import { Activity as stepModule } from '@effect/workflow';
 import { Workflow as workflowModule } from '@effect/workflow';
 
+/**
+ * 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;
+
+/** 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;
+
+/**
+ * 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>;
+
 export { durableClock }
 
 /** Define a durable queue for concurrency-controlled side work. */
@@ -15,8 +56,32 @@ export { durableQueueModule }
 
 export { durableRateLimiterModule }
 
+/** 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;
+
+/** 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 const isWorkflowWorkerLayer: (value: unknown) => value is WorkflowWorkerLayerBrand;
 
 declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefined> = {
@@ -31,6 +96,9 @@ declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefi
     } ? NonNullable<Queries> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
 };
 
+/** The SCHEMA a payload input denotes — `Fields` lifted into a `Struct`. */
+declare type PayloadSchemaOf<P> = P extends Schema.Struct.Fields ? Schema.Struct<P> : P;
+
 /** Enqueue work and await the durable queue worker's result. */
 export declare const processQueue: typeof durableQueueModule.process;
 
@@ -46,6 +114,74 @@ export declare const queueWorker: typeof durableQueueModule.worker;
 /** Durable rate limiter activity. Delays through the workflow clock. */
 export declare const rateLimit: typeof durableRateLimiterModule.rateLimit;
 
+/** 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;
+        /**
+         * Schema of ONE item — what a CALLER passes to `start()`, as opposed to the
+         * workflow's own `{ items: [...] }` payload.
+         *
+         * Carried through resolution because the facade validates an arriving start
+         * against it. It used to be declared, asserted at declaration time, and then
+         * dropped here — so every `start()` on a batching workflow was validated
+         * against the batch shape it is not, and threw `WorkflowPayloadError` before
+         * the gate ever saw it. A required option nothing reads is worse than an
+         * absent one: it reads as wired.
+         */
+        readonly item?: unknown;
+    };
+    readonly priority?: (payload: unknown) => number;
+    readonly timeouts?: {
+        readonly startMs?: number;
+        readonly finishMs?: number;
+    };
+    readonly onFailure?: string;
+    readonly encryptSteps?: boolean;
+    readonly cancelOn?: ReadonlyArray<ResolvedCancelOn>;
+}
+
 /**
  * Durable sleep — wake time journaled in the cluster. Wrapper around
  * `DurableClock.sleep` that emits `timer-set` / `timer-fired` events
@@ -60,6 +196,32 @@ export declare const rateLimit: typeof durableRateLimiterModule.rateLimit;
  */
 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>>;
 
 /**
@@ -123,7 +285,7 @@ declare type StepOptions<R, Success extends Schema.Schema.Any, Error extends Sch
  * JSON-serialisable EXCEPT `retryable` (a predicate), which the recorder drops
  * when it stores the policy as dashboard metadata.
  */
-declare interface StepRetryPolicy {
+export declare interface StepRetryPolicy {
     /** Total attempts INCLUDING the first. Default `3`. `1` disables retry. */
     readonly maxAttempts?: number;
     /** Backoff shape between attempts. Default `'exponential'`. */
@@ -162,6 +324,23 @@ declare interface StepRetryPolicy {
     readonly note?: string;
 }
 
+/**
+ * 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;
+}
+
 /**
  * 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
@@ -181,15 +360,376 @@ declare interface StepRetryPolicy {
  */
 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;
 
-/** 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']>>);
+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;
+}
+
+/**
+ * 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;
 
@@ -218,9 +758,79 @@ export declare const WorkflowMessagesProperty = "__voltroWorkflowMessages";
 
 export { workflowModule }
 
-declare type WorkflowOptions = Parameters<WorkflowMake>[0] & WorkflowVersionOptions & {
-    readonly messages?: WorkflowMessageSchemas;
-};
+/** 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;
+}
+
+/**
+ * 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';
+}
+
+/**
+ * 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 WorkflowVersionMetadata {
     readonly version: string;