@cosmicdrift/kumiko-framework 0.170.0 → 0.171.1

package/package.json

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

package/src/__tests__/schema-cli.integration.test.ts

@@ -200,6 +200,25 @@ CREATE TABLE IF NOT EXISTS "read_widgets_v2" ("id" uuid PRIMARY KEY);
     expect(cap.err.join("\n")).toContain("read_widgets");
   });
 
+  test("migration creates a table with no snapshot entry → unexpected-table hint points at r.storeTable, not hand-fix", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    writeFileSync(
+      join(appCwd, "kumiko/migrations/0002_raw.sql"),
+      `-- hand-written table outside the entity system, never registered via r.storeTable
+CREATE TABLE IF NOT EXISTS "marketing_waitlist" ("id" uuid PRIMARY KEY);
+`,
+    );
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    const err = cap.err.join("\n");
+    expect(err).toContain("marketing_waitlist");
+    expect(err).toContain("Fix (unexpected-table)");
+    expect(err).toContain("r.storeTable");
+    expect(err).not.toContain("Fix (missing-table/column-drift)");
+  });
+
   test("no FEATURES export → validateBoot skipped (drift still checked)", async () => {
     writeSchemaFile(appCwd, "read_widgets");
     await runSchemaCli(["generate", "init"], appCwd, captureOut().out);

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

@@ -384,6 +384,71 @@ 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);
+  });
+
+  // #1702: same ""-problem as #1674, but for a select WITH a default —
+  // an untouched <select> sends "" and the default only kicks in for
+  // undefined. "" maps to the default (a defaulted field is never unset).
+  test("optional select with default accepts empty string and falls back to the default", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        locale: createSelectField({ options: ["de", "en", "fr"] as const, default: "de" }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    const result = schema.safeParse({ locale: "" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["locale"]).toBe("de");
+    }
+  });
+
+  test("optional select with default still validates a real value", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        locale: createSelectField({ options: ["de", "en"] as const, default: "de" }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ locale: "en" }).success).toBe(true);
+    expect(schema.safeParse({ locale: "xx" }).success).toBe(false);
+  });
 });
 
 // --- Update schema (all partial) ---
@@ -422,4 +487,56 @@ 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);
+    }
+  });
+
+  // Update schemas strip defaults deliberately (buildUpdateSchema never
+  // applies them — omitting a field must leave it untouched). So "" maps
+  // to the same explicit clear-to-null as the no-default case; only the
+  // insert path falls back to the default (#1702).
+  test("optional select with default on update: empty string is a clear-to-null, not the default", () => {
+    const entity = createEntity({
+      table: "Test",
+      fields: {
+        locale: createSelectField({ options: ["de", "en"] as const, default: "de" }),
+      },
+    });
+
+    const schema = buildUpdateSchema(entity);
+    const result = schema.safeParse({ locale: "" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data["locale"]).toBeNull();
+    }
+  });
 });

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

