@voltro/testing 0.85.0 → 0.87.0

package/dist/factory.js

@@ -0,0 +1,65 @@
+import { fixtureRow as e, nextSequence as t } from "./fixtureRow.js";
+import { missingRequiredColumns as n } from "@voltro/database";
+//#region src/factory.ts
+var r = (e) => {
+	let n = {};
+	for (let [r, i] of Object.entries(e)) n[r] = typeof i == "function" ? i(t()) : i;
+	return n;
+}, i = (e) => {
+	for (let [t, n] of Object.entries(e.fields)) if (n.type === "id") return t;
+	return "id";
+}, a = async (e, t, r, a, s) => {
+	let c = {};
+	for (let l of n(t, r)) {
+		let n = t.fields[l];
+		if (n === void 0 || n.type !== "reference" || n.references === void 0) continue;
+		let r = n.references();
+		if (s.includes(r.tableName)) throw Error(`defineFactory: creating '${t.tableName}' requires '${r.tableName}' via '${l}', and that reference is cyclic (${[...s, r.tableName].join(" → ")}). Insert one side first and pass the id: create(store, { ${l}: existing.id }).`);
+		let u = a[l];
+		c[l] = (u === void 0 ? await o(e, r, {}, {}, [...s, r.tableName]) : await u.create(e, {}))[n.referenceColumn ?? i(r)];
+	}
+	return c;
+}, o = async (t, n, r, i, o) => {
+	let s = {
+		...await a(t, n, r, i, o),
+		...r
+	};
+	return t.insert(n.tableName, e(n, s));
+}, s = (e, t) => typeof e == "function" ? e(t) : e ?? {}, c = (t, n = {}) => {
+	let i = n.traits ?? {}, a = n.associations ?? {}, c = (n) => {
+		let l = (e = {}) => ({
+			...r(n),
+			...e
+		}), u = (n = {}) => e(t, l(n));
+		return {
+			table: t,
+			build: u,
+			buildList: (e, t) => Array.from({ length: e }, (e, n) => u(s(t, n))),
+			create: (e, n = {}) => o(e, t, l(n), a, [t.tableName]),
+			createList: async (e, n, r) => {
+				let i = [];
+				for (let c = 0; c < n; c++) i.push(await o(e, t, l(s(r, c)), a, [t.tableName]));
+				return i;
+			},
+			with: (...e) => {
+				let r = n;
+				for (let n of e) {
+					let e = i[n];
+					if (e === void 0) throw Error(`defineFactory: '${t.tableName}' has no trait '${n}'. Declared: ${Object.keys(i).join(", ") || "(none)"}.`);
+					r = {
+						...r,
+						...e
+					};
+				}
+				return c(r);
+			},
+			extend: (e) => c({
+				...n,
+				...e
+			})
+		};
+	};
+	return c(n.defaults ?? {});
+};
+//#endregion
+export { c as defineFactory };

package/dist/fieldKeys.js

