@nwire/runtime 0.11.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/capability.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A Capability is a by-reference contribution to the Runtime. It can add
+ * any combination of:
+ *
+ *   1. A per-request ctx member (`provideCtx`) — merged into the handler
+ *      ctx every dispatch. Lets handler code see typed verbs like
+ *      `ctx.enqueue`, `ctx.publish`, `ctx.mail.send`.
+ *   2. A runtime method (`provideRuntime`) — installed once at
+ *      `runtime.add(cap)`. Lets external code call e.g.
+ *      `runtime.publish(...)` directly when no envelope is in scope.
+ *
+ * `TMark` is the phantom carrier that App's `<TCaps>` accumulates across
+ * `.with(plugin)`. The encoding is structural intersection: every plugin
+ * advertises its contribution as a structural type, and the App's
+ * accumulated `TCaps` is the intersection of all installed marks.
+ */
+import type { MessageEnvelope } from "@nwire/envelope";
+import type { Container } from "@nwire/container";
+import type { Runtime } from "./runtime.js";
+/**
+ * Base shape passed to `provideCtx`. The capability returns a Record that is
+ * spread into the handler ctx for one dispatch. `envelope`, `container`, and
+ * `runtime` are the three references every capability has access to.
+ */
+export interface CapabilityBase {
+    readonly envelope: MessageEnvelope;
+    readonly container: Container;
+    readonly runtime: Runtime;
+}
+/**
+ * A Capability contributes to the Runtime by reference.
+ *
+ * @typeParam TMark — phantom shape advertising what this capability adds to
+ *                    the handler ctx. Accumulated by the App layer via
+ *                    structural intersection. Never read at runtime; the
+ *                    `__mark` field exists only to carry the type.
+ */
+export interface Capability<TMark = unknown> {
+    /** Stable identifier — used for diagnostics and duplicate-install detection. */
+    readonly name: string;
+    /**
+     * Build the per-request ctx contribution. Called once per dispatch with
+     * the current envelope + container scope. The returned object is spread
+     * into the handler ctx. Should read but not mutate the base values.
+     */
+    provideCtx?(base: CapabilityBase): Record<string, unknown>;
+    /**
+     * Install a runtime-level method. Called once at `runtime.add(cap)`.
+     * Returned members are attached to the runtime instance directly so
+     * external code can call `runtime.<method>(...)` without dispatching.
+     */
+    provideRuntime?(runtime: Runtime): Record<string, (...args: any[]) => unknown>;
+    /** Phantom marker — carries the ctx-shape type into App<TCaps>. */
+    readonly __mark?: TMark;
+}
+/**
+ * Typed capability declaration that locks the ctx shape into both the type
+ * system and the runtime contract.
+ *
+ *   const enqueueCap = defineCapability<{ enqueue: typeof enqueueFn }>({
+ *     name: "queue.enqueue",
+ *     provideCtx: ({ envelope }) => ({ enqueue: enqueueFn }),
+ *   });
+ *
+ * Pure factory — no runtime cost beyond returning the input. The `TMark`
+ * generic is carried through `Capability<TMark>` so the App layer sees it.
+ */
+export declare function defineCapability<TMark>(cap: Capability<TMark>): Capability<TMark>;

package/dist/capability.js

@@ -0,0 +1,31 @@
+/**
+ * A Capability is a by-reference contribution to the Runtime. It can add
+ * any combination of:
+ *
+ *   1. A per-request ctx member (`provideCtx`) — merged into the handler
+ *      ctx every dispatch. Lets handler code see typed verbs like
+ *      `ctx.enqueue`, `ctx.publish`, `ctx.mail.send`.
+ *   2. A runtime method (`provideRuntime`) — installed once at
+ *      `runtime.add(cap)`. Lets external code call e.g.
+ *      `runtime.publish(...)` directly when no envelope is in scope.
+ *
+ * `TMark` is the phantom carrier that App's `<TCaps>` accumulates across
+ * `.with(plugin)`. The encoding is structural intersection: every plugin
+ * advertises its contribution as a structural type, and the App's
+ * accumulated `TCaps` is the intersection of all installed marks.
+ */
+/**
+ * Typed capability declaration that locks the ctx shape into both the type
+ * system and the runtime contract.
+ *
+ *   const enqueueCap = defineCapability<{ enqueue: typeof enqueueFn }>({
+ *     name: "queue.enqueue",
+ *     provideCtx: ({ envelope }) => ({ enqueue: enqueueFn }),
+ *   });
+ *
+ * Pure factory — no runtime cost beyond returning the input. The `TMark`
+ * generic is carried through `Capability<TMark>` so the App layer sees it.
+ */
+export function defineCapability(cap) {
+    return cap;
+}

