@cosmicdrift/kumiko-framework 0.340.0 → 0.342.0

package/dist/api/index.d.ts

@@ -21,7 +21,8 @@ export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker.j
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
 export { type RequestContextData, requestContext, runAsDirectCallEntry, } from "./request-context.js";
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
-export { DEFAULT_MAX_REQUEST_BYTES } from "./route-registrars.js";
+export type { MetricsRouteOptions } from "./route-registrars.js";
+export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
 export type { KumikoServer, ServerOptions } from "./server.js";
 export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server.js";

package/dist/api/index.js

@@ -12,7 +12,7 @@ export { isSafeLandingPath } from "./post-auth-landing.js";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
 export { requestContext, runAsDirectCallEntry, } from "./request-context.js";
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
-export { DEFAULT_MAX_REQUEST_BYTES } from "./route-registrars.js";
+export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
 export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server.js";
 export { createSseBroker } from "./sse-broker.js";

package/dist/api/route-registrars.d.ts

@@ -1,7 +1,7 @@
-import type { Hono } from "hono";
+import { Hono } from "hono";
 import type { DbConnection } from "../db/connection.js";
 import type { Lifecycle } from "../lifecycle/index.js";
-import type { Meter } from "../observability/index.js";
+import type { Meter, PrometheusMeter } from "../observability/index.js";
 import type { EventConsumer } from "../pipeline/event-dispatcher.js";
 export declare const DEFAULT_MAX_REQUEST_BYTES = 1048576;
 export declare function registerBodyLimit(app: Hono, maxBytes: number): void;
@@ -9,7 +9,9 @@ export type MetricsRouteOptions = {
     readonly token?: string;
     readonly path?: string;
 };
+export declare function isPrometheusMeter(m: Meter): m is PrometheusMeter;
 export declare function registerMetricsRoute(app: Hono, meter: Meter, options: MetricsRouteOptions): void;
