@cosmicdrift/kumiko-framework 0.304.0 → 0.306.0

package/src/pipeline/__tests__/public-intake-runtime-gate.integration.test.ts

@@ -0,0 +1,425 @@
+// Every anonymous handler here keeps personal-data keys out of its own input schema,
+// so the static boot check passes and only the runtime gate can stop the write.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import type { SchemaTable } from "../../db";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { asRawClient, selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import type { TenantDb } from "../../db/tenant-db";
+import { createEntity, createSystemUser, createTextField, defineFeature } from "../../engine";
+import { SYSTEM_ROLE } from "../../engine/system-user";
+import type { TenantId } from "../../engine/types";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+const RATE_LIMIT = { per: "ip", limit: 1000, windowSeconds: 60 } as const;
+
+// --- Feature B: owns the PII-carrying entity ---
+
+const contactEntity = createEntity({
+  table: "intake_contacts",
+  fields: {
+    email: createTextField({ personal: "self", find: "none", default: "" }),
+    note: createTextField({ personal: false, reason: "test_fixture", default: "" }),
+  },
+});
+const contactTable = buildEntityTable("contact", contactEntity);
+
+// No `table:` override: the gate must resolve the default, entity-name-derived table.
+const leadEntity = createEntity({
+  fields: {
+    phone: createTextField({ personal: "self", find: "none", default: "" }),
+  },
+});
+const leadTable = buildEntityTable("intakeLead", leadEntity);
+
+const featureB = defineFeature("intakeb", (r) => {
+  r.entity("contact", contactEntity);
+  r.entity("intakeLead", leadEntity);
+
+  r.writeHandler(
+    "create-lead",
+    z.object({ phone: z.string() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(leadTable, leadEntity, { entityName: "intakeLead" });
+      return crud.create({ phone: event.payload.phone }, event.user, ctx.db);
+    },
+    { access: { roles: [SYSTEM_ROLE] } },
+  );
+
+  r.writeHandler(
+    "create",
+    z.object({ email: z.string(), note: z.string().optional() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(contactTable, contactEntity, { entityName: "contact" });
+      return crud.create(
+        { email: event.payload.email, note: event.payload.note ?? "" },
+        event.user,
+        ctx.db,
+      );
+    },
+    { access: { roles: [SYSTEM_ROLE] } },
+  );
+});
+
+// --- Feature A: anonymous entry points that try to leak B's PII by every route ---
+
+const probeEntity = createEntity({
+  table: "intake_probes",
+  fields: {
+    note: createTextField({ personal: false, reason: "test_fixture", required: true }),
+  },
+});
+const probeTable = buildEntityTable("probe", probeEntity);
+
+const featureA = defineFeature("intakea", (r) => {
+  r.entity("probe", probeEntity);
+
+  r.writeHandler(
+    "direct-insert-no-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      // @cast-boundary test-fixture — proving the RUNTIME gate stops this
+      // write, not the compile-time ExecutorOnly brand on contactTable.
+      await ctx.db.insertOne(contactTable as unknown as SchemaTable, {
+        email: "leak-direct@example.com",
+        note: event.payload.note,
+      });
+      return { isSuccess: true as const, data: { ok: true as const } };
+    },
+    { access: { roles: ["anonymous"] }, rateLimit: RATE_LIMIT },
+  );
+
+  r.writeHandler(
+    "direct-insert-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      // @cast-boundary test-fixture — see direct-insert-no-declare above.
+      await ctx.db.insertOne(contactTable as unknown as SchemaTable, {
+        email: "leak-direct-declared@example.com",
+        note: event.payload.note,
+      });
+      return { isSuccess: true as const, data: { ok: true as const } };
+    },
+    { access: { roles: ["anonymous"], personalData: "public-intake" }, rateLimit: RATE_LIMIT },
+  );
+
+  r.writeHandler(
+    "writeas-no-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) =>
+      ctx.writeAs(createSystemUser(event.user.tenantId), "intakeb:write:create", {
+        email: "leak-writeas@example.com",
+        note: event.payload.note,
+      }),
+    {
+      access: { roles: ["anonymous"] },
+      rateLimit: RATE_LIMIT,
+      escapeHatch: { reason: "test: cross-identity detour to prove the gate survives writeAs" },
+    },
+  );
+
+  r.writeHandler(
+    "writeas-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) =>
+      ctx.writeAs(createSystemUser(event.user.tenantId), "intakeb:write:create", {
+        email: "leak-writeas-declared@example.com",
+        note: event.payload.note,
+      }),
+    {
+      access: { roles: ["anonymous"], personalData: "public-intake" },
+      rateLimit: RATE_LIMIT,
+      escapeHatch: { reason: "test: cross-identity detour to prove the gate survives writeAs" },
+    },
+  );
+
+  // The postSave hook only fires for handlers whose result is a genuine
+  // SaveContext (createEventStoreExecutor's crud.create), so these write to
+  // a harmless non-PII probe entity purely to trigger the hook.
+  r.writeHandler(
+    "hook-no-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(probeTable, probeEntity, { entityName: "probe" });
+      return crud.create({ note: event.payload.note }, event.user, ctx.db);
+    },
+    { access: { roles: ["anonymous"] }, rateLimit: RATE_LIMIT },
+  );
+  r.writeHandler(
+    "hook-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(probeTable, probeEntity, { entityName: "probe" });
+      return crud.create({ note: event.payload.note }, event.user, ctx.db);
+    },
+    { access: { roles: ["anonymous"], personalData: "public-intake" }, rateLimit: RATE_LIMIT },
+  );
+  r.hook("postSave", "hook-no-declare", async (_result, ctx) => {
+    // @cast-boundary test-fixture — postSave hooks receive HandlerContext as
+    // AppContext, whose `db` is typed as the DbConnection|TenantDb union
+    // (fail-closed at the outer boundary); at runtime it's always the
+    // TenantDb built for this write. See direct-insert-no-declare above.
+    await (ctx.db as TenantDb).insertOne(contactTable as unknown as SchemaTable, {
+      email: "leak-hook@example.com",
+      note: "from-afterCommit-hook",
+    });
+  });
+  r.hook("postSave", "hook-declare", async (_result, ctx) => {
+    // @cast-boundary test-fixture — see hook-no-declare above.
+    await (ctx.db as TenantDb).insertOne(contactTable as unknown as SchemaTable, {
+      email: "leak-hook-declared@example.com",
+      note: "from-afterCommit-hook",
+    });
+  });
+
+  r.queryHandler(
+    "detour-query",
+    z.object({ note: z.string() }),
+    async (event, ctx) =>
+      ctx.write("intakeb:write:create", {
+        email: "leak-queryas@example.com",
+        note: event.payload.note,
+      }),
+    { access: { roles: [SYSTEM_ROLE] } },
+  );
+
+  r.writeHandler(
+    "queryas-no-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) =>
+      // Detour: anonymous root -> ctx.queryAs(SYSTEM) -> that query handler's
+      // own ctx.write. The origin travels with the root call, not the
+      // identity-switched SYSTEM user, so this must still be blocked.
+      ctx.queryAs(createSystemUser(event.user.tenantId), "intakea:query:detour-query", {
+        note: event.payload.note,
+      }) as ReturnType<typeof ctx.write>,
+    {
+      access: { roles: ["anonymous"] },
+      rateLimit: RATE_LIMIT,
+      escapeHatch: {
+        reason: "test: queryAs detour to prove the gate survives nested query->write",
+      },
+    },
+  );
+  r.writeHandler(
+    "queryas-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) =>
+      ctx.queryAs(createSystemUser(event.user.tenantId), "intakea:query:detour-query", {
+        note: event.payload.note,
+      }) as ReturnType<typeof ctx.write>,
+    {
+      access: { roles: ["anonymous"], personalData: "public-intake" },
+      rateLimit: RATE_LIMIT,
+      escapeHatch: {
+        reason: "test: queryAs detour to prove the gate survives nested query->write",
+      },
+    },
+  );
+
+  r.writeHandler(
+    "default-table-insert-no-declare",
+    z.object({ note: z.string() }),
+    async (_event, ctx) => {
+      // @cast-boundary test-fixture — see direct-insert-no-declare above.
+      await ctx.db.insertOne(leadTable as unknown as SchemaTable, { phone: "+49 30 1234" });
+      return { isSuccess: true as const, data: { ok: true as const } };
+    },
+    { access: { roles: ["anonymous"] }, rateLimit: RATE_LIMIT },
+  );
+
+  r.writeHandler(
+    "default-table-writeas-no-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) =>
+      ctx.writeAs(createSystemUser(event.user.tenantId), "intakeb:write:create-lead", {
+        phone: "+49 30 5678",
+      }),
+    {
+      access: { roles: ["anonymous"] },
+      rateLimit: RATE_LIMIT,
+      escapeHatch: { reason: "test: cross-identity detour to prove the gate survives writeAs" },
+    },
+  );
+
+  r.writeHandler(
+    "non-pii-insert",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      // @cast-boundary test-fixture — only the non-PII `note` column is
+      // written here; `email` is deliberately absent so the gate has
+      // nothing to block.
+      await ctx.db.insertOne(contactTable as unknown as SchemaTable, {
+        note: event.payload.note,
+      });
+      return { isSuccess: true as const, data: { ok: true as const } };
+    },
+    { access: { roles: ["anonymous"] }, rateLimit: RATE_LIMIT },
+  );
+
+  r.writeHandler(
+    "mixed-role-insert",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      // @cast-boundary test-fixture — see direct-insert-no-declare above.
+      await ctx.db.insertOne(contactTable as unknown as SchemaTable, {
+        email: "leak-mixed-role@example.com",
+        note: event.payload.note,
+      });
+      return { isSuccess: true as const, data: { ok: true as const } };
+    },
+    { access: { roles: ["anonymous", "Admin"] }, rateLimit: RATE_LIMIT },
+  );
+});
+
+describe("public-intake runtime gate", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [featureB, featureA],
+      anonymousAccess: { defaultTenantId: TENANT_ID },
+    });
+    await unsafeCreateEntityTable(stack.db, contactEntity);
+    await unsafeCreateEntityTable(stack.db, probeEntity);
+    await unsafeCreateEntityTable(stack.db, leadEntity, "intakeLead");
+  });
+
+  afterAll(() => stack.cleanup());
+
+  beforeEach(async () => {
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${contactTable.tableName}"`);
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${probeTable.tableName}"`);
+    await asRawClient(stack.db).unsafe(`DELETE FROM "${leadTable.tableName}"`);
+  });
+
+  async function rowCount(): Promise<number> {
+    const rows = await selectMany(stack.db, contactTable);
+    return rows.length;
+  }
+
+  async function probeRowCount(): Promise<number> {
+    const rows = await selectMany(stack.db, probeTable);
+    return rows.length;
+  }
+
+  test("(a) direct ctx.db.insertOne on a foreign PII table — blocked without declaration", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:direct-insert-no-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { details: { reason: string } } };
+    expect(body.error.details.reason).toBe("public_intake_required");
+    expect(await rowCount()).toBe(0);
+  });
+
+  test("(a) direct ctx.db.insertOne on a foreign PII table — allowed once declared", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:direct-insert-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(200);
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("(b) ctx.writeAs(SYSTEM, ...) detour — blocked without declaration", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:writeas-no-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { details: { reason: string } } };
+    expect(body.error.details.reason).toBe("public_intake_required");
+    expect(await rowCount()).toBe(0);
+  });
+
+  test("(b) ctx.writeAs(SYSTEM, ...) detour — allowed once declared", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:writeas-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(200);
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("(c) afterCommit postSave hook writing foreign PII — blocked without declaration", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:hook-no-declare",
+      payload: { note: "x" },
+    });
+    // The outer write itself already succeeded before the hook ran —
+    // afterCommit errors are logged, never surfaced on the HTTP response
+    // (flushAfterCommit is awaited inside runBatch before it returns, so
+    // there is no race to sleep past). The probe-row assertion proves the
+    // hook actually ran (and was gated), not merely that it never fired.
+    expect(res.status).toBe(200);
+    expect(await probeRowCount()).toBe(1);
+    expect(await rowCount()).toBe(0);
+  });
+
+  test("(c) afterCommit postSave hook writing foreign PII — allowed once declared", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:hook-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(200);
+    expect(await probeRowCount()).toBe(1);
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("(d) anonymous write -> queryAs(SYSTEM) -> query handler's own ctx.write — blocked without declaration", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:queryas-no-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { details: { reason: string } } };
+    expect(body.error.details.reason).toBe("public_intake_required");
+    expect(await rowCount()).toBe(0);
+  });
+
+  test("(d) anonymous write -> queryAs(SYSTEM) -> query handler's own ctx.write — allowed once declared", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:queryas-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(200);
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("default entity table name — insertOne and executor create both blocked", async () => {
+    for (const type of [
+      "intakea:write:default-table-insert-no-declare",
+      "intakea:write:default-table-writeas-no-declare",
+    ]) {
+      const res = await stack.http.raw("POST", "/api/write", { type, payload: { note: "x" } });
+      expect(res.status).toBe(403);
+      const body = (await res.json()) as { error: { details: { reason: string } } };
+      expect(body.error.details.reason).toBe("public_intake_required");
+    }
+    expect(await selectMany(stack.db, leadTable)).toHaveLength(0);
+  });
+
+  test("(e) anonymous write of a non-PII field only — allowed without declaration", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:non-pii-insert",
+      payload: { note: "hello" },
+    });
+    expect(res.status).toBe(200);
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("(f) authenticated user on a mixed-role handler (anonymous + Admin) — allowed without declaration", async () => {
+    const res = await stack.http.write(
+      "intakea:write:mixed-role-insert",
+      { note: "hi" },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(200);
+    expect(await rowCount()).toBe(1);
+  });
+});

