@cosmicdrift/kumiko-framework 0.292.0 → 0.294.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.292.0",
+  "version": "0.294.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.292.0",
-    "@cosmicdrift/kumiko-types": "0.292.0",
+    "@cosmicdrift/kumiko-http": "0.294.0",
+    "@cosmicdrift/kumiko-types": "0.294.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.292.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.294.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli-rebuild.integration.test.ts

@@ -18,7 +18,6 @@ import { buildEntityTable } from "../db/table-builder";
 import { createTenantDb, type TenantDb } from "../db/tenant-db";
 import { createEntity, createTextField, defineApply, defineFeature } from "../engine";
 import type { ProjectionDefinition } from "../engine/types";
-import { createEventsTable } from "../event-store";
 import { createProjectionStateTable } from "../pipeline";
 import { runSchemaCli, type SchemaCliOut } from "../schema-cli";
 import {
@@ -101,7 +100,6 @@ beforeAll(async () => {
   await ensureTemporalPolyfill();
   testDb = await createTestDb();
   await unsafeCreateEntityTable(testDb.db, itemEntity, "apply-item");
-  await createEventsTable(testDb.db);
   await createProjectionStateTable(testDb.db);
   await unsafePushTables(testDb.db, { applyItemsPerGroup: counterTable });
   tdb = createTenantDb(testDb.db, admin.tenantId);

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.294.0",
+    "type": "improvement",
+    "title": "Declare Key Manager ciphertext slots in the env schema",
+    "detail": "An env field can carry `.meta({ kumiko: { kms: true } })` to be deliverable as `<NAME>_CIPHERTEXT`. `runProdApp` now decrypts the schema-declared slots once at boot (`kmsSlotsOf(schema)` → `resolvePlatformKeks({ slots })`) and hands the resolved env to the boot-time master-key probe (`ValidateBootOptions.env`) and to the master-key keyring, so a ciphertext-only `KUMIKO_SECRETS_MASTER_KEY_V<n>` boots. `parseEnv` treats a `kms` slot as satisfied by its ciphertext twin. `composeEnvSchema` declares the `<NAME>_CIPHERTEXT` twin of every `kms` field itself (an already declared twin is kept), so a versioned family needs one declaration per version. `KUMIKO_SECRETS_MASTER_KEY_V1` of the secrets feature is such a slot. `runWorkerApp` takes the same slots as `kmsSlots` (it parses no schema). A deployment missing `KUMIKO_SECRETS_MASTER_KEY_V1` but carrying its `_CIPHERTEXT` twin now passes `parseEnv` and fails at the master-key probe if the decrypt yields nothing, instead of failing in `parseEnv`. `resolvePlatformKeks` without `slots` keeps resolving the three platform slots until consumers declare theirs."
+  },
+  {
+    "version": "0.293.0",
+    "type": "improvement",
+    "title": "Resolve the blind-index key from a Key Manager ciphertext",
+    "detail": "resolvePlatformKeks walks an allowlist of slots (PLATFORM_KEK, PLATFORM_KEK_PREVIOUS, KUMIKO_BLIND_INDEX_KEY) instead of two hardcoded KEK slots, so each slot's <SLOT>_CIPHERTEXT is unwrapped at boot. The blind-index key can leave the pod env in the clear with no app-code change, because resolveKmsWiringAsync already resolves before its trio check. Ciphertexts outside the allowlist are ignored rather than resolved: a foreign *_CIPHERTEXT must never fail boot."
+  },
   {
     "version": "0.292.0",
     "type": "fix",

package/src/crypto/__tests__/kek-source.test.ts

@@ -295,4 +295,147 @@ describe("resolvePlatformKeks", () => {
 
     expect(lines).toEqual([]);
   });
+
+  test("decrypts KUMIKO_BLIND_INDEX_KEY_CIPHERTEXT into KUMIKO_BLIND_INDEX_KEY", async () => {
+    const { fetch, calls } = trackedFetch([jsonResponse(200, { plaintext: PLAINTEXT_A })]);
+    const env: KekSourceEnv = {
+      KUMIKO_BLIND_INDEX_KEY_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result.KUMIKO_BLIND_INDEX_KEY).toBe(PLAINTEXT_A);
+    expect(calls.length).toBe(1);
+  });
+
+  test("a plaintext KUMIKO_BLIND_INDEX_KEY wins over its ciphertext, no fetch", async () => {
+    const { fetch, calls } = trackedFetch([]);
+    const env: KekSourceEnv = {
+      KUMIKO_BLIND_INDEX_KEY: "blind-index-plaintext",
+      KUMIKO_BLIND_INDEX_KEY_CIPHERTEXT: CIPHERTEXT_A,
+    };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result.KUMIKO_BLIND_INDEX_KEY).toBe("blind-index-plaintext");
+    expect(calls.length).toBe(0);
+  });
+
+  test("ignores a ciphertext outside the allowlist entirely", async () => {
+    const { fetch, calls } = trackedFetch([]);
+    const env: KekSourceEnv = {
+      FOO_CIPHERTEXT: CIPHERTEXT_A,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(calls.length).toBe(0);
+    expect(result["FOO"]).toBeUndefined();
+    expect(result).toBe(env);
+  });
+
+  test("decrypts PLATFORM_KEK and KUMIKO_BLIND_INDEX_KEY ciphertexts together", async () => {
+    const { fetch, calls } = trackedFetch([
+      jsonResponse(200, { plaintext: "active-plaintext" }),
+      jsonResponse(200, { plaintext: "blind-index-plaintext" }),
+    ]);
+    const env: KekSourceEnv = {
+      PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A,
+      KUMIKO_BLIND_INDEX_KEY_CIPHERTEXT: CIPHERTEXT_B,
+      PLATFORM_KEK_KMS_KEY_ID: "key-1",
+      PLATFORM_KEK_KMS_TOKEN: TOKEN,
+    };
+
+    const result = await resolvePlatformKeks(env, { fetch });
+
+    expect(result.PLATFORM_KEK).toBe("active-plaintext");
+    expect(result.KUMIKO_BLIND_INDEX_KEY).toBe("blind-index-plaintext");
+    expect(calls.length).toBe(2);
+  });
+
+  describe("with schema-declared slots", () => {
+    const KEY_MANAGER = { PLATFORM_KEK_KMS_KEY_ID: "key-1", PLATFORM_KEK_KMS_TOKEN: TOKEN };
+
+    test("resolves a versioned master-key family without the framework knowing the versions", async () => {
+      const { fetch, calls } = trackedFetch([
+        jsonResponse(200, { plaintext: "v1-plaintext" }),
+        jsonResponse(200, { plaintext: "v2-plaintext" }),
+      ]);
+      const env: KekSourceEnv = {
+        KUMIKO_SECRETS_MASTER_KEY_V1_CIPHERTEXT: CIPHERTEXT_A,
+        KUMIKO_SECRETS_MASTER_KEY_V2_CIPHERTEXT: CIPHERTEXT_B,
+        ...KEY_MANAGER,
+      };
+
+      const result = await resolvePlatformKeks(env, {
+        fetch,
+        slots: ["KUMIKO_SECRETS_MASTER_KEY_V1", "KUMIKO_SECRETS_MASTER_KEY_V2"],
+      });
+
+      expect(result["KUMIKO_SECRETS_MASTER_KEY_V1"]).toBe("v1-plaintext");
+      expect(result["KUMIKO_SECRETS_MASTER_KEY_V2"]).toBe("v2-plaintext");
+      expect(calls.length).toBe(2);
+    });
+
+    test("a plaintext beats its ciphertext per slot, the other slot still resolves", async () => {
+      const { fetch, calls } = trackedFetch([jsonResponse(200, { plaintext: "v2-plaintext" })]);
+      const env: KekSourceEnv = {
+        KUMIKO_SECRETS_MASTER_KEY_V1: "v1-plaintext",
+        KUMIKO_SECRETS_MASTER_KEY_V1_CIPHERTEXT: CIPHERTEXT_A,
+        KUMIKO_SECRETS_MASTER_KEY_V2_CIPHERTEXT: CIPHERTEXT_B,
+        ...KEY_MANAGER,
+      };
+
+      const result = await resolvePlatformKeks(env, {
+        fetch,
+        slots: ["KUMIKO_SECRETS_MASTER_KEY_V1", "KUMIKO_SECRETS_MASTER_KEY_V2"],
+      });
+
+      expect(result["KUMIKO_SECRETS_MASTER_KEY_V1"]).toBe("v1-plaintext");
+      expect(result["KUMIKO_SECRETS_MASTER_KEY_V2"]).toBe("v2-plaintext");
+      expect(calls.length).toBe(1);
+    });
+
+    test("does not touch the platform slots that the caller did not name", async () => {
+      const { fetch, calls } = trackedFetch([]);
+      const env: KekSourceEnv = { PLATFORM_KEK_CIPHERTEXT: CIPHERTEXT_A, ...KEY_MANAGER };
+
+      const result = await resolvePlatformKeks(env, { fetch, slots: [] });
+
+      expect(result).toBe(env);
+      expect(calls.length).toBe(0);
+    });
+
+    test("logs the source line for a declared slot", async () => {
+      const { fetch } = trackedFetch([jsonResponse(200, { plaintext: "v1-plaintext" })]);
+      const lines: string[] = [];
+      const env: KekSourceEnv = {
+        KUMIKO_SECRETS_MASTER_KEY_V1_CIPHERTEXT: CIPHERTEXT_A,
+        ...KEY_MANAGER,
+      };
+
+      await resolvePlatformKeks(env, {
+        fetch,
+        slots: ["KUMIKO_SECRETS_MASTER_KEY_V1"],
+        log: (line) => lines.push(line),
+      });
+
+      expect(lines).toEqual([
+        "KUMIKO_SECRETS_MASTER_KEY_V1 source=key-manager keyId=key-1 region=fr-par",
+      ]);
+    });
+
+    test("still rejects a previous KEK without its version when that slot is declared", async () => {
+      const { fetch } = trackedFetch([jsonResponse(200, { plaintext: "previous-plaintext" })]);
+      const env: KekSourceEnv = { PLATFORM_KEK_PREVIOUS_CIPHERTEXT: CIPHERTEXT_B, ...KEY_MANAGER };
+
+      await expect(
+        resolvePlatformKeks(env, { fetch, slots: ["PLATFORM_KEK_PREVIOUS"] }),
+      ).rejects.toThrow(/PLATFORM_KEK_PREVIOUS_VERSION must be set/);
+    });
+  });
 });

package/src/crypto/kek-source.ts

@@ -1,12 +1,16 @@
-// Resolves PLATFORM_KEK / PLATFORM_KEK_PREVIOUS from a Key Manager ciphertext
-// when no plaintext is set, so the KEK need not sit in the pod env in the
-// clear. `PLATFORM_KEK` stays the source of truth: a plaintext value always
-// wins over its ciphertext sibling, with no request made at all.
+// Resolves a caller-named set of secret slots from a Key Manager ciphertext
+// when no plaintext is set, so they need not sit in the pod env in the clear.
+// A slot's plaintext always wins over its ciphertext sibling, with no request
+// made at all. Any `*_CIPHERTEXT` in the env that names no requested slot is
+// ignored — a foreign ciphertext must never fail boot.
 
 const SCALEWAY_KEY_MANAGER_API_VERSION = "v1alpha1";
 const DEFAULT_REGION = "fr-par";
 const DECRYPT_TIMEOUT_MS = 5_000;
 const RETRY_DELAYS_MS = [200, 800];
+// Used when the caller names no slots. Apps that predate `kms` schema meta
+// rely on it; drop once every consumer declares its slots in the env schema.
+const LEGACY_SLOTS = ["PLATFORM_KEK", "PLATFORM_KEK_PREVIOUS", "KUMIKO_BLIND_INDEX_KEY"] as const;
 
 export type KekSourceEnv = {
   readonly PLATFORM_KEK?: string | undefined;
@@ -17,6 +21,8 @@ export type KekSourceEnv = {
   readonly PLATFORM_KEK_KMS_KEY_ID?: string | undefined;
   readonly PLATFORM_KEK_KMS_TOKEN?: string | undefined;
   readonly PLATFORM_KEK_KMS_REGION?: string | undefined;
+  readonly KUMIKO_BLIND_INDEX_KEY?: string | undefined;
+  readonly KUMIKO_BLIND_INDEX_KEY_CIPHERTEXT?: string | undefined;
   readonly [key: string]: string | undefined;
 };
 
@@ -25,6 +31,9 @@ export type KekSourceOptions = {
   readonly logPrefix?: string;
   /** Where the boot line naming the KEK source goes. Defaults to `console.info`. */
   readonly log?: (message: string) => void;
+  /** Env names to resolve, e.g. `kmsSlotsOf(schema)`. Defaults to the three
+   *  platform slots. */
+  readonly slots?: readonly string[];
 };
 
 function isRetryableStatus(status: number): boolean {
@@ -97,13 +106,14 @@ async function decryptCiphertext(
 }
 
 async function resolveSlot(
-  plaintext: string | undefined,
-  ciphertext: string | undefined,
+  name: string,
   env: KekSourceEnv,
   options: KekSourceOptions,
   fetchImpl: typeof globalThis.fetch,
 ): Promise<string | undefined> {
+  const plaintext = env[name];
   if (plaintext) return plaintext;
+  const ciphertext = env[`${name}_CIPHERTEXT`];
   if (!ciphertext) return undefined;
 
   const keyId = env.PLATFORM_KEK_KMS_KEY_ID;
@@ -111,7 +121,7 @@ async function resolveSlot(
   if (!keyId || !token) {
     const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
     throw new Error(
-      `${prefix}PLATFORM_KEK_KMS_KEY_ID / PLATFORM_KEK_KMS_TOKEN are all-or-none with a KEK ciphertext — a partial set means the KMS wiring is broken.`,
+      `${prefix}PLATFORM_KEK_KMS_KEY_ID / PLATFORM_KEK_KMS_TOKEN are all-or-none with a KEK ciphertext (slot ${name}) — a partial set means the KMS wiring is broken.`,
     );
   }
   const region = env.PLATFORM_KEK_KMS_REGION ?? DEFAULT_REGION;
@@ -121,12 +131,9 @@ async function resolveSlot(
 // A leftover plaintext beside a ciphertext boots green while nothing was
 // migrated, which is indistinguishable from a finished cutover unless the
 // boot says which source won. Never carries a key value, only its origin.
-function describeKekSource(
-  name: string,
-  plaintext: string | undefined,
-  ciphertext: string | undefined,
-  env: KekSourceEnv,
-): string | undefined {
+function describeKekSource(name: string, env: KekSourceEnv): string | undefined {
+  const plaintext = env[name];
+  const ciphertext = env[`${name}_CIPHERTEXT`];
   if (plaintext) {
     return ciphertext
       ? `${name} source=plaintext-env (ciphertext present and ignored)`
@@ -138,52 +145,36 @@ function describeKekSource(
 }
 
 // Each slot resolves independently so a rollback that clears one slot's
-// plaintext (leaving its ciphertext/_VERSION behind or gone) never blocks the
-// other slot's fallback path — the trio check downstream still applies.
+// plaintext (leaving its ciphertext/_VERSION behind or gone) never blocks
+// another slot's fallback path — the trio check downstream still applies.
 export async function resolvePlatformKeks(
   env: KekSourceEnv,
   options: KekSourceOptions = {},
 ): Promise<KekSourceEnv> {
   const fetchImpl = options.fetch ?? globalThis.fetch;
 
-  const active = await resolveSlot(
-    env.PLATFORM_KEK,
-    env.PLATFORM_KEK_CIPHERTEXT,
-    env,
-    options,
-    fetchImpl,
-  );
-  const previous = await resolveSlot(
-    env.PLATFORM_KEK_PREVIOUS,
-    env.PLATFORM_KEK_PREVIOUS_CIPHERTEXT,
-    env,
-    options,
-    fetchImpl,
-  );
+  const slots = options.slots ?? LEGACY_SLOTS;
+  const resolved: Record<string, string | undefined> = {};
+  for (const name of slots) {
+    resolved[name] = await resolveSlot(name, env, options, fetchImpl);
+  }
 
   const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
   // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
   const log = options.log ?? console.info;
-  for (const line of [
-    describeKekSource("PLATFORM_KEK", env.PLATFORM_KEK, env.PLATFORM_KEK_CIPHERTEXT, env),
-    describeKekSource(
-      "PLATFORM_KEK_PREVIOUS",
-      env.PLATFORM_KEK_PREVIOUS,
-      env.PLATFORM_KEK_PREVIOUS_CIPHERTEXT,
-      env,
-    ),
-  ]) {
+  for (const name of slots) {
+    const line = describeKekSource(name, env);
     if (line) log(`${prefix}${line}`);
   }
 
-  if (previous && !env.PLATFORM_KEK_PREVIOUS_VERSION) {
+  if (resolved["PLATFORM_KEK_PREVIOUS"] && !env.PLATFORM_KEK_PREVIOUS_VERSION) {
     throw new Error(
       `${prefix}PLATFORM_KEK_PREVIOUS_VERSION must be set when PLATFORM_KEK_PREVIOUS is set.`,
     );
   }
 
-  if (active === env.PLATFORM_KEK && previous === env.PLATFORM_KEK_PREVIOUS) {
-    return env;
-  }
-  return { ...env, PLATFORM_KEK: active, PLATFORM_KEK_PREVIOUS: previous };
+  const changed = slots.some((name) => resolved[name] !== env[name]);
+  if (!changed) return env;
+
+  return { ...env, ...resolved };
 }

package/src/db/__tests__/apply-entity-event-tenant.integration.test.ts

@@ -21,7 +21,6 @@ import { asRawClient, selectMany } from "../../db/query";
 import { createEntity, createTextField } from "../../engine/factories";
 import type { TenantId } from "../../engine/types";
 import type { StoredEvent } from "../../event-store";
-import { createEventsTable } from "../../event-store";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { applyEntityEvent } from "../apply-entity-event";
 import { buildEntityTable } from "../table-builder";
@@ -39,7 +38,6 @@ let testDb: BunTestDb;
 beforeAll(async () => {
   await ensureTemporalPolyfill();
   testDb = await createTestDb();
-  await createEventsTable(testDb.db);
   await asRawClient(testDb.db).unsafe(`
     CREATE TABLE read_apply_tenant_check (
       id uuid PRIMARY KEY,

package/src/db/__tests__/assert-no-unreachable-live-rows.integration.test.ts

@@ -14,7 +14,7 @@ import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db
 import { asRawClient, insertOne, selectMany } from "../../db/query";
 import { createBooleanField, createEntity, createTextField, defineFeature } from "../../engine";
 import { createRegistry } from "../../engine/registry";
-import { archiveStream, createArchivedStreamsTable, createEventsTable } from "../../event-store";
+import { archiveStream, createArchivedStreamsTable } from "../../event-store";
 import { rebuildProjection } from "../../pipeline";
 import { createProjectionStateTable } from "../../pipeline/projection-state";
 import { TestUsers, unsafeCreateEntityTable } from "../../stack";
@@ -49,7 +49,6 @@ beforeAll(async () => {
   await ensureTemporalPolyfill();
   testDb = await createTestDb();
   await unsafeCreateEntityTable(testDb.db, userEntity, "user");
-  await createEventsTable(testDb.db);
   await createArchivedStreamsTable(testDb.db);
   await createProjectionStateTable(testDb.db);
   tdb = createTenantDb(testDb.db, adminUser.tenantId);

package/src/db/__tests__/blind-index.integration.test.ts

@@ -20,7 +20,6 @@ import {
 import { defineFeature } from "../../engine/define-feature";
 import { createEntity, createTextField } from "../../engine/factories";
 import { createRegistry } from "../../engine/registry";
-import { createEventsTable } from "../../event-store";
 import { rebuildProjection } from "../../pipeline";
 import { createProjectionStateTable } from "../../pipeline/projection-state";
 import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
@@ -65,7 +64,6 @@ const adminUser = TestUsers.admin;
 beforeAll(async () => {
   testDb = await createTestDb();
   await unsafeCreateEntityTable(testDb.db, personEntity, "person");
-  await createEventsTable(testDb.db);
   await createProjectionStateTable(testDb.db);
   tdb = createTenantDb(testDb.db, adminUser.tenantId);
 });

package/src/db/__tests__/entity-field-encryption.test.ts

@@ -5,6 +5,7 @@ import {
   collectEncryptedFieldNames,
   decryptEntityFieldValues,
   encryptEntityFieldValues,
+  validateEntityFieldEncryptionAvailable,
 } from "../entity-field-encryption";
 
 const TEST_KEY = Buffer.from("a]bJm#kP9xQ2@wN!vL$hR5yT8eU0iO3f").toString("base64");
@@ -43,3 +44,31 @@ describe("entity-field-encryption", () => {
     expect(stored["secretNote"]).not.toBe("note");
   });
 });
+
+describe("validateEntityFieldEncryptionAvailable", () => {
+  test("accepts a keyring made only of the env it is handed", () => {
+    expect(() =>
+      validateEntityFieldEncryptionAvailable({ KUMIKO_SECRETS_MASTER_KEY_V1: TEST_KEY }),
+    ).not.toThrow();
+  });
+
+  test("rejects a handed env without any master key, whatever process.env holds", () => {
+    const previous = process.env["KUMIKO_SECRETS_MASTER_KEY_V1"];
+    process.env["KUMIKO_SECRETS_MASTER_KEY_V1"] = TEST_KEY;
+    try {
+      expect(() => validateEntityFieldEncryptionAvailable({})).toThrow(/no usable master key/);
+    } finally {
+      if (previous === undefined) delete process.env["KUMIKO_SECRETS_MASTER_KEY_V1"];
+      else process.env["KUMIKO_SECRETS_MASTER_KEY_V1"] = previous;
+    }
+  });
+
+  test("a pinned CURRENT_VERSION without that version's key still fails", () => {
+    expect(() =>
+      validateEntityFieldEncryptionAvailable({
+        KUMIKO_SECRETS_MASTER_KEY_V1: TEST_KEY,
+        KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "2",
+      }),
+    ).toThrow(/no usable master key/);
+  });
+});

package/src/db/__tests__/event-store-executor-list.integration.test.ts

@@ -15,7 +15,6 @@ import {
   SYSTEM_TENANT_ID,
 } from "../../engine";
 import { UnprocessableError } from "../../errors";
-import { createEventsTable } from "../../event-store";
 import { TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { encodeCursor } from "../cursor";
@@ -46,7 +45,6 @@ beforeAll(async () => {
   await ensureTemporalPolyfill();
   testDb = await createTestDb();
   await unsafeCreateEntityTable(testDb.db, entity, "pagerItem");
-  await createEventsTable(testDb.db);
   tdb = createTenantDb(testDb.db, admin.tenantId);
 });
 

package/src/db/__tests__/event-store-executor-money-rehydrate.integration.test.ts

@@ -9,7 +9,6 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
 import { asRawClient } from "../../db/query";
 import { createEntity, createMoneyField, createTextField, from } from "../../engine";
-import { createEventsTable } from "../../event-store";
 import { TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { createTestEnvelopeCipher } from "../../testing";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
@@ -59,7 +58,6 @@ beforeAll(async () => {
   await ensureTemporalPolyfill();
   testDb = await createTestDb();
   await unsafeCreateEntityTable(testDb.db, entity, "moneyOrder");
-  await createEventsTable(testDb.db);
   tdb = createTenantDb(testDb.db, admin.tenantId);
   configureEntityFieldEncryption(cipher);
 });

package/src/db/__tests__/event-store-executor-reference-search.integration.test.ts

@@ -11,7 +11,6 @@ import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db
 import { asRawClient } from "../../db/query";
 import { createEntity, createTextField, from } from "../../engine";
 import type { EntityDefinition } from "../../engine/types";
-import { createEventsTable } from "../../event-store";
 import { createInMemorySearchAdapter } from "../../search";
 import { TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { seedRows } from "../../testing";
@@ -156,7 +155,6 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(testDb.db, piiCustomerEntity, "refSearchPiiCustomer");
   await unsafeCreateEntityTable(testDb.db, piiOrderEntity, "refSearchPiiOrder");
   await unsafeCreateEntityTable(testDb.db, tenantMetaEntity, "tenant");
-  await createEventsTable(testDb.db);
   tdbA = createTenantDb(testDb.db, admin.tenantId);
   tdbB = createTenantDb(testDb.db, otherTenantAdmin.tenantId);
 });

package/src/db/__tests__/event-store-executor-reference-sort.integration.test.ts

@@ -9,7 +9,6 @@ import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db
 import { asRawClient } from "../../db/query";
 import { createEntity, createTextField } from "../../engine";
 import type { EntityDefinition } from "../../engine/types";
-import { createEventsTable } from "../../event-store";
 import { TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { seedRows } from "../../testing";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
@@ -107,7 +106,6 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(testDb.db, customerEntity, "refSortCustomer");
   await unsafeCreateEntityTable(testDb.db, orderEntity, "refSortOrder");
   await unsafeCreateEntityTable(testDb.db, restrictedOrderEntity, "refSortRestrictedOrder");
-  await createEventsTable(testDb.db);
   tdbA = createTenantDb(testDb.db, admin.tenantId);
 });
 

package/src/db/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -9,7 +9,6 @@ import { asRawClient, transaction } from "../../db/query";
 import { createEntity, createTextField } from "../../engine";
 import { from } from "../../engine/ownership";
 import { createSystemUser } from "../../engine/system-user";
-import { createEventsTable } from "../../event-store";
 import type { EntityCache } from "../../pipeline/entity-cache";
 import {
   createTestDb,
@@ -29,7 +28,6 @@ const nonAdmin = TestUsers.user;
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await createEventsTable(testDb.db);
   tdb = createTenantDb(testDb.db, admin.tenantId);
 });
 

package/src/db/__tests__/event-store-executor.integration.test.ts

@@ -2,7 +2,7 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { InMemoryKmsAdapter, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL } from "../../crypto";
 import { asRawClient } from "../../db/query";
 import { createBooleanField, createEntity, createTextField } from "../../engine";
-import { append, createEventsTable, loadEventsAfterVersion } from "../../event-store";
+import { append, loadEventsAfterVersion } from "../../event-store";
 import type { EntityCache } from "../../pipeline/entity-cache";
 import {
   createTestDb,
@@ -41,7 +41,6 @@ const adminUser = TestUsers.admin;
 beforeAll(async () => {
   testDb = await createTestDb();
   await unsafeCreateEntityTable(testDb.db, entity, "esExecUser");
-  await createEventsTable(testDb.db);
   tdb = createTenantDb(testDb.db, adminUser.tenantId);
 });
 

package/src/db/__tests__/implicit-projection-equivalence.integration.test.ts

@@ -19,7 +19,6 @@ import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } fr
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
 import { createBooleanField, createEntity, createTextField, defineFeature } from "../../engine";
 import { createRegistry } from "../../engine/registry";
-import { createEventsTable } from "../../event-store";
 import { rebuildProjection } from "../../pipeline";
 import { createProjectionStateTable } from "../../pipeline/projection-state";
 import { TestUsers, unsafeCreateEntityTable } from "../../stack";
@@ -52,7 +51,6 @@ beforeAll(async () => {
   await ensureTemporalPolyfill();
   testDb = await createTestDb();
   await unsafeCreateEntityTable(testDb.db, userEntity, "user");
-  await createEventsTable(testDb.db);
   await createProjectionStateTable(testDb.db);
   tdb = createTenantDb(testDb.db, adminUser.tenantId);
 });

package/src/db/__tests__/unique-violation-mapping.integration.test.ts

@@ -17,7 +17,6 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
 import { asRawClient, selectMany, transaction } from "../../db/query";
 import { createEntity, createTextField } from "../../engine";
-import { createEventsTable } from "../../event-store";
 import { TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { createEventStoreExecutor } from "../event-store-executor";
@@ -52,7 +51,6 @@ beforeAll(async () => {
   await ensureTemporalPolyfill();
   testDb = await createTestDb();
   await unsafeCreateEntityTable(testDb.db, userEntity, "unique-user");
-  await createEventsTable(testDb.db);
   tdb = createTenantDb(testDb.db, admin.tenantId);
 });
 

package/src/db/entity-field-encryption.ts

@@ -134,15 +134,17 @@ export function resetEntityFieldEncryptionCacheForTests(): void {
 // surfaces missing AND malformed keys (wrong length, bad base64) at boot
 // instead of on the first encrypted read in prod. validateBoot runs before
 // configureEntityFieldEncryption, so the env probe is the common path.
-export function validateEntityFieldEncryptionAvailable(): void {
+export function validateEntityFieldEncryptionAvailable(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): void {
   // skip: an injected cipher (test seam / custom KMS) satisfies availability
   if (injectedCipher) return;
   try {
     createEnvMasterKeyProvider({
       env: {
-        ...process.env,
+        ...env,
         KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION:
-          process.env["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
+          env["KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION"] ?? "1",
       },
     });
   } catch (err) {

package/src/db/queries/__tests__/event-store-idempotency-index.integration.test.ts

@@ -1,6 +1,5 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../../../bun-db/__tests__/bun-test-db";
-import { createEventsTable } from "../../../event-store/events-schema";
 import { asRawClient } from "../../query";
 import { ensureIdempotencyKeyIndex } from "../event-store";
 
@@ -8,7 +7,6 @@ let testDb: BunTestDb;
 
 beforeAll(async () => {
   testDb = await createTestDb();
-  await createEventsTable(testDb.db);
 });
 
 afterAll(async () => {

package/src/engine/boot-validator/index.ts

@@ -100,6 +100,10 @@ export type ValidateBootOptions = {
    *  screen is reachable another way (e.g. as a sub-page of a generated
    *  settings hub). Suppresses the navAllowlist warning for these QNs. */
   readonly navAllowlistExempt?: ReadonlySet<string>;
+  /** Env the encrypted-field master-key probe reads. Defaults to
+   *  `process.env`; runners pass their resolved env so a ciphertext-only
+   *  key (already decrypted at boot) is visible to the probe. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
 };
 
 /**
@@ -276,7 +280,7 @@ export function validateBoot(
     // catches malformed keys (wrong length, bad base64) at boot instead of
     // on the first encrypted read in prod. An injected cipher (test seam,
     // custom KMS provider) satisfies the requirement without env keys.
-    validateEntityFieldEncryptionAvailable();
+    validateEntityFieldEncryptionAvailable(options?.env);
   }
 
   if (hasFileFields && !process.env[FILE_STORAGE_PROVIDER_ENV]) {