@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/config/handlers/cascade.query.ts

@@ -0,0 +1,94 @@
+import {
+  type ConfigCascade,
+  type ConfigCascadeLevel,
+  defineQueryHandler,
+  isEncryptedAtRest,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { requireConfigResolver, requireSystemDb } from "../feature.js";
+import { MASKED, redactInheritedCascade, shouldRedactInherited } from "../read-redaction.js";
+import { hasConfigAccess } from "../write-helpers.js";
+
+export const cascadeQuery = defineQueryHandler({
+  name: "cascade",
+  description:
+    "Shows, per config key the caller may read, the value at every cascade level (user, tenant, system, app override, default) and which level won; use it to explain where a setting's current value comes from.",
+  schema: z.object({
+    keys: z.array(z.string()).optional(),
+  }),
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call cascade; hasConfigAccess filters the result to " +
+        "only the config keys the caller's roles may read, before any value is returned",
+    },
+  },
+  rateLimit: {
+    disabled: true,
+    reason:
+      "self-scoped read of the caller's own readable config cascade, hit on every page load; " +
+      "per-tenant bucket would throttle the whole tenant, L1 IP limit still applies",
+  },
+  handler: async (query, ctx) => {
+    const db = requireSystemDb(ctx, "config:query:cascade", query.user.tenantId);
+    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,
+      ctx.secrets,
+    );
+
+    const result: Record<string, ConfigCascade> = {};
+    for (const [key, rawCascade] of cascades) {
+      const keyDef = keyDefs.get(key);
+      if (!keyDef) continue;
+
+      // Redact the inherited platform value (system-row, app-override,
+      // computed, default) BEFORE masking — masking alone leaves hasValue=true
+      // and would still leak "it is set" to a tenant.
+      const cascade = shouldRedactInherited(keyDef, query.user.roles)
+        ? redactInheritedCascade(rawCascade)
+        : rawCascade;
+
+      // backing="secrets" is masked like encrypted — the resolver revealed the
+      // plaintext for internal reads, but it must never reach the cascade UI.
+      if (isEncryptedAtRest(keyDef)) {
+        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/packages/bundled-features/src/config/handlers/readiness.query.ts

@@ -0,0 +1,164 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type ConfigKeyType,
+  type ConfigScope,
+  defineQueryHandler,
+  type HandlerContext,
+  type SessionUser,
+  toKebab,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { requireConfigResolver, requireSystemDb } from "../feature.js";
+import { hasConfigAccess } from "../write-helpers.js";
+
+export type ReadinessMissingKey = {
+  readonly key: string;
+  readonly scope: ConfigScope;
+  readonly type: ConfigKeyType;
+};
+
+// Mirrors requireNonEmpty in foundation-shared/config-helpers.ts: required
+// text keys ship default "" and count as unset while empty/whitespace.
+function isUnset(value: string | number | boolean | undefined, type: ConfigKeyType): boolean {
+  if (value === undefined) return true;
+  return type === "text" && typeof value === "string" && value.trim().length === 0;
+}
+
+// Whether a required key/secret counts for THIS tenant right now. Keys of
+// provider-features under a selector-declared extension point count only
+// while their provider is the selected one — an SMTP password is no gap
+// for a tenant running the inmemory transport.
+export type RequiredKeyGate = (qualifiedName: string) => boolean;
+
+// Builds the per-tenant gate from r.extensionSelector declarations: resolve
+// each selector through the config cascade, mark every provider-feature
+// registered under that point as counted/uncounted. Features without a
+// selector-gated registration always count. `db` is the caller's own scoped
+// handle — config's own handlers pass requireSystemDb's result, the plain
+// tenant-scoped readiness feature passes its own ctx.db. This function makes
+// no scope decision itself; see readiness/handlers/status.query.ts and
+// config/handlers/readiness.query.ts's own handler for the two call sites.
+export async function buildProviderSelectionGate(
+  ctx: HandlerContext,
+  callerQn: string,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<RequiredKeyGate> {
+  const resolver = requireConfigResolver(ctx, callerQn);
+  const countsByFeature = new Map<string, boolean>();
+  for (const [extensionName, selectorKey] of ctx.registry.getAllExtensionSelectors()) {
+    const keyDef = ctx.registry.getConfigKey(selectorKey);
+    if (!keyDef) continue; // registry-build already failed this; defensive
+    const value = await resolver.get(selectorKey, keyDef, user.tenantId, user.id, db);
+    const selected = typeof value === "string" ? value.trim() : "";
+    for (const usage of ctx.registry.getExtensionUsages(extensionName)) {
+      if (usage.featureName === undefined) continue;
+      const owner = toKebab(usage.featureName);
+      const isSelected = usage.entityName === selected;
+      countsByFeature.set(owner, (countsByFeature.get(owner) ?? false) || isSelected);
+    }
+  }
+  return (qualifiedName) => countsByFeature.get(qualifiedName.split(":")[0] ?? "") ?? true;
+}
+
+// Core of config:query:readiness, exported through the config barrel so the
+// readiness rollup-feature reuses the exact same cascade + access filter.
+// Resolved through the same cascade as ctx.config() so readiness can never
+// drift from what the owning feature's build-fn will see. Note:
+// required+encrypted assumes encryption is wired — resolver.get decrypts
+// stored values, same prerequisite as any ctx.config() read of that key.
+export async function collectMissingRequiredConfig(
+  ctx: HandlerContext,
+  callerQn: string,
+  user: SessionUser,
+  db: TenantDb,
+  gate?: RequiredKeyGate,
+  options?: {
+    /** Verdict-Pfade (Rollup, selbst role-gated) MÜSSEN ungefiltert zählen:
+     *  der Per-Key-read-Filter ist Info-Disclosure-Schutz für den
+     *  openToAll-Handler — im Verdict droppte er SystemAdmin-gated
+     *  required-Keys still und meldete ready:true trotz Lücke. */
+    readonly skipAccessFilter?: boolean;
+  },
+): Promise<ReadinessMissingKey[]> {
+  const resolver = requireConfigResolver(ctx, callerQn);
+  const effectiveGate = gate ?? (await buildProviderSelectionGate(ctx, callerQn, user, db));
+  // Kandidaten erst sammeln, dann EIN Batch-Resolve — die sequentielle
+  // resolver.get-Schleife war ein N+1 über alle required Keys (272/1).
+  type KeyDef =
+    ReturnType<typeof ctx.registry.getAllConfigKeys> extends ReadonlyMap<string, infer D>
+      ? D
+      : never;
+  const candidates = new Map<string, KeyDef>();
+  for (const [qualifiedKey, keyDef] of ctx.registry.getAllConfigKeys()) {
+    if (keyDef.required !== true) continue;
+    if (!effectiveGate(qualifiedKey)) continue;
+    if (options?.skipAccessFilter !== true && !hasConfigAccess(keyDef.access.read, user.roles)) {
+      // skip: key not visible to this user's roles (access-filtered listing)
+      continue;
+    }
+    candidates.set(qualifiedKey, keyDef);
+  }
+  const missing: ReadinessMissingKey[] = [];
+  const cascades = await resolver.getCascadeBatch(
+    [...candidates.keys()],
+    candidates,
+    user.tenantId,
+    user.id,
+    db,
+    ctx.secrets,
+  );
+  for (const [qualifiedKey, keyDef] of candidates) {
+    // Deliberately the unredacted cascade value: readiness asks "does this
+    // tenant functionally have the value?", and an inheritedToTenant:false key
+    // set only at system-level IS inherited (the resolver ignores
+    // inheritedToTenant — that flag only redacts the value queries' display).
+    // Redacting here would report a working key as missing. The is-set bit this
+    // exposes is intentional; see read-redaction.ts.
+    const value = cascades.get(qualifiedKey)?.value;
+    if (isUnset(value, keyDef.type)) {
+      missing.push({ key: qualifiedKey, scope: keyDef.scope, type: keyDef.type });
+    }
+  }
+  return missing;
+}
+
+// No boolean "ready" verdict on purpose — config readiness says nothing
+// about secrets. readiness:query:status (readiness feature) rolls both up.
+export const readinessQuery = defineQueryHandler({
+  name: "readiness",
+  description:
+    "Lists the required config keys that are still unset for the caller's tenant, each with its scope and type; use it to find out what is missing before a feature can run.",
+  schema: z.object({}),
+  // Per-key read access enforced via hasConfigAccess inside the handler.
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call readiness; collectMissingRequiredConfig filters " +
+        "candidate keys through hasConfigAccess so only keys the caller's roles may read are reported",
+    },
+  },
+  rateLimit: {
+    disabled: true,
+    reason:
+      "self-scoped read of the caller's own tenant's config readiness, hit on every page load; " +
+      "per-tenant bucket would throttle the whole tenant, L1 IP limit still applies",
+  },
+  handler: async (query, ctx) => {
+    const db = requireSystemDb(ctx, "config:query:readiness", query.user.tenantId);
+    const missing = await collectMissingRequiredConfig(
+      ctx,
+      "config:query:readiness",
+      query.user,
+      db,
+    );
+    // Additive, display-ready fields for the admin-shell dashboard stat
+    // panel (fw#2312) — `missing` itself stays untouched for existing
+    // consumers that read the array directly.
+    return {
+      missing,
+      missingCount: missing.length,
+      missingTone: missing.length > 0 ? "warn" : "default",
+    };
+  },
+});

package/packages/bundled-features/src/config/handlers/reencrypt.job.ts

@@ -0,0 +1,274 @@
+// KEK-rotation job for `encrypted: true` config values: envelope values
+// wrapped under an older kekVersion get re-encrypted under
+// provider.currentVersion(). Config has no kek_version column (values live
+// in a TEXT column), so unlike the secrets rotate job the version check
+// parses the stored JSON.
+//
+// A row whose value isn't a current-cipher envelope (malformed JSON, or
+// any pre-envelope format) is counted `failed` before any decrypt attempt
+// and left untouched — migrateRow short-circuits on `unrecognized` instead
+// of relying on cipher.decrypt to reject it. No legacy single-key path.
+//
+// Idempotent: a re-run skips rows already on the current version. Every
+// write goes through the event-store executor (config values are
+// entity-backed — raw UPDATEs would be wiped by a projection rebuild),
+// so each rotation appends a normal `.updated` event whose payload carries
+// the NEW envelope: after a full run even a from-scratch rebuild only
+// ever sees the current-KEK envelope.
+//
+// systemScope() fail-closed pattern (framework#2056): the initial scan is
+// intentionally cross-tenant (system-wide key rotation), acknowledged via
+// UncheckedSystemDb.acknowledgeCrossTenant(). Rows are bucketed by tenant,
+// and assertRowsTenant() re-verifies each row against its bucket's tenant
+// right before the write — both checks are built locally from the exported
+// createSystemDbView().
+
+import {
+  createEventStoreExecutor,
+  createSystemDbView,
+  createTenantDb,
+  type DbConnection,
+  type TenantDb,
+  type UncheckedSystemDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  type JobHandlerFn,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { createEscapeHatchReporter } from "@cosmicdrift/kumiko-framework/pipeline";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  type ChunkedMigrationStopReason,
+  classifyStoredEnvelope,
+  runChunkedMigration,
+} from "../../shared/index.js";
+import { configValueEntity, configValuesTable } from "../table.js";
+
+const DEFAULT_MAX_FAILURES = 10;
+const SCAN_SLICE_SIZE = 100;
+const SYSTEM_ROLES = ["system"] as const;
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+export type ReencryptJobPayload = {
+  readonly maxDurationMs?: number;
+  readonly maxFailures?: number;
+};
+
+export type ReencryptJobResult = {
+  readonly migrated: number;
+  readonly failed: number;
+  readonly alreadyCurrent: number;
+  readonly stoppedReason: ChunkedMigrationStopReason;
+};
+
+export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
+  const payload = rawPayload as ReencryptJobPayload; // @cast-boundary engine-payload
+  const maybeCipher = ctx.configEncryption;
+  if (!maybeCipher) {
+    throw new InternalError({
+      message:
+        "[config:reencrypt] ctx.configEncryption missing — provide a master key " +
+        "(KUMIKO_SECRETS_MASTER_KEY_V<n>) so the boot wires the envelope cipher.",
+    });
+  }
+  // hoisted function declarations below capture these — pin the narrowed
+  // type explicitly so TS keeps it inside the closures
+  const cipher: EnvelopeCipher = maybeCipher;
+  const provider = ctx.masterKeyProvider;
+  if (!provider) {
+    throw new InternalError({
+      message:
+        "[config:reencrypt] ctx.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
+    });
+  }
+  if (!ctx.registry) {
+    throw new InternalError({
+      message: "[config:reencrypt] ctx.registry missing — job context requires the registry.",
+    });
+  }
+  // config is r.systemScope(), so ctx.systemDb is always present on its jobs.
+  if (!ctx.systemDb) {
+    throw new InternalError({
+      message: "[config:reencrypt] ctx.systemDb missing on a system-scoped job",
+    });
+  }
+  const db = ctx.systemDb.unsafeRaw(
+    "system-wide KEK rotation scans every tenant's encrypted config values",
+  ) as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
+
+  const encryptedKeys = [...ctx.registry.getAllConfigKeys()]
+    .filter(([, def]) => def.encrypted === true)
+    .map(([key]) => key);
+
+  const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
+  const deadline = payload.maxDurationMs
+    ? Date.now() + payload.maxDurationMs
+    : Number.POSITIVE_INFINITY;
+
+  function reportEscapeHatchFor(tenantId: TenantId) {
+    return createEscapeHatchReporter({
+      handler: "config:job:reencrypt",
+      tenantId,
+      actor: "system",
+      sink: ctx._escapeHatchAuditSink,
+      log: ctx.log,
+    });
+  }
+
+  const tdbCache = new Map<TenantId, TenantDb>();
+  function tdbFor(tenantId: TenantId): TenantDb {
+    let existing = tdbCache.get(tenantId);
+    if (!existing) {
+      existing = createTenantDb(db, tenantId, "system");
+      tdbCache.set(tenantId, existing);
+    }
+    return existing;
+  }
+
+  const sdbCache = new Map<TenantId, UncheckedSystemDb>();
+  function sdbFor(tenantId: TenantId): UncheckedSystemDb {
+    let existing = sdbCache.get(tenantId);
+    if (!existing) {
+      existing = createSystemDbView(tdbFor(tenantId), undefined, reportEscapeHatchFor(tenantId));
+      sdbCache.set(tenantId, existing);
+    }
+    return existing;
+  }
+
+  // Standalone from sdbCache/tdbCache on purpose: this one is only ever used
+  // to acknowledge the cross-tenant scan below, never bound to a real
+  // tenant's writes — sharing it with sdbFor(SYSTEM_TENANT_ID) would make a
+  // write-path cache entry double as the scan's ack gate.
+  const scanDb = createSystemDbView(
+    createTenantDb(db, SYSTEM_TENANT_ID, "system"),
+    undefined,
+    reportEscapeHatchFor(SYSTEM_TENANT_ID),
+  );
+
+  type ConfigRow = {
+    id: string;
+    key: string;
+    value: string | null;
+    tenantId: string;
+    version: number;
+  };
+
+  let alreadyCurrent = 0;
+  const targetVersion = provider.currentVersion();
+
+  type BucketedRow = { tenantId: TenantId; row: ConfigRow };
+
+  // ponytail: one full candidate scan — config rows are operator-scale
+  // (tenants × encrypted keys), cursor pagination when that ever changes.
+  // Bucketed by tenant so each row keeps its bucket's tenant attached
+  // (assertRowsTenant below re-checks that against the row's own field
+  // right before the write) and the shared loop's deadline/signal/failure
+  // checks still run between chunks, not only once.
+  let buckets: Map<TenantId, ConfigRow[]> | undefined;
+  async function loadBuckets(): Promise<Map<TenantId, ConfigRow[]>> {
+    if (buckets) return buckets;
+    const grouped = new Map<TenantId, ConfigRow[]>();
+    if (encryptedKeys.length > 0) {
+      const scanned = await scanDb
+        .acknowledgeCrossTenant("system-wide key rotation")
+        .selectMany<ConfigRow>(configValuesTable, { key: { in: encryptedKeys } });
+      for (const row of scanned) {
+        const tenantId = row.tenantId as TenantId; // @cast-boundary db-row
+        const bucket = grouped.get(tenantId);
+        if (bucket) bucket.push(row);
+        else grouped.set(tenantId, [row]);
+      }
+    }
+    buckets = grouped;
+    return buckets;
+  }
+
+  async function nextBatch(): Promise<readonly BucketedRow[]> {
+    const grouped = await loadBuckets();
+    for (const [tenantId, rows] of grouped) {
+      if (rows.length === 0) {
+        grouped.delete(tenantId);
+        continue;
+      }
+      const slice = rows.splice(0, SCAN_SLICE_SIZE);
+      if (rows.length === 0) grouped.delete(tenantId);
+      return slice.map((row) => ({ tenantId, row }));
+    }
+    return [];
+  }
+
+  async function migrateRow({
+    tenantId,
+    row,
+  }: BucketedRow): Promise<"migrated" | "skipped" | "failed"> {
+    if (row.value === null || row.value === undefined) return "skipped";
+    const classification = classifyStoredEnvelope(row.value, targetVersion);
+    if (classification === "current") {
+      alreadyCurrent++;
+      return "skipped";
+    }
+
+    if (classification === "unrecognized") {
+      // Not a current-cipher envelope (malformed JSON, or any pre-envelope
+      // format) — never a supported re-encrypt input, so fail loudly
+      // instead of relying on cipher.decrypt to reject it. Log only the
+      // row id, never the value (ciphertext-adjacent).
+      ctx.log?.warn?.(
+        `[config:reencrypt] row ${row.id} is not a current-cipher envelope, not re-encryptable`,
+      );
+      return "failed";
+    }
+
+    // Re-verify the row's own tenantId against the bucket it was scanned
+    // into, right before the write (framework#2072) — a mismatch here
+    // fails this row only (via onRowError below), it does not abort the
+    // whole job.
+    sdbFor(tenantId).assertRowsTenant([row], "tenantId");
+
+    const plaintext = await cipher.decrypt(row.value, { tenantId });
+    const reencrypted = await cipher.encrypt(plaintext, { tenantId });
+
+    const actor: SessionUser = { id: "system", tenantId, roles: SYSTEM_ROLES };
+    const result = await executor.update(
+      { id: row.id, version: row.version, changes: { value: reencrypted } },
+      actor,
+      tdbFor(tenantId),
+    );
+
+    // version_conflict == a concurrent config:set beat us; the row now
+    // holds a fresh envelope written by the set handler — already fine.
+    if (!result.isSuccess) {
+      if (result.error.code === "version_conflict") return "skipped";
+      ctx.log?.warn?.(`[config:reencrypt] executor rejected row ${row.id}`, {
+        code: result.error.code,
+      });
+      return "failed";
+    }
+    return "migrated";
+  }
+
+  const outcome = await runChunkedMigration<BucketedRow>({
+    nextBatch,
+    migrateRow,
+    maxFailures,
+    deadlineAt: deadline,
+    signal: ctx.signal,
+    onRowError: ({ row }, err) => {
+      ctx.log?.warn?.(`[config:reencrypt] failed to re-encrypt row ${row.id}`, { err });
+    },
+  });
+
+  const result: ReencryptJobResult = {
+    migrated: outcome.migrated,
+    failed: outcome.failed,
+    alreadyCurrent,
+    stoppedReason: outcome.stoppedReason,
+  };
+  ctx.log?.info?.(`[config:reencrypt] complete: ${JSON.stringify(result)}`);
+};

package/packages/bundled-features/src/config/handlers/reset.write.ts

@@ -0,0 +1,76 @@
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  ConfigScopes,
+  defineWriteHandler,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { requireSystemDb } from "../feature.js";
+import { configValueEntity, configValuesTable } from "../table.js";
+import { findConfigRow, prepareConfigWrite } from "../write-helpers.js";
+
+const scopeEnum = z.enum([ConfigScopes.system, ConfigScopes.tenant, ConfigScopes.user]);
+
+const executor = createEventStoreExecutor(configValuesTable, configValueEntity, {
+  entityName: "config-value",
+});
+
+export const resetWrite = defineWriteHandler({
+  name: "reset",
+  description:
+    "Removes the stored config value for one key at the given scope so the key falls back to the next cascade level, and permanently deletes the stored credential for secrets-backed keys.",
+  agent: { risk: "high" },
+  schema: z.object({
+    key: z.string(),
+    scope: scopeEnum.optional(),
+  }),
+  // Per-key access enforcement lives inside the handler via checkWriteAccess.
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call reset; prepareConfigWrite enforces the per-key " +
+        "write access rule before any value is touched",
+    },
+  },
+  handler: async (event, ctx) => {
+    const db = requireSystemDb(ctx, "config:write:reset", event.user.tenantId);
+
+    const prep = prepareConfigWrite({
+      registry: ctx.registry,
+      user: event.user,
+      key: event.payload.key,
+      scope: event.payload.scope,
+    });
+    if (!prep.ok) return prep.failure;
+    const { keyDef, scope, tenantId, userId } = prep;
+
+    // backing="secrets": clear the secret from the secrets store. delete() is
+    // idempotent (returns false if absent) — mirrors the config no-op contract.
+    if (keyDef.backing === "secrets") {
+      if (!ctx.secrets) {
+        throw new InternalError({
+          message:
+            `[config:write:reset] key "${event.payload.key}" declares backing="secrets" but ` +
+            `ctx.secrets is not wired — provide extraContext.secrets (and a MasterKeyProvider).`,
+        });
+      }
+      await ctx.secrets.delete(SYSTEM_TENANT_ID, event.payload.key, {
+        deletedBy: event.user.id,
+      });
+      return { isSuccess: true, data: { key: event.payload.key, scope } };
+    }
+
+    const existing = await findConfigRow(db, event.payload.key, tenantId, userId);
+
+    // No-op when there is nothing to reset. Pre-ES this path silently did
+    // nothing too — keep the contract intact so callers can reset
+    // idempotently without a 404 dance.
+    if (existing) {
+      const result = await executor.delete({ id: existing.id }, event.user, db);
+      if (!result.isSuccess) return result;
+    }
+
+    return { isSuccess: true, data: { key: event.payload.key, scope } };
+  },
+});