package/dist/framework-hooks.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Per-runtime framework-hook registry. Each slot is a `Hook<TPayload>`
+ * accessed as a typed property on `runtime.hooks`. Plugins extend via
+ * TS module augmentation + `runtime.defineHook(name)`.
+ */
+import { type Hook } from "@nwire/hooks";
+/**
+ * Plugins can distinguish "module compiled onto plugin lifecycle" from a
+ * normal plugin. Lifecycle payloads include this so observers can filter.
+ */
+export type PluginKind = "plugin" | "module";
+/**
+ * The typed registry. Plugin packages augment this interface to add their
+ * own slots; the foundation contributes the lifecycle slots below.
+ *
+ * Every slot is `Hook<TPayload>` — no dispatch-mode discriminator.
+ * Consumers call `.use()` to participate in the chain (with optional veto
+ * via not calling `next()`), `.on()` to observe in parallel, `.tap()` to
+ * receive step-level telemetry.
+ */
+export interface FrameworkHooks {
+    AppRegistering: Hook<{
+        readonly appName: string;
+    }>;
+    AppBooting: Hook<{
+        readonly appName: string;
+    }>;
+    AppBooted: Hook<{
+        readonly appName: string;
+        readonly bootedAt: string;
+    }>;
+    AppReady: Hook<{
+        readonly appName: string;
+        readonly readyAt: string;
+    }>;
+    AppShuttingDown: Hook<{
+        readonly appName: string;
+        readonly reason?: string;
+    }>;
+    AppShutdown: Hook<{
+        readonly appName: string;
+    }>;
+    PluginRegistered: Hook<{
+        readonly appName: string;
+        readonly pluginName: string;
+        readonly kind?: PluginKind;
+    }>;
+    PluginBooting: Hook<{
+        readonly appName: string;
+        readonly pluginName: string;
+        readonly kind?: PluginKind;
+    }>;
+    PluginBooted: Hook<{
+        readonly appName: string;
+        readonly pluginName: string;
+        readonly durationMs: number;
+        readonly kind?: PluginKind;
+    }>;
+    PluginShuttingDown: Hook<{
+        readonly appName: string;
+        readonly pluginName: string;
+        readonly kind?: PluginKind;
+    }>;
+    PluginShutdown: Hook<{
+        readonly appName: string;
+        readonly pluginName: string;
+        readonly durationMs: number;
+        readonly kind?: PluginKind;
+    }>;
+    WireMounting: Hook<{
+        readonly appName: string;
+        readonly transport: string;
+        readonly manifest: unknown;
+    }>;
+    WireMounted: Hook<{
+        readonly appName: string;
+        readonly transport: string;
+        readonly manifest: unknown;
+    }>;
+    WireUnmounted: Hook<{
+        readonly appName: string;
+        readonly transport: string;
+    }>;
+}
+/** Canonical names for the built-in slots — used to label the underlying Hooks. */
+declare const BUILT_IN_HOOK_NAMES: {
+    readonly AppRegistering: "nwire.app.registering";
+    readonly AppBooting: "nwire.app.booting";
+    readonly AppBooted: "nwire.app.booted";
+    readonly AppReady: "nwire.app.ready";
+    readonly AppShuttingDown: "nwire.app.shutting-down";
+    readonly AppShutdown: "nwire.app.shutdown";
+    readonly PluginRegistered: "nwire.plugin.registered";
+    readonly PluginBooting: "nwire.plugin.booting";
+    readonly PluginBooted: "nwire.plugin.booted";
+    readonly PluginShuttingDown: "nwire.plugin.shutting-down";
+    readonly PluginShutdown: "nwire.plugin.shutdown";
+    readonly WireMounting: "nwire.wire.mounting";
+    readonly WireMounted: "nwire.wire.mounted";
+    readonly WireUnmounted: "nwire.wire.unmounted";
+};
+/**
+ * Construct the per-runtime registry, with every built-in slot
+ * pre-instantiated. Plugin slots added via `runtime.defineHook(name)`
+ * land on the same registry instance.
+ */
+export declare function createFrameworkHooks(): FrameworkHooks;
+/** True if `slot` is one of the built-in hook keys. */
+export declare function isBuiltInHook(slot: string): slot is keyof typeof BUILT_IN_HOOK_NAMES;
+export {};

