aeat.domain.buckets._event module

Bucket-scoped append-only event records.

A BucketEvent captures one material workflow transition inside a bucket. Events are immutable, content-addressed by their (bucket_id, event_type, occurred_at, actor, object_type, object_id, payload) tuple, and grouped into a frozen catalogue.

The closed BucketEventType enum fixes the emission scope mandated by the bucket event history specification. New event kinds enter the codebase as enum additions, never as ad-hoc strings.

BucketActorLabel

Short label identifying the actor that emitted a bucket event.

A non-empty string of at most 64 characters; trailing and leading whitespace is stripped at validation time. Typical values are the CLI command path ("aeat.app.modelo.calculate") or an automated-agent slug ("censo.sync").

alias of Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=64, pattern=None, ascii_only=None)]

class BucketEventType(*values)[source]

Bases: StrEnum

Closed catalogue of bucket-event kinds.

The enum mirrors the per-service emission scope declared by the bucket event history specification. Emitters land incrementally with their owning implementations; new kinds are added here only when a corresponding specification sanctions the emission.

MODELO_CALCULATION_CREATED
MODELO_VERIFICATION_PASSED
MODELO_VERIFICATION_REFUSED
MODELO_FILED
MODELO_FILED_SUPERSEDED
MODELO_AMENDED
MODELO_FILING_IMPORTED
MODELO_LIVE_EVIDENCE_STAMPED
MODELO_RECONCILED
MODELO_EXPORTED
MODELO_IVA_WALLET_CORRECTED
MODELO_IVA_WALLET_OVERRIDE_RECORDED
MODELO_145_COMMUNICATION_CREATED
MODELO_145_COMMUNICATION_EXPORTED
MODELO_145_COMMUNICATION_DELIVERED_TO_PAYER
MODELO_145_COMMUNICATION_LOCALLY_COMPLETED
MODELO_WORK_UNIT_CREATED
MODELO_WORK_UNIT_DISCARDED
MODELO_WORK_UNIT_RENAMED
PROFILE_BUCKET_CREATED
PROFILE_SELECTED
PROFILE_VALUES_UPDATED
PROFILE_VALUES_CLEARED
PROFILE_TOMBSTONED
PROFILE_REACTIVATED
PROFILE_DUPLICATED
PROFILE_RENAMED
PROFILE_EXPORTED
PROFILE_IMPORTED
PROFILE_ACTIVATED
CENSO_REFRESHED
CENSO_APPLIED
CENSO_DEPENDENT_STAMPED_STALE
MODELO_LEDGER_DEPENDENT_STAMPED_STALE
CENSO_DECLARATION_ALTA
CENSO_DECLARATION_MODIFICACION
CENSO_DECLARATION_BAJA
BUCKET_EXPORTED
BUCKET_IMPORTED
BUCKET_RENAMED
BUCKET_DELETED
BUCKET_ARCHIVED
BUCKET_RESTORED
BUCKET_MERGED
LEDGER_RATIOS_SET
LEDGER_RATIOS_UNSET
LEDGER_RATIOS_CENSO_OVERRIDE_WARNING
AUTH_PROVIDER_CONFIGURED
CONFIG_ENV_UPDATED
AUTH_CERTIFICATE_SOURCE_REGISTERED
AUTH_CERTIFICATE_SOURCE_SELECTED
AUTH_CERTIFICATE_SOURCE_REMOVED
AUTH_CERTIFICATE_SOURCE_SECRET_SET
AUTH_CERTIFICATE_SOURCE_SECRET_ROTATED
AUTH_CERTIFICATE_SOURCE_SECRET_REMOVED
LEDGER_TRANSACTION_CREATED
LEDGER_TRANSACTION_IMPORTED
LEDGER_IMPORT_DIAGNOSTIC_RECORDED
LEDGER_TRANSACTION_UPDATED
LEDGER_TRANSACTION_CLASSIFIED
LEDGER_TRANSACTION_LLM_SUGGESTION_REJECTED
LEDGER_TRANSACTION_ALLOCATED
LEDGER_TRANSACTION_REMOVED
LEDGER_TRANSACTION_ARCHIVED
LEDGER_TRANSACTION_STASHED
LEDGER_TRANSACTION_RESTORED
LEDGER_TRANSACTION_REVIEWED_EXCLUDED
LEDGER_TRANSACTION_EXPORTED
LEDGER_TRANSACTION_SPLIT
LEDGER_TRANSACTION_MERGED
LEDGER_CATALOGUE_RESET
LEDGER_SANITIZATION_COMPLETED
PURCHASE_INVOICE_EVIDENCE_ATTACHED
PURCHASE_INVOICE_EVIDENCE_REPLACED
PURCHASE_INVOICE_EVIDENCE_DETACHED
PAYABLE_INVOICE_CREATED
PAYABLE_INVOICE_UPDATED
PAYABLE_INVOICE_REMOVED
COLLECTIBLE_INVOICE_CREATED
COLLECTIBLE_INVOICE_UPDATED
COLLECTIBLE_INVOICE_REMOVED
LEDGER_INVENTORY_CREATED
LEDGER_INVENTORY_MOVEMENT_ADDED
LEDGER_INVENTORY_VALUATION_PREVIEWED
LEDGER_INVENTORY_REMOVED
MODELO_AUDIT_VERIFIED
MODELO_AUDIT_EXPORTED
MODELO_AUDIT_REPLAYED
LIVE_NOTIFICATIONS_SNAPSHOT_CAPTURED
LIVE_EXPEDIENTES_SNAPSHOT_CAPTURED
LIVE_VERIFY_NIF_IVA_CHECKED
LIVE_VERIFY_TGVI_CHECKED
LIVE_BORRADOR100_SNAPSHOT_CAPTURED
ATTACHMENT_LINKED
ATTACHMENT_REMOVED
WORKFLOW_STATE_RESET
LEDGER_TRANSACTION_CORRECTION_APPLIED
LEDGER_PURCHASE_INVOICE_EVIDENCE_CORRECTION_APPLIED
LEDGER_PAYABLE_INVOICE_CORRECTION_APPLIED
LEDGER_COLLECTIBLE_INVOICE_CORRECTION_APPLIED
LEDGER_RENTAL_INCOME_CORRECTION_APPLIED
LEDGER_RENTAL_EXPENSE_CORRECTION_APPLIED
COLLAB_RECIPIENT_REGISTERED
COLLAB_RECIPIENT_REMOVED
COLLAB_PACKAGE_ENCRYPTED_FOR_RECIPIENT
COLLAB_PACKAGE_DECRYPTED
COLLAB_REVIEW_ONLY_WORKSPACE_OPENED
COLLAB_PACKAGE_COUNTER_SIGNED
class BucketEventObjectType(*values)[source]

