@voltro/testing 0.1.0

package/dist/dialect.d.ts

@@ -0,0 +1,51 @@
+import { applySchema } from '@voltro/database/sql';
+import { DataStore } from '@voltro/database';
+import { SqlDialect } from '@voltro/database';
+
+export { applySchema }
+
+/**
+ * Per-dialect fixture passed into the harness. `setup` runs before
+ * each scenario, `teardown` after. Both are responsible for whatever
+ * the dialect needs to give the scenario a clean slate — temp-file
+ * sqlite, scratch docker postgres, etc.
+ *
+ * `make` returns the live `DataStore` for the scenario. Most fixtures
+ * will close the store + drop the scratch state in `teardown`.
+ */
+export declare interface DialectFixture {
+    readonly dialect: SqlDialect;
+    readonly name?: string;
+    readonly setup: () => Promise<void>;
+    readonly teardown: () => Promise<void>;
+    readonly make: () => Promise<DialectFixtureSession>;
+}
+
+export declare interface DialectFixtureSession {
+    readonly store: DataStore;
+    /** Apply `applySchema(tables, dialect.id)` against the same runtime
+     *  the store is using, so DDL and DML hit the same database. The
+     *  fixture knows how (most dialects expose a `run` method on their
+     *  store; the fixture forwards). */
+    readonly migrate: (tables: ReadonlyArray<unknown>) => Promise<void>;
+    /** Tear down the session (close store, drop scratch DB, etc.). */
+    readonly dispose: () => Promise<void>;
+}
+
+/**
+ * Register the dialect's parity suite with vitest. Calls
+ * `describe(...)` so the dialect's name appears in test output.
+ *
+ * Caller imports this from `@voltro/testing` inside its
+ * `__tests__/parity.test.ts` and supplies a fixture. The fixture's
+ * lifecycle hooks (`setup` / `teardown` / `make.dispose`) coordinate
+ * docker / temp-file state.
+ *
+ * Returning early when the fixture's `setup` throws keeps CI green on
+ * machines without docker — the fixture reports a clean skip via its
+ * own logic before calling `runDialectParity`. We don't soft-skip here
+ * because that would mask real fixture bugs.
+ */
+export declare const runDialectParity: (fixture: DialectFixture) => void;
+
+export { }

package/dist/dialect.js

