@nwire/forge 0.7.0

package/dist/__tests__/workflow-saga.test.js

@@ -0,0 +1,239 @@
+/**
+ * Stateful (saga) workflows — verify the closure-based state-machine
+ * runtime fires entry effects, transitions on handler return, persists
+ * data across events, and emits `complete` on final states.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import { defineWorkflow } from "../define-workflow.js";
+const PaymentRequested = defineEvent({
+    name: "billing.payment-requested",
+    schema: z.object({ subscriptionId: z.string(), amount: z.number() }),
+});
+const PaymentConfirmed = defineEvent({
+    name: "billing.payment-confirmed",
+    schema: z.object({ subscriptionId: z.string() }),
+});
+const PaymentFailed = defineEvent({
+    name: "billing.payment-failed",
+    schema: z.object({ subscriptionId: z.string() }),
+});
+/**
+ * Tiny in-test FireContext factory. Recorders capture every effect so
+ * tests can assert exact side-effect sequences.
+ */
+function makeFireCtx() {
+    const store = new Map();
+    const sent = [];
+    const published = [];
+    const scheduled = [];
+    return {
+        send: async (action, input) => {
+            sent.push({ action: action.name, input });
+            return undefined;
+        },
+        enqueue: async (action, input) => {
+            sent.push({ action: action.name, input });
+        },
+        publish: async (event) => {
+            published.push({ eventName: event.eventName });
+        },
+        load: (key) => store.get(key),
+        save: (key, instance) => store.set(key, { ...instance }),
+        drop: (key) => store.delete(key),
+        scheduleTimer: async (name, delay) => {
+            scheduled.push({ name, delay });
+        },
+        store,
+        sent,
+        published,
+        scheduled,
+    };
+}
+describe("defineWorkflow — stateful", () => {
+    it("transitions on handler return + persists data with assign()", async () => {
+        const ctx = makeFireCtx();
+        const renewal = defineWorkflow("subscription.renewal", ({ on, assign, states }) => {
+            const { notified, paid } = states;
+            on(PaymentRequested, async (e) => {
+                await assign({
+                    subscriptionId: e.subscriptionId,
+                    amount: e.amount,
+                    attempts: 0,
+                });
+                return notified.$name;
+            });
+            on(PaymentConfirmed, async () => {
+                return paid.$name;
+            });
+            // Reference states so they get registered in the spec.
+            void notified;
+            void paid;
+        }, {
+            data: z.object({
+                subscriptionId: z.string(),
+                amount: z.number(),
+                attempts: z.number().default(0),
+            }),
+            states: {
+                notified: {},
+                paid: { final: true },
+            },
+        });
+        expect(renewal.stateful).toBe(true);
+        expect(renewal.initialState).toBe("notified");
+        expect(renewal.finalStates.has("paid")).toBe(true);
+        await renewal._fire(PaymentRequested({ subscriptionId: "sub_1", amount: 99 }), ctx);
+        // The default-correlation key the runtime uses without explicit correlate.
+        const stored = [...ctx.store.values()][0];
+        expect(stored?.data).toMatchObject({ subscriptionId: "sub_1", amount: 99, attempts: 0 });
+        expect(stored?.state).toBe("notified");
+    });
+    it("transitioning to a final state fires complete and drops the instance", async () => {
+        const ctx = makeFireCtx();
+        const completed = [];
+        const flow = defineWorkflow("test.complete", ({ on, states, complete }) => {
+            const { open, closed } = states;
+            on(PaymentRequested, async () => closed.$name);
+            on(complete, async () => {
+                completed.push(1);
+            });
+            void open;
+        }, {
+            data: z.object({ x: z.number().default(0) }),
+            states: {
+                open: {},
+                closed: { final: true },
+            },
+        });
+        await flow._fire(PaymentRequested({ subscriptionId: "x", amount: 1 }), ctx);
+        expect(completed).toEqual([1]);
+        expect(ctx.store.size).toBe(0); // dropped after final
+    });
+    it("nested `state(() => on(...))` captures state-scoped subscriptions on entry", async () => {
+        const ctx = makeFireCtx();
+        const ran = [];
+        const flow = defineWorkflow("test.nested-state-body", ({ on, states }) => {
+            const { open, working, done } = states;
+            // Top-level: kicks off into `open`.
+            on(PaymentRequested, async () => open.$name);
+            // State body: registers a state-scoped handler for PaymentFailed
+            // that only fires while in `open`.
+            open(() => {
+                on(PaymentFailed, async () => {
+                    ran.push("open.failed");
+                    return working.$name;
+                });
+            });
+            working(() => {
+                on(PaymentFailed, async () => {
+                    ran.push("working.failed");
+                    return done.$name;
+                });
+            });
+            void done;
+        }, {
+            data: z.object({ k: z.string().default("") }),
+            states: { open: {}, working: {}, done: { final: true } },
+        });
+        // open: PaymentFailed → working (open's handler fires)
+        await flow._fire(PaymentRequested({ subscriptionId: "x", amount: 1 }), ctx);
+        await flow._fire(PaymentFailed({ subscriptionId: "x" }), ctx);
+        // working: PaymentFailed → done (working's handler fires)
+        await flow._fire(PaymentFailed({ subscriptionId: "x" }), ctx);
+        expect(ran).toEqual(["open.failed", "working.failed"]);
+        // done is final → instance dropped.
+        expect(ctx.store.size).toBe(0);
+    });
+    it("respects `opts.in` state-filter — handlers fire only in declared states", async () => {
+        const ctx = makeFireCtx();
+        const ran = [];
+        const flow = defineWorkflow("test.state-filter", ({ on, states }) => {
+            const { a, b } = states;
+            on(PaymentRequested, async () => b.$name); // any state → b
+            on(PaymentFailed, async () => {
+                ran.push("a-only");
+            }, { in: ["a"] });
+            on(PaymentFailed, async () => {
+                ran.push("b-only");
+            }, { in: ["b"] });
+            void a;
+            void b;
+        }, {
+            data: z.object({ k: z.string().default("") }),
+            states: { a: {}, b: {} },
+        });
+        // First event transitions from initial state "a" → "b".
+        await flow._fire(PaymentRequested({ subscriptionId: "x", amount: 1 }), ctx);
+        // Now in state "b": only b-only should fire.
+        await flow._fire(PaymentFailed({ subscriptionId: "x" }), ctx);
+        expect(ran).toEqual(["b-only"]);
+    });
+});
+describe("defineWorkflow — timers", () => {
+    it("schedule(timer) enqueues via FireContext.scheduleTimer with the right name+delay", async () => {
+        const ctx = makeFireCtx();
+        const flow = defineWorkflow("billing.renewal", ({ on, states, timeout, schedule }) => {
+            const { armed } = states;
+            const PaymentOverdue = timeout("payment-overdue", "7d");
+            on(PaymentRequested, async () => {
+                await schedule(PaymentOverdue);
+                return armed.$name;
+            });
+            // Suppress unused-state warning.
+            void PaymentOverdue;
+        }, {
+            data: z.object({ k: z.string().default("") }),
+            states: { armed: {} },
+        });
+        await flow._fire(PaymentRequested({ subscriptionId: "x", amount: 1 }), ctx);
+        expect(ctx.scheduled).toEqual([{ name: "payment-overdue", delay: "7d" }]);
+    });
+    it("timer fire routes via synthesized event name; on(timer, …) catches it", async () => {
+        const ctx = makeFireCtx();
+        const seen = [];
+        const flow = defineWorkflow("billing.renewal-2", ({ on, states, timeout }) => {
+            const { armed, expired } = states;
+            const Overdue = timeout("payment-overdue", "7d");
+            on(PaymentRequested, async () => armed.$name);
+            on(Overdue, async () => {
+                seen.push("overdue");
+                return expired.$name;
+            });
+            void armed;
+            void expired;
+        }, {
+            data: z.object({ k: z.string().default("") }),
+            states: { armed: {}, expired: { final: true } },
+        });
+        // Bootstrap the saga into `armed`.
+        await flow._fire(PaymentRequested({ subscriptionId: "x", amount: 1 }), ctx);
+        // Now simulate the timer fire: feed the synthesized event back in.
+        const timerEv = {
+            eventName: "__nwire/timer/billing.renewal-2/payment-overdue",
+            payload: undefined,
+        };
+        await flow._fire(timerEv, ctx);
+        expect(seen).toEqual(["overdue"]);
+        expect(ctx.store.size).toBe(0); // expired → final → dropped
+    });
+});
+describe("defineWorkflow — stateless still works", () => {
+    it("plain dispatch, no instance state", async () => {
+        const ctx = makeFireCtx();
+        const seen = [];
+        const flow = defineWorkflow("translate", ({ on, publish }) => {
+            on(PaymentRequested, async (e) => {
+                seen.push(e.subscriptionId);
+                await publish(PaymentConfirmed({ subscriptionId: e.subscriptionId }));
+            });
+        });
+        expect(flow.stateful).toBe(false);
+        await flow._fire(PaymentRequested({ subscriptionId: "s1", amount: 10 }), ctx);
+        expect(seen).toEqual(["s1"]);
+        expect(ctx.published.map((p) => p.eventName)).toEqual(["billing.payment-confirmed"]);
+        expect(ctx.store.size).toBe(0);
+    });
+});
+//# sourceMappingURL=workflow-saga.test.js.map

