Runtime path authority¶
YAMS resolves process paths once through yams::config::resolve_runtime_paths() and passes the resulting ResolvedRuntimePaths snapshot to daemon, client, CLI, MCP, and service code.
Precedence¶
| Path | Precedence (highest first) |
|---|---|
| Config file | explicit --config/typed override, existing YAMS_CONFIG_PATH compatibility override, YAMS_CONFIG, platform config default |
| Data directory | explicit --data-dir/typed override, TOML core.data_dir, compatible [daemon] data keys, YAMS_DATA_DIR or legacy YAMS_STORAGE, platform data default |
| Runtime directory | explicit typed override, XDG_RUNTIME_DIR/Windows runtime default, per-user temporary fallback |
| Daemon socket | explicit --socket/typed override, YAMS_DAEMON_SOCKET or compatibility YAMS_DAEMON_SOCKET_PATH, TOML daemon.socket_path, platform socket default |
| PID file | explicit --pid-file/typed override, TOML daemon.pid_file, platform PID default |
Every resolved field records its RuntimePathSource and source name. The snapshot also carries diagnostics for inactive lower-precedence conflicts.
Alias conflicts¶
Compatibility aliases remain supported. YAMS_CONFIG_PATH is a legacy test/daemon override: it is used only when it names an existing file, then YAMS_CONFIG remains the canonical environment path. Equal path aliases are accepted. Unequal aliases fail closed when they would decide the effective path:
YAMS_DATA_DIRversusYAMS_STORAGEYAMS_DAEMON_SOCKETversusYAMS_DAEMON_SOCKET_PATH
An explicit or configured data directory safely disambiguates conflicting data aliases; YAMS uses the higher-precedence value and emits a warning. An explicit socket similarly disambiguates socket aliases. This prevents daemon and client processes from silently selecting different corpora or sockets while preserving existing isolated fixtures that export equal aliases.
Platform defaults¶
Unix follows XDG config/data/runtime homes and then HOME; daemon socket and PID fallbacks retain per-user /tmp behavior, while root retains /var/run. Windows uses APPDATA, LOCALAPPDATA, and USERPROFILE fallbacks. Callers should not reconstruct these branches locally.