@voltro/testing 0.85.0 → 0.87.0

package/dist/invoke.js

@@ -0,0 +1,82 @@
+import { queryCacheOf as e, resetAfterCommit as t, restInvocationOf as n, rpcInterceptorFor as r, runAfterCommit as i, runInStoreTransaction as a, serviceLayerFor as o } from "./testContext.js";
+import { Cause as s, Effect as c, Exit as l, Schema as u } from "effect";
+import { SubjectService as d, checkGuardsEffect as f } from "@voltro/protocol";
+import { cachedComputedCall as p, computedCacheKey as m, makeEffectStoreLayer as h, runProvidedEffect as g, runWithDeadlockRetry as _ } from "@voltro/runtime";
+//#region src/invoke.ts
+var v = (e, t) => {
+	let n = o(t);
+	return (n === void 0 ? e : c.provide(e, n)).pipe(c.provide(h(t.store)), c.provideService(d, t.request.subject));
+}, y = async (o, h, y, x) => {
+	let S = o.input, C = await u.decodeUnknownPromise(S)(y), w = o.kind, T = async (e) => {
+		let t = h(C, e);
+		return c.isEffect(t) ? g(v(t, e)) : t;
+	}, E = async () => {
+		let t = e(x), n = o.cache;
+		if (t === void 0 || n === void 0) return b;
+		let r = t.deps.policyFor(n);
+		if (r === void 0) return b;
+		let i = o, a = i.name ?? "", s = i.source === void 0 ? [] : typeof i.source == "string" ? [i.source] : [...i.source], l = await t.rowFilter(), u = m({
+			name: a,
+			codeIdentity: t.deps.codeIdentity,
+			output: i.output,
+			input: i.input,
+			decodedInput: C,
+			scope: r.scope,
+			subject: x.request.subject,
+			rowFilter: l,
+			declaredSources: s
+		});
+		return "bypass" in u ? b : g(p({
+			cache: t.deps,
+			policy: r,
+			key: u.key,
+			name: a,
+			sources: s,
+			output: i.output,
+			subject: x.request.subject,
+			rowFilter: l,
+			ctx: x,
+			execute: async (e, t) => {
+				let n = h(C, e);
+				return c.isEffect(n) ? g(v(n.pipe(c.provideService(d, t)), x)) : n;
+			},
+			onDescriptor: () => {},
+			isDescriptor: () => !1,
+			unwrap: (e) => e
+		}).pipe(c.map(({ value: e }) => e)));
+	}, D = async () => {
+		let e = o.guards;
+		if (e !== void 0 && e.length > 0) {
+			let t = await c.runPromise(f(x.request.subject, e, C));
+			if (t !== null) throw t;
+		}
+		if (w === "query") {
+			let e = await E();
+			if (e !== b) return e;
+		}
+		if (w !== "mutation") return T(x);
+		let n = await _(async () => a(x, async (e) => (t(x), T(e))), { delay: () => Promise.resolve() });
+		return await i(x), n;
+	}, O = w === "mutation" || w === "query" || w === "action" ? w : void 0, k = O === void 0 ? void 0 : r(x, O);
+	if (k === void 0 || O === void 0) return await D();
+	let A = c.tryPromise({
+		try: () => D(),
+		catch: (e) => e
+	}), j = n(x), M = k(A, {
+		tag: o.name ?? "",
+		kind: O,
+		input: C,
+		subject: x.request.subject,
+		traceId: x.request.traceId,
+		...x.request.spanId === void 0 ? {} : { spanId: x.request.spanId },
+		...j === void 0 ? {} : {
+			surface: "rest",
+			publicApi: j.publicApi
+		},
+		...j?.remoteAddr === void 0 ? {} : { remoteAddr: j.remoteAddr }
+	}), N = await c.runPromiseExit(M);
+	if (l.isSuccess(N)) return N.value;
+	throw s.squash(N.cause);
+}, b = Symbol("voltro:testing:not-cached");
+//#endregion
+export { y as invoke };

package/dist/mockClock.js

