@nwire/forge 0.12.1 → 0.13.1

package/dist/runtime/forge-plugin.js

@@ -27,7 +27,9 @@
  * single-process apps. For custom stores or a cross-service bus, use
  * `createForgePlugin(opts)`.
  */
+import { loggerForEnvelope } from "@nwire/logger";
 import { ForgeDispatcher } from "./forge-dispatcher.js";
+import { seedEnvelope } from "@nwire/envelope";
 /** Container binding the forge dispatcher is registered under. */
 export const FORGE_DISPATCHER_BINDING = "forge.dispatcher";
 /** Capability bindings consumed by handler / resolver ctx via `ctx.resolve(...)`. */
@@ -42,59 +44,117 @@ export const FORGE_USE_PROJECTION_BINDING = "useProjection";
 export function createForgePlugin(options = {}) {
     return {
         name: "forge",
-        setup({ runtime, bind, dispose, hooks }) {
+        setup({ runtime, bind, dispose, hooks, add }) {
             const dispatcher = new ForgeDispatcher(runtime, options);
             bind(FORGE_DISPATCHER_BINDING, dispatcher);
+            // Forge handler-ctx members as a capability — contributed per dispatch
+            // via capCtx (so they ride `runtime.execute`'s one ctx). The dispatcher
+            // is resolved per dispatch; `signal` threads cancellation into nested
+            // dispatches. `emit`/`publish` come from the core publish capability, not
+            // here. Replaces the hand-built members in the old `buildHandlerContext`.
+            add({
+                name: "forge.ctx",
+                provideCtx: ({ envelope, container, signal }) => {
+                    const d = container.resolve(FORGE_DISPATCHER_BINDING);
+                    return {
+                        // Members the old buildHandlerContext put on the forge handler ctx
+                        // that execute's base ctx doesn't carry.
+                        logger: loggerForEnvelope(runtime.logger, envelope),
+                        container,
+                        signal,
+                        requestId: envelope.messageId,
+                        request: (action, input) => d.dispatch(action, input, envelope, { signal }),
+                        // Fire-and-forget command dispatch. Rides the runtime's `enqueue`
+                        // so it returns a MessageRef up-front (named for the same message
+                        // the deferred dispatch runs under) rather than blocking on the
+                        // handler's result. The handler's `run` is the full forge pipeline,
+                        // so retry / hooks / event-publish still fire when it lands.
+                        send: (action, input) => {
+                            const handler = d.findHandler(action.name);
+                            if (!handler) {
+                                throw new Error(`forge ctx.send: no handler registered for action "${action.name}".`);
+                            }
+                            return runtime.enqueue(handler, input, { parent: envelope, signal });
+                        },
+                        query: (queryDef, input) => d.query(queryDef.name, input, envelope.tenant ?? ""),
+                        actor: (actor, id) => d.actorView(actor, id, envelope),
+                        externalCall: (call, request) => d.executeExternalCall(call, request, envelope),
+                    };
+                },
+            });
             // Capability factories for handler / HTTP resolver ctx
             // (`ctx.resolve("execute" | "send" | "useProjection")`).
             const execute = (action, input, envelope) => dispatcher.dispatch(action, input, envelope);
             const send = (action, input, envelope) => {
-                void dispatcher.dispatch(action, input, envelope);
-                return Promise.resolve();
+                const handler = dispatcher.findHandler(action.name);
+                if (!handler) {
+                    throw new Error(`forge send: no handler registered for action "${action.name}".`);
+                }
+                return runtime.enqueue(handler, input, { parent: envelope });
             };
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const useProjection = (query, input, tenant = "") => dispatcher.query(query.name, input, tenant);
             bind(FORGE_EXECUTE_BINDING, () => execute);
             bind(FORGE_SEND_BINDING, () => send);
             bind(FORGE_USE_PROJECTION_BINDING, () => useProjection);
-            // Materialise forge's Action* / Event* hook slots and the
-            // EventPublishing chain. Apps without forge don't carry these.
+            // Materialise forge's Action* / Event* hook slots. Apps without forge
+            // don't carry these. (Local event delivery rides the core
+            // `LocalDelivery` hook, which is always present.)
             for (const slot of [
                 "ActionDispatching",
                 "ActionCompleted",
                 "ActionFailed",
                 "EventRecording",
                 "EventRecorded",
-                "EventPublishing",
             ]) {
                 runtime.defineHook(slot);
             }
-            // Attach forge's atomic publish chain to the EventPublishing hook.
-            // Each step does its work for one event and calls next() to descend
-            // to the next priority slot. The idempotency step short-circuits
-            // (skips next) when a duplicate is seen.
+            // Attach forge's fold steps (idempotency → actors → projections →
+            // workflows) to the core `LocalDelivery` hook. Each step does its work
+            // for one event and calls next() to descend to the next priority slot;
+            // the idempotency step short-circuits (skips next) on a duplicate.
+            // Bus + outbound sink are NOT chain steps — `dispatcher.publish`
+            // applies them after `runtime.deliver` for public, non-deduped events.
             dispatcher.attachPublishChain();
-            // Pin the dispatch chain handler step at priority -Infinity so any
-            // user `runtime.use()` middleware stays strictly outside the
-            // handler invocation.
-            //
-            // The runtime installs its OWN core step (`__nwire_runtime_core__`,
-            // also -Infinity) the first time a `runtime.use()` middleware routes
-            // a dispatch through the chain. Both steps would otherwise call
-            // `coreFn()`, so a forge action running while any user middleware is
-            // present would execute its handler twice. Guard the call with a
-            // per-dispatch sentinel: whichever -Infinity step runs first invokes
-            // the handler; the rest fall through. Forge keeps its own step
-            // because it dispatches straight through `dispatchHook$.run`, where
-            // the runtime's lazily-pinned step may not exist yet.
-            runtime.dispatchHook$.use(async (hctx, next) => {
-                const h = hctx;
-                if (!h.__nwireCoreInvoked) {
-                    h.__nwireCoreInvoked = true;
-                    hctx.result = await hctx.coreFn();
-                }
-                await next();
-            }, { name: "handler", priority: -Infinity });
+            // External / bus-inbound events ride the ONE delivery path. This source
+            // stage folds a declared external event through `runtime.deliver` — the
+            // same LocalDelivery chain (idempotency → actors → projections →
+            // workflows + listeners) that local `emit` uses — deduped by the
+            // inbound messageId, then stops the chain so the terminal router does
+            // not re-handle it. Non-external events pass through to the router,
+            // which validates them against their definition. Replaces the dispatcher
+            // `applyExternalEvent` parallel fold.
+            runtime.source({
+                name: "forge.external-delivery",
+                position: "terminal",
+                run: async (ctx) => {
+                    const msg = ctx.message;
+                    if (!msg || msg.kind !== "event")
+                        return;
+                    if (!dispatcher.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 };
+                },
+            });
             // Domain registration runs at AppBooting — 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
@@ -126,8 +186,30 @@ export function createForgePlugin(options = {}) {
                 for (const call of options.externalCalls ?? []) {
                     dispatcher.registerExternalCall(call);
                 }
+                for (const eventName of options.externalEvents ?? []) {
+                    dispatcher.registerExternalEvent(eventName);
+                }
                 await next();
             }, { name: "forge.register-domain", priority: 1_000_000 });
+            // Bus inbound — the symmetric counterpart to outbound `publishToBus`.
+            // When a bus is configured, subscribe each declared external event and
+            // fold it through `runtime.receive`; the forge external-delivery source
+            // stage lands it on the one delivery path, deduped by the inbound
+            // messageId. Skips this app's own published echoes by origin. Runs after
+            // domain registration so `externalEventNames` is populated.
+            if (options.bus) {
+                const bus = options.bus;
+                hooks.AppBooting.use(async (_, next) => {
+                    for (const eventName of dispatcher.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 });
+                        });
+                    }
+                    await next();
+                }, { name: "forge.bus-inbound", priority: 900_000 });
+            }
             // Cleanup hook — durable adopters with their own dispose schedules
             // register via `bind(name, store, { dispose })`.
             dispose(async () => {

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

@@ -0,0 +1,55 @@
+/**
+ * `forgePlugins(options)` — the batteries-included forge SET.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { forgePlugins } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     handlers: [placeOrder, sendReceipt, listOrders],  // actions + queries
+ *     plugins: [...forgePlugins({ actors, projections })],
+ *   });
+ *
+ * Handlers are NOT passed here — registration is the app's job. forge scans the
+ * runtime for `kind:"action"` / `kind:"query"` and wires each (command pipeline
+ * for actions, the read engine for queries).
+ *
+ * It is NOT a wrapping plugin — it returns the array of concern plugins so the
+ * composition stays a flat set you can see and trim. Install the concern
+ * plugins individually for an à-la-carte build; spread `forgePlugins()` for the
+ * full set. There is no parallel dispatcher — each plugin registers its
+ * primitives on the runtime, attaches its fold step to `LocalDelivery`, and
+ * contributes its own ctx verb.
+ */
+import type { PluginDefinition } from "@nwire/app";
+import type { DeadLetterSink } from "@nwire/dead-letter";
+import type { EventBus } from "@nwire/bus";
+import type { ActorDefinition } from "../primitives/define-actor.js";
+import type { ProjectionDefinition } from "../primitives/define-projection.js";
+import type { WorkflowDefinition } from "../primitives/define-workflow.js";
+import type { ExternalCallDefinition } from "../primitives/define-external-call.js";
+import type { ActorStore } from "../stores/actor-store.js";
+import type { ProjectionStore } from "../stores/projection-store.js";
+import type { IdempotencyStore } from "../stores/idempotency-store.js";
+import type { WorkflowTimerStore } from "../stores/workflow-timer-store.js";
+export interface ForgeOptions {
+    readonly actors?: readonly ActorDefinition[];
+    readonly projections?: readonly ProjectionDefinition<any>[];
+    readonly workflows?: readonly WorkflowDefinition[];
+    readonly externalCalls?: readonly ExternalCallDefinition<any, any>[];
+    /** Event names accepted from the bus / source chain. */
+    readonly externalEvents?: readonly string[];
+    readonly actorStore?: ActorStore;
+    readonly projectionStore?: ProjectionStore;
+    readonly idempotencyStore?: IdempotencyStore;
+    readonly workflowTimerStore?: WorkflowTimerStore;
+    readonly deadLetterSink?: DeadLetterSink;
+    readonly bus?: EventBus;
+    readonly publishToBus?: boolean;
+}
+/**
+ * Build the full forge plugin set. Order matters: idempotency (the dedup gate)
+ * first, then actions (binds the publish + action-runner other concerns use),
+ * then state concerns; queries after projections (it reads the store).
+ */
+export declare function forgePlugins(options?: ForgeOptions): PluginDefinition[];

package/dist/runtime/forge-plugins.js

@@ -0,0 +1,57 @@
+/**
+ * `forgePlugins(options)` — the batteries-included forge SET.
+ *
+ *   import { createApp } from "@nwire/app";
+ *   import { forgePlugins } from "@nwire/forge";
+ *
+ *   const app = createApp({
+ *     appName: "orders",
+ *     handlers: [placeOrder, sendReceipt, listOrders],  // actions + queries
+ *     plugins: [...forgePlugins({ actors, projections })],
+ *   });
+ *
+ * Handlers are NOT passed here — registration is the app's job. forge scans the
+ * runtime for `kind:"action"` / `kind:"query"` and wires each (command pipeline
+ * for actions, the read engine for queries).
+ *
+ * It is NOT a wrapping plugin — it returns the array of concern plugins so the
+ * composition stays a flat set you can see and trim. Install the concern
+ * plugins individually for an à-la-carte build; spread `forgePlugins()` for the
+ * full set. There is no parallel dispatcher — each plugin registers its
+ * primitives on the runtime, attaches its fold step to `LocalDelivery`, and
+ * contributes its own ctx verb.
+ */
+import { idempotencyPlugin } from "../plugins/idempotency-plugin.js";
+import { actionsPlugin } from "../plugins/actions-plugin.js";
+import { actorsPlugin } from "../plugins/actors-plugin.js";
+import { projectionsPlugin } from "../plugins/projections-plugin.js";
+import { queriesPlugin } from "../plugins/queries-plugin.js";
+import { workflowsPlugin } from "../plugins/workflows-plugin.js";
+import { externalCallsPlugin } from "../plugins/external-calls-plugin.js";
+/**
+ * Build the full forge plugin set. Order matters: idempotency (the dedup gate)
+ * first, then actions (binds the publish + action-runner other concerns use),
+ * then state concerns; queries after projections (it reads the store).
+ */
+export function forgePlugins(options = {}) {
+    return [
+        idempotencyPlugin({
+            idempotencyStore: options.idempotencyStore,
+            externalEvents: options.externalEvents,
+            bus: options.bus,
+        }),
+        actionsPlugin({
+            deadLetterSink: options.deadLetterSink,
+            bus: options.bus,
+            publishToBus: options.publishToBus,
+        }),
+        actorsPlugin(options.actors ?? [], { actorStore: options.actorStore }),
+        projectionsPlugin(options.projections ?? [], { projectionStore: options.projectionStore }),
+        queriesPlugin(),
+        workflowsPlugin(options.workflows ?? [], {
+            workflowTimerStore: options.workflowTimerStore,
+            bus: options.bus,
+        }),
+        externalCallsPlugin(options.externalCalls ?? []),
+    ];
+}

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

@@ -3,7 +3,7 @@
  * and the widened telemetry union forge emits.
  */
 import type { MessageEnvelope } from "@nwire/envelope";
-import type { SerializedError, HookStepTelemetry } from "@nwire/app";
+import type { SerializedError, Telemetry } from "@nwire/app";
 import type { ActionDefinition } from "../primitives/define-action.js";
 import type { ActorDefinition } from "../primitives/define-actor.js";
 import type { WorkflowDefinition } from "../primitives/define-workflow.js";
@@ -11,6 +11,12 @@ import type { HandlerContext } from "../primitives/define-handler.js";
 import type { EventMessage } from "../messages/event-message.js";
 export interface DispatchOptions {
     readonly signal?: AbortSignal;
+    /**
+     * A fully-minted envelope to dispatch under, used verbatim instead of
+     * deriving a fresh child. Lets a fire-and-forget `send` mint the child
+     * up-front so the `MessageRef` it returns names the same message.
+     */
+    readonly envelope?: MessageEnvelope;
 }
 /** `action.before:<name>` hook ctx. Set `vetoed = true` to cleanly skip the handler. */
 export interface ActionBeforeHookCtx {
@@ -42,7 +48,7 @@ export interface WorkflowFireHookCtx {
     readonly envelope: MessageEnvelope;
     readonly correlationKey: string;
 }
-export type ForgeTelemetry = HookStepTelemetry | {
+export type ForgeTelemetry = Telemetry | {
     kind: "action.dispatched";
     action: string;
     input: unknown;

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

@@ -1,26 +1,23 @@
 /**
- * `withForge(opts)` — App-transformer that installs forge.
- *
- * A plain function `App → App` that calls `app.with(createForgePlugin(opts))`
- * under the hood. Use it as the canonical install path for forge:
+ * `withForge(opts)` — App-transformer that installs the forge plugin set.
  *
  *   const app = withForge({
  *     actors: [Order],
  *     projections: [OrdersDashboard],
- *     actions: [placeOrder, sendReceipt],
+ *     handlers: [placeOrder, sendReceipt],
  *   })(createApp({ appName: "orders" }));
  *
- * Equivalent to writing the chain by hand:
+ * Equivalent to spreading the set by hand:
  *
- *   const app = createApp({ appName: "orders" })
- *     .with(createForgePlugin({ actors: [Order], ... }));
+ *   const app = createApp({ appName: "orders" });
+ *   for (const p of forgePlugins({ actors: [Order], ... })) app.with(p);
  *
  * Use whichever reads better at the call site.
  */
 import type { App } from "@nwire/app";
-import { type ForgePluginOptions } from "./forge-plugin.js";
+import { type ForgeOptions } from "./forge-plugins.js";
 /**
- * Returns an App transformer that installs forge into any App it's
+ * Returns an App transformer that installs the forge set into any App it's
  * applied to. The transformer preserves the existing `<TCaps>`.
  */
-export declare function withForge(opts?: ForgePluginOptions): <TCaps>(app: App<TCaps>) => App<TCaps>;
+export declare function withForge(opts?: ForgeOptions): <TCaps>(app: App<TCaps>) => App<TCaps>;

package/dist/runtime/with-forge.js

@@ -1,30 +1,28 @@
 /**
- * `withForge(opts)` — App-transformer that installs forge.
- *
- * A plain function `App → App` that calls `app.with(createForgePlugin(opts))`
- * under the hood. Use it as the canonical install path for forge:
+ * `withForge(opts)` — App-transformer that installs the forge plugin set.
  *
  *   const app = withForge({
  *     actors: [Order],
  *     projections: [OrdersDashboard],
- *     actions: [placeOrder, sendReceipt],
+ *     handlers: [placeOrder, sendReceipt],
  *   })(createApp({ appName: "orders" }));
  *
- * Equivalent to writing the chain by hand:
+ * Equivalent to spreading the set by hand:
  *
- *   const app = createApp({ appName: "orders" })
- *     .with(createForgePlugin({ actors: [Order], ... }));
+ *   const app = createApp({ appName: "orders" });
+ *   for (const p of forgePlugins({ actors: [Order], ... })) app.with(p);
  *
  * Use whichever reads better at the call site.
  */
-import { createForgePlugin } from "./forge-plugin.js";
+import { forgePlugins } from "./forge-plugins.js";
 /**
- * Returns an App transformer that installs forge into any App it's
+ * Returns an App transformer that installs the forge set into any App it's
  * applied to. The transformer preserves the existing `<TCaps>`.
  */
 export function withForge(opts = {}) {
     return (app) => {
-        app.with(createForgePlugin(opts));
+        for (const plugin of forgePlugins(opts))
+            app.with(plugin);
         return app;
     };
 }

package/dist/stores/idempotency-store.d.ts

@@ -24,7 +24,7 @@ export interface IdempotencyStore {
     }): void | Promise<void>;
     /**
      * Atomic check-and-record. Returns true on the first call for a given
-     * key and false on subsequent calls. Used by the EventPublishing
+     * key and false on subsequent calls. Used by the LocalDelivery
      * idempotency step to dedup correctly under concurrent publishes.
      *
      * Adapters backed by Redis / Postgres / etc. should implement this as

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nwire/forge",
-  "version": "0.12.1",
-  "description": "Nwire — the framework's core primitives. defineAction, defineEvent, defineHandler, defineActor, defineProjection, defineQuery, defineWorkflow, defineModule, defineApp, definePlugin, createApp. MessageEnvelope with correlation/causation. The runtime is the bus.",
+  "version": "0.13.1",
+  "description": "Nwire — the CQRS battery. Actors, projections, workflows, queries, and the action pipeline, plus outbox/inbox/cron, invariants, and DLQ wiring — installed via forgePlugins / withForge. Opt-in; an app boots without it. The runtime is the bus.",
   "keywords": [
     "actions",
     "actors",
@@ -34,16 +34,16 @@
     "emittery": "1.0.1",
     "koa": "^2.16.4",
     "zod": "^4.0.0",
-    "@nwire/bus": "0.12.1",
-    "@nwire/container": "0.12.1",
-    "@nwire/dead-letter": "0.12.1",
-    "@nwire/app": "0.12.1",
-    "@nwire/handler": "0.12.1",
-    "@nwire/envelope": "0.12.1",
-    "@nwire/hooks": "0.12.1",
-    "@nwire/logger": "0.12.1",
-    "@nwire/messages": "0.12.1",
-    "@nwire/wires": "0.12.1"
+    "@nwire/envelope": "0.13.1",
+    "@nwire/dead-letter": "0.13.1",
+    "@nwire/container": "0.13.1",
+    "@nwire/app": "0.13.1",
+    "@nwire/logger": "0.13.1",
+    "@nwire/wires": "0.13.1",
+    "@nwire/bus": "0.13.1",
+    "@nwire/hooks": "0.13.1",
+    "@nwire/messages": "0.13.1",
+    "@nwire/handler": "0.13.1"
   },
   "devDependencies": {
     "@types/koa": "^2.15.0",