@cosmicdrift/kumiko-framework 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @cosmicdrift/kumiko-framework
 
+## 0.4.1
+
+### Patch Changes
+
+- 010b410: feat(auth-email-password): "Bestätigungs-Mail erneut senden" im LoginScreen
+
+  LoginScreen bietet bei reason=email_not_verified jetzt einen Resend-Link
+  im Fehler-Banner — der existierende `requestEmailVerification`-Endpoint
+  wird direkt aufgerufen, der Banner wechselt nach Erfolg zum Info-Variant
+  ("Wir haben dir eine neue Bestätigungs-Mail geschickt.").
+
+  UX-Details:
+
+  - Bei 429 → inline-Hint "Bitte warte kurz und versuche es erneut."
+  - Bei Netzwerk/sonstigen Fehlern → inline-Hint "Konnte nicht senden."
+  - Anti-Typo-Gate: ändert der User die Email-Eingabe nach dem Login-Fail,
+    verschwindet der Resend-Link — sonst würde Resend silent-success an die
+    geänderte (potentiell typoed) Adresse gehen ohne User-Feedback.
+  - Andere Failure-Codes (invalid_credentials etc.) zeigen weiterhin keinen
+    Resend-Link.
+
+  i18n: 4 neue Keys (DE+EN) im `auth.login.resend*`-Namespace, additive.
+  Apps die ihre Translations override-en müssen nichts ändern.
+
+  Additive UI-Feature — keine API-Breaks, keine Schema-Migration.
+
+## 0.4.0
+
+### Minor Changes
+
+- 825e7d2: Visual-Tree V.1.4 → V.1.6 — Feature-complete Editor + Folder-Hierarchy + Roving-tabindex.
+
+  **V.1.4** — explicit `folder?: string` Schema-Field auf text-block-entity. Slug bleibt
+  kebab-only validiert, Folder explizit gesetzt. Tree gruppiert via `groupBlocksByFolder`
+  (ersetzt `groupBlocksBySlugPrefix`). `Subscribe<T>` Signature um optional `emitError`
+  erweitert für explicit async-error-Pfade. ProviderBranch zeigt Error-Banner mit
+  Retry-Button. Drift-Test pinnt seedTextBlock-vs-set.write Slug-Validation.
+
+  **V.1.4b** — URL-State-Routing für Editor-Target via `nav.searchParams`. F5 + Back-Button
+  stellen den Editor-State wieder her. Format: `?t=text-content:edit&a_slug=...&a_lang=...`.
+  Plus `useDispatchTarget` hook ersetzt globalen `dispatchTarget` als empfohlenen Production-
+  Pfad (legacy bleibt für Test-Hooks).
+
+  **V.1.5** — Arrow-Key-Navigation (`<aside role="tree">`, ARIA-tree-Pattern) + SSE-driven
+  Tree-Refresh. `ClientFeatureDefinition.treeEntities?: string[]` listet Entity-Namen pro
+  Provider; live-events triggern provider-re-mount → Stale-Tree-state="stub"→"filled"
+  flippt nach save automatisch.
+
+  **V.1.5c+d** — Active-Node-Highlight (explicit blue + 2px border-l + scrollIntoView),
+  VS-Code-Polish (compact spacing, focus-visible, folder-icon-color text-amber, indent-
+  guides per ancestor-depth), Folder-Wrapper für legal-pages ("📁 Legal" + slug-first
+  Verschachtelung) und text-content ("📁 Content").
+
+  **V.1.6** — Multi-level Folder-Splitting (`folder="page/marketing"` → nested folders,
+  walk-or-create-pattern, folder/leaf-collision-tolerant). Roving-tabindex (nur focused-
+  treeitem hat tabIndex=0, Tab cyclt aus dem Tree raus).
+
+  35/35 kumiko check PASS, 13/13 group-blocks + 22/22 text-content integration tests grün.
+  Browser + Keyboard lokal validated.
+
+  **Breaking**: `TreeContext` Type entfernt (V.1.2 SR2-Rip — war nie genutzt). Provider sind
+  session-bound: `TreeChildrenSubscribe = () => Subscribe<T>` statt `(ctx) => Subscribe<T>`.
+
+  **V.1.7-Followups**: useEffect-deps in VisualTree-focus-init (Performance), Cancellation-
+  Token in TreeProvider's fetch (emit-after-unmount-warning), inline-rename, drag-drop,
+  file-icons per slug-extension, parent-jump bei ArrowLeft auf collapsed-item.
+
 ## 0.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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>",
@@ -159,7 +159,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.3.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.4.1",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "drizzle-kit": "^0.31.10",

package/src/db/__tests__/config-seed.integration.ts

