@cosmicdrift/kumiko-framework 0.270.0 → 0.273.0

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

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { validateBoot } from "../boot-validator";
 import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
 
 describe("validateBoot — projectionList screens", () => {
   test("rejects hand-written searchable:true when the query schema has no search param (3a)", () => {
@@ -441,5 +442,95 @@ describe("validateBoot — projectionList screens", () => {
       });
       expect(() => validateBoot([feature])).not.toThrow();
     });
+
+    test("a reference facet targeting an unknown entity is rejected", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ filters: z.unknown().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["tenant"],
+          facets: [{ field: "tenant", type: "reference", label: "Tenant", entity: "tenant" }],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/does not resolve to a registered entity/);
+    });
+
+    test("a reference facet targeting a known entity passes boot", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.entity(
+          "tenant",
+          createEntity({
+            table: "Tenants",
+            fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+          }),
+        );
+        r.queryHandler(
+          "schedule:list",
+          z.object({ filters: z.unknown().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["tenant"],
+          facets: [{ field: "tenant", type: "reference", label: "Tenant", entity: "tenant" }],
+        });
+        r.translations({
+          keys: {
+            "screen:schedule-list.title": { de: "Liste", en: "List" },
+            "ledger:entity:tenant:field:name": { de: "Name", en: "Name" },
+          },
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+
+    test("a reference facet filtering by an id field with no same-named column boots (displays a different label column)", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.entity(
+          "property",
+          createEntity({
+            table: "Properties",
+            fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+          }),
+        );
+        r.queryHandler(
+          "schedule:list",
+          z.object({ filters: z.unknown().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          // Filters by propertyId, displays propertyLabel — no "propertyId"
+          // column exists, and none should be required for a reference facet.
+          columns: ["propertyLabel"],
+          facets: [
+            { field: "propertyId", type: "reference", label: "Property", entity: "property" },
+          ],
+        });
+        r.translations({
+          keys: {
+            "screen:schedule-list.title": { de: "Liste", en: "List" },
+            "ledger:entity:property:field:name": { de: "Name", en: "Name" },
+          },
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
   });
 });

package/src/engine/__tests__/boot-validator-query-output-schema.test.ts

@@ -142,6 +142,149 @@ describe("validateBoot — query output schema column refs (fw#2493)", () => {
     );
   });
 
+  test("relatedList toolbarAction visible.field not in the projectionDetail's own outputSchema throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("lease:detail", z.object({}), async () => ({ id: "1", status: "active" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        outputSchema: z.object({ id: z.string(), status: z.string() }),
+      });
+      r.queryHandler(
+        "lease:positions",
+        z.object({}),
+        async () => ({ rows: [], nextCursor: null }),
+        {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          outputSchema: z.object({
+            rows: z.array(z.object({ id: z.string() })),
+            nextCursor: z.string().nullable(),
+          }),
+        },
+      );
+      r.screen({
+        id: "lease-detail",
+        type: "projectionDetail",
+        query: "app:query:lease:detail",
+        layout: {
+          sections: [
+            {
+              kind: "relatedList",
+              title: "Positions",
+              query: "app:query:lease:positions",
+              columns: ["id"],
+              toolbarActions: [
+                {
+                  kind: "navigate",
+                  id: "create",
+                  label: "Add position",
+                  screen: "position-create",
+                  visible: { field: "ghost-status", eq: "active" },
+                },
+              ],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /toolbarAction "create" visible\.field references unknown field "ghost-status"/,
+    );
+  });
+
+  test("relatedList toolbarAction navigate params source field not in the projectionDetail's own outputSchema throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("lease:detail", z.object({}), async () => ({ id: "1" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        outputSchema: z.object({ id: z.string() }),
+      });
+      r.queryHandler(
+        "lease:positions",
+        z.object({}),
+        async () => ({ rows: [], nextCursor: null }),
+        {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          outputSchema: z.object({
+            rows: z.array(z.object({ id: z.string() })),
+            nextCursor: z.string().nullable(),
+          }),
+        },
+      );
+      r.screen({
+        id: "lease-detail",
+        type: "projectionDetail",
+        query: "app:query:lease:detail",
+        layout: {
+          sections: [
+            {
+              kind: "relatedList",
+              title: "Positions",
+              query: "app:query:lease:positions",
+              columns: ["id"],
+              toolbarActions: [
+                {
+                  kind: "navigate",
+                  id: "create",
+                  label: "Add position",
+                  screen: "position-create",
+                  params: { map: { leaseId: "ghost-id" } },
+                },
+              ],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /toolbarAction "create" params references unknown field "ghost-id"/,
+    );
+  });
+
+  test("relatedList toolbarAction visible/params present in the projectionDetail's own outputSchema does not throw", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("lease:detail", z.object({}), async () => ({ id: "1", status: "active" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        outputSchema: z.object({ id: z.string(), status: z.string() }),
+      });
+      r.queryHandler(
+        "lease:positions",
+        z.object({}),
+        async () => ({ rows: [], nextCursor: null }),
+        {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+          outputSchema: z.object({
+            rows: z.array(z.object({ id: z.string() })),
+            nextCursor: z.string().nullable(),
+          }),
+        },
+      );
+      r.screen({
+        id: "lease-detail",
+        type: "projectionDetail",
+        query: "app:query:lease:detail",
+        layout: {
+          sections: [
+            {
+              kind: "relatedList",
+              title: "Positions",
+              query: "app:query:lease:positions",
+              columns: ["id"],
+              toolbarActions: [
+                {
+                  kind: "navigate",
+                  id: "create",
+                  label: "Add position",
+                  screen: "position-create",
+                  visible: { field: "status", eq: "active" },
+                  params: { map: { leaseId: "id" } },
+                },
+              ],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
   test("projectionDetail header.title referencing an unknown field throws", () => {
     const feature = defineFeature("app", (r) => {
       r.queryHandler("tenant:detail", z.object({}), async () => ({ id: "1", name: "x" }), {

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

@@ -2403,6 +2403,10 @@ describe("boot-validator", () => {
       readonly sections?: ReadonlyArray<{
         readonly title: string;
         readonly fields: readonly string[];
+        readonly groups?: ReadonlyArray<{
+          readonly title: string;
+          readonly fields: readonly string[];
+        }>;
       }>;
       readonly redirect?: string | { readonly screen: string; readonly idFrom: string };
       readonly cancelTarget?: string | false;
@@ -2501,6 +2505,53 @@ describe("boot-validator", () => {
       ).toThrow(/layout references unknown field "ghost"/);
     });
 
+    test("section mit fields UND groups → Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature({
+            sections: [
+              {
+                title: "Approval",
+                fields: ["note"],
+                groups: [{ title: "Priority", fields: ["priority"] }],
+              },
+            ],
+          }),
+        ]),
+      ).toThrow(/declares both fields and groups/);
+    });
+
+    test("group referenziert unknown field → Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature({
+            sections: [
+              { title: "Approval", fields: [], groups: [{ title: "Priority", fields: ["ghost"] }] },
+            ],
+          }),
+        ]),
+      ).toThrow(/layout references unknown field "ghost"/);
+    });
+
+    test("valide groups → kein Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature({
+            sections: [
+              {
+                title: "Approval",
+                fields: [],
+                groups: [
+                  { title: "Basics", fields: ["note"] },
+                  { title: "Priority", fields: ["priority"] },
+                ],
+              },
+            ],
+          }),
+        ]),
+      ).not.toThrow();
+    });
+
     test("redirect → existing screen-id im selben feature → kein Throw", () => {
       expect(() =>
         validateBoot([makeFeature({ redirect: "after-form", extraScreens: ["after-form"] })]),

package/src/engine/__tests__/entity-create-caller-id.integration.test.ts

@@ -0,0 +1,87 @@
+// The schema lets a caller id through, but only a system identity gets it honored; HTTP users
+// can never present one (SYSTEM_ROLE is reserved), so both halves are pinned end to end here.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import {
+  createEntity,
+  createSystemUser,
+  createTextField,
+  defineEntityCreateHandler,
+  defineFeature,
+} from "../index";
+
+const thingEntity = createEntity({
+  table: "callerid_things",
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+  access: { write: { Admin: "all" } },
+});
+const CREATE_QN = "callerid:write:thing:create";
+
+const feature = defineFeature("callerid", (r) => {
+  r.entity("thing", thingEntity);
+  r.writeHandler(defineEntityCreateHandler("thing", thingEntity, { access: { roles: ["Admin"] } }));
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [feature] });
+  await unsafeCreateEntityTable(stack.db, thingEntity, "thing");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("entity create — caller-chosen id", () => {
+  test("system-identity caller: the chosen id is honored", async () => {
+    const chosenId = "00000000-0000-4000-8000-0000000000c1";
+    const systemUser = createSystemUser(admin.tenantId, ["Admin"]);
+    const result = await stack.http.writeOk<{ id: string }>(
+      CREATE_QN,
+      { label: "from a job", id: chosenId },
+      systemUser,
+    );
+    expect(result.id).toBe(chosenId);
+  });
+
+  test("system-identity caller retrying the same id → version_conflict, no duplicate row created", async () => {
+    const chosenId = "00000000-0000-4000-8000-0000000000c2";
+    const systemUser = createSystemUser(admin.tenantId, ["Admin"]);
+    await stack.http.writeOk<{ id: string }>(
+      CREATE_QN,
+      { label: "first attempt", id: chosenId },
+      systemUser,
+    );
+    const retry = await stack.http.writeErr(
+      CREATE_QN,
+      { label: "redelivered event", id: chosenId },
+      systemUser,
+    );
+    expect(retry.code).toBe("version_conflict");
+  });
+
+  test("ordinary end user: the payload id is ignored, a fresh id is minted", async () => {
+    const chosenId = "00000000-0000-4000-8000-0000000000c3";
+    const result = await stack.http.writeOk<{ id: string }>(
+      CREATE_QN,
+      { label: "from a browser", id: chosenId },
+      admin,
+    );
+    expect(result.id).not.toBe(chosenId);
+  });
+
+  test("malformed id → validation error, regardless of caller identity", async () => {
+    const systemUser = createSystemUser(admin.tenantId, ["Admin"]);
+    const err = await stack.http.writeErr(
+      CREATE_QN,
+      { label: "bad id", id: "not-a-uuid" },
+      systemUser,
+    );
+    expect(err.code).toBe("validation_error");
+  });
+});

package/src/engine/__tests__/entity-handlers-escape-hatch.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import {
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  isDeprecatedCrossTenantHandler,
+} from "../entity-handlers";
+import { createEntity, createTextField } from "../factories";
+
+const thingEntity = createEntity({
+  table: "escape_hatch_things",
+  fields: {
+    label: createTextField({ required: true, personal: false, reason: "test_fixture" }),
+  },
+});
+
+const sysadminAccess = { access: { roles: ["SystemAdmin"] } } as const;
+
+describe("entity convention handlers: escapeHatch option", () => {
+  test("throws when both escapeHatch and the deprecated crossTenant are set", () => {
+    expect(() =>
+      defineEntityUpdateHandler("thing", thingEntity, {
+        ...sysadminAccess,
+        escapeHatch: { reason: "operator write" },
+        crossTenant: true,
+      }),
+    ).toThrow(/declare either escapeHatch or the deprecated crossTenant, not both/);
+  });
+
+  test("throws when escapeHatch.reason is empty", () => {
+    expect(() =>
+      defineEntityUpdateHandler("thing", thingEntity, {
+        ...sysadminAccess,
+        escapeHatch: { reason: "" },
+      }),
+    ).toThrow(/non-empty reason/);
+  });
+
+  test("throws when escapeHatch.reason is whitespace-only", () => {
+    expect(() =>
+      defineEntityListHandler("thing", thingEntity, {
+        ...sysadminAccess,
+        escapeHatch: { reason: "   " },
+      }),
+    ).toThrow(/non-empty reason/);
+  });
+
+  test("WriteHandlerDef from an escapeHatch update handler carries no escapeHatch field", () => {
+    const def = defineEntityUpdateHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      escapeHatch: { reason: "operator cross-tenant write" },
+    });
+    expect("escapeHatch" in def).toBe(false);
+  });
+
+  test("QueryHandlerDef from an escapeHatch list handler carries no escapeHatch field", () => {
+    const def = defineEntityListHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      escapeHatch: { reason: "operator cross-tenant list" },
+    });
+    expect("escapeHatch" in def).toBe(false);
+  });
+
+  test("WriteHandlerDef from a legacy crossTenant handler also carries no escapeHatch field", () => {
+    const def = defineEntityUpdateHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      crossTenant: true,
+    });
+    expect("escapeHatch" in def).toBe(false);
+  });
+
+  test("isDeprecatedCrossTenantHandler is true only for handlers built with crossTenant: true", () => {
+    const legacyWrite = defineEntityUpdateHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      crossTenant: true,
+    });
+    const escapeHatchWrite = defineEntityUpdateHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      escapeHatch: { reason: "operator cross-tenant write" },
+    });
+    const plainWrite = defineEntityUpdateHandler("thing", thingEntity, sysadminAccess);
+    const legacyList = defineEntityListHandler("thing", thingEntity, {
+      ...sysadminAccess,
+      crossTenant: true,
+    });
+
+    expect(isDeprecatedCrossTenantHandler(legacyWrite.handler)).toBe(true);
+    expect(isDeprecatedCrossTenantHandler(legacyList.handler)).toBe(true);
+    expect(isDeprecatedCrossTenantHandler(escapeHatchWrite.handler)).toBe(false);
+    expect(isDeprecatedCrossTenantHandler(plainWrite.handler)).toBe(false);
+  });
+});

