@cosmicdrift/kumiko-framework 0.168.0 → 0.171.0

package/package.json

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

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__/boot-validator-pii-retention.test.ts

@@ -271,6 +271,42 @@ describe("validateBoot — PII annotations", () => {
     expect(matchingWarn).toBeDefined();
   });
 
+  test("user-reference-name heuristic warns when authorId field has no subjectRef annotation", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "thing",
+        createEntity({
+          fields: {
+            authorId: createTextField(),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes("user-reference-typical name"),
+    );
+    expect(matchingWarn).toBeDefined();
+  });
+
+  test("subjectRef: true on authorId field silences user-reference-name heuristic warning", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "thing",
+        createEntity({
+          fields: {
+            authorId: createTextField({ subjectRef: true }),
+          },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes("user-reference-typical name"),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
   test("allowPlaintext marker silences PII-name heuristic warning", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(

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

@@ -2820,4 +2820,204 @@ describe("boot-validator — config key backing × scope", () => {
     });
     expect(() => validateBoot([feature])).not.toThrow();
   });
+
+  test("navigate with params targeting a dashboard screen → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "view",
+            label: "actions.view",
+            screen: "product-dashboard",
+            params: { pick: ["name"] },
+          },
+        ],
+      });
+      r.queryHandler("count", z.object({}), async () => ({ total: 0 }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "product-dashboard",
+        type: "dashboard",
+        panels: [
+          {
+            kind: "stat",
+            id: "count",
+            label: "Products",
+            query: "shop:query:count",
+            valueField: "total",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /sets params on navigate-target "product-dashboard".*screen type "dashboard".*only actionForm and entityEdit-create/,
+    );
+  });
+
+  test("navigate with params targeting a custom screen → no throw (author owns the component, may read searchParams itself)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "view",
+            label: "actions.view",
+            screen: "product-dashboard",
+            params: { pick: ["name"] },
+          },
+        ],
+      });
+      r.screen({
+        id: "product-dashboard",
+        type: "custom",
+        renderer: { react: "stub" },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("navigate with params targeting a same-entity entityEdit screen → Throw (resolves to update mode)", () => {
+    // No explicit entityId + same entity as the source list → the renderer's
+    // runNavigate() auto-fills row["id"], landing in EntityEditUpdateBody,
+    // which never reads searchParams. Params would silently no-op.
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "open",
+            label: "actions.open",
+            screen: "product-edit",
+            params: { pick: ["name"] },
+          },
+        ],
+      });
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: { sections: [{ columns: 1, fields: ["name"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /resolves to UPDATE mode.*same entity "product" auto-fills row\["id"\]/,
+    );
+  });
+
+  test("navigate with params + explicit entityId targeting an entityEdit screen → Throw (forced update mode)", () => {
+    const feature = defineFeature("housing", (r) => {
+      r.entity("unit", createEntity({ fields: { name: createTextField() } }));
+      r.entity("contract", createEntity({ fields: { unitId: createTextField() } }));
+      r.screen({
+        id: "unit-list",
+        type: "entityList",
+        entity: "unit",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "edit-contract",
+            label: "actions.edit-contract",
+            screen: "contract-edit",
+            entityId: "name",
+            params: { pick: ["name"] },
+          },
+        ],
+      });
+      r.screen({
+        id: "contract-edit",
+        type: "entityEdit",
+        entity: "contract",
+        layout: { sections: [{ columns: 1, fields: ["unitId"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /resolves to UPDATE mode \(explicit entityId "name"\)/,
+    );
+  });
+
+  test("navigate with params targeting a cross-entity entityEdit screen (no explicit entityId) → no throw", () => {
+    // The issue's actual use case: a unit row navigates to "create contract"
+    // pre-filled with unitId. Different entity + no explicit entityId → the
+    // renderer's same-entity row["id"] fallback does NOT fire, so this stays
+    // in create mode and EntityEditCreateBody reads the params.
+    const feature = defineFeature("housing", (r) => {
+      r.entity("unit", createEntity({ fields: { name: createTextField() } }));
+      r.entity("contract", createEntity({ fields: { unitId: createTextField() } }));
+      r.screen({
+        id: "unit-list",
+        type: "entityList",
+        entity: "unit",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "create-contract",
+            label: "actions.create-contract",
+            screen: "contract-edit",
+            params: { map: { unitId: "name" } },
+          },
+        ],
+      });
+      r.screen({
+        id: "contract-edit",
+        type: "entityEdit",
+        entity: "contract",
+        layout: { sections: [{ columns: 1, fields: ["unitId"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("navigate with params targeting an actionForm screen → no throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.writeHandler(
+        "create",
+        z.object({ name: z.string() }),
+        async () => ({ isSuccess: true as const, data: { id: "1" } }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "open-form",
+            label: "actions.form",
+            screen: "product-form",
+            params: { pick: ["name"] },
+          },
+        ],
+      });
+      r.screen({
+        id: "product-form",
+        type: "actionForm",
+        handler: "shop:write:create",
+        fields: { name: createTextField() },
+        layout: { sections: [{ columns: 1, fields: ["name"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
 });

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__/schema-builder.test.ts

@@ -384,6 +384,41 @@ describe("buildInsertSchema", () => {
       schema.safeParse({ pickup: { at: "2026-04-03T10:00:00", tz: "Mars/Phobos" } }).success,
     ).toBe(false);
   });
+
+  // #1674: an untouched HTML <select> submits "" for its placeholder option.
+  // An optional select without a default must treat "" as "not set" (null),
+  // not reject it as an invalid enum value.
+  test("optional select without default accepts empty string as unset (null)", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: { locale: createSelectField({ options: ["de", "en", "fr"] as const }) },
+    });
+    const schema = buildInsertSchema(entity);
+    const result = schema.safeParse({ locale: "" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["locale"]).toBeNull();
+    }
+  });
+
+  test("optional select without default still validates a real value", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: { locale: createSelectField({ options: ["de", "en", "fr"] as const }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ locale: "en" }).success).toBe(true);
+    expect(schema.safeParse({ locale: "xx" }).success).toBe(false);
+  });
+
+  test("required select rejects empty string", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: { locale: createSelectField({ options: ["de", "en"] as const, required: true }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ locale: "" }).success).toBe(false);
+  });
 });
 
 // --- Update schema (all partial) ---
@@ -422,4 +457,36 @@ describe("buildUpdateSchema", () => {
     expect(schema.safeParse({ email: "valid@test.de" }).success).toBe(true);
     expect(schema.safeParse({ email: "not-email" }).success).toBe(false);
   });
+
+  // #1674: clearing a previously-set optional select back to "unset" must
+  // work through the update path too — "" from an untouched <select> maps to
+  // an explicit `null`, not `undefined` (which would be dropped from the
+  // changes payload and silently no-op instead of clearing).
+  test("optional select accepts empty string as an explicit clear-to-null", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: { locale: createSelectField({ options: ["de", "en"] as const }) },
+    });
+
+    const schema = buildUpdateSchema(entity);
+    const result = schema.safeParse({ locale: "" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["locale"]).toBeNull();
+    }
+  });
+
+  test("omitting an optional select on update leaves it untouched", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: { locale: createSelectField({ options: ["de", "en"] as const }) },
+    });
+
+    const schema = buildUpdateSchema(entity);
+    const result = schema.safeParse({});
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(Object.hasOwn(result.data, "locale")).toBe(false);
+    }
+  });
 });

