@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/compliance-profiles/schema/profile-selection.ts

@@ -0,0 +1,53 @@
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createLongTextField,
+  createSelectField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Tenant-1-zu-1: Pro Tenant genau eine Profile-Wahl.
+//
+// Architektur-Entscheidung (2026-05-06): Profile-Selection lebt als
+// separate Entity im compliance-profiles-Feature, NICHT als config-key
+// im tenant-Feature. Begruendung:
+//   (a) override ist strukturiertes JSON, config-key-Pattern (timezone/
+//       locale) ist key-value-flach
+//   (b) Profile-Wechsel ist audit-relevant — Event-Store gibt das
+//       automatisch fuer Entity-Writes
+//   (c) Plan-Files in docs/plans/datenschutz/compliance-profiles.md
+//       nennen sie explizit als tenantComplianceProfile-Entity
+//
+// Wer in 6 Monaten zweifelt warum nicht config-key: siehe oben.
+//
+// override als JSON-String in longText: kein dedizierter jsonField-Typ
+// im Framework; embedded hat festes Schema, das hier dynamisch ist.
+// Zod-Validation beim set-profile-Handler stellt Schema-Konformitaet
+// sicher.
+export const tenantComplianceProfileEntity = createEntity({
+  table: "read_tenant_compliance_profiles",
+  fields: {
+    profileKey: createSelectField({
+      required: true,
+      options: ["eu-dsgvo", "swiss-dsg", "de-hr-dsgvo-hgb", "minimal-no-region"] as const,
+    }),
+    // override: JSON-String mit Partial-ComplianceProfile. NULL/leer
+    // bedeutet "Default-Profile, keine Override". Validiert beim
+    // set-profile-Handler via Zod.
+    override: createLongTextField({
+      personal: false,
+      reason: "is_business_data",
+    }),
+  },
+  indexes: [
+    // Pro Tenant nur EIN Profile-Datensatz. Boot-Validator-Comment in
+    // EntityIndexDef warnt vor single-column-tenantId-Index als redundant
+    // — UNIQUE-Constraint ist hier aber semantisch noetig (1:1-Relation)
+    // und nicht nur Performance-Hint, daher explizit deklariert.
+    { unique: true, columns: ["tenantId"] },
+  ],
+});
+
+export const tenantComplianceProfileTable = buildEntityTable(
+  "tenantComplianceProfile",
+  tenantComplianceProfileEntity,
+);

package/packages/bundled-features/src/compliance-profiles/seeding.ts

