@nagi-js/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lymo, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,665 @@
+type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+type Millis = number;
+type RunId = string & {
+    readonly __brand: "RunId";
+};
+type StepId = string;
+type AttemptNumber = number;
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: Types<Input, Output>;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment>;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+}
+type InferSchemaInput<S> = S extends StandardSchemaV1<infer I, unknown> ? I : never;
+type InferSchemaOutput<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never;
+interface Register {
+}
+type Tx = Register extends {
+    tx: infer T;
+} ? T : unknown;
+type StepKind = "task" | "signal" | "match";
+interface Step<Output = unknown> {
+    readonly kind: StepKind;
+    readonly id: StepId;
+    readonly __output?: Output;
+}
+type StepOutput<S> = S extends Step<infer O> ? O : never;
+type StepMap = Readonly<Record<string, Step<unknown>>>;
+type NeedsMap = StepMap;
+type NeedsOutputs<N extends NeedsMap> = {
+    readonly [K in keyof N]: StepOutput<N[K]>;
+};
+interface Logger {
+    debug(message: string, attrs?: Record<string, unknown>): void;
+    info(message: string, attrs?: Record<string, unknown>): void;
+    warn(message: string, attrs?: Record<string, unknown>): void;
+    error(message: string, attrs?: Record<string, unknown>): void;
+}
+interface StepCtx<Input = unknown> {
+    readonly input: Input;
+    readonly tx: Tx;
+    readonly runId: RunId;
+    readonly stepId: StepId;
+    readonly attempt: AttemptNumber;
+    readonly signal: AbortSignal;
+    readonly now: () => Date;
+    readonly logger: Logger;
+    /**
+     * Durable per-effect memoization. The first successful call for `(runId, stepId, scope)`
+     * persists its return value; subsequent calls (including post-crash retries) return the
+     * cached value without re-invoking `fn`.
+     */
+    once<T extends Json>(scope: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Stable idempotency key for external APIs (Stripe, Mux, etc.).
+     * Returns `hash(runId + stepId + scope)` — identical across retries of the same attempt,
+     * different across runs.
+     */
+    idempotencyKey(scope: string): string;
+}
+type BackoffStrategy = "exponential" | "linear" | "fixed";
+interface RetryPolicy {
+    readonly maxAttempts: number;
+    readonly backoff: BackoffStrategy;
+    readonly initialDelayMs?: Millis;
+    readonly maxDelayMs?: Millis;
+    readonly retryOn?: (error: unknown) => boolean;
+}
+interface StepConfigBase<Input, N extends NeedsMap> {
+    readonly needs?: N;
+    /**
+     * Skip this step when the predicate returns false. Locked semantic:
+     * downstream steps that need a skipped step are also skipped (transitive).
+     * Therefore at the type level, `needs.x` is the unconditional `Output` —
+     * not `Output | undefined`.
+     */
+    readonly when?: (args: {
+        readonly input: NoInfer<Input>;
+        readonly needs: NoInfer<NeedsOutputs<N>>;
+    }) => boolean;
+    readonly timeout?: Millis;
+}
+interface TaskConfig<Input, N extends NeedsMap, Output> extends StepConfigBase<Input, N> {
+    readonly retry?: RetryPolicy;
+    readonly run: (args: {
+        readonly input: NoInfer<Input>;
+        readonly needs: NoInfer<NeedsOutputs<N>>;
+        readonly ctx: StepCtx<NoInfer<Input>>;
+    }) => Promise<Output>;
+}
+interface SignalConfig<Input, N extends NeedsMap, Schema extends StandardSchemaV1> extends StepConfigBase<Input, N> {
+    readonly schema: Schema;
+}
+/**
+ * Discriminator mode — exhaustive at compile time. `cases` must cover every
+ * value in the discriminant union; adding a new value to the discriminant
+ * is a type error until the case is handled.
+ */
+interface MatchDiscriminatorConfig<Input, N extends NeedsMap, D extends string, M extends Record<D, StepMap>> {
+    readonly needs?: N;
+    readonly on: (args: {
+        readonly input: NoInfer<Input>;
+        readonly needs: NoInfer<NeedsOutputs<N>>;
+    }) => D;
+    readonly cases: {
+        readonly [K in D]: (b: Builder<Input>) => M[K];
+    };
+}
+interface MatchArmGuard<Input, N extends NeedsMap, M extends StepMap> {
+    readonly when: (args: {
+        readonly input: NoInfer<Input>;
+        readonly needs: NoInfer<NeedsOutputs<N>>;
+    }) => boolean;
+    readonly otherwise?: never;
+    readonly build: (b: Builder<Input>) => M;
+}
+interface MatchArmOtherwise<Input, M extends StepMap> {
+    readonly otherwise: true;
+    readonly when?: never;
+    readonly build: (b: Builder<Input>) => M;
+}
+type MatchArm<Input, N extends NeedsMap, M extends StepMap> = MatchArmGuard<Input, N, M> | MatchArmOtherwise<Input, M>;
+/**
+ * Inference-friendly arm shape: M is not bound, so each arm in an `arms:` tuple
+ * keeps its own StepMap (and per-step Output) through inference. The `arms`
+ * overload of `Builder.match` uses this; user-facing arms still satisfy
+ * `MatchArm<Input, N, M>` for any concrete M they construct.
+ */
+type MatchArmShape<Input, N extends NeedsMap> = {
+    readonly when: (args: {
+        readonly input: NoInfer<Input>;
+        readonly needs: NoInfer<NeedsOutputs<N>>;
+    }) => boolean;
+    readonly otherwise?: never;
+    readonly build: (b: Builder<Input>) => StepMap;
+} | {
+    readonly otherwise: true;
+    readonly when?: never;
+    readonly build: (b: Builder<Input>) => StepMap;
+};
+/**
+ * Guard mode — Rust-style `match { x if guard => ... }`. Top-to-bottom,
+ * first match wins. The terminal `{ otherwise: true }` arm is required so
+ * guard mode can never silently fall through.
+ */
+interface MatchGuardConfig<Input, N extends NeedsMap, M extends StepMap> {
+    readonly needs?: N;
+    readonly arms: ReadonlyArray<MatchArm<Input, N, M>>;
+}
+/** The output of a match step is a record of each step in the chosen arm. */
+type MatchArmOutput<M extends StepMap> = {
+    readonly [K in keyof M]: StepOutput<M[K]>;
+};
+/** Across all cases of a discriminator match — the union of arm outputs. */
+type MatchDiscriminatorOutput<D extends string, M extends Record<D, StepMap>> = {
+    [K in D]: MatchArmOutput<M[K]>;
+}[D];
+/**
+ * `b` inside `flow({ build: (b) => ... })`. Constructors return `Step<Output>`
+ * values whose Output has been inferred from the handler / schema / arms.
+ */
+interface Builder<Input = unknown> {
+    task<N extends NeedsMap, Output>(config: TaskConfig<Input, N, Output>): Step<Output>;
+    signal<N extends NeedsMap, S extends StandardSchemaV1>(config: SignalConfig<Input, N, S>): Step<InferSchemaOutput<S>>;
+    match<N extends NeedsMap, D extends string, Cases extends {
+        readonly [K in D]: (b: Builder<Input>) => StepMap;
+    }>(config: {
+        readonly needs?: N;
+        readonly on: (args: {
+            readonly input: NoInfer<Input>;
+            readonly needs: NoInfer<NeedsOutputs<N>>;
+        }) => D;
+        readonly cases: Cases;
+    }): Step<{
+        readonly [K in keyof Cases]: MatchArmOutput<ReturnType<Cases[K]>>;
+    }[keyof Cases]>;
+    match<N extends NeedsMap, Arms extends ReadonlyArray<MatchArmShape<Input, N>>>(config: {
+        readonly needs?: N;
+        readonly arms: Arms;
+    }): Step<MatchArmOutput<ReturnType<Arms[number]["build"]>>>;
+}
+interface FlowConfig<Id extends string, InputSchema extends StandardSchemaV1, M extends StepMap, Output = unknown> {
+    /** Stable persistence handle. TanStack-key shaped (kebab or snake). */
+    readonly id: Id;
+    readonly input: InputSchema;
+    readonly build: (b: Builder<InferSchemaOutput<InputSchema>>) => M;
+    /**
+     * Compute the flow's terminal output from its step outputs. Fired once at
+     * `flow.completed` and persisted on the fact + `onFlowComplete` event.
+     * Skipped steps land as `null` in the input record at runtime even though
+     * the type claims otherwise (consistent with the "skip is transitive" lock).
+     * Method-shorthand syntax keeps `M` bivariant so `Flow<Id, S, M, O>` remains
+     * assignable to `Flow<string, S, StepMap, O>` in fixture/test code.
+     */
+    output?(steps: NeedsOutputs<M>): Output;
+}
+interface Flow<Id extends string = string, InputSchema extends StandardSchemaV1 = StandardSchemaV1, M extends StepMap = StepMap, Output = unknown> {
+    readonly id: Id;
+    readonly input: InputSchema;
+    readonly steps: M;
+    output?(steps: NeedsOutputs<M>): Output;
+}
+type FlowInput<F> = F extends Flow<string, infer S, StepMap, unknown> ? InferSchemaOutput<S> : never;
+type FlowOutput<F> = F extends Flow<string, StandardSchemaV1, StepMap, infer O> ? O : never;
+interface FlowEvent {
+    readonly runId: RunId;
+    readonly flowId: string;
+    readonly at: Date;
+}
+interface FlowStartEvent extends FlowEvent {
+    readonly input: Json;
+}
+interface FlowCompleteEvent extends FlowEvent {
+    readonly output: Json;
+}
+interface FlowErrorEvent extends FlowEvent {
+    readonly error: SerializedError;
+}
+interface StepEvent extends FlowEvent {
+    readonly stepId: StepId;
+    readonly attempt: AttemptNumber;
+    readonly kind: StepKind;
+}
+interface StepStartEvent extends StepEvent {
+    /**
+     * The resolved input for this step at the moment it starts.
+     * - Task: the value passed to `run({ input, needs, ctx })`.
+     * - Signal: `null` (signals await an external payload — no pre-execution input).
+     * - Match: `null` (the discriminator value is computed inside the match
+     *   handler; the start event fires before that resolves).
+     */
+    readonly input: Json;
+}
+interface StepCompleteEvent extends StepEvent {
+    readonly output: Json;
+    readonly durationMs: Millis;
+}
+interface StepErrorEvent extends StepEvent {
+    readonly error: SerializedError;
+}
+interface StepRetryEvent extends StepEvent {
+    readonly error: SerializedError;
+    readonly nextAttemptAt: Date;
+}
+interface SignalSentEvent extends StepEvent {
+    readonly payload: Json;
+}
+interface SignalReceivedEvent extends StepEvent {
+    readonly payload: Json;
+}
+interface FlowHooks {
+    readonly onFlowStart?: (event: FlowStartEvent) => void | Promise<void>;
+    readonly onFlowComplete?: (event: FlowCompleteEvent) => void | Promise<void>;
+    readonly onFlowError?: (event: FlowErrorEvent) => void | Promise<void>;
+    readonly onStepStart?: (event: StepStartEvent) => void | Promise<void>;
+    readonly onStepComplete?: (event: StepCompleteEvent) => void | Promise<void>;
+    readonly onStepError?: (event: StepErrorEvent) => void | Promise<void>;
+    readonly onStepRetry?: (event: StepRetryEvent) => void | Promise<void>;
+    readonly onSignalSent?: (event: SignalSentEvent) => void | Promise<void>;
+    readonly onSignalReceived?: (event: SignalReceivedEvent) => void | Promise<void>;
+}
+interface WorkerConfig {
+    readonly concurrency?: number;
+    readonly pollIntervalMs?: Millis;
+    /** AbortSignal drives graceful drain on SIGTERM/SIGINT. */
+    readonly signal?: AbortSignal;
+}
+interface WorkerRunOnceOpts {
+    readonly maxSteps?: number;
+}
+interface WorkerRunUntilEmptyOpts {
+    /** Wall-clock deadline in `Date.now()` units. Edge runtimes have CPU/wall-time budgets. */
+    readonly deadline?: number;
+}
+interface WorkerRunResult {
+    readonly processed: number;
+}
+interface Worker {
+    /** Long-running fleet (Cloud Run service, ECS, dedicated VM). Blocks until `signal` aborts. */
+    run(): Promise<void>;
+    /** HTTP server alongside requests. Returns after up to `maxSteps` are processed. */
+    runOnce(opts?: WorkerRunOnceOpts): Promise<WorkerRunResult>;
+    /** Serverless / edge. Drains everything available within the deadline and exits. */
+    runUntilEmpty(opts?: WorkerRunUntilEmptyOpts): Promise<WorkerRunResult>;
+}
+type ClaimToken = string & {
+    readonly __brand: "ClaimToken";
+};
+interface SerializedError {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly cause?: Json;
+}
+/**
+ * Fact-ordering invariant (must hold for every Store implementation):
+ * facts persisted via `appendFact` / `completeStep` / `failStep` MUST be
+ * visible to the next `loadRunState` call. The scheduler decides what to run
+ * by projecting `RunState.steps` from the fact log, then calls `nextRunnable`
+ * — if a `step.completed` write isn't reflected in a subsequent read, the
+ * scheduler will re-enqueue or skip steps incorrectly. Adapters with read
+ * replicas must route `loadRunState` to the primary or wait for replication
+ * within a single `advance` cycle.
+ */
+interface Store {
+    appendFact(runId: RunId, fact: Fact): Promise<void>;
+    loadRunState(runId: RunId): Promise<RunState>;
+    /**
+     * Atomically begin a run. Inserts the `flow.started` fact and any
+     * materialized run row keyed by `runId` IFF no run with this `runId` already
+     * exists. Returns `{ started: true }` if this call created the run,
+     * `{ started: false }` if the run already exists.
+     *
+     * Two concurrent `tryStartRun(runId, ...)` calls with the same `runId` must
+     * result in exactly one `flow.started` fact. Adapters enforce this at the
+     * durability layer (e.g. Postgres `INSERT ... ON CONFLICT DO NOTHING` keyed
+     * by `run_id`), NOT via app-level check-then-insert.
+     *
+     * The runtime calls this exactly once at `wf.start()`. Subsequent facts go
+     * through `appendFact` as usual.
+     */
+    tryStartRun(runId: RunId, fact: FlowStartedFact): Promise<{
+        readonly started: boolean;
+    }>;
+    /**
+     * Returns null if the step is already claimed under a live lease. Lease
+     * duration is owned by the Store implementation; configure it on the adapter.
+     */
+    claimStep(runId: RunId, stepId: StepId, attempt: AttemptNumber): Promise<ClaimToken | null>;
+    completeStep(runId: RunId, stepId: StepId, output: Json, fact: Fact): Promise<void>;
+    failStep(runId: RunId, stepId: StepId, error: SerializedError, fact: Fact): Promise<void>;
+    /** Memoization read — returns the persisted output of a previously completed step. */
+    getStepOutput(runId: RunId, stepId: StepId): Promise<Json | null>;
+    /** `ctx.once` durable record. */
+    recordOnce(runId: RunId, stepId: StepId, scope: string, value: Json): Promise<void>;
+    getOnce(runId: RunId, stepId: StepId, scope: string): Promise<Json | null>;
+    /**
+     * Run a task step's handler inside an adapter-owned transaction.
+     *
+     * Implementations open a transaction (or equivalent atomic scope), invoke
+     * `body(tx)`, and on a successful return persist the returned fact
+     * atomically with any writes the handler made via `ctx.tx`. The output is
+     * returned to the caller; for `step.failed` facts the output is ignored
+     * (callers should still return the placeholder shape the type requires).
+     *
+     * Contract:
+     * - If `body` throws, the transaction is rolled back and the error
+     *   propagates. The caller (dispatcher) is responsible for recording the
+     *   failure via `failStep` in a separate scope so the failure survives
+     *   even when domain writes do not.
+     * - On a returned `step.completed` fact, the same atomic scope must also
+     *   record the step output (such that `getStepOutput` reflects it) and
+     *   release any worker lease held for `(runId, stepId, attempt)`.
+     *
+     * For adapters with no real transaction (in-memory, sqlite without WAL),
+     * `tx` is passed as `undefined as Tx` and the write is non-atomic — those
+     * adapters are not used with `ctx.tx` writes.
+     */
+    runStep<T extends Json>(runId: RunId, stepId: StepId, attempt: AttemptNumber, body: (tx: Tx) => Promise<{
+        readonly output: T;
+        readonly fact: StepCompletedFact | StepFailedFact;
+    }>): Promise<T>;
+}
+interface QueueMessage {
+    readonly receipt: string;
+    readonly runId: RunId;
+    readonly stepId: StepId;
+    readonly payload: Json;
+    readonly attempt: AttemptNumber;
+}
+interface QueueDequeueOpts {
+    readonly count: number;
+}
+interface QueueEnqueueOpts {
+    /** Attempt number to publish. Defaults to 1. The dispatcher controls increments. */
+    readonly attempt?: AttemptNumber;
+    /** Visibility delay — the message becomes dequeueable after `delayMs`. */
+    readonly delayMs?: Millis;
+    /** Adapter-specific extra data. Core never reads this. */
+    readonly payload?: Json;
+}
+interface Queue {
+    enqueue(runId: RunId, stepId: StepId, opts?: QueueEnqueueOpts): Promise<void>;
+    dequeue(opts: QueueDequeueOpts): Promise<readonly QueueMessage[]>;
+    ack(receipt: string): Promise<void>;
+    nack(receipt: string, opts?: {
+        delayMs?: Millis;
+    }): Promise<void>;
+    extend(receipt: string, leaseMs: Millis): Promise<void>;
+}
+interface Clock {
+    now(): Date;
+    /** Resolves when `ms` has elapsed or `signal` aborts. */
+    sleep(ms: Millis, signal?: AbortSignal): Promise<void>;
+    /** Persistent timer — wakes the scheduler at `at` for `(runId, stepId)`. */
+    schedule(at: Date, runId: RunId, stepId: StepId): Promise<void>;
+}
+/**
+ * Wakes the scheduler when there's work to do. Default impl polls via the
+ * Queue plugin; Postgres adapter offers a NOTIFY/LISTEN variant.
+ * Per the sharding-safety lock: the handler receives a `runId` — there is no
+ * global tick.
+ */
+interface Trigger {
+    subscribe(handler: (runId: RunId) => void): () => void;
+}
+type FactKind = "flow.started" | "flow.completed" | "flow.failed" | "step.started" | "step.completed" | "step.failed" | "step.retried" | "step.skipped" | "signal.sent" | "signal.received" | "once.recorded" | "match.arm-selected";
+interface FactBase {
+    readonly runId: RunId;
+    readonly at: Date;
+}
+interface FlowStartedFact extends FactBase {
+    readonly kind: "flow.started";
+    readonly flowId: string;
+    readonly input: Json;
+}
+interface FlowCompletedFact extends FactBase {
+    readonly kind: "flow.completed";
+    readonly output: Json;
+}
+interface FlowFailedFact extends FactBase {
+    readonly kind: "flow.failed";
+    readonly error: SerializedError;
+}
+interface StepStartedFact extends FactBase {
+    readonly kind: "step.started";
+    readonly stepId: StepId;
+    readonly attempt: AttemptNumber;
+}
+interface StepCompletedFact extends FactBase {
+    readonly kind: "step.completed";
+    readonly stepId: StepId;
+    readonly attempt: AttemptNumber;
+    readonly output: Json;
+}
+interface StepFailedFact extends FactBase {
+    readonly kind: "step.failed";
+    readonly stepId: StepId;
+    readonly attempt: AttemptNumber;
+    readonly error: SerializedError;
+}
+interface StepRetriedFact extends FactBase {
+    readonly kind: "step.retried";
+    readonly stepId: StepId;
+    readonly attempt: AttemptNumber;
+    readonly nextAttemptAt: Date;
+}
+interface StepSkippedFact extends FactBase {
+    readonly kind: "step.skipped";
+    readonly stepId: StepId;
+    readonly reason: "when-false" | "transitive";
+}
+interface SignalSentFact extends FactBase {
+    readonly kind: "signal.sent";
+    readonly stepId: StepId;
+    readonly payload: Json;
+}
+interface SignalReceivedFact extends FactBase {
+    readonly kind: "signal.received";
+    readonly stepId: StepId;
+    readonly payload: Json;
+}
+interface OnceRecordedFact extends FactBase {
+    readonly kind: "once.recorded";
+    readonly stepId: StepId;
+    readonly scope: string;
+    readonly value: Json;
+}
+interface MatchArmSelectedFact extends FactBase {
+    readonly kind: "match.arm-selected";
+    readonly stepId: StepId;
+    readonly arm: string;
+}
+type Fact = FlowStartedFact | FlowCompletedFact | FlowFailedFact | StepStartedFact | StepCompletedFact | StepFailedFact | StepRetriedFact | StepSkippedFact | SignalSentFact | SignalReceivedFact | OnceRecordedFact | MatchArmSelectedFact;
+type RunStatus = "pending" | "running" | "completed" | "failed";
+type StepStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+interface StepState {
+    readonly stepId: StepId;
+    readonly status: StepStatus;
+    readonly attempts: AttemptNumber;
+    readonly output?: Json;
+    readonly error?: SerializedError;
+}
+interface RunState {
+    readonly runId: RunId;
+    readonly flowId: string;
+    readonly status: RunStatus;
+    readonly steps: Readonly<Record<StepId, StepState>>;
+    readonly facts: ReadonlyArray<Fact>;
+}
+type ReplayMode = "inspect" | "continue";
+interface ReplayOpts {
+    readonly mode: ReplayMode;
+}
+
+/**
+ * Construct a flow.
+ *
+ * 1. Run `build(b)` to collect the user's StepMap. Each call to `b.task` /
+ *    `b.signal` / `b.match` produced a Step with `id: ""` and a captured def
+ *    (which may reference upstream Step values from earlier in the closure).
+ *    Match defs additionally hold their arms' nested StepMaps on `_nested`.
+ * 2. Walk the returned map *recursively*, descending into match arms. Each
+ *    step gets an id derived from its position: top-level keys verbatim,
+ *    nested arm steps namespaced as `<matchKey>.<armId>.<stepKey>`.
+ * 3. Rewrite every def's `needs` so each upstream Step value carries its
+ *    assigned id. Nested-arm step defs additionally get a `parentMatch`
+ *    annotation so the scheduler can gate them on arm selection.
+ * 4. Promote `MatchArmDef._nested` → `MatchArmDef.stepIds` (the namespaced
+ *    IDs of the arm's nested steps), then drop `_nested`.
+ */
+declare function flow<const Id extends string, InputSchema extends StandardSchemaV1, M extends StepMap, Output = unknown>(config: FlowConfig<Id, InputSchema, M, Output>): Flow<Id, InputSchema, M, Output>;
+
+interface InMemoryStoreOpts {
+    readonly leaseMs?: Millis;
+}
+declare class InMemoryStore implements Store {
+    private readonly facts;
+    private readonly outputs;
+    private readonly onces;
+    private readonly leases;
+    private readonly leaseMs;
+    constructor(opts?: InMemoryStoreOpts);
+    appendFact(runId: RunId, fact: Fact): Promise<void>;
+    tryStartRun(runId: RunId, fact: FlowStartedFact): Promise<{
+        readonly started: boolean;
+    }>;
+    loadRunState(runId: RunId): Promise<RunState>;
+    claimStep(runId: RunId, stepId: StepId, attempt: AttemptNumber): Promise<ClaimToken | null>;
+    completeStep(runId: RunId, stepId: StepId, output: Json, fact: Fact): Promise<void>;
+    failStep(runId: RunId, _stepId: StepId, _error: SerializedError, fact: Fact): Promise<void>;
+    getStepOutput(runId: RunId, stepId: StepId): Promise<Json | null>;
+    recordOnce(runId: RunId, stepId: StepId, scope: string, value: Json): Promise<void>;
+    getOnce(runId: RunId, stepId: StepId, scope: string): Promise<Json | null>;
+    runStep<T extends Json>(runId: RunId, stepId: StepId, _attempt: AttemptNumber, body: (tx: Tx) => Promise<{
+        readonly output: T;
+        readonly fact: StepCompletedFact | StepFailedFact;
+    }>): Promise<T>;
+}
+/**
+ * Project an append-only fact stream into a `RunState`. Public so adapters
+ * (e.g. `@nagi-js/postgres`) can re-use the same projection rules — keeping
+ * one canonical definition of "what does the fact log mean".
+ */
+declare function projectRunState(runId: RunId, facts: readonly Fact[]): RunState;
+interface InMemoryQueueOpts {
+    readonly leaseMs?: Millis;
+}
+declare class InMemoryQueue implements Queue {
+    private readonly pending;
+    private readonly leased;
+    private readonly leaseMs;
+    constructor(opts?: InMemoryQueueOpts);
+    enqueue(runId: RunId, stepId: StepId, opts?: QueueEnqueueOpts): Promise<void>;
+    dequeue(opts: QueueDequeueOpts): Promise<readonly QueueMessage[]>;
+    ack(receipt: string): Promise<void>;
+    nack(receipt: string, opts?: {
+        delayMs?: Millis;
+    }): Promise<void>;
+    extend(receipt: string, leaseMs: Millis): Promise<void>;
+}
+interface InMemoryClockOpts {
+    /**
+     * Wires `schedule()` wake-ups to a trigger. When the persistent timer fires,
+     * the clock calls `trigger.fire(runId)` so scheduler subscribers can resume
+     * the run. Without this, `schedule()` is a no-op on the worker loop and any
+     * step that depends on it (time-based gates, long-delayed retries) will
+     * stall in tests.
+     */
+    readonly trigger?: InMemoryTrigger;
+}
+declare class InMemoryClock implements Clock {
+    private readonly timers;
+    private readonly trigger;
+    constructor(opts?: InMemoryClockOpts);
+    now(): Date;
+    sleep(ms: Millis, signal?: AbortSignal): Promise<void>;
+    schedule(at: Date, runId: RunId, stepId: StepId): Promise<void>;
+    /** Clear any pending scheduled timers. Call from test teardown. */
+    dispose(): void;
+}
+declare class InMemoryTrigger implements Trigger {
+    private handlers;
+    subscribe(handler: (runId: RunId) => void): () => void;
+    /**
+     * Test-only: synchronously dispatch a wake-up to all subscribers.
+     * Real triggers fire from a Store change (NOTIFY/LISTEN, polling, etc.).
+     */
+    fire(runId: RunId): void;
+}
+
+interface NagiConfig {
+    readonly flows: ReadonlyArray<Flow>;
+    readonly store: Store;
+    readonly queue: Queue;
+    readonly clock?: Clock;
+    readonly trigger?: Trigger;
+    readonly hooks?: FlowHooks;
+    readonly logger?: Logger;
+    readonly defaultRetry?: RetryPolicy;
+}
+interface StartOpts {
+    /**
+     * Caller-supplied runId for idempotent kickoff. If provided and a run with
+     * this ID already exists, `start()` is a no-op and returns the same ID
+     * without re-appending `flow.started`, re-dispatching, or re-validating the
+     * input. Two concurrent `start()` calls with the same `runId` produce
+     * exactly one run (enforced at the Store layer).
+     *
+     * If omitted, the runtime mints a fresh ID via `crypto.randomUUID()`.
+     *
+     * Typical usage: a content hash of the input, so callers de-duplicate
+     * kickoffs without coordinating.
+     */
+    readonly runId?: RunId;
+}
+interface Wf {
+    /** Begin a new run. Returns the runId. */
+    start<F extends Flow>(flow: F, input: FlowInput<F>, opts?: StartOpts): Promise<RunId>;
+    /** Resolve a `b.signal()` step waiting on external input. */
+    signal(runId: RunId, stepName: string, payload: unknown): Promise<void>;
+    /** Construct a worker; call `run` / `runOnce` / `runUntilEmpty` on it. */
+    worker(config?: WorkerConfig): Worker;
+    /**
+     * Re-dispatch from the first incomplete step. `mode: "continue"` runs side
+     * effects (idempotency protects); `mode: "inspect"` is a no-op probe.
+     */
+    replay(runId: RunId, opts?: ReplayOpts): Promise<void>;
+}
+declare class NagiValidationError extends Error {
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+declare class NagiRuntimeError extends Error {
+    constructor(message: string);
+}
+declare function nagi(config: NagiConfig): Wf;
+
+export { type AttemptNumber, type BackoffStrategy, type Builder, type ClaimToken, type Clock, type Fact, type FactKind, type Flow, type FlowCompleteEvent, type FlowCompletedFact, type FlowConfig, type FlowErrorEvent, type FlowEvent, type FlowFailedFact, type FlowHooks, type FlowInput, type FlowOutput, type FlowStartEvent, type FlowStartedFact, InMemoryClock, InMemoryQueue, InMemoryStore, InMemoryTrigger, type InferSchemaInput, type InferSchemaOutput, type Json, type Logger, type MatchArm, type MatchArmGuard, type MatchArmOtherwise, type MatchArmOutput, type MatchArmSelectedFact, type MatchArmShape, type MatchDiscriminatorConfig, type MatchDiscriminatorOutput, type MatchGuardConfig, type Millis, type NagiConfig, NagiRuntimeError, NagiValidationError, type NeedsMap, type NeedsOutputs, type OnceRecordedFact, type Queue, type QueueDequeueOpts, type QueueEnqueueOpts, type QueueMessage, type Register, type ReplayMode, type ReplayOpts, type RetryPolicy, type RunId, type RunState, type RunStatus, type SerializedError, type SignalConfig, type SignalReceivedEvent, type SignalReceivedFact, type SignalSentEvent, type SignalSentFact, StandardSchemaV1, type StartOpts, type Step, type StepCompleteEvent, type StepCompletedFact, type StepCtx, type StepErrorEvent, type StepEvent, type StepFailedFact, type StepId, type StepKind, type StepMap, type StepOutput, type StepRetriedFact, type StepRetryEvent, type StepSkippedFact, type StepStartEvent, type StepStartedFact, type StepState, type StepStatus, type Store, type TaskConfig, type Trigger, type Tx, type Wf, type Worker, type WorkerConfig, type WorkerRunOnceOpts, type WorkerRunResult, type WorkerRunUntilEmptyOpts, flow, nagi, projectRunState };