@voltro/testing 0.24.0 → 0.26.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { AppContext } from '@voltro/runtime';
 import { Effect } from 'effect';
+import { EventBus } from '@voltro/runtime';
+import { EventDescriptor } from '@voltro/protocol';
 import { InspectedStep } from '@voltro/workflow';
 import { InspectedWorkflow } from '@voltro/workflow';
 import { Layer } from 'effect';
@@ -283,7 +285,7 @@ export declare const mockStore: (seed: Record<string, ReadonlyArray<Row>>) => Re
 export declare class MockWebhooks {
     readonly emitted: EmittedWebhook[];
     /** Mirrors `WebhooksServiceShape.emit`. Accepts the event id OR a
-     *  `defineOutgoingEvent` descriptor, exactly as the real service does — the
+     *  declared event, exactly as the real service does — the
      *  handler under test should not have to be written differently to be
      *  testable. */
     emit<P>(event: string | {
@@ -321,6 +323,13 @@ export declare interface ReachableTarget {
     readonly timeoutMs?: number;
 }
 
+/** One delivery a test subscriber saw. */
+export declare interface RecordedDelivery<P = unknown> {
+    readonly payload: P;
+    readonly origin: string;
+    readonly n: number;
+}
+
 /**
  * Drop queued post-commit work WITHOUT running it.
  *
@@ -401,8 +410,79 @@ export declare interface TestContext extends AppContext {
     withTenant<T>(tenantId: string, fn: (ctx: TestContext) => T | Promise<T>): Promise<T>;
 }
 
+export declare interface TestEventBus {
+    /**
+     * Publish exactly as a handler would — through the real validation, the real
+     * size gate and the real serial assignment. A payload that does not match the
+     * descriptor fails here, which is the point: a harness that skipped validation
+     * would let a test pass on a payload production rejects.
+     */
+    publish<Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any>(descriptor: EventDescriptor<Name, Key, Payload>, key: Schema.Schema.Type<Key>, payload: Schema.Schema.Type<Payload>): Promise<{
+        readonly n: number;
+    }>;
+    /** Publish and ASSERT it succeeded — the common case, one line. */
+    subscribe<Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any>(descriptor: EventDescriptor<Name, Key, Payload>, key: Schema.Schema.Type<Key>, options?: {
+        readonly tenantId?: string | null;
+        readonly resume?: ReadonlyArray<{
+            origin: string;
+            n: number;
+        }>;
+    }): TestSubscriber<Schema.Schema.Type<Payload>>;
+    /**
+     * Force a gap WITHOUT waiting for a buffer to overflow.
+     *
+     * A consumer's recovery path (`onMissed` → resync) is the hardest thing to
+     * test honestly, because provoking a real loss means racing a queue. This
+     * injects a delivery `count` serials ahead, so the next subscriber to resume
+     * is owed messages the ring never held — exactly the shape a slow consumer
+     * produces, deterministically.
+     */
+    skipSerials<Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any>(descriptor: EventDescriptor<Name, Key, Payload>, key: Schema.Schema.Type<Key>, count: number, options?: {
+        readonly tenantId?: string | null;
+    }): void;
+    /** The underlying bus, for a test that needs something not exposed here. */
+    readonly bus: EventBus;
+    /** Drop every subscriber and buffer. */
+    readonly reset: () => void;
+}
+
+/**
+ * A running event bus with no transport.
+ *
+ * ```ts
+ * const events = testEventBus()
+ * const display = events.subscribe(gameStarted, { arenaId: 'a1' })
+ * await events.publish(gameStarted, { arenaId: 'a1' }, { gameId: 'g1' })
+ * expect(display.received).toEqual([{ gameId: 'g1' }])
+ * ```
+ */
+export declare const testEventBus: (options?: TestEventBusOptions) => TestEventBus;
+
+export declare interface TestEventBusOptions {
+    /** Default tenant for publishes and subscriptions. `null` = system. */
+    readonly tenantId?: string | null;
+    /** Ring depth — a small one makes an eviction test deterministic. */
+    readonly ringSize?: number;
+    readonly origin?: string;
+}
+
 export declare const TESTING_PRESET_VERSION: 1;
 
+export declare interface TestSubscriber<P = unknown> {
+    /** Payloads delivered so far, in order. */
+    readonly received: ReadonlyArray<P>;
+    /** Full envelopes, when a test cares about serials or origin. */
+    readonly deliveries: ReadonlyArray<RecordedDelivery<P>>;
+    /** Losses the server could PROVE, with their cause. */
+    readonly missed: ReadonlyArray<{
+        readonly count: number;
+        readonly reason: 'buffer' | 'resume';
+    }>;
+    /** Total proven losses. */
+    readonly missedCount: number;
+    readonly stop: () => void;
+}
+
 /** 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, ... })`

package/dist/index.js

@@ -1,13 +1,13 @@
 import { AUTO_FILLED_COLUMNS as e, allRegisteredTables as t, clearRelationsRegistry as n, missingRequiredColumns as r, registerRelations as i } from "@voltro/database";
 import { Cause as a, Effect as o, Exit as s, Layer as c, Schema as l } from "effect";
-import { SubjectService as u, anonymousSubject as d, checkGuardsEffect as f, composeRpcInterceptors as p, tenantScopedSubject as m } from "@voltro/protocol";
-import { InMemoryDataStore as h, applyRowFilterToDescriptor as g, clearSystemStoreHandle as _, getRowFilter as v, getSystemStoreHandle as y, makeAppAccess as b, makeDataLoader as x, makeEffectStoreLayer as S, makeOutboxFacade as C, makeSchemaRegistry as ee, resolveRowFilterScopeFor as te, runProvidedEffect as w, runWithDeadlockRetry as T, setSystemStoreHandle as E, wrapStoreWithMixinBehaviour as D } from "@voltro/runtime";
-import { installEnvSnapshot as O } from "@voltro/env";
-import k from "node:net";
-import { describe as A } from "vitest";
-import { CurrentWorkflowRunId as j, inMemoryWorkflowEngineLayer as M, makeInMemoryRecorder as N } from "@voltro/workflow";
+import { SubjectService as u, anonymousSubject as d, checkGuardsEffect as f, composeRpcInterceptors as p, eventRoute as m, tenantScopedSubject as h } from "@voltro/protocol";
+import { EventBus as g, InMemoryDataStore as _, applyRowFilterToDescriptor as v, clearSystemStoreHandle as y, getRowFilter as b, getSystemStoreHandle as x, makeAppAccess as ee, makeDataLoader as S, makeEffectStoreLayer as C, makeOutboxFacade as w, makeSchemaRegistry as T, publishEvent as te, resolveRowFilterScopeFor as E, runProvidedEffect as D, runWithDeadlockRetry as O, setSystemStoreHandle as k, wrapStoreWithMixinBehaviour as A } from "@voltro/runtime";
+import { installEnvSnapshot as j } from "@voltro/env";
+import M from "node:net";
+import { describe as N } from "vitest";
+import { CurrentWorkflowRunId as ne, inMemoryWorkflowEngineLayer as re, makeInMemoryRecorder as ie } from "@voltro/workflow";
 //#region src/fixtureRow.ts
-var P = new Set(e), F = 0, ne = (e, t) => {
+var ae = new Set(e), P = 0, oe = (e, t) => {
 	if (t.oneOf && t.oneOf.length > 0) return t.oneOf[0];
 	if (t.enumValues && t.enumValues.length > 0) return t.enumValues[0];
 	let n = t.unique === !0;
@@ -15,24 +15,24 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 		case "text":
 		case "reference":
 		case "id":
-		case "enum": return n ? `${e}-${++F}` : e;
+		case "enum": return n ? `${e}-${++P}` : e;
 		case "integer":
-		case "real": return n ? ++F : 0;
+		case "real": return n ? ++P : 0;
 		case "decimal":
-		case "bigint": return n ? String(++F) : "0";
+		case "bigint": return n ? String(++P) : "0";
 		case "boolean": return !1;
 		case "timestamp":
 		case "date": return /* @__PURE__ */ new Date(0);
 		default: throw Error(`fixtureRow: column '${e}' is a required '${t.type}' with no default, and fixtureRow can't synthesize a safe placeholder for that type. Pass it explicitly: fixtureRow(table, { ${e}: … }).`);
 	}
-}, re = (e, t = {}) => {
+}, se = (e, t = {}) => {
 	let n = {};
-	for (let i of r(e, t)) P.has(i) || (n[i] = ne(i, e.fields[i]));
+	for (let i of r(e, t)) ae.has(i) || (n[i] = oe(i, e.fields[i]));
 	return {
 		...n,
 		...t
 	};
-}, I = class {
+}, F = class {
 	currentMs;
 	constructor(e = /* @__PURE__ */ new Date("2026-01-01T00:00:00Z")) {
 		this.currentMs = typeof e == "number" ? e : e.getTime();
@@ -44,9 +44,9 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 		return new Date(this.currentMs);
 	}
 	advance(e) {
-		this.currentMs += typeof e == "number" ? e : ie(e);
+		this.currentMs += typeof e == "number" ? e : I(e);
 	}
-}, ie = (e) => {
+}, I = (e) => {
 	let t = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)\s*$/.exec(e);
 	if (!t) throw Error(`mockClock: cannot parse duration '${e}'`);
 	let n = Number(t[1]), r = t[2];
