python-verbs-failure

name

python-verbs-failure

description

Fires when a model method is about to be written wrong instead of as the matching construct in python-verbs-success — a stub body (raise NotImplementedError/pass/...), a second top-level construction statement in a verb, a verb's signature drifted from its modeled row, a modeled verb missing from the class, a verb/derivation/method with no row authorizing it, an undecorated method on a frozen model, or a verb body that skips a declared constructs/emits participant.

Verbs — failure patterns

Seven ways behavior gets written wrong instead of built as a verb or derivation (python-verbs-success).

Stub verb

A verb body of raise NotImplementedError, pass, or bare ... treats the row as a signature to fill later. But the row already is the work: the placeholder is a missing expansion, not a TODO.

A verb body contains at most one construction statement, with constituents constructing inside that call; it may capture a foreign reply before the construction, re-point a state field to the constructed fact, and emit that fact through a client field. A verb that constructs, emits, and yields nothing declares no transition.

def settle(self) -> Receipt:
    raise NotImplementedError   # the row is the work: construct the Receipt and re-point the state field to it

Multiple constructions in one verb

Two or more top-level construction statements sequence the graph by hand. A verb is one state transition, which is one construction, with constituents constructing inside that single call.

The body holds at most one construction statement. A constituent the composite holds constructs inside the composite's own call, proven by coercion there; a constituent built in a separate statement beside the composite restates what the composite's call already proves.

def advance(self) -> SignalSnapshot:
    spread = Spread(...)             # one
    return SignalSnapshot(spread)    # two: construct the Spread inside the SignalSnapshot call, so the verb has one construction

Surface drifted from the verb row

The signature claims what the row did not: a missing or wrong return annotation, a yielding verb not typed as an iterator, parameters that do not match the row's accepts, or parameters where the row declared none.

The verb's surface is the row rendered exactly: the parameter is the innermost constructed value the row's accepts names, and the return annotation is the row's declared type, with a yielding verb typed as an AsyncIterator (or Iterator) of the fact it yields.

def project(self) -> dict:            # row says -> SignalSnapshot: annotate the row's declared type
def stream(self) -> SignalSnapshot:   # yields, but not typed Iterator: type it Iterator[SignalSnapshot]

Verb absent from the surface

A verb the ontology models that the class never defines: the row promised an act the code does not perform.

Every verb row renders a method on the consistency model. A modeled verb missing from the class is a transition the ontology authorized and the code never wrote; define the method the row names.

# row names `settle`; the class has no settle method: define settle as the verb its row declares

Unmodeled behavior

A verb, derivation, or consistency-model method with no row is behavior built before it was modeled. The ontology authorizes the act first, then the code performs it.

Every act traces to a row: a verb for a state transition, a derivation for a fact implied by frozen fields. Behavior the code needs that no row names is a meaning to place in the ontology before it is written.

def reconcile(self) -> Ledger: ...   # no row names this act: place the verb in the ontology first, then build it

Free method on a frozen value

A method on an immutable value that is not decorated @property, @cached_property, or @computed_field is procedure escaping where a modeled implied fact belongs.

A fact implied by a frozen value's already-proven fields is a derivation: it takes only self, its body is one returned expression, and it returns a declared type, model, or union. @property recomputes a cheap fact, @cached_property computes a costly or recursive one once, and @computed_field above @cached_property writes the fact into the contract's serialized shape.

class SignalSnapshot(BaseModel, frozen=True):
    def momentum(self) -> Momentum: ...   # undecorated: a derivation decorated @property or @cached_property, body one returned expression

Body drifted from the chain

The declared chain and the body disagree. A constructs/emits participant the body never touches is promised work undone; a value-type the chain cannot account for is unmodeled work smuggled in.

The body realizes exactly the chain the row declares: it constructs every constructs participant and emits every emits participant, and it touches no value-type the chain does not name. Work the body needs that the chain does not carry is a meaning to model in the row first.

# row: emits SignalSnapshot
def observe(self) -> None:
    self.book.ingest(tick)   # never touches the snapshot it promised: construct and emit the SignalSnapshot the chain declares