symfonic.services.effects.errors¶
errors ¶
The effect-fence error taxonomy (EFX).
Each class answers a different operational question, because each leads to a different response: "could this invocation not get a lease at all?" (the generation moved, or a fence already covers it — do not retry blindly), "did a live lease go invalid mid-run?" (cancellation applies), "did a fence stop an effect at dispatch?" (the effect never left; nothing to compensate), "is the lease backend unreachable?" (fail closed, and say so in the incident), "is this port outside the classification?" (a hole in the evidence, not a permission), "does this irreversible port lack an approved compensation rule?" (block cutover).
A caller that had to parse a message to tell those apart would eventually parse it wrong, so they are types.
EffectFenceError ¶
Bases: SymfonicError
Root of the effect-admission taxonomy. Never raised directly.
FencedEffectError ¶
Bases: LeaseInvalidError
EFX-F-3 — a fence covered this operation at one of its checkpoints.
A subclass of :class:LeaseInvalidError because a fence is one specific
way a lease stops authorizing effects, and because a revert revokes the
leases it fences: both conditions are true afterwards, and a caller that
only cares "may I proceed?" should not have to catch two types to find
out. A caller that does care — an incident writer distinguishing "the
fence stopped it" from "the lease aged out" — catches this one first.
IncompleteFenceCoverageError ¶
Bases: ConfigurationError
A classified effect port has no reversibility verdict.
A ConfigurationError on purpose: the fence's coverage of T2.3.7's
table is a build-time property, and a gap is a misconfiguration adopters
already catch in that taxonomy.
LeaseAcquisitionError ¶
Bases: EffectFenceError
EFX-L-1 — the conditional write that would grant a lease did not hold.
The bundle's epoch moved, or a fence already covers the requested generation or subject. Fail-closed: no lease, no effect.
LeaseInvalidError ¶
Bases: EffectFenceError
A lease that existed is no longer usable: revoked, expired, or superseded.
EFX-L-3 and EFX-L-5 both land here, because the invocation's next effect attempt is denied identically in either case.
LeaseStoreUnavailableError ¶
Bases: EffectFenceError
The lease backend could not be reached, so no fact could be established.
Not a denial of a known state — an inability to know one. The fence treats it as denial anyway (SEC-FCP-1) and records the degradation.
UnapprovedCompensationError ¶
Bases: ConfigurationError
An irreversible port has no tested, approved compensation rule.
Raised at registration for an untested rule and at lookup for a missing one. Either way the capability does not cut over.
UnclassifiedEffectPortError ¶
Bases: EffectFenceError
SEC-FCP-5 precedent — an effect port carries no fence row.
An unclassified port is not "probably reversible". It is a hole in the evidence, and the operation that found it is denied.