@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/es-ops/types.d.ts

@@ -3,49 +3,50 @@ import type { TenantId, WriteResult } from "../engine/index.ts";
 export type EsOperationAppliedBy = "boot" | "cli" | "ci-pipeline";
 /** Default-Export einer seed-Migration-File. */
 export type SeedMigration = {
-    /** Kurze Beschreibung was die Migration tut. Wird in kumiko_es_operations.notes
-     *  und im `ops seed:status`-Output gezeigt. */
+    /** A short description of what the migration does. Shown in
+     * kumiko_es_operations.notes and in the `ops seed:status` output. */
     readonly description: string;
-    /** Optional: skippe diesen Seed wenn die env-var
-     *  `KUMIKO_SKIP_ES_OPS_<sanitized-filename>=1` gesetzt ist (für Recovery /
-     *  Debug-Boots). Default false = always-run-pending. */
+    /** Optional: skip this seed when the env var
+     * `KUMIKO_SKIP_ES_OPS_<sanitized-filename>=1` is set (for recovery or
+     * debug boots). Default false = always-run-pending. */
     readonly skippable?: boolean;
-    /** Hauptarbeit. ctx liefert systemWriteAs (Event-Store-konformer Pfad,
-     *  bypassed Access-Checks via system-user) plus Read-Helpers.
+    /** Main migration work. ctx provides systemWriteAs (the Event Store-compliant
+     * path, bypassing access checks through the system user) plus read helpers.
      *
-     *  Throws → Marker NICHT geschrieben, App-Boot bricht ab, Retry bei
-     *  nächstem Boot. Pro-Migration eigene Transaction; ein Failure stoppt
-     *  alle nachfolgenden pending-Migrations (Order-Erhalt). */
+     * If this throws, the marker is NOT written, app boot aborts, and the
+     * migration is retried on the next boot. Each migration has its own
+     * transaction; a failure stops all subsequent pending migrations, preserving
+     * their order. */
     readonly run: (ctx: SeedMigrationContext) => Promise<void>;
 };
-/** Read-shape eines User-Eintrags wie an Seed-Helpers exposed.
- *  Schmaler Subset von AuthUserRow — Seeds brauchen typischerweise nur
- *  diese Felder zur Identifikation. */
+/** Read shape of a user entry exposed to seed helpers.
+ * A narrow subset of AuthUserRow, since seeds typically need only
+ * these fields for identification. */
 export type SeedUserRow = {
     readonly id: string;
     readonly email: string;
     readonly tenantId: string;
 };
-/** Read-shape eines Membership-Eintrags wie an Seed-Helpers exposed.
- *  Unterscheidet zwei tenantIds: die "logische" aus dem Read-Projektion
- *  (`tenantId`) und die "physische" aus dem Aggregate-Stream
- *  (`streamTenantId`). Die beiden weichen voneinander ab wenn das
- *  Aggregate von einem Executor mit anderer tenantId angelegt wurde
- *  (z.B. seedTenantMembership-by=systemAdmin) — typischer
- *  publicstatus-Driver-Use-Case. */
+/** Read shape of a membership entry exposed to seed helpers.
+ * Distinguishes two tenantIds: the logical one from the read projection
+ * (`tenantId`) and the physical one from the aggregate stream
+ * (`streamTenantId`). They differ when the aggregate was created by an
+ * executor with a different tenantId (for example,
+ * seedTenantMembership-by=systemAdmin), which is a typical
+ * publicstatus driver use case. */
 export type SeedMembershipRow = {
     readonly userId: string;
-    /** Payload-tenant aus `read_tenant_memberships.tenant_id`. Geht ins
-     *  write-payload als `tenantId`. */
+    /** Payload tenant from `read_tenant_memberships.tenant_id`; it is used
+     * as `tenantId` in the write payload. */
     readonly tenantId: string;
-    /** Stream-tenant aus `kumiko_events.tenant_id` der v1-Row. MUSS als
-     *  `tenantIdOverride` an `systemWriteAs` durchgereicht werden, sonst
-     *  sucht der Event-Store-Executor den Stream im falschen Tenant und
-     *  liefert `version_conflict`. */
+    /** Stream tenant from `kumiko_events.tenant_id` in the v1 row. MUST be
+     * passed as `tenantIdOverride` to `systemWriteAs`; otherwise the Event
+     * Store executor looks for the stream in the wrong tenant and returns
+     * `version_conflict`. */
     readonly streamTenantId: string;
     readonly roles: readonly string[];
 };
