@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/db/queries/backfill-pii.ts

@@ -0,0 +1,277 @@
+// One-time backfill for pre-KMS plaintext PII in kumiko_events (#799).
+//
+// Crypto-shredding (#724/#818) only covers NEW writes — events appended
+// before a KMS was configured still carry plaintext (user.created email,
+// delivery attempt recipientAddress, job payloads). This tool re-encrypts
+// them in place, per field, under the owning subject's DEK:
+//
+//   - entity lifecycle events (<entity>.created/updated/deleted/forgotten/
+//     restored) for every entity with PII subject annotations
+//   - custom events from the event-PII catalog (r.defineEvent piiFields)
+//
+// Already-forgotten subjects must NOT get a fresh key minted for their old
+// plaintext — three erased-detection layers write [[erased]] instead:
+//   1. KeyErasedError from the KMS (subject forgotten in the KMS era)
+//   2. the event's own aggregate has a *.forgotten event (pre-KMS forget)
+//   3. the resolved user subject's id has a *.forgotten event (custom
+//      events referencing a pre-KMS-forgotten user)
+//
+// Idempotent: ciphertext and sentinel values pass through untouched — a
+// second run reports 0 updates. One failing event does not abort the run;
+// failures are collected and reported (fail-loud at the caller).
+//
+// Snapshots of touched aggregates are dropped (they may cache plaintext);
+// the next snapshotting load recreates them. AFTER a run, rebuild the
+// affected projections — applyEntityEvent materializes ciphertext AND the
+// blind-index columns, which keeps equality lookups (login by email) alive.
+
+import { asRawClient } from "../../bun-db";
+import { configuredEventPiiCatalog } from "../../crypto/event-pii";
+import type { KmsContext, LocalKeyKmsAdapter, SubjectId } from "../../crypto/kms-adapter";
+import { KeyErasedError } from "../../crypto/kms-adapter";
+import {
+  configuredPiiSubjectKms,
+  encryptPiiValueForSubject,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+} from "../../crypto/pii-field-encryption";
+import { collectPiiSubjectFields, resolveSubjectForField } from "../../crypto/subject-resolver";
+import type { EntityDefinition, Registry, TenantId } from "../../engine/types";
+import type { DbRunner } from "../connection";
+
+const LIFECYCLE_VERBS = ["created", "updated", "deleted", "restored", "forgotten"] as const;
+
+export type PiiBackfillFailure = {
+  readonly eventId: string;
+  readonly reason: string;
+};
+
+export type PiiBackfillResult = {
+  readonly scannedEvents: number;
+  readonly updatedEvents: number;
+  readonly encryptedFields: number;
+  readonly erasedFields: number;
+  readonly deletedSnapshots: number;
+  readonly failures: readonly PiiBackfillFailure[];
+};
+
+export type PiiBackfillOptions = {
+  readonly batchSize?: number;
+  // Scan + count only, write nothing.
+  readonly dryRun?: boolean;
+};
+
+type EventRow = {
+  readonly id: bigint | string;
+  readonly aggregate_id: string;
+  readonly aggregate_type: string;
+  readonly tenant_id: string;
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+};
+
+type FieldOutcome = "unchanged" | "encrypted" | "erased";
+
+export async function backfillEventPiiEncryption(
+  db: DbRunner,
+  registry: Registry,
+  options: PiiBackfillOptions = {},
+): Promise<PiiBackfillResult> {
+  const kms = configuredPiiSubjectKms();
+  if (!kms) {
+    throw new Error(
+      "backfillEventPiiEncryption requires a configured subject KMS — boot with " +
+        "runProdApp({ kms }) / configurePiiSubjectKms(adapter) before running the backfill.",
+    );
+  }
+  const batchSize = options.batchSize ?? 500;
+  const raw = asRawClient(db);
+  const kmsCtx: KmsContext = { requestId: "pii-backfill" };
+
+  const entityTargets = new Map<
+    string,
+    { readonly entity: EntityDefinition; readonly piiFields: readonly string[] }
+  >();
+  for (const [name, entity] of registry.getAllEntities()) {
+    const piiFields = collectPiiSubjectFields(entity);
+    if (piiFields.length > 0) entityTargets.set(name, { entity, piiFields });
+  }
+  const eventCatalog = configuredEventPiiCatalog();
+
+  const aggregateTypes = [...entityTargets.keys()];
+  const catalogTypes = [...eventCatalog.keys()];
+  const result = {
+    scannedEvents: 0,
+    updatedEvents: 0,
+    encryptedFields: 0,
+    erasedFields: 0,
+    deletedSnapshots: 0,
+    failures: [] as PiiBackfillFailure[],
+  };
+  if (aggregateTypes.length === 0 && catalogTypes.length === 0) return result;
+
+  // Pre-KMS forgets left no key tombstone — the *.forgotten event on the
+  // stream is the only durable marker. Collect once; aggregate_id doubles
+  // as the user id for user-subject lookups.
+  const forgottenRows = (await raw.unsafe(
+    `SELECT DISTINCT "aggregate_id" FROM "kumiko_events" WHERE "type" LIKE '%.forgotten'`,
+  )) as ReadonlyArray<{ aggregate_id: string }>;
+  const forgottenAggregates = new Set(forgottenRows.map((r) => r.aggregate_id));
+
+  const touchedAggregates = new Set<string>();
+  let cursor = "0";
+
+  for (;;) {
+    const rows = (await raw.unsafe(
+      `SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
+         FROM "kumiko_events"
+        WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" > $3::bigint
+        ORDER BY "id" ASC
+        LIMIT $4`,
+      [aggregateTypes, catalogTypes, cursor, batchSize],
+    )) as ReadonlyArray<EventRow>;
+    if (rows.length === 0) break;
+
+    for (const row of rows) {
+      result.scannedEvents++;
+      try {
+        const outcome = await transformEvent(row);
+        if (outcome === null) continue;
+        result.encryptedFields += outcome.encrypted;
+        result.erasedFields += outcome.erased;
+        if (!options.dryRun) {
+          await raw.unsafe(`UPDATE "kumiko_events" SET "payload" = $1::jsonb WHERE "id" = $2`, [
+            JSON.stringify(outcome.payload),
+            row.id,
+          ]);
+        }
+        result.updatedEvents++;
+        touchedAggregates.add(row.aggregate_id);
+      } catch (e) {
+        result.failures.push({
+          eventId: String(row.id),
+          reason: e instanceof Error ? e.message : String(e),
+        });
+      }
+    }
+    const last = rows[rows.length - 1];
+    if (last === undefined) break;
+    cursor = String(last.id);
+  }
+
+  // Snapshots may cache the plaintext state of touched aggregates.
+  if (!options.dryRun && touchedAggregates.size > 0) {
+    const deleted = (await raw.unsafe(
+      `DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = ANY($1::uuid[]) RETURNING "aggregate_id"`,
+      [[...touchedAggregates]],
+    )) as ReadonlyArray<unknown>;
+    result.deletedSnapshots = deleted.length;
+  }
+
+  return result;
+
+  async function transformEvent(
+    row: EventRow,
+  ): Promise<{ payload: Record<string, unknown>; encrypted: number; erased: number } | null> {
+    const counters = { encrypted: 0, erased: 0 };
+    const payload = structuredClone(row.payload);
+
+    const catalogFields = eventCatalog.get(row.type);
+    if (catalogFields) {
+      for (const [field, spec] of Object.entries(catalogFields)) {
+        const subjectId = payload[spec.subjectField];
+        if (typeof subjectId !== "string" || subjectId.length === 0) continue;
+        const outcome = await encryptField(payload, field, { kind: "user", userId: subjectId });
+        bump(outcome);
+      }
+    } else {
+      const target = entityTargets.get(row.aggregate_type);
+      if (!target || !isLifecycleEventOf(row.type, row.aggregate_type)) return null;
+      const sections = lifecycleSections(payload);
+      for (const section of sections) {
+        // Update-changes may carry a pii field without its owner field —
+        // resolve subjects from the merged view; aggregate_id backs the
+        // self-subject when a section lacks the id column.
+        const subjectSource: Record<string, unknown> = {
+          id: row.aggregate_id,
+          ...Object.assign({}, ...sections),
+          ...section,
+        };
+        for (const field of target.piiFields) {
+          const subject = resolveSubjectForField(target.entity, field, subjectSource, {
+            // @cast-boundary db-read — tenant_id column is the branded TenantId
+            tenantId: row.tenant_id as TenantId,
+          });
+          if (subject === null) continue;
+          const outcome = await encryptField(section, field, subject);
+          bump(outcome);
+        }
+      }
+    }
+
+    if (counters.encrypted === 0 && counters.erased === 0) return null;
+    return { payload, ...counters };
+
+    function bump(outcome: FieldOutcome): void {
+      if (outcome === "encrypted") counters.encrypted++;
+      if (outcome === "erased") counters.erased++;
+    }
+
+    async function encryptField(
+      section: Record<string, unknown>,
+      field: string,
+      subject: SubjectId,
+    ): Promise<FieldOutcome> {
+      const value = section[field];
+      if (value === null || value === undefined) return "unchanged";
+      if (typeof value !== "string") return "unchanged";
+      if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL) return "unchanged";
+      if (isForgottenSubject(subject, row.aggregate_id)) {
+        section[field] = PII_ERASED_SENTINEL;
+        return "erased";
+      }
+      try {
+        section[field] = await encryptPiiValueForSubject(
+          kms as LocalKeyKmsAdapter,
+          subject,
+          value,
+          kmsCtx,
+          field,
+        );
+        return "encrypted";
+      } catch (e) {
+        if (e instanceof KeyErasedError) {
+          section[field] = PII_ERASED_SENTINEL;
+          return "erased";
+        }
+        throw e;
+      }
+    }
+  }
+
+  function isForgottenSubject(subject: SubjectId, aggregateId: string): boolean {
+    if (forgottenAggregates.has(aggregateId)) return true;
+    return subject.kind === "user" && forgottenAggregates.has(subject.userId);
+  }
+}
+
+function isLifecycleEventOf(eventType: string, aggregateType: string): boolean {
+  if (!eventType.startsWith(`${aggregateType}.`)) return false;
+  const verb = eventType.slice(aggregateType.length + 1);
+  return (LIFECYCLE_VERBS as readonly string[]).includes(verb);
+}
+
+// created events carry the fields flat; updated carries { changes, previous };
+// deleted/forgotten/restored carry { previous }. Returned sections are the
+// mutable objects INSIDE the payload clone — encryptField writes in place.
+function lifecycleSections(payload: Record<string, unknown>): Record<string, unknown>[] {
+  const sections: Record<string, unknown>[] = [];
+  if (isRecord(payload["changes"])) sections.push(payload["changes"]);
+  if (isRecord(payload["previous"])) sections.push(payload["previous"]);
+  if (sections.length === 0) sections.push(payload);
+  return sections;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/db/queries/ddl.ts

@@ -0,0 +1,45 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+import { quoteTableIdent } from "./table-ops";
+
+// Generic DDL helpers used on the prod-boot path (stack/table-helpers.ts's
+// unsafePushTables, event-consumer-state.ts's multi-instance backfill) —
+// split out of queries/test-stack.ts so a prod-boot import doesn't point at
+// a module named for test-only concerns (truncate/create/drop-database).
+
+export async function executeDdlStatement(db: AnyDb, sqlText: string): Promise<void> {
+  await asRawClient(db).unsafe(sqlText);
+}
+
+export async function alterTableAddColumn(
+  db: AnyDb,
+  tableName: string,
+  columnName: string,
+  columnType: string,
+  defaultClause: string,
+  notNull: string,
+  // table-helpers.ts's unmanaged-table sync relies on the plain form
+  // throwing when a column already exists with a different shape than
+  // EntityTableMeta expects — that's how it surfaces drift. Callers that
+  // just need an idempotent, race-safe backfill (e.g. event-consumer-state's
+  // multi-instance boot path, #1362) opt in explicitly.
+  ifNotExists = false,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `ALTER TABLE ${quoteTableIdent(tableName)} ADD COLUMN ${ifNotExists ? "IF NOT EXISTS " : ""}${quoteTableIdent(columnName)} ${columnType}${defaultClause}${notNull}`,
+  );
+}
+
+export async function createIndexIfNotExists(
+  db: AnyDb,
+  indexKind: "UNIQUE INDEX" | "INDEX",
+  indexName: string,
+  tableName: string,
+  columnList: string,
+  whereSql?: string,
+): Promise<void> {
+  const where = whereSql !== undefined ? ` WHERE ${whereSql}` : "";
+  await asRawClient(db).unsafe(
+    `CREATE ${indexKind} IF NOT EXISTS ${quoteTableIdent(indexName)} ON ${quoteTableIdent(tableName)} (${columnList})${where}`,
+  );
+}