+export declare function createMetricsApp(meter: Meter, options: MetricsRouteOptions): Hono;
 export declare function registerVersionRoute(app: Hono): void;
 export type HealthRoutesOptions = {
     readonly lifecycle?: Lifecycle;

package/dist/api/route-registrars.js

@@ -3,6 +3,7 @@
 // branches. Every registrar takes the Hono app + whatever state it
 // actually reads — no monolithic `options` parameter, because these
 // helpers exist to make each step's dependencies visible at the call-site.
+import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { serializeOpenMetrics } from "../observability/index.js";
 import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "./api-constants.js";
@@ -45,7 +46,7 @@ function constantTimeEqual(a, b) {
 // Type-guard: duck-types the meter on `snapshot()`. An alternative
 // Prometheus-compatible meter (future OTLP bridge) works without an
 // explicit union — if it exposes `snapshot()` it's serialisable.
-function isPrometheusMeter(m) {
+export function isPrometheusMeter(m) {
     return typeof m.snapshot === "function"; // @cast-boundary schema-walk
 }
 // Mount `/metrics` (or the caller-supplied path). Takes just the Meter —
@@ -73,6 +74,13 @@ export function registerMetricsRoute(app, meter, options) {
         return c.body(body);
     });
 }
+// Standalone fetch-handler serving only the scrape route — for HTTP-less
+// processes (worker pods) that expose /metrics on their own port.
+export function createMetricsApp(meter, options) {
+    const app = new Hono();
+    registerMetricsRoute(app, meter, options);
+    return app;
+}
 // --- /version ---------------------------------------------------------------
 // Anonymous endpoint that returns build-identity. Used by ops tooling
 // (prod-version.sh) and the Telegram deploy notification so nobody needs

package/dist/api/server.d.ts

@@ -1,3 +1,4 @@
+import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import { Hono } from "hono";
 import type { PgClient } from "../db/connection.js";
 import { type AppContext, type Registry, type RunIn, type WriteResult } from "../engine/types/index.js";
@@ -75,7 +76,7 @@ export type KumikoServer = {
     lifecycle?: Lifecycle;
     context: AppContext;
 };
-export declare function withFileProviderResolver(registry: Registry, context: AppContext): AppContext;
+export declare function withFileProviderResolver(registry: Registry, context: AppContext, cacheSync?: CacheSyncBus): AppContext;
 export declare function buildServer(options: ServerOptions): KumikoServer;
 export declare function makeDispatchSystemWrite(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<WriteResult>;
 export declare function makeDispatchSystemQuery(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<unknown>;

package/dist/api/server.js

@@ -19,7 +19,8 @@ import { createEventDispatcher } from "../pipeline/event-dispatcher.js";
 import { createLifecycleHooks } from "../pipeline/lifecycle-pipeline.js";
 import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context.js";
 import { createAccessInvalidationEventConsumer, createJobTriggerEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, } from "../pipeline/system-hooks.js";
-import { authEndpointRateLimit, createRateLimitResolver, globalIpRateLimit, } from "../rate-limit/index.js";
+import { authEndpointRateLimit, createPayloadDigest, createRateLimitResolver, globalIpRateLimit, httpRouteRateLimit, } from "../rate-limit/index.js";
+import { resolveCacheSyncBus } from "../redis/cache-sync-bus.js";
 import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
 import { assertUnreachable, generateId } from "../utils/index.js";
 import { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
@@ -47,7 +48,7 @@ import { buildWebSocketSessionRevalidator, createWebSocketConnectionLimiter, has
 // per-tenant provider cache). Mirrors buildServer's own resolution exactly —
 // including NOT inventing a resolver when no `file-provider-*` plugin is
 // mounted, which is what keeps buildServer's boot-guard below able to fire.
-export function withFileProviderResolver(registry, context) {
+export function withFileProviderResolver(registry, context, cacheSync) {
     if (context._fileProviderResolver !== undefined)
         return context;
     if (registry.getExtensionUsages(EXT_FILE_PROVIDER).length === 0)
@@ -59,6 +60,7 @@ export function withFileProviderResolver(registry, context) {
             _configAccessorFactory: context._configAccessorFactory,
             secrets: context.secrets,
             db: context.db,
+            ...(cacheSync ? { cacheSync } : {}),
         }),
     };
 }
@@ -127,6 +129,10 @@ export function buildServer(options) {
         sseBroker = defaults.sseBroker;
         ownedRedisSseBroker = defaults.ownedRedisSseBroker;
     }
+    // Same decision as the SSE broker: an explicit dispatcherOptions value
+    // (incl. null = opt out) wins, otherwise REDIS_URL turns on cross-replica
+    // cache invalidation (no REDIS_URL = process-local bus).
+    const { bus: cacheSync, owned: ownedCacheSync } = resolveCacheSyncBus(options.dispatcherOptions?.cacheSync);
     // Resolve the per-process instance identifier. Prefer explicit
     // ServerOptions.instanceId (tests, deliberate wiring), fall back to the
     // deploy-env variable, finally a boot-time UUID. Validator rejects the
@@ -184,7 +190,7 @@ export function buildServer(options) {
     // resolver once (when a provider plugin is mounted) — the dispatcher uses it
     // to materialise `ctx.files`, the upload routes + MSP-applies share it. The
     // resolver reads config + the s3.secretAccessKey secret under SYSTEM identity.
-    const contextWithFiles = withFileProviderResolver(options.registry, options.context);
+    const contextWithFiles = withFileProviderResolver(options.registry, options.context, cacheSync);
     const fileProviderResolver = contextWithFiles._fileProviderResolver;
     // Auto-wire the rate-limit resolver, but ONLY when at least one
     // handler actually declared a rateLimit option. Apps that don't use
@@ -197,13 +203,22 @@ export function buildServer(options) {
     // both share the same instance to avoid duplicate Lua-script registration.
     const wantsL3 = options.registry.hasRateLimitedHandler();
     const wantsL1L2 = options.rateLimit?.global !== undefined || options.rateLimit?.auth !== undefined;
-    const wantsResolver = wantsL3 || wantsL1L2;
+    const wantsHttpRouteLimit = [...options.registry.features.values()].some((feature) => Object.values(feature.httpRoutes).some((route) => route.rateLimit !== undefined));
+    const wantsResolver = wantsL3 || wantsL1L2 || wantsHttpRouteLimit;
+    // Master for the payload-bucket HMAC: the current signing secret (the
+    // keyring's signKid for rotation setups). buildServer always has one, so
+    // the digest is available whenever a handler declares additionalRateLimits.
+    const payloadDigest = createPayloadDigest(typeof options.jwtSecret === "string"
+        ? options.jwtSecret
+        : (options.jwtSecret.keys[options.jwtSecret.signKid] ?? ""));
     const rateLimitResolver = options.context.rateLimit ??
         (wrappedRedis && wantsResolver ? createRateLimitResolver({ redis: wrappedRedis }) : undefined);
     const contextWithObservability = {
         ...contextWithFiles,
         ...(wrappedRedis ? { redis: wrappedRedis } : {}),
         ...(rateLimitResolver ? { rateLimit: rateLimitResolver } : {}),
+        _rateLimitPayloadDigest: payloadDigest,
+        ...(cacheSync ? { cacheSync } : {}),
         // Propagate the feature-toggle resolver to the context so the event-
         // dispatcher (and any future context-reading consumer) sees the same
         // source as the command dispatcher's handler-gate. Options take
@@ -220,6 +235,7 @@ export function buildServer(options) {
         ...options.dispatcherOptions,
         lifecycle,
         sseBroker,
+        cacheSync: cacheSync ?? null,
         ...(options.auth ? { membershipQuery: options.auth.membershipQuery } : {}),
     });
     // Async event-dispatcher — the replacement for the old transactional
@@ -379,6 +395,12 @@ export function buildServer(options) {
             await broker.close();
         });
     }
+    if (options.lifecycle && ownedCacheSync) {
+        const bus = ownedCacheSync;
+        options.lifecycle.registerShutdownHook("cacheSync", async () => {
+            await bus.close();
+        });
+    }
     const app = new Hono();
     // Sub-apps mounted via app.route() without their own handler inherit this one.
     app.onError(handleUncaughtRouteError);
@@ -657,7 +679,23 @@ export function buildServer(options) {
                 systemQuery: makeSystemQuery(c, dispatcher, clientIpResolver),
                 clientIp: clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
             });
-            mountHonoRoute(app, route.method, route.path, honoHandler, route.anonymous ? [] : sessionOnlyHttpRouteGuards);
+            // Without a resolver (no Redis in the context — dev/test stacks) the
+            // declared limit is skipped rather than failing the boot of every app
+            // that mounts a bundled feature whose routes carry a default limit.
+            const routeLimit = route.rateLimit && rateLimitResolver
+                ? [
+                    httpRouteRateLimit({
+                        resolver: rateLimitResolver,
+                        rateLimit: route.rateLimit,
+                        routeKey: `${route.method} ${route.path}`,
+                        clientIpResolver,
+                    }),
+                ]
+                : [];
+            mountHonoRoute(app, route.method, route.path, honoHandler, [
+                ...routeLimit,
+                ...(route.anonymous ? [] : sessionOnlyHttpRouteGuards),
+            ]);
         }
     }
     // r.webSocketRoute — GET routes under /api/ws/*, so the jwt/pat/rate-limit

package/dist/crypto/kek-source.d.ts

@@ -16,8 +16,7 @@ export type KekSourceOptions = {
     readonly logPrefix?: string;
     /** Where the boot line naming the KEK source goes. Defaults to `console.info`. */
     readonly log?: (message: string) => void;
-    /** Env names to resolve, e.g. `kmsSlotsOf(schema)`. Defaults to the three
-     *  platform slots. */
-    readonly slots?: readonly string[];
+    /** Env names to resolve, e.g. `kmsSlotsOf(schema)`. */
+    readonly slots: readonly string[];
 };
-export declare function resolvePlatformKeks(env: KekSourceEnv, options?: KekSourceOptions): Promise<KekSourceEnv>;
+export declare function resolvePlatformKeks(env: KekSourceEnv, options: KekSourceOptions): Promise<KekSourceEnv>;

package/dist/crypto/kek-source.js

@@ -7,9 +7,6 @@ const SCALEWAY_KEY_MANAGER_API_VERSION = "v1alpha1";
 const DEFAULT_REGION = "fr-par";
 const DECRYPT_TIMEOUT_MS = 5_000;
 const RETRY_DELAYS_MS = [200, 800];
-// Used when the caller names no slots. Apps that predate `kms` schema meta
-// rely on it; drop once every consumer declares its slots in the env schema.
-const LEGACY_SLOTS = ["PLATFORM_KEK", "PLATFORM_KEK_PREVIOUS", "KUMIKO_BLIND_INDEX_KEY"];
 function isRetryableStatus(status) {
     return status >= 500;
 }
@@ -97,10 +94,10 @@ async function resolveSlot(name, env, options, fetchImpl) {
 // another slot's fallback path — the trio check downstream still applies.
 // Slots resolve in parallel: sequentially, a slow Key Manager would cost up to
 // ~16 s per slot (3 x 5 s timeout + backoff) and could trip startup probes.
-export async function resolvePlatformKeks(env, options = {}) {
+export async function resolvePlatformKeks(env, options) {
     const fetchImpl = options.fetch ?? globalThis.fetch;
     const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
-    const slots = options.slots ?? LEGACY_SLOTS;
+    const { slots } = options;
     // Misconfiguration must not cost a Key Manager round trip.
     if (slots.includes("PLATFORM_KEK_PREVIOUS") &&
         (env.PLATFORM_KEK_PREVIOUS || env.PLATFORM_KEK_PREVIOUS_CIPHERTEXT) &&

package/dist/crypto/kms-wiring.d.ts

@@ -62,6 +62,6 @@ export declare function requireKmsWiring(env: KmsWiringEnv, options?: KmsWiringO
  *  from a Key Manager ciphertext first when no plaintext is set — see
  *  `resolvePlatformKeks`. The validation stays in the sync function; this only
  *  adds the KEK-fetching step in front of it. */
-export declare function resolveKmsWiringAsync(env: KmsWiringEnv, options?: KmsWiringOptions & KekSourceOptions): Promise<KmsWiring>;
+export declare function resolveKmsWiringAsync(env: KmsWiringEnv, options: KmsWiringOptions & KekSourceOptions): Promise<KmsWiring>;
 /** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
-export declare function requireKmsWiringAsync(env: KmsWiringEnv, options?: KmsWiringOptions & KekSourceOptions): Promise<ActiveKmsWiring>;
+export declare function requireKmsWiringAsync(env: KmsWiringEnv, options: KmsWiringOptions & KekSourceOptions): Promise<ActiveKmsWiring>;

package/dist/crypto/kms-wiring.js

@@ -116,10 +116,10 @@ export function requireKmsWiring(env, options = {}) {
  *  from a Key Manager ciphertext first when no plaintext is set — see
  *  `resolvePlatformKeks`. The validation stays in the sync function; this only
  *  adds the KEK-fetching step in front of it. */
-export async function resolveKmsWiringAsync(env, options = {}) {
+export async function resolveKmsWiringAsync(env, options) {
     return resolveKmsWiring(await resolvePlatformKeks(env, options), options);
 }
 /** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
-export async function requireKmsWiringAsync(env, options = {}) {
+export async function requireKmsWiringAsync(env, options) {
     return requireKmsWiring(await resolvePlatformKeks(env, options), options);
 }

package/dist/db/index.d.ts

@@ -20,7 +20,7 @@ export { createEventStoreExecutor, entityEventName } from "./event-store-executo
 export { enumerateFeatureTableSources, type FeatureTableSource, } from "./feature-table-sources.js";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp.js";
 export { assertValidMigrationName, diffSnapshots, type GenerateMigrationInput, type GenerateMigrationOutput, generateMigration, loadSnapshotJson, renderMigrationSql, type SchemaDiff, type Snapshot, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.js";
-export { type AppliedMigration, type ApplyResult, type BaselineResult, baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, type Migration, MigrationChecksumMismatchError, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
+export { type AppliedMigration, type ApplyResult, type BaselineResult, baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, type Migration, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
 export { flattenMoney, type MoneyRead, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";
 export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, type PgErrorInfo, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
@@ -31,6 +31,7 @@ export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from ".
 export { seedReferenceData } from "./reference-data.js";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";
 export { diffReplayAgainstSnapshot, type ReplayedSchema, type ReplayedTable, type ReplayMismatch, replayMigrationsDir, } from "./replay-migration-sql.js";
+export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
 export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db.js";

package/dist/db/index.js

@@ -14,7 +14,7 @@ export { createEventStoreExecutor, entityEventName } from "./event-store-executo
 export { enumerateFeatureTableSources, } from "./feature-table-sources.js";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp.js";
 export { assertValidMigrationName, diffSnapshots, generateMigration, loadSnapshotJson, renderMigrationSql, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.js";
-export { baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, MigrationChecksumMismatchError, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
+export { baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
 export { flattenMoney, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";
 export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
@@ -24,6 +24,7 @@ export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from ".
 export { seedReferenceData } from "./reference-data.js";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";
 export { diffReplayAgainstSnapshot, replayMigrationsDir, } from "./replay-migration-sql.js";
+export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
 export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, } from "./tenant-db.js";

package/dist/db/migrate-generator.d.ts

@@ -1,4 +1,5 @@
 import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta.js";
+import { type RetiredFrameworkTable } from "./retired-framework-tables.js";
 declare const SNAPSHOT_VERSION: 1;
 export type Snapshot = {
     readonly version: typeof SNAPSHOT_VERSION;
@@ -62,18 +63,23 @@ export declare function managedChangeRequiresRecreate(td: TableDiff): boolean;
 export declare function renderMigrationSql(diff: SchemaDiff, options: {
     readonly name: string;
     readonly sequenceNumber: number;
+    readonly retiredDrops?: readonly RetiredFrameworkTable[];
 }): string;
 export type GenerateMigrationInput = {
     readonly metas: readonly EntityTableMeta[];
     readonly prevSnapshot: Snapshot | null;
     readonly name: string;
     readonly sequenceNumber: number;
+    /** Raw SQL of all earlier migrations, in order — lets the generator decide
+     *  whether a retired framework table still needs its executable drop. */
+    readonly priorMigrationsSql?: readonly string[];
 };
 export type GenerateMigrationOutput = {
     readonly filename: string;
     readonly sqlContent: string;
     readonly snapshot: Snapshot;
     readonly diff: SchemaDiff;
+    readonly retiredDrops: readonly RetiredFrameworkTable[];
 };
 export declare const MIGRATION_NAME_RE: RegExp;
 export declare function assertValidMigrationName(name: string): void;

package/dist/db/migrate-generator.js

@@ -17,6 +17,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { compareByCodepoint } from "../utils/index.js";
 import { renderIndex, renderTableDdl } from "./render-ddl.js";
+import { findRetiredTableDrops } from "./retired-framework-tables.js";
 const SNAPSHOT_VERSION = 1;
 export function snapshotFromMetas(metas) {
     // Stable ordering by tableName so the snapshot.json diff in PRs is
@@ -321,6 +322,7 @@ function describeIndexChange(change) {
 // the index serves performance) are emitted as commented-out statements
 // for explicit reviewer-action.
 export function renderMigrationSql(diff, options) {
+    const retiredDrops = options.retiredDrops ?? [];
     const lines = [];
     const seq = options.sequenceNumber.toString().padStart(4, "0");
     lines.push(`-- Migration ${seq}_${options.name}`);
@@ -393,9 +395,18 @@ export function renderMigrationSql(diff, options) {
         }
         lines.push("");
     }
+    if (retiredDrops.length > 0) {
+        lines.push("-- === Retired framework tables ===");
+        for (const retired of retiredDrops) {
+            lines.push(`-- ${retired.tableName}: retired since framework ${retired.sinceVersion} — ${retired.explanation}`);
+            lines.push(`DROP TABLE IF EXISTS ${quoteIdent(retired.tableName)};`);
+        }
+        lines.push("");
+    }
     if (diff.newTables.length === 0 &&
         diff.changedTables.length === 0 &&
-        diff.droppedTables.length === 0) {
+        diff.droppedTables.length === 0 &&
+        retiredDrops.length === 0) {
         lines.push("-- No schema changes detected.");
     }
     return lines.join("\n");
@@ -413,9 +424,11 @@ export function generateMigration(input) {
     assertValidMigrationName(input.name);
     const nextSnapshot = snapshotFromMetas(input.metas);
     const diff = diffSnapshots(input.prevSnapshot, nextSnapshot);
+    const retiredDrops = findRetiredTableDrops(input.priorMigrationsSql ?? [], nextSnapshot);
     const sqlContent = renderMigrationSql(diff, {
         name: input.name,
         sequenceNumber: input.sequenceNumber,
+        retiredDrops,
     });
     const seq = input.sequenceNumber.toString().padStart(4, "0");
     return {
@@ -423,5 +436,6 @@ export function generateMigration(input) {
         sqlContent,
         snapshot: nextSnapshot,
         diff,
+        retiredDrops,
     };
 }

package/dist/db/migrate-runner.d.ts

@@ -14,6 +14,7 @@ export type ApplyResult = {
 };
 export declare function splitSqlStatements(sqlText: string): readonly string[];
 export declare function loadMigrationsFromDir(dir: string, preprocess?: (sql: string) => string): readonly Migration[];
+export declare function readMigrationSqlTexts(dir: string): readonly string[];
 export declare function fetchAppliedMigrations(db: DbConnection): Promise<readonly AppliedMigration[]>;
 export declare class MigrationChecksumMismatchError extends Error {
     readonly migrationId: string;

package/dist/db/migrate-runner.js

@@ -14,7 +14,7 @@
 // fehl mit klarer Fehlermeldung (production-DBs haben das alte SQL drin —
 // edit nachträglich = production-state inkonsistent mit committed-state).
 import { createHash } from "node:crypto";
-import { readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 // Adapter: extract raw postgres-js client from drizzle DbConnection,
 // or use Bun.sql instance directly. Either way `.unsafe()` is the
@@ -171,6 +171,16 @@ export function loadMigrationsFromDir(dir, preprocess) {
         };
     });
 }
+// Raw file texts in migration order, comments intact (loadMigrationsFromDir
+// strips them) — the retired-table scan reads them for DESTRUCTIVE markers.
+export function readMigrationSqlTexts(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".sql"))
+        .sort()
+        .map((file) => readFileSync(join(dir, file), "utf8"));
+}
 // Raw-SQL via postgres-js or Bun.sql .unsafe() — same shape for both.
 async function executeRaw(db, sqlText) {
     await rawClient(db).unsafe(sqlText);

package/dist/db/queries/shadow-swap.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectionRowIdOf } from "@cosmicdrift/kumiko-types/projection";
 import type { DbConnection, DbTx } from "../connection.js";
 import type { EntityTableMeta } from "../entity-table-meta.js";
 import { type AnyDb } from "../query.js";
@@ -8,7 +9,7 @@ export declare function assertLiveColumnsMatchMeta(db: DbConnection | DbTx, meta
 export declare function assertLiveTableHasNoRowLevelSecurity(tx: AnyDb, tableName: string, projectionName?: string): Promise<void>;
 export declare function buildShadowTable(tx: AnyDb, meta: EntityTableMeta): Promise<void>;
 export declare function fenceLiveTable(tx: AnyDb, tableName: string, lockTimeoutMs: number): Promise<void>;
-export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[]): Promise<void>;
+export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[], derivedRowIds?: Readonly<Record<string, ProjectionRowIdOf>>): Promise<void>;
 export declare function assertNoBlindIndexLoss(tx: AnyDb, tableName: string, meta: EntityTableMeta, projectionName: string): Promise<void>;
 export type ColumnDriftResult = {
     readonly rowCount: number;

package/dist/db/queries/shadow-swap.js

@@ -17,6 +17,7 @@
 // Boundary: the shadow table is rebuilt from EntityTableMeta, so any index NOT
 // expressed in meta (hand-added in a migration) is not reconstructed, and a
 // partial index whose WHERE the renderer can't express is rejected up-front.
+import { isUuid, parseTenantId } from "@cosmicdrift/kumiko-types/identifiers";
 import { configuredBlindIndexKey } from "../../crypto/index.js";
 import { asEntityTableMeta, asRawClient } from "../query.js";
 import { renderTableDdl } from "../render-ddl.js";
@@ -178,19 +179,80 @@ const UNREACHABLE_SAMPLE_LIMIT = 20;
 //
 // Implicit projections only (caller-gated). aggregate_id and the entity id are
 // both uuid, so the anti-join probes the events index without a cast.
-export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes) {
+//
+// Source streams whose rows are keyed by a DERIVED id (r.extendEntityProjection
+// `rowIdOf`, e.g. tenant-salted) cannot be matched on aggregate_id: their
+// distinct (tenant, aggregate) pairs are mapped through rowIdOf into a temp
+// table, and a live row is backed when its id is in that set. The guard stays
+// strict — a row keyed by the raw aggregate id of a derived stream is a ghost.
+const DERIVED_ROW_ID_BATCH_SIZE = 5000;
+const DERIVED_ROW_ID_TABLE = "pg_temp.kumiko_derived_row_ids";
+async function fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf) {
+    let cursor;
+    for (;;) {
+        const page = await raw.unsafe(`SELECT DISTINCT "tenant_id"::text AS tenant_id, "aggregate_id"::text AS aggregate_id
+         FROM "kumiko_events"
+        WHERE "aggregate_type" = $1
+          ${cursor ? `AND ("tenant_id", "aggregate_id") > ($2::uuid, $3::uuid)` : ""}
+        ORDER BY "tenant_id", "aggregate_id"
+        LIMIT ${DERIVED_ROW_ID_BATCH_SIZE}`, cursor ? [aggregateType, cursor.tenant_id, cursor.aggregate_id] : [aggregateType]);
+        // skip: keyset exhausted — every source event of this type has been mapped
+        if (page.length === 0)
+            return;
+        const derivedIds = page.map((row) => {
+            const tenantId = parseTenantId(row.tenant_id);
+            if (tenantId === null) {
+                throw new Error(`projection-rebuild "${projectionName}": event of aggregate type "${aggregateType}" ` +
+                    `carries a non-uuid tenant_id "${row.tenant_id}".`);
+            }
+            const derived = rowIdOf({ tenantId, aggregateId: row.aggregate_id });
+            if (!isUuid(derived)) {
+                throw new Error(`projection-rebuild "${projectionName}": rowIdOf for aggregate type "${aggregateType}" ` +
+                    `returned "${String(derived)}", which is not a uuid (aggregate ${row.aggregate_id}).`);
+            }
+            return derived;
+        });
+        await raw.unsafe(`INSERT INTO ${DERIVED_ROW_ID_TABLE} ("id") SELECT unnest($1::uuid[]) ON CONFLICT DO NOTHING`, [derivedIds]);
+        // skip: a short page is the last one
+        if (page.length < DERIVED_ROW_ID_BATCH_SIZE)
+            return;
+        cursor = page[page.length - 1];
+    }
+}
+export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes, derivedRowIds = {}) {
     // skip: no source streams → no events could back any row anyway; a rebuild
     // of a subscription-less projection swaps an empty shadow (handled upstream).
     if (aggregateTypes.length === 0)
         return;
     const raw = asRawClient(tx);
     const t = quoteTableIdent(tableName);
+    const derivedTypes = aggregateTypes.filter((type) => derivedRowIds[type] !== undefined);
+    const directTypes = aggregateTypes.filter((type) => derivedRowIds[type] === undefined);
+    if (derivedTypes.length > 0) {
+        // search_path points at the shadow schema here; pg_temp is addressed explicitly.
+        await raw.unsafe(`CREATE TEMP TABLE IF NOT EXISTS kumiko_derived_row_ids ("id" uuid PRIMARY KEY) ON COMMIT DROP`);
+        await raw.unsafe(`TRUNCATE ${DERIVED_ROW_ID_TABLE}`);
+        for (const aggregateType of derivedTypes) {
+            const rowIdOf = derivedRowIds[aggregateType];
+            // skip: filtered by derivedTypes above, narrows the Record lookup for the compiler
+            if (rowIdOf === undefined)
+                continue;
+            await fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf);
+        }
+    }
+    const unbackedClauses = [];
+    if (directTypes.length > 0) {
+        unbackedClauses.push(`NOT EXISTS (
+         SELECT 1 FROM "kumiko_events" e
+          WHERE e."aggregate_id" = l."id" AND e."aggregate_type" = ANY($1::text[])
+       )`);
+    }
+    if (derivedTypes.length > 0) {
+        unbackedClauses.push(`NOT EXISTS (SELECT 1 FROM ${DERIVED_ROW_ID_TABLE} d WHERE d."id" = l."id")`);
+    }
     const ghosts = await raw.unsafe(`SELECT l."id" FROM public.${t} l
-     WHERE NOT EXISTS (
-       SELECT 1 FROM "kumiko_events" e
-        WHERE e."aggregate_id" = l."id" AND e."aggregate_type" = ANY($1::text[])
-     )
-     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, [aggregateTypes]);
+     WHERE ${unbackedClauses.join(" AND ")}
+     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, directTypes.length > 0 ? [directTypes] : []);
     // skip: every live row has a backing event — nothing unreachable, swap is safe
     if (ghosts.length === 0)
         return;
@@ -200,7 +262,8 @@ export async function assertNoUnreachableLiveRows(tx, projectionName, tableName,
         `event in the projection's source streams and cannot be reconstructed by replay — the swap ` +
         `would silently drop them (ids: ${ids.join(", ")}). A handler direct-inserted these rows ` +
         `without emitting a .created event. Fix: register the table with r.storeTable(meta, ` +
-        `{ reason }) to opt out of rebuild, or emit the missing events. See ` +
+        `{ reason }) to opt out of rebuild, or emit the missing events. Rows keyed by an id ` +
+        `derived from the source event declare \`rowIdOf\` on r.extendEntityProjection. See ` +
         `docs/reference/entity-write-patterns.md. Rebuild aborted; live table untouched.`);
 }
 // The bidx column is schema-driven, not key-driven: it exists NULL in a

package/dist/db/retired-framework-tables.d.ts

@@ -0,0 +1,10 @@
+import type { Snapshot } from "./migrate-generator.js";
+export type RetiredFrameworkTable = {
+    readonly tableName: string;
+    readonly sinceVersion: string;
+    readonly explanation: string;
+};
+export declare const retiredFrameworkTables: readonly RetiredFrameworkTable[];
+export declare function findRetiredTableDrops(priorMigrationsSql: readonly string[], nextSnapshot: Snapshot): readonly RetiredFrameworkTable[];
+export declare function findCommentedDropTables(migrationsSql: readonly string[], snapshot: Snapshot | null): readonly string[];
+export declare function isRetiredFrameworkTable(tableName: string): boolean;

package/dist/db/retired-framework-tables.js

@@ -0,0 +1,72 @@
+// Framework tables that a framework release stopped creating and whose data
+// was explicitly declared dispensable. `kumiko schema generate` drops them
+// for real (instead of the commented-out DESTRUCTIVE marker app tables get),
+// because the framework — not the app — owns the decision that the data is
+// gone. Without this, every app carried a stale table forever behind a
+// commented drop nobody uncomments.
+//
+// Add an entry only when the release notes state the data is not preserved.
+// A rename is NOT a retirement: the data lives on under the new name.
+export const retiredFrameworkTables = [
+    {
+        tableName: "read_job_runs",
+        sinceVersion: "0.210.0",
+        explanation: "replaced by store_job_runs; the job run history was not migrated (operational data, not a system of record)",
+    },
+];
+const IDENT = `"?([^"\\s(;,.]+)"?`;
+const CREATE_TABLE_RE = new RegExp(`^CREATE TABLE\\s+(?:IF NOT EXISTS\\s+)?${IDENT}`, "i");
+const DROP_TABLE_RE = new RegExp(`^DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i");
+const COMMENTED_DROP_TABLE_RE = new RegExp(`^--\\s*DESTRUCTIVE:\\s*DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i");
+// Last known state per table across all migrations, in order — so a
+// DROP followed by a re-CREATE (managed-projection recreate) counts as
+// "created", and a commented drop followed by an executable one as "dropped".
+function scanTableLifecycle(sqlTexts) {
+    const states = new Map();
+    for (const text of sqlTexts) {
+        for (const rawLine of text.split("\n")) {
+            const line = rawLine.trim();
+            const commentedDrop = COMMENTED_DROP_TABLE_RE.exec(line)?.[1];
+            if (commentedDrop !== undefined) {
+                states.set(commentedDrop, "commented-drop");
+                continue;
+            }
+            if (line.startsWith("--"))
+                continue;
+            const created = CREATE_TABLE_RE.exec(line)?.[1];
+            if (created !== undefined) {
+                states.set(created, "created");
+                continue;
+            }
+            const dropped = DROP_TABLE_RE.exec(line)?.[1];
+            if (dropped !== undefined)
+                states.set(dropped, "dropped");
+        }
+    }
+    return states;
+}
+function snapshotHasTable(snapshot, tableName) {
+    return snapshot?.tables.some((t) => t.tableName === tableName) ?? false;
+}
+// Retired tables the next migration must drop: a migration created them (or
+// carries a commented drop), none dropped them for real, and the schema no
+// longer declares them.
+export function findRetiredTableDrops(priorMigrationsSql, nextSnapshot) {
+    const states = scanTableLifecycle(priorMigrationsSql);
+    return retiredFrameworkTables.filter((retired) => {
+        const state = states.get(retired.tableName);
+        return ((state === "created" || state === "commented-drop") &&
+            !snapshotHasTable(nextSnapshot, retired.tableName));
+    });
+}
+// Tables a migration only carries as a commented DESTRUCTIVE drop although
+// the snapshot no longer has them: if they still exist in the live DB, the
+// drop was never made.
+export function findCommentedDropTables(migrationsSql, snapshot) {
+    return [...scanTableLifecycle(migrationsSql)]
+        .filter(([tableName, state]) => state === "commented-drop" && !snapshotHasTable(snapshot, tableName))
+        .map(([tableName]) => tableName);
+}
+export function isRetiredFrameworkTable(tableName) {
+    return retiredFrameworkTables.some((retired) => retired.tableName === tableName);
+}