@cosmicdrift/kumiko-bundled-features 0.4.0 → 0.5.0

package/src/config/__tests__/cascade.integration.ts

@@ -0,0 +1,419 @@
+import { seedConfigValues } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  ConfigCascade,
+  ConfigKeyDefinition,
+  ConfigKeyType,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  access,
+  createSystemConfig,
+  createSystemSeed,
+  createTenantConfig,
+  createTenantSeed,
+  createUserConfig,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { ConfigHandlers, ConfigQueries } from "../constants";
+import { createConfigAccessorFactory, createConfigFeature } from "../feature";
+import { type ConfigResolver, createConfigResolver } from "../resolver";
+import { configValueEntity, configValuesTable } from "../table";
+
+let stack: TestStack;
+let db: import("@cosmicdrift/kumiko-framework/db").DbConnection;
+let resolver: ConfigResolver;
+
+const tenantAdmin = createTestUser({ id: 2 });
+
+const cascadeFeature = defineFeature("cascade-test", (r) => {
+  r.requires("config");
+
+  r.config({
+    keys: {
+      tenantKey: createTenantConfig("text", {
+        default: "DEFAULT_TENANT",
+        read: access.all,
+        write: access.all,
+      }),
+      userKey: createUserConfig("text", {
+        default: "DEFAULT_USER",
+        read: access.all,
+        write: access.all,
+      }),
+      systemKey: createSystemConfig("text", {
+        default: "DEFAULT_SYSTEM",
+        read: access.systemAdmin,
+        write: access.systemAdmin,
+      }),
+      numberKey: createTenantConfig("number", {
+        default: 0,
+        read: access.all,
+        write: access.all,
+      }),
+      booleanKey: createTenantConfig("boolean", {
+        default: false,
+        read: access.all,
+        write: access.all,
+      }),
+      computedKey: createTenantConfig("number", {
+        // Plan-based stub: always returns 42 so the test can assert the
+        // `computed` level shows up between app-override and default.
+        computed: async () => 42,
+        read: access.all,
+        write: access.all,
+      }),
+    },
+    seeds: {
+      tenantKey: createTenantSeed({ value: "SEED_TENANT" }),
+      systemKey: createSystemSeed({ value: "SEED_SYSTEM" }),
+    },
+  });
+});
+
+const configFeature = createConfigFeature();
+
+const TENANT_KEY = "cascade-test:config:tenant-key";
+const USER_KEY = "cascade-test:config:user-key";
+const SYSTEM_KEY = "cascade-test:config:system-key";
+const NUMBER_KEY = "cascade-test:config:number-key";
+const BOOLEAN_KEY = "cascade-test:config:boolean-key";
+const COMPUTED_KEY = "cascade-test:config:computed-key";
+
+beforeAll(async () => {
+  resolver = createConfigResolver();
+
+  stack = await setupTestStack({
+    features: [configFeature, cascadeFeature],
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    }),
+  });
+  db = stack.db;
+
+  // Materialise the config-values projection table
+  await unsafePushTables(db, { configValuesTable });
+
+  // Execute seeds defined in the cascade-test feature
+  const seedDefs = stack.registry
+    .getAllConfigSeeds()
+    .filter((s) => s.key.startsWith("cascade-test:"));
+  await seedConfigValues(seedDefs, configValuesTable, configValueEntity, stack.registry, db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("getCascade", () => {
+  test("tenant-scope key with system-row (from seed) + default", async () => {
+    const keyDef = stack.registry.getConfigKey(TENANT_KEY);
+    expect(keyDef).toBeDefined();
+
+    const cascade = await resolver.getCascade(
+      TENANT_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    expect(cascade.levels.length).toBeGreaterThanOrEqual(4);
+    // Seed creates a system-row (tenantId = SYSTEM_TENANT_ID)
+    const systemLevel = cascade.levels.find((l) => l.source === "system-row");
+    expect(systemLevel).toBeDefined();
+    expect(systemLevel?.hasValue).toBe(true);
+    expect(systemLevel?.value).toBe("SEED_TENANT");
+
+    // No tenant-row for this tenant
+    const tenantLevel = cascade.levels.find((l) => l.source === "tenant-row");
+    expect(tenantLevel).toBeDefined();
+    expect(tenantLevel?.hasValue).toBe(false);
+
+    const defaultLevel = cascade.levels.find((l) => l.source === "default");
+    expect(defaultLevel).toBeDefined();
+
+    const activeLevels = cascade.levels.filter((l) => l.isActive);
+    expect(activeLevels.length).toBe(1);
+    expect(activeLevels[0]?.source).toBe("system-row");
+  });
+
+  test("tenant-scope key without tenant-row — default active", async () => {
+    const keyDef = stack.registry.getConfigKey(NUMBER_KEY);
+    expect(keyDef).toBeDefined();
+
+    const cascade = await resolver.getCascade(
+      NUMBER_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    expect(cascade.levels.length).toBeGreaterThanOrEqual(4);
+
+    const tenantLevel = cascade.levels.find((l) => l.source === "tenant-row");
+    expect(tenantLevel).toBeDefined();
+    expect(tenantLevel?.hasValue).toBe(false);
+
+    const systemLevel = cascade.levels.find((l) => l.source === "system-row");
+    expect(systemLevel).toBeDefined();
+    expect(systemLevel?.hasValue).toBe(false);
+
+    const activeLevels = cascade.levels.filter((l) => l.isActive);
+    expect(activeLevels.length).toBe(1);
+    expect(activeLevels[0]?.source).toBe("default");
+    expect(activeLevels[0]?.value).toBe(0);
+  });
+
+  test("tenant-scope key with default only (no rows)", async () => {
+    const keyDef = stack.registry.getConfigKey(BOOLEAN_KEY);
+    expect(keyDef).toBeDefined();
+
+    const cascade = await resolver.getCascade(
+      BOOLEAN_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    const activeLevels = cascade.levels.filter((l) => l.isActive);
+    expect(activeLevels.length).toBe(1);
+    expect(activeLevels[0]?.source).toBe("default");
+    expect(activeLevels[0]?.value).toBe(false);
+  });
+
+  test("user-scope key with user + tenant-row", async () => {
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: USER_KEY, value: "TENANT_VAL", scope: "tenant" },
+      tenantAdmin,
+    );
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: USER_KEY, value: "USER_VAL", scope: "user" },
+      tenantAdmin,
+    );
+
+    const keyDef = stack.registry.getConfigKey(USER_KEY);
+    expect(keyDef).toBeDefined();
+
+    const cascade = await resolver.getCascade(
+      USER_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    const userLevel = cascade.levels.find((l) => l.source === "user-row");
+    expect(userLevel).toBeDefined();
+    expect(userLevel?.value).toBe("USER_VAL");
+    expect(userLevel?.isActive).toBe(true);
+
+    const tenantLevel = cascade.levels.find((l) => l.source === "tenant-row");
+    expect(tenantLevel).toBeDefined();
+    expect(tenantLevel?.value).toBe("TENANT_VAL");
+    expect(tenantLevel?.isActive).toBe(false);
+  });
+
+  test("system-scope key with system-row + default", async () => {
+    const keyDef = stack.registry.getConfigKey(SYSTEM_KEY);
+    expect(keyDef).toBeDefined();
+
+    const cascade = await resolver.getCascade(
+      SYSTEM_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    expect(cascade.levels.length).toBeGreaterThanOrEqual(3);
+    const systemLevel = cascade.levels.find((l) => l.source === "system-row");
+    expect(systemLevel).toBeDefined();
+    expect(systemLevel?.hasValue).toBe(true);
+    expect(systemLevel?.value).toBe("SEED_SYSTEM");
+    expect(systemLevel?.isActive).toBe(true);
+  });
+});
+
+describe("getCascadeBatch", () => {
+  test("batch returns cascades for multiple keys", async () => {
+    const keys = [TENANT_KEY, NUMBER_KEY, BOOLEAN_KEY];
+    const keyDefs = new Map<string, ConfigKeyDefinition<ConfigKeyType>>();
+    for (const k of keys) {
+      const keyDef = stack.registry.getConfigKey(k);
+      if (keyDef) keyDefs.set(k, keyDef);
+    }
+
+    const cascades = await resolver.getCascadeBatch(
+      keys,
+      keyDefs,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    expect(cascades.size).toBe(3);
+    for (const [, cascade] of cascades) {
+      expect(cascade.levels.length).toBeGreaterThanOrEqual(4);
+    }
+  });
+
+  test("empty keys returns empty map", async () => {
+    const cascades = await resolver.getCascadeBatch(
+      [],
+      new Map(),
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+    expect(cascades.size).toBe(0);
+  });
+});
+
+describe("cascade levels — non-DB sources", () => {
+  test("computed key shows as active computed level when no row exists", async () => {
+    const keyDef = stack.registry.getConfigKey(COMPUTED_KEY);
+    expect(keyDef).toBeDefined();
+
+    const cascade = await resolver.getCascade(
+      COMPUTED_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    const computedLevel = cascade.levels.find((l) => l.source === "computed");
+    expect(computedLevel).toBeDefined();
+    expect(computedLevel?.hasValue).toBe(true);
+    expect(computedLevel?.value).toBe(42);
+    expect(computedLevel?.isActive).toBe(true);
+    expect(cascade.value).toBe(42);
+    expect(cascade.source).toBe("computed");
+  });
+
+  test("app-override appears above computed/default when set in resolver options", async () => {
+    // Build a one-off resolver with appOverrides to verify the cascade
+    // surfaces the override-level — main `resolver` is plain and would
+    // skip this path.
+    const overrideResolver = createConfigResolver({
+      appOverrides: new Map<string, string | number | boolean>([[BOOLEAN_KEY, true]]),
+    });
+    const keyDef = stack.registry.getConfigKey(BOOLEAN_KEY);
+    expect(keyDef).toBeDefined();
+
+    const cascade = await overrideResolver.getCascade(
+      BOOLEAN_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+
+    const overrideLevel = cascade.levels.find((l) => l.source === "app-override");
+    expect(overrideLevel).toBeDefined();
+    expect(overrideLevel?.hasValue).toBe(true);
+    expect(overrideLevel?.value).toBe(true);
+    expect(overrideLevel?.isActive).toBe(true);
+    // System-row stays empty; tenant-row also empty → override wins.
+    expect(cascade.value).toBe(true);
+    expect(cascade.source).toBe("app-override");
+  });
+});
+
+describe("reset cycle regression", () => {
+  // Pins the executor-create-with-fresh-id contract: hard-delete +
+  // re-set must hit a NEW aggregate stream, never version_conflict
+  // against the deleted one. If someone ever flips configValueEntity
+  // to deterministic IDs without adjusting set.write.ts, this test
+  // will catch the regression.
+  test("set → reset → set succeeds (no version_conflict)", async () => {
+    const RESET_KEY = NUMBER_KEY;
+
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: RESET_KEY, value: 11, scope: "tenant" },
+      tenantAdmin,
+    );
+
+    await stack.http.writeOk(
+      ConfigHandlers.reset,
+      { key: RESET_KEY, scope: "tenant" },
+      tenantAdmin,
+    );
+
+    // Second set after reset — would version_conflict if the executor
+    // re-used the deleted stream's aggregateId.
+    await stack.http.writeOk(
+      ConfigHandlers.set,
+      { key: RESET_KEY, value: 22, scope: "tenant" },
+      tenantAdmin,
+    );
+
+    const keyDef = stack.registry.getConfigKey(RESET_KEY);
+    expect(keyDef).toBeDefined();
+    const cascade = await resolver.getCascade(
+      RESET_KEY,
+      keyDef!,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+    expect(cascade.value).toBe(22);
+    expect(cascade.source).toBe("tenant-row");
+  });
+});
+
+describe("config:query:cascade handler", () => {
+  test("systemAdmin sees all keys including SystemAdmin-restricted ones", async () => {
+    const data = await stack.http.queryOk<Record<string, ConfigCascade>>(
+      ConfigQueries.cascade,
+      {},
+      TestUsers.systemAdmin,
+    );
+
+    expect(data[TENANT_KEY]).toBeDefined();
+    expect(data[NUMBER_KEY]).toBeDefined();
+    expect(data[BOOLEAN_KEY]).toBeDefined();
+    expect(data[SYSTEM_KEY]).toBeDefined();
+
+    for (const cascade of Object.values(data)) {
+      expect(cascade.levels).toBeDefined();
+      expect(Array.isArray(cascade.levels)).toBe(true);
+    }
+  });
+
+  test("filters to specific keys when keys param is set", async () => {
+    const data = await stack.http.queryOk<Record<string, ConfigCascade>>(
+      ConfigQueries.cascade,
+      { keys: [TENANT_KEY] },
+      tenantAdmin,
+    );
+
+    expect(Object.keys(data).length).toBe(1);
+    expect(data[TENANT_KEY]).toBeDefined();
+  });
+
+  test("user without read access does not see SystemAdmin-restricted key", async () => {
+    const data = await stack.http.queryOk<Record<string, ConfigCascade>>(
+      ConfigQueries.cascade,
+      {},
+      createTestUser({ id: 99, roles: ["User"] }),
+    );
+
+    expect(data[SYSTEM_KEY]).toBeUndefined();
+    // But keys with `read: access.all` stay visible to plain users.
+    expect(data[TENANT_KEY]).toBeDefined();
+  });
+});

package/src/config/__tests__/config.integration.ts

@@ -1,11 +1,18 @@
 import { randomBytes } from "node:crypto";
-import { createEncryptionProvider, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEncryptionProvider,
+  type DbConnection,
+  seedConfigValues,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
+  createSeed,
   createSystemConfig,
+  createSystemSeed,
   createTenantConfig,
   createUserConfig,
   defineFeature,
+  type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import {
@@ -22,7 +29,7 @@ import { z } from "zod";
 import { ConfigHandlers, ConfigQueries } from "../constants";
 import { createConfigAccessor, createConfigAccessorFactory, createConfigFeature } from "../feature";
 import { type ConfigResolver, createConfigResolver, validateAppOverrides } from "../resolver";
-import { configValuesTable } from "../table";
+import { configValueEntity, configValuesTable } from "../table";
 
 // --- Setup ---
 
@@ -173,6 +180,22 @@ const integrationFeature = defineFeature("integration", (r) => {
 });
 
 const configFeature = createConfigFeature();
+
+// Scenario 11: Config seeding — feature with deploy-time defaults
+const seedFeature = defineFeature("seeddemo", (r) => {
+  r.requires("config");
+  return r.config({
+    keys: {
+      themeColor: createTenantConfig("text", { default: "blue" }),
+      maintenanceMode: createSystemConfig("boolean", { default: false }),
+    },
+    seeds: {
+      themeColor: createSeed({ value: "dark" }),
+      maintenanceMode: createSystemSeed({ value: true }),
+    },
+  });
+});
+
 const testEncryptionKey = randomBytes(32).toString("base64");
 
 beforeAll(async () => {
@@ -188,6 +211,7 @@ beforeAll(async () => {
       ordersFeature,
       integrationFeature,
       probeFeature,
+      seedFeature,
     ],
     // Wire `ctx.config()` for real handlers: pass the resolver-bound factory
     // so the dispatcher can mint a per-user accessor inside buildHandlerContext.
@@ -1244,3 +1268,86 @@ describe("scenario 10: getWithSource reports source-of-truth", () => {
     expect(traced.value).toBe(flat);
   });
 });
+
+// --- Scenario 11: Config Seeding ---
+//
+// Seeds are deploy-time defaults written as system-rows via the event-store
+// executor. They sit at cascade level 4 (system-row) — above app-override
+// and default but below any explicit user/tenant row.
+
+describe("scenario 11: config seeding", () => {
+  const SEED_THEME = "seeddemo:config:theme-color";
+  const SEED_MAINT = "seeddemo:config:maintenance-mode";
+  const T1 = "00000000-0000-4000-8000-0000000000aa" as TenantId;
+  const T2 = "00000000-0000-4000-8000-0000000000bb" as TenantId;
+  const T3 = "00000000-0000-4000-8000-0000000000cc" as TenantId;
+
+  beforeAll(async () => {
+    const seedDefs = stack.registry
+      .getAllConfigSeeds()
+      .filter((s) => s.key.startsWith("seeddemo:"));
+    await seedConfigValues(seedDefs, configValuesTable, configValueEntity, stack.registry, db);
+  });
+
+  test("returns seed value when no row exists", async () => {
+    const configFn = createConfigAccessor(
+      stack.registry,
+      resolver,
+      T1,
+      "00000000-0000-4000-8000-0000000000aa",
+      db,
+    );
+    expect(await configFn(SEED_THEME)).toBe("dark");
+  });
+
+  test("system-scope seed produces system-row in cascade", async () => {
+    const configFn = createConfigAccessor(
+      stack.registry,
+      resolver,
+      T1,
+      "00000000-0000-4000-8000-0000000000aa",
+      db,
+    );
+    expect(await configFn(SEED_MAINT)).toBe(true);
+  });
+
+  test("getWithSource reports source=system-row for seeded values", async () => {
+    const keyDef = stack.registry.getConfigKey(SEED_THEME);
+    if (!keyDef) throw new Error("key missing");
+    const traced = await resolver.getWithSource(
+      SEED_THEME,
+      keyDef,
+      T2,
+      "00000000-0000-4000-8000-0000000000bb",
+      db,
+    );
+    expect(traced.value).toBe("dark");
+    expect(traced.source).toBe("system-row");
+  });
+
+  test("seed + app-override: seed wins (system-row > app-override)", async () => {
+    const resolverWithOverride = createConfigResolver({
+      appOverrides: validateAppOverrides(stack.registry, { [SEED_THEME]: "pink" }),
+    });
+    const configFn = createConfigAccessor(
+      stack.registry,
+      resolverWithOverride,
+      T3,
+      "00000000-0000-4000-8000-0000000000cc",
+      db,
+    );
+    expect(await configFn(SEED_THEME)).toBe("dark");
+  });
+
+  test("admin override beats seed (tenant-row > system-row)", async () => {
+    await stack.http.writeOk(ConfigHandlers.set, { key: SEED_THEME, value: "red" }, tenantAdmin);
+    const configFn = createConfigAccessor(
+      stack.registry,
+      resolver,
+      tenantAdmin.tenantId,
+      tenantAdmin.id,
+      db,
+    );
+    expect(await configFn(SEED_THEME)).toBe("red");
+  });
+});

package/src/config/constants.ts

@@ -9,6 +9,7 @@ export const ConfigHandlers = {
 
 // Qualified query handler names (QN format: scope:type:name)
 export const ConfigQueries = {
+  cascade: "config:query:cascade",
   values: "config:query:values",
   schema: "config:query:schema",
 } as const;

package/src/config/feature.ts

@@ -12,6 +12,7 @@ import {
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { cascadeQuery } from "./handlers/cascade.query";
 import { resetWrite } from "./handlers/reset.write";
 import { schemaQuery } from "./handlers/schema.query";
 import { setWrite } from "./handlers/set.write";
@@ -38,6 +39,7 @@ export function createConfigFeature(): FeatureDefinition {
     };
 
     const queries = {
+      cascade: r.queryHandler(cascadeQuery),
       values: r.queryHandler(valuesQuery),
       schema: r.queryHandler(schemaQuery),
     };

package/src/config/handlers/cascade.query.ts

@@ -0,0 +1,70 @@
+import {
+  type ConfigCascade,
+  type ConfigCascadeLevel,
+  defineQueryHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { requireConfigResolver } from "../feature";
+import { hasConfigAccess } from "../write-helpers";
+
+const MASKED = "••••••";
+
+export const cascadeQuery = defineQueryHandler({
+  name: "cascade",
+  schema: z.object({
+    keys: z.array(z.string()).optional(),
+  }),
+  access: { openToAll: true },
+  handler: async (query, ctx) => {
+    const db = ctx.db;
+    const registry = ctx.registry;
+    const resolver = requireConfigResolver(ctx, "config:query:cascade");
+
+    const allKeys = registry.getAllConfigKeys();
+    const keys = query.payload.keys ?? Array.from(allKeys.keys());
+
+    const keyDefs = new Map<
+      string,
+      import("@cosmicdrift/kumiko-framework/engine").ConfigKeyDefinition
+    >();
+    const filteredKeys: string[] = [];
+
+    for (const key of keys) {
+      const keyDef = allKeys.get(key);
+      if (!keyDef) continue;
+      if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
+      keyDefs.set(key, keyDef);
+      filteredKeys.push(key);
+    }
+
+    const cascades = await resolver.getCascadeBatch(
+      filteredKeys,
+      keyDefs,
+      query.user.tenantId,
+      query.user.id,
+      db,
+    );
+
+    const result: Record<string, ConfigCascade> = {};
+    for (const [key, cascade] of cascades) {
+      const keyDef = keyDefs.get(key);
+      if (!keyDef) continue;
+
+      if (keyDef.encrypted) {
+        const maskedLevels: ConfigCascadeLevel[] = cascade.levels.map((l) => ({
+          ...l,
+          value: l.hasValue ? MASKED : l.value,
+        }));
+        result[key] = {
+          value: cascade.value !== undefined ? MASKED : cascade.value,
+          source: cascade.source,
+          levels: maskedLevels,
+        };
+      } else {
+        result[key] = cascade;
+      }
+    }
+
+    return result;
+  },
+});

package/src/config/handlers/values.query.ts

@@ -1,4 +1,8 @@
-import { type ConfigScope, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type ConfigScope,
+  type ConfigValueSource,
+  defineQueryHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import { requireConfigResolver } from "../feature";
 import { deserializeValue } from "../resolver";
@@ -15,11 +19,15 @@ export const valuesQuery = defineQueryHandler({
     const resolver = requireConfigResolver(ctx, "config:query:values");
 
     const allKeys = registry.getAllConfigKeys();
-    const storedValues = await resolver.getAll(query.user.tenantId, query.user.id, db);
+    const storedValues = await resolver.getAllWithSource(query.user.tenantId, query.user.id, db);
 
     const result: Record<
       string,
-      { value: string | number | boolean | undefined; scope: ConfigScope }
+      {
+        value: string | number | boolean | undefined;
+        scope: ConfigScope;
+        source: ConfigValueSource;
+      }
     > = {};
 
     for (const [qualifiedKey, keyDef] of allKeys) {
@@ -27,6 +35,8 @@ export const valuesQuery = defineQueryHandler({
 
       const stored = storedValues.get(qualifiedKey);
       let value: string | number | boolean | undefined;
+      const source: ConfigValueSource = stored?.source ?? "default";
+
       if (keyDef.encrypted) {
         value = stored ? "••••••" : undefined;
       } else if (stored?.value !== null && stored?.value !== undefined) {
@@ -35,7 +45,7 @@ export const valuesQuery = defineQueryHandler({
         value = keyDef.default;
       }
 
-      result[qualifiedKey] = { value, scope: keyDef.scope };
+      result[qualifiedKey] = { value, scope: keyDef.scope, source };
     }
 
     return result;