@nwire/runtime 0.12.1 → 0.13.0

package/dist/source.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Inbound source chain — the seam between an arriving message (HTTP request,
+ * queue job, broker delivery) and the runtime's one execution terminal.
+ *
+ * Transports hand a raw message to `runtime.receive(msg)`. Every installed
+ * stage runs in position order; a stage that returns `{ continue: false }`
+ * stops the chain (e.g. a dedup stage dropping a replay). The terminal stage
+ * is the router: it lands a command on `runtime.execute` and an event on
+ * `runtime.emit`. Exact mirror of the outbound `sink` chain.
+ *
+ * The runtime knows about the chain but nothing about transports — every
+ * source (HTTP, NATS, queue) is installed by an inbound adapter through
+ * `endpoint.use(...)` at boot and calls `receive` per message.
+ */
+import type { MessageEnvelope } from "@nwire/envelope";
+import type { EventDefinition } from "@nwire/messages";
+import type { HandlerDefinition } from "@nwire/handler";
+import type { StagePosition } from "./sink.js";
+/**
+ * A command's dispatch target: a direct handler reference (the HTTP wire
+ * already holds one), a plain `(input, ctx)` function, or a registry name the
+ * runtime resolves.
+ */
+export type InboundTarget = HandlerDefinition<any, any, any> | ((input: any, ctx: any) => any) | string;
+/**
+ * A message arriving at the runtime's inbound boundary. `kind` selects the
+ * door: a `command` lands on `execute`, an `event` on `emit`.
+ */
+export interface InboundMessage {
+    readonly kind: "command" | "event";
+    /** Logical message name — the route key for telemetry and name-based dispatch. */
+    readonly name: string;
+    readonly input: unknown;
+    /**
+     * Command target. Adapters holding the wire pass the handler reference
+     * directly; omit to dispatch by `name` through the handler registry.
+     */
+    readonly target?: InboundTarget;
+    /**
+     * Event definition — required when `kind === "event"` so `emit` can validate
+     * the payload against its schema. (Resolving a broker-delivered event name
+     * to its definition is a later step.)
+     */
+    readonly event?: EventDefinition & {
+        readonly name: string;
+        readonly schema: {
+            parse(input: unknown): unknown;
+        };
+    };
+    /** Idempotency / dedup key, when the transport carries one. */
+    readonly id?: string;
+    /** Raw transport message (koa ctx, nats msg) — diagnostic / stage use. */
+    readonly raw?: unknown;
+}
+/**
+ * Per-stage context for the inbound chain. Stages may rewrite `message`
+ * (translators / anti-corruption), enrich `envelope` (tenant, user,
+ * correlation), or short-circuit. The terminal router reads `message` +
+ * `envelope` + `extras` and writes `result`.
+ */
+export interface InboundContext {
+    message?: InboundMessage;
+    /**
+     * Envelope seed / overrides for this inbound — tenant, user, correlation,
+     * causation. The full `MessageEnvelope` is minted downstream by `execute` /
+     * `emit`; at the boundary this is the partial the transport resolved.
+     */
+    envelope: Partial<MessageEnvelope>;
+    /** Transport extras threaded onto the handler ctx (logger, koa, …). */
+    extras?: Record<string, unknown>;
+    /** Cancellation signal threaded onto the dispatch (queue lock, request abort). */
+    signal?: AbortSignal;
+    /**
+     * Parent envelope to inherit from — the dispatch derives a child (carries
+     * correlationId, causationId = parent.messageId). Set by async sources
+     * (queue) that replay a stored envelope.
+     */
+    parent?: MessageEnvelope;
+    resolve<T = unknown>(name: string): T;
+    /** Acknowledge / negatively-acknowledge, when the transport supports it. */
+    ack?(): Promise<void> | void;
+    nak?(): Promise<void> | void;
+    result?: unknown;
+}
+/**
+ * An inbound pipeline stage. Returns nothing to keep going, or
+ * `{ continue: false }` to short-circuit (e.g. a dedup stage dropping a
+ * replayed message before it reaches the router).
+ */
+export interface InboundStage {
+    readonly name: string;
+    readonly position: StagePosition;
+    /**
+     * Optional kind tag — `"http" | "nats" | "queue" | ...`. For terminal stages
+     * it enforces uniqueness (one per kind); for non-terminal stages it's
+     * diagnostic only.
+     */
+    readonly kind?: string;
+    run(ctx: InboundContext): Promise<{
+        continue?: boolean;
+    } | void> | {
+        continue?: boolean;
+    } | void;
+}

package/dist/source.js

@@ -0,0 +1,15 @@
+/**
+ * Inbound source chain — the seam between an arriving message (HTTP request,
+ * queue job, broker delivery) and the runtime's one execution terminal.
+ *
+ * Transports hand a raw message to `runtime.receive(msg)`. Every installed
+ * stage runs in position order; a stage that returns `{ continue: false }`
+ * stops the chain (e.g. a dedup stage dropping a replay). The terminal stage
+ * is the router: it lands a command on `runtime.execute` and an event on
+ * `runtime.emit`. Exact mirror of the outbound `sink` chain.
+ *
+ * The runtime knows about the chain but nothing about transports — every
+ * source (HTTP, NATS, queue) is installed by an inbound adapter through
+ * `endpoint.use(...)` at boot and calls `receive` per message.
+ */
+export {};

