@cosmicdrift/kumiko-framework 0.309.0 → 0.311.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.309.0",
+  "version": "0.311.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>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.309.0",
-    "@cosmicdrift/kumiko-types": "0.309.0",
+    "@cosmicdrift/kumiko-http": "0.311.0",
+    "@cosmicdrift/kumiko-types": "0.311.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.309.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.311.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.310.0",
+    "type": "improvement",
+    "title": "Boot validator checks the target tab of navigate actions",
+    "detail": "A navigate action with `tab` fails boot when its target is not a\nprojectionDetail with layout.mode \"tabs\" or has no section with that id.\nThe check covers list rowActions, relatedList rowActions, screen actions,\nsection actions and relatedList emptyState actions."
+  },
   {
     "version": "0.309.0",
     "type": "fix",

package/src/engine/__tests__/row-action-navigate-tab.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+function buildFeature(options: {
+  readonly detailTabs: boolean;
+  readonly tab: string;
+  readonly via: "entityEditSection" | "entityListRowAction";
+}) {
+  return defineFeature("app", (r) => {
+    r.entity(
+      "vehicle",
+      createEntity({
+        fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+      }),
+    );
+    r.queryHandler("vehicle:detail", z.object({}), async () => ({ name: "x" }), {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+    });
+    r.screen({
+      id: "vehicle-detail",
+      type: "projectionDetail",
+      query: "app:query:vehicle:detail",
+      layout: options.detailTabs
+        ? {
+            mode: "tabs",
+            sections: [
+              { id: "overview", title: "Overview", fields: ["name"] },
+              { id: "channels", title: "Channels", fields: ["name"] },
+            ],
+          }
+        : { sections: [{ title: "Overview", fields: ["name"] }] },
+    });
+    const navigateAction = {
+      kind: "navigate" as const,
+      id: "view-channels",
+      label: "app.actions.viewChannels",
+      screen: "vehicle-detail",
+      tab: options.tab,
+    };
+    if (options.via === "entityEditSection") {
+      r.screen({
+        id: "vehicle-edit",
+        type: "entityEdit",
+        entity: "vehicle",
+        layout: {
+          sections: [
+            {
+              id: "main",
+              title: "Main",
+              columns: 1,
+              fields: ["name"],
+              actions: [{ ...navigateAction, entityId: "vehicleId" }],
+            },
+          ],
+        },
+      });
+    } else {
+      r.screen({
+        id: "vehicle-list",
+        type: "entityList",
+        entity: "vehicle",
+        columns: ["name"],
+        rowActions: [navigateAction],
+      });
+    }
+  });
+}
+
+describe("validateBoot — RowActionNavigate.tab", () => {
+  test("entityEdit section action navigates to a known tab boots cleanly", () => {
+    const feature = buildFeature({ detailTabs: true, tab: "channels", via: "entityEditSection" });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("entityEdit section action navigates to an unknown tab throws", () => {
+    const feature = buildFeature({ detailTabs: true, tab: "unknown", via: "entityEditSection" });
+    expect(() => validateBoot([feature])).toThrow(
+      /navigates to tab "unknown", which is not a section id on target screen/,
+    );
+  });
+
+  test("entityEdit section action navigating to a non-tabs projectionDetail throws", () => {
+    const feature = buildFeature({ detailTabs: false, tab: "overview", via: "entityEditSection" });
+    expect(() => validateBoot([feature])).toThrow(
+      /is not a projectionDetail with layout.mode "tabs"/,
+    );
+  });
+
+  test("entityList rowAction navigating to an unknown tab throws (central resolution path)", () => {
+    const feature = buildFeature({
+      detailTabs: true,
+      tab: "unknown",
+      via: "entityListRowAction",
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /navigates to tab "unknown", which is not a section id on target screen/,
+    );
+  });
+});

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

@@ -542,11 +542,48 @@ type RowActionNavigateRuntime = RowActionNavigateBase & {
   readonly entity?: string;
 };
 
+// The target can be any screen, so this checks the resolved target's
+// sections, not the host's.
+function validateRowActionNavigateTab(
+  featureName: string,
+  screenId: string,
+  screenType: "entityList" | "projectionList" | "projectionDetail" | "entityEdit",
+  actionLabel: string,
+  action: RowActionNavigateRuntime,
+  target: { readonly featureName: string; readonly screen: ScreenDefinition } | undefined,
+): void {
+  // skip: no tab declared — nothing to check against the target's sections
+  if (action.tab === undefined) return;
+  if (target === undefined) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
+        `sets tab "${action.tab}", but its navigate-target could not be resolved to a screen.`,
+    );
+  }
+  if (target.screen.type !== "projectionDetail" || target.screen.layout.mode !== "tabs") {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
+        `sets tab "${action.tab}", but navigate-target screen "${target.screen.id}" is not a ` +
+        `projectionDetail with layout.mode "tabs" — only those read the tab param.`,
+    );
+  }
+  const sectionIds = target.screen.layout.sections
+    .map((section) => section.id)
+    .filter((id): id is string => id !== undefined);
+  if (!sectionIds.includes(action.tab)) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
+        `navigates to tab "${action.tab}", which is not a section id on target screen ` +
+        `"${target.screen.id}". Available: ${sectionIds.join(", ") || "(none)"}.`,
+    );
+  }
+}
+
 function resolveRowActionNavigateTarget(
   featureName: string,
   screenId: string,
   screenType: "entityList" | "projectionList" | "projectionDetail" | "entityEdit",
-  actionLabel: "rowAction" | "action",
+  actionLabel: string,
   action: RowActionNavigateRuntime,
   allScreenQns: ReadonlySet<string>,
   navTargetShortIds: ReadonlySet<string>,
@@ -586,6 +623,7 @@ function resolveRowActionNavigateTarget(
           `detailFor: "${action.entity}".`,
       );
     }
