cadrumo.application.filing.retention module

Canonical filing-retention facts used by current local profile deletion.

The owner accepts real ModeloRecord facts and derives retention from the domain legal floor. It never accepts a caller-selected clear/held outcome and is intentionally not re-exported through application.user_profile.

FILING_RETENTION_OWNER_DIRNAME: Final[str]

This owner’s directory name, read from its one declaration in the taxonomy.

The storage path registry spells the same segment in this format’s grammar, so the name is declared once and read in both places rather than typed in each.

FILING_RETENTION_SNAPSHOT_SCHEMA_VERSION: Final[int]

Current on-disk schema version of FilingRetentionSnapshot documents.

class FilingRetentionFact(**data)[source]

Bases: BaseModel

The retention-relevant immutable projection of a real modelo filing.

Parameters:

data (Any)

filing_record_id: FilingRecordId
modelo: str
filing_year: FilingYear
filed_at: datetime
class FilingRetentionSnapshot(**data)[source]

Bases: BaseModel

Canonical filing-owner input; it contains facts, never a verdict.

Parameters:

data (Any)

schema_version: int
profile_id: UUID
filing_records: tuple[FilingRetentionFact, ...]
observed_at: datetime
self_digest: PrefixedContentDigest
property canonical_payload: dict[str, object]

Return the ordered field mapping the self-digest is computed over.

property computed_self_digest: str

Return the digest recomputed from the live fields, for tamper comparison.

canonical_json_bytes()[source]

Return the canonical on-disk encoding of this snapshot.

Return type:

bytes

classmethod from_modelo_records(*, profile_id, records, observed_at)[source]

Build a digest-sealed snapshot from the profile’s filing records.

Parameters:

  • profile_id (UUID) – Profile whose retention position is being recorded.

  • records (Iterable[ModeloRecord]) – ModeloRecord entries contributing one retention fact each.

  • observed_at (datetime) – UTC instant the retention position was observed.

Return type:

FilingRetentionSnapshot

Returns:

A FilingRetentionSnapshot whose facts are ordered by filing record id and whose self-digest is already sealed.

class FilingRetentionAuthority(*, root=None, local_record_store=None)[source]

Bases: object

Filing-owner source mutation and read-only deletion projection.

Parameters:
record_filing_catalogue(*, profile_id, records, observed_at)[source]

Persist actual filing facts; retention verdict remains domain-derived.

Core types: ModeloRecord.

Return type:

FilingRetentionSnapshot

Parameters:
assess(profile_id, *, now, authority=None)[source]

Return the FULL retention position for one profile’s filed records.

The same computation project() performs, returned whole instead of reduced to a blocking flag. Two consumers want different halves of one answer: the custody deletion gate needs only “may I erase”, while the operator-facing refusal must say how many records are retained, against what floor, and when erasure becomes safe – a message that cites Ley 58/2003 (LGT) arts. 66 and 70 and is worthless if it cannot name them. Exposing the assessment keeps assess_retention_floor() the single source for both rather than growing a second retention path.

There is deliberately NO empty-assessment fallback. An absent or unreadable snapshot raises, exactly as it does for project(), because an assessment defaulted to zero retained records is indistinguishable from a genuine “nothing is retained” and would read as permission to erase.

Raises:

  • FileNotFoundError – The canonical filing snapshot is absent.

  • ValueError – The snapshot is invalid, or its identity or bytes disagree with its path.

Return type:

RetentionFloorAssessment

Parameters:
project(profile_id, *, now, authority=None)[source]

Evaluate persisted filing facts using the domain retention authority.

Return type:

ProfileDeletionHoldOwnerProjection

Parameters:
path(profile_id)[source]

Return the canonical snapshot path for profile_id.

Return type:

Path

Parameters:

profile_id (UUID)

try_record_filing_retention_snapshot(*, bucket_id, records, observed_at)[source]

Record one profile’s filing facts, and never raise doing it.

The deletion preflight cannot read a profile’s filing catalogue – it runs against profiles it has not unlocked – so this plaintext snapshot is how the retention position stays knowable without the key. Two callers write it: profile creation, so “never filed” is a RECORDED fact, and filing persistence, so the position stays current.

Never raises, and the asymmetry is the reason rather than convenience. Neither caller exists to serve deletion: one creates a profile and one discharges a statutory filing obligation. A caller REFUSED because a deletion-support record could not be written is a worse outcome than a profile whose snapshot is stale or missing, and it would put a deletion concern in the path of both.

Swallowing is safe only while absence fails CLOSED: with no snapshot the retention assessment refuses, which blocks a deletion rather than permitting one. An empty RECORDED snapshot is a different thing from an absent one and must stay so – if absence ever comes to mean “nothing retained”, this function’s contract becomes a fail-open and must be revisited with it.

Return type:

bool

Returns:

True when the snapshot was written, False when it was not. The caller is expected to ignore it; it exists so a test can assert the write happened rather than inferring it.

Parameters:

Core types: ModeloRecord.