@nwire/forge 0.7.0

package/dist/define-workflow.js

@@ -0,0 +1,345 @@
+/**
+ * `defineWorkflow` — the unified primitive for everything event-driven that
+ * isn't an actor. Reactions, translators, and sagas all use this same call.
+ *
+ * Three sophistication levels live in one closure:
+ *
+ *   • Observer / translator — one event in → side effects out.
+ *   • Reaction               — one event in → dispatch an action.
+ *   • Saga                   — multi-event correlated state machine.
+ *
+ * The framework picks the runtime path:
+ *   • No `data` and no `states` → plain async dispatch (zero overhead).
+ *   • `data` or `states` declared → per-correlation instance state, transitions
+ *     via handler return values, XState-equivalent overlap semantics
+ *     (state-scoped handlers shadow root-level ones for the current state).
+ *
+ * Example shapes appear in `packages/nwire-docs/concepts/workflow.md`.
+ */
+import { markable } from "./public-marker.js";
+import { timerEventName } from "./workflow-timer-store.js";
+/**
+ * `complete` — framework-emitted pseudo-event that fires when a stateful
+ * workflow enters any state marked `final: true`. Exposed on the closure
+ * context so `on(complete, …)` can register a finalization hook.
+ */
+export const COMPLETE_EVENT_NAME = "__nwire/workflow.complete";
+function isStateful(opts) {
+    if (!opts)
+        return false;
+    return "data" in opts || "states" in opts;
+}
+// Implementation signature — internal, accepts the union.
+export function defineWorkflow(name, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+closure, options) {
+    const stateful = isStateful(options);
+    const stateSpecs = stateful ? (options.states ?? {}) : {};
+    const finalStates = new Set();
+    for (const [n, spec] of Object.entries(stateSpecs)) {
+        if (spec.final)
+            finalStates.add(n);
+    }
+    const initialState = stateful
+        ? Object.keys(stateSpecs).find((n) => !finalStates.has(n))
+        : undefined;
+    // ── Probe pass: subscribed events, declared dispatches, correlations. ──
+    const subscribed = new Set();
+    const dispatched = new Set();
+    const correlateTable = new Map();
+    const completeMarker = {
+        $kind: "workflow.complete",
+        name: COMPLETE_EVENT_NAME,
+    };
+    const probeOn = (event, _handler, opts) => {
+        const eventName = event.name;
+        // Timer subscriptions use a canonical synthesized name so the runtime
+        // can route fires by name alone.
+        const subscribedName = event.$kind === "workflow-timer"
+            ? timerEventName(name, eventName)
+            : eventName;
+        subscribed.add(subscribedName);
+        for (const a of opts?.dispatches ?? [])
+            dispatched.add(a.name);
+    };
+    const probeStates = stateful ? buildProbeStateCallables(stateSpecs) : {};
+    const probeCtx = stateful
+        ? {
+            on: probeOn,
+            send: async () => undefined,
+            enqueue: async () => undefined,
+            publish: async () => undefined,
+            data: {},
+            states: probeStates,
+            complete: completeMarker,
+            assign: async () => undefined,
+            timeout: (timerName, delay) => ({ $kind: "workflow-timer", name: timerName, delay }),
+            schedule: async () => undefined,
+        }
+        : {
+            on: probeOn,
+            send: async () => undefined,
+            enqueue: async () => undefined,
+            publish: async () => undefined,
+        };
+    closure(probeCtx);
+    if (stateful && options?.correlate) {
+        const map = (event, picker) => {
+            correlateTable.set(event.name, picker);
+        };
+        options.correlate(map);
+    }
+    const correlate = stateful
+        ? (event) => {
+            const picker = correlateTable.get(event.eventName);
+            return picker ? picker(event.payload) : undefined;
+        }
+        : undefined;
+    const built = {
+        $kind: "workflow",
+        name,
+        description: options?.description,
+        subscribedEvents: subscribed,
+        dispatchedActions: dispatched,
+        stateful,
+        finalStates,
+        initialState,
+        correlate,
+        async _fire(event, fireCtx) {
+            if (!stateful) {
+                await fireStateless({ closure, event, fireCtx, completeMarker });
+                return;
+            }
+            await fireStateful({
+                name,
+                closure,
+                event,
+                fireCtx,
+                stateSpecs,
+                finalStates,
+                initialState: initialState ?? "",
+                completeMarker,
+                correlate,
+                // Pass the data schema so fresh instances seed with Zod defaults.
+                dataSchema: stateful ? options.data : undefined,
+            });
+        },
+    };
+    return markable(built);
+}
+async function fireStateless({ closure, event, fireCtx, completeMarker, }) {
+    const matched = [];
+    const completeHandlers = [];
+    const ctx = {
+        on: ((subscribedEvent, handler) => {
+            const eventName = subscribedEvent.name;
+            if (eventName === completeMarker.name) {
+                completeHandlers.push(handler);
+                return;
+            }
+            if (eventName === event.eventName) {
+                matched.push(handler);
+            }
+        }),
+        send: fireCtx.send,
+        enqueue: fireCtx.enqueue,
+        publish: fireCtx.publish,
+    };
+    closure(ctx);
+    for (const h of matched) {
+        await h(event.payload);
+    }
+    // `complete` for a stateless workflow fires after each successful event.
+    if (matched.length > 0) {
+        for (const c of completeHandlers)
+            await c();
+    }
+}
+async function fireStateful(args) {
+    const { name, closure, event, fireCtx, stateSpecs, finalStates, initialState, completeMarker, correlate, dataSchema, } = args;
+    // Correlation: which instance owns this event?
+    //   • If the workflow declared `correlate(map)` and registered a picker
+    //     for this event, use the picker's output as the key.
+    //   • Otherwise (singleton workflow / no correlation), use `__default__`.
+    // Prefer an explicit override (timer fires hand the stored key down);
+    // otherwise derive from the user's correlate map; finally fall back to
+    // a singleton default for workflows that don't declare correlation.
+    const key = fireCtx.correlationKey ?? correlate?.(event) ?? "__default__";
+    let instance = fireCtx.load(key);
+    if (!instance) {
+        // Seed with Zod-declared defaults so handlers see typed initial values
+        // (e.g. `attempts: 0`) instead of `undefined`. If parsing the empty
+        // object fails (schema has required fields without defaults), fall
+        // back to `{}` so the handler can choose how to populate via assign().
+        let seed = {};
+        if (dataSchema) {
+            const parsed = dataSchema.safeParse({});
+            if (parsed.success)
+                seed = parsed.data;
+        }
+        instance = { state: initialState, data: seed, scopedEvents: [] };
+    }
+    const stateRegistrations = new Map();
+    const globalHandlers = [];
+    const completeHandlers = [];
+    let scope = { kind: "global" };
+    const states = buildFireStateCallables(stateSpecs, stateRegistrations);
+    const dataView = new Proxy({}, {
+        get: (_, prop) => instance.data[prop],
+    });
+    const onImpl = (subscribedEvent, handler, opts) => {
+        const rawName = subscribedEvent.name;
+        if (rawName === completeMarker.name) {
+            if (scope.kind === "global") {
+                completeHandlers.push(handler);
+            }
+            return;
+        }
+        // Timer subscriptions use the canonical synthesized event name so the
+        // runtime's fire path matches by name alone.
+        const isTimer = subscribedEvent.$kind === "workflow-timer";
+        const eventName = isTimer ? timerEventName(name, rawName) : rawName;
+        const entry = {
+            eventName,
+            handler: handler,
+            opts,
+            stateFilter: opts?.in ?? [],
+        };
+        if (scope.kind === "collect") {
+            scope.into.push(entry);
+        }
+        else {
+            globalHandlers.push(entry);
+        }
+    };
+    const ctx = {
+        on: onImpl,
+        async send(action, input) {
+            if (scope.kind === "collect")
+                return undefined;
+            return fireCtx.send(action, input);
+        },
+        async enqueue(action, input) {
+            if (scope.kind === "collect")
+                return;
+            await fireCtx.enqueue(action, input);
+        },
+        async publish(eventMsg) {
+            if (scope.kind === "collect")
+                return;
+            await fireCtx.publish(eventMsg);
+        },
+        data: dataView,
+        states,
+        complete: completeMarker,
+        async assign(patch) {
+            if (scope.kind === "collect")
+                return;
+            instance.data = { ...instance.data, ...patch };
+            // Write-through to the store so recursive workflow fires triggered by
+            // `send()` from the same handler see the updated state. Without this,
+            // a saga that retries via `send(action)` re-enters fireStateful, calls
+            // `fireCtx.load(key)`, gets back undefined (no save yet), re-runs with
+            // defaults — and recurses infinitely. Discovered debugging the
+            // payment-renewal saga's retry path.
+            fireCtx.save(key, instance);
+        },
+        timeout(timerName, delay) {
+            return { $kind: "workflow-timer", name: timerName, delay };
+        },
+        async schedule(timer, payload) {
+            if (scope.kind === "collect")
+                return;
+            await fireCtx.scheduleTimer(timer.name, timer.delay, payload);
+        },
+    };
+    closure(ctx);
+    // Find the winning handler for this event in the current state.
+    //   1. Re-run the current state's entry body in `collect` mode so any
+    //      nested `on(...)` inside `state(() => {...})` lands in a
+    //      state-local list. These shadow root-level handlers.
+    //   2. Else, among globalHandlers with `in:[…]` constraints that include
+    //      current state, pick the first match (state-scoped via opts.in).
+    //   3. Else, among globalHandlers with no constraint, pick the first match.
+    const stateScopedHandlers = [];
+    const stateReg = stateRegistrations.get(instance.state);
+    if (stateReg) {
+        const prev = scope;
+        scope = { kind: "collect", into: stateScopedHandlers };
+        try {
+            await stateReg.body();
+        }
+        finally {
+            scope = prev;
+        }
+    }
+    const matches = (h) => {
+        if (h.eventName !== event.eventName)
+            return false;
+        if (h.stateFilter.length === 0)
+            return true;
+        return h.stateFilter.includes(instance.state);
+    };
+    // XState semantics: state-scoped wins over root.
+    const chosen = stateScopedHandlers.find((h) => h.eventName === event.eventName) ??
+        globalHandlers.find((h) => matches(h) && h.stateFilter.length > 0) ??
+        globalHandlers.find((h) => matches(h) && h.stateFilter.length === 0);
+    if (!chosen) {
+        fireCtx.save(key, instance);
+        return;
+    }
+    const next = await chosen.handler(event.payload);
+    // Persist any assign() effects before the transition.
+    fireCtx.save(key, instance);
+    if (next && typeof next === "string" && stateSpecs[next]) {
+        instance.state = next;
+        // Run the new state's entry body so its effects fire and state-scoped
+        // subscriptions populate for the next event.
+        const newReg = stateRegistrations.get(next);
+        if (newReg) {
+            const innerTransition = await newReg.body();
+            // The entry body itself may return a state to transition into
+            // (early-exit pattern from the docs).
+            if (innerTransition && typeof innerTransition === "string" && stateSpecs[innerTransition]) {
+                instance.state = innerTransition;
+            }
+        }
+        fireCtx.save(key, instance);
+        if (finalStates.has(instance.state)) {
+            for (const c of completeHandlers)
+                await c();
+            fireCtx.drop(key);
+            void name; // reserved for richer instance keying (multi-workflow same correlation)
+        }
+    }
+}
+// ─── State callable factories ───────────────────────────────────────
+function buildProbeStateCallables(specs) {
+    const out = {};
+    for (const [name, spec] of Object.entries(specs)) {
+        const callable = ((_body) => {
+            // probe pass: ignore body — we only want to count states + flag final
+        });
+        Object.defineProperties(callable, {
+            $name: { value: name, enumerable: true },
+            $final: { value: !!spec.final, enumerable: true },
+        });
+        out[name] = callable;
+    }
+    return out;
+}
+function buildFireStateCallables(specs, registrations) {
+    const out = {};
+    for (const [name, spec] of Object.entries(specs)) {
+        const callable = ((body) => {
+            registrations.set(name, { body });
+        });
+        Object.defineProperties(callable, {
+            $name: { value: name, enumerable: true },
+            $final: { value: !!spec.final, enumerable: true },
+        });
+        out[name] = callable;
+    }
+    return out;
+}
+//# sourceMappingURL=define-workflow.js.map

