@cosmicdrift/kumiko-framework 0.312.0 → 0.314.0

package/package.json

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

package/src/__tests__/upgrade-cli.test.ts

@@ -564,6 +564,34 @@ describe("upgrade command — filter baseline is the marker, not the installed v
     // rather than filtered out entirely by a too-high baseline.
     expect(updatedMarker.version).toBe("0.188.0");
     expect(updatedMarker.version).not.toBe("0.195.0");
+    expect(spy.logs.join("\n")).toContain(
+      "Marker moved past the manual change(s) above to 0.188.0",
+    );
+  });
+
+  test("a manual breaking change is acknowledged by a second --apply after the first one held the marker back", async () => {
+    const fixEntry = { version: "0.310.0", type: "fix", title: "earlier fix" };
+    const manualEntry = { version: "0.311.0", type: "breaking", title: "manual breaking change" };
+    const cwd = tmp({
+      "packages/framework/src/changes.json": JSON.stringify([fixEntry, manualEntry]),
+      "packages/bundled-features/package.json": JSON.stringify({ version: "0.311.0" }),
+      ".kumiko/upgrade-state.json": marker("0.309.0"),
+    });
+    const markerPath = join(cwd, ".kumiko/upgrade-state.json");
+
+    const firstRun = makeSpyOutput();
+    expect(await runUpgradeCli(["--apply"], cwd, firstRun.out, { repoRoot: REAL_REPO_ROOT })).toBe(
+      0,
+    );
+    expect(JSON.parse(readFileSync(markerPath, "utf-8")).version).toBe("0.310.0");
+    expect(firstRun.logs.join("\n")).toContain("Marker stays at 0.310.0");
+
+    const secondRun = makeSpyOutput();
+    expect(await runUpgradeCli(["--apply"], cwd, secondRun.out, { repoRoot: REAL_REPO_ROOT })).toBe(
+      0,
+    );
+    expect(secondRun.logs.join("\n")).toContain("no codemod, manual migration required");
+    expect(JSON.parse(readFileSync(markerPath, "utf-8")).version).toBe("0.311.0");
   });
 
   test("bare --apply with no marker (bootstrap): behaves as before, marker is written at the installed version", async () => {

package/src/api/__tests__/origin-middleware.integration.test.ts

@@ -9,8 +9,10 @@
 // rejected them (guards return 403).
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";
-import { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, CSRF_HEADER_NAME } from "../auth-middleware";
+import { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, getUser } from "../auth-middleware";
 
 const ALLOWED = "https://admin.example.eu";
 const DISALLOWED = "https://tenant.example.eu";
@@ -130,3 +132,142 @@ describe("origin-middleware opt-out (unsafeSkipOriginCheck)", () => {
     expect(await errorCode(res)).toBe("csrf_token_mismatch");
   });
 });
