cadrumo.core.config_state_root module

The platform user-data storage root.

The central settings facade (Settings) roots the encrypted profile store at cadrumo_local_storage_root, from which the token, log, secret, blob and audit roots derive. This module resolves that default, and resolves it to exactly one place: the platform user-data directory (%LOCALAPPDATA% on Windows, $XDG_DATA_HOME with the ~/.local/share fallback on Linux, ~/Library/Application Support on macOS).

It does NOT classify how the process was installed. Cadrumo is a tax-filing product; a repository is a development artefact with no runtime meaning, so production code never inspects the filesystem for a pyproject.toml or a .git marker. An earlier revision did exactly that and branched on the answer to choose between a checkout-local var/storage and the platform directory — which meant a source-layout guess decided where a taxpayer’s regulated financial state was written. Detection is gone; only the platform answer remains.

The dev loop is served by configuration, not by detection: a developer who wants the store inside their checkout sets CADRUMO_LOCAL_STORAGE_ROOT (the justfile does), and an explicit operator override wins over this default like any other setting.

Every input the resolution reads — the platform string, the environment mapping, and the home directory — is captured in the frozen StateRootInputs seam, so resolution is a pure function of its argument and testable without mutating the ambient process. default_storage_root() is the live entry point Settings binds as its cadrumo_local_storage_root default factory.

See also

Settings

Central settings aggregate whose storage-root default is resolved here.

StateRootInputs

Frozen seam that captures every environmental input used by resolution.

resolve_state_root()

Pure resolver that returns the effective storage root.

default_storage_root()

Live default factory bound into the settings model.

BUCKETS_DIRNAME

Bucket container directory name, read from the one core storage authority.

BUCKET_DB_DIRNAME

Per-bucket database directory name, read from the one core storage authority.

PRODUCT_DATABASE_FILENAME

Canonical SQLite filename, read from the one core storage authority.

FORMER_PRODUCT_DATABASE_FILENAME

Retired aeat database filename inspected only for refusal.

exception FormerProductStateError(message=None, *, context=None, translated_message=None)

Bases: CoreError

Raised when installed Cadrumo detects a retired aeat state root.

Detection is refusal-only. The resolver does not open, read, move, re-key, delete, or adopt anything below the retired aeat application directory.

Parameters:

• message (str | None)

• context (Mapping[str, object] | None)

• translated_message (str | None)

Return type:

None

code

refuse_former_product_database(storage_root, *, bucket_id=None)

Refuse a recognizable retired aeat database without opening it.

Only filesystem metadata is inspected. The retired database is never connected to, read, copied, moved, deleted, or adopted.

Return type:

None

Parameters:

• storage_root (Path)

• bucket_id (str | None)

class StateRootInputs(**data)

Bases: BaseModel

Injectable, frozen seam for state-root resolution.

Capturing every environmental input as an explicit field makes both platform_user_data_root() and resolve_state_root() pure functions of its argument, so a test constructs a deterministic platform context rather than mutating os.environ or patching sys.platform.

Parameters:

• platform (str)

• environ (dict[str, str])

• home (Path)

platform: str

environ: dict[str, str]

home: Path

class StateRootResolution(**data)

Bases: BaseModel

Typed outcome of resolving the storage state root.

Carries the platform user-data base and the effective storage_root that Settings defaults cadrumo_local_storage_root to. No run-mode or repository concept appears here: the product does not classify its own installation.

Parameters:

data (Any)

platform_user_data_root: Path

storage_root: Path

live_state_root_inputs()

Capture the running process’s state-root inputs.

Snapshots platform, a copy of os.environ, and the user’s home directory into a frozen StateRootInputs for resolve_state_root().

Return type:

StateRootInputs

platform_user_data_root(inputs)

Resolve the Cadrumo platform user-data directory for the given inputs.

Windows resolves under %LOCALAPPDATA% (~/AppData/Local when the variable is unset or not absolute); macOS under ~/Library/Application Support; every other platform under $XDG_DATA_HOME (~/.local/share when unset or not absolute). The canonical product application directory name is appended to the resolved base.

Return type:

Path

Parameters:

inputs (StateRootInputs)

resolve_state_root(inputs)

Resolve the effective storage state root.

Unconditional: the store always lands under the platform user-data directory. Cadrumo is a tax-filing product and is blind to how it was installed — it never inspects the filesystem for a pyproject.toml or a .git marker to decide where a taxpayer’s encrypted state belongs. A repository is a development artefact with no meaning at runtime, and branching on one put regulated financial data in a location chosen by a source-layout guess.

A developer who wants the store inside their checkout sets CADRUMO_LOCAL_STORAGE_ROOT (the justfile does this), which wins over this default like any other operator override. That keeps the dev loop working through the ordinary configuration channel instead of through product code that detects its own environment.

Return type:

StateRootResolution

Parameters:

inputs (StateRootInputs)

default_storage_root()

Return the cadrumo_local_storage_root default for the live process.

Bound as the Settings cadrumo_local_storage_root default factory. Always the platform user-data storage directory — the product does not classify its installation. A developer overrides it with CADRUMO_LOCAL_STORAGE_ROOT.

Return type:

Path