@nwire/hooks 0.7.1 → 0.8.0

package/dist/record.js

@@ -0,0 +1,86 @@
+/**
+ * Recording + replay.
+ *
+ * Recording a hook run produces a {@link Recording} — the full step trace
+ * plus user-supplied ctx snapshots taken before and after. Replays the
+ * recording later (or in another process) and assert step-by-step shape
+ * matches. This is the substrate Studio's "replay this trace" button and
+ * the deterministic debug flow are built on.
+ *
+ * Two scopes:
+ *
+ *   record(hook, ctx, opts?)      one-shot: run the hook, snapshot ctx, return Recording
+ *   replay(hook, recording, opts) re-run with the recorded ctxIn; compare shapes
+ *
+ * The clone strategy is pluggable; default is `structuredClone`. Pass
+ * `clone: (x) => JSON.parse(JSON.stringify(x))` for non-clonable shapes.
+ */
+const defaultClone = (ctx) => {
+    if (typeof structuredClone === "function")
+        return structuredClone(ctx);
+    // Last-resort fallback for environments without structuredClone.
+    return JSON.parse(JSON.stringify(ctx));
+};
+/**
+ * Run the hook once, capture ctx-in/out + every observation. Result is a
+ * self-contained {@link Recording} that can be persisted (JSON-safe if the
+ * caller's clone yields JSON-safe shapes), shipped to Studio, or fed back
+ * into `replay()`.
+ */
+export async function record(hook, ctx, opts = {}) {
+    const clone = opts.clone ?? defaultClone;
+    const ctxIn = clone(ctx);
+    const result = await hook.runDetailed(ctx, opts);
+    const ctxOut = clone(result.ctx);
+    return {
+        hookId: "id" in hook ? hook.id : "unknown",
+        hookName: hook.name,
+        runId: result.runId,
+        outcome: result.outcome,
+        steps: result.steps,
+        ctxIn,
+        ctxOut,
+        capturedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Replay a recording. Re-runs the hook with `recording.ctxIn` (cloned),
+ * compares the resulting step sequence + outcome against the recording,
+ * and reports drift. This is observational — it does not stub side effects.
+ * Pure / idempotent chains should match; non-deterministic chains report
+ * their drift so a human can decide whether it's expected.
+ */
+export async function replay(hook, recording, opts = {}) {
+    const clone = opts.clone ?? defaultClone;
+    const inputCtx = clone(recording.ctxIn);
+    const result = await hook.runDetailed(inputCtx, opts);
+    const drift = [];
+    if (result.outcome !== recording.outcome) {
+        drift.push(`outcome: recorded=${recording.outcome} replayed=${result.outcome}`);
+    }
+    if (result.steps.length !== recording.steps.length) {
+        drift.push(`step count: recorded=${recording.steps.length} replayed=${result.steps.length}`);
+    }
+    // Compare step sequences by (stepKind, stepName, phase). Durations + ts
+    // are inherently non-deterministic — we exclude them from the compare.
+    const lim = Math.min(result.steps.length, recording.steps.length);
+    for (let i = 0; i < lim; i++) {
+        const r = recording.steps[i];
+        const p = result.steps[i];
+        if (r.stepKind !== p.stepKind || r.stepName !== p.stepName || r.phase !== p.phase) {
+            drift.push(`step[${i}]: recorded=${r.stepKind}/${r.stepName ?? ""}/${r.phase} ` +
+                `replayed=${p.stepKind}/${p.stepName ?? ""}/${p.phase}`);
+        }
+    }
+    return {
+        matches: drift.length === 0,
+        drift,
+        recorded: recording,
+        replayed: {
+            ctx: result.ctx,
+            stepCount: result.steps.length,
+            outcome: result.outcome,
+        },
+    };
+}
+//# sourceMappingURL=record.js.map

package/dist/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Process-wide registry + topology helpers.
+ *
+ * Everything that needs to be ambient — the "current run" context that
+ * lets nested `.run()` calls link as children, plus the introspection
+ * list `nwire scan` and Studio consume — lives here. One module, no
+ * deps beyond `node:async_hooks` (stdlib).
+ */
+import type { Hook } from "./hook.js";
+import type { SourceLocation } from "./types.js";
+/** Internal — called by `hook()` after instantiation. */
+export declare function registerHook(hook: Hook<unknown>, source?: SourceLocation): void;
+/**
+ * Metadata for every hook created in this process. Scan + Studio call
+ * this to enumerate the world; it returns a snapshot, mutating it has
+ * no effect on the registry.
+ */
+export declare function listHooks(): ReadonlyArray<{
+    readonly id: string;
+    readonly name: string;
+    readonly chain: number;
+    readonly listeners: number;
+    readonly source?: SourceLocation;
+}>;
+/** Clear the registry. Test-only — never call in production paths. */
+export declare function __resetRegistryForTests(): void;
+/**
+ * Walk the V8 stack, skip frames that originate inside `@nwire/*` packages,
+ * return the first user-code frame. `skipFrames` lets call sites that are
+ * one or two helpers deep aim past their own wrapper.
+ */
+export declare function captureSourceLocation(skipFrames?: number): SourceLocation | undefined;
+interface RunContext {
+    readonly runId: string;
+    readonly hookId: string;
+    readonly parentRunId?: string;
+}
+/** Monotonic id for the next `.run()`. Shared across module instances. */
+export declare function nextRunId(): string;
+/** Monotonic id assigned to each `hook()` at construction. */
+export declare function nextHookId(): string;
+/**
+ * Run a function with a {@link RunContext} active for the duration. Nested
+ * `.run()` calls inside `fn` see this context via {@link currentRun} and
+ * pick up `runId` as their `parentRunId`.
+ */
+export declare function withRunContext<T>(ctx: RunContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * The active run context, if any. Returns undefined when called outside
+ * a hook run — that's the normal case for top-level dispatch.
+ */
+export declare function currentRun(): RunContext | undefined;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AA6B9C,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,aAAa,CAAC;IACzC,QAAQ,CAAC,EAAE,EAAQ,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAM,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAK,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAC,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAG,cAAc,CAAC;CACnC,CAAC,CAQD;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAaD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,SAAI,GAAG,cAAc,GAAG,SAAS,CAehF;AAID,UAAU,UAAU;IAClB,QAAQ,CAAC,KAAK,EAAS,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAQ,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID,0EAA0E;AAC1E,wBAAgB,SAAS,IAAI,MAAM,CAGlC;AAED,8DAA8D;AAC9D,wBAAgB,UAAU,IAAI,MAAM,CAGnC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEnF;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,UAAU,GAAG,SAAS,CAEnD"}

package/dist/registry.js

@@ -0,0 +1,103 @@
+/**
+ * Process-wide registry + topology helpers.
+ *
+ * Everything that needs to be ambient — the "current run" context that
+ * lets nested `.run()` calls link as children, plus the introspection
+ * list `nwire scan` and Studio consume — lives here. One module, no
+ * deps beyond `node:async_hooks` (stdlib).
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+// Pin to globalThis so every instance of @nwire/hooks loaded into this
+// process (Node loader + jiti + tsx + …) shares one registry. Without
+// this, scan-time `listHooks()` ran against a different module graph
+// than user code and saw an empty list.
+const GLOBAL_KEY = "__nwire_hooks_registry__";
+const g = globalThis;
+const slot = (g[GLOBAL_KEY] ??= {
+    registry: [],
+    hookCounter: { value: 0 },
+    runCounter: { value: 0 },
+});
+const registry = slot.registry;
+/** Internal — called by `hook()` after instantiation. */
+export function registerHook(hook, source) {
+    registry.push({ hook, source });
+}
+/**
+ * Metadata for every hook created in this process. Scan + Studio call
+ * this to enumerate the world; it returns a snapshot, mutating it has
+ * no effect on the registry.
+ */
+export function listHooks() {
+    return registry.map(({ hook, source }) => ({
+        id: hook.id,
+        name: hook.name,
+        chain: hook.stepCounts().chain,
+        listeners: hook.stepCounts().listeners,
+        source,
+    }));
+}
+/** Clear the registry. Test-only — never call in production paths. */
+export function __resetRegistryForTests() {
+    registry.length = 0;
+}
+// ─── Source-location capture ──────────────────────────────────────────
+const PAREN_RE = /\(([^()]+):(\d+):(\d+)\)\s*$/;
+const PLAIN_RE = /\s+at\s+([^()\s]+):(\d+):(\d+)\s*$/;
+// Skip frames inside installed @nwire packages (node_modules) and inside
+// framework-source paths — but NOT inside test files under those packages,
+// so package-local tests can assert on captured user-code locations.
+// `[\\/]` accepts both POSIX `/` and Windows `\` separators because V8
+// stack frames emit native path syntax per-platform.
+const NWIRE_FRAME_RE = /(node_modules[\\/](@nwire[\\/]|\.pnpm[\\/]@nwire\+)|packages[\\/]nwire-[^\\/]+[\\/](src|dist)[\\/](?!__tests__[\\/]))/;
+/**
+ * Walk the V8 stack, skip frames that originate inside `@nwire/*` packages,
+ * return the first user-code frame. `skipFrames` lets call sites that are
+ * one or two helpers deep aim past their own wrapper.
+ */
+export function captureSourceLocation(skipFrames = 1) {
+    const err = new Error();
+    const stack = err.stack;
+    if (!stack)
+        return undefined;
+    const lines = stack.split("\n");
+    // First line is "Error" header; the +1 skips it.
+    for (let i = skipFrames + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (NWIRE_FRAME_RE.test(line))
+            continue;
+        const m = PAREN_RE.exec(line) ?? PLAIN_RE.exec(line);
+        if (!m)
+            continue;
+        const [, file, lineStr, colStr] = m;
+        return { file: file, line: Number(lineStr), column: Number(colStr) };
+    }
+    return undefined;
+}
+const runContext = new AsyncLocalStorage();
+/** Monotonic id for the next `.run()`. Shared across module instances. */
+export function nextRunId() {
+    slot.runCounter.value += 1;
+    return `r${slot.runCounter.value.toString(36)}-${Date.now().toString(36)}`;
+}
+/** Monotonic id assigned to each `hook()` at construction. */
+export function nextHookId() {
+    slot.hookCounter.value += 1;
+    return `h${slot.hookCounter.value.toString(36)}`;
+}
+/**
+ * Run a function with a {@link RunContext} active for the duration. Nested
+ * `.run()` calls inside `fn` see this context via {@link currentRun} and
+ * pick up `runId` as their `parentRunId`.
+ */
+export function withRunContext(ctx, fn) {
+    return runContext.run(ctx, fn);
+}
+/**
+ * The active run context, if any. Returns undefined when called outside
+ * a hook run — that's the normal case for top-level dispatch.
+ */
+export function currentRun() {
+    return runContext.getStore();
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAYrD,uEAAuE;AACvE,sEAAsE;AACtE,qEAAqE;AACrE,wCAAwC;AACxC,MAAM,UAAU,GAAG,0BAAmC,CAAC;AAQvD,MAAM,CAAC,GAAG,UAA+B,CAAC;AAC1C,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK;IAC9B,QAAQ,EAAK,EAAE;IACf,WAAW,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE;IACzB,UAAU,EAAG,EAAE,KAAK,EAAE,CAAC,EAAE;CAC1B,CAAC,CAAC;AACH,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;AAE/B,yDAAyD;AACzD,MAAM,UAAU,YAAY,CAAC,IAAmB,EAAE,MAAuB;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS;IAOvB,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QACzC,EAAE,EAAS,IAAI,CAAC,EAAE;QAClB,IAAI,EAAO,IAAI,CAAC,IAAI;QACpB,KAAK,EAAM,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK;QAClC,SAAS,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,SAAS;QACtC,MAAM;KACP,CAAC,CAAC,CAAC;AACN,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,uBAAuB;IACrC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtB,CAAC;AAED,yEAAyE;AAEzE,MAAM,QAAQ,GAAG,8BAA8B,CAAC;AAChD,MAAM,QAAQ,GAAG,oCAAoC,CAAC;AACtD,yEAAyE;AACzE,2EAA2E;AAC3E,qEAAqE;AACrE,uEAAuE;AACvE,qDAAqD;AACrD,MAAM,cAAc,GAAG,uHAAuH,CAAC;AAE/I;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAU,GAAG,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;IACxB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACxB,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,iDAAiD;IACjD,KAAK,IAAI,CAAC,GAAG,UAAU,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACvB,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QACxC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrD,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;QACpC,OAAO,EAAE,IAAI,EAAE,IAAK,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IACxE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAUD,MAAM,UAAU,GAAG,IAAI,iBAAiB,EAAc,CAAC;AAEvD,0EAA0E;AAC1E,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AAC7E,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,UAAU;IACxB,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC,CAAC;IAC5B,OAAO,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAI,GAAe,EAAE,EAAoB;IACrE,OAAO,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,UAAU,CAAC,QAAQ,EAAE,CAAC;AAC/B,CAAC"}

package/dist/types.d.ts

@@ -1,23 +1,52 @@
 /**
- * Public types for `@nwire/hooks`. See architecture-sketch.html §06–§07.
+ * Public types for `@nwire/hooks`.
+ *
+ * The two function shapes:
+ *   - ChainFn — koa-compose middleware. Wraps next(); can short-circuit.
+ *   - ListenerFn — parallel observer. Reads the final ctx; never mutates.
+ *
+ * The observability surface (StepObservation / RunResult / Recording) is the
+ * contract every consumer relies on for tracing, scan, Studio, OTel, replay.
  */
 /** A single link in a chain — koa-compose-shaped middleware. */
 export type ChainFn<Ctx> = (ctx: Ctx, next: () => Promise<void>) => Promise<void> | void;
 /** A listener — observes the final ctx state, never mutates it. */
 export type ListenerFn<Ctx> = (ctx: Readonly<Ctx>) => Promise<void> | void;
-/** Options for {@link createHook}/{@link hook}. */
+/** Where this hook (or step) was authored. Captured at attach time. */
+export interface SourceLocation {
+    readonly file: string;
+    readonly line: number;
+    readonly column?: number;
+}
+/** Options for `hook()` / `createHook()`. */
 export interface HookOptions<Ctx> {
     /**
      * If true, listener errors are re-thrown by `.run()` instead of being
-     * collected and surfaced via `onListenerError`. Default: false (conservative).
+     * collected and surfaced via `onListenerError`. Default: false.
      */
     strictListeners?: boolean;
     /**
-     * Called once per listener error. Defaults to `console.error`. A host
-     * (e.g. `createHooks(...)`) wires its `lifecycle.error` hook here.
+     * Called once per listener error. Defaults to console.error. Hosts can
+     * route this through their own logger / framework-event bus.
      */
     onListenerError?: (err: unknown, ctx: Readonly<Ctx>, hookName: string) => void;
 }
+/** Optional per-step metadata supplied at `.use()` / `.on()` time. */
+export interface UseOptions {
+    /** Human label — shown in tap events, OTel spans, Studio. */
+    readonly name?: string;
+    /** Higher runs first (= outermost in chain). Default 0. */
+    readonly priority?: number;
+}
+export interface OnOptions extends UseOptions {
+    /**
+     * Filter when this listener fires relative to the chain outcome.
+     *   "always"   — fire on completed + prevented + failed (default).
+     *   "success"  — fire only when the chain completed without throw.
+     *   "failure"  — fire only when the chain threw.
+     */
+    readonly when?: "always" | "success" | "failure";
+}
 /** Retry policy for {@link withRetry}. */
 export interface RetryOpts {
     /** Total attempts (including the first). Must be >= 1. */
@@ -27,4 +56,67 @@ export interface RetryOpts {
     /** Optional predicate — return false to stop retrying a given error. */
     shouldRetry?: (err: unknown, attempt: number) => boolean;
 }
+export type StepKind = "chain" | "listener";
+export type StepPhase = "start" | "end" | "error";
+export type RunOutcome = "completed" | "prevented" | "failed";
+/** One observation emitted to taps. Tagged union by `phase`. */
+export interface StepObservation {
+    /** Hook name, stable across runs. */
+    readonly hookName: string;
+    /** Hook instance id — unique per `hook()` call in this process. */
+    readonly hookId: string;
+    /** Run id — unique per `.run()` invocation. */
+    readonly runId: string;
+    /** Parent run id when this `.run()` was started inside another. */
+    readonly parentRunId?: string;
+    /** Monotonic step id within the hook (insertion order). */
+    readonly stepId: number;
+    readonly stepKind: StepKind;
+    /** Optional human label from {@link UseOptions.name} / {@link OnOptions.name}. */
+    readonly stepName?: string;
+    readonly phase: StepPhase;
+    /** performance.now() timestamp at observation. */
+    readonly ts: number;
+    /** Set on `end` and `error`. Milliseconds since matching `start`. */
+    readonly durationMs?: number;
+    /** Set on `error`. */
+    readonly error?: unknown;
+}
+/** Subscriber to a hook's per-step observations. */
+export type TapFn = (obs: StepObservation) => void;
+/** Per-run options. */
+export interface RunOptions {
+    /** Abort the run. Listeners may inspect; chains may bail mid-flight. */
+    readonly signal?: AbortSignal;
+    /** Explicit parent. When omitted, picks up the ambient parent. */
+    readonly parentRunId?: string;
+}
+/** Detailed result returned by {@link Hook.runDetailed}. */
+export interface RunResult<Ctx> {
+    readonly ctx: Ctx;
+    readonly outcome: RunOutcome;
+    readonly runId: string;
+    readonly parentRunId?: string;
+    readonly steps: ReadonlyArray<StepObservation>;
+    readonly durationMs: number;
+    /** Set when outcome === "failed". */
+    readonly error?: unknown;
+}
+/**
+ * A recorded run, complete enough to replay step-by-step.
+ *
+ * `ctxIn` / `ctxOut` are snapshots provided by the caller — the recorder
+ * does not serialize ctx itself (ctx shapes are domain-specific). Callers
+ * usually pass `structuredClone(ctx)` before and after.
+ */
+export interface Recording {
+    readonly hookId: string;
+    readonly hookName: string;
+    readonly runId: string;
+    readonly outcome: RunOutcome;
+    readonly steps: ReadonlyArray<StepObservation>;
+    readonly ctxIn: unknown;
+    readonly ctxOut: unknown;
+    readonly capturedAt: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gEAAgE;AAChE,MAAM,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzF,mEAAmE;AACnE,MAAM,MAAM,UAAU,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE3E,mDAAmD;AACnD,MAAM,WAAW,WAAW,CAAC,GAAG;IAC9B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAChF;AAED,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,gEAAgE;AAChE,MAAM,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzF,mEAAmE;AACnE,MAAM,MAAM,UAAU,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE3E,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAI,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAI,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAW,CAAC,GAAG;IAC9B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAChF;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,CAAC,EAAM,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;CAClD;AAED,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D;AAID,MAAM,MAAM,QAAQ,GAAI,OAAO,GAAG,UAAU,CAAC;AAC7C,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE9D,gEAAgE;AAChE,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAM,MAAM,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAQ,MAAM,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAS,MAAM,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAQ,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAM,QAAQ,CAAC;IAChC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAK,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAS,SAAS,CAAC;IACjC,kDAAkD;IAClD,QAAQ,CAAC,EAAE,EAAY,MAAM,CAAC;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAG,MAAM,CAAC;IAC9B,sBAAsB;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAQ,OAAO,CAAC;CAChC;AAED,oDAAoD;AACpD,MAAM,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAC;AAEnD,uBAAuB;AACvB,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAO,WAAW,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,4DAA4D;AAC5D,MAAM,WAAW,SAAS,CAAC,GAAG;IAC5B,QAAQ,CAAC,GAAG,EAAY,GAAG,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAQ,UAAU,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAU,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAU,aAAa,CAAC,eAAe,CAAC,CAAC;IACvD,QAAQ,CAAC,UAAU,EAAK,MAAM,CAAC;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAS,OAAO,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAK,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAG,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAI,UAAU,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAM,aAAa,CAAC,eAAe,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAM,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAK,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B"}

package/dist/types.js

@@ -1,5 +1,12 @@
 /**
- * Public types for `@nwire/hooks`. See architecture-sketch.html §06–§07.
+ * Public types for `@nwire/hooks`.
+ *
+ * The two function shapes:
+ *   - ChainFn — koa-compose middleware. Wraps next(); can short-circuit.
+ *   - ListenerFn — parallel observer. Reads the final ctx; never mutates.
+ *
+ * The observability surface (StepObservation / RunResult / Recording) is the
+ * contract every consumer relies on for tracing, scan, Studio, OTel, replay.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/hooks",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Nwire — the universal dispatch primitive. One hook() accepts both .use() (sequential koa-compose chain) and .on() (parallel listener) attachments. Built on emittery + a ~30 LOC composer. Standalone, in-process only, ~100 LOC of surface.",
   "keywords": [
     "dispatch",