@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/files/zip-stream.d.ts

@@ -1,31 +1,24 @@
 import { getTemporal } from "../time/index.ts";
 export interface ZipEntry {
-    /** Pfad im ZIP, slash-separated. ASCII (kein UTF-8-Flag gesetzt). */
+    /** Path inside the ZIP, slash-separated and UTF-8 encoded (general-purpose flag bit 11). */
     readonly path: string;
-    /** Body als AsyncIterable — kann lazy generated sein (kein Upfront-Memory). */
+    /** Body as an AsyncIterable; it may be generated lazily to avoid upfront memory use. */
     readonly data: AsyncIterable<Uint8Array>;
     /**
-     * Optional Modification-Time. Default = Now. ZIP nutzt MS-DOS-Format
-     * (2-Sek-Aufloesung). Wer Audit-Trail-Zeitpunkte haben will, setzt
-     * den Generation-Timestamp ueber alle Entries.
+     * Optional modification time. Defaults to the current time and uses the ZIP
+     * MS-DOS format with two-second precision. Set the generation timestamp on
+     * every entry when consistent audit-trail timestamps are required.
      */
     readonly mtime?: InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 }
 /**
- * Erzeugt einen ZIP-Stream als `AsyncIterable<Uint8Array>`. Caller (z.B.
- * `FileStorageProvider.writeStream`) konsumiert chunk-fuer-chunk, kein
- * Entry haengt im Memory bis fertig.
+ * Creates a ZIP stream as `AsyncIterable<Uint8Array>`. The caller, such as
+ * `FileStorageProvider.writeStream`, consumes the output chunk by chunk.
  *
- * Streaming-Lifecycle pro Entry:
- *   1. Local File Header (mit CRC32+size=0 als Placeholder; wir nutzen
- *      KEINE Streaming-Data-Descriptor weil Storage-Provider Random-
- *      Access nicht garantiert — wir collecten den Body in Memory pro
- *      Entry um CRC + size **vor** dem Header zu kennen.
- *      Trade-off: 1 Entry-Body im Memory at-a-time; bei <100 MB Files
- *      OK, bei >1 GB single-Files braeuchte ZIP64+Streaming-Descriptor).
- *   2. File Body (raw bytes)
- * Am Ende:
- *   3. Central Directory (eine Liste-Entry pro File mit CRC + size)
- *   4. EOCD (End Of Central Directory)
+ * Each entry's body is collected in memory before its local file header is
+ * emitted because non-seekable storage providers cannot use a streaming data
+ * descriptor, and the header must contain the CRC32 and size. This limits
+ * memory use to one entry body at a time; ZIP64 plus streaming descriptors
+ * would be needed for larger single files.
  */
 export declare function createZipStream(entries: AsyncIterable<ZipEntry>): AsyncIterable<Uint8Array>;

package/dist/files/zip-stream.js

@@ -1,27 +1,22 @@
 import { getTemporal } from "../time/index.js";
-// Streaming-ZIP-Builder (S2.U3 Atom 3a) — pure-JS, dependency-frei.
+// Pure-JS streaming ZIP builder without dependencies.
 //
-// **Format-Wahl: STORE (kein DEFLATE).** Compression-frei + minimal —
-// fuer User-Data-Export-Bundles akzeptabel weil:
-//   - Storage-Provider (S3/R2) komprimiert eh on-the-wire (HTTP gzip)
-//   - JSON-Snippets sind klein, File-Binaries sind oft schon komprimiert
-//     (PNG/JPG/PDF/MP4/...)
-//   - DEFLATE braucht zlib + buffering pro Entry, killt das Streaming-
-//     Property
+// **Format: STORE (no DEFLATE).** Avoiding compression keeps the implementation minimal:
+//   - Storage providers (S3/R2) compress data on the wire (HTTP gzip).
+//   - JSON snippets are small, and file binaries are often already compressed
+//     (PNG/JPG/PDF/MP4/...).
+//   - DEFLATE requires zlib and per-entry buffering, which defeats streaming.
 //
-// **Streaming-Property:** Caller gibt `AsyncIterable<ZipEntry>`, jeder
-// Entry hat `data: AsyncIterable<Uint8Array>`. ZIP-Bytes werden
-// chunk-fuer-chunk yieldet — kein Entry haengt im Memory bis er fertig
-// ist. Storage-Provider's writeStream konsumiert direkt durch.
+// **Streaming:** The caller provides `AsyncIterable<ZipEntry>`, and each entry
+// has `data: AsyncIterable<Uint8Array>`. ZIP bytes are yielded chunk by chunk.
+// The storage provider's writeStream consumes them directly.
 //
