@cosmicdrift/kumiko-framework 0.304.0 → 0.306.0

package/src/pipeline/__tests__/ctx-bridge.integration.test.ts

@@ -177,35 +177,52 @@ const bridgeFeature = defineFeature("ctxbridge", (r) => {
     },
   );
 
-  // Records whether ctx.db threw (should, once the request signal is
-  // aborted) and whether the ctx.dbOutsideTransaction insert still landed
-  // (should — durability writes must survive a client disconnect).
-  //
-  // The throwing side reads via ctx.db.selectMany, not the event-store
-  // executor's create() — the latter writes through db.raw (bypassing
-  // TenantDb's withDbSpan/signal check entirely), so it wouldn't exercise
-  // the signal wiring this test is meant to prove. insertOne isn't an
-  // option either: bagTable is executor-managed (WritableTable rejects its
-  // EXECUTOR_ONLY brand) — direct writes would drift it past its event
-  // stream. selectMany has no such restriction (reads keep the plain
-  // SchemaTable param) and still goes through the same signal check.
+  // Proves runBatch strips the request signal: both inserts land and
+  // ctx.signal is undefined even though the request was pre-aborted.
   r.writeHandler(
     "bag:create-signal-probe",
     z.object({ label: z.string() }),
     async (event, ctx) => {
       const crud = createEventStoreExecutor(bagTable, bagEntity, { entityName: "bag" });
-      let dbThrewAbortError = false;
-      try {
-        await ctx.db?.selectMany(bagTable, {});
-      } catch (err) {
-        dbThrewAbortError = err instanceof Error && err.name === "AbortError";
-      }
+      await ctx.db?.selectMany(bagTable, {});
+      await crud.create({ label: `${event.payload.label}-inside-tx` }, event.user, ctx.db);
       const outsideTx = ctx.dbOutsideTransaction;
       if (!outsideTx) {
         throw new Error("bag:create-signal-probe requires ctx.dbOutsideTransaction");
       }
       await crud.create({ label: `${event.payload.label}-outside-tx` }, event.user, outsideTx);
-      return { isSuccess: true as const, data: { dbThrewAbortError } };
+      return { isSuccess: true as const, data: { signalSeen: ctx.signal !== undefined } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Query path counterpart — ctx.db.selectMany hits signal.throwIfAborted().
+  r.queryHandler(
+    "bag:list-signal-probe",
+    z.object({}),
+    async (_query, ctx) => selectMany(ctx.db, bagTable),
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Negative control: never touches ctx.db, so a pre-aborted signal must still 500.
+  r.queryHandler(
+    "bag:query-boom",
+    z.object({}),
+    async () => {
+      throw new Error("unrelated boom");
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Pre-write ctx.db read — crud.create's own insert writes via db.raw and
+  // doesn't check the signal, so this is what makes the test discriminating.
+  r.writeHandler(
+    "bag:create-plain",
+    z.object({ label: z.string() }),
+    async (event, ctx) => {
+      await ctx.db?.selectMany(bagTable, {});
+      const crud = createEventStoreExecutor(bagTable, bagEntity, { entityName: "bag" });
+      return crud.create(event.payload, event.user, ctx.db);
     },
     { access: { roles: ["Admin"] } },
   );
@@ -366,7 +383,7 @@ describe("ctx.dbOutsideTransaction", () => {
     expect(labels).toEqual(["probe-outside-tx"]);
   });
 
-  test("an already-aborted request signal fails ctx.db but not ctx.dbOutsideTransaction", async () => {
+  test("an already-aborted request signal still commits both ctx.db and ctx.dbOutsideTransaction writes", async () => {
     const controller = new AbortController();
     controller.abort();
     const token = await stack.jwt.sign(admin);
@@ -385,16 +402,86 @@ describe("ctx.dbOutsideTransaction", () => {
 
     const body = (await res.json()) as {
       isSuccess: boolean;
-      data?: { dbThrewAbortError: boolean };
+      data?: { signalSeen: boolean };
     };
     expect(body.isSuccess).toBe(true);
-    expect(body.data?.dbThrewAbortError).toBe(true);
+    expect(body.data?.signalSeen).toBe(false);
 
-    // Only the outside-tx insert landed — ctx.db's insert threw before it
-    // could write, and there was nothing to roll back for it.
+    // Both inserts landed — the client's disconnect doesn't touch the write.
     const bags = await selectMany(stack.db, bagTable);
-    const labels = (bags as Array<Record<string, unknown>>).map((row) => row["label"]);
-    expect(labels).toEqual(["signal-probe-outside-tx"]);
+    const labels = (bags as Array<Record<string, unknown>>).map((row) => row["label"]).sort();
+    expect(labels).toEqual(["signal-probe-inside-tx", "signal-probe-outside-tx"]);
+  });
+
+  test("an already-aborted signal doesn't stop idempotent retries from committing", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const token = await stack.jwt.sign(admin);
+    const requestId = "retry-under-abort-1";
+
+    const requestOptions = {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+      body: JSON.stringify({
+        type: "ctxbridge:write:bag:create-plain",
+        payload: { label: "retried" },
+        requestId,
+      }),
+      signal: controller.signal,
+    } as const;
+
+    const first = await stack.app.request(
+      new Request("http://test.local/api/write", requestOptions),
+    );
+    const second = await stack.app.request(
+      new Request("http://test.local/api/write", requestOptions),
+    );
+
+    expect((await first.json()).isSuccess).toBe(true);
+    expect((await second.json()).isSuccess).toBe(true);
+
+    const bags = await selectMany(stack.db, bagTable);
+    expect(bags).toHaveLength(1);
+  });
+});
+
+describe("query dispatch surfaces a client abort as 499, not a server fault", () => {
+  test("a pre-aborted signal 499s instead of 500ing", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const token = await stack.jwt.sign(admin);
+
+    const res = await stack.app.request(
+      new Request("http://test.local/api/query", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+          type: "ctxbridge:query:bag:list-signal-probe",
+          payload: {},
+        }),
+        signal: controller.signal,
+      }),
+    );
+    expect(res.status).toBe(499);
+  });
+
+  test("a pre-aborted signal still 500s when the handler fails for an unrelated reason", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const token = await stack.jwt.sign(admin);
+
+    const res = await stack.app.request(
+      new Request("http://test.local/api/query", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+          type: "ctxbridge:query:bag:query-boom",
+          payload: {},
+        }),
+        signal: controller.signal,
+      }),
+    );
+    expect(res.status).toBe(500);
   });
 });
 

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