package/src/pipeline/__tests__/redis-pipeline.integration.test.ts

@@ -223,6 +223,65 @@ describe("idempotency guard", () => {
     if (final.status !== "cached") throw new Error("expected cached value");
     expect(JSON.parse(final.result)).toEqual({ isSuccess: true, data: { owner: "reclaimer" } });
   });
+
+  test("release() frees the lock — a waiting check() reclaims immediately instead of polling out", async () => {
+    const guard = createIdempotencyGuard(testRedis.redis, {
+      pendingTtlSeconds: 5,
+      pollIntervalMs: 20,
+      waitTimeoutMs: 10_000,
+    });
+    const requestId = "req-release-1";
+
+    const first = await guard.check(tenantA, userA, requestId);
+    expect(first.status).toBe("acquired");
+    if (first.status !== "acquired") throw new Error("expected to acquire the lock");
+
+    // Waiter starts BEFORE release — if release is a no-op this only resolves
+    // once waitTimeoutMs elapses (10s), which the 500ms race below catches.
+    const waiterPromise = guard.check(tenantA, userA, requestId);
+
+    await guard.release(tenantA, userA, requestId, first.token);
+
+    const raced = await Promise.race([
+      waiterPromise.then((v) => ({ done: true as const, v })),
+      new Promise<{ done: false }>((r) => setTimeout(() => r({ done: false }), 500)),
+    ]);
+    expect(raced.done).toBe(true);
+    if (!raced.done) throw new Error("waiter did not reclaim after release()");
+    expect(raced.v.status).toBe("acquired");
+  });
+
+  test("release() with a stale token is a no-op — it must not clear a new owner's lock", async () => {
+    const guard = createIdempotencyGuard(testRedis.redis, {
+      pendingTtlSeconds: 1,
+      pollIntervalMs: 20,
+      waitTimeoutMs: 6_000,
+    });
+    const requestId = "req-release-stale";
+
+    const original = await guard.check(tenantA, userA, requestId);
+    expect(original.status).toBe("acquired");
+    if (original.status !== "acquired") throw new Error("expected to acquire the lock");
+
+    // Let the lock expire, then a new owner reclaims it.
+    await new Promise((r) => setTimeout(r, 1100));
+    const reclaimer = await guard.check(tenantA, userA, requestId);
+    expect(reclaimer.status).toBe("acquired");
+    if (reclaimer.status !== "acquired") throw new Error("expected to reclaim the lock");
+
+    // The original (stale) owner's release() must not touch the reclaimer's lock.
+    await guard.release(tenantA, userA, requestId, original.token);
+
+    await guard.store(tenantA, userA, requestId, reclaimer.token, {
+      isSuccess: true,
+      data: { owner: "reclaimer" },
+    });
+
+    const final = await guard.check(tenantA, userA, requestId);
+    expect(final.status).toBe("cached");
+    if (final.status !== "cached") throw new Error("expected cached value");
+    expect(JSON.parse(final.result)).toEqual({ isSuccess: true, data: { owner: "reclaimer" } });
+  });
 });
 
 // --- Event Dedup ---