@@ -0,0 +1,279 @@
+import { sql } from "drizzle-orm";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import {
+  createEntity,
+  createSystemConfig,
+  createTenantConfig,
+  createTextField,
+  createUserConfig,
+  SYSTEM_TENANT_ID,
+} from "../../engine";
+import type { ConfigSeedDef, Registry } from "../../engine/types";
+import { createTestDb, type TestDb, unsafeCreateEntityTable } from "../../stack";
+import { seedConfigValues } from "../config-seed";
+import { createEncryptionProvider } from "../encryption";
+import { buildDrizzleTable } from "../table-builder";
+
+// --- Test Entity ---
+// Mirrors the config-value entity from bundled-features with a unique
+// table name so it never collides with the real config table.
+const configEntity = createEntity({
+  table: "read_cfg_seed_test",
+  fields: {
+    key: createTextField({ required: true }),
+    value: createTextField({}),
+    userId: createTextField({}),
+  },
+  indexes: [
+    {
+      unique: true,
+      columns: ["key", "tenantId", "userId"],
+      name: "cfg_seed_test_unique",
+    },
+  ],
+});
+const configTable = buildDrizzleTable("cfgSeedTest", configEntity);
+
+// --- Registry Stub ---
+const KEY_DEFS = {
+  "test:config:service-url": createSystemConfig("text", {
+    default: "https://default.example.com",
+  }),
+  "test:config:max-upload": createTenantConfig("number", { default: 10 }),
+  "test:config:stripe-key": createTenantConfig("text", { encrypted: true }),
+  "test:config:theme": createUserConfig("text", { default: "blue" }),
+};
+
+const mockRegistry = {
+  getConfigKey: (key: string) => KEY_DEFS[key as keyof typeof KEY_DEFS] ?? undefined,
+} as unknown as Registry;
+
+// --- Helpers ---
+const encryption = createEncryptionProvider(
+  Buffer.from("0123456789abcdef0123456789abcdef").toString("base64"),
+);
+
+let testDb: TestDb;
+
+async function countRows(): Promise<number> {
+  const [r] = await testDb.db.execute<{ count: number }>(
+    sql`SELECT COUNT(*)::int AS count FROM read_cfg_seed_test`,
+  );
+  return r?.count ?? 0;
+}
+
+async function countEvents(): Promise<number> {
+  const [r] = await testDb.db.execute<{ count: number }>(
+    sql`SELECT COUNT(*)::int AS count FROM kumiko_events`,
+  );
+  return r?.count ?? 0;
+}
+
+// --- Setup ---
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, configEntity, "cfgSeedTest");
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await testDb.db.execute(sql`TRUNCATE kumiko_events, read_cfg_seed_test RESTART IDENTITY CASCADE`);
+});
+
+// --- Tests ---
+
+describe("seedConfigValues", () => {
+  test("inserts initial seeds — creates rows + events", async () => {
+    const TENANT_A = "22222222-2222-4222-8222-222222222222";
+    const seeds: ConfigSeedDef[] = [
+      { key: "test:config:service-url", value: "https://prod.example.com", scope: "system" },
+      { key: "test:config:max-upload", value: 50, scope: "tenant" },
+      {
+        key: "test:config:theme",
+        value: "dark",
+        scope: "user",
+        tenantId: TENANT_A,
+        userId: "u-123",
+      },
+    ];
+
+    const result = await seedConfigValues(
+      seeds,
+      configTable,
+      configEntity,
+      mockRegistry,
+      testDb.db,
+    );
+
+    expect(result.created).toBe(3);
+    expect(result.skipped).toBe(0);
+    expect(await countRows()).toBe(3);
+    expect(await countEvents()).toBe(3);
+  });
+
+  test("idempotent re-run — all skipped", async () => {
+    const seeds: ConfigSeedDef[] = [
+      { key: "test:config:service-url", value: "https://prod.example.com", scope: "system" },
+    ];
+
+    const first = await seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db);
+    expect(first).toEqual({ created: 1, skipped: 0 });
+
+    const second = await seedConfigValues(
+      seeds,
+      configTable,
+      configEntity,
+      mockRegistry,
+      testDb.db,
+    );
+    expect(second).toEqual({ created: 0, skipped: 1 });
+  });
+
+  test("insert-only — value change ignored on re-boot", async () => {
+    const seeds: ConfigSeedDef[] = [{ key: "test:config:max-upload", value: 10, scope: "tenant" }];
+
+    await seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db);
+
+    const seedsChanged: ConfigSeedDef[] = [
+      { key: "test:config:max-upload", value: 999, scope: "tenant" },
+    ];
+    const result = await seedConfigValues(
+      seedsChanged,
+      configTable,
+      configEntity,
+      mockRegistry,
+      testDb.db,
+    );
+    expect(result).toEqual({ created: 0, skipped: 1 });
+
+    // Old value persists
+    const [row] = await testDb.db.execute<{ value: string }>(
+      sql`SELECT value FROM read_cfg_seed_test WHERE key = 'test:config:max-upload' LIMIT 1`,
+    );
+    expect(row).toBeDefined();
+    expect(JSON.parse(row!.value)).toBe(10);
+  });
+
+  test("scope mapping — system/tenant under SYSTEM_TENANT_ID, user under real tenantId", async () => {
+    const TENANT_A = "11111111-1111-4111-8111-111111111111";
+
+    const seeds: ConfigSeedDef[] = [
+      { key: "test:config:service-url", value: "x", scope: "system" },
+      { key: "test:config:max-upload", value: 20, scope: "tenant" },
+      { key: "test:config:theme", value: "dark", scope: "user", tenantId: TENANT_A, userId: "u-1" },
+    ];
+
+    await seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db);
+
+    const rows = await testDb.db.execute<{
+      key: string;
+      tenantId: string;
+      userId: string | null;
+    }>(
+      sql`SELECT key, tenant_id AS "tenantId", user_id AS "userId" FROM read_cfg_seed_test ORDER BY key`,
+    );
+
+    const sys = rows.find((r) => r.key === "test:config:service-url");
+    const tnt = rows.find((r) => r.key === "test:config:max-upload");
+    const usr = rows.find((r) => r.key === "test:config:theme");
+
+    expect(sys!.tenantId).toBe(SYSTEM_TENANT_ID);
+    expect(sys!.userId).toBeNull();
+
+    expect(tnt!.tenantId).toBe(SYSTEM_TENANT_ID);
+    expect(tnt!.userId).toBeNull();
+
+    // user-scope seed must live under the user's actual tenantId so the
+    // resolver cascade can match it — never under SYSTEM_TENANT_ID.
+    expect(usr!.tenantId).toBe(TENANT_A);
+    expect(usr!.userId).toBe("u-1");
+  });
+
+  test("user-scope seed without tenantId throws (would be unreachable)", async () => {
+    const seeds: ConfigSeedDef[] = [
+      { key: "test:config:theme", value: "dark", scope: "user", userId: "u-1" },
+    ];
+
+    await expect(
+      seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db),
+    ).rejects.toThrow(/user-scope seed.*requires both tenantId and userId/);
+  });
+
+  test("encrypted seed without EncryptionProvider throws — fail loud at boot", async () => {
+    const seeds: ConfigSeedDef[] = [
+      { key: "test:config:stripe-key", value: "sk_live_xxx", scope: "tenant" },
+    ];
+
+    await expect(
+      seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db),
+    ).rejects.toThrow(/encrypted but no EncryptionProvider/);
+  });
+
+  test("encrypted seed with provider stores ciphertext, not plaintext", async () => {
+    const seeds: ConfigSeedDef[] = [
+      { key: "test:config:stripe-key", value: "sk_live_secret_token", scope: "tenant" },
+    ];
+
+    const result = await seedConfigValues(
+      seeds,
+      configTable,
+      configEntity,
+      mockRegistry,
+      testDb.db,
+      encryption,
+    );
+    expect(result).toEqual({ created: 1, skipped: 0 });
+
+    const [row] = await testDb.db.execute<{ value: string }>(
+      sql`SELECT value FROM read_cfg_seed_test WHERE key = 'test:config:stripe-key' LIMIT 1`,
+    );
+    expect(row).toBeDefined();
+    // value column holds ciphertext, never the plain token. The
+    // resolver later runs `decrypt → JSON.parse` to get the primitive
+    // back; we replay the same round-trip here.
+    expect(row!.value).not.toContain("sk_live_secret_token");
+    expect(JSON.parse(encryption.decrypt(row!.value))).toBe("sk_live_secret_token");
+  });
+
+  test("race-safe parallel boot — two concurrent calls result in 1 created + 1 skipped", async () => {
+    const seeds: ConfigSeedDef[] = [
+      { key: "test:config:service-url", value: "race-target", scope: "system" },
+    ];
+
+    const [a, b] = await Promise.all([
+      seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db),
+      seedConfigValues(seeds, configTable, configEntity, mockRegistry, testDb.db),
+    ]);
+
+    const totalCreated = (a.created ?? 0) + (b.created ?? 0);
+    const totalSkipped = (a.skipped ?? 0) + (b.skipped ?? 0);
+    expect(totalCreated).toBe(1);
+    expect(totalSkipped).toBe(1);
+    expect(await countRows()).toBe(1);
+  });
+
+  test("unknown key — skipped gracefully", async () => {
+    const seeds: ConfigSeedDef[] = [
+      { key: "test:config:nonexistent", value: "nope", scope: "tenant" },
+    ];
+
+    const result = await seedConfigValues(
+      seeds,
+      configTable,
+      configEntity,
+      mockRegistry,
+      testDb.db,
+    );
+
+    expect(result).toEqual({ created: 0, skipped: 1 });
+    expect(await countRows()).toBe(0);
+  });
+
+  test("empty seeds returns 0/0", async () => {
+    const result = await seedConfigValues([], configTable, configEntity, mockRegistry, testDb.db);
+    expect(result).toEqual({ created: 0, skipped: 0 });
+  });
+});

