@nwire/handler 0.8.17 → 0.9.1

package/README.md

@@ -1,88 +1,203 @@
 # @nwire/handler
 
-> Operation primitive — one shape for action / query / resolver, usable from any transport.
-
-`defineHandler(name, config)` describes a single operation: input
-schema, response shape, the function. `execute(handler, input, ctx?)`
-runs one. Every Nwire transport (`@nwire/http`, `@nwire/queue`,
-`@nwire/mcp`) speaks this exact shape; `@nwire/forge`'s `defineAction`
-and `defineQuery` are flavored sugar on top.
+The operation primitive — one typed, callable, hookable value usable from every transport (HTTP, queue, MCP, CLI, direct test).
 
 ```bash
-pnpm add @nwire/handler zod
+pnpm add @nwire/handler
+```
+
+## Why
+
+Every backend ends up with the same shape: parse input, run a function with some deps, return a typed response or throw a typed error. Different teams wrap it in different abstractions (controllers, route handlers, command handlers, tRPC procedures, NestJS providers). They're all the same thing.
+
+`@nwire/handler` is that thing, distilled: a callable, type-generic value. It's a `Hook` from `@nwire/hooks` underneath, so it gets `.use()` middleware, `.on()` listeners, `.tap()` observation, `signal` cancellation, and replay — for free.
+
+Three rules:
+
+1. **Ctx is generic.** Whatever you pass to `.run(ctx)` is what the handler body destructures, fully typed.
+2. **App pins ctx once.** `defineHandlerWith<AppExtras>()` returns a factory you import everywhere; handlers never annotate ctx.
+3. **No global pollution.** Plugin contributions are imported types, intersected at the app boundary. Nothing is `declare module`-ed.
+
+## Surface
+
+```ts
+// The primitive
+function defineHandler<TInputSchema, TOutput, TExtras extends object = object>(
+  name: string,
+  config: HandlerConfig<TInputSchema, TOutput, TExtras>,
+): HandlerDefinition<TInputSchema, TOutput, TExtras>;
+
+// The app-boundary factory — pins TExtras once
+function defineHandlerWith<TExtras extends object>(): typeof defineHandler bound to TExtras;
+
+// Type alias for declaring a handler's ctx shape inline
+type Ctx<TInput, TExtras extends object = object> =
+  { input: TInput; signal: AbortSignal; set: …  } & TExtras;
+
+// Resources, errors, response factories
+function defineResource(name, { schema, public, examples });
+function defineError({ code, status, summary });   // callable: throw NotFound({ resourceId });
+ok / created / accepted / noContent / notModified / gone
+
+// Built-in errors
+Unauthorized / Forbidden / NotFound / Conflict / Gone / BadRequest
+
+// Type helpers
+HandlerInput<H> / HandlerOutput<H> / HandlerExtras<H>
 ```
 
-## Quick example
+## Consumer example
+
+`app/define.ts` — one file, pinned once:
+
+```ts
+import { defineHandlerWith, type Ctx } from "@nwire/handler";
+import type { AuthCradle } from "@nwire/auth";
+import type { DbCradle } from "@nwire/data-drizzle";
+
+// Plugins export type fragments; app composes its cradle:
+export type AppCradle = AuthCradle &
+  DbCradle & {
+    config: AppConfig;
+    logger: Logger;
+  };
+
+// Extras the wires put onto ctx at request time:
+type AppExtras = {
+  logger: Logger;
+  pg: PgClient;
+  user: { id: string; role: string; balance: number };
+};
+
+export const defineAction = defineHandlerWith<AppExtras>();
+export type AppCtx<I = unknown> = Ctx<I, AppExtras>;
+```
+
+`app/orders/buy-wash.action.ts` — a complete handler:
 
 ```ts
 import { z } from "zod";
-import {
-  defineHandler,
-  defineMiddleware,
-  defineHook,
-  pipe,
-  execute,
-  NotFound,
-  ok,
-} from "@nwire/handler";
-
-const authenticate = defineMiddleware("authenticate", async (ctx, next) => {
-  ctx.user = await verifyToken(ctx.header("authorization"));
+import { defineResource, defineError, NotFound } from "@nwire/handler";
+import { defineAction } from "@/define";
+
+const Wash = defineResource("Wash", {
+  schema: z.object({ id: z.string(), name: z.string(), price: z.number() }),
+  public: ["id", "name", "price"],
+});
+
+const InsufficientFunds = defineError({
+  code: "INSUFFICIENT_FUNDS",
+  status: 402,
+  summary: "balance too low for this wash",
+});
+
+export const BuyWash = defineAction("buyWash", {
+  input: z.object({ washId: z.string() }),
+  returns: Wash,
+  errors: [NotFound, InsufficientFunds],
+  handler: async ({ input, logger, pg, user, signal }) => {
+    const row = await pg.query("SELECT * FROM washes WHERE id=$1", [input.washId], { signal });
+    if (!row) throw NotFound({ resourceId: input.washId });
+    if (user.balance < row.price) throw InsufficientFunds({ have: user.balance, need: row.price });
+    logger.log(`${user.id} bought ${row.id}`);
+    return row;
+  },
+});
+
+// Per-handler middleware via the hook substrate
+BuyWash.use(async (ctx, next) => {
+  const t = performance.now();
   await next();
+  ctx.logger.log(`buyWash ${(performance.now() - t).toFixed(1)}ms`);
 });
+```
 
