@cosmicdrift/kumiko-framework 0.203.0 → 0.204.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.203.0",
+  "version": "0.204.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>",
@@ -190,7 +190,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.203.0",
+    "@cosmicdrift/kumiko-types": "0.204.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -206,7 +206,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.203.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.204.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/sql-inventory.ts

@@ -48,7 +48,22 @@ export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
   /\/packages\/framework\/src\/db\/sql-inventory\.ts$/,
   /\/packages\/framework\/src\/bun-db\/query\.ts$/,
   /\/packages\/framework\/src\/testing\//,
-  /\/packages\/bundled-features\/src\/[^/]+\/db\/queries\//,
+  // ponytail: explicit enumeration — blanket regex auto-allowed any new .unsafe()
+  /\/bundled-features\/src\/billing-foundation\/db\/queries\/subscription-projection\.ts$/,
+  /\/bundled-features\/src\/config\/db\/queries\/resolver\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/field-access\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/projection\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/quota\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/retention\.ts$/,
+  /\/bundled-features\/src\/custom-fields\/db\/queries\/user-data-rights\.ts$/,
+  /\/bundled-features\/src\/delivery\/db\/queries\/preferences\.ts$/,
+  /\/bundled-features\/src\/form-draft\/db\/queries\/cleanup\.ts$/,
+  /\/bundled-features\/src\/form-draft\/db\/queries\/draft-count\.ts$/,
+  /\/bundled-features\/src\/form-draft\/db\/queries\/owned-file-refs\.ts$/,
+  /\/bundled-features\/src\/inbound-mail-foundation\/db\/queries\/inbound-projections\.ts$/,
+  /\/bundled-features\/src\/secrets\/db\/queries\/read\.ts$/,
+  /\/bundled-features\/src\/sessions\/db\/queries\/cleanup\.ts$/,
+  /\/bundled-features\/src\/user\/db\/queries\/stream-tenant-backfill\.ts$/,
   /\/packages\/framework\/src\/engine\/steps\/unsafe-projection-/,
   /\/samples\/(apps|recipes)\/[^/]+\/src\/db\/queries\//,
   /\/bin\/commands\//,

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

@@ -240,6 +240,30 @@ describe("validateBoot — action wiring (no function values)", () => {
     expect(() => validateBoot([feature])).toThrow(/column "amount" renderer is a function/);
   });
 
