@nwire/forge 0.7.0

package/dist/__tests__/cli-runner.test.js

@@ -0,0 +1,158 @@
+/**
+ * CLI runner — contract test. Verifies argv parsing → action/query dispatch
+ * → stdout/stderr capture, with no actual process spawning.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import * as forge from "../foundation.js";
+const { defineAction, defineActor, defineHandler, defineProjection, defineQuery, defineModule, eventFactory, createApp, runCli, } = forge;
+const TodoCreatedEventDef = defineEvent({
+    name: "todos.created",
+    schema: z.object({ todoId: z.string(), title: z.string() }),
+});
+const TodoCreated = eventFactory(TodoCreatedEventDef);
+const Todo = defineActor("todo", {
+    schema: z.object({ todoId: z.string(), title: z.string().optional() }),
+    key: "todoId",
+    initial: "open",
+    states: {
+        open: {
+            on: {
+                [TodoCreated.name]: {
+                    assign: (_, event) => {
+                        const e = event;
+                        return { todoId: e.todoId, title: e.title };
+                    },
+                },
+            },
+        },
+    },
+});
+const TodosByOwner = defineProjection("todos-by-owner", {
+    listens: [TodoCreatedEventDef],
+    initial: () => ({}),
+    on: {
+        [TodoCreatedEventDef.name]: (state, event) => {
+            const e = event;
+            return { ...state, [e.todoId]: { todoId: e.todoId, title: e.title } };
+        },
+    },
+});
+const todosByOwner = defineQuery(TodosByOwner, {
+    name: "todos.by-owner",
+    schema: z.object({ tenant: z.string().optional() }),
+    execute: (state) => Object.values(state),
+});
+const createTodo = defineAction({
+    name: "todos.create",
+    description: "Create a todo with the given id and title.",
+    schema: z.object({
+        todoId: z.string(),
+        title: z.string(),
+    }),
+});
+const createTodoHandler = defineHandler(createTodo, async (input) => TodoCreated({ todoId: input.todoId, title: input.title }));
+const todosModule = defineModule("todos", {
+    actions: [createTodo],
+    actors: [Todo],
+    handlers: [createTodoHandler],
+    projections: [TodosByOwner],
+    queries: [todosByOwner],
+    events: [TodoCreatedEventDef],
+});
+function makeApp() {
+    return createApp({ modules: [todosModule] });
+}
+describe("CLI runner — runCli", () => {
+    it("dispatches an action with --field value flags", async () => {
+        const app = makeApp();
+        const out = [];
+        const err = [];
+        const code = await runCli(app, ["todos.create", "--todoId", "t-1", "--title", "Buy milk"], {
+            stdout: (l) => out.push(l),
+            stderr: (l) => err.push(l),
+        });
+        expect(code).toBe(0);
+        expect(out).toEqual(["OK"]);
+        expect(err).toEqual([]);
+        const stored = await app.runtime.getActorStore().load("todo", "t-1");
+        expect((stored?.data).title).toBe("Buy milk");
+    });
+    it("supports --field=value form", async () => {
+        const app = makeApp();
+        const out = [];
+        const code = await runCli(app, ["todos.create", "--todoId=t-2", "--title=Walk dog"], {
+            stdout: (l) => out.push(l),
+            stderr: () => { },
+        });
+        expect(code).toBe(0);
+        const stored = await app.runtime.getActorStore().load("todo", "t-2");
+        expect((stored?.data).title).toBe("Walk dog");
+    });
+    it("--tenant routes the dispatch into a tenant scope", async () => {
+        const app = makeApp();
+        await runCli(app, ["todos.create", "--todoId=t-3", "--title=A", "--tenant=school-tlv"], {
+            stdout: () => { },
+            stderr: () => { },
+        });
+        await runCli(app, ["todos.create", "--todoId=t-3", "--title=B", "--tenant=school-jlm"], {
+            stdout: () => { },
+            stderr: () => { },
+        });
+        const tlv = await app.runtime.getActorStore().load("todo", "t-3", "school-tlv");
+        const jlm = await app.runtime.getActorStore().load("todo", "t-3", "school-jlm");
+        expect((tlv?.data).title).toBe("A");
+        expect((jlm?.data).title).toBe("B");
+    });
+    it("dispatches a query and prints JSON to stdout", async () => {
+        const app = makeApp();
+        await runCli(app, ["todos.create", "--todoId=t-4", "--title=hello"], {
+            stdout: () => { },
+            stderr: () => { },
+        });
+        const out = [];
+        const code = await runCli(app, ["todos.by-owner"], {
+            stdout: (l) => out.push(l),
+            stderr: () => { },
+        });
+        expect(code).toBe(0);
+        const printed = out.join("\n");
+        const parsed = JSON.parse(printed);
+        expect(parsed.find((t) => t.todoId === "t-4")).toBeDefined();
+    });
+    it("prints help with --help and lists actions + queries", async () => {
+        const app = makeApp();
+        const out = [];
+        const code = await runCli(app, ["--help"], {
+            stdout: (l) => out.push(l),
+            stderr: () => { },
+        });
+        expect(code).toBe(0);
+        const text = out.join("\n");
+        expect(text).toMatch(/todos\.create/);
+        expect(text).toMatch(/todos\.by-owner/);
+    });
+    it("returns non-zero and writes to stderr for unknown action", async () => {
+        const app = makeApp();
+        const out = [];
+        const err = [];
+        const code = await runCli(app, ["nonexistent.thing"], {
+            stdout: (l) => out.push(l),
+            stderr: (l) => err.push(l),
+        });
+        expect(code).toBe(1);
+        expect(out).toEqual([]);
+        expect(err.join("\n")).toMatch(/unknown action or query/);
+    });
+    it("returns non-zero and writes to stderr when input fails validation", async () => {
+        const app = makeApp();
+        const err = [];
+        const code = await runCli(app, 
+        // Missing required title.
+        ["todos.create", "--todoId=t-bad"], { stdout: () => { }, stderr: (l) => err.push(l) });
+        expect(code).toBe(1);
+        expect(err.join("\n")).toMatch(/error dispatching/);
+    });
+});
+//# sourceMappingURL=cli-runner.test.js.map

package/dist/__tests__/cli-runner.test.js.map

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

package/dist/__tests__/create-app.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * createApp — end-to-end contract test through the runtime.
+ *
+ * Proves the core composes:
+ *   defineAction → defineHandler → defineActor (with state machine + after timer)
+ *   → defineProjection → defineQuery → defineModule → createApp
+ *
+ * Drives a tiny "todos" domain straight through the runtime (no transport).
+ * Asserts:
+ *   - dispatching the create action produces an actor in `open` with the
+ *     populated data and a scheduled `auto-archive` timer
+ *   - dispatching the complete action transitions state via target + assign
+ *     and cancels the open-state timer
+ *   - the projection emits the expected read-side state (CQRS round-trip)
+ *   - `completed` is final — further events for the same actor are skipped
+ */
+export {};
+//# sourceMappingURL=create-app.test.d.ts.map