@@ -0,0 +1,73 @@
+import { declaredEncryptedColumns as e, declaredRenames as t, getFieldCipher as n, isFieldKeyring as r, makeFieldKeyring as i, openCell as a, setFieldCipher as o } from "@voltro/runtime";
+//#region src/fieldKeys.ts
+var s = /* @__PURE__ */ new WeakMap(), c = (e) => {
+	let t = i(e);
+	return s.set(t, e), o(t), t;
+}, l = (e, t = e.active) => {
+	let n = e.keys.find((e) => e.id === t);
+	if (n === void 0) throw Error(`the keyring does not hold its active key "${t}"`);
+	return i({
+		active: n.id,
+		keys: [n]
+	});
+}, u = (e = (() => {
+	let e = n();
+	return r(e) ? e : void 0;
+})(), t) => {
+	if (t !== void 0) return l(t);
+	if (e === void 0) throw Error("no field keyring is registered — pass `fieldKeys` to makeTestContext, or call registerTestFieldKeys");
+	let i = s.get(e);
+	if (i === void 0) throw Error("the registered field keyring was not built by the test helpers, so its keys are unknown here — register it with `fieldKeys` / registerTestFieldKeys");
+	return l(i, e.activeKeyId);
+}, d = /* @__PURE__ */ new WeakMap(), f = (e, t) => {
+	d.set(e, t);
+}, p = (e) => typeof e == "string" ? e : e?.tableName, m = async (n, r) => {
+	let i = d.get(n) ?? n;
+	if (typeof i.query != "function") throw Error("pass a test context (makeTestContext) or a DataStore");
+	let o = [...r.tables], s = e(o), c = t(o), l = u(r.keyring), f = 0, m = [];
+	for (let e of o) {
+		let t = p(e);
+		if (t === void 0) continue;
+		let n = await i.query({
+			table: t,
+			predicate: void 0,
+			order: [],
+			take: void 0,
+			skip: void 0,
+			projection: void 0
+		});
+		for (let e of n) {
+			let { id: n, ...r } = e;
+			for (let [i, o] of Object.entries(e)) {
+				if (o == null) continue;
+				let e = typeof o == "string" ? o : JSON.stringify(o);
+				if (!e.includes("enc:v")) continue;
+				let u = a(e, l, {
+					table: t,
+					column: i,
+					rowId: n,
+					row: r,
+					declared: s,
+					renames: c
+				});
+				f += u.opened, u.unopened > 0 && m.push({
+					table: t,
+					column: i,
+					rowId: n,
+					count: u.unopened
+				});
+			}
+		}
+	}
+	return {
+		activeKeyId: l.activeKeyId,
+		opened: f,
+		unopened: m
+	};
+}, h = (e) => `${e.unopened.reduce((e, t) => e + t.count, 0)} sealed value(s) do not open with the active key ${e.activeKeyId} alone:\n` + e.unopened.slice(0, 20).map((e) => `  ${e.table}.${e.column}${e.rowId === void 0 ? "" : ` (row ${String(e.rowId)})`}: ${e.count}`).join("\n") + (e.unopened.length > 20 ? `\n  … and ${e.unopened.length - 20} more place(s)` : ""), g = async (e, t) => {
+	let n = await m(e, t);
+	if (n.unopened.length > 0) throw Error(h(n));
+	return n;
+};
+//#endregion
+export { u as activeKeyAlone, h as describeActiveKeyAloneFailures, g as expectSealedWithActiveKeyAlone, f as recordTestRawStore, c as registerTestFieldKeys, m as sealedValuesWithActiveKeyAlone };

package/dist/fieldKeysSql.js

@@ -0,0 +1,14 @@
+import { activeKeyAlone as e } from "./fieldKeys.js";
+import { Effect as t } from "effect";
+import { verifySealedValues as n } from "@voltro/runtime";
+//#region src/fieldKeysSql.ts
+var r = async (r) => {
+	let i = e(r.keyring, r.fieldKeys), a = await t.runPromise(t.scoped(n(r.dialect, i, r.tables ?? [])).pipe(t.provide(r.layer))), o = {
+		activeKeyId: i.activeKeyId,
+		...a
+	};
+	if (o.unopened.length > 0 || o.unreadable.length > 0) throw Error(`${o.unopened.reduce((e, t) => e + t.count, 0)} sealed value(s) do not open with the active key ${o.activeKeyId} alone` + (o.unopened.length === 0 ? "" : `:\n${o.unopened.map((e) => `  ${e.table}.${e.column}: ${e.count}`).join("\n")}`) + (o.unreadable.length === 0 ? "" : `\n${o.unreadable.length} column(s) could not be read:\n${o.unreadable.map((e) => `  ${e.table}.${e.column}: ${e.reason}`).join("\n")}`));
+	return o;
+};
+//#endregion
+export { r as expectSealedWithActiveKeyAloneInSql };

package/dist/fixtureRow.js

@@ -0,0 +1,30 @@
+import { AUTO_FILLED_COLUMNS as e, missingRequiredColumns as t } from "@voltro/database";
+//#region src/fixtureRow.ts
+var n = new Set(e), r = 0, i = () => ++r, a = (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;
+	switch (t.type) {
+		case "text":
+		case "id":
+		case "enum": return n ? `${e}-${++r}` : e;
+		case "reference": return t.referenceStorage === "numeric" ? n ? ++r : 0 : n ? `${e}-${++r}` : e;
+		case "integer":
+		case "real": return n ? ++r : 0;
+		case "decimal":
+		case "bigint": return n ? String(++r) : "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}: … }).`);
+	}
+}, o = (e, r = {}) => {
+	let i = {};
+	for (let o of t(e, r)) n.has(o) || (i[o] = a(o, e.fields[o]));
+	return {
+		...i,
+		...r
+	};
+};
+//#endregion
+export { o as fixtureRow, i as nextSequence };

