cadrumo.application.filing.draft_review module

Draft approval persistence and stale-detection helpers.

Provides the approve_draft() / refresh_review_status() lifecycle on top of domain.filing.schema.ModeloDraft and domain.submission.models.ModeloDraftStatus, plus the deterministic domain.filing.schema.ModeloApprovalBasis fingerprint pipeline that lets approval_stale_reasons() detect when a APROBADO draft has been invalidated by upstream changes.

The compute_current_approval_basis() helper receives the required DraftReviewPorts bundle. The executable composition root binds its concrete repositories before the review lifecycle is invoked.

See also

application.filing.runtime.build_runtime_schema_provider()

Builds the registry-backed schema provider whose casilla and formula surface participates in the approval basis.

application.review.source_adapters.drafts_pending()

Emits stale filing approvals as high-severity review queue items.

domain.filing.schema.ModeloApprovalBasis

Persisted digest bundle compared during stale detection.

class ModeloApprovalStaleReason(*values)[source]

Bases: StrEnum

Stable reason codes surfaced when a draft approval becomes stale.

Variables:

  • APPROVAL_BASIS_VERSION_CHANGED – The domain.filing.schema.ModeloApprovalBasis schema version has been bumped since approval.

  • DRAFT_PAYLOAD_CHANGED – The draft’s payload fingerprint (draft_id) no longer matches the stored basis.

  • DRAFT_REVIEW_CHANGED – The draft’s validation findings or machine status changed since approval.

  • TRANSACTION_CATALOGUE_CHANGED – Upstream classified transactions have been updated since approval.

  • INVOICE_CATALOGUE_CHANGED – Upstream issued/received invoices (a calculation source resolved through the source mesh) have been updated since approval.

  • PRIOR_FILING_OBSERVATIONS_CHANGED – Prior filed observations in the bucket (the previous_filing carry and relation fold-in source) have been updated since approval.

  • PROFILE_ACTIVITY_CHANGED – The taxpayer profile facts that scope relation resolution (activity-start date, m111 no-retenciones attestations, declared income categories) have changed since approval.

  • CATEGORY_PROFILES_CHANGED – The fiscal category profile catalog has been edited since approval.

  • SCHEMA_FORMULA_CHANGED – The registry-backed casilla schema or formula set has changed since approval.

  • REVIEW_CHECKSUM_MISMATCH – The stored review_checksum is not the checksum of the stored basis. Unlike every other reason here, this does not mean an upstream source moved – it means the persisted approval metadata is internally inconsistent, so the aggregate claim over the basis is false and the approval cannot be trusted even when every basis field still matches.

APPROVAL_BASIS_VERSION_CHANGED
DRAFT_PAYLOAD_CHANGED
DRAFT_REVIEW_CHANGED
TRANSACTION_CATALOGUE_CHANGED
INVOICE_CATALOGUE_CHANGED
PRIOR_FILING_OBSERVATIONS_CHANGED
PROFILE_ACTIVITY_CHANGED
CATEGORY_PROFILES_CHANGED
SCHEMA_FORMULA_CHANGED
REVIEW_CHECKSUM_MISMATCH
compute_current_approval_basis(draft, *, bucket_id, schema_provider, ports, operation, prior_filing_observations_fingerprint=None, profile_activity_fingerprint=None, category_profiles=None)[source]

Return the ModeloApprovalBasis digests for current upstream state.

The basis hashes the draft identity and validation surface, the persisted TransactionCatalogue, the persisted InvoiceCatalogue (a calculation source resolved through the source mesh), the bucket’s prior filed observations (the previous_filing carry and relation fold-in source), the bucket’s taxpayer profile facts that scope relation resolution, the supplied or bundled CategoryProfile mapping, and the active registry schema/formula surface exposed by schema_provider.

The invoice-catalogue, prior-filing-observations, and profile-activity digests make an APROBADO draft stale when its upstream invoices, prior filed values, or relation-scoping profile facts change, closing the gap left by fingerprinting only the ledger transaction catalogue. Like the transaction catalogue, the prior observations, and the profile projection are read through the required ports bundle so stale detection is reproducible at refresh time without running the source mesh in the review layer.

Parameters:
Return type:

ModeloApprovalBasis

Returns:

A freshly computed ModeloApprovalBasis.

compute_review_checksum(approval_basis)[source]

Return the canonical SHA-256 hex checksum for approval_basis.

Parameters:

approval_basis (ModeloApprovalBasis) – The basis to hash.

Return type:

str

Returns:

Lowercase hex SHA-256 of the basis’s canonical JSON dump.

approval_stale_reasons(draft, *, bucket_id, schema_provider, ports, operation, prior_filing_observations_fingerprint=None, profile_activity_fingerprint=None, category_profiles=None)[source]

Return the ordered stale reasons for draft.

The return value is empty when the draft has no approval metadata or when its stored approval basis still matches the freshly recomputed basis.

Parameters:
Return type:

tuple[ModeloApprovalStaleReason, ...]

Returns:

Tuple of ModeloApprovalStaleReason values in evaluation order; empty when the basis is fresh.

approve_draft(draft, *, bucket_id, approved_by, schema_provider, ports, operation, prior_filing_observations_fingerprint=None, profile_activity_fingerprint=None, category_profiles=None, approved_at=None)[source]

Stamp approval metadata on draft and promote it to APROBADO.

Parameters:
Return type:

ModeloDraft

Returns:

A new ModeloDraft with approval metadata populated.

Raises:

ModeloDraftError – When approved_by is blank or the draft is not in ModeloDraftStatus.LISTO_PARA_PRESENTAR.

refresh_review_status(draft, *, bucket_id, schema_provider, ports, operation, prior_filing_observations_fingerprint=None, profile_activity_fingerprint=None, category_profiles=None, refreshed_at=None)[source]

Return draft with its approval status synchronised to current state.

Downstream-status drafts (submitted / acknowledged / rejected / amended / cancelled) get any leftover approval metadata cleared so historical state cannot pretend to be current. APROBADO drafts transition to ModeloDraftStatus.APROBACION_CADUCADA when approval_stale_reasons() returns a non-empty tuple.

Parameters:
Return type:

ModeloDraft

Returns:

Either draft unchanged (when no transition was needed) or a new ModeloDraft with the appropriate status update.

describe_stale_reason(reason)[source]

Return a short localized explanation for reason.

Parameters:

reason (ModeloApprovalStaleReason) – The ModeloApprovalStaleReason to describe.

Return type:

str

Returns:

A localized phrase suitable for inline UI display.