package/src/db/queries/event-consumer.ts

@@ -47,6 +47,7 @@ export type ConsumerDeliveryOutcome = {
   readonly attempts: number;
   readonly lastError: string | null;
   readonly deadLettered: boolean;
+  readonly processed: number;
 };
 
 export async function updateConsumerDeliveryOutcome(
@@ -55,19 +56,26 @@ export async function updateConsumerDeliveryOutcome(
   instanceId: string,
   outcome: ConsumerDeliveryOutcome,
 ): Promise<void> {
+  // Advancing the cursor proves this pass wasn't poison — reset the re-arm
+  // budget so an unrelated failure down the line gets its own fresh 3
+  // chances instead of inheriting a partially-spent counter from a past,
+  // already-resolved outage.
+  const resetRearmCount = outcome.processed > 0;
   await asRawClient(db).unsafe(
     `UPDATE "kumiko_event_consumers" SET
        "last_processed_event_id" = $1,
        "attempts" = $2,
        "status" = $3,
        "last_error" = $4,
+       "rearm_count" = CASE WHEN $5 THEN 0 ELSE "rearm_count" END,
        "updated_at" = now()
-     WHERE "name" = $5 AND "instance_id" = $6`,
+     WHERE "name" = $6 AND "instance_id" = $7`,
     [
       outcome.cursor,
       outcome.attempts,
       outcome.deadLettered ? "dead" : "idle",
       outcome.lastError,
+      resetRearmCount,
       name,
       instanceId,
     ],
@@ -81,7 +89,7 @@ export async function updateConsumerStatusReturning(
   status: "idle" | "disabled",
 ): Promise<Record<string, unknown> | undefined> {
   const rows = (await asRawClient(db).unsafe(
-    `UPDATE "kumiko_event_consumers" SET "status" = $1, "attempts" = 0, "last_error" = NULL, "updated_at" = now()
+    `UPDATE "kumiko_event_consumers" SET "status" = $1, "attempts" = 0, "last_error" = NULL, "rearm_count" = 0, "updated_at" = now()
      WHERE "name" = $2 AND "instance_id" = $3
      RETURNING *`,
     [status, name, instanceId],
@@ -101,6 +109,7 @@ export async function advanceConsumerPastEventReturning(
        "status" = 'idle',
        "attempts" = 0,
        "last_error" = NULL,
+       "rearm_count" = 0,
        "updated_at" = now()
      WHERE "name" = $2 AND "instance_id" = $3
      RETURNING *`,
@@ -168,3 +177,27 @@ export async function markConsumerRebuildFailed(
     [errorMessage, name, instanceId],
   );
 }
+
+// Auto-revive a dead consumer once its cooldown has elapsed (called from
+// acquireConsumerState — not an ops action, so no "requireConsumerRow"
+// precondition like restartConsumer/enableConsumer). Increments rearm_count
+// so the caller can enforce a lifetime cap on automatic revivals; manual
+// restartConsumer()/enableConsumer() reset it back to 0.
+export async function rearmDeadConsumer(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+): Promise<Record<string, unknown> | undefined> {
+  const rows = (await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "rearm_count" = "rearm_count" + 1,
+       "updated_at" = now()
+     WHERE "name" = $1 AND "instance_id" = $2
+     RETURNING *`,
+    [name, instanceId],
+  )) as ReadonlyArray<Record<string, unknown>>;
+  return rows[0];
+}

package/src/db/queries/event-store.ts

@@ -1,3 +1,9 @@
+import {
+  constraintOf,
+  isLockNotAvailable,
+  isTableAlreadyExists,
+  isUniqueViolation,
+} from "../pg-error";
 import type { AnyDb } from "../query";
 import { asRawClient } from "../query";
 
@@ -6,6 +12,106 @@ export async function notifyPgChannel(db: AnyDb, channel: string): Promise<void>
   await asRawClient(db).unsafe(`SELECT pg_notify($1, '')`, [channel]);
 }
 