+
+// The "without anonymousAccess" case (disallowed origin → 403) is already
+// covered above by the first describe block's server config, minus
+// anonymousAccess — not repeated here.
+const anonEchoQuery = { type: "origin-anon-probe:query:anon-echo", payload: {} };
+const userOnlyRoute = { type: "origin-anon-probe:write:user-only", payload: {} };
+const probeFeature = defineFeature("origin-anon-probe", (r) => {
+  r.queryHandler({
+    name: "anon-echo",
+    schema: z.object({}),
+    access: { roles: ["anonymous"] },
+    handler: async (event) => ({ userId: event.user.id, roles: event.user.roles }),
+  });
+  r.writeHandler({
+    name: "user-only",
+    schema: z.object({}),
+    access: { roles: ["User"] },
+    handler: async (event) => ({
+      isSuccess: true as const,
+      data: { userId: event.user.id, roles: event.user.roles },
+    }),
+  });
+  // anonymous:false httpRoutes can't live under /api/* — the boot validator
+  // (feature-ui-extensions.ts) hard-blocks that path prefix for every
+  // feature route, so this is mounted outside /api/* and guarded by
+  // sessionOnlyHttpRouteGuards (sessionOnlyGuard, no foreignCookieOrigins
+  // downgrade) instead of the /api/* jwtGuard used above.
+  r.httpRoute({
+    method: "POST",
+    path: "/origin-anon-probe-http",
+    anonymous: false,
+    handler: async (c) => c.json({ id: getUser(c).id }),
+  });
+});
+
+describe("origin-middleware + anonymousAccess: foreign-origin cookie becomes anonymous", () => {
+  let stack: TestStack;
+  let authCookie: string;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({
+      features: [probeFeature],
+      authConfig: {
+        membershipQuery: "tenant:query:memberships",
+        allowedOrigins: [ALLOWED],
+        cookieDomain: "example.eu",
+      },
+      anonymousAccess: { defaultTenantId: TestUsers.user.tenantId },
+    });
+    const token = await stack.jwt.sign(TestUsers.user);
+    authCookie = `${AUTH_COOKIE_NAME}=${token}`;
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  test("foreign origin + cookie, no CSRF token → handler runs as the anonymous user", async () => {
+    const res = await stack.http.raw("POST", "/api/query", anonEchoQuery, {
+      Cookie: authCookie,
+      Origin: DISALLOWED,
+    });
+    // 200 (not csrf_token_mismatch) proves CSRF wasn't required — authTransport
+    // stayed unset — and the echoed identity is the synthesised anonymous
+    // user, not the cookie's real one.
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { userId: string; roles: readonly string[] } };
+    expect(body.data.userId).toBe("anonymous");
+    expect(body.data.roles).toEqual(["anonymous"]);
+  });
+
+  test("foreign origin + garbage cookie value → still anonymous, jwt.verify never runs", async () => {
+    const res = await stack.http.raw("POST", "/api/query", anonEchoQuery, {
+      Cookie: `${AUTH_COOKIE_NAME}=not-a-valid-jwt`,
+      Origin: DISALLOWED,
+    });
+    // A malformed token would 401 invalid_token if jwt.verify ran on it —
+    // 200 here is only possible if the cookie was dropped unread.
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { userId: string } };
+    expect(body.data.userId).toBe("anonymous");
+  });
+
+  test("/api/auth/logout from a foreign origin → still 403 origin_not_allowed, not silently anonymous", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/auth/logout",
+      {},
+      {
+        Cookie: authCookie,
+        Origin: DISALLOWED,
+      },
+    );
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("origin_not_allowed");
+  });
+
+  test("allowed origin + cookie, no CSRF token → real user path still requires CSRF", async () => {
+    const res = await stack.http.raw("POST", "/api/write", userOnlyRoute, {
+      Cookie: authCookie,
+      Origin: ALLOWED,
+    });
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("csrf_token_mismatch");
+  });
+
+  test("allowed origin + cookie + valid CSRF → authenticated as the real user, not anonymous", async () => {
+    const csrf = "csrf-fixed-anon-fallthrough-token";
+    const res = await stack.http.raw("POST", "/api/write", userOnlyRoute, {
+      Cookie: `${authCookie}; ${CSRF_COOKIE_NAME}=${csrf}`,
+      Origin: ALLOWED,
+      [CSRF_HEADER_NAME]: csrf,
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: { userId: string; roles: readonly string[] } };
+    expect(body.data.userId).toBe(TestUsers.user.id);
+    expect(body.data.roles).toEqual(TestUsers.user.roles);
+  });
+
+  test("anonymous:false r.httpRoute, foreign origin + cookie, no CSRF → 403 origin_not_allowed, sessionOnlyGuard does not downgrade to anonymous", async () => {
+    // /api/* would downgrade a foreign-origin cookie to anonymous (see the
+    // anon-echo tests above) because jwtGuard carries foreignCookieOrigins.
+    // r.httpRoute anonymous:false routes run behind sessionOnlyGuard instead,
+    // which was deliberately built WITHOUT anonymousAccess/foreignCookieOrigins
+    // — a real cookie must still resolve to the real user, so the Origin guard
+    // rejects it outright instead of silently falling through anonymous.
+    const res = await stack.http.raw(
+      "POST",
+      "/origin-anon-probe-http",
+      {},
+      {
+        Cookie: authCookie,
+        Origin: DISALLOWED,
+      },
+    );
+    expect(res.status).toBe(403);
+    expect(await errorCode(res)).toBe("origin_not_allowed");
+  });
+});

package/src/api/auth-middleware.ts

@@ -6,6 +6,7 @@ import type { SessionUser, TenantId } from "../engine/types";
 import { parseTenantId } from "../engine/types/identifiers";
 import { TENANT_COOKIE_NAME, TENANT_HEADER_NAME } from "./api-constants";
 import type { JwtHelper } from "./jwt";
