@cosmicdrift/kumiko-framework 0.277.0 → 0.280.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.277.0",
+  "version": "0.280.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,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.277.0",
+    "@cosmicdrift/kumiko-types": "0.280.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.277.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.280.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,31 @@
 [
+  {
+    "version": "0.280.0",
+    "type": "breaking",
+    "title": "TenantDataHookCtx/UserDataHookCtx.db is a tenant-filtered TenantDb; unfiltered hook access needs r.useExtension({ escapeHatch }) (fw#2914 Zugang 3).",
+    "detail": "EXT_TENANT_DATA `destroy` hooks (`TenantDataHookCtx.db`) and EXT_USER_DATA `export`/`delete` hooks (`UserDataHookCtx.db`) no longer receive the unfiltered `DbRunner` that was bound to the extension's owning handler. Both are now a `TenantDb` in \"tenant\" mode, built via the public `createTenantDb(...)`, bound to the hook's `tenantId`: reads/writes go through `ctx.db.selectMany/fetchOne/insertOne/updateMany/deleteMany`, already scoped to that tenant plus `SYSTEM_TENANT_ID` reference rows. `r.useExtension(EXT_USER_DATA | EXT_TENANT_DATA, entityName, { ... })` gains an `escapeHatch?: { reason: string }` option, validated non-empty at registration time (throws at boot for an empty/whitespace reason). Declaring it grants `ctx.db.unsafeRaw(reason)` inside that entity's hooks — same reason string — which returns the real, unfiltered `DbRunner`; without it, `ctx.db.unsafeRaw(reason)` throws `AccessDeniedError`. Every granted use reports an `\"unsafe-raw\"` escape-hatch audit event (`{ handler: \"userData:<entity>\"|\"tenantData:<entity>\", kind, reason, tenantId, actor }`) through the caller's `_escapeHatchAuditSink` when wired, else a `security:escape-hatch-used` warn-log — same #2861 pattern PR #2934 already applied to the job runner, and the same one fw#2914's earlier JobContext.db and read-step changes already applied elsewhere in the framework. `run-forget-cleanup.ts`/`run-user-export.ts` (user-data-rights) thread `escapeHatchAuditSink`/`actor` from their owning `r.job`'s `ctx._escapeHatchAuditSink`/`ctx.systemUser.id` down to each hook's `TenantDb`, so a declared use is attributed to the real job run, not `\"<unattributed>\"`.\n`asRawClient(ctx.db)` inside a hook now throws immediately: `asRawClient` rejects a `TenantDb`-shaped argument (\"received a tenant-scoped TenantDb (ctx.db). Raw SQL helpers do not apply the tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw(reason) with escapeHatch: { reason } ...\"). The framework's `DbRunner`-typed free functions (`selectMany(db, table, where)`, `fetchOne`, `insertOne`, `updateMany`, `deleteMany`, `createTenantDb(db, tenantId, mode)`, etc. from `@cosmicdrift/kumiko-framework/bun-db`/`/db`) now reject `ctx.db` as their first argument at compile time too — `TenantDb` does not structurally satisfy `DbRunner` (no `.unsafe`/`.begin`).\nA table built via `createEntity`+`buildEntityTable`+`r.entity(...)` carries the pre-existing `EXECUTOR_ONLY` brand, so `ctx.db.insertOne/updateMany/deleteMany(table, ...)` against it is a compile error by design (\"a managed projection is only writable through the executor\"); a hook that needs to write such a table directly (bulk hard-delete, jsonb key removal, an UPDATE expression `updateMany`'s literal-value `set` can't express) needs the `escapeHatch` + `ctx.db.unsafeRaw(reason)` route, filtering by tenant/owner in the SQL text itself — the escape hatch removes automatic tenant-filtering, not the hook author's responsibility to filter. A table built via `defineUnmanagedTable` carries no such brand and stays writable through `ctx.db`'s typed methods directly.\nThis PR's own `custom-fields` user-data-rights wiring (`wire-user-data-rights.ts`) uses the escape hatch for exactly this reason: `selectCustomFieldsHostRows` runs against a dynamic host table name unknown at compile time, so it can't use `ctx.db`'s typed methods. CI's `AST-Guards (shared runner)` step (`@cosmicdriftgamestudio/kumiko-guards@^0.36.0`, pinned) does not yet recognize this call shape — `isEscapeHatchDeclaredFunction` in `guard-escape-hatch-declared.ts` only matches a property/method literally named `handler`, or a direct call to `hook`/`writeHandler`/`queryHandler`/`streamHandler`; `r.useExtension(EXT_USER_DATA, entityName, { export: exportHook, escapeHatch })` matches neither, because `useExtension` isn't in `ESCAPE_HATCH_CALL_METHODS` and the hook property here is `export`/`delete`, never `handler`. This also isn't fixable by baselining from kumiko-framework: `security-baselines/<repo>.json` ships inside the pinned `@cosmicdriftgamestudio/kumiko-guards` npm package itself, and `run-guards.ts`'s own comment states it is rewritten only by \"the infra baseline-maintenance run over all repos on main\" — never by a consuming repo's local run, and never persisted through a consuming repo's `bun install`. The fix belongs in the guard's owning repo (presumably `infra`, per this workspace's root `CLAUDE.md`): add `useExtension` to `ESCAPE_HATCH_CALL_METHODS`, or otherwise recognize the framework's actual hook-property names (`export`/`delete`/`destroy`), then release a new `@cosmicdriftgamestudio/kumiko-guards` version and bump the range in kumiko-framework's `package.json`. Until that lands, this PR's `AST-Guards (shared runner)` CI check stays red on this one finding; every other check is green.",
+    "migration": "A hook that only reads/writes its own tenant through `ctx.db` method calls (`ctx.db.selectMany/fetchOne/insertOne/updateMany/deleteMany`) needs no change — it now gets the same tenant filter every other `TenantDb` consumer already had. A hook that treated `ctx.db` as a raw connection (`asRawClient(ctx.db)`, `ctx.db` passed as the first argument to a free-function `selectMany`/`fetchOne`/`insertOne`/`updateMany`/`deleteMany`/`createTenantDb`, a cast to `DbRunner`/`DbConnection`, or `\"raw\" in db ? db.raw : db`) must add `escapeHatch: { reason: \"<why>\" }` to its `r.useExtension(EXT_USER_DATA | EXT_TENANT_DATA, entityName, { ... })` registration and fetch the runner explicitly with `ctx.db.unsafeRaw(\"<why>\")` (same reason string) at the point of use. Prefer converting to `ctx.db`'s typed methods first — reach for `unsafeRaw` only when the target table is `EXECUTOR_ONLY`-branded (a managed `r.entity(...)` table; typed writes reject it by design — see the `EXECUTOR_ONLY`/`WritableTable` note in Detail) or the SQL needs an expression the typed API can't produce (e.g. a jsonb `-` key-removal `UPDATE`). No codemod — cross-hook raw-SQL usage is expected to be rare enough, and tenant-filter-relevant enough, to review by hand per hook. Hand-built `TenantDataHookCtx`/`UserDataHookCtx` objects in tests need `db: createTenantDb(conn, tenantId, \"tenant\", undefined, undefined, undefined, { unsafeRaw: { reason: \"<why>\" } })` instead of a plain connection.\n\nAudit at release — kumiko-enterprise, 7 files across 5 packages, none touched by this PR (out of scope; must be migrated in kumiko-enterprise itself before it bumps its pinned `@cosmicdrift/kumiko-framework`/`@cosmicdrift/kumiko-types` version, or `tsc` fails):\n- `packages/kumiko-credit/src/hooks/userdata-hook-shared.ts` (`forgetMatchingRows`/`anonymizeMatchingRows`, shared by bauspar + credit's delete hooks): `createTenantDb(ctx.db, ctx.tenantId, \"system\")` and `selectMany(ctx.db, table, where)` both take `ctx.db` as a raw-`DbRunner`-typed argument — needs `escapeHatch` on both entities' `r.useExtension(...)` plus `createTenantDb(ctx.db.unsafeRaw(\"<why>\"), ctx.tenantId, \"system\")`; the `selectMany` call can drop the free-function form entirely and become `ctx.db.selectMany(table, where)` (already tenant-scoped to `ctx.tenantId`, no need for \"system\" mode there).\n- `packages/kumiko-credit/src/hooks/bauspar.userdata-hook.ts` and `.../credit.userdata-hook.ts`: each has its own inline `selectMany(ctx.db, table, { ... })` (export hook) — same fix, `ctx.db.selectMany(table, { ... })`.\n- `packages/ai-agent/src/hooks/ai-agent-turn.userdata-hook.ts`, `packages/ai-conversation/src/hooks/designer-conversation-turn.userdata-hook.ts`, `packages/pattern-storage/src/hooks/pattern-file.userdata-hook.ts`, `packages/prompt-store/src/hooks/prompt-template-version.userdata-hook.ts`: each has the same `createTenantDb(ctx.db, ctx.tenantId, \"system\")` + two `selectMany(ctx.db, table, { ... })` inline pair as `userdata-hook-shared.ts` above — same fix per file.\n\n`packages/ai-foundation/src/providers/provenance.ts` (`recordAiCall`) and `packages/ai-pipeline/src/steps/shared.ts` (`recordStepProvenance`) were checked and need NO change: neither registers an EXT_USER_DATA/EXT_TENANT_DATA hook (they run off `HandlerContext`/`WorkflowPipelineCtx`, unrelated to this PR — that context's `.db` was already `TenantDb` from an earlier fw#2914 change), and both already use exactly the pattern this PR expects from hooks too: `withUnsafeRawGrant(ctx.dbOutsideTransaction ?? ctx.db, { reason: PROVENANCE_UNSAFE_RAW_REASON }).unsafeRaw(reason)`.\n\nGuard-version gap: once each of these 7 files declares `escapeHatch` on its `r.useExtension(...)` registration, expect the same `AST-Guards (shared runner)` failure this PR hits on `wire-user-data-rights.ts` (see Detail above) — the currently-pinned `@cosmicdriftgamestudio/kumiko-guards@^0.36.0` doesn't recognize `escapeHatch` on a `useExtension` call. That guard bump has to land (and kumiko-enterprise's pinned guards range has to move) before or alongside this migration, not after."
+  },
+  {
+    "version": "0.279.0",
+    "type": "improvement",
+    "title": "Event-store gains appendProvenanceEvent(db, event), a declared entry point for provenance events (fw#2914).",
+    "detail": "`appendProvenanceEvent` (`@cosmicdrift/kumiko-framework/event-store`) takes a plain `TenantDb` and an event (`aggregateId`, `aggregateType`, `tenantId`, `expectedVersion` — a number or `\"current\"` to resolve the stream's current version inside the same savepoint, `type`, `payload`, `metadata`), grants itself a raw runner with a fixed, framework-owned reason, runs the append in a driver savepoint when one is available, and calls the public `append()`. The reason string is never caller-supplied — only the framework declares why this append is allowed to skip the ownership check. `event.type` must be owner-qualified (`\"<feature>:<name>\"`) and rejects the framework-internal `kumiko:system:` namespace. A `TenantDb` not built by `createTenantDb` fails closed.",
+    "migration": "No action required — purely additive. Existing self-granted `withUnsafeRawGrant(...).unsafeRaw(...)` provenance writers can migrate to `appendProvenanceEvent` in a follow-up; nothing is removed in this change."
+  },
+  {
+    "version": "0.278.0",
+    "type": "fix",
+    "title": "Fix urlPrefillFields allowlist missing relatedList toolbarActions",
+    "detail": "A screen reached only through a relatedList toolbar action never received its mapped id, so its hidden required field stayed empty and the declared redirect never ran."
+  },
+  {
+    "version": "0.278.0",
+    "type": "improvement",
+    "title": "TenantDb gains a count(table, where?) method for a tenant-scoped COUNT(*) (fw#2854).",
+    "detail": "`TenantDb.count(table, where?)` returns a tenant-scoped row count with the same tenant semantics as `selectMany`: \"tenant\" mode counts the caller's own tenant plus `SYSTEM_TENANT_ID` reference rows, a caller-supplied `where.tenantId` may only narrow that scope, and \"system\" mode counts unfiltered. Lets app/feature code compute stock-caps (`count(*) WHERE tenant_id = …`) without an `unsafeRaw`/`escapeHatch` detour. A hand-built `TenantDb` object literal (test fakes, mocks) must add a `count` method to keep satisfying the `TenantDb` type — `db.global()` is unaffected, `count` is only on the tenant-scoped surface.",
+    "migration": "No action required for existing `TenantDb` consumers — purely additive. Any hand-built object literal typed as `TenantDb` (not built via `createTenantDb`) needs a `count(table, where?)` method added; `bunCountWhere`/`countWhere` from `@cosmicdrift/kumiko-framework/db` implements the same query shape if you need equivalent logic outside a `TenantDb`."
+  },
   {
     "version": "0.277.0",
     "type": "improvement",

package/src/db/__tests__/tenant-db-count.integration.test.ts

@@ -0,0 +1,92 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { createEntity, createTextField } from "../../engine";
+import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import type { TableColumns } from "../dialect";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+const entity = createEntity({
+  table: "tenant_db_count_items",
+  fields: {
+    name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+});
+
+const table: TableColumns = buildEntityTable("tenantDbCountItem", entity);
+
+let testDb: TestDb;
+const tenantA = TestUsers.admin; // tenantId: 1
+const tenantB = TestUsers.otherTenant; // tenantId: 2
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, entity, "tenantDbCountItem");
+
+  const tdbA = createTenantDb(testDb.db, tenantA.tenantId);
+  const tdbB = createTenantDb(testDb.db, tenantB.tenantId);
+
+  await tdbA.insertOne(table, { name: "A1" });
+  await tdbA.insertOne(table, { name: "A2" });
+  await tdbA.insertOne(table, { name: "A3" });
+  await tdbB.insertOne(table, { name: "B1" });
+
+  await seedRow(testDb.db, table, {
+    name: "Reference",
+    tenantId: "00000000-0000-4000-8000-000000000000",
+    version: 1,
+    insertedAt: Temporal.Now.instant(),
+  });
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+describe("TenantDb.count() — tenant mode", () => {
+  test("B's count returns only B's own rows plus the reference row, never A's rows", async () => {
+    const tdbB = createTenantDb(testDb.db, tenantB.tenantId);
+    const count = await tdbB.count(table);
+    expect(count).toBe(2); // B1 + Reference
+  });
+
+  test("A's count returns only A's own rows plus the reference row", async () => {
+    const tdbA = createTenantDb(testDb.db, tenantA.tenantId);
+    const count = await tdbA.count(table);
+    expect(count).toBe(4); // A1, A2, A3 + Reference
+  });
+
+  test("where filter narrows the count", async () => {
+    const tdbA = createTenantDb(testDb.db, tenantA.tenantId);
+    const count = await tdbA.count(table, { name: "A1" });
+    expect(count).toBe(1);
+  });
+
+  test("B's where: { tenantId: tenantA } cannot widen scope — falls back to B's own scope", async () => {
+    const tdbB = createTenantDb(testDb.db, tenantB.tenantId);
+    const count = await tdbB.count(table, { tenantId: tenantA.tenantId });
+    // The requested tenantId isn't in B's allowed set [B, SYSTEM], so it falls
+    // back to B's full enforced scope rather than widening to A.
+    expect(count).toBe(2); // B1 + Reference
+  });
+
+  test("where: { tenantId: B } excludes the reference row", async () => {
+    const tdbB = createTenantDb(testDb.db, tenantB.tenantId);
+    const count = await tdbB.count(table, { tenantId: tenantB.tenantId });
+    expect(count).toBe(1); // B1 only
+  });
+
+  test("count matches selectMany(...).length for the same scope", async () => {
+    const tdbA = createTenantDb(testDb.db, tenantA.tenantId);
+    const [count, rows] = await Promise.all([tdbA.count(table), tdbA.selectMany(table)]);
+    expect(count).toBe(rows.length);
+  });
+});
+
+describe("TenantDb.count() — system mode", () => {
+  test("counts all rows across every tenant, unfiltered", async () => {
+    const systemDb = createTenantDb(testDb.db, tenantA.tenantId, "system");
+    const count = await systemDb.count(table);
+    expect(count).toBe(5); // A1, A2, A3, B1, Reference
+  });
+});

package/src/db/queries/raw-sql.ts

@@ -14,6 +14,7 @@ export async function executeRawQuery<T = Record<string, unknown>>(
 
 /** SELECT-only escape hatch with the #1163 closed-connection retry. Do not pass
  *  INSERT/UPDATE/DELETE — retry re-executes the statement. */
+// @wrapper-known semantic-alias
 export async function executeRawQueryRead<T = Record<string, unknown>>(
   db: AnyDb,
   sqlText: string,

package/src/db/tenant-db.ts

@@ -15,6 +15,7 @@ import {
 import {
   asEntityTableMeta,
   asRawClient,
+  countWhere as bunCountWhere,
   deleteMany as bunDeleteMany,
   fetchOne as bunFetchOne,
   insertOne as bunInsertOne,
@@ -453,6 +454,11 @@ export function createTenantDb(
       return withDbSpan("select", table, async () => bunFetchOne<T>(db, table, filter));
     },
 
+    count(table: Table | EntityTableMeta, where?: WhereObject): Promise<number> {
+      const filter = readWhere(table, where);
+      return withDbSpan("select", table, async () => bunCountWhere(db, table, filter));
+    },
+
     insertOne<T = Record<string, unknown>>(
       table: Table,
       values: Record<string, unknown>,

package/src/engine/__tests__/build-app-schema-url-prefill.test.ts

@@ -70,7 +70,31 @@ const leasesFeature = defineFeature("leases", (r) => {
     id: "lease-detail",
     type: "projectionDetail",
     query: "leases:query:lease:detail",
-    layout: { sections: [] },
+    layout: {
+      sections: [
+        {
+          kind: "relatedList",
+          title: "Items",
+          query: "leases:query:lease:items",
+          columns: ["name"],
+          toolbarActions: [
+            {
+              kind: "navigate",
+              id: "quick-note",
+              label: "Quick note",
+              screen: "item-toolbar-note",
+              params: { map: { leaseId: "id" } },
+            },
+            {
+              kind: "navigate",
+              id: "silent-add",
+              label: "Silent add",
+              screen: "item-toolbar-silent",
+            },
+          ],
+        },
+      ],
+    },
     metrics: [
       {
         field: "openItems",
@@ -85,6 +109,18 @@ const leasesFeature = defineFeature("leases", (r) => {
     entity: "item",
     layout: { sections: [{ title: "x", fields: ["leaseId", "note"] }] },
   });
+  r.screen({
+    id: "item-toolbar-note",
+    type: "entityEdit",
+    entity: "item",
+    layout: { sections: [{ title: "x", fields: ["leaseId", "note"] }] },
+  });
+  r.screen({
+    id: "item-toolbar-silent",
+    type: "entityEdit",
+    entity: "item",
+    layout: { sections: [{ title: "x", fields: ["leaseId", "note"] }] },
+  });
   r.screen({
     id: "record-payment",
     type: "actionForm",
@@ -150,4 +186,12 @@ describe("buildAppSchema — urlPrefillFields derived from navigate params", ()
   test("non-form screens carry no urlPrefillFields", () => {
     expect(urlPrefillFieldsOf("leases", "lease-list")).toBeUndefined();
   });
+
+  test("a relatedList toolbarAction's params.map target gets the mapped field", () => {
+    expect(urlPrefillFieldsOf("leases", "item-toolbar-note")).toEqual(["leaseId"]);
+  });
+
+  test("a relatedList toolbarAction without params contributes no fields — the allowlist stays an allowlist", () => {
+    expect(urlPrefillFieldsOf("leases", "item-toolbar-silent")).toEqual([]);
+  });
 });

package/src/engine/boot-validator/query-output-columns.ts

@@ -118,6 +118,7 @@ function checkProjectionDetailOutputFields(
 ): void {
   const recordShape = getZodObjectShape(queryHandlers.get(screen.query)?.outputSchema);
   const prefix = `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`;
+  // @wrapper-known semantic-alias
   const checkHeaderField = (part: "title" | "subtitle" | "status", field: string): void => {
     checkFieldExists(
       recordShape,

package/src/engine/boot-validator/url-prefill-fields.ts

@@ -52,6 +52,9 @@ function projectionDetailNavigateActions(
     ...screen.layout.sections.flatMap((section) =>
       section.kind === "relatedList" ? scopeActions(section.rowActions, undefined) : [],
     ),
+    ...screen.layout.sections.flatMap((section) =>
+      section.kind === "relatedList" ? scopeActions(section.toolbarActions, undefined) : [],
+    ),
     ...(screen.metrics ?? []).flatMap((metric) =>
       typeof metric === "string" || metric.navigate === undefined
         ? []

package/src/engine/extensions/__tests__/hook-ctx-db-tenant-scoped.test.ts

@@ -0,0 +1,76 @@
+// fw#2914 — TenantDataHookCtx.db / UserDataHookCtx.db are TenantDb, not a raw
+// DbRunner. A hook that hasn't declared `escapeHatch: { reason }` on its
+// `r.useExtension(...)` registration must not be able to reach raw SQL
+// through `ctx.db` at all — these are compile-time guarantees, not runtime
+// checks (the runtime denial is covered by escape-hatch-declaration
+// .integration.test.ts in bundled-features/user-data-rights).
+
+import { describe, expect, test } from "bun:test";
+import type { DbRunner } from "@cosmicdrift/kumiko-types/db-connection";
+import { createTenantDb } from "../../../db/tenant-db";
+import { testTenantId } from "../../../stack";
+import type { TenantDataHookCtx } from "../tenant-data";
+import type { UserDataHookCtx } from "../user-data";
+
+const tenantId = testTenantId(1);
+
+function fakeRunner(): DbRunner {
+  return {
+    unsafe: async () => [],
+    begin: async () => {
+      throw new Error("begin not used in this test");
+    },
+  } as unknown as DbRunner;
+}
+
+describe("TenantDataHookCtx.db / UserDataHookCtx.db are TenantDb, not DbRunner", () => {
+  test("compile-time: ctx.db has no raw .unsafe()/.begin() surface", () => {
+    const tenantCtx: TenantDataHookCtx = {
+      db: createTenantDb(fakeRunner(), tenantId),
+      registry: {} as TenantDataHookCtx["registry"],
+      tenantId,
+    };
+    const userCtx: UserDataHookCtx = {
+      db: createTenantDb(fakeRunner(), tenantId),
+      registry: {} as UserDataHookCtx["registry"],
+      tenantId,
+      userId: "user-1",
+    };
+
+    // @ts-expect-error TenantDb has no `.unsafe()` — only DbRunner does.
+    expect(tenantCtx.db.unsafe).toBeUndefined();
+    // @ts-expect-error TenantDb has no `.begin()` — only DbRunner does.
+    expect(tenantCtx.db.begin).toBeUndefined();
+    // @ts-expect-error TenantDb has no `.unsafe()` — only DbRunner does.
+    expect(userCtx.db.unsafe).toBeUndefined();
+    // @ts-expect-error TenantDb has no `.begin()` — only DbRunner does.
+    expect(userCtx.db.begin).toBeUndefined();
+  });
+
+  test("compile-time: ctx.db does not structurally satisfy DbRunner", () => {
+    const tenantCtx: TenantDataHookCtx = {
+      db: createTenantDb(fakeRunner(), tenantId),
+      registry: {} as TenantDataHookCtx["registry"],
+      tenantId,
+    };
+
+    // @ts-expect-error TenantDb is not assignable to DbRunner — a hook can't
+    // smuggle ctx.db into a helper typed to expect a raw connection.
+    const asRunner: DbRunner = tenantCtx.db;
+    expect(asRunner).toBeDefined();
+  });
+
+  test("declared escape hatch: ctx.db.unsafeRaw(reason) returns a real DbRunner", () => {
+    const runner = fakeRunner();
+    const tenantCtx: TenantDataHookCtx = {
+      db: createTenantDb(runner, tenantId, "tenant", undefined, undefined, undefined, {
+        unsafeRaw: { reason: "test: declared escape hatch" },
+      }),
+      registry: {} as TenantDataHookCtx["registry"],
+      tenantId,
+    };
+
+    const raw: DbRunner = tenantCtx.db.unsafeRaw("test: declared escape hatch");
+    expect(raw).toBe(runner);
+  });
+});

package/src/engine/extensions/escape-hatch-usage.ts

@@ -0,0 +1,16 @@
+// fw#2914 — reads the { escapeHatch: { reason } } convention off a
+// `r.useExtension(...)` registration's untyped options bag. Registration-time
+// validation (feature-ui-extensions.ts's useExtension) already rejects an
+// empty reason, but options stays `Record<string, unknown>`, so orchestrators
+// re-narrow at read time instead of trusting the shape.
+
+import type { RegistrarExtensionRegistration } from "../types/config";
+
+export function extensionUsageEscapeHatchReason(
+  usage: Pick<RegistrarExtensionRegistration, "options">,
+): string | undefined {
+  const escapeHatch = usage.options?.["escapeHatch"];
+  if (typeof escapeHatch !== "object" || escapeHatch === null) return undefined;
+  const reason = (escapeHatch as { reason?: unknown }).reason;
+  return typeof reason === "string" && reason.trim().length > 0 ? reason : undefined;
+}

package/src/engine/extensions/tenant-data.ts

@@ -3,11 +3,13 @@
 // Mirror of engine/extensions/user-data.ts at tenant granularity.
 // tenant-lifecycle orchestrates destroy via registry.getExtensionUsages(EXT_TENANT_DATA).
 
-import type { DbRunner } from "../../db/connection";
+import type { TenantDb } from "../../db/tenant-db";
 import type { Registry, TenantId } from "../types";
 
+// fw#2914 — db is tenant-filtered; unfiltered access needs
+// `escapeHatch: { reason }` on the owning `r.useExtension(...)` registration.
 export interface TenantDataHookCtx {
-  readonly db: DbRunner;
+  readonly db: TenantDb;
   readonly registry: Registry;
   readonly tenantId: TenantId;
 }

package/src/engine/extensions/user-data.ts

@@ -1,19 +1,16 @@
-// Hook-Signatur-Types für die EXT_USER_DATA-Extension (DSGVO Art. 15+17+20).
+// Hook signature types for the EXT_USER_DATA extension (GDPR Art. 15+17+20).
 //
-// Sprint 1.9 Z1: Bisher gibt der Boot-Validator JEDES Hook-Shape durch
-// — useExtension(EXT_USER_DATA, "X", { export: ... }) wird nicht gegen
-// eine erwartete Signatur geprüft. Diese Types sind die canonical
-// Schema-Sicht; Sprint 2 user-data-rights wird sie via
-// `r.extendsRegistrar(EXT_USER_DATA, { hooks: ... })`-Doku exposen.
+// The boot validator does not check useExtension(EXT_USER_DATA, "X", { export: ... })
+// hook shapes against an expected signature — these types are the canonical
+// schema view; app authors get compile-time hints only, no runtime validation.
 //
-// Boot-Time-Schape-Check (Runtime) ist orthogonal und kommt in Sprint
-// 2 wenn die exportRunner-/forgetRunner-Pipelines stehen — bis dahin
-// sind diese Types Compile-Time-Hints für App-Authors, keine Runtime-
-// Validation.
+// The runner pipelines that consume these hooks are built and live: see
+// packages/bundled-features/src/user-data-rights/run-user-export.ts,
+// run-forget-cleanup.ts, run-export-jobs.ts.
 //
-// Siehe docs/plans/datenschutz/user-data-rights.md.
+// See docs/plans/datenschutz/user-data-rights.md.
 
-import type { DbRunner } from "../../db/connection";
+import type { TenantDb } from "../../db/tenant-db";
 import type { Registry, TenantId } from "../types";
 
 // SessionUser.id ist plattformweit `string` (kein Brand-Type). Wenn
@@ -49,13 +46,10 @@ export type UserDataDeleteStrategy = "delete" | "anonymize";
 export type TenantUserModel = "single-user" | "multi-user";
 
 /**
- * Context-Snapshot der dem Hook übergeben wird. Sprint 2 erweitert
- * das ggf. um cancel-/timeout-Marker; aktuell minimaler Schnitt.
- *
- * `db` ist `DbRunner` (DbConnection | DbTx) damit der Cleanup-Runner
- * (S2.U5b) den Hook in einer Per-User-Sub-Tx callen kann. Hooks die
- * raw-DB-Operationen machen funktionieren auf beiden Shapes via
- * Drizzle's polymorphem select/insert/update/delete-Chain.
+ * fw#2914 — `db` is a tenant-filtered `TenantDb`, bound to `tenantId`
+ * (or the per-user sub-tx in the forget path). Unfiltered access needs
+ * `escapeHatch: { reason }` on the `r.useExtension(...)` registration,
+ * then `ctx.db.unsafeRaw(reason)`.
  */
 /**
  * Minimal storage surface a file-aware forget hook needs to erase binaries.
@@ -73,7 +67,7 @@ export interface UserDataStorageProvider {
 }
 
 export interface UserDataHookCtx {
-  readonly db: DbRunner;
+  readonly db: TenantDb;
   /**
    * The app registry. A forget hook that must erase CHILD read-model rows past
    * the entity's own row — m:n join projections, per-parent detail projections —

package/src/engine/feature-ast/patch.ts

@@ -537,6 +537,7 @@ function matchArgString(call: CallExpression, index: number, expected: string):
   return readNameLiteral(arg) === expected;
 }
 
+// @wrapper-known semantic-alias
 function matchFirstArgString(call: CallExpression, expected: string): boolean {
   return matchArgString(call, 0, expected);
 }

package/src/engine/feature-ui-extensions.ts

@@ -240,9 +240,27 @@ export function buildUiExtensionsMethods<TName extends string>(
               const { name, entity, ...rest } = extensionNameOrDefinition;
               return [name, entity, rest] as const;
             })();
+      const resolvedEntityName = resolveName(resolvedEntityRef);
+      // fw#2914 — cross-cutting escapeHatch convention for hook-context db
+      // access (mirrors r.hook's validation above). Not part of a typed
+      // per-extension options shape: useExtension's bag stays generic, but
+      // this one key is validated for every extension the same way.
+      const escapeHatch = resolvedOptions?.["escapeHatch"];
+      if (escapeHatch !== undefined) {
+        const reason =
+          typeof escapeHatch === "object" && escapeHatch !== null
+            ? (escapeHatch as { reason?: unknown }).reason
+            : undefined;
+        if (typeof reason !== "string" || reason.trim().length === 0) {
+          throw new Error(
+            `[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ` +
+              `must be { reason: "<non-empty string>" } explaining why this usage needs unfiltered db access.`,
+          );
+        }
+      }
       state.extensionUsages.push({
         extensionName,
-        entityName: resolveName(resolvedEntityRef),
+        entityName: resolvedEntityName,
         options: resolvedOptions,
       });
     },

package/src/engine/index.ts

@@ -112,6 +112,7 @@ export {
   FILE_PROVIDER_CONFIG_KEY,
   TENANT_MEMBERSHIPS_QUERY,
 } from "./extension-names";
+export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage";
 export type {
   StorageProviderDestroyTenantHook,
   StorageProviderExtensionHooks,

package/src/engine/registry-validate.ts

@@ -127,8 +127,9 @@ export function applyExtensionUsages(state: RegistryState): void {
     // to also be gated, store the registering-feature on
     // RegistrarExtensionRegistration and use that here.
     const extOwner = "*";
-    // Extensions have no declaration site for escapeHatch, so SYSTEM is always denied
-    // (system-identity-switch.ts) — bindHookEscapeHatchGrant(..., undefined) below.
+    // Unlike export/forget hooks (escapeHatch on r.useExtension(...)), these
+    // entity-lifecycle wrappers (postSave/preDelete/postDelete/preSave) have no
+    // escapeHatch declaration site, so SYSTEM stays denied here (system-identity-switch.ts).
     if (ext.hooks) {
       if (ext.hooks.postSave) {
         const wrapped = bindHookEscapeHatchGrant(

package/src/event-store/__tests__/provenance-append.integration.test.ts

@@ -0,0 +1,109 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient, transaction } from "../../db/query";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { InternalError } from "../../errors";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { generateId as uuid } from "../../utils";
+import { createEventsTable, loadAggregate, VersionConflictError } from "../index";
+import { appendProvenanceEvent, type ProvenanceEventInput } from "../provenance-append";
+
+let testDb: BunTestDb;
+let tdb: TenantDb;
+
+const tenantA = uuid();
+
+function provenanceEvent(overrides: Partial<ProvenanceEventInput>): ProvenanceEventInput {
+  return {
+    aggregateId: uuid(),
+    aggregateType: "ai-call",
+    tenantId: tenantA,
+    expectedVersion: 0,
+    type: "ai-foundation:ai-call-recorded",
+    payload: { promptVersion: "abc123" },
+    metadata: { userId: uuid() },
+    ...overrides,
+  };
+}
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  await createEventsTable(testDb.db);
+  tdb = createTenantDb(testDb.db, tenantA);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(`TRUNCATE kumiko_events RESTART IDENTITY`);
+});
+
+describe("appendProvenanceEvent", () => {
+  test("expectedVersion: 0 writes the event, readable via loadAggregate", async () => {
+    const event = provenanceEvent({ expectedVersion: 0 });
+
+    await appendProvenanceEvent(tdb, event);
+
+    const events = await loadAggregate(testDb.db, event.aggregateId, tenantA);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.type).toBe(event.type);
+    expect(events[0]?.payload).toEqual(event.payload);
+  });
+
+  test('expectedVersion: "current" appends twice to the same aggregate without a version conflict', async () => {
+    const aggregateId = uuid();
+
+    await appendProvenanceEvent(tdb, provenanceEvent({ aggregateId, expectedVersion: "current" }));
+    await appendProvenanceEvent(tdb, provenanceEvent({ aggregateId, expectedVersion: "current" }));
+
+    const events = await loadAggregate(testDb.db, aggregateId, tenantA);
+    expect(events).toHaveLength(2);
+    expect(events[0]?.type).toBe("ai-foundation:ai-call-recorded");
+    expect(events[1]?.type).toBe("ai-foundation:ai-call-recorded");
+  });
+
+  test("a failing append does not poison the surrounding transaction", async () => {
+    const aggregateId = uuid();
+    await appendProvenanceEvent(tdb, provenanceEvent({ aggregateId, expectedVersion: 0 }));
+
+    await transaction(testDb.db, async (tx) => {
+      const txTdb = createTenantDb(tx, tenantA);
+
+      await expect(
+        appendProvenanceEvent(txTdb, provenanceEvent({ aggregateId, expectedVersion: 0 })),
+      ).rejects.toThrow(VersionConflictError);
+
+      const stillUsable = await asRawClient(tx).unsafe<{ one: number }>("SELECT 1 AS one");
+      expect(stillUsable[0]?.one).toBe(1);
+    });
+  });
+
+  test("a TenantDb not built by createTenantDb fails closed", async () => {
+    const handBuilt = { tenantId: tenantA, mode: "tenant" } as unknown as TenantDb;
+
+    await expect(appendProvenanceEvent(handBuilt, provenanceEvent({}))).rejects.toThrow(
+      InternalError,
+    );
+  });
+
+  test("rejects a kumiko:system: type and writes nothing", async () => {
+    const event = provenanceEvent({ type: "kumiko:system:deferred-dispatch" });
+
+    await expect(appendProvenanceEvent(tdb, event)).rejects.toThrow(InternalError);
+
+    const events = await loadAggregate(testDb.db, event.aggregateId, tenantA);
+    expect(events).toHaveLength(0);
+  });
+
+  test("rejects an unqualified type without a ':' and writes nothing", async () => {
+    const event = provenanceEvent({ type: "ai-call-recorded" });
+
+    await expect(appendProvenanceEvent(tdb, event)).rejects.toThrow(InternalError);
+
+    const events = await loadAggregate(testDb.db, event.aggregateId, tenantA);
+    expect(events).toHaveLength(0);
+  });
+});

package/src/event-store/index.ts

@@ -31,6 +31,7 @@ export {
   streamAllEventsByType,
 } from "./event-store";
 export { createEventsTable, eventsTable } from "./events-schema";
+export { appendProvenanceEvent, type ProvenanceEventInput } from "./provenance-append";
 export {
   createRebuildDeadLetterTable,
   listRebuildDeadLetters,

package/src/event-store/provenance-append.ts

@@ -0,0 +1,59 @@
+import { runInSavepointIfSupported } from "../db/query";
+import { type TenantDb, unsafeRawForDeclaredStep, withUnsafeRawGrant } from "../db/tenant-db";
+import type { TenantId } from "../engine/types";
+import { InternalError } from "../errors";
+import { SYSTEM_EVENT_PREFIX } from "../pipeline/append-event-core";
+import { append, type EventMetadata, getStreamVersion } from "./event-store";
+
+// Fixed by the framework, not the caller — the point of this entry point is
+// that no caller can invent its own escapeHatch reason for bypassing
+// cross-feature event ownership (appendDomainEventCore).
+const PROVENANCE_APPEND_REASON =
+  "event-store: provenance events append outside the calling feature's ownership — declared once, framework-wide, for provenance streams only.";
+
+export type ProvenanceEventInput = {
+  readonly aggregateId: string;
+  readonly aggregateType: string;
+  readonly tenantId: TenantId;
+  readonly expectedVersion: number | "current";
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+  readonly metadata: EventMetadata;
+};
+
+// The only place provenance writers are allowed to reach a raw event-store append.
+export async function appendProvenanceEvent(
+  db: TenantDb,
+  event: ProvenanceEventInput,
+): Promise<void> {
+  if (event.type.startsWith(SYSTEM_EVENT_PREFIX)) {
+    throw new InternalError({
+      message: `appendProvenanceEvent("${event.type}") — the "${SYSTEM_EVENT_PREFIX}" namespace is framework-internal and is not reachable through this entry point.`,
+    });
+  }
+  if (!event.type.includes(":")) {
+    throw new InternalError({
+      message: `appendProvenanceEvent("${event.type}") — event types must be owner-qualified ("<feature>:<name>"). Unowned types are not allowed here.`,
+    });
+  }
+  const granted = withUnsafeRawGrant(db, { reason: PROVENANCE_APPEND_REASON });
+  const runner = unsafeRawForDeclaredStep(granted, PROVENANCE_APPEND_REASON);
+  // Bun.SQL/postgres.js abort the whole surrounding begin() on a statement
+  // error (25P02) even when the caller's catch swallows it — the savepoint
+  // confines that to this scope. Pool connections have no ambient tx to poison.
+  await runInSavepointIfSupported(runner, async (sp) => {
+    const expectedVersion =
+      event.expectedVersion === "current"
+        ? await getStreamVersion(sp, event.aggregateId, event.tenantId)
+        : event.expectedVersion;
+    await append(sp, {
+      aggregateId: event.aggregateId,
+      aggregateType: event.aggregateType,
+      tenantId: event.tenantId,
+      expectedVersion,
+      type: event.type,
+      payload: event.payload,
+      metadata: event.metadata,
+    });
+  });
+}

package/src/pipeline/append-event-core.ts

@@ -47,7 +47,7 @@ function eventOwnerFeature(qualifiedName: string): string | undefined {
 // on the literal type-string. Apps cannot write into "kumiko:system:*"
 // directly — only framework step implementations call unsafeAppendEvent
 // with these types.
-const SYSTEM_EVENT_PREFIX = "kumiko:system:";
+export const SYSTEM_EVENT_PREFIX = "kumiko:system:";
 
 export async function appendDomainEventCore(
   deps: AppendDomainEventCoreDeps,