@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/event-store/__tests__/backfill-pii.integration.test.ts

@@ -0,0 +1,279 @@
+// backfillEventPiiEncryption (#799): pre-KMS plaintext events get re-
+// encrypted in place — entity lifecycle payloads (created / updated
+// changes+previous / forgotten previous) AND catalogued custom events.
+// Pre-KMS-forgotten subjects (detectable only via their *.forgotten event)
+// get [[erased]] instead of a freshly minted key. After the backfill,
+// applyEntityEvent (the rebuild primitive) materializes ciphertext AND the
+// blind-index column, so equality lookups keep working.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "../../crypto";
+import { applyEntityEvent } from "../../db/apply-entity-event";
+import { backfillEventPiiEncryption } from "../../db/queries/backfill-pii";
+import { asRawClient, fetchOne } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { defineFeature } from "../../engine/define-feature";
+import { createEntity, createTextField } from "../../engine/factories";
+import { createRegistry } from "../../engine/registry";
+import type { Registry, TenantId } from "../../engine/types";
+import { createTestDb, type TestDb, unsafeCreateEntityTable } from "../../stack";
+import { generateId } from "../../utils";
+import { append, loadAggregate } from "../event-store";
+import { createEventsTable } from "../events-schema";
+
+const TENANT = "00000000-0000-4000-8000-000000000001" as TenantId;
+const BIDX_KEY = Buffer.alloc(32, 5).toString("base64");
+
+const contactEntity = createEntity({
+  fields: {
+    email: createTextField({ required: true, pii: true, lookupable: true }),
+    displayName: createTextField(),
+  },
+});
+const contactTable = buildEntityTable("contact", contactEntity);
+
+const crmFeature = defineFeature("crm", (r) => {
+  r.entity("contact", contactEntity);
+});
+
+const mailerFeature = defineFeature("mailer", (r) => {
+  r.defineEvent(
+    "ping",
+    z.object({ targetId: z.string().nullable(), address: z.string().nullable() }),
+    { piiFields: { address: { subjectField: "targetId" } } },
+  );
+});
+
+let testDb: TestDb;
+let registry: Registry;
+let kms: InMemoryKmsAdapter;
+
+async function appendPlain(
+  aggregateId: string,
+  aggregateType: string,
+  type: string,
+  payload: Record<string, unknown>,
+  expectedVersion = 0,
+): Promise<void> {
+  await append(testDb.db, {
+    aggregateId,
+    aggregateType,
+    tenantId: TENANT,
+    expectedVersion,
+    type,
+    payload,
+    metadata: { userId: "system" },
+  });
+}
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  registry = createRegistry([crmFeature, mailerFeature]);
+  await createEventsTable(testDb.db);
+  await unsafeCreateEntityTable(testDb.db, contactEntity, "contact");
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  const raw = asRawClient(testDb.db);
+  await raw.unsafe(`TRUNCATE "kumiko_events" RESTART IDENTITY`);
+  await raw.unsafe(`TRUNCATE "${contactTable.tableName}"`);
+  // Plaintext era: NO KMS while the legacy events are appended.
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+  resetBlindIndexKeyForTests();
+});
+
+function armKms(): void {
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+}
+
+describe("backfillEventPiiEncryption", () => {
+  test("encrypts entity lifecycle payloads: created flat, updated changes+previous", async () => {
+    const c1 = generateId();
+    await appendPlain(c1, "contact", "contact.created", {
+      id: c1,
+      email: "old@x.com",
+      displayName: "Alice",
+    });
+    await appendPlain(
+      c1,
+      "contact",
+      "contact.updated",
+      { changes: { email: "new@x.com" }, previous: { id: c1, email: "old@x.com" } },
+      1,
+    );
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+
+    expect(result.failures).toEqual([]);
+    expect(result.updatedEvents).toBe(2);
+    expect(result.encryptedFields).toBe(3);
+
+    const events = await loadAggregate(testDb.db, c1, TENANT);
+    const created = events[0]?.payload as Record<string, unknown>;
+    expect(isPiiCiphertext(created["email"])).toBe(true);
+    expect(String(created["email"])).toContain(`user:${c1}`);
+    expect(created["displayName"]).toBe("Alice");
+
+    const updated = events[1]?.payload as {
+      changes: Record<string, unknown>;
+      previous: Record<string, unknown>;
+    };
+    expect(isPiiCiphertext(updated.changes["email"])).toBe(true);
+    expect(isPiiCiphertext(updated.previous["email"])).toBe(true);
+  });
+
+  test("pre-KMS-forgotten aggregate gets [[erased]], not a fresh key", async () => {
+    const c2 = generateId();
+    await appendPlain(c2, "contact", "contact.created", { id: c2, email: "gone@x.com" });
+    await appendPlain(
+      c2,
+      "contact",
+      "contact.forgotten",
+      { previous: { id: c2, email: "gone@x.com" } },
+      1,
+    );
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+
+    expect(result.failures).toEqual([]);
+    expect(result.erasedFields).toBe(2);
+    const events = await loadAggregate(testDb.db, c2, TENANT);
+    const created = events[0]?.payload as Record<string, unknown>;
+    expect(created["email"]).toBe(PII_ERASED_SENTINEL);
+    const forgotten = events[1]?.payload as { previous: Record<string, unknown> };
+    expect(forgotten.previous["email"]).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("catalogued custom events: encrypt under target's DEK; forgotten target → [[erased]]", async () => {
+    const forgottenUser = generateId();
+    await appendPlain(forgottenUser, "contact", "contact.created", {
+      id: forgottenUser,
+      email: "f@x.com",
+    });
+    await appendPlain(
+      forgottenUser,
+      "contact",
+      "contact.forgotten",
+      { previous: { id: forgottenUser, email: "f@x.com" } },
+      1,
+    );
+
+    const p1 = generateId();
+    const p2 = generateId();
+    const p3 = generateId();
+    await appendPlain(p1, "ping", "mailer:event:ping", {
+      targetId: "u-7",
+      address: "u7@x.com",
+    });
+    await appendPlain(p2, "ping", "mailer:event:ping", {
+      targetId: forgottenUser,
+      address: "f@x.com",
+    });
+    await appendPlain(p3, "ping", "mailer:event:ping", { targetId: null, address: "ops@x.com" });
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+
+    expect(result.failures).toEqual([]);
+    const alive = (await loadAggregate(testDb.db, p1, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(isPiiCiphertext(alive["address"])).toBe(true);
+    expect(String(alive["address"])).toContain("user:u-7");
+
+    const erased = (await loadAggregate(testDb.db, p2, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(erased["address"]).toBe(PII_ERASED_SENTINEL);
+
+    // No subject → no key to shred; stays plaintext (documented rollout gap).
+    const system = (await loadAggregate(testDb.db, p3, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(system["address"]).toBe("ops@x.com");
+  });
+
+  test("idempotent: second run updates nothing; dryRun writes nothing", async () => {
+    const c1 = generateId();
+    await appendPlain(c1, "contact", "contact.created", { id: c1, email: "a@x.com" });
+
+    armKms();
+    const dry = await backfillEventPiiEncryption(testDb.db, registry, { dryRun: true });
+    expect(dry.updatedEvents).toBe(1);
+    const untouched = (await loadAggregate(testDb.db, c1, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(untouched["email"]).toBe("a@x.com");
+
+    const first = await backfillEventPiiEncryption(testDb.db, registry);
+    expect(first.updatedEvents).toBe(1);
+    const second = await backfillEventPiiEncryption(testDb.db, registry);
+    expect(second.updatedEvents).toBe(0);
+    expect(second.failures).toEqual([]);
+  });
+
+  test("small batchSize pages through the estate completely", async () => {
+    const ids = [generateId(), generateId(), generateId(), generateId(), generateId()];
+    for (const id of ids) {
+      await appendPlain(id, "contact", "contact.created", { id, email: `${id}@x.com` });
+    }
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry, { batchSize: 2 });
+    expect(result.scannedEvents).toBe(5);
+    expect(result.updatedEvents).toBe(5);
+  });
+
+  test("after backfill, applyEntityEvent (rebuild) materializes ciphertext + blind index", async () => {
+    const c1 = generateId();
+    await appendPlain(c1, "contact", "contact.created", { id: c1, email: "login@x.com" });
+
+    armKms();
+    configureBlindIndexKey(BIDX_KEY);
+    await backfillEventPiiEncryption(testDb.db, registry);
+
+    const events = await loadAggregate(testDb.db, c1, TENANT);
+    const created = events[0];
+    if (!created) throw new Error("missing created event");
+    await applyEntityEvent(created, contactTable, contactEntity, testDb.db);
+
+    const row = await fetchOne(testDb.db, contactTable, { id: c1 });
+    expect(isPiiCiphertext(row?.["email"])).toBe(true);
+    const rawRows = (await asRawClient(testDb.db).unsafe(
+      `SELECT "email_bidx" FROM "${contactTable.tableName}" WHERE "id" = $1`,
+      [c1],
+    )) as ReadonlyArray<Record<string, unknown>>;
+    expect(String(rawRows[0]?.["email_bidx"])).toStartWith("kumiko-bidx:v1:");
+  });
+
+  test("throws without a configured KMS", async () => {
+    expect(backfillEventPiiEncryption(testDb.db, registry)).rejects.toThrow(
+      /requires a configured subject KMS/,
+    );
+  });
+});

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

@@ -6,6 +6,7 @@ import { generateId as uuid } from "../../utils";
 import {
   append,
   createEventsTable,
+  IdempotentAppendConflictError,
   loadAggregate,
   loadAggregateAsOf,
   loadAllEventsByType,
@@ -59,6 +60,38 @@ describe("event-store: append + load", () => {
     expect(events[0]?.metadata.userId).toBe(userA);
   });
 
+  test("kumiko-framework#1490: subsequent append doesn't rely on globalThis.Temporal", async () => {
+    const aggregateId = uuid();
+    const first = await append(testDb.db, {
+      aggregateId,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "Buy milk" },
+      metadata: { userId: userA },
+    });
+
+    const savedGlobal = (globalThis as { Temporal?: unknown }).Temporal;
+    delete (globalThis as { Temporal?: unknown }).Temporal;
+    try {
+      const second = await append(testDb.db, {
+        aggregateId,
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: first.version,
+        type: "task.updated",
+        payload: { title: "Buy oat milk" },
+        metadata: { userId: userA },
+      });
+      expect(second.version).toBe(2);
+      expect(second.createdAt).toBeDefined();
+    } finally {
+      if (savedGlobal === undefined) delete (globalThis as { Temporal?: unknown }).Temporal;
+      else (globalThis as { Temporal?: unknown }).Temporal = savedGlobal;
+    }
+  });
+
   test("subsequent appends increment version and are ordered", async () => {
     const aggregateId = uuid();
     const base = {
@@ -93,6 +126,143 @@ describe("event-store: append + load", () => {
   });
 });
 
+describe("event-store: idempotency-key conflict", () => {
+  test("second append with a reused idempotencyKey (new aggregate+version) throws IdempotentAppendConflictError", async () => {
+    const first = uuid();
+    const second = uuid();
+    const key = uuid();
+
+    await append(testDb.db, {
+      aggregateId: first,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "Orig" },
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+
+    // A retried command that re-runs after the Redis idempotency guard
+    // missed its window: different aggregate, fresh expectedVersion=0 — the
+    // aggregate-version unique index has nothing to say about this pair, so
+    // only the idempotency-key index catches the duplicate.
+    await expect(
+      append(testDb.db, {
+        aggregateId: second,
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 0,
+        type: "task.created",
+        payload: { title: "Retry" },
+        metadata: { userId: userA, idempotencyKey: key },
+      }),
+    ).rejects.toThrow(IdempotentAppendConflictError);
+
+    const events = await loadAggregate(testDb.db, second, tenantA);
+    expect(events).toHaveLength(0);
+  });
+
+  test("subsequent-event append (expectedVersion > 0) also enforces the idempotency key", async () => {
+    const aggregateId = uuid();
+    const key = uuid();
+
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "Orig" },
+      metadata: { userId: userA },
+    });
+
+    await append(testDb.db, {
+      aggregateId,
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 1,
+      type: "task.updated",
+      payload: { title: "V2" },
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+
+    // Retry of the v2 update: goes through insertSubsequentEventRow's raw
+    // INSERT ... SELECT ... WHERE EXISTS path, not insertFirstEvent — the
+    // idempotency index must catch it there too.
+    await expect(
+      append(testDb.db, {
+        aggregateId,
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 2,
+        type: "task.updated",
+        payload: { title: "V3-retry" },
+        metadata: { userId: userA, idempotencyKey: key },
+      }),
+    ).rejects.toThrow(IdempotentAppendConflictError);
+
+    const events = await loadAggregate(testDb.db, aggregateId, tenantA);
+    expect(events).toHaveLength(2);
+  });
+
+  test("same idempotencyKey on a different tenant does not conflict", async () => {
+    const key = uuid();
+
+    const a = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+    const b = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantB,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA, idempotencyKey: key },
+    });
+
+    expect(a.version).toBe(1);
+    expect(b.version).toBe(1);
+  });
+
+  test("omitting idempotencyKey allows unlimited appends, unchanged from before", async () => {
+    // Same tenant for both, unlike the different-aggregateId version this
+    // replaces — Postgres treats every NULL as distinct even in a plain
+    // unique index, so this does NOT exercise the partial index's `WHERE
+    // ... IS NOT NULL` clause specifically (that's provable only by a
+    // duplicate NON-null key, covered above). What this does pin: a fully-
+    // omitted key and an explicit `idempotencyKey: undefined` both serialize
+    // to a JSON-absent key (JSON.stringify drops undefined) and must behave
+    // identically, rather than one silently colliding on `"idempotencyKey":null`.
+    const omitted = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA },
+    });
+    const explicitUndefined = await append(testDb.db, {
+      aggregateId: uuid(),
+      aggregateType: "task",
+      tenantId: tenantA,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: {},
+      metadata: { userId: userA, idempotencyKey: undefined },
+    });
+    expect(omitted.version).toBe(1);
+    expect(explicitUndefined.version).toBe(1);
+  });
+});
+
 describe("event-store: optimistic concurrency", () => {
   test("wrong expectedVersion throws VersionConflictError (no write)", async () => {
     const aggregateId = uuid();
@@ -456,6 +626,37 @@ describe("event-store: loadAllEventsByType", () => {
     expect(all.map((e) => e.version)).toEqual([1, 2, 3, 4]);
     expect(all.map((e) => (e.payload as { v: number }).v)).toEqual([0, 1, 2, 3]);
   });
+
+  test("throws once rows exceed the given rowLimit", async () => {
+    for (let v = 0; v < 3; v++) {
+      await append(testDb.db, {
+        aggregateId: uuid(),
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 0,
+        type: "task.created",
+        payload: { v },
+        metadata: { userId: userA },
+      });
+    }
+    await expect(loadAllEventsByType(testDb.db, "task", 2)).rejects.toThrow(/exceeds 2 rows/);
+  });
+
+  test("does not throw when rows equal the given rowLimit", async () => {
+    for (let v = 0; v < 2; v++) {
+      await append(testDb.db, {
+        aggregateId: uuid(),
+        aggregateType: "task",
+        tenantId: tenantA,
+        expectedVersion: 0,
+        type: "task.created",
+        payload: { v },
+        metadata: { userId: userA },
+      });
+    }
+    const all = await loadAllEventsByType(testDb.db, "task", 2);
+    expect(all).toHaveLength(2);
+  });
 });
 
 describe("event-store: streamAllEventsByType (memory-bounded iteration)", () => {

package/src/event-store/__tests__/row-to-stored-event.test.ts

@@ -48,8 +48,8 @@ describe("toStoredEvent", () => {
   });
 
   test("Feld-Vollständigkeit: das Mapping deckt genau die StoredEvent-Keys ab", () => {
-    // Pin gegen versehentliches Weglassen eines Feldes im Mapping. Muss mit
-    // der StoredEvent-Definition (event-store.ts) synchron bleiben.
+    // Guards required fields staying in sync with StoredEvent (event-store.ts);
+    // optional fields consistently omitted on both sides must be added manually.
     const expectedKeys: ReadonlyArray<keyof StoredEvent> = [
       "id",
       "aggregateId",

package/src/event-store/__tests__/snapshot.integration.test.ts

@@ -242,3 +242,89 @@ describe("snapshot-store — loadAggregateWithSnapshot", () => {
     expect(archived.state.count).toBe(10);
   });
 });
+
+describe("snapshot-store — auto-snapshot policy (snapshotEvery)", () => {
+  test("first load persists a snapshot at the folded version; second load hits it", async () => {
+    const aggId = await seedAggregate(250);
+
+    const first = await loadAggregateWithSnapshot<CounterState>(
+      bun.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+      { snapshotEvery: 100 },
+    );
+    expect(first.snapshotHit).toBe(false);
+    expect(first.version).toBe(250);
+    expect(first.state).toEqual(await loadFullState(aggId));
+
+    const stored = await loadLatestSnapshot<CounterState>(bun.db, aggId, tenant);
+    expect(stored?.version).toBe(250);
+    expect(stored?.snapshotVersion).toBe(1);
+    expect(stored?.aggregateType).toBe("counter");
+
+    const second = await loadAggregateWithSnapshot<CounterState>(
+      bun.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+      { snapshotEvery: 100 },
+    );
+    expect(second.snapshotHit).toBe(true);
+    expect(second.state).toEqual(first.state);
+    expect(second.version).toBe(250);
+  });
+
+  test("fewer folded events than snapshotEvery → no snapshot written", async () => {
+    const aggId = await seedAggregate(10);
+    await loadAggregateWithSnapshot<CounterState>(bun.db, aggId, tenant, reducer, initial, {
+      snapshotEvery: 100,
+    });
+    expect(await loadLatestSnapshot(bun.db, aggId, tenant)).toBeNull();
+  });
+
+  test("snapshotVersion bump ignores the stored snapshot and restamps on auto-save", async () => {
+    const aggId = await seedAggregate(120);
+    await loadAggregateWithSnapshot<CounterState>(bun.db, aggId, tenant, reducer, initial, {
+      snapshotEvery: 100,
+    });
+
+    // Shape bump: the generation-1 snapshot must be ignored (full replay),
+    // and the auto-save restamps generation 2 at the same event version.
+    const bumped = await loadAggregateWithSnapshot<CounterState>(
+      bun.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+      { snapshotEvery: 100, snapshotVersion: 2 },
+    );
+    expect(bumped.snapshotHit).toBe(false);
+    expect(bumped.state).toEqual(await loadFullState(aggId));
+
+    const restamped = await loadLatestSnapshot<CounterState>(bun.db, aggId, tenant);
+    expect(restamped?.snapshotVersion).toBe(2);
+    expect(restamped?.version).toBe(120);
+
+    const third = await loadAggregateWithSnapshot<CounterState>(
+      bun.db,
+      aggId,
+      tenant,
+      reducer,
+      initial,
+      { snapshotEvery: 100, snapshotVersion: 2 },
+    );
+    expect(third.snapshotHit).toBe(true);
+  });
+
+  test("invalid snapshotEvery fails loud", async () => {
+    const aggId = await seedAggregate(1);
+    await expect(
+      loadAggregateWithSnapshot<CounterState>(bun.db, aggId, tenant, reducer, initial, {
+        snapshotEvery: 0,
+      }),
+    ).rejects.toThrow(/snapshotEvery/);
+  });
+});

package/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { Glob } from "bun";
+
+// getUnscopedAggregateStreamMaxVersion has no tenant filter — a caller can use
+// it to probe whether a foreign tenant's aggregate exists (see event-store.ts
+// SECURITY doc). Restricted to known seed/system-internal callers; extend
+// only for genuine new ones.
+const RESTRICTED_SYMBOLS = ["getUnscopedAggregateStreamMaxVersion"];
+
+const ALLOWED_FILES = new Set([
+  "packages/framework/src/event-store/event-store.ts",
+  "packages/framework/src/event-store/index.ts",
+  "packages/bundled-features/src/tenant/seeding.ts",
+  "packages/bundled-features/src/tier-engine/feature.ts",
+  "packages/framework/src/event-store/__tests__/unscoped-stream-primitives.guard.test.ts",
+]);
+
+const REPO_ROOT = `${import.meta.dir}/../../../../..`;
+
+describe("unscoped stream primitives — caller allowlist", () => {
+  test("only seed/system-internal paths reference the existence-oracle primitives", async () => {
+    // Widened from {framework,bundled-features} — the primitives are exported
+    // from the public @cosmicdrift/kumiko-framework/event-store barrel, so any
+    // package (server-runtime, dispatcher-live, headless, renderer-web, cli, ...)
+    // can import and call them; the allowlist must cover all of them, not just
+    // the two packages that happened to have callers when this guard was written.
+    const glob = new Glob("packages/*/src/**/*.ts");
+    const matches = new Set<string>();
+    for await (const relPath of glob.scan({ cwd: REPO_ROOT })) {
+      const content = await Bun.file(`${REPO_ROOT}/${relPath}`).text();
+      // Strip full-line `//` comments before scanning — a bare
+      // `content.includes(symbol)` also matches a symbol only mentioned in
+      // prose (e.g. explaining why a helper isn't needed), which would force
+      // an unrelated file into the allowlist for a reference that isn't an
+      // actual import or call.
+      const code = content
+        .split("\n")
+        .filter((line) => !line.trim().startsWith("//"))
+        .join("\n");
+      const referencesSymbol = (symbol: string): boolean =>
+        new RegExp(`\\b${symbol}\\s*\\(`).test(code) ||
+        // Covers both `import { symbol } from "..."` and a re-export barrel
+        // (`export { symbol } from "./event-store"`) — a new barrel that
+        // surfaces the oracle primitive must widen the allowlist too.
+        new RegExp(`\\b(import|export)\\b[^;]*\\b${symbol}\\b`).test(code);
+      if (RESTRICTED_SYMBOLS.some(referencesSymbol)) {
+        matches.add(relPath);
+      }
+    }
+
+    // Positive control — proves the scan actually ran and found the known
+    // caller, not just that it (silently) found nothing.
+    expect(matches.has("packages/bundled-features/src/tenant/seeding.ts")).toBe(true);
+
+    const offenders = [...matches].filter((relPath) => !ALLOWED_FILES.has(relPath));
+    expect(offenders).toEqual([]);
+  });
+});