@bluelibs/runner 6.3.0 → 6.3.1

package/readmes/DURABLE_WORKFLOWS_AI.md

@@ -0,0 +1,258 @@
+# Durable Workflows (v2) — Token-Friendly
+
+← [Back to main README](../README.md) | [Full documentation](./DURABLE_WORKFLOWS.md)
+
+---
+
+Durable workflows are **Runner tasks with replay-safe checkpoints** (Node-only: `@bluelibs/runner/node`).
+
+They're designed for flows that span time (minutes → days): approvals, payments, onboarding, shipping.
+
+## The mental model
+
+- A workflow does not "resume the instruction pointer".
+- On every wake-up (sleep/signal/retry/recover), it **re-runs from the top** and fast-forwards using stored results:
+  - `durableContext.step("id", fn)` runs once, persists result, returns cached on replay.
+  - `durableContext.sleep(...)` and `durableContext.waitForSignal(...)` persist durable checkpoints.
+
+Rule: side effects belong inside `durableContext.step(...)`.
+
+## The happy path
+
+1. **Register a durable resource** (store + queue + event bus).
+2. **Write a durable task**:
+   - stable `durableContext.step("...")` ids
+   - explicit `{ stepId }` for `sleep/emit/waitForSignal` in production
+3. **Start the workflow**:
+   - `executionId = await service.start(taskOrTaskId, input)`
+   - persist `executionId` in your domain row (eg. `orders.execution_id`)
+   - or `await service.startAndWait(taskOrTaskId, input)` to start + wait in one call
+4. **Interact later via signals**:
+   - look up `executionId`
+   - `await service.signal(executionId, SignalDef, payload)`
+
+For user-facing status pages, you can read the durable execution on-demand from the durable store using `executionId` (no need to mirror into Postgres): `store.getExecution(executionId)` (or `new DurableOperator(store).getExecutionDetail(executionId)` when supported).
+
+Signals buffer if no waiter exists yet; the next `waitForSignal(...)` consumes the payload.
+
+`taskOrTaskId` can be:
+
+- an `ITask` (recommended, keeps full input/result type-safety)
+- a task id `string` (resolved via runtime registry; fail-fast if not found)
+
+`taskOrTaskId` is the built task object (`.build()`) or its id string, not the injected dependency callable from `.dependencies({...})`.
+
+`start()` vs `startAndWait()`:
+
+- `start(taskOrTaskId, input)` returns `executionId` immediately.
+- `startAndWait(taskOrTaskId, input)` starts, waits, and returns `{ durable: { executionId }, data }`.
+
+## Tagging workflows (required for discovery)
+
+Durable workflows are regular Runner tasks, but **must be tagged with `tags.durableWorkflow`** to make them discoverable at runtime. Always add this tag to your workflow tasks:
+
+```ts
+import { r } from "@bluelibs/runner";
+import { resources, tags } from "@bluelibs/runner/node";
+
+const durable = resources.memoryWorkflow.fork("app-durable");
+
+const onboarding = r
+  .task("onboarding")
+  .dependencies({ durable })
+  .tags([
+    tags.durableWorkflow.with({
+      category: "users",
+      defaults: { invitedBy: "system" },
+    }),
+  ])
+  .run(async (_input, { durable }) => {
+    const durableContext = durable.use();
+    await durableContext.step("create-user", async () => ({ ok: true }));
+    return { ok: true };
+  })
+  .build();
+
+// Later, after run(...):
+// const durableRuntime = runtime.getResourceValue(durable);
+// const workflows = durableRuntime.getWorkflows();
+```
+
+`tags.durableWorkflow` is **required** — workflows without this tag will not be discoverable via `getWorkflows()`. Register `resources.durable` once in the app so the durable tag definition and durable events are available at runtime.
+
+`tags.durableWorkflow` is discovery metadata, and can also carry optional `defaults` for `describe(...)`.
+The unified response envelope is produced by `startAndWait(...)`: `{ durable: { executionId }, data }`.
+`defaults` are applied only by `describe(task)` when no explicit describe input is passed.
+
+### Starting workflows from dependencies (HTTP route)
+
+Tagged tasks are discovery metadata only. Start workflows explicitly via `durable.start(...)` (or `durable.startAndWait(...)` when you want to wait for completion):
+
+```ts
+import express from "express";
+import { r, run } from "@bluelibs/runner";
+import { resources, tags } from "@bluelibs/runner/node";
+
+const durable = resources.memoryWorkflow.fork("app-durable");
+
+const approveOrder = r
+  .task("approve-order")
+  .dependencies({ durable })
+  .tags([tags.durableWorkflow.with({ category: "orders" })])
+  .run(async (input: { orderId: string }, { durable }) => {
+    const durableContext = durable.use();
+    await durableContext.step("approve", async () => ({ approved: true }));
+    return { orderId: input.orderId, status: "approved" as const };
+  })
+  .build();
+
+const api = r
+  .resource("api")
+  .register([resources.durable, durable.with({ worker: false }), approveOrder])
+  .dependencies({ durable, approveOrder })
+  .init(async (_cfg, { durable, approveOrder }) => {
+    const app = express();
+    app.use(express.json());
+
+    app.post("/orders/:id/approve", async (req, res) => {
+      const executionId = await durable.start(approveOrder, {
+        orderId: req.params.id,
+      });
+      res.status(202).json({ executionId });
+    });
+
+    app.listen(3000);
+  })
+  .build();
+
+await run(api);
+```
+
+Recommended wiring (config-only resources):
+
+```ts
+import { resources } from "@bluelibs/runner/node";
+
+// dev/tests
+const durable = resources.memoryWorkflow.fork("app-durable").with({
+  worker: true,
+});
+
+// production (Redis + optional RabbitMQ queue)
+const durableProd = resources.redisWorkflow.fork("app-durable").with({
+  redis: { url: process.env.REDIS_URL! },
+  queue: { url: process.env.RABBITMQ_URL! },
+  worker: true,
+});
+```
+
+`waitForSignal()` return shapes:
+
+- `await durableContext.waitForSignal(Signal)` → `payload` (throws on timeout)
+- `await durableContext.waitForSignal(Signal, { timeoutMs })` → `{ kind: "signal", payload } | { kind: "timeout" }`
+
+## Scheduling
+
+- One-time: `service.schedule(taskOrTaskId, input, { at } | { delay })`
+- Recurring: `service.ensureSchedule(taskOrTaskId, input, { id, cron } | { id, interval })`
+- Manage: `pauseSchedule/resumeSchedule/getSchedule/listSchedules/updateSchedule/removeSchedule`
+
+## Recovery
+
+- `await service.recover()` on startup kicks incomplete executions.
+- Timers (sleeps, signal timeouts, schedules) require polling enabled in at least one process.
+
+## Inspecting an execution
+
+- `createDashboardMiddleware` is now part of `@bluelibs/runner-durable-dashboard` (not core).
+- `store.getExecution(executionId)` → status (running/sleeping/completed/failed/etc)
+- When supported:
+  - `store.listStepResults(executionId)` → completed steps
+  - `store.listAuditEntries(executionId)` → timeline (step_completed, signal_waiting, signal_delivered, sleeps, status changes)
+- `new DurableOperator(store).getExecutionDetail(executionId)` returns `{ execution, steps, audit }`.
+
+"Internal steps" are recorded steps created by durable primitives (`sleep/waitForSignal/emit` and some bookkeeping). They typically use reserved step id prefixes like `__...` or `rollback:...`.
+
+Audit can be enabled via `audit: { enabled: true }`; inside workflows you can add replay-safe notes via `durableContext.note("msg", meta)`. In Runner integration, audit entries are also emitted via `durableEvents.*`.
+
+Runner integration detail: durable events emission does not depend on `audit.enabled` (it controls store persistence); events are emitted as long as an audit emitter is configured (the built-in durable workflow resources wire one by default).
+
+Import and subscribe using event definitions (not strings): `import { durableEvents } from "@bluelibs/runner/node"` and `.on(durableEvents.audit.appended)` (or a specific durable event).
+
+## Compensation / rollback
+
+- `durableContext.step("id").up(...).down(...)` registers compensations.
+- `await durableContext.rollback()` runs compensations in reverse order.
+
+## Branching with durableContext.switch()
+
+`durableContext.switch()` is a replay-safe branching primitive. It evaluates matchers against a value, persists which branch was taken, and on replay skips the matchers entirely.
+
+```ts
+const result = await durableContext.switch(
+  "route-order",
+  order.status,
+  [
+    {
+      id: "approve",
+      match: (s) => s === "paid",
+      run: async (s) => {
+        /* ... */ return "approved";
+      },
+    },
+    {
+      id: "reject",
+      match: (s) => s === "declined",
+      run: async () => "rejected",
+    },
+  ],
+  { id: "manual-review", run: async () => "needs-review" },
+); // optional default
+```
+
+- First arg is the step id (must be unique, like `durableContext.step`).
+- Matchers evaluate in order; first match wins.
+- The matched branch `id` + result are persisted; on replay the cached result is returned immediately.
+- Throws if no branch matches and no default is provided.
+- Audit emits a `switch_evaluated` entry with `branchId` and `durationMs`.
+
+## Describing a flow (static shape export)
+
+Use `durable.describe(...)` to export the structure of a workflow without executing it. Useful for documentation, visualization, and tooling.
+
+**Easiest: pass the task directly** — no refactoring needed:
+
+```ts
+// Get your durable dependency from runtime, then:
+const durableRuntime = runtime.getResourceValue(durable);
+const shape = await durableRuntime.describe(myTask);
+// shape.nodes = [{ kind: "step", stepId: "validate", ... }, ...]
+
+// TInput is inferred from the task, or can be specified explicitly:
+const shape2 = await durableRuntime.describe<{ orderId: string }>(myTask, {
+  orderId: "123",
+});
+```
+
+The recorder shims `durable.use()` inside the task's `run` and records every `durableContext.*` operation.
+
+If the task uses `tags.durableWorkflow.with({ defaults: {...} })`, `describe(task)` uses those defaults.
+`describe(task, input)` always overrides tag defaults.
+
+Notes:
+
+- The recorder captures each `durableContext.*` call as a `FlowNode`; step bodies are never executed.
+- Supported node kinds: `step`, `sleep`, `waitForSignal`, `emit`, `switch`, `note`.
+- `DurableFlowShape` and all `FlowNode` types are exported for type-safe consumption.
+- Conditional logic should be modeled with `durableContext.switch()` (not JS `if/else`) for the shape to capture it.
+
+## Versioning (don't get burned)
+
+- Step ids are part of the durable contract: don't rename/reorder casually.
+- For breaking behavior changes, ship a **new workflow task id** (eg. `...v2`) and route new starts to it while v1 drains.
+- A "dispatcher/alias" task is great for _new starts_, but in-flight stability requires the version choice to be stable (don't silently change behavior under the same durable task id).
+
+## Operational notes
+
+- `durableContext.emit(...)` is best-effort (notifications), not guaranteed delivery.
+- Queue mode is at-least-once; correctness comes from the store + step memoization.

package/readmes/ENTERPRISE.md

@@ -0,0 +1,219 @@
+# BlueLibs Runner — Enterprise
+
+← [Back to main README](../README.md)
+
+Build reliable, observable, and compliant services with a TypeScript-first framework designed for governed environments.
+
+- Strong typing and explicit dependency graphs
+- Tasks, Resources, Events, Middleware as clear building blocks
+- First-class observability and graceful lifecycle management
+- Predictable releases with LTS options
+- Enterprise support with SLAs and architecture guidance
+
+---
+
+## Why Enterprises Choose BlueLibs Runner
+
+- Reliability by design
+  - Validated dependency graph at boot (dry-run option)
+  - Error boundaries and graceful shutdown
+  - Resilience patterns: retries, timeouts, caching
+
+- Operability out of the box
+  - Structured logging with configurable formats
+  - System lifecycle events for orchestration
+  - Task- and event-level observability hooks
+
+- Performance at scale
+  - Minimal-overhead DI and middleware
+  - Async-first, highly concurrent execution
+  - Benchmark guidance and tuning tips
+
+- Low-risk adoption
+  - Type-safe contracts reduce defects
+  - Modular, opt-in architecture
+  - Clear upgrade and migration paths
+
+---
+
+## Long-Term Support (LTS) & Release Governance
+
+We align with enterprise change management: stability, predictability, and controlled upgrades.
+
+- Semantic Versioning
+  - Patch: bug/security fixes, no breaking changes
+  - Minor: backward-compatible improvements
+  - Major: planned, documented changes with migration guides
+
+- LTS Policy (current)
+  - Version 6.x: actively maintained
+  - Version 5.x: LTS through December 31, 2026
+  - New features, improvements, and public API evolution land on 6.x first
+  - 5.x receives important maintenance and critical fixes during the LTS window
+
+- Release channels
+  - Tagged releases: [GitHub Releases](https://github.com/bluelibs/runner/releases)
+
+- Governance and Change Management
+  - Deprecation policy with advance notice
+  - Documented migration guides for major versions
+  - Release note entry for every public behavior/API change
+  - Optional dry-run to validate dependency graphs in CI
+
+---
+
+## Security & Compliance
+
+Operate confidently under security review and audit.
+
+- Security posture
+  - No telemetry by default
+  - Small, explicit surface area (functional DI, no hidden globals)
+  - Error boundary and controlled shutdown hooks
+
+- Vulnerability management
+  - Rapid triage and patching for reported issues
+  - Coordinated disclosure process (contact below)
+  - Clear security advisories and release notes
+
+- Supply chain considerations
+  - Deterministic builds via lockfiles
+  - Compatible with private registries/proxies
+  - Supports Node.js LTS releases
+
+- Data handling
+  - Framework does not persist data by itself
+  - Configurable structured logging to avoid sensitive output
+
+Security contact: theodor@bluelibs.com
+
+---
+
+## Operability: Observability, Resilience, and Lifecycle
+
+- Observability
+  - Structured logger with multiple output strategies
+  - System-ready event to coordinate startup
+  - Debug modes for local/incident analysis
+
+- Resilience
+  - Retry middleware with configurable strategies
+  - Timeout middleware (AbortController-based)
+  - Caching middleware for expensive operations
+
+- Lifecycle
+  - Graceful shutdown (SIGINT/SIGTERM)
+  - Uncaught exception/rejection handling
+  - Resource disposal in reverse dependency order
+
+---
+
+## Compatibility & Environments
+
+- TypeScript-first (strong types across tasks/resources/events)
+- Node.js: `>=22` (matches package engines)
+- TypeScript: `5.6+` recommended for best type inference and tooling parity
+- Integrations:
+  - HTTP servers (e.g., Express)
+  - Message/event systems
+  - Async-capable data stores and services
+
+---
+
+## Support Plans
+
+- Professional Support
+  - 4-hour response for urgent issues (business hours)
+  - Guidance on configuration, debugging, and best practices
+  - Covers one production application
+  - Up to 25 developers
+
+- Enterprise Support
+  - 1-hour response for urgent issues, 24/7 for critical incidents
+  - Dedicated support engineer familiar with your setup
+  - Architecture reviews and performance guidance
+  - Covers one production application
+  - Up to 100 developers
+
+- Strategic Support (Custom)
+  - Custom SLAs and escalation paths
+  - Multi-app, multi-team rollouts
+  - Training and quarterly reviews
+  - Input on roadmap and feature planning
+
+Severity targets (typical):
+
+- Sev-1 (Production down/data loss): 1h response (24/7), work until mitigated
+- Sev-2 (Critical degradation, no workaround): 4h response, prioritized mitigation
+- Sev-3 (Non-critical defect, workaround exists): next business day response
+- Sev-4 (How-to/consulting): 2 business days
+
+---
+
+## Custom Work
+
+Extend the framework for your environment without bespoke debt.
+
+- Framework Extensions
+  - Custom middleware (security, compliance, integrations)
+  - Observability adapters
+
+- Migration Tooling
+  - From legacy frameworks/systems
+  - Data/config transformations and compatibility shims
+
+- Integration Adapters
+  - Message queues, proprietary protocols, legacy services
+
+- Performance Engineering
+  - Profiling and optimization
+  - Tailored caching and resource pooling
+
+Delivery model:
+
+- Discovery → Fixed proposal (scope, timeline) → Dev & test → Documentation & handover
+
+---
+
+## Adoption Playbook
+
+A practical, low-risk path from evaluation to production.
+
+1. Evaluation (days)
+
+- Run example apps and benchmarks
+- Validate logging, shutdown, retries/timeouts
+- Use dry-run in CI to inspect dependency graphs
+
+2. Pilot (weeks)
+
+- Wrap one service/workflow with tasks/resources/middleware
+- Add observability and resilience policies
+- Define SLOs and validate on staging
+
+3. Production rollout (weeks+)
+
+- Phase-by-phase migration
+- Architecture review and performance check
+- Runbooks and on-call integration
+- Formalize support plan and escalation
+
+Success metrics:
+
+- MTTR and incident count trending down
+- Error rate and p95 latency stable or improved
+- Predictable, low-friction upgrades
+
+---
+
+## Getting Started
+
+- Schedule a call: theodor@bluelibs.com
+- For rapid evaluations, share timelines and constraints to fast-track review.
+
+Please include:
+
+- Team size, criticality, and environment (cloud/on‑prem)
+- Target Node.js/TypeScript versions
+- Security/compliance requirements
+- Desired timelines and success