@cosmicdrift/kumiko-framework 0.332.0 → 0.334.0

package/dist/db/eagerload.js

@@ -25,6 +25,7 @@
 import { requestContext } from "../api/request-context.js";
 import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, } from "../crypto/index.js";
 import { selectMany } from "../db/query.js";
+import { maskWriteOnlyFields } from "../engine/field-access.js";
 import { parseRefTargetEntityName } from "../engine/parse-ref-target.js";
 import { collectEncryptedFieldNames, decryptEntityFieldValues, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
 import { buildEntityTable } from "./table-builder.js";
@@ -114,7 +115,7 @@ async function buildRefLookupMap(rawRefRows, refEntity, refEntityName, piiFields
         }
         const id = decrypted["id"];
         if (typeof id === "string")
-            map.set(id, decrypted);
+            map.set(id, maskWriteOnlyFields(refEntity, decrypted));
     }
     return map;
 }

package/dist/engine/boot-validator/config-deps.js

@@ -1,3 +1,4 @@
+import { optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
 import { isEncryptedAtRest } from "../config-helpers.js";
 // --- Toggleable-dependency warnings ---
 //
@@ -123,6 +124,18 @@ export function validateConfigKeyOptionsQuery(feature) {
         if (keyDef.allowPerRequest) {
             throw new Error(`${prefix} has optionsQuery AND allowPerRequest=true — a per-request value would bypass the option set unchecked`);
         }
+        validateOptionsQueryKeyRefs(feature, keyName, keyDef);
+    }
+}
+function validateOptionsQueryKeyRefs(feature, keyName, keyDef) {
+    const prefix = `[Feature ${feature.name}] Config key "${keyName}"`;
+    for (const ref of optionsQueryFieldRefs(keyDef.optionsQueryPayload)) {
+        if (ref === keyName) {
+            throw new Error(`${prefix} optionsQueryPayload references itself ({ field: "${ref}" })`);
+        }
+        if (feature.configKeys[ref] === undefined) {
+            throw new Error(`${prefix} optionsQueryPayload references unknown config key "${ref}" of feature "${feature.name}"`);
+        }
     }
 }
 // --- Config key storage backing × scope matrix ---

package/dist/engine/boot-validator/pii-retention.js

@@ -26,6 +26,42 @@ function ownerFieldNamesReferencedByPersonalOf(fieldsByName) {
     }
     return ownerFieldNames;
 }
