@bluelibs/runner 6.3.0 → 6.3.1

package/.agents/skills/core/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: runner
+description: Main skill for building applications with BlueLibs Runner. Use when Agent needs help modeling resources, tasks, events, hooks, middleware, tags, errors, runtime lifecycle, validation, observability, or testing in apps built with Runner, and when it should navigate Runner documentation from the compact guide into the correct in-depth guide chapter. Can be used for architecting and developing Runner as well.
+---
+
+# Runner
+
+Start with `./references/COMPACT_GUIDE.md`.
+It is the fast path for Runner's core mental model, public API shape, and common contracts.
+
+When the task needs deeper documentation, open the matching chapter from `./references/guide-units/`:
+
+- `02-resources.md` for resources, app composition, ownership, boundaries, exports, subtree policy, and overrides
+- `02b-tasks.md` for tasks, schemas, dependencies, result validation, and execution patterns
+- `02c-events-and-hooks.md` for events, hooks, event payload contracts, and decoupled flow design
+- `02d-middleware.md` for task/resource middleware and cross-cutting behavior
+- `02e-tags.md` for tags, discovery, and policy-style metadata
+- `02f-errors.md` for typed Runner errors and `.throws(...)`
+- `03-runtime-lifecycle.md` for `run(...)`, startup, shutdown, pause/resume, and run options
+- `04-features.md` for advanced built-in features such as HTTP shutdown patterns, execution context and signal propagation, cron scheduling, semaphores, and queue/semaphore utilities
+- `04b-serialization-validation.md` for serialization, validation, DTO boundaries, and trust-boundary parsing
+- `04c-security.md` for identity-aware execution, partitioning, and security patterns
+- `05-observability.md` for logs, metrics, traces, and health strategy
+- `06-meta-and-internals.md` for `meta(...)`, canonical ids and namespacing, and built-in internal services such as `resources.runtime`, `resources.store`, and `resources.taskRunner`
+- `08-testing.md` for unit, focused integration, and full integration testing
+
+When the task is about documentation authoring or guide composition itself, also read:
+
+- `DOCS_STYLE_GUIDE.md`
+- `INDEX_GUIDE.md`
+- `INDEX_README.md`
+
+Use the more specialized skills when the task leaves general Runner app usage:
+
+- use `runner-remote-lanes-specialist` for Remote Lanes work
+- use `runner-durable-workflow-specialist` for Durable Workflows work
+- use `runner-architect` for Runner framework internals, public architecture, or design changes

