@nwire/forge 0.12.1 → 0.13.0

package/dist/plugins/actions-chain.js

@@ -1,48 +1,86 @@
 /**
- * Action runner — handler registry + dispatch loop.
+ * Action runner — the forge command pipeline, composed onto the real handler's
+ * own hook chain. There is no parallel dispatcher and no `run`-override:
+ * `install(action)` attaches the pipeline as a high-priority `.use()` step on
+ * the action handler's hook, so dispatching it through `runtime.execute` (from
+ * a wire, queue, cron, or another handler's `ctx.request`) runs retry / DLQ /
+ * ActionDispatching / before-after / telemetry / event-publish as the outermost
+ * step. The step invokes the handler body directly in its retry loop and
+ * short-circuits (`@nwire/hooks` `compose` forbids calling `next()` twice, so
+ * retry cannot loop the chain).
  *
- * Owns the per-action retry policy, DLQ integration, and the
- * `action.dispatched` / `action.completed` / `action.failed` / `dlq.recorded`
- * telemetry. Calls `runtime.hooks.ActionDispatching` (vetoable),
- * `ActionCompleted`, and `ActionFailed` at the right transitions.
- *
- * The runner builds a handler ctx with `resolve`, `request`, `send`, and
- * `query` wired through the container. Returned events from the handler
- * flow into the `EventPublishing` chain via the injected `publishEvents`
- * callback.
+ * The handler ctx (input, envelope, request/send/emit/query/actor/…) is built
+ * by `runtime.execute`'s capability ctx — each forge concern plugin contributes
+ * its verb. This runner owns the pipeline + the per-action before/after hooks +
+ * a `dispatch` convenience; events a handler returns flow out via the injected
+ * `publishEvents` (local LocalDelivery fold + outbound sink for public).
  */
 import { serializeError } from "@nwire/app";
-import { deriveEnvelope, seedEnvelope } from "@nwire/envelope";
 import { loggerForEnvelope } from "@nwire/logger";
 import { isValidated, markValidated } from "@nwire/messages";
 import { hook } from "@nwire/hooks";
 import { buildDeadLetterEntry } from "@nwire/dead-letter";
 import { normalizeEventReturn } from "../messages/event-message.js";
 import { computeBackoff, sleep } from "../helpers/retry-helpers.js";
