{
  "uid": "cogitave.learn.configuration-management.the-configuration-model",
  "kind": "moduleUnit",
  "href": "/modules/configuration-management/the-configuration-model/",
  "title": "The configuration model",
  "summary": "",
  "type": null,
  "products": [],
  "roles": [],
  "levels": [],
  "subjects": [],
  "headings": [
    "1. The line: constant vs configuration vs secret",
    "2. The precedence chain",
    "3. Parsed once, typed, fail-closed"
  ],
  "source": "The [configuration standard](../../../../standards/docs/standards/configuration.md)\nbuilds up in three moves: classify every value, assemble config from ordered\nproviders, then parse it once into a value that cannot be invalid.\n\n## 1. The line: constant vs configuration vs secret\n\nThe first discipline is **classification**. Every value in the codebase is one of\nexactly three things, and the bucket decides how it is expressed.\n\n| Bucket | What it is | How it is expressed |\n| --- | --- | --- |\n| **Domain invariant** | A fact intrinsic to correctness, identical in every environment (`SECONDS_PER_DAY`, `HTTP_OK = 200`, a protocol-fixed frame size) | A **named** `const` in code - never a bare literal |\n| **Deployment parameter** | Anything likely to vary between deploys - URLs, pool sizes, timeouts, hostnames, limits, regions | The **typed config layer** |\n| **Secret** | A credential, key, or token | A **`SecretRef`** resolved at runtime - never a value in code or config |\n\nThe litmus test is 12-Factor's Factor III: *could the codebase be open-sourced at\nany moment without leaking a credential or pinning it to one environment?* If\nexposing the value leaks a secret or hard-binds an environment, it is **not** a\ncode constant.\n\n> [!NOTE]\n> A bare literal in business logic that is not `0`, `1`, or a self-evident unit is\n> a **review-blocking defect**. Even a config *default* is a named, documented\n> constant. This is enforced mechanically - `clippy` restriction lints in Rust,\n> `mnd` in Go, ESLint `no-magic-numbers` in TypeScript - not by reviewer goodwill.\n\n## 2. The precedence chain\n\nConfig is assembled from **ordered providers**, later overriding earlier. This\ncross-ecosystem chain is the Cogitave standard:\n\n```\nbuilt-in defaults\n  -> config.toml                 (committed base)\n  -> config.{env}.toml           (committed per-environment overlay)\n  -> COG_* environment variables (deploy-time + secret references)\n  -> command-line arguments      (explicit override)     [highest precedence]\n```\n\nOne prefix, granular keys. 12-Factor's explicit anti-pattern is grouping config\ninto in-code `dev`/`test`/`prod` bundles, which causes a \"combinatorial\nexplosion.\" The environment is selected by **which overlay file loads**\n(`config.{env}.toml`), never by branching logic in code. Environment variables\nare a **narrow override and secret-reference channel**, not the primary store -\nthey are global, untyped, and leak via logs and child processes.\n\n## 3. Parsed once, typed, fail-closed\n\nThis is the doctrinal core.\n\n- **One canonical JSON Schema per service is the source of truth**; the Rust, Go,\n  and TypeScript types are *generated* from it, so they never drift by hand.\n- **Parse, don't validate.** Read the raw files and env into a single **typed,\n  immutable `Config` value once, at the boundary, at startup.** After a successful\n  parse you hold a value that **cannot be invalid**, and downstream code never\n  re-checks it.\n- **Make illegal states unrepresentable** with enums and newtypes (`Port`, `Url`,\n  `NonEmptyString`), so impossible config will not parse.\n- **Fail-closed.** Invalid or missing-required config means the process **refuses\n  to start**, emitting a precise, **layer-attributed** error that names which\n  file, env var, or flag was wrong. Cert-grade means never running misconfigured.\n\nFinally, config is **config-as-code**: it lives in git, is reviewed like code, and\neach service exposes an effective-config surface with **per-key provenance** -\nwhich layer set each value - with secrets masked. That provenance is ready-made\nchange-management evidence.\n",
  "partOf": "cogitave.learn.configuration-management",
  "durationInMinutes": 7,
  "quiz": null
}