@cosmicdrift/kumiko-framework 0.48.1 → 0.51.0

package/src/db/dialect.ts

@@ -337,10 +337,12 @@ function makeIndex(name: string, unique: boolean): IndexBuilder {
   };
 }
 
+// @wrapper-known semantic-alias
 export function index(name: string): IndexBuilder {
   return makeIndex(name, false);
 }
 
+// @wrapper-known semantic-alias
 export function uniqueIndex(name: string): IndexBuilder {
   return makeIndex(name, true);
 }
@@ -428,7 +430,7 @@ export function table<TCols extends ColumnMap>(
     const handle: ColumnHandle = {
       name: final.sqlName,
       pgType: final.pgType,
-      getSQLType: () => pgTypeToSqlType(final.pgType),
+      getSQLType: () => pgTypeToSqlType(final.pgType), // @wrapper-known semantic-alias
     };
     handles[field] = handle;
     const meta: ColumnMeta = {

package/src/db/migrate-generator.ts

@@ -17,6 +17,7 @@
 
 import { readFileSync, writeFileSync } from "node:fs";
 
+import { compareByCodepoint } from "../utils";
 import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta";
 import { renderTableDdl } from "./render-ddl";
 
@@ -56,8 +57,11 @@ export type SchemaDiff = {
 
 export function snapshotFromMetas(metas: readonly EntityTableMeta[]): Snapshot {
   // Stable ordering by tableName so the snapshot.json diff in PRs is
-  // meaningful (table-add isn't a noisy re-sort of everything).
-  const sorted = [...metas].sort((a, b) => a.tableName.localeCompare(b.tableName));
+  // meaningful (table-add isn't a noisy re-sort of everything). Codepoint, not
+  // localeCompare: the snapshot is serialized to byte-exact JSON and the table
+  // order carries into the generated migration SQL — locale-dependent ordering
+  // would drift between macOS-dev and Linux-CI (#367).
+  const sorted = [...metas].sort((a, b) => compareByCodepoint(a.tableName, b.tableName));
   return {
     version: SNAPSHOT_VERSION,
     generatedAt: new Date().toISOString(),

package/src/db/queries/event-store.ts

@@ -112,6 +112,7 @@ export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
 }
 
 /** Head event id for lag metrics — alias for selectEventsHighWaterMark. */
+// @wrapper-known semantic-alias
 export async function selectEventsHeadId(db: AnyDb): Promise<bigint> {
   return selectEventsHighWaterMark(db);
 }

package/src/engine/__tests__/boot-validator.test.ts

@@ -1521,6 +1521,26 @@ describe("boot-validator", () => {
       ).toThrow(/Config-Key "shop:config:typo-here" ist in keiner Feature-Registry deklariert/);
     });
 
+    test("camelCase-Quelle (multi-word) → kanonische kebab-QN matched, kein Throw", () => {
+      // Regression: r.config registriert den camelCase-Objekt-Key
+      // (brandingTitle), die echte QN ist aber `shop:config:branding-title`
+      // (define-feature toKebab't beides). Ein configEdit-Screen, der die
+      // kanonische kebab-QN referenziert, darf NICHT als "unbekannt" failen —
+      // ohne qualifyEntityName im Validator stand dort die rohe camelCase-QN.
+      const feature = defineFeature("shop", (r) => {
+        r.config({ keys: { brandingTitle: createTenantConfig("text", { default: "" }) } });
+        r.screen({
+          id: "settings",
+          type: "configEdit",
+          scope: "tenant",
+          configKeys: { title: "shop:config:branding-title" },
+          fields: { title: { type: "text" } } as never,
+          layout: { sections: [{ title: "Basics", fields: ["title"] }] } as never,
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+
     test("extension section ohne component → Throw (Parität zu entityEdit)", () => {
       // synthesizeConfigEditScreen reicht die layout 1:1 an RenderEdit weiter —
       // eine Extension-Section ohne react/native-Marker rendert sonst stumm leer.
@@ -2115,3 +2135,26 @@ describe("boot-validator", () => {
     });
   });
 });
+
+describe("boot-validator — config key backing × scope", () => {
+  test("rejects backing:secrets on a non-system scope (secrets do not cascade)", () => {
+    const feature = defineFeature("billing", (r) => {
+      r.config({ keys: { apiKey: createTenantConfig("text", { backing: "secrets" }) } });
+    });
+    expect(() => validateBoot([feature])).toThrow(/backing="secrets".*requires scope="system"/i);
+  });
+
+  test("allows backing:secrets when system-scoped (dispatch is wired)", () => {
+    const feature = defineFeature("billing", (r) => {
+      r.config({ keys: { apiKey: createSystemConfig("text", { backing: "secrets" }) } });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("a config key without secrets backing boots fine", () => {
+    const feature = defineFeature("billing", (r) => {
+      r.config({ keys: { apiKey: createSystemConfig("text") } });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});

package/src/engine/__tests__/build-app-schema-settings-hub.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test";
+import { buildAppSchema, findNonJsonSafePath } from "../build-app-schema";
+import { SETTINGS_HUB_FEATURE, SETTINGS_HUB_WORKSPACE } from "../build-config-feature-schema";
+import { createSystemConfig, createTenantConfig } from "../config-helpers";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+
+// A feature that opts a config key into the Settings-Hub via `mask`.
+const billing = defineFeature("billing", (r) => {
+  r.config({
+    keys: {
+      stripeKey: createTenantConfig("text", { mask: { title: "billing.stripe-key" } }),
+      platformFee: createSystemConfig("number", { mask: { title: "billing.platform-fee" } }),
+    },
+  });
+});
+
+// A config key WITHOUT mask — internal plumbing, must not surface a hub.
+const plain = defineFeature("plain", (r) => {
+  r.config({ keys: { secret: createSystemConfig("text", {}) } });
+});
+
+function configFeature(app: ReturnType<typeof buildAppSchema>) {
+  return app.features.filter((f) => f.featureName === SETTINGS_HUB_FEATURE);
+}
+
+describe("buildAppSchema — Settings-Hub wiring", () => {
+  test("app WITHOUT workspaces: hub screens/navs appear, app stays in no-filter mode (no flip)", () => {
+    const app = buildAppSchema(createRegistry([billing]));
+
+    // The decisive non-flip assertion: a workspace-less app must NOT gain
+    // workspaces — else the renderer flips into filter-mode and drops navs.
+    expect(app.workspaces).toBeUndefined();
+
+    const config = configFeature(app);
+    expect(config).toHaveLength(1); // exactly one FeatureSchema, no duplicate
+    const hub = config[0];
+    // billing has a tenant + a system masked key → two configEdit screens
+    expect(hub?.screens.map((s) => s.id).sort()).toEqual(["billing-system", "billing-tenant"]);
+    // audience parents (system, tenant) + the two children
+    expect(hub?.navs?.map((n) => n.id).sort()).toEqual([
+      "audience-system",
+      "audience-tenant",
+      "billing-system",
+      "billing-tenant",
+    ]);
+  });
+
+  test("app WITH workspaces: original workspaces kept + synthetic settings workspace appended", () => {
+    const shell = defineFeature("shell", (r) => {
+      r.screen({ id: "home", type: "entityList", entity: "thing", columns: ["label"] });
+      r.entity("thing", { fields: { label: { type: "text" } } });
+      r.nav({ id: "home", label: "Home", screen: "home" });
+      r.workspace({ id: "main", label: "Main", nav: ["shell:nav:home"] });
+    });
+
+    const app = buildAppSchema(createRegistry([shell, billing]));
+
+    expect(app.workspaces).toBeDefined();
+    const ids = app.workspaces?.map((w) => w.definition.id).sort();
+    expect(ids).toEqual(["main", SETTINGS_HUB_WORKSPACE]);
+
+    const settings = app.workspaces?.find((w) => w.definition.id === SETTINGS_HUB_WORKSPACE);
+    // navMembers are qualified QNs under the config namespace
+    expect(settings?.navMembers).toContain("config:nav:audience-tenant");
+    expect(settings?.navMembers).toContain("config:nav:billing-tenant");
+    // and the original workspace's members are untouched
+    const main = app.workspaces?.find((w) => w.definition.id === "main");
+    expect(main?.navMembers).toEqual(["shell:nav:home"]);
+  });
+
+  test("find-or-create: merges into an existing `config` feature instead of duplicating it", () => {
+    // Stand-in for the config bundled-feature: a real feature named "config"
+    // that already owns a screen/nav. The hub must fold INTO it.
+    const configBundled = defineFeature(SETTINGS_HUB_FEATURE, (r) => {
+      r.entity("config-value", { fields: { value: { type: "text" } } });
+      r.screen({ id: "existing", type: "entityList", entity: "config-value", columns: ["value"] });
+      r.nav({ id: "existing", label: "Existing", screen: "existing" });
+    });
+
+    const app = buildAppSchema(createRegistry([configBundled, billing]));
+
+    const config = configFeature(app);
+    expect(config).toHaveLength(1); // NOT two FeatureSchemas with name "config"
+    const hub = config[0];
+    // the pre-existing screen survives alongside the generated hub screens
+    expect(hub?.screens.map((s) => s.id)).toContain("existing");
+    expect(hub?.screens.map((s) => s.id)).toContain("billing-tenant");
+    expect(hub?.navs?.map((n) => n.id)).toContain("existing");
+    expect(hub?.navs?.map((n) => n.id)).toContain("audience-tenant");
+  });
+
+  test("non-breaking: config keys WITHOUT mask leave the schema hub-free", () => {
+    const app = buildAppSchema(createRegistry([plain]));
+    expect(app.workspaces).toBeUndefined();
+    const config = configFeature(app);
+    // the plain feature isn't named "config", so no config FeatureSchema is
+    // synthesized at all — the app is byte-identical to the pre-hub world.
+    expect(config).toHaveLength(0);
+  });
+
+  test("generated hub output stays JSON-safe (factory fields are pure literals)", () => {
+    const app = buildAppSchema(shellWith(billing));
+    expect(findNonJsonSafePath(app, "app")).toBeNull();
+  });
+});
+
+// Helper: an app that has a workspace AND the masked billing keys, so the
+// JSON-safety walk covers the synthetic workspace + configEdit screens too.
+function shellWith(masked: ReturnType<typeof defineFeature>) {
+  const shell = defineFeature("shell", (r) => {
+    r.entity("thing", { fields: { label: { type: "text" } } });
+    r.screen({ id: "home", type: "entityList", entity: "thing", columns: ["label"] });
+    r.nav({ id: "home", label: "Home", screen: "home" });
+    r.workspace({ id: "main", label: "Main", nav: ["shell:nav:home"] });
+  });
+  return createRegistry([shell, masked]);
+}

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

@@ -0,0 +1,174 @@
+import { describe, expect, test } from "bun:test";
+import { buildConfigFeatureSchema } from "../build-config-feature-schema";
+import { createSystemConfig, createTenantConfig, createUserConfig } from "../config-helpers";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+import type { NavDefinition } from "../types/nav";
+import type { ConfigEditScreenDefinition, ScreenDefinition } from "../types/screen";
+
+// Two features declaring masked keys across all three scopes, plus two
+// exclusion probes: an UNMASKED key (internal plumbing) and a computed+masked
+// key (no row to set). Built through the real createRegistry so the qualified
+// names come from the real qn(toKebab(...)) path, not a hand-written stub.
+const billing = defineFeature("billing", (r) => {
+  r.config({
+    keys: {
+      stripeKey: createTenantConfig("text", { mask: { title: "billing.stripe-key", order: 1 } }),
+      currency: createTenantConfig("select", {
+        options: ["eur", "usd"],
+        mask: { title: "billing.currency", order: 2 },
+      }),
+      internalFlag: createTenantConfig("boolean", {}), // no mask → excluded
+      platformFee: createSystemConfig("number", { mask: { title: "billing.platform-fee" } }),
+      derived: createTenantConfig("number", {
+        computed: async () => 5,
+        mask: { title: "billing.derived" }, // masked BUT computed → excluded
+      }),
+    },
+  });
+});
+
+const notify = defineFeature("notify", (r) => {
+  r.config({
+    keys: {
+      fromAddress: createTenantConfig("text", { mask: { title: "notify.from" } }),
+      digest: createUserConfig("boolean", { mask: { title: "notify.digest" } }),
+    },
+  });
+});
+
+const schema = buildConfigFeatureSchema(createRegistry([billing, notify]));
+
+function navById(id: string): NavDefinition | undefined {
+  return schema.navs.find((n) => n.id === id);
+}
+function configScreen(id: string): ConfigEditScreenDefinition {
+  const s: ScreenDefinition | undefined = schema.screens.find((x) => x.id === id);
+  if (!s || s.type !== "configEdit") throw new Error(`no configEdit screen "${id}"`);
+  return s;
+}
+
+describe("buildConfigFeatureSchema — structure", () => {
+  test("emits one audience parent per present scope + one child per (feature × scope)", () => {
+    // scopes present: tenant (stripe/currency/from), system (platform-fee), user (digest)
+    expect(navById("audience-system")).toBeDefined();
+    expect(navById("audience-tenant")).toBeDefined();
+    expect(navById("audience-user")).toBeDefined();
+
+    // children: billing-tenant, notify-tenant, billing-system, notify-user
+    expect(schema.screens.map((s) => s.id).sort()).toEqual([
+      "billing-system",
+      "billing-tenant",
+      "notify-tenant",
+      "notify-user",
+    ]);
+    expect(schema.navs).toHaveLength(7); // 3 audiences + 4 children
+  });
+
+  test("audience parents are grouping nodes (no screen) ordered system<tenant<user", () => {
+    const sys = navById("audience-system");
+    const ten = navById("audience-tenant");
+    const usr = navById("audience-user");
+    expect(sys?.screen).toBeUndefined();
+    expect(sys?.parent).toBeUndefined();
+    expect(ten?.label).toBe("config.settings.tenant");
+    expect((sys?.order ?? 0) < (ten?.order ?? 0) && (ten?.order ?? 0) < (usr?.order ?? 0)).toBe(
+      true,
+    );
+  });
+
+  test("child nav points to its screen under the right audience parent", () => {
+    const child = navById("billing-tenant");
+    expect(child?.parent).toBe("audience-tenant");
+    expect(child?.screen).toBe("billing-tenant");
+    expect(child?.label).toBe("billing.settings");
+  });
+
+  test("screen carries qualified configKeys, derived field types, and mask.title as fieldLabels", () => {
+    const s = configScreen("billing-tenant");
+    expect(s.scope).toBe("tenant");
+    expect(s.configKeys).toEqual({
+      "stripe-key": "billing:config:stripe-key",
+      currency: "billing:config:currency",
+    });
+    expect(s.fields["stripe-key"]?.type).toBe("text");
+    expect(s.fields["currency"]?.type).toBe("select");
+    expect((s.fields["currency"] as { options?: readonly string[] }).options).toEqual([
+      "eur",
+      "usd",
+    ]);
+    // mask.title flows to fieldLabels — the per-field label override the
+    // Settings-Hub relies on (no __config-edit__ convention duplication).
+    expect(s.fieldLabels).toEqual({
+      "stripe-key": "billing.stripe-key",
+      currency: "billing.currency",
+    });
+  });
+
+  test("fields are ordered by mask.order; section title is the feature group key", () => {
+    const s = configScreen("billing-tenant");
+    expect(s.layout.sections).toHaveLength(1);
+    const section = s.layout.sections[0];
+    expect(section && "title" in section ? section.title : undefined).toBe("billing.settings");
+    expect(section && "fields" in section ? section.fields : undefined).toEqual([
+      "stripe-key",
+      "currency",
+    ]);
+  });
+
+  test("excludes unmasked keys and computed keys", () => {
+    const s = configScreen("billing-tenant");
+    // internal-flag has no mask, derived is computed → neither appears anywhere
+    expect(Object.keys(s.configKeys)).not.toContain("internal-flag");
+    expect(Object.keys(s.configKeys)).not.toContain("derived");
+    const allConfigKeyValues = schema.screens.flatMap((x) =>
+      x.type === "configEdit" ? Object.values(x.configKeys) : [],
+    );
+    expect(allConfigKeyValues).not.toContain("billing:config:internal-flag");
+    expect(allConfigKeyValues).not.toContain("billing:config:derived");
+  });
+
+  test("access: union of write (edit) roles; an `all`-writable group collapses to openToAll", () => {
+    // billing tenant keys are createTenantConfig → write = admin roles
+    const billingTenant = configScreen("billing-tenant");
+    expect(billingTenant.access).toEqual({ roles: ["TenantAdmin", "Admin", "SystemAdmin"] });
+    // digest is createUserConfig → write access.all (["all"]) → openToAll
+    expect(configScreen("notify-user").access).toEqual({ openToAll: true });
+  });
+
+  test("returns empty (no workspace) when no key opts into the hub via mask", () => {
+    const plain = defineFeature("plain", (r) => {
+      r.config({ keys: { secret: createSystemConfig("text", {}) } });
+    });
+    const empty = buildConfigFeatureSchema(createRegistry([plain]));
+    expect(empty.screens).toHaveLength(0);
+    expect(empty.navs).toHaveLength(0);
+    expect(empty.workspace).toBeUndefined();
+  });
+
+  test("emits a settings workspace with qualified navMembers (config:nav:*) over every generated nav", () => {
+    const ws = schema.workspace;
+    expect(ws).toBeDefined();
+    expect(ws?.definition.id).toBe("settings");
+    expect(ws?.definition.label).toBe("config.settings.title");
+    expect(ws?.definition.default).toBeUndefined(); // never the login default
+    // every generated nav (parents + children) qualified under the config namespace
+    expect(ws?.navMembers).toEqual(schema.navs.map((n) => `config:nav:${n.id}`).sort());
+  });
+
+  test("workspace access is the union of write roles across all hub keys", () => {
+    // billing/notify tenant keys → admin write; notify-user digest → write all.
+    // Any `all`-writable key collapses the whole switcher entry to openToAll.
+    expect(schema.workspace?.definition.access).toEqual({ openToAll: true });
+  });
+
+  test("workspace access stays role-gated when no hub key is world-writable", () => {
+    const adminOnly = defineFeature("adminonly", (r) => {
+      r.config({ keys: { apiKey: createTenantConfig("text", { mask: { title: "a.key" } }) } });
+    });
+    const out = buildConfigFeatureSchema(createRegistry([adminOnly]));
+    expect(out.workspace?.definition.access).toEqual({
+      roles: ["TenantAdmin", "Admin", "SystemAdmin"],
+    });
+  });
+});

package/src/engine/__tests__/config-helpers.test.ts

@@ -99,6 +99,63 @@ describe("createUserConfig", () => {
   });
 });
 
+describe("config helpers — provisioning metadata (env / inheritedToTenant / backing)", () => {
+  test("env name is carried; absent → field absent", () => {
+    const bridged = createSystemConfig("text", { env: "STRIPE_SECRET_KEY" });
+    expect(bridged.env).toBe("STRIPE_SECRET_KEY");
+    expect(createSystemConfig("text").env).toBeUndefined();
+  });
+
+  test("inheritedToTenant:false attaches; default/true is omitted", () => {
+    const hidden = createSystemConfig("text", { inheritedToTenant: false });
+    expect(hidden.inheritedToTenant).toBe(false);
+
+    expect(createSystemConfig("text").inheritedToTenant).toBeUndefined();
+    expect(
+      createSystemConfig("text", { inheritedToTenant: true }).inheritedToTenant,
+    ).toBeUndefined();
+  });
+
+  test("backing:secrets is carried; default config is omitted", () => {
+    const secrets = createSystemConfig("text", { backing: "secrets" });
+    expect(secrets.backing).toBe("secrets");
+    expect(createSystemConfig("text").backing).toBeUndefined();
+    expect(createSystemConfig("text", { backing: "config" }).backing).toBeUndefined();
+  });
+
+  test("provisioning fields live on every scope factory — no factory switch to gain them", () => {
+    // The whole point of folding them in: a tenant or user key gains an env
+    // binding (or redaction) by adding a field, never by switching factory.
+    expect(createTenantConfig("text", { env: "TENANT_VAR" }).env).toBe("TENANT_VAR");
+    expect(createUserConfig("boolean", { inheritedToTenant: false }).inheritedToTenant).toBe(false);
+  });
+
+  test("Stripe-shape: system + masked + hidden-from-tenant + env + secrets in one call", () => {
+    const key = createSystemConfig("text", {
+      env: "STRIPE_SECRET_KEY",
+      encrypted: true,
+      inheritedToTenant: false,
+      backing: "secrets",
+      required: true,
+    });
+    expect(key).toMatchObject({
+      type: "text",
+      scope: "system",
+      encrypted: true,
+      inheritedToTenant: false,
+      env: "STRIPE_SECRET_KEY",
+      backing: "secrets",
+      required: true,
+    });
+  });
+
+  test("@ts-expect-error: backing only accepts the ConfigBacking union", () => {
+    // @ts-expect-error — "vault" is not a ConfigBacking ("config" | "secrets")
+    const key = createSystemConfig("text", { backing: "vault" });
+    expect(key.type).toBe("text");
+  });
+});
+
 // expectTypeOf + @ts-expect-error are the real assertions — they fail the
 // build if the helper generic widens. The expect() lines exist so the
 // fake-test guard sees runtime asserts and lint stays quiet on unused vars.

package/src/engine/boot-validator/config-deps.ts

@@ -136,6 +136,30 @@ export function validateConfigKeyAllowPerRequest(feature: FeatureDefinition): vo
   }
 }
 
+// --- Config key storage backing × scope matrix ---
+
+export function validateConfigKeyBacking(feature: FeatureDefinition): void {
+  for (const [keyName, keyDef] of Object.entries(feature.configKeys)) {
+    if (keyDef.backing !== "secrets") continue;
+
+    // secrets storage is flat per (tenant, key) with no system→tenant cascade,
+    // so a tenant- or user-scoped secret could never inherit a system default.
+    // Permanent rule: secrets-backed keys must be system-scoped.
+    if (keyDef.scope !== "system") {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has backing="secrets" but scope="${keyDef.scope}" — secrets storage is flat per (tenant,key) and does not cascade; backing="secrets" requires scope="system"`,
+      );
+    }
+
+    // system-scoped backing="secrets" is wired end-to-end: reads dispatch
+    // through the resolver's secretsReader, writes through config:write:set/
+    // :reset into the secrets store (SYSTEM_TENANT_ID), masked in the query
+    // handlers. The runtime contract is that the app provides
+    // `extraContext.secrets` (+ a MasterKeyProvider) — a backing="secrets"
+    // read/write without it throws loud at request time, not silently.
+  }
+}
+
 // --- Config key cross-feature reference validation ---
 
 export function validateConfigReads(

package/src/engine/boot-validator/index.ts

@@ -1,8 +1,10 @@
+import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
 import {
   validateCircularDeps,
   validateConfigKeyAllowPerRequest,
+  validateConfigKeyBacking,
   validateConfigKeyBounds,
   validateConfigKeyComputed,
   validateConfigKeyRequired,
@@ -57,14 +59,18 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
 
   // Collect all config keys across features (for cross-feature reference validation)
   const allConfigKeys = new Set<string>();
-  // Qualified config-key set für ConfigEditScreen-Validation. Format
-  // wie in registry.ts: `<feature>:config:<short>`. allConfigKeys oben
-  // nutzt das ältere `feature.short`-Format für validateConfigReads.
+  // Qualified config-key set für ConfigEditScreen-Validation. MUSS via
+  // qualifyEntityName kanonisiert werden (toKebab auf Feature + Key) — exakt
+  // wie define-feature/registry den QN bildet. Der rohe f.configKeys-Key ist
+  // der camelCase-Objekt-Key (`brandingTitle`), die echte QN aber
+  // `…:config:branding-title`; ohne toKebab failt jeder configEdit-Screen mit
+  // multi-word Config-Key fälschlich. allConfigKeys oben nutzt das ältere
+  // `feature.short`-Format für validateConfigReads.
   const allConfigKeyQns = new Set<string>();
   for (const f of features) {
     for (const key of Object.keys(f.configKeys)) {
       allConfigKeys.add(`${f.name}.${key}`);
-      allConfigKeyQns.add(`${f.name}:config:${key}`);
+      allConfigKeyQns.add(qualifyEntityName(f.name, QnTypes.config, key));
     }
   }
 
@@ -136,6 +142,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
     validateConfigKeyRequired(feature);
     validateConfigKeyComputed(feature);
     validateConfigKeyAllowPerRequest(feature);
+    validateConfigKeyBacking(feature);
     validateOwnershipRules(feature, allClaimKeys, knownRoles);
     validateMultiStreamProjections(feature);
     validateScreens(feature, featureMap, allWriteHandlerQns, allScreenQns, allConfigKeyQns);

package/src/engine/build-app-schema.ts

@@ -26,6 +26,11 @@
 // `effectiveFeatures` Argument annehmen und über alle iterations filtern.
 
 import type { AppSchema, EntityDefinition, FeatureSchema, WorkspaceSchema } from "../ui-types";
+import {
+  buildConfigFeatureSchema,
+  type ConfigFeatureSchema,
+  SETTINGS_HUB_FEATURE,
+} from "./build-config-feature-schema";
 import type { Registry } from "./types/feature";
 import type { FieldDefinition } from "./types/fields";
 
@@ -59,6 +64,21 @@ export function buildAppSchema(registry: Registry): AppSchema {
     }
   }
 
+  // Self-Populating Settings-Hub: aus den deklarierten Config-Keys mit `mask`
+  // werden Screens/Navs (+ eine Workspace) abgeleitet und hier eingehängt —
+  // kein manuelles r.screen/r.nav am App-Author.
+  const appHadWorkspaces = workspaces.length > 0;
+  const generated = buildConfigFeatureSchema(registry);
+  if (generated.screens.length > 0) {
+    mergeSettingsHubIntoConfigFeature(features, generated);
+    // Flip-Schutz: die Workspace NUR anhängen wenn die App schon Workspaces
+    // nutzt. Bei einer workspace-losen App bleibt app.workspaces undefined →
+    // der Renderer zeigt alle Navs ungefiltert, die Hub-Navs inklusive.
+    if (appHadWorkspaces && generated.workspace !== undefined) {
+      workspaces.push(generated.workspace);
+    }
+  }
+
   const schema = {
     features,
     ...(workspaces.length > 0 && { workspaces }),
@@ -81,6 +101,31 @@ export function buildAppSchema(registry: Registry): AppSchema {
   return schema;
 }
 
+// Hängt die generierten Hub-Screens/Navs an die config-FeatureSchema (qualified
+// dann als config:screen:* / config:nav:*). Existiert sie noch nicht (config
+// bundled-feature nicht gemountet), wird sie angelegt. find-or-create statt
+// fixem Push verhindert eine zweite FeatureSchema mit demselben featureName.
+function mergeSettingsHubIntoConfigFeature(
+  features: FeatureSchema[],
+  generated: ConfigFeatureSchema,
+): void {
+  const existing = features.find((f) => f.featureName === SETTINGS_HUB_FEATURE);
+  if (existing === undefined) {
+    features.push({
+      featureName: SETTINGS_HUB_FEATURE,
+      entities: {},
+      screens: generated.screens,
+      navs: generated.navs,
+    });
+  } else {
+    features[features.indexOf(existing)] = {
+      ...existing,
+      screens: [...existing.screens, ...generated.screens],
+      navs: [...(existing.navs ?? []), ...generated.navs],
+    };
+  }
+}
+
 // PlatformComponent slots ({ react, native }) legitimately hold component
 // functions — JSON.stringify drops them at inject-time and the client
 // re-resolves by name, so the walker treats them as opaque.