@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/inbound-provider-imap/imap-client.ts

@@ -0,0 +1,158 @@
+// imapflow-Wiring + pure Helpers des IMAP-Providers.
+// Referenz-Impl: /Users/marc/code/doc-o-mat (HEINZ) — aber inkrementeller
+// UIDVALIDITY:lastUid-Cursor statt '1:*'-Vollscan.
+
+import {
+  InboundAuthError,
+  InboundCursorInvalidError,
+  InboundTransientError,
+  type RawInboundMessage,
+  type SyncCursorPayload,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { legacyDateToInstant } from "@cosmicdrift/kumiko-framework/time";
+import { ImapFlow } from "imapflow";
+import { type AddressObject, type ParsedMail, simpleParser } from "mailparser";
+import { Temporal } from "temporal-polyfill";
+import type { ImapCredentialDocument } from "./credential-document";
+
+export const IMAP_MAILBOX = "INBOX";
+const SNIPPET_MAX = 300;
+
+// =============================================================================
+// Client-Factory + Fehler-Mapping
+// =============================================================================
+
+export function createImapClient(doc: ImapCredentialDocument): ImapFlow {
+  return new ImapFlow({
+    host: doc.host,
+    port: doc.port,
+    secure: doc.secure,
+    auth: doc.password
+      ? { user: doc.user, pass: doc.password }
+      : { user: doc.user, accessToken: doc.accessToken as string },
+    logger: false,
+    emitLogs: false,
+  });
+}
+
+/** Server-Fehler → typisierte Foundation-Fehlerklassen (Plan §2). */
+export function mapImapError(err: unknown, host: string): Error {
+  // imapflow-Fehler tragen die Server-Antwort in responseText, die
+  // message ist nur "Command failed" — beides in den Match einbeziehen;
+  // authenticationFailed ist das verlässliche Flag.
+  const carrier = err as { authenticationFailed?: unknown; responseText?: unknown };
+  const responseText = typeof carrier?.responseText === "string" ? carrier.responseText : "";
+  const msg = `${err instanceof Error ? err.message : String(err)} ${responseText}`.trim();
+  if (
+    carrier?.authenticationFailed === true ||
+    /auth(entication)? failed|invalid credentials|invalid login|LOGIN failed|AUTHENTICATIONFAILED/i.test(
+      msg,
+    )
+  ) {
+    return new InboundAuthError(`IMAP auth failed at ${host}: ${msg}`);
+  }
+  if (/ENOTFOUND|ECONNREFUSED|EAI_AGAIN|ETIMEDOUT|ECONNRESET|socket|closed/i.test(msg)) {
+    return new InboundTransientError(`IMAP ${host} unreachable: ${msg}`);
+  }
+  return new InboundTransientError(`IMAP ${host}: ${msg}`);
+}
+
+// =============================================================================
+// Cursor — { uidValidity: string, lastUid: number }
+// =============================================================================
+
+export type ImapCursor = { readonly uidValidity: string; readonly lastUid: number };
+
+export function parseImapCursor(cursor: SyncCursorPayload | null): ImapCursor | null {
+  if (!cursor) return null;
+  const uidValidity = cursor["uidValidity"];
+  const lastUid = cursor["lastUid"];
+  if (typeof uidValidity !== "string" || typeof lastUid !== "number") return null;
+  return { uidValidity, lastUid };
+}
+
+/** Wirft InboundCursorInvalidError bei UIDVALIDITY-Wechsel — die
+ *  Foundation resettet den Cursor und macht einen Voll-Resync im
+ *  Backfill-Fenster (Dedup fängt Dubletten). */
+export function assertUidValidity(cursor: ImapCursor | null, serverUidValidity: string): void {
+  if (cursor && cursor.uidValidity !== serverUidValidity) {
+    throw new InboundCursorInvalidError(
+      `UIDVALIDITY changed (${cursor.uidValidity} → ${serverUidValidity}) — full resync required`,
+    );
+  }
+}
+
+// =============================================================================
+// Message-Normalisierung → RawInboundMessage
+// =============================================================================
+
+function stripAngles(id: string): string {
+  return id.replace(/^<|>$/g, "").trim();
+}
+
+/** References-Chain normalisieren: mailparser liefert string | string[]
+ *  | undefined; fehlt References, trägt In-Reply-To den Thread-Anker. */
+export function normalizeReferences(parsed: {
+  references?: string | string[];
+  inReplyTo?: string;
+}): string[] {
+  const raw = parsed.references;
+  const list = raw === undefined ? [] : Array.isArray(raw) ? raw : raw.split(/\s+/);
+  const refs = list.map(stripAngles).filter((r) => r.length > 0);
+  if (refs.length === 0 && parsed.inReplyTo) {
+    const inReplyTo = stripAngles(parsed.inReplyTo);
+    if (inReplyTo) return [inReplyTo];
+  }
+  return refs;
+}
+
+function addressList(a: AddressObject | AddressObject[] | undefined): string[] {
+  if (!a) return [];
+  const arr = Array.isArray(a) ? a : [a];
+  return arr.map((x) => x.text).filter((t): t is string => Boolean(t));
+}
+
+/** imapflow liefert internalDate je nach Codepfad als Date ODER string.
+ *  String-Form verwerfen wir bewusst (kein Date-Parsing im Feature-Code,
+ *  no-date-api) — toRawInboundMessage fällt dann auf mailparsers
+ *  Date-Header zurück, der immer als echtes Date kommt. */
+export function coerceDate(d: Date | string | undefined): Date | undefined {
+  return d instanceof Date ? d : undefined;
+}
+
+/** providerMessageId: UID ist nur innerhalb einer UIDVALIDITY eindeutig
+ *  — beides zusammen ist der stabile Idempotency-Anchor. */
+export function buildProviderMessageId(uidValidity: string, uid: number): string {
+  return `${uidValidity}:${uid}`;
+}
+
+export async function toRawInboundMessage(args: {
+  readonly source: Uint8Array;
+  readonly uid: number;
+  readonly uidValidity: string;
+  readonly internalDate: Date | undefined;
+}): Promise<RawInboundMessage> {
+  const parsed: ParsedMail = await simpleParser(Buffer.from(args.source));
+  const messageIdHeader = parsed.messageId ? stripAngles(parsed.messageId) : null;
+  const receivedAt = args.internalDate ?? parsed.date;
+  const text = parsed.text?.trim() ?? "";
+  return {
+    providerMessageId: buildProviderMessageId(args.uidValidity, args.uid),
+    messageIdHeader: messageIdHeader && messageIdHeader.length > 0 ? messageIdHeader : null,
+    providerThreadId: null,
+    references: normalizeReferences(parsed),
+    from: parsed.from?.text ?? "",
+    to: addressList(parsed.to),
+    cc: addressList(parsed.cc),
+    subject: parsed.subject ?? "",
+    snippet: text.slice(0, SNIPPET_MAX),
+    // Lib-Boundary-Bridge (Date von imapflow/mailparser) → Temporal;
+    // fehlt jedes Datum, ist Epoch der ehrliche Marker.
+    receivedAtIso: (receivedAt
+      ? legacyDateToInstant(receivedAt)
+      : Temporal.Instant.fromEpochMilliseconds(0)
+    ).toString(),
+    rawMime: args.source,
+    scope: "inbox",
+  };
+}

package/src/inbound-provider-imap/index.ts

@@ -0,0 +1,17 @@
+// Public API of the inbound-provider-imap bundled-feature.
+
+export {
+  type ImapCredentialDocument,
+  imapCredentialDocumentSchema,
+  type ParseCredentialResult,
+  parseImapCredentialDocument,
+} from "./credential-document";
+export { IMAP_PROVIDER_KEY, inboundProviderImapFeature } from "./feature";
+export {
+  assertUidValidity,
+  buildProviderMessageId,
+  type ImapCursor,
+  mapImapError,
+  normalizeReferences,
+  parseImapCursor,
+} from "./imap-client";

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

@@ -0,0 +1,52 @@
+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",
+        }),
+    };
+  },
+  { hasWatch: Boolean(inMemoryInboundMailPlugin.watch) },
+);

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