+/**
+ * Priority for the pipeline `.use()` step — outermost, above any user chain
+ * step and the kernel's `MIN_SAFE_INTEGER` terminal (which stays inert since
+ * the pipeline short-circuits and runs the body itself).
+ */
+const PIPELINE_PRIORITY = Number.MAX_SAFE_INTEGER;
+/**
+ * Actions are module-level singletons, but the command pipeline is
+ * app-instance-specific. Track the pipeline step currently installed on each
+ * action object so re-building an app (tests, multi-app) REPLACES it instead of
+ * stacking a second step that closes over a dead runtime/store. Last install
+ * wins — matching the previous `run`-override semantics.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const installedSteps = new WeakMap();
 export class ActionRunner {
     runtime;
     container;
     deadLetterSink;
     publishEvents;
+    // Registered actions, keyed by name. The action IS the handler.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     handlers = new Map();
     beforeHooks = new Map();
     afterHooks = new Map();
-    augmenters = [];
     constructor(runtime, container, deadLetterSink, publishEvents) {
         this.runtime = runtime;
         this.container = container;
         this.deadLetterSink = deadLetterSink;
         this.publishEvents = publishEvents;
     }
+    /**
+     * Compose the command pipeline onto an action's own hook chain. The action is
+     * already registered on the runtime (by the app); this only attaches behavior.
+     */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    register(handler) {
-        if (this.handlers.has(handler.action.name)) {
-            throw new Error(`actionsPlugin: handler for action "${handler.action.name}" already registered.`);
+    install(action) {
+        const name = action.name;
+        if (this.handlers.has(name)) {
+            throw new Error(`actionsPlugin: handler for action "${name}" already registered.`);
+        }
+        if (!action.config?.handler || typeof action.use !== "function") {
+            throw new Error(`actionsPlugin: action "${name}" has no inline handler to run. Declare it ` +
+                `with defineAction({ name, input, handler }).`);
         }
-        this.handlers.set(handler.action.name, handler);
-        this.ensureBeforeHook(handler.action.name);
-        this.ensureAfterHook(handler.action.name);
+        this.handlers.set(name, action);
+        this.ensureBeforeHook(name);
+        this.ensureAfterHook(name);
+        // Replace any pipeline a prior app instance left on this singleton action.
+        const prior = installedSteps.get(action);
+        if (prior && typeof action.off === "function")
+            action.off(prior);
+        const rawHandler = action.config.handler;
+        const step = async (ctx) => {
+            ctx.result = await this.runActionPipeline(action, rawHandler, ctx, ctx.signal ?? new AbortController().signal);
+            // No next(): the pipeline ran the body; the kernel terminal stays inert.
+        };
+        action.use(step, { priority: PIPELINE_PRIORITY, name: `forge.action:${name}` });
+        installedSteps.set(action, step);
     }
     /** Action handler names, in registration order. */
     listHandlers() {
@@ -50,7 +88,14 @@ export class ActionRunner {
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     findActionByName(name) {
-        return this.handlers.get(name)?.action;
+        return this.handlers.get(name);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findHandler(name) {
+        return this.handlers.get(name);
+    }
+    hasHandler(name) {
+        return this.handlers.has(name);
     }
     ensureBeforeHook(name) {
         let h = this.beforeHooks.get(name);
@@ -58,6 +103,7 @@ export class ActionRunner {
             return h;
         h = hook(`action.before:${name}`);
         this.beforeHooks.set(name, h);
+        this.runtime.observe(h);
         return h;
     }
     ensureAfterHook(name) {
@@ -66,23 +112,44 @@ export class ActionRunner {
             return h;
         h = hook(`action.after:${name}`);
         this.afterHooks.set(name, h);
+        this.runtime.observe(h);
         return h;
     }
-    /** Plugins can hang extra ctx members on each handler invocation. */
-    registerCtxAugmenter(fn) {
-        this.augmenters.push(fn);
-    }
+    /**
+     * Thin dispatch convenience — routes through `runtime.execute`, whose pinned
+     * core runs the action's hook chain (this pipeline). Used by `ctx.request`
+     * and any caller holding the action reference.
+     */
     async dispatch(action, input, parentEnvelope, opts) {
-        const handler = this.handlers.get(action.name);
-        if (!handler) {
+        if (!this.handlers.has(action.name)) {
             throw new Error(`actionsPlugin: no handler registered for action "${action.name}".`);
         }
+        return this.runtime.execute(action, input, {
+            parent: parentEnvelope,
+            signal: opts?.signal,
+            envelope: opts?.envelope,
+        });
+    }
+    /**
+     * The command pipeline — runs as the action's outermost hook step under
+     * `runtime.execute`: `action.dispatched` telemetry, the `ActionDispatching`
+     * veto hook, per-action before/after hooks, retry + backoff invoking the
+     * handler body, dead-letter on exhaustion, completion/failure telemetry, and
+     * event-return publishing. `ctx` is execute's capability ctx; `rawHandler` is
+     * the action's adapted `(ctx)` body.
+     */
+    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.input.parse(rawInput));
+        ctx.input = validated;
         const log = loggerForEnvelope(this.runtime.logger, envelope);
-        const signal = opts?.signal ?? new AbortController().signal;
-        const ctx = this.buildHandlerContext(envelope, signal);
+        const startedAt = performance.now();
         this.runtime.pushTelemetry({
             kind: "action.dispatched",
             action: action.name,
@@ -91,7 +158,6 @@ export class ActionRunner {
             appName,
             ts: new Date().toISOString(),
         });
-        const startedAt = performance.now();
         const dispatchResult = await this.runtime.hooks.ActionDispatching.runDetailed({
             action,
             input: validated,
@@ -115,16 +181,28 @@ export class ActionRunner {
         while (attempt < maxAttempts) {
             attempt++;
             if (attempt > 1 && signal.aborted) {
+                log.warn(`abort observed between attempts; skipping retries`, {
+                    action: action.name,
+                    attempt,
+                    maxAttempts,
+                });
                 throw lastError;
             }
             try {
                 if (attempt > 1) {
                     const delay = computeBackoff(retry, attempt - 1);
+                    log.warn(`retrying handler`, {
+                        action: action.name,
+                        attempt,
+                        maxAttempts,
+                        delayMs: delay,
+                    });
                     if (delay > 0)
                         await sleep(delay);
                 }
-                const rawResult = await handler.handler(validated, ctx);
-                const events = normalizeEventReturn(rawResult ?? null);
+                ctx.input = validated;
+                const rawResult = await rawHandler(ctx);
+                const events = normalizeEventReturn((rawResult ?? null));
                 if (events.length > 0) {
                     await this.publishEvents(events, envelope);
                 }
@@ -161,10 +239,16 @@ export class ActionRunner {
                     result: rawResult ?? undefined,
                     durationMs,
                 });
-                return rawResult;
+                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,
@@ -203,49 +287,4 @@ export class ActionRunner {
         });
         throw lastError;
     }
-    /** Build the handler ctx for one dispatch. */
-    buildHandlerContext(envelope, signal) {
-        const self = this;
-        const container = this.container;
-        const ctx = {
-            container,
-            envelope,
-            logger: loggerForEnvelope(this.runtime.logger, envelope),
-            signal,
-            resolve(name) {
-                return container.resolve(name);
-            },
-            get requestId() {
-                return envelope.messageId;
-            },
-            async request(action, input) {
-                return self.dispatch(action, input, envelope, { signal });
-            },
-            async send(action, input) {
-                await self.dispatch(action, input, envelope, { signal });
-            },
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            async query(queryDef, input) {
-                // Resolve the standalone QueryRunner when present; otherwise fall
-                // through to the bundled forge dispatcher.
-                if (container.has("forge.queryRunner")) {
-                    const runner = container.resolve("forge.queryRunner");
-                    return runner.run(queryDef.name, input, envelope.tenant ?? "");
-                }
-                const dispatcher = container.resolve("forge.dispatcher");
-                return dispatcher.query(queryDef.name, input, envelope.tenant ?? "");
-            },
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            async use() {
-                throw new Error("actionsPlugin: ctx.use requires the bundled forge dispatcher. Standalone ctx.use is not yet implemented.");
-            },
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            async externalCall() {
-                throw new Error("actionsPlugin: ctx.externalCall requires the bundled forge dispatcher.");
-            },
-        };
-        for (const augment of this.augmenters)
-            augment(ctx, envelope);
-        return ctx;
-    }
 }

package/dist/plugins/actions-plugin.d.ts

@@ -1,40 +1,43 @@
 /**
- * `actionsPlugin` — standalone forge action concern.
+ * `actionsPlugin` — the forge command concern as a runtime-native plugin.
  *
  *   import { createApp } from "@nwire/app";
- *   import {
- *     actionsPlugin,
- *     idempotencyPlugin,
- *     forgePlugin,
- *   } from "@nwire/forge";
+ *   import { actionsPlugin, idempotencyPlugin } from "@nwire/forge";
  *
  *   const app = createApp({
  *     appName: "orders",
- *     plugins: [
- *       forgePlugin,
- *       actionsPlugin([placeOrderHandler, sendReceiptHandler]),
- *     ],
+ *     handlers: [placeOrder, sendReceipt],          // app registers handlers
+ *     plugins: [idempotencyPlugin(), actionsPlugin()],
  *   });
  *
- * Owns:
- *   - the action handler registry through `ActionRunner`
- *   - the `forge.deadLetterSink` container binding (overridable)
- *   - the `forge.actionRunner` container binding so other plugins can
- *     resolve it (queue-worker, http adapter, please CLI, etc.)
- *   - the per-action retry loop, DLQ recording, and action.dispatched /
- *     action.completed / action.failed / dlq.recorded telemetry
+ * It owns no handler list. At setup it scans the runtime's registered handlers
+ * for `config.kind === "action"` and composes the command pipeline onto each
+ * (retry / DLQ / before-after / telemetry / event-publish) via the action's own
+ * hook chain. Registration is the app's job (`createApp({ handlers })`); forge
+ * only adds behavior keyed on `kind`.
  *
- * Handlers returning events feed the `EventPublishing` chain so the
- * actors / projections / workflows / bus steps all run in order. The
- * standalone plugin is equivalent to forgePlugin's bundled handler path.
+ * Owns:
+ *   - the `ActionRunner` (pipeline + per-action before/after hooks + dispatch
+ *     convenience) and the `forge.actionRunner` / `forge.deadLetterSink` binds.
+ *   - the event-publish path (`forge.publishEvents` binding): local
+ *     `LocalDelivery` fold + outbound sink/bus for public events.
+ *   - the forge handler-ctx verbs `request` / `send` / `emit` plus the ambient
+ *     `container` / `requestId` / `logger`, contributed as a capability.
  */
 import type { PluginDefinition } from "@nwire/app";
 import { type DeadLetterSink } from "@nwire/dead-letter";
-import type { HandlerDefinition } from "../primitives/define-handler.js";
+import type { EventBus } from "@nwire/bus";
 export declare const FORGE_ACTION_RUNNER_BINDING: "forge.actionRunner";
 export declare const FORGE_DEAD_LETTER_SINK_BINDING: "forge.deadLetterSink";
+/** Shared event-publish fn — actor views and workflow effects resolve it too. */
+export declare const FORGE_PUBLISH_BINDING: "forge.publishEvents";
+/** Names of events declared `.public()` — consulted by the outbound drain. */
+export declare const FORGE_PUBLIC_EVENTS_BINDING: "forge.publicEvents";
 export interface ActionsPluginOptions {
-    /** Override the dead-letter sink. Defaults to `InMemoryDeadLetterSink`. */
     readonly deadLetterSink?: DeadLetterSink;
+    /** Cross-service bus for public events. */
+    readonly bus?: EventBus;
+    /** Drain public events to the bus. Default false. */
+    readonly publishToBus?: boolean;
 }
-export declare function actionsPlugin(handlers: readonly HandlerDefinition<any>[], opts?: ActionsPluginOptions): PluginDefinition;
+export declare function actionsPlugin(opts?: ActionsPluginOptions): PluginDefinition;

package/dist/plugins/actions-plugin.js

@@ -1,76 +1,154 @@
 /**
- * `actionsPlugin` — standalone forge action concern.
+ * `actionsPlugin` — the forge command concern as a runtime-native plugin.
  *
  *   import { createApp } from "@nwire/app";
- *   import {
- *     actionsPlugin,
- *     idempotencyPlugin,
- *     forgePlugin,
- *   } from "@nwire/forge";
+ *   import { actionsPlugin, idempotencyPlugin } from "@nwire/forge";
  *
  *   const app = createApp({
  *     appName: "orders",
- *     plugins: [
- *       forgePlugin,
- *       actionsPlugin([placeOrderHandler, sendReceiptHandler]),
- *     ],
+ *     handlers: [placeOrder, sendReceipt],          // app registers handlers
+ *     plugins: [idempotencyPlugin(), actionsPlugin()],
  *   });
  *
- * Owns:
- *   - the action handler registry through `ActionRunner`
- *   - the `forge.deadLetterSink` container binding (overridable)
- *   - the `forge.actionRunner` container binding so other plugins can
- *     resolve it (queue-worker, http adapter, please CLI, etc.)
- *   - the per-action retry loop, DLQ recording, and action.dispatched /
- *     action.completed / action.failed / dlq.recorded telemetry
+ * It owns no handler list. At setup it scans the runtime's registered handlers
+ * for `config.kind === "action"` and composes the command pipeline onto each
+ * (retry / DLQ / before-after / telemetry / event-publish) via the action's own
+ * hook chain. Registration is the app's job (`createApp({ handlers })`); forge
+ * only adds behavior keyed on `kind`.
  *
- * Handlers returning events feed the `EventPublishing` chain so the
- * actors / projections / workflows / bus steps all run in order. The
- * standalone plugin is equivalent to forgePlugin's bundled handler path.
+ * Owns:
+ *   - the `ActionRunner` (pipeline + per-action before/after hooks + dispatch
+ *     convenience) and the `forge.actionRunner` / `forge.deadLetterSink` binds.
+ *   - the event-publish path (`forge.publishEvents` binding): local
+ *     `LocalDelivery` fold + outbound sink/bus for public events.
+ *   - the forge handler-ctx verbs `request` / `send` / `emit` plus the ambient
+ *     `container` / `requestId` / `logger`, contributed as a capability.
  */
+import { deriveEnvelope } from "@nwire/envelope";
+import { loggerForEnvelope } from "@nwire/logger";
 import { InMemoryDeadLetterSink } from "@nwire/dead-letter";
+import { eventFactory } from "../messages/event-message.js";
+import { forgeFrameworkSlots } from "../framework-events.js";
 import { ActionRunner } from "./actions-chain.js";
 export const FORGE_ACTION_RUNNER_BINDING = "forge.actionRunner";
 export const FORGE_DEAD_LETTER_SINK_BINDING = "forge.deadLetterSink";
-export function actionsPlugin(
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-handlers, opts = {}) {
+/** Shared event-publish fn — actor views and workflow effects resolve it too. */
+export const FORGE_PUBLISH_BINDING = "forge.publishEvents";
+/** Names of events declared `.public()` — consulted by the outbound drain. */
+export const FORGE_PUBLIC_EVENTS_BINDING = "forge.publicEvents";
+/** Is this registered handler a forge action? */
+function isActionHandler(h) {
+    return typeof h === "function" && h.config?.kind === "action";
+}
+export function actionsPlugin(opts = {}) {
     return {
         name: "forge.actions",
         register({ bind, container }) {
-            // Don't shadow a sink that dlqPlugin already bound. The option
-            // override still wins when explicitly passed.
             if (opts.deadLetterSink) {
                 bind(FORGE_DEAD_LETTER_SINK_BINDING, () => opts.deadLetterSink);
-                return;
             }
-            if (container.has(FORGE_DEAD_LETTER_SINK_BINDING))
-                return;
-            const sink = new InMemoryDeadLetterSink();
-            bind(FORGE_DEAD_LETTER_SINK_BINDING, () => sink);
+            else if (!container.has(FORGE_DEAD_LETTER_SINK_BINDING)) {
+                const sink = new InMemoryDeadLetterSink();
+                bind(FORGE_DEAD_LETTER_SINK_BINDING, () => sink);
+            }
+            // Shared public-event registry (other plugins may add to it).
+            if (!container.has(FORGE_PUBLIC_EVENTS_BINDING)) {
+                const publicEvents = new Set();
+                bind(FORGE_PUBLIC_EVENTS_BINDING, () => publicEvents);
+            }
         },
-        setup({ runtime, container }) {
+        setup({ runtime, container, bind }) {
+            // Materialise forge's Action* / Event* hook slots — apps without forge
+            // don't carry these. The action pipeline (and the event fold steps)
+            // read them off `runtime.hooks`, so they must exist before any dispatch.
+            for (const slot of forgeFrameworkSlots)
+                runtime.defineHook(slot);
             const sink = container.resolve(FORGE_DEAD_LETTER_SINK_BINDING);
-            // Returned events from a handler flow into the EventPublishing chain
-            // — each event becomes a payload that walks the priority steps
-            // (idempotency → actors → projections → workflows → bus).
-            const publishEvents = async (events, envelope) => {
+            const publicEvents = container.resolve(FORGE_PUBLIC_EVENTS_BINDING);
+            const appName = runtime.appName;
+            // The one event-publish path: local LocalDelivery fold, then outbound
+            // sink/bus for public, non-deduped events.
+            const publishEvents = async (events, parentEnvelope) => {
                 for (let i = 0; i < events.length; i++) {
                     const event = events[i];
-                    const dedupKey = events.length === 1 ? envelope.messageId : `${envelope.messageId}#${i}`;
-                    const payload = {
+                    const dedupKey = events.length === 1 ? parentEnvelope.messageId : `${parentEnvelope.messageId}#${i}`;
+                    const childEnvelope = deriveEnvelope(parentEnvelope);
+                    const { deduped } = await runtime.deliver(event.eventName, event.payload, childEnvelope, dedupKey);
+                    if (deduped) {
+                        runtime.pushTelemetry({
+                            kind: "event.deduped",
+                            event,
+                            envelope: childEnvelope,
+                            source: "in-process",
+                            appName,
+                            ts: new Date().toISOString(),
+                        });
+                        continue;
+                    }
+                    if (publicEvents.has(event.eventName)) {
+                        if (opts.publishToBus && opts.bus) {
+                            await opts.bus.publish({
+                                eventName: event.eventName,
+                                payload: event.payload,
+                                envelope: childEnvelope,
+                                origin: appName,
+                            });
+                        }
+                        await runtime.sinkDrain({ name: event.eventName }, event.payload, childEnvelope);
+                    }
+                    runtime.pushTelemetry({
+                        kind: "event.published",
                         event,
-                        envelope,
-                        dedupKey,
-                        deduped: false,
-                    };
-                    await runtime.hooks.EventPublishing.run(payload);
+                        envelope: childEnvelope,
+                        source: "in-process",
+                        appName,
+                        ts: new Date().toISOString(),
+                    });
                 }
             };
+            bind(FORGE_PUBLISH_BINDING, () => publishEvents);
             const runner = new ActionRunner(runtime, container, sink, publishEvents);
-            for (const handler of handlers)
-                runner.register(handler);
+            // Scan the runtime's registered handlers — the app owns registration;
+            // forge composes the pipeline onto every action-kind handler.
+            for (const name of runtime.listHandlers()) {
+                const handler = runtime.getHandler(name);
+                if (!isActionHandler(handler))
+                    continue;
+                runner.install(handler);
+                const emits = handler.emits;
+                if (emits)
+                    for (const ev of emits)
+                        if (ev.$public === true)
+                            publicEvents.add(ev.name);
+            }
             container.register(FORGE_ACTION_RUNNER_BINDING, runner);
+            // Forge handler-ctx verbs contributed per dispatch. `request` awaits the
+            // result through the one execute path; `send` is fire-and-forget via
+            // enqueue (returns a MessageRef); `emit` announces a fact via the shared
+            // publish. Ambient `container` / `requestId` / `logger` ride along.
+            // Ambient ctx — every dispatch (universal). What the verb closes over is
+            // only the envelope/container, so it's not kind-specific.
+            runtime.add({
+                name: "forge.ambient-ctx",
+                provideCtx: ({ envelope, container: c }) => ({
+                    container: c,
+                    requestId: envelope.messageId,
+                    logger: loggerForEnvelope(runtime.logger, envelope),
+                }),
+            });
+            // Dispatch verbs — kind-scoped to the write/orchestrate side (actions,
+            // plain handlers/resolvers, commands), so a read-only `query` body never
+            // structurally carries `request`/`send`/`emit`. (Workflow/actor reactions
+            // build their own send/publish from their router ctx.)
+            runtime.add({
+                name: "forge.action-ctx",
+                kinds: ["handler", "action", "command"],
+                provideCtx: ({ envelope, signal }) => ({
+                    request: (action, input) => runtime.execute(action, input, { parent: envelope, signal }),
+                    send: (action, input) => runtime.enqueue(action, input, { parent: envelope, signal }),
+                    emit: (event, payload) => publishEvents([eventFactory(event)(payload)], envelope),
+                }),
+            });
         },
     };
 }

package/dist/plugins/actors-chain.d.ts

@@ -1,5 +1,5 @@
 /**
- * Actor chain runner — the EventPublishing step that applies an event to
+ * Actor chain runner — the LocalDelivery step that applies an event to
  * every registered actor type whose reactions match.
  *
  * Self-contained: takes its dependencies as constructor arguments. Both
@@ -41,7 +41,7 @@ export declare class ActorChainRunner {
     ensureTransitionHook(actorName: string): Hook<ActorTransitionHookCtx>;
     /**
      * Apply one event to every actor type whose reactions match. Called
-     * by the EventPublishing step at priority 800.
+     * by the LocalDelivery step at priority 800.
      */
     apply(event: EventMessage, envelope: MessageEnvelope): Promise<void>;
     private extractKey;
@@ -49,4 +49,11 @@ export declare class ActorChainRunner {
     private applyLocked;
     private computeTimersForState;
     private envelopeLogger;
+    /**
+     * Load an actor instance as a method-bound view — backs `ctx.actor`. Methods
+     * are pure (state-first or closure-bound); events a method records are
+     * published via the injected `publish` (the shared event-publish path) so a
+     * view method's facts ride the same LocalDelivery fold + outbound drain.
+     */
+    view<TActor extends ActorDefinition>(actor: TActor, id: string, envelope: MessageEnvelope, publish: (events: readonly EventMessage[], envelope: MessageEnvelope) => Promise<void>): Promise<any>;
 }