@cosmicdrift/kumiko-framework 0.326.1 → 0.328.0

package/src/bun-db/__tests__/closed-connection-retry.integration.test.ts

@@ -6,7 +6,11 @@ import postgres from "postgres";
 import { constraintOf, extractPgError, isUniqueViolation } from "../../db/pg-error";
 import { testDatabaseUrl } from "../../testing/closed-connection-error";
 import { waitFor } from "../../testing/wait-for";
-import { isClosedConnectionError, unsafeReadRetrying } from "../query";
+import {
+  describeClosedConnectionFailure,
+  isClosedConnectionError,
+  unsafeReadRetrying,
+} from "../query";
 
 const DATABASE_URL = testDatabaseUrl();
 
@@ -157,3 +161,92 @@ describe.each(drivers)("extractPgError — %s unique-violation SQLSTATE", (kind)
     }
   });
 });
+
+describe("describeClosedConnectionFailure", () => {
+  test("describes a real postgres-js pool error without SQL text or params", async () => {
+    const applicationName = randomAppName();
+    const pool = postgres(DATABASE_URL, {
+      max: 2,
+      connection: { application_name: applicationName },
+    });
+    try {
+      await Promise.all([pool.unsafe("select 1"), pool.unsafe("select 1")]);
+      const secretParam = `secret-${crypto.randomUUID()}`;
+      const pending = pool
+        .unsafe("select $1::text as x from pg_sleep(0.3)", [secretParam])
+        .catch((e: unknown) => e);
+      const pid = await pollForActivePid(applicationName, "%pg_sleep(0.3)%");
+      await terminateBackendPid(pid);
+      const caught = await pending;
+
+      const described = describeClosedConnectionFailure(pool, caught, 3);
+      expect(described).toMatchObject({
+        driver: "postgres-js",
+        pooled: true,
+        attempts: 3,
+        poolMax: 2,
+      });
+      expect(described?.["errorCode"]).toBe(extractPgError(caught)?.code);
+      const serialized = JSON.stringify(described);
+      expect(serialized).not.toContain(secretParam);
+      expect(serialized).not.toContain("pg_sleep");
+    } finally {
+      await pool.end({ timeout: 0 });
+    }
+  });
+
+  test("describes a real postgres-js transaction handle as not pooled", async () => {
+    const applicationName = randomAppName();
+    const pool = postgres(DATABASE_URL, {
+      max: 2,
+      connection: { application_name: applicationName },
+    });
+    try {
+      let described: Record<string, unknown> | undefined;
+      await pool
+        .begin(async (tx) => {
+          const pending = tx.unsafe("select 1 from pg_sleep(0.3)").catch((e: unknown) => e);
+          const pid = await pollForActivePid(applicationName, "%pg_sleep(0.3)%");
+          await terminateBackendPid(pid);
+          described = describeClosedConnectionFailure(tx, await pending, 1);
+        })
+        .catch(() => undefined);
+      expect(described).toMatchObject({ driver: "postgres-js", pooled: false, attempts: 1 });
+    } finally {
+      await pool.end({ timeout: 0 });
+    }
+  });
+
+  test("describes a real Bun.SQL closed-pool error", async () => {
+    const pool = new Bun.SQL({ url: DATABASE_URL, max: 1, idleTimeout: 5, maxLifetime: 10 });
+    await pool.unsafe("select 1");
+    await pool.close();
+    const caught = await pool.unsafe("select 1").catch((e: unknown) => e);
+
+    expect(describeClosedConnectionFailure(pool, caught, 1)).toMatchObject({
+      driver: "bun-sql",
+      pooled: true,
+      poolMax: 1,
+      idleTimeoutMs: 5000,
+      maxLifetimeMs: 10000,
+      errorCode: "ERR_POSTGRES_CONNECTION_CLOSED",
+    });
+  });
+
+  test("returns undefined for an unrelated error", () => {
+    expect(describeClosedConnectionFailure({}, new Error("boom"), 1)).toBeUndefined();
+    expect(describeClosedConnectionFailure({}, "not an error", 1)).toBeUndefined();
+  });
+
+  test("matches the driver's AbortError for a closed connection", () => {
+    const abort = new DOMException("The connection was closed.", "AbortError");
+    expect(describeClosedConnectionFailure({}, abort, 2)).toMatchObject({
+      driver: "unknown",
+      attempts: 2,
+      errorName: "AbortError",
+    });
+    expect(
+      describeClosedConnectionFailure({}, new DOMException("other", "AbortError"), 1),
+    ).toBeUndefined();
+  });
+});

