@cosmicdrift/kumiko-framework 0.312.0 → 0.313.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.312.0",
+  "version": "0.313.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.312.0",
-    "@cosmicdrift/kumiko-types": "0.312.0",
+    "@cosmicdrift/kumiko-http": "0.313.0",
+    "@cosmicdrift/kumiko-types": "0.313.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.312.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.313.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/auth-routes.ts

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

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "DB pool close() no longer hangs forever during an outage",
+    "detail": "createDbConnection/createConnection's close() and PgKmsAdapter.close()\ncalled client.end() with no timeout, which postgres.js waits on\nindefinitely if a query is still referenced on a dead connection — a DB\noutage during process shutdown could hang forever. close() now bounds\nthe wait via a new closeTimeoutSeconds option on DbConnectionOptions\n(default 5s, DEFAULT_DB_CLOSE_TIMEOUT_SECONDS). No migration needed."
+  },
+  {
+    "version": "0.313.0",
+    "type": "fix",
+    "title": "event-dispatcher stop() waits for a pass still in its idle pre-check",
+    "detail": "Since 0.308.0 a pass started by the timer or a NOTIFY wake-up shortly\nbefore stop() could still be inside its idle pre-check, which stop()\nnever waited for. That pass kept running after stop() returned and\nqueried the DB pool the caller was closing, which could make\npostgres.js' end() hang. stop() now also drains in-flight passes.\nNo migration needed."
+  },
+  {
+    "version": "0.313.0",
+    "type": "improvement",
+    "title": "Event-triggered jobs get the triggering event's id and headers via ctx.triggerEvent",
+    "detail": "r.job's `trigger.on` reached via an r.defineEvent QN (async, at-least-once\ndelivery through the job-trigger event consumer) had no way to key an\nidempotency check on the stored event that fired it. JobContext now\ncarries `triggerEvent?: { id, headers }` — the stored event's id and\nmetadata.headers — when the job was reached this way. Undefined for\ncron/manual jobs and for jobs triggered synchronously off a write/query\nhandler (no stored event to hand over). No migration needed."
+  },
   {
     "version": "0.312.0",
     "type": "improvement",

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

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

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

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

package/src/db/api.ts

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

package/src/db/bun-provider.ts

@@ -8,7 +8,11 @@
 // Bun.SQL hat kein LISTEN — postgres-js-Peer für event-dispatcher.
 
 import postgres from "postgres";
-import type { DbConnectionOptions, DbPoolHandle } from "./api";
+import {
+  type DbConnectionOptions,
+  type DbPoolHandle,
+  DEFAULT_DB_CLOSE_TIMEOUT_SECONDS,
+} from "./api";
 
 export function createBunConnection(url: string, options: DbConnectionOptions = {}): DbPoolHandle {
   const bunOpts: { max?: number; idleTimeout?: number; connectionTimeout?: number } = {};
@@ -25,13 +29,14 @@ export function createBunConnection(url: string, options: DbConnectionOptions =
     pgOpts.connect_timeout = options.connectTimeoutSeconds;
   const listenClient = postgres(url, pgOpts);
 
+  const closeTimeout = options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS;
   return {
     db,
     client: listenClient,
     listenClient,
     close: async () => {
-      await db.end();
-      await listenClient.end();
+      await db.end({ timeout: closeTimeout });
+      await listenClient.end({ timeout: closeTimeout });
     },
   };
 }

package/src/db/connection.ts

@@ -3,6 +3,7 @@
 import type { DbConnection, PgClient } from "@cosmicdrift/kumiko-types/db-connection";
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "./api";
 
 // Raw client types (postgres-js | Bun.SQL) — the name used across query/
 // event-store/pipeline call sites. The structural pool handle from ./api is
@@ -33,9 +34,8 @@ export function createDbConnection(
   return {
     db: client,
     client,
-    close: async () => {
-      await client.end();
-    },
+    close: () =>
+      client.end({ timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS }),
   };
 }
 

package/src/db/eagerload.ts

@@ -26,6 +26,7 @@
 import { requestContext } from "../api/request-context";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues } from "../crypto";
 import { selectMany } from "../db/query";
+import { parseRefTargetEntityName } from "../engine/parse-ref-target";
 import type { EntityDefinition, FieldDefinition, ReferenceFieldDef } from "../engine/types";
 import {
   collectEncryptedFieldNames,
@@ -67,21 +68,13 @@ function isReferenceField(field: FieldDefinition): field is ReferenceFieldDef {
   return field.type === "reference";
 }
 
-function parseRefEntity(raw: string): string {
-  // Same-feature ("user") oder cross-feature ("users:user") — wir
-  // brauchen nur den entity-name (Names sind global eindeutig in
-  // entityMap). Der feature-prefix dient nur der Author-Klarheit.
-  const idx = raw.indexOf(":");
-  return idx < 0 ? raw : raw.slice(idx + 1);
-}
-
 export function collectReferenceFields(entity: EntityDefinition): readonly ReferenceFieldEntry[] {
   const out: ReferenceFieldEntry[] = [];
   for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
     if (!isReferenceField(fieldDef)) continue;
     out.push({
       fieldName,
-      refEntityName: parseRefEntity(fieldDef.entity),
+      refEntityName: parseRefTargetEntityName(fieldDef.entity),
       multiple: fieldDef.multiple === true,
     });
   }

package/src/db/index.ts

@@ -114,7 +114,7 @@ export {
   type PgErrorInfo,
 } from "./pg-error";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock";
-export { executeRawQuery } from "./queries/raw-sql";
+export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql";
 export type { SelectOptions, WhereObject, WhereValue } from "./query-api";
 export {
   asRawClient,

package/src/db/postgres-provider.ts

@@ -3,7 +3,11 @@
 // `asRawClient(db)` wrappt .unsafe und .begin transparent.
 
 import postgres from "postgres";
-import type { DbConnectionOptions, DbPoolHandle } from "./api";
+import {
+  type DbConnectionOptions,
+  type DbPoolHandle,
+  DEFAULT_DB_CLOSE_TIMEOUT_SECONDS,
+} from "./api";
 
 export function createPgConnection(url: string, options: DbConnectionOptions = {}): DbPoolHandle {
   const pgOptions: Parameters<typeof postgres>[1] = {};
@@ -18,8 +22,7 @@ export function createPgConnection(url: string, options: DbConnectionOptions = {
   return {
     db: client,
     client,
-    close: async () => {
-      await client.end();
-    },
+    close: () =>
+      client.end({ timeout: options.closeTimeoutSeconds ?? DEFAULT_DB_CLOSE_TIMEOUT_SECONDS }),
   };
 }

package/src/db/queries/event-consumer.ts

@@ -326,11 +326,12 @@ export async function selectConsumerForUpdate(
   db: AnyDb,
   name: string,
   instanceId: string,
-): Promise<void> {
-  await asRawClient(db).unsafe(
+): Promise<Record<string, unknown> | undefined> {
+  const rows = (await asRawClient(db).unsafe(
     `SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE`,
     [name, instanceId],
-  );
+  )) as ReadonlyArray<Record<string, unknown>>;
+  return rows[0];
 }
 
 export async function updateConsumerRebuildCursor(

package/src/engine/boot-validator/__tests__/transfer-graph.test.ts

@@ -115,6 +115,18 @@ describe("validateTransferGraph", () => {
     expect(() => validate(chain)).not.toThrow();
   });
 
+  // A feature-prefixed reference target ("<feature>:<entity>") must resolve
+  // to the same entity name as an unprefixed one, or a chain built entirely
+  // out of prefixed refs would silently never trip the depth limit.
+  test("counts a chain of feature-prefixed reference targets into the depth limit", () => {
+    const chain: Record<string, EntityDefinition> = { e0: entity({}) };
+    for (let i = 1; i <= MAX_TRANSFER_DEPTH + 1; i++) {
+      chain[`e${i}`] = entity({ references: { parentId: { entity: `graph:e${i - 1}` } } });
+    }
+
+    expect(() => validate(chain)).toThrow(/deeper than the 5-level limit.*e0 -> e1/s);
+  });
+
   test("terminates on a reference cycle instead of reporting false depth", () => {
     expect(() =>
       validate({

package/src/engine/boot-validator/transfer-graph.ts

@@ -1,3 +1,4 @@
+import { parseRefTargetEntityName } from "../parse-ref-target";
 import type { EntityDefinition, FeatureDefinition } from "../types";
 
 // --- Transfer-graph boot validation (fw#3088) ---
@@ -39,7 +40,7 @@ function referenceTargets(entity: EntityDefinition): readonly string[] {
   for (const field of Object.values(entity.fields)) {
     if (field.type !== "reference") continue;
     if (field.multiple === true) continue;
-    targets.push(field.entity);
+    targets.push(parseRefTargetEntityName(field.entity));
   }
   return targets;
 }

package/src/engine/index.ts

@@ -264,6 +264,8 @@ export {
   userCanReadFieldRow,
   userCanWriteFieldRow,
 } from "./ownership";
+export type { ParsedRefTarget } from "./parse-ref-target";
+export { parseRefTarget, parseRefTargetEntityName } from "./parse-ref-target";
 export { buildPipelineSteps, stepsPipeline } from "./pipeline";
 export { defineApply, defineMspApply, setFields } from "./projection-helpers";
 export type { BuiltinQnType, ParsedQn, QnType } from "./qualified-name";
@@ -431,6 +433,7 @@ export type {
   JobDefinition,
   JobHandlerFn,
   JobTrigger,
+  JobTriggerEvent,
   JsonbFieldDef,
   KumikoEntityTypeMap,
   KumikoEventTypeMap,

package/src/engine/parse-ref-target.ts

@@ -20,3 +20,9 @@ export function parseRefTarget(raw: string, currentFeature: string): ParsedRefTa
   }
   return { featureName: raw.slice(0, idx), entityName: raw.slice(idx + 1) };
 }
+
+// Entity names are globally unique in the registry, so callers that only
+// need the entity (not its owning feature) can drop the currentFeature arg.
+export function parseRefTargetEntityName(raw: string): string {
+  return parseRefTarget(raw, "").entityName;
+}

package/src/engine/registry-validate.ts

@@ -2,6 +2,7 @@ import { configureEventPiiCatalog } from "../crypto/event-pii";
 import { hasSearchablePlaintext, isSensitiveLabelField } from "../db/entity-field-encryption";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch";
 import { resolveName } from "./handler-helpers";
+import { parseRefTargetEntityName } from "./parse-ref-target";
 import type {
   RegistryState,
   SearchableReferenceField,
@@ -192,16 +193,6 @@ export function applyExtensionUsages(state: RegistryState): void {
   }
 }
 
-// "customer" (same-feature) or "users:customer" (cross-feature,
-// "<featureName>:<entityName>") — only the entity name matters here, names
-// are globally unique in entityMap. Local duplicate of the same parse done
-// in db/eagerload.ts's parseRefEntity — this loop has no feature context to
-// hand to engine/parse-ref-target.ts's parseRefTarget.
-function parseReferenceTargetEntityName(raw: string): string {
-  const idx = raw.indexOf(":");
-  return idx < 0 ? raw : raw.slice(idx + 1);
-}
-
 // fw#2660: labelField defaults to "id" (a UUID column) elsewhere, but a
 // searchable reference ILIKEs the label column — an implicit or explicit
 // "id" default would 500 on every search request. Fail at boot.
@@ -224,7 +215,7 @@ function buildSearchableReferenceField(
         `(array) reference fields — remove "multiple" or "searchable".`,
     );
   }
-  const targetEntityName = parseReferenceTargetEntityName(field.entity);
+  const targetEntityName = parseRefTargetEntityName(field.entity);
   const targetEntity = entityMap.get(targetEntityName);
   if (targetEntity !== undefined) {
     if (
@@ -273,7 +264,7 @@ function buildSortableReferenceField(
   }
   return {
     fieldName,
-    targetEntityName: parseReferenceTargetEntityName(field.entity),
+    targetEntityName: parseRefTargetEntityName(field.entity),
     labelField: field.labelField,
   };
 }

package/src/engine/types/index.ts

@@ -185,6 +185,7 @@ export type {
   HandlerRef,
   JobContext,
   JobRunnerRef,
+  JobTriggerEvent,
   MemberReader,
   NameOrRef,
   NotifyFactory,

package/src/files/__tests__/storage-tracking.test.ts

@@ -0,0 +1,46 @@
+// fileRefStorageDelta — the single source of truth the tenant-storage-usage
+// MSP's apply handlers and transferTenantStorageUsage's replay both use to
+// turn one fileRef event into a signed (bytes, files) delta.
+
+import { describe, expect, test } from "bun:test";
+import { entityEventName } from "../../db";
+import { fileRefStorageDelta } from "../storage-tracking";
+
+const CREATED = entityEventName("fileRef", "created");
+const DELETED = entityEventName("fileRef", "deleted");
+const RESTORED = entityEventName("fileRef", "restored");
+
+describe("fileRefStorageDelta", () => {
+  test("created: positive delta from payload.size", () => {
+    expect(fileRefStorageDelta({ type: CREATED, payload: { size: 42 } })).toEqual({
+      bytes: 42,
+      files: 1,
+    });
+  });
+
+  test("created: missing/non-numeric size reads as 0 bytes, still counts a file", () => {
+    expect(fileRefStorageDelta({ type: CREATED, payload: {} })).toEqual({ bytes: 0, files: 1 });
+  });
+
+  test("deleted: negative delta from payload.previous.size", () => {
+    expect(fileRefStorageDelta({ type: DELETED, payload: { previous: { size: 42 } } })).toEqual({
+      bytes: -42,
+      files: -1,
+    });
+  });
+
+  test("deleted: missing previous reads as 0 bytes, still counts -1 file", () => {
+    expect(fileRefStorageDelta({ type: DELETED, payload: {} })).toEqual({ bytes: 0, files: -1 });
+  });
+
+  test("restored: positive delta from payload.previous.size, symmetric to delete", () => {
+    expect(fileRefStorageDelta({ type: RESTORED, payload: { previous: { size: 42 } } })).toEqual({
+      bytes: 42,
+      files: 1,
+    });
+  });
+
+  test("an unrelated event type returns null", () => {
+    expect(fileRefStorageDelta({ type: "fileRef.renamed", payload: { size: 42 } })).toBeNull();
+  });
+});

package/src/files/index.ts

@@ -26,7 +26,12 @@ export {
   isFileProviderPlugin,
   makeFileProviderResolver,
 } from "./provider-resolver";
-export { filesStorageTrackingFeature, tenantStorageUsageTable } from "./storage-tracking";
+export {
+  fileRefStorageDelta,
+  filesStorageTrackingFeature,
+  tenantStorageUsageTable,
+  transferTenantStorageUsage,
+} from "./storage-tracking";
 export type {
   FileMetadata,
   FileStorageProvider,

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/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";

package/src/pipeline/system-hooks.ts

@@ -542,7 +542,10 @@ export function createJobTriggerEventConsumer(
         tenantId: event.tenantId,
         roles: [],
       };
-      await jobRunner.handleEvent(event.type, event.payload, user);
+      await jobRunner.handleEvent(event.type, event.payload, user, {
+        id: event.id,
+        headers: event.metadata.headers ?? {},
+      });
     },
   };
 }