aeat.application.operator_surface._crud_contract module

Standardized CRUD verb contract for mutating noun-groups.

Locks the canonical five-verb mutating-noun-group shape (add/remove/update/view/list). Every operator-facing CLI domain that exposes an edit work surface over persisted records (ledger transactions, purchase invoice evidence, payable and collectible invoices, profile values, auth providers, apoderado configuration, inventory rows, bucket records, usage ratios) must satisfy this contract or declare an explicit exception.

The reference shape is the aeat app ledger evidence verb group: five CRUD verbs with strict semantics. Orthogonal-axis verbs and lifecycle-state verbs remain at the noun-group level but are explicitly demoted to sub-verbs, not CRUD substitutes. Key-value-as- record noun-groups adopt a documented set/get/unset exception where records are conceptually keyed scalars rather than entities.

class CrudVerb(*values)[source]

Bases: StrEnum

Canonical five-verb spine for mutating noun-groups.

ADD
REMOVE
UPDATE
VIEW
LIST
CANONICAL_CRUD_VERBS: frozenset[CrudVerb]

The five-verb canonical CRUD set every strict noun-group must register.

A MutatingNounGroupContract with exception=STRICT_CRUD must declare exactly these five verbs. Tests assert against this constant so any future CrudVerb addition surfaces immediately as a contract drift.

class BucketEventSuffix(*values)[source]

Bases: StrEnum

Canonical bucket event suffixes emitted by mutating CRUD verbs.

Every mutating verb in a noun-group must emit a bucket event whose name ends with one of these suffixes (e.g. payable_invoice.created, profile.updated). Read verbs (view, list) emit no event. Lifecycle-state verbs use state-specific suffixes documented per noun-group rather than these CRUD suffixes.

CREATED
REMOVED
UPDATED
event_suffix_for(verb)[source]

Return the BucketEventSuffix for verb, or None for read verbs.

Return type:

BucketEventSuffix | None

Parameters:

verb (CrudVerb)

class OrthogonalAxis(*values)[source]

Bases: StrEnum

Axes that operate on existing noun-group records without lifecycle change.

Orthogonal-axis verbs are NOT CRUD substitutes. They stay at the noun-group level alongside the canonical CRUD spine and operate on records the spine materialised.

CLASSIFY
ALLOCATE
ATTACH
CHECK
PREFLIGHT
RECONCILE
class LifecycleStateVerb(*values)[source]

Bases: StrEnum

State-transition verbs distinct from CRUD lifecycle.

Lifecycle-state verbs move a record between named states with distinct semantics. They emit state-specific bucket events (e.g. modelo.work_unit.discarded) rather than the CRUD suffixes and do not collapse into remove or update.

ARCHIVE
STASH
RESET
DISCARD
class KeyValueVerb(*values)[source]

Bases: StrEnum

Documented exception for key-value-as-record noun-groups.

Where records are conceptually keyed scalars rather than entities (profile values, usage ratios, configuration keys), the canonical CRUD shape adapts: add``→``set KEY VALUE, remove``→``unset KEY, update``→``set KEY VALUE (idempotent), view``→``get KEY, list``→``list [--prefix PREFIX].

SET
GET
UNSET
LIST
class NounGroupExceptionKind(*values)[source]

Bases: StrEnum

Categories of documented deviation from the strict CRUD spine.

STRICT_CRUD
KEY_VALUE_AS_RECORD
LIFECYCLE_OPERATIONS_ONLY
class MutatingNounGroupContract(**data)[source]

Bases: BaseModel

Contract describing a single mutating noun-group’s canonical shape.

Every noun-group that exposes an edit work surface registers a contract instance. CLI Typer-graph conformance tests and runtime invariant tests consume the registered contract to assert the noun-group’s verb set is canonical or carries a documented exception.

Parameters:
noun: str
cli_path: str
exception: NounGroupExceptionKind
crud_verbs: frozenset[CrudVerb]
key_value_verbs: frozenset[KeyValueVerb]
orthogonal_axes: frozenset[OrthogonalAxis]
lifecycle_state_verbs: frozenset[LifecycleStateVerb]
declares_crud()[source]

Return True iff this noun-group exposes the strict CRUD spine.

Return type:

bool

all_verb_names()[source]

Return every registered verb name across CRUD, key-value, orthogonal, lifecycle axes.

Return type:

frozenset[str]

class CrudContractCatalogue(**data)[source]

Bases: BaseModel

Catalogue of every mutating noun-group’s registered contract.

The catalogue is the source of truth for cross-cutting CLI conformance checks. Tests assert every Typer noun-group app present in the CLI layer has a matching catalogue entry, and that its registered verb set matches the contract.

Parameters:

entries (tuple[MutatingNounGroupContract, ...])

entries: tuple[MutatingNounGroupContract, ...]
find(cli_path)[source]

Return the MutatingNounGroupContract for cli_path, or None if not registered.

Parameters:

cli_path (str) – The Typer mount path to look up (e.g. "aeat app ledger invoice").

Return type:

MutatingNounGroupContract | None