package/dist/formBindingHarness.js

@@ -0,0 +1,46 @@
+import { makeVoltroTestClient as e } from "./client.js";
+import { act as t, createElement as n } from "react";
+import { useFormBinding as r } from "@voltro/client";
+//#region src/formBindingHarness.tsx
+var i = async (i, a = {}) => {
+	if (globalThis.document === void 0) throw Error("renderFormBinding needs a DOM to render hooks — add `// @vitest-environment jsdom` to the spec.");
+	let { createRoot: o } = await import("react-dom/client"), s = a.apiName ?? "app", c = e({
+		apiName: s,
+		...a.client ?? {},
+		mutations: {
+			[i]: a.mutation ?? (() => ({ ok: !0 })),
+			...a.client?.mutations ?? {}
+		}
+	}), l, u = () => (l = r(s, i, a.binding ?? {}), null), d = o(globalThis.document.createElement("div"));
+	return await t(async () => {
+		d.render(n(c.Provider, null, n(u)));
+	}), {
+		binding: () => l,
+		fill: (e, n) => {
+			t(() => {
+				l.field(e).setValue(n);
+			});
+		},
+		blur: (e) => {
+			t(() => {
+				l.field(e).onBlur();
+			});
+		},
+		submit: async () => {
+			let e;
+			return await t(async () => {
+				e = await l.submit();
+			}), e;
+		},
+		errors: () => l.errors,
+		state: () => l.state,
+		client: c,
+		unmount: () => {
+			t(() => {
+				d.unmount();
+			});
+		}
+	};
+};
+//#endregion
+export { i as renderFormBinding };

package/dist/hotStoreSqlParity.js

