@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

package/src/api/index.ts

@@ -5,10 +5,10 @@ export type {
   AuthMiddlewareOptions,
   AuthSessionChecker,
   AuthSessionStatus,
-  PatResolver,
   TenantExists,
   TenantLifecycleStatusResolver,
   TenantResolver,
+  TokenVerifier,
 } from "./auth-middleware";
 export { authMiddleware, getUser, PAT_TOKEN_PREFIX } from "./auth-middleware";
 export type {
@@ -34,8 +34,8 @@ export {
   etagMatches,
   parseIfNoneMatch,
 } from "./http-cache";
-export type { JwtHelper, JwtPayload } from "./jwt";
-export { createJwtHelper } from "./jwt";
+export type { JwtHelper, JwtKeyring, JwtPayload } from "./jwt";
+export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt";
 export { patAllows, qnMatches } from "./pat-scope";
 export { type RequestContextData, requestContext } from "./request-context";
 export { requestIdMiddleware } from "./request-id-middleware";

package/src/api/jwt.ts

@@ -23,10 +23,82 @@ export type JwtPayload = {
 export type JwtHelper = {
   sign(user: SessionUser): Promise<string>;
   verify(token: string): Promise<JwtPayload>;
+  // The TTL this helper signs tokens with, in seconds — the single source for
+  // callers (e.g. the auth-cookie's maxAge) that must stay coupled to the JWT's exp.
+  readonly ttlSeconds: number;
 };
 
-export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
-  const encodedSecret = new TextEncoder().encode(secret);
+// kid → secret. All entries verify; `signKid` picks the sign-key. Rotation:
+// add the new kid, flip signKid, keep the old kid around until in-flight
+// tokens expire.
+export type JwtKeyring = {
+  readonly keys: Readonly<Record<string, string>>;
+  readonly signKid: string;
+};
+
+type NormalizedKeyring = {
+  readonly verifyKeys: ReadonlyMap<string, Uint8Array>;
+  readonly signKid: string | undefined;
+  readonly signKey: Uint8Array;
+};
+
+function normalizeKeyring(secretOrKeyring: string | JwtKeyring): NormalizedKeyring {
+  if (typeof secretOrKeyring === "string") {
+    const key = new TextEncoder().encode(secretOrKeyring);
+    return { verifyKeys: new Map(), signKid: undefined, signKey: key };
+  }
+
+  const verifyKeys = new Map<string, Uint8Array>();
+  for (const [kid, secret] of Object.entries(secretOrKeyring.keys)) {
+    verifyKeys.set(kid, new TextEncoder().encode(secret));
+  }
+  const signKey = verifyKeys.get(secretOrKeyring.signKid);
+  if (!signKey) {
+    throw new Error(
+      `createJwtHelper: signKid "${secretOrKeyring.signKid}" is not present in the keyring`,
+    );
+  }
+  return { verifyKeys, signKid: secretOrKeyring.signKid, signKey };
+}
+
+// Tokens carry `kid` in the protected header when signed from a keyring — pick the
+// matching verify-key directly. Tokens without `kid` (single-secret form, or in-flight
+// tokens signed before a rotation) fall back to trying every verify-key.
+async function verifyWithKeyring(token: string, keyring: NormalizedKeyring, issuer: string) {
+  const { kid } = jose.decodeProtectedHeader(token);
+  if (typeof kid === "string" && keyring.verifyKeys.size > 0) {
+    const key = keyring.verifyKeys.get(kid);
+    if (!key) {
+      throw new Error(`JWT verification failed: unknown kid "${kid}"`);
+    }
+    return jose.jwtVerify(token, key, { issuer });
+  }
+
+  // ponytail: tries every key in the ring (O(keys) per legacy-token verify) — fine for a
+  // rotation window of a handful of keys, revisit if the keyring ever grows large.
+  const candidates =
+    keyring.verifyKeys.size > 0 ? [...keyring.verifyKeys.values()] : [keyring.signKey];
+  let lastError: unknown;
+  for (const key of candidates) {
+    try {
+      return await jose.jwtVerify(token, key, { issuer });
+    } catch (err) {
+      lastError = err;
+    }
+  }
+  throw lastError instanceof Error
+    ? lastError
+    : new Error("JWT verification failed: no matching key");
+}
+
+const DEFAULT_JWT_TTL_SECONDS = 24 * 60 * 60;
+
+export function createJwtHelper(
+  secretOrKeyring: string | JwtKeyring,
+  issuer = "kumiko",
+  ttlSeconds = DEFAULT_JWT_TTL_SECONDS,
+): JwtHelper {
+  const keyring = normalizeKeyring(secretOrKeyring);
 
   return {
     async sign(user) {
@@ -36,19 +108,27 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
       };
       if (user.claims) body.claims = { ...user.claims };
 
+      const header: jose.JWTHeaderParameters = keyring.signKid
+        ? { alg: "HS256", kid: keyring.signKid }
+        : { alg: "HS256" };
+
+      // iat/exp share one `now` — jose's setIssuedAt()/setExpirationTime(Date)
+      // each read the clock separately, letting `exp - iat` drift by a
+      // second and making TTL-precision tests flaky.
+      const nowSec = Math.floor(Date.now() / 1000);
       const builder = new jose.SignJWT(body)
-        .setProtectedHeader({ alg: "HS256" })
+        .setProtectedHeader(header)
         .setSubject(String(user.id))
         .setIssuer(issuer)
-        .setIssuedAt()
-        .setExpirationTime("24h");
+        .setIssuedAt(nowSec)
+        .setExpirationTime(nowSec + ttlSeconds);
       if (user.sid) builder.setJti(user.sid);
 
-      return builder.sign(encodedSecret);
+      return builder.sign(keyring.signKey);
     },
 
     async verify(token) {
-      const { payload } = await jose.jwtVerify(token, encodedSecret, { issuer });
+      const { payload } = await verifyWithKeyring(token, keyring, issuer);
 
       // defence-in-depth: valid sig ≠ well-formed claims; malformed payload → throw → 401
       const tenantId = parseTenantId(payload["tenantId"]);
@@ -84,5 +164,66 @@ export function createJwtHelper(secret: string, issuer = "kumiko"): JwtHelper {
       }
       return result;
     },
+    ttlSeconds,
   };
 }
+
+const JWT_KEY_VAR_PATTERN = /^JWT_SECRET_V(\d+)$/;
+const JWT_CURRENT_VERSION_VAR = "JWT_SECRET_CURRENT_VERSION";
+// Mirrors authEmailPasswordEnvSchema's JWT_SECRET.min(32) — HS256 minimum.
+// JWT_SECRET_V<n> bypasses that zod schema entirely (it only validates the
+// plain JWT_SECRET name), so this loader is the only gate for the rotation path.
+const MIN_JWT_SECRET_LENGTH = 32;
+
+function assertMinLength(name: string, value: string): void {
+  if (value.length < MIN_JWT_SECRET_LENGTH) {
+    throw new Error(`[jwt] ${name} must be ≥${MIN_JWT_SECRET_LENGTH} chars (HS256 minimum)`);
+  }
+}
+
+// Env-loader for createJwtHelper's secret-or-keyring param, analog to
+// secrets' loadKeyring: JWT_SECRET_V<n> (+ JWT_SECRET_CURRENT_VERSION picking
+// the active signKid) for rotation, falling back to plain JWT_SECRET when no
+// JWT_SECRET_V<n> is set — so a non-rotating deployment needs no new env vars.
+export function loadJwtSecretOrKeyring(
+  env: Readonly<Record<string, string | undefined>>,
+): string | JwtKeyring {
+  const keys: Record<string, string> = {};
+  for (const [name, value] of Object.entries(env)) {
+    const match = name.match(JWT_KEY_VAR_PATTERN);
+    if (!match || !value) continue;
+    assertMinLength(name, value);
+    // biome-ignore lint/style/noNonNullAssertion: regex group 1 always present
+    keys[`v${match[1]!}`] = value;
+  }
+
+  // skip: no JWT_SECRET_V<n> found — single-secret fallback.
+  if (Object.keys(keys).length === 0) {
+    const secret = env["JWT_SECRET"];
+    if (!secret) {
+      throw new Error(
+        "[jwt] JWT_SECRET not set — set JWT_SECRET for a single key, or " +
+          "JWT_SECRET_V1 (+ JWT_SECRET_CURRENT_VERSION=1) for a rotatable keyring.",
+      );
+    }
+    assertMinLength("JWT_SECRET", secret);
+    return secret;
+  }
+
+  const currentRaw = env[JWT_CURRENT_VERSION_VAR];
+  if (!currentRaw) {
+    throw new Error(
+      `[jwt] ${JWT_CURRENT_VERSION_VAR} not set — explicit current-version required ` +
+        "so adding a new JWT_SECRET_V<n> doesn't auto-promote it to the sign key.",
+    );
+  }
+  const signKid = `v${currentRaw}`;
+  if (!keys[signKid]) {
+    throw new Error(
+      `[jwt] ${JWT_CURRENT_VERSION_VAR}="${currentRaw}" not present in the keyring ` +
+        `(have versions: ${Object.keys(keys).sort().join(", ")}). ` +
+        `Check JWT_SECRET_V${currentRaw} is set.`,
+    );
+  }
+  return { keys, signKid };
+}

package/src/api/pii-leak-guard.ts

@@ -2,7 +2,10 @@ import type { MiddlewareHandler } from "hono";
 import { configuredPiiSubjectKms, PII_CIPHERTEXT_PREFIX } from "../crypto";
 
 const isProductionEnv = () => process.env["NODE_ENV"] === "production";
-const CIPHERTEXT_RE = /kumiko-pii:v1:[^"\s<>\\]*/g;
+// Version-agnostic: catches both the current PII_CIPHERTEXT_PREFIX and any
+// older/decrypt-only format version still present in unmigrated rows.
+const CIPHERTEXT_MARKER = "kumiko-pii:v";
+const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^"\s<>\\]*/g;
 
 // A PII subject ciphertext never belongs in an API response — its presence
 // means a raw DB read (fetchOne/selectMany) leaked to the surface. Dev/test
@@ -19,7 +22,7 @@ export function piiCiphertextResponseGuard(): MiddlewareHandler {
     if (!contentType.includes("application/json")) return;
     const text = await c.res.clone().text();
     // skip: clean response — the common case
-    if (!text.includes(PII_CIPHERTEXT_PREFIX)) return;
+    if (!text.includes(CIPHERTEXT_MARKER)) return;
 
     const detail =
       `[api] JSON response for ${c.req.method} ${c.req.path} contains a PII ciphertext ` +

package/src/api/routes.ts

@@ -1,4 +1,5 @@
 import { type Context, Hono } from "hono";
+import { streamSSE } from "hono/streaming";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import type { SessionUser } from "../engine/types/handlers";
 import {
@@ -16,6 +17,7 @@ import { Routes } from "./api-constants";
 import { getUser } from "./auth-middleware";
 import { patAllows } from "./pat-scope";
 import { requestContext } from "./request-context";
+import { SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route";
 
 export function createApiRoutes(dispatcher: Dispatcher) {
   const api = new Hono();
@@ -121,6 +123,61 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     }
   });
 
+  // Dispatcher-driven SSE, full auth/CSRF/rate-limit chain (unlike the
+  // broker-based /sse route). Frame contract for clients: "chunk" (one per
+  // yielded value, JSON-encoded), "ping" (heartbeat, empty data), "done"
+  // (terminal, empty data), "error" (terminal, JSON error envelope — the
+  // response status stays 200 since SSE headers are already flushed before
+  // dispatch gates run on the generator's first pull).
+  api.post(Routes.stream, async (c) => {
+    const user = getUser(c);
+    const body = await c.req.json<{ type: string; payload: unknown }>();
+    const requestId = requestContext.get()?.requestId;
+
+    try {
+      assertPatAllowed(user, body.type);
+    } catch (e) {
+      return queryErrorResponse(c, toKumiko(e), body.type);
+    }
+
+    return streamSSE(c, async (stream) => {
+      const generator = dispatcher.stream(body.type, body.payload, user);
+      stream.onAbort(() => {
+        void generator.return(undefined);
+      });
+
+      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: "" });
+      } catch (e) {
+        const err = toKumiko(e);
+        logServerFault(err, requestId, body.type);
+        const { error } = serializeError(err, requestId);
+        await stream.writeSSE({ event: "error", data: stringifyJson(error) });
+      }
+    });
+  });
+
   return api;
 }
 

