aeat.application.bucket_maintenance package¶

Application-layer bucket-maintenance lifecycle facade.

This package exposes BucketMaintenanceService and its Pydantic command/result contracts for profile-scoped storage maintenance. The service composes the existing single-writer primitives that own bucket lifecycle operations: label rename, soft tombstone plus hard removal, sealed portable-bundle export/import, and namespace-level browse. It contributes bucket-maintenance audit events through domain.buckets.BucketEventHistoryRepository while the inner profile primitives keep emitting their lifecycle events.

Authority: 2026-06-03-cli-workflow-redesign-adr (composition pattern). The service does not re-implement a cross-store write; it delegates to the existing top-level user-profile re-exports: application.user_profile.rename_profile(), application.user_profile.delete_profile_with_lifecycle_span(), application.user_profile.remove_profile_bucket_directory(), application.user_profile.serialize_profile_bundle(), and application.user_profile.deserialize_profile_bundle().

Export/import composition is deliberately typed at the facade boundary: commands such as ExportBucketCommand and ImportBucketCommand produce sealed archives with adapters.persistence.storage.bucket.ExportArchiveHeader, payloads based on domain.user_profile.UserProfilePortableExport, and a manifest digest from compute_manifest_digest(). Sealed exports use adapters.persistence.storage.StorageCustodyProfile.FULL: the portable payload carries the typed profile/work/ledger/calculation/filing categories plus the registry-derived carried secure-object namespaces. Carried rows are addressed by their natural object keys, not the stored HMAC lookup digests, so import re-saves them through the recipient bucket’s adapters.persistence.storage.SecureObjectRepository and re-encrypts under that bucket’s DEK. This package exposes the lifecycle composition verbs archive, browse, delete, disk_usage, export, import, inspect, rename, and restore. The search verb is deferred behind its own ADR because it must route through domain repositories instead of decrypting secure-object storage directly.

BucketMaintenanceService.disk_usage() measures a bucket’s on-disk footprint by summing regular-file byte sizes under its fixed directory layout (adapters.persistence.storage.bucket.bucket_paths()); it reads only filesystem metadata, never decrypted content, so it can measure a non-active (even archived) bucket without opening a storage session.

create_sandbox() and discard_sandbox() expose a discardable experiment-workspace lifecycle over the same primitives: a sandbox is an ordinary bucket labelled with the reserved SANDBOX_LABEL_PREFIX, created (optionally forked from a live profile’s facts) through the canonical atomic-create span and discarded through this package’s BucketMaintenanceService.delete(). preview_discard_sandbox() reports what a discard would remove without removing it, and list_sandboxes() enumerates every live sandbox for bulk operations such as sandbox prune. archive_sandbox() and restore_sandbox() expose a reversible-dormancy alternative to discard: BucketMaintenanceService.archive() soft-tombstones the sandbox without removing its directory, and BucketMaintenanceService.restore() reactivates it. merge_sandbox() promotes a SandboxMergeScope (ledger, modelo, or all) from a sandbox into a target profile bucket by composing the same typed catalogue repositories and domain upsert primitives (upsert_work_unit, upsert_calculation_revision, upsert_filing_record) the portable-bundle import path already uses for those categories, so a repeated merge of unchanged sandbox content is an idempotent no-op write.

aeat.application.bucket_maintenance package¶

Submodules¶