package/src/engine/boot-validator/entity-handler.ts

@@ -53,6 +53,27 @@ export const PII_USER_OWNED_NAME_HINTS: ReadonlySet<string> = new Set([
   "notes",
 ]);
 
+// Field names that typically hold a FK into the `user` entity — carry no
+// content of their own, but the subject-data obligation attaches to the
+// link, not to annotated content. Without this hint, an entity with no
+// userOwned-content field stays invisible to the GDPR-hook-coverage guard
+// even though `authorId` is still personal data.
+export const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string> = new Set([
+  "authorid",
+  "assigneeid",
+  "ownerid",
+  "createdbyid",
+  "createdbyuserid",
+  "updatedbyid",
+  "updatedbyuserid",
+  "invitedby",
+  "approvedby",
+  "reviewedby",
+  "uploadedby",
+  "assignedto",
+  "reportedby",
+]);
+
 // --- Extension preSave wiring validation ---
 
 /** Extensions with preSave must target an entity that has mapped write handlers. */

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

@@ -1,6 +1,10 @@
 import type { FeatureDefinition } from "../types";
 import type { FieldAccess, PiiAnnotations } from "../types/fields";
-import { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS } from "./entity-handler";
+import {
+  PII_DIRECT_NAME_HINTS,
+  PII_USER_OWNED_NAME_HINTS,
+  PII_USER_REFERENCE_NAME_HINTS,
+} from "./entity-handler";
 
 // Framework-managed Timestamp-Spalten — dürfen als retention.reference
 // genutzt werden auch wenn nicht in entity.fields deklariert.
@@ -208,6 +212,11 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
           console.warn(
             `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-content-typical name but no { userOwned } annotation. If this contains user-generated content, mark it { userOwned: { ownerField: "<authorIdField>" }}. If business data, set { allowPlaintext: "..." } to silence.`,
           );