package/dist/__tests__/workflow-saga.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-saga.test.js","sourceRoot":"","sources":["../../src/__tests__/workflow-saga.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGpD,MAAM,gBAAgB,GAAG,WAAW,CAAC;IACnC,IAAI,EAAE,2BAA2B;IACjC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;CACrE,CAAC,CAAC;AACH,MAAM,gBAAgB,GAAG,WAAW,CAAC;IACnC,IAAI,EAAE,2BAA2B;IACjC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;CACjD,CAAC,CAAC;AACH,MAAM,aAAa,GAAG,WAAW,CAAC;IAChC,IAAI,EAAE,wBAAwB;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;CACjD,CAAC,CAAC;AAEH;;;GAGG;AACH,SAAS,WAAW;IAMlB,MAAM,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAC;IAClD,MAAM,IAAI,GAA8C,EAAE,CAAC;IAC3D,MAAM,SAAS,GAAiC,EAAE,CAAC;IACnD,MAAM,SAAS,GAA2C,EAAE,CAAC;IAC7D,OAAO;QACL,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE;YAC5B,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1C,OAAO,SAAkB,CAAC;QAC5B,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE;YAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;YACvB,SAAS,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;QAC7B,IAAI,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,QAAQ,EAAE,CAAC;QACxD,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;QAChC,aAAa,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YACnC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAClC,CAAC;QACD,KAAK;QACL,IAAI;QACJ,SAAS;QACT,SAAS;KACV,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACzC,EAAE,CAAC,6DAA6D,EAAE,KAAK,IAAI,EAAE;QAC3E,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAE1B,MAAM,OAAO,GAAG,cAAc,CAC5B,sBAAsB,EACtB,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE;YACzB,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;YAClC,EAAE,CAAC,gBAAgB,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;gBAC/B,MAAM,MAAM,CAAC;oBACX,cAAc,EAAE,CAAC,CAAC,cAAc;oBAChC,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,QAAQ,EAAE,CAAC;iBACZ,CAAC,CAAC;gBACH,OAAO,QAAQ,CAAC,KAAK,CAAC;YACxB,CAAC,CAAC,CAAC;YACH,EAAE,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE;gBAC9B,OAAO,IAAI,CAAC,KAAK,CAAC;YACpB,CAAC,CAAC,CAAC;YACH,uDAAuD;YACvD,KAAK,QAAQ,CAAC;YACd,KAAK,IAAI,CAAC;QACZ,CAAC,EACD;YACE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;gBACb,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;gBAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;gBAClB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;aAChC,CAAC;YACF,MAAM,EAAE;gBACN,QAAQ,EAAE,EAAE;gBACZ,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;aACtB;SACF,CACF,CAAC;QAEF,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC9C,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEnD,MAAM,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QACpF,2EAA2E;QAC3E,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,aAAa,CAAC,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QACzF,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sEAAsE,EAAE,KAAK,IAAI,EAAE;QACpF,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAa,EAAE,CAAC;QAE/B,MAAM,IAAI,GAAG,cAAc,CACzB,eAAe,EACf,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE;YAC3B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;YAChC,EAAE,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC/C,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;gBACtB,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,CAAC,CAAC,CAAC;YACH,KAAK,IAAI,CAAC;QACZ,CAAC,EACD;YACE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,MAAM,EAAE;gBACN,IAAI,EAAE,EAAE;gBACR,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;aACxB;SACF,CACF,CAAC;QAEF,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5E,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,sBAAsB;IACxD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4EAA4E,EAAE,KAAK,IAAI,EAAE;QAC1F,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAa,EAAE,CAAC;QAEzB,MAAM,IAAI,GAAG,cAAc,CACzB,wBAAwB,EACxB,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;YACjB,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;YAEvC,oCAAoC;YACpC,EAAE,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAE7C,iEAAiE;YACjE,mCAAmC;YACnC,IAAI,CAAC,GAAG,EAAE;gBACR,EAAE,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE;oBAC3B,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;oBACxB,OAAO,OAAO,CAAC,KAAK,CAAC;gBACvB,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YAEH,OAAO,CAAC,GAAG,EAAE;gBACX,EAAE,CAAC,aAAa,EAAE,KAAK,IAAI,EAAE;oBAC3B,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;oBAC3B,OAAO,IAAI,CAAC,KAAK,CAAC;gBACpB,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YACH,KAAK,IAAI,CAAC;QACZ,CAAC,EACD;YACE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7C,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;SACzD,CACF,CAAC;QAEF,uDAAuD;QACvD,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5E,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QAC9D,0DAA0D;QAC1D,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QAE9D,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAC,CAAC;QACvD,oCAAoC;QACpC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yEAAyE,EAAE,KAAK,IAAI,EAAE;QACvF,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAa,EAAE,CAAC;QAEzB,MAAM,IAAI,GAAG,cAAc,CACzB,mBAAmB,EACnB,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;YACjB,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,MAAM,CAAC;YACxB,EAAE,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB;YAC3D,EAAE,CACA,aAAa,EACb,KAAK,IAAI,EAAE;gBACT,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,CAAC,EACD,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CACd,CAAC;YACF,EAAE,CACA,aAAa,EACb,KAAK,IAAI,EAAE;gBACT,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,CAAC,EACD,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CACd,CAAC;YACF,KAAK,CAAC,CAAC;YACP,KAAK,CAAC,CAAC;QACT,CAAC,EACD;YACE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7C,MAAM,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;SACzB,CACF,CAAC;QAEF,wDAAwD;QACxD,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5E,6CAA6C;QAC7C,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,kFAAkF,EAAE,KAAK,IAAI,EAAE;QAChG,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAG,cAAc,CACzB,iBAAiB,EACjB,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE;YACpC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;YACzB,MAAM,cAAc,GAAG,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;YACxD,EAAE,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE;gBAC9B,MAAM,QAAQ,CAAC,cAAc,CAAC,CAAC;gBAC/B,OAAO,KAAK,CAAC,KAAK,CAAC;YACrB,CAAC,CAAC,CAAC;YACH,iCAAiC;YACjC,KAAK,cAAc,CAAC;QACtB,CAAC,EACD;YACE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7C,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;SACtB,CACF,CAAC;QAEF,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5E,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uEAAuE,EAAE,KAAK,IAAI,EAAE;QACrF,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAa,EAAE,CAAC;QAE1B,MAAM,IAAI,GAAG,cAAc,CACzB,mBAAmB,EACnB,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE;YAC1B,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;YAClC,MAAM,OAAO,GAAG,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;YACjD,EAAE,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC9C,EAAE,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;gBACrB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACrB,OAAO,OAAO,CAAC,KAAK,CAAC;YACvB,CAAC,CAAC,CAAC;YACH,KAAK,KAAK,CAAC;YACX,KAAK,OAAO,CAAC;QACf,CAAC,EACD;YACE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7C,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;SAChD,CACF,CAAC;QAEF,mCAAmC;QACnC,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QAE5E,mEAAmE;QACnE,MAAM,OAAO,GAAG;YACd,SAAS,EAAE,iDAAiD;YAC5D,OAAO,EAAE,SAAS;SACnB,CAAC;QACF,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAE/B,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,4BAA4B;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,wCAAwC,EAAE,GAAG,EAAE;IACtD,EAAE,CAAC,mCAAmC,EAAE,KAAK,IAAI,EAAE;QACjD,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,MAAM,IAAI,GAAa,EAAE,CAAC;QAE1B,MAAM,IAAI,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;YAC3D,EAAE,CAAC,gBAAgB,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;gBAC/B,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;gBAC5B,MAAM,OAAO,CAAC,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;YACxE,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QAC9E,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7B,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC;QACrF,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/actor-store.d.ts

