Module capacity 

Juridical capacity & state-transition (§18, legal_logic.md).

Obligations and stipulations are only valid if the asserting agent had the legal/cognitive capacity to form them. This module is a conservative engine over the existing guardianship ontology vocabulary (values:juridicalCapacity, CoercedConsentFlag, VoidableStipulation, values:guardian, survivesDeath) — it wires terms Timothy already coined; it does not invent new sensitive vocabulary.

Handled with gravity, two deliberate semantic choices (both from the spec, both the legally-careful reading — flagged here, not silently assumed):

• Duress → VOIDABLE, not void. A stipulation made under coercion is voidable at the victim’s election — it is NOT automatically nullified. Auto-nullifying would strip the victim of the choice to keep or undo it. (◇Void, not Void.)
• Guardianship carries the dependent’s weight, it does not replace the dependent. A guardian acts on behalf of the dependent; the legal weight is the dependent’s.

Enums

CapacityStatus

An agent’s juridical capacity for an act.

Functions

authorized_after_revocation

Authority after cascading revocation: a guardian may act in requested_domain iff it is authorized AND not present in the revoked_domains set (revocation withdraws it immediately).

capacity_from_age

Derive capacity from age against a jurisdiction threshold: below majority → Impaired (minority); at/above → Intact. Coercion is layered separately (capacity_under_pressure).

capacity_under_pressure

Capacity under relational pressure: an otherwise-Intact agent whose act is coerced becomes UnderDuress (voidable). Duress never upgrades an already-Impaired capacity.

chain_authorizes

A multi-link delegation chain authorizes requested_domain iff: the root holds it, every link attenuates its predecessor (subset), and the domain survives at every level (no link silently re-broadens authority). chain[0] is the root delegation; each later link is a sub-delegation. Zero-heap (slice of slices).

decayed_impairment

A transient impairment decaying linearly toward zero — a conservative clearance model (e.g. intoxication). initial is the level in [0,1] at t0; rate is decay per elapsed time unit. Returns the clamped residual level at elapsed units.

delegation_attenuates

Attenuation: a sub-delegation’s child_domains are valid only if a SUBSET of the delegator’s parent_domains — a delegatee never receives more authority than the delegator holds. (Empty child set trivially attenuates.)

detect_duress

Map a relational power-imbalance signal to a duress finding. imbalance is a normalised [0,1] measure of relational asymmetry (dependency / authority / economic capture); an explicit_threat forces duress regardless. At/above threshold, or under an explicit threat, the act is coerced → the resulting stipulation is voidable (never auto-void; the election stays with the victim — see module header).

effective_principal

Guardianship / delegation: when a guardianship relation holds, a guardian’s act carries the dependent’s legal weight (values:actsOnBehalfOf). Returns the identity whose weight the act bears — the dependent under guardianship, else the actor themselves.

effective_principal_scoped

Domain-scoped effective principal: a guardian’s act carries the dependent’s weight ONLY within a delegated domain; outside the delegated set the guardian cannot bind the dependent (the act falls back to the actor’s own weight).

guardianship_authorized

Selective delegation: authorized_domains enumerate exactly the domains of agency delegated to a guardian. The guardian may act in requested_domain iff it is among them — no domain ⇒ no authority (selective, never plenary).

meets_age_of_majority

Does age_years meet a jurisdiction’s majority_age? The threshold is supplied by the caller (jurisdiction-specific — 18 in most, 21 in some, mental-health-act variations) so the engine never bakes one jurisdiction’s law in as universal.

posthumous_standing

Posthumous standing: a representative may prosecute the surviving claims of a deceased agent (BreachRecord(survivesDeath) + representative standing). True iff the agent is deceased AND a representative stands for them.

stipulation_binding

A stipulation by the agent is binding only when capacity is Intact.

stipulation_voidable

A stipulation made UnderDuress is voidable at the victim’s election (CoercedConsentFlag → VoidableStipulation). Returns true iff the agent may elect to void it — NOT that it is already void (that choice stays with the victim).

transient_capacity

Capacity under a transient impairment: while the decayed level is at/above threshold the agent is Impaired; once it decays below, capacity self-clears to Intact. Distinct from durable incapacity (which does not decay).