package/src/db/config-seed.ts

@@ -0,0 +1,104 @@
+import { v5 as uuidv5 } from "uuid";
+import type { EntityDefinition } from "../engine";
+import { createSystemUser, SYSTEM_TENANT_ID } from "../engine";
+import type { ConfigSeedDef, Registry } from "../engine/types";
+import type { DbConnection } from "./connection";
+import type { EncryptionProvider } from "./encryption";
+import { createEventStoreExecutor } from "./event-store-executor";
+import type { DrizzleTable } from "./table-builder";
+import { createTenantDb } from "./tenant-db";
+
+// Namespace UUID for deterministic seed aggregate IDs. Same namespace +
+// (key, tenantId, userId) triple always produces the same UUIDv5, which
+// makes executor.create(…, expectedVersion: 0) hit version_conflict on
+// re-boot — no new stream created, idempotent without DB-level checks.
+const CONFIG_SEED_NS = "6f1e9d8c-2a5b-4c7d-9e3f-1a2b3c4d5e6f";
+
+/**
+ * Seed config values at boot time via the event-store executor.
+ *
+ * For each ConfigSeedDef: calls executor.create(payload, SYSTEM_USER, db).
+ * When the aggregate stream already exists (e.g. re-boot, admin-override),
+ * the executor returns a WriteFailure(version_conflict) which we skip.
+ *
+ * Idempotent, race-safe via DB-level unique constraints, and visible to
+ * multi-stream-projection subscribers as normal configValue.created events.
+ */
+export async function seedConfigValues(
+  seeds: readonly ConfigSeedDef[],
+  table: DrizzleTable,
+  entity: EntityDefinition,
+  registry: Registry,
+  db: DbConnection,
+  encryption?: EncryptionProvider,
+): Promise<{ created: number; skipped: number }> {
+  let created = 0;
+  let skipped = 0;
+
+  if (seeds.length === 0) return { created, skipped };
+
+  const systemUser = createSystemUser(SYSTEM_TENANT_ID);
+  const executor = createEventStoreExecutor(table, entity, { entityName: "config-value" });
+  const tdb = createTenantDb(db, SYSTEM_TENANT_ID, "system");
+
+  for (const seed of seeds) {
+    const keyDef = registry.getConfigKey(seed.key);
+    if (!keyDef) {
+      skipped++;
+      continue;
+    }
+
+    // Encrypted keys without an encryption provider would silently write
+    // plaintext to a column the resolver later tries to decrypt — fail
+    // loud at boot, not on first read in prod.
+    if (keyDef.encrypted && !encryption) {
+      throw new Error(
+        `seedConfigValues: key "${seed.key}" is encrypted but no EncryptionProvider was supplied.`,
+      );
+    }
+
+    const scope = seed.scope ?? keyDef.scope;
+
+    // User-scope seeds need a concrete tenantId because the resolver
+    // user-cascade matches the user's actual tenantId, not the SYSTEM
+    // sentinel — a SYSTEM-rooted user row would be unreachable.
+    if (scope === "user" && (!seed.tenantId || !seed.userId)) {
+      throw new Error(
+        `seedConfigValues: user-scope seed "${seed.key}" requires both tenantId and userId — use createUserSeed({value}, {tenantId, userId}).`,
+      );
+    }
+
+    const tenantId = seed.tenantId ?? SYSTEM_TENANT_ID;
+    const userId = scope === "user" ? (seed.userId ?? null) : null;
+
+    // Deterministic aggregate id (key+tenant+user triple) so re-boot hits
+    // the existing stream → version_conflict → counted as skipped.
+    const idSource = `${seed.key}:${tenantId}:${userId ?? ""}`;
+    const aggregateId = uuidv5(idSource, CONFIG_SEED_NS);
+
+    let value = JSON.stringify(seed.value);
+    if (keyDef.encrypted && encryption) {
+      value = encryption.encrypt(value);
+    }
+
+    const payload: Record<string, unknown> = {
+      id: aggregateId,
+      key: seed.key,
+      value,
+      tenantId,
+      userId,
+    };
+
+    const result = await executor.create(payload, systemUser, tdb);
+
+    if (result.isSuccess) {
+      created++;
+    } else {
+      // version_conflict (stream exists) and unique_violation (projection
+      // race) both mean "already seeded" — count as skipped, not error.
+      skipped++;
+    }
+  }
+
+  return { created, skipped };
+}

