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

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 coupleaddagaming@gmail.com. All rights reserved.
+
+State Flow is proprietary software. No license is granted by downloading,
+accessing, or receiving this software or its documentation. All third-party
+use, including personal, noncommercial and commercial use, requires prior
+written permission from the copyright holder. Copying, modifying, distributing,
+sublicensing or incorporating this software into another product also requires
+prior written permission. Request permission at coupleaddagaming@gmail.com.
+
+Any permission granted separately is governed by its written terms. This notice
+does not alter the licenses of third-party dependencies or bundled third-party
+materials; their respective licenses continue to apply.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
+THE COPYRIGHT HOLDER IS NOT LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY
+ARISING FROM THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,301 @@
-# Temporary Holding Version
+# @ai-digital-factory/state-flow-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Application-owned durable execution with SQLite storage. Requires Node.js 22.13 or later.
+
+Import from `@ai-digital-factory/state-flow-runtime`. There is one execution model: callback checkpoints, request deduplication, bounded recovery and manual resolution.
+
+Every handlers package compiles for this runtime. No execution opt-in is needed. Each callback declares how it recovers, and `state-flow compile` type-checks it against its generated contract:
+
+```ts
+import { z } from "zod";
+
+export const payloadSchema = z.strictObject({ amount: z.number().positive() });
+export type Payload = z.output<typeof payloadSchema>;
+
+export const onTransition = {
+  run: async (context, payload) => {
+    await context.dependencies.payments.charge({
+      idempotencyKey: context.operation.operationId,
+      amount: payload.amount,
+    });
+  },
+  recovery: {
+    strategy: "reconcile",
+    reconcile: async (context) =>
+      (await context.dependencies.payments.find(context.operation.operationId))
+        ? { decision: "completed" }
+        : { decision: "safe-to-retry" },
+  },
+} satisfies TransitionCallback<TransitionContext<Dependencies>, Payload>;
+```
+
+Strategies: `safe-replay` (running again cannot duplicate an effect), `reconcile` (check the external system and return `completed`, `safe-to-retry`, `pending` or `needs-attention`), and `manual` (stop for an operator on failure).
+
+Callbacks read service-supplied implementations through `context.dependencies` (formerly `context.config`). The handlers package owns the dependency interfaces; the service passes implementations to `createFlow(compiled, dependencies)` again after every restart, and State Flow never persists them.
+
+## Transition destinations and FinalState
+
+A Transition declares its destinations with `<To>` children (ADR 0087). With one destination, `onTransition` is optional and returns nothing. With several, `onTransition` is required and returns one of the authored destination names; the generated `TransitionResult` type is that exact union:
+
+```ts
+import type {
+  TransitionContext,
+  TransitionResult, // "placed" | "rejected"
+} from "@scope/flows/place-order.submit-order";
+
+export const onTransition = {
+  run: async (context, payload) => {
+    const decision = await context.dependencies.broker.submit({
+      operationId: context.operation.operationId,
+      ...payload,
+    });
+    return decision === "accepted" ? "placed" : "rejected";
+  },
+  recovery: {
+    strategy: "reconcile",
+    reconcile: async (context) => {
+      const decision = await context.dependencies.broker.lookup(
+        context.operation.operationId,
+      );
+      return decision === null
+        ? { decision: "safe-to-retry" }
+        : {
+            decision: "completed",
+            result: decision === "accepted" ? "placed" : "rejected",
+          };
+    },
+  },
+} satisfies TransitionCallback<
+  TransitionContext<Dependencies>,
+  Payload,
+  TransitionResult
+>;
+```
+
+- Guards stay boolean admission checks. Guard and `onTransition` contexts expose the allowed `context.destinations`; there is no `toState`, because a branching destination is unknown until the operation returns.
+- The lifecycle is unchanged: guard, source `onExit`, `onTransition`, commit the destination, destination `onEnter`. A false guard stops before `onExit`.
+- The selected destination is checkpointed with the callback's completion before the state commits, so a restart resumes the same choice without running the callback again.
+- Throwing, returning nothing or returning an undeclared destination is a failure handled by the declared recovery strategy; it never selects a branch implicitly. Returning an authored rejection destination is a successful business result.
+- An operator confirms a branching operation with its destination: `recoveryTarget(work).confirm(reason, "rejected")`.
+- While a transition runs, the snapshot keeps the source `state` and reports `status: { kind: "running", transition, requestId }` for UI progress.
+- `applied` dispatch results carry `destination`: the state that request's execution recorded. Duplicates report the original destination even after the instance has moved on; use `snapshot` for the current condition.
+
+A `<FinalState>` has no callbacks and no outgoing transitions. Committing it also sets `status.kind` to `completed`, atomically. Completed is distinct from operational termination and says nothing about business success. A new request against a completed instance resolves to the `completed` outcome without running callbacks; duplicates of applied requests still return their recorded results.
+
+A service registers each flow once, ensures instances by ID, and maps every dispatch outcome at compile time (ADR 0090):
+
+```ts
+import visitorAccess, {
+  type Dependencies,
+} from "@scope/handlers/visitor-access";
+import {
+  createRuntime,
+  instanceId,
+  requestId,
+} from "@ai-digital-factory/state-flow-runtime";
+
+await using runtime = createRuntime({
+  databasePath: "state-flow.db",
+  shutdownTimeoutMs: 10_000,
+});
+// Rejects with DefinitionError for an invalid module.
+const flow = await runtime.createFlow(visitorAccess, dependencies);
+
+// Opens the instance, or creates it once. Rejects with DefinitionMismatchError when the stored
+// instance belongs to another definition or has unresolved work from other handler code.
+const instance = await flow.ensureInstance({
+  instanceId: instanceId("visitor-1"),
+});
+
+// One callback per outcome; adding an outcome is a compile error until every map handles it.
+// Build the dispatcher once per state and reuse it.
+const fromGuest = instance.when("guest").handle({
+  applied: ({ duplicate, destination }) => ({
+    ok: true,
+    destination,
+    duplicate,
+  }),
+  blocked: () => ({ ok: false, reason: "blocked" }),
+  "invalid-payload": ({ issues }) => ({ ok: false, reason: "invalid", issues }),
+  busy: () => ({ ok: false, reason: "busy" }),
+  "recovery-pending": () => ({ ok: false, reason: "recovering" }),
+  "needs-attention": ({ reason }) => ({ ok: false, reason }),
+  "state-mismatch": ({ actualState }) => ({ ok: false, reason: actualState }),
+  "request-conflict": () => ({ ok: false, reason: "conflict" }),
+  terminated: ({ reason }) => ({ ok: false, reason }),
+  completed: () => ({ ok: false, reason: "completed" }),
+});
+const result = await fromGuest.dispatch({
+  requestId: requestId("unlock-1"),
+  transition: "unlock-succeeds",
+  payload: { operatorSessionCookie: "…" },
+});
+
+// Runtime cleanup is awaited automatically when this scope exits.
+```
+
+`ensureInstance` is the only way to acquire an instance. A service that must not create one (for example, a webhook for an order that should already exist) checks first: `runtime.inspector.getSnapshot(instanceId)` returns `null` for an unknown ID. Programmer and infrastructure errors (an unknown transition, a closed runtime, a failing disk) reject the dispatch promise; they are not outcomes.
+
+- **One owner per database.** A second runtime on the same file throws `OwnershipError`; a crashed process releases the lock.
+- **Recovery** runs in the background with at most 4 attempts per callback (waits of 1 s, 5 s, 30 s), then marks the instance needs-attention. Budgets survive restarts. Opening an instance resumes interrupted work.
+- **Observation:** `getSnapshot()`, `subscribe()` and paged `history()` per instance; `runtime.inspector` lists instances; authorized `runtime.controls` resolves work across them for operator tools such as the durable companion in `@ai-digital-factory/state-flow-observe`.
+- **Manual recovery:** `instance.handleResolve({ accepted, rejected }).resolve({ action: "retry" | "confirm-completed" | "terminate", operationId, expectedAttempts, reason, … })`, or `runtime.controls.resolve(instanceId, …)` for operator tooling, taking `operationId` and `attempts` from the snapshot's unresolved work. An action based on an older attempt is rejected as `stale`. Your application authorizes the caller; `parseResolveInput` validates input from untrusted sources.
+- **Handler changes:** unresolved work started under different handler code (handlers, local helpers, `dependencies.ts`, declared dependencies) is not resumed (`definition-mismatch` with `reason: "handler-revision"`). Finish it with the previous build, or terminate it with `runtime.controls.resolve(id, { action: "terminate", … })`, which runs no handler.
+- **Stalls:** if an infrastructure error stops execution, `snapshot.stall` shows it; fix the cause and call `instance.handleRestart({ restarted, "not-restarted" }).restart()`.
+- **Shutdown:** `close({ timeoutMs })` rejects with `ShutdownTimeoutError` if callbacks ignore their `AbortSignal`; the database stays owned until they settle or the process exits.
+
+See ADR 0075 for the exact rules and what is not covered yet.
+
+## Composition: nested scopes (ADR 0095, 0096)
+
+A Flow that places other Flows needs them registered first, each with its own dependencies:
+
+```ts
+await runtime.createFlow(fileUpload, uploadDependencies);
+await runtime.createFlow(placeOrder, orderDependencies);
+const workspaces = await runtime.createFlow(
+  workspaceSession,
+  workspaceDependencies,
+);
+const session = await workspaces.ensureInstance({
+  instanceId: instanceId("user-1"),
+});
+
+const signedIn = session.scope("signed-in"); // compound State: its name
+const upload = signedIn.scope("uploading", "report.pdf"); // FlowList member by key
+const order = signedIn.scope("order-desk:order"); // parallel region: state:region
+
+await upload
+  .when("queued")
+  .handle({
+    ...outcomes,
+    interrupted: ({ duplicate }) =>
+      "a parent Transition interrupted this request",
+    inactive: () => "no active upload with that key",
+  })
+  .dispatch({
+    requestId: requestId("send-1"),
+    transition: "send-file",
+    payload: null,
+  });
+```
+
+- Each nested activation is a durable scope with its own State, executions and recovery; regions and members progress independently. `session.getSnapshot().scopes` lists active scopes and exited ones that still retain unresolved work.
+- Scope handles resolve the current activation on every call. Their outcomes add `interrupted` (a parent `interrupt` fenced this execution) and `inactive` (no activation at that path). A request ID belongs to its original activation.
+- `childWork="block"` parent Transitions answer `busy` while descendant work is running or unresolved; nothing queues. While a parent execution runs, its descendants answer `busy`.
+- `childWork="interrupt"` aborts the descendants' `context.signal` and proceeds. Interrupted work never advances the graph and is never replayed: a failure is reconciled (`safe-to-retry` then needs attention), and `safe-replay` or `manual` work needs attention. Retry runs only a reconcile check, Confirm it completed records the outcome, and Terminate ends the root and every activation. Unresolved interrupted work blocks `handover()` and `checkDeployment()`.
+- Late outcomes (a late result, a post-exit reconciliation or a confirmation) stay in `runtime.inspector.lateOutcomes()` and arrive through `subscribeLateOutcomes()` until `runtime.controls.acknowledgeLateOutcome(sequence)`, across restarts.
+- Manual resolution takes the root instance ID and the operation ID of work at any depth. A root's handler revision covers every placed Flow.
+- Databases from 0.1.0 upgrade in place to schema version 3; flat Flows keep their definition identity.
+
+## Schema contracts
+
+Every durable transition module exports a Zod `payloadSchema`; use `z.null()` for an explicitly empty payload. Compile derives the service payload type from the schema and rejects missing declarations or mismatched handlers. The compiled module carries the schema so State Flow validates dynamic input before running a handler or reserving a request ID. Consumers must handle `invalid-payload` alongside every other dispatch outcome. Both invalid-payload and request-conflict contexts expose the rejected payload as unknown.
+
+Use validation-only schemas. Async refinements are supported; State Flow rechecks admission and deduplication after validation yields. Schema output must preserve the JSON input; coercion, defaults, transformations and silently stripped fields are rejected when they change that input. A duplicate request is matched before validating it against a changed payload schema, preserving recorded outcomes across compatible handler deployments. Consequently, `applied` and `blocked` expose `input.payload` as unknown when `duplicate` is true; historic data must not be assumed to match the current schema. Schema refinements should be side-effect free; external I/O belongs in checkpointed handler callbacks. Domain-specific refinements belong in the handlers package; State Flow performs validation and maps its errors. Zod does not replace graph membership, freshness, authorization, or safe-replay decisions.
+
+## Scoped runtime lifetime
+
+```ts
+import { withRuntime } from "@ai-digital-factory/state-flow-runtime";
+
+await withRuntime(
+  { databasePath: "state-flow.db", shutdownTimeoutMs: 5000 },
+  async (runtime) => {
+    const flow = await runtime.createFlow(compiled, dependencies);
+    // Ensure instances and dispatch within this managed scope.
+  },
+);
+```
+
+The helper awaits application work and closes the runtime in `finally`, including when startup or response mapping fails. If work and shutdown both fail, an `AggregateError` preserves both failures. Applications decide their lifetime and signal handling; the library does not install global process handlers. Shutdown timeout retains ownership until active work settles.
+
+## Typed recovery and operator capabilities
+
+```ts
+const snapshot = instance.getSnapshot();
+if (snapshot.status.kind === "needs-attention") {
+  const target = recoveryTarget(snapshot.status.work);
+  const resolver = instance.handleResolve({
+    accepted: ({ snapshot }) => snapshot,
+    rejected: ({ reason }) => {
+      throw new Error(reason);
+    },
+  });
+  await resolver.resolve(target.retry("external dependency restored"));
+}
+```
+
+Import `recoveryTarget` from the durable entrypoint. It captures the operation ID and attempt count and exposes callback-specific confirmation input: boolean for a guard, an authored state for start-state resolution, the selected destination for a branching `onTransition`, and only a reason for void callbacks. Captured targets remain stale after later attempts; they never silently retarget refreshed work. `handleRestart({ restarted, "not-restarted" }).restart()` requires both explicit restart outcomes.
+
+`runtime.inspector` exposes only listing, snapshot/history reads and subscriptions. `runtime.controls` is the explicit privileged capability used by authorized operator tooling, including companion recovery. Instances expose recovery only through these exhaustive interfaces; the raw primitives live on `runtime.controls`. Application authorization remains mandatory before forwarding untrusted actions.
+
+Transient SQLite busy/locked infrastructure errors receive at most three automatic restart attempts (1 s, 5 s, 30 s). Other infrastructure failures remain visible stalls requiring explicit intervention. These in-memory infrastructure retries neither reset durable callback budgets nor bypass a callback's declared recovery strategy.
+
+## Deployment gate
+
+Unfinished execution never resumes under different handler code (ADR 0076), so deploying over it would strand it. Run the deployment gate before a new build replaces the old one (ADR 0091, 0094). Instances that are **Running**, **Recovering** or **Needs attention** block a deployment; **Ready** instances waiting for their next event, **Completed** and **Terminated** instances do not. These are the durable companion's status filters: an empty result for those three filters is what the gate checks, but only the gate's check is protected against new work starting.
+
+The running application performs the gate with `runtime.handover()`:
+
+```ts
+// Called by the deployment system, for example through an authenticated admin endpoint.
+app.post("/admin/deployment/handover", async (_request, response) => {
+  try {
+    const gate = await runtime.handover({ timeoutMs: 10_000 });
+    switch (gate.outcome) {
+      case "blocked":
+        // Nothing changed: this build keeps running so the work can finish or be resolved.
+        return response.status(409).json({ blockers: gate.blockers });
+      case "handed-over":
+        // The runtime is closed and the database released; stop this process now.
+        response.status(200).json({ outcome: "handed-over" });
+        setImmediate(() => process.exit(0));
+        return;
+    }
+  } catch (error) {
+    // A failed check or a timed-out shutdown is never permission to deploy.
+    response.status(503).json({ error: String(error) });
+    if (error instanceof ShutdownTimeoutError) {
+      // The runtime admits no more work but still owns the database: exit so the supervisor
+      // restarts this build, which recovers the interrupted work.
+      setImmediate(() => process.exit(1));
+    }
+  }
+});
+```
+
+```bash
+# Deployment script: deploy only after a 200 response.
+curl --fail -X POST https://app.internal/admin/deployment/handover || exit 1
+start-new-build || start-old-build   # an abandoned deployment restarts the old build
+```
+
+- `blocked` lists every blocking instance (ID, flow, state, status, reason) read from storage, including instances this process has not opened and beyond any listing page. It changes nothing: no waiting, termination or budget reset.
+- When nothing blocks, `handover` stops admission and starts closing in the same step, so no dispatch, creation, recovery or manual action can start between the check and the handover. Later calls reject with `RuntimeClosedError`. It resolves `handed-over` once the database is released. If the deployment is then abandoned, start the old build again; every remaining instance is Ready, Completed or Terminated, so nothing needs repair.
+- It rejects when the check fails, and with `ShutdownTimeoutError` when the close times out (the database stays owned until the process exits). Neither permits a deployment. `createRuntime`'s `shutdownTimeoutMs` applies when `timeoutMs` is omitted.
+
+When no runtime owns the database, for example after a crash or a manual stop, use `checkDeployment({ databasePath })` or `state-flow deployment-check --database <file>`. It returns the same `ready` / `blocked` result and blockers. While a runtime owns the database it returns `owned`, never readiness; a missing file or one that is not a State Flow database throws. It never creates or migrates the database or changes its data (opening it can roll back a journal a crashed process left behind, as any open does). A new build can run it at startup and refuse to accept work unless it is `ready`.
+
+There is no bypass. If a handler defect keeps an instance in Needs attention, the deployment that fixes the defect is blocked too: Terminate that instance with a reason through `runtime.controls` (or the companion's Terminate action), then deploy. Retry and Confirm it completed also resolve blockers, under the handler revision that started the work.
+
+The deployment system must call the gate; the library cannot stop a process from being replaced without it. Passing the gate does not waive definition checks: a Ready instance still opens only under a compatible Flow definition.
+
+### Restarts and their limits
+
+After a restart, callbacks durably recorded as completed are never run again and their results are reused; a callback that had started but not completed recovers by its declared strategy (reconcile, safe replay, or manual attention) under the same operation ID, with the interrupted run counted against its attempt budget; callbacks that had not started run normally (ADR 0093). State Flow does not provide exactly-once external effects: an effect can complete before its callback's completion is recorded, which is what reconciliation is for. It does not infer business expiry from a restart or a delay; validity checks belong in handlers. Terminating an instance stops its execution and keeps its history, but does not enter a business State or cancel external work already started.
+
+## Consumer linting
+
+Use `serviceConfig` or `handlersConfig` from the corresponding `@ai-digital-factory/eslint-plugin-state-flow/eslint.*.config.js` entrypoint and run lint in CI alongside compile and typecheck. These type-aware configurations enforce promise observation, require automatic runtime ownership through await using or withRuntime for services, prevent legacy execution bypasses, and keep runtime construction out of handlers. Explicit framework/operator lifecycle adapters may override the constructor restriction. Prepared dispatchers and unrelated transport methods are permitted. Fire-and-forget work requires explicit rejection handling; `void` alone does not satisfy the lint rule.
+
+`flow.ensureInstance({ instanceId })` opens an existing instance or reserves and creates it once, including for overlapping callers, and starts interrupted recovery. Its snapshot may be running, recovering, awaiting attention, terminated or completed; acquiring an instance does not imply it is ready. Pending recovery continues independently while the runtime remains open, and dispatch does not retry caller requests or wait for background recovery.
+
+`createRuntime({ databasePath, shutdownTimeoutMs })` creates a standalone runtime synchronously. Use `await using runtime = createRuntime(...)` to call operations sequentially and automatically await shutdown on normal completion or exceptions. TypeScript projects should include `ESNext.Disposable` in `compilerOptions.lib`. The configured shutdown timeout applies to disposal and to `runtime.close()`; explicit `close({ timeoutMs })` overrides it. `withRuntime` remains the callback-style alternative. Applications with an existing framework lifecycle can explicitly close the runtime, with a deliberate override of the managed-runtime lint rule.
+
+`runtime.createFlow(compiled, dependencies)` validates the module, including every handler's recovery declaration, and registers it before any handler runs. It rejects with `DefinitionError` for an invalid module and `InputError` for a duplicate registration; a failed registration does not reserve the flow name.
+
+## License
+
+Proprietary software. All third-party use requires prior written permission from
+coupleaddagaming@gmail.com. See LICENSE.