@nwire/telemetry 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/auto-install.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Dev auto-install — persist telemetry runs without any user code.
+ *
+ * When an app boots inside a project working directory, we install the local
+ * file reporter by default so every run lands in `.nwire/telemetry/*.jsonl`
+ * and shows up in Studio history. This is userland-unaware: no plugin, no
+ * config — the composition root (`createApp`) calls this once.
+ *
+ * "Project cwd" is detected two ways, in order:
+ *   1. `NWIRE_CWD` env var set — the dev / Studio host exports this. Its value
+ *      is the project root to write under.
+ *   2. A `.nwire` directory present in `process.cwd()` — a scanned project.
+ *
+ * It is deliberately gated OFF when neither holds (a bare unit test, a library
+ * import) and when running under Vitest (`VITEST` / `NODE_ENV=test`), so the
+ * test suite never writes stray run files. Returns the detach when installed,
+ * or `undefined` when it declined to install.
+ */
+import { type Runtime } from "@nwire/runtime";
+/**
+ * Resolve the project root to persist telemetry under, or `undefined` when the
+ * process is not running inside a project (so auto-install should decline).
+ */
+export declare function resolveProjectCwd(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Install the local file reporter on `runtime` when a project cwd is detected.
+ * No-op (returns `undefined`) otherwise. Safe to call unconditionally from the
+ * composition root.
+ */
+export declare function autoInstallFileReporter(runtime: Runtime, env?: NodeJS.ProcessEnv): (() => void) | undefined;

package/dist/auto-install.js

@@ -0,0 +1,48 @@
+/**
+ * Dev auto-install — persist telemetry runs without any user code.
+ *
+ * When an app boots inside a project working directory, we install the local
+ * file reporter by default so every run lands in `.nwire/telemetry/*.jsonl`
+ * and shows up in Studio history. This is userland-unaware: no plugin, no
+ * config — the composition root (`createApp`) calls this once.
+ *
+ * "Project cwd" is detected two ways, in order:
+ *   1. `NWIRE_CWD` env var set — the dev / Studio host exports this. Its value
+ *      is the project root to write under.
+ *   2. A `.nwire` directory present in `process.cwd()` — a scanned project.
+ *
+ * It is deliberately gated OFF when neither holds (a bare unit test, a library
+ * import) and when running under Vitest (`VITEST` / `NODE_ENV=test`), so the
+ * test suite never writes stray run files. Returns the detach when installed,
+ * or `undefined` when it declined to install.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { installTelemetryReporter } from "@nwire/runtime";
+import { fileTelemetryReporter } from "./file-telemetry-reporter.js";
+/**
+ * Resolve the project root to persist telemetry under, or `undefined` when the
+ * process is not running inside a project (so auto-install should decline).
+ */
+export function resolveProjectCwd(env = process.env) {
+    // Never auto-write during the test suite.
+    if (env.VITEST || env.NODE_ENV === "test")
+        return undefined;
+    if (env.NWIRE_CWD)
+        return env.NWIRE_CWD;
+    const cwd = process.cwd();
+    if (existsSync(join(cwd, ".nwire")))
+        return cwd;
+    return undefined;
+}
+/**
+ * Install the local file reporter on `runtime` when a project cwd is detected.
+ * No-op (returns `undefined`) otherwise. Safe to call unconditionally from the
+ * composition root.
+ */
+export function autoInstallFileReporter(runtime, env = process.env) {
+    const dir = resolveProjectCwd(env);
+    if (!dir)
+        return undefined;
+    return installTelemetryReporter(runtime, fileTelemetryReporter({ dir }));
+}

package/dist/file-telemetry-reporter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `fileTelemetryReporter` — the local disk telemetry sink.
+ *
+ * Appends every record from `runtime.onTelemetry` (via
+ * `installTelemetryReporter`) as one JSON line to
+ * `<dir>/.nwire/telemetry/<runId>.jsonl`. One file per run; `runId` defaults
+ * to a sortable timestamp id minted at construction so successive runs sort
+ * lexically. On construction it prunes the telemetry directory so only the
+ * newest `maxRuns` run files survive — restarts don't accumulate forever.
+ *
+ * This is the "local" driver of the telemetry-sink lane: no ingestion server,
+ * no network — the dev/Studio host tails these JSONL files to render run
+ * history. The cloud driver (OTLP → Vector → Greptime) is
+ * `@nwire/telemetry-otel`.
+ *
+ * Writes are buffered through a Node write stream so a record push never blocks
+ * dispatch on a syscall; `flush()` drains the buffer, `close()` ends the stream.
+ */
+import type { TelemetryReporter } from "@nwire/runtime";
+export interface FileTelemetryReporterOptions {
+    /** Project root. The reporter writes under `<dir>/.nwire/telemetry/`. */
+    readonly dir: string;
+    /**
+     * Run identifier — becomes the `<runId>.jsonl` filename. Defaults to a
+     * sortable timestamp id minted at construction (see {@link generateRunId}).
+     */
+    readonly runId?: string;
+    /**
+     * Keep only the newest N run files; older ones are pruned at construction.
+     * Default 20.
+     */
+    readonly maxRuns?: number;
+}
+/**
+ * Sortable run id: an ISO-8601 timestamp with the colons / dot stripped so it
+ * is filesystem-safe and still lexically sorts by time, plus a short random
+ * suffix so two runs started in the same millisecond don't collide.
+ *
+ *   2026-06-18T09-41-12-307Z-a1b2c3
+ */
+export declare function generateRunId(now?: Date): string;
+export declare function fileTelemetryReporter(opts: FileTelemetryReporterOptions): TelemetryReporter;

package/dist/file-telemetry-reporter.js

@@ -0,0 +1,128 @@
+/**
+ * `fileTelemetryReporter` — the local disk telemetry sink.
+ *
+ * Appends every record from `runtime.onTelemetry` (via
+ * `installTelemetryReporter`) as one JSON line to
+ * `<dir>/.nwire/telemetry/<runId>.jsonl`. One file per run; `runId` defaults
+ * to a sortable timestamp id minted at construction so successive runs sort
+ * lexically. On construction it prunes the telemetry directory so only the
+ * newest `maxRuns` run files survive — restarts don't accumulate forever.
+ *
+ * This is the "local" driver of the telemetry-sink lane: no ingestion server,
+ * no network — the dev/Studio host tails these JSONL files to render run
+ * history. The cloud driver (OTLP → Vector → Greptime) is
+ * `@nwire/telemetry-otel`.
+ *
+ * Writes are buffered through a Node write stream so a record push never blocks
+ * dispatch on a syscall; `flush()` drains the buffer, `close()` ends the stream.
+ */
+import { appendFileSync, createWriteStream, mkdirSync, readdirSync, rmSync, } from "node:fs";
+import { join } from "node:path";
+const TELEMETRY_SUBDIR = join(".nwire", "telemetry");
+const DEFAULT_MAX_RUNS = 20;
+/**
+ * Sortable run id: an ISO-8601 timestamp with the colons / dot stripped so it
+ * is filesystem-safe and still lexically sorts by time, plus a short random
+ * suffix so two runs started in the same millisecond don't collide.
+ *
+ *   2026-06-18T09-41-12-307Z-a1b2c3
+ */
+export function generateRunId(now = new Date()) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `${stamp}-${rand}`;
+}
+export function fileTelemetryReporter(opts) {
+    const runId = opts.runId ?? generateRunId();
+    const maxRuns = opts.maxRuns ?? DEFAULT_MAX_RUNS;
+    const telemetryDir = join(opts.dir, TELEMETRY_SUBDIR);
+    mkdirSync(telemetryDir, { recursive: true });
+    pruneRuns(telemetryDir, runId, maxRuns);
+    const filePath = join(telemetryDir, `${runId}.jsonl`);
+    // Touch the file synchronously so the run is visible the instant the reporter
+    // is constructed (the dev host watches the dir; the stream's own open is
+    // async and lazy). Append-mode so a re-attached runId keeps prior records.
+    appendFileSync(filePath, "");
+    let stream = createWriteStream(filePath, { flags: "a" });
+    // A write stream emits 'error' asynchronously (a vanished dir, a full disk).
+    // Without a listener Node turns it into an uncaught exception that would take
+    // the process down — telemetry must never do that. Swallow + log.
+    stream.on("error", (err) => {
+        // eslint-disable-next-line no-console
+        console.error(`[telemetry] file reporter "${runId}" stream error:`, err);
+    });
+    return {
+        name: `file:${runId}`,
+        report(record) {
+            if (!stream)
+                return;
+            // One JSON object per line. A record that can't serialize (a cycle, a
+            // BigInt) must not break the stream — drop it and note why.
+            let line;
+            try {
+                line = JSON.stringify(record);
+            }
+            catch (err) {
+                line = JSON.stringify({
+                    kind: "telemetry.unserializable",
+                    error: String(err),
+                    ts: new Date().toISOString(),
+                });
+            }
+            stream.write(line + "\n");
+        },
+        flush() {
+            const s = stream;
+            if (!s)
+                return Promise.resolve();
+            // Resolve once the OS buffer accepts the next write — the drain barrier
+            // that guarantees everything queued so far has been handed to the kernel.
+            return new Promise((resolve) => {
+                const ok = s.write("");
+                if (ok)
+                    resolve();
+                else
+                    s.once("drain", () => resolve());
+            });
+        },
+        close() {
+            const s = stream;
+            stream = undefined;
+            if (!s)
+                return Promise.resolve();
+            return new Promise((resolve, reject) => {
+                s.end((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}
+/**
+ * Keep only the newest `maxRuns` `.jsonl` files in `telemetryDir`, counting the
+ * run we're about to create. Files sort lexically (the run id is timestamp-
+ * prefixed), so the lexically-smallest are the oldest. Best-effort — a missing
+ * dir or an unreadable entry never blocks startup.
+ */
+function pruneRuns(telemetryDir, currentRunId, maxRuns) {
+    if (maxRuns <= 0)
+        return;
+    let existing;
+    try {
+        existing = readdirSync(telemetryDir).filter((f) => f.endsWith(".jsonl"));
+    }
+    catch {
+        return;
+    }
+    // The run we're about to open counts toward the cap, so leave room for it.
+    const keep = Math.max(0, maxRuns - 1);
+    const current = `${currentRunId}.jsonl`;
+    const others = existing.filter((f) => f !== current).sort();
+    const toDelete = others.slice(0, Math.max(0, others.length - keep));
+    for (const f of toDelete) {
+        try {
+            rmSync(join(telemetryDir, f));
+        }
+        catch {
+            /* best-effort — a locked / vanished file is fine to skip */
+        }
+    }
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@nwire/telemetry` — local telemetry reporters (sink terminals).
+ *
+ * The canonical telemetry stream (`runtime.onTelemetry`) is the SOURCE; a
+ * `TelemetryReporter` is the SINK terminal. This package ships the local
+ * disk driver — `fileTelemetryReporter` — which appends every record to a
+ * per-run JSONL file under `<dir>/.nwire/telemetry/`. The dev / Studio host
+ * tails those files to render run history with no ingestion server.
+ *
+ * Install a reporter with `installTelemetryReporter` from `@nwire/runtime`:
+ *
+ *   import { installTelemetryReporter } from "@nwire/runtime";
+ *   import { fileTelemetryReporter } from "@nwire/telemetry";
+ *
+ *   const detach = installTelemetryReporter(
+ *     app.runtime,
+ *     fileTelemetryReporter({ dir: process.cwd() }),
+ *   );
+ *
+ * Cloud / OTLP forwarding is a sibling driver — `@nwire/telemetry-otel`.
+ */
+export { fileTelemetryReporter, generateRunId, type FileTelemetryReporterOptions, } from "./file-telemetry-reporter.js";
+export { autoInstallFileReporter, resolveProjectCwd } from "./auto-install.js";
+export { installTopologyEmit, writeTopologyFile, TOPOLOGY_FILE_VERSION, type TopologyFile, } from "./topology-emit.js";
+export { captureTopology, type Topology, type CapabilityInfo, type StageInfo, type PluginInfo, type BindingInfo, type HandlerInfo, type HookInfo, type ContributionInfo, type TriggerInfo, type AppInfo, type RouteInfo, } from "./topology-capture.js";

package/dist/telemetry.js

@@ -0,0 +1,31 @@
+/**
+ * `@nwire/telemetry` — local telemetry reporters (sink terminals).
+ *
+ * The canonical telemetry stream (`runtime.onTelemetry`) is the SOURCE; a
+ * `TelemetryReporter` is the SINK terminal. This package ships the local
+ * disk driver — `fileTelemetryReporter` — which appends every record to a
+ * per-run JSONL file under `<dir>/.nwire/telemetry/`. The dev / Studio host
+ * tails those files to render run history with no ingestion server.
+ *
+ * Install a reporter with `installTelemetryReporter` from `@nwire/runtime`:
+ *
+ *   import { installTelemetryReporter } from "@nwire/runtime";
+ *   import { fileTelemetryReporter } from "@nwire/telemetry";
+ *
+ *   const detach = installTelemetryReporter(
+ *     app.runtime,
+ *     fileTelemetryReporter({ dir: process.cwd() }),
+ *   );
+ *
+ * Cloud / OTLP forwarding is a sibling driver — `@nwire/telemetry-otel`.
+ */
+export { fileTelemetryReporter, generateRunId, } from "./file-telemetry-reporter.js";
+// Dev auto-install — the composition root calls this so runs persist with no
+// user code, gated to project cwds (off in unit tests / library imports).
+export { autoInstallFileReporter, resolveProjectCwd } from "./auto-install.js";
+// Topology self-emit — a running app writes its own runtime wiring to
+// `.nwire/topology.json` so the static scanner can fold it in without booting.
+export { installTopologyEmit, writeTopologyFile, TOPOLOGY_FILE_VERSION, } from "./topology-emit.js";
+// Live-runtime topology capture — also re-exported by `@nwire/scan` for its
+// legacy instance-based manifest path.
+export { captureTopology, } from "./topology-capture.js";

package/dist/topology-capture.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The TOPOLOGY layer — the runtime wiring a static AST pass can't see, because
+ * plugins register imperatively. Captured by a lean boot-introspection over a
+ * booted App, read from the runtime's own surface (`describeCapabilities`,
+ * `listSourceStages`/`listSinkStages`, `listHandlers`, `container.list`, the
+ * hooks registry, the app's plugin list).
+ *
+ * This lives in `@nwire/telemetry` (a runtime lib) — not the scanner — because
+ * a running app emits its own topology to `.nwire/topology.json` (see
+ * `topology-emit.ts`), and the static scanner (`@nwire/scan`) folds that file
+ * into the manifest. The scanner re-exports `captureTopology` for the legacy
+ * instance-based path. Introspecting a live runtime is runtime-domain work, so
+ * the lib owns it.
+ *
+ * This is the "show the internals exactly — how, what, why" half: which plugins
+ * are installed, what each contributes (capabilities + the kinds they apply to +
+ * the ctx keys they add), the ordered source/sink stage pipelines, the
+ * ctx-surface-per-kind, the registered handlers by kind, the DI bindings, the
+ * hooks, and the transport triggers.
+ */
+export interface CapabilityInfo {
+    readonly name: string;
+    /** Handler kinds this capability's ctx applies to; undefined = universal. */
+    readonly kinds?: readonly string[];
+    /** ctx keys it contributes (probed). */
+    readonly ctxKeys: readonly string[];
+}
+export interface StageInfo {
+    readonly name: string;
+    readonly position: string;
+    readonly kind?: string;
+}
+export interface PluginInfo {
+    readonly name: string;
+}
+export interface BindingInfo {
+    readonly name: string;
+    readonly kind?: string;
+}
+export interface HandlerInfo {
+    readonly name: string;
+    /** `action` / `query` / `handler` / … — read off the registered handler. */
+    readonly kind: string;
+}
+export interface HookInfo {
+    readonly name: string;
+    readonly id?: string;
+    readonly chain?: number;
+    readonly listeners?: number;
+    /** Where the hook was authored — `file:line:column`, captured at attach time. */
+    readonly source?: {
+        readonly file: string;
+        readonly line: number;
+        readonly column?: number;
+    };
+}
+/**
+ * What a single plugin contributed to the app — DI bindings, capabilities,
+ * source/sink stages, registered handlers, and hooks. Attributed at boot by the
+ * app lifecycle; powers the `contributes` graph edge on Studio's Plugins page.
+ */
+export interface ContributionInfo {
+    readonly plugin: string;
+    readonly bindings: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly sourceStages: readonly string[];
+    readonly sinkStages: readonly string[];
+    readonly handlers: readonly string[];
+    readonly hooks: readonly string[];
+}
+/** A transport trigger: a wired binding → the handler it dispatches. */
+export interface TriggerInfo {
+    readonly binding: string;
+    readonly handler?: string;
+}
+/** An installed app (the BC). For a single captured app this is a one-element list. */
+export interface AppInfo {
+    readonly name: string;
+    readonly description?: string;
+    readonly plugins: readonly string[];
+}
+/** A transport route: method + path + the handler it mounts. */
+export interface RouteInfo {
+    readonly method: string;
+    readonly path: string;
+    readonly handler?: string;
+}
+export interface Topology {
+    readonly apps: readonly AppInfo[];
+    readonly plugins: readonly PluginInfo[];
+    readonly capabilities: readonly CapabilityInfo[];
+    /** kind → the ctx keys a handler of that kind receives (universal caps + kind-matched). */
+    readonly ctxByKind: Readonly<Record<string, readonly string[]>>;
+    readonly sourceStages: readonly StageInfo[];
+    readonly sinkStages: readonly StageInfo[];
+    readonly handlers: readonly HandlerInfo[];
+    readonly bindings: readonly BindingInfo[];
+    readonly hooks: readonly HookInfo[];
+    readonly triggers: readonly TriggerInfo[];
+    /** HTTP routes (method + path → handler) — the richer shape over `triggers`. */
+    readonly routes: readonly RouteInfo[];
+    /** Per-plugin contribution attribution — the `contributes` edge source. */
+    readonly contributions: readonly ContributionInfo[];
+}
+type Any = any;
+interface IntrospectableApp {
+    readonly appName?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly plugins?: ReadonlyArray<{
+        readonly name: string;
+    }>;
+    readonly pluginContributions?: () => ReadonlyArray<ContributionInfo>;
+    readonly container?: {
+        list?(): ReadonlyArray<{
+            readonly name: string;
+            readonly kind?: string;
+        }>;
+    };
+    readonly interface?: {
+        readonly wires?: ReadonlyArray<{
+            readonly binding?: Any;
+            readonly handler?: Any;
+        }>;
+    };
+    readonly runtime?: {
+        describeCapabilities?(): ReadonlyArray<{
+            name: string;
+            kinds?: readonly string[];
+            ctxKeys: readonly string[];
+        }>;
+        listSourceStages?(): ReadonlyArray<{
+            name: string;
+            position: string;
+            kind?: string;
+        }>;
+        listSinkStages?(): ReadonlyArray<{
+            name: string;
+            position: string;
+            kind?: string;
+        }>;
+        listHandlers?(): readonly string[];
+        getHandler?(name: string): Any;
+    };
+}
+/**
+ * Capture the topology from a booted App. Every read is guarded so a forge-less
+ * or transport-less app still produces a valid (sparser) topology.
+ */
+export declare function captureTopology(app: IntrospectableApp): Topology;
+export {};

package/dist/topology-capture.js

@@ -0,0 +1,145 @@
+/**
+ * The TOPOLOGY layer — the runtime wiring a static AST pass can't see, because
+ * plugins register imperatively. Captured by a lean boot-introspection over a
+ * booted App, read from the runtime's own surface (`describeCapabilities`,
+ * `listSourceStages`/`listSinkStages`, `listHandlers`, `container.list`, the
+ * hooks registry, the app's plugin list).
+ *
+ * This lives in `@nwire/telemetry` (a runtime lib) — not the scanner — because
+ * a running app emits its own topology to `.nwire/topology.json` (see
+ * `topology-emit.ts`), and the static scanner (`@nwire/scan`) folds that file
+ * into the manifest. The scanner re-exports `captureTopology` for the legacy
+ * instance-based path. Introspecting a live runtime is runtime-domain work, so
+ * the lib owns it.
+ *
+ * This is the "show the internals exactly — how, what, why" half: which plugins
+ * are installed, what each contributes (capabilities + the kinds they apply to +
+ * the ctx keys they add), the ordered source/sink stage pipelines, the
+ * ctx-surface-per-kind, the registered handlers by kind, the DI bindings, the
+ * hooks, and the transport triggers.
+ */
+import { listHooks } from "@nwire/hooks";
+/** Describe a wire binding compactly: `"POST /orders"`, a queue name, or its kind. */
+function describeBinding(binding) {
+    if (!binding || typeof binding !== "object")
+        return "binding";
+    const verb = binding.verb ?? binding.method;
+    if (verb && binding.path)
+        return `${String(verb).toUpperCase()} ${binding.path}`;
+    return String(binding.name ?? binding.adapter ?? binding.$adapter ?? binding.kind ?? "binding");
+}
+/** Kind off a registered handler: `config.kind` → `$kind` → `"handler"`. */
+function handlerKind(h) {
+    return h?.config?.kind ?? h?.$kind ?? "handler";
+}
+/** A wire binding's method + path, when it's an HTTP route (else undefined). */
+function routeOf(binding) {
+    if (!binding || typeof binding !== "object")
+        return undefined;
+    const verb = binding.verb ?? binding.method;
+    if (verb && binding.path)
+        return { method: String(verb).toUpperCase(), path: String(binding.path) };
+    return undefined;
+}
+/**
+ * Capture the topology from a booted App. Every read is guarded so a forge-less
+ * or transport-less app still produces a valid (sparser) topology.
+ */
+export function captureTopology(app) {
+    const rt = app.runtime ?? {};
+    const plugins = (app.plugins ?? []).map((p) => ({ name: p.name }));
+    const capabilities = (rt.describeCapabilities?.() ?? []).map((c) => ({
+        name: c.name,
+        kinds: c.kinds,
+        ctxKeys: c.ctxKeys,
+    }));
+    const sourceStages = (rt.listSourceStages?.() ?? []).map((s) => ({
+        name: s.name,
+        position: s.position,
+        kind: s.kind,
+    }));
+    const sinkStages = (rt.listSinkStages?.() ?? []).map((s) => ({
+        name: s.name,
+        position: s.position,
+        kind: s.kind,
+    }));
+    const handlerNames = rt.listHandlers?.() ?? [];
+    const handlers = handlerNames.map((name) => ({
+        name,
+        kind: handlerKind(rt.getHandler?.(name)),
+    }));
+    const bindings = (app.container?.list?.() ?? []).map((b) => ({
+        name: b.name,
+        kind: b.kind,
+    }));
+    // Hooks: from the process-wide hook registry (best-effort; tolerate absence).
+    let hooks = [];
+    try {
+        hooks = listHooks().map((h) => ({
+            name: h.name,
+            id: h.id,
+            chain: h.chain ?? h.stepCounts?.()?.chain,
+            listeners: h.listeners ?? h.stepCounts?.()?.listeners,
+            source: h.source,
+        }));
+    }
+    catch {
+        /* registry unavailable — leave empty */
+    }
+    const wires = app.interface?.wires ?? [];
+    const triggers = wires.map((w) => ({
+        binding: describeBinding(w.binding),
+        handler: w.handler?.name,
+    }));
+    // Apps (the BC) — a single captured app yields a one-element list; an
+    // app-composition merge would concatenate.
+    const apps = app.appName
+        ? [{ name: app.appName, description: app.description, plugins: plugins.map((p) => p.name) }]
+        : [];
+    // Routes — the richer method+path+handler shape over `triggers`, for HTTP wires.
+    const routes = [];
+    for (const w of wires) {
+        const r = routeOf(w.binding);
+        if (r)
+            routes.push({ method: r.method, path: r.path, handler: w.handler?.name });
+    }
+    // ctx-per-kind: every kind a handler is registered under, plus the event
+    // listener kind, mapped to the union of ctx keys it receives (universal caps +
+    // caps whose `kinds` include it).
+    const kinds = new Set(handlers.map((h) => h.kind));
+    kinds.add("listener");
+    const ctxByKind = {};
+    for (const kind of kinds) {
+        const keys = new Set();
+        for (const cap of capabilities) {
+            if (cap.kinds === undefined || cap.kinds.includes(kind)) {
+                for (const k of cap.ctxKeys)
+                    keys.add(k);
+            }
+        }
+        ctxByKind[kind] = [...keys];
+    }
+    const contributions = (app.pluginContributions?.() ?? []).map((c) => ({
+        plugin: c.plugin,
+        bindings: c.bindings,
+        capabilities: c.capabilities,
+        sourceStages: c.sourceStages,
+        sinkStages: c.sinkStages,
+        handlers: c.handlers,
+        hooks: c.hooks,
+    }));
+    return {
+        apps,
+        plugins,
+        capabilities,
+        ctxByKind,
+        sourceStages,
+        sinkStages,
+        handlers,
+        bindings,
+        hooks,
+        triggers,
+        routes,
+        contributions,
+    };
+}

package/dist/topology-emit.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Topology self-emit — a running app writes its own wiring to disk.
+ *
+ * The static scanner (`@nwire/scan`) sees source shapes (events/actions/…) but
+ * not the runtime topology, because plugins register imperatively at boot. The
+ * old fix booted the app from the scanner to read it; this replaces that with a
+ * self-emit, mirroring the telemetry auto-install: when an app boots inside a
+ * project working directory, it introspects its own runtime once it is ready and
+ * writes `<cwd>/.nwire/topology.json`. The scanner then folds that file into the
+ * manifest with no live instance — "scan the graph, not the runtime."
+ *
+ * Userland-unaware: no plugin, no config — the composition root (`createApp`)
+ * calls `installTopologyEmit` once. Gated by the SAME rule as the telemetry
+ * auto-install (`resolveProjectCwd`): `NWIRE_CWD` set, or a `.nwire` dir present,
+ * and OFF under Vitest / `NODE_ENV=test` so the suite never writes stray files.
+ */
+import { type Topology } from "./topology-capture.js";
+/** The on-disk shape of `.nwire/topology.json`. */
+export interface TopologyFile {
+    /** Bumped when the file shape changes, so a reader can detect a stale file. */
+    readonly version: 1;
+    /** ISO timestamp of the emit — the app's ready moment. */
+    readonly emittedAt: string;
+    /** The captured runtime topology. */
+    readonly topology: Topology;
+}
+/** Bumped when {@link TopologyFile} changes shape. */
+export declare const TOPOLOGY_FILE_VERSION: 1;
+/**
+ * Write the captured topology of a booted `app` to `<dir>/.nwire/topology.json`.
+ * Exported for tests + the scanner's instance path; the composition root uses
+ * {@link installTopologyEmit} instead, which gates + hooks lifecycle.
+ */
+export declare function writeTopologyFile(app: any, dir: string): string;
+/** Minimal shape the emit needs off the App — its lifecycle hooks. */
+interface EmittableApp {
+    readonly appHooks?: {
+        readonly AppReady?: {
+            on(fn: () => void | Promise<void>): unknown;
+        };
+        readonly AppShutdown?: {
+            on(fn: () => void | Promise<void>): unknown;
+        };
+    };
+}
+/**
+ * Install the topology self-emit on `app` when a project cwd is detected.
+ * No-op (returns `undefined`) otherwise. Safe to call unconditionally from the
+ * composition root. The topology is complete only after boot, so it captures on
+ * `AppReady`; the file is removed on `AppShutdown` so a dead app leaves no stale
+ * topology behind for the scanner to fold.
+ */
+export declare function installTopologyEmit(app: EmittableApp & Record<string, any>, env?: NodeJS.ProcessEnv): (() => void) | undefined;
+export {};

package/dist/topology-emit.js

@@ -0,0 +1,73 @@
+/**
+ * Topology self-emit — a running app writes its own wiring to disk.
+ *
+ * The static scanner (`@nwire/scan`) sees source shapes (events/actions/…) but
+ * not the runtime topology, because plugins register imperatively at boot. The
+ * old fix booted the app from the scanner to read it; this replaces that with a
+ * self-emit, mirroring the telemetry auto-install: when an app boots inside a
+ * project working directory, it introspects its own runtime once it is ready and
+ * writes `<cwd>/.nwire/topology.json`. The scanner then folds that file into the
+ * manifest with no live instance — "scan the graph, not the runtime."
+ *
+ * Userland-unaware: no plugin, no config — the composition root (`createApp`)
+ * calls `installTopologyEmit` once. Gated by the SAME rule as the telemetry
+ * auto-install (`resolveProjectCwd`): `NWIRE_CWD` set, or a `.nwire` dir present,
+ * and OFF under Vitest / `NODE_ENV=test` so the suite never writes stray files.
+ */
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolveProjectCwd } from "./auto-install.js";
+import { captureTopology } from "./topology-capture.js";
+/** Bumped when {@link TopologyFile} changes shape. */
+export const TOPOLOGY_FILE_VERSION = 1;
+/** Resolve `<cwd>/.nwire/topology.json` for a project cwd. */
+function topologyPath(cwd) {
+    return join(cwd, ".nwire", "topology.json");
+}
+/**
+ * Write the captured topology of a booted `app` to `<dir>/.nwire/topology.json`.
+ * Exported for tests + the scanner's instance path; the composition root uses
+ * {@link installTopologyEmit} instead, which gates + hooks lifecycle.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function writeTopologyFile(app, dir) {
+    const file = {
+        version: TOPOLOGY_FILE_VERSION,
+        emittedAt: new Date().toISOString(),
+        topology: captureTopology(app),
+    };
+    const path = topologyPath(dir);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(file, null, 2));
+    return path;
+}
+/**
+ * Install the topology self-emit on `app` when a project cwd is detected.
+ * No-op (returns `undefined`) otherwise. Safe to call unconditionally from the
+ * composition root. The topology is complete only after boot, so it captures on
+ * `AppReady`; the file is removed on `AppShutdown` so a dead app leaves no stale
+ * topology behind for the scanner to fold.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function installTopologyEmit(app, env = process.env) {
+    const dir = resolveProjectCwd(env);
+    if (!dir)
+        return undefined;
+    let written;
+    app.appHooks?.AppReady?.on(() => {
+        written = writeTopologyFile(app, dir);
+    });
+    const cleanup = () => {
+        if (!written)
+            return;
+        try {
+            rmSync(written, { force: true });
+        }
+        catch {
+            /* best-effort — a missing file is fine */
+        }
+        written = undefined;
+    };
+    app.appHooks?.AppShutdown?.on(cleanup);
+    return cleanup;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nwire/telemetry",
+  "version": "0.13.0",
+  "description": "Nwire — local telemetry reporters. Writes the canonical telemetry stream to disk as JSONL run files (.nwire/telemetry/<runId>.jsonl) for Studio history and post-mortem review. Cloud/OTLP forwarding lives in @nwire/telemetry-otel.",
+  "keywords": [
+    "jsonl",
+    "nwire",
+    "observability",
+    "reporter",
+    "telemetry"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/telemetry.js",
+  "types": "./dist/telemetry.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/telemetry.js",
+      "types": "./dist/telemetry.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/hooks": "0.13.0",
+    "@nwire/runtime": "0.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "@nwire/container": "0.13.0"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}