@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

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

@@ -0,0 +1,582 @@
+// Self-Populating Settings-Hub (config-provisioning Phase 2).
+//
+// Leitet aus den im Registry deklarierten Config-Keys automatisch die
+// Settings-UI ab: pro Audience (scope) einen Parent-Nav, pro (Feature ×
+// scope) einen configEdit-Screen + Child-Nav darunter. Kein manuelles
+// r.screen/r.nav am App-Author.
+//
+// Sichtbar wird nur ein Key MIT `mask` (siehe ConfigKeyDefinition): mask ist
+// die per-Key-Intent „user-facing Einstellung" und trägt zugleich das Label
+// (mask.title, ein i18n-Key). Keys ohne mask sind internes Plumbing
+// (ENV-provisioniert/computed) und erscheinen nicht.
+//
+// Die erzeugten Screens/Navs werden von buildAppSchema in die FeatureSchema
+// 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 { 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";
+import { isOpenToAllGranted } from "./types/handlers.js";
+// Namespace, unter dem buildAppSchema die generierten Screens/Navs einhängt
+// (find-or-create FeatureSchema). MUSS gleich CONFIG_FEATURE aus dem config
+// bundled-feature sein — framework kann das const nicht importieren (Richtung
+// bundled-features → framework), darum hier gepinnt + Pin-Test bundled-seitig.
+export const SETTINGS_HUB_FEATURE = "config";
+// Eigene Workspace nur für workspace-mode-Apps (siehe buildAppSchema): Settings
+// erscheinen als eigener Switcher-Eintrag, statt die kuratierten App-Workspaces
+// zu verschmutzen. Apps ohne Workspaces zeigen die Navs über den no-filter-Pfad.
+export const SETTINGS_HUB_WORKSPACE = "settings";
+// Audience-Reihenfolge im Sidebar: Plattform vor Tenant vor Benutzer.
+const SCOPE_ORDER = { system: 10, tenant: 20, user: 30 };
+const SCOPE_ICON = {
+    system: "shield",
+    tenant: "building",
+    user: "user",
+};
+const SCOPES_BROAD_TO_DEEP = ["system", "tenant", "user"];
+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)}`);
+// An einem Scope BREITER als der Home-Scope eines Keys darf nur eine für DIESE
+// Ebene privilegierte Rolle den (Cascade-)Default setzen — SystemAdmin auf
+// system, TenantAdmin/Admin auf tenant. Am Home-Scope gilt das volle write-Set
+// (unverändertes Verhalten). So liefert ein tenant-Home-Key wie SMTP zusätzlich
+// einen SystemAdmin-only Plattform-Screen; ein Key, dessen write-Set keine
+// dieser Rollen nennt, bekommt keinen breiteren Screen (write-Set = opt-in).
+const ELEVATED_ROLES = {
+    system: ["SystemAdmin"],
+    tenant: ["TenantAdmin", "Admin"],
+    user: [],
+};
+// Der interne Maschinen-Akteur (access.system). Ein Key, den NUR diese Rolle
+// schreiben darf, ist provisioned-not-user-facing: er gehört nicht in den
+// menschlichen Hub (sonst rendert ein Feld, das der sichtbare Mensch nicht
+// speichern kann). `as const` für Literal-Verengung am Vergleich.
+const MACHINE_WRITE_ROLE = "system";
+const NO_SELECTOR_GATING = {
+    pluginsByOwnerGroup: new Map(),
+    pluginFeatures: new Set(),
+    secretQns: new Set(),
+};
+// Verbatim (unprefixed) keys as the client sees them — NOT getAllTranslations()
+// (server-merged, "feature:"-prefixed, see build-app-schema.ts:77-81).
+function collectDeclaredTranslations(registry) {
+    const declared = new Map();
+    for (const f of registry.features.values()) {
+        for (const [key, values] of Object.entries(f.translations ?? {})) {
+            if (!declared.has(key))
+                declared.set(key, values);
+        }
+    }
+    return declared;
+}
+function collectSelectorOptions(registry) {
+    const options = new Map();
+    for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {
+        const pluginIds = selectablePluginIds(registry, extensionName);
+        if (pluginIds.length > 0)
+            options.set(selectorKey, pluginIds);
+    }
+    return options;
+}
+function collectVisibleSelectorOwners(registry, visible) {
+    const ownerGroupByExtension = new Map();
+    const selectorFeatures = new Set();
+    for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {
+        const selector = visible.find((v) => v.key.qn === selectorKey);
+        if (selector === undefined)
+            continue;
+        ownerGroupByExtension.set(extensionName, selector.key.feature);
+        selectorFeatures.add(selector.key.feature);
+        selectorFeatures.add(selector.key.ownerFeature);
+    }
+    return { ownerGroupByExtension, selectorFeatures };
+}
+function countSelectorUsagesByFeature(registry) {
+    const usageCountByFeature = new Map();
+    for (const [extensionName] of registry.getAllExtensionSelectors()) {
+        for (const usage of registry.getExtensionUsages(extensionName)) {
+            if (usage.featureName === undefined)
+                continue;
+            const feature = toKebab(usage.featureName);
+            usageCountByFeature.set(feature, (usageCountByFeature.get(feature) ?? 0) + 1);
+        }
+    }
+    return usageCountByFeature;
+}
+// A plugin feature with several selector-gated registrations can't sit under one
+// selector's panel, so it stays ungated (own nav, secrets in the global screen).
+function planSelectorGating(registry, visible, declaredSecrets, secretsEnabled) {
+    const { ownerGroupByExtension, selectorFeatures } = collectVisibleSelectorOwners(registry, visible);
+    if (ownerGroupByExtension.size === 0)
+        return NO_SELECTOR_GATING;
+    const usageCountByFeature = countSelectorUsagesByFeature(registry);
+    const pluginsByOwnerGroup = new Map();
+    const pluginFeatures = new Set();
+    const secretQns = new Set();
+    for (const [extension, ownerGroup] of [...ownerGroupByExtension].sort(([a], [b]) => a.localeCompare(b))) {
+        const usages = [...registry.getExtensionUsages(extension)].sort((a, b) => (a.featureName ?? "").localeCompare(b.featureName ?? ""));
+        for (const usage of usages) {
+            if (usage.featureName === undefined)
+                continue;
+            const feature = toKebab(usage.featureName);
+            if (usageCountByFeature.get(feature) !== 1 || selectorFeatures.has(feature))
+                continue;
+            const scopedKeys = visible.filter((v) => v.key.ownerFeature === feature);
+            const secrets = secretsEnabled ? declaredSecrets.filter((s) => s.feature === feature) : [];
+            if (scopedKeys.length === 0 && secrets.length === 0)
+                continue;
+            const plugins = pluginsByOwnerGroup.get(ownerGroup) ?? [];
+            plugins.push({ feature, extension, pluginId: usage.entityName, scopedKeys, secrets });
+            pluginsByOwnerGroup.set(ownerGroup, plugins);
+            pluginFeatures.add(feature);
+            for (const s of secrets)
+                secretQns.add(s.qn);
+        }
+    }
+    return { pluginsByOwnerGroup, pluginFeatures, secretQns };
+}
+// A tenant/user-home key with an elevated write role (SystemAdmin on a
+// tenant key, see ELEVATED_ROLES) surfaces the SAME feature under two
+// audience navs (cascade-default screen + home screen) — both would
+// otherwise carry the identical `${feature}.settings` label. Opt-in
+// scoped override (`${feature}.settings.${scope}`) disambiguates only
+// where a feature actually declares one; every single-scope feature
+// keeps the plain key unchanged.
+function buildFeatureNav(scope, feature, ordered, access, declaredTranslationKeys) {
+    const shortId = `${feature}-${scope}`;
+    const scopedLabel = `${feature}.settings.${scope}`;
+    return {
+        id: shortId,
+        label: declaredTranslationKeys.has(scopedLabel) ? scopedLabel : `${feature}.settings`,
+        parent: audienceNavShortId(scope),
+        screen: shortId,
+        icon: ordered[0]?.def.mask?.icon ?? "settings",
+        order: minMaskOrder(ordered),
+        access,
+    };
+}
+// One configEdit screen + child-nav per feature; a tenant-scope selector owner
+// becomes a dashboard instead and its gated plugins get no entries of their own.
+function buildFeatureScreensAndNavs(scope, visible, hub, gating, secretsAccess) {
+    const out = { screens: [], navs: [], translations: {} };
+    const ungated = visible.filter((v) => !gating.pluginFeatures.has(v.key.ownerFeature));
+    for (const feature of featuresPresent(ungated.map((v) => v.key))) {
+        const group = ungated.filter((v) => v.key.feature === feature);
+        const ordered = sortByMaskOrder(group.map((v) => v.key));
+        const access = rolesToAccess(group.flatMap((v) => v.roles));
+        const shortId = `${feature}-${scope}`;
+        const plugins = scope === "tenant" ? gating.pluginsByOwnerGroup.get(feature) : undefined;
+        if (plugins === undefined) {
+            out.screens.push(buildScreen(shortId, scope, feature, ordered, access, hub));
+            out.navs.push(buildFeatureNav(scope, feature, ordered, access, hub.declaredTranslationKeys));
+            continue;
+        }
+        const ownerHub = buildSelectorOwnerDashboard(feature, ordered, access, plugins, hub, secretsAccess);
+        out.screens.push(...ownerHub.screens);
+        out.navs.push(buildFeatureNav(scope, feature, ordered, ownerHub.access, hub.declaredTranslationKeys));
+        Object.assign(out.translations, ownerHub.translations);
+    }
+    return out;
+}
+function pluginTenantScreenId(plugin) {
+    return `${plugin.feature}-tenant`;
+}
+// Plugin screens keep their `${F}-tenant` ids so consumer title keys stay valid;
+// they are dormant because only this dashboard embeds them.
+function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins, hub, secretsAccess) {
+    const selectionScreenId = `${ownerGroup}-tenant-selection`;
+    const selectionScreen = {
+        ...buildScreen(selectionScreenId, "tenant", ownerGroup, ownerKeys, ownerAccess, hub),
+        dormant: true,
+    };
+    const screens = [selectionScreen];
+    const configPanels = [];
+    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;
+    for (const plugin of plugins) {
+        const visibleWhen = {
+            query: SELECTED_EXTENSIONS_QUERY,
+            field: plugin.extension,
+            eq: plugin.pluginId,
+        };
+        if (plugin.scopedKeys.length > 0) {
+            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),
+                dormant: true,
+            });
+            accessRules.push(pluginAccess);
+            configPanels.push({
+                kind: "screen",
+                id: `${plugin.feature}-config`,
+                screen: pluginTenantScreenId(plugin),
+                visibleWhen,
+            });
+        }
+        if (plugin.secrets.length > 0) {
+            const secretsScreenId = `${plugin.feature}-tenant-secrets`;
+            const generated = buildSecretsEditScreen(secretsScreenId, plugin.secrets, secretsAccess, hub.declaredTranslationKeys);
+            screens.push({ ...generated.screen, dormant: true });
+            Object.assign(translations, generated.translations);
+            accessRules.push(secretsAccess);
+            secretsPanels.push({
+                kind: "screen",
+                id: `${plugin.feature}-secrets`,
+                screen: secretsScreenId,
+                visibleWhen,
+            });
+        }
+    }
+    const access = unionAccessRules(accessRules);
+    const dashboard = {
+        id: `${ownerGroup}-tenant`,
+        type: "dashboard",
+        description: EXTENSION_SELECTOR_HINT_KEY,
+        panels: [
+            { kind: "screen", id: "selection", screen: selectionScreenId },
+            ...configPanels,
+            ...secretsPanels,
+        ],
+        access,
+    };
+    return { screens: [dashboard, ...screens], access, translations };
+}
+// Everything generated for one audience scope: the audience-parent nav, the
+// per-feature configEdit screens+navs, and (tenant-scope only, when secrets
+// are enabled) the secrets screen. Null when nothing is visible at this scope.
+function buildScopeResult(scope, masked, secretsEnabled, secretsWriteHandler, declaredSecrets, hub, registry) {
+    const visible = scopedKeysAt(masked, scope);
+    // Secrets attach to the tenant-audience nav regardless of whether any
+    // config key is visible there — they alone must be enough to open it.
+    const includeSecrets = secretsEnabled && scope === "tenant";
+    if (visible.length === 0 && !includeSecrets)
+        return null;
+    const configAccess = rolesToAccess(visible.flatMap((v) => v.roles));
+    const secretsAccess = secretsWriteHandler?.access;
+    const gating = scope === "tenant"
+        ? planSelectorGating(registry, visible, declaredSecrets, secretsEnabled)
+        : NO_SELECTOR_GATING;
+    const screens = [];
+    const navs = [];
+    // Audience-Parent: Gruppierungs-Knoten ohne Screen.
+    navs.push({
+        id: audienceNavShortId(scope),
+        label: `config.settings.${scope}`,
+        icon: SCOPE_ICON[scope],
+        order: SCOPE_ORDER[scope],
+        access: includeSecrets ? unionAccessRules([configAccess, secretsAccess]) : configAccess,
+    });
+    const perFeature = buildFeatureScreensAndNavs(scope, visible, hub, gating, secretsAccess);
+    screens.push(...perFeature.screens);
+    navs.push(...perFeature.navs);
+    const translations = {
+        ...perFeature.translations,
+    };
+    const globalSecrets = declaredSecrets.filter((s) => !gating.secretQns.has(s.qn));
+    if (includeSecrets && globalSecrets.length > 0) {
+        const generated = buildSecretsScreen(globalSecrets, secretsAccess, hub.declaredTranslationKeys);
+        screens.push(generated.screen);
+        navs.push(generated.nav);
+        Object.assign(translations, generated.translations);
+    }
+    return {
+        screens,
+        navs,
+        ...(Object.keys(translations).length > 0 && { translations }),
+    };
+}
+export function buildConfigFeatureSchema(registry) {
+    const masked = collectMaskedKeys(registry);
+    const declaredSecrets = collectDeclaredSecrets(registry);
+    // The `secrets` feature must actually be mounted (its set-handler
+    // registered) for a declared `r.secret()` to have anywhere to write to.
+    const secretsWriteHandler = registry.getWriteHandler("secrets:write:set");
+    const secretsEnabled = secretsWriteHandler !== undefined && declaredSecrets.length > 0;
+    if (masked.length === 0 && !secretsEnabled)
+        return { screens: [], navs: [] };
+    const translationsByKey = collectDeclaredTranslations(registry);
+    const hub = {
+        declaredTranslationKeys: new Set(translationsByKey.keys()),
+        selectorOptions: collectSelectorOptions(registry),
+        translationsByKey,
+    };
+    const screens = [];
+    const navs = [];
+    let translations;
+    for (const scope of SCOPES_BROAD_TO_DEEP) {
+        const result = buildScopeResult(scope, masked, secretsEnabled, secretsWriteHandler, declaredSecrets, hub, registry);
+        if (result === null)
+            continue;
+        screens.push(...result.screens);
+        navs.push(...result.navs);
+        if (result.translations !== undefined) {
+            translations = { ...translations, ...result.translations };
+        }
+    }
+    // Every masked key machine-only and no secrets → no human hub, and no
+    // (empty) settings switcher.
+    if (navs.length === 0)
+        return { screens, navs };
+    return {
+        screens,
+        navs,
+        workspace: buildSettingsWorkspace(navs),
+        ...(translations !== undefined && { translations }),
+    };
+}
+function collectDeclaredSecrets(registry) {
+    const out = [];
+    for (const [qn, def] of registry.getAllSecretKeys()) {
+        const sep = qn.indexOf(":secret:");
+        if (sep === -1)
+            continue;
+        out.push({
+            qn,
+            feature: qn.slice(0, sep),
+            shortKey: qn.slice(sep + ":secret:".length),
+            def,
+        });
+    }
+    return out.sort((a, b) => a.feature.localeCompare(b.feature) || a.shortKey.localeCompare(b.shortKey));
+}
+// One screen for ALL declared secrets (not one per feature — a per-feature
+// nav would collide with the same feature's configEdit nav under
+// audience-tenant). `access` mirrors the secrets `set`-handler's own access
+// rule verbatim so a screen never permits more than the handler itself does.
+function buildSecretsScreen(secrets, access, declaredTranslationKeys) {
+    const { screen, translations } = buildSecretsEditScreen("secrets", secrets, access, declaredTranslationKeys);
+    const nav = {
+        id: "secrets",
+        label: "config.secrets.title",
+        parent: audienceNavShortId("tenant"),
+        screen: "secrets",
+        icon: "key",
+        order: 900,
+        ...(access !== undefined && { access }),
+    };
+    return { screen, nav, translations };
+}
+function buildSecretsEditScreen(screenId, secrets, access, declaredTranslationKeys) {
+    const secretKeys = {};
+    const fieldLabels = {};
+    const fieldHints = {};
+    const requiredFields = [];
+    // Mutable outer record — TranslationKeys' Readonly<Record<...>> index
+    // signature only permits reading, so the top-level assignments below
+    // need a writable local type; each entry is still a fresh, never-mutated object.
+    const translations = {};
+    const sections = [];
+    for (const feature of [...new Set(secrets.map((s) => s.feature))]) {
+        const fieldIds = [];
+        for (const s of secrets.filter((v) => v.feature === feature)) {
+            const fieldId = `${s.feature}-${s.shortKey}`;
+            fieldIds.push(fieldId);
+            secretKeys[fieldId] = s.qn;
+            const labelKey = `config.secret.${s.feature}.${s.shortKey}.label`;
+            fieldLabels[fieldId] = labelKey;
+            translations[labelKey] = { ...s.def.label };
+            if (s.def.hint !== undefined) {
+                const hintKey = `config.secret.${s.feature}.${s.shortKey}.hint`;
+                fieldHints[fieldId] = hintKey;
+                translations[hintKey] = { ...s.def.hint };
+            }
+            if (s.def.required === true)
+                requiredFields.push(fieldId);
+        }
+        const titleKey = `${feature}.settings`;
+        sections.push({
+            ...(declaredTranslationKeys.has(titleKey) && { title: titleKey }),
+            fields: fieldIds,
+        });
+    }
+    const screen = {
+        id: screenId,
+        type: "secretsEdit",
+        secretKeys,
+        fieldLabels,
+        ...(Object.keys(fieldHints).length > 0 && { fieldHints }),
+        ...(requiredFields.length > 0 && { requiredFields }),
+        sections,
+        ...(access !== undefined && { access }),
+    };
+    return { screen, translations };
+}
+// Keys visible at `scope`, paired with their effective write roles AT that
+// scope (Home = full write; broader = elevated ∩ write).
+function scopedKeysAt(masked, scope) {
+    const out = [];
+    for (const key of masked) {
+        const roles = effectiveWriteRoles(key.def, scope);
+        // Strip MACHINE_WRITE_ROLE from the screen roles: a mixed write set
+        // (e.g. ["system", "SystemAdmin"]) must not leak "system" into the
+        // screen access gate — mirrors the machine-filtered workspace gate.
+        const humanRoles = roles.filter((r) => r !== MACHINE_WRITE_ROLE);
+        if (humanRoles.length > 0)
+            out.push({ key, roles: humanRoles });
+    }
+    return out;
+}
+function effectiveWriteRoles(def, scope) {
+    if (SCOPE_ORDER[scope] > SCOPE_ORDER[def.scope])
+        return [];
+    if (scope === def.scope)
+        return [...def.access.write];
+    const elevated = ELEVATED_ROLES[scope];
+    return def.access.write.filter((r) => elevated.includes(r));
+}
+// navMembers tragen die QUALIFIZIERTEN Nav-QNs (siehe build-app-schema.test:
+// admin.navMembers === ["orders:nav:list", ...]). Die generierten Navs leben
+// unter SETTINGS_HUB_FEATURE, also `config:nav:<shortId>`. Sortiert = stabile
+// Landing-Screen-Wahl (firstNavScreenId iteriert navMembers der Reihe nach).
+function buildSettingsWorkspace(navs) {
+    const navMembers = navs.map((n) => `${SETTINGS_HUB_FEATURE}:nav:${n.id}`).sort();
+    return {
+        definition: {
+            id: SETTINGS_HUB_WORKSPACE,
+            label: "config.settings.title",
+            icon: "settings",
+            order: 1000,
+            // Union der Zugriffs-Regeln der bereits generierten (machine-gefilterten)
+            // Hub-Navs — sonst sieht ein unprivilegierter User einen leeren
+            // "Settings"-Switcher. Aus den Navs statt aus `masked`, damit die
+            // machine-only "system"-Rolle (die in keinem Nav steht) nicht ins
+            // Switcher-Gate leakt.
+            access: unionAccessRules(navs.map((n) => n.access)),
+        },
+        navMembers,
+    };
+}
+function buildScreen(shortId, scope, feature, keys, access, hub) {
+    const configKeys = {};
+    const fields = {};
+    const fieldLabels = {};
+    // 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,
+    // to keep two features sharing a group from clobbering the same shortKey.
+    const fieldId = (k) => k.feature === k.ownerFeature ? k.shortKey : `${k.ownerFeature}-${k.shortKey}`;
+    const seenFieldIds = new Map();
+    for (const k of keys) {
+        const id = fieldId(k);
+        const prevQn = seenFieldIds.get(id);
+        if (prevQn !== undefined) {
+            throw new Error(`[Settings-Hub] group "${feature}" scope "${scope}": config keys "${prevQn}" and "${k.qn}" both resolve to field id "${id}" — rename one key or its group.`);
+        }
+        seenFieldIds.set(id, k.qn);
+        configKeys[id] = k.qn;
+        fields[id] = deriveField(k.def, hub.selectorOptions.get(k.qn));
+        // mask is the visibility gate, so collectMaskedKeys guarantees it here.
+        if (k.def.mask)
+            fieldLabels[id] = k.def.mask.title;
+    }
+    // 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),
+    };
+    return {
+        id: shortId,
+        type: "configEdit",
+        scope,
+        configKeys,
+        fields,
+        fieldLabels,
+        layout: { sections: [section], width: "full" },
+        access,
+    };
+}
+function deriveField(def, selectorPluginIds) {
+    if (selectorPluginIds !== undefined)
+        return createSelectField({ options: selectorPluginIds });
+    switch (def.type) {
+        case "number":
+            return createNumberField();
+        case "boolean":
+            return createBooleanField();
+        case "select":
+            return def.options !== undefined && def.options.length > 0
+                ? createSelectField({ options: def.options })
+                : createTextField({ personal: false, reason: "system_metadata" });
+        default:
+            return createTextField({ personal: false, reason: "system_metadata" });
+    }
+}
+function collectMaskedKeys(registry) {
+    const out = [];
+    for (const [qn, def] of registry.getAllConfigKeys()) {
+        const sep = qn.indexOf(":config:");
+        if (sep === -1)
+            continue;
+        const ownerFeature = qn.slice(0, sep);
+        if (def.group !== undefined && !isKebabSegment(def.group)) {
+            throw new Error(`[Feature ${ownerFeature}] config key "${qn.slice(sep + ":config:".length)}" has invalid group "${def.group}" — must be kebab-case.`);
+        }
+        // computed keys derive their value — there is no row to set, so a
+        // configEdit screen could not write them. Skip even when masked.
+        if (def.mask === undefined || def.computed !== undefined)
+            continue;
+        out.push({
+            qn,
+            feature: def.group ?? ownerFeature,
+            ownerFeature,
+            shortKey: qn.slice(sep + ":config:".length),
+            def,
+        });
+    }
+    return out;
+}
+function featuresPresent(keys) {
+    return [...new Set(keys.map((k) => k.feature))].sort();
+}
+function sortByMaskOrder(keys) {
+    return [...keys].sort((a, b) => maskOrder(a) - maskOrder(b) || a.shortKey.localeCompare(b.shortKey));
+}
+function maskOrder(k) {
+    return k.def.mask?.order ?? 0;
+}
+function minMaskOrder(keys) {
+    return Math.min(...keys.map(maskOrder));
+}
+// Der Hub ist zum Editieren — wer mindestens einen Key der Gruppe SCHREIBEN
+// darf, sieht den Settings-Eintrag (write, nicht read). Das hält system-scope
+// (write default `["system"]`) human-hidden bis der Autor write: SystemAdmin
+// opt-int, und zeigt user-scope (write `all`) jedem. `all` lässt sich in
+// AccessRule nur als openToAll ausdrücken; der Write bleibt server-seitig
+// per Key gegated.
+// Union der Navs-Access-Regeln: ein openToAll-Nav öffnet das ganze Gate, sonst
+// die Vereinigung der Rollen. undefined-access-Navs tragen nichts bei.
+function unionAccessRules(rules) {
+    const roles = [];
+    for (const rule of rules) {
+        if (rule === undefined)
+            continue;
+        if ("openToAll" in rule) {
+            if (isOpenToAllGranted(rule))
+                return rule;
+            continue;
+        }
+        roles.push(...rule.roles);
+    }
+    return rolesToAccess(roles);
+}
+// `all` lässt sich in AccessRule nur als openToAll ausdrücken; der Write bleibt
+// server-seitig per Key gegated.
+function rolesToAccess(roles) {
+    if (roles.includes("all"))
+        return {
+            openToAll: {
+                reason: 'config key declares the "all" role, so every signed-in user of the tenant may read/write it',
+            },
+        };
+    return { roles: [...new Set(roles)] };
+}

package/dist/engine/build-target.d.ts

@@ -0,0 +1,28 @@
+import type { TargetRef } from "./types/target-ref.js";
+import type { TreeActionDef } from "./types/tree-node.js";
+type FeatureWithTreeActions<TActions extends Record<string, TreeActionDef>> = {
+    readonly id: string;
+    readonly treeActions: TActions;
+};
+type NoArgsAction<T extends Record<string, TreeActionDef>> = {
+    [K in keyof T]: T[K] extends {
+        args: unknown;
+    } ? never : K;
+}[keyof T] & string;
+type WithArgsAction<T extends Record<string, TreeActionDef>> = {
+    [K in keyof T]: T[K] extends {
+        args: unknown;
+    } ? K : never;
+}[keyof T] & string;
+export declare function buildTarget<TActions extends Record<string, TreeActionDef>, TActionName extends NoArgsAction<TActions>>(spec: {
+    readonly target: FeatureWithTreeActions<TActions>;
+    readonly action: TActionName;
+}): TargetRef;
+export declare function buildTarget<TActions extends Record<string, TreeActionDef>, TActionName extends WithArgsAction<TActions>>(spec: {
+    readonly target: FeatureWithTreeActions<TActions>;
+    readonly action: TActionName;
+    readonly args: TActions[TActionName] extends {
+        args: infer TArgs;
+    } ? TArgs : never;
+}): TargetRef;
+export {};

package/dist/engine/build-target.js

@@ -0,0 +1,43 @@
+// buildTarget — typed Builder für TargetRef.
+//
+// **Was er macht.** Erzeugt einen TargetRef, dessen action + args
+// compile-time gegen die treeActions-Map des Ziel-Features validiert
+// sind. Magic-String-URIs werden nirgends hand-getippt; das ist die
+// Single-Source-of-Truth für Cross-Feature-Linking im Visual-Tree.
+//
+// **Wie er typed.** Function-Overloads splitten Actions ohne args
+// (NoArgsAction) und Actions mit args (WithArgsAction). TS validiert:
+//   - action ist string-literal aus den Keys von treeActions
+//   - bei WithArgsAction sind args required und matchen
+//     treeActions[action]["args"]
+//   - bei NoArgsAction ist args nicht erlaubt
+//
+// **Phase 0.** Das Feature-Handle ist hier eine generische Constraint
+// (FeatureWithTreeActions). In Schicht 2 wird treeActions ein
+// Pattern-Type im Feature-AST und defineFeature exposed eine
+// treeActions-Slot mit gleichem Shape — dann passen real Features
+// drauf, ohne Builder-Änderung.
+//
+// Siehe docs/plans/architecture/visual-tree.md A5.
+// TypeGuard für args: Overloads garantieren ein Plain-Object, aber die
+// Implementation-Signature sieht args als unknown (TArgs ist erased zur
+// Laufzeit). Der Guard validiert die Plain-Object-Convention runtime
+// statt einen `as`-Cast zu setzen — siehe coding-standards.md.
+function isArgsObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+// Implementation — args ist `unknown` weil die Overloads-Generic-TArgs
+// zur Laufzeit erased ist. Plain-Object-Convention via TypeGuard.
+export function buildTarget(spec) {
+    if (!isArgsObject(spec.args)) {
+        return Object.freeze({
+            featureId: spec.target.id,
+            action: spec.action,
+        });
+    }
+    return Object.freeze({
+        featureId: spec.target.id,
+        action: spec.action,
+        args: Object.freeze({ ...spec.args }),
+    });
+}

package/dist/engine/changeset-changes.d.ts

@@ -0,0 +1,12 @@
+import { type ChangelogType } from "./feature-changelog.js";
+export type PendingChange = {
+    readonly feature: string;
+    readonly type: ChangelogType;
+    readonly title: string;
+    readonly detail?: string;
+    readonly migration?: string;
+    readonly codemod?: string;
+    readonly source: string;
+};
+/** Parse structured upgrade metadata embedded in a Changeset body. */
+export declare function parseChangesetChanges(markdown: string, source: string): readonly PendingChange[];