@cosmicdrift/kumiko-framework 0.310.0 → 0.312.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.310.0",
+  "version": "0.312.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.310.0",
-    "@cosmicdrift/kumiko-types": "0.310.0",
+    "@cosmicdrift/kumiko-http": "0.312.0",
+    "@cosmicdrift/kumiko-types": "0.312.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.310.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.312.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.312.0",
+    "type": "improvement",
+    "title": "files: doc/docx accepted, with magic-byte content verification",
+    "detail": "EXTENSION_MIME_WHITELIST and MAGIC_BYTE_SIGNATURES now cover .doc (application/msword, OLE signature) and .docx (application/vnd.openxmlformats-officedocument.wordprocessingml.document, ZIP signature). New exported validateFileContent(mimeType, content) checks, for doc/docx only, the declared mimeType against the file's magic bytes independent of options.accept — validateFile's own signature is unchanged (metadata-only); file-routes.ts calls validateFile first, then validateFileContent once after reading the upload body. normalizeMimeType is exported from files/types.ts as the single case/parameter-normalization helper (derivatives-context.ts's local copy was removed in favor of it)."
+  },
+  {
+    "version": "0.312.0",
+    "type": "breaking",
+    "title": "MultiStreamApplyContext gains a required registry field",
+    "migration": "Any hand-built MultiStreamApplyContext (e.g. in an MSP test that constructs the context object literal instead of using createMultiStreamApplyContext/setupTestStack) must add registry: <the app Registry instance>, the same instance HandlerContext/JobContext already expose. Lets an apply resolve extension-point usages (registry.getExtensionUsages) to pick behavior by payload discriminant, e.g. a provider-routed MSP."
+  },
+  {
+    "version": "0.312.0",
+    "type": "improvement",
+    "title": "r.job triggers can filter on payload fields via JobTrigger.where",
+    "detail": "A job's {on} trigger can now carry an optional where: equality filter on top-level event-payload fields, checked in job-runner's handleEvent before the job is enqueued (both the sync write-handler dispatch path and the async event-consumer path share this check). Lets N jobs share one broad event QN, partitioned by a payload discriminant, instead of each needing its own narrow event type."
+  },
   {
     "version": "0.310.0",
     "type": "improvement",

package/src/derivatives/derivatives-context.ts

@@ -14,7 +14,7 @@ import type { Registry, TenantId } from "../engine/types";
 import { InternalError, NotFoundError } from "../errors";
 import type { FileContext } from "../files/file-handle";
 import { fileRefsTable } from "../files/file-ref-table";
-import { assertSafeStorageKey } from "../files/types";
+import { assertSafeStorageKey, normalizeMimeType } from "../files/types";
 import { variantSuffix } from "./variant-key";
 
 export type DerivativesContextDeps = {
@@ -30,13 +30,6 @@ function isDerivativeRendererPlugin(o: unknown): o is DerivativeRendererPlugin {
   return typeof o === "object" && o !== null && "render" in o && typeof o.render === "function";
 }
 
-// Mirrors validateFile's mime-normalization: strip a `; charset=…` suffix,
-// trim, lowercase — so a provider-supplied `image/jpeg; charset=binary`
-// still resolves.
-function normalizeMimeType(mimeType: string): string {
-  return mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
-}
-
 export function resolveRenderer(
   registry: Registry,
   mimeType: string,

package/src/engine/feature-config-events-jobs.ts

@@ -222,6 +222,9 @@ export function buildConfigEventsJobsMethods<TName extends string>(
               on: Array.isArray(jobOptions.trigger.on)
                 ? jobOptions.trigger.on.map(resolveName)
                 : resolveName(jobOptions.trigger.on as NameOrRef), // @cast-boundary engine-bridge
+              ...(jobOptions.trigger.where !== undefined
+                ? { where: jobOptions.trigger.where }
+                : {}),
             }
           : jobOptions.trigger;
       state.jobs[jobName] = { ...jobOptions, trigger, name: jobName, handler: jobHandler };

package/src/entrypoint/__tests__/split-deploy.integration.test.ts

@@ -20,6 +20,7 @@ import { createRegistry, defineFeature } from "../../engine";
 import { createArchivedStreamsTable } from "../../event-store";
 import { createEventConsumerStateTable } from "../../pipeline";
 import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
+import { waitFor } from "../../testing";
 import { createAllInOneEntrypoint, createApiEntrypoint, createWorkerEntrypoint } from "../index";
 
 const splitFeature = defineFeature("split", (r) => {
@@ -103,14 +104,6 @@ const fileJobFeature = defineFeature("fileJob", (r) => {
   r.multiStreamProjection({ name: "noop", apply: { [requested.name]: async () => {} } });
 });
 
-async function waitForCondition(check: () => boolean, timeoutMs = 5000): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (!check()) {
-    if (Date.now() > deadline) throw new Error("waitForCondition: timed out");
-    await new Promise((resolve) => setTimeout(resolve, 25));
-  }
-}
-
 const JWT = "split-deploy-test-secret-must-be-32-chars!!";
 
 // Per-test queue-name with a random suffix. Date.now() alone collided
@@ -195,7 +188,7 @@ describe("entrypoint factories", () => {
         { storageKey: "some/key.pdf" },
         TestUsers.admin,
       );
-      await waitForCondition(() => jobSawFilesRef.length > 0);
+      await waitFor(() => jobSawFilesRef.length > 0);
       expect(jobSawFilesRef[0]).toBe("function");
     } finally {
       await worker.stop();
@@ -239,7 +232,7 @@ describe("entrypoint factories", () => {
       // The worker's own eventDispatcher (started above) picks the event
       // back up and runs the MSP — proves the afterCommit/MSP chain works
       // inside the worker lane, not just that the write itself succeeded.
-      await waitForCondition(() => consumedNotes.includes("written from the worker"));
+      await waitFor(() => consumedNotes.includes("written from the worker"));
     } finally {
       await worker.stop();
     }
@@ -264,7 +257,7 @@ describe("entrypoint factories", () => {
         { storageKey: "some/key.pdf" },
         TestUsers.admin,
       );
-      await waitForCondition(() => jobSawFilesRef.length > 0);
+      await waitFor(() => jobSawFilesRef.length > 0);
       expect(jobSawFilesRef[0]).toBe("function");
     } finally {
       await entry.stop();

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

@@ -35,7 +35,7 @@ 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 } from "../types";
+import { parseMaxSize, 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
@@ -222,6 +222,80 @@ describe("file validation", () => {
     expect(sniffMimeType(new Uint8Array([0x00, 0x01, 0x02]))).toBeNull();
     expect(sniffMimeType(new TextEncoder().encode("hello world"))).toBeNull();
   });
+
+  // --- doc/docx magic-byte content verification ---
+
+  const docBytes = new Uint8Array([
+    0xd0,
+    0xcf,
+    0x11,
+    0xe0,
+    0xa1,
+    0xb1,
+    0x1a,
+    0xe1,
+    ...Array(20).fill(0),
+  ]);
+  const docxBytes = new Uint8Array([0x50, 0x4b, 0x03, 0x04, ...Array(20).fill(0)]);
+
+  test("validateFile accepts a .doc/.docx upload on extension/mimeType alone", () => {
+    expect(
+      validateFile(
+        { fileName: "report.doc", mimeType: "application/msword", size: docBytes.length },
+        { accept: ["doc", "docx"] },
+      ),
+    ).toBeNull();
+    expect(
+      validateFile(
+        {
+          fileName: "report.docx",
+          mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+          size: docxBytes.length,
+        },
+        { accept: ["doc", "docx"] },
+      ),
+    ).toBeNull();
+  });
+
+  test("validateFileContent accepts .doc/.docx bytes matching their declared mimeType", () => {
+    expect(validateFileContent("application/msword", docBytes)).toBeNull();
+    expect(
+      validateFileContent(
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        docxBytes,
+      ),
+    ).toBeNull();
+  });
+
+  test("validateFileContent rejects .doc/.docx whose content doesn't match the declared mimeType", () => {
+    const fakeDoc = validateFileContent(
+      "application/msword",
+      new TextEncoder().encode("not actually a Word document, just text"),
+    );
+    expectErrorIncludes(fakeDoc, "content_mismatch");
+
+    const fakeDocx = validateFileContent(
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      new TextEncoder().encode("not actually a docx, just text"),
+    );
+    expectErrorIncludes(fakeDocx, "content_mismatch");
+  });
+
+  test("validateFileContent does not content-verify pre-existing types (e.g. pdf) even when content mismatches", () => {
+    expect(
+      validateFileContent(
+        "application/pdf",
+        new TextEncoder().encode("not a PDF at all, just text"),
+      ),
+    ).toBeNull();
+  });
+
+  test("sniffMimeType recognizes doc (OLE) and docx (ZIP) signatures", () => {
+    expect(sniffMimeType(docBytes)).toBe("application/msword");
+    expect(sniffMimeType(docxBytes)).toBe(
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    );
+  });
 });
 
 // --- Integration: Upload → Download → Delete via real HTTP API ---
@@ -409,6 +483,46 @@ describe("download Content-Type is sniffed from bytes, not trusted from the decl
   });
 });
 
+// --- doc/docx upload via API: content-verified independent of `accept` ---
+
+describe("doc/docx upload is content-verified against magic bytes", () => {
+  const docBytes = new Uint8Array([
+    0xd0,
+    0xcf,
+    0x11,
+    0xe0,
+    0xa1,
+    0xb1,
+    0x1a,
+    0xe1,
+    ...Array(20).fill(0),
+  ]);
+  const docxBytes = new Uint8Array([0x50, 0x4b, 0x03, 0x04, ...Array(20).fill(0)]);
+
+  test("a real .doc upload succeeds", async () => {
+    const res = await uploadFile(adminUser, "report.doc", docBytes, "application/msword");
+    expect(res.status).toBe(201);
+  });
+
+  test("a real .docx upload succeeds", async () => {
+    const res = await uploadFile(
+      adminUser,
+      "report.docx",
+      docxBytes,
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    );
+    expect(res.status).toBe(201);
+  });
+
+  test("a .doc upload whose bytes don't match the declared mimeType is rejected with content_mismatch, even unattached (no `accept` list)", async () => {
+    const fakeDocBytes = new TextEncoder().encode("plain text pretending to be a Word document");
+    const res = await uploadFile(adminUser, "fake.doc", fakeDocBytes, "application/msword");
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain("content_mismatch");
+  });
+});
+
 // --- Cross-user access within a tenant (attached file owner-scope) ---
 
 describe("attached file owner-scope", () => {

package/src/files/__tests__/write-stream.test.ts

@@ -16,6 +16,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtemp, readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { waitFor } from "../../testing";
 import { createInMemoryFileProvider } from "../in-memory-provider";
 import { createLocalProvider } from "../local-provider";
 
@@ -215,12 +216,15 @@ describe("FileStorageProvider.writeStream — Streaming-Property", () => {
       // Poll bis tmp existiert ODER final schon fertig (zu schneller CI).
       let hasTmp = false;
       let alreadyDone = false;
-      for (let i = 0; i < 20 && !hasTmp && !alreadyDone; i++) {
-        await new Promise((r) => setTimeout(r, 10));
-        const dirContents = await readdir(basePath);
-        hasTmp = dirContents.some((f) => f.endsWith(".tmp"));
-        alreadyDone = dirContents.includes("streamed.bin");
-      }
+      await waitFor(
+        async () => {
+          const dirContents = await readdir(basePath);
+          hasTmp = dirContents.some((f) => f.endsWith(".tmp"));
+          alreadyDone = dirContents.includes("streamed.bin");
+          return hasTmp || alreadyDone;
+        },
+        { delays: Array(20).fill(10) },
+      );
       if (alreadyDone && !hasTmp) {
         throw new Error(
           "slowChunks-delay zu kurz fuer CI: writeStream war fertig bevor poll start. " +

package/src/files/file-routes.ts

@@ -27,7 +27,12 @@ import { createFileContext } from "./file-handle";
 import { fileRefEntity } from "./file-ref-entity";
 import { fileRefsTable } from "./file-ref-table";
 import type { FileProviderResolver } from "./provider-resolver";
-import { buildStorageKey, resolveServedContentType, validateFile } from "./types";
+import {
+  buildStorageKey,
+  resolveServedContentType,
+  validateFile,
+  validateFileContent,
+} from "./types";
 
 // Decision returned by a FileAccessGuard — distinct from boolean so callers
 // can't accidentally negate or default it.
@@ -228,13 +233,19 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       generateId(),
     );
 
+    const data = new Uint8Array(await file.arrayBuffer());
+
+    const contentValidationError = validateFileContent(file.type, data);
+    if (contentValidationError) {
+      return c.json({ error: contentValidationError }, 400);
+    }
+
     // 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);
-    const data = new Uint8Array(await file.arrayBuffer());
     await storageProvider.write(storageKey, data, file.type);
 
     // Create via the standard entity executor: emits fileRef.created +

package/src/files/index.ts

@@ -37,10 +37,12 @@ export type {
 export {
   assertSafeStorageKey,
   buildStorageKey,
+  normalizeMimeType,
   parseMaxSize,
   tenantExportPrefix,
   tenantStoragePrefixes,
   validateFile,
+  validateFileContent,
 } from "./types";
 export type { ZipEntry } from "./zip-stream";
 export { createZipStream } from "./zip-stream";

package/src/files/types.ts

@@ -50,6 +50,8 @@ const EXTENSION_MIME_WHITELIST: Record<string, readonly string[]> = {
   csv: ["text/csv", "application/csv", "text/plain"],
   json: ["application/json", "text/json"],
   md: ["text/markdown", "text/plain"],
+  doc: ["application/msword"],
+  docx: ["application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
 } satisfies Record<string, readonly string[]>;
 
 // Magic-byte signatures for the subset of EXTENSION_MIME_WHITELIST that has
@@ -78,6 +80,19 @@ const MAGIC_BYTE_SIGNATURES: ReadonlyArray<{
     matches: (bytes) => startsWithAscii(bytes, "RIFF") && startsWithAscii(bytes, "WEBP", 8),
   },
   { mimeType: "application/pdf", matches: (bytes) => startsWithAscii(bytes, "%PDF-") },
+  // Full 8-byte OLE Compound File signature (legacy .doc/.xls/.ppt share it —
+  // sniffing can't tell them apart by bytes alone, only content-verification
+  // below narrows to msword specifically).
+  {
+    mimeType: "application/msword",
+    matches: (bytes) => startsWithBytes(bytes, [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]),
+  },
+  // ZIP local-file-header signature — .docx/.xlsx/.pptx/plain .zip all share
+  // it; same caveat as OLE above.
+  {
+    mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    matches: (bytes) => startsWithBytes(bytes, [0x50, 0x4b, 0x03, 0x04]),
+  },
 ];
 
 function startsWithBytes(bytes: Uint8Array, signature: readonly number[]): boolean {
@@ -100,6 +115,12 @@ export function sniffMimeType(bytes: Uint8Array): string | null {
   return null;
 }
 
+// Strips a `; charset=…`-style suffix and trims/lowercases — the one
+// normalization every mimeType comparison needs before comparing values.
+export function normalizeMimeType(mimeType: string): string {
+  return mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+}
+
 // image/jpg is not a registered IANA type but EXTENSION_MIME_WHITELIST above
 // accepts it as a jpg alias — sniffMimeType only ever returns the canonical
 // image/jpeg, so without this a legitimately-declared "image/jpg" upload
@@ -119,11 +140,19 @@ const DECLARED_MIME_ALIASES: Readonly<Record<string, string>> = {
 export function resolveServedContentType(bytes: Uint8Array, declaredMimeType: string): string {
   const sniffed = sniffMimeType(bytes);
   if (!sniffed) return "application/octet-stream";
-  const normalizedDeclared = declaredMimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+  const normalizedDeclared = normalizeMimeType(declaredMimeType);
   const declared = DECLARED_MIME_ALIASES[normalizedDeclared] ?? normalizedDeclared;
   return sniffed === declared ? sniffed : "application/octet-stream";
 }
 
+// Signature-checked against the declared mimeType regardless of
+// `options.accept`. Deliberately narrow: most of the whitelist has no magic
+// bytes at all and would reject honestly-mislabeled uploads if checked.
+const CONTENT_VERIFIED_MIME_TYPES = new Set([
+  "application/msword",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+]);
+
 export function validateFile(
   metadata: FileMetadata,
   options: FileValidationOptions,
@@ -146,7 +175,7 @@ export function validateFile(
     // and having the mimeType reflect that.
     const allowedMimes = EXTENSION_MIME_WHITELIST[ext];
     if (allowedMimes && metadata.mimeType) {
-      const normalized = metadata.mimeType.toLowerCase().split(";")[0]?.trim() ?? "";
+      const normalized = normalizeMimeType(metadata.mimeType);
       if (!allowedMimes.includes(normalized)) {
         return `mime_mismatch: extension ".${ext}" does not match mimeType "${metadata.mimeType}"`;
       }
@@ -156,6 +185,19 @@ export function validateFile(
   return null;
 }
 
+// Separate from validateFile: metadata is known before the upload body is
+// fully read, content-verification only after — callers reject early on
+// metadata without buffering bytes they'll then have to reject anyway.
+export function validateFileContent(mimeType: string, content: Uint8Array): string | null {
+  const normalizedDeclared = normalizeMimeType(mimeType);
+  if (!CONTENT_VERIFIED_MIME_TYPES.has(normalizedDeclared)) return null;
+  const signature = MAGIC_BYTE_SIGNATURES.find((s) => s.mimeType === normalizedDeclared);
+  if (signature && !signature.matches(content)) {
+    return `content_mismatch: bytes do not match declared mimeType "${mimeType}"`;
+  }
+  return null;
+}
+
 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__/jobs.integration.test.ts

@@ -439,6 +439,7 @@ describe("concurrency: skip", () => {
 
       // Try dispatching multiple times while first is running
       let skippedCount = 0;
+      // @timeout-exception: #3118 paces repeated dispatch attempts, nothing to poll for
       for (let i = 0; i < 5; i++) {
         await sleep(50);
         const id = await runner.dispatch("test:job:skip-job", { n: i + 2 });
@@ -1212,6 +1213,7 @@ describe("handleEvent maxPerTenant", () => {
       // racing against the handler's own 500ms sleep, which could land
       // outside the window on a starved runner and silently pass.
       await runner.handleEvent("test:write:capped-event", { n: 3 }, user);
+      // @timeout-exception: #3118 asserts a negative (stays capped) at each checkpoint
       for (const delayMs of [50, 100, 200, 400]) {
         await sleep(delayMs);
         const startedNow = jobLog.filter((e) => e.name === "test:job:per-tenant-limited-event");

package/src/jobs/job-runner.ts

@@ -367,6 +367,17 @@ function buildRetryBullOpts(jobDef: JobDefinition): Pick<JobsOptions, "attempts"
   return opts;
 }
 
+// Equality filter on top-level payload fields for a job's trigger.where —
+// lets N jobs share one broad event QN, partitioned by a payload
+// discriminant instead of needing N distinct event types.
+function payloadMatchesTriggerFilter(
+  where: Readonly<Record<string, string | number | boolean>> | undefined,
+  payload: Record<string, unknown>,
+): boolean {
+  if (!where) return true;
+  return Object.entries(where).every(([key, value]) => payload[key] === value);
+}
+
 // BullMQ sweeps queue-wide: any job finishing with keepJobs set can evict
 // OTHER jobs in the same completed/failed zset (moveToFinished lua,
 // removeJobsByMaxAge/removeJobsByMaxCount), not just the finishing job, and
@@ -1263,6 +1274,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
           ? triggerOn.includes(eventName)
           : triggerOn === eventName;
         if (!matches) continue;
+        if (!payloadMatchesTriggerFilter(jobDef.trigger.where, payload)) continue;
         const data: Record<string, unknown> = { ...payload };
         if (user) {
           data["_tenantId"] = user.tenantId;

package/src/lifecycle/__tests__/signal-handlers.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, mock, test } from "bun:test";
+import { waitFor } from "../../testing";
 import { createLifecycle } from "../lifecycle";
 import { attachSignalHandlers } from "../signal-handlers";
 import { createTestLifecycle } from "./create-test-lifecycle";
@@ -95,12 +96,3 @@ describe("attachSignalHandlers", () => {
     expect(process.listenerCount("SIGTERM")).toBe(before);
   });
 });
-
-async function waitFor(predicate: () => boolean, timeoutMs = 500): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (predicate()) return;
-    await new Promise((r) => setTimeout(r, 5));
-  }
-  throw new Error("waitFor timed out");
-}

package/src/pipeline/__tests__/event-dispatcher-db-outage.integration.test.ts

@@ -186,7 +186,12 @@ describe("E: dispatcher survives a DB outage and logs the recovery", () => {
     } finally {
       await dispatcher.stop();
       await listenClient.end({ timeout: 1 });
-      await proxiedDb.close();
+      // Destroy instead of a graceful end(): when proxy2.stop() kills a socket
+      // mid-query, postgres.js keeps that query referenced on the dead
+      // connection, and a plain end() then waits for a resolver only
+      // terminate() fires, so it never returns. The pool is test-owned and
+      // every assertion has already run, so dropping in-flight work is safe.
+      await proxiedDb.client.end({ timeout: 0 });
     }
   });
 });

package/src/pipeline/__tests__/event-dispatcher-lifecycle.integration.test.ts

@@ -31,7 +31,7 @@ import {
   TestUsers,
   unsafeCreateEntityTable,
 } from "../../stack";
-import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+import { sharedWidgetEntity, sharedWidgetTable, waitFor } from "../../testing";
 
 // --- Test fixtures ---
 
@@ -118,7 +118,7 @@ describe("E.1 — .start() lifecycle + slow handler", () => {
 
       // pollIntervalMs in the test-stack is 50ms. Give the timer a few
       // ticks to observe the event.
-      await waitFor(() => observations.length >= 1, 2000);
+      await waitFor(() => observations.length >= 1, { delays: Array(40).fill(50) });
       expect(observations).toHaveLength(1);
       expect(observations[0]?.event.payload["name"]).toBe("started-delivery");
     } finally {
@@ -140,7 +140,7 @@ describe("E.1 — .start() lifecycle + slow handler", () => {
       await appendWidget("slow-3");
 
       // Wait until all 3 slow-observer invocations have completed.
-      await waitFor(() => slowHandlerInvocations.length >= 3, 5000);
+      await waitFor(() => slowHandlerInvocations.length >= 3, { delays: Array(50).fill(100) });
 
       // Check: no invocation overlapped with the next — every pass
       // finished before the following one started. The guard does
@@ -207,14 +207,3 @@ describe("E.1 — consumer-lag metric", () => {
 });
 
 // --- Helpers ---
-
-async function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    if (predicate()) return;
-    await new Promise((r) => setTimeout(r, 20));
-  }
-  if (!predicate()) {
-    throw new Error(`waitFor: predicate never became true within ${timeoutMs}ms`);
-  }
-}

package/src/pipeline/__tests__/event-dispatcher-second-audit.integration.test.ts

@@ -33,7 +33,7 @@ import {
   TestUsers,
   unsafeCreateEntityTable,
 } from "../../stack";
-import { sharedWidgetEntity } from "../../testing";
+import { sharedWidgetEntity, waitFor } from "../../testing";
 import { generateId } from "../../utils";
 
 // --- Fixture ---
@@ -247,7 +247,7 @@ describe("Second audit — LISTEN gauge", () => {
           ).length;
 
         // Wait for the initial onlisten (gauge.set 1) to land.
-        await waitFor(() => connectsWithValue1() >= 1, 2000);
+        await waitFor(() => connectsWithValue1() >= 1, { delays: Array(40).fill(50) });
         const initialConnects = connectsWithValue1();
         expect(initialConnects).toBeGreaterThanOrEqual(1);
 
@@ -266,7 +266,9 @@ describe("Second audit — LISTEN gauge", () => {
 
         // Wait for the SECOND gauge.set(1) — the reconnect. Generous timeout
         // because postgres.js's reconnect loop includes backoff.
-        await waitFor(() => connectsWithValue1() > initialConnects, 10000);
+        await waitFor(() => connectsWithValue1() > initialConnects, {
+          delays: Array(50).fill(200),
+        });
         expect(connectsWithValue1()).toBeGreaterThan(initialConnects);
       } finally {
         await recStack.eventDispatcher?.stop();
@@ -278,14 +280,3 @@ describe("Second audit — LISTEN gauge", () => {
 });
 
 // --- Helpers ---
-
-async function waitFor(predicate: () => boolean, timeoutMs: number): Promise<void> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    if (predicate()) return;
-    await new Promise((r) => setTimeout(r, 25));
-  }
-  if (!predicate()) {
-    throw new Error(`waitFor: predicate never became true within ${timeoutMs}ms`);
-  }
-}

package/src/pipeline/__tests__/job-trigger-consumer.integration.test.ts

@@ -23,6 +23,7 @@ import { defineFeature } from "../../engine";
 import { createInMemoryFileProvider, type InMemoryFileProvider } from "../../files";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";
 import { waitFor } from "../../testing";
+import { generateId } from "../../utils";
 
 const ITEM_REQUESTED_EVENT_QN = "job-trigger-fixture:event:item-requested";
 const FILE_REF_CREATED = entityEventName("fileRef", "created");
@@ -62,25 +63,90 @@ const jobTriggerFixtureFeature = defineFeature("job-trigger-fixture", (r) => {
   );
 });
 
+// trigger.where partition fixture — two jobs share one broad QN, each
+// filtered to a disjoint payload.kind, mirroring document-ingest-foundation's
+// N-providers-one-QN shape without pulling in the whole feature.
+const WHERE_ITEM_REQUESTED_EVENT_QN = "job-trigger-where-fixture:event:item-requested";
+
+const alphaProcessed: Array<{ readonly fileRefId: string }> = [];
+const betaProcessed: Array<{ readonly fileRefId: string }> = [];
+
+const jobTriggerWhereFixtureFeature = defineFeature("job-trigger-where-fixture", (r) => {
+  r.defineEvent(
+    "item-requested",
+    z.object({ fileRefId: z.string().min(1), kind: z.enum(["alpha", "beta"]) }),
+    { piiFields: "none" },
+  );
+
+  r.multiStreamProjection({
+    name: "request-item",
+    apply: {
+      [FILE_REF_CREATED]: async (event, _tx, ctx) => {
+        const fileName = event.payload["fileName"];
+        const kind =
+          typeof fileName === "string" && fileName.startsWith("alpha-") ? "alpha" : "beta";
+        await ctx.unsafeAppendEvent({
+          aggregateId: event.aggregateId,
+          aggregateType: "job-trigger-where-fixture-request",
+          type: WHERE_ITEM_REQUESTED_EVENT_QN,
+          payload: { fileRefId: event.aggregateId, kind },
+        });
+      },
+    },
+  });
+
+  // Under test: both jobs trigger on the SAME QN; only the one whose
+  // `where` matches the appended payload's `kind` may run.
+  r.job(
+    "process-alpha",
+    { trigger: { on: WHERE_ITEM_REQUESTED_EVENT_QN, where: { kind: "alpha" } }, runIn: "worker" },
+    async (payload) => {
+      alphaProcessed.push({ fileRefId: payload["fileRefId"] as string });
+    },
+  );
+  r.job(
+    "process-beta",
+    { trigger: { on: WHERE_ITEM_REQUESTED_EVENT_QN, where: { kind: "beta" } }, runIn: "worker" },
+    async (payload) => {
+      betaProcessed.push({ fileRefId: payload["fileRefId"] as string });
+    },
+  );
+});
+
 let stack: TestStack;
 let provider: InMemoryFileProvider;
+let whereStack: TestStack;
+let whereProvider: InMemoryFileProvider;
 
 beforeAll(async () => {
   provider = createInMemoryFileProvider();
   stack = await setupTestStack({
     features: [jobTriggerFixtureFeature],
     files: { storageProvider: provider },
-    jobs: { consumerLane: "worker" },
+    jobs: { consumerLane: "worker", queueNamePrefix: `job-trigger-fixture-${generateId()}` },
+  });
+  whereProvider = createInMemoryFileProvider();
+  whereStack = await setupTestStack({
+    features: [jobTriggerWhereFixtureFeature],
+    files: { storageProvider: whereProvider },
+    // Distinct prefix from `stack` above — createTestRedis's keyPrefix
+    // isolation doesn't cover BullMQ's own connections, so without this both
+    // JobRunners would race each other on the same default queue name.
+    jobs: { consumerLane: "worker", queueNamePrefix: `job-trigger-where-fixture-${generateId()}` },
   });
 });
 
 afterAll(async () => {
   await stack.cleanup();
+  await whereStack.cleanup();
 });
 
 beforeEach(() => {
   processedItems.length = 0;
   provider.clear();
+  alphaProcessed.length = 0;
+  betaProcessed.length = 0;
+  whereProvider.clear();
 });
 
 describe("job-trigger event consumer", () => {
@@ -106,3 +172,36 @@ describe("job-trigger event consumer", () => {
     expect(processedItems[0]?.fileRefId).toBeTruthy();
   });
 });
+
+describe("job-trigger event consumer — trigger.where partitions one QN across jobs", () => {
+  test("only the job whose where matches the payload runs — both partitions checked, not just the absence of the other", async () => {
+    const token = await whereStack.jwt.sign(TestUsers.admin);
+    async function uploadKind(fileName: string): Promise<string> {
+      const formData = new FormData();
+      formData.append("file", new File([Buffer.from("hello")], fileName, { type: "text/plain" }));
+      const res = await whereStack.app.request("/api/files", {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}` },
+        body: formData,
+      });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as { id: string };
+      return body.id;
+    }
+
+    const alphaFileRefId = await uploadKind("alpha-note.txt");
+    const betaFileRefId = await uploadKind("beta-note.txt");
+
+    await waitFor(async () => {
+      // Drives both jobs' consumers in the same pass — asserting both lists
+      // are non-empty before checking membership rules out "beta simply
+      // hasn't run yet" as an explanation for an empty betaProcessed.
+      await whereStack.eventDispatcher?.runOnce();
+      expect(alphaProcessed).toHaveLength(1);
+      expect(betaProcessed).toHaveLength(1);
+    });
+
+    expect(alphaProcessed).toEqual([{ fileRefId: alphaFileRefId }]);
+    expect(betaProcessed).toEqual([{ fileRefId: betaFileRefId }]);
+  });
+});

package/src/pipeline/msp-rebuild.ts

@@ -115,6 +115,7 @@ function createRebuildCtx(
     });
   };
   return {
+    registry,
     appendEvent: refuseAppend as MultiStreamApplyContext["appendEvent"], // @cast-boundary engine-bridge
     unsafeAppendEvent: refuseAppend,
     loadAggregate: async (aggregateId, options) => {

package/src/pipeline/multi-stream-apply-context.ts

@@ -38,6 +38,7 @@ export function createMultiStreamApplyContext(
   deps: MultiStreamApplyContextDeps,
 ): MultiStreamApplyContext {
   return {
+    registry: deps.registry,
     ...(deps.files ? { files: deps.files } : {}),
     ...(deps.derivatives ? { derivatives: deps.derivatives } : {}),
     appendEvent: (async (args: AppendEventArgs) => {