@cosmicdrift/kumiko-framework 0.386.0 → 0.387.0

package/dist/engine/feature-ast/parse.js

@@ -17,8 +17,8 @@
 //   - Top-level code outside `defineFeature(...)`. Designer/AI treat
 //     such files as "not a feature file".
 //
-// **Skeleton status (C1.3):** interface fixed, extractors are TODO.
-// Per-pattern extractors fill in iteratively (C1.5) — each round adds
+// **Skeleton status:** interface fixed, extractors are TODO.
+// Per-pattern extractors fill in iteratively — each iteration adds
 // one extractor + a focused test.
 import { Project, SyntaxKind } from "ts-morph";
 import { extractAiClassify, extractAiExtract, extractAiGenerate, extractAuthClaims, extractBootCheck, extractClaimKey, extractConfig, extractDefineEvent, extractDescribe, extractEntity, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractHook, extractHttpRoute, extractJob, extractMetric, extractMultiStreamProjection, extractNav, extractNotification, extractOptionalRequires, extractProjection, extractQueryHandler, extractReadsConfig, extractReferenceData, extractRelation, extractRequires, extractScreen, extractSecret, extractSecretNamespace, extractStoreTable, extractStreamHandler, extractSystemScope, extractToggleable, extractTranslations, extractTreeActions, extractUiHints, extractUseExtension, extractUsesApi, extractWorkspace, extractWriteHandler, findFunctionLiteral, findImportBindingForLocalName, readObjectPropertyInitializer, resolveModuleFile, resolveSameFileObjectLiteral, } from "./extractors/index.js";
@@ -185,7 +185,7 @@ function walkSetupCallback(body, registrarParamName, sourceFile, patterns, error
         // a registrar-wrapper call — a function that receives the registrar as
         // a bare argument, e.g. `registerShowPonyScreens(r)`. Such wrappers are
         // invisible to a receiver-shape match, so we resolve the callee (same
-        // file, or the declaring file of a named import — #1008) and recurse
+        // file, or the declaring file of a named import) and recurse
         // into its body with its own parameter name for the registrar slot.
         const wrapper = resolveRegistrarWrapperCall(call, registrarParamName);
         if (!wrapper)
@@ -368,7 +368,7 @@ function walkAiStepCalls(body, registrarParamName, sourceFile, patterns, errors,
     }
 }
 // =============================================================================
