@ultimat3/testing 22.15.0 → 24.0.0

package/src/matcher-row.ts

@@ -0,0 +1,93 @@
+// Single responsibility: equality over a repository ROW, own properties included. `@ultimat3/entity`
+// answers a `.sealed()` column as a server-only property — own, readable by name, not enumerable —
+// and `toEqual` walks enumerable properties only: `expect(row).toEqual({ …, password })` fails with
+// an EMPTY diff (both sides print alike), and `toEqual(otherRow)` cannot see a wrong secret at all.
+// `toEqualRow` compares what the row HOLDS, and names what differs without printing a secret.
+
+import { describeValue, renderCauseValue } from '@ultimat3/core';
+import type { MatcherResult } from './matcher-result';
+
+const isPlain = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+/**
+ * `value` with every own property of every plain object in it made enumerable — the form
+ * `Bun.deepEquals` can compare. A `Date`, a `Map` or a class instance is left as it is: equality
+ * already knows them, and none of them is a row. `seen` maps an object to its copy, so a cycle
+ * comes back as a cycle instead of a stack overflow.
+ */
+const reveal = (value: unknown, seen: Map<object, unknown>): unknown => {
+  if (Array.isArray(value)) {
+    const known = seen.get(value);
+    if (known !== undefined) return known;
+    const out: unknown[] = [];
+    seen.set(value, out);
+    for (const item of value) out.push(reveal(item, seen));
+    return out;
+  }
+  if (!isPlain(value)) return value;
+  const known = seen.get(value);
+  if (known !== undefined) return known;
+  const out: Record<string, unknown> = {};
+  seen.set(value, out);
+  for (const key of Object.getOwnPropertyNames(value)) {
+    // `defineProperty`, never assignment: a key named `__proto__` must stay a key.
+    Object.defineProperty(out, key, {
+      value: reveal(value[key], seen),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return out;
+};
+
+const same = (received: unknown, expected: unknown): boolean =>
+  Bun.deepEquals(reveal(received, new Map()), reveal(expected, new Map()));
+
+const serverOnly = (row: unknown, key: string): boolean =>
+  isPlain(row) && Object.getOwnPropertyDescriptor(row, key)?.enumerable === false;
+
+/**
+ * One line per top-level property that differs. A server-only property is NAMED and nothing more —
+ * not its value and not its length: the message lands in a CI log, and that property is a secret.
+ */
+const differences = (received: unknown, expected: unknown): readonly string[] => {
+  if (!isPlain(received) || !isPlain(expected)) {
+    return [`received ${describeValue(received)}, expected ${describeValue(expected)}`];
+  }
+  const keys = new Set([
+    ...Object.getOwnPropertyNames(received),
+    ...Object.getOwnPropertyNames(expected),
+  ]);
+  const lines: string[] = [];
+  for (const key of keys) {
+    if (same(received[key], expected[key])) continue;
+    if (!serverOnly(received, key) && !serverOnly(expected, key)) {
+      lines.push(
+        `${key}: received ${renderCauseValue(received[key])}, expected ${renderCauseValue(expected[key])}`,
+      );
+    } else if (!Object.hasOwn(expected, key)) {
+      lines.push(`${key} (server-only): the row holds one and the expected value names none`);
+    } else if (!Object.hasOwn(received, key)) {
+      lines.push(`${key} (server-only): the expected value holds one and the row has none`);
+    } else {
+      lines.push(`${key} (server-only): differs — a server-only value is never printed`);
+    }
+  }
+  return lines;
+};
+
+export function rowEquality(received: unknown, expected: unknown): MatcherResult {
+  const pass = same(received, expected);
+  return {
+    pass,
+    message: () =>
+      pass
+        ? 'expected the row not to equal the given one, own non-enumerable properties included'
+        : `expected the row to equal the given one, own non-enumerable properties included — ${differences(received, expected).join('; ')}`,
+  };
+}

package/src/matcher-surface.ts

@@ -24,6 +24,13 @@ export interface UltimateMatchers<T> {
   toBeWithinBudget(limit: number): T;
   toRejectInput(input: unknown): Promise<T>;
   toAcceptInput(input: unknown): Promise<T>;
+  /**
+   * `toEqual` for a repository ROW. A `.sealed()` column is an own property a row does not
+   * ENUMERATE, so `toEqual({ …, password })` fails with an empty diff and `toEqual(otherRow)`
+   * cannot see a wrong secret. This compares every own property, and its message names what
+   * differs — a server-only property by shape, never by value.
+   */
+  toEqualRow(expected: unknown): T;
   /**
    * The one matcher that WAITS. Retries `isVisible()` to a budget — 5000ms every 100ms unless
    * narrowed — and `.not.toBeVisible()` waits for the element to GO rather than inverting one look.

package/src/matchers.ts

@@ -12,6 +12,7 @@ import {
   TestPolicyExpectedError,
 } from './matcher-receiver-errors';
 import type { MatcherResult } from './matcher-result';
+import { rowEquality } from './matcher-row';
 import type { UltimateMatchers } from './matcher-surface';
 import type { VisibleOptions } from './matcher-visible';
 import { assertVisibilityProbe, visibilityResult } from './matcher-visible';
@@ -296,6 +297,11 @@ const implementations: ExpectExtendMatchers<UltimateMatchers<unknown>> = {
     );
   },
 
+  // Any receiver is comparable, so there is nothing to refuse: a non-row simply is not equal.
+  toEqualRow(received: unknown, expected: unknown) {
+    return rowEquality(received, expected);
+  },
+
   toAcceptInput(received: unknown, input: unknown) {
     const schema = assertStandardSchema(received);
     return hasIssues(schema, input).then((rejected) =>

package/src/per-test-reset.ts

@@ -0,0 +1,43 @@
+// What every test starts from, put back by the preload before each one — the per-TEST half of
+// isolation, beside `file-boundary.ts`'s per-file half. Today one thing: the jobs event bus, which
+// STORES what it is handed, so an answer one test published resumed the next test's waiting run.
+
+import { beforeEach } from 'bun:test';
+import type { resetEventBus } from '@ultimat3/jobs';
+
+let installed = false;
+
+/**
+ * The module that holds the ambient bus, when something in this process has loaded it — and only
+ * then. A test that never touched `@ultimat3/jobs` has no bus to reset, and loading the package to
+ * reset one would put the jobs graph into every `packages/core` test.
+ */
+function loadedEventsModule(): string | undefined {
+  // Resolved once per process: every test asks, and the answer is a path that does not move.
+  eventsPath ??= Bun.resolveSync('@ultimat3/jobs', import.meta.dir).replace(
+    /index\.ts$/,
+    'events.ts',
+  );
+  return eventsPath in require.cache ? eventsPath : undefined;
+}
+
+let eventsPath: string | undefined;
+
+/** Before each test: a fresh ambient event bus, when the jobs package is loaded at all. */
+export async function resetPerTestState(): Promise<void> {
+  const events = loadedEventsModule();
+  if (events === undefined) return;
+  // Already evaluated — this import answers from the module registry, the same instance.
+  const loaded = (await import(events)) as { readonly resetEventBus: typeof resetEventBus };
+  loaded.resetEventBus();
+}
+
+/**
+ * Called by the app preload (`./preload`), once per process. In a preload, `beforeEach` runs
+ * before every test of every file; idempotent so a second caller cannot register it twice.
+ */
+export function installPerTestReset(): void {
+  if (installed) return;
+  installed = true;
+  beforeEach(resetPerTestState);
+}

package/src/preload.ts

@@ -5,15 +5,23 @@
 //   [test]
 //   preload = ["@ultimat3/testing/preload"]
 
+// A green run prints the reporter and nothing else: the process logger's lines go to a sink.
+import './quiet-logs';
 import { installDeterminism } from './determinism';
 import { registerFrameworkFixtures } from './framework-fixtures';
 import './matchers';
 import { installAppJsxLoader } from './app-jsx-loader';
 import { onFileBoundary } from './file-boundary';
-import { disposeLiveIslands } from './fixture-island';
-import { releasePluginsAfterIsolatedFile } from './isolated-plugins';
+import { ISOLATED_ENV, releasePluginsAfterIsolatedFile } from './isolated-plugins';
+import { installPerTestReset } from './per-test-reset';
 import { installRegistryLeakGuard } from './registry-leak-guard';
 import { sealNetwork } from './sealed-network';
+import { installTestSealKey } from './test-seal-key';
+
+// `.secrets.key` is gitignored and CI names no `ULTIMATE_SECRETS_KEY`: without a key every test
+// over a `.sealed()` column is `X_SEAL_KEY_MISSING` on a fresh clone. A throwaway one, only in a
+// test process (`NODE_ENV=test`) and only when the app supplied none — see the file.
+installTestSealKey();
 
 const seed = Number.parseInt(Bun.env['ULTIMATE_TEST_SEED'] ?? '', 10);
 const now = Bun.env['ULTIMATE_TEST_NOW'];
@@ -35,15 +43,14 @@ Bun.env['ULTIMATE_TEST_SLOT_HELD'] ??= '1';
 // fails a later file in another package, for a reason nothing in that file explains.
 installRegistryLeakGuard();
 
-// A worker runs many files in one global unless the repo opted into `--isolate` (22.7): a mount a
-// file never disposed is disposed between files, and `file-boundary.ts` then puts `globalThis`
-// back to what the first file saw.
-onFileBoundary(disposeLiveIslands);
+// And per TEST: the jobs event bus stores what it is handed, so one test's published answer
+// resumed the next test's waiting run (`per-test-reset.ts`).
+installPerTestReset();
 
 // A shared worker only (an isolated file is a fresh registry anyway): the app's
 // `defineApi({ pathStyle })` evaluates once per worker, in whichever file first imports it, and
 // must not be refused because an EARLIER file derived action paths under the default style.
-if (Bun.env['ULTIMATE_TEST_ISOLATED'] !== '1') {
+if (Bun.env[ISOLATED_ENV] !== '1') {
   const { forgetHandedOutActionPaths } = await import('@ultimat3/action');
   onFileBoundary(forgetHandedOutActionPaths);
 }

package/src/quiet-logs.ts

@@ -0,0 +1,56 @@
+// Single responsibility: where the process logger's lines go under `bun test`. Both preloads
+// import this FIRST, before anything that loads `@ultimat3/core`.
+//
+//   LOG_LEVEL unset            a green run prints the reporter and nothing else: every line is dropped
+//   LOG_LEVEL=info (or lower)  the escape hatch — `LOG_LEVEL=info bun test <file>` prints them
+//   LOG_LEVEL=warn (or higher) the terminal shows that level and above
+//
+// The third row is a FILTER ON THE TERMINAL, never the logger's own threshold. Core reads
+// `LOG_LEVEL` once, when it is first imported, so `LOG_LEVEL=error bun test` used to raise the
+// process logger itself to `error` — and a test that installs a sink to assert on an `info` audit
+// line collected nothing and failed for an environment variable. The level is therefore pinned at
+// `info` for the one moment core loads, and what the author named decides what is PRINTED.
+//
+// A test that asserts on log output hands `createLogger({ level, writer })` its own writer, or
+// installs its own `setLogSink` and restores the previous one. Never `process.stdout`.
+
+import type { LogLevel } from '@ultimat3/core';
+
+/** The levels above `info`, least severe first: the ones a named `LOG_LEVEL` must not cost a sink. */
+const ABOVE_INFO = ['warn', 'error', 'fatal', 'silent'] as const satisfies readonly LogLevel[];
+
+export type LogRouting =
+  | { readonly lines: 'dropped' }
+  | { readonly lines: 'printed' }
+  | { readonly lines: 'filtered'; readonly from: (typeof ABOVE_INFO)[number] };
+
+/**
+ * What a named `LOG_LEVEL` means for a test process. `info` and below are core's own to print, at
+ * the level named — asking for `debug` is asking for more lines, and a collecting sink is handed
+ * them too. Anything core would not read as a level is `info` there, so it is `printed` here.
+ */
+export function logRouting(named: string | undefined): LogRouting {
+  if (named === undefined || named === '') return { lines: 'dropped' };
+  const from = ABOVE_INFO.find((level) => level === named);
+  return from === undefined ? { lines: 'printed' } : { lines: 'filtered', from };
+}
+
+const named = Bun.env['LOG_LEVEL'];
+const routing = logRouting(named);
+
+// Core's `logger` is built at module init from this variable, so the pin goes in before the
+// import and the author's value goes back after it: a child this process spawns inherits what
+// was named, never the pin. A dynamic import, because a static one is hoisted above this line.
+if (routing.lines === 'filtered') Bun.env['LOG_LEVEL'] = 'info';
+const { setLogSink } = await import('@ultimat3/core');
+
+if (routing.lines === 'dropped') {
+  setLogSink(() => undefined);
+} else if (routing.lines === 'filtered') {
+  Bun.env['LOG_LEVEL'] = routing.from;
+  const shown = new Set<LogLevel>(ABOVE_INFO.slice(ABOVE_INFO.indexOf(routing.from)));
+  // Core's own split: `error` and above to stderr, the rest to stdout.
+  setLogSink((line, level) => {
+    if (shown.has(level)) (level === 'warn' ? process.stdout : process.stderr).write(`${line}\n`);
+  });
+}

package/src/registry-leak-guard.ts

@@ -7,7 +7,7 @@ import { afterAll } from 'bun:test';
 import { knownTags, registeredTiers } from '@ultimat3/cache';
 import { isAppRoot } from './app-jsx-loader';
 import { RegistryLeakError } from './errors';
-import { runFileBoundary } from './file-boundary';
+import { runBoundaryHooks, runFileBoundary } from './file-boundary';
 import type { ProcessRegistrySnapshot } from './registry-snapshot';
 import {
   captureProcessRegistries,
@@ -219,6 +219,8 @@ export function installRegistryLeakGuard(): void {
   });
 
   afterAll(() => {
+    // The run's LAST file has no boundary after it: its undisposed island mounts end here.
+    runBoundaryHooks();
     close();
     if (leaks.length > 0) throw new RegistryLeakError({ leaks });
   });

package/src/registry-snapshot.ts

@@ -24,6 +24,7 @@ import { registeredTasks, restoreTasks } from '@ultimat3/jobs';
 import type { RoleMap } from '@ultimat3/policy';
 import {
   knownPermissions,
+  permissionDeclarationSites,
   restorePermissions,
   restoreRoles,
   roleDeclarationSites,
@@ -39,6 +40,8 @@ export interface ProcessRegistrySnapshot {
   readonly locales: LocaleConfig;
   readonly catalogs: readonly (readonly [Locale, Catalog])[];
   readonly permissions: readonly string[];
+  /** Restored WITH the names: a site-less permission is one the policy step can never judge. */
+  readonly permissionSites: Readonly<Record<string, readonly string[]>>;
   readonly roles: RoleMap;
   /** Kept beside the map: restoring through `defineRoles()` would rewrite every site. */
   readonly roleSites: Readonly<Record<string, string>>;
@@ -57,6 +60,7 @@ export function captureProcessRegistries(): ProcessRegistrySnapshot {
     locales: localeConfig(),
     catalogs: registeredLocales().map((locale) => [locale, catalogFor(locale)] as const),
     permissions: knownPermissions(),
+    permissionSites: permissionDeclarationSites(),
     roles: roleDefinitions(),
     roleSites: roleDeclarationSites(),
     tasks: registeredTasks(),
@@ -74,7 +78,7 @@ export function restoreProcessRegistries(snapshot: ProcessRegistrySnapshot): voi
   // a partial call can never widen `supported` back.
   configureLocales(snapshot.locales);
   restoreCatalogs(snapshot.catalogs);
-  restorePermissions(snapshot.permissions);
+  restorePermissions(snapshot.permissions, snapshot.permissionSites);
   restoreRoles(snapshot.roles, snapshot.roleSites);
   restoreTasks(snapshot.tasks);
 }
@@ -138,9 +142,26 @@ export function mergeSnapshots(
     locales: newer.locales,
     catalogs: [...catalogs],
     permissions: [...new Set([...older.permissions, ...newer.permissions])],
+    permissionSites: mergeSites(older.permissionSites, newer.permissionSites),
     roles: { ...older.roles, ...newer.roles },
     roleSites: { ...older.roleSites, ...newer.roleSites },
     tasks: [...tasks.values()],
     catalogDeclarations: Math.max(older.catalogDeclarations, newer.catalogDeclarations),
   };
 }
+
+/** Per name, every module either snapshot saw declare it — the union the names themselves are. */
+function mergeSites(
+  older: Readonly<Record<string, readonly string[]>>,
+  newer: Readonly<Record<string, readonly string[]>>,
+): Readonly<Record<string, readonly string[]>> {
+  const merged = new Map<string, Set<string>>();
+  for (const side of [older, newer]) {
+    for (const [name, at] of Object.entries(side)) {
+      const into = merged.get(name) ?? new Set<string>();
+      for (const site of at) into.add(site);
+      merged.set(name, into);
+    }
+  }
+  return Object.fromEntries([...merged].map(([name, at]) => [name, [...at]]));
+}

package/src/render-view.ts

@@ -0,0 +1,118 @@
+// What the server renders, for a unit test: `renderView` for one component, `renderRoute` for a
+// whole route module — its `load`, its `meta` and its page, resolved the way a request resolves
+// them. No browser, no server, no cast: a test asserts on markup and on visible text.
+
+import type { Actor } from '@ultimat3/core';
+import { assert, createContext, runWithContext } from '@ultimat3/core';
+import type { IslandDirective, RouteConfig, RouteParams } from '@ultimat3/render';
+
+/** What a component rendered. */
+export interface RenderedView {
+  /** The markup, exactly as the document would carry it. */
+  readonly html: string;
+  /**
+   * What a reader sees: tags, scripts and styles removed, entities decoded, whitespace collapsed
+   * to single spaces. Compare it with `t('<key>')` — the markup escapes what the catalog does not.
+   */
+  readonly text: string;
+}
+
+/** What a route rendered for one request. */
+export interface RenderedRoute<TData> extends RenderedView {
+  /** What `load` resolved — the one object `meta` and the page were both given. */
+  readonly data: TData;
+  readonly meta: Awaited<ReturnType<RouteConfig<TData>['meta']>>;
+  /** The islands this render emitted, in order. Empty on a page that ships no JavaScript. */
+  readonly islands: readonly IslandDirective[];
+}
+
+/**
+ * A route file's exports, passed whole: `import * as page from './page'`. Only `config` is typed —
+ * the page component is found among the rest by the rule the router finds it by.
+ */
+export interface RouteModule<TData> {
+  readonly config: RouteConfig<TData>;
+  /** Everything else the file exports — the page among it. Open, so a literal module typechecks. */
+  readonly [exported: string]: unknown;
+}
+
+export interface RouteRequest {
+  /** Absolute, as a request's is. Its search string becomes the page's `query`. */
+  readonly url?: string;
+  readonly params?: RouteParams;
+  /** Who is asking. `load` and the page run inside a request context holding this actor. */
+  readonly actor?: Actor;
+}
+
+const DEFAULT_URL = 'http://localhost/';
+
+const SCRIPT_OR_STYLE = /<(script|style)\b[^>]*>[\s\S]*?<\/\1>/g;
+
+/**
+ * `&amp;` last: decoding it first would turn the text `&amp;lt;` — an author's literal `&lt;` —
+ * into `<`, a character the page never showed.
+ */
+const visibleText = (html: string): string =>
+  html
+    .replace(SCRIPT_OR_STYLE, ' ')
+    .replace(/<[^>]*>/g, ' ')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+const viewOf = (html: string): RenderedView => ({ html, text: visibleText(html) });
+
+/**
+ * Render one component with the props a page would hand it. The props are the component's own
+ * type, so a renamed prop is a compile error in the test rather than an `undefined` in the markup.
+ *
+ * No island collector: a component that renders an `island()` belongs to a route, which is where
+ * its hydration timing comes from — render it through `renderRoute`.
+ */
+export async function renderView<Props>(
+  component: (props: Props) => unknown,
+  props: Props,
+): Promise<RenderedView> {
+  const { renderToHtml } = await import('@ultimat3/render/server');
+  return viewOf(await renderToHtml(component(props)));
+}
+
+/**
+ * Render a route module the way a request does: `load` once, `meta` and the page on that same
+ * data, islands collected under the route's own `hydrate`. Pass the module whole —
+ * `import * as page from './page'` — so the page is found by the rule the router finds it by.
+ */
+export async function renderRoute<TData>(
+  module: RouteModule<TData>,
+  request: RouteRequest = {},
+): Promise<RenderedRoute<TData>> {
+  const render = await import('@ultimat3/render');
+  const { renderToHtml } = await import('@ultimat3/render/server');
+  const { config } = module;
+  // A copy typed by its own shape: the page is one of the exports `RouteModule` does not name.
+  const exported: Readonly<Record<string, unknown>> = { ...module };
+  const component = render.pageComponentOf(exported);
+  assert(
+    component !== undefined,
+    'renderRoute was handed a route module that exports no page component',
+    "export the page beside `config` — `export function Page()` — and pass the module whole: import * as page from './page'",
+  );
+  const url = request.url ?? DEFAULT_URL;
+  const ctx = { params: request.params ?? {}, url };
+  const islands = render.createIslandCollector({ file: url, hydrate: config.hydrate });
+
+  const run = async (): Promise<RenderedRoute<TData>> => {
+    const data = await render.routeDataFor(config, ctx);
+    const meta = await config.meta(render.metaContextFor(ctx, data));
+    const query = Object.fromEntries(new URL(url).searchParams);
+    const html = await renderToHtml(component({ data, params: ctx.params, url, query }), {
+      islands,
+    });
+    return { ...viewOf(html), data, meta, islands: islands.directives };
+  };
+
+  if (request.actor === undefined) return run();
+  return runWithContext(createContext({ actor: request.actor }), run);
+}

package/src/sealed-network.ts

@@ -36,7 +36,11 @@ const state: SealState = {
 };
 
 const matches = (route: MockRoute, url: string): boolean => {
-  if (route.match instanceof RegExp) return route.match.test(url);
+  if (route.match instanceof RegExp) {
+    // A `g`/`y` pattern's `test` resumes at `lastIndex`: without the reset, every other call missed.
+    route.match.lastIndex = 0;
+    return route.match.test(url);
+  }
   if (route.match.endsWith('*')) return url.startsWith(route.match.slice(0, -1));
   return route.match === url;
 };

package/src/template-db.ts

@@ -18,7 +18,7 @@ export interface TemplateDbConfig {
   /** Connection URL with rights to CREATE DATABASE. Absent means "fall back to PGlite". */
   readonly adminUrl?: string | undefined;
   readonly templateName?: string;
-  /** Applied once, into the template, under an advisory lock. */
+  /** Applied into the template under an advisory lock, which every worker's clone also holds. */
   readonly migrate?: (url: string) => Promise<void>;
 }
 
@@ -144,11 +144,14 @@ export async function acquireWorkerDatabase(
       // serialises them, so a failure here is a real failure and `alreadyExists` (a substring match
       // on the message) would read `relation "x_jobs" already exists` as success.
       if (config.migrate !== undefined) await config.migrate(urlFor(adminUrl, template));
+      // INSIDE the lock: `CREATE DATABASE … TEMPLATE` waits 5 s for every session on the template
+      // to leave, then refuses — and the next worker's migration opens one the moment the lock is
+      // free. Measured: a clone outside it failed whenever that migration ran past 5 s.
+      await admin.exec(dropSql(database));
+      await admin.exec(cloneSql(template, database));
     } finally {
       await admin.exec(unlockSql(template));
     }
-    await admin.exec(dropSql(database));
-    await admin.exec(cloneSql(template, database));
   } catch (error) {
     await admin.close();
     throw new TestDatabaseUnavailableError({

package/src/test-seal-key.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the master key a TEST process seals under when the app handed it none.
+// `.secrets.key` is gitignored and CI has no `ULTIMATE_SECRETS_KEY`, so without this every test
+// over an entity with a `.sealed()` column is `X_SEAL_KEY_MISSING` on a fresh clone. The preload
+// is the one caller; the key itself is not exported, from this module or from the package.
+
+import { findMasterKey, SECRETS_KEY_ENV } from '@ultimat3/core';
+
+/**
+ * Public by construction — it is in the package on npm — so it protects nothing and must never
+ * seal a real row. 64 hex characters, which is all `parseMasterKey` asks of a key.
+ */
+const TEST_SEAL_KEY = '7e57'.repeat(16);
+
+type EnvRecord = Record<string, string | undefined>;
+
+export interface TestSealKeySource {
+  /** The app root a `.secrets.key` would sit in. Defaults to the working directory. */
+  readonly root?: string;
+  /** Read for the mode and the key, and written to. Defaults to `process.env`. */
+  readonly env?: EnvRecord;
+}
+
+/**
+ * Installs the throwaway key, and answers whether it did. Two refusals, both silent because both
+ * are the correct outcome rather than a mistake to report:
+ *
+ * - **Not a test process.** `bun test` sets `NODE_ENV=test`; anything else — a server that
+ *   imported the preload, `NODE_ENV=production` — gets no key, so a sealed write there is still
+ *   `X_SEAL_KEY_MISSING` and never a row sealed under a key the whole world holds.
+ * - **A key is already there**, in the variable or in `.secrets.key`. The app's own key wins: a
+ *   suite that reads the committed `secrets.enc.json` needs the key that sealed it.
+ */
+export function installTestSealKey(source: TestSealKeySource = {}): boolean {
+  const env = source.env ?? (process.env as EnvRecord);
+  const added = testSealKeyEnv({ ...source, env });
+  Object.assign(env, added);
+  return SECRETS_KEY_ENV in added;
+}
+
+/**
+ * The same decision as a value: the variable to ADD to a child's environment, or nothing. For a
+ * harness that spawns the app under test (`startE2eApp`) — the child is a server, not a `bun test`
+ * process, so it can never install a key for itself, and it must not be able to. The rule is still
+ * judged in THIS process: only a test process hands the key down.
+ */
+export function testSealKeyEnv(source: TestSealKeySource = {}): Readonly<Record<string, string>> {
+  const env = source.env ?? (process.env as EnvRecord);
+  if (env['NODE_ENV'] !== 'test') return {};
+  if (findMasterKey(source.root ?? process.cwd(), env) !== undefined) return {};
+  return { [SECRETS_KEY_ENV]: TEST_SEAL_KEY };
+}