aeat.application.state_projection module

The single canonical operator-facing state read-projection.

Every operator-facing state or readiness surface that reports “the truth” about the active profile - overview status, auth status, auth test, and modelo readiness - consumes this one projection. None of them re-derives state from a private subset of the stores.

The OperatorStateProjection is a typed, frozen pydantic model built by exactly one producer, build_operator_state_projection(). The producer loads the profile aggregate, the workspace catalogues (transactions via TransactionCatalogueRepository, invoices via InvoiceCatalogueRepository, declaration drafts via ModeloDraftRepository, modelo work units via WorkUnitCatalogueRepository, and calculation revisions via CalculationRevisionCatalogueRepository), the auth state, the active-profile health, and the deadline obligations computed from Schedule, and computes each readiness value exactly once. Modelo readiness resolves a RegistrySnapshot only to evaluate registry-declared profile, binding, and ledger preflight requirements for the requested ModeloReadinessRequest.

The projection is pure read: building it mutates no store.

Background: overview status once reconstructed workspace counters from a different store subset than modelo work writes: it read the ModeloDraft store but never the WorkUnitCatalogue or CalculationRevisionCatalogue stores, so an operator who used modelo work create / calculate saw drafts: 0. This projection carries drafts (the declaration-draft ModeloDraft store) and work_units (the WorkUnitCatalogue store) as distinct counters, so neither is silently zero.

See also

OverviewStatusReport

Overview emit shape derived from this projection, rather than from a second store assembly path.

build_overview_status_report()

Overview producer that consumes this projection instead of rebuilding workspace, auth, and deadline readiness.

AuthStatusResult

Auth emit shape that reads the same canonical configured/authenticated readiness values carried here.

inspect_operator_auth()

Auth status producer that reads ProjectionAuthReadiness and ProjectionActiveProfile from this projection.

inspect_bucket_storage_runtime()

Storage-runtime inspection used by the workspace summary without letting presentation surfaces open their own storage-reading paths.

ProjectionWorkspaceSummary

Per-store counter record that keeps declaration drafts, work units, and calculation revisions distinct.

ProjectionModeloReadiness

Per-target readiness record built from profile facts, registry snapshots, binding availability, and ledger preflight.

resolve_deadline_stage_obligation()

Filing workflow selector that filters a schedule for the workflow gate; it does not consume pending_obligations directly.

compute_obligation_schedule()

Single deadline schedule producer used for projection obligations and workflow deadline-stage checks.

RegistrySnapshot

Registry authority snapshot used to resolve modelo-readiness preflight requirements.

class ProjectionActiveProfile(**data)[source]

Bases: BaseModel

Active-profile identity and health, computed once for every surface.

This record is the projection-side form of ActiveProfileHealth. Auth and overview surfaces read these fields instead of re-running profile pointer or bucket manifest checks.

Variables:

  • profile_id – Immutable bucket UUID of the active profile, or None when no profile is active.

  • label – Operator-chosen display name of the active profile, or None when no profile is active or the label cannot be resolved.

  • health_status – The ActiveProfileHealth status string (none / dangling_pointer / incomplete / ready / …).

  • registered_bucket – Whether the active-profile pointer resolves to a registered bucket.

  • record_present – Whether the encrypted profile record loaded.

  • next_action – The operator-facing next-step command carried from assess_active_profile_health().

Parameters:

  • profile_id (str | None)

  • label (str | None)

  • health_status (str)

  • registered_bucket (bool)

  • record_present (bool)

  • next_action (str)

profile_id: str | None
label: str | None
health_status: str
registered_bucket: bool
record_present: bool
next_action: str
class ProjectionAuthReadiness(**data)[source]

Bases: BaseModel

Auth operational readiness, computed once for every surface.

The record narrows WorkflowState and provider backend health into the fields consumed by AuthStatusResult and AuthTestResult.

configured is the single canonical definition of “auth is operationally ready”: a provider is selected in workflow state and, for the certificate provider, a certificate path is recorded. Both auth status and auth test read this same field — they cannot disagree because the value is computed once here.

Variables:

  • provider – The configured (or requested) provider id, or "".

  • configured – The single canonical operational-readiness flag.

  • authenticated – Whether a live session has been recorded.

  • available – Whether the live backend reports itself reachable. auth test may probe the live backend for a fresher available reading, but it never recomputes configured.

  • health_summary – The backend-reported health summary text.

  • health_severity – A non-empty health severity token coherent with health_summary. The certificate backend’s own tokens (OK / EXPIRED / …) pass through; for a provider whose backend reports no severity the projection derives ok / warning / error from the readiness signals. Empty only when no provider is selected.

  • certificate_path – Recorded certificate filesystem reference for the certificate provider, or "". A non-certificate provider always reports "" — it never carries a stale path from an earlier certificate configuration.