package/src/db/index.ts

@@ -1,5 +1,6 @@
 export { assertExistsIn } from "./assert-exists-in";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
+export { seedConfigValues } from "./config-seed";
 export type { DbConnection, DbConnectionOptions, DbRow, DbRunner, DbTx } from "./connection";
 export { createDbConnection, dbConnectionOptionsFromEnv } from "./connection";
 export type { CursorQueryOptions, CursorResult } from "./cursor";

package/src/engine/config-helpers.ts

@@ -4,7 +4,11 @@ import type {
   ConfigComputedFn,
   ConfigKeyDefinition,
   ConfigKeyType,
+  ConfigSeedDef,
   ConfigValue,
+  CreateSeedOptions,
+  CreateTenantSeedOptions,
+  CreateUserSeedOptions,
 } from "./types";
 
 // --- Access Presets ---
@@ -103,3 +107,52 @@ export function createUserConfig<T extends ConfigKeyType>(
 ): ConfigKeyDefinition<T> {
   return createConfigKey("user", type, opts);
 }
+
+// --- Seed Factories ---
+//
+// `key` is set to "" here — define-feature.ts fills in the qualified name
+// from the seeds-record-key during r.config() processing.
+
+// Scope-agnostic seed. The scope is derived from the matching keyDef in
+// define-feature.ts (via `seed.scope ?? keyDef.scope`). NOT usable for
+// user-scope keys — those need an explicit tenantId+userId, use
+// `createUserSeed` instead.
+export function createSeed(opts: CreateSeedOptions): ConfigSeedDef {
+  return { value: opts.value, key: "" };
+}
+
+// System-scope seed. Always writes under SYSTEM_TENANT_ID.
+export function createSystemSeed(opts: CreateSeedOptions): ConfigSeedDef {
+  return { value: opts.value, scope: "system", key: "" };
+}
+
+// Tenant-scope seed. `tenantId` omitted → fallback row under
+// SYSTEM_TENANT_ID (visible to all tenants via the resolver cascade).
+// Explicit `tenantId` → seed targets that one tenant only.
+export function createTenantSeed(
+  opts: CreateSeedOptions,
+  options?: CreateTenantSeedOptions,
+): ConfigSeedDef {
+  return {
+    value: opts.value,
+    scope: "tenant",
+    key: "",
+    tenantId: options?.tenantId,
+  };
+}
+
+// User-scope seed. Both tenantId AND userId are required — the resolver
+// matches against the user's actual tenantId, so a seed under
+// SYSTEM_TENANT_ID would never resolve.
+export function createUserSeed(
+  opts: CreateSeedOptions,
+  options: CreateUserSeedOptions,
+): ConfigSeedDef {
+  return {
+    value: opts.value,
+    scope: "user",
+    key: "",
+    tenantId: options.tenantId,
+    userId: options.userId,
+  };
+}