@@ -0,0 +1,78 @@
+import { Effect as e } from "effect";
+//#region src/mockClock.ts
+var t = Symbol.for("voltro/testing/mockClock.installed"), n = () => globalThis, r = (e, t) => new Proxy(e, {
+	construct: (e, n, r) => Reflect.construct(e, n.length === 0 ? [t()] : n, r),
+	apply: () => new e(t()).toString(),
+	get: (e, n, r) => n === "now" ? () => t() : Reflect.get(e, n, r)
+}), i = (e) => {
+	if (typeof e == "number") return e;
+	let t = e instanceof Date ? e.getTime() : Date.parse(e);
+	if (Number.isNaN(t)) throw Error(`mockClock: cannot read an instant from '${String(e)}'`);
+	return t;
+}, a = class {
+	currentMs;
+	constructor(e = "2026-01-01T00:00:00Z") {
+		this.currentMs = i(e);
+	}
+	now() {
+		return this.currentMs;
+	}
+	date() {
+		return new Date(this.currentMs);
+	}
+	advance(e) {
+		this.currentMs += typeof e == "number" ? e : l(e);
+	}
+	set(e) {
+		this.currentMs = i(e);
+	}
+	get installed() {
+		return n()[t]?.clock === this;
+	}
+	install() {
+		let e = n(), i = e[t];
+		if (i !== void 0) throw Error("mockClock: global time is already faked" + (i.clock === this ? " by this same clock" : " by another MockClock") + ". Uninstall it before installing again — a nested install restores the outer fake on the way out, which leaves the realm frozen with nothing pointing at why. `withFrozenTime` always restores, including on a throw.");
+		let a = globalThis.Date;
+		return e[t] = {
+			realDate: a,
+			clock: this
+		}, globalThis.Date = r(a, () => this.currentMs), () => {
+			this.uninstall();
+		};
+	}
+	uninstall() {
+		let e = n(), r = e[t];
+		r !== void 0 && r.clock === this && (globalThis.Date = r.realDate, delete e[t]);
+	}
+}, o = (e) => typeof e == "object" && !!e && typeof e.then == "function", s = (e, t) => {
+	let n = e instanceof a ? e : new a(e);
+	n.install();
+	let r = !1;
+	try {
+		let e = t(n);
+		return o(e) ? (r = !0, e.then((e) => (n.uninstall(), e), (e) => {
+			throw n.uninstall(), e;
+		})) : e;
+	} finally {
+		r || n.uninstall();
+	}
+}, c = (t) => e.acquireRelease(e.sync(() => {
+	let e = t instanceof a ? t : new a(t);
+	return e.install(), e;
+}), (t) => e.sync(() => {
+	t.uninstall();
+})), l = (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];
+	switch (r) {
+		case "ms": return n;
+		case "s": return n * 1e3;
+		case "m": return n * 6e4;
+		case "h": return n * 36e5;
+		case "d": return n * 864e5;
+		default: throw Error(`mockClock: unknown unit '${r}'`);
+	}
+};
+//#endregion
+export { a as MockClock, c as frozenTime, s as withFrozenTime };

package/dist/mockLLM.js

@@ -0,0 +1,19 @@
+//#region src/mockLLM.ts
+var e = class {
+	queue;
+	calls = [];
+	constructor(e) {
+		this.queue = [...e];
+	}
+	next(e) {
+		this.calls.push(e);
+		let t = this.queue.shift();
+		if (!t) throw Error("MockLLM: no more responses queued");
+		return t;
+	}
+	remaining() {
+		return this.queue.length;
+	}
+};
+//#endregion
+export { e as MockLLM };

package/dist/mockWebhooks.js