-// **ZIP-Standard:** APPNOTE.TXT v6.3.10 (April 2022). STORE-Method,
-// kein ZIP64 (max 4 GB pro Entry, max 65535 Entries — fuer User-Daten-
-// Exports ausreichend; ZIP64-Support kommt wenn ein realer User mit
-// >4 GB single-File auftaucht). Kein UTF-8-Flag (filenames sind ASCII
-// in unserem Use-Case: "profile.json", "files/<id>.<ext>").
+// **ZIP standard:** APPNOTE.TXT v6.3.10 (April 2022). STORE method, no ZIP64
+// (maximum 4 GB per entry and 65535 entries). ZIP64 support is needed before
+// exporting a single file larger than 4 GB. The UTF-8 flag is enabled because
+// filenames may contain non-ASCII characters.
 //
-// **CRC32:** klassisches IEEE-802.3-Polynom (0xEDB88320). Lookup-Table
-// einmal initialisiert + cached.
+// **CRC32:** Classic IEEE-802.3 polynomial (0xEDB88320), with a cached lookup table.
 const ZIP_VERSION_NEEDED = 20; // 2.0 = STORE
 const ZIP_METHOD_STORE = 0;
 // Local file header signature: 0x04034b50 = "PK\x03\x04"
@@ -31,50 +26,38 @@ const CENTRAL_DIR_HEADER_SIG = 0x02014b50;
 // End of central directory record signature: 0x06054b50 = "PK\x05\x06"
 const EOCD_SIG = 0x06054b50;
 const VERSION_MADE_BY = 0x031e; // 0x03 = UNIX, 0x1e = ZIP 3.0
-// General Purpose Flag Bit 11 (0x0800) = UTF-8 filename + comment encoding.
-// Wird default-on gesetzt: ASCII ist gueltiges UTF-8, also Win-Win.
-// Ohne Flag interpretieren aeltere ZIP-Tools filenames als CP437 — bei
-// Umlauten ("Bügel.pdf") wird das Mojibake.
+// General Purpose Flag Bit 11 (0x0800) enables UTF-8 encoding for filenames and comments.
+// ASCII is valid UTF-8, while omitting the flag makes older ZIP tools interpret
+// filenames as CP437, producing mojibake for non-ASCII characters such as umlauts.
 const GENERAL_PURPOSE_FLAGS = 0x0800;
-// External-Attrs (UNIX-Mode in High-Bytes) fuer regulaere Dateien mit
-// 0644-Permissions: `(S_IFREG | 0644) << 16 = 0o100644 << 16 = 0x81a40000`.
-// S_IFREG = 0o100000 (regular file), 0o644 = rw-r--r--. Ohne diese
-// Bits entpackt Info-ZIP mit Mode 0000 (EACCES beim Read).
+// Store UNIX file permissions in the high bytes of the external attributes.
+// Without `(S_IFREG | 0644) << 16 = 0o100644 << 16 = 0x81a40000`, Info-ZIP
+// extracts regular files with mode 0000, causing EACCES when they are read.
 const UNIX_REGULAR_FILE_0644 = 0o100644 << 16; // 0x81a40000
