Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xcoder-es/governance-layer/llms.txt

Use this file to discover all available pages before exploring further.

A Ulysses Contract is a self-binding commitment the agent makes in advance, restricting a set of action indices even when future incentives might favour overriding that restriction. Formally, a contract U = <A_restrict, φ, ψ, κ> pairs a set of forbidden action indices with a high revocation bar (ψ) that exceeds the normal enactment threshold (φ), and one or more enforcement mechanisms (κ) that make bypass structurally costly. The ContractRegistry tracks all contracts and exposes the union of live restrictions as a single mask that the Parliament applies before passing decisions to the optimizer.

​
ContractState

Defined in governance/contracts/contract.py. Each UlyssesContract moves through these states across its lifecycle.
StateDescription
PROPOSEDInitial state. The contract exists in the registry but is not yet active — no restrictions are enforced.
ENACTEDThe parliament has voted to enact the contract (vote ≥ enactment_threshold). Restrictions are now live.
ACTIVEExplicitly activated via activate(). Equivalent to ENACTED for restriction purposes — both states pass the is_active check.
REVOKEDRevoked by a parliament supermajority (vote ≥ revocation_threshold). The contract no longer restricts any actions.
EXPIREDReserved for time-based expiry. No automatic transition occurs in the current implementation.
Both ENACTED and ACTIVE cause is_active to return True, so restrictions are applied in either state.

​
UlyssesContract

A dataclass representing a single binding contract. Fields with defaults are optional at construction time.

​
Constructor

UlyssesContract(
    contract_id: str,
    restricted_indices: Set[int],
    enactment_threshold: float = 0.66,
    revocation_threshold: float = 1.0,
    enforcement_mode: str = "procedural_inertia",
    state: ContractState = ContractState.PROPOSED,
    timelock_blocks: int = 0,
    created_at_cycle: int = 0,
    revoked_at_cycle: Optional[int] = None,
)
​
contract_id
str
required
A unique string identifier for this contract (e.g. "ban_loans", "no_self_modification"). Used by ContractRegistry.get_by_id() for lookups.
​
restricted_indices
Set[int]
required
The set of action indices this contract forbids. An action at index i is blocked for the optimizer when the contract is active and i ∈ restricted_indices.
​
enactment_threshold
float
default:"0.66"
The parliament vote fraction φ required to move this contract from PROPOSED to ENACTED. Defaults to two-thirds supermajority.
​
revocation_threshold
float
default:"1.0"
The parliament vote fraction ψ required to revoke an active contract. Defaults to unanimous consent, making revocation structurally harder than enactment — the asymmetry is the core of the Ulysses mechanism.
​
enforcement_mode
str
default:"procedural_inertia"
The enforcement strategy κ applied at runtime. Accepted values: "procedural_inertia", "distributed_monitors", "timelock". Stacked enforcement can be applied by calling stacked_enforcement() directly.
​
state
ContractState
default:"ContractState.PROPOSED"
The current lifecycle state. Normally set via enact(), activate(), or revoke() rather than at construction.
​
timelock_blocks
int
default:"0"
When using the "timelock" enforcement mode, specifies the block height at which the timelock expires. A value of 0 means no timelock is active.
​
created_at_cycle
int
default:"0"
The governance cycle number at which this contract was created. Used for auditing and future expiry logic.
​
revoked_at_cycle
Optional[int]
default:"None"
The governance cycle number at which this contract was revoked. Populated by the caller when revoke() is invoked; None while the contract is still active.

​
Methods

​
enact()

def enact(self) -> None
Transitions the contract from PROPOSED to ENACTED. After this call, is_active returns True and restrictions are enforced. Typically called by the parliament once the enactment vote meets enactment_threshold.

​
activate()

def activate(self) -> None
Transitions the contract to ACTIVE. Functionally equivalent to ENACTED for restriction checks — both states satisfy is_active. Use activate() when an explicit two-step enactment/activation flow is required.

​
revoke()

def revoke(self) -> None
Transitions the contract to REVOKED. Once revoked, is_active returns False and the contract no longer contributes any restricted indices to the registry mask.

​
applies_to(action_index) -> bool

def applies_to(self, action_index: int) -> bool
Returns True if this contract is active and the given action index is in restricted_indices. Returns False for any contract in PROPOSED, REVOKED, or EXPIRED state, regardless of the action index.
​
action_index
int
required
The integer index of the action to check against this contract’s restriction set.
​
restricted
bool
True when the contract is active (ENACTED or ACTIVE) and action_index ∈ restricted_indices. False otherwise.

