@nwire/hooks 0.7.1 → 0.8.0

package/README.md

@@ -1,57 +1,687 @@
 # @nwire/hooks
 
-> Universal dispatch primitive. One `hook()` accepts both `.use()` (sequential chain) and `.on()` (parallel listener) attachments.
+> The universal dispatch primitive. Every middleware, lifecycle phase, event
+> subscription, plugin extension, and dev-tool tap in Nwire is built from one
+> shape: a named hook that runs a koa-compose chain first, then fans out
+> parallel listeners. Auditable, traceable, replayable, topology-aware.
 
-## What it is
+```bash
+pnpm add @nwire/hooks
+```
 
-Every middleware, lifecycle phase, event subscription, and plugin attachment in Nwire is built from one primitive: a named hook that runs a koa-compose chain first, then a parallel listener fan-out via `Promise.allSettled`. Built on [emittery](https://github.com/sindresorhus/emittery) (~3KB) plus a ~30 LOC composer. No other Nwire package required.
+---
 
-## Install
+## TL;DR
 
-```bash
-pnpm add @nwire/hooks
+```ts
+import { hook } from "@nwire/hooks";
+
+const request = hook<{ url: string; user?: string }>("http.request");
+
+request.use(async (ctx, next) => { ctx.user = await auth(ctx); await next(); });
+request.use(async (ctx, next) => { /* metrics */ await next(); }, { priority: 100 });
+request.on((ctx) => analytics.track(ctx), { when: "success" });
+
+await request.run({ url: "/api/x" });
+```
+
+Two attachment kinds, one primitive:
+
+- **`.use(fn)`** — chain step. koa-compose-shaped `(ctx, next)`. Can mutate ctx.
+  Can short-circuit by not calling `next()`. Throws bubble up.
+- **`.on(fn)`** — listener. Observer `(ctx)`. Cannot mutate. Cannot bail.
+  Fired in parallel via `Promise.allSettled` after the chain settles.
+
+Everything else — telemetry taps, source capture, run-id linkage, recording,
+priorities, success/failure filters — sits on top of those two without
+changing them.
+
+---
+
+## Why this exists
+
+The Nwire stack used to ship six overlapping middleware/hook substrates —
+one per package, each with its own composer, error policy, and observability
+story. `@nwire/hooks` is the single primitive they all reduce to:
+
+| Substrate                                    | Maps to                                                |
+| -------------------------------------------- | ------------------------------------------------------ |
+| `@nwire/handler` `defineMiddleware` + `pipe` | chain via `.use()`                                     |
+| `@nwire/handler` `defineHook("after", fn)`   | listener via `.on(fn, { when: "success" })`            |
+| `@nwire/forge` `runtime.use(mw)`             | chain via `.use()` on the dispatch hook                |
+| `@nwire/http` `httpInterface().use()`        | chain via `.use()` on the http-request hook            |
+| `@nwire/http` per-route `middleware: […]`    | per-route hook + chain                                 |
+| `definePlugin({ middleware, actorHooks })`   | chain (middleware) + listener (actorHooks)             |
+| `definePlugin({ before, after })`            | chain veto (`before`) + filtered listener (`after`)    |
+| `@nwire/app` framework events — `parallel`   | listener fan-out                                       |
+| `@nwire/app` framework events — `series`     | chain without bail                                     |
+| `@nwire/app` framework events — `series-bail`| chain with `.runDetailed()` reading `outcome === "prevented"` |
+
+If you're building a new extension point: it's a hook.
+
+---
+
+## The contract — behavior matrix
+
+| Question                                              | Answer                                                                                          |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Chain ordering                                        | Higher `priority` first (outermost). Stable on ties — equal priority preserves insertion order. |
+| Listener ordering                                     | Higher `priority` first. Listeners run in parallel; ordering is *attempt* order only.           |
+| What if a chain step doesn't call `next()`?           | Chain short-circuits. `outcome === "prevented"`. Listeners still fire (subject to `when`).      |
+| What if a chain step throws?                          | `.run()` rejects with the error. `outcome === "failed"`. Listeners still fire (subject to `when`). `ctx.error` is set. |
+| What if a listener throws?                            | Reported via `onListenerError` (default: `console.error`). The run does **not** fail. Opt in with `strictListeners: true`. |
+| Can a listener cancel the run?                        | No.                                                                                              |
+| Can a chain step mutate ctx?                          | Yes. Listeners see the post-chain ctx.                                                          |
+| Can listeners run before the chain finishes?          | No.                                                                                              |
+| Is `next()` allowed to be called twice?               | No — throws `Error("next() called multiple times in @nwire/hooks chain")`.                       |
+| Are taps observers or participants?                   | Observers. Tap throws are swallowed.                                                            |
+| Run-id propagation across nested `.run()` calls?     | Automatic via `AsyncLocalStorage`. Inner run's `parentRunId` = outer run's `runId`.             |
+| Is recording side-effect free?                        | No — it executes the hook normally and snapshots ctx before + after. Replay re-executes the chain. |
+
+---
+
+## Core API
+
+### `hook(name, options?)`
+
+```ts
+import { hook } from "@nwire/hooks";
+
+const lifecycle = hook<EndpointCtx>("endpoint.boot", {
+  strictListeners: false,                   // default
+  onListenerError: (err, ctx, hookName) => logger.error(...),
+});
+```
+
+Creates a fresh hook. Captures the call-site source location for Studio +
+`nwire scan`. Adds it to the process-wide registry so `listHooks()` sees it.
+
+### `Hook<Ctx>` surface
+
+```ts
+interface Hook<Ctx> {
+  readonly name: string;
+  readonly id:   string;                              // process-unique
+
+  use(fn: ChainFn<Ctx>,   opts?: UseOptions): this;   // chain step
+  on (fn: ListenerFn<Ctx>, opts?: OnOptions):  this;  // listener
+  off(fn): this;                                       // detach
+
+  run(ctx: Ctx, opts?: RunOptions): Promise<Ctx>;
+  runDetailed(ctx, opts?): Promise<RunResult<Ctx>>;
+
+  tap(observer): () => void;                           // per-step trace
+  stepCounts(): { chain: number; listeners: number };
+}
+```
+
+#### `UseOptions` / `OnOptions`
+
+```ts
+interface UseOptions {
+  name?:     string;       // human label — shown in taps, OTel, Studio
+  priority?: number;       // higher = earlier in chain (default 0)
+}
+interface OnOptions extends UseOptions {
+  when?: "always" | "success" | "failure";   // default "always"
+}
+```
+
+#### `RunOptions`
+
+```ts
+interface RunOptions {
+  signal?:      AbortSignal;   // injects onto ctx.signal too; thrown if aborted before next step
+  parentRunId?: string;        // override the ambient parent
+}
+```
+
+#### `RunResult<Ctx>`
+
+```ts
+interface RunResult<Ctx> {
+  ctx:           Ctx;
+  outcome:       "completed" | "prevented" | "failed";
+  runId:         string;
+  parentRunId?:  string;
+  steps:         StepObservation[];
+  durationMs:    number;
+  error?:        unknown;     // set when outcome === "failed"
+}
+```
+
+`run(ctx)` is the simple form. It returns the (mutated) ctx and throws on
+failure — the way every existing call site has worked for years.
+`runDetailed(ctx)` returns the structured result instead. Use it when you
+need the outcome distinction (e.g. framework events that need to know
+"was this prevented?").
+
+### `compose(fns)` / `pipe(...fns)` / `withTimeout(ms, fn)` / `withRetry(opts, fn)`
+
+Helpers for assembling reusable chain pieces before attaching them to a hook.
+
+```ts
+import { pipe, withRetry, withTimeout } from "@nwire/hooks";
+
+const protected = pipe(
+  authenticate,
+  withRetry({ attempts: 3, delayMs: 100 }, callExternalApi),
+  withTimeout(5_000, persistResult),
+);
+hook.use(protected);
+```
+
+---
+
+## Observability — what every hook surfaces for free
+
+Every hook emits a stream of `StepObservation` events. Subscribe with
+`.tap(observer)` to wire it into:
+
+- structured logs (`logger.info(obs)`)
+- Studio Live (push over SSE)
+- `nwire scan` (write to `.nwire/observations.json`)
+- OTel adapter (one span per `start → end` pair)
+
+```ts
+interface StepObservation {
+  hookName:     string;
+  hookId:       string;
+  runId:        string;
+  parentRunId?: string;
+  stepId:       number;
+  stepKind:     "chain" | "listener";
+  stepName?:    string;       // from UseOptions.name / OnOptions.name
+  phase:        "start" | "end" | "error";
+  ts:           number;       // performance.now()
+  durationMs?:  number;       // set on end + error
+  error?:       unknown;      // set on error
+}
+```
+
+### Topology — caller / callee linkage
+
+`AsyncLocalStorage` propagates the active `runId` through the chain. When
+your chain step calls `await otherHook.run(...)`, the nested run picks up
+the outer `runId` as its `parentRunId` automatically — no plumbing.
+
+```ts
+import { hook, currentRun } from "@nwire/hooks";
+
+const outer = hook<{}>("outer");
+const inner = hook<{}>("inner");
+
+outer.use(async (_, next) => {
+  await inner.run({});           // inner's parentRunId === outer's runId
+  await next();
+});
+
+inner.use(async () => {
+  console.log(currentRun());     // { runId, hookId, parentRunId }
+});
+```
+
+This is the substrate Studio's Trace page uses to render the causal tree.
+
+### Source location
+
+`hook()` captures its call site at construction. `listHooks()` exposes it
+to `nwire scan` and Studio so every hook in the manifest has a click-to-open
+pill — same UX as actions/events/projections.
+
+```ts
+import { listHooks } from "@nwire/hooks";
+
+console.log(listHooks());
+// [
+//   { id: "h1", name: "endpoint.boot", chain: 2, listeners: 1, source: { file, line } },
+//   { id: "h2", name: "http.request",  chain: 4, listeners: 0, source: { file, line } },
+// ]
+```
+
+### Recording + replay
+
+```ts
+import { record, replay } from "@nwire/hooks";
+
+// Production: capture the full trace from one run.
+const recording = await record(myHook, ctx);
+await fetch("/__nwire/recordings", { method: "POST", body: JSON.stringify(recording) });
+
+// Dev / debug: replay against the same hook and assert on drift.
+const result = await replay(myHook, recording);
+if (!result.matches) console.warn("drift:", result.drift);
+```
+
+`record` runs the hook once, snapshots `ctxIn`/`ctxOut` (via `structuredClone`
+by default), and returns a self-contained, JSON-serializable trace. `replay`
+re-runs the hook with the captured `ctxIn` (cloned) and compares step
+sequences — flagging drift in step count, names, order, or outcome.
+
+This is observational, not stubbing. Pure / idempotent chains match
+deterministically; non-deterministic chains report exactly what diverged.
+
+---
+
+## Consumer APIs — the surfaces every nwire package presents
+
+This is the locked-in contract each downstream package exposes to its users.
+Internally they all reduce to `hook()`, but the public API stays familiar
+and ergonomic. This table is the source of truth — anything outside it is
+not a public API of that package.
+
+### `@nwire/forge`
+
+```ts
+// Runtime dispatch middleware — onion around every action handler.
+runtime.use(mw: DispatchMiddleware): void;
+type DispatchMiddleware = (
+  next: () => Promise<EventMessage | EventMessage[] | void>,
+  action: ActionDefinition,
+  input: unknown,
+  ctx: HandlerContext,
+) => Promise<EventMessage | EventMessage[] | void>;
+// → forge.action.dispatch hook · chain · priority by registration order
+
+// Actor transition hook — observable, fires after every state change.
+runtime.actorHook(fn: ActorTransitionHook): void;
+type ActorTransitionHook = (
+  actor: ActorDefinition,
+  key: string,
+  fromState: string,
+  toState: string,
+  event: EventMessage,
+  envelope: MessageEnvelope,
+) => Promise<void> | void;
+// → forge.actor.transition hook · listener · when=always
+```
+
+### `@nwire/forge` — plugin builder (closure form)
+
+```ts
+definePlugin("name", ({ bind, resolve, on, before, after, middleware, actorHook, boot, shutdown }) => {
+  // — Generic framework event subscription.
+  on<TPayload>(event, handler, priority?): void;
+  //   → underlying framework-event hook · chain or listener per event.mode
+
+  // — Action-scoped sugar.
+  before(actionName, fn): void;
+  //   fn returns void | false. false short-circuits ("prevented"); throw fails.
+  //   → action.before:<name> hook · chain · use+next bail
+  after(actionName, fn): void;
+  //   fn observes result + durationMs. Errors logged, not fatal.
+  //   → action.after:<name> hook · listener · when=success
+
+  // — Dispatch middleware (same shape as runtime.use).
+  middleware(mw: DispatchMiddleware): void;
+  //   → forge.action.dispatch hook · chain
+
+  // — Actor transitions (same shape as runtime.actorHook).
+  actorHook(fn: ActorTransitionHook): void;
+  //   → forge.actor.transition hook · listener
+
+  // — Plugin lifecycle. Run order = registration; shutdown is reverse.
+  boot(fn: () => Promise<void> | void): void;
+  shutdown(fn: () => Promise<void> | void): void;
+});
+```
+
+### `@nwire/app` — framework events (3 dispatch modes)
+
+```ts
+// Subscribe (priority desc; default 0).
+bus.on(event, handler, priority?): () => void;
+
+// Fire. Returns false only when a series-bail handler vetoed.
+bus.fire(event, payload): Promise<boolean>;
+
+// Per-firing observer — sees every event, cannot veto. For dev-logger,
+// Studio Live, OTel.
+bus.onFire(observer): () => void;
+type FrameworkEventObservation = {
+  eventName: string;
+  payload:   unknown;
+  mode:      "parallel" | "series" | "series-bail";
+  phase:     "fired" | "prevented";
+  ts:        string;
+};
+
+// Modes — set when defining the event.
+defineFrameworkEvent<TPayload>(name, mode: "parallel" | "series" | "series-bail");
+//   parallel    → listener fan-out (Promise.allSettled, errors logged)
+//   series      → chain without bail (sequential await; throw stops)
+//   series-bail → chain with bail (sequential await; return false short-circuits)
+```
+
+### `@nwire/handler` — resolver middleware
+
+```ts
+defineMiddleware(name?, fn: (ctx, next) => Promise<void> | void): MiddlewareDefinition;
+//   → resolver hook · chain
+
+defineHook("before", name?, fn: (ctx) => Promise<void> | void): HookDefinition;
+//   → resolver hook · listener · when=always · runs before handler
+defineHook("after",  name?, fn: (ctx, result) => Promise<void> | void): HookDefinition;
+//   → resolver hook · listener · when=success · runs after handler
+
+pipe(...steps: PipeStep[]): MiddlewarePipe;
+//   compose middlewares + hooks; transports unwind into chain + listeners
+```
+
+### `@nwire/http` — request pipeline
+
+```ts
+httpInterface(opts?)
+  .use(mw: KoaMiddleware): this;
+  //   → http.request hook · chain · global to this interface
+  .provide(container): this;
+  .wire(route: RouteBinding, handler: HttpHandler): this;
+  //   per-route middleware lives on the binding:
+  //   route = post("/path", { body, middleware: [mw1, mw2], openapi })
+  //   → http.request:<METHOD> <path> hook · chain · scoped to this route
+  .compile(): KoaApp;
+  .toExpress(): ExpressMiddleware;
+```
+
+### `@nwire/auth` — canonical resolvers + middleware
+
+```ts
+// All canonical auth operations are resolvers (SignIn, SignOut, Refresh,
+// Register, Me) and run through the @nwire/handler pipeline above.
+identityPlugin({ adapter, scopes? }): PluginDefinition;
+//   contributes:
+//     middleware  → forge.action.dispatch · chain · enriches ctx.envelope.user
+//     resolvers   → /auth/*
+```
+
+### `@nwire/rbac`
+
+```ts
+defineAbility((user, { allow, deny }) => { ... }): AbilityFactory;
+rbacPlugin({ ability }): PluginDefinition;
+//   contributes:
+//     middleware  → forge.action.dispatch · chain · enforces action.policy
+
+// Resolver-level:
+can(action: string, subject: string | Subject): MiddlewareDefinition;
+```
+
+### `@nwire/observability` (tracing + auth-as-plugin)
+
+```ts
+tracingPlugin({ tracer? }): PluginDefinition;
+//   wires OTel via .tap() on the dispatch + framework-event hooks.
+
+// Application code rarely calls hooks directly — observability plugs in
+// at boot, taps every hook in listHooks(), and emits spans / logs.
+```
+
+### Test surface — `@nwire/test-kit`
+
+```ts
+const harness = createTestHarness({ app });
+// Every hook the app creates is .tap()-able through harness.observe():
+harness.observe(hookName, (obs) => { ... });
+// Recordings can be captured + diffed in tests:
+const rec = await harness.record(hookName, ctx);
+expect(rec.steps.map((s) => s.stepName)).toEqual([...]);
+```
+
+### Studio + scan
+
+`nwire scan` emits `.nwire/hooks.json`:
+
+```json
+[
+  { "id": "h1", "name": "forge.action.dispatch",  "chain": 4, "listeners": 0, "source": { "file": "...", "line": 12 } },
+  { "id": "h2", "name": "nwire.app.booting",      "chain": 2, "listeners": 0, "source": { "file": "...", "line": 8  } },
+  { "id": "h3", "name": "action.after:CreateStation", "chain": 0, "listeners": 2, "source": { "file": "...", "line": 23 } }
+]
+```
+
+Studio surfaces a **Hooks** page that lists these with source pills, a per-hook
+inspector showing attached chain + listeners with their names + priorities,
+and a Trace mode that overlays live `.tap()` observations onto the causation
+tree using `runId` / `parentRunId`.
+
+---
+
+## Recipes — wiring the substrate
+
+### 1. Forge — `runtime.use(middleware)`
+
+```ts
+const dispatch = hook<DispatchCtx>("forge.action.dispatch");
+
+dispatch.use(async (ctx, next) => {
+  const span = tracer.startSpan(ctx.action.name);
+  try { await next(); span.end(); } catch (err) { span.recordException(err); throw err; }
+}, { name: "tracing", priority: 100 });
+
+// `runtime.use(mw)` is sugar:
+runtime.use = (mw) => dispatch.use(adaptDispatchMiddleware(mw));
+```
+
+### 2. HTTP — global `.use()` + per-route `middleware: [...]`
+
+```ts
+const httpRequest = hook<KoaCtx>("http.request");                    // global
+const routeRequest = (route) =>
+  hook<KoaCtx>(`http.request:${route.method} ${route.path}`);        // per route
+
+httpRequest.use(cors());
+httpRequest.use(bodyParser());
+const routeHook = routeRequest(route);
+for (const mw of route.middleware) routeHook.use(mw);
+routeHook.use(invokeHandler(route));
+
+// At dispatch:
+await httpRequest.run(ctx);
+await routeHook.run(ctx);
+```
+
+### 3. Handler — `defineMiddleware` + `defineHook("after", ...)`
+
+```ts
+// Migrate:
+const authenticate = defineMiddleware(async (ctx, next) => { ... });
+const auditLog     = defineHook("after", async (ctx, result) => { ... });
+
+// To:
+resolverHook.use(authenticate.fn, { name: "authenticate" });
+resolverHook.on((ctx) => auditLog.fn(ctx, ctx.result), { when: "success", name: "audit-log" });
+```
+
+### 4. Plugin — `before(actionName, fn)` (series-bail)
+
+```ts
+const beforeAction = hook<BeforeCtx>("action.before:" + actionName);
+
+beforeAction.use(async (ctx, next) => {
+  const allowed = await fn(ctx);
+  if (allowed === false) return;     // short-circuit -> outcome "prevented"
+  await next();
+});
+
+// Dispatch:
+const result = await beforeAction.runDetailed(ctx);
+if (result.outcome === "prevented") return /* skip the action */;
+```
+
+### 5. Plugin — `after(actionName, fn)` (parallel observer, success-only)
+
+```ts
+const afterAction = hook<AfterCtx>("action.after:" + actionName);
+afterAction.on(fn, { when: "success", name: actionName + ":after" });
+```
+
+### 6. Plugin — `actorHooks.afterTransition`
+
+```ts
+const actorTransition = hook<TransitionCtx>("actor.transition");
+actorTransition.on((ctx) => userHook(ctx.actor, ctx.key, ctx.from, ctx.to, ctx.event));
+
+// runtime emits on every transition:
+await actorTransition.run({ actor, key, from, to, event, envelope });
 ```
 
-## Within nwire-app
+### 7. App framework events — three modes
 
-For developers using this package as part of the Nwire stack. You usually never call `hook()` yourself — `@nwire/app` lifecycle, `@nwire/forge` events, and every plugin's middleware all build on it. Touch this package when authoring a plugin that needs custom hooks.
+```ts
+const ev = hook<Payload>("nwire.app.booting", {
+  // strictListeners=false matches "parallel mode" — handler errors are logged.
+  strictListeners: false,
+});
+
+// parallel:
+ev.on(handler, { priority });
+
+// series:
+ev.use(async (ctx, next) => { await handler(ctx); await next(); }, { priority });
+
+// series-bail:
+ev.use(async (ctx, next) => {
+  const ret = await handler(ctx);
+  if (ret === false) return;        // short-circuit
+  await next();
+}, { priority });
+
+const r = await ev.runDetailed(payload);
+const prevented = r.outcome === "prevented";
+```
+
+### 8. Studio / scan integration
+
+```ts
+import { listHooks } from "@nwire/hooks";
+
+// scan emits per-hook metadata to .nwire/hooks.json
+const manifest = listHooks().map((h) => ({
+  id: h.id, name: h.name, chain: h.chain, listeners: h.listeners, source: h.source,
+}));
+```
+
+### 9. OTel adapter
+
+```ts
+import { trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("nwire");
+const spans = new Map<string, ReturnType<typeof tracer.startSpan>>();
+
+myHook.tap((obs) => {
+  const key = `${obs.runId}:${obs.stepId}:${obs.stepKind}`;
+  if (obs.phase === "start") {
+    spans.set(key, tracer.startSpan(`${obs.hookName}.${obs.stepName ?? obs.stepKind}`));
+  } else if (obs.phase === "end") {
+    spans.get(key)?.end(); spans.delete(key);
+  } else if (obs.phase === "error") {
+    const s = spans.get(key);
+    if (s) { s.recordException(obs.error as Error); s.end(); spans.delete(key); }
+  }
+});
+```
+
+### 10. Structured logger tap
+
+```ts
+myHook.tap((obs) => {
+  logger.debug({
+    msg:        "hook.step",
+    hook:       obs.hookName,
+    runId:      obs.runId,
+    parentRun:  obs.parentRunId,
+    step:       obs.stepName ?? `#${obs.stepId}`,
+    phase:      obs.phase,
+    durationMs: obs.durationMs,
+    error:      obs.error && (obs.error as Error).message,
+  });
+});
+```
+
+### 11. AbortSignal
+
+```ts
+const ac = new AbortController();
+setTimeout(() => ac.abort(new Error("timeout")), 1000);
+
+await myHook.run(ctx, { signal: ac.signal });
+// ctx.signal is set so inner code can poll:
+//   if (ctx.signal?.aborted) return;
+```
+
+---
+
+## `createHooks()` — bundled named hosts
 
 ```ts
 import { createHooks, hook } from "@nwire/hooks";
 
 const lifecycle = createHooks({
-  boot: hook<EndpointCtx>("endpoint.boot"),
-  ready: hook<EndpointCtx>("endpoint.ready"),
-  shutdown: hook<EndpointCtx>("endpoint.shutdown"),
+  registering: hook<RegisteringCtx>("nwire.app.registering"),
+  booting:     hook<BootingCtx>    ("nwire.app.booting"),
+  ready:       hook<ReadyCtx>      ("nwire.app.ready"),
+  shutdown:    hook<ShutdownCtx>   ("nwire.app.shutdown"),
 });
 
-// Apply a plugin object — same hook can take chains AND listeners:
+// Apply a plugin across all four at once:
 lifecycle.use({
-  boot: async (ctx, next) => {
-    logger.info("booting…");
-    await next();
-  },
-  shutdown: { on: (ctx) => logger.info("shut down", ctx) },
+  booting:  async (ctx, next) => { logger.info("booting"); await next(); },
+  ready:    { on: (ctx) => logger.info("ready", { port: ctx.port }) },
+  shutdown: async (ctx, next) => { await flushOutbox(); await next(); },
 });
 ```
 
-## The contract — the matrix
+`.hooks` is the underlying record — spread it to compose hosts:
+
+```ts
+const full = createHooks({ ...lifecycle.hooks, request: hook<...>("http.request") });
+```
+
+---
+
+## Production guidance
+
+- **Hot paths.** A `.use()` step adds one wrapper closure + one observation
+  emit. Per-request HTTP middleware on a busy server: ~250 ns/step in our
+  microbench. If you have a 100k-rps inner loop and don't need observability,
+  prefer a hand-rolled compose.
+- **Listener errors.** Default policy is log + continue. This matches Node's
+  `EventEmitter` and Koa's "don't crash because metrics broke." Opt into
+  `strictListeners: true` for testing and any place where listener failure
+  must surface.
+- **Taps.** Taps fire synchronously inside `.run()`. Don't do blocking I/O.
+  Buffer + flush async.
+- **AbortSignal.** Aborting throws between steps. A long-running step that
+  never `await`s won't notice. Plumb `ctx.signal` into your I/O calls.
+- **Topology.** `AsyncLocalStorage` survives microtasks and timers. It does
+  *not* survive `setImmediate` if you escape the await chain. Stay in
+  `await` land if you care about parent linkage.
+- **Recording size.** A recording grows linearly with step count; ctx
+  snapshots dominate the size. Use a custom `clone` to redact PII before
+  persisting.
+
+---
+
+## When NOT to use a hook
+
+- A single, hard-coded step that has no extension point. Just call the
+  function.
+- A synchronous calculation that never spans I/O. The async overhead is
+  wasted.
+- Something that's fundamentally request/response with no observers and no
+  cancellability. A normal function is fine.
+
+Hooks are for extension. If nobody will ever attach to it, don't make it
+one.
 
-| Question                                         | Behavior                                    |
-| ------------------------------------------------ | ------------------------------------------- |
-| `.on()` runs if chain short-circuits (no throw)? | Yes — listeners observe outcome             |
-| `.on()` runs if chain throws?                    | Yes — `ctx.error` is set first              |
-| Can listeners mutate ctx?                        | No — `.on()` types ctx as `Readonly<Ctx>`   |
-| Listeners awaited by `.run()`?                   | Yes — parallel, `Promise.allSettled`        |
-| Listener throws → fails chain?                   | No — collected, routed to `onListenerError` |
-| Listener ordering                                | Unordered (parallel)                        |
-| Chain ordering                                   | Insertion order (koa-compose)               |
+---
 
-Escape hatch: `hook(name, { strictListeners: true })` re-throws the first listener error instead of routing it through `onListenerError`.
+## Versioning + stability
 
-## API
+`@nwire/hooks` follows the framework's semver. The contract matrix in this
+README is the law — changing any row is a major bump.
 
-- `hook<Ctx>(name, options?)` — create one hook.
-- `Hook<Ctx>.use(fn)` / `.on(fn)` / `.off(fn)` / `.run(ctx)`.
-- `createHooks(record)` — typed bundle with `.hooks` + `.use(plugin)`.
-- `compose(fns)` / `pipe(...fns)` / `withTimeout(ms, fn)` / `withRetry(opts, fn)` — composition helpers.
+Already locked: `Hook<Ctx>` surface, `RunResult`, `StepObservation`,
+`Recording`. New optional capabilities (more `RunOptions`, more tap fields)
+are minor bumps; never breaking.