@cosmicdrift/kumiko-framework 0.341.0 → 0.342.0

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/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);
+}

package/dist/engine/soft-delete-cleanup.d.ts

@@ -1,9 +1,11 @@
 import type { ConfigKeyDefinition, JobDefinition, JobHandlerFn } from "./types/config.js";
+import type { EntityDefinition } from "./types/index.js";
 export declare const SOFT_DELETE_CLEANUP_JOB = "soft-delete:job:cleanup";
 export declare const SOFT_DELETE_CLEANUP_SYSTEM_JOB = "soft-delete:job:cleanup-system";
 export declare const SOFT_DELETE_GRACE_DAYS_KEY = "soft-delete:config:grace-days";
 export declare const DEFAULT_GRACE_DAYS = 30;
 export declare const softDeleteGraceDaysConfig: ConfigKeyDefinition;
+export declare function isSystemScopedSoftDeleteTable(table: unknown, entity: Pick<EntityDefinition, "tenancy">): boolean;
 export declare const softDeleteCleanupJob: JobHandlerFn;
 export declare const softDeleteCleanupSystemJob: JobHandlerFn;
 export declare function buildSoftDeleteCleanupJob(): JobDefinition;

package/dist/engine/soft-delete-cleanup.js

@@ -10,7 +10,7 @@
 // resurrect the row as isDeleted=true. That's acceptable: cleanup bounds LIVE
 // table growth; irreversible event-log purging is data-retention's job
 // (pruneEvents), a separate, consumer-lag-guarded path.
-import { deleteMany } from "../db/query.js";
+import { asEntityTableMeta, deleteMany } from "../db/query.js";
 import { SYSTEM_USER_ID } from "./system-user.js";
 // qualifyEntityName convention (feature:type:kebab-name) with a reserved
 // "soft-delete" owner — no real feature owns these; the framework synthesizes
@@ -31,6 +31,18 @@ export const softDeleteGraceDaysConfig = {
     // existing silent-below-bound / audited-crossing behavior.
     bounds: { min: 1 },
 };
+function hasTenantIdColumn(table) {
+    return table["tenantId"] !== undefined;
+}
+// The entity declaration decides, not the column: a `tenancy: "global"` table
+// (e.g. user) still carries a tenantId column (SYSTEM_TENANT_ID), yet no
+// tenant-mode delete can ever match its rows.
+export function isSystemScopedSoftDeleteTable(table, entity) {
+    return entity.tenancy === "global" || !hasTenantIdColumn(table);
+}
+function isGlobalTenancyTable(table) {
+    return asEntityTableMeta(table)?.tenancy === "global";
+}
 export const softDeleteCleanupJob = async (_payload, ctx) => {
     const { db, registry } = ctx;
     if (!db || !registry) {
@@ -57,21 +69,18 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
         const entity = registry.getEntity(proj.source);
         if (!entity?.softDelete)
             continue;
-        // @cast-boundary column-presence probe — identical access the executor's
-        // list() does on table["tenantId"] to decide tenant-scoping.
-        const hasTenantColumn = proj.table["tenantId"] !== undefined;
-        // System-global entities (no tenantId column, e.g. `user`) are NOT swept
+        // System-global entities (tenancy "global" or no tenantId column, e.g. `user`) are NOT swept
         // here: this handler runs once PER TENANT, so a tenant-scoped grace value
         // would purge every OTHER tenant's still-within-grace rows too (effective
         // grace = min() across all tenants). softDeleteCleanupSystemJob handles
         // these separately, once, with a fixed grace period.
-        if (!hasTenantColumn)
+        if (isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff }, tenantId };
         await deleteMany(db, proj.table, where);
     }
 };
-// System-global soft-deleted entities (no tenantId column) can't take a
+// System-global soft-deleted entities (tenancy "global" or no tenantId column) can't take a
 // per-tenant grace period — there's no "this tenant's view" of a row that
 // isn't scoped to any tenant. Runs once (not perTenant) with a fixed grace
 // period; a future system-scope config key could make this configurable
@@ -88,9 +97,15 @@ export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
         const entity = registry.getEntity(proj.source);
         if (!entity?.softDelete)
             continue;
-        if (proj.table["tenantId"] !== undefined)
+        if (!isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
-        await deleteMany(db, proj.table, { isDeleted: true, deletedAt: { lt: cutoff } });
+        const where = { isDeleted: true, deletedAt: { lt: cutoff } };
+        if (isGlobalTenancyTable(proj.table)) {
+            await db.global(proj.table).deleteMany(where);
+        }
+        else {
+            await deleteMany(db, proj.table, where);
+        }
     }
 };
 export function buildSoftDeleteCleanupJob() {
@@ -110,5 +125,9 @@ export function buildSoftDeleteCleanupSystemJob() {
         trigger: { cron: "15 3 * * *" },
         concurrency: "skip",
         runIn: "worker",
+        escapeHatch: {
+            reason: "hard-deletes expired soft-deleted rows of global entities (e.g. user) once, system-wide",
+            grants: ["globalWrites"],
+        },
     };
 }

package/dist/jobs/job-runner.js

