@nwire/forge 0.7.0

package/dist/runtime.js

@@ -0,0 +1,1083 @@
+/**
+ * Runtime — the framework's dispatch + apply pipeline.
+ *
+ * Responsibilities:
+ *   1. Register actions, actors, handlers, and `when` reactions.
+ *   2. `dispatch(action, input, envelope?)` — runs the action's handler,
+ *      collects returned events, atomically: applies them to actors, runs
+ *      reactions, schedules new timers, cancels old timers.
+ *   3. `publish(events, envelope)` — runs the apply-actors-and-reactions step
+ *      for events produced outside a handler (rare; mostly internal).
+ *   4. `request(action, input)` — invoked from inside a handler to call
+ *      another action with a derived child envelope. Returns the inner
+ *      handler's result.
+ *
+ * The runtime owns commit atomicity:
+ *   - All actor state changes from one event-publish either ALL persist or
+ *     NONE persist (in-memory is naturally atomic; persistent stores rely
+ *     on the adapter's transaction primitives).
+ *   - Events fan out to actors first, then workflow reactions, then
+ *     projections.
+ */
+import { rootContainer } from "@nwire/container";
+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 { 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";
+/** Serialize an unknown thrown value into the canonical SerializedError shape. */
+function serializeError(err) {
+    if (err instanceof Error) {
+        const out = {
+            name: err.name,
+            message: err.message,
+            stack: err.stack,
+        };
+        for (const k of Object.keys(err)) {
+            if (k === "name" || k === "message" || k === "stack")
+                continue;
+            out[k] = err[k];
+        }
+        return out;
+    }
+    return { name: "NonError", message: String(err) };
+}
+export class Runtime {
+    handlers = new Map();
+    actors = new Map();
+    /**
+     * Workflows keyed by event name. Built from each registered workflow's
+     * `subscribedEvents`. On publish, every workflow listening to an event
+     * gets `_fire`d with runtime-bound effects.
+     */
+    workflowsByEvent = new Map();
+    /**
+     * Per-workflow instance state — keyed first by workflow name, then by
+     * correlation key. In-memory for slice 1; future adapters (Mongo, Redis)
+     * plug in via a WorkflowStore contract analogous to ActorStore.
+     */
+    workflowInstances = new Map();
+    workflowInstanceStore(workflowName) {
+        let store = this.workflowInstances.get(workflowName);
+        if (!store) {
+            store = new Map();
+            this.workflowInstances.set(workflowName, store);
+        }
+        return store;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    projections = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    projectionsByEvent = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    queries = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    externalCalls = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    externalCallExecutors = new Map();
+    container;
+    actorStore;
+    projectionStore;
+    logger;
+    deadLetterSink;
+    middlewares = [];
+    actorTransitionHooks = [];
+    bus;
+    publishToBus;
+    appName;
+    telemetryListeners = [];
+    /** Known external events — set by createApp from modules' needs.externalEvents. */
+    externalEventNames = new Set();
+    /** Public-event names (visibility: 'public') — set by createApp from modules' events. */
+    publicEventNames = new Set();
+    /** Saga timer store (default in-memory; pluggable via RuntimeOptions). */
+    workflowTimerStore;
+    /**
+     * Framework event bus — lifecycle + dispatch hooks. Plugins and apps
+     * subscribe with `runtime.onFramework(Event, handler)`; the runtime
+     * fires events at the appropriate sites in `dispatch`, `start`, `stop`.
+     */
+    frameworkEvents;
+    constructor(options = {}) {
+        this.container = options.container ?? rootContainer;
+        this.actorStore = options.actorStore ?? new InMemoryActorStore();
+        this.projectionStore = options.projectionStore ?? new InMemoryProjectionStore();
+        this.logger = options.logger ?? new NoopLogger();
+        this.deadLetterSink = options.deadLetterSink ?? new InMemoryDeadLetterSink();
+        this.bus = options.bus;
+        this.publishToBus = options.publishToBus ?? false;
+        this.appName = options.appName ?? "app";
+        this.workflowTimerStore = options.workflowTimerStore ?? new InMemoryWorkflowTimerStore();
+        this.frameworkEvents = new FrameworkEventBus(this.logger);
+        // 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
+        // domain events. `namespace` = the second dotted segment so dev
+        // logger / Studio can group by phase (app / plugin / wire / …).
+        this.frameworkEvents.onFire((rec) => {
+            const parts = rec.eventName.split(".");
+            const namespace = parts.length >= 2 ? parts[1] : "framework";
+            this.emit({
+                kind: "lifecycle",
+                event: rec.eventName,
+                namespace,
+                payload: rec.payload,
+                phase: rec.phase,
+                appName: this.appName,
+                ts: rec.ts,
+            });
+        });
+    }
+    /**
+     * Subscribe to a framework event. Sugar over `runtime.frameworkEvents.on`
+     * so plugins can write `runtime.onFramework(ActionDispatching, ...)`.
+     * Returns an unsubscribe function.
+     */
+    onFramework(event, handler, priority = 0) {
+        return this.frameworkEvents.on(event, handler, priority);
+    }
+    /** Internal — createApp registers known external event names. */
+    registerExternalEvent(eventName) {
+        this.externalEventNames.add(eventName);
+    }
+    /** Internal — createApp registers public event names (visibility: 'public'). */
+    registerPublicEvent(eventName) {
+        this.publicEventNames.add(eventName);
+    }
+    /** Internal — createApp registers actor-transition hooks from plugins. */
+    registerActorTransitionHook(hook) {
+        this.actorTransitionHooks.push(hook);
+    }
+    /**
+     * 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.
+     */
+    use(middleware) {
+        this.middlewares.push(middleware);
+    }
+    // ─── Registration ────────────────────────────────────────────────
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    registerHandler(handler) {
+        const name = handler.action.name;
+        if (this.handlers.has(name)) {
+            throw new Error(`Runtime: handler for action "${name}" already registered.`);
+        }
+        this.handlers.set(name, handler);
+    }
+    registerActor(actor) {
+        if (this.actors.has(actor.name)) {
+            throw new Error(`Runtime: actor "${actor.name}" already registered.`);
+        }
+        this.actors.set(actor.name, actor);
+    }
+    /** Internal — createApp registers each module's workflows. */
+    registerWorkflow(workflow) {
+        for (const eventName of workflow.subscribedEvents) {
+            const list = this.workflowsByEvent.get(eventName) ?? [];
+            list.push(workflow);
+            this.workflowsByEvent.set(eventName, list);
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    registerProjection(projection) {
+        if (this.projections.has(projection.name)) {
+            throw new Error(`Runtime: projection "${projection.name}" already registered.`);
+        }
+        this.projections.set(projection.name, projection);
+        for (const event of projection.listens) {
+            const list = this.projectionsByEvent.get(event.name) ?? [];
+            list.push(projection);
+            this.projectionsByEvent.set(event.name, list);
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    registerQuery(query) {
+        if (this.queries.has(query.name)) {
+            throw new Error(`Runtime: query "${query.name}" already registered.`);
+        }
+        this.queries.set(query.name, query);
+    }
+    /**
+     * Register an external-call declaration. Modules announce their external
+     * calls so Studio + the static graph see them; wires (adapters) call
+     * `registerExternalCallExecutor` to provide the transport.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    registerExternalCall(def) {
+        if (this.externalCalls.has(def.name)) {
+            throw new Error(`Runtime: external call "${def.name}" already registered.`);
+        }
+        this.externalCalls.set(def.name, def);
+    }
+    /**
+     * Bind an executor (HTTP client / SDK wrapper / test mock) to a declared
+     * external call. Lookup is by `def.name`. Called by wires/adapters at
+     * boot. Idempotent: re-registering replaces the executor (useful for
+     * swapping mocks in tests).
+     */
+    registerExternalCallExecutor(def, executor) {
+        this.externalCallExecutors.set(def.name, executor);
+    }
+    async executeExternalCall(def, request, envelope) {
+        const validated = def.request.parse(request);
+        const executor = this.externalCallExecutors.get(def.name);
+        const idempotencyKey = def.idempotencyKey?.(validated);
+        const target = `${def.target.provider}/${def.target.endpoint}`;
+        if (!executor) {
+            const err = new Error(`Runtime.externalCall: no executor registered for "${def.name}". ` +
+                `Wires/adapters must call runtime.registerExternalCallExecutor() at boot.`);
+            this.emit({
+                kind: "external.call.failed",
+                call: def.name,
+                target,
+                attempt: 1,
+                willRetry: false,
+                error: serializeError(err),
+                envelope,
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+            throw err;
+        }
+        const retry = def.retry;
+        const maxAttempts = 1 + (retry?.max ?? 0);
+        let attempt = 0;
+        let lastError;
+        while (attempt < maxAttempts) {
+            attempt++;
+            this.emit({
+                kind: "external.call.started",
+                call: def.name,
+                target,
+                idempotencyKey,
+                envelope,
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+            const t0 = performance.now();
+            try {
+                if (attempt > 1) {
+                    const delay = computeBackoff(retry, attempt - 1);
+                    if (delay > 0)
+                        await sleep(delay);
+                }
+                const raw = await executor(validated, { idempotencyKey, attempt });
+                const response = def.response ? def.response.parse(raw) : raw;
+                this.emit({
+                    kind: "external.call.completed",
+                    call: def.name,
+                    target,
+                    durationMs: performance.now() - t0,
+                    idempotencyKey,
+                    envelope,
+                    appName: this.appName,
+                    ts: new Date().toISOString(),
+                });
+                return response;
+            }
+            catch (err) {
+                lastError = err;
+                this.emit({
+                    kind: "external.call.failed",
+                    call: def.name,
+                    target,
+                    attempt,
+                    willRetry: attempt < maxAttempts,
+                    error: serializeError(err),
+                    envelope,
+                    appName: this.appName,
+                    ts: new Date().toISOString(),
+                });
+            }
+        }
+        throw lastError;
+    }
+    // ─── Query execution ─────────────────────────────────────────────
+    async query(queryName, input, tenant = "") {
+        const query = this.queries.get(queryName);
+        if (!query) {
+            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));
+        this.emit({
+            kind: "query.executed",
+            query: queryName,
+            input: validated,
+            durationMs: performance.now() - t0,
+            tenant,
+            appName: this.appName,
+            ts: new Date().toISOString(),
+        });
+        return result;
+    }
+    // ─── Introspection ───────────────────────────────────────────────
+    getActorStore() {
+        return this.actorStore;
+    }
+    getProjectionStore() {
+        return this.projectionStore;
+    }
+    getContainer() {
+        return this.container;
+    }
+    listHandlers() {
+        return [...this.handlers.keys()];
+    }
+    listActors() {
+        return [...this.actors.keys()];
+    }
+    listProjections() {
+        return [...this.projections.keys()];
+    }
+    listQueries() {
+        return [...this.queries.keys()];
+    }
+    listExternalCalls() {
+        return [...this.externalCalls.keys()];
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getExternalCall(name) {
+        return this.externalCalls.get(name);
+    }
+    // ─── Timer firing (durable scheduler primitive) ──────────────────
+    /**
+     * Walk every registered actor's instances; for each `activeTimers[name]`
+     * with `fireAt <= now`, dispatch the timer's action. Removes fired timers
+     * from the instance's `activeTimers` map.
+     *
+     * Returns the count of timers that fired. Idempotent: a timer's `fireAt`
+     * is not bumped, so a second call after `now` advances will not re-fire
+     * the same timer (it was removed).
+     *
+     * For tests: pass `now` to fast-forward (`runtime.fireDueTimers(Date.now() + 3 * 86400_000)`).
+     * For production: a transport (BullMQ, polling worker) calls this on an
+     * interval; see `startTimerScheduler(app, intervalMs)` in `create-app.ts`.
+     */
+    async fireDueTimers(now = Date.now()) {
+        let fired = 0;
+        for (const actor of this.actors.values()) {
+            const instances = await this.actorStore.listInstances(actor.name);
+            for (const instance of instances) {
+                const due = [];
+                for (const [timerName, handle] of Object.entries(instance.activeTimers)) {
+                    if (handle.fireAt <= now) {
+                        due.push([timerName, handle]);
+                    }
+                }
+                if (due.length === 0)
+                    continue;
+                // Remove fired timers BEFORE dispatching, so handlers that
+                // re-enter `fireDueTimers` (rare but possible) don't see them.
+                const remainingTimers = {};
+                for (const [name, handle] of Object.entries(instance.activeTimers)) {
+                    if (handle.fireAt > now)
+                        remainingTimers[name] = handle;
+                }
+                await this.actorStore.save({
+                    ...instance,
+                    activeTimers: remainingTimers,
+                });
+                // Dispatch each fired timer's action in the actor's tenant
+                // scope so the handler chain stays inside the right partition.
+                const tenantEnvelope = seedEnvelope({
+                    tenant: instance.tenant || undefined,
+                });
+                for (const [timerName, handle] of due) {
+                    const action = this.findActionByName(handle.action);
+                    if (!action) {
+                        // Action not registered — skip gracefully; the timer
+                        // fired but its target is gone.
+                        continue;
+                    }
+                    this.emit({
+                        kind: "timer.fired",
+                        actor: actor.name,
+                        key: instance.key,
+                        timer: timerName,
+                        action: handle.action,
+                        lateByMs: Math.max(0, now - handle.fireAt),
+                        tenant: instance.tenant,
+                        appName: this.appName,
+                        ts: new Date().toISOString(),
+                    });
+                    await this.dispatch(action, handle.input, tenantEnvelope);
+                    fired++;
+                }
+            }
+        }
+        return fired;
+    }
+    findActionByName(name) {
+        const handler = this.handlers.get(name);
+        return handler?.action;
+    }
+    /**
+     * Drain every due saga timer from the workflow timer store and route
+     * each as a synthetic event back into the originating workflow. The
+     * store removes drained timers atomically (see `WorkflowTimerStore`
+     * contract); calling `fireDueWorkflowTimers` twice with the same `now`
+     * MUST be a no-op the second time.
+     *
+     * Returns the count of timers fired.
+     *
+     * Tests: pass `now` to fast-forward
+     * (`runtime.fireDueWorkflowTimers(new Date(Date.now() + 8 * 86400_000))`).
+     * Production: the same polling loop that calls `fireDueTimers` calls
+     * this — they share the timer tick infrastructure.
+     */
+    async fireDueWorkflowTimers(now = new Date()) {
+        let fired = 0;
+        const envelope = seedEnvelope({});
+        for await (const timer of this.workflowTimerStore.drainDue(now)) {
+            // Synthesize an event so the standard `runWorkflows` path handles
+            // routing. The event name is the canonical timer name; the payload
+            // carries through what `schedule()` was called with.
+            //
+            // Critical: the timer record carries the originating saga's
+            // `correlationKey`. We must thread it through so the workflow loads
+            // the right instance (the one that scheduled the timer) — not a
+            // fresh "__default__" instance. The synthetic timer event has no
+            // shape the user's `correlate()` map can recognize.
+            const eventName = timerEventName(timer.workflowName, timer.timerName);
+            await this.runWorkflows({ eventName, payload: timer.payload }, envelope, timer.correlationKey);
+            fired++;
+        }
+        return fired;
+    }
+    // ─── Dispatch ────────────────────────────────────────────────────
+    /**
+     * 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) {
+        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);
+        const log = loggerForEnvelope(this.logger, envelope);
+        const ctx = this.buildHandlerContext(envelope, log);
+        this.emit({
+            kind: "action.dispatched",
+            action: action.name,
+            input: validated,
+            envelope,
+            appName: this.appName,
+            ts: new Date().toISOString(),
+        });
+        const startedAt = performance.now();
+        // Framework event: ActionDispatching — interceptable. A subscriber
+        // returning `false` cleanly cancels the dispatch (no throw, no events,
+        // empty handler return). Throwing from a subscriber fails the dispatch
+        // as if the handler itself threw.
+        const dispatchAllowed = await this.frameworkEvents.fire(ActionDispatching, {
+            action,
+            input: validated,
+            ctx,
+        });
+        if (!dispatchAllowed) {
+            return undefined;
+        }
+        // Core: retry loop + handler invocation + event publishing.
+        // Returns the raw handler return for the dispatcher to type-cast.
+        const core = async () => {
+            const retry = action.retry;
+            const maxAttempts = 1 + (retry?.max ?? 0);
+            let attempt = 0;
+            let lastError;
+            while (attempt < maxAttempts) {
+                attempt++;
+                try {
+                    if (attempt > 1) {
+                        const delay = computeBackoff(retry, attempt - 1);
+                        log.warn(`retrying handler`, {
+                            action: action.name,
+                            attempt,
+                            maxAttempts,
+                            delayMs: delay,
+                        });
+                        if (delay > 0)
+                            await sleep(delay);
+                    }
+                    const rawResult = await handler.handler(validated, ctx);
+                    const events = normalizeEventReturn(rawResult ?? null);
+                    if (events.length > 0) {
+                        await this.publish(events, envelope);
+                    }
+                    const durationMs = performance.now() - startedAt;
+                    this.emit({
+                        kind: "action.completed",
+                        action: action.name,
+                        durationMs,
+                        emittedEvents: events.map((e) => e.eventName),
+                        envelope,
+                        appName: this.appName,
+                        ts: new Date().toISOString(),
+                    });
+                    // Framework event: ActionCompleted (parallel, observable).
+                    // Don't await — observers shouldn't block the response path.
+                    void this.frameworkEvents.fire(ActionCompleted, {
+                        action,
+                        input: validated,
+                        result: rawResult ?? undefined,
+                        durationMs,
+                    });
+                    return rawResult ?? undefined;
+                }
+                catch (err) {
+                    lastError = err;
+                    log.error(`handler threw`, {
+                        action: action.name,
+                        attempt,
+                        maxAttempts,
+                        error: err?.message,
+                    });
+                    this.emit({
+                        kind: "action.failed",
+                        action: action.name,
+                        attempt,
+                        maxAttempts,
+                        willRetry: attempt < maxAttempts,
+                        error: serializeError(err),
+                        envelope,
+                        appName: this.appName,
+                        ts: new Date().toISOString(),
+                    });
+                    if (attempt >= maxAttempts) {
+                        // Final failure — fire ActionFailed exactly once (not per
+                        // retry attempt; the observable view is "this dispatch failed",
+                        // not "the n-th attempt threw"). Parallel + non-awaited.
+                        void this.frameworkEvents.fire(ActionFailed, {
+                            action,
+                            input: validated,
+                            error: err,
+                            durationMs: performance.now() - startedAt,
+                        });
+                    }
+                }
+            }
+            // All attempts failed → dead-letter and re-raise.
+            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.emit({
+                kind: "dlq.recorded",
+                action: action.name,
+                attempts: attempt,
+                error: serializeError(lastError),
+                envelope,
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+            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;
+    }
+    /**
+     * Apply a batch of events: route to actors (state transitions + assigns +
+     * timer scheduling), fold projections, then fire workflows. Used internally
+     * by `dispatch` and exposed for tests and rare external publishes.
+     */
+    async publish(events, parentEnvelope) {
+        for (const event of events) {
+            const childEnvelope = deriveEnvelope(parentEnvelope);
+            // Ordering: actors → projections → workflows.
+            //   - actors first: state must be coherent before observers see it.
+            //   - projections second: workflows often read state via queries
+            //     (`ctx.request(query, ...)`), and chained dispatches via
+            //     `ctx.request(action, ...)` will themselves fold projections —
+            //     we must avoid stale reads, so projections fold before any
+            //     workflow-triggered chain begins.
+            //   - workflows last. Workflows produced events (translator pattern)
+            //     publish recursively through this same method, so the full
+            //     pipeline applies to derived events too.
+            await this.applyToActors(event, childEnvelope);
+            await this.foldProjections(event, childEnvelope);
+            await this.runWorkflows(event, childEnvelope);
+            // Telemetry tap — emit `event.published` after committed apply.
+            this.emit({
+                kind: "event.published",
+                event,
+                envelope: childEnvelope,
+                source: "in-process",
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+            // Cross-service fan-out: send public events to the bus AFTER the
+            // in-process apply succeeded. Subscribers in other services will
+            // call `applyExternalEvent` on their own runtime. Internal events
+            // (visibility: 'internal') stay in-process — explicit gate.
+            if (this.publishToBus && this.bus && this.publicEventNames.has(event.eventName)) {
+                await this.bus.publish({
+                    eventName: event.eventName,
+                    payload: event.payload,
+                    envelope: childEnvelope,
+                    origin: this.appName,
+                });
+            }
+        }
+    }
+    /**
+     * Tap into the canonical telemetry stream. One subscriber sees every kind:
+     * `action.dispatched` / `.completed` / `.failed`, `event.published`,
+     * `actor.transitioned`, `projection.folded`, `reaction.fired` / `.failed`,
+     * `query.executed`, `timer.scheduled` / `.fired`, `dlq.recorded`.
+     *
+     * Listeners run AFTER the corresponding lifecycle action commits — they
+     * observe what actually happened, not in-flight intent. Throwing in a
+     * listener is caught and logged; it never breaks domain dispatch.
+     *
+     * Returns an unsubscribe function.
+     */
+    onTelemetry(listener) {
+        this.telemetryListeners.push(listener);
+        return () => this.offTelemetry(listener);
+    }
+    offTelemetry(listener) {
+        const i = this.telemetryListeners.indexOf(listener);
+        if (i >= 0)
+            this.telemetryListeners.splice(i, 1);
+    }
+    emit(record) {
+        if (this.telemetryListeners.length === 0)
+            return;
+        for (const listener of this.telemetryListeners) {
+            try {
+                listener(record);
+            }
+            catch (err) {
+                // Best-effort — don't let a bad listener break dispatch.
+                // eslint-disable-next-line no-console
+                console.error("Runtime.onTelemetry listener threw:", err);
+            }
+        }
+    }
+    /**
+     * Apply an event that arrived from the cross-service bus. Same pipeline
+     * as `publish` (actors → projections → workflows) but does NOT re-publish
+     * to the bus — avoids fan-out loops between services. The runtime tracks
+     * which event names it declared as external (via createApp's wiring of
+     * modules' `needs.externalEvents`); calls for other names throw to catch
+     * misconfigured subscriptions early.
+     */
+    async applyExternalEvent(eventName, payload, envelope) {
+        if (!this.externalEventNames.has(eventName)) {
+            throw new Error(`Runtime.applyExternalEvent: "${eventName}" was not declared in any module's needs.externalEvents.`);
+        }
+        const event = { eventName, payload };
+        await this.applyToActors(event, envelope);
+        await this.foldProjections(event, envelope);
+        await this.runWorkflows(event, envelope);
+        this.emit({
+            kind: "event.published",
+            event,
+            envelope,
+            source: "external",
+            appName: this.appName,
+            ts: new Date().toISOString(),
+        });
+    }
+    async foldProjections(event, envelope) {
+        const projections = this.projectionsByEvent.get(event.eventName);
+        if (!projections || projections.length === 0)
+            return;
+        const tenant = envelope.tenant ?? "";
+        for (const projection of projections) {
+            const reducer = projection.on[event.eventName];
+            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(),
+            });
+        }
+    }
+    // ─── Internal: actor dispatch ────────────────────────────────────
+    async applyToActors(event, envelope) {
+        const tenant = envelope.tenant ?? "";
+        for (const actor of this.actors.values()) {
+            const reactionsForEvent = actor.eventIndex.get(event.eventName);
+            if (!reactionsForEvent || reactionsForEvent.length === 0)
+                continue;
+            const key = this.extractKey(event, actor);
+            if (key === undefined || key === null) {
+                // Event doesn't carry this actor's key — not addressed to it.
+                continue;
+            }
+            await this.applyEventToActor(actor, String(key), tenant, event, reactionsForEvent, envelope);
+        }
+    }
+    extractKey(event, actor) {
+        const payload = event.payload;
+        if (!payload || typeof payload !== "object")
+            return undefined;
+        return payload[actor.key];
+    }
+    async applyEventToActor(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);
+        if (!matching) {
+            // Actor is in a state that doesn't react to this event — silently
+            // skip. (Future: dead-letter / log; surfacing here is too noisy for
+            // events that fan out to many actors, only some of which match.)
+            return;
+        }
+        const stateConfig = actor.states[instance.state];
+        if (stateConfig?.final) {
+            // Defensive: a final state shouldn't have entries in eventIndex,
+            // but guard anyway.
+            return;
+        }
+        const partial = matching.reaction.assign
+            ? matching.reaction.assign(instance.data, event.payload)
+            : {};
+        const nextData = { ...instance.data, ...partial };
+        const nextStateName = matching.reaction.target ?? instance.state;
+        const nextStateConfig = actor.states[nextStateName];
+        if (!nextStateConfig) {
+            throw new Error(`Runtime: actor "${actor.name}" reaction targets undeclared state "${nextStateName}" from "${instance.state}".`);
+        }
+        // Schema validation on save — invalid partial → throw, atomically
+        // skip persistence, re-raise to caller.
+        const validated = actor.schema.parse(nextData);
+        const stateChanged = nextStateName !== instance.state;
+        const isNewActor = !existing;
+        // Timers are owned by a state, not the actor. Compute them on:
+        //   - state change (cancel old, schedule new), or
+        //   - actor creation (born into a state — schedule its timers).
+        const nextTimers = stateChanged || isNewActor
+            ? this.computeTimersForState(actor, nextStateName, key)
+            : instance.activeTimers;
+        const nextInstance = {
+            actorName: actor.name,
+            key,
+            tenant,
+            state: nextStateName,
+            data: validated,
+            activeTimers: nextTimers,
+        };
+        await this.actorStore.save(nextInstance);
+        if (stateChanged) {
+            this.emit({
+                kind: "actor.transitioned",
+                actor: actor.name,
+                key,
+                tenant,
+                from: instance.state,
+                to: nextStateName,
+                triggeringEvent: event.eventName,
+                envelope,
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+        }
+        // Fire actor-transition hooks (registered by plugins). Hooks run AFTER
+        // the save so they observe committed state. Errors propagate — plugins
+        // are infrastructure; we want loud failures, not silent skips.
+        if (this.actorTransitionHooks.length > 0 && stateChanged) {
+            for (const hook of this.actorTransitionHooks) {
+                await hook(actor, key, instance.state, nextStateName, event, envelope);
+            }
+        }
+    }
+    computeTimersForState(actor, stateName, actorKey) {
+        const stateConfig = actor.states[stateName];
+        if (!stateConfig?.after)
+            return {};
+        const now = Date.now();
+        const timers = {};
+        for (const [timerName, spec] of Object.entries(stateConfig.after)) {
+            const delayString = typeof spec === "string" ? timerName : spec.delay;
+            const action = typeof spec === "string" ? spec : spec.action;
+            const input = typeof spec === "string" || !spec.buildInput
+                ? { [actor.key]: actorKey }
+                : spec.buildInput({}, actorKey);
+            const handle = {
+                scheduledAt: now,
+                fireAt: now + parseDelay(delayString),
+                action,
+                input,
+            };
+            timers[timerName] = handle;
+            this.emit({
+                kind: "timer.scheduled",
+                actor: actor.name,
+                key: actorKey,
+                timer: timerName,
+                action,
+                fireAt: handle.fireAt,
+                tenant: "",
+                appName: this.appName,
+                ts: new Date().toISOString(),
+            });
+        }
+        return timers;
+    }
+    // ─── Internal: workflows ─────────────────────────────────────────
+    /**
+     * Fire every workflow subscribed to `event`. Each workflow receives a
+     * runtime-bound effects bag: `send`/`enqueue` go through `dispatch` for
+     * retry + telemetry parity with action handlers; `publish` goes back
+     * through `this.publish` so derived events flow through the full
+     * actors → projections → workflows pipeline (translator pattern).
+     *
+     * Telemetry emits as `workflow.fired` / `workflow.failed`.
+     */
+    async runWorkflows(event, envelope, 
+    /**
+     * Optional override for correlationKey. Used by `fireDueWorkflowTimers`
+     * to route a synthetic timer event back to the saga instance that
+     * scheduled it — `workflow.correlate(event)` can't determine the key
+     * from a synthetic timer payload alone.
+     */
+    correlationKeyOverride) {
+        const workflows = this.workflowsByEvent.get(event.eventName);
+        if (!workflows || workflows.length === 0)
+            return;
+        const log = loggerForEnvelope(this.logger, envelope).child({
+            event: event.eventName,
+        });
+        const handlerCtx = this.buildHandlerContext(envelope, log);
+        const self = this;
+        const baseEffects = {
+            async send(action, input) {
+                return handlerCtx.request(action, input);
+            },
+            async enqueue(action, input) {
+                await handlerCtx.send(action, input);
+            },
+            async publish(eventMsg) {
+                await self.publish([eventMsg], envelope);
+            },
+        };
+        for (const workflow of workflows) {
+            const t0 = performance.now();
+            try {
+                const store = this.workflowInstanceStore(workflow.name);
+                // Workflow correlation MUST include the tenant axis. Without it,
+                // two tenants with the same business key (e.g. subscriptionId)
+                // share a saga instance — the second tenant's PaymentFailed sees
+                // the first tenant's state. The override path (from timer fires)
+                // already carries tenant context; only derive when no override.
+                const userKey = workflow.correlate?.(event) ?? "__default__";
+                const tenantPrefix = envelope.tenant ? `${envelope.tenant}::` : "";
+                const correlationKey = correlationKeyOverride ?? `${tenantPrefix}${userKey}`;
+                const fireCtx = {
+                    ...baseEffects,
+                    load: (key) => store.get(key),
+                    save: (key, instance) => store.set(key, instance),
+                    drop: (key) => store.delete(key),
+                    correlationKey,
+                    scheduleTimer: async (timerName, delay, payload) => {
+                        await this.workflowTimerStore.schedule({
+                            id: randomUUID(),
+                            workflowName: workflow.name,
+                            correlationKey,
+                            timerName,
+                            fireAt: new Date(Date.now() + parseDelay(delay)).toISOString(),
+                            payload,
+                        });
+                    },
+                };
+                await workflow._fire(event, fireCtx);
+                this.emit({
+                    kind: "reaction.fired",
+                    sourceEvent: event.eventName,
+                    durationMs: performance.now() - t0,
+                    envelope,
+                    appName: this.appName,
+                    ts: new Date().toISOString(),
+                });
+            }
+            catch (err) {
+                this.emit({
+                    kind: "reaction.failed",
+                    sourceEvent: event.eventName,
+                    error: serializeError(err),
+                    envelope,
+                    appName: this.appName,
+                    ts: new Date().toISOString(),
+                });
+                throw err;
+            }
+        }
+    }
+    // ─── Internal: handler context ───────────────────────────────────
+    buildHandlerContext(envelope, log) {
+        const self = this;
+        const logger = log ?? loggerForEnvelope(self.logger, envelope);
+        const ctx = {
+            container: self.container,
+            envelope,
+            logger,
+            resolve(name) {
+                return self.container.resolve(name);
+            },
+            get requestId() {
+                return envelope.messageId;
+            },
+            async request(action, input) {
+                const result = await self.dispatch(action, input, envelope);
+                return result;
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            async query(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            queryDef, input) {
+                return self.query(queryDef.name, input, envelope.tenant ?? "");
+            },
+            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);
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            async use(actor, id) {
+                return self.loadActorView(actor, id, envelope);
+            },
+            async externalCall(call, request) {
+                return self.executeExternalCall(call, request, envelope);
+            },
+        };
+        return ctx;
+    }
+    // ─── Internal: actor view (ctx.use) ──────────────────────────────
+    async loadActorView(actor, id, envelope) {
+        if (!this.actors.has(actor.name)) {
+            throw new Error(`Runtime.use: actor "${actor.name}" is not registered. ` +
+                `Add it to a module's manifest.actors and pass that module to createApp.`);
+        }
+        const loaded = await this.actorStore.load(actor.name, id, envelope.tenant ?? "");
+        // Virgin instance — let `create` methods bootstrap a new actor.
+        // The bootstrap event flows through the actor's `on` transitions and
+        // populates state for subsequent dispatches.
+        const instance = loaded ?? {
+            name: actor.name,
+            key: id,
+            state: actor.initial,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            data: {},
+            version: 0,
+            timers: [],
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const view = {
+            state: instance.data,
+            key: instance.key,
+            stateName: instance.state,
+        };
+        // Closure-form actor: bind methods via the closure binder. recordThat
+        // calls accumulate events; we publish them after each method call.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const closureBinder = actor.closureBinder;
+        if (closureBinder) {
+            const bound = closureBinder(instance.data, instance.key);
+            for (const [methodName, fn] of Object.entries(bound.methods)) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                view[methodName] = async (...args) => {
+                    // Re-bind for the live state at call time (the actor may have been
+                    // updated since the view was created).
+                    const fresh = await this.actorStore.load(actor.name, id, envelope.tenant ?? "");
+                    const liveData = fresh?.data ?? instance.data;
+                    const localBound = closureBinder(liveData, instance.key);
+                    const localFn = localBound.methods[methodName];
+                    if (!localFn) {
+                        throw new Error(`Actor "${actor.name}" has no method "${methodName}".`);
+                    }
+                    const result = localFn(...args);
+                    // Publish recorded events through the runtime pipeline.
+                    if (localBound.recorded.length > 0) {
+                        const messages = localBound.recorded.map((r) => ({
+                            eventName: r.eventName,
+                            payload: r.payload,
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        }));
+                        await this.publish(messages, envelope);
+                    }
+                    return result;
+                };
+            }
+            return view;
+        }
+        // Classic / schema-bound-object form: methods are (state, ...args) => event.
+        const methods = actor.methods ?? {};
+        for (const [methodName, fn] of Object.entries(methods)) {
+            const method = fn;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            view[methodName] = (...args) => method(instance.data, ...args);
+        }
+        return view;
+    }
+    /** Test/inspection seam — read what's in the DLQ. */
+    getDeadLetterSink() {
+        return this.deadLetterSink;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function computeBackoff(retry, attemptIndex) {
+    if (!retry)
+        return 0;
+    const base = retry.baseDelayMs ?? 100;
+    const cap = retry.maxDelayMs ?? 30_000;
+    if (retry.backoff === "fixed")
+        return Math.min(base, cap);
+    // Exponential default — 2^(attempt-1) * base, capped.
+    return Math.min(Math.floor(Math.pow(2, attemptIndex - 1) * base), cap);
+}
+/**
+ * Parse a delay string like '3d', '90s', '4h' into milliseconds.
+ * Supports: ms, s, m, h, d. Numbers without units treated as milliseconds.
+ */
+export function parseDelay(value) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/.exec(value);
+    if (!match) {
+        throw new Error(`Runtime: cannot parse delay "${value}". Expected '3d', '90s', '4h', '500ms'.`);
+    }
+    const n = Number(match[1]);
+    const unit = match[2] ?? "ms";
+    const multipliers = {
+        ms: 1,
+        s: 1000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+    };
+    return n * (multipliers[unit] ?? 1);
+}
+//# sourceMappingURL=runtime.js.map