@voltro/workflow 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,865 @@
+import { Cause } from 'effect';
+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 { Effect } from 'effect';
+import { FiberRef } from 'effect';
+import { Layer } from 'effect';
+import { ParseResult } from 'effect';
+import { QueryDescriptor } from '@voltro/database';
+import { Row } from '@voltro/database';
+import { Schema } from 'effect';
+import { SchemaTable } from '@voltro/database';
+import { Activity as stepModule } from '@effect/workflow';
+import { Subject } from '@voltro/protocol';
+import { TableLike } from '@voltro/database';
+import { WorkflowEngine } from '@effect/workflow';
+import { Workflow as workflowModule } from '@effect/workflow';
+import { WorkflowParentClosePolicy } from '@voltro/protocol';
+
+/**
+ * Wait inside a workflow body for an externally-injected signal.
+ *
+ * Usage:
+ * ```ts
+ * const buildExecute = (ctx: AppContext) =>
+ *   (input: { ... }) =>
+ *     Effect.gen(function* () {
+ *       // ... earlier steps ...
+ *       const decision = yield* awaitSignal(ctx, {
+ *         name: 'approval',
+ *         schema: Schema.Struct({ approved: Schema.Boolean }),
+ *       })
+ *       // `decision: { approved: boolean }` — typed by the schema.
+ *       if (!decision.approved) return { status: 'rejected' as const }
+ *       // ... continue ...
+ *     })
+ * ```
+ *
+ * From the dashboard, click "Send signal" on the run row and pick
+ * `approval` with a JSON body matching the schema.
+ */
+export declare const awaitSignal: <A>(ctx: AwaitSignalCtx, options: AwaitSignalOptions<A>) => Effect.Effect<A, Cause.UnknownException | ParseResult.ParseError>;
+
+/** The slice of `ctx.store` awaitSignal needs — just `query`, typed against
+ *  the real `QueryDescriptor` so a full `AppContext` store (`DataStore`) is
+ *  assignable. This is what makes the documented `awaitSignal(ctx, …)` call
+ *  inside a workflow executor typecheck. (`@voltro/workflow` already depends on
+ *  `@voltro/database` — see the `and`/`eq` import above — so this adds no new
+ *  package edge.) */
+export declare interface AwaitSignalCtx {
+    readonly store: {
+        readonly query: (descriptor: QueryDescriptor) => Promise<ReadonlyArray<unknown>>;
+    };
+}
+
+export declare interface AwaitSignalOptions<A> {
+    /** Caller-chosen signal name. Mirror this in the dashboard's "Send
+     *  signal" modal — the inspect bus matches on this exact string. */
+    readonly name: string;
+    /** Schema the incoming payload is parsed against. Parse failures
+     *  fail the activity with a typed error (the schema's ParseError);
+     *  fix the sender's payload shape and re-send. */
+    readonly schema: Schema.Schema<A, any>;
+    /** Initial poll interval in milliseconds. Default 200 ms — gives
+     *  sub-second wake for fresh signals. Subsequent polls back off
+     *  exponentially up to `maxPollIntervalMs`. */
+    readonly pollIntervalMs?: number;
+    /** Upper bound on the exponential backoff. Default 5000 ms. The
+     *  poll loop never sleeps longer than this between checks. */
+    readonly maxPollIntervalMs?: number;
+    /** Max time to wait before failing the activity. Default 24 h.
+     *  Pass `Number.POSITIVE_INFINITY` for an unbounded wait. */
+    readonly timeoutMs?: number;
+}
+
+/**
+ * Wait inside a workflow body for an externally-injected signal, SUSPENDING
+ * the run (freeing its worker) until the signal arrives or the timeout fires.
+ *
+ * Drop-in shape-compatible with {@link awaitSignal}; prefer this variant for
+ * waits that may last minutes/hours/days (human-in-the-loop, AI-Flows) so a
+ * parked run does not pin a fiber.
+ *
+ * ```ts
+ * const decision = yield* awaitSignalSuspending(ctx, {
+ *   name: 'approval',
+ *   schema: Schema.Struct({ approved: Schema.Boolean }),
+ * })
+ * // `decision: { approved: boolean }` — the run was Suspended until an
+ * // external `ctx.workflows.signal(target, 'approval', { approved })` resumed it.
+ * ```
+ *
+ * `ctx` is accepted for signature parity with `awaitSignal` (so the two are
+ * interchangeable in a body); the suspending variant reads the durable
+ * deferred, not `ctx.store`.
+ */
+export declare const awaitSignalSuspending: <A>(ctx: AwaitSignalCtx, options: AwaitSignalSuspendingOptions<A>) => Effect.Effect<A, ParseResult.ParseError>;
+
+export declare interface AwaitSignalSuspendingOptions<A> {
+    /** Caller-chosen signal name. The external completer targets this exact
+     *  string — mirror it in the dashboard's "Send signal" modal. */
+    readonly name: string;
+    /** Schema the incoming payload is decoded against. A decode failure fails
+     *  the workflow with the schema's `ParseError`. */
+    readonly schema: Schema.Schema<A, any>;
+    /** Max time to wait before failing the workflow. Default 24 h. The timeout
+     *  is itself durable (a raced `DurableClock`), so a long wait frees the
+     *  runner too. Pass `Number.POSITIVE_INFINITY` for an unbounded wait. */
+    readonly timeoutMs?: number;
+}
+
+export declare const awaitUpdate: <A, B = A>(ctx: AwaitUpdateCtx, options: AwaitUpdateOptions<A, B>) => Effect.Effect<B, unknown, never>;
+
+/** The `ctx.store` slice awaitUpdate needs, typed against the real
+ *  `QueryDescriptor` so a full `AppContext` store (`DataStore`) is assignable —
+ *  i.e. so the documented `awaitUpdate(ctx, …)` call inside an executor
+ *  typechecks. Mirrors `AwaitSignalCtx`. */
+export declare interface AwaitUpdateCtx {
+    readonly store: {
+        readonly query: (descriptor: QueryDescriptor) => Promise<ReadonlyArray<unknown>>;
+    };
+}
+
+export declare interface AwaitUpdateOptions<A, B = A> {
+    readonly name: string;
+    readonly schema: Schema.Schema<A, any>;
+    readonly success?: Schema.Schema<B, any>;
+    readonly handle?: (payload: A) => Effect.Effect<B, unknown, never>;
+    readonly pollIntervalMs?: number;
+    readonly maxPollIntervalMs?: number;
+    readonly timeoutMs?: number;
+}
+
+export declare const closeWorkflowChildrenForParent: (options: CloseWorkflowChildrenForParentOptions) => Promise<ReadonlyArray<WorkflowParentCloseDecision>>;
+
+export declare interface CloseWorkflowChildrenForParentOptions {
+    readonly store: WorkflowParentCloseStore;
+    readonly parentExecutionId: string;
+    readonly parentStatus: WorkflowParentCloseStatus;
+    readonly recorder?: WorkflowRunRecorderService;
+    readonly emit?: WorkflowParentCloseEmitter['emit'];
+    readonly log?: WorkflowParentCloseLogger;
+    readonly limit?: number;
+    readonly interruptChild: (workflowName: string, executionId: string, policy: Exclude<WorkflowParentClosePolicy, 'abandon'>) => Promise<void>;
+}
+
+/**
+ * Externally complete a suspending signal wait, resuming the parked run with
+ * `payload`. The counterpart to {@link awaitSignalSuspending} and the
+ * suspending analogue of `sendWorkflowSignal`.
+ *
+ * Returns an `Effect` that requires the `WorkflowEngine` — run it through the
+ * same runner that executes workflows (the CLI's `workflowRuntime.runPromise`,
+ * i.e. the facade's `runEffect`), so `DurableDeferred.done` reaches the engine.
+ *
+ * Completing a deferred that no run is awaiting is a no-op, so it is safe to
+ * call this for every signal alongside `sendWorkflowSignal` — the polling
+ * `awaitSignal` reads the row, the suspending variant reads the deferred, and
+ * whichever the target workflow uses resumes.
+ */
+export declare const completeSuspendingSignal: (input: CompleteSuspendingSignalInput) => Effect.Effect<{
+    readonly completed: boolean;
+}, Cause.UnknownException, WorkflowEngine.WorkflowEngine>;
+
+/** Input to {@link completeSuspendingSignal}. */
+export declare interface CompleteSuspendingSignalInput {
+    /** Which run to resume. If it carries BOTH `executionId` and `workflowName`
+     *  the store lookup is skipped; otherwise `store` is used to resolve them. */
+    readonly target: WorkflowMessageTarget;
+    /** Signal name — must match the workflow's `awaitSignalSuspending({ name })`. */
+    readonly signalName: string;
+    /** Payload delivered to the workflow. Stored raw and decoded on the awaiting
+     *  side through that call's `schema`. */
+    readonly payload?: unknown;
+    /** Store used to resolve the run's `executionId` + workflow name when the
+     *  target doesn't already provide both. */
+    readonly store?: WorkflowMessageStore;
+}
+
+/** FiberRef carrying the active workflow's executionId — set by
+ *  `wrapWithRunRecording` on every workflow body entry, read by a
+ *  child workflow's recorder to populate
+ *  `_voltro_workflow_runs.parentExecutionId`. Distinct
+ *  from `CurrentWorkflowRunId` (which is the runs-row primary key)
+ *  because the natural durable id used by other workflows is the
+ *  engine-assigned executionId, not our row id. */
+export declare const CurrentWorkflowExecutionId: FiberRef.FiberRef<string | undefined>;
+
+/** FiberRef carrying the active workflow run's id. The outer
+ *  `wrapWithRunRecording` in dev.ts sets it via
+ *  `Effect.locally(CurrentWorkflowRunId, runId)`. */
+export declare const CurrentWorkflowRunId: FiberRef.FiberRef<string | undefined>;
+
+export { durableClock }
+
+/** Define a durable queue for concurrency-controlled side work. */
+export declare const durableQueue: typeof durableQueueModule.make;
+
+export { durableQueueModule }
+
+export { durableRateLimiterModule }
+
+/** 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>;
+
+/** Try to read the current run id. Returns undefined when not in a
+ *  recorded workflow context (= step is being run outside the
+ *  framework's wrapper, e.g. in a unit test). */
+export declare const getCurrentWorkflowRunId: () => Effect.Effect<string | undefined>;
+
+export declare const getWorkflowVersionMetadata: (value: unknown) => WorkflowVersionMetadata;
+
+export declare interface InMemoryRecorder {
+    readonly layer: Layer.Layer<WorkflowRunRecorder>;
+    readonly readSteps: () => ReadonlyArray<RecordedStep>;
+    readonly readEvents: () => ReadonlyArray<RecordedEvent>;
+}
+
+export declare const inMemoryWorkflowEngineLayer: Layer.Layer<WorkflowEngine.WorkflowEngine>;
+
+export declare interface InspectedStep {
+    readonly name: string;
+    /** The attempt number of THIS row (1 on first try, 2+ on retry). When
+     *  a step has multiple attempts, the assembled step reflects the
+     *  latest attempt's status/output/error. */
+    readonly attempt: number;
+    /** Total attempts recorded for this stepName (row count). */
+    readonly attempts: number;
+    readonly status: 'running' | 'succeeded' | 'failed';
+    readonly input: unknown;
+    readonly output: unknown;
+    readonly error: {
+        readonly tag: string | null;
+        readonly message: string;
+    } | null;
+    readonly durationMs: number | null;
+}
+
+export declare interface InspectedWorkflow {
+    readonly id: string;
+    readonly executionId: string;
+    readonly name: string;
+    readonly status: 'running' | 'succeeded' | 'failed' | 'cancelled' | 'suspended';
+    readonly input: unknown;
+    readonly output: unknown;
+    readonly subject: Subject | null;
+    readonly source: string | null;
+    readonly steps: ReadonlyArray<InspectedStep>;
+    readonly startedAt: Date;
+    readonly finishedAt: Date | null;
+    readonly traceId: string | null;
+    readonly parentExecutionId: string | null;
+    readonly parentClosePolicy: WorkflowParentClosePolicy | null;
+}
+
+/** Minimal store surface `inspectWorkflow` needs: descriptor-in /
+ *  rows-out. Satisfied by `FluentStore`, `DataStore`, and
+ *  `InMemoryDataStore`. */
+export declare interface InspectStore {
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
+}
+
+/**
+ * Resolve a workflow run by its `id` OR its `executionId`, assemble the
+ * full inspected shape (run header + per-step attempts), and return it.
+ * Returns `null` when no run matches.
+ *
+ * @param idOrExecutionId  `_voltro_workflow_runs.id` or `.executionId`.
+ * @param store            any `query`-capable store (fluent `ctx.store`,
+ *                         `InMemoryDataStore`, or a live SQL `DataStore`).
+ */
+export declare const inspectWorkflow: (idOrExecutionId: string, store: InspectStore) => Promise<InspectedWorkflow | null>;
+
+export declare const isWorkflowWorkerLayer: (value: unknown) => value is WorkflowWorkerLayerBrand;
+
+export declare const makeInMemoryRecorder: () => InMemoryRecorder;
+
+export declare const makeWorkflowRunRecorder: (options: WorkflowRunRecorderOptions) => WorkflowRunRecorderService;
+
+export declare const makeWorkflowUpdateId: () => string;
+
+declare type NormaliseWorkflowMessages<M extends WorkflowMessageSchemas | undefined> = {
+    readonly signals: M extends {
+        readonly signals: infer Signals;
+    } ? NonNullable<Signals> & Readonly<Record<string, Schema.Schema.Any>> : {};
+    readonly updates: M extends {
+        readonly updates: infer Updates;
+    } ? NonNullable<Updates> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
+    readonly queries: M extends {
+        readonly queries: infer Queries;
+    } ? NonNullable<Queries> & Readonly<Record<string, WorkflowMessagePairSchemas>> : {};
+};
+
+/** Enqueue work and await the durable queue worker's result. */
+export declare const processQueue: typeof durableQueueModule.process;
+
+/** Start a durable queue worker layer with bounded concurrency.
+ *
+ *  `DurableQueue.worker` is itself generic (`<Payload, Success, Error, R>`), so
+ *  a hand-written wrapper can't re-state that generic signature — the body runs
+ *  against erased args and the const's explicit `: typeof DurableQueue.worker`
+ *  annotation restores the full generic public type. That annotation (not an
+ *  inferred type) is what emits in the `.d.ts`, so it stays portable. */
+export declare const queueWorker: typeof durableQueueModule.worker;
+
+/** Durable rate limiter activity. Delays through the workflow clock. */
+export declare const rateLimit: typeof durableRateLimiterModule.rateLimit;
+
+/** One recorded run-event — mirrors a `_voltro_workflow_run_events` row. */
+export declare interface RecordedEvent {
+    readonly id: string;
+    readonly runId: string;
+    readonly eventType: WorkflowRunEventType;
+    readonly payload: Record<string, unknown> | null;
+    readonly stepName: string | null;
+    readonly attempt: number | null;
+    readonly occurredAt: Date;
+}
+
+/** One recorded step attempt — mirrors a `_voltro_workflow_run_steps`
+ *  row closely enough for inspection. One row per attempt. */
+export declare interface RecordedStep {
+    readonly id: string;
+    readonly runId: string;
+    readonly stepName: string;
+    readonly attempt: number;
+    status: 'running' | 'succeeded' | 'failed';
+    readonly input: unknown;
+    readonly retryPolicy: StepRetryPolicy | null;
+    output: unknown;
+    errorTag: string | null;
+    errorMessage: string | null;
+    errorCause: {
+        readonly pretty: string;
+        readonly failures: ReadonlyArray<unknown>;
+        readonly defects: ReadonlyArray<unknown>;
+    } | null;
+    readonly startedAt: Date;
+    completedAt: Date | null;
+    durationMs: number | null;
+}
+
+export declare const resolveWorkflowMessageRun: (store: WorkflowMessageStore, target: WorkflowMessageTarget) => Promise<WorkflowResolvedRun>;
+
+export declare const sendWorkflowSignal: (input: {
+    readonly store: WorkflowMessageStore;
+    readonly recorder: WorkflowRunRecorderService;
+    readonly target: WorkflowMessageTarget;
+    readonly signalName: string;
+    readonly payload?: unknown;
+}) => Promise<{
+    readonly eventId: string;
+}>;
+
+export declare const sendWorkflowUpdate: (input: {
+    readonly store: WorkflowMessageStore;
+    readonly recorder: WorkflowRunRecorderService;
+    readonly target: WorkflowMessageTarget;
+    readonly updateName: string;
+    readonly payload?: unknown;
+    readonly options?: WorkflowUpdateSendOptions;
+}) => Promise<WorkflowUpdateResult>;
+
+export declare const serialiseWorkflowRowForWire: (row: Record<string, unknown>) => Record<string, unknown>;
+
+/**
+ * Durable sleep — wake time journaled in the cluster. Wrapper around
+ * `DurableClock.sleep` that emits `timer-set` / `timer-fired` events
+ * to the recorder so the dashboard's Gantt timeline renders the wait
+ * as a visible bar — a workflow waiting on a cron-style delay should
+ * not look like a black hole.
+ *
+ * The wrap is transparent: signature matches `DurableClock.sleep`,
+ * no observable behavior change beyond the event emissions. When no
+ * recorder is in scope (unit tests, no `voltro dev`/`voltro start`
+ * wrapper around the workflow) it's a zero-overhead passthrough.
+ */
+export declare const sleep: typeof durableClock.sleep;
+
+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>>;
+
+/**
+ * Derive a deterministic idempotency key for the current workflow run,
+ * scoped to `name`. Call it inside a `step()` so a retried external
+ * side-effect converges on a single key instead of double-creating —
+ * pair it with a read-before-write provider-operations ledger. Pass
+ * `{ includeAttempt: true }` to vary the key per attempt.
+ *
+ * Named for the framework's `step` vocabulary (it is upstream's
+ * `Activity.idempotencyKey`).
+ */
+export declare const stepIdempotencyKey: typeof stepModule.idempotencyKey;
+
+export { stepModule }
+
+/**
+ * Define a checkpointed step (activity) inside a workflow body.
+ *
+ * Wraps `@effect/workflow`'s `Activity.make` to record every
+ * invocation in `_voltro_workflow_run_steps`. The wrapping is
+ * transparent — accepts everything `Activity.make` accepts, plus an
+ * optional `input` field whose value is persisted to the step row
+ * (truncated to 8 KB by the recorder). The dashboard surfaces it as
+ * "Input" alongside Output, so operators can answer "what arguments
+ * did this step receive?" without grep-ing logs.
+ *
+ * ```ts
+ * step({
+ *   name: 'fetch-todos',
+ *   input: { tenantId, since: lastFetch },  // ← optional, recorded
+ *   execute: Effect.tryPromise({ try: () => ctx.store.query(...) }),
+ * })
+ * ```
+ *
+ * Without the recorder service in scope (unit tests, etc.) the input
+ * is dropped and the wrap is a no-op.
+ */
+declare type StepOptions<R, Success extends Schema.Schema.Any, Error extends Schema.Schema.All> = {
+    readonly name: string;
+    readonly success?: Success | undefined;
+    readonly error?: Error | undefined;
+    readonly execute: Effect.Effect<Success['Type'], Error['Type'], R>;
+    readonly interruptRetryPolicy?: Parameters<typeof stepModule.make<R, Success, Error>>[0]['interruptRetryPolicy'];
+    /** Structured value recorded into `_voltro_workflow_run_steps.input`.
+     *  Pass whatever makes the step debuggable in isolation. */
+    readonly input?: unknown;
+    /** Declarative retry-policy summary recorded into
+     *  `_voltro_workflow_run_steps.retryPolicy`. Pure metadata — does
+     *  NOT change retry behavior on its own. Wire actual retries via
+     *  `Effect.retry` inside `execute:` or via `interruptRetryPolicy`
+     *  above; this field tells the dashboard what the intended policy
+     *  looks like so the per-attempt panel can show "attempt 2 of 5,
+     *  exponential 1s base" instead of just "attempt 2". */
+    readonly retry?: StepRetryPolicy;
+};
+
+/**
+ * Declarative retry-policy summary. Pure metadata for the dashboard;
+ * the framework does NOT apply this. Users wire actual retry behavior
+ * via `Effect.retry(Schedule.*)` inside `execute:` or
+ * `Activity.make`'s `interruptRetryPolicy`.
+ *
+ * Shape is intentionally close to Effect's Schedule combinators so a
+ * future framework version can auto-translate declarative policies
+ * into a Schedule + apply it. For now: record + display.
+ *
+ *   { strategy: 'exponential', maxAttempts: 5, baseDelay: '1 second', maxDelay: '30 seconds' }
+ *   { strategy: 'fixed',       maxAttempts: 3, baseDelay: '500 millis' }
+ *   { strategy: 'linear',      maxAttempts: 4, baseDelay: '1 second',  step: '2 seconds' }
+ */
+export declare interface StepRetryPolicy {
+    readonly strategy: 'exponential' | 'fixed' | 'linear';
+    readonly maxAttempts: number;
+    /** Effect Duration string, e.g. `'1 second'`, `'500 millis'`. */
+    readonly baseDelay?: string;
+    /** Cap on exponential / linear growth, e.g. `'30 seconds'`. */
+    readonly maxDelay?: string;
+    /** Increment for `linear` strategy. */
+    readonly step?: string;
+    /** Free-form note rendered as a chip in the dashboard. Useful when
+     *  the retry behavior is partially implemented in the user's
+     *  Effect chain and the summary is just documentation. */
+    readonly note?: string;
+}
+
+/**
+ * The stable `DurableDeferred` name for a suspending signal wait. It is a pure
+ * function of the workflow name + the signal name, so the awaiting body and an
+ * external completer derive the SAME name without any shared state — the
+ * engine keys the deferred result by `<executionId>/<this name>`.
+ */
+export declare const suspendingSignalDeferredName: (workflowName: string, signalName: string) => string;
+
+export declare const truncateWorkflowValue: (value: unknown, bytes?: number) => unknown;
+
+export declare const _voltroWorkflowRunEventsTable: SchemaTable;
+
+export declare const _voltroWorkflowRunsTable: SchemaTable;
+
+export declare const _voltroWorkflowRunStepsTable: SchemaTable;
+
+export declare const _voltroWorkflowStartContextsTable: TableLike;
+
+/**
+ * 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
+ * saga-style undo: release a half-acquired resource, revert a partial
+ * promotion. Upstream constraint: compensation is registered only for
+ * top-level effects in the workflow, NOT for nested steps/activities.
+ *
+ * Pinned with `typeof` to keep the emitted .d.ts portable (see the TS2742
+ * note above the type-explicit re-exports).
+ *
+ * ```ts
+ * yield* withCompensation(
+ *   step({ name: 'provision-db', execute: ... }),
+ *   (resource) => releaseResource(resource),  // runs only if the workflow fails
+ * )
+ * ```
+ */
+export declare const withCompensation: typeof workflowModule.withCompensation;
+
+/** Define a durable workflow. Adds Voltro version metadata on top of `Workflow.make`. */
+export declare const workflow: WorkflowFn;
+
+export declare interface WorkflowExecuteRecordingOptions extends WorkflowRunRecorderOptions {
+    readonly name: string;
+    readonly subject?: unknown;
+    readonly source?: string | null;
+    readonly traceId?: string | null;
+    readonly workflowVersion?: string | null;
+    readonly workflowCompatibleVersions?: ReadonlyArray<string> | null;
+    readonly workflowPatches?: ReadonlyArray<string> | null;
+    readonly parentExecutionId?: string | null;
+    readonly parentClosePolicy?: WorkflowParentClosePolicy | null;
+    readonly onParentClose?: (input: {
+        readonly workflowName: string;
+        readonly executionId: string;
+        readonly runId?: string;
+        readonly status: WorkflowParentCloseStatus;
+    }) => Promise<void>;
+    readonly recorder?: WorkflowRunRecorderService;
+    readonly pluginWorkflowStepLayer?: Layer.Layer<any, never, never>;
+}
+
+/** 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 WorkflowMake = typeof workflowModule.make;
+
+export declare interface WorkflowMessagePairSchemas {
+    readonly payload: Schema.Schema.Any;
+    readonly success: Schema.Schema.Any;
+}
+
+export declare interface WorkflowMessagesCarrier<M extends WorkflowMessagesMetadata = WorkflowMessagesMetadata> {
+    readonly [WorkflowMessagesProperty]: M;
+}
+
+export declare interface WorkflowMessageSchemas {
+    readonly signals?: Readonly<Record<string, Schema.Schema.Any>>;
+    readonly updates?: Readonly<Record<string, WorkflowMessagePairSchemas>>;
+    readonly queries?: Readonly<Record<string, WorkflowMessagePairSchemas>>;
+}
+
+export declare interface WorkflowMessagesMetadata {
+    readonly signals: Readonly<Record<string, Schema.Schema.Any>>;
+    readonly updates: Readonly<Record<string, WorkflowMessagePairSchemas>>;
+    readonly queries: Readonly<Record<string, WorkflowMessagePairSchemas>>;
+}
+
+export declare const WorkflowMessagesProperty = "__voltroWorkflowMessages";
+
+export declare interface WorkflowMessageStore {
+    readonly query: (input: QueryDescriptor) => Promise<ReadonlyArray<unknown>>;
+}
+
+export declare interface WorkflowMessageTarget {
+    readonly id?: string;
+    readonly executionId?: string;
+    /** Workflow name (the `_voltro_workflow_runs.tag` column). Lets a caller
+     *  that already holds it (e.g. from a `WorkflowRunHandle`) skip the store
+     *  lookup when completing a suspending signal — see
+     *  `completeSuspendingSignal`. */
+    readonly workflowName?: string;
+}
+
+export { workflowModule }
+
+declare type WorkflowOptions = Parameters<WorkflowMake>[0] & WorkflowVersionOptions & {
+    readonly messages?: WorkflowMessageSchemas;
+};
+
+export declare interface WorkflowParentCloseDecision {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly executionId: string;
+    readonly policy: WorkflowParentClosePolicy | null;
+    readonly action: 'cancelled' | 'abandoned' | 'skipped' | 'failed';
+    readonly reason?: string;
+}
+
+export declare interface WorkflowParentCloseEmitter {
+    emit(channel: 'workflowRuns' | 'workflowSteps' | 'workflowEvents', event: {
+        readonly op: 'insert' | 'update';
+        readonly row: Record<string, unknown>;
+    }): void;
+}
+
+export declare interface WorkflowParentCloseLogger {
+    warn(message: string, fields?: Record<string, unknown>): void;
+}
+
+export declare type WorkflowParentCloseStatus = 'succeeded' | 'failed' | 'cancelled';
+
+export declare interface WorkflowParentCloseStore {
+    query(descriptor: QueryDescriptor): Promise<ReadonlyArray<unknown>>;
+    update(table: string, id: string, patch: unknown): Promise<unknown | null>;
+}
+
+export declare interface WorkflowRecordingEmitter {
+    emit(channel: 'workflowRuns' | 'workflowSteps' | 'workflowEvents', event: {
+        readonly op: 'insert' | 'update';
+        readonly row: Record<string, unknown>;
+    }): void;
+}
+
+export declare interface WorkflowRecordingLogger {
+    warn(message: string, fields?: Record<string, unknown>): void;
+}
+
+export declare interface WorkflowRecordingStore {
+    insert(table: string, row: unknown): Promise<unknown>;
+    update(table: string, id: string, patch: unknown): Promise<unknown | null>;
+    query?(descriptor: unknown): Promise<ReadonlyArray<unknown>>;
+}
+
+export declare interface WorkflowResolvedRun {
+    readonly id: string;
+    readonly executionId?: string;
+    /** Denormalised workflow name (`_voltro_workflow_runs.tag`). Present because
+     *  the resolve query projects all columns; used to key a suspending signal's
+     *  `DurableDeferred` by workflow name + signal name. */
+    readonly tag?: string;
+}
+
+/**
+ * Closed enumeration of event types the framework knows how to emit.
+ * Kept here (not in `runEventsTable.ts`) so callers in the recorder
+ * + dev.ts share a single source of truth. The TABLE column is
+ * open-text on purpose (future phases add new types without a column
+ * migration) — but at emit time we still want type-safety.
+ */
+export declare type WorkflowRunEventType = 'run-started' | 'run-suspended' | 'run-resumed' | 'run-cancelled' | 'run-succeeded' | 'run-failed'
+/** Emitted when `sleep({ name, duration })` enters the wait — `payload`
+*  carries `{ name, durationMs, scheduledWakeAt }`. The dashboard
+*  Gantt renders these as a hatched bar in the timeline so a
+*  workflow waiting on a cron-style delay isn't shown as silently
+*  hung. */
+| 'timer-set'
+/** Emitted when the sleep wakes — `payload` carries `{ name,
+*  actualDurationMs }`. Pairs with the matching `timer-set` on the
+*  same `name`. */
+| 'timer-fired'
+/** Emitted by `awaitSignal({ name, schema })` when the
+*  workflow enters the wait. `payload` carries `{ signalName }`. The
+*  dashboard surfaces the awaited signal in the run header + adds a
+*  "Send signal" CTA targeting this name. */
+| 'signal-awaited'
+/** Emitted by the inspect bus when an external caller
+*  sends a signal via `POST /_voltro/inspect/workflows/runs/:id/signal`.
+*  `payload` carries `{ signalName, value }`. The polling
+*  `awaitSignal` activity picks the event up on its next tick. */
+| 'signal-sent'
+/** Emitted by `awaitSignal` after a matching
+*  `signal-sent` is observed and parsed. `payload` carries
+*  `{ signalName, value }`. Pairs visually with `signal-awaited` for
+*  the same signalName so timelines render a complete handshake. */
+| 'signal-received'
+/** Emitted when an external caller sends a synchronous workflow
+*  update. `payload` carries `{ updateId, updateName, value }`.
+*  The matching `awaitUpdate(...)` activity picks it up, validates
+*  it, and records a terminal update event. */
+| 'update-requested'
+/** Emitted by `awaitUpdate(...)` once the workflow has claimed an
+*  update request. Useful in dashboards to distinguish "queued for
+*  workflow" from "currently being handled". */
+| 'update-received'
+/** Emitted by `awaitUpdate(...)` after the handler returns.
+*  `payload` carries `{ updateId, updateName, result }`; the
+*  caller's `ctx.workflows.update(...)` waits for this event. */
+| 'update-completed'
+/** Emitted by `awaitUpdate(...)` when schema validation or the
+*  update handler fails. `payload` carries `{ updateId, updateName,
+*  errorTag, errorMessage }`; the caller's update promise rejects. */
+| 'update-failed';
+
+export declare class WorkflowRunRecorder extends WorkflowRunRecorder_base {
+}
+
+declare const WorkflowRunRecorder_base: Context.TagClass<WorkflowRunRecorder, "@voltro/WorkflowRunRecorder", WorkflowRunRecorderService>;
+
+export declare interface WorkflowRunRecorderOptions {
+    readonly store: WorkflowRecordingStore;
+    readonly emit?: WorkflowRecordingEmitter['emit'];
+    readonly log?: WorkflowRecordingLogger;
+    readonly truncateBytes?: number;
+    readonly makeId?: (prefix: 'wr' | 'ws' | 'wfev') => string;
+    /** Dormancy wakeup producer — present only in sleep mode. Absent →
+     *  zero overhead (always-on default). */
+    readonly wakeups?: WorkflowWakeupHook;
+}
+
+/** Per-step lifecycle hooks. Implementations should not throw —
+ *  recorder failures must NOT break workflow execution.
+ *
+ *  Two responsibilities: write rows to the steps table AND emit
+ *  inspect-stream events so cross-process consumers (cloud-api's
+ *  per-app SSE bridge → cache mirror → dashboard subscriptions) see
+ *  state transitions in real time. */
+export declare interface WorkflowRunRecorderService {
+    /** Called before a step body runs. Returns an id the caller passes
+     *  back to `endStep`. Implementations may return undefined to
+     *  signal "not recording this step" (e.g. no current run id, or
+     *  the runs table isn't available yet); callers should treat that
+     *  as "no recording happened" and not call `endStep`. */
+    readonly startStep: (input: {
+        readonly runId: string;
+        readonly stepName: string;
+        readonly attempt: number;
+        /** User-declared structured input recorded into
+         *  `_voltro_workflow_run_steps.input`. The recorder truncates large
+         *  payloads — pass whatever the step needs to make sense in
+         *  isolation, not the full universe. */
+        readonly stepInput?: unknown;
+        /** Declarative retry-policy summary recorded into
+         *  `_voltro_workflow_run_steps.retryPolicy`. Pure metadata — the
+         *  framework doesn't apply this; the user is still responsible for
+         *  using `Effect.retry` or `Activity.interruptRetryPolicy` to
+         *  implement the actual retry behavior. The dashboard renders the
+         *  policy alongside the attempt counter so operators can see
+         *  "attempt 2 of 5, exponential 1s base" at a glance. */
+        readonly retryPolicy?: StepRetryPolicy;
+    }) => Promise<string | undefined>;
+    readonly endStepSuccess: (input: {
+        readonly stepRecordId: string;
+        readonly output: unknown;
+        readonly durationMs: number;
+    }) => Promise<void>;
+    readonly endStepFailure: (input: {
+        readonly stepRecordId: string;
+        readonly errorTag: string | null;
+        readonly errorMessage: string;
+        /** Structured Cause record — pretty form +
+         *  typed failures + defects. The dashboard renders the pretty
+         *  string as a stack-trace panel in the expanded step view, so
+         *  ops can see "where in user code" the throw originated. */
+        readonly errorCause?: {
+            readonly pretty: string;
+            readonly failures: ReadonlyArray<unknown>;
+            readonly defects: ReadonlyArray<unknown>;
+        };
+        readonly durationMs: number;
+    }) => Promise<void>;
+    /**
+     * Record a run-scoped lifecycle event into
+     * `_voltro_workflow_run_events`. Used for transitions that don't
+     * have a row representation in the runs or steps tables:
+     * suspend / resume / cancel, and (in later phases) timer fires +
+     * signal receipts + child spawns. Implementations should NOT throw —
+     * recorder failures must NOT break workflow execution.
+     */
+    readonly recordEvent: (input: {
+        readonly runId: string;
+        readonly eventType: WorkflowRunEventType;
+        readonly payload?: Record<string, unknown> | null;
+        readonly stepName?: string | null;
+        readonly attempt?: number | null;
+    }) => Promise<{
+        readonly id: string;
+    }>;
+}
+
+/**
+ * Per-step plugin interceptor. Plugins can wrap every `step()`
+ * (== `Activity.make`) invocation with observability, suppress /
+ * substitute behaviour, or retry-policy overrides. Composed across
+ * plugins by the CLI (`composePluginWorkflowStep`).
+ *
+ * Receives the user's `execute` Effect + a `WorkflowStepContext`
+ * carrying `{ runId, stepName, attempt }`. Returns a wrapped Effect.
+ * A FAIL inside the interceptor abort the step the same way a fail
+ * in the user effect would — including triggering @effect/workflow's
+ * retry policy.
+ */
+export declare interface WorkflowStepContext {
+    /** Run id from `_voltro_workflow_runs` (or 'unrecorded'). */
+    readonly runId: string;
+    /** Step name (== `Activity.make({ name })`). */
+    readonly stepName: string;
+    /** Attempt number (1 on first try, 2+ on retry). */
+    readonly attempt: number;
+}
+
+export declare type WorkflowStepInterceptor = <Success, ErrorE, R>(next: Effect.Effect<Success, ErrorE, R>, ctx: WorkflowStepContext) => Effect.Effect<Success, ErrorE, R>;
+
+export declare interface WorkflowStepInterceptorService {
+    readonly interceptor: WorkflowStepInterceptor;
+}
+
+/**
+ * Optional service Tag carrying the composed per-step interceptor
+ * chain. When absent (no plugin contributes `onWorkflowStep`) the
+ * step wrapper takes the zero-overhead unchanged path.
+ */
+export declare class WorkflowStepInterceptorTag extends WorkflowStepInterceptorTag_base {
+}
+
+declare const WorkflowStepInterceptorTag_base: Context.TagClass<WorkflowStepInterceptorTag, "@voltro/WorkflowStepInterceptor", WorkflowStepInterceptorService>;
+
+export declare interface WorkflowUpdateResult {
+    readonly eventId: string;
+    readonly updateId: string;
+    readonly completedEventId: string;
+    readonly result: unknown;
+}
+
+export declare interface WorkflowUpdateSendOptions {
+    readonly timeoutMs?: number;
+    readonly pollIntervalMs?: number;
+}
+
+export declare interface WorkflowVersionMetadata {
+    readonly version: string;
+    readonly compatibleWith: ReadonlyArray<string>;
+    readonly patches: ReadonlyArray<string>;
+}
+
+export declare interface WorkflowVersionOptions {
+    readonly version?: string | number;
+    readonly compatibleWith?: ReadonlyArray<string | number>;
+    readonly patches?: ReadonlyArray<string>;
+}
+
+export declare const WorkflowVersionTypeId: unique symbol;
+
+/**
+ * Dormancy producer (plan 50 — scale-to-zero). Injected by the CLI ONLY
+ * in `dormancy: 'sleep'` mode so the workflow package stays free of a
+ * `@voltro/runtime` dependency (it has none). The recorder mirrors a
+ * durable-clock wait into the wakeup registry: `register` on `timer-set`,
+ * `cancel` when the wait ends or the run reaches a terminal state. The
+ * external waker reads those rows to resume a scaled-to-zero runner.
+ *
+ * This NEVER touches `DurableClock.sleep` or the cluster journal — it is
+ * additive bookkeeping next to the existing best-effort event write, so
+ * the durable-resume path is unaffected. Implementations must not throw.
+ */
+export declare interface WorkflowWakeupHook {
+    /** `tenantId` is the wake-routing target carried from the workflow's
+     *  caller subject (plan 50). Absent → the CLI hook falls back to the
+     *  deployment's configured tenant (correct for single-tenant). */
+    readonly register: (runId: string, wakeAt: Date, tenantId?: string) => Promise<void>;
+    /** `tenantId` is carried on the `timer-fired` event (the normal cancel
+     *  path) so the cancel targets the same row `register` created. Absent
+     *  on terminal-event cancels → the CLI hook falls back to the
+     *  deployment tenant (consistent with register for single-tenant). */
+    readonly cancel: (runId: string, tenantId?: string) => Promise<void>;
+}
+
+export declare interface WorkflowWorkerLayerBrand {
+    readonly [WorkflowWorkerLayerTypeId]: true;
+}
+
+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>;
+
+export { }