@nwire/forge 0.10.1 → 0.11.1

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

@@ -0,0 +1,47 @@
+/**
+ * `workflowsPlugin` — standalone forge workflow concern.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { workflowsPlugin, forgePlugin } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [
+ *       forgePlugin,
+ *       workflowsPlugin([autoCharge, sendReceipt]),
+ *     ],
+ *   });
+ *
+ * Owns:
+ *   - the `forge.workflowTimerStore` container binding
+ *   - the workflow registry (private to the plugin's `WorkflowChainRunner`)
+ *   - the `forge.publish.workflows` step on the EventPublishing chain
+ *     (priority 400 — between projections and bus delivery)
+ *   - the `forge.workflowChain` container binding so other plugins can
+ *     resolve the runner (the timer scheduler fires through it)
+ *
+ * Workflow effects (`send` / `enqueue` / `publish`) are resolved through
+ * the forge dispatcher bound on the container. `forgePlugin` (or a
+ * future `actionsPlugin`) must be installed alongside this plugin.
+ *
+ * If `forgePlugin`'s `options.workflows` is also passed, both installs
+ * fire 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 { EventBus } from "@nwire/bus";
+import { type WorkflowTimerStore } from "../stores/workflow-timer-store.js";
+import type { WorkflowDefinition } from "../primitives/define-workflow.js";
+export declare const FORGE_WORKFLOW_CHAIN_BINDING: "forge.workflowChain";
+export declare const FORGE_WORKFLOW_TIMER_STORE_BINDING: "forge.workflowTimerStore";
+export interface WorkflowsPluginOptions {
+    /** Override the timer store. Defaults to `InMemoryWorkflowTimerStore`. */
+    readonly workflowTimerStore?: WorkflowTimerStore;
+    /**
+     * Optional bus reference. Not used directly by workflows, but plugins
+     * that wrap the timer scheduler may need it; surfaced here so the
+     * standalone plugin doesn't force them through a re-resolve.
+     */
+    readonly bus?: EventBus;
+}
+export declare function workflowsPlugin(workflows: readonly WorkflowDefinition[], opts?: WorkflowsPluginOptions): PluginDefinition;

package/dist/plugins/workflows-plugin.js

@@ -0,0 +1,81 @@
+/**
+ * `workflowsPlugin` — standalone forge workflow concern.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { workflowsPlugin, forgePlugin } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [
+ *       forgePlugin,
+ *       workflowsPlugin([autoCharge, sendReceipt]),
+ *     ],
+ *   });
+ *
+ * Owns:
+ *   - the `forge.workflowTimerStore` container binding
+ *   - the workflow registry (private to the plugin's `WorkflowChainRunner`)
+ *   - the `forge.publish.workflows` step on the EventPublishing chain
+ *     (priority 400 — between projections and bus delivery)
+ *   - the `forge.workflowChain` container binding so other plugins can
+ *     resolve the runner (the timer scheduler fires through it)
+ *
+ * Workflow effects (`send` / `enqueue` / `publish`) are resolved through
+ * the forge dispatcher bound on the container. `forgePlugin` (or a
+ * future `actionsPlugin`) must be installed alongside this plugin.
+ *
+ * If `forgePlugin`'s `options.workflows` is also passed, both installs
+ * fire every event — install ONE path, not both. A diagnostic warning
+ * fires at `AppReady` when both attachments are present.
+ */
+import { InMemoryWorkflowTimerStore, } from "../stores/workflow-timer-store.js";
+import { FORGE_DISPATCHER_BINDING } from "../runtime/forge-plugin.js";
+import { EVENT_PUBLISHING_PRIORITIES } from "../framework-events.js";
+import { WorkflowChainRunner } from "./workflows-chain.js";
+export const FORGE_WORKFLOW_CHAIN_BINDING = "forge.workflowChain";
+export const FORGE_WORKFLOW_TIMER_STORE_BINDING = "forge.workflowTimerStore";
+export function workflowsPlugin(workflows, opts = {}) {
+    return {
+        name: "forge.workflows",
+        register({ bind }) {
+            const store = opts.workflowTimerStore ?? new InMemoryWorkflowTimerStore();
+            bind(FORGE_WORKFLOW_TIMER_STORE_BINDING, () => store);
+        },
+        setup({ runtime, container, on }) {
+            const timerStore = container.resolve(FORGE_WORKFLOW_TIMER_STORE_BINDING);
+            const chain = new WorkflowChainRunner(runtime, timerStore, (envelope) => {
+                // Effects resolve the dispatcher lazily so the binding exists by
+                // the time a workflow actually fires.
+                const dispatcher = container.resolve(FORGE_DISPATCHER_BINDING);
+                const effects = {
+                    async send(action, input) {
+                        return dispatcher.dispatch(action, input, envelope);
+                    },
+                    async enqueue(action, input) {
+                        void dispatcher.dispatch(action, input, envelope);
+                    },
+                    async publish(eventMsg) {
+                        await dispatcher.publish([eventMsg], envelope);
+                    },
+                };
+                return effects;
+            });
+            for (const workflow of workflows)
+                chain.register(workflow);
+            container.register(FORGE_WORKFLOW_CHAIN_BINDING, chain);
+            runtime.hooks.EventPublishing.use(async (payload, next) => {
+                await chain.apply(payload.event, payload.envelope);
+                await next();
+            }, { name: "forge.publish.workflows", priority: EVENT_PUBLISHING_PRIORITIES.workflows });
+            on("AppReady", () => {
+                const hookChain = runtime.hooks.EventPublishing;
+                const steps = (hookChain.chain ?? []).filter((s) => s.name === "forge.publish.workflows");
+                if (steps.length > 1) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`workflowsPlugin: detected ${steps.length} "forge.publish.workflows" steps on the EventPublishing chain. ` +
+                        `Install either workflowsPlugin OR forgePlugin's options.workflows path, not both.`);
+                }
+            });
+        },
+    };
+}