package/src/bun-db/query.ts

@@ -28,6 +28,7 @@ import type {
 // Static polyfill import (not getTemporal()): coercion results stay on one
 // Temporal implementation repo-wide, even when Bun exposes a global (#1480).
 import { Temporal } from "temporal-polyfill";
+import { requestContext } from "../api/request-context";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index";
 import { SQL_EXPR_BRAND } from "../db/dialect";
 import type { EntityTableMeta } from "../db/entity-table-meta";
@@ -35,6 +36,7 @@ import { extractPgError } from "../db/pg-error";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
 import { InternalError } from "../errors";
+import { createFallbackLogger } from "../logging";
 import { parseJsonSafe } from "../utils/safe-json";
 
 // Idempotent snake_case → camelCase. `env.camelCase` always lowercases first
@@ -755,6 +757,120 @@ function isPooledClient(raw: unknown): boolean {
   );
 }
 
+const closedConnectionLog = createFallbackLogger("bun-db");
+
+// The driver rejects in-flight queries with this AbortError (no code) when the
+// pool closes under them, so isClosedConnectionError can't see it.
+const DRIVER_CLOSED_ABORT_MESSAGE = "The connection was closed.";
+
+function isDriverClosedAbort(err: unknown): boolean {
+  return (
+    err instanceof Error && err.name === "AbortError" && err.message === DRIVER_CLOSED_ABORT_MESSAGE
+  );
+}
+
+function isHandleLike(raw: unknown): raw is Record<string, unknown> {
+  return raw !== null && (typeof raw === "object" || typeof raw === "function");
+}
+
+type ClosedConnectionDriver = "bun-sql" | "postgres-js" | "unknown";
+
+// Bun.SQL is not instanceof-checkable (Bun.SQL.prototype is invalid) and its tx
+// handles are plain function objects, so discriminate by members only one driver
+// has: `flush` on Bun.SQL (pool and tx), `typed` on postgres-js (pool and tx).
+function driverOf(raw: unknown): ClosedConnectionDriver {
+  if (!isHandleLike(raw)) return "unknown";
+  if (typeof raw["flush"] === "function") return "bun-sql";
+  if (typeof raw["typed"] === "function") return "postgres-js";
+  return "unknown";
+}
+
+function positiveNumber(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined;
+}
+
+// postgres-js configures timeouts in seconds, Bun.SQL in milliseconds.
+function timeoutOptionMs(
+  options: Record<string, unknown>,
+  driver: ClosedConnectionDriver,
+  bunName: string,
+  postgresJsName: string,
+): number | undefined {
+  if (driver === "postgres-js") {
+    const seconds = positiveNumber(options[postgresJsName]);
+    return seconds === undefined ? undefined : seconds * 1000;
+  }
+  return positiveNumber(options[bunName]);
+}
+
+function errorProp(err: unknown, name: string): unknown {
+  return isHandleLike(err) ? err[name] : undefined;
+}
+
+// Deliberately excludes SQL text and parameters: app SQL can carry PII.
+export function describeClosedConnectionFailure(
+  raw: unknown,
+  err: unknown,
+  attempts: number,
+): Record<string, unknown> | undefined {
+  if (!isClosedConnectionError(err) && !isDriverClosedAbort(err)) return undefined;
+  const driver = driverOf(raw);
+  const rawOptions = isHandleLike(raw) ? raw["options"] : undefined;
+  const options = isHandleLike(rawOptions) ? rawOptions : {};
+  return {
+    driver,
+    pooled: isPooledClient(raw),
+    attempts,
+    poolMax: positiveNumber(options["max"]),
+    idleTimeoutMs: timeoutOptionMs(options, driver, "idleTimeout", "idle_timeout"),
+    maxLifetimeMs: timeoutOptionMs(options, driver, "maxLifetime", "max_lifetime"),
+    connectionTimeoutMs: timeoutOptionMs(options, driver, "connectionTimeout", "connect_timeout"),
+    errorName: errorProp(err, "name"),
+    errorCode: extractPgError(err)?.code ?? errorProp(err, "code"),
+    errorErrno: errorProp(err, "errno"),
+    errorMessage: errorProp(err, "message"),
+  };
+}
+
+type ClosedConnectionContext = { readonly operation: string; readonly table?: string };
+
+function logClosedConnection(
+  raw: unknown,
+  err: unknown,
+  attempts: number,
+  context?: ClosedConnectionContext,
+): void {
+  const failure = describeClosedConnectionFailure(raw, err, attempts);
+  // skip: not a closed-connection error, nothing to diagnose
+  if (!failure) return;
+  // Request identity lets this line be joined to the route's `handler failed` log.
+  const request = requestContext.get();
+  closedConnectionLog.warn("closed connection surfaced", {
+    ...failure,
+    ...context,
+    requestId: request?.requestId,
+    correlationId: request?.correlationId,
+    handler: request?.handler,
+  });
+}
+
+// Write and other non-retried paths: log when a closed-connection error leaves
+// bun-db, rethrow unchanged.
+async function unsafeLoggingClosedConnection(
+  db: AnyDb,
+  sqlText: string,
+  params: readonly unknown[],
+  context: ClosedConnectionContext,
+): Promise<readonly unknown[]> {
+  const raw = asRawClient(db);
+  try {
+    return await raw.unsafe(sqlText, params);
+  } catch (err) {
+    logClosedConnection(raw, err, 1, context);
+    throw err;
+  }
+}
+
 function poolMaxOf(raw: unknown): number {
   // @cast-boundary driver pool options — both postgres-js and Bun.SQL expose options.max
   const max = (raw as { options?: { max?: unknown } }).options?.max;
@@ -774,7 +890,10 @@ export async function unsafeReadRetrying<TRow>(
   try {
     return (await raw.unsafe(sqlText, params)) as readonly TRow[];
   } catch (err) {
-    if (!isPooledClient(raw) || !isClosedConnectionError(err)) throw err;
+    if (!isPooledClient(raw) || !isClosedConnectionError(err)) {
+      logClosedConnection(raw, err, 1);
+      throw err;
+    }
     const maxAttempts = poolMaxOf(raw) + 1;
     let lastErr: unknown = err;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
@@ -782,9 +901,13 @@ export async function unsafeReadRetrying<TRow>(
         return (await raw.unsafe(sqlText, params)) as readonly TRow[];
       } catch (retryErr) {
         lastErr = retryErr;
-        if (!isClosedConnectionError(retryErr)) throw retryErr;
+        if (!isClosedConnectionError(retryErr)) {
+          logClosedConnection(raw, retryErr, attempt + 2);
+          throw retryErr;
+        }
       }
     }
+    logClosedConnection(raw, lastErr, maxAttempts + 1);
     throw lastErr;
   }
 }