@@ -1082,5 +1082,10 @@ function createMockIdempotencyGuard() {
       pendingTokens.delete(key);
       results.set(key, JSON.stringify(result));
     },
+    async release(tenantId: string, userId: string, requestId: string, token: string) {
+      const key = `${tenantId}:${userId}:${requestId}`;
+      if (pendingTokens.get(key) !== token) return;
+      pendingTokens.delete(key);
+    },
   };
 }

package/src/pipeline/__tests__/hook-systemdb-escape-hatch.integration.test.ts

@@ -0,0 +1,246 @@
+// fw#3198 — a postSave hook's OWN `escapeHatch` must gate ctx.systemDb.unsafeRaw
+// inside a r.systemScope() handler's write, not the handler's (absent) grant.
+// Real HTTP calls + setupTestStack — never createTestDispatcher. Modelled on
+// entity-write-crosstenant.integration.test.ts (tier-engine's
+// ctx.systemDb.unsafeRaw + createTenantDb(raw, otherTenantId, "system") pattern)
+// and escape-hatch-audit.integration.test.ts (recordingSink for EscapeHatchUseEvent).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { defineUnmanagedTable } from "../../db/entity-table-meta";
+import { selectMany } from "../../db/query";
+import { createTenantDb } from "../../db/tenant-db";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineFeature,
+  HookPhases,
+} from "../../engine";
+import type { EscapeHatchUseEvent } from "../../engine/types";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "../../stack";
+
+const OTHER_TENANT_ID = testTenantId(2);
+const HOOK_ESCAPE_HATCH_REASON = "fw#3198 integration test — hook's own cross-tenant audit write";
+const NO_HOOK_ESCAPE_HATCH_REASON = "fw#3198 integration test — hook declared no escapeHatch";
+
+const auditTable = defineUnmanagedTable({
+  tableName: "store_fw3198_hook_systemdb_audit",
+  columns: [
+    {
+      name: "id",
+      pgType: "uuid",
+      notNull: true,
+      primaryKey: true,
+      defaultSql: "gen_random_uuid()",
+    },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "note", pgType: "text", notNull: true },
+  ],
+});
+
+type ThingMode =
+  | "escapeHatch-unsafe-raw"
+  | "escapeHatch-ack-unsafe-raw"
+  | "no-escapeHatch-unsafe-raw"
+  | "no-escapeHatch-ack-unsafe-raw"
+  | "no-escapeHatch-ack-crud";
+
+const thingEntity = createEntity({
+  table: "hooksys3198_things",
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+    mode: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+  access: { write: { Admin: "all" } },
+});
+
+// Feature A: r.systemScope() handler whose postSave fires with ctx.systemDb present —
+// mirrors tenant/feature.ts (r.systemScope() + entity + create handler).
+const featureA = defineFeature("hooksys3198-a", (r) => {
+  r.systemScope();
+  r.entity("thing", thingEntity);
+  r.writeHandler(defineEntityCreateHandler("thing", thingEntity, { access: { roles: ["Admin"] } }));
+});
+
+function modeOf(result: unknown): ThingMode | undefined {
+  const saveResult = result as { isNew?: unknown; data?: unknown };
+  if (saveResult.isNew !== true) return undefined;
+  const data = saveResult.data as { mode?: unknown };
+  return typeof data.mode === "string" ? (data.mode as ThingMode) : undefined;
+}
+
+function labelOf(result: unknown): string {
+  const saveResult = result as { data?: unknown };
+  const data = saveResult.data as { label?: unknown };
+  return typeof data.label === "string" ? data.label : "";
+}
+
+// Feature B: NOT systemScope, hooks cross-feature onto A's "thing" entity — same
+// shape as tier-engine's hook on the "tenant" feature's entity.
+const featureB = defineFeature("hooksys3198-b", (r) => {
+  r.storeTable(auditTable, {
+    reason:
+      "fw#3198 integration test — cross-tenant audit row written from a hook's own escapeHatch",
+  });
+
+  r.hook(
+    "postSave",
+    { allOf: "thing" },
+    async (result, ctx) => {
+      const mode = modeOf(result);
+      if (mode !== "escapeHatch-unsafe-raw" && mode !== "escapeHatch-ack-unsafe-raw") return;
+      if (!ctx.systemDb) return;
+      const rawDb =
+        mode === "escapeHatch-unsafe-raw"
+          ? ctx.systemDb.unsafeRaw(HOOK_ESCAPE_HATCH_REASON)
+          : ctx.systemDb
+              .acknowledgeCrossTenant(HOOK_ESCAPE_HATCH_REASON)
+              .unsafeRaw(HOOK_ESCAPE_HATCH_REASON);
+      const otherTenantDb = createTenantDb(rawDb, OTHER_TENANT_ID, "system");
+      await otherTenantDb.insertOne(auditTable, { note: `${mode}:${labelOf(result)}` });
+    },
+    { escapeHatch: { reason: HOOK_ESCAPE_HATCH_REASON } },
+    // phase defaults to afterCommit
+  );
+
+  r.hook(
+    "postSave",
+    { allOf: "thing" },
+    async (result, ctx) => {
+      const mode = modeOf(result);
+      if (!ctx.systemDb) return;
+      if (mode === "no-escapeHatch-unsafe-raw") {
+        const rawDb = ctx.systemDb.unsafeRaw(NO_HOOK_ESCAPE_HATCH_REASON);
+        const otherTenantDb = createTenantDb(rawDb, OTHER_TENANT_ID, "system");
+        await otherTenantDb.insertOne(auditTable, { note: `${mode}:${labelOf(result)}` });
+      } else if (mode === "no-escapeHatch-ack-unsafe-raw") {
+        const rawDb = ctx.systemDb
+          .acknowledgeCrossTenant(NO_HOOK_ESCAPE_HATCH_REASON)
+          .unsafeRaw(NO_HOOK_ESCAPE_HATCH_REASON);
+        const otherTenantDb = createTenantDb(rawDb, OTHER_TENANT_ID, "system");
+        await otherTenantDb.insertOne(auditTable, { note: `${mode}:${labelOf(result)}` });
+      } else if (mode === "no-escapeHatch-ack-crud") {
+        const db = ctx.systemDb.acknowledgeCrossTenant(NO_HOOK_ESCAPE_HATCH_REASON);
+        await db.insertOne(auditTable, {
+          tenantId: OTHER_TENANT_ID,
+          note: `${mode}:${labelOf(result)}`,
+        });
+      }
+    },
+    { phase: HookPhases.inTransaction },
+  );
+});
+
+function recordingSink(events: EscapeHatchUseEvent[]) {
+  return async (event: EscapeHatchUseEvent) => {
+    events.push(event);
+  };
+}
+
+async function auditNotesFor(
+  label: string,
+): Promise<ReadonlyArray<{ tenantId: string; note: string }>> {
+  const rows = await selectMany<{ tenantId: string; note: string }>(stack.db, auditTable, {});
+  return rows.filter((r) => r.note.endsWith(`:${label}`));
+}
+
+let stack: TestStack;
+const escapeHatchAuditEvents: EscapeHatchUseEvent[] = [];
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [featureA, featureB],
+    extraContext: { _escapeHatchAuditSink: recordingSink(escapeHatchAuditEvents) },
+  });
+  await unsafeCreateEntityTable(stack.db, thingEntity, "thing");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("a postSave hook's own escapeHatch gates ctx.systemDb.unsafeRaw (fw#3198)", () => {
+  test("afterCommit, WITH escapeHatch, ctx.systemDb.unsafeRaw: cross-tenant audit row lands, reported as unsafe-raw", async () => {
+    escapeHatchAuditEvents.length = 0;
+    const label = `label-${crypto.randomUUID()}`;
+    await stack.http.writeOk(
+      "hooksys3198-a:write:thing:create",
+      { label, mode: "escapeHatch-unsafe-raw" },
+      TestUsers.admin,
+    );
+
+    const rows = await auditNotesFor(label);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.tenantId).toBe(OTHER_TENANT_ID);
+
+    const matches = escapeHatchAuditEvents.filter((e) => e.kind === "unsafe-raw");
+    expect(matches).toEqual([
+      {
+        handler: "hooksys3198-a:write:thing:create",
+        kind: "unsafe-raw",
+        reason: HOOK_ESCAPE_HATCH_REASON,
+        tenantId: TestUsers.admin.tenantId,
+        actor: TestUsers.admin.id,
+        target: undefined,
+      },
+    ]);
+  });
+
+  test("afterCommit, WITH escapeHatch, ctx.systemDb.acknowledgeCrossTenant(...).unsafeRaw: cross-tenant audit row lands (the reported issue path)", async () => {
+    const label = `label-${crypto.randomUUID()}`;
+    await stack.http.writeOk(
+      "hooksys3198-a:write:thing:create",
+      { label, mode: "escapeHatch-ack-unsafe-raw" },
+      TestUsers.admin,
+    );
+
+    const rows = await auditNotesFor(label);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.tenantId).toBe(OTHER_TENANT_ID);
+  });
+
+  test("inTransaction, WITHOUT escapeHatch, ctx.systemDb.unsafeRaw: denied, no audit row", async () => {
+    const label = `label-${crypto.randomUUID()}`;
+    const err = await stack.http.writeErr(
+      "hooksys3198-a:write:thing:create",
+      { label, mode: "no-escapeHatch-unsafe-raw" },
+      TestUsers.admin,
+    );
+    expect(err.code).toBe("access_denied");
+
+    const rows = await auditNotesFor(label);
+    expect(rows).toHaveLength(0);
+  });
+
+  test("inTransaction, WITHOUT escapeHatch, ctx.systemDb.acknowledgeCrossTenant(...).unsafeRaw: denied, no audit row", async () => {
+    const label = `label-${crypto.randomUUID()}`;
+    const err = await stack.http.writeErr(
+      "hooksys3198-a:write:thing:create",
+      { label, mode: "no-escapeHatch-ack-unsafe-raw" },
+      TestUsers.admin,
+    );
+    expect(err.code).toBe("access_denied");
+
+    const rows = await auditNotesFor(label);
+    expect(rows).toHaveLength(0);
+  });
+
+  test("inTransaction, WITHOUT escapeHatch, ctx.systemDb.acknowledgeCrossTenant(...) typed CRUD: still works (regression)", async () => {
+    const label = `label-${crypto.randomUUID()}`;
+    await stack.http.writeOk(
+      "hooksys3198-a:write:thing:create",
+      { label, mode: "no-escapeHatch-ack-crud" },
+      TestUsers.admin,
+    );
+
+    const rows = await auditNotesFor(label);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.tenantId).toBe(OTHER_TENANT_ID);
+  });
+});

