@cosmicdrift/kumiko-bundled-features 0.158.2 → 0.160.0

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -26,6 +26,7 @@ import {
   encryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "temporal-polyfill";
 import { z } from "zod";
 import { inboundMessageAggregateId, mailThreadAggregateId } from "../aggregate-id";
@@ -99,6 +100,7 @@ function buildThreadKey(p: IngestMessagePayload, effectiveMessageIdHeader: strin
   return `mid:${effectiveMessageIdHeader}`.slice(0, 500);
 }
 
+const THREAD_ROLLUP_MAX_ATTEMPTS = 5;
 export const ingestMessageHandler: WriteHandlerDef = {
   name: "ingest-message",
   schema: ingestMessageSchema,
@@ -221,46 +223,33 @@ export const ingestMessageHandler: WriteHandlerDef = {
     }
 
     // ---------------------------------------------------------------
-    // 5. Thread-Rollup. Der Handler berechnet den NEUEN Snapshot
-    //    (count via Live-COUNT, max(lastMessageAt)) — die apply ist ein
-    //    dummer UPSERT und bleibt replay-idempotent. lastMessageAtIso ist
-    //    kein PII (Zeitpunkt), damit plaintext-vergleichbar; subject
-    //    wird frisch encrypted (jede Thread-Version trägt das Subject
-    //    der jüngsten Mail).
+    // 5. Thread-Rollup. New snapshot (live COUNT + max(lastMessageAt)) via
+    //    ctx.tryAppendEvent in a bounded retry loop — the apply stays a
+    //    dumb, replay-idempotent UPSERT. lastMessageAtIso is not PII (a
+    //    timestamp), so it stays plaintext-comparable; subject is
+    //    encrypted once up front (constant across retries, doesn't
+    //    depend on the thread's prior state).
     //
-    //    messageCount kommt bewusst NICHT aus einem frueher gelesenen
-    //    threadEvents-Snapshot (previousCount+1): getStreamVersion in
-    //    unsafeAppendEvent liest die Stream-Version FRISCH zum
-    //    Append-Zeitpunkt, unabhaengig vom Read hier — zwei parallele
-    //    ingests auf denselben Thread (Watch-Push + Poll-Reconciliation)
-    //    koennten beide denselben previousCount sehen und der Append der
-    //    zweiten TX wuerde trotzdem gelingen (kein VersionConflictError,
-    //    da der Version-Check nur die Stream-Version prueft), sodass
-    //    previousCount+1 dauerhaft nach unten drieftet.
+    //    messageCount deliberately does NOT come from a previously loaded
+    //    threadEvents snapshot (previousCount+1): two concurrent ingests
+    //    on the same thread (Watch-Push vs. Poll-Reconciliation overlap,
+    //    or two different messages of the same thread arriving at once)
+    //    can both read the same stream version before either commits.
+    //    tryAppendEvent's fresh version-read at append time then makes
+    //    the loser's append fail with a VersionConflictError instead of
+    //    silently succeeding — so we retry: reload the thread stream,
+    //    recompute the live row-count and lastMessageAt, and append
+    //    again. Unlike step 4, a lost race here must NOT be treated as a
+    //    no-op duplicate — skipping would leave this message's
+    //    contribution to messageCount/lastMessageAt out of the thread
+    //    forever. Exhausting all attempts throws, rolling back the whole
+    //    TX (including the step-4 message append) for a clean re-ingest
+    //    on the next poll — never return success with a stale snapshot.
     //
-    //    Ein COUNT gegen read_inbound_messages SCHLIESST das Race-Fenster
-    //    NICHT (COUNT und Append sind weiterhin zwei getrennte Statements —
-    //    zwischen COUNT und Append kann die andere TX committen und derselbe
-    //    Drift theoretisch weiterhin auftreten). Was der COUNT aendert: er
-    //    macht den Fehler SELBSTKORRIGIEREND statt kumulativ — jeder
-    //    nachfolgende ingest liest den echten Row-Count neu, statt einen
-    //    frueher falsch geschriebenen previousCount fortzuschreiben. Eine
-    //    echte Race-freie Loesung braucht ein atomares Read+Append (z.B.
-    //    SELECT ... FOR UPDATE oder eine Advisory-Lock auf threadAggId) —
-    //    das ist bewusst nicht Teil dieses Fixes (siehe PR-Beschreibung).
+    //    A true race-free read+append (e.g. SELECT ... FOR UPDATE or an
+    //    advisory lock on threadAggId) is deliberately not part of this
+    //    fix — two writers (watch + poll) make bounded retry sufficient.
     // ---------------------------------------------------------------
-    const threadEvents = await ctx.loadAggregate(threadAggId);
-    const lastThreadEvent = threadEvents[threadEvents.length - 1];
-    // @cast-boundary engine-payload — eigene events, shape via defineEvent
-    const previousThread = lastThreadEvent?.payload as MailThreadEventPayload | undefined;
-    const previousLastAt = previousThread?.lastMessageAtIso ?? "";
-    const newLastAt =
-      payload.receivedAtIso > previousLastAt ? payload.receivedAtIso : previousLastAt;
-    const messageCount = await countWhere(ctx.db.raw, inboundMessagesProjectionTable, {
-      tenantId,
-      threadKey,
-    });
-
     const threadPlainPii = { tenantId, subject: payload.subject };
     const encryptedThreadFields = piiKms
       ? await encryptPiiFieldValues(
@@ -275,19 +264,40 @@ export const ingestMessageHandler: WriteHandlerDef = {
         )
       : threadPlainPii;
 
-    const threadEventPayload: MailThreadEventPayload = {
-      threadKey,
-      subject: encryptedThreadFields["subject"] as string,
-      lastMessageAtIso: newLastAt,
-      messageCount,
-    };
-    await ctx.unsafeAppendEvent({
-      aggregateId: threadAggId,
-      aggregateType: MAIL_THREAD_AGGREGATE_TYPE,
-      type: MAIL_THREAD_UPDATED_EVENT_QN,
-      payload: threadEventPayload,
-      headers: messageHeaders,
-    });
+    let threadAppendOk = false;
+    for (let attempt = 1; attempt <= THREAD_ROLLUP_MAX_ATTEMPTS && !threadAppendOk; attempt++) {
+      const threadEvents = await ctx.loadAggregate(threadAggId);
+      const lastThreadEvent = threadEvents[threadEvents.length - 1];
+      // @cast-boundary engine-payload — eigene events, shape via defineEvent
+      const previousThread = lastThreadEvent?.payload as MailThreadEventPayload | undefined;
+      const previousLastAt = previousThread?.lastMessageAtIso ?? "";
+      const newLastAt =
+        payload.receivedAtIso > previousLastAt ? payload.receivedAtIso : previousLastAt;
+      const messageCount = await countWhere(ctx.db.raw, inboundMessagesProjectionTable, {
+        tenantId,
+        threadKey,
+      });
+
+      const threadEventPayload: MailThreadEventPayload = {
+        threadKey,
+        subject: encryptedThreadFields["subject"] as string,
+        lastMessageAtIso: newLastAt,
+        messageCount,
+      };
+      const threadAppend = await ctx.tryAppendEvent({
+        aggregateId: threadAggId,
+        aggregateType: MAIL_THREAD_AGGREGATE_TYPE,
+        type: MAIL_THREAD_UPDATED_EVENT_QN,
+        payload: threadEventPayload,
+        headers: messageHeaders,
+      });
+      threadAppendOk = threadAppend.ok;
+    }
+    if (!threadAppendOk) {
+      throw new InternalError({
+        message: `ingest-message: thread-rollup append for "${threadAggId}" lost the version-conflict race ${THREAD_ROLLUP_MAX_ATTEMPTS} times in a row — aborting for a clean re-ingest instead of persisting a stale messageCount.`,
+      });
+    }
 
     // ---------------------------------------------------------------
     // 6. Dedup-Anchor. Läuft in derselben TX wie die appends — stirbt

package/src/inbound-provider-imap/__tests__/imap-live.integration.test.ts

@@ -25,6 +25,7 @@ import {
   type MailAccountRecord,
   type RawInboundMessage,
 } from "../../inbound-mail-foundation";
+import { describeInboundMailProviderContract } from "../../inbound-mail-foundation/__tests__/inbound-mail-provider-contract";
 import { imapInboundMailPlugin } from "../feature";
 
 const HOST = process.env["IMAP_LIVE_HOST"] ?? "127.0.0.1";
@@ -192,3 +193,14 @@ describe("imap-live — echter Server (greenmail)", () => {
     20_000,
   );
 });
+
+describeInboundMailProviderContract(
+  "imap (greenmail)",
+  () => ({
+    plugin: imapInboundMailPlugin,
+    ctx: ctxWithCredentials(credentialDoc(PASSWORD)),
+    account,
+    seed: (subject) => sendTestMail(subject, "contract seed"),
+  }),
+  { skip: !available },
+);

package/src/inbound-provider-imap/__tests__/plugin-mocked.test.ts

@@ -0,0 +1,331 @@
+// Always-on unit coverage for imapInboundMailPlugin.verify/fetch/watch.
+// Greenmail suites skip in CI when the container is down — this file mocks
+// imapflow so the plugin body stays on the coverage badge without Docker.
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { EventEmitter } from "node:events";
+import { createSecret } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  type InboundMailContext,
+  isInboundAuthError,
+  isInboundCursorInvalidError,
+  isInboundTransientError,
+  type MailAccountRecord,
+  type RawInboundMessage,
+} from "../../inbound-mail-foundation";
+
+type FakeMsg = {
+  readonly uid: number;
+  readonly source: Buffer;
+  readonly internalDate: Date;
+};
+
+type FakeState = {
+  connectError?: Error;
+  authFailed?: boolean;
+  uidValidity: string;
+  uidNext: number;
+  messages: FakeMsg[];
+  /** When set, search() returns this list instead of all message uids. */
+  searchUids?: number[];
+};
+
+let state: FakeState;
+let lastIdleClient: FakeImapFlow | undefined;
+
+class FakeImapFlow extends EventEmitter {
+  mailbox: { uidValidity: bigint; uidNext: number } | false = false;
+  private idleReject: ((err: Error) => void) | undefined;
+
+  constructor(_opts: unknown) {
+    super();
+    lastIdleClient = this;
+  }
+
+  async connect(): Promise<void> {
+    if (state.connectError) {
+      const err = state.connectError as Error & { authenticationFailed?: boolean };
+      if (state.authFailed) err.authenticationFailed = true;
+      throw err;
+    }
+  }
+
+  async logout(): Promise<void> {
+    this.idleReject?.(new Error("connection closed"));
+    this.idleReject = undefined;
+  }
+
+  async getMailboxLock(_box: string): Promise<{ release: () => void }> {
+    this.mailbox = {
+      uidValidity: BigInt(state.uidValidity),
+      uidNext: state.uidNext,
+    };
+    return { release: () => {} };
+  }
+
+  async mailboxOpen(_box: string): Promise<{ uidValidity: bigint; uidNext: number }> {
+    this.mailbox = {
+      uidValidity: BigInt(state.uidValidity),
+      uidNext: state.uidNext,
+    };
+    return this.mailbox;
+  }
+
+  async search(_query: unknown, _opts?: unknown): Promise<number[]> {
+    return state.searchUids ?? state.messages.map((m) => m.uid);
+  }
+
+  async *fetch(
+    range: string,
+    _opts?: unknown,
+    _uidOpts?: unknown,
+  ): AsyncGenerator<{
+    uid: number;
+    source: Buffer;
+    internalDate: Date;
+  }> {
+    // Real imapflow is called with either "N,M,…" (explicit uid list) or "N:*".
+    const wanted = new Set<number>();
+    if (range.includes("*")) {
+      const start = Number(range.split(":")[0]);
+      for (const m of state.messages) {
+        if (m.uid >= start) wanted.add(m.uid);
+      }
+    } else {
+      for (const part of range.split(",")) {
+        const n = Number(part.trim());
+        if (Number.isFinite(n)) wanted.add(n);
+      }
+    }
+    for (const m of state.messages) {
+      if (wanted.size > 0 && !wanted.has(m.uid)) continue;
+      yield { uid: m.uid, source: m.source, internalDate: m.internalDate };
+    }
+  }
+
+  async idle(): Promise<void> {
+    await new Promise<void>((_resolve, reject) => {
+      this.idleReject = reject;
+    });
+  }
+}
+
+mock.module("imapflow", () => ({ ImapFlow: FakeImapFlow }));
+
+const { imapInboundMailPlugin } = await import("../feature");
+
+function mime(subject: string, text: string): Buffer {
+  return Buffer.from(
+    [
+      "From: Sender <sender@example.com>",
+      "To: inbox@example.com",
+      `Subject: ${subject}`,
+      "Message-ID: <msg-1@example.com>",
+      "Date: Mon, 01 Jan 2024 12:00:00 +0000",
+      "MIME-Version: 1.0",
+      "Content-Type: text/plain; charset=utf-8",
+      "",
+      text,
+    ].join("\r\n"),
+  );
+}
+
+const account: MailAccountRecord = {
+  id: "00000000-0000-4000-8000-000000001a01",
+  tenantId: "00000000-0000-4000-8000-000000004242",
+  provider: "imap",
+  authMethod: "password",
+  ownerUserId: null,
+  address: "inbox@example.com",
+  displayName: "Mock",
+  status: "active",
+  watchState: "idle",
+};
+
+function ctxWithDoc(doc: string | null): InboundMailContext {
+  return {
+    _userId: "imap-plugin-mocked",
+    secrets: {
+      get: async () => (doc === null ? null : createSecret(doc)),
+      has: async () => doc !== null,
+      set: async () => {},
+      delete: async () => {},
+    } as unknown as import("@cosmicdrift/kumiko-framework/secrets").SecretsContext, // @cast-boundary test-double
+  };
+}
+
+const goodDoc = JSON.stringify({
+  host: "imap.example.com",
+  port: 993,
+  secure: true,
+  user: "u@example.com",
+  password: "pw",
+});
+
+beforeEach(() => {
+  lastIdleClient = undefined;
+  state = {
+    uidValidity: "17",
+    uidNext: 3,
+    messages: [
+      {
+        uid: 1,
+        source: mime("one", "hello one"),
+        internalDate: new Date("2024-01-01T12:00:00Z"),
+      },
+      {
+        uid: 2,
+        source: mime("two", "hello two"),
+        internalDate: new Date("2024-01-02T12:00:00Z"),
+      },
+    ],
+  };
+});
+
+describe("imapInboundMailPlugin — mocked imapflow", () => {
+  test("verify: connect+logout happy path", async () => {
+    await expect(
+      imapInboundMailPlugin.verify(ctxWithDoc(goodDoc), account),
+    ).resolves.toBeUndefined();
+  });
+
+  test("verify: auth failure → InboundAuthError", async () => {
+    state.connectError = new Error("Authentication failed");
+    state.authFailed = true;
+    try {
+      await imapInboundMailPlugin.verify(ctxWithDoc(goodDoc), account);
+      expect.unreachable("expected verify to throw");
+    } catch (e) {
+      expect(isInboundAuthError(e)).toBe(true);
+    }
+  });
+
+  test("verify: missing credential secret → InboundAuthError", async () => {
+    try {
+      await imapInboundMailPlugin.verify(ctxWithDoc(null), account);
+      expect.unreachable("expected verify to throw");
+    } catch (e) {
+      expect(isInboundAuthError(e)).toBe(true);
+    }
+  });
+
+  test("verify: malformed credential JSON → InboundAuthError", async () => {
+    try {
+      await imapInboundMailPlugin.verify(ctxWithDoc("not-json"), account);
+      expect.unreachable("expected verify to throw");
+    } catch (e) {
+      expect(isInboundAuthError(e)).toBe(true);
+    }
+  });
+
+  test("fetch: backfill (null cursor) returns messages + nextCursor", async () => {
+    const result = await imapInboundMailPlugin.fetch(ctxWithDoc(goodDoc), account, null, {
+      backfillWindowDays: 7,
+      maxMessages: 50,
+    });
+    expect(result.messages).toHaveLength(2);
+    expect(result.messages[0]?.subject).toBe("one");
+    expect(result.nextCursor).toEqual({ uidValidity: "17", lastUid: 2 });
+    expect(result.hasMore).toBe(false);
+  });
+
+  test("fetch: incremental cursor filters uid <= lastUid + hasMore via maxMessages", async () => {
+    state.searchUids = [1, 2, 3, 4];
+    state.messages = [
+      {
+        uid: 2,
+        source: mime("two", "x"),
+        internalDate: new Date("2024-01-02T12:00:00Z"),
+      },
+      {
+        uid: 3,
+        source: mime("three", "y"),
+        internalDate: new Date("2024-01-03T12:00:00Z"),
+      },
+      {
+        uid: 4,
+        source: mime("four", "z"),
+        internalDate: new Date("2024-01-04T12:00:00Z"),
+      },
+    ];
+    const result = await imapInboundMailPlugin.fetch(
+      ctxWithDoc(goodDoc),
+      account,
+      { uidValidity: "17", lastUid: 1 },
+      { backfillWindowDays: 7, maxMessages: 2 },
+    );
+    // search returns 2,3,4 (> lastUid=1); maxMessages=2 → hasMore
+    expect(result.messages.length).toBeLessThanOrEqual(2);
+    expect(result.hasMore).toBe(true);
+    expect(result.nextCursor["uidValidity"]).toBe("17");
+  });
+
+  test("fetch: UIDVALIDITY change → InboundCursorInvalidError", async () => {
+    try {
+      await imapInboundMailPlugin.fetch(
+        ctxWithDoc(goodDoc),
+        account,
+        { uidValidity: "16", lastUid: 1 },
+        { backfillWindowDays: 7, maxMessages: 50 },
+      );
+      expect.unreachable("expected fetch to throw");
+    } catch (e) {
+      expect(isInboundCursorInvalidError(e)).toBe(true);
+    }
+  });
+
+  test("fetch: network error → InboundTransientError", async () => {
+    state.connectError = new Error("ECONNREFUSED");
+    try {
+      await imapInboundMailPlugin.fetch(ctxWithDoc(goodDoc), account, null, {
+        backfillWindowDays: 7,
+        maxMessages: 50,
+      });
+      expect.unreachable("expected fetch to throw");
+    } catch (e) {
+      expect(isInboundTransientError(e)).toBe(true);
+    }
+  });
+
+  test("watch: exists → onMessages, stop() tears down", async () => {
+    expect(imapInboundMailPlugin.watch).toBeDefined();
+    const received: RawInboundMessage[][] = [];
+    const stop = await imapInboundMailPlugin.watch!(ctxWithDoc(goodDoc), account, {
+      onMessages: async (msgs) => {
+        received.push([...msgs]);
+      },
+      onError: () => {},
+    });
+
+    // New mail above uidNext-1 (uidNext=3 → nextUid starts at 3)
+    state.messages = [
+      {
+        uid: 3,
+        source: mime("pushed", "idle body"),
+        internalDate: new Date("2024-01-05T12:00:00Z"),
+      },
+    ];
+    lastIdleClient?.emit("exists");
+
+    await Bun.sleep(50);
+    expect(received.some((batch) => batch.some((m) => m.subject === "pushed"))).toBe(true);
+
+    await stop();
+  });
+
+  test("watch: client error → onError once", async () => {
+    let errors = 0;
+    const stop = await imapInboundMailPlugin.watch!(ctxWithDoc(goodDoc), account, {
+      onMessages: async () => {},
+      onError: () => {
+        errors += 1;
+      },
+    });
+    lastIdleClient?.emit("error", new Error("socket hang up"));
+    await Bun.sleep(20);
+    lastIdleClient?.emit("error", new Error("second"));
+    await Bun.sleep(20);
+    expect(errors).toBe(1);
+    await stop().catch(() => {});
+  });
+});

package/src/inbound-provider-inmemory/__tests__/feature.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import { describeInboundMailProviderContract } from "../../inbound-mail-foundation/__tests__/inbound-mail-provider-contract";
+import {
+  inboundProviderInMemoryFeature,
+  inMemoryInboundMailPlugin,
+  seedInboundMessage,
+} from "../feature";
+
+describe("inboundProviderInMemoryFeature — shape", () => {
+  test("has the expected name + requirement", () => {
+    expect(inboundProviderInMemoryFeature.name).toBe("inbound-provider-inmemory");
+    expect(inboundProviderInMemoryFeature.requires).toContain("inbound-mail-foundation");
+  });
+});
+
+describeInboundMailProviderContract("inmemory", () => {
+  const accountId = crypto.randomUUID();
+  return {
+    plugin: inMemoryInboundMailPlugin,
+    ctx: {},
+    account: {
+      id: accountId,
+      tenantId: "00000000-0000-4000-8000-000000004242",
+      provider: "inmemory",
+      authMethod: "password",
+      ownerUserId: null,
+      address: "contract@example.com",
+      displayName: "Contract-Test",
+      status: "active",
+      watchState: "idle",
+    },
+    seed: (subject) =>
+      seedInboundMessage(accountId, {
+        providerMessageId: crypto.randomUUID(),
+        messageIdHeader: null,
+        providerThreadId: null,
+        references: [],
+        from: "sender@example.com",
+        to: ["contract@example.com"],
+        cc: [],
+        subject,
+        snippet: subject,
+        receivedAtIso: "2026-07-01T10:00:00Z",
+        rawMime: null,
+        scope: "inbox",
+      }),
+  };
+});

package/src/inbound-provider-inmemory/feature.ts

@@ -102,7 +102,7 @@ function offsetOf(cursor: SyncCursorPayload | null): number {
   return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : 0;
 }
 
-const plugin: InboundMailProviderPlugin = {
+export const inMemoryInboundMailPlugin: InboundMailProviderPlugin = {
   verify: async (_ctx, account: MailAccountRecord) => {
     const state = stateFor(account.id);
     if (state.nextVerifyError) {
@@ -150,5 +150,5 @@ export const inboundProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) =>
     recommended: false,
   });
   r.requires("inbound-mail-foundation");
-  r.useExtension("inboundMailProvider", INMEMORY_PROVIDER_KEY, plugin);
+  r.useExtension("inboundMailProvider", INMEMORY_PROVIDER_KEY, inMemoryInboundMailPlugin);
 });