package/dist/define-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-workflow.js","sourceRoot":"","sources":["../src/define-workflow.ts"],"names":[],"mappings":"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"}

package/dist/dev-logger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Dev console telemetry logger.
+ *
+ * Subscribes to `runtime.onTelemetry` and prints a single colored line
+ * per interesting record. Wired by `createApp` by default so a fresh
+ * `pnpm dev` shows something useful in the terminal instead of just the
+ * boot banner.
+ *
+ * Production wires that ship a structured `Logger` (pino, winston) should
+ * pass `devLogs: false` to `createApp` — the structured pipeline takes
+ * over and dev console noise gets out of the way.
+ *
+ * The selection of "interesting" records is conservative: domain dispatch
+ * + event publish + actor transitions + reaction failures + DLQ.
+ * Orchestrator + queue/cron records are suppressed by default to keep
+ * the firehose readable.
+ */
+import type { Runtime, Telemetry } from "./runtime.js";
+export interface DevLoggerOptions {
+    /**
+     * Filter — only records whose `kind` matches one of these is printed.
+     * Default: ["action.dispatched","action.completed","action.failed",
+     * "event.published","actor.transitioned","reaction.failed","dlq.recorded"].
+     */
+    readonly kinds?: readonly Telemetry["kind"][];
+    /**
+     * Custom sink. Default: stdout via `process.stdout.write`. Tests pass
+     * a buffer to assert without touching the real stream.
+     */
+    readonly write?: (line: string) => void;
+}
+/** Format a single telemetry record as a one-liner. */
+export declare function formatTelemetry(rec: Telemetry): string;
+/**
+ * Attach the dev logger to a runtime. Returns an unsubscribe.
+ *
+ * Idempotent at the caller's level — call once per runtime. createApp
+ * stores the unsubscribe and calls it in stop().
+ */
+export declare function attachDevLogger(runtime: Runtime, options?: DevLoggerOptions): () => void;
+//# sourceMappingURL=dev-logger.d.ts.map

