@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/crypto/pii-field-encryption.ts

@@ -0,0 +1,248 @@
+// PII field encryption with per-subject DEKs (crypto-shredding, #724 phase C).
+// Same executor hook points as `encrypted: true`, but the key belongs to the
+// erase subject — kms.eraseKey(subject) makes every value unreadable at once.
+// Storage format is a sniffable string that fits existing text columns and
+// names its subject inline, so decrypt needs no schema change and no resolver:
+//   kumiko-pii:v2:<subjectKey>:<base64(iv|tag|ciphertext)>
+// v2 GCM-binds the ciphertext to `subjectKey|field` as AAD (#1263) — subject
+// selects the DEK, field stops a cut-and-paste between two fields of the
+// SAME subject (same DEK, so key selection alone can't catch that) from
+// decrypting silently. v1 (no AAD) stays decrypt-only for pre-#1263 rows;
+// every new write emits v2.
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import type { EntityDefinition } from "../engine/types/fields";
+import type { TenantId } from "../engine/types/identifiers";
+import {
+  isLocalKeyKmsAdapter,
+  KeyAlreadyExistsError,
+  KeyErasedError,
+  KeyNotFoundError,
+  type KmsAdapter,
+  type KmsContext,
+  type LocalKeyKmsAdapter,
+  type SubjectDek,
+  type SubjectId,
+  subjectIdFromKey,
+  subjectIdToKey,
+} from "./kms-adapter";
+import { resolveSubjectForField } from "./subject-resolver";
+
+// Spec value (crypto-shredding.md) — renderers show it verbatim.
+export const PII_ERASED_SENTINEL = "[[erased]]";
+
+const PII_CIPHERTEXT_PREFIX_V1 = "kumiko-pii:v1:";
+export const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+
+export function isPiiCiphertext(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    (value.startsWith(PII_CIPHERTEXT_PREFIX) || value.startsWith(PII_CIPHERTEXT_PREFIX_V1))
+  );
+}
+
+function buildAad(subject: SubjectId, field: string): Buffer {
+  return Buffer.from(`${subjectIdToKey(subject)}|${field}`, "utf8");
+}
+
+function encryptValue(
+  subject: SubjectId,
+  dek: SubjectDek,
+  plaintext: string,
+  field: string,
+): string {
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv("aes-256-gcm", dek, iv);
+  cipher.setAAD(buildAad(subject, field));
+  const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const blob = Buffer.concat([iv, cipher.getAuthTag(), ciphertext]);
+  return `${PII_CIPHERTEXT_PREFIX}${subjectIdToKey(subject)}:${blob.toString("base64")}`;
+}
+
+function parseCiphertext(value: string): { subject: SubjectId; blob: Buffer; hasAad: boolean } {
+  const hasAad = value.startsWith(PII_CIPHERTEXT_PREFIX);
+  const prefix = hasAad ? PII_CIPHERTEXT_PREFIX : PII_CIPHERTEXT_PREFIX_V1;
+  const rest = value.slice(prefix.length);
+  // subjectKey itself contains ":" ("user:<id>") — base64 never does, so the
+  // last ":" is always the key/blob separator.
+  const sep = rest.lastIndexOf(":");
+  if (sep === -1) throw new Error(`Malformed PII ciphertext (no subject/blob separator)`);
+  return {
+    subject: subjectIdFromKey(rest.slice(0, sep)),
+    blob: Buffer.from(rest.slice(sep + 1), "base64"),
+    hasAad,
+  };
+}
+
+function decryptValue(
+  dek: SubjectDek,
+  blob: Buffer,
+  subject: SubjectId,
+  field: string,
+  hasAad: boolean,
+): string {
+  const iv = blob.subarray(0, IV_LENGTH);
+  const tag = blob.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+  const ciphertext = blob.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+  const decipher = createDecipheriv("aes-256-gcm", dek, iv);
+  if (hasAad) decipher.setAAD(buildAad(subject, field));
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}
+
+// First write to a PII field of a new subject creates the key implicitly
+// (user-signup / tenant-create need no extra hook). The AlreadyExists catch
+// covers the concurrent-first-write race; a tombstoned subject re-throws
+// KeyErasedError from the final getKey — writes to a forgotten subject fail.
+async function getOrCreateDek(
+  kms: LocalKeyKmsAdapter,
+  subject: SubjectId,
+  ctx: KmsContext,
+): Promise<SubjectDek> {
+  try {
+    return await kms.getKey(subject, ctx);
+  } catch (e) {
+    if (!(e instanceof KeyNotFoundError)) throw e;
+  }
+  try {
+    await kms.createKey(subject, ctx);
+  } catch (e) {
+    if (!(e instanceof KeyAlreadyExistsError)) throw e;
+  }
+  return kms.getKey(subject, ctx);
+}
+
+// Single-value encrypt for callers that resolve the subject themselves
+// (event-pii catalog, backfill). Ciphertext/sentinel inputs pass through —
+// idempotent like the field-map variant. `field` names the value's storage
+// slot (payload field / config key) — part of the AAD, so it must match the
+// `field` passed to decryptPiiValueForSubject for the same value.
+export async function encryptPiiValueForSubject(
+  kms: LocalKeyKmsAdapter,
+  subject: SubjectId,
+  value: string,
+  kmsCtx: KmsContext,
+  field: string,
+): Promise<string> {
+  if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) return value;
+  const dek = await getOrCreateDek(kms, subject, kmsCtx);
+  return encryptValue(subject, dek, value, field);
+}
+
+// Single-value decrypt for callers that don't have an entity/field-map to
+// pass through decryptPiiFieldValues (config values). The subject lives
+// inside the ciphertext itself, so no subject/scope resolution is needed
+// on this side — only the encrypt direction has to pick one. `field` must
+// match the one used at encrypt time (AAD) or decrypt fails loud.
+export async function decryptPiiValueForSubject(
+  kms: LocalKeyKmsAdapter,
+  value: string,
+  kmsCtx: KmsContext,
+  field: string,
+): Promise<string> {
+  if (!isPiiCiphertext(value)) return value;
+  const { subject, blob, hasAad } = parseCiphertext(value);
+  try {
+    return decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, field, hasAad);
+  } catch (e) {
+    if (!(e instanceof KeyErasedError)) throw e;
+    return PII_ERASED_SENTINEL;
+  }
+}
+
+export interface EncryptPiiOptions {
+  readonly onlyKeys?: Iterable<string>;
+  // Write-time tenant for tenantOwned fields on rows without a tenantId column.
+  readonly tenantId?: TenantId;
+  // Row to resolve subjects from when `row` is a partial (update changes may
+  // carry a pii field without its ownerField — the merged row still has it).
+  readonly subjectSource?: Record<string, unknown>;
+}
+
+export async function encryptPiiFieldValues(
+  row: Record<string, unknown>,
+  entity: EntityDefinition,
+  piiFields: readonly string[],
+  kms: LocalKeyKmsAdapter,
+  kmsCtx: KmsContext,
+  opts: EncryptPiiOptions = {},
+): Promise<Record<string, unknown>> {
+  if (piiFields.length === 0) return row;
+  const only = opts.onlyKeys ? new Set(opts.onlyKeys) : null;
+  const subjectSource = opts.subjectSource ?? row;
+  const out = { ...row };
+  for (const name of piiFields) {
+    if (only && !only.has(name)) continue;
+    if (!(name in out)) continue;
+    const value = out[name];
+    if (value === null || value === undefined) continue;
+    // Re-encrypt paths (update previous, detail cache) may see values that
+    // are already ciphertext or the erased sentinel — both stay as-is.
+    if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) continue;
+    if (typeof value !== "string") {
+      throw new Error(`PII field "${name}" must be a string, got ${typeof value}`);
+    }
+    const subject = resolveSubjectForField(entity, name, subjectSource, {
+      ...(opts.tenantId !== undefined && { tenantId: opts.tenantId }),
+    });
+    // skip: collectPiiSubjectFields only yields annotated fields — null is unreachable, kept as a type guard
+    if (subject === null) continue;
+    const dek = await getOrCreateDek(kms, subject, kmsCtx);
+    out[name] = encryptValue(subject, dek, value, name);
+  }
+  return out;
+}
+
+export async function decryptPiiFieldValues(
+  row: Record<string, unknown>,
+  piiFields: readonly string[],
+  kms: LocalKeyKmsAdapter,
+  kmsCtx: KmsContext,
+): Promise<Record<string, unknown>> {
+  if (piiFields.length === 0) return row;
+  const out = { ...row };
+  for (const name of piiFields) {
+    const value = out[name];
+    // Pre-engine plaintext rows pass through unchanged (mixed-state reads
+    // work during rollout; backfill is tracked in kumiko-framework#799).
+    if (!isPiiCiphertext(value)) continue;
+    const { subject, blob, hasAad } = parseCiphertext(value);
+    try {
+      out[name] = decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, name, hasAad);
+    } catch (e) {
+      // KeyNotFound deliberately propagates: ciphertext without a key row
+      // means the key store is wrong (not shredded) — fail loud.
+      if (!(e instanceof KeyErasedError)) throw e;
+      out[name] = PII_ERASED_SENTINEL;
+    }
+  }
+  return out;
+}
+
+// Boot-injected app-wide subject KMS, mirroring configureEntityFieldEncryption:
+// run{Prod,Dev}App call configurePiiSubjectKms once; executors resolve lazily.
+// Absent adapter = engine off (pii fields stay plaintext, pre-phase-C
+// behavior) — the hard boot gate arrives with the prod-grade PgKmsAdapter
+// (phase E); until then no production deployment can satisfy it.
+let injectedKms: LocalKeyKmsAdapter | undefined;
+
+export function configurePiiSubjectKms(adapter: KmsAdapter | undefined): void {
+  if (adapter !== undefined && !isLocalKeyKmsAdapter(adapter)) {
+    throw new Error(
+      "PII field encryption requires a local-key KMS adapter — remote-crypto " +
+        "(Vault transit) support lands with the BYOK adapter.",
+    );
+  }
+  injectedKms = adapter;
+}
+
+export function configuredPiiSubjectKms(): LocalKeyKmsAdapter | undefined {
+  return injectedKms;
+}
+
+/** @internal test-only */
+export function resetPiiSubjectKmsForTests(): void {
+  injectedKms = undefined;
+}