@@ -0,0 +1,26 @@
+//#region src/mockWebhooks.ts
+var e = class {
+	emitted = [];
+	async emit(e, t) {
+		let n = typeof e == "string" ? e : e.name ?? e.id ?? e.event ?? "(unnamed event)";
+		return this.emitted.push({
+			event: n,
+			payload: t,
+			emittedAt: /* @__PURE__ */ new Date()
+		}), { delivered: 0 };
+	}
+	async listTargets(e, t) {
+		return [];
+	}
+	payloadsFor(e) {
+		return this.emitted.filter((t) => t.event === e).map((e) => e.payload);
+	}
+	last(e) {
+		for (let t = this.emitted.length - 1; t >= 0; t--) if (this.emitted[t].event === e) return this.emitted[t];
+	}
+	clear() {
+		this.emitted.length = 0;
+	}
+};
+//#endregion
+export { e as MockWebhooks };

package/dist/platform.js

@@ -10,11 +10,7 @@ var r = (r, i) => {
 			t(Number.isFinite(e.clock.now())).toBe(!0);
 		}), n("storage: the local area is a synchronous store that reads back what it wrote", async () => {
 			let e = await o(), n = e.storage("local");
-			if (n === null) {
-				t(e.storage("session")).toBeNull();
-				return;
-			}
-			n.setItem(a, "v1"), t(n.getItem(a)).toBe("v1"), n.removeItem?.(a);
+			n === null ? t(e.storage("session")).toBeNull() : (n.setItem(a, "v1"), t(n.getItem(a)).toBe("v1"), n.removeItem?.(a));
 		}), n("secureStorage: honours its declared kind", async () => {
 			let e = await o();
 			e.capabilities.secureTokenStorage ? (t(e.secureStorage.kind).not.toBe("none"), await e.secureStorage.set(a, "secret"), t(await e.secureStorage.get(a)).toBe("secret"), await e.secureStorage.delete(a), t(await e.secureStorage.get(a)).toBeNull()) : (t(e.secureStorage.kind).toBe("none"), t(await e.secureStorage.get(a)).toBeNull(), await t(e.secureStorage.set(a, "secret")).rejects.toThrow());

package/dist/reachable.js

@@ -0,0 +1,27 @@
+import e from "node:net";
+import { describe as t } from "vitest";
+//#region src/reachable.ts
+var n = (t) => new Promise((n) => {
+	let r = new e.Socket(), i = (e) => {
+		clearTimeout(a), r.destroy(), n(e);
+	}, a = setTimeout(() => i(!1), t.timeoutMs ?? 750);
+	r.once("connect", () => i(!0)), r.once("error", () => i(!1)), r.connect(t.port, t.host);
+}), r = async (e, n, r, i) => {
+	if (typeof n != "string" || typeof r != "function" || typeof i != "function") throw TypeError(`describeIfAvailable('${e}', ...): expected (label, dependency, probe, suite) — got dependency: ${typeof n}, probe: ${typeof r}, suite: ${typeof i}. Three arguments means the suite body is being used as the probe: it would run at file scope, unconditionally, and the skip would silently do nothing.`);
+	let a = !1;
+	try {
+		a = await r();
+	} catch {
+		a = !1;
+	}
+	t.skipIf(!a)(a ? e : `${e} [SKIPPED: needs ${n}]`, i);
+}, i = async (e, t, i) => {
+	await r(e, `${t.name} at ${t.host}:${t.port}`, () => n(t), i);
+}, a = async (e, t) => {
+	try {
+		let n = await t();
+		n !== void 0 && n !== "" && console.log(`[engine] ${e}: ${n}`);
+	} catch {}
+};
+//#endregion
+export { r as describeIfAvailable, i as describeIfReachable, n as isTcpReachable, a as reportEngineVersion };

package/dist/serviceApiMock.js

@@ -0,0 +1,53 @@
+import { Effect as e, Schema as t } from "effect";
+import { ApiUnavailable as n } from "@voltro/protocol";
+//#region src/serviceApiMock.ts
+var r = (r, i, a = {}) => {
+	let o = a.name ?? "mock", s = [], c = /* @__PURE__ */ new Map(), l = (e, t) => `${e}\u0000${JSON.stringify(t)}`, u = async (e, a, c) => {
+		let l = r[e];
+		if (l === void 0) throw Error(`makeServiceApiMock: '${e}' is not a service procedure of this api`);
+		let u = l.input, d = t.encodeUnknownSync(u)(a), f = t.decodeUnknownSync(u)(d);
+		s.push({
+			tag: e,
+			input: f,
+			idempotencyKey: c?.idempotencyKey
+		});
+		let p = i[e];
+		if (p === void 0) throw new n({
+			api: o,
+			tag: e,
+			reason: "transport",
+			message: "no handler in makeServiceApiMock"
+		});
+		let m = await p(f), h = l.output;
+		return t.decodeUnknownSync(h)(t.encodeUnknownSync(h)(m));
+	}, d = (t) => {
+		let n = t.join("."), r = Object.assign((e, t) => u(n, e, t), {
+			effect: (t, r) => e.tryPromise({
+				try: () => u(n, t, r),
+				catch: (e) => e
+			}),
+			subscribe: (e, t) => {
+				let r = l(n, e), i = c.get(r) ?? /* @__PURE__ */ new Set();
+				return c.set(r, i), i.add(t.onValue), u(n, e).then(t.onValue, (e) => t.onError?.(e)), { unsubscribe: () => {
+					i.delete(t.onValue);
+				} };
+			}
+		});
+		return new Proxy(r, { get: (e, n) => {
+			if (typeof n == "string") {
+				if (n === "effect" || n === "subscribe") return e[n];
+				if (n !== "then") return d([...t, n]);
+			}
+		} });
+	};
+	return {
+		api: new Proxy({}, { get: (e, t) => typeof t == "string" && t !== "then" ? d([t]) : void 0 }),
+		calls: (e) => e === void 0 ? [...s] : s.filter((t) => t.tag === e),
+		emit: (e, n, i) => {
+			let a = r[e], o = a === void 0 ? i : t.decodeUnknownSync(a.output)(t.encodeUnknownSync(a.output)(i));
+			for (let t of c.get(l(e, n)) ?? []) t(o);
+		}
+	};
+};
+//#endregion
+export { r as makeServiceApiMock };

package/dist/subject.js

@@ -0,0 +1,11 @@
+import { anonymousSubject as e, systemSubject as t } from "@voltro/protocol";
+//#region src/subject.ts
+var n = "test-tenant", r = (e, t, n) => ({
+	type: e,
+	id: t,
+	tenantId: n.tenantId ?? "test-tenant",
+	scopes: n.scopes ?? [],
+	...n.metadata === void 0 ? {} : { metadata: n.metadata }
+}), i = (e, t = {}) => r("user", e, t), a = (e, t = {}) => r("apiKey", e, t), o = (e, t = {}) => r("serviceAccount", e, t), s = (t = null) => e(t), c = (e = "job:test", n) => n === void 0 ? t(e) : t(e, n);
+//#endregion
+export { n as TEST_TENANT_ID, s as anonymous, a as apiKey, o as serviceAccount, c as system, i as user };

package/dist/subscribeContext.js

@@ -0,0 +1,16 @@
+import { changeDelete as e, changeInsert as t, changeSoftDelete as n, changeUpdate as r } from "@voltro/database";
+import { createLogger as i } from "@voltro/logger";
+//#region src/subscribeContext.ts
+var a = (e = {}) => {
+	let t = e.id ?? "test", n = e.store ?? new Proxy({}, { get: (e, t) => {
+		throw Error(`makeSubscribeContext: this subscriber reached ctx.store.${String(t)} and the test passed no store. Pass \`{ store: makeTestContext().store }\` so the subscriber and the code under test share one — an empty stand-in would let a read of the wrong table pass.`);
+	} });
+	return {
+		id: t,
+		log: e.log ?? i({ scope: `subscribe:${t}` }),
+		store: n,
+		...e.publish === void 0 ? {} : { publish: e.publish }
+	};
+};
+//#endregion
+export { e as changeDelete, t as changeInsert, n as changeSoftDelete, r as changeUpdate, a as makeSubscribeContext };

package/dist/system.d.ts

@@ -0,0 +1,99 @@
+import { AnyEventDescriptor } from '@voltro/protocol';
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { PluginInspectRequest } from '@voltro/protocol';
+import { PluginInspectResponse } from '@voltro/protocol';
+import { PluginPrivacyRequest } from '@voltro/protocol';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { VoltroPlugin } from '@voltro/protocol';
+
+/**
+ * Register the system contract against real exports and descriptor surfaces.
+ * Refuses incomplete inventories before registering any tests. This suite does
+ * not establish SQL parity, ordinary boot, four dashboard layers or capacity.
+ */
+export declare const systemContractConformance: (plugin: VoltroPlugin, options: SystemContractConformanceOptions) => void;
+
+export declare interface SystemContractConformanceOptions {
+    readonly manifest: SystemContractManifest;
+    /** Actual module namespace imports, never copies of the system exports. */
+    readonly strategies: Readonly<Record<string, unknown>>;
+    readonly ports: Readonly<Record<string, unknown>>;
+    readonly testing: Readonly<Record<string, unknown>>;
+    /** Actual descriptors used by discovery/codegen. Hidden events are not inferred. */
+    readonly eventCatalog: ReadonlyArray<AnyEventDescriptor>;
+    readonly eventFixtures: Readonly<Record<string, SystemEventFixture>>;
+    readonly stages: Readonly<Record<'take' | 'configure' | 'hook' | 'override' | 'extendOrReplace', SystemContractProbe>>;
+    readonly privacy: Readonly<Record<string, (kind: PluginPrivacyTarget['kind']) => Effect.Effect<SystemPrivacyFixture, unknown>>>;
+    /** Exactly one case per contributed endpoint, keyed as "GET path". */
+    readonly inspect: Readonly<Record<string, SystemInspectFixture>>;
+}
+
+/** Export this inventory beside the system's public strategies and ports. */
+export declare interface SystemContractManifest {
+    readonly slots: Readonly<Record<string, {
+        readonly defaultExport: string;
+        readonly fixtureExport: string;
+    }>>;
+    readonly ports: Readonly<Record<string, {
+        readonly tagExport: string;
+        readonly fakeLayerExport: string;
+        readonly fixtureExport: string;
+    }>>;
+    readonly events: ReadonlyArray<string>;
+}
+
+/** A measured observation. Use inputs that distinguish defaults from overrides. */
+export declare interface SystemContractProbe {
+    readonly run: () => Effect.Effect<unknown, unknown>;
+    readonly expected: unknown;
+}
+
+export declare interface SystemEventFixture {
+    readonly descriptor: AnyEventDescriptor;
+    readonly key: unknown;
+    readonly payload: unknown;
+}
+
+export declare interface SystemInspectFixture {
+    readonly request: PluginInspectRequest;
+    readonly expected: PluginInspectResponse;
+}
+
+export declare interface SystemPortFixture {
+    readonly kind: 'port';
+    readonly tag: unknown;
+    readonly fakeLayer: unknown;
+    readonly probe: SystemContractProbe;
+}
+
+/** Preserve concrete Tag/Layer types; the suite owns scope acquisition and cleanup. */
+export declare const systemPortFixture: <Identifier, Service>(options: {
+    readonly tag: Context.Service<Identifier, Service>;
+    readonly fakeLayer: Layer.Layer<Identifier>;
+    readonly read: Effect.Effect<unknown, unknown, Identifier>;
+    readonly expected: unknown;
+}) => SystemPortFixture;
+
+/** A fresh, seeded fixture; read() must include peer/tenant rows that must survive. */
+export declare interface SystemPrivacyFixture {
+    /** Explicitly reviewed tenant-wide table without subject facts; erase retains every row. */
+    readonly subjectData?: 'none';
+    readonly request: PluginPrivacyRequest;
+    readonly read: () => Effect.Effect<ReadonlyArray<unknown>, unknown>;
+    readonly before: ReadonlyArray<unknown>;
+    readonly after: ReadonlyArray<unknown>;
+    readonly exported: unknown;
+    readonly close: Effect.Effect<void>;
+}
+
+/** A ./testing export that exercises the imported default and configured override. */
+export declare interface SystemSlotFixture {
+    readonly kind: 'slot';
+    readonly defaultImplementation: unknown;
+    readonly defaultProbe: SystemContractProbe;
+    readonly overrideProbe: SystemContractProbe;
+}
+
+export { }

package/dist/system.js

@@ -0,0 +1,94 @@
+import { testEventBus as e } from "./testEventBus.js";
+import { Context as t, Effect as n, Layer as r } from "effect";
+import { createPluginPrivacyRegistry as i } from "@voltro/protocol";
+import { describe as a, expect as o, it as s } from "vitest";
+//#region src/systemContractConformance.ts
+var c = (e) => ({
+	kind: "port",
+	tag: e.tag,
+	fakeLayer: e.fakeLayer,
+	probe: {
+		run: () => n.scoped(e.read.pipe(n.provide(e.fakeLayer))),
+		expected: e.expected
+	}
+}), l = (e, t) => {
+	if (e.some((e) => !e.trim()) || new Set(e).size !== e.length) throw Error(`Invalid system ${t} inventory`);
+}, u = (e, t, n) => {
+	if (l(e, n), l(t, n), JSON.stringify([...e].sort()) !== JSON.stringify([...t].sort())) throw Error(`Incomplete system ${n} fixtures`);
+}, d = (e) => typeof e == "object" && !!e, f = (e) => d(e) && typeof e.run == "function" && e.expected !== void 0, p = (e) => d(e) && e.kind === "slot" && typeof e.defaultImplementation == "function" && f(e.defaultProbe) && f(e.overrideProbe), m = (e) => d(e) && e.kind === "port" && t.isKey(e.tag) && r.isLayer(e.fakeLayer) && f(e.probe), h = (e, t) => `${e} ${t.replace(/^\//, "")}`, g = (t, r) => {
+	let { manifest: c } = r, g = t.services !== void 0 || (t.routes?.length ?? 0) > 0 || (t.extendSchema?.tables?.length ?? 0) > 0 || (t.inspectEndpoints?.length ?? 0) > 0 || t.onActivate !== void 0 || t.interceptMutation !== void 0;
+	if (!t.name.trim() || !g || Object.keys(c.slots).length === 0) throw Error("System conformance requires an implemented system with strategy slots");
+	let _ = (t.extendSchema?.tables ?? []).map((e) => {
+		if (!d(e) || typeof e.tableName != "string") throw Error("System conformance requires named table descriptors");
+		return e.tableName;
+	});
+	u(Object.keys(r.stages), [
+		"take",
+		"configure",
+		"hook",
+		"override",
+		"extendOrReplace"
+	], "stages");
+	for (let e of Object.values(r.stages)) if (!f(e)) throw Error("System stages require measured probes");
+	u(Object.keys(r.privacy), _, "privacy"), u(r.eventCatalog.map((e) => e.name), c.events, "events"), u(Object.keys(r.eventFixtures), c.events, "events");
+	let v = t.inspectEndpoints ?? [];
+	u(Object.keys(r.inspect), v.map((e) => h(e.method, e.path)), "inspect");
+	let y = Object.entries(c.slots).map(([e, t]) => {
+		l([e], "slots");
+		let n = r.strategies[t.defaultExport], i = r.testing[t.fixtureExport];
+		if (typeof n != "function" || !p(i) || i.defaultImplementation !== n) throw Error(`System slot requires its actual default export and fixture: ${e}`);
+		return {
+			name: e,
+			fixture: i
+		};
+	}), b = Object.entries(c.ports).map(([e, t]) => {
+		l([e], "ports");
+		let n = r.testing[t.fixtureExport];
+		if (!m(n) || n.tag !== r.ports[t.tagExport] || n.fakeLayer !== r.testing[t.fakeLayerExport]) throw Error(`System port requires its actual Tag, fake Layer and fixture: ${e}`);
+		return {
+			name: e,
+			fixture: n
+		};
+	});
+	for (let e of r.eventCatalog) if (e.kind !== "event" || r.eventFixtures[e.name]?.descriptor !== e) throw Error(`System event requires its actual catalog descriptor: ${e.name}`);
+	for (let e of v) {
+		let t = r.inspect[h(e.method, e.path)];
+		if (t.request.method !== e.method || t.expected.kind !== "json" || (t.expected.status ?? 200) !== 200 || t.expected.data === void 0) throw Error("System inspect fixture must observe successful JSON");
+	}
+	let x = i([t]);
+	if (_.length > 0 && (!t.subjectPrivacy || x.coverage("user").missing.length > 0 || x.coverage("guest").missing.length > 0 || !t.subjectPrivacy.kinds.includes("user") || !t.subjectPrivacy.kinds.includes("guest"))) throw Error("System tables require user and guest erase/export coverage");
+	let S = async (e) => {
+		o(await n.runPromise(n.suspend(e.run))).toEqual(e.expected);
+	};
+	a(`system contract — ${t.name}`, () => {
+		for (let [e, t] of Object.entries(r.stages)) s(`stage ${e}`, () => S(t));
+		for (let { name: e, fixture: t } of y) s(`slot ${e}: exported default and configured override`, async () => {
+			o(t.overrideProbe.expected).not.toEqual(t.defaultProbe.expected), await S(t.defaultProbe), await S(t.overrideProbe);
+		});
+		for (let { name: e, fixture: t } of b) s(`port ${e}: scoped fake Layer`, () => S(t.probe));
+		for (let t of r.eventCatalog) s(`event ${t.name}: real validation and delivery`, async () => {
+			let n = r.eventFixtures[t.name], i = e(), a = i.subscribe(t, n.key);
+			try {
+				await i.publish(t, n.key, n.payload), o(a.received).toEqual([n.payload]), o(a.missedCount).toBe(0);
+			} finally {
+				a.stop(), i.reset();
+			}
+		});
+		for (let e of _) for (let i of ["user", "guest"]) s(`table ${e}: ${i} export, erase, peers and idempotent retry`, () => n.runPromise(n.acquireUseRelease(r.privacy[e](i), (e) => n.gen(function* () {
+			o(e.request.target.kind).toBe(i), o(e.before.length).toBeGreaterThan(0), e.subjectData === "none" ? o(e.before).toEqual(e.after) : o(e.before).not.toEqual(e.after), o(yield* e.read()).toEqual(e.before);
+			let n = yield* x.exportSubject(e.request);
+			o(n.plugins).toEqual([{
+				name: t.name,
+				data: e.exported
+			}]);
+			let r = yield* x.eraseSubject(e.request);
+			o(r.completed).toEqual([t.name]), o(yield* e.read()).toEqual(e.after), yield* x.eraseSubject(e.request), o(yield* e.read()).toEqual(e.after);
+		}), (e) => e.close)));
+		for (let e of v) s(`inspect ${h(e.method, e.path)}: actual handler`, async () => {
+			let t = r.inspect[h(e.method, e.path)];
+			o(await n.runPromise(n.suspend(() => e.handler(t.request)))).toEqual(t.expected);
+		});
+	});
+};
+//#endregion
+export { g as systemContractConformance, c as systemPortFixture };

package/dist/testApps.js

@@ -0,0 +1,111 @@
+import { apiBindingTokenEnv as e, apiBindingUrlEnv as t, mintServiceToken as n, serviceCallerTokenEnv as r } from "@voltro/runtime";
+import i from "node:net";
+import { randomBytes as a } from "node:crypto";
+import { spawn as o } from "node:child_process";
+import { createRequire as s } from "node:module";
+import { dirname as c, join as l } from "node:path";
+//#region src/testApps.ts
+var u = () => new Promise((e, t) => {
+	let n = i.createServer();
+	n.once("error", t), n.listen(0, "127.0.0.1", () => {
+		let t = n.address(), r = typeof t == "object" && t ? t.port : 0;
+		n.close(() => e(r));
+	});
+}), d = async (e) => {
+	try {
+		return (await fetch(`http://127.0.0.1:${e}/internal/readiness`)).status === 200;
+	} catch {
+		return !1;
+	}
+}, f = (e) => l(c(s(l(e, "package.json")).resolve("@voltro/cli/package.json")), "bin", "voltro.mjs"), p = 1e4, m = (e) => new Promise((t) => {
+	if (e.exitCode !== null || e.signalCode !== null) return t();
+	let n = setTimeout(() => {
+		e.kill("SIGKILL");
+	}, p);
+	e.once("exit", () => {
+		clearTimeout(n), t();
+	}), e.kill("SIGTERM");
+}), h = async (i) => {
+	let s = Object.keys(i.apps);
+	if (s.length === 0) throw Error("startTestApps: no apps given");
+	let c = i.mode ?? "dev", l = i.bootTimeoutMs ?? 3e5, p = i.cli ?? f(i.apps[s[0]].root), h = /* @__PURE__ */ new Map();
+	for (let e of s) h.set(e, await u());
+	let g = /* @__PURE__ */ new Map(), _ = new Map(s.map((e) => [e, {}]));
+	for (let a of i.edges ?? []) {
+		for (let e of [a.caller, a.callee]) if (!s.includes(e)) throw Error(`startTestApps: edge names '${e}', which is not among the apps (${s.join(", ")})`);
+		let i = n();
+		g.set(`${a.caller}\u0000${a.callee}`, i), Object.assign(_.get(a.caller), {
+			[e(a.binding)]: i,
+			[t(a.binding)]: `ws://127.0.0.1:${h.get(a.callee)}/ws`
+		}), Object.assign(_.get(a.callee), { [r(a.caller)]: i });
+	}
+	let v = [], y = /* @__PURE__ */ new Set(), b = (e) => {
+		if (!v.includes(e)) {
+			if (y.has(e)) throw Error(`startTestApps: the edges form a cycle through '${e}' — no app can boot first`);
+			y.add(e);
+			for (let t of i.edges ?? []) t.caller === e && b(t.callee);
+			y.delete(e), v.push(e);
+		}
+	};
+	for (let e of s) b(e);
+	let x = [], S = /* @__PURE__ */ new Map(), C = async () => {
+		await Promise.all(x.map(m));
+	};
+	for (let e of v) {
+		let t = i.apps[e], n = h.get(e), r = "", s = o(process.execPath, [
+			p,
+			c,
+			...c === "serve" ? ["."] : []
+		], {
+			cwd: t.root,
+			env: {
+				...process.env,
+				...c === "serve" ? { VOLTRO_SESSION_SECRET: a(32).toString("base64url") } : {},
+				...t.env,
+				..._.get(e),
+				PORT: String(n)
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		x.push(s), s.stdout?.on("data", (e) => {
+			r += e.toString();
+		}), s.stderr?.on("data", (e) => {
+			r += e.toString();
+		}), s.on("exit", (e, t) => {
+			r += `\n[exited] code=${String(e)} signal=${String(t)}`;
+		});
+		let u = {
+			name: e,
+			port: n,
+			url: `http://127.0.0.1:${n}`,
+			wsUrl: `ws://127.0.0.1:${n}/ws`,
+			log: () => r,
+			stop: () => m(s)
+		};
+		S.set(e, u);
+		let f = Date.now() + l;
+		for (; !await d(n);) {
+			if (s.exitCode !== null || s.signalCode !== null || Date.now() > f) {
+				await C();
+				let t = s.exitCode !== null || s.signalCode !== null ? "exited before it was ready" : `was not ready within ${l} ms`;
+				throw Error(`startTestApps: '${e}' ${t}\n${u.log().slice(-4e3)}`);
+			}
+			await new Promise((e) => setTimeout(e, 250));
+		}
+	}
+	return {
+		apps: Object.fromEntries(S),
+		token: (e, t) => {
+			let n = g.get(`${e}\u0000${t}`);
+			if (n === void 0) throw Error(`startTestApps: no edge ${e} → ${t}`);
+			return n;
+		},
+		stop: C
+	};
+};
+//#endregion
+export { h as startTestApps };