@cosmicdrift/kumiko-framework 0.1.0

package/src/api/__tests__/auth-middleware-transport.test.ts

@@ -0,0 +1,80 @@
+// auth-middleware: cookie + bearer + reject-both. Pure-logic unit tests
+// against a hand-rolled Hono app — no DB, no dispatcher. Exercises the
+// transport-extraction path that drives the csrf-middleware downstream.
+
+import { Hono } from "hono";
+import { describe, expect, test } from "vitest";
+import { TestUsers } from "../../stack";
+import { AUTH_COOKIE_NAME, authMiddleware, getAuthTransport, getUser } from "../auth-middleware";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "auth-middleware-transport-test-secret-min-32-chars";
+
+async function buildApp(): Promise<{ app: Hono; token: string }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const token = await jwt.sign(TestUsers.user);
+  const app = new Hono();
+  app.use("/api/*", authMiddleware(jwt));
+  app.get("/api/ping", (c) => {
+    const user = getUser(c);
+    const transport = getAuthTransport(c);
+    return c.json({ userId: user.id, transport });
+  });
+  return { app, token };
+}
+
+describe("auth-middleware transport selection", () => {
+  test("bearer header authenticates and sets transport=bearer", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/ping", {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { userId: string; transport: string };
+    expect(body.userId).toBe(TestUsers.user.id);
+    expect(body.transport).toBe("bearer");
+  });
+
+  test("auth cookie authenticates and sets transport=cookie", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/ping", {
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=${token}` },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { userId: string; transport: string };
+    expect(body.userId).toBe(TestUsers.user.id);
+    expect(body.transport).toBe("cookie");
+  });
+
+  test("both cookie AND bearer → 400 ambiguous_auth", async () => {
+    const { app, token } = await buildApp();
+    const res = await app.request("/api/ping", {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Cookie: `${AUTH_COOKIE_NAME}=${token}`,
+      },
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string; httpStatus: number } };
+    expect(body.error.code).toBe("ambiguous_auth");
+    expect(body.error.httpStatus).toBe(400);
+  });
+
+  test("neither cookie nor bearer → 401 missing_token", async () => {
+    const { app } = await buildApp();
+    const res = await app.request("/api/ping");
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("missing_token");
+  });
+
+  test("invalid cookie JWT → 401 invalid_token", async () => {
+    const { app } = await buildApp();
+    const res = await app.request("/api/ping", {
+      headers: { Cookie: `${AUTH_COOKIE_NAME}=not-a-real-jwt` },
+    });
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("invalid_token");
+  });
+});

package/src/api/__tests__/auth-routes-cookie.test.ts

@@ -0,0 +1,179 @@
+// auth-routes cookie behaviour — login sets cookies, logout clears them,
+// switch-tenant rotates them, cookieSameSite controls the SameSite flag.
+//
+// Uses a stub Dispatcher so the tests exercise ONLY the HTTP-layer cookie
+// logic — full-stack login via real loginHandler is covered by the
+// auth-cookie sample integration test.
+
+import type { Hono } from "hono";
+import { Hono as HonoCtor } from "hono";
+import { describe, expect, test } from "vitest";
+import type { SessionUser } from "../../engine/types";
+import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
+import { TestUsers } from "../../stack";
+import { getSetCookieRaw, getSetCookies } from "../../testing/http-cookies";
+import { PUBLIC_API_PATHS } from "../api-constants";
+import { AUTH_COOKIE_NAME, authMiddleware, CSRF_COOKIE_NAME } from "../auth-middleware";
+import { type AuthRoutesConfig, createAuthRoutes } from "../auth-routes";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "auth-routes-cookie-test-secret-min-32-characters";
+
+function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
+  const base: Dispatcher = {
+    async write(): Promise<WriteResult> {
+      // Explicit `const: WriteResult` locks the `isSuccess: true` branch of
+      // the union without an `as`-cast (which widens + silences the
+      // compiler). Success shape has to satisfy `{ isSuccess: true; data }`.
+      const ok: WriteResult = {
+        isSuccess: true,
+        data: {
+          kind: "auth-session",
+          session: TestUsers.user,
+        },
+      };
+      return ok;
+    },
+    async query(): Promise<unknown> {
+      return [];
+    },
+    async command(): Promise<void> {},
+    async batch(): Promise<BatchResult> {
+      const ok: BatchResult = { isSuccess: true, results: [] };
+      return ok;
+    },
+    async resolveAuthClaims(): Promise<Record<string, unknown>> {
+      return {};
+    },
+  };
+  return { ...base, ...overrides };
+}
+
+async function buildApp(
+  overrides: Partial<AuthRoutesConfig> = {},
+  dispatcher: Dispatcher = createStubDispatcher(),
+): Promise<{ app: Hono; validToken: string }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const validToken = await jwt.sign(TestUsers.user);
+  const config: AuthRoutesConfig = {
+    membershipQuery: "tenant:query:memberships",
+    loginHandler: "auth:write:login",
+    loginRateLimit: null, // don't need rate-limit interference in cookie tests
+    ...overrides,
+  };
+  const app = new HonoCtor();
+  const jwtGuard = authMiddleware(jwt);
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    return jwtGuard(c, next);
+  });
+  app.route("/api", createAuthRoutes(dispatcher, jwt, config));
+  return { app, validToken };
+}
+
+describe("auth-routes cookie behaviour on /auth/login", () => {
+  test("login sets both kumiko_auth and kumiko_csrf cookies", async () => {
+    const { app } = await buildApp();
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+    expect(res.status).toBe(200);
+    const cookies = getSetCookies(res);
+    expect(cookies.get(AUTH_COOKIE_NAME)).toBeDefined();
+    expect(cookies.get(CSRF_COOKIE_NAME)).toBeDefined();
+  });
+
+  test("cookieSameSite defaults to Lax", async () => {
+    const { app } = await buildApp();
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(/SameSite=Lax/i);
+  });
+
+  test("cookieSameSite: strict → SameSite=Strict flag", async () => {
+    const { app } = await buildApp({ cookieSameSite: "strict" });
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(/SameSite=Strict/i);
+  });
+
+  test("auth cookie is HttpOnly, csrf cookie is not", async () => {
+    const { app } = await buildApp();
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(/HttpOnly/i);
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).not.toMatch(/HttpOnly/i);
+  });
+
+  test("login still returns token in body (for native bearer clients)", async () => {
+    const { app } = await buildApp();
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+    const body = (await res.json()) as { isSuccess: boolean; token: string };
+    expect(body.isSuccess).toBe(true);
+    expect(typeof body.token).toBe("string");
+    expect(body.token.length).toBeGreaterThan(20);
+  });
+});
+
+describe("auth-routes cookie behaviour on /auth/logout", () => {
+  test("logout clears both cookies via Max-Age=0", async () => {
+    const { app, validToken } = await buildApp();
+    const res = await app.request("/api/auth/logout", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${validToken}` },
+    });
+    expect(res.status).toBe(200);
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(/Max-Age=0/i);
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).toMatch(/Max-Age=0/i);
+  });
+});
+
+describe("auth-routes cookie behaviour on /auth/switch-tenant", () => {
+  test("switch-tenant rotates both cookies", async () => {
+    const otherTenant = TestUsers.otherTenant;
+    const dispatcher = createStubDispatcher({
+      async query(type: string, _payload: unknown, _user: SessionUser): Promise<unknown> {
+        if (type === "tenant:query:memberships") {
+          return [
+            {
+              userId: TestUsers.user.id,
+              tenantId: otherTenant.tenantId,
+              roles: otherTenant.roles,
+            },
+          ];
+        }
+        return [];
+      },
+    });
+    const { app, validToken } = await buildApp({}, dispatcher);
+    const res = await app.request("/api/auth/switch-tenant", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${validToken}`,
+      },
+      body: JSON.stringify({ tenantId: otherTenant.tenantId }),
+    });
+    expect(res.status).toBe(200);
+    const cookies = getSetCookies(res);
+    const newAuth = cookies.get(AUTH_COOKIE_NAME);
+    expect(newAuth).toBeDefined();
+    expect(cookies.get(CSRF_COOKIE_NAME)).toBeDefined();
+    expect(newAuth?.value).not.toBe(validToken); // new jwt
+  });
+});

package/src/api/__tests__/batch.integration.ts

@@ -0,0 +1,404 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildDrizzleTable } from "../../db/table-builder";
+import {
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineFeature,
+  type EntityId,
+  HookPhases,
+  type SaveContext,
+} from "../../engine";
+import { UnprocessableError, writeFailure } from "../../errors";
+import { createEntityTable, setupTestStack, type TestStack, TestUsers } from "../../stack";
+
+// Entity: a simple "item" with name + counter
+const itemEntity = createEntity({
+  table: "batch_items",
+  fields: {
+    name: createTextField({ required: true }),
+    counter: createNumberField({ default: 0 }),
+  },
+});
+
+const itemTable = buildDrizzleTable("item", itemEntity);
+
+// Second entity used by an inTransaction hook to prove that hook DB writes
+// roll back with the main transaction.
+const auditEntity = createEntity({
+  table: "batch_audit",
+  fields: {
+    action: createTextField({ required: true }),
+    itemId: createTextField({ required: true }),
+  },
+});
+const auditTable = buildDrizzleTable("audit", auditEntity);
+
+// Hook invocation logs — reset per test. Captures which phase each hook saw.
+const inTxHookLog: Array<{ id: EntityId; name: string }> = [];
+const afterCommitHookLog: Array<{ id: EntityId; name: string }> = [];
+
+// Toggles for afterCommit fault-injection test
+let afterCommitShouldThrow = false;
+const afterCommitThirdHookRan: string[] = [];
+
+const itemFeature = defineFeature("batch", (r) => {
+  const item = r.entity("item", itemEntity);
+
+  r.writeHandler(
+    "item:create",
+    z.object({ name: z.string().min(1), counter: z.number().optional() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(itemTable, itemEntity, { entityName: "item" });
+      return crud.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Handler that always fails validation — used to trigger rollback mid-batch
+  r.writeHandler(
+    "item:fail",
+    z.object({ name: z.string().min(1) }),
+    async () => writeFailure(new UnprocessableError("intentional_failure")),
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Handler that always throws — used to verify unexpected throws surface as failures
+  r.writeHandler(
+    "item:throw",
+    z.object({ name: z.string().min(1) }),
+    async () => {
+      throw new Error("handler_crashed");
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
+  // Entity hook: inTransaction — records in memory
+  r.entityHook(
+    "postSave",
+    item,
+    async (result: SaveContext) => {
+      inTxHookLog.push({ id: result.id, name: (result.data["name"] as string) ?? "" });
+    },
+    { phase: HookPhases.inTransaction },
+  );
+
+  // Entity hook: inTransaction — writes to DB via ctx.db (the tx-scoped TenantDb).
+  // Proves that hook DB writes roll back with the main transaction on failure.
+  r.entityHook(
+    "postSave",
+    item,
+    async (result, ctx) => {
+      if (!ctx.db) return;
+      await ctx.db
+        .insert(auditTable)
+        .values({ action: "item_saved", itemId: result.id })
+        .returning();
+    },
+    { phase: HookPhases.inTransaction },
+  );
+
+  // Entity hook: afterCommit — records in memory (default phase)
+  r.entityHook("postSave", item, async (result: SaveContext) => {
+    afterCommitHookLog.push({ id: result.id, name: (result.data["name"] as string) ?? "" });
+  });
+
+  // Entity hook: afterCommit — may throw, used to verify error isolation
+  r.entityHook("postSave", item, async () => {
+    if (afterCommitShouldThrow) throw new Error("afterCommit_boom");
+  });
+
+  // Entity hook: afterCommit — runs AFTER the throwing one. Used to prove the
+  // next hooks still fire despite the earlier failure.
+  r.entityHook("postSave", item, async (result: SaveContext) => {
+    afterCommitThirdHookRan.push((result.data["name"] as string) ?? "");
+  });
+
+  // Two hooks used by the parallelism test. Each records its start+end
+  // timestamps so the assertion can compare intervals rather than elapsed
+  // wall-clock time (which is timing-flaky on loaded CI boxes).
+  r.entityHook("postSave", item, async (result: SaveContext) => {
+    const name = result.data["name"] as string;
+    if (!name?.startsWith("slowness-")) return;
+    parallelismWindows.push({ hook: "A", start: Date.now() });
+    await new Promise((r) => setTimeout(r, 80));
+    parallelismWindows.push({ hook: "A", end: Date.now() });
+  });
+  r.entityHook("postSave", item, async (result: SaveContext) => {
+    const name = result.data["name"] as string;
+    if (!name?.startsWith("slowness-")) return;
+    parallelismWindows.push({ hook: "B", start: Date.now() });
+    await new Promise((r) => setTimeout(r, 80));
+    parallelismWindows.push({ hook: "B", end: Date.now() });
+  });
+});
+
+// Start + end timestamps recorded by the parallelism hooks above. A pair of
+// hooks that ran truly in parallel will show B.start < A.end (and vice-versa),
+// regardless of how long the whole request took overall.
+//
+// Module-level mutable state — safe here because Vitest runs tests inside a
+// single file sequentially (the default). If someone flips vitest's
+// `sequence.concurrent` on for this file, the test body would need its own
+// window collector passed through ctx instead.
+type ParallelismEvent = { hook: "A" | "B"; start?: number; end?: number };
+const parallelismWindows: ParallelismEvent[] = [];
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [itemFeature] });
+  await createEntityTable(stack.db, itemEntity);
+  await createEntityTable(stack.db, auditEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  inTxHookLog.length = 0;
+  afterCommitHookLog.length = 0;
+  afterCommitThirdHookRan.length = 0;
+  afterCommitShouldThrow = false;
+  parallelismWindows.length = 0;
+  stack.events.reset();
+  await stack.db.delete(itemTable);
+  await stack.db.delete(auditTable);
+});
+
+describe("POST /api/batch", () => {
+  test("empty commands array returns success with empty results", async () => {
+    const res = await stack.http.batch([], admin);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+    expect(body.results).toEqual([]);
+  });
+
+  test("rejects non-array commands with 400", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/batch",
+      // biome-ignore lint/suspicious/noExplicitAny: intentional bad body
+      { commands: "not-an-array" as any },
+      { Authorization: `Bearer ${await stack.jwt.sign(admin)}` },
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("all-succeed: writes persist, both phases fire per command", async () => {
+    const res = await stack.http.batch(
+      [
+        { type: "batch:write:item:create", payload: { name: "alpha" } },
+        { type: "batch:write:item:create", payload: { name: "beta" } },
+        { type: "batch:write:item:create", payload: { name: "gamma" } },
+      ],
+      admin,
+    );
+
+    const body = await res.json();
+    expect(res.status).toBe(200);
+    expect(body.isSuccess).toBe(true);
+    expect(body.results).toHaveLength(3);
+    for (const r of body.results) expect(r.isSuccess).toBe(true);
+
+    // Both phases fired once per command, same ids, same order
+    expect(inTxHookLog).toHaveLength(3);
+    expect(afterCommitHookLog).toHaveLength(3);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["alpha", "beta", "gamma"]);
+    expect(afterCommitHookLog.map((h) => h.name)).toEqual(["alpha", "beta", "gamma"]);
+
+    // Rows actually persisted
+    const rows = await stack.db.select().from(itemTable);
+    expect(rows).toHaveLength(3);
+  });
+
+  test("mid-batch failure: all writes roll back, afterCommit hooks do NOT fire", async () => {
+    // Seed with one existing item so we can verify the batch didn't persist anything
+    await stack.db
+      .insert(itemTable)
+      .values({ name: "seed", counter: 0, tenantId: "00000000-0000-4000-8000-000000000001" });
+    const seedCount = (await stack.db.select().from(itemTable)).length;
+
+    const res = await stack.http.batch(
+      [
+        { type: "batch:write:item:create", payload: { name: "will-rollback-1" } },
+        { type: "batch:write:item:fail", payload: { name: "fails" } },
+        { type: "batch:write:item:create", payload: { name: "never-runs" } },
+      ],
+      admin,
+    );
+
+    const body = await res.json();
+    // UnprocessableError → 422 (business-rule violation), which is the
+    // "expected failure" HTTP status. The batch envelope keeps `failedIndex`
+    // + `results` alongside the error payload so callers know which command
+    // tripped the rollback.
+    expect(res.status).toBe(422);
+    expect(body.isSuccess).toBe(false);
+    expect(body.failedIndex).toBe(1);
+    expect(body.error.code).toBe("unprocessable");
+    expect(body.error.details.reason).toBe("intentional_failure");
+
+    // inTransaction hook fired for the first successful command (then rolled back
+    // — but the hook log is in-memory, it persists)
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["will-rollback-1"]);
+
+    // afterCommit hook must NOT have fired (transaction rolled back)
+    expect(afterCommitHookLog).toEqual([]);
+
+    // DB: only the seed row remains, the batch's first successful write rolled back
+    const rows = await stack.db.select().from(itemTable);
+    expect(rows).toHaveLength(seedCount);
+    expect((rows[0] as { name: string }).name).toBe("seed");
+  });
+
+  test("inTransaction hook DB writes roll back with the batch", async () => {
+    // Successful batch: audit rows should be written
+    const okRes = await stack.http.batch(
+      [{ type: "batch:write:item:create", payload: { name: "alpha" } }],
+      admin,
+    );
+    expect((await okRes.json()).isSuccess).toBe(true);
+    const auditAfterOk = await stack.db.select().from(auditTable);
+    expect(auditAfterOk).toHaveLength(1);
+    expect((auditAfterOk[0] as { action: string }).action).toBe("item_saved");
+
+    // Reset — new batch fails mid-way. Both entity rows AND audit rows must roll back.
+    await stack.db.delete(itemTable);
+    await stack.db.delete(auditTable);
+
+    const failRes = await stack.http.batch(
+      [
+        { type: "batch:write:item:create", payload: { name: "beta" } },
+        { type: "batch:write:item:fail", payload: { name: "stop" } },
+      ],
+      admin,
+    );
+    expect((await failRes.json()).isSuccess).toBe(false);
+
+    // Both tables are empty — the inTransaction audit hook's write rolled back
+    // together with the item row.
+    const itemsAfterFail = await stack.db.select().from(itemTable);
+    const auditAfterFail = await stack.db.select().from(auditTable);
+    expect(itemsAfterFail).toHaveLength(0);
+    expect(auditAfterFail).toHaveLength(0);
+  });
+
+  test("afterCommit hooks run in parallel (B starts before A finishes)", async () => {
+    const res = await stack.http.batch(
+      [{ type: "batch:write:item:create", payload: { name: "slowness-parallel" } }],
+      admin,
+    );
+    expect(res.status).toBe(200);
+
+    // Extract each hook's interval independently — checks overlap of
+    // intervals, not total elapsed time. Robust against CI noise.
+    const aStart = parallelismWindows.find((e) => e.hook === "A" && e.start !== undefined)?.start;
+    const aEnd = parallelismWindows.find((e) => e.hook === "A" && e.end !== undefined)?.end;
+    const bStart = parallelismWindows.find((e) => e.hook === "B" && e.start !== undefined)?.start;
+    const bEnd = parallelismWindows.find((e) => e.hook === "B" && e.end !== undefined)?.end;
+
+    expect(aStart).toBeDefined();
+    expect(aEnd).toBeDefined();
+    expect(bStart).toBeDefined();
+    expect(bEnd).toBeDefined();
+
+    // Parallel iff the two intervals overlap: one starts before the other
+    // ends. Sequential execution would produce disjoint intervals.
+    const overlap = (aStart as number) < (bEnd as number) && (bStart as number) < (aEnd as number);
+    expect(overlap).toBe(true);
+  });
+
+  test("afterCommit hook error is isolated: batch succeeds, other hooks still fire", async () => {
+    afterCommitShouldThrow = true;
+
+    const res = await stack.http.batch(
+      [{ type: "batch:write:item:create", payload: { name: "omega" } }],
+      admin,
+    );
+
+    // Batch is reported successful despite the afterCommit hook throwing
+    const body = await res.json();
+    expect(res.status).toBe(200);
+    expect(body.isSuccess).toBe(true);
+
+    // DB row persisted (tx committed)
+    const rows = await stack.db.select().from(itemTable);
+    expect(rows).toHaveLength(1);
+
+    // The hook AFTER the throwing one still ran — errors don't cascade
+    expect(afterCommitThirdHookRan).toEqual(["omega"]);
+  });
+
+  test("idempotency: repeated batch with same requestId returns cached result, no re-exec", async () => {
+    const requestId = "batch-rid-123";
+    const commands = [{ type: "batch:write:item:create", payload: { name: "once" } }];
+
+    const first = await stack.http.batch(commands, admin, requestId);
+    const firstBody = await first.json();
+    expect(firstBody.isSuccess).toBe(true);
+    expect(firstBody.results).toHaveLength(1);
+
+    const rowsAfterFirst = await stack.db.select().from(itemTable);
+    expect(rowsAfterFirst).toHaveLength(1);
+
+    // Hook logs reflect one execution
+    expect(inTxHookLog).toHaveLength(1);
+    expect(afterCommitHookLog).toHaveLength(1);
+
+    // Retry with the same requestId — same response, but commands did NOT run again
+    const second = await stack.http.batch(commands, admin, requestId);
+    const secondBody = await second.json();
+
+    expect(secondBody.isSuccess).toBe(true);
+    expect(secondBody.results).toEqual(firstBody.results);
+
+    // DB still has only one row (no double-insert)
+    const rowsAfterSecond = await stack.db.select().from(itemTable);
+    expect(rowsAfterSecond).toHaveLength(1);
+
+    // Hooks didn't fire a second time
+    expect(inTxHookLog).toHaveLength(1);
+    expect(afterCommitHookLog).toHaveLength(1);
+  });
+});
+
+describe("POST /api/write (single write runs in its own transaction)", () => {
+  test("inTransaction hook DB write persists with the entity write", async () => {
+    const res = await stack.http.write("batch:write:item:create", { name: "single" }, admin);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(true);
+
+    // Both the item row AND the audit row exist — proves the single write
+    // went through a transaction and the inTx hook shared it.
+    const items = await stack.db.select().from(itemTable);
+    const audits = await stack.db.select().from(auditTable);
+    expect(items).toHaveLength(1);
+    expect(audits).toHaveLength(1);
+  });
+
+  test("handler throw rolls back inTransaction hook writes too", async () => {
+    // First a successful write so there's something to compare against
+    await stack.http.write("batch:write:item:create", { name: "survivor" }, admin);
+    const beforeItems = await stack.db.select().from(itemTable);
+    const beforeAudits = await stack.db.select().from(auditTable);
+    expect(beforeItems).toHaveLength(1);
+    expect(beforeAudits).toHaveLength(1);
+
+    // Now a write whose handler throws — nothing new should be committed
+    const res = await stack.http.write("batch:write:item:throw", { name: "crash" }, admin);
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+
+    const afterItems = await stack.db.select().from(itemTable);
+    const afterAudits = await stack.db.select().from(auditTable);
+    // Counts unchanged — no partial commit
+    expect(afterItems).toHaveLength(beforeItems.length);
+    expect(afterAudits).toHaveLength(beforeAudits.length);
+  });
+});