@nwire/runtime 0.12.1 → 0.13.0

package/dist/capability.d.ts

@@ -19,13 +19,16 @@ 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.
+ * spread into the handler ctx for one dispatch. `envelope`, `container`,
+ * `runtime`, and the per-dispatch `signal` are the references every capability
+ * has access to. Thread `signal` into any nested dispatch a contributed verb
+ * starts, so caller cancellation propagates.
  */
 export interface CapabilityBase {
     readonly envelope: MessageEnvelope;
     readonly container: Container;
     readonly runtime: Runtime;
+    readonly signal: AbortSignal;
 }
 /**
  * A Capability contributes to the Runtime by reference.
@@ -38,6 +41,18 @@ export interface CapabilityBase {
 export interface Capability<TMark = unknown> {
     /** Stable identifier — used for diagnostics and duplicate-install detection. */
     readonly name: string;
+    /**
+     * Handler kinds this capability's ctx applies to. When set, `provideCtx`
+     * runs only for dispatches whose handler is one of these kinds — so an
+     * action's ctx carries `request`/`send`/`emit` while a query's does not.
+     * Omit for a universal contribution (the base every handler gets:
+     * `resolve`/`logger`/ambient). The dividing line is what the verb closes
+     * over: envelope/container-scoped verbs are kind-tagged here; instance-bound
+     * verbs (`assign`/`recordThat`) are layered on by the actor/workflow builder,
+     * not the runtime ctx. Values are `HandlerKind` strings ("action" / "query" /
+     * "handler" / …).
+     */
+    readonly kinds?: readonly string[];
     /**
      * Build the per-request ctx contribution. Called once per dispatch with
      * the current envelope + container scope. The returned object is spread

package/dist/framework-hooks.d.ts

@@ -1,17 +1,43 @@
 /**
- * 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)`.
+ * Per-runtime delivery / plugin-extension hook registry. Each slot is a
+ * `Hook<TPayload>` accessed as a typed property on `runtime.hooks`. The
+ * runtime ships exactly one built-in slot — `LocalDelivery`, the ordered
+ * local fan-out chain. Plugins extend the registry via TS module
+ * augmentation + `runtime.defineHook(name)` (forge adds its Action* / Event*
+ * slots this way).
+ *
+ * App / plugin LIFECYCLE hooks are an App concern and live in `@nwire/app`'s
+ * `AppHooks` registry — not here. The runtime does not know about plugins.
  */
 import { type Hook } from "@nwire/hooks";
+import type { MessageEnvelope } from "@nwire/envelope";
 /**
  * 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.
+ * Payload threaded through the `LocalDelivery` chain — the one
+ * incoming-to-all delivery `runtime.emit` runs before fanning out to
+ * `when` listeners. Ordered fold steps (forge's idempotency, actors,
+ * projections, workflows) attach via `.use()` at their priority and
+ * read/mutate `deduped`: the idempotency gate sets it and vetoes (skips
+ * `next()`) to short-circuit both the rest of the chain AND the listener
+ * fan-out. Core-shaped on purpose — name + payload + envelope, no forge
+ * `EventMessage` type — so the runtime owns local delivery with zero forge
+ * dependency.
+ */
+export interface LocalDeliveryPayload {
+    readonly eventName: string;
+    readonly payload: unknown;
+    readonly envelope: MessageEnvelope;
+    readonly dedupKey: string;
+    /** Set by an idempotency step when this event was seen before. */
+    deduped: boolean;
+}
+/**
+ * The typed delivery registry. Plugin packages augment this interface to add
+ * their own slots; the runtime contributes only the local-delivery slot.
  *
  * Every slot is `Hook<TPayload>` — no dispatch-mode discriminator.
  * Consumers call `.use()` to participate in the chain (with optional veto
@@ -19,85 +45,28 @@ export type PluginKind = "plugin" | "module";
  * 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;
-    }>;
+    /**
+     * The one ordered local-delivery chain. `runtime.emit` runs it (veto via
+     * skipping `next()`), then fans out to listeners unless an upstream step
+     * deduped. Forge's fold steps (idempotency → actors → projections →
+     * workflows) attach here at priority; core ships it empty so a forge-less
+     * app's `emit` is just listener fan-out.
+     */
+    LocalDelivery: Hook<LocalDeliveryPayload>;
+}
+/**
+ * App / plugin LIFECYCLE hook registry — an App concern. The runtime does
+ * not own a lifecycle; `@nwire/app` augments this interface with the actual
+ * slots (App* / Plugin*) and owns the concrete registry instance (see
+ * `AppHooks` / `createAppHooks` in `@nwire/app`). It is declared here only
+ * so `PluginContext.on` / `PluginContext.defineHook` — which target app
+ * lifecycle hooks — stay typed without core-runtime depending on core-app.
+ */
+export interface AppHooks {
 }