@@ -0,0 +1,101 @@
+// Test-Helper für compliance-profiles. Legt einen Profile-Eintrag direkt
+// über den Event-Store-Executor an — gleicher Pfad wie der echte
+// set-profile-Handler, aber ohne Zod-Schema-Engung (akzeptiert
+// minimal-no-region für Migration-Edge-Case-Tests) und ohne Access-
+// Check. Default ifExists="skip": nur fehlende Profile anlegen.
+//
+// Sprint 2 user-data-rights nutzt das fuer Test-Setup ("user kann
+// Daten exportieren mit profile X" — pro Test ein frischer Tenant +
+// Profile-Wahl in einem Helper-Call).
+//
+// Pattern matched seedTextBlock aus text-content.
+
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import type {
+  ComplianceProfileKey,
+  ComplianceProfileOverride,
+} from "@cosmicdrift/kumiko-framework/compliance";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import {
+  tenantComplianceProfileEntity,
+  tenantComplianceProfileTable,
+} from "./schema/profile-selection.js";
+
+const executor = createEventStoreExecutor(
+  tenantComplianceProfileTable,
+  tenantComplianceProfileEntity,
+  { entityName: "tenant-compliance-profile" },
+);
+
+export type SeedComplianceProfileOptions = {
+  readonly tenantId: TenantId;
+  readonly profileKey: ComplianceProfileKey;
+  readonly override?: ComplianceProfileOverride;
+  readonly by?: SessionUser;
+  readonly ifExists?: SeedIfExists;
+};
+
+export async function seedComplianceProfile(
+  db: DbConnection,
+  opts: SeedComplianceProfileOptions,
+): Promise<{ id: string }> {
+  // user.tenantId muss === opts.tenantId sein damit Event-Store-Stream
+  // + Projection im selben Tenant-Bucket landen (Memory:
+  // feedback_event_store_tenant_consistency).
+  const by = opts.by ?? { ...TestUsers.systemAdmin, tenantId: opts.tenantId };
+  const tdb = createTenantDb(db, opts.tenantId, "system");
+  const overrideJson = opts.override !== undefined ? JSON.stringify(opts.override) : null;
+
+  const existing = (await fetchOne(db, tenantComplianceProfileTable, {
+    tenantId: opts.tenantId,
+  })) as { id: string; version: number } | null; // @cast-boundary db-runner
+
+  return runEventStoreSeed({
+    existing,
+    ifExists: opts.ifExists,
+    create: async () => {
+      const result = await executor.create(
+        {
+          profileKey: opts.profileKey,
+          override: overrideJson,
+          tenantId: opts.tenantId,
+        },
+        by,
+        tdb,
+      );
+      if (!result.isSuccess) {
+        throw new Error(`seedComplianceProfile create failed: ${JSON.stringify(result)}`);
+      }
+      // @cast-boundary db-row: executor.create result.data ist die
+      // inserted Projection-Row (Record<string, unknown>); id ist nach
+      // INSERT garantiert (Runtime-Check direkt darunter).
+      const data = result.data as { id?: string };
+      if (data.id === undefined) {
+        throw new Error("seedComplianceProfile: executor.create did not return an id");
+      }
+      return { id: data.id };
+    },
+    update: async (row) => {
+      const result = await executor.update(
+        {
+          id: row.id,
+          version: row.version,
+          changes: { profileKey: opts.profileKey, override: overrideJson },
+        },
+        by,
+        tdb,
+      );
+      if (!result.isSuccess) {
+        throw new Error(`seedComplianceProfile update failed: ${JSON.stringify(result)}`);
+      }
+      return { id: row.id };
+    },
+  });
+}

package/packages/bundled-features/src/compliance-profiles/web/client-plugin.tsx

@@ -0,0 +1,25 @@
+// @runtime client
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import {
+  COMPLIANCE_PROFILE_CATALOG_EXTENSION_NAME,
+  COMPLIANCE_PROFILES_FEATURE,
+} from "../constants.js";
+import { ComplianceProfileCatalog } from "./compliance-profile-catalog.js";
+import { defaultTranslations } from "./i18n.js";
+
+export type ComplianceProfilesClientOptions = {
+  readonly translations?: TranslationsByLocale;
+};
+
+export function complianceProfilesClient(
+  options?: ComplianceProfilesClientOptions,
+): ClientFeatureDefinition {
+  return {
+    name: COMPLIANCE_PROFILES_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+    extensionSectionComponents: {
+      [COMPLIANCE_PROFILE_CATALOG_EXTENSION_NAME]: ComplianceProfileCatalog,
+    },
+  };
+}

package/packages/bundled-features/src/compliance-profiles/web/compliance-profile-catalog.tsx