package/.agents/skills/durable-workflows/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: runner-durable-workflow-specialist
+description: Specialized guidance for using Runner Durable Workflows in applications. Use when Codex needs to design replay-safe workflows, choose durable resources or backends, model `step`/`sleep`/`waitForSignal` flows, wire workflow start and signal entry points, handle recovery, scheduling, rollback, or audit inspection, or debug replay and persistence behavior in Runner Durable Workflows.
+---
+
+# Runner Durable Workflow Specialist
+
+Use this skill for application-level Durable Workflow work.
+This is about building with durable workflows, not changing the workflow engine internals.
+
+## Start Here
+
+Read in this order:
+
+- `./references/DURABLE_WORKFLOWS.md` for the main guide and canonical examples.
+- `./references/DURABLE_WORKFLOWS_AI.md` for the shorter token-friendly field guide.
+- `../../../readmes/MULTI_PLATFORM.md` when platform assumptions matter, because durable workflows are Node-only.
+
+Keep the core mental model front and center:
+
+- a workflow does not resume the instruction pointer
+- it re-runs from the top and reuses persisted step results
+- side effects belong inside `durableContext.step(...)`
+
+## Design The Workflow From Checkpoints
+
+Start from the workflow contract before writing code:
+
+1. Identify the long-running business flow.
+2. Decide which moments must survive restarts, deploys, or worker moves.
+3. Turn those moments into durable checkpoints:
+   - `step(...)`
+   - `sleep(...)`
+   - `waitForSignal(...)`
+4. Decide how the workflow starts:
+   - `start(...)`
+   - `startAndWait(...)`
+5. Decide how outside systems interact later:
+   - signals
+   - schedules
+   - operator/store inspection
+
+Stable step ids are part of the workflow contract.
+If a task includes side effects outside durable steps, treat that as a bug until proven otherwise.
+
+## Wire Durable Resources Correctly
+
+Build from the supported Runner pattern:
+
+- register `resources.durable` once for tags and durable events
+- fork a concrete backend such as `resources.memoryWorkflow` or `resources.redisWorkflow`
+- inject the durable resource and call `durable.use()` inside the workflow task
+- tag workflow tasks with `tags.durableWorkflow`
+
+Prefer:
+
+- `memoryWorkflow` for local development and tests
+- `redisWorkflow` when the workflow must survive real process boundaries and production restarts
+
+Keep starter tasks, routes, or handlers separate from the durable workflow task itself.
+Start workflows explicitly through the durable service instead of exposing the workflow body as an ordinary remote task entry point.
+
+## Keep Replay Safety Honest
+
+When implementing or reviewing durable logic:
+
+- put external side effects inside `durableContext.step(...)`
+- keep step ids stable and descriptive
+- use explicit `stepId` options for production-facing sleeps, emits, and signal waits when needed
+- use `durableContext.switch(...)` for replay-safe branching when the flow shape matters
+- model compensation deliberately with `up(...)`, `down(...)`, and `rollback()`
+
+Common smell:
+
+- using plain mutable local flow assumptions as if the instruction pointer resumes where it left off
+
+## Signals, Scheduling, And Recovery
+
+Be explicit about how the workflow moves through time:
+
+- use signals for external approvals or domain events
+- use sleep for time-based waiting
+- use schedules for delayed or recurring durable starts
+- use recovery on startup when incomplete executions must resume
+
+When a task asks for observability or support tooling, prefer:
+
+- `store.getExecution(...)`
+- durable operator helpers when available
+- audit entries and durable events for timeline visibility
+
+## Local Development And Testing
+
+In tests:
+
+- build the smallest app that expresses the workflow contract
+- assert replay-safe behavior, not only happy-path completion
+- test signal delivery, timeout behavior, recovery, and rollback when relevant
+- prefer local durable backends first, then broader integration only when the transport or persistence layer is the actual subject
+
+When debugging, check these first:
+
+- missing `tags.durableWorkflow`
+- workflow started through the wrong surface
+- side effects outside `step(...)`
+- unstable or changed step ids
+- missing polling or recovery expectations
+- confusion between workflow result state and current execution detail in the store
+
+## Finish Cleanly
+
+Before finishing:
+
+- confirm every side effect sits behind a durable checkpoint
+- confirm workflow entry and signal paths are explicit
+- confirm the selected backend matches the runtime environment
+- run focused tests first, then `npm run qa`

