@nwire/forge 0.7.1 → 0.8.17

package/dist/runtime.js

@@ -20,16 +20,19 @@
  *     projections.
  */
 import { rootContainer } from "@nwire/container";
+import { hook } from "@nwire/hooks";
+import { isValidated, markValidated } from "@nwire/messages";
 import { seedEnvelope, deriveEnvelope } from "@nwire/envelope";
 import { InMemoryWorkflowTimerStore, timerEventName, } from "./workflow-timer-store.js";
 import { randomUUID } from "node:crypto";
 import { InMemoryActorStore, createInitialInstance, } from "./actor-store.js";
 import { normalizeEventReturn } from "./event-message.js";
 import { InMemoryProjectionStore } from "./projection-store.js";
+import { InMemoryIdempotencyStore } from "./idempotency-store.js";
 import { NoopLogger, loggerForEnvelope } from "@nwire/logger";
 import { InMemoryDeadLetterSink, buildDeadLetterEntry, } from "@nwire/dead-letter";
 import { FrameworkEventBus } from "./framework-event-bus.js";
-import { ActionDispatching, ActionCompleted, ActionFailed, } from "./framework-events.js";
+import { ActionDispatching, ActionCompleted, ActionFailed, builtInFrameworkEvents, } from "./framework-events.js";
 /** Serialize an unknown thrown value into the canonical SerializedError shape. */
 function serializeError(err) {
     if (err instanceof Error) {
@@ -85,7 +88,33 @@ export class Runtime {
     projectionStore;
     logger;
     deadLetterSink;
-    middlewares = [];
+    /**
+     * Dispatch is a `@nwire/hooks` chain — user middlewares plus a permanent
+     * "handler" step pinned to the inner edge. `runtime.use(mw)` adapts the
+     * legacy `DispatchMiddleware` shape into a `ChainFn` and registers it.
+     * Taps fire into `runtime.onTelemetry` under `kind: "hook.step"`, which is
+     * what Studio + CLI + OTel consume.
+     */
+    dispatchHook;
+    /**
+     * Per-action `action.before:<name>` hooks. Pre-created at
+     * `registerHandler()` so they show up in `listHooks()` + scan + Studio
+     * even before any plugin's `before(name, …)` sugar runs. Adopted into
+     * the canonical telemetry stream so each chain step emits `hook.step`
+     * observations.
+     */
+    actionBeforeHooks = new Map();
+    /** Per-action `action.after:<name>` hooks. Pre-created identically. */
+    actionAfterHooks = new Map();
+    /**
+     * Per-actor `actor.transition:<name>` hooks. Pre-created at
+     * `registerActor()` time. Adopted into the canonical telemetry stream
+     * so each chain step emits `hook.step` observations — same model as
+     * `actionBeforeHooks` / `actionAfterHooks`.
+     */
+    perActorHooks = new Map();
+    /** Per-workflow `workflow.fire:<name>` hooks. Pre-created at registration. */
+    perWorkflowHooks = new Map();
     actorTransitionHooks = [];
     bus;
     publishToBus;
@@ -97,6 +126,8 @@ export class Runtime {
     publicEventNames = new Set();
     /** Saga timer store (default in-memory; pluggable via RuntimeOptions). */
     workflowTimerStore;
+    /** Envelope-level dedup table — see RuntimeOptions.idempotencyStore. */
+    idempotencyStore;
     /**
      * Framework event bus — lifecycle + dispatch hooks. Plugins and apps
      * subscribe with `runtime.onFramework(Event, handler)`; the runtime
@@ -113,7 +144,14 @@ export class Runtime {
         this.publishToBus = options.publishToBus ?? false;
         this.appName = options.appName ?? "app";
         this.workflowTimerStore = options.workflowTimerStore ?? new InMemoryWorkflowTimerStore();
-        this.frameworkEvents = new FrameworkEventBus(this.logger);
+        this.idempotencyStore = options.idempotencyStore ?? new InMemoryIdempotencyStore();
+        // Forward bus's per-event hook adoptions through runtime.adoptHook so
+        // every framework event becomes a registered hook (visible in
+        // listHooks() / scan / Studio).
+        this.frameworkEvents = new FrameworkEventBus(this.logger, {
+            adoptHook: (h) => this.adoptHook(h),
+            events: builtInFrameworkEvents,
+        });
         // Bridge framework-event firings into the telemetry stream so every
         // existing telemetry consumer (dev logger, Studio Live SSE, OTel
         // exporter) sees lifecycle activity through the same channel as
@@ -132,6 +170,32 @@ export class Runtime {
                 ts: rec.ts,
             });
         });
+        // Set up the dispatch hook + the innermost "handler" step (pinned at
+        // -Infinity so user middleware always wraps it). Every step emits a
+        // start/end/error observation through the tap into the canonical
+        // telemetry stream — that's what powers Studio Live + CLI hook trace.
+        this.dispatchHook = hook("forge.action.dispatch");
+        this.dispatchHook.use(async (hctx, next) => {
+            hctx.result = await hctx.coreFn();
+            await next();
+        }, { name: "handler", priority: -Infinity });
+        this.dispatchHook.tap((obs) => {
+            this.emit({
+                kind: "hook.step",
+                hookName: obs.hookName,
+                hookId: obs.hookId,
+                runId: obs.runId,
+                parentRunId: obs.parentRunId,
+                stepId: obs.stepId,
+                stepKind: obs.stepKind,
+                stepName: obs.stepName,
+                phase: obs.phase,
+                durationMs: obs.durationMs,
+                error: obs.error ? serializeError(obs.error) : undefined,
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+        });
     }
     /**
      * Subscribe to a framework event. Sugar over `runtime.frameworkEvents.on`
@@ -149,6 +213,38 @@ export class Runtime {
     registerPublicEvent(eventName) {
         this.publicEventNames.add(eventName);
     }
+    /**
+     * Wire a hook's per-step tap into the canonical telemetry stream. After
+     * calling this, every `.use()` / `.on()` step on the hook emits a
+     * `kind: "hook.step"` record through `runtime.onTelemetry`, the same way
+     * the built-in `forge.action.dispatch` hook does.
+     *
+     * createApp uses this for every per-plugin and per-module lifecycle hook;
+     * plugin authors can call it on their own hooks if they want their
+     * extension points surfaced in Studio + dev-logger + OTel for free.
+     *
+     * Idempotent at the source — calling twice on the same hook attaches two
+     * tap subscribers; the framework only calls this once per hook it owns.
+     */
+    adoptHook(hook) {
+        hook.tap((obs) => {
+            this.emit({
+                kind: "hook.step",
+                hookName: obs.hookName,
+                hookId: obs.hookId,
+                runId: obs.runId,
+                parentRunId: obs.parentRunId,
+                stepId: obs.stepId,
+                stepKind: obs.stepKind,
+                stepName: obs.stepName,
+                phase: obs.phase,
+                durationMs: obs.durationMs,
+                error: obs.error ? serializeError(obs.error) : undefined,
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+        });
+    }
     /** Internal — createApp registers actor-transition hooks from plugins. */
     registerActorTransitionHook(hook) {
         this.actorTransitionHooks.push(hook);
@@ -157,10 +253,27 @@ export class Runtime {
      * Register a dispatch middleware. Outermost first — the order you call
      * `use()` is the order layers wrap (first `use` is the outermost layer).
      * Middlewares run once per dispatch, outside the retry loop.
+     *
+     * Internally this attaches to the `forge.action.dispatch` hook as a
+     * chain step. The legacy `(next, action, input, ctx)` shape is adapted
+     * to a `ChainFn<DispatchHookCtx>` without surface change for callers.
      */
     use(middleware) {
-        this.middlewares.push(middleware);
+        // Each user middleware gets a distinct priority so the chain order
+        // matches registration order. We start from 0 and DECREMENT — the
+        // first registered middleware ends up with the highest priority
+        // (= outermost), and the pinned "handler" step at -Infinity stays
+        // strictly innermost.
+        const priority = -this.userMiddlewareCount;
+        this.userMiddlewareCount += 1;
+        this.dispatchHook.use(async (hctx, next) => {
+            hctx.result = await middleware(async () => {
+                await next();
+                return hctx.result;
+            }, hctx.action, hctx.input, hctx.ctx);
+        }, { name: middleware.name || `middleware#${this.userMiddlewareCount}`, priority });
     }
+    userMiddlewareCount = 0;
     // ─── Registration ────────────────────────────────────────────────
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     registerHandler(handler) {
@@ -169,12 +282,76 @@ export class Runtime {
             throw new Error(`Runtime: handler for action "${name}" already registered.`);
         }
         this.handlers.set(name, handler);
+        // Pre-create the per-action observation hooks so `listHooks()` + scan +
+        // Studio show every action's before/after extension points whether or
+        // not a plugin has subscribed yet. Lazy-on-first-subscribe would hide
+        // them from static introspection.
+        this.ensureActionBeforeHook(name);
+        this.ensureActionAfterHook(name);
+    }
+    /**
+     * Get (or lazily create + adopt) the per-action `action.before:<name>`
+     * hook. Plugin authors normally reach this via `plugin.before(name, …)`;
+     * this method is also public so test code + custom orchestrators can
+     * register chain steps or taps directly.
+     */
+    ensureActionBeforeHook(actionName) {
+        let h = this.actionBeforeHooks.get(actionName);
+        if (h)
+            return h;
+        h = hook(`action.before:${actionName}`);
+        this.actionBeforeHooks.set(actionName, h);
+        this.adoptHook(h);
+        return h;
+    }
+    /** Get (or lazily create + adopt) the per-action `action.after:<name>` hook. */
+    ensureActionAfterHook(actionName) {
+        let h = this.actionAfterHooks.get(actionName);
+        if (h)
+            return h;
+        h = hook(`action.after:${actionName}`);
+        this.actionAfterHooks.set(actionName, h);
+        this.adoptHook(h);
+        return h;
+    }
+    /**
+     * Get (or lazily create + adopt) the per-actor `actor.transition:<name>`
+     * hook. Plugin authors reach this via `runtime.ensureActorTransitionHook(name)`
+     * to attach chain steps or taps; the dispatcher runs the hook after the
+     * actor's state has been saved.
+     */
+    ensureActorTransitionHook(actorName) {
+        let h = this.perActorHooks.get(actorName);
+        if (h)
+            return h;
+        h = hook(`actor.transition:${actorName}`);
+        this.perActorHooks.set(actorName, h);
+        this.adoptHook(h);
+        return h;
+    }
+    /**
+     * Get (or lazily create + adopt) the per-workflow `workflow.fire:<name>`
+     * hook. Runs around every workflow invocation triggered by a subscribed
+     * event — see `runWorkflows`.
+     */
+    ensureWorkflowFireHook(workflowName) {
+        let h = this.perWorkflowHooks.get(workflowName);
+        if (h)
+            return h;
+        h = hook(`workflow.fire:${workflowName}`);
+        this.perWorkflowHooks.set(workflowName, h);
+        this.adoptHook(h);
+        return h;
     }
     registerActor(actor) {
         if (this.actors.has(actor.name)) {
             throw new Error(`Runtime: actor "${actor.name}" already registered.`);
         }
         this.actors.set(actor.name, actor);
+        // Pre-create the observation hook so scan + listHooks() + Studio see
+        // every actor's transition extension point even before any plugin
+        // subscribes.
+        this.ensureActorTransitionHook(actor.name);
     }
     /** Internal — createApp registers each module's workflows. */
     registerWorkflow(workflow) {
@@ -183,6 +360,9 @@ export class Runtime {
             list.push(workflow);
             this.workflowsByEvent.set(eventName, list);
         }
+        // Same eager-creation rationale as registerActor — surface workflow
+        // fire extension points statically.
+        this.ensureWorkflowFireHook(workflow.name);
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     registerProjection(projection) {
@@ -305,10 +485,27 @@ export class Runtime {
             throw new Error(`Runtime: no query registered with name "${queryName}".`);
         }
         const t0 = performance.now();
-        const validated = query.schema.parse(input);
-        const state = (await this.projectionStore.load(query.projection.name, tenant)) ??
-            query.projection.initial();
-        const result = (await query.execute(state, validated));
+        const validated = isValidated(input) ? input : markValidated(query.schema.parse(input));
+        let result;
+        if (query.projection && query.execute) {
+            // Projection form — load state, hand it to `execute`.
+            const state = (await this.projectionStore.load(query.projection.name, tenant)) ??
+                query.projection.initial();
+            result = (await query.execute(state, validated));
+        }
+        else if (query.handler) {
+            // Handler form — no projection, hand a QueryContext (DI + tenant +
+            // signal) to the user's reader. Lets queries read from any source
+            // (Postgres, Redis, search) without a projection layer.
+            result = (await query.handler(validated, {
+                resolve: (name) => this.container.resolve(name),
+                tenant,
+            }));
+        }
+        else {
+            throw new Error(`Runtime: query "${queryName}" has neither projection+execute nor a handler — ` +
+                `the runtime cannot route the call. defineQuery must be given one or the other.`);
+        }
         this.emit({
             kind: "query.executed",
             query: queryName,
@@ -417,6 +614,12 @@ export class Runtime {
         }
         return fired;
     }
+    /**
+     * Resolve an action definition by its routing name. Used by execute/send
+     * to support the callable form `execute(myAction(input))` — the
+     * `CommandMessage` carries only the name; the runtime looks up the actual
+     * action from the registered handler map.
+     */
     findActionByName(name) {
         const handler = this.handlers.get(name);
         return handler?.action;
@@ -459,15 +662,26 @@ export class Runtime {
      * Run an action through its handler, then atomically apply returned events.
      * Returns the handler's raw return value (events) for callers that want it.
      */
-    async dispatch(action, input, parentEnvelope) {
+    async dispatch(action, input, parentEnvelope, opts) {
         const handler = this.handlers.get(action.name);
         if (!handler) {
             throw new Error(`Runtime: no handler registered for action "${action.name}".`);
         }
         const envelope = parentEnvelope ? deriveEnvelope(parentEnvelope) : seedEnvelope({});
-        const validated = action.schema.parse(input);
+        // Skip re-parse if a trust boundary already validated this input
+        // (HTTP `parseAndValidate`, queue worker consume, bus inbound).
+        // Untrusted call sites (raw object from application code) hit the
+        // parse path because the brand is missing. The brand is dropped by
+        // serialization, structural copy, and primitive coercion — so it
+        // never produces a false "trust me."
+        const validated = isValidated(input) ? input : markValidated(action.schema.parse(input));
         const log = loggerForEnvelope(this.logger, envelope);
-        const ctx = this.buildHandlerContext(envelope, log);
+        // Caller-side cancellation: every dispatch carries an AbortSignal on
+        // ctx. When the caller doesn't supply one, we mint a never-aborted
+        // controller so handler code can call `ctx.signal.throwIfAborted()`
+        // unconditionally — existing handlers behave identically.
+        const signal = opts?.signal ?? new AbortController().signal;
+        const ctx = this.buildHandlerContext(envelope, log, signal);
         this.emit({
             kind: "action.dispatched",
             action: action.name,
@@ -489,8 +703,23 @@ export class Runtime {
         if (!dispatchAllowed) {
             return undefined;
         }
+        // Per-action `action.before:<name>` hook. Mirrors the ActionDispatching
+        // veto semantics but routes through a named hook so the chain is visible
+        // in `listHooks()`, scan, and Studio. Chain steps registered via the
+        // `plugin.before(name, …)` sugar set `vetoed = true` when their handler
+        // returns false; that cleanly cancels the dispatch with no events.
+        const beforeHook = this.actionBeforeHooks.get(action.name);
+        if (beforeHook) {
+            const beforeCtx = { action, input: validated, ctx };
+            await beforeHook.run(beforeCtx);
+            if (beforeCtx.vetoed) {
+                return undefined;
+            }
+        }
         // Core: retry loop + handler invocation + event publishing.
-        // Returns the raw handler return for the dispatcher to type-cast.
+        // Returns the raw handler return for the dispatcher to type-cast. The
+        // return union mirrors `HandlerReturn` — plain records (e.g. `{ userId }`)
+        // surface here untouched so the dispatcher can hand them back to callers.
         const core = async () => {
             const retry = action.retry;
             const maxAttempts = 1 + (retry?.max ?? 0);
@@ -498,6 +727,21 @@ export class Runtime {
             let lastError;
             while (attempt < maxAttempts) {
                 attempt++;
+                // Caller already gave up — skip remaining retries (and the DLQ
+                // entry that would follow exhaustion). The original error still
+                // surfaces to whatever is `await`ing the dispatch, but we don't
+                // spend retry budget on a result no one will read. We re-throw
+                // outside the inner try so the catch's failed/DLQ telemetry does
+                // not fire for the skipped attempts.
+                if (attempt > 1 && signal.aborted) {
+                    log.warn(`abort observed between attempts; skipping retries`, {
+                        action: action.name,
+                        attempt,
+                        maxAttempts,
+                    });
+                    // eslint-disable-next-line no-throw-literal
+                    throw lastError;
+                }
                 try {
                     if (attempt > 1) {
                         const delay = computeBackoff(retry, attempt - 1);
@@ -525,6 +769,28 @@ export class Runtime {
                         appName: this.appName,
                         ts: new Date().toISOString(),
                     });
+                    // Per-action `action.after:<name>` hook. Observation-only —
+                    // chain steps registered by `plugin.after(name, …)` see the
+                    // result + durationMs but can't undo. Awaited so `hook.step`
+                    // taps land in telemetry before the action returns, the way
+                    // the dispatch hook's taps already do.
+                    const afterHook = this.actionAfterHooks.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,
+                            });
+                        }
+                    }
                     // Framework event: ActionCompleted (parallel, observable).
                     // Don't await — observers shouldn't block the response path.
                     void this.frameworkEvents.fire(ActionCompleted, {
@@ -585,16 +851,13 @@ export class Runtime {
             });
             throw lastError;
         };
-        // Compose middlewares around the core. Outermost first (registration
-        // order is execution order — first `use(m)` is the outermost layer).
-        let pipeline = core;
-        for (let i = this.middlewares.length - 1; i >= 0; i--) {
-            const mw = this.middlewares[i];
-            const inner = pipeline;
-            pipeline = () => mw(inner, action, validated, ctx);
-        }
-        const result = await pipeline();
-        return result;
+        // Run through the dispatch hook. Every user-registered middleware sits
+        // outside the pinned "handler" chain step (-Infinity); the hook calls
+        // `coreFn` in that innermost step and writes the result back on hctx.
+        // Taps fire per step into runtime.onTelemetry as `kind: "hook.step"`.
+        const hctx = { action, input: validated, ctx, coreFn: core };
+        await this.dispatchHook.run(hctx);
+        return hctx.result;
     }
     /**
      * Apply a batch of events: route to actors (state transitions + assigns +
@@ -602,8 +865,30 @@ export class Runtime {
      * by `dispatch` and exposed for tests and rare external publishes.
      */
     async publish(events, parentEnvelope) {
-        for (const event of events) {
+        for (let i = 0; i < events.length; i++) {
+            const event = events[i];
+            // Envelope-level idempotency: short-circuit when we've already
+            // applied this exact `messageId`. The dedup key is the PARENT
+            // envelope's id — that's the identity a queue/bus driver carries
+            // through verbatim on redelivery, and the identity a caller
+            // can pin to make two publish() calls share a fate. When more than
+            // one event ships under the same parent envelope we tag the
+            // dedup key with the event index so each one applies on the
+            // first delivery and dedups on the second.
+            const dedupKey = events.length === 1 ? parentEnvelope.messageId : `${parentEnvelope.messageId}#${i}`;
             const childEnvelope = deriveEnvelope(parentEnvelope);
+            if (await this.idempotencyStore.seen(dedupKey)) {
+                this.emit({
+                    kind: "event.deduped",
+                    event,
+                    envelope: childEnvelope,
+                    source: "in-process",
+                    appName: this.appName,
+                    ts: new Date().toISOString(),
+                });
+                continue;
+            }
+            await this.idempotencyStore.record(dedupKey);
             // Ordering: actors → projections → workflows.
             //   - actors first: state must be coherent before observers see it.
             //   - projections second: workflows often read state via queries
@@ -688,6 +973,22 @@ export class Runtime {
             throw new Error(`Runtime.applyExternalEvent: "${eventName}" was not declared in any module's needs.externalEvents.`);
         }
         const event = { eventName, payload };
+        // Bus inbound dedup mirrors the in-process publish path: a queue
+        // redrive or bus replay carries the same `envelope.messageId`,
+        // so an identical second delivery short-circuits without touching
+        // actor or projection state.
+        if (await this.idempotencyStore.seen(envelope.messageId)) {
+            this.emit({
+                kind: "event.deduped",
+                event,
+                envelope,
+                source: "external",
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+            return;
+        }
+        await this.idempotencyStore.record(envelope.messageId);
         await this.applyToActors(event, envelope);
         await this.foldProjections(event, envelope);
         await this.runWorkflows(event, envelope);
@@ -710,19 +1011,40 @@ export class Runtime {
             if (!reducer)
                 continue;
             const t0 = performance.now();
-            const current = (await this.projectionStore.load(projection.name, tenant)) ?? projection.initial();
-            const next = reducer(current, event.payload);
-            await this.projectionStore.save(projection.name, next, tenant);
-            this.emit({
-                kind: "projection.folded",
-                projection: projection.name,
-                event: event.eventName,
-                tenant,
-                durationMs: performance.now() - t0,
-                envelope,
-                appName: this.appName,
-                ts: new Date().toISOString(),
-            });
+            try {
+                const current = (await this.projectionStore.load(projection.name, tenant)) ?? projection.initial();
+                const next = reducer(current, event.payload);
+                await this.projectionStore.save(projection.name, next, tenant);
+                this.emit({
+                    kind: "projection.folded",
+                    projection: projection.name,
+                    event: event.eventName,
+                    tenant,
+                    durationMs: performance.now() - t0,
+                    envelope,
+                    appName: this.appName,
+                    ts: new Date().toISOString(),
+                });
+            }
+            catch (err) {
+                // Fold failed — surface a first-class telemetry record so
+                // observability can alarm on projection drift directly (gap 4).
+                // We re-throw so the surrounding apply path still fails fast;
+                // the only behavior change is that consumers no longer have to
+                // deduce drift from missing `projection.folded` records.
+                this.emit({
+                    kind: "projection.failed",
+                    projection: projection.name,
+                    event: event.eventName,
+                    tenant,
+                    durationMs: performance.now() - t0,
+                    error: serializeError(err),
+                    envelope,
+                    appName: this.appName,
+                    ts: new Date().toISOString(),
+                });
+                throw err;
+            }
         }
     }
     // ─── Internal: actor dispatch ────────────────────────────────────
@@ -747,6 +1069,21 @@ export class Runtime {
         return payload[actor.key];
     }
     async applyEventToActor(actor, key, tenant, event, candidateReactions, envelope) {
+        // Per-(actor, key, tenant) lock around the load → reduce → save
+        // window. Without it, two concurrent dispatches racing for the same
+        // actor key both observe the same pre-state and the second save
+        // wins — silent invariant loss. Production adapters (Mongo, SQL)
+        // should treat lockKey as a no-op and rely on row-level locks; the
+        // in-memory store needs it explicitly.
+        const release = (await this.actorStore.lockKey?.(actor.name, key, tenant)) ?? (() => { });
+        try {
+            await this.applyEventToActorLocked(actor, key, tenant, event, candidateReactions, envelope);
+        }
+        finally {
+            release();
+        }
+    }
+    async applyEventToActorLocked(actor, key, tenant, event, candidateReactions, envelope) {
         const existing = await this.actorStore.load(actor.name, key, tenant);
         const instance = existing ?? createInitialInstance(actor, key, tenant);
         const matching = candidateReactions.find((c) => c.state === instance.state);
@@ -813,6 +1150,31 @@ export class Runtime {
                 await hook(actor, key, instance.state, nextStateName, event, envelope);
             }
         }
+        // Per-actor `actor.transition:<name>` hook — named, observable in
+        // listHooks(), tap-able by plugins via runtime.ensureActorTransitionHook.
+        // Runs only on actual transitions (state changed) so observers don't
+        // see no-op events.
+        if (stateChanged) {
+            const perActorHook = this.perActorHooks.get(actor.name);
+            if (perActorHook) {
+                try {
+                    await perActorHook.run({
+                        actor,
+                        key,
+                        fromState: instance.state,
+                        toState: nextStateName,
+                        triggeringEvent: event,
+                        envelope,
+                    });
+                }
+                catch (err) {
+                    loggerForEnvelope(this.logger, envelope).error(`actor.transition hook threw`, {
+                        actor: actor.name,
+                        error: err?.message,
+                    });
+                }
+            }
+        }
     }
     computeTimersForState(actor, stateName, actorKey) {
         const stateConfig = actor.states[stateName];
@@ -913,7 +1275,101 @@ export class Runtime {
                         });
                     },
                 };
-                await workflow._fire(event, fireCtx);
+                // Per-workflow `workflow.fire:<name>` hook — observation-only.
+                // Runs BEFORE the saga fires so chain steps see input + context;
+                // failures here are logged, never block the saga. Chain steps
+                // intending to gate workflow execution should subscribe to the
+                // `WorkflowFiring` framework event (future surface) — the hook
+                // is for telemetry + drift detection.
+                const perWorkflowHook = this.perWorkflowHooks.get(workflow.name);
+                if (perWorkflowHook) {
+                    try {
+                        await perWorkflowHook.run({
+                            workflow,
+                            event,
+                            envelope,
+                            correlationKey,
+                        });
+                    }
+                    catch (err) {
+                        log.error(`workflow.fire hook threw`, {
+                            workflow: workflow.name,
+                            error: err?.message,
+                        });
+                    }
+                }
+                // Honor the workflow's retry policy around `_fire`. Without a
+                // declared policy, the historical contract holds: one attempt,
+                // failure emits `reaction.failed` and re-raises. With a policy,
+                // we retry per the same back-off math the action dispatch loop
+                // uses; each failure emits `reaction.failed` with attempt info,
+                // and the FINAL failure additionally emits `reaction.exhausted`
+                // so alarms can fire on saga death distinctly from transient
+                // drift.
+                const retry = workflow.retry;
+                const maxAttempts = 1 + (retry?.max ?? 0);
+                let attempt = 0;
+                let lastError;
+                let fired = false;
+                let exhausted = false;
+                while (attempt < maxAttempts) {
+                    attempt++;
+                    try {
+                        if (attempt > 1) {
+                            const delay = computeBackoff(retry, attempt - 1);
+                            if (delay > 0)
+                                await sleep(delay);
+                        }
+                        await workflow._fire(event, fireCtx);
+                        fired = true;
+                        break;
+                    }
+                    catch (err) {
+                        lastError = err;
+                        const willRetry = attempt < maxAttempts;
+                        this.emit({
+                            kind: "reaction.failed",
+                            sourceEvent: event.eventName,
+                            error: serializeError(err),
+                            envelope,
+                            appName: this.appName,
+                            ts: new Date().toISOString(),
+                            workflow: workflow.name,
+                            attempt,
+                            maxAttempts,
+                            willRetry,
+                        });
+                        if (!willRetry && retry) {
+                            // Only fire `reaction.exhausted` when retry was actually
+                            // declared — otherwise a one-shot failure (no policy) is
+                            // semantically just "the saga threw," not "the saga
+                            // burned through its retry budget." Alarms should target
+                            // the policy-aware signal.
+                            this.emit({
+                                kind: "reaction.exhausted",
+                                workflow: workflow.name,
+                                sourceEvent: event.eventName,
+                                attempts: attempt,
+                                error: serializeError(err),
+                                envelope,
+                                appName: this.appName,
+                                ts: new Date().toISOString(),
+                            });
+                            exhausted = true;
+                        }
+                    }
+                }
+                if (!fired) {
+                    // Mark so the outer catch knows the loop already emitted
+                    // `reaction.failed` for this failure — avoids double-emit.
+                    // `exhausted` is unused for marking; the loop emits one
+                    // `reaction.failed` per attempt regardless of policy.
+                    void exhausted;
+                    if (lastError && typeof lastError === "object") {
+                        lastError.__nwireWorkflowEmitted = true;
+                    }
+                    throw lastError;
+                }
                 this.emit({
                     kind: "reaction.fired",
                     sourceEvent: event.eventName,
@@ -924,26 +1380,40 @@ export class Runtime {
                 });
             }
             catch (err) {
-                this.emit({
-                    kind: "reaction.failed",
-                    sourceEvent: event.eventName,
-                    error: serializeError(err),
-                    envelope,
-                    appName: this.appName,
-                    ts: new Date().toISOString(),
-                });
+                // The retry loop above already emitted `reaction.failed` for
+                // every saga-body failure. If we see one tagged with the
+                // internal marker, the loop owns the telemetry — skip the
+                // duplicate emission here. Anything untagged (correlate() throws,
+                // hook bug, etc.) lands as a single bare `reaction.failed`.
+                if (!err?.__nwireWorkflowEmitted) {
+                    this.emit({
+                        kind: "reaction.failed",
+                        sourceEvent: event.eventName,
+                        error: serializeError(err),
+                        envelope,
+                        appName: this.appName,
+                        ts: new Date().toISOString(),
+                        workflow: workflow.name,
+                    });
+                }
                 throw err;
             }
         }
     }
     // ─── Internal: handler context ───────────────────────────────────
-    buildHandlerContext(envelope, log) {
+    buildHandlerContext(envelope, log, signal) {
         const self = this;
         const logger = log ?? loggerForEnvelope(self.logger, envelope);
+        // Child dispatches inherit the parent's signal so a caller-side abort
+        // travels through every nested `ctx.request(...)`. The runtime never
+        // mutates the incoming signal — handlers observe; the wire owns the
+        // controller.
+        const ctxSignal = signal ?? new AbortController().signal;
         const ctx = {
             container: self.container,
             envelope,
             logger,
+            signal: ctxSignal,
             resolve(name) {
                 return self.container.resolve(name);
             },
@@ -951,7 +1421,7 @@ export class Runtime {
                 return envelope.messageId;
             },
             async request(action, input) {
-                const result = await self.dispatch(action, input, envelope);
+                const result = await self.dispatch(action, input, envelope, { signal: ctxSignal });
                 return result;
             },
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -963,7 +1433,7 @@ export class Runtime {
             async send(action, input) {
                 // For now, send is identical to request but result is ignored.
                 // Real fire-and-forget arrives with the queue transport.
-                await self.dispatch(action, input, envelope);
+                await self.dispatch(action, input, envelope, { signal: ctxSignal });
             },
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             async use(actor, id) {