@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.158.2",
+  "version": "0.160.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>",
@@ -147,6 +147,10 @@
       "types": "./src/schema-cli.ts",
       "default": "./src/schema-cli.ts"
     },
+    "./consumer-cli": {
+      "types": "./src/consumer-cli.ts",
+      "default": "./src/consumer-cli.ts"
+    },
     "./stack": {
       "types": "./src/stack/index.ts",
       "default": "./src/stack/index.ts"
@@ -178,6 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@cosmicdrift/kumiko-types": "0.160.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.18",
@@ -193,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.158.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.160.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -0,0 +1,110 @@
+// Integration test for `runConsumerCli` (kumiko-framework#1351).
+//
+// Recovery semantics themselves are already covered by
+// event-dispatcher-recovery — this only exercises the CLI layer: argv
+// parsing, DB-connection handling, exit codes, output formatting.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../bun-db/__tests__/bun-test-db";
+import { type ConsumerCliOut, runConsumerCli } from "../consumer-cli";
+import { insertConsumerIfAbsent, markConsumerRebuildFailed } from "../db/queries/event-consumer";
+import { asRawClient } from "../db/query";
+import { createEventConsumerStateTable } from "../pipeline";
+import { ensureTemporalPolyfill } from "../time/polyfill";
+
+const SHARED = "__shared__";
+
+let testDb: BunTestDb;
+let testUrl: string;
+let prevDbUrl: string | undefined;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  const baseUrl = process.env["TEST_DATABASE_URL"];
+  if (!baseUrl) throw new Error("TEST_DATABASE_URL not set — required for this test file");
+  testUrl = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+  await createEventConsumerStateTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+afterEach(async () => {
+  await asRawClient(testDb.db).unsafe(`TRUNCATE TABLE "kumiko_event_consumers"`);
+  if (prevDbUrl === undefined) delete process.env["DATABASE_URL"];
+  else process.env["DATABASE_URL"] = prevDbUrl;
+});
+
+function captureOut(): { out: ConsumerCliOut; lines: string[] } {
+  const lines: string[] = [];
+  return {
+    out: { log: (l: string) => lines.push(l), err: (l: string) => lines.push(`ERR ${l}`) },
+    lines,
+  };
+}
+
+describe("runConsumerCli status", () => {
+  test("unknown consumer → exit 1, not-found message", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "no-such-consumer"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("not found");
+  });
+
+  test("known consumer → exit 0, reports status/cursor/attempts", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:foo", SHARED);
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "test:consumer:foo"], out);
+    expect(code).toBe(0);
+    const joined = lines.join("\n");
+    expect(joined).toContain("test:consumer:foo");
+    expect(joined).toContain("status:      idle");
+  });
+
+  test("missing <name> → exit 1, usage message", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("Usage:");
+  });
+
+  test("missing DATABASE_URL → exit 1", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    delete process.env["DATABASE_URL"];
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["status", "whatever"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("DATABASE_URL not set");
+  });
+});
+
+describe("runConsumerCli restart", () => {
+  test("dead consumer → idle, exit 0", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:bar", SHARED);
+    await markConsumerRebuildFailed(testDb.db, "test:consumer:bar", SHARED, "boom");
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["restart", "test:consumer:bar"], out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain("→ idle");
+  });
+
+  test("non-dead consumer → propagated error, exit 1", async () => {
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = testUrl;
+    await insertConsumerIfAbsent(testDb.db, "test:consumer:baz", SHARED);
+    const { out, lines } = captureOut();
+    const code = await runConsumerCli(["restart", "test:consumer:baz"], out);
+    expect(code).toBe(1);
+    expect(lines.join("\n")).toContain("not dead");
+  });
+});

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

@@ -28,6 +28,17 @@ const testFeature = defineFeature("test", (r) => {
     async () => [{ id: 1, name: "Test" }],
     { access: { openToAll: true } },
   );
+
+  r.streamHandler(
+    "item:tail",
+    z.object({ count: z.number().int().min(0) }),
+    async function* (query) {
+      for (let i = 0; i < query.payload.count; i++) {
+        yield { i };
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
 });
 
 const registry = createRegistry([testFeature]);
@@ -215,6 +226,60 @@ describe("GET /api/sse", () => {
   });
 });
 
