@cosmicdrift/kumiko-framework 0.165.2 → 0.165.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.165.2",
+  "version": "0.165.3",
   "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>",
@@ -197,10 +197,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@cosmicdrift/kumiko-types": "^0.165.2"
+    "@cosmicdrift/kumiko-types": "^0.165.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.165.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.165.3",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/sse-broker.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, mock, test } from "bun:test";
-import { createSseBroker, type SseEvent } from "../sse-broker";
+import { createSseBroker, type SseBroker, type SseEvent } from "../sse-broker";
+
+function requireAccessInvalidation(broker: SseBroker) {
+  const subscribe = broker.subscribeAccessInvalidation;
+  const publish = broker.publishAccessInvalidation;
+  if (!subscribe || !publish) {
+    throw new Error("createSseBroker must implement access-invalidation hooks");
+  }
+  return { subscribe, publish };
+}
 
 describe("SSE broker", () => {
   test("adds client and tracks count", () => {
@@ -57,59 +66,59 @@ describe("SSE broker", () => {
   });
 
   test("subscribeAccessInvalidation fires only listeners on the same user's channel", () => {
-    const broker = createSseBroker();
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
     const onInvalidateA = mock();
     const onInvalidateB = mock();
 
-    broker.subscribeAccessInvalidation("user-a", onInvalidateA);
-    broker.subscribeAccessInvalidation("user-b", onInvalidateB);
+    subscribe("user-a", onInvalidateA);
+    subscribe("user-b", onInvalidateB);
 
-    broker.publishAccessInvalidation("user-a");
+    publish("user-a");
 
     expect(onInvalidateA).toHaveBeenCalledTimes(1);
     expect(onInvalidateB).not.toHaveBeenCalled();
   });
 
   test("subscribeAccessInvalidation supports multiple listeners on the same user", () => {
-    const broker = createSseBroker();
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
     const first = mock();
     const second = mock();
 
-    broker.subscribeAccessInvalidation("user-a", first);
-    broker.subscribeAccessInvalidation("user-a", second);
-    broker.publishAccessInvalidation("user-a");
+    subscribe("user-a", first);
+    subscribe("user-a", second);
+    publish("user-a");
 
     expect(first).toHaveBeenCalledTimes(1);
     expect(second).toHaveBeenCalledTimes(1);
   });
 
   test("unsubscribe (returned closure) stops further delivery", () => {
-    const broker = createSseBroker();
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
     const onInvalidate = mock();
 
-    const unsubscribe = broker.subscribeAccessInvalidation("user-a", onInvalidate);
+    const unsubscribe = subscribe("user-a", onInvalidate);
     unsubscribe();
-    broker.publishAccessInvalidation("user-a");
+    publish("user-a");
 
     expect(onInvalidate).not.toHaveBeenCalled();
   });
 
   test("a fired listener can unsubscribe itself without skipping other listeners", () => {
-    const broker = createSseBroker();
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
     let unsubscribeSelf: () => void = () => {};
     const self = mock(() => unsubscribeSelf());
     const other = mock();
 
-    unsubscribeSelf = broker.subscribeAccessInvalidation("user-a", self);
-    broker.subscribeAccessInvalidation("user-a", other);
-    broker.publishAccessInvalidation("user-a");
+    unsubscribeSelf = subscribe("user-a", self);
+    subscribe("user-a", other);
+    publish("user-a");
 
     expect(self).toHaveBeenCalledTimes(1);
     expect(other).toHaveBeenCalledTimes(1);
   });
 
   test("publishAccessInvalidation to a user with no listeners does nothing", () => {
-    const broker = createSseBroker();
-    expect(() => broker.publishAccessInvalidation("nobody-listening")).not.toThrow();
+    const { publish } = requireAccessInvalidation(createSseBroker());
+    expect(() => publish("nobody-listening")).not.toThrow();
   });
 });

package/src/api/sse-broker.ts

@@ -19,8 +19,9 @@ export type SseBroker = {
   getClientCount(channel: string): number;
   getTotalClientCount(): number;
   // Separate from addClient so it doesn't count towards getClientCount.
-  subscribeAccessInvalidation(userId: string, onInvalidate: () => void): () => void;
-  publishAccessInvalidation(userId: string): void;
+  // Optional: additive for external/test SseBroker impls (call sites use?.).
+  subscribeAccessInvalidation?(userId: string, onInvalidate: () => void): () => void;
+  publishAccessInvalidation?(userId: string): void;
 };
 
 export function createSseBroker(): SseBroker {
@@ -28,7 +29,7 @@ export function createSseBroker(): SseBroker {
   // Redis. Multi-replica deployments will not revoke SSE streams on other pods
   // (security control is single-node). Upgrade: Redis pub/sub on userAccessChannel.
   const channels = new Map<string, Map<string, SseClient>>();
-  const accessInvalidationListeners = new Map<string, Map<string, () => void>>();
+  const accessInvalidationListeners = new Map<string, Set<() => void>>();
 
   function getOrCreateChannel(channel: string): Map<string, SseClient> {
     let clients = channels.get(channel);
@@ -78,18 +79,17 @@ export function createSseBroker(): SseBroker {
 
     subscribeAccessInvalidation(userId, onInvalidate) {
       const channel = userAccessChannel(userId);
-      const listenerId = generateId();
       let listeners = accessInvalidationListeners.get(channel);
       if (!listeners) {
-        listeners = new Map();
+        listeners = new Set();
         accessInvalidationListeners.set(channel, listeners);
       }
-      listeners.set(listenerId, onInvalidate);
+      listeners.add(onInvalidate);
       return () => {
         const current = accessInvalidationListeners.get(channel);
         // skip: already unsubscribed (e.g. stream ended after a publish already fired)
         if (!current) return;
-        current.delete(listenerId);
+        current.delete(onInvalidate);
         if (current.size === 0) accessInvalidationListeners.delete(channel);
       };
     },
@@ -101,7 +101,7 @@ export function createSseBroker(): SseBroker {
       if (!listeners) return;
       // Snapshot before iterating — a fired listener unsubscribes itself,
       // which would mutate `listeners` mid-iteration otherwise.
-      for (const onInvalidate of [...listeners.values()]) {
+      for (const onInvalidate of [...listeners]) {
         onInvalidate();
       }
     },

package/src/crypto/index.ts

@@ -61,6 +61,7 @@ export {
 } from "./request-kms-cache";
 export {
   collectPiiSubjectFields,
+  collectSearchableSubjectFields,
   type ResolveSubjectOptions,
   resolveSubjectForField,
   SubjectResolutionError,

package/src/crypto/subject-resolver.ts

@@ -89,3 +89,18 @@ export function collectPiiSubjectFields(entity: EntityDefinition): readonly stri
     )
     .map(([name]) => name);
 }
+
+/** Subject-annotated fields that may be plaintext in the derived search index (#1610). */
+export function collectSearchableSubjectFields(entity: EntityDefinition): readonly string[] {
+  return Object.entries(entity.fields)
+    .filter(([, field]) => {
+      const subject =
+        ("userOwned" in field && field.userOwned !== undefined) ||
+        ("tenantOwned" in field && field.tenantOwned === true) ||
+        ("pii" in field && field.pii === true);
+      if (!subject) return false;
+      if ("sensitive" in field && field.sensitive === true) return false;
+      return "searchable" in field && field.searchable === true;
+    })
+    .map(([name]) => name);
+}

package/src/db/__tests__/migrate-runner.test.ts

@@ -38,6 +38,10 @@ describe("splitSqlStatements", () => {
     expect(splitSqlStatements("SELECT a/*x*/AS b;")).toEqual(["SELECT a AS b;"]);
   });
 
+  test("nested block comments close only at matching depth (Postgres)", () => {
+    expect(splitSqlStatements("/* a /* b */ c */ SELECT 1;")).toEqual(["SELECT 1;"]);
+  });
+
   test("a block-comment opener inside a line comment does not swallow the next statement", () => {
     const sql = `
       -- note: see /* details below

package/src/db/migrate-runner.ts

@@ -81,6 +81,7 @@ export function splitSqlStatements(sqlText: string): readonly string[] {
   const statements: string[] = [];
   let current = "";
   let state: SqlScanState = "normal";
+  let blockCommentDepth = 0;
 
   for (let i = 0; i < sqlText.length; i++) {
     const ch = sqlText.charAt(i);
@@ -94,11 +95,21 @@ export function splitSqlStatements(sqlText: string): readonly string[] {
       continue;
     }
     if (state === "blockComment") {
+      // Postgres nests block comments — track depth so the first `*/` does
+      // not leave trailing comment text in the statement.
+      if (ch === "/" && next === "*") {
+        blockCommentDepth++;
+        i++;
+        continue;
+      }
       if (ch === "*" && next === "/") {
-        state = "normal";
         i++;
-        // Keep a space so `a/*x*/AS` does not become `aAS`.
-        current += " ";
+        blockCommentDepth--;
+        if (blockCommentDepth === 0) {
+          state = "normal";
+          // Keep a space so `a/*x*/AS` does not become `aAS`.
+          current += " ";
+        }
       }
       continue;
     }
@@ -135,6 +146,7 @@ export function splitSqlStatements(sqlText: string): readonly string[] {
     }
     if (ch === "/" && next === "*") {
       state = "blockComment";
+      blockCommentDepth = 1;
       i++;
       continue;
     }

package/src/engine/__tests__/boot-validator-pii-retention.test.ts

@@ -680,7 +680,7 @@ describe("validateBoot — lookupable / blind-index (#818)", () => {
     expect(() => validateBoot([feature])).toThrow(/only apply to text fields/);
   });
 
-  test("searchable combined with a subject annotation throws", () => {
+  test("searchable combined with a subject annotation passes (#1610)", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(
         "user",
@@ -691,7 +691,7 @@ describe("validateBoot — lookupable / blind-index (#818)", () => {
         }),
       );
     });
-    expect(() => validateBoot([feature])).toThrow(/searchable.*cannot work/);
+    expect(() => validateBoot([feature])).not.toThrow();
   });
 
   test("sortable combined with a subject annotation throws", () => {
@@ -705,7 +705,25 @@ describe("validateBoot — lookupable / blind-index (#818)", () => {
         }),
       );
     });
-    expect(() => validateBoot([feature])).toThrow(/sortable.*cannot work/);
+    expect(() => validateBoot([feature])).toThrow(/sortable/);
+  });
+
+  test("searchable combined with sensitive throws (#1610)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "user",
+        createEntity({
+          fields: {
+            passwordHash: createTextField({
+              pii: true,
+              sensitive: true,
+              searchable: true,
+            }),
+          },
+        }),
+      );
+    });
+    expect(() => validateBoot([feature])).toThrow(/sensitive.*searchable/);
   });
 });
 
@@ -758,7 +776,7 @@ describe("validateBoot — piiEncrypted (kumiko-platform#231/#456)", () => {
     expect(() => validateBoot([feature])).toThrow(/piiEncrypted.*without a subject annotation/);
   });
 
-  test("piiEncrypted combined with searchable throws", () => {
+  test("piiEncrypted combined with searchable passes (#1610)", () => {
     const feature = defineFeature("test", (r) => {
       r.entity(
         "tenant",
@@ -774,7 +792,7 @@ describe("validateBoot — piiEncrypted (kumiko-platform#231/#456)", () => {
         }),
       );
     });
-    expect(() => validateBoot([feature])).toThrow(/piiEncrypted.*searchable.*cannot work/);
+    expect(() => validateBoot([feature])).not.toThrow();
   });
 
   test("piiEncrypted combined with sortable throws", () => {
@@ -793,7 +811,7 @@ describe("validateBoot — piiEncrypted (kumiko-platform#231/#456)", () => {
         }),
       );
     });
-    expect(() => validateBoot([feature])).toThrow(/piiEncrypted.*sortable.*cannot work/);
+    expect(() => validateBoot([feature])).toThrow(/sortable/);
   });
 
   test("piiEncrypted without access.read throws (kumiko-platform#460)", () => {

package/src/engine/boot-validator/pii-retention.ts

@@ -129,15 +129,25 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         );
       }
 
-      // Substring-Suche/Sortierung auf Ciphertext ist prinzipbedingt
-      // unmöglich — searchable würde Plaintext-Kopien in den Suchindex
-      // schieben, sortable sortiert Base64-Blobs. Equality → lookupable.
-      if (annotCount > 0 || piiEncryptedFlag.piiEncrypted === true) {
-        const flags = field as { readonly searchable?: boolean; readonly sortable?: boolean }; // @cast-boundary schema-walk
-        if (flags.searchable === true || flags.sortable === true) {
-          const offending = flags.searchable === true ? "searchable" : "sortable";
+      // Sortierung liest die Projection-Spalte — die bleibt Ciphertext, also
+      // sortable + Subject-Annotation bleibt Boot-Fail. searchable ist seit
+      // #1610 erlaubt: der Search-Consumer decryptet in den abgeleiteten
+      // Index und forget purgt die Docs (siehe createSearchEventConsumer).
+      // sensitive + searchable bleibt verboten (nobody-may-read-back).
+      {
+        const flags = field as {
+          readonly searchable?: boolean;
+          readonly sortable?: boolean;
+          readonly sensitive?: boolean;
+        }; // @cast-boundary schema-walk
+        if ((annotCount > 0 || piiEncryptedFlag.piiEncrypted === true) && flags.sortable === true) {
           throw new Error(
-            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation or { piiEncrypted: true } with { ${offending}: true } — ${offending} on encrypted fields cannot work (ciphertext at rest). For equality lookups use { lookupable: true }; for search/sort the field must stay plaintext (allowPlaintext).`,
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation or { piiEncrypted: true } with { sortable: true } — sorting reads the projection column, which is ciphertext at rest. For equality lookups use { lookupable: true }; drop sortable or keep the field plaintext (allowPlaintext).`,
+          );
+        }
+        if (flags.sensitive === true && flags.searchable === true) {
+          throw new Error(
+            `[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines { sensitive: true } with { searchable: true } — sensitive means nobody may read the value back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not.`,
           );
         }
       }

package/src/engine/feature-changelog.ts

@@ -0,0 +1,93 @@
+// Per-feature changelog — each bundled feature has a `changes.json` that
+// tracks breaking changes, improvements, and fixes per version. The CLI
+// (`kumiko upgrade`) reads these to show apps what they need to migrate.
+// All fields should be in English for consistency across the codebase.
+//
+// File I/O stays in the CLI (`bin/commands/upgrade.ts`) — this module is
+// pure parse/validate so engine stays off the node:fs allowlist.
+
+export type ChangelogType = "breaking" | "improvement" | "fix";
+
+export type ChangelogEntry = {
+  readonly version: string;
+  readonly type: ChangelogType;
+  readonly title: string;
+  readonly detail?: string;
+  /** Required when type=breaking. Shown in `kumiko upgrade` output. */
+  readonly migration?: string;
+};
+
+export type FeatureChangelog = {
+  readonly feature: string;
+  readonly entries: readonly ChangelogEntry[];
+};
+
+/** Parse a changes.json body. Callers own file I/O. */
+export function parseFeatureChangelog(raw: string, featureName: string): FeatureChangelog | null {
+  try {
+    const entries = JSON.parse(raw) as unknown;
+    if (!Array.isArray(entries)) return null;
+
+    const validated: ChangelogEntry[] = [];
+    for (const entry of entries) {
+      if (!isChangelogEntry(entry)) continue;
+      validated.push(entry);
+    }
+
+    return { feature: featureName, entries: validated };
+  } catch {
+    return null;
+  }
+}
+
+function isChangelogEntry(value: unknown): value is ChangelogEntry {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj["version"] !== "string") return false;
+  if (!["breaking", "improvement", "fix"].includes(obj["type"] as string)) return false;
+  if (typeof obj["title"] !== "string") return false;
+  return true;
+}
+
+export function validateChangelog(entry: ChangelogEntry): string[] {
+  const errors: string[] = [];
+  if (entry.type === "breaking" && !entry.migration) {
+    errors.push(`breaking change "${entry.title}" missing migration field`);
+  }
+  if (entry.type === "breaking" && entry.migration?.trim() === "") {
+    errors.push(`breaking change "${entry.title}" has empty migration field`);
+  }
+  return errors;
+}
+
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const na = pa[i] ?? 0;
+    const nb = pb[i] ?? 0;
+    if (na > nb) return 1;
+    if (na < nb) return -1;
+  }
+  return 0;
+}
+
+export function filterEntriesAfter(
+  entries: readonly ChangelogEntry[],
+  version: string,
+): readonly ChangelogEntry[] {
+  return entries.filter((e) => compareVersions(e.version, version) > 0);
+}
+
+export function sortEntries(entries: readonly ChangelogEntry[]): readonly ChangelogEntry[] {
+  const order: Record<ChangelogType, number> = {
+    breaking: 0,
+    improvement: 1,
+    fix: 2,
+  };
+  return [...entries].sort((a, b) => {
+    const typeDiff = order[a.type] - order[b.type];
+    if (typeDiff !== 0) return typeDiff;
+    return compareVersions(b.version, a.version);
+  });
+}

package/src/engine/feature-manifest.ts

@@ -8,6 +8,7 @@
 
 import { compareByCodepoint } from "../utils";
 import { isEncryptedAtRest } from "./config-helpers";
+import type { ChangelogEntry } from "./feature-changelog";
 import { qualifyEntityName } from "./qualified-name";
 import type { Registry, UiHints } from "./types/feature";
 
@@ -64,6 +65,9 @@ export type ManifestFeature = {
   readonly uiHints?: UiHints;
   /** Optionaler Herkunfts-Tag (z.B. "enterprise") — gesetzt via Options. */
   readonly tier?: string;
+  /** Per-feature changelog entries (from changes.json). Optional —
+   *  absent when no changes.json exists or feature has no entries. */
+  readonly changelog?: readonly ChangelogEntry[];
 };
 
 export type FeatureManifest = {

package/src/engine/index.ts

@@ -163,6 +163,16 @@ export {
   replacePattern,
   VERSION_HEADER,
 } from "./feature-ast";
+export {
+  type ChangelogEntry,
+  type ChangelogType,
+  compareVersions,
+  type FeatureChangelog,
+  filterEntriesAfter,
+  parseFeatureChangelog,
+  sortEntries,
+  validateChangelog,
+} from "./feature-changelog";
 export {
   type BuildManifestOptions,
   buildManifestFromRegistry,

package/src/jobs/__tests__/scheduler-id.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { schedulerIdForJobName } from "../job-runner";
+
+describe("schedulerIdForJobName", () => {
+  test("strips dots and colons so BullMQ job ids stay under the 5-segment legacy heuristic", () => {
+    // Job id becomes repeat:<id>:<millis> — colons in <id> previously pushed
+    // the segment count to ≥5 and leaked a permanent hash per cron tick
+    // (fw#1603 / bullmq#3828).
+    const id = schedulerIdForJobName("publicstatus:job:uptime-probe");
+    expect(id).toBe("scheduler-publicstatus-job-uptime-probe");
+    expect(id.includes(":")).toBe(false);
+    expect(`repeat:${id}:1784992080000`.split(":").length).toBeLessThan(5);
+  });
+
+  test("still collapses dotted QNs", () => {
+    expect(schedulerIdForJobName("app.job.tick")).toBe("scheduler-app-job-tick");
+  });
+});

package/src/jobs/index.ts

@@ -1,2 +1,2 @@
 export type { JobLogEntry, JobMeta, JobRunner, JobRunnerOptions } from "./job-runner";
-export { createJobRunner } from "./job-runner";
+export { createJobRunner, schedulerIdForJobName } from "./job-runner";

package/src/jobs/job-runner.ts

@@ -34,6 +34,22 @@ function queueNameFor(prefix: string, lane: JobRunIn): string {
   return `${prefix}-${lane}`;
 }
 
+/**
+ * BullMQ job ids are `repeat:<schedulerId>:<millis>`. Colons inside the
+ * scheduler id push the segment count to ≥5, which BullMQ's legacy heuristic
+ * treated as old repeatables — spawning a new scheduler entry every tick and
+ * leaking permanent `repeat:*` hashes (taskforcesh/bullmq#3828, fw#1603 /
+ * publicstatus Redis OOM). Strip `.` and `:` from the job QN.
+ */
+export function schedulerIdForJobName(jobName: string): string {
+  return `scheduler-${jobName.replace(/[.:]/g, "-")}`;
+}
+
+/** Pre-sanitize id (`.` only) — remove on boot so colon-form ghosts die. */
+function legacySchedulerIdForJobName(jobName: string): string {
+  return `scheduler-${jobName.replace(/\./g, "-")}`;
+}
+
 export type JobLogEntry = {
   level: "info" | "warn" | "error";
   message: string;
@@ -473,12 +489,26 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       for (const [name, jobDef] of allJobs) {
         if (laneForJob(jobDef) !== consumerLane) continue;
         if ("cron" in jobDef.trigger) {
+          const schedulerId = schedulerIdForJobName(name);
+          const legacyId = legacySchedulerIdForJobName(name);
+          // Drop pre-sanitize scheduler ids so colon-form ghosts stop firing.
+          if (legacyId !== schedulerId) {
+            try {
+              await consumerQueue.removeJobScheduler(legacyId);
+            } catch {
+              // skip: legacy scheduler absent (fresh install / already purged)
+            }
+          }
           await consumerQueue.upsertJobScheduler(
-            `scheduler-${name.replace(/\./g, "-")}`,
+            schedulerId,
             { pattern: jobDef.trigger.cron },
             {
               name: jobDef.perTenant ? `_perTenant:${name}` : name,
               data: {},
+              opts: {
+                removeOnComplete: { count: 100 },
+                removeOnFail: { count: 50 },
+              },
             },
           );
         }

package/src/pipeline/dispatch-stream.ts

@@ -59,9 +59,12 @@ async function* executeStreamInner(
   const invalidated = new Promise<void>((resolve) => {
     resolveInvalidated = resolve;
   });
-  const unsubscribeAccessInvalidation = ctx.sseBroker?.subscribeAccessInvalidation(user.id, () => {
-    resolveInvalidated?.();
-  });
+  const unsubscribeAccessInvalidation = ctx.sseBroker?.subscribeAccessInvalidation?.(
+    user.id,
+    () => {
+      resolveInvalidated?.();
+    },
+  );
 
   let iterator: AsyncIterator<unknown> | undefined;
   // When access is revoked mid-pull, `iterator.next()` is still in flight.

package/src/pipeline/system-hooks.ts

@@ -1,4 +1,11 @@
 import type { SseBroker } from "../api/sse-broker";
+import {
+  collectSearchableSubjectFields,
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+} from "../crypto";
 import type { DbRow } from "../db/connection";
 import { tenantChannel } from "../engine/constants";
 import type { EntityId, JobRunnerRef, Registry, SessionUser } from "../engine/types";
@@ -53,10 +60,9 @@ export function createSearchEventConsumer(
       const verb = event.type.split(".").pop();
       const tenantId = event.tenantId;
 
-      // skip: delete takes an early-return after removing the index entry —
-      // the "reconstruct state" path below only makes sense for created/
-      // updated/restored, which carry field data in the payload.
-      if (verb === "deleted") {
+      // skip: delete/forgotten remove the index entry — reconstruct only
+      // makes sense for created/updated/restored (field data in payload).
+      if (verb === "deleted" || verb === "forgotten") {
         await searchAdapter.remove(tenantId, entityName, event.aggregateId);
         return;
       }
@@ -68,7 +74,13 @@ export function createSearchEventConsumer(
         return;
       }
 
-      const state = reconstructStateForSearch(event.payload, verb);
+      let state = reconstructStateForSearch(event.payload, verb);
+      state = await decryptSearchableSubjectFields(entityName, state, registry);
+      // skip: erased subject — drop the doc so a rebuild cannot resurrect plaintext.
+      if (hasErasedSearchableSubjectField(entityName, state, registry)) {
+        await searchAdapter.remove(tenantId, entityName, event.aggregateId);
+        return;
+      }
       const doc = await buildSearchDocument(entityName, event.aggregateId, state, registry);
       if (!doc) {
         // skip: entity isn't searchable (no searchable fields declared)
@@ -79,6 +91,41 @@ export function createSearchEventConsumer(
   };
 }
 
+// #1610 — subject-annotated searchable fields are ciphertext in the event
+// payload; decrypt into the derived index only. No KMS → omit ciphertext
+// values rather than indexing blobs.
+async function decryptSearchableSubjectFields(
+  entityName: string,
+  state: Record<string, unknown>,
+  registry: Registry,
+): Promise<Record<string, unknown>> {
+  const entity = registry.getEntity(entityName);
+  if (!entity) return state;
+  const fields = collectSearchableSubjectFields(entity);
+  if (fields.length === 0) return state;
+  const kms = configuredPiiSubjectKms();
+  if (!kms) {
+    const out = { ...state };
+    for (const name of fields) {
+      if (isPiiCiphertext(out[name])) delete out[name];
+    }
+    return out;
+  }
+  return decryptPiiFieldValues(state, fields, kms, {
+    requestId: "system:consumer:search",
+  });
+}
+
+function hasErasedSearchableSubjectField(
+  entityName: string,
+  state: Record<string, unknown>,
+  registry: Registry,
+): boolean {
+  const entity = registry.getEntity(entityName);
+  if (!entity) return false;
+  return collectSearchableSubjectFields(entity).some((name) => state[name] === PII_ERASED_SENTINEL);
+}
+
 // Rebuild the entity-state a search index needs from the event-payload alone.
 // Three shapes to handle — see event-store-executor.ts for the emitter side.
 function reconstructStateForSearch(
@@ -369,7 +416,7 @@ export function createAccessInvalidationEventConsumer(sseBroker: SseBroker): Eve
         // poison would otherwise permanently stop access-invalidation for
         // every user behind one bad row).
         if (typeof userId !== "string" || userId.length === 0) return;
-        sseBroker.publishAccessInvalidation(userId);
+        sseBroker.publishAccessInvalidation?.(userId);
       }
 
       if (
@@ -380,7 +427,7 @@ export function createAccessInvalidationEventConsumer(sseBroker: SseBroker): Eve
         // skip: previous snapshot missing/malformed userId — same fail-open
         // reasoning as above.
         if (userId === undefined) return;
-        sseBroker.publishAccessInvalidation(userId);
+        sseBroker.publishAccessInvalidation?.(userId);
       }
     },
   };

package/src/schema-cli.ts

@@ -273,11 +273,10 @@ export async function runSchemaCli(
 
       // 3. Migration-content drift — replay the committed *.sql files and
       // diff the reconstructed schema against .snapshot.json.
-      const committedSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
-      if (existsSync(migrationsDir) && committedSnapshot !== null) {
+      if (existsSync(migrationsDir) && prevSnapshot !== null) {
         try {
           const replayed = replayMigrationsDir(migrationsDir);
-          const mismatches = diffReplayAgainstSnapshot(replayed, committedSnapshot);
+          const mismatches = diffReplayAgainstSnapshot(replayed, prevSnapshot);
           if (mismatches.length === 0) {
             out.log("  ✓ migrations: table/column names match .snapshot.json");
           } else {

package/src/search/__tests__/search-pii-derived-index.integration.test.ts

@@ -0,0 +1,164 @@
+// fw#1610 — subject-annotated searchable fields: ciphertext in events,
+// plaintext in derived search index, purged on subject erase.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  configurePiiSubjectKms,
+  InMemoryKmsAdapter,
+  isPiiCiphertext,
+  resetPiiSubjectKmsForTests,
+  subjectIdToKey,
+} from "../../crypto";
+import { asRawClient, buildEntityTable, createEventStoreExecutor, createTenantDb } from "../../db";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import { createEventsTable } from "../../event-store";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { purgeSearchDocumentsForSubject } from "../purge-subject";
+
+const contactEntity = createEntity({
+  table: "read_search_pii_contacts",
+  fields: {
+    // pii: true → subject = entity id (self). searchable via derived index.
+    label: createTextField({ required: true, maxLength: 100, pii: true, searchable: true }),
+    note: createTextField({ required: true, maxLength: 100, searchable: true }),
+  },
+});
+
+const contactTable = buildEntityTable("contact", contactEntity);
+
+const contactFeature = defineFeature("search-pii-probe", (r) => {
+  r.entity("contact", contactEntity);
+});
+
+let stack: TestStack;
+let kms: InMemoryKmsAdapter;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [contactFeature] });
+  await unsafeCreateEntityTable(stack.db, contactEntity, "contact");
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  kms = new InMemoryKmsAdapter();
+  configurePiiSubjectKms(kms);
+});
+
+afterEach(() => {
+  resetPiiSubjectKmsForTests();
+});
+
+function executor() {
+  return createEventStoreExecutor(contactTable, contactEntity, {
+    entityName: "contact",
+    searchAdapter: stack.search,
+  });
+}
+
+function tenantDb() {
+  return createTenantDb(stack.db, admin.tenantId, "system");
+}
+
+describe("searchable PII derived index (#1610)", () => {
+  test("create indexes plaintext; event payload stays ciphertext; erase purges search", async () => {
+    const plain = "UniqueSearchPiiLabel1610";
+    const created = await executor().create(
+      { label: plain, note: "public-note" },
+      admin,
+      tenantDb(),
+    );
+    if (!created.isSuccess) throw new Error("create failed");
+    const id = String(created.data.id);
+
+    const events = await asRawClient(stack.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE aggregate_id = $1 AND type = 'contact.created' LIMIT 1`,
+      [id],
+    );
+    const payload = (events as { payload: Record<string, unknown> }[])[0]?.payload;
+    expect(isPiiCiphertext(payload?.["label"])).toBe(true);
+    expect(payload?.["label"]).not.toBe(plain);
+
+    await stack.eventDispatcher?.runOnce();
+
+    const hits = await stack.search.search(admin.tenantId, plain, { filterType: "contact" });
+    expect(hits.some((h) => String(h.entityId) === id)).toBe(true);
+
+    // pii: true → subject key is the entity id itself.
+    const subject = { kind: "user" as const, userId: id };
+    await kms.eraseKey(subject);
+    await purgeSearchDocumentsForSubject(
+      stack.db,
+      stack.registry.features,
+      stack.search,
+      subjectIdToKey(subject),
+      subject,
+    );
+
+    const after = await stack.search.search(admin.tenantId, plain, { filterType: "contact" });
+    expect(after.some((h) => String(h.entityId) === id)).toBe(false);
+  });
+
+  test("consumer treats erased decrypt as remove (no sentinel index)", async () => {
+    const plain = "SentinelRebuildLabel1610";
+    const created = await executor().create({ label: plain, note: "x" }, admin, tenantDb());
+    if (!created.isSuccess) throw new Error("create failed");
+    const id = String(created.data.id);
+
+    await stack.eventDispatcher?.runOnce();
+    expect(
+      (await stack.search.search(admin.tenantId, plain, { filterType: "contact" })).some(
+        (h) => String(h.entityId) === id,
+      ),
+    ).toBe(true);
+
+    await kms.eraseKey({ kind: "user", userId: id });
+    // Force re-index path by updating a non-PII field — consumer decrypts
+    // label → [[erased]] → remove.
+    const updated = await executor().update(
+      { id: created.data.id, changes: { note: "y" } },
+      admin,
+      tenantDb(),
+      { skipOptimisticLock: true },
+    );
+    if (!updated.isSuccess) throw new Error("update failed");
+    await stack.eventDispatcher?.runOnce();
+
+    const after = await stack.search.search(admin.tenantId, plain, { filterType: "contact" });
+    expect(after.some((h) => String(h.entityId) === id)).toBe(false);
+  });
+  test("purge finds rows after anonymize rewrote ciphertext (#1610 bugbot)", async () => {
+    const plain = "AnonymizedStillPurge1610";
+    const created = await executor().create({ label: plain, note: "n" }, admin, tenantDb());
+    if (!created.isSuccess) throw new Error("create failed");
+    const id = String(created.data.id);
+    await stack.eventDispatcher?.runOnce();
+    expect(
+      (await stack.search.search(admin.tenantId, plain, { filterType: "contact" })).some(
+        (h) => String(h.entityId) === id,
+      ),
+    ).toBe(true);
+
+    // Simulate forget-cleanup anonymize: overwrite searchable PII with plaintext.
+    await asRawClient(stack.db).unsafe(
+      `UPDATE read_search_pii_contacts SET label = $1 WHERE id = $2`,
+      ["[[erased]]", id],
+    );
+
+    const subject = { kind: "user" as const, userId: id };
+    await purgeSearchDocumentsForSubject(
+      stack.db,
+      stack.registry.features,
+      stack.search,
+      subjectIdToKey(subject),
+      subject,
+    );
+
+    const after = await stack.search.search(admin.tenantId, plain, { filterType: "contact" });
+    expect(after.some((h) => String(h.entityId) === id)).toBe(false);
+  });
+});

package/src/search/index.ts

@@ -3,6 +3,7 @@
 // von SearchAdapter-Types. Apps die Meilisearch nicht nutzen, ziehen den
 // Client-Code nicht mit rein.
 export { createInMemorySearchAdapter } from "./in-memory-adapter";
+export { purgeSearchDocumentsForSubject } from "./purge-subject";
 export type {
   ReindexEntityFailure,
   ReindexEntityOptions,

package/src/search/purge-subject.ts

@@ -0,0 +1,135 @@
+// Purge derived search documents for an erased PII subject (#1610).
+//
+// After kms.eraseKey the projection/event ciphertext is unreadable, but Meili
+// still holds the plaintext that createSearchEventConsumer decrypted into the
+// index. Discovery is dual-path:
+//   1. Ownership: pii self-id / userOwned.ownerField / tenantOwned.tenantId
+//      (survives anonymize hooks that overwrite ciphertext with plaintext).
+//   2. Ciphertext LIKE prefix (same as nullBlindIndexesForSubject) for rows
+//      that still carry the subject key in encrypted columns.
+
+import type { SubjectId } from "../crypto/kms-adapter";
+import { collectSearchableSubjectFields } from "../crypto/subject-resolver";
+import type { DbRunner } from "../db/connection";
+import { resolveTableName } from "../db/entity-table-meta";
+import { executeRawQuery } from "../db/queries/raw-sql";
+import type { FeatureDefinition } from "../engine/types";
+import type { EntityDefinition } from "../engine/types/fields";
+import type { EntityId, TenantId } from "../engine/types/identifiers";
+import { toSnakeCase } from "../utils/case";
+import type { SearchAdapter } from "./types";
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+function escapeLikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, (m) => `\\${m}`);
+}
+
+/** Build OR predicates for rows owned by `subject` (id / ownerField / tenant_id). */
+function ownershipPredicates(
+  entity: EntityDefinition,
+  searchableFields: readonly string[],
+  subject: SubjectId,
+  nextParam: () => number,
+): { sql: string; params: unknown[] } | null {
+  const parts: string[] = [];
+  const params: unknown[] = [];
+  let selfIdN: number | undefined;
+  let tenantIdN: number | undefined;
+  const ownerFieldN = new Map<string, number>();
+
+  for (const fieldName of searchableFields) {
+    const field = entity.fields[fieldName];
+    if (!field) continue;
+    if (subject.kind === "user") {
+      if ("userOwned" in field && field.userOwned !== undefined) {
+        const col = toSnakeCase(field.userOwned.ownerField);
+        let n = ownerFieldN.get(col);
+        if (n === undefined) {
+          n = nextParam();
+          ownerFieldN.set(col, n);
+          params.push(subject.userId);
+          parts.push(`${quoteIdent(col)} = $${n}`);
+        }
+      } else if ("pii" in field && field.pii === true && selfIdN === undefined) {
+        selfIdN = nextParam();
+        params.push(subject.userId);
+        parts.push(`${quoteIdent("id")} = $${selfIdN}`);
+      }
+    } else if ("tenantOwned" in field && field.tenantOwned === true && tenantIdN === undefined) {
+      tenantIdN = nextParam();
+      params.push(subject.tenantId);
+      parts.push(`${quoteIdent("tenant_id")} = $${tenantIdN}`);
+    }
+  }
+  if (parts.length === 0) return null;
+  return { sql: parts.join(" OR "), params };
+}
+
+export async function purgeSearchDocumentsForSubject(
+  db: DbRunner,
+  features: ReadonlyMap<string, FeatureDefinition>,
+  search: SearchAdapter,
+  subjectKey: string,
+  /** When set, also match rows by ownership — needed after anonymize rewrites ciphertext. */
+  subject?: SubjectId,
+): Promise<void> {
+  const likePattern = `kumiko-pii:v%:${escapeLikePattern(subjectKey)}:%`;
+  const byTenant = new Map<string, { entityType: string; entityId: EntityId }[]>();
+  const seen = new Set<string>();
+
+  for (const feature of features.values()) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+      const fields = collectSearchableSubjectFields(entity);
+      if (fields.length === 0) continue;
+      const tableName = resolveTableName(entityName, entity, undefined);
+
+      let paramIdx = 0;
+      const nextParam = () => ++paramIdx;
+      const params: unknown[] = [];
+      const orParts: string[] = [];
+
+      const likeN = nextParam();
+      params.push(likePattern);
+      orParts.push(
+        `(${fields.map((f) => `${quoteIdent(toSnakeCase(f))} LIKE $${likeN}`).join(" OR ")})`,
+      );
+
+      if (subject) {
+        const owned = ownershipPredicates(entity, fields, subject, nextParam);
+        if (owned) {
+          params.push(...owned.params);
+          orParts.push(`(${owned.sql})`);
+        }
+      }
+
+      const rows = await executeRawQuery<{ id: string; tenant_id: string }>(
+        db,
+        `SELECT id, tenant_id FROM ${quoteIdent(tableName)} WHERE ${orParts.join(" OR ")}`,
+        params,
+      );
+      for (const row of rows) {
+        const key = `${row.tenant_id}:${entityName}:${row.id}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const list = byTenant.get(row.tenant_id) ?? [];
+        list.push({ entityType: entityName, entityId: row.id as EntityId });
+        byTenant.set(row.tenant_id, list);
+      }
+    }
+  }
+
+  for (const [tenantId, items] of byTenant) {
+    if (items.length === 0) continue;
+    const tid = tenantId as TenantId;
+    if (search.removeBatch) {
+      await search.removeBatch(tid, items);
+    } else {
+      for (const item of items) {
+        await search.remove(tid, item.entityType, item.entityId);
+      }
+    }
+  }
+}

package/src/testing/__tests__/wait-for.test.ts

@@ -2,15 +2,18 @@ import { describe, expect, test } from "bun:test";
 import { waitFor } from "../wait-for";
 
 describe("waitFor", () => {
-  test("returns immediately once fn succeeds on the first attempt", async () => {
+  test("calls fn exactly once when it passes on the first attempt (no prior sleep)", async () => {
     let calls = 0;
+    const started = Date.now();
     await waitFor(
       () => {
         calls++;
       },
-      { delays: [1, 1, 1] },
+      { delays: [200, 200, 200] },
     );
     expect(calls).toBe(1);
+    // try-first: must not burn the first delay when the condition already holds
+    expect(Date.now() - started).toBeLessThan(100);
   });
 
   test("retries on failure and succeeds once fn passes", async () => {
@@ -35,8 +38,9 @@ describe("waitFor", () => {
         },
         { delays: [1, 1] },
       ),
-    ).rejects.toThrow("fail-2");
-    expect(calls).toBe(2);
+    ).rejects.toThrow("fail-3");
+    // N delays → N+1 attempts (final try after the last backoff)
+    expect(calls).toBe(3);
   });
 
   test("throws a descriptive error for an empty delay schedule", async () => {

package/src/testing/wait-for.ts

@@ -1,8 +1,10 @@
 /**
  * Polls a condition with escalating timeouts.
  *
- * Default schedule: 250ms → 1s → 3s (3 attempts).
- * Returns immediately on success. Throws the last assertion error if all attempts fail.
+ * Default schedule: 250ms → 1s → 3s between attempts. Tries first (already-true
+ * returns immediately), then sleeps `delays[i]` after each failure before the
+ * next try — so N delays yield N+1 attempts and the full backoff budget.
+ * Throws the last assertion error if all attempts fail.
  *
  * Usage:
  *   await waitFor(() => {
@@ -19,15 +21,18 @@ export async function waitFor(
   }
   let lastError: unknown;
 
-  for (let i = 0; i < delays.length; i++) {
-    await new Promise((r) => setTimeout(r, delays[i]));
+  for (let i = 0; ; i++) {
     try {
       await fn();
-      // skip: retry attempt succeeded, no further polling needed
+      // skip: condition already true — no further polling
       return;
     } catch (err) {
       lastError = err;
     }
+    if (i >= delays.length) {
+      break;
+    }
+    await new Promise((r) => setTimeout(r, delays[i]));
   }
 
   throw lastError;