@@ -876,7 +999,10 @@ export async function insertMany<TRow = any>(
     valuesClauses.push(`(${placeholders.join(", ")})`);
   }
   const sqlText = `INSERT INTO ${quoteIdent(info.name)} (${cols}) VALUES ${valuesClauses.join(", ")} RETURNING *`;
-  const raw = (await asRawClient(db).unsafe(sqlText, params)) as readonly Record<string, unknown>[];
+  const raw = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+    operation: "insertMany",
+    table: info.name,
+  })) as readonly Record<string, unknown>[];
   return coerceRows(raw, info) as readonly TRow[];
 }
 
@@ -909,10 +1035,10 @@ export async function insertOne<TRow = any>(
     })
     .join(", ");
   const sqlText = `INSERT INTO ${quoteIdent(info.name)} (${cols}) VALUES (${placeholders}) RETURNING *`;
-  const rows = (await asRawClient(db).unsafe(sqlText, params)) as readonly Record<
-    string,
-    unknown
-  >[];
+  const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+    operation: "insertOne",
+    table: info.name,
+  })) as readonly Record<string, unknown>[];
   const first = rows[0];
   if (!first) return undefined;
   return coerceRow(first, info) as TRow;
@@ -930,11 +1056,13 @@ export async function updateMany<TRow = any>(
     return scoped.updateMany<TRow>(table, set, where);
   }
   const info = extractTableInfo(table);
