cadrumo.application.overview.home module

Pure composition of the frontend-neutral Home projection.

The composer accepts results that have already been read by the application composition root. It does not resolve repositories, contact AEAT, or import a frontend. Zone availability is supplied alongside those results so absence is never silently presented as a known empty collection or zero count.

HOME_ACTION_REASON_CODES: tuple[str, ...]

Complete finite vocabulary for Home next-action reason labels.

class HomeAvailability(*values)

Bases: StrEnum

Whether one Home zone can make an authoritative claim.

AVAILABLE

LOCKED

STALE

NEVER_CAPTURED

UNAVAILABLE

class HomeSessionPosture(*values)

Bases: StrEnum

Local profile-custody posture for the current TUI session.

NO_PROFILE

LOCKED

ACTIVE

EXPIRED

class HomeDeclarationState(*values)

Bases: StrEnum

Closed operator-facing lifecycle for a resumable declaration.

DRAFT

NEEDS_REVIEW

READY

FILED

DISCARDED

class HomeTargetKind(*values)

Bases: StrEnum

Which Home zone a selected row came from.

One vocabulary that the production Home screen and the devtools candidate prototypes had each written out. The three members are the three selectable zones of HomeProjectionV1, so the projection that defines those zones is where the vocabulary belongs; a frontend that restates it can disagree with the projection it renders.

ACTION

A row from the next-action zone.

DECLARATION

A row from the resumable-declaration zone.

AGENDA

A row from the agenda zone.

class HomeZoneState(**data)

Bases: BaseModel

Authority and freshness state shared by every Home zone.

Parameters:

data (Any)

availability: HomeAvailability

observed_at: datetime | None

reason_code: str | None

missing_profile_paths: tuple[str, ...]

Profile paths whose absence is the reason, when the reason is one.

A zone refused because the profile is incomplete must name what to fill in; a reason code alone sends the operator to guess which of dozens of fields the refusal meant.

class HomeAccountSession(**data)

Bases: BaseModel

Non-secret account identity and local custody posture for the header.

Parameters:

data (Any)

posture: HomeSessionPosture

profile_label: str | None

expires_at: datetime | None

class HomeNextAction(**data)

Bases: BaseModel

Application-ranked action shown without frontend-owned urgency logic.

Parameters:

data (Any)

rank: NonNegativeInt

action: DeclaredNextAction

reason_code: str

modelo: ModeloId | None

filing_year: FilingYear | None

period: Period | None

class HomeDeclarationResume(**data)

Bases: BaseModel

Natural declaration address and current revision state for resumption.

Parameters:

data (Any)

work_unit_id: WorkUnitId

modelo: ModeloId

filing_year: FilingYear

period: Period

name: str

state: HomeDeclarationState

revision_id: RevisionId | None

class HomeLedgerReadiness(**data)

Bases: BaseModel

Ledger quality counts; zone availability decides whether zero is known.

Parameters:

data (Any)

entries: NonNegativeInt

requiring_review: NonNegativeInt

unclassified: NonNegativeInt

missing_evidence: NonNegativeInt

class HomeAgendaEntry(**data)

Bases: BaseModel

One legal filing date with independent local and observed-AEAT axes.

Parameters:

data (Any)

modelo: ModeloId

filing_year: FilingYear

period: Period

due_on: date

period_state: OverviewPeriodState

local_filing_state: OverviewLocalFilingState

aeat_submission_state: OverviewAeatSubmissionState

class HomeProjectionV1(**data)

Bases: BaseModel

Complete immutable input rendered by Home; it performs no reads itself.

Parameters:

data (Any)

generated_at: datetime

account: HomeAccountSession

actions_state: HomeZoneState

actions: tuple[HomeNextAction, ...]

declarations_state: HomeZoneState

declarations: tuple[HomeDeclarationResume, ...]

ledger_state: HomeZoneState

ledger: HomeLedgerReadiness | None

agenda_state: HomeZoneState

agenda_evidence_state: HomeZoneState

agenda: tuple[HomeAgendaEntry, ...]

messages_state: HomeZoneState

messages_requiring_attention: NonNegativeInt | None

class HomeProjectionInput(**data)

Bases: BaseModel

Already-local reader results and explicit authority state for Home.

Parameters:

data (Any)

generated_at: datetime

account: HomeAccountSession

actions_state: HomeZoneState

actions: tuple[HomeNextAction, ...]

declarations_state: HomeZoneState

declarations: tuple[HomeDeclarationResume, ...]

ledger_state: HomeZoneState

ledger_readiness: HomeLedgerReadiness | None

agenda_state: HomeZoneState

agenda_evidence_state: HomeZoneState

overview_agenda: OverviewAgenda | None

messages_state: HomeZoneState

messages_requiring_attention: int | None

compose_home_projection(source)

Compose one immutable Home snapshot from canonical local read models.

Return type:

HomeProjectionV1

Parameters:

source (HomeProjectionInput)