@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/engine/screen-helpers.js

@@ -1,3 +1,5 @@
+import { createFallbackLogger } from "../logging/utils.js";
+const log = createFallbackLogger("kumiko");
 // Entity name the renderer gives the synthesized entity of an actionForm, secretMint or confirm
 // step. It is not registered, so nothing server-side may treat it as a real entity.
 export const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
@@ -71,7 +73,7 @@ export function isWriteFormEditSection(section) {
 }
 // Union of both sources, unlike the boot-validator's either-or flattening: that
 // one runs after the fields-XOR-groups check, collectors run without it and must
-// not drop a source (fw#2986).
+// not drop a source.
 export function sectionFieldSpecs(section) {
     return [...(section.fields ?? []), ...(section.groups?.flatMap((group) => group.fields) ?? [])];
 }
@@ -90,8 +92,7 @@ export function normalizeListColumn(c) {
         process.env.NODE_ENV !== "production" &&
         col.renderer !== undefined &&
         typeof col.renderer === "function") {
-        // biome-ignore lint/suspicious/noConsole: dev-only warning
-        console.warn(`[kumiko] normalizeListColumn: Feld "${col.field}" hat einen Funktions-Renderer — dieser wird von JSON.stringify verworfen. Bitte auf FormatSpec ({ format: "..." }) migrieren.`);
+        log.warn(`normalizeListColumn: Feld "${col.field}" hat einen Funktions-Renderer — dieser wird von JSON.stringify verworfen. Bitte auf FormatSpec ({ format: "..." }) migrieren.`);
     }
     return col;
 }

package/dist/engine/state-machine.d.ts