@@ -0,0 +1,154 @@
+// kumiko-feature-version: 1
+//
+// inbound-provider-inmemory — scriptbarer In-Memory-Provider für die
+// inbound-mail-foundation Plugin-API. Für Tests, Demos und Sample-Apps:
+// Messages werden per `seedInboundMessage()` eingespeist statt von einem
+// echten Postfach gefetcht; `watch()` pusht geseedete Messages sofort
+// (IDLE-Simulation), `fetch()` liefert sie cursor-basiert nach
+// (Reconciliation-Pfad) — beide Pfade zusammen exercisen exakt die
+// Dedup-Garantie der Foundation.
+//
+// **Pattern-Vorbild:** mail-transport-inmemory (module-level State +
+// Test-Helper-Exports). NICHT für Production.
+
+import type {
+  InboundFetchResult,
+  InboundMailProviderPlugin,
+  MailAccountRecord,
+  RawInboundMessage,
+  SyncCursorPayload,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+const FEATURE_NAME = "inbound-provider-inmemory";
+export const INMEMORY_PROVIDER_KEY = "inmemory";
+
+// =============================================================================
+// Module-level State — pro Account: Message-Log (append-only, wie ein
+// echtes Postfach), aktive Watch-Handler, One-Shot-Fehlerinjektion.
+// =============================================================================
+
+type WatchHandlers = {
+  readonly onMessages: (msgs: readonly RawInboundMessage[]) => Promise<void>;
+  readonly onError: (err: unknown) => void;
+};
+
+type AccountState = {
+  readonly log: RawInboundMessage[];
+  watch: WatchHandlers | null;
+  nextFetchError: unknown;
+  nextVerifyError: unknown;
+};
+
+const accounts = new Map<string, AccountState>();
+
+function stateFor(accountId: string): AccountState {
+  let state = accounts.get(accountId);
+  if (!state) {
+    state = { log: [], watch: null, nextFetchError: null, nextVerifyError: null };
+    accounts.set(accountId, state);
+  }
+  return state;
+}
+
+/** Test-Helper: Message ins Postfach legen. Läuft ein watch, wird sie
+ *  sofort gepusht (IDLE-Simulation); der nächste fetch liefert sie
+ *  cursor-basiert ebenfalls — Dedup der Foundation macht das idempotent. */
+export async function seedInboundMessage(accountId: string, msg: RawInboundMessage): Promise<void> {
+  const state = stateFor(accountId);
+  state.log.push(msg);
+  if (state.watch) await state.watch.onMessages([msg]);
+}
+
+/** Test-Helper: One-Shot-Fehler für den nächsten fetch (z.B.
+ *  InboundAuthError, InboundCursorInvalidError). */
+export function failNextFetchWith(accountId: string, err: unknown): void {
+  stateFor(accountId).nextFetchError = err;
+}
+
+/** Test-Helper: One-Shot-Fehler für das nächste verify. */
+export function failNextVerifyWith(accountId: string, err: unknown): void {
+  stateFor(accountId).nextVerifyError = err;
+}
+
+/** Test-Helper: Tod der Live-Verbindung simulieren (Supervisor muss
+ *  mit Backoff neu starten). */
+export function emitWatchError(accountId: string, err: unknown): void {
+  const state = accounts.get(accountId);
+  if (state?.watch) {
+    const handlers = state.watch;
+    state.watch = null;
+    handlers.onError(err);
+  }
+}
+
+/** Test-Helper: läuft gerade ein watch für den Account? */
+export function isWatching(accountId: string): boolean {
+  return accounts.get(accountId)?.watch != null;
+}
+
+/** Test-Helper: kompletter State-Reset (Test-Isolation — Mock-States
+ *  nie zwischen Tests teilen). */
+export function resetInboundInMemory(): void {
+  accounts.clear();
+}
+
+// =============================================================================
+// Plugin — cursor = { offset: number } über das append-only-Log.
+// =============================================================================
+
+function offsetOf(cursor: SyncCursorPayload | null): number {
+  const raw = cursor?.["offset"];
+  return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : 0;
+}
+
+export const inMemoryInboundMailPlugin: InboundMailProviderPlugin = {
+  verify: async (_ctx, account: MailAccountRecord) => {
+    const state = stateFor(account.id);
+    if (state.nextVerifyError) {
+      const err = state.nextVerifyError;
+      state.nextVerifyError = null;
+      throw err;
+    }
+  },
+  fetch: async (_ctx, account, cursor, opts): Promise<InboundFetchResult> => {
+    const state = stateFor(account.id);
+    if (state.nextFetchError) {
+      const err = state.nextFetchError;
+      state.nextFetchError = null;
+      throw err;
+    }
+    const offset = offsetOf(cursor);
+    const slice = state.log.slice(offset, offset + opts.maxMessages);
+    const nextOffset = offset + slice.length;
+    return {
+      messages: slice,
+      nextCursor: { offset: nextOffset },
+      hasMore: nextOffset < state.log.length,
+    };
+  },
+  watch: async (_ctx, account, handlers) => {
+    const state = stateFor(account.id);
+    state.watch = handlers;
+    return async () => {
+      if (state.watch === handlers) state.watch = null;
+    };
+  },
+};
+
+// =============================================================================
+// Feature-definition
+// =============================================================================
+
+export const inboundProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
+  r.describe(
+    'Registers a scriptable in-process `"inmemory"` provider for `inbound-mail-foundation`. Seed messages with `seedInboundMessage(accountId, msg)` — an active watch pushes them immediately (IDLE simulation) and the cursor-based `fetch` re-delivers them on the reconciliation path, exercising the foundation dedup guarantee. Error injection via `failNextFetchWith`/`failNextVerifyWith`/`emitWatchError`; reset state with `resetInboundInMemory()`. For tests, demos and sample apps — not for production.',
+  );
+  r.uiHints({
+    displayLabel: "Inbound Mail · In-Memory Provider",
+    category: "notifications",
+    recommended: false,
+  });
+  r.requires("inbound-mail-foundation");
+  r.useExtension("inboundMailProvider", INMEMORY_PROVIDER_KEY, inMemoryInboundMailPlugin);
+});

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

