@cosmicdrift/kumiko-framework 0.167.0 → 0.168.0

package/package.json

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

package/src/__tests__/full-stack.integration.test.ts

@@ -493,6 +493,22 @@ describe("full stack: auth + access + validation", () => {
     );
     expectErrorIncludes(error, "banned_domain");
   });
+
+  test("queryOk throws on a query error response instead of returning undefined", async () => {
+    await expect(
+      stack.http.queryOk("users:query:user:detail", { id: "not-a-uuid" }, adminUser),
+    ).rejects.toThrow(/validation_error/);
+  });
+
+  test("queryErr asserts + returns the structured error for a failing query", async () => {
+    const error = await stack.http.queryErr(
+      "users:query:user:detail",
+      { id: "not-a-uuid" },
+      adminUser,
+    );
+    expect(error.code).toBe("validation_error");
+    expect(error.httpStatus).toBe(400);
+  });
 });
 
 // =============================================================================

package/src/api/__tests__/jwt.test.ts

@@ -82,6 +82,18 @@ describe("createJwtHelper.verify — payload validation (KF-2)", () => {
       .sign(new TextEncoder().encode(SECRET));
     await expect(jwt.verify(token)).rejects.toThrow(/sub/);
   });
+
+  // fw#1636 — SessionUser.timezone must survive the sign/verify roundtrip
+  // (jwt.sign silently drops any field it doesn't explicitly copy).
+  it("round-trips the timezone claim when set", async () => {
+    const payload = await jwt.verify(await jwt.sign({ ...user, timezone: "Asia/Tokyo" }));
+    expect(payload.timezone).toBe("Asia/Tokyo");
+  });
+
+  it("omits the timezone claim when unset", async () => {
+    const payload = await jwt.verify(await jwt.sign(user));
+    expect(payload.timezone).toBeUndefined();
+  });
 });
 
 describe("createJwtHelper — keyring form", () => {

package/src/api/auth-middleware.ts

@@ -307,6 +307,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
       id: payload.sub,
       tenantId: payload.tenantId,
       roles: payload.roles,
+      ...(payload.timezone ? { timezone: payload.timezone } : {}),
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),
     };

package/src/api/jwt.ts

