@cosmicdrift/kumiko-framework 0.52.0 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.52.0",
+  "version": "0.55.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>",

package/src/db/queries/__tests__/shadow-swap.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import type { EntityTableMeta } from "../../entity-table-meta";
+import { rebuildMetaOrThrow } from "../shadow-swap";
+
+const cleanMeta: EntityTableMeta = {
+  tableName: "read_x",
+  source: "managed",
+  columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true }],
+  indexes: [{ name: "read_x_tenant_id_idx", columns: ["tenant_id"] }],
+};
+
+describe("rebuildMetaOrThrow", () => {
+  test("returns the resolved meta for a clean projection table", () => {
+    expect(rebuildMetaOrThrow(cleanMeta, "feat:projection:x")).toBe(cleanMeta);
+  });
+
+  test("throws when the table object carries no resolvable EntityTableMeta", () => {
+    expect(() => rebuildMetaOrThrow({}, "feat:projection:x")).toThrow(
+      /no resolvable EntityTableMeta/,
+    );
+  });
+
+  test("rejects a meta-inexpressible partial index instead of silently dropping it", () => {
+    const meta: EntityTableMeta = {
+      ...cleanMeta,
+      indexes: [{ name: "read_x_active_idx", columns: ["status"], needsManualWhere: true }],
+    };
+    expect(() => rebuildMetaOrThrow(meta, "feat:projection:x")).toThrow(/partial index/);
+  });
+});

package/src/db/queries/projection-rebuild.ts

@@ -12,17 +12,25 @@ export async function markProjectionRebuilding(db: AnyDb, projectionName: string
   );
 }
 
