cadrumo.adapters.persistence.storage.secure_object_namespaces module

Typed secure-object namespace and hierarchy contracts.

Each SecureObjectNamespaceDefinition carries a SensitivityClass field that governs the at-rest encryption treatment applied by the substrate for every object in that namespace.

is_former_product_namespace(namespace)[source]

Return whether namespace uses a retired product-owned prefix.

Return type:

bool

Parameters:

namespace (str)

class SecureObjectNamespaceDefinition(**data)[source]

Bases: BaseModel

Contract for one encrypted SQL secure-object namespace.

Parameters:
key: str
namespace: str
owner: str
sensitivity: SensitivityClass
schema_version: int
object_key_grammar: str
scope: StorageNamespaceScope
custody_disposition: StorageCustodyDisposition
default_object_key: str | None
record_formats: tuple[str, ...]

Persisted-format inventory keys carried by this namespace’s rows.

A namespace is not a persisted format. The great majority hold rows under the secure-object envelope’s one schema version and one upgrader registry, and declare nothing here. The few that do carry a record grammar enrolled in the durability inventory on its own axis: the envelope governs whether the bytes decrypt, the record’s own declaration governs whether what is inside them can still be read, and a floor on the first does not cover the second.

Declared beside the namespace rather than in the gate that reads it, so the author adding such a record sees the obligation where the row lives. Three of these once sat in a hand-maintained table inside a test module, where a correct durability declaration read as a stale one because nothing in production pointed at it.

remote_mirror_policy: StorageRemoteMirrorPolicy
remote_mirror_requires_revision: bool
remote_mirror_requires_integrity_manifest: bool
property singleton_object_key: str | None

Return the one key this namespace admits, or None when it is multi-key.

A grammar carrying no {placeholder} names a literal key rather than a template, so the namespace holds exactly one row under exactly that key – catalogue, default, state. That makes the declared grammar machine-checkable for this class of namespace without a per-namespace parser.

validate_object_key(object_key)[source]

Raise NamespaceRegistryError when object_key violates this contract.

Two checks apply. Every namespace rejects surrounding whitespace and a .. traversal segment, because the key also names a logical storage path (secure_object_logical_path()). Path SEPARATORS are not rejected: several namespaces declare a grammar rooted at a logical path ({logical_root}|..., {storage_state_path_posix}) whose keys legitimately contain them.

A singleton namespace additionally requires the key to equal its declared literal. Without that, a valid envelope written under a mistyped key round-trips through raw storage while the owning repository – which addresses the singleton by its canonical key – reports the record absent: the row is silently orphaned rather than refused.

A templated (multi-key) namespace is checked for traversal safety only. Its placeholder grammar stays documentation until a typed per-namespace key validator exists; asserting more here would refuse keys the registry itself declares as valid.

Parameters:

object_key (str) – The natural (pre-digest) key a caller is addressing.

Raises:

NamespaceRegistryError – When the key is unsafe or, for a singleton namespace, is not the declared literal.

Return type:

None

require_default_object_key()[source]

Return the singleton object key or raise when the namespace is multi-key.

Return type:

str

class StorageHierarchyRegistry(**data)[source]

Bases: BaseModel

Registry carrying the known secure-storage hierarchy contracts.

Parameters:
namespaces: tuple[SecureObjectNamespaceDefinition, ...]
paths: tuple[StoragePathDefinition, ...]
namespace_by_value(value)[source]

Return a SecureObjectNamespaceDefinition by persisted namespace value.

Return type:

SecureObjectNamespaceDefinition

Parameters:

value (str)

path_by_key(key)[source]

Return a StoragePathDefinition by registry key.

Return type:

StoragePathDefinition

Parameters:

key (str)

namespaces_for_custody_profile(profile)[source]

Return carried SecureObjectNamespaceDefinition rows for a custody profile.

Return type:

tuple[SecureObjectNamespaceDefinition, ...]

Parameters:

profile (StorageCustodyProfile)