@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/files/file-routes.js

@@ -1,3 +1,4 @@
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { getUser } from "../api/auth-middleware.js";
@@ -18,6 +19,12 @@ import { RecordWriteDecisions } from "./record-write-check.js";
 import { neutralFileNameForMimeType } from "./resolve-content-type.js";
 import { parseMaxSize, resolveServedContentType } from "./types.js";
 import { createFileUploadLedger } from "./upload-ledger.js";
+// Exactly the httpStatus values declared by KumikoError subclasses across packages/*.
+const ERROR_STATUSES = [400, 401, 403, 404, 409, 422, 429, 500, 503, 504];
+export function deleteFailureResponseFor(error) {
+    const status = isOneOf(ERROR_STATUSES, error.httpStatus) ? error.httpStatus : 500;
+    return { status, code: status === 404 ? "not_found" : error.code };
+}
 const DEFAULT_PRIVILEGED_ROLES = ["Admin", "SystemAdmin"];
 // 15 minutes — long enough for a download to start, short enough that a
 // leaked URL (e.g. from a browser history screenshot) isn't a long-lived
@@ -281,7 +288,7 @@ export function createFileRoutes(options) {
     // GET /files/:id/variant/:name — a named derived version of the file.
     // Same tenant + guard gate as the download above; the original stays
     // reachable only through that route. The public, anonymous counterpart is
-    // a separate cut (#1951) and does not go through createFileRoutes.
+    // a separate cut and does not go through createFileRoutes.
     api.get("/files/:id/variant/:name", async (c) => {
         const user = getUser(c);
         const id = c.req.param("id");
@@ -358,9 +365,8 @@ export function createFileRoutes(options) {
             // pattern from the access-deny path above. Everything else (version
             // conflict 409, ownership 403, validation 422, internal 500) gets the
             // real status off the error so callers can distinguish recoverable
-            // from terminal — pauschales 404 hier hat genau das verschleiert.
-            const status = result.error.httpStatus;
-            const code = status === 404 ? "not_found" : result.error.code;
+            // from terminal — a blanket 404 here had obscured exactly that.
+            const { status, code } = deleteFailureResponseFor(result.error);
             return c.json({ error: code }, status);
         }
         return c.json({ ok: true });
@@ -411,7 +417,7 @@ export function createFileRoutes(options) {
         return c.json({ url, expiresAt });
     });
     // Metadata without the bytes. Unlike the byte-serving routes, this returns
-    // fileName as JSON — and fileName is `personal: "self"` (fw#2423), so it must
+    // fileName as JSON — and fileName is `personal: "self"`, so it must
     // go through the entity executor's detail() to decrypt instead of
     // loadFileForTenant's raw, still-encrypted read.
     async function loadReadableFileMeta(id, user) {

package/dist/files/in-memory-provider.js

@@ -12,9 +12,8 @@ export function createInMemoryFileProvider() {
             store.set(key, { data: new Uint8Array(data), mimeType });
         },
         async writeStream(key, source, options) {
-            // In-Memory hat kein "Streaming" im real-physikalischen Sinn —
-            // wir collecten chunks in einen Uint8Array. Test-Tauglich, kein
-            // Production-Pfad.
+            // In-memory storage does not provide real streaming; it collects chunks
+            // into a Uint8Array. Suitable for tests, not a production path.
             const chunks = [];
             let total = 0;
             for await (const chunk of source) {
@@ -36,12 +35,12 @@ export function createInMemoryFileProvider() {
             return new Uint8Array(entry.data);
         },
         readStream(key) {
-            // In-Memory hat technisch keine Chunks, aber das Surface muss
-            // identisch zu echten Streamern (Local/S3) sein damit Test-Code
-            // den Pfad genauso geht. Wir yielden die Bytes als single-chunk.
-            // Map-lookup ist O(1), also kein Verlust durch eager-resolve.
-            // Throw passiert beim ersten chunk-pull — gleicher Lazy-Pattern
-            // wie S3 (request abgesetzt beim ersten Iterator-Step).
+            // In-memory storage has no chunks, but the surface must match real
+            // streamers (Local/S3) so test code exercises the same path. Yield the
+            // bytes as a single chunk.
+            // The O(1) map lookup avoids a cost from eager resolution.
+            // Errors are thrown on the first chunk pull, matching S3's lazy pattern
+            // (the request starts on the first iterator step).
             const entry = store.get(key);
             const captured = entry ? new Uint8Array(entry.data) : null;
             return {

package/dist/files/local-provider.js

@@ -33,16 +33,12 @@ export function createLocalProvider(basePath) {
             await writeFile(filePath, data);
         },
         async writeStream(key, source, _options) {
-            // Atomar via tmp-File + rename: ein Reader der den finalen Pfad
-            // sieht, sieht entweder die alte Version (falls vorhanden) oder
-            // die vollstaendige neue. Niemals einen halb-fertigen Stream.
-            // Falls der Stream mid-write bricht, ist das tmp-Cleanup
-            // best-effort — je nach OS-Race im stream-destroy-Pfad kann
-            // das `.tmp`-File kurz liegen bleiben. Kein Korrektheits-
-            // Problem (kein Reader sucht `*.tmp`-Patterns), nur Operations-
-            // Hygiene; ein periodischer cron-cleanup auf alten `.tmp`-Files
-            // ist die saubere Loesung wenn das in Production realistisch
-            // greift.
+            // Atomic via a temporary file and rename: readers see either the previous version (if any) or
+            // the complete new version, never a partially written stream. If the stream fails during
+            // writing, temporary-file cleanup is best-effort; an OS race in stream destruction can leave
+            // the `.tmp` file briefly. This affects operational hygiene only, because readers never
+            // search `*.tmp` patterns. A periodic cleanup of old `.tmp` files is appropriate if this runs
+            // in production.
             const filePath = resolveContainedPath(key);
             const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
             await mkdir(dirname(filePath), { recursive: true });
@@ -51,8 +47,8 @@ export function createLocalProvider(basePath) {
                 await rename(tmpPath, filePath);
             }
             catch (e) {
-                // Best-effort tmp-Cleanup; wenn das auch failt, hat der
-                // Filesystem ein Problem das nicht in unserem Scope liegt.
+                // Best-effort temporary-file cleanup; if that also fails, the filesystem problem is outside
+                // this component's scope.
                 await unlink(tmpPath).catch(() => { });
                 throw e;
             }
@@ -62,24 +58,21 @@ export function createLocalProvider(basePath) {
             return readFile(filePath);
         },
         readStream(key) {
-            // node:fs createReadStream ist ein AsyncIterable<Buffer>; Buffer
-            // extends Uint8Array. Wir bauen einen kleinen Adapter weil
-            // @types/node das asyncIterator als AsyncIterableIterator<any>
-            // typt — Adapter sichert die Surface auf Uint8Array.
-            // Default-highWaterMark = 64KB Chunks, was fuer ZIP-Stream-Konsum
-            // gut ist. Errors landen im for-await-Loop des Konsumenten
-            // (z.B. ENOENT bei Missing-File faellt erst beim ersten chunk-
-            // pull, nicht beim readStream-Aufruf — gleiches Lazy-Verhalten
-            // wie inmemory + S3).
+            // node:fs createReadStream is an AsyncIterable<Buffer>; Buffer extends Uint8Array. This
+            // adapter preserves a Uint8Array surface because @types/node types the async iterator as
+            // AsyncIterableIterator<any>. The default highWaterMark produces 64KB chunks, which suits ZIP
+            // stream consumption. Errors reach the consumer's for-await loop; for example, a missing file
+            // raises ENOENT on the first chunk pull rather than when readStream is called, matching the
+            // lazy behavior of in-memory and S3 providers.
             const filePath = resolveContainedPath(key);
             const stream = createReadStream(filePath);
             return {
                 async *[Symbol.asyncIterator]() {
                     for await (const chunk of stream) {
-                        // Stream ohne encoding liefert Buffer. Buffer extends Uint8Array,
-                        // aber @types/node typt asyncIterator als string|Buffer. View
-                        // ohne copy auf dasselbe ArrayBuffer; runtime-check schliesst
-                        // den string-Branch aus (Stream wurde nicht mit encoding= gesetzt).
+                        // A stream without an encoding yields Buffer. Buffer extends Uint8Array, but
+                        // @types/node types the async iterator as string|Buffer. Take a zero-copy view
+                        // onto the same ArrayBuffer; the runtime check rules out the string branch
+                        // because the stream was not opened with an encoding.
                         if (typeof chunk === "string") {
                             throw new Error("local-provider readStream: unexpected string chunk (encoding leaked)");
                         }

package/dist/files/provider-resolver.d.ts

@@ -36,13 +36,13 @@ export type FileProviderContext = {
  * file-provider-inmemory, ...) registers an implementation via
  * `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`.
  *
- * **Plugin-Author-Warnung:** `ctx` ist EXPLIZIT ein FileProviderContext, nicht
- * ein voller HandlerContext. Felder ausserhalb der schmalen Surface (z.B.
- * `ctx.tx`, `ctx.actor`, `ctx.signal`) sind im Worker-Pfad NICHT vorhanden.
- * Cast `ctx as unknown as HandlerContext` fliegt zur Runtime im Worker — der
- * Crash kommt erst in production mit dem ersten S3-Tenant. Braucht ein Plugin
- * Felder ausserhalb FileProviderContext: lieber FileProviderContext explizit
- * erweitern (sichtbarer breaking change) als ctx-cast.
+ * **Plugin-Author-Warning:** `ctx` is EXPLICITLY a FileProviderContext, not
+ * a full HandlerContext. Fields outside the narrow surface (e.g.
+ * `ctx.tx`, `ctx.actor`, `ctx.signal`) are NOT available on the worker path.
+ * Casting `ctx as unknown as HandlerContext` fails at runtime on the worker —
+ * the crash only appears in production with the first S3 tenant. If a plugin
+ * needs fields outside FileProviderContext, extend FileProviderContext
+ * explicitly (a visible breaking change) rather than casting `ctx`.
  */
 export type FileProviderPlugin = {
     readonly build: (ctx: FileProviderContext, tenantId: string) => Promise<FileStorageProvider>;

package/dist/files/storage-tracking.js

@@ -1,7 +1,7 @@
 // Tenant storage usage — counts bytes + files per tenant from the event log.
 //
-// Tracking-only for Phase 1: no hard limit, no upload gatekeeping. Apps read
-// the row to decide what to do (show a warning, soft-throttle, bill, …).
+// Tracking-only: no hard limit, no upload gatekeeping. Apps read the row to
+// decide what to do (show a warning, soft-throttle, bill, …).
 // Enforcement is a conscious deferred call — we want production numbers
 // before picking thresholds (see "Storage tracking: counted now, enforced
 // later" in core-files.md).

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

@@ -1,5 +1,5 @@
 export { createDbConnection } from "../db/connection.ts";
-export { createDatabase, databaseExists, dropDatabaseIfExists, truncateTablesRestartIdentity, } from "../db/queries/test-stack.ts";
+export { acquireSessionAdvisoryLock, createDatabase, databaseExists, dropDatabaseIfExists, listDatabaseNamesWithPrefix, renameDatabase, truncateTablesRestartIdentity, } from "../db/queries/test-stack.ts";
 export { type AnyDb, isClosedConnectionError } from "../db/query.ts";
 export { columnNamesOf } from "../db/schema-inspection.ts";
 export { schemaTableName } from "../db/table-introspection.ts";

package/dist/internal/stack-support.js

@@ -1,6 +1,6 @@
 // @runtime dev
 export { createDbConnection } from "../db/connection.js";
-export { createDatabase, databaseExists, dropDatabaseIfExists, truncateTablesRestartIdentity, } from "../db/queries/test-stack.js";
+export { acquireSessionAdvisoryLock, createDatabase, databaseExists, dropDatabaseIfExists, listDatabaseNamesWithPrefix, renameDatabase, truncateTablesRestartIdentity, } from "../db/queries/test-stack.js";
 export { isClosedConnectionError } from "../db/query.js";
 export { columnNamesOf } from "../db/schema-inspection.js";
 export { schemaTableName } from "../db/table-introspection.js";

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

@@ -3,7 +3,7 @@ import type { ConfigAccessor } from "@cosmicdrift/kumiko-types/config";
 import type { TzContext } from "@cosmicdrift/kumiko-types/tz-context";
 import type { JobsOptions, Queue } from "bullmq";
 import type { TenantDb } from "../db/tenant-db.ts";
-import type { AppContext, EscapeHatchReporter, JobContext, JobDefinition, JobRunIn, JobTriggerEvent } from "../engine/types/index.ts";
+import type { AppContext, JobDefinition, JobRunIn, JobTriggerEvent } from "../engine/types/index.ts";
 import type { Logger } from "../logging/types.ts";
 import type { Meter, SerializedTraceContext, Tracer } from "../observability/index.ts";
 import type { JobLogEntry, JobSubjectValue } from "./job-runner-types.ts";
@@ -14,7 +14,6 @@ export declare function serializeJobSubject(subject: Readonly<Record<string, Job
 export declare function jobSubjectKey(jobName: string, payload: Record<string, unknown>, fields: readonly string[] | undefined, declaration: "tenantVisibleFailure" | "tenantVisibleRun"): string | null;
 export declare function resolveJobTz(config: ConfigAccessor | undefined, context: Pick<AppContext, "geoTzProvider" | "clock">): Promise<TzContext>;
 export declare function missingDbProxy(jobName: string): TenantDb;
-export declare function createCrossTenantReads(systemModeDb: TenantDb, reason: string, report: EscapeHatchReporter): NonNullable<JobContext["crossTenantReads"]>;
 export declare function priorAttemptsOf(data: Record<string, unknown>): number;
 export declare function tenantFailureMessageKey(err: unknown, declaration: JobDefinition["tenantVisibleFailure"]): string | null;
 export declare const TRACE_CONTEXT_KEY = "_traceContext";

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;
@@ -103,22 +109,6 @@ export function missingDbProxy(jobName) {
         },
     });
 }
-export function createCrossTenantReads(systemModeDb, reason, report) {
-    return {
-        selectMany(table, where, options) {
-            report("cross-tenant-read", reason);
-            return systemModeDb.selectMany(table, where, options);
-        },
-        fetchOne(table, where) {
-            report("cross-tenant-read", reason);
-            return systemModeDb.fetchOne(table, where);
-        },
-        count(table, where) {
-            report("cross-tenant-read", reason);
-            return systemModeDb.count(table, where);
-        },
-    };
-}
 export function priorAttemptsOf(data) {
     const value = data["_priorAttempts"];
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : 0;
@@ -266,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, "-");