@nwire/forge 0.11.0 → 0.12.0

package/dist/framework-events.d.ts

@@ -93,5 +93,6 @@ export declare const EVENT_PUBLISHING_PRIORITIES: {
     readonly projections: 600;
     readonly workflows: 400;
     readonly bus: 200;
+    readonly outbound: 100;
 };
 export type ForgeFrameworkSlot = (typeof forgeFrameworkSlots)[number];

package/dist/framework-events.js

@@ -29,4 +29,5 @@ export const EVENT_PUBLISHING_PRIORITIES = {
     projections: 600,
     workflows: 400,
     bus: 200,
+    outbound: 100,
 };

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

@@ -20,7 +20,7 @@ import { type Hook } from "@nwire/hooks";
 import { type MessageEnvelope } from "@nwire/envelope";
 import { type Runtime } from "@nwire/app";
 import type { WorkflowDefinition, WorkflowInstance, WorkflowEffects } from "../primitives/define-workflow.js";
-import type { EventMessage } from "../messages/event-message.js";
+import { type EventMessage } from "../messages/event-message.js";
 import type { WorkflowFireHookCtx } from "../runtime/forge-types.js";
 import type { WorkflowTimerStore } from "../stores/workflow-timer-store.js";
 /**

package/dist/plugins/workflows-chain.js

@@ -20,6 +20,7 @@ import { randomUUID } from "node:crypto";
 import { hook } from "@nwire/hooks";
 import { loggerForEnvelope } from "@nwire/logger";
 import { serializeError } from "@nwire/app";
+import { eventFactory } from "../messages/event-message.js";
 import { computeBackoff, parseDelay, sleep } from "../helpers/retry-helpers.js";
 export class WorkflowChainRunner {
     runtime;
@@ -88,6 +89,10 @@ export class WorkflowChainRunner {
                 const correlationKey = correlationKeyOverride ?? `${tenantPrefix}${userKey}`;
                 const fireCtx = {
                     ...baseEffects,
+                    envelope,
+                    emit: (eventDef, payload) => baseEffects.publish(eventFactory(eventDef)(payload)),
+                    resolve: (name) => this.runtime.resolve(name),
+                    logger: log,
                     load: (key) => store.get(key),
                     save: (key, instance) => store.set(key, instance),
                     drop: (key) => store.delete(key),

package/dist/primitives/define-workflow.d.ts

@@ -19,6 +19,8 @@
 import type { z } from "zod";
 import type { ZodTypeAny, SourceLocation } from "@nwire/messages";
 import type { EventDefinition, EventPayload } from "@nwire/messages";
+import type { MessageEnvelope } from "@nwire/envelope";
+import type { Logger } from "@nwire/logger";
 import type { ActionDefinition, ActionInput, ActionResult } from "./define-action.js";
 import type { EventMessage } from "../messages/event-message.js";
 import { type PublicMarker } from "../helpers/public-marker.js";
@@ -85,11 +87,13 @@ export type StateBody = () => Awaitable<Transition>;
  * `on()` returns are ignored (there's no state machine to transition).
  */
 export interface StatelessWorkflowContext extends WorkflowEffects {
-    on<E extends EventDefinition>(event: E, handler: (payload: EventPayload<E>) => Awaitable<Transition>, opts?: WorkflowOnOptions): void;
+    on<E extends EventDefinition>(event: E, handler: (payload: EventPayload<E>, ctx: WorkflowReactionContext) => Awaitable<Transition>, opts?: WorkflowOnOptions): void;
     /** Subscribe to the `complete` pseudo-event. Fires after each handler. */
     on(event: CompleteEvent, handler: () => Awaitable<void>, opts?: WorkflowOnOptions): void;
     /** Subscribe to a saga timer fire. */
-    on(event: TimerDefinition, handler: (payload?: unknown) => Awaitable<Transition>, opts?: WorkflowOnOptions): void;
+    on(event: TimerDefinition, handler: (payload: unknown, ctx: WorkflowReactionContext) => Awaitable<Transition>, opts?: WorkflowOnOptions): void;
+    /** Canonical event verb — alias of `on`. Prefer `when`; `on` is retained for now. */
+    when: StatelessWorkflowContext["on"];
 }
 /**
  * Stateful workflow context — adds `data`, `assign`, `states`, and the
@@ -174,6 +178,19 @@ export interface WorkflowDefinition extends PublicMarker {
  * and run effects. Supplied by the kernel-side runtime.
  */
 export interface FireContext extends WorkflowEffects {
+    /** The triggering event's envelope. Threaded onto the reaction ctx. */
+    readonly envelope: MessageEnvelope;
+    /** Publish an event by definition + payload (listener-parity `emit`). */
+    readonly emit: (event: EventDefinition & {
+        readonly name: string;
+        readonly schema: {
+            parse(input: unknown): unknown;
+        };
+    }, payload: unknown) => Promise<void>;
+    /** Resolve a dependency from the container. */
+    readonly resolve: <T = unknown>(name: string) => T;
+    /** The envelope-scoped logger. */
+    readonly logger: Logger;
     /** Load or create the instance row for this correlation key. */
     readonly load: (key: string) => WorkflowInstance | undefined;
     readonly save: (key: string, instance: WorkflowInstance) => void;
@@ -199,6 +216,31 @@ export interface WorkflowInstance {
     /** Names of events the current state has registered handlers for. */
     scopedEvents: string[];
 }
+/**
+ * Reaction context handed to a `when` handler as its second argument. The
+ * listener-subset (`envelope` · `send` · `emit` · `resolve` · `logger`) is
+ * identical to `ListenerContext`, so a `when(Event, (payload, ctx) => …)`
+ * block written for a listener runs unchanged here; the workflow adds
+ * `enqueue` · `publish` · `assign` · `schedule`.
+ */
+export interface WorkflowReactionContext {
+    readonly envelope: MessageEnvelope;
+    send<A extends ActionDefinition>(action: A, input: ActionInput<A>): Promise<ActionResult<A>>;
+    emit<E extends EventDefinition & {
+        readonly name: string;
+        readonly schema: {
+            parse(input: unknown): unknown;
+        };
+    }>(event: E, payload: EventPayload<E>): Promise<void>;
+    resolve<T = unknown>(name: string): T;
+    readonly logger: Logger;
+    enqueue<A extends ActionDefinition>(action: A, input: ActionInput<A>): Promise<void>;
+    publish(event: EventMessage): Promise<void>;
+    /** Stateful only — merge a patch into the instance data. No-op when stateless. */
+    assign(patch: Record<string, unknown>): Promise<void>;
+    /** Stateful only — enqueue a declared timer. No-op when stateless. */
+    schedule(timer: TimerDefinition, payload?: unknown): Promise<void>;
+}
 /**
  * Stateful overload — when `options.data` is declared, the closure
  * receives a `StatefulWorkflowContext` with `data`, `assign`, `states`,

package/dist/primitives/define-workflow.js

@@ -81,6 +81,7 @@ closure, options) {
     const probeCtx = stateful
         ? {
             on: probeOn,
+            when: probeOn,
             send: async () => undefined,
             enqueue: async () => undefined,
             publish: async () => undefined,
@@ -93,6 +94,7 @@ closure, options) {
         }
         : {
             on: probeOn,
+            when: probeOn,
             send: async () => undefined,
             enqueue: async () => undefined,
             publish: async () => undefined,
@@ -164,24 +166,43 @@ closure, options) {
 async function fireStateless({ closure, event, fireCtx, completeMarker, }) {
     const matched = [];
     const completeHandlers = [];
+    const register = ((subscribedEvent, handler) => {
+        const eventName = subscribedEvent.name;
+        if (eventName === completeMarker.name) {
+            completeHandlers.push(handler);
+            return;
+        }
+        if (eventName === event.eventName) {
+            matched.push(handler);
+        }
+    });
     const ctx = {
-        on: ((subscribedEvent, handler) => {
-            const eventName = subscribedEvent.name;
-            if (eventName === completeMarker.name) {
-                completeHandlers.push(handler);
-                return;
-            }
-            if (eventName === event.eventName) {
-                matched.push(handler);
-            }
-        }),
+        on: register,
+        when: register,
         send: fireCtx.send,
         enqueue: fireCtx.enqueue,
         publish: fireCtx.publish,
     };
     closure(ctx);
+    // Reaction ctx — the listener-subset + workflow effects. Stateless, so
+    // assign/schedule are no-ops (no per-correlation instance or timers).
+    const reactionCtx = {
+        envelope: fireCtx.envelope,
+        send: fireCtx.send,
+        emit: fireCtx.emit,
+        resolve: fireCtx.resolve,
+        logger: fireCtx.logger,
+        enqueue: fireCtx.enqueue,
+        publish: fireCtx.publish,
+        assign: async () => {
+            fireCtx.logger.warn?.("ctx.assign() is a no-op in a stateless workflow — declare `data` to make it stateful, or move this reaction to a listener.");
+        },
+        schedule: async () => {
+            fireCtx.logger.warn?.("ctx.schedule() is a no-op in a stateless workflow — declare `data`/`states` to use timers.");
+        },
+    };
     for (const h of matched) {
-        await h(event.payload);
+        await h(event.payload, reactionCtx);
     }
     // `complete` for a stateless workflow fires after each successful event.
     if (matched.length > 0) {
@@ -248,6 +269,7 @@ async function fireStateful(args) {
     };
     const ctx = {
         on: onImpl,
+        when: onImpl,
         async send(action, input) {
             if (scope.kind === "collect")
                 return undefined;
@@ -322,7 +344,25 @@ async function fireStateful(args) {
         fireCtx.save(key, instance);
         return;
     }
-    const next = await chosen.handler(event.payload);
+    // Reaction ctx — listener-subset + workflow effects. assign/schedule
+    // do the real per-instance work (handlers run in global scope here).
+    const reactionCtx = {
+        envelope: fireCtx.envelope,
+        send: fireCtx.send,
+        emit: fireCtx.emit,
+        resolve: fireCtx.resolve,
+        logger: fireCtx.logger,
+        enqueue: fireCtx.enqueue,
+        publish: fireCtx.publish,
+        async assign(patch) {
+            instance.data = { ...instance.data, ...patch };
+            fireCtx.save(key, instance);
+        },
+        async schedule(timer, payload) {
+            await fireCtx.scheduleTimer(timer.name, timer.delay, payload);
+        },
+    };
+    const next = await chosen.handler(event.payload, reactionCtx);
     // Persist any assign() effects before the transition.
     fireCtx.save(key, instance);
     if (next && typeof next === "string" && stateSpecs[next]) {

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

@@ -153,6 +153,9 @@ export declare class ForgeDispatcher {
      *    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.

package/dist/runtime/forge-dispatcher.js

@@ -27,7 +27,7 @@ import { InMemoryActorStore, createInitialInstance, ActorVersionConflictError, }
 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 { normalizeEventReturn, eventFactory } from "../messages/event-message.js";
 import { EVENT_PUBLISHING_PRIORITIES } from "../framework-events.js";
 export class ForgeDispatcher {
     runtime;
@@ -116,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)) {
@@ -630,6 +641,9 @@ export class ForgeDispatcher {
      *    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.
@@ -667,6 +681,16 @@ export class ForgeDispatcher {
             }
             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)) {
@@ -921,6 +945,14 @@ export class ForgeDispatcher {
                 const correlationKey = correlationKeyOverride ?? `${tenantPrefix}${userKey}`;
                 const fireCtx = {
                     ...baseEffects,
+                    envelope,
+                    // Local publish through the forge chain — fans out to in-process
+                    // reactions; the outbound stage drains it to a sink only if the
+                    // event is .public() and a sink is installed. Built via the event
+                    // factory so messageId / correlation / idempotency hold.
+                    emit: (eventDef, payload) => self.publish([eventFactory(eventDef)(payload)], envelope),
+                    resolve: (name) => handlerCtx.resolve(name),
+                    logger: log,
                     load: (key) => store.get(key),
                     save: (key, instance) => store.set(key, instance),
                     drop: (key) => store.delete(key),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/forge",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "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.",
   "keywords": [
     "actions",
@@ -34,16 +34,16 @@
     "emittery": "1.0.1",
     "koa": "^2.16.4",
     "zod": "^4.0.0",
-    "@nwire/app": "0.11.0",
-    "@nwire/bus": "0.11.0",
-    "@nwire/dead-letter": "0.11.0",
-    "@nwire/handler": "0.11.0",
-    "@nwire/container": "0.11.0",
-    "@nwire/messages": "0.11.0",
-    "@nwire/wires": "0.11.0",
-    "@nwire/logger": "0.11.0",
-    "@nwire/envelope": "0.11.0",
-    "@nwire/hooks": "0.11.0"
+    "@nwire/app": "0.12.0",
+    "@nwire/bus": "0.12.0",
+    "@nwire/container": "0.12.0",
+    "@nwire/dead-letter": "0.12.0",
+    "@nwire/envelope": "0.12.0",
+    "@nwire/hooks": "0.12.0",
+    "@nwire/messages": "0.12.0",
+    "@nwire/handler": "0.12.0",
+    "@nwire/wires": "0.12.0",
+    "@nwire/logger": "0.12.0"
   },
   "devDependencies": {
     "@types/koa": "^2.15.0",