-const auditLog = defineHook("after", "audit", async (ctx, result) => {
-  await audit.write({ user: ctx.user.id, result });
+`wires/api.wire.ts` — boot, container, request composition:
+
+```ts
+import { createContainer } from "@nwire/container";
+import type { AppCradle } from "@/define";
+import { BuyWash } from "@/orders/buy-wash.action";
+
+const root = createContainer<AppCradle>();
+root.register("config", { port: 3000 });
+root.register("logger", () => ({ log: (s) => console.log(s) }));
+root.register("db.pg", () => new PgClient(root.cradle.config.port));
+
+const server = createServer(async (req, res) => {
+  const user = await authenticate(req);
+
+  const result = await BuyWash(JSON.parse(await readBody(req))).run({
+    ctx: {
+      logger: root.cradle.logger,
+      pg: root.cradle["db.pg"],
+      user,
+    },
+    signal: req.signal,
+  });
+  res.writeHead(201).end(JSON.stringify(result));
 });
+```
 
-const userPipeline = pipe("user-pipeline", authenticate, auditLog);
+`app/orders/buy-wash.test.ts` — unit test, no container:
 
-const getUser = defineHandler("getUser", {
-  input: z.object({ id: z.string() }),
-  middleware: [userPipeline],
-  handler: async ({ input, resolve }) => {
-    const repo = resolve<UserRepo>("UserRepo");
-    const user = await repo.findById(input.id);
-    if (!user) throw NotFound("user", input.id);
-    return ok(user);
-  },
+```ts
+import { expect, test } from "vitest";
+import { BuyWash, InsufficientFunds } from "./buy-wash.action";
+
+test("rejects when balance < price", async () => {
+  await expect(
+    BuyWash({ washId: "w1" }).run({
+      ctx: {
+        logger: { log: () => {} },
+        pg: { query: async () => ({ id: "w1", name: "Quick", price: 100 }) },
+        user: { id: "u-1", role: "user", balance: 5 },
+      },
+    }),
+  ).rejects.toMatchObject({
+    code: "INSUFFICIENT_FUNDS",
+    status: 402,
+    context: { have: 5, need: 100 },
+  });
 });
+```
+
+## The four contracts in one model
+
+| Concern          | How                                                                                         |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| Input validation | `input: zodSchema` — parsed before the handler body runs                                    |
+| Output shape     | `returns: Resource \| ResponseSpec[]` — narrows the handler's return type, drives OpenAPI   |
+| Throws           | `errors: [NotFound, …]` — typed throwables, drive 4xx OpenAPI bodies                        |
+| Cancellation     | `signal: AbortSignal` on ctx — forward to fetch/pg/etc., bail via `signal.throwIfAborted()` |
+
+## Cancellation in practice
 
-const res = await execute(getUser, { id: "u_1" }, { resolve });
+The signal flows through nested `.run()` calls automatically:
+
+```ts
+const ParentOp = defineAction("parent", {
+  handler: async ({ signal }) => ChildOp().run({ signal }),
+});
+// caller-supplied signal → ParentOp.run({ signal }) → ChildOp.run({ signal })
+// abort the caller's controller → both bail
 ```
 
-## Surface
+When no signal is supplied, ctx gets a non-aborting placeholder — code can always pass `ctx.signal` through to `fetch`/`pg`/`redis` without null checks.
+
+## Errors
+
+```ts
+throw NotFound; // bare value (it IS an Error)
+throw NotFound({ resourceId: input.id }); // callable, contextualised clone
+```
+
+Caught at the transport layer — REST → `status` + `{ code, message, context }`, GraphQL → `extensions.code`, CLI → exit status + stderr.
+
+## Built on @nwire/hooks
+
+Every handler is a `Hook<HandlerRunCtx>` underneath. `.use()`, `.on()`, `.tap()`, `.runDetailed()` all work. The user's handler function is the innermost chain step, registered at construction with `Number.MIN_SAFE_INTEGER` priority so every `.use()` you add wraps around it. Telemetry, replay, observation come along for free.
+
+## Scope
 
-| Export                                       | Role                                                                                                                                              |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `defineHandler(name, config)`                | The operation primitive: `{ input, handler, returns?, errors?, summary?, policy?, middleware? }`.                                                 |
-| `execute(handler, input, ctx?)`              | Run one handler; returns a response envelope.                                                                                                     |
-| `defineMiddleware(name?, fn)`                | Chain step `(ctx, next)`. Captures `$source`. Reusable.                                                                                           |
-| `defineHook("before" \| "after", name?, fn)` | Before-or-after-only step (cleaner than mw that forgets `next()`).                                                                                |
-| `pipe(name?, ...steps)`                      | Compose middleware + hooks into a reusable pipe value. Attaches a per-pipe `$hook` (`@nwire/hooks`) so transports adopt it for telemetry.         |
-| `unwindPipe(steps)`                          | Walk a pipe into `{ middlewares, beforeHooks, afterHooks }` — transports call this when mounting.                                                 |
-| `defineResource(name, opts)`                 | Public response shape (field allowlist, OpenAPI schema).                                                                                          |
-| `defineError(meta)`                          | Typed throwable with status code.                                                                                                                 |
-| Response factories                           | `ok` / `created` / `accepted` / `noContent` / `notModified` / `gone`.                                                                             |
-| Framework errors                             | `Unauthorized` / `Forbidden` / `NotFound` / `Conflict` / `Gone` / `BadRequest`.                                                                   |
-| Type guards                                  | `isHandlerDefinition` / `isMiddleware` / `isHook` / `isPipe` / `isResourceDefinition` / `isNwireError` / `isResponseSpec` / `isResponseInstance`. |
-
-### `$source` + `$hook`
-
-- Every `defineMiddleware` / `pipe` captures its call site as `$source`
-  via `@nwire/messages.captureSourceLocation`, so Studio can render
-  click-to-open chips.
-- Every `pipe(...)` creates a per-pipe `Hook<ResolverCtx>` (one
-  `.use()` per middleware step). Runtimes adopt it via
-  `runtime.adoptHook($hook)` to route taps into telemetry; consumers
-  that don't know about `$hook` ignore the field.
-
-## Related
-
-- `@nwire/forge` — re-exports this surface and layers `defineAction` (`defineHandler` + `emits`) + `defineQuery` on top.
-- `@nwire/hooks` — backs `pipe()`'s per-pipe `$hook` and the resolver-level dispatch chain.
-- `@nwire/http` — mounts handlers by `unwindPipe`-ing their middleware.
-
-## Status
-
-v0.x — handler shape, middleware/hook/pipe primitives, response factories, and core errors are locked. Per-pipe `$hook` adoption is the canonical observation seam.
+Standalone — no DI, no events, no logger, no transport opinions. App composes ctx by value; transports compose ctx at boot. Forge / HTTP / queue / MCP wires layer on top.

package/dist/define-error.d.ts

@@ -7,14 +7,20 @@
  *     summary: "Station already has an unfinished wash",
  *   });
  *
- *   // In a resolver handler:
- *   if (active) throw WashInProgress;
+ *   // Throw it with context — callable form, symmetric with defineEvent/defineAction:
+ *   throw WashInProgress({ stationId: input.id });
  *
- * Each call site reuses the SAME instance (immutable). Transports detect
- * `instanceof NwireError`, read `.code` + `.status` + `.summary`, render
- * the right shape per medium:
- *   - REST     → JSON body `{ code, message }` with the declared status
- *   - GraphQL  → error with `extensions: { code }`
+ *   // Throw it without context — works because the definition IS an Error:
+ *   throw WashInProgress;
+ *
+ * Each `defineError(...)` result is BOTH:
+ *   - an `Error` instance you can `throw` directly (zero context),
+ *   - a callable factory `Boom(context)` that returns a contextualised clone.
+ *
+ * Transports detect `instanceof NwireError`, read `.code` + `.status` + `.summary`
+ * + `.context`, render the right shape per medium:
+ *   - REST     → JSON body `{ code, message, context }` with the declared status
+ *   - GraphQL  → error with `extensions: { code, context }`
  *   - CLI      → stderr message + exit status
  */
 export interface ErrorMeta {
@@ -24,36 +30,36 @@ export interface ErrorMeta {
     readonly description?: string;
     readonly tags?: readonly string[];
 }
-export interface ErrorDefinition extends ErrorMeta {
-    readonly $kind: "error";
-}
 /**
  * Concrete Error subclass — thrown by domain code, caught by transport.
- * The `defineError(...)` result is an instance of this class.
+ * The `defineError(...)` result is an instance of this class, AND callable
+ * so `Boom(context)` returns a contextualised clone.
  */
-export declare class NwireError extends Error implements ErrorDefinition {
+export declare class NwireError extends Error implements ErrorMeta {
     readonly $kind: "error";
     readonly code: string;
     readonly status: number;
     readonly summary: string;
     readonly description?: string;
     readonly tags?: readonly string[];
-    constructor(meta: ErrorMeta);
-    /**
-     * Build a fresh error instance with the same metadata but additional
-     * runtime context — e.g., the resource id that triggered it.
-     */
-    with(context: Record<string, unknown>): NwireError & {
-        readonly context: Record<string, unknown>;
-    };
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(meta: ErrorMeta, context?: Readonly<Record<string, unknown>>);
+}
+/**
+ * The value returned by `defineError(meta)` — callable to build a contextual
+ * clone, and itself an Error instance you can throw directly.
+ */
+export interface ErrorDefinition extends NwireError {
+    /** Build a contextualised clone — `throw NotFound({ resourceId: id })`. */
+    (context: Readonly<Record<string, unknown>>): NwireError;
 }
-export declare function defineError(meta: ErrorMeta): NwireError;
+export declare function defineError(meta: ErrorMeta): ErrorDefinition;
 /** Type narrow. */
 export declare function isNwireError(x: unknown): x is NwireError;
-export declare const Unauthorized: NwireError;
-export declare const Forbidden: NwireError;
-export declare const NotFound: NwireError;
-export declare const Gone: NwireError;
-export declare const BadRequest: NwireError;
-export declare const Conflict: NwireError;
+export declare const Unauthorized: ErrorDefinition;
+export declare const Forbidden: ErrorDefinition;
+export declare const NotFound: ErrorDefinition;
+export declare const Gone: ErrorDefinition;
+export declare const BadRequest: ErrorDefinition;
+export declare const Conflict: ErrorDefinition;
 //# sourceMappingURL=define-error.d.ts.map

package/dist/define-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-error.d.ts","sourceRoot":"","sources":["../src/define-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAKzB;AAED;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAM,YAAW,eAAe;IAC9D,QAAQ,CAAC,KAAK,EAAG,OAAO,CAAU;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEtB,IAAI,EAAE,SAAS;IAU3B;;;OAGG;IACH,IAAI,CACF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,UAAU,GAAG;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE;CAK9D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,CAEvD;AAED,mBAAmB;AACnB,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAExD;AAGD,eAAO,MAAM,YAAY,YAIvB,CAAC;AAEH,eAAO,MAAM,SAAS,YAIpB,CAAC;AAEH,eAAO,MAAM,QAAQ,YAInB,CAAC;AAEH,eAAO,MAAM,IAAI,YAIf,CAAC;AAEH,eAAO,MAAM,UAAU,YAIrB,CAAC;AAEH,eAAO,MAAM,QAAQ,YAInB,CAAC"}
+{"version":3,"file":"define-error.d.ts","sourceRoot":"","sources":["../src/define-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,KAAM,YAAW,SAAS;IACxD,QAAQ,CAAC,KAAK,EAAG,OAAO,CAAU;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAEzC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAUzE;AAED;;;GAGG;AACH,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,2EAA2E;IAC3E,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,UAAU,CAAC;CAC1D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,eAAe,CAW5D;AAED,mBAAmB;AACnB,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAExD;AAGD,eAAO,MAAM,YAAY,iBAIvB,CAAC;AAEH,eAAO,MAAM,SAAS,iBAIpB,CAAC;AAEH,eAAO,MAAM,QAAQ,iBAInB,CAAC;AAEH,eAAO,MAAM,IAAI,iBAIf,CAAC;AAEH,eAAO,MAAM,UAAU,iBAIrB,CAAC;AAEH,eAAO,MAAM,QAAQ,iBAInB,CAAC"}

package/dist/define-error.js

@@ -7,19 +7,26 @@
  *     summary: "Station already has an unfinished wash",
  *   });
  *
- *   // In a resolver handler:
- *   if (active) throw WashInProgress;
+ *   // Throw it with context — callable form, symmetric with defineEvent/defineAction:
+ *   throw WashInProgress({ stationId: input.id });
  *
- * Each call site reuses the SAME instance (immutable). Transports detect
- * `instanceof NwireError`, read `.code` + `.status` + `.summary`, render
- * the right shape per medium:
- *   - REST     → JSON body `{ code, message }` with the declared status
- *   - GraphQL  → error with `extensions: { code }`
+ *   // Throw it without context — works because the definition IS an Error:
+ *   throw WashInProgress;
+ *
+ * Each `defineError(...)` result is BOTH:
+ *   - an `Error` instance you can `throw` directly (zero context),
+ *   - a callable factory `Boom(context)` that returns a contextualised clone.
+ *
+ * Transports detect `instanceof NwireError`, read `.code` + `.status` + `.summary`
+ * + `.context`, render the right shape per medium:
+ *   - REST     → JSON body `{ code, message, context }` with the declared status
+ *   - GraphQL  → error with `extensions: { code, context }`
  *   - CLI      → stderr message + exit status
  */
 /**
  * Concrete Error subclass — thrown by domain code, caught by transport.
- * The `defineError(...)` result is an instance of this class.
+ * The `defineError(...)` result is an instance of this class, AND callable
+ * so `Boom(context)` returns a contextualised clone.
  */
 export class NwireError extends Error {
     $kind = "error";
@@ -28,7 +35,8 @@ export class NwireError extends Error {
     summary;
     description;
     tags;
-    constructor(meta) {
+    context;
+    constructor(meta, context) {
         super(meta.summary);
         this.name = meta.code;
         this.code = meta.code;
@@ -36,19 +44,19 @@ export class NwireError extends Error {
         this.summary = meta.summary;
         this.description = meta.description;
         this.tags = meta.tags;
-    }
-    /**
-     * Build a fresh error instance with the same metadata but additional
-     * runtime context — e.g., the resource id that triggered it.
-     */
-    with(context) {
-        const next = new NwireError(this);
-        Object.assign(next, { context });
-        return next;
+        if (context !== undefined)
+            this.context = context;
     }
 }
 export function defineError(meta) {
-    return new NwireError(meta);
+    // Build the canonical (no-context) instance + make it callable.
+    const base = new NwireError(meta);
+    const factory = ((context) => new NwireError(meta, context));
+    // Copy every own property + the prototype-resident fields onto the factory
+    // so `factory instanceof Error`, `factory.code`, `factory.message`, etc.
+    // all behave like the underlying NwireError instance.
+    Object.setPrototypeOf(factory, base);
+    return factory;
 }
 /** Type narrow. */
 export function isNwireError(x) {

package/dist/define-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-error.js","sourceRoot":"","sources":["../src/define-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkBH;;;GAGG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,KAAK,GAAG,OAAgB,CAAC;IACzB,IAAI,CAAS;IACb,MAAM,CAAS;IACf,OAAO,CAAS;IAChB,WAAW,CAAU;IACrB,IAAI,CAAqB;IAElC,YAAY,IAAe;QACzB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED;;;OAGG;IACH,IAAI,CACF,OAAgC;QAEhC,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACjC,OAAO,IAAkE,CAAC;IAC5E,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,IAAe;IACzC,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,mBAAmB;AACnB,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,OAAO,CAAC,YAAY,UAAU,CAAC;AACjC,CAAC;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;IACtC,IAAI,EAAE,cAAc;IACpB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,0BAA0B;CACpC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;IACnC,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,kDAAkD;CAC5D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CAAC;IAClC,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,+BAA+B;CACzC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,IAAI,GAAG,WAAW,CAAC;IAC9B,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,iDAAiD;CAC3D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,WAAW,CAAC;IACpC,IAAI,EAAE,aAAa;IACnB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,8EAA8E;CACxF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CAAC;IAClC,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,2DAA2D;CACrE,CAAC,CAAC"}
+{"version":3,"file":"define-error.js","sourceRoot":"","sources":["../src/define-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,KAAK,GAAG,OAAgB,CAAC;IACzB,IAAI,CAAS;IACb,MAAM,CAAS;IACf,OAAO,CAAS;IAChB,WAAW,CAAU;IACrB,IAAI,CAAqB;IACzB,OAAO,CAAqC;IAErD,YAAY,IAAe,EAAE,OAA2C;QACtE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACpD,CAAC;CACF;AAWD,MAAM,UAAU,WAAW,CAAC,IAAe;IACzC,gEAAgE;IAChE,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,OAAO,GAAoB,CAAC,CAAC,OAA0C,EAAE,EAAE,CAC/E,IAAI,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAA+B,CAAC;IAE/D,2EAA2E;IAC3E,yEAAyE;IACzE,sDAAsD;IACtD,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACrC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,mBAAmB;AACnB,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,OAAO,CAAC,YAAY,UAAU,CAAC;AACjC,CAAC;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;IACtC,IAAI,EAAE,cAAc;IACpB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,0BAA0B;CACpC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;IACnC,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,kDAAkD;CAC5D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CAAC;IAClC,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,+BAA+B;CACzC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,IAAI,GAAG,WAAW,CAAC;IAC9B,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,iDAAiD;CAC3D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,WAAW,CAAC;IACpC,IAAI,EAAE,aAAa;IACnB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,8EAA8E;CACxF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CAAC;IAClC,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,2DAA2D;CACrE,CAAC,CAAC"}

package/dist/define-handler.d.ts

@@ -3,166 +3,205 @@
  *
  *   const GetStation = defineHandler("GetStation", {
  *     input:   z.object({ stationId: z.string() }),
+ *     handler: async ({ input }) => loadStation(input.stationId),
  *     returns: Station,
- *     handler: async ({ input, db }) => db.stations.findById(input.stationId),
+ *     errors:  [NotFound],
  *   });
  *
- * The shape is universal — same primitive whether the operation is exposed
- * via HTTP, queue, MCP, CLI, or invoked directly via `execute(handler, input)`.
- * Every transport binds via its own `(binding, handler, options)` signature;
- * the binding narrows the input contract at the boundary, the handler is
- * the lowest-common-denominator inside.
+ *   GetStation({ stationId: "abc" })                  // mint a prepared op
+ *   await GetStation({ stationId: "abc" }).run()      // run it
+ *   await GetStation.run({ input, signal })           // low-level hook surface
+ *   GetStation.use(myMiddleware)                      // attach a hook chain step
+ *   GetStation.on(observer)                           // attach a listener
  *
- *   See: architecture-sketch.html §08.
+ * The handler IS a `Hook` from `@nwire/hooks`. `.use()` attaches chain steps;
+ * `.on()` attaches parallel listeners; `.run()` executes. The user's handler
+ * function is the innermost chain step — registered at construction with
+ * `Number.MIN_SAFE_INTEGER` priority so every `.use(...)` wraps around it.
  *
- * Field placement follows the freq table:
- *   first-class — input, handler, returns, errors, summary, policy, emits
- *   meta        — tags, description, version, deprecated, successor
- *   settings    — retry, timeout, cache, idempotency
+ * **Ctx is generic.** The handler's ctx is `BaseHookCtx & { input } & TExtras`
+ * where `TExtras` is inferred from the handler's param annotation, or pinned
+ * once via `defineHandlerWith<TExtras>()` at the app boundary. Whatever you
+ * pass to `.run(ctx)` is what reaches the handler body, fully typed. No
+ * declaration merging on ctx — composition by value.
  *
- * `meta` + `settings` are open bags; adapters extend them via TS declaration
- * merging without touching the core type.
- *
- * NOTE: forge has its own `defineHandler(action, fn)` that binds a handler
- * to an existing `ActionDefinition`. That signature stays inside `@nwire/forge`
- * because it depends on the action machinery. The standalone version lives
- * here because every transport needs it without the forge surface.
+ * `meta` + `settings` ARE globally augmentable open interfaces. Those are
+ * declarative per-handler tags (policy, retry, persona, SLO) that plugins
+ * must discover across every handler — different role from ctx, different
+ * mechanism by design.
  */
 import type { z } from "zod";
 import type { ZodTypeAny } from "@nwire/messages";
-import type { Container } from "@nwire/container";
-import { type Logger } from "@nwire/logger";
+import { type BaseHookCtx, type ChainFn, type ListenerFn, type RunOptions, type RunResult, type UseOptions, type OnOptions, type TapFn } from "@nwire/hooks";
 import type { ErrorDefinition } from "./define-error.js";
 import type { ResponseSpec, ListResponseSpec } from "./response.js";
 import type { ResourceDefinition } from "./define-resource.js";
-/** Bags extensible via TS declaration merging — adapters add fields here. */
+/**
+ * Empty bags — plugins extend via TS declaration merging.
+ *
+ *   declare module "@nwire/handler" {
+ *     interface HandlerSettings { retry?: { attempts: number } }
+ *   }
+ *
+ * These hold *declarative config* (RBAC policies, retry strategies,
+ * SLO budgets, persona tags) — NOT runtime ctx. Different role, different
+ * mechanism: ctx is per-invocation runtime data composed by value;
+ * meta/settings are per-handler design-time tags plugins discover globally.
+ */
 export interface HandlerMeta {
-    readonly tags?: readonly string[];
-    readonly description?: string;
-    readonly version?: number;
-    readonly deprecated?: boolean;
-    readonly successor?: string;
 }
 export interface HandlerSettings {
-    readonly retry?: {
-        attempts: number;
-        backoff?: "linear" | "exponential";
-    };
-    readonly timeout?: number;
-    readonly cache?: {
-        ttl: number;
-    };
-    readonly idempotency?: (input: unknown) => string;
 }
+/** Resolve a zod schema (or `undefined`) to the parsed input type. */
+export type InferInput<S extends ZodTypeAny | undefined> = S extends ZodTypeAny ? z.output<S> : undefined;
 /**
- * Context delivered to every handler. The shape is intentionally minimal —
- * adapters supply richer context via the container (resolve any registered
- * dep by name + destructure into the handler signature).
+ * The base ctx every handler receives — hooks' `BaseHookCtx` (`signal` + typed
+ * `set`) plus the parsed `input`. Apps extend with their own `TExtras` via
+ * the `Ctx<TInput, TExtras>` alias below.
  */
-export interface HandlerContext<TInput = unknown> {
-    /** Parsed + validated input (drawn from `config.input` schema). */
-    readonly input: TInput;
-    /** Look up a dependency by name. Most handlers destructure instead. */
-    resolve<T = unknown>(name: string): T;
-    /** Per-execution container scope. */
-    readonly container: Container;
-    /** Logger scoped to this execution (correlation/causation already attached). */
-    readonly logger: Logger;
-    /** Free-form bag for transport-specific extras (raw request, MCP progress, …). */
-    readonly transport?: Record<string, unknown>;
+export interface HandlerBaseCtx<TInput> extends BaseHookCtx {
+    input: TInput;
 }
+/**
+ * Sugar for declaring a handler's ctx shape:
+ *
+ *   handler: async ({ input, cradle, user }: Ctx<MyInput, { cradle: Cradle; user: User }>) => …
+ */
+export type Ctx<TInput, TExtras extends object = object> = HandlerBaseCtx<TInput> & TExtras;
 /**
  * `returns` may be a single resource, a single response spec, or an array
  * of response specs (e.g. `[created(Station), accepted(StationHandle)]`).
  */
 export type HandlerReturnsSpec = ResourceDefinition | ResponseSpec | ListResponseSpec<ResourceDefinition> | ReadonlyArray<ResponseSpec | ListResponseSpec<ResourceDefinition>>;
-/**
- * Policy: a tag (`"admin"`), a list of tags (`["admin", "operator"]`), or
- * a tuple of `[action, subject]` for RBAC-style policies. Adapters
- * interpret the value per their authorization model.
- */
-export type HandlerPolicy = string | readonly string[] | readonly [string, string];
-export interface HandlerConfig<TInputSchema extends ZodTypeAny | undefined = ZodTypeAny | undefined, TOutput = unknown> {
+export interface HandlerConfig<TInputSchema extends ZodTypeAny | undefined = undefined, TOutput = unknown, TExtras extends object = object> {
     /** Input schema. Optional for zero-arg handlers (health checks, listings without filters). */
     readonly input?: TInputSchema;
-    /** The implementation. Receives the typed input + context. */
-    readonly handler: (ctx: HandlerContext<TInputSchema extends ZodTypeAny ? z.output<TInputSchema> : undefined>) => TOutput | Promise<TOutput>;
+    /** The implementation. Receives the typed input + ctx fields contributed upstream. */
+    readonly handler: (ctx: Ctx<InferInput<TInputSchema>, TExtras>) => TOutput | Promise<TOutput>;
     /** Documented response shape(s). Drives OpenAPI + runtime body validation. */
     readonly returns?: HandlerReturnsSpec;
     /** Declared error values this handler may throw. */
     readonly errors?: readonly ErrorDefinition[];
-    /** Events this handler may emit (action flavour). */
-    readonly emits?: readonly unknown[];
-    /** One-line intent. Surfaces in OpenAPI/MCP descriptions. */
+    /** One-line intent. Surfaces in OpenAPI / MCP / Studio. */
     readonly summary?: string;
-    /** Authorization policy. Adapters (rbac, authz) consume this. */
-    readonly policy?: HandlerPolicy;
-    /** Rare-field bag — tags, description, version, deprecated, …. */
+    /** Multi-line prose. Surfaces in OpenAPI / MCP / Studio. */
+    readonly description?: string;
+    /** Open bag — plugins contribute fields via declaration merging. */
     readonly meta?: HandlerMeta;
-    /** Behavior-tuning bag — retry, timeout, cache, idempotency. */
+    /** Open bag — plugins contribute fields via declaration merging. */
     readonly settings?: HandlerSettings;
 }
-export interface HandlerDefinition<TInputSchema extends ZodTypeAny | undefined = ZodTypeAny | undefined, TOutput = unknown> {
+/**
+ * Hook ctx that flows through the chain when a handler runs. Extends the
+ * consumer's `TExtras` so middleware that wrote to ctx (or used `.set()`)
+ * is visible to subsequent steps + listeners.
+ */
+export type HandlerRunCtx<TInput = unknown, TOutput = unknown, TExtras extends object = object> = Ctx<TInput, TExtras> & {
+    result?: TOutput;
+};
+/** Options passed to `PreparedOp.run()` — the high-level callable form. */
+export interface PreparedOpRunOptions<TExtras extends object = object> {
+    readonly signal?: AbortSignal;
+    /**
+     * Extras to populate on ctx before the handler body runs. Required when
+     * `TExtras` declares fields the runtime must supply (`cradle`, `user`, …).
+     * Optional `{}` for handlers that declared no extras.
+     */
+    readonly ctx?: TExtras;
+}
+/**
+ * The value returned by calling a handler as a factory: `Handler(input)`.
+ * Holds the validated input and exposes `.run(opts?)` to execute.
+ */
+export interface PreparedOp<TInput = unknown, TOutput = unknown, TExtras extends object = object> {
+    readonly input: TInput;
+    run(opts?: PreparedOpRunOptions<TExtras>): Promise<TOutput>;
+}
+/**
+ * The handler definition. Composes a `Hook<HandlerRunCtx>` for the chain
+ * surface (`.use` / `.on` / `.off` / `.run` / `.runDetailed` / `.tap`) and
+ * is callable as a factory that mints a `PreparedOp`.
+ */
+export interface HandlerDefinition<TInputSchema extends ZodTypeAny | undefined = undefined, TOutput = unknown, TExtras extends object = object> {
     readonly $kind: "handler";
     readonly name: string;
-    readonly config: HandlerConfig<TInputSchema, TOutput>;
+    readonly config: HandlerConfig<TInputSchema, TOutput, TExtras>;
+    (input: TInputSchema extends ZodTypeAny ? z.input<TInputSchema> : void): PreparedOp<InferInput<TInputSchema>, TOutput, TExtras>;
+    /** Hook chain attach — runs sequentially, can short-circuit. */
+    use(fn: ChainFn<HandlerRunCtx<InferInput<TInputSchema>, TOutput, TExtras>>, opts?: UseOptions): HandlerDefinition<TInputSchema, TOutput, TExtras>;
+    /** Listener attach — observes the final ctx, cannot mutate. */
+    on(fn: ListenerFn<HandlerRunCtx<InferInput<TInputSchema>, TOutput, TExtras>>, opts?: OnOptions): HandlerDefinition<TInputSchema, TOutput, TExtras>;
+    /** Detach a previously attached `.use()` or `.on()` fn. */
+    off(fn: ChainFn<HandlerRunCtx<InferInput<TInputSchema>, TOutput, TExtras>> | ListenerFn<HandlerRunCtx<InferInput<TInputSchema>, TOutput, TExtras>>): HandlerDefinition<TInputSchema, TOutput, TExtras>;
     /**
-     * Convenience accessor — equivalent to `config.handler`. Lets transports
-     * write `handler.run(ctx)` without reaching into `.config`.
+     * Run the chain + listeners. The caller supplies the ctx — `input` +
+     * `signal` are filled in automatically; everything in `TExtras` must
+     * be present on the ctx object.
      */
-    run(ctx: HandlerContext<TInputSchema extends ZodTypeAny ? z.output<TInputSchema> : undefined>): TOutput | Promise<TOutput>;
+    run(ctx: HandlerRunCtx<InferInput<TInputSchema>, TOutput, TExtras>, opts?: RunOptions): Promise<HandlerRunCtx<InferInput<TInputSchema>, TOutput, TExtras>>;
+    /** Same as `.run()` but returns the full observation trace. */
+    runDetailed(ctx: HandlerRunCtx<InferInput<TInputSchema>, TOutput, TExtras>, opts?: RunOptions): Promise<RunResult<HandlerRunCtx<InferInput<TInputSchema>, TOutput, TExtras>>>;
+    /** Subscribe to per-step observations. */
+    tap(observer: TapFn): () => void;
+    /** Step counts on the underlying hook. */
+    stepCounts(): {
+        readonly chain: number;
+        readonly listeners: number;
+    };
 }
+/**
+ * `HandlerLike` — what `interface-builder.wire()` accepts.
+ *
+ *   - a full `HandlerDefinition` (typed, hookable, has metadata) — the canonical path.
+ *   - a bare async function (one-liners, health checks, escape hatch).
+ */
+export type HandlerLike<TInput = unknown, TOutput = unknown> = HandlerDefinition<ZodTypeAny | undefined, TOutput, object> | ((input: TInput) => Promise<TOutput> | TOutput);
 /**
  * Define a handler — the operation primitive.
  *
  *   const ListTodos = defineHandler("listTodos", {
  *     input:   z.object({ status: z.string().optional() }),
- *     handler: async ({ input, resolve }) => {
- *       const db = resolve<DB>("db");
- *       return db.todos.findMany(input);
- *     },
+ *     handler: async ({ input }) => todos.findMany(input),
  *   });
  *
  *   // Direct invocation:
- *   const todos = await execute(ListTodos, { status: "open" });
+ *   const result = await ListTodos({ status: "open" }).run();
  *
- *   // HTTP transport:
- *   api.wire(get("/todos"), ListTodos);
+ *   // Hook composition:
+ *   ListTodos.use(withTimeout(5000));
+ *   ListTodos.on(record => otel.span(...));
  *
- *   // Queue transport (same handler):
- *   workers.wire(job("listTodos"), ListTodos);
- */
-export declare function defineHandler<TInputSchema extends ZodTypeAny | undefined, TOutput>(name: string, config: HandlerConfig<TInputSchema, TOutput>): HandlerDefinition<TInputSchema, TOutput>;
-/** Type narrow. */
-export declare function isHandlerDefinition(x: unknown): x is HandlerDefinition;
-/**
- * Options for `execute()` — transport-agnostic. Adapters can pass a
- * container so the handler can `resolve()` its deps; if omitted, a
- * minimal stub container is supplied that throws on resolve.
+ *   // Low-level hook surface (transports use this):
+ *   await ListTodos.run({ input: { status: "open" }, signal });
  */
-export interface ExecuteOptions {
-    readonly container?: Container;
-    readonly logger?: Logger;
-    readonly transport?: Record<string, unknown>;
-}
+export declare function defineHandler<TInputSchema extends ZodTypeAny | undefined, TOutput, TExtras extends object = object>(name: string, config: HandlerConfig<TInputSchema, TOutput, TExtras>): HandlerDefinition<TInputSchema, TOutput, TExtras>;
 /**
- * Invoke a handler directly with input. The framework validates input
- * against the handler's `input` schema (if declared), constructs the
- * handler context, runs the handler, and returns its result.
+ * App-boundary sugar — pin `TExtras` once so every handler in the app reads
+ * `ctx` as the bound shape without per-call annotations.
  *
- *   const todos = await execute(ListTodos, { status: "open" });
+ *   // app/action.ts
+ *   type AppExtras = { cradle: AppCradle; user: User };
+ *   export const action = defineHandlerWith<AppExtras>();
  *
- * This is the universal "any host can mount it" entry point. Transports
- * call into `execute()` after parsing the binding's payload; tests call
- * `execute()` directly to bypass transport machinery.
- */
-export declare function execute<TInputSchema extends ZodTypeAny | undefined, TOutput>(handler: HandlerDefinition<TInputSchema, TOutput>, input: TInputSchema extends ZodTypeAny ? z.input<TInputSchema> : any, options?: ExecuteOptions): Promise<TOutput>;
-/**
- * Type alias for a handler-or-callable. Transports `.wire()` accept either
- * a full `HandlerDefinition` (typed, validated) or a bare async function
- * (escape hatch for one-liners + health checks).
+ *   // every handler file:
+ *   import { action } from "@/action";
+ *   const PlaceOrder = action("placeOrder", {
+ *     input: z.object({ id: z.string() }),
+ *     handler: async ({ input, cradle, user }) => …   // fully typed, no annotation
+ *   });
+ *
+ *   // every transport / .run() call:
+ *   PlaceOrder.run({ input, signal, cradle, user });
  */
-export type HandlerLike<TInput = unknown, TOutput = unknown> = HandlerDefinition<ZodTypeAny | undefined, TOutput> | ((input: TInput) => Promise<TOutput> | TOutput);
-/** Re-exports for the public surface. */
+export declare function defineHandlerWith<TExtras extends object>(): <TInputSchema extends ZodTypeAny | undefined, TOutput>(name: string, config: HandlerConfig<TInputSchema, TOutput, TExtras>) => HandlerDefinition<TInputSchema, TOutput, TExtras>;
+/** Type narrow. */
+export declare function isHandlerDefinition(x: unknown): x is HandlerDefinition;
+/** Extract the input type of a handler's schema (post-parse). */
+export type HandlerInput<H> = H extends HandlerDefinition<infer S, unknown, object> ? InferInput<S> : never;
+/** Extract the output type of a handler. */
+export type HandlerOutput<H> = H extends HandlerDefinition<ZodTypeAny | undefined, infer O, object> ? O : never;
+/** Extract the extras (TExtras) a handler requires on ctx. */
+export type HandlerExtras<H> = H extends HandlerDefinition<ZodTypeAny | undefined, unknown, infer E> ? E : never;
+/** Re-export from the response builders for ergonomics. */
 export type { ResponseInstance } from "./response.js";
 //# sourceMappingURL=define-handler.d.ts.map

package/dist/define-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-handler.d.ts","sourceRoot":"","sources":["../src/define-handler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define-handler.d.ts","sourceRoot":"","sources":["../src/define-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,KAAK,EACX,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAoB,MAAM,eAAe,CAAC;AACtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;CAAG;AAC/B,MAAM,WAAW,eAAe;CAAG;AAEnC,sEAAsE;AACtE,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,UAAU,GAAG,SAAS,IAAI,CAAC,SAAS,UAAU,GAC3E,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GACX,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,CAAE,SAAQ,WAAW;IACzD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;AAE5F;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,kBAAkB,GAClB,YAAY,GACZ,gBAAgB,CAAC,kBAAkB,CAAC,GACpC,aAAa,CAAC,YAAY,GAAG,gBAAgB,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAEvE,MAAM,WAAW,aAAa,CAC5B,YAAY,SAAS,UAAU,GAAG,SAAS,GAAG,SAAS,EACvD,OAAO,GAAG,OAAO,EACjB,OAAO,SAAS,MAAM,GAAG,MAAM;IAE/B,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9F,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IACtC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CACvB,MAAM,GAAG,OAAO,EAChB,OAAO,GAAG,OAAO,EACjB,OAAO,SAAS,MAAM,GAAG,MAAM,IAC7B,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhD,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,SAAS,MAAM,GAAG,MAAM;IAC9F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7D;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAChC,YAAY,SAAS,UAAU,GAAG,SAAS,GAAG,SAAS,EACvD,OAAO,GAAG,OAAO,EACjB,OAAO,SAAS,MAAM,GAAG,MAAM;IAE/B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAG/D,CACE,KAAK,EAAE,YAAY,SAAS,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,IAAI,GACpE,UAAU,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAE1D,gEAAgE;IAChE,GAAG,CACD,EAAE,EAAE,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,EACtE,IAAI,CAAC,EAAE,UAAU,GAChB,iBAAiB,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAErD,+DAA+D;IAC/D,EAAE,CACA,EAAE,EAAE,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,EACzE,IAAI,CAAC,EAAE,SAAS,GACf,iBAAiB,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAErD,2DAA2D;IAC3D,GAAG,CACD,EAAE,EACE,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,GAClE,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,GACxE,iBAAiB,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAErD;;;;OAIG;IACH,GAAG,CACD,GAAG,EAAE,aAAa,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAC9D,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAEtE,+DAA+D;IAC/D,WAAW,CACT,GAAG,EAAE,aAAa,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAC9D,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,SAAS,CAAC,aAAa,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEjF,0CAA0C;IAC1C,GAAG,CAAC,QAAQ,EAAE,KAAK,GAAG,MAAM,IAAI,CAAC;IAEjC,0CAA0C;IAC1C,UAAU,IAAI;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IACvD,iBAAiB,CAAC,UAAU,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,GAC1D,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AASpD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,YAAY,SAAS,UAAU,GAAG,SAAS,EAC3C,OAAO,EACP,OAAO,SAAS,MAAM,GAAG,MAAM,EAE/B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,GACpD,iBAAiB,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,CAkGnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,MAAM,MAC9C,YAAY,SAAS,UAAU,GAAG,SAAS,EAAE,OAAO,EAC1D,MAAM,MAAM,EACZ,QAAQ,aAAa,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,KACpD,iBAAiB,CAAC,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,CAErD;AAED,mBAAmB;AACnB,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,iBAAiB,CAEtE;AAED,iEAAiE;AACjE,MAAM,MAAM,YAAY,CAAC,CAAC,IACxB,CAAC,SAAS,iBAAiB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AAEhF,4CAA4C;AAC5C,MAAM,MAAM,aAAa,CAAC,CAAC,IACzB,CAAC,SAAS,iBAAiB,CAAC,UAAU,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEnF,8DAA8D;AAC9D,MAAM,MAAM,aAAa,CAAC,CAAC,IACzB,CAAC,SAAS,iBAAiB,CAAC,UAAU,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpF,2DAA2D;AAC3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/define-handler.js

@@ -3,114 +3,170 @@
  *
  *   const GetStation = defineHandler("GetStation", {
  *     input:   z.object({ stationId: z.string() }),
+ *     handler: async ({ input }) => loadStation(input.stationId),
  *     returns: Station,
- *     handler: async ({ input, db }) => db.stations.findById(input.stationId),
+ *     errors:  [NotFound],
  *   });
  *
- * The shape is universal — same primitive whether the operation is exposed
- * via HTTP, queue, MCP, CLI, or invoked directly via `execute(handler, input)`.
- * Every transport binds via its own `(binding, handler, options)` signature;
- * the binding narrows the input contract at the boundary, the handler is
- * the lowest-common-denominator inside.
+ *   GetStation({ stationId: "abc" })                  // mint a prepared op
+ *   await GetStation({ stationId: "abc" }).run()      // run it
+ *   await GetStation.run({ input, signal })           // low-level hook surface
+ *   GetStation.use(myMiddleware)                      // attach a hook chain step
+ *   GetStation.on(observer)                           // attach a listener
  *
- *   See: architecture-sketch.html §08.
+ * The handler IS a `Hook` from `@nwire/hooks`. `.use()` attaches chain steps;
+ * `.on()` attaches parallel listeners; `.run()` executes. The user's handler
+ * function is the innermost chain step — registered at construction with
+ * `Number.MIN_SAFE_INTEGER` priority so every `.use(...)` wraps around it.
  *
- * Field placement follows the freq table:
- *   first-class — input, handler, returns, errors, summary, policy, emits
- *   meta        — tags, description, version, deprecated, successor
- *   settings    — retry, timeout, cache, idempotency
+ * **Ctx is generic.** The handler's ctx is `BaseHookCtx & { input } & TExtras`
+ * where `TExtras` is inferred from the handler's param annotation, or pinned
+ * once via `defineHandlerWith<TExtras>()` at the app boundary. Whatever you
+ * pass to `.run(ctx)` is what reaches the handler body, fully typed. No
+ * declaration merging on ctx — composition by value.
  *
- * `meta` + `settings` are open bags; adapters extend them via TS declaration
- * merging without touching the core type.
- *
- * NOTE: forge has its own `defineHandler(action, fn)` that binds a handler
- * to an existing `ActionDefinition`. That signature stays inside `@nwire/forge`
- * because it depends on the action machinery. The standalone version lives
- * here because every transport needs it without the forge surface.
+ * `meta` + `settings` ARE globally augmentable open interfaces. Those are
+ * declarative per-handler tags (policy, retry, persona, SLO) that plugins
+ * must discover across every handler — different role from ctx, different
+ * mechanism by design.
+ */
+import { hook, } from "@nwire/hooks";
+/**
+ * Tag for the terminal chain step that calls the user's handler function.
+ * Registered with `Number.MIN_SAFE_INTEGER` priority so every `.use()` from
+ * the consumer wraps around it (higher priority = runs first / outermost).
  */
-import { NoopLogger } from "@nwire/logger";
+const TERMINAL_STEP_NAME = "@nwire/handler/terminal";
 /**
  * Define a handler — the operation primitive.
  *
  *   const ListTodos = defineHandler("listTodos", {
  *     input:   z.object({ status: z.string().optional() }),
- *     handler: async ({ input, resolve }) => {
- *       const db = resolve<DB>("db");
- *       return db.todos.findMany(input);
- *     },
+ *     handler: async ({ input }) => todos.findMany(input),
  *   });
  *
  *   // Direct invocation:
- *   const todos = await execute(ListTodos, { status: "open" });
+ *   const result = await ListTodos({ status: "open" }).run();
  *
- *   // HTTP transport:
- *   api.wire(get("/todos"), ListTodos);
+ *   // Hook composition:
+ *   ListTodos.use(withTimeout(5000));
+ *   ListTodos.on(record => otel.span(...));
  *
- *   // Queue transport (same handler):
- *   workers.wire(job("listTodos"), ListTodos);
+ *   // Low-level hook surface (transports use this):
+ *   await ListTodos.run({ input: { status: "open" }, signal });
  */
 export function defineHandler(name, config) {
-    return {
-        $kind: "handler",
-        name,
-        config,
-        run(ctx) {
-            return config.handler(ctx);
-        },
+    const h = hook(name);
+    // Innermost step — runs the user's handler after every `.use()` has had
+    // its chance to wrap. Validation happens here (parse against config.input)
+    // so middleware that mutates ctx.input does so BEFORE validation. The
+    // chain ctx is forwarded so middleware-contributed fields (TExtras —
+    // cradle, user, tenant, logger, …) flow through.
+    h.use(async (ctx, next) => {
+        ctx.signal?.throwIfAborted();
+        const parsed = config.input ? config.input.parse(ctx.input) : ctx.input;
+        ctx.input = parsed;
+        const result = await config.handler(ctx);
+        ctx.result = result;
+        await next();
+    }, {
+        name: TERMINAL_STEP_NAME,
+        priority: Number.MIN_SAFE_INTEGER,
+    });
+    // The factory is a callable function. `Object.defineProperty` attaches the
+    // metadata + delegated hook methods + the `$kind` discriminator.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const factory = (input) => {
+        const prepared = {
+            input: input,
+            async run(opts) {
+                const ctx = {
+                    input,
+                    ...(opts?.ctx ?? {}),
+                };
+                const out = await h.run(ctx, { signal: opts?.signal });
+                return out.result;
+            },
+        };
+        return prepared;
     };
-}
-/** Type narrow. */
-export function isHandlerDefinition(x) {
-    return typeof x === "object" && x !== null && x.$kind === "handler";
+    Object.defineProperties(factory, {
+        $kind: { value: "handler", enumerable: true },
+        name: { value: name, enumerable: true, configurable: true },
+        config: { value: config, enumerable: true },
+        toString: { value: () => name, enumerable: false },
+        $hook: { value: h, enumerable: false, configurable: true },
+        use: {
+            value: function use(fn, opts) {
+                h.use(fn, opts);
+                return factory;
+            },
+            enumerable: false,
+        },
+        on: {
+            value: function on(fn, opts) {
+                h.on(fn, opts);
+                return factory;
+            },
+            enumerable: false,
+        },
+        off: {
+            value: function off(fn) {
+                h.off(fn);
+                return factory;
+            },
+            enumerable: false,
+        },
+        run: {
+            value: function run(ctx, opts) {
+                return h.run(ctx, opts);
+            },
+            enumerable: false,
+        },
+        runDetailed: {
+            value: function runDetailed(ctx, opts) {
+                return h.runDetailed(ctx, opts);
+            },
+            enumerable: false,
+        },
+        tap: {
+            value: function tap(observer) {
+                return h.tap(observer);
+            },
+            enumerable: false,
+        },
+        stepCounts: {
+            value: function stepCounts() {
+                return h.stepCounts();
+            },
+            enumerable: false,
+        },
+    });
+    return factory;
 }
 /**
- * Invoke a handler directly with input. The framework validates input
- * against the handler's `input` schema (if declared), constructs the
- * handler context, runs the handler, and returns its result.
+ * App-boundary sugar — pin `TExtras` once so every handler in the app reads
+ * `ctx` as the bound shape without per-call annotations.
+ *
+ *   // app/action.ts
+ *   type AppExtras = { cradle: AppCradle; user: User };
+ *   export const action = defineHandlerWith<AppExtras>();
  *
- *   const todos = await execute(ListTodos, { status: "open" });
+ *   // every handler file:
+ *   import { action } from "@/action";
+ *   const PlaceOrder = action("placeOrder", {
+ *     input: z.object({ id: z.string() }),
+ *     handler: async ({ input, cradle, user }) => …   // fully typed, no annotation
+ *   });
  *
- * This is the universal "any host can mount it" entry point. Transports
- * call into `execute()` after parsing the binding's payload; tests call
- * `execute()` directly to bypass transport machinery.
+ *   // every transport / .run() call:
+ *   PlaceOrder.run({ input, signal, cradle, user });
  */
-export async function execute(handler, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-input, options = {}) {
-    const schema = handler.config.input;
-    const parsed = schema ? schema.parse(input) : input;
-    const container = options.container ?? minimalContainer();
-    const logger = options.logger ?? minimalLogger();
-    const ctx = {
-        input: parsed,
-        container,
-        resolve: (name) => container.resolve(name),
-        logger,
-        transport: options.transport,
-    };
-    return handler.run(ctx);
-}
-/** Minimal stub container — every resolve throws. Used when no container supplied. */
-function minimalContainer() {
-    const stub = {
-        resolve(name) {
-            throw new Error(`execute(): no container provided — cannot resolve "${name}". ` +
-                `Pass options.container or use a transport that wires one.`);
-        },
-        register() {
-            throw new Error("execute(): minimal container is read-only");
-        },
-        createScope() {
-            return minimalContainer();
-        },
-        has() {
-            return false;
-        },
-    };
-    return stub;
+export function defineHandlerWith() {
+    return (name, config) => defineHandler(name, config);
 }
-/** Minimal stub logger. No-op every method. */
-function minimalLogger() {
-    return new NoopLogger();
+/** Type narrow. */
+export function isHandlerDefinition(x) {
+    return typeof x === "function" && x.$kind === "handler";
 }
 //# sourceMappingURL=define-handler.js.map

package/dist/define-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-handler.js","sourceRoot":"","sources":["../src/define-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,OAAO,EAAE,UAAU,EAAe,MAAM,eAAe,CAAC;AAkGxD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,MAA4C;IAE5C,OAAO;QACL,KAAK,EAAE,SAAS;QAChB,IAAI;QACJ,MAAM;QACN,GAAG,CAAC,GAAG;YACL,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,mBAAmB;AACnB,MAAM,UAAU,mBAAmB,CAAC,CAAU;IAC5C,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAyB,CAAC,KAAK,KAAK,SAAS,CAAC;AAC/F,CAAC;AAeD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAiD;AACjD,8DAA8D;AAC9D,KAAoE,EACpE,UAA0B,EAAE;IAE5B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;IACpC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAEpD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,EAAE,CAAC;IAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;IAEjD,MAAM,GAAG,GAAmB;QAC1B,KAAK,EAAE,MAAM;QACb,SAAS;QACT,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;QAC1C,MAAM;QACN,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC;IAEF,OAAO,OAAO,CAAC,GAAG,CAChB,GAA2F,CAC5F,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,SAAS,gBAAgB;IACvB,MAAM,IAAI,GAAc;QACtB,OAAO,CAAI,IAAY;YACrB,MAAM,IAAI,KAAK,CACb,sDAAsD,IAAI,KAAK;gBAC7D,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QACD,QAAQ;YACN,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,WAAW;YACT,OAAO,gBAAgB,EAAE,CAAC;QAC5B,CAAC;QACD,GAAG;YACD,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+CAA+C;AAC/C,SAAS,aAAa;IACpB,OAAO,IAAI,UAAU,EAAE,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"define-handler.js","sourceRoot":"","sources":["../src/define-handler.ts"],"names":[],"mappings":"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"}

package/dist/handler-index.d.ts

@@ -1,27 +1,20 @@
 /**
  * `@nwire/handler` — the operation primitive.
  *
- * Per the sealed architecture (§05), every transport (HTTP, queue,
- * MCP, CLI, …) speaks the same handler shape. This package ships that
- * shape — the operation as value — without dragging in forge's action /
- * actor / event machinery. A NestJS team can import `defineHandler`
- * from here, mount it on Express, and never touch `@nwire/forge`.
- *
- * `@nwire/forge` re-exports the same names so existing call sites keep
- * compiling unchanged. Forge layers `defineAction = defineHandler +
- * { flavor: "action", emits }` on top — same primitive, additional
- * semantics for the event-driven path.
+ * A handler is a typed, callable, hookable value built on `@nwire/hooks`.
+ * One value, every transport (HTTP, queue, MCP, CLI, direct test) —
+ * standalone, no DI, no events, no logger, no transport opinions. Ctx is
+ * generic; the app pins `TExtras` via `defineHandlerWith<TExtras>()` once
+ * at the boot site and every handler reads `ctx` as the bound shape with
+ * full autocomplete, zero per-call annotations.
  *
  * Public surface:
  *
  *   Primitives
- *     defineHandler(name, config) — the operation primitive
- *     execute(handler, input)     — direct invocation
- *     defineError(meta)           — typed throwable
- *     defineResource(name, opts)  — interface/response shape
- *     defineMiddleware            — chain step
- *     defineHook                  — before/after-only step
- *     pipe(...steps)              — compose chain
+ *     defineHandler(name, config)        — the operation primitive
+ *     defineHandlerWith<TExtras>()       — app-boundary factory binding
+ *     defineError(meta)                  — typed throwable
+ *     defineResource(name, opts)         — interface/response shape
  *
  *   Response factories
  *     ok / ok.list / created / accepted / noContent / notModified / gone
@@ -30,12 +23,14 @@
  *     Unauthorized / Forbidden / NotFound / Conflict / Gone / BadRequest
  *
  *   Types
- *     HandlerDefinition / HandlerConfig / HandlerContext / HandlerLike
- *     ResponseInstance / ResponseSpec / ChainFn / NwireError
+ *     HandlerDefinition / HandlerConfig / Ctx / HandlerBaseCtx
+ *     HandlerRunCtx / PreparedOp / HandlerLike
+ *     HandlerMeta / HandlerSettings (empty bags — extend via declaration merging)
+ *     HandlerInput<H> / HandlerOutput<H> / HandlerExtras<H>
+ *     ResponseInstance / ResponseSpec / NwireError
  */
-export { defineHandler, execute, isHandlerDefinition, type HandlerDefinition, type HandlerConfig, type HandlerContext, type HandlerMeta, type HandlerSettings, type HandlerReturnsSpec, type HandlerPolicy, type HandlerLike, type ExecuteOptions, } from "./define-handler.js";
+export { defineHandler, defineHandlerWith, isHandlerDefinition, type HandlerDefinition, type HandlerConfig, type HandlerBaseCtx, type Ctx, type HandlerMeta, type HandlerSettings, type HandlerReturnsSpec, type HandlerRunCtx, type HandlerLike, type PreparedOp, type PreparedOpRunOptions, type HandlerInput, type HandlerOutput, type HandlerExtras, type InferInput, type ResponseInstance, } from "./define-handler.js";
 export { defineError, isNwireError, NwireError, Unauthorized, Forbidden, NotFound, Gone, BadRequest, Conflict, type ErrorDefinition, type ErrorMeta, } from "./define-error.js";
 export { defineResource, isResourceDefinition, type ResourceDefinition, type DefineResourceOptions, } from "./define-resource.js";
-export { defineMiddleware, defineHook, pipe, unwindPipe, isMiddleware, isHook, isPipe, type MiddlewareDefinition, type HookDefinition, type MiddlewarePipe, type PipeStep, type ChainFn, type ResolverCtx, type Next, } from "./define-middleware.js";
-export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, type ResponseSpec, type ListResponseSpec, type ResponseInstance, type ResponseSpecBase, type ResponseKind, } from "./response.js";
+export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, type ResponseSpec, type ListResponseSpec, type ResponseSpecBase, type ResponseKind, } from "./response.js";
 //# sourceMappingURL=handler-index.d.ts.map

package/dist/handler-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler-index.d.ts","sourceRoot":"","sources":["../src/handler-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACL,aAAa,EACb,OAAO,EACP,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,UAAU,EACV,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,IAAI,EACJ,UAAU,EACV,YAAY,EACZ,MAAM,EACN,MAAM,EACN,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,IAAI,GACV,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,EAAE,EACF,OAAO,EACP,QAAQ,EACR,SAAS,EACT,WAAW,EACX,IAAI,EACJ,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"handler-index.d.ts","sourceRoot":"","sources":["../src/handler-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,GAAG,EACR,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,UAAU,EACV,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,EAAE,EACF,OAAO,EACP,QAAQ,EACR,SAAS,EACT,WAAW,EACX,IAAI,EACJ,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC"}

package/dist/handler-index.js

@@ -1,27 +1,20 @@
 /**
  * `@nwire/handler` — the operation primitive.
  *
- * Per the sealed architecture (§05), every transport (HTTP, queue,
- * MCP, CLI, …) speaks the same handler shape. This package ships that
- * shape — the operation as value — without dragging in forge's action /
- * actor / event machinery. A NestJS team can import `defineHandler`
- * from here, mount it on Express, and never touch `@nwire/forge`.
- *
- * `@nwire/forge` re-exports the same names so existing call sites keep
- * compiling unchanged. Forge layers `defineAction = defineHandler +
- * { flavor: "action", emits }` on top — same primitive, additional
- * semantics for the event-driven path.
+ * A handler is a typed, callable, hookable value built on `@nwire/hooks`.
+ * One value, every transport (HTTP, queue, MCP, CLI, direct test) —
+ * standalone, no DI, no events, no logger, no transport opinions. Ctx is
+ * generic; the app pins `TExtras` via `defineHandlerWith<TExtras>()` once
+ * at the boot site and every handler reads `ctx` as the bound shape with
+ * full autocomplete, zero per-call annotations.
  *
  * Public surface:
  *
  *   Primitives
- *     defineHandler(name, config) — the operation primitive
- *     execute(handler, input)     — direct invocation
- *     defineError(meta)           — typed throwable
- *     defineResource(name, opts)  — interface/response shape
- *     defineMiddleware            — chain step
- *     defineHook                  — before/after-only step
- *     pipe(...steps)              — compose chain
+ *     defineHandler(name, config)        — the operation primitive
+ *     defineHandlerWith<TExtras>()       — app-boundary factory binding
+ *     defineError(meta)                  — typed throwable
+ *     defineResource(name, opts)         — interface/response shape
  *
  *   Response factories
  *     ok / ok.list / created / accepted / noContent / notModified / gone
@@ -30,12 +23,14 @@
  *     Unauthorized / Forbidden / NotFound / Conflict / Gone / BadRequest
  *
  *   Types
- *     HandlerDefinition / HandlerConfig / HandlerContext / HandlerLike
- *     ResponseInstance / ResponseSpec / ChainFn / NwireError
+ *     HandlerDefinition / HandlerConfig / Ctx / HandlerBaseCtx
+ *     HandlerRunCtx / PreparedOp / HandlerLike
+ *     HandlerMeta / HandlerSettings (empty bags — extend via declaration merging)
+ *     HandlerInput<H> / HandlerOutput<H> / HandlerExtras<H>
+ *     ResponseInstance / ResponseSpec / NwireError
  */
-export { defineHandler, execute, isHandlerDefinition, } from "./define-handler.js";
+export { defineHandler, defineHandlerWith, isHandlerDefinition, } from "./define-handler.js";
 export { defineError, isNwireError, NwireError, Unauthorized, Forbidden, NotFound, Gone, BadRequest, Conflict, } from "./define-error.js";
 export { defineResource, isResourceDefinition, } from "./define-resource.js";
-export { defineMiddleware, defineHook, pipe, unwindPipe, isMiddleware, isHook, isPipe, } from "./define-middleware.js";
 export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, } from "./response.js";
 //# sourceMappingURL=handler-index.js.map

package/dist/handler-index.js.map

@@ -1 +1 @@
-{"version":3,"file":"handler-index.js","sourceRoot":"","sources":["../src/handler-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACL,aAAa,EACb,OAAO,EACP,mBAAmB,GAUpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,UAAU,EACV,QAAQ,GAGT,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,oBAAoB,GAGrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,IAAI,EACJ,UAAU,EACV,YAAY,EACZ,MAAM,EACN,MAAM,GAQP,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,EAAE,EACF,OAAO,EACP,QAAQ,EACR,SAAS,EACT,WAAW,EACX,IAAI,GAML,MAAM,eAAe,CAAC"}
+{"version":3,"file":"handler-index.js","sourceRoot":"","sources":["../src/handler-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,mBAAmB,GAiBpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,UAAU,EACV,QAAQ,GAGT,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,oBAAoB,GAGrB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,EAAE,EACF,OAAO,EACP,QAAQ,EACR,SAAS,EACT,WAAW,EACX,IAAI,GAKL,MAAM,eAAe,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nwire/handler",
-  "version": "0.8.17",
-  "description": "Nwire — the operation primitive. defineHandler / defineError / defineResource / defineMiddleware / pipe / response factories / typed framework errors. Standalone — depend on this without pulling forge. Every transport (HTTP, queue, MCP, …) speaks the same handler shape.",
+  "version": "0.9.1",
+  "description": "Nwire — the operation primitive. Typed, callable, hookable value built on @nwire/hooks. defineHandler / defineError / defineResource / response factories / framework errors. Standalone; every transport (HTTP, queue, MCP, CLI) speaks the same handler shape.",
   "keywords": [
     "execute",
     "handler",
@@ -28,11 +28,8 @@
   },
   "dependencies": {
     "zod": "^4.0.0",
-    "@nwire/container": "0.8.17",
-    "@nwire/envelope": "0.8.17",
-    "@nwire/hooks": "0.8.17",
-    "@nwire/logger": "0.8.17",
-    "@nwire/messages": "0.8.17"
+    "@nwire/messages": "0.9.1",
+    "@nwire/hooks": "0.9.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",