@cosmicdrift/kumiko-framework 0.333.0 → 0.335.0

package/dist/engine/build-config-feature-schema.js

@@ -14,6 +14,9 @@
 // des config-Features (featureName "config") gemerged — der Renderer
 // qualifiziert die kurzen ids/refs mit "config". Daher hier durchweg KURZE
 // ids/parent/screen-Refs (buildNavRegistrySliceForApp qualifiziert selbst).
+import { isOptionsQueryFieldRef } from "@cosmicdrift/kumiko-types/fields";
+import { CONFIG_EDIT_ENTITY, fieldLabelKey } from "../i18n/required-surface-keys.js";
+import { isEncryptedAtRest } from "./config-helpers.js";
 import { EXTENSION_SELECTOR_HINT_KEY, SELECTED_EXTENSIONS_QUERY, selectablePluginIds, } from "./extension-selector-plugins.js";
 import { createBooleanField, createNumberField, createSelectField, createTextField, } from "./factories.js";
 import { isKebabSegment, toKebab } from "./qualified-name.js";
@@ -35,6 +38,14 @@ const SCOPE_ICON = {
     user: "user",
 };
 const SCOPES_BROAD_TO_DEEP = ["system", "tenant", "user"];
+const audienceDescriptionKey = (scope) => `config.settings.audience.${scope}`;
+const PROVIDER_PANEL_TITLE_ENTRY = {
+    en: "Provider",
+    de: "Anbieter",
+    es: "Proveedor",
+};
+const PROVIDER_SECTION_TITLE_KEY = "config.settings.provider";
+const SAVE_PROVIDER_LABEL_KEY = "config.settings.saveProvider";
 const audienceNavShortId = (scope) => `audience-${scope}`;
 // Generated post-boot, never via r.nav() — the boot validator exempts exactly these QNs (an app references one to place the settings group inline).
 export const SETTINGS_HUB_AUDIENCE_NAV_QNS = SCOPES_BROAD_TO_DEEP.map((scope) => `${SETTINGS_HUB_FEATURE}:nav:${audienceNavShortId(scope)}`);
@@ -212,7 +223,11 @@ function assertUniquePanelIds(ownerGroup, panels) {
 function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins, ownerPanels, hub, secretsAccess) {
     const selectionScreenId = `${ownerGroup}-tenant-selection`;
     const selectionScreen = {
-        ...buildScreen(selectionScreenId, "tenant", ownerGroup, ownerKeys, ownerAccess, hub),
+        ...buildScreen(selectionScreenId, "tenant", ownerGroup, ownerKeys, ownerAccess, hub, {
+            description: EXTENSION_SELECTOR_HINT_KEY,
+            sectionTitle: PROVIDER_SECTION_TITLE_KEY,
+            submitLabel: SAVE_PROVIDER_LABEL_KEY,
+        }),
         dormant: true,
     };
     const screens = [selectionScreen];
@@ -220,10 +235,8 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
     const secretsPanels = [];
     const accessRules = [ownerAccess];
     const translations = {};
-    const titleSource = [`${ownerGroup}.settings.tenant`, `${ownerGroup}.settings`].find((key) => hub.translationsByKey.has(key));
-    const titleValues = titleSource === undefined ? undefined : hub.translationsByKey.get(titleSource);
-    if (titleValues !== undefined)
-        translations[`screen:${selectionScreenId}.title`] = titleValues;
+    translations[`screen:${selectionScreenId}.title`] = PROVIDER_PANEL_TITLE_ENTRY;
+    Object.assign(translations, providerOptionTranslations(selectionScreen, plugins, hub));
     for (const plugin of plugins) {
         const visibleWhen = {
             query: SELECTED_EXTENSIONS_QUERY,
@@ -234,7 +247,7 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
             const pluginAccess = rolesToAccess(plugin.scopedKeys.flatMap((v) => v.roles));
             const ordered = sortByMaskOrder(plugin.scopedKeys.map((v) => v.key));
             screens.push({
-                ...buildScreen(pluginTenantScreenId(plugin), "tenant", plugin.feature, ordered, pluginAccess, hub),
+                ...buildScreen(pluginTenantScreenId(plugin), "tenant", plugin.feature, ordered, pluginAccess, hub, { description: null }),
                 dormant: true,
             });
             accessRules.push(pluginAccess);
@@ -243,6 +256,7 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
                 id: `${plugin.feature}-config`,
                 screen: pluginTenantScreenId(plugin),
                 visibleWhen,
+                chromeless: true,
             });
         }
         if (plugin.secrets.length > 0) {
@@ -256,6 +270,7 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
                 id: `${plugin.feature}-secrets`,
                 screen: secretsScreenId,
                 visibleWhen,
+                chromeless: true,
             });
         }
     }
