@cosmicdrift/kumiko-framework 0.105.1 → 0.108.0

package/src/engine/types/fields.ts

@@ -199,6 +199,11 @@ export type NumberFieldDef = {
   readonly sensitive?: boolean;
   readonly default?: number;
   readonly access?: FieldAccess;
+  // Write-boundary constraints (Zod-level, no migration/storage impact — the
+  // Postgres column stays a plain numeric). Opt-in, so existing entities are
+  // unaffected.
+  readonly min?: number;
+  readonly integer?: boolean;
 } & PiiAnnotations;
 
 /**
@@ -557,6 +562,13 @@ export type DerivedFieldDef = {
 
 export type DerivedFieldsMap = Readonly<Record<string, DerivedFieldDef>>;
 
+/** Client-facing projection of DerivedFieldDef — `derive` is server-only and
+ *  not JSON-safe (would trip the output-walk guard), so the browser schema
+ *  only ever carries `valueType`. A real `Pick`, not a same-shape cast: TS
+ *  itself proves `derive` isn't there instead of a `{ valueType } as
+ *  DerivedFieldDef` cast lying about a field that's actually missing. */
+export type ClientDerivedFieldDef = Pick<DerivedFieldDef, "valueType">;
+
 // --- Entity ---
 
 // --- State Transitions ---

package/src/engine/types/handlers.ts

@@ -40,6 +40,19 @@ export type SessionUser = {
   // When present, middleware can validate that the sid is still alive before
   // accepting the request (session revocation).
   readonly sid?: string;
+  // Set ONLY when the request authenticated via a Personal Access Token
+  // (bearer, PAT_TOKEN_PREFIX). Absent for cookie/JWT logins, which stay
+  // unrestricted. `allowedQns` are the QN globs the token's granted scopes
+  // expand to; the API boundary (routes.ts) rejects any dispatch type not
+  // matched by one of them (fail-closed). `scopes` are the granted scope
+  // names, kept for audit/display only.
+  readonly pat?: {
+    // The token row id — the per-token key for PAT rate limiting. Not the
+    // secret; safe to carry on the principal.
+    readonly tokenId: string;
+    readonly scopes: readonly string[];
+    readonly allowedQns: readonly string[];
+  };
 };
 
 // --- Claim Keys (r.claimKey declarations) ---

package/src/engine/types/index.ts