-/** Read-shape eines Tenant-Eintrags wie an Seed-Helpers exposed. */
+/** Read shape of a tenant entry exposed to seed helpers. */
 export type SeedTenantRow = {
     readonly id: string;
     readonly name: string;
@@ -69,34 +70,32 @@ export type SeedTemplateResourceFilter = {
     readonly locale?: string;
 };
 export type SeedMigrationContext = {
-    /** Event-Store-konformer Write via existing write-handler. System-User
-     *  als Executor bypassed Access-Check (Standard-Seed-Pattern). Events
-     *  haben inserted_by_id = SYSTEM_TENANT_ID-User → audit-fähig.
+    /** Event Store-compliant write through the existing write handler. The system
+     * user executes it while bypassing access checks. Events have
+     * inserted_by_id = SYSTEM_TENANT_ID-user, making them auditable.
      *
-     *  Typ-Signatur folgt existing ctx.writeAs (payload als unknown) — Type-
-     *  Safety kommt über handler-spezifische Wrapper im Aufrufer ("ich weiß
-     *  was updateMemberRoles braucht"). Versucht NICHT Generic-Magic.
+     * The type signature follows existing ctx.writeAs (with payload as unknown).
+     * Type safety comes from handler-specific wrappers in the caller; do not
+     * attempt generic magic.
      *
-     *  **tenantIdOverride (Phase 1.5):** wenn das Ziel-Aggregate in einem
-     *  spezifischen Tenant-Stream lebt (nicht SYSTEM_TENANT_ID, was Default
-     *  ist), MUSS der Caller die Stream-tenantId mitgeben — sonst sucht der
-     *  Event-Store-Executor den Aggregate-Stream gegen `SYSTEM_TENANT_ID`
-     *  und liefert `version_conflict` (siehe Memory
-     *  `feedback_event_store_tenant_consistency.md` + Driver-Use-Case
-     *  publicstatus-admin-roles in `project_es_ops_phase1_retro.md`).
+     * **tenantIdOverride:** when the target aggregate lives in a specific
+     * tenant stream (rather than SYSTEM_TENANT_ID, the default), the caller
+     * MUST provide the stream tenantId. Otherwise the Event Store executor
+     * looks for the aggregate stream under `SYSTEM_TENANT_ID` and returns
+     * `version_conflict`.
      *
-     *  Typische Pattern:
-     *    - System-scope-Aggregate (config-values, system text-content) →
-     *      tenantIdOverride weglassen (Default SYSTEM_TENANT_ID).
-     *    - Tenant-scope-Aggregate (memberships, tenant-config, app-data) →
-     *      `tenantIdOverride: m.tenantId` (oder den Stream-Tenant aus
-     *      einem find*-Helper).
+     * Typical patterns:
+     *   - System-scope aggregates (config-values, system text-content): omit
+     *     tenantIdOverride (default SYSTEM_TENANT_ID).
+     *   - Tenant-scope aggregates (memberships, tenant-config, app-data): use
+     *     `tenantIdOverride: m.tenantId` or the stream tenant from a find*
+     *     helper.
      *
-     *  **extraRoles:** hasAccess has no system-bypass — a handler with an
-     *  explicit role gate (e.g. `access: { roles: ["SystemAdmin"] }` or
-     *  `["anonymous"]`) otherwise rejects the bare `system` actor with
-     *  `access_denied`. Pass the required role(s) here — see
-     *  `createSystemUser`'s `extraRoles` doc. */
+     * **extraRoles:** hasAccess has no system bypass. A handler with an
+     * explicit role gate (for example, `access: { roles: ["SystemAdmin"] }` or
+     * `["anonymous"]`) otherwise rejects the bare `system` actor with
+     * `access_denied`. Pass the required role(s) here; see
+     * `createSystemUser`'s `extraRoles` documentation. */
     readonly systemWriteAs: (handlerQualifiedName: string, payload: unknown, tenantIdOverride?: TenantId, extraRoles?: readonly string[]) => Promise<WriteResult>;
     readonly findUserByEmail: (email: string) => Promise<SeedUserRow | null>;
     readonly findMembershipsOfUser: (userId: string) => Promise<readonly SeedMembershipRow[]>;
@@ -104,9 +103,10 @@ export type SeedMigrationContext = {
     /** Template rows ordered by slug, locale. Empty list when the
      *  template-resolver feature (its table) is not present. */
     readonly findTemplateResources: (filter?: SeedTemplateResourceFilter) => Promise<readonly SeedTemplateResourceRow[]>;
-    /** Escape-Hatch — direkter DB-Zugang. Nur für READ-only Lookups die der
-     *  Context nicht standard-mäßig anbietet. WRITES via systemWriteAs!
-     *  Type ist DbRunner (Connection oder aktive Tx) weil der Runner den
-     *  Context pro-Migration im Tx-Scope erzeugt. */
+    /** Escape hatch for direct database access. Use only for READ-only lookups
+     * that the context does not provide by default; WRITES must use
+     * systemWriteAs. The type is DbRunner (a connection or active transaction)
+     * because the runner creates the context within each migration's
+     * transaction scope. */
     readonly db: DbRunner;
 };

package/dist/es-ops/types.js

@@ -1,14 +1,14 @@
-// Public API für seed-migrations. Files in /seeds/<date>-<slug>.ts
-// exportieren ein default-Object dieses Typs. Runner ruft `run(ctx)` in
-// chronologischer Reihenfolge auf, einmal pro App-Boot (track in
-// kumiko_es_operations).
+// Public API for seed migrations. Files in /seeds/<date>-<slug>.ts
+// export a default object of this type. The runner calls `run(ctx)` in
+// chronological order, once per app boot, tracking runs in
+// kumiko_es_operations.
 //
-// API-Stabilität: Phase 1 ist "minimal-viable". Helper am Context
-// (findUserByEmail, etc.) wachsen on-demand — wenn eine real-Migration
-// einen Lookup braucht den der Context nicht anbietet, fügen wir ihn
-// dort hinzu. Das vermeidet "wir-bauen-alle-möglichen-Helper-spekulativ".
+// API stability: the initial API is intentionally minimal. Context helpers
+// (findUserByEmail, etc.) grow on demand: when a real migration needs a
+// lookup the context does not provide, add it there. This avoids speculative
+// helper APIs.
 //
-// ctx.db als Escape-Hatch ist erlaubt für READ-only lookups. WRITES
-// IMMER via ctx.systemWriteAs damit Event-Store-Invariants bleiben
-// (Source-of-Truth + Projection läuft automatisch).
+// ctx.db is permitted as an escape hatch for READ-only lookups. WRITES must
+// always go through ctx.systemWriteAs so Event Store invariants remain intact
+// (source of truth plus automatic projection).
 export {};

package/dist/event-store/admin-api.js

@@ -1,12 +1,11 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-// Event-Store Admin-API — Marten-Bypass für Legacy-Daten-Importe.
-// Spec + Verhalten: docs/plans/features/event-store-admin-api.md
+// Event-store admin API — bypasses Marten for legacy-data imports.
+// Specification and behavior: docs/plans/features/event-store-admin-api.md
 //
-// Guard-Rail: dieses Modul ist NICHT aus event-store/index.ts re-exportiert.
-// Import nur via deep-path `@cosmicdrift/kumiko-framework/event-store/admin-api`. Das
-// Guard-Script `scripts/guard-admin-api.ts` blockt Aufrufe aus App-Code —
-// Allowlist: samples/*/migration/, scripts/migrations/, die Definition
-// selbst, das Guard-Script selbst.
+// Guard rail: this module is NOT re-exported from event-store/index.ts. Import only via the deep
+// path `@cosmicdrift/kumiko-framework/event-store/admin-api`. The guard script
+// `scripts/guard-admin-api.ts` blocks calls from application code. Allowlist: samples/*/migration/,
+// scripts/migrations/, this definition, and the guard script itself.
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
 import { claimXactId, runAtomicEventWrite } from "../db/queries/event-store.js";
 import { eventPredecessorExists, findExistingEventVersion, insertRawEventBatch, insertRawFirstEvent, insertRawSubsequentEvent, } from "../db/queries/event-store-admin.js";

package/dist/event-store/errors.js

@@ -3,7 +3,7 @@
 // errors so the executor layer can map them to the framework's
 // WriteResult error contract (version_conflict).
 //
-// These live here and not in kumiko-types (#1629): `instanceof` needs a
+// These live here and not in kumiko-types: `instanceof` needs a
 // single copy of the class, which forced kumiko-types to be a peerDependency
 // and made every minor changeset resolve to a major bump.
 export class VersionConflictError extends Error {

package/dist/event-store/event-store.js

@@ -35,7 +35,7 @@ import { currentSeedCreatedAt } from "./seed-clock.js";
 // by TCP round-trip instead of pollIntervalMs.
 export const EVENTS_PUBSUB_CHANNEL = "kumiko_events_new";
 export async function append(db, event) {
-    // Event-PII (#799): stored payload AND returned echo carry ciphertext, so
+    // Event-PII: stored payload AND returned echo carry ciphertext, so
     // inline projections and rebuilds materialize identical rows.
     const payload = await encryptEventPayloadPii(event.type, event.payload, {
         tenantId: event.tenantId,
@@ -80,7 +80,7 @@ export async function append(db, event) {
         throw e;
     }
 }
-// #3043 — attribution is derived from the execution scope, never taken from
+// Attribution is derived from the execution scope, never taken from
 // the caller: a passed-in value can lie about who wrote the row, a derived
 // one cannot. Hence overwrite rather than merge. appendRaw/appendRawBatch
 // bypass this deliberately — they replay historical rows verbatim.

package/dist/event-store/rebuild-dead-letter.js

@@ -5,7 +5,7 @@
 // whose (possibly years-old) payload makes its apply throw rolls the whole
 // replay back — the projection stays permanently un-rebuildable until the
 // event is repaired by hand. The upcaster dead-letter only quarantines
-// upcast-TRANSFORM failures, not apply failures (#760).
+// upcast-TRANSFORM failures, not apply failures.
 //
 // Quarantine mode (errorPolicy.skipApplyErrors on RebuildDeps, or
 // MspErrorMode.rebuild.skipApplyErrors on the MSP definition) confines each

package/dist/files/feature.js

@@ -4,17 +4,16 @@ import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 import { DEFAULT_UPLOAD_SWEEP_GRACE_HOURS, MIN_UPLOAD_SWEEP_GRACE_HOURS, sweepOrphanedUploads, } from "./sweep-orphaned-uploads.js";
 import { fileUploadLedgerTable } from "./upload-ledger.js";
 export { fileRefEntity } from "./file-ref-entity.js";
-// files — `fileRef` als ganz normales ES-Entity. Upload/Delete laufen über
-// den Standard-Entity-Executor (file-routes.ts: executor.create/delete →
-// `fileRef.created`/`fileRef.deleted` → applyEntityEvent materialisiert
-// `file_refs`). Soft-Delete/Anonymize/Restore/Retention kommen damit
-// generisch aus dem Entity-Lifecycle + data-retention — keine
-// file-spezifische Lösch-Logik.
+// `fileRef` is a regular ES entity. Uploads and deletes go through the standard
+// entity executor (file-routes.ts: executor.create/delete → `fileRef.created` /
+// `fileRef.deleted` → applyEntityEvent materializes `file_refs`), so soft-delete,
+// anonymization, restore and retention come generically from the entity lifecycle
+// and data-retention, with no file-specific deletion logic.
 //
-// `r.entity` macht die Tabelle für PII-Boot-Validation +
-// userData/tenantData-Extensions sichtbar und registriert die implizite
-// Entity-Projektion (für rebuildProjection). Liegt im Framework neben
-// file-routes + fileRefsTable; bundled-features/files re-exportiert nur.
+// `r.entity` exposes the table to PII boot validation and the userData/tenantData
+// extensions, and registers the implicit entity projection used by
+// rebuildProjection. It lives in the framework next to file-routes and
+// fileRefsTable; bundled-features/files only re-exports it.
 export const FILES_FEATURE = "files";
 function assertValidSweepGraceHours(hours) {
     if (!Number.isInteger(hours) || hours < MIN_UPLOAD_SWEEP_GRACE_HOURS) {

package/dist/files/file-handle.js

@@ -121,12 +121,11 @@ export function deriveKey(key, suffix) {
     const { stem, ext } = splitKeyExtension(key);
     return ext === "" ? `${key}.${suffix}` : `${stem}.${suffix}${ext}`;
 }
-// The prefix that covers a key AND every `derive()`d variant of it —
-// `foo/bar.jpg` → `foo/bar.`, matching `foo/bar.jpg` and `foo/bar.medium.jpg`
-// alike, since derive() only ever inserts a suffix between the stem and the
-// extension. Used by the tenant-handover destroy sweep (kumiko-framework#3035)
-// to reach a moved fileRef's original plus every already-rendered derivative,
-// none of which have their own `file_refs` row.
+// The prefix that covers a key AND every `derive()`d variant of it — `foo/bar.jpg` → `foo/bar.`,
+// matching `foo/bar.jpg` and `foo/bar.medium.jpg` alike, since derive() only ever inserts a suffix
+// between the stem and the extension. Used by the tenant-handover destroy sweep to reach a moved
+// fileRef's original plus every already-rendered derivative, none of which have their own
+// `file_refs` row.
 export function storageKeyStemPrefix(key) {
     const { stem, ext } = splitKeyExtension(key);
     return ext === "" ? `${key}.` : `${stem}.`;

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";
@@ -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).