+  test("projectionDetail relatedList column renderer as function → Throw (fw#2166)", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.screen({
+        id: "order-detail",
+        type: "projectionDetail",
+        query: "shop:query:order:detail",
+        layout: {
+          sections: [
+            {
+              kind: "relatedList",
+              title: "Payments",
+              query: "shop:query:order:payments",
+              columns: [
+                // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+                { field: "amount", renderer: ((v: unknown) => String(v)) as any },
+              ],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/column "amount" renderer is a function/);
+  });
+
   test("projectionList rowAction payload as function → Throw", () => {
     const feature = defineFeature("shop", (r) => {
       r.screen({

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

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "bun:test";
+import { z } from "zod";
 import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
 import { validateBoot as validateBootRaw } from "../boot-validator";
+import { createTenantConfig } from "../config-helpers";
 import { defineFeature } from "../define-feature";
 import { createDerivedField, createEntity, createTextField } from "../factories";
 import { createRegistry } from "../registry";
@@ -165,6 +167,196 @@ describe("r.screen() — registration", () => {
     expect(() => validateBoot(features)).toThrow(/extension section/i);
   });
 
+  test("validateBoot rejects a projectionDetail relatedList section with an empty query (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [{ kind: "relatedList", title: "s", query: "", columns: ["name"] }],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /Screen "x".*relatedList.*empty or non-string query/,
+    );
+  });
+
+  test("validateBoot rejects a relatedList rowClick with no matching detailFor screen (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowClick: { entity: "invoice" },
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /Add detailFor: "invoice" to the screen that shows it\./,
+    );
+  });
+
+  test("validateBoot accepts a relatedList rowClick with a detailFor screen in another feature (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowClick: { entity: "invoice" },
+              },
+            ],
+          },
+        });
+      }),
+      defineFeature("billing", (r) => {
+        r.entity(
+          "invoice",
+          createEntity({ table: "invoices", fields: { name: createTextField() } }),
+        );
+        r.screen({
+          id: "invoice-detail",
+          type: "custom",
+          renderer: { react: { __component: "stub" } },
+          detailFor: "invoice",
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a relatedList section in a wizard layout (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            mode: "wizard",
+            sections: [
+              { kind: "relatedList", title: "s", query: "app:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/relatedList.*wizard layout/);
+  });
+
+  test("validateBoot accepts a valid relatedList section without rowClick (fw#2166)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              { kind: "relatedList", title: "s", query: "app:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a relatedList section on entityEdit (fw#2166)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.entity("product", productEntity());
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: {
+            sections: [
+              { kind: "relatedList", title: "s", query: "shop:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(entityEdit\) relatedList section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a relatedList section on configEdit (fw#2166)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.config({
+          keys: { "site-name": createTenantConfig("text", { default: "" }) },
+        });
+        r.screen({
+          id: "settings",
+          type: "configEdit",
+          scope: "tenant",
+          configKeys: { siteName: "shop:config:site-name" },
+          fields: { siteName: { type: "text" } } as never,
+          layout: {
+            sections: [
+              { kind: "relatedList", title: "s", query: "shop:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(configEdit\) relatedList section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a relatedList section on actionForm (fw#2166)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.writeHandler(
+          "restock",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "restock",
+          type: "actionForm",
+          handler: "shop:write:restock",
+          fields: { qty: { type: "number" } } as never,
+          layout: {
+            sections: [
+              { kind: "relatedList", title: "s", query: "shop:query:foo:list", columns: ["name"] },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(actionForm\) relatedList section "s".*projectionDetail-only/,
+    );
+  });
+
   test("stores an entityEdit screen with sections + conditional fields", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

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

@@ -1,4 +1,4 @@
-import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
+import { isFieldsEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
 import type {
   EditFieldSpec,
   EditLayout,
@@ -112,7 +112,13 @@ function validateEditLayoutNoFunctions(
   layout: EditLayout,
 ): void {
   for (const section of layout.sections) {
-    if (isExtensionEditSection(section)) continue;
+    // relatedList carries `columns` instead of `fields` — route it through
+    // the same column check entityList/projectionList top-level columns use.
+    if (section.kind === "relatedList") {
+      validateColumnsNoFunctions(featureName, screenId, screenType, section.columns);
+      continue;
+    }
+    if (!isFieldsEditSection(section)) continue;
     for (const fieldSpec of section.fields) {
       validateEditFieldNoFunctions(featureName, screenId, screenType, fieldSpec);
     }

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

@@ -381,6 +381,35 @@ export function validateScreens(
               `section to persist against.`,
           );
         }
+        if (section.kind === "relatedList") {
+          if (!section.query || typeof section.query !== "string") {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(relatedList) has empty or non-string query.`,
+            );
+          }
+          if (screen.layout.mode === "wizard") {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `is kind "relatedList" in a wizard layout — a read-only list is not supported in a ` +
+                `stepped form. Remove mode: "wizard" or drop the relatedList section.`,
+            );
+          }
+          if (section.rowClick !== undefined) {
+            const targetEntity = section.rowClick.entity;
+            const hasDetailScreen = [...featureMap.values()].some((f) =>
+              Object.values(f.screens).some((s) => s.detailFor === targetEntity),
+            );
+            if (!hasDetailScreen) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(relatedList) rowClick targets entity "${targetEntity}", but no screen declares ` +
+                  `detailFor: "${targetEntity}". Add detailFor: "${targetEntity}" to the screen that shows it.`,
+              );
+            }
+          }
+          continue;
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has a section "${section.title}" ` +
@@ -474,6 +503,13 @@ export function validateScreens(
           }
           continue;
         }
+        if (section.kind === "relatedList") {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (configEdit) relatedList section ` +
+              `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
+              `primitive (fw#2166).`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (configEdit) has a section "${section.title}" ` +
@@ -582,6 +618,13 @@ export function validateScreens(
           }
           continue;
         }
+        if (section.kind === "relatedList") {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) relatedList section ` +
+              `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
+              `primitive (fw#2166).`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has a section "${section.title}" ` +
@@ -909,6 +952,13 @@ export function validateScreens(
           }
           continue;
         }
+        if (section.kind === "relatedList") {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) relatedList section ` +
+              `"${section.title}" is not supported — relatedList is a projectionDetail-only ` +
+              `primitive (fw#2166).`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) has a section "${section.title}" ` +

package/src/engine/index.ts

@@ -227,7 +227,12 @@ export { runsInLane } from "./run-in";
 export type { StepListOutcome } from "./run-pipeline";
 export { runPipeline, runStepList } from "./run-pipeline";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-builder";
-export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./screen-helpers";
+export {
+  isExtensionEditSection,
+  isFieldsEditSection,
+  normalizeEditField,
+  normalizeListColumn,
+} from "./screen-helpers";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
 export {

package/src/engine/screen-helpers.ts

@@ -1,6 +1,7 @@
 import type {
   EditExtensionSection,
   EditFieldSpec,
+  EditFieldsSection,
   EditSectionSpec,
   FieldCondition,
   FormatSpec,
@@ -11,6 +12,10 @@ export function isExtensionEditSection(section: EditSectionSpec): section is Edi
   return section.kind === "extension";
 }
 
+export function isFieldsEditSection(section: EditSectionSpec): section is EditFieldsSection {
+  return section.kind === undefined || section.kind === "fields";
+}
+
 // Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
 // authors who branch on the three FieldRenderer variants without manual
 // "format" in renderer checks.

package/src/i18n/required-surface-keys.ts

@@ -153,6 +153,7 @@ export function requiredKeysFromScreen(
           pushKey(out, section.title);
           continue;
         }
+        if (section.kind === "relatedList") continue; // rejected at boot, unreachable here
         pushKey(out, section.title);
         for (const f of section.fields) {
           const fieldName = editFieldName(f);
@@ -174,6 +175,7 @@ export function requiredKeysFromScreen(
           pushKey(out, section.title);
           continue;
         }
+        if (section.kind === "relatedList") continue; // rejected at boot, unreachable here
         pushKey(out, section.title);
         for (const f of section.fields) {
           const fieldName = editFieldName(f);
@@ -195,6 +197,7 @@ export function requiredKeysFromScreen(
           pushKey(out, section.title);
           continue;
         }
+        if (section.kind === "relatedList") continue; // rejected at boot, unreachable here
         pushKey(out, section.title);
         for (const f of section.fields) {
           const fieldName = editFieldName(f);
@@ -209,6 +212,14 @@ export function requiredKeysFromScreen(
       const detail = screen as ProjectionDetailScreenDefinition;
       for (const section of detail.layout.sections) {
         if (isExtensionEditSection(section)) continue; // rejected at boot, unreachable here
+        if (section.kind === "relatedList") {
+          pushKey(out, section.title);
+          for (const col of section.columns) {
+            const normalized = normalizeListColumn(col);
+            if (normalized.label !== undefined) pushKey(out, normalized.label);
+          }
+          continue;
+        }
         pushKey(out, section.title);
         for (const f of section.fields) {
           const fieldName = editFieldName(f);

package/src/testing/e2e-generator.ts

@@ -30,7 +30,7 @@ import {
   type EntityEditScreenDefinition,
   type EntityListScreenDefinition,
   type FieldDefinition,
-  isExtensionEditSection,
+  isFieldsEditSection,
   normalizeEditField,
   normalizeListColumn,
   parseQn,
@@ -243,7 +243,7 @@ function collectRequiredEditFields(
 ): string[] {
   const out: string[] = [];
   for (const section of screen.layout.sections) {
-    if (isExtensionEditSection(section)) continue;
+    if (!isFieldsEditSection(section)) continue;
     for (const rawField of section.fields) {
       const { field } = normalizeEditField(rawField);
       const def = entity.fields[field];
@@ -281,7 +281,7 @@ function buildEditFillOps(
   // form; Felder ohne Fixture-Wert (file/image/…) werden übersprungen.
   const ops: EditFillOp[] = [];
   for (const section of screen.layout.sections) {
-    if (isExtensionEditSection(section)) continue;
+    if (!isFieldsEditSection(section)) continue;
     for (const raw of section.fields) {
       const { field } = normalizeEditField(raw);
       const def = entity.fields[field];
@@ -329,7 +329,7 @@ function pickIdentifyingForEdit(
     : undefined;
 
   for (const section of editScreen.layout.sections) {
-    if (isExtensionEditSection(section)) continue;
+    if (!isFieldsEditSection(section)) continue;
     for (const rawField of section.fields) {
       const { field } = normalizeEditField(rawField);
       if (entity.fields[field]?.type !== "text") continue;

package/src/ui-types/index.ts

@@ -28,6 +28,7 @@ export { parseRefTarget } from "../engine/parse-ref-target";
 export {
   evalFieldCondition,
   isExtensionEditSection,
+  isFieldsEditSection,
   isFormatSpec,
   normalizeEditField,
   normalizeListColumn,
@@ -71,6 +72,7 @@ export type {
   EditFieldSpec,
   EditFieldsSection,
   EditLayout,
+  EditRelatedListSection,
   EditSectionSpec,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,