@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/engine/feature-manifest.d.ts

@@ -48,10 +48,10 @@ export type ManifestFeature = {
     readonly extensionsUsed: readonly ManifestExtension[];
     readonly configKeys: readonly ManifestConfigKey[];
     readonly secrets: readonly ManifestSecret[];
-    /** Alle registrierten Write-Handler-QNs dieses Features
-     *  (z.B. "user:write:user:create", "auth-email-password:write:login").
-     *  Von `collectWriteHandlerQns` abgeleitet — dient als Source-of-Truth
-     *  für den Client-seitigen Typcheck von `dispatcher.write`-Calls. */
+    /** All registered write-handler QNs for this feature
+     *  (e.g. "user:write:user:create", "auth-email-password:write:login").
+     *  Derived from `collectWriteHandlerQns` and used as the source of truth
+     *  for client-side type checking of `dispatcher.write` calls. */
     readonly writeHandlers: readonly string[];
     /** Picker/scaffolder UI metadata declared via r.uiHints(). Optional —
      *  absent for features that haven't been annotated yet (the picker falls
@@ -68,13 +68,13 @@ export type FeatureManifest = {
     readonly tier?: string;
 };
 export type BuildManifestOptions = {
-    /** Herkunfts-Beschreibung fürs Manifest (landet 1:1 im JSON). */
+    /** Description of the manifest's origin, included unchanged in the JSON. */
     readonly source: string;
-    /** Nur diese Features emittieren (z.B. die 16 enterprise-Features einer
-     *  Registry, die auch deren bundled-requires gemountet hat). Default:
-     *  alle Features der Registry. */
+    /** Emit only these features (e.g. the 16 enterprise features from a
+     *  Registry that also mounted their bundled requirements). Default:
+     *  all features in the Registry. */
     readonly featureNames?: ReadonlySet<string>;
-    /** Taggt jedes Feature + das Manifest top-level (z.B. "enterprise"). */
+    /** Tags each feature and the top-level manifest (e.g. "enterprise"). */
     readonly tier?: string;
 };
 export declare function buildManifestFromRegistry(registry: Registry, options: BuildManifestOptions): FeatureManifest;

package/dist/engine/feature-manifest.js

@@ -1,10 +1,9 @@
-// Runtime-introspected feature-manifest — die geteilte Extraktionslogik
-// hinter `gen-feature-manifest.ts` (use-all-bundled) und dem enterprise-
-// Generator. Vorher waren das zwei fast wortgleiche Forks mit divergentem
-// Schema (enterprise#95): erweitert das Framework die Introspektion, driftete
-// die Kopie still. Quelle der Wahrheit ist die GEBOOTETE Registry — der
-// AST-Parser kann die imperativen Factory-Helper der bundled features nicht
-// lesen.
+// Runtime-introspected feature manifest — shared extraction logic for
+// `gen-feature-manifest.ts` (use-all-bundled) and the enterprise generator.
+// These were previously two nearly identical forks with diverging schemas:
+// when framework introspection was extended, the copy silently drifted. The
+// booted Registry is authoritative because the AST parser cannot read the
+// imperative factory helpers of bundled features.
 import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii.js";
 import { compareByCodepoint } from "../utils/index.js";
 import { isEncryptedAtRest } from "./config-helpers.js";

package/dist/engine/feature-ui-extensions.d.ts