package/packages/bundled-features/src/config/handlers/schema.query.ts

@@ -0,0 +1,36 @@
+import { type ConfigKeyDefinition, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { hasConfigAccess } from "../write-helpers.js";
+
+export const schemaQuery = defineQueryHandler({
+  name: "schema",
+  description:
+    "Returns the definitions of all config keys the caller may read (scope, type, default, bounds, required flag) without any values; use it to discover which settings exist and how they may be set.",
+  schema: z.object({}),
+  // Per-key read access enforced via hasConfigAccess inside the handler.
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may call schema; hasConfigAccess filters the result to " +
+        "only the config key definitions the caller's roles may read",
+    },
+  },
+  rateLimit: {
+    disabled: true,
+    reason:
+      "self-scoped read of the caller's own readable config schema, hit on every page load; " +
+      "per-tenant bucket would throttle the whole tenant, L1 IP limit still applies",
+  },
+  handler: async (query, ctx) => {
+    const registry = ctx.registry;
+    const allKeys = registry.getAllConfigKeys();
+    const result: Record<string, ConfigKeyDefinition> = {};
+
+    for (const [qualifiedKey, keyDef] of allKeys) {
+      if (!hasConfigAccess(keyDef.access.read, query.user.roles)) continue;
+      result[qualifiedKey] = keyDef;
+    }
+
+    return result;
+  },
+});