@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/random/generate.js

@@ -1,23 +1,23 @@
-// Random-Generator für human-readable Resource-Identifier:
-//   - Tenant-Keys ("happy-cloud", "swift-river-k8x")
-//   - Webhook-Subscriber-Slugs ("bold-falcon-receiver" mit custom nouns)
-//   - API-Key-Display-Names (3 Vorschläge anbieten beim Create)
-//   - Tenant-Subdomain-Vorschläge im Subdomain-Setup-Screen
-//   - Test-Fixtures mit lesbaren Identifiern
+// Random generator for human-readable resource identifiers:
+//   - Tenant keys ("happy-cloud", "swift-river-k8x")
+//   - Webhook subscriber slugs ("bold-falcon-receiver" with custom nouns)
+//   - API key display names (offer 3 suggestions on creation)
+//   - Tenant subdomain suggestions in the subdomain setup screen
+//   - Test fixtures with readable identifiers
 //
-// NICHT für Security-Token (CSRF, Session, API-Keys, OAuth-State,
-// Reset-Token). Math.random() ist nicht kryptografisch unvorhersagbar.
-// Authority-binding für Tenant-Keys läuft über JWT + DB-Lookup, nicht
-// über Slug-Geheimhaltung — der Slug darf erratbar sein.
+// NOT for security tokens (CSRF, session, API keys, OAuth state,
+// reset tokens). Math.random() is not cryptographically unpredictable.
+// Authority binding for tenant keys uses JWT + DB lookup, not slug secrecy;
+// the slug may be guessable.
 //
-// Universal-safe: Math.random() läuft in Bun, Node, Metro/RN, Expo-Web.
-// Keine node:crypto-Imports.
+// Safe across environments: Math.random() runs in Bun, Node, Metro/RN, and
+// Expo Web. No node:crypto imports.
 import { ADJECTIVES, NOUNS } from "./words.js";
-// Alphabet ohne handgetippt verwechselbare Zeichen:
-//   - keine 0/O (Null vs Großbuchstabe O)
-//   - keine 1/l/I (Eins vs Kleinbuchstabe L vs Großbuchstabe I)
-// Resultat: 32 Zeichen, sicher beim Telefon-Buchstabieren UND beim
-// Mailtext-Copy-Paste in fremde Schriftarten.
+// Alphabet without characters that are easily confused when entered manually:
+//   - no 0/O (zero versus uppercase O)
+//   - no 1/l/I (one versus lowercase L versus uppercase I)
+// Result: 32 characters, safe for spelling over the phone AND for copying
+// from email text in unfamiliar fonts.
 const NO_CONFUSABLE_ALPHABET = "23456789abcdefghjkmnpqrstuvwxyz";
 const NO_CONFUSABLE_CHARS = Object.freeze(NO_CONFUSABLE_ALPHABET.split(""));
 function pickRandom(arr) {
@@ -25,15 +25,15 @@ function pickRandom(arr) {
         throw new Error("pickRandom: cannot pick from empty array");
     }
     const value = arr[Math.floor(Math.random() * arr.length)];
-    // Length-Check oben garantiert dass index in-range ist.
+    // The length check above guarantees that the index is in range.
     if (value === undefined) {
         throw new Error("pickRandom: indexed value undefined (sparse array?)");
     }
     return value;
 }
-/** Sync Generator: produziert "happy-cloud" oder "happy-cloud-k8x"
- *  (mit suffix). Kein Conflict-Check — Caller verantwortlich für
- *  Uniqueness, oder generateUniqueName() für die async Variante. */
+/** Sync generator: produces "happy-cloud" or "happy-cloud-k8x"
+ *  (with suffix). No conflict check — the caller is responsible for
+ *  uniqueness, or can use generateUniqueName() for the async variant. */
 export function generateAdjNounName(options = {}) {
     const sep = options.separator ?? "-";
     const adjs = options.adjectives ?? ADJECTIVES;
@@ -44,9 +44,9 @@ export function generateAdjNounName(options = {}) {
     }
     return name;
 }