+// --- Stream (dispatcher-driven SSE) ---
+
+function parseSseFrames(text: string): Array<{ event: string; data: string }> {
+  return text
+    .split("\n\n")
+    .filter((frame) => frame.trim().length > 0)
+    .map((frame) => {
+      const event = /^event: (.*)$/m.exec(frame)?.[1] ?? "";
+      const data = /^data: (.*)$/m.exec(frame)?.[1] ?? "";
+      return { event, data };
+    });
+}
+
+describe("POST /api/stream", () => {
+  test("dispatches stream handler and yields chunk frames then done", async () => {
+    const headers = await authHeader(adminUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: { count: 3 } },
+      headers,
+    );
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
+    const frames = parseSseFrames(await res.text());
+    expect(frames).toEqual([
+      { event: "chunk", data: JSON.stringify({ i: 0 }) },
+      { event: "chunk", data: JSON.stringify({ i: 1 }) },
+      { event: "chunk", data: JSON.stringify({ i: 2 }) },
+      { event: "done", data: "" },
+    ]);
+  });
+
+  test("access-denied gate surfaces as an error frame, not an HTTP error status", async () => {
+    // Dispatch gates (feature/rate-limit/access/validation) fire on the
+    // generator's first pull, which happens after SSE headers are already
+    // flushed — so an access-denied mid-stream stays HTTP 200.
+    const headers = await authHeader(guestUser);
+    const res = await req(
+      "POST",
+      "/api/stream",
+      { type: "test:stream:item:tail", payload: { count: 1 } },
+      headers,
+    );
+
+    expect(res.status).toBe(200);
+    const frames = parseSseFrames(await res.text());
+    expect(frames).toHaveLength(1);
+    expect(frames[0]?.event).toBe("error");
+    expect(JSON.parse(frames[0]?.data ?? "{}")).toMatchObject({ code: "access_denied" });
+  });
+});
+
 // --- r.httpRoute (feature-deklarierte HTTP-Routes außerhalb /api/) ---
 
 describe("feature-declared HTTP routes (r.httpRoute)", () => {

package/src/api/__tests__/auth-routes-cookie.test.ts

@@ -37,6 +37,7 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async query(): Promise<unknown> {
       return [];
     },
+    async *stream(): AsyncGenerator<unknown> {},
     async command(): Promise<void> {},
     async batch(): Promise<BatchResult> {
       const ok: BatchResult = { isSuccess: true, results: [] };
@@ -52,8 +53,11 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
 async function buildApp(
   overrides: Partial<AuthRoutesConfig> = {},
   dispatcher: Dispatcher = createStubDispatcher(),
+  ttlSeconds?: number,
 ): Promise<{ app: Hono; validToken: string }> {
-  const jwt = createJwtHelper(JWT_SECRET);
+  const jwt = ttlSeconds
+    ? createJwtHelper(JWT_SECRET, undefined, ttlSeconds)
+    : createJwtHelper(JWT_SECRET);
   const validToken = await jwt.sign(TestUsers.user);
   const config: AuthRoutesConfig = {
     membershipQuery: "tenant:query:memberships",
@@ -128,6 +132,18 @@ describe("auth-routes cookie behaviour on /auth/login", () => {
     expect(typeof body.token).toBe("string");
     expect(body.token.length).toBeGreaterThan(20);
   });
+
+  test("cookie maxAge tracks the jwt helper's ttlSeconds, not a hardcoded default", async () => {
+    const customTtl = 60 * 60; // 1h — distinct from the 24h default
+    const { app } = await buildApp({}, undefined, customTtl);
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(new RegExp(`Max-Age=${customTtl}\\b`));
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).toMatch(new RegExp(`Max-Age=${customTtl}\\b`));
+  });
 });
 
 describe("auth-routes cookie behaviour on /auth/logout", () => {

package/src/api/__tests__/auth-routes-invalid-body-invite.test.ts

@@ -0,0 +1,237 @@
+// auth-routes invalid_body + invite-accept success paths — HTTP-layer only,
+// stub Dispatcher (same pattern as auth-routes-mfa-verify.test.ts).
+
+import { describe, expect, test } from "bun:test";
+import type { Hono } from "hono";
+import { Hono as HonoCtor } from "hono";
+import type { SessionUser, TenantId } from "../../engine/types";
+import type { BatchResult, Dispatcher, WriteResult } from "../../pipeline/dispatcher";
+import { TestUsers } from "../../stack";
+import { getSetCookies } from "../../testing/http-cookies";
+import { PUBLIC_API_PATHS } from "../api-constants";
+import { AUTH_COOKIE_NAME, authMiddleware, CSRF_COOKIE_NAME } from "../auth-middleware";
+import { type AuthRoutesConfig, createAuthRoutes } from "../auth-routes";
+import { createJwtHelper } from "../jwt";
+
+const JWT_SECRET = "auth-routes-invalid-body-invite-secret-min-32-chars";
+const INVITE_ACCEPT_QN = "auth:write:invite-accept";
+const INVITE_LOGIN_QN = "auth:write:invite-accept-with-login";
+
+function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
+  const base: Dispatcher = {
+    async write(): Promise<WriteResult> {
+      const ok: WriteResult = { isSuccess: true, data: { kind: "noop" } };
+      return ok;
+    },
+    async query(): Promise<unknown> {
+      return [];
+    },
+    async command(): Promise<void> {},
+    async batch(): Promise<BatchResult> {
+      return { isSuccess: true, results: [] };
+    },
+    async resolveAuthClaims(): Promise<Record<string, unknown>> {
+      return {};
+    },
+    // Stream API added with r.streamHandler (#1446) — stub unused in these routes.
+    async *stream(): AsyncGenerator<unknown> {},
+  };
+  return { ...base, ...overrides };
+}
+
+async function buildApp(
+  overrides: Partial<AuthRoutesConfig> = {},
+  dispatcher: Dispatcher = createStubDispatcher(),
+): Promise<{ app: Hono; validToken: string }> {
+  const jwt = createJwtHelper(JWT_SECRET);
+  const validToken = await jwt.sign(TestUsers.user);
+  const config: AuthRoutesConfig = {
+    membershipQuery: "tenant:query:memberships",
+    loginHandler: "auth:write:login",
+    loginRateLimit: null,
+    ...overrides,
+  };
+  const app = new HonoCtor();
+  const jwtGuard = authMiddleware(jwt);
+  app.use("/api/*", async (c, next) => {
+    if (PUBLIC_API_PATHS.has(c.req.path)) return next();
+    return jwtGuard(c, next);
+  });
+  app.route("/api", createAuthRoutes(dispatcher, jwt, config));
+  return { app, validToken };
+}
+
+const inviteConfig: AuthRoutesConfig["invite"] = {
+  acceptHandler: INVITE_ACCEPT_QN,
+  acceptWithLoginHandler: INVITE_LOGIN_QN,
+  signupCompleteHandler: "auth:write:invite-signup-complete",
+};
+
+describe("POST /auth/login — invalid_body", () => {
+  test("400 when password field is missing", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return { isSuccess: true, data: { kind: "auth-session", session: TestUsers.user } };
+      },
+    });
+    const { app } = await buildApp({}, dispatcher);
+    const res = await app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c" }),
+    });
+    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);
+  });
+});
+
+describe("POST /auth/invite-accept", () => {
+  test("requires JWT — not a public route", async () => {
+    expect(PUBLIC_API_PATHS.has("/api/auth/invite-accept")).toBe(false);
+  });
+
+  test("400 invalid_body before dispatch", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return {
+          isSuccess: true,
+          data: {
+            kind: "invite-accepted",
+            tenantId: TestUsers.otherTenant.tenantId,
+            role: "User",
+            alreadyMember: false,
+          },
+        };
+      },
+    });
+    const { app, validToken } = await buildApp({ invite: inviteConfig }, dispatcher);
+    const res = await app.request("/api/auth/invite-accept", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${validToken}`,
+      },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+    expect((await res.json()) as { isSuccess: boolean; error: string }).toMatchObject({
+      isSuccess: false,
+      error: "invalid_body",
+    });
+    expect(dispatched).toBe(false);
+  });
+
+  test("success returns tenantId, role, alreadyMember", async () => {
+    const tenantId = TestUsers.otherTenant.tenantId as TenantId;
+    let receivedUser: SessionUser | undefined;
+    const dispatcher = createStubDispatcher({
+      async write(qn, payload, user): Promise<WriteResult> {
+        expect(qn).toBe(INVITE_ACCEPT_QN);
+        expect(payload).toEqual({ token: "invite-token-abc" });
+        receivedUser = user;
+        return {
+          isSuccess: true,
+          data: {
+            kind: "invite-accepted",
+            tenantId,
+            role: "Editor",
+            alreadyMember: true,
+          },
+        };
+      },
+    });
+    const { app, validToken } = await buildApp({ invite: inviteConfig }, dispatcher);
+    const res = await app.request("/api/auth/invite-accept", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${validToken}`,
+      },
+      body: JSON.stringify({ token: "invite-token-abc" }),
+    });
+    expect(res.status).toBe(200);
+    expect(receivedUser?.id).toBe(TestUsers.user.id);
+    expect(await res.json()).toEqual({
+      isSuccess: true,
+      tenantId,
+      role: "Editor",
+      alreadyMember: true,
+    });
+  });
+});
+
+describe("POST /auth/invite-accept-with-login — invalid_body + success", () => {
+  test("400 when email missing", async () => {
+    let dispatched = false;
+    const dispatcher = createStubDispatcher({
+      async write(): Promise<WriteResult> {
+        dispatched = true;
+        return { isSuccess: true, data: { kind: "auth-session", session: TestUsers.user } };
+      },
+    });
+    const { app } = await buildApp({ invite: inviteConfig }, dispatcher);
+    const res = await app.request("/api/auth/invite-accept-with-login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token: "t", password: "long-enough-pw" }),
+    });
+    expect(res.status).toBe(400);
+    expect((await res.json()) as { error: string }).toMatchObject({
+      isSuccess: false,
+      error: "invalid_body",
+    });
+    expect(dispatched).toBe(false);
+  });
+
+  test("success mints JWT + cookies", async () => {
+    const tenantId = TestUsers.otherTenant.tenantId as TenantId;
+    const dispatcher = createStubDispatcher({
+      async write(qn, payload): Promise<WriteResult> {
+        expect(qn).toBe(INVITE_LOGIN_QN);
+        expect(payload).toEqual({
+          token: "invite-t",
+          email: "user@example.com",
+          password: "password123",
+        });
+        return {
+          isSuccess: true,
+          data: {
+            kind: "auth-session",
+            session: TestUsers.user,
+            tenantId,
+            role: "User",
+          },
+        };
+      },
+    });
+    const { app } = await buildApp({ invite: inviteConfig }, dispatcher);
+    const res = await app.request("/api/auth/invite-accept-with-login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        token: "invite-t",
+        email: "user@example.com",
+        password: "password123",
+      }),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      isSuccess: boolean;
+      token: string;
+      tenantId: TenantId;
+      role: string;
+    };
+    expect(body.isSuccess).toBe(true);
+    expect(typeof body.token).toBe("string");
+    expect(body.tenantId).toBe(tenantId);
+    expect(body.role).toBe("User");
+    expect(getSetCookies(res).get(AUTH_COOKIE_NAME)).toBeDefined();
+    expect(getSetCookies(res).get(CSRF_COOKIE_NAME)).toBeDefined();
+  });
+});

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

