@nwire/forge 0.12.0 → 0.13.0

package/README.md

@@ -1,7 +1,7 @@
 # @nwire/forge
 
-> Domain primitives: actions, actors, events, workflows, projections.
-> Plus the runtime that fires them.
+> Domain primitives: actions, queries, actors, events, workflows, projections.
+> The batteries you grow into, riding the one runtime.
 
 ```bash
 pnpm add @nwire/forge zod
@@ -11,162 +11,179 @@ pnpm add @nwire/forge zod
 
 ### 1. Define an action
 
+An action is a handler — `defineAction = defineHandler.kind("action")`. It
+carries a name, a zod `input`, and the handler body. The body takes one `ctx`
+arg with the validated `input` on it.
+
 ```ts
 import { defineAction } from "@nwire/forge";
 import { z } from "zod";
 
 export const placeOrder = defineAction({
   name: "orders.place",
-  schema: z.object({
+  input: z.object({
     customerId: z.string(),
     items: z.array(z.object({ sku: z.string(), qty: z.number().int().positive() })),
   }),
+  handler: async ({ input, resolve }) => {
+    const orders = resolve<OrderRepo>("orders");
+    return orders.create(input);
+  },
 });
 ```
 
-An action is a typed contract — a name + zod schema. The runtime
-validates input on every dispatch.
+`ctx` carries `input`, `resolve<T>(name)`, `envelope` (tenant / user /
+correlation / causation), and the dispatch verbs `request` (ask + await),
+`send` (fire-and-forget → `MessageRef`), `emit` (publish an event), `query`
+(read a projection), and `actor` (load an actor view).
+
+For a cross-module contract the local module doesn't handle, omit `handler` —
+it's then a schema-only action you dispatch toward; the owning module registers
+the handler.
 
-### 2. Define a handler
+### 2. Define a query
+
+A query is a handler too — `defineQuery = defineHandler.kind("query")` — so it
+wires to a GET and dispatches like anything else. Projection form reads folded
+state; handler form reaches a source directly.
 
 ```ts
-import { defineHandler } from "@nwire/forge";
+import { defineQuery } from "@nwire/forge";
 
-export const placeOrderHandler = defineHandler(placeOrder, async (input, ctx) => {
-  const orders = ctx.resolve<OrderRepo>("orders");
-  return orders.create(input);
+export const listOrders = defineQuery(OrdersDashboard, {
+  name: "orders.list",
+  input: z.object({ status: z.enum(["open", "shipped"]).optional() }),
+  execute: (state, { status }) =>
+    Object.values(state).filter((o) => !status || o.status === status),
 });
 ```
 
-`(input, ctx)` is the canonical handler shape. `ctx` carries:
-
-- `resolve<T>(name)` — pull bindings from the container
-- `envelope` — tenant, user, correlation, causation
-- `dispatch(action, input)` — fire other actions
-- `enqueue(queueName, payload)` — defer work to a queue
-- `emit(event, payload)` — emit a domain event
+### 3. Register + wire into an App
 
-### 3. Wire it into an App
+Registration is the app's job — pass handlers (actions **and** queries) to
+`createApp({ handlers })`. `forgePlugins()` adds the batteries (it scans the
+runtime for action/query handlers and wires the command pipeline + read engine);
+it does **not** take a handler list.
 
 ```ts
 import { createApp } from "@nwire/app";
-import { createForgePlugin } from "@nwire/forge";
-import { post } from "@nwire/wires/http";
+import { forgePlugins } from "@nwire/forge";
+import { post, get } from "@nwire/wires/http";
 
 const app = createApp({
   appName: "orders",
-  plugins: [createForgePlugin({})],
-  handlers: [placeOrderHandler],
+  handlers: [placeOrder, listOrders],
+  plugins: [...forgePlugins({ actors: [subscription], projections: [OrdersDashboard] })],
 });
 
-// HTTP route dispatches the same handler
-app.wire(post("/orders", { body: placeOrder.schema }), placeOrderHandler);
+// HTTP routes wire the same handlers — the action/query IS the handler.
+app.wire(post("/orders", { body: placeOrder.input }), placeOrder);
+app.wire(get("/orders", { query: listOrders.input }), listOrders);
 ```
 
-`createForgePlugin({})` installs the dispatcher; handlers passed in
-`createApp({ handlers })` register on it at boot.
-
 ### 4. Dispatch from anywhere
 
 ```ts
-const dispatcher = app.container.resolve<ForgeDispatcher>("forge.dispatcher");
-
-await dispatcher.dispatch(placeOrder, {
+await app.runtime.execute(placeOrder, {
   customerId: "c-1",
   items: [{ sku: "WIDGET", qty: 2 }],
 });
 ```
 
 The runtime validates input, opens an envelope, runs middleware, fires
-`action.before` hooks, executes the handler, runs `action.after` hooks,
-and surfaces telemetry. HTTP and queue adopters route through the same
-path so dispatch semantics never differ by transport.
+`ActionDispatching` + per-action before/after hooks, runs the handler with
+retry + DLQ, publishes returned events, and surfaces telemetry. HTTP and queue
+adopters land on the same `runtime.execute`, so dispatch semantics never differ
+by transport. Inside a handler, prefer `ctx.request` / `ctx.send`.
 
 ## Actors
 
 ```ts
-import { defineActor } from "@nwire/forge";
+import { defineActor, defineSchema } from "@nwire/forge";
 
-export const subscription = defineActor({
+const SubscriptionData = defineSchema({
   name: "subscription",
-  schema: z.object({
+  key: "id",
+  fields: {
     id: z.string(),
     plan: z.enum(["free", "pro"]),
     status: z.enum(["active", "past_due", "suspended"]),
-  }),
-  methods: {
-    suspend: ({ self }) => ({ ...self, status: "suspended" }),
-    activate: ({ self }) => ({ ...self, status: "active" }),
+  },
+  states: {
+    active: { initial: true },
+    past_due: {},
+    suspended: { final: true },
   },
 });
+
+export const subscription = defineActor(
+  "subscription",
+  ({ states, when }) => {
+    const { active, pastDue } = states;
+    active(() =>
+      when(PaymentFailed, (_e, { assign }) => {
+        assign({ status: "past_due" });
+        return pastDue;
+      }),
+    );
+  },
+  { schema: SubscriptionData },
+);
 ```
 
-Actors carry state, version, and OCC. Methods receive the current state
-and return the next state — pure transitions. The dispatcher persists
-through an `ActorStore` adapter.
+Actors carry state, version, and OCC; events drive transitions. The store seam
+is an `ActorStore` adapter. Pass `actors: [...]` to `forgePlugins`.
 
 ## Workflows
 
 ```ts
 import { defineWorkflow } from "@nwire/forge";
 
-export const paymentRenewal = defineWorkflow({
-  name: "payment.renewal",
-  on: { event: chargeFailed },
-  steps: {
-    holdGrace: async (ctx) => {
-      await ctx.schedule(suspendSubscription, { in: "48h" });
-    },
-  },
+export const paymentRenewal = defineWorkflow("payment.renewal", ({ when, schedule, timeout }) => {
+  const Overdue = timeout("overdue", "48h");
+  when(ChargeFailed, async (e, ctx) => {
+    await schedule(Overdue);
+  });
+  when(Overdue, async (_e, ctx) => {
+    await ctx.send(suspendSubscription, { id: _e.id });
+  });
 });
 ```
 
-Workflows react to events. `ctx.schedule(...)` arms timers, `ctx.dispatch(...)`
-fires actions; state persists between hops via the actor store.
+Workflows react to events with the one verb, `when`; `schedule`/`timeout` arm
+timers and `ctx.send(...)` dispatches actions. Declare `data`/`states` (3rd arg)
+to make it a stateful saga. Pass `workflows: [...]` to `forgePlugins`.
 
 ## Projections
 
 ```ts
 import { defineProjection } from "@nwire/forge";
 
-export const queueDashboard = defineProjection({
-  name: "queue.dashboard",
-  on: { event: postSubmitted },
-  apply: async (state, event) => {
-    state.pending.push({ id: event.payload.postId, submittedAt: event.envelope.ts });
+export const OrdersDashboard = defineProjection(
+  "orders.dashboard",
+  ({ when }) => {
+    when(orderPlaced, (state, event) => ({ ...state, [event.orderId]: event }));
   },
-});
+  { initial: () => ({}) },
+);
 ```
 
-Projections build read models from events. Domain code reads them via
-`ctx.resolve<ProjectionStore>("projection.queue.dashboard")`.
-
-## Plugin options
-
-`createForgePlugin({...})` accepts:
-
-```ts
-createForgePlugin({
-  workflows: [paymentRenewal],
-  projections: [queueDashboard],
-  queries: [listPending, queueTotals],
-  actors: [subscription],
-  externalCalls: [chargeStripe],
-});
-```
+Projections fold events into read models; queries read them. Pass
+`projections: [...]` to `forgePlugins`.
 
 ## Surface
 
-- **Primitives** — `defineAction`, `defineActor`, `defineEvent`,
-  `defineWorkflow`, `defineProjection`, `defineQuery`, `defineHandler`
-- **Plugin** — `createForgePlugin(options)`
-- **Dispatcher** — `ForgeDispatcher` (resolved as `"forge.dispatcher"`)
-- **Helpers** — `eventFactory`, `defineResource`, `NotFound`,
-  `defineUpcaster`, response builders
+- **Primitives** — `defineAction`, `defineQuery`, `defineActor`, `defineEvent`,
+  `defineWorkflow`, `defineProjection`; plus `eventFactory`, `defineResource`,
+  `defineUpcaster`, response builders. (`defineAction`/`defineQuery` are
+  `defineHandler.kind(...)` from `@nwire/handler`.)
+- **Plugins** — `forgePlugins(options)` (the set) or the à-la-carte concern
+  plugins: `actionsPlugin`, `queriesPlugin`, `actorsPlugin`, `projectionsPlugin`,
+  `workflowsPlugin`, `idempotencyPlugin`, `externalCallsPlugin`.
 
 ## Related
 
 - [`@nwire/app`](../core-app) — `createApp`, plugin lifecycle, runtime
-- [`@nwire/handler`](../core-handler) — handler contract + error envelope
+- [`@nwire/handler`](../core-handler) — the handler primitive (`defineHandler`)
 - [`@nwire/messages`](../core-messages) — typed envelope + zod helpers
-- [`@nwire/koa`](../nwire-koa) — HTTP adopter that routes through the dispatcher
+- [`@nwire/koa`](../nwire-koa) — HTTP adopter that routes through the runtime

package/dist/framework-events.d.ts

@@ -14,26 +14,8 @@
  * 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(). */
@@ -66,27 +48,16 @@ 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 — materialised by `createForgePlugin`. */
-export declare const forgeFrameworkSlots: readonly ["ActionDispatching", "ActionCompleted", "ActionFailed", "EventRecording", "EventRecorded", "EventPublishing"];
-/** Priority slots forge's own chain participants attach at. */
+/** Forge-specific framework-hook slot names — materialised by `actionsPlugin`. */
+export declare const forgeFrameworkSlots: readonly ["ActionDispatching", "ActionCompleted", "ActionFailed", "EventRecording", "EventRecorded"];
+/**
+ * Priority slots forge's fold steps attach at on the core `LocalDelivery`
+ * hook (idempotency → actors → projections → workflows). Bus + outbound
+ * sink are no longer chain steps — they're the outbound `publish` concern,
+ * applied by the dispatcher after `runtime.deliver`.
+ */
 export declare const EVENT_PUBLISHING_PRIORITIES: {
     readonly idempotency: 1000;
     readonly actors: 800;

package/dist/framework-events.js

@@ -13,16 +13,20 @@
  * are pre-instantiated on every Runtime; this file only adds forge's
  * domain-specific slots.
  */
-/** Forge-specific framework-hook slot names — materialised by `createForgePlugin`. */
+/** Forge-specific framework-hook slot names — materialised by `actionsPlugin`. */
 export const forgeFrameworkSlots = [
     "ActionDispatching",
     "ActionCompleted",
     "ActionFailed",
     "EventRecording",
     "EventRecorded",
-    "EventPublishing",
 ];
-/** Priority slots forge's own chain participants attach at. */
+/**
+ * Priority slots forge's fold steps attach at on the core `LocalDelivery`
+ * hook (idempotency → actors → projections → workflows). Bus + outbound
+ * sink are no longer chain steps — they're the outbound `publish` concern,
+ * applied by the dispatcher after `runtime.deliver`.
+ */
 export const EVENT_PUBLISHING_PRIORITIES = {
     idempotency: 1000,
     actors: 800,

package/dist/helpers/cli-runner.js

@@ -34,7 +34,16 @@
  * 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";
+import { FORGE_ACTION_RUNNER_BINDING } from "../plugins/actions-plugin.js";
+import { FORGE_QUERY_RUNNER_BINDING } from "../plugins/queries-plugin.js";
+function actionRunnerOf(app) {
+    return app.container.resolve(FORGE_ACTION_RUNNER_BINDING);
+}
+function queryRunnerOf(app) {
+    return app.container.has(FORGE_QUERY_RUNNER_BINDING)
+        ? app.container.resolve(FORGE_QUERY_RUNNER_BINDING)
+        : undefined;
+}
 export async function runCli(app, argv, options = {}) {
     const stdout = options.stdout ?? ((line) => console.log(line));
     const stderr = options.stderr ?? ((line) => console.error(line));
@@ -44,14 +53,15 @@ export async function runCli(app, argv, options = {}) {
     }
     const targetName = argv[0];
     const rest = argv.slice(1);
-    const dispatcher = forgeDispatcher(app);
-    const action = dispatcher.findActionByName(targetName);
+    const actions = actionRunnerOf(app);
+    const queries = queryRunnerOf(app);
+    const action = actions.findActionByName(targetName);
     if (action) {
         const { tenant, parsed } = parseFlags(rest);
         try {
-            const validated = action.schema.parse(parsed);
+            const validated = action.input.parse(parsed);
             const envelope = tenant ? seedEnvelope({ tenant }) : undefined;
-            await dispatcher.dispatch(action, validated, envelope);
+            await actions.dispatch(action, validated, envelope);
             stdout("OK");
             return 0;
         }
@@ -61,10 +71,10 @@ export async function runCli(app, argv, options = {}) {
         }
     }
     // Fall back to query.
-    if (dispatcher.listQueries().includes(targetName)) {
+    if (queries?.listQueries().includes(targetName)) {
         const { tenant, parsed } = parseFlags(rest);
         try {
-            const result = await dispatcher.query(targetName, parsed, tenant);
+            const result = await queries.run(targetName, parsed, tenant);
             stdout(JSON.stringify(result, null, 2));
             return 0;
         }
@@ -77,15 +87,16 @@ export async function runCli(app, argv, options = {}) {
     return 1;
 }
 function printHelp(app, stdout) {
-    const dispatcher = forgeDispatcher(app);
+    const actions = actionRunnerOf(app);
+    const queries = queryRunnerOf(app);
     stdout("nwire — action CLI runner\n");
     stdout("Usage: amit <action-or-query-name> [--field value ...] [--tenant <id>]\n");
     stdout("Actions:");
-    for (const name of dispatcher.listHandlers()) {
+    for (const name of actions.listHandlers()) {
         stdout(`  ${name}`);
     }
     stdout("Queries:");
-    for (const name of dispatcher.listQueries()) {
+    for (const name of queries?.listQueries() ?? []) {
         stdout(`  ${name}`);
     }
 }

package/dist/index.d.ts

@@ -13,8 +13,9 @@
  *   const dispatcher = forgeDispatcher(app);
  *   await dispatcher.dispatch(placeOrder, { … });
  */
-export { forgePlugin, createForgePlugin, forgeDispatcher, type ForgePluginOptions, FORGE_DISPATCHER_BINDING, } from "./runtime/forge-plugin.js";
+export { forgePlugins, type ForgeOptions } from "./runtime/forge-plugins.js";
 export { withForge } from "./runtime/with-forge.js";
+export { externalCallsPlugin, ExternalCallRunner, FORGE_EXTERNAL_CALLS_BINDING, } from "./plugins/external-calls-plugin.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";
@@ -23,21 +24,20 @@ export { workflowsPlugin, FORGE_WORKFLOW_CHAIN_BINDING, FORGE_WORKFLOW_TIMER_STO
 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 { actionsPlugin, FORGE_ACTION_RUNNER_BINDING, FORGE_DEAD_LETTER_SINK_BINDING, FORGE_PUBLISH_BINDING, FORGE_PUBLIC_EVENTS_BINDING, type ActionsPluginOptions, } from "./plugins/actions-plugin.js";
+export { ActionRunner, type PublishEventsFn } 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 { 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 { defineActor, eventKey, type ActorDefinition, type ActorOptions, type ActorBuilderContext, type StateRef, 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";
 export { validate, isInvariantError, InvariantError, type Invariant } from "./helpers/validate.js";
-export { defineHandler, type HandlerContext, type HandlerDefinition, type HandlerReturn, } from "./primitives/define-handler.js";
+export { type HandlerContext, type HandlerReturn } from "./primitives/define-handler.js";
 export { eventFactory, isEventMessage, normalizeEventReturn, type EventMessage, type EventFactory, } from "./messages/event-message.js";
 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 { defineQuery, type QueryDefinition, type QueryOptions, type QueryContext, } from "./primitives/define-query.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";
@@ -57,5 +57,6 @@ export { NoopLogger, ConsoleLogger, loggerForEnvelope, type Logger } from "@nwir
 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";
+export { messageRef, type MessageRef } from "@nwire/app";
 import "./framework-events.js";
 export type { FrameworkHooks, PluginKind } from "@nwire/app";

package/dist/index.js

@@ -13,9 +13,10 @@
  *   const dispatcher = forgeDispatcher(app);
  *   await dispatcher.dispatch(placeOrder, { … });
  */
-// ─── Plugin + composition ──────────────────────────────────────────
-export { forgePlugin, createForgePlugin, forgeDispatcher, FORGE_DISPATCHER_BINDING, } from "./runtime/forge-plugin.js";
+// ─── Plugin set + composition ──────────────────────────────────────
+export { forgePlugins } from "./runtime/forge-plugins.js";
 export { withForge } from "./runtime/with-forge.js";
+export { externalCallsPlugin, ExternalCallRunner, FORGE_EXTERNAL_CALLS_BINDING, } from "./plugins/external-calls-plugin.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";
@@ -24,21 +25,19 @@ export { workflowsPlugin, FORGE_WORKFLOW_CHAIN_BINDING, FORGE_WORKFLOW_TIMER_STO
 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 { actionsPlugin, FORGE_ACTION_RUNNER_BINDING, FORGE_DEAD_LETTER_SINK_BINDING, FORGE_PUBLISH_BINDING, FORGE_PUBLIC_EVENTS_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";
 // ─── Domain primitives ─────────────────────────────────────────────
 export { defineAction, isCommandMessage, resolveDispatch, } from "./primitives/define-action.js";
 export { defineActor, eventKey, } from "./primitives/define-actor.js";
 export { defineSchema, isSchemaDefinition, } from "./primitives/define-schema.js";
 export { validate, isInvariantError, InvariantError } from "./helpers/validate.js";
-export { defineHandler, } from "./primitives/define-handler.js";
 export { eventFactory, isEventMessage, normalizeEventReturn, } from "./messages/event-message.js";
 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 { defineQuery, } from "./primitives/define-query.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";
@@ -61,6 +60,8 @@ export { NoopLogger, ConsoleLogger, loggerForEnvelope } from "@nwire/logger";
 export { InMemoryDeadLetterSink, buildDeadLetterEntry, } from "@nwire/dead-letter";
 export { defineResource, isResourceDefinition, } from "@nwire/handler";
 export { response, isResponseSpec, isResponseInstance, ok, created, accepted, noContent, notModified, gone, } from "./helpers/response.js";
+// Message handle returned by the async dispatch verbs (`ctx.send`).
+export { messageRef } from "@nwire/app";
 // Module augmentation side effect — adds Action* / Event* slots to
 // FrameworkHooks on @nwire/app's runtime.
 import "./framework-events.js";

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

@@ -1,48 +1,65 @@
 /**
- * Action runner — handler registry + dispatch loop.
+ * Action runner — the forge command pipeline, composed onto the real handler's
+ * own hook chain. There is no parallel dispatcher and no `run`-override:
+ * `install(action)` attaches the pipeline as a high-priority `.use()` step on
+ * the action handler's hook, so dispatching it through `runtime.execute` (from
+ * a wire, queue, cron, or another handler's `ctx.request`) runs retry / DLQ /
+ * ActionDispatching / before-after / telemetry / event-publish as the outermost
+ * step. The step invokes the handler body directly in its retry loop and
+ * short-circuits (`@nwire/hooks` `compose` forbids calling `next()` twice, so
+ * retry cannot loop the chain).
  *
- * 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.
+ * The handler ctx (input, envelope, request/send/emit/query/actor/…) is built
+ * by `runtime.execute`'s capability ctx — each forge concern plugin contributes
+ * its verb. This runner owns the pipeline + the per-action before/after hooks +
+ * a `dispatch` convenience; events a handler returns flow out via the injected
+ * `publishEvents` (local LocalDelivery fold + outbound sink for public).
  */
 import { type Runtime } from "@nwire/app";
-import { type MessageEnvelope } from "@nwire/envelope";
+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 { HandlerContext } 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. */
+/** Publish callback — injected so the runner doesn't own the outbound concern. */
 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 handlers: Map<string, ActionDefinition<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;
+    /**
+     * Compose the command pipeline onto an action's own hook chain. The action is
+     * already registered on the runtime (by the app); this only attaches behavior.
+     */
+    install(action: ActionDefinition<any>): void;
     /** Action handler names, in registration order. */
     listHandlers(): readonly string[];
     findActionByName(name: string): ActionDefinition<any> | undefined;
+    findHandler(name: string): ActionDefinition<any> | undefined;
+    hasHandler(name: string): boolean;
     ensureBeforeHook(name: string): Hook<ActionBeforeHookCtx>;
     ensureAfterHook(name: string): Hook<ActionAfterHookCtx>;
-    /** Plugins can hang extra ctx members on each handler invocation. */
-    registerCtxAugmenter(fn: CtxAugmenter): void;
+    /**
+     * Thin dispatch convenience — routes through `runtime.execute`, whose pinned
+     * core runs the action's hook chain (this pipeline). Used by `ctx.request`
+     * and any caller holding the action reference.
+     */
     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;
+    /**
+     * The command pipeline — runs as the action's outermost hook step under
+     * `runtime.execute`: `action.dispatched` telemetry, the `ActionDispatching`
+     * veto hook, per-action before/after hooks, retry + backoff invoking the
+     * handler body, dead-letter on exhaustion, completion/failure telemetry, and
+     * event-return publishing. `ctx` is execute's capability ctx; `rawHandler` is
+     * the action's adapted `(ctx)` body.
+     */
+    runActionPipeline(action: ActionDefinition<any>, rawHandler: (ctx: HandlerContext) => unknown, ctx: HandlerContext, signal: AbortSignal): Promise<unknown>;
 }