-/** Random-String aus dem no-confusable-Alphabet. Für Suffix-bei-Kollision
- *  oder als standalone short-IDs (z.B. Webhook-Verifizierungs-Codes
- *  zum Vorlesen am Telefon). length ≥ 1. */
+/** Random string from the no-confusable alphabet. For suffixes after
+ *  collisions or as standalone short IDs (e.g. webhook verification codes
+ *  to be read aloud over the phone). length ≥ 1. */
 export function generateNoConfusableId(length) {
     if (length < 1) {
         throw new Error(`generateNoConfusableId: length must be ≥ 1 (got ${length})`);
@@ -57,17 +57,17 @@ export function generateNoConfusableId(length) {
     }
     return id;
 }
-/** Generiert einen unique Adj-Noun-Slug indem es bis zu maxCleanAttempts
- *  saubere Wortpaare versucht, danach mit random Suffix bis maxTotal-
- *  Attempts. Wirft wenn auch das nicht hilft (= caller hat ein Bug
- *  mit isAvailable, oder die Wortliste ist defekt).
+/** Generates a unique Adj-Noun slug by trying up to maxCleanAttempts
+ *  clean word pairs, then using a random suffix up to maxTotal-
+ *  Attempts. Throws if that also fails (= the caller has a bug
+ *  in isAvailable, or the word list is defective).
  *
- *  Beispiel:
+ *  Example:
  *    const slug = await generateUniqueName({
  *      isAvailable: async (s) =>
  *        !(await db.select().from(tenants).where(eq(tenants.tenantKey, s)).then(r => r.length > 0)),
  *    });
- *    // → "happy-cloud" oder "happy-cloud-k8x" bei Kollision
+ *    // → "happy-cloud" or "happy-cloud-k8x" on collision
  */
 export async function generateUniqueName(options) {
     const maxClean = options.maxCleanAttempts ?? 3;

package/dist/random/words.js

@@ -1,26 +1,26 @@
-// Wortlisten für human-readable Resource-Slugs (Tenant-Keys, Webhook-
-// Subscribers, API-Key-Display-Names, Test-Fixtures). Heroku/Docker-
-// Style — adjective + noun produzieren aussprechbare, merkbare,
-// PII-freie Identifier.
+// Word lists for human-readable resource slugs (tenant keys, webhook-
+// subscribers, API-key display names, test fixtures). Heroku/Docker-
+// style — adjective + noun produce pronounceable, memorable,
+// PII-free identifiers.
 //
-// Auswahl-Kriterien:
-//   - Emotional-neutral und professionell (kein "fluffy", "sneaky")
-//   - Keine Tiernamen (Heroku-Cliché)
-//   - Keine Personennamen (cultural appropriation, prominenten-collision)
-//   - Keine Themen-Cluster (kein Wetter-only, kein Geographie-only)
-//   - Lowercase, ASCII-only, keine Bindestriche im Wort selbst
-//   - 3-10 Buchstaben pro Wort (kompakter Slug)
-//   - Aussprechbar in Deutsch UND Englisch (User-Telefon-Support)
-//   - Keine Wörter mit ambiguer Bedeutung in Englisch+Deutsch
+// Selection criteria:
+//   - Emotionally neutral and professional (no "fluffy", "sneaky")
+//   - No animal names (Heroku cliché)
+//   - No personal names (cultural appropriation, celebrity collisions)
+//   - No thematic clusters (neither weather-only nor geography-only)
+//   - Lowercase, ASCII-only, with no hyphens within a word
+//   - 3–10 letters per word (compact slug)
+//   - Pronounceable in German AND English (user phone support)
+//   - No words with ambiguous meanings in English and German
 //
-// 191 × 173 = 33.043 saubere Kombinationen. Birthday-Bound: ab ~180
-// Tenants wird kumulativ die erste Kollision wahrscheinlich (~50%);
-// pro Einzel-Draw bleibt p(Kollision) < 1% (vgl. generate.ts). Bei
-// Kollision greift der Suffix-Pfad in generateUniqueName.
+// 191 × 173 = 33,043 clean combinations. Birthday bound: from ~180
+// tenants onward, the first collision becomes likely cumulatively (~50%);
+// for an individual draw, p(collision) remains < 1% (see generate.ts). On
+// collision, the suffix path in generateUniqueName is used.
 //
-// Erweiterung: weitere Wörter unten anhängen reicht (sortiert ist
-// hilfreich für Reviews aber nicht erforderlich). Caller können auch
-// eigene Listen via generateUniqueName({ adjectives, nouns }) reichen.
+// Extension: appending more words below is sufficient (sorting helps with
+// reviews but is not required). Callers can also provide custom lists via
+// generateUniqueName({ adjectives, nouns }).
 export const ADJECTIVES = Object.freeze([
     "agile",
     "amber",

package/dist/rate-limit/middleware.js

@@ -108,21 +108,25 @@ export function createFailOpenReporter(label, meter, now = Date.now) {
         lastWarnAt = nowMs;
         logger.warn("rate limiter unavailable, failing open", {
             label,
-            // ioredis errors can carry the command args, i.e. the bucket key with IP/target.
+            // ioredis errors can carry the command args, i.e. the bucket key. scrubLogText masks an e-mail
+            // address in it; the client IP stays in the line as an operational datum.
             error: scrubLogText(err instanceof Error ? err.message : String(err)),
         });
     };
 }
+const failClosedLogger = createFallbackLogger("rate-limit");
 function defaultOnFailClosed(label) {
     return (err) => {
         // Loud by default — fail-closed for an unknown reason is an ops
         // signal, not something to swallow silently. Production deploys
         // override this with a structured logger; the default keeps the
         // noise visible if no logger is wired.
-        // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-        console.error(`[rate-limit ${label}] fail-closed (refusing request):`, 
-        // ioredis errors can carry the command args, i.e. the bucket key with IP/target.
-        err instanceof Error ? err.message : String(err));
+        failClosedLogger.error("fail-closed (refusing request)", {
+            label,
+            // ioredis errors can carry the command args, i.e. the bucket key. scrubLogText masks an e-mail
+            // address in it; the client IP stays in the line as an operational datum.
+            error: scrubLogText(err instanceof Error ? err.message : String(err)),
+        });
     };
 }
 function setRateLimitHeaders(c, decision) {

package/dist/redis/client.js

@@ -8,8 +8,8 @@
 // production defaults stay consistent and env-var wiring lives in one
 // place. Tests / one-off scripts can still `new Redis()` directly.
 //
-// Split out of index.ts (fw#2625) so pubsub-signal.ts can import this
-// without a same-directory cycle back through the barrel.
+// Split out of index.ts so pubsub-signal.ts can import this without a
+// same-directory cycle back through the barrel.
 import { Redis } from "ioredis";
 import { scrubLogText } from "../logging/scrub.js";
 import { readPositiveIntEnv } from "../utils/env-parse.js";

package/dist/redis/pubsub-signal.js

@@ -1,18 +1,19 @@
+import { createFallbackLogger } from "../logging/utils.js";
 import { createRedisClient } from "./client.js";
 // Redis emits 'error' on connection blips (reconnects transparently); an
-// unhandled listener crashes the process (fw#1805 — job-runner hit the same
-// class with BullMQ's internal client).
-function logConnectionError(label, role) {
+// unhandled listener crashes the process — job-runner hit the same
+// class with BullMQ's internal client.
+function logConnectionError(log, role) {
     return (err) => {
-        // biome-ignore lint/suspicious/noConsole: ops-visible fallback — no logger is threaded through PubSubSignalOptions.
-        console.error(`[kumiko:${label}] ${role} connection error:`, err.message);
+        log.error(`${role} connection error`, { error: err.message });
     };
 }
 export function createRedisPubSubSignal(opts) {
+    const log = createFallbackLogger(`kumiko:${opts.label}`);
     const publisher = createRedisClient(opts.redisUrl, opts.clientOptions);
     const subscriber = createRedisClient(opts.redisUrl, opts.clientOptions);
-    publisher.on("error", logConnectionError(opts.label, "publisher"));
-    subscriber.on("error", logConnectionError(opts.label, "subscriber"));
+    publisher.on("error", logConnectionError(log, "publisher"));
+    subscriber.on("error", logConnectionError(log, "subscriber"));
     const listeners = new Set();
     const reconnectListeners = new Set();
     // Sole purpose: stop close() from racing the initial psubscribe (see
@@ -26,8 +27,7 @@ export function createRedisPubSubSignal(opts) {
             payload = JSON.parse(message);
         }
         catch (err) {
-            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-            console.error(`[kumiko:${opts.label}] dropping unparseable message on "${channel}":`, err);
+            log.error(`dropping unparseable message on "${channel}"`, { err });
             // skip: unparseable payload already logged above, nothing to deliver
             return;
         }
@@ -37,14 +37,14 @@ export function createRedisPubSubSignal(opts) {
     // ponytail: psubscribe on one pattern rather than per-channel
     // subscribe/unsubscribe — every instance receives every message that
     // matches, filtered by the caller. That's strictly no worse than the
-    // pre-fw#2625 per-instance-cursor model (which already read every event
+    // per-instance-cursor model (which already read every event
     // from Postgres in every process) and sidesteps the subscribe-ack/
     // first-publish race a per-channel scheme would have. Revisit with
     // per-channel subscribe only if fanout volume becomes the bottleneck.
     //
     // Awaited by close() below — quitting while this is still in flight (a
     // shutdown landing immediately after construction, e.g. a test closing
-    // right after building the signal) makes ioredis rejects the queued
+    // right after building the signal) makes ioredis reject the queued
     // psubscribe with "Connection is closed" instead of it completing
     // cleanly first. Not caught here or logged when a close is already
     // underway (`closed`), so an intentional shutdown never surfaces this
@@ -54,8 +54,7 @@ export function createRedisPubSubSignal(opts) {
         // this rejection is the expected side effect, not an ops-visible error.
         if (closed)
             return;
-        // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-        console.error(`[kumiko:${opts.label}] psubscribe failed:`, err);
+        log.error("psubscribe failed", { err });
     });
     // ioredis re-sends the psubscribe itself (autoResubscribe) but emits no ack
     // event; repeating it here queues behind that one on the same connection,
@@ -77,8 +76,7 @@ export function createRedisPubSubSignal(opts) {
             // skip: a close() already underway intentionally quit the connection
             if (closed)
                 return;
-            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-            console.error(`[kumiko:${opts.label}] resubscribe failed:`, err);
+            log.error("resubscribe failed", { err });
         });
     });
     return {
@@ -88,8 +86,7 @@ export function createRedisPubSubSignal(opts) {
                 // connections — this rejection is the expected side effect.
                 if (closed)
                     return;
-                // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
-                console.error(`[kumiko:${opts.label}] publish failed:`, err);
+                log.error("publish failed", { err });
             });
         },
         async publishConfirmed(channel, payload) {

package/dist/schema-cli.js

@@ -17,8 +17,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve as resolvePath } from "node:path";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolveKmsWiringAsync, } from "./crypto/index.js";
 import { assertUniqueTableNames, assertValidMigrationName, baselineMigrations, createDbConnection, diffReplayAgainstSnapshot, fetchAppliedMigrations, findCommentedDropTables, generateMigration, isRetiredFrameworkTable, loadMigrationsFromDir, loadSnapshotJson, readMigrationSqlTexts, rebuildTablesFromDiff, replayMigrationsDir, runMigrationsFromDir, tableExists, writeRebuildMarker, writeSnapshotJson, } from "./db/index.js";
