@cosmicdrift/kumiko-framework 0.170.0 → 0.171.0

package/package.json

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

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,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/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/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,