@cosmicdrift/kumiko-framework 0.312.0 → 0.314.0

package/src/files/storage-tracking.ts

@@ -11,18 +11,28 @@
 // consumer-cursor row. Apps that want it pass filesStorageTrackingFeature
 // into createApp / setupTestStack alongside their domain features.
 
-import { entityEventName } from "../db";
+import { type DbRunner, entityEventName, executeRawQueryRead } from "../db";
 import { bigint, instant, integer, table as pgTable, sql, uuid } from "../db/dialect";
 import { incrementCounter } from "../db/query";
-import { defineFeature } from "../engine";
+import { defineFeature, qn, type Registry, toKebab } from "../engine";
+import {
+  type PendingGapEntry,
+  SHARED_INSTANCE_SENTINEL,
+  selectConsumerCursorForUpdate,
+} from "../pipeline";
+import { parseJsonOrThrow } from "../utils";
+
+const FILE_REF_AGGREGATE_TYPE = "fileRef";
+const STORAGE_TRACKING_FEATURE_NAME = "files-storage-tracking";
+const TENANT_STORAGE_USAGE_MSP_NAME = "tenant-storage-usage";
 
 // fileRef is a standard ES entity, so usage tracking subscribes to its
 // auto-verb events. `fileRef.created` payload carries the entity fields
 // (incl. size); `fileRef.deleted` / `fileRef.restored` carry `{ previous }`
 // (the pre-event row), so the byte count to apply lives at previous.size.
