@cosmicdrift/kumiko-framework 0.167.1 → 0.170.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.167.1",
+  "version": "0.170.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.1",
+    "@cosmicdrift/kumiko-types": "0.170.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.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.170.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/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/db/event-store-executor-write.ts

@@ -67,14 +67,19 @@ export function createWriteVerbs(
   } = ctx;
 
   return {
-    async create(payload, user, db) {
+    async create(payload, user, db, options) {
       // Respect an explicit id in the payload (seed pattern, SCIM import). Without
       // one the framework mints a fresh UUIDv7 via generateId. Strip it out of the
       // event payload so defaults + downstream consumers don't see a redundant id field.
       const explicitId = typeof payload["id"] === "string" ? (payload["id"] as string) : undefined; // @cast-boundary engine-payload
       const aggregateId = explicitId ?? generateId();
       const { id: _id, ...payloadWithoutId } = payload;
-      const data = applyDefaults(payloadWithoutId);
+      // preSave runs before ownership checks: authorization must evaluate the
+      // row as it will actually be persisted, including hook-derived fields
+      // (kumiko-framework#1672).
+      const data = options?.preSave
+        ? await options.preSave(applyDefaults(payloadWithoutId), {}, true)
+        : applyDefaults(payloadWithoutId);
 
       // H.2 — entity-level write-ownership on create. No oldRow exists, so
       // only the new row is checked. No Straddle concern for creates.
@@ -221,12 +226,19 @@ export function createWriteVerbs(
       const previous = await loadById(payload.id, db);
       if (!previous) return writeFailure(new NotFoundError(entityName, payload.id));
 
+      // preSave runs before ownership checks: authorization must evaluate the
+      // row as it will actually be persisted, including hook-derived fields
+      // (kumiko-framework#1672).
+      const changes = updateOptions?.preSave
+        ? await updateOptions.preSave(payload.changes, previous, false)
+        : payload.changes;
+
       // H.2 — entity-level write-ownership on update. Load old row (already
       // done above), build post-change row via shallow merge. Straddle-safe
       // multi-role check: at least one role must accept BOTH old and new —
       // prevents the attack where role A passes old, role B passes new and
       // aggregation would wrongly allow a row-grab.
-      const mergedNew: Record<string, unknown> = { ...previous, ...payload.changes };
+      const mergedNew: Record<string, unknown> = { ...previous, ...changes };
       if (!userCanWriteFieldRow(user, entity.access?.write, previous, mergedNew)) {
         return writeFailure(
           new UnprocessableError("ownership_denied", {
@@ -247,7 +259,7 @@ export function createWriteVerbs(
       // `previous`, we can run the ownership rules per field against both
       // sides and reject individual fields the user isn't entitled to
       // touch on this specific row.
-      const fieldDeniedUpdate = checkWriteFieldOwnership(entity, payload.changes, user, previous);
+      const fieldDeniedUpdate = checkWriteFieldOwnership(entity, changes, user, previous);
       if (fieldDeniedUpdate) {
         return writeFailure(
           new UnprocessableError("ownership_denied", {
@@ -303,11 +315,11 @@ export function createWriteVerbs(
         // ownerField — the merged row still names the subject.
         const submittedChanges = updateOptions?.skipUnchanged
           ? Object.fromEntries(
-              Object.entries(payload.changes).filter(
+              Object.entries(changes).filter(
                 ([key, value]) => !isUnchangedValue(value, previous[key]),
               ),
             )
-          : payload.changes;
+          : changes;
         const flatChangesPlain = flattenCompoundTypes(submittedChanges, entity);
         const flatChanges = await encryptForStorage(flatChangesPlain, user, {
           onlyKeys: Object.keys(submittedChanges),
@@ -368,7 +380,7 @@ export function createWriteVerbs(
             kind: "save",
             id: data["id"] as EntityId, // @cast-boundary engine-payload
             data,
-            changes: payload.changes,
+            changes,
             previous,
             isNew: false,
             entityName,

package/src/engine/__tests__/entity-presave-wiring.integration.test.ts

@@ -0,0 +1,97 @@
+// Regression coverage for kumiko-framework#1672 — preSave hooks were
+// registered and boot-validated but never invoked by the dispatch path,
+// making `r.hook("preSave", ...)` a silent no-op. This exercises the real
+// HTTP dispatcher (not a hand-fed handler context) so the fix is proven at
+// the layer app authors actually depend on.
+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 contactEntity = createEntity({
+  table: "presave_wiring_contacts",
+  fields: {
+    firstName: createTextField({ required: true }),
+    lastName: createTextField({ required: true }),
+    displayName: createTextField(),
+  },
+});
+
+const seenIsNew: boolean[] = [];
+
+const deriveDisplayName: import("../types").PreSaveHookFn = async (changes, ctx) => {
+  seenIsNew.push(ctx.isNew);
+  const first =
+    (changes["firstName"] as string | undefined) ??
+    (ctx.previous["firstName"] as string | undefined);
+  const last =
+    (changes["lastName"] as string | undefined) ?? (ctx.previous["lastName"] as string | undefined);
+  return { ...changes, displayName: `${first ?? ""} ${last ?? ""}`.trim() };
+};
+
+const contactFeature = defineFeature("presave-wiring", (r) => {
+  r.crud("contact", contactEntity, {
+    write: { access: { roles: ["User"] } },
+    read: { access: { openToAll: true } },
+  });
+
+  // preSave has no entity-wide `{ allOf }` shorthand (unlike postSave/
+  // preDelete/postDelete) — r.crud registers separate create/update
+  // handlers, so both need their own target.
+  r.hook("preSave", "contact:create", deriveDisplayName);
+  r.hook("preSave", "contact:update", deriveDisplayName);
+});
+
+const CREATE = "presave-wiring:write:contact:create";
+const UPDATE = "presave-wiring:write:contact:update";
+
+describe("preSave hooks — real dispatcher path (#1672)", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [contactFeature] });
+    await unsafeCreateEntityTable(stack.db, contactEntity);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  beforeEach(async () => {
+    seenIsNew.length = 0;
+    await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+    await asRawClient(stack.db).unsafe('DELETE FROM "presave_wiring_contacts"');
+  });
+
+  test("create: preSave hook derives displayName before persistence", async () => {
+    const res = await stack.http.write(
+      CREATE,
+      { firstName: "Marc", lastName: "Ristone" },
+      TestUsers.user,
+    );
+    expect(res.status).toBe(200);
+    const { data } = (await res.json()) as { data: { data: { displayName: string } } };
+    expect(data.data.displayName).toBe("Marc Ristone");
+    expect(seenIsNew).toEqual([true]);
+  });
+
+  test("update: preSave hook sees previous row and re-derives displayName", async () => {
+    const created = await stack.http.write(
+      CREATE,
+      { firstName: "Marc", lastName: "Ristone" },
+      TestUsers.user,
+    );
+    const { data } = (await created.json()) as { data: { data: { id: string; version: number } } };
+
+    const res = await stack.http.write(
+      UPDATE,
+      { id: data.data.id, version: data.data.version, changes: { lastName: "Kumiko" } },
+      TestUsers.user,
+    );
+    expect(res.status).toBe(200);
+    const { data: updated } = (await res.json()) as { data: { data: { displayName: string } } };
+    expect(updated.data.displayName).toBe("Marc Kumiko");
+    expect(seenIsNew).toEqual([true, false]);
+  });
+});

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/entity-handlers.ts

@@ -182,7 +182,14 @@ export function defineEntityWriteHandler(
   switch (verb) {
     case "create":
       schema = buildInsertSchema(entity);
-      handler = async (event, ctx) => executor.create(event.payload as DbRow, event.user, ctx.db);
+      handler = async (event, ctx) => {
+        const { runPreSave } = ctx;
+        return executor.create(event.payload as DbRow, event.user, ctx.db, {
+          preSave:
+            runPreSave &&
+            ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
+        });
+      };
       break;
     case "update":
       schema = z.object({
@@ -190,16 +197,21 @@ export function defineEntityWriteHandler(
         version: z.number(),
         changes: buildUpdateSchema(entity),
       });
-      handler = async (event, ctx) =>
+      handler = async (event, ctx) => {
+        const { runPreSave } = ctx;
         // 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.
-        executor.update(event.payload as UpdatePayload, event.user, ctx.db, {
+        return executor.update(event.payload as UpdatePayload, event.user, ctx.db, {
           skipUnchanged: true,
+          preSave:
+            runPreSave &&
+            ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
         }); // @cast-boundary engine-payload
+      };
       break;
     case "delete":
       schema = idSchema;
@@ -479,23 +491,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-shared.ts

@@ -154,7 +154,7 @@ export async function buildHandlerContext(
   afterCommitHooks?: AfterCommitHook[],
   includeDeleted?: boolean,
 ): Promise<HandlerContext> {
-  const { registry, appContext: context, effectiveFeatures, jobRunner } = ctx;
+  const { registry, appContext: context, effectiveFeatures, jobRunner, lifecycle } = ctx;
   const isSystem = registry.isHandlerSystemScoped(type);
   // The outer dispatcher receives a DbConnection from the server/stack;
   // AppContext's `db` union also allows TenantDb (for downstream hook calls),
@@ -537,6 +537,18 @@ export async function buildHandlerContext(
     notify,
     ...(config && { config }),
     ...(files && { files }),
+    // preSave hooks need `changes`/`previous`/`isNew`, which only exist once
+    // a handler actually starts building its write — bound here so entity
+    // CRUD handlers (entity-handlers.ts) can forward it to the executor
+    // (kumiko-framework#1672).
+    ...(lifecycle && {
+      runPreSave: (
+        handlerName: string,
+        changes: Record<string, unknown>,
+        previous: Readonly<Record<string, unknown>>,
+        isNew: boolean,
+      ) => lifecycle.runPreSave(handlerName, changes, previous, isNew, context),
+    }),
     tracer,
     metrics,
     tz,

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,