@nwire/forge 0.10.0 → 0.11.0

package/dist/framework-events.d.ts

@@ -14,8 +14,26 @@
  * domain-specific slots.
  */
 import type { Hook } from "@nwire/hooks";
+import type { MessageEnvelope } from "@nwire/envelope";
 import type { ActionDefinition } from "./primitives/define-action.js";
 import type { HandlerContext } from "./primitives/define-handler.js";
+import type { EventMessage } from "./messages/event-message.js";
+/**
+ * Payload threaded through the `EventPublishing` hook chain. Each chain
+ * step does its work for one event in order. Steps may set `deduped` to
+ * short-circuit (idempotency), or read it to skip work when an earlier
+ * step already deduplicated.
+ *
+ * Mutable so steps can flag deduplication without restructuring the
+ * chain return shape.
+ */
+export interface EventPublishingPayload {
+    readonly event: EventMessage;
+    readonly envelope: MessageEnvelope;
+    readonly dedupKey: string;
+    /** Set by the idempotency step when this event was seen before. */
+    deduped: boolean;
+}
 declare module "@nwire/app" {
     interface FrameworkHooks {
         /** Fired before a dispatch reaches the handler. Veto by skipping next(). */
@@ -48,8 +66,32 @@ declare module "@nwire/app" {
             readonly eventName: string;
             readonly payload: unknown;
         }>;
+        /**
+         * The atomic event-publish chain. Each domain concern attaches one
+         * `.use()` step at its priority slot; the hook engine enforces the
+         * order. Priority slots used by forge:
+         *
+         *   1000 — idempotency (dedup gate; short-circuits when seen)
+         *    800 — actor state transitions
+         *    600 — projection folds
+         *    400 — workflow correlation + fire
+         *    200 — cross-process bus delivery (public events only)
+         *
+         * External plugins can attach at intermediate priorities to inject
+         * domain-specific work (audit log, cross-tenant fan-out, etc.) while
+         * preserving the forge ordering.
+         */
+        EventPublishing: Hook<EventPublishingPayload>;
     }
 }
-/** Forge-specific framework-hook slot names — used by Runtime to materialise. */
-export declare const forgeFrameworkSlots: readonly ["ActionDispatching", "ActionCompleted", "ActionFailed", "EventRecording", "EventRecorded"];
+/** Forge-specific framework-hook slot names — materialised by `createForgePlugin`. */
+export declare const forgeFrameworkSlots: readonly ["ActionDispatching", "ActionCompleted", "ActionFailed", "EventRecording", "EventRecorded", "EventPublishing"];
+/** Priority slots forge's own chain participants attach at. */
+export declare const EVENT_PUBLISHING_PRIORITIES: {
+    readonly idempotency: 1000;
+    readonly actors: 800;
+    readonly projections: 600;
+    readonly workflows: 400;
+    readonly bus: 200;
+};
 export type ForgeFrameworkSlot = (typeof forgeFrameworkSlots)[number];

package/dist/framework-events.js

@@ -13,11 +13,20 @@
  * are pre-instantiated on every Runtime; this file only adds forge's
  * domain-specific slots.
  */
-/** Forge-specific framework-hook slot names — used by Runtime to materialise. */
+/** Forge-specific framework-hook slot names — materialised by `createForgePlugin`. */
 export const forgeFrameworkSlots = [
     "ActionDispatching",
     "ActionCompleted",
     "ActionFailed",
     "EventRecording",
     "EventRecorded",
+    "EventPublishing",
 ];
+/** Priority slots forge's own chain participants attach at. */
+export const EVENT_PUBLISHING_PRIORITIES = {
+    idempotency: 1000,
+    actors: 800,
+    projections: 600,
+    workflows: 400,
+    bus: 200,
+};

package/dist/helpers/cli-runner.d.ts

@@ -33,7 +33,7 @@
  * Wire-mode invariance: same domain handlers run in HTTP, queue, and CLI.
  * The CLI doesn't know about HTTP routes; it dispatches via the runtime.
  */
