aeat.adapters.outbound.storage._local module

Local-filesystem adapters.outbound.storage.StorageProvider implementation.

Stores objects under a configurable root directory. Each namespace is a subdirectory; each object is a single file named <hmac_prefix_8>--<label>.<ext>. Metadata (content_hash, byte_length, written_at, full HMAC, and label) lives in a sibling JSON sidecar so the listing API can return ProviderObjectMetadata without re-hashing the payload.

Bytes-in / bytes-out: encryption + classification stay above this layer. The provider treats every payload as opaque bytes and uses adapters.outbound.storage._integrity.verify_content_hash() to enforce the stored digest on read.

class LocalFileSystemProvider(root)

Bases: object

Bytes-in / bytes-out provider backed by a pathlib.Path tree.

Parameters:

root (Path)

property root: Path

Provider storage root as a pathlib.Path.

put(namespace, object_key_hmac, payload, *, content_hash, label)

Atomically write the object and its sidecar, returning ProviderObjectMetadata.

Atomicity guarantee: the payload file is written to a .tmp sibling and renamed into place. The sidecar is written afterwards; on sidecar-write failure the payload is removed so no orphaned object lingers without metadata.

Return type:

ProviderObjectMetadata

Parameters:

• namespace (str)

• object_key_hmac (str)

• payload (bytes)

• content_hash (str)

• label (str)

get(namespace, object_key_hmac)

Read the object payload from disk and return verified metadata.

Locates the .bin file by HMAC prefix, loads the sibling .meta.json sidecar, reads the raw bytes, and compares the core.hashing.sha256_hex() digest against the sidecar’s content_hash field through verify_content_hash(). Both sha256-<hex>-prefixed strings and bare hex digests are accepted.

Parameters:

• namespace (str) – Logical bucket name; maps to a subdirectory of root.

• object_key_hmac (str) – Full HMAC string identifying the object.

Return type:

tuple[bytes, ProviderObjectMetadata]

Returns:

A two-tuple containing payload bytes and ProviderObjectMetadata.

Raises:

• OutboundStorageNotFoundError – When the object file is absent.

• OutboundStorageIntegrityError – When the sidecar is missing, unreadable, or contains non-JSON content; or when the payload digest does not match the stored hash.

• OutboundStoragePermissionError – When the object file cannot be read due to OS permissions.

• StorageCorruptionError – When the sidecar byte_length field has an unexpected type.

• OutboundStorageValidationError – When namespace or object_key_hmac fail format checks.

delete(namespace, object_key_hmac)

Remove the object file and its sidecar from disk.

Returns False immediately when the object is absent; deleting a non-existent object is idempotent. The sidecar is removed with missing_ok=True so a pre-existing orphaned payload without a sidecar is still cleanly deleted.

Parameters:

• namespace (str) – Logical bucket name.

• object_key_hmac (str) – Full HMAC string identifying the object.

Return type:

bool

Returns:

True when the object was found and deleted; False when it was already absent.

Raises:

• OutboundStoragePermissionError – When the OS refuses the unlink call.

• OutboundStorageValidationError – When namespace or object_key_hmac fail format checks.

iter_namespaces()

Yield the name of every namespace subdirectory under root.

Returns immediately (yields nothing) when root does not yet exist on disk.

Yields:

Directory names in filesystem-returned order.

Return type:

Iterator[str]

iter_objects(namespace)

Yield metadata for every object in namespace.

Only .bin files with a companion .meta.json sidecar are yielded; files without a sidecar are silently skipped (the coordinator surfaces those as integrity issues via its own diff classifier).

Parameters:

namespace (str) – Logical bucket name.

Yields:

ProviderObjectMetadata records in sorted filename order.

Raises:

• OutboundStorageNotFoundError – When the namespace directory is absent.

• OutboundStorageIntegrityError – When a sidecar file is unreadable or contains non-JSON content.

• StorageCorruptionError – When a sidecar byte_length field has an unexpected type.

• OutboundStorageValidationError – When namespace fails format checks.

Return type:

Iterator[ProviderObjectMetadata]

probe(*, read_only=False)

Assess filesystem accessibility and write permissions, returning a ProviderProbeReport.

Attempts to create root if absent. Then, unless read_only=True, performs a sentinel write/delete round-trip in a _probe namespace to confirm write access end-to-end.

The method never raises; every failure mode is encoded in the returned ProviderProbeReport.

Parameters:

read_only (bool) – When True, skip the sentinel write round-trip and report writable=False regardless of actual permissions.

Return type:

ProviderProbeReport

Returns:

A ProviderProbeReport with reachable, writable, and a human-readable detail string describing the outcome.