-/** Canonical names for the built-in slots — used to label the underlying Hooks. */
+/** Canonical names for the built-in delivery slots — used to label the 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";
+    readonly LocalDelivery: "nwire.event.local-delivery";
 };
 /**
  * Construct the per-runtime registry, with every built-in slot
@@ -105,6 +74,6 @@ declare const BUILT_IN_HOOK_NAMES: {
  * land on the same registry instance.
  */
 export declare function createFrameworkHooks(): FrameworkHooks;
-/** True if `slot` is one of the built-in hook keys. */
+/** True if `slot` is one of the built-in runtime hook keys. */
 export declare function isBuiltInHook(slot: string): slot is keyof typeof BUILT_IN_HOOK_NAMES;
 export {};

package/dist/framework-hooks.js

@@ -1,25 +1,18 @@
 /**
- * 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)`.
+ * Per-runtime delivery / plugin-extension hook registry. Each slot is a
+ * `Hook<TPayload>` accessed as a typed property on `runtime.hooks`. The
+ * runtime ships exactly one built-in slot — `LocalDelivery`, the ordered
+ * local fan-out chain. Plugins extend the registry via TS module
+ * augmentation + `runtime.defineHook(name)` (forge adds its Action* / Event*
+ * slots this way).
+ *
+ * App / plugin LIFECYCLE hooks are an App concern and live in `@nwire/app`'s
+ * `AppHooks` registry — not here. The runtime does not know about plugins.
  */
 import { hook } from "@nwire/hooks";
-/** Canonical names for the built-in slots — used to label the underlying Hooks. */
+/** Canonical names for the built-in delivery slots — used to label the 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",
+    LocalDelivery: "nwire.event.local-delivery",
 };
 /**
  * Construct the per-runtime registry, with every built-in slot
@@ -33,7 +26,7 @@ export function createFrameworkHooks() {
     }
     return registry;
 }
-/** True if `slot` is one of the built-in hook keys. */
+/** True if `slot` is one of the built-in runtime hook keys. */
 export function isBuiltInHook(slot) {
     return slot in BUILT_IN_HOOK_NAMES;
 }

package/dist/index.d.ts

@@ -7,7 +7,9 @@
  * 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, type ListenerContext, } from "./runtime.js";
-export { createFrameworkHooks, type FrameworkHooks, type PluginKind } from "./framework-hooks.js";
+export { Runtime, createRuntime, isBuiltInHook, serializeError, messageRef, type MessageRef, type RuntimeOptions, type Telemetry, type TelemetryListener, type HookStepTelemetry, type SourceStageTelemetry, type SinkStageTelemetry, type DispatchHookCtx, type DispatchMiddleware, type SerializedError, type PluginDefinition, type PluginContext, type ListenerContext, } from "./runtime.js";
+export { createFrameworkHooks, type FrameworkHooks, type AppHooks, type PluginKind, type LocalDeliveryPayload, } from "./framework-hooks.js";
 export { defineCapability, type Capability, type CapabilityBase } from "./capability.js";
 export type { OutboundStage, StagePosition, StageContext } from "./sink.js";
+export type { InboundStage, InboundMessage, InboundContext, InboundTarget } from "./source.js";
+export { installTelemetryReporter, type TelemetryReporter } from "./telemetry-sink.js";

package/dist/index.js

@@ -8,7 +8,11 @@
  * 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";
