@nwire/forge 0.8.0 → 0.9.0

package/dist/runtime.js

@@ -19,38 +19,20 @@
  *   - Events fan out to actors first, then workflow reactions, then
  *     projections.
  */
-import { rootContainer } from "@nwire/container";
 import { hook } from "@nwire/hooks";
+import { Runtime as RuntimeBase, serializeError, } from "@nwire/app";
 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 { InMemoryActorStore, createInitialInstance, ActorVersionConflictError, } 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 { loggerForEnvelope } from "@nwire/logger";
 import { InMemoryDeadLetterSink, buildDeadLetterEntry, } from "@nwire/dead-letter";
-import { FrameworkEventBus } from "./framework-event-bus.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) {
-        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 {
+export class Runtime extends RuntimeBase {
     handlers = new Map();
     actors = new Map();
     /**
@@ -83,19 +65,9 @@ export class Runtime {
     externalCalls = new Map();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     externalCallExecutors = new Map();
-    container;
     actorStore;
     projectionStore;
-    logger;
     deadLetterSink;
-    /**
-     * 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
@@ -118,8 +90,6 @@ export class Runtime {
     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. */
@@ -128,82 +98,53 @@ export class Runtime {
     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
-     * fires events at the appropriate sites in `dispatch`, `start`, `stop`.
-     */
-    frameworkEvents;
     constructor(options = {}) {
-        this.container = options.container ?? rootContainer;
+        // Container / logger / appName / frameworkEvents / dispatchHook / use /
+        // adoptHook / onTelemetry / offTelemetry / emit / getContainer are all
+        // owned by the base. Forge layers the CQRS engine on top.
+        super({
+            container: options.container,
+            logger: options.logger,
+            appName: options.appName,
+            events: builtInFrameworkEvents,
+        });
         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.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
-        // 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,
-            });
-        });
-        // 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");
+        // Pin the innermost dispatch step that calls forge's per-action retry +
+        // handler-invocation + event-publishing closure. priority `-Infinity`
+        // keeps user `runtime.use()` middleware strictly outside it.
         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`
-     * so plugins can write `runtime.onFramework(ActionDispatching, ...)`.
-     * Returns an unsubscribe function.
+     * Tap into the canonical telemetry stream — narrowed to forge's widened
+     * `Telemetry` union. Delegates to the base `Runtime.onTelemetry` but
+     * locks the listener's record type to forge's CQRS-aware shape so
+     * `rec.kind === "event.published"` narrowing works for consumers.
      */
-    onFramework(event, handler, priority = 0) {
-        return this.frameworkEvents.on(event, handler, priority);
+    onTelemetry(listener) {
+        return super.onTelemetry(listener);
+    }
+    offTelemetry(listener) {
+        super.offTelemetry(listener);
+    }
+    /**
+     * Register a dispatch middleware. Narrows the base `use(middleware)` to
+     * forge's tightened `DispatchMiddleware` shape so middleware authors
+     * see typed `action: ActionDefinition` / `ctx: HandlerContext`. The base
+     * runtime sees its `unknown`-typed shape; the cast is safe — every call
+     * site we control hands the same `(action, input, ctx)` triple forge's
+     * dispatcher pushes through `dispatchHook.run(...)`.
+     */
+    use(middleware) {
+        super.use(middleware);
     }
     /** Internal — createApp registers known external event names. */
     registerExternalEvent(eventName) {
@@ -213,67 +154,10 @@ 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);
     }
-    /**
-     * 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) {
-        // 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) {
@@ -485,12 +369,27 @@ export class Runtime {
             throw new Error(`Runtime: no query registered with name "${queryName}".`);
         }
         const t0 = performance.now();
-        const validated = isValidated(input)
-            ? input
-            : markValidated(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,
@@ -509,9 +408,6 @@ export class Runtime {
     getProjectionStore() {
         return this.projectionStore;
     }
-    getContainer() {
-        return this.container;
-    }
     listHandlers() {
         return [...this.handlers.keys()];
     }
@@ -599,6 +495,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;
@@ -653,9 +555,7 @@ export class Runtime {
         // 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 validated = isValidated(input) ? input : markValidated(action.schema.parse(input));
         const log = loggerForEnvelope(this.logger, envelope);
         // Caller-side cancellation: every dispatch carries an AbortSignal on
         // ctx. When the caller doesn't supply one, we mint a never-aborted
@@ -698,7 +598,9 @@ export class Runtime {
             }
         }
         // 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);
@@ -854,9 +756,7 @@ export class Runtime {
             // 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 dedupKey = events.length === 1 ? parentEnvelope.messageId : `${parentEnvelope.messageId}#${i}`;
             const childEnvelope = deriveEnvelope(parentEnvelope);
             if (await this.idempotencyStore.seen(dedupKey)) {
                 this.emit({
@@ -906,41 +806,6 @@ export class Runtime {
             }
         }
     }
-    /**
-     * 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
@@ -1065,96 +930,109 @@ export class Runtime {
         }
     }
     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);
-        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,
+        const maxOccRetries = 3;
+        for (let occAttempt = 0; occAttempt < maxOccRetries; occAttempt++) {
+            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,
-                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);
+                state: nextStateName,
+                data: validated,
+                activeTimers: nextTimers,
+                version: instance.version,
+            };
+            try {
+                await this.actorStore.save(nextInstance, { expectedVersion: instance.version });
             }
-        }
-        // 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) {
+                if (err instanceof ActorVersionConflictError && occAttempt < maxOccRetries - 1) {
+                    continue;
                 }
-                catch (err) {
-                    loggerForEnvelope(this.logger, envelope).error(`actor.transition hook threw`, {
-                        actor: actor.name,
-                        error: err?.message,
-                    });
+                throw err;
+            }
+            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);
+                }
+            }
+            // 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,
+                        });
+                    }
                 }
             }
+            return;
         }
     }
     computeTimersForState(actor, stateName, actorKey) {
@@ -1402,8 +1280,7 @@ export class Runtime {
                 return envelope.messageId;
             },
             async request(action, input) {
-                const result = await self.dispatch(action, input, envelope, { signal: ctxSignal });
-                return result;
+                return self.dispatch(action, input, envelope, { signal: ctxSignal });
             },
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             async query(