@cosmicdrift/kumiko-framework 0.231.0 → 0.232.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.231.0",
+  "version": "0.232.0",
   "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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.231.0",
+    "@cosmicdrift/kumiko-types": "0.232.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.231.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.232.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/bun-db/query.ts

@@ -1,6 +1,6 @@
-// Typed Query-API über Bun.sql. KEIN drizzle intern. Identische Signatur
-// zur legacy `db/query-api.ts` — App-code-migration ist Import-Pfad-Wechsel,
-// kein call-site-Refactor.
+// Typed query API over Bun.sql. No drizzle internally. Same signature as the
+// legacy `db/query-api.ts` — app-code migration is just an import-path swap,
+// not a call-site refactor.
 //
 // API:
 //   selectMany<T>(db, table, where?, opts?) → readonly T[]
@@ -13,11 +13,11 @@
 //   deleteManyBatched(db, table, where, { limit }) → { deleted, batches }
 //   transaction<T>(db, fn) → T
 //
-// `table` kann sein:
+// `table` can be either:
 //   - EntityTableMeta (preferred, plain data)
-//   - drizzle pgTable (legacy, hat Symbol-based tableName) — extracted via
-//     drizzle's getTableName + getTableColumns (drizzle weiterhin als type-
-//     reference, NICHT als runtime-API-call)
+//   - drizzle pgTable (legacy, has Symbol-based tableName) — extracted via
+//     drizzle's getTableName + getTableColumns (drizzle kept only as a type
+//     reference, never as a runtime API call)
 
 import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import type {
@@ -49,7 +49,7 @@ function snakeToCamel(key: string): string {
 import type { DbRunner } from "@cosmicdrift/kumiko-types/db-connection";
 import type { BunDbRunner } from "./connection";
 
-// Drizzle-pgTable-Inspection via raw Symbol-access (kein drizzle-orm import).
+// Drizzle pgTable inspection via raw Symbol access (no drizzle-orm import).
 // table() (dialect) stores the canonical, shadow-proof EntityTableMeta under
 // `Symbol.for("kumiko:schema:Meta")`. The column handles on the table object are
 // enumerable props, so an entity field named `source`/`columns`/`tableName`/…
@@ -79,12 +79,12 @@ export function asEntityTableMeta(table: unknown): EntityTableMeta | undefined {
   return isEntityTableMeta(table) ? table : undefined;
 }
 
-// `db` Input akzeptiert drei Shapes:
-//   1. Bun.SQL connection (BunDbRunner) — neue Welt, native .unsafe + .begin
-//   2. drizzle DbConnection (postgres-js-Wrapper) — legacy compat,
-//      raw postgres-js client liegt unter `db.$client.unsafe / .begin`
-//   3. drizzle tx-handle — client liegt unter `tx.session.client`
-// Shim extrahiert in allen Fällen ein `{unsafe, begin}`-Surface.
+// `db` input accepts three shapes:
+//   1. Bun.SQL connection (BunDbRunner) — new world, native .unsafe + .begin
+//   2. drizzle DbConnection (postgres-js wrapper) — legacy compat,
+//      raw postgres-js client sits under `db.$client.unsafe / .begin`
+//   3. drizzle tx-handle — client sits under `tx.session.client`
+// The shim extracts a `{unsafe, begin}` surface in every case.
 type RawClient = {
   unsafe: <TRow = unknown>(sql: string, params?: readonly unknown[]) => Promise<readonly TRow[]>;
   begin: <T>(fn: (tx: unknown) => Promise<T>) => Promise<T>;
@@ -254,23 +254,24 @@ function isWhereOperator(v: unknown): v is WhereOperator {
   if (keys.length === 0) return false;
   return keys.every((k) => (WHERE_OPERATOR_KEYS as readonly string[]).includes(k));
 }
-// Akzeptiert EITHER. Beide haben einen tableName und field→column-mapping.
+// Accepts EITHER. Both have a tableName and field→column mapping.
 // biome-ignore lint/suspicious/noExplicitAny: legacy drizzle pgTable surface
 type TableLike = EntityTableMeta | any;
 
-// Write-Param: alles was TableLike akzeptiert AUSSER einer gebrandeten
-// EntityTable (managed projection). Ein direkter Write auf eine Entity ist ein
-// Compile-Fehler — der einzige Schreibweg ist der Executor (Event ->
-// rebuild-safe). Unmanaged EntityTableMeta + die am Executor-Seam auf
-// TableColumns<any> eraste Table tragen den Brand nicht -> erlaubt. Test-Seeds
-// gehen über den sanktionierten testing-Seam (seedRow/…), der den Brand strippt.
+// Write param: everything TableLike accepts EXCEPT a branded
+// EntityTable (managed projection). A direct write to an Entity is a
+// compile error — the only write path is the executor (event ->
+// rebuild-safe). Unmanaged EntityTableMeta plus the table erased to
+// TableColumns<any> at the executor seam don't carry the brand -> allowed.
+// Test seeds go through the sanctioned testing seam (seedRow/…), which
+// strips the brand.
 // Method-form writes (ctx.db.insertOne/…) keep an erased param and are covered
 // by the guard-direct-entity-writes AST guard instead (see tenant-db.ts).
 type WritableTable = EntityTableMeta & NotExecutorOnly;
 
 export type TableInfo = {
   readonly name: string;
-  // field-name (camelCase oder snake_case) → snake_case column-name
+  // field name (camelCase or snake_case) → snake_case column name
   readonly columnOf: (field: string) => string;
   // pgType per column-name, for jsonb-cast detection
   readonly pgTypeOf: (column: string) => string | undefined;
@@ -366,8 +367,8 @@ function coerceBigIntFromDriver(value: bigint | string): bigint | number {
 function instantFromDriver(value: unknown): Temporal.Instant | null {
   if (value === null || value === undefined) return null;
   if (isTemporalInstant(value)) return value as Temporal.Instant;
-  // Number-coercion via +date — equivalent to .getTime() ohne Date-API-Methode
-  // (guard-no-date-api). Date → epochMilliseconds, dann zu Temporal.Instant.
+  // Number coercion via +date — equivalent to .getTime() without a Date-API
+  // method (guard-no-date-api). Date → epoch milliseconds, then to Temporal.Instant.
   if (value instanceof Date) return Temporal.Instant.fromEpochMilliseconds(+value);
   if (typeof value === "string") {
     try {
@@ -437,8 +438,8 @@ export function coerceRow<T extends Record<string, unknown>>(row: T, info: Table
   const out: Record<string, unknown> = {};
   let changed = false;
   for (const key of Object.keys(row)) {
-    // Blind-Index-Spalten (#818) sind reine Lookup-Artefakte — der
-    // deterministische HMAC darf nie an Caller/API-Responses leaken.
+    // Blind-index columns (#818) are pure lookup artifacts — the
+    // deterministic HMAC must never leak into caller/API responses.
     if ((key.endsWith("_bidx") || key.endsWith("Bidx")) && info.hasColumn(key)) {
       changed = true;
       continue;
@@ -505,11 +506,11 @@ function coerceRows<T extends Record<string, unknown>>(
   return rows.map((r) => coerceRow(r, info));
 }
 
-// Helper für jsonb-Werte: structured values binden als JS object/array mit
-// ::jsonb cast. JSON.stringify vor dem cast würde JSON-string-scalars erzeugen.
+// Helper for jsonb values: structured values bind as a JS object/array with
+// an ::jsonb cast. JSON.stringify before the cast would produce JSON-string scalars.
 // Plus Temporal.Instant → ISO string coercion for timestamptz columns.
-// SqlExpression (sql`now()`, sql`gen_random_uuid()`) wird als kind:"literal"
-// returned — Caller embedded das inline statt einen $N-placeholder zu setzen.
+// SqlExpression (sql`now()`, sql`gen_random_uuid()`) is returned as
+// kind:"literal" — the caller embeds it inline instead of setting a $N placeholder.
 type PreparedValue =
   | { readonly kind: "param"; readonly sql: string; readonly bound: unknown }
   | { readonly kind: "literal"; readonly literal: string };
@@ -693,12 +694,12 @@ function buildWhereClause(
       if (p.kind === "literal") {
         conditions.push(`${quoteIdent(col)} = ${p.literal}`);
       } else {
-        // Blind-Index-OR-Rewrite (#818): existiert zur Spalte ein bidx-
-        // Pendant (Suffix-Konvention `<col>_bidx`, framework-reserviert)
-        // und ist ein Key konfiguriert, matcht Equality beide Arme —
-        // Klartext-Alt-Rows über den Plaintext-Arm, verschlüsselte Rows
-        // über den HMAC. Der `kumiko-pii:`-Prefix der Ciphertexte macht
-        // einen Zufalls-Match des Plaintext-Arms praktisch unmöglich.
+        // Blind-index OR rewrite (#818): if the column has a bidx
+        // counterpart (suffix convention `<col>_bidx`, framework-reserved)
+        // and a key is configured, equality matches both arms —
+        // plaintext legacy rows via the plaintext arm, encrypted rows
+        // via the HMAC. The `kumiko-pii:` prefix on ciphertexts makes
+        // a random match on the plaintext arm practically impossible.
         const bidxKey = configuredBlindIndexKey();
         const bidxCol = `${col}_bidx`;
         if (

package/src/db/__tests__/blind-index.integration.test.ts

@@ -45,6 +45,18 @@ const personFeature = defineFeature("bidxtest", (r) => {
 });
 const personTable = buildEntityTable("person", personEntity);
 
+// Lookupable entity whose read table is deliberately never created — used to
+// prove the forget sweep skips missing relations (fw#2550).
+const ghostEntity = createEntity({
+  table: "read_bidx_ghosts_missing",
+  fields: {
+    email: createTextField({ required: true, personal: "self", find: "exact" }),
+  },
+});
+const ghostFeature = defineFeature("bidxghost", (r) => {
+  r.entity("ghost", ghostEntity);
+});
+
 let testDb: TestDb;
 let tdb: TenantDb;
 let kms: InMemoryKmsAdapter;
@@ -247,4 +259,24 @@ describe("blind-index rebuild + forget", () => {
     expect((await rawRow(String(created.data.id)))["email_bidx"]).toBeNull();
     expect(await fetchOne(tdb, personTable, { email: "marc@example.com" })).toBeUndefined();
   });
+
+  test("nullBlindIndexesForSubject skips missing projection tables (fw#2550)", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    expect((await rawRow(String(created.data.id)))["email_bidx"]).not.toBeNull();
+
+    await kms.eraseKey({ kind: "user", userId: String(created.data.id) });
+    // Registry includes a lookupable ghost whose table was never migrated —
+    // pre-fix this UPDATE threw after eraseKey and left bidx linkable.
+    const registry = createRegistry([personFeature, ghostFeature]);
+    await expect(
+      nullBlindIndexesForSubject(
+        testDb.db,
+        registry.features,
+        subjectIdToKey({ kind: "user", userId: String(created.data.id) }),
+      ),
+    ).resolves.toBeUndefined();
+
+    expect((await rawRow(String(created.data.id)))["email_bidx"]).toBeNull();
+  });
 });

package/src/db/blind-index-cleanup.ts

@@ -19,6 +19,7 @@ import { toSnakeCase } from "../utils/case";
 import type { DbRunner } from "./connection";
 import { resolveTableName } from "./entity-table-meta";
 import { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql";
+import { tableExists } from "./schema-inspection";
 
 export async function nullBlindIndexesForSubject(
   db: DbRunner,
@@ -34,6 +35,11 @@ export async function nullBlindIndexesForSubject(
       // one (buildEntityTable with no featureName option), the sweep has to
       // hit the same names.
       const tableName = resolveTableName(entityName, entity, undefined);
+      // Skip entities whose projection was never migrated — same class as
+      // subjectRowExistsInTenant (fw#2348). A throw here runs AFTER eraseKey
+      // in forget-subject and would leave deterministic bidx columns still
+      // linkable (fw#2550).
+      if (!(await tableExists(db, tableName))) continue;
       for (const fieldName of lookupable) {
         const snake = toSnakeCase(fieldName);
         await executeRawQuery(

package/src/db/entity-table-meta.ts

@@ -38,8 +38,8 @@ export type {
   UnmanagedTableInput,
 } from "./entity-table-meta-types";
 
-// Standard base-columns für event-sourced Read-Model-Tabellen. Spiegelt
-// `buildBaseColumns()` aus table-builder.ts (drizzle-Variante).
+// Standard base columns for event-sourced read-model tables. Mirrors
+// `buildBaseColumns()` from table-builder.ts (drizzle variant).
 function fullBaseColumns(idType: "uuid" | "serial", softDelete: boolean): readonly ColumnMeta[] {
   const idCol: ColumnMeta =
     idType === "uuid"
@@ -85,8 +85,8 @@ function fieldDefaultLiteral(field: FieldDefinition): string | undefined {
   return undefined;
 }
 
-// Spiegelt `fieldToColumns()` aus table-builder.ts (Drizzle-Variante).
-// Lock-step: jeder Field-Type produziert dieselben PG-Spalten wie heute.
+// Mirrors `fieldToColumns()` from table-builder.ts (drizzle variant).
+// Lock-step: every field type must produce the same PG columns as today.
 function fieldToColumnMeta(
   name: string,
   field: FieldDefinition,
@@ -105,9 +105,9 @@ function fieldToColumnMeta(
           ...(def !== undefined && { defaultSql: def }),
         },
       ];
-      // lookupable → HMAC-Blind-Index-Pendant. Nullable ist Pflicht:
-      // managedChangeRequiresRecreate würde eine NOT-NULL-Spalte ohne
-      // Default auf Bestandstabellen als DROP+Rebuild diffen.
+      // lookupable → HMAC blind-index counterpart. Nullable is mandatory:
+      // managedChangeRequiresRecreate would diff a NOT-NULL column without
+      // a default on existing tables as DROP+rebuild.
       if (field.type === "text" && field.lookupable === true) {
         cols.push({ name: `${snake}_bidx`, pgType: "text", notNull: false });
       }
@@ -262,13 +262,13 @@ export function deriveEntityTableMeta(
   }
   const idType = entity.idType ?? "uuid";
 
-  // Base-columns first, then user-fields. User-fields with the same
-  // pg-name as a base-column OVERRIDE the base-column (last-wins, gleiches
-  // Verhalten wie drizzle's `{ ...base, ...fields }` Spread im table-
-  // builder). Use-case: user-session hat `tenantId` als field um access-
-  // control aufzudrücken, fileRef hat `insertedAt` als field für sortable/
-  // filterable-marker. Die DB-Spalte bleibt die gleiche, nur Application-
-  // Metadata auf der Field-Seite ändert sich.
+  // Base columns first, then user-fields. User-fields with the same
+  // pg-name as a base-column OVERRIDE the base-column (last-wins, same
+  // behavior as drizzle's `{ ...base, ...fields }` spread in the table
+  // builder). Use case: user-session has `tenantId` as a field to enforce
+  // access control, fileRef has `insertedAt` as a field for sortable/
+  // filterable marking. The DB column stays the same, only the application
+  // metadata on the field side changes.
   const baseCols = fullBaseColumns(idType, entity.softDelete === true);
   const colByName = new Map<string, ColumnMeta>();
   for (const c of baseCols) colByName.set(c.name, c);
@@ -323,15 +323,15 @@ export function deriveEntityTableMeta(
     indexes.push({ name: `${tableName}_${snake}_idx`, columns: [snake] });
   }
 
-  // lookupable-Felder: Index auf der bidx-Spalte — der OR-Rewrite der
-  // Query-Compiler trifft sie bei jedem Equality-Lookup.
+  // lookupable fields: index on the bidx column — the query compiler's
+  // OR rewrite hits it on every equality lookup.
   for (const bidxSnake of bidxSnakeByFieldSnake.values()) {
     indexes.push({ name: `${tableName}_${bidxSnake}_idx`, columns: [bidxSnake] });
   }
 
-  // Explizit deklarierte indexes (EntityIndexDef). `def.where` ist ein
-  // SqlExpression (`sql\`…\`` aus @cosmicdrift/kumiko-framework/db) —
-  // renderbar via `.text`. Unbekannte where-Shapes bleiben needsManualWhere.
+  // Explicitly declared indexes (EntityIndexDef). `def.where` is a
+  // SqlExpression (`sql\`…\`` from @cosmicdrift/kumiko-framework/db) —
+  // renderable via `.text`. Unknown where-shapes stay needsManualWhere.
   for (const def of (entity.indexes ?? []) as readonly EntityIndexDef[]) {
     const cols = def.columns.map(
       (fieldName) => fieldNameToSnake.get(fieldName) ?? toSnakeCase(fieldName),
@@ -346,10 +346,10 @@ export function deriveEntityTableMeta(
       ...(whereSql !== undefined && { whereSql }),
       ...(def.where !== undefined && whereSql === undefined && { needsManualWhere: true }),
     });
-    // Unique-Index über lookupable-Spalten: partielles bidx-Pendant, damit
-    // Uniqueness auch für verschlüsselte Rows greift. Das Original bleibt
-    // für Klartext-Alt-Rows; partial (IS NOT NULL) weil bidx bei erased/
-    // key-losen Rows NULL ist.
+    // Unique index over lookupable columns: partial bidx counterpart, so
+    // uniqueness also holds for encrypted rows. The original stays
+    // for plaintext legacy rows; partial (IS NOT NULL) because bidx is
+    // NULL for erased/key-less rows.
     if (def.unique === true && def.where === undefined) {
       const bidxCols = cols.map((c) => bidxSnakeByFieldSnake.get(c) ?? c);
       if (bidxCols.some((c, i) => c !== cols[i])) {

package/src/engine/__tests__/build-app-schema.test.ts

@@ -49,6 +49,48 @@ describe("buildAppSchema", () => {
     expect(fleet?.entities["vehicle"]).toBeDefined();
   });
 
+  // r.screen({ nav: {...} }) sugar must omit absent optional nav fields
+  // rather than writing them as explicit `undefined` — a plain key-per-
+  // field object literal makes `undefined` a real value in the schema,
+  // which findNonJsonSafePath flags as a boot-time warning even though
+  // JSON.stringify silently drops the key later. r.contentCollection()
+  // already gets this right via a conditional spread; this pins the same
+  // fix for r.screen().
+  test("r.screen({ nav }) sugar omits absent optional nav fields instead of writing them as undefined", () => {
+    const topLevelFeature = defineFeature("privacy", (r) => {
+      r.screen({
+        id: "privacy-center",
+        type: "custom",
+        renderer: { react: { __component: "PrivacyCenterScreen" } },
+        nav: { label: "Privacy" },
+      });
+    });
+    const nestedFeature = defineFeature("billing", (r) => {
+      r.screen({
+        id: "invoices",
+        type: "custom",
+        renderer: { react: { __component: "InvoicesScreen" } },
+        nav: { label: "Invoices", parent: "billing:nav:overview" },
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([topLevelFeature, nestedFeature]));
+
+    const privacyFeature = app.features.find((f) => f.featureName === "privacy");
+    const topLevelNav = privacyFeature?.navs?.[0];
+    if (!topLevelNav) throw new Error("privacy feature's nav entry is missing");
+    expect("parent" in topLevelNav).toBe(false);
+    expect("icon" in topLevelNav).toBe(false);
+    expect("order" in topLevelNav).toBe(false);
+
+    const billingFeature = app.features.find((f) => f.featureName === "billing");
+    const nestedNav = billingFeature?.navs?.[0];
+    if (!nestedNav) throw new Error("billing feature's nav entry is missing");
+    expect(nestedNav.parent).toBe("billing:nav:overview");
+
+    expect(findNonJsonSafePath(app, "schema")).toBeNull();
+  });
+
   // #1059: r.translations({keys}) must flow into FeatureSchema.translations
   // BYTE-IDENTICAL — nav/screen labels resolve these keys verbatim via
   // t(label) client-side, so any re-prefixing (like the registry's internal

package/src/engine/__tests__/define-workflow.test.ts

@@ -4,6 +4,7 @@ import {
   defineWorkflow,
   type WorkflowTrigger,
 } from "../define-workflow";
+import { stepsPipeline } from "../pipeline";
 import type { PipelineDef } from "../types/step";
 
 const pipe = (build: PipelineDef["build"]): PipelineDef => ({ __kind: "pipeline", build });
@@ -17,7 +18,28 @@ describe("defineWorkflow", () => {
     expect(wf.__kind).toBe("workflow");
     expect(wf.name).toBe("onboard");
     expect(wf.trigger).toEqual(eventTrigger);
-    expect(wf.pipelineDef).toBe(steps);
+    // pipelineDef is no longer `steps` by reference — defineWorkflow rebuilds
+    // it to carry the (possibly absent) branded awaits map — but the
+    // closure itself must be the exact same function.
+    expect(wf.pipelineDef.__kind).toBe("pipeline");
+    expect(wf.pipelineDef.build).toBe(steps.build);
+    expect(wf.awaits).toBeUndefined();
+    expect(wf.pipelineDef.awaits).toBeUndefined();
+  });
+
+  test("brands the declared awaits map onto both the definition and the pipelineDef", () => {
+    const wf = defineWorkflow({
+      name: "order-fulfillment",
+      trigger: eventTrigger,
+      awaits: { shipped: "order.shipped", cancelled: "order.cancelled" },
+      steps: stepsPipeline(() => []),
+    });
+
+    expect(wf.awaits).toEqual({ shipped: "order.shipped", cancelled: "order.cancelled" });
+    expect(wf.pipelineDef.awaits).toEqual({
+      shipped: "order.shipped",
+      cancelled: "order.cancelled",
+    });
   });
 });
 

package/src/engine/__tests__/steps-workflow.test.ts

@@ -10,7 +10,12 @@ import {
 import { buildRetryStep, calculateBackoff } from "../steps/retry";
 import { buildWaitStep } from "../steps/wait";
 import { buildWaitForEventStep } from "../steps/wait-for-event";
-import type { EventMatch, PipelineCtx } from "../types/step";
+import type { AwaitedEventType, EventMatch, PipelineCtx } from "../types/step";
+
+// Test-only helper for the low-level step-builder unit tests below, which
+// call buildWaitForEventStep directly instead of going through a
+// defineWorkflow `awaits` declaration (the only legitimate branding route).
+const asAwaited = (event: string): AwaitedEventType => event as AwaitedEventType;
 
 const mockUnsafeAppendEvent = mock();
 
@@ -91,7 +96,7 @@ describe("workflow.wait run", () => {
 describe("buildWaitForEventStep", () => {
   it("returns a StepInstance with kind workflow.waitForEvent", () => {
     const step = buildWaitForEventStep({
-      event: "user.confirmed-email",
+      event: asAwaited("user.confirmed-email"),
       timeout: "P7D",
     });
     expect(step.kind).toBe("workflow.waitForEvent");
@@ -103,12 +108,19 @@ describe("buildWaitForEventStep", () => {
       expr: { kind: "atom", path: ["email"], op: { kind: "eq", value: "test@test.com" } },
     };
     const step = buildWaitForEventStep({
-      event: "user.confirmed-email",
+      event: asAwaited("user.confirmed-email"),
       match,
       timeout: "P7D",
     });
     expect(step.kind).toBe("workflow.waitForEvent");
   });
+
+  it("@ts-expect-error: event must come from an awaits declaration, not a raw string", () => {
+    // @ts-expect-error — a raw string is not an AwaitedEventType; only
+    // defineWorkflow's `awaits` map can produce one (D4, workflow-resume-loop.md).
+    const step = buildWaitForEventStep({ event: "user.confirmed-email", timeout: "P7D" });
+    expect(step.kind).toBe("workflow.waitForEvent");
+  });
 });
 
 describe("workflow.waitForEvent run", () => {

package/src/engine/define-workflow.ts

@@ -5,7 +5,7 @@
 
 import { createHash } from "node:crypto";
 import type { WriteEvent } from "./types/handlers";
-import type { PipelineDef } from "./types/step";
+import type { AwaitedEventType, PipelineDef } from "./types/step";
 
 /**
  * Trigger configuration for a workflow. Determines what starts a run.
@@ -28,12 +28,27 @@ export type WorkflowTrigger =
 /**
  * Workflow definition — the result of defineWorkflow().
  */
-export type WorkflowDefinition<TPayload = unknown, TData = unknown> = {
+export type WorkflowDefinition<
+  TPayload = unknown,
+  TData = unknown,
+  TAwaits extends Record<string, string> = Record<string, string>,
+> = {
   readonly __kind: "workflow";
   readonly name: string;
   readonly trigger: WorkflowTrigger;
+  /**
+   * Declared expected events (D4, workflow-resume-loop.md) — the sole route
+   * a waitForEvent step can reach an event type. Read at registration time
+   * to build the static apply-map (Phase 3b); values are plain event-type
+   * strings, not the branded AwaitedEventType the pipeline closure sees.
+   */
+  readonly awaits?: TAwaits;
   /** The pipeline definition containing the step list closure. */
-  readonly pipelineDef: PipelineDef<TPayload, TData>;
+  readonly pipelineDef: PipelineDef<
+    TPayload,
+    TData,
+    { readonly [K in keyof TAwaits]: AwaitedEventType }
+  >;
   /** Idempotency key for deduplication — prevents duplicate runs. */
   readonly idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string);
 };
@@ -41,10 +56,15 @@ export type WorkflowDefinition<TPayload = unknown, TData = unknown> = {
 /**
  * Input shape for defineWorkflow() — the user-facing API.
  */
-export type WorkflowInput<TPayload = unknown, TData = unknown> = {
+export type WorkflowInput<
+  TPayload = unknown,
+  TData = unknown,
+  TAwaits extends Record<string, string> = Record<string, string>,
+> = {
   readonly name: string;
   readonly trigger: WorkflowTrigger;
-  readonly steps: PipelineDef<TPayload, TData>;
+  readonly awaits?: TAwaits;
+  readonly steps: PipelineDef<TPayload, TData, { readonly [K in keyof TAwaits]: AwaitedEventType }>;
   readonly idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string);
   readonly onError?: PipelineDef<unknown>;
 };
@@ -69,14 +89,22 @@ export type WorkflowInput<TPayload = unknown, TData = unknown> = {
  * });
  * ```
  */
-export function defineWorkflow<TPayload = unknown, TData = unknown>(
-  input: WorkflowInput<TPayload, TData>,
-): WorkflowDefinition<TPayload, TData> {
+export function defineWorkflow<
+  TPayload = unknown,
+  TData = unknown,
+  const TAwaits extends Record<string, string> = Record<string, string>,
+>(input: WorkflowInput<TPayload, TData, TAwaits>): WorkflowDefinition<TPayload, TData, TAwaits> {
+  // pipelineDef.awaits carries the same raw strings as the declaration
+  // below — buildPipelineSteps (pipeline.ts) is where they're branded into
+  // AwaitedEventType for the step closure, not here (see PipelineDef.awaits
+  // doc comment in types/step.ts for why the brand can't happen at this
+  // layer without breaking inference for an inline `stepsPipeline(...)`).
   return {
     __kind: "workflow",
     name: input.name,
     trigger: input.trigger,
-    pipelineDef: input.steps,
+    awaits: input.awaits,
+    pipelineDef: { ...input.steps, awaits: input.awaits },
     idempotencyKey: input.idempotencyKey,
   };
 }
@@ -98,12 +126,21 @@ export function defineWorkflow<TPayload = unknown, TData = unknown>(
  *     environments. Run-the-fingerprint-in-the-same-environment is the
  *     contract; cross-env replay is out of scope.
  */
-export function computeDefinitionFingerprint(
-  workflow: Pick<WorkflowDefinition, "name" | "trigger" | "pipelineDef">,
+export function computeDefinitionFingerprint<
+  TPayload = unknown,
+  TData = unknown,
+  TAwaits extends Record<string, string> = Record<string, string>,
+>(
+  workflow: Pick<WorkflowDefinition<TPayload, TData, TAwaits>, "name" | "trigger" | "pipelineDef">,
 ): string {
+  // `awaits` is part of the routing contract (D4, workflow-resume-loop.md):
+  // changing which events a run waits on changes the run's behavior just
+  // like changing the step source does, so a changed declaration must flip
+  // the fingerprint and trip the Q7 stale-definition check on resume.
   const material = JSON.stringify({
     name: workflow.name,
     trigger: workflow.trigger,
+    awaits: workflow.pipelineDef.awaits,
     source: workflow.pipelineDef.build.toString(),
   });
   return createHash("sha256").update(material).digest("hex");

package/src/engine/feature-ui-extensions.ts

@@ -360,12 +360,15 @@ export function buildUiExtensionsMethods<TName extends string>(
         // Sugar for the common "one nav entry pointing at this screen"
         // case — synthesizes id/screen from the screen's own id. Beyond
         // label/icon/parent/order, declare a standalone r.nav() instead.
+        // Optional fields stay absent rather than explicitly undefined —
+        // buildAppSchema's JSON-safety check flags undefined values. Same
+        // pattern as r.contentCollection() below.
         registerNav({
           id: definition.id,
           label: definition.nav.label,
-          icon: definition.nav.icon,
-          parent: definition.nav.parent,
-          order: definition.nav.order,
+          ...(definition.nav.icon !== undefined && { icon: definition.nav.icon }),
+          ...(definition.nav.parent !== undefined && { parent: definition.nav.parent }),
+          ...(definition.nav.order !== undefined && { order: definition.nav.order }),
           screen: `${name}:screen:${definition.id}`,
         });
       }

package/src/engine/index.ts

@@ -470,6 +470,7 @@ export type {
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases } from "./types";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
 export type {
+  AwaitedEventType,
   PipelineBuildCtx,
   PipelineCtx,
   PipelineDef,

package/src/engine/pipeline.ts

@@ -31,7 +31,13 @@ import { buildWaitStep } from "./steps/wait";
 import { buildWaitForEventStep } from "./steps/wait-for-event";
 import { buildWebhookSendStep } from "./steps/webhook-send";
 import type { WriteEvent } from "./types/handlers";
-import type { PipelineBuildCtx, PipelineDef, StepBuilder, StepInstance } from "./types/step";
+import type {
+  AwaitedEventType,
+  PipelineBuildCtx,
+  PipelineDef,
+  StepBuilder,
+  StepInstance,
+} from "./types/step";
 
 const stepBuilder: StepBuilder = {
   step: {
@@ -64,9 +70,13 @@ const stepBuilder: StepBuilder = {
   },
 };
 
-export function stepsPipeline<TPayload = unknown, TData = unknown>(
-  closure: (ctx: PipelineBuildCtx<TPayload>) => readonly StepInstance[],
-): PipelineDef<TPayload, TData> {
+export function stepsPipeline<
+  TPayload = unknown,
+  TData = unknown,
+  TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>,
+>(
+  closure: (ctx: PipelineBuildCtx<TPayload, TAwaits>) => readonly StepInstance[],
+): PipelineDef<TPayload, TData, TAwaits> {
   return {
     __kind: "pipeline",
     build: closure,
@@ -76,9 +86,26 @@ export function stepsPipeline<TPayload = unknown, TData = unknown>(
 // Internal: invoked by run-pipeline.ts to materialise the step list.
 // Not exported from the engine barrel — pipeline-internal plumbing.
 // @wrapper-known semantic-alias
-export function buildPipelineSteps<TPayload>(
-  pipelineDef: PipelineDef<TPayload>,
+//
+// `awaits` comes off pipelineDef itself (set by defineWorkflow), not a
+// function argument — every existing buildPipelineSteps caller (runner.ts,
+// resume-run.write.ts, run-pipeline.ts, validate-projection-allowlist.ts)
+// keeps working unchanged while workflow pipelines still get their real
+// awaits map wired into the closure. The cast below is the one place a
+// workflow's raw declared event-type strings become AwaitedEventType — safe
+// because pipelineDef.awaits only ever holds what defineWorkflow's `awaits`
+// carried in (D4, workflow-resume-loop.md), never an unchecked external
+// value.
+export function buildPipelineSteps<
+  TPayload,
+  TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>,
+>(
+  pipelineDef: PipelineDef<TPayload, unknown, TAwaits>,
   event: WriteEvent<TPayload>,
 ): readonly StepInstance[] {
-  return pipelineDef.build({ event, r: stepBuilder });
+  return pipelineDef.build({
+    event,
+    r: stepBuilder,
+    awaits: (pipelineDef.awaits ?? {}) as TAwaits,
+  });
 }

package/src/engine/steps/wait-for-event.ts

@@ -12,9 +12,23 @@
 // EventMatch AST (not a closure) that is persisted into the waiting event's
 // payload; the Resume-Loop evaluates it via evaluateEventMatch against the
 // candidate event's payload.
+//
+// resultKey is `args.event` itself (the branded event-type string) rather
+// than a new `name` argument — a workflow only ever has one `awaits` entry
+// per event type, so `ctx.steps[awaits.someKey]` is already a unique,
+// intention-revealing handle. resume-run.write.ts (framework#2513 Phase 3b)
+// is the only producer of this key's value: the step itself always
+// suspends (never returns a real result), so a subsequent step only ever
+// sees the matched event's payload after a resume seeds it in.
 
 import { defineStep } from "../define-step";
-import type { EventMatch, PipelineCtx, StepInstance, StepResolver } from "../types/step";
+import type {
+  AwaitedEventType,
+  EventMatch,
+  PipelineCtx,
+  StepInstance,
+  StepResolver,
+} from "../types/step";
 import { addDuration } from "./_duration-utils";
 import { resolveOptional, resolveRequired } from "./_resolver-utils";
 import {
@@ -24,7 +38,7 @@ import {
 } from "./_step-dispatch-constants";
 
 type WaitForEventArgs = {
-  readonly event: string;
+  readonly event: AwaitedEventType;
   readonly match?: StepResolver<EventMatch>;
   readonly timeout: StepResolver<string>;
 };
@@ -33,6 +47,7 @@ defineStep<WaitForEventArgs, undefined | typeof SUSPEND_SENTINEL>({
   kind: "workflow.waitForEvent",
   tier: 3,
   defaultFailureStrategy: "throw",
+  resultKey: (args) => args.event,
   run: async (args, ctx: PipelineCtx): Promise<undefined | typeof SUSPEND_SENTINEL> => {
     if (!ctx.workflow) {
       throw new Error(

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

@@ -925,6 +925,9 @@ describe("perTenant across multiple runner instances", () => {
     // A post-close 'error' here is otherwise unhandled and bun:test
     // attributes it to whichever test runs next (fw#1805).
     rawQueue.on("error", () => {});
+    // Snapshot of completed wrapper runs — declared outside try so the
+    // post-finally fan-out check can read it.
+    let drainedCalls = 0;
     try {
       // Both instances call start() → both call upsertJobScheduler() with
       // the SAME schedulerId against the SAME Redis. If that didn't dedup,
@@ -937,27 +940,38 @@ describe("perTenant across multiple runner instances", () => {
       // called upsertJobScheduler() against it. Two entries here means two
       // independent repeat timers, which would double-fire every tick.
       expect(await rawQueue.getJobSchedulersCount()).toBe(1);
-      await waitFor(() => expect(wrapperCalls).toBeGreaterThanOrEqual(1), {
-        delays: [2000, 3000, 5000],
-      });
+      // Wait for the asserted drain state while workers are still up —
+      // stop() tears down consumers, so a post-finally sleep/assert races
+      // on unprocessed children (fw#2556: expected 4, got 2). Snapshot
+      // drainedCalls inside the predicate; do not assert a post-stop
+      // log-length ceiling — in-flight children (and sequential multi-
+      // runner stop) can still append after the snapshot.
+      await waitFor(
+        () => {
+          expect(wrapperCalls).toBeGreaterThanOrEqual(1);
+          expect(log.length).toBe(wrapperCalls * tenants.length);
+          drainedCalls = wrapperCalls;
+        },
+        { delays: [2000, 3000, 5000] },
+      );
     } finally {
-      // Stop immediately after catching the first tick so no further ticks
-      // can land mid-assertion — the invariant below still holds however
-      // many ticks slipped in before stop() took effect.
       await runnerA.stop();
       await runnerB.stop();
       await rawQueue.close();
     }
-    await sleep(300); // let any in-flight children land
 
     // Secondary sanity check only — this ratio holds whether the wrapper
     // fired once or twice per tick (wrapperCalls scales with it either
     // way), so it does not by itself prove the once-per-tick invariant.
     // It only confirms each wrapper run that did happen fanned out to
-    // every tenant exactly once.
-    expect(log.length).toBe(wrapperCalls * tenants.length);
-    const seenTenants = log.map((e) => e.tenantId).sort();
-    const expectedTenants = Array.from({ length: wrapperCalls }, () => tenants)
+    // every tenant exactly once. Slice to the drained prefix so a late
+    // tick that lands during stop() cannot break the multiset check.
+    expect(log.length).toBeGreaterThanOrEqual(drainedCalls * tenants.length);
+    const seenTenants = log
+      .slice(0, drainedCalls * tenants.length)
+      .map((e) => e.tenantId)
+      .sort();
+    const expectedTenants = Array.from({ length: drainedCalls }, () => tenants)
       .flat()
       .sort();
     expect(seenTenants).toEqual(expectedTenants);
@@ -1123,23 +1137,31 @@ describe("perTenant wrapper re-run for the same trigger", () => {
       queueNamePrefix,
       getActiveTenantIds,
     });
+    let drainedCalls = 0;
     try {
       await runner.start();
       // Two distinct ticks get two distinct repeat-job ids (different
       // millis) — each must still produce its own full batch of children;
       // a wrongly cross-tick dedup would collapse the second tick's log
       // entries into the first.
-      await waitFor(() => expect(wrapperCalls).toBeGreaterThanOrEqual(2), {
-        delays: [1500, 2000, 3000],
-      });
+      await waitFor(
+        () => {
+          expect(wrapperCalls).toBeGreaterThanOrEqual(2);
+          expect(log.length).toBe(wrapperCalls * tenants.length);
+          drainedCalls = wrapperCalls;
+        },
+        { delays: [1500, 2000, 3000] },
+      );
     } finally {
       await runner.stop();
     }
-    await sleep(300); // let any in-flight children land
 
-    expect(log.length).toBe(wrapperCalls * tenants.length);
-    const seenTenants = log.map((e) => e.tenantId).sort();
-    const expectedTenants = Array.from({ length: wrapperCalls }, () => tenants)
+    expect(log.length).toBeGreaterThanOrEqual(drainedCalls * tenants.length);
+    const seenTenants = log
+      .slice(0, drainedCalls * tenants.length)
+      .map((e) => e.tenantId)
+      .sort();
+    const expectedTenants = Array.from({ length: drainedCalls }, () => tenants)
       .flat()
       .sort();
     expect(seenTenants).toEqual(expectedTenants);

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

@@ -10,7 +10,7 @@ import {
   subjectIdToKey,
 } from "../../crypto";
 import { asRawClient, buildEntityTable, createEventStoreExecutor, createTenantDb } from "../../db";
-import { createEntity, createTextField, defineFeature } from "../../engine";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
 import { createEventsTable } from "../../event-store";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { purgeSearchDocumentsForSubject } from "../purge-subject";
@@ -30,6 +30,16 @@ const contactFeature = defineFeature("search-pii-probe", (r) => {
   r.entity("contact", contactEntity);
 });
 
+const ghostSearchEntity = createEntity({
+  table: "read_search_pii_ghosts_missing",
+  fields: {
+    label: createTextField({ required: true, maxLength: 100, personal: "self", find: "fuzzy" }),
+  },
+});
+const ghostSearchFeature = defineFeature("search-pii-ghost", (r) => {
+  r.entity("ghost", ghostSearchEntity);
+});
+
 let stack: TestStack;
 let kms: InMemoryKmsAdapter;
 const admin = TestUsers.admin;
@@ -161,4 +171,34 @@ describe("searchable PII derived index (#1610)", () => {
     const after = await stack.search.search(admin.tenantId, plain, { filterType: "contact" });
     expect(after.some((h) => String(h.entityId) === id)).toBe(false);
   });
+
+  test("purgeSearchDocumentsForSubject skips missing projection tables (fw#2550)", async () => {
+    const plain = "MissingTableStillPurges1610";
+    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);
+
+    const subject = { kind: "user" as const, userId: id };
+    await kms.eraseKey(subject);
+    // Ghost searchable entity never got DDL — must not abort the purge.
+    const registry = createRegistry([contactFeature, ghostSearchFeature]);
+    await expect(
+      purgeSearchDocumentsForSubject(
+        stack.db,
+        registry.features,
+        stack.search,
+        subjectIdToKey(subject),
+        subject,
+      ),
+    ).resolves.toBeUndefined();
+
+    const after = await stack.search.search(admin.tenantId, plain, { filterType: "contact" });
+    expect(after.some((h) => String(h.entityId) === id)).toBe(false);
+  });
 });

package/src/search/purge-subject.ts

@@ -15,6 +15,7 @@ import { collectSearchableSubjectFields } from "../crypto/subject-resolver";
 import type { DbRunner } from "../db/connection";
 import { resolveTableName } from "../db/entity-table-meta";
 import { executeRawQueryRead } from "../db/queries/raw-sql";
+import { tableExists } from "../db/schema-inspection";
 import type { FeatureDefinition } from "../engine/types";
 import type { EntityDefinition } from "../engine/types/fields";
 import type { EntityId, TenantId } from "../engine/types/identifiers";
@@ -139,6 +140,10 @@ export async function purgeSearchDocumentsForSubject(
       const fields = collectSearchableSubjectFields(entity);
       if (fields.length === 0) continue;
       const tableName = resolveTableName(entityName, entity, undefined);
+      // Same post-eraseKey hazard as nullBlindIndexesForSubject (fw#2550):
+      // a mounted feature without its migration must not abort the purge
+      // (and the audit event after it).
+      if (!(await tableExists(db, tableName))) continue;
       const predicate = buildSubjectPredicate(entity, fields, likePattern, subject);
       const rows = await collectMatchingRowsForEntity(
         db,

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

@@ -60,4 +60,45 @@ describe("waitFor", () => {
     );
     expect(calls).toBe(2);
   });
+
+  test("polls a boolean predicate until it returns true", async () => {
+    let calls = 0;
+    await waitFor(
+      () => {
+        calls++;
+        return calls >= 3;
+      },
+      { delays: [1, 1, 1] },
+    );
+    expect(calls).toBe(3);
+  });
+
+  test("throws a descriptive error when a predicate stays false for the whole schedule", async () => {
+    let calls = 0;
+    await expect(
+      waitFor(
+        () => {
+          calls++;
+          return false;
+        },
+        { delays: [1, 1] },
+      ),
+    ).rejects.toThrow("waitFor: condition never became true within the delay schedule");
+    expect(calls).toBe(3);
+  });
+
+  test("returns immediately for a block-style fn that returns undefined without throwing", async () => {
+    let calls = 0;
+    const events = [1];
+    const started = Date.now();
+    await waitFor(
+      () => {
+        calls++;
+        expect(events).toHaveLength(1);
+      },
+      { delays: [2000] },
+    );
+    expect(calls).toBe(1);
+    expect(Date.now() - started).toBeLessThan(500);
+  });
 });

package/src/testing/wait-for.ts

@@ -6,13 +6,18 @@
  * next try — so N delays yield N+1 attempts and the full backoff budget.
  * Throws the last assertion error if all attempts fail.
  *
- * Usage:
+ * Usage (assertion form):
  *   await waitFor(() => {
  *     expect(events).toHaveLength(1);
  *   });
+ *
+ * Usage (predicate form — a literal `false` return means "not yet", anything
+ * else, including `undefined`, counts as success):
+ *   await waitFor(() => events.length >= 4);
  */
 export async function waitFor(
-  fn: () => void | Promise<void>,
+  // biome-ignore lint/suspicious/noConfusingVoidType: void must stay in the union so the existing expect(...) block form (implicit void return) still type-checks
+  fn: () => void | boolean | Promise<void | boolean>,
   options?: { delays?: number[] },
 ): Promise<void> {
   const delays = options?.delays ?? [250, 1000, 3000];
@@ -23,9 +28,11 @@ export async function waitFor(
 
   for (let i = 0; ; i++) {
     try {
-      await fn();
-      // skip: condition already true — no further polling
-      return;
+      const result = await fn();
+      if (result !== false) {
+        // skip: condition already true — no further polling
+        return;
+      }
     } catch (err) {
       lastError = err;
     }
@@ -35,5 +42,8 @@ export async function waitFor(
     await new Promise((r) => setTimeout(r, delays[i]));
   }
 
-  throw lastError;
+  if (lastError !== undefined) {
+    throw lastError;
+  }
+  throw new Error("waitFor: condition never became true within the delay schedule");
 }