package/src/api/server.ts

@@ -50,7 +50,7 @@ import { PUBLIC_API_PATHS } from "./api-constants";
 import { type AnonymousAccessConfig, authMiddleware, getUser } from "./auth-middleware";
 import { type AuthRoutesConfig, createAuthRoutes } from "./auth-routes";
 import { csrfMiddleware } from "./csrf-middleware";
-import { createJwtHelper, type JwtHelper } from "./jwt";
+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";
@@ -69,8 +69,13 @@ import { createSseRoute } from "./sse-route";
 export type ServerOptions = {
   registry: Registry;
   context: AppContext;
-  jwtSecret: string;
+  jwtSecret: string | JwtKeyring;
   jwtIssuer?: string;
+  // JWT lifetime in seconds. Explicit always wins. When omitted, the default
+  // depends on `auth.sessionChecker`: wired (revocation possible) keeps the
+  // long-lived 24h default; unwired (stateless JWTs, no revocation) drops to
+  // 1h so a leaked stateless token has a much smaller exposure window.
+  jwtTtl?: number;
   dispatcherOptions?: Omit<DispatcherOptions, "lifecycle">;
   systemHooks?: SystemHooks;
   eventDedup?: EventDedup;
@@ -94,6 +99,8 @@ export type ServerOptions = {
     pollIntervalMs?: number;
     batchSize?: number;
     maxAttempts?: number;
+    rearmCooldownMs?: number;
+    maxRearmCount?: number;
     // Opt out of building the dispatcher even if consumers exist — e.g. ops
     // runs a dedicated dispatcher process, or a test needs to control the
     // consumer lifecycle manually.
@@ -238,7 +245,15 @@ export function buildServer(options: ServerOptions): KumikoServer {
     );
   }
 
-  const jwt = createJwtHelper(options.jwtSecret, options.jwtIssuer);
+  // Stateless JWTs (no sessionChecker → no revocation) default to a shorter
+  // TTL than session-backed ones, since a leaked stateless token can't be
+  // revoked and stays valid until it expires. Explicit jwtTtl always wins.
+  const defaultJwtTtl = options.auth?.sessionChecker ? 24 * 60 * 60 : 60 * 60;
+  const jwt = createJwtHelper(
+    options.jwtSecret,
+    options.jwtIssuer,
+    options.jwtTtl ?? defaultJwtTtl,
+  );
   const sseBroker = options.sseBroker ?? createSseBroker();
 
   // Resolve the per-process instance identifier. Prefer explicit
@@ -566,8 +581,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // middleware can reject revoked sids on every request.
   const jwtGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
-    ...(options.auth?.sessionStrictMode ? { strictMode: options.auth.sessionStrictMode } : {}),
-    ...(options.auth?.patResolver ? { patResolver: options.auth.patResolver } : {}),
+    ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
     ...(options.auth?.resolveTenantLifecycleStatus
       ? { resolveTenantLifecycleStatus: options.auth.resolveTenantLifecycleStatus }
       : {}),

package/src/bun-db/__tests__/select-many-retry.test.ts

@@ -0,0 +1,79 @@
+// #1163: Bun.SQL can hand out a closed connection under load (AbortError
+// "The connection was closed."). Pure reads retry exactly once on a fresh
+// pool checkout; tx handles, non-matching errors, and genuine user aborts
+// must NOT retry.
+
+import { describe, expect, test } from "bun:test";
+import { buildEntityTable } from "../../db/table-builder";
+import { selectMany } from "../query";
+
+function closedConnectionError(): Error {
+  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
+}
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin?: () => never;
+  calls: number;
+};
+
+function fakeClient(failures: Error[], opts: { tx?: boolean } = {}): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [{ id: "r1", title: "ok", tenant_id: "t1", inserted_at: null, updated_at: null }];
+    },
+  };
+  // A top-level pool client has begin(); a transaction handle does not.
+  if (!opts.tx)
+    client.begin = () => {
+      throw new Error("not used in test");
+    };
+  return client;
+}
+
+const table = buildEntityTable("note", {
+  fields: { title: { type: "text", required: true } },
+});
+
+describe("selectMany — closed-connection retry (#1163)", () => {
+  test("retries once on AbortError 'connection was closed' and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()]);
+    const rows = await selectMany(db, table);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.title).toBe("ok");
+    expect(db.calls).toBe(2);
+  });
+
+  test("gives up after the single retry when the connection stays closed", async () => {
+    const db = fakeClient([closedConnectionError(), closedConnectionError()]);
+    await expect(selectMany(db, table)).rejects.toThrow("connection was closed");
+    expect(db.calls).toBe(2);
+  });
+
+  test("never retries on a transaction handle (no begin)", async () => {
+    const db = fakeClient([closedConnectionError()], { tx: true });
+    await expect(selectMany(db, table)).rejects.toThrow("connection was closed");
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry a genuine user abort (different message)", async () => {
+    const userAbort = Object.assign(new Error("The operation was aborted."), {
+      name: "AbortError",
+    });
+    const db = fakeClient([userAbort]);
+    await expect(selectMany(db, table)).rejects.toThrow("operation was aborted");
+    expect(db.calls).toBe(1);
+  });
+
+  test("does not retry generic query errors", async () => {
+    const syntax = Object.assign(new Error("syntax error at or near"), { name: "PostgresError" });
+    const db = fakeClient([syntax]);
+    await expect(selectMany(db, table)).rejects.toThrow("syntax error");
+    expect(db.calls).toBe(1);
+  });
+});

