@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/errors/transition-details.js

@@ -1,11 +1,11 @@
-// Gemeinsame Detail-Shape für invalid_transition-Errors. Beide Pfade
-// (state-machine.assertTransition + failTransition) müssen identisch
-// strukturierte Details liefern, sonst können HTTP-Clients den 422-Body
-// nicht uniform parsen — `from`/`to`/`allowed` sind die strukturierten
-// Felder, `message` ist die menschen-lesbare Form.
+// Shared detail shape for invalid_transition errors. Both paths
+// (`state-machine.assertTransition` and `failTransition`) must provide
+// identically structured details so HTTP clients can parse the 422 body uniformly:
+// `from`/`to`/`allowed` are the structured fields, while `message` is the
+// human-readable form.
 //
-// Kein Re-Export von "validTargets" (CSV-string) mehr — wer CSV will
-// baut's via `allowed.join(", ")`. Eine Shape, ein Vertrag.
+// `validTargets` is not re-exported as a CSV string; callers that need CSV can use
+// `allowed.join(", ")`. One shape defines the contract.
 export function buildInvalidTransitionDetails(from, to, allowed) {
     return {
         from,

package/dist/errors/write-error-info.d.ts

@@ -7,13 +7,13 @@ export declare function failUnprocessable(reason: string, details?: Readonly<Rec
     readonly reason?: never;
 }): WriteFailure;
 /**
- * Convenience für State-Transition-Rejects: produces a WriteFailure mit
- * reason="invalid_transition" + strukturiertem `from`/`to`/`allowed`-
- * Detail-Block + lesbarer message. Pattern hat sich in publicstatus-
- * Maintenance + bestehenden state-machine-Helpers wiederholt — Helper
- * sammelt das in einem Aufruf statt drei manuelle Detail-Felder.
+ * Convenience for state-transition rejects: produces a WriteFailure with
+ * reason="invalid_transition", a structured `from`/`to`/`allowed` detail
+ * block, and a readable message. This pattern recurs in publicstatus
+ * maintenance and existing state-machine helpers, so the helper collects it
+ * in one call instead of requiring three manual detail fields.
  *
- * `allowed` ist typisch `MAINTENANCE_TRANSITIONS.allowedFrom(from)`.
+ * `allowed` is typically `MAINTENANCE_TRANSITIONS.allowedFrom(from)`.
  */
 export declare function failTransition(from: string, to: string, allowed: readonly string[]): WriteFailure;
 export declare function toWriteErrorInfo(err: KumikoError): WriteErrorInfo;

package/dist/errors/write-error-info.js

@@ -24,13 +24,13 @@ export function failUnprocessable(reason, details) {
     return writeFailure(new UnprocessableError(reason, details ? { details } : undefined));
 }
 /**
- * Convenience für State-Transition-Rejects: produces a WriteFailure mit
- * reason="invalid_transition" + strukturiertem `from`/`to`/`allowed`-
- * Detail-Block + lesbarer message. Pattern hat sich in publicstatus-
- * Maintenance + bestehenden state-machine-Helpers wiederholt — Helper
- * sammelt das in einem Aufruf statt drei manuelle Detail-Felder.
+ * Convenience for state-transition rejects: produces a WriteFailure with
+ * reason="invalid_transition", a structured `from`/`to`/`allowed` detail
+ * block, and a readable message. This pattern recurs in publicstatus
+ * maintenance and existing state-machine helpers, so the helper collects it
+ * in one call instead of requiring three manual detail fields.
  *
- * `allowed` ist typisch `MAINTENANCE_TRANSITIONS.allowedFrom(from)`.
+ * `allowed` is typically `MAINTENANCE_TRANSITIONS.allowedFrom(from)`.
  */
 export function failTransition(from, to, allowed) {
     return writeFailure(new UnprocessableError(FrameworkReasons.invalidTransition, {

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

@@ -5,15 +5,15 @@ export type CreateSeedMigrationContextArgs = {
     readonly dispatcher: Dispatcher;
     readonly dbRunner: DbRunner;
 };
-/** Builder: gibt eine factory-function zurück die der Runner pro-Migration
- *  aufruft. Der dbRunner kann eine Top-Connection oder eine Tx sein —
- *  Read-Helpers nutzen ihn direkt, systemWriteAs delegiert an dispatcher.
+/** Builder that returns a factory function called by the runner for each
+ *  migration. dbRunner may be a top-level connection or a transaction—read
+ *  helpers use it directly, while systemWriteAs delegates to the dispatcher.
  *
- *  Hinweis: dispatcher.write bekommt den Runner-tx NICHT durchgereicht —
- *  runBatch öffnet eine eigene Transaktion auf context.db (eigene Pool-
- *  Connection). Die Writes committen daher unabhängig: ein Runner-Failure
- *  rollt NUR den Marker-Insert + dbRunner-reads zurück, die dispatcher-Writes
- *  bleiben committed. Seeds MÜSSEN deshalb idempotent sein (verifiziert in
- *  runner.integration.test.ts „dispatcher-writes vor throw bleiben committed"). */
+ *  dispatcher.write does not receive the runner transaction: runBatch opens
+ *  a separate transaction on context.db (using a separate pool connection).
+ *  Writes therefore commit independently: a runner failure rolls back only
+ *  the marker insert and dbRunner reads; dispatcher writes remain committed.
+ *  Seeds must therefore be idempotent (verified in
+ *  runner.integration.test.ts “dispatcher-writes vor throw bleiben committed”). */
 export declare function createSeedMigrationContext(args: CreateSeedMigrationContextArgs): SeedMigrationContext;
 export type { SeedMigrationContext } from "./types.ts";

package/dist/es-ops/context.js

@@ -1,45 +1,45 @@
-// SeedMigrationContext-Builder. Caller (runProdApp/CLI) übergibt einen
-// schon-konfigurierten Dispatcher; der Builder produziert pro-Migration
-// einen tx-scoped Context der via dispatcher.write den existierenden
-// Handler-Pfad nutzt — gleiches Pattern wie ein User-UI-Click.
+// SeedMigrationContext builder. The caller (runProdApp/CLI) supplies a
+// preconfigured dispatcher; the builder creates a transaction-scoped context
+// for each migration that uses the existing handler path through
+// dispatcher.write—the same pattern as a user UI click.
 //
-// SystemUser bypassed Access-Checks (Standard-Seed-Pattern, siehe
-// config-seed.ts:40). Events haben createdBy = SYSTEM_TENANT_ID-User
-// → audit-fähig.
+// The system user bypasses access checks (the standard seed pattern; see
+// config-seed.ts:40). Events have createdBy = SYSTEM_TENANT_ID user,
+// making them auditable.
 import { configuredPiiSubjectKms, decryptPiiFieldValues } from "../crypto/index.js";
 import { selectAllTenants, selectMembershipsOfUser, selectTemplateResources, selectUserByEmail, } from "../db/queries/seed-context.js";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine/index.js";
 import { parseStringArrayJson } from "../utils/parse-string-array-json.js";
-/** Builder: gibt eine factory-function zurück die der Runner pro-Migration
- *  aufruft. Der dbRunner kann eine Top-Connection oder eine Tx sein —
- *  Read-Helpers nutzen ihn direkt, systemWriteAs delegiert an dispatcher.
+/** Builder that returns a factory function called by the runner for each
+ *  migration. dbRunner may be a top-level connection or a transaction—read
+ *  helpers use it directly, while systemWriteAs delegates to the dispatcher.
  *
- *  Hinweis: dispatcher.write bekommt den Runner-tx NICHT durchgereicht —
- *  runBatch öffnet eine eigene Transaktion auf context.db (eigene Pool-
- *  Connection). Die Writes committen daher unabhängig: ein Runner-Failure
- *  rollt NUR den Marker-Insert + dbRunner-reads zurück, die dispatcher-Writes
- *  bleiben committed. Seeds MÜSSEN deshalb idempotent sein (verifiziert in
- *  runner.integration.test.ts „dispatcher-writes vor throw bleiben committed"). */
+ *  dispatcher.write does not receive the runner transaction: runBatch opens
+ *  a separate transaction on context.db (using a separate pool connection).
+ *  Writes therefore commit independently: a runner failure rolls back only
+ *  the marker insert and dbRunner reads; dispatcher writes remain committed.
+ *  Seeds must therefore be idempotent (verified in
+ *  runner.integration.test.ts “dispatcher-writes vor throw bleiben committed”). */
 export function createSeedMigrationContext(args) {
-    // Default-Executor für System-scope-Aggregates (config-values, system
-    // text-content, etc.). Bei Tenant-scope-Aggregates muss der Caller
-    // explizit `tenantIdOverride` übergeben — siehe types.ts Doku.
+    // Default executor for system-scope aggregates (config-values, system
+    // text-content, etc.). For tenant-scope aggregates, the caller must
+    // explicitly provide `tenantIdOverride`—see the documentation in types.ts.
     const defaultSystemUser = createSystemUser(SYSTEM_TENANT_ID);
     return {
         systemWriteAs: async (handlerQualifiedName, payload, tenantIdOverride, extraRoles) => {
-            // tenantIdOverride: baut einen System-User mit der Stream-tenantId
-            // damit der Event-Store-Executor das Aggregate im richtigen Stream
-            // findet. Verhindert die version_conflict-Falle (siehe Memory
-            // feedback_event_store_tenant_consistency.md).
+            // tenantIdOverride creates a system user with the stream tenant ID so that
+            // the event-store executor finds the aggregate in the correct stream.
+            // This prevents the version_conflict failure.
             const executor = tenantIdOverride !== undefined || (extraRoles && extraRoles.length > 0)
                 ? createSystemUser(tenantIdOverride ?? SYSTEM_TENANT_ID, extraRoles)
                 : defaultSystemUser;
             const result = await args.dispatcher.write(handlerQualifiedName, payload, executor);
-            // Critical: WriteResult{isSuccess: false} würde sonst silent durchlaufen
-            // → Marker landet trotz failed-Write → Migration falsch als "applied"
-            // markiert. Hier throw damit der Runner's outer-tx rollback macht und
-            // Marker NICHT geschrieben wird. Seed-Author kann via try/catch eigene
-            // Fehler-Behandlung machen wenn ein soft-failure erwartet ist.
+            // Without this check, WriteResult{isSuccess: false} would pass silently,
+            // causing the marker to be written despite the failed write and the
+            // migration to be incorrectly marked as "applied". Throw so the
+            // runner's outer transaction rolls back and the marker is not written.
+            // Seed authors can use try/catch for custom handling when a soft failure
+            // is expected.
             if (!result.isSuccess) {
                 const code = result.error?.code ?? "unknown";
                 const message = result.error?.message ?? "(no message)";

package/dist/es-ops/index.js

@@ -1,14 +1,12 @@
-// es-ops — ES-Operations-Pattern für Kumiko-Apps.
+// es-ops — ES operations pattern for Kumiko apps.
 //
-// Phase 1: seed-migrations. Phase 2+ docken an dieselbe Infra an
-// (kumiko_es_operations-Table mit operation_type-Discriminator).
+// Seed migrations use the same infrastructure as later operation types
+// (the `kumiko_es_operations` table with an `operation_type` discriminator).
 //
-// App-Author-API:
-//   - SeedMigration: default-export-Typ einer seed-file
-//   - runProdApp({ seedsDir }): Framework runs pending bei Boot
-//   - bunx kumiko ops seed:new|status|apply (CLI)
-//
-// Plan-Doc: kumiko-platform/docs/plans/features/es-ops.md
+// App author API:
+//   - `SeedMigration`: default export type of a seed file
+//   - `runProdApp({ seedsDir })`: the framework runs pending migrations at boot
+//   - `bunx kumiko ops seed:new|status|apply` (CLI)
 export { createSeedMigrationContext, } from "./context.js";
 export { createEsOperationsTable, esOperationsTable, } from "./operations-schema.js";
 export { runPendingSeedMigrations, } from "./runner.js";

package/dist/es-ops/operations-schema.js

@@ -1,12 +1,6 @@
-// Tracking-Table für ES-Operations (Phase 1: seed-migrations; Phase 2+:
-// projection-rebuild, event-replay, stream-migration, ... — siehe
-// kumiko-platform/docs/plans/features/es-ops.md).
-//
-// File-ID-Tracking analog drizzle-kit: filename ist die ID, applied-set
-// liegt in dieser Tabelle. Pending = files-on-disk MINUS applied-set.
-//
-// operation_type-Discriminator lässt Phase 2+ dieselbe Tabelle nutzen,
-// kein Schema-Sprawl. CLI-Status filtert per type:
+// Tracks ES operations. The filename is the ID, so pending operations are files on disk minus the
+// applied set. The operation_type discriminator lets different operation types share one table
+// without schema sprawl; CLI status commands filter by type:
 //   bunx kumiko ops seed:status      → operation_type = "seed-migration"
 //   bunx kumiko ops projection:status → operation_type = "projection-rebuild"
 import { index, integer, table as pgTable, sql, text, timestamp } from "../db/dialect.js";
@@ -24,7 +18,7 @@ export const esOperationsTable = pgTable("kumiko_es_operations", {
         .default(sql `now()`),
     durationMs: integer("duration_ms").notNull(),
     // Trace: came from boot-time auto-apply, explicit CLI, or CI step.
-    // Helps when forensics ask "wer hat das wann angestoßen".
+    // Supports forensic questions about who initiated the operation and when.
     appliedBy: text("applied_by").notNull().$type(),
     // Optional human-readable annotation — surfaced in `ops <op>:status`.
     notes: text("notes"),

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

@@ -3,23 +3,23 @@ import type { Registry } from "../engine/index.ts";
 import type { EsOperationAppliedBy, SeedMigrationContext } from "./types.ts";
 export type RunPendingSeedMigrationsArgs = {
     readonly db: DbConnection;
-    /** Absoluter Pfad zum seeds-Directory (typically <appRoot>/seeds). */
+    /** Absolute path to the seeds directory (typically <appRoot>/seeds). */
     readonly seedsDir: string;
-    /** Factory die den Context für jede einzelne seed-Migration erzeugt.
-     *  Caller bekommt einen DbRunner (Connection ODER aktive Tx) — Runner
-     *  ruft das pro-migration im tx-Scope auf. */
+    /** Factory that creates the context for each seed migration.
+     * The caller receives a DbRunner (connection OR active transaction); the
+     * runner invokes this once per migration within the transaction scope. */
     readonly createContext: (dbRunner: DbRunner) => SeedMigrationContext;
     /** Trace-marker: boot | cli | ci-pipeline. Landet in applied_by. */
     readonly appliedBy: EsOperationAppliedBy;
-    /** Optional registry für Dry-Run-Validation: parsed jeden seed-file und
-     *  checkt dass alle referenzierten handler-QNs in der Registry existieren
-     *  BEVOR die Migration läuft. Catched camelCase-typos + andere QN-Drift
-     *  zur Boot-Zeit statt mitten im write-cycle (Phase 1.5 / A2).
+    /** Optional registry for dry-run validation: parses each seed file and
+     * checks that all referenced handler QNs exist in the registry
+     * BEFORE the migration runs. This catches camelCase typos and other QN
+     * drift at boot rather than in the middle of a write cycle.
      *
-     *  Wenn weggelassen → kein Dry-Run (backward-compat für tests die ohne
-     *  Registry arbeiten). runProdApp reicht den richtigen Registry rein. */
+     * If omitted, no dry run is performed (backward compatibility for tests
+     * that do not provide a registry). runProdApp supplies the correct one. */
     readonly registry?: Registry;
-    /** Optional log-prefix override, default "[es-ops/seed-migration]". */
+    /** Optional line sink; the default logs under the "es-ops/seed-migration" namespace. */
     readonly logger?: (line: string) => void;
 };
 export type RunPendingSeedMigrationsResult = {

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();