@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -0,0 +1,248 @@
+// Blind-Index end-to-end (#818): create/update schreiben die bidx-Spalte
+// (nie ins Event-Log), Equality-Lookups matchen über den OR-Rewrite sowohl
+// verschlüsselte als auch Klartext-Alt-Rows, Rebuild recomputet bidx aus
+// dem Ciphertext (erased → NULL), und der Forget-Sweep nullt sofort.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  computeBlindIndex,
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  decodeBlindIndexKey,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+  subjectIdToKey,
+} from "../../crypto";
+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";
+import { nullBlindIndexesForSubject } from "../blind-index-cleanup";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { asRawClient, fetchOne } from "../query";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const TEST_KEY_B64 = Buffer.alloc(32, 7).toString("base64");
+const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
+
+const personEntity = createEntity({
+  table: "read_bidx_persons",
+  fields: {
+    email: createTextField({ required: true, pii: true, lookupable: true }),
+    firstName: createTextField(),
+  },
+});
+const personFeature = defineFeature("bidxtest", (r) => {
+  r.entity("person", personEntity);
+});
+const personTable = buildEntityTable("person", personEntity);
+
+let testDb: TestDb;
+let tdb: TenantDb;
+let kms: InMemoryKmsAdapter;
+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);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, read_bidx_persons, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+  configureBlindIndexKey(TEST_KEY_B64);
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+const crud = createEventStoreExecutor(personTable, personEntity, { entityName: "person" });
+
+async function rawRow(id: string): Promise<Record<string, unknown>> {
+  const rows = await asRawClient(testDb.db).unsafe<Record<string, unknown>>(
+    `SELECT * FROM read_bidx_persons WHERE id = $1`,
+    [id],
+  );
+  const row = rows[0];
+  if (!row) throw new Error(`no row for ${id}`);
+  return row;
+}
+
+describe("blind-index write path", () => {
+  test("create: bidx in the row, ciphertext in the email column, NOTHING in the event", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const row = await rawRow(String(created.data.id));
+    expect(row["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+    expect(isPiiCiphertext(row["email"])).toBe(true);
+
+    // Executor-Response: plaintext email, kein bidx-Leak.
+    expect(created.data.data["email"]).toBe("marc@example.com");
+    expect("emailBidx" in created.data.data).toBe(false);
+
+    const events = await asRawClient(testDb.db).unsafe<{ payload: unknown }>(
+      `SELECT payload FROM kumiko_events WHERE aggregate_id = $1`,
+      [String(created.data.id)],
+    );
+    const payloadText = JSON.stringify(events.map((e) => e.payload));
+    expect(payloadText).not.toContain("bidx");
+  });
+
+  test("update recomputes bidx for the changed field", async () => {
+    const created = await crud.create({ email: "old@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    await crud.update(
+      { id: created.data.id, version: 1, changes: { email: "new@example.com" } },
+      adminUser,
+      tdb,
+    );
+    const row = await rawRow(String(created.data.id));
+    expect(row["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "new@example.com"));
+  });
+});
+
+describe("blind-index lookup (OR-rewrite)", () => {
+  test("fetchOne by plaintext email finds the encrypted row", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const hit = await fetchOne<Record<string, unknown>>(tdb, personTable, {
+      email: "marc@example.com",
+    });
+    expect(hit).toBeDefined();
+    expect(hit?.["id"]).toBe(created.data.id);
+    // Read-Strip: bidx nie am Caller.
+    expect(hit && "emailBidx" in hit).toBe(false);
+    expect(hit && "email_bidx" in hit).toBe(false);
+
+    expect(await fetchOne(tdb, personTable, { email: "other@example.com" })).toBeUndefined();
+  });
+
+  test("plaintext legacy row (written pre-rollout) still matches the same query", async () => {
+    // Rollout-Zustand VOR KMS+Key: Klartext-Row, bidx NULL.
+    resetPiiSubjectKmsForTests();
+    resetBlindIndexKeyForTests();
+    const legacy = await crud.create({ email: "legacy@example.com" }, adminUser, tdb);
+    if (!legacy.isSuccess) throw new Error("create failed");
+    const legacyRow = await rawRow(String(legacy.data.id));
+    expect(legacyRow["email"]).toBe("legacy@example.com");
+    expect(legacyRow["email_bidx"]).toBeNull();
+
+    // Rollout an: dieselbe Query matcht über den Plaintext-Arm.
+    configurePiiSubjectKms(kms);
+    configureBlindIndexKey(TEST_KEY_B64);
+    const hit = await fetchOne<Record<string, unknown>>(tdb, personTable, {
+      email: "legacy@example.com",
+    });
+    expect(hit?.["id"]).toBe(legacy.data.id);
+  });
+
+  test("list filter eq matches the encrypted row and strips bidx", async () => {
+    const created = await crud.create(
+      { email: "marc@example.com", firstName: "Marc" },
+      adminUser,
+      tdb,
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+
+    const page = await crud.list(
+      { filter: { field: "email", op: "eq", value: "marc@example.com" } },
+      adminUser,
+      tdb,
+    );
+    expect(page.rows).toHaveLength(1);
+    expect(page.rows[0]?.["email"]).toBe("marc@example.com");
+    expect(page.rows[0] && "emailBidx" in page.rows[0]).toBe(false);
+
+    const miss = await crud.list(
+      { filter: { field: "email", op: "eq", value: "nobody@example.com" } },
+      adminUser,
+      tdb,
+    );
+    expect(miss.rows).toHaveLength(0);
+  });
+});
+
+describe("blind-index rebuild + forget", () => {
+  const implicitName = "bidxtest:projection:person-entity";
+
+  test("rebuild recomputes bidx from ciphertext (identical to live)", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    const liveBidx = (await rawRow(String(created.data.id)))["email_bidx"];
+
+    const registry = createRegistry([personFeature]);
+    expect(registry.getAllProjections().has(implicitName)).toBe(true);
+    await rebuildProjection(implicitName, { db: testDb.db, registry });
+
+    const rebuilt = await rawRow(String(created.data.id));
+    expect(rebuilt["email_bidx"]).toBe(liveBidx);
+    expect(rebuilt["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+  });
+
+  test("erased subject → rebuild sets bidx NULL, lookup stops matching", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    await kms.eraseKey({ kind: "user", userId: String(created.data.id) });
+
+    const registry = createRegistry([personFeature]);
+    await rebuildProjection(implicitName, { db: testDb.db, registry });
+
+    const rebuilt = await rawRow(String(created.data.id));
+    expect(rebuilt["email_bidx"]).toBeNull();
+    expect(await fetchOne(tdb, personTable, { email: "marc@example.com" })).toBeUndefined();
+  });
+
+  test("erased subject → column drift excludes bidx (#916, not counted)", async () => {
+    // Pre-swap, live still holds the OLD bidx hash while the shadow already
+    // computed NULL for the erased subject — a real live-vs-shadow divergence,
+    // but the exact legitimate class countColumnDrift is designed to ignore.
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    await kms.eraseKey({ kind: "user", userId: String(created.data.id) });
+
+    const registry = createRegistry([personFeature]);
+    const result = await rebuildProjection(implicitName, { db: testDb.db, registry });
+
+    expect(result.columnDriftCount).toBe(0);
+    expect((await rawRow(String(created.data.id)))["email_bidx"]).toBeNull();
+  });
+
+  test("nullBlindIndexesForSubject nulls bidx immediately (no rebuild needed)", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    expect((await rawRow(String(created.data.id)))["email_bidx"]).not.toBeNull();
+
+    await kms.eraseKey({ kind: "user", userId: String(created.data.id) });
+    const registry = createRegistry([personFeature]);
+    await nullBlindIndexesForSubject(
+      testDb.db,
+      registry.features,
+      subjectIdToKey({ kind: "user", userId: String(created.data.id) }),
+    );
+
+    expect((await rawRow(String(created.data.id)))["email_bidx"]).toBeNull();
+    expect(await fetchOne(tdb, personTable, { email: "marc@example.com" })).toBeUndefined();
+  });
+});

package/src/db/__tests__/build-filter-where.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { buildFilterWhere } from "../event-store-executor-context";
+
+describe("buildFilterWhere", () => {
+  test("eq: returns a direct field-equality WhereObject", () => {
+    expect(buildFilterWhere("status", "eq", "active")).toEqual({ status: "active" });
+  });
+
+  test("ne: wraps the value in a { ne } clause", () => {
+    expect(buildFilterWhere("status", "ne", "active")).toEqual({ status: { ne: "active" } });
+  });
+
+  test("lt: wraps the value in a { lt } clause", () => {
+    expect(buildFilterWhere("createdAt", "lt", 100)).toEqual({ createdAt: { lt: 100 } });
+  });
+
+  test("gt: wraps the value in a { gt } clause", () => {
+    expect(buildFilterWhere("createdAt", "gt", 100)).toEqual({ createdAt: { gt: 100 } });
+  });
+
+  test("in: non-empty array → direct array WhereObject", () => {
+    expect(buildFilterWhere("status", "in", ["active", "pending"])).toEqual({
+      status: ["active", "pending"],
+    });
+  });
+
+  test("in: empty array → null (no-match short-circuit)", () => {
+    expect(buildFilterWhere("status", "in", [])).toBeNull();
+  });
+
+  test("in: non-array value → null (no-match short-circuit)", () => {
+    expect(buildFilterWhere("status", "in", "not-an-array")).toBeNull();
+  });
+});

package/src/db/__tests__/collect-table-metas.test.ts

@@ -20,7 +20,7 @@ const counterTable = table("read_unit_counters", {
 }) as unknown as SchemaTable;
 
 describe("collectTableMetas (#255)", () => {
-  test("collects entity, projection, MSP and rawTable tables — same sources as the test-stack auto-push", () => {
+  test("collects entity, projection, MSP and storeTable tables — same sources as the test-stack auto-push", () => {
     const feature = defineFeature("test", (r) => {
       r.entity("unit", exampleEntity());
       r.projection({
@@ -39,16 +39,16 @@ describe("collectTableMetas (#255)", () => {
       });
       // side-effect-only MSP — no table, must be skipped without throwing
       r.multiStreamProjection({ name: "unit-notify", apply: { "unit.created": async () => {} } });
-      r.rawTable(
-        "cache",
-        table("unit_cache", {
-          id: uuid("id").primaryKey(),
-        }) as unknown as SchemaTable,
+      r.storeTable(
+        defineUnmanagedTable({
+          tableName: "unit_cache",
+          columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true }],
+        }),
         { reason: "test fixture" },
       );
-      r.unmanagedTable(
+      r.storeTable(
         defineUnmanagedTable({
-          tableName: "read_unit_log",
+          tableName: "store_unit_log",
           columns: [{ name: "id", pgType: "serial", notNull: true, primaryKey: true }],
         }),
         { reason: "test fixture" },
@@ -59,8 +59,8 @@ describe("collectTableMetas (#255)", () => {
     expect(names).toContain("read_units"); // entity
     expect(names).toContain("read_unit_counters"); // r.projection
     expect(names).toContain("read_unit_audit"); // r.multiStreamProjection
-    expect(names).toContain("unit_cache"); // r.rawTable
-    expect(names).toContain("read_unit_log"); // r.unmanagedTable
+    expect(names).toContain("unit_cache"); // r.storeTable
+    expect(names).toContain("store_unit_log"); // r.storeTable (second registration)
     expect(names).toHaveLength(5);
   });
 

package/src/db/__tests__/config-seed.integration.test.ts

@@ -10,10 +10,11 @@ import {
   SYSTEM_TENANT_ID,
 } from "../../engine";
 import type { ConfigSeedDef, Registry } from "../../engine/types";
+import { createEnvMasterKeyProvider } from "../../secrets/env-master-key-provider";
+import { createEnvelopeCipher } from "../../secrets/envelope-cipher";
 import { unsafeCreateEntityTable } from "../../stack";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { seedConfigValues } from "../config-seed";
-import { createEncryptionProvider } from "../encryption";
 import { buildEntityTable } from "../table-builder";
 
 // --- Test Entity ---
@@ -51,8 +52,15 @@ const mockRegistry = {
 } as unknown as Registry;
 
 // --- Helpers ---
-const encryption = createEncryptionProvider(
-  Buffer.from("0123456789abcdef0123456789abcdef").toString("base64"),
+const encryption = createEnvelopeCipher(
+  createEnvMasterKeyProvider({
+    env: {
+      KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
+      KUMIKO_SECRETS_MASTER_KEY_V1: Buffer.from("0123456789abcdef0123456789abcdef").toString(
+        "base64",
+      ),
+    },
+  }),
 );
 
 let testDb: BunTestDb;
@@ -214,7 +222,7 @@ describe("seedConfigValues", () => {
 
     await expect(
       seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db),
-    ).rejects.toThrow(/encrypted but no EncryptionProvider/);
+    ).rejects.toThrow(/encrypted but no EnvelopeCipher/);
   });
 
   test("encrypted seed with provider stores ciphertext, not plaintext", async () => {
@@ -240,7 +248,7 @@ describe("seedConfigValues", () => {
     // resolver later runs `decrypt → JSON.parse` to get the primitive
     // back; we replay the same round-trip here.
     expect(row!.value).not.toContain("sk_live_secret_token");
-    expect(JSON.parse(encryption.decrypt(row!.value))).toBe("sk_live_secret_token");
+    expect(JSON.parse(await encryption.decrypt(row!.value))).toBe("sk_live_secret_token");
   });
 
   test("race-safe parallel boot — two concurrent calls result in 1 created + 1 skipped", async () => {

package/src/db/__tests__/dialect-instant.test.ts

@@ -11,11 +11,8 @@
 // die invalid-Probe (echte Garbage muss weiterhin throwen — kein silent
 // swallowing).
 
-import { ensureTemporalPolyfill } from "../../time/polyfill";
-
-await ensureTemporalPolyfill();
-
 import { describe, expect, test } from "bun:test";
+import { Temporal } from "temporal-polyfill";
 import { instantToDriver as toDriver } from "../dialect";
 
 describe("instant() customType — toDriver", () => {

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

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
-import { createEncryptionProvider } from "../encryption";
+import { createTestEnvelopeCipher } from "../../testing";
 import {
   collectEncryptedFieldNames,
   decryptEntityFieldValues,
@@ -18,25 +18,25 @@ describe("entity-field-encryption", () => {
     },
   });
   const encryptedFields = collectEncryptedFieldNames(entity);
-  const encryption = createEncryptionProvider(TEST_KEY);
+  const encryption = createTestEnvelopeCipher(TEST_KEY);
 
   test("collectEncryptedFieldNames finds encrypted text fields only", () => {
     expect([...encryptedFields]).toEqual(["secretNote"]);
   });
 
-  test("encrypt on write / decrypt on read round-trip", () => {
+  test("encrypt on write / decrypt on read round-trip", async () => {
     const plain = { email: "a@b.de", secretNote: "top secret" };
-    const stored = encryptEntityFieldValues(plain, encryptedFields, encryption);
+    const stored = await encryptEntityFieldValues(plain, encryptedFields, encryption);
     expect(stored["email"]).toBe(plain.email);
     expect(stored["secretNote"]).not.toBe("top secret");
 
-    const read = decryptEntityFieldValues(stored, encryptedFields, encryption);
+    const read = await decryptEntityFieldValues(stored, encryptedFields, encryption);
     expect(read).toEqual(plain);
   });
 
-  test("onlyKeys limits encryption to changed fields", () => {
+  test("onlyKeys limits encryption to changed fields", async () => {
     const row = { email: "a@b.de", secretNote: "note" };
-    const stored = encryptEntityFieldValues(row, encryptedFields, encryption, {
+    const stored = await encryptEntityFieldValues(row, encryptedFields, encryption, {
       onlyKeys: ["secretNote"],
     });
     expect(stored["email"]).toBe("a@b.de");

package/src/db/__tests__/entity-table-meta-source.test.ts

@@ -0,0 +1,50 @@
+// #1210: buildEntityTableMeta() hardcoded source: "managed", so unmanaged
+// direct-write stores (store_user_sessions, store_api_tokens, mail sync/seen
+// cursors) were misclassified as rebuildable event-sourced projections — a
+// destructive column change would DROP+rebuild-from-events tables that have
+// no events, wiping live data. The options.source escape hatch must produce
+// a byte-identical column/piiSubjectFields shape (only source differs), so
+// the migration diff for an existing table stays empty when flipping it.
+
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine";
+import { buildEntityTableMeta } from "../entity-table-meta";
+import { diffSnapshots, snapshotFromMetas } from "../migrate-generator";
+
+const entity = createEntity({
+  table: "source-probe",
+  fields: {
+    userId: createTextField({ required: true }),
+    ip: createTextField({ userOwned: { ownerField: "userId" } }),
+  },
+});
+
+describe("buildEntityTableMeta — options.source (#1210)", () => {
+  test("defaults to managed when omitted", () => {
+    expect(buildEntityTableMeta("source-probe", entity).source).toBe("managed");
+  });
+
+  test("options.source: 'unmanaged' changes only source, columns + piiSubjectFields stay identical", () => {
+    const managed = buildEntityTableMeta("source-probe", entity);
+    const unmanaged = buildEntityTableMeta("source-probe", entity, { source: "unmanaged" });
+
+    expect(managed.source).toBe("managed");
+    expect(unmanaged.source).toBe("unmanaged");
+    expect(unmanaged.columns).toEqual(managed.columns);
+    expect(unmanaged.indexes).toEqual(managed.indexes);
+    expect(unmanaged.piiSubjectFields).toEqual(managed.piiSubjectFields);
+    expect(unmanaged.piiSubjectFields).toEqual(["ip"]);
+  });
+
+  test("flipping an existing table's meta to unmanaged produces an empty migration diff", () => {
+    const prevSnapshot = snapshotFromMetas([buildEntityTableMeta("source-probe", entity)]);
+    const nextSnapshot = snapshotFromMetas([
+      buildEntityTableMeta("source-probe", entity, { source: "unmanaged" }),
+    ]);
+
+    const diff = diffSnapshots(prevSnapshot, nextSnapshot);
+    expect(diff.newTables).toEqual([]);
+    expect(diff.droppedTables).toEqual([]);
+    expect(diff.changedTables).toEqual([]);
+  });
+});

package/src/db/__tests__/event-store-executor-context.pii-roundtrip.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decryptPiiFieldValues,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  type KmsContext,
+} from "../../crypto";
+import { createEntity, createTextField } from "../../engine";
+import { createTestUser, testUserId } from "../../stack/test-users";
+import { createTestEnvelopeCipher } from "../../testing";
+import { buildExecutorContext, type Table } from "../event-store-executor-context";
+
+const TEST_KEY = Buffer.from("a]bJm#kP9xQ2@wN!vL$hR5yT8eU0iO3f").toString("base64");
+
+describe("event-store-executor-context — encryptForStorage/decryptForRead layering", () => {
+  const entity = createEntity({
+    table: "pii_roundtrip_test",
+    fields: {
+      userId: createTextField({ required: true }),
+      // Both markers at once — the auth-mfa.totpSecret/recoveryCodes shape
+      // that first surfaced the ordering bug (pii-subject-encryption
+      // integration test).
+      secretNote: createTextField({ encrypted: true, userOwned: { ownerField: "userId" } }),
+    },
+  });
+  const encryption = createTestEnvelopeCipher(TEST_KEY);
+  const kms = new InMemoryKmsAdapter();
+  const kmsCtx: KmsContext = { requestId: "test" };
+  const context = buildExecutorContext({} as Table, entity, {
+    entityName: "piiRoundtripTest",
+    encryption,
+    kms,
+  });
+  const user = createTestUser({ id: testUserId(1) });
+
+  test("round-trips through both layers", async () => {
+    const row = { userId: user.id, secretNote: "the actual secret" };
+    const stored = await context.encryptForStorage(row, user);
+    expect(stored["secretNote"]).not.toBe("the actual secret");
+
+    const read = await context.decryptForRead(stored);
+    expect(read["secretNote"]).toBe("the actual secret");
+  });
+
+  test("stores PII(envelope(plaintext)) — PII is the outer layer, not envelope", async () => {
+    const row = { userId: user.id, secretNote: "the actual secret" };
+    const stored = await context.encryptForStorage(row, user);
+    const storedNote = stored["secretNote"];
+
+    // Outer layer is PII ciphertext.
+    expect(isPiiCiphertext(storedNote)).toBe(true);
+
+    // Peeling only the outer (PII) layer must leave an envelope-ciphertext
+    // string underneath, not the plaintext directly — proves encryptForStorage
+    // wrapped the envelope-ciphertext with PII, not the raw plaintext.
+    const piiPeeled = await decryptPiiFieldValues(stored, ["secretNote"], kms, kmsCtx);
+    const innerValue = piiPeeled["secretNote"];
+    expect(innerValue).not.toBe("the actual secret");
+    expect(isPiiCiphertext(innerValue)).toBe(false);
+    await expect(encryption.decrypt(innerValue as string)).resolves.toBe("the actual secret");
+
+    // decryptForRead must peel PII first: feeding the stored value straight
+    // to the envelope cipher (skipping the PII unwrap) has to fail — this is
+    // the ordering bug the roundtrip guards against.
+    await expect(encryption.decrypt(storedNote as string)).rejects.toThrow();
+  });
+});