@@ -0,0 +1,12 @@
+// Public API of the inbound-provider-inmemory bundled-feature.
+
+export {
+  emitWatchError,
+  failNextFetchWith,
+  failNextVerifyWith,
+  INMEMORY_PROVIDER_KEY,
+  inboundProviderInMemoryFeature,
+  isWatching,
+  resetInboundInMemory,
+  seedInboundMessage,
+} from "./feature";

package/src/jobs/__tests__/entity-ddl.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from "bun:test";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { jobRunEntity } from "../job-run-table";
+
+function pgTypeOf(table: unknown, dbName: string): string | undefined {
+  const cols = (table as { columns?: ReadonlyArray<{ name: string; pgType?: string }> }).columns;
+  return cols?.find((c) => c.name === dbName)?.pgType;
+}
+
+describe("jobRunEntity — DDL (#1205 regression)", () => {
+  test("duration column is integer, not double precision", () => {
+    const table = buildEntityTable("read_job_runs", jobRunEntity);
+    expect(pgTypeOf(table, "duration")).toBe("integer");
+  });
+});

package/src/jobs/__tests__/job-instant.test.ts

@@ -0,0 +1,15 @@
+// kumiko-framework#1525: parseJobInstant is the extracted seam for the five
+// value-position Temporal.Instant.from call sites inside feature.ts's
+// defineApply callbacks (no exported seam there) — must not rely on
+// globalThis.Temporal.
+
+import { describe, expect, test } from "bun:test";
+import { withoutAmbientTemporal } from "@cosmicdrift/kumiko-framework/testing";
+import { parseJobInstant } from "../job-instant";
+
+describe("parseJobInstant — kumiko-framework#1525: no ambient Temporal global", () => {
+  test("parses an ISO instant without relying on globalThis.Temporal", async () => {
+    const instant = await withoutAmbientTemporal(() => parseJobInstant("2026-01-01T00:00:00Z"));
+    expect(instant.toString()).toBe("2026-01-01T00:00:00Z");
+  });
+});

