@nwire/forge 0.12.1 → 0.13.1

package/dist/runtime/forge-dispatcher.d.ts

@@ -23,7 +23,7 @@ import { type DeadLetterSink } from "@nwire/dead-letter";
 import type { EventBus } from "@nwire/bus";
 import type { z } from "zod";
 import type { ActionDefinition, ActionInput, ActionResult } from "../primitives/define-action.js";
-import type { HandlerDefinition } from "../primitives/define-handler.js";
+import type { HandlerContext, HandlerDefinition } from "../primitives/define-handler.js";
 import type { ActorDefinition } from "../primitives/define-actor.js";
 import type { WorkflowDefinition, WorkflowInstance } from "../primitives/define-workflow.js";
 import type { ProjectionDefinition } from "../primitives/define-projection.js";
@@ -133,9 +133,19 @@ export declare class ForgeDispatcher {
     fireDueTimers(now?: number): Promise<number>;
     fireDueWorkflowTimers(now?: Date): Promise<number>;
     dispatch<A extends ActionDefinition>(action: A, input: ActionInput<A>, parentEnvelope?: MessageEnvelope, opts?: DispatchOptions): Promise<ActionResult<A>>;
+    /**
+     * The forge command pipeline — runs as a registered action handler's core
+     * under `runtime.execute`: `action.dispatched` telemetry, the
+     * `ActionDispatching` veto hook, the per-action `before`/`after` hooks,
+     * retry + backoff invoking the raw handler, dead-letter on exhaustion,
+     * completion/failure telemetry, and event-return publishing. `ctx` is
+     * execute's handler ctx (capCtx + verbs); `rawHandler` is the action's
+     * original handler fn.
+     */
+    runActionPipeline(action: ActionDefinition<any>, rawHandler: (input: unknown, ctx: HandlerContext) => unknown, ctx: HandlerContext, signal: AbortSignal): Promise<unknown>;
     /**
      * Publish a batch of events. Each event flows through the
-     * `EventPublishing` hook chain — idempotency → actors → projections →
+     * `LocalDelivery` hook chain — idempotency → actors → projections →
      * workflows → bus — at structurally enforced priorities. The chain
      * participants are attached once at plugin setup via
      * {@link attachPublishChain}.
@@ -145,23 +155,29 @@ export declare class ForgeDispatcher {
      */
     publish(events: readonly EventMessage[], parentEnvelope: MessageEnvelope): Promise<void>;
     /**
-     * Attach forge's atomic publish chain to the `EventPublishing` hook.
+     * Attach forge's bundled fold steps to the core `LocalDelivery` hook.
      * Priority slots are defined in `EVENT_PUBLISHING_PRIORITIES`:
      *
-     *   1000 — idempotency gate. Short-circuits on duplicate.
+     *   1000 — idempotency gate. Short-circuits (vetoes) on duplicate.
      *    800 — actor state transitions.
      *    600 — projection folds.
      *    400 — workflow correlation + fire.
-     *    200 — cross-process bus delivery (public events only).
-     *    100 — outbound sink drain (public events only) — feeds
-     *          adopters that install via `installSinkStage` (bullmq,
-     *          AMQP, telemetry-otel, …).
      *
-     * Called once at plugin setup. Idempotent — re-attaching is a no-op
-     * because the hook engine guards against duplicate step names.
+     * Cross-process bus delivery and the outbound sink drain are NOT chain
+     * steps — they're the outgoing `publish` concern, applied by
+     * `dispatcher.publish` after `runtime.deliver` for public, non-deduped
+     * events. Keeping them out of the local chain means local `emit` (and
+     * `publishCapability`) never double-drain.
+     *
+     * Called once at plugin setup (bundled mode). NOTE: the hook engine does
+     * NOT dedup step names — bundled (`createForgePlugin`) and à-la-carte (the
+     * sub-plugins) are mutually exclusive; mixing them double-registers a fold
+     * step. Each sub-plugin warns at `AppReady` if it detects a duplicate
+     * (the `AppReady` hook fires `.on` listeners via `allSettled`, so a thrown
+     * guard would be swallowed — a hard-fail needs a registration-time check;
+     * tracked as a follow-up).
      */
     attachPublishChain(): void;
-    applyExternalEvent(eventName: string, payload: unknown, envelope: MessageEnvelope): Promise<void>;
     private foldProjections;
     private applyToActors;
     private extractKey;
@@ -169,7 +185,9 @@ export declare class ForgeDispatcher {
     private applyEventToActorLocked;
     private computeTimersForState;
     private runWorkflows;
-    private buildHandlerContext;
+    /** Public actor-view accessor — backs the `actor(actor, id)` ctx member. */
+    actorView<TActor extends ActorDefinition>(actor: TActor, id: string, envelope: MessageEnvelope): Promise<any>;
     private loadActorView;
     getDeadLetterSink(): DeadLetterSink;
 }
+/** Local alias for the dispatch-hook ctx shape; lifted into kernel.Runtime. */

package/dist/runtime/forge-dispatcher.js

@@ -116,9 +116,20 @@ export class ForgeDispatcher {
         this.handlers.set(name, handler);
         this.ensureActionBeforeHook(name);
         this.ensureActionAfterHook(name);
+        // Make the handler's `run` the forge command pipeline, so dispatching it
+        // through `runtime.execute` (whether from `dispatch`, a wire, or HTTP)
+        // runs retry/DLQ/hooks/telemetry/event-publish as the core. Mutate in
+        // place so every reference (dispatcher, runtime registry, wires) shares
+        // it. The retry loop re-invokes the raw `handler.handler` directly, as
+        // before — no nested `.use` chain.
+        const rawHandler = handler.handler;
+        const action = handler.action;
+        handler.run = async (ctx, opts) => ({
+            result: await this.runActionPipeline(action, rawHandler, ctx, opts?.signal ?? new AbortController().signal),
+        });
         // The action declares `emits: [SomeEvent, ...]`. Any event the
         // author marked `.public()` carries `$public: true` — surface it
-        // to the dispatcher so the EventPublishing chain's bus + outbound
+        // to the dispatcher so the LocalDelivery chain's bus + outbound
         // steps fire when that event flows through.
         const emits = handler.action.emits;
         if (emits) {
@@ -434,12 +445,35 @@ export class ForgeDispatcher {
         if (!handler) {
             throw new Error(`Runtime: no handler registered for action "${action.name}".`);
         }
+        // One dispatch path. The handler's `run` IS the forge command pipeline
+        // (installed at registerActionHandler), so retry / DLQ / ActionDispatching /
+        // before-after / telemetry / event-publish run as the handler's core under
+        // `runtime.execute` — capCtx, one per-request scope, one dispatch pin.
+        return this.runtime.execute(handler, input, {
+            parent: parentEnvelope,
+            signal: opts?.signal,
+        });
+    }
+    /**
+     * The forge command pipeline — runs as a registered action handler's core
+     * under `runtime.execute`: `action.dispatched` telemetry, the
+     * `ActionDispatching` veto hook, the per-action `before`/`after` hooks,
+     * retry + backoff invoking the raw handler, dead-letter on exhaustion,
+     * completion/failure telemetry, and event-return publishing. `ctx` is
+     * execute's handler ctx (capCtx + verbs); `rawHandler` is the action's
+     * original handler fn.
+     */
+    async runActionPipeline(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    action, rawHandler, ctx, signal) {
         const appName = this.runtime.appName;
-        const envelope = parentEnvelope ? deriveEnvelope(parentEnvelope) : seedEnvelope({});
-        const validated = isValidated(input) ? input : markValidated(action.schema.parse(input));
+        const envelope = ctx.envelope;
+        const rawInput = ctx.input;
+        const validated = isValidated(rawInput)
+            ? rawInput
+            : markValidated(action.schema.parse(rawInput));
         const log = loggerForEnvelope(this.runtime.logger, envelope);
-        const signal = opts?.signal ?? new AbortController().signal;
-        const ctx = this.buildHandlerContext(envelope, log, signal);
+        const startedAt = performance.now();
         this.runtime.pushTelemetry({
             kind: "action.dispatched",
             action: action.name,
@@ -448,7 +482,6 @@ export class ForgeDispatcher {
             appName,
             ts: new Date().toISOString(),
         });
-        const startedAt = performance.now();
         const dispatchResult = await this.runtime.hooks.ActionDispatching.runDetailed({
             action,
             input: validated,
@@ -468,128 +501,123 @@ export class ForgeDispatcher {
                 return undefined;
             }
         }
-        const core = async () => {
-            const retry = action.retry;
-            const maxAttempts = 1 + (retry?.max ?? 0);
-            let attempt = 0;
-            let lastError;
-            while (attempt < maxAttempts) {
-                attempt++;
-                if (attempt > 1 && signal.aborted) {
-                    log.warn(`abort observed between attempts; skipping retries`, {
+        const retry = action.retry;
+        const maxAttempts = 1 + (retry?.max ?? 0);
+        let attempt = 0;
+        let lastError;
+        while (attempt < maxAttempts) {
+            attempt++;
+            if (attempt > 1 && signal.aborted) {
+                log.warn(`abort observed between attempts; skipping retries`, {
+                    action: action.name,
+                    attempt,
+                    maxAttempts,
+                });
+                // eslint-disable-next-line no-throw-literal
+                throw lastError;
+            }
+            try {
+                if (attempt > 1) {
+                    const delay = computeBackoff(retry, attempt - 1);
+                    log.warn(`retrying handler`, {
                         action: action.name,
                         attempt,
                         maxAttempts,
+                        delayMs: delay,
                     });
-                    // eslint-disable-next-line no-throw-literal
-                    throw lastError;
+                    if (delay > 0)
+                        await sleep(delay);
                 }
-                try {
-                    if (attempt > 1) {
-                        const delay = computeBackoff(retry, attempt - 1);
-                        log.warn(`retrying handler`, {
-                            action: action.name,
-                            attempt,
-                            maxAttempts,
-                            delayMs: delay,
+                const rawResult = await rawHandler(validated, ctx);
+                const events = normalizeEventReturn((rawResult ?? null));
+                if (events.length > 0) {
+                    await this.publish(events, envelope);
+                }
+                const durationMs = performance.now() - startedAt;
+                this.runtime.pushTelemetry({
+                    kind: "action.completed",
+                    action: action.name,
+                    durationMs,
+                    emittedEvents: events.map((e) => e.eventName),
+                    envelope,
+                    appName,
+                    ts: new Date().toISOString(),
+                });
+                const afterHook = this.actionAfterHooks.get(action.name);
+                if (afterHook) {
+                    try {
+                        await afterHook.run({
+                            action,
+                            input: validated,
+                            result: rawResult ?? undefined,
+                            durationMs,
                         });
-                        if (delay > 0)
-                            await sleep(delay);
                     }
-                    const rawResult = await handler.handler(validated, ctx);
-                    const events = normalizeEventReturn(rawResult ?? null);
-                    if (events.length > 0) {
-                        await this.publish(events, envelope);
-                    }
-                    const durationMs = performance.now() - startedAt;
-                    this.runtime.pushTelemetry({
-                        kind: "action.completed",
-                        action: action.name,
-                        durationMs,
-                        emittedEvents: events.map((e) => e.eventName),
-                        envelope,
-                        appName,
-                        ts: new Date().toISOString(),
-                    });
-                    const afterHook = this.actionAfterHooks.get(action.name);
-                    if (afterHook) {
-                        try {
-                            await afterHook.run({
-                                action,
-                                input: validated,
-                                result: rawResult ?? undefined,
-                                durationMs,
-                            });
-                        }
-                        catch (err) {
-                            log.error(`action.after hook threw`, {
-                                action: action.name,
-                                error: err?.message,
-                            });
-                        }
+                    catch (err) {
+                        log.error(`action.after hook threw`, {
+                            action: action.name,
+                            error: err?.message,
+                        });
                     }
-                    void this.runtime.hooks.ActionCompleted.run({
+                }
+                void this.runtime.hooks.ActionCompleted.run({
+                    action,
+                    input: validated,
+                    result: rawResult ?? undefined,
+                    durationMs,
+                });
+                return rawResult ?? undefined;
+            }
+            catch (err) {
+                lastError = err;
+                log.error(`handler threw`, {
+                    action: action.name,
+                    attempt,
+                    maxAttempts,
+                    error: err?.message,
+                });
+                this.runtime.pushTelemetry({
+                    kind: "action.failed",
+                    action: action.name,
+                    attempt,
+                    maxAttempts,
+                    willRetry: attempt < maxAttempts,
+                    error: serializeError(err),
+                    envelope,
+                    appName,
+                    ts: new Date().toISOString(),
+                });
+                if (attempt >= maxAttempts) {
+                    void this.runtime.hooks.ActionFailed.run({
                         action,
                         input: validated,
-                        result: rawResult ?? undefined,
-                        durationMs,
+                        error: err,
+                        durationMs: performance.now() - startedAt,
                     });
-                    return rawResult ?? undefined;
-                }
-                catch (err) {
-                    lastError = err;
-                    log.error(`handler threw`, {
-                        action: action.name,
-                        attempt,
-                        maxAttempts,
-                        error: err?.message,
-                    });
-                    this.runtime.pushTelemetry({
-                        kind: "action.failed",
-                        action: action.name,
-                        attempt,
-                        maxAttempts,
-                        willRetry: attempt < maxAttempts,
-                        error: serializeError(err),
-                        envelope,
-                        appName,
-                        ts: new Date().toISOString(),
-                    });
-                    if (attempt >= maxAttempts) {
-                        void this.runtime.hooks.ActionFailed.run({
-                            action,
-                            input: validated,
-                            error: err,
-                            durationMs: performance.now() - startedAt,
-                        });
-                    }
                 }
             }
-            const entry = buildDeadLetterEntry(action.name, validated, envelope, attempt, lastError);
-            await this.deadLetterSink.record(entry);
-            log.error(`dead-lettered after ${attempt} attempts`, {
-                action: action.name,
-                error: entry.lastError.message,
-            });
-            this.runtime.pushTelemetry({
-                kind: "dlq.recorded",
-                action: action.name,
-                attempts: attempt,
-                error: serializeError(lastError),
-                envelope,
-                appName,
-                ts: new Date().toISOString(),
-            });
-            throw lastError;
-        };
-        const hctx = { action, input: validated, ctx, coreFn: core };
-        await this.runtime.dispatchHook$.run(hctx);
-        return hctx.result;
+        }
+        const entry = buildDeadLetterEntry(action.name, validated, envelope, attempt, lastError);
+        await this.deadLetterSink.record(entry);
+        log.error(`dead-lettered after ${attempt} attempts`, {
+            action: action.name,
+            error: entry.lastError.message,
+        });
+        this.runtime.pushTelemetry({
+            kind: "dlq.recorded",
+            action: action.name,
+            attempts: attempt,
+            error: serializeError(lastError),
+            envelope,
+            appName,
+            ts: new Date().toISOString(),
+        });
+        throw lastError;
     }
-    // ─── Publish + applyExternalEvent ──────────────────────────────────
+    // ─── Publish ───────────────────────────────────────────────────────
     /**
      * Publish a batch of events. Each event flows through the
-     * `EventPublishing` hook chain — idempotency → actors → projections →
+     * `LocalDelivery` hook chain — idempotency → actors → projections →
      * workflows → bus — at structurally enforced priorities. The chain
      * participants are attached once at plugin setup via
      * {@link attachPublishChain}.
@@ -603,14 +631,10 @@ export class ForgeDispatcher {
             const event = events[i];
             const dedupKey = events.length === 1 ? parentEnvelope.messageId : `${parentEnvelope.messageId}#${i}`;
             const childEnvelope = deriveEnvelope(parentEnvelope);
-            const payload = {
-                event,
-                envelope: childEnvelope,
-                dedupKey,
-                deduped: false,
-            };
-            await this.runtime.hooks.EventPublishing.run(payload);
-            if (payload.deduped) {
+            // Local delivery (incoming-to-all): the LocalDelivery fold chain
+            // (idempotency → actors → projections → workflows) + core listeners.
+            const { deduped } = await this.runtime.deliver(event.eventName, event.payload, childEnvelope, dedupKey);
+            if (deduped) {
                 this.runtime.pushTelemetry({
                     kind: "event.deduped",
                     event,
@@ -619,108 +643,79 @@ export class ForgeDispatcher {
                     appName,
                     ts: new Date().toISOString(),
                 });
+                continue;
             }
-            else {
-                this.runtime.pushTelemetry({
-                    kind: "event.published",
-                    event,
-                    envelope: childEnvelope,
-                    source: "in-process",
-                    appName,
-                    ts: new Date().toISOString(),
-                });
+            // Outbound (publish = outgoing only): cross-process bus + sink drain
+            // for public, non-deduped events. Moved OUT of the local chain so
+            // local `emit` / `publishCapability` never double-drain (trap b), and
+            // a dedup veto skips outbound (trap c).
+            if (this.publicEventNames.has(event.eventName)) {
+                if (this.publishToBus && this.bus) {
+                    await this.bus.publish({
+                        eventName: event.eventName,
+                        payload: event.payload,
+                        envelope: childEnvelope,
+                        origin: this.runtime.appName,
+                    });
+                }
+                const eventRef = { name: event.eventName };
+                await this.runtime.sinkDrain(eventRef, event.payload, childEnvelope);
             }
+            this.runtime.pushTelemetry({
+                kind: "event.published",
+                event,
+                envelope: childEnvelope,
+                source: "in-process",
+                appName,
+                ts: new Date().toISOString(),
+            });
         }
     }
     /**
-     * Attach forge's atomic publish chain to the `EventPublishing` hook.
+     * Attach forge's bundled fold steps to the core `LocalDelivery` hook.
      * Priority slots are defined in `EVENT_PUBLISHING_PRIORITIES`:
      *
-     *   1000 — idempotency gate. Short-circuits on duplicate.
+     *   1000 — idempotency gate. Short-circuits (vetoes) on duplicate.
      *    800 — actor state transitions.
      *    600 — projection folds.
      *    400 — workflow correlation + fire.
-     *    200 — cross-process bus delivery (public events only).
-     *    100 — outbound sink drain (public events only) — feeds
-     *          adopters that install via `installSinkStage` (bullmq,
-     *          AMQP, telemetry-otel, …).
      *
-     * Called once at plugin setup. Idempotent — re-attaching is a no-op
-     * because the hook engine guards against duplicate step names.
+     * Cross-process bus delivery and the outbound sink drain are NOT chain
+     * steps — they're the outgoing `publish` concern, applied by
+     * `dispatcher.publish` after `runtime.deliver` for public, non-deduped
+     * events. Keeping them out of the local chain means local `emit` (and
+     * `publishCapability`) never double-drain.
+     *
+     * Called once at plugin setup (bundled mode). NOTE: the hook engine does
+     * NOT dedup step names — bundled (`createForgePlugin`) and à-la-carte (the
+     * sub-plugins) are mutually exclusive; mixing them double-registers a fold
+     * step. Each sub-plugin warns at `AppReady` if it detects a duplicate
+     * (the `AppReady` hook fires `.on` listeners via `allSettled`, so a thrown
+     * guard would be swallowed — a hard-fail needs a registration-time check;
+     * tracked as a follow-up).
      */
     attachPublishChain() {
-        const hook = this.runtime.hooks.EventPublishing;
+        const hook = this.runtime.hooks.LocalDelivery;
         hook.use(async (payload, next) => {
             const isNew = await this.idempotencyStore.recordIfNew(payload.dedupKey);
             if (!isNew) {
                 payload.deduped = true;
-                return; // veto — downstream steps skipped
+                return; // veto — downstream steps + listeners skipped
             }
             await next();
         }, { name: "forge.publish.idempotency", priority: EVENT_PUBLISHING_PRIORITIES.idempotency });
         hook.use(async (payload, next) => {
-            await this.applyToActors(payload.event, payload.envelope);
+            await this.applyToActors({ eventName: payload.eventName, payload: payload.payload }, payload.envelope);
             await next();
         }, { name: "forge.publish.actors", priority: EVENT_PUBLISHING_PRIORITIES.actors });
         hook.use(async (payload, next) => {
-            await this.foldProjections(payload.event, payload.envelope);
+            await this.foldProjections({ eventName: payload.eventName, payload: payload.payload }, payload.envelope);
             await next();
         }, { name: "forge.publish.projections", priority: EVENT_PUBLISHING_PRIORITIES.projections });
         hook.use(async (payload, next) => {
-            await this.runWorkflows(payload.event, payload.envelope);
+            await this.runWorkflows({ eventName: payload.eventName, payload: payload.payload }, payload.envelope);
             await next();
         }, { name: "forge.publish.workflows", priority: EVENT_PUBLISHING_PRIORITIES.workflows });
-        hook.use(async (payload, next) => {
-            if (this.publishToBus && this.bus && this.publicEventNames.has(payload.event.eventName)) {
-                await this.bus.publish({
-                    eventName: payload.event.eventName,
-                    payload: payload.event.payload,
-                    envelope: payload.envelope,
-                    origin: this.runtime.appName,
-                });
-            }
-            await next();
-        }, { name: "forge.publish.bus", priority: EVENT_PUBLISHING_PRIORITIES.bus });
-        hook.use(async (payload, next) => {
-            if (this.publicEventNames.has(payload.event.eventName)) {
-                // Outbound sink chain — adopters like bullmq, AMQP, telemetry-otel
-                // install terminal stages via `installSinkStage`. `sinkDrain`
-                // reads `.name` off the event; the schema is not consulted here.
-                const eventRef = { name: payload.event.eventName };
-                await this.runtime.sinkDrain(eventRef, payload.event.payload, payload.envelope);
-            }
-            await next();
-        }, { name: "forge.publish.outbound", priority: EVENT_PUBLISHING_PRIORITIES.outbound });
-    }
-    async applyExternalEvent(eventName, payload, envelope) {
-        if (!this.externalEventNames.has(eventName)) {
-            throw new Error(`Runtime.applyExternalEvent: "${eventName}" was not declared in any module's needs.externalEvents.`);
-        }
-        const appName = this.runtime.appName;
-        const event = { eventName, payload };
-        const isNew = await this.idempotencyStore.recordIfNew(envelope.messageId);
-        if (!isNew) {
-            this.runtime.pushTelemetry({
-                kind: "event.deduped",
-                event,
-                envelope,
-                source: "external",
-                appName,
-                ts: new Date().toISOString(),
-            });
-            return;
-        }
-        await this.applyToActors(event, envelope);
-        await this.foldProjections(event, envelope);
-        await this.runWorkflows(event, envelope);
-        this.runtime.pushTelemetry({
-            kind: "event.published",
-            event,
-            envelope,
-            source: "external",
-            appName,
-            ts: new Date().toISOString(),
-        });
     }
     // ─── Projection folding ────────────────────────────────────────────
     async foldProjections(event, envelope) {
@@ -923,14 +918,14 @@ export class ForgeDispatcher {
         const log = loggerForEnvelope(this.runtime.logger, envelope).child({
             event: event.eventName,
         });
-        const handlerCtx = this.buildHandlerContext(envelope, log);
         const self = this;
+        const container = this.runtime.getContainer();
         const baseEffects = {
             async send(action, input) {
-                return handlerCtx.request(action, input);
+                return self.dispatch(action, input, envelope);
             },
             async enqueue(action, input) {
-                await handlerCtx.send(action, input);
+                await self.dispatch(action, input, envelope);
             },
             async publish(eventMsg) {
                 await self.publish([eventMsg], envelope);
@@ -951,7 +946,7 @@ export class ForgeDispatcher {
                     // event is .public() and a sink is installed. Built via the event
                     // factory so messageId / correlation / idempotency hold.
                     emit: (eventDef, payload) => self.publish([eventFactory(eventDef)(payload)], envelope),
-                    resolve: (name) => handlerCtx.resolve(name),
+                    resolve: (name) => container.resolve(name),
                     logger: log,
                     load: (key) => store.get(key),
                     save: (key, instance) => store.set(key, instance),
@@ -1065,49 +1060,15 @@ export class ForgeDispatcher {
             }
         }
     }
-    // ─── Handler context (internal) ────────────────────────────────────
-    buildHandlerContext(envelope, log, signal) {
-        const self = this;
-        const container = this.runtime.getContainer();
-        const logger = log ?? loggerForEnvelope(this.runtime.logger, envelope);
-        const ctxSignal = signal ?? new AbortController().signal;
-        const ctx = {
-            container,
-            envelope,
-            logger,
-            signal: ctxSignal,
-            resolve(name) {
-                return container.resolve(name);
-            },
-            get requestId() {
-                return envelope.messageId;
-            },
-            async request(action, input) {
-                return self.dispatch(action, input, envelope, { signal: ctxSignal });
-            },
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            async query(
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            queryDef, input) {
-                return self.query(queryDef.name, input, envelope.tenant ?? "");
-            },
-            async send(action, input) {
-                await self.dispatch(action, input, envelope, { signal: ctxSignal });
-            },
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            async use(actor, id) {
-                return self.loadActorView(actor, id, envelope);
-            },
-            async externalCall(call, request) {
-                return self.executeExternalCall(call, request, envelope);
-            },
-        };
-        return ctx;
-    }
     // ─── Actor view (ctx.use) ──────────────────────────────────────────
+    /** Public actor-view accessor — backs the `actor(actor, id)` ctx member. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    actorView(actor, id, envelope) {
+        return this.loadActorView(actor, id, envelope);
+    }
     async loadActorView(actor, id, envelope) {
         if (!this.actors.has(actor.name)) {
-            throw new Error(`Runtime.use: actor "${actor.name}" is not registered. ` +
+            throw new Error(`ctx.actor: actor "${actor.name}" is not registered. ` +
                 `Add it to a module's manifest.actors and pass that module to createApp.`);
         }
         const loaded = await this.actorStore.load(actor.name, id, envelope.tenant ?? "");
@@ -1166,3 +1127,4 @@ export class ForgeDispatcher {
         return this.deadLetterSink;
     }
 }
+/** Local alias for the dispatch-hook ctx shape; lifted into kernel.Runtime. */

package/dist/runtime/forge-plugin.d.ts

@@ -53,6 +53,14 @@ export interface ForgePluginOptions extends ForgeDispatcherOptions {
     readonly queries?: readonly QueryDefinition<any, any, any>[];
     readonly workflows?: readonly WorkflowDefinition[];
     readonly externalCalls?: readonly ExternalCallDefinition<any, any>[];
+    /**
+     * Event names this app accepts from the bus (the inbound counterpart to
+     * `publishToBus`). When a `bus` is configured, each declared name is
+     * subscribed at boot and folded through `runtime.receive` — the same source
+     * chain + delivery path local events use. An app's own published echoes are
+     * skipped by origin.
+     */
+    readonly externalEvents?: readonly string[];
 }
 /**
  * Construct a forge plugin with custom stores, bus, and/or domain