+export { Runtime, createRuntime, isBuiltInHook, serializeError, messageRef, } from "./runtime.js";
+export { createFrameworkHooks, } from "./framework-hooks.js";
 // Capability primitive — by-reference Runtime contribution.
 export { defineCapability } from "./capability.js";
+// Telemetry sink — the terminal end of the onTelemetry source. Reporters are
+// installed on the runtime; the concrete file/cloud drivers live in node
+// packages that implement TelemetryReporter (fs-free here).
+export { installTelemetryReporter } from "./telemetry-sink.js";

package/dist/runtime.d.ts

@@ -1,9 +1,11 @@
 /**
- * Runtime — Container, dispatch hook, FrameworkHooks registry, telemetry
- * stream, plugin lifecycle. The dispatch hook composes user middleware
+ * Runtime — Container, dispatch hook, delivery / plugin-extension hook
+ * registry, telemetry stream. The dispatch hook composes user middleware
  * via `runtime.use(...)` around an inner pinned step that calls the
- * registered handler. Plugins materialise additional FrameworkHooks
- * slots via `runtime.defineHook(name)` and TS module augmentation.
+ * registered handler. Plugins materialise additional `FrameworkHooks` slots
+ * via `runtime.defineHook(name)` and TS module augmentation. The runtime is
+ * a stateless substrate — it has no boot/shutdown lifecycle; the App owns
+ * that (see `AppHooks` / `AppLifecycle` in `@nwire/app`).
  */
 import { type Container } from "@nwire/container/awilix";
 import { type Hook } from "@nwire/hooks";
@@ -11,9 +13,10 @@ import { type Logger } from "@nwire/logger";
 import { type MessageEnvelope } from "@nwire/envelope";
 import type { HandlerDefinition } from "@nwire/handler";
 import type { EventDefinition, EventPayload } from "@nwire/messages";
-import { isBuiltInHook, type FrameworkHooks } from "./framework-hooks.js";
+import { isBuiltInHook, type FrameworkHooks, type AppHooks } from "./framework-hooks.js";
 import type { Capability } from "./capability.js";
-import type { OutboundStage } from "./sink.js";
+import type { OutboundStage, StagePosition } from "./sink.js";
+import type { InboundStage, InboundMessage } from "./source.js";
 /**
  * Serialized form of any thrown value — `Error` instances keep `name` /
  * `message` / `stack` plus any own enumerable properties; non-Error throws
@@ -47,6 +50,43 @@ export interface HookStepTelemetry {
     readonly appName: string;
     readonly ts: string;
 }
+/**
+ * `source.stage` — one record per installed inbound stage run (the terminal
+ * router is not recorded; its landing shows up as the `execute` / `emit` /
+ * fold records it triggers). `correlationId` ties the inbound pipeline to the
+ * dispatch it feeds, so Studio can draw one trace: inbound → execute → fold →
+ * outbound.
+ */
+export interface SourceStageTelemetry {
+    readonly kind: "source.stage";
+    readonly stage: string;
+    readonly position: StagePosition;
+    readonly stageKind?: string;
+    readonly message?: {
+        readonly name?: string;
+        readonly kind?: "command" | "event";
+    };
+    readonly correlationId?: string;
+    readonly tenant?: string;
+    readonly shortCircuited: boolean;
+    readonly durationMs: number;
+    readonly appName: string;
+    readonly ts: string;
+}
+/** `sink.stage` — one record per outbound stage run during `sinkDrain`. */
+export interface SinkStageTelemetry {
+    readonly kind: "sink.stage";
+    readonly stage: string;
+    readonly position: StagePosition;
+    readonly stageKind?: string;
+    readonly event: string;
+    readonly correlationId?: string;
+    readonly tenant?: string;
+    readonly shortCircuited: boolean;
+    readonly durationMs: number;
+    readonly appName: string;
+    readonly ts: string;
+}
 /**
  * Base `Telemetry` union — generic kinds only. Subclasses (forge) WIDEN
  * this with their own domain kinds and re-export the wider union as their
@@ -54,7 +94,7 @@ export interface HookStepTelemetry {
  * everything; consumers that care about discriminants narrow with
  * `switch (rec.kind)`.
  */