Parameters:

  • provider (str)

  • configured (bool)

  • authenticated (bool)

  • available (bool)

  • health_summary (str)

  • health_severity (str)

  • certificate_path (str)

provider: str
configured: bool
authenticated: bool
available: bool
health_summary: str
health_severity: str
certificate_path: str
class ProjectionWorkspaceSummary(**data)[source]

Bases: BaseModel

Counters for every workspace store, so none is silently zero.

drafts and work_units are deliberately distinct counters: modelo file writes the declaration-draft ModeloDraft store while modelo work create / calculate write the WorkUnitCatalogue store. Calculation output is counted separately through CalculationRevisionCatalogue. A single drafts counter that read only the first store reported 0 for an operator who used the modelo work flow.

Variables:

  • transactions – Count of imported transactions.

  • invoices – Count of imported invoices.

  • drafts – Count of declaration-draft ModeloDraft entries.

  • work_units – Count of active (BORRADOR) WorkUnitCatalogue entries written by modelo work create. Discarded units are excluded so the counter is never inflated by units the operator has abandoned.

  • discarded_work_units – Count of DESCARTADO WorkUnitCatalogue entries, carried distinctly so a surface can state the active / discarded split rather than a misleading total.

  • calculation_revisions – Count of CalculationRevisionCatalogue entries written by modelo work calculate.

  • unreadable_rows – Count of secure-object rows that failed to decrypt — an integrity warning.

Parameters:

  • transactions (int)

  • invoices (int)

  • drafts (int)

  • work_units (int)

  • discarded_work_units (int)

  • calculation_revisions (int)

  • unreadable_rows (int)

transactions: int
invoices: int
drafts: int
work_units: int
discarded_work_units: int
calculation_revisions: int
unreadable_rows: int
class ProjectionObligation(**data)[source]

Bases: BaseModel

One pending filing obligation carried in the projection.

Rows are copied from the Schedule obligations produced for the active TaxpayerProfile. Workflow filing gates later select a narrower ModeloDeadline from the same schedule producer.

Variables:

  • modelo – Modelo identifier.

  • period – Typed Period for the obligation window.

  • opens_on – First day the filing window accepts submissions.

  • closes_on – Last day the filing window accepts submissions.

  • status – The engine ObligationStatus.

Parameters:
modelo: str
period: Period
opens_on: date
closes_on: date
status: ObligationStatus
class OperatorStateProjection(**data)[source]

Bases: BaseModel

The single canonical operator-facing state view.

Built by exactly one producer, build_operator_state_projection(), and consumed by every operator-facing surface. Each readiness value it carries is computed once; surfaces present these values, they never recompute.

Variables:

  • active_profile – Active-profile identity + health.

  • auth – Auth operational readiness (carries the one canonical configured definition).

  • workspace – Per-store workspace counters.

  • modelo_readiness – Per-modelo preflight readiness reports, keyed by the (modelo, revision, year, period) request the caller asked for. Empty when no modelo target was supplied.

  • pending_obligations – The full, unfiltered deadline obligations for the active profile’s current year, as ProjectionObligation records. They are computed through compute_obligation_schedule(), the same schedule producer that the workflow deadline stage filters through resolve_deadline_stage_obligation(). The workflow does not consume this tuple directly; the shared invariant is producer-level schedule agreement.

Parameters:

data (Any)

active_profile: ProjectionActiveProfile
auth: ProjectionAuthReadiness
workspace: ProjectionWorkspaceSummary
modelo_readiness: tuple[ProjectionModeloReadiness, ...]
pending_obligations: tuple[ProjectionObligation, ...]
build_pending_obligations(profile, *, today)[source]

Compute the deadline obligations for the active profile.

Routes through compute_obligation_schedule(), the single producer of the pending-obligation datum also used by the workflow deadline stage. This function projects the full Schedule; the workflow gate separately filters its target ModeloDeadline through resolve_deadline_stage_obligation(). A failure to compute the schedule is logged and degrades to an empty tuple rather than failing the whole projection.

Parameters:

  • profile (TaxpayerProfile) – The TaxpayerProfile whose deadline obligations are projected.

  • today (date) – Reference date for fiscal-year selection and obligation status.

Return type:

tuple[ProjectionObligation, ...]

Returns:

The projected ProjectionObligation records.

class ModeloReadinessRequest(**data)[source]

Bases: BaseModel

One (modelo, revision, year, period) readiness target.

The projection producer accepts a tuple of these and computes one ProjectionModeloReadiness per request, so modelo readiness never builds its own profile, registry, binding, or ledger preflight pass.

Variables:

period – Typed Period scoping the readiness check, or None when the caller omits the period (the projection uses the annual 0A period for registry and ledger preflight resolution).

