@cosmicdrift/kumiko-framework 0.340.0 → 0.342.0

package/dist/redis/index.d.ts

@@ -1,3 +1,7 @@
+export type { CacheSyncBus, CacheSyncBusOverSignalOptions, ClosableCacheSyncBus, RedisCacheSyncBusOptions, ResolvedCacheSyncBus, } from "./cache-sync-bus.js";
+export { createCacheSyncBusOverSignal, createDefaultCacheSyncBus, createLocalCacheSyncBus, createRedisCacheSyncBus, resolveCacheSyncBus, } from "./cache-sync-bus.js";
+export type { TenantConfigSyncMessage, TierAssignmentSyncMessage } from "./cache-sync-topics.js";
+export { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage, isTierAssignmentSyncMessage, } from "./cache-sync-topics.js";
 export type { RedisClientOptions } from "./client.js";
 export { createRedisClient, redisClientOptionsFromEnv } from "./client.js";
 export type { PubSubSignal, PubSubSignalOptions } from "./pubsub-signal.js";

package/dist/redis/index.js

@@ -1,2 +1,4 @@
+export { createCacheSyncBusOverSignal, createDefaultCacheSyncBus, createLocalCacheSyncBus, createRedisCacheSyncBus, resolveCacheSyncBus, } from "./cache-sync-bus.js";
+export { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage, isTierAssignmentSyncMessage, } from "./cache-sync-topics.js";
 export { createRedisClient, redisClientOptionsFromEnv } from "./client.js";
 export { createRedisPubSubSignal } from "./pubsub-signal.js";

package/dist/redis/pubsub-signal.d.ts

