@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/es-ops/runner.js

@@ -1,24 +1,23 @@
-// Runner für pending seed-migrations beim Boot.
+// Runner for pending seed migrations during boot.
 //
 // Flow:
-//   1. List seeds/<*.ts> sorted ascending (filename = chronologische ID)
+//   1. List seeds/<*.ts> sorted ascending (filename = chronological ID)
 //   2. SELECT id FROM kumiko_es_operations WHERE operation_type='seed-migration'
-//   3. pending = files \ applied
-//   4. Für jeden pending in Order:
-//      a. dynamic import → default-export (SeedMigration)
-//      b. wenn migration.skippable && env[KUMIKO_SKIP_ES_OPS_<sanitized>]='1':
-//         → console.log + continue (kein Marker geschrieben)
-//      c. Tx start
+//   3. pending = files \\ applied
+//   4. For each pending migration in order:
+//      a. dynamic import → default export (SeedMigration)
+//      b. if migration.skippable && env[KUMIKO_SKIP_ES_OPS_<sanitized>]='1':
+//         → log line + continue (no marker written)
+//      c. Start transaction
 //      d. await migration.run(ctx)
-//      e. INSERT marker mit duration_ms + appliedBy
-//      f. Tx commit
-//   5. On any failure: Tx rollback + console.error + throw
-//      → App-Boot bricht ab. Operator muss Failure fixen + retry.
+//      e. INSERT marker with duration_ms + appliedBy
+//      f. Commit transaction
+//   5. On any failure: transaction rollback + error log + throw
+//      → App boot aborts. The operator must fix the failure and retry.
 //
-// Skippable-Pattern: seed.skippable=true erlaubt im Notfall ein
-// `KUMIKO_SKIP_ES_OPS_<id>=1` env-flag um eine kaputte Migration zu
-// überspringen ohne ihr Code touchen zu müssen. NICHT als
-// Standard-Workflow — wirklich Notfall.
+// Emergency skip pattern: seed.skippable=true permits a
+// `KUMIKO_SKIP_ES_OPS_<id>=1` env flag to skip a broken migration
+// without touching its code. NOT a standard workflow — emergency use only.
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
         return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
@@ -31,32 +30,30 @@ import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { acquireEsOpsAdvisoryLock, esOperationExists } from "../db/queries/es-ops.js";
 import { insertOne, selectMany } from "../db/query.js";
+import { createFallbackLogger } from "../logging/utils.js";
 import { esOperationsTable } from "./operations-schema.js";