@@ -0,0 +1,83 @@
+/**
+ * ActorStore — persistence contract for actor state.
+ *
+ * The runtime reads and writes actor instances through this contract.
+ * Implementations:
+ *   - InMemoryActorStore — process-local; default for tests and dev.
+ *   - (future) MongoActorStore, PostgresActorStore — persisted, cluster-safe.
+ *
+ * The store is intentionally thin: load/save/exists keyed by (actorName, key).
+ * No queries, no joins, no streaming — those live in projections.
+ */
+import type { ActorDefinition } from "./define-actor.js";
+export interface ActorInstance<TData = unknown> {
+    /** Logical actor type name (matches `ActorDefinition.name`). */
+    readonly actorName: string;
+    /** Stable identifier extracted from the actor's `key` field. */
+    readonly key: string;
+    /** Tenant scope. Empty string means the global / single-tenant scope. */
+    readonly tenant: string;
+    /** Current state name. */
+    readonly state: string;
+    /** Actor data. Validated against the actor's schema on save. */
+    readonly data: TData;
+    /**
+     * Active timers for the current state. Map of timer name → scheduled time
+     * (ms epoch) and the action that fires.
+     */
+    readonly activeTimers: Readonly<Record<string, ActorTimerHandle>>;
+}
+export interface ActorTimerHandle {
+    readonly scheduledAt: number;
+    readonly fireAt: number;
+    readonly action: string;
+    readonly input: unknown;
+}
+export interface ActorStore {
+    /**
+     * Load an actor instance scoped to `tenant` (default `''` for the global
+     * / single-tenant scope). Two tenants writing the same key see entirely
+     * separate state — there is no cross-tenant leakage by construction.
+     */
+    load(actorName: string, key: string, tenant?: string): Promise<ActorInstance | null>;
+    save(instance: ActorInstance): Promise<void>;
+    exists(actorName: string, key: string, tenant?: string): Promise<boolean>;
+    /**
+     * Enumerate stored instances. Used by the timer scheduler to walk every
+     * actor and find expired timers. With no `tenant`, returns instances
+     * across ALL tenants (the scheduler must dispatch each timer in its
+     * owning tenant's envelope). Implementations backed by databases should
+     * index `activeTimers.fireAt` for efficient querying.
+     */
+    listInstances(actorName: string, tenant?: string): Promise<readonly ActorInstance[]>;
+}
+/**
+ * Process-local in-memory store. Each save deep-clones the instance to prevent
+ * the runtime from observing post-save mutations of the same reference.
+ */
+export declare class InMemoryActorStore implements ActorStore {
+    private readonly entries;
+    /**
+     * Storage key includes tenant first so prefix scans by `(actor, tenant)`
+     * are O(matching tenant) — and across-tenant scans (no tenant) are O(N)
+     * by intent.
+     */
+    private cacheKey;
+    load(actorName: string, key: string, tenant?: string): Promise<ActorInstance | null>;
+    save(instance: ActorInstance): Promise<void>;
+    exists(actorName: string, key: string, tenant?: string): Promise<boolean>;
+    listInstances(actorName: string, tenant?: string): Promise<readonly ActorInstance[]>;
+    /** Test-only — returns the count of stored actor instances. */
+    size(): number;
+    /** Test-only — clears all stored instances. */
+    clear(): void;
+    private clone;
+}
+/**
+ * Build the initial instance for an actor whose key has never been seen in
+ * this tenant. Data is `{}` cast to the schema's output type — the first
+ * reaction's `assign` is responsible for populating it. Validation runs at
+ * save time.
+ */
+export declare function createInitialInstance(actor: ActorDefinition, key: string, tenant?: string): ActorInstance;
+//# sourceMappingURL=actor-store.d.ts.map