@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import type { FeatureDefinition } from "../../types";
+import { warnOnUniqueAccessRoles } from "../access-roles";
+
+function fakeFeature(overrides: Partial<FeatureDefinition> & { name: string }): FeatureDefinition {
+  return {
+    writeHandlers: {},
+    queryHandlers: {},
+    streamHandlers: {},
+    ...overrides,
+  } as unknown as FeatureDefinition;
+}
+
+describe("warnOnUniqueAccessRoles", () => {
+  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn");
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  test("warns when a role is used by exactly one handler", () => {
+    const features = [
+      fakeFeature({
+        name: "users",
+        writeHandlers: {
+          "create-user": { name: "create-user", access: { roles: ["Admin"] } },
+        } as unknown as FeatureDefinition["writeHandlers"],
+      }),
+    ];
+
+    warnOnUniqueAccessRoles(features);
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = warnSpy.mock.calls[0]![0] as string;
+    expect(msg).toContain("Admin");
+    expect(msg).toContain("users:write:create-user");
+  });
+
+  test("does NOT warn when the same role is used by two different handlers", () => {
+    const features = [
+      fakeFeature({
+        name: "users",
+        writeHandlers: {
+          "create-user": { name: "create-user", access: { roles: ["Admin"] } },
+        } as unknown as FeatureDefinition["writeHandlers"],
+      }),
+      fakeFeature({
+        name: "billing",
+        queryHandlers: {
+          "list-invoices": { name: "list-invoices", access: { roles: ["Admin"] } },
+        } as unknown as FeatureDefinition["queryHandlers"],
+      }),
+    ];
+
+    warnOnUniqueAccessRoles(features);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("does NOT warn for built-in roles 'all' or 'system' even when used by one handler", () => {
+    const features = [
+      fakeFeature({
+        name: "misc",
+        writeHandlers: {
+          "open-endpoint": { name: "open-endpoint", access: { roles: ["all"] } },
+        } as unknown as FeatureDefinition["writeHandlers"],
+      }),
+      fakeFeature({
+        name: "admin-tools",
+        streamHandlers: {
+          "audit-log": { name: "audit-log", access: { roles: ["system"] } },
+        } as unknown as FeatureDefinition["streamHandlers"],
+      }),
+    ];
+
+    warnOnUniqueAccessRoles(features);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

package/src/engine/boot-validator/access-roles.ts

@@ -0,0 +1,43 @@
+import type { FeatureDefinition } from "../types";
+
+const BUILTIN_ROLES = new Set(["all", "system"]);
+
+export function warnOnUniqueAccessRoles(features: readonly FeatureDefinition[]): void {
+  // role → set of distinct handler identifiers using it
+  const roleHandlers = new Map<string, Set<string>>();
+
+  for (const f of features) {
+    const handlerGroups = [
+      { type: "write", defs: f.writeHandlers },
+      { type: "query", defs: f.queryHandlers },
+      { type: "stream", defs: f.streamHandlers },
+    ] as const;
+
+    for (const { type, defs } of handlerGroups) {
+      for (const [handlerName, def] of Object.entries(defs)) {
+        if (!def.access || !("roles" in def.access)) continue;
+        const identifier = `${f.name}:${type}:${handlerName}`;
+        for (const role of def.access.roles) {
+          let handlers = roleHandlers.get(role);
+          if (!handlers) {
+            handlers = new Set();
+            roleHandlers.set(role, handlers);
+          }
+          handlers.add(identifier);
+        }
+      }
+    }
+  }
+
+  for (const [role, handlers] of roleHandlers) {
+    if (BUILTIN_ROLES.has(role)) continue;
+    if (handlers.size !== 1) continue;
+    const [identifier] = handlers;
+    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+    console.warn(
+      `[kumiko:boot] Access role "${role}" is only used by one handler (${identifier}). ` +
+        `This is often a typo — the role is unknown to every other handler in the boot scan. ` +
+        `If this is intentional, ignore this warning.`,
+    );
+  }
+}

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/index.ts

@@ -1,6 +1,7 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
+import { warnOnUniqueAccessRoles } from "./access-roles";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
 import { validateFeatureBootChecks } from "./boot-check";
@@ -212,4 +213,5 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
 
   validateConfigReads(features, allConfigKeys);
   warnOnToggleableDependencies(features, featureMap);
+  warnOnUniqueAccessRoles(features);
 }

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/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,22 @@ 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)
+        // Untouched <select> sends "" too; with a default that maps to the
+        // default (same semantics as undefined) instead of the invalid-value
+        // rejection from #1702. A field with a default is never "unset".
+        return z.preprocess(
+          (value) => (value === "" ? field.default : value),
+          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/schema-cli.ts

@@ -287,9 +287,22 @@ export async function runSchemaCli(
             for (const m of mismatches) {
               out.err(`    ${m.tableName} (${m.kind}): ${m.detail}`);
             }
-            out.err(
-              "    Fix: a migration file's body doesn't match what it (or the snapshot) claims — hand-fix the file, or ship a corrective migration if it's already applied in prod.",
-            );
+            if (mismatches.some((m) => m.kind === "unexpected-table")) {
+              out.err(
+                "    Fix (unexpected-table): register the raw/hand-written table via `table()` " +
+                  "(or `defineUnmanagedTable()`) from `@cosmicdrift/kumiko-framework/db`, then " +
+                  "`r.storeTable(meta, { reason: ... })` inside a feature — this adds it to " +
+                  "ENTITY_METAS and the snapshot without going through r.entity(). See the " +
+                  "bundled `jobs` feature's job-run-log store table for the pattern.",
+              );
+            }
+            if (mismatches.some((m) => m.kind !== "unexpected-table")) {
+              out.err(
+                "    Fix (missing-table/column-drift): a migration file's body doesn't match " +
+                  "what it (or the snapshot) claims — hand-fix the file, or ship a corrective " +
+                  "migration if it's already applied in prod.",
+              );
+            }
           }
         } catch (e) {
           // replayMigrationsDir fail-loud's on a table-DDL statement it can't

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,