+import { isForeignCookieOrigin } from "./origin-middleware";
 
 const USER_KEY = "pipelineUser";
 const AUTH_TRANSPORT_KEY = "authTransport";
@@ -92,6 +93,14 @@ export type AuthMiddlewareOptions = {
   // when the tenant is in teardown (destroyRequested/destroying/destroyed).
   // cancel-destruction is exempt while status=destroyRequested.
   readonly resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
+  // Normalized auth.allowedOrigins. A cookie from an origin outside this set
+  // is dropped BEFORE jwt.verify — treated as if no cookie was sent — and
+  // falls through to the anonymousAccess flow instead of the 403 the
+  // sibling originMiddleware would give (fw#340: a public status page's
+  // session cookie, set on the base domain, reaches every tenant subdomain
+  // even though those pages only ever make anonymous queries). Only
+  // meaningful together with anonymousAccess.
+  readonly foreignCookieOrigins?: ReadonlySet<string>;
 };
 
 // Resolves the tenant for an unauthenticated request. Returns null when no
@@ -205,7 +214,13 @@ function extractToken(
 }
 
 export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions = {}) {
-  const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus } = options;
+  const {
+    sessionChecker,
+    anonymousAccess,
+    tokenVerifier,
+    resolveTenantLifecycleStatus,
+    foreignCookieOrigins,
+  } = options;
 
   // Fail loud at boot, not silently at request time: a tenantResolver
   // without a declared resolverTrust is an ambiguous trust decision no
@@ -259,6 +274,20 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     }
     const { token, transport } = extracted;
 
+    // A foreign-origin cookie is noise, not an authentication attempt worth
+    // verifying — drop it before jwt.verify, the token is never read. Auth
+    // routes are excluded (same reasoning as the missing-token branch above):
+    // logout must still see the real auth state, not be silently downgraded.
+    if (
+      transport === "cookie" &&
+      anonymousAccess &&
+      !c.req.path.startsWith("/api/auth/") &&
+      foreignCookieOrigins &&
+      isForeignCookieOrigin(c, foreignCookieOrigins)
+    ) {
+      return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
+    }
+
     // Generic bearer-verifier path: try the wired tokenVerifier (PAT, future
     // JWT-provider, ...) BEFORE jwt.verify. A hit short-circuits the JWT path
     // entirely; a miss (null — no provider's shape matched, or the matching

package/src/api/auth-routes.ts

@@ -148,6 +148,20 @@ const SignupConfirmBody = z.object({
   password: z.string().min(8).max(200),
 });
 
+// Cross-device try-first handover (kumiko-framework#3035 follow-up,
+// offlot-app#454): an optional tenant-handover grant the signup-request
+// route forwards to the handler for server-side verification and binding —
+// the grant itself never appears anywhere else (URL, mail, log, response).
+const SignupRequestBody = z.object({
+  email: z.email(),
+  handover: z
+    .object({
+      entityType: z.string().min(1).max(200),
+      token: z.string().min(1).max(4096),
+    })
+    .optional(),
+});
+
 const InviteAcceptBody = z.object({
   token: z.string().min(1),
 });
@@ -1122,6 +1136,7 @@ export function createAuthRoutes(
       dispatcher,
       path: Routes.authSignupRequest,
       requestHandler: sg.requestHandler,
+      schema: SignupRequestBody,
     });
 
     api.post(Routes.authSignupConfirm, async (c) => {
@@ -1149,6 +1164,7 @@ export function createAuthRoutes(
         kind: "auth-session";
         session: SessionUser;
         tenantKey: string;
+        handover?: { entityType: string; id: string };
       };
 
       // Session creation + JWT sign + cookies — see mintSessionAndRespond.
@@ -1168,6 +1184,11 @@ export function createAuthRoutes(
         // membership — die Frontend-UI nimmt das direkt als Redirect-
         // Target.
         tenantKey: data.tenantKey,
+        // Cross-device try-first handover (kumiko-framework#3035 follow-up):
+        // present only when signup-confirm actually claimed a bound grant —
+        // absent, not null, so a client that doesn't know the field sees
+        // nothing unusual.
+        ...(data.handover !== undefined && { handover: data.handover }),
       });
     });
   }
