Skip to content
CommonLayer
Documentation menu
On this page

ADR-0038: Runtime settings are a closed, typed registry of policy values

Status: Accepted (WP-70a). Supersedes the free key/value store of WP-40. Implemented in crates/commonlayer-core/src/ports/settings.rs, crates/commonlayer-app/src/runtime_settings.rs and src/platform.rs.

Context

WP-40 built a validated, versioned and audited key/value store for runtime settings (platform_settings), but no domain read it, and the administration page let an administrator write arbitrary keys that changed nothing. Some policy values (funding thresholds, the reward approval limit, the scan-age bound) are legitimately decided by the platform's operators while it runs.

Decision

  • A fixed registry of known keys, each with a description, a type (integer with bounds, or severity) and a default taken from the configuration: funding.surplus_bps, funding.fully_funded_bps, funding.partially_funded_bps, funding.underfunded_notice_cycles, funding.reward_single_approval_max_minor, funding.min_infrastructure_bps, funding.refund_window_days, security.kev_minimum_severity, security.not_affected_confirmation_min_severity, security.max_scan_age_hours.
  • PUT /api/v1/admin/settings/{key} refuses unknown keys and invalid values (422) and checks cross-key rules (the funding thresholds must stay ordered). Writes use optimistic concurrency, are versioned and audited. GET /api/v1/admin/settings returns the registry with the value in force, the default, whether it is overridden and who changed it.
  • The consuming domains read through a RuntimeSettingsHandle with a 5-second cache, invalidated on write: funding (thresholds, reward limit, minimum infrastructure share, refund window), projects (coverage thresholds, notice cycles, scan age) and security (KEV minimum, confirmation threshold, scan age).
  • Only policy values are runtime settings. Decisions that move money or change trust (payment provider, payout mode, legal entity, keys) stay deployment configuration.

Consequences

  • An administrator can change these policies without a restart, within bounds, with a record of who changed what. Tests: hardening::runtime_settings_change_behaviour_and_are_audited, refresh::coverage_thresholds_follow_the_runtime_settings, confirmations::the_confirmation_threshold_follows_the_runtime_setting.
  • There is no delete: "set back to the default" in the portal stores the default value as an override (WP-70e).
  • settings.manage is never held by API tokens, so settings change only in an interactive session.
  • The development seed's completion marker (development.seed) is written through an internal method, not through this API.