@@ -38,9 +38,9 @@ export declare function buildUiExtensionsMethods<TName extends string>(state: Fe
      */
     exposesApi(apiName: string): void;
     /**
-     * Declares that this feature calls a cross-feature API. Boot-Validator
-     * checkt dass irgendein anderes Feature `r.exposesApi(name)` macht und
-     * dass dieses Feature `r.requires` darauf hat.
+     * Declares that this feature calls a cross-feature API. The boot validator
+     * checks that another feature calls `r.exposesApi(name)` and that this
+     * feature declares a corresponding `r.requires` dependency.
      */
     usesApi(apiName: string): void;
     bootCheck(fn: BootCheckFn): void;

package/dist/engine/feature-ui-extensions.js

@@ -6,7 +6,7 @@ import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js"
 import { LifecycleHookTypes } from "./constants.js";
 import { reasonProblem } from "./escape-hatch-reason.js";
 import { resolveName } from "./handler-helpers.js";
-import { isObjectArgument, throwObjectArgumentRequired } from "./object-form.js";
+import { isObjectArgument, requireArgument, throwObjectArgumentRequired } from "./object-form.js";
 import { isKebabSegment, isValidQn, qualifyEntityName, toKebab } from "./qualified-name.js";
 import { HookPhases } from "./types/index.js";
 // Builds hooks/extensions/projections/screens/nav/workspace/tables/tree-actions
@@ -159,7 +159,7 @@ export function buildUiExtensionsMethods(state, name) {
             }
             const targets = Array.isArray(target) ? target : [target];
             const names = targets.map(resolveName);
-            // Hook-fn casts unten alle: @cast-boundary engine-bridge
+            // All hook-function casts below: @cast-boundary engine-bridge
             // — typed Dev-API (LifecycleHookFn|ValidationHookFn) → erased Map<name, fn>.
             if (type === "validation") {
                 for (const n of names) {
@@ -211,7 +211,11 @@ export function buildUiExtensionsMethods(state, name) {
         },
         useExtension(extensionNameOrDefinition, entityRef, options) {
             const [extensionName, resolvedEntityRef, resolvedOptions] = typeof extensionNameOrDefinition === "string"
-                ? [extensionNameOrDefinition, entityRef, options]
+                ? [
+                    extensionNameOrDefinition,
+                    requireArgument(entityRef, name, "useExtension", "entity"),
+                    options,
+                ]
                 : (() => {
                     const { name, entity, ...rest } = extensionNameOrDefinition;
                     return [name, entity, rest];
@@ -219,13 +223,14 @@ export function buildUiExtensionsMethods(state, name) {
             const resolvedEntityName = resolveName(resolvedEntityRef);
             // @cast-boundary engine-bridge — typed per-extension options → erased registration bag
             const optionsBag = resolvedOptions;
-            // fw#2914 — cross-cutting escapeHatch convention for hook-context db
+            // Cross-cutting escapeHatch convention for hook-context db
             // access (mirrors r.hook's validation above). Validated the same way
             // for every extension regardless of its typed hook shape.
             const escapeHatch = optionsBag?.["escapeHatch"];
             if (escapeHatch !== undefined) {
-                const reason = isPlainObject(escapeHatch) ? escapeHatch["reason"] : undefined;
-                if (typeof reason !== "string") {
+                const escapeHatchObject = isPlainObject(escapeHatch) ? escapeHatch : undefined;
+                const reason = escapeHatchObject?.["reason"];
+                if (escapeHatchObject === undefined || typeof reason !== "string") {
                     throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ` +
                         `must be { reason: "<explanation>" } explaining why this usage needs unfiltered db access.`);
                 }
@@ -233,7 +238,7 @@ export function buildUiExtensionsMethods(state, name) {
                 if (extReasonProblem !== undefined) {
                     throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extReasonProblem}`);
                 }
-                const extGrantsProblem = escapeHatchGrantsProblem(escapeHatch);
+                const extGrantsProblem = escapeHatchGrantsProblem(escapeHatchObject);
                 if (extGrantsProblem) {
                     throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ${extGrantsProblem}`);
                 }
@@ -282,9 +287,9 @@ export function buildUiExtensionsMethods(state, name) {
             state.exposedApis.add(apiName);
         },
         /**
-         * Declares that this feature calls a cross-feature API. Boot-Validator
-         * checkt dass irgendein anderes Feature `r.exposesApi(name)` macht und
-         * dass dieses Feature `r.requires` darauf hat.
+         * Declares that this feature calls a cross-feature API. The boot validator
+         * checks that another feature calls `r.exposesApi(name)` and that this
+         * feature declares a corresponding `r.requires` dependency.
          */
         usesApi(apiName) {
             state.usedApis.add(apiName);
@@ -344,7 +349,11 @@ export function buildUiExtensionsMethods(state, name) {
                     entityRefOrDefinition.data,
                     entityRefOrDefinition.upsertKey,
                 ]
-                : [entityRefOrDefinition, data, options?.upsertKey];
+                : [
+                    entityRefOrDefinition,
+                    requireArgument(data, name, "referenceData", "data"),
+                    options?.upsertKey,
+                ];
             state.referenceData.push({
                 entityName: resolveName(entityRef),
                 data: resolvedData,
@@ -424,10 +433,9 @@ export function buildUiExtensionsMethods(state, name) {
             state.workspaces[definition.id] = definition;
         },
         httpRoute(definition) {
-            // Path-Validation: muss mit "/" beginnen, keine /api/-Routes (die
-            // sind dem Dispatcher reserviert; eine HTTP-Route die /api/foo
-            // belegt, würde die Auth-Middleware umgehen ohne dass der Author
-            // das ausgesprochen hat — bewusster Block).
+            // Path validation: must start with "/"; /api/ routes are reserved for the
+            // dispatcher. An HTTP route occupying /api/foo could bypass the auth
+            // middleware without the author explicitly intending it, so block it.
             if (!definition.path.startsWith("/")) {
                 throw new Error(`[Feature ${name}] httpRoute path "${definition.path}" must start with "/". ` +
                     `Got "${definition.path}".`);
@@ -505,7 +513,7 @@ export function buildUiExtensionsMethods(state, name) {
             }
             // `read_` is reserved for r.entity()/r.projection() (managed,
             // event-sourced, rebuildable). storeTable is the unmanaged
-            // direct-write escape hatch — the prefix must say so (#1220).
+            // direct-write escape hatch — the prefix must say so.
             if (tableName.startsWith("read_")) {
                 throw new Error(`[Feature ${name}] r.storeTable("${tableName}"): the "read_" prefix is reserved ` +
                     `for managed r.entity()/r.projection() tables. Pick an unprefixed name or a ` +
@@ -514,7 +522,7 @@ export function buildUiExtensionsMethods(state, name) {
             // meta.source must agree with the r.storeTable() escape hatch, or the
             // migrate-generator treats schema drift on this table as safe to
             // DROP+rebuild-from-events — wiping direct-write data with no events
-            // to replay it from (#1209).
+            // to replay it from.
             if (meta.source !== "unmanaged") {
                 throw new Error(`[Feature ${name}] r.storeTable("${tableName}") was given an EntityTableMeta with ` +
                     `source: "${meta.source}". r.storeTable() requires source: "unmanaged" (via ` +
@@ -538,16 +546,16 @@ export function buildUiExtensionsMethods(state, name) {
             };
         },
         treeActions(actions) {
-            // Only-once-guard: zweiter Aufruf ist Author-Bug, soll am
-            // Feature-File aufschlagen (gleicher Stil wie r.toggleable).
+            // Only-once guard: a second call is an authoring error that should surface in
+            // the feature file (matching the behavior of r.toggleable).
             if (state.treeActions !== undefined) {
                 throw new Error(`[Feature ${name}] r.treeActions() already called. ` +
                     `Each feature may declare a single tree-actions schema.`);
             }
             state.treeActions = actions;
-            // Return typed handle für setup-export. Frozen damit Caller die
-            // Map nicht nachträglich mutieren (würde Pattern-AST + Runtime-
-            // Lookup divergieren lassen).
+            // Return a typed handle for the setup export. Freeze it so callers cannot
+            // mutate the map afterward, which would make the pattern AST and runtime
+            // lookup diverge.
             return Object.freeze({
                 id: name,
                 treeActions: actions,

package/dist/engine/field-access.js

@@ -119,18 +119,17 @@ export function checkWriteFieldRoles(entity, changes, user) {
 // row. For creates, pass oldRow = undefined; the check degenerates to a
 // newRow-only evaluation.
 //
-// `submittedChanges` and `rowContext` are deliberately separate (fw#1685):
+// `submittedChanges` and `rowContext` are deliberately separate:
 // - `submittedChanges` drives WHICH fields get checked — only what the user
 //   actually wrote in the request. A preSave-hook-derived field the user
 //   never touched (e.g. a system hook setting `assignedTo`) must not be
 //   field-ownership-checked against the user at all.
 // - `rowContext` drives what a checked field's rule is evaluated AGAINST —
 //   this needs the full post-hook row, because an ownership rule can
-//   reference a DIFFERENT column that only a hook populates (kumiko-
-//   framework#1672: a hook derives `authorId`, a user-submitted `secretNote`
-//   field's rule is `from("user:id", "authorId")` — the check needs the
-//   hook-derived `authorId` in scope even though the user only wrote
-//   `secretNote`). Defaults to `submittedChanges` when omitted.
+//   reference a DIFFERENT column that only a hook populates (a hook derives
+//   `authorId`, a user-submitted `secretNote` field's rule is `from("user:id", "authorId")`
+//   — the check needs the hook-derived `authorId` in scope even though the
+//   user only wrote `secretNote`). Defaults to `submittedChanges` when omitted.
 //
 // Returns the denied field name for the caller to wrap into an
 // `ownership_denied` error with scope: "field", or null if all fields pass.

package/dist/engine/form-derivations.js

@@ -101,17 +101,30 @@ function sumListCell(rows, listField, cell) {
     return sum;
 }
 function targetCurrency(field, current, sourceCurrency) {
+    // The client value is last: it must never override what the field or its sources dictate.
+    if (field.type === "money" && field.currency.kind === "literal")
+        return field.currency.code;
+    if (sourceCurrency !== undefined)
+        return sourceCurrency;
     if (isPlainObject(current) &&
         typeof current["currency"] === "string" &&
         current["currency"] !== "") {
         return current["currency"];
     }
-    if (sourceCurrency !== undefined)
-        return sourceCurrency;
-    if (field.type === "money" && field.currency.kind === "literal")
-        return field.currency.code;
     return undefined;
 }
+function computeOrdinary(derivation, values, fields) {
+    const operands = derivation.from.map((name) => readOperand(values, fields, name));
+    const currencies = new Set(operands.flatMap((operand) => operand.currency ?? []));
+    const sourceCurrency = currencies.values().next().value;
+    // Operands in different currencies have no meaningful sum.
+    if (currencies.size > 1)
+        return { computed: undefined, sourceCurrency };
+    return {
+        computed: computeDerivedCellValue(derivation.op, operands.map((operand) => operand.value)),
+        sourceCurrency,
+    };
+}
 /** Recomputes every derived head field of an action form from its inputs.
  *  Pure and client-safe: the renderer runs it live, the server runs it
  *  again (`withFormDerivations`) and overwrites whatever the client sent.
@@ -148,9 +161,7 @@ export function applyFormDerivations(values, screen) {
             ordinary = derivation;
         }
         if (ordinary !== undefined) {
-            const operands = ordinary.from.map((name) => readOperand(result, screen.fields, name));
-            sourceCurrency = operands.find((operand) => operand.currency !== undefined)?.currency;
-            computed = computeDerivedCellValue(ordinary.op, operands.map((operand) => operand.value));
+            ({ computed, sourceCurrency } = computeOrdinary(ordinary, result, screen.fields));
         }
         if (computed === undefined) {
             delete result[target];

package/dist/engine/handler-field-references.js

@@ -5,7 +5,7 @@ const MAX_WRAPPER_DEPTH = 8;
 const MAX_NESTING_DEPTH = 8;
 const referenceMetaSchema = z.union([
     z.string().min(1),
-    z.object({ entity: z.string().min(1), by: z.string().min(1).optional() }),
+    z.strictObject({ entity: z.string().min(1), by: z.string().min(1).optional() }),
 ]);
 function rawReferenceMeta(field) {
     const meta = zodMeta(field);

package/dist/engine/index.d.ts

@@ -91,4 +91,5 @@ export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMe
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.ts";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.ts";
 export { runValidation } from "./validation.ts";
+export { walkStepInstances } from "./walk-step-instances.ts";
 export { formDerivationsOfSchema, withFormDerivations } from "./with-form-derivations.ts";

package/dist/engine/index.js

@@ -22,10 +22,9 @@ export { defineStep, getStep, listStepKinds } from "./define-step.js";
 export { computeDefinitionFingerprint, defineWorkflow } from "./define-workflow.js";
 export { computeEffectiveFeatures, isToggleableFeature } from "./effective-features.js";
 export { createEntityExecutor, defineEntityCreateHandler, defineEntityDeleteHandler, defineEntityDetailHandler, defineEntityListHandler, 
-// Legacy single-fn-with-verb-string API. Backwards-compat — neue
-// Apps nehmen die verb-spezifischen Wrapper oben. Existierende
-// Caller (Integration-Tests, alte bundled-features) bleiben so
-// unverändert lauffähig.
+// Legacy single-fn-with-verb-string API. Backwards compatibility — new
+// apps use the verb-specific wrappers above. Existing callers (integration
+// tests, old bundled-features) remain runnable without changes.
 defineEntityQueryHandler, defineEntityRestoreHandler, defineEntityUpdateHandler, defineEntityWriteHandler, defineProjectionQueryHandler, entityListSchema, MAX_LIST_LIMIT, } from "./entity-handlers.js";
 export { declareEscapeHatch } from "./escape-hatch-declaration.js";
 export { createEventDef } from "./event-def.js";
@@ -81,4 +80,5 @@ export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTra
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export { runValidation } from "./validation.js";
+export { walkStepInstances } from "./walk-step-instances.js";
 export { formDerivationsOfSchema, withFormDerivations } from "./with-form-derivations.js";

package/dist/engine/object-form.d.ts

@@ -1,6 +1,7 @@
 export declare function splitNamedDefinition<T extends {
     readonly name: string;
 }>(definition: T): [string, Omit<T, "name">];
+export declare function requireArgument<T>(value: T | undefined, featureName: string, method: string, argument: string): T;
 export declare function unwrapArrayForm<K extends string>(args: readonly [Record<K, readonly string[]>] | readonly string[], key: K): readonly string[];
 export declare function isObjectArgument(value: unknown): boolean;
 export declare function throwObjectArgumentRequired(featureName: string, method: string): never;

package/dist/engine/object-form.js

@@ -4,14 +4,24 @@ export function splitNamedDefinition(definition) {
     const { name, ...rest } = definition;
     return [name, rest];
 }
+// The `(name, options)` overloads make `options` required for typed callers;
+// the implementation signature has to stay optional, so untyped callers are caught here.
+export function requireArgument(value, featureName, method, argument) {
+    if (value === undefined) {
+        throw new Error(`[Feature ${featureName}] r.${method}() needs its ${argument} argument`);
+    }
+    return value;
+}
+function isStringList(args) {
+    return args.every((arg) => typeof arg === "string");
+}
 // `optionalRequires` and `readConfig` still accept variadic strings next to a
 // single object wrapping the same string array under `key`.
 export function unwrapArrayForm(args, key) {
+    if (isStringList(args))
+        return args;
     const [first] = args;
-    if (typeof first === "object" && first !== null && key in first) {
-        return first[key];
-    }
-    return args;
+    return first[key];
 }
 export function isObjectArgument(value) {
     return typeof value === "object" && value !== null;

package/dist/engine/ownership.js

@@ -72,7 +72,7 @@ export function matchesRule(rule, user, row) {
         // `where` rules produce SQL for the DB-side filter and have no in-memory
         // evaluator — the feature author owns the semantics. Only the read path
         // reaches SQL (buildOwnershipClause); on write maps the boot-validator
-        // rejects them outright (fw#2626), and the in-memory write helpers below
+        // rejects them outright, and the in-memory write helpers below
         // fail closed rather than calling in here.
         throw new Error("where-rules can only be evaluated at the SQL layer (buildOwnershipClause); they are rejected on access.write at boot.");
     }
@@ -219,7 +219,7 @@ export function shiftParams(fragment, shift) {
 // is a boot-time misconfiguration; at request time we treat it as empty
 // (safe default) rather than passing silently.
 //
-// Caller obligations (fw#1700) — this function returns ONLY the ownership
+// Caller obligations — this function returns ONLY the ownership
 // fragment, not the full row-access contract. A raw-SQL caller (not going
 // through `ctx.db`, which already applies all three) must additionally:
 //   1. Pass `paramStart` as `params.length + 1` for its own already-bound
@@ -309,7 +309,7 @@ function ruleToFragment(rule, user, table, paramStart) {
         });
         // Runtime backstop for the boot-time probe (boot-validator/ownership.ts):
         // an unqualified column in a correlated subquery silently turns into a
-        // fail-open tautology (fw#2639) — throw instead of shipping it.
+        // fail-open tautology — throw instead of shipping it.
         assertQualifiedWhereFragment(frag.sqlText, cachedTableColumnSqlNames(table), `ownership where-rule on "${tableNameOf(table)}"`);
         return { kind: "sql", sqlText: frag.sqlText, params: frag.params };
     }

package/dist/engine/parse-ref-target.js

@@ -1,12 +1,10 @@
-// Tier 2.7e Cross-Feature: ReferenceFieldDef.entity-String-Parser.
-//
-// Akzeptiert beide Formen:
+// Parser for the ReferenceFieldDef.entity string. Accepts both forms:
 //   - "user"        → same-feature ref (featureName = currentFeature)
-//   - "users:user"  → cross-feature ref (qualifiziert)
+//   - "users:user"  → cross-feature ref (qualified)
 //
-// Lebt im framework-Package damit Server-Validator + Renderer (über
-// Re-Export aus @cosmicdrift/kumiko-renderer/headless) denselben Parser nutzen — die
-// Convention darf nicht zweimal implementiert werden.
+// Kept in the framework package so the server validator and renderer (via
+// re-export from @cosmicdrift/kumiko-renderer/headless) use the same parser;
+// the convention must not be implemented twice.
 export function parseRefTarget(raw, currentFeature) {
     const idx = raw.indexOf(":");
     if (idx < 0) {

package/dist/engine/pattern-library/index.js

@@ -1,3 +1,3 @@
-// Public API of the pattern-library — Designer (C5/C6), AI-Builder (L2),
-// MCP-Server (L9) consume from here.
+// Public API of the pattern-library — Designer, AI-Builder,
+// MCP-Server consume from here.
 export { getPatternSchema, groupByCategory, PATTERN_LIBRARY } from "./library.js";

package/dist/engine/pattern-library/library.js

@@ -1,6 +1,6 @@
 // Pattern-Library — concrete FormSchema entries for every FeaturePattern
-// kind. Centralised here so the Designer (C5/C6), the AI-Builder (L2),
-// and the MCP-Server (L9) share one source-of-truth for "how does this
+// kind. Centralised here so the Designer, the AI-Builder,
+// and the MCP-Server share one source-of-truth for "how does this
 // pattern look as a form?".
 //
 // **Updating contract:** when a new pattern-kind gets a parser/renderer

package/dist/engine/pattern-library/types.js

@@ -1,7 +1,7 @@
 // Forms-Schema metadata — describes how a FeaturePattern is rendered as
 // a Designer form, fed to an LLM as a JSON-Schema, or surfaced in the
 // MCP-Server tool list. One schema, three consumers — that's the whole
-// point of factoring this out of the hand-rolled C5 skeleton.
+// point of factoring this out of the hand-rolled skeleton.
 //
 // **NOT a DSL.** The Source-of-Truth for a feature stays
 // `defineFeature.ts` — the AST-visitor (feature-ast/parse.ts) reads it
@@ -10,7 +10,7 @@
 // already-parsed FeaturePattern in a form. No alternative parser, no
 // alternative syntax, no second canonical representation.
 //
-// **Vokabular** (12 input-types):
+// **Vocabulary** (12 input-types):
 //
 //   text                  — single-line string (name / label / id)
 //   textarea              — multi-line string (description / SQL / readme)
@@ -31,6 +31,6 @@
 // FeaturePattern object using dot-separated keys (`definition.fields`,
 // `access.roles`, `templates.email`). Numeric indices use the bracket
 // form (`columns.0`). The Designer/LLM uses paths for read & write —
-// the patcher (C2) consumes pattern-level updates only, so paths are
+// the patcher consumes pattern-level updates only, so paths are
 // purely a UI concern at this stage.
 export {};

package/dist/engine/pipeline.js

@@ -8,7 +8,7 @@
 // the resolver-side PipelineCtx (run-pipeline.ts). Resolvers that need
 // prior step results destructure them from the resolver's ctx.
 //
-// Renamed from `pipeline()` (Followup #1) — it shared its name with the
+// Renamed from `pipeline()` — it shared its name with the
 // internal `packages/framework/src/pipeline/` directory (dispatcher,
 // lifecycle, outbox-poller), which made repo-wide grep for `pipeline`
 // return mixed results.
@@ -76,7 +76,7 @@ export function stepsPipeline(closure) {
 // awaits map wired into the closure. The cast below is the one place a
 // workflow's raw declared event-type strings become AwaitedEventType — safe
 // because pipelineDef.awaits only ever holds what defineWorkflow's `awaits`
-// carried in (D4, workflow-resume-loop.md), never an unchecked external
+// carried in (workflow-resume-loop.md), never an unchecked external
 // value.
 export function buildPipelineSteps(pipelineDef, event) {
     const steps = pipelineDef.build({

package/dist/engine/project-app-schema-for-roles.d.ts

@@ -1,2 +1,4 @@
 import type { AppSchema } from "../ui-types/app-schema.ts";
+import type { NavDefinition } from "./types/nav.ts";
 export declare function projectAppSchemaForRoles(schema: AppSchema, roles: readonly string[]): AppSchema;
+export declare function isPureGroupingNav(nav: Pick<NavDefinition, "screen" | "target" | "provider">): boolean;

package/dist/engine/project-app-schema-for-roles.js

@@ -1,4 +1,4 @@
-// Per-role projection of a fully-built AppSchema (fw#3314). GET /api/schema
+// Per-role projection of a fully-built AppSchema. GET /api/schema
 // used to ship the same full schema — screens, navs, workspaces, content
 // collections — to every authenticated user regardless of role, relying on
 // client-side UI checks (isUiAccessGranted) alone to hide what a role
@@ -27,7 +27,7 @@
 // @cosmicdrift/kumiko-types/handlers) — an unset `access` here means every
 // signed-in user may see the entry, the opposite stance from `hasAccess`.
 //
-// Reference-site coverage (every place boot-validator/screens.ts resolves a
+// Reference-site coverage (every place boot-validator/screens*.ts resolves a
 // screen target is a site this file also projects):
 //   - nav.screen / nav.parent (author-registered AND settings-hub-generated
 //     navs — the latter use short ids relative to the synthetic "config"
@@ -204,16 +204,18 @@ function isNavDeniedOrDead(ctx, screenAccessByQn, keptScreenQns, roles) {
     const effectiveAccess = ctx.nav.access ?? screenAccessByQn.get(ctx.resolvedScreenQn);
     return !isUiAccessGranted(effectiveAccess, roles);
 }
+export function isPureGroupingNav(nav) {
+    return nav.screen === undefined && nav.target === undefined && nav.provider !== true;
+}
 function isDroppedByPropagation(ctx, dropped, childrenByParent) {
     if (ctx.resolvedParentQn !== undefined && dropped.has(ctx.resolvedParentQn))
         return true;
-    const isPureGroupingNode = ctx.nav.screen === undefined && ctx.nav.target === undefined && ctx.nav.provider !== true;
-    if (!isPureGroupingNode)
+    if (!isPureGroupingNav(ctx.nav))
         return false;
     const children = childrenByParent.get(ctx.qn) ?? [];
     return children.length > 0 && children.every((child) => dropped.has(child.qn));
 }
-// --- screen-target resolution helpers (mirror boot-validator/screens.ts) ---
+// --- screen-target resolution helpers (mirror boot-validator/screens*.ts) ---
 function isScreenTargetKept(featureName, target, keptScreenQns) {
     return keptScreenQns.has(resolveScreenTargetQn(featureName, target));
 }

package/dist/engine/projection-helpers.js

@@ -1,27 +1,27 @@
 import { updateMany } from "../db/query.js";
-// Typed-Apply-Helper für r.projection.apply: erlaubt per-event-type
-// typed event.payload-Access ohne SingleStreamApplyFn-Generic durch die
-// ganze ProjectionDefinition propagieren zu müssen.
+// Typed apply helper for r.projection.apply: enables typed event.payload
+// access per event type without propagating a SingleStreamApplyFn generic
+// through the entire ProjectionDefinition.
 //
-// Der Helper ist ein purer Type-Vehikel — zur Laufzeit identitäts-fn:
+// The helper is purely a type vehicle — an identity function at runtime:
 //
 //   apply: {
 //     "user.created": defineApply<UserCreatedPayload>(async (event, tx, table) => {
-//       // event.payload ist UserCreatedPayload, nicht Record<string, unknown>.
+//       // event.payload is UserCreatedPayload, not Record<string, unknown>.
 //       // Write through the passed `table` (ES-blessed inside apply), not a
 //       // closed-over branded constant.
 //       await insertOne(tx, table, { id: event.aggregateId, ...event.payload });
 //     }),
 //   }
 //
-// Default-Generic = Record<string, unknown> behält rückwärtskompatibles
-// Verhalten für Apply-Handler die ohne Type-Argument geschrieben sind. Der
-// `table`-Param ist optional zu nutzen — 2-arg-Applies bleiben gültig.
+// The default generic, Record<string, unknown>, preserves backward-compatible
+// behavior for apply handlers written without a type argument. The `table`
+// parameter is optional to use, so 2-argument applies remain valid.
 export function defineApply(fn) {
     // @cast-boundary engine-bridge — typed user-fn → erased internal storage
     return fn;
 }
-// Pendant für r.multiStreamProjection.apply — bekommt zusätzlich ctx.
+// Counterpart for r.multiStreamProjection.apply — also receives ctx.
 export function defineMspApply(fn) {
     // @cast-boundary engine-bridge — typed user-fn → erased internal storage
     return fn;

package/dist/engine/qualified-name.js

@@ -32,7 +32,7 @@ function validateSegment(value, label, context) {
 }
 // registry-ingest.ts also qualifies handlers/projections with these two —
 // not in the public QnTypes enum, but reachable as a type segment the same
-// way (#1991).
+// way.
 const NON_ENUM_QN_TYPES = ["stream", "projection", "workspace"];
 // Every segment word that a fully-qualified QN can carry as its type.
 const RESERVED_QN_SEGMENTS = new Set([
@@ -44,7 +44,7 @@ const RESERVED_QN_SEGMENTS = new Set([
 // the trailing part. Both signals must hold together: the scope alone
 // repeating (e.g. entity "user:create" on feature "user") or a reserved word
 // alone appearing (e.g. "compliance:query:for-tenant") are both common,
-// legitimate sub-structure on their own (#1991).
+// legitimate sub-structure on their own.
 function isDoubleQualified(scope, segments) {
     const [first, second] = segments;
     return first === scope && second !== undefined && RESERVED_QN_SEGMENTS.has(second);

package/dist/engine/registry-facade.js

@@ -85,7 +85,7 @@ export function buildRegistryFacade(state) {
         getEntityPostQueryHooks(entityName, effectiveFeatures) {
             return filterOwned(state.entityPostQueryHooks.get(entityName), effectiveFeatures);
         },
-        // F3 — Search-Payload-Extension contributors for an entity. Used by
+        // Search-Payload-Extension contributors for an entity. Used by
         // `buildSearchDocument` in system-hooks.ts to enrich the indexed payload.
         // `effectiveFeatures` filters out contributors owned by feature-toggle-
         // disabled features (parallel to getEntityPostQueryHooks etc.).