package/.agents/skills/remote-lanes/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: runner-remote-lanes-specialist
+description: Specialized guidance for using Runner Remote Lanes in applications. Use when Codex needs to choose between Event Lanes and RPC Lanes, design lane topology with profiles and bindings, configure transport modes (`network`, `transparent`, `local-simulated`), wire HTTP exposure or communicator resources, debug lane auth or serializer-boundary issues, or test distributed routing with Runner Remote Lanes.
+---
+
+# Runner Remote Lanes Specialist
+
+Use this skill for application-level Remote Lanes work.
+This is about building with Remote Lanes, not changing Runner internals.
+
+## Start Here
+
+Read in this order:
+
+- `./references/REMOTE_LANES.md` for the main guide and canonical examples.
+- `./references/REMOTE_LANES_AI.md` for the compact AI field guide when you need a faster refresher.
+- `../../../readmes/REMOTE_LANES_HTTP_POLICY.md` only when the task is specifically about HTTP transport policy.
+
+Treat Remote Lanes as a routing layer that should preserve your domain definitions.
+Tasks and events stay normal Runner definitions; topology decides where they run.
+
+## Choose The Right Lane Model
+
+Make the first decision explicit:
+
+- Use Event Lanes for async fire-and-forget event propagation.
+- Use RPC Lanes for synchronous task or event RPC.
+- Use both only when the architecture genuinely needs request/response plus downstream propagation.
+
+If the user is undecided, recommend:
+
+- Event Lanes for decoupled propagation and queue semantics.
+- RPC Lanes for request/response behavior with remote results.
+
+## Build The Topology Deliberately
+
+Design Remote Lanes from three moving parts:
+
+- `lane`: the named routing boundary
+- `profile`: which runtime role is active in this process
+- `binding`: which queue or communicator backs that lane
+
+When implementing or reviewing a lane setup:
+
+1. Identify which tasks or events should be lane-assigned.
+2. Choose Event Lanes or RPC Lanes.
+3. Define lanes first.
+4. Define topology with explicit `profiles` and `bindings`.
+5. Register the correct Node resource:
+   - `eventLanesResource`
+   - `rpcLanesResource`
+6. Choose the right mode:
+   - `network` for real transport
+   - `transparent` for fastest local smoke tests
+   - `local-simulated` for serializer-boundary and auth-path simulation
+
+Prefer explicit lane assignment via lane builders or Runner tags.
+
+## Keep Boundaries Honest
+
+Remote Lanes are Node-only on the server side.
+
+- Import server resources from `@bluelibs/runner/node`.
+- Keep domain logic outside lane transport config.
+- Use topology to decide where work runs, not whether the business action should exist.
+- Keep hook/task business rules in application code, not in routing assumptions.
+- Remember that auth for HTTP exposure and auth for lane execution are separate concerns.
+
+For RPC Lanes:
+
+- Distinguish `exposure.http.auth` from lane `binding.auth`.
+- Ensure every served or assigned lane has a communicator binding.
+
+For Event Lanes:
+
+- Model queue ownership and retry policy intentionally.
+- Keep in mind that dead-letter behavior belongs to queue or broker policy.
+
+## Local Development And Testing
+
+Use the lightest mode that proves the contract:
+
+- `transparent` when you only need call-site shape and local behavior.
+- `local-simulated` when you need serialization, async-context filtering, or auth-path simulation.
+- `network` when you need real integration with queues or remote communicators.
+
+In tests:
+
+- Start with the smallest app/resource graph that expresses the lane contract.
+- Assert through emitted events, task results, queue effects, or exposure behavior.
+- Add focused tests for auth readiness, missing bindings, and mode-specific behavior when those are part of the task.
+
+## Debugging Heuristics
+
+When Remote Lanes misbehave, check these first:
+
+- wrong lane type chosen for the use case
+- lane not assigned at all
+- profile does not `consume` or `serve` the target lane
+- missing queue or communicator binding
+- missing signer or verifier material
+- `transparent` or `local-simulated` mode hiding a network-only expectation
+- serializer boundary mismatch or async-context policy mismatch
+
+If the problem mentions HTTP transport details, multipart uploads, or exposure policy, read `../../../readmes/REMOTE_LANES_HTTP_POLICY.md` before changing code.
+
+## Finish Cleanly
+
+Before finishing:
+
+- confirm the lane choice still matches the latency and coupling model
+- confirm topology is explicit and profile-driven
+- confirm Node-only assumptions stay in Node surfaces
+- run focused tests first, then `npm run qa`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluelibs/runner",
-  "version": "6.3.0",
+  "version": "6.3.1",
   "description": "BlueLibs Runner",
   "sideEffects": false,
   "main": "dist/universal/index.cjs",
