@nwire/forge 0.12.1 → 0.13.0

package/dist/plugins/actors-chain.js

@@ -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
@@ -52,7 +52,7 @@ export class ActorChainRunner {
     }
     /**
      * 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.
      */
     async apply(event, envelope) {
         const tenant = envelope.tenant ?? "";
@@ -201,4 +201,64 @@ export class ActorChainRunner {
     envelopeLogger(envelope) {
         return loggerForEnvelope(this.runtime.logger, envelope);
     }
+    /**
+     * 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.
+     */
+    async view(actor, id, envelope, publish) {
+        if (!this.actors.has(actor.name)) {
+            throw new Error(`ctx.actor: actor "${actor.name}" is not registered. Add it to actorsPlugin([...]).`);
+        }
+        const loaded = await this.store.load(actor.name, id, envelope.tenant ?? "");
+        const instance = loaded ?? {
+            name: actor.name,
+            key: id,
+            state: actor.initial,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            data: {},
+            version: 0,
+            timers: [],
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const view = {
+            state: instance.data,
+            key: instance.key,
+            stateName: instance.state,
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const closureBinder = actor.closureBinder;
+        if (closureBinder) {
+            const bound = closureBinder(instance.data, instance.key);
+            for (const methodName of Object.keys(bound.methods)) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                view[methodName] = async (...args) => {
+                    const fresh = await this.store.load(actor.name, id, envelope.tenant ?? "");
+                    const liveData = fresh?.data ?? instance.data;
+                    const localBound = closureBinder(liveData, instance.key);
+                    const localFn = localBound.methods[methodName];
+                    if (!localFn)
+                        throw new Error(`Actor "${actor.name}" has no method "${methodName}".`);
+                    const result = localFn(...args);
+                    if (localBound.recorded.length > 0) {
+                        const messages = localBound.recorded.map((r) => ({
+                            eventName: r.eventName,
+                            payload: r.payload,
+                        }));
+                        await publish(messages, envelope);
+                    }
+                    return result;
+                };
+            }
+            return view;
+        }
+        const methods = actor.methods ?? {};
+        for (const [methodName, fn] of Object.entries(methods)) {
+            const method = fn;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            view[methodName] = (...args) => method(instance.data, ...args);
+        }
+        return view;
+    }
 }

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

@@ -15,7 +15,7 @@
  * Owns:
  *   - the `forge.actorStore` container binding
  *   - the actor types registry (private to the plugin's `ActorChainRunner`)
- *   - the `forge.publish.actors` step on the EventPublishing chain
+ *   - the `forge.publish.actors` step on the LocalDelivery chain
  *     (priority 800 — between idempotency and projections)
  *   - the `forge.actorChain` container binding so other plugins can
  *     resolve the runner (workflow timer scheduler, ctx.use binding, …)

package/dist/plugins/actors-plugin.js

@@ -15,7 +15,7 @@
  * Owns:
  *   - the `forge.actorStore` container binding
  *   - the actor types registry (private to the plugin's `ActorChainRunner`)
- *   - the `forge.publish.actors` step on the EventPublishing chain
+ *   - the `forge.publish.actors` step on the LocalDelivery chain
  *     (priority 800 — between idempotency and projections)
  *   - the `forge.actorChain` container binding so other plugins can
  *     resolve the runner (workflow timer scheduler, ctx.use binding, …)
@@ -27,6 +27,7 @@
 import { InMemoryActorStore } from "../stores/actor-store.js";
 import { EVENT_PUBLISHING_PRIORITIES } from "../framework-events.js";
 import { ActorChainRunner } from "./actors-chain.js";
+import { FORGE_PUBLISH_BINDING } from "./actions-plugin.js";
 export const FORGE_ACTOR_CHAIN_BINDING = "forge.actorChain";
 export const FORGE_ACTOR_STORE_BINDING = "forge.actorStore";
 export function actorsPlugin(actorTypes, opts = {}) {
@@ -36,27 +37,36 @@ export function actorsPlugin(actorTypes, opts = {}) {
             const store = opts.actorStore ?? new InMemoryActorStore();
             bind(FORGE_ACTOR_STORE_BINDING, () => store);
         },
-        setup({ runtime, container, on }) {
+        setup({ runtime, container }) {
             const store = container.resolve(FORGE_ACTOR_STORE_BINDING);
             const chain = new ActorChainRunner(runtime, store);
             for (const actor of actorTypes)
                 chain.register(actor);
             container.register(FORGE_ACTOR_CHAIN_BINDING, chain);
-            runtime.hooks.EventPublishing.use(async (payload, next) => {
-                await chain.apply(payload.event, payload.envelope);
+            runtime.hooks.LocalDelivery.use(async (payload, next) => {
+                await chain.apply({ eventName: payload.eventName, payload: payload.payload }, payload.envelope);
                 await next();
             }, { name: "forge.publish.actors", priority: EVENT_PUBLISHING_PRIORITIES.actors });
-            // Diagnostic — warn if forgePlugin's bundled mode also attached an
-            // actors step. Both would run and produce duplicate work.
-            on("AppReady", () => {
-                const hookChain = runtime.hooks.EventPublishing;
-                const steps = (hookChain.chain ?? []).filter((s) => s.name === "forge.publish.actors");
-                if (steps.length > 1) {
-                    // eslint-disable-next-line no-console
-                    console.warn(`actorsPlugin: detected ${steps.length} "forge.publish.actors" steps on the EventPublishing chain. ` +
-                        `Install either actorsPlugin OR forgePlugin's options.actors path, not both.`);
-                }
+            // Contribute the `ctx.actor` verb — a method-bound actor view. Events a
+            // view method records publish through the shared `forge.publishEvents`
+            // path (bound by actionsPlugin); falls back to local fold if absent.
+            runtime.add({
+                name: "forge.actor-ctx",
+                provideCtx: ({ envelope, container: c }) => ({
+                    actor: (actor, id) => chain.view(actor, id, envelope, resolvePublish(c, runtime)),
+                }),
             });
         },
     };
 }
+/** Resolve the shared event-publish fn, or fall back to local LocalDelivery. */
+function resolvePublish(container, runtime) {
+    if (container.has(FORGE_PUBLISH_BINDING)) {
+        return container.resolve(FORGE_PUBLISH_BINDING);
+    }
+    return async (events, envelope) => {
+        for (const e of events) {
+            await runtime.deliver(e.eventName, e.payload, envelope, envelope.messageId);
+        }
+    };
+}

package/dist/plugins/external-calls-plugin.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `externalCallsPlugin` — the forge external-call concern as a plugin.
+ *
+ * Owns the external-call registry + executor table and contributes the
+ * `ctx.externalCall` verb. Wires/adapters register the real transport via
+ * the `forge.externalCalls` runner (`registerExecutor`). The runner applies
+ * the declared idempotency key + retry policy and emits
+ * `external.call.started / .completed / .failed` telemetry.
+ */
+import type { PluginDefinition } from "@nwire/app";
+import { type Runtime } from "@nwire/app";
+import type { MessageEnvelope } from "@nwire/envelope";
+import type { ZodTypeAny } from "@nwire/messages";
+import type { z } from "zod";
+import type { ExternalCallDefinition, ExternalCallExecutor } from "../primitives/define-external-call.js";
+export declare const FORGE_EXTERNAL_CALLS_BINDING: "forge.externalCalls";
+export declare class ExternalCallRunner {
+    private readonly runtime;
+    readonly calls: Map<string, ExternalCallDefinition<any, any>>;
+    readonly executors: Map<string, ExternalCallExecutor<any, any>>;
+    constructor(runtime: Runtime);
+    register(def: ExternalCallDefinition<any, any>): void;
+    registerExecutor<TReq extends ZodTypeAny, TRes extends ZodTypeAny>(def: ExternalCallDefinition<TReq, TRes>, executor: ExternalCallExecutor<TReq, TRes>): void;
+    listExternalCalls(): readonly string[];
+    getExternalCall(name: string): ExternalCallDefinition<any, any> | undefined;
+    execute<TReq extends ZodTypeAny, TRes extends ZodTypeAny>(def: ExternalCallDefinition<TReq, TRes>, request: z.output<TReq>, envelope?: MessageEnvelope): Promise<z.output<TRes>>;
+}
+export declare function externalCallsPlugin(calls?: readonly ExternalCallDefinition<any, any>[]): PluginDefinition;

package/dist/plugins/external-calls-plugin.js

@@ -0,0 +1,136 @@
+/**
+ * `externalCallsPlugin` — the forge external-call concern as a plugin.
+ *
+ * Owns the external-call registry + executor table and contributes the
+ * `ctx.externalCall` verb. Wires/adapters register the real transport via
+ * the `forge.externalCalls` runner (`registerExecutor`). The runner applies
+ * the declared idempotency key + retry policy and emits
+ * `external.call.started / .completed / .failed` telemetry.
+ */
+import { serializeError } from "@nwire/app";
+import { computeBackoff, sleep } from "../helpers/retry-helpers.js";
+export const FORGE_EXTERNAL_CALLS_BINDING = "forge.externalCalls";
+export class ExternalCallRunner {
+    runtime;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    calls = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    executors = new Map();
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    register(def) {
+        if (this.calls.has(def.name)) {
+            throw new Error(`externalCallsPlugin: external call "${def.name}" already registered.`);
+        }
+        this.calls.set(def.name, def);
+    }
+    registerExecutor(def, executor) {
+        this.executors.set(def.name, executor);
+    }
+    listExternalCalls() {
+        return [...this.calls.keys()];
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getExternalCall(name) {
+        return this.calls.get(name);
+    }
+    async execute(def, request, envelope) {
+        const validated = def.request.parse(request);
+        const executor = this.executors.get(def.name);
+        const idempotencyKey = def.idempotencyKey?.(validated);
+        const target = `${def.target.provider}/${def.target.endpoint}`;
+        const appName = this.runtime.appName;
+        if (!executor) {
+            const err = new Error(`ctx.externalCall: no executor registered for "${def.name}". ` +
+                `Wires/adapters must call the forge.externalCalls runner's registerExecutor() at boot.`);
+            this.runtime.pushTelemetry({
+                kind: "external.call.failed",
+                call: def.name,
+                target,
+                attempt: 1,
+                willRetry: false,
+                error: serializeError(err),
+                envelope,
+                appName,
+                ts: new Date().toISOString(),
+            });
+            throw err;
+        }
+        const retry = def.retry;
+        const maxAttempts = 1 + (retry?.max ?? 0);
+        let attempt = 0;
+        let lastError;
+        while (attempt < maxAttempts) {
+            attempt++;
+            this.runtime.pushTelemetry({
+                kind: "external.call.started",
+                call: def.name,
+                target,
+                idempotencyKey,
+                envelope,
+                appName,
+                ts: new Date().toISOString(),
+            });
+            const t0 = performance.now();
+            try {
+                if (attempt > 1) {
+                    const delay = computeBackoff(retry, attempt - 1);
+                    if (delay > 0)
+                        await sleep(delay);
+                }
+                const raw = await executor(validated, { idempotencyKey, attempt });
+                const response = def.response ? def.response.parse(raw) : raw;
+                this.runtime.pushTelemetry({
+                    kind: "external.call.completed",
+                    call: def.name,
+                    target,
+                    durationMs: performance.now() - t0,
+                    idempotencyKey,
+                    envelope,
+                    appName,
+                    ts: new Date().toISOString(),
+                });
+                return response;
+            }
+            catch (err) {
+                lastError = err;
+                this.runtime.pushTelemetry({
+                    kind: "external.call.failed",
+                    call: def.name,
+                    target,
+                    attempt,
+                    willRetry: attempt < maxAttempts,
+                    error: serializeError(err),
+                    envelope,
+                    appName,
+                    ts: new Date().toISOString(),
+                });
+            }
+        }
+        throw lastError;
+    }
+}
+export function externalCallsPlugin(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+calls = []) {
+    return {
+        name: "forge.external-calls",
+        setup({ runtime, container, bind }) {
+            const runner = new ExternalCallRunner(runtime);
+            for (const def of calls)
+                runner.register(def);
+            bind(FORGE_EXTERNAL_CALLS_BINDING, () => runner);
+            runtime.add({
+                name: "forge.external-call-ctx",
+                provideCtx: ({ envelope, container: c }) => ({
+                    externalCall: (def, request) => c
+                        .resolve(FORGE_EXTERNAL_CALLS_BINDING)
+                        .execute(def, request, envelope),
+                }),
+            });
+            void container;
+        },
+    };
+}

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

@@ -1,6 +1,6 @@
 /**
  * `idempotencyPlugin` — owns the per-event dedup gate at the head of
- * the EventPublishing chain.
+ * the LocalDelivery chain.
  *
  *   import { createApp } from "@nwire/app";
  *   import { idempotencyPlugin, forgePlugin } from "@nwire/forge";
@@ -19,10 +19,24 @@
  * runs; warn at AppReady.
  */
 import type { PluginDefinition } from "@nwire/app";
+import type { EventBus } from "@nwire/bus";
 import { type IdempotencyStore } from "../stores/idempotency-store.js";
 export declare const FORGE_IDEMPOTENCY_STORE_BINDING: "forge.idempotencyStore";
 export interface IdempotencyPluginOptions {
     /** Override the idempotency store. Defaults to `InMemoryIdempotencyStore`. */
     readonly idempotencyStore?: IdempotencyStore;
+    /**
+     * Event names accepted from the bus/source chain. Each is folded through the
+     * one LocalDelivery path (deduped by the inbound messageId) when it arrives
+     * via `runtime.receive({ kind: "event" })`.
+     */
+    readonly externalEvents?: readonly string[];
+    /**
+     * Cross-service bus. When set, each declared external event is subscribed at
+     * boot and folded through `runtime.receive` — the inbound counterpart to
+     * `actionsPlugin`'s `publishToBus`. An app's own published echoes are skipped
+     * by origin.
+     */
+    readonly bus?: EventBus;
 }
 export declare function idempotencyPlugin(opts?: IdempotencyPluginOptions): PluginDefinition;

package/dist/plugins/idempotency-plugin.js

@@ -1,6 +1,6 @@
 /**
  * `idempotencyPlugin` — owns the per-event dedup gate at the head of
- * the EventPublishing chain.
+ * the LocalDelivery chain.
  *
  *   import { createApp } from "@nwire/app";
  *   import { idempotencyPlugin, forgePlugin } from "@nwire/forge";
@@ -18,19 +18,38 @@
  * If `forgePlugin`'s bundled mode is also installed, a duplicate step
  * runs; warn at AppReady.
  */
+import { seedEnvelope } from "@nwire/envelope";
 import { InMemoryIdempotencyStore } from "../stores/idempotency-store.js";
 import { EVENT_PUBLISHING_PRIORITIES } from "../framework-events.js";
 export const FORGE_IDEMPOTENCY_STORE_BINDING = "forge.idempotencyStore";
 export function idempotencyPlugin(opts = {}) {
+    const externalEventNames = new Set(opts.externalEvents ?? []);
     return {
         name: "forge.idempotency",
         register({ bind }) {
             const store = opts.idempotencyStore ?? new InMemoryIdempotencyStore();
             bind(FORGE_IDEMPOTENCY_STORE_BINDING, () => store);
         },
-        setup({ runtime, container, on }) {
+        setup({ runtime, container, boot }) {
             const store = container.resolve(FORGE_IDEMPOTENCY_STORE_BINDING);
-            runtime.hooks.EventPublishing.use(async (payload, next) => {
+            // Bus inbound — subscribe each declared external event and fold it
+            // through `runtime.receive`; the external-delivery source stage below
+            // lands it on the one delivery path. Skips this app's own echoes by
+            // origin. The symmetric counterpart to outbound `publishToBus`.
+            // Deferred to boot so the wiring lands once the app is starting.
+            if (opts.bus) {
+                const bus = opts.bus;
+                boot(() => {
+                    for (const eventName of externalEventNames) {
+                        bus.subscribe(eventName, async (msg) => {
+                            if (msg.origin === runtime.appName)
+                                return;
+                            await runtime.receive({ kind: "event", name: msg.eventName, input: msg.payload }, { envelope: msg.envelope });
+                        });
+                    }
+                });
+            }
+            runtime.hooks.LocalDelivery.use(async (payload, next) => {
                 // Atomic check-and-record so concurrent publishes with the
                 // same dedupKey see exactly one winner.
                 const isNew = await store.recordIfNew(payload.dedupKey);
@@ -43,14 +62,40 @@ export function idempotencyPlugin(opts = {}) {
                 name: "forge.publish.idempotency",
                 priority: EVENT_PUBLISHING_PRIORITIES.idempotency,
             });
-            on("AppReady", () => {
-                const hookChain = runtime.hooks.EventPublishing;
-                const steps = (hookChain.chain ?? []).filter((s) => s.name === "forge.publish.idempotency");
-                if (steps.length > 1) {
-                    // eslint-disable-next-line no-console
-                    console.warn(`idempotencyPlugin: detected ${steps.length} "forge.publish.idempotency" steps on the EventPublishing chain. ` +
-                        `Install either idempotencyPlugin OR forgePlugin's bundled idempotency path, not both.`);
-                }
+            // External / bus-inbound events ride the ONE delivery path. This source
+            // stage folds a declared external event through `runtime.deliver` (same
+            // LocalDelivery fold local emit uses), deduped by the inbound messageId,
+            // then stops so the terminal router doesn't re-handle it.
+            runtime.source({
+                name: "forge.external-delivery",
+                position: "terminal",
+                run: async (ctx) => {
+                    const msg = ctx.message;
+                    if (!msg || msg.kind !== "event")
+                        return;
+                    if (!externalEventNames.has(msg.name))
+                        return;
+                    const seed = ctx.envelope;
+                    const envelope = seed?.messageId
+                        ? seed
+                        : seedEnvelope({
+                            tenant: ctx.envelope.tenant,
+                            userId: ctx.envelope.userId,
+                            user: ctx.envelope.user,
+                            correlationId: ctx.envelope.correlationId,
+                            causationId: ctx.envelope.causationId,
+                        });
+                    const { deduped } = await runtime.deliver(msg.name, msg.input, envelope, envelope.messageId);
+                    runtime.pushTelemetry({
+                        kind: deduped ? "event.deduped" : "event.published",
+                        event: { eventName: msg.name, payload: msg.input },
+                        envelope,
+                        source: "external",
+                        appName: runtime.appName,
+                        ts: new Date().toISOString(),
+                    });
+                    return { continue: false };
+                },
             });
         },
     };

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

@@ -1,5 +1,5 @@
 /**
- * Projection chain runner — the EventPublishing step that folds an
+ * Projection chain runner — the LocalDelivery step that folds an
  * event into every registered projection that listens for it.
  *
  * Self-contained: takes its dependencies as constructor arguments. Both
@@ -11,7 +11,7 @@
  *   1. Look up projections that listen for `event.eventName`.
  *   2. For each, load the per-tenant state, run the reducer, save.
  *   3. Push `projection.folded` telemetry on success or `projection.failed`
- *      on a reducer throw (then re-raise so the EventPublishing chain
+ *      on a reducer throw (then re-raise so the LocalDelivery chain
  *      surfaces the failure).
  */
 import { type MessageEnvelope } from "@nwire/envelope";

package/dist/plugins/projections-chain.js

@@ -1,5 +1,5 @@
 /**
- * Projection chain runner — the EventPublishing step that folds an
+ * Projection chain runner — the LocalDelivery step that folds an
  * event into every registered projection that listens for it.
  *
  * Self-contained: takes its dependencies as constructor arguments. Both
@@ -11,7 +11,7 @@
  *   1. Look up projections that listen for `event.eventName`.
  *   2. For each, load the per-tenant state, run the reducer, save.
  *   3. Push `projection.folded` telemetry on success or `projection.failed`
- *      on a reducer throw (then re-raise so the EventPublishing chain
+ *      on a reducer throw (then re-raise so the LocalDelivery chain
  *      surfaces the failure).
  */
 import { serializeError } from "@nwire/app";

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

@@ -15,7 +15,7 @@
  * Owns:
  *   - the `forge.projectionStore` container binding
  *   - the projection registry (private to the plugin's `ProjectionChainRunner`)
- *   - the `forge.publish.projections` step on the EventPublishing chain
+ *   - the `forge.publish.projections` step on the LocalDelivery chain
  *     (priority 600 — between actors and workflows)
  *   - the `forge.projectionChain` container binding so queriesPlugin (and
  *     other consumers) can resolve the runner

package/dist/plugins/projections-plugin.js

@@ -15,7 +15,7 @@
  * Owns:
  *   - the `forge.projectionStore` container binding
  *   - the projection registry (private to the plugin's `ProjectionChainRunner`)
- *   - the `forge.publish.projections` step on the EventPublishing chain
+ *   - the `forge.publish.projections` step on the LocalDelivery chain
  *     (priority 600 — between actors and workflows)
  *   - the `forge.projectionChain` container binding so queriesPlugin (and
  *     other consumers) can resolve the runner
@@ -38,26 +38,17 @@ projections, opts = {}) {
             const store = opts.projectionStore ?? new InMemoryProjectionStore();
             bind(FORGE_PROJECTION_STORE_BINDING, () => store);
         },
-        setup({ runtime, container, on }) {
+        setup({ runtime, container }) {
             const store = container.resolve(FORGE_PROJECTION_STORE_BINDING);
             const chain = new ProjectionChainRunner(runtime, store);
             for (const projection of projections) {
                 chain.register(projection);
             }
             container.register(FORGE_PROJECTION_CHAIN_BINDING, chain);
-            runtime.hooks.EventPublishing.use(async (payload, next) => {
-                await chain.apply(payload.event, payload.envelope);
+            runtime.hooks.LocalDelivery.use(async (payload, next) => {
+                await chain.apply({ eventName: payload.eventName, payload: payload.payload }, payload.envelope);
                 await next();
             }, { name: "forge.publish.projections", priority: EVENT_PUBLISHING_PRIORITIES.projections });
-            on("AppReady", () => {
-                const hookChain = runtime.hooks.EventPublishing;
-                const steps = (hookChain.chain ?? []).filter((s) => s.name === "forge.publish.projections");
-                if (steps.length > 1) {
-                    // eslint-disable-next-line no-console
-                    console.warn(`projectionsPlugin: detected ${steps.length} "forge.publish.projections" steps on the EventPublishing chain. ` +
-                        `Install either projectionsPlugin OR forgePlugin's options.projections path, not both.`);
-                }
-            });
         },
     };
 }

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

@@ -1,9 +1,9 @@
 /**
- * Query runner — the read-side equivalent of the EventPublishing chain.
+ * Query runner — the read-side equivalent of the LocalDelivery chain.
  *
  * Queries don't participate in the publish chain; they execute on
  * demand against the projection store (`projection.execute(state, input)`)
- * or via a handler closure (`query.handler(input, ctx)`). The runner is
+ * or via a handler closure (`query.handler(ctx)`). The runner is
  * a thin holder around the registry + execution logic that both the
  * standalone `queriesPlugin` and the bundled `ForgeDispatcher` use.
  *
@@ -18,6 +18,7 @@
  */
 import { type Runtime } from "@nwire/app";
 import type { Container } from "@nwire/container";
+import type { MessageEnvelope } from "@nwire/envelope";
 import type { QueryDefinition } from "../primitives/define-query.js";
 import type { ProjectionStore } from "../stores/projection-store.js";
 export declare class QueryRunner {
@@ -29,5 +30,5 @@ export declare class QueryRunner {
     register(query: QueryDefinition<any, any, any>): void;
     /** All registered query names, in registration order. */
     listQueries(): readonly string[];
-    run<TResult = unknown>(queryName: string, input: unknown, tenant?: string): Promise<TResult>;
+    run<TResult = unknown>(queryName: string, input: unknown, tenant?: string, envelope?: MessageEnvelope): Promise<TResult>;
 }

package/dist/plugins/queries-chain.js

@@ -1,9 +1,9 @@
 /**
- * Query runner — the read-side equivalent of the EventPublishing chain.
+ * Query runner — the read-side equivalent of the LocalDelivery chain.
  *
  * Queries don't participate in the publish chain; they execute on
  * demand against the projection store (`projection.execute(state, input)`)
- * or via a handler closure (`query.handler(input, ctx)`). The runner is
+ * or via a handler closure (`query.handler(ctx)`). The runner is
  * a thin holder around the registry + execution logic that both the
  * standalone `queriesPlugin` and the bundled `ForgeDispatcher` use.
  *
@@ -39,13 +39,13 @@ export class QueryRunner {
     listQueries() {
         return [...this.queries.keys()];
     }
-    async run(queryName, input, tenant = "") {
+    async run(queryName, input, tenant = "", envelope) {
         const query = this.queries.get(queryName);
         if (!query) {
             throw new Error(`queriesPlugin: no query registered with name "${queryName}".`);
         }
         const t0 = performance.now();
-        const validated = isValidated(input) ? input : markValidated(query.schema.parse(input));
+        const validated = isValidated(input) ? input : markValidated(query.input.parse(input));
         const appName = this.runtime.appName;
         let result;
         if (query.projection && query.execute) {
@@ -54,9 +54,12 @@ export class QueryRunner {
             result = (await query.execute(state, validated));
         }
         else if (query.handler) {
-            result = (await query.handler(validated, {
+            result = (await query.handler({
+                input: validated,
                 resolve: (name) => this.container.resolve(name),
                 tenant,
+                envelope,
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
             }));
         }
         else {