@cosmicdrift/kumiko-framework 0.220.1 → 0.222.0

package/src/pipeline/__tests__/event-dispatcher-pg-listen.integration.test.ts

@@ -1,36 +1,18 @@
 // E.4 — PG LISTEN/NOTIFY wake-up. Without this, delivery latency is
 // bounded below by pollIntervalMs. With LISTEN, event-store.append fires
-// `pg_notify` on commit and any subscribed dispatcher wakes immediately —
-// latency becomes TCP round-trip, typically sub-millisecond on localhost.
+// `pg_notify` on commit and any subscribed dispatcher wakes immediately.
 //
-// The polling timer stays on as a safety net for dropped subscriptions
-// and crashes between commit and wake. These tests pin:
-//
-//   1. NOTIFY → runOnce fires promptly, without waiting for the timer.
-//   2. The dispatcher starts cleanly when pgClient is wired and stops
-//      without leaking the LISTEN connection, and still wakes on NOTIFY
-//      after a restart cycle.
-//
-// #2042: these used to assert an absolute millisecond latency bound
-// (`< 40`, later `< 100`) against the test-stack's default 50ms polling
-// timer. On a shared CI runner a stalled event loop can push even a
-// working LISTEN's delivery past 100ms — measured up to 154ms — so no
-// millisecond bound both clears runner noise and stays under a 50ms
-// timer. Fix: push the polling timer out to 60s for this stack
-// (`eventDispatcherPollIntervalMs`) and assert delivery happens at all
-// inside a 5s window. If LISTEN is dead, nothing arrives before the 5s
-// deadline — a 12x margin under the 60s timer that no runner stall gets
-// anywhere near. If LISTEN works, delivery is near-instant regardless of
-// runner load. Verified by temporarily forcing pgClient to undefined in
-// test-stack.ts: both tests then fail at toHaveLength(1) with 0 received
-// after ~5s, confirming the assertion still discriminates.
+// The polling timer stays as a safety net. These tests pin NOTIFY wake
+// without waiting for the timer, and that start/stop still leaves LISTEN
+// working. #2042: poll interval is 60s here; assert delivery inside 5s —
+// if LISTEN is dead the timer cannot rescue the assertion.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { createTenantDb, type TenantDb } from "../../db/tenant-db";
 import { defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
-import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+import { sharedWidgetEntity, sharedWidgetTable, waitFor } from "../../testing";
 
 // --- Fixture ---
 
@@ -85,21 +67,22 @@ describe("E.4 — PG NOTIFY/LISTEN wake-up", () => {
     try {
       await executor.create({ name: "latency-test" }, admin, tdb);
 
-      const deadline = Date.now() + 5000;
-      while (Date.now() < deadline && deliveryCount === 0) {
-        await new Promise((r) => setTimeout(r, 5));
-      }
-      expect(deliveryCount).toBe(1);
+      await waitFor(
+        () => {
+          expect(deliveryCount).toBe(1);
+        },
+        { delays: [100, 500, 1000, 3500] },
+      );
     } finally {
       await stack.eventDispatcher?.stop();
     }
   });
 
   test("dispatcher start/stop cycle with LISTEN attached still delivers after restart", async () => {
-    // Repeated start/stop must not leak connections or break LISTEN. After
-    // 3 cycles the last .start() should still wake on NOTIFY — if the
-    // unlisten handle was mishandled, the subscription would either be
-    // stale (LISTEN on a closed connection) or double-registered.
+    // Repeated start/stop must not leak connections or break LISTEN.
+    // Two start/stop cycles, then a third start() that must still wake on
+    // NOTIFY — if the unlisten handle was mishandled, the subscription
+    // would be stale or double-registered.
     for (let i = 0; i < 2; i++) {
       await stack.eventDispatcher?.start();
       await stack.eventDispatcher?.stop();
@@ -110,11 +93,12 @@ describe("E.4 — PG NOTIFY/LISTEN wake-up", () => {
     try {
       await executor.create({ name: "restart-probe" }, admin, tdb);
 
-      const deadline = Date.now() + 5000;
-      while (Date.now() < deadline && deliveryCount === 0) {
-        await new Promise((r) => setTimeout(r, 5));
-      }
-      expect(deliveryCount).toBe(1);
+      await waitFor(
+        () => {
+          expect(deliveryCount).toBe(1);
+        },
+        { delays: [100, 500, 1000, 3500] },
+      );
     } finally {
       await stack.eventDispatcher?.stop();
     }

package/src/pipeline/__tests__/tenant-timezone-cache.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import type { TenantId } from "../../engine/types/identifiers";
+import { createTenantTimezoneCache } from "../tenant-timezone-cache";
+
+const tenantA = "tenant-a" as TenantId;
+const tenantB = "tenant-b" as TenantId;
+
+describe("TenantTimezoneCache", () => {
+  test("miss on an unset tenant", () => {
+    const cache = createTenantTimezoneCache();
+    expect(cache.get(tenantA)).toBeUndefined();
+  });
+
+  test("hit returns the cached value, including a cached 'no override' (undefined)", () => {
+    const cache = createTenantTimezoneCache();
+    cache.set(tenantA, "Asia/Tokyo");
+    cache.set(tenantB, undefined);
+
+    expect(cache.get(tenantA)).toEqual({ value: "Asia/Tokyo" });
+    // Distinct from a miss: tenantB was looked up and confirmed unset.
+    expect(cache.get(tenantB)).toEqual({ value: undefined });
+  });
+
+  test("invalidate() drops only the given tenant", () => {
+    const cache = createTenantTimezoneCache();
+    cache.set(tenantA, "Asia/Tokyo");
+    cache.set(tenantB, "Europe/Berlin");
+
+    cache.invalidate(tenantA);
+
+    expect(cache.get(tenantA)).toBeUndefined();
+    expect(cache.get(tenantB)).toEqual({ value: "Europe/Berlin" });
+  });
+
+  test("clear() drops every tenant", () => {
+    const cache = createTenantTimezoneCache();
+    cache.set(tenantA, "Asia/Tokyo");
+    cache.set(tenantB, "Europe/Berlin");
+
+    cache.clear();
+
+    expect(cache.size()).toBe(0);
+    expect(cache.get(tenantA)).toBeUndefined();
+    expect(cache.get(tenantB)).toBeUndefined();
+  });
+
+  test("entry expires after ttlMs", () => {
+    let t = 1_000_000;
+    const cache = createTenantTimezoneCache({ ttlMs: 1000, now: () => t });
+    cache.set(tenantA, "Asia/Tokyo");
+
+    expect(cache.get(tenantA)).toEqual({ value: "Asia/Tokyo" });
+
+    t += 1500;
+    expect(cache.get(tenantA)).toBeUndefined();
+  });
+
+  test("LRU: evicts oldest tenant when maxEntries is reached", () => {
+    const cache = createTenantTimezoneCache({ maxEntries: 2, ttlMs: 60_000 });
+    cache.set("a" as TenantId, "UTC");
+    cache.set("b" as TenantId, "UTC");
+    expect(cache.size()).toBe(2);
+
+    cache.set("c" as TenantId, "UTC");
+    expect(cache.size()).toBe(2);
+    expect(cache.get("a" as TenantId)).toBeUndefined();
+    expect(cache.get("c" as TenantId)).toEqual({ value: "UTC" });
+  });
+
+  test("LRU: touching an entry (get) moves it to the 'most recent' end", () => {
+    const cache = createTenantTimezoneCache({ maxEntries: 2, ttlMs: 60_000 });
+    cache.set("a" as TenantId, "UTC");
+    cache.set("b" as TenantId, "UTC");
+    cache.get("a" as TenantId); // touch a — b is now the oldest
+
+    cache.set("c" as TenantId, "UTC");
+
+    expect(cache.get("b" as TenantId)).toBeUndefined();
+    expect(cache.get("a" as TenantId)).toEqual({ value: "UTC" });
+  });
+
+  test("default maxEntries is 1000", () => {
+    const cache = createTenantTimezoneCache();
+    for (let i = 0; i < 1001; i++) {
+      cache.set(`tenant-${i}` as TenantId, "UTC");
+    }
+    expect(cache.size()).toBe(1000);
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -75,13 +75,22 @@ import {
 } from "./dispatcher-utils";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
+import type { TenantTimezoneCache } from "./tenant-timezone-cache";
 
 // Framework/pipeline stays bundled-features-free, so this can't import the
 // `tenant` feature — the literal below IS the coupling to its `timezone`
 // config key. Renaming that key (or the "tenant" feature name) must update
 // this constant too; tenant-timezone-boot.integration.test.ts boots the real
 // createTenantFeature() and would catch a drift.
-const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";
+export const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";
+
+// Same bundled-features-free constraint as above — these name the config
+// feature's write handlers so dispatch-write.ts can invalidate
+// TENANT_TIMEZONE_CONFIG_KEY's cache entry on a successful write without
+// importing the `config` feature. tenant-timezone-boot.integration.test.ts
+// exercises both against the real config feature.
+export const CONFIG_WRITE_SET_TYPE = "config:write:set";
+export const CONFIG_WRITE_RESET_TYPE = "config:write:reset";
 
 export type BatchCommand = {
   readonly type: string;
@@ -110,6 +119,7 @@ export type DispatchContext = {
   sseBroker: SseBroker | undefined;
   tableCache: Map<string, ReturnType<typeof buildEntityTable>>;
   transitionCache: Map<string, ReturnType<typeof defineTransitions>>;
+  tenantTimezoneCache: TenantTimezoneCache;
   tracer: ReturnType<typeof getFallbackTracer>;
   meter: ReturnType<typeof getFallbackMeter>;
 };
@@ -606,7 +616,34 @@ export async function buildHandlerContext(
   // comes from SessionUser.timezone (set at login), else falls back to
   // tenant (createTzContext's own default). An app-injected GeoTzProvider
   // (context.geoTzProvider) feeds ctx.tz.fromCoordinates / fromAddress.
-  const tenantTz = config !== undefined ? await config(TENANT_TIMEZONE_CONFIG_KEY) : undefined;
+  //
+  // Resolving this via `config()` is a config-table SELECT on every single
+  // dispatch (fw#2462) — ctx.tenantTimezoneCache memoizes it per tenant.
+  // dispatch-write.ts invalidates on config:write:set/reset for this key.
+  // Only populate from a tx-free read (tx === undefined): a write-path
+  // lookup runs inside the caller's own open transaction, and caching a
+  // value read there could memoize state from a write earlier in that same
+  // transaction before it's known to commit. Reads always consult the
+  // cache regardless of tx, since serving a slightly stale cached value on
+  // the write path is harmless (bounded by ttlMs) and avoids reintroducing
+  // the SELECT on the hot path this fix targets.
+  let tenantTz: unknown;
+  if (config === undefined) {
+    tenantTz = undefined;
+  } else {
+    const cachedTz = ctx.tenantTimezoneCache.get(user.tenantId);
+    if (cachedTz) {
+      tenantTz = cachedTz.value;
+    } else {
+      tenantTz = await config(TENANT_TIMEZONE_CONFIG_KEY);
+      if (tx === undefined) {
+        ctx.tenantTimezoneCache.set(
+          user.tenantId,
+          typeof tenantTz === "string" ? tenantTz : undefined,
+        );
+      }
+    }
+  }
   // Guarded against garbage: an unvalidated string here (free-form config
   // key, legacy JWT claim predating validation) blows up every ctx.tz call
   // for the whole tenant with a RangeError. Fall back to UTC/tenant instead

package/src/pipeline/dispatch-write.ts

@@ -3,6 +3,7 @@ import { selectRowForUpdateById } from "../db/queries/entity-read";
 import { asEntityTableMeta, selectMany } from "../db/query";
 import { buildEntityTable, toSnakeCase } from "../db/table-builder";
 import { hasAccess } from "../engine/access";
+import { ConfigScopes } from "../engine/constants";
 import { checkWriteFieldRoles } from "../engine/field-access";
 import { defineTransitions, guardTransition } from "../engine/state-machine";
 import type { HandlerContext, SessionUser, WriteResult } from "../engine/types";
@@ -22,9 +23,12 @@ import { assertNoSecretLeak } from "../secrets";
 import type { DispatchContext } from "./dispatch-shared";
 import {
   buildHandlerContext,
+  CONFIG_WRITE_RESET_TYPE,
+  CONFIG_WRITE_SET_TYPE,
   checkFeatureEnabled,
   enforceRateLimit,
   runHandlerInstrumented,
+  TENANT_TIMEZONE_CONFIG_KEY,
 } from "./dispatch-shared";
 import {
   type AfterCommitHook,
@@ -73,6 +77,42 @@ function getTransitions(
   return transitions;
 }
 
+// A successful config:write:set/reset returns { key, scope, ... } — see
+// bundled-features/src/config/handlers/{set,reset}.write.ts. Narrows the
+// otherwise-`unknown` WriteResult.data so invalidateTenantTimezoneCache
+// below can check `key` without an unchecked cast.
+function isConfigWriteResultForKey(
+  data: unknown,
+  key: string,
+): data is { key: string; scope?: string } {
+  if (typeof data !== "object" || data === null || !("key" in data)) return false;
+  return (data as { key: unknown }).key === key; // @cast-boundary engine-payload
+}
+
+// fw#2462: dispatch-shared.ts caches the resolved tenant:config:timezone
+// value per tenant. A successful write to that key must drop the stale
+// entry — tenant/user scope only affects the writing tenant, system scope
+// changes the fallback every tenant without an override reads, so the
+// whole cache is dropped instead of just one entry.
+function invalidateTenantTimezoneCache(
+  ctx: DispatchContext,
+  type: string,
+  user: SessionUser,
+  result: WriteResult,
+): void {
+  // skip: failed write, nothing to invalidate
+  if (!result.isSuccess) return;
+  // skip: not a config:write:set/reset dispatch
+  if (type !== CONFIG_WRITE_SET_TYPE && type !== CONFIG_WRITE_RESET_TYPE) return;
+  // skip: write was for a different config key
+  if (!isConfigWriteResultForKey(result.data, TENANT_TIMEZONE_CONFIG_KEY)) return;
+  if (result.data.scope === ConfigScopes.system) {
+    ctx.tenantTimezoneCache.clear();
+  } else {
+    ctx.tenantTimezoneCache.invalidate(user.tenantId);
+  }
+}
+
 // Runs lifecycle hooks for a handler result. inTransaction hooks fire NOW
 // (they see the tx via ctx.db when batch/write opens a transaction).
 // afterCommit hooks are queued into `afterCommitHooks` for the caller to
@@ -450,6 +490,14 @@ async function executeWriteInner(
       const eventData = (parsed.data ?? {}) as DbRow; // @cast-boundary engine-payload
       afterCommitHooks.push(() => jobRunner.handleEvent(type, eventData, user));
     }
+
+    invalidateTenantTimezoneCache(ctx, type, user, result);
+    // Again after commit: a query landing between the drop above and the
+    // commit would read the pre-write row (tx not yet visible) and
+    // repopulate the cache with the stale value for a full TTL.
+    afterCommitHooks.push(async () => {
+      invalidateTenantTimezoneCache(ctx, type, user, result);
+    });
   }
 
   // Response-guard: block Secret<> leaks in write responses (SaveContext

package/src/pipeline/dispatcher.ts

@@ -13,6 +13,7 @@ import { executeStream } from "./dispatch-stream";
 import { type HandlerType, resolveType } from "./dispatcher-utils";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
+import { createTenantTimezoneCache } from "./tenant-timezone-cache";
 
 // Re-export for callers that reach for dispatcher-adjacent types (tests,
 // HTTP-layer stubs) — dispatch consumes these, grouping the type-surface
@@ -92,6 +93,9 @@ export function createDispatcher(
   // Pre-build tables and transition maps for auto-guard (avoid per-request allocation)
   const tableCache = new Map<string, ReturnType<typeof buildEntityTable>>();
   const transitionCache = new Map<string, ReturnType<typeof defineTransitions>>();
+  // One per dispatcher instance (not a module-level singleton) so caches
+  // never leak across separately-booted apps or test stacks.
+  const tenantTimezoneCache = createTenantTimezoneCache();
 
   const dispatcherTracer = context.tracer ?? getFallbackTracer();
   const dispatcherMeter = context.meter ?? getFallbackMeter();
@@ -109,6 +113,7 @@ export function createDispatcher(
     sseBroker,
     tableCache,
     transitionCache,
+    tenantTimezoneCache,
     tracer: dispatcherTracer,
     meter: dispatcherMeter,
   };

package/src/pipeline/distributed-lock.ts

@@ -50,6 +50,9 @@ export function createDistributedLock(
     },
 
     async renew(key, token, ttlSeconds) {
+      // EXPIRE with 0/negative deletes the key but still returns 1 — reject
+      // before we claim ownership while releasing the lock.
+      if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1) return false;
       const result = (await redis.eval(
         renewScript,
         1,

package/src/pipeline/tenant-timezone-cache.ts

@@ -0,0 +1,92 @@
+// Per-dispatcher in-process cache for the resolved tenant:config:timezone
+// value (fw#2462). dispatch-shared.ts's buildHandlerContext resolves that
+// key on every dispatch to build ctx.tz — without a cache that's a config
+// SELECT (sometimes two, cascade + fallback) per request, often inside an
+// open write transaction. A tenant-keyed TTL cache removes the steady-state
+// cost; dispatch-write.ts invalidates entries synchronously on
+// config:write:set/reset for this key, so the TTL below only covers writes
+// that bypass that path (migrations, seeds, direct DB edits).
+
+import type { TenantId } from "../engine/types/identifiers";
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 1000;
+
+export type TenantTimezoneCacheOptions = {
+  readonly ttlMs?: number;
+  // Cap on distinct tenants cached. On overflow, least-recently-used
+  // entries are evicted — mirrors secrets/dek-cache.ts.
+  readonly maxEntries?: number;
+  readonly now?: () => number;
+};
+
+export type TenantTimezoneCacheEntry = {
+  // The raw resolved config value, or undefined when the tenant has no
+  // override — undefined here is a cached fact ("looked up, no value"),
+  // distinct from a cache miss (get() returning undefined below).
+  readonly value: string | undefined;
+};
+
+export type TenantTimezoneCache = {
+  // Returns undefined on a cache miss (never looked up, or expired).
+  get(tenantId: TenantId): TenantTimezoneCacheEntry | undefined;
+  set(tenantId: TenantId, value: string | undefined): void;
+  invalidate(tenantId: TenantId): void;
+  // Drops every tenant's entry — used when a system-scope write changes
+  // the key, since the system row is the fallback default for every
+  // tenant without its own override (a system-scope change can affect
+  // all of them at once).
+  clear(): void;
+  size(): number;
+};
+
+export function createTenantTimezoneCache(
+  opts: TenantTimezoneCacheOptions = {},
+): TenantTimezoneCache {
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const now = opts.now ?? (() => Date.now());
+  // Map insertion order doubles as LRU order: touch = delete+re-insert.
+  const entries = new Map<TenantId, { value: string | undefined; expiresAt: number }>();
+
+  function evictOldestIfFull(): void {
+    // skip: cache has room, nothing to evict
+    if (entries.size < maxEntries) return;
+    const oldestKey = entries.keys().next().value;
+    // skip: defensive — only reachable if maxEntries is 0 (cache disabled) and entries is empty
+    if (oldestKey === undefined) return;
+    entries.delete(oldestKey);
+  }
+
+  return {
+    get(tenantId) {
+      const hit = entries.get(tenantId);
+      if (!hit) return undefined;
+      if (hit.expiresAt <= now()) {
+        entries.delete(tenantId);
+        return undefined;
+      }
+      entries.delete(tenantId);
+      entries.set(tenantId, hit);
+      return { value: hit.value };
+    },
+
+    set(tenantId, value) {
+      entries.delete(tenantId);
+      evictOldestIfFull();
+      entries.set(tenantId, { value, expiresAt: now() + ttlMs });
+    },
+
+    invalidate(tenantId) {
+      entries.delete(tenantId);
+    },
+
+    clear() {
+      entries.clear();
+    },
+
+    size() {
+      return entries.size;
+    },
+  };
+}

package/src/schema-cli.ts

@@ -11,15 +11,14 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve as resolvePath } from "node:path";
 import {
+  assertValidMigrationName,
   baselineMigrations,
   createDbConnection,
-  type DbConnection,
   diffReplayAgainstSnapshot,
   fetchAppliedMigrations,
   generateMigration,
   loadMigrationsFromDir,
   loadSnapshotJson,
-  readRebuildMarker,
   rebuildTablesFromDiff,
   type renderTablesDdl,
   replayMigrationsDir,
@@ -32,12 +31,8 @@ import { validateBoot } from "./engine/boot-validator";
 import { createRegistry } from "./engine/registry";
 import type { FeatureDefinition } from "./engine/types/feature";
 import { createEventsTable } from "./event-store";
-import { buildProjectionTableIndex } from "./migrations";
-import {
-  createEventConsumerStateTable,
-  createProjectionStateTable,
-  rebuildProjection,
-} from "./pipeline";
+import { queueRebuildsFromMarkers, runPendingRebuilds } from "./migrations";
+import { createEventConsumerStateTable, createProjectionStateTable } from "./pipeline";
 import { ensureTemporalPolyfill } from "./time";
 
 export type SchemaCliOut = {
@@ -85,33 +80,6 @@ function nextSequenceNumber(migrationsDir: string): number {
   return max + 1;
 }
 
-// Maps changed tables to their projections (via the app registry) and replays
-// the events. Tables without a registered projection are skipped.
-async function rebuildAffectedProjections(
-  db: DbConnection,
-  changedTables: readonly string[],
-  features: readonly FeatureDefinition[],
-  out: SchemaCliOut,
-): Promise<void> {
-  const registry = createRegistry(features);
-  const tableToProjection = buildProjectionTableIndex(registry);
-
-  const projections = new Set<string>();
-  for (const table of changedTables) {
-    const name = tableToProjection.get(table);
-    if (name) projections.add(name);
-  }
-  // skip: no changed table maps to a registered projection — nothing to rebuild.
-  if (projections.size === 0) return;
-
-  out.log(`  Rebuild ${projections.size} Projection(s)…`);
-  for (const name of projections) {
-    const r = await rebuildProjection(name, { db, registry });
-    out.log(`    ↻ ${name} (${r.eventsProcessed} events, ${r.durationMs}ms)`);
-  }
-  out.log("");
-}
-
 export type RunSchemaCliOptions = {
   /** Composed app features. When given, `apply` rebuilds the projections whose
    *  tables a freshly applied migration changed (via its `.rebuild.json`
@@ -151,10 +119,14 @@ export async function runSchemaCli(
         out.err("  Usage: schema generate <name>");
         return 1;
       }
-      // name lands unescaped in `${seq}_${name}.sql` (generateMigration) — this
-      // allowlist blocks flag-like names and path traversal (`../../x`).
-      if (name.startsWith("-") || !/^[A-Za-z0-9_-]+$/.test(name)) {
-        out.err(`  Invalid migration name "${name}" — use letters, digits, "-", "_" only.`);
+      // name lands unescaped in `${seq}_${name}.sql` (generateMigration) —
+      // shared allowlist blocks flag-like names, path traversal, and
+      // ENAMETOOLONG-length names.
+      try {
+        assertValidMigrationName(name);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        out.err(`  ${msg}`);
         out.err("  Usage: schema generate <name>");
         return 1;
       }
@@ -365,17 +337,36 @@ export async function runSchemaCli(
         out.log("");
 
         // Projection-rebuild for tables a freshly applied migration changed
-        // (marker NNNN_<name>.rebuild.json from `generate`). Without it read_*
-        // projections stay stale after a schema change. Needs the composed
+        // (marker NNNN_<name>.rebuild.json from `generate`). Needs the composed
         // feature set → only when the caller passed `features` (the app bin);
-        // the dev CLI omits it and applies migrations only.
-        if (options.features && result.applied.length > 0) {
-          const changedTables = new Set<string>();
-          for (const id of result.applied) {
-            for (const table of readRebuildMarker(migrationsDir, id)) changedTables.add(table);
+        // the dev CLI omits it and applies migrations only. Runs unconditionally
+        // (not gated on result.applied.length > 0): a persistent queue
+        // (kumiko_pending_rebuilds) survives a failed/crashed rebuild from an
+        // earlier apply, so a later apply with zero new migrations still must
+        // retry it — otherwise a failed rebuild is silently never retried,
+        // since the migration itself is already tracked applied (#2464).
+        if (options.features) {
+          const thisRunTables = await queueRebuildsFromMarkers(db, {
+            migrationsDir,
+            appliedIds: result.applied,
+          });
+          const registry = createRegistry(options.features);
+          const rebuildRun = await runPendingRebuilds(db, registry, { thisRunTables });
+          if (rebuildRun.rebuilt.length > 0) {
+            out.log(`  Rebuild ${rebuildRun.rebuilt.length} Projection(s)…`);
+            for (const r of rebuildRun.rebuilt) {
+              out.log(`    ↻ ${r.projection} (${r.eventsProcessed} events)`);
+            }
+            out.log("");
           }
-          if (changedTables.size > 0) {
-            await rebuildAffectedProjections(db, [...changedTables], options.features, out);
+          if (rebuildRun.failed.length > 0) {
+            throw new Error(
+              `Projection rebuild failed for: ${rebuildRun.failed
+                .map((f) => `${f.projection} (${f.error})`)
+                .join(
+                  "; ",
+                )}. Table(s) stay queued in kumiko_pending_rebuilds — retried on the next apply.`,
+            );
           }
         }
         return 0;