@nwire/forge 0.10.1 → 0.11.1

package/dist/plugins/actions-plugin.js

@@ -0,0 +1,76 @@
+/**
+ * `actionsPlugin` — standalone forge action concern.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import {
+ *     actionsPlugin,
+ *     idempotencyPlugin,
+ *     forgePlugin,
+ *   } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [
+ *       forgePlugin,
+ *       actionsPlugin([placeOrderHandler, sendReceiptHandler]),
+ *     ],
+ *   });
+ *
+ * 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
+ *
+ * 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.
+ */
+import { InMemoryDeadLetterSink } from "@nwire/dead-letter";
+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 = {}) {
+    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);
+        },
+        setup({ runtime, container }) {
+            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) => {
+                for (let i = 0; i < events.length; i++) {
+                    const event = events[i];
+                    const dedupKey = events.length === 1 ? envelope.messageId : `${envelope.messageId}#${i}`;
+                    const payload = {
+                        event,
+                        envelope,
+                        dedupKey,
+                        deduped: false,
+                    };
+                    await runtime.hooks.EventPublishing.run(payload);
+                }
+            };
+            const runner = new ActionRunner(runtime, container, sink, publishEvents);
+            for (const handler of handlers)
+                runner.register(handler);
+            container.register(FORGE_ACTION_RUNNER_BINDING, runner);
+        },
+    };
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Actor chain runner — the EventPublishing step that applies an event to
+ * every registered actor type whose reactions match.
+ *
+ * Self-contained: takes its dependencies as constructor arguments. Both
+ * `actorsPlugin` and the bundled `ForgeDispatcher` instantiate one of
+ * these and call `apply(event, envelope)` from their respective hook
+ * attachment.
+ *
+ * Behavior matches the original dispatcher implementation: per-actor
+ * locking, optimistic concurrency retry, schema validation, per-actor
+ * transition hook fan-out, and `actor.transitioned` telemetry.
+ */
+import { type Hook } from "@nwire/hooks";
+import { type MessageEnvelope } from "@nwire/envelope";
+import { type Runtime } from "@nwire/app";
+import type { ActorDefinition } from "../primitives/define-actor.js";
+import type { ActorTransitionHookCtx } from "../runtime/forge-types.js";
+import type { EventMessage } from "../messages/event-message.js";
+import { type ActorStore } from "../stores/actor-store.js";
+/**
+ * Listener fired after any actor transition (any type). Plugins observe
+ * cross-actor side effects with these (the workflow timer scheduler is
+ * the canonical example).
+ */
+export type ActorTransitionListener = (actor: ActorDefinition, key: string, fromState: string, toState: string, triggeringEvent: EventMessage, envelope: MessageEnvelope) => void | Promise<void>;
+export declare class ActorChainRunner {
+    private readonly runtime;
+    readonly store: ActorStore;
+    readonly actors: Map<string, ActorDefinition>;
+    readonly perActorHooks: Map<string, Hook<ActorTransitionHookCtx>>;
+    readonly globalListeners: ActorTransitionListener[];
+    constructor(runtime: Runtime, store: ActorStore);
+    /** Register an actor type. Throws on duplicate names. */
+    register(actor: ActorDefinition): void;
+    /** All registered actor type names, in registration order. */
+    listActors(): readonly string[];
+    /** Register a global transition listener. */
+    observeTransitions(listener: ActorTransitionListener): void;
+    /** Lazy-create the per-actor transition hook. */
+    ensureTransitionHook(actorName: string): Hook<ActorTransitionHookCtx>;
+    /**
+     * Apply one event to every actor type whose reactions match. Called
+     * by the EventPublishing step at priority 800.
+     */
+    apply(event: EventMessage, envelope: MessageEnvelope): Promise<void>;
+    private extractKey;
+    private applyToOne;
+    private applyLocked;
+    private computeTimersForState;
+    private envelopeLogger;
+}

package/dist/plugins/actors-chain.js