@@ -36,6 +36,7 @@ function createStubDispatcher(overrides?: Partial<Dispatcher>): Dispatcher {
     async query(): Promise<unknown> {
       return [];
     },
+    async *stream(): AsyncGenerator<unknown> {},
     async command(): Promise<void> {},
     async batch(): Promise<BatchResult> {
       const ok: BatchResult = { isSuccess: true, results: [] };

package/src/api/__tests__/csrf-constants-sync.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import {
+  CSRF_COOKIE_NAME as DISPATCHER_CSRF_COOKIE_NAME,
+  CSRF_HEADER_NAME as DISPATCHER_CSRF_HEADER_NAME,
+} from "@cosmicdrift/kumiko-dispatcher-live";
+import { CSRF_COOKIE_NAME, CSRF_HEADER_NAME } from "../auth-middleware";
+
+// dispatcher-live keeps its own literal copies of these two constants
+// (see packages/dispatcher-live/src/csrf.ts) because it must stay
+// server-dep-free for browser/React Native bundles. This test is the
+// guardrail that catches drift in CI instead of at runtime.
+describe("CSRF constant sync between framework and dispatcher-live", () => {
+  test("cookie name matches", () => {
+    expect(DISPATCHER_CSRF_COOKIE_NAME).toBe(CSRF_COOKIE_NAME);
+  });
+
+  test("header name matches", () => {
+    expect(DISPATCHER_CSRF_HEADER_NAME).toBe(CSRF_HEADER_NAME);
+  });
+});

package/src/api/__tests__/dispatcher-live.integration.test.ts

@@ -48,6 +48,17 @@ const itemFeature = defineFeature("dlive", (r) => {
     },
     { access: { roles: ["Admin"] } },
   );
+
+  r.streamHandler(
+    "item:tail",
+    z.object({ count: z.number().int().min(0) }),
+    async function* (query) {
+      for (let i = 0; i < query.payload.count; i++) {
+        yield { i, name: `n-${i}` };
+      }
+    },
+    { access: { roles: ["Admin"] } },
+  );
 });
 
 let stack: TestStack;
