@ai-digital-factory/state-flow-runtime 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,739 @@
+import { z } from 'zod';
+
+/** Base class for durable runtime rejections (infrastructure, defects, invalid input). */
+declare class DurableRuntimeError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Another runtime already owns the database (ADR 0047). */
+declare class DurableOwnershipError extends DurableRuntimeError {
+}
+/** The runtime is closing or closed and admits no new work (ADR 0061). */
+declare class DurableRuntimeClosedError extends DurableRuntimeError {
+}
+/**
+ * `close({ timeoutMs })` elapsed while callbacks were still running. The runtime keeps the
+ * database lock; exit the process to release it (ADR 0075).
+ */
+declare class DurableShutdownTimeoutError extends DurableRuntimeError {
+}
+/** A compiled module failed startup validation before any handler ran (ADR 0046). */
+declare class DurableDefinitionError extends DurableRuntimeError {
+    readonly problems: readonly string[];
+    constructor(chartName: string, problems: readonly string[]);
+}
+/** Input that cannot become trusted durable data (IDs, payloads, transitions). */
+declare class DurableInputError extends DurableRuntimeError {
+}
+/** The database was written by a newer State Flow schema. */
+declare class DurableSchemaError extends DurableRuntimeError {
+}
+/** A non-applied dispatch outcome routed to the application's shared failure handler. */
+declare class DurableDispatchError extends DurableRuntimeError {
+    readonly outcome: Exclude<DispatchOutcome, "applied">;
+    readonly instanceId: InstanceId;
+    readonly context: unknown;
+    readonly phase: "dispatch";
+    constructor(outcome: Exclude<DispatchOutcome, "applied">, instanceId: InstanceId, context: unknown);
+}
+/** Runtime operation failures retain the original exception as cause. */
+declare class DurableOperationError extends DurableRuntimeError {
+    readonly phase: "create-flow" | "ensure-instance" | "dispatch";
+    readonly outcome: "error";
+    constructor(phase: "create-flow" | "ensure-instance" | "dispatch", cause: unknown);
+}
+/** Stored instances remain untouched when their definition or handler revision is incompatible. */
+declare class DurableDefinitionMismatchError extends DurableRuntimeError {
+    readonly context: DefinitionMismatchContext;
+    readonly phase: "ensure-instance";
+    readonly outcome: "definition-mismatch";
+    constructor(context: DefinitionMismatchContext);
+}
+
+/** Shared runtime contract for manual actions, also used by companion transports. */
+declare const resolveInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"retry">;
+    operationId: z.ZodPipe<z.ZodString, z.ZodTransform<OperationId, string>>;
+    expectedAttempts: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"terminate">;
+    operationId: z.ZodPipe<z.ZodString, z.ZodTransform<OperationId, string>>;
+    expectedAttempts: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    action: z.ZodLiteral<"confirm-completed">;
+    callback: z.ZodLiteral<"guard">;
+    result: z.ZodBoolean;
+    operationId: z.ZodPipe<z.ZodString, z.ZodTransform<OperationId, string>>;
+    expectedAttempts: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"confirm-completed">;
+    callback: z.ZodLiteral<"resolve-start-state">;
+    result: z.ZodString;
+    operationId: z.ZodPipe<z.ZodString, z.ZodTransform<OperationId, string>>;
+    expectedAttempts: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodPipe<z.ZodObject<{
+    action: z.ZodLiteral<"confirm-completed">;
+    callback: z.ZodEnum<{
+        "on-enter": "on-enter";
+        "on-exit": "on-exit";
+        "on-transition": "on-transition";
+    }>;
+    result: z.ZodOptional<z.ZodNull>;
+    operationId: z.ZodPipe<z.ZodString, z.ZodTransform<OperationId, string>>;
+    expectedAttempts: z.ZodNumber;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodTransform<{
+    action: "confirm-completed";
+    callback: "on-enter" | "on-exit" | "on-transition";
+    operationId: OperationId;
+    expectedAttempts: number;
+    reason: string;
+}, {
+    action: "confirm-completed";
+    callback: "on-enter" | "on-exit" | "on-transition";
+    operationId: OperationId;
+    expectedAttempts: number;
+    reason: string;
+    result?: null | undefined;
+}>>], "callback">], "action">;
+type ParsedResolveInput = z.output<typeof resolveInputSchema>;
+/** Parses untrusted input; graph membership and stale-target validation follow at execution. */
+declare function parseResolveInput(value: unknown): ResolveInput<string>;
+
+/**
+ * Public types for the durable runtime (ADRs 0046–0075).
+ *
+ * Handler authors use the callback types (`DurableGuard`, `DurableTransitionCallback`, …).
+ * Services use the outcome-handler, snapshot, and resolve types through `DurableRuntime`.
+ */
+declare const durableIdKind: unique symbol;
+type DurableId<Kind extends string> = string & {
+    readonly [durableIdKind]: Kind;
+};
+/** Application-supplied flow instance identity. Build with `instanceId(...)`. */
+type InstanceId = DurableId<"instance">;
+/** Application-supplied dispatch request identity. Build with `requestId(...)`. */
+type RequestId = DurableId<"request">;
+/** State Flow-generated logical callback operation identity, stable across attempts. */
+type OperationId = DurableId<"operation">;
+/** State Flow-generated identity of one execution or recovery attempt. */
+type AttemptId = DurableId<"attempt">;
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * Maps `T` to its JSON-compatible shape. Members that cannot be persisted
+ * (functions, symbols, bigint, `undefined`, class instances with methods)
+ * become `never`, so `T` is only assignable to the result when it is JSON-compatible.
+ */
+type JsonCompatible<T> = T extends JsonPrimitive ? T : T extends (...args: never[]) => unknown ? never : T extends bigint | symbol | undefined ? never : T extends readonly (infer Item)[] ? readonly JsonCompatible<Item>[] : T extends object ? {
+    [K in keyof T]: JsonCompatible<T[K]>;
+} : never;
+type IsJsonCompatible<T> = [unknown] extends [T] ? false : [T] extends [JsonCompatible<T>] ? true : false;
+/** Transition names whose payload types are not JSON-compatible. */
+type NonJsonPayloadTransitions<Payloads> = {
+    [T in keyof Payloads]: IsJsonCompatible<Payloads[T]> extends true ? never : T;
+}[keyof Payloads];
+type RecoveryStrategy = "safe-replay" | "reconcile" | "manual";
+type DurableOperationInfo = {
+    readonly operationId: OperationId;
+    readonly attemptId: AttemptId;
+    /** 1 for the first run; increases with each run or reconciliation attempt. */
+    readonly attempt: number;
+};
+/** Fields State Flow adds to every durable callback context. */
+type DurableExecutionContext = {
+    readonly instanceId: InstanceId;
+    readonly operation: DurableOperationInfo;
+    /** Cooperative cancellation, for example during runtime close (ADR 0068). */
+    readonly signal: AbortSignal;
+};
+type DurableContext<Context> = Context & DurableExecutionContext;
+type RecoveryCause = "failed" | "interrupted";
+type ReconcileContext<Context> = DurableContext<Context> & {
+    readonly recovery: {
+        /** `interrupted` when the process stopped while `run` was in flight. */
+        readonly cause: RecoveryCause;
+        readonly lastError: string | null;
+    };
+};
+/** `completed` carries the callback's result, except for callbacks that return nothing. */
+type CompletedDecision<Result> = [Result] extends [void] ? {
+    readonly decision: "completed";
+    readonly result?: never;
+} : {
+    readonly decision: "completed";
+    readonly result: Result;
+};
+/** Explicit reconciliation decisions (ADR 0064). */
+type ReconcileDecision<Result> = CompletedDecision<Result> | {
+    readonly decision: "safe-to-retry";
+} | {
+    readonly decision: "pending";
+} | {
+    readonly decision: "needs-attention";
+    readonly reason: string;
+};
+/** Discriminated recovery declaration: only `reconcile` carries a reconcile function. */
+type RecoveryDeclaration<Context, Args extends readonly unknown[], Result> = {
+    readonly strategy: "safe-replay";
+    readonly reconcile?: never;
+} | {
+    readonly strategy: "manual";
+    readonly reconcile?: never;
+} | {
+    readonly strategy: "reconcile";
+    readonly reconcile: (context: ReconcileContext<Context>, ...args: Args) => ReconcileDecision<Result> | Promise<ReconcileDecision<Result>>;
+};
+/** One implemented callback: its execution and its recovery declared together. */
+type DurableCallback<Context, Args extends readonly unknown[], Result> = {
+    readonly run: (context: DurableContext<Context>, ...args: Args) => Result | Promise<Result>;
+    readonly recovery: RecoveryDeclaration<Context, Args, Result>;
+};
+/** `onEnter` / `onExit` in a durable state handler. */
+type DurableStateCallback<Context> = DurableCallback<Context, [], void>;
+/** `guard` in a durable transition handler. */
+type DurableGuard<Context, Payload> = DurableCallback<Context, [
+    payload: Payload
+], boolean>;
+/** `onTransition` in a durable transition handler. */
+type DurableTransitionCallback<Context, Payload> = DurableCallback<Context, [
+    payload: Payload
+], void>;
+/** `resolveStartState` in a durable creation handler. Return the initial state for ordinary creation. */
+type DurableStartStateResolver<Context, StateName extends string> = DurableCallback<Context, [], StateName>;
+/**
+ * `onEnter` receives the incoming transition (or `"default"` at creation); `onExit` receives the
+ * outgoing transition, so the two callbacks have different context types.
+ */
+type DurableStateHooks<EntryContext, ExitContext> = {
+    readonly onEnter?: DurableStateCallback<EntryContext>;
+    readonly onExit?: DurableStateCallback<ExitContext>;
+};
+type DurableTransitionHooks<Context, Payload> = {
+    readonly guard?: DurableGuard<Context, Payload>;
+    readonly onTransition?: DurableTransitionCallback<Context, Payload>;
+};
+type DurableCreationHooks<Context, StateName extends string> = {
+    readonly resolveStartState?: DurableStartStateResolver<Context, StateName>;
+};
+type EndpointMapFor<StateName extends string> = Record<string, {
+    fromState: StateName;
+    toState: StateName;
+}>;
+type DurableHookTable = {
+    readonly states: Readonly<Record<string, DurableStateHooks<any, any> | null>>;
+    readonly transitions: Readonly<Record<string, DurableTransitionHooks<any, any> | null>>;
+    readonly creation: DurableCreationHooks<any, string> | null;
+};
+type DurableCompiledFlowModule<StateName extends string, TransitionPayloads extends Record<string, unknown>, FlowConfig, EndpointMap extends EndpointMapFor<StateName>, Hooks extends DurableHookTable> = {
+    readonly execution: "durable";
+    readonly chartName: string;
+    readonly initialStateId: string;
+    readonly states: ReadonlyArray<{
+        readonly id: string;
+        readonly name: StateName;
+    }>;
+    readonly transitions: ReadonlyArray<{
+        readonly fromId: string;
+        readonly fromName: StateName;
+        readonly toId: string;
+        readonly toName: StateName;
+        readonly name: Extract<keyof TransitionPayloads, string>;
+        readonly description: string;
+    }>;
+    readonly transitionEndpointMap: EndpointMap;
+    /** Runtime payload contracts; generated from each transition module's payloadSchema. */
+    readonly payloadSchemas: {
+        readonly [T in keyof TransitionPayloads]: z.ZodType<TransitionPayloads[T], TransitionPayloads[T]>;
+    };
+    readonly hooks: Hooks;
+    /**
+     * Hash of the chart's handler sources, written by compile. Unresolved work started under a
+     * different revision is not resumed (ADR 0049, 0075). `null` for hand-built modules.
+     */
+    readonly handlerRevision?: string | null;
+    readonly transitionPayloadSamples?: Readonly<Record<string, unknown>>;
+    readonly transitionPayloadTypeLabels?: Readonly<Record<string, string>>;
+    readonly __flowConfigBrand?: FlowConfig;
+    readonly __transitionPayloadsBrand?: TransitionPayloads;
+} & DurablePayloadCheck<TransitionPayloads>;
+/** Rejects a compiled module whose transition payloads are not JSON-compatible. */
+type DurablePayloadCheck<TransitionPayloads> = [
+    NonJsonPayloadTransitions<TransitionPayloads>
+] extends [never] ? unknown : {
+    readonly "State Flow: transition payloads must be JSON-compatible": NonJsonPayloadTransitions<TransitionPayloads>;
+};
+/** States that have at least one outgoing transition. */
+type StatesWithOutgoing<StateName extends string, EndpointMap extends EndpointMapFor<StateName>> = EndpointMap[keyof EndpointMap]["fromState"];
+type OutgoingFrom<EndpointMap extends EndpointMapFor<string>, From extends string> = {
+    [K in keyof EndpointMap]: EndpointMap[K]["fromState"] extends From ? K & string : never;
+}[keyof EndpointMap];
+/** Dispatch input for a scoped dispatcher. Narrowing `transition` narrows `payload`. */
+type DurableDispatchInput<TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<string>, From extends string> = {
+    [T in OutgoingFrom<EndpointMap, From>]: {
+        readonly requestId: RequestId;
+        readonly transition: T;
+        readonly payload: TransitionPayloads[T];
+    };
+}[OutgoingFrom<EndpointMap, From>];
+type CallbackRef<StateName extends string, TransitionName extends string> = {
+    readonly kind: "resolve-start-state";
+} | {
+    readonly kind: "on-enter";
+    readonly state: StateName;
+} | {
+    readonly kind: "on-exit";
+    readonly state: StateName;
+} | {
+    readonly kind: "guard";
+    readonly transition: TransitionName;
+} | {
+    readonly kind: "on-transition";
+    readonly transition: TransitionName;
+};
+type CallbackKind = CallbackRef<string, string>["kind"];
+/** The unresolved callback blocking an instance. */
+type UnresolvedWork<StateName extends string, TransitionName extends string> = {
+    readonly operationId: OperationId;
+    /** `null` while the instance is being created. */
+    readonly requestId: RequestId | null;
+    readonly callback: CallbackRef<StateName, TransitionName>;
+    readonly strategy: RecoveryStrategy;
+    readonly attempts: number;
+    readonly lastError: string | null;
+    /** ISO timestamp of the next automatic attempt, or `null` when none is scheduled. */
+    readonly nextAttemptAt: string | null;
+};
+type ExecutionStatus<StateName extends string, TransitionName extends string> = {
+    readonly kind: "ready";
+} | {
+    readonly kind: "running";
+    readonly requestId: RequestId | null;
+} | {
+    readonly kind: "recovering";
+    readonly work: UnresolvedWork<StateName, TransitionName>;
+} | {
+    readonly kind: "needs-attention";
+    readonly work: UnresolvedWork<StateName, TransitionName>;
+    readonly reason: string;
+} | {
+    readonly kind: "terminated";
+    readonly reason: string;
+};
+type DurableSnapshot<StateName extends string, TransitionName extends string> = {
+    readonly instanceId: InstanceId;
+    readonly chartName: string;
+    /** The committed authored state. Stays visible while post-commit work recovers (ADR 0060). */
+    readonly state: StateName;
+    /** Increases with every committed state or status change. */
+    readonly revision: number;
+    readonly status: ExecutionStatus<StateName, TransitionName>;
+    /**
+     * Set when an infrastructure error (for example a failing disk) stopped this instance's
+     * execution in this process. `status` then shows where it stopped; call `restartRecovery()`
+     * or open the instance again to resume from persisted state (ADR 0076).
+     */
+    readonly stall: {
+        readonly error: string;
+        readonly at: string;
+    } | null;
+};
+type HistoryEventType = "instance-created" | "execution-started" | "callback-started" | "callback-completed" | "callback-failed" | "recovery-scheduled" | "recovery-interrupted" | "state-committed" | "execution-applied" | "execution-blocked" | "needs-attention" | "manual-resolution" | "instance-terminated";
+type HistoryEvent = {
+    readonly sequence: number;
+    readonly at: string;
+    readonly type: HistoryEventType;
+    readonly requestId: RequestId | null;
+    readonly operationId: OperationId | null;
+    readonly attemptId: AttemptId | null;
+    readonly data: JsonValue;
+};
+/** Bounded history query. Pages are in sequence order. */
+type HistoryQuery = {
+    /** Return events after this sequence number (exclusive). Defaults to 0. */
+    readonly afterSequence?: number;
+    /** Defaults to 100; at most 1000. */
+    readonly limit?: number;
+};
+type HistoryPage = {
+    readonly events: readonly HistoryEvent[];
+    /** Pass as `afterSequence` for the next page; `null` when this page is the last. */
+    readonly nextAfterSequence: number | null;
+};
+type ExecutionStatusKind = ExecutionStatus<string, string>["kind"];
+/** One row of an instance listing, read from storage without opening the instance. */
+type InstanceSummary = {
+    readonly instanceId: InstanceId;
+    readonly chartName: string;
+    readonly state: string;
+    readonly status: ExecutionStatusKind;
+    /** Needs-attention or termination reason. */
+    readonly statusReason: string | null;
+    readonly revision: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+};
+type InstanceQuery = {
+    readonly chartName?: string;
+    readonly status?: ExecutionStatusKind | readonly ExecutionStatusKind[];
+    /** Cursor from a previous page's `next`. */
+    readonly after?: string;
+    /** Defaults to 50; at most 500. */
+    readonly limit?: number;
+};
+type InstancePage = {
+    readonly instances: readonly InstanceSummary[];
+    /** Pass as `after` for the next page; `null` when this page is the last. */
+    readonly next: string | null;
+};
+type OutcomeHandler<Context> = (context: Context) => unknown;
+/** Rejects handler keys outside the expected outcome set. */
+type ExactHandlers<Handlers, Expected> = Handlers & {
+    readonly [K in Exclude<keyof Handlers, keyof Expected>]: never;
+};
+type HandlerResult<Handlers> = Awaited<{
+    [K in keyof Handlers]: Handlers[K] extends (...args: never[]) => infer R ? R : never;
+}[keyof Handlers]>;
+/** A rejected or historic payload has not been validated against the current contract. */
+type UnvalidatedDispatchInput<Input> = Input extends unknown ? Omit<Input, "payload"> & {
+    readonly payload: unknown;
+} : never;
+type CompletedDispatchContext<Input, StateName extends string, TransitionName extends string> = {
+    readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+} & ({
+    readonly duplicate: false;
+    readonly input: Input;
+} | {
+    readonly duplicate: true;
+    readonly input: UnvalidatedDispatchInput<Input>;
+});
+type DispatchOutcomeHandlers<StateName extends string, TransitionName extends string, Input, From extends StateName> = {
+    readonly applied: OutcomeHandler<CompletedDispatchContext<Input, StateName, TransitionName>>;
+    readonly "invalid-payload": OutcomeHandler<{
+        readonly input: UnvalidatedDispatchInput<Input>;
+        readonly issues: readonly {
+            readonly path: readonly PropertyKey[];
+            readonly message: string;
+        }[];
+    }>;
+    readonly blocked: OutcomeHandler<CompletedDispatchContext<Input, StateName, TransitionName>>;
+    readonly busy: OutcomeHandler<{
+        readonly input: Input;
+        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+    }>;
+    readonly "recovery-pending": OutcomeHandler<{
+        readonly input: Input;
+        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly work: UnresolvedWork<StateName, TransitionName>;
+    }>;
+    readonly "needs-attention": OutcomeHandler<{
+        readonly input: Input;
+        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly work: UnresolvedWork<StateName, TransitionName>;
+        readonly reason: string;
+    }>;
+    readonly "state-mismatch": OutcomeHandler<{
+        readonly input: Input;
+        readonly expectedState: From;
+        readonly actualState: StateName;
+        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+    }>;
+    readonly "request-conflict": OutcomeHandler<{
+        readonly input: UnvalidatedDispatchInput<Input>;
+        readonly recorded: {
+            readonly fromState: StateName;
+            readonly transition: TransitionName;
+            readonly payload: JsonValue;
+        };
+    }>;
+    readonly terminated: OutcomeHandler<{
+        readonly input: Input;
+        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly reason: string;
+    }>;
+};
+type DispatchOutcome = keyof DispatchOutcomeHandlers<string, string, unknown, string>;
+/** Success information returned by direct awaited dispatch. */
+type AppliedDispatchContext<Input, StateName extends string, TransitionName extends string> = CompletedDispatchContext<Input, StateName, TransitionName>;
+/** A non-applied outcome, with its context correlated to its discriminator. */
+type DispatchFailure<StateName extends string, TransitionName extends string, Input, From extends StateName> = {
+    [Outcome in Exclude<DispatchOutcome, "applied">]: DurableDispatchError & {
+        readonly outcome: Outcome;
+        readonly context: Parameters<DispatchOutcomeHandlers<StateName, TransitionName, Input, From>[Outcome]>[0];
+    };
+}[Exclude<DispatchOutcome, "applied">];
+/** Shared application policy for setup, acquisition and non-applied dispatch outcomes. */
+type FlowFailure<StateName extends string, TransitionName extends string, Input, From extends StateName> = DurableOperationError | DurableDefinitionMismatchError | DispatchFailure<StateName, TransitionName, Input, From>;
+type CreateOutcomeHandlers<Instance, StateName extends string, TransitionName extends string> = {
+    readonly created: OutcomeHandler<{
+        readonly instance: Instance;
+        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+    }>;
+    readonly "already-exists": OutcomeHandler<{
+        readonly instanceId: InstanceId;
+    }>;
+    readonly "recovery-pending": OutcomeHandler<{
+        readonly instance: Instance;
+        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly work: UnresolvedWork<StateName, TransitionName>;
+    }>;
+    readonly "needs-attention": OutcomeHandler<{
+        readonly instance: Instance;
+        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly work: UnresolvedWork<StateName, TransitionName>;
+        readonly reason: string;
+    }>;
+};
+type OpenOutcomeHandlers<Instance, StateName extends string, TransitionName extends string> = {
+    /** Recovery of interrupted work has started (not finished) when this runs (ADR 0050). */
+    readonly opened: OutcomeHandler<{
+        readonly instance: Instance;
+        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+    }>;
+    readonly "not-found": OutcomeHandler<{
+        readonly instanceId: InstanceId;
+    }>;
+    readonly "definition-mismatch": OutcomeHandler<{
+        /** The chart graph or recovery declarations changed. */
+        readonly reason: "definition";
+        readonly instanceId: InstanceId;
+        readonly message: string;
+        readonly storedChartName: string;
+        readonly storedDefinitionId: string;
+        readonly currentDefinitionId: string;
+    } | {
+        /** Handler code changed while this instance had unresolved work. */
+        readonly reason: "handler-revision";
+        readonly instanceId: InstanceId;
+        readonly message: string;
+        readonly storedHandlerRevision: string | null;
+        readonly currentHandlerRevision: string | null;
+    }>;
+};
+type DefinitionMismatchContext = Parameters<OpenOutcomeHandlers<unknown, string, string>["definition-mismatch"]>[0];
+/** Acquisition does not imply readiness; dispatch maps execution statuses exhaustively. */
+type EnsureOutcomeHandlers = {
+    /** Must throw/reject or transfer control; an incompatible instance cannot be returned. */
+    readonly "definition-mismatch": (mismatch: Parameters<OpenOutcomeHandlers<unknown, string, string>["definition-mismatch"]>[0]) => never | Promise<never>;
+};
+type ResolveInput<StateName extends string> = Exclude<ParsedResolveInput, {
+    callback: "resolve-start-state";
+}> | (Omit<Extract<ParsedResolveInput, {
+    callback: "resolve-start-state";
+}>, "result"> & {
+    readonly result: StateName;
+});
+type ResolveRejection = 
+/** Inspector only: no registered flow can load this instance (unknown chart or definition mismatch). */
+"unavailable"
+/**
+ * The operation is not the instance's current unresolved work awaiting attention, or it has
+ * had attempts since `expectedAttempts`.
+ */
+ | "stale"
+/** `callback` does not match the unresolved callback. */
+ | "callback-mismatch"
+/** `result` does not satisfy the callback's result contract. */
+ | "invalid-result";
+type ResolveResult<StateName extends string, TransitionName extends string> = {
+    readonly outcome: "accepted";
+    readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+} | {
+    readonly outcome: "rejected";
+    readonly reason: ResolveRejection;
+    readonly message: string;
+};
+/** Application mapping for each manual-resolution outcome. */
+type ResolveOutcomeHandlers<StateName extends string, TransitionName extends string> = {
+    readonly accepted: (context: Extract<ResolveResult<StateName, TransitionName>, {
+        outcome: "accepted";
+    }>) => unknown;
+    readonly rejected: (context: Extract<ResolveResult<StateName, TransitionName>, {
+        outcome: "rejected";
+    }>) => unknown;
+};
+type RestartOutcomeHandlers = {
+    readonly restarted: () => unknown;
+    readonly "not-restarted": () => unknown;
+};
+
+type DurableRuntimeOptions = {
+    /** Persistent SQLite file owned by State Flow, or `":memory:"` for disposable runs. */
+    readonly databasePath: string;
+    /** Receives subscriber failures, which never affect execution (ADR 0059). Defaults to console.error. */
+    readonly onObserverError?: (error: unknown) => void;
+    /**
+     * Receives infrastructure errors from background recovery, which has no caller to reject.
+     * The affected instance resumes recovery when it is opened again. Defaults to console.error.
+     */
+    readonly onRecoveryError?: (error: unknown) => void;
+};
+type DurableRuntime = {
+    /** Prepare flow registration; no definition validation or registration happens until run(). */
+    createFlow<StateName extends string, TransitionPayloads extends Record<string, unknown>, FlowConfig, EndpointMap extends EndpointMapFor<StateName>, Hooks extends DurableHookTable>(compiled: DurableCompiledFlowModule<StateName, TransitionPayloads, FlowConfig, EndpointMap, Hooks> & DurablePayloadCheck<TransitionPayloads>, config: FlowConfig): CreateFlowBuilder<StateName, TransitionPayloads, EndpointMap>;
+    /**
+     * Registers a durable compiled module with its dependencies. Validates every handler's
+     * recovery declaration before any handler runs (ADR 0046).
+     */
+    flow<StateName extends string, TransitionPayloads extends Record<string, unknown>, FlowConfig, EndpointMap extends EndpointMapFor<StateName>, Hooks extends DurableHookTable>(compiled: DurableCompiledFlowModule<StateName, TransitionPayloads, FlowConfig, EndpointMap, Hooks> & DurablePayloadCheck<TransitionPayloads>, config: FlowConfig): DurableFlow<StateName, TransitionPayloads, EndpointMap>;
+    /**
+     * Stops admission and recovery scheduling, aborts handler signals, lets active work checkpoint,
+     * and releases the database (ADR 0061). With `timeoutMs`, rejects with
+     * `DurableShutdownTimeoutError` if callbacks are still running; the lock is kept until they
+     * settle or the process exits.
+     */
+    close(options?: {
+        readonly timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Cross-instance access for operator tools such as the companion UI: listing, snapshots and
+     * history straight from storage, runtime-wide subscriptions, and manual resolution. The
+     * application authorizes every resolve call it forwards (ADR 0062, 0063).
+     */
+    readonly inspector: DurableInspector;
+    /** Explicit operator capability; pass inspector alone to read-only tools. */
+    readonly controls: DurableControls;
+};
+type DurableInspector = {
+    listInstances(query?: InstanceQuery): InstancePage;
+    /** `null` when no instance has this ID. */
+    getSnapshot(instanceId: InstanceId): DurableSnapshot<string, string> | null;
+    history(instanceId: InstanceId, query?: HistoryQuery): HistoryPage;
+    /** Snapshots of every instance this runtime executes, after each change. */
+    subscribe(listener: (snapshot: DurableSnapshot<string, string>) => unknown): () => void;
+};
+type DurableControls = {
+    /**
+     * Resolves unresolved work using the flow registered for the instance's chart, opening the
+     * instance if needed. When no registered flow can load it (unknown chart, definition or
+     * handler-revision mismatch), only `terminate` is accepted, and it runs no handler; other
+     * actions return `unavailable`.
+     */
+    resolve(instanceId: InstanceId, input: ResolveInput<string>): Promise<ResolveResult<string, string>>;
+    /** Restarts recovery of a stalled instance this runtime has loaded. False if nothing to restart. */
+    restartRecovery(instanceId: InstanceId): boolean;
+};
+type TransitionNameOf<TransitionPayloads> = Extract<keyof TransitionPayloads, string>;
+type CreateFlowBuilder<StateName extends string, TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<StateName>> = {
+    handleFailure(onFailure: (failure: FlowFailure<StateName, TransitionNameOf<TransitionPayloads>, DurableDispatchInput<TransitionPayloads, EndpointMap, StatesWithOutgoing<StateName, EndpointMap>>, StatesWithOutgoing<StateName, EndpointMap>>) => never | Promise<never>): {
+        run(): Promise<DurableFlow<StateName, TransitionPayloads, EndpointMap, true, true>>;
+    };
+};
+type EnsureInstanceBuilder<StateName extends string, TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<StateName>> = {
+    run(): Promise<DurableInstance<StateName, TransitionPayloads, EndpointMap, true>>;
+    handleEnsureInstance<Handlers extends EnsureOutcomeHandlers>(handlers: ExactHandlers<Handlers, EnsureOutcomeHandlers>): {
+        run(): Promise<DurableInstance<StateName, TransitionPayloads, EndpointMap, true>>;
+    };
+};
+type DurableFlow<StateName extends string, TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<StateName>, HasDispatchPolicy extends boolean = false, HasFlowFailurePolicy extends boolean = false> = {
+    readonly chartName: string;
+    readonly definitionId: string;
+    /** Prepare acquisition using the inherited failure policy. */
+    ensureInstance: HasFlowFailurePolicy extends true ? (input: {
+        readonly instanceId: InstanceId;
+    }) => EnsureInstanceBuilder<StateName, TransitionPayloads, EndpointMap> : never;
+    /** Configure one shared handler for every non-applied direct dispatch outcome. */
+    handleDispatch: HasDispatchPolicy extends true ? never : (onFailure: (failure: DispatchFailure<StateName, TransitionNameOf<TransitionPayloads>, DurableDispatchInput<TransitionPayloads, EndpointMap, StatesWithOutgoing<StateName, EndpointMap>>, StatesWithOutgoing<StateName, EndpointMap>>) => never | Promise<never>) => DurableFlow<StateName, TransitionPayloads, EndpointMap, true, HasFlowFailurePolicy>;
+    /** Opens an existing instance or creates it once, starting recovery when needed. */
+    handleEnsure<Handlers extends EnsureOutcomeHandlers>(handlers: ExactHandlers<Handlers, EnsureOutcomeHandlers>): {
+        ensure(input: {
+            readonly instanceId: InstanceId;
+        }): Promise<DurableInstance<StateName, TransitionPayloads, EndpointMap, HasDispatchPolicy>>;
+    };
+    /** Prepares reusable instance creation with every creation outcome handled (ADR 0067). */
+    handleCreate<Handlers extends CreateOutcomeHandlers<DurableInstance<StateName, TransitionPayloads, EndpointMap, HasDispatchPolicy>, StateName, TransitionNameOf<TransitionPayloads>>>(handlers: ExactHandlers<Handlers, CreateOutcomeHandlers<unknown, StateName, TransitionNameOf<TransitionPayloads>>>): {
+        create(input: {
+            readonly instanceId: InstanceId;
+            /** Skip `resolveStartState` and start (or restore) at this state. */
+            readonly startState?: StateName;
+        }): Promise<HandlerResult<Handlers>>;
+    };
+    /** Prepares reusable instance opening with every opening outcome handled (ADR 0067). */
+    handleOpen<Handlers extends OpenOutcomeHandlers<DurableInstance<StateName, TransitionPayloads, EndpointMap, HasDispatchPolicy>, StateName, TransitionNameOf<TransitionPayloads>>>(handlers: ExactHandlers<Handlers, OpenOutcomeHandlers<unknown, StateName, TransitionNameOf<TransitionPayloads>>>): {
+        open(instanceId: InstanceId): Promise<HandlerResult<Handlers>>;
+    };
+};
+type DurableInstance<StateName extends string, TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<StateName>, HasDispatchPolicy extends boolean = false> = {
+    readonly instanceId: InstanceId;
+    getSnapshot(): DurableSnapshot<StateName, TransitionNameOf<TransitionPayloads>>;
+    /** Called after every committed state or status change. Returns an unsubscribe function. */
+    subscribe(listener: (snapshot: DurableSnapshot<StateName, TransitionNameOf<TransitionPayloads>>) => unknown): () => void;
+    /** One page of this instance's execution history (ADR 0072). */
+    history(query?: HistoryQuery): HistoryPage;
+    /** Direct dispatch requires a shared flow failure policy; `handle` supports explicit local mapping. */
+    when<From extends StatesWithOutgoing<StateName, EndpointMap>>(state: From): (HasDispatchPolicy extends true ? {
+        dispatch(input: DurableDispatchInput<TransitionPayloads, EndpointMap, From>): Promise<AppliedDispatchContext<DurableDispatchInput<TransitionPayloads, EndpointMap, From>, StateName, TransitionNameOf<TransitionPayloads>>>;
+    } : Record<never, never>) & {
+        handle<Handlers extends DispatchOutcomeHandlers<StateName, TransitionNameOf<TransitionPayloads>, DurableDispatchInput<TransitionPayloads, EndpointMap, From>, From>>(handlers: ExactHandlers<Handlers, DispatchOutcomeHandlers<StateName, string, unknown, From>>): {
+            dispatch(input: DurableDispatchInput<TransitionPayloads, EndpointMap, From>): Promise<HandlerResult<Handlers>>;
+        };
+    };
+    /** Exhaustive outcome mapping for manual actions; raw resolve remains the operator primitive. */
+    handleResolve<Handlers extends ResolveOutcomeHandlers<StateName, TransitionNameOf<TransitionPayloads>>>(handlers: ExactHandlers<Handlers, ResolveOutcomeHandlers<StateName, TransitionNameOf<TransitionPayloads>>>): {
+        resolve(input: ResolveInput<StateName>): Promise<HandlerResult<Handlers>>;
+    };
+    handleRestart<Handlers extends RestartOutcomeHandlers>(handlers: ExactHandlers<Handlers, RestartOutcomeHandlers>): {
+        restart(): HandlerResult<Handlers> | Promise<HandlerResult<Handlers>>;
+    };
+    /** @deprecated Application instances use handleResolve; raw resolution is for trusted operator tooling. */
+    resolve(input: ResolveInput<StateName>): Promise<ResolveResult<StateName, TransitionNameOf<TransitionPayloads>>>;
+    /**
+     * @deprecated Application instances use handleRestart; raw restart is for trusted operator tooling.
+     * Returns false when the instance is not stalled or is executing.
+     */
+    restartRecovery(): boolean;
+};
+declare function createDurableRuntime(options: DurableRuntimeOptions): DurableRuntime;
+
+/** Validates an application-supplied flow instance identity. */
+declare function instanceId(value: string): InstanceId;
+/** Validates an application-supplied dispatch request identity. */
+declare function requestId(value: string): RequestId;
+
+/**
+ * The one built-in bounded recovery policy (ADR 0066, values in ADR 0075).
+ * An operation gets at most this many attempts in total, counting its first run,
+ * replays, and reconciliation checks. Attempts survive restarts.
+ */
+declare const MAX_ATTEMPTS = 4;
+/** Delay before the next automatic attempt, indexed by attempts already used minus one. */
+declare const RECOVERY_DELAYS_MS: readonly [1000, 5000, 30000];
+
+type RuntimeOptions = DurableRuntimeOptions & {
+    readonly shutdownTimeoutMs?: number;
+};
+/** A standalone runtime whose asynchronous disposal releases its database ownership. */
+type ManagedRuntime = DurableRuntime & {
+    [Symbol.asyncDispose](): Promise<void>;
+};
+/** Use `await using runtime = createRuntime(options)` for automatic cleanup at scope exit. */
+declare function createRuntime(options: RuntimeOptions): ManagedRuntime;
+
+/** Owns runtime cleanup even when registration, execution, or response handling throws. */
+declare function withDurableRuntime<Result>(options: RuntimeOptions, run: (runtime: DurableRuntime) => Result | Promise<Result>): Promise<Awaited<Result>>;
+
+type TargetBase<StateName extends string> = {
+    retry(reason: string): ResolveInput<StateName>;
+    terminate(reason: string): ResolveInput<StateName>;
+};
+/** Immutable captured target: refreshing a snapshot cannot silently retarget an operator's action. */
+type RecoveryTarget<StateName extends string> = TargetBase<StateName> & ({
+    readonly callback: "guard";
+    confirm(result: boolean, reason: string): ResolveInput<StateName>;
+} | {
+    readonly callback: "resolve-start-state";
+    confirm(result: StateName, reason: string): ResolveInput<StateName>;
+} | {
+    readonly callback: "on-enter" | "on-exit" | "on-transition";
+    confirm(reason: string): ResolveInput<StateName>;
+});
+declare function recoveryTarget<StateName extends string>(work: UnresolvedWork<StateName, string>): RecoveryTarget<StateName>;
+
+export { type AppliedDispatchContext, type AttemptId, type CallbackKind, type CallbackRef, type CompletedDecision, type CreateFlowBuilder, type CreateOutcomeHandlers, type DefinitionMismatchContext, type DispatchFailure, type DispatchOutcome, type DispatchOutcomeHandlers, type DurableCallback, type DurableCompiledFlowModule, type DurableContext, type DurableControls, type DurableCreationHooks, DurableDefinitionError, DurableDefinitionMismatchError, DurableDispatchError, type DurableDispatchInput, type DurableExecutionContext, type DurableFlow, type DurableGuard, type DurableHookTable, DurableInputError, type DurableInspector, type DurableInstance, DurableOperationError, type DurableOperationInfo, DurableOwnershipError, type DurablePayloadCheck, type DurableRuntime, DurableRuntimeClosedError, DurableRuntimeError, type DurableRuntimeOptions, DurableSchemaError, DurableShutdownTimeoutError, type DurableSnapshot, type DurableStartStateResolver, type DurableStateCallback, type DurableStateHooks, type DurableTransitionCallback, type DurableTransitionHooks, type EndpointMapFor, type EnsureInstanceBuilder, type EnsureOutcomeHandlers, type ExactHandlers, type ExecutionStatus, type ExecutionStatusKind, type FlowFailure, type HandlerResult, type HistoryEvent, type HistoryEventType, type HistoryPage, type HistoryQuery, type InstanceId, type InstancePage, type InstanceQuery, type InstanceSummary, type IsJsonCompatible, type JsonCompatible, type JsonPrimitive, type JsonValue, MAX_ATTEMPTS, type ManagedRuntime, type NonJsonPayloadTransitions, type OpenOutcomeHandlers, type OperationId, type OutgoingFrom, RECOVERY_DELAYS_MS, type ReconcileContext, type ReconcileDecision, type RecoveryCause, type RecoveryDeclaration, type RecoveryStrategy, type RecoveryTarget, type RequestId, type ResolveInput, type ResolveOutcomeHandlers, type ResolveRejection, type ResolveResult, type RestartOutcomeHandlers, type RuntimeOptions, type StatesWithOutgoing, type UnresolvedWork, type UnvalidatedDispatchInput, createDurableRuntime, createRuntime, instanceId, parseResolveInput, recoveryTarget, requestId, resolveInputSchema, withDurableRuntime };