package/dist/runtime/create-forge-app.d.ts

@@ -1,19 +1,19 @@
 /**
- * `createForgeApp` — foundation-form composition entry point.
+ * `createForgeApp` — composition entry point for forge-shaped apps.
  *
- * Wraps `createRuntime() + runtime.registerPlugin(forgePlugin) +
- * runtime.start/stop` with the forge dispatch verbs added on the returned
- * app handle. Each verb resolves the `ForgeDispatcher` bound on the
- * container by `forgePlugin` and delegates.
+ * A thin wrapper over `createApp({appName, plugins})` that installs forge,
+ * registers direct domain primitives (actors / projections / workflows /
+ * etc.) during boot, and surfaces forge's dispatch verbs (`dispatch`,
+ * `publish`, `query`, …) as methods on the returned handle. Each verb
+ * resolves the `ForgeDispatcher` bound by `forgePlugin` and delegates.
  *
- * Modules are gone in 0.10 — the App is the bounded context. Pass
- * actors / projections / queries / workflows / external calls / handlers
- * directly on opts; they register against the dispatcher during plugin
- * boot (an AppBooting chain step does the registration before any
- * plugin's boot() runs).
+ * The App is the bounded context. Pass actors / projections / queries /
+ * workflows / external calls / handlers directly on opts; they register
+ * against the dispatcher during `AppBooting`, after every plugin's setup
+ * ran (so the dispatcher is bound) but before plugin boot queues fire.
  */
-import { type Container } from "@nwire/container/awilix";
 import { type PluginDefinition, type Runtime } from "@nwire/app";
+import type { Container } from "@nwire/container";
 import type { Logger } from "@nwire/logger";
 import type { MessageEnvelope } from "@nwire/envelope";
 import type { z } from "zod";

package/dist/runtime/create-forge-app.js

