aeat.adapters.persistence.storage.bucket._layout module

Filesystem provisioning and path resolution for per-bucket directories.

The per-bucket on-disk model lives at <aeat-root>/buckets/<bucket-id>/ and carries exactly three subdirectories:

  • db/ relational state (SQLite database files).

  • blobs/ opaque artefact storage (sealed ciphertext blobs).

  • audit/ append-only audit-trail log files.

Provisioning is fail-closed: a re-attempt against an already-provisioned bucket id raises rather than silently masking a configuration error. The typed BucketPaths record carries each resolved subpath so callers never compose the layout themselves.

class BucketPaths(**data)[source]

Bases: BaseModel

Typed record carrying the resolved paths for one bucket directory.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • root (Path)

  • bucket_dir (Path)

  • db_dir (Path)

  • blobs_dir (Path)

  • audit_dir (Path)

bucket_id: BucketId
root: Path
bucket_dir: Path
db_dir: Path
blobs_dir: Path
audit_dir: Path
bucket_paths(root, bucket_id)[source]

Resolve the typed paths for <root>/buckets/<bucket_id>/ without IO.

Parameters:

  • root (Path) – AEAT root directory (the parent of buckets/).

  • bucket_id (str) – The bucket identifier; must be non-empty.

Return type:

BucketPaths

Returns:

A BucketPaths record carrying every resolved subpath.

Raises:

BucketValidationError – When bucket_id is empty or contains a path separator.

provision_bucket_directory(root, bucket_id)[source]

Materialise the <root>/buckets/<bucket_id>/{db,blobs,audit}/ tree.

Provisioning is fail-closed: if the bucket directory already exists, the function raises rather than reusing the partial state. The parent <root>/buckets/ directory is created lazily.

Parameters:

  • root (Path) – AEAT root directory (the parent of buckets/).

  • bucket_id (str) – The bucket identifier; must be non-empty.

Return type:

BucketPaths

Returns:

A BucketPaths record carrying every resolved subpath.