@@ -11,7 +11,7 @@ import { InternalError } from "../errors/index.js";
 import { isKumikoError } from "../errors/kumiko-error.js";
 import { createFileContext } from "../files/file-handle.js";
 import { createFallbackLogger } from "../logging/index.js";
-import { createEscapeHatchReporter, emitJobLastSuccess, emitJobQueueDepth, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
+import { createEscapeHatchProcessDedup, createEscapeHatchReporter, emitJobLastSuccess, emitJobQueueDepth, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
 import { createDistributedLock } from "../pipeline/distributed-lock.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
 import { buildPersonalDataGate, isPersonalDataGated, parseWriteOrigin, } from "../pipeline/write-origin.js";
@@ -316,6 +316,8 @@ export function createJobRunner(options) {
     // must not depend on buildServer having done it first. Idempotent.
     if (context.meter)
         registerStandardMetrics(context.meter);
+    // Instance-scoped, not module-level: each runner (and each test) audits a system cron's declared hatch once.
+    const systemCronEscapeHatchDedup = createEscapeHatchProcessDedup(["unsafe-raw", "global-write"]);
     // Set at the top of stop() — a graceful shutdown closes the redis/BullMQ
     // clients itself, which fires the exact same 'error' listeners below with
     // an expected "Connection is closed." Downgrading to debug once stopping
@@ -692,12 +694,15 @@ export function createJobRunner(options) {
             : undefined;
         const isSystemJob = registry.isJobSystemScoped(jobName);
         // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
+        const isSystemCronRun = triggeredById === null && jobDef.escapeHatch !== undefined && "cron" in jobDef.trigger;
         const reportEscapeHatch = createEscapeHatchReporter({
             handler: jobName,
             tenantId,
             actor: jobSystemUser.id,
             sink: context._escapeHatchAuditSink,
             log: context.log,
+            ...(isSystemCronRun && { processDedup: systemCronEscapeHatchDedup }),
+            ...(context.meter && { meter: context.meter }),
         });
         const systemDb = isSystemJob && tenantScopedDb
             ? createUncheckedSystemDb(tenantScopedDb, undefined, reportEscapeHatch)
@@ -705,6 +710,7 @@ export function createJobRunner(options) {
         const jobDb = configDb
             ? createTenantDb(configDb, tenantId, "tenant", context.tracer, context.meter, undefined, {
                 unsafeRaw: escapeHatchFor(jobDef.escapeHatch, "unsafeRaw"),
+                globalWrites: escapeHatchFor(jobDef.escapeHatch, "globalWrites"),
                 report: reportEscapeHatch,
                 ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
             })

package/dist/observability/escape-hatch-report.d.ts

@@ -1,5 +1,6 @@
-import type { EscapeHatchAuditSink, EscapeHatchReporter, EscapeHatchUseEvent, TenantId } from "../engine/types/index.js";
+import type { EscapeHatchAuditSink, EscapeHatchKind, EscapeHatchReporter, EscapeHatchUseEvent, TenantId } from "../engine/types/index.js";
 import type { Logger } from "../logging/types.js";
+import type { Meter } from "./types/index.js";
 export declare const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
 export type EscapeHatchReportWindow = {
     shouldReport(key: string, nowMs: number): boolean;
@@ -8,6 +9,11 @@ export declare function createEscapeHatchReportWindow(opts?: {
     readonly windowMs?: number;
     readonly maxEntries?: number;
 }): EscapeHatchReportWindow;
+export type EscapeHatchProcessDedup = {
+    readonly kinds: ReadonlySet<EscapeHatchKind>;
+    readonly seen: Set<string>;
+};
+export declare function createEscapeHatchProcessDedup(kinds: readonly EscapeHatchKind[]): EscapeHatchProcessDedup;
 export declare function reportEscapeHatchUse(event: EscapeHatchUseEvent, deps: {
     readonly sink?: EscapeHatchAuditSink;
     readonly log?: Logger;
@@ -19,6 +25,9 @@ export declare function createEscapeHatchReporter(opts: {
     readonly sink?: EscapeHatchAuditSink;
     readonly log?: Logger;
     readonly window?: EscapeHatchReportWindow;
+    readonly processDedup?: EscapeHatchProcessDedup;
+    readonly meter?: Meter;
+    readonly now?: () => number;
 }): EscapeHatchReporter;
 export declare const UNATTRIBUTED_ACTOR = "system";
 export declare function fallbackEscapeHatchReporter(tenantId: TenantId): EscapeHatchReporter;

package/dist/observability/escape-hatch-report.js

@@ -1,3 +1,4 @@
+import { emitEscapeHatchUse } from "./standard-metrics.js";
 export const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
 const DEFAULT_WINDOW_MS = 60_000;
 const DEFAULT_MAX_ENTRIES = 1_000;
@@ -24,6 +25,9 @@ export function createEscapeHatchReportWindow(opts) {
         },
     };
 }
+export function createEscapeHatchProcessDedup(kinds) {
+    return { kinds: new Set(kinds), seen: new Set() };
+}
 // Default window for createEscapeHatchReporter callers that don't pass their own.
 const fallbackReportWindow = createEscapeHatchReportWindow();
 const consoleLogger = {
@@ -67,7 +71,21 @@ export function reportEscapeHatchUse(event, deps) {
 }
 export function createEscapeHatchReporter(opts) {
     const window = opts.window ?? fallbackReportWindow;
+    const now = opts.now ?? Date.now;
     return (kind, reason, target) => {
+        if (opts.meter)
+            emitEscapeHatchUse(opts.meter, opts.handler, kind);
+        const { processDedup } = opts;
+        if (processDedup?.kinds.has(kind)) {
+            const processKey = JSON.stringify([opts.handler, kind, opts.tenantId]);
+            // skip: this (handler, kind, tenant) was already audited by this process
+            if (processDedup.seen.has(processKey))
+                return;
+            processDedup.seen.add(processKey);
+            reportEscapeHatchUse({ handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target }, { sink: opts.sink, log: opts.log });
+            // skip: audited above, the window dedup below only serves the other kinds
+            return;
+        }
         const key = JSON.stringify([
             opts.handler,
             kind,
@@ -78,7 +96,7 @@ export function createEscapeHatchReporter(opts) {
             target?.tenantId ?? null,
         ]);
         // skip: same (handler, kind, reason, target) already reported within the window — dedup
-        if (!window.shouldReport(key, Date.now()))
+        if (!window.shouldReport(key, now()))
             return;
         reportEscapeHatchUse({ handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target }, { sink: opts.sink, log: opts.log });
     };

package/dist/observability/index.d.ts

@@ -1,6 +1,6 @@
 export { type ConsoleProviderOptions, createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
-export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchProcessDedup, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";
@@ -12,5 +12,5 @@ export { type MetricEvent, type MetricEventHandler, RecordingMeter, } from "./re
 export { type RecordedSpan, RecordingTracer, type RecordingTracerOptions, serializeSpanContext, } from "./recording-tracer.js";
 export { wrapRedisClient } from "./redis-wrapper.js";
 export { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, REDACTED, redactAttributes, redactHeaders, redactQueryString, redactValue, shouldRedactAttribute, } from "./sensitive-filter.js";
-export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
+export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEscapeHatchUse, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
 export type { Counter, Gauge, Histogram, Meter, MetricDefinition, MetricLabels, MetricsHandle, MetricType, ObservabilityOptions, ObservabilityProvider, SamplingConfig, SensitiveFilterConfig, SerializedTraceContext, Span, SpanAttributes, SpanAttributeValue, SpanKind, SpanStatus, StartSpanOptions, Tracer, } from "./types/index.js";

package/dist/observability/index.js

@@ -1,7 +1,7 @@
 // Public surface of the observability module.
 export { createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
-export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";
@@ -13,4 +13,4 @@ export { RecordingMeter, } from "./recording-meter.js";
 export { RecordingTracer, serializeSpanContext, } from "./recording-tracer.js";
 export { wrapRedisClient } from "./redis-wrapper.js";
 export { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, REDACTED, redactAttributes, redactHeaders, redactQueryString, redactValue, shouldRedactAttribute, } from "./sensitive-filter.js";
-export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
+export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEscapeHatchUse, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";

package/dist/observability/standard-metrics.d.ts

@@ -43,3 +43,4 @@ export declare function emitEventConsumerPassOutcome(meter: Meter, labels: {
 }, processed: number, failed: number): void;
 export declare function emitJobQueueDepth(meter: Meter, lane: string, counts: Readonly<Record<string, number>>): void;
 export declare function emitJobLastSuccess(meter: Meter, job: string): void;
+export declare function emitEscapeHatchUse(meter: Meter, handler: string, kind: string): void;

package/dist/observability/standard-metrics.js

@@ -140,6 +140,15 @@ export const STANDARD_METRIC_DEFS = [
         description: "Unix timestamp of the last successful run, per registered job.",
         labels: ["job"],
     },
+    // Every escape-hatch use counts here, including the ones the audit sink
+    // dedups away: a system cron firing every minute writes one audit event per
+    // process, so this counter is the only record of how often it ran.
+    {
+        name: "kumiko_escape_hatch_uses_total",
+        type: "counter",
+        description: "Escape-hatch uses by handler and kind, whether or not an audit event was written.",
+        labels: ["handler", "kind"],
+    },
 ];
 export function registerStandardMetrics(meter) {
     for (const def of STANDARD_METRIC_DEFS) {
@@ -251,3 +260,8 @@ export function emitJobQueueDepth(meter, lane, counts) {
 export function emitJobLastSuccess(meter, job) {
     meter.gauge("kumiko_job_last_success_timestamp_seconds").set(Date.now() / 1000, { job });
 }
+// `handler` is a registry-declared handler/job name, `kind` a closed union —
+// no tenant or user input reaches the label set.
+export function emitEscapeHatchUse(meter, handler, kind) {
+    meter.counter("kumiko_escape_hatch_uses_total").inc(1, { handler, kind });
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.341.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.341.0",
-    "@cosmicdrift/kumiko-types": "0.341.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.341.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,32 @@
 [
+  {
+    "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",