package/src/jobs/__tests__/reindex-entity-job.integration.test.ts

@@ -12,7 +12,12 @@ import {
   createEventStoreExecutor,
   createTenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type JobContext,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   setupTestStack,
@@ -20,6 +25,7 @@ import {
   TestUsers,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing";
 import { createJobsFeature } from "../feature";
 import { reindexEntityJob } from "../handlers/reindex-entity.job";
 
@@ -43,6 +49,16 @@ const widgetFeature = defineFeature("reindex-job-test", (r) => {
 let stack: TestStack;
 const admin = TestUsers.admin;
 
+const noopLogger: JobContext["log"] = {
+  info() {},
+  warn() {},
+  error() {},
+  debug() {},
+  child() {
+    return noopLogger;
+  },
+};
+
 beforeAll(async () => {
   stack = await setupTestStack({ features: [widgetFeature, createJobsFeature()] });
   await unsafeCreateEntityTable(stack.db, widgetEntity);
@@ -87,6 +103,42 @@ describe("reindexEntityJob", () => {
     expect(postResults.some((r) => r.entityId === created.data.id)).toBe(true);
   });
 
+  test("the registered job handler resolves a systemUser-scoped fan-out run and actually indexes (not reindexEntityJob called directly)", async () => {
+    // The two direct-call tests above bypass jobRunner.dispatch()'s
+    // ctx-resolution/guard chain entirely — a bug there (e.g. a systemUser
+    // that isn't wired through) would be invisible to them. Invoke the
+    // ACTUAL registered handler, same as retention-cleanup's handler test.
+    const executor = createEventStoreExecutor(widgetTable, widgetEntity, { entityName: "widget" });
+    const tenantDb = createTenantDb(stack.db, admin.tenantId, "system");
+    const created = await executor.create({ name: "Registry-Resolved Widget" }, admin, tenantDb);
+    if (!created.isSuccess) throw new Error("seed failed");
+
+    const preResults = await stack.search.search(admin.tenantId, "registry-resolved", {
+      filterType: "widget",
+    });
+    expect(preResults).toHaveLength(0);
+
+    const job = stack.registry.getJob(REINDEX_ENTITY_JOB);
+    expect(job).toBeDefined();
+    if (!job) return;
+
+    const ctx: JobContext = {
+      db: stack.db,
+      registry: stack.registry,
+      searchAdapter: stack.search,
+      systemUser: admin,
+      log: noopLogger,
+      triggeredBy: null,
+      ...bridgeStub(),
+    };
+    await job.handler({ entity: "widget" }, ctx);
+
+    const postResults = await stack.search.search(admin.tenantId, "registry-resolved", {
+      filterType: "widget",
+    });
+    expect(postResults.some((r) => r.entityId === created.data.id)).toBe(true);
+  });
+
   test("skips silently when no tenant is resolvable (fan-out misfire)", async () => {
     await expect(
       reindexEntityJob(

package/src/jobs/handlers/detail.query.ts

@@ -21,7 +21,7 @@ export const detailQuery = defineQueryHandler({
 
     // payload is stored encrypted under the triggering user's DEK (#799).
     if (typeof row["payload"] === "string") {
-      row["payload"] = await decryptStoredPii(row["payload"], "job-run-detail");
+      row["payload"] = await decryptStoredPii(row["payload"], "payload", "job-run-detail");
     }
 
     const logs = await selectMany(

package/src/jobs/handlers/list.query.ts

@@ -6,7 +6,7 @@ import { jobRunsTable } from "../job-run-table";
 
 async function decryptRunPayload<T extends Record<string, unknown>>(row: T): Promise<T> {
   if (typeof row["payload"] !== "string") return row;
-  return { ...row, payload: await decryptStoredPii(row["payload"], "job-runs") };
+  return { ...row, payload: await decryptStoredPii(row["payload"], "payload", "job-runs") };
 }
 
 export const listQuery = defineQueryHandler({