package/src/crypto/request-kms-cache.ts

@@ -0,0 +1,38 @@
+import type {
+  KmsContext,
+  LocalKeyKmsAdapter,
+  SubjectDek,
+  SubjectId,
+  SubjectKey,
+} from "./kms-adapter";
+import { subjectIdToKey } from "./kms-adapter";
+
+// Per-request DEK cache: a list rendering 50 comments of one author does one
+// adapter round-trip, not 50. Only meaningful for local-key adapters —
+// remote-crypto backends never release keys, every call is a round-trip.
+export interface RequestKmsCache {
+  getKey(subject: SubjectId, ctx: KmsContext): Promise<SubjectDek>;
+  /** Drops one subject's cached DEK — called when its key is shredded mid-request. */
+  invalidate(subject: SubjectId): void;
+  clear(): void;
+}
+
+export function createRequestKmsCache(adapter: LocalKeyKmsAdapter): RequestKmsCache {
+  const cache = new Map<SubjectKey, SubjectDek>();
+  return {
+    async getKey(subject, ctx) {
+      const subjectKey = subjectIdToKey(subject);
+      const hit = cache.get(subjectKey);
+      if (hit !== undefined) return hit;
+      const dek = await adapter.getKey(subject, ctx);
+      cache.set(subjectKey, dek);
+      return dek;
+    },
+    invalidate(subject) {
+      cache.delete(subjectIdToKey(subject));
+    },
+    clear() {
+      cache.clear();
+    },
+  };
+}

