@ai-digital-factory/state-flow-runtime 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -1,56 +1,5 @@
 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">;
@@ -76,12 +25,45 @@ declare const resolveInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     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.ZodLiteral<"on-transition">;
+    result: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    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-transition";
+    operationId: OperationId;
+    expectedAttempts: number;
+    reason: string;
+} | {
+    result: string;
+    action: "confirm-completed";
+    callback: "on-transition";
+    operationId: OperationId;
+    expectedAttempts: number;
+    reason: string;
+}, {
+    action: "confirm-completed";
+    callback: "on-transition";
+    operationId: OperationId;
+    expectedAttempts: number;
+    reason: string;
+    result?: string | null | undefined;
+}>>, z.ZodObject<{
+    action: z.ZodLiteral<"confirm-completed">;
+    callback: z.ZodLiteral<"children">;
+    result: z.ZodJSONSchema;
+    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>>;
@@ -89,13 +71,13 @@ declare const resolveInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     reason: z.ZodString;
 }, z.core.$strict>, z.ZodTransform<{
     action: "confirm-completed";
-    callback: "on-enter" | "on-exit" | "on-transition";
+    callback: "on-enter" | "on-exit";
     operationId: OperationId;
     expectedAttempts: number;
     reason: string;
 }, {
     action: "confirm-completed";
-    callback: "on-enter" | "on-exit" | "on-transition";
+    callback: "on-enter" | "on-exit";
     operationId: OperationId;
     expectedAttempts: number;
     reason: string;
@@ -108,21 +90,21 @@ 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`.
+ * Handler authors use the callback types (`Guard`, `TransitionCallback`, …).
+ * Services use the outcome-handler, snapshot, and resolve types through `Runtime`.
  */
 declare const durableIdKind: unique symbol;
-type DurableId<Kind extends string> = string & {
+type BrandedId<Kind extends string> = string & {
     readonly [durableIdKind]: Kind;
 };
 /** Application-supplied flow instance identity. Build with `instanceId(...)`. */
-type InstanceId = DurableId<"instance">;
+type InstanceId = BrandedId<"instance">;
 /** Application-supplied dispatch request identity. Build with `requestId(...)`. */
-type RequestId = DurableId<"request">;
+type RequestId = BrandedId<"request">;
 /** State Flow-generated logical callback operation identity, stable across attempts. */
-type OperationId = DurableId<"operation">;
+type OperationId = BrandedId<"operation">;
 /** State Flow-generated identity of one execution or recovery attempt. */
-type AttemptId = DurableId<"attempt">;
+type AttemptId = BrandedId<"attempt">;
 type JsonPrimitive = string | number | boolean | null;
 type JsonValue = JsonPrimitive | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -141,22 +123,37 @@ type NonJsonPayloadTransitions<Payloads> = {
     [T in keyof Payloads]: IsJsonCompatible<Payloads[T]> extends true ? never : T;
 }[keyof Payloads];
 type RecoveryStrategy = "safe-replay" | "reconcile" | "manual";
-type DurableOperationInfo = {
+type OperationInfo = {
     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 = {
+type ExecutionContext = {
+    /** The root instance, also for callbacks of nested scopes. */
     readonly instanceId: InstanceId;
-    readonly operation: DurableOperationInfo;
-    /** Cooperative cancellation, for example during runtime close (ADR 0068). */
+    readonly operation: OperationInfo;
+    /**
+     * Cooperative cancellation: aborted when the runtime closes (ADR 0068) and when a parent
+     * Transition interrupts this nested scope (ADR 0095). Unrelated scopes are not affected.
+     */
     readonly signal: AbortSignal;
+    /** Where this callback runs: `null` for the root graph, otherwise its nested scope. */
+    readonly scope: ScopeRef | null;
+};
+/** Identity of one nested activation (ADR 0096). */
+type ScopeRef = {
+    /** Composition path from the root, for example `authenticated` or `workspace:uploads`. */
+    readonly path: string;
+    /** Distinct per activation: re-entering the same path creates a new one. */
+    readonly activationId: string;
+    /** FlowList member key; `null` outside a FlowList. */
+    readonly memberKey: string | null;
 };
-type DurableContext<Context> = Context & DurableExecutionContext;
+type CallbackContext<Context> = Context & ExecutionContext;
 type RecoveryCause = "failed" | "interrupted";
-type ReconcileContext<Context> = DurableContext<Context> & {
+type ReconcileContext<Context> = CallbackContext<Context> & {
     readonly recovery: {
         /** `interrupted` when the process stopped while `run` was in flight. */
         readonly cause: RecoveryCause;
@@ -192,91 +189,170 @@ type RecoveryDeclaration<Context, Args extends readonly unknown[], Result> = {
     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>;
+type Callback<Context, Args extends readonly unknown[], Result> = {
+    readonly run: (context: CallbackContext<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>;
+type StateCallback<Context> = Callback<Context, [], void>;
+/** One FlowList member: a key unique within the activation and the member's invocation input. */
+type ListMember<Input> = {
+    readonly key: string;
+    readonly input: Input;
+};
+/**
+ * What a composite State's `children` callback returns (ADR 0096): the input of each placed
+ * Flow that declares one, and the members of each FlowList. Placed Flows without input are omitted.
+ */
+type ChildInputsOf<Regions extends Record<string, {
+    readonly kind: "flow" | "list";
+    readonly input: unknown;
+}>> = {
+    readonly [R in keyof Regions as Regions[R]["kind"] extends "list" ? R : [Regions[R]["input"]] extends [null] ? never : R]: Regions[R]["kind"] extends "list" ? readonly ListMember<Regions[R]["input"]>[] : Regions[R]["input"];
+};
+/**
+ * `children` in a composite State handler: checkpointed once per activation. It receives the
+ * entering Transition's payload, or `null` when the State is entered at a default.
+ */
+type ChildrenCallback<Context, Inputs, EntryPayload = null> = Callback<Context, [
+    payload: EntryPayload
+], Inputs>;
+/** Handlers of a composite State: `children` is required when the result has required fields. */
+type CompositeStateHandlers<EntryContext, ExitContext, ChildrenContext, Inputs, EntryPayload = null> = StateHandlers<EntryContext, ExitContext> & (Record<never, never> extends Inputs ? {
+    readonly children?: ChildrenCallback<ChildrenContext, Inputs, EntryPayload>;
+} : {
+    readonly children: ChildrenCallback<ChildrenContext, Inputs, EntryPayload>;
+});
 /** `guard` in a durable transition handler. */
-type DurableGuard<Context, Payload> = DurableCallback<Context, [
+type Guard<Context, Payload> = Callback<Context, [
     payload: Payload
 ], boolean>;
-/** `onTransition` in a durable transition handler. */
-type DurableTransitionCallback<Context, Payload> = DurableCallback<Context, [
+/**
+ * `onTransition` in a durable transition handler. `Result` is `void` for a fixed destination and
+ * the generated union of destination names when the transition branches (ADR 0087).
+ */
+type TransitionCallback<Context, Payload, Result = void> = Callback<Context, [
     payload: Payload
-], void>;
+], Result>;
 /** `resolveStartState` in a durable creation handler. Return the initial state for ordinary creation. */
-type DurableStartStateResolver<Context, StateName extends string> = DurableCallback<Context, [], StateName>;
+type StartStateResolver<Context, StateName extends string> = Callback<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 StateHandlers<EntryContext, ExitContext> = {
+    readonly onEnter?: StateCallback<EntryContext>;
+    readonly onExit?: StateCallback<ExitContext>;
+};
+/** Handlers of a transition with one fixed destination: both callbacks are optional. */
+type TransitionHandlers<Context, Payload, Result = void> = {
+    readonly guard?: Guard<Context, Payload>;
+    readonly onTransition?: TransitionCallback<Context, Payload, Result>;
 };
-type DurableTransitionHooks<Context, Payload> = {
-    readonly guard?: DurableGuard<Context, Payload>;
-    readonly onTransition?: DurableTransitionCallback<Context, Payload>;
+/** Handlers of a branching transition: `onTransition` is required and selects the destination. */
+type BranchingTransitionHandlers<Context, Payload, Result> = {
+    readonly guard?: Guard<Context, Payload>;
+    readonly onTransition: TransitionCallback<Context, Payload, Result>;
 };
-type DurableCreationHooks<Context, StateName extends string> = {
-    readonly resolveStartState?: DurableStartStateResolver<Context, StateName>;
+type CreationHandlers<Context, StateName extends string> = {
+    readonly resolveStartState?: StartStateResolver<Context, StateName>;
 };
 type EndpointMapFor<StateName extends string> = Record<string, {
     fromState: StateName;
-    toState: StateName;
+    destinations: readonly 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 HandlerTable = {
+    readonly states: Readonly<Record<string, StateHandlers<any, any> | CompositeStateHandlers<any, any, any, any, any> | null>>;
+    readonly transitions: Readonly<Record<string, TransitionHandlers<any, any> | TransitionHandlers<any, any, string> | null>>;
+    readonly creation: CreationHandlers<any, string> | null;
 };
-type DurableCompiledFlowModule<StateName extends string, TransitionPayloads extends Record<string, unknown>, FlowConfig, EndpointMap extends EndpointMapFor<StateName>, Hooks extends DurableHookTable> = {
+/** Contract of one nested scope reachable through `instance.scope(...)` (ADR 0096). */
+type ScopeEntry<StateName extends string, EndpointMap, Payloads, List extends boolean, Scopes> = {
+    readonly states: StateName;
+    readonly endpoints: EndpointMap;
+    readonly payloads: Payloads;
+    /** A FlowList: address members with their key. */
+    readonly list: List;
+    readonly scopes: Scopes;
+};
+/** Erased scope map: composition-path segment → scope contract. */
+type ScopeMap = Record<string, ScopeEntry<string, EndpointMapFor<string>, Record<string, unknown>, boolean, unknown>>;
+type CompiledFlowModule<StateName extends string, TransitionPayloads extends Record<string, unknown>, Dependencies, EndpointMap extends EndpointMapFor<StateName>, Handlers extends HandlerTable, Scopes = Record<never, never>, Input = null> = {
     readonly execution: "durable";
-    readonly chartName: string;
+    readonly flowName: string;
     readonly initialStateId: string;
     readonly states: ReadonlyArray<{
         readonly id: string;
         readonly name: StateName;
+        /** `final` for a FinalState; reaching it completes the instance. */
+        readonly kind?: "state" | "final";
+        /** Nested States name their composite parent and region (ADR 0095). */
+        readonly parentId?: string;
+        readonly region?: string;
     }>;
     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 destinations: ReadonlyArray<{
+            readonly toId: string;
+            readonly toName: StateName;
+            readonly description: string;
+        }>;
+        readonly childWork?: "block" | "interrupt";
+        readonly trigger?: "dispatch" | "done";
+    }>;
+    /** Composite States and their regions (ADR 0096); absent for a flat flow. */
+    readonly compositions?: ReadonlyArray<{
+        readonly stateId: string;
+        readonly kind: "compound" | "parallel";
+        readonly regions: ReadonlyArray<{
+            readonly name: string;
+            readonly kind: "inline";
+            readonly defaultId: string;
+        } | {
+            readonly name: string;
+            readonly kind: "flow" | "list";
+            readonly flow: string;
+        }>;
     }>;
+    /** Compiled modules of the Flows this one places, by flow name. */
+    readonly placedFlows?: Readonly<Record<string, unknown>>;
+    /** Invocation input contract when this Flow runs as a nested child. */
+    readonly inputSchema?: z.ZodType<Input, Input>;
+    /** Dispatchable Transitions of the root graph. */
     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;
+    readonly handlers: Handlers;
     /**
-     * Hash of the chart's handler sources, written by compile. Unresolved work started under a
+     * Hash of the flow'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 __dependenciesBrand?: Dependencies;
     readonly __transitionPayloadsBrand?: TransitionPayloads;
-} & DurablePayloadCheck<TransitionPayloads>;
+    readonly __scopesBrand?: Scopes;
+} & PayloadCheck<TransitionPayloads>;
 /** Rejects a compiled module whose transition payloads are not JSON-compatible. */
-type DurablePayloadCheck<TransitionPayloads> = [
+type PayloadCheck<TransitionPayloads> = [
     NonJsonPayloadTransitions<TransitionPayloads>
 ] extends [never] ? unknown : {
     readonly "State Flow: transition payloads must be JSON-compatible": NonJsonPayloadTransitions<TransitionPayloads>;
 };
+/** Allowed destinations of transition `T`. */
+type DestinationOf<EndpointMap extends EndpointMapFor<string>, T extends keyof EndpointMap> = EndpointMap[T]["destinations"][number];
 /** 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> = {
+type DispatchInput<TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<string>, From extends string> = {
     [T in OutgoingFrom<EndpointMap, From>]: {
         readonly requestId: RequestId;
         readonly transition: T;
@@ -291,6 +367,11 @@ type CallbackRef<StateName extends string, TransitionName extends string> = {
 } | {
     readonly kind: "on-exit";
     readonly state: StateName;
+}
+/** A composite State's `children` callback (ADR 0096). */
+ | {
+    readonly kind: "children";
+    readonly state: StateName;
 } | {
     readonly kind: "guard";
     readonly transition: TransitionName;
@@ -316,6 +397,16 @@ type ExecutionStatus<StateName extends string, TransitionName extends string> =
 } | {
     readonly kind: "running";
     readonly requestId: RequestId | null;
+    /**
+     * The transition in progress, `null` during creation. The committed `state` remains its
+     * source until the selected destination commits, so UIs show progress from this (ADR 0087).
+     */
+    readonly transition: TransitionName | null;
+    /**
+     * The destination this execution recorded once `onTransition` selected it (or a fixed
+     * destination advanced); `null` before selection.
+     */
+    readonly destination: StateName | null;
 } | {
     readonly kind: "recovering";
     readonly work: UnresolvedWork<StateName, TransitionName>;
@@ -326,10 +417,22 @@ type ExecutionStatus<StateName extends string, TransitionName extends string> =
 } | {
     readonly kind: "terminated";
     readonly reason: string;
+}
+/** The instance reached a FinalState. Distinct from operational termination (ADR 0087). */
+ | {
+    readonly kind: "completed";
+}
+/**
+ * A nested scope whose activation ended (ADR 0095). `interrupted` when a parent Transition
+ * interrupted its work. Retained unresolved work shows as `recovering` or `needs-attention`.
+ */
+ | {
+    readonly kind: "exited";
+    readonly interrupted: boolean;
 };
-type DurableSnapshot<StateName extends string, TransitionName extends string> = {
+type InstanceSnapshot<StateName extends string, TransitionName extends string> = {
     readonly instanceId: InstanceId;
-    readonly chartName: string;
+    readonly flowName: 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. */
@@ -344,8 +447,36 @@ type DurableSnapshot<StateName extends string, TransitionName extends string> =
         readonly error: string;
         readonly at: string;
     } | null;
+    /**
+     * Nested scopes of a root instance (ADR 0096): every active scope, and exited scopes that
+     * still retain unresolved work. Empty for a flat flow and for scope snapshots.
+     */
+    readonly scopes: readonly ScopeSnapshot[];
+};
+/** One nested activation in a root snapshot. */
+type ScopeSnapshot = ScopeRef & {
+    /** Composition-path segment relative to the parent scope. */
+    readonly segment: string;
+    /** Activation of the parent scope, `null` when the parent is the root. */
+    readonly parentActivationId: string | null;
+    /** The Flow whose graph this scope executes. */
+    readonly flowName: string;
+    readonly state: string;
+    /** False once the scope's activation exited. */
+    readonly active: boolean;
+    readonly status: ExecutionStatus<string, string>;
 };
-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 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" | "instance-completed"
+/** A composite State activated its child scopes (ADR 0096). */
+ | "scope-activated"
+/** A nested scope exited because an ancestor Transition left its State. */
+ | "scope-exited"
+/** A parent Transition interrupted a scope's running or unresolved work. */
+ | "scope-interrupted"
+/** A nested scope reached a FinalState. */
+ | "scope-completed"
+/** An interrupted operation's outcome was established after its activation exited. */
+ | "late-outcome";
 type HistoryEvent = {
     readonly sequence: number;
     readonly at: string;
@@ -368,12 +499,14 @@ type HistoryPage = {
     readonly nextAfterSequence: number | null;
 };
 type ExecutionStatusKind = ExecutionStatus<string, string>["kind"];
+/** Statuses a root instance can have: only nested scopes exit (ADR 0096). */
+type InstanceStatusKind = Exclude<ExecutionStatusKind, "exited">;
 /** One row of an instance listing, read from storage without opening the instance. */
 type InstanceSummary = {
     readonly instanceId: InstanceId;
-    readonly chartName: string;
+    readonly flowName: string;
     readonly state: string;
-    readonly status: ExecutionStatusKind;
+    readonly status: InstanceStatusKind;
     /** Needs-attention or termination reason. */
     readonly statusReason: string | null;
     readonly revision: number;
@@ -381,8 +514,8 @@ type InstanceSummary = {
     readonly updatedAt: string;
 };
 type InstanceQuery = {
-    readonly chartName?: string;
-    readonly status?: ExecutionStatusKind | readonly ExecutionStatusKind[];
+    readonly flowName?: string;
+    readonly status?: InstanceStatusKind | readonly InstanceStatusKind[];
     /** Cursor from a previous page's `next`. */
     readonly after?: string;
     /** Defaults to 50; at most 500. */
@@ -406,7 +539,7 @@ type UnvalidatedDispatchInput<Input> = Input extends unknown ? Omit<Input, "payl
     readonly payload: unknown;
 } : never;
 type CompletedDispatchContext<Input, StateName extends string, TransitionName extends string> = {
-    readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+    readonly snapshot: InstanceSnapshot<StateName, TransitionName>;
 } & ({
     readonly duplicate: false;
     readonly input: Input;
@@ -414,8 +547,15 @@ type CompletedDispatchContext<Input, StateName extends string, TransitionName ex
     readonly duplicate: true;
     readonly input: UnvalidatedDispatchInput<Input>;
 });
+/**
+ * Applied dispatch: `destination` is the State this request's execution recorded, which stays the
+ * same for duplicates even after the instance moves on; `snapshot` is the current condition.
+ */
+type AppliedContext<Input, StateName extends string, TransitionName extends string> = CompletedDispatchContext<Input, StateName, TransitionName> & {
+    readonly destination: StateName;
+};
 type DispatchOutcomeHandlers<StateName extends string, TransitionName extends string, Input, From extends StateName> = {
-    readonly applied: OutcomeHandler<CompletedDispatchContext<Input, StateName, TransitionName>>;
+    readonly applied: OutcomeHandler<AppliedContext<Input, StateName, TransitionName>>;
     readonly "invalid-payload": OutcomeHandler<{
         readonly input: UnvalidatedDispatchInput<Input>;
         readonly issues: readonly {
@@ -426,16 +566,16 @@ type DispatchOutcomeHandlers<StateName extends string, TransitionName extends st
     readonly blocked: OutcomeHandler<CompletedDispatchContext<Input, StateName, TransitionName>>;
     readonly busy: OutcomeHandler<{
         readonly input: Input;
-        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly snapshot: InstanceSnapshot<StateName, TransitionName>;
     }>;
     readonly "recovery-pending": OutcomeHandler<{
         readonly input: Input;
-        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly snapshot: InstanceSnapshot<StateName, TransitionName>;
         readonly work: UnresolvedWork<StateName, TransitionName>;
     }>;
     readonly "needs-attention": OutcomeHandler<{
         readonly input: Input;
-        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly snapshot: InstanceSnapshot<StateName, TransitionName>;
         readonly work: UnresolvedWork<StateName, TransitionName>;
         readonly reason: string;
     }>;
@@ -443,7 +583,7 @@ type DispatchOutcomeHandlers<StateName extends string, TransitionName extends st
         readonly input: Input;
         readonly expectedState: From;
         readonly actualState: StateName;
-        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly snapshot: InstanceSnapshot<StateName, TransitionName>;
     }>;
     readonly "request-conflict": OutcomeHandler<{
         readonly input: UnvalidatedDispatchInput<Input>;
@@ -455,83 +595,65 @@ type DispatchOutcomeHandlers<StateName extends string, TransitionName extends st
     }>;
     readonly terminated: OutcomeHandler<{
         readonly input: Input;
-        readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+        readonly snapshot: InstanceSnapshot<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;
+    /** The instance reached a FinalState; this new request ran no callbacks. */
+    readonly completed: OutcomeHandler<{
+        readonly input: Input;
+        readonly snapshot: InstanceSnapshot<StateName, TransitionName>;
     }>;
 };
-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;
+type DispatchOutcome = keyof DispatchOutcomeHandlers<string, string, unknown, string>;
+/**
+ * Outcomes of a dispatch to a nested scope (ADR 0095, 0096): the root outcomes, plus
+ * `interrupted` when a parent Transition interrupted this request's execution, and `inactive`
+ * when no activation exists at the addressed scope.
+ */
+type ScopedDispatchOutcomeHandlers<StateName extends string, TransitionName extends string, Input, From extends StateName> = DispatchOutcomeHandlers<StateName, TransitionName, Input, From> & {
+    /** The execution was interrupted; nothing further commits for it. Not success, not rejection. */
+    readonly interrupted: OutcomeHandler<{
+        readonly input: UnvalidatedDispatchInput<Input>;
+        readonly snapshot: InstanceSnapshot<StateName, TransitionName>;
+        readonly duplicate: boolean;
     }>;
-    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;
+    /** The addressed scope or FlowList member is not active, for example after its parent exited. */
+    readonly inactive: OutcomeHandler<{
+        readonly input: Input;
     }>;
 };
-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 ScopedDispatchOutcome = keyof ScopedDispatchOutcomeHandlers<string, string, unknown, string>;
+/** Why `ensureInstance` rejected with `DefinitionMismatchError`; the stored instance is untouched. */
+type DefinitionMismatchContext = {
+    /** The flow graph or recovery declarations changed. */
+    readonly reason: "definition";
+    readonly instanceId: InstanceId;
+    readonly message: string;
+    readonly storedFlowName: 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 ResolveInput<StateName extends string> = Exclude<ParsedResolveInput, {
-    callback: "resolve-start-state";
+    callback: "resolve-start-state" | "on-transition";
 }> | (Omit<Extract<ParsedResolveInput, {
     callback: "resolve-start-state";
 }>, "result"> & {
     readonly result: StateName;
+}) | (Omit<Extract<ParsedResolveInput, {
+    callback: "on-transition";
+}>, "result"> & {
+    /** The selected destination when the transition branches; omitted for a fixed destination. */
+    readonly result?: StateName;
 });
 type ResolveRejection = 
-/** Inspector only: no registered flow can load this instance (unknown chart or definition mismatch). */
+/** Inspector only: no registered flow can load this instance (unknown flow or definition mismatch). */
 "unavailable"
 /**
  * The operation is not the instance's current unresolved work awaiting attention, or it has
@@ -541,10 +663,15 @@ type ResolveRejection =
 /** `callback` does not match the unresolved callback. */
  | "callback-mismatch"
 /** `result` does not satisfy the callback's result contract. */
- | "invalid-result";
+ | "invalid-result"
+/**
+ * Retry of interrupted work whose activation exited (ADR 0095): it is never replayed. Only a
+ * reconcile check, Confirm it completed, or Terminate are possible.
+ */
+ | "not-replayable";
 type ResolveResult<StateName extends string, TransitionName extends string> = {
     readonly outcome: "accepted";
-    readonly snapshot: DurableSnapshot<StateName, TransitionName>;
+    readonly snapshot: InstanceSnapshot<StateName, TransitionName>;
 } | {
     readonly outcome: "rejected";
     readonly reason: ResolveRejection;
@@ -563,8 +690,57 @@ type RestartOutcomeHandlers = {
     readonly restarted: () => unknown;
     readonly "not-restarted": () => unknown;
 };
+/** Execution statuses that block a deployment: the instance has unfinished execution. */
+type BlockingStatusKind = Extract<ExecutionStatusKind, "running" | "recovering" | "needs-attention">;
+/** One instance whose unfinished execution blocks a deployment. */
+type DeploymentBlocker = {
+    /** The root instance, also when the unfinished work belongs to a nested scope. */
+    readonly instanceId: InstanceId;
+    readonly flowName: string;
+    readonly state: string;
+    readonly status: BlockingStatusKind;
+    /** Needs-attention reason; `null` otherwise. */
+    readonly statusReason: string | null;
+    /** The nested scope holding the work, including exited activations (ADR 0095); else `null`. */
+    readonly scope: (ScopeRef & {
+        readonly active: boolean;
+    }) | null;
+};
+/**
+ * The established outcome of interrupted work after its activation exited: a late result, a
+ * post-exit reconciliation, or an operator's confirmation. Durable until acknowledged, because
+ * the exited graph can no longer react and the external effect may be live.
+ */
+type LateOutcome = ScopeRef & {
+    readonly sequence: number;
+    readonly instanceId: InstanceId;
+    readonly operationId: OperationId;
+    readonly callback: CallbackRef<string, string>;
+    readonly source: "late-result" | "reconciled" | "confirmed";
+    readonly result: JsonValue;
+    readonly recordedAt: string;
+};
+/** Every persisted instance with unfinished execution, ordered by instance ID. */
+type DeploymentBlocked = {
+    readonly outcome: "blocked";
+    readonly blockers: readonly DeploymentBlocker[];
+};
+/**
+ * `runtime.handover()`: either the runtime closed and released the database, or nothing changed
+ * and the old application keeps running.
+ */
+type HandoverResult = {
+    readonly outcome: "handed-over";
+} | DeploymentBlocked;
+/** `checkDeployment()` against a database no runtime owns. */
+type DeploymentCheck = {
+    readonly outcome: "ready";
+} | DeploymentBlocked | {
+    readonly outcome: "owned";
+    readonly message: string;
+};
 
-type DurableRuntimeOptions = {
+type UnmanagedRuntimeOptions = {
     /** 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. */
@@ -575,44 +751,72 @@ type DurableRuntimeOptions = {
      */
     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>;
+type Runtime = {
+    /**
+     * Validates a compiled module, including every handler's recovery declaration, and registers it
+     * with its dependencies before any handler runs (ADR 0046, 0090). Rejects with `DefinitionError`
+     * for an invalid module and `InputError` when the flow is already registered.
+     */
+    createFlow<StateName extends string, TransitionPayloads extends Record<string, unknown>, Dependencies, EndpointMap extends EndpointMapFor<StateName>, Handlers extends HandlerTable, Scopes = Record<never, never>, Input = null>(compiled: CompiledFlowModule<StateName, TransitionPayloads, Dependencies, EndpointMap, Handlers, Scopes, Input> & PayloadCheck<TransitionPayloads>, 
     /**
-     * Registers a durable compiled module with its dependencies. Validates every handler's
-     * recovery declaration before any handler runs (ADR 0046).
+     * Implementations of the handler-owned dependency interfaces (`context.dependencies`). A
+     * Flow that places other Flows uses each placed Flow's registered dependencies, so register
+     * placed Flows first (ADR 0096).
      */
-    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>;
+    dependencies: Dependencies): Promise<RegisteredFlow<StateName, TransitionPayloads, EndpointMap, Scopes>>;
     /**
      * 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
+     * `ShutdownTimeoutError` if callbacks are still running; the lock is kept until they
      * settle or the process exits.
      */
     close(options?: {
         readonly timeoutMs?: number;
     }): Promise<void>;
+    /**
+     * The deployment gate (ADR 0091, 0094). Resolves `blocked`, listing every persisted instance
+     * that is running, recovering or needs attention, and changes nothing: the application keeps
+     * running. Otherwise it closes the runtime in the same step and resolves `handed-over` once the
+     * database is released; a deployment abandoned after that restarts this build. Rejects when the
+     * check fails, and with `ShutdownTimeoutError` when the close times out: neither permits a
+     * deployment.
+     */
+    handover(options?: {
+        readonly timeoutMs?: number;
+    }): Promise<HandoverResult>;
     /**
      * 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;
+    readonly inspector: RuntimeInspector;
     /** Explicit operator capability; pass inspector alone to read-only tools. */
-    readonly controls: DurableControls;
+    readonly controls: RuntimeControls;
 };
-type DurableInspector = {
+type RuntimeInspector = {
+    /** Root instances; nested scopes appear in their root's snapshot (`scopes`). */
     listInstances(query?: InstanceQuery): InstancePage;
     /** `null` when no instance has this ID. */
-    getSnapshot(instanceId: InstanceId): DurableSnapshot<string, string> | null;
+    getSnapshot(instanceId: InstanceId): InstanceSnapshot<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;
+    subscribe(listener: (snapshot: InstanceSnapshot<string, string>) => unknown): () => void;
+    /**
+     * Late outcomes of interrupted work the application has not acknowledged, oldest first
+     * (ADR 0095, 0096). Durable: they survive restarts until `controls.acknowledgeLateOutcome`.
+     */
+    lateOutcomes(query?: {
+        readonly instanceId?: InstanceId;
+    }): readonly LateOutcome[];
+    /** Called after each newly recorded late outcome commits. */
+    subscribeLateOutcomes(listener: (outcome: LateOutcome) => unknown): () => void;
 };
-type DurableControls = {
+type RuntimeControls = {
+    /** Marks a late outcome handled. False when it was already acknowledged or does not exist. */
+    acknowledgeLateOutcome(sequence: number): boolean;
     /**
-     * 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
+     * Resolves unresolved work using the flow registered for the instance's flow, opening the
+     * instance if needed. When no registered flow can load it (unknown flow, definition or
      * handler-revision mismatch), only `terminate` is accepted, and it runs no handler; other
      * actions return `unavailable`.
      */
@@ -621,76 +825,100 @@ type DurableControls = {
     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;
+type RegisteredFlow<StateName extends string, TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<StateName>, Scopes = Record<never, never>> = {
+    readonly flowName: string;
     readonly definitionId: string;
-    /** Prepare acquisition using the inherited failure policy. */
-    ensureInstance: HasFlowFailurePolicy extends true ? (input: {
+    /**
+     * The only way to acquire an instance (ADR 0090): opens it, or creates it once when absent, and
+     * starts required recovery. Acquiring does not imply readiness. Rejects with
+     * `DefinitionMismatchError` when the stored instance belongs to another definition or has
+     * unresolved work from other handler code. To avoid creating, check
+     * `runtime.inspector.getSnapshot(instanceId)` first.
+     */
+    ensureInstance(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>>;
+    }): Promise<FlowInstance<StateName, TransitionPayloads, EndpointMap, Scopes>>;
+};
+/** Composition-path segments that address a single activation (not a FlowList). */
+type SingleSegment<Scopes> = {
+    [K in keyof Scopes & string]: Scopes[K] extends {
+        readonly list: false;
+    } ? K : never;
+}[keyof Scopes & string];
+/** Composition-path segments of FlowLists, addressed with a member key. */
+type ListSegment<Scopes> = {
+    [K in keyof Scopes & string]: Scopes[K] extends {
+        readonly list: true;
+    } ? K : never;
+}[keyof Scopes & string];
+type ScopeHandleFor<Entry> = Entry extends {
+    readonly states: infer StateName extends string;
+    readonly endpoints: infer EndpointMap extends EndpointMapFor<string>;
+    readonly payloads: infer Payloads extends Record<string, unknown>;
+    readonly scopes: infer Nested;
+} ? ScopeHandle<StateName, Payloads, EndpointMap, Nested> : never;
+/** States of a scope with at least one dispatchable Transition. */
+type ScopeFromStates<EndpointMap> = {
+    [K in keyof EndpointMap]: EndpointMap[K] extends {
+        readonly fromState: infer From extends string;
+    } ? From : never;
+}[keyof EndpointMap];
+/** Typed access to nested scopes (ADR 0096): one level per call, chained for deeper scopes. */
+type ScopeNavigation<Scopes> = {
+    /**
+     * The active activation at `segment` (`state` for a compound State, `state:region` for a
+     * parallel region). Resolved at each call, so a handle never reaches an exited activation.
+     */
+    scope<Segment extends SingleSegment<Scopes>>(segment: Segment): ScopeHandleFor<Scopes[Segment]>;
+    /** One FlowList member by key. */
+    scope<Segment extends ListSegment<Scopes>>(segment: Segment, memberKey: string): ScopeHandleFor<Scopes[Segment]>;
+};
+/** A nested scope addressed by composition path; every call resolves its current activation. */
+type ScopeHandle<StateName extends string, TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<string>, Scopes> = ScopeNavigation<Scopes> & {
+    /** Composition path from the root, for example `workspace:uploads`. */
+    readonly path: string;
+    readonly memberKey: string | null;
+    /** The active activation's snapshot, or `null` when none is active. */
+    getSnapshot(): InstanceSnapshot<StateName, TransitionNameOf<TransitionPayloads>> | null;
+    /** History of the active activation; empty when none is active. */
+    history(query?: HistoryQuery): HistoryPage;
+    /**
+     * Dispatch to the active activation from `state`. Besides the root outcomes, `interrupted`
+     * reports an execution a parent Transition interrupted and `inactive` an absent activation.
+     * A duplicate request ID always refers to its original activation (ADR 0095).
+     */
+    when<From extends ScopeFromStates<EndpointMap> & StateName>(state: From): {
+        handle<Handlers extends ScopedDispatchOutcomeHandlers<StateName, TransitionNameOf<TransitionPayloads>, DispatchInput<TransitionPayloads, EndpointMap, From>, From>>(handlers: ExactHandlers<Handlers, ScopedDispatchOutcomeHandlers<StateName, string, unknown, From>>): {
+            dispatch(input: DispatchInput<TransitionPayloads, EndpointMap, From>): Promise<HandlerResult<Handlers>>;
+        };
     };
 };
-type DurableInstance<StateName extends string, TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<StateName>, HasDispatchPolicy extends boolean = false> = {
+type FlowInstance<StateName extends string, TransitionPayloads extends Record<string, unknown>, EndpointMap extends EndpointMapFor<StateName>, Scopes = Record<never, never>> = ScopeNavigation<Scopes> & {
     readonly instanceId: InstanceId;
-    getSnapshot(): DurableSnapshot<StateName, TransitionNameOf<TransitionPayloads>>;
+    getSnapshot(): InstanceSnapshot<StateName, TransitionNameOf<TransitionPayloads>>;
     /** Called after every committed state or status change. Returns an unsubscribe function. */
-    subscribe(listener: (snapshot: DurableSnapshot<StateName, TransitionNameOf<TransitionPayloads>>) => unknown): () => void;
+    subscribe(listener: (snapshot: InstanceSnapshot<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>>;
+    /**
+     * Dispatch from `state`: `handle` takes one callback per outcome, checked exhaustively at compile
+     * time, and returns a reusable dispatcher. The promise resolves to the selected callback's value;
+     * only programmer misuse and infrastructure failures reject (ADR 0090).
+     */
+    when<From extends StatesWithOutgoing<StateName, EndpointMap>>(state: From): {
+        handle<Handlers extends DispatchOutcomeHandlers<StateName, TransitionNameOf<TransitionPayloads>, DispatchInput<TransitionPayloads, EndpointMap, From>, From>>(handlers: ExactHandlers<Handlers, DispatchOutcomeHandlers<StateName, string, unknown, From>>): {
+            dispatch(input: DispatchInput<TransitionPayloads, EndpointMap, From>): Promise<HandlerResult<Handlers>>;
         };
     };
-    /** Exhaustive outcome mapping for manual actions; raw resolve remains the operator primitive. */
+    /** Exhaustive outcome mapping for manual actions; `runtime.controls` holds the raw 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;
+declare function createUnmanagedRuntime(options: UnmanagedRuntimeOptions): Runtime;
 
 /** Validates an application-supplied flow instance identity. */
 declare function instanceId(value: string): InstanceId;
@@ -706,18 +934,64 @@ 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 & {
+/** Base class for durable runtime rejections (infrastructure, defects, invalid input). */
+declare class RuntimeError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Another runtime already owns the database (ADR 0047). */
+declare class OwnershipError extends RuntimeError {
+}
+/** The runtime is closing or closed and admits no new work (ADR 0061). */
+declare class RuntimeClosedError extends RuntimeError {
+}
+/**
+ * `close({ timeoutMs })` elapsed while callbacks were still running. The runtime keeps the
+ * database lock; exit the process to release it (ADR 0075).
+ */
+declare class ShutdownTimeoutError extends RuntimeError {
+}
+/** A compiled module failed startup validation before any handler ran (ADR 0046). */
+declare class DefinitionError extends RuntimeError {
+    readonly problems: readonly string[];
+    constructor(flowName: string, problems: readonly string[]);
+}
+/** Input that cannot become trusted durable data (IDs, payloads, transitions). */
+declare class InputError extends RuntimeError {
+}
+/** The database was written by a newer State Flow schema. */
+declare class SchemaError extends RuntimeError {
+}
+/** Stored instances remain untouched when their definition or handler revision is incompatible. */
+declare class DefinitionMismatchError extends RuntimeError {
+    readonly context: DefinitionMismatchContext;
+    constructor(context: DefinitionMismatchContext);
+}
+
+/**
+ * The deployment gate for a database no runtime owns, for example after a crash or a manual
+ * stop (ADR 0094). It takes ownership for the check and releases it before returning, so it
+ * reports `owned` rather than readiness while a runtime is live. It never creates or upgrades the
+ * database or changes its data; a missing or foreign file throws, and other failures throw too: only
+ * `ready` permits a deployment.
+ */
+declare function checkDeployment(options: {
+    readonly databasePath: string;
+}): DeploymentCheck;
+
+type RuntimeOptions = UnmanagedRuntimeOptions & {
     readonly shutdownTimeoutMs?: number;
 };
 /** A standalone runtime whose asynchronous disposal releases its database ownership. */
-type ManagedRuntime = DurableRuntime & {
+type ManagedRuntime = Runtime & {
     [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>>;
+declare function withRuntime<Result>(options: RuntimeOptions, run: (runtime: Runtime) => Result | Promise<Result>): Promise<Awaited<Result>>;
 
 type TargetBase<StateName extends string> = {
     retry(reason: string): ResolveInput<StateName>;
@@ -731,9 +1005,20 @@ type RecoveryTarget<StateName extends string> = TargetBase<StateName> & ({
     readonly callback: "resolve-start-state";
     confirm(result: StateName, reason: string): ResolveInput<StateName>;
 } | {
-    readonly callback: "on-enter" | "on-exit" | "on-transition";
+    readonly callback: "on-enter" | "on-exit";
     confirm(reason: string): ResolveInput<StateName>;
+} | {
+    readonly callback: "children";
+    /** The child inputs and FlowList members the callback produced (ADR 0096). */
+    confirm(result: JsonValue, reason: string): ResolveInput<StateName>;
+} | {
+    readonly callback: "on-transition";
+    /**
+     * A branching transition needs the destination the operation selected; a fixed
+     * destination takes none. The runtime rejects an undeclared or missing destination.
+     */
+    confirm(reason: string, destination?: StateName): 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 };
+export { type AttemptId, type BlockingStatusKind, type BranchingTransitionHandlers, type Callback, type CallbackContext, type CallbackKind, type CallbackRef, type ChildInputsOf, type ChildrenCallback, type CompiledFlowModule, type CompletedDecision, type CompositeStateHandlers, type CreationHandlers, DefinitionError, type DefinitionMismatchContext, DefinitionMismatchError, type DeploymentBlocked, type DeploymentBlocker, type DeploymentCheck, type DestinationOf, type DispatchInput, type DispatchOutcome, type DispatchOutcomeHandlers, type EndpointMapFor, type ExactHandlers, type ExecutionContext, type ExecutionStatus, type ExecutionStatusKind, type FlowInstance, type Guard, type HandlerResult, type HandlerTable, type HandoverResult, type HistoryEvent, type HistoryEventType, type HistoryPage, type HistoryQuery, InputError, type InstanceId, type InstancePage, type InstanceQuery, type InstanceSnapshot, type InstanceStatusKind, type InstanceSummary, type IsJsonCompatible, type JsonCompatible, type JsonPrimitive, type JsonValue, type LateOutcome, type ListMember, MAX_ATTEMPTS, type ManagedRuntime, type NonJsonPayloadTransitions, type OperationId, type OperationInfo, type OutgoingFrom, OwnershipError, type PayloadCheck, RECOVERY_DELAYS_MS, type ReconcileContext, type ReconcileDecision, type RecoveryCause, type RecoveryDeclaration, type RecoveryStrategy, type RecoveryTarget, type RegisteredFlow, type RequestId, type ResolveInput, type ResolveOutcomeHandlers, type ResolveRejection, type ResolveResult, type RestartOutcomeHandlers, type Runtime, RuntimeClosedError, type RuntimeControls, RuntimeError, type RuntimeInspector, type RuntimeOptions, SchemaError, type ScopeEntry, type ScopeMap, type ScopeRef, type ScopeSnapshot, type ScopedDispatchOutcome, type ScopedDispatchOutcomeHandlers, ShutdownTimeoutError, type StartStateResolver, type StateCallback, type StateHandlers, type StatesWithOutgoing, type TransitionCallback, type TransitionHandlers, type UnmanagedRuntimeOptions, type UnresolvedWork, type UnvalidatedDispatchInput, checkDeployment, createRuntime, createUnmanagedRuntime, instanceId, parseResolveInput, recoveryTarget, requestId, resolveInputSchema, withRuntime };