aeat.application.operator_surface._models module

Strict Pydantic records for the backend-owned operator-surface contract.

The records describe accepted RootSurface values, curated HelpDocument / RootLandingReport presentation documents, mounted MountedCommandFamily declarations, parser-only BindingSourceKind aliases, backend ServiceOwner inventory, stable OperatorSurfaceLogFields, and the aggregate OperatorSurfaceContract built by build_operator_surface_contract(). They are data contracts only; builders and renderers live in sibling modules.

S538 invariant-guard classification note

All ValueError raises in this module appear inside Pydantic v2 @field_validator / @model_validator methods. Pydantic wraps these into pydantic.ValidationError automatically; raising any other exception type (including core.errors.AeatError) would bypass that wrapping and surface as an uncaught internal exception. These guards are therefore developer-surface-only invariants and must remain ValueError. They are NOT operator-facing errors and do not require translated_message.

class RootSurfaceName(*values)[source]

Bases: StrEnum

Accepted root command surfaces enforced by OperatorSurfaceContract.

CONFIG
APP
class ModeloLifecycleStep(*values)[source]

Bases: StrEnum

Canonical modelo lifecycle steps carried by LifecycleContract.

CALCULATE
VERIFY
FILE
class FilingStatus(*values)[source]

Bases: StrEnum

Canonical live-read filing token used by mounted live command families.

FILED
class OperatorMutability(*values)[source]

Bases: StrEnum

Side-effect class declared on each MountedCommandFamily.

READ_ONLY
LOCAL_STATE_MUTATING
class HelpSurface(*values)[source]

Bases: StrEnum

Curated help surfaces accepted by build_help_document().

ROOT
CONFIG
APP
class MountedCommandDomain(*values)[source]

Bases: StrEnum

Backend-owned command domains used to classify mounted command families.

FIRST_RUN
PROFILE
CUSTODY
BUCKET
AUTH
DIAGNOSTICS
GOOGLE
COLLAB
OVERVIEW
LEDGER
LIVE
MODELO
REVIEW
REGISTRY
CONTRACT
AGENT
QUICKFILE
class RootSurface(**data)[source]

Bases: BaseModel

Backend ownership record for an accepted root surface.

Instances are declared in ACCEPTED_ROOTS and validated into the aggregate OperatorSurfaceContract. The required_children field names required command-family children, not an exhaustive command tree.

Parameters:
name: RootSurfaceName
purpose: str
owns_storage_maintenance: bool
owns_operational_workflow: bool
required_children: tuple[str, ...]
class HelpEntry(**data)[source]

Bases: BaseModel

One localized command row in a curated HelpSection.

Parameters:

  • command (str)

  • description (str)

command: str
description: str
class HelpSection(**data)[source]

Bases: BaseModel

One workflow-ordered section in a curated HelpDocument.

Parameters:
title: str
entries: tuple[HelpEntry, ...]
class HelpDocument(**data)[source]

Bases: BaseModel

Curated help document built by build_help_document().

The document owns contributor-facing command inventory and localized prose shape for a HelpSurface; renderers preserve the section and entry ordering rather than rediscovering command rows.

Parameters:
surface: HelpSurface
heading: str
paragraphs: tuple[str, ...]
sections: tuple[HelpSection, ...]
footer: str
class RootLandingReport(**data)[source]

Bases: BaseModel

Bare-root landing report built from caller-projected profile state.

build_root_landing_report() creates this record from an already-resolved profile display label. The model carries the message and next command only; it does not perform profile discovery.

Parameters:

  • active_profile (str | None)

  • command (str)

  • message (str)

active_profile: str | None
command: str
message: str
class LifecycleContract(**data)[source]

Bases: BaseModel

Modelo lifecycle vocabulary and live-submission safety contract.

The default internal_filed_term and disabled live-submission fields keep operator copy aligned with the accepted workflow: calculate, verify, then internally file/export without implying live AEAT submission.

Parameters:
steps: tuple[ModeloLifecycleStep, ...]
internal_filed_term: str
live_submission_enabled: bool
live_submission_wording: str
class SourceKindAlias(**data)[source]

Bases: BaseModel

Input-only parser alias mapped to canonical BindingSourceKind.

Alias resolution is owned by resolve_source_kind_alias(); no operator-only source-kind enum is introduced here.

Parameters:
alias: str
canonical: BindingSourceKind
class MountedCommandFamily(**data)[source]

Bases: BaseModel

One accepted command-family declaration and its backend owner.

Families bind a root surface, child token, domain, backend service owner, curated command tuple, and OperatorMutability. The command tuple is a contract summary used by help/conformance checks, not a replacement for live command-tree traversal.

Parameters:
domain: MountedCommandDomain
root: RootSurfaceName
child: str
operator_question: str
service_owner: str
commands: tuple[str, ...]
mutability: OperatorMutability
class ServiceOwner(**data)[source]

Bases: BaseModel

Application/domain package that owns an operator-facing capability.

Parameters:
capability: str
owner: str
notes: str
class OperatorSurfaceLogFields(**data)[source]

Bases: BaseModel

Stable non-secret log fields emitted by operator-surface services.

Parameters:

  • contract_name (str)

  • root_count (int)

  • lifecycle (str)

  • source_kind_count (int)

contract_name: str
root_count: int
lifecycle: str
source_kind_count: int
as_extra()[source]

Return a logging extra payload with stable field names.

Return type:

Mapping[str, object]

class OperatorSurfaceContract(**data)[source]

Bases: BaseModel

Complete backend-owned contract consumed by CLI adapters.

Built by build_operator_surface_contract(), this record ties together accepted roots, modelo lifecycle vocabulary, canonical BindingSourceKind subset, parser aliases, mounted command families, backend ownership inventory, log metadata, and registered error codes.

Parameters:
schema_version: str
roots: tuple[RootSurface, ...]
lifecycle: LifecycleContract
source_kinds: tuple[BindingSourceKind, ...]
source_kind_aliases: tuple[SourceKindAlias, ...]
command_families: tuple[MountedCommandFamily, ...]
service_owners: tuple[ServiceOwner, ...]
log_fields: OperatorSurfaceLogFields
error_codes: tuple[str, ...]