package/src/jobs/__tests__/job-system-user.integration.test.ts

@@ -1,10 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import {
-  createEncryptionProvider,
-  createTenantDb,
-  type DbConnection,
-} from "@cosmicdrift/kumiko-framework/db";
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   createRegistry,
@@ -26,7 +22,7 @@ import {
   TestUsers,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { bridgeStub, sleep } from "@cosmicdrift/kumiko-framework/testing";
+import { bridgeStub, createTestEnvelopeCipher, sleep } from "@cosmicdrift/kumiko-framework/testing";
 import { ConfigHandlers } from "../../config/constants";
 import { createConfigAccessor, createConfigFeature } from "../../config/feature";
 import { type ConfigResolver, createConfigResolver } from "../../config/resolver";
@@ -107,8 +103,8 @@ beforeAll(async () => {
   await createEventsTable(db);
   await createArchivedStreamsTable(db);
 
-  const encryption = createEncryptionProvider(testEncryptionKey);
-  resolver = createConfigResolver({ encryption });
+  const encryption = createTestEnvelopeCipher(testEncryptionKey);
+  resolver = createConfigResolver({ cipher: encryption });
 
   registry = createRegistry([configFeature, billingFeature]);
 

package/src/jobs/__tests__/jobs-events.integration.test.ts

@@ -32,12 +32,13 @@ import { jobRunLogsTable, jobRunsTable } from "../job-run-table";
 
 let testDb: TestDb;
 let testRedis: TestRedis;
+let registry: ReturnType<typeof createRegistry>;
 let logger: ReturnType<typeof createJobRunLogger>;
 
 beforeAll(async () => {
   testDb = await createTestDb();
   testRedis = await createTestRedis();
-  const registry = createRegistry([createJobsFeature()]);
+  registry = createRegistry([createJobsFeature()]);
   await unsafePushTables(testDb.db, { jobRunsTable, jobRunLogsTable });
   await createEventsTable(testDb.db);
   logger = createJobRunLogger({ db: testDb.db, registry });
@@ -127,4 +128,39 @@ describe("jobRun event shapes", () => {
     const ids = new Set(events.map((e) => e.aggregateId));
     expect(ids.size).toBe(1);
   });
+
+  test("complete/fail without a prior start skips — does not forge a jobRun stream", async () => {
+    // State-loss path: worker restart with empty cache AND no projection row for
+    // this bullJobId. Dropping the terminal event is intentional — forging an
+    // aggregate from scratch would invent a run that never started.
+    await logger.onJobComplete?.("example:job:orphan", "bull-orphan-complete", 50, []);
+    await logger.onJobFailed?.("example:job:orphan", "bull-orphan-failed", "boom", []);
+
+    const completed = await selectMany(testDb.db, eventsTable, { type: JOB_RUN_COMPLETED_EVENT });
+    const failed = await selectMany(testDb.db, eventsTable, { type: JOB_RUN_FAILED_EVENT });
+    const runs = await selectMany(testDb.db, jobRunsTable);
+
+    expect(completed).toHaveLength(0);
+    expect(failed).toHaveLength(0);
+    expect(runs).toHaveLength(0);
+  });
+
+  test("complete after cache loss recovers runId from the projection (same stream)", async () => {
+    // Simulates worker process restart: in-memory bullJobId→runId cache is gone,
+    // but the run-started projection row still has bull_job_id. A fresh logger
+    // must DB-lookup and append onto the original aggregate — not mint a second.
+    await logger.onJobStart?.("example:job:restart", "bull-restart-1", {});
+    const started = await selectMany(testDb.db, eventsTable, { type: JOB_RUN_STARTED_EVENT });
+    expect(started).toHaveLength(1);
+    const originalAggregateId = started[0]?.aggregateId;
+    expect(originalAggregateId).toBeTruthy();
+
+    const coldLogger = createJobRunLogger({ db: testDb.db, registry });
+    await coldLogger.onJobComplete?.("example:job:restart", "bull-restart-1", 42, []);
+
+    const all = await selectMany(testDb.db, eventsTable, { aggregateType: "jobRun" });
+    expect(all).toHaveLength(2);
+    expect(new Set(all.map((e) => e.aggregateId))).toEqual(new Set([originalAggregateId]));
+    expect(all.some((e) => e.type === JOB_RUN_COMPLETED_EVENT)).toBe(true);
+  });
 });

package/src/jobs/__tests__/jobs-pii-kms.integration.test.ts

@@ -0,0 +1,120 @@
+// Event-PII on the jobs run-logger (#799): runStarted.payload can carry
+// arbitrary user data and is written via LOW-LEVEL append() (not
+// ctx.appendEvent) — exactly the path the event-PII catalog must cover.
+// With a KMS active the stored event AND the projected read-row carry
+// ciphertext under the triggering user's DEK; erasing that key makes the
+// payload unreadable ([[erased]]) without touching the append-only stream.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { fetchOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  configurePiiSubjectKms,
+  decryptPiiFieldValues,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestDb,
+  createTestRedis,
+  type TestDb,
+  type TestRedis,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { createJobsFeature } from "../feature";
+import { createJobRunLogger, JOB_RUN_STARTED_EVENT } from "../job-run-logger";
+import { jobRunLogsTable, jobRunsTable } from "../job-run-table";
+
+let testDb: TestDb;
+let testRedis: TestRedis;
+let logger: ReturnType<typeof createJobRunLogger>;
+let kms: InMemoryKmsAdapter;
+
+const USER_ID = "u-pii-9";
+const SECRET_PAYLOAD = JSON.stringify({ iban: "DE89370400440532013000" });
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+  // createRegistry publishes the event-PII catalog as a module singleton —
+  // the logger's low-level append() picks it up without further wiring.
+  const registry = createRegistry([createJobsFeature()]);
+  await unsafePushTables(testDb.db, { jobRunsTable, jobRunLogsTable });
+  await createEventsTable(testDb.db);
+  logger = createJobRunLogger({ db: testDb.db, registry });
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+beforeEach(async () => {
+  await resetTestTables(testDb.db, [eventsTable, jobRunsTable, jobRunLogsTable]);
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+describe("jobs run-started payload under KMS", () => {
+  test("stored event carries ciphertext payload, plaintext triggeredById", async () => {
+    await logger.onJobStart?.("app:job:export", "bull-1", {
+      triggeredById: USER_ID,
+      payload: SECRET_PAYLOAD,
+      attempt: 1,
+    });
+
+    const events = await selectMany(testDb.db, eventsTable, { type: JOB_RUN_STARTED_EVENT });
+    expect(events.length).toBe(1);
+    const payload = events[0]?.payload as Record<string, unknown>;
+    expect(isPiiCiphertext(payload["payload"])).toBe(true);
+    expect(String(payload["payload"])).toContain(`user:${USER_ID}`);
+    expect(payload["triggeredById"]).toBe(USER_ID);
+
+    const back = await decryptPiiFieldValues(payload, ["payload"], kms, { requestId: "t" });
+    expect(back["payload"]).toBe(SECRET_PAYLOAD);
+  });
+
+  test("projected read-row carries the same ciphertext; erase → [[erased]]", async () => {
+    await logger.onJobStart?.("app:job:export", "bull-2", {
+      triggeredById: USER_ID,
+      payload: SECRET_PAYLOAD,
+    });
+
+    const row = await fetchOne(testDb.db, jobRunsTable, { bullJobId: "bull-2" });
+    expect(isPiiCiphertext(row?.["payload"])).toBe(true);
+
+    await kms.eraseKey({ kind: "user", userId: USER_ID });
+    const after = await decryptPiiFieldValues({ payload: row?.["payload"] }, ["payload"], kms, {
+      requestId: "t",
+    });
+    expect(after["payload"]).toBe(PII_ERASED_SENTINEL);
+  });
+
+  test("system run (no triggeredById) stays plaintext — no subject to shred", async () => {
+    await logger.onJobStart?.("app:job:cron-sweep", "bull-3", {
+      payload: JSON.stringify({ scope: "all" }),
+    });
+
+    const row = await fetchOne(testDb.db, jobRunsTable, { bullJobId: "bull-3" });
+    expect(row?.["payload"]).toBe(JSON.stringify({ scope: "all" }));
+  });
+
+  test("without a KMS the payload stays plaintext (rollout mode)", async () => {
+    resetPiiSubjectKmsForTests();
+    await logger.onJobStart?.("app:job:export", "bull-4", {
+      triggeredById: USER_ID,
+      payload: SECRET_PAYLOAD,
+    });
+
+    const row = await fetchOne(testDb.db, jobRunsTable, { bullJobId: "bull-4" });
+    expect(row?.["payload"]).toBe(SECRET_PAYLOAD);
+  });
+});

package/src/jobs/__tests__/jobs-screens.boot.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { rolesOf } from "@cosmicdrift/kumiko-framework/testing";
+import { createConfigFeature } from "../../config/feature";
+import { JOB_RUN_DETAIL_SCREEN_ID, JOB_RUNS_SCREEN_ID } from "../constants";
+import { createJobsFeature } from "../feature";
+
+const SYSTEM_ADMIN_ROLES = ["SystemAdmin"] as const;
+
+describe("jobs screens + handler access alignment", () => {
+  const features = [createConfigFeature(), createJobsFeature()];
+
+  test("boot-validates with job-runs screens registered", () => {
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("job-runs screens are SystemAdmin-gated", () => {
+    const jobs = createJobsFeature();
+    for (const id of [JOB_RUNS_SCREEN_ID, JOB_RUN_DETAIL_SCREEN_ID] as const) {
+      const screen = jobs.screens[id];
+      expect(screen?.type).toBe("custom");
+      if (screen && "access" in screen && screen.access && "roles" in screen.access) {
+        expect(screen.access.roles).toEqual(SYSTEM_ADMIN_ROLES);
+      }
+    }
+  });
+
+  test("jobs queries + operator writes share SystemAdmin access", () => {
+    const jobs = createJobsFeature();
+    const roles = [...SYSTEM_ADMIN_ROLES];
+    expect(rolesOf(jobs.queryHandlers["list"]?.access)).toEqual(roles);
+    expect(rolesOf(jobs.queryHandlers["details"]?.access)).toEqual(roles);
+    expect(rolesOf(jobs.writeHandlers["trigger"]?.access)).toEqual(roles);
+    expect(rolesOf(jobs.writeHandlers["retry"]?.access)).toEqual(roles);
+  });
+});