Parameters:
modelo: str
revision_id: str
filing_year: int
period: Period | None
class ProjectionModeloBindingRequirement(**data)[source]

Bases: BaseModel

One registry calculation binding readiness cannot currently satisfy.

These are non-constant binding declarations from the resolved RegistrySnapshot that are not supplied by profile binding resolution, enum/date helpers, or a successful ledger preflight. The parent ProjectionModeloReadiness carries these rows as operator-facing missing input requirements.

Parameters:

  • binding_id (str)

  • source (str)

  • input_channel (str)

binding_id: str
source: str
input_channel: str
class ProjectionModeloReadiness(**data)[source]

Bases: BaseModel

Readiness for one modelo target across all preflight axes.

The projection combines profile requirements, registry-snapshot availability, calculation binding resolution, and ledger preflight into one emit shape. ready is true only when every axis is ready; a LedgerPreflightIssue blocks readiness only when the resolved RegistrySnapshot declares ledger-backed bindings.

Variables:

  • profile_id – Active ProfileId used for the readiness report.

  • modelo – Modelo identifier from the ModeloReadinessRequest.

  • revision_id – Registry revision requested or resolved for this target.

  • filing_year – Filing year used to resolve registry and profile requirements.

  • missing – Profile fields still required by the ProfilePreflightReport.

  • profile_refusal – Operator-facing refusal when profile facts are present but disqualify the target period.

  • registry_ready – Whether the requested modelo/year/period/revision resolved to a usable registry snapshot.

  • registry_refusal – Operator-facing explanation when registry resolution failed.

  • binding_ready – Whether every non-constant registry binding can be supplied by the current profile or ledger state.

  • missing_bindings – Missing ProjectionModeloBindingRequirement records for unresolved calculation inputs.

  • period – Typed Period the readiness check was scoped to.

  • ledger_preflight_required – Whether the registry declares any ledger aggregation binding requiring ledger preflight.

  • ledger_ready – Ledger-preflight verdict, or None when no ledger preflight was required.

  • ledger_period – The Period the ledger preflight was scoped to, or None when no ledger preflight was run.

  • ledger_issues – Blocking LedgerPreflightIssue rows.

Parameters:
profile_id: ProfileId
modelo: str
revision_id: str
filing_year: int
period: Period
missing: tuple[ProfilePreflightRequirement, ...]
profile_ready: bool
profile_refusal: str
registry_ready: bool
registry_refusal: str
binding_ready: bool
missing_bindings: tuple[ProjectionModeloBindingRequirement, ...]
ledger_preflight_required: bool
ledger_ready: bool | None
ledger_period: Period | None
ledger_checked_transaction_count: int
ledger_issues: tuple[LedgerPreflightIssue, ...]
ready: bool
modelo_requires_ledger_preflight(request)[source]

Return whether a modelo readiness target requires ledger preflight.

An unresolved registry snapshot is treated as “not required” for this predicate and logged at DEBUG; the full readiness projection reports the registry refusal through ProjectionModeloReadiness.registry_refusal after resolving the same RegistrySnapshot.

Return type:

bool

Parameters:

request (ModeloReadinessRequest)

build_operator_state_projection(*, state=None, requested_provider=None, probe_live_backend=False, include_workspace_summary=True, include_pending_obligations=True, modelo_readiness_requests=(), today=None)[source]

Assemble the one canonical operator-facing state projection.

This is the single producer of OperatorStateProjection. Every operator-facing surface calls it and reads its typed fields; no surface re-derives state.

Parameters:

  • state (WorkflowState | None) – Pre-loaded workflow state. When None and a profile is active, the state is loaded through workflow_state_repository(); when None and no profile is active, an empty WorkflowState is used (opening the bucket database would require a session that does not exist yet).

  • requested_provider (str | None) – Optional provider id the caller scoped the auth readiness to. None reports the configured provider.

  • probe_live_backend (bool) – When set, the live auth backend is queried for the available / health_* fields. configured is never sourced from the probe.

  • include_workspace_summary (bool) – When false, skip ledger, invoice, draft, work-unit, and revision counters. Auth-only surfaces use this so unrelated workspace-store corruption cannot block local auth readiness inspection; overview-style surfaces keep the default full projection.

  • include_pending_obligations (bool) – When false, skip period deadline projection. Auth-only surfaces do not render obligation rows, so they should not fail because an unrelated period-readiness path changes.

  • modelo_readiness_requests (tuple[ModeloReadinessRequest, ...]) – Optional readiness targets; one ProjectionModeloReadiness is computed per request.

  • today (date | None) – Reference date for the deadline computation. Defaults to date.today().

Return type:

OperatorStateProjection

Returns:

The fully-populated OperatorStateProjection. Building it mutates no store.