package/dist/telemetry-sink.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Telemetry sink — the terminal end of the observability lane.
+ *
+ * `runtime.onTelemetry` is the SOURCE: every dispatch, hook step, source/sink
+ * stage, and event push lands on it. A `TelemetryReporter` is the SINK
+ * terminal — it takes each record and does something durable with it (write a
+ * JSONL run file, forward to OTLP, ship to a cloud collector). Telemetry
+ * records are not domain events, so this is its own lane, parallel to the
+ * event sink chain — never an endpoint plugin.
+ *
+ * Multiple reporters may be installed on one runtime (a local disk reporter
+ * for dev history plus a cloud exporter, say). Each `installTelemetryReporter`
+ * call subscribes one reporter and returns a detach.
+ *
+ * This module is deliberately fs-free so `@nwire/runtime` stays portable. The
+ * concrete drivers (the local disk file reporter) live in node packages that
+ * implement this interface — see `@nwire/telemetry`.
+ */
+import type { Runtime } from "./runtime.js";
+/**
+ * A telemetry sink terminal. Receives every record pushed onto
+ * `runtime.onTelemetry` and persists / forwards it however the driver sees
+ * fit. A reporter must never throw out of `report` in a way that breaks the
+ * runtime — {@link installTelemetryReporter} guards each call, but well-behaved
+ * drivers swallow their own write errors too.
+ */
+export interface TelemetryReporter {
+    /** Stable identifier — diagnostics, and which reporter is which in logs. */
+    readonly name: string;
+    /** Called once per `onTelemetry` record. Must be fast + non-throwing. */
+    report(record: unknown): void;
+    /** Drain any buffered records. Awaited at shutdown / before close. */
+    flush?(): Promise<void>;
+    /** Release resources (close the file stream, the exporter). Awaited on detach. */
+    close?(): Promise<void>;
+}
+/**
+ * Subscribe a {@link TelemetryReporter} to `runtime.onTelemetry`.
+ *
+ * Each pushed record is handed to `reporter.report`. A throwing reporter is
+ * caught and logged — telemetry is observation, it never breaks dispatch.
+ *
+ * Returns a detach: it unsubscribes from the stream, then calls
+ * `reporter.close?()` (best-effort; a rejecting close is swallowed so detach
+ * is always safe to await in a shutdown sequence). The returned function is
+ * synchronous — the close runs fire-and-forget so detach can be wired into
+ * sync shutdown paths; await `reporter.flush()` / `reporter.close()` directly
+ * when you need the drain to complete.
+ */
+export declare function installTelemetryReporter(runtime: Runtime, reporter: TelemetryReporter): () => void;

package/dist/telemetry-sink.js

@@ -0,0 +1,54 @@
+/**
+ * Telemetry sink — the terminal end of the observability lane.
+ *
+ * `runtime.onTelemetry` is the SOURCE: every dispatch, hook step, source/sink
+ * stage, and event push lands on it. A `TelemetryReporter` is the SINK
+ * terminal — it takes each record and does something durable with it (write a
+ * JSONL run file, forward to OTLP, ship to a cloud collector). Telemetry
+ * records are not domain events, so this is its own lane, parallel to the
+ * event sink chain — never an endpoint plugin.
+ *
+ * Multiple reporters may be installed on one runtime (a local disk reporter
+ * for dev history plus a cloud exporter, say). Each `installTelemetryReporter`
+ * call subscribes one reporter and returns a detach.
+ *
+ * This module is deliberately fs-free so `@nwire/runtime` stays portable. The
+ * concrete drivers (the local disk file reporter) live in node packages that
+ * implement this interface — see `@nwire/telemetry`.
+ */
+/**
+ * Subscribe a {@link TelemetryReporter} to `runtime.onTelemetry`.
+ *
+ * Each pushed record is handed to `reporter.report`. A throwing reporter is
+ * caught and logged — telemetry is observation, it never breaks dispatch.
+ *
+ * Returns a detach: it unsubscribes from the stream, then calls
+ * `reporter.close?()` (best-effort; a rejecting close is swallowed so detach
+ * is always safe to await in a shutdown sequence). The returned function is
+ * synchronous — the close runs fire-and-forget so detach can be wired into
+ * sync shutdown paths; await `reporter.flush()` / `reporter.close()` directly
+ * when you need the drain to complete.
+ */
+export function installTelemetryReporter(runtime, reporter) {
+    const unsubscribe = runtime.onTelemetry((record) => {
+        try {
+            reporter.report(record);
+        }
+        catch (err) {
+            // Best-effort — a bad reporter must not break the runtime.
+            // eslint-disable-next-line no-console
+            console.error(`[telemetry] reporter "${reporter.name}" report threw:`, err);
+        }
+    });
+    return () => {
+        unsubscribe();
+        if (reporter.close) {
+            void Promise.resolve()
+                .then(() => reporter.close())
+                .catch((err) => {
+                // eslint-disable-next-line no-console
+                console.error(`[telemetry] reporter "${reporter.name}" close threw:`, err);
+            });
+        }
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nwire/runtime",
-  "version": "0.12.1",
-  "description": "Nwire — envelope-execution substrate. Dispatch + emit + when + sink + capability registry. Extracted from @nwire/app for 0.11. Standalone usable without the App layer.",
+  "version": "0.13.0",
+  "description": "Nwire — envelope-execution substrate. Dispatch + emit + when + sink + capability registry. Standalone — usable without the App layer.",
   "keywords": [
     "capability",
     "dispatch",
@@ -27,12 +27,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@nwire/container": "0.12.1",
-    "@nwire/envelope": "0.12.1",
-    "@nwire/handler": "0.12.1",
-    "@nwire/hooks": "0.12.1",
-    "@nwire/logger": "0.12.1",
-    "@nwire/messages": "0.12.1"
+    "@nwire/container": "0.13.0",
+    "@nwire/hooks": "0.13.0",
+    "@nwire/logger": "0.13.0",
+    "@nwire/messages": "0.13.0",
+    "@nwire/envelope": "0.13.0",
+    "@nwire/handler": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.9",