@cosmicdrift/kumiko-framework 0.368.0 → 0.369.0

package/agents/features.md

@@ -106,7 +106,7 @@ Requires: `delivery`, `secrets`
 
 ## channel-email
 
-Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.
+Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send the notifications declared with `tenantTransport: true` through the sending tenant's own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`; every other notification (password reset, sign-in) always goes through the app `transport`. `transport` may be left out when `tenantTransport` is set; a mail that then has no transport fails with `missing_credentials`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.
 
 Category: notifications
 
@@ -206,7 +206,7 @@ Exposes APIs: `retention.policyFor`
 
 ## delivery
 
-The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (`runProdApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.
+The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (the `runProdApp` and `runDevApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. An app serving its own (e.g. legacy) unsubscribe links renders the same result page with `renderUnsubscribeResultPage({ kind, locale })`. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.
 
 Category: notifications
 
@@ -413,7 +413,7 @@ German UI and mail copy for framework screens. Opt-in; not included by includeBu
 
 ## mail-foundation
 
-Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences. Pass `tenantMailTransport` as `tenantTransport` to `createChannelEmailFeature` so a tenant with a provider configured sends delivery mails through its own transport and other tenants through the app transport.
+Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences. Pass `tenantMailTransport` as `tenantTransport` to `createChannelEmailFeature`: notifications declared with `tenantTransport: true` then go through the tenant's own transport when it has a provider and through the app transport otherwise. Tenant admins pick the provider and fill in its settings on the generated Email sending settings screen; an empty provider is a valid choice and means the platform sends.
 
 Category: notifications
 
@@ -558,7 +558,7 @@ Requires: `renderer-foundation`
 
 ## secrets
 
-Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: ["TenantAdmin"] }; adopt the host's role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins).
+Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: ["TenantAdmin"] }; adopt the host's role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins). Server-side code writes a tenant secret with `dispatchSystemWrite({ handlerQn: "secrets:write:set", payload, tenantId })`: set and delete also admit the in-process system identity, so such writes pass the same declared-key and value checks.
 
 Category: infrastructure
 

package/dist/engine/boot-validator/screens.js

@@ -551,6 +551,25 @@ function validateOptionsQueryFieldRefs(where, fieldName, payload, siblingFieldNa
 function isWriteOnlyField(fdef) {
     return fdef?.writeOnly === true; // @cast-boundary schema-walk
 }
+// A secret on a configEdit form keeps its value out of the client like an encrypted
+// config key does, and the secrets store only exists per tenant.
+function validateConfigEditSecretField(featureName, screen, fieldName, secretQn, featureMap) {
+    const where = `[Feature ${featureName}] Screen "${screen.id}" (configEdit) field "${fieldName}"`;
+    if (screen.configKeys[fieldName] !== undefined) {
+        throw new Error(`${where} is mapped in both configKeys and secretKeys — keep one.`);
+    }
+    if (screen.scope !== "tenant") {
+        throw new Error(`${where} maps secret "${secretQn}" on a ${screen.scope}-scope screen — secrets are tenant-scoped.`);
+    }
+    const fdef = screen.fields[fieldName];
+    if (fdef?.type !== "text" || !isWriteOnlyField(fdef)) {
+        throw new Error(`${where} maps secret "${secretQn}" but is no writeOnly text field — a stored secret never goes back to the client.`);
+    }
+    const declared = [...featureMap.values()].some((feature) => Object.values(feature.secretKeys ?? {}).some((def) => def.qualifiedName === secretQn));
+    if (!declared) {
+        throw new Error(`${where} → secret "${secretQn}" is not declared via r.secret() in any feature.`);
+    }
+}
 // Inline forms have no stored value to hide or keep: writeOnly there would
 // render a "set / keep" affordance with nothing behind it.
 function rejectWriteOnlyFormField(featureName, screenId, context, fieldName, fdef) {
@@ -1477,9 +1496,19 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                 }
             }
             validateWizardLayout(feature.name, screenId, "configEdit", screen.layout, featureMap);