@@ -1,39 +1,35 @@
 /**
- * `createForgeApp` — foundation-form composition entry point.
+ * `createForgeApp` — composition entry point for forge-shaped apps.
  *
- * Wraps `createRuntime() + runtime.registerPlugin(forgePlugin) +
- * runtime.start/stop` with the forge dispatch verbs added on the returned
- * app handle. Each verb resolves the `ForgeDispatcher` bound on the
- * container by `forgePlugin` and delegates.
+ * A thin wrapper over `createApp({appName, plugins})` that installs forge,
+ * registers direct domain primitives (actors / projections / workflows /
+ * etc.) during boot, and surfaces forge's dispatch verbs (`dispatch`,
+ * `publish`, `query`, …) as methods on the returned handle. Each verb
+ * resolves the `ForgeDispatcher` bound by `forgePlugin` and delegates.
  *
- * Modules are gone in 0.10 — the App is the bounded context. Pass
- * actors / projections / queries / workflows / external calls / handlers
- * directly on opts; they register against the dispatcher during plugin
- * boot (an AppBooting chain step does the registration before any
- * plugin's boot() runs).
+ * The App is the bounded context. Pass actors / projections / queries /
+ * workflows / external calls / handlers directly on opts; they register
+ * against the dispatcher during `AppBooting`, after every plugin's setup
+ * ran (so the dispatcher is bound) but before plugin boot queues fire.
  */