+import { isEntityTableMeta } from "./db/table-introspection.js";
 import { validateBoot } from "./engine/boot-validator.js";
 import { FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, } from "./engine/extension-names.js";
 import { createRegistry } from "./engine/registry.js";
@@ -75,6 +77,79 @@ function parseValidateBootOptions(raw) {
         ...(warnOnUniqueAccessRoles !== undefined && { warnOnUniqueAccessRoles }),
     };
 }
+function tableNameHint(entry) {
+    if (isPlainObject(entry) && typeof entry["tableName"] === "string")
+        return entry["tableName"];
+    return "unknown";
+}
+// Every non-optional top-level property of FeatureDefinition, grouped by the runtime shape the
+// boot validators rely on; a hand-built entry missing one would crash far from the cause.
+const FEATURE_ARRAY_KEYS = [
+    "requires",
+    "optionalRequires",
+    "configSeeds",
+    "extensionUsages",
+    "extensionSelectors",
+    "bootChecks",
+    "referenceData",
+    "configReads",
+    "authClaimsHooks",
+];
+const FEATURE_SET_KEYS = [
+    "requiredProjections",
+    "requiredSteps",
+    "exposedApis",
+    "usedApis",
+];
+const FEATURE_RECORD_KEYS = [
+    "relations",
+    "writeHandlers",
+    "queryHandlers",
+    "streamHandlers",
+    "translations",
+    "configKeys",
+    "jobs",
+    "registrarExtensions",
+    "notifications",
+    "events",
+    "eventMigrations",
+    "handlerEntityMappings",
+    "metrics",
+    "secretKeys",
+    "secretNamespaces",
+    "projections",
+    "multiStreamProjections",
+    "claimKeys",
+    "screens",
+    "navs",
+    "workspaces",
+    "httpRoutes",
+    "webSocketRoutes",
+    "storeTables",
+];
+function isFeatureDefinitionShape(entry) {
+    if (!isPlainObject(entry))
+        return false;
+    return (typeof entry["name"] === "string" &&
+        typeof entry["systemScope"] === "boolean" &&
+        FEATURE_ARRAY_KEYS.every((key) => Array.isArray(entry[key])) &&
+        FEATURE_SET_KEYS.every((key) => entry[key] instanceof Set) &&
+        FEATURE_RECORD_KEYS.every((key) => isPlainObject(entry[key])));
+}
+// FEATURES comes from the app's schema module; one malformed entry would make
+// validateBoot fail with an unrelated error far from the cause, so name the index here.
+function featureDefinitionsOf(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const definitions = [];
+    for (const [index, entry] of value.entries()) {
+        if (!isFeatureDefinitionShape(entry)) {
+            throw new Error(`FEATURES[${index}] is not a FeatureDefinition (expected an object with a string \`name\`)`);
+        }
+        definitions.push(entry);
+    }
+    return definitions;
+}
 // 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