package/src/crypto/subject-resolver.ts

@@ -0,0 +1,91 @@
+import type { EntityDefinition } from "../engine/types/fields";
+import type { TenantId } from "../engine/types/identifiers";
+import type { SubjectId } from "./kms-adapter";
+
+// Thrown when a field IS pii-annotated but the row can't name its subject —
+// that must surface as an error, not fall back to plaintext.
+export class SubjectResolutionError extends Error {
+  constructor(
+    public readonly fieldName: string,
+    reason: string,
+  ) {
+    super(`Cannot resolve PII subject for field "${fieldName}": ${reason}`);
+    this.name = "SubjectResolutionError";
+  }
+}
+
+export interface ResolveSubjectOptions {
+  // Write-time tenant scope — consulted for tenantOwned fields when the row
+  // itself carries no tenantId column.
+  readonly tenantId?: TenantId;
+}
+
+function nonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Maps a pii-annotated field to the subject whose key encrypts it.
+ * Returns null for fields without any PII annotation (stored plaintext).
+ *
+ * Precedence for multi-annotated fields mirrors the erase triggers:
+ * userOwned (user-forget) > tenantOwned (tenant-destroy) > pii (self).
+ */
+export function resolveSubjectForField(
+  entity: EntityDefinition,
+  fieldName: string,
+  row: Record<string, unknown>,
+  opts: ResolveSubjectOptions = {},
+): SubjectId | null {
+  const field = entity.fields[fieldName];
+  if (!field) throw new SubjectResolutionError(fieldName, "field is not defined on the entity");
+
+  if ("userOwned" in field && field.userOwned !== undefined) {
+    const ownerField = field.userOwned.ownerField;
+    const userId = nonEmptyString(row[ownerField]);
+    if (userId === null) {
+      throw new SubjectResolutionError(
+        fieldName,
+        `owner field "${ownerField}" is empty on the row`,
+      );
+    }
+    return { kind: "user", userId };
+  }
+
+  if ("tenantOwned" in field && field.tenantOwned === true) {
+    const tenantId = nonEmptyString(row["tenantId"]) ?? opts.tenantId;
+    if (tenantId === undefined) {
+      throw new SubjectResolutionError(
+        fieldName,
+        "row has no tenantId column and no write-time tenantId was provided",
+      );
+    }
+    return { kind: "tenant", tenantId };
+  }
+
+  if ("pii" in field && field.pii === true) {
+    // pii: true = the entity itself is the subject (user.email belongs to
+    // that user row). Serial ids are stringified — subject keys are text.
+    const id = row["id"];
+    const userId = nonEmptyString(id) ?? (typeof id === "number" ? String(id) : null);
+    if (userId === null) {
+      throw new SubjectResolutionError(fieldName, "row has no id to use as the pii self-subject");
+    }
+    return { kind: "user", userId };
+  }
+
+  return null;
+}
+
+// The field names an encrypt engine must process for an entity — precomputed
+// once at executor build time, like the sensitiveFields set.
+export function collectPiiSubjectFields(entity: EntityDefinition): readonly string[] {
+  return Object.entries(entity.fields)
+    .filter(
+      ([, field]) =>
+        ("userOwned" in field && field.userOwned !== undefined) ||
+        ("tenantOwned" in field && field.tenantOwned === true) ||
+        ("pii" in field && field.pii === true),
+    )
+    .map(([name]) => name);
+}

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

