@bluelibs/runner 4.9.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluelibs/runner",
-  "version": "4.9.0",
+  "version": "5.0.0",
   "description": "BlueLibs Runner",
   "sideEffects": false,
   "main": "dist/universal/index.cjs",
@@ -77,25 +77,35 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts --sourcemap",
+    "build": "tsup --config config/tsup/tsup.config.ts --sourcemap",
+    "build:dashboard": "node ./scripts/build-dashboard.mjs",
+    "build:dashboard:ci": "node ./scripts/build-dashboard.mjs --install",
     "clean": "rm -rf dist",
-    "watch": "tsup --config tsup.config.ts --watch",
-    "test": "jest --verbose --runInBand",
-    "test:dev": "jest --verbose --watch",
-    "coverage": "jest --verbose --coverage",
+    "watch": "tsup --config config/tsup/tsup.config.ts --watch",
+    "test": "node ./scripts/run-jest-watchdog.mjs -- --config config/jest/jest.config.js --maxWorkers=50% --verbose=false",
+    "test:serial": "node ./scripts/run-jest-watchdog.mjs -- --config config/jest/jest.config.js --verbose --runInBand",
+    "test:dev": "jest --config config/jest/jest.config.js --verbose --watch",
+    "coverage": "jest --config config/jest/jest.config.js --verbose --coverage",
     "coverage:ai": "node ./scripts/run-coverage-ai.mjs",
-    "verbose:coverage": "jest --verbose --coverage --verbose=false --silent --noStackTrace --bail=1",
-    "test:clean": "jest --clearCache",
+    "verbose:coverage": "jest --config config/jest/jest.config.js --verbose --coverage --verbose=false --silent --noStackTrace --bail=1",
+    "test:clean": "jest --config config/jest/jest.config.js --clearCache",
     "testonly": "npm test",
-    "test:ci": "jest --verbose --coverage --ci --maxWorkers=2 --reporters=default --reporters=jest-junit",
-    "test:security": "jest --verbose --runInBand --testPathPattern=src/__tests__/security",
-    "prepublishOnly": "npm run clean && npm run build",
-    "typedoc": "typedoc --options typedoc.json",
-    "benchmark": "jest --config jest.bench.config.js --verbose --runInBand",
-    "benchmark:json": "BENCHMARK_OUTPUT=./benchmark-results.json NODE_OPTIONS=--expose-gc npm run benchmark",
-    "benchmark:compare": "node ./scripts/compare-benchmarks.mjs ./baseline.json ./benchmark-results.json ./benchmarks.config.json"
+    "test:ci": "node ./scripts/run-jest-watchdog.mjs -- --config config/jest/jest.config.js --verbose --coverage --ci --maxWorkers=2 --reporters=default --reporters=jest-junit",
+    "test:security": "jest --config config/jest/jest.config.js --verbose --runInBand --testPathPattern=src/__tests__/security",
+    "typecheck": "tsc -p config/ts/tsconfig.json --noEmit",
+    "lint": "eslint --config config/eslint/eslint.config.mjs ./src",
+    "lint:fix": "eslint --config config/eslint/eslint.config.mjs ./src --fix",
+    "qa": "npm run coverage:ai && npm run lint:fix && npm run typecheck && npm run build",
+    "prepublishOnly": "npm run clean && npm run build && npm run build:dashboard",
+    "postbuild": "npm run guide:compose",
+    "typedoc": "typedoc --options config/typedoc/typedoc.json",
+    "benchmark": "jest --config config/jest/jest.bench.config.js --verbose --runInBand",
+    "benchmark:json": "BENCHMARK_OUTPUT=./benchmarks/benchmark-results.json NODE_OPTIONS=--expose-gc npm run benchmark",
+    "benchmark:compare": "node ./scripts/compare-benchmarks.mjs ./benchmarks/baseline.json ./benchmarks/benchmark-results.json ./benchmarks/benchmarks.config.json",
+    "guide:compose": "node ./scripts/compose-readme.mjs"
   },
   "devDependencies": {
+    "@types/amqplib": "^0.10.7",
     "@types/benchmark": "^2.1.5",
     "@types/busboy": "^1.5.4",
     "@types/express": "^5.0.3",
@@ -106,14 +116,17 @@
     "@typescript-eslint/parser": "8.39.0",
     "benchmark": "^2.1.4",
     "busboy": "^1.6.0",
-    "eslint": "^9.32.0",
-    "eslint-config-prettier": "6.3.0",
-    "eslint-plugin-prettier": "3.1.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jest": "^29.11.2",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-unused-imports": "^4.3.0",
     "express": "^5.1.0",
+    "globals": "^16.5.0",
     "jest": "^29.0.0",
     "jest-environment-jsdom": "^30.1.2",
     "jest-junit": "^10.0.0",
-    "prettier": "^2.0.5",
+    "prettier": "^3.7.4",
     "reflect-metadata": "^0.2.2",
     "source-map-support": "^0.5.13",
     "tailwindcss": "^4.1.12",
@@ -123,6 +136,7 @@
     "typedoc-material-theme": "^1.1.0",
     "typedoc-plugin-pages": "^1.1.0",
     "typescript": "^5.6.2",
+    "typescript-eslint": "^8.51.0",
     "zod": "^4.0.17"
   },
   "typings": "dist/universal/index.d.ts",