@@ -2,6 +2,7 @@ import { type RedisClientOptions } from "./client.js";
 export type PubSubSignal = {
     publish(channel: string, payload: unknown): void;
     onMessage(listener: (channel: string, payload: unknown) => void): void;
+    onReconnect(listener: () => void): void;
     close(): Promise<void>;
 };
 export type PubSubSignalOptions = {

package/dist/redis/pubsub-signal.js

@@ -14,6 +14,7 @@ export function createRedisPubSubSignal(opts) {
     publisher.on("error", logConnectionError(opts.label, "publisher"));
     subscriber.on("error", logConnectionError(opts.label, "subscriber"));
     const listeners = new Set();
+    const reconnectListeners = new Set();
     // Sole purpose: stop close() from racing the initial psubscribe (see
     // below) and silence its logging once a shutdown is already underway —
     // not a defense against ioredis auto-reconnecting later (quit() below
@@ -56,6 +57,30 @@ export function createRedisPubSubSignal(opts) {
         // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
         console.error(`[kumiko:${opts.label}] psubscribe failed:`, err);
     });
+    // ioredis re-sends the psubscribe itself (autoResubscribe) but emits no ack
+    // event; repeating it here queues behind that one on the same connection,
+    // so its reply means the subscription is live again.
+    let hasBeenReady = false;
+    subscriber.on("ready", () => {
+        if (!hasBeenReady) {
+            hasBeenReady = true;
+            // skip: the first ready is the initial connect, not a reconnect
+            return;
+        }
+        subscriber.psubscribe(opts.channelPattern).then(() => {
+            // skip: close() ran while the resubscribe was in flight
+            if (closed)
+                return;
+            for (const listener of reconnectListeners)
+                listener();
+        }, (err) => {
+            // skip: a close() already underway intentionally quit the connection
+            if (closed)
+                return;
+            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
+            console.error(`[kumiko:${opts.label}] resubscribe failed:`, err);
+        });
+    });
     return {
         publish(channel, payload) {
             publisher.publish(channel, JSON.stringify(payload)).catch((err) => {
@@ -70,6 +95,9 @@ export function createRedisPubSubSignal(opts) {
         onMessage(listener) {
             listeners.add(listener);
         },
+        onReconnect(listener) {
+            reconnectListeners.add(listener);
+        },
         async close() {
             closed = true;
             await initialSubscribe;

package/dist/schema-cli.d.ts

@@ -4,15 +4,17 @@ export type SchemaCliOut = {
     readonly err: (line: string) => void;
 };
 export type RunSchemaCliOptions = {
+    readonly features?: undefined;
+    readonly kmsSlots?: undefined;
+} | {
     /** Composed app features. When given, `apply` rebuilds the projections whose
      *  tables a freshly applied migration changed (via its `.rebuild.json`
      *  marker). Omitted (dev `kumiko schema`) → no rebuild, migrations only. */
-    readonly features?: readonly FeatureDefinition[];
-    /** Schema-declared Key Manager slots, typically `kmsSlotsOf(composedEnv.schema)`.
-     *  This CLI parses no env schema, so `apply`'s KMS wiring cannot derive them
-     *  itself; omitted, `resolvePlatformKeks` (inside `resolveKmsWiringAsync`)
-     *  falls back to its own default. */
-    readonly kmsSlots?: readonly string[];
+    readonly features: readonly FeatureDefinition[];
+    /** Schema-declared Key Manager slots, `kmsSlotsOf(composedEnv.schema)`, or
+     *  `[]` when the app wires none. This CLI parses no env schema, so the
+     *  rebuild's KMS wiring cannot derive them itself. */
+    readonly kmsSlots: readonly string[];
 };
 /**
  * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where

package/dist/schema-cli.js

@@ -10,7 +10,7 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve as resolvePath } from "node:path";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolveKmsWiringAsync, } from "./crypto/index.js";
-import { assertValidMigrationName, baselineMigrations, createDbConnection, diffReplayAgainstSnapshot, fetchAppliedMigrations, generateMigration, loadMigrationsFromDir, loadSnapshotJson, rebuildTablesFromDiff, replayMigrationsDir, runMigrationsFromDir, tableExists, writeRebuildMarker, writeSnapshotJson, } from "./db/index.js";
+import { assertValidMigrationName, baselineMigrations, createDbConnection, diffReplayAgainstSnapshot, fetchAppliedMigrations, findCommentedDropTables, generateMigration, isRetiredFrameworkTable, loadMigrationsFromDir, loadSnapshotJson, readMigrationSqlTexts, rebuildTablesFromDiff, replayMigrationsDir, runMigrationsFromDir, tableExists, writeRebuildMarker, writeSnapshotJson, } from "./db/index.js";
 import { validateBoot } from "./engine/boot-validator.js";
 import { createRegistry } from "./engine/registry.js";
 import { createEventsTable } from "./event-store/index.js";
@@ -49,12 +49,40 @@ function nextSequenceNumber(migrationsDir) {
     }
     return max + 1;
 }
+// A table that a migration only drops as a commented DESTRUCTIVE marker and
+// that the snapshot no longer has is gone on paper but still in the live DB.
+async function reportLeftoverDroppedTables(db, migrationsDir, out) {
+    const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
+    const snapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
+    const leftovers = [];
+    for (const tableName of findCommentedDropTables(readMigrationSqlTexts(migrationsDir), snapshot)) {
+        if (await tableExists(db, tableName))
+            leftovers.push(tableName);
+    }
+    // skip: nothing left over, nothing to report
+    if (leftovers.length === 0)
+        return;
+    out.log("  Tables dropped only as a commented DESTRUCTIVE marker but still in the database:");
+    for (const tableName of leftovers) {
+        out.log(isRetiredFrameworkTable(tableName)
+            ? `    ! ${tableName} — retired framework table: the next \`schema generate <name>\` creates the drop`
+            : `    ! ${tableName} — app table: after a backup, write a new migration with the drop`);
+    }
+    out.log("");
+}
 const SCHEMA_SUBCOMMANDS = ["generate", "validate", "apply", "baseline", "status"];
 /**
  * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where
  * `kumiko/schema.ts` + `kumiko/migrations/` live). Returns a process exit code.
  */
 export async function runSchemaCli(argv, appCwd, out, options = {}) {
+    // Runtime guard for untyped callers: the rebuild after `apply` needs the
+    // slots, and failing there would leave migrations applied but unrebuilt.
+    if (options.features && !options.kmsSlots) {
+        out.err("runSchemaCli: `features` requires `kmsSlots` — pass kmsSlots: kmsSlotsOf(<composedEnv>.schema), " +
+            "or [] when the app wires no Key Manager slots.");
+        return 1;
+    }
     // runProdApp/runDevApp install this at boot; the standalone CLI (the
     // migrate-db initContainer, `bun kumiko.js schema apply`) never goes through
     // that boot path, so a projection rebuild's tz/timestamp coercion throws
@@ -114,10 +142,12 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 prevSnapshot,
                 name,
                 sequenceNumber: nextSequenceNumber(migrationsDir),
+                priorMigrationsSql: readMigrationSqlTexts(migrationsDir),
             });
             const isEmpty = result.diff.newTables.length === 0 &&
                 result.diff.changedTables.length === 0 &&
-                result.diff.droppedTables.length === 0;
+                result.diff.droppedTables.length === 0 &&
+                result.retiredDrops.length === 0;
             if (isEmpty) {
                 out.log("  No schema changes detected — kein neues Migration-File geschrieben.");
                 return 0;
@@ -133,7 +163,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             writeRebuildMarker(migrationsDir, result.filename, rebuildTables);
             out.log("");
             out.log(`  ✓ ${result.filename}`);
-            out.log(`    new tables: ${result.diff.newTables.length}, changed: ${result.diff.changedTables.length}, dropped: ${result.diff.droppedTables.length}`);
+            out.log(`    new tables: ${result.diff.newTables.length}, changed: ${result.diff.changedTables.length}, dropped: ${result.diff.droppedTables.length}, retired framework tables dropped: ${result.retiredDrops.length}`);
             if (rebuildTables.length > 0) {
                 out.log(`    rebuild-marker: ${result.filename.replace(/\.sql$/, ".rebuild.json")} (${rebuildTables.length} table(s))`);
             }
@@ -182,11 +212,13 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 prevSnapshot,
                 name: "validate",
                 sequenceNumber: nextSequenceNumber(migrationsDir),
+                priorMigrationsSql: readMigrationSqlTexts(migrationsDir),
             });
             const pendingTables = [
                 ...drift.diff.newTables.map((t) => t.tableName),
                 ...drift.diff.changedTables.map((t) => t.tableName),
                 ...drift.diff.droppedTables,
+                ...drift.retiredDrops.map((t) => t.tableName),
             ];
             if (pendingTables.length === 0) {
                 out.log("  ✓ schema: migrations match the entity definitions");
@@ -308,7 +340,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                     wiring = await resolveKmsWiringAsync(process.env, {
                         logPrefix: "[kumiko schema apply]",
                         log: out.log,
-                        ...(options.kmsSlots && { slots: options.kmsSlots }),
+                        slots: options.kmsSlots,
                     });
                     if ("kms" in wiring) {
                         configurePiiSubjectKms(wiring.kms);
@@ -398,6 +430,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 out.log("");
                 out.log(`  ${applied.size} applied, ${pending} pending.`);
                 out.log("");
+                await reportLeftoverDroppedTables(db, migrationsDir, out);
                 return pending === 0 ? 0 : 1;
             }
             finally {

package/dist/stack/redis.d.ts

@@ -9,4 +9,9 @@ export type TestRedis = {
     cleanup: () => Promise<void>;
 };
 export declare function queueNamePrefixForTestRedis(keyPrefix: string): string;
-export declare function createTestRedis(): Promise<TestRedis>;
+export type CreateTestRedisOptions = {
+    /** Reuse another stack's keyPrefix on a fresh connection. cleanup() then only
+     *  disconnects — the owning stack flushes the namespace and its queues. */
+    readonly borrowKeyPrefix?: string;
+};
+export declare function createTestRedis(opts?: CreateTestRedisOptions): Promise<TestRedis>;

package/dist/stack/redis.js

@@ -6,13 +6,13 @@ import { requireEnv } from "./db.js";
 export function queueNamePrefixForTestRedis(keyPrefix) {
     return keyPrefix.split(":").filter(Boolean).join("-");
 }
-export async function createTestRedis() {
+export async function createTestRedis(opts = {}) {
     const Redis = (await import("ioredis")).Redis;
     const redisUrl = requireEnv("REDIS_URL");
     // Every test gets a per-file key prefix on a shared DB (no DB-pool-of-15
     // round-robin). Collisions at birthday-paradox rates are gone — the
     // prefix space is unbounded. See Track B.3 in docs/plans/tests-refactor.
-    const prefix = `kt:${generateId().slice(-8)}:`;
+    const prefix = opts.borrowKeyPrefix ?? `kt:${generateId().slice(-8)}:`;
     const redis = new Redis(redisUrl, { keyPrefix: prefix });
     async function deleteKeysMatching(pattern) {
         // Open a prefix-less client for the scan — ioredis' keyPrefix is applied
@@ -38,6 +38,11 @@ export async function createTestRedis() {
         keyPrefix: prefix,
         flushNamespace,
         cleanup: async () => {
+            if (opts.borrowKeyPrefix !== undefined) {
+                redis.disconnect();
+                // skip: the owning stack flushes the shared namespace and its queues
+                return;
+            }
             await flushNamespace();
             // The derived per-stack JobRunner queues sit outside the keyPrefix.
             await deleteKeysMatching(`bull:${queueNamePrefixForTestRedis(prefix)}-*`);

package/dist/stack/test-stack.d.ts

@@ -7,6 +7,7 @@ import { type JobRunner, type JobRunnerOptions } from "../jobs/index.js";
 import type { Lifecycle } from "../lifecycle/index.js";
 import { type ObservabilityProvider } from "../observability/index.js";
 import type { Dispatcher, EventDispatcher } from "../pipeline/index.js";
+import { type ClosableCacheSyncBus } from "../redis/cache-sync-bus.js";
 import type { SearchAdapter } from "../search/types.js";
 import { type EventCollector } from "./event-collector.js";
 import { type TestRedis } from "./redis.js";
@@ -17,6 +18,7 @@ export type TestStack = {
     registry: Registry;
     db: import("../db/index.js").DbConnection;
     redis: TestRedis;
+    cacheSync: ClosableCacheSyncBus;
     search: SearchAdapter;
     events: EventCollector;
     http: RequestHelper;
@@ -157,5 +159,18 @@ export type TestStackOptions = {
     /** Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops`
      *  — see there. Default 0. */
     trustedProxyHops?: number;
+    /** Second stack on the Redis namespace of `owner`: own connection, same
+     *  keyPrefix, so rate-limit buckets, locks, idempotency keys and the
+     *  cache-sync channel are shared across both. The derived
+     *  queueNamePrefix is identical too, so both stacks share BullMQ queues.
+     *  Cleanup only disconnects; the owner flushes the namespace and queues, so
+     *  clean up the borrowing stack first. The DB is NOT shared — pass the same
+     *  `dbName` + `persistentDb` for that. */
+    sharedRedisWith?: TestStack;
+    /** Publish/receive cache invalidations (tenant timezone, file providers,
+     *  tier sets) over Redis Pub/Sub, namespaced by this stack's keyPrefix.
+     *  Implied by `sharedRedisWith`; set it on the owner stack too, or its writes
+     *  never reach the borrower. Without it the stack uses a process-local bus. */
+    cacheSync?: boolean;
 };
 export declare function setupTestStack(options: TestStackOptions): Promise<TestStack>;

package/dist/stack/test-stack.js

@@ -7,6 +7,7 @@ import { createJobRunner } from "../jobs/index.js";
 import { createNoopProvider } from "../observability/index.js";
 import { createEntityCache, createEventDedup, createIdempotencyGuard, dispatcherToWriteRef, } from "../pipeline/index.js";
 import { createRateLimitResolver } from "../rate-limit/index.js";
+import { createLocalCacheSyncBus, createRedisCacheSyncBus, } from "../redis/cache-sync-bus.js";
 import { createInMemorySearchAdapter } from "../search/index.js";
 import { createTestDb } from "./db.js";
 import { createJobFailureTracker, drainJobs } from "./drain-jobs.js";
@@ -39,7 +40,7 @@ export async function setupTestStack(options) {
             ...(options.dbName !== undefined && { dbName: options.dbName }),
             ...(options.persistentDb !== undefined && { persistent: options.persistentDb }),
         }),
-        createTestRedis(),
+        createTestRedis(options.sharedRedisWith && { borrowKeyPrefix: options.sharedRedisWith.redis.keyPrefix }),
     ]);
     // Any throw in this DDL region must still drop the just-created ephemeral
     // DB/Redis — the caller never gets the stack object back to call
@@ -103,6 +104,16 @@ export async function setupTestStack(options) {
         }
         throw error;
     }
+    // Redis only where two stacks can actually disagree (avoids two extra
+    // Pub/Sub connections); otherwise a local bus so invalidation still works
+    // inside this stack. Passing it explicitly keeps buildServer from using its
+    // REDIS_URL default (an unnamespaced channel).
+    const cacheSync = options.cacheSync || options.sharedRedisWith
+        ? createRedisCacheSyncBus({
+            redisUrl: testRedis.redisUrl,
+            channelPrefix: testRedis.keyPrefix,
+        })
+        : createLocalCacheSyncBus();
     const searchAdapter = createInMemorySearchAdapter();
     const events = createEventCollector();
     const registry = createRegistry([...options.features]);
@@ -262,6 +273,7 @@ export async function setupTestStack(options) {
             ...(options.observability ? { observability: options.observability } : {}),
             dispatcherOptions: {
                 idempotency,
+                cacheSync,
                 ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
                 ...(jobRunner && { jobRunner }),
             },
@@ -338,6 +350,7 @@ export async function setupTestStack(options) {
             registry,
             db: testDb.db,
             redis: testRedis,
+            cacheSync,
             search: searchAdapter,
             events,
             http,
@@ -355,6 +368,7 @@ export async function setupTestStack(options) {
                 if (eventDispatcher)
                     await eventDispatcher.stop();
                 await server.observability.shutdown();
+                await cacheSync.close();
                 await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
             },
         };
@@ -375,6 +389,12 @@ export async function setupTestStack(options) {
                 // ignore — `error` is the one that matters
             }
         }
+        try {
+            await cacheSync.close();
+        }
+        catch {
+            // ignore — `error` is the one that matters
+        }
         try {
             await testDb.cleanup();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.340.0",
+  "version": "0.342.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>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.340.0",
-    "@cosmicdrift/kumiko-types": "0.340.0",
+    "@cosmicdrift/kumiko-http": "0.342.0",
+    "@cosmicdrift/kumiko-types": "0.342.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.340.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.342.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,79 @@
 [
+  {
+    "version": "0.342.0",
+    "type": "improvement",
+    "title": "System cron escape hatches are audited once per process, with a use counter and audit retention",
+    "detail": "System crons audit their declared escape hatch once per process; audit events get a retention\nA cron job with a declared `escapeHatch` that uses `unsafeRaw()` or `db.global()` writes one `audit:event:escape-hatch-used` per process, handler and tenant instead of one per run. Manual runs by a user, identity switches, `acknowledge-cross-tenant` and `unsafe-all-tenants` keep the 60-second dedup window. Every use, audited or not, counts in the new metric `kumiko_escape_hatch_uses_total{handler,kind}`; `createEscapeHatchReporter` takes optional `processDedup`, `meter` and `now` for this. The audit feature gains a daily job `audit:job:escape-hatch-retention` that removes `escapeHatchUse` events through `pruneEvents`, with the period in the system config key `audit:config:escape-hatch-retention-days` (default 90). A new runbook, `docs/runbooks/kumiko-events-bloat.md`, shows how to measure `kumiko_events` bloat and reclaim the space.",
+    "migration": "The first run of `audit:job:escape-hatch-retention` deletes `escapeHatchUse` events older than 90 days. To keep them longer, set the system config key `audit:config:escape-hatch-retention-days` (for example through an app override) before the bump rolls out. The audit feature now also requires the `config` feature, which every app with `tenant` already mounts."
+  },
+  {
+    "version": "0.342.0",
+    "type": "breaking",
+    "title": "Key Manager slots are required, LEGACY_SLOTS default removed",
+    "detail": "Key Manager slots are required: no more LEGACY_SLOTS default\n`resolvePlatformKeks`, `resolveKmsWiringAsync` and `requireKmsWiringAsync` no longer fall back to the three platform slots; `slots` is a required option. `runSchemaCli` called with `features` now requires `kmsSlots` and exits 1 with a hint before any DB connect or migration apply when it is missing. `kmsSlots: []` stays valid for apps that wire no Key Manager slots. The scaffolded `bin/kumiko.ts` passes `kmsSlots` derived from the composed env schema.",
+    "migration": "Pass `slots` (for example `kmsSlotsOf(<app>ComposedEnv.schema)`) to `resolvePlatformKeks`, `resolveKmsWiringAsync` and `requireKmsWiringAsync`. In `bin/kumiko.ts`, `runSchemaCli(..., { features })` needs `kmsSlots: kmsSlotsOf(<app>ComposedEnv.schema)` (or `[]` when the app wires no Key Manager slots. With `[]` every `*_CIPHERTEXT` env var is ignored, so an app that ships a ciphertext must pass its slots); without it the CLI exits 1 before applying migrations.\nWorkspace state at release: show-pony `bin/kumiko.ts` and its docs copy `kumiko-platform/apps/docs/_samples/show-pony/bin/kumiko.ts` still call `runSchemaCli` with `features` only. publicstatus, solon, offlot-app, money-horse, phronexsis and kumiko-studio already pass `kmsSlots` / `slots`."
+  },
+  {
+    "version": "0.342.0",
+    "type": "fix",
+    "title": "Retired framework tables (read_job_runs) are dropped by the next schema generate",
+    "detail": "`kumiko schema generate` now writes an executable `DROP TABLE IF EXISTS \"read_job_runs\";` for retired framework tables (new `retiredFrameworkTables` list next to the migration code). Until now the drop stayed a commented `-- DESTRUCTIVE:` marker in every app, so the table lived on forever. A retired table is dropped only if an earlier migration created it or carries the commented drop, no earlier migration dropped it for real, and the schema no longer declares it. App tables stay commented out. `generate` writes a migration even when the retired drop is its only content, and `schema validate` reports it as pending. `kumiko schema status` now lists tables that a migration only drops as a commented marker but that still exist in the database, with a hint per case.",
+    "migration": "Run `kumiko schema generate <name>` in publicstatus, solon, money-horse, phronexsis, show-pony and kumiko-studio, review and commit the drop of read_job_runs (old job run history is not preserved), then apply."
+  },
+  {
+    "version": "0.342.0",
+    "type": "fix",
+    "title": "Soft-delete cleanup works for global tables such as user",
+    "detail": "Soft-delete cleanup no longer aborts on `tenancy: \"global\"` tables\n`soft-delete:job:cleanup` aborted for a tenant as soon as an entity with `tenancy: \"global\"` and a `tenantId` column (such as `user`) had softDelete enabled, so the tenant's other entities were not cleaned either. Both cleanup jobs now decide by the entity's tenancy declaration. The per-tenant job skips global tables; `soft-delete:job:cleanup-system` hard-deletes their expired rows once, system-wide, through `db.global()`. Jobs can now receive the `globalWrites` grant from their `escapeHatch` declaration.\nThe first run of `soft-delete:job:cleanup-system` after the update hard-deletes soft-deleted users older than the fixed 30-day grace period in every app with the user feature. Earlier versions never removed them.",
+    "migration": "None required. The first nightly run of `soft-delete:job:cleanup-system` after the bump hard-deletes soft-deleted users older than 30 days; restore any you still need before it runs."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "rowIdOf on extendEntityProjection for derived row ids",
+    "detail": "`r.extendEntityProjection` accepts `rowIdOf`, the row id the extension's applies write for events on its `sources` when that id is not the aggregate id (for example a tenant-salted `uuidv5(tenantId|aggregateId)` over workflow events). The ghost-row guard of the projection rebuild now counts a live row as backed when its id is `rowIdOf` of a source event, so such projections can be rebuilt instead of aborting. The guard stays strict: a row keyed by the raw aggregate id of a derived source still aborts the rebuild.\n`rowIdOf` requires `sources`, must not name the entity's own stream, and must return a uuid; a source shared by several extensions needs the same `rowIdOf` in all of them. Violations fail at boot. `ProjectionDefinition` carries the result as `extraSourceRowIds`, and `assertNoUnreachableLiveRows` takes it as an optional fifth parameter. New type `ProjectionRowIdOf`."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "CacheSyncBus keeps tier assignments and file providers in sync across pods",
+    "detail": "A Redis-backed CacheSyncBus (one channel, envelope with origin id, echo dropped, malformed messages ignored) now carries typed invalidation topics between pods and fires a debounced resync after a Redis reconnect. Tier assignments are published after commit and reloaded on the other pods with a per-tenant out-of-order guard; the tier cache is swapped atomically on resync. The file provider resolver drops cached providers when tenant config or secrets change on any pod. Prod, worker and dev entrypoints wire one bus per process, and TierResolverPlugin.build accepts an optional cacheSync."
+  },
+  {
+    "version": "0.341.0",
+    "type": "fix",
+    "title": "L3 rate-limit backend failure answers 503 rate_limit_unavailable instead of 500"
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "r.httpRoute rateLimit option",
+    "detail": "Per-IP limit enforced through the rate-limit resolver before the route guards; legal-pages and GET /user-export/by-token declare defaults."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "Tenant timezone cache is invalidated across processes",
+    "detail": "A config write to tenant:config:timezone now invalidates the cached value on every API and worker pod after commit, instead of letting it live until the 5 minute TTL. The signal travels over the new CacheSyncBus (Redis when REDIS_URL is set, process-local otherwise); DispatcherOptions.cacheSync overrides it and null opts out. setupTestStack gains cacheSync, implied by sharedRedisWith, to test two instances on one Redis. This replaces the earlier tenantTimezoneSync option."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "Per-recipient rate limits on payload fields (additionalRateLimits)",
+    "detail": "Write handlers can declare `additionalRateLimits: [{ per: { payloadField: \"email\" }, limit, windowSeconds }]` next to `rateLimit`. The named string field of the validated payload is trimmed, lowercased and HMAC-hashed (key derived from the server's current JWT signing secret) into the bucket key `payload+handler:<handler>:<field>:<digest>`, so one address is limited across all IPs and Redis never holds it in plaintext. The check runs after schema validation and before the handler, answers 429 `rate_limited`, behaves the same for matching and non-matching values, and is skipped for system callers. Rotating the JWT secret only resets these buckets.\nBoot rejects `additionalRateLimits` on an anonymous handler without a real ip-keyed `rateLimit` (the payload bucket only complements the IP bucket), an empty list, a `payloadField` that is not a field of the Zod object schema, and a non-positive `limit` or `windowSeconds`. A handler with `additionalRateLimits` makes `buildServer` wire the rate-limit resolver. The option exists on write handlers only and appears in the feature-ast patterns, render and patch schema.\nBehavior change: `request-contract-termination` and `signup-request` now allow 3 requests per email address per 24 hours, and each token-request endpoint (`request-password-reset`, `request-email-verification`, `request-account-unlock`) allows 5 per address per 24 hours, in addition to the existing per-IP limits. The public `/api/auth` token-request routes still answer `{ isSuccess: true }` when the limit is hit; only the mail is not sent."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "429 bodies omit the payload bucket digest",
+    "detail": "A 429 caused by a payload bucket (`additionalRateLimits`) no longer carries the HMAC digest of the bucketed value in `details.bucket` or the error message: it reads `payload+handler`. The digest is a stable pseudonym of the address, so anyone who could guess an address could confirm it from the response. Redis keys are unchanged.\n`waitlist:write:submit` additionally limits each email address (case-insensitive) to 3 submits per day, across all IPs, so a botnet cannot flood one address with confirmation mails. `createWaitlistFeature({ emailRateLimits })` overrides it (`[]` disables). The admin notice mail now carries its `locale` (`en` or `de`) in the notify call."
+  },
+  {
+    "version": "0.341.0",
+    "type": "fix",
+    "title": "429 bodies carry only the rate-limit scope",
+    "detail": "429 bodies (`details.bucket` and the message) now carry only the bucket scope tag (`l1`, `http`, `l2`, `user`, `ip+handler`, `payload+handler`, ...) instead of IP, user/tenant id, auth target or payload digest. Fail-closed logging prints only the error message, since Redis errors can carry the bucket key. Redis keys are unchanged."
+  },
   {
     "version": "0.340.0",
     "type": "improvement",