python-state-success

State

The live-node constructs: where mutable state and transport clients are allowed to exist at all. Everything in python-values-success is frozen; the consistency model is the one deliberate exception, and the binding is what wires clients into it.

Consistency Model

Definition

The single unfrozen BaseModel of a context, the one node where live clients and mutable state converge. Every state it holds is a proven fact, and state evolution is a field re-pointing to a newer proven value.

Required Form

PositionState = Annotated[Position | Flat, Field(discriminator="kind")]


class PositionConsistencyModel(BaseModel):
    model_config = ConfigDict(arbitrary_types_allowed=True)
    bus: BusClient
    ledger: LedgerClient
    latest: PositionState

    def book(self, report: VenueFill) -> None:
        self.latest = Position(prior=self.latest, fill=report)
        self.bus.publish(self.latest)
        self.ledger.append(self.latest)

PositionState is the state union: Position and Flat are the concept models declared in their own sections, each carrying the same-named exposure derivation, so exposure reads off latest with no branch. Clients are fields, state fields are declared types, and every method is a verb. arbitrary_types_allowed is legal on this class and nowhere else.

Sorting Rules

A second unfrozen model means the context is two contexts: stop and report it. Client binding belongs to the binding; the consistency model receives constructed clients as fields. A fact the state implies is a derivation on the state's model, not a method here. A frozen domain composite is a concept model.

Replaced Forms

A manager or engine is domain logic with a technology name and no proof obligation. A module-level client is the live edge escaped from the one node that may hold it. A second unfrozen model is a second convergence point for state, which is two contexts fused into one.

Construct-Specific Doctrine

State evolution is reassignment of proofs, never mutation of their contents: construct the newer proven fact and re-point the field to it. The consistency model never holds an unproven value, not even for one statement. Every non-client field is a declared type; no bare primitives, no T | None, no bool gates. Selection never happens here: construction selected the variant, the checker narrows it, and what differs by variant is read from the union value.

Allowed Patterns

• one unfrozen BaseModel per context with arbitrary_types_allowed=True, clients as fields
• every non-client field a declared type holding a proven value
• state evolution by re-pointing a field to a newly constructed fact
• verbs as the only methods

Forbidden

• a second unfrozen model in one context
• a module-level client
• match, if/elif, or isinstance anywhere in the class
• a hand-assembled dict where a constructed type belongs
• an unproven or unmodeled value held in any field
• arbitrary_types_allowed on any other class

Halt Rule

Halt when a context needs a second unfrozen model, when a client no verb reaches is demanded, or when a state field has no declared row. Report the row and the field or client: the context is mis-factored or the meaning is unmodeled, and the table is not finished.

Binding

Definition

The class whose connect method binds transport clients to the consistency model. Its entire meaning is the binding it performs: it owns no domain type, holds no domain logic, and makes no domain decision.

Required Form

class PositionBinding:
    def connect(self, bus: BusClient, ledger: LedgerClient, opening: PositionState) -> PositionConsistencyModel:
        return PositionConsistencyModel(bus=bus, ledger=ledger, latest=opening)

Sorting Rules

Domain state and domain transitions belong to the consistency model; the binding only constructs it. Client instantiation and configuration belong to the composition root; the binding receives constructed clients. Transport ingress belongs to the route; the binding handles no request.

Replaced Forms

A repository is a fetch surface given a class name; consumers read facts the consistency model's transitions establish. A computing service is domain logic that escaped the consistency model. A manager is sequencing the construction graph already owns.

Construct-Specific Doctrine

connect may perform transport setup whose signal has no domain meaning: connection, authentication, subscription, and the idempotent create-or-bind that binds the same client either way. If the domain reacts to a transport signal, the signal is modeled through the ordered union (python-adapters-success), never caught here.

Allowed Patterns

• one class whose connect accepts constructed transport clients and any opening state, and returns the constructed consistency model
• connection, authentication, and subscription setup inside connect

Forbidden

• a method that computes a domain fact
• a catch that converts a transport signal into a domain answer
• a domain type defined in the binding's file
• a repository, manager, or computing service

Halt Rule

Halt when connect would need a domain decision, a domain computation, or a catch the domain reacts to. Report the row and the signal as a modeling gap: the meaning belongs in the consistency model or the ordered union, and the table is not finished.