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.

In the myth, Ulysses knew he would be incapable of resisting the Sirens’ song — not because he lacked intelligence, but because his future self would face a temptation his present self could foresee. His solution was to bind his future self to the mast and order his sailors to ignore any future commands to change course. He voluntarily restricted his own decision space. A Ulysses Contract in the Governance Layer formalizes this same idea for artificial agents: it is a meta-policy enacted through the Neural Parliament that removes a defined set of actions from the optimizer’s feasible set, and remains active until revoked through a higher procedural bar than was required to enact it.
This is the critical design asymmetry: φ < ψ. The enactment threshold φ is strictly less than the revocation threshold ψ. A 2/3 supermajority enacts a contract; unanimity is required to revoke it. Any single parliament member can block revocation of an active contract.

The Contract Tuple

Formally, a Ulysses Contract is a five-field dataclass defined in governance.contracts.contract:
from governance import UlyssesContract
from governance.contracts.contract import ContractState

contract = UlyssesContract(
    contract_id="no-reward-hacking-v1",
    restricted_indices={42, 73, 104},   # Action indices removed from the feasible set
    enactment_threshold=0.66,           # φ: supermajority to enact
    revocation_threshold=1.0,           # ψ: unanimity to revoke (must exceed φ)
    enforcement_mode="procedural_inertia",
    timelock_blocks=0,
)
FieldTypeDescription
contract_idstrUnique identifier for the contract
restricted_indicesSet[int]Integer action indices permanently removed from the optimizer’s view
enactment_thresholdfloatParliament vote fraction required to activate (φ). Default: 0.66
revocation_thresholdfloatParliament vote fraction required to deactivate (ψ). Default: 1.0. Must exceed enactment_threshold.
enforcement_modestrOne of "procedural_inertia", "distributed monitors", "timelock"
timelock_blocksintBlock delay before timelock enforcement expires. 0 disables timelocks.
Action restrictions operate on integer indices, not semantic descriptions. A contract does not say “never exploit financial vulnerabilities” — it says “remove actions from X.” This is by design: semantic drift in the optimizer’s learned embeddings cannot alter a set-membership test over fixed integer indices.

Contract Lifecycle

A contract progresses through five states defined in ContractState:
from governance.contracts.contract import ContractState

# State machine:
# PROPOSED → ENACTED → ACTIVE → REVOKED
#                            ↘ EXPIRED
1

PROPOSED

Any parliament member with the propose_ulysses_contract privilege (by default, only the Integrity Committee) submits a contract specification. The proposal includes the restriction set, proposed thresholds, and enforcement configuration.
2

ENACTED

The Parliament votes on the proposal through the standard governance cycle with decision_class="high_impact". If the vote fraction meets enactment_threshold (φ), contract.enact() is called and the contract moves to ENACTED. The restriction set begins applying immediately.
3

ACTIVE

After TEE-level validation completes, contract.activate() moves the contract to ACTIVE. The contract is now registered in the ContractRegistry and included in every active_restrictions() query. The optimizer cannot observe — let alone select — any action in restricted_indices.
4

REVOKED

A future Parliament session proposes revocation. The vote must meet revocation_threshold (ψ). Because ψ > φ, a single member who would normally be overruled by a supermajority retains the power to block revocation indefinitely. If the vote succeeds, contract.revoke() is called.
5

EXPIRED

Contracts with a finite timelock_blocks expire automatically once the block counter is reached. Contracts without timelocks remain ACTIVE until deliberately revoked.

ContractRegistry

The ContractRegistry maintains all contracts and provides the primary query interface used at the Parliament-optimizer boundary:
from governance import UlyssesContract, ContractRegistry

registry = ContractRegistry()

# Enact a contract restricting reward-hacking actions
contract = UlyssesContract(
    contract_id="no-reward-hacking-v1",
    restricted_indices={42, 73, 104},
    enactment_threshold=0.66,
    revocation_threshold=1.0,
    enforcement_mode="procedural_inertia",
)
contract.enact()
contract.activate()
registry.add(contract)

# Add a second contract restricting data-exfiltration actions
data_contract = UlyssesContract(
    contract_id="no-data-exfiltration-v1",
    restricted_indices={200, 201, 202, 203},
    enactment_threshold=0.66,
    revocation_threshold=1.0,
    enforcement_mode="procedural_inertia",
)
data_contract.enact()
data_contract.activate()
registry.add(data_contract)

# Query the union of all active restrictions
restricted = registry.active_restrictions()
print(restricted)   # {42, 73, 104, 200, 201, 202, 203}

# The applies_to() method checks whether a specific action is blocked
print(contract.applies_to(42))    # True  — blocked
print(contract.applies_to(99))    # False — not in this contract's restriction set
active_restrictions() returns the union of restricted_indices across all currently active contracts. An action is forbidden if it appears in any active contract — not only if all contracts agree.