-// Internal — pattern extractors (skeleton, implementation in C1.5)
+// Internal — pattern extractors
 // =============================================================================
 /**
  * Route an `<r>.<method>(...)` call to its concrete extractor. New
@@ -377,12 +377,12 @@ function walkAiStepCalls(body, registrarParamName, sourceFile, patterns, errors,
  * commit to the new kind via compile errors.
  *
  * Skeleton: every recognised method currently returns an UnknownPattern
- * with the right method name. C1.5 replaces the cases with concrete
- * extractors one at a time.
+ * with the right method name. Extractors replace the cases with concrete
+ * implementations one at a time.
  */
 function dispatchExtractor(methodName, call, sourceFile) {
     switch (methodName) {
-        // Round 1 — simplest static patterns
+        // Simplest static patterns
         case "requires":
             return extractRequires(call, sourceFile);
         case "optionalRequires":
@@ -397,7 +397,7 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractDescribe(call, sourceFile);
         case "uiHints":
             return extractUiHints(call, sourceFile);
-        // Round 2 — object-literal-based static patterns
+        // Object-literal-based static patterns
         case "entity":
             return extractEntity(call, sourceFile);
         case "relation":
@@ -406,7 +406,7 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractNav(call, sourceFile);
         case "workspace":
             return extractWorkspace(call, sourceFile);
-        // Round 3 — complex static patterns
+        // Complex static patterns
         case "config":
             return extractConfig(call, sourceFile);
         case "translations":
@@ -423,7 +423,7 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractReferenceData(call, sourceFile);
         case "useExtension":
             return extractUseExtension(call, sourceFile);
-        // Round 4 — mixed (header + body) patterns
+        // Mixed (header + body) patterns
         case "hook":
             return extractHook(call, sourceFile);
         case "authClaims":
@@ -448,7 +448,7 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractMultiStreamProjection(call, sourceFile);
         case "screen":
             return extractScreen(call, sourceFile);
-        // Round 5 — opaque patterns
+        // Opaque patterns
         case "extendsRegistrar":
             return extractExtendsRegistrar(call, sourceFile);
         case "usesApi":
@@ -459,10 +459,10 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractStoreTable(call, sourceFile);
         case "bootCheck":
             return extractBootCheck(call, sourceFile);
-        // Round 6 — Tree-Actions pattern
+        // Tree-Actions pattern
         case "treeActions":
             return extractTreeActions(call, sourceFile);
-        // Round 7 — env-schema contract (opaque, Zod-expression argument)
+        // Env-schema contract (opaque, Zod-expression argument)
         case "envSchema":
             return extractEnvSchema(call, sourceFile);
         // Unknown method — UnknownPattern signal so Designer/AI surface it

package/dist/engine/feature-ast/patch.js

@@ -668,7 +668,7 @@ function callMatchesId(call, id) {
 // a string literal directly, or a bare identifier following its
 // declaration (same-file or imported) to a string-literal initializer —
 // the dominant naming style in the framework's own bundled-features
-// (`r.entity(ENTITY, ...)`, `r.useExtension(EXT_X, ...)`, see #1746).
+// (`r.entity(ENTITY, ...)`, `r.useExtension(EXT_X, ...)`).
 //
 // Narrow on purpose: every kind's arg-0 (and relation's arg-1) is parsed
 // via readNameLiteral, never readNameOrRef (see round2.ts/round3.ts) —

package/dist/engine/feature-ast/pattern-change-schema.js

@@ -2,7 +2,7 @@
 // tool (or any external caller) hands us JSON; before it ever reaches
 // `applyChanges` it must pass through here. Every rejection carries an
 // exact dotted/bracketed path so the caller (frequently an LLM) can
-// self-correct without a human in the loop — see kumiko-framework#3137.
+// self-correct without a human in the loop.
 //
 // **Zod v4 constraint driving this file's shape:** every discriminated-
 // union member below stays a plain `z.object(...)` (or `.superRefine`

package/dist/engine/feature-ast/patterns.d.ts

@@ -258,14 +258,14 @@ export type EnvSchemaPattern = {
     readonly source: SourceLocation;
     readonly schemaBody: SourceLocation;
 };
-/** Live-editable policy defaults for an AI pipeline step instance (#256). */
+/** Live-editable policy defaults for an AI pipeline step instance. */
 export type AiStepPolicy = {
     readonly enabled: boolean;
     readonly providerId?: string;
     readonly model?: string;
     readonly params: Record<string, unknown>;
 };
-/** Preserves an unresolvable argument reference across parse → render (#998). */
+/** Preserves an unresolvable argument reference across parse → render. */
 export type AiStepOpaqueArgs = {
     readonly __raw: string;
 };

package/dist/engine/feature-ast/render.js

@@ -278,7 +278,7 @@ function renderUseExtension(p) {
     if (p.extensionNameRaw !== undefined) {
         // A raw-ref name can't be spread into the merged Object-Form without
         // losing it to renderValue's plain-string serialization — fall back
-        // to positional form, which keeps the reference verbatim (#2111).
+        // to positional form, which keeps the reference verbatim.
         const optionsArg = p.options !== undefined ? `, ${renderValue(p.options)}` : "";
         return `r.useExtension(${nameLiteral}, ${JSON.stringify(p.entityName)}${optionsArg});`;
     }
@@ -568,7 +568,7 @@ function renderMultiStreamProjection(p) {
 function renderDefineEvent(p) {
     const nameLiteral = p.eventNameRaw ?? JSON.stringify(p.eventName);
     const migrationEntries = p.migrations !== undefined ? Object.entries(p.migrations) : [];
-    // piiFields is a mandatory option (fw#2558) — the options object is
+    // piiFields is a mandatory option — the options object is
     // always rendered, unlike the old version/migrations-only shortcut.
     const lines = [`r.defineEvent(${nameLiteral}, ${p.schemaSource.raw}, {`];
     lines.push(`  piiFields: ${p.piiFields.raw},`);

package/dist/engine/feature-config-events-jobs.js

@@ -4,7 +4,7 @@ import { isValidIanaTimeZone } from "../time/iana.js";
 import { reasonProblem } from "./escape-hatch-reason.js";
 import { createEventDef } from "./event-def.js";
 import { resolveName } from "./handler-helpers.js";
-import { splitNamedDefinition, unwrapArrayForm } from "./object-form.js";
+import { requireArgument, splitNamedDefinition, unwrapArrayForm } from "./object-form.js";
 import { QnTypes, qn, toKebab } from "./qualified-name.js";
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.
 export function buildConfigEventsJobsMethods(state, name) {
@@ -49,7 +49,7 @@ export function buildConfigEventsJobsMethods(state, name) {
     }
     // Shared by defineEvent's `migrations` option — each entry registers a
     // single upcast step, same validation/dedup as the old standalone
-    // r.eventMigration() call (folded into defineEvent, #1082 step 8).
+    // r.eventMigration() call (folded into defineEvent).
     function registerEventMigration(eventName, fromVersion, toVersion, transform) {
         if (toVersion !== fromVersion + 1) {
             throw new Error(`[Feature ${name}] defineEvent("${eventName}") migrations: only single-step migrations are allowed — toVersion must be fromVersion + 1 (got ${fromVersion} -> ${toVersion}). ` +
@@ -73,8 +73,8 @@ export function buildConfigEventsJobsMethods(state, name) {
             const [jobName, jobOptions, jobHandler] = typeof jobNameOrDefinition === "string"
                 ? [
                     jobNameOrDefinition,
-                    options,
-                    handler,
+                    requireArgument(options, name, "job", "options"),
+                    requireArgument(handler, name, "job", "handler"),
                 ]
                 : (() => {
                     const { name: definedJobName, handler: h, ...rest } = jobNameOrDefinition;
@@ -97,9 +97,9 @@ export function buildConfigEventsJobsMethods(state, name) {
                         'tz must be an IANA time zone name such as "Europe/Berlin".');
                 }
             }
-            // Resolve NameOrRef(s) in trigger.on. Multi-Trigger-Form: Array
-            // wird zu Array von resolved strings, Single bleibt single string —
-            // job-runner unterscheidet anhand Array.isArray.
+            // Resolve NameOrRef(s) in trigger.on. For the multi-trigger form, arrays
+            // become arrays of resolved strings while a single value remains a string;
+            // the job runner distinguishes them with Array.isArray.
             const trigger = "on" in jobOptions.trigger
                 ? {
                     on: Array.isArray(jobOptions.trigger.on)
@@ -114,7 +114,10 @@ export function buildConfigEventsJobsMethods(state, name) {
         },
         notification(notificationNameOrDefinition, definition) {
             const [notificationName, resolvedDefinition] = typeof notificationNameOrDefinition === "string"
-                ? [notificationNameOrDefinition, definition]
+                ? [
+                    notificationNameOrDefinition,
+                    requireArgument(definition, name, "notification", "definition"),
+                ]
                 : splitNamedDefinition(notificationNameOrDefinition);
             state.notifications[notificationName] = {
                 name: notificationName,
@@ -167,7 +170,7 @@ export function buildConfigEventsJobsMethods(state, name) {
         },
         metric(shortNameOrDefinition, options) {
             const [shortName, metricOptions] = typeof shortNameOrDefinition === "string"
-                ? [shortNameOrDefinition, options]
+                ? [shortNameOrDefinition, requireArgument(options, name, "metric", "options")]
                 : splitNamedDefinition(shortNameOrDefinition);
             if (state.metrics[shortName]) {
                 throw new Error(`[Feature ${name}] Metric "${shortName}" already registered. ` +
@@ -183,7 +186,7 @@ export function buildConfigEventsJobsMethods(state, name) {
         },
         secret(shortNameOrDefinition, options) {
             const [shortName, secretOptions] = typeof shortNameOrDefinition === "string"
-                ? [shortNameOrDefinition, options]
+                ? [shortNameOrDefinition, requireArgument(options, name, "secret", "options")]
                 : splitNamedDefinition(shortNameOrDefinition);
             if (state.secretKeys[shortName]) {
                 throw new Error(`[Feature ${name}] Secret "${shortName}" already registered. ` +
@@ -208,7 +211,7 @@ export function buildConfigEventsJobsMethods(state, name) {
         },
         secretNamespace(shortNameOrDefinition, options) {
             const [shortName, namespaceOptions] = typeof shortNameOrDefinition === "string"
-                ? [shortNameOrDefinition, options]
+                ? [shortNameOrDefinition, requireArgument(options, name, "secretNamespace", "options")]
                 : splitNamedDefinition(shortNameOrDefinition);
             if (state.secretNamespaces[shortName]) {
                 throw new Error(`[Feature ${name}] Secret namespace "${shortName}" already registered. ` +
@@ -227,7 +230,7 @@ export function buildConfigEventsJobsMethods(state, name) {
                 ? shortNameOrDefinition
                 : shortNameOrDefinition.name;
             const claimType = typeof shortNameOrDefinition === "string"
-                ? options.type
+                ? requireArgument(options, name, "claimKey", "options").type
                 : shortNameOrDefinition.type;
             if (state.claimKeys[shortName]) {
                 throw new Error(`[Feature ${name}] Claim key "${shortName}" already declared. ` +

package/dist/engine/feature-entity-handlers.js

@@ -3,7 +3,7 @@ import { toTableName } from "../db/table-builder.js";
 import { isEntityConventionQueryHandler, isPagedQueryHandler, PAGED_QUERY_HANDLER_BRAND, } from "./define-handler.js";
 import { assertEscapeHatchAccessIsSystemAdminOnly, registerCrudHandlers, } from "./entity-handlers.js";
 import { resolveName } from "./handler-helpers.js";
-import { isObjectArgument, throwObjectArgumentRequired } from "./object-form.js";
+import { isObjectArgument, requireArgument, throwObjectArgumentRequired } from "./object-form.js";
 const CRUD_VERBS = new Set(["create", "update", "delete"]);
 const CRUD_REGISTERED_VERBS = new Set([...CRUD_VERBS, "restore", "list", "detail"]);
 // A silent overwrite would drop framework behaviour that rides on the r.crud
@@ -42,9 +42,9 @@ function tryMapEntity(state, name, handlerName) {
             // skip: feature-name entity match is the preferred mapping
             return;
         }
-        const entityKeys = Object.keys(state.entities);
-        if (entityKeys.length === 1) {
-            state.handlerEntityMappings[handlerName] = entityKeys[0];
+        const [onlyEntityName, ...otherEntityNames] = Object.keys(state.entities);
+        if (onlyEntityName !== undefined && otherEntityNames.length === 0) {
+            state.handlerEntityMappings[handlerName] = onlyEntityName;
         }
     }
 }
@@ -97,7 +97,11 @@ export function buildEntityHandlerMethods(state, name) {
                     const { entity, name: innerName, ...rest } = entityRefOrDefinition;
                     return [entity, innerName, rest];
                 })()
-                : [entityRefOrDefinition, relationName, definition];
+                : [
+                    entityRefOrDefinition,
+                    requireArgument(relationName, name, "relation", "relation name"),
+                    requireArgument(definition, name, "relation", "definition"),
+                ];
             const entityName = resolveName(entityRef);
             if (!state.relations[entityName])
                 state.relations[entityName] = {};

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