@@ -0,0 +1,191 @@
+// Runtime guard #722: before the rebuild swaps the shadow over the live table,
+// abort if a live row has NO event in the projection's source streams — a row
+// no replay can reconstruct (#498 ghost, direct-inserted without a .created
+// event), which the swap would silently drop.
+//
+// The guard is deliberately narrow (event EXISTENCE only, not a column diff):
+// the framework legitimately makes live diverge from a fresh replay in shipped
+// ways (blind-index erase→NULL, sensitive-strip, archived-stream wipe, the #494
+// backfill flow). Those rows all HAVE an event, so they are not ghosts and the
+// guard leaves them alone — proven by the "direct column-write" test below.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+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 { rebuildProjection } from "../../pipeline";
+import { createProjectionStateTable } from "../../pipeline/projection-state";
+import { TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb, type TenantDb } from "../tenant-db";
+
+const userEntity = createEntity({
+  table: "read_unreachable_users",
+  fields: {
+    email: createTextField({ required: true }),
+    firstName: createTextField(),
+    isEnabled: createBooleanField({ default: true }),
+  },
+  softDelete: true,
+});
+
+const userFeature = defineFeature("unreachabletest", (r) => {
+  r.entity("user", userEntity);
+});
+
+const userTable = buildEntityTable("user", userEntity);
+const projectionName = "unreachabletest:projection:user-entity";
+const registry = createRegistry([userFeature]);
+
+let testDb: BunTestDb;
+let tdb: TenantDb;
+const adminUser = TestUsers.admin;
+
+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);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, kumiko_archived_streams, read_unreachable_users, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+});
+
+async function snapshotTable(): Promise<readonly Record<string, unknown>[]> {
+  const rows = await selectMany(
+    testDb.db,
+    userTable,
+    {},
+    { orderBy: { col: "id", direction: "asc" } },
+  );
+  return rows as readonly Record<string, unknown>[];
+}
+
+describe("assert-no-unreachable-live-rows / #722 ghost-row guard", () => {
+  test("clean executor-only projection rebuilds without firing the guard", async () => {
+    const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+    await crud.create({ email: "a@test.de", firstName: "Alice" }, adminUser, tdb);
+    await crud.create({ email: "b@test.de", firstName: "Bob" }, adminUser, tdb);
+    const before = await snapshotTable();
+
+    const result = await rebuildProjection(projectionName, { db: testDb.db, registry });
+
+    expect(result.eventsProcessed).toBe(2);
+    expect(result.columnDriftCount).toBe(0);
+    expect(await snapshotTable()).toEqual(before);
+  });
+
+  test("ghost row (no backing event) → swap aborts, live untouched", async () => {
+    const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+    const a = await crud.create({ email: "a@test.de", firstName: "Alice" }, adminUser, tdb);
+    if (!a.isSuccess) throw new Error("setup failed");
+
+    // Drift: clone the event-backed row into a second id WITHOUT appending an
+    // event — the #498 ghost. No replay can ever reconstruct it.
+    const [liveRow] = await selectMany(testDb.db, userTable, { id: a.data.id as string });
+    if (!liveRow) throw new Error("live row missing");
+    const ghostId = crypto.randomUUID();
+    // Deliberately bypass the EXECUTOR_ONLY brand: the whole point is to write
+    // the entity table WITHOUT going through the executor — the production bug
+    // the guard defends against.
+    const writable = userTable as unknown as Parameters<typeof insertOne>[1];
+    await insertOne(tdb, writable, { ...liveRow, id: ghostId, email: "ghost@test.de" });
+    expect(await snapshotTable()).toHaveLength(2);
+
+    await expect(rebuildProjection(projectionName, { db: testDb.db, registry })).rejects.toThrow(
+      // #915: exact count below the truncation limit, no misleading "+" suffix.
+      /^projection-rebuild ".*": 1 live rows in ".*" have no\s+event in the projection's source streams/,
+    );
+
+    // Swap never ran: both rows — including the ghost — survive.
+    const after = await snapshotTable();
+    expect(after).toHaveLength(2);
+    expect(after.map((r) => r["id"])).toContain(ghostId);
+  });
+
+  test("direct column-write on an event-backed row does NOT trip the guard", async () => {
+    // The row has a .created event, so it is not a ghost. Its column state was
+    // direct-written without an event (the #494 / blind-index-erase class) — the
+    // guard is event-existence-only and leaves it alone; the replay overwrites
+    // the column from the event, which is the intended, shipped behavior.
+    const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+    const a = await crud.create({ email: "a@test.de", firstName: "Alice" }, adminUser, tdb);
+    if (!a.isSuccess) throw new Error("setup failed");
+
+    await asRawClient(testDb.db).unsafe(
+      `UPDATE read_unreachable_users SET first_name = 'DirectWrite' WHERE id = $1`,
+      [a.data.id],
+    );
+
+    // No throw — the row is event-backed. Rebuild replays the create event.
+    // #916: the direct write IS reported as column drift (non-blocking) —
+    // this is the exact #494 healing case the guard leaves to replay.
+    const result = await rebuildProjection(projectionName, { db: testDb.db, registry });
+    expect(result.columnDriftCount).toBe(1);
+
+    const [rebuilt] = await selectMany(testDb.db, userTable, { id: a.data.id as string });
+    expect(rebuilt?.["email"]).toBe("a@test.de");
+    // The direct write is overwritten by the replay — deliberately allowed.
+    expect(rebuilt?.["firstName"]).toBe("Alice");
+  });
+
+  test("columnDriftCount reports the TRUE total, not capped at the 20-row sample limit", async () => {
+    const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+    const created = await Promise.all(
+      Array.from({ length: 21 }, (_, i) =>
+        crud.create({ email: `u${i}@test.de`, firstName: `Name${i}` }, adminUser, tdb),
+      ),
+    );
+    for (const c of created) {
+      if (!c.isSuccess) throw new Error("setup failed");
+      await asRawClient(testDb.db).unsafe(
+        `UPDATE read_unreachable_users SET first_name = 'DirectWrite' WHERE id = $1`,
+        [c.data.id],
+      );
+    }
+
+    const result = await rebuildProjection(projectionName, { db: testDb.db, registry });
+
+    // #916: the sample query is LIMITed to 20 rows, but the count must reflect
+    // all 21 — a min(actual, 20) would silently understate severity to ops.
+    expect(result.columnDriftCount).toBe(21);
+  });
+
+  test("archived stream (fw#832 tombstone) does NOT trip the guard", async () => {
+    // archiveStream never deletes the .created event — projection rebuild
+    // deliberately excludes archived streams from replay (fw#832, see
+    // projection-rebuild.ts), so the row is wiped from live on swap. The
+    // guard only checks event EXISTENCE, not replay-inclusion, so it must
+    // not fire — this is the shipped tombstone behavior, not drift.
+    const crud = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+    const a = await crud.create({ email: "a@test.de", firstName: "Alice" }, adminUser, tdb);
+    if (!a.isSuccess) throw new Error("setup failed");
+
+    await archiveStream(testDb.db, {
+      tenantId: adminUser.tenantId,
+      aggregateId: a.data.id as string,
+      aggregateType: "user",
+      archivedBy: adminUser.id,
+    });
+
+    // No throw — the row is event-backed despite being archived.
+    const result = await rebuildProjection(projectionName, { db: testDb.db, registry });
+
+    expect(result.eventsProcessed).toBe(0);
+    expect(await snapshotTable()).toHaveLength(0);
+  });
+});