python-state-failure

name	python-state-failure
description	Fires when live state or a transport client is about to land somewhere wrong instead of the matching construct in python-state-success — frozen=True on the consistency model, a client field with no verb emitting through it, or arbitrary_types_allowed=True on any model other than the consistency model.

State — failure patterns

Three ways live state or a transport client escapes the one node allowed to hold it (the consistency model, python-state-success).

Frozen live edge

Freezing the consistency model contradicts what it is: the one node holding live clients and accumulating mutable state. Frozen, it is a different construct wearing the name.

The consistency model is the single unfrozen BaseModel of a context, with arbitrary_types_allowed=True, clients as fields, and state evolution by re-pointing a field to a newly constructed proven fact. A frozen domain composite holding no client is a concept model, not this.

class MarketSession(BaseModel, frozen=True):   # the consistency model is unfrozen; drop frozen=True and add arbitrary_types_allowed=True
    book: CoinbaseBook

Dead handle

A client held on the consistency model but reached by no verb is a capability wired to nothing: structure with no act crossing through it.

Every client field exists for a verb that crosses through it. A verb is a state transition on the consistency model that may emit the constructed fact through a client field; a client no verb touches names no transition and belongs nowhere, or its verb is missing and must be modeled.

class MarketSession(BaseModel):
    coinbase: CoinbaseClient   # no verb ever touches self.coinbase: either a verb must emit through it, or the field is unwired structure

Arbitrary type off the edge

arbitrary_types_allowed anywhere but the one live model lets an unmodeled foreign object sit inside a value: meaning the ontology never described.

arbitrary_types_allowed is legal on the consistency model and nowhere else, because that is the one node where live clients converge. A foreign system's data shape entering a frozen value is a foreign model (python-adapters-success), named for the foreign thing, lifting whole; a live client is held only by the consistency model.

class Snapshot(BaseModel):
    model_config = ConfigDict(arbitrary_types_allowed=True)   # legal only on the consistency model
    client: SomeSDKThing   # a live client belongs on the consistency model; foreign data belongs in a foreign model