@@ -0,0 +1,55 @@
+// @runtime client
+// Extension-section component for the profile-picker actionForm's catalog
+// block — read-only list of the selectable compliance profiles (region +
+// supervisory authority). The select field above owns the actual choice;
+// this is reference material for the tenant admin.
+import {
+  type ExtensionSectionProps,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { ComplianceProfileQueries } from "../constants.js";
+
+type ProfileSummary = {
+  readonly key: string;
+  readonly region: string;
+  readonly label: string;
+  readonly authorityContact: string;
+};
+
+type ListProfilesResponse = {
+  readonly profiles: readonly ProfileSummary[];
+};
+
+export function ComplianceProfileCatalog(_props: ExtensionSectionProps): ReactNode {
+  const { Banner, Text } = usePrimitives();
+  const t = useTranslation();
+  const query = useQuery<ListProfilesResponse>(ComplianceProfileQueries.listProfiles, {});
+
+  if (query.loading && query.data === null) {
+    return (
+      <Banner variant="loading" testId="compliance-profile-catalog-loading">
+        <Text>{t("compliance.profile.catalog.loading")}</Text>
+      </Banner>
+    );
+  }
+  if (query.error) {
+    return (
+      <Banner variant="error" testId="compliance-profile-catalog-error">
+        <Text>{t(query.error.i18nKey, query.error.i18nParams)}</Text>
+      </Banner>
+    );
+  }
+
+  return (
+    <ul className="flex flex-col gap-2 text-sm" data-testid="compliance-profile-catalog">
+      {(query.data?.profiles ?? []).map((profile) => (
+        <li key={profile.key} data-profile-key={profile.key}>
+          <strong>{profile.label}</strong> — {profile.region} — {profile.authorityContact}
+        </li>
+      ))}
+    </ul>
+  );
+}

package/packages/bundled-features/src/compliance-profiles/web/i18n.ts

@@ -0,0 +1,9 @@
+// @runtime client
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  en: {
+    "compliance.profile.catalog.loading": "Loading compliance profiles…",
+    "compliance-profiles:nav.profilePicker": "Compliance",
+  },
+};

package/packages/bundled-features/src/compliance-profiles/web/index.ts

@@ -0,0 +1,6 @@
+// @runtime client
+export {
+  type ComplianceProfilesClientOptions,
+  complianceProfilesClient,
+} from "./client-plugin.js";
+export { ComplianceProfileCatalog } from "./compliance-profile-catalog.js";

package/packages/bundled-features/src/compliance-profiles-ops/handlers/tenants-missing-profile.query.ts