@@ -0,0 +1,132 @@
+import { eq as e, queryFor as t, registerTable as n } from "@voltro/database";
+import { Effect as r, Layer as i, Option as a, Result as o, Stream as s } from "effect";
+import { describe as c, expect as l, it as u } from "vitest";
+import { randomUUID as d } from "node:crypto";
+import { HotStore as f } from "@voltro/kv/hot/contract";
+import { hotStoreConformance as p } from "@voltro/kv/hot/testing";
+import { dataStoreHotStore as m, hotDataStoreTables as h, hotKvTable as g, hotZTable as _ } from "@voltro/runtime/hot";
+//#region src/hotStoreSqlParity.ts
+var v = (v) => {
+	h.forEach(n), p(v.name, () => {
+		let e = 0;
+		return {
+			layer: i.effect(f, r.acquireRelease(r.promise(v.make), (e) => r.promise(e.dispose)).pipe(r.map((t) => m(t.store, {
+				dialect: v.dialect,
+				namespace: d(),
+				now: () => e
+			})))),
+			advance: (t) => r.sync(() => {
+				e += t;
+			}),
+			capabilities: {
+				atomicMulti: !0,
+				crossNode: !0,
+				persistent: !0
+			}
+		};
+	});
+	let y = (e, t) => u(e, async () => {
+		let e = await v.make();
+		try {
+			await t(e);
+		} finally {
+			await e.dispose();
+		}
+	}, 6e4);
+	c(`HotStore SQL parity — ${v.name}`, () => {
+		y("idempotent table DDL preserves exact normalized scores and physical deletion", async (e) => {
+			let n = m(e.store, {
+				dialect: v.dialect,
+				namespace: "sql"
+			}), i = 1.2345678901234567;
+			await r.runPromise(n.zadd("player:subject", [{
+				member: "member",
+				score: i
+			}])), await e.migrate(), l(await e.store.query(t(_).descriptor)).toEqual([l.objectContaining({
+				member: "member",
+				score: i
+			})]), await r.runPromise(n.delete("player:subject")), l(await e.store.query(t(_).descriptor)).toEqual([]), l(await e.store.query(t(g).descriptor)).toEqual([l.objectContaining({
+				keyHash: "lock",
+				namespace: null,
+				key: null,
+				payload: null,
+				expiresAtMs: null
+			})]);
+		}), y("wrong-type batches roll back every preceding SQL write", async (n) => {
+			let i = m(n.store, {
+				dialect: v.dialect,
+				namespace: "atomic"
+			});
+			await r.runPromise(i.zadd("board", [{
+				member: "m",
+				score: 1
+			}]));
+			let s = await r.runPromise(i.multi([{
+				op: "incrBy",
+				key: "other",
+				delta: 1
+			}, {
+				op: "incrBy",
+				key: "board",
+				delta: 1
+			}]).pipe(r.result));
+			l(o.isFailure(s)).toBe(!0), l(await n.store.query(t(g).where(e("key", "other")).descriptor)).toEqual([]), l(a.getOrNull(await r.runPromise(i.zscore("board", "m")))).toBe(1);
+		}), y("namespace/key boundaries, case, wildcard prefixes and long Unicode values remain exact", async (e) => {
+			let t = m(e.store, {
+				dialect: v.dialect,
+				namespace: "n"
+			}), n = m(e.store, {
+				dialect: v.dialect,
+				namespace: "n:tenant"
+			}), i = m(e.store, {
+				dialect: v.dialect,
+				namespace: "N"
+			});
+			await r.runPromise(t.incrBy("tenant:key", 4)), await r.runPromise(n.incrBy("key", 2)), await r.runPromise(i.incrBy("tenant:key", 9)), await r.runPromise(t.incrBy("%_:key", 1)), await r.runPromise(t.incrBy("wildcard-key", 1));
+			let o = "🎮".repeat(2e3);
+			await r.runPromise(t.zadd(o, [{
+				member: o,
+				score: -1.5
+			}])), l(await r.runPromise(t.incrBy("tenant:key", 0))).toBe(4), l(await r.runPromise(n.incrBy("key", 0))).toBe(2), l(await r.runPromise(i.incrBy("tenant:key", 0))).toBe(9), l(await r.runPromise(s.runCollect(t.scanPrefix("%_:")))).toEqual(["%_:key"]), l(await r.runPromise(s.runCollect(i.scanPrefix("")))).toEqual(["tenant:key"]), l(a.getOrNull(await r.runPromise(t.zscore(o, o)))).toBe(-1.5);
+		}), y("independent connections retain every cold-key increment and have one lease winner", async (e) => {
+			let t = [e.store];
+			for (let n = 0; n < 3; n++) t.push(await e.connect());
+			let n = t.map((e) => m(e, {
+				dialect: v.dialect,
+				namespace: "connections"
+			})), i = await Promise.all(Array.from({ length: 32 }, (e, t) => r.runPromise(n[t % n.length].incrBy("counter", 1))));
+			l(new Set(i).size).toBe(32), l(await r.runPromise(n[0].incrBy("counter", 0))).toBe(32);
+			let a = await Promise.all(Array.from({ length: 32 }, (e, t) => r.runPromise(n[t % n.length].setNx("seat", String(t), 6e4))));
+			l(a.filter(Boolean)).toHaveLength(1);
+		}), y("concurrent first-use ports admit coordination before application writes", async (e) => {
+			let t = [e.store];
+			for (let n = 0; n < 3; n++) t.push(await e.connect());
+			let n = Array.from({ length: 32 }, (e, n) => m(t[n % t.length], {
+				dialect: v.dialect,
+				namespace: "first-use"
+			})), i = (await Promise.allSettled(n.map((e) => r.runPromise(e.incrBy("counter", 1))))).map((e) => {
+				if (e.status === "rejected") throw e.reason;
+				return e.value;
+			});
+			l(new Set(i).size).toBe(32), l(await r.runPromise(n[0].incrBy("counter", 0))).toBe(32);
+		}), y("new connections rebuild the port from persisted SQL and apply stored expiry", async (e) => {
+			let t = 0, n = m(e.store, {
+				dialect: v.dialect,
+				namespace: "reconnect",
+				now: () => t
+			});
+			await r.runPromise(n.incrBy("counter", 7)), await r.runPromise(n.zadd("board", [{
+				member: "𐀀",
+				score: 1.2345678901234567
+			}])), await r.runPromise(n.setNx("seat", "holder", 100));
+			let i = m(await e.connect(), {
+				dialect: v.dialect,
+				namespace: "reconnect",
+				now: () => t
+			});
+			l(await r.runPromise(i.incrBy("counter", 0))).toBe(7), l(a.getOrNull(await r.runPromise(i.zscore("board", "𐀀")))).toBe(1.2345678901234567), l(await r.runPromise(i.setNx("seat", "replacement", 100))).toBe(!1), t = 100, l(await r.runPromise(i.setNx("seat", "replacement", 100))).toBe(!0);
+		});
+	});
+};
+//#endregion
+export { v as runHotStoreSqlParity };

package/dist/hydrateFixtureRows.js