-  const setEntries = Object.entries(set).map(([k, v]) => {
-    const col = info.columnOf(k);
-    const pgType = info.pgTypeOf(col);
-    return { col, prepared: prepareValue(v, pgType) };
-  });
+  const setEntries = Object.entries(set)
+    .filter(([k]) => info.hasColumn(k))
+    .map(([k, v]) => {
+      const col = info.columnOf(k);
+      const pgType = info.pgTypeOf(col);
+      return { col, prepared: prepareValue(v, pgType) };
+    });
   if (setEntries.length === 0) throw new Error("updateMany: empty set object");
   const values: unknown[] = [];
   let idx = 1;
@@ -954,7 +1082,10 @@ export async function updateMany<TRow = any>(
     for (const v of w.values) values.push(v);
   }
   sqlText += " RETURNING *";
-  const raw = (await asRawClient(db).unsafe(sqlText, values)) as readonly Record<string, unknown>[];
+  const raw = (await unsafeLoggingClosedConnection(db, sqlText, values, {
+    operation: "updateMany",
+    table: info.name,
+  })) as readonly Record<string, unknown>[];
   return coerceRows(raw, info) as readonly TRow[];
 }
 
@@ -971,7 +1102,10 @@ export async function deleteMany(
   const w = buildWhereClause(info, where, 1);
   let sqlText = `DELETE FROM ${quoteIdent(info.name)}`;
   if (w.sqlText) sqlText += ` WHERE ${w.sqlText}`;
-  await asRawClient(db).unsafe(sqlText, w.values);
+  await unsafeLoggingClosedConnection(db, sqlText, w.values, {
+    operation: "deleteMany",
+    table: info.name,
+  });
 }
 
 type InsertEntry = {
@@ -1104,10 +1238,10 @@ export async function upsertOnConflict<TRow = any>(
 
   const conflictList = conflictCols.map((c) => quoteIdent(c)).join(", ");
   const sqlText = `${sqlPrefix} ON CONFLICT (${conflictList}) DO UPDATE SET ${updateParts.join(", ")} RETURNING *`;
-  const rows = (await asRawClient(db).unsafe(sqlText, params)) as readonly Record<
-    string,
-    unknown
-  >[];
+  const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+    operation: "upsertOnConflict",
+    table: info.name,
+  })) as readonly Record<string, unknown>[];
   const first = rows[0];
   if (!first) return undefined;
   return coerceRow(first, info) as TRow;
@@ -1186,10 +1320,10 @@ export async function incrementCounter<TRow = any>(
 
   const conflictList = conflictCols.map((c) => quoteIdent(c)).join(", ");
   const sqlText = `${sqlPrefix} ON CONFLICT (${conflictList}) DO UPDATE SET ${updateParts.join(", ")} RETURNING *`;
-  const rows = (await asRawClient(db).unsafe(sqlText, params)) as readonly Record<
-    string,
-    unknown
-  >[];
+  const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+    operation: "incrementCounter",
+    table: info.name,
+  })) as readonly Record<string, unknown>[];
   const first = rows[0];
   if (!first) return undefined;
   return coerceRow(first, info) as TRow;
