@cosmicdrift/kumiko-framework 0.204.1 → 0.206.0

package/package.json

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

package/src/db/index.ts

@@ -108,6 +108,7 @@ export {
   isUniqueViolation,
   type PgErrorInfo,
 } from "./pg-error";
+export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock";
 export type { SelectOptions, WhereObject, WhereValue } from "./query-api";
 export {
   asRawClient,

package/src/db/queries/advisory-lock.ts

@@ -0,0 +1,11 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+/** pg_advisory_xact_lock keyed on namespace+key hash — xact-scoped, auto-released at commit/rollback. */
+export async function acquireNamespacedAdvisoryLock(
+  db: AnyDb,
+  namespace: number,
+  key: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(`SELECT pg_advisory_xact_lock($1, hashtext($2))`, [namespace, key]);
+}

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

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { z } from "zod";
 import { requiredKeysFromScreen } from "../../i18n/required-surface-keys";
 import { validateBoot } from "../boot-validator";
 import { defineFeature } from "../define-feature";
@@ -17,6 +18,12 @@ function dashboardFeature(
   filter?: DashboardScreenDefinition["filter"],
 ) {
   return defineFeature("demo", (r) => {
+    r.queryHandler("incident:open-count", z.object({}), async () => ({ count: 3 }), {
+      access: { openToAll: true },
+    });
+    r.queryHandler("incident:latest", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+      access: { openToAll: true },
+    });
     r.screen({
       id: "overview",
       type: "dashboard",

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

@@ -188,4 +188,54 @@ describe("validateBoot — projectionList screens", () => {
     });
     expect(() => validateBoot([feature])).toThrow(/paginated is derived/);
   });
+
+  // fw#2164 Nebenbefund: the "at most one rowClick:true" cap (already
+  // enforced for entityList) didn't run for projectionList — a boot-time
+  // gap, not a rendering one (the renderer only wires the first match, see
+  // ProjectionListBody), but two conflicting rowClick actions on the same
+  // screen should still fail loud instead of silently picking one.
+  describe("projectionList rowAction rowClick", () => {
+    function makeFeature(rowClickCount: number) {
+      return defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({}),
+          async () => ({ rows: [], nextCursor: null }),
+          {
+            access: { openToAll: true },
+          },
+        );
+        r.screen({ id: "schedule-detail", type: "custom", renderer: { react: "stub" } });
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["description"],
+          rowActions: Array.from({ length: rowClickCount }, (_, i) => ({
+            kind: "navigate" as const,
+            id: `open-${i}`,
+            label: "actions.open",
+            screen: "schedule-detail",
+            rowClick: true,
+          })),
+        });
+        r.translations({
+          keys: {
+            "screen:schedule-list.title": { de: "Liste", en: "List" },
+            "screen:schedule-detail.title": { de: "Detail", en: "Detail" },
+          },
+        });
+      });
+    }
+
+    test("one rowClick navigate action passes boot", () => {
+      expect(() => validateBoot([makeFeature(1)])).not.toThrow();
+    });
+
+    test("more than one rowClick action per list is rejected", () => {
+      expect(() => validateBoot([makeFeature(2)])).toThrow(
+        /at most one may fire on a row-body click/i,
+      );
+    });
+  });
 });

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