+// Tenant-scoped partial unique index over metadata.idempotencyKey.
+// Expression index straight on the jsonb column — no dedicated key column,
+// so it needs no INSERT-path change and covers admin-api's raw appends too
+// (same metadata jsonb). CREATE ... IF NOT EXISTS makes this safe to call
+// on every boot, same "ensure" pattern as ensureSnapshotVersionColumn: heals
+// installs that predate the index without a table rebuild.
+//
+// CONCURRENTLY (not a plain CREATE): a non-concurrent build takes a SHARE
+// lock for the full table scan on kumiko_events — the hottest table in the
+// framework — blocking every append() for however long that scan takes on
+// an existing installation's event history. CONCURRENTLY avoids that at the
+// cost of needing to tolerate two failure modes a plain build doesn't have.
+// Neither CREATE nor DROP ... CONCURRENTLY may run inside a transaction —
+// no caller of this function (dev-server, schema-cli.ts, stack/db.ts) may
+// wrap it in one, or Postgres raises 25001.
+// undefined = index doesn't exist at all (nothing to drop, CREATE below
+// handles it); false = exists but INVALID (crashed mid-build, needs DROP +
+// rebuild); true = exists and valid.
+async function indexValidity(client: ReturnType<typeof asRawClient>): Promise<boolean | undefined> {
+  const rows = await client.unsafe(
+    `SELECT i.indisvalid FROM pg_class c JOIN pg_index i ON i.indexrelid = c.oid ` +
+      `WHERE c.relname = 'events_idempotency_uq' AND i.indrelid = '"kumiko_events"'::regclass`,
+  );
+  return (rows[0] as { indisvalid?: boolean } | undefined)?.indisvalid;
+}
+
+export async function ensureIdempotencyKeyIndex(db: AnyDb): Promise<void> {
+  const client = asRawClient(db);
+
+  try {
+    // 1) A prior CONCURRENTLY build that got killed mid-flight (crash, deploy
+    //    restart) leaves an INVALID index: the catalog entry exists, so
+    //    IF NOT EXISTS below would silently skip forever, but the index is
+    //    incomplete and not plannable for queries — it does NOT mean the
+    //    constraint enforces nothing; Postgres keeps maintaining an INVALID
+    //    index on every insert, it just refuses to use it for planning.
+    //    Detect + rebuild it. Scoped to kumiko_events specifically (indrelid),
+    //    not just the relname, so a same-named index in another schema can't
+    //    false-positive this DROP.
+    if ((await indexValidity(client)) === false) {
+      await client.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS "events_idempotency_uq"`);
+    }
+
+    await client.unsafe(
+      `CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS "events_idempotency_uq" ON "kumiko_events" ` +
+        `("tenant_id", (("metadata"->>'idempotencyKey'))) ` +
+        `WHERE "metadata"->>'idempotencyKey' IS NOT NULL`,
+    );
+  } catch (e) {
+    if (isBenignConcurrentIndexBuildRace(e)) {
+      // "Benign" only means the losing side of a race, not that the index
+      // actually landed valid — a lock_timeout on the CREATE (55P03) backs
+      // off the same way a genuine duplicate-build race does, but leaves no
+      // valid index at all. Re-check before declaring victory instead of
+      // trusting the error class alone.
+      // skip: sibling pod already built a valid index — this race loser is done.
+      if ((await indexValidity(client)) === true) return;
+      console.warn(
+        `ensureIdempotencyKeyIndex: backed off on a "benign" race (${String(e)}) but ` +
+          `"events_idempotency_uq" is still missing/invalid afterward — likely a ` +
+          `lock_timeout during CREATE INDEX CONCURRENTLY, not an actual winner/loser race.`,
+      );
+      throw e;
+    }
+    throw duplicateIdempotencyKeyErrorOr(e);
+  }
+}
+
+// Two pods booting concurrently against the same DB (rolling deploy): both
+// see the index missing/invalid and both start a DROP/CREATE CONCURRENTLY
+// build. The loser typically does NOT get the plain duplicate-relation
+// no-op IF NOT EXISTS normally gives — it can instead see a unique-violation
+// on Postgres' own pg_class catalog insert (23505, constraint
+// pg_class_relname_nsp_index) or a lock-not-available (55P03) from the
+// racing DDL. Both are benign: the other pod's build wins and this one just
+// backs off. A 23505 against "events_idempotency_uq" itself is NOT this
+// race — see duplicateIdempotencyKeyErrorOr.
+function isBenignConcurrentIndexBuildRace(e: unknown): boolean {
+  if (isTableAlreadyExists(e) || isLockNotAvailable(e)) return true;
+  return isUniqueViolation(e) && constraintOf(e) === "pg_class_relname_nsp_index";
+}
+
+// A 23505 against "events_idempotency_uq" means real duplicate
+// metadata->>'idempotencyKey' values for the same tenant already exist —
+// CONCURRENTLY still enforces uniqueness on live inserts against the
+// not-yet-valid index. That needs an operator to find + resolve the
+// duplicates, not a crash-loop on every subsequent boot, so re-throw a
+// distinguishable error instead of the raw driver error.
+function duplicateIdempotencyKeyErrorOr(e: unknown): unknown {
+  if (isUniqueViolation(e) && constraintOf(e) === "events_idempotency_uq") {
+    return new Error(
+      "ensureIdempotencyKeyIndex: duplicate metadata->>'idempotencyKey' values exist for at least " +
+        "one tenant in kumiko_events — CREATE UNIQUE INDEX CONCURRENTLY cannot complete. Find and " +
+        "resolve the duplicate idempotencyKey rows, then restart to retry.",
+      { cause: e },
+    );
+  }
+  return e;
+}
+
 export type SubsequentEventInsertParams = {
   readonly aggregateId: string;
   readonly aggregateType: string;
@@ -85,22 +191,6 @@ export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string):
   return rows[0]?.v ?? 0;
 }
 
-/** tenant_id the aggregate's events were written under — no membership/tenant
- *  filter. A r.systemScope() aggregate (e.g. user) lives in whichever tenant
- *  its creating executor used, which need not be a tenant the subject holds a
- *  membership in. Returns null for unknown streams. */
-export async function selectAggregateStreamTenant(
-  db: AnyDb,
-  aggregateId: string,
-  aggregateType: string,
-): Promise<string | null> {
-  const rows = (await asRawClient(db).unsafe(
-    `SELECT "tenant_id" AS t FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = $2 ORDER BY "version" LIMIT 1`,
-    [aggregateId, aggregateType],
-  )) as ReadonlyArray<{ t: string | null }>;
-  return rows[0]?.t ?? null;
-}
-
 export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
   const rows = (await asRawClient(db).unsafe(
     `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`,
@@ -135,18 +225,35 @@ export type SaveSnapshotParams = {
   // Plain object — see SubsequentEventInsertParams on why pre-stringified
   // JSON double-encodes under Bun.SQL's ::jsonb binding.
   readonly state: Record<string, unknown>;
+  readonly snapshotVersion: number;
 };
 
+// kumiko_snapshots predates snapshot_version — idempotent heal for existing
+// installs, run from the same ensure path as table creation.
+export async function ensureSnapshotVersionColumn(db: AnyDb): Promise<void> {
+  await asRawClient(db).unsafe(
+    `ALTER TABLE "kumiko_snapshots" ADD COLUMN IF NOT EXISTS "snapshot_version" integer NOT NULL DEFAULT 1`,
+  );
+}
+
 export async function upsertSnapshot(db: AnyDb, params: SaveSnapshotParams): Promise<void> {
   await asRawClient(db).unsafe(
     `INSERT INTO "kumiko_snapshots"
-       ("aggregate_id", "tenant_id", "aggregate_type", "version", "state")
-     VALUES ($1, $2, $3, $4, $5::jsonb)
+       ("aggregate_id", "tenant_id", "aggregate_type", "version", "state", "snapshot_version")
+     VALUES ($1, $2, $3, $4, $5::jsonb, $6)
      ON CONFLICT ("aggregate_id", "version") DO UPDATE SET
        "state" = $5::jsonb,
        "aggregate_type" = $3,
+       "snapshot_version" = $6,
        "created_at" = now()`,
-    [params.aggregateId, params.tenantId, params.aggregateType, params.version, params.state],
+    [
+      params.aggregateId,
+      params.tenantId,
+      params.aggregateType,
+      params.version,
+      params.state,
+      params.snapshotVersion,
+    ],
   );
 }
 

package/src/db/queries/projection-rebuild.ts

@@ -23,12 +23,19 @@ export async function selectEventsForProjectionRebuildBatch(
   afterId: bigint,
   limit: number,
 ): Promise<ReadonlyArray<Record<string, unknown>>> {
+  // Archived streams don't replay (Marten-aligned): their aggregates are
+  // frozen ops-tombstones — replaying them would resurrect rows (or, for
+  // stranded duplicate-aggregates like fw#832, collide on unique indexes).
   return (await asRawClient(db).unsafe(
-    `SELECT * FROM "kumiko_events"
-     WHERE "aggregate_type" = ANY($1::text[])
-       AND "type" = ANY($2::text[])
-       AND "id" > $3
-     ORDER BY "id" ASC
+    `SELECT * FROM "kumiko_events" e
+     WHERE e."aggregate_type" = ANY($1::text[])
+       AND e."type" = ANY($2::text[])
+       AND e."id" > $3
+       AND NOT EXISTS (
+         SELECT 1 FROM "kumiko_archived_streams" a
+          WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
+       )
+     ORDER BY e."id" ASC
      LIMIT $4`,
     [aggregateTypes, eventTypes, afterId, limit],
   )) as ReadonlyArray<Record<string, unknown>>;
@@ -43,10 +50,17 @@ export async function countSubscribedEvents(
   aggregateTypes: readonly string[],
   eventTypes: readonly string[],
 ): Promise<bigint> {
+  // Same archived-streams exclusion as the batch query — the #443 recompute
+  // compares this count against applied events; a filter mismatch would make
+  // every rebuild with an archived stream loop the full-re-replay forever.
   const rows = (await asRawClient(db).unsafe(
-    `SELECT count(*)::bigint AS n FROM "kumiko_events"
-     WHERE "aggregate_type" = ANY($1::text[])
-       AND "type" = ANY($2::text[])`,
+    `SELECT count(*)::bigint AS n FROM "kumiko_events" e
+     WHERE e."aggregate_type" = ANY($1::text[])
+       AND e."type" = ANY($2::text[])
+       AND NOT EXISTS (
+         SELECT 1 FROM "kumiko_archived_streams" a
+          WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
+       )`,
     [aggregateTypes, eventTypes],
   )) as ReadonlyArray<{ n: bigint | string | number | null }>;
   const raw = rows[0]?.n;