package/src/pipeline/active-membership.ts

@@ -16,6 +16,7 @@ import type { TenantId } from "../engine/types/identifiers";
 import { InternalError } from "../errors";
 import { executeQuery } from "./dispatch-query";
 import { type DispatchContext, resolveDbSource } from "./dispatch-shared";
+import { rootWriteOrigin } from "./write-origin";
 
 export type ActiveMembershipPolicy = {
   // destroyRequested still counts as active — owners must be able to cancel
@@ -60,11 +61,14 @@ async function findMembership(
   userId: string,
   tenantId: TenantId,
 ): Promise<RawMembershipRow | undefined> {
+  const membershipUser = createSystemUser(tenantId);
+  // Auth-flow entry point with no enclosing handler, so it is its own root.
   const rawMemberships = await executeQuery(
     ctx,
     ctx.membershipQuery,
     { userId },
-    createSystemUser(tenantId),
+    membershipUser,
+    rootWriteOrigin(ctx.registry, ctx.membershipQuery, membershipUser),
   );
   if (!Array.isArray(rawMemberships) || !rawMemberships.every(isMembershipRow)) {
     throw new InternalError({

package/src/pipeline/dispatch-batch.ts

@@ -1,3 +1,4 @@
+import { requestContext } from "../api/request-context";
 import type { DbConnection } from "../db/connection";
 import { transaction } from "../db/query";
 import type { DeleteContext, SaveContext, SessionUser, WriteResult } from "../engine/types";
@@ -13,6 +14,7 @@ import {
   isLifecycleResult,
   wrapToKumiko,
 } from "./dispatcher-utils";
+import { rootWriteOrigin } from "./write-origin";
 
 // Core batch logic extracted so write() and command() can reuse it
 // (a single write = batch of one, running in its own transaction).
@@ -21,6 +23,22 @@ export async function runBatch(
   commands: readonly BatchCommand[],
   user: SessionUser,
   requestId?: string,
+): Promise<BatchResult> {
+  const current = requestContext.get();
+  if (!current?.signal) {
+    return runBatchBody(ctx, commands, user, requestId);
+  }
+  // Strip the signal: a disconnect would roll back the tx, idempotency would
+  // cache a 500 for the uncommitted write and afterCommit effects would be lost.
+  const { signal: _signal, ...withoutSignal } = current;
+  return requestContext.run(withoutSignal, () => runBatchBody(ctx, commands, user, requestId));
+}
+
+async function runBatchBody(
+  ctx: DispatchContext,
+  commands: readonly BatchCommand[],
+  user: SessionUser,
+  requestId?: string,
 ): Promise<BatchResult> {
   const { idempotency, lifecycle, appContext: context } = ctx;
   if (commands.length === 0) {
@@ -44,8 +62,8 @@ export async function runBatch(
     }
   }
 
-  // Wrap return paths: cache the final result under requestId so retries get
-  // the same answer (both success and failure results are cached).
+  // Cache the result under requestId so retries get the same answer. Only a
+  // provably rolled-back 5xx releases the lock instead (releaseOrFinalize).
   const finalize = async (result: BatchResult): Promise<BatchResult> => {
     if (requestId && idempotency && idempotencyToken) {
       await idempotency.store(user.tenantId, user.id, requestId, idempotencyToken, result);
@@ -53,6 +71,19 @@ export async function runBatch(
     return result;
   };
 
+  // Never for the no-tx fallback: without a rollback, a re-run would repeat
+  // the side effects of the commands that already ran.
+  const releaseOrFinalize = async (
+    result: BatchResult,
+    isRetryableRollback: boolean,
+  ): Promise<BatchResult> => {
+    if (isRetryableRollback && requestId && idempotency && idempotencyToken) {
+      await idempotency.release(user.tenantId, user.id, requestId, idempotencyToken);
+      return result;
+    }
+    return finalize(result);
+  };
+
   const afterCommitHooks: AfterCommitHook[] = [];
   const results: WriteResult[] = [];
 
@@ -117,6 +148,7 @@ export async function runBatch(
         cmd.type,
         cmd.payload,
         user,
+        rootWriteOrigin(ctx.registry, cmd.type, user),
         undefined,
         afterCommitHooks,
       );
@@ -132,6 +164,7 @@ export async function runBatch(
     return finalize({ isSuccess: true, results });
   }
 
+  let transactionCallbackCompleted = false;
   try {
     await transaction(db, async (tx) => {
       for (let i = 0; i < commands.length; i++) {
@@ -142,6 +175,7 @@ export async function runBatch(
           cmd.type,
           cmd.payload,
           user,
+          rootWriteOrigin(ctx.registry, cmd.type, user),
           tx,
           afterCommitHooks,
         );
@@ -150,22 +184,34 @@ export async function runBatch(
           throw new BatchRollback(i, res.error);
         }
       }
+      transactionCallbackCompleted = true;
     });
   } catch (e) {
     if (e instanceof BatchRollback) {
-      return finalize({
+      // Thrown inside the callback, so the tx rolled back. A 4xx is
+      // deterministic and stays cached; a 5xx may be transient.
+      return releaseOrFinalize(
+        {
+          isSuccess: false,
+          error: e.failureError,
+          failedIndex: e.failedIndex,
+          results,
+        },
+        e.failureError.httpStatus >= 500,
+      );
+    }
+    // A completed callback means the throw came from COMMIT (outcome unknown),
+    // so cache it; otherwise COMMIT was never sent and releasing is safe.
+    const error = toWriteErrorInfo(wrapToKumiko(e));
+    return releaseOrFinalize(
+      {
         isSuccess: false,
-        error: e.failureError,
-        failedIndex: e.failedIndex,
+        error,
+        failedIndex: results.length,
         results,
-      });
-    }
-    return finalize({
-      isSuccess: false,
-      error: toWriteErrorInfo(wrapToKumiko(e)),
-      failedIndex: results.length,
-      results,
-    });
+      },
+      !transactionCallbackCompleted && error.httpStatus >= 500,
+    );
   }
 
   // Commit succeeded — fire deferred side-effects.