@cosmicdrift/kumiko-framework 0.48.1 → 0.51.0

package/src/engine/build-config-feature-schema.ts

@@ -0,0 +1,228 @@
+// Self-Populating Settings-Hub (config-provisioning Phase 2).
+//
+// Leitet aus den im Registry deklarierten Config-Keys automatisch die
+// Settings-UI ab: pro Audience (scope) einen Parent-Nav, pro (Feature ×
+// scope) einen configEdit-Screen + Child-Nav darunter. Kein manuelles
+// r.screen/r.nav am App-Author.
+//
+// Sichtbar wird nur ein Key MIT `mask` (siehe ConfigKeyDefinition): mask ist
+// die per-Key-Intent „user-facing Einstellung" und trägt zugleich das Label
+// (mask.title, ein i18n-Key). Keys ohne mask sind internes Plumbing
+// (ENV-provisioniert/computed) und erscheinen nicht.
+//
+// Die erzeugten Screens/Navs werden von buildAppSchema in die FeatureSchema
+// des config-Features (featureName "config") gemerged — der Renderer
+// qualifiziert die kurzen ids/refs mit "config". Daher hier durchweg KURZE
+// ids/parent/screen-Refs (buildNavRegistrySliceForApp qualifiziert selbst).
+
+import type { WorkspaceSchema } from "../ui-types";
+import type { ConfigScope } from "./constants";
+import {
+  createBooleanField,
+  createNumberField,
+  createSelectField,
+  createTextField,
+} from "./factories";
+import type { ConfigKeyDefinition } from "./types/config";
+import type { Registry } from "./types/feature";
+import type { FieldDefinition } from "./types/fields";
+import type { AccessRule } from "./types/handlers";
+import type { NavDefinition } from "./types/nav";
+import type {
+  ConfigEditScreenDefinition,
+  EditFieldsSection,
+  ScreenDefinition,
+} from "./types/screen";
+
+// Namespace, unter dem buildAppSchema die generierten Screens/Navs einhängt
+// (find-or-create FeatureSchema). MUSS gleich CONFIG_FEATURE aus dem config
+// bundled-feature sein — framework kann das const nicht importieren (Richtung
+// bundled-features → framework), darum hier gepinnt + Pin-Test bundled-seitig.
+export const SETTINGS_HUB_FEATURE = "config";
+// Eigene Workspace nur für workspace-mode-Apps (siehe buildAppSchema): Settings
+// erscheinen als eigener Switcher-Eintrag, statt die kuratierten App-Workspaces
+// zu verschmutzen. Apps ohne Workspaces zeigen die Navs über den no-filter-Pfad.
+export const SETTINGS_HUB_WORKSPACE = "settings";
+
+export type ConfigFeatureSchema = {
+  readonly screens: readonly ScreenDefinition[];
+  readonly navs: readonly NavDefinition[];
+  // Fertige Settings-Workspace mit qualifizierten navMembers. Nur present
+  // wenn mind. ein Key opt-in via mask hat; buildAppSchema hängt sie NUR an
+  // wenn die App bereits Workspaces nutzt (sonst kippt eine workspace-lose
+  // App in den Filter-Modus und verliert alle übrigen Navs).
+  readonly workspace?: WorkspaceSchema;
+};
+
+// Audience-Reihenfolge im Sidebar: Plattform vor Tenant vor Benutzer.
+const SCOPE_ORDER: Record<ConfigScope, number> = { system: 10, tenant: 20, user: 30 };
+
+type MaskedKey = {
+  readonly qn: string;
+  readonly feature: string;
+  readonly shortKey: string;
+  readonly def: ConfigKeyDefinition;
+};
+
+export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchema {
+  const masked = collectMaskedKeys(registry);
+  if (masked.length === 0) return { screens: [], navs: [] };
+
+  const screens: ScreenDefinition[] = [];
+  const navs: NavDefinition[] = [];
+
+  for (const scope of scopesPresent(masked)) {
+    const scopeKeys = masked.filter((k) => k.def.scope === scope);
+
+    // Audience-Parent: Gruppierungs-Knoten ohne Screen.
+    navs.push({
+      id: `audience-${scope}`,
+      label: `config.settings.${scope}`,
+      order: SCOPE_ORDER[scope],
+      access: unionEditAccess(scopeKeys.map((k) => k.def)),
+    });
+
+    for (const feature of featuresPresent(scopeKeys)) {
+      const group = scopeKeys.filter((k) => k.feature === feature);
+      const ordered = sortByMaskOrder(group);
+      const shortId = `${feature}-${scope}`;
+
+      screens.push(buildScreen(shortId, scope, feature, ordered));
+      navs.push({
+        id: shortId,
+        label: `${feature}.settings`,
+        parent: `audience-${scope}`,
+        screen: shortId,
+        order: minMaskOrder(group),
+        access: unionEditAccess(group.map((k) => k.def)),
+      });
+    }
+  }
+
+  return { screens, navs, workspace: buildSettingsWorkspace(navs, masked) };
+}
+
+// navMembers tragen die QUALIFIZIERTEN Nav-QNs (siehe build-app-schema.test:
+// admin.navMembers === ["orders:nav:list", ...]). Die generierten Navs leben
+// unter SETTINGS_HUB_FEATURE, also `config:nav:<shortId>`. Sortiert = stabile
+// Landing-Screen-Wahl (firstNavScreenId iteriert navMembers der Reihe nach).
+function buildSettingsWorkspace(
+  navs: readonly NavDefinition[],
+  masked: readonly MaskedKey[],
+): WorkspaceSchema {
+  const navMembers = navs.map((n) => `${SETTINGS_HUB_FEATURE}:nav:${n.id}`).sort();
+  return {
+    definition: {
+      id: SETTINGS_HUB_WORKSPACE,
+      label: "config.settings.title",
+      icon: "settings",
+      order: 1000,
+      // Union der Schreib-Rollen aller Hub-Keys — sonst sieht ein
+      // unprivilegierter User einen leeren "Settings"-Switcher-Eintrag.
+      access: unionEditAccess(masked.map((k) => k.def)),
+    },
+    navMembers,
+  };
+}
+
+function buildScreen(
+  shortId: string,
+  scope: ConfigScope,
+  feature: string,
+  keys: readonly MaskedKey[],
+): ConfigEditScreenDefinition {
+  const configKeys: Record<string, string> = {};
+  const fields: Record<string, FieldDefinition> = {};
+  const fieldLabels: Record<string, string> = {};
+  for (const k of keys) {
+    configKeys[k.shortKey] = k.qn;
+    fields[k.shortKey] = deriveField(k.def);
+    // mask is the visibility gate, so collectMaskedKeys guarantees it here.
+    if (k.def.mask) fieldLabels[k.shortKey] = k.def.mask.title;
+  }
+  const section: EditFieldsSection = {
+    title: `${feature}.settings`,
+    fields: keys.map((k) => k.shortKey),
+  };
+  return {
+    id: shortId,
+    type: "configEdit",
+    scope,
+    configKeys,
+    fields,
+    fieldLabels,
+    layout: { sections: [section] },
+    access: unionEditAccess(keys.map((k) => k.def)),
+  };
+}
+
+function deriveField(def: ConfigKeyDefinition): FieldDefinition {
+  switch (def.type) {
+    case "number":
+      return createNumberField();
+    case "boolean":
+      return createBooleanField();
+    case "select":
+      return def.options !== undefined && def.options.length > 0
+        ? createSelectField({ options: def.options })
+        : createTextField();
+    default:
+      return createTextField();
+  }
+}
+
+function collectMaskedKeys(registry: Registry): MaskedKey[] {
+  const out: MaskedKey[] = [];
+  for (const [qn, def] of registry.getAllConfigKeys()) {
+    // computed keys derive their value — there is no row to set, so a
+    // configEdit screen could not write them. Skip even when masked.
+    if (def.mask === undefined || def.computed !== undefined) continue;
+    const sep = qn.indexOf(":config:");
+    if (sep === -1) continue;
+    out.push({
+      qn,
+      feature: qn.slice(0, sep),
+      shortKey: qn.slice(sep + ":config:".length),
+      def,
+    });
+  }
+  return out;
+}
+
+function scopesPresent(keys: readonly MaskedKey[]): ConfigScope[] {
+  const set = new Set<ConfigScope>(keys.map((k) => k.def.scope));
+  return [...set].sort((a, b) => (SCOPE_ORDER[a] ?? 0) - (SCOPE_ORDER[b] ?? 0));
+}
+
+function featuresPresent(keys: readonly MaskedKey[]): string[] {
+  return [...new Set(keys.map((k) => k.feature))].sort();
+}
+
+function sortByMaskOrder(keys: readonly MaskedKey[]): MaskedKey[] {
+  return [...keys].sort(
+    (a, b) => maskOrder(a) - maskOrder(b) || a.shortKey.localeCompare(b.shortKey),
+  );
+}
+
+function maskOrder(k: MaskedKey): number {
+  return k.def.mask?.order ?? 0;
+}
+
+function minMaskOrder(keys: readonly MaskedKey[]): number {
+  return Math.min(...keys.map(maskOrder));
+}
+
+// Der Hub ist zum Editieren — wer mindestens einen Key der Gruppe SCHREIBEN
+// darf, sieht den Settings-Eintrag (write, nicht read). Das hält system-scope
+// (write default `["system"]`) human-hidden bis der Autor write: SystemAdmin
+// opt-int, und zeigt user-scope (write `all`) jedem. `all` lässt sich in
+// AccessRule nur als openToAll ausdrücken; der Write bleibt server-seitig
+// per Key gegated.
+function unionEditAccess(defs: readonly ConfigKeyDefinition[]): AccessRule {
+  const roles = new Set<string>();
+  for (const def of defs) {
+    for (const role of def.access.write) roles.add(role);
+  }
+  if (roles.has("all")) return { openToAll: true };
+  return { roles: [...roles] };
+}