+        } else if (PII_USER_REFERENCE_NAME_HINTS.has(lower) && !annot.subjectRef) {
+          // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+          console.warn(
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no { subjectRef: true } annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { subjectRef: true }, or { userOwned: { ownerField: "${fieldName}" } } on the field it owns. If business data, set { allowPlaintext: "..." } to silence.`,
+          );
         }
       }
     }

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

@@ -575,6 +575,48 @@ export function validateScreens(
                   `the row field that names the target entity's id.`,
               );
             }
+            // params only have a reader in actionForm and entityEdit-CREATE;
+            // on projectionDetail/dashboard/configEdit/entityEdit-update they
+            // are silently ignored at runtime. `custom` is deliberately
+            // exempt: it renders an app-registered component the framework
+            // has no visibility into — the author may read nav.searchParams
+            // directly (real example: publicstatus's MonitorDetailScreen
+            // does exactly that), so flagging it would be a false positive
+            // on working code, not a caught bug.
+            //
+            // Whether an entityEdit target lands in create or update mode is
+            // decided by the same rule the renderer's runNavigate() uses: an
+            // explicit entityId always forces update mode, and (absent an
+            // explicit entityId) a same-entity target gets row["id"] auto-
+            // injected — only a cross-entity target with no explicit
+            // entityId reaches create.
+            if (
+              action.params !== undefined &&
+              target !== undefined &&
+              target.screen.type !== "custom"
+            ) {
+              const isEntityEditUpdate =
+                target.screen.type === "entityEdit" &&
+                (action.entityId !== undefined || target.screen.entity === screen.entity);
+              if (
+                (target.screen.type !== "actionForm" && target.screen.type !== "entityEdit") ||
+                isEntityEditUpdate
+              ) {
+                const reason = isEntityEditUpdate
+                  ? `resolves to UPDATE mode (${
+                      action.entityId !== undefined
+                        ? `explicit entityId "${action.entityId}"`
+                        : `same entity "${screen.entity}" auto-fills row["id"]`
+                    })`
+                  : `screen type "${target.screen.type}"`;
+                throw new Error(
+                  `[Feature ${feature.name}] Screen "${screenId}" (entityList) rowAction "${action.id}" ` +
+                    `sets params on navigate-target "${action.screen}" which ${reason} — only actionForm ` +
+                    `and entityEdit-create targets read URL search params as initial values. Remove the ` +
+                    `params extractor or retarget to an actionForm / cross-entity entityEdit-create screen.`,
+                );
+              }
+            }
           } else {
             if (!allWriteHandlerQns.has(action.handler)) {
               throw new Error(

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;

package/src/engine/index.ts

@@ -202,7 +202,12 @@ export {
   stripForbiddenMembershipRoles,
 } from "./membership-roles";
 export type { OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule } from "./ownership";
-export { from } from "./ownership";
+export {
+  buildOwnershipClause,
+  from,
+  userCanReadFieldRow,
+  userCanWriteFieldRow,
+} from "./ownership";
 export { buildPipelineSteps, stepsPipeline } from "./pipeline";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers";
 export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";

package/src/engine/schema-builder.ts

@@ -80,8 +80,15 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
     case "select": {
       const [first, ...rest] = field.options;
       if (!first) return z.string();
-      const schema = z.enum([first, ...rest]);
-      return field.default !== undefined ? schema.default(field.default) : schema;
+      const enumSchema = z.enum([first, ...rest]);
+      if (field.default !== undefined) return enumSchema.default(field.default);
+      if (field.required) return enumSchema;
+      // Optional select without a default: an untouched HTML <select> submits
+      // "" for its placeholder option. Treat that as "unset" (null) instead of
+      // an invalid enum value — null (not undefined) so the value survives the
+      // JSON-serialized event payload and an update can actually clear a
+      // previously-set select back to unset, not just skip validation.
+      return z.preprocess((value) => (value === "" ? null : value), enumSchema.nullable());
     }
     case "multiSelect": {
       const [first, ...rest] = field.options;

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/testing/boot-validator-fixture.ts

@@ -62,12 +62,15 @@ function ensureEntityListRowNavigation(
     ...screen,
     rowActions: [
       ...(screen.rowActions ?? []),
+      // No `params` here: this same-entity target always resolves to
+      // UPDATE mode (the renderer auto-fills entityId from row["id"]),
+      // and entityEdit-update never reads search-params as initial
+      // values — the boot-validator now rejects that combination (#1680).
       {
         kind: "navigate",
         id: "edit",
         label: "stub:edit",
         screen: editScreen.id,
-        params: { pick: ["id"] },
       },
     ],
   };

package/src/ui-types/index.ts

@@ -72,6 +72,7 @@ export type {
   EntityListScreenDefinition,
   FieldCondition,
   FieldRenderer,
+  FormWidth,
   ListColumnSpec,
   PlatformComponent,
   ProjectionDetailScreenDefinition,