Module paths 

Typed XDG base-directory resolvers for lean-ctx (GH #408 / GL #602).

Historically every lean-ctx file joined onto a single lean_ctx_data_dir rooted at $XDG_CONFIG_HOME/lean-ctx, mixing config.toml with 30+ runtime data files (sessions, vectors, graphs, events, logs, caches). That violates the XDG Base Directory Spec and makes a read-only config sandbox impossible.

This module introduces one typed resolver per XDG category so call-sites can migrate to the correct base over the following phases (GL #603/#604/#606/#607).

Backward compatibility (single-dir mode)

Existing installs MUST NOT split silently. single_dir_override returns Some(dir) when LEAN_CTX_DATA_DIR is set or a legacy/mixed install with data exists; in that case every category resolves to that one directory — byte-for-byte today’s behavior. The real per-category split only applies to fresh installs (and, later, on-demand via lean-ctx doctor --fix).

data_dir() and the fresh-install flip

data_dir delegates to lean_ctx_data_dir. Config (config.toml + hooks) and the runtime STATE/CACHE files were migrated onto config_dir, state_dir and cache_dir (GL #603/#604) so that, since GL #606, the data resolver defaults fresh installs to $XDG_DATA_HOME/lean-ctx without scattering config or state into the data dir. Legacy and pre-split mixed installs keep resolving every category to their existing single directory.

Determinism (#498): every resolver is a pure function of environment + HOME; no timestamps, counters or randomness.

Functions

cache_dir

Cache directory — semantic cache, models, learned patterns. tmpfs-safe. Override: LEAN_CTX_CACHE_DIR; default $XDG_CACHE_HOME/lean-ctx.

config_dir

Config directory — config.toml, shell hooks, env.sh. RO-safe. Override: LEAN_CTX_CONFIG_DIR; default $XDG_CONFIG_HOME/lean-ctx.

data_dir

Data directory — sessions, vectors, graphs, knowledge, archives, memory.

runtime_dir

Runtime directory — daemon.pid, daemon.sock. $XDG_RUNTIME_DIR/lean-ctx.

state_dir

State directory — events, stats, logs, journals, ledgers, captured keys. Override: LEAN_CTX_STATE_DIR; default $XDG_STATE_HOME/lean-ctx.