@@ -136,15 +150,33 @@
     "index.d.ts",
     "node",
     "README.md",
-    "AI.md",
+    "readmes/AI.md",
     "LICENSE.md"
   ],
   "license": "MIT",
   "dependencies": {
-    "@bluelibs/ejson": "^1.5.0",
     "lru-cache": "^11.1.0"
   },
   "optionalDependencies": {
-    "busboy": "^1.6.0"
+    "amqplib": "^0.10.9",
+    "busboy": "^1.6.0",
+    "cron-parser": "^5.4.0",
+    "ioredis": "^5.7.0"
+  },
+  "prettier": {
+    "trailingComma": "all",
+    "tabWidth": 2,
+    "singleQuote": false,
+    "endOfLine": "auto",
+    "overrides": [
+      {
+        "files": [
+          "*.ts"
+        ],
+        "options": {
+          "parser": "babel-ts"
+        }
+      }
+    ]
   }
 }

package/readmes/AI.md

@@ -0,0 +1,534 @@
+# BlueLibs Runner: Fluent Builder Field Guide
+
+> Token-friendly guide spotlighting the fluent builder API (`r.*`). Classic `defineX` / `resource({...})` remain supported for backwards compatibility.
+
+For the landing overview, see [README.md](../README.md). For the complete guide, see [FULL_GUIDE.md](./FULL_GUIDE.md).
+
+**Durable Workflows (Node-only):** For persistence and crash recovery, see `DURABLE_WORKFLOWS.md`.
+
+## Serializer Safety
+
+When deserializing untrusted payloads, configure the serializer to restrict
+symbol handling so payloads cannot grow the global Symbol registry.
+
+```ts
+import { Serializer, SymbolPolicy } from "@bluelibs/runner";
+
+const serializer = new Serializer({
+  symbolPolicy: SymbolPolicy.WellKnownOnly,
+});
+```
+
+## Resources
+
+```ts
+import express from "express";
+import { r, run, globals } from "@bluelibs/runner";
+import { nodeExposure } from "@bluelibs/runner/node";
+
+const server = r
+  .resource<{ port: number }>("app.server")
+  .context(() => ({ app: express() }))
+  .init(async ({ port }, _deps, ctx) => {
+    ctx.app.use(express.json());
+    const listener = ctx.app.listen(port);
+    return { ...ctx, listener };
+  })
+  .dispose(async ({ listener }) => listener.close())
+  .build();
+
+const createUser = r
+  .task("app.tasks.createUser")
+  .dependencies({ logger: globals.resources.logger })
+  .inputSchema<{ name: string }>({ parse: (value) => value })
+  .resultSchema<{ id: string; name: string }>({ parse: (value) => value })
+  .run(async (input, { logger }) => {
+    await logger.info(`Creating user ${input.name}`);
+    return { id: "user-1", name: input.name };
+  })
+  .build();
+
+const api = r
+  .resource("app.api")
+  .register([
+    server.with({ port: 3000 }),
+    nodeExposure.with({
+      http: { basePath: "/__runner", listen: { port: 3000 } },
+    }),
+    createUser,
+  ])
+  .dependencies({ server, createUser })
+  .init(async (_config, { server, createUser }) => {
+    server.listener.on("listening", () => {
+      console.log("Runner HTTP server ready on port 3000");
+    });
+
+    server.app.post("/users", async (req, res) => {
+      const user = await createUser(req.body);
+      res.json(user);
+    });
+  })
+  .build();
+
+const runtime = await run(api);
+await runtime.runTask(createUser, { name: "Ada" });
+// runtime.dispose() when you are done.
+```
+
+- `r.*.with(config)` produces a configured copy of the definition.
+- `r.*.fork(newId)` creates a new resource with a different id but the same definition—useful for multi-instance patterns. Export forked resources to use as dependencies.
+- `run(root)` wires dependencies, runs `init`, emits lifecycle events, and returns helpers such as `runTask`, `getResourceValue`, and `dispose`.
+- Enable verbose logging with `run(root, { debug: "verbose" })`.
+
+### Resource Forking
+
+Use `.fork(newId)` to clone a resource definition under a new id (handy for multi-instance patterns).
+Forks keep the same implementation/types but get separate runtime instances (no shared state).
+Prefer exporting forks so other tasks/resources can depend on them.
+
+## Tasks
+
+Tasks are your business actions. They are plain async functions with DI, middleware, and validation.
+
+```ts
+import { r } from "@bluelibs/runner";
+
+// Assuming: userService, loggingMiddleware, and tracingMiddleware are defined elsewhere
+const sendEmail = r
+  .task("app.tasks.sendEmail")
+  .inputSchema<{ to: string; subject: string; body: string }>({
+    parse: (value) => value,
+  })
+  .dependencies({ emailer: userService })
+  .middleware([loggingMiddleware.with({ label: "email" }), tracingMiddleware])
+  .run(async (input, { emailer }) => {
+    await emailer.send(input);
+    return { delivered: true };
+  })
+  .build();
+```
+
+**Builder composition rules (applies to tasks, resources, hooks, middleware):**
+
+- `.dependencies()` accepts a literal map or function `(config) => deps`; appends (shallow-merge) by default
+- `.middleware()` appends by default
+- `.tags()` replaces the list each time
+- Pass `{ override: true }` to any of these methods to replace instead of append
+- Provide result validation with `.resultSchema()` when the function returns structured data
+
+## Events and Hooks
+
+Events are strongly typed signals. Hooks listen to them with predictable execution order.
+
+```ts
+import { r } from "@bluelibs/runner";
+
+const userRegistered = r
+  .event("app.events.userRegistered")
+  .payloadSchema<{ userId: string; email: string }>({ parse: (v) => v })
+  .build();
+
+// Type-only alternative (no runtime payload validation):
+// const userRegistered = r.event<{ userId: string; email: string }>("app.events.userRegistered").build();
+
+// Assuming: userService and sendEmail are defined elsewhere
+const registerUser = r
+  .task("app.tasks.registerUser")
+  .dependencies({ userRegistered, userService })
+  .run(async (input, deps) => {
+    const user = await deps.userService.create(input);
+    await deps.userRegistered({ userId: user.id, email: user.email });
+    return user;
+  })
+  .build();
+
+const sendWelcomeEmail = r
+  .hook("app.hooks.sendWelcomeEmail")
+  .on(userRegistered)
+  .dependencies({ mailer: sendEmail })
+  .run(async (event, { mailer }) => {
+    await mailer({
+      to: event.data.email,
+      subject: "Welcome",
+      body: "Welcome!",
+    });
+  })
+  .build();
+```
+
+- Use `.on(onAnyOf(...))` to listen to several events while keeping inference.
+- Hooks can set `.order(priority)`; lower numbers run first. Call `event.stopPropagation()` inside `run` to cancel downstream hooks.
+- Wildcard hooks use `.on("*")` and receive every emission except events tagged with `globals.tags.excludeFromGlobalHooks`.
+- Use `.parallel(true)` on event definitions to enable batched parallel execution:
+  - Listeners with the same `order` run concurrently within a batch
+  - Batches execute sequentially in ascending order priority
+  - All listeners in a failing batch run to completion; if multiple fail, an `AggregateError` with all errors is thrown
+  - Propagation is checked between batches only (not mid-batch since parallel listeners can't be stopped mid-flight)
+  - If any listener throws, subsequent batches will not run
+
+## Middleware
+
+Middleware wraps tasks or resources. Fluent builders live under `r.middleware`.
+
+```ts
+import { r } from "@bluelibs/runner";
+import { globals } from "@bluelibs/runner";
+
+const auditTasks = r.middleware
+  .task("app.middleware.audit")
+  .dependencies({ logger: globals.resources.logger })
+  .everywhere((task) => !task.id.startsWith("admin."))
+  .run(async ({ task, next }, { logger }) => {
+    logger.info(`→ ${task.definition.id}`);
+    const result = await next(task.input);
+    logger.info(`← ${task.definition.id}`);
+    return result;
+  })
+  .build();
+
+const cacheResources = r.middleware
+  .resource("app.middleware.cache")
+  .configSchema<{ ttl: number }>({ parse: (value) => value })
+  .run(async ({ value, next }, _deps, config) => {
+    if (value.current) {
+      return value.current;
+    }
+    const computed = await next();
+    value.current = computed;
+    setTimeout(() => (value.current = null), config.ttl);
+    return computed;
+  })
+  .build();
+```
+
+Attach middleware using `.middleware([auditTasks])` on the definition that owns it, and register the middleware alongside the target resource or task at the root.
+
+- Contract middleware: middleware can declare `Config`, `Input`, `Output` generics; tasks using it must conform (contracts intersect across `.middleware([...])` and `.tags([...])`). Collisions surface as `InputContractViolationError` / `OutputContractViolationError` in TypeScript; if you add `.inputSchema()`, ensure the schema’s inferred type includes the contract shape.
+
+```ts
+type AuthConfig = { requiredRole: string };
+type AuthInput = { user: { role: string } };
+type AuthOutput = { ok: true };
+
+const auth = r.middleware
+  .task<AuthConfig, AuthInput, AuthOutput>("app.middleware.auth")
+  .run(async ({ task, next }) => next(task.input))
+  .build();
+```
+
+### ExecutionJournal
+
+**ExecutionJournal** is a typed key-value store scoped to a single task execution, enabling middleware and tasks to share state. It has **fail-fast semantics**: calling `set()` on an existing key throws an error (prevents silent bugs from middleware clobbering each other). Use `{ override: true }` to intentionally update.
+
+```ts
+import { r, globals, journal } from "@bluelibs/runner";
+
+const abortControllerKey =
+  globals.middleware.task.timeout.journalKeys.abortController;
+
+// Middleware accesses journal via execution input
+const auditMiddleware = r.middleware
+  .task("app.middleware.audit")
+  .run(async ({ task, next, journal }) => {
+    // Access typed values from journal
+    const ctrl = journal.get(abortControllerKey);
+    if (journal.has(abortControllerKey)) {
+      /* ... */
+    }
+    return next(task.input);
+  })
+  .build();
+
+// Task accesses journal via context
+const myTask = r
+  .task("app.tasks.myTask")
+  .run(async (input, deps, { journal }) => {
+    journal.set(abortControllerKey, new AbortController());
+    // To update existing: journal.set(key, newValue, { override: true });
+    return "done";
+  })
+  .build();
+
+// Create custom keys
+const myKey = journal.createKey<{ startedAt: Date }>("app.middleware.timing");
+```
+
+**Built-in Middleware Journal Keys**: Global middlewares (`retry`, `cache`, `circuitBreaker`, `rateLimit`, `fallback`, `timeout`) expose runtime state via typed journal keys at `globals.middleware.task.<name>.journalKeys`. For example, `retry` exposes `attempt` and `lastError`; `cache` exposes `hit`; `circuitBreaker` exposes `state` and `failures`. Access these via `journal.get(key)` without deep imports.
+
+## Tags
+
+Tags let you annotate definitions with metadata that can be queried later.
+
+```ts
+import { r, globals } from "@bluelibs/runner";
+
+const httpRouteTag = r
+  .tag("app.tags.httpRoute")
+  .configSchema<{ method: "GET" | "POST"; path: string }>({
+    parse: (value) => value,
+  })
+  .build();
+
+const getHealth = r
+  .task("app.tasks.getHealth")
+  .tags([httpRouteTag.with({ method: "GET", path: "/health" })])
+  .run(async () => ({ status: "ok" }))
+  .build();
+```
+
+Retrieve tagged items by using `globals.resources.store` inside a hook or resource and calling `store.getTasksWithTag(tag)`.
+
+- Contract tags (a “smart tag”): define type contracts for task input/output (or resource config/value) via `r.tag<TConfig, TInputContract, TOutputContract>(id)`. They don’t change runtime behavior; they shape the inferred types and compose with contract middleware.
+- Smart tags: built-in tags like `globals.tags.system`, `globals.tags.debug`, and `globals.tags.excludeFromGlobalHooks` change framework behavior; use them for per-component debug or to opt out of global hooks.
+
+```ts
+type Input = { id: string };
+type Output = { name: string };
+const userContract = r.tag<void, Input, Output>("contract.user").build();
+
+const getUser = r
+  .task("app.tasks.getUser")
+  .tags([userContract])
+  .run(async (input) => ({ name: input.id }))
+  .build();
+```
+
+## Async Context
+
+Async Context provides per-request/thread-local state via the platform's `AsyncLocalStorage` (Node). Use the fluent builder under `r.asyncContext` or the classic `asyncContext({ ... })` export.
+
+> **Platform Note**: `AsyncLocalStorage` is Node.js-only. Async Context is unavailable in browsers/edge runtimes.
+
+```ts
+import { r } from "@bluelibs/runner";
+
+const requestContext = r
+  .asyncContext<{ requestId: string }>("app.ctx.request")
+  // below is optional
+  .configSchema(z.object({ ... }))
+  .serialize((data) => JSON.stringify(data))
+  .parse((raw) => JSON.parse(raw))
+  .build();
+
+// Provide and read within an async boundary
+await requestContext.provide({ requestId: "abc" }, async () => {
+  const ctx = requestContext.use(); // { requestId: "abc" }
+});
+
+// Require middleware for tasks that need the context
+r.task('task').middleware([requestContext.require()]);
+```
+
+- If you don't provide `serialize`/`parse`, Runner uses its default serializer to preserve Dates, RegExp, etc.
+- You can also inject async contexts as dependencies; the injected value is the helper itself. Contexts must be registered to be used.
+
+```ts
+const whoAmI = r
+  .task("app.tasks.whoAmI")
+  .dependencies({ requestContext })
+  .run(async (_input, { requestContext }) => requestContext.use().requestId)
+  .build();
+
+const app = r.resource("app").register([requestContext, whoAmI]).build();
+```
+
+## Errors
+
+Define typed, namespaced errors with a fluent builder. Built helpers expose `throw` and `is`:
+
+```ts
+import { r } from "@bluelibs/runner";
+
+// Fluent builder
+const AppError = r
+  .error<{ code: number; message: string }>("app.errors.AppError")
+  .dataSchema({ parse: (value) => value })
+  .build();
+
+try {
+  AppError.throw({ code: 400, message: "Oops" });
+} catch (err) {
+  if (AppError.is(err)) {
+    // Do something
+  }
+}
+```
+
+- The thrown `Error` has `name = id` and `message = format(data)`. If you don’t provide `.format(...)`, the default is `JSON.stringify(data)`.
+- `message` is not required in the data unless your custom formatter expects it.
+- Declare a task/resource error contract with `.throws([AppError])` (or ids). This is declarative only and does not imply DI.
+
+## Overrides
+
+Override a task/resource/hook/middleware while preserving `id`. Use the helper or the fluent override builder:
+
+```ts
+const mockMailer = r
+  .override(realMailer)
+  .init(async () => new MockMailer())
+  .build();
+
+const app = r
+  .resource("app")
+  .register([realMailer])
+  .overrides([mockMailer])
+  .build();
+```
+
+- `r.override(base)` starts from the base definition and applies fluent mutations using the same composition rules as the base builder.
+- Hook overrides keep the same `.on` target; only behavior/metadata is overridable.
+- The `override(base, patch)` helper remains for direct, shallow patches.
+
+## Runtime & Lifecycle
+
+- `run(root, options)` wires dependencies, initializes resources, and returns helpers: `runTask`, `emitEvent`, `getResourceValue`, `store`, `logger`, and `dispose`.
+- Run options highlights: `debug` (normal/verbose or custom config), `logs` (printThreshold/strategy/buffer), `errorBoundary` and `onUnhandledError`, `shutdownHooks`, `dryRun`.
+- Task interceptors: inside resource init, call `deps.someTask.intercept(async (next, input) => next(input))` to wrap a single task execution at runtime (runs inside middleware; won’t run if middleware short-circuits).
+- Shutdown hooks: install signal listeners to call `dispose` (default in `run`).
+- Unhandled errors: `onUnhandledError` receives a structured context (kind and source) for telemetry or controlled shutdown.
+
+## Reliability & Performance
+
+- **Concurrency**: Limit parallel execution using a shared or local `Semaphore`.
+  ```ts
+  .middleware([globals.middleware.task.concurrency.with({ limit: 5 })])
+  ```
+- **Circuit Breaker**: Trip after failures to prevent cascading downstream pressure.
+  ```ts
+  .middleware([globals.middleware.task.circuitBreaker.with({ failureThreshold: 5, resetTimeout: 30000 })])
+  ```
+- **Rate Limit**: Protect APIs with fixed-window request counting.
+  ```ts
+  .middleware([globals.middleware.task.rateLimit.with({ windowMs: 60000, max: 100 })])
+  ```
+- **Temporal (Debounce/Throttle)**: Control execution frequency.
+  ```ts
+  .middleware([globals.middleware.task.debounce.with({ ms: 300 })])
+  ```
+- **Fallback**: Provide a Plan B (value, function, or another task) when the primary fails.
+  ```ts
+  // Recommended: Fallback should be outer (on top) of Retry to catch final failures
+  .middleware([
+    globals.middleware.task.fallback.with({ fallback: "Guest User" }),
+    globals.middleware.task.retry.with({ attempts: 3 })
+  ])
+  ```
+- **Retry/Backoff**: `globals.middleware.task.retry` and `globals.middleware.resource.retry` for transient failures.
+  ```ts
+  .middleware([globals.middleware.task.retry.with({ retries: 3 })])
+  ```
+- **Caching**: `globals.middleware.task.cache` plus `globals.resources.cache`.
+  ```ts
+  .middleware([globals.middleware.task.cache.with({ ttl: 60000 })])
+  ```
+- **Timeouts**: `globals.middleware.task.timeout` / `globals.middleware.resource.timeout` using `AbortController`.
+  ```ts
+  .middleware([globals.middleware.task.timeout.with({ ttl: 5000 })])
+  ```
+- **Logging & Debug**: `globals.resources.logger` and `globals.resources.debug`.
+  ```ts
+  // Verbose debug logging for a specific task
+  .tags([globals.tags.debug])
+  ```
+
+## HTTP & Tunnels
+
+Tunnels let you call Runner tasks/events across a process boundary over a small HTTP surface (Node-only exposure via `nodeExposure`), while preserving task ids, middleware, validation, typed errors, and async context.
+
+For “no call-site changes”, register a client-mode tunnel resource tagged with `globals.tags.tunnel` plus phantom tasks for the remote ids; the tunnel middleware auto-routes selected tasks/events to an HTTP client. For explicit boundaries, create a client once and call `client.task(id, input)` / `client.event(id, payload)` directly. Full guide: `readmes/TUNNELS.md`.
+
+Node client note: prefer `createHttpMixedClient` (it uses the serialized-JSON path via Runner `Serializer` + `fetch` when possible and switches to the streaming-capable Smart path when needed). If a task may return a stream even for plain JSON inputs (ex: downloads), set `forceSmart` on Mixed (or use `createHttpSmartClient` directly).
+
+## Serialization
+
+Runner ships with a serializer that round-trips Dates, RegExp, binary, and custom shapes across Node and web.
+
+It also supports:
+
+- `bigint` (encoded as a decimal string under `__type: "BigInt"`)
+- `symbol` for `Symbol.for(key)` and well-known symbols like `Symbol.iterator` (unique `Symbol("...")` values are rejected because identity cannot be preserved)
+
+```ts
+import { r, globals } from "@bluelibs/runner";
+
+const serializerSetup = r
+  .resource("app.serialization")
+  .dependencies({ serializer: globals.resources.serializer })
+  .init(async (_config, { serializer }) => {
+    class Distance {
+      constructor(
+        public value: number,
+        public unit: string,
+      ) {}
+      typeName() {
+        return "Distance";
+      }
+      toJSONValue() {
+        return { value: this.value, unit: this.unit };
+      }
+    }
+
+    serializer.addType(
+      "Distance",
+      (json) => new Distance(json.value, json.unit),
+    );
+  })
+  .build();
+```
+
+Use `getDefaultSerializer()` when you need a standalone instance outside DI.
+
+Note on files: The “File” you see in tunnels is not a custom serializer type. Runner uses a dedicated `$runnerFile: "File"` sentinel in inputs which the tunnel client/server convert to multipart streams via a manifest. File handling is performed by the tunnel layer (manifest hydration and multipart), not by the serializer. Keep using `createWebFile`/`createNodeFile` for uploads.
+
+## Testing
+
+- In unit tests, prefer running a minimal root resource and call `await run(root)` to get `runTask`, `emitEvent`, or `getResourceValue`.
+- The Jest runner has a watchdog (`JEST_WATCHDOG_MS`, default 10 minutes) to avoid "hung test run" situations.
+- For durable workflow tests, use `createDurableTestSetup` from `@bluelibs/runner/node` for fast, in-memory execution.
+
+```ts
+import { run } from "@bluelibs/runner";
+
+test("sends welcome email", async () => {
+  const app = r
+    .resource("spec.app")
+    .register([sendWelcomeEmail, registerUser])
+    .build();
+  const runtime = await run(app);
+  await runtime.runTask(registerUser, { email: "user@example.com" });
+  await runtime.dispose();
+});
+```
+
+## Observability & Debugging
+
+- Pass `{ debug: "verbose" }` to `run` for structured logs about registration, middleware, and lifecycle events.
+- `globals.resources.logger` exposes the framework logger; register your own logger resource and override it at the root to capture logs centrally.
+- Hooks and tasks emit metadata through `globals.resources.store`. Query it for dashboards or editor plugins.
+- Use middleware for tracing (`r.middleware.task("...").run(...)`) to wrap every task call.
+- `Semaphore` and `Queue` publish local lifecycle events through isolated `EventManager` instances (`on/once`). These are separate from the global EventManager used for business-level application events. Event names: semaphore → `queued/acquired/released/timeout/aborted/disposed`; queue → `enqueue/start/finish/error/cancel/disposed`.
+
+## Metadata & Namespacing
+
+- Meta: `.meta({ title, description })` on tasks/resources/events/middleware for human-friendly docs and tooling; extend meta types via module augmentation when needed.
+- Namespacing: keep ids consistent with `domain.resources.name`, `domain.tasks.name`, `domain.events.name`, `domain.hooks.on-name`, and `domain.middleware.{task|resource}.name`.
+- Runtime validation: `inputSchema`, `resultSchema`, `payloadSchema`, `configSchema` share the same `parse(input)` contract; config validation happens on `.with()`, task/event validation happens on call/emit.
+
+## Advanced Patterns
+
+- **Optional dependencies:** mark dependencies as optional (`analytics: analyticsService.optional()`) so the builder injects `null` when the resource is absent.
+- **Conditional registration:** `.register((config) => (config.enableFeature ? [featureResource] : []))`.
+- **Async coordination:** `Semaphore` (O(1) linked queue for heavy contention) and `Queue` live in the main package. Both use isolated EventManagers internally for their lifecycle events, separate from the global EventManager used for business-level application events.
+- **Event safety:** Runner detects event emission cycles and throws an `EventCycleError` with the offending chain.
+- **Internal services:** access `globals.resources.store`, `globals.resources.taskRunner`, and `globals.resources.eventManager` for advanced introspection or custom tooling.
+
+## Interop With Classic APIs
+
+Existing code that uses `resource({ ... })`, `task({ ... })`, or `defineX` keeps working. You can gradually migrate:
+
+```ts
+import { r, resource as classicResource } from "@bluelibs/runner";
+
+const classic = classicResource({ id: "legacy", init: async () => "ok" });
+const modern = r.resource("modern").register([classic]).build();
+```