@@ -0,0 +1,22 @@
+import { Result as e, Schema as t } from "effect";
+//#region src/hydrateFixtureRows.ts
+var n = t.decodeUnknownResult(t.DateFromString), r = /^\d{4}-\d{2}-\d{2}$/, i = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/, a = (t, a) => {
+	if (typeof t != "string" || !i.test(t) && !(a === "date" && r.test(t))) return !1;
+	let o = t.slice(0, 10), s = n(o);
+	return e.isSuccess(s) && Number.isFinite(s.success.getTime()) && s.success.toISOString().slice(0, 10) === o;
+}, o = (t, r) => {
+	let i = Object.entries(t.fields).filter(([, e]) => e.type === "timestamp" || e.type === "date");
+	return r.map((r, o) => {
+		let s = { ...r };
+		for (let [c, l] of i) {
+			let i = r[c];
+			if (i == null || i instanceof Date && Number.isFinite(i.getTime())) continue;
+			let u = n(i);
+			if (!a(i, l.type) || e.isFailure(u) || !Number.isFinite(u.success.getTime())) throw TypeError(`hydrateFixtureRows: table '${t.tableName}', row ${o}, column '${c}' requires a valid Date or ISO date-time with Z or an offset${l.type === "date" ? " (YYYY-MM-DD is also accepted as UTC midnight)" : ""}.`);
+			s[c] = u.success;
+		}
+		return s;
+	});
+};
+//#endregion
+export { o as hydrateFixtureRows };

package/dist/index.d.ts

@@ -6,22 +6,33 @@ import { ChangeEvent } from '@voltro/database';
 import { changeInsert } from '@voltro/database';
 import { changeSoftDelete } from '@voltro/database';
 import { changeUpdate } from '@voltro/database';
+import { ComputedQueryCacheDeps } from '@voltro/runtime';
+import { ConnectionRef } from '@voltro/kv/connection';
+import { ConnectionRegistry } from '@voltro/kv/connection';
+import { ConnectionRegistryOptions } from '@voltro/kv/connection';
+import { ConnectionsConfig } from '@voltro/kv/connection';
+import { DialectId } from '@voltro/database';
 import { Effect } from 'effect';
 import { EventBus } from '@voltro/runtime';
 import { EventDescriptor } from '@voltro/protocol';
 import { EventPublisher } from '@voltro/runtime';
+import { FieldKeyring } from '@voltro/runtime';
+import { FieldKeyringConfig } from '@voltro/runtime';
 import { InspectedStep } from '@voltro/workflow';
 import { InspectedWorkflow } from '@voltro/workflow';
 import { Layer } from 'effect';
+import { MemoryRedisConnection } from '@voltro/kv/connection';
 import { ProcedureDescriptor } from '@voltro/protocol';
 import { PublicApiDescriptor } from '@voltro/protocol/rest';
 import { PublicApiProfileConfig } from '@voltro/protocol';
 import { PublicApiSpec } from '@voltro/protocol';
+import { RedisConnections } from '@voltro/kv';
 import { RelationsSpec } from '@voltro/database';
 import { RestRouteDescriptor } from '@voltro/protocol/rest';
 import { RestServeBindings } from '@voltro/protocol/rest';
 import { Row } from '@voltro/database';
 import { RowFilter } from '@voltro/runtime';
+import { RowFilterScope } from '@voltro/runtime';
 import { RpcConnection } from '@voltro/runtime';
 import { RpcInterceptor } from '@voltro/protocol';
 import { RpcKind } from '@voltro/protocol';
@@ -29,12 +40,46 @@ import { Schema } from 'effect';
 import { SchemaError } from 'effect/Schema';
 import { Scope } from 'effect';
 import { ServiceApi } from '@voltro/protocol';
+import { SqlClient } from 'effect/sql';
 import { Subject } from '@voltro/protocol';
 import { SubscribeContext } from '@voltro/runtime';
 import { SyncLogger } from '@voltro/logger';
 import { TableLike } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