@@ -1225,7 +1359,10 @@ export async function deleteManyBatched(
     const sqlText = `DELETE FROM ${tableQ} WHERE ${idQ} IN (
       SELECT ${idQ} FROM ${tableQ} WHERE ${w.sqlText} LIMIT $${limitIdx}
     ) RETURNING ${idQ}`;
-    const rows = (await asRawClient(db).unsafe(sqlText, params)) as readonly unknown[];
+    const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+      operation: "deleteManyBatched",
+      table: info.name,
+    })) as readonly unknown[];
     batches++;
     deleted += rows.length;
     if (rows.length < limit) break;

package/src/changes.json

@@ -1,4 +1,58 @@
 [
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "bun-db logs a diagnostic warning when a closed-connection error surfaces",
+    "detail": "When a closed-connection error leaves bun-db (retries exhausted, a transaction/reserved handle, or a write path), a `[bun-db] closed connection surfaced` warning records driver, pooled vs. transaction handle, attempts, pool size, timeouts and the error code. It never includes SQL text or parameters. Behaviour, retries and timeouts are unchanged."
+  },
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "runProdApp and runWorkerApp re-encrypt plaintext events after a field gains a PII annotation",
+    "detail": "When an event field is annotated as PII after events were already stored, the stored payloads stay plaintext because a projection rebuild copies them unchanged. After start, `runProdApp` and `runWorkerApp` now run `runPiiEventBackfill` in the background: it encrypts those events in place once per annotation state, queues the affected projections (including multi-stream projections with their own table) in `kumiko_pending_rebuilds` and rebuilds them, so ciphertext and blind-index columns get materialized. Later boots only run a cheap catch-up over the newest events. Replicas are serialized by an advisory lock, each batch commits on its own, and failed events are logged and retried on the next boot. Progress lives in the new table `kumiko_pii_backfill_state`, created on first run. Behavior change: the first boot after the bump rewrites `kumiko_events` payloads for annotated fields; set `KUMIKO_SKIP_PII_BACKFILL=1` to opt out. Calling `backfillEventPiiEncryption` by hand stays necessary for `eraseUnresolvableSubjects`, which the boot run never sets. `backfillEventPiiEncryptionBatch` is the new single-batch primitive both build on. `runPendingRebuilds` (the schema-apply queue drain) now also rebuilds queued multi-stream projection tables instead of failing on them; a failed multi-stream rebuild in either path stays queued and leaves the live consumer running."
+  },
+  {
+    "version": "0.328.0",
+    "type": "fix",
+    "title": "The projection-rebuild job also rebuilds multi-stream projections",
+    "detail": "`enqueueProjectionRebuild` and the `jobs:job:projection-rebuild` worker used to call the single-stream rebuild only, so a multi-stream projection name failed with \"not registered\". Both now go through `rebuildProjectionOrMultiStream` (exported from `@cosmicdrift/kumiko-framework/migrations`), the same helper the pending-rebuild queue uses. For multi-stream projections the skip mode comes from the projection's declared `errorMode`; the job payload's `skipApplyErrors` only applies to single-stream projections."
+  },
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "SearchAdapter gains an optional dropAllIndexes() for rebuilds on a persistent index",
+    "detail": "`dropAllIndexes()` deletes every tenant index the adapter owns and returns the count. The in-memory adapter clears all tenants; the Meilisearch adapter deletes all indexes under its prefix (and refuses an empty prefix) and resets its configured-tenant state so the next write recreates a filterable index."
+  },
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "setupTestStack can wire job run-logger callbacks, and setupTestStackFromFeatures does so by default",
+    "detail": "`TestStackOptions.jobs.runLogger` receives `{ registry, db }` and returns `onJobStart`/`onJobComplete`/`onJobFailed`. The stack awaits them before drainJobs() observes the outcome, so a log row is always written before drainJobs() resolves or rejects. `setupTestStackFromFeatures` (and with it `setupAppTestStack`) defaults to the same `jobRunLoggerCallbacks` prod uses whenever `jobs` is set and the jobs feature is mounted, so `tenantVisibleFailure` rows and `jobs:query:failures` work in tests without a hand-built harness. Such suites now write `job_runs` and tenant failure rows for every job run; a suite that counts those rows, or that wants the old behavior, passes its own `jobs.runLogger` (for example one returning `undefined`)."
+  },
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "build-app-schema carries optionTones and collects the new screen i18n keys",
+    "detail": "Select `optionTones` reach the client schema. `createLabel`, `searchPlaceholder`, `summary`, related list `description` and `itemNoun` are collected as i18n keys of the screen, so they are translated like other screen text."
+  },
+  {
+    "version": "0.327.0",
+    "type": "improvement",
+    "title": "r.webSocketRoute for authenticated WebSocket routes under /api/ws/",
+    "detail": "renderer-web gains `FloatingPanel` (movable, resizable, non-modal panel with persisted geometry and a full-screen sheet on narrow viewports) and exports `useIsNarrowViewport`. Features can declare `r.webSocketRoute` under `/api/ws/` with session auth, an Origin check (allowlist, or same host without one), a per-route message cap, backpressure protection (4 MiB, the socket is closed beyond it) and a per-user connection cap (`maxConnectionsPerUser`, default 5, per server process; over it the upgrade gets 429). Handlers run one after another in arrival order per socket; on close `onClose` runs immediately (not queued behind a hung handler), queued messages never start, and `connection.signal` aborts. A 25 s heartbeat revalidates session, roles, tenant lifecycle and the token's own expiry (close 1008); a session store that keeps failing closes the socket with 1013 after three failed checks in a row. A server without upgrade wiring answers 501 `websocket_upgrade_not_wired` and logs the fix. `buildBunServeOptions` takes an optional `{ upgradeFetch, heartbeatIntervalMs? }` object as 4th argument and `runProdApp` handles expose `webSocketUpgradeFetch`; the dev server wires it. Upgrade rejections carry the same security headers as other responses. Additive, no migration."
+  },
+  {
+    "version": "0.327.0",
+    "type": "fix",
+    "title": "JobRunner.stop() waits for queue readiness before closing",
+    "detail": "JobRunner.stop() waits (bounded by the boot Redis timeout) for its queues to be ready before closing them. Stopping a runner right after construction no longer leaves an unhandled \"Connection is closed.\" rejection behind."
+  },
+  {
+    "version": "0.327.0",
+    "type": "fix",
+    "title": "updateMany drops unknown columns, so replaying an update event for a removed field no longer fails the rebuild",
+    "detail": "`updateMany` now ignores keys that have no column on the target table, matching `insertOne`/`insertMany`. A historical `<entity>.updated` event that still carries a field removed from the entity no longer aborts a projection rebuild with \"column ... does not exist\"."
+  },
   {
     "version": "0.325.0",
     "type": "improvement",

package/src/crypto/__tests__/system-event-pii.test.ts

@@ -0,0 +1,77 @@
+// System events bypass the defineEvent catalog, so their PII stance lives in
+// a static map. An undeclared system type must fail closed (also without a
+// KMS), and every known system type must have a declared stance.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import * as stepDispatchConstants from "../../engine/steps/_step-dispatch-constants";
+import type { TenantId } from "../../engine/types/identifiers";
+import { encryptEventPayloadPii } from "../event-pii";
+import { InMemoryKmsAdapter } from "../in-memory-kms-adapter";
+import {
+  configurePiiSubjectKms,
+  isPiiCiphertext,
+  resetPiiSubjectKmsForTests,
+} from "../pii-field-encryption";
+import type { EventSubjectEnvelope } from "../subject-resolver";
+import {
+  AGGREGATE_TRANSFERRED_EVENT_TYPE,
+  SYSTEM_EVENT_PII_STANCES,
+  SYSTEM_EVENT_PREFIX,
+} from "../system-event-pii";
+
+const ENVELOPE: EventSubjectEnvelope = {
+  tenantId: "6b2f4a0e-1c9d-4f3a-9d2e-0000000000e1" as TenantId,
+  aggregateType: "step-dispatch",
+  aggregateId: "6b2f4a0e-1c9d-4f3a-9d2e-0000000000e2",
+};
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+describe("system event PII stances", () => {
+  test("every system event type constant has a declared stance", () => {
+    const declaredTypes = [
+      ...Object.entries(stepDispatchConstants)
+        .filter(([name]) => name.endsWith("_TYPE"))
+        .map(([, value]: [string, unknown]) => value)
+        .filter(
+          (value): value is string =>
+            typeof value === "string" && value.startsWith(SYSTEM_EVENT_PREFIX),
+        ),
+      AGGREGATE_TRANSFERRED_EVENT_TYPE,
+    ];
+    expect(declaredTypes.length).toBeGreaterThanOrEqual(11);
+    for (const type of declaredTypes) {
+      expect(SYSTEM_EVENT_PII_STANCES.has(type)).toBe(true);
+    }
+  });
+
+  test("an undeclared system type fails closed, even without a configured KMS", async () => {
+    await expect(
+      encryptEventPayloadPii(`${SYSTEM_EVENT_PREFIX}made.up`, { secret: "x" }, ENVELOPE),
+    ).rejects.toThrow(/System event "kumiko:system:made\.up" has no PII stance/);
+  });
+
+  test('a "none" stance passes the payload through untouched', async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const payload = { stepKind: "mail.send", status: 202 };
+    expect(
+      await encryptEventPayloadPii(stepDispatchConstants.STEP_DISPATCHED_TYPE, payload, ENVELOPE),
+    ).toBe(payload);
+  });
+
+  test("dispatch-requested encrypts its string fields under the per-dispatch record key", async () => {
+    configurePiiSubjectKms(new InMemoryKmsAdapter());
+    const out = await encryptEventPayloadPii(
+      stepDispatchConstants.STEP_DISPATCH_REQUESTED_TYPE,
+      { stepKind: "mail.send", to: '"a@example.com"', subject: "Hi", body: "Body" },
+      ENVELOPE,
+    );
+    expect(out["stepKind"]).toBe("mail.send");
+    for (const field of ["to", "subject", "body"]) {
+      expect(isPiiCiphertext(out[field])).toBe(true);
+      expect(String(out[field])).toContain(`record:step-dispatch:${ENVELOPE.aggregateId}`);
+    }
+  });
+});