@@ -122,13 +122,13 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 	let n = [...t];
 	t.length = 0;
 	for (let e of n) await e();
-}, ae = (e) => W.get(e) ?? [], Y = async (e, t) => {
+}, Y = (e) => W.get(e) ?? [], X = async (e, t) => {
 	let n = H.get(e);
 	return n === void 0 ? e.store.transactional(async (n) => t({
 		...e,
 		store: n
 	})) : n(t);
-}, oe = (e) => {
+}, ce = (e) => {
 	let t = /* @__PURE__ */ new Map(), n = /* @__PURE__ */ new Map(), r = (n) => {
 		let r = t.get(n);
 		return r === void 0 ? !1 : r.expiresAt !== null && r.expiresAt <= e() ? (t.delete(n), !1) : !0;
@@ -167,7 +167,7 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 			return i(e, o, n.ttlMs, n.tags), o;
 		}
 	};
-}, se = (e) => {
+}, le = (e) => {
 	let t = /* @__PURE__ */ new Map(), n = (n) => {
 		let r = t.get(n);
 		return r === void 0 ? !1 : r.expiresAt !== null && r.expiresAt <= e() ? (t.delete(n), !1) : !0;
@@ -195,62 +195,62 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 			t.clear();
 		}
 	};
-}, ce = async (e, t) => {
-	let n = y();
-	E(e);
+}, ue = async (e, t) => {
+	let n = x();
+	k(e);
 	try {
 		return await t();
 	} finally {
-		n === void 0 ? _() : E(n);
+		n === void 0 ? y() : k(n);
 	}
-}, le = (e, t, n) => {
-	let r = X, i;
+}, de = (e, t, n) => {
+	let r = fe, i;
 	return () => {
-		let a = t ?? v();
-		return (i === void 0 || a !== r) && (r = a, i = ce(n, () => w(te(a, e, (e) => {
+		let a = t ?? b();
+		return (i === void 0 || a !== r) && (r = a, i = ue(n, () => D(E(a, e, (e) => {
 			console.error("[voltro:testing] row filter failed to load — reads refused for this subject", e);
 		})))), i;
 	};
-}, X = Symbol("unresolved"), Z = (e, t) => new Proxy(e, { get: (e, n) => {
-	if (n === "query") return async (n) => e.query(g(await t(), n));
+}, fe = Symbol("unresolved"), Z = (e, t) => new Proxy(e, { get: (e, n) => {
+	if (n === "query") return async (n) => e.query(v(await t(), n));
 	let r = Reflect.get(e, n, e);
 	return typeof r == "function" ? r.bind(e) : r;
-} }), ue = (e = {}) => {
-	if (O({
+} }), pe = (e = {}) => {
+	if (j({
 		...process.env,
 		...e.env ?? {}
 	}), e.relations !== void 0) {
 		n();
 		for (let t of e.relations) i(t);
 	}
-	let r = ee(e.tables ?? t()), a = new h(e.store ?? {}), o = {
+	let r = T(e.tables ?? t()), a = new _(e.store ?? {}), o = {
 		dataStore: a,
 		schemaRegistry: r
 	};
-	E(o);
-	let s = new I(e.clockStart), c = new L(), l = new R(), u = new z(e.llmResponses ?? []), f = oe(() => s.now()), p = se(() => s.now()), g = (t, n = a, i) => {
+	k(o);
+	let s = new F(e.clockStart), c = new L(), l = new R(), u = new z(e.llmResponses ?? []), f = ce(() => s.now()), p = le(() => s.now()), m = (t, n = a, i) => {
 		let d = {
 			subject: t,
 			traceId: V
-		}, h = i?.queued ?? [], _ = i?.nudges ?? [], v = x({ store: n }), y = le(t, e.rowFilter, o), S = {
+		}, g = i?.queued ?? [], _ = i?.nudges ?? [], v = S({ store: n }), y = de(t, e.rowFilter, o), b = {
 			clock: s,
 			email: c,
 			webhooks: l,
 			llm: u,
 			...e.ai === void 0 ? {} : { ai: e.ai },
 			request: d,
-			access: b(t),
+			access: ee(t),
 			cache: f,
 			kv: p,
-			store: D(Z(n, y), {
+			store: A(Z(n, y), {
 				subject: t,
 				schemaRegistry: r
 			}),
-			storeForTenant: (e) => D(Z(n, y), {
-				subject: m(t, e),
+			storeForTenant: (e) => A(Z(n, y), {
+				subject: h(t, e),
 				schemaRegistry: r
 			}),
-			outbox: C({
+			outbox: w({
 				store: n,
 				subject: t,
 				traceId: V,
@@ -258,33 +258,33 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 					_.push(V);
 				},
 				afterCommit: (e) => {
-					h.push(e);
+					g.push(e);
 				}
 			}),
 			load: v.load,
 			loadMany: v.loadMany,
-			withSubject: (e, t) => Promise.resolve(t(g(e, n, {
-				queued: h,
+			withSubject: (e, t) => Promise.resolve(t(m(e, n, {
+				queued: g,
 				nudges: _
 			}))),
-			withTenant: (e, r) => Promise.resolve(r(g({
+			withTenant: (e, r) => Promise.resolve(r(m({
 				...t,
 				tenantId: e
 			}, n, {
-				queued: h,
+				queued: g,
 				nudges: _
 			})))
 		};
-		return U.set(S, h), W.set(S, _), G.set(S, e.plugins ?? []), H.set(S, (e) => n.transactional((n) => e(g(t, n, {
-			queued: h,
+		return U.set(b, g), W.set(b, _), G.set(b, e.plugins ?? []), H.set(b, (e) => n.transactional((n) => e(m(t, n, {
+			queued: g,
 			nudges: _
-		})))), S;
+		})))), b;
 	};
-	return g(e.subject ?? d(null));
-}, de = (e, t) => e.pipe(o.provide(S(t.store)), o.provideService(u, t.request.subject)), fe = async (e, t, n, r) => {
+	return m(e.subject ?? d(null));
+}, me = (e, t) => e.pipe(o.provide(C(t.store)), o.provideService(u, t.request.subject)), he = async (e, t, n, r) => {
 	let i = e.input, c = await l.decodeUnknownPromise(i)(n), u = e.kind, d = async (e) => {
 		let n = t(c, e);
-		return o.isEffect(n) ? w(de(n, e)) : n;
+		return o.isEffect(n) ? D(me(n, e)) : n;
 	}, p = async () => {
 		let t = e.guards;
 		if (t !== void 0 && t.length > 0) {
@@ -292,7 +292,7 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 			if (e !== null) throw e;
 		}
 		if (u !== "mutation") return d(r);
-		let n = await T(async () => (q(r), Y(r, async (e) => d(e))), { delay: () => Promise.resolve() });
+		let n = await O(async () => (q(r), X(r, async (e) => d(e))), { delay: () => Promise.resolve() });
 		return await J(r), n;
 	}, m = u === "mutation" || u === "query" || u === "action" ? u : void 0, h = m === void 0 ? void 0 : K(r, m);
 	if (h === void 0 || m === void 0) return await p();
@@ -310,7 +310,7 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 	if (s.isSuccess(_)) return _.value;
 	throw a.squash(_.cause);
 }, Q = (e) => new Promise((t) => {
-	let n = new k.Socket(), r = (e) => {
+	let n = new M.Socket(), r = (e) => {
 		clearTimeout(i), n.destroy(), t(e);
 	}, i = setTimeout(() => r(!1), e.timeoutMs ?? 750);
 	n.once("connect", () => r(!0)), n.once("error", () => r(!1)), n.connect(e.port, e.host);
@@ -321,10 +321,80 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 	} catch {
 		i = !1;
 	}
-	A.skipIf(!i)(i ? e : `${e} [SKIPPED: needs ${t}]`, r);
-}, pe = async (e, t, n) => {
+	N.skipIf(!i)(i ? e : `${e} [SKIPPED: needs ${t}]`, r);
+}, ge = async (e, t, n) => {
 	await $(e, `${t.name} at ${t.host}:${t.port}`, () => Q(t), n);
-}, me = (e) => {
+}, _e = (e = {}) => {
+	let t = e.tenantId ?? null, n = new g({
+		origin: e.origin ?? "test",
+		...e.ringSize === void 0 ? {} : { ringSize: e.ringSize }
+	});
+	return {
+		publish: async (e, r, i) => {
+			let a = await o.runPromise(o.either(te({
+				bus: n,
+				tenantId: t
+			}, e, r, i)));
+			if (a._tag === "Left") {
+				let t = a.left;
+				throw Error(`testEventBus.publish(${e.name}) was rejected: ${t._tag}`, { cause: t });
+			}
+			return { n: a.right.n };
+		},
+		subscribe: (e, r, i) => {
+			let a = [], o = [];
+			return {
+				get received() {
+					return a.map((e) => e.payload);
+				},
+				get deliveries() {
+					return a;
+				},
+				get missed() {
+					return o;
+				},
+				get missedCount() {
+					return o.reduce((e, t) => e + t.count, 0);
+				},
+				stop: n.subscribe({
+					tenantId: i?.tenantId ?? t,
+					event: e.name,
+					key: r,
+					listener: (e) => {
+						if (e.kind === "gap") {
+							o.push({
+								count: e.missed,
+								reason: e.reason
+							});
+							return;
+						}
+						a.push({
+							payload: e.envelope.payload,
+							origin: e.envelope.origin,
+							n: e.envelope.n
+						});
+					},
+					...i?.resume === void 0 ? {} : { options: { resume: i.resume } }
+				})
+			};
+		},
+		skipSerials: (e, r, i, a) => {
+			let o = {
+				route: m(a?.tenantId ?? t, e.name, r),
+				event: e.name,
+				origin: "test-gap",
+				n: i + 1,
+				emittedAt: Date.now(),
+				payload: void 0
+			};
+			n.injectRemote(o);
+		},
+		bus: n,
+		reset: () => {
+			n.clear();
+		}
+	};
+}, ve = (e) => {
 	let t = /* @__PURE__ */ new Map();
 	for (let n of e) {
 		let e = t.get(n.stepName);
@@ -350,13 +420,13 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 		});
 	}
 	return n.sort((e, t) => e._startedAt - t._startedAt), n.map(({ _startedAt: e, ...t }) => t);
-}, he = (e) => {
+}, ye = (e) => {
 	let t = e.workflows ?? [], n = /* @__PURE__ */ new Map(), r = 0;
 	return {
 		start: async (i, a) => {
 			let s = t.find((e) => e.workflow.name === i);
 			if (s === void 0) throw Error(`makeWorkflowRunner: no workflow named '${i}' — pass it in makeWorkflowRunner({ ctx, workflows: [{ workflow, execute }] }).`);
-			let l = `wfrun_test_${++r}`, u = N(), d = s.workflow.toLayer(s.execute).pipe(c.provideMerge(M)), f = /* @__PURE__ */ new Date(), p = s.workflow.execute(a).pipe(o.locally(j, l), o.provide(u.layer), o.provide(d), o.either), m = await o.runPromise(p), h = me(u.readSteps()), g = /* @__PURE__ */ new Date(), _;
+			let l = `wfrun_test_${++r}`, u = ie(), d = s.workflow.toLayer(s.execute).pipe(c.provideMerge(re)), f = /* @__PURE__ */ new Date(), p = s.workflow.execute(a).pipe(o.locally(ne, l), o.provide(u.layer), o.provide(d), o.either), m = await o.runPromise(p), h = ve(u.readSteps()), g = /* @__PURE__ */ new Date(), _;
 			if (m._tag === "Right") _ = {
 				status: "succeeded",
 				output: m.right,
@@ -396,6 +466,6 @@ var P = new Set(e), F = 0, ne = (e, t) => {
 		},
 		inspect: async (e) => n.get(e) ?? null
 	};
-}, ge = 1;
+}, be = 1;
 //#endregion
-export { I as MockClock, L as MockEmail, z as MockLLM, R as MockWebhooks, ge as TESTING_PRESET_VERSION, $ as describeIfAvailable, pe as describeIfReachable, re as fixtureRow, fe as invoke, Q as isTcpReachable, ue as makeTestContext, he as makeWorkflowRunner, B as mockStore, ae as outboxNudgesOf, q as resetAfterCommit, K as rpcInterceptorFor, J as runAfterCommit, Y as runInStoreTransaction };
+export { F as MockClock, L as MockEmail, z as MockLLM, R as MockWebhooks, be as TESTING_PRESET_VERSION, $ as describeIfAvailable, ge as describeIfReachable, se as fixtureRow, he as invoke, Q as isTcpReachable, pe as makeTestContext, ye as makeWorkflowRunner, B as mockStore, Y as outboxNudgesOf, q as resetAfterCommit, K as rpcInterceptorFor, J as runAfterCommit, X as runInStoreTransaction, _e as testEventBus };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/testing",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Test utilities for Voltro apps — deterministic clock, captured emails, queued LLM responses, scoped subject/tenant runners, and a cross-dialect parity harness.",
   "keywords": [
     "voltro",
@@ -42,14 +42,14 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
-    "@voltro/workflow": "0.24.0"
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
+    "@voltro/workflow": "0.26.0"
   },
   "peerDependencies": {
-    "@voltro/client": "0.24.0",
+    "@voltro/client": "0.26.0",
     "effect": "^3.22.0",
     "react": "^19.0.0",
     "@effect/sql": "^0.52.0"