package/src/pipeline/__tests__/idempotency-transient-failure.integration.test.ts

@@ -0,0 +1,198 @@
+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 { UnprocessableError, writeFailure } from "../../errors";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+
+const probeEntity = createEntity({
+  table: "idempotency_transient_probes",
+  fields: {
+    label: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+const probeTable = buildEntityTable("probe", probeEntity);
+
+const batchItemEntity = createEntity({
+  table: "idempotency_transient_batch_items",
+  fields: {
+    label: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+const batchItemTable = buildEntityTable("batchItem", batchItemEntity);
+
+// Reset per test — counts real handler invocations so a cached replay
+// (no re-invocation) is distinguishable from a genuine retry.
+let transientCallCount = 0;
+let unprocessableCallCount = 0;
+let batchTransientCallCount = 0;
+
+const transientFailureFeature = defineFeature("idempotencytransient", (r) => {
+  r.entity("probe", probeEntity);
+  r.entity("batchItem", batchItemEntity);
+
+  // Inserts via ctx.db, then throws on its first invocation only — the
+  // insert lands inside the (later rolled-back) transaction, so a retry
+  // must not see a leftover row from the failed attempt.
+  r.writeHandler(
+    "probe:create-transient-once",
+    z.object({ label: z.string() }),
+    async (event, ctx) => {
+      transientCallCount++;
+      const crud = createEventStoreExecutor(probeTable, probeEntity, { entityName: "probe" });
+      const created = await crud.create(event.payload, event.user, ctx.db);
+      if (transientCallCount === 1) {
+        throw new Error("transient boom");
+      }
+      return created;
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "probe:create-always-rejected",
+    z.object({ label: z.string() }),
+    async () => {
+      unprocessableCallCount++;
+      return writeFailure(new UnprocessableError("always_rejected"));
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "batch-item:create",
+    z.object({ label: z.string() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(batchItemTable, batchItemEntity, {
+        entityName: "batchItem",
+      });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "probe:create-batch-transient-once",
+    z.object({ label: z.string() }),
+    async (event, ctx) => {
+      batchTransientCallCount++;
+      const crud = createEventStoreExecutor(probeTable, probeEntity, { entityName: "probe" });
+      const created = await crud.create(event.payload, event.user, ctx.db);
+      if (batchTransientCallCount === 1) {
+        throw new Error("transient boom in batch");
+      }
+      return created;
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [transientFailureFeature] });
+  await unsafeCreateEntityTable(stack.db, probeEntity);
+  await unsafeCreateEntityTable(stack.db, batchItemEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  transientCallCount = 0;
+  unprocessableCallCount = 0;
+  batchTransientCallCount = 0;
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${probeTable.tableName}"`);
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${batchItemTable.tableName}"`);
+  await stack.redis.flushNamespace();
+});
+
+describe("idempotent retry after a rolled-back transient 5xx", () => {
+  test("write: first call fails with internal_error, retry with the same requestId succeeds", async () => {
+    const requestId = "req-transient-5xx-1";
+
+    const first = await stack.http.write(
+      "idempotencytransient:write:probe:create-transient-once",
+      { label: "attempt-1" },
+      admin,
+      requestId,
+    );
+    const firstBody = (await first.json()) as { isSuccess: boolean; error?: { code?: string } };
+    expect(firstBody.isSuccess).toBe(false);
+    expect(firstBody.error?.code).toBe("internal_error");
+
+    const second = await stack.http.write(
+      "idempotencytransient:write:probe:create-transient-once",
+      { label: "attempt-1" },
+      admin,
+      requestId,
+    );
+    const secondBody = (await second.json()) as { isSuccess: boolean };
+    expect(secondBody.isSuccess).toBe(true);
+
+    expect(transientCallCount).toBe(2);
+    const rows = await selectMany(stack.db, probeTable);
+    expect(rows).toHaveLength(1);
+  });
+
+  test("write: a deterministic 4xx rejection stays cached — retry returns the identical body without re-invoking the handler", async () => {
+    const requestId = "req-4xx-cached-1";
+
+    const first = await stack.http.write(
+      "idempotencytransient:write:probe:create-always-rejected",
+      { label: "rejected" },
+      admin,
+      requestId,
+    );
+    const firstBody = (await first.json()) as {
+      isSuccess: boolean;
+      error?: { code?: string; message?: string; details?: unknown };
+    };
+
+    const second = await stack.http.write(
+      "idempotencytransient:write:probe:create-always-rejected",
+      { label: "rejected" },
+      admin,
+      requestId,
+    );
+    const secondBody = (await second.json()) as typeof firstBody;
+
+    // Compare the cached payload, not the wire envelope — the response
+    // carries a fresh per-HTTP-call requestId/timestamp on every replay,
+    // both from the same cached idempotency entry.
+    expect(secondBody.isSuccess).toBe(false);
+    expect(secondBody.error?.code).toEqual(firstBody.error?.code);
+    expect(secondBody.error?.message).toEqual(firstBody.error?.message);
+    expect(secondBody.error?.details).toEqual(firstBody.error?.details);
+    expect(unprocessableCallCount).toBe(1);
+  });
+
+  test("batch: a rolled-back transient 5xx on one command doesn't block a retry, and the rolled-back first command lands exactly once", async () => {
+    const requestId = "req-batch-transient-5xx-1";
+    const commands = [
+      { type: "idempotencytransient:write:batch-item:create", payload: { label: "item-1" } },
+      {
+        type: "idempotencytransient:write:probe:create-batch-transient-once",
+        payload: { label: "probe-1" },
+      },
+    ];
+
+    const first = await stack.http.batch(commands, admin, requestId);
+    const firstBody = (await first.json()) as { isSuccess: boolean };
+    expect(firstBody.isSuccess).toBe(false);
+
+    const second = await stack.http.batch(commands, admin, requestId);
+    const secondBody = (await second.json()) as { isSuccess: boolean };
+    expect(secondBody.isSuccess).toBe(true);
+
+    expect(batchTransientCallCount).toBe(2);
+    const batchItems = await selectMany(stack.db, batchItemTable);
+    expect(batchItems).toHaveLength(1);
+    const probes = await selectMany(stack.db, probeTable);
+    expect(probes).toHaveLength(1);
+  });
+});