package/src/crypto/event-pii.ts

@@ -4,7 +4,9 @@
 // path at all. `r.defineEvent(name, schema, { piiFields })` declares which
 // payload fields are PII and which payload field names the owning user;
 // createRegistry publishes the catalog and append() — the single write funnel
-// into kumiko_events — encrypts every catalogued field.
+// into kumiko_events — encrypts every catalogued field. `kumiko:system:*`
+// events skip the registry and take their stance from system-event-pii.ts
+// instead (fail-closed when missing).
 //
 // `piiFields` is a mandatory, explicit stance (fw#2558): a payload can only
 // go uncatalogued through a declared `piiFields: "none"`, never by omission —
@@ -12,10 +14,11 @@
 // silent no-op (forgetting the option) is now either an explicit "none" or a
 // missing subject KMS at encrypt-time, both visible states, not a gap.
 
-import type { EventPiiFields } from "@cosmicdrift/kumiko-types/handlers";
+import type { EventPiiFields, EventPiiStance } from "@cosmicdrift/kumiko-types/handlers";
 import { requestContext } from "../api/request-context";
 import { configuredPiiSubjectKms, encryptPiiValueForSubject } from "./pii-field-encryption";
 import { type EventSubjectEnvelope, resolveEventSubject } from "./subject-resolver";