-import type { ForgeApp as App } from "../runtime/create-forge-app.js";
+import type { App } from "@nwire/app";
 export interface RunCliOptions {
     /**
      * Override stdout/stderr — useful for tests. Defaults to console.log /

package/dist/helpers/cli-runner.js

@@ -34,6 +34,7 @@
  * The CLI doesn't know about HTTP routes; it dispatches via the runtime.
  */
 import { seedEnvelope } from "@nwire/envelope";
+import { forgeDispatcher } from "../runtime/forge-plugin.js";
 export async function runCli(app, argv, options = {}) {
     const stdout = options.stdout ?? ((line) => console.log(line));
     const stderr = options.stderr ?? ((line) => console.error(line));
@@ -43,14 +44,14 @@ export async function runCli(app, argv, options = {}) {
     }
     const targetName = argv[0];
     const rest = argv.slice(1);
-    const dispatcher = app.dispatcher();
+    const dispatcher = forgeDispatcher(app);
     const action = dispatcher.findActionByName(targetName);
     if (action) {
         const { tenant, parsed } = parseFlags(rest);
         try {
             const validated = action.schema.parse(parsed);
             const envelope = tenant ? seedEnvelope({ tenant }) : undefined;
-            await app.dispatch(action, validated, envelope);
+            await dispatcher.dispatch(action, validated, envelope);
             stdout("OK");
             return 0;
         }
@@ -63,7 +64,7 @@ export async function runCli(app, argv, options = {}) {
     if (dispatcher.listQueries().includes(targetName)) {
         const { tenant, parsed } = parseFlags(rest);
         try {
-            const result = await app.query(targetName, parsed, tenant);
+            const result = await dispatcher.query(targetName, parsed, tenant);
             stdout(JSON.stringify(result, null, 2));
             return 0;
         }
@@ -76,7 +77,7 @@ export async function runCli(app, argv, options = {}) {
     return 1;
 }
 function printHelp(app, stdout) {
-    const dispatcher = app.dispatcher();
+    const dispatcher = forgeDispatcher(app);
     stdout("nwire — action CLI runner\n");
     stdout("Usage: amit <action-or-query-name> [--field value ...] [--tenant <id>]\n");
     stdout("Actions:");

package/dist/index.d.ts

@@ -2,21 +2,33 @@
  * `@nwire/forge` — CQRS engine delivered as an app plugin.
  *
  *   import { createApp } from "@nwire/app";
- *   import { forgePlugin } from "@nwire/forge";
+ *   import { createForgePlugin, forgeDispatcher } from "@nwire/forge";
  *
- *   const app = createApp({ appName: "orders", plugins: [forgePlugin, …] });
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [createForgePlugin({ handlers, actors, projections, … })],
+ *   });
+ *   await app.start();
  *
- * Or via the convenience wrapper that auto-installs forgePlugin and adds
- * the dispatch/publish/query/… verbs as methods on the app handle:
- *
- *   import { createForgeApp } from "@nwire/forge";
- *
- *   const app = createForgeApp({ name: "orders", handlers, actors, … });
+ *   const dispatcher = forgeDispatcher(app);
+ *   await dispatcher.dispatch(placeOrder, { … });
  */
-export { forgePlugin, createForgePlugin, FORGE_DISPATCHER_BINDING, } from "./runtime/forge-plugin.js";
+export { forgePlugin, createForgePlugin, forgeDispatcher, type ForgePluginOptions, FORGE_DISPATCHER_BINDING, } from "./runtime/forge-plugin.js";
+export { withForge } from "./runtime/with-forge.js";
+export { actorsPlugin, FORGE_ACTOR_CHAIN_BINDING, FORGE_ACTOR_STORE_BINDING, type ActorsPluginOptions, } from "./plugins/actors-plugin.js";
+export { ActorChainRunner, type ActorTransitionListener } from "./plugins/actors-chain.js";
+export { projectionsPlugin, FORGE_PROJECTION_CHAIN_BINDING, FORGE_PROJECTION_STORE_BINDING, type ProjectionsPluginOptions, } from "./plugins/projections-plugin.js";
+export { ProjectionChainRunner } from "./plugins/projections-chain.js";
+export { workflowsPlugin, FORGE_WORKFLOW_CHAIN_BINDING, FORGE_WORKFLOW_TIMER_STORE_BINDING, type WorkflowsPluginOptions, } from "./plugins/workflows-plugin.js";
+export { WorkflowChainRunner, type WorkflowEffectsFactory } from "./plugins/workflows-chain.js";
+export { queriesPlugin, FORGE_QUERY_RUNNER_BINDING } from "./plugins/queries-plugin.js";
+export { QueryRunner } from "./plugins/queries-chain.js";
+export { actionsPlugin, FORGE_ACTION_RUNNER_BINDING, FORGE_DEAD_LETTER_SINK_BINDING, type ActionsPluginOptions, } from "./plugins/actions-plugin.js";
+export { ActionRunner, type PublishEventsFn, type CtxAugmenter } from "./plugins/actions-chain.js";
+export { idempotencyPlugin, FORGE_IDEMPOTENCY_STORE_BINDING, type IdempotencyPluginOptions, } from "./plugins/idempotency-plugin.js";
+export { dlqPlugin, type DlqPluginOptions } from "./plugins/dlq-plugin.js";
 export { ForgeDispatcher, type ForgeDispatcherOptions } from "./runtime/forge-dispatcher.js";
 export type { ForgeTelemetry, DispatchOptions, ActionBeforeHookCtx, ActionAfterHookCtx, ActorTransitionHookCtx, WorkflowFireHookCtx, } from "./runtime/forge-types.js";
-export { createForgeApp, type ForgeApp, type ForgeAppOptions, } from "./runtime/create-forge-app.js";
 export { defineAction, isCommandMessage, resolveDispatch, type ActionDefinition, type CallableActionDefinition, type CommandMessage, type ActionMeta, type ActionInput, type ActionResult, type ActionPolicy, type NwireActionRegistry, type RetryPolicy, } from "./primitives/define-action.js";
 export { defineActor, eventKey, type ActorDefinition, type ActorOptions, type ActorOptionsBound, type ActorReaction, type ActorStateConfig, type ActorTimerSpec, type ActorMethod, type ActorInstanceView, } from "./primitives/define-actor.js";
 export { defineSchema, isSchemaDefinition, type SchemaDefinition, type SchemaOptions, type SchemaStateSpec, type SchemaStorageHints, } from "./primitives/define-schema.js";
@@ -26,7 +38,7 @@ export { eventFactory, isEventMessage, normalizeEventReturn, type EventMessage,
 export { defineWorkflow, COMPLETE_EVENT_NAME, type WorkflowDefinition, type WorkflowContext, type StatelessWorkflowContext, type StatefulWorkflowContext, type WorkflowEffects, type WorkflowOptions, type StatelessWorkflowOptions, type StatefulWorkflowOptions, type WorkflowOnOptions, type WorkflowRetryPolicy, type WorkflowStateSpec, type WorkflowInstance, type WorkflowCorrelateMap, type FireContext, type CompleteEvent, type StateCallable, type TimerDefinition, } from "./primitives/define-workflow.js";
 export { defineProjection, type ProjectionDefinition, type ProjectionOptions, type ProjectionReducer, } from "./primitives/define-projection.js";
 export { defineQuery, type QueryDefinition, type QueryOptions } from "./primitives/define-query.js";
-export { defineUpcaster, applyUpcasters, type UpcasterDefinition } from "./primitives/define-upcaster.js";
+export { defineUpcaster, applyUpcasters, type UpcasterDefinition, } from "./primitives/define-upcaster.js";
 export { defineExternalCall, type ExternalCallDefinition, type ExternalCallMeta, type ExternalCallTarget, type ExternalCallSlo, type ExternalCallRetry, type ExternalCallExecutor, } from "./primitives/define-external-call.js";
 export { defineInboundWebhook, type InboundWebhookDefinition, type InboundWebhookMeta, type WebhookSignatureVerifier, type WebhookDedupe, } from "./primitives/define-inbound-webhook.js";
 export { defineOutbox, type OutboxDefinition, type OutboxMeta } from "./primitives/define-outbox.js";
@@ -39,11 +51,11 @@ export { InMemoryIdempotencyStore, type IdempotencyStore } from "./stores/idempo
 export { InMemoryWorkflowTimerStore, timerEventName, type WorkflowTimer, type WorkflowTimerStore, } from "./stores/workflow-timer-store.js";
 export { parseDelay } from "./helpers/retry-helpers.js";
 export { isPublic, type PublicMarker } from "./helpers/public-marker.js";
-export { attachDevLogger, formatTelemetry, type DevLoggerOptions } from "./observability/dev-logger.js";
+export { attachDevLogger, formatTelemetry, type DevLoggerOptions, } from "./observability/dev-logger.js";
 export { runCli, type RunCliOptions } from "./helpers/cli-runner.js";
 export { NoopLogger, ConsoleLogger, loggerForEnvelope, type Logger } from "@nwire/logger";
 export { InMemoryDeadLetterSink, buildDeadLetterEntry, type DeadLetterSink, type DeadLetterEntry, } from "@nwire/dead-letter";
 export { defineResource, isResourceDefinition, type ResourceDefinition, type DefineResourceOptions, } from "@nwire/handler";
 export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, type ResponseSpec, type ListResponseSpec, type ResponseInstance, type ResponseKind, } from "./helpers/response.js";
-import "./framework-events";
+import "./framework-events.js";
 export type { FrameworkHooks, PluginKind } from "@nwire/app";

package/dist/index.js

@@ -2,21 +2,33 @@
  * `@nwire/forge` — CQRS engine delivered as an app plugin.
  *
  *   import { createApp } from "@nwire/app";
- *   import { forgePlugin } from "@nwire/forge";
+ *   import { createForgePlugin, forgeDispatcher } from "@nwire/forge";
  *
- *   const app = createApp({ appName: "orders", plugins: [forgePlugin, …] });
+ *   const app = createApp({
+ *     appName: "orders",
+ *     plugins: [createForgePlugin({ handlers, actors, projections, … })],
+ *   });
+ *   await app.start();
  *
- * Or via the convenience wrapper that auto-installs forgePlugin and adds
- * the dispatch/publish/query/… verbs as methods on the app handle:
- *
- *   import { createForgeApp } from "@nwire/forge";
- *
- *   const app = createForgeApp({ name: "orders", handlers, actors, … });
+ *   const dispatcher = forgeDispatcher(app);
+ *   await dispatcher.dispatch(placeOrder, { … });
  */
 // ─── Plugin + composition ──────────────────────────────────────────
-export { forgePlugin, createForgePlugin, FORGE_DISPATCHER_BINDING, } from "./runtime/forge-plugin.js";
+export { forgePlugin, createForgePlugin, forgeDispatcher, FORGE_DISPATCHER_BINDING, } from "./runtime/forge-plugin.js";
+export { withForge } from "./runtime/with-forge.js";
+export { actorsPlugin, FORGE_ACTOR_CHAIN_BINDING, FORGE_ACTOR_STORE_BINDING, } from "./plugins/actors-plugin.js";
+export { ActorChainRunner } from "./plugins/actors-chain.js";
+export { projectionsPlugin, FORGE_PROJECTION_CHAIN_BINDING, FORGE_PROJECTION_STORE_BINDING, } from "./plugins/projections-plugin.js";
+export { ProjectionChainRunner } from "./plugins/projections-chain.js";
+export { workflowsPlugin, FORGE_WORKFLOW_CHAIN_BINDING, FORGE_WORKFLOW_TIMER_STORE_BINDING, } from "./plugins/workflows-plugin.js";
+export { WorkflowChainRunner } from "./plugins/workflows-chain.js";
+export { queriesPlugin, FORGE_QUERY_RUNNER_BINDING } from "./plugins/queries-plugin.js";
+export { QueryRunner } from "./plugins/queries-chain.js";
+export { actionsPlugin, FORGE_ACTION_RUNNER_BINDING, FORGE_DEAD_LETTER_SINK_BINDING, } from "./plugins/actions-plugin.js";
+export { ActionRunner } from "./plugins/actions-chain.js";
+export { idempotencyPlugin, FORGE_IDEMPOTENCY_STORE_BINDING, } from "./plugins/idempotency-plugin.js";
+export { dlqPlugin } from "./plugins/dlq-plugin.js";
 export { ForgeDispatcher } from "./runtime/forge-dispatcher.js";
-export { createForgeApp, } from "./runtime/create-forge-app.js";
 // ─── Domain primitives ─────────────────────────────────────────────
 export { defineAction, isCommandMessage, resolveDispatch, } from "./primitives/define-action.js";
 export { defineActor, eventKey, } from "./primitives/define-actor.js";
@@ -27,7 +39,7 @@ export { eventFactory, isEventMessage, normalizeEventReturn, } from "./messages/
 export { defineWorkflow, COMPLETE_EVENT_NAME, } from "./primitives/define-workflow.js";
 export { defineProjection, } from "./primitives/define-projection.js";
 export { defineQuery } from "./primitives/define-query.js";
-export { defineUpcaster, applyUpcasters } from "./primitives/define-upcaster.js";
+export { defineUpcaster, applyUpcasters, } from "./primitives/define-upcaster.js";
 export { defineExternalCall, } from "./primitives/define-external-call.js";
 export { defineInboundWebhook, } from "./primitives/define-inbound-webhook.js";
 export { defineOutbox } from "./primitives/define-outbox.js";
@@ -42,7 +54,7 @@ export { InMemoryWorkflowTimerStore, timerEventName, } from "./stores/workflow-t
 // ─── Helpers ───────────────────────────────────────────────────────
 export { parseDelay } from "./helpers/retry-helpers.js";
 export { isPublic } from "./helpers/public-marker.js";
-export { attachDevLogger, formatTelemetry } from "./observability/dev-logger.js";
+export { attachDevLogger, formatTelemetry, } from "./observability/dev-logger.js";
 export { runCli } from "./helpers/cli-runner.js";
 // ─── Re-exports from neighbours ────────────────────────────────────
 export { NoopLogger, ConsoleLogger, loggerForEnvelope } from "@nwire/logger";
@@ -51,4 +63,4 @@ export { defineResource, isResourceDefinition, } from "@nwire/handler";
 export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, } from "./helpers/response.js";
 // Module augmentation side effect — adds Action* / Event* slots to
 // FrameworkHooks on @nwire/app's runtime.
-import "./framework-events";
+import "./framework-events.js";

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

@@ -0,0 +1,48 @@
+/**
+ * Action runner — handler registry + dispatch loop.
+ *
+ * Owns the per-action retry policy, DLQ integration, and the
+ * `action.dispatched` / `action.completed` / `action.failed` / `dlq.recorded`
+ * telemetry. Calls `runtime.hooks.ActionDispatching` (vetoable),
+ * `ActionCompleted`, and `ActionFailed` at the right transitions.
+ *
+ * The runner builds a handler ctx with `resolve`, `request`, `send`, and
+ * `query` wired through the container. Returned events from the handler
+ * flow into the `EventPublishing` chain via the injected `publishEvents`
+ * callback.
+ */
+import { type Runtime } from "@nwire/app";
+import { type MessageEnvelope } from "@nwire/envelope";
+import { type Hook } from "@nwire/hooks";
+import type { Container } from "@nwire/container";
+import { type DeadLetterSink } from "@nwire/dead-letter";
+import type { ActionDefinition, ActionInput, ActionResult } from "../primitives/define-action.js";
+import type { HandlerContext, HandlerDefinition } from "../primitives/define-handler.js";
+import type { ActionBeforeHookCtx, ActionAfterHookCtx, DispatchOptions } from "../runtime/forge-types.js";
+import { type EventMessage } from "../messages/event-message.js";
+/** Publish callback — injected so the runner doesn't know about the chain hook directly. */
+export type PublishEventsFn = (events: readonly EventMessage[], envelope: MessageEnvelope) => Promise<void>;
+/** Optional ctx augmenter — actorsPlugin / externalCallsPlugin can extend ctx.use etc. */
+export type CtxAugmenter = (ctx: HandlerContext, envelope: MessageEnvelope) => void;
+export declare class ActionRunner {
+    private readonly runtime;
+    private readonly container;
+    private readonly deadLetterSink;
+    private readonly publishEvents;
+    readonly handlers: Map<string, HandlerDefinition<any>>;
+    readonly beforeHooks: Map<string, Hook<ActionBeforeHookCtx>>;
+    readonly afterHooks: Map<string, Hook<ActionAfterHookCtx>>;
+    readonly augmenters: CtxAugmenter[];
+    constructor(runtime: Runtime, container: Container, deadLetterSink: DeadLetterSink, publishEvents: PublishEventsFn);
+    register(handler: HandlerDefinition<any>): void;
+    /** Action handler names, in registration order. */
+    listHandlers(): readonly string[];
+    findActionByName(name: string): ActionDefinition<any> | undefined;
+    ensureBeforeHook(name: string): Hook<ActionBeforeHookCtx>;
+    ensureAfterHook(name: string): Hook<ActionAfterHookCtx>;
+    /** Plugins can hang extra ctx members on each handler invocation. */
+    registerCtxAugmenter(fn: CtxAugmenter): void;
+    dispatch<A extends ActionDefinition>(action: A, input: ActionInput<A>, parentEnvelope?: MessageEnvelope, opts?: DispatchOptions): Promise<ActionResult<A>>;
+    /** Build the handler ctx for one dispatch. */
+    private buildHandlerContext;
+}

package/dist/plugins/actions-chain.js

@@ -0,0 +1,251 @@
+/**
+ * Action runner — handler registry + dispatch loop.
+ *
+ * Owns the per-action retry policy, DLQ integration, and the
+ * `action.dispatched` / `action.completed` / `action.failed` / `dlq.recorded`
+ * telemetry. Calls `runtime.hooks.ActionDispatching` (vetoable),
+ * `ActionCompleted`, and `ActionFailed` at the right transitions.
+ *
+ * The runner builds a handler ctx with `resolve`, `request`, `send`, and
+ * `query` wired through the container. Returned events from the handler
+ * flow into the `EventPublishing` chain via the injected `publishEvents`
+ * callback.
+ */
+import { serializeError } from "@nwire/app";
+import { deriveEnvelope, seedEnvelope } from "@nwire/envelope";
+import { loggerForEnvelope } from "@nwire/logger";
+import { isValidated, markValidated } from "@nwire/messages";
+import { hook } from "@nwire/hooks";
+import { buildDeadLetterEntry } from "@nwire/dead-letter";
+import { normalizeEventReturn } from "../messages/event-message.js";
+import { computeBackoff, sleep } from "../helpers/retry-helpers.js";
+export class ActionRunner {
+    runtime;
+    container;
+    deadLetterSink;
+    publishEvents;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handlers = new Map();
+    beforeHooks = new Map();
+    afterHooks = new Map();
+    augmenters = [];
+    constructor(runtime, container, deadLetterSink, publishEvents) {
+        this.runtime = runtime;
+        this.container = container;
+        this.deadLetterSink = deadLetterSink;
+        this.publishEvents = publishEvents;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    register(handler) {
+        if (this.handlers.has(handler.action.name)) {
+            throw new Error(`actionsPlugin: handler for action "${handler.action.name}" already registered.`);
+        }
+        this.handlers.set(handler.action.name, handler);
+        this.ensureBeforeHook(handler.action.name);
+        this.ensureAfterHook(handler.action.name);
+    }
+    /** Action handler names, in registration order. */
+    listHandlers() {
+        return [...this.handlers.keys()];
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    findActionByName(name) {
+        return this.handlers.get(name)?.action;
+    }
+    ensureBeforeHook(name) {
+        let h = this.beforeHooks.get(name);
+        if (h)
+            return h;
+        h = hook(`action.before:${name}`);
+        this.beforeHooks.set(name, h);
+        return h;
+    }
+    ensureAfterHook(name) {
+        let h = this.afterHooks.get(name);
+        if (h)
+            return h;
+        h = hook(`action.after:${name}`);
+        this.afterHooks.set(name, h);
+        return h;
+    }
+    /** Plugins can hang extra ctx members on each handler invocation. */
+    registerCtxAugmenter(fn) {
+        this.augmenters.push(fn);
+    }
+    async dispatch(action, input, parentEnvelope, opts) {
+        const handler = this.handlers.get(action.name);
+        if (!handler) {
+            throw new Error(`actionsPlugin: no handler registered for action "${action.name}".`);
+        }
+        const appName = this.runtime.appName;
+        const envelope = parentEnvelope ? deriveEnvelope(parentEnvelope) : seedEnvelope({});
+        const validated = isValidated(input) ? input : markValidated(action.schema.parse(input));
+        const log = loggerForEnvelope(this.runtime.logger, envelope);
+        const signal = opts?.signal ?? new AbortController().signal;
+        const ctx = this.buildHandlerContext(envelope, signal);
+        this.runtime.pushTelemetry({
+            kind: "action.dispatched",
+            action: action.name,
+            input: validated,
+            envelope,
+            appName,
+            ts: new Date().toISOString(),
+        });
+        const startedAt = performance.now();
+        const dispatchResult = await this.runtime.hooks.ActionDispatching.runDetailed({
+            action,
+            input: validated,
+            ctx,
+        });
+        if (dispatchResult.outcome === "failed")
+            throw dispatchResult.error;
+        if (dispatchResult.outcome !== "completed")
+            return undefined;
+        const beforeHook = this.beforeHooks.get(action.name);
+        if (beforeHook) {
+            const beforeCtx = { action, input: validated, ctx };
+            await beforeHook.run(beforeCtx);
+            if (beforeCtx.vetoed)
+                return undefined;
+        }
+        const retry = action.retry;
+        const maxAttempts = 1 + (retry?.max ?? 0);
+        let attempt = 0;
+        let lastError;
+        while (attempt < maxAttempts) {
+            attempt++;
+            if (attempt > 1 && signal.aborted) {
+                throw lastError;
+            }
+            try {
+                if (attempt > 1) {
+                    const delay = computeBackoff(retry, attempt - 1);
+                    if (delay > 0)
+                        await sleep(delay);
+                }
+                const rawResult = await handler.handler(validated, ctx);
+                const events = normalizeEventReturn(rawResult ?? null);
+                if (events.length > 0) {
+                    await this.publishEvents(events, envelope);
+                }
+                const durationMs = performance.now() - startedAt;
+                this.runtime.pushTelemetry({
+                    kind: "action.completed",
+                    action: action.name,
+                    durationMs,
+                    emittedEvents: events.map((e) => e.eventName),
+                    envelope,
+                    appName,
+                    ts: new Date().toISOString(),
+                });
+                const afterHook = this.afterHooks.get(action.name);
+                if (afterHook) {
+                    try {
+                        await afterHook.run({
+                            action,
+                            input: validated,
+                            result: rawResult ?? undefined,
+                            durationMs,
+                        });
+                    }
+                    catch (err) {
+                        log.error(`action.after hook threw`, {
+                            action: action.name,
+                            error: err?.message,
+                        });
+                    }
+                }
+                void this.runtime.hooks.ActionCompleted.run({
+                    action,
+                    input: validated,
+                    result: rawResult ?? undefined,
+                    durationMs,
+                });
+                return rawResult;
+            }
+            catch (err) {
+                lastError = err;
+                this.runtime.pushTelemetry({
+                    kind: "action.failed",
+                    action: action.name,
+                    attempt,
+                    maxAttempts,
+                    willRetry: attempt < maxAttempts,
+                    error: serializeError(err),
+                    envelope,
+                    appName,
+                    ts: new Date().toISOString(),
+                });
+                if (attempt >= maxAttempts) {
+                    void this.runtime.hooks.ActionFailed.run({
+                        action,
+                        input: validated,
+                        error: err,
+                        durationMs: performance.now() - startedAt,
+                    });
+                }
+            }
+        }
+        const entry = buildDeadLetterEntry(action.name, validated, envelope, attempt, lastError);
+        await this.deadLetterSink.record(entry);
+        log.error(`dead-lettered after ${attempt} attempts`, {
+            action: action.name,
+            error: entry.lastError.message,
+        });
+        this.runtime.pushTelemetry({
+            kind: "dlq.recorded",
+            action: action.name,
+            attempts: attempt,
+            error: serializeError(lastError),
+            envelope,
+            appName,
+            ts: new Date().toISOString(),
+        });
+        throw lastError;
+    }
+    /** Build the handler ctx for one dispatch. */
+    buildHandlerContext(envelope, signal) {
+        const self = this;
+        const container = this.container;
+        const ctx = {
+            container,
+            envelope,
+            logger: loggerForEnvelope(this.runtime.logger, envelope),
+            signal,
+            resolve(name) {
+                return container.resolve(name);
+            },
+            get requestId() {
+                return envelope.messageId;
+            },
+            async request(action, input) {
+                return self.dispatch(action, input, envelope, { signal });
+            },
+            async send(action, input) {
+                await self.dispatch(action, input, envelope, { signal });
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            async query(queryDef, input) {
+                // Resolve the standalone QueryRunner when present; otherwise fall
+                // through to the bundled forge dispatcher.
+                if (container.has("forge.queryRunner")) {
+                    const runner = container.resolve("forge.queryRunner");
+                    return runner.run(queryDef.name, input, envelope.tenant ?? "");
+                }
+                const dispatcher = container.resolve("forge.dispatcher");
+                return dispatcher.query(queryDef.name, input, envelope.tenant ?? "");
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            async use() {
+                throw new Error("actionsPlugin: ctx.use requires the bundled forge dispatcher. Standalone ctx.use is not yet implemented.");
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            async externalCall() {
+                throw new Error("actionsPlugin: ctx.externalCall requires the bundled forge dispatcher.");
+            },
+        };
+        for (const augment of this.augmenters)
+            augment(ctx, envelope);
+        return ctx;
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * `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 type { PluginDefinition } from "@nwire/app";
+import { type DeadLetterSink } from "@nwire/dead-letter";
+import type { HandlerDefinition } from "../primitives/define-handler.js";
+export declare const FORGE_ACTION_RUNNER_BINDING: "forge.actionRunner";
+export declare const FORGE_DEAD_LETTER_SINK_BINDING: "forge.deadLetterSink";
+export interface ActionsPluginOptions {
+    /** Override the dead-letter sink. Defaults to `InMemoryDeadLetterSink`. */
+    readonly deadLetterSink?: DeadLetterSink;
+}
+export declare function actionsPlugin(handlers: readonly HandlerDefinition<any>[], opts?: ActionsPluginOptions): PluginDefinition;