@cosmicdrift/kumiko-framework 0.1.0

package/src/pipeline/__tests__/perf-rebuild.integration.ts

@@ -0,0 +1,147 @@
+// Projection-Rebuild Performance — NOT a perf gate, a "not-broken" gate.
+//
+// Asserts the current rebuildProjection() pipeline (registry + state-table
+// + status-lifecycle wrapper) still moves bulk events at a sane rate. The
+// real performance number is what we observe in isolation: 14–15k events/s
+// on this hardware. The threshold below is intentionally loose because
+// vitest runs integration suites in parallel — other files hammer the same
+// Postgres at the same time, and an I/O-bound rebuild shares bandwidth.
+//
+// Threshold: 5000 events/s. Picked so a 2× regression on a real bottleneck
+// (e.g. accidental N+1 in the apply-loop, missing index on events.id, a
+// stray await in the hot path) trips the test, while normal suite-load
+// jitter does not. If this ever flakes in CI, drop to 3000 — the goal is
+// "catastrophic regression detector", not "perf SLO".
+
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import {
+  integer as drizzleInteger,
+  table as drizzlePgTable,
+  uuid as drizzleUuid,
+} from "../../db/dialect";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import type { ProjectionDefinition } from "../../engine/types";
+import { createEventsTable } from "../../event-store";
+import { createProjectionStateTable, rebuildProjection } from "../../pipeline";
+import { createTestDb, pushTables, type TestDb, TestUsers } from "../../stack";
+import { generateId as uuid } from "../../utils";
+
+// Counter projection: every task.created bumps a counter, every
+// task.updated is a no-op. Enough to exercise the apply path —
+// rebuild cost is dominated by event iteration + apply dispatch,
+// not the projection state shape.
+const taskCountTable = drizzlePgTable("read_perf_rebuild_task_count", {
+  tenantId: drizzleUuid("tenant_id").primaryKey(),
+  count: drizzleInteger("count").notNull().default(0),
+});
+
+const taskCountProjection: ProjectionDefinition = {
+  name: "task-count",
+  source: "task",
+  table: taskCountTable,
+  apply: {
+    "task.created": async (event, tx) => {
+      await tx
+        .insert(taskCountTable)
+        .values({ tenantId: event.tenantId, count: 1 })
+        .onConflictDoUpdate({
+          target: taskCountTable.tenantId,
+          set: { count: sql`${taskCountTable.count} + 1` },
+        });
+    },
+    "task.updated": async (_event, _tx) => {
+      // No-op apply — measuring event-iteration overhead, not per-event
+      // DB roundtrips. 10k events/s with one row-update per event would
+      // be an I/O-bound test, not a rebuild-throughput test.
+    },
+  },
+};
+
+const taskEntity = createEntity({
+  table: "perf_rebuild_tasks",
+  fields: { title: createTextField({ required: true }) },
+});
+
+const feature = defineFeature("perfrebuild", (r) => {
+  r.entity("task", taskEntity);
+  r.projection(taskCountProjection);
+});
+
+const admin = TestUsers.admin;
+let testDb: TestDb;
+const registry = createRegistry([feature]);
+const qualifiedProjectionName = "perfrebuild:projection:task-count";
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+  await pushTables(testDb.db, { perf_rebuild_task_count: taskCountTable });
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(
+    sql`TRUNCATE kumiko_events, read_perf_rebuild_task_count, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+});
+
+// Bulk-seed via SQL — sequential append() calls would take minutes.
+// Measures rebuild throughput on a finished stream, not the seed phase.
+// Produces count aggregates × depth events per aggregate.
+async function seedEvents(count: number, depth: number): Promise<void> {
+  const userId = uuid();
+  // v1 creates
+  await testDb.db.execute(sql`
+    INSERT INTO kumiko_events (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
+    SELECT gen_random_uuid(), 'task', ${admin.tenantId}::uuid, 1, 'task.created',
+           jsonb_build_object('title', 'Task ' || gs.n),
+           jsonb_build_object('userId', ${userId}::text),
+           ${userId}::text
+      FROM generate_series(1, ${count}) AS gs(n);
+  `);
+  // v2..depth updates
+  for (let v = 2; v <= depth; v++) {
+    await testDb.db.execute(sql`
+      INSERT INTO kumiko_events (aggregate_id, aggregate_type, tenant_id, version, type, payload, metadata, created_by)
+      SELECT e.aggregate_id, 'task', ${admin.tenantId}::uuid, ${v}, 'task.updated',
+             jsonb_build_object('title', 'Task v' || ${v}),
+             jsonb_build_object('userId', ${userId}::text),
+             ${userId}::text
+        FROM kumiko_events e
+       WHERE e.aggregate_type = 'task' AND e.version = ${v - 1};
+    `);
+  }
+}
+
+describe("rebuildProjection performance — Gate A", () => {
+  test("rebuild rate >= 3k events/sec under suite-parallel-load (10000 events)", async () => {
+    // 2000 aggregates × 5 events = 10000 events
+    await seedEvents(2000, 5);
+
+    const start = performance.now();
+    const result = await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+    });
+    const durationMs = performance.now() - start;
+
+    expect(result.eventsProcessed).toBe(10_000);
+    const rate = result.eventsProcessed / (durationMs / 1000);
+    console.log(
+      `  Rebuild: ${result.eventsProcessed} events in ${durationMs.toFixed(1)}ms = ${Math.round(rate)} events/s`,
+    );
+
+    // Budget 3k events/s under suite-parallel-load. Isolated runs on dev
+    // hardware see ~14k events/s; parallel-load drops it 3-4x (Docker-PG
+    // contention, Vitest worker concurrency). The gate catches real
+    // regressions (~40% drop to <2k) without daily false positives. If
+    // you see this flake below 3k, profile `rebuildProjection` — don't
+    // just lower the budget further.
+    expect(rate).toBeGreaterThanOrEqual(3_000);
+  });
+});

package/src/pipeline/__tests__/projection-rebuild.integration.ts

@@ -0,0 +1,551 @@
+// Projection rebuild — the load-bearing claim of the whole projections API.
+// "Projections are rebuildable read-models" has to actually work: replaying
+// the event log must produce the exact same state as live apply().
+//
+// Tests here:
+//   - rebuild from empty state matches live-applied state
+//   - rebuild after data-corruption fixes the projection
+//   - rebuild preserves atomicity (throw mid-replay → status=failed + old
+//     rows intact)
+//   - status lifecycle (idle → rebuilding → idle on success, → failed on throw)
+//   - never-rebuilt projection has sensible default state
+
+import { eq, sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import {
+  integer as drizzleInteger,
+  table as drizzlePgTable,
+  uuid as drizzleUuid,
+} from "../../db/dialect";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildDrizzleTable } from "../../db/table-builder";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import {
+  createEntity,
+  createRegistry,
+  createTextField,
+  defineApply,
+  defineFeature,
+} from "../../engine";
+import type { ProjectionDefinition } from "../../engine/types";
+import { createEventsTable } from "../../event-store";
+import {
+  createProjectionStateTable,
+  getAllProjectionProgress,
+  getProjectionState,
+  listProjectionsWithState,
+  rebuildProjection,
+} from "../../pipeline";
+import { createEntityTable, createTestDb, pushTables, type TestDb, TestUsers } from "../../stack";
+
+// --- Test fixtures ---
+
+const itemEntity = createEntity({
+  table: "read_rebuild_items",
+  fields: {
+    groupId: createTextField({ required: true }),
+    name: createTextField({ required: true }),
+  },
+  softDelete: true,
+});
+const itemTable = buildDrizzleTable("rebuild-item", itemEntity);
+
+const itemsPerGroupTable = drizzlePgTable("read_rebuild_items_per_group", {
+  groupId: drizzleUuid("group_id").primaryKey(),
+  tenantId: drizzleUuid("tenant_id").notNull(),
+  itemCount: drizzleInteger("item_count").notNull().default(0),
+});
+
+async function bump(tx: unknown, groupId: string, tenantId: string, delta: number): Promise<void> {
+  // biome-ignore lint/suspicious/noExplicitAny: tx is DbRunner
+  await (tx as any)
+    .insert(itemsPerGroupTable)
+    .values({ groupId, tenantId, itemCount: delta })
+    .onConflictDoUpdate({
+      target: itemsPerGroupTable.groupId,
+      set: { itemCount: sql`${itemsPerGroupTable.itemCount} + ${delta}` },
+    });
+}
+
+type ItemCreated = { groupId: string };
+type ItemRestoreOrDelete = { previous: { groupId: string } };
+
+const itemsPerGroupProjection: ProjectionDefinition = {
+  name: "items-per-group",
+  source: "rebuild-item",
+  table: itemsPerGroupTable,
+  apply: {
+    "rebuild-item.created": defineApply<ItemCreated>(async (event, tx) => {
+      await bump(tx, event.payload.groupId, event.tenantId, 1);
+    }),
+    "rebuild-item.deleted": defineApply<ItemRestoreOrDelete>(async (event, tx) => {
+      await bump(tx, event.payload.previous.groupId, event.tenantId, -1);
+    }),
+    "rebuild-item.restored": defineApply<ItemRestoreOrDelete>(async (event, tx) => {
+      await bump(tx, event.payload.previous.groupId, event.tenantId, 1);
+    }),
+  },
+};
+
+const feature = defineFeature("rebuildtest", (r) => {
+  r.entity("rebuild-item", itemEntity);
+  r.projection(itemsPerGroupProjection);
+});
+
+const admin = TestUsers.admin;
+let testDb: TestDb;
+let tdb: TenantDb;
+const registry = createRegistry([feature]);
+const qualifiedProjectionName = "rebuildtest:projection:items-per-group";
+
+// Drizzle identifier for the executor.
+const executor = createEventStoreExecutor(itemTable, itemEntity, { entityName: "rebuild-item" });
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEntityTable(testDb.db, itemEntity, "rebuild-item");
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+  await pushTables(testDb.db, { rebuildItemsPerGroup: itemsPerGroupTable });
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(
+    sql`TRUNCATE kumiko_events, read_rebuild_items, read_rebuild_items_per_group, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+});
+
+// --- Live-apply helper: use the dispatcher pipeline so projections fire.
+// For rebuild-only tests we can bypass live apply and just append events
+// directly — the point of rebuild is to reconstruct state from events alone.
+
+async function appendCreatedEvent(groupId: string, name: string): Promise<void> {
+  // Use the executor directly — this fires events + the entity row, but
+  // NOT the projection (pipeline not wired). Perfect for "live has no
+  // projection state, rebuild reconstructs it" scenarios.
+  await executor.create({ groupId, name }, admin, tdb);
+}
+
+async function getCount(groupId: string): Promise<number | undefined> {
+  const [row] = await testDb.db
+    .select()
+    .from(itemsPerGroupTable)
+    .where(eq(itemsPerGroupTable.groupId, groupId));
+  return row?.itemCount;
+}
+
+describe("rebuildProjection — happy path", () => {
+  test("replays events and produces correct counter state", async () => {
+    const group = "00000000-0000-4000-8000-000000000001";
+    await appendCreatedEvent(group, "item1");
+    await appendCreatedEvent(group, "item2");
+    await appendCreatedEvent(group, "item3");
+
+    // Projection table is empty — pipeline wasn't wired in these writes.
+    expect(await getCount(group)).toBeUndefined();
+
+    const result = await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+    });
+
+    expect(result.projection).toBe(qualifiedProjectionName);
+    expect(result.eventsProcessed).toBe(3);
+    expect(result.lastProcessedEventId).toBeGreaterThan(0n);
+
+    // Counter now reflects all three creates.
+    expect(await getCount(group)).toBe(3);
+  });
+
+  test("rebuild wipes existing state before replay (no double-count)", async () => {
+    const group = "00000000-0000-4000-8000-000000000002";
+    await appendCreatedEvent(group, "a");
+    await appendCreatedEvent(group, "b");
+
+    // Seed the projection table with a stale/wrong value.
+    await testDb.db
+      .insert(itemsPerGroupTable)
+      .values({ groupId: group, tenantId: admin.tenantId, itemCount: 999 });
+
+    const result = await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+    });
+
+    expect(result.eventsProcessed).toBe(2);
+    // Not 999+2, not 999 — TRUNCATE + replay.
+    expect(await getCount(group)).toBe(2);
+  });
+
+  test("handles events across multiple groups and aggregate IDs", async () => {
+    const groupA = "00000000-0000-4000-8000-000000000010";
+    const groupB = "00000000-0000-4000-8000-000000000011";
+
+    await appendCreatedEvent(groupA, "a1");
+    await appendCreatedEvent(groupB, "b1");
+    await appendCreatedEvent(groupA, "a2");
+    await appendCreatedEvent(groupA, "a3");
+    await appendCreatedEvent(groupB, "b2");
+
+    const result = await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+    });
+
+    expect(result.eventsProcessed).toBe(5);
+    expect(await getCount(groupA)).toBe(3);
+    expect(await getCount(groupB)).toBe(2);
+  });
+
+  test("rebuild on empty event log is a no-op with 0 events processed", async () => {
+    const result = await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+    });
+    expect(result.eventsProcessed).toBe(0);
+    expect(result.lastProcessedEventId).toBe(0n);
+  });
+});
+
+describe("rebuildProjection — state table lifecycle", () => {
+  test("writes state row with status=idle + lastRebuildAt after success", async () => {
+    const group = "00000000-0000-4000-8000-000000000020";
+    await appendCreatedEvent(group, "one");
+
+    // Before: no state row.
+    expect(await getProjectionState(testDb.db, qualifiedProjectionName)).toBeNull();
+
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+
+    const state = await getProjectionState(testDb.db, qualifiedProjectionName);
+    expect(state?.status).toBe("idle");
+    expect(state?.lastProcessedEventId).toBeGreaterThan(0n);
+    expect(state?.lastRebuildAt).not.toBeNull();
+    expect(state?.lastError).toBeNull();
+  });
+
+  test("subsequent rebuild overwrites state row (status + timestamp)", async () => {
+    const group = "00000000-0000-4000-8000-000000000021";
+    await appendCreatedEvent(group, "first");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    const first = await getProjectionState(testDb.db, qualifiedProjectionName);
+
+    // Wait a tick so timestamp difference is visible.
+    await new Promise((r) => setTimeout(r, 20));
+    await appendCreatedEvent(group, "second");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+
+    const second = await getProjectionState(testDb.db, qualifiedProjectionName);
+    if (!first?.lastRebuildAt || !second?.lastRebuildAt) throw new Error("missing lastRebuildAt");
+    expect(Temporal.Instant.compare(second.lastRebuildAt, first.lastRebuildAt)).toBeGreaterThan(0);
+    expect(second?.lastProcessedEventId).toBeGreaterThan(first?.lastProcessedEventId ?? 0n);
+  });
+});
+
+describe("rebuildProjection — error path", () => {
+  test("apply throw rolls TRUNCATE + partial replay back, marks status=failed", async () => {
+    const group = "00000000-0000-4000-8000-000000000030";
+    await appendCreatedEvent(group, "keeper-1");
+    await appendCreatedEvent(group, "keeper-2");
+
+    // First rebuild succeeds — leaves counter at 2.
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(2);
+
+    // Construct a broken registry where apply("rebuild-item.created") throws.
+    const brokenFeature = defineFeature("brokentest", (r) => {
+      r.entity("rebuild-item", itemEntity);
+      r.projection({
+        ...itemsPerGroupProjection,
+        name: "items-per-group",
+        apply: {
+          "rebuild-item.created": async () => {
+            throw new Error("boom");
+          },
+        },
+      });
+    });
+    const brokenRegistry = createRegistry([brokenFeature]);
+    const brokenName = "brokentest:projection:items-per-group";
+
+    // Rebuild throws.
+    await expect(
+      rebuildProjection(brokenName, { db: testDb.db, registry: brokenRegistry }),
+    ).rejects.toThrow("boom");
+
+    // Old counter rows are gone (TRUNCATE is inside the TX but this is a
+    // DIFFERENT projection). Verify our original projection's rows WERE
+    // preserved because the broken rebuild targets a different name.
+    expect(await getCount(group)).toBe(2);
+
+    // State of the broken projection is "failed" with the error message.
+    const state = await getProjectionState(testDb.db, brokenName);
+    expect(state?.status).toBe("failed");
+    expect(state?.lastError).toContain("boom");
+  });
+
+  test("broken rebuild of EXISTING projection keeps OLD rows intact", async () => {
+    const group = "00000000-0000-4000-8000-000000000031";
+    await appendCreatedEvent(group, "a");
+    await appendCreatedEvent(group, "b");
+    await appendCreatedEvent(group, "c");
+
+    // First rebuild leaves counter at 3.
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    expect(await getCount(group)).toBe(3);
+
+    // Now attempt a rebuild with a broken apply under the SAME projection name.
+    const brokenFeature = defineFeature("rebuildtest", (r) => {
+      r.entity("rebuild-item", itemEntity);
+      r.projection({
+        ...itemsPerGroupProjection,
+        apply: {
+          "rebuild-item.created": async () => {
+            throw new Error("poisoned");
+          },
+        },
+      });
+    });
+    const brokenRegistry = createRegistry([brokenFeature]);
+
+    await expect(
+      rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry: brokenRegistry }),
+    ).rejects.toThrow("poisoned");
+
+    // CRITICAL: the old counter rows survive. TRUNCATE happened INSIDE the
+    // transaction, so the rollback restored them. Without this the rebuild
+    // would be worse than not rebuilding at all.
+    expect(await getCount(group)).toBe(3);
+
+    // State reflects the failure.
+    const state = await getProjectionState(testDb.db, qualifiedProjectionName);
+    expect(state?.status).toBe("failed");
+    expect(state?.lastError).toContain("poisoned");
+  });
+
+  test("unknown projection name throws with helpful message", async () => {
+    await expect(rebuildProjection("nonexistent", { db: testDb.db, registry })).rejects.toThrow(
+      /not registered/,
+    );
+  });
+});
+
+describe("listProjectionsWithState", () => {
+  test("lists every registered projection with combined state info", async () => {
+    // Before any rebuild: state field indicates never-rebuilt.
+    const before = await listProjectionsWithState(testDb.db, registry);
+    expect(before).toHaveLength(1);
+    expect(before[0]?.name).toBe(qualifiedProjectionName);
+    expect(before[0]?.status).toBe("never-rebuilt");
+    expect(before[0]?.sources).toEqual(["rebuild-item"]);
+
+    // After rebuild: status reflects DB state.
+    await appendCreatedEvent("00000000-0000-4000-8000-000000000040", "x");
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+
+    const after = await listProjectionsWithState(testDb.db, registry);
+    expect(after[0]?.status).toBe("idle");
+    expect(after[0]?.lastRebuildAt).not.toBeNull();
+  });
+});
+
+describe("getAllProjectionProgress", () => {
+  test("computes lag = highWaterMark - cursor for caught-up projection", async () => {
+    // Empty event-log → HWM=0n, lag=0n, projection never-rebuilt → cursor=0n.
+    const empty = await getAllProjectionProgress(testDb.db, registry);
+    expect(empty[0]?.highWaterMark).toBe(0n);
+    expect(empty[0]?.lag).toBe(0n);
+
+    // Seed some events but skip rebuild → HWM advances, cursor stays 0n,
+    // lag = HWM. This is the "behind" state an ops dashboard sees before
+    // someone triggers a rebuild.
+    await appendCreatedEvent("00000000-0000-4000-8000-000000000060", "a");
+    await appendCreatedEvent("00000000-0000-4000-8000-000000000061", "b");
+    await appendCreatedEvent("00000000-0000-4000-8000-000000000062", "c");
+
+    const behind = await getAllProjectionProgress(testDb.db, registry);
+    expect(behind[0]?.highWaterMark).toBe(3n);
+    expect(behind[0]?.lastProcessedEventId).toBe(0n);
+    expect(behind[0]?.lag).toBe(3n);
+
+    // Nach rebuild: cursor = HWM, lag wieder 0.
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry });
+    const caughtUp = await getAllProjectionProgress(testDb.db, registry);
+    expect(caughtUp[0]?.highWaterMark).toBe(3n);
+    expect(caughtUp[0]?.lastProcessedEventId).toBe(3n);
+    expect(caughtUp[0]?.lag).toBe(0n);
+  });
+});
+
+describe("rebuildProjection — metrics callback", () => {
+  test("invokes onMetrics with the RebuildResult on success", async () => {
+    const group = "00000000-0000-4000-8000-000000000050";
+    await appendCreatedEvent(group, "a");
+    await appendCreatedEvent(group, "b");
+
+    const calls: Array<{
+      projection: string;
+      eventsProcessed: number;
+      durationMs: number;
+    }> = [];
+    await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+      onMetrics: (r) =>
+        calls.push({
+          projection: r.projection,
+          eventsProcessed: r.eventsProcessed,
+          durationMs: r.durationMs,
+        }),
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.projection).toBe(qualifiedProjectionName);
+    expect(calls[0]?.eventsProcessed).toBe(2);
+    expect(calls[0]?.durationMs).toBeGreaterThanOrEqual(0);
+  });
+});
+
+describe("rebuildProjection — meter emission", () => {
+  test("emits success=true metric + events counter on happy path", async () => {
+    const { RecordingMeter } = await import("../../observability/recording-meter");
+    const { registerStandardMetrics } = await import("../../observability/standard-metrics");
+
+    const group = "00000000-0000-4000-8000-000000000060";
+    await appendCreatedEvent(group, "a");
+    await appendCreatedEvent(group, "b");
+    await appendCreatedEvent(group, "c");
+
+    const events: Array<{
+      type: string;
+      name: string;
+      value: number;
+      labels: Record<string, string | number> | undefined;
+    }> = [];
+    const meter = new RecordingMeter((e) =>
+      events.push({
+        type: e.type,
+        name: e.name,
+        value: e.value,
+        labels: e.labels as Record<string, string | number> | undefined,
+      }),
+    );
+    registerStandardMetrics(meter);
+
+    await rebuildProjection(qualifiedProjectionName, { db: testDb.db, registry, meter });
+
+    const duration = events.find((e) => e.name === "kumiko_projection_rebuild_duration_seconds");
+    expect(duration).toBeDefined();
+    expect(duration?.type).toBe("histogram.observe");
+    expect(duration?.labels?.["projection"]).toBe(qualifiedProjectionName);
+    expect(duration?.labels?.["success"]).toBe("true");
+    expect(duration?.value).toBeGreaterThanOrEqual(0);
+
+    const counter = events.find((e) => e.name === "kumiko_projection_rebuild_events_total");
+    expect(counter).toBeDefined();
+    expect(counter?.type).toBe("counter.inc");
+    expect(counter?.value).toBe(3);
+    expect(counter?.labels?.["projection"]).toBe(qualifiedProjectionName);
+  });
+
+  test("emits success=false metric when apply throws", async () => {
+    const { RecordingMeter } = await import("../../observability/recording-meter");
+    const { registerStandardMetrics } = await import("../../observability/standard-metrics");
+
+    const group = "00000000-0000-4000-8000-000000000061";
+    await appendCreatedEvent(group, "a");
+
+    const brokenFeature = defineFeature("failmeter", (r) => {
+      r.entity("rebuild-item", itemEntity);
+      r.projection({
+        ...itemsPerGroupProjection,
+        apply: {
+          "rebuild-item.created": async () => {
+            throw new Error("metric-failure-probe");
+          },
+        },
+      });
+    });
+    const brokenRegistry = createRegistry([brokenFeature]);
+
+    const events: Array<{
+      type: string;
+      name: string;
+      value: number;
+      labels: Record<string, string | number> | undefined;
+    }> = [];
+    const meter = new RecordingMeter((e) =>
+      events.push({
+        type: e.type,
+        name: e.name,
+        value: e.value,
+        labels: e.labels as Record<string, string | number> | undefined,
+      }),
+    );
+    registerStandardMetrics(meter);
+
+    await expect(
+      rebuildProjection("failmeter:projection:items-per-group", {
+        db: testDb.db,
+        registry: brokenRegistry,
+        meter,
+      }),
+    ).rejects.toThrow("metric-failure-probe");
+
+    const duration = events.find((e) => e.name === "kumiko_projection_rebuild_duration_seconds");
+    expect(duration).toBeDefined();
+    expect(duration?.labels?.["success"]).toBe("false");
+    expect(duration?.labels?.["projection"]).toBe("failmeter:projection:items-per-group");
+  });
+});
+
+describe("rebuildProjection — cancellation", () => {
+  test("pre-aborted signal: rebuild throws, TRUNCATE rolls back, projection state preserved", async () => {
+    // Setup: events on the log + a clean rebuild → projection has known
+    // counter state. Then call rebuildProjection with a pre-aborted
+    // controller. The first throwIfAborted() inside the apply loop
+    // throws, the TX rolls back, and the projection row from the prior
+    // good rebuild is still there.
+    //
+    // Why pre-aborted instead of mid-replay: the apply hook is wired in
+    // the projection definition at registry-build-time, so injecting
+    // "abort after event N" requires a separate registered projection.
+    // This test pins the rollback semantics — a separate test would be
+    // needed to exercise mid-loop abort, but the rollback path is the
+    // same code so the value-add is small.
+    const group = "00000000-0000-4000-8000-0000000000c1";
+    for (let i = 0; i < 10; i++) {
+      await appendCreatedEvent(group, `cancel-${i}`);
+    }
+
+    await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+    });
+    const before = await getCount(group);
+    expect(before).toBe(10);
+
+    const controller = new AbortController();
+    controller.abort();
+
+    let thrown: unknown;
+    try {
+      await rebuildProjection(qualifiedProjectionName, {
+        db: testDb.db,
+        registry,
+        signal: controller.signal,
+      });
+    } catch (e) {
+      thrown = e;
+    }
+    expect((thrown as Error).name).toBe("AbortError");
+
+    const after = await getCount(group);
+    expect(after).toBe(before);
+  });
+});