package/src/engine/define-feature.ts

@@ -13,6 +13,7 @@ import type {
   ConfigKeyDefinition,
   ConfigKeyHandle,
   ConfigKeyType,
+  ConfigSeedDef,
   EntityDefinition,
   EntityRef,
   EventDef,
@@ -112,6 +113,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     Record<string, PhasedHook<LifecycleHookFn>[]>
   > = { postSave: {}, preDelete: {}, postDelete: {} };
   const configKeys: Record<string, ConfigKeyDefinition> = {};
+  const configSeeds: ConfigSeedDef[] = [];
   const jobs: Record<string, JobDefinition> = {};
   const events: Record<string, { name: string; schema: ZodType; version: number }> = {};
   const eventMigrations: Record<string, EventMigrationDef[]> = {};
@@ -358,6 +360,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
 
     config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
       readonly keys: TKeys;
+      readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
     }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> } {
       // Qualify eagerly (same as defineEvent) so the handle name matches what
       // the registry stores — lazy qualification would break compile-time
@@ -370,6 +373,22 @@ export function defineFeature<const TName extends string, TExports = undefined>(
           type: keyDef.type,
         };
       }
+      // Parse seeds: resolve qualified key names and validate scope
+      if (definition.seeds) {
+        for (const [shortKey, seedDef] of Object.entries(definition.seeds)) {
+          const keyDef = definition.keys[shortKey];
+          if (!keyDef) continue; // skip — boot-validator reports unknown keys
+          const qualifiedKey = qn(toKebab(name), "config", toKebab(shortKey));
+          const scope = seedDef.scope ?? keyDef.scope;
+          configSeeds.push({
+            key: qualifiedKey,
+            value: seedDef.value,
+            scope,
+            tenantId: seedDef.tenantId,
+            userId: seedDef.userId,
+          });
+        }
+      }
       return handles as {
         readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]>;
       }; // @cast-boundary engine-bridge — Mapped-Type-Inference at config()-callsite
@@ -830,6 +849,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       postDelete: entityPostDelete,
     },
     configKeys,
+    configSeeds,
     jobs,
     notifications,
     registrarExtensions,

package/src/engine/index.ts

@@ -4,7 +4,16 @@ export { hasAccess } from "./access";
 export { validateBoot } from "./boot-validator";
 export { buildAppSchema } from "./build-app-schema";
 export { buildTarget } from "./build-target";