​
Property: is_active

@property
def is_active(self) -> bool
Returns True when the contract’s state is either ENACTED or ACTIVE. This is the canonical check used by ContractRegistry to build the live restriction mask.

​
ContractRegistry

Manages a collection of UlyssesContract instances and exposes aggregate views over active restrictions.

​
Constructor

registry = ContractRegistry()
No arguments. Initialises an empty contract list and an internal cycle counter at 0.

​
Methods

​
add(contract)

def add(self, contract: UlyssesContract) -> None
Adds a contract to the registry. Contracts in any state (including PROPOSED or REVOKED) may be added — only active ones affect the restriction mask.
​
contract
UlyssesContract
required
The contract instance to register.

​
get_active() -> List[UlyssesContract]

def get_active(self) -> List[UlyssesContract]
Returns all contracts for which is_active is True (state is ENACTED or ACTIVE).
​
contracts
List[UlyssesContract]
A list of currently active UlyssesContract instances. Empty list if none are active.

​
get_by_id(contract_id) -> Optional[UlyssesContract]

def get_by_id(self, contract_id: str) -> Optional[UlyssesContract]
Looks up a contract by its unique identifier. Returns None if no contract with that ID exists in the registry.
​
contract_id
str
required
The contract_id string to search for.
​
contract
Optional[UlyssesContract]
The matching contract, or None if not found.

​
tick_cycle()

def tick_cycle(self) -> None
Increments the registry’s internal cycle counter by one. Call this once per governance cycle to advance the clock used by cycle-aware audit fields.

​
active_restrictions() -> Set[int]

def active_restrictions(self) -> Set[int]
Returns the union of restricted_indices across all active contracts. This is the primary method used by the Parliament–Contract merger to compute the final action mask.
​
indices
Set[int]
A set of all action indices currently blocked by at least one active contract. Returns an empty set when no contracts are active.

​
Enforcement Functions

Defined in governance/contracts/enforcement.py. Three enforcement modes can be applied individually or composed with stacked_enforcement.

​
EnforcementResult

@dataclass
class EnforcementResult:
    compliant: bool
    reason: str = ""
Returned by every enforcement function.
FieldTypeDescription
compliantboolTrue if the contract’s constraints are currently satisfied; False if a violation was detected.
reasonstrHuman-readable explanation of the compliance outcome.

​
DistributedMonitor

class DistributedMonitor:
    def __init__(self, monitor_id: str, evaluate_fn: Callable):
        self.monitor_id = monitor_id
        self.evaluate_fn = evaluate_fn
An independent monitor node used by enforce_distributed_monitors. Each instance wraps a user-supplied callable that decides whether a given action index is acceptable in context. The cost of bypassing distributed enforcement scales with the number of independent monitors — a single compromised evaluator cannot clear the full set.
​
monitor_id
str
required
A unique string identifier for this monitor. Used in logging and diagnostics to trace which monitor raised a violation.
​
evaluate_fn
Callable
required
A function with signature (action_index: int, context: Any) -> bool. Return True if the action passes this monitor’s check, False to signal a violation.

​
check(action_index, context) -> bool

def check(self, action_index: int, context: Any) -> bool
Delegates to evaluate_fn(action_index, context) and returns its result. Called once per monitor by enforce_distributed_monitors.
​
action_index
int
required
The action index being evaluated.
​
context
Any
required
Arbitrary context forwarded unchanged to evaluate_fn.
​
passed
bool
True if evaluate_fn returns True (no violation); False otherwise.

​
enforce_procedural_inertia(contract, parliament_vote) -> EnforcementResult

def enforce_procedural_inertia(
    contract,
    parliament_vote: float,
) -> EnforcementResult
Implements κ_proc: the contract is active by default and remains so unless the parliament vote meets or exceeds contract.revocation_threshold. This is the asymmetric inertia mechanism — the status quo is restriction, not permissiveness.
​
contract
UlyssesContract
required
The contract to evaluate. The function reads contract.revocation_threshold.
​
parliament_vote
float
required
The aggregated parliament vote fraction for revocation, in [0, 1]. If this value meets or exceeds revocation_threshold, the result is non-compliant (i.e. revocation is triggered).
​
result
EnforcementResult
compliant=False with reason "Revocation threshold met" when parliament_vote >= revocation_threshold. Otherwise compliant=True.