-export type Telemetry = HookStepTelemetry;
+export type Telemetry = HookStepTelemetry | SourceStageTelemetry | SinkStageTelemetry;
 export type TelemetryListener<T = Telemetry> = (record: T) => void;
 /**
  * Per-dispatch context passed through the `runtime.dispatch` hook. Subclass
@@ -74,6 +114,33 @@ export interface DispatchHookCtx {
     readonly coreFn: () => Promise<unknown>;
     result?: unknown;
 }
+/**
+ * A handle to a dispatched message. Returned by the async dispatch verbs
+ * (`enqueue`, and forge's `send`) so the caller can correlate and observe a
+ * dispatch without blocking on its result. Every identifier comes from the
+ * envelope minted at dispatch time, so the ref matches the envelope the
+ * handler sees and every telemetry record that dispatch emits.
+ *
+ * The default is "ref, not result." Helpers that recover a result later
+ * (`awaitUntil`, `poll`) wrap a ref; they live outside the runtime so the
+ * hot dispatch path stays allocation-light.
+ */
+export interface MessageRef {
+    /** The dispatched message's id — this dispatch's `envelope.messageId`. */
+    readonly messageId: string;
+    /** Correlation id shared across the whole causal chain. */
+    readonly correlationId: string;
+    /** What caused this dispatch — the parent's messageId (self at chain head). */
+    readonly causationId: string;
+    /** Logical target name — the handler / action / event name. */
+    readonly name: string;
+    /** Which door it went through. */
+    readonly kind: "command" | "event";
+    /** Tenant the dispatch is scoped to, when set. */
+    readonly tenant?: string;
+}
+/** Build a {@link MessageRef} from a minted envelope + target metadata. */
+export declare function messageRef(envelope: MessageEnvelope, name: string, kind: "command" | "event"): MessageRef;
 /**
  * Onion-style extension point around action dispatch. Outermost first;
  * registration order is execution order (matches Koa/express semantics).
@@ -110,9 +177,12 @@ export declare class Runtime {
     protected readonly dispatchHook: Hook<DispatchHookCtx>;
     private userMiddlewareCount;
     /**
-     * Per-runtime framework-hook registry. Built-in slots (App*, Plugin*,
-     * Wire*) are pre-instantiated; plugins augment the `FrameworkHooks`
-     * interface and materialise their slots via `defineHook(name)`.
+     * Per-runtime delivery / plugin-extension hook registry. The one built-in
+     * slot (`LocalDelivery`) is pre-instantiated; plugins augment the
+     * `FrameworkHooks` interface and materialise their slots via
+     * `defineHook(name)` (forge adds its Action* / Event* slots this way).
+     * App / plugin lifecycle hooks are an App concern — see `AppHooks` in
+     * `@nwire/app`.
      */
     readonly hooks: FrameworkHooks;
     private readonly telemetryListeners;
