cadrumo.core.storage_taxonomy_locations module

Compiled storage-taxonomy data and its resolution accessors.

Split out of _storage_taxonomy.py along the seam that module now names in its own docstring: the axis enums, StorageLocation, and the _location() factory are the TYPE layer – stable, small, imported everywhere. _ROOT_LOCATIONS / _BUCKET_LOCATIONS are the DATA – one entry per application-chosen location, and the fastest-growing part of the taxonomy by construction, since every new governed path adds a member here. Keeping them together pushed the combined module past its reviewed size band; this module is the data and resolver half, imported directly by the consumers that need those canonical definitions.

STORAGE_TAXONOMY: Final[dict[StorageCategory, StorageLocation]]

The single declaration of every application-chosen on-disk location.

Total over StorageCategory: a member without a declaration would be a name the application can pass around but never resolve.

STORAGE_FIELD_CATEGORIES: Final[dict[str, StorageCategory]]

Reverse index from a flat settings field name to the member that governs it.

ROOT_DERIVED_STORAGE_LOCATIONS: Final[tuple[StorageLocation, ...]]

Members whose settings default is computed from the storage root, in declaration order.

Settings validation and the override-rebuild loop iterate this rather than a parallel table, so a member cannot be declared here and silently left underived.

ROOT_DERIVED_STORAGE_FIELDS: Final[tuple[str, ...]]

Settings fields whose default is computed from the storage root, in declaration order.

FINGERPRINT_EXCLUDED_STORAGE_FIELDS: Final[frozenset[str]]

Settings fields whose contents are kept out of the data-root drift digest.

Compared by field NAME wherever it is checked, never by resolved-path cardinality: two fields may legitimately be overridden onto one directory, which shrinks a resolved-path set while exactly the same fields are consulted.

storage_location(category)[source]

Return the declaration for category.

Return type:

StorageLocation

Parameters:

category (StorageCategory)

storage_path(category, *, settings=None)[source]

Return the resolved absolute path of a root-scoped member.

The member’s settings field is the authority when it declares one and holds a value, so an explicit per-field operator override wins here exactly as it does everywhere else, and the isolation fixtures that place a category outside the root keep resolving to where they put it. A member with no field – the fixed bucket container, the active-profile pointer – resolves as the root joined with its declared subpath.

Parameters:

  • category (StorageCategory) – The member to resolve. Must be root-scoped.

  • settings (Settings | None) – Settings to resolve against. Defaults to the effective settings for the calling context.

Return type:

Path

Returns:

The absolute path this member occupies.

Raises:

CoreValidationError – When category is bucket- or keystore-scoped and therefore needs a bucket identifier to resolve.

bucket_scoped_storage_path(category, bucket_id, *, settings=None)[source]

Return the resolved absolute path of a bucket- or keystore-scoped member.

Bucket layout is fixed by policy, so this resolves through the declared subpaths rather than through any operator-facing setting: a keystore cannot be relocated out from under the bucket it unlocks.

Parameters:

  • category (StorageCategory) – The member to resolve. Must not be root-scoped.

  • bucket_id (str) – The bucket whose tree the member sits in.

  • settings (Settings | None) – Settings to resolve the bucket container against. Defaults to the effective settings for the calling context.

Return type:

Path

Returns:

The absolute path this member occupies within bucket_id’s tree.

Raises:

CoreValidationError – When category is root-scoped, or bucket_id is blank.

storage_tree_targets(settings, *, include_explicit=True, include_derived=True)[source]

Return every directory ensure_storage_tree() creates.

Derived from the declaration and from nothing else, so the materialiser cannot drift from the taxonomy by carrying a second list. A file-valued member contributes its parent and explicitly not its leaf – creating the leaf would put a directory exactly where a document must be written, and the failure would surface much later, at the write.

Members with no settings field are fixed layout the bucket lifecycle provisions per bucket, and members whose field is absent are opt-in locations the operator has not asked for; neither is materialised here. include_explicit and include_derived select settings named in, or absent from, Settings.model_fields_set. This lets callers distinguish application-owned defaults from operator-owned dependencies without maintaining a second taxonomy, including when both resolve to the same path.

Return type:

tuple[Path, ...]

Parameters: