@cosmicdrift/kumiko-framework 0.333.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/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,

package/dist/engine/field-access.d.ts

@@ -1,4 +1,6 @@
 import type { EntityDefinition, SessionUser } from "./types/index.js";
+export declare function maskWriteOnlyFields<T extends Readonly<Record<string, unknown>>>(entity: EntityDefinition, row: T): T;
+export declare function dropEmptyWriteOnlyValues<T extends Readonly<Record<string, unknown>>>(entity: EntityDefinition, values: T): T;
 export declare function filterReadFields(entity: EntityDefinition, data: Readonly<Record<string, unknown>>, user: SessionUser): Record<string, unknown>;
 export declare function checkWriteFieldRoles(entity: EntityDefinition, changes: Readonly<Record<string, unknown>>, user: SessionUser): string | null;
 export declare function checkWriteFieldOwnership(entity: EntityDefinition, submittedChanges: Readonly<Record<string, unknown>>, user: SessionUser, oldRow?: Readonly<Record<string, unknown>>, rowContext?: Readonly<Record<string, unknown>>): string | null;

package/dist/engine/field-access.js

@@ -1,4 +1,40 @@
 import { normalizeAccessEntry, userCanReadFieldRow, userCanWriteFieldRow } from "./ownership.js";
+function writeOnlyFieldNames(entity) {
+    const names = [];
+    for (const [name, field] of Object.entries(entity.fields)) {
+        if (field.type === "text" && field.writeOnly === true)
+            names.push(name);
+    }
+    return names;
+}
+function maskWriteOnlyValue(value) {
+    return value === null || value === undefined || value === "" ? null : true;
+}
+// writeOnly text fields never leave the server as plaintext: set -> true,
+// empty -> null. Only keys present in the row are touched (a partial `changes`
+// stays partial). Returns the same object when the entity has no such field.
+export function maskWriteOnlyFields(entity, row) {
+    const names = writeOnlyFieldNames(entity);
+    if (names.length === 0)
+        return row;
+    const masked = { ...row };
+    for (const name of names) {
+        if (name in masked)
+            masked[name] = maskWriteOnlyValue(masked[name]);
+    }
+    return masked; // @cast-boundary engine-payload
+}
+// Write payloads: "" on a writeOnly field means "unchanged" (an untouched
+// masked input submits it), so the key is dropped before the executor sees it.
+export function dropEmptyWriteOnlyValues(entity, values) {
+    const names = writeOnlyFieldNames(entity).filter((name) => values[name] === "");
+    if (names.length === 0)
+        return values;
+    const kept = { ...values };
+    for (const name of names)
+        delete kept[name];
+    return kept; // @cast-boundary engine-payload
+}
 // Field-level read filtering. Returns a copy of `data` with fields stripped
 // if the user's roles don't grant read access OR the ownership-rule for the
 // matching role doesn't accept this concrete row. Fields without access
