@cosmicdrift/kumiko-framework 0.48.0 → 0.50.0

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

@@ -2115,3 +2115,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("rejects backing:secrets even system-scoped until the dispatch is wired (framework#333)", () => {
+    const feature = defineFeature("billing", (r) => {
+      r.config({ keys: { apiKey: createSystemConfig("text", { backing: "secrets" }) } });
+    });
+    expect(() => validateBoot([feature])).toThrow(/not yet wired.*333/i);
+  });
+
+  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/__tests__/feature-manifest.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { ConfigScopes } from "../constants";
+import { buildManifestFromRegistry, createRegistry, defineFeature } from "../index";
+
+const boolKey = {
+  type: "boolean",
+  scope: ConfigScopes.system,
+  access: { read: ["anonymous"], write: ["anonymous"] },
+} as const;
+
+describe("buildManifestFromRegistry — deterministic codepoint sort (#330)", () => {
+  // `bZeta` vs `balpha`: localeCompare orders these case-insensitively
+  // (balpha < bZeta), but a codepoint sort puts uppercase 'Z' (U+005A) ahead of
+  // lowercase 'a' (U+0061) — the two comparators DISAGREE. The manifest is
+  // serialized to byte-exact JSON and must not depend on the runner's ICU
+  // locale (macOS-dev vs Linux-CI). This assertion fails the instant anyone
+  // reverts buildManifestFromRegistry to localeCompare. (Feature names skip the
+  // kebab normalization that config/secret short-names go through, so they are
+  // the one place a case-based disagreement survives into the sorted output.)
+  test("features are ordered by codepoint name, not locale", () => {
+    const registry = createRegistry([
+      defineFeature("bZeta", () => {}),
+      defineFeature("balpha", () => {}),
+    ]);
+
+    const manifest = buildManifestFromRegistry(registry, { source: "test" });
+
+    expect(manifest.features.map((f) => f.name)).toEqual(["bZeta", "balpha"]);
+  });
+
+  test("config keys within a feature come out sorted by qualified name", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.config({ keys: { "z-flag": boolKey, "a-flag": boolKey } });
+    });
+    const registry = createRegistry([feature]);
+
+    const manifest = buildManifestFromRegistry(registry, { source: "test" });
+    const demo = manifest.features.find((f) => f.name === "demo");
+
+    expect(demo?.configKeys.map((k) => k.qualifiedName)).toEqual([
+      "demo:config:a-flag",
+      "demo:config:z-flag",
+    ]);
+  });
+});

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

@@ -136,6 +136,32 @@ 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"`,
+      );
+    }
+
+    // The secrets read/write dispatch is not yet wired (framework#333). Until
+    // it lands, the value would silently persist in the config-values
+    // projection instead of the secrets store — losing the envelope-encryption,
+    // key-rotation and audit-on-read that backing="secrets" promises. Reject
+    // loudly rather than degrade to config-encrypted behind the declaration.
+    throw new Error(
+      `[Feature ${feature.name}] Config key "${keyName}" declares backing="secrets", but the secrets read/write dispatch is not yet wired (framework#333). Until then remove backing (the value would store as config-encrypted) or gate the feature behind #333.`,
+    );
+  }
+}
+
 // --- Config key cross-feature reference validation ---
 
 export function validateConfigReads(

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

@@ -3,6 +3,7 @@ import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext"
 import {
   validateCircularDeps,
   validateConfigKeyAllowPerRequest,
+  validateConfigKeyBacking,
   validateConfigKeyBounds,
   validateConfigKeyComputed,
   validateConfigKeyRequired,
@@ -136,6 +137,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.