@bluelibs/runner 4.6.1 → 4.7.0

package/AI.md

@@ -1,4 +1,25 @@
-# BlueLibs Runner: Minimal Guide
+# BlueLibs Runner: Fluent Builder Field Guide
+
+> Token-friendly (<5000 tokens). This guide spotlights the fluent builder API (`r.*`) that ships with Runner 4.x. Classic `defineX` / `resource({...})` remain supported for backwards compatibility, but fluent builders are the default throughout.
+
+## Table of Contents
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Platform Matrix](#platform-matrix)
+- [Fluent Builder Primer](#fluent-builder-primer)
+- [Core Concepts](#core-concepts)
+  - [Resources](#resources)
+  - [Tasks](#tasks)
+  - [Events and Hooks](#events-and-hooks)
+  - [Middleware](#middleware)
+  - [Tags](#tags)
+- [HTTP & Tunnels](#http--tunnels)
+- [Serialization](#serialization)
+- [Testing](#testing)
+- [Observability & Debugging](#observability--debugging)
+- [Advanced Patterns](#advanced-patterns)
+- [Interop With Classic APIs](#interop-with-classic-apis)
+- [Reference Links](#reference-links)
 
 ## Install
 
@@ -6,677 +27,396 @@
 npm install @bluelibs/runner
 ```
 
-## Platform & Browser
+Runner auto-detects its runtime. The Node bundle lives under `@bluelibs/runner/node`; browser helpers are under `@bluelibs/runner/platform`.
 
-- Auto‑detects platform at runtime. In browsers, `exit()` is unsupported and throws. Env reads use `globalThis.__ENV__`, `process.env`, or `globalThis.env`.
+## Quick Start
 
 ```ts
-import { setPlatform, PlatformAdapter } from "@bluelibs/runner/platform";
-setPlatform(new PlatformAdapter("browser"));
-//
-globalThis.__ENV__ = { API_URL: "https://example.test" };
-```
+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");
+    });
 
-## Core Philosophy
+    server.app.post("/users", async (req, res) => {
+      const user = await createUser(req.body);
+      res.json(user);
+    });
+  })
+  .build();
 
-BlueLibs Runner is a **powerful and integrated** framework. It provides a comprehensive set of tools for building robust, testable, and maintainable applications by combining a predictable Dependency Injection (DI) container with a dynamic metadata and eventing system.
+const runtime = await run(api);
+await runtime.runTask(createUser, { name: "Ada" });
+// runtime.dispose() when you are done.
+```
 
-## DI Container Guarantees
+- `r.*.with(config)` produces a configured copy of the definition.
+- `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" })`.
 
-This is the foundation of trust for any DI framework.
+## Platform Matrix
 
-- **Circular Dependencies**: A runtime circular dependency (e.g., `A → B → A`) is a fatal error. The runner **will fail to start** and will throw a descriptive error showing the full dependency chain, forcing you to fix the architecture.
-- **Override Precedence**: Overrides are applied top-down. In case of conflicting overrides for the same `id`, the one defined closest to the root `run()` call wins. The "root is the boss."
+| Capability | Node.js | Browser | Workers (e.g. Cloudflare) |
+| --- | --- | --- | --- |
+| `run()` lifecycle | ✅ | ✅ | ✅ |
+| `nodeExposure`, Node tunnels | ✅ | ❌ | ❌ |
+| `createHttpClient` | ✅ | ✅ | ✅ |
+| Duplex upload (`createHttpSmartClient`) | ✅ | ❌ | ❌ |
+| File helpers (`createNodeFile`, `createWebFile`) | Node only | Browser only | Browser only |
+| Async context (AsyncLocalStorage) | ✅ | n/a | n/a |
 
-## TL;DR
+- Browser environments rely on `globalThis.__ENV__` or `globalThis.env` for configuration; Node uses `process.env`.
+- Runner will throw if you call Node-only helpers in the browser; keep shared code inside `src/` and Node-specific logic under `src/node/`.
 
-- **Lifecycle**: `run() → init resources (deps first) → 'ready' event → dispose() (reverse order)`
-- **Tasks**: Functions with DI and middleware. Flow: `call → middleware → input validation → run() → result validation → return`
-- **Resources**: Managed singletons (init/dispose).
-- **Events**: Decoupled communication. Flow: `emit → validation → find & order hooks → run hooks (stoppable)`
-- **Hooks**: Lightweight event listeners. Async and awaited by default.
-- **Middleware**: Cross-cutting concerns. Async and awaited by default. Optionally contract-enforcing for input/output.
-- **Tags**: Metadata for organizing, filtering, enforcing input/output contracts to tasks or resources.
+## Fluent Builder Primer
 
-## Quick Start
+The fluent API lives under the single `r` namespace:
 
 ```ts
-import express from "express";
-import { resource, task, run } from "@bluelibs/runner";
-
-const server = resource({
-  id: "app.server",
-  // "context" is for private state between init() and dispose()
-  context: () => ({ value: null }),
-  init: async (config: { port: number }, dependencies, ctx) => {
-    ctx.value = "some-value"; // Store private state for dispose()
-
-    const app = express();
-    const server = app.listen(config.port);
-    return { app, server };
-  },
-  dispose: async ({ server }, config, deps, ctx) => server.close(),
-});
-
-const createUser = task({
-  id: "app.tasks.createUser",
-  dependencies: { server },
-  run: async (user: { name: string }, deps) => ({ id: "u1", ...user }),
-});
+import { r } from "@bluelibs/runner";
 
-const app = resource({
-  id: "app",
-  // Resources with configurations must be registered with with() unless the configuration allows all optional
-  // All elements must be registered for them to be used in the system
-  register: [server.with({ port: 3000 }), createUser],
-  dependencies: { server, createUser },
-  init: async (_, { server, createUser }) => {
-    server.app.post("/users", async (req, res) =>
-      res.json(await createUser(req.body)),
-    );
-  },
-});
-
-// Run with optional debug/logs
-// If app had a config app.with(config) for 1st arg
-await run(app, {
-  debug: "normal", // "normal" | "verbose" | DebugConfig
-  logs: { printThreshold: "info", printStrategy: "pretty" },
-});
+const task = r.task("demo.tasks.hello").run(async ({ input }) => input).build();
 ```
 
-## Events & Hooks
+Key rules:
 
-```ts
-import { event, hook, globals } from "@bluelibs/runner";
+- Builders are immutable; every fluent call returns a new builder with tightened typings.
+- Call `.build()` once you finish configuring the definition.
+- `with(config)` clones the built definition with typed config overrides.
+- Use the same pattern across tasks, resources, hooks, middleware, and tags for consistent DX.
 
-const userRegistered = event<{ userId: string; email: string }>({
-  id: "app.events.userRegistered",
-});
+## Core Concepts
 
-const sendWelcome = hook({
-  id: "app.hooks.sendWelcome",
-  on: userRegistered,
-  run: async (e) => console.log(`Welcome ${e.data.email}`),
-});
+### Resources
 
-// Wildcard listener
-const audit = hook({
-  id: "app.hooks.audit",
-  on: "*",
-  run: (e) => console.log(e.id),
-});
-
-// Exclude internal events from "*"
-const internal = event({
-  id: "app.events.internal",
-  tags: [globals.tags.excludeFromGlobalHooks],
-});
-
-// Performance: runtime event emission cycle detection
-// run(app, { runtimeCycleDetection: true }) // To prevent deadlocks from happening.
-```
-
-### Multiple Events per Hook
-
-Listen to multiple events with type-safe common fields:
+Resources encapsulate long-lived values such as database connections or service facades.
 
 ```ts
-const h = hook({
-  id: "app.hooks.multi",
-  on: [event1, event2, event3],
-  run: async (ev) => {
-    // helper utility
-    if (isOneOf(ev, [event1, event2])) {
-      // all common fields from event1 and event2, if just event1, it will be just event1
-    }
-  },
-});
+import { MongoClient } from "mongodb";
+import { r } from "@bluelibs/runner";
+
+const database = r
+  .resource<{ url: string }>("app.resources.database")
+  .init(async ({ url }) => {
+    const client = new MongoClient(url);
+    await client.connect();
+    return client;
+  })
+  .dispose(async (client) => client.close())
+  .build();
+
+const userService = r
+  .resource("app.resources.userService")
+  .dependencies({ database })
+  .init(async (_config, { database }) => ({
+    async create(user: { email: string }) {
+      return database.db().collection("users").insertOne(user);
+    },
+  }))
+  .build();
 ```
 
-### Interception APIs
-
-Low-level interception is available for advanced observability and control:
-
-- `eventManager.intercept((next, event) => Promise<void>)` — wraps event emission
-- `eventManager.interceptHook((next, hook, event) => Promise<any>)` — wraps hook execution
-- `middlewareManager.intercept("task" | "resource", (next, input) => Promise<any>)` — wraps middleware execution
-- `middlewareManager.interceptMiddleware(middleware, interceptor)` — per-middleware interception
+- `context(fn)` gives you a private object that survives `init` → `dispose`.
+- `configSchema` and `resultSchema` accept anything with a `parse()` method (Zod, custom validators).
+- Register resources inside other resources via `.register([...])`. Repeated calls append unless you pass `{ override: true }`.
 
-Prefer task-level `task.intercept()` for application logic; use the above for cross-cutting concerns.
+### Tasks
 
-## Unhandled Errors
-
-By default, unhandled errors are just logged. You can customize this via `run(app, { onUnhandledError })`:
+Tasks are your business actions. They are plain async functions with DI, middleware, and validation.
 
 ```ts
-await run(app, {
-  errorBoundary: true, // Catch process-level errors (default: true)
-  onUnhandledError: async ({ error, kind, source }) => {
-    // kind: "task" | "middleware" | "resourceInit" | "hook" | "process" | "run"
-    // source: optional origin hint (ex: "uncaughtException")
-    await telemetry.capture(error as Error, { kind, source });
-
-    // Optionally decide on remediation strategy
-    if (kind === "process") {
-      // For hard process faults, prefer fast, clean exit after flushing logs
-      await flushAll();
-      process.exit(1);
-    }
-  },
-});
+import { r } from "@bluelibs/runner";
+
+const sendEmail = r
+  .task("app.tasks.sendEmail")
+  .inputSchema<{ to: string; subject: string; body: string }>({
+    parse: (value) => value,
+  })
+  .dependencies({ emailer: userService })
+  .middleware((config) => [
+    loggingMiddleware.with({ label: "email" }),
+    tracingMiddleware,
+  ])
+  .run(async ({ input }, { emailer }) => {
+    await emailer.send(input);
+    return { delivered: true };
+  })
+  .build();
 ```
 
-If you prefer event-driven handling, you can still emit your own custom events from this callback.
+- `.dependencies()` accepts a literal map or a function `(config) => deps`.
+- `.middleware()` appends by default; pass `{ override: true }` to replace. `.tags()` replaces the list each time.
+- `.dependencies()` appends (shallow-merge) by default on resources, tasks, hooks, and middleware; pass `{ override: true }` to replace. Functions and objects are merged consistently.
+- Provide result validation with `.resultSchema()` when the function returns structured data.
 
-## Debug (zero‑overhead when disabled)
+### Events and Hooks
 
-Enable globally at run time:
+Events are strongly typed signals. Hooks listen to them with predictable execution order.
 
 ```ts
-await run(app, { debug: "verbose" }); // "normal" or DebugConfig
+import { r } from "@bluelibs/runner";
+
+const userRegistered = r
+  .event("app.events.userRegistered")
+  .payloadSchema<{ userId: string; email: string }>({ parse: (v) => v })
+  .build();
+
+const registerUser = r
+  .task("app.tasks.registerUser")
+  .dependencies({ userRegistered, userService })
+  .run(async ({ input }, deps) => {
+    const user = await deps.userService.create(input);
+    await deps.userRegistered.emit({ 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: "🎉" });
+  })
+  .build();
 ```
 
-or per‑component via tag:
+- 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`.
 
-```ts
-import { globals, task } from "@bluelibs/runner";
+### Middleware
 
-const critical = task({
-  id: "app.tasks.critical",
-  tags: [globals.tags.debug.with({ logTaskInput: true, logTaskOutput: true })],
-  run: async () => "ok",
-});
-```
-
-## Logger (direct API)
+Middleware wraps tasks or resources. Fluent builders live under `r.middleware`.
 
 ```ts
-import { resource, globals } from "@bluelibs/runner";
-
-const logsExtension = resource({
-  id: "app.logs",
-  dependencies: { logger: globals.resources.logger },
-  init: async (_, { logger }) => {
-    logger.info("test", { example: 123 }); // "trace", "debug", "info", "warn", "error", "critical"
-    const sublogger = logger.with({
-      source: "app.logs",
-      additionalContext: {},
-    });
-    logger.onLog((log) => {
-      // ship or transform
-    });
-  },
-});
+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();
 ```
 
-## AWS Lambda
+Attach middleware using `.middleware([auditTasks])` on the definition that owns it, and register the middleware alongside the target resource or task at the root.
 
-- Cache the runner between warm invocations; do not dispose on each call.
-- Disable shutdown hooks (`shutdownHooks: false`) and enable the error boundary.
-- Provide a request-scoped context per invocation via `createContext`.
-- Parse API Gateway v1/v2 events (handle `requestContext.http.method`/`rawPath` and `httpMethod`/`path`) and base64 bodies.
-- Optionally set `context.callbackWaitsForEmptyEventLoop = false` when using long‑lived connections.
+### Tags
 
-Example outline:
+Tags let you annotate definitions with metadata that can be queried later.
 
 ```ts
-// bootstrap.ts
-import { resource, task, run, createContext } from "@bluelibs/runner";
-export const RequestCtx: any = createContext("app.http.request");
-// define resources & tasks...
-let rrPromise: Promise<any> | null = null;
-export async function getRunner() {
-  if (!rrPromise) {
-    rrPromise = run(app, { shutdownHooks: false, errorBoundary: true });
-  }
-  return rrPromise;
-}
-
-// handler.ts
-export const handler = async (event: any, context: any) => {
-  const rr: any = await getRunner();
-  const method =
-    event?.requestContext?.http?.method ?? event?.httpMethod ?? "GET";
-  const path = event?.rawPath || event?.path || "/";
-  const rawBody = event?.body
-    ? event.isBase64Encoded
-      ? Buffer.from(event.body, "base64").toString("utf8")
-      : event.body
-    : undefined;
-  const body = rawBody ? JSON.parse(rawBody) : undefined;
-
-  return RequestCtx.provide(
-    { requestId: context?.awsRequestId ?? "local", method, path },
-    async () => {
-      // route and call rr.runTask(...)
-    },
-  );
-};
+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();
 ```
 
-## Middleware (global or local)
+Retrieve tagged items by using `globals.resources.store` inside a hook or resource and calling `store.getTasksWithTag(tag)`.
 
-Middleware now supports type contracts with `<Config, Input, Output>` signature:
+## HTTP & Tunnels
 
-```ts
-import {
-  taskMiddleware,
-  resourceMiddleware,
-  resource,
-  task,
-  globals,
-} from "@bluelibs/runner";
-
-// Custom task middleware with type contracts
-const auth = taskMiddleware<
-  { role: string },
-  { user: { role: string } },
-  { user: { role: string; verified: boolean } }
->({
-  id: "app.middleware.auth",
-  run: async ({ task, next }, _, cfg) => {
-    if (task.input?.user?.role !== cfg.role) throw new Error("Unauthorized");
-    const result = await next(task.input);
-    return { user: { ...task.input.user, verified: true } };
-  },
-});
+Run Node exposures and connect to remote Runners with fluent resources.
 
-// Resource middleware can augment a resource's behavior after it's initialized.
-// For example, this `softDelete` middleware intercepts the `delete` method
-// of a resource and replaces it with a non-destructive update.
-const softDelete = resourceMiddleware({
-  id: "app.middleware.softDelete",
-  run: async ({ resource, next }) => {
-    const resourceInstance = await next(resource.config); // The original resource instance
-
-    // This example assumes the resource has `update` and `delete` methods.
-    // A more robust implementation would check for their existence.
-
-    // Monkey-patch the 'delete' method
-    const originalDelete = resourceInstance.delete;
-    resourceInstance.delete = async (id: string, ...args) => {
-      // Instead of deleting, call 'update' to mark as deleted
-      return resourceInstance.update(id, { deletedAt: new Date() }, ...args);
-    };
-
-    return resourceInstance;
-  },
-});
-
-const adminOnly = task({
-  id: "app.tasks.adminOnly",
-  middleware: [auth.with({ role: "admin" })],
-  run: async () => "secret",
-});
-
-// Built-in middleware patterns
-const {
-  task: { retry, timeout, cache },
-  // available: resource: { retry, timeout, cache } as well, same configs.
-} = globals.middleware;
-
-// Example of custom middleware with full type contracts
-const validationMiddleware = taskMiddleware<
-  { strict: boolean },
-  { data: unknown },
-  { data: any; validated: boolean }
->({
-  id: "app.middleware.validation",
-  run: async ({ task, next }, _, config) => {
-    // Validation logic here
-    const result = await next(task.input);
-    return { ...result, validated: true };
+```ts
+import { r, globals } from "@bluelibs/runner";
+import { nodeExposure } from "@bluelibs/runner/node";
+
+const httpExposure = nodeExposure.with({
+  http: {
+    basePath: "/__runner",
+    listen: { host: "0.0.0.0", port: 7070 },
+    auth: { token: process.env.RUNNER_TOKEN },
   },
 });
 
-const resilientTask = task({
-  id: "app.tasks.resilient",
-  middleware: [
-    // Retry with exponential backoff, allow each with timeout
-    retry.with({
-      retries: 3,
-      delayStrategy: (attempt) => 1000 * attempt,
-      stopRetryIf: (error) => error.message === "Invalid credentials",
+const tunnelClient = r
+  .resource("app.tunnels.http")
+  .tags([globals.tags.tunnel])
+  .init(async () => ({
+    mode: "client" as const,
+    transport: "http" as const,
+    tasks: (task) => task.id.startsWith("remote.tasks."),
+    client: globals.tunnels.http.createClient({
+      url: process.env.REMOTE_URL ?? "http://127.0.0.1:7070/__runner",
+      auth: { token: process.env.RUNNER_TOKEN },
     }),
-    // Timeout protection (propose-timeout)
-    timeout.with({ ttl: 10000 }),
-    // Caching first (onion-level)
-    cache.with({
-      ttl: 60000,
-      keyBuilder: (taskId, input) => `${taskId}-${JSON.stringify(input)}`,
-    }),
-  ],
-  run: async () => expensiveApiCall(),
-});
+  }))
+  .build();
 
-// Global middleware
-const globalTaskMiddleware = taskMiddleware({
-  id: "...",
-  everywhere: true, // Use everywhere: (task) => boolean, where true means it gets applied
-  // ... rest as usual ...
-  // if you have dependencies as task, exclude them via everywhere filter.
-});
-
-// Global resource middleware (same everywhere semantics)
-const globalResourceMiddleware = resourceMiddleware({
-  id: "...",
-  everywhere: true, // or: (resource) => boolean
-  run: async ({ next }) => next(),
-});
+const root = r
+  .resource("app")
+  .register([httpExposure, tunnelClient, getHealth])
+  .build();
 ```
 
-## Context (request-scoped values)
+Use the unified HTTP client anywhere:
 
 ```ts
-import { createContext } from "@bluelibs/runner";
-
-const UserCtx = createContext<{ userId: string }>("app.userContext");
+import { createHttpClient } from "@bluelibs/runner";
+import { createFile as createWebFile } from "@bluelibs/runner/platform/createFile";
 
-// In middleware or entry-point
-UserCtx.provide({ userId: "u1" }, async () => {
-  await someTask(); // has access to the context
+const client = createHttpClient({
+  baseUrl: "/__runner",
+  auth: { token: "secret" },
 });
 
-// In a task or hook
-const user = UserCtx.use(); // -> { userId: "u1" }
-
-// In a task definition
-const task = {
-  middleware: [UserCtx.require()], // This middleware works only in tasks.
-};
-```
-
-## System Shutdown & Error Boundary
-
-The framework includes built-in support for graceful shutdowns:
-
-```ts
-const { dispose } = await run(app, {
-  shutdownHooks: true, // Automatically handle SIGTERM/SIGINT (default: true)
-  errorBoundary: true, // Catch unhandled errors and rejections (default: true)
-});
-```
-
-## Type Helpers
+await client.task("app.tasks.getHealth");
 
-Extract generics from tasks, resources, and events without re-declaring their shapes and avoid use of 'any'.
-
-```ts
-import { task, resource, event } from "@bluelibs/runner";
-import type {
-  ExtractTaskInput, // ExtractTaskInput(typeof myTask)
-  ExtractTaskOutput,
-  ExtractResourceConfig,
-  ExtractResourceValue,
-  ExtractEventPayload,
-} from "@bluelibs/runner";
+const file = createWebFile({ name: "notes.txt" }, new Blob(["Hello"]));
+await client.task("app.tasks.upload", { file });
 ```
 
-## Run Options (high‑level)
-
-- debug: "normal" | "verbose" | DebugConfig
-- logs: {
-  - printThreshold?: LogLevel | null;
-  - printStrategy?: "pretty" | "json" | "json-pretty" | "plain";
-  - bufferLogs?: boolean
-- }
-- errorBoundary: boolean (default true)
-- shutdownHooks: boolean (default true)
-- onUnhandledError(error) {}
+- `createHttpSmartClient` (Node only) supports duplex streams.
+- For Node-specific features such as `useExposureContext` for handling aborts and streaming in exposed tasks, see TUNNELS.md.
+- Register authentication middleware or rate limiting on the exposure via middleware tags and filters.
 
-Note: `globals` is a convenience object exposing framework internals:
+## Serialization
 
-- `globals.events` (ready)
-- `globals.resources` (store, taskRunner, eventManager, logger, cache, queue)
-- `globals.middleware` (retry, cache, timeout, requireContext)
-- `globals.tags` (system, debug, excludeFromGlobalHooks)
-
-## Overrides
+Runner ships with an EJSON serializer that round-trips Dates, RegExp, binary, and custom shapes across Node and web.
 
 ```ts
-import { override, resource } from "@bluelibs/runner";
-
-const emailer = resource({ id: "app.emailer", init: async () => new SMTP() });
-const testEmailer = override(emailer, { init: async () => new MockSMTP() });
+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 };
+      }
+    }
 
-const app = resource({
-  id: "app",
-  register: [emailer],
-  overrides: [testEmailer],
-});
+    serializer.addType("Distance", (json) => new Distance(json.value, json.unit));
+  })
+  .build();
 ```
 
-## Namespacing
-
-As your app grows, you'll want consistent naming. Here's the convention that won't drive you crazy:
-
-| Type                | Format                                           |
-| ------------------- | ------------------------------------------------ |
-| Resources           | `{domain}.resources.{resource-name}`             |
-| Tasks               | `{domain}.tasks.{task-name}`                     |
-| Events              | `{domain}.events.{event-name}`                   |
-| Hooks               | `{domain}.hooks.on-{event-name}`                 |
-| Task Middleware     | `{domain}.middleware.task.{middleware-name}`     |
-| Resource Middleware | `{domain}.middleware.resource.{middleware-name}` |
-
-We recommend kebab-case for file names and ids. Suffix files with their primitive type: `*.task.ts`, `*.task-middleware.ts`, `*.hook.ts`, etc.
+Use `getDefaultSerializer()` when you need a standalone instance outside DI.
 
-Folders can look something like this: `src/app/users/tasks/create-user.task.ts`. For domain: `app.users` and a task. Use `middleware/task|resource` for middleware files.
-
-## Factory Pattern
-
-Use a resource to act as a factory for creating class instances. The resource is configured once, and the resulting function can be used throughout the app.
-
-```ts
-const myFactory = resource({
-  id: "app.factories.myFactory",
-  init: async (config: SomeConfigType) => {
-    // The resource's value is a factory function
-    return (input: any) => {
-      return new MyClass(input, config.someOption);
-    };
-  },
-});
-
-const app = resource({
-  id: "app",
-  register: [myFactory.with({ someOption: "configured" })],
-  dependencies: { myFactory },
-  init: async (_, { myFactory }) => {
-    const instance = myFactory({ someInput: "hello" });
-  },
-});
-```
+Note on files: The “File” you see in tunnels is not an EJSON custom type. Runner uses a dedicated $ejson: "File" sentinel in inputs which the tunnel client/server convert to multipart streams via a manifest. We intentionally do not call `EJSON.addType("File", ...)` by default, because file handling is performed by the tunnel layer (manifest hydration and multipart), not by the serializer. Keep using `createWebFile`/`createNodeFile` for uploads; use `EJSON.addType` only for your own domain types.
 
 ## Testing
 
-```ts
-import { resource, run, override } from "@bluelibs/runner";
-
-const app = resource({
-  id: "app",
-  register: [
-    /* tasks/resources */
-  ],
-});
-const harness = resource({
-  id: "test",
-  register: [app],
-  overrides: [
-    /* test overrides */
-  ],
-});
-
-const rr = await run(harness);
-await rr.runTask(id | task, { input: 1 });
-// rr.getResourceValue(id | resource)
-// await rr.emitEvent(event, payload)
-// rr.logger.info("xxx")
-await rr.dispose();
-```
-
-## Pre‑release (alpha)
-
-Publish an alpha without affecting latest:
-
-```bash
-npm version prerelease --preid=alpha
-npm run clean && npm run build
-npm publish --tag alpha --access public
-# consumers: npm i @bluelibs/runner@alpha
-```
-
-Local test without publishing:
-
-```bash
-npm pack  # then in a demo app: npm i ../@bluelibs-runner-<version>.tgz
-# or: npm link / npm link @bluelibs/runner
-```
-
-Coverage tip: the script name is `npm run coverage`.
-
-## Metadata & Tags
+- Use `npm run coverage:ai` to execute the full Jest suite in a token-friendly format. Focused tests can run via `npm run test -- task-name`.
+- In unit tests, prefer running a minimal root resource and call `await run(root)` to get `runTask`, `emitEvent`, or `getResourceValue`.
+- `createTestResource` is available for legacy suites but new code should compose fluent resources directly.
 
-Tags and meta can be applied to all elements.
+Example:
 
 ```ts
-import { tag, globals, task, resource } from "@bluelibs/runner";
+import { run } from "@bluelibs/runner";
 
-const contractTag = tag<void, void, { result: string }>({ id: "contract" });
-const httpRouteTag = tag<{ method: "GET" | "POST"; path: string }>({
-  id: "httpRoute",
-});
-
-const task = task({
-  id: "app.tasks.myTask",
-  tags: [contractTag, httpRouteTag.with({ method: "POST", path: "/do" })],
-  run: async () => ({ result: "ok" }), // must return { result: string }
-  meta: {
-    title: "My Task",
-    description: "Does something important", // multi-line description, markdown
-  },
+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();
 });
 ```
 
-Usage:
-
-```ts
-const onReady = hook({
-  id: "app.hooks.onReady",
-  on: globals.events.ready,
-  dependencies: { store: globals.resources.store },
-  run: async (_, { store }) => {
-    // Same concept for resources
-    const tasks = store.getTasksWithTag(httpRouteTag); // uses httpRouteTag.exists(component);
-    tasks.forEach((t) => {
-      const cfg = httpRouteTag.extract(tasks); // { method, path }
-      // you can even do t
-    });
-  },
-});
-```
+## Observability & Debugging
 
-## Key Patterns & Features
+- 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.
 
-- **Optional Dependencies**: Gracefully handle missing services by defining dependencies as optional. The dependency will be `null` if not registered.
-  `dependencies: { analytics: analyticsService.optional() }`
+## Advanced Patterns
 
-- **Stop Propagation**: Prevent other hooks from running for a specific event.
-  `// inside a hook`
-  `event.stopPropagation()`
+- **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` and `Queue` live in the main package.
+- **Event safety:** Runner detects event emission cycles and throws an `EventCycleError` with the offending chain.
 
-That’s it. Small surface area, strong primitives, great DX.
+## Interop With Classic APIs
 
-## Concurrency: Semaphore & Queue
+Existing code that uses `resource({ ... })`, `task({ ... })`, or `defineX` keeps working. You can gradually migrate:
 
 ```ts
-import { Semaphore, Queue } from "@bluelibs/runner";
-
-// Semaphore: limit parallelism
-const dbSem = new Semaphore(5);
-const users = await dbSem.withPermit(async () =>
-  db.query("SELECT * FROM users"),
-);
-
-// Queue: FIFO with cooperative cancellation
-const queue = new Queue();
-const result = await queue.run(async (signal) => {
-  signal.throwIfAborted();
-  return await doWork();
-});
-await queue.dispose({ cancel: true });
-```
-
-## Handling Circular Types (even if runtime is fine)
-
-Rarely, when TypeScript struggles with circular type inference, break the chain with an explicit interface:
-
-```ts
-import type { IResource } from "@bluelibs/runner";
+import { r, resource as classicResource } from "@bluelibs/runner";
 
-export const cResource = resource({
-  id: "c.resource",
-  dependencies: { a: aResource },
-  init: async (_, { a }) => `C depends on ${a}`,
-}) as IResource<void, string>; // void config, returns string
+const classic = classicResource({ id: "legacy", init: async () => "ok" });
+const modern = r.resource("modern").register([classic]).build();
 ```
 
-## Validation (optional and library‑agnostic)
-
-## Event Cycle Safety
-
-To prevent event‑driven deadlocks, the runner detects cycles during emission:
-
-- A cycle occurs when an event emits another event that eventually re‑emits the original event within the same emission chain (for example: `e1 -> e2 -> e1`).
-- When a cycle is detected, an `EventCycleError` is thrown with a readable chain to help debugging.
-- A hook re‑emitting the same event it currently handles is allowed only when the emission originates from the same hook instance (useful for idempotent/no‑op retries); other cases are blocked.
-
-Guidance:
+Fluent builders produce the exact same runtime definitions, so you can mix both styles within one project.
 
-- Prefer one‑way flows; avoid mutual cross‑emits between hooks.
-- Use `event.stopPropagation()` to short‑circuit handlers when appropriate.
-- Use tags (for example, `globals.tags.excludeFromGlobalHooks`) to scope listeners and avoid unintended re‑entry via global hooks.
+## Reference Links
 
-Interface any library can implement:
-
-```ts
-interface IValidationSchema<T> {
-  parse(input: unknown): T;
-}
-```
-
-Works out of the box with Zod (`z.object(...).parse`), and can be adapted for Yup/Joi with small wrappers. As it only needs a parse() method.
-
-```ts
-import { z } from "zod";
-
-// Task input/result validation
-const inputSchema = z.object({ email: z.string().email() });
-const resultSchema = z.object({ id: z.string(), email: z.string().email() });
-
-task({
-  // ...
-  inputSchema, // validates before run
-  resultSchema, // validates awaited return
-});
-
-resource({
-  configSchema, // Resource config validation (runs on .with())
-  resultSchema, // Runs after initialization
-});
-
-event({
-  payloadSchema, // Runs on event emission
-});
-
-tag({
-  configSchema, // Tag config validation (runs on .with())
-});
-
-// Middleware config validation (runs on .with())
-middleware({
-  // ...
-  configSchema, // runs on .with()
-});
-```
+- `readmes/FLUENT_BUILDERS.md` – deep dive into fluent APIs.
+- `readmes/TUNNELS.md` – streaming, authentication, deployment tips.
+- `README.md` – project overview and additional examples.
+- `AI.md` (this file) – copy/paste friendly summary.
+- `MULTIPLATFORM.md` – cross-platform gotchas and recommended structure.