-export { access, createSystemConfig, createTenantConfig, createUserConfig } from "./config-helpers";
+export {
+  access,
+  createSeed,
+  createSystemConfig,
+  createSystemSeed,
+  createTenantConfig,
+  createTenantSeed,
+  createUserConfig,
+  createUserSeed,
+} from "./config-helpers";
 export type { SystemHookName } from "./constants";
 export {
   ConcurrencyModes,
@@ -193,6 +202,8 @@ export type {
   ConcurrencyMode,
   ConfigAccessor,
   ConfigAccessorFactory,
+  ConfigCascade,
+  ConfigCascadeLevel,
   ConfigDefinition,
   ConfigEditScreenDefinition,
   ConfigKeyAccess,
@@ -201,10 +212,15 @@ export type {
   ConfigKeyType,
   ConfigResolver,
   ConfigScope,
+  ConfigSeedDef,
   ConfigStoredRow,
+  ConfigStoredRowWithSource,
   ConfigValue,
   ConfigValueSource,
   ConfigValueWithSource,
+  CreateSeedOptions,
+  CreateTenantSeedOptions,
+  CreateUserSeedOptions,
   CustomScreenDefinition,
   CustomScreenRoute,
   DateFieldDef,
@@ -293,7 +309,6 @@ export type {
   TreeActionDef,
   TreeActionsHandle,
   TreeChildrenSubscribe,
-  TreeContext,
   TreeNode,
   TreeNodeState,
   UnsafeAppendEventFn,

package/src/engine/registry.ts

@@ -6,6 +6,7 @@ import type {
   AuthClaimsHookDef,
   ClaimKeyDefinition,
   ConfigKeyDefinition,
+  ConfigSeedDef,
   EntityDefinition,
   EntityRelations,
   EventDef,
@@ -136,6 +137,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   const extensionMap = new Map<string, RegistrarExtensionDef>();
   const extensionUsages: RegistrarExtensionRegistration[] = [];
   const allReferenceData: ReferenceDataDef[] = [];
+  const allConfigSeeds: ConfigSeedDef[] = [];
   const mergedTranslations: Record<string, Record<string, string>> = {};
   // Metric registry — keyed by fully qualified name (kumiko_<feature>_<short>).
   // Boot-time validation rejects bad names; dashboards then safely rely on shape.
@@ -425,6 +427,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     }
     extensionUsages.push(...feature.extensionUsages);
     allReferenceData.push(...feature.referenceData);
+    allConfigSeeds.push(...feature.configSeeds);
 
     // Metrics: validate + qualify per feature. Collisions across features are
     // rejected here — two features can't both register "created_total" under
@@ -1288,6 +1291,10 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       return allReferenceData;
     },
 
+    getAllConfigSeeds(): readonly ConfigSeedDef[] {
+      return allConfigSeeds;
+    },
+
     getProjectionsForSource(entityName: string): readonly ProjectionDefinition[] {
       return projectionsBySource.get(entityName) ?? [];
     },

package/src/engine/types/config.ts

@@ -123,6 +123,12 @@ export type ConfigStoredRow = {
   readonly userId: string | null;
 };
 
+// Extended row returned by ConfigResolver.getAllWithSource — includes the
+// resolution source so the UI can display where each value came from.
+export type ConfigStoredRowWithSource = ConfigStoredRow & {
+  readonly source: ConfigValueSource;
+};
+
 // Which layer of the cascade actually produced a value. Emitted only by
 // `getWithSource` — regular `get` hides this to keep the hot-path simple.
 // Use-case: Ops-debugging ("warum ist mein Wert 50 und nicht 100?") without
@@ -141,6 +147,22 @@ export type ConfigValueWithSource = {
   readonly source: ConfigValueSource;
 };
 
+/// Full cascade for a single config key — every level the resolver
+/// walks through, with the winning level marked.
+export type ConfigCascadeLevel = {
+  readonly label: string;
+  readonly value: string | number | boolean | undefined;
+  readonly source: ConfigValueSource;
+  readonly isActive: boolean;
+  readonly hasValue: boolean;
+};
+
+export type ConfigCascade = {
+  readonly value: string | number | boolean | undefined;
+  readonly source: ConfigValueSource;
+  readonly levels: readonly ConfigCascadeLevel[];
+};
+
 // Minimal contract handlers (set/reset/values.query) call against the
 // resolver. Lives in the framework so SharedContextFields.configResolver
 // can drop the `unknown` cast — the concrete implementation in
@@ -176,6 +198,39 @@ export type ConfigResolver = {
     userId: string,
     db: DbConnection | TenantDb,
   ): Promise<ReadonlyMap<string, ConfigStoredRow>>;
+
+  // Like getAll() but also reports the resolution source for each key.
+  // Use when the caller needs to display the cascade origin (e.g. the
+  // values.query handler serves the UI's hierarchy badge). Hot-path
+  // callers should prefer getAll() for the narrower return type.
+  getAllWithSource(
+    tenantId: TenantId,
+    userId: string,
+    db: DbConnection | TenantDb,
+  ): Promise<ReadonlyMap<string, ConfigStoredRowWithSource>>;
+
+  // Returns ALL cascade levels for a single key — not just the winner.
+  // Each level shows its value (or undefined if not set) and whether it
+  // is the active/winning level. Levels are ordered by specificity
+  // descending (most specific first).
+  getCascade(
+    qualifiedKey: string,
+    keyDef: ConfigKeyDefinition,
+    tenantId: TenantId,
+    userId: string,
+    db: DbConnection | TenantDb,
+  ): 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.
+  getCascadeBatch(
+    keys: readonly string[],
+    keyDefs: ReadonlyMap<string, ConfigKeyDefinition>,
+    tenantId: TenantId,
+    userId: string,
+    db: DbConnection | TenantDb,
+  ): Promise<ReadonlyMap<string, ConfigCascade>>;
 };
 
 // --- Process-Placement (runIn) ---
@@ -304,3 +359,44 @@ export type ReferenceDataDef = {
   readonly data: readonly Record<string, unknown>[];
   readonly upsertKey?: string | undefined;
 };
+
+// --- Config Seeding ---
+
+// A deploy-time default for a config key, written via the event-store
+// executor at boot. Idempotent — if the stream already exists the executor
+// returns version_conflict and seedConfigValues counts it as skipped.
+// See config-seeding.md.
+//
+// `scope` is optional on the factory-output: createSeed leaves it unset
+// (define-feature derives it from keyDef.scope). createSystemSeed /
+// createTenantSeed / createUserSeed always set it explicitly.
+//
+// `tenantId` / `userId` semantics:
+//   - system scope: both stay undefined (row stored under SYSTEM_TENANT_ID).
+//   - tenant scope: tenantId optional (undefined → fallback row under
+//     SYSTEM_TENANT_ID, visible to all tenants via resolver cascade).
+//   - user scope: BOTH tenantId AND userId required, otherwise the resolver
+//     can never match the row (user-scope cascade looks up the user's actual
+//     tenantId, not SYSTEM_TENANT_ID).
+export type ConfigSeedDef = {
+  readonly key: string; // fully-qualified config key name (set by define-feature)
+  readonly value: string | number | boolean;
+  readonly scope?: ConfigScope;
+  readonly tenantId?: string;
+  readonly userId?: string;
+};
+
+// Factory types for ergonomic seed creation in r.config({ seeds }).
+
+export type CreateSeedOptions = {
+  readonly value: string | number | boolean;
+};
+
+export type CreateTenantSeedOptions = {
+  readonly tenantId?: string;
+};
+
+export type CreateUserSeedOptions = {
+  readonly tenantId: string;
+  readonly userId: string;
+};

package/src/engine/types/feature.ts

@@ -5,6 +5,7 @@ import type {
   ConfigKeyDefinition,
   ConfigKeyHandle,
   ConfigKeyType,
+  ConfigSeedDef,
   JobDefinition,
   JobHandlerFn,
   NotificationDataFn,
@@ -170,6 +171,7 @@ export type FeatureDefinition = {
   readonly hooks: HookMap;
   readonly entityHooks: EntityHookMap;
   readonly configKeys: Readonly<Record<string, ConfigKeyDefinition>>;
+  readonly configSeeds: readonly ConfigSeedDef[];
   readonly jobs: Readonly<Record<string, JobDefinition>>;
   readonly registrarExtensions: Readonly<Record<string, RegistrarExtensionDef>>;
   readonly extensionUsages: readonly RegistrarExtensionRegistration[];
@@ -356,8 +358,11 @@ export type FeatureRegistrar<TFeature extends string = string> = {
 
   // Returns a handle map keyed exactly like the input. Pass any handle to
   // `ctx.config(handle)` to get the value type narrowed by the key's `type`.
+  // Optional `seeds` declare boot-time system-rows that are written via the
+  // event-store executor — idempotent, skipped when the stream already exists.
   config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
     readonly keys: TKeys;
+    readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
   }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> };
 
   job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
@@ -573,9 +578,10 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // that emits the top-level Tree-Knoten when the Visual-Workspace
   // (navigation: "tree") mounts. At-most-one call per feature.
   //
-  // Provider receives a TreeContext (Phase-0-stub, opaque) and an
-  // emit-function; returns an unsubscribe-function. Initial-emit synchron
-  // oder async, weitere Emits beliebig oft (e.g. on entity-update SSE).
+  // Provider returns a Subscribe-Function (emit-fn → unsubscribe-fn).
+  // Initial-emit synchron oder async, weitere Emits beliebig oft (e.g.
+  // on entity-update SSE). Provider sind session-bound; tenantId fließt
+  // über die Backend-Session bei fetch/dispatch, nicht über ein ctx-Arg.
   //
   // A feature without r.tree() is invisible in `navigation: "tree"`-
   // workspaces — that's the Zero-Whitelist-Filter from visual-tree.md A2:
@@ -655,6 +661,7 @@ export type Registry = {
   getAllTranslations(): TranslationKeys;
   getConfigKey(qualifiedKey: string): ConfigKeyDefinition | undefined;
   getAllConfigKeys(): ReadonlyMap<string, ConfigKeyDefinition>;
+  getAllConfigSeeds(): readonly ConfigSeedDef[];
   // Feature-declared secrets, aggregated across all registered features.
   // Keyed by qualified name ("<feature>:<shortName>"). Used by the rotation
   // job (to iterate "known" secrets) and admin-UIs to list available keys.

package/src/engine/types/identifiers.ts

@@ -1,4 +1,3 @@
-// @runtime client
 // Domain-identifier type aliases. Used everywhere a tenantId/userId/aggregateId
 // travels through the framework. One declaration per concept so future
 // representation changes (branded types, UUID validation, opaque wrappers)

package/src/engine/types/index.ts

@@ -13,6 +13,8 @@ export type {
   ConfigAccessor,
   ConfigAccessorFactory,
   ConfigBounds,
+  ConfigCascade,
+  ConfigCascadeLevel,
   ConfigComputedContext,
   ConfigComputedFn,
   ConfigDefinition,
@@ -21,10 +23,15 @@ export type {
   ConfigKeyHandle,
   ConfigKeyType,
   ConfigResolver,
+  ConfigSeedDef,
   ConfigStoredRow,
+  ConfigStoredRowWithSource,
   ConfigValue,
   ConfigValueSource,
   ConfigValueWithSource,
+  CreateSeedOptions,
+  CreateTenantSeedOptions,
+  CreateUserSeedOptions,
   JobDefinition,
   JobHandlerFn,
   JobRunIn,
@@ -218,7 +225,6 @@ export type {
   TreeActionDef,
   TreeActionsHandle,
   TreeChildrenSubscribe,
-  TreeContext,
   TreeNode,
   TreeNodeState,
 } from "./tree-node";

package/src/engine/types/tree-node.ts

@@ -23,7 +23,6 @@
 //
 // Siehe docs/plans/architecture/visual-tree.md A4.
 
-import type { TenantId } from "./identifiers";
 import type { TargetRef } from "./target-ref";
 
 export type TreeNodeState = "filled" | "stub" | "empty" | "loading" | "error";
@@ -75,25 +74,28 @@ export type TreeNode = {
 // Subscribe<T> — Provider implementiert: emit(initial); ...emit(updated);
 // und gibt unsubscribe-Function zurück. Caller (Tree-Component) ruft
 // unsubscribe auf wenn Knoten unmounted/eingeklappt wird.
-export type Subscribe<T> = (emit: (value: T) => void) => () => void;
+//
+// **V.1.4 emitError**: optional callback für async-error-Pfade (fetch-
+// fail, SSE-disconnect). Provider die explizit Errors signalisieren
+// wollen rufen `emitError(e)` statt empty-emit; VisualTree zeigt
+// Error-Banner mit Retry-Button. Sync-Throws im Provider-Body werden
+// vom useEffect-try/catch abgefangen — emitError ist nur für async.
+export type Subscribe<T> = (
+  emit: (value: T) => void,
+  emitError?: (error: Error) => void,
+) => () => void;
 
 // TreeChildrenSubscribe — Lazy-Variante für dynamic Children. Wird
-// erst aufgerufen wenn der Knoten im UI ausgeklappt wird. ctx ist
-// für Phase 0 ein opaque empty Type; V.1.1 erweitert ihn um Query-/
-// Subscribe-Helpers (entity-list, slug-list etc.).
-export type TreeChildrenSubscribe = (ctx: TreeContext) => Subscribe<readonly TreeNode[]>;
-
-// TreeContext — Provider erhält context-Objekt mit den minimal-nötigen
-// React-Tree-State-Bridges. V.1.1 startet mit `tenantId` only (Provider
-// braucht tenant-awareness sonst stale-tenant-Bug bei Tenant-Switch);
-// `query` und `subscribe` werden additiv ergänzt wenn ein konkreter
-// Konsument sie braucht (V.1.2: text-content slug-list-query, später
-// SSE-driven re-emit). Memory `[Keine Optionen ohne Bedarf]` — surface
-// wächst mit Bedarfen, nicht mit Spekulation. Siehe visual-tree.md
-// V.1.1-Decision D1.
-export type TreeContext = Readonly<{
-  readonly tenantId: TenantId;
-}>;
+// erst aufgerufen wenn der Knoten im UI ausgeklappt wird. Kein ctx-
+// Argument: Provider sind session-bound; Backend liest tenantId aus
+// session bei jedem fetch/dispatch. V.1.1 hatte ein ctx mit tenantId,
+// das aber im Browser nie echten Tenant trug (war auf SYSTEM_TENANT_ID
+// gepinnt) und vom einzigen V.1.2-Consumer (text-content) ignoriert
+// wurde. SR2-Rip 2026-05-18: Dead-API entfernt; wenn später ein
+// Provider tenant-aware-rendern muss (z.B. cross-tenant-Dashboards
+// für SystemAdmin), wird ctx mit echtem Tenant-Source aus dem Auth-
+// Layer re-introduziert. YAGNI bis dahin.
+export type TreeChildrenSubscribe = () => Subscribe<readonly TreeNode[]>;
 
 // TreeActionDef — Schema-Eintrag pro Action in der treeActions-Map
 // eines Features. Phase 0: Args sind ein optionales Type-Sample