@@ -83,13 +158,20 @@ function parseValidateBootOptions(raw) {
 async function loadSchemaModFromApp(schemaFile) {
     // bun imports TS directly — no spawn needed.
     const mod = await import(__rewriteRelativeImportExtension(schemaFile));
-    if (!Array.isArray(mod["ENTITY_METAS"])) {
+    const entityMetas = mod["ENTITY_METAS"];
+    if (!Array.isArray(entityMetas)) {
         throw new Error(`Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`);
     }
-    const entityMetas = mod["ENTITY_METAS"];
-    assertUniqueTableNames(entityMetas);
+    const validMetas = [];
+    for (const [index, entry] of entityMetas.entries()) {
+        if (!isEntityTableMeta(entry)) {
+            throw new Error(`Schema file ${schemaFile}: ENTITY_METAS[${index}] is not an EntityTableMeta (table: ${tableNameHint(entry)}).`);
+        }
+        validMetas.push(entry);
+    }
+    assertUniqueTableNames(validMetas);
     return {
-        entityMetas,
+        entityMetas: validMetas,
         features: mod["FEATURES"],
         validateBootOptions: mod["VALIDATE_BOOT_OPTIONS"],
     };
@@ -223,9 +305,9 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 mkdirSync(migrationsDir, { recursive: true });
             writeFileSync(join(migrationsDir, result.filename), result.sqlContent);
             writeSnapshotJson(snapshotPath, result.snapshot);
-            // Rebuild-Marker nur für inkrementelle Migrationen — die Init-Migration
-            // (prevSnapshot===null) legt nur Tabellen an, es gibt keine historischen
-            // Events zum Replayen.
+            // Rebuild markers are written only for incremental migrations — the initial
+            // migration (prevSnapshot===null) only creates tables, so there are no historical
+            // events to replay.
             const rebuildTables = prevSnapshot === null ? [] : rebuildTablesFromDiff(result.diff);
             writeRebuildMarker(migrationsDir, result.filename, rebuildTables);
             out.log("");
@@ -269,7 +351,6 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 out.err(`  ${e instanceof Error ? e.message : String(e)}`);
                 return 1;
             }
-            const mod = { FEATURES: schemaMod.features };
             let ok = true;
             // 1. Schema drift — compute the diff, never write.
             const metas = schemaMod.entityMetas;
@@ -299,9 +380,21 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 out.err("    Fix: `kumiko-schema generate <name>`, then commit the migration.");
             }
             // 2. Boot validity — needs the composed feature set.
-            if (Array.isArray(mod.FEATURES)) {
+            let bootFeatures;
+            let bootFeaturesError;
+            try {
+                bootFeatures = featureDefinitionsOf(schemaMod.features);
+            }
+            catch (e) {
+                bootFeaturesError = e instanceof Error ? e.message : String(e);
+            }
+            if (bootFeaturesError !== undefined) {
+                ok = false;
+                out.err(`  ✗ boot: ${bootFeaturesError}`);
+            }
+            else if (bootFeatures) {
                 try {
-                    validateBoot(mod.FEATURES, {
+                    validateBoot(bootFeatures, {
                         ...parseValidateBootOptions(schemaMod.validateBootOptions),
                         env: withFileStoragePresence(process.env),
                     });
@@ -350,7 +443,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                     // replayMigrationsDir fail-loud's on a table-DDL statement it can't
                     // parse — that must surface as a normal ✗ line like every other
                     // check here, not a raw stack trace that kills the process before
-                    // any later check (or the Fix: help) ever runs (framework#1535).
+                    // any later check (or the Fix: help) ever runs.
                     ok = false;
                     out.err(`  ✗ migration-content: ${e instanceof Error ? e.message : String(e)}`);
                     out.err("    Fix: a statement in a migration file isn't recognizable to the replay parser — extend the parser's recognized patterns, or reword the migration to one it understands.");
@@ -372,11 +465,12 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             let wiring;
             try {
                 const result = await runMigrationsFromDir(db, migrationsDir);
-                // Framework-Infra-Tabellen (event-store + pipeline-state) — die erfasst
-                // `generate` nicht (nur Entity-read-Tabellen). Bestehende DBs haben sie
-                // aus dem legacy-drizzle-Fundament; eine Greenfield-DB (erste App ohne
-                // Cutover) hätte sonst kein kumiko_events → runProdApp-Boot scheitert.
-                // Alle drei sind idempotent (tableExists-Gate), also no-op für Bestands-DBs.
+                // Framework infrastructure tables (event store + pipeline state) are not captured by
+                // `generate`, which handles only entity read tables. Existing databases have them
+                // from the legacy-drizzle foundation; without them, a greenfield database (the
+                // first app without a cutover) would lack kumiko_events and runProdApp would fail
+                // during boot. All three are idempotent (tableExists-gated), so they are no-ops for
+                // existing databases.
                 await createEventsTable(db);
                 await createEventConsumerStateTable(db);
                 await createProjectionStateTable(db);
@@ -400,14 +494,14 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 // (kumiko_pending_rebuilds) survives a failed/crashed rebuild from an
                 // earlier apply, so a later apply with zero new migrations still must
                 // retry it — otherwise a failed rebuild is silently never retried,
-                // since the migration itself is already tracked applied (#2464).
+                // since the migration itself is already tracked applied.
                 if (options.features) {
                     // A rebuild replays applyEntityEvent, which computes bidx columns from
                     // configureBlindIndexKey/configurePiiSubjectKms — both boot-injected by
                     // run{Prod,Dev}App but never by this standalone CLI (the migrate-db
                     // initContainer). Without wiring them here, a rebuild would silently
                     // null out bidx columns and, for ciphertext, throw only once it hits
-                    // the row (fw#3091).
+                    // the row.
                     wiring = await resolveKmsWiringAsync(process.env, {
                         logPrefix: "[kumiko schema apply]",
                         log: out.log,
@@ -485,10 +579,10 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             const local = loadMigrationsFromDir(migrationsDir);
             const { db, close } = createDbConnection({ url: dbUrl });
             try {
-                // Frische DB ohne je gelaufenes `kumiko schema apply` → tracking-table
-                // fehlt = "nichts applied". Connection-/Permission-Fehler dagegen
-                // sollen NICHT geschluckt werden (False-pending verschleiert das Problem) —
-                // tableExists prüft gezielt nur Existenz, alles andere propagiert.
+                // On a fresh database where `kumiko schema apply` has never run, the tracking table is
+                // absent, which means "nothing applied". Connection and permission errors must not
+                // be swallowed (false pending results would hide the problem) — tableExists checks
+                // only for existence, while all other errors propagate.
                 const trackingExists = await tableExists(db, "_kumiko_migrations");
                 const applied = trackingExists
                     ? new Set((await fetchAppliedMigrations(db)).map((a) => a.id))

package/dist/search/index.js

@@ -1,7 +1,7 @@
-// Meilisearch-Adapter lebt im Sub-Path-Export `@cosmicdrift/kumiko-framework/search/meilisearch`.
-// Damit lädt der Main-Barrel keinen Meilisearch-Client beim bloßen Anfassen
-// von SearchAdapter-Types. Apps die Meilisearch nicht nutzen, ziehen den
-// Client-Code nicht mit rein.
+// The Meilisearch adapter is exposed through the subpath export
+// `@cosmicdrift/kumiko-framework/search/meilisearch`. This keeps the main barrel from loading a
+// Meilisearch client when consumers only use SearchAdapter types, so apps that do not use
+// Meilisearch do not pull in the client code.
 export { collectSearchableFieldNames, configureTenantSearchIndex, } from "./configure-tenant-index.js";
 export { deriveSearchAdapterConfig } from "./derive-search-adapter-config.js";
 export { createInMemorySearchAdapter } from "./in-memory-adapter.js";

package/dist/search/purge-subject.js

@@ -1,4 +1,4 @@
-// Purge derived search documents for an erased PII subject (#1610).
+// Purge derived search documents for an erased PII subject.
 //
 // After kms.eraseKey the projection/event ciphertext is unreadable, but Meili
 // still holds the plaintext that createSearchEventConsumer decrypted into the
@@ -152,7 +152,7 @@ subject) {
             if (declaredFields.length === 0)
                 continue;
             const tableName = resolveTableName(entityName, entity, undefined);
-            // Same post-eraseKey hazard as nullBlindIndexesForSubject (fw#2550):
+            // Same post-eraseKey hazard as nullBlindIndexesForSubject:
             // a mounted feature without its migration must not abort the purge
             // (and the audit event after it).
             if (!(await tableExists(db, tableName)))
@@ -178,13 +178,12 @@ subject) {
     for (const [tenantId, items] of byTenant) {
         if (items.length === 0)
             continue;
-        const tid = tenantId;
         if (search.removeBatch) {
-            await search.removeBatch(tid, items);
+            await search.removeBatch(tenantId, items);
         }
         else {
             for (const item of items) {
-                await search.remove(tid, item.entityType, item.entityId);
+                await search.remove(tenantId, item.entityType, item.entityId);
             }
         }
     }

package/dist/search/reindex-entity.js

@@ -1,5 +1,5 @@
 // One-time backfill for entities that only got `searchable: true` after rows
-// already existed (#1206). buildSearchDocument() only runs on the write path
+// already existed. buildSearchDocument() only runs on the write path
 // (createSearchEventConsumer, system-hooks.ts) — pre-existing rows never
 // pass through it, so they stay unfindable until their next write. This
 // re-derives a SearchDocument straight from the read-table row for every
@@ -47,12 +47,8 @@ async function scanAndIndexEntity(db, registry, searchAdapter, entityName, tenan
     // calls searchAdapter.remove()) — resurrecting them here would make
     // erased entities findable again.
     const deletedFilter = entity.softDelete === true ? `AND ${quoteIdent("is_deleted")} IS NOT TRUE` : "";
-    const result = {
-        scannedRows: 0,
-        indexedRows: 0,
-        wouldIndexRows: 0,
-        failures: [],
-    };
+    const failures = [];
+    const result = { scannedRows: 0, indexedRows: 0, wouldIndexRows: 0, failures };
     let lastId;
     // Whether a searchable field lacks a matching read-table column depends
     // only on the table's column set (rowToState/Object.hasOwn), not on any
@@ -69,11 +65,12 @@ async function scanAndIndexEntity(db, registry, searchAdapter, entityName, tenan
         WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter} ${afterLastId}
         ORDER BY ${quoteIdent("id")} ASC
         LIMIT $2`, lastId === undefined ? [tenantId, batchSize] : [tenantId, batchSize, lastId]);
-        if (rows.length === 0)
+        const [firstRow] = rows;
+        if (firstRow === undefined)
             break;
         if (uncheckedSchema) {
             uncheckedSchema = false;
-            const sampleState = rowToState(rows[0], fieldNames);
+            const sampleState = rowToState(firstRow, fieldNames);
             const unmappedField = searchableFields.find((fieldName) => !(fieldName in sampleState));
             if (unmappedField !== undefined) {
                 throw new Error(`reindexEntity: searchable field "${unmappedField}" is not mappable from read-table ` +

package/dist/time/boot-tz-warning.d.ts

@@ -1,5 +1,5 @@
 /**
- * Warnt einmalig beim Server-Start, wenn die Prozess-TZ nicht UTC ist.
- * Parameter sind für Tests injizierbar. Gibt zurück, ob gewarnt wurde.
+ * Warn once at server startup when the process time zone is not UTC.
+ * Parameters are injectable for tests. Returns whether a warning was emitted.
  */
 export declare function warnIfNonUtcServerTimeZone(resolvedTimeZone?: string, warn?: (message: string) => void): boolean;

package/dist/time/boot-tz-warning.js

@@ -1,17 +1,17 @@
-// Boot-Warnung wenn die Prozess-Uhr nicht in UTC läuft. Der gesamte
-// Server-Code nimmt UTC an (System-TZ ist kein Konzept — siehe timezones.md);
-// eine abweichende Prozess-TZ lässt versehentliche new Date()-Pfade
-// lokal-abhängig brechen ("grün in UTC-CI, kaputt in Berlin-Prod"). Soft:
-// nicht-UTC ist in Dev legitim, daher Warnung statt Boot-Fehler.
+// Warn at boot when the process time zone is not UTC. All server code assumes UTC
+// (the system time zone is not a framework concept); a different process time zone
+// can make accidental new Date() paths behave differently locally ("green in UTC-CI,
+// broken in Berlin production"). This is a soft check: non-UTC is legitimate in
+// development, so warn instead of failing boot.
 function resolvedServerTimeZone() {
     return Intl.DateTimeFormat().resolvedOptions().timeZone;
 }
 /**
- * Warnt einmalig beim Server-Start, wenn die Prozess-TZ nicht UTC ist.
- * Parameter sind für Tests injizierbar. Gibt zurück, ob gewarnt wurde.
+ * Warn once at server startup when the process time zone is not UTC.
+ * Parameters are injectable for tests. Returns whether a warning was emitted.
  */
 export function warnIfNonUtcServerTimeZone(resolvedTimeZone = resolvedServerTimeZone(), 
-// biome-ignore lint/suspicious/noConsole: boot-time warning, no logger wired this early
+// biome-ignore lint/suspicious/noConsole: runs before any logger exists; the default is the only console sink
 warn = console.warn) {
     // GMT and Etc/UTC are UTC-equivalent (no offset, no DST) — TZ=GMT is a
     // legitimate way to pin a process to UTC and must not trip this warning.