package/dist/__tests__/create-app.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-app.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/create-app.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/__tests__/create-app.test.js

@@ -0,0 +1,189 @@
+/**
+ * createApp — end-to-end contract test through the runtime.
+ *
+ * Proves the core composes:
+ *   defineAction → defineHandler → defineActor (with state machine + after timer)
+ *   → defineProjection → defineQuery → defineModule → createApp
+ *
+ * Drives a tiny "todos" domain straight through the runtime (no transport).
+ * Asserts:
+ *   - dispatching the create action produces an actor in `open` with the
+ *     populated data and a scheduled `auto-archive` timer
+ *   - dispatching the complete action transitions state via target + assign
+ *     and cancels the open-state timer
+ *   - the projection emits the expected read-side state (CQRS round-trip)
+ *   - `completed` is final — further events for the same actor are skipped
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import * as forge from "../foundation.js";
+const { defineAction, defineActor, defineHandler, defineProjection, defineQuery, defineModule, eventFactory, createApp, } = forge;
+// ─── Domain: tiny todos ────────────────────────────────────────────
+const TodoCreatedEventDef = defineEvent({
+    name: "todos.created",
+    schema: z.object({
+        todoId: z.string(),
+        title: z.string(),
+        createdAt: z.string().datetime(),
+    }),
+});
+const TodoCreated = eventFactory(TodoCreatedEventDef);
+const TodoCompletedEventDef = defineEvent({
+    name: "todos.completed",
+    schema: z.object({
+        todoId: z.string(),
+        completedAt: z.string().datetime(),
+    }),
+});
+const TodoCompleted = eventFactory(TodoCompletedEventDef);
+const TodoActorData = z.object({
+    todoId: z.string(),
+    title: z.string().optional(),
+    status: z.enum(["open", "completed"]).optional(),
+    createdAt: z.string().optional(),
+    completedAt: z.string().optional(),
+});
+const Todo = defineActor("todo", {
+    schema: TodoActorData,
+    key: "todoId",
+    initial: "open",
+    states: {
+        open: {
+            on: {
+                [TodoCreated.name]: {
+                    assign: (_ctx, event) => {
+                        const e = event;
+                        return {
+                            todoId: e.todoId,
+                            title: e.title,
+                            status: "open",
+                            createdAt: e.createdAt,
+                        };
+                    },
+                },
+                [TodoCompleted.name]: {
+                    target: "completed",
+                    assign: (_ctx, event) => {
+                        const e = event;
+                        return { status: "completed", completedAt: e.completedAt };
+                    },
+                },
+            },
+            after: {
+                "auto-archive": { delay: "7d", action: "todos.auto-archive" },
+            },
+        },
+        completed: { final: true },
+    },
+});
+// ─── Action + handler ──────────────────────────────────────────────
+const CreateTodoInput = z.object({
+    todoId: z.string(),
+    title: z.string().min(1),
+});
+const createTodo = defineAction({
+    name: "todos.create",
+    schema: CreateTodoInput,
+    description: "Create a new todo for the named id and title.",
+});
+const createTodoHandler = defineHandler(createTodo, async (input) => {
+    return TodoCreated({
+        todoId: input.todoId,
+        title: input.title,
+        createdAt: "2026-05-10T12:00:00Z",
+    });
+});
+const CompleteTodoInput = z.object({ todoId: z.string() });
+const completeTodo = defineAction({
+    name: "todos.complete",
+    schema: CompleteTodoInput,
+});
+const completeTodoHandler = defineHandler(completeTodo, async (input) => {
+    return TodoCompleted({
+        todoId: input.todoId,
+        completedAt: "2026-05-10T13:00:00Z",
+    });
+});
+const TodosByStatus = defineProjection("todos-by-status", {
+    listens: [TodoCreatedEventDef, TodoCompletedEventDef],
+    initial: () => ({}),
+    on: {
+        [TodoCreatedEventDef.name]: (state, event) => {
+            const e = event;
+            return { ...state, [e.todoId]: { todoId: e.todoId, title: e.title, status: "open" } };
+        },
+        [TodoCompletedEventDef.name]: (state, event) => {
+            const e = event;
+            const current = state[e.todoId];
+            if (!current)
+                return state;
+            return { ...state, [e.todoId]: { ...current, status: "completed" } };
+        },
+    },
+});
+const todosByStatus = defineQuery(TodosByStatus, {
+    name: "todos.by-status",
+    schema: z.object({ status: z.enum(["open", "completed"]).optional() }),
+    execute: (state, { status }) => Object.values(state).filter((t) => !status || t.status === status),
+});
+// ─── Module ────────────────────────────────────────────────────────
+const todosModule = defineModule("todos", {
+    actions: [createTodo, completeTodo],
+    actors: [Todo],
+    handlers: [createTodoHandler, completeTodoHandler],
+    projections: [TodosByStatus],
+    queries: [todosByStatus],
+    events: [TodoCreatedEventDef, TodoCompletedEventDef],
+});
+// ─── Tests ─────────────────────────────────────────────────────────
+describe("createApp — end-to-end through the runtime", () => {
+    function build() {
+        return createApp({ modules: [todosModule] });
+    }
+    it("dispatching create produces an actor in `open` with the `auto-archive` timer", async () => {
+        const app = build();
+        await app.runtime.dispatch(createTodo, { todoId: "t-1", title: "Buy milk" });
+        const stored = await app.runtime.getActorStore().load("todo", "t-1");
+        expect(stored?.state).toBe("open");
+        const data = stored?.data;
+        expect(data.title).toBe("Buy milk");
+        expect(data.status).toBe("open");
+        expect(stored?.activeTimers["auto-archive"]).toBeDefined();
+        expect(stored?.activeTimers["auto-archive"]?.action).toBe("todos.auto-archive");
+    });
+    it("dispatching complete transitions state via target + cancels the open-state timer", async () => {
+        const app = build();
+        await app.runtime.dispatch(createTodo, { todoId: "t-2", title: "Walk dog" });
+        await app.runtime.dispatch(completeTodo, { todoId: "t-2" });
+        const stored = await app.runtime.getActorStore().load("todo", "t-2");
+        expect(stored?.state).toBe("completed");
+        expect(Object.keys(stored?.activeTimers ?? {})).toHaveLength(0);
+    });
+    it("query reads from the projection (CQRS round-trip)", async () => {
+        const app = build();
+        await app.runtime.dispatch(createTodo, { todoId: "t-a", title: "A" });
+        await app.runtime.dispatch(createTodo, { todoId: "t-b", title: "B" });
+        await app.runtime.dispatch(completeTodo, { todoId: "t-a" });
+        const all = await app.runtime.query("todos.by-status", {});
+        expect(all).toHaveLength(2);
+        const open = await app.runtime.query("todos.by-status", { status: "open" });
+        expect(open).toHaveLength(1);
+        expect(open[0]?.todoId).toBe("t-b");
+        const completedQ = await app.runtime.query("todos.by-status", { status: "completed" });
+        expect(completedQ).toHaveLength(1);
+        expect(completedQ[0]?.todoId).toBe("t-a");
+    });
+    it("completed is final — further completion events are silently skipped", async () => {
+        const app = build();
+        await app.runtime.dispatch(createTodo, { todoId: "t-final", title: "Once" });
+        await app.runtime.dispatch(completeTodo, { todoId: "t-final" });
+        const before = await app.runtime.getActorStore().load("todo", "t-final");
+        // Try to complete again — current state has no reaction; runtime silently skips.
+        await app.runtime.dispatch(completeTodo, { todoId: "t-final" });
+        const after = await app.runtime.getActorStore().load("todo", "t-final");
+        expect(after?.state).toBe("completed");
+        expect(after?.data).toEqual(before?.data);
+    });
+});
+//# sourceMappingURL=create-app.test.js.map

package/dist/__tests__/create-app.test.js.map

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

package/dist/__tests__/cross-service-bus.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Cross-service event bus integration — two apps wired through one
+ * InMemoryEventBus. App A produces a public event; App B has a module that
+ * declares `needs.externalEvents` for it; the runtime auto-subscribes and
+ * dispatches a reaction without A and B sharing process state.
+ */
+export {};
+//# sourceMappingURL=cross-service-bus.test.d.ts.map

