cadrumo.application.user_profile.custody_service module

Application service for current-format profile custody transactions.

exception ProfileCustodyDisplacedSessionRetirementError(message=None, *, context=None, translated_message=None)[source]

Bases: ProfileCustodyTransactionConflictError

The create transaction could not void the session of the profile it displaces.

Distinct from the generic transaction conflict for one reason that is operator-facing rather than structural: creation refuses on this and on a label or UUID collision alike, and the collision message – the profile already exists – is a false account of this one. The operator’s own credentials and label are fine; a prior profile’s session artefact could not be removed, so the creation door needs a refusal that says that.

It subclasses the conflict deliberately. Every existing handler treats a create conflict as a refusal that leaves the pointer where it was, and that is exactly the disposition wanted here; narrowing the message must not narrow which handlers catch it.

Its registry entry is declared retryable, which is a considered value rather than an oversight to correct: the underlying removal fails when something else holds the receipt open – another reader, a backup agent, a scanner – which clears on its own, so a second attempt is the right advice to give.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

code
class ProfileCustodyTransactionService(*, root=None)[source]

Bases: object

Internal physical-custody capability owned by ProfileCapsuleLifecycle.

No application caller may use this capability directly. The lifecycle is the only collaboration boundary entitled to prepare, publish, recover, or remove a current capsule; keeping the transaction mechanics here prevents a second public writer from materialising beside that boundary.

Parameters:

root (Path | None)

prepare_delete(*, profile_id, transaction_id=None, retention_override=None, requires_inactive_target=False, now=None)[source]

Record all local preflight evidence before any destructive action.

The hold assessment, exact inventory, pointer snapshot, and confirmation challenge are written into one journal before the deletion marker exists. A later executor therefore either has the complete authorization record or cannot begin the destructive sequence.

retention_override is an operator authorisation to proceed past an asserted FILING hold – the statutory retention floor. It is recorded into the journal so the executor re-validates against the same authorisation this preparation weighed, and it is refused outright when no filing hold blocks the deletion: an override answers an assessed block, and one carried where nothing blocks is a free pass.

Return type:

ProfileCustodyTransactionJournal

Parameters:
create_capsule(*, profile_id, password_envelope, sentinel, data_files, label, publication_kind=ProfilePublicationKind.ENROLL, stage_initializer=None, transaction_id=None, now=None)[source]

Journal, stage, verify, publish, then point at one new custody capsule.

The stage is inventory-bound before publication, and the pointer changes only after the committed capsule is visible. Every intermediate state is durable so recovery can resume at the last verified boundary.

Return type:

ProfileCustodyTransactionReceipt

Parameters:
recover_create(transaction_id, *, now=None)[source]

Recover a create journal without replacing an independently changed pointer.

Recovery reloads the journal while holding the profile lock, then checks the captured pointer witness again immediately before publication. A receipt makes the operation idempotent without replaying adapter effects.

Return type:

ProfileCustodyTransactionReceipt | None

Parameters:
confirmation_for(journal)[source]

Return the exact target-bound confirmation object an operator must echo.

Return type:

ProfileCustodyDeleteConfirmation

Parameters:

journal (ProfileCustodyTransactionJournal)

execute_delete(confirmation, *, now=None)[source]

Execute or resume one fully confirmed local deletion; never touch external state.

The confirmation is checked before and inside the profile lock. Each owner step persists its receipt and next journal state, allowing a crash to resume without repeating a completed local effect.

Return type:

ProfileCustodyTransactionReceipt

Parameters: