cadrumo.adapters.persistence.storage.storage_path_definitions module

Filesystem and blob storage-hierarchy path contracts.

Split out of secure_object_namespaces.py along the seam that module’s own docstring already named: the SQL secure-object namespace keys are a different concern – logical database keys, not filesystem paths – and keep their own declarations there. Everything here is the other half: the per-bucket and per-keystore layout names (read from the one core storage taxonomy) and the StoragePathDefinition contracts for the on-disk hierarchy, including the parameterised fan-out SHAPES (a content-hash prefix, an outbound namespace, a per-run id) that cannot be enumerable StorageCategory members.

STORAGE_PATH_DEFINITIONS is consumed by namespace_registry.STORAGE_NAMESPACE_REGISTRY, which combines it with the SQL namespace definitions into one StorageHierarchyRegistry. Nothing here reaches back into namespace_registry.py, so there is no cycle.

BUCKET_DATABASE_FILENAME

Relative to the bucket root, not to db/ – this is the nested file, the sibling constant above is the directory that holds it.

PROFILE_SESSION_RETIREMENT_FILENAME

The crash-window sidecar for an interrupted session-key swap. Its location is derived from the receipt above at the call site, which is why the name is declared once in the taxonomy and read here rather than typed at the writer.

The three owner directories below the hold-evidence root, each the home of one persisted format. Declared as whole taxonomy subpaths (<root>-relative, two components) rather than as bare leaf names, so the grammars below spell exactly what the taxonomy declares.

PROFILE_PASSWORD_ENVELOPE_FILENAME

Bucket-root-relative nested paths (custody/envelope.v1.json), not single components – so their definitions below omit segment, matching bucket_database_file’s treatment of the same shape.

CONFIG_RESET_JOURNAL_DIRNAME

Directory holding the application-owned config-reset journal. The application module owns the durable journal itself; the name is declared once in the core taxonomy (CONFIG_RESET_JOURNAL) and read here, so the on-disk hierarchy has one inventory rather than two agreeing constants.

RUNS_DIRNAME

The six names below back the parameterised fan-out grammars further down this module (run-trace, LLM usage/telemetry logs, the token acquisition lock, and the two cache families). Each was previously hand-typed straight into its grammar string even though the taxonomy already declares it, duplicating the name the same way the bucket/keystore literals above did before this module started reading them off storage_location too.

LLM_CACHE_SUBPATH

A two-component subpath (cache/<name>) – interpolated whole, not split, since the taxonomy declares the compound as one subpath rather than two nested categories.

class StoragePathDefinition(**data)[source]

Bases: BaseModel

Contract for one storage hierarchy path or logical marker.

Parameters:
key: str
kind: StoragePathKind
grammar: str
owner: str
segment: str | None
schema_version: int | None
anchor: StoragePathAnchor | None

Which directory grammar’s <root> token means.

Required for every <root>-anchored kind (FILE, DIRECTORY, BLOB_OBJECT) and forbidden for LOGICAL_SQL (a db:// logical path has no <root> token to anchor). The three blob-content entries declare StoragePathAnchor.BLOB_STORE_ROOT rather than STORAGE_ROOT; see StoragePathAnchor’s own docstring for what that distinction currently rests on (an open question, not a settled one) and for why both anchors are checked by the directory-agreement gate regardless.