package/dist/dev-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-logger.d.ts","sourceRoot":"","sources":["../src/dev-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAsDD,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CA+CtD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAOxF"}

package/dist/dev-logger.js

@@ -0,0 +1,135 @@
+/**
+ * Dev console telemetry logger.
+ *
+ * Subscribes to `runtime.onTelemetry` and prints a single colored line
+ * per interesting record. Wired by `createApp` by default so a fresh
+ * `pnpm dev` shows something useful in the terminal instead of just the
+ * boot banner.
+ *
+ * Production wires that ship a structured `Logger` (pino, winston) should
+ * pass `devLogs: false` to `createApp` — the structured pipeline takes
+ * over and dev console noise gets out of the way.
+ *
+ * The selection of "interesting" records is conservative: domain dispatch
+ * + event publish + actor transitions + reaction failures + DLQ.
+ * Orchestrator + queue/cron records are suppressed by default to keep
+ * the firehose readable.
+ */
+const DEFAULT_KINDS = [
+    "action.dispatched",
+    "action.completed",
+    "action.failed",
+    "event.published",
+    "actor.transitioned",
+    "reaction.failed",
+    "dlq.recorded",
+    "query.executed",
+    "lifecycle",
+];
+/**
+ * Render a `nwire:<ns>` tag colored by phase. A single glance distinguishes
+ * app boot from plugin lifecycle from wire mounts. The mapping is
+ * conservative — anything we don't know prints uncolored.
+ */
+function namespaceTag(ns) {
+    const text = `nwire:${ns}`;
+    switch (ns) {
+        case "app":
+            return color(text, BLU);
+        case "plugin":
+            return color(text, MAG);
+        case "wire":
+            return color(text, CYAN);
+        case "hook":
+            return color(text, YEL);
+        case "action":
+            return color(text, GREEN);
+        case "event":
+            return color(text, MAG);
+        default:
+            return color(text, DIM);
+    }
+}
+// Minimal color helpers — no picocolors dep so forge stays leaf-clean.
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const YEL = "\x1b[33m";
+const MAG = "\x1b[35m";
+const BLU = "\x1b[34m";
+function color(text, code) {
+    if (!process.stdout.isTTY)
+        return text;
+    return `${code}${text}${RESET}`;
+}
+/** Format a single telemetry record as a one-liner. */
+export function formatTelemetry(rec) {
+    const t = rec.ts.slice(11, 23); // HH:MM:SS.mmm
+    const dim = (s) => color(s, DIM);
+    switch (rec.kind) {
+        case "action.dispatched":
+            return `${dim(t)} ${color("→ action", CYAN)} ${rec.action}`;
+        case "action.completed":
+            return `${dim(t)} ${color("✓ action", GREEN)} ${rec.action} ${dim(`(${rec.durationMs}ms` + (rec.emittedEvents.length ? `, +${rec.emittedEvents.length} event${rec.emittedEvents.length === 1 ? "" : "s"}` : "") + ")")}`;
+        case "action.failed":
+            return `${dim(t)} ${color("✗ action", RED)} ${rec.action} ${dim(`(attempt ${rec.attempt}/${rec.maxAttempts}` + (rec.willRetry ? ", retrying" : "") + ")")} ${rec.error.message}`;
+        case "event.published":
+            return `${dim(t)} ${color("● event ", MAG)} ${rec.event.eventName} ${dim(rec.source === "external" ? "(bus)" : "")}`;
+        case "actor.transitioned":
+            return `${dim(t)} ${color("↻ actor ", YEL)} ${rec.actor}/${rec.key} ${dim(`${rec.from} → ${rec.to}`)} via ${rec.triggeringEvent}`;
+        case "reaction.failed":
+            return `${dim(t)} ${color("✗ react ", RED)} on ${rec.sourceEvent}: ${rec.error.message}`;
+        case "dlq.recorded":
+            return `${dim(t)} ${color("☠ dlq   ", RED)} ${rec.action} ${dim(`(${rec.attempts} attempts)`)} ${rec.error.message}`;
+        case "query.executed":
+            return `${dim(t)} ${color("? query ", CYAN)} ${rec.query} ${dim(`(${rec.durationMs.toFixed(1)}ms)`)}`;
+        case "lifecycle": {
+            // Namespaced lifecycle log: render `nwire:<ns>` colored by phase
+            // (app / plugin / wire / hook) so the eye groups events by axis.
+            // Pad the visible tag width to 14 chars so subsequent columns
+            // line up regardless of which namespace.
+            const visibleTag = `nwire:${rec.namespace}`;
+            const padded = visibleTag.padEnd(14, " ");
+            const tag = namespaceTag(rec.namespace) + padded.slice(visibleTag.length);
+            const marker = rec.phase === "prevented" ? color("✗", RED) : color("•", DIM);
+            // Strip the leading `nwire.` from the event name — every event has
+            // it; printing it once via the colored tag is enough.
+            const shortName = rec.event.replace(/^nwire\./, "");
+            // Pull the most useful 1-2 fields out of the payload for context.
+            const p = rec.payload;
+            const ctx = [];
+            if (p) {
+                if (typeof p["pluginName"] === "string")
+                    ctx.push(p["pluginName"]);
+                if (typeof p["transport"] === "string")
+                    ctx.push(p["transport"]);
+                if (typeof p["reason"] === "string")
+                    ctx.push(p["reason"]);
+                if (typeof p["durationMs"] === "number")
+                    ctx.push(`${p["durationMs"]}ms`);
+            }
+            const ctxLine = ctx.length > 0 ? ` ${dim(ctx.join(" · "))}` : "";
+            return `${dim(t)} ${marker} ${tag} ${shortName}${ctxLine}`;
+        }
+        default:
+            return `${dim(t)} ${rec.kind}`;
+    }
+}
+/**
+ * Attach the dev logger to a runtime. Returns an unsubscribe.
+ *
+ * Idempotent at the caller's level — call once per runtime. createApp
+ * stores the unsubscribe and calls it in stop().
+ */
+export function attachDevLogger(runtime, options) {
+    const kinds = new Set(options?.kinds ?? DEFAULT_KINDS);
+    const write = options?.write ?? ((line) => process.stdout.write(line + "\n"));
+    return runtime.onTelemetry((rec) => {
+        if (!kinds.has(rec.kind))
+            return;
+        write(formatTelemetry(rec));
+    });
+}
+//# sourceMappingURL=dev-logger.js.map

package/dist/dev-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-logger.js","sourceRoot":"","sources":["../src/dev-logger.ts"],"names":[],"mappings":"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"}

package/dist/event-message.d.ts

@@ -0,0 +1,37 @@
+/**
+ * EventMessage — what the framework dispatches and actors react to.
+ *
+ * Events flow through the runtime as `{ eventName, payload, envelope }`.
+ * Domain code authors them via the callable factory returned by
+ * `eventFactory(EventDef)` — given an EventDefinition (from @nwire/messages),
+ * produces a callable that validates payload and returns an EventMessage:
+ *
+ *   const flagged = AnswerFlaggedEvent({ submissionId, studentId, ... })
+ *   //  ^ EventMessage<typeof AnswerFlaggedEvent>
+ *
+ * Handlers return EventMessages (or arrays of them). The runtime atomically
+ * publishes them, looks up actors by their `key` field, and runs reactions.
+ */
+import type { EventDefinition, EventPayload } from "@nwire/messages";
+export interface EventMessage<E extends EventDefinition = EventDefinition> {
+    readonly eventName: string;
+    readonly payload: EventPayload<E>;
+}
+export type EventFactory<E extends EventDefinition> = ((payload: EventPayload<E>) => EventMessage<E>) & {
+    readonly definition: E;
+    readonly name: string;
+};
+/**
+ * Wrap an `EventDefinition` into a callable factory. The factory validates
+ * the payload against the event's schema (parse, not safeParse — invalid
+ * payloads throw, surfacing programmer errors immediately).
+ *
+ * The factory carries `.definition` (the original EventDefinition) and `.name`
+ * (the event's routing name) so handlers and the runtime can introspect.
+ */
+export declare function eventFactory<E extends EventDefinition>(definition: E): EventFactory<E>;
+/** Type-narrowing predicate. */
+export declare function isEventMessage(value: unknown): value is EventMessage;
+/** Normalize a handler's return value to an EventMessage[]. */
+export declare function normalizeEventReturn(value: void | EventMessage | EventMessage[] | null | undefined): EventMessage[];
+//# sourceMappingURL=event-message.d.ts.map

package/dist/event-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-message.d.ts","sourceRoot":"","sources":["../src/event-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;CACnC;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,eAAe,IAAI,CAAC,CACrD,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,KACrB,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG;IACtB,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,eAAe,EAAE,UAAU,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAYtF;AAED,gCAAgC;AAChC,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAOpE;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,IAAI,GAAG,YAAY,GAAG,YAAY,EAAE,GAAG,IAAI,GAAG,SAAS,GAC7D,YAAY,EAAE,CAIhB"}

package/dist/event-message.js

@@ -0,0 +1,51 @@
+/**
+ * EventMessage — what the framework dispatches and actors react to.
+ *
+ * Events flow through the runtime as `{ eventName, payload, envelope }`.
+ * Domain code authors them via the callable factory returned by
+ * `eventFactory(EventDef)` — given an EventDefinition (from @nwire/messages),
+ * produces a callable that validates payload and returns an EventMessage:
+ *
+ *   const flagged = AnswerFlaggedEvent({ submissionId, studentId, ... })
+ *   //  ^ EventMessage<typeof AnswerFlaggedEvent>
+ *
+ * Handlers return EventMessages (or arrays of them). The runtime atomically
+ * publishes them, looks up actors by their `key` field, and runs reactions.
+ */
+/**
+ * Wrap an `EventDefinition` into a callable factory. The factory validates
+ * the payload against the event's schema (parse, not safeParse — invalid
+ * payloads throw, surfacing programmer errors immediately).
+ *
+ * The factory carries `.definition` (the original EventDefinition) and `.name`
+ * (the event's routing name) so handlers and the runtime can introspect.
+ */
+export function eventFactory(definition) {
+    const factory = (payload) => ({
+        eventName: definition.name,
+        payload: definition.schema.parse(payload),
+    });
+    Object.defineProperty(factory, "definition", { value: definition, enumerable: true });
+    Object.defineProperty(factory, "name", { value: definition.name, enumerable: true });
+    Object.defineProperty(factory, "toString", {
+        value: () => definition.name,
+        enumerable: false,
+    });
+    return factory;
+}
+/** Type-narrowing predicate. */
+export function isEventMessage(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.eventName === "string" &&
+        "payload" in value);
+}
+/** Normalize a handler's return value to an EventMessage[]. */
+export function normalizeEventReturn(value) {
+    if (value == null)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    return [value];
+}
+//# sourceMappingURL=event-message.js.map

package/dist/event-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-message.js","sourceRoot":"","sources":["../src/event-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkBH;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAA4B,UAAa;IACnE,MAAM,OAAO,GAAG,CAAC,OAAwB,EAAmB,EAAE,CAAC,CAAC;QAC9D,SAAS,EAAE,UAAU,CAAC,IAAI;QAC1B,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAoB;KAC7D,CAAC,CAAC;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IACtF,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IACrF,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE;QACzC,KAAK,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI;QAC5B,UAAU,EAAE,KAAK;KAClB,CAAC,CAAC;IACH,OAAO,OAA0B,CAAC;AACpC,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAiC,CAAC,SAAS,KAAK,QAAQ;QAChE,SAAS,IAAI,KAAK,CACnB,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,oBAAoB,CAClC,KAA8D;IAE9D,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC"}