@cosmicdrift/kumiko-framework 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @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

package/package.json

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

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;
@@ -656,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/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,