@@ -22,6 +58,10 @@ export function filterReadFields(entity, data, user) {
         if (!userCanReadFieldRow(user, accessMap, data)) {
             continue; // entire field stripped
         }
+        if (field.type === "text" && field.writeOnly === true) {
+            result[key] = maskWriteOnlyValue(value);
+            continue;
+        }
         // For embedded fields: filter sub-fields with access restrictions.
         // A list-embedded value is an array of rows — each row is filtered on its
         // own, so a sub-field rule can reference the row it sits in. Filtering the

package/dist/engine/index.d.ts

@@ -40,7 +40,7 @@ export type { AddEntityArgs, AddHookArgs, AddRelationArgs, AddWriteHandlerArgs,
 export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, groupByCategory, PATTERN_LIBRARY, parseFeatureFile, parsePatternChanges, parseSourceFile, removePattern, renderFeatureFile, renderPattern, replacePattern, updatePattern, VERSION_HEADER, } from "./feature-ast/index.js";
 export { type ChangelogEntry, type ChangelogType, compareVersions, type FeatureChangelog, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { type BuildManifestOptions, buildManifestFromRegistry, type FeatureManifest, type ManifestConfigKey, type ManifestExtension, type ManifestFeature, type ManifestSecret, serializeManifest, } from "./feature-manifest.js";
-export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, } from "./field-access.js";
+export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 export { buildSessionRoles, findForbiddenMembershipRole, isForbiddenMembershipRole, stripForbiddenMembershipRoles, } from "./membership-roles.js";

package/dist/engine/index.js

@@ -35,7 +35,7 @@ export { createBigIntField, createBooleanField, createDateField, createDecimalFi
 export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, groupByCategory, PATTERN_LIBRARY, parseFeatureFile, parsePatternChanges, parseSourceFile, removePattern, renderFeatureFile, renderPattern, replacePattern, updatePattern, VERSION_HEADER, } from "./feature-ast/index.js";
 export { compareVersions, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { buildManifestFromRegistry, serializeManifest, } from "./feature-manifest.js";
-export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, } from "./field-access.js";
+export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/

package/dist/engine/schema-builder.d.ts

@@ -3,6 +3,7 @@ import type { EntityDefinition, FieldDefinition } from "./types/index.js";
 export declare function isRepresentableAtScale(n: number, scale: number): boolean;
 export declare function fieldToZod(field: FieldDefinition, currencies: readonly string[], opts?: {
     readonly applyDefaults?: boolean;
+    readonly isUpdate?: boolean;
 }): z.ZodTypeAny;
 export declare function buildInsertSchema(entity: EntityDefinition, currencies?: readonly string[], excludedFields?: readonly string[], options?: {
     readonly allowCallerId?: boolean;

package/dist/engine/schema-builder.js

@@ -87,6 +87,13 @@ export function fieldToZod(field, currencies, opts = {}) {
             let schema = z.string();
             if (field.maxLength)
                 schema = schema.max(field.maxLength);
+            if (field.writeOnly === true) {
+                // Update: "" = unchanged (dropped before the executor), null = clear,
+                // unless required. Create: "" would leave a required field unset.
+                if (opts.isUpdate !== true)
+                    return field.required ? schema.min(1) : schema;
+                return field.required ? schema : schema.nullable();
+            }
             if (field.format === "email")
                 schema = schema.email();
             if (field.format === "url")
@@ -399,7 +406,10 @@ export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES],
         // fieldToZod still knows the default for its "" → default mapping
         // (e.g. select) — applyDefaults: false only suppresses the schema-level
         // `.default(...)` fallback for a genuinely omitted key.
-        shape[name] = fieldToZod(field, currencies, { applyDefaults: false }).optional();
+        shape[name] = fieldToZod(field, currencies, {
+            applyDefaults: false,
+            isUpdate: true,
+        }).optional();
     }
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }

package/dist/engine/types/index.d.ts

@@ -6,7 +6,7 @@ export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap,
 export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsMap, } from "@cosmicdrift/kumiko-types/extension-options-map";
 export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
