cadrumo.adapters.persistence.storage.errors module

Storage-layer exceptions.

All storage errors inherit from core.errors.hierarchy.CadrumoError so callers can catch domain-wide failures with a single base class.

The class tree:

  • StorageError — base for every storage error.

  • PersistenceError — base for the at-rest crypto, secret store, blob store, envelope, file lock, path containment, and audit-redaction surfaces. Subclass of StorageError so existing catchers continue to work.

exception SecureStorageError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoError

Base class for secure-storage failures.

This named base keeps the encrypted persistence, secret-store, bucket-session, and per-bucket lifecycle surfaces catchable as one family while still deriving from the central Cadrumo error registry.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception StorageError(message=None, *, context=None, translated_message=None)[source]

Bases: SecureStorageError

Base class for every error raised by adapters.persistence.storage.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception RepositoryError(message=None, *, context=None, translated_message=None)[source]

Bases: StorageError

Raised when a repository operation fails (not-found, integrity, etc.).

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception RepositorySetupError(message=None, *, context=None, translated_message=None)[source]

Bases: RepositoryError

Raised when a concrete repository subclass is missing a required class attribute.

Programming-contract guard: the attribute must be declared on the subclass before instantiation. Unlike a plain TypeError, this error is enrolled in the Cadrumo error registry so it produces a structured envelope rather than an opaque interpreter-level exception.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception SecureObjectRevisionConflictError(message=None, *, context=None, translated_message=None)[source]

Bases: RepositoryError, LedgerPersistenceConflictError

Raised when a revision-aware secure-object write sees a stale revision.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception PersistenceError(message=None, *, context=None, translated_message=None)[source]

Bases: StorageError

Base class for governed-persistence error subtypes.

Errors raised by the at-rest crypto primitives, the secret store, the encrypted blob store, the schema-version envelope, the file-lock helper, the path containment helper, and the audit-sink redaction contract all inherit from this class.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception StorageValidationError(message=None, *, context=None, translated_message=None)[source]

Bases: PersistenceError

Raised when a storage parameter fails validation (e.g. key length).

Pydantic-facing validators translate this registered error to a plain ValueError at their callback boundary. The storage layer itself keeps the registered type, so callers can dispatch on StorageError without leaking a framework builtin into the hierarchy.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
storage_validation_error(message)[source]

Build a StorageValidationError carrying the shared integrity message key.

Single canonical factory for the storage-validation error that the persistence-storage submodules (crypto, envelope, runtime, secret store, and the master-key helpers) previously each declared identically.

Return type:

StorageValidationError

Parameters:

message (str)

exception EncryptionError(message=None, *, context=None, translated_message=None)[source]

Bases: PersistenceError

Base class for AEAD encryption / decryption failures.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception DecryptionError(message=None, *, context=None, translated_message=None)[source]

Bases: EncryptionError

Raised when AEAD decryption fails (tag mismatch, malformed input).

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception SecureObjectUnreadableError(namespace, row_id, *, cause=None)[source]

Bases: DecryptionError

Raised when one stored secure object cannot be decrypted under the current master key.

Distinct from the generic DecryptionError so iterator-shaped consumers can surface a structured per-row failure (namespace, row id, underlying cause) without aborting the iteration. The plaintext bound to such a row is cryptographically unrecoverable from this process: the master key under which it was sealed is no longer available.

Parameters:
Return type:

None

code
exception KeyDerivationError(message=None, *, context=None, translated_message=None)[source]

Bases: EncryptionError

Raised when a key-derivation step fails.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception NonceCollisionError(message=None, *, context=None, translated_message=None)[source]

Bases: EncryptionError

Raised on a defensive nonce-uniqueness invariant violation.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception SecretStoreError(message=None, *, context=None, translated_message=None)[source]

Bases: PersistenceError

Base class for secret-store I/O failures.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception SessionExpiredError(message=None, *, context=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when the active BucketSession has crossed its idle deadline.

The session was opened earlier in the process lifetime but the operator did not act before the configured idle-lock window elapsed. The session is sealed. The CLI boundary may project a recovery action only after it resolves a public profile target.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception KeyringUnavailableError(message=None, *, context=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when the OS keychain backend is unusable.

Either no backend is registered (e.g. headless Linux without libsecret), the backend rejected the operation, or the configured backend is the no-op null keyring.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception ClassificationError(message=None, *, context=None, translated_message=None)[source]

Bases: PersistenceError

Raised when a record’s declared sensitivity class is incompatible with its repository.

Example: writing a CORPUS-class blob through the encrypted-blob path, or loading an envelope under a different classification than the one persisted on disk.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception EnvelopeVersionError(message=None, *, context=None, translated_message=None)[source]

Bases: PersistenceError

Raised when an on-disk envelope version differs from the consumer contract.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception PathContainmentError(message=None, *, context=None)[source]

Bases: PersistenceError

Raised when a computed path escapes its configured root directory.

Parameters:

  • message (str | None)

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

Return type:

None

code
exception BlobNotFoundError(message=None, *, context=None, translated_message=None)[source]

Bases: PersistenceError

Raised when a blob lookup misses on the encrypted blob store.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception BlobIntegrityError(message=None, *, context=None, translated_message=None)[source]

Bases: PersistenceError

Raised when a blob’s on-disk SHA-256 disagrees with its manifest.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception SecureObjectRowIdentityError(namespace, *, expected_identifier, payload_identifier=None)[source]

Bases: PersistenceError

Raised when a stored row’s payload does not reconstruct the key it is filed under.

Every envelope-bound repository derives its object key from the payload’s own natural identity, so the two are two encodings of one fact and must agree. A row whose decrypted payload rebuilds a different key is a substituted or misfiled record: the window it was addressed under is not the window it describes, and projecting it would let a foreign record inherit the addressed row’s coordinates.

Raised by the verifying scan rather than silently skipping the row, because a caller counting records for a declaration must never be handed a quietly shortened set.

Parameters:

  • namespace (str)

  • expected_identifier (str)

  • payload_identifier (str | None)

Return type:

None

code
exception SecretNotFoundError(message=None, *, context=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when a secret-store get does not find a record for the requested key.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception SecretAlreadyExistsError(message=None, *, context=None, translated_message=None)[source]

Bases: SecretStoreError

Raised when a secret-store put would overwrite an existing key without overwrite=True.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception RetentionPolicyError(message=None, *, context=None, translated_message=None)[source]

Bases: PersistenceError

Raised when a record’s retention metadata violates its classification policy.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception NamespaceRegistryError(message=None, *, context=None, translated_message=None)[source]

Bases: StorageError

Raised when a namespace-registry key or definition violates a boot-time invariant.

Fires from Pydantic field and model validators on SecureObjectNamespaceDefinition, StoragePathDefinition, and StorageHierarchyRegistry when a registry key, namespace slug, path segment, or uniqueness constraint is violated at construction time. Inherits from StorageError and ultimately from CadrumoError so callers can catch it without importing Pydantic internals.

Pydantic callback boundaries translate this registered error to a plain ValueError while preserving it as __cause__. Direct callers of StorageHierarchyRegistry helper methods receive the raw NamespaceRegistryError.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
STORAGE_DEGRADATION_ERRORS: Final[tuple[type[Exception], ...]]

The storage failures a calculation treats as DEGRADATION rather than a defect: encrypted facts that cannot be read back, so the caller reports an incomplete source instead of a wrong total.

Nine modules each spelled this tuple out. Seven carried exactly these three, and two extended it with their own persistence errors – which is legitimate, and is why extenders compose this tuple rather than restating it. Restating it is how one caller ends up not degrading on an error the others do.