@cosmicdrift/kumiko-framework 0.152.0 → 0.154.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.152.0",
+  "version": "0.154.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>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.152.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.154.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/anonymous-access.integration.test.ts

@@ -361,6 +361,31 @@ describe("anonymous access — resolverTrust: authoritative", () => {
     const body = (await res.json()) as { error: { code: string } };
     expect(body.error.code).toBe("tenant_mismatch");
   });
+
+  // pr-review kumiko-framework #1052/3 — resolveTenant treats header and
+  // cookie identically, but every case above only exercised the header.
+  // These two lock in that the cookie path behaves the same way.
+  test("kumiko_tenant cookie agreeing with the resolver → accepted", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { Cookie: `kumiko_tenant=${TENANT_ID}` },
+    );
+    expect(res.status).toBe(200);
+  });
+
+  test("kumiko_tenant cookie disagreeing with the resolver → 400 tenant_mismatch, same as a disagreeing header", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "anonshop:query:product:list", payload: {} },
+      { Cookie: `kumiko_tenant=${OTHER_TENANT_ID}` },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_mismatch");
+  });
 });
 
 describe("anonymous access — resolverTrust: authoritative, resolver returns null", () => {

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

@@ -0,0 +1,242 @@
+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 — action wiring (no function values)", () => {
+  test("rowAction writeHandler payload as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "writeHandler",
+            id: "sync",
+            label: "actions.sync",
+            handler: "shop:write:sync",
+            // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+            payload: ((row: unknown) => ({ id: row })) as any,
+          },
+        ],
+      });
+      r.writeHandler("sync", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/rowAction "sync" payload is a function/);
+  });
+
+  test("rowAction writeHandler payload as declarative pick → kein Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField({ sortable: true }) } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        defaultSort: { field: "name", dir: "asc" },
+        rowActions: [
+          {
+            kind: "writeHandler",
+            id: "sync",
+            label: "actions.sync",
+            handler: "shop:write:sync",
+            payload: { pick: ["name"] },
+          },
+        ],
+      });
+      r.writeHandler("sync", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { roles: ["Admin"] },
+      });
+      r.translations({
+        keys: {
+          "screen:product-list.title": { de: "Liste", en: "List" },
+          "shop:entity:product:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("rowAction navigate visible as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "edit",
+            label: "actions.edit",
+            screen: "product-list",
+            // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+            visible: (() => true) as any,
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/rowAction "edit" visible is a function/);
+  });
+
+  test("toolbarAction writeHandler payload as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        toolbarActions: [
+          {
+            kind: "writeHandler",
+            id: "sync",
+            label: "actions.sync",
+            handler: "shop:write:sync",
+            // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+            payload: (() => ({})) as any,
+          },
+        ],
+      });
+      r.writeHandler("sync", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/toolbarAction "sync" payload is a function/);
+  });
+
+  test("entityList column renderer as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: [
+          // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+          { field: "name", renderer: ((v: unknown) => String(v)) as any },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/column "name" renderer is a function/);
+  });
+
+  test("entityEdit field visible as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [
+            {
+              columns: 1,
+              // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+              fields: [{ field: "name", visible: (() => true) as any }],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/field "name" visible is a function/);
+  });
+
+  test("entityEdit field renderer as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [
+            {
+              columns: 1,
+              // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+              fields: [{ field: "name", renderer: ((v: unknown) => String(v)) as any }],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/field "name" renderer is a function/);
+  });
+
+  test("entityEdit field with declarative visible/readOnly/required → kein Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "product-edit",
+        type: "entityEdit",
+        entity: "product",
+        layout: {
+          sections: [
+            {
+              columns: 1,
+              fields: [
+                {
+                  field: "name",
+                  visible: { field: "name", ne: "" },
+                  readOnly: false,
+                  required: true,
+                },
+              ],
+            },
+          ],
+        },
+      });
+      r.translations({
+        keys: {
+          "screen:product-edit.title": { de: "Bearbeiten", en: "Edit" },
+          "shop:entity:product:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("projectionList column renderer as function → Throw", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.screen({
+        id: "sales-list",
+        type: "projectionList",
+        query: "shop:query:sales",
+        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({
+        id: "sales-list",
+        type: "projectionList",
+        query: "shop:query:sales",
+        columns: ["amount"],
+        rowActions: [
+          {
+            kind: "writeHandler",
+            id: "sync",
+            label: "actions.sync",
+            handler: "shop:write:sync",
+            // biome-ignore lint/suspicious/noExplicitAny: intentional type violation under test
+            payload: (() => ({})) as any,
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/rowAction "sync" payload is a function/);
+  });
+});

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

@@ -1231,8 +1231,9 @@ describe("boot-validator", () => {
   // --- entityList column-renderer form-check ---
   // Validator akzeptiert die `{ react: { __component: "Name" } }`-Form
   // (PlatformComponent → client-side Registry-Lookup) und prüft sie
-  // strukturell. String-Funktionen, null/undefined, native-only und
-  // andere Formen bleiben opak.
+  // strukturell. null/undefined, native-only und andere Formen bleiben
+  // opak. Function-Renderer werfen (action-wiring.ts validateFieldWiring) —
+  // von JSON.stringify verworfen, sonst stiller No-op auf dem Client.
   describe("entityList column renderer form", () => {
     function shopFeature(renderer: unknown) {
       return defineFeature("shop", (r) => {
@@ -1250,8 +1251,10 @@ describe("boot-validator", () => {
       });
     }
 
-    test("function-renderer → kein Throw (Bestand)", () => {
-      expect(() => validateBoot([shopFeature((v: unknown) => String(v))])).not.toThrow();
+    test("function-renderer → Throw (Function wird von JSON.stringify verworfen)", () => {
+      expect(() => validateBoot([shopFeature((v: unknown) => String(v))])).toThrow(
+        /column "name" renderer is a function/,
+      );
     });
 
     test("undefined renderer → kein Throw (Spalte ohne Renderer)", () => {

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

@@ -80,6 +80,86 @@ describe("r.nav() — registration", () => {
   });
 });
 
+describe("r.screen({ nav }) — inline nav sugar", () => {
+  test("synthesizes a nav entry from the screen's id", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        nav: { label: "shop:nav.products", icon: "box", order: 5 },
+      });
+    });
+    expect(feature.navs["products"]).toMatchObject({
+      id: "products",
+      label: "shop:nav.products",
+      icon: "box",
+      order: 5,
+      screen: "shop:screen:products",
+    });
+  });
+
+  test("supports parent like a standalone r.nav()", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.nav({ id: "catalog", label: "x" });
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        nav: { label: "y", parent: "shop:nav:catalog" },
+      });
+    });
+    expect(feature.navs["products"]?.parent).toBe("shop:nav:catalog");
+  });
+
+  test("passes the same boot-validation as a standalone r.nav()", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+        nav: { label: "y" },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("screen without nav registers no nav entry", () => {
+    const feature = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "products",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+    });
+    expect(feature.navs["products"]).toBeUndefined();
+  });
+
+  test("rejects when a standalone r.nav() already used the screen's id", () => {
+    expect(() =>
+      defineFeature("shop", (r) => {
+        r.nav({ id: "products", label: "standalone" });
+        r.entity("product", productEntity());
+        r.screen({
+          id: "products",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          nav: { label: "inline" },
+        });
+      }),
+    ).toThrow(/already registered/);
+  });
+});
+
 describe("createRegistry — nav indexing", () => {
   test("indexes nav entries by qualified name", () => {
     const feature = defineFeature("shop", (r) => {

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

@@ -0,0 +1,99 @@
+import type { EditFieldSpec, FeatureDefinition, RowAction, ToolbarAction } from "../types";
+import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
+
+const FUNCTION_DROPPED_HINT =
+  "functions are dropped by JSON.stringify when the screen config reaches the client " +
+  "bundle — the action/field silently no-ops at runtime instead of failing loudly.";
+
+function throwIfFunction(value: unknown, message: string): void {
+  if (typeof value === "function") {
+    throw new Error(message);
+  }
+}
+
+// rowActions/toolbarActions carry row-context extractors (payload/params),
+// static visibility conditions and navigate entityId — all declarative-DSL-
+// only fields (RowFieldExtractor's `{ pick }`/`{ map }`, FieldCondition's
+// `{ field, eq }`/`{ field, ne }`, plain strings). A function literal here
+// compiles fine (the DSL types are structural, not branded) but is silently
+// dropped once the feature config is serialized for the client.
+const ACTION_FUNCTION_FIELDS = ["payload", "params", "entityId", "visible"] as const;
+
+function validateActionNoFunctions(
+  featureName: string,
+  screenId: string,
+  actionKind: "rowAction" | "toolbarAction",
+  action: RowAction | ToolbarAction,
+): void {
+  const record = action as unknown as Record<string, unknown>;
+  for (const field of ACTION_FUNCTION_FIELDS) {
+    throwIfFunction(
+      record[field],
+      `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${action.id}" ${field} ` +
+        `is a function — ${FUNCTION_DROPPED_HINT} Use the declarative DSL ({ pick }, { map }, ` +
+        `"fieldName", { field, eq }) instead.`,
+    );
+  }
+}
+
+export function validateActionWiring(feature: FeatureDefinition): void {
+  for (const screen of Object.values(feature.screens)) {
+    if (screen.type !== "entityList" && screen.type !== "projectionList") continue;
+    for (const action of screen.rowActions ?? []) {
+      validateActionNoFunctions(feature.name, screen.id, "rowAction", action);
+    }
+    for (const action of screen.toolbarActions ?? []) {
+      validateActionNoFunctions(feature.name, screen.id, "toolbarAction", action);
+    }
+  }
+}
+
+// EditFieldSpec's visible/readOnly/required are the same FieldCondition DSL
+// as rowActions — same footgun, different screen type (entityEdit layouts).
+const EDIT_FIELD_FUNCTION_FIELDS = ["visible", "readOnly", "required"] as const;
+
+function validateEditFieldNoFunctions(
+  featureName: string,
+  screenId: string,
+  fieldSpec: EditFieldSpec,
+): void {
+  const normalized = normalizeEditField(fieldSpec);
+  const record = normalized as unknown as Record<string, unknown>;
+  for (const key of EDIT_FIELD_FUNCTION_FIELDS) {
+    throwIfFunction(
+      record[key],
+      `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${normalized.field}" ` +
+        `${key} is a function — ${FUNCTION_DROPPED_HINT} Use a FieldCondition ` +
+        `(boolean or { field, eq }/{ field, ne }) instead.`,
+    );
+  }
+  throwIfFunction(
+    normalized.renderer,
+    `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${normalized.field}" ` +
+      `renderer is a function — ${FUNCTION_DROPPED_HINT} Use a FormatSpec ({ format: "..." }) instead.`,
+  );
+}
+
+export function validateFieldWiring(feature: FeatureDefinition): void {
+  for (const screen of Object.values(feature.screens)) {
+    if (screen.type === "entityList" || screen.type === "projectionList") {
+      for (const col of screen.columns) {
+        const normalized = normalizeListColumn(col);
+        throwIfFunction(
+          normalized.renderer,
+          `[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) column ` +
+            `"${normalized.field}" renderer is a function — ${FUNCTION_DROPPED_HINT} ` +
+            `Use a FormatSpec ({ format: "..." }) instead.`,
+        );
+      }
+      continue;
+    }
+    if (screen.type !== "entityEdit") continue;
+    for (const section of screen.layout.sections) {
+      if (isExtensionEditSection(section)) continue;
+      for (const fieldSpec of section.fields) {
+        validateEditFieldNoFunctions(feature.name, screen.id, fieldSpec);
+      }
+    }
+  }
+}

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

@@ -1,6 +1,7 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
+import { validateActionWiring, validateFieldWiring } from "./action-wiring";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
 import {
   validateCircularDeps,
@@ -171,6 +172,12 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
     validateConfigKeyBacking(feature);
     validateOwnershipRules(feature, allClaimKeys, knownRoles);
     validateMultiStreamProjections(feature);
+    // Vor validateScreens: dessen visible/entityId-Feldref-Checks werfen für
+    // einen Function-Wert bereits (mit verwirrender "unknown field undefined"-
+    // Message, weil `typeof fn !== "boolean"` true ist), bevor der klare
+    // Function-Check hier überhaupt liefe.
+    validateActionWiring(feature);
+    validateFieldWiring(feature);
     validateScreens(
       feature,
       featureMap,

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -358,3 +358,45 @@ describe("renderPattern — single-pattern shape", () => {
     expect(out).toBe('r.metric({ name: "requests", type: "counter" });');
   });
 });
+
+// Regression guard for the class of bug the r.exposesApi/r.usesApi fold
+// hit: a registrar-shape change (there, removing a method; here, adding a
+// nested optional field) must survive the Designer's parse→render→parse
+// cycle, not just a TS compile of the framework itself. r.screen()'s `nav`
+// sugar is a generic nested object on an already-generic pattern (no
+// per-field extractor/renderer), so this is the cheap case — but proving
+// it beats assuming it.
+const SCREEN_WITH_NAV_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("shop", (r) => {
+  r.entity("product", { fields: { name: { type: "text" } } });
+  r.screen({
+    id: "products",
+    type: "entityList",
+    entity: "product",
+    columns: ["name"],
+    nav: { label: "shop:nav.products", icon: "box", order: 5 },
+  });
+});
+`;
+
+describe("render → parse roundtrip — r.screen({ nav }) inline sugar", () => {
+  test("nested nav object survives parse → render → parse unchanged", () => {
+    const initial = parse(SCREEN_WITH_NAV_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+
+    const screenPattern = reparsed.patterns.find((p) => p.kind === "screen");
+    expect(screenPattern?.kind).toBe("screen");
+    if (screenPattern?.kind === "screen") {
+      expect(screenPattern.definition).toMatchObject({
+        nav: { label: "shop:nav.products", icon: "box", order: 5 },
+      });
+    }
+  });
+});

package/src/engine/feature-ui-extensions.ts

@@ -260,6 +260,27 @@ export function buildUiExtensionsMethods<TName extends string>(
         );
       }
       state.screens[definition.id] = definition;
+      if (definition.nav) {
+        // Sugar for the common "one nav entry pointing at this screen"
+        // case — synthesizes id/screen from the screen's own id. Beyond
+        // label/icon/parent/order, declare a standalone r.nav() instead.
+        if (state.navs[definition.id]) {
+          throw new Error(
+            `[Feature ${name}] Nav entry "${definition.id}" already registered. ` +
+              `Nav ids must be unique per feature — remove the standalone ` +
+              `r.nav("${definition.id}", ...) call or the screen's inline nav.`,
+          );
+        }
+        const navDefinition: NavDefinition = {
+          id: definition.id,
+          label: definition.nav.label,
+          icon: definition.nav.icon,
+          parent: definition.nav.parent,
+          order: definition.nav.order,
+          screen: `${name}:screen:${definition.id}`,
+        };
+        state.navs[definition.id] = navDefinition;
+      }
     },
     nav(definition: NavDefinition): void {
       // Reject kebab-drift at registration-time so the stack trace points at

package/src/engine/types/feature.ts

@@ -684,7 +684,9 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // the registry qualifies to "<feature>:screen:<id>". Boot-validation checks
   // that entity-bound screens reference a registered entity and that the
   // columns / form-field refs name real fields — cross-feature component-QN
-  // validation (r.uiComponent) comes in M4/M5.
+  // validation (r.uiComponent) comes in M4/M5. Optional `nav` field is
+  // sugar for a single nav entry pointing at this screen — equivalent to
+  // a standalone r.nav({ id: <same id>, screen: "<feature>:screen:<id>", ... }).
   screen(definition: ScreenDefinition): void;
 
   // Register a nav entry. The id is the feature-local short name (kebab-case);

package/src/engine/types/screen.ts

@@ -727,7 +727,19 @@ export type ScreenSlots = {
 
 // --- discriminated union ---
 
-export type ScreenDefinition =
+// Inline nav-entry sugar for `r.screen({ ..., nav: {...} })` — covers the
+// common case of "one nav entry pointing at this screen". The nav entry's
+// `id`/`screen` are synthesized from the screen's own id; for anything
+// beyond label/icon/parent/order (access-gating, workspaces, actions),
+// declare a standalone `r.nav()` entry instead.
+export type ScreenNavSugar = {
+  readonly label: string;
+  readonly icon?: string;
+  readonly parent?: string;
+  readonly order?: number;
+};
+
+export type ScreenDefinition = (
   | EntityListScreenDefinition
   | ProjectionListScreenDefinition
   | ProjectionDetailScreenDefinition
@@ -735,7 +747,8 @@ export type ScreenDefinition =
   | EntityEditScreenDefinition
   | ActionFormScreenDefinition
   | ConfigEditScreenDefinition
-  | CustomScreenDefinition;
+  | CustomScreenDefinition
+) & { readonly nav?: ScreenNavSugar };
 
 // Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
 // authors who branch on the three FieldRenderer variants without manual

package/src/stack/redis.ts

@@ -3,6 +3,13 @@ import { requireEnv } from "./db";
 
 export type TestRedis = {
   redis: import("ioredis").default;
+  // The exact REDIS_URL used to build `redis` above — for a second, unrelated
+  // connection (e.g. the test-stack's JobRunner) that needs its own client
+  // rather than sharing this one's keyPrefix. Reconstructing a URL from
+  // `redis.options` loses password/username/tls/path (pr-review
+  // kumiko-framework #1036/2) — callers needing a fresh connection should use
+  // this raw string, not rebuild one from parsed options.
+  redisUrl: string;
   /** Delete every key this test created (prefix-scoped). Replaces the old
    *  `redis.flushdb()` — that wiped other parallel tests' BullMQ state. */
   flushNamespace: () => Promise<void>;
@@ -35,6 +42,7 @@ export async function createTestRedis(): Promise<TestRedis> {
 
   return {
     redis,
+    redisUrl,
     flushNamespace,
     cleanup: async () => {
       await flushNamespace();

package/src/stack/test-stack.ts

@@ -237,167 +237,187 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   // test-stack's own ephemeral redis — no separate `redisUrl` seam needed.
   let jobRunner: JobRunner | undefined;
   if (options.jobs && registry.getAllJobs().size > 0) {
-    const redisOpts = testRedis.redis.options;
     jobRunner = createJobRunner({
       registry,
       context: { db: testDb.db, registry },
-      redisUrl: `redis://${redisOpts.host}:${redisOpts.port}/${redisOpts.db}`,
+      // The real REDIS_URL, not one rebuilt from `.options` — that lost
+      // password/username/tls/path (pr-review kumiko-framework #1036/2).
+      redisUrl: testRedis.redisUrl,
       ...(options.jobs.consumerLane !== undefined && { consumerLane: options.jobs.consumerLane }),
       ...(options.jobs.queueNamePrefix !== undefined && {
         queueNamePrefix: options.jobs.queueNamePrefix,
       }),
     });
-    await jobRunner.start();
   }
 
-  // Auto-configure search for tenant 1 based on registry
-  if (enabledHooks.includes("search")) {
-    const searchableFields: string[] = [];
-    for (const feature of options.features) {
-      for (const [, entity] of Object.entries(feature.entities ?? {})) {
-        for (const [fieldName, field] of Object.entries(entity.fields)) {
-          if (field.type === "text" && field.searchable) {
-            searchableFields.push(fieldName);
-          }
-          if (field.type === "embedded") {
-            for (const [subName, subField] of Object.entries(field.schema)) {
-              if (subField.searchable) {
-                searchableFields.push(`${fieldName}_${subName}`);
+  // From here on, any throw must stop a jobRunner that was already created
+  // above (createJobRunner() itself opens live BullMQ Queue/lock Redis
+  // connections, .start() adds a live worker) — otherwise a failing
+  // buildServer()/search-config/etc. leaks that connection and the test
+  // process hangs on exit (pr-review kumiko-framework #1036/1).
+  try {
+    if (jobRunner) await jobRunner.start();
+
+    // Auto-configure search for tenant 1 based on registry
+    if (enabledHooks.includes("search")) {
+      const searchableFields: string[] = [];
+      for (const feature of options.features) {
+        for (const [, entity] of Object.entries(feature.entities ?? {})) {
+          for (const [fieldName, field] of Object.entries(entity.fields)) {
+            if (field.type === "text" && field.searchable) {
+              searchableFields.push(fieldName);
+            }
+            if (field.type === "embedded") {
+              for (const [subName, subField] of Object.entries(field.schema)) {
+                if (subField.searchable) {
+                  searchableFields.push(`${fieldName}_${subName}`);
+                }
               }
             }
           }
         }
       }
-    }
 
-    if (options.searchConfig) {
-      await searchAdapter.configure(options.searchConfig.tenantId, {
-        searchableFields: options.searchConfig.searchableFields,
-        rankingFields: options.searchConfig.rankingFields,
-      });
-    } else if (searchableFields.length > 0) {
-      await searchAdapter.configure("00000000-0000-4000-8000-000000000001", {
-        searchableFields,
-        rankingFields: searchableFields,
-      });
+      if (options.searchConfig) {
+        await searchAdapter.configure(options.searchConfig.tenantId, {
+          searchableFields: options.searchConfig.searchableFields,
+          rankingFields: options.searchConfig.rankingFields,
+        });
+      } else if (searchableFields.length > 0) {
+        await searchAdapter.configure("00000000-0000-4000-8000-000000000001", {
+          searchableFields,
+          rankingFields: searchableFields,
+        });
+      }
     }
-  }
 
-  // Wire SSE broker with event collector
-  const sseBroker = createSseBroker();
-  sseBroker.addClient(
-    "tenant:00000000-0000-4000-8000-000000000001",
-    (event) => events.sse.push(event),
-    () => {},
-  );
+    // Wire SSE broker with event collector
+    const sseBroker = createSseBroker();
+    sseBroker.addClient(
+      "tenant:00000000-0000-4000-8000-000000000001",
+      (event) => events.sse.push(event),
+      () => {},
+    );
 
-  const idempotency = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 60 });
-  const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
-  const entityCache = createEntityCache(testRedis.redis, { ttlSeconds: 60 });
+    const idempotency = createIdempotencyGuard(testRedis.redis, { ttlSeconds: 60 });
+    const eventDedup = createEventDedup(testRedis.redis, { ttlSeconds: 60 });
+    const entityCache = createEntityCache(testRedis.redis, { ttlSeconds: 60 });
 
-  // A static `files.storageProvider` is wired as the per-tenant resolver — the
-  // framework test seam that doesn't require mounting config + file-foundation.
-  // (Bundled GDPR tests mount the real provider features instead.)
-  let fileProviderResolver: import("../files").FileProviderResolver | undefined;
-  if (options.files) {
-    const provider = options.files.storageProvider;
-    fileProviderResolver = () => Promise.resolve(provider);
-  }
+    // A static `files.storageProvider` is wired as the per-tenant resolver — the
+    // framework test seam that doesn't require mounting config + file-foundation.
+    // (Bundled GDPR tests mount the real provider features instead.)
+    let fileProviderResolver: import("../files").FileProviderResolver | undefined;
+    if (options.files) {
+      const provider = options.files.storageProvider;
+      fileProviderResolver = () => Promise.resolve(provider);
+    }
 
-  const server = buildServer({
-    registry,
-    context: {
-      db: testDb.db,
-      redis: testRedis.redis,
-      searchAdapter,
-      entityCache,
+    const server = buildServer({
       registry,
-      ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
-      ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
-      ...(typeof options.extraContext === "function"
-        ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
-        : options.extraContext),
-    },
-    jwtSecret,
-    dispatcherOptions: {
-      idempotency,
-      ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
-      ...(jobRunner && { jobRunner }),
-    },
-    eventDedup,
-    sseBroker,
-    // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for
-    // deterministic drains — no timer-induced flakiness. pollIntervalMs
-    // stays short anyway in case a test opts into `.start()`. pgClient
-    // plumbs through the LISTEN wake-up for tests that want to measure
-    // post-commit latency (Sprint E.4).
-    eventDispatcher: {
-      pollIntervalMs: 50,
-      pgClient: testDb.client as PgClient | undefined,
-      systemConsumers: {
-        sse: enabledHooks.includes("sse"),
-        search: enabledHooks.includes("search"),
+      context: {
+        db: testDb.db,
+        redis: testRedis.redis,
+        searchAdapter,
+        entityCache,
+        registry,
+        ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
+        ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
+        ...(typeof options.extraContext === "function"
+          ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
+          : options.extraContext),
       },
-    },
-    // Default tests to no login rate-limiter so existing suites that loop
-    // over logins don't hit a 429 after 10 attempts. Suites specifically
-    // testing the limiter can override via authConfig.loginRateLimit.
-    ...(options.authConfig
-      ? {
-          auth: {
-            ...options.authConfig,
-            ...(options.authConfig.loginRateLimit === undefined ? { loginRateLimit: null } : {}),
-          },
-        }
-      : {}),
-    ...(options.observability ? { observability: options.observability } : {}),
-    ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
-    ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
-    ...(options.anonymousAccess
-      ? {
-          anonymousAccess:
-            typeof options.anonymousAccess === "function"
-              ? options.anonymousAccess({
-                  registry,
-                  db: testDb.db,
-                  sseBroker,
-                  redis: testRedis.redis,
-                })
-              : options.anonymousAccess,
-        }
-      : {}),
-  });
+      jwtSecret,
+      dispatcherOptions: {
+        idempotency,
+        ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
+        ...(jobRunner && { jobRunner }),
+      },
+      eventDedup,
+      sseBroker,
+      // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for
+      // deterministic drains — no timer-induced flakiness. pollIntervalMs
+      // stays short anyway in case a test opts into `.start()`. pgClient
+      // plumbs through the LISTEN wake-up for tests that want to measure
+      // post-commit latency (Sprint E.4).
+      eventDispatcher: {
+        pollIntervalMs: 50,
+        pgClient: testDb.client as PgClient | undefined,
+        systemConsumers: {
+          sse: enabledHooks.includes("sse"),
+          search: enabledHooks.includes("search"),
+        },
+      },
+      // Default tests to no login rate-limiter so existing suites that loop
+      // over logins don't hit a 429 after 10 attempts. Suites specifically
+      // testing the limiter can override via authConfig.loginRateLimit.
+      ...(options.authConfig
+        ? {
+            auth: {
+              ...options.authConfig,
+              ...(options.authConfig.loginRateLimit === undefined ? { loginRateLimit: null } : {}),
+            },
+          }
+        : {}),
+      ...(options.observability ? { observability: options.observability } : {}),
+      ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
+      ...(options.rateLimit ? { rateLimit: options.rateLimit } : {}),
+      ...(options.anonymousAccess
+        ? {
+            anonymousAccess:
+              typeof options.anonymousAccess === "function"
+                ? options.anonymousAccess({
+                    registry,
+                    db: testDb.db,
+                    sseBroker,
+                    redis: testRedis.redis,
+                  })
+                : options.anonymousAccess,
+          }
+        : {}),
+    });
 
-  const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
+    const eventDispatcher: EventDispatcher | undefined = server.eventDispatcher;
 
-  // Pre-register consumer state rows so tests can call runOnce() directly
-  // without a preceding explicit start(). Timer fires at pollIntervalMs=50
-  // but passInFlight serialises concurrent passes — tests that drain via
-  // runOnce() remain deterministic. Tests that specifically exercise the
-  // timer loop call start() again (idempotent) after setup.
-  if (eventDispatcher) await eventDispatcher.ensureRegistered();
+    // Pre-register consumer state rows so tests can call runOnce() directly
+    // without a preceding explicit start(). Timer fires at pollIntervalMs=50
+    // but passInFlight serialises concurrent passes — tests that drain via
+    // runOnce() remain deterministic. Tests that specifically exercise the
+    // timer loop call start() again (idempotent) after setup.
+    if (eventDispatcher) await eventDispatcher.ensureRegistered();
 
-  const http = createRequestHelper(server.app, server.jwt);
+    const http = createRequestHelper(server.app, server.jwt);
 
-  return {
-    app: server.app,
-    jwt: server.jwt,
-    registry,
-    db: testDb.db,
-    redis: testRedis,
-    search: searchAdapter,
-    events,
-    http,
-    observability: server.observability,
-    dispatcher: server.dispatcher,
-    ...(eventDispatcher ? { eventDispatcher } : {}),
-    ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
-    ...(jobRunner ? { jobRunner } : {}),
-    cleanup: async () => {
-      if (jobRunner) await jobRunner.stop();
-      if (eventDispatcher) await eventDispatcher.stop();
-      await server.observability.shutdown();
-      await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
-    },
-  };
+    return {
+      app: server.app,
+      jwt: server.jwt,
+      registry,
+      db: testDb.db,
+      redis: testRedis,
+      search: searchAdapter,
+      events,
+      http,
+      observability: server.observability,
+      dispatcher: server.dispatcher,
+      ...(eventDispatcher ? { eventDispatcher } : {}),
+      ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
+      ...(jobRunner ? { jobRunner } : {}),
+      cleanup: async () => {
+        if (jobRunner) await jobRunner.stop();
+        if (eventDispatcher) await eventDispatcher.stop();
+        await server.observability.shutdown();
+        await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
+      },
+    };
+  } catch (error) {
+    // Best-effort — a broken jobRunner.stop() must never mask the real
+    // setup failure below.
+    if (jobRunner) {
+      try {
+        await jobRunner.stop();
+      } catch {
+        // ignore — `error` is the one that matters
+      }
+    }
+    throw error;
+  }
 }