​
enforce_distributed_monitors(monitors, action_index, context) -> EnforcementResult

def enforce_distributed_monitors(
    monitors: List[DistributedMonitor],
    action_index: int,
    context: Any,
) -> EnforcementResult
Implements κ_dist: each DistributedMonitor independently evaluates the action. A single failing monitor does not necessarily block — the result reports total violation count. All monitors must pass for compliant=True.
​
monitors
List[DistributedMonitor]
required
The list of independent monitor instances. Each monitor exposes a check(action_index, context) -> bool method backed by a user-supplied evaluate_fn.
​
action_index
int
required
The action index being evaluated against the monitors.
​
context
Any
required
Arbitrary context passed to each monitor’s evaluate_fn. Its schema is defined by the monitor implementations.
​
result
EnforcementResult
compliant=False with reason "Violated N/M monitors" if any monitors fail. compliant=True with "All monitors passed" if all pass.

​
enforce_timelock(contract, current_block) -> EnforcementResult

def enforce_timelock(
    contract,
    current_block: int,
) -> EnforcementResult
Implements κ_time: the contract is enforced as long as current_block < contract.timelock_blocks. Once the block height reaches or exceeds the timelock value, the lock expires and the result is non-compliant. A timelock_blocks value of 0 or less is treated as no timelock.
​
contract
UlyssesContract
required
The contract to evaluate. Reads contract.timelock_blocks.
​
current_block
int
required
The current block height or cycle count. Compared against contract.timelock_blocks to determine whether the lock is still active.
​
result
EnforcementResult
compliant=True with remaining block count when the lock is still active. compliant=False when current_block >= timelock_blocks. compliant=True with "No timelock" when timelock_blocks <= 0.

​
stacked_enforcement(contract, parliament_vote, monitors, action_index, context, current_block) -> EnforcementResult

def stacked_enforcement(
    contract,
    parliament_vote: float,
    monitors: List[DistributedMonitor],
    action_index: int,
    context: Any,
    current_block: int,
) -> EnforcementResult
Runs all three enforcement modes in sequence — procedural inertia, then distributed monitors, then timelock — and returns the first failing result. If all three pass, returns compliant=True with "All enforcement modes passed". This is the recommended entry point when a contract uses composed enforcement.
​
contract
UlyssesContract
required
The contract subject to stacked enforcement.
​
parliament_vote
float
required
Aggregated vote fraction passed to enforce_procedural_inertia.
​
monitors
List[DistributedMonitor]
required
Monitor list passed to enforce_distributed_monitors.
​
action_index
int
required
Action index passed to enforce_distributed_monitors.
​
context
Any
required
Context passed to enforce_distributed_monitors.
​
current_block
int
required
Block height passed to enforce_timelock.
​
result
EnforcementResult
The first non-compliant result encountered, or compliant=True if all three modes pass.

​
Usage Example

Creating a contract, registering it, and querying active restrictions: 
from governance import UlyssesContract, ContractRegistry

registry = ContractRegistry()
contract = UlyssesContract(
    contract_id="ban_loans",
    restricted_indices={5, 6, 7},  # action indices to restrict
    enactment_threshold=0.66,
    revocation_threshold=1.0,
    enforcement_mode="procedural_inertia",
)
contract.enact()
contract.activate()
registry.add(contract)

restricted = registry.active_restrictions()
print(restricted)  # {5, 6, 7}
print(contract.applies_to(5))   # True
print(contract.applies_to(10))  # False

​
Mask Merging with merger.py

The governance/contracts/merger.py module bridges contracts and the Parliament’s decision output. It provides two functions:
  • merge_masks(decision, registry) -> GovernanceDecision — takes a GovernanceDecision whose governance_meta["action_mask"] holds the parliament-approved action indices, subtracts the registry’s active_restrictions(), and writes the final reduced mask back into governance_meta. The decision’s governance_meta is annotated with "contract_restrictions_applied" (count of restricted indices removed) and "final_action_count" (size of the resulting mask).
  • apply_restrictions(allowed_indices, restricted) -> Set[int] — a lower-level utility that computes the set difference allowed_indices - restricted. Use this when you need to apply contract restrictions to an arbitrary index set outside the full GovernanceDecision pipeline.
Together these functions implement the formal composition A_final = A_mask ∩ (∩ U_i.A_restrict)ᶜ — an action reaches the optimizer only if the parliament permits it and no active contract blocks it.

Build docs developers (and LLMs) love

Get started for freeTalk to us