@cosmicdrift/kumiko-framework 0.371.1 → 0.372.0

package/dist/files/provider-resolver.js

@@ -15,6 +15,7 @@ import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT
 import { SYSTEM_USER_ID } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
 import { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage } from "../redis/cache-sync-topics.js";
+import { withUploadLedger } from "./upload-ledger.js";
 const FEATURE_NAME = "file-foundation";
 // extension-usage `options` is engine-payload (unknown) — structurally validate
 // instead of casting blind.
@@ -95,7 +96,7 @@ export function makeFileProviderResolver(deps) {
             cache.delete(message.tenantId);
     });
     deps.cacheSync?.onResync(() => cache.clear());
-    return (tenantId) => {
+    const resolveProvider = (tenantId) => {
         const cached = cache.get(tenantId);
         if (cached)
             return cached;
@@ -118,4 +119,5 @@ export function makeFileProviderResolver(deps) {
         cache.set(tenantId, built);
         return built;
     };
+    return deps.db ? withUploadLedger(resolveProvider, deps.db) : resolveProvider;
 }

package/dist/files/sweep-orphaned-uploads.d.ts

@@ -0,0 +1,16 @@
+import type { FileContext } from "@cosmicdrift/kumiko-types/file-handle-types";
+import type { Logger } from "@cosmicdrift/kumiko-types/logger";
+import { type TenantDb } from "../db/tenant-db.ts";
+export declare const ORPHANED_UPLOAD_SWEEP_BATCH = 500;
+export declare const DEFAULT_UPLOAD_SWEEP_GRACE_HOURS = 24;
+export declare const MIN_UPLOAD_SWEEP_GRACE_HOURS = 1;
+type SweepLog = Pick<Logger, "warn"> | undefined;
+export declare function sweepOrphanedUploads(args: {
+    readonly db: TenantDb;
+    readonly files: FileContext | undefined;
+    readonly now: Temporal.Instant;
+    readonly graceHours: number;
+    readonly log: SweepLog;
+    readonly pageSize?: number;
+}): Promise<void>;
+export {};

package/dist/files/sweep-orphaned-uploads.js

@@ -0,0 +1,53 @@
+import { selectMany } from "../db/query.js";
+import { runInOwnTransaction } from "../db/tenant-db.js";
+import { deleteFileRefBytes } from "../derivatives/delete-stored-file.js";
+import { fileRefsTable } from "./file-ref-table.js";
+import { fileUploadLedgerTable, takeUploadLedgerEntry } from "./upload-ledger.js";
+export const ORPHANED_UPLOAD_SWEEP_BATCH = 500;
+export const DEFAULT_UPLOAD_SWEEP_GRACE_HOURS = 24;
+export const MIN_UPLOAD_SWEEP_GRACE_HOURS = 1;
+// Each candidate gets its own short transaction that takes the ledger row first. A commit that
+// holds the row makes the sweep wait and then find it gone; a sweep that took the row first makes
+// the commit find it gone and fail, so bytes and fileRef row can never end up apart.
+async function sweepOrphanedUpload(txDb, files, storageKey) {
+    const taken = await takeUploadLedgerEntry(txDb, storageKey);
+    // skip: a commit took the row in the meantime and owns the bytes now
+    if (!taken)
+        return;
+    const committedRows = await selectMany(txDb, fileRefsTable, { storageKey }, { limit: 1, fields: ["id"] });
+    // skip: a fileRef row claims the bytes, only the stale ledger row goes
+    if (committedRows.length > 0)
+        return;
+    const failedKeys = await deleteFileRefBytes(files, { storageKey }, "upload-ledger-sweep");
+    if (failedKeys.length > 0)
+        throw new Error("bytes not fully deleted");
+}
+// Deletes the bytes (original and derivatives) of uploads that never got a fileRef row within the
+// grace period. Walks the ledger page by page along storage_key, so rows that keep failing or are
+// locked cannot hide the rows behind them; a failed row rolls back and the next run retries it.
+export async function sweepOrphanedUploads(args) {
+    const { db, files, now, graceHours, log } = args;
+    const pageSize = args.pageSize ?? ORPHANED_UPLOAD_SWEEP_BATCH;
+    if (!files) {
+        log?.warn("[upload-ledger-sweep] no file storage available, orphaned uploads kept");
+        return;
+    }
+    const cutoff = now.subtract({ hours: graceHours });
+    let cursor;
+    for (;;) {
+        const rows = await selectMany(db, fileUploadLedgerTable, { createdAt: { lt: cutoff }, ...(cursor !== undefined && { storageKey: { gt: cursor } }) }, { orderBy: { col: "storageKey", direction: "asc" }, fields: ["storageKey"], limit: pageSize });
+        const lastRow = rows[rows.length - 1];
+        // skip: an empty page means every due row has been visited
+        if (lastRow === undefined)
+            return;
+        cursor = lastRow.storageKey;
+        for (const { storageKey } of rows) {
+            try {
+                await runInOwnTransaction(db, (txDb) => sweepOrphanedUpload(txDb, files, storageKey));
+            }
+            catch (err) {
+                log?.warn(`[upload-ledger-sweep] orphaned upload not deleted, retried next run: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+}

package/dist/files/upload-ledger.d.ts

@@ -0,0 +1,10 @@
+import type { FileProviderResolver, FileUploadLedger } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
+import type { FileStorageProvider } from "@cosmicdrift/kumiko-types/file-storage-provider-types";
+import type { TenantId } from "@cosmicdrift/kumiko-types/identifiers";
+import type { DbConnection } from "../db/connection.ts";
+import { type EntityTableMeta } from "../db/entity-table-meta.ts";
+import { type TenantDb } from "../db/tenant-db.ts";
+export declare const fileUploadLedgerTable: EntityTableMeta;
+export declare function createFileUploadLedger(db: DbConnection | TenantDb, tenantId: TenantId): FileUploadLedger;
+export declare function withUploadLedger(resolver: (tenantId: TenantId) => Promise<FileStorageProvider>, db: DbConnection | TenantDb): FileProviderResolver;
+export declare function takeUploadLedgerEntry(txDb: TenantDb, storageKey: string): Promise<boolean>;

package/dist/files/upload-ledger.js

@@ -0,0 +1,47 @@
+import { defineUnmanagedTable } from "../db/entity-table-meta.js";
+import { createTenantDb } from "../db/tenant-db.js";
+import { tenantDbRunner } from "../db/tenant-db-runner.js";
+const CREATED_AT_INDEX = "store_file_upload_ledger_created_at_idx";
+// One row per upload whose bytes are in storage but whose fileRef row is not committed yet. The
+// commit path deletes it inside the transaction that creates the fileRef; the sweep finds the
+// rows that never got there. Unmanaged: a coordination aid, not state with an event history.
+export const fileUploadLedgerTable = defineUnmanagedTable({
+    tableName: "store_file_upload_ledger",
+    indexes: [{ name: CREATED_AT_INDEX, columns: ["created_at"] }],
+    columns: [
+        { name: "storage_key", pgType: "text", notNull: true, primaryKey: true },
+        { name: "tenant_id", pgType: "uuid", notNull: true },
+        { name: "created_at", pgType: "timestamptz", notNull: true },
+    ],
+});
+function isTenantDb(db) {
+    return "tenantId" in db && "fetchOne" in db && typeof db.fetchOne === "function";
+}
+// The ledger writes on a connection of its own, never on a handler transaction: a rollback of the
+// handler must not take the row with it, or the bytes it uploaded would be unfindable.
+export function createFileUploadLedger(db, tenantId) {
+    const runner = isTenantDb(db) ? tenantDbRunner(db) : db;
+    const ledgerDb = createTenantDb({ db: runner, tenantId });
+    return {
+        record: async (storageKey) => {
+            await ledgerDb.insertOne(fileUploadLedgerTable, {
+                storageKey,
+                tenantId,
+                createdAt: Temporal.Now.instant(),
+            });
+        },
+        forget: async (storageKey) => {
+            await ledgerDb.deleteMany(fileUploadLedgerTable, { storageKey });
+        },
+    };
+}
+export function withUploadLedger(resolver, db) {
+    return Object.assign(resolver, {
+        uploadLedgerFor: (tenantId) => createFileUploadLedger(db, tenantId),
+    });
+}
+// Runs inside the transaction that creates the fileRef row. False means no ledger row was left to
+// take: the sweep already removed the bytes, so the row must not be committed.
+export async function takeUploadLedgerEntry(txDb, storageKey) {
+    return (await txDb.deleteMany(fileUploadLedgerTable, { storageKey })) > 0;
+}

package/dist/i18n/index.d.ts

@@ -1,6 +1,6 @@
 import type { Registry } from "../engine/types/index.ts";
 export { hasMailTranslationKey, hasMailTranslations, listMailLocales, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.ts";
-export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.ts";
+export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, rankAcceptLanguage, rankPreferredLocales, resolveHeaderLocale, } from "./request-locale.ts";
 export { SETTINGS_HUB_I18N } from "./settings-hub-keys.ts";
 export type I18nOptions = {
     defaultLocale: string;

package/dist/i18n/index.js

@@ -1,6 +1,6 @@
 import { resolveTranslationValue } from "../ui-types/plural.js";
 export { hasMailTranslationKey, hasMailTranslations, listMailLocales, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
-export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.js";
+export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, rankAcceptLanguage, rankPreferredLocales, resolveHeaderLocale, } from "./request-locale.js";
 export { SETTINGS_HUB_I18N } from "./settings-hub-keys.js";
 export function createI18n(registry, options) {
     const translations = registry.getAllTranslations();

package/dist/i18n/request-locale.d.ts

@@ -5,12 +5,23 @@ export declare function isValidLocaleTag(value: string): boolean;
  *  hit registered keys regardless of header casing. */
 export declare function canonicalizeLocaleTag(tag: string): string;
 /**
- * Picks the best well-formed tag from an Accept-Language header (RFC 9110
- * §12.5.4): parses "tag;q=x" pairs, sorts by q descending (header order
- * breaks ties), and returns the first tag that passes isValidLocaleTag.
- * Tags with q=0 (explicitly excluded) are dropped entirely.
+ * Well-formed tags of an Accept-Language header (RFC 9110 §12.5.4) in
+ * preference order: "tag;q=x" pairs sorted by q descending, header order
+ * breaking ties. Tags with q=0 (explicitly excluded) and malformed tags are
+ * dropped. Tags are returned as sent, not canonicalized or deduped.
  */
+export declare function rankAcceptLanguage(header: string | undefined): string[];
+/** Picks the best well-formed tag from an Accept-Language header, see rankAcceptLanguage. */
 export declare function pickAcceptLanguage(header: string | undefined): string | undefined;
+/**
+ * Ordered locale preference of a page request: a valid `?lang=` first, then
+ * every Accept-Language tag by q. Canonicalized and deduped (case-insensitive),
+ * so a resolver can walk the list and take the first locale it has content for.
+ */
+export declare function rankPreferredLocales(options: {
+    readonly queryLang?: string | null | undefined;
+    readonly acceptLanguage?: string | null | undefined;
+}): string[];
 /**
  * Request-layer resolution: an explicit, validated X-Locale header wins;
  * otherwise the best Accept-Language tag; otherwise undefined — no signal

package/dist/i18n/request-locale.js

@@ -33,15 +33,15 @@ export function canonicalizeLocaleTag(tag) {
         .join("-");
 }
 /**
- * Picks the best well-formed tag from an Accept-Language header (RFC 9110
- * §12.5.4): parses "tag;q=x" pairs, sorts by q descending (header order
- * breaks ties), and returns the first tag that passes isValidLocaleTag.
- * Tags with q=0 (explicitly excluded) are dropped entirely.
+ * Well-formed tags of an Accept-Language header (RFC 9110 §12.5.4) in
+ * preference order: "tag;q=x" pairs sorted by q descending, header order
+ * breaking ties. Tags with q=0 (explicitly excluded) and malformed tags are
+ * dropped. Tags are returned as sent, not canonicalized or deduped.
  */
-export function pickAcceptLanguage(header) {
+export function rankAcceptLanguage(header) {
     if (header === undefined || header.length === 0)
-        return undefined;
-    const candidates = header
+        return [];
+    return header
         .split(",")
         .map((part, index) => {
         const [tagRaw, ...params] = part.trim().split(";");
@@ -54,8 +54,25 @@ export function pickAcceptLanguage(header) {
         return { tag, q, index };
     })
         .filter((c) => c !== undefined && c.q > 0)
-        .sort((a, b) => b.q - a.q || a.index - b.index);
-    return candidates[0]?.tag;
+        .sort((a, b) => b.q - a.q || a.index - b.index)
+        .map((c) => c.tag);
+}
+/** Picks the best well-formed tag from an Accept-Language header, see rankAcceptLanguage. */
+export function pickAcceptLanguage(header) {
+    return rankAcceptLanguage(header)[0];
+}
+/**
+ * Ordered locale preference of a page request: a valid `?lang=` first, then
+ * every Accept-Language tag by q. Canonicalized and deduped (case-insensitive),
+ * so a resolver can walk the list and take the first locale it has content for.
+ */
+export function rankPreferredLocales(options) {
+    const ranked = [];
+    if (options.queryLang != null && isValidLocaleTag(options.queryLang)) {
+        ranked.push(options.queryLang);
+    }
+    ranked.push(...rankAcceptLanguage(options.acceptLanguage ?? undefined));
+    return [...new Set(ranked.map(canonicalizeLocaleTag))];
 }
 /**
  * Request-layer resolution: an explicit, validated X-Locale header wins;

package/dist/jobs/job-runner.js

@@ -12,7 +12,7 @@ import { createSystemUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID, } from "../engine/types/index.js";
 import { InternalError } from "../errors/index.js";
 import { isKumikoError } from "../errors/kumiko-error.js";
-import { createFileContext } from "../files/file-handle.js";
+import { createTenantFileContext } from "../files/file-handle.js";
 import { createFallbackLogger } from "../logging/index.js";
 import { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, createMetricsForFactory, emitJobLastSuccess, emitJobQueueDepth, flushEscapeHatchAudits, getFallbackTracer, registerStandardMetrics, withEscapeHatchAuditScope, } from "../observability/index.js";
 import { createDistributedLock } from "../pipeline/distributed-lock.js";
@@ -903,9 +903,7 @@ export function createJobRunner(options) {
         // through the same _fileProviderResolver for jobs as for write-handlers,
         // otherwise event-triggered jobs silently get an unresolved ctx.files.
         const fileResolver = context._fileProviderResolver;
-        const files = fileResolver
-            ? createFileContext(() => fileResolver(tenantId), tenantId)
-            : context.files;
+        const files = fileResolver ? createTenantFileContext(fileResolver, tenantId) : context.files;
         const jobSystemUser = createSystemUser(tenantId);
         // Same buildHandlerContext parity as ctx.files above: ctx.notify/ctx.config
         // must resolve for jobs the same way they do for write-handlers, or an

package/dist/pipeline/dispatch-shared.js

@@ -12,7 +12,7 @@ import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictErro
 import { loadAggregate, loadAggregateAsOf, loadAggregateForWriting, } from "../event-store/event-store.js";
 import { effectiveSnapshotGeneration, loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapshot.js";
 import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
-import { createFileContext } from "../files/file-handle.js";
+import { createTenantFileContext } from "../files/file-handle.js";
 import { DEFAULT_LOCALE, isValidLocaleTag } from "../i18n/request-locale.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { createEscapeHatchReporter, createMetricsForFactory, createMetricsHandle, createNoopMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
@@ -459,9 +459,7 @@ readOnlyForTenant = false) {
     // _fileProviderResolver when a file-provider plugin is mounted; falls back
     // to a statically-injected context.files (tests).
     const fileResolver = context._fileProviderResolver;
-    const files = fileResolver
-        ? createFileContext(() => fileResolver(user.tenantId), user.tenantId)
-        : context.files;
+    const files = fileResolver ? createTenantFileContext(fileResolver, user.tenantId) : context.files;
     // ctx.derivatives builds on ctx.files (needs a FileContext to read the
     // original + write the variant) plus db (to look up the FileRef row) — so
     // it can only be constructed exactly when files+db both resolved; falls

package/dist/pipeline/index.d.ts

@@ -1,6 +1,7 @@
 export type { EscapeHatchReportWindow } from "../observability/escape-hatch-report.ts";
 export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "../observability/escape-hatch-report.ts";
 export { normalizePayloadBucketValue } from "../rate-limit/bucket.ts";
+export { createUnlimitedRateLimitResolver } from "../rate-limit/unlimited-resolver.ts";
 export type { AppendDomainEventCoreDeps } from "./append-event-core.ts";
 export { appendDomainEventCore } from "./append-event-core.ts";
 export type { ResolveAuthClaimsArgs } from "./auth-claims-resolver.ts";

package/dist/pipeline/index.js

@@ -1,5 +1,6 @@
 export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, flushEscapeHatchAudits, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, withEscapeHatchAuditScope, } from "../observability/escape-hatch-report.js";
 export { normalizePayloadBucketValue } from "../rate-limit/bucket.js";
+export { createUnlimitedRateLimitResolver } from "../rate-limit/unlimited-resolver.js";
 export { appendDomainEventCore } from "./append-event-core.js";
 export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";

package/dist/rate-limit/index.d.ts

@@ -1,3 +1,4 @@
 export { type BucketContext, type BucketResult, buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.ts";
 export { type AuthEndpointRateLimitOptions, authEndpointRateLimit, type GlobalIpRateLimitOptions, globalIpRateLimit, type HttpRouteRateLimitOptions, httpRouteRateLimit, } from "./middleware.ts";
 export { createRateLimitResolver, type RateLimitConfig, type RateLimitDecision, type RateLimitResolver, type RateLimitResolverOptions, } from "./resolver.ts";
+export { createUnlimitedRateLimitResolver } from "./unlimited-resolver.ts";

package/dist/rate-limit/index.js

@@ -1,3 +1,4 @@
 export { buildBucketKey, buildPayloadBucketKey, createPayloadDigest, normalizePayloadBucketValue, } from "./bucket.js";
 export { authEndpointRateLimit, globalIpRateLimit, httpRouteRateLimit, } from "./middleware.js";
 export { createRateLimitResolver, } from "./resolver.js";
+export { createUnlimitedRateLimitResolver } from "./unlimited-resolver.js";

package/dist/rate-limit/unlimited-resolver.d.ts

@@ -0,0 +1,2 @@
+import type { RateLimitResolver } from "@cosmicdrift/kumiko-types/rate-limit-types";
+export declare function createUnlimitedRateLimitResolver(): RateLimitResolver;

package/dist/rate-limit/unlimited-resolver.js

@@ -0,0 +1,21 @@
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+// Resolver for callers that are bootstrap work rather than tenant traffic (boot seeds,
+// seed migrations): a handler's `rateLimit` declaration must not fail them, and they must not
+// drain the buckets real requests share. Nothing is stored, so the decision is always "full bucket".
+export function createUnlimitedRateLimitResolver() {
+    function fullBucket(config) {
+        return {
+            allowed: true,
+            limit: config.limit,
+            remaining: config.limit,
+            retryAfterSeconds: 0,
+            windowSeconds: config.windowSeconds,
+            resetAt: Temporal.Instant.fromEpochMilliseconds(Date.now()),
+        };
+    }
+    return {
+        check: async (_bucket, config) => fullBucket(config),
+        enforce: async (_bucket, config) => fullBucket(config),
+        peek: async (_bucket, config) => fullBucket(config),
+    };
+}

package/dist/schema-cli.js

@@ -35,6 +35,41 @@ function withFileStoragePresence(env) {
         ? { ...env, [FILE_STORAGE_PROVIDER_ENV]: FILE_STORAGE_PROVIDER_BOOT_SENTINEL }
         : { ...env };
 }
+function isStringSet(value) {
+    return value instanceof Set && [...value].every((entry) => typeof entry === "string");
+}
+function isBoolean(value) {
+    return typeof value === "boolean";
+}
+function validateBootOptionsError(detail) {
+    return new Error(`kumiko/schema.ts: \`VALIDATE_BOOT_OPTIONS\` ${detail}`);
+}
+function readOptionalOption(raw, key, isValid, expected) {
+    const value = Reflect.get(raw, key);
+    if (value === undefined)
+        return undefined;
+    if (!isValid(value))
+        throw validateBootOptionsError(`\`${key}\` must be ${expected}.`);
+    return value;
+}
+// Boundary check for `export const VALIDATE_BOOT_OPTIONS` in kumiko/schema.ts.
+// Only the options that change what validateBoot reports are honoured; `env` and
+// `entityFieldCipher` are runner-injected and deliberately ignored here.
+function parseValidateBootOptions(raw) {
+    if (raw === undefined)
+        return {};
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw validateBootOptionsError("must be an object (ValidateBootOptions).");
+    }
+    const navAllowlist = readOptionalOption(raw, "navAllowlist", isStringSet, "a Set<string>");
+    const navAllowlistExempt = readOptionalOption(raw, "navAllowlistExempt", isStringSet, "a Set<string>");
+    const warnOnUniqueAccessRoles = readOptionalOption(raw, "warnOnUniqueAccessRoles", isBoolean, "a boolean");
+    return {
+        ...(navAllowlist !== undefined && { navAllowlist }),
+        ...(navAllowlistExempt !== undefined && { navAllowlistExempt }),
+        ...(warnOnUniqueAccessRoles !== undefined && { warnOnUniqueAccessRoles }),
+    };
+}
 // Single load-path for kumiko/schema.ts (512/3) — `generate` and `validate`
 // both need ENTITY_METAS (and validate additionally wants FEATURES); this is
 // the one place that enforces "ENTITY_METAS must be an array" so the two
@@ -42,13 +77,17 @@ function withFileStoragePresence(env) {
 // want a graceful exit code (validate) catch it themselves.
 async function loadSchemaModFromApp(schemaFile) {
     // bun imports TS directly — no spawn needed.
-    const mod = (await import(__rewriteRelativeImportExtension(schemaFile)));
-    if (!Array.isArray(mod.ENTITY_METAS)) {
+    const mod = await import(__rewriteRelativeImportExtension(schemaFile));
+    if (!Array.isArray(mod["ENTITY_METAS"])) {
         throw new Error(`Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`);
     }
-    const entityMetas = mod.ENTITY_METAS;
+    const entityMetas = mod["ENTITY_METAS"];
     assertUniqueTableNames(entityMetas);
-    return { entityMetas, features: mod.FEATURES };
+    return {
+        entityMetas,
+        features: mod["FEATURES"],
+        validateBootOptions: mod["VALIDATE_BOOT_OPTIONS"],
+    };
 }
 function nextSequenceNumber(migrationsDir) {
     if (!existsSync(migrationsDir))
@@ -201,7 +240,8 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             //   1. schema drift: would `generate` write a migration? (= an entity was
             //      added/changed but never generated → missing table → prod 500)
             //   2. boot validity: validateBoot over the composed FEATURES (QN/screen/
-            //      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES.
+            //      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES;
+            //      honours its optional VALIDATE_BOOT_OPTIONS export.
             //   3. migration-content drift: replay every committed *.sql file and
             //      diff the result against .snapshot.json — catches a migration
             //      file whose SQL body doesn't match what its own snapshot entry
@@ -257,6 +297,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             if (Array.isArray(mod.FEATURES)) {
                 try {
                     validateBoot(mod.FEATURES, {
+                        ...parseValidateBootOptions(schemaMod.validateBootOptions),
                         env: withFileStoragePresence(process.env),
                     });
                     out.log("  ✓ boot: feature configuration is valid");

package/package.json

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

package/src/changes.json

@@ -1,4 +1,46 @@
 [
+  {
+    "version": "0.372.0",
+    "type": "improvement",
+    "title": "kumiko check validates the boot configuration with the validateBootOptions from kumiko.config.ts",
+    "detail": "Set validateBootOptions in defineAppConfig (navAllowlist, navAllowlistExempt, warnOnUniqueAccessRoles); the managed kumiko/schema.ts exports it as VALIDATE_BOOT_OPTIONS and kumiko check validates with it. Apps with a hand-written kumiko/schema.ts can export VALIDATE_BOOT_OPTIONS themselves.",
+    "migration": "Existing apps get the new line in kumiko/schema.ts through `kumiko-upgrade --apply` (managed file). The bin files belong to the app: pass `...(appConfig.validateBootOptions && { validateBootOptions: appConfig.validateBootOptions })` to runProdApp in bin/main.ts and to runDevApp in bin/server.ts (import appConfig from \"../kumiko.config\") so runtime and kumiko check agree."
+  },
+  {
+    "version": "0.372.0",
+    "type": "fix",
+    "title": "createEntity no longer collapses to never for inline field literals such as { type: \"reference\", entity }",
+    "detail": "The fields type parameter is const, so the literal type of each inline field survives without as const."
+  },
+  {
+    "version": "0.372.0",
+    "type": "breaking",
+    "title": "executor.detail() and executor.list() return EntityRow<E>, derived from the entity definition",
+    "detail": "Rows of createEntityExecutor / createEventStoreExecutor are typed per entity; wide entities keep Record<string, unknown>. createBooleanField is typed non-null. UserMfaRow in the bundled auth-mfa feature now declares enabledAt and lastUsedAt as Temporal.Instant, which is what the row always held.",
+    "migration": "Remove the `row as T` casts on executor.detail() / executor.list() results with `bun kumiko-upgrade --apply` (codemod remove-engine-payload-casts). Casts to a type the row does not satisfy stay and are listed as manual; replace them with a field-level check or a narrower type.",
+    "codemod": "scripts/codemod/remove-engine-payload-casts.ts",
+    "manualAfterCodemod": true
+  },
+  {
+    "version": "0.372.0",
+    "type": "fix",
+    "title": "A save cannot reference a file that belongs to another record",
+    "detail": "Creating or updating a record with a file id that is already bound to a different record of the same tenant is now rejected with invalid_element on that field, the same error as for a foreign tenant. Pending uploads, ids the record already holds and moves between its own file fields are unaffected."
+  },
+  {
+    "version": "0.372.0",
+    "type": "breaking",
+    "title": "Tokens carrying system or all lose those roles on verify",
+    "detail": "jwt.verify strips the system and all roles that session minting never grants, so a self-signed or leaked-key token cannot act as System.",
+    "migration": "Apps that mint their own tokens with the `system` role must stop doing so and use `createSystemUser` or system dispatch in-process instead. Tokens issued by the framework are unaffected. Tests that send a system user over `stack.http.*` must switch to `stack.dispatcher.write/query`."
+  },
+  {
+    "version": "0.372.0",
+    "type": "breaking",
+    "title": "http.route and the metric route label carry the route pattern, http.target is removed",
+    "detail": "Spans are named \"METHOD pattern\" instead of \"http.request\"; paths no route matched are labelled \"unmatched\". The PII ciphertext guard message names the pattern as well.",
+    "migration": "Dashboards, alerts and trace queries keyed on raw paths or on the span name \"http.request\" must switch to route patterns and the \"METHOD pattern\" span name. Read the query string from your access logs if you relied on http.target."
+  },
   {
     "version": "0.371.0",
     "type": "improvement",

package/src/scripts/codemod/README.md

@@ -118,3 +118,25 @@ bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/import-extens
 Runs via `bun kumiko-upgrade --apply`. Without a mode flag it writes. `--check` exits 1 while any
 rewritable or manual site is left. The `import-extensions` guard (`kumiko check guards`) reports
 sites that are still on `.js`.
+
+## remove-engine-payload-casts.ts
+
+`executor.detail()` and `executor.list()` from `createEntityExecutor` / `createEventStoreExecutor`
+return the entity's own row type (`EntityRow<E>`), so `row["f"] as T`, `row as T` and
+`(await executor.detail(…)) as unknown as T` are usually redundant. The codemod removes such a cast,
+and its `@cast-boundary` marker comment when no other cast stays in the statement, only when the
+operand derives from an executor read (directly, through `rows[0]`, property access, `??` or a
+single-assignment variable) and the type checker says its type is assignable to the cast target. A
+file is left untouched if removing the casts would add type errors to it.
+
+It type-checks against the tsconfig at or above each file, so run it with the new framework version
+installed. Reported as `manual` and left alone: casts the row type does not satisfy (for example a
+nullable column cast to a non-null type, or `rows[0]` under `noUncheckedIndexedAccess`), and files
+without a tsconfig. A call site that still needs a narrower type than the row gives keeps its cast.
+
+```bash
+bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/remove-engine-payload-casts.ts <dir> [--check | --dry-run | --write] [--no-format]
+```
+
+Runs via `bun kumiko-upgrade --apply`. Without a mode flag it writes, then formats the changed files
+with Biome. `--check` exits 1 while any rewritable or manual site is left.