package/dist/__tests__/cross-service-bus.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-service-bus.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cross-service-bus.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/__tests__/cross-service-bus.test.js

@@ -0,0 +1,139 @@
+/**
+ * Cross-service event bus integration — two apps wired through one
+ * InMemoryEventBus. App A produces a public event; App B has a module that
+ * declares `needs.externalEvents` for it; the runtime auto-subscribes and
+ * dispatches a reaction without A and B sharing process state.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import { InMemoryEventBus } from "@nwire/bus";
+import { defineAction, defineHandler, defineModule, createApp, eventFactory, defineWorkflow, } from "../foundation.js";
+const StudentEnrolledEvent = defineEvent({
+    name: "roster.student-enrolled",
+    schema: z.object({ studentId: z.string(), courseId: z.string() }),
+});
+const StudentEnrolled = eventFactory(StudentEnrolledEvent);
+const InternalEvent = defineEvent({
+    name: "roster.internal-only",
+    schema: z.object({ id: z.string() }),
+    visibility: "internal",
+});
+describe("cross-service event bus", () => {
+    it("an event published in app A reaches a reaction in app B via the bus", async () => {
+        const bus = new InMemoryEventBus();
+        // App A (lms-service) — produces the event.
+        const enrollStudent = defineAction({
+            name: "roster.enroll",
+            schema: z.object({ studentId: z.string(), courseId: z.string() }),
+            handler: async (input) => StudentEnrolled({ studentId: input.studentId, courseId: input.courseId }),
+        });
+        const lmsModule = defineModule("roster", {
+            actions: [enrollStudent],
+            events: [StudentEnrolledEvent],
+        });
+        const lmsApp = createApp({
+            modules: [lmsModule],
+            bus,
+            publishToBus: true,
+            appName: "lms-service",
+        });
+        // App B (lxp-service) — subscribes to enrollment events.
+        const noticeEnrollment = defineAction({
+            name: "lxp.notice-enrollment",
+            schema: z.object({ studentId: z.string(), courseId: z.string() }),
+        });
+        let observed = null;
+        const noticeHandler = defineHandler(noticeEnrollment, async (input) => {
+            observed = input;
+            return undefined;
+        });
+        const enrollmentWorkflow = defineWorkflow("lxp.on-student-enrolled", ({ on, send }) => {
+            on(StudentEnrolledEvent, async (payload) => {
+                await send(noticeEnrollment, payload);
+            });
+        });
+        const lxpModule = defineModule("lxp-runtime", {
+            actions: [noticeEnrollment],
+            handlers: [noticeHandler],
+            workflows: [enrollmentWorkflow],
+            needs: { externalEvents: [StudentEnrolledEvent] },
+        });
+        const lxpApp = createApp({
+            modules: [lxpModule],
+            bus,
+            appName: "lxp-service",
+        });
+        // App A dispatches; App B reacts via the bus.
+        await lmsApp.runtime.dispatch(enrollStudent, {
+            studentId: "avi",
+            courseId: "hebrew-letters",
+        });
+        // InMemoryEventBus is synchronous within publish() — the cross-app
+        // reaction has already run by the time dispatch returns.
+        expect(observed).toEqual({ studentId: "avi", courseId: "hebrew-letters" });
+        await bus.stop();
+    });
+    it("refuses externalEvents when no bus is configured", () => {
+        const consumer = defineModule("consumer", {
+            needs: { externalEvents: [StudentEnrolledEvent] },
+        });
+        expect(() => createApp({ modules: [consumer] })).toThrow(/no bus is configured/);
+    });
+    it("refuses externalEvents that this app also provides", () => {
+        const bus = new InMemoryEventBus();
+        const conflicted = defineModule("conflict", {
+            events: [StudentEnrolledEvent],
+            needs: { externalEvents: [StudentEnrolledEvent] },
+        });
+        expect(() => createApp({ modules: [conflicted], bus, appName: "x" })).toThrow(/this app also provides it/);
+    });
+    it("suppresses self-echoes (event from same appName is dropped at the subscriber)", async () => {
+        const bus = new InMemoryEventBus();
+        const selfPub = defineAction({
+            name: "self.publish",
+            schema: z.object({ studentId: z.string(), courseId: z.string() }),
+            handler: async (input) => StudentEnrolled({ studentId: input.studentId, courseId: input.courseId }),
+        });
+        let echoCount = 0;
+        const echoWorkflow = defineWorkflow("odd.echo-on-enrolled", ({ on }) => {
+            on(StudentEnrolledEvent, async () => {
+                echoCount += 1;
+            });
+        });
+        // Same app both produces AND declares external — pathological config,
+        // but the runtime should suppress echo by appName origin tag.
+        const oddModule = defineModule("odd", {
+            actions: [selfPub],
+            events: [StudentEnrolledEvent],
+            workflows: [echoWorkflow],
+            // Note: cannot ALSO declare externalEvents because validator
+            // rejects local+external for same event. So the echo path here
+            // exercises only the in-process reaction (1 invocation expected).
+        });
+        const app = createApp({
+            modules: [oddModule],
+            bus,
+            publishToBus: true,
+            appName: "odd-service",
+        });
+        await app.runtime.dispatch(selfPub, { studentId: "a", courseId: "c" });
+        // In-process reaction fired exactly once (no bus echo back).
+        expect(echoCount).toBe(1);
+        await bus.stop();
+    });
+    it("applyExternalEvent throws for un-declared event names", async () => {
+        const bus = new InMemoryEventBus();
+        const m = defineModule("m", { events: [InternalEvent] });
+        const app = createApp({ modules: [m], bus, appName: "x" });
+        await expect(app.runtime.applyExternalEvent("not-declared", {}, {
+            messageId: "m1",
+            correlationId: "c1",
+            causationId: "m1",
+            timestamp: new Date().toISOString(),
+            version: 1,
+        })).rejects.toThrow(/was not declared in any module's needs\.externalEvents/);
+        await bus.stop();
+    });
+});
+//# sourceMappingURL=cross-service-bus.test.js.map

package/dist/__tests__/cross-service-bus.test.js.map

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

package/dist/__tests__/define-schema.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * defineSchema — extracts data shape + lifecycle states + storage hints.
+ */
+export {};
+//# sourceMappingURL=define-schema.test.d.ts.map

