Module loader 

Static config-file loader (DESIGN.md §5.12; first slice of the TOML surface called out in the design doc’s “TOML covers static option overrides only” line).

Reads lattice.toml from the XDG config home (~/.config/lattice/lattice.toml on all Unix incl. macOS, honouring $XDG_CONFIG_HOME; see config_home) and .lattice/config.toml from the workspace root, in that precedence order. Project beats user; :set writes after startup beat both.

Design (read-only, walk-and-set)

The loader walks the parsed TOML table breadth-first. For each sub-table, it asks: does its dotted path match a registered structural prefix (e.g. completion.per-language)? If so, the table is recorded verbatim in LoadOutcome::structural and descent stops there – the caller (App, plugin host) owns the interpretation of structural sections. If not, descent continues and any scalar leaf becomes a parse_and_set_command("key=value") call against the supplied ConfigRegistry.

This keeps the loader policy-free for everything map-shaped: plugins (Phase 7), per-language overrides (Phase 4.2.g.5 (3b)), and any future structurally-typed config all flow through the same structural bucket.

Errors are warnings

Parse failures, unknown keys, and validation rejects all produce LoadMessages the caller surfaces in its message buffer. Nothing here panics or aborts startup – a bad config file is recoverable with an editor and a re-launch.

What this is NOT

• Hot reload. The loader runs once at startup; :reload-config is a future addition (will share the walk-and-set core).
• A writer. :customize post-1.0 is the round-trip surface; it’ll move to toml_edit for write-preserving edits.
• A keymap loader. Keymaps are a separate registry; their loader will compose with this one.

Structs

LoadMessage

One diagnostic from the loader. Caller decides how to surface it (echo, message buffer, log line); the loader stays IO-agnostic.

LoadOutcome

Outcome of loading one or more TOML files. The caller drains messages into its echo / message buffer and walks structural to dispatch sub-tables to their owners.

Enums

LoadMessageLevel

Severity of a LoadMessage.

Functions

cache_home

The cache root, <config-home>/lattice/cache/.

cache_home_from

Pure resolver behind cache_home.

config_home

The XDG config base directory for lattice’s config root.

default_user_config_path

Default user config path: <config_home>/lattice/lattice.toml, i.e. ~/.config/lattice/lattice.toml (honouring $XDG_CONFIG_HOME). See config_home for the cross-platform resolution. None when no config home resolves (no $XDG_CONFIG_HOME override and no $HOME).

load_default_paths

Load both default paths in standard precedence order: user first, then project. Missing files are silent (no message). structural_prefixes lists dotted prefixes the caller wants to handle itself (e.g. &["completion.per-language", "plugin"]).

load_file

Load a single TOML file, applying scalar leaves to registry and bucketing structural sub-tables. The path is recorded in every emitted message so the caller can surface path:reason-style diagnostics.

lookup_dotted_path

Walk a TOML table by a dotted path, returning the value at the leaf or None if any segment is missing or steps through a non-table. Used by workspace/configuration to look up server-namespaced keys (e.g. "rust-analyzer.cargo.features" walks tree["rust-analyzer"]["cargo"]["features"]).

migrate_path

Move old to new if old exists and new does not, returning whether anything moved. Works for a file or a directory.

project_config_path

Default project config path: <workspace_root>/.lattice/config.toml. Caller supplies workspace_root (typically the directory the editor was launched in, walked up to the first .git / .lattice/ marker if desired).