@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

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/strip-disabled-features-from-app-schema.js

@@ -11,42 +11,79 @@
 // gone it also drops every action, redirect, nav and workspace member that
 // pointed at them. The one reference it does not resolve is a nav `parent`
 // pointing at a missing nav; that is pruned here.
+import { createFallbackLogger, scrubLogText } from "../logging/index.js";
 import { resolveScreenTargetQn } from "./boot-validator/screens.js";
 import { isToggleableFeature } from "./effective-features.js";
+import { isPureGroupingNav } from "./project-app-schema-for-roles.js";
 import { isValidQn, qualifyEntityName } from "./qualified-name.js";
+const schemaLogger = createFallbackLogger("app-schema");
 // Sorted, so the result doubles as a stable cache key. The trial gate is
 // consulted like the dispatcher's feature gate does, but only for toggleable
 // features: a trial can only unlock tier (toggleable) features, so a
-// cascade-disabled always-on feature needs no gate call.
+// cascade-disabled always-on feature needs no gate call. A failing gate counts
+// as "not unlocked" (the handlers answer 403 then anyway), so a gate outage
+// hides the add-on instead of taking the whole schema endpoint down.
 export async function resolveDisabledFeatureNames(registry, effectiveFeatures, tenantId) {
     const enabled = effectiveFeatures(tenantId);
-    const disabled = [];
-    for (const [featureName, feature] of registry.features) {
-        if (enabled.has(featureName))
-            continue;
-        if (isToggleableFeature(feature) &&
-            (await effectiveFeatures.trialGate?.(tenantId, featureName))) {
-            continue;
+    const trialGate = effectiveFeatures.trialGate;
+    const disabled = [...registry.features].filter(([featureName]) => !enabled.has(featureName));
+    const unlockedByTrial = await Promise.all(disabled.map(async ([featureName, feature]) => {
+        if (trialGate === undefined || !isToggleableFeature(feature))
+            return false;
+        try {
+            return await trialGate(tenantId, featureName);
         }
-        disabled.push(featureName);
-    }
-    return disabled.sort();
+        catch (error) {
+            schemaLogger.warn("trial gate failed, treating feature as not unlocked", {
+                featureName,
+                error: scrubLogText(error instanceof Error ? error.message : String(error)),
+            });
+            return false;
+        }
+    }));
+    return disabled
+        .filter((_, index) => !unlockedByTrial[index])
+        .map(([featureName]) => featureName)
+        .sort();
 }
 function navParentQn(featureName, parent) {
     return isValidQn(parent) ? parent : qualifyEntityName(featureName, "nav", parent);
 }
-// Navs of enabled features whose parent chain ends in a removed nav.
+function navQnsByParent(features) {
+    const childrenByParent = new Map();
+    for (const feature of features) {
+        for (const nav of feature.navs ?? []) {
+            if (nav.parent === undefined)
+                continue;
+            const parentQn = navParentQn(feature.featureName, nav.parent);
+            const children = childrenByParent.get(parentQn) ?? [];
+            children.push(qualifyEntityName(feature.featureName, "nav", nav.id));
+            childrenByParent.set(parentQn, children);
+        }
+    }
+    return childrenByParent;
+}
+// Navs of enabled features whose parent chain ends in a removed nav, plus pure grouping
+// navs whose children are all removed (an empty section the role projection cannot drop,
+// because it only drops groups that still have children).
 function collectOrphanedNavQns(features, removedNavQns) {
     const orphaned = new Set();
+    const childrenByParent = navQnsByParent(features);
     let changed = true;
     while (changed) {
         changed = false;
         for (const feature of features) {
             for (const nav of feature.navs ?? []) {
                 const qn = qualifyEntityName(feature.featureName, "nav", nav.id);
-                if (removedNavQns.has(qn) || nav.parent === undefined)
+                if (removedNavQns.has(qn))
                     continue;
-                if (removedNavQns.has(navParentQn(feature.featureName, nav.parent))) {
+                const parentRemoved = nav.parent !== undefined &&
+                    removedNavQns.has(navParentQn(feature.featureName, nav.parent));
+                const children = childrenByParent.get(qn) ?? [];
+                const emptiedGroup = isPureGroupingNav(nav) &&
+                    children.length > 0 &&
+                    children.every((childQn) => removedNavQns.has(childQn));
+                if (parentRemoved || emptiedGroup) {
                     removedNavQns.add(qn);
                     orphaned.add(qn);
                     changed = true;

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,17 @@
 // 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 { resolveTableName } from "../db/entity-table-meta.js";
 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,11 +77,10 @@ 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 ?? {})) {
-            const tableName = entity.table ?? entityName;
+            const tableName = resolveTableName(entityName, entity, undefined);
             const existing = aggregateTables.get(tableName);
             if (existing && existing !== f.name) {
                 throw new Error(`Aggregate-table "${tableName}" is registered by both feature "${existing}" and feature "${f.name}" via r.entity. ` +
@@ -129,8 +110,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 +121,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) {