+const WRITE_ONLY_FORBIDDEN_FLAGS = [
+    "default",
+    "searchable",
+    "sortable",
+    "filterable",
+    "lookupable",
+];
+function validateWriteOnlyField(featureName, entityName, fieldName, field) {
+    const where = `[Feature ${featureName}] Field "${fieldName}" on entity "${entityName}"`;
+    if (field.type === "embedded") {
+        for (const [subName, subField] of Object.entries(field.schema)) {
+            if (subField.writeOnly === true) {
+                // @cast-boundary schema-walk
+                throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields.`);
+            }
+        }
+        // skip: embedded fields carry no writeOnly of their own; sub-fields are checked above
+        return;
+    }
+    const flags = field; // @cast-boundary schema-walk
+    // skip: only writeOnly fields have constraints to validate
+    if (flags.writeOnly !== true)
+        return;
+    if (field.type !== "text") {
+        throw new Error(`${where} declares { writeOnly: true } but has type "${field.type}" — writeOnly only applies to text fields.`);
+    }
+    if (field.sensitive !== true) {
+        throw new Error(`${where} declares { writeOnly: true } without { sensitive: true } — add find: "secret" (ciphertext at rest, stripped from event echoes).`);
+    }
+    for (const flag of WRITE_ONLY_FORBIDDEN_FLAGS) {
+        const value = flags[flag];
+        if (value !== undefined && value !== false) {
+            throw new Error(`${where} combines { writeOnly: true } with { ${flag} } — a value that is never returned cannot be defaulted, searched, sorted, filtered or looked up.`);
+        }
+    }
+}
 // --- PII / Subject-Key Annotations + Retention validation ---
 //
 // Drei Klassen von Checks:
@@ -92,19 +128,20 @@ export function validatePiiAndRetention(feature) {
                 sensitiveFlags.encrypted !== true) {
                 throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares { sensitive: true } without ciphertext-at-rest. Since #967 the event log stores sensitive fields as table ciphertext — add a subject annotation (personal: "self" / "tenant" / { of: "<field>" }) or { encrypted: true }.`);
             }
+            validateWriteOnlyField(feature.name, entityName, fieldName, field);
             // Sorting reads the projection column — that stays ciphertext, so
             // sortable + subject annotation stays a boot-fail. searchable has
             // been allowed since #1610: the search consumer decrypts into the
             // derived index and forget purges those docs (see
             // createSearchEventConsumer). sensitive + searchable stays forbidden
-            // (nobody-may-read-back).
+            // (never searchable).
             {
                 const flags = field; // @cast-boundary schema-walk
                 if (annotCount > 0 && flags.sortable === true) {
                     throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines a subject-key annotation with { sortable: true } — sorting reads the projection column, which is ciphertext at rest. For equality lookups use find: "exact"; drop sortable or keep the field plaintext (personal: false).`);
                 }
                 if (flags.sensitive === true && flags.searchable === true) {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines { sensitive: true } with { searchable: true } — sensitive means nobody may read the value back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not.`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines { sensitive: true } with { searchable: true } — sensitive means ciphertext at rest, never searchable, stripped from event echoes — authorized readers can still read it back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not. To never return the value at all, add { writeOnly: true }.`);
                 }
             }
             if (annot.userOwned) {

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

@@ -4,7 +4,7 @@
 // into validateColumnRendererForm, splitting them would create a
 // same-folder require cycle.
 import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
-import { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
+import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
 import { NAV_ICON_KEYS } from "@cosmicdrift/kumiko-types/nav-icon";
 import { rowMetaFieldNames } from "../../db/table-builder.js";
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
@@ -471,13 +471,35 @@ function validateFormFieldsMap(featureName, screenId, context, fields, allowEmpt
         if (ftype === "money") {
             validateFormMoneyCurrency(featureName, screenId, context, fname, fdef);
         }
-        validateFormSelectOptions(featureName, screenId, context, fname, fdef);
+        validateFormSelectOptions(featureName, screenId, context, fname, fdef, fieldNames);
+        rejectWriteOnlyFormField(featureName, screenId, context, fname, fdef);
     }
     return fieldNames;
 }
-// Static options XOR optionsQuery on inline-form select fields. The QN
-// existence check lives in query-refs.ts with the other query refs.
-function validateFormSelectOptions(featureName, screenId, context, fieldName, fdef) {
+function validateOptionsQueryFieldRefs(where, fieldName, payload, siblingFieldNames) {
+    for (const ref of optionsQueryFieldRefs(payload)) {
+        if (ref === fieldName) {
+            throw new Error(`${where} optionsQueryPayload references itself ({ field: "${ref}" })`);
+        }
+        if (!siblingFieldNames.has(ref)) {
+            throw new Error(`${where} optionsQueryPayload references unknown field "${ref}" — it must be another field of the same form`);
+        }
+    }
+}
+// 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) {
+    if (fdef.writeOnly === true) {
+        // @cast-boundary schema-walk
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) field "${fieldName}" declares writeOnly — ` +
+            `writeOnly only applies to entity fields (nothing to hide on a form that stores no value). ` +
+            `Use format: "password" for a masked input.`);
+    }
+}
+// Static options XOR optionsQuery on inline-form select fields, and `{ field }`
+// payload refs must name another field of the same form. The QN existence check
+// lives in query-refs.ts with the other query refs.
+function validateFormSelectOptions(featureName, screenId, context, fieldName, fdef, siblingFieldNames) {
     if (fdef.type === "select") {
         const where = `[Feature ${featureName}] Screen "${screenId}" (${context}) select field "${fieldName}"`;
         if (fdef.optionsQuery !== undefined) {
@@ -487,6 +509,7 @@ function validateFormSelectOptions(featureName, screenId, context, fieldName, fd
             if (fdef.options.length > 0) {
                 throw new Error(`${where} declares both options and optionsQuery — pick one`);
             }
+            validateOptionsQueryFieldRefs(where, fieldName, fdef.optionsQueryPayload, siblingFieldNames);
         }
         else if (fdef.optionsQueryPayload !== undefined) {
             throw new Error(`${where} has optionsQueryPayload without optionsQuery`);
@@ -1048,6 +1071,14 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                         throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
                             `(writeForm) has zero fields — drop the section or add fields to it.`);
                     }
+                    // A ref to a fieldDef the form never renders would never resolve.
+                    const writeFormFieldNames = new Set(
+                    // kumiko-lint-ignore section-fields-raw writeForm sections carry no groups (EditWriteFormSection)
+                    section.fields.map((f) => normalizeEditField(f).field));
+                    for (const [defName, fdef] of Object.entries(section.fieldDefs)) {
+                        validateFormSelectOptions(feature.name, screenId, `projectionDetail section "${section.title}" writeForm`, defName, fdef, writeFormFieldNames);
+                        rejectWriteOnlyFormField(feature.name, screenId, `projectionDetail section "${section.title}" writeForm`, defName, fdef);
+                    }
                     // kumiko-lint-ignore section-fields-raw writeForm sections carry no groups (EditWriteFormSection)
                     for (const f of section.fields) {
                         const fieldName = normalizeEditField(f).field;
@@ -1128,7 +1159,8 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) field "${fname}" has no ` +
                         `\`type\` set. Each field must declare a type (e.g. "text", "number", "select").`);
                 }
-                validateFormSelectOptions(feature.name, screenId, "configEdit", fname, fdef);
+                validateFormSelectOptions(feature.name, screenId, "configEdit", fname, fdef, fieldNames);
+                rejectWriteOnlyFormField(feature.name, screenId, "configEdit", fname, fdef);
             }
             if (screen.layout.sections.length === 0) {
                 throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (configEdit) has an empty sections list — ` +

package/dist/engine/build-app-schema.js

@@ -439,6 +439,9 @@ function projectField(fieldDef) {
     // refuse any prefill (URL or handoff) into the field.
     if (def["sensitive"] === true)
         out["sensitive"] = true;
+    // Without it the renderer shows a plain text input for a field whose value never leaves the server.
+    if (def["writeOnly"] === true)
+        out["writeOnly"] = true;
     // timestamp: the edit view-model derives its wall-clock input mode from this.
     if (typeof def["locatedBy"] === "string")
         out["locatedBy"] = def["locatedBy"];

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

@@ -14,6 +14,8 @@
 // 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 { 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 +37,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 +222,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 +234,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 +246,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 +255,7 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
                 id: `${plugin.feature}-config`,
                 screen: pluginTenantScreenId(plugin),
                 visibleWhen,
+                chromeless: true,
             });
         }
         if (plugin.secrets.length > 0) {
@@ -256,6 +269,7 @@ function buildSelectorOwnerDashboard(ownerGroup, ownerKeys, ownerAccess, plugins
                 id: `${plugin.feature}-secrets`,
                 screen: secretsScreenId,
                 visibleWhen,
+                chromeless: true,
             });
         }
     }
@@ -263,9 +277,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 +493,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 +513,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 +530,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 +611,7 @@ function deriveField(def, selectorPluginIds) {
                     options: [],
                     optionsQuery: def.optionsQuery,
                     ...(def.optionsQueryPayload !== undefined && {
-                        optionsQueryPayload: def.optionsQueryPayload,
+                        optionsQueryPayload: rewriteOptionsQueryFieldRefs(key, def.optionsQueryPayload, screenKeys, fieldIdOf),
                     }),
                 });
             }

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/extension-names.d.ts

@@ -5,6 +5,7 @@ import type { PrincipalStatusPlugin, TenantLifecycleStatusPlugin } from "./activ
 import type { TenantDataExtensionHooks } from "./extensions/tenant-data.js";
 import type { TenantResourceExtensionHooks } from "./extensions/tenant-resource.js";
 import type { UserDataExtensionOptions } from "./extensions/user-data.js";
+import type { AssignableFromRole } from "./role-assignment.js";
 import { TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin } from "./tier-resolver-extension.js";
 /**
  * `userData` — User-Daten-Rights-Hooks (DSGVO Art. 15 + 17 + 20).
@@ -137,13 +138,20 @@ export declare const EXT_PRINCIPAL_STATUS: "principalStatus";
  * the bundled `tenant-lifecycle` feature; absent means no tenant is ever "in teardown".
  */
 export declare const EXT_TENANT_LIFECYCLE_STATUS: "tenantLifecycleStatus";
+/**
+ * `assignableRole` — an app declares a membership role as assignable:
+ * `r.useExtension(EXT_ASSIGNABLE_ROLE, "<RoleName>", { assignableFrom? })`
+ * (`assignableFrom` defaults to "Admin").
+ * Provider is the bundled `tenant` feature; consumers are the membership-role guards.
+ */
+export declare const EXT_ASSIGNABLE_ROLE: "assignableRole";
 export declare const TENANT_MEMBERSHIPS_QUERY: "tenant:query:memberships";
 /**
  * Union aller standardisierten Extension-Namen der Datenschutz-Surface.
  * Nicht alle Extensions im System sind in dieser Liste — andere
  * Features koennen weiterhin eigene Extension-Namen registrieren.
  */
-export type KumikoExtensionName = typeof EXT_USER_DATA | typeof EXT_TENANT_DATA | typeof EXT_STORAGE_PROVIDER | typeof EXT_SEARCH_ADAPTER | typeof EXT_EXTERNAL_RESOURCE | typeof EXT_INFRA_RESOURCE | typeof EXT_FILE_PROVIDER | typeof EXT_DERIVATIVE_RENDERER | typeof EXT_DERIVATIVE_PUBLIC_PREDICATE | typeof EXT_DERIVATIVE_OVERLAY_RESOLVER | typeof EXT_PRINCIPAL_STATUS | typeof EXT_TENANT_LIFECYCLE_STATUS;
+export type KumikoExtensionName = typeof EXT_USER_DATA | typeof EXT_TENANT_DATA | typeof EXT_STORAGE_PROVIDER | typeof EXT_SEARCH_ADAPTER | typeof EXT_EXTERNAL_RESOURCE | typeof EXT_INFRA_RESOURCE | typeof EXT_FILE_PROVIDER | typeof EXT_DERIVATIVE_RENDERER | typeof EXT_DERIVATIVE_PUBLIC_PREDICATE | typeof EXT_DERIVATIVE_OVERLAY_RESOLVER | typeof EXT_PRINCIPAL_STATUS | typeof EXT_TENANT_LIFECYCLE_STATUS | typeof EXT_ASSIGNABLE_ROLE;
 /** The four `destroyTenant(tenantId, ctx)`-only resource-cleanup extension points. */
 export type TenantResourceExtensionName = typeof EXT_STORAGE_PROVIDER | typeof EXT_SEARCH_ADAPTER | typeof EXT_EXTERNAL_RESOURCE | typeof EXT_INFRA_RESOURCE;
 declare module "@cosmicdrift/kumiko-framework/engine" {
@@ -155,6 +163,9 @@ declare module "@cosmicdrift/kumiko-framework/engine" {
         [EXT_DERIVATIVE_OVERLAY_RESOLVER]: OverlayResolverPlugin;
         [EXT_PRINCIPAL_STATUS]: PrincipalStatusPlugin;
         [EXT_TENANT_LIFECYCLE_STATUS]: TenantLifecycleStatusPlugin;
+        [EXT_ASSIGNABLE_ROLE]: {
+            readonly assignableFrom?: AssignableFromRole;
+        };
         [EXT_STORAGE_PROVIDER]: TenantResourceExtensionHooks;
         [EXT_SEARCH_ADAPTER]: TenantResourceExtensionHooks;
         [EXT_EXTERNAL_RESOURCE]: TenantResourceExtensionHooks;

package/dist/engine/extension-names.js

@@ -167,6 +167,13 @@ export const EXT_PRINCIPAL_STATUS = "principalStatus";
  * the bundled `tenant-lifecycle` feature; absent means no tenant is ever "in teardown".
  */
 export const EXT_TENANT_LIFECYCLE_STATUS = "tenantLifecycleStatus";
+/**
+ * `assignableRole` — an app declares a membership role as assignable:
+ * `r.useExtension(EXT_ASSIGNABLE_ROLE, "<RoleName>", { assignableFrom? })`
+ * (`assignableFrom` defaults to "Admin").
+ * Provider is the bundled `tenant` feature; consumers are the membership-role guards.
+ */
+export const EXT_ASSIGNABLE_ROLE = "assignableRole";
 // Default membership-list query handler name. Accepted coupling, same
 // pattern as FILE_PROVIDER_CONFIG_KEY — the `tenant` feature registers a handler under this literal.
 export const TENANT_MEMBERSHIPS_QUERY = "tenant:query:memberships";

package/dist/engine/feature-ast/extractors/index.d.ts

@@ -8,7 +8,7 @@ export { findImportBindingForLocalName, resolveModuleFile, } from "./resolve-imp
 export { extractDescribe, extractOptionalRequires, extractReadsConfig, extractRequires, extractSystemScope, extractToggleable, extractUiHints, } from "./round1.js";
 export { extractEntity, extractNav, extractRelation, extractWorkspace, } from "./round2.js";
 export { extractClaimKey, extractConfig, extractMetric, extractReferenceData, extractSecret, extractTranslations, extractUseExtension, isClaimKeyType, type NamedOptionsResult, readNamedOptions, } from "./round3.js";
-export { extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractStoreTable, extractUsesApi, } from "./round5.js";
+export { extractBootCheck, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractStoreTable, extractUsesApi, } from "./round5.js";
 export { extractTreeActions } from "./round6.js";
 export type { ExtractOutput } from "./shared.js";
 export { fail, findFunctionLiteral, isPlainObject, ok, readBooleanProperty, readDataLiteralNode, readNameOrRef, readNameOrRefOrList, readObjectPropertyInitializer, readPropertyKey, readStringLiteralArgs, readVarargsOrArrayProp, resolveSameFileObjectLiteral, } from "./shared.js";

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

@@ -8,6 +8,6 @@ export { findImportBindingForLocalName, resolveModuleFile, } from "./resolve-imp
 export { extractDescribe, extractOptionalRequires, extractReadsConfig, extractRequires, extractSystemScope, extractToggleable, extractUiHints, } from "./round1.js";
 export { extractEntity, extractNav, extractRelation, extractWorkspace, } from "./round2.js";
 export { extractClaimKey, extractConfig, extractMetric, extractReferenceData, extractSecret, extractTranslations, extractUseExtension, isClaimKeyType, readNamedOptions, } from "./round3.js";
-export { extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractStoreTable, extractUsesApi, } from "./round5.js";
+export { extractBootCheck, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractStoreTable, extractUsesApi, } from "./round5.js";
 export { extractTreeActions } from "./round6.js";
 export { fail, findFunctionLiteral, isPlainObject, ok, readBooleanProperty, readDataLiteralNode, readNameOrRef, readNameOrRefOrList, readObjectPropertyInitializer, readPropertyKey, readStringLiteralArgs, readVarargsOrArrayProp, resolveSameFileObjectLiteral, } from "./shared.js";

package/dist/engine/feature-ast/extractors/round5.d.ts

@@ -6,3 +6,4 @@ export declare function extractExtendsRegistrar(call: CallExpression, sourceFile
 export declare function extractUsesApi(call: CallExpression, sourceFile: SourceFile): ExtractOutput<UsesApiPattern>;
 export declare function extractExposesApi(call: CallExpression, sourceFile: SourceFile): ExtractOutput<ExposesApiPattern>;
 export declare function extractStoreTable(call: CallExpression, sourceFile: SourceFile): ExtractOutput<never>;
+export declare function extractBootCheck(call: CallExpression, sourceFile: SourceFile): ExtractOutput<never>;

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

@@ -61,3 +61,8 @@ export function extractStoreTable(call, sourceFile) {
     // UnknownPattern) marks it design-time-unreadable, like entity-by-identifier.
     return fail("storeTable", sourceLocationFromNode(call, sourceFile), "storeTable meta is a factory/identifier argument, not a static literal");
 }
+export function extractBootCheck(call, sourceFile) {
+    // The argument is a runtime closure over the composed feature list —
+    // nothing to extract statically, so a clean ParseError like storeTable.
+    return fail("bootCheck", sourceLocationFromNode(call, sourceFile), "bootCheck takes a runtime closure, not a static literal");
+}

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

@@ -21,7 +21,7 @@
 // Per-pattern extractors fill in iteratively (C1.5) — each round adds
 // one extractor + a focused test.
 import { Project, SyntaxKind } from "ts-morph";
-import { extractAiClassify, extractAiExtract, extractAiGenerate, extractAuthClaims, extractClaimKey, extractConfig, extractDefineEvent, extractDescribe, extractEntity, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractHook, extractHttpRoute, extractJob, extractMetric, extractMultiStreamProjection, extractNav, extractNotification, extractOptionalRequires, extractProjection, extractQueryHandler, extractReadsConfig, extractReferenceData, extractRelation, extractRequires, extractScreen, extractSecret, extractStoreTable, extractStreamHandler, extractSystemScope, extractToggleable, extractTranslations, extractTreeActions, extractUiHints, extractUseExtension, extractUsesApi, extractWorkspace, extractWriteHandler, findFunctionLiteral, findImportBindingForLocalName, readObjectPropertyInitializer, resolveModuleFile, resolveSameFileObjectLiteral, } from "./extractors/index.js";
+import { extractAiClassify, extractAiExtract, extractAiGenerate, extractAuthClaims, extractBootCheck, extractClaimKey, extractConfig, extractDefineEvent, extractDescribe, extractEntity, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractHook, extractHttpRoute, extractJob, extractMetric, extractMultiStreamProjection, extractNav, extractNotification, extractOptionalRequires, extractProjection, extractQueryHandler, extractReadsConfig, extractReferenceData, extractRelation, extractRequires, extractScreen, extractSecret, extractStoreTable, extractStreamHandler, extractSystemScope, extractToggleable, extractTranslations, extractTreeActions, extractUiHints, extractUseExtension, extractUsesApi, extractWorkspace, extractWriteHandler, findFunctionLiteral, findImportBindingForLocalName, readObjectPropertyInitializer, resolveModuleFile, resolveSameFileObjectLiteral, } from "./extractors/index.js";
 import { sourceLocationFromNode } from "./source-location.js";
 /**
  * Parse the given feature file and return all recognised r.* calls
@@ -440,6 +440,8 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractExposesApi(call, sourceFile);
         case "storeTable":
             return extractStoreTable(call, sourceFile);
+        case "bootCheck":
+            return extractBootCheck(call, sourceFile);
         // Round 6 — Tree-Actions pattern
         case "treeActions":
             return extractTreeActions(call, sourceFile);

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

@@ -5,6 +5,24 @@ import { registerEntityCrud } from "./entity-handlers.js";
 import { resolveName } from "./handler-helpers.js";
 import { splitNamedDefinition } from "./object-form.js";
 const CRUD_VERBS = new Set(["create", "update", "delete"]);
+const CRUD_REGISTERED_VERBS = new Set([...CRUD_VERBS, "restore", "list", "detail"]);
+// A silent overwrite would drop framework behaviour that rides on the r.crud
+// handlers (e.g. writeOnly masking), so a same-name registration fails loudly.
+function assertHandlerNameFree(state, featureName, kind, handlerName) {
+    const registered = kind === "write" ? state.writeHandlers : state.queryHandlers;
+    // skip: a free name is the normal case
+    if (!Object.hasOwn(registered, handlerName))
+        return;
+    const [entityName, verb] = handlerName.split(":");
+    const crudShaped = entityName !== undefined &&
+        verb !== undefined &&
+        state.entities[entityName] !== undefined &&
+        CRUD_REGISTERED_VERBS.has(verb);
+    throw new Error(`Feature "${featureName}" registers the ${kind} handler "${handlerName}" twice.` +
+        (crudShaped
+            ? ` r.crud("${entityName}", ...) already registers that name; use a distinct name or drop the "${verb}" verb from r.crud.`
+            : " Use a distinct name."));
+}
 // Map handler name to entity via colon convention.
 // "task:create" → entity "task". Bare CRUD verbs (create/update/delete) map
 // when feature name matches an entity or the feature owns exactly one entity.
@@ -70,6 +88,7 @@ export function buildEntityHandlerMethods(state, name) {
         writeHandler(nameOrDef, schema, handler, options) {
             if (typeof nameOrDef === "object") {
                 const def = nameOrDef;
+                assertHandlerNameFree(state, name, "write", def.name);
                 state.writeHandlers[def.name] = {
                     name: def.name,
                     schema: def.schema,
@@ -101,6 +120,7 @@ export function buildEntityHandlerMethods(state, name) {
                 return { name: def.name };
             }
             const inline = requireInlineHandlerArgs("writeHandler", schema, handler, options);
+            assertHandlerNameFree(state, name, "write", nameOrDef);
             state.writeHandlers[nameOrDef] = {
                 name: nameOrDef,
                 schema: inline.schema,
@@ -116,6 +136,7 @@ export function buildEntityHandlerMethods(state, name) {
         queryHandler(nameOrDef, schema, handler, options) {
             if (typeof nameOrDef === "object") {
                 const def = nameOrDef;
+                assertHandlerNameFree(state, name, "query", def.name);
                 state.queryHandlers[def.name] = {
                     name: def.name,
                     schema: def.schema,
@@ -137,6 +158,7 @@ export function buildEntityHandlerMethods(state, name) {
                 return { name: def.name };
             }
             const inline = requireInlineHandlerArgs("queryHandler", schema, handler, options);
+            assertHandlerNameFree(state, name, "query", nameOrDef);
             state.queryHandlers[nameOrDef] = {
                 name: nameOrDef,
                 schema: inline.schema,