@@ -0,0 +1,363 @@
+import { boolean as e, eq as t, id as n, integer as r, table as i, text as a, timestamp as o } from "@voltro/database";
+import { _voltroUndoLogTable as s, applyInverses as c, synthesizeInverse as l } from "@voltro/runtime";
+import { afterEach as u, beforeEach as d, describe as f, expect as p, it as m } from "vitest";
+import { applySchema as h } from "@voltro/database/sql";
+//#region src/dialectParity.ts
+var g = (e) => ({
+	table: e,
+	predicate: void 0,
+	order: [],
+	take: void 0,
+	skip: void 0,
+	projection: void 0
+}), _ = i("voltro_parity_a", {
+	id: n(),
+	title: a(),
+	count: r()
+}), v = i("voltro_parity_b", {
+	id: n(),
+	title: a()
+}), y = i("voltro_parity_c", {
+	id: n(),
+	title: a(),
+	count: r(),
+	flag: e().default(!1)
+}), b = i("voltro_parity_d", {
+	id: n(),
+	title: a(),
+	at: o().nullable(),
+	n: r().nullable()
+}), x = (e) => {
+	f(`dialect parity: ${e.name ?? e.dialect.id}`, () => {
+		let n = null;
+		d(async () => {
+			await e.setup(), n = await e.make(), await n.migrate([
+				_,
+				v,
+				y,
+				b,
+				s
+			]);
+			for (let e of [
+				"voltro_parity_a",
+				"voltro_parity_b",
+				"voltro_parity_c",
+				"voltro_parity_d",
+				"_voltro_undo_log"
+			]) {
+				let t = await n.store.query(g(e));
+				for (let r of t) await n.store.delete(e, r.id);
+			}
+		}), u(async () => {
+			await n?.dispose(), await e.teardown(), n = null;
+		}), m("DDL is idempotent — re-applying the schema is a no-op", async () => {
+			await n.migrate([_, v]);
+		}), m("insert + query round-trips a row", async () => {
+			p(await n.store.insert("voltro_parity_a", {
+				id: "a1",
+				title: "one",
+				count: 1
+			})).toMatchObject({
+				id: "a1",
+				title: "one",
+				count: 1
+			});
+			let e = await n.store.query(g("voltro_parity_a"));
+			p(e.length).toBe(1), p(e[0]?.id).toBe("a1");
+		}), m("update returns the post-image", async () => {
+			await n.store.insert("voltro_parity_a", {
+				id: "a2",
+				title: "pre",
+				count: 1
+			}), p(await n.store.update("voltro_parity_a", "a2", { title: "post" })).toMatchObject({
+				id: "a2",
+				title: "post"
+			});
+		}), m("delete removes the row + reports true", async () => {
+			await n.store.insert("voltro_parity_a", {
+				id: "a3",
+				title: "x",
+				count: 1
+			}), p(await n.store.delete("voltro_parity_a", "a3")).toBe(!0), p((await n.store.query(g("voltro_parity_a"))).length).toBe(0);
+		}), m("undo: the _voltro_undo_log TEXT changes column round-trips a JSON ChangeSet", async () => {
+			let e = [{
+				table: "voltro_parity_c",
+				op: "update",
+				id: "c1",
+				prev: {
+					id: "c1",
+					title: "t",
+					count: 1,
+					flag: !0
+				},
+				next: {
+					id: "c1",
+					title: "t",
+					count: 2,
+					flag: !1
+				}
+			}];
+			await n.store.insert("_voltro_undo_log", {
+				id: "undo_p1",
+				tag: "parityC.update",
+				label: null,
+				subjectId: null,
+				tenantId: null,
+				traceId: null,
+				changes: JSON.stringify(e),
+				crossesAction: !1,
+				undone: !1,
+				createdAt: /* @__PURE__ */ new Date()
+			});
+			let t = await n.store.query(g("_voltro_undo_log"));
+			p(t.length).toBe(1), p(JSON.parse(t[0].changes)).toEqual(e);
+		}), m("undo: reverts an INSERT (inverse delete) on this dialect", async () => {
+			let e = {
+				invocationId: "inv1",
+				subject: null,
+				changes: [{
+					table: "voltro_parity_c",
+					op: "insert",
+					next: await n.store.insert("voltro_parity_c", {
+						id: "c2",
+						title: "new",
+						count: 1,
+						flag: !0
+					})
+				}]
+			};
+			await c(n.store, l(e)), p((await n.store.query(g("voltro_parity_c"))).find((e) => e.id === "c2")).toBeUndefined();
+		}), m("undo: reverts an UPDATE including the BOOLEAN, restoring the captured value FAITHFULLY", async () => {
+			await n.store.insert("voltro_parity_c", {
+				id: "c3",
+				title: "t",
+				count: 1,
+				flag: !0
+			});
+			let e = (await n.store.query({
+				...g("voltro_parity_c"),
+				predicate: t("id", "c3")
+			}))[0], r = await n.store.update("voltro_parity_c", "c3", {
+				count: 2,
+				flag: !1
+			});
+			p(r.flag).not.toEqual(e.flag);
+			let i = {
+				invocationId: "inv2",
+				subject: null,
+				changes: [{
+					table: "voltro_parity_c",
+					op: "update",
+					id: "c3",
+					prev: e,
+					next: r
+				}]
+			};
+			await c(n.store, l(i));
+			let a = (await n.store.query({
+				...g("voltro_parity_c"),
+				predicate: t("id", "c3")
+			}))[0];
+			p(a.flag).toEqual(e.flag), p(a.count).toEqual(e.count);
+		}), m("undo: reverts a DELETE (inverse re-insert) on this dialect", async () => {
+			let e = await n.store.insert("voltro_parity_c", {
+				id: "c4",
+				title: "gone",
+				count: 9,
+				flag: !0
+			});
+			await n.store.delete("voltro_parity_c", "c4");
+			let r = {
+				invocationId: "inv3",
+				subject: null,
+				changes: [{
+					table: "voltro_parity_c",
+					op: "delete",
+					id: "c4",
+					prev: e
+				}]
+			};
+			await c(n.store, l(r));
+			let i = (await n.store.query({
+				...g("voltro_parity_c"),
+				predicate: t("id", "c4")
+			}))[0];
+			p(i.id).toBe("c4"), p(i.title).toBe("gone"), p(i.flag).toEqual(e.flag);
+		}), m("onChange fires insert + update + delete events", async () => {
+			let e = [], t = n.store.onChange((t) => e.push(t.op));
+			await n.store.insert("voltro_parity_a", {
+				id: "a4",
+				title: "a",
+				count: 1
+			}), await n.store.update("voltro_parity_a", "a4", { title: "b" }), await n.store.delete("voltro_parity_a", "a4"), t(), p(e).toEqual([
+				"insert",
+				"update",
+				"delete"
+			]);
+		}), m("transactional rolls back on throw + drops queued events", async () => {
+			let e = [], t = n.store.onChange((t) => e.push(t.op));
+			await p(n.store.transactional(async (e) => {
+				throw await e.insert("voltro_parity_a", {
+					id: "rollback",
+					title: "r",
+					count: 0
+				}), Error("intentional rollback");
+			})).rejects.toThrow("intentional rollback"), t(), p(e).toEqual([]), p((await n.store.query(g("voltro_parity_a"))).length).toBe(0);
+		}), m("transactional commit drains queued events in order", async () => {
+			let e = [], t = n.store.onChange((t) => e.push(t.op));
+			await n.store.transactional(async (e) => {
+				await e.insert("voltro_parity_a", {
+					id: "commit1",
+					title: "a",
+					count: 1
+				}), await e.insert("voltro_parity_a", {
+					id: "commit2",
+					title: "b",
+					count: 2
+				});
+			}), t(), p(e).toEqual(["insert", "insert"]);
+		}), m("upsert inserts a new row, then updates on conflict — no duplicate", async () => {
+			await n.store.upsert("voltro_parity_a", {
+				id: "u1",
+				title: "first",
+				count: 1
+			}, { conflictColumns: ["id"] }), await n.store.upsert("voltro_parity_a", {
+				id: "u1",
+				title: "second",
+				count: 2
+			}, {
+				conflictColumns: ["id"],
+				update: ["title", "count"]
+			});
+			let e = await n.store.query(g("voltro_parity_a"));
+			p(e.length).toBe(1), p(e[0]).toMatchObject({
+				id: "u1",
+				title: "second",
+				count: 2
+			});
+		}), m("insert + update bind an explicit NULL into a datetime2/int column", async () => {
+			p(await n.store.insert("voltro_parity_d", {
+				id: "nd1",
+				title: "nulls",
+				at: null,
+				n: null
+			})).toMatchObject({
+				id: "nd1",
+				title: "nulls",
+				at: null,
+				n: null
+			}), await n.store.insert("voltro_parity_d", {
+				id: "nd2",
+				title: "set",
+				at: /* @__PURE__ */ new Date(),
+				n: 7
+			}), p(await n.store.update("voltro_parity_d", "nd2", {
+				at: null,
+				n: null
+			})).toMatchObject({
+				id: "nd2",
+				at: null,
+				n: null
+			});
+		}), m("updateMany updates only the rows matching the predicate + returns the count", async () => {
+			await n.store.insert("voltro_parity_a", {
+				id: "m1",
+				title: "x",
+				count: 5
+			}), await n.store.insert("voltro_parity_a", {
+				id: "m2",
+				title: "y",
+				count: 5
+			}), await n.store.insert("voltro_parity_a", {
+				id: "m3",
+				title: "z",
+				count: 9
+			}), p(await n.store.updateMany("voltro_parity_a", { title: "hit" }, { where: {
+				column: "count",
+				op: "eq",
+				value: 5
+			} })).toBe(2), p((await n.store.query({
+				...g("voltro_parity_a"),
+				predicate: {
+					column: "title",
+					op: "eq",
+					value: "hit"
+				}
+			})).length).toBe(2);
+		}), m("updateMany with an AND predicate is an atomic compare-and-set (the wakeup-claim pattern)", async () => {
+			await n.store.insert("voltro_parity_a", {
+				id: "cas",
+				title: "pending",
+				count: 1
+			});
+			let e = (e) => ({ and: [{
+				column: "id",
+				op: "eq",
+				value: "cas"
+			}, {
+				column: "title",
+				op: "eq",
+				value: e
+			}] });
+			p(await n.store.updateMany("voltro_parity_a", { title: "claimed" }, { where: e("pending") })).toBe(1), p(await n.store.updateMany("voltro_parity_a", { title: "claimed-again" }, { where: e("pending") })).toBe(0);
+		}), m("deleteMany removes only the rows matching the predicate + returns the count", async () => {
+			await n.store.insert("voltro_parity_a", {
+				id: "d1",
+				title: "x",
+				count: 5
+			}), await n.store.insert("voltro_parity_a", {
+				id: "d2",
+				title: "y",
+				count: 5
+			}), await n.store.insert("voltro_parity_a", {
+				id: "d3",
+				title: "z",
+				count: 9
+			}), p(await n.store.deleteMany("voltro_parity_a", { where: {
+				column: "count",
+				op: "eq",
+				value: 5
+			} })).toBe(2), p((await n.store.query(g("voltro_parity_a"))).map((e) => e.id)).toEqual(["d3"]);
+		}), m("deleteMany emits one delete ChangeEvent per removed row (old-image)", async () => {
+			await n.store.insert("voltro_parity_a", {
+				id: "e1",
+				title: "gone",
+				count: 1
+			}), await n.store.insert("voltro_parity_a", {
+				id: "e2",
+				title: "gone",
+				count: 1
+			}), await n.store.insert("voltro_parity_a", {
+				id: "e3",
+				title: "stay",
+				count: 2
+			});
+			let e = [], t = n.store.onChange((t) => e.push({
+				op: t.op,
+				id: t.old?.id
+			})), r = await n.store.deleteMany("voltro_parity_a", { where: {
+				column: "title",
+				op: "eq",
+				value: "gone"
+			} });
+			t(), p(r).toBe(2);
+			let i = e.filter((e) => e.op === "delete");
+			p(i).toHaveLength(2), p(i.map((e) => e.id).sort()).toEqual(["e1", "e2"]);
+		}), m("deleteMany with no match returns 0 and removes nothing", async () => {
+			await n.store.insert("voltro_parity_a", {
+				id: "k1",
+				title: "keep",
+				count: 1
+			}), p(await n.store.deleteMany("voltro_parity_a", { where: {
+				column: "title",
+				op: "eq",
+				value: "absent"
+			} })).toBe(0), p((await n.store.query(g("voltro_parity_a"))).length).toBe(1);
+		}), m("retryFilter recognises the dialect's own transient codes", () => {
+			let t = e.dialect.retryFilter(/* @__PURE__ */ Error("garbage"));
+			p(["retry", "noRetry"]).toContain(t);
+		});
+	});
+};
+//#endregion
+export { h as applySchema, x as runDialectParity };

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+import { AppContext } from '@voltro/runtime';
+import { Effect } from 'effect';
+import { InspectedStep } from '@voltro/workflow';
+import { InspectedWorkflow } from '@voltro/workflow';
+import { Layer } from 'effect';
+import { ParseResult } from 'effect';
+import { ProcedureDescriptor } from '@voltro/protocol';
+import { Row } from '@voltro/database';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { TableLike } from '@voltro/database';
+
+/** Effect shape the runner erases a workflow's success/error/requirement
+ *  channels down to. `unknown` for value/error (covariant — anything
+ *  assigns), `never` for the requirement (the runner provides the engine
+ *  layer itself). Callers pass concrete workflows cast via `as never` —
+ *  `never` assigns to any field type, so the object-literal form stays
+ *  ergonomic without an `any` in the public type. */
+declare type ErasedWorkflowEffect = Effect.Effect<unknown, unknown, never>;
+
+/**
+ * Decode `rawInput` through the procedure descriptor's `input` Schema, then
+ * call `executor` with the decoded value and `ctx`. Rejects with a
+ * `ParseError` if `rawInput` doesn't satisfy the input Schema — the same
+ * validation the live dispatcher runs before your handler sees the input.
+ *
+ * Only the input-decode hop is reproduced (see the file header): guards /
+ * middleware are dispatch-time rpc concerns, not descriptor-carried.
+ *
+ * ```ts
+ * import { createNote } from './notes.mutation'          // descriptor
+ * import { createNoteHandler } from './notes.mutation.server' // executor
+ *
+ * const ctx = makeTestContext({ subject: user('A') })
+ * const note = await invoke(createNote, createNoteHandler, { title: 'hi' }, ctx)
+ * // a bad shape rejects at the decode, before the handler runs:
+ * await expect(invoke(createNote, createNoteHandler, { title: 42 }, ctx)).rejects.toThrow()
+ * ```
+ */
+export declare const invoke: <D extends Pick<ProcedureDescriptor, "input">, Output>(descriptor: D, executor: ProcedureExecutor<Schema.Schema.Type<D["input"]>, Output>, rawInput: unknown, ctx: TestContext) => Promise<Output>;
+
+export declare const makeTestContext: (options?: MakeTestContextOptions) => TestContext;
+
+export declare interface MakeTestContextOptions {
+    /** The acting subject. Default: anonymous, no tenant. Read it back at
+     *  `ctx.request.subject` (the same place a live handler reads it). */
+    readonly subject?: Subject;
+    /** Tables to wire into the store's schema. Default: all globally
+     *  registered tables (whatever the test imported). */
+    readonly tables?: ReadonlyArray<TableLike>;
+    /** Seed rows keyed by table name (use `mockStore({...})`). */
+    readonly store?: Record<string, ReadonlyArray<Row>>;
+    /** Frozen clock start. Default 2026-01-01T00:00:00Z. */
+    readonly clockStart?: Date;
+    /** Injected AI mock (plan 05's `mockAi({...})`). */
+    readonly ai?: MockAi;
+    /** Queued LLM responses for the bundled `MockLLM`. */
+    readonly llmResponses?: ReadonlyArray<MockResponse>;
+    /** Env values sealed into the boot snapshot so handler code that reads
+     *  `getSecret('X')` / `serverEnv.X` resolves under test. Without a snapshot
+     *  those accessors throw ("read before the boot env gate ran") because the
+     *  test harness never runs the real boot gate. Merged OVER `process.env`
+     *  (these win). Default: just the ambient `process.env`. */
+    readonly env?: Record<string, string | undefined>;
+}
+
+export declare const makeWorkflowRunner: (opts: MakeWorkflowRunnerOptions) => WorkflowRunner;
+
+export declare interface MakeWorkflowRunnerOptions {
+    readonly ctx: TestContext;
+    readonly workflows?: ReadonlyArray<WorkflowEntry>;
+}
+
+/** Minimal AI mock surface. The full `mockAi({...})` helper is owned by
+ *  the AI package (plan 05); typed here as an optional injected interface
+ *  so `@voltro/testing` carries no hard `@voltro/ai` dependency. */
+export declare interface MockAi {
+    readonly generate?: (...args: ReadonlyArray<unknown>) => unknown;
+    readonly generateObject?: (...args: ReadonlyArray<unknown>) => unknown;
+}
+
+export declare class MockClock {
+    private currentMs;
+    constructor(initial?: Date | number);
+    /** Current mock time as an instant in ms. */
+    now(): number;
+    /** Current mock time as a Date. */
+    date(): Date;
+    /** Advance time by a duration (ms / seconds / minutes / hours / days). */
+    advance(amount: number | string): void;
+}
+
+export declare class MockEmail {
+    readonly sent: SentEmail[];
+    send(email: Omit<SentEmail, 'sentAt'>): void;
+    /** Find the most recent email to a recipient, or undefined. */
+    lastTo(recipient: string): SentEmail | undefined;
+    clear(): void;
+}
+
+export declare class MockLLM {
+    private readonly queue;
+    readonly calls: MockLLMCall[];
+    constructor(responses: ReadonlyArray<MockResponse>);
+    next(call: MockLLMCall): MockResponse;
+    remaining(): number;
+}
+
+export declare interface MockLLMCall {
+    readonly model: string;
+    readonly messages: ReadonlyArray<unknown>;
+    readonly tools?: ReadonlyArray<string>;
+}
+
+export declare type MockResponse = {
+    readonly text: string;
+} | {
+    readonly toolCall: {
+        readonly name: string;
+        readonly input: unknown;
+    };
+} | {
+    readonly error: {
+        readonly code: string;
+        readonly message?: string;
+    };
+};
+
+/** Seed helper: `makeTestContext({ store: mockStore({ docs: [...] }) })`.
+ *  Identity over the table→rows map; exists so the call site reads well. */
+export declare const mockStore: (seed: Record<string, ReadonlyArray<Row>>) => Record<string, ReadonlyArray<Row>>;
+
+export { ParseResult }
+
+/** Any procedure executor: takes the DECODED input + a context, returns a
+ *  result (sync or async). Mirrors the `(input, ctx) => …` shape a real
+ *  query / mutation / action handler has. */
+export declare type ProcedureExecutor<Input, Output> = (input: Input, ctx: TestContext) => Output | Promise<Output>;
+
+export declare interface SentEmail {
+    readonly to: string;
+    readonly template: string;
+    readonly props?: Readonly<Record<string, unknown>>;
+    readonly locale?: string;
+    readonly sentAt: Date;
+}
+
+/** The test context IS an `AppContext` (store + request + cache), plus the
+ *  deterministic doubles and the subject/tenant re-scopers. Because it
+ *  extends `AppContext`, you can pass it straight into an executor typed
+ *  `(input, ctx: AppContext) => …`. */
+export declare interface TestContext extends AppContext {
+    readonly clock: MockClock;
+    readonly email: MockEmail;
+    readonly llm: MockLLM;
+    readonly ai?: MockAi;
+    /** Re-scope to a different subject for one block (real subject swap, not
+     *  a closure stub). Shares the underlying data so cross-subject reads
+     *  exercise real tenant scoping. */
+    withSubject<T>(subject: Subject, fn: (ctx: TestContext) => T | Promise<T>): Promise<T>;
+    /** Re-scope to a different tenant (keeps the current subject identity). */
+    withTenant<T>(tenantId: string, fn: (ctx: TestContext) => T | Promise<T>): Promise<T>;
+}
+
+export declare const TESTING_PRESET_VERSION: 1;
+
+/** A workflow + its execute function, as the framework pairs them via
+ *  `workflow.toLayer(execute)`. Structural (no `@effect/workflow` generic
+ *  signature) so callers can pass the value from `workflow({ name, ... })`
+ *  plus its `(payload, executionId) => Effect` execute directly — type-erased
+ *  over the workflow's payload/success/error/requirement shapes. */
+export declare interface WorkflowEntry {
+    readonly workflow: {
+        readonly name: string;
+        readonly execute: (payload: unknown, options?: unknown) => ErasedWorkflowEffect;
+        readonly toLayer: (execute: (payload: unknown, executionId: string) => ErasedWorkflowEffect) => Layer.Layer<unknown, unknown, never>;
+    };
+    readonly execute: (payload: unknown, executionId: string) => ErasedWorkflowEffect;
+}
+
+export declare interface WorkflowRunner {
+    /** Start a workflow by its `name` (tag) with a payload and block until
+     *  terminal. Records every step attempt so `result.steps[i].attempts`
+     *  reflects real retries. */
+    start(workflowName: string, payload: unknown): Promise<WorkflowRunResult>;
+    /** Inspect a previously-started run by id without re-running it. Returns
+     *  `null` for an unknown run id. */
+    inspect(runId: string): Promise<InspectedWorkflow | null>;
+}
+
+export declare interface WorkflowRunResult {
+    readonly status: 'succeeded' | 'failed';
+    readonly output: unknown;
+    readonly error: {
+        readonly tag: string | null;
+        readonly message: string;
+    } | null;
+    readonly steps: ReadonlyArray<InspectedStep>;
+    readonly runId: string;
+}
+
+export { }