package/src/engine/config-helpers.ts

@@ -1,9 +1,11 @@
 import type { ConfigScope } from "./constants";
 import type {
+  ConfigBacking,
   ConfigBounds,
   ConfigComputedFn,
   ConfigKeyDefinition,
   ConfigKeyType,
+  ConfigMask,
   ConfigSeedDef,
   ConfigValue,
   CreateSeedOptions,
@@ -43,6 +45,18 @@ export const access = {
 // `allowPerRequest` is conditional against `text`: text keys can never
 // opt in to per-request overrides (XSS/SQL/Shell risk). For other types
 // it's a plain boolean opt-in consumed by resolveConfigOrParam.
+//
+// Provisioning metadata (optional, available on every scope so a key never
+// switches factory to gain it):
+//   `env`              binds an ENV var as the boot-time default (the
+//                      ENV→app-override bridge reads keyDef.env).
+//   `inheritedToTenant` default true; false redacts the inherited system
+//                      value from tenant-side reads (e.g. SMTP creds).
+//   `backing`          storage backing; "secrets" routes the key through the
+//                      secrets store. backing×scope rules are enforced at
+//                      boot, not by this type (secrets don't cascade).
+//   `mask`             marks the key as a user-facing setting → the
+//                      Settings-Hub derives its screen+nav. Absent = internal.
 type ConfigKeyOptions<T extends ConfigKeyType> = {
   write?: readonly string[];
   read?: readonly string[];
@@ -50,9 +64,18 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
   encrypted?: boolean;
   options?: readonly string[]; // for select type
   bounds?: T extends "number" ? ConfigBounds : never;
+  // Regex enforced at write (set.write) — only meaningful for text keys
+  // (never for the other type-tags). Use anchored + length-bounded patterns:
+  // the value is tenant-supplied, so an unbounded backtracking regex is a
+  // ReDoS vector. See ConfigKeyDefinition.pattern.
+  pattern?: T extends "text" ? { regex: string; flags?: string } : never;
   computed?: ConfigComputedFn<T>;
   allowPerRequest?: T extends "text" ? never : boolean;
   required?: boolean;
+  env?: string;
+  inheritedToTenant?: boolean;
+  backing?: ConfigBacking;
+  mask?: ConfigMask;
 };
 
 // --- Scope Defaults ---
@@ -82,9 +105,14 @@ function createConfigKey<T extends ConfigKeyType>(
     ...(opts.encrypted ? { encrypted: true } : {}),
     ...(opts.options ? { options: opts.options } : {}),
     bounds: opts.bounds as ConfigBounds | undefined, // @cast-boundary schema-walk
+    ...(opts.pattern ? { pattern: opts.pattern } : {}),
     computed: opts.computed,
     ...(opts.allowPerRequest === true ? { allowPerRequest: true } : {}),
     ...(opts.required === true ? { required: true } : {}),
+    ...(opts.env ? { env: opts.env } : {}),
+    ...(opts.inheritedToTenant === false ? { inheritedToTenant: false } : {}),
+    ...(opts.backing === "secrets" ? { backing: "secrets" } : {}),
+    ...(opts.mask ? { mask: opts.mask } : {}),
   };
 }
 
@@ -92,6 +120,7 @@ function createConfigKey<T extends ConfigKeyType>(
 // Generic on the type-tag so `r.config({keys})` can propagate it into the
 // returned `ConfigKeyHandle<T>` — that's what narrows `ctx.config(handle)`.
 
+// @wrapper-known semantic-alias
 export function createTenantConfig<T extends ConfigKeyType>(
   type: T,
   opts?: ConfigKeyOptions<T>,
@@ -99,6 +128,7 @@ export function createTenantConfig<T extends ConfigKeyType>(
   return createConfigKey("tenant", type, opts);
 }
 
+// @wrapper-known semantic-alias
 export function createSystemConfig<T extends ConfigKeyType>(
   type: T,
   opts?: ConfigKeyOptions<T>,
@@ -106,6 +136,7 @@ export function createSystemConfig<T extends ConfigKeyType>(
   return createConfigKey("system", type, opts);
 }
 
+// @wrapper-known semantic-alias
 export function createUserConfig<T extends ConfigKeyType>(
   type: T,
   opts?: ConfigKeyOptions<T>,

package/src/engine/define-handler.ts

@@ -122,6 +122,7 @@ export function defineWriteHandler<
 
   if ("perform" in def && def.perform !== undefined) {
     const performDef = def.perform;
+    // @wrapper-known semantic-alias
     const compiledHandler = async (
       event: WriteEvent<z.infer<TSchema>>,
       ctx: HandlerContext<TMap>,

package/src/engine/entity-handlers.ts

@@ -261,6 +261,7 @@ export function defineEntityQueryHandler(
 
 type EntityHandlerOptions = { readonly access?: AccessRule };
 
+// @wrapper-known semantic-alias
 export function defineEntityCreateHandler(
   entityName: string,
   entity: EntityDefinition,
@@ -269,6 +270,7 @@ export function defineEntityCreateHandler(
   return defineEntityWriteHandler(`${entityName}:create`, entity, options);
 }
 
+// @wrapper-known semantic-alias
 export function defineEntityUpdateHandler(
   entityName: string,
   entity: EntityDefinition,
@@ -277,6 +279,7 @@ export function defineEntityUpdateHandler(
   return defineEntityWriteHandler(`${entityName}:update`, entity, options);
 }
 
+// @wrapper-known semantic-alias
 export function defineEntityDeleteHandler(
   entityName: string,
   entity: EntityDefinition,
@@ -285,6 +288,7 @@ export function defineEntityDeleteHandler(
   return defineEntityWriteHandler(`${entityName}:delete`, entity, options);
 }
 
+// @wrapper-known semantic-alias
 export function defineEntityRestoreHandler(
   entityName: string,
   entity: EntityDefinition,
@@ -293,6 +297,7 @@ export function defineEntityRestoreHandler(
   return defineEntityWriteHandler(`${entityName}:restore`, entity, options);
 }
 
+// @wrapper-known semantic-alias
 export function defineEntityListHandler(
   entityName: string,
   entity: EntityDefinition,
@@ -301,6 +306,7 @@ export function defineEntityListHandler(
   return defineEntityQueryHandler(`${entityName}:list`, entity, options);
 }
 
+// @wrapper-known semantic-alias
 export function defineEntityDetailHandler(
   entityName: string,
   entity: EntityDefinition,
@@ -359,7 +365,7 @@ export function defineProjectionQueryHandler(
       ctx.queryProjection(
         projectionQualifiedName,
         options?.unsafeAllTenants ? { unsafeAllTenants: true } : undefined,
-      ),
+      ), // @wrapper-known semantic-alias
     ...(options?.access && { access: options.access }),
   };
 }

package/src/engine/feature-manifest.ts

@@ -6,6 +6,7 @@
 // AST-Parser kann die imperativen Factory-Helper der bundled features nicht
 // lesen.
 
+import { compareByCodepoint } from "../utils";
 import type { Registry } from "./types/feature";
 
 export type ManifestConfigKey = {
@@ -18,6 +19,10 @@ export type ManifestConfigKey = {
   readonly computed: boolean;
   readonly options: readonly string[] | null;
   readonly bounds: { readonly min?: number; readonly max?: number } | null;
+  // Serializable write-time validator for type="text" keys (hex/https/length).
+  // Carried into the manifest as ConfigKeyDefinition.pattern's JSDoc promises
+  // (feature-manifest, docgen) — was previously dropped by this serializer.
+  readonly pattern: { readonly regex: string; readonly flags?: string } | null;
   readonly writeRoles: readonly string[];
   readonly readRoles: readonly string[];
 };
@@ -59,13 +64,6 @@ export type FeatureManifest = {
 
 const CONFIG_SEGMENT = ":config:";
 
-// Codepoint order, not localeCompare: the manifest is serialized to byte-exact
-// JSON, and localeCompare's ordering depends on the runner's ICU locale → drift
-// between macOS-dev and Linux-CI (#330).
-function compareByCodepoint(a: string, b: string): number {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
-
 export type BuildManifestOptions = {
   /** Herkunfts-Beschreibung fürs Manifest (landet 1:1 im JSON). */
   readonly source: string;
@@ -102,6 +100,7 @@ export function buildManifestFromRegistry(
         computed: def.computed !== undefined,
         options: def.options ?? null,
         bounds: def.bounds ?? null,
+        pattern: def.pattern ?? null,
         writeRoles: def.access.write,
         readRoles: def.access.read,
       });

package/src/engine/index.ts

@@ -3,6 +3,12 @@
 export { hasAccess } from "./access";
 export { validateBoot } from "./boot-validator";
 export { buildAppSchema } from "./build-app-schema";
+export type { ConfigFeatureSchema } from "./build-config-feature-schema";
+export {
+  buildConfigFeatureSchema,
+  SETTINGS_HUB_FEATURE,
+  SETTINGS_HUB_WORKSPACE,
+} from "./build-config-feature-schema";
 export { buildTarget } from "./build-target";
 export {
   access,
@@ -215,6 +221,7 @@ export type {
   ConcurrencyMode,
   ConfigAccessor,
   ConfigAccessorFactory,
+  ConfigBacking,
   ConfigCascade,
   ConfigCascadeLevel,
   ConfigDefinition,
@@ -223,8 +230,10 @@ export type {
   ConfigKeyDefinition,
   ConfigKeyHandle,
   ConfigKeyType,
+  ConfigMask,
   ConfigResolver,
   ConfigScope,
+  ConfigSecretsReader,
   ConfigSeedDef,
   ConfigStoredRow,
   ConfigStoredRowWithSource,

package/src/engine/pipeline.ts

@@ -80,6 +80,7 @@ export function pipeline<TPayload = unknown, TData = unknown>(
 
 // Internal: invoked by run-pipeline.ts to materialise the step list.
 // Not exported from the engine barrel — pipeline-internal plumbing.
+// @wrapper-known semantic-alias
 export function buildPipelineSteps<TPayload>(
   pipelineDef: PipelineDef<TPayload>,
   event: WriteEvent<TPayload>,

package/src/engine/qualified-name.ts

@@ -92,6 +92,7 @@ export function isValidQn(value: string): boolean {
 // True if `name` is a valid QN segment (lowercase letters, digits, dashes;
 // starts with a letter). Same rule as `QN_SEGMENT` — kept public so feature
 // registration can reject bad names at the source instead of at registry-boot.
+// @wrapper-known semantic-alias
 export function isKebabSegment(name: string): boolean {
   return QN_SEGMENT.test(name);
 }

package/src/engine/state-machine.ts

@@ -61,6 +61,7 @@ export function defineTransitions<const TMap extends Record<string, readonly str
  * nutzen. Beides ist erlaubt; die Method-Form auf dem Graph ist die
  * idiomatische API für neuen Code.
  */
+// @wrapper-known semantic-alias
 export function guardTransition<TStates extends string>(
   transitions: TransitionGraph<TStates>,
   from: TStates,

package/src/engine/steps/compute.ts

@@ -27,7 +27,7 @@ defineStep<ComputeStepArgs, unknown>({
   kind: "compute",
   defaultFailureStrategy: "throw",
   resultKey: (args) => args.name,
-  run: (args, ctx) => args.fn(ctx),
+  run: (args, ctx) => args.fn(ctx), // @wrapper-known semantic-alias
 });
 
 export function buildComputeStep<TResult>(

package/src/engine/steps/return.ts

@@ -23,6 +23,7 @@ defineStep<ReturnStepArgs, WriteResult<unknown>>({
   kind: "return",
   defaultFailureStrategy: "throw",
   resultKey: () => RETURN_RESULT_KEY,
+  // @wrapper-known semantic-alias
   run: (args, ctx: PipelineCtx) => resolveRequired(args.resolver, ctx),
 });
 

package/src/engine/types/config.ts

@@ -66,6 +66,23 @@ export type ConfigComputedFn<T extends ConfigKeyType = ConfigKeyType> = (
   ctx: ConfigComputedContext,
 ) => Promise<ConfigValue<T>>;
 
+// Storage-Backing eines provisionierten Config-Keys. "config" (Default) =
+// config_values-Projektion mit voller Cascade (user→tenant→system→app→default).
+// "secrets" = read_tenant_secrets (flach pro (tenant,key), AES-GCM-Envelope mit
+// Rotation/Audit, KEINE Cascade) — nur sinnvoll für scope:system ohne
+// Tenant-Override. Die backing×scope-Matrix erzwingt der boot-validator.
+export type ConfigBacking = "config" | "secrets";
+
+// Minimal read surface the config resolver needs to dispatch a
+// backing="secrets" key to the secrets store, without coupling the engine
+// types to the full SecretsContext. The app's `ctx.secrets` (a SecretsContext)
+// is structurally assignable. Threaded per-call (not at resolver construction)
+// because the resolver is framework-auto-created while `ctx.secrets` is
+// app-provided — only the request context sees both.
+export type ConfigSecretsReader = {
+  get(tenantId: TenantId, key: string): Promise<{ readonly reveal: () => string } | undefined>;
+};
+
 export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
   readonly type: T;
   readonly default?: ConfigValue<T>;
@@ -74,6 +91,15 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
   readonly encrypted?: boolean;
   readonly options?: readonly string[];
   readonly bounds?: ConfigBounds;
+  // Per-key string-pattern validation for type="text". The value must match
+  // the regex at write time — set.write hard-rejects a mismatch with
+  // ValidationError("invalid_format"), same posture as bounds. Stored as a
+  // serializable {regex, flags} pair (not a RegExp/predicate) so it survives
+  // JSON like `bounds`/`options` (feature-manifest, docgen) and compiles per
+  // write via new RegExp. Keep patterns anchored + length-bounded: the value
+  // is tenant-supplied (untrusted), an unbounded catastrophic-backtracking
+  // regex applied to it would be a ReDoS vector.
+  readonly pattern?: { readonly regex: string; readonly flags?: string };
   readonly computed?: ConfigComputedFn<T>;
   // Per-Request opt-in. Default false — resolveConfigOrParam wirft für
   // Keys ohne diese Marke, auch wenn der Caller paramValue übergibt. Das
@@ -91,6 +117,34 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
   // config:query:readiness; keep in sync with the feature's requireNonEmpty
   // calls in its build-fn.
   readonly required?: boolean;
+
+  // --- Provisioning-Metadata (optional auf createTenant/System/UserConfig) ---
+  // ENV-Var-Name, dessen Wert beim Boot als app-override-Default dieses Keys
+  // gebrückt wird. Reiner Fallback — überschreibt keinen gesetzten Row.
+  readonly env?: string;
+  // false → der geerbte system-row-Wert wird für Tenant-Admins redigiert
+  // (cascade.query + values.query): der Tenant sieht weder den Wert noch dass
+  // er gesetzt ist, nur den eigenen Override. Greift quell-basiert auf jeden
+  // Wert aus der system-row — nicht scope-gebunden; typischer Fall ist ein
+  // scope:tenant Key, dessen Plattform-Default in der system-row liegt (SMTP-
+  // Creds). Default true = transparente Cascade.
+  readonly inheritedToTenant?: boolean;
+  // "config" (Default, volle Cascade) oder "secrets" (flach pro (tenant,key)).
+  readonly backing?: ConfigBacking;
+  // Markiert den Key als user-facing Einstellung: der Self-Populating
+  // Settings-Hub leitet daraus automatisch Screen+Nav-Eintrag ab (kein
+  // manuelles r.screen/r.nav). Fehlt `mask`, gilt der Key als internes
+  // Plumbing (ENV-provisioniert/computed) und erscheint NICHT im Hub.
+  readonly mask?: ConfigMask;
+};
+
+// Label-Träger für den Settings-Hub. `title` ist ein i18n-Key (kein Literal —
+// Guard), `icon` ein Icon-Registry-Key für den Nav-Eintrag, `order` die
+// Sortier-Gewichtung innerhalb seiner Audience-Gruppe.
+export type ConfigMask = {
+  readonly title: string;
+  readonly icon?: string;
+  readonly order?: number;
 };
 
 export type ConfigDefinition = {
@@ -110,6 +164,10 @@ export type ConfigAccessor = {
 export type ConfigAccessorFactory = (deps: {
   readonly user: { readonly id: string; readonly tenantId: TenantId };
   readonly db: DbConnection | TenantDb;
+  // Present when the app wired `extraContext.secrets`. Lets the internal
+  // `ctx.config.get` read a backing="secrets" key transparently from the
+  // secrets store; absent → a backing="secrets" read throws loud.
+  readonly secrets?: ConfigSecretsReader;
 }) => ConfigAccessor;
 
 // Row shape returned by ConfigResolver.getAll — just enough for the
@@ -183,6 +241,7 @@ export type ConfigResolver = {
     tenantId: TenantId,
     userId: string,
     db: DbConnection | TenantDb,
+    secretsReader?: ConfigSecretsReader,
   ): Promise<string | number | boolean | undefined>;
 
   // Same cascade as get() but also reports which layer produced the value.
@@ -196,6 +255,7 @@ export type ConfigResolver = {
     tenantId: TenantId,
     userId: string,
     db: DbConnection | TenantDb,
+    secretsReader?: ConfigSecretsReader,
   ): Promise<ConfigValueWithSource>;
 
   getAll(
@@ -224,17 +284,21 @@ export type ConfigResolver = {
     tenantId: TenantId,
     userId: string,
     db: DbConnection | TenantDb,
+    secretsReader?: ConfigSecretsReader,
   ): Promise<ConfigCascade>;
 
   // Batch variant: resolves cascades for N keys in one DB round-trip.
   // keyDefs must contain definitions for every key in the keys array.
-  // Returns a map of qualifiedKey → ConfigCascade.
+  // Returns a map of qualifiedKey → ConfigCascade. backing="secrets" keys
+  // resolve their system rung from the secrets store via secretsReader
+  // (one read each — they are system-only and rare).
   getCascadeBatch(
     keys: readonly string[],
     keyDefs: ReadonlyMap<string, ConfigKeyDefinition>,
     tenantId: TenantId,
     userId: string,
     db: DbConnection | TenantDb,
+    secretsReader?: ConfigSecretsReader,
   ): Promise<ReadonlyMap<string, ConfigCascade>>;
 };
 

package/src/engine/types/index.ts

@@ -12,6 +12,7 @@ export type {
 export type {
   ConfigAccessor,
   ConfigAccessorFactory,
+  ConfigBacking,
   ConfigBounds,
   ConfigCascade,
   ConfigCascadeLevel,
@@ -22,7 +23,9 @@ export type {
   ConfigKeyDefinition,
   ConfigKeyHandle,
   ConfigKeyType,
+  ConfigMask,
   ConfigResolver,
+  ConfigSecretsReader,
   ConfigSeedDef,
   ConfigStoredRow,
   ConfigStoredRowWithSource,

package/src/engine/types/screen.ts

@@ -344,6 +344,13 @@ export type EntityEditScreenDefinition = {
    *  (History-/Audit-Erhalt): unterdrückt den Löschen-Button im
    *  Update-Form. */
   readonly allowDelete?: boolean;
+  /** Optionaler per-Field-Label-i18n-Key (Field-Name → Key), überschreibt
+   *  die Default-Konvention `<feature>:entity:<entity>:field:<name>`.
+   *  Primär für configEdit: dessen Pseudo-Entity `__config-edit__` hat
+   *  keinen natürlichen Field-Namespace — der Settings-Hub injiziert hier
+   *  das `mask.title`-Label des Config-Keys. Fehlt ein Eintrag, gilt die
+   *  Konvention. */
+  readonly fieldLabels?: Readonly<Record<string, string>>;
   readonly slots?: ScreenSlots;
   readonly access?: AccessRule;
 };
@@ -470,6 +477,12 @@ export type ConfigEditScreenDefinition = {
   /** Layout: Sections mit Field-Refs. Identisch zu entityEdit/
    *  actionForm. */
   readonly layout: EditLayout;
+  /** Optionaler per-Field-Label-i18n-Key (Field-Name → Key). Der
+   *  Settings-Hub setzt hier `mask.title` des jeweiligen Config-Keys,
+   *  damit das am Key deklarierte Label am generierten Feld erscheint —
+   *  ohne es unter der `__config-edit__`-Konvention zu duplizieren.
+   *  Fehlt ein Eintrag, gilt die Konvention. */
+  readonly fieldLabels?: Readonly<Record<string, string>>;
   /** i18n-key für den Submit-Button. Default: "kumiko.actions.save". */
   readonly submitLabel?: string;
   readonly slots?: ScreenSlots;

package/src/env/index.ts

@@ -106,6 +106,7 @@ export function getDefaultValue(field: z.ZodType): unknown {
   return undefined;
 }
 
+// @wrapper-known semantic-alias
 export function getFieldDescription(field: z.ZodType): string | undefined {
   return zodDescription(field);
 }