@@ -0,0 +1,56 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { defineQueryHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { tenantComplianceProfileTable } from "../../compliance-profiles/index.js";
+import { tenantTable } from "../../tenant/index.js";
+
+// SystemAdmin platform-wide counterpart to needs-profile (#2089).
+//
+// #2084 stopped needs-profile from nagging a TenantAdmin who can no longer
+// reach a picker narrowed to access.systemAdmin — correct, but it left no
+// one else able to notice: needs-profile stays TenantAdmin-only on purpose
+// (widening its call-access was explicitly rejected in #2084), so a
+// SystemAdmin who owns the platform-only picker has no way to see which
+// tenants still run on minimal-no-region. This query fills that gap
+// instead of touching needs-profile: every enabled tenant that has no row
+// in tenantComplianceProfile at all, tenant-wide rather than for the
+// caller's own tenant.
+export const tenantsMissingProfileQuery = defineQueryHandler({
+  name: "tenants-missing-profile",
+  schema: z.object({}),
+  access: { roles: [ROLES.SystemAdmin] },
+  description:
+    "Lists every enabled tenant that has never selected a compliance profile, for the platform operator sweeping the whole installation; needs-profile answers the same question but only for the caller's own tenant.",
+  handler: async (_query, ctx): Promise<TenantsMissingProfileResponse> => {
+    if (!ctx.systemDb) {
+      throw new InternalError({
+        message:
+          "[compliance-profiles-ops] tenants-missing-profile requires ctx.systemDb — the " +
+          "compliance-profiles-ops feature must stay r.systemScope() (see feature.ts).",
+      });
+    }
+    const db = ctx.systemDb.acknowledgeCrossTenant(
+      "platform operator scans every tenant for a missing compliance-profile selection",
+    );
+
+    const tenants = await db.selectMany<{ id: TenantId; name: string }>(tenantTable, {
+      isEnabled: true,
+    });
+    const profileRows = await db.selectMany<{ tenantId: TenantId }>(
+      tenantComplianceProfileTable,
+      {},
+    );
+    const tenantIdsWithProfile = new Set(profileRows.map((row) => row.tenantId));
+
+    return {
+      tenants: tenants
+        .filter((tenant) => !tenantIdsWithProfile.has(tenant.id))
+        .map((tenant) => ({ id: tenant.id, name: tenant.name })),
+    };
+  },
+});
+
+interface TenantsMissingProfileResponse {
+  readonly tenants: readonly { readonly id: TenantId; readonly name: string }[];
+}

package/packages/bundled-features/src/compliance-profiles-ops/index.ts

@@ -0,0 +1,34 @@
+// compliance-profiles-ops — platform-wide SystemAdmin visibility into
+// tenants missing a compliance-profile selection (#2089).
+//
+// needs-profile (compliance-profiles) tells a TenantAdmin they must pick a
+// profile, but stays TenantAdmin-only by design (#2084) — a SystemAdmin who
+// owns a picker narrowed to access.systemAdmin has no query at all. Kept as
+// a separate feature (mirrors folders-user-data/notes-history-user-data)
+// rather than folded into compliance-profiles: this is the one genuinely
+// cross-tenant capability in the picker's orbit, and it alone needs
+// r.systemScope() + a hard r.requires("tenant") — apps that only want the
+// per-tenant picker (the vast majority) stay unaffected.
+
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { tenantsMissingProfileQuery } from "./handlers/tenants-missing-profile.query.js";
+
+export const complianceProfilesOpsFeature = defineFeature("compliance-profiles-ops", (r) => {
+  r.describe(
+    "Platform-wide SystemAdmin counterpart to `compliance-profiles`' `needs-profile` query (#2089): `tenants-missing-profile` lists every enabled tenant with no row in `tenantComplianceProfile` at all, tenant-wide instead of scoped to the caller's own tenant. Mount alongside `compliance-profiles` and `tenant` when an operator UI needs to see which tenants still silently run on `minimal-no-region`.",
+  );
+  r.uiHints({
+    displayLabel: "Compliance Profiles · Operator Visibility",
+    category: "compliance",
+    recommended: false,
+  });
+  r.systemScope();
+  r.requires("compliance-profiles");
+  r.requires("tenant");
+
+  const queries = {
+    tenantsMissingProfile: r.queryHandler(tenantsMissingProfileQuery),
+  };
+
+  return { queries };
+});

package/packages/bundled-features/src/config/changes.json

@@ -0,0 +1,35 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "config keys can declare an async write validator that rejects with a KumikoError",
+    "detail": "Config key definitions accept a new async `validate(value, ctx)` function. `config:write:set` runs it after the type, bounds and pattern checks and before the value is stored, for every scope and backing. A validator rejects the write by throwing a `KumikoError`, for example an `UnprocessableError`. The feature manifest reports `validated` per key.",
+    "migration": "No action needed: keys without `validate` behave as before."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "config:write:set masks the echoed value for encrypted-at-rest keys; validation errors no longer include the value",
+    "migration": "A caller that reads `data.value` from a `config:write:set` result for a key with `encrypted: true` or `backing: \"secrets\"` now gets the mask. Use the value it sent instead. Tests that match the `value` param of a validation error on such a key need to drop that expectation."
+  },
+  {
+    "version": "0.326.0",
+    "type": "breaking",
+    "title": "Extension-selector settings render as one tenant screen",
+    "detail": "BREAKING: an extension-selector key now renders as a select of the mounted plugin ids, and\n`config:write:set` rejects every value except a mounted plugin id or \"\" with 422\n`config.errors.unknownExtensionPlugin`.\n\nThe owner's tenant screen `<owner>-tenant` is now a dashboard; its former configEdit moved\nto `<owner>-tenant-selection`. Plugin features under a masked selector lose their tenant nav\nentry: their `<plugin>-tenant` screen stays as a nav-less embedded panel (a direct deep link\nstill resolves), and their secrets move from the global `secrets` screen into\n`<plugin>-tenant-secrets` panels. A plugin feature registered under more than one selector\nregistration keeps the previous behaviour.\n\nGenerated hub screens need the new key `config.settings.extensionSelectorHint` (shipped in\nthe config and secrets bundles, en/de/es).",
+    "migration": "Links, tests or screenshots that open `<plugin>-tenant` through the nav or expect a configEdit\nat `<owner>-tenant` should open `<owner>-tenant` (now the dashboard) and look for the plugin\npanels there. Tenant rows or scripts that write a selector value naming no mounted plugin must\nwrite a mounted plugin id or \"\" instead. No new translation keys are required from apps."
+  },
+  {
+    "version": "0.271.0",
+    "type": "improvement",
+    "title": "systemScope handlers get a default per-tenant+handler rate limit; the four read queries opt out (fw#2861).",
+    "detail": "`config` mounts under `r.systemScope()`, so `config:write:set`/`config:write:reset` without their own `rateLimit` now default to `{ per: \"tenant+handler\", limit: 600, windowSeconds: 60 }` once an app has a `RateLimitResolver` configured (framework change, see kumiko-framework changes.json 0.271.0). `config:query:cascade`, `config:query:values`, `config:query:schema` and `config:query:readiness` declare `rateLimit: { disabled: true, reason: \"...\" }` — each is a self-scoped read of the caller's own readable config, hit on every page load, and a per-tenant bucket would throttle the whole tenant's page loads instead of just that one handler's traffic."
+  },
+  {
+    "version": "0.165.0",
+    "type": "breaking",
+    "title": "Reencrypt job: removed legacy-decrypt path",
+    "detail": "The old single-key format (CONFIG_ENCRYPTION_KEY) is no longer supported. The reencrypt job now classifies rows as rotate/current/unrecognized — unreadable rows are counted as failed instead of silently attempted.",
+    "migration": "If any config values still exist in the old single-key format, re-encrypt them with the current envelope format before upgrading. The job will now throw an error instead of attempting migration."
+  }
+]