Bases: StrEnum

Closed catalogue of object types a bucket event can reference.

WORK_UNIT
CALCULATION_REVISION
VERIFICATION_REPORT
FILING_RECORD
COMMUNICATION_RECORD
PROFILE
BUCKET
LEDGER_TRANSACTION
LEDGER_IMPORT_BATCH
LEDGER_CATALOGUE
LEDGER_EXPORT
PURCHASE_INVOICE_EVIDENCE
PAYABLE_INVOICE
COLLECTIBLE_INVOICE
ATTACHMENT
WORKFLOW_STATE
RECIPIENT
derive_bucket_event_id(*, bucket_id, event_type, occurred_at, actor, object_type, object_id, payload)[source]

Return the deterministic SHA-256 id for a bucket event.

Return type:

str

Parameters:
class BucketEvent(**data)[source]

Bases: BaseModel

One append-only bucket event.

Variables:

  • event_id – Lowercase 64-char SHA-256 derived from the full event body. Content-addressed: structurally identical emissions collapse to the same id, making append naturally idempotent.

  • bucket_id – Owning bucket identifier.

  • event_type – One of BucketEventType.

  • occurred_at – UTC timestamp when the event was emitted.

  • actor – Actor label (free text up to 64 chars).

  • object_type – Type of the affected domain object.

  • object_id – Stable identifier of the affected object (e.g. a 64-char SHA-256 work-unit / revision / filing-record id).

  • payload_version – Integer schema version of the payload mapping. Bumped when the payload contract changes.

  • payload – Free-form structured details. Keys and values are short strings; secrets / credentials must not appear.

Parameters:

  • event_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • event_type (BucketEventType)

  • occurred_at (datetime)

  • actor (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=64, pattern=None, ascii_only=None)])

  • object_type (BucketEventObjectType)

  • object_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • payload_version (int)

  • payload (Mapping[Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=64, pattern=None, ascii_only=None)], Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=0, max_length=500, pattern=None, ascii_only=None)]])

event_id: _EventId
bucket_id: _ProfileName
event_type: BucketEventType
occurred_at: datetime
actor: BucketActorLabel
object_type: BucketEventObjectType
object_id: _ObjectId
payload_version: int
payload: Mapping[_PayloadKey, _PayloadValue]
class BucketEventHistoryCatalogue(**data)[source]

Bases: BaseModel

Immutable catalogue of every bucket event in storage.

Parameters:

events (Mapping[str, BucketEvent])

events: Mapping[str, BucketEvent]
get(event_id)[source]

Return the BucketEvent for event_id, or None if absent.

Return type:

BucketEvent | None

Parameters:

event_id (str)

for_bucket(bucket_id, *, event_types=None)[source]

Return every BucketEvent recorded against bucket_id in chronological order.

Events are sorted by occurred_at ascending and optionally filtered to one or more event types.

Return type:

tuple[BucketEvent, ...]

Parameters:
for_object(*, object_type, object_id)[source]

Return every event recorded against one object, ordered by occurred_at ascending.

Return type:

tuple[BucketEvent, ...]

Returns:

Tuple of BucketEvent records in chronological order.

Parameters:
values()[source]

Return a live view over every BucketEvent in the catalogue.

Return type:

ValuesView[BucketEvent]