package/dist/framework-hooks.js

@@ -0,0 +1,39 @@
+/**
+ * Per-runtime framework-hook registry. Each slot is a `Hook<TPayload>`
+ * accessed as a typed property on `runtime.hooks`. Plugins extend via
+ * TS module augmentation + `runtime.defineHook(name)`.
+ */
+import { hook } from "@nwire/hooks";
+/** Canonical names for the built-in slots — used to label the underlying Hooks. */
+const BUILT_IN_HOOK_NAMES = {
+    AppRegistering: "nwire.app.registering",
+    AppBooting: "nwire.app.booting",
+    AppBooted: "nwire.app.booted",
+    AppReady: "nwire.app.ready",
+    AppShuttingDown: "nwire.app.shutting-down",
+    AppShutdown: "nwire.app.shutdown",
+    PluginRegistered: "nwire.plugin.registered",
+    PluginBooting: "nwire.plugin.booting",
+    PluginBooted: "nwire.plugin.booted",
+    PluginShuttingDown: "nwire.plugin.shutting-down",
+    PluginShutdown: "nwire.plugin.shutdown",
+    WireMounting: "nwire.wire.mounting",
+    WireMounted: "nwire.wire.mounted",
+    WireUnmounted: "nwire.wire.unmounted",
+};
+/**
+ * Construct the per-runtime registry, with every built-in slot
+ * pre-instantiated. Plugin slots added via `runtime.defineHook(name)`
+ * land on the same registry instance.
+ */
+export function createFrameworkHooks() {
+    const registry = {};
+    for (const [slot, name] of Object.entries(BUILT_IN_HOOK_NAMES)) {
+        registry[slot] = hook(name);
+    }
+    return registry;
+}
+/** True if `slot` is one of the built-in hook keys. */
+export function isBuiltInHook(slot) {
+    return slot in BUILT_IN_HOOK_NAMES;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@nwire/runtime` — the envelope-execution substrate.
+ *
+ * The Runtime is the dispatch + emit + listen substrate the App builds on.
+ * It owns the container reference, the dispatch hook chain, the capability
+ * registry, the sink chain, and the framework hooks. Standalone — container
+ * plus runtime alone is enough to dispatch handlers with envelopes, install
+ * capabilities, install middleware, and react to events without any App.
+ */
+export { Runtime, createRuntime, isBuiltInHook, serializeError, type RuntimeOptions, type Telemetry, type TelemetryListener, type HookStepTelemetry, type DispatchHookCtx, type DispatchMiddleware, type SerializedError, type PluginDefinition, type PluginContext, } from "./runtime.js";
+export { createFrameworkHooks, type FrameworkHooks, type PluginKind } from "./framework-hooks.js";
+export { defineCapability, type Capability, type CapabilityBase } from "./capability.js";
+export type { OutboundStage, StagePosition, StageContext } from "./sink.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@nwire/runtime` — the envelope-execution substrate.
+ *
+ * The Runtime is the dispatch + emit + listen substrate the App builds on.
+ * It owns the container reference, the dispatch hook chain, the capability
+ * registry, the sink chain, and the framework hooks. Standalone — container
+ * plus runtime alone is enough to dispatch handlers with envelopes, install
+ * capabilities, install middleware, and react to events without any App.
+ */
+// Runtime core
+export { Runtime, createRuntime, isBuiltInHook, serializeError, } from "./runtime.js";
+export { createFrameworkHooks } from "./framework-hooks.js";
+// Capability primitive — by-reference Runtime contribution.
+export { defineCapability } from "./capability.js";