@@ -10,6 +10,9 @@ export type JwtPayload = {
   sub: string;
   tenantId: TenantId;
   roles: string[];
+  // IANA zone from user.timezone, set at login — see SessionUser.timezone
+  // (fw#1636). Absent → ctx.tz.user falls back to ctx.tz.tenant.
+  timezone?: string;
   // Optional — present when a feature has registered auth claims via the
   // `r.authClaims()` hook system. Absent for stateless-JWT deployments
   // without auth-claims wiring.
@@ -106,6 +109,7 @@ export function createJwtHelper(
         tenantId: user.tenantId,
         roles: [...user.roles],
       };
+      if (user.timezone) body.timezone = user.timezone;
       if (user.claims) body.claims = { ...user.claims };
 
       const header: jose.JWTHeaderParameters = keyring.signKid
@@ -155,6 +159,9 @@ export function createJwtHelper(
         tenantId,
         roles,
       };
+      if (typeof payload["timezone"] === "string") {
+        result.timezone = payload["timezone"];
+      }
       const claims = payload["claims"];
       if (claims && typeof claims === "object") {
         result.claims = claims as DbRow;

package/src/changes.json

@@ -0,0 +1,40 @@
+[
+  {
+    "version": "0.167.0",
+    "type": "breaking",
+    "title": "resetEntityFieldEncryptionCacheForTests / resetEventPiiCatalogForTests moved to /testing (fw#1631).",
+    "detail": "Test-only reset helpers with no owning feature: resetEntityFieldEncryptionCacheForTests left the /db barrel, resetEventPiiCatalogForTests left /crypto. The functions did not move, only their export path.",
+    "migration": "Import both from \"@cosmicdrift/kumiko-framework/testing\" instead of \"/db\" and \"/crypto\". Relative deep-imports of the defining module are unaffected."
+  },
+  {
+    "version": "0.167.0",
+    "type": "breaking",
+    "title": "Six identity-sensitive error classes moved from kumiko-types into kumiko-framework (fw#1616).",
+    "detail": "VersionConflictError, IdempotentAppendConflictError and ArchivedStreamError now live in /event-store, KeyErasedError, KeyNotFoundError and KeyAlreadyExistsError in /crypto — the public paths callers already import from. With no classes left in it, kumiko-types is a plain dependency again instead of a peerDependency, which closes the changesets cycle that escalated every minor release to a major.",
+    "migration": "Only affects direct imports from the removed @cosmicdrift/kumiko-types/event-store-errors subpath: import from @cosmicdrift/kumiko-framework/event-store or /crypto instead. Apps importing from the framework paths need no change."
+  },
+  {
+    "version": "0.167.0",
+    "type": "fix",
+    "title": "hono range raised to ^4.12.27 — security floor for the HTTP layer (fw#1634).",
+    "detail": "Carries the fixes for three advisories: cross-request data disclosure in hono/jsx (context not isolated per request), server-side XSS via a JSX escaping bypass in cx(), and a dropped repeated request header in the API-Gateway v1 adapter. The old ^4.12.18 allowed the patched versions, but the lockfile sat on 4.12.25 — the range now states the floor instead of relying on resolution luck."
+  },
+  {
+    "version": "0.165.2",
+    "type": "improvement",
+    "title": "buildEntityTableMeta renamed to deriveEntityTableMeta (fw#1208).",
+    "detail": "The old name read like the unmanaged escape hatch (defineUnmanagedTable). Unmanaged builders now reject the reserved read_ table-name prefix. The deprecated alias still works."
+  },
+  {
+    "version": "0.165.1",
+    "type": "fix",
+    "title": "isSafeHref decodes HTML character references before its scheme check (fw#1551).",
+    "detail": "javascript:alert(1) and java	script:alert(1) slipped through because neither contains a literal colon for the pre-decode regex, while the browser decodes the entity back into an executable javascript: URL on click. Affects renderSafeMarkdown (page-render) and the renderer-web Link primitive."
+  },
+  {
+    "version": "0.165.1",
+    "type": "improvement",
+    "title": "createNumberField accepts max (fw#1573).",
+    "detail": "Mirrored from min; the schema-builder applies Zod .max() at the write boundary so integer CRUD rejects values that would overflow a Postgres integer instead of failing at insert time."
+  }
+]

package/src/db/__tests__/eagerload.integration.test.ts

@@ -3,16 +3,28 @@
 // werden (TenantDb filtert), sonst leakt eagerload fremde Rows nach _refs.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { seedRows } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  configurePiiSubjectKms,
+  encryptPiiFieldValues,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+} from "../../crypto";
 import { createEntity, createTextField } from "../../engine";
 import type { EntityDefinition } from "../../engine/types";
 import { setupTestStack, type TestStack, testTenantId, unsafeCreateEntityTable } from "../../stack";
+import { createTestEnvelopeCipher, resetPiiSubjectKmsForTests, seedRows } from "../../testing";
 import {
   collectReferenceFields,
   type EagerloadedRow,
   enrichRowWithReferences,
   enrichWithReferences,
 } from "../eagerload";
+import {
+  collectEncryptedFieldNames,
+  configureEntityFieldEncryption,
+  encryptEntityFieldValues,
+  resetEntityFieldEncryptionCacheForTests,
+} from "../entity-field-encryption";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -30,8 +42,31 @@ const postEntity = createEntity({
 });
 const authorTable = buildEntityTable("author", authorEntity);
 
-const resolve = (name: string): EntityDefinition | undefined =>
-  name === "author" ? authorEntity : undefined;
+// #1667: eager-loaded _refs bypassed PII/entity-field decryption entirely —
+// a raw selectMany read the referenced row straight from the table, so
+// piiCiphertextResponseGuard 500'd on the leaked ciphertext.
+const contactEntity = createEntity({
+  table: "el_contacts",
+  fields: {
+    name: createTextField({ required: true }),
+    email: createTextField({ required: true, tenantOwned: true }),
+    iban: createTextField({ required: true, encrypted: true }),
+  },
+});
+const leadEntity = createEntity({
+  table: "el_leads",
+  fields: {
+    title: createTextField({ required: true }),
+    contact: { type: "reference", entity: "contact" },
+  },
+});
+const contactTable = buildEntityTable("contact", contactEntity);
+
+const resolve = (name: string): EntityDefinition | undefined => {
+  if (name === "author") return authorEntity;
+  if (name === "contact") return contactEntity;
+  return undefined;
+};
 
 const tenantA = testTenantId(91);
 const tenantB = testTenantId(92);
@@ -47,12 +82,18 @@ const single = (r: EagerloadedRow | undefined, f: string) =>
 const many = (r: EagerloadedRow | undefined, f: string) =>
   r?._refs?.[f] as ReadonlyArray<Record<string, unknown>> | undefined;
 
+const CX = "44444444-4444-4444-8444-444444444444";
+const TEST_KEY = Buffer.from("a]bJm#kP9xQ2@wN!vL$hR5yT8eU0iO3f").toString("base64");
+const cipher = createTestEnvelopeCipher(TEST_KEY);
+const kms = new InMemoryKmsAdapter();
+
 let stack: TestStack;
 let dbA: ReturnType<typeof createTenantDb>;
 
 beforeAll(async () => {
   stack = await setupTestStack({ features: [] });
   await unsafeCreateEntityTable(stack.db, authorEntity);
+  await unsafeCreateEntityTable(stack.db, contactEntity);
   dbA = createTenantDb(stack.db, tenantA, "tenant");
 
   await seedRows(stack.db, authorTable, [
@@ -60,9 +101,30 @@ beforeAll(async () => {
     { id: A2, tenantId: tenantA, name: "Linus" },
     { id: BX, tenantId: tenantB, name: "Foreign" },
   ]);
+
+  configureEntityFieldEncryption(cipher);
+  configurePiiSubjectKms(kms);
+  const plainContact = {
+    id: CX,
+    tenantId: tenantA,
+    name: "Grace",
+    email: "grace@acme.test",
+    iban: "DE12345",
+  };
+  const piiEncrypted = await encryptPiiFieldValues(plainContact, contactEntity, ["email"], kms, {
+    requestId: "test",
+  });
+  const encrypted = await encryptEntityFieldValues(
+    piiEncrypted,
+    collectEncryptedFieldNames(contactEntity),
+    cipher,
+  );
+  await seedRows(stack.db, contactTable, [encrypted]);
 });
 
 afterAll(async () => {
+  resetEntityFieldEncryptionCacheForTests();
+  resetPiiSubjectKmsForTests();
   await stack.cleanup();
 });
 
@@ -161,4 +223,18 @@ describe("enrichWithReferences", () => {
     )) as EagerloadedRow;
     expect(single(row, "author")?.["name"]).toBe("Ada");
   });
+
+  test("#1667: referenzierte PII-/encrypted-Felder werden entschlüsselt, keine Ciphertext-Leaks", async () => {
+    const [row] = (await enrichWithReferences(
+      [{ id: "l1", contact: CX }],
+      leadEntity,
+      resolve,
+      dbA,
+    )) as EagerloadedRow[];
+    const contact = single(row, "contact");
+
+    expect(contact?.["email"]).toBe("grace@acme.test");
+    expect(contact?.["iban"]).toBe("DE12345");
+    expect(isPiiCiphertext(contact?.["email"])).toBe(false);
+  });
 });