@@ -215,4 +226,67 @@ describe("dispatcher-live (integration) — full path against Kumiko server", ()
     const rows = await selectMany(stack.db, itemTable);
     expect(rows).toHaveLength(0);
   });
+
+  test("stream: yields every chunk then completes (live dispatcher ↔ POST /api/stream)", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    const chunks: Array<{ i: number; name: string }> = [];
+    for await (const chunk of dispatcher.stream<{ i: number; name: string }>(
+      "dlive:stream:item:tail",
+      { count: 3 },
+    )) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks).toEqual([
+      { i: 0, name: "n-0" },
+      { i: 1, name: "n-1" },
+      { i: 2, name: "n-2" },
+    ]);
+  });
+
+  test("stream: access-denied mid-stream throws mapped DispatcherError (HTTP still 200 SSE)", async () => {
+    // Non-Admin JWT — stream handler requires Admin. Gate fires after SSE
+    // headers are flushed, so the client sees an error frame, not HTTP 403.
+    const csrfToken = generateToken();
+    const guestJwt = await stack.jwt.sign(TestUsers.user);
+    const cookieHeader = `kumiko_auth=${guestJwt}; kumiko_csrf=${csrfToken}`;
+    const fetchImpl = (async (url: unknown, init: RequestInit | undefined) => {
+      return stack.app.request(String(url), {
+        ...(init ?? {}),
+        headers: { ...(init?.headers ?? {}), Cookie: cookieHeader },
+      });
+    }) as unknown as typeof fetch;
+    const dispatcher = createLiveDispatcher({ fetch: fetchImpl, readCsrf: () => csrfToken });
+
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream("dlive:stream:item:tail", { count: 1 })) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "access_denied" });
+  });
+
+  test("stream: validation failure throws mapped DispatcherError from error frame", async () => {
+    const { fetch, csrfToken } = await buildFetch();
+    const dispatcher = createLiveDispatcher({ fetch, readCsrf: () => csrfToken });
+
+    let thrown: unknown;
+    try {
+      for await (const _ of dispatcher.stream("dlive:stream:item:tail", { count: -1 })) {
+        // should not yield
+      }
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toMatchObject({ code: "validation_error" });
+  });
+
+  // AbortSignal mid-stream against Hono's in-memory `app.request` is
+  // unreliable (body often fully buffered before abort lands). Abort
+  // mapping for stream is covered in dispatcher-live unit tests.
 });