-export async function selectEventsForProjectionRebuild(
+// Cursor-paged read for the live-tail catch-up loop: one batch of events
+// strictly newer than `afterId`, ascending. Each call is a fresh SELECT, so
+// under READ COMMITTED it sees events committed by concurrent writers since the
+// previous batch — that is what lets the rebuild drain the tail to ~0 lag.
+export async function selectEventsForProjectionRebuildBatch(
   db: AnyDb,
   aggregateTypes: readonly string[],
   eventTypes: readonly string[],
+  afterId: bigint,
+  limit: number,
 ): Promise<ReadonlyArray<Record<string, unknown>>> {
   return (await asRawClient(db).unsafe(
     `SELECT * FROM "kumiko_events"
      WHERE "aggregate_type" = ANY($1::text[])
        AND "type" = ANY($2::text[])
-     ORDER BY "id" ASC`,
-    [aggregateTypes, eventTypes],
+       AND "id" > $3
+     ORDER BY "id" ASC
+     LIMIT $4`,
+    [aggregateTypes, eventTypes, afterId, limit],
   )) as ReadonlyArray<Record<string, unknown>>;
 }
 

package/src/db/queries/shadow-swap.ts

@@ -0,0 +1,118 @@
+// Online projection rebuild via a transient shadow schema.
+//
+// Why a shadow SCHEMA and not a `read_foo__rebuild` table: apply(event, tx)
+// writes through the projection's canonical table object → an unqualified
+// `read_foo`. A captured table reference can't be re-pointed, so we redirect
+// NAME RESOLUTION instead of the write: build the shadow under the SAME name
+// in a private schema, point `search_path` there for the rebuild tx, and apply
+// lands in the shadow untouched. The live `read_foo` keeps serving reads and
+// writes for the whole replay — only the final swap takes a brief ACCESS
+// EXCLUSIVE lock, instead of holding it for the entire replay like an
+// in-place TRUNCATE + replay would.
+//
+// The shadow-schema choice also dissolves the index-rename problem: indexes
+// built in the shadow carry their canonical `read_foo_*` names and move intact
+// when the table is moved to public via SET SCHEMA.
+//
+// Boundary: the shadow table is rebuilt from EntityTableMeta, so any index NOT
+// expressed in meta (hand-added in a migration) is not reconstructed, and a
+// partial index whose WHERE the renderer can't express is rejected up-front.
+
+import type { EntityTableMeta } from "../entity-table-meta";
+import { type AnyDb, asEntityTableMeta, asRawClient } from "../query";
+import { renderTableDdl } from "../render-ddl";
+import { quoteTableIdent } from "./table-ops";
+
+export const PROJECTION_REBUILD_SCHEMA = "kumiko_rebuild";
+
+const SCHEMA_IDENT = quoteTableIdent(PROJECTION_REBUILD_SCHEMA);
+
+function isDuplicateSchemaError(e: unknown): boolean {
+  if (typeof e !== "object" || e === null || !("code" in e)) return false;
+  const { code } = e;
+  // 42P06 duplicate_schema, 23505 unique_violation on pg_namespace — both
+  // surface from the well-known CREATE SCHEMA IF NOT EXISTS race.
+  return code === "42P06" || code === "23505";
+}
+
+// Idempotent. MUST run OUTSIDE the rebuild tx: CREATE SCHEMA IF NOT EXISTS is
+// not race-free (two concurrent rebuilds of DIFFERENT projections can collide
+// on pg_namespace), and a collision inside the rebuild tx would roll the whole
+// replay back. The dup race is swallowed; anything else (e.g. a role without
+// CREATE privilege) rethrows so ops sees it loud.
+export async function ensureRebuildSchema(db: AnyDb): Promise<void> {
+  try {
+    await asRawClient(db).unsafe(`CREATE SCHEMA IF NOT EXISTS ${SCHEMA_IDENT}`);
+  } catch (e) {
+    if (!isDuplicateSchemaError(e)) throw e;
+  }
+}
+
+// Resolve the canonical EntityTableMeta a projection's table object carries,
+// or throw. Online rebuild needs the full column+index shape to build the
+// shadow table; a meta-inexpressible partial index would be silently dropped
+// by the renderer, so reject it up-front instead of swapping in a table that
+// is missing an index.
+export function rebuildMetaOrThrow(table: unknown, projectionName: string): EntityTableMeta {
+  const meta = asEntityTableMeta(table);
+  if (!meta) {
+    throw new Error(
+      `Projection "${projectionName}" has no resolvable EntityTableMeta — online rebuild needs it to build the shadow table.`,
+    );
+  }
+  if (meta.indexes.some((idx) => idx.needsManualWhere === true)) {
+    throw new Error(
+      `Projection "${projectionName}" has a partial index whose WHERE clause the schema renderer can't express (drizzle sql\`…\`). Online rebuild reconstructs the table from meta and would silently drop that index. Make the WHERE renderable or rebuild this projection offline.`,
+    );
+  }
+  return meta;
+}
+
+// Runs INSIDE the rebuild tx, AFTER the state/consumer row lock is taken.
+// Points search_path at the shadow schema (SET LOCAL → auto-reset on commit or
+// rollback), drops any leftover shadow from a crashed run, then builds the
+// shadow table + indexes under their canonical names. renderTableDdl output and
+// apply-writes are unqualified and resolve into the shadow; kumiko_events /
+// kumiko_projections live only in public and fall through to it.
+//
+// Boundary: an apply that writes to a table OTHER than its own projection (e.g.
+// an MSP saga touching a second read-model) writes UNQUALIFIED → resolves to
+// public, i.e. the live secondary table, not a shadow of it. Online rebuild is
+// safe for self-table-only apply (the common case); a multi-table apply would
+// mutate live state during replay.
+export async function buildShadowTable(tx: AnyDb, meta: EntityTableMeta): Promise<void> {
+  const raw = asRawClient(tx);
+  await raw.unsafe(`SET LOCAL search_path TO ${SCHEMA_IDENT}, public`);
+  await raw.unsafe(`DROP TABLE IF EXISTS ${SCHEMA_IDENT}.${quoteTableIdent(meta.tableName)}`);
+  for (const stmt of renderTableDdl(meta)) {
+    await raw.unsafe(stmt);
+  }
+}
+
+// Fence the live table before the cutover: take ACCESS EXCLUSIVE on
+// public.<tableName> so no concurrent synchronous projection apply (a command
+// handler's append+apply) can commit a new event-derived row past the rebuild's
+// final catch-up. Schema-qualified so the active shadow search_path can't
+// redirect it. lock_timeout (SET LOCAL → auto-reset) bounds the wait: under a
+// pathological long-running writer the fence fails loud and the rebuild rolls
+// back rather than hanging indefinitely.
+export async function fenceLiveTable(
+  tx: AnyDb,
+  tableName: string,
+  lockTimeoutMs: number,
+): Promise<void> {
+  const raw = asRawClient(tx);
+  await raw.unsafe(`SET LOCAL lock_timeout = ${Math.trunc(lockTimeoutMs)}`);
+  await raw.unsafe(`LOCK TABLE public.${quoteTableIdent(tableName)} IN ACCESS EXCLUSIVE MODE`);
+}
+
+// Atomic swap, INSIDE the rebuild tx, AFTER replay. Schema-qualified so the
+// active shadow search_path can't redirect them. DROP without CASCADE: if any
+// object depends on the live table the swap fails loud and the whole rebuild
+// rolls back, leaving the old table untouched.
+export async function swapShadowIntoLive(tx: AnyDb, tableName: string): Promise<void> {
+  const raw = asRawClient(tx);
+  const ident = quoteTableIdent(tableName);
+  await raw.unsafe(`DROP TABLE public.${ident}`);
+  await raw.unsafe(`ALTER TABLE ${SCHEMA_IDENT}.${ident} SET SCHEMA public`);
+}

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

@@ -1,16 +1,22 @@
 import { describe, expect, test } from "bun:test";
+import { validateBoot } from "../boot-validator";
 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 { access, 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`.
+// A feature that opts config keys into the Settings-Hub via `mask`. platformFee
+// is a system-home key with a human writer (SystemAdmin); stripeKey is tenant-
+// home but its admin write-set cascades it up to the Plattform screen too.
 const billing = defineFeature("billing", (r) => {
   r.config({
     keys: {
       stripeKey: createTenantConfig("text", { mask: { title: "billing.stripe-key" } }),
-      platformFee: createSystemConfig("number", { mask: { title: "billing.platform-fee" } }),
+      platformFee: createSystemConfig("number", {
+        write: access.systemAdmin,
+        mask: { title: "billing.platform-fee" },
+      }),
     },
   });
 });
@@ -116,3 +122,80 @@ function shellWith(masked: ReturnType<typeof defineFeature>) {
   });
   return createRegistry([shell, masked]);
 }
+
+// A shell whose workspaces place the generated audience parents inline by
+// referencing config:nav:audience-<scope> directly (the app-driven placement
+// the renderer-side slice then expands with the audience's children).
+function placingShell(...audienceScopes: string[]) {
+  return 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", ...audienceScopes.map((s) => `config:nav:audience-${s}`)],
+    });
+  });
+}
+
+function workspaceNavs(app: ReturnType<typeof buildAppSchema>, id: string): readonly string[] {
+  const ws = app.workspaces?.find((w) => w.definition.id === id);
+  if (ws === undefined) throw new Error(`no workspace "${id}"`);
+  return ws.navMembers;
+}
+
+describe("buildAppSchema — Settings-Hub inline placement", () => {
+  test("a workspace referencing an audience parent gets that audience's children expanded in", () => {
+    const app = buildAppSchema(createRegistry([placingShell("system"), billing]));
+    const main = workspaceNavs(app, "main");
+    // the app listed only the parent; the framework expands the child screen-nav
+    // so the slice doesn't drop it.
+    expect(main).toContain("config:nav:audience-system");
+    expect(main).toContain("config:nav:billing-system");
+    // the app's own nav is untouched
+    expect(main).toContain("shell:nav:home");
+  });
+
+  test("placing every audience suppresses the standalone settings switcher entirely", () => {
+    // billing spans system + tenant → place both → no separate Einstellungen tab.
+    const app = buildAppSchema(createRegistry([placingShell("system", "tenant"), billing]));
+    expect(app.workspaces?.map((w) => w.definition.id).sort()).toEqual(["main"]);
+    const main = workspaceNavs(app, "main");
+    expect(main).toContain("config:nav:billing-system");
+    expect(main).toContain("config:nav:billing-tenant");
+  });
+
+  test("partial placement keeps un-placed audiences in the standalone tab (nothing vanishes)", () => {
+    // place only system → the tenant audience must still be reachable via the
+    // standalone settings workspace, never silently dropped.
+    const app = buildAppSchema(createRegistry([placingShell("system"), billing]));
+    const settings = workspaceNavs(app, SETTINGS_HUB_WORKSPACE);
+    expect(settings).toContain("config:nav:audience-tenant");
+    expect(settings).toContain("config:nav:billing-tenant");
+    // the placed (system) audience is NOT duplicated into the standalone tab
+    expect(settings).not.toContain("config:nav:audience-system");
+    expect(settings).not.toContain("config:nav:billing-system");
+  });
+
+  test("an app that places NO audience keeps the standalone tab whole (backward compatible)", () => {
+    const app = buildAppSchema(shellWith(billing));
+    const settings = workspaceNavs(app, SETTINGS_HUB_WORKSPACE);
+    expect(settings).toContain("config:nav:audience-system");
+    expect(settings).toContain("config:nav:audience-tenant");
+  });
+
+  test("boot validation exempts the generated audience nav QNs but still catches typos", () => {
+    const ok = defineFeature("ok", (r) => {
+      r.config({ keys: { fee: createSystemConfig("number", { mask: { title: "ok.fee" } }) } });
+      r.workspace({ id: "w", label: "W", nav: ["config:nav:audience-system"] });
+    });
+    expect(() => validateBoot([ok])).not.toThrow();
+
+    const typo = defineFeature("typo", (r) => {
+      r.config({ keys: { fee: createSystemConfig("number", { mask: { title: "t.fee" } }) } });
+      r.workspace({ id: "w", label: "W", nav: ["config:nav:audience-systemm"] });
+    });
+    expect(() => validateBoot([typo])).toThrow(/references nav "config:nav:audience-systemm"/);
+  });
+});

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

@@ -1,25 +1,42 @@
 import { describe, expect, test } from "bun:test";
 import { buildConfigFeatureSchema } from "../build-config-feature-schema";
-import { createSystemConfig, createTenantConfig, createUserConfig } from "../config-helpers";
+import {
+  access,
+  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.
+// Two features declaring masked keys across all three scopes. Probes:
+//  - apiKey: a SYSTEM-home key with a human writer (SystemAdmin) — the real
+//    subscription-stripe shape; renders on the Plattform screen.
+//  - platformFee: a SYSTEM-home key that keeps the default `["system"]` write
+//    (machine-only) — must NOT surface in the human hub anywhere.
+//  - internalFlag: UNMASKED (internal plumbing) — excluded.
+//  - derived: computed+masked (no row to set) — excluded.
+// stripeKey/currency/fromAddress are TENANT-home with the admin write-set
+// (∋ SystemAdmin), so they yield BOTH a SystemAdmin-only Plattform screen (set
+// the platform default) AND a tenant screen with the full admin set (override).
+// 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: {
+      apiKey: createSystemConfig("text", {
+        write: access.systemAdmin,
+        mask: { title: "billing.api-key" },
+      }),
       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" } }),
+      platformFee: createSystemConfig("number", { mask: { title: "billing.platform-fee" } }), // machine-only write → excluded
       derived: createTenantConfig("number", {
         computed: async () => 5,
         mask: { title: "billing.derived" }, // masked BUT computed → excluded
@@ -50,19 +67,20 @@ function configScreen(id: string): ConfigEditScreenDefinition {
 
 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)
+    // scopes present: system (api-key + tenant keys elevated), tenant, user
     expect(navById("audience-system")).toBeDefined();
     expect(navById("audience-tenant")).toBeDefined();
     expect(navById("audience-user")).toBeDefined();
 
-    // children: billing-tenant, notify-tenant, billing-system, notify-user
+    // tenant keys (stripe/currency/from) span system too → notify-system exists.
     expect(schema.screens.map((s) => s.id).sort()).toEqual([
       "billing-system",
       "billing-tenant",
+      "notify-system",
       "notify-tenant",
       "notify-user",
     ]);
-    expect(schema.navs).toHaveLength(7); // 3 audiences + 4 children
+    expect(schema.navs).toHaveLength(8); // 3 audiences + 5 children
   });
 
   test("audience parents are grouping nodes (no screen) ordered system<tenant<user", () => {
@@ -127,11 +145,68 @@ describe("buildConfigFeatureSchema — structure", () => {
     expect(allConfigKeyValues).not.toContain("billing:config:internal-flag");
     expect(allConfigKeyValues).not.toContain("billing:config:derived");
   });
+});
+
+describe("buildConfigFeatureSchema — per-role cascade (system > tenant > user)", () => {
+  test("a tenant-home key yields a SystemAdmin-only Plattform screen AND a full-admin tenant screen", () => {
+    // The cascade env→system→tenant lets SystemAdmin set the platform DEFAULT a
+    // tenant inherits; the tenant admin OVERRIDES at the tenant row. The two
+    // screens MUST gate differently — else a tenant admin could edit the
+    // platform default (the security crux of "smtp = sysadmin > admin").
+    const sysScreen = configScreen("notify-system");
+    expect(sysScreen.scope).toBe("system");
+    expect(sysScreen.configKeys).toEqual({ "from-address": "notify:config:from-address" });
+    expect(sysScreen.access).toEqual({ roles: ["SystemAdmin"] });
+    // TenantAdmin/Admin are NOT on the platform-default screen.
+    const sysAccess = sysScreen.access;
+    const sysRoles = sysAccess && "roles" in sysAccess ? sysAccess.roles : [];
+    expect(sysRoles).not.toContain("TenantAdmin");
+    expect(sysRoles).not.toContain("Admin");
+
+    const tenScreen = configScreen("notify-tenant");
+    expect(tenScreen.scope).toBe("tenant");
+    expect(tenScreen.configKeys).toEqual({ "from-address": "notify:config:from-address" });
+    expect(tenScreen.access).toEqual({ roles: ["TenantAdmin", "Admin", "SystemAdmin"] });
+
+    // audience-system is likewise SystemAdmin-only (parent gate union).
+    expect(navById("audience-system")?.access).toEqual({ roles: ["SystemAdmin"] });
+  });
+
+  test("the Plattform screen co-groups a feature's system-home key with its elevated tenant keys", () => {
+    // billing-system carries api-key (system home, write SystemAdmin) AND the
+    // elevated tenant keys stripe-key/currency — all writable by SystemAdmin.
+    const s = configScreen("billing-system");
+    expect(Object.keys(s.configKeys).sort()).toEqual(["api-key", "currency", "stripe-key"]);
+    expect(s.access).toEqual({ roles: ["SystemAdmin"] });
+  });
+
+  test("a machine-only system key (write defaults to ['system']) never reaches the human hub", () => {
+    // platform-fee keeps the default system write — no human can set it, so it
+    // must not render on any screen (would otherwise look editable but reject).
+    const allConfigKeyValues = schema.screens.flatMap((x) =>
+      x.type === "configEdit" ? Object.values(x.configKeys) : [],
+    );
+    expect(allConfigKeyValues).not.toContain("billing:config:platform-fee");
+    expect(schema.screens.some((s) => s.id === "billing-system" && "scope" in s)).toBe(true);
+  });
+
+  test("a user-home `all`-writable key stays at the user scope only — no broader default screen", () => {
+    // digest is write `all`; no elevated role names it (all ∩ elevated = ∅), so
+    // it gets no broader (tenant/system) default screen, only the personal one.
+    expect(configScreen("notify-user").scope).toBe("user");
+    const digestPlacements = schema.screens
+      .flatMap((x) => (x.type === "configEdit" ? Object.values(x.configKeys) : []))
+      .filter((v) => v === "notify:config:digest");
+    expect(digestPlacements).toHaveLength(1);
+  });
+});
 
-  test("access: union of write (edit) roles; an `all`-writable group collapses to openToAll", () => {
+describe("buildConfigFeatureSchema — access + workspace", () => {
+  test("home-scope screens union 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"] });
+    expect(configScreen("billing-tenant").access).toEqual({
+      roles: ["TenantAdmin", "Admin", "SystemAdmin"],
+    });
     // digest is createUserConfig → write access.all (["all"]) → openToAll
     expect(configScreen("notify-user").access).toEqual({ openToAll: true });
   });
@@ -146,6 +221,18 @@ describe("buildConfigFeatureSchema — structure", () => {
     expect(empty.workspace).toBeUndefined();
   });
 
+  test("returns empty (no workspace) when every masked key is machine-only", () => {
+    // masked BUT default ["system"] write — no human writer at any scope, so the
+    // hub has nothing to show and no (empty) settings switcher is emitted.
+    const internalOnly = defineFeature("internal", (r) => {
+      r.config({ keys: { token: createSystemConfig("text", { mask: { title: "i.token" } }) } });
+    });
+    const empty = buildConfigFeatureSchema(createRegistry([internalOnly]));
+    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();

package/src/engine/__tests__/schema-builder-date-bounds.test.ts

@@ -0,0 +1,47 @@
+// #369: min/max auf date/timestamp-Feldern werden im Insert-Schema
+// durchgesetzt (lexikografischer ISO-Vergleich, ohne Date-API). Die UI
+// begrenzt den Picker; diese Zod-Grenze ist die Write-seitige Sicherung.
+
+import { describe, expect, test } from "bun:test";
+import { createDateField, createEntity, createTimestampField } from "../factories";
+import { buildInsertSchema } from "../schema-builder";
+
+describe("date/timestamp min/max bounds", () => {
+  test("date max abgewiesen, im Rahmen akzeptiert", () => {
+    const entity = createEntity({
+      table: "T",
+      fields: { born: createDateField({ max: "2026-06-15" }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ born: "2026-01-01" }).success).toBe(true);
+    expect(schema.safeParse({ born: "2026-12-31" }).success).toBe(false);
+  });
+
+  test("date min abgewiesen, im Rahmen akzeptiert", () => {
+    const entity = createEntity({
+      table: "T",
+      fields: { d: createDateField({ min: "2026-01-01" }) },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ d: "2026-05-05" }).success).toBe(true);
+    expect(schema.safeParse({ d: "2025-12-31" }).success).toBe(false);
+  });
+
+  test("ohne bounds: jedes valide Datum passt", () => {
+    const entity = createEntity({ table: "T", fields: { d: createDateField() } });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ d: "1999-01-01" }).success).toBe(true);
+  });
+
+  test("timestamp min/max (UTC-Instant) durchgesetzt", () => {
+    const entity = createEntity({
+      table: "T",
+      fields: {
+        at: createTimestampField({ min: "2026-01-01T00:00:00Z", max: "2026-12-31T23:59:59Z" }),
+      },
+    });
+    const schema = buildInsertSchema(entity);
+    expect(schema.safeParse({ at: "2026-06-15T10:00:00Z" }).success).toBe(true);
+    expect(schema.safeParse({ at: "2027-01-01T00:00:00Z" }).success).toBe(false);
+  });
+});

package/src/engine/boot-validator/screens-nav.ts

@@ -1,3 +1,4 @@
+import { SETTINGS_HUB_AUDIENCE_NAV_QNS } from "../build-config-feature-schema";
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
@@ -742,6 +743,12 @@ export function validateWorkspaces(
   for (const [wsId, wsDef] of Object.entries(feature.workspaces)) {
     if (wsDef.nav !== undefined) {
       for (const navQn of wsDef.nav) {
+        // Settings-Hub-Audience-Navs sind generiert (buildAppSchema, nach Boot),
+        // also nie via r.nav() registriert. Eine App platziert die Settings-
+        // Gruppe inline, indem sie genau einen dieser drei QNs referenziert —
+        // hier exempt, damit der Boot nicht fälschlich wirft. Tippfehler an
+        // anderen Hub-QNs (Kinder) fängt der Render-Slice-Filter ab.
+        if (SETTINGS_HUB_AUDIENCE_NAV_QN_SET.has(navQn)) continue;
         if (!allNavQns.has(navQn)) {
           throw new Error(
             `[Feature ${feature.name}] Workspace "${wsId}" references nav "${navQn}" ` +
@@ -754,6 +761,10 @@ export function validateWorkspaces(
   }
 }
 
+const SETTINGS_HUB_AUDIENCE_NAV_QN_SET: ReadonlySet<string> = new Set(
+  SETTINGS_HUB_AUDIENCE_NAV_QNS,
+);
+
 // Single-default rule across the entire app. Mirrors how createApp validates
 // roles up front — a second `default: true` is a configuration error, not a
 // runtime fallback. Apps without any default fall back to "first workspace

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

@@ -53,7 +53,7 @@ export function buildAppSchema(registry: Registry): AppSchema {
   // navigate({ workspaceId })). Wir gehen direkt durch `feature.workspaces`
   // — dort sind die ids noch in der Autor-Form (short) — und ziehen die
   // pre-resolved navMembers aus der Registry.
-  const workspaces: WorkspaceSchema[] = [];
+  let workspaces: WorkspaceSchema[] = [];
   for (const [featureName, feature] of registry.features) {
     for (const [shortId, definition] of Object.entries(feature.workspaces)) {
       const qualified = `${featureName}:workspace:${shortId}`;
@@ -71,11 +71,14 @@ export function buildAppSchema(registry: Registry): AppSchema {
   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);
+    // Flip-Schutz: nur für Apps die schon Workspaces nutzen. Bei einer
+    // workspace-losen App bleibt app.workspaces undefined → der Renderer zeigt
+    // alle Navs ungefiltert, die Hub-Navs inklusive.
+    if (appHadWorkspaces) {
+      const placed = placeSettingsHub(workspaces, generated);
+      workspaces = placed.workspaces;
+      if (placed.standalone !== undefined) workspaces.push(placed.standalone);
+      warnUnplacedAudiences(placed.unplaced);
     }
   }
 
@@ -126,6 +129,80 @@ function mergeSettingsHubIntoConfigFeature(
   }
 }
 
+// Inline-Platzierung des Settings-Hubs: Referenziert eine App-Workspace einen
+// generierten Audience-Parent (`config:nav:audience-<scope>`) in ihren
+// navMembers, hängen wir die Kinder dieser Audience dort an (der Slice-Filter
+// blendet sonst Kinder aus, die nicht explizit Member sind) und zählen die
+// Audience als „platziert". Der Standalone-Switcher behält NUR un-platzierte
+// Audiences — so erscheint nichts doppelt und keine Audience verschwindet still
+// (alles platziert → kein Tab; teils platziert → Rest im Tab).
+function placeSettingsHub(
+  appWorkspaces: readonly WorkspaceSchema[],
+  generated: ConfigFeatureSchema,
+): { workspaces: WorkspaceSchema[]; standalone: WorkspaceSchema | undefined; unplaced: string[] } {
+  const prefix = `${SETTINGS_HUB_FEATURE}:nav:`;
+  const audienceShortIds = new Set<string>();
+  const childParent = new Map<string, string>();
+  const childrenByAudience = new Map<string, string[]>();
+  for (const nav of generated.navs) {
+    if (nav.parent === undefined) {
+      audienceShortIds.add(nav.id);
+    } else {
+      childParent.set(nav.id, nav.parent);
+      const list = childrenByAudience.get(nav.parent) ?? [];
+      list.push(nav.id);
+      childrenByAudience.set(nav.parent, list);
+    }
+  }
+
+  const placedAudiences = new Set<string>();
+  const workspaces = appWorkspaces.map((ws) => {
+    const additions: string[] = [];
+    for (const member of ws.navMembers) {
+      if (!member.startsWith(prefix)) continue;
+      const shortId = member.slice(prefix.length);
+      if (!audienceShortIds.has(shortId)) continue;
+      placedAudiences.add(shortId);
+      for (const child of childrenByAudience.get(shortId) ?? []) {
+        const childQn = `${prefix}${child}`;
+        if (!ws.navMembers.includes(childQn) && !additions.includes(childQn)) {
+          additions.push(childQn);
+        }
+      }
+    }
+    return additions.length > 0 ? { ...ws, navMembers: [...ws.navMembers, ...additions] } : ws;
+  });
+
+  const audienceOf = (shortId: string): string =>
+    audienceShortIds.has(shortId) ? shortId : (childParent.get(shortId) ?? shortId);
+  let standalone: WorkspaceSchema | undefined;
+  if (generated.workspace !== undefined && placedAudiences.size < audienceShortIds.size) {
+    const remaining = generated.workspace.navMembers.filter((member) => {
+      const shortId = member.startsWith(prefix) ? member.slice(prefix.length) : member;
+      return !placedAudiences.has(audienceOf(shortId));
+    });
+    if (remaining.length > 0) standalone = { ...generated.workspace, navMembers: remaining };
+  }
+
+  const unplaced =
+    placedAudiences.size > 0 ? [...audienceShortIds].filter((id) => !placedAudiences.has(id)) : [];
+  return { workspaces, standalone, unplaced };
+}
+
+function warnUnplacedAudiences(unplaced: readonly string[]): void {
+  // skip: every audience placed — nothing to warn about
+  if (unplaced.length === 0) return;
+  // skip: dev-only authoring hint, never in production
+  if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+  // biome-ignore lint/suspicious/noConsole: dev-only authoring hint
+  console.warn(
+    `[kumiko] Settings-Hub: ${unplaced.join(", ")} nicht in einer App-Workspace platziert — ` +
+      `erscheint im Standalone-"Einstellungen"-Tab. Referenziere ` +
+      `${unplaced.map((id) => `${SETTINGS_HUB_FEATURE}:nav:${id}`).join(", ")} ` +
+      `in einer r.workspace.nav, um die Gruppe inline zu zeigen.`,
+  );
+}
+
 // 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.