package/packages/bundled-features/src/config/constants.ts

@@ -0,0 +1,30 @@
+// @runtime client
+// Pure name/string constants — browser-safe, importable from web client code
+// (configClient() pins its feature name to CONFIG_FEATURE).
+export const CONFIG_FEATURE = "config" as const;
+
+// Qualified write handler names (QN format: scope:type:name)
+export const ConfigHandlers = {
+  set: "config:write:set",
+  reset: "config:write:reset",
+} as const;
+
+// Qualified query handler names (QN format: scope:type:name)
+export const ConfigQueries = {
+  cascade: "config:query:cascade",
+  values: "config:query:values",
+  schema: "config:query:schema",
+  readiness: "config:query:readiness",
+  selectedExtensions: "config:query:config-value:selected-extensions",
+} as const;
+
+// Error codes
+export const ConfigErrors = {
+  unknownKey: "unknown_config_key",
+  systemOnly: "config_key_is_system_only",
+  invalidScope: "invalid_scope",
+  systemScopeWriteDenied: "system_scope_write_denied",
+  typeError: "type_error",
+  invalidOption: "invalid_option",
+  unknownExtensionPlugin: "unknown_extension_plugin",
+} as const;

package/packages/bundled-features/src/config/db/queries/resolver.ts

@@ -0,0 +1,51 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { configValuesTable } from "../../table.js";
+
+export type ConfigRow = {
+  readonly id: string;
+  readonly key: string;
+  readonly value: string | null;
+  readonly tenantId: TenantId;
+  readonly userId: string | null;
+};
+
+// Method-form so a tenant-mode TenantDb stays filtered. Two parallel selects
+// (disjoint via userId IS NULL) instead of one OR query: the buckets don't share
+// a snapshot, so a concurrent config write can mix old scope and new user values.
+export async function selectConfigRowsForScope(
+  db: DbRunner | TenantDb,
+  systemTenantId: TenantId,
+  tenantId: TenantId,
+  userId: string,
+): Promise<readonly ConfigRow[]> {
+  const [scopeRows, userRows] = await Promise.all([
+    selectMany<ConfigRow>(db, configValuesTable, {
+      tenantId: [systemTenantId, tenantId],
+      userId: null,
+    }),
+    selectMany<ConfigRow>(db, configValuesTable, { tenantId, userId }),
+  ]);
+  return [...scopeRows, ...userRows];
+}
+
+export async function selectConfigRowsForKeys(
+  db: DbRunner | TenantDb,
+  keys: readonly string[],
+  systemTenantId: TenantId,
+  tenantId: TenantId,
+  userId: string,
+): Promise<readonly ConfigRow[]> {
+  if (keys.length === 0) return [];
+  const keyFilter = { in: [...keys] };
+  const [scopeRows, userRows] = await Promise.all([
+    selectMany<ConfigRow>(db, configValuesTable, {
+      key: keyFilter,
+      tenantId: [systemTenantId, tenantId],
+      userId: null,
+    }),
+    selectMany<ConfigRow>(db, configValuesTable, { key: keyFilter, tenantId, userId }),
+  ]);
+  return [...scopeRows, ...userRows];
+}