package/src/bun-db/query.ts

@@ -19,6 +19,11 @@
 //     drizzle's getTableName + getTableColumns (drizzle weiterhin als type-
 //     reference, NICHT als runtime-API-call)
 
+import type {
+  SelectOptions,
+  WhereObject,
+  WhereOperator,
+} from "@cosmicdrift/kumiko-types/where-clause-types";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index";
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
@@ -183,19 +188,13 @@ function assertNotTenantScoped(db: unknown, fnName: string): void {
 
 export type AnyDb = BunDbRunner | unknown;
 
-// WhereValue: primitive für eq, array für IN, null für IS NULL, oder
-// operator-object für range/comparisons.
-export type WhereOperator = {
-  readonly gt?: unknown;
-  readonly gte?: unknown;
-  readonly lt?: unknown;
-  readonly lte?: unknown;
-  readonly ne?: unknown;
-  readonly in?: readonly unknown[];
-  readonly like?: string;
-};
-export type WhereValue = unknown | WhereOperator;
-export type WhereObject = Record<string, WhereValue>;
+export type {
+  OrderByClause,
+  SelectOptions,
+  WhereObject,
+  WhereOperator,
+  WhereValue,
+} from "@cosmicdrift/kumiko-types/where-clause-types";
 
 function isWhereOperator(v: unknown): v is WhereOperator {
   if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
@@ -206,18 +205,6 @@ function isWhereOperator(v: unknown): v is WhereOperator {
   const opKeys = ["gt", "gte", "lt", "lte", "ne", "in", "like"];
   return keys.every((k) => opKeys.includes(k));
 }
-export type OrderByClause = {
-  readonly col: string;
-  readonly direction?: "asc" | "desc";
-};
-
-export type SelectOptions = {
-  readonly limit?: number;
-  // Single column or array for multi-column tie-breaks (e.g.
-  // [{col: "createdAt"}, {col: "id"}] for chronological-with-stable-id).
-  readonly orderBy?: OrderByClause | readonly OrderByClause[];
-};
-
 // Akzeptiert EITHER. Beide haben einen tableName und field→column-mapping.
 // biome-ignore lint/suspicious/noExplicitAny: legacy drizzle pgTable surface
 type TableLike = EntityTableMeta | any;
@@ -562,6 +549,38 @@ function buildWhereClause(
   return { sqlText: conditions.join(" AND "), values };
 }
 
+// #1163: under load the Bun.SQL pool can hand out a connection the server
+// already closed ("The connection was closed.", AbortError code 20) — no
+// validate-on-checkout exists. One retry re-checks out a fresh connection;
+// safe for pure reads. Tx handles are never retried: their transaction is
+// dead once the connection dropped, and a retry would run on the same dead
+// handle. Detection is name+message (not name alone) so a genuine user
+// abort (AbortSignal cancel) is NOT retried.
+function isClosedConnectionError(err: unknown): boolean {
+  if (err === null || typeof err !== "object") return false;
+  const e = err as { name?: unknown; message?: unknown };
+  return (
+    e.name === "AbortError" &&
+    typeof e.message === "string" &&
+    /connection was closed/i.test(e.message)
+  );
+}
+
+async function unsafeRead<TRow>(
+  db: AnyDb,
+  sqlText: string,
+  params: readonly unknown[],
+): Promise<readonly TRow[]> {
+  const raw = asRawClient(db);
+  try {
+    return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+  } catch (err) {
+    // TransactionSql has savepoint(), only a top-level pool client has begin().
+    if (typeof raw.begin !== "function" || !isClosedConnectionError(err)) throw err;
+    return (await raw.unsafe(sqlText, params)) as readonly TRow[];
+  }
+}
+
 // biome-ignore lint/suspicious/noExplicitAny: opt-in default loosens row type for unannotated test fixtures
 export async function selectMany<TRow = any>(
   db: AnyDb,
@@ -598,7 +617,7 @@ export async function selectMany<TRow = any>(
     }
     sqlText += ` LIMIT ${options.limit}`;
   }
-  const raw = (await asRawClient(db).unsafe(sqlText, values)) as readonly Record<string, unknown>[];
+  const raw = (await unsafeRead(db, sqlText, values)) as readonly Record<string, unknown>[];
   return coerceRows(raw, info) as readonly TRow[];
 }
 
@@ -832,7 +851,7 @@ export async function countWhere(
     sqlText += ` WHERE ${w.sqlText}`;
     values = w.values;
   }
-  const rows = (await asRawClient(db).unsafe(sqlText, values)) as readonly { count: number }[];
+  const rows = (await unsafeRead(db, sqlText, values)) as readonly { count: number }[];
   return rows[0]?.count ?? 0;
 }
 

