@cosmicdrift/kumiko-framework 0.304.0 → 0.306.0

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,112 @@
 [
+  {
+    "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",
+    "title": "rateLimit.auth (L2) no longer throttles GET /api/auth/tenants",
+    "detail": "The SPA's own session bootstrap called GET /api/auth/tenants on every\npage load, which counted against the L2 auth-endpoint bucket and threw\n429 on the 6th page load within a minute. This route is now exempted\nfrom rateLimit.auth by exact method+path match; all other auth routes\n(including POST on the same path, if ever added) are unaffected.",
+    "migration": "Apps using the default rateLimit.auth need no changes. Apps that want\nto keep throttling GET /api/auth/tenants should rely on rateLimit.global\n(L1, IP-based) instead. Credential-submitting POST routes are unaffected\neven when rateLimit.auth's `path` option is customized."
+  },
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "KUMIKO_DRY_RUN_ENV=pulumi and =k8s now list optional env keys (e.g. PROMETHEUS_METRICS_TOKEN) as commented-out lines under an \"Optional\" header, with secret flag, generator and description; defaulted keys stay omitted",
+    "migration": "No action needed. Uncomment and set an optional line only when you want to enable that feature."
+  },
+  {
+    "version": "0.305.0",
+    "type": "improvement",
+    "title": "ExtraRouteRejection supports 503 + Retry-After for signature routes whose verify() is temporarily unable to run"
+  },
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "Job backoff now waits between retries: backoff defaults to a 1000 ms base delay and accepts { type, delayMs } (fw#3167)",
+    "detail": "Previously, jobs with backoff set retried immediately: BullMQ received only { type } with no delay, and its fixed/exponential strategies compute NaN/undefined without one (falsy, so no wait). Now \"fixed\" waits a constant 1000 ms and \"exponential\" waits 1000/2000/4000 ms... between attempts by default. Jobs with a high retries count will therefore take noticeably longer to reach their final failure. A new object form, backoff: { type, delayMs }, lets a job configure its own base delay instead of the 1000 ms default."
+  },
+  {
+    "version": "0.305.0",
+    "type": "breaking",
+    "title": "Writes under an anonymous root need access.personalData: \"public-intake\" at runtime, across feature boundaries (fw#3165)",
+    "detail": "The boot check from fw#2885 only sees personal-data keys in an anonymous write handler's own input schema, for entities of its own feature. Every public dispatch (write, batch command, query, stream) now computes a WriteOrigin (root handler, anonymous root, public-intake declared) once. Every nested call inherits it: ctx.write, ctx.writeAs, ctx.query, ctx.queryAs, nested writes and afterCommit hooks. When the root is anonymous and does not declare public-intake, a write that touches a personal-data field (pii / userOwned / recordOwned) of any registered entity fails with AccessDeniedError, details.reason \"public_intake_required\". The error details name the root handler, the table and the fields, never the values. The check runs in TenantDb.insertOne/updateMany, in db.global().insertOne/updateMany and in the event-sourced create/update executor, after preSave and before the event append. It also covers rebound TenantDbs (acknowledgeCrossTenant, hook re-gating). Authenticated sessions are not affected. Not gated: ctx.db.unsafeRaw (covered by escapeHatch plus audit); ctx.appendEvent on a feature's own events (foreign events are already rejected); tables outside the registered entities; jobs and event subscribers queued from an anonymous root; and TenantDbs that handler code builds directly with createTenantDb. The last two are tracked in fw#3185, which also lists the bundled auth-email-password and user-data-rights flows that go through unsafeRaw or createTenantDb.",
+    "migration": "A write handler that anonymous callers can reach (roles include \"anonymous\") and that writes a personal-data field (pii / userOwned / recordOwned) of any entity must declare access: { roles: [..., \"anonymous\"], personalData: \"public-intake\" }. This applies whether the handler writes the field itself or through ctx.db, the CRUD executor, ctx.write, ctx.writeAs/queryAs or a postSave/afterCommit hook, and it applies across features. Without the declaration the write now fails with AccessDeniedError (details.reason \"public_intake_required\"). A failing afterCommit hook is only logged, and its write does not happen. Known consumer handlers, measured on 23.09.2026: offlot-app waitlist:submit, vehicle-enquiry:submit and try-first:set-contact; publicstatus email-subscriber:subscribe; show-pony rsvp:submit. Add the declaration if the anonymous intake is intended (the handler's rateLimit is then the only protection). Otherwise stop writing the field from the anonymous path."
+  },
+  {
+    "version": "0.305.0",
+    "type": "improvement",
+    "title": "setupTestStack accepts a metrics option, forwarded to buildServer like runProdApp (fw#3182)",
+    "detail": "TestStackOptions gains an optional metrics field forwarded to buildServer, same as runProdApp. Spread resolveObservabilityWiring(token) into setupTestStack/setupTestStackFromFeatures/setupAppTestStack to get /metrics mounted in integration tests with the same token-gated PrometheusMeter-backed behavior as prod."
+  },
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "Write-path 5xx logs now include the original cause chain"
+  },
   {
     "version": "0.303.0",
     "type": "breaking",

package/src/db/__tests__/pg-error.test.ts

@@ -18,6 +18,20 @@ describe("extractPgError", () => {
   test("returns null for non-objects", () => {
     expect(extractPgError("nope")).toBeNull();
   });
+
+  test("normalizes Bun.SQL's errno/constraint into code/constraint_name", () => {
+    const info = extractPgError({
+      code: "ERR_POSTGRES_SERVER_ERROR",
+      errno: "23505",
+      constraint: "users_email_uq",
+    });
+    expect(info).toEqual({ code: "23505", constraint_name: "users_email_uq" });
+  });
+
+  test("leaves ERR_POSTGRES_SERVER_ERROR untouched when errno isn't a string", () => {
+    const info = extractPgError({ code: "ERR_POSTGRES_SERVER_ERROR" });
+    expect(info).toEqual({ code: "ERR_POSTGRES_SERVER_ERROR", constraint_name: undefined });
+  });
 });
 
 describe("isUniqueViolation", () => {

package/src/db/__tests__/system-db-view-export.test.ts

@@ -0,0 +1,107 @@
+// createUncheckedSystemDb() is framework-private (not re-exported from
+// db/index.ts); createSystemDbView is the public replacement, whose
+// unsafeRaw follows the source TenantDb's own escapeHatch gate instead of
+// handing out an ungated tenantDbRunner(db).
+
+import { describe, expect, test } from "bun:test";
+import * as dbBarrel from "@cosmicdrift/kumiko-framework/db";
+import { createSystemDbView, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { AccessDeniedError } from "../../errors";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import { unsafeRawForDeclaredStep, withSystemDbUnsafeRawGrant } from "../tenant-db";
+
+const tenantId = testTenantId(1);
+
+function fakeRunner(): DbRunner {
+  return {
+    unsafe: async () => {
+      throw new Error("system-db-view-export tests must not reach the DB");
+    },
+    begin: async () => {
+      throw new Error("system-db-view-export tests must not reach the DB");
+    },
+  } as unknown as DbRunner;
+}
+
+describe("db barrel export", () => {
+  test("createUncheckedSystemDb is no longer exported from @cosmicdrift/kumiko-framework/db", () => {
+    expect("createUncheckedSystemDb" in dbBarrel).toBe(false);
+  });
+});
+
+describe("createSystemDbView(...).unsafeRaw", () => {
+  test("denies without a grant on the source TenantDb, without reporting on either side", () => {
+    const sourceReports: Array<{ kind: string; reason: string }> = [];
+    const viewReports: Array<{ kind: string; reason: string }> = [];
+    const source = createTenantDb(
+      fakeRunner(),
+      tenantId,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      { report: (kind, reason) => sourceReports.push({ kind, reason }) },
+    );
+    const view = createSystemDbView(source, undefined, (kind, reason) =>
+      viewReports.push({ kind, reason }),
+    );
+
+    expect(() => view.unsafeRaw("x")).toThrow(AccessDeniedError);
+    expect(sourceReports).toEqual([]);
+    expect(viewReports).toEqual([]);
+  });
+
+  test("resolves to the source's own bound runner and reports through the source, not the view", () => {
+    const runner = fakeRunner();
+    const sourceReports: Array<{ kind: string; reason: string }> = [];
+    const viewReports: Array<{ kind: string; reason: string }> = [];
+    const source = createTenantDb(runner, tenantId, "tenant", undefined, undefined, undefined, {
+      unsafeRaw: { reason: "handler declared unsafeRaw" },
+      report: (kind, reason) => sourceReports.push({ kind, reason }),
+    });
+    const view = createSystemDbView(source, undefined, (kind, reason) =>
+      viewReports.push({ kind, reason }),
+    );
+
+    expect(view.unsafeRaw("x")).toBe(runner);
+    expect(sourceReports).toEqual([{ kind: "unsafe-raw", reason: "x" }]);
+    expect(viewReports).toEqual([]);
+  });
+
+  test("memberReadOnly on the source denies even with an unsafeRaw grant", () => {
+    const source = createTenantDb(
+      fakeRunner(),
+      tenantId,
+      "tenant",
+      undefined,
+      undefined,
+      undefined,
+      { unsafeRaw: { reason: "handler declared unsafeRaw" }, memberReadOnly: true },
+    );
+    const view = createSystemDbView(source);
+
+    expect(() => view.unsafeRaw("x")).toThrow(AccessDeniedError);
+    expect(() => view.unsafeRaw("x")).toThrow(/read-only/);
+  });
+});
+
+describe("unsafeRawForDeclaredStep(createSystemDbView(...))", () => {
+  test("throws AccessDeniedError, not InternalError, without a grant on the source", () => {
+    const source = createTenantDb(fakeRunner(), tenantId, "tenant");
+    const view = createSystemDbView(source);
+
+    expect(() => unsafeRawForDeclaredStep(view, "x")).toThrow(AccessDeniedError);
+  });
+});
+
+describe("withSystemDbUnsafeRawGrant(createSystemDbView(...))", () => {
+  test("returns the view unchanged — no rebind, so no rights upgrade over the source's own gate", () => {
+    const source = createTenantDb(fakeRunner(), tenantId, "tenant");
+    const view = createSystemDbView(source);
+
+    const rebound = withSystemDbUnsafeRawGrant(view, { reason: "hook grant" }, "some hook");
+    expect(rebound).toBe(view);
+    expect(() => rebound.unsafeRaw("x")).toThrow(AccessDeniedError);
+  });
+});

package/src/db/__tests__/tenant-db-no-raw.test.ts

@@ -3,6 +3,7 @@ import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { InternalError } from "../../errors";
 import { testTenantId } from "../../stack";
 import type { DbRunner } from "../connection";
+import { asRawClient } from "../query";
 import { createTenantDb, createUncheckedSystemDb, withUnsafeRawGrant } from "../tenant-db";
 import { tenantDbRunner } from "../tenant-db-runner";
 
@@ -26,6 +27,15 @@ describe("TenantDb has no .raw", () => {
     // @ts-expect-error TenantDb no longer exposes `raw`.
     expect(tdb.raw).toBeUndefined();
   });
+
+  test("createTenantDb rejects an already tenant-scoped TenantDb: compile error, and raw access throws", () => {
+    const tdb = createTenantDb(fakeRunner(), tenantId);
+    expect(() => {
+      // @ts-expect-error TenantDb is already tenant-scoped; createTenantDb only accepts a raw DbRunner.
+      const rewrapped = createTenantDb(tdb, tenantId);
+      asRawClient(tenantDbRunner(rewrapped));
+    }).toThrow();
+  });
 });
 
 describe("tenantDbRunner", () => {

package/src/db/__tests__/with-systemdb-unsafe-raw-grant.test.ts

@@ -0,0 +1,71 @@
+// fw#3198 — unit coverage for withSystemDbUnsafeRawGrant: passthrough for
+// unknown values, no stacking across repeated rebinds, and the gated runner
+// registered under declaredUnsafeRawRunners (unsafeRawForDeclaredStep).
+
+import { describe, expect, test } from "bun:test";
+import type { UncheckedSystemDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { AccessDeniedError } from "../../errors";
+import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
+import {
+  createTenantDb,
+  createUncheckedSystemDb,
+  unsafeRawForDeclaredStep,
+  withSystemDbUnsafeRawGrant,
+} from "../tenant-db";
+
+const tenantId = testTenantId(1);
+
+function fakeRunner(): DbRunner {
+  return {
+    unsafe: async () => [],
+    begin: async () => {
+      throw new Error("begin not used in these tests");
+    },
+  } as unknown as DbRunner;
+}
+
+describe("withSystemDbUnsafeRawGrant", () => {
+  test("passes through a value not built by createUncheckedSystemDb, unchanged", () => {
+    const notBuilt = { unsafeRaw: () => fakeRunner() } as unknown as UncheckedSystemDb;
+    const rebound = withSystemDbUnsafeRawGrant(notBuilt, { reason: "x" }, "some hook");
+    expect(rebound).toBe(notBuilt);
+  });
+
+  test("without a grant, unsafeRaw denies with AccessDeniedError naming the caller", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    const gated = withSystemDbUnsafeRawGrant(systemDb, undefined, 'postSave hook of feature "x"');
+    expect(() => gated.unsafeRaw("a reason")).toThrow(AccessDeniedError);
+    expect(() => gated.unsafeRaw("a reason")).toThrow(/postSave hook of feature "x"/);
+  });
+
+  test("with a grant, unsafeRaw resolves to the original runner", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    const gated = withSystemDbUnsafeRawGrant(systemDb, { reason: "hook reason" }, "hook");
+    expect(gated.unsafeRaw("hook reason")).toBe(runner);
+  });
+
+  test("repeated rebinding is not stacked — a second rebind reflects only its own grant", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    const grantedFirst = withSystemDbUnsafeRawGrant(systemDb, { reason: "first" }, "hook-1");
+    const deniedSecond = withSystemDbUnsafeRawGrant(grantedFirst, undefined, "hook-2");
+    expect(() => deniedSecond.unsafeRaw("first")).toThrow(AccessDeniedError);
+    // Re-granting from the ORIGINAL systemDb (not stacked through grantedFirst) still works.
+    const grantedThird = withSystemDbUnsafeRawGrant(systemDb, { reason: "third" }, "hook-3");
+    expect(grantedThird.unsafeRaw("third")).toBe(runner);
+  });
+
+  test("the gated runner is registered for unsafeRawForDeclaredStep", () => {
+    const runner = fakeRunner();
+    const tdb = createTenantDb(runner, tenantId, "system");
+    const systemDb = createUncheckedSystemDb(tdb);
+    const gated = withSystemDbUnsafeRawGrant(systemDb, { reason: "hook reason" }, "hook");
+    expect(unsafeRawForDeclaredStep(gated, "hook reason")).toBe(runner);
+  });
+});

package/src/db/event-store-executor-write.ts

@@ -31,6 +31,7 @@ import {
   tryMapUniqueViolation,
 } from "./event-store-executor-context";
 import { runInSavepointIfSupported } from "./query";
+import { assertPersonalDataWrite, tableNameOf } from "./tenant-db";
 import { tenantDbRunner } from "./tenant-db-runner";
 
 // Art. 17 erasure runs as the framework operator, not as a row owner; a
@@ -145,6 +146,9 @@ export function createWriteVerbs(
       if ("failure" in preSaveResult) return preSaveResult.failure;
       const data = preSaveResult.data;
 
+      // After preSave so derived fields count, before the event append so nothing persists.
+      assertPersonalDataWrite(db, tableNameOf(table), Object.keys(data), entity);
+
       // H.2 — entity-level write-ownership on create. No oldRow exists, so
       // only the new row is checked. No Straddle concern for creates.
       if (!userCanCreateFieldRow(user, entity.access?.write, data)) {
@@ -334,6 +338,9 @@ export function createWriteVerbs(
       if ("failure" in preSaveResult) return preSaveResult.failure;
       const changes = preSaveResult.data;
 
+      // After preSave so derived fields count, before the event append so nothing persists.
+      assertPersonalDataWrite(db, tableNameOf(table), Object.keys(changes), entity);
+
       // H.2 — entity-level write-ownership on update. Load old row (already
       // done above), build post-change row via shallow merge. Straddle-safe
       // multi-role check: at least one role must accept BOTH old and new —

package/src/db/index.ts

@@ -155,7 +155,7 @@ export {
 export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db";
 export {
   castTenantRows,
+  createSystemDbView,
   createTenantDb,
-  createUncheckedSystemDb,
   SYSTEM_SCOPE_CHECK_BRAND,
 } from "./tenant-db";

package/src/db/pg-error.ts

@@ -21,6 +21,19 @@ export function extractPgError(e: unknown): PgErrorInfo | null {
     // @cast-boundary error-details — postgres-js error shape (code, constraint_name)
     const code = (layer as { code?: string }).code;
     const constraintName = (layer as { constraint_name?: string }).constraint_name; // @cast-boundary error-details
+    // Bun.SQL carries the SQLSTATE in `errno` (string) and the constraint name
+    // in `constraint`, not in postgres-js's `code`/`constraint_name`.
+    if (code === "ERR_POSTGRES_SERVER_ERROR") {
+      const errno = (layer as { errno?: unknown }).errno; // @cast-boundary error-details
+      const constraint = (layer as { constraint?: unknown }).constraint; // @cast-boundary error-details
+      if (typeof errno === "string") {
+        return {
+          code: errno,
+          constraint_name:
+            constraintName ?? (typeof constraint === "string" ? constraint : undefined),
+        };
+      }
+    }
     if (code !== undefined || constraintName !== undefined) {
       return { code, constraint_name: constraintName };
     }