@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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);
+  });
+});

package/src/pipeline/__tests__/try-append-event.integration.test.ts

@@ -0,0 +1,166 @@
+// Issue #1038 — ctx.tryAppendEvent (savepoint-scoped append).
+//
+// Claims pinned here:
+//   1. Happy path: first append on a fresh aggregate succeeds, returns
+//      { ok: true, event } with the stored event.
+//   2. Non-poisoning: when tryAppendEvent loses a version-conflict race, the
+//      rest of the handler's transaction still commits (a write AFTER the
+//      call in the same handler is not rolled back) — this is the whole
+//      reason the primitive exists over a bare try/catch around
+//      unsafeAppendEvent (Bun.SQL/postgres.js abort the entire begin() on
+//      an uncaught statement error, SQLSTATE 25P02, even if the JS error is
+//      caught).
+//
+// The conflict branch can't be forced deterministically through the public
+// interface — appendDomainEventCore reads the stream version fresh inside
+// itself, so a lone sequential append never conflicts; only two concurrent
+// transactions racing the same version produce the 23505. So claim 2 is
+// tested as an invariant over concurrent writers (looped per house
+// convention for probabilistic tests) rather than by asserting the conflict
+// branch was hit on a specific call — depending on interleaving, Postgres
+// may pick either writer as the winner.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { asRawClient, selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import { loadAggregate } from "../../event-store";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+
+const TAE_AGGREGATE_TYPE = "taeDoc";
+
+// Marker entity — a plain CRUD write issued right after ctx.tryAppendEvent
+// in the same handler/transaction. Its row landing (regardless of whether
+// the append won or lost the race) is the non-poisoning proof.
+const markerEntity = createEntity({
+  table: "tae_markers",
+  fields: {
+    note: createTextField({ required: true }),
+  },
+});
+const markerTable = buildEntityTable("taeMarker", markerEntity);
+const markerExecutor = createEventStoreExecutor(markerTable, markerEntity, {
+  entityName: "taeMarker",
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+const tryAppendFeature = defineFeature("tae", (r) => {
+  r.entity("taeMarker", markerEntity);
+  const appended = r.defineEvent("appended", z.object({ note: z.string() }));
+
+  r.writeHandler(
+    "doc:try-append",
+    z.object({ aggregateId: z.uuid(), note: z.string() }),
+    async (event, ctx) => {
+      const result = await ctx.tryAppendEvent({
+        aggregateId: event.payload.aggregateId,
+        aggregateType: TAE_AGGREGATE_TYPE,
+        type: appended.name,
+        payload: { note: event.payload.note },
+      });
+      // Runs unconditionally — if tryAppendEvent's savepoint failed to
+      // confine the VersionConflictError, this write would fail too
+      // because the whole tx aborted (25P02).
+      const markerCreated = await markerExecutor.create(
+        { note: event.payload.note },
+        event.user,
+        ctx.db,
+      );
+      if (!markerCreated.isSuccess) return markerCreated;
+      return {
+        isSuccess: true as const,
+        data: {
+          ok: result.ok,
+          version: result.ok ? result.event.version : null,
+        },
+      };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [tryAppendFeature] });
+  await unsafeCreateEntityTable(stack.db, markerEntity, "taeMarker");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(
+    `TRUNCATE kumiko_events, "${markerTable.tableName}" RESTART IDENTITY CASCADE`,
+  );
+});
+
+describe("Issue #1038 — ctx.tryAppendEvent", () => {
+  test("happy path: first append on a fresh aggregate returns { ok: true, event }", async () => {
+    const aggregateId = crypto.randomUUID();
+
+    const result = await stack.http.writeOk<{
+      ok: boolean;
+      version: number | null;
+    }>("tae:write:doc:try-append", { aggregateId, note: "hello" }, admin);
+
+    expect(result.ok).toBe(true);
+    expect(result.version).toBe(1);
+
+    const events = await loadAggregate(stack.db, aggregateId, admin.tenantId);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.payload).toEqual({ note: "hello" });
+
+    const markers = await selectMany(stack.db, markerTable);
+    expect(markers).toHaveLength(1);
+  });
+
+  // Probabilistic — looped per house convention (mehrere Durchläufe, z.B.
+  // 20x) since a genuine 23505 race depends on transaction-timing
+  // interleaving that a single run can't force deterministically.
+  const ITERATIONS = 20;
+  const CONCURRENCY = 3;
+
+  test(`non-poisoning invariant holds across ${ITERATIONS} concurrent-writer rounds`, async () => {
+    for (let i = 0; i < ITERATIONS; i++) {
+      const aggregateId = crypto.randomUUID();
+
+      const responses = await Promise.all(
+        Array.from({ length: CONCURRENCY }, (_, n) =>
+          stack.http.write("tae:write:doc:try-append", { aggregateId, note: `writer-${n}` }, admin),
+        ),
+      );
+
+      // No writer's transaction was poisoned by a losing append — every
+      // request completes as a normal 200, never a 500 from an aborted tx.
+      let okCount = 0;
+      for (const res of responses) {
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { isSuccess: boolean; data: { ok: boolean } };
+        expect(body.isSuccess).toBe(true);
+        if (body.data.ok) okCount++;
+      }
+
+      // One event per successful append — interleaving-independent
+      // invariant. Serialized (non-racing) writers can legitimately all
+      // succeed at different versions; only actual conflicts return
+      // { ok: false }, so events.length must track okCount, not a fixed 1.
+      const events = await loadAggregate(stack.db, aggregateId, admin.tenantId);
+      expect(events).toHaveLength(okCount);
+      expect(okCount).toBeGreaterThanOrEqual(1);
+
+      // Every writer's marker insert landed regardless of win/lose — the
+      // savepoint confined the losers' VersionConflictError instead of
+      // aborting their whole transaction.
+      const markers = await selectMany(stack.db, markerTable);
+      expect(markers).toHaveLength(CONCURRENCY);
+
+      await asRawClient(stack.db).unsafe(
+        `TRUNCATE kumiko_events, "${markerTable.tableName}" RESTART IDENTITY CASCADE`,
+      );
+    }
+  });
+});

package/src/pipeline/dispatch-batch.ts

@@ -0,0 +1,187 @@
+import type { DbConnection } from "../db/connection";
+import { transaction } from "../db/query";
+import type { DeleteContext, SaveContext, SessionUser, WriteResult } from "../engine/types";
+import { InternalError, toWriteErrorInfo, writeFailure } from "../errors";
+import { createFallbackLogger } from "../logging/utils";
+import { parseJsonSafe } from "../utils/safe-json";
+import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared";
+import { resolveDbSource } from "./dispatch-shared";
+import { executeNestedWrite } from "./dispatch-write";
+import {
+  type AfterCommitHook,
+  BatchRollback,
+  isLifecycleResult,
+  wrapToKumiko,
+} from "./dispatcher-utils";
+
+// Core batch logic extracted so write() and command() can reuse it
+// (a single write = batch of one, running in its own transaction).
+export async function runBatch(
+  ctx: DispatchContext,
+  commands: readonly BatchCommand[],
+  user: SessionUser,
+  requestId?: string,
+): Promise<BatchResult> {
+  const { idempotency, lifecycle, appContext: context } = ctx;
+  if (commands.length === 0) {
+    return { isSuccess: true, results: [] };
+  }
+
+  // Idempotency: if the same requestId has already been processed, return the
+  // cached result without re-executing. The cache holds the full BatchResult.
+  if (requestId && idempotency) {
+    const cached = await idempotency.check(requestId);
+    if (cached) {
+      const parsed = parseJsonSafe<BatchResult | null>(cached, null);
+      if (parsed) return parsed;
+      // corrupted cache entry — treat as miss, let the request re-run
+    }
+  }
+
+  // Wrap return paths: cache the final result under requestId so retries get
+  // the same answer (both success and failure results are cached).
+  const finalize = async (result: BatchResult): Promise<BatchResult> => {
+    if (requestId && idempotency) {
+      await idempotency.store(requestId, result);
+    }
+    return result;
+  };
+
+  const afterCommitHooks: AfterCommitHook[] = [];
+  const results: WriteResult[] = [];
+
+  // Flush afterCommit hooks in parallel. Errors are logged, not rethrown:
+  // the writes are already committed, we can't undo them.
+  //
+  // Parallelisation is safe because afterCommit hooks are deferred side-
+  // effects (e.g. feature-level postSave hooks in afterCommit phase)
+  // that don't depend on each other — the in-transaction work already ran
+  // sequentially inside the lifecycle pipeline where ordering matters. If a
+  // future hook ever needs ordering, it should do its sequencing internally
+  // (one hook pushing multiple sub-calls) rather than relying on the
+  // flush-loop order.
+  const flushAfterCommit = async () => {
+    const logError = createFallbackLogger("dispatcher", context.log);
+    const outcomes = await Promise.allSettled(afterCommitHooks.map((hook) => hook()));
+    for (const outcome of outcomes) {
+      if (outcome.status === "rejected") {
+        const detail =
+          outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+        logError.error("afterCommit hook failed", { error: detail });
+      }
+    }
+  };
+
+  // Fires the batch-level system hooks with every successful save/delete
+  // context from this run. Called after flushAfterCommit so per-save hooks
+  // have all completed first; errors are isolated inside lifecycleHooks.
+  const flushBatchHooks = async () => {
+    try {
+      const saves: SaveContext[] = [];
+      const deletes: DeleteContext[] = [];
+      for (const r of results) {
+        if (!r.isSuccess) continue;
+        if (!isLifecycleResult(r.data)) continue;
+        if (r.data.kind === "save") saves.push(r.data);
+        else if (r.data.kind === "delete") deletes.push(r.data);
+      }
+      if (saves.length > 0 && lifecycle) await lifecycle.runPostSaveBatch(saves, context);
+      if (deletes.length > 0 && lifecycle) await lifecycle.runPostDeleteBatch(deletes, context);
+    } catch (e) {
+      // Batch hooks must never fail the batch — the commit already happened.
+      // Pass the raw error so the logger preserves stack + cause chain;
+      // collapsing to .message hides exactly what ops needs to debug.
+      const logError = createFallbackLogger("dispatcher", context.log);
+      logError.error("batch hook flush failed", { error: e });
+    }
+  };
+
+  // batch() opens its own outer transaction — needs the top-level
+  // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
+  const db = resolveDbSource(ctx, undefined) as DbConnection | undefined;
+  if (!db) {
+    // Without a DB connection there is no transaction to open. Fall back to
+    // sequential execution — useful for unit tests that don't touch the DB.
+    // Each command runs independently; a failure stops the batch.
+    for (let i = 0; i < commands.length; i++) {
+      const cmd = commands[i];
+      if (!cmd) continue;
+      const res = await executeNestedWrite(
+        ctx,
+        cmd.type,
+        cmd.payload,
+        user,
+        undefined,
+        afterCommitHooks,
+      );
+      results.push(res);
+      if (!res.isSuccess) {
+        // No tx means no rollback — but we still drop afterCommit hooks,
+        // matching the semantic "failure = side-effects don't fire".
+        return finalize({ isSuccess: false, error: res.error, failedIndex: i, results });
+      }
+    }
+    await flushAfterCommit();
+    await flushBatchHooks();
+    return finalize({ isSuccess: true, results });
+  }
+
+  try {
+    await transaction(db, async (tx) => {
+      for (let i = 0; i < commands.length; i++) {
+        const cmd = commands[i];
+        if (!cmd) continue;
+        const res = await executeNestedWrite(
+          ctx,
+          cmd.type,
+          cmd.payload,
+          user,
+          tx,
+          afterCommitHooks,
+        );
+        results.push(res);
+        if (!res.isSuccess) {
+          throw new BatchRollback(i, res.error);
+        }
+      }
+    });
+  } catch (e) {
+    if (e instanceof BatchRollback) {
+      return finalize({
+        isSuccess: false,
+        error: e.failureError,
+        failedIndex: e.failedIndex,
+        results,
+      });
+    }
+    return finalize({
+      isSuccess: false,
+      error: toWriteErrorInfo(wrapToKumiko(e)),
+      failedIndex: results.length,
+      results,
+    });
+  }
+
+  // Commit succeeded — fire deferred side-effects.
+  await flushAfterCommit();
+  await flushBatchHooks();
+  return finalize({ isSuccess: true, results });
+}
+
+// Unwrap a BatchResult into a single WriteResult for write()/command().
+// Picks the first result on success (the only one for a single write), the
+// failing one on failure. Falls back to a synthetic error if the batch
+// didn't produce any results (unexpected).
+export function unwrapSingle(batchResult: BatchResult): WriteResult {
+  if (batchResult.isSuccess) {
+    return (
+      batchResult.results[0] ?? writeFailure(new InternalError({ message: "empty_batch_result" }))
+    );
+  }
+  return (
+    batchResult.results[batchResult.failedIndex] ?? {
+      isSuccess: false,
+      error: batchResult.error,
+    }
+  );
+}