Skip to content

Configuration Subsystem

The Configuration Subsystem is a platform-level, cross-cutting subsystem that standardizes how SmrtHub components locate, read, validate, and persist configuration/state artifacts.

Canonical policy reference: README.Files/System/Policies/SmrtHub-Operational-Data-Policy-v1.0.README.md

Overview & responsibilities

  • Define and enforce canonical locations and naming for configuration/state artifacts (per Operational Data Policy).
  • Provide safe, deterministic persistence primitives (atomic writes, minimal backups, deterministic JSON formatting).
  • Ensure cross-runtime parity between C# and Python so components behave consistently.

Contracts and invariants

All SmrtHub components must follow these contracts:

  1. Canonical paths only
  2. Config/state artifacts live under %AppData%/SmrtHub/Config/<component-slug>/ (roaming) or %LocalAppData%/SmrtHub/Config/<component-slug>/ (local), per Operational Data Policy.

  3. Slugs are kebab-case (examples: trigger-manager, clipboard-monitor, python-core).

  4. Canonical file names

  5. Prefer the Operational Data Policy defaults (for example <slug>-config.json, <slug>-state.json).

  6. Do not invent new per-component naming patterns.

  7. Atomic persistence

  8. Writes must be atomic: no partial files should appear on disk.
  9. C# uses Smrt.Config.ConfigJson.AtomicWrite (or a component wrapper that calls into it).

  10. Python uses the canonical atomic JSON write helper used by python_core.

  11. Minimal backup policy

  12. Overwriting an existing file leaves a single adjacent .bak for quick recovery.

  13. No multi-file rotation for config/state artifacts.

  14. Deterministic JSON

  15. Persist UTF-8 JSON with stable key ordering to minimize diffs and support troubleshooting.

  16. When migrations matter, include a root schemaVersion and keep forward-migration behavior explicit.

  17. No secrets in config/state

  18. Tokens and secrets must not be stored in config/state JSON.
  19. Store secrets in the approved secret store (Windows Credential Manager via Smrt.Security) and persist only references/IDs.

Integration points

  • C#
  • Smrt.Config provides ConfigPathResolver and ConfigJson for path computation and JSON persistence.
  • Python
  • python_core uses its configuration path resolver and atomic persistence helpers to match the same Operational Data Policy conventions.

Configuration, paths, and operational data

  • The authoritative path rules, slugs, and filenames are defined in README.Files/System/Policies/SmrtHub-Operational-Data-Policy-v1.0.README.md.
  • Component READMEs should reference those rules rather than duplicating path tables.

Observability & diagnostics

  • Components must log configuration load/validation failures via the unified logging subsystem (Smrt.Logging in C#, python_core.utils.logger in Python).
  • Failures should be actionable: include which artifact failed (kind + component slug), which scope (roaming/local), and the failure mode (missing file, parse failure, schema mismatch, permissions).
  • Support Bundle tooling may collect configuration snapshots from canonical directories; do not write config outside canonical locations.

Security/privacy notes

  • Treat config/state as potentially sensitive operational metadata.
  • Enforce “no secrets in JSON” as a hard rule.
  • Ensure logs do not emit full config payloads unless redacted and explicitly required for diagnostics.

Testing & validation expectations

  • Validate path resolution produces the expected canonical directories and filenames.
  • Validate atomic write behavior under interruption and concurrent access (no partial files; .bak behavior correct).
  • Validate schema/version migration behavior where applicable.
  • Validate parity across C# and Python for the same component slug and artifact kinds.