+/**
+ * The keyring reduced to its active key — `fieldKeys` when given (a
+ * configuration, e.g. the one a rotation printed), else the registered one.
+ */
+export declare const activeKeyAlone: (keyring?: FieldKeyring | undefined, fieldKeys?: FieldKeyringConfig) => FieldKeyring;
+
+/** Values the active key alone does not open, per place. */
+export declare interface ActiveKeyAloneReport {
+    readonly activeKeyId: string;
+    readonly opened: number;
+    readonly unopened: ReadonlyArray<{
+        readonly table: string;
+        readonly column: string;
+        readonly rowId: unknown;
+        readonly count: number;
+    }>;
+}
+
+export declare interface ActiveKeyAloneSqlReport {
+    readonly activeKeyId: string;
+    readonly opened: number;
+    readonly unopened: ReadonlyArray<{
+        readonly table: string;
+        readonly column: string;
+        readonly count: number;
+    }>;
+    readonly unreadable: ReadonlyArray<{
+        readonly table: string;
+        readonly column: string;
+        readonly reason: string;
+    }>;
+}
+
 /** An unauthenticated caller, optionally carrying a tenant (what the
  *  `x-tenant` header resolves to when no auth strategy matches). Delegates to
  *  the protocol's own constructor so the harness cannot drift from it. */