@@ -125,7 +195,7 @@ export declare class Runtime {
     private readonly handlers;
     /**
      * Per-event subscriber registry — keyed by `event.name`. Subscribers
-     * attach via `runtime.subscribe(event, fn)` and fire on `runtime.emit(
+     * attach via `runtime.when(event, fn)` and fire on `runtime.emit(
      * event, payload)`. Foundation calls this out as the broadcast verb
      * distinct from telemetry-push (`runtime.pushTelemetry(record)`).
      */
@@ -150,6 +220,16 @@ export declare class Runtime {
      */
     private readonly sinkStages;
     private readonly terminalKinds;
+    /**
+     * Inbound source chain — populated by `runtime.source(stage)`, the mirror
+     * of the sink chain. `receive` runs them in position order (early → middle →
+     * terminal) and then the default `inboundRouter` lands the message on the
+     * one execution terminal. Terminal stages with a `kind` are exclusivity-
+     * checked, in a namespace independent of sink kinds.
+     */
+    private readonly sourceStages;
+    private readonly terminalSourceKinds;
+    private readonly inboundRouter;
     constructor(options?: RuntimeOptions);
     /**
      * Materialise a slot on `runtime.hooks` for a plugin-defined framework
@@ -190,12 +270,24 @@ export declare class Runtime {
     add(cap: Capability<unknown>): void;
     /** All installed capability names, in install order. Used by tests + Studio. */
     listCapabilities(): readonly string[];
+    /**
+     * Describe installed capabilities for the manifest/topology — name, the
+     * handler `kinds` it scopes to (undefined = universal), and the ctx keys it
+     * contributes (discovered by invoking `provideCtx` with a probe envelope).
+     * Read-only introspection; a `provideCtx` that throws on a bare probe yields
+     * `ctxKeys: []` rather than failing the scan.
+     */
+    describeCapabilities(): readonly {
+        readonly name: string;
+        readonly kinds?: readonly string[];
+        readonly ctxKeys: readonly string[];
+    }[];
     /**
      * Internal — called by `execute` to build the ctx contribution from every
      * installed capability for one dispatch. Public so subclass dispatchers
      * (forge) can compose; not part of the documented contract.
      */
-    buildCapabilityCtx(envelope: MessageEnvelope): Record<string, unknown>;
+    buildCapabilityCtx(envelope: MessageEnvelope, signal: AbortSignal, kind?: string): Record<string, unknown>;
     /**
      * Install an outbound pipeline stage. Position-ordered: early → middle →
      * terminal. Within a position, install order is run order. Terminal stages
@@ -220,6 +312,48 @@ export declare class Runtime {
     }, payload: unknown, envelope: MessageEnvelope): Promise<void>;
     /** Stable position ordering: early → middle → terminal, install-order within. */
     private orderedSinkStages;
+    /**
+     * Install an inbound source stage — the mirror of `sink(stage)`. Position-
+     * ordered: early → middle → terminal; install order within a position.
+     * Terminal stages carrying a `kind` are deduplicated (one per kind), in a
+     * namespace independent of sink kinds.
+     */
+    source(stage: InboundStage): void;
+    /** All installed source stages plus the terminal router. Used by tests + Studio. */
+    listSourceStages(): readonly InboundStage[];
+    /**
+     * Inbound entry point — the mirror of `sinkDrain`. A transport (HTTP, queue,
+     * broker) hands a raw message here; every source stage runs in position
+     * order (early → middle → terminal), then the default router lands it on the
+     * one execution terminal. A stage returning `{ continue: false }` short-
+     * circuits the rest (e.g. a dedup stage dropping a replay).
+     *
+     * `opts.envelope` carries the seed / overrides the transport resolved
+     * (tenant, user, correlation); `opts.extras` threads transport context
+     * (logger, koa) onto the handler ctx. Returns the router's `ctx.result` — a
+     * command's handler result; events return nothing.
+     */
+    receive(message: InboundMessage, opts?: {
+        envelope?: Partial<MessageEnvelope>;
+        extras?: Record<string, unknown>;
+        /** Cancellation signal threaded onto the dispatch (queue lock, request abort). */
+        signal?: AbortSignal;
+        /**
+         * Parent envelope to inherit from — the message derives a child (carries
+         * correlationId, causationId = parent.messageId). Used by async sources
+         * (queue) that replay a stored envelope.
+         */
+        parent?: MessageEnvelope;
+    }): Promise<unknown>;
+    /** Stable inbound ordering: early → middle → terminal, router lands last. */
+    private orderedSourceStages;
+    /**
+     * The default terminal source stage — the router. A `command` lands on
+     * `execute` (by direct `target` reference, or by `name` through the
+     * registry); an `event` lands on `emit`. This is the one place inbound
+     * messages reach the execution terminal — no second dispatch path.
+     */
+    private buildInboundRouter;
     /**
      * Wire a hook's per-step tap into the canonical telemetry stream. After
      * this call, every `.use()` / `.on()` step on the hook emits a
@@ -242,8 +376,8 @@ export declare class Runtime {
      * subclass-widened records (CQRS kinds in forge) don't need cast
      * gymnastics — listeners narrow with `switch (rec.kind)`.
      *
-     * Public so external dispatchers (forge's ForgeDispatcher composed
-     * around a Runtime instance) can push records without subclassing.
+     * Public so forge's plugins (which ride this runtime rather than
+     * subclassing it) can push their own domain records.
      * Misuse risk is low: callers who own a Runtime are by definition
      * inside the trust boundary.
      *
@@ -264,6 +398,14 @@ export declare class Runtime {
     getHandler(name: string): HandlerDefinition<any, any, any>;
     /** All registered handler names — used by adapters to build wire tables. */
     listHandlers(): readonly string[];
+    /**
+     * Mint the delivery envelope for a dispatch. With a `parent` it derives a
+     * child (correlationId carried, causationId = parent.messageId); otherwise
+     * it seeds a fresh chain from the supplied overrides. The single place the
+     * derive-vs-seed choice lives — `execute`, `emit`, and `enqueue` share it
+     * so a ref minted up-front matches the envelope the handler sees.
+     */
+    private mintEnvelope;
     /**
      * Canonical sync dispatch verb. Validates input via the handler's input
      * schema, mints a child envelope (or seeds one when no parent is given),
@@ -277,21 +419,30 @@ export declare class Runtime {
     execute<TInput = unknown, TOutput = unknown>(handler: HandlerDefinition<any, TOutput, any> | string | ((input: TInput, ctx: any) => TOutput | Promise<TOutput>), input: TInput, envelopePartial?: Partial<MessageEnvelope> & {
         readonly signal?: AbortSignal;
         readonly parent?: MessageEnvelope;
+        /**
+         * A fully-minted envelope to use verbatim — skips derive/seed. Set by
+         * `enqueue`, which mints up-front so the `MessageRef` it returns names
+         * the same message the deferred dispatch runs under.
+         */
+        readonly envelope?: MessageEnvelope;
     }, extras?: Record<string, unknown>): Promise<TOutput>;
     /** Innermost dispatch step that calls the actual handler. Pinned once. */
     private dispatchCorePinned;
     private ensureDispatchCorePin;
     /**
-     * Fire-and-forget dispatch. Default implementation: `setImmediate` →
-     * `execute`. Queue-adapter installation can override this to enqueue
-     * onto an external queue (BullMQ, SQS, etc.). Errors are pushed onto
-     * the telemetry stream as `kind: "enqueue.failed"` — the caller has
-     * already returned.
+     * Fire-and-forget dispatch. Mints the delivery envelope up-front, hands
+     * the deferred dispatch that exact envelope, and returns a {@link MessageRef}
+     * naming it — so the caller can correlate / observe without blocking on the
+     * result. Default implementation: `setImmediate` → `execute`. Queue-adapter
+     * installation can override this to enqueue onto an external queue (BullMQ,
+     * SQS, etc.) while keeping the same up-front envelope + ref contract. Errors
+     * surface on the telemetry stream as `kind: "enqueue.failed"` — the caller
+     * has already returned.
      */
     enqueue<TInput = unknown>(handler: HandlerDefinition<any, any, any> | string, input: TInput, envelopePartial?: Partial<MessageEnvelope> & {
         readonly signal?: AbortSignal;
         readonly parent?: MessageEnvelope;
-    }): Promise<void>;
+    }): Promise<MessageRef>;
     /** Resolve a dependency from the runtime's container. */
     resolve<T = unknown>(name: string): T;
     /**
@@ -303,13 +454,6 @@ export declare class Runtime {
     when<E extends EventDefinition & {
         readonly name: string;
     }>(event: E, listener: (payload: EventPayload<E>, ctx: ListenerContext) => void | Promise<void>): () => void;
-    /**
-     * Alias for {@link when} — same behavior, same return. Preserved for
-     * call sites that prefer the longer name.
-     */
-    subscribe<E extends EventDefinition & {
-        readonly name: string;
-    }>(event: E, listener: (payload: EventPayload<E>, ctx: ListenerContext) => void | Promise<void>): () => void;
     /**
      * Broadcast an event to its subscribers. Validates payload against the
      * event's schema, mints a child envelope, fires every registered
@@ -317,6 +461,19 @@ export declare class Runtime {
      * "event.emitted"` telemetry record. Subscriber throws are captured
      * but do not propagate to the caller.
      */