@@ -0,0 +1,151 @@
+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 { defineFeature } from "../define-feature";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+// fw#2178: a screen's `query` (or a relatedList/dashboard-panel query) must
+// resolve to a query-handler actually registered via r.queryHandler(...) —
+// mirrors the existing rowAction/toolbarAction handler-existence check.
+describe("validateBoot — query QN refs (fw#2178)", () => {
+  test("projectionList with a dead query QN throws (a)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:ghost",
+        columns: ["description"],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /query "ledger:query:schedule:ghost" is not a registered query-handler/,
+    );
+  });
+
+  // (b) targets projectionDetail rather than entityEdit: screens.ts
+  // unconditionally rejects a relatedList section on entityEdit/actionForm/
+  // configEdit with its own "projectionDetail-only primitive" error
+  // (fw#2166, screens.ts:955/:621/:506) — that fires first in the per-feature
+  // loop, before validateQueryRefs ever runs, so a dead QN there can't reach
+  // this check. projectionDetail is the one screen type where relatedList is
+  // actually reachable.
+  test("projectionDetail relatedList section with a dead query QN throws (b)", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("rent:detail", z.object({}), async () => ({ description: "x" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: {
+          sections: [
+            {
+              kind: "relatedList",
+              title: "Payments",
+              query: "app:query:rent:payments-ghost",
+              columns: ["amount"],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /relatedList section "Payments" query "app:query:rent:payments-ghost" is not a registered query-handler/,
+    );
+  });
+
+  test("dashboard stat-group child with a dead query QN throws (c)", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.screen({
+        id: "overview",
+        type: "dashboard",
+        panels: [
+          {
+            kind: "stat-group",
+            id: "net-worth",
+            label: "demo:dashboard:group:net-worth",
+            stats: [
+              {
+                kind: "stat",
+                id: "assets",
+                label: "demo:dashboard:panel:assets",
+                query: "demo:query:net-worth:assets-ghost",
+                valueField: "value",
+              },
+            ],
+          },
+        ],
+      });
+      r.translations({
+        keys: {
+          "demo:dashboard:group:net-worth": { de: "Net Worth", en: "Net Worth" },
+          "demo:dashboard:panel:assets": { de: "Assets", en: "Assets" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /stat-group "net-worth" child "assets" query "demo:query:net-worth:assets-ghost" is not a registered query-handler/,
+    );
+  });
+
+  test("dashboard filter optionsQuery with a dead query QN throws", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.queryHandler("open-count", z.object({}), async () => ({ value: "0" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "overview",
+        type: "dashboard",
+        filter: {
+          id: "region",
+          label: "demo:dashboard:filter:region",
+          kind: "select",
+          optionsQuery: "demo:query:region:options-ghost",
+        },
+        panels: [
+          {
+            kind: "stat",
+            id: "open",
+            label: "demo:dashboard:panel:open",
+            query: "demo:query:open-count",
+            valueField: "value",
+          },
+        ],
+      });
+      r.translations({
+        keys: {
+          "demo:dashboard:panel:open": { de: "Offen", en: "Open" },
+          "demo:dashboard:filter:region": { de: "Region", en: "Region" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /filter "region" query "demo:query:region:options-ghost" is not a registered query-handler/,
+    );
+  });
+
+  test("a screen referencing a query registered by a different mounted feature does not throw (d)", () => {
+    const provider = defineFeature("catalog", (r) => {
+      r.queryHandler("items:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+    });
+    const consumer = defineFeature("storefront", (r) => {
+      r.screen({
+        id: "items",
+        type: "projectionList",
+        query: "catalog:query:items:list",
+        columns: ["name"],
+      });
+      r.translations({
+        keys: { "screen:items.title": { de: "Artikel", en: "Items" } },
+      });
+    });
+    expect(() => validateBoot([provider, consumer])).not.toThrow();
+  });
+});

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

@@ -3838,6 +3838,9 @@ describe("boot-validator — config key backing × scope", () => {
   test("projectionList rowAction: navigate with params to an entityEdit-create target (no entityId) → no throw", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.queryHandler("products", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
       r.screen({
         id: "product-projection",
         type: "projectionList",

package/src/engine/__tests__/projection-detail-actions.test.ts

@@ -41,6 +41,9 @@ describe("validateBoot — projectionDetail actions (fw#2166)", () => {
 
   test("valid navigate + writeHandler actions boot cleanly", () => {
     const feature = defineFeature("app", (r) => {
+      r.queryHandler("rent:detail", z.object({}), async () => ({ description: "x" }), {
+        access: { openToAll: true },
+      });
       r.writeHandler(
         "archive",
         z.object({ id: z.string() }),

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

@@ -214,6 +214,12 @@ describe("r.screen() — registration", () => {
   test("validateBoot accepts a relatedList rowClick with a detailFor screen in another feature (fw#2166)", () => {
     const features = [
       defineFeature("app", (r) => {
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+          access: { openToAll: true },
+        });
         r.screen({
           id: "x",
           type: "projectionDetail",
@@ -269,6 +275,12 @@ describe("r.screen() — registration", () => {
   test("validateBoot accepts a valid relatedList section without rowClick (fw#2166)", () => {
     const features = [
       defineFeature("app", (r) => {
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+          access: { openToAll: true },
+        });
         r.screen({
           id: "x",
           type: "projectionDetail",

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

@@ -46,6 +46,7 @@ import {
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
 import { validateProjectionListScreens } from "./projection-list-screens";
+import { validateQueryRefs } from "./query-refs";
 import {
   collectScreenQns,
   collectScreensByShortId,
@@ -211,6 +212,11 @@ export function validateBoot(
   validateI18nSurfaceKeys(features);
   validateEntityListScreens(features);
   validateDetailForScreens(features, featureMap);
+  // Must run before validateProjectionListScreens: an unresolvable query
+  // there is silently treated as "capability absent" and surfaces as a
+  // misleading "no search parameter in its Zod schema" error instead of
+  // the clear typo message below.
+  validateQueryRefs(features);
   validateProjectionListScreens(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);

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

@@ -9,7 +9,9 @@ import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens";
 // entity, so sharing the function would mean threading a discriminated
 // union through every entity-bound helper it calls.
 
-function buildQueryHandlerMap(
+// Exported for query-refs.ts (fw#2178) — one source for the QN-derivation
+// logic instead of duplicating it in both boot-validators.
+export function buildQueryHandlerMap(
   features: readonly FeatureDefinition[],
 ): ReadonlyMap<string, QueryHandlerDef> {
   const out = new Map<string, QueryHandlerDef>();

package/src/engine/boot-validator/query-refs.ts

@@ -0,0 +1,129 @@
+import type {
+  DashboardScreenDefinition,
+  EditLayout,
+  FeatureDefinition,
+  QueryHandlerDef,
+  ScreenDefinition,
+} from "../types";
+import { buildQueryHandlerMap } from "./projection-list-screens";
+
+const NOT_REGISTERED_SUFFIX =
+  "is not a registered query-handler. Check the QN spelling (expected " +
+  '"<feature>:query:<short>") and that the handler is declared via r.queryHandler(...).';
+
+function isNonEmptyQueryString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function checkQueryRef(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  query: string,
+  buildPrefix: () => string,
+): void {
+  // skip: empty/non-string queries get their own message in screens.ts;
+  // a registered query has nothing left to check.
+  if (!isNonEmptyQueryString(query) || queryHandlers.has(query)) return;
+  throw new Error(`${buildPrefix()} query "${query}" ${NOT_REGISTERED_SUFFIX}`);
+}
+
+// relatedList is currently only reachable on projectionDetail — screens.ts
+// rejects it outright on entityEdit/actionForm/configEdit (fw#2166). Walking
+// the shared EditLayout uniformly here (instead of excluding those three
+// types) keeps this collector correct if that restriction is ever lifted.
+function checkEditLayoutQueryRefs(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  featureName: string,
+  screenId: string,
+  screenType: string,
+  layout: EditLayout,
+): void {
+  for (const section of layout.sections) {
+    if (section.kind !== "relatedList") continue;
+    checkQueryRef(
+      queryHandlers,
+      section.query,
+      () =>
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList section "${section.title}"`,
+    );
+  }
+}
+
+function checkDashboardQueryRefs(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  featureName: string,
+  screenId: string,
+  screen: DashboardScreenDefinition,
+): void {
+  for (const panel of screen.panels) {
+    if (panel.kind === "custom") continue;
+    if (panel.kind === "stat-group") {
+      for (const stat of panel.stats) {
+        checkQueryRef(
+          queryHandlers,
+          stat.query,
+          () =>
+            `[Feature ${featureName}] Screen "${screenId}" (dashboard) stat-group "${panel.id}" child "${stat.id}"`,
+        );
+      }
+      continue;
+    }
+    checkQueryRef(
+      queryHandlers,
+      panel.query,
+      () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`,
+    );
+  }
+  if (screen.filter?.optionsQuery !== undefined) {
+    checkQueryRef(
+      queryHandlers,
+      screen.filter.optionsQuery,
+      () =>
+        `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter "${screen.filter?.id}"`,
+    );
+  }
+}
+
+function checkScreenQueryRefs(
+  queryHandlers: ReadonlyMap<string, QueryHandlerDef>,
+  featureName: string,
+  screenId: string,
+  screen: ScreenDefinition,
+): void {
+  if (screen.type === "projectionList") {
+    checkQueryRef(
+      queryHandlers,
+      screen.query,
+      () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`,
+    );
+  } else if (screen.type === "projectionDetail") {
+    checkQueryRef(
+      queryHandlers,
+      screen.query,
+      () => `[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`,
+    );
+    checkEditLayoutQueryRefs(
+      queryHandlers,
+      featureName,
+      screenId,
+      "projectionDetail",
+      screen.layout,
+    );
+  } else if (
+    screen.type === "entityEdit" ||
+    screen.type === "actionForm" ||
+    screen.type === "configEdit"
+  ) {
+    checkEditLayoutQueryRefs(queryHandlers, featureName, screenId, screen.type, screen.layout);
+  } else if (screen.type === "dashboard") {
+    checkDashboardQueryRefs(queryHandlers, featureName, screenId, screen);
+  }
+}
+
+export function validateQueryRefs(features: readonly FeatureDefinition[]): void {
+  const queryHandlers = buildQueryHandlerMap(features);
+  for (const feature of features) {
+    for (const [screenId, screen] of Object.entries(feature.screens)) {
+      checkScreenQueryRefs(queryHandlers, feature.name, screenId, screen);
+    }
+  }
+}

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

@@ -25,6 +25,24 @@ import type {
   ToolbarAction,
 } from "../types/screen";
 
+// entityList and projectionList both allow a rowAction to double as the
+// row-body click target (rowClick: true, fw#1708/#2164) — at most one per
+// screen, or the renderer can't tell which one should fire.
+function validateAtMostOneRowClick(
+  featureName: string,
+  screenId: string,
+  screenType: "entityList" | "projectionList",
+  rowActions: readonly RowAction[],
+): void {
+  const rowClickActions = rowActions.filter((a) => a.kind === "navigate" && a.rowClick === true);
+  if (rowClickActions.length > 1) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) has ${rowClickActions.length} ` +
+        "rowActions marked rowClick:true — at most one may fire on a row-body click.",
+    );
+  }
+}
+
 // A field type in NO_WIDGET_FIELD_TYPES renders read-only on the auto-wired
 // entityEdit path (#1925) — a required field the user can never fill would
 // block every save. Only the statically-resolvable case is caught here: a
@@ -354,6 +372,7 @@ export function validateScreens(
             );
           }
         }
+        validateAtMostOneRowClick(feature.name, screenId, "projectionList", screen.rowActions);
       }
       continue;
     }
@@ -889,15 +908,7 @@ export function validateScreens(
             rowMeta,
           );
         }
-        const rowClickActions = screen.rowActions.filter(
-          (a) => a.kind === "navigate" && a.rowClick === true,
-        );
-        if (rowClickActions.length > 1) {
-          throw new Error(
-            `[Feature ${feature.name}] Screen "${screenId}" (entityList) has ${rowClickActions.length} ` +
-              "rowActions marked rowClick:true — at most one may fire on a row-body click.",
-          );
-        }
+        validateAtMostOneRowClick(feature.name, screenId, "entityList", screen.rowActions);
       }
       // Tier 2.7e-2: toolbarActions — analog zu rowActions, aber bisher
       // ohne Validator. Typo'd navigate-targets und unregistrierte