+import { SYSTEM_EVENT_PII_STANCES, SYSTEM_EVENT_PREFIX } from "./system-event-pii";
 
 export type EventPiiCatalog = ReadonlyMap<string, EventPiiFields>;
 
@@ -36,6 +39,19 @@ export function resetEventPiiCatalogForTests(): void {
   catalog = new Map();
 }
 
+// System types are checked before the KMS gate: an undeclared one throws
+// even in plaintext rollout mode.
+function resolvePiiStance(eventType: string): EventPiiStance | undefined {
+  if (!eventType.startsWith(SYSTEM_EVENT_PREFIX)) return catalog.get(eventType);
+  const stance = SYSTEM_EVENT_PII_STANCES.get(eventType);
+  if (stance === undefined) {
+    throw new Error(
+      `System event "${eventType}" has no PII stance — declare one in SYSTEM_EVENT_PII_STANCES (crypto/system-event-pii.ts)`,
+    );
+  }
+  return stance;
+}
+
 // Encrypts catalogued payload fields under the declared subject's DEK
 // (user/tenant/self — resolveEventSubject, fw#2801). No-op when the event
 // type is uncatalogued or no subject KMS is configured (plaintext rollout
@@ -51,8 +67,8 @@ export async function encryptEventPayloadPii(
   payload: Record<string, unknown>,
   envelope: EventSubjectEnvelope,
 ): Promise<Record<string, unknown>> {
-  const piiFields = catalog.get(eventType);
-  if (!piiFields) return payload;
+  const piiFields = resolvePiiStance(eventType);
+  if (!piiFields || piiFields === "none") return payload;
   const kms = configuredPiiSubjectKms();
   if (!kms) return payload;
 

package/src/crypto/system-event-pii.ts

@@ -0,0 +1,57 @@
+// PII stance of every `kumiko:system:*` event. System events bypass the
+// registry (append-event-core), so they never reach the defineEvent catalog;
+// this static map is their catalog. encryptEventPayloadPii fails closed on a
+// system type with no entry here, so a new system event cannot ship its
+// payload as plaintext by omission.
+
+import type { EventPiiStance } from "@cosmicdrift/kumiko-types/handlers";
+import {
+  STEP_DISPATCH_FAILED_TYPE,
+  STEP_DISPATCH_REQUESTED_TYPE,
+  STEP_DISPATCHED_TYPE,
+  WORKFLOW_RESUMED_TYPE,
+  WORKFLOW_RETRY_SCHEDULED_TYPE,
+  WORKFLOW_RUN_COMPLETED_TYPE,
+  WORKFLOW_RUN_FAILED_TYPE,
+  WORKFLOW_RUN_STARTED_TYPE,
+  WORKFLOW_WAITING_FOR_EVENT_TYPE,
+  WORKFLOW_WAITING_TYPE,
+} from "../engine/steps/_step-dispatch-constants";
+
+export const SYSTEM_EVENT_PREFIX = "kumiko:system:";
+
+// Lives here (not in event-store/transfer.ts) so this module stays free of
+// an event-store import cycle; transfer.ts re-exports it.
+export const AGGREGATE_TRANSFERRED_EVENT_TYPE = `${SYSTEM_EVENT_PREFIX}aggregate.transferred`;
+
+const SELF = { personal: "self" } as const;
+
+// Workflow payloads carry `triggerPayload`, the stored payload of the trigger
+// event: catalogued fields there are already ciphertext, so "none" leaks nothing.
+export const SYSTEM_EVENT_PII_STANCES: ReadonlyMap<string, EventPiiStance> = new Map<
+  string,
+  EventPiiStance
+>([
+  [
+    STEP_DISPATCH_REQUESTED_TYPE,
+    {
+      to: SELF,
+      subject: SELF,
+      body: SELF,
+      from: SELF,
+      url: SELF,
+      headersJson: SELF,
+      bodyJson: SELF,
+    },
+  ],
+  [STEP_DISPATCHED_TYPE, "none"],
+  [STEP_DISPATCH_FAILED_TYPE, "none"],
+  [AGGREGATE_TRANSFERRED_EVENT_TYPE, "none"],
+  [WORKFLOW_WAITING_TYPE, "none"],
+  [WORKFLOW_WAITING_FOR_EVENT_TYPE, "none"],
+  [WORKFLOW_RESUMED_TYPE, "none"],
+  [WORKFLOW_RUN_STARTED_TYPE, "none"],
+  [WORKFLOW_RUN_COMPLETED_TYPE, "none"],
+  [WORKFLOW_RUN_FAILED_TYPE, "none"],
+  [WORKFLOW_RETRY_SCHEDULED_TYPE, "none"],
+]);