+    /**
+     * The one incoming-to-all LOCAL delivery. Runs the ordered `LocalDelivery`
+     * chain (forge's idempotency → actors → projections → workflows attach
+     * here); if an upstream step vetoed (`deduped`), stops — otherwise fans
+     * out to `when` listeners. Both `emit` (the validated entry)
+     * and forge's publish ride this, so there is one local-delivery path and
+     * no second fan-out. `envelope` is the already-minted delivery envelope —
+     * callers derive/seed it; `deliver` does not. Returns whether the event
+     * was deduped so a caller can gate its outbound `publish`.
+     */
+    deliver(eventName: string, payload: unknown, envelope: MessageEnvelope, dedupKey: string): Promise<{
+        deduped: boolean;
+    }>;
     emit<TPayload>(event: EventDefinition & {
         readonly name: string;
         readonly schema: {
@@ -395,15 +552,18 @@ export interface PluginDefinition<TOptions = void, TMark = unknown> {
  * What register/setup closures receive. One context type is used by both
  * phases. Members:
  *
- *   - `container` / `runtime` / `hooks` — the layer references
+ *   - `container` / `runtime` / `hooks` — the layer references. `hooks` is
+ *     the runtime's delivery / plugin-extension registry; runtime concerns
+ *     (`add` / `sink`) are reached through `runtime`.
  *   - `options`     — the typed value the plugin was constructed with
  *   - `bind`        — write a binding into the container
- *   - `add(cap)`    — install a capability (proxies to `runtime.add`)
- *   - `sink(stage)` — install an outbound pipeline stage
- *   - `use(mw)`     — wrap dispatch in middleware (via runtime)
- *   - `on(hook, fn)` — observe a framework hook
+ *   - `on(hook, fn)` — observe an app lifecycle hook
  *   - `boot(fn)` / `shutdown(fn)` — async lifecycle queues
- *   - `defineHook(name)` — materialise a plugin-defined framework hook slot
+ *   - `defineHook(name)` — materialise a plugin-defined app lifecycle slot
+ *
+ * Runtime concerns (`runtime.add(cap)`, `runtime.sink(stage)`,
+ * `runtime.use(mw)`) live on the `runtime` reference — the context exposes
+ * app concerns only.
  */
 export interface PluginContext<TOptions = void> {
     readonly container: Container;
@@ -415,21 +575,17 @@ export interface PluginContext<TOptions = void> {
         dispose?: (v: T) => void | Promise<void>;
         check?: (v: T) => void | Promise<void>;
     }): void;
-    /** Install a capability — same as `runtime.add(cap)` but routed through this plugin. */
-    add(cap: Capability<unknown>): void;
-    /** Install an outbound pipeline stage. */
-    sink(stage: OutboundStage): void;
     /**
-     * Observe a framework lifecycle hook — calls `runtime.hooks[name].on(fn)`
-     * under the hood. The payload is typed from the named hook, so
+     * Observe an app lifecycle hook — calls `appHooks[name].on(fn)` under the
+     * hood. The payload is typed from the named hook, so
      * `on("AppBooted", ({ appName, bootedAt }) => …)` is fully inferred.
      */
-    on<K extends keyof FrameworkHooks>(name: K, fn: (payload: FrameworkHooks[K] extends Hook<infer P> ? P : never) => void): void;
+    on<K extends keyof AppHooks>(name: K, fn: (payload: AppHooks[K] extends Hook<infer P> ? P : never) => void): void;
     boot(fn: () => Promise<void> | void): void;
     /** Async cleanup work to run at `runtime.stop()`. */
     dispose(fn: () => Promise<void> | void): void;
     /** Alias for {@link dispose}. */
     shutdown(fn: () => Promise<void> | void): void;
-    defineHook<TCtx>(name: keyof FrameworkHooks): Hook<TCtx>;
+    defineHook<TCtx>(name: keyof AppHooks): Hook<TCtx>;
 }
 export { isBuiltInHook };