-export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
+export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
 export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyFactory, NotifyFn, NotifyOptions, NotifyPriority, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
 export { isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";

package/dist/files/file-ref-entity.d.ts

@@ -9,6 +9,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -29,6 +30,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -49,6 +51,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -81,6 +84,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -101,6 +105,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -121,6 +126,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/files/file-ref-table.d.ts

@@ -9,6 +9,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -29,6 +30,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -49,6 +51,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -81,6 +84,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -101,6 +105,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -121,6 +126,7 @@ export declare const fileRefsTable: import("../db/table-builder.js").EntityTable
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/i18n/required-surface-keys.js

@@ -293,6 +293,10 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
         case "configEdit": {
             const config = screen;
             pushKey(out, config.submitLabel);
+            pushKey(out, config.description, treatDotFormAsKey);
+            for (const key of Object.values(config.fieldDescriptions ?? {})) {
+                pushKey(out, key, treatDotFormAsKey);
+            }
             for (const fieldName of Object.keys(config.fields)) {
                 const override = config.fieldLabels?.[fieldName];
                 if (override !== undefined)
@@ -308,6 +312,7 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                 if (section.kind === "relatedList")
                     continue; // rejected at boot, unreachable here
                 pushSectionTitles(out, section, treatDotFormAsKey);
+                pushKey(out, section.description, treatDotFormAsKey);
                 for (const f of sectionFieldSpecs(section)) {
                     const fieldName = editFieldName(f);
                     const override = config.fieldLabels?.[fieldName];

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

@@ -16,14 +16,28 @@ export const SETTINGS_HUB_I18N = {
     "config.settings.tenant": { en: "Tenant" },
     "config.settings.user": { en: "Personal" },
     "config.settings.extensionSelectorHint": {
-        en: "Save the provider selection to show its settings below.",
+        en: "Choose a provider and save. Its settings appear below.",
     },
+    "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.",
+    },
+    "config.settings.audience.tenant": {
+        en: "Applies to everyone in this tenant. Platform defaults are shown where nothing is set here.",
+    },
+    "config.settings.audience.user": { en: "Only applies to you." },
     "config.secrets.title": { en: "Secrets" },
     "config.secrets.notSet": { en: "Not set" },
     "config.secrets.set": { en: "Set" },
-    "config.secrets.required": { en: "Required" },
+    "config.secrets.saved": { en: "Saved" },
+    "config.secrets.section": { en: "Secrets" },
+    "config.secrets.description": {
+        en: "Stored encrypted. Saved values are never shown again.",
+    },
+    "config.secrets.stored": { en: "Stored: {preview}" },
     "config.secrets.placeholder": { en: "Enter a value" },
-    "config.secrets.replacePlaceholder": { en: "Enter a new value to replace" },
-    "config.secrets.delete": { en: "Delete" },
+    "config.secrets.replacePlaceholder": { en: "Enter a new value to replace it" },
+    "config.secrets.delete": { en: "Remove" },
     "screen:secrets.title": { en: "Secrets" },
 };

package/dist/pipeline/dispatch-batch.js

@@ -7,6 +7,7 @@ import { resolveDbSource } from "./dispatch-shared.js";
 import { executeNestedWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
 import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin.js";
+import { maskBatchResultForClient } from "./write-result-masking.js";
 // afterCommit hooks fire in flushAfterCommit, outside the command's scope.
 function rewrapHooksWithOrigin(afterCommitHooks, fromIndex, origin) {
     for (let i = fromIndex; i < afterCommitHooks.length; i++) {
@@ -51,20 +52,24 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
             idempotencyToken = checked.token;
         }
     }
+    // Hooks already ran on the plaintext results; what is returned and cached
+    // for retries must not carry writeOnly values.
+    const maskForClient = (result) => maskBatchResultForClient(ctx.registry, commands, result);
     // Cache the result under requestId so retries get the same answer. Only a
     // provably rolled-back 5xx releases the lock instead (releaseOrFinalize).
     const finalize = async (result) => {
+        const masked = maskForClient(result);
         if (requestId && idempotency && idempotencyToken) {
-            await idempotency.store(user.tenantId, user.id, requestId, idempotencyToken, result);
+            await idempotency.store(user.tenantId, user.id, requestId, idempotencyToken, masked);
         }
-        return result;
+        return masked;
     };
     // Never for the no-tx fallback: without a rollback, a re-run would repeat
     // the side effects of the commands that already ran.
     const releaseOrFinalize = async (result, isRetryableRollback) => {
         if (isRetryableRollback && requestId && idempotency && idempotencyToken) {
             await idempotency.release(user.tenantId, user.id, requestId, idempotencyToken);
-            return result;
+            return maskForClient(result);
         }
         return finalize(result);
     };

package/dist/pipeline/dispatch-write.js

@@ -5,7 +5,7 @@ import { createTenantDb, hasTenantColumn } from "../db/tenant-db.js";
 import { tenantDbRunner } from "../db/tenant-db-runner.js";
 import { hasAccess } from "../engine/access.js";
 import { ConfigScopes } from "../engine/constants.js";
-import { checkWriteFieldOwnership, checkWriteFieldRoles } from "../engine/field-access.js";
+import { checkWriteFieldOwnership, checkWriteFieldRoles, maskWriteOnlyFields, } from "../engine/field-access.js";
 import { defineTransitions, guardTransition } from "../engine/state-machine.js";
 import { HookPhases } from "../engine/types/index.js";
 import { runValidation } from "../engine/validation.js";
@@ -262,7 +262,10 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
             }
             const subWrapper = subResult.data; // @cast-boundary engine-payload
             const subRow = (subWrapper["data"] ?? subWrapper); // @cast-boundary engine-payload
-            subRows.push(subRow);
+            const subEntityName = registry.getHandlerEntity(spec.subType);
+            const subEntity = subEntityName ? registry.getEntity(subEntityName) : undefined;
+            // parentRow is returned to the client; the child's own SaveContext keeps the plaintext.
+            subRows.push(subEntity ? maskWriteOnlyFields(subEntity, subRow) : subRow);
         }
         parentRow[spec.key] = subRows;
     }

package/dist/pipeline/dispatcher-utils.js

@@ -4,8 +4,11 @@ import { VersionConflictError as EventStoreVersionConflictError } from "../event
 export function isFailedWriteResult(result) {
     return (!!result && typeof result === "object" && "isSuccess" in result && result.isSuccess === false);
 }
+const LIFECYCLE_KINDS = ["save", "delete"];
 export function isLifecycleResult(data) {
-    return !!data && typeof data === "object" && "kind" in data;
+    if (!data || typeof data !== "object" || !("kind" in data))
+        return false;
+    return LIFECYCLE_KINDS.some((kind) => kind === data.kind);
 }
 export function isWriteResultShape(result) {
     return (!!result &&

package/dist/pipeline/write-result-masking.d.ts

@@ -0,0 +1,6 @@
+import type { WriteResult } from "../engine/types/index.js";
+import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared.js";
+type EntityLookup = Pick<DispatchContext["registry"], "getHandlerEntity" | "getEntity">;
+export declare function maskWriteResultForClient(registry: EntityLookup, handlerType: string, result: WriteResult): WriteResult;
+export declare function maskBatchResultForClient(registry: EntityLookup, commands: readonly BatchCommand[], batch: BatchResult): BatchResult;
+export {};

package/dist/pipeline/write-result-masking.js

@@ -0,0 +1,36 @@
+import { maskWriteOnlyFields } from "../engine/field-access.js";
+import { isLifecycleResult } from "./dispatcher-utils.js";
+function maskLifecycleOrRow(entity, data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return data;
+    if (!isLifecycleResult(data))
+        return maskWriteOnlyFields(entity, data); // @cast-boundary engine-payload
+    if (data.kind === "save") {
+        return {
+            ...data,
+            data: maskWriteOnlyFields(entity, data.data),
+            changes: maskWriteOnlyFields(entity, data.changes),
+            previous: maskWriteOnlyFields(entity, data.previous),
+        };
+    }
+    return { ...data, data: maskWriteOnlyFields(entity, data.data) };
+}
+// Copy-on-mask: the original results still feed postSaveBatch hooks, which
+// need the plaintext. Only what leaves the dispatcher is masked.
+export function maskWriteResultForClient(registry, handlerType, result) {
+    if (!result.isSuccess)
+        return result;
+    const entityName = registry.getHandlerEntity(handlerType);
+    const entity = entityName ? registry.getEntity(entityName) : undefined;
+    if (!entity)
+        return result;
+    const data = maskLifecycleOrRow(entity, result.data);
+    return data === result.data ? result : { ...result, data };
+}
+export function maskBatchResultForClient(registry, commands, batch) {
+    const results = batch.results.map((result, index) => {
+        const command = commands[index];
+        return command ? maskWriteResultForClient(registry, command.type, result) : result;
+    });
+    return { ...batch, results };
+}

package/dist/testing/shared-entities.d.ts

@@ -9,6 +9,7 @@ export declare const sharedWidgetEntity: import("@cosmicdrift/kumiko-types/field
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -31,6 +32,7 @@ export declare const sharedWidgetTable: import("../db/table-builder.js").EntityT
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -53,6 +55,7 @@ export declare const sharedUserEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -73,6 +76,7 @@ export declare const sharedUserEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -93,6 +97,7 @@ export declare const sharedUserEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -118,6 +123,7 @@ export declare const sharedUserTable: import("../db/table-builder.js").EntityTab
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -138,6 +144,7 @@ export declare const sharedUserTable: import("../db/table-builder.js").EntityTab
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -158,6 +165,7 @@ export declare const sharedUserTable: import("../db/table-builder.js").EntityTab
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -183,6 +191,7 @@ export declare const sharedItemEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;
@@ -224,6 +233,7 @@ export declare const sharedItemTable: import("../db/table-builder.js").EntityTab
         readonly filterable?: boolean;
         readonly encrypted?: boolean;
         readonly sensitive?: boolean;
+        readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
         readonly format?: "email" | "url" | "phone" | "password";
         readonly default?: string;

package/dist/ui-types/index.d.ts

@@ -5,7 +5,7 @@ export type { ParsedRefTarget } from "../engine/parse-ref-target.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export type { FieldsOrGroupsSection } from "../engine/screen-helpers.js";
 export { evalFieldCondition, explicitListScreenId, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
-export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, NumberFieldDef, SelectFieldDef, SelectOptionTone, TextFieldDef, } from "../engine/types/fields.js";
+export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, SelectFieldDef, SelectOptionTone, TextFieldDef, } from "../engine/types/fields.js";
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.333.0",
+  "version": "0.334.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>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.333.0",
-    "@cosmicdrift/kumiko-types": "0.333.0",
+    "@cosmicdrift/kumiko-http": "0.334.0",
+    "@cosmicdrift/kumiko-types": "0.334.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.333.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.334.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.334.0",
+    "type": "improvement",
+    "title": "Settings form gaps: writeForm footer submit, option description/group, dependent optionsQueryPayload, config badge label, writeOnly secret fields",
+    "detail": "- A `writeForm` section that fills a whole tab puts its submit button into the pinned form footer.\n- `optionsQuery` rows may carry `description` (muted second line) and `group` (heading). The combobox and the radio list show both. Options with either one never render as segments.\n- `optionsQueryPayload` values may be `{ field: \"<sibling>\" }`. The select reloads when that field changes and clears a value the new rows no longer contain. A cleared config select resets the key, so the inherited value applies again. On config keys, `field` names another key of the same feature on the same settings mask. The boot validator checks the names, and `writeForm` fieldDefs now go through the select checks too.\n- The origin line and cascade level rows on `configEdit` fields show the option label instead of the raw value or id.\n- New `writeOnly: true` on entity text fields with `find: \"secret\"`. Reads return `true` (set) or `null` and never the value. On write, `\"\"` keeps the stored value and `null` clears it. The edit form shows a masked input with a \"set\" placeholder and a remove action. `maskWriteOnlyFields(entity, row)` is exported from `@cosmicdrift/kumiko-framework/engine` for custom query handlers that return executor rows."
+  },
+  {
+    "version": "0.334.0",
+    "type": "breaking",
+    "title": "Duplicate write/query handler names in one feature fail at definition time",
+    "migration": "Rename a custom handler that shares its name with another handler of the same feature, including names r.crud registers (<entity>:list, <entity>:detail, <entity>:create, <entity>:update, <entity>:delete, <entity>:restore). Before, the later registration replaced the earlier one silently."
+  },
   {
     "version": "0.332.0",
     "type": "fix",