@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/files/file-ref-entity.js

@@ -1,22 +1,22 @@
 import { createBigIntField, createEntity, createTextField } from "../engine/index.js";
-// fileRef — das File-Metadata-Entity. Ganz normales ES-Entity: Upload/Delete
-// laufen über den Standard-Executor (file-routes.ts), die Tabelle `file_refs`
-// wird via buildEntityTable aus dieser Definition gebaut.
+// fileRef — the file-metadata entity. A standard ES entity: uploads/deletes
+// run through the standard executor (file-routes.ts), and the `file_refs` table
+// is built from this definition via buildEntityTable.
 //
-// softDelete: true — wie das `user`-Entity + die data-retention-Strategien.
-// Ein Delete markiert `isDeleted=true` (wiederherstellbar, kein "sofort weg");
-// echtes Erasure (Art. 17) läuft über den Forget-Hook + Retention-Cleanup.
+// softDelete: true — as with the `user` entity and the data-retention strategies.
+// A delete sets `isDeleted=true` (recoverable, not "gone immediately"); actual
+// erasure (Art. 17) runs through the Forget hook and retention cleanup.
 //
-// `insertedAt`/`insertedById` sind framework-managed base columns (siehe
-// buildBaseColumns in table-builder.ts) und dürfen NICHT als Entity-Fields
-// dupliziert werden — fieldColumns gewinnen beim Merge, und die Field-Variante
-// ohne `.default(now()).notNull()` macht inserted_at still nullable.
+// `insertedAt`/`insertedById` are framework-managed base columns (see
+// buildBaseColumns in table-builder.ts) and must NOT be duplicated as entity
+// fields — fieldColumns win during the merge, and the field variant without
+// `.default(now()).notNull()` silently makes inserted_at nullable.
 //