@@ -1462,8 +1483,12 @@ function registerTokenRequestRoute(opts: {
   dispatcher: Dispatcher;
   path: string;
   requestHandler: string;
+  // reset/verify/unlock keep the plain RequestTokenBody; signup passes its
+  // own schema (adds an optional `handover`, see SignupRequestBody above)
+  // so the extra field reaches the handler instead of being parsed away.
+  schema?: typeof RequestTokenBody | typeof SignupRequestBody;
 }): void {
-  const body = RequestTokenBody;
+  const body = opts.schema ?? RequestTokenBody;
   opts.api.post(opts.path, async (c) => {
     const raw = await c.req.json().catch(() => null);
     const parsed = body.safeParse(raw);
@@ -1478,7 +1503,7 @@ function registerTokenRequestRoute(opts: {
     // the log line (PII).
     const result = await opts.dispatcher.write(
       opts.requestHandler,
-      { email: parsed.data.email },
+      parsed.data,
       createAnonymousUser(SYSTEM_TENANT_ID),
     );
     if (!result.isSuccess) {

package/src/api/origin-middleware.ts

@@ -16,6 +16,21 @@ export function isOriginAllowed(origin: string, normalizedAllowlist: ReadonlySet
   return normalizedAllowlist.has(normalizeOrigin(origin));
 }
 
+// True when a state-changing request carries an Origin (or Sec-Fetch-Site)
+// signal that marks it as coming from outside the allowlist.
+export function isForeignCookieOrigin(c: Context, allowlist: ReadonlySet<string>): boolean {
+  if (!STATE_CHANGING_METHODS.has(c.req.method)) return false;
+
+  const origin = c.req.header("origin");
+  if (origin !== undefined) return !isOriginAllowed(origin, allowlist);
+
+  // No Origin header — older browsers, and some same-origin POSTs in Safari.
+  // Fall back to the Fetch-Metadata Sec-Fetch-Site signal: only an explicit
+  // cross-site marker counts as foreign here (it's a relation, not an origin,
+  // so it can't be matched against the allowlist).
+  return c.req.header("sec-fetch-site") === "cross-site";
+}
+
 function rejectOrigin(c: Context): Response {
   return c.json(
     {
@@ -49,26 +64,14 @@ export function originMiddleware(allowedOrigins: readonly string[]) {
   return async (c: Context, next: Next) => {
     const transport = getAuthTransport(c);
     if (transport !== "cookie") return next();
-    if (!STATE_CHANGING_METHODS.has(c.req.method)) return next();
-
-    const origin = c.req.header("origin");
-    if (origin !== undefined) {
-      if (isOriginAllowed(origin, allowlist)) return next();
-      return rejectOrigin(c);
-    }
-
-    // No Origin header — older browsers, and some same-origin POSTs in Safari.
-    // Fall back to the Fetch-Metadata Sec-Fetch-Site signal: only an explicit
-    // cross-site marker is blocked here (it's a relation, not an origin, so it
-    // can't be matched against the allowlist). Everything else (same-site,
-    // same-origin, none, absent) falls through to the CSRF token. Note: the
-    // CSRF token alone does NOT stop a same-site subdomain XSS — it can read
-    // the wide cookie — but that attack uses fetch/XHR, which always sends an
-    // Origin header and is already rejected by the allowlist branch above. The
-    // residual is only the no-Origin-yet-Sec-Fetch-Site combo, which no current
-    // browser emits for state-changing requests.
-    if (c.req.header("sec-fetch-site") === "cross-site") return rejectOrigin(c);
-
+    // Everything else (same-site, same-origin, none, absent) falls through to
+    // the CSRF token. Note: the CSRF token alone does NOT stop a same-site
+    // subdomain XSS — it can read the wide cookie — but that attack uses
+    // fetch/XHR, which always sends an Origin header and is already rejected
+    // by the allowlist branch inside isForeignCookieOrigin. The residual is
+    // only the no-Origin-yet-Sec-Fetch-Site combo, which no current browser
+    // emits for state-changing requests.
+    if (isForeignCookieOrigin(c, allowlist)) return rejectOrigin(c);
     return next();
   };
 }

package/src/api/server.ts

@@ -71,7 +71,7 @@ import {
 } from "./extra-route";
 import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
-import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
+import { assertOriginGuardConfig, normalizeOrigin, originMiddleware } from "./origin-middleware";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
 import { createDefaultSseBroker, type RedisSseBroker } from "./redis-sse-broker";
 import { requestContext } from "./request-context";
@@ -726,11 +726,20 @@ export function buildServer(options: ServerOptions): KumikoServer {
   const tenantLifecycleResolver =
     options.auth?.resolveTenantLifecycleStatus ??
     deriveTenantLifecycleResolver(options.registry, baseDb);
+  // sessionOnlyGuard deliberately does NOT get this — its callers have no
+  // anonymousAccess fallback, so a foreign-origin cookie there must keep
+  // failing through the sibling originMiddleware 403.
+  const normalizedForeignCookieOrigins = options.auth?.allowedOrigins?.length
+    ? new Set(options.auth.allowedOrigins.map(normalizeOrigin))
+    : undefined;
   const jwtGuard = authMiddleware(jwt, {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
     ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
     ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
+    ...(normalizedForeignCookieOrigins
+      ? { foreignCookieOrigins: normalizedForeignCookieOrigins }
+      : {}),
   });
   app.use("/api/*", async (c, next) => {
     if (PUBLIC_API_PATHS.has(c.req.path) || isExtraRoutePublicPath(c)) return next();

package/src/changes.json

@@ -1,4 +1,52 @@
 [
+  {
+    "version": "0.314.0",
+    "type": "improvement",
+    "title": "drainEventConsumers helper for test stacks with a named consumer backlog",
+    "detail": "The `while ((await eventDispatcher.runOnce())?.processed ?? 0) > 0) {}`\npattern under-drains a backlog bigger than one dispatcher batch and gives no\ndiagnostics when a consumer is stuck. drainEventConsumers(stack,\nconsumerNames, { maxPasses }) from @cosmicdrift/kumiko-framework/stack\nsnapshots the events high-water mark at call time and runs bounded passes\nuntil every named consumer's cursor reaches it, throwing with per-consumer\nstatus, attempts and lastError when the budget (default 25) is exhausted.\nEvents written by consumers after the snapshot are not waited on. No\nmigration needed."
+  },
+  {
+    "version": "0.314.0",
+    "type": "improvement",
+    "title": "validateFile/resolveUploadMimeType accept .csv declared as application/vnd.ms-excel",
+    "detail": "Windows derives a file's upload MIME type from its Explorer file-type\nassociation rather than its content — .csv is registered to Excel there,\nso a Windows browser can declare \"application/vnd.ms-excel\" for a\nplain-text CSV. validateFile now accepts that declared/extension\ncombination for fields whose `accept` includes \"csv\" instead of rejecting\nit as a `mime_mismatch`. The built-in multipart upload route also calls the\nnew `resolveUploadMimeType`, which rewrites an aliased declared mimeType to\nits canonical form (\"text/csv\") after checking the uploaded bytes against\nknown binary signatures — a match (e.g. a real .xls/.xlsx renamed to .csv)\nis rejected with `content_mismatch` instead of being silently rewritten.\nNote: on Bun 1.4.0 (this repo's pinned engines/Dockerfile version, verified\nlocally), `Request#formData()` derives a multipart file's `.type` from its\nfilename extension rather than the part's declared Content-Type, so a\nbrowser's declared \"application/vnd.ms-excel\" for a `.csv` file does not\ncurrently reach the built-in route as such — callers that read a declared\nmimeType from elsewhere (e.g. a separate form field) are the ones this\nalias helps today. Aliases are declarative per extension; only\ncsv → vnd.ms-excel is defined so far.\n`@cosmicdrift/kumiko-framework/files` now also exports `sniffMimeType(bytes:\nUint8Array): string | null` (canonical MIME for a known binary signature,\nor null for text formats — every OLE Compound File returns\n\"application/msword\" and every ZIP returns the docx MIME, callers can't\ntell those apart by bytes alone) and `resolveUploadMimeType`."
+  },
+  {
+    "version": "0.314.0",
+    "type": "fix",
+    "title": "Foreign-origin cookie on an anonymousAccess server is treated as anonymous, not 403",
+    "detail": "originMiddleware rejected any state-changing request whose cookie-carrying\nOrigin (or Sec-Fetch-Site) fell outside auth.allowedOrigins with 403\norigin_not_allowed, including a logged-in tenant admin's own session cookie\nsent along by their public status page, which only makes anonymous queries.\nOn servers with anonymousAccess wired, authMiddleware now drops such a\nforeign-origin cookie before jwt.verify and falls through to the anonymous\nflow; the token is never read. Servers without anonymousAccess, /api/auth/*\npaths and session-only httpRoutes keep the 403. No migration needed."
+  },
+  {
+    "version": "0.314.0",
+    "type": "fix",
+    "title": "setupTestStack isolates job queues per stack by default",
+    "detail": "BullMQ queues live on the raw Redis URL, outside the per-test keyPrefix, so\ntwo parallel test stacks with `jobs` and no explicit `queueNamePrefix` shared\nthe prod default queue names and one stack's consumer could run the other\nstack's jobs. setupTestStack/setupAppTestStack now derive a unique\n`queueNamePrefix` from the stack's test Redis keyPrefix. An explicit\n`jobs.queueNamePrefix` still wins; pass the same value to every runner that\nhas to share a stack's queues. createJobRunner and the prod path are unchanged."
+  },
+  {
+    "version": "0.314.0",
+    "type": "improvement",
+    "title": "kumiko-upgrade --apply says where the marker landed relative to manual breaking changes",
+    "detail": "A breaking change without a codemod was listed as \"manual migration\nrequired\", but the run never said whether the upgrade marker stopped below\nit (the guard keeps listing it until a second --apply acknowledges it) or\nalready moved past it (the guard no longer lists it). --apply now prints\nwhich of the two happened. The marker logic itself is unchanged; the\nacknowledgement path is documented in docs/reference/stability-policy.md."
+  },
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "DB pool close() no longer hangs forever during an outage",
+    "detail": "createDbConnection/createConnection's close() and PgKmsAdapter.close()\ncalled client.end() with no timeout, which postgres.js waits on\nindefinitely if a query is still referenced on a dead connection — a DB\noutage during process shutdown could hang forever. close() now bounds\nthe wait via a new closeTimeoutSeconds option on DbConnectionOptions\n(default 5s, DEFAULT_DB_CLOSE_TIMEOUT_SECONDS). No migration needed."
+  },
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "event-dispatcher stop() waits for a pass still in its idle pre-check",
+    "detail": "Since 0.308.0 a pass started by the timer or a NOTIFY wake-up shortly\nbefore stop() could still be inside its idle pre-check, which stop()\nnever waited for. That pass kept running after stop() returned and\nqueried the DB pool the caller was closing, which could make\npostgres.js' end() hang. stop() now also drains in-flight passes.\nNo migration needed."
+  },
+  {
+    "version": "0.313.0",
+    "type": "improvement",
+    "title": "Event-triggered jobs get the triggering event's id and headers via ctx.triggerEvent",
+    "detail": "r.job's `trigger.on` reached via an r.defineEvent QN (async, at-least-once\ndelivery through the job-trigger event consumer) had no way to key an\nidempotency check on the stored event that fired it. JobContext now\ncarries `triggerEvent?: { id, headers }` — the stored event's id and\nmetadata.headers — when the job was reached this way. Undefined for\ncron/manual jobs and for jobs triggered synchronously off a write/query\nhandler (no stored event to hand over). No migration needed."
+  },
   {
     "version": "0.312.0",
     "type": "improvement",

package/src/crypto/pg-kms-adapter.ts

@@ -1,5 +1,6 @@
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import postgres from "postgres";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "../db/api";
 import {
   KeyAlreadyExistsError,
   KeyErasedError,
@@ -172,7 +173,7 @@ export class PgKmsAdapter implements LocalKeyKmsAdapter {
   }
 
   async close(): Promise<void> {
-    await this.sql.end();
+    await this.sql.end({ timeout: DEFAULT_DB_CLOSE_TIMEOUT_SECONDS });
   }
 
   private ensureSchema(): Promise<void> {

package/src/db/__tests__/connection-close-outage.integration.test.ts

@@ -0,0 +1,110 @@
+// A DB outage must not turn process shutdown into a hang: postgres.js keeps
+// an in-flight query referenced on a dead socket, so a plain end() (no
+// timeout = wait for queries to finish) never resolves once the DB is gone.
+// close() has to bound that wait (db/api.ts's closeTimeoutSeconds). Routes
+// createDbConnection through a TCP proxy that stops forwarding bytes after
+// connect ("blackhole") — same simulated-outage approach as
+// pipeline/__tests__/event-dispatcher-db-outage.integration.test.ts, but
+// without touching the shared test DB's actual availability.
+
+import { afterAll, describe, expect, test } from "bun:test";
+import net from "node:net";
+import { waitFor } from "../../testing";
+import { testDatabaseUrl } from "../../testing/closed-connection-error";
+import { createDbConnection } from "../connection";
+
+function startBlackholeProxy(dbUrl: URL): {
+  readonly server: net.Server;
+  blackhole: () => void;
+  swallowedBytes: () => number;
+  destroy: () => void;
+} {
+  let blackholed = false;
+  let swallowed = 0;
+  const sockets = new Set<net.Socket>();
+  const server = net.createServer((downstream) => {
+    sockets.add(downstream);
+    const upstream = net.connect(Number(dbUrl.port), dbUrl.hostname);
+    sockets.add(upstream);
+    downstream.on("data", (chunk: Buffer) => {
+      if (blackholed) {
+        swallowed += chunk.length;
+        return;
+      }
+      upstream.write(chunk);
+    });
+    upstream.on("data", (chunk: Buffer) => {
+      if (!blackholed) downstream.write(chunk);
+    });
+    downstream.on("error", () => {});
+    upstream.on("error", () => {});
+    downstream.on("close", () => sockets.delete(downstream));
+    upstream.on("close", () => sockets.delete(upstream));
+  });
+  return {
+    server,
+    blackhole: () => {
+      blackholed = true;
+    },
+    swallowedBytes: () => swallowed,
+    destroy: () => {
+      for (const socket of sockets) socket.destroy();
+      server.close();
+    },
+  };
+}
+
+async function listenOn(server: net.Server, port: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, resolve);
+  });
+}
+
+let proxy: ReturnType<typeof startBlackholeProxy>;
+
+afterAll(() => {
+  proxy?.destroy();
+});
+
+describe("createDbConnection close() bounds shutdown during a DB outage", () => {
+  test("close() resolves within the bounded timeout even with in-flight queries on a dead socket", async () => {
+    const dbUrl = new URL(testDatabaseUrl());
+    proxy = startBlackholeProxy(dbUrl);
+    await listenOn(proxy.server, 0);
+    const address = proxy.server.address();
+    if (address === null || typeof address === "string") {
+      throw new Error("proxy did not bind to a TCP port");
+    }
+
+    const proxiedUrl = new URL(dbUrl.toString());
+    proxiedUrl.hostname = "127.0.0.1";
+    proxiedUrl.port = String(address.port);
+
+    const conn = createDbConnection(proxiedUrl.toString(), {
+      maxConnections: 1,
+      closeTimeoutSeconds: 1,
+    });
+
+    // Establish the connection while the proxy still forwards normally —
+    // isolates the assertion to close()'s own timeout, not connect_timeout.
+    await conn.client.unsafe("select 1");
+
+    // Fired without awaiting: once the socket goes dead, end() has to
+    // reject these instead of waiting on them forever. .catch prevents an
+    // unhandled rejection when end() tears the connection down.
+    const inFlightBeforeBlackhole = conn.client.unsafe("select 1").catch(() => undefined);
+    proxy.blackhole();
+    const inFlightAfterBlackhole = conn.client.unsafe("select 1").catch(() => undefined);
+
+    await waitFor(() => proxy.swallowedBytes() > 0);
+
+    const start = Date.now();
+    await conn.close();
+    const elapsed = Date.now() - start;
+
+    expect(elapsed).toBeLessThan(3000);
+
+    await Promise.all([inFlightBeforeBlackhole, inFlightAfterBlackhole]);
+  });
+});

package/src/db/api.ts

@@ -11,8 +11,14 @@ export type DbConnectionOptions = {
   readonly maxConnections?: number;
   readonly idleTimeoutSeconds?: number;
   readonly connectTimeoutSeconds?: number;
+  readonly closeTimeoutSeconds?: number;
 };
 
+// A DB outage can leave an in-flight query referenced on a dead connection,
+// so a plain end() (no timeout = wait for queries to finish) hangs forever —
+// close() must always bound how long shutdown waits.
+export const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;
+
 // Connection-Handle: db für Queries, client für Legacy-Zugriff (LISTEN/NOTIFY-Peer
 // bei Bun.SQL), close für Pool-Shutdown.
 export type DbPoolHandle = {