package/src/db/eagerload.ts

@@ -23,8 +23,15 @@
 // keine framework-engine-Internals und kann auch von custom
 // query-handlern manuell aufgerufen werden.
 
+import { requestContext } from "../api/request-context";
+import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues } from "../crypto";
 import { selectMany } from "../db/query";
 import type { EntityDefinition, FieldDefinition, ReferenceFieldDef } from "../engine/types";
+import {
+  collectEncryptedFieldNames,
+  decryptEntityFieldValues,
+  resolveEntityFieldEncryption,
+} from "./entity-field-encryption";
 import { buildEntityTable } from "./table-builder";
 import type { TenantDb } from "./tenant-db";
 
@@ -81,6 +88,32 @@ export function collectReferenceFields(entity: EntityDefinition): readonly Refer
   return out;
 }
 
+// Referenced rows are read via a raw selectMany, not the referenced entity's
+// own executor context (enrichWithReferences only gets an
+// EagerLoadEntityResolver — routing through buildExecutorContext per ref
+// would need table/searchAdapter/entityCache wiring for no reason). Mirrors
+// event-store-executor-context's decryptForRead ordering: PII is the outer
+// layer, peel it before the envelope-encrypted fields, or the envelope
+// cipher chokes on a still-PII-wrapped string.
+async function decryptReferencedRow(
+  row: Record<string, unknown>,
+  refEntity: EntityDefinition,
+): Promise<Record<string, unknown>> {
+  let out = row;
+  const piiFields = collectPiiSubjectFields(refEntity);
+  const kms = configuredPiiSubjectKms();
+  if (piiFields.length > 0 && kms) {
+    out = await decryptPiiFieldValues(out, piiFields, kms, {
+      requestId: requestContext.get()?.requestId ?? "eagerload",
+    });
+  }
+  const encryptedFields = collectEncryptedFieldNames(refEntity);
+  if (encryptedFields.size > 0) {
+    out = await decryptEntityFieldValues(out, encryptedFields, resolveEntityFieldEncryption());
+  }
+  return out;
+}
+
 /** Eagerload für eine Liste von Rows. Mutiert nicht — gibt eine
  *  flache Kopie der Rows mit hinzugefügtem `_refs`-Property zurück. */
 export async function enrichWithReferences(
@@ -123,9 +156,10 @@ export async function enrichWithReferences(
       }
       const refTable = buildEntityTable(rf.refEntityName, refEntity);
       const idArray = [...ids];
-      const refRows = (await selectMany(db, refTable, { id: idArray })) as Array<
+      const rawRefRows = (await selectMany(db, refTable, { id: idArray })) as Array<
         Record<string, unknown>
       >;
+      const refRows = await Promise.all(rawRefRows.map((r) => decryptReferencedRow(r, refEntity)));
       const map = new Map<string, Record<string, unknown>>();
       for (const r of refRows) {
         const id = r["id"];

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

@@ -558,6 +558,7 @@ describe("validateBoot — retention", () => {
         createEntity({
           fields: {
             invoiceNumber: createTextField({ allowPlaintext: "is-business-data" }),
+            customerName: createTextField({ pii: true }),
           },
           retention: { keepFor: "10y", strategy: "blockDelete" },
         }),
@@ -570,6 +571,25 @@ describe("validateBoot — retention", () => {
     expect(matchingWarn).toBeDefined();
   });
 
+  test("blockDelete without any subject-annotated field stays silent (#1622)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "lease",
+        createEntity({
+          fields: {
+            reference: createTextField({ allowPlaintext: "is-business-data" }),
+          },
+          retention: { keepFor: "10y", strategy: "blockDelete" },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes('strategy="blockDelete" but no field has an anonymize-function'),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
   test('retention.keepFor with invalid format "30days" warns', () => {
     const feature = defineFeature("test", (r) => {
       r.entity(

package/src/engine/__tests__/feature-crud-shorthand.test.ts

@@ -25,4 +25,43 @@ describe("r.crud", () => {
       ["task:detail", "task:list"].sort(),
     );
   });
+
+  test("without verbAccess, write handlers keep write.access (never fall back to the broader read.access)", () => {
+    const write = { access: { roles: ["Manager"] } } as const;
+    const read = { access: { openToAll: true } } as const;
+
+    const feature = defineFeature("via-crud-no-verb-access", (r) => {
+      r.crud("task", taskEntity, { write, read });
+    });
+
+    for (const verb of ["create", "update", "delete", "restore"] as const) {
+      expect(feature.writeHandlers?.[`task:${verb}`]?.access).toEqual(write.access);
+    }
+    for (const verb of ["list", "detail"] as const) {
+      expect(feature.queryHandlers?.[`task:${verb}`]?.access).toEqual(read.access);
+    }
+  });
+
+  test("verbAccess overrides access per verb, other verbs keep write/read.access", () => {
+    const write = { access: { roles: ["Manager"] } } as const;
+    const read = { access: { openToAll: true } } as const;
+    const deleteAccess = { roles: ["Operator"] } as const;
+    const restoreAccess = { roles: ["Operator"] } as const;
+    const listAccess = { roles: ["Auditor"] } as const;
+
+    const feature = defineFeature("via-crud-verb-access", (r) => {
+      r.crud("task", taskEntity, {
+        write,
+        read,
+        verbAccess: { delete: deleteAccess, restore: restoreAccess, list: listAccess },
+      });
+    });
+
+    expect(feature.writeHandlers?.["task:create"]?.access).toEqual(write.access);
+    expect(feature.writeHandlers?.["task:update"]?.access).toEqual(write.access);
+    expect(feature.writeHandlers?.["task:delete"]?.access).toEqual(deleteAccess);
+    expect(feature.writeHandlers?.["task:restore"]?.access).toEqual(restoreAccess);
+    expect(feature.queryHandlers?.["task:list"]?.access).toEqual(listAccess);
+    expect(feature.queryHandlers?.["task:detail"]?.access).toEqual(read.access);
+  });
 });

package/src/engine/__tests__/feature-crud-verb-access.integration.test.ts

@@ -0,0 +1,83 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "../../db/query";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+const propertyEntity = createEntity({
+  table: "crud_verb_access_properties",
+  fields: { title: createTextField({ required: true }) },
+  softDelete: true,
+});
+
+const propertyFeature = defineFeature("crud-verb-access", (r) => {
+  r.crud("property", propertyEntity, {
+    write: { access: { roles: ["User"] } },
+    read: { access: { openToAll: true } },
+    verbAccess: {
+      delete: { roles: ["Admin"] },
+      restore: { roles: ["Admin"] },
+    },
+  });
+});
+
+const CREATE = "crud-verb-access:write:property:create";
+const DELETE = "crud-verb-access:write:property:delete";
+const RESTORE = "crud-verb-access:write:property:restore";
+
+describe("r.crud verbAccess — real dispatcher path", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [propertyFeature] });
+    await unsafeCreateEntityTable(stack.db, propertyEntity);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  beforeEach(async () => {
+    await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+    await asRawClient(stack.db).unsafe('DELETE FROM "crud_verb_access_properties"');
+  });
+
+  test("create stays gated by write.access — User role passes", async () => {
+    const res = await stack.http.write(CREATE, { title: "verbAccess create" }, TestUsers.user);
+    expect(res.status).toBe(200);
+  });
+
+  test("delete overridden by verbAccess — User role (write.access) is rejected", async () => {
+    const created = await stack.http.write(CREATE, { title: "to be deleted" }, TestUsers.user);
+    const { data } = (await created.json()) as { data: { id: string } };
+
+    const res = await stack.http.write(DELETE, { id: data.id }, TestUsers.user);
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { isSuccess: false; error: { code: string } };
+    expect(body.error.code).toBe("access_denied");
+  });
+
+  test("delete overridden by verbAccess — Admin role (verbAccess.delete) passes", async () => {
+    const created = await stack.http.write(
+      CREATE,
+      { title: "to be deleted by admin" },
+      TestUsers.user,
+    );
+    const { data } = (await created.json()) as { data: { id: string } };
+
+    const res = await stack.http.write(DELETE, { id: data.id }, TestUsers.admin);
+    expect(res.status).toBe(200);
+  });
+
+  test("restore overridden by verbAccess — Admin role passes, User role rejected", async () => {
+    const created = await stack.http.write(CREATE, { title: "to be restored" }, TestUsers.user);
+    const { data } = (await created.json()) as { data: { id: string } };
+    await stack.http.write(DELETE, { id: data.id }, TestUsers.admin);
+
+    const deniedRestore = await stack.http.write(RESTORE, { id: data.id }, TestUsers.user);
+    expect(deniedRestore.status).toBe(403);
+
+    const allowedRestore = await stack.http.write(RESTORE, { id: data.id }, TestUsers.admin);
+    expect(allowedRestore.status).toBe(200);
+  });
+});

package/src/engine/boot-validator/pii-retention.ts

@@ -234,11 +234,17 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
       }
 
       if (retention.strategy === "blockDelete") {
+        // blockDelete on an entity with no subject field is the correct
+        // "never auto-delete" choice; User-Forget never reaches those rows (#1622).
+        const hasSubjectField = Object.values(fieldsByName).some((f) => {
+          const a = f as PiiAnnotations; // @cast-boundary schema-walk
+          return Boolean(a.pii || a.userOwned || a.tenantOwned);
+        });
         const hasAnonymize = Object.values(fieldsByName).some((f) => {
           const a = f as PiiAnnotations; // @cast-boundary schema-walk
           return Boolean(a.anonymize);
         });
-        if (!hasAnonymize) {
+        if (hasSubjectField && !hasAnonymize) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
             `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. User-Forget cannot anonymize — Forget will return error. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`,

package/src/engine/entity-handlers.ts

@@ -479,23 +479,31 @@ export function registerEntityCrud(
   }
   const writeOpts = options?.write;
   const readOpts = options?.read;
+  const resolveWriteOpts = (verb: EntityCrudVerb): EntityHandlerOptions => ({
+    ...writeOpts,
+    access: options?.verbAccess?.[verb] ?? writeOpts?.access,
+  });
+  const resolveReadOpts = (verb: EntityCrudVerb): EntityQueryHandlerOptions => ({
+    ...readOpts,
+    access: options?.verbAccess?.[verb] ?? readOpts?.access,
+  });
 
   if (verbs.create) {
-    r.writeHandler(defineEntityCreateHandler(entityName, entity, writeOpts));
+    r.writeHandler(defineEntityCreateHandler(entityName, entity, resolveWriteOpts("create")));
   }
   if (verbs.update) {
-    r.writeHandler(defineEntityUpdateHandler(entityName, entity, writeOpts));
+    r.writeHandler(defineEntityUpdateHandler(entityName, entity, resolveWriteOpts("update")));
   }
   if (verbs.delete) {
-    r.writeHandler(defineEntityDeleteHandler(entityName, entity, writeOpts));
+    r.writeHandler(defineEntityDeleteHandler(entityName, entity, resolveWriteOpts("delete")));
   }
   if (verbs.restore) {
-    r.writeHandler(defineEntityRestoreHandler(entityName, entity, writeOpts));
+    r.writeHandler(defineEntityRestoreHandler(entityName, entity, resolveWriteOpts("restore")));
   }
   if (verbs.list) {
-    r.queryHandler(defineEntityListHandler(entityName, entity, readOpts));
+    r.queryHandler(defineEntityListHandler(entityName, entity, resolveReadOpts("list")));
   }
   if (verbs.detail) {
-    r.queryHandler(defineEntityDetailHandler(entityName, entity, readOpts));
+    r.queryHandler(defineEntityDetailHandler(entityName, entity, resolveReadOpts("detail")));
   }
 }

package/src/pipeline/dispatch-query.ts

@@ -79,7 +79,7 @@ async function executeQueryInner(
     typeof parsed.data === "object" &&
     parsed.data !== null &&
     (parsed.data as Record<string, unknown>)["includeDeleted"] === true; // @cast-boundary validated-payload
-  const handlerContext = buildHandlerContext(ctx, type, user, tx, undefined, includeDeleted);
+  const handlerContext = await buildHandlerContext(ctx, type, user, tx, undefined, includeDeleted);
   let result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
 
   // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data

package/src/pipeline/dispatch-shared.ts

@@ -146,14 +146,14 @@ async function appendDomainEvent(
   );
 }
 
-export function buildHandlerContext(
+export async function buildHandlerContext(
   ctx: DispatchContext,
   type: string,
   user: SessionUser,
   tx?: DbTx,
   afterCommitHooks?: AfterCommitHook[],
   includeDeleted?: boolean,
-): HandlerContext {
+): Promise<HandlerContext> {
   const { registry, appContext: context, effectiveFeatures, jobRunner } = ctx;
   const isSystem = registry.isHandlerSystemScoped(type);
   // The outer dispatcher receives a DbConnection from the server/stack;
@@ -515,13 +515,19 @@ export function buildHandlerContext(
   // HandlerContext. The spread-then-assign order matters: anything in
   // `context` can be overridden, but we want the authoritative registry
   // from the dispatcher's own closure to win.
-  // ctx.tz ist immer da. Tenant + User-Defaults kommen aus dem
-  // SessionUser sobald die Felder existieren — bis dahin "UTC". Ein
-  // app-injizierter GeoTzProvider (context.geoTzProvider) speist
-  // ctx.tz.fromCoordinates / fromAddress.
-  const tz = createTzContext(
-    context.geoTzProvider !== undefined ? { geoTz: context.geoTzProvider } : {},
-  );
+  // ctx.tz is always present. tenant reads tenant:config:timezone through
+  // the already-built `config` accessor (raw qualified-key — no import of
+  // the tenant feature, framework/pipeline stays bundled-features-free);
+  // falls back to "UTC" when config is missing or the key is unset. user
+  // comes from SessionUser.timezone (set at login), else falls back to
+  // tenant (createTzContext's own default). An app-injected GeoTzProvider
+  // (context.geoTzProvider) feeds ctx.tz.fromCoordinates / fromAddress.
+  const tenantTz = config !== undefined ? await config("tenant:config:timezone") : undefined;
+  const tz = createTzContext({
+    ...(context.geoTzProvider !== undefined ? { geoTz: context.geoTzProvider } : {}),
+    tenant: typeof tenantTz === "string" ? tenantTz : "UTC",
+    ...(user.timezone !== undefined && { user: user.timezone }),
+  });
 
   return {
     ...context,

package/src/pipeline/dispatch-stream.ts

@@ -73,7 +73,7 @@ async function* executeStreamInner(
   // await; close is fire-and-forget instead (#1563).
   let abandonedForInvalidation = false;
   try {
-    const handlerContext = buildHandlerContext(ctx, type, user);
+    const handlerContext = await buildHandlerContext(ctx, type, user);
     const chunks = handler.handler({ type, payload: parsed.data, user }, handlerContext);
     iterator = chunks[Symbol.asyncIterator]();
 

package/src/pipeline/dispatch-write.ts

@@ -348,7 +348,7 @@ async function executeWriteInner(
     }
   }
 
-  const handlerContext = buildHandlerContext(ctx, type, user, tx, afterCommitHooks);
+  const handlerContext = await buildHandlerContext(ctx, type, user, tx, afterCommitHooks);
 
   // Auto transition guard: if entity has transitions and handler doesn't skip it
   if (entityName && !handler.unsafeSkipTransitionGuard) {

package/src/stack/request-helper.ts

@@ -14,7 +14,7 @@ type WireErrorBody = {
   };
 };
 
-function formatWriteFailure(type: string, body: unknown): string {
+function formatFailure(kind: "write" | "query", type: string, body: unknown): string {
   const parsed = body as {
     isSuccess?: boolean;
     error?: WireErrorBody | string;
@@ -35,12 +35,12 @@ function formatWriteFailure(type: string, body: unknown): string {
       ? String((details as { causeName?: unknown }).causeName ?? "")
       : "";
   if (code === "internal_error" && (causeMessage || causeName)) {
-    return `Expected write "${type}" to succeed but got error: ${code} (${causeName}: ${causeMessage})`;
+    return `Expected ${kind} "${type}" to succeed but got error: ${code} (${causeName}: ${causeMessage})`;
   }
   if (details !== undefined) {
-    return `Expected write "${type}" to succeed but got error: ${code} — ${JSON.stringify(details)}`;
+    return `Expected ${kind} "${type}" to succeed but got error: ${code} — ${JSON.stringify(details)}`;
   }
-  return `Expected write "${type}" to succeed but got error: ${code}`;
+  return `Expected ${kind} "${type}" to succeed but got error: ${code}`;
 }
 
 export type RequestHelper = {
@@ -80,6 +80,13 @@ export type RequestHelper = {
   ) => Promise<import("../errors").WriteErrorInfo>;
   /** query + json — returns data directly */
   queryOk: <T = unknown>(type: string, payload: unknown, user: SessionUser) => Promise<T>;
+  /** query + json + assert the response is an error — returns the structured
+   *  WriteErrorInfo with `httpStatus` filled in from the HTTP response. */
+  queryErr: (
+    type: string,
+    payload: unknown,
+    user: SessionUser,
+  ) => Promise<import("../errors").WriteErrorInfo>;
 
   /** write + additional HTTP headers (e.g. X-Correlation-ID). Returns the
    *  raw Response so callers can assert on status + headers + body as needed. */
@@ -205,7 +212,7 @@ export function createRequestHelper(
       // follow the error-contract shape { error: { code, i18nKey, ... } } with
       // a 4xx/5xx status — no isSuccess flag. Detect either.
       if (body.isSuccess !== true) {
-        throw new Error(formatWriteFailure(type, body));
+        throw new Error(formatFailure("write", type, body));
       }
       return body.data as T; // @cast-boundary engine-bridge
     },
@@ -239,10 +246,45 @@ export function createRequestHelper(
 
     async queryOk<T = unknown>(type: string, payload: unknown, user: SessionUser): Promise<T> {
       const res = await queryRaw(type, payload, user);
-      const body = (await res.json()) as { data: unknown }; // @cast-boundary engine-bridge
+      const rawBody = await res.json();
+      const body = rawBody as {
+        // @cast-boundary engine-bridge
+        data?: unknown;
+        error?: WireErrorBody | string;
+      };
+      // res.ok mirrors writeOk's isSuccess assertion — belt-and-suspenders
+      // in case a future non-dispatcher rejection skips the error-contract shape.
+      if (!res.ok || body.error !== undefined) {
+        throw new Error(`${formatFailure("query", type, body)} [HTTP ${res.status}]`);
+      }
       return body.data as T; // @cast-boundary engine-bridge
     },
 
+    async queryErr(
+      type: string,
+      payload: unknown,
+      user: SessionUser,
+    ): Promise<import("../errors").WriteErrorInfo> {
+      const res = await queryRaw(type, payload, user);
+      const rawErrorBody = await res.json();
+      const body = rawErrorBody as {
+        // @cast-boundary engine-bridge
+        error?: Omit<import("../errors").WriteErrorInfo, "httpStatus">;
+      };
+      if (res.ok) {
+        throw new Error(`Expected query "${type}" to fail but it succeeded`);
+      }
+      const wire = body.error;
+      if (!wire || typeof wire !== "object" || typeof wire.code !== "string") {
+        throw new Error(
+          `Expected error response for "${type}" but got unexpected shape: ${JSON.stringify(body)}`,
+        );
+      }
+      // Same rationale as writeErr: the wire body has no httpStatus (it would
+      // be redundant with the HTTP response status), so fill it in here.
+      return { ...wire, httpStatus: res.status };
+    },
+
     async writeWithHeaders(type, payload, user, extraHeaders) {
       const authHeaders = await authHeader(user);
       return req("POST", "/api/write", { type, payload }, { ...authHeaders, ...extraHeaders });

package/src/testing/shared-entities.ts

@@ -27,9 +27,20 @@ export const sharedWidgetTable = buildEntityTable("widget", sharedWidgetEntity);
 // realistic-looking user record.
 export const sharedUserEntity = createEntity({
   fields: {
-    email: createTextField({ required: true, format: "email", searchable: true }),
-    firstName: createTextField({ searchable: true }),
-    lastName: createTextField({ searchable: true }),
+    email: createTextField({
+      required: true,
+      format: "email",
+      searchable: true,
+      allowPlaintext: "shared test fixture, not real user data",
+    }),
+    firstName: createTextField({
+      searchable: true,
+      allowPlaintext: "shared test fixture, not real user data",
+    }),
+    lastName: createTextField({
+      searchable: true,
+      allowPlaintext: "shared test fixture, not real user data",
+    }),
     isEnabled: createBooleanField({ default: true }),
   },
   softDelete: true,

package/src/time/tz-context.ts

@@ -10,9 +10,10 @@
 // Feature code should no longer call `new Date()` — the lint rule for that
 // lands in a later iteration, once all existing usages are migrated.
 //
-// `tenant` + `user` are the TZ defaults for the current request. Currently
-// both default to "UTC" — once tenant.timezone + user.timezone fields
-// exist, they get read from the request context here.
+// `tenant` + `user` are the TZ defaults for the current request — resolved
+// by buildHandlerContext (tenant:config:timezone, then SessionUser.timezone,
+// falling back to "UTC" at each step) and passed in via TzContextOptions.
+// This factory itself stays a pure default-filler.
 //
 // The pure type contracts (TzContext, TzContextOptions, LocatedTimestampJson)
 // live in @cosmicdrift/kumiko-types/tz-context — only the factories are here.