@@ -142,6 +187,28 @@ export declare interface EmittedWebhook {
  *  ergonomic without an `any` in the public type. */
 declare type ErasedWorkflowEffect = Effect.Effect<unknown, unknown, never>;
 
+/** Assert that after a rotation every sealed value opens with the active key alone. Returns the report. */
+export declare const expectSealedWithActiveKeyAlone: (source: object, options: {
+    readonly tables: Iterable<unknown>;
+    readonly keyring?: FieldKeyring;
+}) => Promise<ActiveKeyAloneReport>;
+
+/**
+ * Assert that every sealed value in the database `layer` connects to opens with
+ * the active key alone. `tables` are the app's declared tables (their
+ * `.encrypted()` columns are always checked); `keyring` defaults to the one
+ * registered with `fieldKeys` / `registerTestFieldKeys`. Columns that cannot be
+ * read fail the assertion too — a check that skipped them would pass vacuously.
+ */
+export declare const expectSealedWithActiveKeyAloneInSql: (options: {
+    readonly dialect: DialectId;
+    readonly layer: Layer.Layer<SqlClient.SqlClient, unknown, never>;
+    readonly tables?: Iterable<unknown>;
+    readonly keyring?: FieldKeyring;
+    /** The keyring as configured (ids and keys, the active one named) — instead of a registered keyring. */
+    readonly fieldKeys?: FieldKeyringConfig;
+}) => Promise<ActiveKeyAloneSqlReport>;
+
 export declare interface Factory {
     /** The table this factory builds rows for. */
     readonly table: TableLike;
@@ -482,6 +549,14 @@ export declare interface MakeTestContextOptions<RowFilterCtx = unknown> {
      * gate, and the gate is what turns the variable into a cipher.
      */
     readonly fieldEncryptionKey?: string;
+    /**
+     * A keyring instead of one key — several ids, one active — registered the way
+     * the boot registers `VOLTRO_FIELD_ENCRYPTION_KEYS` (`registerTestFieldKeys`).
+     * With it, `expectSealedWithActiveKeyAlone(ctx, { tables })` checks what a
+     * rotation ends with: every sealed value opens with the active key alone.
+     * Not together with `fieldEncryptionKey`.
+     */
+    readonly fieldKeys?: FieldKeyringConfig;
     /**
      * Plugins whose rpc interceptors (`interceptMutation` / `interceptQuery` /
      * `interceptAction`) wrap every `invoke` on this context — the same list an
@@ -528,7 +603,7 @@ export declare interface MakeTestContextOptions<RowFilterCtx = unknown> {
      * Merged LAST, so a user layer overrides a plugin layer declaring the same
      * Tag — the ordering `makeHandlerServiceLayer` uses on both boot paths.
      */
-    readonly layers?: ReadonlyArray<Layer.Layer<unknown, never, never>>;
+    readonly layers?: ReadonlyArray<Layer.Layer<never, never, never>>;
     /**
      * Row-level security for this context, WITHOUT touching the process global.
      *
@@ -706,6 +781,8 @@ export declare interface PublicApiBinding {
     readonly handler: (input: never, ctx: TestContext) => unknown;
 }
 
+export declare const queryCacheOf: (ctx: TestContext) => TestQueryCache | undefined;
+
 export declare interface ReachableTarget {
     readonly host: string;
     readonly port: number;
@@ -721,6 +798,14 @@ export declare interface RecordedDelivery<P = unknown> {
     readonly n: number;
 }
 
+/**
+ * Register a keyring as this process's field cipher — what the boot builds from
+ * `VOLTRO_FIELD_ENCRYPTION_KEYS` — and remember its keys, so the active-key-alone
+ * check can open values with the active key and nothing else. Call it again with
+ * the next configuration to rotate inside a test.
+ */
+export declare const registerTestFieldKeys: (config: FieldKeyringConfig) => FieldKeyring;
+
 /**
  * The engine BUILD behind a target, printed once per file.
  *
@@ -809,6 +894,16 @@ export declare const runInStoreTransaction: <T>(ctx: TestContext, work: (txCtx:
 
 export { SchemaError }
 
+/**
+ * Every sealed value in `tables` — the app's declared tables, or names — opened
+ * with the active key alone; the values it does not open are listed. Reads the
+ * RAW rows (envelopes as stored), not through the store's decryption.
+ */
+export declare const sealedValuesWithActiveKeyAlone: (source: object, options: {
+    readonly tables: Iterable<unknown>;
+    readonly keyring?: FieldKeyring;
+}) => Promise<ActiveKeyAloneReport>;
+
 /** A machine subject scoped to ONE tenant (a per-tenant integration, a
  *  `storeForTenant` view). NOT the cross-tenant `system()` below. */
 export declare const serviceAccount: (id: string, options?: TestSubjectOptions) => Subject;
@@ -1071,6 +1166,22 @@ export declare interface TestEventBusOptions {
 
 export declare const TESTING_PRESET_VERSION: 1;
 
+/**
+ * The query cache a context's `invoke` serves `cache:` queries through — the
+ * runtime's own `cachedComputedCall` over a real `@voltro/cache` `Cache` (memory
+ * backend, ttl on `ctx.clock`). A write through any context of the tree drops
+ * the entries tagged with its table, synchronously, so a test can assert
+ * "write X invalidates query Y" and "a revoked grant refuses a hit" without a
+ * redis and without waiting.
+ */
+export declare interface TestQueryCache {
+    readonly deps: ComputedQueryCacheDeps;
+    /** This context's resolved row-filter visibility (`undefined`: no filter). */
+    readonly rowFilter: () => Promise<RowFilterScope | undefined>;
+    /** Results a cached compute did not keep, and why — the dev log's lines. */
+    readonly notices: ReadonlyArray<string>;
+}
+
 export declare interface TestRequestOptions {
     /** Extra headers for this call, merged over the app's (`actingAs` /
      *  `withHeaders`) headers. Names are lowercased, as the transport delivers
@@ -1094,13 +1205,13 @@ export declare interface TestResponse {
     readonly headers: Readonly<Record<string, string | ReadonlyArray<string>>>;
     /** The raw response body as text (empty string when there was none). */
     readonly text: string;
-    /** The body parsed as JSON when the route answered with a JSON content-type,
-     *  otherwise `undefined`. Every framework REST response is JSON; a streaming
-     *  (SSE) route answers with neither — see `stream`. */
+    /** Byte-exact buffered body, including a consumed finite byte stream. SSE remains unconsumed. */
+    readonly bytes?: Uint8Array;
+    /** Parsed JSON when the response has a JSON content-type; otherwise
+     *  `undefined`. SSE responses remain unconsumed. */
     readonly body: unknown;
-    /** `true` for a streaming (SSE) route: the response has no buffered body, so
-     *  `text` is empty and `body` is `undefined`. Stated rather than silently
-     *  looking like an empty 200. */
+    /** True for SSE and byte streams. Finite byte streams populate `bytes` and
+     *  `text`; SSE remains unconsumed, with empty text and undefined body. */
     readonly stream: boolean;
 }
 
@@ -1138,6 +1249,13 @@ export declare interface TestSubscriber<P = unknown> {
  */
 export declare const user: (id: string, options?: TestSubjectOptions) => Subject;
 
+/** Replace named app entries with scoped local transports, without changing a
+ * handler's references. Provide this layer last in a test context's layers. */
+export declare const withConnections: (overrides: Readonly<Record<ConnectionRef<"redis">, MemoryRedisConnection>>, options?: {
+    readonly connections?: ConnectionsConfig;
+    readonly connectAnalytics?: ConnectionRegistryOptions["connectAnalytics"];
+}) => Layer.Layer< ConnectionRegistry | RedisConnections, never, never>;
+
 /**
  * Run `body` with global time frozen at `at`, then restore — whether the body
  * returns, throws, resolves or rejects.