package/src/consumer-cli.ts

@@ -0,0 +1,87 @@
+// Shared core for the standalone consumer-ops CLI (status | restart).
+//
+// A dead event consumer (halt-on-poison after maxAttempts) previously had no
+// recovery surface in the standalone prod bundle — only raw SQL against
+// kumiko_event_consumers. Mirrors schema-cli.ts's shape (single runXCli(argv,
+// out) entry point, own DB connection) so `kumiko-consumer` ships the same
+// way `kumiko-schema` does.
+
+import { createDbConnection } from "./db";
+import { getConsumerState, restartConsumer } from "./pipeline";
+import { ensureTemporalPolyfill } from "./time";
+
+export type ConsumerCliOut = {
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+};
+
+function parseInstanceIdFlag(argv: readonly string[]): string | undefined {
+  const i = argv.indexOf("--instance-id");
+  return i === -1 ? undefined : argv[i + 1];
+}
+
+export async function runConsumerCli(
+  argv: readonly string[],
+  out: ConsumerCliOut,
+): Promise<number> {
+  // The standalone bundle never runs runProdApp/runDevApp's boot, which is
+  // where Temporal normally gets installed — ConsumerRecoveryState.updatedAt
+  // is a Temporal.Instant, so without this every subcommand throws "Temporal
+  // is not defined" (same failure mode as schema-cli, see its polyfill test).
+  await ensureTemporalPolyfill();
+  const sub = argv[0];
+
+  if (sub !== "status" && sub !== "restart") {
+    out.log("");
+    out.log("  Subcommands:");
+    out.log("    status <name> [--instance-id <id>]   Zeigt Status + Cursor eines Consumers");
+    out.log("    restart <name> [--instance-id <id>]  Reaktiviert einen dead-Consumer (idle)");
+    out.log("");
+    return sub === undefined ? 0 : 1;
+  }
+
+  const name = argv[1];
+  if (!name) {
+    out.err(`  Usage: consumer ${sub} <name> [--instance-id <id>]`);
+    return 1;
+  }
+  const instanceId = parseInstanceIdFlag(argv);
+
+  const dbUrl = process.env["DATABASE_URL"];
+  if (!dbUrl) {
+    out.err("  DATABASE_URL not set.");
+    return 1;
+  }
+  const { db, close } = createDbConnection(dbUrl);
+  try {
+    if (sub === "status") {
+      const state = await getConsumerState(db, name, instanceId);
+      if (!state) {
+        out.err(`  Consumer "${name}" (instance_id="${instanceId ?? "__shared__"}") not found.`);
+        return 1;
+      }
+      out.log("");
+      out.log(`  ${state.name} (instance_id="${state.instanceId}")`);
+      out.log(`    status:      ${state.status}`);
+      out.log(`    cursor:      ${state.lastProcessedEventId}`);
+      out.log(`    attempts:    ${state.attempts}`);
+      out.log(`    rearmCount:  ${state.rearmCount}`);
+      out.log(`    lastError:   ${state.lastError ?? "-"}`);
+      out.log(`    updatedAt:   ${state.updatedAt.toString()}`);
+      out.log("");
+      return 0;
+    }
+
+    // restart
+    const result = await restartConsumer(db, name, instanceId);
+    out.log("");
+    out.log(`  ✓ ${result.name} (instance_id="${result.instanceId}") → ${result.status}`);
+    out.log("");
+    return 0;
+  } catch (e) {
+    out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  } finally {
+    await close();
+  }
+}