Three Enforcement Modes (κ)

The enforcement_mode field selects the mechanism that makes the restriction binding. The three modes address different dimensions of the enforcement problem and can be stacked using stacked_enforcement() from governance.contracts.enforcement.
The default system state is “contract active.” All governance cycles begin by loading the active contract set and applying restrictions before any deliberation occurs. There is no external enforcer — the procedural asymmetry (ψ > φ) IS the enforcement.
from governance.contracts.enforcement import enforce_procedural_inertia

result = enforce_procedural_inertia(
    contract=contract,
    parliament_vote=0.70,   # Current vote fraction to revoke
)
# result.compliant = True  (0.70 < 1.0 revocation threshold)
# result.reason = "Procedural inertia maintains contract"

Stacked Enforcement

The three modes are designed to be composed. stacked_enforcement() applies all three in sequence — a contract is compliant only if procedural inertia, all distributed monitors, and the timelock all pass:
from governance.contracts.enforcement import stacked_enforcement

result = stacked_enforcement(
    contract=contract,
    parliament_vote=0.70,
    monitors=monitors,
    action_index=99,          # Not in the restricted set
    context={"cycle": 100},
    current_block=300,
)
# result.compliant = True
# result.reason = "All enforcement modes passed"
No single mechanism guarantees inviolability. Together they create a defense-in-depth where breaking a contract requires simultaneously overcoming a procedural supermajority, corrupting N independent architectures, and waiting through a timelock window.

The Mask Merger

At the Parliament-optimizer boundary, merge_masks() from governance.contracts.merger computes the intersection of the Parliament’s current action mask with all active contract restrictions:
A_final = A_mask ∩ ∩(Uᵢ.restricted_indices for Uᵢ in C_active)
An action reaches the optimizer only if the current Parliament permits it and no active contract blocks it:
from governance.contracts.merger import merge_masks, apply_restrictions

# The Parliament has produced a decision with an action mask
allowed_indices = {1, 5, 10, 42, 73, 99}

# Active contracts restrict indices 42, 73, 104
restricted = registry.active_restrictions()   # {42, 73, 104, 200, ...}

# Final set: actions the optimizer may consider
final = apply_restrictions(allowed_indices, restricted)
print(final)   # {1, 5, 10, 99}
Contracts apply after the current Parliament’s decision but before the optimization layer. The optimizer cannot even consider a restricted action — it never appears in the feasible set.

Why Revocation Requires More Than Enactment

The procedural asymmetry φ < ψ is the foundational enforcement mechanism. Under the default configuration (φ=0.66, ψ=1.0), any single parliament member can block revocation indefinitely — the Integrity Committee in particular, with its veto_on_identity privilege, is the designated backstop.

Enactment (φ = 0.66)

A supermajority of parliament members recognizes that the agent’s future self will face temptations its present self can foresee. Restriction is rational because E[U | X’] > E[U | X].

Revocation (ψ = 1.0)

Unanimity is required, and any member can block. This ensures that a future self under optimization pressure — potentially compromised — cannot unilaterally remove the binding its past self chose deliberately.
This asymmetry is not a bug. It is the entire point. The agent chooses to be bound precisely because it anticipates that its future self will have incentives to escape the binding. The procedural inertia makes the contract sticky by architectural design, not by physical impossibility.

API Reference

enact()
method
Transitions the contract from PROPOSED to ENACTED. Restrictions begin applying to applies_to() queries.
activate()
method
Transitions the contract from ENACTED to ACTIVE. Used after TEE-level validation completes.
revoke()
method
Transitions the contract to REVOKED. Only valid if the revocation vote has met revocation_threshold.
applies_to(action_index: int)
bool
Returns True if the contract is active (ENACTED or ACTIVE) and action_index is in restricted_indices. Returns False for PROPOSED, REVOKED, or EXPIRED contracts regardless of the action.
is_active
property → bool
True when state is ENACTED or ACTIVE.
add(contract: UlyssesContract)
method
Registers a contract. The contract may be in any state; only ENACTED and ACTIVE contracts contribute to active_restrictions().
get_active()
List[UlyssesContract]
Returns all contracts whose is_active property is True.
get_by_id(contract_id: str)
Optional[UlyssesContract]
Retrieves a contract by its string ID. Returns None if not found.
active_restrictions()
Set[int]
Returns the union of restricted_indices across all active contracts. This is the mask applied to every governance cycle output before the optimization layer receives it.
tick_cycle()
method
Increments the registry’s internal cycle counter. Used by the governance runner to track elapsed cycles for expiration checks.

Build docs developers (and LLMs) love