package/dist/actor-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-store.d.ts","sourceRoot":"","sources":["../src/actor-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,OAAO;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACrF,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E;;;;;;OAMG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;CACtF;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAE5D;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAIV,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAKxF,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAI7E,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAW1F,+DAA+D;IAC/D,IAAI,IAAI,MAAM;IAId,+CAA+C;IAC/C,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,KAAK;CAYd;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,MAAW,GAClB,aAAa,CAWf"}

package/dist/actor-store.js

@@ -0,0 +1,85 @@
+/**
+ * ActorStore — persistence contract for actor state.
+ *
+ * The runtime reads and writes actor instances through this contract.
+ * Implementations:
+ *   - InMemoryActorStore — process-local; default for tests and dev.
+ *   - (future) MongoActorStore, PostgresActorStore — persisted, cluster-safe.
+ *
+ * The store is intentionally thin: load/save/exists keyed by (actorName, key).
+ * No queries, no joins, no streaming — those live in projections.
+ */
+/**
+ * Process-local in-memory store. Each save deep-clones the instance to prevent
+ * the runtime from observing post-save mutations of the same reference.
+ */
+export class InMemoryActorStore {
+    entries = new Map();
+    /**
+     * Storage key includes tenant first so prefix scans by `(actor, tenant)`
+     * are O(matching tenant) — and across-tenant scans (no tenant) are O(N)
+     * by intent.
+     */
+    cacheKey(actorName, key, tenant) {
+        return `${tenant}::${actorName}::${key}`;
+    }
+    async load(actorName, key, tenant = "") {
+        const stored = this.entries.get(this.cacheKey(actorName, key, tenant));
+        return stored ? this.clone(stored) : null;
+    }
+    async save(instance) {
+        this.entries.set(this.cacheKey(instance.actorName, instance.key, instance.tenant), this.clone(instance));
+    }
+    async exists(actorName, key, tenant = "") {
+        return this.entries.has(this.cacheKey(actorName, key, tenant));
+    }
+    async listInstances(actorName, tenant) {
+        const result = [];
+        for (const [storeKey, value] of this.entries) {
+            if (value.actorName !== actorName)
+                continue;
+            if (tenant !== undefined && value.tenant !== tenant)
+                continue;
+            void storeKey;
+            result.push(this.clone(value));
+        }
+        return result;
+    }
+    /** Test-only — returns the count of stored actor instances. */
+    size() {
+        return this.entries.size;
+    }
+    /** Test-only — clears all stored instances. */
+    clear() {
+        this.entries.clear();
+    }
+    clone(instance) {
+        return {
+            actorName: instance.actorName,
+            key: instance.key,
+            tenant: instance.tenant,
+            state: instance.state,
+            data: structuredClone(instance.data),
+            activeTimers: structuredClone(instance.activeTimers),
+        };
+    }
+}
+/**
+ * Build the initial instance for an actor whose key has never been seen in
+ * this tenant. Data is `{}` cast to the schema's output type — the first
+ * reaction's `assign` is responsible for populating it. Validation runs at
+ * save time.
+ */
+export function createInitialInstance(actor, key, tenant = "") {
+    return {
+        actorName: actor.name,
+        key,
+        tenant,
+        state: actor.initial,
+        // Initial data is empty; the first reaction's `assign` fills it.
+        // Schema validation happens at save time, not here.
+        data: {},
+        activeTimers: {},
+    };
+}
+//# sourceMappingURL=actor-store.js.map