package/packages/bundled-features/src/config/feature.ts

@@ -0,0 +1,169 @@
+import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type ConfigAccessor,
+  type ConfigAccessorFactory,
+  type ConfigKeyHandle,
+  type ConfigKeyType,
+  type ConfigSecretsReader,
+  type ConfigValue,
+  defineFeature,
+  type FeatureDefinition,
+  type HandlerContext,
+  type Registry,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import { cascadeQuery } from "./handlers/cascade.query.js";
+import { readinessQuery } from "./handlers/readiness.query.js";
+import { reencryptJob } from "./handlers/reencrypt.job.js";
+import { resetWrite } from "./handlers/reset.write.js";
+import { schemaQuery } from "./handlers/schema.query.js";
+import { selectedExtensionsQuery } from "./handlers/selected-extensions.query.js";
+import { setWrite } from "./handlers/set.write.js";
+import { valuesQuery } from "./handlers/values.query.js";
+import { CONFIG_FEATURE_I18N } from "./i18n.js";
+import type { ConfigResolver } from "./resolver.js";
+import { configValueEntity } from "./table.js";
+
+export type ConfigContext = { readonly config: ConfigAccessor };
+
+export function createConfigFeature(): FeatureDefinition {
+  return defineFeature("config", (r) => {
+    r.describe(
+      "Stores per-tenant (and optionally per-user) configuration values with a multi-layer cascade: user-row \u2192 tenant-row \u2192 system-row \u2192 app-override (deploy-time `AppConfigOverrides`) \u2192 computed \u2192 feature default. Access a value in handlers via `ctx.config(handle)`, declare keys with `r.config({ keys: { ... } })` inside a feature's registry callback, and optionally mark them `encrypted: true` to route storage through the envelope cipher (versioned master key). Use this feature whenever a tenant admin needs to customise behaviour at runtime without a code deploy.",
+    );
+    r.uiHints({
+      displayLabel: "Tenant Config Store",
+      category: "infrastructure",
+      recommended: true,
+    });
+    r.systemScope();
+
+    // One aggregate stream per (key, scope) pair — the executor handles the
+    // lifecycle events `configValue.created / .updated / .deleted` plus the
+    // projection write in one TX. Subscribers that need config-change
+    // semantics listen to those auto-events via r.multiStreamProjection
+    // (see docs/plans/architecture/event-sourcing-pivot.md §4.7).
+    r.entity("config-value", configValueEntity);
+
+    const handlers = {
+      set: r.writeHandler(setWrite),
+      reset: r.writeHandler(resetWrite),
+    };
+
+    const queries = {
+      cascade: r.queryHandler(cascadeQuery),
+      values: r.queryHandler(valuesQuery),
+      schema: r.queryHandler(schemaQuery),
+      readiness: r.queryHandler(readinessQuery),
+      selectedExtensions: r.queryHandler(selectedExtensionsQuery),
+    };
+
+    // KEK-rotation for encrypted values. Manual trigger — ops runs it once
+    // after adding a new master key version.
+    r.job("reencrypt", { trigger: { manual: true } }, reencryptJob);
+
+    r.translations({ keys: CONFIG_FEATURE_I18N });
+
+    return { handlers, queries };
+  });
+}
+
+export function createConfigAccessor(
+  registry: Registry,
+  resolver: ConfigResolver,
+  tenantId: TenantId,
+  userId: string,
+  db: DbConnection | TenantDb,
+  secrets?: ConfigSecretsReader,
+): ConfigAccessor {
+  async function configAccessor(
+    qualifiedKey: string,
+  ): Promise<string | number | boolean | undefined>;
+  async function configAccessor<T extends ConfigKeyType>(
+    handle: ConfigKeyHandle<T>,
+  ): Promise<ConfigValue<T> | undefined>;
+  async function configAccessor(
+    keyOrHandle: string | ConfigKeyHandle<ConfigKeyType>,
+  ): Promise<string | number | boolean | undefined> {
+    const qualifiedKey = typeof keyOrHandle === "string" ? keyOrHandle : keyOrHandle.name;
+    const keyDef = registry.getConfigKey(qualifiedKey);
+    if (!keyDef) return undefined;
+    return resolver.get(qualifiedKey, keyDef, tenantId, userId, db, secrets);
+  }
+  return configAccessor;
+}
+
+// Pass to the test-stack / server-boot as `_configAccessorFactory` —
+// `buildHandlerContext` mints a per-user `ctx.config` from this.
+export function createConfigAccessorFactory(
+  registry: Registry,
+  resolver: ConfigResolver,
+): ConfigAccessorFactory {
+  return ({ user, db, secrets }) =>
+    createConfigAccessor(registry, resolver, user.tenantId, user.id, db, secrets);
+}
+
+// Single point of truth for "this handler needs the resolver". Throws a
+// proper InternalError (with i18n) instead of bare Error, and points the
+// caller at the boot wiring step that's missing — so a future debug
+// session reads "config feature not wired into AppContext" instead of a
+// generic "configResolver missing".
+export function requireConfigResolver(ctx: HandlerContext, handlerName: string): ConfigResolver {
+  if (!ctx.configResolver) {
+    throw new InternalError({
+      message:
+        `[${handlerName}] ctx.configResolver missing — pass createConfigAccessorFactory's ` +
+        `output via extraContext._configAccessorFactory and the resolver via ` +
+        `extraContext.configResolver at boot.`,
+    });
+  }
+  return ctx.configResolver;
+}
+
+// Config declares r.systemScope() (raw ctx.db is unfiltered across tenants
+// in that mode), so config's own query handlers must go through ctx.systemDb's
+// explicit self-check instead of touching ctx.db directly. Only valid for
+// handlers dispatched as config:query:* — those always run under config's
+// own system-scoped context, so ctx.systemDb is never actually missing here;
+// the throw documents that invariant instead of silently degrading.
+// buildProviderSelectionGate / collectMissingRequiredConfig (readiness.query.ts)
+// are shared with the separate, plain tenant-scoped readiness feature, so they
+// take the already-scoped db as an explicit parameter instead of resolving it
+// themselves — each call site (config's own handler here, readiness's
+// status.query.ts) makes its own scope decision instead of this function
+// guessing from ctx.systemDb's presence.
+export function requireSystemDb(
+  ctx: HandlerContext,
+  handlerName: string,
+  tenantId: TenantId,
+): TenantDb {
+  if (!ctx.systemDb) {
+    throw new InternalError({
+      message:
+        `[${handlerName}] ctx.systemDb missing — only present for r.systemScope() handlers; ` +
+        `the config feature declares r.systemScope() in feature.ts, so this points at a ` +
+        `pipeline wiring bug rather than a missing feature declaration.`,
+    });
+  }
+  return ctx.systemDb.assertTenantMatch(tenantId);
+}
+
+// Mirror of requireConfigResolver for the encryption round-trip side.
+// Only keys declared `encrypted: true` need this — the setter calls it
+// lazily so apps that never wire encryption still boot (and only crash
+// if a handler tries to write an encrypted key without the provider in
+// place, pointing at the exact wiring gap).
+export function requireConfigEncryption(ctx: HandlerContext, handlerName: string): EnvelopeCipher {
+  if (!ctx.configEncryption) {
+    throw new InternalError({
+      message:
+        `[${handlerName}] ctx.configEncryption missing — at least one config key declares ` +
+        `encrypted: true, so the boot wiring must pass an EnvelopeCipher via ` +
+        `extraContext.configEncryption (run{Prod,Dev}App wire it automatically from ` +
+        `KUMIKO_SECRETS_MASTER_KEY_V<n>; same instance the resolver was built with).`,
+    });
+  }
+  return ctx.configEncryption;
+}