@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/engine/transfer-adjacency.js

@@ -61,7 +61,7 @@ function parentRefEdgesFrom(entityName, entity, allEntityNames) {
 //
 // A type can legitimately be reached by more than one edge — `note.vehicleId`
 // and `note.campaignId` are distinct, and collapsing them by entity name would
-// leave one edge's rows behind, the silent partial move #3088 exists to end.
+// leave one edge's rows behind, causing a silent partial move.
 export function resolveTransferAdjacency(entities, rootEntityType) {
     const allEntityNames = [...entities.keys()];
     const byParent = new Map();
@@ -96,7 +96,7 @@ export function findOverDeepTransferChain(adjacency, onPath) {
         // skip: a cycle revisits a type already on this path, and schema depth
         // cannot measure how far it actually runs — that depends on the rows, not
         // the declaration. The mover carries this one instead, failing with
-        // `transfer_graph_too_deep` when its rounds run out (#3131).
+        // `transfer_graph_too_deep` when its rounds run out.
         if (onPath.includes(edge.entityName))
             continue;
         const deeper = findOverDeepTransferChain(adjacency, [...onPath, edge.entityName]);

package/dist/engine/validate-projection-allowlist.js

@@ -23,35 +23,16 @@
 // caught by this validator. A future lint-rule will enforce the contract
 // statically; today it lives in this comment + the StepBuilder doc.
 import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { schemaTableName } from "../db/table-introspection.js";
 import { getStep } from "./define-step.js";
 import { buildPipelineSteps } from "./pipeline.js";
+import { walkStepInstances } from "./walk-step-instances.js";
 // Listed step-kinds whose `args.table` must be in the owning feature's
 // r.requires.projection allowlist. Extend as further unsafeProjection.*
 // steps land — don't pre-list hypothetical kinds (CLAUDE.md: don't design
 // for scenarios that can't happen).
 const UNSAFE_PROJECTION_KINDS = new Set(["unsafeProjectionUpsert", "unsafeProjectionDelete"]);
-// Sub-pipeline arg-paths come from `defineStep({ subPaths: [...] })` —
-// each builder declares its own (e.g. branch's onTrue/onFalse, forEach's
-// do). Walking via the registry means nested unsafeProjection-* in NEW
-// sub-step-builders is automatically caught the moment the builder
-// registers itself; no central map to keep in sync. Followup #15.
-function* walkAllSteps(steps) {
-    for (const step of steps) {
-        yield step;
-        const def = getStep(step.kind);
-        const subPaths = def?.subPaths;
-        if (!subPaths || subPaths.length === 0)
-            continue;
-        const args = step.args;
-        for (const path of subPaths) {
-            const subSteps = args[path];
-            if (Array.isArray(subSteps)) {
-                yield* walkAllSteps(subSteps);
-            }
-        }
-    }
-}
 // table()/buildEntityTable spread column handles as enumerable props, so an
 // entity field named `tableName`/`source` would shadow the matching meta key —
 // the canonical meta under KUMIKO_META_SYMBOL is the only collision-safe source.
@@ -95,7 +76,6 @@ export function validateProjectionAllowlist(features) {
     // the first feature's projections (and vice-versa). Detect and surface
     // here so the error names BOTH owners; without this, the silent-set
     // would point any later unsafeProjection-error at the wrong feature.
-    // Followup #8.
     const aggregateTables = new Map();
     for (const f of features) {
         for (const [entityName, entity] of Object.entries(f.entities ?? {})) {
@@ -129,8 +109,8 @@ export function validateProjectionAllowlist(features) {
                     `Closure body must produce the step list without reading event-payload fields ` +
                     `(those belong inside step resolvers).`);
             }
-            for (const step of walkAllSteps(steps)) {
-                // Tier-2 step-discovery (Q9): require explicit opt-in via
+            for (const step of walkStepInstances(steps, `[Feature ${f.name}] writeHandler "${handlerName}"`)) {
+                // Tier-2 step-discovery: require explicit opt-in via
                 // r.requires.step("<kind>") for any tier-2+ step. Tier-1 is implicit.
                 const def = getStep(step.kind);
                 if (def?.tier === 2 && !f.requiredSteps.has(step.kind)) {
@@ -140,12 +120,12 @@ export function validateProjectionAllowlist(features) {
                 }
                 if (!UNSAFE_PROJECTION_KINDS.has(step.kind))
                     continue;
-                const stepArgs = step.args;
-                if (!stepArgs.table) {
+                const stepTable = isPlainObject(step.args) ? step.args["table"] : undefined;
+                if (!stepTable) {
                     throw new Error(`[Feature ${f.name}] writeHandler "${handlerName}" has a ${step.kind} step ` +
                         `without a \`table\` argument.`);
                 }
-                const tableName = resolveTableNameFromStep(stepArgs.table);
+                const tableName = resolveTableNameFromStep(stepTable);
                 const aggregateOwner = aggregateTables.get(tableName);
                 if (aggregateOwner) {
                     throw new Error(`[Feature ${f.name}] writeHandler "${handlerName}" uses ${step.kind} on table "${tableName}", ` +

package/dist/engine/walk-step-instances.d.ts

@@ -0,0 +1,2 @@
+import type { StepInstance } from "./types/step.ts";
+export declare function walkStepInstances(steps: readonly StepInstance[], where: string): Generator<StepInstance, void, void>;

package/dist/engine/walk-step-instances.js

@@ -0,0 +1,38 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { getStep } from "./define-step.js";
+function isStepInstance(value) {
+    return isPlainObject(value) && typeof value["kind"] === "string";
+}
+// Sub-pipeline arg-paths come from `defineStep({ subPaths })`, so nested steps of new
+// sub-step builders are walked without a central map.
+// Fail-closed: an entry the walker cannot read would hide a step from the caller's check
+// (projection allowlist, event-trigger support), so malformed input throws instead of being skipped.
+export function* walkStepInstances(steps, where) {
+    for (const [stepIndex, step] of steps.entries()) {
+        yield step;
+        const subPaths = getStep(step.kind)?.subPaths;
+        if (!subPaths || subPaths.length === 0)
+            continue;
+        const stepWhere = `${where} step[${stepIndex}] "${step.kind}"`;
+        if (!isPlainObject(step.args)) {
+            throw new Error(`${stepWhere} declares sub-paths (${subPaths.join(", ")}) but its args is not an object.`);
+        }
+        for (const path of subPaths) {
+            const subSteps = step.args[path];
+            // skip: optional sub-path not provided (branch.run treats onFalse: null like absent)
+            if (subSteps === undefined || subSteps === null)
+                continue;
+            if (!Array.isArray(subSteps)) {
+                throw new Error(`${stepWhere} sub-path "${path}" must be a list of steps.`);
+            }
+            const checked = [];
+            for (const [entryIndex, entry] of subSteps.entries()) {
+                if (!isStepInstance(entry)) {
+                    throw new Error(`${stepWhere} sub-path "${path}"[${entryIndex}] is not a step (expected an object with a string "kind").`);
+                }
+                checked.push(entry);
+            }
+            yield* walkStepInstances(checked, `${stepWhere} ${path}`);
+        }
+    }
+}

package/dist/engine/where-rule-lint.js

@@ -1,4 +1,4 @@
-// Static lint for `WhereRule` SQL fragments (fw#2639).
+// Static lint for `WhereRule` SQL fragments.
 //
 // A `where`-rule hands the framework raw SQL. If the author writes an
 // unqualified column name inside a correlated subquery, Postgres binds it

package/dist/engine/write-handler-qn-extract.js

@@ -6,7 +6,7 @@ import { toKebab } from "./qualified-name.js";
 export const WRITE_HANDLER_QN_FORMAT_RE = /^[a-zA-Z][a-zA-Z0-9-]*:write:[a-zA-Z][a-zA-Z0-9-]*(:[a-zA-Z][a-zA-Z0-9-]*)*$/;
 // Matches `dispatcher.write("qn", ...)` and `<expr>.write("qn", ...)` —
 // same surface the CI guard scans. Dynamic QNs (variables, templates) are
-// intentionally skipped (known limitation, documented in #403).
+// intentionally skipped (known limitation).
 const DISPATCHER_WRITE_LITERAL_RE = /\.write\s*\(\s*["']([^"']+)["']/g;
 /** Extract string-literal write-handler QNs from TS/TSX source text. */
 export function extractDispatcherWriteQnsFromSource(source) {

package/dist/entrypoint/index.js

@@ -36,7 +36,7 @@
 //
 // 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.
@@ -55,7 +55,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).
@@ -198,7 +198,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.

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