@cosmicdrift/kumiko-framework 0.243.3 → 0.244.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.243.3",
+  "version": "0.244.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.243.3",
+    "@cosmicdrift/kumiko-types": "0.244.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.243.3",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.244.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/boot-validator.test.ts

@@ -23,6 +23,7 @@ import {
   from,
   registerEntityCrud,
 } from "../index";
+import type { RowFieldExtractor } from "../types/screen";
 
 function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
   validateBootRaw(withBootValidatorFixture(features));
@@ -3696,6 +3697,110 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- action/rowAction drawer-target reachability across the remaining
+  //     RowAction call sites (fw#2710): projectionDetail.actions,
+  //     entityEdit.actions, and a relatedList section's rowActions. The
+  //     entityList/projectionList rowAction and toolbarAction drawer cases
+  //     are covered above — this pins the drawer branch actually being
+  //     reached (not skipped/mis-nested) at the other three sites, and the
+  //     "action" actionLabel used by both non-list call sites. ---
+  describe("drawer-target reachability at the remaining RowAction call sites (fw#2710)", () => {
+    test('projectionDetail.actions drawer-target unknown → throw with actionLabel "action"', () => {
+      const feature = defineFeature("shop", (r) => {
+        r.screen({
+          id: "order-detail",
+          type: "projectionDetail",
+          query: "shop:query:order-detail",
+          layout: { sections: [{ fields: ["total"] }] },
+          actions: [
+            { kind: "drawer", id: "add-note", label: "actions.addNote", screen: "ghost-form" },
+          ],
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(
+        /action "add-note" drawer-target "ghost-form" does not resolve to a registered screen/,
+      );
+    });
+
+    test('entityEdit.actions drawer-target unknown → throw with actionLabel "action"', () => {
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+          actions: [
+            { kind: "drawer", id: "add-note", label: "actions.addNote", screen: "ghost-form" },
+          ],
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(
+        /action "add-note" drawer-target "ghost-form" does not resolve to a registered screen/,
+      );
+    });
+
+    test("entityEdit.actions drawer-target → registered actionForm → no throw", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.writeHandler(
+          "add-note",
+          z.object({ note: z.string() }),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+          actions: [
+            { kind: "drawer", id: "add-note", label: "actions.addNote", screen: "note-form" },
+          ],
+        });
+        r.screen({
+          id: "note-form",
+          type: "actionForm",
+          handler: "shop:write:add-note",
+          fields: { note: { type: "text" } } as never,
+          layout: { sections: [{ fields: ["note"] }] },
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+
+    test('projectionDetail relatedList section rowAction drawer-target unknown → throw with actionLabel "rowAction"', () => {
+      const feature = defineFeature("shop", (r) => {
+        r.screen({
+          id: "order-detail",
+          type: "projectionDetail",
+          query: "shop:query:order-detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "Positions",
+                query: "shop:query:order-positions",
+                columns: [{ field: "name" }],
+                rowActions: [
+                  {
+                    kind: "drawer",
+                    id: "add-note",
+                    label: "actions.addNote",
+                    screen: "ghost-form",
+                  },
+                ],
+              },
+            ],
+          },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(
+        /rowAction "add-note" drawer-target "ghost-form" does not resolve to a registered screen/,
+      );
+    });
+  });
+
   // --- Screen short-id collision across features ---
   describe("screen short-id collisions across features", () => {
     test("two features registering the same short screen-id → Throw", () => {
@@ -4112,6 +4217,149 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- entityList rowAction drawer (fw#2710) ---
+  describe("entityList rowAction drawer (fw#2710)", () => {
+    function makeFeature(opts: {
+      readonly targetId?: string;
+      readonly targetType?: "actionForm" | "entityList";
+    }) {
+      const targetId = opts.targetId ?? "restock-form";
+      return defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [
+            { kind: "drawer", id: "open-drawer", label: "actions.restock", screen: targetId },
+          ],
+        });
+        if (opts.targetType === "entityList") {
+          r.screen({
+            id: targetId,
+            type: "entityList",
+            entity: "product",
+            columns: ["name"],
+          });
+          return;
+        }
+        if (opts.targetType === "actionForm") {
+          r.writeHandler(
+            "restock",
+            z.object({ qty: z.number() }),
+            async () => ({ isSuccess: true as const, data: null }),
+            { access: { roles: ["Admin"] } },
+          );
+          r.screen({
+            id: targetId,
+            type: "actionForm",
+            handler: "shop:write:restock",
+            fields: { qty: { type: "number" } } as never,
+            layout: { sections: [{ fields: ["qty"] }] },
+          });
+        }
+      });
+    }
+
+    test("drawer-target → registered actionForm → no throw", () => {
+      expect(() => validateBoot([makeFeature({ targetType: "actionForm" })])).not.toThrow();
+    });
+
+    test("drawer-target → unknown → throw with a clear message", () => {
+      expect(() => validateBoot([makeFeature({ targetId: "ghost-form" })])).toThrow(
+        /rowAction "open-drawer" drawer-target "ghost-form" does not resolve to a registered screen/,
+      );
+    });
+
+    test("drawer-target → screen exists but is not an actionForm → throw with a clear message", () => {
+      expect(() =>
+        validateBoot([makeFeature({ targetId: "product-list-2", targetType: "entityList" })]),
+      ).toThrow(
+        /rowAction "open-drawer" drawer-target "product-list-2" is a "entityList" screen, not an actionForm/,
+      );
+    });
+  });
+
+  // --- projectionList rowAction drawer + params prefill (fw#2710) ---
+  // projectionList is the second list call site; its rowActions run through a
+  // different branch of validateScreens than entityList's. The params cases
+  // pin the prefill check: a key the target actionForm doesn't declare is
+  // dropped by the renderer, so it has to fail at boot instead.
+  describe("projectionList rowAction drawer (fw#2710)", () => {
+    function makeFeature(opts: {
+      readonly targetId?: string;
+      readonly params?: RowFieldExtractor;
+    }) {
+      const targetId = opts.targetId ?? "restock-form";
+      return defineFeature("shop", (r) => {
+        r.queryHandler("products", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "restock",
+          z.object({ qty: z.number() }),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "product-projection",
+          type: "projectionList",
+          query: "shop:query:products",
+          columns: ["name"],
+          rowActions: [
+            {
+              kind: "drawer",
+              id: "open-drawer",
+              label: "actions.restock",
+              screen: targetId,
+              ...(opts.params !== undefined && { params: opts.params }),
+            },
+          ],
+        });
+        r.screen({
+          id: "restock-form",
+          type: "actionForm",
+          handler: "shop:write:restock",
+          fields: { qty: { type: "number" } } as never,
+          layout: { sections: [{ fields: ["qty"] }] },
+        });
+      });
+    }
+
+    test("drawer-target → registered actionForm → no throw", () => {
+      expect(() => validateBoot([makeFeature({})])).not.toThrow();
+    });
+
+    test("drawer-target → unknown → throw with a clear message", () => {
+      expect(() => validateBoot([makeFeature({ targetId: "ghost-form" })])).toThrow(
+        /rowAction "open-drawer" drawer-target "ghost-form" does not resolve to a registered screen/,
+      );
+    });
+
+    test("params pick a field the target actionForm declares → no throw", () => {
+      expect(() => validateBoot([makeFeature({ params: { pick: ["qty"] } })])).not.toThrow();
+    });
+
+    test("params pick a field the target actionForm does not declare → throw", () => {
+      expect(() => validateBoot([makeFeature({ params: { pick: ["nope"] } })])).toThrow(
+        /rowAction "open-drawer" params prefills "nope", which drawer-target "restock-form" does not declare as a field/,
+      );
+    });
+
+    test("params map to a target key the actionForm does not declare → throw", () => {
+      expect(() =>
+        validateBoot([makeFeature({ params: { map: { nope: "productQty" } } })]),
+      ).toThrow(/params prefills "nope", which drawer-target "restock-form" does not declare/);
+    });
+
+    test("params map to a declared target key → no throw", () => {
+      expect(() =>
+        validateBoot([makeFeature({ params: { map: { qty: "productQty" } } })]),
+      ).not.toThrow();
+    });
+  });
+
   // --- defaultSort funktioniert für ALLE Field-Types die sortable
   //     unterstützen (Tier 2.6b Field-Erweiterung) ---
   // Vor Tier 2.6b war `sortable` nur auf TextFieldDef. Erweitert auf

package/src/engine/__tests__/entity-write-crosstenant.integration.test.ts

@@ -0,0 +1,158 @@
+// fw#2650 — crossTenant on write handlers. A SystemAdmin operator writes a
+// row that lives in a different tenant than their own session. That needs
+// two things: (1) an unfiltered db instead of the caller's tenant-scoped
+// one (so the row is even visible), and (2) the event-store stream AND the
+// entity's tenant-based write-ownership rule — both keyed off the ACTING
+// user, not the db — so the acting user's tenantId must be rewritten to the
+// target row's tenant before the write, not just handed an unfiltered db.
+//
+// Two stacks on the SAME Postgres database: one registers the update
+// handler without `crossTenant`, the other with it — a clean A/B on the one
+// flag, no handler-name collisions to work around.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { eventsTable } from "../../event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "../../stack";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  from,
+} from "../index";
+
+// "Admin" passes unconditionally (any tenant may create its own rows).
+// "SystemAdmin" is tenant-scoped — this is the entity-level rule the
+// crossTenant acting-user rewrite must satisfy for the operator write to
+// go through; without the rewrite the acting user's own tenant would never
+// match a foreign row's tenantId here.
+const thingEntity = createEntity({
+  table: "ctwrite_things",
+  fields: {
+    label: createTextField({ required: true }),
+  },
+  access: { write: { Admin: "all", SystemAdmin: from("user:tenantId", "tenantId") } },
+});
+const thingTable = buildEntityTable("thing", thingEntity);
+
+function buildFeature(crossTenant: boolean) {
+  return defineFeature("ctwrite", (r) => {
+    r.entity("thing", thingEntity);
+    r.writeHandler(
+      defineEntityCreateHandler("thing", thingEntity, {
+        access: { roles: ["Admin", "SystemAdmin"] },
+      }),
+    );
+    r.writeHandler(
+      defineEntityUpdateHandler("thing", thingEntity, {
+        access: { roles: ["SystemAdmin"] },
+        ...(crossTenant && { crossTenant: true }),
+      }),
+    );
+  });
+}
+
+const dbName = `kumiko_test_ctwrite_${crypto.randomUUID().replace(/-/g, "").slice(0, 8)}`;
+
+let tenantScopedStack: TestStack;
+let crossTenantStack: TestStack;
+
+beforeAll(async () => {
+  tenantScopedStack = await setupTestStack({ features: [buildFeature(false)], dbName });
+  await unsafeCreateEntityTable(tenantScopedStack.db, thingEntity, "thing");
+  // Second connection to the SAME database — persistentDb:true means its
+  // cleanup() only closes the pool; tenantScopedStack (created without that
+  // flag) owns the actual DROP DATABASE and must clean up last.
+  crossTenantStack = await setupTestStack({
+    features: [buildFeature(true)],
+    dbName,
+    persistentDb: true,
+  });
+});
+
+afterAll(async () => {
+  await crossTenantStack.cleanup();
+  await tenantScopedStack.cleanup();
+});
+
+async function updatedEventTenantId(aggregateId: string): Promise<string | undefined> {
+  const rows = await selectMany<{ type: string; tenantId: string }>(
+    tenantScopedStack.db,
+    eventsTable,
+    {
+      aggregateId,
+    },
+  );
+  const updatedRow = rows.find((r) => r.type.includes("updated"));
+  return updatedRow?.tenantId;
+}
+
+describe("entity write handlers: crossTenant option (fw#2650)", () => {
+  test("crossTenant handler: SystemAdmin updates a row owned by another tenant", async () => {
+    const created = await tenantScopedStack.http.writeOk<{ id: string }>(
+      "ctwrite:write:thing:create",
+      { label: "foreign" },
+      TestUsers.otherTenant,
+    );
+
+    const updated = await crossTenantStack.http.writeOk<{ id: string; data: { label: string } }>(
+      "ctwrite:write:thing:update",
+      { id: created.id, version: 1, changes: { label: "touched by operator" } },
+      TestUsers.systemAdmin,
+    );
+    expect(updated.data.label).toBe("touched by operator");
+
+    // Row stays on its original tenant — crossTenant reaches across the
+    // tenant boundary, it does not migrate the row.
+    const rows = await selectMany(tenantScopedStack.db, thingTable, { id: created.id });
+    expect(rows[0]?.["tenantId"]).toBe(testTenantId(2));
+
+    // The append must land on the row's own tenant stream, not the acting
+    // (operator) user's — otherwise the append targets an empty stream in
+    // the operator's tenant and the update would have failed above with a
+    // bogus version_conflict rather than reaching this point at all.
+    expect(await updatedEventTenantId(created.id)).toBe(testTenantId(2));
+  });
+
+  test("normal (non-crossTenant) handler cannot reach a row in another tenant", async () => {
+    const created = await tenantScopedStack.http.writeOk<{ id: string }>(
+      "ctwrite:write:thing:create",
+      { label: "foreign-untouched" },
+      TestUsers.otherTenant,
+    );
+
+    const err = await tenantScopedStack.http.writeErr(
+      "ctwrite:write:thing:update",
+      { id: created.id, version: 1, changes: { label: "nope" } },
+      TestUsers.systemAdmin,
+    );
+    expect(err.code).toBe("not_found");
+
+    const rows = await selectMany(tenantScopedStack.db, thingTable, { id: created.id });
+    expect(rows[0]?.["label"]).toBe("foreign-untouched");
+  });
+
+  test("crossTenant still gates on access — a role without SystemAdmin is denied", async () => {
+    const created = await tenantScopedStack.http.writeOk<{ id: string }>(
+      "ctwrite:write:thing:create",
+      { label: "foreign-denied" },
+      TestUsers.otherTenant,
+    );
+
+    const err = await crossTenantStack.http.writeErr(
+      "ctwrite:write:thing:update",
+      { id: created.id, version: 1, changes: { label: "nope" } },
+      TestUsers.admin,
+    );
+    expect(err.code).toBe("access_denied");
+  });
+});

package/src/engine/boot-validator/screens.ts

@@ -367,18 +367,25 @@ function validateScreenNavTarget(
 // validateScreens below), the drawer mounts the target inline using this
 // feature's schema, so a cross-feature reference could never actually
 // render. Two distinct failure messages: dangling reference vs. wrong
-// screen type (fw#2225).
-function validateToolbarDrawerAction(
+// screen type. Shared by ToolbarAction (fw#2225) and RowAction (fw#2710)
+// drawer variants — same target-resolution rule, only the label in the
+// error message ("toolbarAction" vs. "rowAction" vs. "action") differs.
+function validateDrawerTargetAction(
   featureName: string,
   screenId: string,
   screenKind: string,
-  action: Extract<ToolbarAction, { kind: "drawer" }>,
+  actionLabel: "toolbarAction" | "rowAction" | "action",
+  action: {
+    readonly id: string;
+    readonly screen: string;
+    readonly params?: RowFieldExtractor;
+  },
   screens: FeatureDefinition["screens"],
 ): void {
   const target = screens[action.screen];
   if (target === undefined) {
     throw new Error(
-      `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) toolbarAction "${action.id}" ` +
+      `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
         `drawer-target "${action.screen}" does not resolve to a registered screen in this feature. ` +
         `kind:"drawer" only resolves same-feature screens (unlike kind:"navigate", which can target ` +
         `screens in any feature) — the drawer mounts the target inline using this feature's schema. ` +
@@ -387,12 +394,28 @@ function validateToolbarDrawerAction(
   }
   if (target.type !== "actionForm") {
     throw new Error(
-      `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) toolbarAction "${action.id}" ` +
+      `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
         `drawer-target "${action.screen}" is a "${target.type}" screen, not an actionForm. ` +
         `kind:"drawer" mounts an actionForm inside a Drawer widget — point "screen" at an ` +
         `actionForm screen, or use kind:"navigate" for a full-page target.`,
     );
   }
+  // A prefill key the target form doesn't declare is dropped silently by the
+  // renderer (mergeSearchParamsIntoInitial iterates the target's fields), so
+  // the typo would only show up as an empty field at click time.
+  // skip: no params extractor — nothing to check against the target's fields.
+  if (action.params === undefined) return;
+  const prefilledFields =
+    "pick" in action.params ? action.params.pick : Object.keys(action.params.map);
+  for (const fieldName of prefilledFields) {
+    if (Object.hasOwn(target.fields, fieldName)) continue;
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +
+        `params prefills "${fieldName}", which drawer-target "${action.screen}" does not declare as a ` +
+        `field — the renderer would drop it and leave the form empty. Target fields: ` +
+        `${Object.keys(target.fields).sort().join(", ") || "(none)"}.`,
+    );
+  }
 }
 
 // fw#2228: a navigate rowAction (or projectionDetail header action, which
@@ -590,6 +613,15 @@ export function validateScreens(
               action,
               target,
             );
+          } else if (action.kind === "drawer") {
+            validateDrawerTargetAction(
+              feature.name,
+              screenId,
+              "projectionList",
+              "rowAction",
+              action,
+              feature.screens,
+            );
           }
         }
         validateAtMostOneRowClick(feature.name, screenId, "projectionList", screen.rowActions);
@@ -600,10 +632,11 @@ export function validateScreens(
       if (screen.toolbarActions !== undefined) {
         for (const action of screen.toolbarActions) {
           if (action.kind === "drawer") {
-            validateToolbarDrawerAction(
+            validateDrawerTargetAction(
               feature.name,
               screenId,
               "projectionList",
+              "toolbarAction",
               action,
               feature.screens,
             );
@@ -779,6 +812,15 @@ export function validateScreens(
                   action,
                   target,
                 );
+              } else if (action.kind === "drawer") {
+                validateDrawerTargetAction(
+                  feature.name,
+                  screenId,
+                  "projectionDetail",
+                  "rowAction",
+                  action,
+                  feature.screens,
+                );
               } else if (!allWriteHandlerQns.has(action.handler)) {
                 throw new Error(
                   `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section ` +
@@ -886,6 +928,15 @@ export function validateScreens(
               action,
               target,
             );
+          } else if (action.kind === "drawer") {
+            validateDrawerTargetAction(
+              feature.name,
+              screenId,
+              "projectionDetail",
+              "action",
+              action,
+              feature.screens,
+            );
           } else {
             if (!allWriteHandlerQns.has(action.handler)) {
               throw new Error(
@@ -1356,6 +1407,15 @@ export function validateScreens(
               action,
               target,
             );
+          } else if (action.kind === "drawer") {
+            validateDrawerTargetAction(
+              feature.name,
+              screenId,
+              "entityList",
+              "rowAction",
+              action,
+              feature.screens,
+            );
           } else {
             if (!allWriteHandlerQns.has(action.handler)) {
               throw new Error(
@@ -1391,10 +1451,11 @@ export function validateScreens(
               );
             }
           } else if (action.kind === "drawer") {
-            validateToolbarDrawerAction(
+            validateDrawerTargetAction(
               feature.name,
               screenId,
               "entityList",
+              "toolbarAction",
               action,
               feature.screens,
             );
@@ -1507,6 +1568,15 @@ export function validateScreens(
               action,
               target,
             );
+          } else if (action.kind === "drawer") {
+            validateDrawerTargetAction(
+              feature.name,
+              screenId,
+              "entityEdit",
+              "action",
+              action,
+              feature.screens,
+            );
           } else {
             if (!allWriteHandlerQns.has(action.handler)) {
               throw new Error(

package/src/engine/entity-handlers.ts

@@ -17,6 +17,7 @@ import type {
   EntityDefinition,
   HandlerContext,
   QueryHandlerDef,
+  SessionUser,
   WriteHandlerDef,
 } from "./types";
 import type {
@@ -190,12 +191,38 @@ export function defineEntityWriteHandler(
   // acknowledges cross-tenant access on the feature's behalf. This is
   // behavior-preserving: ctx.db was already an unfiltered "system"-mode
   // TenantDb for these handlers before the ctx.db cutover.
-  const dbFor = (ctx: HandlerContext): TenantDb =>
-    ctx.systemDb
-      ? ctx.systemDb.acknowledgeCrossTenant(
-          `entity convention handler for r.systemScope() feature (${name})`,
-        )
-      : ctx.db;
+  //
+  // options.crossTenant mirrors the query-handler branch below: this ONE
+  // write handler reads/writes across every tenant without making the
+  // whole feature r.systemScope().
+  const crossTenant = options?.crossTenant === true;
+
+  const dbFor = (ctx: HandlerContext): TenantDb => {
+    if (ctx.systemDb) {
+      return ctx.systemDb.acknowledgeCrossTenant(
+        `entity convention handler for r.systemScope() feature (${name})`,
+      );
+    }
+    return crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+  };
+
+  // The event stream is keyed by the acting user's tenantId (streamTenantFor in
+  // event-store-executor-context.ts), not by the db handed to the executor — an
+  // unfiltered "system"-mode db alone reads the foreign row but appends to an
+  // empty stream in the operator's own tenant, surfacing as a bogus
+  // version_conflict. Rewriting the acting tenant also keeps PII envelope keys
+  // derived from the row's tenant rather than the operator's.
+  const actingUserFor = async (
+    user: SessionUser,
+    id: unknown,
+    db: TenantDb,
+  ): Promise<SessionUser> => {
+    if (!crossTenant || entity.systemStream) return user;
+    const row = await db.fetchOne<Record<string, unknown>>(table, { id });
+    const rowTenantId = row?.["tenantId"];
+    if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId) return user;
+    return { ...user, tenantId: rowTenantId };
+  };
 
   let schema: ZodType;
   let handler: WriteHandlerDef["handler"];
@@ -220,29 +247,40 @@ export function defineEntityWriteHandler(
       });
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
+        const db = dbFor(ctx);
+        const payload = event.payload as UpdatePayload; // @cast-boundary engine-payload
+        const user = await actingUserFor(event.user, payload.id, db);
         // skipUnchanged (#464): API-driven updates diff against the stored
         // row so a resubmitted-but-identical field doesn't force a fresh
         // pii/encrypted ciphertext. Direct executor.update() callers (e.g.
         // KEK-rotation, the user-data-rights #494 backfill) don't go through
         // this handler and keep today's always-re-encrypt behavior, which
         // they rely on to intentionally force a fresh event/ciphertext.
-        return executor.update(event.payload as UpdatePayload, event.user, dbFor(ctx), {
+        return executor.update(payload, user, db, {
           skipUnchanged: true,
           preSave:
             runPreSave &&
             ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
-        }); // @cast-boundary engine-payload
+        });
       };
       break;
     case "delete":
       schema = idSchema;
-      handler = async (event, ctx) =>
-        executor.delete(event.payload as IdPayload, event.user, dbFor(ctx)); // @cast-boundary engine-payload
+      handler = async (event, ctx) => {
+        const db = dbFor(ctx);
+        const payload = event.payload as IdPayload; // @cast-boundary engine-payload
+        const user = await actingUserFor(event.user, payload.id, db);
+        return executor.delete(payload, user, db);
+      };
       break;
     case "restore":
       schema = idSchema;
-      handler = async (event, ctx) =>
-        executor.restore(event.payload as IdPayload, event.user, dbFor(ctx)); // @cast-boundary engine-payload
+      handler = async (event, ctx) => {
+        const db = dbFor(ctx);
+        const payload = event.payload as IdPayload; // @cast-boundary engine-payload
+        const user = await actingUserFor(event.user, payload.id, db);
+        return executor.restore(payload, user, db);
+      };
       break;
     default:
       assertUnreachable(verb, "write verb");

package/src/errors/__tests__/reason-i18n.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AgentReasons, FrameworkReasons } from "../reasons";
+
+type ReasonEntry = { readonly endUser?: string; readonly developer?: string };
+
+const LOCALES = ["en", "de"] as const;
+const ALL_REASONS: readonly string[] = [
+  ...Object.values(FrameworkReasons),
+  ...Object.values(AgentReasons),
+];
+
+function loadLocale(locale: (typeof LOCALES)[number]): Readonly<Record<string, ReasonEntry>> {
+  const path = join(import.meta.dirname, "..", "i18n", `${locale}.yaml`);
+  // Parse boundary: the YAML shape is the file's documented schema.
+  return Bun.YAML.parse(readFileSync(path, "utf-8")) as Readonly<Record<string, ReasonEntry>>;
+}
+
+describe("reason i18n", () => {
+  for (const locale of LOCALES) {
+    test(`${locale}.yaml renders a docs page for every declared reason`, () => {
+      const entries = loadLocale(locale);
+      for (const reason of ALL_REASONS) {
+        const entry = entries[reason];
+        // The docgen skips a reason whose entry is missing or has neither
+        // text — the page then stays absent from docs.kumiko.rocks.
+        expect(entry, `${locale}.yaml has no entry for ${reason}`).toBeDefined();
+        expect(entry?.endUser?.trim() ?? "").not.toBe("");
+        expect(entry?.developer?.trim() ?? "").not.toBe("");
+      }
+    });
+  }
+
+  test("agent reasons are flat keys with the dot, not a nested agent map", () => {
+    for (const locale of LOCALES) {
+      const keys = Object.keys(loadLocale(locale));
+      expect(keys).toContain("agent.tool_not_allowed");
+      expect(keys).not.toContain("agent");
+    }
+  });
+
+  test("de and en cover the same reason keys", () => {
+    expect(Object.keys(loadLocale("de")).sort()).toEqual(Object.keys(loadLocale("en")).sort());
+  });
+});

package/src/errors/i18n/de.yaml

@@ -1,7 +1,9 @@
-# i18n-Texte für FrameworkReasons (deutsch).
+# i18n-Texte für die Reason-Kataloge aus reasons.ts (deutsch).
 #
-# Schema pro Reason-Key (snake_case, identisch mit Wert in reasons.ts
-# FrameworkReasons):
+# Schema pro Reason-Key — der Key ist wörtlich der Reason-Wert, Punkte
+# inklusive: FrameworkReasons bleibt präfixfrei (`stale_state`), AgentReasons
+# behält seinen Namespace innerhalb eines flachen Keys
+# (`agent.tool_not_allowed`), nie als verschachtelte `agent:`-Map:
 #
 #   <reason_key>:
 #     endUser: |
@@ -81,3 +83,59 @@ feature_disabled:
     `details.feature` und `details.handler` zeigen welches Feature/Handler.
     Aktiviere das Feature via Feature-Toggle oder Routing-Config (siehe
     [Feature-Toggles](/en/feature-reference/feature-toggles/)).
+
+agent.tool_not_allowed:
+  endUser: |
+    Dieses Tool ist im aktuellen Modus nicht verfügbar.
+    Stell den Assistenten auf einen Modus um, der diese Aktion abdeckt, oder
+    führe sie selbst in der App aus.
+  developer: |
+    `AccessDeniedError` aus dem Tool-Dispatch des Agenten: das Modell hat einen
+    Tool-Namen außerhalb des für diesen Lauf gebauten Katalogs angefragt — ein
+    halluzinierter Name, oder ein Handler, den der aktuelle Agent-Modus nicht
+    freigibt.
+
+    Der Katalog wird aus der gemounteten Registry abgeleitet
+    (`buildToolCatalog`) — ein Handler ohne `description` wird also gar nicht
+    erst zum Tool. Handler beschreiben oder den Agent-Modus weiten, wenn der
+    Call funktionieren sollte.
+
+agent.iteration_limit:
+  endUser: |
+    Der Assistent hat die maximale Anzahl an Schritten erreicht, ohne eine
+    eindeutige Antwort zu finden.
+    Bitte formuliere die Anfrage um oder teile sie in kleinere Schritte.
+  developer: |
+    `UnprocessableError` aus der Agent-Loop: der Lauf hat sein Runden-Limit
+    erreicht, bevor das Modell eine Endantwort produziert hat — meist ein Tool,
+    das immer wieder denselben Fehler liefert, oder eine Aufgabe, die mehr
+    Schritte braucht als das Limit erlaubt.
+
+    Runden-Limit für den Lauf anheben oder die Aufgabe verkleinern. Die
+    Turn-Historie der Unterhaltung zeigt, welcher Tool-Call sich wiederholt hat.
+
+agent.permission_denied:
+  endUser: |
+    Dir fehlt die Berechtigung für diese Aktion.
+    Der Assistent darf nur das, was dein eigener Account darf.
+  developer: |
+    `AccessDeniedError` aus dem Tool-Dispatch des Agenten: das Tool steht im
+    Katalog, aber die Rollen des Aufrufers decken den dahinterliegenden Handler
+    nicht ab. Der Agent läuft strikt mit den Rechten des aufrufenden Users — er
+    eskaliert nie.
+
+    Rolle am Handler ergänzen, oder hinnehmen, dass dieses Tool für diesen User
+    nicht verfügbar ist.
+
+agent.high_risk_no_always:
+  endUser: |
+    Für risikoreiche Aktionen kann „immer erlauben“ nicht gesetzt werden.
+    Jeder Lauf dieser Aktion braucht deine ausdrückliche Bestätigung.
+  developer: |
+    `AccessDeniedError` aus dem Risiko-Gate des Agenten: ein Handler mit
+    `agent: { risk: "high" }` wurde ohne die ausdrückliche Einzel-Bestätigung
+    aufgerufen, die solche Handler verlangen, oder es sollte eine
+    „immer erlauben“-Regel dafür gesetzt werden.
+
+    Deklariertes Risiko senken, wenn die Aktion wirklich Routine ist —
+    ansonsten ist der Bestätigungsdialog genau das gewollte Verhalten.

package/src/errors/i18n/en.yaml

@@ -1,7 +1,9 @@
-# i18n texts for FrameworkReasons (english).
+# i18n texts for the reason catalogs in reasons.ts (english).
 #
-# Schema per reason key (snake_case, matches the value in
-# reasons.ts FrameworkReasons):
+# Schema per reason key — the key is the reason value verbatim, dots
+# included: FrameworkReasons stays prefix-free (`stale_state`), AgentReasons
+# keeps its namespace inside a flat key (`agent.tool_not_allowed`), never a
+# nested `agent:` map:
 #
 #   <reason_key>:
 #     endUser: |
@@ -78,3 +80,56 @@ feature_disabled:
     `details.feature` and `details.handler` indicate which feature and
     handler. Enable the feature via feature toggle or routing config (see
     [Feature Toggles](/en/feature-reference/feature-toggles/)).
+
+agent.tool_not_allowed:
+  endUser: |
+    This tool is not available in the current mode.
+    Switch the assistant to a mode that covers this action, or do it yourself
+    in the app.
+  developer: |
+    `AccessDeniedError` from the agent's tool dispatch: the model asked for a
+    tool name outside the catalog built for this run — a hallucinated name, or
+    a handler the current agent mode doesn't expose.
+
+    The catalog is derived from the mounted registry (`buildToolCatalog`), so a
+    handler without a `description` never becomes a tool at all. Describe the
+    handler, or widen the agent mode, if the call was meant to work.
+
+agent.iteration_limit:
+  endUser: |
+    The assistant reached the maximum number of steps without a clear answer.
+    Please rephrase the request or split it into smaller steps.
+  developer: |
+    `UnprocessableError` from the agent loop: the run hit its maximum round
+    count before the model produced a final answer — usually a tool that keeps
+    returning the same error, or a task that needs more steps than the limit
+    allows.
+
+    Raise the round limit for the run, or narrow the task. The conversation's
+    turn history shows which tool call kept repeating.
+
+agent.permission_denied:
+  endUser: |
+    You don't have permission for this action.
+    The assistant can only do what your own account is allowed to do.
+  developer: |
+    `AccessDeniedError` from the agent's tool dispatch: the tool exists in the
+    catalog, but the caller's roles don't cover the handler behind it. The
+    agent runs strictly with the calling user's permissions — it never
+    escalates.
+
+    Grant the role on the handler, or accept that this tool stays unavailable
+    for that user.
+
+agent.high_risk_no_always:
+  endUser: |
+    High-risk actions can't be set to "always allow".
+    Every run of this action needs your explicit confirmation.
+  developer: |
+    `AccessDeniedError` from the agent's risk gate: a handler declared
+    `agent: { risk: "high" }` was invoked without the explicit per-call
+    confirmation such handlers require, or an "always allow" rule was requested
+    for one.
+
+    Lower the declared risk if the action really is routine; otherwise the
+    confirmation prompt is the intended behaviour.

package/src/ui-types/index.ts

@@ -89,6 +89,7 @@ export type {
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
   RowAction,
+  RowActionDrawer,
   RowActionNavigate,
   RowActionWriteHandler,
   RowFieldExtractor,