@@ -178,16 +178,6 @@
   "typescript": {
     "definition": "dist/types/index.d.ts"
   },
-  "files": [
-    "dist",
-    "node.js",
-    "node.d.ts",
-    "index.d.ts",
-    "node",
-    "README.md",
-    "readmes/COMPACT_GUIDE.md",
-    "LICENSE.md"
-  ],
   "license": "MIT",
   "dependencies": {
     "cron-parser": "^5.4.0",

package/readmes/BENCHMARKS.md

@@ -0,0 +1,131 @@
+# Benchmark System
+
+← [Back to main README](../README.md)
+
+This project includes a comprehensive benchmark system to track performance regressions over time.
+
+## Overview
+
+The benchmark system has been designed to be **statistically reliable** and **CI-friendly**, addressing the common issues with micro-benchmarks:
+
+- Multiple runs with statistical analysis (median, percentiles)
+- Proper warmup phases to stabilize JIT compilation
+- Environment-aware thresholds (higher tolerance in CI)
+- Severity classification (major vs minor regressions)
+- Trend monitoring with warnings
+
+## Running Benchmarks
+
+### Full Benchmark Suite
+
+```bash
+# Run all benchmarks (takes ~2-3 minutes)
+npx jest --config=config/jest/jest.bench.config.js
+
+# Run with output to file
+BENCHMARK_OUTPUT=results.json npx jest --config=config/jest/jest.bench.config.js
+```
+
+### Single Benchmark
+
+```bash
+npx jest --config=config/jest/jest.bench.config.js --testNamePattern="basic task execution"
+```
+
+## Benchmark Configuration
+
+Configuration is stored in `config/benchmarks/benchmarks.config.json`:
+
+```json
+{
+  "threshold": 0.3, // 30% tolerance for local runs
+  "ciThreshold": 0.4, // 40% tolerance for CI runs
+  "metricThresholds": {
+    // Per-metric overrides
+    "cacheMiddleware.speedupFactor": 0.2
+  }
+}
+```
+
+## Comparing Results
+
+```bash
+# Compare current results against baseline
+node scripts/compare-benchmarks.mjs config/benchmarks/baseline.json config/benchmarks/benchmark-results.json config/benchmarks/benchmarks.config.json
+```
+
+The comparison script provides:
+
+- **Environment detection** (CI vs Local)
+- **Severity classification** (Major vs Minor regressions)
+- **Trend warnings** for concerning changes within thresholds
+- **Statistical context** showing actual vs expected values
+
+## Updating Baselines
+
+When performance characteristics legitimately change (new features, architectural changes):
+
+```bash
+# Update baseline with current environment
+./scripts/update-baseline.sh
+```
+
+**Important:** Only update baselines when:
+
+- You've made intentional performance changes
+- The current environment is representative
+- Changes have been reviewed and approved
+
+## Statistical Approach
+
+Each benchmark runs multiple times (3-5 runs) and reports:
+
+- **Median** - Primary comparison metric (robust against outliers)
+- **25th/75th percentiles** - Spread indication
+- **Min/Max** - Full range
+- **All values** - Complete transparency
+
+This approach provides much more reliable results than single-run measurements.
+
+## CI Integration
+
+The system automatically:
+
+- Detects CI environments and uses relaxed thresholds
+- Only fails builds on **major regressions** (>60% by default)
+- Shows **minor regressions** as warnings
+- Provides context about environment differences
+
+## Troubleshooting
+
+### "Screaming CI" (False Positives)
+
+If CI frequently fails with minor performance differences:
+
+1. Increase `ciThreshold` in config (try 0.5-0.6)
+2. Check if baseline was generated in similar environment
+3. Consider updating baseline if environment has changed
+
+### Inconsistent Results
+
+If results vary wildly between runs:
+
+1. Check for background processes during benchmarks
+2. Ensure sufficient warmup iterations
+3. Consider running fewer concurrent jobs in CI
+
+### Major Regressions
+
+If you see legitimate major regressions:
+
+1. Identify the change that caused it
+2. Determine if it's intentional (new feature trade-off)
+3. Optimize the regression or update baseline if acceptable
+
+## Best Practices
+
+1. **Run benchmarks in consistent environments**
+2. **Update baselines sparingly** - only when necessary
+3. **Review benchmark changes** like any other code
+4. **Monitor trends** - small consistent changes may indicate gradual regression
+5. **Don't over-optimize** - focus on real-world performance impact

package/readmes/COMPARISON.md

@@ -0,0 +1,233 @@
+# Framework Comparison
+
+> Detailed side-by-side comparison of Runner with NestJS, Effect, and DI-only containers. For the quick matrix, see the [Getting Started](#how-does-it-compare) section.
+
+---
+
+## Side-by-Side: The Same Feature in Both Frameworks
+
+Let's compare implementing the same user service in Runner and NestJS:
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**NestJS Approach** (~45 lines)
+
+```typescript
+// user.dto.ts
+import { IsString, IsEmail } from "class-validator";
+
+export class CreateUserDto {
+  @IsString()
+  name: string;
+
+  @IsEmail()
+  email: string;
+}
+
+// user.service.ts
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+
+@Injectable()
+export class UserService {
+  constructor(
+    @InjectRepository(User)
+    private userRepo: Repository<User>,
+    private readonly mailer: MailerService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async createUser(dto: CreateUserDto) {
+    const user = await this.userRepo.save(dto);
+    await this.mailer.sendWelcome(user.email);
+    this.logger.log(`Created user ${user.id}`);
+    return user;
+  }
+}
+
+// user.module.ts
+@Module({
+  imports: [TypeOrmModule.forFeature([User])],
+  providers: [UserService, MailerService],
+  controllers: [UserController],
+})
+export class UserModule {}
+```
+
+</td>
+<td width="50%" valign="top">
+
+**Runner Approach** (~25 lines)
+
+```typescript
+// users.ts
+import { r, resources } from "@bluelibs/runner";
+import { z } from "zod";
+
+const createUser = r
+  .task("users.create")
+  .dependencies({
+    db,
+    mailer,
+    logger: resources.logger,
+  })
+  .inputSchema(
+    z.object({
+      name: z.string(),
+      email: z.string().email(),
+    }),
+  )
+  .run(async (input, { db, mailer, logger }) => {
+    const user = await db.users.insert(input);
+    await mailer.sendWelcome(user.email);
+    await logger.info(`Created user ${user.id}`);
+    return user;
+  })
+  .build();
+
+// Register in app
+const app = r.resource("app").register([db, mailer, createUser]).build();
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+**Unit Testing in NestJS:**
+
+```typescript
+describe("UserService", () => {
+  it("creates user", async () => {
+    // Direct instantiation - no module needed
+    const service = new UserService(mockRepo, mockMailer, mockLogger);
+    const result = await service.createUser({
+      name: "Ada",
+      email: "ada@test.com",
+    });
+    expect(result.id).toBeDefined();
+  });
+});
+```
+
+**Integration Testing in NestJS:**
+
+```typescript
+describe("UserService (integration)", () => {
+  let service: UserService;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [
+        UserService,
+        { provide: getRepositoryToken(User), useFactory: mockRepository },
+        { provide: MailerService, useValue: mockMailer },
+        { provide: LoggerService, useValue: mockLogger },
+      ],
+    }).compile();
+
+    service = module.get(UserService);
+  });
+
+  it("creates user through DI", async () => {
+    const result = await service.createUser({
+      name: "Ada",
+      email: "ada@test.com",
+    });
+    expect(result.id).toBeDefined();
+  });
+});
+```
+
+</td>
+<td valign="top">
+
+**Unit Testing in Runner:**
+
+```typescript
+describe("createUser", () => {
+  it("creates user", async () => {
+    // Direct call - bypasses middleware
+    const result = await createUser.run(
+      { name: "Ada", email: "ada@test.com" },
+      {
+        db: mockDb,
+        mailer: mockMailer,
+        logger: mockLogger,
+      },
+    );
+    expect(result.id).toBeDefined();
+  });
+});
+```
+
+**Integration Testing in Runner:**
+
+```typescript
+describe("createUser (integration)", () => {
+  it("creates user through full pipeline", async () => {
+    // r.override(base, fn) builds replacement definitions
+    // .overrides([...]) applies them in this test container
+    const testApp = r
+      .resource("test")
+      .register([app])
+      .overrides([
+        r.override(db, async () => mockDb),
+        r.override(mailer, async () => mockMailer),
+      ])
+      .build();
+
+    const { runTask, dispose } = await run(testApp);
+    const result = await runTask(createUser, {
+      name: "Ada",
+      email: "ada@test.com",
+    });
+    expect(result.id).toBeDefined();
+    await dispose();
+  });
+});
+```
+
+</td>
+</tr>
+</table>
+
+---
+
+## Detailed Capability Comparison
+
+| Capability      | NestJS                                       | Runner                                                                 |
+| --------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
+| **Reliability** | Add external libs (e.g., `nestjs-retry`)     | Built-in: retry, circuit breaker, rate limit, cache, timeout, fallback |
+| **Type Safety** | Manual typing for DI tokens                  | Full inference from `.dependencies()` and `.with()`                    |
+| **Test Setup**  | `Test.createTestingModule()` boilerplate     | `task.run(input, mocks)` -- one line                                   |
+| **Scope**       | Web framework (HTTP-centric)                 | Application toolkit (any TypeScript app)                               |
+| **Middleware**  | Guards, interceptors, pipes (HTTP lifecycle) | Composable, type-safe, with journal introspection                      |
+| **Concurrency** | Bring your own                               | Built-in Semaphore and Queue primitives                                |
+| **Bundle Size** | Large (full framework)                       | Tree-shakable (import what you use)                                    |
+
+> **TL;DR:** NestJS gives you a structured web framework with conventions. Runner gives you a composable toolkit with **production-ready reliability built in** -- you bring the structure that fits your app.
+
+---
+
+## Runner vs Effect (TypeScript)
+
+Both Runner and Effect are functional-first and offer full type inference. They solve different problems:
+
+| Aspect                | Runner                                        | Effect                                         |
+| --------------------- | --------------------------------------------- | ---------------------------------------------- |
+| **Core abstraction**  | Tasks (plain async functions) + Resources     | `Effect<A, E, R>` (algebraic effect wrapper)   |
+| **Code style**        | Standard async/await                          | Generators or pipe-based combinators           |
+| **Error model**       | `r.error()` typed helpers, `throws` contracts | Typed error channel (`E` in `Effect<A, E, R>`) |
+| **DI**                | `.dependencies()` with full inference         | Layers and Services                            |
+| **Lifecycle**         | `init` / `dispose` on resources               | Layer acquisition / release                    |
+| **Middleware**        | First-class, composable, with journal         | Aspect-oriented via Layer composition          |
+| **Durable Workflows** | Built-in (Node)                               | Not built-in                                   |
+| **HTTP Remote Lanes** | Built-in (Node server, any fetch client)      | Not built-in                                   |
+| **Adoption path**     | Incremental -- wrap existing async functions  | Pervasive -- all code wrapped in `Effect`      |
+| **Learning curve**    | Gentle (familiar async/await)                 | Steep (FP concepts: fibers, layers, schemas)   |
+
+**Choose Runner** when you want production reliability primitives, familiar async/await, and incremental adoption. **Choose Effect** when you want algebraic effects, structured concurrency, and full compile-time error tracking at the cost of a steeper learning curve and pervasive wrapper types.