package/dist/__tests__/define-schema.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-schema.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/define-schema.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/define-schema.test.js

@@ -0,0 +1,83 @@
+/**
+ * defineSchema — extracts data shape + lifecycle states + storage hints.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineSchema, isSchemaDefinition } from "../define-schema.js";
+describe("defineSchema", () => {
+    const Submission = defineSchema({
+        name: "submission",
+        key: "submissionId",
+        fields: {
+            submissionId: z.string(),
+            studentId: z.string(),
+            exerciseId: z.string(),
+            answer: z.string(),
+            verdict: z.string().optional(),
+            submittedAt: z.string().datetime(),
+        },
+        states: {
+            submitted: { initial: true },
+            "under-review": {},
+            graded: { final: true },
+        },
+        storage: {
+            indexes: [["studentId"], ["exerciseId"]],
+            unique: [["studentId", "exerciseId"]],
+        },
+    });
+    it("captures name, key, fields, states", () => {
+        expect(Submission.$kind).toBe("schema");
+        expect(Submission.name).toBe("submission");
+        expect(Submission.key).toBe("submissionId");
+        expect(Submission.initial).toBe("submitted");
+        expect(Submission.finals).toEqual(["graded"]);
+    });
+    it("compiles a zodSchema from fields", () => {
+        const parsed = Submission.zodSchema.parse({
+            submissionId: "s1",
+            studentId: "alice",
+            exerciseId: "e1",
+            answer: "42",
+            submittedAt: new Date().toISOString(),
+        });
+        expect(parsed.submissionId).toBe("s1");
+    });
+    it("rejects invalid payloads through zodSchema", () => {
+        expect(() => Submission.zodSchema.parse({ submissionId: 1 })).toThrow();
+    });
+    it("preserves storage hints", () => {
+        expect(Submission.storage.indexes).toEqual([["studentId"], ["exerciseId"]]);
+        expect(Submission.storage.unique).toEqual([["studentId", "exerciseId"]]);
+    });
+    it("throws if no state is marked initial", () => {
+        expect(() => defineSchema({
+            name: "bad",
+            key: "id",
+            fields: { id: z.string() },
+            states: { open: {}, closed: { final: true } },
+        })).toThrow(/no state declares `initial: true`/);
+    });
+    it("throws if multiple states are marked initial", () => {
+        expect(() => defineSchema({
+            name: "bad",
+            key: "id",
+            fields: { id: z.string() },
+            states: { a: { initial: true }, b: { initial: true } },
+        })).toThrow(/multiple states declare `initial: true`/);
+    });
+    it("throws if key is not in fields", () => {
+        expect(() => defineSchema({
+            name: "bad",
+            key: "missing",
+            fields: { id: z.string() },
+            states: { open: { initial: true } },
+        })).toThrow(/key "missing" is not declared in fields/);
+    });
+    it("isSchemaDefinition narrows correctly", () => {
+        expect(isSchemaDefinition(Submission)).toBe(true);
+        expect(isSchemaDefinition({})).toBe(false);
+        expect(isSchemaDefinition(null)).toBe(false);
+    });
+});
+//# sourceMappingURL=define-schema.test.js.map