package/dist/actor-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor-store.js","sourceRoot":"","sources":["../src/actor-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgDH;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACZ,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE5D;;;;OAIG;IACK,QAAQ,CAAC,SAAiB,EAAE,GAAW,EAAE,MAAc;QAC7D,OAAO,GAAG,MAAM,KAAK,SAAS,KAAK,GAAG,EAAE,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,SAAiB,EAAE,GAAW,EAAE,SAAiB,EAAE;QAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;QACvE,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAAuB;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,CACd,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,EAChE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CACrB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,SAAiB,EAAE,GAAW,EAAE,SAAiB,EAAE;QAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,SAAiB,EAAE,MAAe;QACpD,MAAM,MAAM,GAAoB,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC7C,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;gBAAE,SAAS;YAC5C,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;gBAAE,SAAS;YAC9D,KAAK,QAAQ,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+DAA+D;IAC/D,IAAI;QACF,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,+CAA+C;IAC/C,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAEO,KAAK,CAAC,QAAuB;QACnC,OAAO;YACL,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,GAAG,EAAE,QAAQ,CAAC,GAAG;YACjB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,IAAI,EAAE,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC;YACpC,YAAY,EAAE,eAAe,CAAC,QAAQ,CAAC,YAAY,CAElD;SACF,CAAC;IACJ,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAsB,EACtB,GAAW,EACX,SAAiB,EAAE;IAEnB,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,IAAI;QACrB,GAAG;QACH,MAAM;QACN,KAAK,EAAE,KAAK,CAAC,OAAO;QACpB,iEAAiE;QACjE,oDAAoD;QACpD,IAAI,EAAE,EAAa;QACnB,YAAY,EAAE,EAAE;KACjB,CAAC;AACJ,CAAC"}

