cadrumo.adapters.outbound.storage.mirror_manifest module

Remote ciphertext mirror manifest construction, persistence, and inspection.

This module converts adapters.persistence.storage.sql.secure_object_records.SecureObjectRawRow records into RemoteMirrorNamespaceManifest payloads, stores those payloads through StorageProvider under REMOTE_MIRROR_MANIFEST_NAMESPACE, and reports mirror drift as RemoteMirrorInspection records. Google sync uses the inspection helpers to distinguish partial uploads, partial downloads, stale mirrors, and revision conflicts without exposing plaintext secure-object payloads.

build_remote_mirror_namespace_manifest(namespace, rows)

Build a RemoteMirrorNamespaceManifest for one ciphertext namespace.

Only rows whose adapters.persistence.storage.sql.secure_object_records.SecureObjectRawRow namespace matches namespace are included. Each row becomes a RemoteMirrorObjectManifest, and the latest revision watermark is derived from the newest revision_written_at among those entries.

Return type:

RemoteMirrorNamespaceManifest

Parameters:

• namespace (str)

• rows (Iterable[SecureObjectRawRow])

put_remote_mirror_namespace_manifest(provider, manifest)

Persist manifest through provider and return its metadata.

The manifest JSON is written as an object in REMOTE_MIRROR_MANIFEST_NAMESPACE with a core.hashing.sha256_hex() content hash.

Return type:

ProviderObjectMetadata

Returns:

The provider’s ProviderObjectMetadata for the manifest object.

Parameters:

• provider (StorageProvider)

• manifest (RemoteMirrorNamespaceManifest)

get_remote_mirror_namespace_manifest(provider, namespace)

Return the stored RemoteMirrorNamespaceManifest for namespace.

Missing manifest objects return None. Malformed manifest payloads are translated to OutboundStorageIntegrityError so callers can handle them through the adapters.outbound.storage.errors.OutboundStorageError hierarchy.

Return type:

RemoteMirrorNamespaceManifest | None

Parameters:

• provider (StorageProvider)

• namespace (str)

inspect_remote_mirror_upload(provider, expected_manifest)

Detect remote upload drift for the expected namespace manifest.

Return type:

RemoteMirrorInspection

Returns:

A RemoteMirrorInspection describing the drift between the expected manifest and the remote mirror. Issues use RemoteMirrorIssueKind values such as PARTIAL_UPLOAD, STALE_MIRROR, and REVISION_CONFLICT.

Parameters:

• provider (StorageProvider)

• expected_manifest (RemoteMirrorNamespaceManifest)

inspect_remote_mirror_download(provider, remote_manifest)

Inspect whether every object in remote_manifest is downloadable.

Missing objects, unreadable objects, integrity failures, and provider metadata drift are reported as PARTIAL_DOWNLOAD issues on the returned RemoteMirrorInspection.

Return type:

RemoteMirrorInspection

Parameters:

• provider (StorageProvider)

• remote_manifest (RemoteMirrorNamespaceManifest)

compare_remote_mirror_manifests(*, local, remote)

Compare two namespace manifests and return a RemoteMirrorInspection.

The comparison classifies absent entries, stale remote revisions, and divergent revision lineages as RemoteMirrorIssue records.

Return type:

RemoteMirrorInspection

Parameters:

• local (RemoteMirrorNamespaceManifest)

• remote (RemoteMirrorNamespaceManifest)

remote_mirror_object_key_hmac(namespace, object_key)

Compute the provider object key used for mirrored ciphertext rows.

The digest combines the logical namespace and the raw secure-object object_key bytes so the remote provider sees only deterministic ciphertext object identifiers.

Return type:

str

Parameters:

• namespace (str)

• object_key (bytes)

remote_mirror_object_label(namespace)

Derive the human-readable half of a mirrored row’s provider filename.

A mirrored object is named <object-key-hmac>--<label>.bin. The hmac half comes from remote_mirror_object_key_hmac(); this is the other half, and both are facts about the wire, not about whichever surface happens to push. The label is the namespace’s trailing dotted segment, sanitised to alphanumerics, dash, underscore and dot, and capped at thirty-two characters, so the operator can recognise a row in a Drive listing without the name carrying anything the hmac exists to hide.

Deliberately not _manifest_label(), which names the manifest FILE for a namespace: that one keeps the whole namespace, admits no dots or underscores, and allows sixty-four characters. Two names for two different objects, and neither policy is a superset of the other.

Return type:

str

Parameters:

namespace (str)