@cosmicdrift/kumiko-framework 0.236.0 → 0.237.0

package/package.json

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

package/src/__tests__/schema-cli.integration.test.ts

@@ -54,11 +54,13 @@ describe("runSchemaCli — no-DB paths", () => {
     expect(cap.err).toHaveLength(0);
   });
 
-  test("unknown subcommand falls through to usage", async () => {
+  test("unknown subcommand exits 1 and reports it on stderr", async () => {
     const cap = captureOut();
-    const code = await runSchemaCli(["lolwut"], appCwd, cap.out);
-    expect(code).toBe(0);
-    expect(cap.log.join("\n")).toContain("Subcommands:");
+    const code = await runSchemaCli(["cutover"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain('Unbekanntes Subcommand: "cutover"');
+    expect(cap.err.join("\n")).toContain("generate | validate | apply | baseline | status");
+    expect(cap.log).toHaveLength(0);
   });
 
   test("generate without name exits 1 with neutral usage wording", async () => {

package/src/api/__tests__/redis-sse-broker.integration.test.ts

@@ -2,7 +2,12 @@ import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test
 import { createTestRedis, type TestRedis } from "../../stack";
 import { waitFor } from "../../testing/wait-for";
 import { generateId } from "../../utils";
-import { createRedisSseBroker, type RedisSseBroker } from "../redis-sse-broker";
+import {
+  createDefaultSseBroker,
+  createRedisSseBroker,
+  isRedisSseBroker,
+  type RedisSseBroker,
+} from "../redis-sse-broker";
 import type { SseEvent } from "../sse-broker";
 
 let testRedis: TestRedis;
@@ -149,3 +154,35 @@ describe("createRedisSseBroker", () => {
     }
   });
 });
+
+describe("createDefaultSseBroker", () => {
+  test("builds a Redis-backed broker under REDIS_URL that participates in cross-pod fanout", async () => {
+    const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker({
+      REDIS_URL: testRedis.redisUrl,
+    });
+    expect(ownedRedisSseBroker).toBeDefined();
+    expect(isRedisSseBroker(sseBroker)).toBe(true);
+    if (ownedRedisSseBroker) brokers.push(ownedRedisSseBroker);
+
+    const otherPod = trackedBroker();
+    const channel = `default-broker-${generateId()}`;
+    const received: SseEvent[] = [];
+    otherPod.addClient(
+      channel,
+      (event) => received.push(event),
+      () => {},
+    );
+
+    await waitFor(() => {
+      sseBroker.pushToChannel(channel, { type: "unit.updated", data: { id: "1" } });
+      return received.length >= 1;
+    });
+    expect(received[0]).toEqual({ type: "unit.updated", data: { id: "1" } });
+  });
+
+  test("falls back to the in-memory broker without REDIS_URL", () => {
+    const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker({});
+    expect(ownedRedisSseBroker).toBeUndefined();
+    expect(isRedisSseBroker(sseBroker)).toBe(false);
+  });
+});

package/src/api/index.ts

@@ -42,7 +42,7 @@ export type { JwtHelper, JwtKeyring, JwtPayload } from "./jwt";
 export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt";
 export { patAllows, qnMatches } from "./pat-scope";
 export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker";
-export { createRedisSseBroker } from "./redis-sse-broker";
+export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker } from "./redis-sse-broker";
 export { type RequestContextData, requestContext } from "./request-context";
 export { requestIdMiddleware } from "./request-id-middleware";
 export { createApiRoutes } from "./routes";

package/src/api/redis-sse-broker.ts

@@ -22,6 +22,34 @@ export type RedisSseBroker = SseBroker & {
   close(): Promise<void>;
 };
 
+// The one property RedisSseBroker adds over SseBroker — cheap and reliable
+// to narrow on, so callers that only hold an SseBroker (e.g. a test that
+// pulled it back out of a generic ServerOptions.sseBroker slot) can tell
+// which lifecycle they own without an unsound `as` cast.
+export function isRedisSseBroker(broker: SseBroker): broker is RedisSseBroker {
+  return "close" in broker;
+}
+
+// Single decision point for "which SseBroker should a caller default to
+// when it doesn't inject its own": REDIS_URL present → cross-replica
+// Redis-backed broker, absent → the in-memory one. Both buildServer and
+// runProdApp must funnel through this rather than each deciding on their
+// own — runProdApp doing exactly that (building an in-memory broker
+// unconditionally, then passing it in as ServerOptions.sseBroker) is why
+// fw#2625's fanout fix (fw#2630) shipped without ever taking effect in
+// production: an explicit ServerOptions.sseBroker always wins in
+// buildServer, so its own REDIS_URL-based default never ran.
+export function createDefaultSseBroker(env: Record<string, string | undefined> = process.env): {
+  readonly sseBroker: SseBroker;
+  // Present only when REDIS_URL resolved. undefined means the fallback
+  // in-memory broker was used, which has nothing to release on shutdown.
+  readonly ownedRedisSseBroker: RedisSseBroker | undefined;
+} {
+  const redisUrl = env["REDIS_URL"];
+  const ownedRedisSseBroker = redisUrl ? createRedisSseBroker({ redisUrl }) : undefined;
+  return { sseBroker: ownedRedisSseBroker ?? createSseBroker(), ownedRedisSseBroker };
+}
+
 function isSseEvent(value: unknown): value is SseEvent {
   return (
     typeof value === "object" &&

package/src/api/server.ts

@@ -57,7 +57,7 @@ import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
-import { createRedisSseBroker } from "./redis-sse-broker";
+import { createDefaultSseBroker, type RedisSseBroker } from "./redis-sse-broker";
 import { requestContext } from "./request-context";
 import { buildRequestContextData, requestIdMiddleware } from "./request-id-middleware";
 import {
@@ -68,7 +68,7 @@ import {
   registerVersionRoute,
 } from "./route-registrars";
 import { createApiRoutes } from "./routes";
-import { createSseBroker, type SseBroker } from "./sse-broker";
+import type { SseBroker } from "./sse-broker";
 import { createSseRoute } from "./sse-route";
 
 export type ServerOptions = {
@@ -318,17 +318,19 @@ export function buildServer(options: ServerOptions): KumikoServer {
     options.jwtTtl ?? defaultJwtTtl,
   );
   // An explicit ServerOptions.sseBroker always wins (caller owns its
-  // lifecycle). Otherwise, REDIS_URL decides the default: without
-  // cross-replica fanout, replicas > 1 silently drops SSE/access-
-  // invalidation events for whichever pod didn't win the shared cursor
-  // (fw#2625) — the safe default has to be the correct one, not the
-  // single-process one.
-  const ownedRedisSseBroker = options.sseBroker
-    ? undefined
-    : process.env["REDIS_URL"]
-      ? createRedisSseBroker({ redisUrl: process.env["REDIS_URL"] })
-      : undefined;
-  const sseBroker = options.sseBroker ?? ownedRedisSseBroker ?? createSseBroker();
+  // lifecycle) — createDefaultSseBroker is the single decision point every
+  // other caller must funnel through instead of picking a broker on its
+  // own, so the REDIS_URL-gated cross-replica default (fw#2625) can't be
+  // silently bypassed the way runProdApp bypassed it before this existed.
+  let sseBroker: SseBroker;
+  let ownedRedisSseBroker: RedisSseBroker | undefined;
+  if (options.sseBroker) {
+    sseBroker = options.sseBroker;
+  } else {
+    const defaults = createDefaultSseBroker();
+    sseBroker = defaults.sseBroker;
+    ownedRedisSseBroker = defaults.ownedRedisSseBroker;
+  }
 
   // Resolve the per-process instance identifier. Prefer explicit
   // ServerOptions.instanceId (tests, deliberate wiring), fall back to the

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

@@ -16,7 +16,7 @@ import {
 import { createEntity, createTextField } from "../factories";
 // Barrel import, not "../entity-handlers": covers that entityListSchema is
 // actually re-exported through engine/index.ts.
-import { entityListSchema } from "../index";
+import { entityListSchema, resolveAgentExposure } from "../index";
 import type { QueryHandlerDef, WriteHandlerDef } from "../types";
 
 const VALID_UUID = "00000000-0000-4000-8000-000000000001";
@@ -367,4 +367,56 @@ describe("registerEntityCrud", () => {
     expect(Object.keys(entities)).toEqual(["note"]);
     expect(writes.map((w) => w.name)).toEqual(["note:create"]);
   });
+  test("descriptions: per-verb text lands on that verb only, and drives agent exposure", () => {
+    const { r, writes, queries } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntity, {
+      descriptions: {
+        create: "Files a new note.",
+        list: "Lists notes newest first.",
+      },
+    });
+
+    const create = writes.find((w) => w.name === "note:create");
+    const update = writes.find((w) => w.name === "note:update");
+    const list = queries.find((q) => q.name === "note:list");
+    const detail = queries.find((q) => q.name === "note:detail");
+    if (!create || !update || !list || !detail) throw new Error("CRUD handlers missing");
+
+    expect(create.description).toBe("Files a new note.");
+    expect(list.description).toBe("Lists notes newest first.");
+    expect(update.description).toBeUndefined();
+    expect(detail.description).toBeUndefined();
+
+    // Fail-closed exposure is why the slot exists: only the described verbs
+    // reach the agent manifest.
+    expect(resolveAgentExposure(create, "write").expose).toBe(true);
+    expect(resolveAgentExposure(list, "query").expose).toBe(true);
+    expect(resolveAgentExposure(update, "write").expose).toBe(false);
+    expect(resolveAgentExposure(detail, "query").expose).toBe(false);
+  });
+
+  test("descriptions: per-verb entry wins over the write/read fallback", () => {
+    const { r, writes } = createCrudRegistrarMock();
+    registerEntityCrud(r, "note", noteEntity, {
+      write: { description: "Shared write text." },
+      descriptions: { create: "Files a new note." },
+      verbs: { list: false, detail: false },
+    });
+
+    expect(writes.find((w) => w.name === "note:create")?.description).toBe("Files a new note.");
+    expect(writes.find((w) => w.name === "note:update")?.description).toBe("Shared write text.");
+  });
+
+  test("agent hints on the per-handler options raise the resolved risk", () => {
+    const del = defineEntityDeleteHandler("note", noteEntity, {
+      description: "Deletes a note permanently.",
+      agent: { risk: "high" },
+    });
+    const create = defineEntityCreateHandler("note", noteEntity, {
+      description: "Files a new note.",
+    });
+
+    expect(resolveAgentExposure(del, "write").risk).toBe("high");
+    expect(resolveAgentExposure(create, "write").risk).toBe("mid");
+  });
 });

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

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
 import { validateBoot as validateBootRaw } from "../boot-validator";
 import { defineFeature } from "../define-feature";
@@ -358,3 +358,55 @@ describe("validateBoot — nav validation", () => {
     expect(() => validateBoot([feature])).not.toThrow();
   });
 });
+
+describe("nav access inversion warning (fw#2640)", () => {
+  test("leaf role-gate disjoint from its parent section's → warns but boot still succeeds", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const feature = defineFeature("shop", (r) => {
+      r.nav({ id: "section", label: "s", access: { roles: ["Manager"] } });
+      r.nav({
+        id: "leaf",
+        label: "l",
+        parent: "shop:nav:section",
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Nav entry "shop:nav:leaf" requires roles [Admin]'),
+    );
+    warnSpy.mockRestore();
+  });
+
+  test("leaf role-gate overlapping its parent's → no warning", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const feature = defineFeature("shop", (r) => {
+      r.nav({ id: "section", label: "s", access: { roles: ["Manager", "Admin"] } });
+      r.nav({
+        id: "leaf",
+        label: "l",
+        parent: "shop:nav:section",
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("Nav entry"));
+    warnSpy.mockRestore();
+  });
+
+  test("parent open to everyone (unset access) → a role-gated leaf never warns", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const feature = defineFeature("shop", (r) => {
+      r.nav({ id: "section", label: "s" });
+      r.nav({
+        id: "leaf",
+        label: "l",
+        parent: "shop:nav:section",
+        access: { roles: ["Admin"] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+    expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("Nav entry"));
+    warnSpy.mockRestore();
+  });
+});

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

@@ -42,6 +42,7 @@ import {
   collectWriteHandlerQns,
   validateNavCycles,
   validateNavs,
+  warnOnNavAccessInversion,
 } from "./nav";
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
@@ -215,6 +216,7 @@ export function validateBoot(
   }
 
   validateNavCycles(allNavQns);
+  warnOnNavAccessInversion(allNavQns);
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateI18nSurfaceKeys(features);
   validateEntityListScreens(features);

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

@@ -3,7 +3,7 @@
 // here since this is a structural move, not a semantic reorg).
 
 import { qualifyEntityName } from "../qualified-name";
-import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+import type { AccessRule, FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
 
 export function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string> {
   const set = new Set<string>();
@@ -99,6 +99,41 @@ export function validateNavCycles(
   }
 }
 
+// undefined access or `{ openToAll: true }` both mean "visible to everyone"
+// — neither has a role-set an inversion check could compare against.
+function navViewerRoles(access: AccessRule | undefined): readonly string[] | undefined {
+  if (access === undefined || "openToAll" in access) return undefined;
+  return access.roles;
+}
+
+// fw#2640: warn (never throw — this is a real UX bug, not a broken ref)
+// when a nav leaf's role gate is disjoint from its parent section's — no
+// user who can see the section could ever see this child, so the section
+// renders with zero visible children for every user who reaches it.
+// Only fires when BOTH sides declare an explicit, non-empty role list:
+// an unset/openToAll side is visible to everyone, so it can't invert.
+export function warnOnNavAccessInversion(
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+): void {
+  for (const [qn, navDef] of allNavQns) {
+    if (navDef.parent === undefined) continue;
+    const parentDef = allNavQns.get(navDef.parent);
+    if (parentDef === undefined) continue; // dangling parent ref — validateNavs already throws for this
+    const parentRoles = navViewerRoles(parentDef.access);
+    const leafRoles = navViewerRoles(navDef.access);
+    if (parentRoles === undefined || leafRoles === undefined) continue;
+    if (parentRoles.length === 0) continue; // parent already visible to nobody — a different problem
+    if (leafRoles.some((role) => parentRoles.includes(role))) continue;
+    // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+    console.warn(
+      `[kumiko:boot] Nav entry "${qn}" requires roles [${leafRoles.join(", ")}] but its parent ` +
+        `"${navDef.parent}" only allows [${parentRoles.join(", ")}] — no user who can see the ` +
+        `parent section could ever see this entry. If this is intentional, ignore this warning; ` +
+        `otherwise align the role sets.`,
+    );
+  }
+}
+
 // Roles we recognise at boot time. The framework has no explicit
 // role-registry (r.defineRoles is a type helper only), so we synthesise
 // one from every handler-access rule plus the "all"/"system" built-ins.

package/src/engine/define-handler.ts

@@ -78,6 +78,8 @@ export function defineWriteHandler<
     name: def.name,
     schema: def.schema,
     ...(def.access && { access: def.access }),
+    ...(def.description !== undefined && { description: def.description }),
+    ...(def.agent && { agent: def.agent }),
     ...(def.unsafeSkipTransitionGuard && {
       unsafeSkipTransitionGuard: def.unsafeSkipTransitionGuard,
     }),

package/src/engine/entity-handlers.ts

@@ -172,7 +172,7 @@ function parseHandlerName<TVerb extends string>(
 export function defineEntityWriteHandler(
   name: string,
   entity: EntityDefinition,
-  options?: { access?: AccessRule },
+  options?: EntityHandlerOptions,
 ): WriteHandlerDef {
   const { entityName, verb } = parseHandlerName(name, WRITE_VERBS);
   if (verb === "restore" && !entity.softDelete) {
@@ -253,6 +253,8 @@ export function defineEntityWriteHandler(
     schema,
     handler,
     ...(options?.access && { access: options.access }),
+    ...(options?.description !== undefined && { description: options.description }),
+    ...(options?.agent !== undefined && { agent: options.agent }),
   };
 }
 
@@ -282,7 +284,7 @@ function augmentDerivedFields(
 export function defineEntityQueryHandler(
   name: string,
   entity: EntityDefinition,
-  options?: { access?: AccessRule; crossTenant?: boolean },
+  options?: EntityQueryHandlerOptions,
 ): QueryHandlerDef {
   const { entityName, verb } = parseHandlerName(name, QUERY_VERBS);
 
@@ -367,6 +369,8 @@ export function defineEntityQueryHandler(
     schema,
     handler,
     ...(options?.access && { access: options.access }),
+    ...(options?.description !== undefined && { description: options.description }),
+    ...(options?.agent !== undefined && { agent: options.agent }),
     // The "list" verb's executor.list() always returns { rows, nextCursor,
     // total? } (see the handler body above) — brand it so the definition
     // site documents the PagedRows contract without needing
@@ -533,10 +537,12 @@ export function registerEntityCrud(
   const resolveWriteOpts = (verb: EntityCrudVerb): EntityHandlerOptions => ({
     ...writeOpts,
     access: options?.verbAccess?.[verb] ?? writeOpts?.access,
+    description: options?.descriptions?.[verb] ?? writeOpts?.description,
   });
   const resolveReadOpts = (verb: EntityCrudVerb): EntityQueryHandlerOptions => ({
     ...readOpts,
     access: options?.verbAccess?.[verb] ?? readOpts?.access,
+    description: options?.descriptions?.[verb] ?? readOpts?.description,
   });
 
   if (verbs.create) {

package/src/engine/factories.ts

@@ -439,6 +439,7 @@ export function createImagesField(
 export function createEntity<F>(def: {
   readonly table?: string;
   readonly fields: F;
+  readonly description?: string;
   readonly softDelete?: boolean;
   /** Event stream lives on SYSTEM_TENANT_ID (tenant-independent aggregate, e.g.
    *  user) instead of the creator's tenant. See EntityDefinition.systemStream. */

package/src/schema-cli.ts

@@ -447,6 +447,15 @@ export async function runSchemaCli(
     }
 
     default: {
+      // No subcommand (`kumiko schema`) is a help request → usage + exit 0.
+      // An unrecognized one (typo, e.g. `schema cutover`) must fail loud —
+      // silently exiting 0 here let a deploy's migrate step print help and
+      // move on without ever running a migration.
+      if (sub !== undefined) {
+        out.err(`  Unbekanntes Subcommand: "${sub}"`);
+        out.err("  Erlaubt: generate | validate | apply | baseline | status");
+        return 1;
+      }
       out.log("");
       out.log("  Subcommands:");
       out.log("    generate <name>   Schreibe neue Migration aus EntityTableMeta-Diff");