@cosmicdrift/kumiko-framework 0.305.0 → 0.307.0

package/src/jobs/job-runner.ts

@@ -1,3 +1,4 @@
+import type { WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
 import { type JobsOptions, Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
@@ -18,6 +19,7 @@ import {
   SYSTEM_TENANT_ID,
   type TenantId,
 } from "../engine/types";
+import { InternalError } from "../errors";
 import { isKumikoError } from "../errors/kumiko-error";
 import { createFileContext } from "../files/file-handle";
 import { createFallbackLogger } from "../logging";
@@ -33,8 +35,22 @@ import {
 import { createEscapeHatchReporter } from "../observability/escape-hatch-report";
 import { createDistributedLock, type DistributedLock } from "../pipeline/distributed-lock";
 import { RedisKeys } from "../pipeline/redis-keys";
+import {
+  buildPersonalDataGate,
+  isPersonalDataGated,
+  parseWriteOrigin,
+} from "../pipeline/write-origin";
 import { bridgeStub } from "../testing/handler-context";
 
+// A payload's own `_writeOrigin` is never trusted; only the ambient gated origin is stamped.
+function stampGatedWriteOrigin(data: Record<string, unknown>): void {
+  delete data["_writeOrigin"];
+  const origin = requestContext.get()?.writeOrigin;
+  if (origin && isPersonalDataGated(origin)) {
+    data["_writeOrigin"] = origin;
+  }
+}
+
 // Queue-name convention: <prefix>-<lane>. The prefix is fixed in prod
 // ("kumiko-jobs") — it must match between enqueuers and consumers, and an
 // accidental drift would silently drop jobs. Tests override via
@@ -85,8 +101,10 @@ function legacySchedulerIdForJobName(jobName: string): string {
 // for the same trigger (retry after failure, a Redis drop, an instance
 // restarting mid-run) re-derives the *same* child ids, and BullMQ's
 // existing-jobId add() no-ops the second batch instead of creating
-// duplicates — the same dedup-on-id mechanism bootJobIdForJobName already
-// relies on above. Same colon-in-BullMQ-id hazard as schedulerIdForJobName
+// duplicates — safe only as long as the child job hash outlives the
+// wrapper's retry window, enforced at construction against
+// COMPLETED_JOB_RETENTION_AGE_SEC (see the invariant check in
+// createJobRunner). Same colon-in-BullMQ-id hazard as schedulerIdForJobName
 // (fw#1603/#1604) — the wrapper id already contains ":", so strip
 // separators from both halves before joining instead of interpolating raw.
 function perTenantChildJobId(wrapperJobId: string, tenantId: string): string {
@@ -225,6 +243,13 @@ export type JobRunnerOptions = {
   // before failing boot. Defaults to BOOT_REDIS_TIMEOUT_MS; tests shrink it
   // to keep an unreachable-Redis assertion fast.
   bootRedisTimeoutMs?: number | undefined;
+  // Override how long completed/failed jobs stay in Redis before BullMQ's
+  // lazy queue-wide sweep evicts them. Defaults to
+  // COMPLETED_JOB_RETENTION_AGE_SEC / FAILED_JOB_RETENTION_AGE_SEC; tests
+  // shrink both to exercise the sweep without a real 24h/7d wait.
+  jobRetention?:
+    | { completedAgeSec?: number | undefined; failedAgeSec?: number | undefined }
+    | undefined;
   getActiveTenantIds?: () => Promise<TenantId[]>;
   onJobStart?: (jobName: string, jobId: string, meta: JobMeta) => void;
   onJobComplete?: (
@@ -323,9 +348,10 @@ function timeoutReject(
 // waiting.
 const DEFAULT_JOB_BACKOFF_DELAY_MS = 1_000;
 
-// Shared by dispatch() and handleEvent() — an event-triggered job must retry
-// on failure the same way a directly-dispatched one does; a duplicated
-// inline computation in handleEvent previously dropped both options.
+// Shared by every enqueue path (dispatch(), handleEvent(), cron, runOnBoot,
+// perTenant wrapper/children, sequential re-enqueue) — a job with `retries`
+// set must retry the same way regardless of how it got enqueued, or it
+// fails for good on the very first error on whichever path skips this.
 function buildRetryBullOpts(jobDef: JobDefinition): Pick<JobsOptions, "attempts" | "backoff"> {
   const opts: Pick<JobsOptions, "attempts" | "backoff"> = {};
   if (jobDef.retries !== undefined) opts.attempts = jobDef.retries + 1;
@@ -341,6 +367,34 @@ function buildRetryBullOpts(jobDef: JobDefinition): Pick<JobsOptions, "attempts"
   return opts;
 }
 
+// BullMQ sweeps queue-wide: any job finishing with keepJobs set can evict
+// OTHER jobs in the same completed/failed zset (moveToFinished lua,
+// removeJobsByMaxAge/removeJobsByMaxCount), not just the finishing job, and
+// the sweep only runs lazily on a later finish into that set. Per-job
+// retention is therefore meaningless on a shared queue — only queue-wide,
+// age-only retention (no count) is safe: a count would evict perTenant
+// children still inside their wrapper's retry window, and boot jobs. The
+// completed age must stay above every perTenant wrapper's own worst-case
+// retry window (see maxRetryWindowMs and the invariant check in
+// createJobRunner below), because child dedup (perTenantChildJobId) relies
+// on the children still existing in Redis when a wrapper retry re-derives
+// their ids. The margin here is generous — queue wait time isn't bounded by
+// backoff — to cover realistic windows. Audit trail lives in read_job_runs,
+// not BullMQ (fw#3199).
+const COMPLETED_JOB_RETENTION_AGE_SEC = 86_400; // 24h
+const FAILED_JOB_RETENTION_AGE_SEC = 604_800; // 7d
+
+// Total wall-clock time BullMQ can hold a perTenant wrapper across all its
+// retries, consistent with buildRetryBullOpts's own backoff computation.
+function maxRetryWindowMs(jobDef: JobDefinition): number {
+  if (!jobDef.backoff || jobDef.retries === undefined) return 0;
+  const delayMs =
+    (typeof jobDef.backoff === "string" ? undefined : jobDef.backoff.delayMs) ??
+    DEFAULT_JOB_BACKOFF_DELAY_MS;
+  const type = typeof jobDef.backoff === "string" ? jobDef.backoff : jobDef.backoff.type;
+  return type === "exponential" ? delayMs * (2 ** jobDef.retries - 1) : jobDef.retries * delayMs;
+}
+
 export function createJobRunner(options: JobRunnerOptions): JobRunner {
   const { registry, context, redisUrl, consumerLane } = options;
   const queueNamePrefix = options.queueNamePrefix ?? DEFAULT_QUEUE_NAME_PREFIX;
@@ -397,6 +451,49 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
 
   const allJobs = registry.getAllJobs();
 
+  function positiveIntRetentionSec(
+    value: number | undefined,
+    fallback: number,
+    label: string,
+  ): number {
+    const resolved = value ?? fallback;
+    if (!Number.isInteger(resolved) || resolved <= 0) {
+      throw new Error(
+        `job-runner: jobRetention.${label} must be a positive integer, got ${resolved}`,
+      );
+    }
+    return resolved;
+  }
+  const completedAgeSec = positiveIntRetentionSec(
+    options.jobRetention?.completedAgeSec,
+    COMPLETED_JOB_RETENTION_AGE_SEC,
+    "completedAgeSec",
+  );
+  const failedAgeSec = positiveIntRetentionSec(
+    options.jobRetention?.failedAgeSec,
+    FAILED_JOB_RETENTION_AGE_SEC,
+    "failedAgeSec",
+  );
+
+  // perTenant child dedup (perTenantChildJobId) only holds as long as the
+  // children are still in Redis when a wrapper retry re-derives their ids,
+  // which requires the completed-job retention to outlast the wrapper's own
+  // worst-case retry window. Enforced here, before any Redis connection
+  // opens below, so a misconfigured job fails boot loudly instead of
+  // silently losing dedup in prod.
+  for (const [name, jobDef] of allJobs) {
+    if (!jobDef.perTenant) continue;
+    const windowMs = maxRetryWindowMs(jobDef);
+    if (windowMs >= completedAgeSec * 1000) {
+      throw new Error(
+        `job-runner: perTenant job "${name}" has a retry window of ${windowMs}ms, which is >= ` +
+          `the completed-job retention (${completedAgeSec}s). Child dedup relies on children ` +
+          "staying in Redis for the whole retry window — lower retries/backoff or raise " +
+          "jobRetention.completedAgeSec.",
+      );
+    }
+  }
+
   // Resolve the lane for a job — "worker" is the default because that's the
   // sensible prod lane (heavy async off the request path). Jobs that opted
   // into "api" must have been validated at registry boot already.
@@ -440,9 +537,22 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
   // queue matching the target job's runIn. Client-creation is cheap (shared
   // ioredis connection via bullmq), so this doesn't scale with number of
   // processes.
+  // Queue-wide, age-only retention (see COMPLETED_JOB_RETENTION_AGE_SEC
+  // above for why) — merged into every add()/addBulk()/upsertJobScheduler()
+  // template on both lanes.
+  const jobRetentionOpts: Pick<JobsOptions, "removeOnComplete" | "removeOnFail"> = {
+    removeOnComplete: { age: completedAgeSec },
+    removeOnFail: { age: failedAgeSec },
+  };
   const queues: Readonly<Record<JobRunIn, Queue>> = {
-    api: new Queue(queueNameFor(queueNamePrefix, "api"), { connection: redisOpts }),
-    worker: new Queue(queueNameFor(queueNamePrefix, "worker"), { connection: redisOpts }),
+    api: new Queue(queueNameFor(queueNamePrefix, "api"), {
+      connection: redisOpts,
+      defaultJobOptions: jobRetentionOpts,
+    }),
+    worker: new Queue(queueNameFor(queueNamePrefix, "worker"), {
+      connection: redisOpts,
+      defaultJobOptions: jobRetentionOpts,
+    }),
   };
   // Same unhandled-'error'-crash hazard as lockRedis above, just via
   // BullMQ's internal ioredis client (fw#1805).
@@ -536,9 +646,15 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         await targetQueue.add(
           actualName,
           { ...bullJob.data, _tenantId: tenantId },
-          wrapperJobId !== undefined
-            ? { jobId: perTenantChildJobId(wrapperJobId, tenantId) }
-            : undefined,
+          {
+            ...buildRetryBullOpts(actualDef),
+            // Dedup over wrapper retries only holds as long as the children
+            // stay in Redis for the wrapper's whole retry window — see the
+            // COMPLETED_JOB_RETENTION_AGE_SEC invariant check above.
+            ...(wrapperJobId !== undefined
+              ? { jobId: perTenantChildJobId(wrapperJobId, tenantId) }
+              : {}),
+          },
         );
       }
       // skip: fan-out dispatcher job, per-tenant children enqueued
@@ -567,8 +683,13 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         // same queue the worker just picked from (since only the consuming
         // lane runs handleJob at all), but route explicitly — no implicit
         // coupling to "whichever queue the caller happened to be on".
+        // The re-enqueued job starts with a full retry budget; a remaining
+        // budget is deliberately not carried over, since finalAttempt/
+        // tenantVisibleFailure are computed from jobDef.retries against
+        // attemptsMade, not against some inherited remainder.
         await queues[laneForJob(jobDef)].add(jobName, bullJob.data, {
           delay: SEQUENTIAL_RETRY_DELAY_MS,
+          ...buildRetryBullOpts(jobDef),
         });
         // skip: lock taken, work re-enqueued with delay, current invocation done
         return;
@@ -626,6 +747,21 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // multi-trigger dispatch; exposed as jobContext.triggerName so handlers
     // don't dig through the raw payload themselves.
     const triggerName = rawData["_triggerName"] as string | undefined; // @cast-boundary dynamic-key
+
+    // Absent = legacy or ungated root; present but invalid fails the run closed.
+    const rawWriteOrigin = rawData["_writeOrigin"]; // @cast-boundary dynamic-key
+    let jobOrigin: WriteOrigin | undefined;
+    let writeOriginInvalid = false;
+    if (rawWriteOrigin !== undefined) {
+      const parsed = parseWriteOrigin(rawWriteOrigin);
+      if (parsed) {
+        jobOrigin = { ...parsed, viaJob: jobName };
+      } else {
+        writeOriginInvalid = true;
+      }
+    }
+    const jobPersonalDataGate = jobOrigin ? buildPersonalDataGate(registry, jobOrigin) : undefined;
+
     // Mirror dispatch-shared.ts buildHandlerContext: ctx.files must resolve
     // through the same _fileProviderResolver for jobs as for write-handlers,
     // otherwise event-triggered jobs silently get an unresolved ctx.files.
@@ -644,8 +780,19 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // systemScope() status (pre-existing, not something this change alters)
     // — isSystemJob below is what actually keeps ctx.systemDb off a
     // non-system job; it is the only thing standing between this db and an
-    // unchecked cross-tenant escape hatch for such a job.
-    const tenantScopedDb = configDb ? createTenantDb(configDb, tenantId, "system") : undefined;
+    // unchecked cross-tenant escape hatch for such a job. Gated like jobDb so
+    // ctx.systemDb, built from it, is gated too.
+    const tenantScopedDb = configDb
+      ? createTenantDb(
+          configDb,
+          tenantId,
+          "system",
+          undefined,
+          undefined,
+          undefined,
+          jobPersonalDataGate ? { personalDataGate: jobPersonalDataGate } : undefined,
+        )
+      : undefined;
     const isSystemJob = registry.isJobSystemScoped(jobName);
     // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
     const reportEscapeHatch = createEscapeHatchReporter({
@@ -663,6 +810,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       ? createTenantDb(configDb, tenantId, "tenant", context.tracer, context.meter, undefined, {
           unsafeRaw: jobDef.escapeHatch,
           report: reportEscapeHatch,
+          ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
         })
       : undefined;
     const config =
@@ -713,7 +861,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             "JobContext.write called before dispatcher attached — call attachDispatcher() first",
           );
         }
-        return dispatchWriteRef.write(jobSystemUser, qn, payload);
+        return dispatchWriteRef.write(jobSystemUser, qn, payload, jobOrigin);
       },
       writeAs: (user: SessionUser, qn: string, payload: unknown) => {
         if (!dispatchWriteRef) {
@@ -721,7 +869,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             "JobContext.writeAs called before dispatcher attached — call attachDispatcher() first",
           );
         }
-        return dispatchWriteRef.write(user, qn, payload);
+        return dispatchWriteRef.write(user, qn, payload, jobOrigin);
       },
       queryAs: (user: SessionUser, qn: string, payload: unknown) => {
         if (!dispatchWriteRef) {
@@ -729,7 +877,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             "JobContext.queryAs called before dispatcher attached — call attachDispatcher() first",
           );
         }
-        return dispatchWriteRef.queryAs(user, qn, payload);
+        return dispatchWriteRef.queryAs(user, qn, payload, jobOrigin);
       },
       queryAsMember: (userId: string, qn: string, payload: unknown) => {
         if (!dispatchWriteRef) {
@@ -761,6 +909,13 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
 
     const runInSpan = async (): Promise<void> => {
       try {
+        if (writeOriginInvalid) {
+          throw new InternalError({
+            message:
+              `Job "${jobName}" received an unparseable _writeOrigin — refusing to run without ` +
+              "a trustworthy anonymous-root gate.",
+          });
+        }
         await requestContext.run(
           {
             requestId: jobRequestId,
@@ -768,6 +923,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             // #3043 — events a job writes carry the job as their origin.
             handler: jobName,
             feature: qnScope(jobName),
+            writeOrigin: jobOrigin,
           },
           () => jobDef.handler(payload, jobContext),
         );
@@ -914,20 +1070,48 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             {
               name: jobDef.perTenant ? `_perTenant:${name}` : name,
               data: {},
+              // Queue-level defaultJobOptions (jobRetentionOpts) covers
+              // retention; a count here would sweep queue-wide again and
+              // evict perTenant children and boot jobs.
               opts: {
-                removeOnComplete: { count: 100 },
-                removeOnFail: { count: 50 },
+                ...buildRetryBullOpts(jobDef),
               },
             },
           );
         }
       }
 
+      // Persistent marker outside the swept completed/failed sets: a plain
+      // Redis hash at one key per consumer queue, fields = boot job ids
+      // already enqueued (BullMQ's IRedisClient has no set commands, only
+      // hash/hexists — a hash with dummy values does the same job). The job
+      // hash itself (removeOnComplete/-Fail: age-bound) is not a safe dedup
+      // target any more — retention now evicts it eventually, which would
+      // otherwise re-run a boot job "once per dataset" every time it ages
+      // out. Order matters: HEXISTS check, then add(), then HSET.
+      // Concurrent starts still dedupe on the existing job hash from add()'s
+      // own jobId no-op; a crash between add() and HSET dedupes again on the
+      // *next* boot (the job hash is still there) instead of losing the
+      // boot job forever, which HSET-first would risk if the process died
+      // before add() ran.
+      const bootEnqueuedKey = consumerQueue.toKey("kumiko-boot-enqueued");
       for (const [name, jobDef] of allJobs) {
         if (laneForJob(jobDef) !== consumerLane) continue;
         if (jobDef.runOnBoot) {
           const bootName = jobDef.perTenant ? `_perTenant:${name}` : name;
-          await consumerQueue.add(bootName, {}, { jobId: bootJobIdForJobName(name) });
+          const bootJobId = bootJobIdForJobName(name);
+          const client = await consumerQueue.client;
+          const alreadyEnqueued = await client.hexists(bootEnqueuedKey, bootJobId);
+          if (alreadyEnqueued) continue;
+          await consumerQueue.add(
+            bootName,
+            {},
+            {
+              jobId: bootJobId,
+              ...buildRetryBullOpts(jobDef),
+            },
+          );
+          await client.hset(bootEnqueuedKey, { [bootJobId]: 1 });
         }
       }
 
@@ -974,7 +1158,13 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
 
       // perTenant: dispatch the fan-out wrapper instead
       if (jobDef.perTenant) {
-        const job = await targetQueue.add(`_perTenant:${jobName}`, payload ?? {});
+        const perTenantData: Record<string, unknown> = { ...(payload ?? {}) };
+        stampGatedWriteOrigin(perTenantData);
+        const job = await targetQueue.add(
+          `_perTenant:${jobName}`,
+          perTenantData,
+          buildRetryBullOpts(jobDef),
+        );
         return job.id ?? "unknown";
       }
 
@@ -1047,6 +1237,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       // stamp the same correlation as the HTTP request that scheduled it.
       const reqCtx = requestContext.get();
       if (reqCtx?.correlationId) data["_correlationId"] = reqCtx.correlationId;
+      stampGatedWriteOrigin(data);
 
       const job = await targetQueue.add(jobName, data, bullOpts);
       return job.id ?? "unknown";
@@ -1091,6 +1282,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
             continue;
           }
         }
+        stampGatedWriteOrigin(data);
         // Route to the job's declared lane, not a fixed queue — that's
         // the whole reason both queues are held.
         await queues[laneForJob(jobDef)].add(name, data, buildRetryBullOpts(jobDef));

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-utils.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { createSystemUser } from "../../engine/system-user";
 import { InternalError } from "../../errors";
+import { VersionConflictError as EventStoreVersionConflictError } from "../../event-store/errors";
 import {
   describeShape,
   dispatcherSpanAttributes,
@@ -115,6 +116,13 @@ describe("wrapToKumiko", () => {
     expect(wrapped.code).toBe("internal_error");
     expect(wrapped.cause).toBeInstanceOf(TypeError);
   });
+
+  test("maps an event-store version conflict to a 409 version_conflict", () => {
+    const wrapped = wrapToKumiko(new EventStoreVersionConflictError("agg-1", 3));
+    expect(wrapped.code).toBe("version_conflict");
+    expect(wrapped.httpStatus).toBe(409);
+    expect(wrapped.details).toMatchObject({ entityId: "agg-1", expectedVersion: 3 });
+  });
 });
 
 describe("extractNestedSpecs", () => {

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