-import { createContainer } from "@nwire/container/awilix";
-import { createRuntime } from "@nwire/app";
+import { createApp } from "@nwire/app";
 import { forgePlugin as defaultForgePlugin, FORGE_DISPATCHER_BINDING, } from "./forge-plugin.js";
 export function createForgeApp(options) {
-    const container = options.container ?? createContainer();
-    const runtime = createRuntime({
-        container,
-        logger: options.logger,
+    // Forge plugin first; user plugins after. Users can pass an explicit
+    // `createForgePlugin(opts)` in their list to control stores.
+    const plugins = ensureForgePlugin(options.plugins ?? []);
+    const base = createApp({
         appName: options.name,
+        container: options.container,
+        logger: options.logger,
+        plugins,
     });
-    // Forge plugin first; user plugins after. The user can also pass an
-    // explicit `createForgePlugin(opts)` in their list to control stores.
-    const plugins = ensureForgePlugin(options.plugins ?? []);
-    for (const p of plugins) {
-        runtime.registerPlugin(p);
-    }
     // Direct registrations land on the dispatcher during AppBooting —
     // after every plugin's setup ran (so forge's dispatcher is bound)
     // but before plugin boot queues fire (so domain routes are wired
-    // when downstream plugins' boot work might reach for them).
-    runtime.hooks.AppBooting.use(async (_, next) => {
-        const d = container.resolve(FORGE_DISPATCHER_BINDING);
+    // when downstream plugin boot work might reach for them).
+    base.runtime.hooks.AppBooting.use(async (_, next) => {
+        const d = base.container.resolve(FORGE_DISPATCHER_BINDING);
         for (const h of options.handlers ?? []) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             d.registerActionHandler(h);
@@ -50,16 +46,16 @@ export function createForgeApp(options) {
             d.registerExternalCall(call);
         await next();
     }, { name: "forge.app.register-domain", priority: 1_000_000 });
-    const dispatcher = () => container.resolve(FORGE_DISPATCHER_BINDING);
+    const dispatcher = () => base.container.resolve(FORGE_DISPATCHER_BINDING);
     const app = {
         $nwireApp: true,
         appName: options.name,
-        runtime,
-        container,
-        start: () => runtime.start(),
-        stop: (reason) => runtime.stop(reason),
-        boot: () => runtime.start(),
-        shutdown: () => runtime.stop(),
+        runtime: base.runtime,
+        container: base.container,
+        start: () => base.start(),
+        stop: (reason) => base.stop(reason),
+        boot: () => base.start(),
+        shutdown: () => base.stop(),
         dispatcher,
         dispatch: (action, input, parentEnvelope, opts) => dispatcher().dispatch(action, input, parentEnvelope, opts),
         publish: (events, parentEnvelope) => dispatcher().publish(events, parentEnvelope),

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

@@ -133,7 +133,34 @@ 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>>;
+    /**
+     * Publish a batch of events. Each event flows through the
+     * `EventPublishing` hook chain — idempotency → actors → projections →
+     * workflows → bus — at structurally enforced priorities. The chain
+     * participants are attached once at plugin setup via
+     * {@link attachPublishChain}.
+     *
+     * Telemetry (`event.deduped` / `event.published`) is pushed here based
+     * on whether the idempotency step short-circuited the chain.
+     */
     publish(events: readonly EventMessage[], parentEnvelope: MessageEnvelope): Promise<void>;
+    /**
+     * Attach forge's atomic publish chain to the `EventPublishing` hook.
+     * Priority slots are defined in `EVENT_PUBLISHING_PRIORITIES`:
+     *
+     *   1000 — idempotency gate. Short-circuits 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.
+     */
+    attachPublishChain(): void;
     applyExternalEvent(eventName: string, payload: unknown, envelope: MessageEnvelope): Promise<void>;
     private foldProjections;
     private applyToActors;

package/dist/runtime/forge-dispatcher.js

@@ -21,13 +21,14 @@ import { hook } from "@nwire/hooks";
 import { isValidated, markValidated } from "@nwire/messages";
 import { seedEnvelope, deriveEnvelope } from "@nwire/envelope";
 import { loggerForEnvelope } from "@nwire/logger";
-import { buildDeadLetterEntry, InMemoryDeadLetterSink } from "@nwire/dead-letter";
+import { buildDeadLetterEntry, InMemoryDeadLetterSink, } from "@nwire/dead-letter";
 import { sleep, computeBackoff, parseDelay } from "../helpers/retry-helpers.js";
 import { InMemoryActorStore, createInitialInstance, ActorVersionConflictError, } from "../stores/actor-store.js";
 import { InMemoryProjectionStore } from "../stores/projection-store.js";
 import { InMemoryIdempotencyStore } from "../stores/idempotency-store.js";
 import { InMemoryWorkflowTimerStore, timerEventName, } from "../stores/workflow-timer-store.js";
 import { normalizeEventReturn } from "../messages/event-message.js";
+import { EVENT_PUBLISHING_PRIORITIES } from "../framework-events.js";
 export class ForgeDispatcher {
     runtime;
     // ─── Domain registries ──────────────────────────────────────────────
@@ -115,6 +116,17 @@ export class ForgeDispatcher {
         this.handlers.set(name, handler);
         this.ensureActionBeforeHook(name);
         this.ensureActionAfterHook(name);
+        // 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
+        // steps fire when that event flows through.
+        const emits = handler.action.emits;
+        if (emits) {
+            for (const ev of emits) {
+                if (ev.$public === true)
+                    this.publicEventNames.add(ev.name);
+            }
+        }
     }
     registerActor(actor) {
         if (this.actors.has(actor.name)) {
@@ -575,13 +587,30 @@ export class ForgeDispatcher {
         return hctx.result;
     }
     // ─── Publish + applyExternalEvent ──────────────────────────────────
+    /**
+     * Publish a batch of events. Each event flows through the
+     * `EventPublishing` hook chain — idempotency → actors → projections →
+     * workflows → bus — at structurally enforced priorities. The chain
+     * participants are attached once at plugin setup via
+     * {@link attachPublishChain}.
+     *
+     * Telemetry (`event.deduped` / `event.published`) is pushed here based
+     * on whether the idempotency step short-circuited the chain.
+     */
     async publish(events, parentEnvelope) {
         const appName = this.runtime.appName;
         for (let i = 0; i < events.length; i++) {
             const event = events[i];
             const dedupKey = events.length === 1 ? parentEnvelope.messageId : `${parentEnvelope.messageId}#${i}`;
             const childEnvelope = deriveEnvelope(parentEnvelope);
-            if (await this.idempotencyStore.seen(dedupKey)) {
+            const payload = {
+                event,
+                envelope: childEnvelope,
+                dedupKey,
+                deduped: false,
+            };
+            await this.runtime.hooks.EventPublishing.run(payload);
+            if (payload.deduped) {
                 this.runtime.pushTelemetry({
                     kind: "event.deduped",
                     event,
@@ -590,37 +619,87 @@ export class ForgeDispatcher {
                     appName,
                     ts: new Date().toISOString(),
                 });
-                continue;
             }
-            await this.idempotencyStore.record(dedupKey);
-            await this.applyToActors(event, childEnvelope);
-            await this.foldProjections(event, childEnvelope);
-            await this.runWorkflows(event, childEnvelope);
-            this.runtime.pushTelemetry({
-                kind: "event.published",
-                event,
-                envelope: childEnvelope,
-                source: "in-process",
-                appName,
-                ts: new Date().toISOString(),
-            });
-            if (this.publishToBus && this.bus && this.publicEventNames.has(event.eventName)) {
-                await this.bus.publish({
-                    eventName: event.eventName,
-                    payload: event.payload,
+            else {
+                this.runtime.pushTelemetry({
+                    kind: "event.published",
+                    event,
                     envelope: childEnvelope,
-                    origin: appName,
+                    source: "in-process",
+                    appName,
+                    ts: new Date().toISOString(),
                 });
             }
         }
     }
+    /**
+     * Attach forge's atomic publish chain to the `EventPublishing` hook.
+     * Priority slots are defined in `EVENT_PUBLISHING_PRIORITIES`:
+     *
+     *   1000 — idempotency gate. Short-circuits 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.
+     */
+    attachPublishChain() {
+        const hook = this.runtime.hooks.EventPublishing;
+        hook.use(async (payload, next) => {
+            const isNew = await this.idempotencyStore.recordIfNew(payload.dedupKey);
+            if (!isNew) {
+                payload.deduped = true;
+                return; // veto — downstream steps 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 next();
+        }, { name: "forge.publish.actors", priority: EVENT_PUBLISHING_PRIORITIES.actors });
+        hook.use(async (payload, next) => {
+            await this.foldProjections(payload.event, 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 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 };
-        if (await this.idempotencyStore.seen(envelope.messageId)) {
+        const isNew = await this.idempotencyStore.recordIfNew(envelope.messageId);
+        if (!isNew) {
             this.runtime.pushTelemetry({
                 kind: "event.deduped",
                 event,
@@ -631,7 +710,6 @@ export class ForgeDispatcher {
             });
             return;
         }
-        await this.idempotencyStore.record(envelope.messageId);
         await this.applyToActors(event, envelope);
         await this.foldProjections(event, envelope);
         await this.runWorkflows(event, envelope);

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

@@ -1,59 +1,74 @@
 /**
- * `forgePlugin` — the foundation-form delivery of forge's CQRS engine.
+ * Forge plugin — installs the dispatcher, materialises forge's framework
+ * hooks, pins the action handler step on the dispatch chain, and registers
+ * any domain primitives passed in options.
  *
- * Used two ways:
+ *   import { createApp } from "@nwire/app";
+ *   import { createForgePlugin, FORGE_DISPATCHER_BINDING } from "@nwire/forge";
  *
- *   // Default stores (InMemory*):
- *   createApp({ plugins: [forgePlugin, ...] })
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [createForgePlugin({
+ *       actors: [Order],
+ *       projections: [OrdersDashboard],
+ *       handlers: [placeOrder, sendReceipt],
+ *     })],
+ *   });
  *
- *   // Custom stores / cross-service bus / persistent timers:
- *   createApp({ plugins: [createForgePlugin({ actorStore, bus }), ...] })
+ *   await app.start();
+ *   const dispatcher = app.container.resolve(FORGE_DISPATCHER_BINDING);
  *
- * Setup work:
- *   1. Construct a `ForgeDispatcher(runtime, opts)`.
- *   2. Bind it on the container as `"forge.dispatcher"`; consumer code
- *      (and forge.createApp's app-handle delegators) resolves it from
- *      there to call `dispatch / publish / fireDueTimers / …`.
- *   3. Materialise the Action* / Event* framework-hook slots forge's
- *      module augmentation declares — kernel pre-instantiates only
- *      App* / Plugin* / Wire* slots; forge's domain slots come in via
- *      the plugin so a non-forge app's runtime stays uncluttered.
- *   4. Pin the action handler chain step on `runtime.dispatchHook$` at
- *      priority `-Infinity` so user-registered `runtime.use()` middleware
- *      stays strictly OUTSIDE the handler invocation.
+ * Handlers and direct registrations land on the dispatcher during the
+ * `AppBooting` chain — after every plugin's setup ran (so the dispatcher
+ * is bound) but before plugin boot queues fire (so downstream plugins'
+ * boot work can reach domain routes already wired).
  *
- * Dispose work:
- *   - Best-effort cleanup of the in-memory workflow timer scheduler if
- *     the dispatcher started one. Persistent stores release through
- *     their own `bind({ dispose })` registrations.
+ * `forgePlugin` is the default-options shortcut for tests, demos, and
+ * single-process apps. For custom stores or a cross-service bus, use
+ * `createForgePlugin(opts)`.
  */
 import type { PluginDefinition } from "@nwire/app";
-import { type ForgeDispatcherOptions } from "./forge-dispatcher.js";
-/** Canonical container binding name for the forge dispatcher. */
+import { ForgeDispatcher, type ForgeDispatcherOptions } from "./forge-dispatcher.js";
+import type { ActorDefinition } from "../primitives/define-actor.js";
+import type { ProjectionDefinition } from "../primitives/define-projection.js";
+import type { QueryDefinition } from "../primitives/define-query.js";
+import type { WorkflowDefinition } from "../primitives/define-workflow.js";
+import type { ExternalCallDefinition } from "../primitives/define-external-call.js";
+import type { HandlerDefinition as ForgeHandlerDef } from "../primitives/define-handler.js";
+/** Container binding the forge dispatcher is registered under. */
 export declare const FORGE_DISPATCHER_BINDING: "forge.dispatcher";
-/** Capability bindings — handler / resolver ctx resolves these by name. */
+/** Capability bindings consumed by handler / resolver ctx via `ctx.resolve(...)`. */
 export declare const FORGE_EXECUTE_BINDING: "execute";
 export declare const FORGE_SEND_BINDING: "send";
 export declare const FORGE_USE_PROJECTION_BINDING: "useProjection";
 /**
- * Default forge plugin — uses in-memory stores for everything.
- * Suitable for tests, demos, and single-process apps. For custom
- * stores or a cross-service bus, use `createForgePlugin(opts)`.
- */
-export declare const forgePlugin: PluginDefinition;
-/**
- * Configurable forge plugin. Pass:
- *   - durable stores (actorStore, projectionStore, deadLetterSink, …)
- *   - a cross-service EventBus to bridge in-process events out
- *   - domain registrations (actors, workflows, projections, queries,
- *     externalCalls) — picked up at AppBooting and forwarded to the
- *     dispatcher so consumers don't need to wire them manually.
+ * Options accepted by `createForgePlugin`. Includes the dispatcher's own
+ * options (stores, bus) and the domain primitives that register against
+ * the dispatcher during the boot phase.
  */
 export interface ForgePluginOptions extends ForgeDispatcherOptions {
-    readonly actors?: readonly any[];
-    readonly workflows?: readonly any[];
-    readonly projections?: readonly any[];
-    readonly queries?: readonly any[];
-    readonly externalCalls?: readonly any[];
+    readonly handlers?: readonly ForgeHandlerDef<any>[];
+    readonly actors?: readonly ActorDefinition[];
+    readonly projections?: readonly ProjectionDefinition<any>[];
+    readonly queries?: readonly QueryDefinition<any, any, any>[];
+    readonly workflows?: readonly WorkflowDefinition[];
+    readonly externalCalls?: readonly ExternalCallDefinition<any, any>[];
 }
+/**
+ * Construct a forge plugin with custom stores, bus, and/or domain
+ * primitives. The plugin's setup is synchronous; domain registration
+ * happens during the App's `AppBooting` chain.
+ */
 export declare function createForgePlugin(options?: ForgePluginOptions): PluginDefinition;
+/** Default forge plugin — in-memory stores, no bus, no domain options. */
+export declare const forgePlugin: PluginDefinition;
+/**
+ * Resolve the forge dispatcher from an app's container. Convenience for
+ * test code and tooling that needs direct dispatcher access; handler code
+ * uses `ctx.execute` / `ctx.send` / `ctx.publish` instead.
+ */
+export declare function forgeDispatcher(app: {
+    container: {
+        resolve<T>(name: string): T;
+    };
+}): ForgeDispatcher;