aeat.application.modelo._review_package_collab_audit module

Bucket-event audit-tag emission for the accountant/gestor collaboration surface.

This module closes the “collab_event / privacy_event audit-tag enrolment” item left open on issue #421 (2026-07-04-recipient-encryption-adr and its follow-up slices): every trust-boundary crossing on the review-package recipient-encryption surface – registering or removing a trusted recipient, sealing a package for a recipient, decrypting a sealed package, opening a review-only workspace, and counter-signing a received package – now emits a typed BucketEvent so an operator can reconstruct the collaboration timeline from the bucket-event-history catalogue, mirroring every other material workflow transition in the codebase (aeat-swarm-audit-cadence’s persistence-identity axis; the pattern established by _iva_wallet_seed.py and _revision_persistence.py).

Two distinct event-name prefixes are used, per the enum’s own grouping comment: collab_event.* marks a TRUST/TRANSPORT-boundary action (adding a recipient, sealing a package for them) that does not itself expose decrypted material to the caller emitting the event; privacy_event.* marks a DISCLOSURE-relevant action where decrypted or otherwise sensitive material was read (decrypting a package, opening a review-only workspace). This mirrors the ADR’s own vocabulary and lets a future audit query distinguish “who was trusted / what was sealed” from “what was actually read”.

Every function in this module is a thin, pure composition over emit_bucket_event() (composition-service-no-parallel-write-path): none of them open a SecureObjectRepository write path of their own for the recipient registry, the encryption primitives, or the review-package build/verify layer – those already own their persistence. This module’s only write is the bucket-event-history append.

Payloads never carry secret key material or decrypted package bytes – only identifiers (recipient id, public-key fingerprint, revision id, bucket id) and small disposition flags (review_only), matching the existing bucket-event payload convention (short strings, no credentials).

This module ALSO closes the “countersign-attach-to-journal” item left open on issue #421: emit_collab_feedback_countersign_attached_event() records, on the ORIGINATOR’s own bucket, that a recipient’s counter-signed receipt (recovered from an imported FeedbackPackage, see _review_package_feedback) was verified and attached to the originator’s approval journal – the mirror image of emit_collab_package_counter_signed_event(), which records the counter-signer’s OWN act of signing on their bucket. Reuses the same COLLAB_PACKAGE_COUNTER_SIGNED event type (no new BucketEventType member): the enum member names the FACT that a counter-signature exists for a package, not which party’s bucket recorded it, exactly as COLLAB_PACKAGE_DECRYPTED already serves both the forward (accountant decrypts the original package) and reverse (the originator decrypts a feedback package) directions.

See also

_review_package_recipient_registry

Owns the recipient-fingerprint registry this module’s register/remove events describe.

_review_package_recipient_encryption

Owns the encrypt/decrypt primitives this module’s package events describe.

_review_package_review_only_workspace

Owns the review-only workspace this module’s workspace-opened event describes.

_review_package_counter_sign

Owns the counter-sign primitive this module’s counter-signed event describes.

_review_package_feedback

Owns the feedback-package round trip whose imported counter-signed receipt emit_collab_feedback_countersign_attached_event() attaches to the originator’s journal.

emit_collab_recipient_registered_event(record, *, bucket_id, repository, actor='operator', occurred_at=None)[source]

Append a COLLAB_RECIPIENT_REGISTERED event for a newly-trusted recipient.

Parameters:
Return type:

BucketEvent

emit_collab_recipient_removed_event(*, recipient_id, bucket_id, repository, actor='operator', occurred_at=None)[source]

Append a COLLAB_RECIPIENT_REMOVED event for a revoked recipient.

Parameters:
Return type:

BucketEvent

emit_collab_package_encrypted_event(envelope, *, bucket_id, repository, actor='operator', occurred_at=None)[source]

Append a COLLAB_PACKAGE_ENCRYPTED_FOR_RECIPIENT event.

Recorded on the SENDER’s bucket (the taxpayer sealing the package): a trust/transport-boundary action, not a disclosure of decrypted material, hence collab_event.* rather than privacy_event.*.

Parameters:
Return type:

BucketEvent

emit_collab_package_decrypted_event(envelope, *, bucket_id, repository, actor='operator', occurred_at=None)[source]

Append a COLLAB_PACKAGE_DECRYPTED event.

Recorded on the RECIPIENT’s bucket after a successful decrypt_review_package_for_recipient() call: decrypted package bytes were read, so this is a privacy_event.*-prefixed disclosure event, not a bare collab_event.* transport event.

Parameters:
Return type:

BucketEvent

emit_collab_review_only_workspace_opened_event(workspace, *, bucket_id, repository, actor='operator', occurred_at=None)[source]

Append a COLLAB_REVIEW_ONLY_WORKSPACE_OPENED event.

A privacy_event.*-prefixed disclosure event: opening the workspace makes the decrypted review-package contents readable to the caller.

Parameters:
Return type:

BucketEvent

emit_collab_package_counter_signed_event(receipt, *, bucket_id, repository, actor='operator', occurred_at=None)[source]

Append a COLLAB_PACKAGE_COUNTER_SIGNED event.

Recorded on the counter-signer’s (accountant’s) bucket after counter_sign_review_package(): a trust/transport-boundary action (attesting to a signature already received), hence collab_event.*.

Parameters:
Return type:

BucketEvent

emit_collab_feedback_countersign_attached_event(imported, *, bucket_id, repository, actor='operator', occurred_at=None)[source]

Append a COLLAB_PACKAGE_COUNTER_SIGNED event to the ORIGINATOR’s journal.

Recorded on the originator’s OWN bucket after import_feedback_package() has already verified the imported feedback’s CounterSignedReceipt (i.e. imported.counter_signature_verified is True): the countersigned approval is now attached to the originator’s approval journal, closing the collaboration round trip. Reuses COLLAB_PACKAGE_COUNTER_SIGNED (see module docstring) rather than minting a new event type – the same fact, recorded from the other party’s bucket.

Parameters:
Raises:

ValueError – If imported.feedback.counter_signed_receipt is None or imported.counter_signature_verified is not True – attaching an unverified or absent countersignature to the journal would misrepresent the collaboration record.

Return type:

BucketEvent