@cosmicdrift/kumiko-framework 0.313.0 → 0.314.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.313.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.313.0",
-    "@cosmicdrift/kumiko-types": "0.313.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.313.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/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,34 @@
 [
+  {
+    "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",

package/src/files/__tests__/files.integration.test.ts

@@ -8,6 +8,7 @@ import { buildServer } from "../../api/server";
 import { configurePiiSubjectKms, InMemoryKmsAdapter } from "../../crypto";
 import {
   createEntity,
+  createFileField,
   createImageField,
   createRegistry,
   createTextField,
@@ -35,7 +36,13 @@ import type { FileRoutesOptions } from "../file-routes";
 import { createInMemoryFileProvider } from "../in-memory-provider";
 import { createLocalProvider } from "../local-provider";
 import type { FileStorageProvider, SignedUrlOptions } from "../types";
-import { parseMaxSize, sniffMimeType, validateFile, validateFileContent } from "../types";
+import {
+  parseMaxSize,
+  resolveUploadMimeType,
+  sniffMimeType,
+  validateFile,
+  validateFileContent,
+} from "../types";
 
 // UUID for "this row doesn't exist" assertions. Valid v4 format so PG accepts
 // the query — the row just isn't there. Pre-v1 files-feature tests used
@@ -59,6 +66,7 @@ const testTenantEntity = createEntity({
   fields: {
     name: createTextField({ personal: false, reason: "test_fixture", required: true }),
     logo: createImageField({ maxSize: "2mb", accept: ["png", "jpg"] }),
+    importFile: createFileField({ maxSize: "2mb", accept: ["csv"] }),
   },
 });
 
@@ -296,6 +304,91 @@ describe("file validation", () => {
       "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
     );
   });
+
+  // --- .csv declared as application/vnd.ms-excel (Windows browsers) ---
+
+  test("validateFile accepts .csv declared as application/vnd.ms-excel when csv is in accept", () => {
+    expect(
+      validateFile(
+        { fileName: "data.csv", mimeType: "application/vnd.ms-excel", size: 100 },
+        { accept: ["csv"] },
+      ),
+    ).toBeNull();
+  });
+
+  test("validateFile does not extend the vnd.ms-excel alias to extensions other than csv", () => {
+    const error = validateFile(
+      { fileName: "photo.jpg", mimeType: "application/vnd.ms-excel", size: 100 },
+      { accept: ["jpg"] },
+    );
+    expectErrorIncludes(error, "mime_mismatch");
+  });
+
+  test("validateFile rejects a prototype-property mimeType instead of treating it as an alias match", () => {
+    const error = validateFile(
+      { fileName: "photo.jpg", mimeType: "constructor", size: 100 },
+      { accept: ["jpg"] },
+    );
+    expectErrorIncludes(error, "mime_mismatch");
+  });
+
+  describe("resolveUploadMimeType", () => {
+    const textCsvBytes = new TextEncoder().encode("name,age\nAda,36\n");
+
+    test("rewrites .csv + application/vnd.ms-excel to text/csv when bytes are text", () => {
+      expect(resolveUploadMimeType("data.csv", "application/vnd.ms-excel", textCsvBytes)).toEqual({
+        kind: "ok",
+        mimeType: "text/csv",
+      });
+    });
+
+    test("rewrites regardless of charset suffix or case", () => {
+      expect(
+        resolveUploadMimeType("data.csv", "Application/VND.MS-EXCEL; charset=utf-8", textCsvBytes),
+      ).toEqual({ kind: "ok", mimeType: "text/csv" });
+    });
+
+    test("rejects .csv + application/vnd.ms-excel when bytes are a real OLE binary", () => {
+      const result = resolveUploadMimeType("data.csv", "application/vnd.ms-excel", docBytes);
+      expect(result.kind).toBe("rejected");
+      if (result.kind === "rejected") {
+        expectErrorIncludes(result.error, "content_mismatch");
+      }
+    });
+
+    test("rejects .csv + application/vnd.ms-excel when bytes are a ZIP container (.xlsx)", () => {
+      const result = resolveUploadMimeType("data.csv", "application/vnd.ms-excel", docxBytes);
+      expect(result.kind).toBe("rejected");
+      if (result.kind === "rejected") {
+        expectErrorIncludes(result.error, "content_mismatch");
+      }
+    });
+
+    test("leaves .csv + text/plain unchanged", () => {
+      expect(resolveUploadMimeType("data.csv", "text/plain", textCsvBytes)).toEqual({
+        kind: "ok",
+        mimeType: "text/plain",
+      });
+    });
+
+    test("leaves .xls + application/vnd.ms-excel unchanged (alias is csv-only)", () => {
+      expect(resolveUploadMimeType("data.xls", "application/vnd.ms-excel", docBytes)).toEqual({
+        kind: "ok",
+        mimeType: "application/vnd.ms-excel",
+      });
+    });
+
+    test("a prototype-property extension or mimeType never resolves as an alias", () => {
+      expect(resolveUploadMimeType("x.constructor", "name", textCsvBytes)).toEqual({
+        kind: "ok",
+        mimeType: "name",
+      });
+      expect(resolveUploadMimeType("data.csv", "constructor", textCsvBytes)).toEqual({
+        kind: "ok",
+        mimeType: "constructor",
+      });
+    });
+  });
 });
 
 // --- Integration: Upload → Download → Delete via real HTTP API ---
@@ -523,6 +616,40 @@ describe("doc/docx upload is content-verified against magic bytes", () => {
   });
 });
 
+// Bun's formData() derives File#type from the filename, so .csv never
+// arrives as vnd.ms-excel here; the csv alias is covered by the unit tests above.
+describe("vnd.ms-excel via HTTP (.xls)", () => {
+  const docBytes = new Uint8Array([
+    0xd0,
+    0xcf,
+    0x11,
+    0xe0,
+    0xa1,
+    0xb1,
+    0x1a,
+    0xe1,
+    ...Array(20).fill(0),
+  ]);
+
+  test("unattached .xls declared as application/vnd.ms-excel keeps its declared mimeType unchanged", async () => {
+    const res = await uploadFile(adminUser, "legacy.xls", docBytes, "application/vnd.ms-excel");
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.mimeType).toBe("application/vnd.ms-excel");
+  });
+
+  test("attached .xls upload is rejected by the importFile field's csv-only accept list", async () => {
+    const res = await uploadFile(adminUser, "legacy.xls", docBytes, "application/vnd.ms-excel", {
+      entityType: "tenant",
+      entityId: "1",
+      fieldName: "importFile",
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("invalid_file_type");
+  });
+});
+
 // --- Cross-user access within a tenant (attached file owner-scope) ---
 
 describe("attached file owner-scope", () => {

package/src/files/file-routes.ts

@@ -30,6 +30,7 @@ import type { FileProviderResolver } from "./provider-resolver";
 import {
   buildStorageKey,
   resolveServedContentType,
+  resolveUploadMimeType,
   validateFile,
   validateFileContent,
 } from "./types";
@@ -240,13 +241,19 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       return c.json({ error: contentValidationError }, 400);
     }
 
+    const mimeTypeResolution = resolveUploadMimeType(file.name, file.type, data);
+    if (mimeTypeResolution.kind === "rejected") {
+      return c.json({ error: mimeTypeResolution.error }, 400);
+    }
+    const mimeType = mimeTypeResolution.mimeType;
+
     // Write binary FIRST (outside the tx — network/disk I/O doesn't belong
     // inside a PG connection's tx window). On DB-tx rollback below the bytes
     // are orphaned in the provider; cleanup-jobs sweep those later. Losing a
     // row on append-failure is acceptable; corrupting a committed row with a
     // missing binary is not.
     const storageProvider = await options.resolveProvider(user.tenantId);
-    await storageProvider.write(storageKey, data, file.type);
+    await storageProvider.write(storageKey, data, mimeType);
 
     // Create via the standard entity executor: emits fileRef.created +
     // materialises the file_refs row in one tx (read-your-own-write). id is
@@ -260,7 +267,7 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
         id: fileRefId,
         storageKey,
         fileName: file.name,
-        mimeType: file.type,
+        mimeType,
         size: file.size,
         entityType: entityType ?? null,
         entityId: entityId ?? null,
@@ -277,7 +284,7 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       {
         id: fileRefId,
         fileName: file.name,
-        mimeType: file.type,
+        mimeType,
         size: file.size,
         storageKey,
       },

package/src/files/index.ts

@@ -37,6 +37,7 @@ export type {
   FileStorageProvider,
   FileValidationOptions,
   SignedUrlOptions,
+  UploadMimeTypeResolution,
   WriteStreamOptions,
 } from "./types";
 export {
@@ -44,6 +45,8 @@ export {
   buildStorageKey,
   normalizeMimeType,
   parseMaxSize,
+  resolveUploadMimeType,
+  sniffMimeType,
   tenantExportPrefix,
   tenantStoragePrefixes,
   validateFile,

package/src/files/types.ts

@@ -34,6 +34,10 @@ export function parseMaxSize(maxSize: string): number {
   }
 }
 
+function extractExtension(fileName: string): string | undefined {
+  return fileName.split(".").pop()?.toLowerCase();
+}
+
 // Extension → acceptable MIME-type whitelist. Guards against a client
 // uploading e.g. name="x.jpg" with mimeType="application/pdf" to slip an
 // executable past the extension-only check. Kept small & conservative — add
@@ -54,6 +58,21 @@ const EXTENSION_MIME_WHITELIST: Record<string, readonly string[]> = {
   docx: ["application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
 } satisfies Record<string, readonly string[]>;
 
+// Extension → declared MIME → canonical MIME. Windows resolves .csv's upload
+// MIME from Explorer's Excel file association, sending "application/vnd.ms-excel" for plain-text CSV.
+const EXTENSION_MIME_ALIASES: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  csv: { "application/vnd.ms-excel": "text/csv" },
+};
+
+// Object.hasOwn at both levels: a plain `in` check on `{}` resolves to
+// Object.prototype members ("constructor", …) for any ext/mimeType.
+function lookupMimeAlias(ext: string, normalizedMimeType: string): string | undefined {
+  if (!Object.hasOwn(EXTENSION_MIME_ALIASES, ext)) return undefined;
+  const aliasesForExt = EXTENSION_MIME_ALIASES[ext];
+  if (!aliasesForExt || !Object.hasOwn(aliasesForExt, normalizedMimeType)) return undefined;
+  return aliasesForExt[normalizedMimeType];
+}
+
 // Magic-byte signatures for the subset of EXTENSION_MIME_WHITELIST that has
 // a reliable binary signature. Used at SERVE time — never trust the stored/
 // client-declared mimeType for Content-Type on its own, sniff the actual
@@ -108,6 +127,14 @@ function startsWithAscii(bytes: Uint8Array, ascii: string, offset = 0): boolean
   return true;
 }
 
+/**
+ * Canonical MIME type for a known binary magic-byte signature (png, jpeg,
+ * gif, webp, pdf, OLE, ZIP), or null for everything else — text formats
+ * (csv, txt, json, svg, md) have no signature and always return null. Every
+ * OLE Compound File (.doc/.xls/.ppt) returns "application/msword" and every
+ * ZIP (.docx/.xlsx/.pptx/.zip) returns the docx MIME — callers can't tell
+ * those apart by bytes alone.
+ */
 export function sniffMimeType(bytes: Uint8Array): string | null {
   for (const signature of MAGIC_BYTE_SIGNATURES) {
     if (signature.matches(bytes)) return signature.mimeType;
@@ -165,7 +192,7 @@ export function validateFile(
   }
 
   if (options.accept && options.accept.length > 0) {
-    const ext = metadata.fileName.split(".").pop()?.toLowerCase();
+    const ext = extractExtension(metadata.fileName);
     if (!ext || !options.accept.includes(ext)) {
       return `invalid_file_type: ".${ext}" is not in [${options.accept.join(", ")}]`;
     }
@@ -176,7 +203,8 @@ export function validateFile(
     const allowedMimes = EXTENSION_MIME_WHITELIST[ext];
     if (allowedMimes && metadata.mimeType) {
       const normalized = normalizeMimeType(metadata.mimeType);
-      if (!allowedMimes.includes(normalized)) {
+      const isAliasedMime = lookupMimeAlias(ext, normalized) !== undefined;
+      if (!allowedMimes.includes(normalized) && !isAliasedMime) {
         return `mime_mismatch: extension ".${ext}" does not match mimeType "${metadata.mimeType}"`;
       }
     }
@@ -198,6 +226,33 @@ export function validateFileContent(mimeType: string, content: Uint8Array): stri
   return null;
 }
 
+export type UploadMimeTypeResolution =
+  | { readonly kind: "ok"; readonly mimeType: string }
+  | { readonly kind: "rejected"; readonly error: string };
+
+/**
+ * Rewrites an aliased declared mimeType to its canonical form and, in the
+ * same call, sniffs the bytes — a renamed binary (a real .xls/.xlsx saved
+ * as .csv) must fail here rather than through an optional, skippable step.
+ */
+export function resolveUploadMimeType(
+  fileName: string,
+  declaredMimeType: string,
+  content: Uint8Array,
+): UploadMimeTypeResolution {
+  const ext = extractExtension(fileName);
+  const normalizedDeclared = normalizeMimeType(declaredMimeType);
+  const canonical = ext ? lookupMimeAlias(ext, normalizedDeclared) : undefined;
+  if (!canonical) return { kind: "ok", mimeType: declaredMimeType };
+  if (sniffMimeType(content) !== null) {
+    return {
+      kind: "rejected",
+      error: `content_mismatch: bytes of ".${ext}" upload declared as "${declaredMimeType}" are a binary format`,
+    };
+  }
+  return { kind: "ok", mimeType: canonical };
+}
+
 export function assertSafeStorageKey(key: string): void {
   if (key.split("/").some((segment) => segment === "." || segment === "..")) {
     throw new Error(`storage key contains a path-traversal segment: "${key}"`);

package/src/jobs/__tests__/job-backoff.integration.test.ts

@@ -14,7 +14,6 @@ import * as z from "zod";
 import { defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";
 import { waitFor } from "../../testing";
-import { generateId } from "../../utils";
 
 const exponentialDefaultStarts: number[] = [];
 const exponentialCustomStarts: number[] = [];
@@ -92,10 +91,7 @@ let stack: TestStack;
 beforeAll(async () => {
   stack = await setupTestStack({
     features: [backoffFixtureFeature],
-    // Own queue namespace: the default "kumiko-jobs" queue on the shared test
-    // Redis is consumed by every parallel test process, and a foreign worker
-    // grabbing a promoted delayed retry fails it as "Unknown job".
-    jobs: { consumerLane: "worker", queueNamePrefix: `backoff-test-${generateId()}` },
+    jobs: { consumerLane: "worker" },
   });
 });
 

package/src/pipeline/system-hooks.ts

@@ -468,7 +468,8 @@ export async function buildSearchDocument(
 //    die auf optimistic-update setzen merken das nicht; strictly-waiting
 //    Clients müssten poll-after-write.
 //
-// Tests drain deterministisch via `await stack.eventDispatcher.runOnce()`.
+// Tests drain deterministically via `await stack.eventDispatcher.runOnce()`,
+// or via `drainEventConsumers` for this consumer name specifically.
 export const SSE_BROADCAST_CONSUMER_NAME = "system:consumer:sse-broadcast";
 
 export function createSseBroadcastEventConsumer(sseBroker: SseBroker): EventConsumer {

package/src/stack/__tests__/drain-event-consumers.integration.test.ts

@@ -0,0 +1,166 @@
+// drainEventConsumers — pass-budgeted alternative to
+// `while ((await eventDispatcher.runOnce())?.processed ?? 0) > 0) {}`, which
+// under-drains a backlog bigger than one dispatcher batch and gives no
+// diagnostics when a consumer is stuck.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { insertOne } from "../../db";
+import { defineFeature } from "../../engine";
+import { eventsTable } from "../../event-store";
+import { drainEventConsumers } from "../drain-event-consumers";
+import { resetEventStore } from "../table-helpers";
+import { setupTestStack, type TestStack } from "../test-stack";
+import { TestUsers } from "../test-users";
+
+const admin = TestUsers.admin;
+const TRACKER_QN = "drain-test:projection:tracker";
+const POISON_QN = "drain-test:projection:poison";
+
+// Distinct from POISON_TARGET_NAME (test 3's own poison consumer) so the two
+// scenarios can't accidentally cross-trigger each other's throw branch.
+const CASCADE_TRIGGER_NAME = "cascade-trigger";
+const CASCADE_POISON_NAME = "cascade-poison-must-not-be-processed";
+const POISON_TARGET_NAME = "always-poison";
+
+let observed: string[] = [];
+
+const drainTestFeature = defineFeature("drain-test", (r) => {
+  r.multiStreamProjection({
+    name: "tracker",
+    apply: {
+      "drain-test.tick": async (event, tx) => {
+        const name = (event.payload as { name: string }).name;
+        if (name === CASCADE_POISON_NAME) {
+          throw new Error(`tracker must not process the post-snapshot cascade: ${name}`);
+        }
+        observed.push(name);
+        // Simulates a consumer whose own handler writes a follow-up event —
+        // drainEventConsumers snapshots the target once, so this write must
+        // never be waited on.
+        if (name === CASCADE_TRIGGER_NAME) {
+          await insertOne(tx, eventsTable, {
+            aggregateId: crypto.randomUUID(),
+            aggregateType: "drain-test-source",
+            tenantId: admin.tenantId,
+            version: 1,
+            type: "drain-test.tick",
+            eventVersion: 1,
+            payload: { name: CASCADE_POISON_NAME },
+            metadata: { userId: admin.id },
+            createdBy: admin.id,
+          });
+        }
+      },
+    },
+  });
+  r.multiStreamProjection({
+    name: "poison",
+    apply: {
+      "drain-test.tick": async (event) => {
+        const name = (event.payload as { name: string }).name;
+        if (name === POISON_TARGET_NAME) {
+          throw new Error(`boom: ${name}`);
+        }
+      },
+    },
+  });
+});
+
+async function appendTick(name: string): Promise<void> {
+  await insertOne(stack.db, eventsTable, {
+    aggregateId: crypto.randomUUID(),
+    aggregateType: "drain-test-source",
+    tenantId: admin.tenantId,
+    version: 1,
+    type: "drain-test.tick",
+    eventVersion: 1,
+    payload: { name },
+    metadata: { userId: admin.id },
+    createdBy: admin.id,
+  });
+}
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [drainTestFeature], systemHooks: [] });
+});
+
+afterEach(async () => {
+  observed = [];
+  await resetEventStore(stack);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("drainEventConsumers", () => {
+  test("backlog larger than the dispatcher batch size gets fully processed", async () => {
+    const names = Array.from({ length: 220 }, (_, i) => `evt-${i}`);
+    for (const name of names) await appendTick(name);
+
+    await drainEventConsumers({ db: stack.db, eventDispatcher: stack.eventDispatcher }, [
+      TRACKER_QN,
+    ]);
+
+    expect(observed.sort()).toEqual([...names].sort());
+  });
+
+  test("an event written after the HWM snapshot does not block", async () => {
+    await appendTick(CASCADE_TRIGGER_NAME);
+
+    await drainEventConsumers({ db: stack.db, eventDispatcher: stack.eventDispatcher }, [
+      TRACKER_QN,
+    ]);
+
+    // The cascade event was written by the handler DURING the drain, after
+    // the target snapshot — proven never processed (would throw otherwise).
+    expect(observed).toEqual([CASCADE_TRIGGER_NAME]);
+  });
+
+  test("a throwing consumer exhausts the budget and the error contains lastError", async () => {
+    await appendTick(POISON_TARGET_NAME);
+
+    let caughtMessage: string | undefined;
+    try {
+      await drainEventConsumers(
+        { db: stack.db, eventDispatcher: stack.eventDispatcher },
+        [POISON_QN],
+        { maxPasses: 2 },
+      );
+    } catch (e) {
+      caughtMessage = e instanceof Error ? e.message : String(e);
+    }
+
+    expect(caughtMessage).toBeDefined();
+    expect(caughtMessage).toContain(POISON_QN);
+    expect(caughtMessage).toContain(`lastError=boom: ${POISON_TARGET_NAME}`);
+  });
+
+  test("an unknown consumer name throws", async () => {
+    let caughtMessage: string | undefined;
+    try {
+      await drainEventConsumers({ db: stack.db, eventDispatcher: stack.eventDispatcher }, [
+        "drain-test:projection:does-not-exist",
+      ]);
+    } catch (e) {
+      caughtMessage = e instanceof Error ? e.message : String(e);
+    }
+
+    expect(caughtMessage).toContain(
+      'consumer "drain-test:projection:does-not-exist" not registered or per-instance',
+    );
+  });
+
+  test("missing eventDispatcher raises a clear error", async () => {
+    let caughtMessage: string | undefined;
+    try {
+      await drainEventConsumers({ db: stack.db, eventDispatcher: undefined }, [TRACKER_QN]);
+    } catch (e) {
+      caughtMessage = e instanceof Error ? e.message : String(e);
+    }
+
+    expect(caughtMessage).toContain("eventDispatcher is undefined");
+  });
+});

package/src/stack/__tests__/setup-test-stack-jobs.integration.test.ts

@@ -8,6 +8,7 @@ import * as z from "zod";
 import { defineFeature } from "../../engine";
 import { InternalError, writeFailure } from "../../errors";
 import { waitFor } from "../../testing";
+import { generateId } from "../../utils";
 import { setupTestStack, type TestStack } from "../test-stack";
 import { TestUsers } from "../test-users";
 
@@ -57,11 +58,22 @@ const jobContextFeature = defineFeature("jobcontextcheck", (r) => {
   });
 });
 
+const laneIsolationRuns: Array<{ from: unknown }> = [];
+
+const laneIsolationFeature = defineFeature("laneisolation", (r) => {
+  r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload) => {
+    laneIsolationRuns.push({ from: payload["from"] });
+  });
+});
+
 let stack: TestStack | undefined;
+let secondStack: TestStack | undefined;
 
 afterEach(async () => {
   if (stack) await stack.cleanup();
+  if (secondStack) await secondStack.cleanup();
   stack = undefined;
+  secondStack = undefined;
 });
 
 describe("setupTestStack({ jobs }) wires ctx.jobRunner for manual dispatch", () => {
@@ -98,6 +110,54 @@ describe("setupTestStack({ jobs }) wires ctx.jobRunner for manual dispatch", ()
   });
 });
 
+// Stack "api" consumes only the api lane, so its worker-lane job can only run
+// if the "worker" stack's consumer reads the same queue.
+describe("setupTestStack({ jobs }) queue isolation between parallel stacks", () => {
+  async function dispatchFromApiStackThenRunOwnJob(): Promise<void> {
+    await stack?.jobRunner?.dispatch("laneisolation:job:record", { from: "api-stack" });
+    await secondStack?.jobRunner?.dispatch("laneisolation:job:record", { from: "worker-stack" });
+    await waitFor(() => {
+      expect(laneIsolationRuns.some((run) => run.from === "worker-stack")).toBe(true);
+    });
+  }
+
+  test("without an explicit queueNamePrefix, one stack's consumer never runs another stack's job", async () => {
+    laneIsolationRuns.length = 0;
+    [stack, secondStack] = await Promise.all([
+      setupTestStack({ features: [laneIsolationFeature], jobs: { consumerLane: "api" } }),
+      setupTestStack({ features: [laneIsolationFeature], jobs: { consumerLane: "worker" } }),
+    ]);
+
+    await dispatchFromApiStackThenRunOwnJob();
+
+    expect(laneIsolationRuns.map((run) => run.from)).toEqual(["worker-stack"]);
+  });
+
+  test("an explicit shared queueNamePrefix wins, so both stacks read one queue", async () => {
+    laneIsolationRuns.length = 0;
+    const queueNamePrefix = `laneisolation-shared-${generateId()}`;
+    [stack, secondStack] = await Promise.all([
+      setupTestStack({
+        features: [laneIsolationFeature],
+        jobs: { consumerLane: "api", queueNamePrefix },
+      }),
+      setupTestStack({
+        features: [laneIsolationFeature],
+        jobs: { consumerLane: "worker", queueNamePrefix },
+      }),
+    ]);
+
+    await dispatchFromApiStackThenRunOwnJob();
+
+    await waitFor(() => {
+      expect(laneIsolationRuns.map((run) => run.from).sort()).toEqual([
+        "api-stack",
+        "worker-stack",
+      ]);
+    });
+  });
+});
+
 describe("setupTestStack({ jobs }) job context matches the request-path context", () => {
   test("job handler's context carries tracer + searchAdapter, mirrors prod's effectiveFeatures-less job context", async () => {
     jobContextFields.length = 0;

package/src/stack/drain-event-consumers.ts

@@ -0,0 +1,74 @@
+import type { DbConnection } from "../db";
+import { getEventsHighWaterMark } from "../event-store";
+import { type ConsumerRecoveryState, getConsumerState } from "../pipeline";
+import type { TestStack } from "./test-stack";
+
+const DEFAULT_MAX_PASSES = 25;
+
+// Drives eventDispatcher.runOnce() until every named consumer has caught up
+// to the events high-water mark captured at call time. No "no progress ⇒
+// throw" shortcut: a pass can legitimately advance zero cursors even though
+// work remains — runOnce's FOR UPDATE SKIP LOCKED lets a concurrent pass
+// (the test stack's own 50ms poll timer) hold a consumer's row, and a
+// consumer coming off a thrown-pass backoff sits idle until its retryAtMs
+// elapses. A bounded pass budget tolerates both without pretending to detect
+// "stuck" from a single empty pass. The target is a snapshot: events a
+// consumer's own handler writes afterward (cascades) are not waited on.
+export async function drainEventConsumers(
+  stack: Pick<TestStack, "db" | "eventDispatcher">,
+  consumerNames: readonly [string, ...string[]],
+  options?: { readonly maxPasses?: number },
+): Promise<void> {
+  const { db, eventDispatcher } = stack;
+  if (!eventDispatcher) {
+    throw new Error(
+      "drainEventConsumers: stack.eventDispatcher is undefined — no system consumer or " +
+        "multiStreamProjection is wired for this stack.",
+    );
+  }
+  const maxPasses = options?.maxPasses ?? DEFAULT_MAX_PASSES;
+  const target = await getEventsHighWaterMark(db);
+
+  for (let pass = 0; pass < maxPasses; pass++) {
+    await eventDispatcher.runOnce();
+    const states = await loadConsumerStates(db, consumerNames);
+    // skip: every named consumer has already caught up to the target snapshot — the
+    // remaining budgeted passes are unnecessary, not a swallowed error.
+    if (states.every((state) => state.lastProcessedEventId >= target)) return;
+    if (pass === maxPasses - 1) {
+      throw budgetExhaustedError(maxPasses, target, states);
+    }
+  }
+}
+
+async function loadConsumerStates(
+  db: DbConnection,
+  consumerNames: readonly [string, ...string[]],
+): Promise<readonly ConsumerRecoveryState[]> {
+  return Promise.all(
+    consumerNames.map(async (name) => {
+      const state = await getConsumerState(db, name);
+      if (!state) {
+        throw new Error(`drainEventConsumers: consumer "${name}" not registered or per-instance`);
+      }
+      return state;
+    }),
+  );
+}
+
+function budgetExhaustedError(
+  maxPasses: number,
+  target: bigint,
+  states: readonly ConsumerRecoveryState[],
+): Error {
+  const unfinished = states.filter((state) => state.lastProcessedEventId < target);
+  const lines = unfinished.map(
+    (state) =>
+      `  ${state.name}: lastProcessedEventId=${state.lastProcessedEventId} target=${target} ` +
+      `status=${state.status} attempts=${state.attempts} lastError=${state.lastError ?? "null"}`,
+  );
+  return new Error(
+    `drainEventConsumers: budget of ${maxPasses} passes exhausted, consumers still behind target:\n` +
+      lines.join("\n"),
+  );
+}

package/src/stack/index.ts

@@ -14,6 +14,7 @@ export {
   createTestDb,
   type TestDb,
 } from "./db";
+export { drainEventConsumers } from "./drain-event-consumers";
 export { createEventCollector, type EventCollector } from "./event-collector";
 export { pushEntityProjectionTables } from "./push-entity-projection-tables";
 export { createTestRedis, type TestRedis } from "./redis";

package/src/stack/redis.ts

@@ -10,6 +10,8 @@ export type TestRedis = {
   // kumiko-framework #1036/2) — callers needing a fresh connection should use
   // this raw string, not rebuild one from parsed options.
   redisUrl: string;
+  /** The per-test `keyPrefix` on `redis`, e.g. `kt:1a2b3c4d:`. */
+  keyPrefix: string;
   /** Delete every key this test created (prefix-scoped). Replaces the old
    *  `redis.flushdb()` — that wiped other parallel tests' BullMQ state. */
   flushNamespace: () => Promise<void>;
@@ -43,6 +45,7 @@ export async function createTestRedis(): Promise<TestRedis> {
   return {
     redis,
     redisUrl,
+    keyPrefix: prefix,
     flushNamespace,
     cleanup: async () => {
       await flushNamespace();

package/src/stack/test-stack.ts

@@ -52,7 +52,8 @@ export type TestStack = {
   // event-triggered job reaching for ctx.files die where the request path works.
   context: AppContext;
   // Present whenever a system consumer (SSE, Search) or
-  // r.multiStreamProjection is wired. Tests drain it via runOnce() for
+  // r.multiStreamProjection is wired. Tests drain it via runOnce() (or the
+  // drainEventConsumers helper for a named-consumer backlog) for
   // deterministic assertion — no timer-induced flakiness.
   eventDispatcher?: EventDispatcher;
   // Only set when the caller passed `lifecycle` via options. Tests that
@@ -167,6 +168,8 @@ export type TestStackOptions = {
    *  `runOnBoot`/cron jobs against a caller-owned consumer). */
   jobs?: {
     consumerLane?: JobRunIn;
+    /** Default: unique per stack, derived from its test Redis keyPrefix. Pass
+     *  the same value to every runner that has to share this stack's queues. */
     queueNamePrefix?: string;
     /** Source of active tenant ids for `perTenant: true` jobs. Omit when the
      *  tenant feature is among `options.features` — the framework then
@@ -188,6 +191,13 @@ export type TestStackOptions = {
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
 
+// BullMQ queues live on the raw redisUrl, outside the test Redis keyPrefix, so
+// parallel stacks sharing the prod default queue name would consume each
+// other's jobs. BullMQ rejects `:` in queue names.
+function queueNamePrefixForTestRedis(keyPrefix: string): string {
+  return keyPrefix.split(":").filter(Boolean).join("-");
+}
+
 export async function setupTestStack(options: TestStackOptions): Promise<TestStack> {
   const jwtSecret = options.jwtSecret ?? DEFAULT_JWT_SECRET;
   const enabledHooks = options.systemHooks ?? ["sse", "search"];
@@ -355,9 +365,8 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       // password/username/tls/path (pr-review kumiko-framework #1036/2).
       redisUrl: testRedis.redisUrl,
       ...(options.jobs.consumerLane !== undefined && { consumerLane: options.jobs.consumerLane }),
-      ...(options.jobs.queueNamePrefix !== undefined && {
-        queueNamePrefix: options.jobs.queueNamePrefix,
-      }),
+      queueNamePrefix:
+        options.jobs.queueNamePrefix ?? queueNamePrefixForTestRedis(testRedis.keyPrefix),
       ...(options.jobs.getActiveTenantIds !== undefined && {
         getActiveTenantIds: options.jobs.getActiveTenantIds,
       }),

package/src/upgrade-cli.ts

@@ -304,9 +304,6 @@ function readMarkerVersion(targetDir: string): string | null {
   }
 }
 
-/** Highest pending version strictly below the earliest open manual breaking
- *  entry (no codemod). Falls back to highest non-breaking pending when every
- *  pending version is at/after that manual — never advances onto the manual. */
 /** Highest pending version strictly below the earliest open manual breaking
  *  entry (no codemod). Falls back to highest non-breaking pending when every
  *  pending version is at/after that manual. If only manuals remain, returns
@@ -340,6 +337,21 @@ function markerVersionForPending(
   return fallbackInstalled;
 }
 
+function logManualMarkerOutcome(
+  out: UpgradeCliOut,
+  manualEntries: readonly ChangelogEntry[],
+  markerVersion: string,
+): void {
+  if (manualEntries.length > 0) {
+    const markerHeldBack = manualEntries.some((e) => compareVersions(e.version, markerVersion) > 0);
+    out.log(
+      markerHeldBack
+        ? `  ⚠ Marker stays at ${markerVersion}, so the upgrade guard keeps listing the manual change(s) above. Migrate them by hand, then run --apply again to acknowledge them.`
+        : `  ⚠ Marker moved past the manual change(s) above to ${markerVersion}; the upgrade guard no longer lists them, so make sure they are migrated.`,
+    );
+  }
+}
+
 // Runs every pending breaking entry's codemod, oldest version first (so a
 // later codemod can assume an earlier one already ran). Stops on the first
 // failure — no partial marker. Writes the marker whenever dryRun is false —
@@ -394,6 +406,7 @@ async function applyCodemods(
         codemods: [],
       });
       out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
+      logManualMarkerOutcome(out, manualEntries, markerVer);
     }
     return 0;
   }
@@ -442,6 +455,7 @@ async function applyCodemods(
   if (pendingManual.length > 0) {
     out.log(`  ⚠ ${pendingManual.length} breaking change(s) still need manual migration.`);
   }
+  logManualMarkerOutcome(out, manualEntries, latestVersion);
   return 0;
 }