@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/pipeline/system-hooks.js

@@ -4,25 +4,26 @@ import { collectSearchableSubjectFields, configuredPiiSubjectKms, decryptPiiFiel
 import { createTenantDb, entityTableFromRegistry, rehydrateCompoundTypes } from "../db/index.js";
 import { tenantChannel } from "../engine/constants.js";
 import { InternalError } from "../errors/index.js";
+import { createFallbackLogger } from "../logging/utils.js";
+const log = createFallbackLogger("kumiko:search");
 // --- Search Index Consumer (async, via event-dispatcher) ---
 //
-// Search-Indexierung läuft seit D.4 als async EventConsumer über den event-
-// dispatcher, nicht mehr als synchroner postSave/postDelete-hook. Das
-// spiegelt Marten's ISubscription-Pattern: ein einziger async Pfad für alle
-// non-inline side-effects.
+// Search indexing runs as an async EventConsumer through the event dispatcher,
+// rather than as a synchronous postSave/postDelete hook. This mirrors Marten's
+// ISubscription pattern: one async path for all non-inline side effects.
 //
 // Event → Search-Op Mapping:
 //
 //   <entity>.created     → index(tenantId, doc)   // state = event.payload
 //   <entity>.updated     → index(tenantId, doc)   // state = { ...previous, ...changes }
 //   <entity>.restored    → index(tenantId, doc)   // state = event.payload.previous
-//   <entity>.deleted     → remove(tenantId, type, id)
-//   <entity>.forgotten   → remove(tenantId, type, id)
-//   <entity>.<named>     → index or remove, state read from the live
-//                          projection row (#2765) — a named domain event
-//                          carries only a payload slice, not the full
-//                          entity, so there's no fixed shape to reconstruct
-//                          state from the way created/updated/restored do.
+//   <entity>.deleted      → remove(tenantId, type, id)
+//   <entity>.forgotten    → remove(tenantId, type, id)
+//   <entity>.<named>      → index or remove, state read from the live
+//                          projection row — a named domain event carries
+//                          only a payload slice, not the full entity, so
+//                          there's no fixed shape to reconstruct state from
+//                          as there is for created/updated/restored.
 //                          Only queried when the entity declares searchable
 //                          fields/extensions; no row (hard/soft-deleted) →
 //                          remove, same as the deleted branch.
@@ -36,7 +37,7 @@ import { InternalError } from "../errors/index.js";
 // batchHandler collapses a turn's events to one search-op per
 // (tenantId, entityType, entityId) and issues one indexBatch/removeBatch
 // call per tenant instead of one round-trip per event; handler stays the
-// per-event fallback the dispatcher falls back to when a batch throws.
+// per-event fallback the dispatcher uses when a batch throws.
 export const SEARCH_CONSUMER_NAME = "system:consumer:search";
 // An executor update with includeDeleted leaves the row deleted; indexing it would make it findable again.
 function isUpdateOfSoftDeletedRow(event, verb) {
@@ -58,7 +59,7 @@ async function resolveSearchOperation(event, ctx, registry) {
         state = reconstructStateForSearch(event.payload, verb);
     }
     else {
-        // #2765 — named domain event: no fixed payload shape to reconstruct
+        // Named domain event: no fixed payload shape to reconstruct
         // state from. Only worth a projection read when the entity actually
         // declared searchable fields/extensions — same check
         // buildSearchDocument makes below, done here first so a non-
@@ -68,7 +69,7 @@ async function resolveSearchOperation(event, ctx, registry) {
             (registry.getSearchableFields(entityName).length > 0 ||
                 registry.getSearchPayloadExtensions(entityName).length > 0);
         // skip: entity declares no searchable fields/extensions — nothing to
-        // index, stays a no-op with no extra query, same as before #2765.
+        // index, stays a no-op with no extra query, same as before.
         if (!entity || !isSearchable)
             return undefined;
         const row = await readProjectionRowForSearch(ctx, registry, entityName, entity, tenantId, event.aggregateId);
@@ -183,7 +184,7 @@ export function createSearchEventConsumer(searchAdapter, registry) {
         },
     };
 }
-// #2765 — reads the live projection row for a named domain event, tenant-
+// Reads the live projection row for a named domain event, tenant-
 // scoped through createTenantDb the same way MultiStreamProjection appliers
 // scope their apply()-writes (see api/server.ts), on the table the registry
 // actually booted (entityTableFromRegistry) rather than one freshly derived
@@ -217,7 +218,7 @@ async function readProjectionRowForSearch(ctx, registry, entityName, entity, ten
     }
     return state;
 }
-// #1610 — subject-annotated searchable fields are ciphertext in the event
+// Subject-annotated searchable fields are ciphertext in the event
 // payload; decrypt into the derived index only. No KMS → omit ciphertext
 // values rather than indexing blobs.
 export async function decryptSearchableSubjectFields(entityName, state, registry) {
@@ -242,8 +243,8 @@ export async function decryptSearchableSubjectFields(entityName, state, registry
         });
     }
     catch (err) {
-        console.warn(`[kumiko:search] decryptSearchableSubjectFields failed for "${entityName}" — ` +
-            `dropping ciphertext fields for this document instead of wedging the consumer.`, err);
+        log.warn(`decryptSearchableSubjectFields failed for "${entityName}" — ` +
+            `dropping ciphertext fields for this document instead of wedging the consumer.`, { err });
         const out = { ...state };
         for (const name of fields) {
             if (isPiiCiphertext(out[name]))
@@ -295,7 +296,7 @@ function warnOncePerKeyCollision(registry, entityName, key, isBaseField) {
         return;
     warned.add(dedupKey);
     const collidesWith = isBaseField ? `base field "${key}"` : `earlier contributor key "${key}"`;
-    console.warn(`[kumiko:search] searchPayloadExtension on "${entityName}" tried to overwrite ` +
+    log.warn(`searchPayloadExtension on "${entityName}" tried to overwrite ` +
         `${collidesWith} — keeping the first value. Rename the contributor key.`);
 }
 // Build a SearchDocument from raw field-state. Parallel to the old
@@ -307,10 +308,9 @@ export async function buildSearchDocument(entityName, entityId, state, registry)
         return null;
     const searchableFields = registry.getSearchableFields(entityName);
     const extensions = registry.getSearchPayloadExtensions(entityName);
-    // Skip-Guard: kein indexable payload UND keine Extensions → kein doc.
-    // Extensions können auch ohne searchable-Stammfields den index befüllen
-    // (z.B. customFields-only-indexierung), daher muss die check beide
-    // berücksichtigen.
+    // Skip guard: no indexable payload and no extensions means there is no doc.
+    // Extensions can populate the index without searchable base fields
+    // (for example, customFields-only indexing), so both must be checked.
     if (searchableFields.length === 0 && extensions.length === 0)
         return null;
     const embeddedFields = new Set();
@@ -348,15 +348,15 @@ export async function buildSearchDocument(entityName, entityId, state, registry)
             fields[f] = state[f];
         }
     }
-    // F3 — Search-Payload-Extensions: contributors merge flat fields into the
+    // Search-Payload-Extensions: contributors merge flat fields into the
     // search-doc (customFields-bundle / tags / computed-counts / etc.).
     // Sequential await — extensions are expected sync or sub-millisecond async;
     // sequential keeps the path simple and deterministic.
     //
     // Precedence is base-fields-win: a contributor key that collides with a
-    // searchable Stammfield is dropped (not silently merged over the real value)
-    // and warned. A jsonb custom-field that happens to share a Stammfield name
-    // must not shadow the indexed Stammfield.
+    // searchable base field is dropped (not silently merged over the real value)
+    // and warned. A jsonb custom-field that happens to share a base field name
+    // must not shadow the indexed base field.
     const baseFieldKeys = new Set(Object.keys(fields));
     for (const contribute of extensions) {
         const contributed = await contribute({ entityName, entityId, state });
@@ -395,7 +395,7 @@ export const SSE_BROADCAST_CONSUMER_NAME = "system:consumer:sse-broadcast";
 export function createSseBroadcastEventConsumer(sseBroker) {
     return {
         name: SSE_BROADCAST_CONSUMER_NAME,
-        // Shared delivery: one cursor reads every event exactly once (fw#2625).
+        // Shared delivery: one cursor reads every event exactly once.
         // Fanout to every process's own SSE clients happens below, through
         // sseBroker.pushToChannel — a Redis-backed broker (the default once
         // REDIS_URL is set) republishes across replicas, so every pod's
@@ -425,7 +425,7 @@ export function createSseBroadcastEventConsumer(sseBroker) {
 // r.multiStreamProjection's ctx.unsafeAppendEvent, or a raw
 // event-store-executor write (e.g. `files`' fileRef.created) — never
 // reached it, so a job could never trigger on an r.defineEvent-registered
-// event (kumiko-framework#1505).
+// event.
 //
 // This consumer closes that gap the same way search/SSE do: read every
 // committed event off the shared cursor and re-check job triggers. It is
@@ -467,10 +467,9 @@ export function createJobTriggerEventConsumer(jobRunner, registry) {
 }
 // --- Access-Invalidation Consumer (async, via event-dispatcher) ---
 //
-// #1524 (Design), #1558 (channel + stream subscribe), #1559 (session-revoke
-// emits an event). This consumer is the last leg: it watches for the two
-// event types that can make an already-issued JWT stale mid-stream and
-// pushes an invalidation through sseBroker.publishAccessInvalidation, which
+// This consumer is the last leg: it watches for the two event types that
+// can make an already-issued JWT stale mid-stream and pushes an invalidation
+// through sseBroker.publishAccessInvalidation, which
 // dispatch-stream.ts's subscribeAccessInvalidation listener turns into an
 // AccessDeniedError thrown into the open stream.
 //
@@ -499,21 +498,20 @@ export function createJobTriggerEventConsumer(jobRunner, registry) {
 //     payload.previous, the full pre-write entity snapshot written by
 //     createEventStoreExecutor. tenantMembershipEntity declares no
 //     encrypted/PII fields, so previous.userId is plaintext — no KMS
-//     decrypt step (see kumiko-framework#1560 PR discussion; the issue's
-//     original handoff assumed encryption that doesn't apply here).
+//     decrypt step; the original handoff assumed encryption that doesn't
+//     apply here.
 //
 // Over-invalidation (e.g. tenant-membership.updated fired by something
 // other than a role change) is fail-safe: the stream closes, the client
-// reconnects and re-authorizes. No opt-out/allowlist — #1524 chose
-// global-by-default specifically so this can't be silently disabled per
-// handler.
+// reconnects and re-authorizes. No opt-out/allowlist — global-by-default
+// specifically so this can't be silently disabled per handler.
 //
 // Scope note: entityEventName also emits "tenant-membership.forgotten" (DSGVO
 // erasure) and ".restored" — .restored re-grants access so ignoring it is
 // correct, .forgotten is not currently produced by any user-data-rights
 // pipeline for memberships but would be revocation-relevant if it ever is.
-// Out of #1560's stated scope (session-revoke + role/membership change),
-// tracked rather than handled speculatively here.
+// Out of the stated scope (session-revoke + role/membership change), tracked
+// rather than handled speculatively here.
 export const ACCESS_INVALIDATION_CONSUMER_NAME = "system:consumer:access-invalidation";
 const SESSION_REVOKED_EVENT_TYPE = "sessions:event:session-revoked";
 const PAT_REVOKED_EVENT_TYPE = "personal-access-tokens:event:pat-revoked";
@@ -557,7 +555,7 @@ function readPatRevokedScope(payload) {
 export function createAccessInvalidationEventConsumer(sseBroker) {
     return {
         name: ACCESS_INVALIDATION_CONSUMER_NAME,
-        // Shared delivery, same reasoning as SSE broadcast (fw#2625): one
+        // Shared delivery, same reasoning as SSE broadcast: one
         // cursor reads every event once and calls sseBroker.publishAccessInvalidation
         // below, which a Redis-backed broker republishes to every replica's
         // subscribeAccessInvalidation listeners — no per-instance cursor needed

package/dist/pipeline/system-identity-switch.js

@@ -1,5 +1,5 @@
 import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
-import { withSystemDbUnsafeRawGrant, withUnsafeRawGrant, } from "../db/tenant-db.js";
+import { withSystemDbUnsafeRawGrant, withUnsafeRawGrant } from "../db/tenant-db.js";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { AccessDeniedError, FrameworkReasons, InternalError } from "../errors/index.js";
 export function isSystemIdentity(user) {
@@ -235,12 +235,10 @@ export function withHookEscapeHatchGrant(context, callerLabel, escapeHatch) {
         }),
         ...gatedMemberReaderField(callerLabel, identityHatch, ctxQueryAsMember),
         ...gatedProjectionReaderField(callerLabel, identityHatch, ctxQueryProjection),
-        // @cast-boundary engine-bridge — withUnsafeRawGrant passes non-TenantDb values (e.g. a guard Proxy) through unchanged.
         ...(ctxDb && { db: withUnsafeRawGrant(ctxDb, rawHatch) }),
         ...(ctxDbOutsideTransaction && {
             dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction, rawHatch),
         }),
-        // @cast-boundary engine-bridge — withSystemDbUnsafeRawGrant passes non-UncheckedSystemDb values through unchanged.
         ...(ctxSystemDb && {
             systemDb: withSystemDbUnsafeRawGrant(ctxSystemDb, rawHatch, callerLabel),
         }),

package/dist/pipeline/tenant-timezone-cache.js

@@ -1,5 +1,5 @@
 // Per-dispatcher in-process cache for the resolved tenant:config:timezone
-// value (fw#2462). dispatch-shared.ts's buildHandlerContext resolves that
+// value. dispatch-shared.ts's buildHandlerContext resolves that
 // key on every dispatch to build ctx.tz — without a cache that's a config
 // SELECT (sometimes two, cascade + fallback) per request, often inside an
 // open write transaction. A tenant-keyed TTL cache removes the steady-state

package/dist/random/generate.d.ts

@@ -1,56 +1,56 @@
 export type AdjNounNameOptions = {
-    /** Trennzeichen zwischen adj/noun (und ggf. suffix). Default "-". */
+    /** Separator between adj/noun (and, if applicable, suffix). Default "-". */
     readonly separator?: string;
-    /** Wenn gesetzt, wird ein random-suffix der Länge .length angehängt
-     *  (no-confusable-Alphabet). Empfohlen 3 Zeichen = 32^3 = 32.768
-     *  zusätzliche Combinations pro Wortpaar. */
+    /** If set, appends a random suffix of length .length
+     *  (no-confusable alphabet). 3 characters are recommended = 32^3 = 32,768
+     *  additional combinations per word pair. */
     readonly suffix?: {
         readonly length: number;
     };
     /** Custom Adjective-Liste — default ADJECTIVES (191 generic). */
     readonly adjectives?: readonly string[];
-    /** Custom Noun-Liste — default NOUNS (173 generic). Apps die Domain-
-     *  spezifische Slugs wollen (z.B. webhook-feature mit eigenen
-     *  -receiver/-listener-Substantiven) reichen ihre eigene Liste. */
+    /** Custom noun list — default NOUNS (173 generic). Apps that want
+     *  domain-specific slugs (e.g. webhook features with their own
+     *  -receiver/-listener nouns) provide their own list. */
     readonly nouns?: readonly string[];
 };
-/** 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 declare function generateAdjNounName(options?: AdjNounNameOptions): string;
-/** 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 declare function generateNoConfusableId(length: number): string;
 export type GenerateUniqueNameOptions = {
-    /** Caller-Predicate. Returns true wenn der Name noch nicht vergeben
-     *  ist (typisch: DB-Query "select where slug=$1" → row count === 0). */
+    /** Caller predicate. Returns true if the name is not yet assigned
+     *  (typically: DB query "select where slug=$1" → row count === 0). */
     readonly isAvailable: (name: string) => Promise<boolean>;
-    /** Max Versuche OHNE Suffix bevor wir auf suffix-mode wechseln.
-     *  Default 3. Bei 33.043 Default-Combos und ~150 existierenden
-     *  Tenants liegt p(Kollision) < 1% — 3 Versuche reichen weit. */
+    /** Maximum attempts WITHOUT a suffix before switching to suffix mode.
+     *  Default 3. With 33,043 default combinations and ~150 existing
+     *  tenants, p(collision) < 1% — 3 attempts are more than sufficient. */
     readonly maxCleanAttempts?: number;
-    /** Suffix-Länge bei Kollision-Mode. Default 3 (= 32.768 Combinations
-     *  pro Wortpaar). */
+    /** Suffix length in collision mode. Default 3 (= 32,768 combinations
+     *  per word pair). */
     readonly suffixLength?: number;
-    /** Hard-Cap an Total-Versuchen bevor wir aufgeben. Default 20.
-     *  Praktisch nie erreicht — wenn doch, ist die Wortliste leer oder
-     *  isAvailable() returnt durchgängig false (DB-Bug). */
+    /** Hard cap on total attempts before giving up. Default 20.
+     *  Rarely reached in practice — if it is, the word list may be empty or
+     *  isAvailable() may return false consistently (DB bug). */
     readonly maxTotalAttempts?: number;
     readonly separator?: string;
     readonly adjectives?: readonly string[];
     readonly nouns?: readonly string[];
 };
-/** 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 declare function generateUniqueName(options: GenerateUniqueNameOptions): Promise<string>;

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) {