@@ -83,6 +83,7 @@ export type {
   AnyFileFieldDef,
   BigIntFieldDef,
   BooleanFieldDef,
+  ClientDerivedFieldDef,
   DateFieldDef,
   DecimalFieldDef,
   DefaultCurrency,
@@ -195,6 +196,7 @@ export type { EntityId, TenantId } from "./identifiers";
 export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./identifiers";
 export type { NavDefinition } from "./nav";
 export type {
+  EntityProjectionExtension,
   MspErrorMode,
   MspErrorPolicy,
   MultiStreamApplyFn,

package/src/engine/types/projection.ts

@@ -14,17 +14,23 @@ import type { RunIn } from "./config";
 export type ProjectionTable = TableColumns<any>;
 
 // Single-stream projection apply: runs inline in the write-TX of the event
-// it projects. Gets the event + TX-scoped DbRunner — that's it. Inline
-// projections must not spawn further events (no ctx) because they run
-// inside the command's transaction and the framework guarantees a single
-// commit boundary per command.
+// it projects. Gets the event, the TX-scoped DbRunner, and the projection's
+// own `table` (already erased to ProjectionTable). Write through THAT table —
+// it is the only ES-blessed write into a managed projection outside the
+// executor, and it is reachable only here (an arbitrary handler has no such
+// arg), so the write-brand cannot be bypassed by closing over the branded
+// table constant. Inline projections must not spawn further events (no ctx)
+// because they run inside the command's transaction and the framework
+// guarantees a single commit boundary per command.
 //
 // Generic über payload-shape. Default = Record<string, unknown> behält
 // rückwärtskompatibles Verhalten; Konkrete Apply-Handler annotieren
-// `SingleStreamApplyFn<MyPayload>` für typed event.payload-Access.
+// `SingleStreamApplyFn<MyPayload>` für typed event.payload-Access. Der
+// `table`-Param ist additiv — 2-arg-Applies (event, tx) bleiben gültig.
 export type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (
   event: StoredEvent<TPayload>,
   tx: DbRunner,
+  table: ProjectionTable,
 ) => Promise<void>;
 
 // Multi-stream projection apply: runs asynchronously via the event-dispatcher
@@ -45,6 +51,11 @@ export type ProjectionDefinition = {
   // index projections so the executor doesn't scan all projections on every
   // write.
   readonly source: string | readonly string[];
+  // Additional aggregate-types whose events the rebuild replay must include
+  // beyond `source`. Fed by r.extendEntityProjection — an extension can react
+  // to events on foreign streams (e.g. "field-definition") while `source`
+  // keeps meaning "the owning entity" for consumers like soft-delete-cleanup.
+  readonly extraSources?: readonly string[];
   // Drizzle-table the projection materializes into. User owns the schema —
   // framework just guarantees the TX and event delivery.
   readonly table: ProjectionTable;
@@ -61,6 +72,23 @@ export type ProjectionDefinition = {
   readonly isImplicit?: boolean;
 };
 
+// Extension merged into an entity's implicit projection at registry build.
+// Lets a bundled feature that writes into the HOST entity's table via events
+// (custom-fields pattern) hook those event types into the entity's rebuild
+// replay — without it, a rebuild resets everything the extension wrote.
+// Live delivery stays with the extension's own MSP: implicit projections are
+// skipped by the inline runner, so the apply here runs ONLY during rebuild.
+export type EntityProjectionExtension = {
+  // Aggregate-types beyond the entity's own stream whose events the rebuild
+  // must scan (e.g. "field-definition"). Omit when all extension events are
+  // appended on the host entity's stream.
+  readonly sources?: readonly string[];
+  // Keyed by fully-qualified event type. Must not collide with the entity's
+  // built-in lifecycle applies (<entity>.created/updated/...) or another
+  // extension — collisions fail at boot.
+  readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
+};
+
 // Per-lifecycle error policy for a MultiStreamProjection. Mirrors Marten's
 // Projections.Errors / Projections.RebuildErrors split — a projection can
 // be lenient during steady-state delivery but strict during rebuild (or

package/src/event-store/index.ts

@@ -24,6 +24,14 @@ export {
   streamAllEventsByType,
 } from "./event-store";
 export { createEventsTable, eventsTable } from "./events-schema";
+export {
+  createRebuildDeadLetterTable,
+  listRebuildDeadLetters,
+  type RebuildDeadLetterRow,
+  rebuildDeadLetterTable,
+  recordRebuildDeadLetters,
+  type SkippedApply,
+} from "./rebuild-dead-letter";
 export { toStoredEvent } from "./row-to-stored-event";
 export {
   createSnapshotsTable,

package/src/event-store/rebuild-dead-letter.ts

@@ -0,0 +1,111 @@
+// Dead-letter storage for apply-handler failures during projection rebuild.
+//
+// Background: rebuildProjection / rebuildMultiStreamProjection replay the
+// event log through apply handlers inside ONE transaction. A single event
+// whose (possibly years-old) payload makes its apply throw rolls the whole
+// replay back — the projection stays permanently un-rebuildable until the
+// event is repaired by hand. The upcaster dead-letter only quarantines
+// upcast-TRANSFORM failures, not apply failures (#760).
+//
+// Quarantine mode (errorPolicy.skipApplyErrors on RebuildDeps, or
+// MspErrorMode.rebuild.skipApplyErrors on the MSP definition) confines each
+// apply to a savepoint: a throwing apply is rolled back, captured into
+// `kumiko_rebuild_dead_letters`, and the replay continues. Replay-after-fix
+// is a separate ops step — same stance as the upcaster dead-letter.
+
+import type { DbConnection, DbRunner } from "../db/connection";
+import { bigint, index, jsonb, table as pgTable, text, timestamp, uuid } from "../db/dialect";
+import { tableExists } from "../db/schema-inspection";
+import { unsafePushTables } from "../stack";
+import type { StoredEvent } from "./event-store";
+
+export const rebuildDeadLetterTable = pgTable(
+  "kumiko_rebuild_dead_letters",
+  {
+    // Surrogate PK — the same event can land here across multiple rebuild
+    // attempts before the fix ships, without unique-violation noise.
+    id: bigint("id", { mode: "bigint" }).primaryKey().generatedAlwaysAsIdentity(),
+    projectionName: text("projection_name").notNull(),
+    // StoredEvent.id is surfaced as `string` (bigint serialised for JSON
+    // safety) — stored as text to keep the round-trip identity.
+    eventId: text("event_id").notNull(),
+    tenantId: uuid("tenant_id").notNull(),
+    aggregateId: text("aggregate_id").notNull(),
+    aggregateType: text("aggregate_type").notNull(),
+    eventType: text("event_type").notNull(),
+    errorMessage: text("error_message").notNull(),
+    payload: jsonb("payload").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    projectionIdx: index("rebuild_dead_letters_projection_idx").on(t.projectionName),
+    createdAtIdx: index("rebuild_dead_letters_created_at_idx").on(t.createdAt),
+  }),
+);
+
+// Idempotent table-create. The rebuild runners call this before the rebuild
+// tx whenever quarantine mode is active, so the opt-in works on databases
+// provisioned before this table existed.
+export async function createRebuildDeadLetterTable(db: DbConnection): Promise<void> {
+  // skip: table already exists — bootstrap called from multiple paths
+  if (await tableExists(db, "public.kumiko_rebuild_dead_letters")) return;
+  await unsafePushTables(db, { kumikoRebuildDeadLetters: rebuildDeadLetterTable });
+}
+
+export type SkippedApply = {
+  readonly event: StoredEvent;
+  readonly error: unknown;
+};
+
+// Bulk-write, called ONCE at the end of a quarantining rebuild (inside its
+// tx). Unqualified insert — during the rebuild the search_path points at the
+// shadow schema, and this table exists only in public, so it falls through.
+export async function recordRebuildDeadLetters(
+  db: DbRunner,
+  projectionName: string,
+  skipped: readonly SkippedApply[],
+): Promise<void> {
+  const { insertMany } = await import("../bun-db/query");
+  await insertMany(
+    db,
+    rebuildDeadLetterTable,
+    skipped.map(({ event, error }) => ({
+      projectionName,
+      eventId: event.id,
+      tenantId: event.tenantId,
+      aggregateId: event.aggregateId,
+      aggregateType: event.aggregateType,
+      eventType: event.type,
+      errorMessage: error instanceof Error ? error.message : String(error),
+      payload: event.payload,
+    })),
+  );
+}
+
+export type RebuildDeadLetterRow = {
+  readonly id: bigint;
+  readonly projectionName: string;
+  readonly eventId: string;
+  readonly tenantId: string;
+  readonly aggregateId: string;
+  readonly aggregateType: string;
+  readonly eventType: string;
+  readonly errorMessage: string;
+  readonly payload: Record<string, unknown>;
+  readonly createdAt: Date;
+};
+
+// Ops-side triage query, optionally scoped to one projection.
+export async function listRebuildDeadLetters(
+  db: DbConnection,
+  options: { projectionName?: string; limit?: number } = {},
+): Promise<readonly RebuildDeadLetterRow[]> {
+  const { selectMany } = await import("../bun-db/query");
+  const limit = options.limit ?? 100;
+  const where =
+    options.projectionName !== undefined ? { projectionName: options.projectionName } : undefined;
+  return selectMany<RebuildDeadLetterRow>(db, rebuildDeadLetterTable, where, {
+    orderBy: { col: "createdAt", direction: "desc" },
+    limit,
+  });
+}

package/src/files/__tests__/storage-tracking.integration.test.ts

@@ -224,4 +224,12 @@ describe("file download roundtrip (GET /files/:id)", () => {
     await deleteFile(admin, id);
     expect((await download(admin, id)).status).toBe(404);
   });
+
+  test("a cross-tenant download is rejected (404, no existence oracle)", async () => {
+    const id = await upload(admin, "tenant-a-only.png", SMALL);
+    const res = await download(otherAdmin, id);
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error?: string };
+    expect(body.error).toBe("not_found");
+  });
 });

