@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/entrypoint/index.d.ts

@@ -10,7 +10,7 @@ import type { Lifecycle } from "../lifecycle/index.ts";
 import type { ObservabilityProvider } from "../observability/index.ts";
 import type { Dispatcher, DispatcherOptions } from "../pipeline/dispatcher.ts";
 import type { EventDedup, EventDispatcher } from "../pipeline/index.ts";
-import type { SystemHooks } from "../pipeline/lifecycle-pipeline.ts";
+import type { LifecycleHooks, SystemHooks } from "../pipeline/lifecycle-pipeline.ts";
 export type BaseEntrypointOptions = {
     readonly registry: Registry;
     readonly context: AppContext;
@@ -21,6 +21,7 @@ export type BaseEntrypointOptions = {
     readonly systemHooks?: SystemHooks;
     readonly eventDedup?: EventDedup;
     readonly lifecycle?: Lifecycle;
+    readonly instanceId?: ServerOptions["instanceId"];
 };
 type JobsBlock = {
     readonly redisUrl: string;
@@ -49,6 +50,7 @@ export type ApiEntrypointOptions = BaseEntrypointOptions & {
         readonly runLocal?: boolean;
     };
     readonly trustedProxyHops?: ServerOptions["trustedProxyHops"];
+    readonly errorDocs?: ServerOptions["errorDocs"];
 };
 export type WorkerEntrypointOptions = BaseEntrypointOptions & JobsBlock & {
     readonly eventDispatcher?: ServerOptions["eventDispatcher"];
@@ -61,6 +63,7 @@ export type ApiEntrypoint = {
     readonly lifecycle: Lifecycle;
     readonly observability: ObservabilityProvider;
     readonly dispatcher: Dispatcher;
+    readonly lifecycleHooks: LifecycleHooks;
     readonly eventDispatcher?: EventDispatcher;
     readonly mode: "api";
     start(): Promise<void>;

package/dist/entrypoint/index.js

@@ -36,11 +36,12 @@
 //
 // SSE fanout across processes (split api/worker deploy, replicas > 1):
 // buildServer's default sseBroker is Redis-backed whenever REDIS_URL is
-// set (fw#2625) — a push on the worker's dispatcher reaches clients
+// set — a push on the worker's dispatcher reaches clients
 // connected to any API instance via Redis Pub/Sub, no per-instance
 // cursor needed. Without REDIS_URL, the in-memory broker still only
 // reaches clients on the same process.
-import { buildServer, withFileProviderResolver } from "../api/server.js";
+import { buildServer } from "../api/server.js";
+import { withFileProviderResolver } from "../api/server-wiring.js";
 import { createJobRunner } from "../jobs/job-runner.js";
 import { createLifecycle } from "../lifecycle/index.js";
 import { createNoopProvider } from "../observability/index.js";
@@ -55,7 +56,7 @@ import { resolveCacheSyncBus } from "../redis/cache-sync-bus.js";
 // so the command-dispatcher fires handleEvent as an afterCommit-hook for
 // event-triggered jobs (dispatcher.ts:997). Without this plumbing,
 // `r.job({ trigger: { on: … } })` silently drops on every write — that
-// was the hidden Welle-2.5 gap.
+// was the hidden gap.
 //
 // Caller-supplied `dispatcherOptions.jobRunner` wins (tests sometimes
 // inject a mock runner directly).
@@ -119,6 +120,8 @@ function buildApiServer(opts, lifecycle, dispatcherOverride, jobRunner, processL
         jwtIssuer: opts.jwtIssuer,
         auth: opts.auth,
         trustedProxyHops: opts.trustedProxyHops,
+        errorDocs: opts.errorDocs,
+        instanceId: opts.instanceId,
         anonymousAccess: opts.anonymousAccess,
         sseBroker: opts.sseBroker,
         rateLimit: opts.rateLimit,
@@ -145,6 +148,7 @@ function buildWorkerServer(opts, lifecycle, jobRunner) {
         jwtSecret: opts.jwtSecret,
         lifecycle,
         processLane: "worker",
+        instanceId: opts.instanceId,
         observability: opts.observability,
         dispatcherOptions,
         systemHooks: opts.systemHooks,
@@ -198,7 +202,7 @@ export function createApiEntrypoint(options) {
     const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
     const observability = resolveObservability(options.observability);
     const { options: busOptions, context } = resolveEntrypointCacheSync(options, lifecycle);
-    // Boot-validation (Welle 2.6.c) — fail loud before traffic arrives:
+    // Boot-validation — fail loud before traffic arrives:
     //   (a) Any jobs declared + no jobs-block → command-dispatcher would
     //       silently drop every event-triggered enqueue. Fix: add jobs:
     //       { redisUrl } so the API holds lane-queue-clients.
@@ -240,6 +244,7 @@ export function createApiEntrypoint(options) {
         lifecycle,
         observability: server.observability,
         dispatcher: server.dispatcher,
+        lifecycleHooks: server.lifecycleHooks,
         ...(server.eventDispatcher && { eventDispatcher: server.eventDispatcher }),
         mode: "api",
         async start() {
@@ -319,6 +324,7 @@ export function createAllInOneEntrypoint(options) {
         jobRunner: workerJobRunner,
         observability: server.observability,
         dispatcher: server.dispatcher,
+        lifecycleHooks: server.lifecycleHooks,
         mode: "all-in-one",
         async start() {
             await eventDispatcher.start();

package/dist/env/index.d.ts

@@ -116,12 +116,13 @@ export type ParseEnvOptions = {
  *  is `undefined` in the result despite its `string` type — it is only set once
  *  the boot-time decrypt (resolvePlatformKeks) has run. */
 export declare function parseEnv<S extends z.ZodObject<z.ZodRawShape>>(schema: S, env: Record<string, string | undefined>, options?: ParseEnvOptions): z.infer<S>;
-/** Dry-Run-Gegenstück zu parseEnv (KUMIKO_DRY_RUN_ENV-Pfad): parst jedes
- *  Feld einzeln und liefert ein ehrliches Partial — vorhandene Werte kommen
- *  typisiert (gecoerct) durch, fehlende/invalide fehlen einfach. Wirft nie:
- *  der Dry-Run soll das Inventory rendern, nicht an required-Feldern
- *  scheitern. Ersetzt das `({} as Shape)`-Muster, bei dem JEDER Zugriff
- *  silent undefined war und das Compile-Level nichts davon wusste. */
+/** Dry-run counterpart to parseEnv (KUMIKO_DRY_RUN_ENV path): parses each
+ *  field individually and returns an honest Partial — present values pass
+ *  through with their types (coerced), while missing or invalid values are
+ *  simply omitted. Never throws: the dry run renders the inventory instead
+ *  of failing on required fields. Replaces the `({} as Shape)` pattern, where
+ *  every access silently returned undefined and the compiler could not detect
+ *  it. */
 export declare function parseEnvDryRun<S extends z.ZodObject<z.ZodRawShape>>(schema: S, env: Record<string, string | undefined>): Partial<z.infer<S>>;
 export type EnvFieldStatus = "set" | "unset" | "missing" | "invalid";
 export type EnvFieldInspection = {

package/dist/env/index.js

@@ -209,7 +209,7 @@ export function composeEnvSchema(options) {
     // rather than silently overwriting a deploy-critical default. The
     // conflict-detection makes the order safe in both directions — both
     // throw — but downstream tools that consume `sources` (e.g. the
-    // upcoming Phase-5 lint-guard) may rely on this insertion order.
+    // upcoming lint-guard) may rely on this insertion order.
     if (options.core) {
         for (const [key, field] of Object.entries(zodShape(options.core))) {
             merged[key] = field;
@@ -356,12 +356,13 @@ export function parseEnv(schema, env, options = {}) {
 function ucfirst(s) {
     return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
 }
-/** Dry-Run-Gegenstück zu parseEnv (KUMIKO_DRY_RUN_ENV-Pfad): parst jedes
- *  Feld einzeln und liefert ein ehrliches Partial — vorhandene Werte kommen
- *  typisiert (gecoerct) durch, fehlende/invalide fehlen einfach. Wirft nie:
- *  der Dry-Run soll das Inventory rendern, nicht an required-Feldern
- *  scheitern. Ersetzt das `({} as Shape)`-Muster, bei dem JEDER Zugriff
- *  silent undefined war und das Compile-Level nichts davon wusste. */
+/** Dry-run counterpart to parseEnv (KUMIKO_DRY_RUN_ENV path): parses each
+ *  field individually and returns an honest Partial — present values pass
+ *  through with their types (coerced), while missing or invalid values are
+ *  simply omitted. Never throws: the dry run renders the inventory instead
+ *  of failing on required fields. Replaces the `({} as Shape)` pattern, where
+ *  every access silently returned undefined and the compiler could not detect
+ *  it. */
 export function parseEnvDryRun(schema, env) {
     const out = {};
     for (const [name, field] of Object.entries(zodShape(schema))) {
@@ -372,8 +373,8 @@ export function parseEnvDryRun(schema, env) {
         if (result.success)
             out[name] = result.data;
     }
-    // @cast-boundary schema-walk — Partial<z.infer<S>> erasure über den
-    // per-Feld-safeParse; jeder enthaltene Wert hat seinen Feld-Parse bestanden.
+    // @cast-boundary schema-walk — Partial<z.infer<S>> erasure through the
+    // per-field safeParse; every included value passed its field-level parse.
     return out;
 }
 /** Checks every field of `schema` on its own against `env`, for the boot dry

package/dist/errors/docs-url.d.ts

@@ -1,5 +1,5 @@
 import type { KumikoError } from "./kumiko-error.ts";
-/** Links an app's own error reasons to its own docs; without it only framework reasons carry a docsUrl. */
+/** Links an app's own error reasons to its own docs; uncovered reasons fall back to the framework page of the error code. */
 export type ErrorDocsConfig = {
     readonly baseUrl: string;
     readonly reasons?: readonly string[] | "all";

package/dist/errors/docs-url.js

@@ -5,6 +5,26 @@ const frameworkReasons = new Set([
     ...Object.values(FrameworkReasons),
     ...Object.values(AgentReasons),
 ]);
+// Codes of the built-in error classes: only these have a framework docs page.
+const frameworkErrorCodes = new Set([
+    "validation_error",
+    "feature_disabled",
+    "access_denied",
+    "unauthenticated",
+    "not_found",
+    "conflict",
+    "version_conflict",
+    "precondition_failed",
+    "record_locked",
+    "idempotent_replay",
+    "unique_violation",
+    "unprocessable",
+    "unconfigured",
+    "internal_error",
+    "member_read_timeout",
+    "rate_limited",
+    "rate_limit_unavailable",
+]);
 function reasonOf(err) {
     if (!err.details || typeof err.details !== "object")
         return undefined;
@@ -22,7 +42,7 @@ function errorsUrl(baseUrl, slug) {
 }
 // A reason the framework documents (or no reason, or the code itself) links to the framework docs, overridable via
 // KUMIKO_DOCS_URL. An app's own reason links to the app docs where `errorDocs` covers it; every
-// other reason falls back to the framework page of the error code, which exists for each code.
+// other reason falls back to the framework page of the error code, unless an app subclass overrode the code.
 export function resolveErrorDocsUrl(err, errorDocs) {
     const reason = reasonOf(err);
     const frameworkBaseUrl = process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
@@ -32,5 +52,5 @@ export function resolveErrorDocsUrl(err, errorDocs) {
     if (errorDocs && isCoveredByConfig(reason, errorDocs)) {
         return errorsUrl(errorDocs.baseUrl, reason);
     }
-    return errorsUrl(frameworkBaseUrl, err.code);
+    return frameworkErrorCodes.has(err.code) ? errorsUrl(frameworkBaseUrl, err.code) : undefined;
 }

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,49 +1,49 @@
-// 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)";
-                throw new Error(`[es-ops/seed-migration] systemWriteAs("${handlerQualifiedName}") failed: ${code} — ${message}`);
+                throw new Error(`systemWriteAs("${handlerQualifiedName}") failed: ${code} — ${message}`);
             }
             return result;
         },

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 = {