package/dist/cli-runner.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `runCli` — command-line runner. Operators dispatch any registered action
+ * (or query) by name, with input parsed from CLI flags.
+ *
+ *   amit submissions.flag-for-review --submissionId xyz --confidence 0.4
+ *   amit lessons.start-attempt --lessonId hebrew-letters-1 \
+ *        --studentId student-avi-9 \
+ *        --exerciseIds exercise-A1 --exerciseIds exercise-A2
+ *   amit submissions.by-student --studentId student-avi-9 --status under-review
+ *
+ * Wires create a small entry script that hands a fresh `App` to `runCli`:
+ *
+ *   #!/usr/bin/env node
+ *   import { runCli } from '@nwire/forge'
+ *   import { boot } from './app/boot.js'
+ *
+ *   const app = await boot()           // returns { learnflow: App }
+ *   const exitCode = await runCli(app.learnflow, process.argv.slice(2))
+ *   process.exit(exitCode)
+ *
+ * Convention:
+ *   - First arg is the action or query name (`submissions.flag-for-review`).
+ *   - `--field value` sets a string field on the input.
+ *   - `--field=value` is also accepted.
+ *   - Repeating `--field a --field b` produces `field: ['a', 'b']`.
+ *   - `--field` (no value) sets `field: true`.
+ *   - `--tenant <id>` is special — sets `envelope.tenant` for the dispatch.
+ *   - Numeric values are auto-coerced when the schema accepts a number.
+ *
+ * Dispatching against an action returns void; the runner prints `OK`. Against
+ * a query: prints the JSON result. Errors print to stderr and exit non-zero.
+ *
+ * Wire-mode invariance: same domain handlers run in HTTP, queue, and CLI.
+ * The CLI doesn't know about HTTP routes; it dispatches via the runtime.
+ */
+import type { App } from "./create-app.js";
+export interface RunCliOptions {
+    /**
+     * Override stdout/stderr — useful for tests. Defaults to console.log /
+     * console.error.
+     */
+    readonly stdout?: (line: string) => void;
+    readonly stderr?: (line: string) => void;
+}
+export declare function runCli(app: App, argv: readonly string[], options?: RunCliOptions): Promise<number>;
+//# sourceMappingURL=cli-runner.d.ts.map

