@cosmicdrift/kumiko-framework 0.174.0 → 0.176.0

package/src/engine/boot-validator/access-roles.ts

@@ -1,32 +1,74 @@
+import { normalizeAccessEntry } from "../ownership";
 import type { FeatureDefinition } from "../types";
 
 const BUILTIN_ROLES = new Set(["all", "system"]);
 
+function addRole(roleHandlers: Map<string, Set<string>>, role: string, identifier: string): void {
+  let handlers = roleHandlers.get(role);
+  if (!handlers) {
+    handlers = new Set();
+    roleHandlers.set(role, handlers);
+  }
+  handlers.add(identifier);
+}
+
+function addHandlerRoles(roleHandlers: Map<string, Set<string>>, f: FeatureDefinition): void {
+  const handlerGroups = [
+    { type: "write", defs: f.writeHandlers },
+    { type: "query", defs: f.queryHandlers },
+    { type: "stream", defs: f.streamHandlers },
+  ] as const;
+
+  for (const { type, defs } of handlerGroups) {
+    for (const [handlerName, def] of Object.entries(defs)) {
+      if (!def.access || !("roles" in def.access)) continue;
+      const identifier = `${f.name}:${type}:${handlerName}`;
+      for (const role of def.access.roles) {
+        addRole(roleHandlers, role, identifier);
+      }
+    }
+  }
+}
+
+function addConfigKeyRoles(roleHandlers: Map<string, Set<string>>, f: FeatureDefinition): void {
+  for (const [key, keyDef] of Object.entries(f.configKeys ?? {})) {
+    const identifier = `${f.name}:config:${key}`;
+    for (const role of [...keyDef.access.read, ...keyDef.access.write]) {
+      addRole(roleHandlers, role, identifier);
+    }
+  }
+}
+
+function addEntityFieldRoles(roleHandlers: Map<string, Set<string>>, f: FeatureDefinition): void {
+  for (const [entityName, entity] of Object.entries(f.entities ?? {})) {
+    for (const [fieldName, field] of Object.entries(entity.fields)) {
+      const identifier = `${f.name}:entity:${entityName}.${fieldName}`;
+      const readRoles = Object.keys(normalizeAccessEntry(field.access?.read) ?? {});
+      const writeRoles = Object.keys(normalizeAccessEntry(field.access?.write) ?? {});
+      for (const role of [...readRoles, ...writeRoles]) {
+        addRole(roleHandlers, role, identifier);
+      }
+    }
+  }
+}
+
+// A single "exactly one handler" heuristic over-counts by construction:
+// legitimate fine-grained roles (a role scoped to one admin endpoint on
+// purpose) are the normal case, not a typo — and until every access
+// surface is scanned, a role can look unique here while it's really used
+// elsewhere (configKeys / entity+field access), a false positive in the
+// other direction. Both is why this stays opt-in (#1711) rather than a
+// default-on prod warning.
 export function warnOnUniqueAccessRoles(features: readonly FeatureDefinition[]): void {
-  // role → set of distinct handler identifiers using it
+  // role → set of distinct identifiers using it, across every access
+  // surface — write/query/stream handlers, config-key access, and
+  // entity/field-level access rules.
   const roleHandlers = new Map<string, Set<string>>();
 
   for (const f of features) {
-    const handlerGroups = [
-      { type: "write", defs: f.writeHandlers },
-      { type: "query", defs: f.queryHandlers },
-      { type: "stream", defs: f.streamHandlers },
-    ] as const;
-
-    for (const { type, defs } of handlerGroups) {
-      for (const [handlerName, def] of Object.entries(defs)) {
-        if (!def.access || !("roles" in def.access)) continue;
-        const identifier = `${f.name}:${type}:${handlerName}`;
-        for (const role of def.access.roles) {
-          let handlers = roleHandlers.get(role);
-          if (!handlers) {
-            handlers = new Set();
-            roleHandlers.set(role, handlers);
-          }
-          handlers.add(identifier);
-        }
-      }
-    }
+    addHandlerRoles(roleHandlers, f);
+    addConfigKeyRoles(roleHandlers, f);
+    addEntityFieldRoles(roleHandlers, f);
   }
 
   for (const [role, handlers] of roleHandlers) {

package/src/engine/boot-validator/entity-handler.ts

@@ -61,9 +61,12 @@ export const PII_USER_OWNED_NAME_HINTS: ReadonlySet<string> = new Set([
 export const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string> = new Set([
   "authorid",
   "assigneeid",
+  "assigneeuserid",
   "ownerid",
+  "createdby",
   "createdbyid",
   "createdbyuserid",
+  "updatedby",
   "updatedbyid",
   "updatedbyuserid",
   "invitedby",
@@ -72,6 +75,7 @@ export const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string> = new Set([
   "uploadedby",
   "assignedto",
   "reportedby",
+  "memberid",
 ]);
 
 // --- Extension preSave wiring validation ---

package/src/engine/boot-validator/index.ts

@@ -61,11 +61,24 @@ export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns";
 // dieselbe Extraktionslogik.
 export { collectWriteHandlerQns } from "./nav";
 
+export type ValidateBootOptions = {
+  /** Warn when an access role is used by exactly one handler/config-key/
+   *  field across the whole boot scan — often a typo, but also the normal
+   *  shape of a legitimate fine-grained role (one role scoped to one admin
+   *  endpoint on purpose). Opt-in (default false, #1711): a default-on
+   *  prod warning that nobody can silence per-role isn't worth the noise
+   *  it generates on every boot. */
+  readonly warnOnUniqueAccessRoles?: boolean;
+};
+
 /**
  * Validates all feature configurations at boot time.
  * Throws on the first error found — fail fast.
  */
-export function validateBoot(features: readonly FeatureDefinition[]): void {
+export function validateBoot(
+  features: readonly FeatureDefinition[],
+  options?: ValidateBootOptions,
+): void {
   const featureMap = new Map<string, FeatureDefinition>();
   for (const f of features) {
     featureMap.set(f.name, f);
@@ -213,5 +226,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
 
   validateConfigReads(features, allConfigKeys);
   warnOnToggleableDependencies(features, featureMap);
-  warnOnUniqueAccessRoles(features);
+  if (options?.warnOnUniqueAccessRoles === true) {
+    warnOnUniqueAccessRoles(features);
+  }
 }

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

@@ -21,6 +21,13 @@ const FRAMEWORK_TIMESTAMP_FIELDS: ReadonlySet<string> = new Set([
 // werden statt erst beim ersten Cleanup-Run.
 const KEEP_FOR_PATTERN = /^\d+[hdwmy]$/;
 
+// A field carries a subject binding — pii/userOwned/tenantOwned mark
+// annotated content, subjectRef marks a bare FK into `user` with no
+// annotated content of its own but the same Art.17 obligations (#1645).
+function hasSubjectAnnotation(annot: PiiAnnotations): boolean {
+  return Boolean(annot.pii || annot.userOwned || annot.tenantOwned || annot.subjectRef);
+}
+
 // --- PII / Subject-Key Annotations + Retention validation ---
 //
 // Drei Klassen von Checks:
@@ -133,11 +140,12 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         );
       }
 
-      // 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).
+      // Sorting reads the projection column — that stays ciphertext, so
+      // sortable + subject annotation stays a boot-fail. searchable has
+      // been allowed since #1610: the search consumer decrypts into the
+      // derived index and forget purges those docs (see
+      // createSearchEventConsumer). sensitive + searchable stays forbidden
+      // (nobody-may-read-back).
       {
         const flags = field as {
           readonly searchable?: boolean;
@@ -215,7 +223,7 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
         } else if (PII_USER_REFERENCE_NAME_HINTS.has(lower) && !annot.subjectRef) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
-            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no { subjectRef: true } annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { subjectRef: true }, or { userOwned: { ownerField: "${fieldName}" } } on the field it owns. If business data, set { allowPlaintext: "..." } to silence.`,
+            `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no { subjectRef: true } annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { subjectRef: true } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) — without the hook the V3 boot guard throws. Or { userOwned: { ownerField: "${fieldName}" } } on the field it owns. If business data, set { allowPlaintext: "..." } to silence.`,
           );
         }
       }
@@ -245,10 +253,9 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
       if (retention.strategy === "blockDelete") {
         // blockDelete on an entity with no subject field is the correct
         // "never auto-delete" choice; User-Forget never reaches those rows (#1622).
-        const hasSubjectField = Object.values(fieldsByName).some((f) => {
-          const a = f as PiiAnnotations; // @cast-boundary schema-walk
-          return Boolean(a.pii || a.userOwned || a.tenantOwned);
-        });
+        const hasSubjectField = Object.values(fieldsByName).some(
+          (f) => hasSubjectAnnotation(f as PiiAnnotations), // @cast-boundary schema-walk
+        );
         const hasAnonymize = Object.values(fieldsByName).some((f) => {
           const a = f as PiiAnnotations; // @cast-boundary schema-walk
           return Boolean(a.anonymize);

package/src/engine/boot-validator/screens.ts

@@ -36,8 +36,16 @@ function validateRowActionNavigateParams(
 ): void {
   // skip: not a navigate-with-params action — nothing to validate here.
   if (action.kind !== "navigate" || action.params === undefined) return;
-  // skip: unresolvable/custom target already reported (or exempt) elsewhere.
-  if (target === undefined || target.screen.type === "custom") return;
+  // entityList/projectionList targets also read URL search params (Tier
+  // 2.7c filter-prefill, see use-list-url-state.ts: `<screenId>.q/.sort/
+  // .dir/.page/.f.<field>`), not just actionForm/entityEdit-create.
+  const exemptTargetType =
+    target === undefined ||
+    target.screen.type === "custom" ||
+    target.screen.type === "entityList" ||
+    target.screen.type === "projectionList";
+  // skip: unresolvable/custom/list target already reported (or exempt) elsewhere.
+  if (exemptTargetType) return;
 
   const isEntityEditUpdate =
     target.screen.type === "entityEdit" &&

package/src/engine/boot-validator.ts

@@ -1,5 +1,6 @@
 export {
   collectWriteHandlerQns,
+  type ValidateBootOptions,
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "./boot-validator/index";

package/src/engine/create-app.ts

@@ -1,4 +1,4 @@
-import { validateBoot } from "./boot-validator";
+import { type ValidateBootOptions, validateBoot } from "./boot-validator";
 import { createRegistry } from "./registry";
 import type { FeatureDefinition, Registry } from "./types";
 import { DEFAULT_CURRENCIES } from "./types";
@@ -8,6 +8,8 @@ export type AppConfig = {
   features: readonly FeatureDefinition[];
   softDelete?: boolean; // Global default for all entities (default: true)
   currencies?: readonly string[]; // Extends DEFAULT_CURRENCIES
+  /** Opt-in boot-validator warnings — see ValidateBootOptions. */
+  validateBootOptions?: ValidateBootOptions;
 };
 
 export type App = {
@@ -98,7 +100,7 @@ export function createApp(config: AppConfig): App {
   }
 
   // Run boot-time validation before creating registry
-  validateBoot(config.features);
+  validateBoot(config.features, config.validateBootOptions);
 
   return {
     registry: createRegistry(config.features),

package/src/engine/index.ts

@@ -205,6 +205,8 @@ export type { OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule } from
 export {
   buildOwnershipClause,
   from,
+  normalizeAccessEntry,
+  userCanCreateFieldRow,
   userCanReadFieldRow,
   userCanWriteFieldRow,
 } from "./ownership";

package/src/engine/ownership.ts

@@ -158,6 +158,12 @@ export function userCanReadFieldRow(
   for (const role of user.roles) {
     const rule = accessMap[role];
     if (!rule) continue;
+    // where-rules are entity-level SQL predicates (buildOwnershipClause);
+    // matchesRule can't evaluate them in-memory and throws. Field-level
+    // access is boot-validator-rejected for where-rules, but this function
+    // is also reachable from hand-rolled entity-level reads.
+    // skip: where-rules are SQL-layer only — fail closed instead of throwing.
+    if (rule !== "all" && rule.kind === "where") continue;
     if (matchesRule(rule, user, row)) return true;
   }
   return false;
@@ -180,6 +186,8 @@ export function userCanWriteFieldRow(
     const rule = accessMap[role];
     if (!rule) continue;
     if (rule === "all") return true;
+    // skip: where-rules are SQL-layer only — fail closed instead of throwing.
+    if (rule.kind === "where") continue;
     if (matchesRule(rule, user, oldRow) && matchesRule(rule, user, newRow)) return true;
   }
   return false;
@@ -272,6 +280,17 @@ export function shiftParams(fragment: SqlFragment, shift: number): SqlFragment {
 // SQL names via the kumiko:schema:Columns symbol. Unknown column on a from-rule
 // is a boot-time misconfiguration; at request time we treat it as empty
 // (safe default) rather than passing silently.
+//
+// Caller obligations (fw#1700) — this function returns ONLY the ownership
+// fragment, not the full row-access contract. A raw-SQL caller (not going
+// through `ctx.db`, which already applies all three) must additionally:
+//   1. Pass `paramStart` as `params.length + 1` for its own already-bound
+//      params, or `$N` placeholders in the returned fragment silently splice
+//      into the wrong query params.
+//   2. Apply tenant + soft-delete scoping itself (event-store-executor-read.ts
+//      does this outside `buildOwnershipClause`) — this function does not.
+//   3. Treat `kind: "empty"` (see `OwnershipClause`) as a hard DENY, and
+//      `kind: "pass"` as an explicit bypass — not as "no additional filter".
 export function buildOwnershipClause(
   user: SessionUser,
   accessMap: OwnershipMap | undefined,

package/src/engine/schema-builder.ts

@@ -55,7 +55,17 @@ function embeddedSubFieldToZod(subField: EmbeddedSubFieldDef): z.ZodTypeAny {
   }
 }
 
-export function fieldToZod(field: FieldDefinition, currencies: readonly string[]): z.ZodTypeAny {
+export function fieldToZod(
+  field: FieldDefinition,
+  currencies: readonly string[],
+  opts: { readonly applyDefaults?: boolean } = {},
+): z.ZodTypeAny {
+  // Insert callers want `.default(...)` applied so an omitted field falls
+  // back to it; buildUpdateSchema passes applyDefaults: false so an omitted
+  // field on update stays omitted (a `{ title }` patch must not clobber
+  // other columns with their defaults) while a field's own default value is
+  // still known here for "" → default mapping (select case below).
+  const applyDefaults = opts.applyDefaults ?? true;
   switch (field.type) {
     case "text": {
       let schema = z.string();
@@ -63,7 +73,7 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       if (field.format === "email") schema = schema.email();
       if (field.format === "url") schema = schema.url();
       if (field.required) schema = schema.min(1);
-      return field.default !== undefined ? schema.default(field.default) : schema;
+      return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
     }
     case "longText": {
       // longText hat keine `format`-Variante (per type-design). Nur
@@ -71,24 +81,32 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       let schema = z.string();
       if (field.maxLength) schema = schema.max(field.maxLength);
       if (field.required) schema = schema.min(1);
-      return field.default !== undefined ? schema.default(field.default) : schema;
+      return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
     }
     case "boolean": {
       const schema = z.boolean();
-      return field.default !== undefined ? schema.default(field.default) : schema;
+      return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
     }
     case "select": {
       const [first, ...rest] = field.options;
       if (!first) return z.string();
       const enumSchema = z.enum([first, ...rest]);
-      if (field.default !== undefined)
+      if (field.default !== undefined) {
         // Untouched <select> sends "" too; with a default that maps to the
         // default (same semantics as undefined) instead of the invalid-value
-        // rejection from #1702. A field with a default is never "unset".
-        return z.preprocess(
-          (value) => (value === "" ? field.default : value),
-          enumSchema.default(field.default),
+        // rejection from #1702. A field with a default is never "unset" —
+        // true on both insert AND update, so this branch (and its "" → default
+        // mapping) fires regardless of applyDefaults; only the `.default(...)`
+        // schema-level fallback for OMITTED input is update-gated below.
+        // `null` maps the same way: the no-default branch below normalizes
+        // an untouched select to null, and a client that reuses that value
+        // against a since-defaulted field must not get rejected either.
+        const mapped = z.preprocess(
+          (value) => (value === "" || value === null ? field.default : value),
+          enumSchema,
         );
+        return applyDefaults ? mapped.default(field.default) : mapped;
+      }
       if (field.required) return enumSchema;
       // Optional select without a default: an untouched HTML <select> submits
       // "" for its placeholder option. Treat that as "unset" (null) instead of
@@ -105,7 +123,9 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       // in buildInsertSchema kümmert sich um „darf fehlen".
       let schema = z.array(z.enum([first, ...rest]));
       if (field.required) schema = schema.min(1);
-      return field.default !== undefined ? schema.default([...field.default]) : schema;
+      return field.default !== undefined && applyDefaults
+        ? schema.default([...field.default])
+        : schema;
     }
     case "number": {
       let schema = z.number();
@@ -115,7 +135,7 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       if (field.integer) schema = schema.int().min(-2147483648).max(2147483647);
       if (field.min !== undefined) schema = schema.min(field.min);
       if (field.max !== undefined) schema = schema.max(field.max);
-      return field.default !== undefined ? schema.default(field.default) : schema;
+      return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
     }
     case "decimal": {
       // Stored as numeric(precision, scale), surfaced as JS number. Bound the
@@ -129,7 +149,7 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
         .refine((n) => isRepresentableAtScale(n, field.scale), {
           message: `at most ${field.scale} decimal places`,
         });
-      return field.default !== undefined ? schema.default(field.default) : schema;
+      return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
     }
     case "bigInt": {
       // JS-`number`-Round-trip via mode:"number"; sicher bis 2^53.
@@ -137,7 +157,7 @@ export function fieldToZod(field: FieldDefinition, currencies: readonly string[]
       // Float reinwirft (z.B. parseFloat-Bug), beim Insert sofort
       // failed statt silent-Truncation zu kassieren.
       const schema = z.number().int().safe();
-      return field.default !== undefined ? schema.default(field.default) : schema;
+      return field.default !== undefined && applyDefaults ? schema.default(field.default) : schema;
     }
     case "money": {
       const [first, ...rest] = currencies;
@@ -245,14 +265,15 @@ export function buildUpdateSchema(
   const shape: Record<string, z.ZodTypeAny> = {};
 
   for (const [name, field] of Object.entries(entity.fields)) {
-    // Update schemas never apply defaults — a user that sends only
-    // `{ title }` means "only change title"; zod defaults would silently
-    // inject default values for every omitted field and clobber existing
-    // data via the event-store-executor's `changes` payload.
-    // Cast widens the discriminated union so destructure works for variants
-    // without a `default` field; remainder is structurally a FieldDefinition.
-    const { default: _default, ...stripped } = field as FieldDefinition & { default?: unknown }; // @cast-boundary schema-walk
-    shape[name] = fieldToZod(stripped as FieldDefinition, currencies).optional(); // @cast-boundary schema-walk
+    // Update schemas never apply defaults for OMITTED fields — a user that
+    // sends only `{ title }` means "only change title"; zod defaults would
+    // silently inject default values for every omitted field and clobber
+    // existing data via the event-store-executor's `changes` payload.
+    // The field is passed through un-stripped (unlike before fw#1703) so
+    // fieldToZod still knows the default for its "" → default mapping
+    // (e.g. select) — applyDefaults: false only suppresses the schema-level
+    // `.default(...)` fallback for a genuinely omitted key.
+    shape[name] = fieldToZod(field, currencies, { applyDefaults: false }).optional();
   }
 
   return z.object(shape);

package/src/entrypoint/index.ts

@@ -142,11 +142,8 @@ export type WorkerEntrypoint = {
   readonly eventDispatcher: EventDispatcher;
   readonly jobRunner: JobRunner;
   readonly observability: ObservabilityProvider;
-  // Same dispatcher the API process exposes — a worker builds the identical
-  // server, only without routes. App-wired components that run in the worker
-  // and must persist their result need it: JobContext has no write/query
-  // (handlers.ts JobContext), so writing goes through dispatchSystemWrite,
-  // the pattern inbound-mail-foundation/watch-supervisor.ts established.
+  // Same dispatcher the API process exposes. Background components in the
+  // worker persist through the write-path — JobContext has no write/query.
   readonly dispatcher: Dispatcher;
   readonly mode: "worker";
   // Starts event-dispatcher poll + BullMQ worker. SIGTERM triggers

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { schedulerIdForJobName } from "../job-runner";
+import { bootJobIdForJobName, schedulerIdForJobName } from "../job-runner";
 
 describe("schedulerIdForJobName", () => {
   test("strips dots and colons so BullMQ job ids stay under the 5-segment legacy heuristic", () => {
@@ -16,3 +16,15 @@ describe("schedulerIdForJobName", () => {
     expect(schedulerIdForJobName("app.job.tick")).toBe("scheduler-app-job-tick");
   });
 });
+
+describe("bootJobIdForJobName", () => {
+  test("strips colons, same hazard as schedulerIdForJobName (fw#1604)", () => {
+    const id = bootJobIdForJobName("publicstatus:job:uptime-probe");
+    expect(id).toBe("boot-publicstatus-job-uptime-probe");
+    expect(id.includes(":")).toBe(false);
+  });
+
+  test("still collapses dotted QNs", () => {
+    expect(bootJobIdForJobName("app.job.tick")).toBe("boot-app-job-tick");
+  });
+});

package/src/jobs/job-runner.ts

@@ -45,6 +45,12 @@ export function schedulerIdForJobName(jobName: string): string {
   return `scheduler-${jobName.replace(/[.:]/g, "-")}`;
 }
 
+// Same colon-in-BullMQ-id hazard as schedulerIdForJobName (fw#1603/#1604) —
+// a QN like "publicstatus:job:uptime-probe" must not leave ":" in the id.
+export function bootJobIdForJobName(jobName: string): string {
+  return `boot-${jobName.replace(/[.:]/g, "-")}`;
+}
+
 // ponytail: migration shim, remove after fw#1603 deploy is everywhere.
 function legacySchedulerIdForJobName(jobName: string): string {
   return `scheduler-${jobName.replace(/\./g, "-")}`;
@@ -518,7 +524,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         if (laneForJob(jobDef) !== consumerLane) continue;
         if (jobDef.runOnBoot) {
           const bootName = jobDef.perTenant ? `_perTenant:${name}` : name;
-          await consumerQueue.add(bootName, {}, { jobId: `boot-${name.replace(/\./g, "-")}` });
+          await consumerQueue.add(bootName, {}, { jobId: bootJobIdForJobName(name) });
         }
       }
 

package/src/pipeline/system-hooks.ts

@@ -111,9 +111,22 @@ export async function decryptSearchableSubjectFields(
     }
     return out;
   }
-  return decryptPiiFieldValues(state, fields, kms, {
-    requestId: "system:consumer:search",
-  });
+  try {
+    return await decryptPiiFieldValues(state, fields, kms, {
+      requestId: "system:consumer:search",
+    });
+  } catch (err) {
+    console.warn(
+      `[kumiko:search] decryptSearchableSubjectFields failed for "${entityName}" — ` +
+        `dropping ciphertext fields for this document instead of wedging the consumer.`,
+      err,
+    );
+    const out = { ...state };
+    for (const name of fields) {
+      if (isPiiCiphertext(out[name])) delete out[name];
+    }
+    return out;
+  }
 }
 
 export function hasErasedSearchableSubjectField(

package/src/schema-cli.ts

@@ -289,11 +289,13 @@ export async function runSchemaCli(
             }
             if (mismatches.some((m) => m.kind === "unexpected-table")) {
               out.err(
-                "    Fix (unexpected-table): register the raw/hand-written table via `table()` " +
-                  "(or `defineUnmanagedTable()`) from `@cosmicdrift/kumiko-framework/db`, then " +
-                  "`r.storeTable(meta, { reason: ... })` inside a feature — this adds it to " +
-                  "ENTITY_METAS and the snapshot without going through r.entity(). See the " +
-                  "bundled `jobs` feature's job-run-log store table for the pattern.",
+                "    Fix (unexpected-table): build a meta via `defineUnmanagedTable()` " +
+                  "from `@cosmicdrift/kumiko-framework/db`, then `r.storeTable(meta, { reason: ... })` " +
+                  "inside a feature — this adds it to ENTITY_METAS immediately; the .snapshot.json " +
+                  "only picks it up on the NEXT `kumiko-schema generate` run, which you still need " +
+                  "to run and commit. `table()` returns a query handle, not a storeTable()-compatible " +
+                  "meta — don't pass its result to storeTable(). See the bundled `jobs` feature's " +
+                  "job-run-log store table for the pattern.",
               );
             }
             if (mismatches.some((m) => m.kind !== "unexpected-table")) {

package/src/search/purge-subject.ts

@@ -8,6 +8,7 @@
 //   2. Ciphertext LIKE prefix (same as nullBlindIndexesForSubject) for rows
 //      that still carry the subject key in encrypted columns.
 
+import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern";
 import type { SubjectId } from "../crypto/kms-adapter";
 import { collectSearchableSubjectFields } from "../crypto/subject-resolver";
 import type { DbRunner } from "../db/connection";
@@ -19,14 +20,6 @@ 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,
@@ -76,7 +69,7 @@ export async function purgeSearchDocumentsForSubject(
   /** When set, also match rows by ownership — needed after anonymize rewrites ciphertext. */
   subject?: SubjectId,
 ): Promise<void> {
-  const likePattern = `kumiko-pii:v%:${escapeLikePattern(subjectKey)}:%`;
+  const likePattern = subjectCiphertextLikePattern(subjectKey);
   const byTenant = new Map<string, { entityType: string; entityId: EntityId }[]>();
   const seen = new Set<string>();
 

package/src/secrets/derive-purpose-secret.ts

@@ -1,21 +1,11 @@
 import { hkdfSync } from "node:crypto";
 
-// One master secret, many purposes: HKDF turns `JWT_SECRET` into an
-// independent secret per trust boundary, so a token-signing key for MFA setup
-// cannot be used to forge a deletion token — and neither can be walked back to
-// the master. Rotating the master rotates every purpose with it.
-//
-// The alternative is an env var per purpose. That is not more secure (same
-// blast radius if the deploy is compromised), it is just more operations, and
-// in practice one of them ends up unset in some environment.
-//
-// The purpose string is a domain separator and part of the contract: change it
-// and every previously issued token for that purpose stops verifying. Version
-// them ("mfa-setup-token-v1") so a single purpose can be rotated deliberately
-// without touching the master or the other purposes.
-//
-// Lived copy-pasted in four apps before fw#1623 (money-horse, kumiko-studio,
-// publicstatus, plus a stale worktree) — identical bodies, drifting comments.
+// HKDF turns one master secret into an independent secret per purpose, so
+// a token-signing key for MFA setup can't forge a deletion token and
+// neither can be walked back to the master. `purpose` is a domain
+// separator, not a label — changing it invalidates every previously
+// issued token for that purpose; version it ("mfa-setup-token-v1") to
+// rotate one purpose deliberately.
 export function derivePurposeSecret(masterSecret: string, purpose: string): string {
   if (!masterSecret) {
     throw new Error("derivePurposeSecret: masterSecret must not be empty.");

package/src/testing/__tests__/e2e-generator.test.ts

@@ -259,4 +259,11 @@ describe("generateZodFixture", () => {
     expect(() => generateZodFixture(z.object({}))).toThrow(/not supported yet/);
     expect(() => generateZodFixture(z.array(z.string()))).toThrow(/not supported yet/);
   });
+
+  test("pipe (select-with-default, same shape schema-builder's z.preprocess produces) unwraps to the underlying type's fixture (fw#1712)", () => {
+    const enumSchema = z.enum(["a", "b"]);
+    const pipe = z.preprocess((value) => (value === "" ? "a" : value), enumSchema);
+    expect(pipe._def.type).toBe("pipe");
+    expect(generateZodFixture(pipe)).toBe("a");
+  });
 });

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

@@ -9,11 +9,11 @@ describe("waitFor", () => {
       () => {
         calls++;
       },
-      { delays: [200, 200, 200] },
+      { delays: [2000] },
     );
     expect(calls).toBe(1);
     // try-first: must not burn the first delay when the condition already holds
-    expect(Date.now() - started).toBeLessThan(100);
+    expect(Date.now() - started).toBeLessThan(500);
   });
 
   test("retries on failure and succeeds once fn passes", async () => {