@@ -0,0 +1,204 @@
+/**
+ * Actor chain runner — the EventPublishing step that applies an event to
+ * every registered actor type whose reactions match.
+ *
+ * Self-contained: takes its dependencies as constructor arguments. Both
+ * `actorsPlugin` and the bundled `ForgeDispatcher` instantiate one of
+ * these and call `apply(event, envelope)` from their respective hook
+ * attachment.
+ *
+ * Behavior matches the original dispatcher implementation: per-actor
+ * locking, optimistic concurrency retry, schema validation, per-actor
+ * transition hook fan-out, and `actor.transitioned` telemetry.
+ */
+import { hook } from "@nwire/hooks";
+import { loggerForEnvelope } from "@nwire/logger";
+import { parseDelay } from "../helpers/retry-helpers.js";
+import { createInitialInstance, ActorVersionConflictError, } from "../stores/actor-store.js";
+export class ActorChainRunner {
+    runtime;
+    store;
+    actors = new Map();
+    perActorHooks = new Map();
+    globalListeners = [];
+    constructor(runtime, store) {
+        this.runtime = runtime;
+        this.store = store;
+    }
+    /** Register an actor type. Throws on duplicate names. */
+    register(actor) {
+        if (this.actors.has(actor.name)) {
+            throw new Error(`actorsPlugin: actor "${actor.name}" already registered.`);
+        }
+        this.actors.set(actor.name, actor);
+        this.ensureTransitionHook(actor.name);
+    }
+    /** All registered actor type names, in registration order. */
+    listActors() {
+        return [...this.actors.keys()];
+    }
+    /** Register a global transition listener. */
+    observeTransitions(listener) {
+        this.globalListeners.push(listener);
+    }
+    /** Lazy-create the per-actor transition hook. */
+    ensureTransitionHook(actorName) {
+        let h = this.perActorHooks.get(actorName);
+        if (h)
+            return h;
+        h = hook(`actor.transition:${actorName}`);
+        this.perActorHooks.set(actorName, h);
+        return h;
+    }
+    /**
+     * Apply one event to every actor type whose reactions match. Called
+     * by the EventPublishing step at priority 800.
+     */
+    async apply(event, envelope) {
+        const tenant = envelope.tenant ?? "";
+        for (const actor of this.actors.values()) {
+            const reactionsForEvent = actor.eventIndex.get(event.eventName);
+            if (!reactionsForEvent || reactionsForEvent.length === 0)
+                continue;
+            const key = this.extractKey(event, actor);
+            if (key === undefined || key === null)
+                continue;
+            await this.applyToOne(actor, String(key), tenant, event, reactionsForEvent, envelope);
+        }
+    }
+    extractKey(event, actor) {
+        const payload = event.payload;
+        if (!payload || typeof payload !== "object")
+            return undefined;
+        return payload[actor.key];
+    }
+    async applyToOne(actor, key, tenant, event, candidateReactions, envelope) {
+        const release = (await this.store.lockKey?.(actor.name, key, tenant)) ?? (() => { });
+        try {
+            await this.applyLocked(actor, key, tenant, event, candidateReactions, envelope);
+        }
+        finally {
+            release();
+        }
+    }
+    async applyLocked(actor, key, tenant, event, candidateReactions, envelope) {
+        const appName = this.runtime.appName;
+        const maxOccRetries = 3;
+        for (let occAttempt = 0; occAttempt < maxOccRetries; occAttempt++) {
+            const existing = await this.store.load(actor.name, key, tenant);
+            const instance = existing ?? createInitialInstance(actor, key, tenant);
+            const matching = candidateReactions.find((c) => c.state === instance.state);
+            if (!matching)
+                return;
+            const stateConfig = actor.states[instance.state];
+            if (stateConfig?.final)
+                return;
+            const partial = matching.reaction.assign
+                ? matching.reaction.assign(instance.data, event.payload)
+                : {};
+            const nextData = { ...instance.data, ...partial };
+            const nextStateName = matching.reaction.target ?? instance.state;
+            const nextStateConfig = actor.states[nextStateName];
+            if (!nextStateConfig) {
+                throw new Error(`actorsPlugin: actor "${actor.name}" reaction targets undeclared state "${nextStateName}" from "${instance.state}".`);
+            }
+            const validated = actor.schema.parse(nextData);
+            const stateChanged = nextStateName !== instance.state;
+            const isNewActor = !existing;
+            const nextTimers = stateChanged || isNewActor
+                ? this.computeTimersForState(actor, nextStateName, key)
+                : instance.activeTimers;
+            const nextInstance = {
+                actorName: actor.name,
+                key,
+                tenant,
+                state: nextStateName,
+                data: validated,
+                activeTimers: nextTimers,
+                version: instance.version,
+            };
+            try {
+                await this.store.save(nextInstance, { expectedVersion: instance.version });
+            }
+            catch (err) {
+                if (err instanceof ActorVersionConflictError && occAttempt < maxOccRetries - 1)
+                    continue;
+                throw err;
+            }
+            if (stateChanged) {
+                this.runtime.pushTelemetry({
+                    kind: "actor.transitioned",
+                    actor: actor.name,
+                    key,
+                    tenant,
+                    from: instance.state,
+                    to: nextStateName,
+                    triggeringEvent: event.eventName,
+                    envelope,
+                    appName,
+                    ts: new Date().toISOString(),
+                });
+                for (const listener of this.globalListeners) {
+                    await listener(actor, key, instance.state, nextStateName, event, envelope);
+                }
+                const perActorHook = this.perActorHooks.get(actor.name);
+                if (perActorHook) {
+                    try {
+                        await perActorHook.run({
+                            actor,
+                            key,
+                            fromState: instance.state,
+                            toState: nextStateName,
+                            triggeringEvent: event,
+                            envelope,
+                        });
+                    }
+                    catch (err) {
+                        this.envelopeLogger(envelope).error(`actor.transition hook threw`, {
+                            actor: actor.name,
+                            error: err?.message,
+                        });
+                    }
+                }
+            }
+            return;
+        }
+    }
+    computeTimersForState(actor, stateName, actorKey) {
+        const stateConfig = actor.states[stateName];
+        if (!stateConfig?.after)
+            return {};
+        const appName = this.runtime.appName;
+        const now = Date.now();
+        const timers = {};
+        for (const [timerName, spec] of Object.entries(stateConfig.after)) {
+            const delayString = typeof spec === "string" ? timerName : spec.delay;
+            const action = typeof spec === "string" ? spec : spec.action;
+            const input = typeof spec === "string" || !spec.buildInput
+                ? { [actor.key]: actorKey }
+                : spec.buildInput({}, actorKey);
+            const handle = {
+                scheduledAt: now,
+                fireAt: now + parseDelay(delayString),
+                action,
+                input,
+            };
+            timers[timerName] = handle;
+            this.runtime.pushTelemetry({
+                kind: "timer.scheduled",
+                actor: actor.name,
+                key: actorKey,
+                timer: timerName,
+                action,
+                fireAt: handle.fireAt,
+                tenant: "",
+                appName,
+                ts: new Date().toISOString(),
+            });
+        }
+        return timers;
+    }
+    envelopeLogger(envelope) {
+        return loggerForEnvelope(this.runtime.logger, envelope);
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * `actorsPlugin` — standalone forge actor concern.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { actorsPlugin, forgePlugin } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [
+ *       forgePlugin,                   // publish orchestration + idempotency + bus
+ *       actorsPlugin([Order, Cart]),   // actor state transitions
+ *     ],
+ *   });
+ *
+ * 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
+ *     (priority 800 — between idempotency and projections)
+ *   - the `forge.actorChain` container binding so other plugins can
+ *     resolve the runner (workflow timer scheduler, ctx.use binding, …)
+ *
+ * If `forgePlugin`'s `options.actors` is also passed, both installs run
+ * actor work for every event — install ONE path, not both. A diagnostic
+ * warning fires at `AppReady` when both attachments are present.
+ */
+import type { PluginDefinition } from "@nwire/app";
+import { type ActorStore } from "../stores/actor-store.js";
+import type { ActorDefinition } from "../primitives/define-actor.js";
+export declare const FORGE_ACTOR_CHAIN_BINDING: "forge.actorChain";
+export declare const FORGE_ACTOR_STORE_BINDING: "forge.actorStore";
+export interface ActorsPluginOptions {
+    /** Override the actor store. Defaults to `InMemoryActorStore`. */
+    readonly actorStore?: ActorStore;
+}
+export declare function actorsPlugin(actorTypes: readonly ActorDefinition[], opts?: ActorsPluginOptions): PluginDefinition;