package/dist/cli-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-runner.d.ts","sourceRoot":"","sources":["../src/cli-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED,wBAAsB,MAAM,CAC1B,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA2CjB"}

package/dist/cli-runner.js

@@ -0,0 +1,164 @@
+/**
+ * `runCli` — command-line runner. Operators dispatch any registered action
+ * (or query) by name, with input parsed from CLI flags.
+ *
+ *   amit submissions.flag-for-review --submissionId xyz --confidence 0.4
+ *   amit lessons.start-attempt --lessonId hebrew-letters-1 \
+ *        --studentId student-avi-9 \
+ *        --exerciseIds exercise-A1 --exerciseIds exercise-A2
+ *   amit submissions.by-student --studentId student-avi-9 --status under-review
+ *
+ * Wires create a small entry script that hands a fresh `App` to `runCli`:
+ *
+ *   #!/usr/bin/env node
+ *   import { runCli } from '@nwire/forge'
+ *   import { boot } from './app/boot.js'
+ *
+ *   const app = await boot()           // returns { learnflow: App }
+ *   const exitCode = await runCli(app.learnflow, process.argv.slice(2))
+ *   process.exit(exitCode)
+ *
+ * Convention:
+ *   - First arg is the action or query name (`submissions.flag-for-review`).
+ *   - `--field value` sets a string field on the input.
+ *   - `--field=value` is also accepted.
+ *   - Repeating `--field a --field b` produces `field: ['a', 'b']`.
+ *   - `--field` (no value) sets `field: true`.
+ *   - `--tenant <id>` is special — sets `envelope.tenant` for the dispatch.
+ *   - Numeric values are auto-coerced when the schema accepts a number.
+ *
+ * Dispatching against an action returns void; the runner prints `OK`. Against
+ * a query: prints the JSON result. Errors print to stderr and exit non-zero.
+ *
+ * Wire-mode invariance: same domain handlers run in HTTP, queue, and CLI.
+ * The CLI doesn't know about HTTP routes; it dispatches via the runtime.
+ */
+import { seedEnvelope } from "@nwire/envelope";
+export async function runCli(app, argv, options = {}) {
+    const stdout = options.stdout ?? ((line) => console.log(line));
+    const stderr = options.stderr ?? ((line) => console.error(line));
+    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+        printHelp(app, stdout);
+        return 0;
+    }
+    const targetName = argv[0];
+    const rest = argv.slice(1);
+    // Try action first — actions write through the runtime's dispatch.
+    const action = findAction(app, targetName);
+    if (action) {
+        const { tenant, parsed } = parseFlags(rest);
+        try {
+            const validated = action.schema.parse(parsed);
+            const envelope = tenant ? seedEnvelope({ tenant }) : undefined;
+            await app.runtime.dispatch(action, validated, envelope);
+            stdout("OK");
+            return 0;
+        }
+        catch (err) {
+            stderr(`error dispatching "${targetName}": ${err.message}`);
+            return 1;
+        }
+    }
+    // Fall back to query.
+    if (app.runtime.listQueries().includes(targetName)) {
+        const { tenant, parsed } = parseFlags(rest);
+        try {
+            const result = await app.runtime.query(targetName, parsed, tenant);
+            stdout(JSON.stringify(result, null, 2));
+            return 0;
+        }
+        catch (err) {
+            stderr(`error querying "${targetName}": ${err.message}`);
+            return 1;
+        }
+    }
+    stderr(`unknown action or query: "${targetName}". Run with --help for the list.`);
+    return 1;
+}
+function findAction(app, name) {
+    return toActionMap(app)[name];
+}
+function toActionMap(app) {
+    const map = {};
+    for (const module of app.modules) {
+        for (const action of module.manifest.actions ?? []) {
+            map[action.name] = action;
+        }
+    }
+    return map;
+}
+function printHelp(app, stdout) {
+    stdout("nwire — action CLI runner\n");
+    stdout("Usage: amit <action-or-query-name> [--field value ...] [--tenant <id>]\n");
+    stdout("Actions:");
+    for (const module of app.modules) {
+        for (const action of module.manifest.actions ?? []) {
+            stdout(`  ${action.name}${action.description ? "   — " + action.description.slice(0, 60) : ""}`);
+        }
+    }
+    stdout("Queries:");
+    for (const module of app.modules) {
+        for (const query of module.manifest.queries ?? []) {
+            stdout(`  ${query.name}${query.description ? "   — " + query.description.slice(0, 60) : ""}`);
+        }
+    }
+}
+function parseFlags(argv) {
+    const out = {};
+    let tenant;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith("--"))
+            continue;
+        // Support both --field=value and --field value.
+        const eq = arg.indexOf("=");
+        let key;
+        let value;
+        if (eq >= 0) {
+            key = arg.slice(2, eq);
+            value = arg.slice(eq + 1);
+        }
+        else {
+            key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                value = next;
+                i++;
+            }
+            else {
+                value = true;
+            }
+        }
+        if (key === "tenant") {
+            if (typeof value === "string")
+                tenant = value;
+            continue;
+        }
+        const coerced = typeof value === "string" ? coerce(value) : value;
+        if (key in out) {
+            const existing = out[key];
+            if (Array.isArray(existing)) {
+                existing.push(coerced);
+            }
+            else {
+                out[key] = [existing, coerced];
+            }
+        }
+        else {
+            out[key] = coerced;
+        }
+    }
+    return { tenant, parsed: out };
+}
+function coerce(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (/^-?\d+$/.test(value))
+        return Number(value);
+    if (/^-?\d+\.\d+$/.test(value))
+        return Number(value);
+    return value;
+}
+//# sourceMappingURL=cli-runner.js.map

package/dist/cli-runner.js.map

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