cadrumo.application.user_profile.preflight module

Preflight service: which schema fields a given modelo/revision needs.

ProfilePreflightService inspects the schema’s model_selectors against a UserProfileRecord and returns a ProfilePreflightReport listing every required field that the record does not yet carry.

build_profile_preflight_requirement(path, *, schema, selector=None, grounding_index=None)[source]

Build one requirement row for a profile path, enriched with a label and grounding.

The shared builder behind every ProfilePreflightRequirement this package or application.modelo’s profile readiness gate constructs - the schema-required walk in ProfilePreflightService.report(), its export-identity and conditional-requirement branches, and the modelo-work baseline/validation checks in _profile_readiness_gate.py all route through this one function rather than maintaining parallel implementations.

path is reduced to its declared section.field form via section_field_key() before lookup, so a repeatable-row path (activities.0.iae_epigraph) and a bare non-dotted validation code both resolve correctly. The label is the locale-catalogue operator label (falling back to the field’s declared description, never a raw dotted path) when the reduced path names a real schema field; otherwise it falls back to selector or path itself. The schema-declared legal_refs come from the field definition; the registry-binding-derived legal_refs and modelos come from grounding_index when the reduced path is a known source = "profile" binding key. A path absent from either source contributes nothing to that source - never a fabricated value. modelos is always the grounded registry union, never the modelo the caller happens to be checking - the two are different facts and must not be conflated under one field.

Return type:

ProfilePreflightRequirement

Parameters:
format_profile_preflight_requirement(requirement)[source]

Render one requirement row as label (legal_ref, legal_ref).

The single operator-facing rendering of a missing profile requirement, shared by every surface that names one: the modelo work readiness gate’s refusal, the overview calendar/agenda/backlog refusals, and the data inventory checklist’s unresolved-coefficient warning.

Falls back to the bare label when the field carries no legal grounding - never a raw dotted path once a label is available, and never an invented citation when none is declared.

Return type:

str

Parameters:

requirement (ProfilePreflightRequirement)

format_profile_selector_requirements(selectors, *, schema, grounding_index=None)[source]

Render declared selector tokens as grounded requirement text, in order.

Bridges the surfaces that hold a model_selectors TOKEN - a deadline-engine gating key, a registry binding’s consumed profile key - rather than a section.field path, which is what build_profile_preflight_requirement() resolves.

A token the schema resolves to exactly one field is rendered as that field’s operator label with its legal grounding. A token the schema does not resolve - because it names no field, because two fields declare it, or because it belongs to another namespace entirely, such as a warning code that is not a profile field at all - is passed through unchanged. Callers mix both kinds in one stream, and a token rendered verbatim is the behaviour that surface already has, whereas a guessed label would be confidently wrong.

Return type:

tuple[str, ...]

Parameters:
format_profile_path_requirements(paths, *, schema, grounding_index=None)[source]

Render profile PATHS as grounded requirement text, in order.

The path-shaped sibling of format_profile_selector_requirements(). The distinction is not cosmetic and the two are not interchangeable: a registry binding names the profile fact it consumes by its section.field PATH, whereas the deadline engine’s completeness gate names its fields by their declared model_selectors TOKEN. Routing binding keys through the selector lookup resolves nothing, so every key passes through unchanged and the rendering is silently a no-op.

build_profile_preflight_requirement() already reduces a path to its declared form, so a row-indexed path resolves here too. A path naming no schema field - a derived-selector pattern expanded for a filing year, for instance - keeps its own text, since there is no label to show for it.

Return type:

tuple[str, ...]

Parameters:
class ProfilePreflightService(*, schema)[source]

Bases: object

Resolve required profile selectors for a given (modelo, revision, year, period).

The service inspects the loaded schema’s model_selectors and schedule_predicates declarations. Today every required field whose model_selectors reference the target modelo is considered required; revision-specific filtering will land alongside the registry-time selector inventory work.

Parameters:

schema (ProfileSchemaDefinition)

report(*, record, modelo, revision_id, period, revision=None, operation=None)[source]

Compute missing required profile fields for the given filing context.

Walks every section and field in the schema. A field is considered required for this filing when field.required is true and at least one of its model_selectors has the prefix modelo_<modelo>. Facts already present on record are excluded from the missing list.

Parameters:

  • record (UserProfileRecord) – The caller’s current UserProfileRecord.

  • modelo (str) – Numeric modelo identifier (e.g. "303").

  • revision_id (TypeAliasType) – Revision tag from the registry (e.g. "2024-0A").

  • period (Period) – Typed filing period.

  • revision (ModeloRevision | None) – Optional ModeloRevision whose export layouts contribute filing-grade declarant identity requirements.

  • operation (PinnedAuthorityOperation | None) – Optional pinned authority operation used to union each missing field’s grounding with every consuming source = "profile" registry binding’s legal_refs and modelos, via build_profile_grounding_index(). When omitted, grounding falls back to the schema field’s own legal_refs only - nothing is invented.

Return type:

ProfilePreflightReport

Returns:

A ProfilePreflightReport with ready=True when all required fields are present, or ready=False with the missing list populated.

per_operation_requirements_assessed reports whether the per-modelo walk described above selected any field at all. The shipped schema declares grounded modelo_ selectors only for Modelo 036, 100 and 303, and among those only identity.tax_id (Modelo 100) is also schema-required - every other tokenised field is optional, so it is never selected by this walk. The flag is therefore true for Modelo 100 and false for every other modelo, including 036 and 303, where ready reflects only the export-identity and conditional checks. A false value means nothing schema-required was examined for that modelo; it MUST NOT be rendered as a clean bill of health.