@cosmicdrift/kumiko-framework 0.341.0 → 0.343.0

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/test-stack.d.ts

@@ -3,6 +3,7 @@ import type { AuthRoutesConfig } from "../api/auth-routes.js";
 import type { JwtHelper } from "../api/jwt.js";
 import { type SseBroker } from "../api/sse-broker.js";
 import type { AppContext, FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types/index.js";
+import type { ErrorDocsConfig } from "../errors/docs-url.js";
 import { type JobRunner, type JobRunnerOptions } from "../jobs/index.js";
 import type { Lifecycle } from "../lifecycle/index.js";
 import { type ObservabilityProvider } from "../observability/index.js";
@@ -159,6 +160,8 @@ export type TestStackOptions = {
     /** Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops`
      *  — see there. Default 0. */
     trustedProxyHops?: number;
+    /** Links the app's own error reasons to its own docs (`docsUrl` in error responses); framework reasons keep the framework docs link. Passed to buildServer's `ServerOptions.errorDocs`. */
+    errorDocs?: ErrorDocsConfig;
     /** 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
@@ -172,5 +175,9 @@ export type TestStackOptions = {
      *  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;
+    /** "full" runs the prod-boot validateBoot over `features` (screens and ref
+     *  entities across features included). Use it with the app's complete feature
+     *  composition; the default only checks what is safe on a feature subset. */
+    validateBoot?: "full";
 };
 export declare function setupTestStack(options: TestStackOptions): Promise<TestStack>;

package/dist/stack/test-stack.js

@@ -1,5 +1,6 @@
 import { buildServer } from "../api/server.js";
 import { createSseBroker } from "../api/sse-broker.js";
+import { validateBoot, validateNavBootSubset } from "../engine/boot-validator/index.js";
 import { validateOwnershipBoot } from "../engine/boot-validator/ownership.js";
 import { createRegistry } from "../engine/registry.js";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store/index.js";
@@ -31,6 +32,10 @@ export async function setupTestStack(options) {
     // columns) and before the ephemeral DB/Redis exist, so a throw can't leak
     // a database that nothing will clean up.
     validateOwnershipBoot(options.features);
+    // Nav/workspace refs fail the prod boot too; the subset check tolerates refs into unmounted features.
+    validateNavBootSubset(options.features);
+    if (options.validateBoot === "full")
+        validateBoot(options.features);
     // Forward db-name/persistent-flag through to createTestDb. The
     // defaults (undefined dbName, persistent:false) keep the legacy
     // test contract: fresh kumiko_test_<random> DB per setup, dropped
@@ -280,6 +285,7 @@ export async function setupTestStack(options) {
             eventDedup,
             sseBroker,
             ...(options.trustedProxyHops !== undefined && { trustedProxyHops: options.trustedProxyHops }),
+            ...(options.errorDocs && { errorDocs: options.errorDocs }),
             ...(options.extraRoutes && { extraRoutes: options.extraRoutes }),
             ...(options.metrics && { metrics: options.metrics }),
             // Tests drive the dispatcher via stack.eventDispatcher.runOnce() for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.341.0",
+  "version": "0.343.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.343.0",
+    "@cosmicdrift/kumiko-types": "0.343.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.343.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,64 @@
 [
+  {
+    "version": "0.343.0",
+    "type": "breaking",
+    "title": "App error reasons only carry a docsUrl when errorDocs covers them",
+    "detail": "`docsUrl` in error responses is now resolved at serialization by `resolveErrorDocsUrl`. Framework reasons (and errors without a reason) link to the framework docs as before. An app's own reasons no longer link to the framework docs, where no page exists for them: they get a `docsUrl` only if the new option `errorDocs: { baseUrl, reasons: string[] | \"all\" }` (on `runProdApp`, `buildServer`, `createKumikoServer`, `setupTestStack`) covers them.\nMigration: `KumikoError.docsUrl` (the getter) is removed; use `resolveErrorDocsUrl(err, errorDocs?)`. `ErrorResponseBody.docsUrl` is now optional. Apps whose clients read `docsUrl` for app reasons pass `errorDocs` or handle the missing field.",
+    "migration": "KumikoError.docsUrl (the getter) is removed; call resolveErrorDocsUrl(err, errorDocs?) instead. ErrorResponseBody.docsUrl is optional. Apps whose clients read docsUrl for app reasons pass errorDocs or handle the missing field."
+  },
+  {
+    "version": "0.343.0",
+    "type": "fix",
+    "title": "Executor writes outside the dispatcher no longer skip custom projections",
+    "detail": "Executor writes run custom projections\n`EventStoreExecutor` create, update, delete, forget and restore now run the custom projections registered for the written event, in the same savepoint as the write. The registry is bound to the `TenantDb` by the dispatcher and the job runner; a `TenantDb` built elsewhere skips custom projections. Projection runs are idempotent per event object, so the dispatcher's own pass after the handler does not run them twice.",
+    "migration": "Remove manual `runProjections` calls after executor writes in hooks or jobs together with the bump. A call is a no-op only when it passes the exact event object the executor returned; a spread or rebuilt event projects twice."
+  },
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "isFailedWriteResult is exported from the pipeline entry",
+    "detail": "`isFailedWriteResult` and `FailedWriteResult` are exported from the pipeline entry\nConsumers can narrow a `WriteResult` to its failure branch with `import { isFailedWriteResult } from \"@cosmicdrift/kumiko-framework/pipeline\"` instead of re-implementing the check."
+  },
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "retiredCookieDomains clears auth cookies left on a former cookieDomain",
+    "detail": "`AuthRoutesConfig.retiredCookieDomains` lists domains that used to carry the auth cookies. Login and logout also send delete headers for `kumiko_auth` and `kumiko_csrf` with `Domain=<entry>`, so a stale cookie from an earlier `cookieDomain` no longer shadows the new session after the value changes. Login sends these deletes before the new `Set-Cookie` headers. `createAuthRoutes` throws on an empty entry, on `;`, comma, whitespace, CR or LF, and on an entry equal to the current `cookieDomain`. Without the option nothing changes. Remove an entry once the session TTL has passed since the switch."
+  },
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "Test stacks validate nav references and can run the full boot validation",
+    "detail": "`setupTestStack` now validates nav, workspace and tree-action references on the mounted features, with the same error messages as the prod boot. References into features that are not mounted are skipped. The new option `validateBoot: \"full\"` runs the complete `validateBoot`, including the screen and ref-entity checks that span features; give apps one boot test with their prod feature composition and this option."
+  },
+  {
+    "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",