+            for (const fname of Object.keys(screen.secretKeys ?? {})) {
+                if (!fieldNames.has(fname)) {
+                    throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) secretKeys names unknown field "${fname}".`);
+                }
+            }
             // configKeys: jeder fieldName muss einen Mapping-Eintrag haben,
             // jeder qualifizierte Key muss in der Registry existieren.
             for (const fname of fieldNames) {
+                const secretQn = screen.secretKeys?.[fname];
+                if (secretQn !== undefined) {
+                    validateConfigEditSecretField(feature.name, screen, fname, secretQn, featureMap);
+                    continue;
+                }
                 const qualified = screen.configKeys[fname];
                 if (qualified === undefined) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) field "${fname}" has ` +

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

@@ -17,9 +17,10 @@
 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 { EXTENSION_SELECTOR_HINT_KEY, isSelectableInSettings, settingsSelectablePluginIds, } from "./extension-selector-plugins.js";
 import { createBooleanField, createNumberField, createSelectField, createTextField, } from "./factories.js";
 import { isKebabSegment, toKebab } from "./qualified-name.js";
+import { isFieldsEditSection, sectionFieldSpecs } from "./screen-helpers.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
@@ -45,7 +46,7 @@ const PROVIDER_PANEL_TITLE_ENTRY = {
     es: "Proveedor",
 };
 const PROVIDER_SECTION_TITLE_KEY = "config.settings.provider";
-const SAVE_PROVIDER_LABEL_KEY = "config.settings.saveProvider";
+const SECRETS_SECTION_DESCRIPTION_KEY = "config.secrets.description";
 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)}`);
@@ -73,25 +74,43 @@ const NO_SELECTOR_GATING = {
 };
 // Verbatim (unprefixed) keys as the client sees them — NOT getAllTranslations()
 // (server-merged, "feature:"-prefixed, see build-app-schema.ts:77-81).
+// Merged per locale: a locale feature (localeDe) declares the same key with only its
+// own language, and mounted first it must not drop the owning feature's en text.
 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);
+            declared.set(key, { ...values, ...declared.get(key) });
         }
     }
     return declared;
 }
+// A selector whose plugins are all hidden from settings still renders as a select
+// (with no option), never as a free text field.
 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);
+        if (registry.getExtensionUsages(extensionName).length === 0)
+            continue;
+        options.set(selectorKey, settingsSelectablePluginIds(registry, extensionName));
     }
     return options;
 }
+// selector key → plugin id → plugin feature, for every selectable plugin, also those
+// without settings of their own (no panel, but still an option with a name).
+function collectSelectorOptionFeatures(registry) {
+    const byKey = new Map();
+    for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {
+        const featureByPluginId = new Map();
+        for (const usage of registry.getExtensionUsages(extensionName).filter(isSelectableInSettings)) {
+            if (usage.featureName === undefined || featureByPluginId.has(usage.entityName))
+                continue;
+            featureByPluginId.set(usage.entityName, toKebab(usage.featureName));
+        }
+        byKey.set(selectorKey, featureByPluginId);
+    }
+    return byKey;
+}
 function collectVisibleSelectorOwners(registry, visible) {
     const ownerGroupByExtension = new Map();
     const selectorFeatures = new Set();
@@ -141,6 +160,9 @@ function planSelectorGating(registry, visible, declaredSecrets, secretsEnabled)
     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 ?? ""));
+        const selectorQn = registry.getAllExtensionSelectors().get(extension);
+        if (selectorQn === undefined)
+            continue;
         for (const usage of usages) {
             if (usage.featureName === undefined)
                 continue;
@@ -148,11 +170,22 @@ function planSelectorGating(registry, visible, declaredSecrets, secretsEnabled)
             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) : [];
+            // The provider form has no per-field access gate, so a secret with its own write
+            // roles stays on the secrets screen, which enforces them.
+            const secrets = secretsEnabled
+                ? declaredSecrets.filter((s) => s.feature === feature && s.def.writeRoles === undefined)
+                : [];
             if (scopedKeys.length === 0 && secrets.length === 0)
                 continue;
             const plugins = pluginsByOwnerGroup.get(ownerGroup) ?? [];
-            plugins.push({ feature, extension, pluginId: usage.entityName, scopedKeys, secrets });
+            plugins.push({
+                feature,
+                extension,
+                selectorQn,
+                pluginId: usage.entityName,
+                scopedKeys,
+                secrets,
+            });
             pluginsByOwnerGroup.set(ownerGroup, plugins);
             pluginFeatures.add(feature);
             for (const s of secrets)
@@ -204,9 +237,6 @@ function buildFeatureScreensAndNavs(scope, visible, hub, gating, secretsAccess)
     }
     return out;
 }
-function pluginTenantScreenId(plugin) {
-    return `${plugin.feature}-tenant`;
-}
 function assertUniquePanelIds(ownerGroup, panels) {
     const seen = new Set();
     for (const panel of panels) {
@@ -218,63 +248,38 @@ function assertUniquePanelIds(ownerGroup, panels) {
     }
     return panels;
 }
-// Plugin screens keep their `${F}-tenant` ids so consumer title keys stay valid;
-// they are dormant because only this dashboard embeds them.
+// One form for the provider and the settings of every provider: a single save writes
+// all of it, so switching sections can't drop typed input. Each plugin's fields are
+// shown only while its provider is picked in the form; hidden fields are not saved.
 function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins, ownerPanels, hub, secretsAccess) {
     const selectionScreenId = `${ownerGroup}-tenant-selection`;
-    const selectionScreen = {
-        ...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];
-    const configPanels = [];
-    const secretsPanels = [];
+    const form = new ProviderFormBuilder(selectionScreenId, buildScreen(selectionScreenId, "tenant", ownerGroup, ownerKeys, ownerAccess, hub, {
+        description: EXTENSION_SELECTOR_HINT_KEY,
+        sectionTitle: PROVIDER_SECTION_TITLE_KEY,
+    }));
     const accessRules = [ownerAccess];
     const translations = {};
     translations[`screen:${selectionScreenId}.title`] = PROVIDER_PANEL_TITLE_ENTRY;
-    Object.assign(translations, providerOptionTranslations(selectionScreen, plugins, hub));
+    Object.assign(translations, providerOptionTranslations(form.base, hub));
     for (const plugin of plugins) {
-        const visibleWhen = {
-            query: SELECTED_EXTENSIONS_QUERY,
-            field: plugin.extension,
-            eq: plugin.pluginId,
-        };
+        const providerFieldId = form.fieldIdOfConfigKey(plugin.selectorQn);
+        const visible = { field: providerFieldId, eq: plugin.pluginId };
+        let pluginSection;
         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, { description: null }),
-                dormant: true,
-            });
+            const pluginScreen = buildScreen(`${plugin.feature}-tenant`, "tenant", plugin.feature, sortByMaskOrder(plugin.scopedKeys.map((v) => v.key)), pluginAccess, hub, { description: null, fieldIdOf: qualifiedFieldId });
+            pluginSection = form.addConfigFields(pluginScreen, visible);
             accessRules.push(pluginAccess);
-            configPanels.push({
-                kind: "screen",
-                id: `${plugin.feature}-config`,
-                screen: pluginTenantScreenId(plugin),
-                visibleWhen,
-                chromeless: true,
-            });
         }
         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 });
+            const generated = buildSecretsEditScreen(`${plugin.feature}-tenant-secrets`, plugin.secrets, secretsAccess, hub.declaredTranslationKeys);
+            form.addSecretFields(generated.screen, plugin.feature, visible, pluginSection);
             Object.assign(translations, generated.translations);
             accessRules.push(secretsAccess);
-            secretsPanels.push({
-                kind: "screen",
-                id: `${plugin.feature}-secrets`,
-                screen: secretsScreenId,
-                visibleWhen,
-                chromeless: true,
-            });
         }
     }
     const access = unionAccessRules(accessRules);
+    const selectionScreen = { ...form.build(access), dormant: true };
     const dashboard = {
         id: `${ownerGroup}-tenant`,
         type: "dashboard",
@@ -282,16 +287,136 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
         panels: assertUniquePanelIds(ownerGroup, [
             { kind: "screen", id: "selection", screen: selectionScreenId, chromeless: true },
             ...ownerPanels,
-            ...configPanels,
-            ...secretsPanels,
         ]),
         access,
     };
-    return { screens: [dashboard, ...screens], access, translations };
+    return { screens: [dashboard, selectionScreen], access, translations };
+}
+// A plugin key keeps its feature in the field id: the provider form holds the keys of
+// several features side by side.
+function qualifiedFieldId(k) {
+    return `${k.ownerFeature}-${k.shortKey}`;
+}
+class ProviderFormBuilder {
+    screenId;
+    base;
+    configKeys;
+    secretKeys = {};
+    fields;
+    fieldLabels;
+    fieldDescriptions;
+    requiredFields;
+    sections;
+    constructor(screenId, base) {
+        this.screenId = screenId;
+        this.base = base;
+        this.configKeys = { ...base.configKeys };
+        this.fields = { ...base.fields };
+        this.fieldLabels = { ...base.fieldLabels };
+        this.fieldDescriptions = { ...base.fieldDescriptions };
+        this.requiredFields = [...(base.requiredFields ?? [])];
+        this.sections = base.layout.sections.filter(isFieldsEditSection);
+    }
+    fieldIdOfConfigKey(qn) {
+        const entry = Object.entries(this.base.configKeys).find(([, keyQn]) => keyQn === qn);
+        if (entry === undefined) {
+            throw new Error(`[Settings-Hub] selector key "${qn}" is not on "${this.screenId}".`);
+        }
+        return entry[0];
+    }
+    addConfigFields(pluginScreen, visible) {
+        for (const [id, qn] of Object.entries(pluginScreen.configKeys)) {
+            this.claim(id, qn);
+            this.configKeys[id] = qn;
+            const field = pluginScreen.fields[id];
+            if (field !== undefined)
+                this.fields[id] = field;
+        }
+        Object.assign(this.fieldLabels, pluginScreen.fieldLabels);
+        Object.assign(this.fieldDescriptions, pluginScreen.fieldDescriptions);
+        this.requiredFields.push(...(pluginScreen.requiredFields ?? []));
+        const section = pluginScreen.layout.sections.find(isFieldsEditSection);
+        if (section === undefined)
+            return undefined;
+        const { groups: _groups, ...flatSection } = section;
+        const gated = {
+            ...flatSection,
+            fields: gateFields(sectionFieldSpecs(section), visible),
+        };
+        this.sections.push(gated);
+        return gated;
+    }
+    // A plugin's sign-in data gets its own section when the plugin names one, else it
+    // continues the plugin's settings section.
+    addSecretFields(secretsScreen, feature, visible, pluginSection) {
+        for (const [id, qn] of Object.entries(secretsScreen.secretKeys)) {
+            this.claim(id, qn);
+            this.secretKeys[id] = qn;
+            this.fields[id] = createTextField({
+                personal: false,
+                reason: "system_metadata",
+                writeOnly: true,
+            });
+        }
+        Object.assign(this.fieldLabels, secretsScreen.fieldLabels);
+        Object.assign(this.fieldDescriptions, secretsScreen.fieldHints);
+        this.requiredFields.push(...(secretsScreen.requiredFields ?? []));
+        const secretsTitleKey = `${feature}.settings.secrets`;
+        for (const section of secretsScreen.sections) {
+            // kumiko-lint-ignore section-fields-raw a secretsEdit section is a flat key list without groups
+            const fields = gateFields(section.fields, visible);
+            const ownSection = section.title === secretsTitleKey || pluginSection === undefined;
+            if (ownSection) {
+                this.sections.push({
+                    title: section.title ?? `${feature}.settings`,
+                    description: SECRETS_SECTION_DESCRIPTION_KEY,
+                    fields,
+                });
+                continue;
+            }
+            const index = this.sections.indexOf(pluginSection);
+            this.sections[index] = {
+                ...pluginSection,
+                fields: [...sectionFieldSpecs(pluginSection), ...fields],
+            };
+        }
+    }
+    build(access) {
+        const { fieldDescriptions: _baseDescriptions, requiredFields: _baseRequired, ...base } = this.base;
+        return {
+            ...base,
+            configKeys: this.configKeys,
+            ...(Object.keys(this.secretKeys).length > 0 && { secretKeys: this.secretKeys }),
+            fields: this.fields,
+            fieldLabels: this.fieldLabels,
+            ...(Object.keys(this.fieldDescriptions).length > 0 && {
+                fieldDescriptions: this.fieldDescriptions,
+            }),
+            ...(this.requiredFields.length > 0 && { requiredFields: this.requiredFields }),
+            layout: { ...base.layout, sections: this.sections },
+            access,
+        };
+    }
+    claim(id, qn) {
+        const previous = this.configKeys[id] ?? this.secretKeys[id];
+        if (previous !== undefined) {
+            throw new Error(`[Settings-Hub] "${previous}" and "${qn}" both resolve to field id "${id}" on "${this.screenId}" — rename one key.`);
+        }
+    }
+}
+function gateFields(fields, visible) {
+    return fields.map((spec) => typeof spec === "string" ? { field: spec, visible } : { ...spec, visible });
 }
 // 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.
+// The secrets set handler also admits the machine role for server-side writes; like the
+// config keys' write roles, that role must not reach a screen or nav access gate.
+function withoutMachineRole(rule) {
+    if (rule === undefined || !("roles" in rule))
+        return rule;
+    return { ...rule, roles: rule.roles.filter((role) => role !== MACHINE_WRITE_ROLE) };
+}
 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
@@ -300,7 +425,7 @@ function buildScopeResult(scope, masked, secretsEnabled, secretsWriteHandler, de
     if (visible.length === 0 && !includeSecrets)
         return null;
     const configAccess = rolesToAccess(visible.flatMap((v) => v.roles));
-    const secretsAccess = secretsWriteHandler?.access;
+    const secretsAccess = withoutMachineRole(secretsWriteHandler?.access);
     const gating = scope === "tenant"
         ? planSelectorGating(registry, visible, declaredSecrets, secretsEnabled)
         : NO_SELECTOR_GATING;
@@ -346,6 +471,7 @@ export function buildConfigFeatureSchema(registry) {
     const hub = {
         declaredTranslationKeys: new Set(translationsByKey.keys()),
         selectorOptions: collectSelectorOptions(registry),
+        selectorOptionFeatures: collectSelectorOptionFeatures(registry),
         translationsByKey,
     };
     const screens = [];
@@ -440,7 +566,12 @@ function buildSecretsEditScreen(screenId, secrets, access, declaredTranslationKe
             if (s.def.writeRoles !== undefined)
                 fieldAccess[fieldId] = { roles: [...s.def.writeRoles] };
         }
-        const titleKey = `${feature}.settings`;
+        // Opt-in `${feature}.settings.secrets`: in a selector dashboard this section sits right
+        // under the plugin's own settings section, which already carries `${feature}.settings`.
+        const secretsTitleKey = `${feature}.settings.secrets`;
+        const titleKey = declaredTranslationKeys.has(secretsTitleKey)
+            ? secretsTitleKey
+            : `${feature}.settings`;
         sections.push({
             ...(declaredTranslationKeys.has(titleKey) && { title: titleKey }),
             fields: fieldIds,
@@ -514,7 +645,8 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
     // 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 fieldId = options.fieldIdOf ??
+        ((k) => (k.feature === k.ownerFeature ? k.shortKey : qualifiedFieldId(k)));
     const seenFieldIds = new Map();
     for (const k of keys) {
         const id = fieldId(k);
@@ -544,7 +676,6 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
         ...(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,
     };
@@ -589,16 +720,17 @@ function buildSettingsSection(feature, scope, fieldIds, hub, options) {
 }
 // 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) {
+function providerOptionTranslations(selectionScreen, hub) {
     const out = {};
     for (const [fieldId, qn] of Object.entries(selectionScreen.configKeys)) {
-        if (!hub.selectorOptions.has(qn))
+        const featureByPluginId = hub.selectorOptionFeatures.get(qn);
+        if (featureByPluginId === undefined)
             continue;
-        for (const plugin of plugins) {
-            const label = hub.translationsByKey.get(`${plugin.feature}.settings`);
+        for (const [pluginId, feature] of featureByPluginId) {
+            const label = hub.translationsByKey.get(`${feature}.settings`);
             if (label === undefined)
                 continue;
-            const key = `${fieldLabelKey(SETTINGS_HUB_FEATURE, CONFIG_EDIT_ENTITY, fieldId)}:option:${plugin.pluginId}`;
+            const key = `${fieldLabelKey(SETTINGS_HUB_FEATURE, CONFIG_EDIT_ENTITY, fieldId)}:option:${pluginId}`;
             out[key] = label;
         }
     }

package/dist/engine/extension-selector-plugins.d.ts

@@ -1,5 +1,8 @@
 import type { Registry } from "./types/feature.js";
+import type { RegistrarExtensionRegistration } from "./types/index.js";
 export declare const SELECTED_EXTENSIONS_QUERY = "config:query:config-value:selected-extensions";
 export declare const EXTENSION_SELECTOR_HINT_KEY = "config.settings.extensionSelectorHint";
 export declare function selectablePluginIds(registry: Pick<Registry, "getExtensionUsages">, extensionName: string): string[];
+export declare function isSelectableInSettings(usage: RegistrarExtensionRegistration): boolean;
+export declare function settingsSelectablePluginIds(registry: Pick<Registry, "getExtensionUsages">, extensionName: string): string[];
 export declare function extensionSelectorTargets(registry: Pick<Registry, "getAllExtensionSelectors">): ReadonlyMap<string, string>;

package/dist/engine/extension-selector-plugins.js

@@ -5,6 +5,20 @@ export const EXTENSION_SELECTOR_HINT_KEY = "config.settings.extensionSelectorHin
 export function selectablePluginIds(registry, extensionName) {
     return [...new Set(registry.getExtensionUsages(extensionName).map((u) => u.entityName))].sort();
 }
+// A plugin registered with `selectableInSettings: false` (a test inbox) stays a valid
+// stored value for seeds and dev setups, but the generated settings never offer it.
+const SELECTABLE_IN_SETTINGS_OPTION = "selectableInSettings";
+export function isSelectableInSettings(usage) {
+    return usage.options?.[SELECTABLE_IN_SETTINGS_OPTION] !== false;
+}
+export function settingsSelectablePluginIds(registry, extensionName) {
+    return [
+        ...new Set(registry
+            .getExtensionUsages(extensionName)
+            .filter(isSelectableInSettings)
+            .map((u) => u.entityName)),
+    ].sort();
+}
 export function extensionSelectorTargets(registry) {
     const extensionByKey = new Map();
     for (const [extensionName, selectorKey] of registry.getAllExtensionSelectors()) {

package/dist/engine/feature-config-events-jobs.d.ts

@@ -28,6 +28,7 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly renamedFrom?: readonly string[];
         readonly systemOnly?: boolean;
         readonly unsubscribe?: boolean;
+        readonly tenantTransport?: boolean;
     }), definition?: {
         readonly trigger?: {
             readonly on: NameOrRef;
@@ -43,6 +44,7 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly renamedFrom?: readonly string[];
         readonly systemOnly?: boolean;
         readonly unsubscribe?: boolean;
+        readonly tenantTransport?: boolean;
     }): void;
     translations(def: TranslationsDef): void;
     defineEvent: <const TInner extends string, TPayload>(eventName: TInner, schema: ZodType<TPayload>, options: {

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

@@ -222,6 +222,7 @@ export function buildConfigEventsJobsMethods(state, name) {
                     : {}),
                 ...(resolvedDefinition.systemOnly === true ? { systemOnly: true } : {}),
                 ...(resolvedDefinition.unsubscribe === true ? { unsubscribe: true } : {}),
+                ...(resolvedDefinition.tenantTransport === true ? { tenantTransport: true } : {}),
             };
         },
         translations(def) {

package/dist/i18n/settings-hub-keys.js

@@ -16,10 +16,9 @@ export const SETTINGS_HUB_I18N = {
     "config.settings.tenant": { en: "Tenant" },
     "config.settings.user": { en: "Personal" },
     "config.settings.extensionSelectorHint": {
-        en: "Choose a provider and save. Its settings appear below.",
+        en: "Choose a provider. Its settings appear below and are saved together with it.",
     },
     "config.settings.provider": { en: "Provider" },
-    "config.settings.saveProvider": { en: "Save provider" },
     "config.settings.audience.system": {
         en: "Applies to every tenant unless a tenant sets its own value.",
     },

package/dist/upgrade-cli.js

@@ -446,7 +446,7 @@ function writePartialMarker(out, targetDir, pending, manualEntries, failedVersio
     });
     out.err(`  ⚠ ${ran.length} codemod(s) already applied; wrote marker at ${version} so a re-run resumes at the failed one.`);
 }
-// Runs every pending breaking entry's codemod, oldest version first (so a
+// Runs every pending entry's codemod, oldest version first (so a
 // later codemod can assume an earlier one already ran). Stops on the first
 // failure; codemods that already ran are kept in a partial marker. Writes the
 // marker whenever dryRun is false —
@@ -474,7 +474,9 @@ markerVersion, previous) {
         return 0;
     }
     const breaking = pending.filter((e) => e.type === "breaking");
-    const codemodEntries = breaking
+    // A codemod is worth running whatever the entry's type: an improvement that
+    // moves a module ships one too, and skipping it leaves the deprecated path in place.
+    const codemodEntries = pending
         .filter(hasCodemod)
         .sort((a, b) => compareVersions(a.version, b.version));
     const manualEntries = breaking.filter(needsManualMigration);
@@ -485,7 +487,7 @@ markerVersion, previous) {
     }
     if (codemodEntries.length === 0) {
         out.log(breaking.length > 0
-            ? "  No automatable codemods among the pending breaking changes."
+            ? "  No automatable codemods among the pending changes."
             : "  ✓ No breaking changes pending.");
         if (!dryRun) {
             const carried = carryOverManual(previous, manualEntries.map(toMarkerManual));
@@ -636,7 +638,7 @@ kumiko-upgrade --resolve <id|version>[,<id|version>...] --reason "<text>" [--not
   --dir <path>       target directory to check/apply against (default: cwd)
   --json             machine-readable output
   --verbose          include full migration details for each pending entry
-  --apply            run codemods for pending breaking changes and write the upgrade marker
+  --apply            run codemods for pending changes and write the upgrade marker
                      (one run moves the marker to the installed version; manual migrations stay listed as open)
   --resolve <refs>   mark open manual migrations as done; ref = full id or a version with exactly one open entry
   --reason <text>    required with --resolve, max 500 characters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.368.0",
+  "version": "0.369.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -221,8 +221,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.368.0",
-    "@cosmicdrift/kumiko-types": "0.368.0",
+    "@cosmicdrift/kumiko-http": "0.369.0",
+    "@cosmicdrift/kumiko-types": "0.369.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -238,8 +238,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.368.0",
-    "@cosmicdrift/kumiko-testing": "0.368.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.369.0",
+    "@cosmicdrift/kumiko-testing": "0.369.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.369.0",
+    "type": "fix",
+    "title": "kumiko-upgrade --apply runs codemods of improvement entries too",
+    "detail": "The apply step only ran codemods attached to breaking entries. The 0.368.0 entry that moves the test stack to kumiko-testing is an improvement with a codemod (testing-move), so `bun kumiko-upgrade --apply` skipped it and left the deprecated framework paths in place. Every pending entry with a codemod now runs, in version order; manual-migration reporting is unchanged. Apps whose marker is already at 0.368.0 no longer see that entry as pending, so they run `bun kumiko-upgrade --apply --from 0.367.0` once, or the codemod directly: `bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/testing-move.ts . --write`."
+  },
   {
     "version": "0.368.0",
     "type": "fix",