package/dist/plugins/actors-plugin.js

@@ -0,0 +1,62 @@
+/**
+ * `actorsPlugin` — standalone forge actor concern.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { actorsPlugin, forgePlugin } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [
+ *       forgePlugin,                   // publish orchestration + idempotency + bus
+ *       actorsPlugin([Order, Cart]),   // actor state transitions
+ *     ],
+ *   });
+ *
+ * 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
+ *     (priority 800 — between idempotency and projections)
+ *   - the `forge.actorChain` container binding so other plugins can
+ *     resolve the runner (workflow timer scheduler, ctx.use binding, …)
+ *
+ * If `forgePlugin`'s `options.actors` is also passed, both installs run
+ * actor work for every event — install ONE path, not both. A diagnostic
+ * warning fires at `AppReady` when both attachments are present.
+ */
+import { InMemoryActorStore } from "../stores/actor-store.js";
+import { EVENT_PUBLISHING_PRIORITIES } from "../framework-events.js";
+import { ActorChainRunner } from "./actors-chain.js";
+export const FORGE_ACTOR_CHAIN_BINDING = "forge.actorChain";
+export const FORGE_ACTOR_STORE_BINDING = "forge.actorStore";
+export function actorsPlugin(actorTypes, opts = {}) {
+    return {
+        name: "forge.actors",
+        register({ bind }) {
+            const store = opts.actorStore ?? new InMemoryActorStore();
+            bind(FORGE_ACTOR_STORE_BINDING, () => store);
+        },
+        setup({ runtime, container, on }) {
+            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);
+                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.`);
+                }
+            });
+        },
+    };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * `dlqPlugin` — owns the dead-letter sink binding.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { dlqPlugin, actionsPlugin } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [
+ *       dlqPlugin({ deadLetterSink: pgDeadLetterSink }),
+ *       actionsPlugin(handlers),
+ *     ],
+ *   });
+ *
+ * Binds `forge.deadLetterSink` (overridable). `actionsPlugin` reads from
+ * this binding when it constructs its `ActionRunner`. Install dlqPlugin
+ * BEFORE actionsPlugin so the binding exists at the time actionsPlugin's
+ * setup runs.
+ *
+ * If neither dlqPlugin nor a binding override is present, actionsPlugin
+ * falls back to an `InMemoryDeadLetterSink`.
+ */
+import type { PluginDefinition } from "@nwire/app";
+import { type DeadLetterSink } from "@nwire/dead-letter";
+export interface DlqPluginOptions {
+    /** Override the dead-letter sink. Defaults to `InMemoryDeadLetterSink`. */
+    readonly deadLetterSink?: DeadLetterSink;
+}
+export declare function dlqPlugin(opts?: DlqPluginOptions): PluginDefinition;

package/dist/plugins/dlq-plugin.js

@@ -0,0 +1,37 @@
+/**
+ * `dlqPlugin` — owns the dead-letter sink binding.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { dlqPlugin, actionsPlugin } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [
+ *       dlqPlugin({ deadLetterSink: pgDeadLetterSink }),
+ *       actionsPlugin(handlers),
+ *     ],
+ *   });
+ *
+ * Binds `forge.deadLetterSink` (overridable). `actionsPlugin` reads from
+ * this binding when it constructs its `ActionRunner`. Install dlqPlugin
+ * BEFORE actionsPlugin so the binding exists at the time actionsPlugin's
+ * setup runs.
+ *
+ * If neither dlqPlugin nor a binding override is present, actionsPlugin
+ * falls back to an `InMemoryDeadLetterSink`.
+ */
+import { InMemoryDeadLetterSink } from "@nwire/dead-letter";
+import { FORGE_DEAD_LETTER_SINK_BINDING } from "./actions-plugin.js";
+export function dlqPlugin(opts = {}) {
+    return {
+        name: "forge.dlq",
+        register({ bind }) {
+            const sink = opts.deadLetterSink ?? new InMemoryDeadLetterSink();
+            bind(FORGE_DEAD_LETTER_SINK_BINDING, () => sink);
+        },
+        setup() {
+            // No setup work — the binding is the contract. ActionsPlugin reads
+            // it during its own setup.
+        },
+    };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * `idempotencyPlugin` — owns the per-event dedup gate at the head of
+ * the EventPublishing chain.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { idempotencyPlugin, forgePlugin } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [forgePlugin, idempotencyPlugin()],
+ *   });
+ *
+ * Binds `forge.idempotencyStore` and attaches the
+ * `forge.publish.idempotency` step at priority 1000. The step checks
+ * whether the event's `dedupKey` has been seen and short-circuits when
+ * it has, marking `payload.deduped = true`.
+ *
+ * If `forgePlugin`'s bundled mode is also installed, a duplicate step
+ * runs; warn at AppReady.
+ */
+import type { PluginDefinition } from "@nwire/app";
+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;
+}
+export declare function idempotencyPlugin(opts?: IdempotencyPluginOptions): PluginDefinition;

package/dist/plugins/idempotency-plugin.js

@@ -0,0 +1,57 @@
+/**
+ * `idempotencyPlugin` — owns the per-event dedup gate at the head of
+ * the EventPublishing chain.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { idempotencyPlugin, forgePlugin } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [forgePlugin, idempotencyPlugin()],
+ *   });
+ *
+ * Binds `forge.idempotencyStore` and attaches the
+ * `forge.publish.idempotency` step at priority 1000. The step checks
+ * whether the event's `dedupKey` has been seen and short-circuits when
+ * it has, marking `payload.deduped = true`.
+ *
+ * If `forgePlugin`'s bundled mode is also installed, a duplicate step
+ * runs; warn at AppReady.
+ */
+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 = {}) {
+    return {
+        name: "forge.idempotency",
+        register({ bind }) {
+            const store = opts.idempotencyStore ?? new InMemoryIdempotencyStore();
+            bind(FORGE_IDEMPOTENCY_STORE_BINDING, () => store);
+        },
+        setup({ runtime, container, on }) {
+            const store = container.resolve(FORGE_IDEMPOTENCY_STORE_BINDING);
+            runtime.hooks.EventPublishing.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);
+                if (!isNew) {
+                    payload.deduped = true;
+                    return; // veto — chain stops here
+                }
+                await next();
+            }, {
+                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.`);
+                }
+            });
+        },
+    };
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Projection chain runner — the EventPublishing step that folds an
+ * event into every registered projection that listens for it.
+ *
+ * Self-contained: takes its dependencies as constructor arguments. Both
+ * `projectionsPlugin` and the bundled `ForgeDispatcher` instantiate one
+ * of these and call `apply(event, envelope)` from their respective hook
+ * attachment.
+ *
+ * Per-event behaviour:
+ *   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
+ *      surfaces the failure).
+ */
+import { type MessageEnvelope } from "@nwire/envelope";
+import { type Runtime } from "@nwire/app";
+import type { ProjectionDefinition } from "../primitives/define-projection.js";
+import type { EventMessage } from "../messages/event-message.js";
+import { type ProjectionStore } from "../stores/projection-store.js";
+export declare class ProjectionChainRunner {
+    private readonly runtime;
+    readonly store: ProjectionStore;
+    readonly projections: Map<string, ProjectionDefinition<unknown>>;
+    readonly projectionsByEvent: Map<string, ProjectionDefinition<unknown>[]>;
+    constructor(runtime: Runtime, store: ProjectionStore);
+    /** Register a projection. Throws on duplicate names. */
+    register(projection: ProjectionDefinition<unknown>): void;
+    /** All registered projection names, in registration order. */
+    listProjections(): readonly string[];
+    /** Apply one event to every projection that listens for it. */
+    apply(event: EventMessage, envelope: MessageEnvelope): Promise<void>;
+}