+    validateRowActionNavigateTab(featureName, screenId, screenType, actionLabel, action, detail);
     return detail;
   }
   if (action.screen === undefined) {
@@ -601,7 +639,9 @@ function resolveRowActionNavigateTarget(
         `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
     );
   }
-  return screensByShortId.get(action.screen)?.[0];
+  const target = screensByShortId.get(action.screen)?.[0];
+  validateRowActionNavigateTab(featureName, screenId, screenType, actionLabel, action, target);
+  return target;
 }
 
 // Shared by the mint step's own handler (screen.handler) and its optional
@@ -1225,6 +1265,19 @@ export function validateScreens(
               `section "${sectionLabel}" action`,
               action,
             );
+            if (action.kind === "navigate" && action.tab !== undefined) {
+              resolveRowActionNavigateTarget(
+                feature.name,
+                screenId,
+                "projectionDetail",
+                `section "${sectionLabel}" action`,
+                action,
+                allScreenQns,
+                navTargetShortIds,
+                screensByShortId,
+                detailForScreens,
+              );
+            }
           }
         }
         if (section.kind === "relatedList" && section.emptyState?.action !== undefined) {
@@ -1235,6 +1288,22 @@ export function validateScreens(
             `section "${sectionLabel}" emptyState action`,
             section.emptyState.action,
           );
+          if (
+            section.emptyState.action.kind === "navigate" &&
+            section.emptyState.action.tab !== undefined
+          ) {
+            resolveRowActionNavigateTarget(
+              feature.name,
+              screenId,
+              "projectionDetail",
+              `section "${sectionLabel}" emptyState action`,
+              section.emptyState.action,
+              allScreenQns,
+              navTargetShortIds,
+              screensByShortId,
+              detailForScreens,
+            );
+          }
         }
         if (isExtensionEditSection(section)) {
           // projectionDetail is read-only (no composed form submit) — an
@@ -1983,6 +2052,19 @@ export function validateScreens(
               `section "${sectionLabel}" action`,
               action,
             );
+            if (action.kind === "navigate" && action.tab !== undefined) {
+              resolveRowActionNavigateTarget(
+                feature.name,
+                screenId,
+                "entityEdit",
+                `section "${sectionLabel}" action`,
+                action,
+                allScreenQns,
+                navTargetShortIds,
+                screensByShortId,
+                detailForScreens,
+              );
+            }
           }
         }
         if (isExtensionEditSection(section)) {

package/src/entrypoint/__tests__/split-deploy.integration.test.ts

@@ -20,6 +20,7 @@ import { createRegistry, defineFeature } from "../../engine";
 import { createArchivedStreamsTable } from "../../event-store";
 import { createEventConsumerStateTable } from "../../pipeline";
 import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
+import { waitFor } from "../../testing";
 import { createAllInOneEntrypoint, createApiEntrypoint, createWorkerEntrypoint } from "../index";
 
 const splitFeature = defineFeature("split", (r) => {
@@ -103,14 +104,6 @@ const fileJobFeature = defineFeature("fileJob", (r) => {
   r.multiStreamProjection({ name: "noop", apply: { [requested.name]: async () => {} } });
 });
 
-async function waitForCondition(check: () => boolean, timeoutMs = 5000): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (!check()) {
-    if (Date.now() > deadline) throw new Error("waitForCondition: timed out");
-    await new Promise((resolve) => setTimeout(resolve, 25));
-  }
-}
-
 const JWT = "split-deploy-test-secret-must-be-32-chars!!";
 
 // Per-test queue-name with a random suffix. Date.now() alone collided
@@ -195,7 +188,7 @@ describe("entrypoint factories", () => {
         { storageKey: "some/key.pdf" },
         TestUsers.admin,
       );
-      await waitForCondition(() => jobSawFilesRef.length > 0);
+      await waitFor(() => jobSawFilesRef.length > 0);
       expect(jobSawFilesRef[0]).toBe("function");
     } finally {
       await worker.stop();
@@ -239,7 +232,7 @@ describe("entrypoint factories", () => {
       // The worker's own eventDispatcher (started above) picks the event
       // back up and runs the MSP — proves the afterCommit/MSP chain works
       // inside the worker lane, not just that the write itself succeeded.
-      await waitForCondition(() => consumedNotes.includes("written from the worker"));
+      await waitFor(() => consumedNotes.includes("written from the worker"));
     } finally {
       await worker.stop();
     }
@@ -264,7 +257,7 @@ describe("entrypoint factories", () => {
         { storageKey: "some/key.pdf" },
         TestUsers.admin,
       );
-      await waitForCondition(() => jobSawFilesRef.length > 0);
+      await waitFor(() => jobSawFilesRef.length > 0);
       expect(jobSawFilesRef[0]).toBe("function");
     } finally {
       await entry.stop();

package/src/files/__tests__/write-stream.test.ts

@@ -16,6 +16,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtemp, readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { waitFor } from "../../testing";
 import { createInMemoryFileProvider } from "../in-memory-provider";
 import { createLocalProvider } from "../local-provider";
 
@@ -215,12 +216,15 @@ describe("FileStorageProvider.writeStream — Streaming-Property", () => {
       // Poll bis tmp existiert ODER final schon fertig (zu schneller CI).
       let hasTmp = false;
       let alreadyDone = false;
-      for (let i = 0; i < 20 && !hasTmp && !alreadyDone; i++) {
-        await new Promise((r) => setTimeout(r, 10));
-        const dirContents = await readdir(basePath);
-        hasTmp = dirContents.some((f) => f.endsWith(".tmp"));
-        alreadyDone = dirContents.includes("streamed.bin");
-      }
+      await waitFor(
+        async () => {
+          const dirContents = await readdir(basePath);
+          hasTmp = dirContents.some((f) => f.endsWith(".tmp"));
+          alreadyDone = dirContents.includes("streamed.bin");
+          return hasTmp || alreadyDone;
+        },
+        { delays: Array(20).fill(10) },
+      );
       if (alreadyDone && !hasTmp) {
         throw new Error(
           "slowChunks-delay zu kurz fuer CI: writeStream war fertig bevor poll start. " +

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -439,6 +439,7 @@ describe("concurrency: skip", () => {
 
       // Try dispatching multiple times while first is running
       let skippedCount = 0;
+      // @timeout-exception: #3118 paces repeated dispatch attempts, nothing to poll for
       for (let i = 0; i < 5; i++) {
         await sleep(50);
         const id = await runner.dispatch("test:job:skip-job", { n: i + 2 });
@@ -1212,6 +1213,7 @@ describe("handleEvent maxPerTenant", () => {
       // racing against the handler's own 500ms sleep, which could land
       // outside the window on a starved runner and silently pass.
       await runner.handleEvent("test:write:capped-event", { n: 3 }, user);
+      // @timeout-exception: #3118 asserts a negative (stays capped) at each checkpoint
       for (const delayMs of [50, 100, 200, 400]) {
         await sleep(delayMs);
         const startedNow = jobLog.filter((e) => e.name === "test:job:per-tenant-limited-event");

package/src/lifecycle/__tests__/signal-handlers.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, mock, test } from "bun:test";
+import { waitFor } from "../../testing";
 import { createLifecycle } from "../lifecycle";
 import { attachSignalHandlers } from "../signal-handlers";
 import { createTestLifecycle } from "./create-test-lifecycle";
@@ -95,12 +96,3 @@ describe("attachSignalHandlers", () => {
     expect(process.listenerCount("SIGTERM")).toBe(before);
   });
 });
-
-async function waitFor(predicate: () => boolean, timeoutMs = 500): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (predicate()) return;
-    await new Promise((r) => setTimeout(r, 5));
-  }
-  throw new Error("waitFor timed out");
-}

package/src/pipeline/__tests__/event-dispatcher-db-outage.integration.test.ts

@@ -186,7 +186,12 @@ describe("E: dispatcher survives a DB outage and logs the recovery", () => {
     } finally {
       await dispatcher.stop();
       await listenClient.end({ timeout: 1 });
-      await proxiedDb.close();
+      // Destroy instead of a graceful end(): when proxy2.stop() kills a socket
+      // mid-query, postgres.js keeps that query referenced on the dead
+      // connection, and a plain end() then waits for a resolver only
+      // terminate() fires, so it never returns. The pool is test-owned and
+      // every assertion has already run, so dropping in-flight work is safe.
+      await proxiedDb.client.end({ timeout: 0 });
     }
   });
 });

package/src/pipeline/__tests__/event-dispatcher-lifecycle.integration.test.ts

@@ -31,7 +31,7 @@ import {
   TestUsers,
   unsafeCreateEntityTable,
 } from "../../stack";
-import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+import { sharedWidgetEntity, sharedWidgetTable, waitFor } from "../../testing";
 
 // --- Test fixtures ---
 
@@ -118,7 +118,7 @@ describe("E.1 — .start() lifecycle + slow handler", () => {
 
       // pollIntervalMs in the test-stack is 50ms. Give the timer a few
       // ticks to observe the event.
-      await waitFor(() => observations.length >= 1, 2000);
+      await waitFor(() => observations.length >= 1, { delays: Array(40).fill(50) });
       expect(observations).toHaveLength(1);
       expect(observations[0]?.event.payload["name"]).toBe("started-delivery");
     } finally {
@@ -140,7 +140,7 @@ describe("E.1 — .start() lifecycle + slow handler", () => {
       await appendWidget("slow-3");
 
       // Wait until all 3 slow-observer invocations have completed.
-      await waitFor(() => slowHandlerInvocations.length >= 3, 5000);
+      await waitFor(() => slowHandlerInvocations.length >= 3, { delays: Array(50).fill(100) });
 
       // Check: no invocation overlapped with the next — every pass
       // finished before the following one started. The guard does
@@ -207,14 +207,3 @@ describe("E.1 — consumer-lag metric", () => {
 });
 
 // --- Helpers ---
-
-async function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    if (predicate()) return;
-    await new Promise((r) => setTimeout(r, 20));
-  }
-  if (!predicate()) {
-    throw new Error(`waitFor: predicate never became true within ${timeoutMs}ms`);
-  }
-}

package/src/pipeline/__tests__/event-dispatcher-second-audit.integration.test.ts

@@ -33,7 +33,7 @@ import {
   TestUsers,
   unsafeCreateEntityTable,
 } from "../../stack";
-import { sharedWidgetEntity } from "../../testing";
+import { sharedWidgetEntity, waitFor } from "../../testing";
 import { generateId } from "../../utils";
 
 // --- Fixture ---
@@ -247,7 +247,7 @@ describe("Second audit — LISTEN gauge", () => {
           ).length;
 
         // Wait for the initial onlisten (gauge.set 1) to land.
-        await waitFor(() => connectsWithValue1() >= 1, 2000);
+        await waitFor(() => connectsWithValue1() >= 1, { delays: Array(40).fill(50) });
         const initialConnects = connectsWithValue1();
         expect(initialConnects).toBeGreaterThanOrEqual(1);
 
@@ -266,7 +266,9 @@ describe("Second audit — LISTEN gauge", () => {
 
         // Wait for the SECOND gauge.set(1) — the reconnect. Generous timeout
         // because postgres.js's reconnect loop includes backoff.
-        await waitFor(() => connectsWithValue1() > initialConnects, 10000);
+        await waitFor(() => connectsWithValue1() > initialConnects, {
+          delays: Array(50).fill(200),
+        });
         expect(connectsWithValue1()).toBeGreaterThan(initialConnects);
       } finally {
         await recStack.eventDispatcher?.stop();
@@ -278,14 +280,3 @@ describe("Second audit — LISTEN gauge", () => {
 });
 
 // --- Helpers ---
-
-async function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    if (predicate()) return;
-    await new Promise((r) => setTimeout(r, 25));
-  }
-  if (!predicate()) {
-    throw new Error(`waitFor: predicate never became true within ${timeoutMs}ms`);
-  }
-}