-// PII-Annotations:
-//   - fileName → personal: "self" (original filename often carries a personal
-//     reference: "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf"). The other
-//     fields (storageKey, mimeType, entityType, entityId, fieldName) are
-//     technical references or system metadata, not subject content.
+// PII annotations:
+//   - fileName → personal: "self" (the original filename often carries a
+//     personal reference: "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf").
+//     The other fields (storageKey, mimeType, entityType, entityId, fieldName)
+//     are technical references or system metadata, not subject content.
 export { FILE_REF_ENTITY_NAME } from "./types.js";
 export const fileRefEntity = createEntity({
     table: "file_refs",

package/dist/files/file-ref-table.js

@@ -1,12 +1,11 @@
 import { buildEntityTable } from "../db/table-builder.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
-// `file_refs` ist die read-table des `fileRef`-Entity. Aus der Entity-
-// Definition gebaut (kein hand-gepflegtes pgTable mehr), damit die implizite
-// Entity-Projektion (Rebuild) und der Live-Executor-Write spaltengleich auf
-// dieselbe Tabelle schreiben — Single Source, keine Dual-Definition-Drift.
+// `file_refs` is the read table for the `fileRef` entity. It is built from the entity
+// definition rather than a manually maintained `pgTable`, so the implicit entity
+// projection (rebuild) and live executor writes use the same columns and table—one
+// source of truth, with no drift between duplicate definitions.
 //
-// `id` ist UUID und doppelt als Aggregate-Id des fileRef-Event-Streams:
-// jeder Upload appended `fileRef.created`, jeder Delete `fileRef.deleted`
-// (Standard-Entity-Auto-Verben). UUIDs schließen die Enumeration-Attacke
-// auf /files/:id.
+// `id` is a UUID and also serves as the aggregate ID for the `fileRef` event stream:
+// each upload appends `fileRef.created`, and each deletion appends `fileRef.deleted`
+// (standard entity auto-verbs). UUIDs prevent enumeration attacks against /files/:id.
 export const fileRefsTable = buildEntityTable(FILE_REF_ENTITY_NAME, fileRefEntity);

package/dist/files/file-routes.d.ts

@@ -1,9 +1,15 @@
+import type { WriteErrorInfo } from "@cosmicdrift/kumiko-types/write-error-info-types";
 import { Hono } from "hono";
 import type { DbConnection } from "../db/connection.ts";
 import { type Registry, type SessionUser, type TenantId } from "../engine/types/index.ts";
 import type { FileProviderResolver } from "./provider-resolver.ts";
 import type { RecordReadCheck } from "./record-read-check.ts";
 import { type RecordWriteCheck } from "./record-write-check.ts";
+declare const ERROR_STATUSES: readonly [400, 401, 403, 404, 409, 422, 429, 500, 503, 504];
+export declare function deleteFailureResponseFor(error: WriteErrorInfo): {
+    readonly status: (typeof ERROR_STATUSES)[number];
+    readonly code: string;
+};
 export type FileAccessDecision = "allow" | "deny";
 export type FileRef = {
     id: string;
@@ -36,3 +42,4 @@ export type FileRoutesOptions = {
 export declare function resolveMaxUploadBodyBytes(options: Pick<FileRoutesOptions, "registry" | "maxUploadSize">): number;
 export declare function readFilesRouteOptions(registry: Registry): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "unclaimedUploadReaders" | "maxUploadSize">;
 export declare function createFileRoutes(options: FileRoutesOptions): Hono;
+export {};

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";
@@ -11,13 +12,19 @@ import { isFileField, isUuid, } from "../engine/types/index.js";
 import { listActionFormFileFields, mayUseActionForm } from "./action-form-upload.js";
 import { buildContentDispositionHeader } from "./content-disposition.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
-import { createFileContext } from "./file-handle.js";
+import { createFileContext, createTenantFileContext } from "./file-handle.js";
 import { fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
 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";
+import { withUploadLedger } 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
@@ -95,6 +102,10 @@ export function readFilesRouteOptions(registry) {
 }
 export function createFileRoutes(options) {
     const { db } = options;
+    // Plain resolvers (not built via withFileProviderResolver) get the ledger on the route's own root connection.
+    const resolveProvider = options.resolveProvider.uploadLedgerFor
+        ? options.resolveProvider
+        : withUploadLedger(options.resolveProvider, db);
     const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
     const guard = options.accessGuard ??
         createDefaultGuard(privilegedRoles, options.canReadRecord, options.unclaimedUploadReaders ?? []);
@@ -193,19 +204,18 @@ export function createFileRoutes(options) {
             }
         }
         const data = new Uint8Array(await file.arrayBuffer());
-        const storageProvider = await options.resolveProvider(user.tenantId);
-        const uploadLedger = createFileUploadLedger(db, user.tenantId);
+        const files = createTenantFileContext(resolveProvider, user.tenantId);
         const outcome = await storeFileAsFileRef({
             user,
             tenantDb: tenantDbFor(user.tenantId),
             rowInOwnTransaction: true,
             registry: options.registry,
             defaultMaxUploadSize: options.maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
-            writeBytes: async (key, bytes, mimeType) => {
-                await uploadLedger.record(key);
-                await storageProvider.write(key, bytes, mimeType);
+            writeBytes: (key, bytes, mimeType) => files.writeUploadBytes(key, bytes, mimeType),
+            deleteBytes: async (key) => {
+                await files.ref(key).delete();
+                await files.forgetUploadBytes(key);
             },
-            deleteBytes: (key) => storageProvider.delete(key),
         }, {
             fileName: file.name,
             declaredMimeType: file.type,
@@ -281,7 +291,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 +368,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 +420,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/resolve-content-type.js

@@ -46,6 +46,49 @@ const NON_XML_ROOT_ELEMENTS = new Set([
     "article",
     "font",
     "center",
+    "form",
+    "iframe",
+    "input",
+    "button",
+    "nav",
+    "header",
+    "footer",
+    "main",
+    "pre",
+    "code",
+    "b",
+    "i",
+    "strong",
+    "em",
+    "label",
+    "textarea",
+    "select",
+    "fieldset",
+    "legend",
+    "tr",
+    "td",
+    "th",
+    "thead",
+    "tbody",
+    "tfoot",
+    "object",
+    "embed",
+    "video",
+    "audio",
+    "canvas",
+    "math",
+    "picture",
+    "figure",
+    "figcaption",
+    "blockquote",
+    "dl",
+    "dt",
+    "dd",
+    "aside",
+    "details",
+    "summary",
+    "dialog",
+    "noscript",
 ]);
 const ROOT_ELEMENT_PATTERN = /^<(?:[A-Za-z_][\w.-]*:)?([A-Za-z_][\w.-]*)/;
 const EXTENSION_FALLBACK = {

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/upload-ledger.js

@@ -1,6 +1,8 @@
 import { defineUnmanagedTable } from "../db/entity-table-meta.js";
+import { runnerCanBeginTransaction } from "../db/query.js";
 import { createTenantDb } from "../db/tenant-db.js";
 import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { InternalError } from "../errors/index.js";
 const CREATED_AT_INDEX = "store_file_upload_ledger_created_at_idx";
 // One row per upload whose bytes are in storage but whose fileRef row is not committed yet. The
 // commit path deletes it inside the transaction that creates the fileRef; the sweep finds the
@@ -21,6 +23,11 @@ function isTenantDb(db) {
 // handler must not take the row with it, or the bytes it uploaded would be unfindable.
 export function createFileUploadLedger(db, tenantId) {
     const runner = isTenantDb(db) ? tenantDbRunner(db) : db;
+    if (!runnerCanBeginTransaction(runner)) {
+        throw new InternalError({
+            message: "createFileUploadLedger: the connection is already inside a transaction; the ledger row would roll back with it and the uploaded bytes become unfindable",
+        });
+    }
     const ledgerDb = createTenantDb({ db: runner, tenantId });
     return {
         record: async (storageKey) => {

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[];