@cosmicdrift/kumiko-framework 0.257.0 → 0.258.1

package/src/engine/__tests__/projection.test.ts

@@ -17,7 +17,7 @@ const testTable = table("test_projection", {
 function exampleEntity(name = "unit") {
   return createEntity({
     table: name,
-    fields: { name: createTextField() },
+    fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
   });
 }
 

package/src/engine/__tests__/registry.test.ts

@@ -65,11 +65,15 @@ describe("getAllQueryHandlers", () => {
   test("returns every registered query handler, qualified, across multiple features", () => {
     const taskEntity = createEntity({
       table: "registry_test_tasks",
-      fields: { title: createTextField({ required: true }) },
+      fields: {
+        title: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+      },
     });
     const noteEntity = createEntity({
       table: "registry_test_notes",
-      fields: { body: createTextField({ required: true }) },
+      fields: {
+        body: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+      },
     });
     const taskFeature = defineFeature("registry-test-task", (r) => {
       r.crud("task", taskEntity, {
@@ -283,7 +287,13 @@ describe("extensionSelector boot-validation", () => {
     });
     const consumer = defineFeature("money-horse", (r) => {
       r.requires("cap-ext");
-      r.entity("credit", createEntity({ table: "Credits", fields: { name: createTextField() } }));
+      r.entity(
+        "credit",
+        createEntity({
+          table: "Credits",
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
       r.writeHandler(
         "doSomething",
         z.object({}),

package/src/engine/__tests__/schema-builder.test.ts

@@ -32,25 +32,34 @@ describe("buildInsertSchema", () => {
   test.each<SchemaCase>([
     {
       name: "required text field",
-      fields: { email: createTextField({ required: true }) },
+      fields: {
+        email: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+      },
       valid: { email: "test@test.de" },
       invalid: { email: "" },
     },
     {
       name: "optional text field",
-      fields: { name: createTextField() },
+      fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
       valid: {},
       invalid: null,
     },
     {
       name: "text field with maxLength",
-      fields: { name: createTextField({ maxLength: 5 }) },
+      fields: { name: createTextField({ maxLength: 5, personal: false, reason: "test_fixture" }) },
       valid: { name: "hello" },
       invalid: { name: "toolong" },
     },
     {
       name: "email format",
-      fields: { email: createTextField({ required: true, format: "email" }) },
+      fields: {
+        email: createTextField({
+          required: true,
+          format: "email",
+          personal: false,
+          reason: "test_fixture",
+        }),
+      },
       valid: { email: "a@b.de" },
       invalid: { email: "not-an-email" },
     },
@@ -166,8 +175,13 @@ describe("buildInsertSchema", () => {
     const entity = createEntity({
       table: "Users",
       fields: {
-        email: createTextField({ required: true, format: "email" }),
-        firstName: createTextField(),
+        email: createTextField({
+          required: true,
+          format: "email",
+          personal: false,
+          reason: "test_fixture",
+        }),
+        firstName: createTextField({ personal: false, reason: "test_fixture" }),
         isEnabled: createBooleanField({ default: true }),
         locale: createSelectField({ options: ["de", "en"] as const }),
       },
@@ -281,7 +295,9 @@ describe("buildInsertSchema", () => {
   test("required text rejects empty string", () => {
     const entity = createEntity({
       table: "Test",
-      fields: { name: createTextField({ required: true }) },
+      fields: {
+        name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+      },
     });
     const schema = buildInsertSchema(entity);
     expect(schema.safeParse({ name: "" }).success).toBe(false);
@@ -353,7 +369,7 @@ describe("buildInsertSchema", () => {
     const entity = createEntity({
       table: "Test",
       fields: {
-        name: createTextField({ required: true }),
+        name: createTextField({ required: true, personal: false, reason: "test_fixture" }),
         address: createEmbeddedField({ street: { type: "text" } }),
       },
     });
@@ -1061,8 +1077,13 @@ describe("buildUpdateSchema", () => {
     const entity = createEntity({
       table: "Users",
       fields: {
-        email: createTextField({ required: true, format: "email" }),
-        firstName: createTextField(),
+        email: createTextField({
+          required: true,
+          format: "email",
+          personal: false,
+          reason: "test_fixture",
+        }),
+        firstName: createTextField({ personal: false, reason: "test_fixture" }),
         isEnabled: createBooleanField(),
       },
     });
@@ -1082,7 +1103,14 @@ describe("buildUpdateSchema", () => {
   test("still validates format on provided fields", () => {
     const entity = createEntity({
       table: "Users",
-      fields: { email: createTextField({ required: true, format: "email" }) },
+      fields: {
+        email: createTextField({
+          required: true,
+          format: "email",
+          personal: false,
+          reason: "test_fixture",
+        }),
+      },
     });
 
     const schema = buildUpdateSchema(entity);

package/src/engine/__tests__/screen.test.ts

@@ -16,8 +16,8 @@ function productEntity() {
   return createEntity({
     table: "products",
     fields: {
-      name: createTextField(),
-      sku: createTextField(),
+      name: createTextField({ personal: false, reason: "test_fixture" }),
+      sku: createTextField({ personal: false, reason: "test_fixture" }),
     },
   });
 }
@@ -26,7 +26,7 @@ function derivedProductEntity() {
   return createEntity({
     table: "derived_products",
     fields: {
-      name: createTextField(),
+      name: createTextField({ personal: false, reason: "test_fixture" }),
     },
     derivedFields: {
       summary: createDerivedField({
@@ -306,7 +306,10 @@ describe("r.screen() — registration", () => {
       defineFeature("billing", (r) => {
         r.entity(
           "invoice",
-          createEntity({ table: "invoices", fields: { name: createTextField() } }),
+          createEntity({
+            table: "invoices",
+            fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+          }),
         );
         r.screen({
           id: "invoice-detail",
@@ -695,7 +698,10 @@ describe("r.screen() — registration", () => {
       defineFeature("billing", (r) => {
         r.entity(
           "invoice",
-          createEntity({ table: "invoices", fields: { name: createTextField() } }),
+          createEntity({
+            table: "invoices",
+            fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+          }),
         );
         r.screen({
           id: "invoice-detail",
@@ -774,7 +780,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: [],
                 handler: "app:write:save",
               },
@@ -798,7 +804,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: ["sku"],
                 handler: "app:write:save",
               },
@@ -825,7 +831,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: ["name"],
                 handler: "app:write:save",
               },
@@ -849,7 +855,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: ["name"],
                 handler: "app:write:missing",
               },
@@ -886,7 +892,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: ["name"],
                 handler: "app:write:save",
                 submitLabel: "actions.save",
@@ -928,7 +934,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: ["name"],
                 handler: "app:write:save",
               },
@@ -970,7 +976,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: ["name"],
                 handler: "app:write:save",
               },
@@ -996,7 +1002,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: ["name"],
                 handler: "shop:write:save",
               },
@@ -1027,7 +1033,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: ["name"],
                 handler: "shop:write:save",
               },
@@ -1060,7 +1066,7 @@ describe("r.screen() — registration", () => {
               {
                 kind: "writeForm",
                 title: "s",
-                fieldDefs: { name: createTextField() },
+                fieldDefs: { name: createTextField({ personal: false, reason: "test_fixture" }) },
                 fields: ["name"],
                 handler: "shop:write:save",
               },

package/src/engine/__tests__/search-payload-extension.test.ts

@@ -124,7 +124,12 @@ describe("buildSearchDocument — contributor precedence (base fields win)", ()
     const feature = defineFeature("test", (r) => {
       const thing = r.entity(
         "thing",
-        createEntity({ table: "things", fields: { title: createTextField({ searchable: true }) } }),
+        createEntity({
+          table: "things",
+          fields: {
+            title: createTextField({ searchable: true, personal: false, reason: "test_fixture" }),
+          },
+        }),
       );
       r.searchPayloadExtension(thing, contributor);
     });
@@ -151,7 +156,9 @@ describe("buildSearchDocument — contributor precedence (base fields win)", ()
         "thing-dedup",
         createEntity({
           table: "things_dedup",
-          fields: { title: createTextField({ searchable: true }) },
+          fields: {
+            title: createTextField({ searchable: true, personal: false, reason: "test_fixture" }),
+          },
         }),
       );
       r.searchPayloadExtension(thing, () => ({ title: "from-contributor" }));
@@ -177,7 +184,12 @@ describe("buildSearchDocument — contributor precedence (base fields win)", ()
     const feature = defineFeature("test", (r) => {
       const thing = r.entity(
         "thing",
-        createEntity({ table: "things", fields: { title: createTextField({ searchable: true }) } }),
+        createEntity({
+          table: "things",
+          fields: {
+            title: createTextField({ searchable: true, personal: false, reason: "test_fixture" }),
+          },
+        }),
       );
       r.searchPayloadExtension(thing, () => ({ overlap: "first" }));
       r.searchPayloadExtension(thing, () => ({ overlap: "second" }));

package/src/engine/__tests__/store-table.test.ts

@@ -65,7 +65,7 @@ describe("r.storeTable — declaration", () => {
   test("rejects an EntityTableMeta whose source is not 'unmanaged' (#1209)", () => {
     const managedEntity = createEntity({
       table: "rt_probe_managed",
-      fields: { name: createTextField() },
+      fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
     });
     const managedMeta = deriveEntityTableMeta("rt-probe-managed", managedEntity);
     expect(() =>
@@ -173,7 +173,10 @@ describe("createRegistry — storeTable aggregation", () => {
     // default would carry read_, which r.storeTable now rejects outright
     // (#1220), so the collision case needs a table name storeTable can
     // actually register.
-    const widget = createEntity({ table: "shop_widgets", fields: { name: createTextField() } });
+    const widget = createEntity({
+      table: "shop_widgets",
+      fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+    });
     // resolveTableName mirrors the migrate-runner — pin the exact physical name.
     const physical = resolveTableName("widget", widget, "shop");
     const clashing = defineUnmanagedTable({
@@ -203,7 +206,7 @@ describe("createRegistry — store tables with PII-annotated fields (#820)", ()
   const piiEntity = createEntity({
     table: "rt_pii_probe",
     fields: {
-      userId: createTextField({ required: true }),
+      userId: createTextField({ required: true, personal: false, reason: "test_fixture" }),
       ip: createTextField({
         personal: { of: "userId" },
         find: "none",

package/src/engine/__tests__/validate-projection-allowlist.test.ts

@@ -52,7 +52,9 @@ describe("validateProjectionAllowlist", () => {
         "widget",
         createEntity({
           table: "widgets",
-          fields: { label: createTextField({ required: true }) },
+          fields: {
+            label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+          },
         }),
       );
     });
@@ -97,7 +99,9 @@ describe("validateProjectionAllowlist", () => {
         "widget",
         createEntity({
           table: "widgets-delete",
-          fields: { label: createTextField({ required: true }) },
+          fields: {
+            label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+          },
         }),
       );
     });
@@ -353,7 +357,9 @@ describe("validateProjectionAllowlist", () => {
         "thing",
         createEntity({
           table: "shared_table",
-          fields: { label: createTextField({ required: true }) },
+          fields: {
+            label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+          },
         }),
       );
     });
@@ -362,7 +368,9 @@ describe("validateProjectionAllowlist", () => {
         "thing",
         createEntity({
           table: "shared_table",
-          fields: { label: createTextField({ required: true }) },
+          fields: {
+            label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+          },
         }),
       );
     });

package/src/engine/__tests__/validation-hooks.test.ts

@@ -6,7 +6,13 @@ import { runValidation } from "../validation";
 describe("validation hooks", () => {
   test("r.hook registers validation hook", () => {
     const feature = defineFeature("test", (r) => {
-      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.entity(
+        "user",
+        createEntity({
+          table: "Users",
+          fields: { email: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
       r.hook("validation", "user:create", (data) => {
         const errors: ValidationError[] = [];
         if (!data["email"]) errors.push({ field: "email", error: "required" });

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

@@ -32,8 +32,8 @@ function featureWith(entityAccess: AccessMaps, fieldAccess?: AccessMaps): Featur
       createEntity({
         table: "fw2626_guard_memos",
         fields: {
-          ownerId: createTextField({ required: true }),
-          title: createTextField({ access: fieldAccess }),
+          ownerId: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+          title: createTextField({ access: fieldAccess, personal: false, reason: "test_fixture" }),
         },
         access: entityAccess,
       }),

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

@@ -0,0 +1,149 @@
+// fw#2766 — boot guard for join-row entities. The read gate needs the registry,
+// which only exists at request time, so the raw executor stays ungated when a
+// caller doesn't wire `parentVisibility`. That keeps framework-internal cascade
+// and GDPR paths working, and moves enforcement here: a hand-written list/detail
+// handler on a parentRef entity must fail boot rather than leak silently.
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../define-feature";
+import { defineEntityDetailHandler, defineEntityListHandler } from "../../entity-handlers";
+import { createEntity, createTextField } from "../../factories";
+import type { FeatureDefinition } from "../../types";
+import { validateParentRefs } from "../parent-ref";
+
+const textField = () =>
+  createTextField({
+    required: true,
+    maxLength: 64,
+    personal: false,
+    reason: "technical_reference",
+  });
+
+const hostEntity = createEntity({
+  table: "read_hosts",
+  fields: { name: textField() },
+});
+
+function joinEntity(parentRef: {
+  entityTypeField: string;
+  entityIdField: string;
+  allowedTypes?: readonly string[];
+}) {
+  return createEntity({
+    table: "read_joins",
+    fields: { entityType: textField(), entityId: textField() },
+    parentRef,
+  });
+}
+
+const validRef = { entityTypeField: "entityType", entityIdField: "entityId" } as const;
+
+function featureMapOf(...features: readonly FeatureDefinition[]) {
+  return new Map(features.map((f) => [f.name, f]));
+}
+
+function validate(feature: FeatureDefinition, extra: readonly FeatureDefinition[] = []): void {
+  validateParentRefs(feature, featureMapOf(feature, ...extra));
+}
+
+describe("validateParentRefs", () => {
+  test("accepts a parentRef whose fields exist and whose list/detail are convention handlers", () => {
+    const entity = joinEntity(validRef);
+    const feature = defineFeature("joins", (r) => {
+      r.entity("join", entity);
+      r.queryHandler(defineEntityListHandler("join", entity, { access: { openToAll: true } }));
+      r.queryHandler(defineEntityDetailHandler("join", entity, { access: { openToAll: true } }));
+    });
+    expect(() => validate(feature)).not.toThrow();
+  });
+
+  test("an entity with no parentRef is not checked at all", () => {
+    const feature = defineFeature("plain", (r) => {
+      r.entity("host", hostEntity);
+      r.queryHandler({
+        name: "host:list",
+        schema: z.object({}),
+        handler: async () => ({ rows: [], nextCursor: null }),
+        access: { openToAll: true },
+      });
+    });
+    expect(() => validate(feature)).not.toThrow();
+  });
+
+  test("rejects an entityTypeField that is not a declared field", () => {
+    const feature = defineFeature("joins", (r) => {
+      r.entity("join", joinEntity({ ...validRef, entityTypeField: "nope" }));
+    });
+    expect(() => validate(feature)).toThrow(/entityTypeField references "nope"/);
+  });
+
+  test("rejects an entityIdField that is not a declared field", () => {
+    const feature = defineFeature("joins", (r) => {
+      r.entity("join", joinEntity({ ...validRef, entityIdField: "nope" }));
+    });
+    expect(() => validate(feature)).toThrow(/entityIdField references "nope"/);
+  });
+
+  test("rejects an allowedTypes entry that names no registered entity", () => {
+    const feature = defineFeature("joins", (r) => {
+      r.entity("join", joinEntity({ ...validRef, allowedTypes: ["ghost"] }));
+    });
+    expect(() => validate(feature)).toThrow(/names "ghost"/);
+  });
+
+  test("accepts an allowedTypes entry registered by another feature", () => {
+    const hosts = defineFeature("hosts", (r) => {
+      r.entity("host", hostEntity);
+    });
+    const entity = joinEntity({ ...validRef, allowedTypes: ["host"] });
+    const feature = defineFeature("joins", (r) => {
+      r.entity("join", entity);
+      r.queryHandler(defineEntityListHandler("join", entity, { access: { openToAll: true } }));
+    });
+    expect(() => validate(feature, [hosts])).not.toThrow();
+  });
+
+  test("rejects an allowedTypes host that is itself a join row — no recursive gating", () => {
+    const others = defineFeature("others", (r) => {
+      r.entity("other", joinEntity(validRef));
+    });
+    const feature = defineFeature("joins", (r) => {
+      r.entity("join", joinEntity({ ...validRef, allowedTypes: ["other"] }));
+    });
+    expect(() => validate(feature, [others])).toThrow(/itself declares a parentRef/);
+  });
+
+  test("rejects a hand-written list handler, which would bypass the read gate", () => {
+    const feature = defineFeature("joins", (r) => {
+      r.entity("join", joinEntity(validRef));
+      r.queryHandler({
+        name: "join:list",
+        schema: z.object({}),
+        handler: async () => ({ rows: [], nextCursor: null }),
+        access: { openToAll: true },
+      });
+    });
+    expect(() => validate(feature)).toThrow(/join:list/);
+  });
+
+  test("rejects a hand-written detail handler too", () => {
+    const feature = defineFeature("joins", (r) => {
+      r.entity("join", joinEntity(validRef));
+      r.queryHandler({
+        name: "join:detail",
+        schema: z.object({ id: z.uuid() }),
+        handler: async () => null,
+        access: { openToAll: true },
+      });
+    });
+    expect(() => validate(feature)).toThrow(/join:detail/);
+  });
+
+  test("registering no list/detail handler at all is allowed", () => {
+    const feature = defineFeature("joins", (r) => {
+      r.entity("join", joinEntity(validRef));
+    });
+    expect(() => validate(feature)).not.toThrow();
+  });
+});

package/src/engine/boot-validator/action-wiring.ts

@@ -1,4 +1,9 @@
-import { isFieldsEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
+import {
+  isEditLayoutScreen,
+  isFieldsEditSection,
+  normalizeEditField,
+  normalizeListColumn,
+} from "../screen-helpers";
 import type {
   EditFieldSpec,
   EditLayout,
@@ -138,12 +143,7 @@ export function validateFieldWiring(feature: FeatureDefinition): void {
       validateColumnsNoFunctions(feature.name, screen.id, screen.type, screen.columns);
       continue;
     }
-    if (
-      screen.type === "entityEdit" ||
-      screen.type === "actionForm" ||
-      screen.type === "configEdit" ||
-      screen.type === "projectionDetail"
-    ) {
+    if (isEditLayoutScreen(screen)) {
       validateEditLayoutNoFunctions(feature.name, screen.id, screen.type, screen.layout);
       continue;
     }

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

@@ -45,6 +45,7 @@ import {
   warnOnNavAccessInversion,
 } from "./nav";
 import { collectClaimKeys, validateOwnershipRules } from "./ownership";
+import { validateParentRefs } from "./parent-ref";
 import { validatePiiAndRetention } from "./pii-retention";
 import {
   validateProjectionListScreens,
@@ -195,6 +196,7 @@ export function validateBoot(
     validateConfigKeyBacking(feature);
     validateConfigKeyPiiEncrypted(feature);
     validateOwnershipRules(feature, allClaimKeys, knownRoles);
+    validateParentRefs(feature, featureMap);
     validateMultiStreamProjections(feature);
     // Vor validateScreens: dessen visible/entityId-Feldref-Checks werfen für
     // einen Function-Wert bereits (mit verwirrender "unknown field undefined"-