cadrumo.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 consumes the application-owned profile and workspace read ports, 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.

StateProjectionReadPorts

Required application-owned reads supplied by an outer composition root.

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.

Core types: ModeloRevision, UserProfileRecord.

class ProjectionActiveProfile(**data)

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.

• precondition_verdict – The application-owned recovery verdict carried from assess_active_profile_health().

Parameters:

data (Any)

profile_id: ProfileId | None

label: str | None

health_status: str

registered_bucket: bool

record_present: bool

precondition_verdict: PreconditionVerdict | None

class ProjectionWorkspaceSummary(**data)

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:

data (Any)

transactions: int

invoices: int

drafts: int

work_units: int

discarded_work_units: int

calculation_revisions: int

unreadable_rows: int

class ProjectionObligation(**data)

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:

data (Any)

modelo: str

period: Period

opens_on: date

closes_on: date

status: ObligationStatus

class OperatorStateProjection(**data)

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_active_profile(health)

Project one coherent profile-health snapshot into the public record.

Return type:

ProjectionActiveProfile

Parameters:

health (ActiveProfileHealth)

build_pending_obligations(profile, *, today)

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)

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:

data (Any)

modelo: str

revision_id: RevisionId

filing_year: FilingYear

period: Period | None

class ProjectionModeloBindingRequirement(**data)

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:

data (Any)

binding_id: str

source: BindingSourceKind

input_channel: str

CLAVES_LOCALE_DISPONIBILIDAD_POR_ORIGEN_VINCULACION_LOCALE_KEYS: Mapping[BindingSourceKind, str]

Total locale-key projection for the noun describing each binding source.

OPERATOR_ACTION_BY_MODELO_READINESS_BINDING_SOURCE: Mapping[BindingSourceKind, OperatorActionAxis]

Total action spine for a readiness missing_bindings source.

OPERATOR_ACTION_BY_MODELO_READINESS_LEDGER_ISSUE: Mapping[LedgerPreflightIssueReason, OperatorActionAxis]

Total action spine for readiness ledger_issues reasons.

class ProjectionModeloReadiness(**data)

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.

• per_operation_requirements_assessed – Whether the per-modelo schema-required axis (see per_operation_requirements_assessed) actually examined any field for this modelo. False means no schema-required field was checked and profile_ready reflects only the export-identity and conditional checks; it MUST NOT be rendered as a clean bill of health.

Parameters:

data (Any)

profile_id: ProfileId

modelo: str

revision_id: RevisionId

filing_year: FilingYear

period: Period

missing: tuple[ProfilePreflightRequirement, ...]

profile_ready: bool

per_operation_requirements_assessed: 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

build_operator_state_projection(*, certificate_secret_backend_factory, operator_probe_ports, operator_scope_ports, read_ports, operation, state=None, auth_snapshot=None, requested_provider=None, probe_live_backend=False, include_workspace_summary=True, include_pending_obligations=True, modelo_readiness_requests=(), today=None)

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:

• certificate_secret_backend_factory (CertificateSecretBackendFactory) – Application-owned certificate-secret backend factory used by auth readiness.

• operator_probe_ports (OperatorProbePorts) – Required inward operator-auth probe capabilities.

• operator_scope_ports (OperatorScopePorts) – Operator-scoped auth and profile capabilities.

• read_ports (StateProjectionReadPorts) – Required application-owned profile and workspace reads composed by the outer entrypoint for this profile scope.

• operation (PinnedAuthorityOperation) – Caller-owned generation-pinned authority operation used by profile health and any requested modelo readiness projection.

• 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). A caller-supplied state has no storage-route provenance, so live backend probing is suppressed rather than combining that snapshot with credentials from the current route.

• auth_snapshot (ActiveAuthProjectionSnapshot | None) – Route-witnessed auth state and credentials obtained from active_auth_projection_span(). The caller keeps that span open while this function consumes the snapshot. Mutually exclusive with state; unlike an unproven state value, the snapshot permits its witnessed credentials to feed the live backend probe.

• 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. The probe may downgrade derived authentication readiness, but it never elevates configuration.

• 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.