-const FILE_REF_CREATED = entityEventName("fileRef", "created");
-const FILE_REF_DELETED = entityEventName("fileRef", "deleted");
-const FILE_REF_RESTORED = entityEventName("fileRef", "restored");
+const FILE_REF_CREATED = entityEventName(FILE_REF_AGGREGATE_TYPE, "created");
+const FILE_REF_DELETED = entityEventName(FILE_REF_AGGREGATE_TYPE, "deleted");
+const FILE_REF_RESTORED = entityEventName(FILE_REF_AGGREGATE_TYPE, "restored");
 
 function readNumber(value: unknown): number {
   return typeof value === "number" ? value : 0;
@@ -36,6 +46,28 @@ function sizeFromPrevious(payload: Record<string, unknown>): number {
   return 0;
 }
 
+// Single source of truth for "how much does this fileRef event move the
+// tenant's storage counters" — shared by the MSP's own apply handlers and by
+// transferTenantStorageUsage's replay of already-applied events during a
+// tenant handover.
+export function fileRefStorageDelta(event: {
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+}): { readonly bytes: number; readonly files: number } | null {
+  switch (event.type) {
+    case FILE_REF_CREATED:
+      return { bytes: readNumber(event.payload["size"]), files: 1 };
+    case FILE_REF_DELETED:
+      // `0 - x`, not `-x`: a zero-byte previous size must stay `0`, not `-0`
+      // (toEqual/JSON round-trips treat -0 as distinct from 0).
+      return { bytes: 0 - sizeFromPrevious(event.payload), files: -1 };
+    case FILE_REF_RESTORED:
+      return { bytes: sizeFromPrevious(event.payload), files: 1 };
+    default:
+      return null;
+  }
+}
+
 // bigint in `mode: "number"` returns a JS number (safe up to 2^53 ≈ 9e15
 // bytes ≈ 8 petabytes per tenant — large enough for any practical storage
 // quota). Default "bigint" mode would hand back a bigint value, which
@@ -48,13 +80,15 @@ export const tenantStorageUsageTable = pgTable("read_tenant_storage_usage", {
   lastUpdatedAt: instant("last_updated_at").default(sql`now()`).notNull(),
 });
 
-export const filesStorageTrackingFeature = defineFeature("files-storage-tracking", (r) => {
+export const filesStorageTrackingFeature = defineFeature(STORAGE_TRACKING_FEATURE_NAME, (r) => {
   r.multiStreamProjection({
-    name: "tenant-storage-usage",
+    name: TENANT_STORAGE_USAGE_MSP_NAME,
     table: tenantStorageUsageTable,
     apply: {
       [FILE_REF_CREATED]: async (event, tx) => {
-        const size = readNumber(event.payload["size"]);
+        const delta = fileRefStorageDelta(event);
+        // skip: not a tracked fileRef storage change
+        if (!delta) return;
 
         // UPSERT: INSERT on first upload per tenant, otherwise atomic increment.
         // The SQL increment guarantees correctness under concurrent dispatcher
@@ -63,13 +97,15 @@ export const filesStorageTrackingFeature = defineFeature("files-storage-tracking
         await incrementCounter(
           tx,
           tenantStorageUsageTable,
-          { tenantId: event.tenantId, totalBytes: size, fileCount: 1 },
-          { totalBytes: size, fileCount: 1 },
+          { tenantId: event.tenantId, totalBytes: delta.bytes, fileCount: delta.files },
+          { totalBytes: delta.bytes, fileCount: delta.files },
           { set: { lastUpdatedAt: sql`now()` } },
         );
       },
       [FILE_REF_DELETED]: async (event, tx) => {
-        const size = sizeFromPrevious(event.payload);
+        const delta = fileRefStorageDelta(event);
+        // skip: not a tracked fileRef storage change
+        if (!delta) return;
         // Decrement on delete. INSERT values are 0/0 so a delete that somehow
         // precedes any upload can't create negative usage; the on-conflict
         // path applies the real negative delta. Async (dispatcher) —
@@ -78,7 +114,7 @@ export const filesStorageTrackingFeature = defineFeature("files-storage-tracking
           tx,
           tenantStorageUsageTable,
           { tenantId: event.tenantId, totalBytes: 0, fileCount: 0 },
-          { totalBytes: -size, fileCount: -1 },
+          { totalBytes: delta.bytes, fileCount: delta.files },
           { set: { lastUpdatedAt: sql`now()` } },
         );
       },
@@ -86,15 +122,124 @@ export const filesStorageTrackingFeature = defineFeature("files-storage-tracking
         // Restore re-increments by the soft-deleted row's size — symmetric
         // to delete. Without this handler totalBytes/fileCount drift low
         // after every delete→restore round-trip.
-        const size = sizeFromPrevious(event.payload);
+        const delta = fileRefStorageDelta(event);
+        // skip: not a tracked fileRef storage change
+        if (!delta) return;
         await incrementCounter(
           tx,
           tenantStorageUsageTable,
-          { tenantId: event.tenantId, totalBytes: size, fileCount: 1 },
-          { totalBytes: size, fileCount: 1 },
+          { tenantId: event.tenantId, totalBytes: delta.bytes, fileCount: delta.files },
+          { totalBytes: delta.bytes, fileCount: delta.files },
           { set: { lastUpdatedAt: sql`now()` } },
         );
       },
     },
   });
 });
+
+// Qualified name of the tenant-storage-usage MSP consumer row in
+// kumiko_event_consumers — the same qualification registry-ingest.ts applies
+// to every multiStreamProjection (qualify(featureName, "projection", name)).
+const TENANT_STORAGE_USAGE_MSP_QN = qn(
+  toKebab(STORAGE_TRACKING_FEATURE_NAME),
+  "projection",
+  toKebab(TENANT_STORAGE_USAGE_MSP_NAME),
+);
+
+const TRACKED_FILE_REF_EVENT_TYPES = [FILE_REF_CREATED, FILE_REF_DELETED, FILE_REF_RESTORED];
+
+function isWithinPendingGap(eventId: bigint, gaps: readonly PendingGapEntry[]): boolean {
+  return gaps.some((gap) => eventId >= BigInt(gap.from) && eventId <= BigInt(gap.to));
+}
+
+// Moves the already-applied share of the tenant-storage-usage counters from
+// source to destination tenant when a tenant-handover claim moves fileRef
+// rows. Must run BEFORE moveEventHistory rewrites the events' tenant_id —
+// the query below finds "already applied" events by sourceTenantId, and once
+// the rewrite runs there is no way to tell an already-applied event from a
+// not-yet-applied one by tenant_id alone.
+//
+// Events with id above the cursor (or inside a pending gap) are NOT summed
+// here: the dispatcher hasn't applied them yet, they will carry the
+// destination tenant_id once moveEventHistory runs, and the dispatcher will
+// apply them against the destination counter on its own next pass.
+export async function transferTenantStorageUsage(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly fileRefIds: readonly string[];
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+}): Promise<void> {
+  const { db, registry, fileRefIds, sourceTenantId, destinationTenantId } = args;
+  // skip: no fileRefs moved, nothing to transfer
+  if (fileRefIds.length === 0) return;
+  // skip: storage tracking is not mounted in this app
+  if (!registry.getAllMultiStreamProjections().has(TENANT_STORAGE_USAGE_MSP_QN)) return;
+
+  // Locks the same consumer row the dispatcher's own FOR UPDATE SKIP LOCKED
+  // pass takes before applying a batch — serializing against it here means no
+  // fileRef event for these ids can be applied between reading the cursor
+  // below and the tenant move that follows in the caller.
+  const cursor = await selectConsumerCursorForUpdate(
+    db,
+    TENANT_STORAGE_USAGE_MSP_QN,
+    SHARED_INSTANCE_SENTINEL,
+  );
+  // skip: no consumer row means the MSP never applied anything yet
+  if (!cursor) return;
+
+  const rows = await executeRawQueryRead<{ id: string; type: string; payload: string }>(
+    db,
+    `SELECT "id"::text AS id, "type", "payload"::text AS payload FROM kumiko_events
+     WHERE "tenant_id" = $1 AND "aggregate_type" = $2 AND "aggregate_id" = ANY($3)
+       AND "type" = ANY($4) AND "id" <= $5`,
+    [
+      sourceTenantId,
+      FILE_REF_AGGREGATE_TYPE,
+      fileRefIds,
+      TRACKED_FILE_REF_EVENT_TYPES,
+      cursor.lastProcessedEventId,
+    ],
+  );
+
+  let bytes = 0;
+  let files = 0;
+  for (const row of rows) {
+    if (isWithinPendingGap(BigInt(row.id), cursor.pendingGaps)) continue;
+    const delta = fileRefStorageDelta({
+      type: row.type,
+      payload: parseJsonOrThrow<Record<string, unknown>>(
+        row.payload,
+        "transferTenantStorageUsage: kumiko_events.payload",
+      ),
+    });
+    if (!delta) continue;
+    bytes += delta.bytes;
+    files += delta.files;
+  }
+  // skip: the moved fileRefs carry no applied storage share
+  if (bytes === 0 && files === 0) return;
+
+  // Source: insert-values stay 0/0 (same guard as the DELETED handler above)
+  // — the row this subtracts from is expected to already exist (the MSP
+  // already applied the create against it), and if it somehow doesn't, this
+  // must not conjure a negative balance out of thin air.
+  await incrementCounter(
+    db,
+    tenantStorageUsageTable,
+    { tenantId: sourceTenantId, totalBytes: 0, fileCount: 0 },
+    { totalBytes: -bytes, fileCount: -files },
+    { set: { lastUpdatedAt: sql`now()` } },
+  );
+  // Destination: insert-values ARE the transferred amount (same as CREATED/
+  // RESTORED above) — a tenant claiming its first-ever fileRef must start
+  // its counter row at the transferred total, not at 0 with an increment
+  // that only fires once a row already exists.
+  await incrementCounter(
+    db,
+    tenantStorageUsageTable,
+    { tenantId: destinationTenantId, totalBytes: bytes, fileCount: files },
+    { totalBytes: bytes, fileCount: files },
+    { set: { lastUpdatedAt: sql`now()` } },
+  );
+}

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/jobs/job-runner.ts

@@ -13,6 +13,7 @@ import {
   type JobContext,
   type JobDefinition,
   type JobRunIn,
+  type JobTriggerEvent,
   type MemberReader,
   type Registry,
   type SessionUser,
@@ -42,6 +43,22 @@ import {
 } from "../pipeline/write-origin";
 import { bridgeStub } from "../testing/handler-context";
 
+// Shape-checked after the BullMQ/Redis JSON round-trip. Unlike `_writeOrigin`
+// (a security-relevant escape hatch that must fail the run closed), a
+// malformed `_triggerEvent` only costs an idempotency-key convenience — the
+// run proceeds without it rather than failing over what would be a framework
+// bug, not untrusted input.
+function isJobTriggerEvent(value: unknown): value is JobTriggerEvent {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate["id"] !== "string") return false;
+  const headers = candidate["headers"];
+  if (typeof headers !== "object" || headers === null) return false;
+  return Object.values(headers as Record<string, unknown>).every(
+    (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean",
+  );
+}
+
 // A payload's own `_writeOrigin` is never trusted; only the ambient gated origin is stamped.
 function stampGatedWriteOrigin(data: Record<string, unknown>): void {
   delete data["_writeOrigin"];
@@ -216,6 +233,7 @@ export type JobRunner = {
     eventName: string,
     payload: Record<string, unknown>,
     user?: SessionUser,
+    triggerEvent?: JobTriggerEvent,
   ): Promise<void>;
   // Wires JobContext.write/writeAs/queryAs to the real dispatcher — called
   // once at boot, after the dispatcher exists (job-runner construction happens
@@ -759,6 +777,12 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // don't dig through the raw payload themselves.
     const triggerName = rawData["_triggerName"] as string | undefined; // @cast-boundary dynamic-key
 
+    // Same carry-through for `_triggerEvent` — handleEvent injects it when
+    // the job-trigger event consumer supplied the stored event that fired
+    // this run (see createJobTriggerEventConsumer).
+    const rawTriggerEvent = rawData["_triggerEvent"];
+    const triggerEvent = isJobTriggerEvent(rawTriggerEvent) ? rawTriggerEvent : undefined;
+
     // Absent = legacy or ungated root; present but invalid fails the run closed.
     const rawWriteOrigin = rawData["_writeOrigin"]; // @cast-boundary dynamic-key
     let jobOrigin: WriteOrigin | undefined;
@@ -866,6 +890,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       triggeredBy: triggeredById !== null ? { id: triggeredById, tenantId } : null,
       log: createJobLogger(logs),
       ...(triggerName !== undefined && { triggerName }),
+      ...(triggerEvent !== undefined && { triggerEvent }),
       write: (qn: string, payload: unknown) => {
         if (!dispatchWriteRef) {
           throw new Error(
@@ -1258,6 +1283,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       eventName: string,
       payload: Record<string, unknown>,
       user?: SessionUser,
+      triggerEvent?: JobTriggerEvent,
     ): Promise<void> {
       const traceCtx = captureTraceContext(tracer);
       // Same correlation propagation as dispatch(): events triggered from
@@ -1285,6 +1311,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         // setzen wir es auch — kostet nichts und vereinfacht Handler-Code
         // (kein "ist es Multi?"-Branch nötig).
         data["_triggerName"] = eventName;
+        if (triggerEvent) data["_triggerEvent"] = triggerEvent;
         if (traceCtx) data[TRACE_CONTEXT_KEY] = traceCtx;
         if (reqCtx?.correlationId) data["_correlationId"] = reqCtx.correlationId;
         // Same maxPerTenant guard as dispatch — events that fan into many

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

@@ -195,3 +195,30 @@ describe("E: dispatcher survives a DB outage and logs the recovery", () => {
     }
   });
 });
+
+describe("F: stop() waits for a pass still mid-flight", () => {
+  test("stop() waits for a pass still in its idle pre-check", async () => {
+    const consumer: EventConsumer = {
+      name: "dboutage:consumer-stop-race",
+      handler: async () => {},
+    };
+    const dispatcher: EventDispatcher = createEventDispatcher({
+      db: stack.db,
+      consumers: [consumer],
+      context: { db: stack.db },
+      pollIntervalMs: 60_000,
+    });
+
+    await dispatcher.start();
+    let passSettled = false;
+    // A pass woken by runOnce() has not registered any turn yet while it is
+    // still awaiting the idle pre-check (selectIdleConsumerKeys) — stop()
+    // must wait for it too, or it queries the pool stop() is closing.
+    const pass = dispatcher.runOnce().finally(() => {
+      passSettled = true;
+    });
+    await dispatcher.stop();
+    expect(passSettled).toBe(true);
+    await pass;
+  });
+});

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

@@ -19,7 +19,8 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import * as z from "zod";
 import { entityEventName } from "../../db";
-import { defineFeature } from "../../engine";
+import { defineFeature, type JobContext } from "../../engine";
+import { loadAggregate } from "../../event-store";
 import { createInMemoryFileProvider, type InMemoryFileProvider } from "../../files";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";
 import { waitFor } from "../../testing";
@@ -27,8 +28,13 @@ import { generateId } from "../../utils";
 
 const ITEM_REQUESTED_EVENT_QN = "job-trigger-fixture:event:item-requested";
 const FILE_REF_CREATED = entityEventName("fileRef", "created");
+const PROVIDER_EVENT_ID_HEADER = "providerEventId";
 
-const processedItems: Array<{ readonly fileRefId: string }> = [];
+const processedItems: Array<{
+  readonly fileRefId: string;
+  readonly triggerEvent: JobContext["triggerEvent"];
+  readonly rawDataKeys: readonly string[];
+}> = [];
 
 const jobTriggerFixtureFeature = defineFeature("job-trigger-fixture", (r) => {
   r.defineEvent("item-requested", z.object({ fileRefId: z.string().min(1) }), {
@@ -37,7 +43,8 @@ const jobTriggerFixtureFeature = defineFeature("job-trigger-fixture", (r) => {
 
   // Mirrors document-ingest-foundation's request-ingest MSP exactly: reacts
   // to fileRef.created, appends a NEW event via unsafeAppendEvent — no
-  // write-handler behind the appended event itself.
+  // write-handler behind the appended event itself. headers carries a
+  // provider-style idempotency key so the job side can assert it round-trips.
   r.multiStreamProjection({
     name: "request-item",
     apply: {
@@ -47,6 +54,7 @@ const jobTriggerFixtureFeature = defineFeature("job-trigger-fixture", (r) => {
           aggregateType: "job-trigger-fixture-request",
           type: ITEM_REQUESTED_EVENT_QN,
           payload: { fileRefId: event.aggregateId },
+          headers: { [PROVIDER_EVENT_ID_HEADER]: "provider-evt-42" },
         });
       },
     },
@@ -57,8 +65,12 @@ const jobTriggerFixtureFeature = defineFeature("job-trigger-fixture", (r) => {
   r.job(
     "process-item",
     { trigger: { on: ITEM_REQUESTED_EVENT_QN }, runIn: "worker" },
-    async (payload) => {
-      processedItems.push({ fileRefId: payload["fileRefId"] as string });
+    async (payload, ctx) => {
+      processedItems.push({
+        fileRefId: payload["fileRefId"] as string,
+        triggerEvent: ctx.triggerEvent,
+        rawDataKeys: Object.keys(payload),
+      });
     },
   );
 });
@@ -169,7 +181,23 @@ describe("job-trigger event consumer", () => {
       expect(processedItems).toHaveLength(1);
     });
 
-    expect(processedItems[0]?.fileRefId).toBeTruthy();
+    const processed = processedItems[0];
+    expect(processed?.fileRefId).toBeTruthy();
+
+    // aggregateId of the appended item-requested event is the fileRef's id
+    // (the MSP apply carries event.aggregateId straight through).
+    const fileRefId = processed?.fileRefId as string;
+    const storedEvents = await loadAggregate(stack.db, fileRefId, TestUsers.admin.tenantId);
+    const itemRequested = storedEvents.find((e) => e.type === ITEM_REQUESTED_EVENT_QN);
+    expect(itemRequested).toBeDefined();
+
+    // triggerEvent carries the stored event's own id and headers through to
+    // the job — the idempotency-key surface at-least-once delivery needs.
+    expect(processed?.triggerEvent?.id).toBe(itemRequested?.id);
+    expect(processed?.triggerEvent?.headers[PROVIDER_EVENT_ID_HEADER]).toBe("provider-evt-42");
+
+    // Reserved keys never leak into the payload the handler receives.
+    expect(processed?.rawDataKeys).not.toContain("_triggerEvent");
   });
 });
 

package/src/pipeline/event-dispatcher-delivery.ts

@@ -3,12 +3,13 @@
 // resolve against (same #1438 dual-package-hazard pattern as event-store.ts).
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import { type RequestContextData, requestContext } from "../api/request-context";
-import type { DbConnection, DbTx } from "../db/connection";
+import type { DbConnection, DbRunner, DbTx } from "../db/connection";
 import {
   insertConsumerIfAbsent,
   markConsumerProcessing,
   rearmDeadConsumer,
   recordConsumerPassFailure,
+  selectConsumerForUpdate,
   selectConsumerForUpdateSkipLocked,
   selectProvablyIdleConsumerPairs,
   updateConsumerDeliveryOutcome,
@@ -160,6 +161,26 @@ export async function acquireConsumerState(
   return { state, skip: null };
 }
 
+export type ConsumerCursor = {
+  readonly lastProcessedEventId: bigint;
+  readonly pendingGaps: readonly PendingGapEntry[];
+};
+
+// Blocking FOR UPDATE (not SKIP LOCKED): callers of this one need to actually
+// wait for the dispatcher's own turn to finish, not skip past it, so their
+// read of the already-applied cursor is guaranteed to be up to date rather
+// than possibly stale.
+export async function selectConsumerCursorForUpdate(
+  db: DbRunner,
+  name: string,
+  instanceId: string,
+): Promise<ConsumerCursor | undefined> {
+  const rawState = await selectConsumerForUpdate(db, name, instanceId);
+  if (!rawState) return undefined;
+  const state = coerceRow(rawState, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow;
+  return { lastProcessedEventId: state.lastProcessedEventId, pendingGaps: state.pendingGaps };
+}
+
 // Read-only pre-check run once per doPass, before any consumer's turn opens
 // a transaction (event-dispatcher.ts's doPass/runConsumerTurn). Keyed like
 // consumerBackoff/inFlightTurns: `${name}:${instanceId}`. Consumers not

package/src/pipeline/event-dispatcher.ts

@@ -385,13 +385,34 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
     );
   }
 
+  // A pass still in doPass's idle pre-check (selectIdleConsumerKeys) hasn't
+  // registered any consumer turn in inFlightTurns yet — stop() must wait for
+  // it too, or it keeps querying the pool stop() is about to close.
+  const inFlightPasses = new Set<Promise<DispatcherPassResult>>();
+
+  async function drainInFlightPasses(): Promise<void> {
+    await Promise.all(
+      [...inFlightPasses].map((pass) =>
+        pass.catch(() => {
+          // skip: errors already recorded per-consumer inside the pass
+        }),
+      ),
+    );
+  }
+
   async function runOnce(): Promise<DispatcherPassResult> {
     if (!preRegistered) {
       throw new Error(
         "EventDispatcher.runOnce() called before start() — consumer state rows are not registered. Call start() first (production) or ensureRegistered() (tests after truncating kumiko_event_consumers).",
       );
     }
-    return doPass();
+    const pass = doPass();
+    inFlightPasses.add(pass);
+    try {
+      return await pass;
+    } finally {
+      inFlightPasses.delete(pass);
+    }
   }
 
   async function doPass(): Promise<DispatcherPassResult> {
@@ -764,7 +785,9 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
         emitEventDispatcherListenConnected(meter, false);
       }
 
-      // Drain any in-flight pass so shutdown observes consistent state.
+      // Drain any in-flight pass so shutdown observes consistent state —
+      // including one still stuck in the idle pre-check above inFlightTurns.
+      await drainInFlightPasses();
       await drainInFlightTurns();
       // preRegistered stays true — the rows survive stop(). runOnce()
       // after a stop() still works (tests stop the timer and then drain

package/src/pipeline/index.ts

@@ -15,11 +15,12 @@ export type { DistributedLock } from "./distributed-lock";
 export { createDistributedLock } from "./distributed-lock";
 export type { EntityCache, EntityCacheOptions } from "./entity-cache";
 export { createEntityCache } from "./entity-cache";
-export type { ConsumerStatus } from "./event-consumer-state";
+export type { ConsumerStatus, PendingGapEntry } from "./event-consumer-state";
 export {
   ConsumerStatuses,
   createEventConsumerStateTable,
   eventConsumerStateTable,
+  SHARED_INSTANCE_SENTINEL,
 } from "./event-consumer-state";
 export type { EventDedup } from "./event-dedup";
 export { createEventDedup } from "./event-dedup";
@@ -43,6 +44,8 @@ export {
   restartConsumer,
   skipPoisonEvent,
 } from "./event-dispatcher";
+export type { ConsumerCursor } from "./event-dispatcher-delivery";
+export { selectConsumerCursorForUpdate } from "./event-dispatcher-delivery";
 export type { PruneEventsOptions, PruneEventsResult } from "./event-retention";
 export { ConsumerLagError, pruneEvents } from "./event-retention";
 export type { IdempotencyGuard } from "./idempotency";