-// ZIP-Format-Limits ohne ZIP64-Extension. Atom 3a-Scope ist STORE-only;
-// ZIP64 kommt wenn ein realer User-Export diese Caps reisst.
+// STORE without ZIP64 is limited to 4 GB per entry and 65535 entries.
+// ZIP64 support is required before these limits can be exceeded.
 const ZIP_MAX_ENTRY_SIZE = 0xffffffff; // uint32 → 4 GB
 const ZIP_MAX_ENTRIES = 0xffff; // uint16 → 65535
 /**
- * Erzeugt einen ZIP-Stream als `AsyncIterable<Uint8Array>`. Caller (z.B.
- * `FileStorageProvider.writeStream`) konsumiert chunk-fuer-chunk, kein
- * Entry haengt im Memory bis fertig.
+ * Creates a ZIP stream as `AsyncIterable<Uint8Array>`. The caller, such as
+ * `FileStorageProvider.writeStream`, consumes the output chunk by chunk.
  *
- * Streaming-Lifecycle pro Entry:
- *   1. Local File Header (mit CRC32+size=0 als Placeholder; wir nutzen
- *      KEINE Streaming-Data-Descriptor weil Storage-Provider Random-
- *      Access nicht garantiert — wir collecten den Body in Memory pro
- *      Entry um CRC + size **vor** dem Header zu kennen.
- *      Trade-off: 1 Entry-Body im Memory at-a-time; bei <100 MB Files
- *      OK, bei >1 GB single-Files braeuchte ZIP64+Streaming-Descriptor).
- *   2. File Body (raw bytes)
- * Am Ende:
- *   3. Central Directory (eine Liste-Entry pro File mit CRC + size)
- *   4. EOCD (End Of Central Directory)
+ * Each entry's body is collected in memory before its local file header is
+ * emitted because non-seekable storage providers cannot use a streaming data
+ * descriptor, and the header must contain the CRC32 and size. This limits
+ * memory use to one entry body at a time; ZIP64 plus streaming descriptors
+ * would be needed for larger single files.
  */
 export async function* createZipStream(entries) {
     const centralDirRecords = [];
-    let offset = 0; // Bytes-Counter fuer central-dir entry's local-header-offset
+    let offset = 0; // Tracks the local-header offset for each central-directory entry
     for await (const entry of entries) {
-        // Body in Memory collecten — wir brauchen CRC32 + size VOR dem
-        // local-file-header (kein streaming-data-descriptor weil
-        // file-storage-providers nicht zwingend seek-able sind, aber wir
-        // wollen vermeiden dass der konsumierende Storage zwei-pass laesst).
+        // Collect the body before writing the local file header: non-seekable storage
+        // providers cannot use a streaming data descriptor, and a two-pass read
+        // would be required otherwise.
         const body = await collectBody(entry.data);
-        // Hard-Limit: STORE-Mode ohne ZIP64-Extension cappt bei uint32 (4 GB).
-        // Bei Ueberschreitung wuerde der Integer-Wrap silent ein korruptes
-        // ZIP produzieren (Decoder lesen Muell-Sizes). Lieber early-fail mit
-        // klarer Begruendung — Worker (Atom 3b) fängt das + setzt Job=failed.
+        // STORE without ZIP64 uses uint32 sizes. Fail early instead of allowing integer
+        // wraparound to produce a corrupt ZIP with incorrect sizes.
         if (body.byteLength > ZIP_MAX_ENTRY_SIZE) {
             throw new Error(`ZIP-Entry "${entry.path}" exceeds 4 GB limit (${body.byteLength} bytes). ` +
                 `STORE-mode without ZIP64-extension caps at uint32. ` +
@@ -105,8 +88,7 @@ export async function* createZipStream(entries) {
         lfh.set(filenameBytes, 30);
         yield lfh;
         yield body;
-        // Central-Directory-Eintrag fuer diesen Entry — wir collecten ihn,
-        // emittieren ihn am Ende.
+        // Keep central-directory entries until all file bodies have been emitted.
         const cdh = new Uint8Array(46 + filenameBytes.byteLength);
         const cdhView = new DataView(cdh.buffer);
         cdhView.setUint32(0, CENTRAL_DIR_HEADER_SIG, true);
@@ -130,7 +112,7 @@ export async function* createZipStream(entries) {
         centralDirRecords.push(cdh);
         offset += lfh.byteLength + body.byteLength;
     }
-    // Central Directory: alle entries hintereinander
+    // Central directory: all entries back to back.
     const centralDirStart = offset;
     let centralDirSize = 0;
     for (const record of centralDirRecords) {
@@ -189,15 +171,14 @@ function crc32(data) {
     }
     return (crc ^ 0xffffffff) >>> 0;
 }
-// MS-DOS Date+Time encoding fuer ZIP-Header.
-// Date: bits 9-15=year-1980, 5-8=month, 0-4=day.
-// Time: bits 11-15=hour, 5-10=minute, 0-4=second/2.
+// MS-DOS date and time encoding for ZIP headers.
+// Date: bits 9-15 = year - 1980, 5-8 = month, 0-4 = day.
+// Time: bits 11-15 = hour, 5-10 = minute, 0-4 = second / 2.
 //
-// **UTC** statt lokaler Zeitzone: in einem DSGVO-Kontext ist der
-// ZIP-mtime Teil des Auskunfts-Artefakts. Verschiedene Server-Zeitzonen
-// wuerden sonst verschiedene mtime-Werte fuer denselben Generation-
-// Instant produzieren — Audit-Drift. UTC ist der Standard fuer alle
-// server-side-Timestamps im Repo (Temporal.Instant ueberall).
+// **UTC** instead of the local time zone: in a GDPR context the ZIP mtime is
+// part of the data-access export. Different server time zones would otherwise produce
+// different values for the same generation instant, causing audit drift. UTC is
+// used for server-side timestamps throughout the repository.
 function toDosTime(i) {
     const dt = i.toZonedDateTimeISO("UTC");
     const year = dt.year;

package/dist/i18n/required-surface-keys.d.ts

@@ -16,7 +16,7 @@ export declare function booleanFacetOptionKeys(featureName: string, entityName:
 export declare function selectFacetOptionKey(featureName: string, entityName: string, fieldName: string, value: string): string;
 export declare function screenTitleKey(screenId: string): string;
 export type RequiredKeysOptions = {
-    /** Bypass `isI18nKey`'s colon-only check for generated dot-form labels (fw#2260). */
+    /** Bypass `isI18nKey`'s colon-only check for generated dot-form labels. */
     readonly treatDotFormAsKey?: boolean;
 };
 export declare function requiredKeysFromScreen(featureName: string, screen: ScreenDefinition, options?: RequiredKeysOptions): readonly string[];

package/dist/i18n/required-surface-keys.js

@@ -35,8 +35,8 @@ function isI18nKey(value) {
 /**
  * `treatAsKey` bypasses the colon-only `isI18nKey` check — used by the Settings-Hub
  * generator's dot-form labels (`${feature}.settings`, mask titles), which are
- * always i18n references by construction, never literal display text (fw#2260).
- * `isI18nKey` itself also accepts dot-form labels explicitly marked via `i18nKey()` (fw#2313).
+ * always i18n references by construction, never literal display text.
+ * `isI18nKey` itself also accepts dot-form labels explicitly marked via `i18nKey()`.
  */
 function pushKey(out, value, treatAsKey = false) {
     if (value !== undefined && (treatAsKey || isI18nKey(value)))
@@ -112,7 +112,7 @@ function pushDashboardScreenKeys(out, dashboard) {
         pushRowActionKeys(out, action);
 }
 function pushDashboardPanelKeys(out, panel) {
-    // skip: custom-Panel übersetzt sich selbst, kein Key hier
+    // skip: custom panels translate themselves, so no key is collected here
     if (panel.kind === "custom")
         return;
     pushKey(out, panel.label);
@@ -251,7 +251,8 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
         }
         case "projectionList": {
             const list = screen;
-            // Keine Entity → keine field-label-Fallbacks; nur explizite Column-Labels.
+            // No entity means there are no field-label fallbacks; only explicit column labels are
+            // collected.
             for (const col of list.columns) {
                 const normalized = normalizeListColumn(col);
                 if (normalized.label !== undefined)
@@ -454,9 +455,8 @@ function collectEntityListFilterKeys(feature, out) {
         const entity = feature.entities?.[screen.entity];
         if (!entity)
             continue;
-        for (const [fieldName, rawDef] of Object.entries(entity.fields)) {
-            const def = rawDef;
-            if (def.filterable !== true)
+        for (const [fieldName, def] of Object.entries(entity.fields)) {
+            if (!("filterable" in def) || def.filterable !== true)
                 continue;
             if (def.type === "boolean") {
                 for (const key of booleanFacetOptionKeys(feature.name, screen.entity, fieldName)) {
@@ -513,7 +513,7 @@ export function buildEffectiveTranslationKeys(features) {
         for (const key of Object.keys(feature.translations ?? {})) {
             out.add(`${feature.name}:${key}`);
             // Blank form too — Settings-Hub group namespaces (`group: "tenant-settings"`)
-            // require `${group}.settings` which is not `${feature}:${key}` (fw#2314).
+            // require `${group}.settings` which is not `${feature}:${key}`.
             out.add(key);
         }
     }

package/dist/jobs/job-runner-helpers.js

@@ -66,6 +66,12 @@ export function serializeJobSubject(subject) {
         .sort()
         .map((field) => [field, subject[field] ?? null]));
 }
+function isJobSubjectValue(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean");
+}
 // Stable identity for the declared payload fields: sorted keys, so two runs
 // with the same subject values produce the same string and the later one
 // replaces the earlier record. Non-primitives would serialize into something
@@ -76,7 +82,7 @@ export function jobSubjectKey(jobName, payload, fields, declaration) {
     const subject = {};
     for (const field of fields) {
         const value = payload[field] ?? null;
-        if (value !== null && typeof value === "object") {
+        if (!isJobSubjectValue(value)) {
             throw new Error(`Job "${jobName}": ${declaration}.subjectFields["${field}"] must be a primitive, got ${typeof value}`);
         }
         subject[field] = value;
@@ -250,7 +256,7 @@ export function payloadMatchesTriggerFilter(where, payload) {
 // on the children still existing in Redis when a wrapper retry re-derives
 // their ids. The margin here is generous — queue wait time isn't bounded by
 // backoff — to cover realistic windows. Audit trail lives in read_job_runs,
-// not BullMQ (fw#3199).
+// not BullMQ.
 export const COMPLETED_JOB_RETENTION_AGE_SEC = 86_400; // 24h
 export const FAILED_JOB_RETENTION_AGE_SEC = 604_800; // 7d
 // Total wall-clock time BullMQ can hold a perTenant wrapper across all its

package/dist/jobs/job-runner-schedulers.d.ts

@@ -7,7 +7,7 @@ export declare const ACTIVE_TENANT_IDS_QUERY_NAME = "tenant:query:active-tenant-
  * BullMQ job ids are `repeat:<schedulerId>:<millis>`. Colons inside the
  * scheduler id push the segment count to ≥5, which BullMQ's legacy heuristic
  * treated as old repeatables — spawning a new scheduler entry every tick and
- * leaking permanent `repeat:*` hashes (taskforcesh/bullmq#3828, fw#1603 /
+ * leaking permanent `repeat:*` hashes (taskforcesh/bullmq#3828,
  * publicstatus Redis OOM). Strip `.` and `:` from the job QN.
  */
 export declare function schedulerIdForJobName(jobName: string): string;

package/dist/jobs/job-runner-schedulers.js

@@ -19,13 +19,13 @@ export const ACTIVE_TENANT_IDS_QUERY_NAME = "tenant:query:active-tenant-ids";
  * BullMQ job ids are `repeat:<schedulerId>:<millis>`. Colons inside the
  * scheduler id push the segment count to ≥5, which BullMQ's legacy heuristic
  * treated as old repeatables — spawning a new scheduler entry every tick and
- * leaking permanent `repeat:*` hashes (taskforcesh/bullmq#3828, fw#1603 /
+ * leaking permanent `repeat:*` hashes (taskforcesh/bullmq#3828,
  * publicstatus Redis OOM). Strip `.` and `:` from the job QN.
  */
 export function schedulerIdForJobName(jobName) {
     return `scheduler-${jobName.replace(/[.:]/g, "-")}`;
 }
-// Same colon-in-BullMQ-id hazard as schedulerIdForJobName (fw#1603/#1604) —
+// Same colon-in-BullMQ-id hazard as schedulerIdForJobName —
 // a QN like "publicstatus:job:uptime-probe" must not leave ":" in the id.
 export function bootJobIdForJobName(jobName) {
     return `boot-${jobName.replace(/[.:]/g, "-")}`;
@@ -97,8 +97,7 @@ export async function removeOrphanJobSchedulers(queue, expectedSchedulerIds, lan
 // duplicates — safe only as long as the child job hash outlives the
 // wrapper's retry window, enforced at construction against
 // COMPLETED_JOB_RETENTION_AGE_SEC (see the invariant check in
-// createJobRunner). Same colon-in-BullMQ-id hazard as schedulerIdForJobName
-// (fw#1603/#1604) — the wrapper id already contains ":", so strip
+// createJobRunner). The wrapper id already contains ":", so strip
 // separators from both halves before joining instead of interpolating raw.
 export function perTenantChildJobId(wrapperJobId, tenantId) {
     const sanitize = (value) => value.replace(/[.:]/g, "-");

package/dist/jobs/job-runner.js

@@ -139,8 +139,7 @@ export function createJobRunner(options) {
         lockRedis = new Redis(redisOpts);
         // Without a listener, a post-close 'error' (e.g. a teardown-race
         // "Connection is closed") is unhandled and crashes the process — in
-        // bun:test it gets attributed to whichever test happens to run next
-        // (fw#1805).
+        // bun:test it gets attributed to whichever test happens to run next.
         lockRedis.on("error", (err) => {
             const log = stopping ? errorLogger.debug : errorLogger.error;
             log("lock redis connection error", { error: err.message });
@@ -181,7 +180,7 @@ export function createJobRunner(options) {
         }),
     };
     // Same unhandled-'error'-crash hazard as lockRedis above, just via
-    // BullMQ's internal ioredis client (fw#1805).
+    // BullMQ's internal ioredis client.
     for (const queue of Object.values(queues)) {
         queue.on("error", (err) => {
             const log = stopping ? errorLogger.debug : errorLogger.error;
@@ -557,7 +556,7 @@ export function createJobRunner(options) {
         // 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
         // app-author job calling ctx.notify(...)/ctx.config(...) hits a TypeError
-        // at runtime the write-handler path never would (framework#1532).
+        // at runtime the write-handler path never would.
         const notify = context._notifyFactory?.(jobSystemUser, tenantId, selfRunner, undefined, context._fileProviderResolver);
         const configDb = context.db; // @cast-boundary db-operator
         // Shared by the config accessor and ctx.derivatives below — both need the
@@ -739,7 +738,7 @@ export function createJobRunner(options) {
                 const handlerResult = await requestContext.run({
                     requestId: jobRequestId,
                     correlationId: jobCorrelationId,
-                    // #3043 — events a job writes carry the job as their origin.
+                    // Events a job writes carry the job as their origin.
                     handler: jobName,
                     feature: registry.getJobFeature(jobName) ?? qnScope(jobName),
                     writeOrigin: jobOrigin,
@@ -794,7 +793,7 @@ export function createJobRunner(options) {
                     "job.id": jobId,
                     "job.attempt": attempt,
                     "kumiko.tenant_id": tenantId,
-                    // Lane-routing attributes (Welle 2.6). `run_in` is the job's
+                    // Lane-routing attributes. `run_in` is the job's
                     // declared lane (explicit or default-"worker"); `consumer_lane`
                     // is which runner actually executed it. They diverge in
                     // all-in-one (both lanes live in one process) but must match
@@ -840,7 +839,7 @@ export function createJobRunner(options) {
     // Boot gates run inline and are awaited, so a throwing gate rejects start()
     // — and with it the entrypoint's start() and runProdApp's boot, before the
     // process reports ready. Enqueuing them (as runOnBoot does) would only fail
-    // a queue job and let the deploy through (fw#2590).
+    // a queue job and let the deploy through.
     async function runBootGates(lane) {
         for (const [name, jobDef] of allJobs) {
             if (laneForJob(jobDef) !== lane)
@@ -978,7 +977,7 @@ export function createJobRunner(options) {
             // still-settling blocking connection: it rejects in-flight commands
             // via ioredis's flushQueue() during close(), which isn't a listenable
             // 'error' event — the only fix is to not return until both of the
-            // worker's connections (main + blocking) are ready (fw#1805). This
+            // worker's connections (main + blocking) are ready. This
             // mirrors the wait BullMQ already does internally for
             // upsertJobScheduler()/add() below when the lane has a cron/boot job.
             // Racing a timeout against it keeps an unreachable Redis from hanging
@@ -1070,7 +1069,7 @@ export function createJobRunner(options) {
             }
             // BullMQ close() while a Queue's connection is still 'initializing'
             // rejects the in-flight INFO with "Connection is closed." on an emitter
-            // without listeners -> unhandled rejection (fw#1805). Wait for readiness
+            // without listeners -> unhandled rejection. Wait for readiness
             // first; a failed/timed-out wait must not block the close itself.
             const stopReadyTimeoutMs = Math.min(bootRedisTimeoutMs, STOP_QUEUE_READY_TIMEOUT_MS);
             await settleAbandonedBootGates(stopReadyTimeoutMs);
@@ -1203,8 +1202,8 @@ export function createJobRunner(options) {
             for (const [name, jobDef] of allJobs) {
                 if (!("on" in jobDef.trigger))
                     continue;
-                // skip: andere Trigger-Formen (cron, manual) reagieren nicht auf
-                // Events. Nur "on"-Trigger werden hier matched.
+                // skip: other trigger types (cron, manual) do not respond to events.
+                // Only "on" triggers are matched here.
                 const triggerOn = jobDef.trigger.on;
                 const matches = Array.isArray(triggerOn)
                     ? triggerOn.includes(eventName)
@@ -1218,10 +1217,9 @@ export function createJobRunner(options) {
                     data["_tenantId"] = user.tenantId;
                     data["_triggeredById"] = user.id;
                 }
-                // Multi-Trigger: payload bekommt _triggerName damit der Handler
-                // weiß, welcher der N Trigger gefeuert hat. Bei Single-Trigger
-                // setzen wir es auch — kostet nichts und vereinfacht Handler-Code
-                // (kein "ist es Multi?"-Branch nötig).
+                // Multi-trigger: add _triggerName to the payload so the handler knows which
+                // of the N triggers fired. Set it for single triggers too; this costs
+                // nothing and keeps handler code simple (no "is it multi?" branch).
                 data["_triggerName"] = eventName;
                 if (triggerEvent)
                     data["_triggerEvent"] = triggerEvent;

package/dist/lifecycle/lifecycle.js

@@ -1,5 +1,6 @@
 // Process lifecycle: 4-state machine + LIFO shutdown hooks.
 // Signal wiring lives in signal-handlers.ts; v1 scope in architecture/lifecycle.md.
+import { createFallbackLogger } from "../logging/utils.js";
 const DEFAULT_DRAIN_TIMEOUT_MS = 40_000;
 export function createLifecycle(opts = {}) {
     const now = opts.now ?? (() => Date.now());
@@ -103,9 +104,6 @@ export function createLifecycle(opts = {}) {
     };
 }
 function makeErrorLogger(logger) {
-    if (logger) {
-        return (msg, err) => logger.error(`[lifecycle] ${msg}`, { err });
-    }
-    // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-    return (msg, err) => console.error(`[lifecycle] ${msg}:`, err);
+    const log = createFallbackLogger("lifecycle", logger);
+    return (msg, err) => log.error(msg, { err });
 }

package/dist/lifecycle/signal-handlers.js

@@ -4,6 +4,9 @@
 export function attachSignalHandlers(lifecycle, opts = {}) {
     const signals = opts.signals ?? ["SIGTERM", "SIGINT"];
     const exitFn = opts.exit ?? ((code) => process.exit(code));
+    // bun-types vs @types/node: signal overload on process.on/off is not
+    // selectable via bind() under the merged types — EventEmitter seam is intentional.
+    const processEmitter = process;
     const listeners = new Map();
     // Guard so double-SIGTERM doesn't call exitFn twice. drain() is already
     // idempotent via its shared promise, but its .then/.catch chain would fire
@@ -24,15 +27,13 @@ export function attachSignalHandlers(lifecycle, opts = {}) {
                 .then(() => exitFn(0))
                 .catch(() => exitFn(1));
         };
-        // bun-types vs @types/node: signal overload on process.on/off is not
-        // selectable via bind() under the merged types — EventEmitter seam is intentional.
-        process.on(sig, handler);
+        processEmitter.on(sig, handler);
         listeners.set(sig, handler);
     }
     return {
         detach: () => {
             for (const [sig, handler] of listeners) {
-                process.off(sig, handler);
+                processEmitter.off(sig, handler);
             }
             listeners.clear();
         },

package/dist/logging/utils.d.ts

@@ -1,9 +1,10 @@
 import type { Logger } from "./types.ts";
 type FallbackLogger = {
+    info(msg: string, data?: Record<string, unknown>): void;
     error(msg: string, data?: Record<string, unknown>): void;
     warn(msg: string, data?: Record<string, unknown>): void;
     debug(msg: string, data?: Record<string, unknown>): void;
 };
 export declare function setProcessLogger(logger: Logger | null): void;
-export declare function createFallbackLogger(namespace: string, logger?: (Pick<Logger, "error"> & Partial<Pick<Logger, "warn" | "debug">>) | undefined): FallbackLogger;
+export declare function createFallbackLogger(namespace: string, logger?: (Pick<Logger, "error"> & Partial<Pick<Logger, "info" | "warn" | "debug" | "child">>) | undefined): FallbackLogger;
 export {};

package/dist/logging/utils.js

@@ -3,9 +3,33 @@ let processLogger = null;
 export function setProcessLogger(logger) {
     processLogger = logger;
 }
+// Bun prints a trailing "undefined" when a second argument is passed explicitly as undefined.
+function writeConsole(write, line, data) {
+    if (data === undefined)
+        write(line);
+    else
+        write(line, data);
+}
 export function createFallbackLogger(namespace, logger) {
+    if (logger?.child) {
+        const child = logger.child({ component: namespace });
+        return {
+            info: (msg, data) => child.info(msg, data),
+            error: (msg, data) => child.error(msg, data),
+            warn: (msg, data) => child.warn(msg, data),
+            debug: (msg, data) => child.debug(msg, data),
+        };
+    }
     if (logger) {
         return {
+            info(msg, data) {
+                if (logger.info) {
+                    logger.info(`[${namespace}] ${msg}`, data);
+                }
+                else {
+                    writeConsole(console.info, `[${namespace}] ${msg}`, data);
+                }
+            },
             error(msg, data) {
                 logger.error(`[${namespace}] ${msg}`, data);
             },
@@ -14,8 +38,7 @@ export function createFallbackLogger(namespace, logger) {
                     logger.warn(`[${namespace}] ${msg}`, data);
                 }
                 else {
-                    // biome-ignore lint/suspicious/noConsole: ops-visible fallback when the wrapped logger has no warn method
-                    console.warn(`[${namespace}] ${msg}`, data);
+                    writeConsole(console.warn, `[${namespace}] ${msg}`, data);
                 }
             },
             debug(msg, data) {
@@ -23,8 +46,7 @@ export function createFallbackLogger(namespace, logger) {
                     logger.debug(`[${namespace}] ${msg}`, data);
                 }
                 else {
-                    // biome-ignore lint/suspicious/noConsole: ops-visible fallback when the wrapped logger has no debug method
-                    console.debug(`[${namespace}] ${msg}`, data);
+                    writeConsole(console.debug, `[${namespace}] ${msg}`, data);
                 }
             },
         };
@@ -41,14 +63,22 @@ export function createFallbackLogger(namespace, logger) {
         return cachedChild;
     };
     return {
+        info(msg, data) {
+            const child = resolveProcessChild();
+            if (child) {
+                child.info(msg, data);
+            }
+            else {
+                writeConsole(console.info, `[${namespace}] ${msg}`, data);
+            }
+        },
         error(msg, data) {
             const child = resolveProcessChild();
             if (child) {
                 child.error(msg, data);
             }
             else {
-                // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-                console.error(`[${namespace}] ${msg}`, data);
+                writeConsole(console.error, `[${namespace}] ${msg}`, data);
             }
         },
         warn(msg, data) {
@@ -57,8 +87,7 @@ export function createFallbackLogger(namespace, logger) {
                 child.warn(msg, data);
             }
             else {
-                // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-                console.warn(`[${namespace}] ${msg}`, data);
+                writeConsole(console.warn, `[${namespace}] ${msg}`, data);
             }
         },
         debug(msg, data) {
@@ -67,8 +96,7 @@ export function createFallbackLogger(namespace, logger) {
                 child.debug(msg, data);
             }
             else {
-                // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
-                console.debug(`[${namespace}] ${msg}`, data);
+                writeConsole(console.debug, `[${namespace}] ${msg}`, data);
             }
         },
     };

package/dist/migrations/index.js

@@ -4,5 +4,5 @@ export { assertKumikoSchemaCurrent, detectKumikoDrift, formatKumikoDriftReport,
 export { createPendingRebuildsTable, enqueueProjectionRebuild, listPendingRebuilds, PROJECTION_REBUILD_JOB, pendingRebuildsTable, queueRebuildsFromMarkers, rebuildProjectionOrMultiStream, reportPendingRebuildRun, runPendingRebuilds, } from "./pending-rebuilds.js";
 // Boot-time backfill: re-encrypts plaintext events after a PII annotation was added.
 export { createPiiBackfillStateTable, piiAnnotationFingerprint, piiBackfillStateTable, runPiiEventBackfill, } from "./pii-event-backfill.js";
-// tableName → projection-name, für den app-seitigen Projection-Rebuild.
+// tableName → projection-name, for application-side projection rebuilds.
 export { buildProjectionTableIndex } from "./projection-table-index.js";