@nwire/runtime 0.12.1 → 0.13.0

package/dist/runtime.js

@@ -1,15 +1,17 @@
 /**
- * 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 { createContainer } from "@nwire/container/awilix";
 import { hook } from "@nwire/hooks";
 import { NoopLogger } from "@nwire/logger";
 import { seedEnvelope, deriveEnvelope } from "@nwire/envelope";
-import { createFrameworkHooks, isBuiltInHook } from "./framework-hooks.js";
+import { createFrameworkHooks, isBuiltInHook, } from "./framework-hooks.js";
 export function serializeError(err) {
     if (err instanceof Error) {
         const out = {
@@ -26,6 +28,17 @@ export function serializeError(err) {
     }
     return { name: "NonError", message: String(err) };
 }
+/** Build a {@link MessageRef} from a minted envelope + target metadata. */
+export function messageRef(envelope, name, kind) {
+    return {
+        messageId: envelope.messageId,
+        correlationId: envelope.correlationId,
+        causationId: envelope.causationId,
+        name,
+        kind,
+        tenant: envelope.tenant,
+    };
+}
 export class Runtime {
     container;
     _logger;
@@ -53,9 +66,12 @@ export class Runtime {
     dispatchHook;
     userMiddlewareCount = 0;
     /**
-     * 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`.
      */
     hooks;
     telemetryListeners = [];
@@ -69,7 +85,7 @@ export class Runtime {
     handlers = new Map();
     /**
      * 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)`).
      */
@@ -94,6 +110,16 @@ export class Runtime {
      */
     sinkStages = [];
     terminalKinds = new Set();
+    /**
+     * 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.
+     */
+    sourceStages = [];
+    terminalSourceKinds = new Set();
+    inboundRouter = this.buildInboundRouter();
     constructor(options = {}) {
         this.container = options.container ?? createContainer();
         this._logger = options.logger ?? new NoopLogger();
@@ -180,22 +206,52 @@ export class Runtime {
     listCapabilities() {
         return this.capabilities.map((c) => c.name);
     }
+    /**
+     * 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() {
+        const probe = seedEnvelope({});
+        const signal = new AbortController().signal;
+        return this.capabilities.map((c) => {
+            let ctxKeys = [];
+            if (c.provideCtx) {
+                try {
+                    ctxKeys = Object.keys(c.provideCtx({ envelope: probe, container: this.container, runtime: this, signal }));
+                }
+                catch {
+                    /* probe-time failure — leave ctxKeys empty */
+                }
+            }
+            return { name: c.name, kinds: c.kinds, ctxKeys };
+        });
+    }
     /**
      * 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) {
+    buildCapabilityCtx(envelope, signal, kind) {
         if (this.capabilities.length === 0)
             return {};
         const merged = {};
         for (const cap of this.capabilities) {
             if (!cap.provideCtx)
                 continue;
+            // Kind-scoped: a capability with `kinds` only contributes to dispatches
+            // of those kinds; one without `kinds` is universal. The workflow/actor
+            // routers call this with their kind too, so envelope-scoped verbs have a
+            // single source and no builder re-implements them.
+            if (cap.kinds && (kind === undefined || !cap.kinds.includes(kind)))
+                continue;
             const piece = cap.provideCtx({
                 envelope,
                 container: this.container,
                 runtime: this,
+                signal,
             });
             Object.assign(merged, piece);
         }
@@ -236,7 +292,21 @@ export class Runtime {
         const ordered = this.orderedSinkStages();
         const ctx = { event, payload, envelope };
         for (const stage of ordered) {
+            const t0 = performance.now();
             const result = await stage.run(ctx);
+            this.pushTelemetry({
+                kind: "sink.stage",
+                stage: stage.name,
+                position: stage.position,
+                stageKind: stage.kind,
+                event: event.name,
+                correlationId: envelope.correlationId,
+                tenant: envelope.tenant,
+                shortCircuited: !!(result && result.continue === false),
+                durationMs: performance.now() - t0,
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
             if (result && result.continue === false)
                 return;
         }
@@ -252,6 +322,118 @@ export class Runtime {
             buckets[s.position].push(s);
         return [...buckets.early, ...buckets.middle, ...buckets.terminal];
     }
+    /**
+     * 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) {
+        if (stage.position === "terminal" && stage.kind) {
+            if (this.terminalSourceKinds.has(stage.kind)) {
+                throw new Error(`Runtime.source: terminal stage of kind "${stage.kind}" already installed — only one terminal per kind allowed.`);
+            }
+            this.terminalSourceKinds.add(stage.kind);
+        }
+        this.sourceStages.push(stage);
+    }
+    /** All installed source stages plus the terminal router. Used by tests + Studio. */
+    listSourceStages() {
+        return [...this.sourceStages, this.inboundRouter];
+    }
+    /**
+     * 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.
+     */
+    async receive(message, opts) {
+        const ctx = {
+            message,
+            envelope: opts?.envelope ?? {},
+            extras: opts?.extras,
+            signal: opts?.signal,
+            parent: opts?.parent,
+            resolve: (name) => this.container.resolve(name),
+        };
+        for (const stage of this.orderedSourceStages()) {
+            // The terminal router lands the message on execute/emit, which emit
+            // their own records; recording it here would double-count. Installed
+            // stages get one `source.stage` record each.
+            if (stage === this.inboundRouter) {
+                const result = await stage.run(ctx);
+                if (result && result.continue === false)
+                    return ctx.result;
+                continue;
+            }
+            const t0 = performance.now();
+            const result = await stage.run(ctx);
+            this.pushTelemetry({
+                kind: "source.stage",
+                stage: stage.name,
+                position: stage.position,
+                stageKind: stage.kind,
+                message: { name: ctx.message?.name, kind: ctx.message?.kind },
+                correlationId: ctx.envelope.correlationId,
+                tenant: ctx.envelope.tenant,
+                shortCircuited: !!(result && result.continue === false),
+                durationMs: performance.now() - t0,
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+            if (result && result.continue === false)
+                return ctx.result;
+        }
+        return ctx.result;
+    }
+    /** Stable inbound ordering: early → middle → terminal, router lands last. */
+    orderedSourceStages() {
+        const buckets = {
+            early: [],
+            middle: [],
+            terminal: [],
+        };
+        for (const s of this.sourceStages)
+            buckets[s.position].push(s);
+        return [...buckets.early, ...buckets.middle, ...buckets.terminal, this.inboundRouter];
+    }
+    /**
+     * 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.
+     */
+    buildInboundRouter() {
+        return {
+            name: "router",
+            position: "terminal",
+            run: async (ctx) => {
+                const msg = ctx.message;
+                if (!msg)
+                    return;
+                if (msg.kind === "command") {
+                    const target = msg.target ?? msg.name;
+                    ctx.result = await this.execute(target, msg.input, { ...ctx.envelope, parent: ctx.parent, signal: ctx.signal }, ctx.extras);
+                }
+                else {
+                    if (!msg.event) {
+                        throw new Error(`Runtime.receive: event "${msg.name}" arrived without its definition; ` +
+                            "inbound events need `event` set so emit can validate the payload.");
+                    }
+                    ctx.result = await this.emit(msg.event, msg.input, {
+                        ...ctx.envelope,
+                        parent: ctx.parent,
+                    });
+                }
+            },
+        };
+    }
     /**
      * Wire a hook's per-step tap into the canonical telemetry stream. After
      * this call, every `.use()` / `.on()` step on the hook emits a
@@ -299,8 +481,8 @@ export 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.
      *
@@ -351,6 +533,28 @@ export class Runtime {
     listHandlers() {
         return [...this.handlers.keys()];
     }
+    /**
+     * 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.
+     */
+    mintEnvelope(partial) {
+        return partial?.parent
+            ? deriveEnvelope(partial.parent, {
+                tenant: partial.tenant,
+                userId: partial.userId,
+                user: partial.user,
+            })
+            : seedEnvelope({
+                tenant: partial?.tenant,
+                userId: partial?.userId,
+                user: partial?.user,
+                causationId: partial?.causationId,
+                correlationId: partial?.correlationId,
+            });
+    }
     /**
      * Canonical sync dispatch verb. Validates input via the handler's input
      * schema, mints a child envelope (or seeds one when no parent is given),
@@ -370,28 +574,19 @@ export class Runtime {
         // parent envelope threads through so correlationId stays linked and
         // causationId records what triggered this dispatch. When called from
         // an entry point (HTTP adopter, queue subscriber) with no parent, the
-        // envelope is seeded fresh — either from explicit overrides or a fully
-        // new chain.
-        const envelope = envelopePartial?.parent
-            ? deriveEnvelope(envelopePartial.parent, {
-                tenant: envelopePartial.tenant,
-                userId: envelopePartial.userId,
-                user: envelopePartial.user,
-            })
-            : seedEnvelope({
-                tenant: envelopePartial?.tenant,
-                userId: envelopePartial?.userId,
-                user: envelopePartial?.user,
-                causationId: envelopePartial?.causationId,
-                correlationId: envelopePartial?.correlationId,
-            });
+        // envelope is seeded fresh. A pre-minted `envelope` (from `enqueue`) is
+        // used verbatim so the returned ref and the handler agree on identity.
+        const envelope = envelopePartial?.envelope ?? this.mintEnvelope(envelopePartial);
         const scope = this.container.createScope();
         const signal = envelopePartial?.signal ?? new AbortController().signal;
         // Capability ctx — every `runtime.add(cap)` contributes per-dispatch
-        // ctx members via `provideCtx`. Spread FIRST so handler-provided extras
-        // and the canonical runtime verbs (execute/enqueue/emit/resolve/scope)
-        // can shadow if there's a name collision.
-        const capCtx = this.buildCapabilityCtx(envelope);
+        // ctx members via `provideCtx`, scoped to the target's kind. Spread FIRST
+        // so handler-provided extras and the canonical runtime verbs (execute/
+        // enqueue/emit/resolve/scope) can shadow if there's a name collision.
+        const targetKind = target?.config?.kind ??
+            target?.$kind ??
+            "handler";
+        const capCtx = this.buildCapabilityCtx(envelope, signal, targetKind);
         // The handler chain expects a ctx with at least `input` on it. We also
         // expose envelope + the three verbs bound to this runtime, threaded
         // with this envelope as the parent so child dispatches inherit the
@@ -404,6 +599,10 @@ export class Runtime {
             ...(extras ?? {}),
             input,
             envelope,
+            // The per-dispatch cancellation signal, available to every handler
+            // shape (plain `(input, ctx)` and forge). Forge's capability sets the
+            // same value; exposing it here makes signal observation uniform.
+            signal,
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             execute: (h, i, partial) => this.execute(h, i, { ...partial, parent: envelope }),
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -428,7 +627,10 @@ export class Runtime {
             if (this.userMiddlewareCount > 0) {
                 this.ensureDispatchCorePin();
                 const hctx = {
-                    action: def,
+                    // Dispatch middleware (auth/rbac/tracing) reads the action contract
+                    // (policy/retry/name). When the handler implements one — forge
+                    // actions carry `.action` — expose that; otherwise the handler def.
+                    action: def.action ?? def,
                     input,
                     ctx,
                     coreFn: innerCore,
@@ -462,28 +664,37 @@ export class Runtime {
         this.dispatchCorePinned = true;
     }
     /**
-     * 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(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     handler, input, envelopePartial) {
         const name = typeof handler === "string" ? handler : handler.name;
+        const envelope = this.mintEnvelope(envelopePartial);
         setImmediate(() => {
-            void this.execute(handler, input, envelopePartial).catch((err) => {
+            void this.execute(handler, input, {
+                envelope,
+                signal: envelopePartial?.signal,
+            }).catch((err) => {
                 this.pushTelemetry({
                     kind: "enqueue.failed",
                     handler: name,
+                    messageId: envelope.messageId,
+                    correlationId: envelope.correlationId,
                     error: serializeError(err),
                     appName: this.appName,
                     ts: new Date().toISOString(),
                 });
             });
         });
-        return Promise.resolve();
+        return Promise.resolve(messageRef(envelope, name, "command"));
     }
     /** Resolve a dependency from the runtime's container. */
     resolve(name) {
@@ -501,18 +712,15 @@ export class Runtime {
             set = new Set();
             this.eventListeners.set(event.name, set);
         }
-        set.add(listener);
+        // A listener IS a handler — tag the fn `kind:"listener"` so it gets the
+        // kind-scoped ctx + per-run telemetry like every other unit of behavior.
+        // Store the tagged wrapper (not the raw fn) so unsubscribe stays exact.
+        const handler = asListenerHandler(listener);
+        set.add(handler);
         return () => {
-            this.eventListeners.get(event.name)?.delete(listener);
+            this.eventListeners.get(event.name)?.delete(handler);
         };
     }
-    /**
-     * Alias for {@link when} — same behavior, same return. Preserved for
-     * call sites that prefer the longer name.
-     */
-    subscribe(event, listener) {
-        return this.when(event, listener);
-    }
     /**
      * Broadcast an event to its subscribers. Validates payload against the
      * event's schema, mints a child envelope, fires every registered
@@ -520,42 +728,60 @@ export class Runtime {
      * "event.emitted"` telemetry record. Subscriber throws are captured
      * but do not propagate to the caller.
      */
-    async emit(event, payload, envelopePartial) {
-        const validated = event.schema.parse(payload);
-        const envelope = envelopePartial?.parent
-            ? deriveEnvelope(envelopePartial.parent, {
-                tenant: envelopePartial.tenant,
-                userId: envelopePartial.userId,
-                user: envelopePartial.user,
-            })
-            : seedEnvelope({
-                tenant: envelopePartial?.tenant,
-                userId: envelopePartial?.userId,
-                user: envelopePartial?.user,
-                causationId: envelopePartial?.causationId,
-                correlationId: envelopePartial?.correlationId,
-            });
-        const startedAt = performance.now();
-        const subs = this.eventListeners.get(event.name);
+    /**
+     * 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`.
+     */
+    async deliver(eventName, payload, envelope, dedupKey) {
+        const dp = { eventName, payload, envelope, dedupKey, deduped: false };
+        await this.hooks.LocalDelivery.run(dp);
+        if (dp.deduped)
+            return { deduped: true };
+        const subs = this.eventListeners.get(eventName);
         if (subs && subs.size > 0) {
-            // Listener ctx — the documented subset of the workflow `when` ctx,
-            // every verb threaded with this envelope as parent so follow-up
-            // dispatches inherit the correlation chain.
+            // Listener ctx, kind-scoped: `buildCapabilityCtx("listener")` layers any
+            // listener-tagged plugin verbs on top of the core base verbs every
+            // listener has. The base verbs stay core (a forge-less app reacts too),
+            // each threaded with this envelope as parent so follow-ups inherit the
+            // correlation chain. Identical shape to the workflow `when` ctx subset.
+            const capCtx = this.buildCapabilityCtx(envelope, new AbortController().signal, "listener");
             const listenerCtx = {
+                ...capCtx,
                 envelope,
                 send: (h, i, partial) => this.execute(h, i, { ...partial, parent: envelope }),
                 emit: (ev, p, partial) => this.emit(ev, p, { ...partial, parent: envelope }),
                 resolve: (name) => this.container.resolve(name),
                 logger: this._logger,
             };
-            // Wrap in async so a SYNC throw inside fn() rejects the wrapper
-            // rather than escaping the .map(). allSettled then captures it.
-            const results = await Promise.allSettled([...subs].map(async (fn) => fn(validated, listenerCtx)));
+            const appName = this.appName;
+            // Each listener is a `kind:"listener"` handler — fire in parallel, record
+            // a dispatch-style record per run so a reaction shows in the trace.
+            // SYNC throws reject the async wrapper; allSettled captures them so a
+            // failing listener never breaks siblings.
+            const results = await Promise.allSettled([...subs].map(async (fn) => {
+                const t0 = performance.now();
+                await fn(payload, listenerCtx);
+                this.pushTelemetry({
+                    kind: "listener.fired",
+                    event: eventName,
+                    listener: fn.name || "listener",
+                    durationMs: performance.now() - t0,
+                    envelope,
+                    appName,
+                    ts: new Date().toISOString(),
+                });
+            }));
             for (const r of results) {
                 if (r.status === "rejected") {
                     this.pushTelemetry({
                         kind: "event.listener.failed",
-                        event: event.name,
+                        event: eventName,
                         envelope,
                         error: serializeError(r.reason),
                         appName: this.appName,
@@ -564,18 +790,46 @@ export class Runtime {
                 }
             }
         }
+        return { deduped: false };
+    }
+    async emit(event, payload, envelopePartial) {
+        const validated = event.schema.parse(payload);
+        const envelope = this.mintEnvelope(envelopePartial);
+        const startedAt = performance.now();
+        const subscriberCount = this.eventListeners.get(event.name)?.size ?? 0;
+        // One local delivery — runs the LocalDelivery chain (empty until forge
+        // attaches its fold steps) then fans out to listeners.
+        await this.deliver(event.name, validated, envelope, envelope.messageId);
         this.pushTelemetry({
             kind: "event.emitted",
             event: event.name,
             payload: validated,
             envelope,
             durationMs: performance.now() - startedAt,
-            subscriberCount: subs?.size ?? 0,
+            subscriberCount,
             appName: this.appName,
             ts: new Date().toISOString(),
         });
     }
 }
+/**
+ * Wrap a bare listener fn as a `kind:"listener"` handler. Wraps (never mutates)
+ * the user's fn so a shared closure isn't tagged in place; idempotent if the fn
+ * is already a listener handler. The name is taken from the fn for telemetry.
+ */
+function asListenerHandler(fn) {
+    const tagged = fn;
+    if (tagged.$kind === "handler" && tagged.config?.kind === "listener") {
+        return fn;
+    }
+    const handler = ((payload, ctx) => fn(payload, ctx));
+    Object.defineProperties(handler, {
+        $kind: { value: "handler", enumerable: true },
+        config: { value: { kind: "listener" }, enumerable: true },
+        name: { value: fn.name || "listener", enumerable: true, configurable: true },
+    });
+    return handler;
+}
 /**
  * Canonical factory for a Runtime. Matches the foundation-doc shape
  * (`createRuntime(opts)`) so consumer code stays uniform across