@cosmicdrift/kumiko-framework 0.305.0 → 0.306.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.305.0",
+  "version": "0.306.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.305.0",
-    "@cosmicdrift/kumiko-types": "0.305.0",
+    "@cosmicdrift/kumiko-http": "0.306.0",
+    "@cosmicdrift/kumiko-types": "0.306.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.305.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.306.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/server-boot-guards.test.ts

@@ -228,6 +228,7 @@ describe("buildServer — auth membershipQuery requires a principalStatus provid
     r.extendsRegistrar(EXT_PRINCIPAL_STATUS, {});
     r.useExtension(EXT_PRINCIPAL_STATUS, "has-principal-status", {
       resolveStatus: async () => "active" as const,
+      resolveProfile: async () => ({ globalRoles: [] }),
     });
   });
 

package/src/api/__tests__/server-error-logging.test.ts

@@ -66,6 +66,16 @@ const boomFeature = defineFeature("boom", (r) => {
     async () => ({ ok: true }),
     openToAll,
   );
+  // Same abort path TenantDb uses (signal.throwIfAborted()), without a DB.
+  r.queryHandler(
+    "abort-probe",
+    z.object({}),
+    async (_query, ctx) => {
+      ctx.signal?.throwIfAborted();
+      return { ok: true };
+    },
+    openToAll,
+  );
 });
 
 const { app, jwt } = buildServer({
@@ -178,6 +188,67 @@ describe("HTTP layer logs unexpected 5xx faults", () => {
     expect(status).toBe(404);
     expect(apiFaultLog(errors)).toBeUndefined();
   });
+
+  test("a pre-aborted client signal 499s and logs a warn, not '[api] handler failed'", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const warnings: unknown[][] = [];
+    const errors: unknown[][] = [];
+    const warnSpy = spyOn(console, "warn").mockImplementation((...args) => {
+      warnings.push(args);
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation((...args) => {
+      errors.push(args);
+    });
+    try {
+      const res = await app.request(
+        new Request("http://test.local/api/query", {
+          method: "POST",
+          headers: await auth(),
+          body: JSON.stringify({ type: "boom:query:abort-probe", payload: {} }),
+          signal: controller.signal,
+        }),
+      );
+      expect(res.status).toBe(499);
+      expect(apiFaultLog(errors)).toBeUndefined();
+      const hit = warnings.find(
+        (args) =>
+          typeof args[0] === "string" && args[0].includes("[api] request aborted by client"),
+      );
+      expect(hit).toBeDefined();
+      const data = hit?.[1];
+      expect(isRecord(data)).toBe(true);
+      if (!isRecord(data)) return;
+      expect(data["status"]).toBe(499);
+      expect(data["type"]).toBe("boom:query:abort-probe");
+    } finally {
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  test("a pre-aborted client signal still 500s + logs when the handler fails for an unrelated reason", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "error").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      const res = await app.request(
+        new Request("http://test.local/api/query", {
+          method: "POST",
+          headers: await auth(),
+          body: JSON.stringify({ type: "boom:query:explode", payload: {} }),
+          signal: controller.signal,
+        }),
+      );
+      expect(res.status).toBe(500);
+      expect(apiFaultLog(calls)).toBeDefined();
+    } finally {
+      spy.mockRestore();
+    }
+  });
 });
 
 describe("HTTP layer logs 4xx client faults on warn (#3077)", () => {

package/src/api/request-context.ts

@@ -17,10 +17,11 @@ import { generateId } from "../utils";
 //                   with correlationId, forms a causal DAG across streams.
 //   signal        — AbortSignal from the underlying HTTP request. Aborts
 //                   when the client disconnects (mobile back-press, tab
-//                   close). Long-running framework code (event streaming,
-//                   projection rebuild) checks signal.aborted at chunk
-//                   boundaries; short queries don't pay the overhead.
-//                   Undefined for non-HTTP entry-points (jobs, MSP-applies).
+//                   close). Query/stream handlers check signal.aborted at
+//                   chunk or query boundaries; runBatch (write dispatch)
+//                   strips it before executing so a disconnect can't abort
+//                   a transaction mid-commit. Undefined for non-HTTP
+//                   entry-points (jobs, MSP-applies) and inside write batches.
 export type RequestContextData = {
   readonly requestId: string;
   readonly correlationId: string;

package/src/api/routes.ts

@@ -29,6 +29,10 @@ export const StreamFrame = {
   error: "error",
 } as const;
 
+// Non-standard but widely used for "client hung up" — distinct from a real
+// 5xx so a disconnect never gets logged as a server fault.
+const CLIENT_CLOSED_REQUEST_STATUS = 499;
+
 export type ApiRoutesOptions = {
   // Override the SSE heartbeat interval (ms). Default SSE_HEARTBEAT_INTERVAL_MS.
   // Deployment-tunable for proxies with different idle timeouts — also used
@@ -203,7 +207,7 @@ export function createApiRoutes(dispatcher: Dispatcher, options: ApiRoutesOption
       // in-flight .next(), so awaiting here would block the response until
       // that pending pull resolves (which may be never for an idle stream).
       void generator.return(undefined).catch(() => {});
-      return c.body(null, 499 as ContentfulStatusCode); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+      return c.body(null, CLIENT_CLOSED_REQUEST_STATUS as ContentfulStatusCode); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
     }
 
     return streamSSE(c, async (stream) => {
@@ -364,6 +368,13 @@ function logClientFault(err: KumikoError, requestId: string | undefined, type?:
   });
 }
 
+// Identity-checked against THIS request's signal — signal.aborted alone
+// would also match a real 5xx that happens to race a disconnect.
+function isClientAbort(err: KumikoError): boolean {
+  const signal = requestContext.get()?.signal;
+  return signal?.aborted === true && err.cause !== undefined && err.cause === signal.reason;
+}
+
 // Unexpected server faults (5xx) carry their diagnostic stack only on the
 // in-process error — serializeError strips cause/details from the wire body.
 // Without this a wrapped throw (InternalError{cause}) returns a 500 with zero
@@ -401,6 +412,20 @@ function writeErrorResponse(c: Context, err: KumikoError, type?: string) {
 // keep the same lean shape on failure — only the `error` key.
 function queryErrorResponse(c: Context, err: KumikoError, type?: string) {
   const requestId = requestContext.get()?.requestId;
+  if (isClientAbort(err)) {
+    if (clientFaultLoggingEnabled()) {
+      const startedAt = requestContext.get()?.startedAt;
+      createFallbackLogger("api").warn("request aborted by client", {
+        requestId,
+        type: type?.slice(0, MAX_LOGGED_TYPE_LENGTH),
+        status: CLIENT_CLOSED_REQUEST_STATUS,
+        ...(startedAt === undefined
+          ? {}
+          : { durationMs: Math.round(performance.now() - startedAt) }),
+      });
+    }
+    return c.body(null, CLIENT_CLOSED_REQUEST_STATUS as ContentfulStatusCode); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+  }
   logServerFault(err, requestId, type);
   const body = serializeError(err, requestId);
   return c.json(body, err.httpStatus as ContentfulStatusCode); // @cast-boundary engine-payload

package/src/bun-db/__tests__/closed-connection-retry.integration.test.ts

@@ -0,0 +1,159 @@
+// Proves the closed-connection retry against a real postgres-js driver error,
+// plus the Bun.SQL matcher and both drivers' extractPgError — see query.ts.
+
+import { afterAll, describe, expect, test } from "bun:test";
+import postgres from "postgres";
+import { constraintOf, extractPgError, isUniqueViolation } from "../../db/pg-error";
+import { testDatabaseUrl } from "../../testing/closed-connection-error";
+import { waitFor } from "../../testing/wait-for";
+import { isClosedConnectionError, unsafeReadRetrying } from "../query";
+
+const DATABASE_URL = testDatabaseUrl();
+
+// Terminate targets only the backend running the slow query so the retry
+// lands on the pool's idle connection instead of reconnecting — a postgres-js
+// reconnect under Bun can hang until connect_timeout (30s).
+const adminClient = postgres(DATABASE_URL, { max: 1 });
+afterAll(async () => {
+  await adminClient.end({ timeout: 0 });
+});
+
+type UnsafeFn = (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+type Pool = { unsafe: UnsafeFn };
+
+// Counts unsafe() calls while forwarding everything (including begin/
+// savepoint/options) to the real handle — no mocked behavior, only counting.
+type CountingClient<T> = T & { readonly calls: number };
+function countingClient<T extends Pool>(real: T): CountingClient<T> {
+  let calls = 0;
+  return new Proxy(real, {
+    get(target, prop, receiver) {
+      if (prop === "calls") return calls;
+      if (prop === "unsafe") {
+        return async (...args: Parameters<UnsafeFn>) => {
+          calls++;
+          return target.unsafe(...args);
+        };
+      }
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  }) as CountingClient<T>;
+}
+
+function randomAppName(): string {
+  return `kumiko-cc-retry-${crypto.randomUUID()}`;
+}
+
+// Waits for the slow query's backend to show up as the single active
+// session before terminating exactly that one — the pg_sleep(0.3) window
+// bounds this, so short fixed delays instead of waitFor's default backoff.
+async function pollForActivePid(applicationName: string, queryLike: string): Promise<number> {
+  let pid: number | undefined;
+  await waitFor(
+    async () => {
+      const rows = (await adminClient.unsafe(
+        "select pid from pg_stat_activity where application_name = $1 and state = 'active' and query like $2",
+        [applicationName, queryLike],
+      )) as readonly { pid: number }[];
+      if (rows.length === 1 && rows[0]?.pid !== undefined) {
+        pid = rows[0].pid;
+        return true;
+      }
+      return false;
+    },
+    { delays: Array(100).fill(10) },
+  );
+  if (pid === undefined) {
+    throw new Error(`pollForActivePid: no single active backend found for ${applicationName}`);
+  }
+  return pid;
+}
+
+async function terminateBackendPid(pid: number): Promise<void> {
+  await adminClient.unsafe("select pg_terminate_backend($1)", [pid]);
+}
+
+type DriverKind = "postgres-js" | "bun-sql";
+
+function makePool(kind: DriverKind, max: number, applicationName: string): Pool {
+  if (kind === "postgres-js") {
+    return postgres(DATABASE_URL, {
+      max,
+      connection: { application_name: applicationName },
+    }) as unknown as Pool;
+  }
+  return new Bun.SQL({
+    url: DATABASE_URL,
+    max,
+    connection: { application_name: applicationName },
+  }) as unknown as Pool;
+}
+
+async function closePool(kind: DriverKind, pool: unknown): Promise<void> {
+  if (kind === "postgres-js") {
+    await (pool as { end: (opts?: { timeout?: number }) => Promise<void> }).end({ timeout: 0 });
+  } else {
+    await (pool as { close: () => Promise<void> }).close();
+  }
+}
+
+const drivers: DriverKind[] = ["postgres-js", "bun-sql"];
+
+// postgres-js only: Bun.SQL sporadically emits an unhandled reject from its
+// internal handleClose in this terminate window, and isn't the prod driver.
+// Multi-retry (≥3 calls) is covered deterministically by the fake-client
+// test in select-many-retry.integration.test.ts instead of a second live test.
+test("retries through a real server-side connection close", async () => {
+  const applicationName = randomAppName();
+  const pool = postgres(DATABASE_URL, {
+    max: 2,
+    connection: { application_name: applicationName },
+  });
+  try {
+    await Promise.all([pool.unsafe("select 1"), pool.unsafe("select 1")]);
+    const counted = countingClient(pool as unknown as Pool);
+    const pending = unsafeReadRetrying(counted as never, "select 1 as x from pg_sleep(0.3)", []);
+    const pid = await pollForActivePid(applicationName, "%pg_sleep(0.3)%");
+    await terminateBackendPid(pid);
+    const rows = await pending;
+    expect([...rows]).toEqual([{ x: 1 }]);
+    expect(counted.calls).toBe(2);
+  } finally {
+    await pool.end({ timeout: 0 });
+  }
+});
+
+test("Bun.SQL closed-connection error matches isClosedConnectionError", async () => {
+  const pool = new Bun.SQL({ url: DATABASE_URL, max: 1 });
+  await pool.unsafe("select 1");
+  await pool.close();
+  const caught = await pool.unsafe("select 1").catch((e: unknown) => e);
+  // @cast-boundary error-details — asserting the real driver error shape
+  expect((caught as { code?: string }).code).toBe("ERR_POSTGRES_CONNECTION_CLOSED");
+  expect(isClosedConnectionError(caught)).toBe(true);
+});
+
+describe.each(drivers)("extractPgError — %s unique-violation SQLSTATE", (kind) => {
+  test("isUniqueViolation and constraintOf resolve the real driver error", async () => {
+    const applicationName = randomAppName();
+    const pool = makePool(kind, 1, applicationName);
+    const tableName = `cc_retry_uniq_${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`;
+    await pool.unsafe(
+      `create table "${tableName}" (id uuid not null, constraint "${tableName}_pk" primary key (id))`,
+    );
+    try {
+      const fixedId = crypto.randomUUID();
+      await pool.unsafe(`insert into "${tableName}" (id) values ($1)`, [fixedId]);
+      const caught = await pool
+        .unsafe(`insert into "${tableName}" (id) values ($1)`, [fixedId])
+        .catch((e: unknown) => e);
+      expect(isUniqueViolation(caught)).toBe(true);
+      expect(extractPgError(caught)?.code).toBe("23505");
+      expect(constraintOf(caught)).toBeDefined();
+    } finally {
+      await pool.unsafe(`drop table if exists "${tableName}"`);
+      await closePool(kind, pool);
+    }
+  });
+});

package/src/bun-db/__tests__/select-many-retry.integration.test.ts

@@ -0,0 +1,138 @@
+// selectMany retries a real captured closed-connection error, never a
+// client abort or a transaction/reserved handle. Live-driver proof is in
+// closed-connection-retry.integration.test.ts.
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import { buildEntityTable } from "../../db/table-builder";
+import { captureClosedConnectionError } from "../../testing/closed-connection-error";
+import { selectMany } from "../query";
+
+let closedConnectionError: unknown;
+
+beforeAll(async () => {
+  closedConnectionError = await captureClosedConnectionError();
+});
+
+type FakeClientOptions = {
+  reserve?: boolean;
+  begin?: boolean;
+  savepoint?: boolean;
+  release?: boolean;
+};
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin?: () => never;
+  savepoint?: () => never;
+  release?: () => never;
+  reserve?: () => never;
+  options?: { max: number };
+  calls: number;
+};
+
+function fakeClient(failures: unknown[], opts: FakeClientOptions = {}): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [{ id: "r1", title: "ok", tenant_id: "t1", inserted_at: null, updated_at: null }];
+    },
+  };
+  const { begin = true, savepoint = false, release = false, reserve = true } = opts;
+  if (begin) {
+    client.begin = () => {
+      throw new Error("not used in test");
+    };
+    client.options = { max: 1 };
+  }
+  if (savepoint)
+    client.savepoint = () => {
+      throw new Error("not used in test");
+    };
+  if (release)
+    client.release = () => {
+      throw new Error("not used in test");
+    };
+  if (reserve)
+    client.reserve = () => {
+      throw new Error("not used in test");
+    };
+  return client;
+}
+
+const table = buildEntityTable("note", {
+  fields: { title: { type: "text", required: true } },
+});
+
+describe("selectMany — closed-connection retry", () => {
+  test("retries once on a real closed-connection error and returns rows", async () => {
+    const db = fakeClient([closedConnectionError]);
+    const rows = await selectMany(db, table);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.title).toBe("ok");
+    expect(db.calls).toBe(2);
+  });
+
+  test("survives two dead connections in a row and returns rows", async () => {
+    const db = fakeClient([closedConnectionError, closedConnectionError]);
+    const rows = await selectMany(db, table);
+    expect(rows).toHaveLength(1);
+    expect(db.calls).toBe(3);
+  });
+
+  test("gives up after exhausting pool-bounded retries (max: 1 → 3 total calls)", async () => {
+    const db = fakeClient([closedConnectionError, closedConnectionError, closedConnectionError]);
+    await expect(selectMany(db, table)).rejects.toBe(closedConnectionError);
+    expect(db.calls).toBe(3);
+  });
+
+  test("never retries on a transaction handle (savepoint, no begin)", async () => {
+    const db = fakeClient([closedConnectionError], {
+      begin: false,
+      savepoint: true,
+      reserve: false,
+    });
+    await expect(selectMany(db, table)).rejects.toBe(closedConnectionError);
+    expect(db.calls).toBe(1);
+  });
+
+  test("never retries on a Bun.SQL-tx-shaped handle (begin + savepoint)", async () => {
+    const db = fakeClient([closedConnectionError], {
+      begin: true,
+      savepoint: true,
+      reserve: false,
+    });
+    await expect(selectMany(db, table)).rejects.toBe(closedConnectionError);
+    expect(db.calls).toBe(1);
+  });
+
+  test("never retries on a reserved handle (begin + release)", async () => {
+    const db = fakeClient([closedConnectionError], { begin: true, release: true, reserve: false });
+    await expect(selectMany(db, table)).rejects.toBe(closedConnectionError);
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry a genuine user abort", async () => {
+    const userAbort = new DOMException("The operation was aborted.", "AbortError");
+    const db = fakeClient([userAbort]);
+    await expect(selectMany(db, table)).rejects.toBe(userAbort);
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry a client abort whose message mentions a closed connection", async () => {
+    const clientAbort = new DOMException("The connection was closed.", "AbortError");
+    const db = fakeClient([clientAbort]);
+    await expect(selectMany(db, table)).rejects.toBe(clientAbort);
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry generic query errors", async () => {
+    const syntax = Object.assign(new Error("syntax error at or near"), { name: "PostgresError" });
+    const db = fakeClient([syntax]);
+    await expect(selectMany(db, table)).rejects.toThrow("syntax error");
+    expect(db.calls).toBe(1);
+  });
+});

package/src/bun-db/query.ts

@@ -729,26 +729,41 @@ function buildWhereClause(
   return { sqlText: conditions.join(" AND "), values };
 }
 
-// #1163: under load the Bun.SQL pool can hand out a connection the server
-// already closed ("The connection was closed.", AbortError code 20) — no
-// validate-on-checkout exists. One retry re-checks out a fresh connection;
-// safe for pure reads. Tx handles are never retried: their transaction is
-// dead once the connection dropped, and a retry would run on the same dead
-// handle. Detection is name+message (not name alone) so a genuine user
-// abort (AbortSignal cancel) is NOT retried.
-function isClosedConnectionError(err: unknown): boolean {
-  if (err === null || typeof err !== "object") return false;
-  const e = err as { name?: unknown; message?: unknown };
+// A pool can briefly keep handing out connections the server just closed.
+// Each failed attempt discards one, so retries are bounded by pool size.
+const CLOSED_CONNECTION_CODES: ReadonlySet<string> = new Set([
+  "CONNECTION_CLOSED", // postgres-js
+  "ERR_POSTGRES_CONNECTION_CLOSED", // Bun.SQL
+  "57P01", // PG SQLSTATE: admin_shutdown / terminated backend
+]);
+
+export function isClosedConnectionError(err: unknown): boolean {
+  const code = extractPgError(err)?.code;
+  return code !== undefined && CLOSED_CONNECTION_CODES.has(code);
+}
+
+// Tx/reserved handles are pinned to one physical connection — a retry there
+// would run on the same dead connection, not swap in a fresh one.
+function isPooledClient(raw: unknown): boolean {
+  if (raw === null || (typeof raw !== "object" && typeof raw !== "function")) return false;
+  // @cast-boundary driver handle shape — begin/savepoint/release are optional across drivers
+  const r = raw as { begin?: unknown; savepoint?: unknown; release?: unknown };
   return (
-    e.name === "AbortError" &&
-    typeof e.message === "string" &&
-    /connection was closed/i.test(e.message)
+    typeof r.begin === "function" &&
+    typeof r.savepoint !== "function" &&
+    typeof r.release !== "function"
   );
 }
 
+function poolMaxOf(raw: unknown): number {
+  // @cast-boundary driver pool options — both postgres-js and Bun.SQL expose options.max
+  const max = (raw as { options?: { max?: unknown } }).options?.max;
+  return typeof max === "number" && Number.isInteger(max) && max > 0 ? max : 10;
+}
+
 // Exported so raw-SQL query modules outside bun-db (e.g. bundled-features'
-// db/queries/*.ts) can opt into the same #1163 retry instead of calling
-// asRawClient(db).unsafe(...) directly and losing it.
+// db/queries/*.ts) can opt into the same closed-connection retry instead of
+// calling asRawClient(db).unsafe(...) directly and losing it.
 // READS ONLY — retry re-executes the statement; never pass INSERT/UPDATE/DELETE.
 export async function unsafeReadRetrying<TRow>(
   db: AnyDb,
@@ -759,9 +774,18 @@ export async function unsafeReadRetrying<TRow>(
   try {
     return (await raw.unsafe(sqlText, params)) as readonly TRow[];
   } catch (err) {
-    // TransactionSql has savepoint(), only a top-level pool client has begin().
-    if (typeof raw.begin !== "function" || !isClosedConnectionError(err)) throw err;
-    return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+    if (!isPooledClient(raw) || !isClosedConnectionError(err)) throw err;
+    const maxAttempts = poolMaxOf(raw) + 1;
+    let lastErr: unknown = err;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      try {
+        return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+      } catch (retryErr) {
+        lastErr = retryErr;
+        if (!isClosedConnectionError(retryErr)) throw retryErr;
+      }
+    }
+    throw lastErr;
   }
 }
 

package/src/changes.json

@@ -1,4 +1,70 @@
 [
+  {
+    "version": "0.306.0",
+    "type": "breaking",
+    "title": "A lifecycle hook's own escapeHatch now gates ctx.systemDb.unsafeRaw (fw#3198)",
+    "migration": "Hooks, die in r.systemScope()-Handlern ctx.systemDb.unsafeRaw nutzen, deklarieren escapeHatch: { reason } in den r.hook-Optionen"
+  },
+  {
+    "version": "0.306.0",
+    "type": "fix",
+    "title": "BullMQ jobs no longer stay in Redis forever: completed jobs are kept 24h, failed jobs 7d (fw#3199)",
+    "detail": "Both job-runner lane queues now set age-only retention via defaultJobOptions, so dispatch(), handleEvent(), perTenant wrappers and children, cron, runOnBoot and sequential re-enqueues are all covered. BullMQ sweeps retention queue-wide, so there is no count limit and no per-job retention: the cron template's count-based removeOnComplete/removeOnFail is gone because it evicted boot jobs and perTenant children in the same queue. runOnBoot now dedupes via a persistent per-queue marker, so it still runs at most once per Redis dataset after its job hash ages out. On existing datasets a boot job re-runs once only if its job hash was already evicted. A perTenant job whose retry window reaches the completed retention now fails at job-runner construction. Cron iterations scheduled before the deploy keep the old template options for one more run."
+  },
+  {
+    "version": "0.306.0",
+    "type": "fix",
+    "title": "Client disconnects answer 499 on queries and no longer abort writes",
+    "detail": "- Queries: a failure caused by this request's own abort signal now answers `499` and logs `[api] request aborted by client` on warn instead of a 5xx server fault.\n- Writes (`/api/write`, `/api/batch`, `command`): write dispatch no longer receives the request's abort signal, so a disconnect can't roll back a transaction halfway and leave a cached 500 under the request's idempotency key. `ctx.signal` is `undefined` inside write handlers and their hooks."
+  },
+  {
+    "version": "0.306.0",
+    "type": "breaking",
+    "title": "createUncheckedSystemDb is no longer exported from /db; use createSystemDbView, whose unsafeRaw follows the source TenantDb's escapeHatch gate (fw#3205)",
+    "migration": "Import auf createSystemDbView umstellen; wer unsafeRaw auf einem selbstgebauten systemDb braucht, übergibt eine TenantDb mit unsafeRaw-Grant (createTenantDb(..., { unsafeRaw: { reason } })).\nDelivery: ein tenantUserIdsQuery-Handler ohne r.systemScope() bekommt jetzt wie im Dispatcher eine tenant-mode ctx.db und kein ctx.systemDb; Handler, die Cross-Tenant-Zugriff brauchen, deklarieren r.systemScope()."
+  },
+  {
+    "version": "0.306.0",
+    "type": "fix",
+    "title": "Feature-AST keeps referenced handler access/rateLimit headers",
+    "detail": "Handler headers (access, rateLimit, escapeHatch, agent on write/query/stream handlers, and escapeHatch on r.hook) authored as an imported or same-file const now round-trip verbatim through the feature AST instead of being silently dropped. `rateLimit: { disabled: true, reason }` is now extracted. streamHandler's escapeHatch is now extracted and rendered. A new ParseError: a fully literal header value with an unrecognized shape (used to silently drop the header instead). Handler calls whose object/options contain a spread, an unmodeled key (e.g. `outputSchema`, `perform`) or a non-literal options argument are now kept verbatim as an opaque pattern instead of losing those parts on render. `parsePatternChanges` accepts these reference and disabled-rate-limit shapes too."
+  },
+  {
+    "version": "0.306.0",
+    "type": "improvement",
+    "title": "PatternChange gets an update op that changes individual handler header fields (access, rateLimit, description, agent, escapeHatch, unsafeSkipTransitionGuard) without resending schema or handler bodies",
+    "detail": "applyChanges/updatePattern edit only the named properties of a write/query/stream handler's inline object literal; bodies, comments and all other properties stay byte-identical. parsePatternChanges validates set/unset per handler kind with exact paths (access cannot be unset). escapeHatch.reason must now be non-empty in PatternChange input, matching the boot validator."
+  },
+  {
+    "version": "0.306.0",
+    "type": "breaking",
+    "title": "r.useExtension options are typed per extension point; a hook with the wrong ctx signature is a compile error",
+    "migration": "Registrations of known extension points (tenantData, userData, fileProvider, derivativeRenderer, derivativeOverlayResolver, derivativePublicPredicate, principalStatus, tenantLifecycleStatus, tokenVerifier, sessionStore, tenantResolver, tenantExistence) now type-check their options, and options are required for them. Fix the reported mismatches: tenantData destroy hooks take TenantDataHookCtx and use ctx.db.* methods. For raw access such as archiveStream, declare escapeHatch: { reason } on the r.useExtension registration (runtime grant), call declareEscapeHatch({ reason }) as a direct statement in the hook body (Escape-Hatch-Declared guard), then use ctx.db.unsafeRaw(reason). userData registrations need at least one of export/delete (plus optional order). PrincipalStatusPlugin needs resolveProfile, FileProviderPlugin fakes need list(). App-owned points can opt in by augmenting KumikoExtensionOptionsMap via declare module \"@cosmicdrift/kumiko-framework/engine\"; unknown names keep the untyped options bag."
+  },
+  {
+    "version": "0.306.0",
+    "type": "fix",
+    "title": "Read retry recognizes real closed pool connections instead of client aborts",
+    "detail": "The closed-connection read retry now checks driver error codes (postgres-js CONNECTION_CLOSED, Bun ERR_POSTGRES_CONNECTION_CLOSED, SQLSTATE 57P01) instead of an AbortError name and message. It retries up to pool size plus one attempt, never retries a genuine client abort, and never retries on a transaction or reserved handle. extractPgError/isUniqueViolation/constraintOf now also work against Bun.SQL errors."
+  },
+  {
+    "version": "0.306.0",
+    "type": "breaking",
+    "title": "Tenant-resource and tenantTierResolver extension options are typed; invalid registrations fail tenant destroy loudly",
+    "migration": "Registrations of storageProvider, searchAdapter, externalResource and infraResource now require options of type TenantResourceExtensionHooks (destroyTenant(tenantId, ctx) => Promise<void>); tenantTierResolver requires a TierResolverPlugin with build. StorageProvider* types remain as aliases of the new TenantResource* types. A tenantData or tenant-resource registration whose destroy hook is missing now fails the destruction stage with the extension and entity name instead of being skipped."
+  },
+  {
+    "version": "0.306.0",
+    "type": "breaking",
+    "title": "Idempotent retries re-run after a rolled-back 5xx instead of replaying it",
+    "detail": "Because the retry re-runs, non-transactional side effects of the failed attempt (writes through `ctx.dbOutsideTransaction`, external calls made inside the handler) run again.\n`IdempotencyGuard` has a new required method `release(tenantId, userId, requestId, token)` that frees the in-progress lock (token-guarded, like `store`) instead of persisting a result.",
+    "migration": "Custom IdempotencyGuard implementations must add release(tenantId, userId, requestId, token), which deletes the pending lock only if it still holds that token"
+  },
+  {
+    "version": "0.306.0",
+    "type": "fix",
+    "title": "Cron, runOnBoot, perTenant and sequential re-enqueued jobs now retry per their retries/backoff (fw#3184)"
+  },
   {
     "version": "0.305.0",
     "type": "breaking",