package/src/files/file-routes.ts

@@ -150,8 +150,8 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     // are orphaned in the provider; cleanup-jobs sweep those later. Losing a
     // row on append-failure is acceptable; corrupting a committed row with a
     // missing binary is not.
-    const data = new Uint8Array(await file.arrayBuffer());
     const storageProvider = await options.resolveProvider(user.tenantId);
+    const data = new Uint8Array(await file.arrayBuffer());
     await storageProvider.write(storageKey, data, file.type);
 
     // Create via the standard entity executor: emits fileRef.created +

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -547,6 +547,49 @@ describe("write-handler shape guard", () => {
   });
 });
 
+// --- Dispatch: geoTzProvider seam ---
+
+describe("dispatcher context.geoTzProvider (680/1)", () => {
+  test("ctx.tz.fromCoordinates reaches the app-injected geoTzProvider through a real dispatch", async () => {
+    // All geo-tz.test.ts coverage calls createTzContext({ geoTz }) directly —
+    // none go through the dispatcher or read context.geoTzProvider. A typo in
+    // the property forwarding at dispatcher.ts would make the injection a
+    // silent no-op (provider configured, ctx.tz.fromCoordinates still throws).
+    const geoFeature = defineFeature("geo", (r) => {
+      r.queryHandler(
+        "resolve-zone",
+        z.object({ latitude: z.number(), longitude: z.number() }),
+        async (query, ctx) => ({
+          zone: await ctx.tz.fromCoordinates({
+            latitude: query.payload.latitude,
+            longitude: query.payload.longitude,
+          }),
+        }),
+        { access: { openToAll: true } },
+      );
+    });
+    const registry = createRegistry([geoFeature]);
+    const calls: Array<{ latitude: number; longitude: number }> = [];
+    const dispatcher = createDispatcher(registry, {
+      geoTzProvider: {
+        fromCoordinates: ({ latitude, longitude }) => {
+          calls.push({ latitude, longitude });
+          return "Europe/Berlin";
+        },
+      },
+    });
+
+    const result = await dispatcher.query(
+      "geo:query:resolve-zone",
+      { latitude: 52.52, longitude: 13.405 },
+      createTestUser(),
+    );
+
+    expect(result).toEqual({ zone: "Europe/Berlin" });
+    expect(calls).toEqual([{ latitude: 52.52, longitude: 13.405 }]);
+  });
+});
+
 // --- Mock helpers ---
 
 function createMockIdempotencyGuard() {

package/src/pipeline/__tests__/load-aggregate-query.integration.test.ts

@@ -9,10 +9,10 @@
 // Bun.SQL-only setup. KEIN postgres-js, KEIN setupTestStack.
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
 import type { DbConnection, DbTx } from "../../db/connection";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
-import { insertOne } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import { append, loadAggregate as loadAggregateRaw } from "../../event-store";
@@ -219,7 +219,7 @@ describe("ctx.loadAggregate via queryHandler — Marten AggregateStreamAsync equ
     // produce garbage.
     const invoiceId = "00000000-0000-4000-8000-000000000042";
     await (stack.db as DbConnection).begin(async (tx: DbTx) => {
-      await insertOne(tx, invoiceTable, {
+      await seedRow(tx, invoiceTable, {
         id: invoiceId,
         tenantId: admin.tenantId,
         customer: "LegacyCo",

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

@@ -750,6 +750,30 @@ describe("rebuildProjection — live-tail catch-up (#363 Phase 2)", () => {
     expect(await getCount(groupX)).toBe(1); // #443 fixed: fenced count re-check re-replayed the missed low-id event
   });
 
+  test("(656/1) a clean rebuild with no concurrency does not trigger the #443 recompute", async () => {
+    // The #443 shortfall-recompute rebuilds the shadow a 2nd time and re-replays
+    // the whole log — correct on the rare path it guards, but a silent perf
+    // regression if it fired on every rebuild. Its final values are identical
+    // either way (full re-replay is idempotent), so only a call-count seam can
+    // prove it stayed off the happy path.
+    const group = "00000000-0000-4000-8000-000000000203";
+    await appendCreatedEvent(group, "a");
+    await appendCreatedEvent(group, "b");
+
+    let shadowBuilds = 0;
+    const result = await rebuildProjection(qualifiedProjectionName, {
+      db: testDb.db,
+      registry,
+      __test_onBuildShadowTable: () => {
+        shadowBuilds++;
+      },
+    });
+
+    expect(shadowBuilds).toBe(1);
+    expect(result.eventsProcessed).toBe(2);
+    expect(await getCount(group)).toBe(2);
+  });
+
   test("the rebuild tx sees concurrently-committed rows (READ COMMITTED, not a frozen snapshot)", async () => {
     // The catch-up loop only works if each fresh SELECT in the rebuild tx sees
     // rows other connections committed since the previous batch. Under

package/src/pipeline/__tests__/rebuild-poison-quarantine.integration.test.ts

@@ -0,0 +1,274 @@
+// #760 — poison-event quarantine during projection rebuild.
+//
+// A single historical event whose apply throws used to abort the WHOLE
+// rebuild (tx rollback, status failed) with no recovery path short of
+// hand-editing the event. With quarantine mode the rebuild confines each
+// apply to a savepoint: the poison event is skipped, recorded into
+// kumiko_rebuild_dead_letters, and the replay completes.
+//
+// Covers both rebuild flavors:
+//   - single-stream: RebuildDeps.errorPolicy.skipApplyErrors (per run)
+//   - MSP: MspErrorMode.rebuild.skipApplyErrors (per definition — declared
+//     API that was previously never honored by rebuildMultiStreamProjection)
+// and both poison flavors:
+//   - JS throw (no SQL executed)
+//   - SQL error (aborts the tx → proves the savepoint is load-bearing)
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { integer as pgInteger, table as pgTable, uuid as pgUuid } from "../../db/dialect";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { asRawClient } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { createEntity, createTextField, defineApply, defineFeature } from "../../engine";
+import type { ProjectionDefinition } from "../../engine/types";
+import { append, createEventsTable } from "../../event-store";
+import { listRebuildDeadLetters } from "../../event-store/rebuild-dead-letter";
+import {
+  createProjectionStateTable,
+  getConsumerState,
+  getProjectionState,
+  rebuildMultiStreamProjection,
+  rebuildProjection,
+} from "../../pipeline";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "../../stack";
+
+// --- Fixtures ---
+
+const POISON_JS = "poison-js";
+const POISON_SQL = "poison-sql";
+
+const itemEntity = createEntity({
+  table: "read_poison_items",
+  fields: {
+    groupId: createTextField({ required: true }),
+    name: createTextField({ required: true }),
+  },
+});
+const itemTable = buildEntityTable("poison-item", itemEntity);
+
+const counterTable = pgTable("read_poison_counter", {
+  groupId: pgUuid("group_id").primaryKey(),
+  tenantId: pgUuid("tenant_id").notNull(),
+  itemCount: pgInteger("item_count").notNull().default(0),
+});
+
+const mspCounterTable = pgTable("read_poison_msp_counter", {
+  groupId: pgUuid("group_id").primaryKey(),
+  tenantId: pgUuid("tenant_id").notNull(),
+  itemCount: pgInteger("item_count").notNull().default(0),
+});
+
+async function bump(tx: unknown, tableName: string, groupId: string, tenantId: string) {
+  await asRawClient(tx).unsafe(
+    `INSERT INTO "${tableName}" (group_id, tenant_id, item_count) VALUES ($1::uuid, $2::uuid, 1) ON CONFLICT (group_id) DO UPDATE SET item_count = "${tableName}".item_count + 1`,
+    [groupId, tenantId],
+  );
+}
+
+// Poison by payload marker. POISON_SQL runs a genuinely failing statement so
+// the surrounding tx would be in 25P02 without the savepoint.
+async function applyOrPoison(
+  tx: unknown,
+  tableName: string,
+  payload: { groupId: string; name: string },
+  tenantId: string,
+): Promise<void> {
+  if (payload.name === POISON_JS) throw new Error("intentional js poison");
+  if (payload.name === POISON_SQL) {
+    await asRawClient(tx).unsafe(
+      `INSERT INTO "${tableName}" (group_id, tenant_id, item_count) VALUES ('not-a-uuid', $1::uuid, 1)`,
+      [tenantId],
+    );
+    return;
+  }
+  await bump(tx, tableName, payload.groupId, tenantId);
+}
+
+type ItemPayload = { groupId: string; name: string };
+
+const poisonProjection: ProjectionDefinition = {
+  name: "poison-counter",
+  source: "poison-item",
+  table: counterTable,
+  apply: {
+    "poison-item.created": defineApply<ItemPayload>(async (event, tx) => {
+      await applyOrPoison(tx, "read_poison_counter", event.payload, event.tenantId);
+    }),
+  },
+};
+
+const MSP_EVENT_SHORT = "poison-noted";
+
+const feature = defineFeature("poisontest", (r) => {
+  r.entity("poison-item", itemEntity);
+  r.projection(poisonProjection);
+  const noted = r.defineEvent(MSP_EVENT_SHORT, z.object({ groupId: z.uuid(), name: z.string() }));
+  r.multiStreamProjection({
+    name: "poison-msp-counter",
+    table: mspCounterTable,
+    errorMode: { rebuild: { skipApplyErrors: true } },
+    apply: {
+      [noted.name]: async (event, tx) => {
+        const p = event.payload as ItemPayload; // @cast-boundary engine-payload
+        await applyOrPoison(tx, "read_poison_msp_counter", p, event.tenantId);
+      },
+    },
+  });
+});
+
+const admin = TestUsers.admin;
+const PROJECTION = "poisontest:projection:poison-counter";
+const MSP = "poisontest:projection:poison-msp-counter";
+const MSP_EVENT = "poisontest:event:poison-noted";
+const GROUP = "00000000-0000-4000-8000-00000000cafe";
+
+let stack: TestStack;
+let tdb: TenantDb;
+
+const executor = createEventStoreExecutor(itemTable, itemEntity, { entityName: "poison-item" });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+  await unsafeCreateEntityTable(stack.db, itemEntity, "poison-item");
+  await createEventsTable(stack.db);
+  await createProjectionStateTable(stack.db);
+  await unsafePushTables(stack.db, {
+    poisonCounter: counterTable,
+    poisonMspCounter: mspCounterTable,
+  });
+  tdb = createTenantDb(stack.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(
+    `TRUNCATE kumiko_events, read_poison_items, read_poison_counter, read_poison_msp_counter, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+  await asRawClient(stack.db).unsafe(`DROP TABLE IF EXISTS kumiko_rebuild_dead_letters`);
+  if (stack.eventDispatcher) await stack.eventDispatcher.ensureRegistered();
+});
+
+async function createItem(name: string): Promise<void> {
+  await executor.create({ groupId: GROUP, name }, admin, tdb);
+}
+
+async function getCount(table: string): Promise<number | undefined> {
+  const rows = (await asRawClient(stack.db).unsafe(
+    `SELECT item_count FROM "${table}" WHERE group_id = $1::uuid`,
+    [GROUP],
+  )) as ReadonlyArray<{ item_count: number }>;
+  return rows[0]?.item_count;
+}
+
+describe("rebuildProjection — poison event, strict default (#760)", () => {
+  test("apply throw aborts the rebuild: status failed, no dead letters", async () => {
+    await createItem("good-1");
+    await createItem(POISON_JS);
+    await createItem("good-2");
+
+    await expect(
+      rebuildProjection(PROJECTION, { db: stack.db, registry: stack.registry }),
+    ).rejects.toThrow("intentional js poison");
+
+    const state = await getProjectionState(stack.db, PROJECTION);
+    expect(state?.status).toBe("failed");
+    // Strict mode never provisions/records dead letters.
+    const rows = (await asRawClient(stack.db).unsafe(
+      `SELECT to_regclass('public.kumiko_rebuild_dead_letters') AS t`,
+    )) as ReadonlyArray<{ t: string | null }>;
+    expect(rows[0]?.t).toBeNull();
+  });
+});
+
+describe("rebuildProjection — quarantine mode (#760)", () => {
+  test("js- and sql-poison events are skipped, recorded, and the rebuild completes", async () => {
+    await createItem("good-1");
+    await createItem(POISON_JS);
+    // sql-poison proves the savepoint: without it the failed statement puts
+    // the whole rebuild tx into 25P02 and every later apply fails too.
+    await createItem(POISON_SQL);
+    await createItem("good-2");
+
+    const result = await rebuildProjection(PROJECTION, {
+      db: stack.db,
+      registry: stack.registry,
+      errorPolicy: { skipApplyErrors: true },
+    });
+
+    expect(result.eventsSkipped).toBe(2);
+    expect(result.eventsProcessed).toBe(4);
+    expect(await getCount("read_poison_counter")).toBe(2);
+
+    const state = await getProjectionState(stack.db, PROJECTION);
+    expect(state?.status).toBe("idle");
+
+    const deadLetters = await listRebuildDeadLetters(stack.db, { projectionName: PROJECTION });
+    expect(deadLetters).toHaveLength(2);
+    const messages = deadLetters.map((d) => d.errorMessage).sort();
+    expect(messages[0]).toContain("poison");
+    expect(deadLetters.every((d) => d.eventType === "poison-item.created")).toBe(true);
+    expect(deadLetters.every((d) => d.aggregateType === "poison-item")).toBe(true);
+  });
+
+  test("clean run in quarantine mode: zero skipped, no dead letters", async () => {
+    await createItem("good-1");
+    await createItem("good-2");
+
+    const result = await rebuildProjection(PROJECTION, {
+      db: stack.db,
+      registry: stack.registry,
+      errorPolicy: { skipApplyErrors: true },
+    });
+
+    expect(result.eventsSkipped).toBe(0);
+    expect(await getCount("read_poison_counter")).toBe(2);
+    expect(await listRebuildDeadLetters(stack.db, { projectionName: PROJECTION })).toHaveLength(0);
+  });
+});
+
+describe("rebuildMultiStreamProjection — errorMode.rebuild.skipApplyErrors (#760)", () => {
+  async function appendMspEvent(name: string, expectedVersion: number): Promise<void> {
+    await append(stack.db, {
+      aggregateId: GROUP,
+      aggregateType: "poison-note",
+      tenantId: admin.tenantId,
+      expectedVersion,
+      type: MSP_EVENT,
+      payload: { groupId: GROUP, name },
+      metadata: { userId: admin.id },
+    });
+  }
+
+  test("declared rebuild policy is honored: poison skipped + recorded, cursor advanced", async () => {
+    await appendMspEvent("good-1", 0);
+    await appendMspEvent(POISON_SQL, 1);
+    await appendMspEvent("good-2", 2);
+
+    const result = await rebuildMultiStreamProjection(MSP, {
+      db: stack.db,
+      registry: stack.registry,
+    });
+
+    expect(result.eventsSkipped).toBe(1);
+    expect(result.eventsProcessed).toBe(3);
+    expect(await getCount("read_poison_msp_counter")).toBe(2);
+
+    const deadLetters = await listRebuildDeadLetters(stack.db, { projectionName: MSP });
+    expect(deadLetters).toHaveLength(1);
+    expect(deadLetters[0]?.eventType).toBe(MSP_EVENT);
+
+    const consumer = await getConsumerState(stack.db, MSP);
+    expect(consumer?.lastProcessedEventId).toBe(result.lastProcessedEventId);
+  });
+});