package/src/engine/__tests__/entity-handlers.test.ts

@@ -72,6 +72,12 @@ describe("defineEntityWriteHandler", () => {
     expect(def.schema.safeParse({}).success).toBe(false);
   });
 
+  test("create: schema accepts an optional caller-chosen id, well-formed UUID only", () => {
+    const def = defineEntityCreateHandler("note", noteEntity, adminAccess);
+    expect(def.schema.safeParse({ title: "x", id: VALID_UUID }).success).toBe(true);
+    expect(def.schema.safeParse({ title: "x", id: "not-a-uuid" }).success).toBe(false);
+  });
+
   test("update: schema requires id + version + changes", () => {
     const def = defineEntityUpdateHandler("note", noteEntity, adminAccess);
     expect(
@@ -242,6 +248,28 @@ describe("defineProjectionQueryHandler", () => {
       defineProjectionQueryHandler("revenue:list", "showcase:projection:customer-revenue"),
     ).toThrow();
   });
+
+  test("escapeHatch is forwarded to the returned def", () => {
+    const def = defineProjectionQueryHandler(
+      "revenue:list",
+      "showcase:projection:customer-revenue",
+      {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        unsafeAllTenants: true,
+        escapeHatch: { reason: "fw#2913 test — cross-tenant revenue analytics" },
+      },
+    );
+    expect(def.escapeHatch).toEqual({ reason: "fw#2913 test — cross-tenant revenue analytics" });
+  });
+
+  test("escapeHatch is omitted from the def when not declared", () => {
+    const def = defineProjectionQueryHandler(
+      "revenue:list",
+      "showcase:projection:customer-revenue",
+      { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+    );
+    expect(def.escapeHatch).toBeUndefined();
+  });
 });
 
 // Verb-spezifische Wrappers — sind dünne Convenience-Layers über

package/src/engine/__tests__/entity-restore-tenant-isolation.integration.test.ts

@@ -3,11 +3,12 @@
 // a soft-deleted row belonging to another tenant and got the decrypted row back
 // in the response. delete() never had that hole (it goes through the
 // tenant-scoped loadById). These tests pin both halves: the tenant-scoped
-// handler must not reach across, and the crossTenant handler must still be able
-// to.
+// handler must not reach across, and the crossTenant/escapeHatch handlers
+// must still be able to.
 //
-// Two stacks on the SAME Postgres database: one registers the restore handler
-// without `crossTenant`, the other with it — a clean A/B on the one flag.
+// Three stacks on the SAME Postgres database: one registers the restore
+// handler without `crossTenant`/`escapeHatch`, one with the deprecated
+// `crossTenant: true`, one with `escapeHatch: { reason }`.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { selectMany } from "../../db/query";
@@ -39,7 +40,9 @@ const thingEntity = createEntity({
 });
 const thingTable = buildEntityTable("thing", thingEntity);
 
-function buildFeature(crossTenant: boolean) {
+const ESCAPE_HATCH_REASON = "fw#2915 integration test — operator restores a foreign tenant's row";
+
+function buildFeature(crossTenant: boolean, escapeHatch?: boolean) {
   return defineFeature("ctrestore", (r) => {
     r.entity("thing", thingEntity);
     r.writeHandler(
@@ -56,6 +59,7 @@ function buildFeature(crossTenant: boolean) {
       defineEntityRestoreHandler("thing", thingEntity, {
         access: { roles: ["Admin", "SystemAdmin"] },
         ...(crossTenant && { crossTenant: true }),
+        ...(escapeHatch && { escapeHatch: { reason: ESCAPE_HATCH_REASON } }),
       }),
     );
   });
@@ -65,6 +69,7 @@ const dbName = `kumiko_test_ctrestore_${crypto.randomUUID().replace(/-/g, "").sl
 
 let tenantScopedStack: TestStack;
 let crossTenantStack: TestStack;
+let escapeHatchStack: TestStack;
 
 beforeAll(async () => {
   tenantScopedStack = await setupTestStack({ features: [buildFeature(false)], dbName });
@@ -74,9 +79,15 @@ beforeAll(async () => {
     dbName,
     persistentDb: true,
   });
+  escapeHatchStack = await setupTestStack({
+    features: [buildFeature(false, true)],
+    dbName,
+    persistentDb: true,
+  });
 });
 
 afterAll(async () => {
+  await escapeHatchStack.cleanup();
   await crossTenantStack.cleanup();
   await tenantScopedStack.cleanup();
 });
@@ -140,4 +151,18 @@ describe("entity restore: tenant isolation", () => {
     expect(rows[0]?.["isDeleted"]).toBe(false);
     expect(rows[0]?.["tenantId"]).toBe(testTenantId(2));
   });
+
+  test("escapeHatch restore still reaches a foreign tenant's row", async () => {
+    const id = await createDeletedThing("escape-hatch-restore");
+
+    await escapeHatchStack.http.writeOk(
+      "ctrestore:write:thing:restore",
+      { id },
+      TestUsers.systemAdmin,
+    );
+
+    const rows = await selectMany(tenantScopedStack.db, thingTable, { id });
+    expect(rows[0]?.["isDeleted"]).toBe(false);
+    expect(rows[0]?.["tenantId"]).toBe(testTenantId(2));
+  });
 });