-const DEFAULT_LOGGER = (line) => {
-    // biome-ignore lint/suspicious/noConsole: boot-time-output, kein Logger-Inject hier
-    console.log(line);
-};
-const LOG_PREFIX = "[es-ops/seed-migration]";
+const seedMigrationLog = createFallbackLogger("es-ops/seed-migration");
+const DEFAULT_LOGGER = (line) => seedMigrationLog.info(line);
 export async function runPendingSeedMigrations(args) {
     const log = args.logger ?? DEFAULT_LOGGER;
     const onDisk = await listSeedFiles(args.seedsDir);
     if (onDisk.length === 0) {
-        log(`${LOG_PREFIX} no seed files in ${args.seedsDir} — skipping`);
+        log(`no seed files in ${args.seedsDir} — skipping`);
         return { appliedIds: [], skippedIds: [] };
     }
     const applied = await loadAppliedIds(args.db);
     const pending = onDisk.filter((entry) => !applied.has(entry.id));
     if (pending.length === 0) {
-        log(`${LOG_PREFIX} ${onDisk.length} on disk, all applied — nothing to do`);
+        log(`${onDisk.length} on disk, all applied — nothing to do`);
         return { appliedIds: [], skippedIds: [] };
     }
-    log(`${LOG_PREFIX} ${pending.length}/${onDisk.length} pending`);
+    log(`${pending.length}/${onDisk.length} pending`);
     const appliedIds = [];
     const skippedIds = [];
-    // Dry-Run-Pass (Phase 1.5 / A2): vor JEDER migration alle handler-QNs aus
-    // den seed-files parsen + gegen registry checken. Fail-fast vor erstem
-    // write — gibt klare error-message mit Datei + qn statt zur runtime
-    // "handler not found" mitten im migration-flow.
+    // Dry-run pass: before any migration, parse all handler QNs from the seed
+    // files and check them against the registry. Fail fast before the first
+    // write, with a clear error containing the file and QN instead of a runtime
+    // "handler not found" error in the middle of the migration flow.
     if (args.registry !== undefined) {
         const unknownQns = [];
         for (const entry of pending) {
@@ -71,27 +68,26 @@ export async function runPendingSeedMigrations(args) {
             const lines = unknownQns.map((u) => `  - ${u.id}: "${u.qn}" not registered`);
             throw new Error(`[es-ops/seed-migration] dry-run found ${unknownQns.length} unknown handler-QN(s):\n${lines.join("\n")}\n  Check spelling against your TenantHandlers/AuthHandlers constants (kebab-case after the colon).`);
         }
-        log(`${LOG_PREFIX} dry-run ok — all referenced handler-QNs registered`);
+        log(`dry-run ok — all referenced handler-QNs registered`);
     }
     for (const entry of pending) {
         const migration = await loadSeedModule(entry.filePath);
         const envFlag = `KUMIKO_SKIP_ES_OPS_${sanitizeForEnv(entry.id)}`;
         if (migration.skippable === true && process.env[envFlag] === "1") {
-            log(`${LOG_PREFIX} skip "${entry.id}" — ${envFlag}=1`);
+            log(`skip "${entry.id}" — ${envFlag}=1`);
             skippedIds.push(entry.id);
             continue;
         }
         const start = Date.now();
         try {
             await args.db.begin(async (tx) => {
-                // Advisory-Lock: sequentialisiert Multi-Replica-Boots. Zweiter
-                // Pod blockt bis erster fertig ist, dann re-checked sein
-                // applied-set (außerhalb dieser Funktion in nächster Iteration)
-                // und findet den Marker → skip. Lock wird beim Tx-Commit
-                // automatisch released (xact-scope).
+                // Advisory lock: serializes multi-replica boots. The second pod blocks until
+                // the first finishes, then rechecks its applied set in the next
+                // iteration and finds the marker, so it skips the migration. The lock
+                // is released automatically when the transaction commits (xact scope).
                 await acquireEsOpsAdvisoryLock(tx);
                 if (await esOperationExists(tx, entry.id)) {
-                    log(`${LOG_PREFIX} race-skip "${entry.id}" — applied by parallel boot`);
+                    log(`race-skip "${entry.id}" — applied by parallel boot`);
                     // skip: parallel boot won the advisory-lock and already applied
                     // this migration. Nothing more to do in this tx.
                     return;
@@ -107,13 +103,13 @@ export async function runPendingSeedMigrations(args) {
                 });
             });
             const elapsed = Date.now() - start;
-            log(`${LOG_PREFIX} ✓ ${entry.id} (${elapsed}ms) — ${migration.description}`);
+            log(`✓ ${entry.id} (${elapsed}ms) — ${migration.description}`);
             appliedIds.push(entry.id);
         }
         catch (err) {
             const elapsed = Date.now() - start;
-            log(`${LOG_PREFIX} ✗ ${entry.id} (${elapsed}ms) — ${stringifyError(err)}`);
-            log(`${LOG_PREFIX} ABORT — ${pending.length - appliedIds.length - skippedIds.length - 1} pending migrations were NOT attempted`);
+            log(`✗ ${entry.id} (${elapsed}ms) — ${stringifyError(err)}`);
+            log(`ABORT — ${pending.length - appliedIds.length - skippedIds.length - 1} pending migrations were NOT attempted`);
             throw err;
         }
     }
@@ -125,8 +121,8 @@ async function listSeedFiles(seedsDir) {
         entries = await readdir(seedsDir);
     }
     catch {
-        // Directory doesn't exist → treat as empty. App ohne seeds-Dir ist
-        // ein valider Zustand (no-op).
+        // A missing directory is treated as empty. An app without a seeds directory
+        // is a valid no-op state.
         return [];
     }
     return entries
@@ -135,11 +131,11 @@ async function listSeedFiles(seedsDir) {
         .sort() // filename = chronologische ID (date-prefix-convention)
         .map((name) => ({
         id: name.replace(/\.(ts|mts|js)$/, ""),
-        // resolve, nicht join: Bun's await import() braucht absolute Pfade.
-        // Wenn seedsDir relativ ist (z.B. "./seeds" aus runProdApp-Option),
-        // wäre der join-Pfad auch relativ → Bun's import-resolver such
-        // relativ zum runner.ts-Modul, nicht zu process.cwd() → fail mit
-        // "Cannot find module 'seeds/...' from '<runner-path>'".
+        // Resolve rather than join: Bun's await import() requires absolute paths.
+        // If seedsDir is relative (for example "./seeds" from a runProdApp
+        // option), the joined path would also be relative. Bun's import resolver
+        // would resolve it relative to runner.ts rather than process.cwd(),
+        // causing "Cannot find module 'seeds/...' from '<runner-path>'".
         filePath: path.resolve(seedsDir, name),
     }));
 }
@@ -171,16 +167,16 @@ function isSeedMigration(value) {
 function sanitizeForEnv(id) {
     return id.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
 }
-// Parse seed-file source + extract handler-QNs aus `systemWriteAs(...)`-
-// Calls. Reine regex (kein AST) — fängt die häufigen Inline-String-Cases:
+// Parse seed-file source and extract handler QNs from `systemWriteAs(...)`
+// calls. A regex (rather than an AST) handles common inline string cases:
 //   ctx.systemWriteAs("foo:write:bar", payload)
 //   systemWriteAs("foo:write:bar", ...)  (destructured)
 //
-// Edge-Cases die NICHT geguckt werden:
-//   - QN aus Variable: `const qn = "..."; ctx.systemWriteAs(qn, ...)`
-//   - String-Concat / Template-Literals mit dynamic vars
-// Diese Pattern sind selten in real seed-migrations + bleibt als known-
-// limitation dokumentiert. Wer dynamic-QN braucht, weiß was er tut.
+// Unsupported cases:
+//   - QN from a variable: `const qn = "..."; ctx.systemWriteAs(qn, ...)`
+//   - String concatenation or template literals with dynamic variables
+// These patterns are uncommon in real seed migrations. This limitation is
+// documented so callers requiring dynamic QNs understand the constraint.
 function extractWriteHandlerQns(source) {
     const pattern = /systemWriteAs\s*\(\s*["']([^"']+)["']/g;
     const out = new Set();

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 {};