@@ -1,14 +1,14 @@
 /**
  * Type-safe transition graph. Wraps the underlying Map so callers don't
  * accidentally fall into the `transitions[from]?.includes(to)` footgun
- * (Object-Index-Access auf einer Map returnt undefined und der ganze
- * Check kollabiert silently). Stattdessen forciert die API explizite
- * Methoden — kein Map-shape mehr extern sichtbar.
+ * (indexing a Map like an object returns undefined and silently breaks the
+ * entire check). The API therefore enforces explicit methods, with no Map
+ * shape exposed externally.
  *
  * - `canTransition(from, to)` → boolean
- * - `allowedFrom(from)` → readonly string[] (leer wenn `from` unbekannt
- *   oder terminaler Zustand)
- * - `assertTransition(from, to)` → wirft UnprocessableError(invalid_transition)
+ * - `allowedFrom(from)` → readonly string[] (empty when `from` is unknown
+ *   or terminal)
+ * - `assertTransition(from, to)` → throws UnprocessableError(invalid_transition)
  */
 export type TransitionGraph<TStates extends string = string> = {
     readonly canTransition: (from: TStates, to: TStates) => boolean;
@@ -17,8 +17,8 @@ export type TransitionGraph<TStates extends string = string> = {
 };
 /**
  * Defines allowed state transitions. Returns a typed graph (see
- * TransitionGraph) — nicht eine Map. Damit ist `transitions[x]`-Zugriff
- * type-error statt silent undefined.
+ * TransitionGraph), not a Map. This makes `transitions[x]` access a
+ * type error instead of silently returning undefined.
  */
 export declare function defineTransitions<const TMap extends Record<string, readonly string[]>>(map: TMap): TransitionGraph<keyof TMap & string>;
 /**
@@ -26,9 +26,9 @@ export declare function defineTransitions<const TMap extends Record<string, read
  * reason="invalid_transition" if not — the 422 status lets the client
  * distinguish a logical rejection from a validation or auth failure.
  *
- * Convenience-Wrapper um `transitions.assertTransition(from, to)` —
- * existiert weil bestehende Aufrufer `guardTransition(graph, ...)`-Form
- * nutzen. Beides ist erlaubt; die Method-Form auf dem Graph ist die
- * idiomatische API für neuen Code.
+ * Convenience wrapper around `transitions.assertTransition(from, to)` —
+ * it exists because existing callers use the `guardTransition(graph, ...)`
+ * form. Both are supported; the graph method is the idiomatic API for new
+ * code.
  */
 export declare function guardTransition<TStates extends string>(transitions: TransitionGraph<TStates>, from: TStates, to: TStates): void;

package/dist/engine/state-machine.js

@@ -1,8 +1,8 @@
 import { buildInvalidTransitionDetails, FrameworkReasons, UnprocessableError, } from "../errors/index.js";
 /**
  * Defines allowed state transitions. Returns a typed graph (see
- * TransitionGraph) — nicht eine Map. Damit ist `transitions[x]`-Zugriff
- * type-error statt silent undefined.
+ * TransitionGraph), not a Map. This makes `transitions[x]` access a
+ * type error instead of silently returning undefined.
  */
 export function defineTransitions(map) {
     const internal = new Map();
@@ -17,7 +17,7 @@ export function defineTransitions(map) {
         },
         assertTransition: (from, to) => {
             const set = internal.get(from);
-            // skip: erlaubter Übergang — kein Throw, fall through.
+            // skip: allowed transition — no throw; fall through.
             if (set?.has(to) === true)
                 return;
             const allowed = set ? [...set] : [];
@@ -33,10 +33,10 @@ export function defineTransitions(map) {
  * reason="invalid_transition" if not — the 422 status lets the client
  * distinguish a logical rejection from a validation or auth failure.
  *
- * Convenience-Wrapper um `transitions.assertTransition(from, to)` —
- * existiert weil bestehende Aufrufer `guardTransition(graph, ...)`-Form
- * nutzen. Beides ist erlaubt; die Method-Form auf dem Graph ist die
- * idiomatische API für neuen Code.
+ * Convenience wrapper around `transitions.assertTransition(from, to)` —
+ * it exists because existing callers use the `guardTransition(graph, ...)`
+ * form. Both are supported; the graph method is the idiomatic API for new
+ * code.
  */
 // @wrapper-known semantic-alias
 export function guardTransition(transitions, from, to) {

package/dist/engine/steps/_resolver-utils.js

@@ -13,14 +13,15 @@
 // was needed to satisfy TS narrowing on a property-access; passing the
 // arg through a function-call achieves the same narrowing trivially via
 // the function-parameter binding.
-//
-// Followup #10 (closed at the M.1.6 cleanup-pass).
+function isResolverFunction(arg) {
+    return typeof arg === "function";
+}
 /**
  * Resolve a required StepResolver — either a static value or a function.
  * Throws if `arg` is undefined; caller must guarantee presence.
  */
 export function resolveRequired(arg, ctx) {
-    if (typeof arg === "function") {
+    if (isResolverFunction(arg)) {
         return arg(ctx);
     }
     return arg;

package/dist/engine/steps/for-each.js

@@ -24,12 +24,12 @@
 // ```
 //
 // M.1.6 supports `concurrency: 1` only (sequential). Concurrent
-// execution (Promise.all-style) is Followup #12 — TX-sharing,
+// execution (Promise.all-style) requires its own audit cycle: TX-sharing,
 // AbortSignal-cancellation, and lifecycle-hook ordering each warrant
-// their own audit cycle (Q16).
+// separate review.
 //
-// Q15: `as` is required — without it, the current item is unreachable
-// from the sub-pipeline's resolvers. Q12: r.step.return inside `do` is
+// `as` is required — without it, the current item is unreachable
+// from the sub-pipeline's resolvers. `r.step.return` inside `do` is
 // rejected at build time (would trigger the discriminated-union
 // TData-Inference trap).
 import { defineStep } from "../define-step.js";

package/dist/engine/steps/unsafe-projection-delete.js

@@ -6,7 +6,7 @@
 // r.requires.projection allowlist, must NOT be a registered
 // r.entity-aggregate-table. Skips the same set of framework-protections
 // (lifecycle hooks, field-access, audit-trail, etc.) — see
-// step-vocabulary.md "Was unsafeProjection.* überspringt".
+// step-vocabulary.md "What unsafeProjection.* skips".
 //
 // Convention (not enforced): most legitimate read-side deletions are
 // downstream of an aggregate event (e.g. delete-user → cascading

package/dist/engine/steps/unsafe-projection-upsert.js

@@ -2,13 +2,13 @@
 //
 // Idempotent on the supplied conflict-key columns (typically the
 // natural key + tenantId). Skips lifecycle hooks, field-access,
-// crypto-shredding, schema-versioning, audit-trail, read-access-log.
-// See "Was unsafeProjection.* überspringt" in
+// crypto-shredding, schema-versioning, audit-trail, and read-access-log.
+// See "What unsafeProjection.* skips" in
 // kumiko-platform/docs/archive/plans/architecture/intern/step-vocabulary.md.
 //
 // Use only on tables explicitly declared via r.requires.projection in
-// the owning feature. Aggregate-tables (registered via r.entity) are
-// rejected by boot-validation — domain mutation MUST go through
+// the owning feature. Aggregate tables (registered via r.entity) are
+// rejected by boot validation — domain mutation MUST go through
 // r.step.aggregate.*.
 import { extractTableName } from "../../db/index.js";
 import { executeRawQuery } from "../../db/queries/raw-sql.js";

package/dist/engine/steps/wait-for-event.js

@@ -16,10 +16,10 @@
 // resultKey is `args.event` itself (the branded event-type string) rather
 // than a new `name` argument — a workflow only ever has one `awaits` entry
 // per event type, so `ctx.steps[awaits.someKey]` is already a unique,
-// intention-revealing handle. resume-run.write.ts (framework#2513 Phase 3b)
-// is the only producer of this key's value: the step itself always
-// suspends (never returns a real result), so a subsequent step only ever
-// sees the matched event's payload after a resume seeds it in.
+// intention-revealing handle. resume-run.write.ts is the only producer of
+// this key's value: the step itself always suspends (never returns a real
+// result), so a subsequent step only ever sees the matched event's payload
+// after a resume seeds it in.
 import { defineStep } from "../define-step.js";
 import { addDuration } from "./_duration-utils.js";
 import { resolveOptional, resolveRequired } from "./_resolver-utils.js";

package/dist/engine/steps/workflow-system-events.js

@@ -15,7 +15,7 @@ const triggerEventRefSchema = z.object({
     aggregateId: z.string(),
     version: z.number().int(),
 });
-// Optional on every step event: runs started before the Q7 fingerprint existed
+// Optional on every step event: runs started before the fingerprint existed
 // have none.
 const stepContext = {
     workflowName: z.string(),
@@ -29,8 +29,8 @@ const WORKFLOW_SYSTEM_EVENT_SCHEMAS = [
         z.object({
             workflowName: z.string(),
             triggerEventType: z.string(),
-            // Current streams reference the trigger event; streams written before
-            // #3474 carry a copy of its payload instead.
+            // Current streams reference the trigger event; older streams carry a copy of
+            // its payload instead.
             triggerEventRef: triggerEventRefSchema.optional(),
             triggerPayload: z.unknown().optional(),
             definitionFingerprint: z.string().optional(),

package/dist/engine/tier-resolver-extension.d.ts

@@ -4,30 +4,32 @@ import type { RegistrarExtensionRegistration } from "./types/config.ts";
 import type { FeatureDefinition, Registry } from "./types/feature.ts";
 import type { TenantId } from "./types/identifiers.ts";
 /**
- * Extension-name unter dem ein tier-resolver-plugin im registry registriert
- * werden muss. Konstante damit `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
- * + framework's `getExtensionUsages(TENANT_TIER_RESOLVER_EXT)` typo-resistent
- * gegen den selben Wert prüfen.
+ * Extension name under which a tier-resolver plugin must be registered in the
+ * registry. The constant keeps `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
+ * and the framework's `getExtensionUsages(TENANT_TIER_RESOLVER_EXT)` aligned
+ * on the same value, preventing typos.
  */
 export declare const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
 /**
- * Resolver-callback shape: synchron (dispatcher hot-path), per-tenant.
- * Returnt das effective feature-Set für den tenant. Implementations sollten
- * einen in-memory cache pflegen + per `r.entityHook` invalidieren.
+ * Resolver callback shape: synchronous (on the dispatcher's hot path), per
+ * tenant. Returns the tenant's effective feature set. Implementations should
+ * maintain an in-memory cache and invalidate it via `r.entityHook`.
  *
- * **System-context convention:** call mit SYSTEM_TENANT_ID erwartet die union
- * aller tier-features (siehe DispatcherOptions.effectiveFeatures doc-block).
+ * **System-context convention:** calls with SYSTEM_TENANT_ID must return the
+ * union of all tier features (see the DispatcherOptions.effectiveFeatures
+ * doc block).
  */
 export type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<string>) & {
     /**
-     * Optionaler Live-Trial-Gate, vom dispatcher-feature-gate NUR konsultiert
-     * wenn der synchrone Resolver ein Feature als disabled meldet. Liest das
-     * Signup-Datum des Tenants live (tenant.inserted_at) und returnt true wenn
-     * der Tenant im Trial-Fenster ist UND das Feature zum Trial-Tier gehört.
-     * Async + nicht im Boot-Cache, weil der Trial zeit-abgeleitet ist (ändert
-     * sich zwischen Requests). Konsultiert an 3 Stellen: den 2 Dispatch-Gate-
-     * Aufrufstellen (checkFeatureEnabled) UND ctx.hasFeature im Handler-Body
-     * (fällt darauf zurück, wenn der synchrone Feature-Set-Check negativ ist).
+     * Optional live-trial gate, consulted by the dispatcher feature gate ONLY
+     * when the synchronous resolver reports a feature as disabled. Reads the
+     * tenant's signup date live (tenant.inserted_at) and returns true when the
+     * tenant is within the trial window AND the feature belongs to the trial
+     * tier. It is async and not part of the boot cache because the trial is
+     * time-dependent and can change between requests. Consulted at three
+     * locations: the two dispatch-gate call sites (checkFeatureEnabled) AND
+     * ctx.hasFeature in the handler body (as a fallback when the synchronous
+     * feature-set check is negative).
      */
     readonly trialGate?: TrialGate;
 };
@@ -36,10 +38,10 @@ export type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<str
  */
 export type TrialGate = (tenantId: TenantId, featureName: string) => Promise<boolean>;
 /**
- * Plugin-shape für tier-resolver-extension. Plugins implementieren `build`
- * als boot-time factory: kriegen `db` + `registry` (post-stack-setup),
- * laden initial cache aus DB, returnen den synchronen resolver-callback
- * (optional mit angehängtem `trialGate`).
+ * Plugin shape for the tier-resolver extension. Plugins implement `build`
+ * as a boot-time factory: they receive `db` + `registry` (after stack setup),
+ * load the initial cache from the database, and return the synchronous
+ * resolver callback, optionally with an attached `trialGate`.
  */
 export type TierResolverPlugin = {
     readonly build: (deps: {
@@ -49,13 +51,13 @@ export type TierResolverPlugin = {
     }) => Promise<EffectiveFeaturesResolver>;
 };
 /**
- * Scan a composed feature-list for a `tenantTierResolver`-extension usage.
- * Single plugin assumption — multiple wären ambiguous (welcher resolver
- * gewinnt). Memory `feedback_no_options_without_need`: kein multi-merge-
- * pattern bis es echten Use-Case gibt.
+ * Scans a composed feature list for a `tenantTierResolver` extension usage.
+ * Only one plugin is supported because multiple plugins would be ambiguous:
+ * it would be unclear which resolver should win. No multi-merge pattern is
+ * needed until there is a real use case.
  *
- * Geteilter helper für runDevApp + runProdApp damit der Pickup-Pfad
- * bit-identisch ist (drift-resistent).
+ * Shared by runDevApp + runProdApp so the pickup path remains byte-for-byte
+ * identical and cannot drift.
  */
 /** Narrows a registration's untyped `options` bag to the tier-resolver
  *  plugin shape — the only thing every implementation must provide is the

package/dist/engine/tier-resolver-extension.js

@@ -1,40 +1,40 @@
-// Sprint-8a Tier-Composition: framework-extension-point für per-tenant
+// Tier composition: framework extension point for per-tenant
 // effective-feature resolution.
 //
-// **Pattern (analog mail-foundation / file-foundation):** ein Feature
-// declares `r.extendsRegistrar("tenantTierResolver")` und plugins
-// implementieren via `r.useExtension("tenantTierResolver", "id", { build })`.
+// **Pattern (analogous to mail-foundation / file-foundation):** a feature
+// declares `r.extendsRegistrar("tenantTierResolver")`, and plugins
+// implement it via `r.useExtension("tenantTierResolver", "id", { build })`.
 //
-// **Auto-wiring im Framework:** runDevApp + runProdApp scannen das registry
-// nach genau diesem extension-name. Wenn ein plugin gefunden ist UND der
-// App-Author nicht selbst eine `effectiveFeatures`-callback gesetzt hat,
-// wird `plugin.build({ db, registry })` einmalig in onAfterSetup aufgerufen.
-// Der returned callback landet als `effectiveFeatures` im dispatcher.
+// **Framework auto-wiring:** runDevApp + runProdApp scan the registry
+// for this exact extension name. If a plugin is found AND the app author
+// has not set an `effectiveFeatures` callback, `plugin.build({ db, registry })`
+// is called once in onAfterSetup. The returned callback becomes
+// `effectiveFeatures` in the dispatcher.
 //
-// **Warum dieser Pattern:** App-Author mountet `createTierEngineFeature(opts)`
-// und das war's — kein Late-Bound-Holder im run-config, kein
-// effectiveFeatures-callback wiren. Das Framework macht den Late-Bound-Trick
-// intern. Memory `feedback_alles_ist_ein_feature`: Tier-Composition ist
-// ein Feature, nicht ein Subsystem mit App-spezifischem Wiring.
+// **Why this pattern:** the app author mounts
+// `createTierEngineFeature(opts)` and is done—no late-bound holder in the
+// run config and no need to wire an effectiveFeatures callback. The framework
+// handles the late-binding internally. Tier composition is a feature, not a
+// subsystem with app-specific wiring.
 //
-// **Apps ohne tier-engine:** wenn keine plugin registriert ist, framework
-// macht nichts — `effectiveFeatures` bleibt undefined, alle features sind on.
+// **Apps without a tier engine:** if no plugin is registered, the framework
+// does nothing—`effectiveFeatures` remains undefined, and all features are on.
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 /**
- * Extension-name unter dem ein tier-resolver-plugin im registry registriert
- * werden muss. Konstante damit `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
- * + framework's `getExtensionUsages(TENANT_TIER_RESOLVER_EXT)` typo-resistent
- * gegen den selben Wert prüfen.
+ * Extension name under which a tier-resolver plugin must be registered in the
+ * registry. The constant keeps `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
+ * and the framework's `getExtensionUsages(TENANT_TIER_RESOLVER_EXT)` aligned
+ * on the same value, preventing typos.
  */
 export const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
 /**
- * Scan a composed feature-list for a `tenantTierResolver`-extension usage.
- * Single plugin assumption — multiple wären ambiguous (welcher resolver
- * gewinnt). Memory `feedback_no_options_without_need`: kein multi-merge-
- * pattern bis es echten Use-Case gibt.
+ * Scans a composed feature list for a `tenantTierResolver` extension usage.
+ * Only one plugin is supported because multiple plugins would be ambiguous:
+ * it would be unclear which resolver should win. No multi-merge pattern is
+ * needed until there is a real use case.
  *
- * Geteilter helper für runDevApp + runProdApp damit der Pickup-Pfad
- * bit-identisch ist (drift-resistent).
+ * Shared by runDevApp + runProdApp so the pickup path remains byte-for-byte
+ * identical and cannot drift.
  */
 /** Narrows a registration's untyped `options` bag to the tier-resolver
  *  plugin shape — the only thing every implementation must provide is the

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