@cosmicdrift/kumiko-framework 0.305.0 → 0.307.0

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

@@ -4,10 +4,11 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { z } from "zod";
 import type { SchemaTable } from "../../db";
+import type { DbRunner } from "../../db/connection";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
-import { asRawClient, selectMany } from "../../db/query";
+import { asRawClient, runInSavepoint, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
-import type { TenantDb } from "../../db/tenant-db";
+import { createTenantDb, 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";
@@ -273,6 +274,185 @@ const featureA = defineFeature("intakea", (r) => {
     },
     { access: { roles: ["anonymous", "Admin"] }, rateLimit: RATE_LIMIT },
   );
+
+  // (g) createTenantDb() built by the HANDLER ITSELF from ctx.db.unsafeRaw(reason) — the
+  // returned runner carries no TenantDb of its own, so without gate inheritance on the
+  // runner (tenant-db.ts's runnerPersonalDataGates) this fresh TenantDb would have no gate.
+  const UNSAFE_RAW_REASON =
+    "test: proves createTenantDb() built from ctx.db.unsafeRaw() inherits the caller's personal-data gate";
+
+  r.writeHandler(
+    "unsafe-raw-tenant-db-no-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const raw = ctx.db.unsafeRaw(UNSAFE_RAW_REASON);
+      await createTenantDb(raw, event.user.tenantId, "system").insertOne(
+        contactTable as unknown as SchemaTable,
+        { email: "leak-unsafe-raw@example.com", note: event.payload.note },
+      );
+      return { isSuccess: true as const, data: { ok: true as const } };
+    },
+    {
+      access: { roles: ["anonymous"] },
+      rateLimit: RATE_LIMIT,
+      escapeHatch: { reason: UNSAFE_RAW_REASON },
+    },
+  );
+
+  r.writeHandler(
+    "unsafe-raw-tenant-db-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const raw = ctx.db.unsafeRaw(UNSAFE_RAW_REASON);
+      await createTenantDb(raw, event.user.tenantId, "system").insertOne(
+        contactTable as unknown as SchemaTable,
+        { email: "leak-unsafe-raw-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,
+      escapeHatch: { reason: UNSAFE_RAW_REASON },
+    },
+  );
+
+  // Nested tx: the handler already runs inside the request's own transaction, so its
+  // unsafeRaw runner is a tx handle (.savepoint, not .begin — see asRawClient's own
+  // comment). The savepoint-scoped tx a callback receives must inherit the same gate,
+  // otherwise a handler could dodge the gate by moving the write inside a savepoint.
+  r.writeHandler(
+    "unsafe-raw-savepoint-tenant-db-no-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const raw = ctx.db.unsafeRaw(UNSAFE_RAW_REASON);
+      await runInSavepoint(raw, async (sp) => {
+        await createTenantDb(sp as DbRunner, event.user.tenantId, "system").insertOne(
+          contactTable as unknown as SchemaTable,
+          { email: "leak-unsafe-raw-tx@example.com", note: event.payload.note },
+        );
+      });
+      return { isSuccess: true as const, data: { ok: true as const } };
+    },
+    {
+      access: { roles: ["anonymous"] },
+      rateLimit: RATE_LIMIT,
+      escapeHatch: { reason: UNSAFE_RAW_REASON },
+    },
+  );
+
+  r.writeHandler(
+    "unsafe-raw-savepoint-tenant-db-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const raw = ctx.db.unsafeRaw(UNSAFE_RAW_REASON);
+      await runInSavepoint(raw, async (sp) => {
+        await createTenantDb(sp as DbRunner, event.user.tenantId, "system").insertOne(
+          contactTable as unknown as SchemaTable,
+          { email: "leak-unsafe-raw-tx-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,
+      escapeHatch: { reason: UNSAFE_RAW_REASON },
+    },
+  );
+
+  // Raw SQL through the gated proxy itself must stay ungated (decision: unsafeRaw's raw SQL
+  // is an escape hatch + audit trail, not something the personal-data gate blocks) — this
+  // just proves the proxy stays transparent for a direct tagged-template call.
+  r.writeHandler(
+    "unsafe-raw-tagged-query-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const raw = ctx.db.unsafeRaw(UNSAFE_RAW_REASON);
+      // @cast-boundary test-fixture — DbRunner's RawClient arm has no tagged-template call
+      // signature; the underlying driver instance (postgres-js/Bun.SQL) does.
+      const tagged = raw as unknown as (
+        strings: TemplateStringsArray,
+        ...values: unknown[]
+      ) => Promise<readonly Record<string, unknown>[]>;
+      const rows = await tagged`SELECT 1 AS one`;
+      if (rows[0]?.["one"] !== 1) throw new Error("tagged query through the proxy failed");
+      await createTenantDb(raw, event.user.tenantId, "system").insertOne(
+        contactTable as unknown as SchemaTable,
+        { email: "leak-unsafe-raw-tagged@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,
+      escapeHatch: { reason: UNSAFE_RAW_REASON },
+    },
+  );
+
+  // Authenticated session: same ctx.db.unsafeRaw() -> createTenantDb() path, but the root
+  // isn't anonymous, so ctx.db carries no personal-data gate to inherit — unaffected.
+  r.writeHandler(
+    "unsafe-raw-tenant-db-authenticated",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const raw = ctx.db.unsafeRaw(UNSAFE_RAW_REASON);
+      await createTenantDb(raw, event.user.tenantId, "system").insertOne(
+        contactTable as unknown as SchemaTable,
+        { email: "leak-unsafe-raw-authenticated@example.com", note: event.payload.note },
+      );
+      return { isSuccess: true as const, data: { ok: true as const } };
+    },
+    { access: { roles: ["Admin"] }, escapeHatch: { reason: UNSAFE_RAW_REASON } },
+  );
+
+  // The CRUD executor writes through tenantDbRunner + assertPersonalDataWrite, not
+  // insertOne — a TenantDb inheriting its gate only from the runner (not from an explicit
+  // grants.personalDataGate) must gate the executor path too, not just direct insertOne.
+  r.writeHandler(
+    "unsafe-raw-executor-no-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const scopedDb = createTenantDb(
+        ctx.db.unsafeRaw(UNSAFE_RAW_REASON),
+        event.user.tenantId,
+        "system",
+      );
+      const crud = createEventStoreExecutor(contactTable, contactEntity, { entityName: "contact" });
+      return crud.create(
+        { email: "leak-unsafe-raw-executor@example.com", note: event.payload.note },
+        event.user,
+        scopedDb,
+      );
+    },
+    {
+      access: { roles: ["anonymous"] },
+      rateLimit: RATE_LIMIT,
+      escapeHatch: { reason: UNSAFE_RAW_REASON },
+    },
+  );
+
+  // Same inherited-gate TenantDb, but only a non-PII field — proves the proxy/executor
+  // combination still appends events and lets the projection run when there is nothing
+  // for the gate to block, not merely that it throws.
+  r.writeHandler(
+    "unsafe-raw-executor-non-pii-no-declare",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      const scopedDb = createTenantDb(
+        ctx.db.unsafeRaw(UNSAFE_RAW_REASON),
+        event.user.tenantId,
+        "system",
+      );
+      const crud = createEventStoreExecutor(probeTable, probeEntity, { entityName: "probe" });
+      return crud.create({ note: event.payload.note }, event.user, scopedDb);
+    },
+    {
+      access: { roles: ["anonymous"] },
+      rateLimit: RATE_LIMIT,
+      escapeHatch: { reason: UNSAFE_RAW_REASON },
+    },
+  );
 });
 
 describe("public-intake runtime gate", () => {
@@ -422,4 +602,83 @@ describe("public-intake runtime gate", () => {
     expect(res.status).toBe(200);
     expect(await rowCount()).toBe(1);
   });
+
+  test("(g) createTenantDb(ctx.db.unsafeRaw(reason), ...) — blocked without declaration", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:unsafe-raw-tenant-db-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("(g) createTenantDb(ctx.db.unsafeRaw(reason), ...) — allowed once declared", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:unsafe-raw-tenant-db-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(200);
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("(g) createTenantDb(tx, ...) inside savepoint() — blocked without declaration", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:unsafe-raw-savepoint-tenant-db-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("(g) createTenantDb(tx, ...) inside savepoint() — allowed once declared", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:unsafe-raw-savepoint-tenant-db-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(200);
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("(g) a tagged-template query through the gated unsafeRaw proxy still works", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:unsafe-raw-tagged-query-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(200);
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("(g) authenticated session on the same unsafeRaw->createTenantDb path — unaffected", async () => {
+    const res = await stack.http.write(
+      "intakea:write:unsafe-raw-tenant-db-authenticated",
+      { note: "x" },
+      TestUsers.admin,
+    );
+    expect(res.status).toBe(200);
+    expect(await rowCount()).toBe(1);
+  });
+
+  test("(g) createEventStoreExecutor.create through an inherited-gate TenantDb — blocked without declaration", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:unsafe-raw-executor-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("(g) createEventStoreExecutor.create of a non-PII field through the same inherited-gate TenantDb — allowed", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: "intakea:write:unsafe-raw-executor-non-pii-no-declare",
+      payload: { note: "x" },
+    });
+    expect(res.status).toBe(200);
+    expect(await probeRowCount()).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/dispatch-batch.ts

@@ -1,3 +1,5 @@
+import type { WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
+import { requestContext, runWithWriteOrigin } 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,7 +15,20 @@ import {
   isLifecycleResult,
   wrapToKumiko,
 } from "./dispatcher-utils";
-import { rootWriteOrigin } from "./write-origin";
+import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin";
+
+// afterCommit hooks fire in flushAfterCommit, outside the command's scope.
+function rewrapHooksWithOrigin(
+  afterCommitHooks: AfterCommitHook[],
+  fromIndex: number,
+  origin: WriteOrigin,
+): void {
+  for (let i = fromIndex; i < afterCommitHooks.length; i++) {
+    const original = afterCommitHooks[i];
+    if (!original) continue;
+    afterCommitHooks[i] = () => runWithWriteOrigin(origin, original);
+  }
+}
 
 // Core batch logic extracted so write() and command() can reuse it
 // (a single write = batch of one, running in its own transaction).
@@ -22,6 +37,26 @@ export async function runBatch(
   commands: readonly BatchCommand[],
   user: SessionUser,
   requestId?: string,
+  inheritedOrigin?: WriteOrigin,
+): Promise<BatchResult> {
+  const current = requestContext.get();
+  if (!current?.signal) {
+    return runBatchBody(ctx, commands, user, requestId, inheritedOrigin);
+  }
+  // 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, inheritedOrigin),
+  );
+}
+
+async function runBatchBody(
+  ctx: DispatchContext,
+  commands: readonly BatchCommand[],
+  user: SessionUser,
+  requestId?: string,
+  inheritedOrigin?: WriteOrigin,
 ): Promise<BatchResult> {
   const { idempotency, lifecycle, appContext: context } = ctx;
   if (commands.length === 0) {
@@ -45,8 +80,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);
@@ -54,6 +89,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[] = [];
 
@@ -79,10 +127,12 @@ export async function runBatch(
     }
   };
 
+  const origins: WriteOrigin[] = [];
+
   // 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 () => {
+  const flushBatchHooksInner = async () => {
     try {
       const saves: SaveContext[] = [];
       const deletes: DeleteContext[] = [];
@@ -103,6 +153,14 @@ export async function runBatch(
     }
   };
 
+  // Batch hooks see every command's saves, so they run under the strictest origin.
+  const flushBatchHooks = async () => {
+    const strictest = origins.find(isPersonalDataGated) ?? origins[0];
+    // skip: no command ran, so batch hooks have no saves or deletes to see
+    if (!strictest) return;
+    await runWithWriteOrigin(strictest, flushBatchHooksInner);
+  };
+
   // 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;
@@ -113,15 +171,16 @@ export async function runBatch(
     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,
+      const origin = effectiveWriteOrigin(
         rootWriteOrigin(ctx.registry, cmd.type, user),
-        undefined,
-        afterCommitHooks,
+        inheritedOrigin,
+      );
+      origins.push(origin);
+      const hookStart = afterCommitHooks.length;
+      const res = await runWithWriteOrigin(origin, () =>
+        executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, undefined, afterCommitHooks),
       );
+      rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
       results.push(res);
       if (!res.isSuccess) {
         // No tx means no rollback — but we still drop afterCommit hooks,
@@ -134,41 +193,55 @@ 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++) {
         const cmd = commands[i];
         if (!cmd) continue;
-        const res = await executeNestedWrite(
-          ctx,
-          cmd.type,
-          cmd.payload,
-          user,
+        const origin = effectiveWriteOrigin(
           rootWriteOrigin(ctx.registry, cmd.type, user),
-          tx,
-          afterCommitHooks,
+          inheritedOrigin,
         );
+        origins.push(origin);
+        const hookStart = afterCommitHooks.length;
+        const res = await runWithWriteOrigin(origin, () =>
+          executeNestedWrite(ctx, cmd.type, cmd.payload, user, origin, tx, afterCommitHooks),
+        );
+        rewrapHooksWithOrigin(afterCommitHooks, hookStart, origin);
         results.push(res);
         if (!res.isSuccess) {
           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.

package/src/pipeline/dispatch-stream.ts

@@ -74,9 +74,13 @@ async function* executeStreamInner(
   const invalidated = new Promise<void>((resolve) => {
     resolveInvalidated = resolve;
   });
-  const unsubscribeAccessInvalidation = ctx.sseBroker?.subscribeAccessInvalidation(user.id, () => {
-    resolveInvalidated?.();
-  });
+  const unsubscribeAccessInvalidation = ctx.sseBroker?.subscribeAccessInvalidation(
+    user.id,
+    () => {
+      resolveInvalidated?.();
+    },
+    user.sid,
+  );
 
   let iterator: AsyncIterator<unknown> | undefined;
   // When access is revoked mid-pull, `iterator.next()` is still in flight.

package/src/pipeline/dispatcher-utils.ts

@@ -6,7 +6,14 @@ import type {
   SessionUser,
   WriteResult,
 } from "../engine/types";
-import { type FieldIssue, toKumikoError, type WriteErrorInfo } from "../errors";
+import {
+  type FieldIssue,
+  type KumikoError,
+  toKumikoError,
+  VersionConflictError,
+  type WriteErrorInfo,
+} from "../errors";
+import { VersionConflictError as EventStoreVersionConflictError } from "../event-store/errors";
 
 export type FailedWriteResult = Extract<WriteResult, { isSuccess: false }>;
 
@@ -177,4 +184,16 @@ export function resolveType(type: HandlerType): string {
   return typeof type === "string" ? type : type.name;
 }
 
-export const wrapToKumiko = toKumikoError;
+// A custom write losing an append race (ctx.appendEvent, stream.append) is a
+// retryable 409 like the CRUD executor's, not an internal error. Mapped here
+// because errors/ is client code and must not import the event store.
+// currentVersion -1 is the executor's "not looked up" sentinel.
+export function wrapToKumiko(e: unknown): KumikoError {
+  if (e instanceof EventStoreVersionConflictError) {
+    return new VersionConflictError(
+      { entityId: e.aggregateId, expectedVersion: e.expectedVersion, currentVersion: -1 },
+      { cause: e },
+    );
+  }
+  return toKumikoError(e);
+}