@cosmicdrift/kumiko-framework 0.163.3 → 0.165.0

package/package.json

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

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

@@ -84,6 +84,36 @@ describe("runConsumerCli status", () => {
     expect(code).toBe(1);
     expect(lines.join("\n")).toContain("DATABASE_URL not set");
   });
+
+  test("--instance-id flag → status looks up the per-instance consumer, not shared", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:inst", "inst-1");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(
+      ["status", "test:consumer:inst", "--instance-id", "inst-1"],
+      out,
+    );
+    expect(code).toBe(0);
+    const joined = lines.join("\n");
+    expect(joined).toContain('instance_id="inst-1"');
+  });
+});
+
+describe("runConsumerCli — unknown/empty subcommand exit codes", () => {
+  test("no subcommand at all → exit 0 (usage, not an error)", async () => {
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli([], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain("Subcommands:");
+  });
+
+  test("an unrecognized subcommand → exit 1", async () => {
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["bogus"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("Subcommands:");
+  });
 });
 
 describe("runConsumerCli restart", () => {

package/src/api/__tests__/api.test.ts

@@ -8,6 +8,7 @@ import {
   type TenantId,
 } from "../../engine";
 import { createTestUser, TestUsers } from "../../stack";
+import { pumpStream } from "../routes";
 import { buildServer } from "../server";
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
@@ -210,6 +211,65 @@ describe("POST /api/command", () => {
   });
 });
 
+// --- pumpStream (SSE pull loop) ---
+
+function fakeSseWriter() {
+  const frames: Array<{ event: string; data: string }> = [];
+  return {
+    frames,
+    async writeSSE(message: { event: string; data: string }) {
+      frames.push(message);
+    },
+  };
+}
+
+async function* delayedGenerator(values: readonly unknown[], delayMsByIndex: readonly number[]) {
+  for (let i = 0; i < values.length; i++) {
+    const delay = delayMsByIndex[i] ?? 0;
+    if (delay > 0) await Bun.sleep(delay);
+    yield values[i];
+  }
+}
+
+describe("pumpStream", () => {
+  test("emits a ping when the handler is slow, then still delivers the pending chunk (no loss)", async () => {
+    const writer = fakeSseWriter();
+    // heartbeatMs (10) fires before the 40ms-delayed second chunk resolves.
+    const gen = delayedGenerator([{ i: 0 }, { i: 1 }], [0, 40]);
+
+    await pumpStream(writer, gen, 10);
+
+    const events = writer.frames.map((f) => f.event);
+    expect(events[0]).toBe("chunk");
+    expect(events).toContain("ping");
+    expect(events.at(-1)).toBe("done");
+    // Both chunks arrive despite the ping in between — no chunk dropped.
+    const chunkData = writer.frames.filter((f) => f.event === "chunk").map((f) => f.data);
+    expect(chunkData).toEqual([JSON.stringify({ i: 0 }), JSON.stringify({ i: 1 })]);
+  });
+
+  test("no heartbeat fires when the handler is faster than heartbeatMs — chunks then done", async () => {
+    const writer = fakeSseWriter();
+    const gen = delayedGenerator([{ i: 0 }, { i: 1 }, { i: 2 }], [0, 0, 0]);
+
+    await pumpStream(writer, gen, 1000);
+
+    expect(writer.frames.map((f) => f.event)).toEqual(["chunk", "chunk", "chunk", "done"]);
+  });
+
+  test("a handler generator that throws propagates the error instead of swallowing it", async () => {
+    const writer = fakeSseWriter();
+    async function* throwing() {
+      yield { i: 0 };
+      throw new Error("handler-boom");
+    }
+
+    await expect(pumpStream(writer, throwing(), 1000)).rejects.toThrow("handler-boom");
+    // The chunk before the throw still made it out.
+    expect(writer.frames.map((f) => f.event)).toEqual(["chunk"]);
+  });
+});
+
 // --- SSE ---
 
 describe("GET /api/sse", () => {

package/src/api/__tests__/auth-routes-mfa-preauth-confirm.test.ts

@@ -80,7 +80,11 @@ function preauthConfirmRequest(body: unknown): Request {
 
 describe("POST /auth/mfa/preauth-confirm", () => {
   test("is public — reachable without a JWT", async () => {
-    expect(PUBLIC_API_PATHS.has("/api/auth/mfa/preauth-confirm")).toBe(true);
+    const { app } = await buildApp();
+    const res = await app.request(preauthConfirmRequest({ setupToken: "t", code: "123456" }));
+    // No Authorization header sent at all — if the route required a JWT,
+    // authMiddleware would reject with 401 before the handler ever runs.
+    expect(res.status).not.toBe(401);
   });
 
   test("not mounted when mfaPreauthConfirmHandler is unset", async () => {
@@ -100,12 +104,24 @@ describe("POST /auth/mfa/preauth-confirm", () => {
         };
       },
     });
-    const { app } = await buildApp({}, dispatcher);
+    // An active limiter, not null — "before rate-limit" is only checkable
+    // when there's a rate-limit to (not) consume.
+    const { app } = await buildApp(
+      { mfaPreauthConfirmRateLimit: createInMemoryLoginRateLimiter(2, 60_000) },
+      dispatcher,
+    );
     const res = await app.request(preauthConfirmRequest({ setupToken: "t" }));
     expect(res.status).toBe(400);
     const body = (await res.json()) as { isSuccess: boolean; error: string };
     expect(body.error).toBe("invalid_body");
     expect(dispatched).toBe(false);
+
+    // The limiter's cap (2) must still be fully available — a malformed
+    // body must not have consumed an attempt.
+    for (let i = 0; i < 5; i++) {
+      const retry = await app.request(preauthConfirmRequest({ setupToken: "t" }));
+      expect(retry.status).toBe(400);
+    }
   });
 
   test("on success: dispatches to mfaPreauthConfirmHandler, mints a JWT + cookies", async () => {

package/src/api/__tests__/login-rate-limiter-sweep.test.ts

@@ -2,25 +2,33 @@ import { describe, expect, test } from "bun:test";
 import { createInMemoryLoginRateLimiter } from "../auth-routes";
 
 describe("createInMemoryLoginRateLimiter — sweep + cap", () => {
-  test("sweepExpired drops windows that already reset before accepting a new key", async () => {
-    // Tiny thresholds so the Map hits the sweep path without flooding.
-    const limiter = createInMemoryLoginRateLimiter(10, 50, {
-      maxEntries: 100,
+  test("sweepExpired removes expired entries before enforceCap can evict a fresh key", async () => {
+    // maxAttempts=1 makes every entry a single-shot probe: a second `check`
+    // on the same key only returns true if the entry was actually removed
+    // from the map (either by expiry+sweep or by enforceCap).
+    const limiter = createInMemoryLoginRateLimiter(1, 50, {
+      maxEntries: 2,
       sweepThreshold: 2,
     });
 
-    expect(await limiter.check("a")).toBe(true);
-    expect(await limiter.check("b")).toBe(true);
-    // Wait for both windows to expire, then a third check must sweep a+b
-    // (hits.size >= sweepThreshold) before inserting "c".
+    expect(await limiter.check("old1")).toBe(true);
+    expect(await limiter.check("old2")).toBe(true);
+    // Let both windows expire.
     await Bun.sleep(60);
-    expect(await limiter.check("c")).toBe(true);
-    // Fresh window for "a" after sweep — not rate-limited.
-    expect(await limiter.check("a")).toBe(true);
+
+    // hits.size (2) >= sweepThreshold (2) → sweepExpired runs first and
+    // clears old1/old2 before "new1" is inserted, so enforceCap never fires.
+    expect(await limiter.check("new1")).toBe(true);
+    expect(await limiter.check("new2")).toBe(true);
+
+    // If enforceCap had run instead of (or before) the sweep, it would have
+    // evicted "new1" as the oldest live entry, and this check would return
+    // true (fresh window) rather than false (still rate-limited).
+    expect(await limiter.check("new1")).toBe(false);
   });
 
-  test("enforceCap drops oldest entries when the map exceeds maxEntries", async () => {
-    const limiter = createInMemoryLoginRateLimiter(100, 60_000, {
+  test("enforceCap drops the oldest entry when the map exceeds maxEntries", async () => {
+    const limiter = createInMemoryLoginRateLimiter(1, 60_000, {
       maxEntries: 3,
       sweepThreshold: 10_000, // never sweep — only the hard cap matters
     });
@@ -28,14 +36,15 @@ describe("createInMemoryLoginRateLimiter — sweep + cap", () => {
     expect(await limiter.check("k1")).toBe(true);
     expect(await limiter.check("k2")).toBe(true);
     expect(await limiter.check("k3")).toBe(true);
-    // 4th insert trips enforceCap → drops oldest (k1).
+    // 4th insert trips enforceCap → drops the oldest entry (k1).
     expect(await limiter.check("k4")).toBe(true);
 
     // k1 was dropped — a fresh check starts a new window (allowed).
     expect(await limiter.check("k1")).toBe(true);
-    // k2/k3/k4 still live in the map (cap=3 after k1 drop + k1 reinsert may
-    // drop another). Reset proves the API still works for survivors.
-    await limiter.reset("k4");
-    expect(await limiter.check("k4")).toBe(true);
+
+    // k4 must still be alive in the map: a check within its still-open
+    // window is rate-limited (count >= maxAttempts), proving enforceCap
+    // dropped k1 and not k4.
+    expect(await limiter.check("k4")).toBe(false);
   });
 });

package/src/api/routes.ts

@@ -147,28 +147,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
       });
 
       try {
-        let pending = generator.next();
-        while (true) {
-          let heartbeatTimer: ReturnType<typeof setTimeout> | undefined;
-          const heartbeat = new Promise<"heartbeat">((resolve) => {
-            heartbeatTimer = setTimeout(() => resolve("heartbeat"), SSE_HEARTBEAT_INTERVAL_MS);
-          });
-          let outcome: Awaited<typeof pending> | "heartbeat";
-          try {
-            outcome = await Promise.race([pending, heartbeat]);
-          } finally {
-            clearTimeout(heartbeatTimer);
-          }
-
-          if (outcome === "heartbeat") {
-            await stream.writeSSE({ event: "ping", data: "" });
-            continue;
-          }
-          if (outcome.done) break;
-          await stream.writeSSE({ event: "chunk", data: stringifyJson(outcome.value) });
-          pending = generator.next();
-        }
-        await stream.writeSSE({ event: "done", data: "" });
+        await pumpStream(stream, generator, SSE_HEARTBEAT_INTERVAL_MS);
       } catch (e) {
         const err = toKumiko(e);
         logServerFault(err, requestId, body.type);
@@ -181,6 +160,46 @@ export function createApiRoutes(dispatcher: Dispatcher) {
   return api;
 }
 
+export type SseWriter = {
+  readonly writeSSE: (message: { readonly event: string; readonly data: string }) => Promise<void>;
+};
+
+// Pull loop for /api/stream: races each generator.next() against a
+// heartbeat timer so a slow/idle handler still keeps the connection alive
+// ("ping" frames), forwards yielded chunks as "chunk" frames, and emits
+// "done" once the generator completes. Factored out of the route handler
+// so the heartbeat/ping and abort/cleanup paths are unit-testable with a
+// fast heartbeatMs instead of only reachable through SSE_HEARTBEAT_INTERVAL_MS
+// (15s) in a full HTTP round-trip.
+export async function pumpStream(
+  stream: SseWriter,
+  generator: AsyncGenerator<unknown>,
+  heartbeatMs: number,
+): Promise<void> {
+  let pending = generator.next();
+  while (true) {
+    let heartbeatTimer: ReturnType<typeof setTimeout> | undefined;
+    const heartbeat = new Promise<"heartbeat">((resolve) => {
+      heartbeatTimer = setTimeout(() => resolve("heartbeat"), heartbeatMs);
+    });
+    let outcome: Awaited<typeof pending> | "heartbeat";
+    try {
+      outcome = await Promise.race([pending, heartbeat]);
+    } finally {
+      clearTimeout(heartbeatTimer);
+    }
+
+    if (outcome === "heartbeat") {
+      await stream.writeSSE({ event: "ping", data: "" });
+      continue;
+    }
+    if (outcome.done) break;
+    await stream.writeSSE({ event: "chunk", data: stringifyJson(outcome.value) });
+    pending = generator.next();
+  }
+  await stream.writeSSE({ event: "done", data: "" });
+}
+
 function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode = 200) {
   return c.body(stringifyJson(body), status, { "Content-Type": "application/json" });
 }

package/src/api/server.ts

@@ -34,6 +34,7 @@ import { createEventDispatcher } from "../pipeline/event-dispatcher";
 import { createLifecycleHooks, type SystemHooks } from "../pipeline/lifecycle-pipeline";
 import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context";
 import {
+  createJobTriggerEventConsumer,
   createSearchEventConsumer,
   createSseBroadcastEventConsumer,
 } from "../pipeline/system-hooks";
@@ -105,12 +106,14 @@ export type ServerOptions = {
     // runs a dedicated dispatcher process, or a test needs to control the
     // consumer lifecycle manually.
     disabled?: boolean;
-    // Opt out of the auto-built system consumers (SSE, Search) while still
-    // running feature r.multiStreamProjection consumers. Useful for tests
-    // that assert only on subscriber behaviour, or for a deployment that
-    // routes SSE via a different transport. Default: both enabled when the
-    // respective dependency (sseBroker / context.searchAdapter) is available.
-    systemConsumers?: { sse?: boolean; search?: boolean };
+    // Opt out of the auto-built system consumers (SSE, Search, Job-Trigger)
+    // while still running feature r.multiStreamProjection consumers. Useful
+    // for tests that assert only on subscriber behaviour, or for a
+    // deployment that routes SSE via a different transport. Default: sse/
+    // search enabled when the respective dependency (sseBroker /
+    // context.searchAdapter) is available; jobTrigger enabled when a
+    // jobRunner is wired via dispatcherOptions.
+    systemConsumers?: { sse?: boolean; search?: boolean; jobTrigger?: boolean };
     // Raw postgres.js client for LISTEN/NOTIFY wake-up (Sprint E.4). When
     // present, `.start()` subscribes to EVENTS_PUBSUB_CHANNEL — delivery
     // latency drops from pollIntervalMs to TCP-round-trip. The poll timer
@@ -398,6 +401,8 @@ export function buildServer(options: ServerOptions): KumikoServer {
 
   const sseConsumerEnabled = options.eventDispatcher?.systemConsumers?.sse ?? true;
   const searchConsumerEnabled = options.eventDispatcher?.systemConsumers?.search ?? true;
+  const jobTriggerConsumerEnabled = options.eventDispatcher?.systemConsumers?.jobTrigger ?? true;
+  const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
 
   const systemConsumers: EventConsumer[] = [];
   if (sseConsumerEnabled) {
@@ -406,6 +411,9 @@ export function buildServer(options: ServerOptions): KumikoServer {
   if (searchConsumerEnabled && searchAdapter) {
     systemConsumers.push(createSearchEventConsumer(searchAdapter, options.registry));
   }
+  if (jobTriggerConsumerEnabled && jobRunnerForTriggers) {
+    systemConsumers.push(createJobTriggerEventConsumer(jobRunnerForTriggers, options.registry));
+  }
 
   // MultiStreamProjections: one EventConsumer per MSP. Handler routes by
   // event.type into the MSP's apply map. MSPs aggregate cross-aggregate but

package/src/bun-db/connection.ts

@@ -6,9 +6,12 @@
 // event-dispatcher.ts. Bun.sql 1.2.20 hat kein listen() (PR oven-sh/bun#25511
 // pending). Nach Landung des Bun-LISTEN-Supports: peer raus.
 
+import type { PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
 
+export type { PgListenClient };
+
 // Bun.SQL ist callable als tagged template `sql\`...\`` PLUS hat methods
 // (.begin / .unsafe / .end / .file / .reserve etc.). DbConnection-Type
 // reflektiert die Instance-Shape.
@@ -21,9 +24,6 @@ export type BunDbTx = BunDbConnection;
 // Beide austauschbar im normalen call-path.
 export type BunDbRunner = BunDbConnection | BunDbTx;
 
-// Postgres-js peer NUR für event-dispatcher LISTEN.
-export type PgListenClient = ReturnType<typeof postgres>;
-
 export type BunDbConnectionOptions = {
   readonly maxConnections?: number;
   readonly idleTimeoutSeconds?: number;

package/src/db/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -50,7 +50,7 @@ describe("event-store-executor write-verbs — entity-level ownership_denied", (
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(restrictedEntity, "esWriteRestricted");
+    await unsafeCreateEntityTable(testDb.db, restrictedEntity, "esWriteRestricted");
   });
 
   beforeEach(async () => {
@@ -158,7 +158,7 @@ describe("event-store-executor write-verbs — restore without softDelete", () =
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(hardDeleteEntity, "esWriteHard");
+    await unsafeCreateEntityTable(testDb.db, hardDeleteEntity, "esWriteHard");
   });
 
   beforeEach(async () => {
@@ -199,7 +199,7 @@ describe("event-store-executor write-verbs — field-level ownership_denied", ()
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(ownedFieldEntity, "esWriteOwnedField");
+    await unsafeCreateEntityTable(testDb.db, ownedFieldEntity, "esWriteOwnedField");
   });
 
   beforeEach(async () => {
@@ -264,7 +264,7 @@ describe("event-store-executor write-verbs — version_conflict edge cases", ()
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(versionEntity, "esWriteVersion");
+    await unsafeCreateEntityTable(testDb.db, versionEntity, "esWriteVersion");
   });
 
   beforeEach(async () => {
@@ -298,13 +298,6 @@ describe("event-store-executor write-verbs — version_conflict edge cases", ()
   });
 });
 
-async function unsafeCreateEntityTableFor(
-  entity: Parameters<typeof buildEntityTable>[1],
-  name: string,
-): Promise<void> {
-  await unsafeCreateEntityTable(testDb.db, entity, name);
-}
-
 // =============================================================================
 // Concurrent update race → EventStoreVersionConflict catch + entityCache.del
 // on forget/restore (create/update/delete already exercise cache in the
@@ -341,7 +334,7 @@ describe("event-store-executor write-verbs — concurrent version race + cache",
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(raceEntity, "esWriteRace");
+    await unsafeCreateEntityTable(testDb.db, raceEntity, "esWriteRace");
   });
 
   beforeEach(async () => {

package/src/db/index.ts

@@ -35,8 +35,6 @@ export {
   enrichRowWithReferences,
   enrichWithReferences,
 } from "./eagerload";
-export type { EncryptionProvider } from "./encryption";
-export { createEncryptionProvider } from "./encryption";
 export {
   collectEncryptedFieldNames,
   configuredEntityFieldEncryption,

package/src/db/pg-error.ts

@@ -3,7 +3,7 @@
 // unwrap both layers so callers don't have to know which layer produced the
 // error. Used by the event-store to distinguish a unique-violation on the
 // aggregate-version index (optimistic-concurrency conflict) from the one on
-// the request-id idempotency index (replay signal).
+// the idempotency-key index (caller-side replay signal).
 
 export type PgErrorInfo = {
   readonly code: string | undefined;

package/src/db/queries/event-store.ts

@@ -6,6 +6,20 @@ export async function notifyPgChannel(db: AnyDb, channel: string): Promise<void>
   await asRawClient(db).unsafe(`SELECT pg_notify($1, '')`, [channel]);
 }
 
+// Tenant-scoped partial unique index over metadata.idempotencyKey.
+// Expression index straight on the jsonb column — no dedicated key column,
+// so it needs no INSERT-path change and covers admin-api's raw appends too
+// (same metadata jsonb). CREATE ... IF NOT EXISTS makes this safe to call
+// on every boot, same "ensure" pattern as ensureSnapshotVersionColumn: heals
+// installs that predate the index without a table rebuild.
+export async function ensureIdempotencyKeyIndex(db: AnyDb): Promise<void> {
+  await asRawClient(db).unsafe(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "events_idempotency_uq" ON "kumiko_events" ` +
+      `("tenant_id", (("metadata"->>'idempotencyKey'))) ` +
+      `WHERE "metadata"->>'idempotencyKey' IS NOT NULL`,
+  );
+}
+
 export type SubsequentEventInsertParams = {
   readonly aggregateId: string;
   readonly aggregateType: string;
@@ -85,22 +99,6 @@ export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string):
   return rows[0]?.v ?? 0;
 }
 
-/** tenant_id the aggregate's events were written under — no membership/tenant
- *  filter. A r.systemScope() aggregate (e.g. user) lives in whichever tenant
- *  its creating executor used, which need not be a tenant the subject holds a
- *  membership in. Returns null for unknown streams. */
-export async function selectAggregateStreamTenant(
-  db: AnyDb,
-  aggregateId: string,
-  aggregateType: string,
-): Promise<string | null> {
-  const rows = (await asRawClient(db).unsafe(
-    `SELECT "tenant_id" AS t FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = $2 ORDER BY "version" LIMIT 1`,
-    [aggregateId, aggregateType],
-  )) as ReadonlyArray<{ t: string | null }>;
-  return rows[0]?.t ?? null;
-}
-
 export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
   const rows = (await asRawClient(db).unsafe(
     `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`,

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

@@ -599,6 +599,20 @@ describe("boot-validator", () => {
     expect(() => validateBoot(features)).toThrow(/a:stream:chat:complete.*missing an access rule/i);
   });
 
+  test("object-form streamHandler with access rule passes boot", () => {
+    const features = [
+      defineFeature("a", (r) => {
+        r.streamHandler({
+          name: "chat:complete",
+          schema: z.object({}),
+          handler: async function* () {},
+          access: { roles: ["User"] },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
   test("accepts openToAll access rule on a stream handler", () => {
     const features = [
       defineFeature("a", (r) => {

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

@@ -139,6 +139,42 @@ describe("getAllStreamHandlers", () => {
     });
     expect(() => createRegistry([aiFeature, otherFeature])).not.toThrow();
   });
+
+  test("two distinct feature names that kebab-collide throw on the qualified stream-handler clash", () => {
+    // "registry-test-kebab-dup" and "registryTestKebabDup" are different raw
+    // feature.name values (so the earlier Duplicate-feature guard doesn't
+    // fire) but toKebab() collapses both to the same qualified name.
+    const featureA = defineFeature("registry-test-kebab-dup", (r) => {
+      r.streamHandler("chat:complete", z.object({}), async function* () {});
+    });
+    const featureB = defineFeature("registryTestKebabDup", (r) => {
+      r.streamHandler("chat:complete", z.object({}), async function* () {});
+    });
+    expect(() => createRegistry([featureA, featureB])).toThrow(/Duplicate stream handler/);
+  });
+
+  test("object-form streamHandler registration preserves schema/access/rateLimit", () => {
+    const schema = z.object({ prompt: z.string() });
+    const handlerFn = async function* () {};
+    const feature = defineFeature("registry-test-object-form", (r) => {
+      r.streamHandler({
+        name: "chat:complete",
+        schema,
+        handler: handlerFn,
+        access: { openToAll: true },
+        rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 60 },
+      });
+    });
+
+    const registry = createRegistry([feature]);
+    const registered = registry.getStreamHandler("registry-test-object-form:stream:chat:complete");
+
+    expect(registered).toBeDefined();
+    expect(registered?.schema).toBe(schema);
+    expect(registered?.handler).toBe(handlerFn);
+    expect(registered?.access).toEqual({ openToAll: true });
+    expect(registered?.rateLimit).toEqual({ per: "ip+handler", limit: 5, windowSeconds: 60 });
+  });
 });
 
 describe("extensionSelector boot-validation", () => {

package/src/engine/boot-validator/entity-handler.ts

@@ -101,32 +101,21 @@ const USER_BUCKETED_RATE_LIMIT_PER: ReadonlySet<string> = new Set(["user", "user
 // at runtime, but we fail at boot to turn an easy-to-miss security regression
 // into a loud configuration error.
 export function validateHandlerAccess(feature: FeatureDefinition): void {
-  for (const [name, handler] of Object.entries(feature.writeHandlers)) {
-    if (!handler.access) {
-      throw new Error(
-        `Write handler "${feature.name}:write:${name}" is missing an access rule. ` +
-          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
-      );
-    }
-    validateAnonymousRateLimit(feature.name, "write", name, handler.access, handler.rateLimit);
-  }
-  for (const [name, handler] of Object.entries(feature.queryHandlers)) {
-    if (!handler.access) {
-      throw new Error(
-        `Query handler "${feature.name}:query:${name}" is missing an access rule. ` +
-          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
-      );
-    }
-    validateAnonymousRateLimit(feature.name, "query", name, handler.access, handler.rateLimit);
-  }
-  for (const [name, handler] of Object.entries(feature.streamHandlers)) {
-    if (!handler.access) {
-      throw new Error(
-        `Stream handler "${feature.name}:stream:${name}" is missing an access rule. ` +
-          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
-      );
+  const kinds = [
+    { kind: "write" as const, label: "Write", handlers: feature.writeHandlers },
+    { kind: "query" as const, label: "Query", handlers: feature.queryHandlers },
+    { kind: "stream" as const, label: "Stream", handlers: feature.streamHandlers },
+  ];
+  for (const { kind, label, handlers } of kinds) {
+    for (const [name, handler] of Object.entries(handlers)) {
+      if (!handler.access) {
+        throw new Error(
+          `${label} handler "${feature.name}:${kind}:${name}" is missing an access rule. ` +
+            `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
+        );
+      }
+      validateAnonymousRateLimit(feature.name, kind, name, handler.access, handler.rateLimit);
     }
-    validateAnonymousRateLimit(feature.name, "stream", name, handler.access, handler.rateLimit);
   }
 }