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

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.hierarchy.CadrumoError) 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.

OPERATOR_SURFACE_MODEL_CONFIG: ConfigDict

The one config every operator-surface record uses.

Diverges from core.models.STRICT_FROZEN_CONFIG only by adding validate_assignment, which these records need. It was previously written out as an identical literal at twelve declaration sites, and every one of them also omitted validate_default – so a guarantee the canonical makes was dropped twelve times over without anyone choosing to drop it. Named once so the divergence is a decision with a reason rather than a repeated accident.

class RootSurfaceName(*values)[source]

Bases: StrEnum

Accepted root command surfaces enforced by OperatorSurfaceContract.

CONFIG
APP
class FilingStatus(*values)[source]

Bases: StrEnum

Filing-state vocabulary a live command family reports a declaration in.

Only FILED is declared: it is the one state the operator surface contract currently asserts. Absence of a member is NOT a claim that the other states cannot occur – an unfiled, refused or pending declaration is represented by its own typed refusal at the boundary that produces it, not by a member here.

FILED

A declaration this product recorded as filed.

class ModeloLifecycleStep(*values)[source]

Bases: StrEnum

Canonical modelo lifecycle steps carried by LifecycleContract.

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

Bases: StrEnum

Side-effect class declared on each MountedCommandFamily.

READ_ONLY
LOCAL_STATE_MUTATING
class MountedCommandDomain(*values)[source]

Bases: StrEnum

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

FIRST_RUN
PROFILE
CUSTODY
BUCKET
AUTH
DIAGNOSTICS
PROVISIONING
MAINTENANCE
STORAGE
GOOGLE
COLLAB
OVERVIEW
LEDGER
LIVE
MODELO
REVIEW
REGISTRY
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 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.

A family declares only what the live command tree cannot supply: which root it hangs from, its child token, its MountedCommandDomain, the operator_question it answers, its backend service_owner, its and OperatorMutability.

It deliberately declares NO command inventory. Which verbs a family contains is established solely by the live command tree, projected once as the registered command-schema keys the manifest carries; group them with the live command reconciliation. A second, hand-authored inventory here would be a restatement of that authority, and a restatement is a thing that can disagree.

Parameters:
domain: MountedCommandDomain
root: RootSurfaceName
child: str
operator_question: str
service_owner: str
mutability: OperatorMutability
class ManifestActionProfile(**data)[source]

Bases: BaseModel

One declarative precondition outcome exposed by the operator manifest.

A profile is keyed to one live subject leaf, failed condition, and scenario. It preserves the exact condition-to-recovery association by carrying either one canonical ActionReference or one explicit NoRecoveryOutcome. The application guard remains the authority for deciding whether the condition applies; this record contains no predicate, runtime evidence, argument value, localized prose, or CLI command string.

Parameters:

  • subject_leaf_key (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=3, max_length=160, pattern=^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$, ascii_only=None)])

  • condition_id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=3, max_length=160, pattern=^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$, ascii_only=None)])

  • scenario_id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=3, max_length=160, pattern=^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$, ascii_only=None)])

  • action (ActionReference | None)

  • no_recovery_outcome (NoRecoveryOutcome | None)

subject_leaf_key: NamespacedId
condition_id: NamespacedId
scenario_id: NamespacedId
action: ActionReference | None
no_recovery_outcome: NoRecoveryOutcome | None
property identity: tuple[str, str, str]

Return the canonical live-coverage key for this declared outcome.

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 typed logging extra payload with stable field names.

Return type:

LogExtra

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, ...]