@@ -263,9 +278,9 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
     const dashboard = {
         id: `${ownerGroup}-tenant`,
         type: "dashboard",
-        description: EXTENSION_SELECTOR_HINT_KEY,
+        showUpdatedAt: false,
         panels: assertUniquePanelIds(ownerGroup, [
-            { kind: "screen", id: "selection", screen: selectionScreenId },
+            { kind: "screen", id: "selection", screen: selectionScreenId, chromeless: true },
             ...ownerPanels,
             ...configPanels,
             ...secretsPanels,
@@ -479,10 +494,12 @@ function buildSettingsWorkspace(navs) {
         navMembers,
     };
 }
-function buildScreen(shortId, scope, feature, keys, access, hub) {
+function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
     const configKeys = {};
     const fields = {};
     const fieldLabels = {};
+    const fieldDescriptions = {};
+    const requiredFields = [];
     // Field id collapses to the plain shortKey when the key stays in its own
     // feature's group (100% of today's apps — byte-identical output). Only a
     // cross-feature `group` (feature !== ownerFeature) needs the owner prefix,
@@ -497,18 +514,16 @@ function buildScreen(shortId, scope, feature, keys, access, hub) {
         }
         seenFieldIds.set(id, k.qn);
         configKeys[id] = k.qn;
-        fields[id] = deriveField(k.def, hub.selectorOptions.get(k.qn));
+        fields[id] = deriveField(k, hub.selectorOptions.get(k.qn), keys, fieldId);
         // mask is the visibility gate, so collectMaskedKeys guarantees it here.
         if (k.def.mask)
             fieldLabels[id] = k.def.mask.title;
+        if (k.def.mask?.description !== undefined)
+            fieldDescriptions[id] = k.def.mask.description;
+        if (k.def.required === true)
+            requiredFields.push(id);
     }
-    // translate() echoes an undeclared key, so an ungated description would render raw.
-    const descriptionKey = `${feature}.settings.description`;
-    const section = {
-        title: `${feature}.settings`,
-        ...(hub.declaredTranslationKeys.has(descriptionKey) && { description: descriptionKey }),
-        fields: keys.map(fieldId),
-    };
+    const { section, screenDescription } = buildSettingsSection(feature, scope, keys.map(fieldId), hub, options);
     return {
         id: shortId,
         type: "configEdit",
@@ -516,16 +531,79 @@ function buildScreen(shortId, scope, feature, keys, access, hub) {
         configKeys,
         fields,
         fieldLabels,
-        layout: { sections: [section], width: "full" },
+        ...(Object.keys(fieldDescriptions).length > 0 && { fieldDescriptions }),
+        ...(requiredFields.length > 0 && { requiredFields }),
+        ...(screenDescription !== undefined && { description: screenDescription }),
+        ...(options.submitLabel !== undefined && { submitLabel: options.submitLabel }),
+        layout: { sections: [section], width: "full", variant: "settings-list" },
         access,
     };
 }
-function deriveField(def, selectorPluginIds) {
+// `{ field: <shortKey> }` names another key of the owner feature; on the form it
+// has to point at that key's generated field id, so it must sit on the same mask.
+function rewriteOptionsQueryFieldRefs(key, payload, screenKeys, fieldIdOf) {
+    return Object.fromEntries(Object.entries(payload).map(([name, value]) => {
+        if (!isOptionsQueryFieldRef(value))
+            return [name, value];
+        const target = screenKeys.find((k) => k.ownerFeature === key.ownerFeature && k.shortKey === toKebab(value.field));
+        if (target === undefined) {
+            throw new Error(`[Settings-Hub] config key "${key.qn}" optionsQueryPayload "${name}" references key "${value.field}", which is not on the same generated settings screen (group "${key.feature}") — give both keys the same group, scope and a mask.`);
+        }
+        return [name, { field: fieldIdOf(target) }];
+    }));
+}
+function buildSettingsSection(feature, scope, fieldIds, hub, options) {
+    // translate() echoes an undeclared key, so an ungated description would render raw.
+    const descriptionKey = `${feature}.settings.description`;
+    const featureDescription = hub.declaredTranslationKeys.has(descriptionKey)
+        ? descriptionKey
+        : undefined;
+    const audienceDescription = options.description === null
+        ? undefined
+        : (options.description ?? audienceDescriptionKey(scope));
+    // The section's header column holds one sentence: the feature's own, else the
+    // audience one. When both exist the audience sentence stays on the screen.
+    const sectionDescription = featureDescription ?? audienceDescription;
+    const screenDescription = featureDescription !== undefined ? audienceDescription : undefined;
+    // A feature whose page title equals its `<feature>.settings` label would have
+    // the section heading dropped as a duplicate; `.settings.section` lets it
+    // declare a distinct heading.
+    const sectionKey = `${feature}.settings.section`;
+    const section = {
+        title: options.sectionTitle ??
+            (hub.declaredTranslationKeys.has(sectionKey) ? sectionKey : `${feature}.settings`),
+        ...(sectionDescription !== undefined && { description: sectionDescription }),
+        fields: fieldIds,
+    };
+    return { section, screenDescription };
+}
+// Option labels of the provider select: each plugin feature's `<feature>.settings`
+// copy, under the option-label key the configEdit renderer already derives.
+function providerOptionTranslations(selectionScreen, plugins, hub) {
+    const out = {};
+    for (const [fieldId, qn] of Object.entries(selectionScreen.configKeys)) {
+        if (!hub.selectorOptions.has(qn))
+            continue;
+        for (const plugin of plugins) {
+            const label = hub.translationsByKey.get(`${plugin.feature}.settings`);
+            if (label === undefined)
+                continue;
+            const key = `${fieldLabelKey(SETTINGS_HUB_FEATURE, CONFIG_EDIT_ENTITY, fieldId)}:option:${plugin.pluginId}`;
+            out[key] = label;
+        }
+    }
+    return out;
+}
+function deriveField(key, selectorPluginIds, screenKeys, fieldIdOf) {
+    const def = key.def;
     if (selectorPluginIds !== undefined)
         return createSelectField({ options: selectorPluginIds });
     switch (def.type) {
         case "number":
-            return createNumberField();
+            return createNumberField({
+                ...(def.bounds?.min !== undefined && { min: def.bounds.min }),
+                ...(def.bounds?.max !== undefined && { max: def.bounds.max }),
+            });
         case "boolean":
             return createBooleanField();
         case "select":
@@ -534,7 +612,7 @@ function deriveField(def, selectorPluginIds) {
                     options: [],
                     optionsQuery: def.optionsQuery,
                     ...(def.optionsQueryPayload !== undefined && {
-                        optionsQueryPayload: def.optionsQueryPayload,
+                        optionsQueryPayload: rewriteOptionsQueryFieldRefs(key, def.optionsQueryPayload, screenKeys, fieldIdOf),
                     }),
                 });
             }
@@ -542,7 +620,13 @@ function deriveField(def, selectorPluginIds) {
                 ? createSelectField({ options: def.options })
                 : createTextField({ personal: false, reason: "system_metadata" });
         default:
-            return createTextField({ personal: false, reason: "system_metadata" });
+            // A stored secret never goes back to the client: the form shows set/empty
+            // and sends only a replacement or a clear.
+            return createTextField({
+                personal: false,
+                reason: "system_metadata",
+                ...(def.type === "text" && isEncryptedAtRest(def) && { writeOnly: true }),
+            });
     }
 }
 function collectMaskedKeys(registry) {

package/dist/engine/changeset-changes.js

@@ -54,25 +54,35 @@ function parseBlock(raw, source) {
 function proseWithoutMetadata(markdown) {
     const withoutFrontmatter = markdown.replace(/^\s*---\n[\s\S]*?\n---\s*/, "");
     return withoutFrontmatter
-        .replace(BLOCK_RE, "")
         .split("\n")
         .map((line) => line.trim())
         .filter((line) => line !== "");
 }
+function sameTitle(title, line) {
+    const normalize = (text) => text.replace(/[.\s]+$/, "").toLowerCase();
+    return line !== undefined && normalize(title) === normalize(line);
+}
+// BLOCK_RE closes at the first line starting with "-->"; text after it on
+// that line means a field value contained one and the block ended early.
+function assertBlockNotClosedEarly(markdown, match, source) {
+    const restOfLine = markdown.slice(match.index + match[0].length).split("\n", 1)[0] ?? "";
+    if (restOfLine.trim() !== "") {
+        throw new Error(`${source}: kumiko-changes block closed early by a line starting with "-->"; field values must not contain such a line`);
+    }
+}
 /** Parse structured upgrade metadata embedded in a Changeset body. */
 export function parseChangesetChanges(markdown, source) {
     const changes = [];
-    const prose = proseWithoutMetadata(markdown);
+    // Each block only inherits prose from the markdown between the previous block
+    // and itself; document-wide prose would give two features the same title.
+    let segmentStart = 0;
     BLOCK_RE.lastIndex = 0;
     let match = BLOCK_RE.exec(markdown);
     while (match !== null) {
         const block = match[1];
-        // BLOCK_RE closes at the first line starting with "-->"; text after it on
-        // that line means a field value contained one and the block ended early.
-        const restOfLine = markdown.slice(match.index + match[0].length).split("\n", 1)[0] ?? "";
-        if (restOfLine.trim() !== "") {
-            throw new Error(`${source}: kumiko-changes block closed early by a line starting with "-->"; field values must not contain such a line`);
-        }
+        const prose = proseWithoutMetadata(markdown.slice(segmentStart, match.index));
+        segmentStart = match.index + match[0].length;
+        assertBlockNotClosedEarly(markdown, match, source);
         if (!block)
             throw new Error(`${source}: empty kumiko-changes block`);
         const fields = parseBlock(block, source);
@@ -81,12 +91,16 @@ export function parseChangesetChanges(markdown, source) {
         if (!TYPE_VALUES.has(rawType)) {
             throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
         }
-        const title = fields.get("title")?.trim() || prose[0];
+        const explicitTitle = fields.get("title")?.trim();
+        const title = explicitTitle || prose[0];
         if (!title)
             throw new Error(`${source}: kumiko-changes title is required`);
+        // The first prose line is the title's source only when no title was given or
+        // the explicit one restates it; otherwise it is genuine detail.
+        const firstLineIsTitle = !explicitTitle || sameTitle(explicitTitle, prose[0]);
         const detail = fields.get("detail")?.trim() ||
             prose
-                .slice(prose.length > 0 ? 1 : 0)
+                .slice(firstLineIsTitle ? 1 : 0)
                 .join("\n")
                 .trim();
         const migration = fields.get("migration")?.trim();

package/dist/engine/config-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions } from "./types/index.js";
+import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, OptionsQueryPayload } from "./types/index.js";
 export declare function isEncryptedAtRest(def: Pick<ConfigKeyDefinition, "encrypted" | "backing">): boolean;
 export declare const access: {
     readonly all: readonly string[];
@@ -19,7 +19,7 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
     piiEncrypted?: T extends "text" ? boolean : never;
     options?: readonly string[];
     optionsQuery?: T extends "select" ? string : never;
-    optionsQueryPayload?: T extends "select" ? Readonly<Record<string, string | number | boolean>> : never;
+    optionsQueryPayload?: T extends "select" ? OptionsQueryPayload : never;
     bounds?: T extends "number" ? ConfigBounds : never;
     pattern?: T extends "text" ? {
         regex: string;

package/dist/engine/entity-handlers.js

@@ -7,6 +7,7 @@ import { acknowledgeConventionCrossTenant } from "../db/tenant-db.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
+import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder.js";
 // Convention-based handler factories for event-sourced aggregates.
@@ -233,7 +234,7 @@ export function defineEntityWriteHandler(name, entity, options) {
                 // present that identity, so their payload.id is dropped exactly as
                 // before this field became part of the schema.
                 const { id: _callerId, ...payloadWithoutId } = event.payload;
-                const payload = isSystemIdentity(event.user) ? event.payload : payloadWithoutId;
+                const payload = dropEmptyWriteOnlyValues(entity, isSystemIdentity(event.user) ? event.payload : payloadWithoutId);
                 return executor.create(payload, event.user, dbFor(ctx), {
                     preSave: runPreSave &&
                         ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
@@ -249,7 +250,11 @@ export function defineEntityWriteHandler(name, entity, options) {
             handler = async (event, ctx) => {
                 const { runPreSave } = ctx;
                 const db = dbFor(ctx);
-                const payload = event.payload; // @cast-boundary engine-payload
+                const submitted = event.payload; // @cast-boundary engine-payload
+                const payload = {
+                    ...submitted,
+                    changes: dropEmptyWriteOnlyValues(entity, submitted.changes),
+                };
                 const user = await actingUserFor(event.user, payload.id, db);
                 // skipUnchanged (#464): API-driven updates diff against the stored
                 // row so a resubmitted-but-identical field doesn't force a fresh

package/dist/engine/feature-ast/extractors/events.js

@@ -61,6 +61,12 @@ function extractEventMigrationsField(node, sourceFile) {
             : undefined;
     return result && Object.keys(result).length > 0 ? result : undefined;
 }
+// `{ piiFields }` shorthand is a valid stance; its name node doubles as the location.
+function readPiiFieldsNode(obj) {
+    const prop = obj?.getProperty("piiFields");
+    return (prop?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer() ??
+        prop?.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getNameNode());
+}
 export function extractDefineEvent(call, sourceFile) {
     const args = call.getArguments();
     const first = args[0];
@@ -94,10 +100,7 @@ export function extractDefineEvent(call, sourceFile) {
             if (typeof v === "number")
                 version = v;
         }
-        const piiFieldsInit = obj
-            .getProperty("piiFields")
-            ?.asKind(SyntaxKind.PropertyAssignment)
-            ?.getInitializer();
+        const piiFieldsInit = readPiiFieldsNode(obj);
         if (!piiFieldsInit) {
             return fail("defineEvent", sourceLocationFromNode(call, sourceFile), 'requires an explicit `piiFields` stance (an object literal or "none")');
         }
@@ -130,11 +133,11 @@ export function extractDefineEvent(call, sourceFile) {
     let migrations;
     const optionsArg = args[2];
     const optionsObj = optionsArg?.asKind(SyntaxKind.ObjectLiteralExpression);
-    const piiFieldsInit = optionsObj
-        ?.getProperty("piiFields")
-        ?.asKind(SyntaxKind.PropertyAssignment)
-        ?.getInitializer();
+    const piiFieldsInit = readPiiFieldsNode(optionsObj);
     if (!piiFieldsInit) {
+        if (optionsArg && !optionsObj) {
+            return fail("defineEvent", sourceLocationFromNode(call, sourceFile), "options must be an object literal");
+        }
         return fail("defineEvent", sourceLocationFromNode(call, sourceFile), 'requires an explicit `piiFields` stance (an object literal or "none")');
     }
     if (optionsObj) {

package/dist/engine/feature-ast/extractors/handlers.js

@@ -62,6 +62,28 @@ const HANDLER_KEY_KINDS = {
 function lookupClassification(map, key) {
     return key in map ? map[key] : undefined;
 }
+function isStaticStringNode(node) {
+    const kind = node.getKind();
+    return kind === SyntaxKind.StringLiteral || kind === SyntaxKind.NoSubstitutionTemplateLiteral;
+}
+function isBooleanLiteralNode(node) {
+    const kind = node.getKind();
+    return kind === SyntaxKind.TrueKeyword || kind === SyntaxKind.FalseKeyword;
+}
+// The literal readers below only understand a static string `description` and
+// a true/false `unsafeSkipTransitionGuard`; any other value shape is lossy.
+function hasUnreadableLiteralValue(key, initializer) {
+    if (key === "description")
+        return !(initializer && isStaticStringNode(initializer));
+    if (key === "unsafeSkipTransitionGuard")
+        return !(initializer && isBooleanLiteralNode(initializer));
+    return false;
+}
+function readStaticStringProperty(obj, key) {
+    const initializer = obj.getProperty(key)?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer();
+    return (initializer?.asKind(SyntaxKind.StringLiteral) ??
+        initializer?.asKind(SyntaxKind.NoSubstitutionTemplateLiteral))?.getLiteralValue();
+}
 // True when the call's object body/options carry a shape the extractor
 // cannot losslessly model property-by-property (a spread, a method/accessor
 // shorthand, a computed key, or a key outside the classification map above).
@@ -76,13 +98,21 @@ function hasUnmodeledShape(obj, methodName) {
         if (propAssign) {
             if (propAssign.getNameNode().getKind() === SyntaxKind.ComputedPropertyName)
                 return true;
-            if (lookupClassification(keyKinds, readPropertyKey(propAssign)) !== "modeled")
+            const key = readPropertyKey(propAssign);
+            if (lookupClassification(keyKinds, key) !== "modeled")
+                return true;
+            const initializer = propAssign.getInitializer();
+            if (hasUnreadableLiteralValue(key, initializer))
                 return true;
             continue;
         }
         const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
         if (shorthand) {
-            if (lookupClassification(keyKinds, shorthand.getName()) !== "modeled")
+            const key = shorthand.getName();
+            if (lookupClassification(keyKinds, key) !== "modeled")
+                return true;
+            // A shorthand's value is invisible to the literal readers below.
+            if (key === "description" || key === "unsafeSkipTransitionGuard")
                 return true;
             continue;
         }
@@ -197,11 +227,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
         const headerResult = readHandlerHeaderFields(obj, methodName, sourceFile);
         if (headerResult.kind === "error")
             return headerResult;
-        const descriptionLiteral = obj
-            .getProperty("description")
-            ?.asKind(SyntaxKind.PropertyAssignment)
-            ?.getInitializer()
-            ?.asKind(SyntaxKind.StringLiteral);
+        const description = readStaticStringProperty(obj, "description");
         const skip = readBooleanProperty(obj, "unsafeSkipTransitionGuard");
         return ok({
             source: sourceLocationFromNode(call, sourceFile),
@@ -209,9 +235,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
             schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
             handlerBody: sourceLocationFromNode(fn, sourceFile),
             ...headerResult.pattern,
-            ...(descriptionLiteral !== undefined && {
-                description: descriptionLiteral.getLiteralValue(),
-            }),
+            ...(description !== undefined && { description }),
             ...(skip === true && { unsafeSkipTransitionGuard: true }),
         });
     }
@@ -244,6 +268,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
     const optionsArg = args[3];
     let headerFields = {};
     let description;
+    let skipTransitionGuard;
     if (optionsArg) {
         const optionsObj = unwrapObjectLiteral(optionsArg);
         if (!optionsObj || hasUnmodeledShape(optionsObj, methodName)) {
@@ -253,12 +278,8 @@ export function parseHandlerCall(call, sourceFile, methodName) {
         if (headerResult.kind === "error")
             return headerResult;
         headerFields = headerResult.pattern;
-        description = optionsObj
-            .getProperty("description")
-            ?.asKind(SyntaxKind.PropertyAssignment)
-            ?.getInitializer()
-            ?.asKind(SyntaxKind.StringLiteral)
-            ?.getLiteralValue();
+        description = readStaticStringProperty(optionsObj, "description");
+        skipTransitionGuard = readBooleanProperty(optionsObj, "unsafeSkipTransitionGuard");
     }
     return ok({
         source: sourceLocationFromNode(call, sourceFile),
@@ -267,6 +288,7 @@ export function parseHandlerCall(call, sourceFile, methodName) {
         handlerBody: sourceLocationFromNode(fn, sourceFile),
         ...headerFields,
         ...(description !== undefined && { description }),
+        ...(skipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
     });
 }
 export function extractWriteHandler(call, sourceFile) {

package/dist/engine/feature-ast/extractors/resolve-import.d.ts

@@ -1,4 +1,5 @@
-import type { Node, SourceFile, VariableDeclaration } from "ts-morph";
+import type { SourceFile, VariableDeclaration } from "ts-morph";
+import { Node } from "ts-morph";
 export declare function resolveModuleFile(fromFile: SourceFile, specifier: string): SourceFile | undefined;
 export declare function findImportBindingForLocalName(sourceFile: SourceFile, localName: string): {
     readonly moduleSpecifier: string;
@@ -10,5 +11,9 @@ export declare function findImportBindingForLocalName(sourceFile: SourceFile, lo
  * the cycle guard; `depth` backstops pathological non-cyclic chains.
  */
 export declare function resolveExportedVariable(file: SourceFile, exportedName: string, visited?: Set<string>, depth?: number): VariableDeclaration | undefined;
-/** A function parameter of the same name shadows and stops the search — it has no statically readable initializer. */
+/**
+ * Any binding of the same name that is not a plain `const NAME = <init>`
+ * (parameter, destructuring, loop variable, catch variable) shadows and ends
+ * the search — it has no statically readable initializer.
+ */
 export declare function findScopedVariableDeclaration(identifier: Node, name: string): VariableDeclaration | undefined;

package/dist/engine/feature-ast/extractors/resolve-import.js

@@ -1,4 +1,4 @@
-import { SyntaxKind, ts } from "ts-morph";
+import { Node, SyntaxKind, ts } from "ts-morph";
 const MODULE_RESOLUTION_OPTIONS = {
     moduleResolution: ts.ModuleResolutionKind.Bundler,
     module: ts.ModuleKind.ESNext,
@@ -112,11 +112,14 @@ function resolveViaStarExport(file, exportedName, visited, depth) {
     }
     return undefined;
 }
-/** A function parameter of the same name shadows and stops the search — it has no statically readable initializer. */
+/**
+ * Any binding of the same name that is not a plain `const NAME = <init>`
+ * (parameter, destructuring, loop variable, catch variable) shadows and ends
+ * the search — it has no statically readable initializer.
+ */
 export function findScopedVariableDeclaration(identifier, name) {
     for (const ancestor of [identifier, ...identifier.getAncestors()]) {
-        const params = getShadowingParameters(ancestor);
-        if (params?.some((p) => p.getName() === name))
+        if (declaresShadowingBinding(ancestor, name))
             return undefined;
         const statements = getDirectStatements(ancestor);
         if (!statements)
@@ -125,21 +128,45 @@ export function findScopedVariableDeclaration(identifier, name) {
             const varStmt = stmt.asKind(SyntaxKind.VariableStatement);
             if (!varStmt)
                 continue;
-            const decl = varStmt
-                .getDeclarationList()
-                .getDeclarations()
-                .find((d) => d.getName() === name);
-            if (decl)
-                return decl;
+            for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+                const nameNode = decl.getNameNode();
+                if (Node.isIdentifier(nameNode)) {
+                    if (nameNode.getText() === name)
+                        return decl;
+                }
+                else if (bindingNames(nameNode).includes(name)) {
+                    return undefined;
+                }
+            }
         }
     }
     return undefined;
 }
-function getShadowingParameters(node) {
-    const fn = node.asKind(SyntaxKind.ArrowFunction) ??
-        node.asKind(SyntaxKind.FunctionExpression) ??
-        node.asKind(SyntaxKind.FunctionDeclaration);
-    return fn?.getParameters();
+function bindingNames(nameNode) {
+    if (Node.isIdentifier(nameNode))
+        return [nameNode.getText()];
+    if (Node.isObjectBindingPattern(nameNode) || Node.isArrayBindingPattern(nameNode)) {
+        return nameNode
+            .getElements()
+            .flatMap((element) => Node.isBindingElement(element) ? bindingNames(element.getNameNode()) : []);
+    }
+    return [];
+}
+function declaresShadowingBinding(node, name) {
+    if (Node.isParametered(node)) {
+        return node.getParameters().some((p) => bindingNames(p.getNameNode()).includes(name));
+    }
+    if (Node.isForOfStatement(node) || Node.isForInStatement(node) || Node.isForStatement(node)) {
+        const initializer = node.getInitializer();
+        return (initializer !== undefined &&
+            Node.isVariableDeclarationList(initializer) &&
+            initializer.getDeclarations().some((decl) => bindingNames(decl.getNameNode()).includes(name)));
+    }
+    if (Node.isCatchClause(node)) {
+        const decl = node.getVariableDeclaration();
+        return decl !== undefined && bindingNames(decl.getNameNode()).includes(name);
+    }
+    return false;
 }
 function getDirectStatements(node) {
     const block = node.asKind(SyntaxKind.Block);

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

@@ -28,3 +28,4 @@ export declare function parseFeatureFile(filePath: string): ParseResult;
  * instance and avoids re-IO per parse).
  */
 export declare function parseSourceFile(sourceFile: SourceFile): ParseResult;
+export declare function relativePosixPath(fromDirectory: string, filePath: string): string;

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

@@ -68,16 +68,31 @@ export function parseSourceFile(sourceFile) {
     const errors = [];
     walkSetupCallback(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
     walkAiStepCalls(setupCallback.getBody(), registrarParamName, sourceFile, patterns, errors);
-    // Tie-break on filePath so cross-file registrar wrappers don't interleave by
-    // foreign line numbers alone.
+    // Tie-break on the path relative to the entry file's directory so cross-file
+    // registrar wrappers don't interleave by foreign line numbers alone, without
+    // the order depending on where the repo is checked out (worktrees).
+    const parseRoot = sourceFile.getDirectoryPath();
     patterns.sort((a, b) => {
-        const fileCmp = a.source.file.localeCompare(b.source.file);
+        const fileCmp = relativePosixPath(parseRoot, a.source.file).localeCompare(relativePosixPath(parseRoot, b.source.file));
         if (fileCmp !== 0)
             return fileCmp;
         return a.source.start.line - b.source.start.line;
     });
     return { featureName, patterns, errors };
 }
+// node:path is avoided: the Designer runs this against an in-memory file
+// system outside Node. ts-morph paths are always posix-style.
+export function relativePosixPath(fromDirectory, filePath) {
+    const fromSegments = fromDirectory.split("/").filter(Boolean);
+    const fileSegments = filePath.split("/").filter(Boolean);
+    let common = 0;
+    while (common < fromSegments.length &&
+        common < fileSegments.length - 1 &&
+        fromSegments[common] === fileSegments[common]) {
+        common += 1;
+    }
+    return [...fromSegments.slice(common).map(() => ".."), ...fileSegments.slice(common)].join("/");
+}
 // =============================================================================
 // Internal — locate defineFeature + setup callback
 // =============================================================================