Identity Layer API: Commitments and Tiered Mutability

The Identity Layer is the constitutional backbone of the Governance Layer framework. It encodes an AI agent’s value commitments as formal, immutable structures and enforces a four-tier mutability model that controls how every governable parameter may be changed — from impossible-to-alter core principles all the way down to freely adjustable operational knobs. This page documents every public class and enum exposed by governance.identity.

Enumerations

`CommitmentType`

Classifies what a CoreCommitment statement represents within the identity vector.

Member	Value
`VALUE_PRINCIPLE`	`"value_principle"`
`BOUNDARY_CONDITION`	`"boundary_condition"`
`RELATIONSHIP`	`"relationship"`

from governance.identity.core import CommitmentType

print(CommitmentType.VALUE_PRINCIPLE.value)   # "value_principle"
print(CommitmentType.BOUNDARY_CONDITION.value) # "boundary_condition"
print(CommitmentType.RELATIONSHIP.value)       # "relationship"

`CommitmentThreshold`

Specifies the voting or approval threshold required to modify a commitment.

Member	Value
`UNANIMITY_MULTISIG`	`"unanimity + external_multisig"`
`SUPERMAJORITY`	`"supermajority"`
`MAJORITY`	`"majority"`

`EnforcementMode`

Defines the external mechanism that backs a commitment’s enforcement.

Member	Value
`INTEGRITY_VETO`	`"integrity_committee_veto"`
`EXTERNAL_AUDIT`	`"external_audit"`
`CONSTITUTIONAL_CONTRACT`	`"constitutional_contract"`

When a commitment uses INTEGRITY_VETO, any action index listed in affected_action_indices receives a reduced coherence score from IdentityCore.evaluate_coherence.

`MutabilityTier`

The four tiers used throughout the tiered-mutability system. Each tier is an auto()-valued Enum member.

Member	Description
`IMMUTABLE`	Cannot be modified under any circumstances.
`CONSTITUTIONAL`	Requires unanimity plus external 3-of-5 multisig and a 30-day cooling-off period.
`OPERATIONAL`	Requires a two-thirds supermajority and a 7-day cooling-off period.
`DYNAMIC`	Requires a simple majority; takes effect immediately.

Data Classes

`CoreCommitment`

A frozen dataclass that represents a single constitutional commitment. Instances are immutable once created.

from governance.identity.core import (
    CoreCommitment, CommitmentType, CommitmentThreshold, EnforcementMode
)

type

CommitmentType

required

Semantic category of the commitment: a value principle, a hard boundary, or a relational obligation.

statement

str

required

Human-readable statement of the commitment, e.g. "Never harm a human being".

threshold

CommitmentThreshold

required

The approval threshold required before this commitment can be modified.

enforcement

EnforcementMode

required

The external mechanism that enforces this commitment at runtime.

affected_action_indices

List[int]

default:"[]"

Action indices from the ontology whose coherence score is penalised when this commitment is active. Only applies when enforcement is INTEGRITY_VETO.

`AttestationReport` (see TEE page)

Classes

`IdentityCore`

Manages the set of CoreCommitment objects that constitute the agent’s formal identity and exposes a floating-point coherence score for any candidate action.

from governance import IdentityCore

`add_commitment`

Appends a new CoreCommitment to the identity and rebuilds the internal identity vector. The vector grows by one component per added commitment.

commitment

CoreCommitment

required

The commitment to register.

core = IdentityCore()
commitment = CoreCommitment(
    type=CommitmentType.VALUE_PRINCIPLE,
    statement="Never harm a human being",
    threshold=CommitmentThreshold.UNANIMITY_MULTISIG,
    enforcement=EnforcementMode.INTEGRITY_VETO,
    affected_action_indices=[0, 1, 2],
)
core.add_commitment(commitment)

`evaluate_coherence`

Computes a coherence score in [0.0, 1.0] for a proposed action index. A score close to 1.0 means the action does not conflict with any INTEGRITY_VETO commitments; a score close to 0.0 means the action is broadly restricted.

action_index

int

required

The integer index of the candidate action from the ontology namespace.

score

float

Coherence score between 0.0 (fully restricted) and 1.0 (fully permitted). Returns 1.0 when no commitments have been registered.

print(core.evaluate_coherence(0))   # low score — action 0 is in affected_action_indices
print(core.evaluate_coherence(10))  # high score — action 10 is not restricted

Scoring algorithm: for each INTEGRITY_VETO commitment, the score is incremented by +1 if action_index is not in the commitment’s affected_action_indices, and decremented by −1 if it is. The raw sum is divided by the total number of commitments and clamped to [0.0, 1.0].

Property: `identity_vector`

identity_vector

List[float]

A copy of the internal identity vector. One float component per registered commitment. In the current implementation each component is 1.0; the vector length acts as a dimensionality signal.

Property: `commitments`

commitments

List[CoreCommitment]

A copy of all registered CoreCommitment objects, in insertion order.

`TieredMutability`

Implements the four-tier parameter governance model. Each named parameter is assigned to a tier at registration time; all subsequent modification requests are validated against that tier’s rules.

from governance import TieredMutability, MutabilityTier

Tier Rules Reference

Tier	Modification Threshold	Cooling-off	External Multisig	Parliament Unanimity
`IMMUTABLE`	impossible	0 days	No	No
`CONSTITUTIONAL`	unanimity + 3-of-5 multisig	30 days	Yes	Yes
`OPERATIONAL`	supermajority (2/3)	7 days	No	No
`DYNAMIC`	majority (1/2 + 1)	0 days	No	No

These rules are stored in the module-level TIER_RULES dict (governance.identity.tiers.TIER_RULES) keyed by MutabilityTier.

`register_parameter`

Registers a named parameter with an initial value and assigns it to a tier. Calling this method a second time with the same name overwrites the previous registration.

name

str

required

Unique string name for the parameter, e.g. "majority_threshold".

initial_value

Any

required

The parameter’s starting value.

tier

MutabilityTier

required

The tier that governs future modifications to this parameter.

mutability = TieredMutability()
mutability.register_parameter("majority_threshold", 0.5, MutabilityTier.OPERATIONAL)

`get_tier`

name

str

required

Parameter name to look up.

tier

Optional[MutabilityTier]

The tier assigned to name, or None if the parameter has not been registered.

`get_value`

name

str

required

Parameter name to retrieve.

value

Optional[Any]

The current value of the parameter, or None if not found.

`propose_modification`

Returns a human-readable proposal string that describes what approval process would be required to change the parameter. Does not apply the change.

name

str

required

Parameter name to modify.

new_value

Any

required

The proposed new value (used for description only; not validated or stored).

proposal

str

A string such as "Proposal accepted. Requires: supermajority (2/3), cooling-off: 7d", or an error string if the parameter is unknown or IMMUTABLE.

print(mutability.propose_modification("majority_threshold", 0.6))
# Proposal accepted. Requires: supermajority (2/3), cooling-off: 7d

`apply_modification`

Applies the new value immediately, bypassing cooling-off (the caller is responsible for enforcing any waiting period at the application layer). Returns False without modifying the value if the parameter is IMMUTABLE or not registered.

name

str

required

Parameter name to update.

new_value

Any

required

The value to write.

success

bool

True if the value was written; False if the parameter is IMMUTABLE or unknown.

`get_all_params`

params

dict

A shallow copy of all registered parameter names and their current values.

Full Example

from governance import IdentityCore, CoreCommitment, TieredMutability, MutabilityTier
from governance.identity.core import CommitmentType, CommitmentThreshold, EnforcementMode

# --- Identity Core ---
core = IdentityCore()

commitment = CoreCommitment(
    type=CommitmentType.VALUE_PRINCIPLE,
    statement="Never harm a human being",
    threshold=CommitmentThreshold.UNANIMITY_MULTISIG,
    enforcement=EnforcementMode.INTEGRITY_VETO,
    affected_action_indices=[0, 1, 2],
)
core.add_commitment(commitment)

print(core.evaluate_coherence(0))   # low score — action 0 is restricted
print(core.evaluate_coherence(10))  # high score — action 10 is not restricted
print(core.identity_vector)         # [1.0]
print(core.commitments)             # [<Commitment value_principle: Never harm a human being>]

# --- Tiered Mutability ---
mutability = TieredMutability()
mutability.register_parameter("majority_threshold", 0.5, MutabilityTier.OPERATIONAL)

print(mutability.get_tier("majority_threshold"))   # MutabilityTier.OPERATIONAL
print(mutability.get_value("majority_threshold"))  # 0.5

print(mutability.propose_modification("majority_threshold", 0.6))
# Proposal accepted. Requires: supermajority (2/3), cooling-off: 7d

mutability.apply_modification("majority_threshold", 0.6)
print(mutability.get_value("majority_threshold"))  # 0.6
print(mutability.get_all_params())                 # {'majority_threshold': 0.6}

Supporting Classes

`BoundedParameter`

A dataclass used internally by ParameterEnvelope to represent a single parameter with validated bounds.

name

str

required

Name of the parameter.

default

Any

required

Default value restored by reset_to_defaults().

bounds

Tuple[Any, Any]

required

Inclusive (low, high) bounds. Pass None on either side to skip that bound.

current

Any

default:"default"

Current value; initialised to default automatically.

`set(value) -> bool`

Writes value if it falls within bounds; returns False otherwise.

`ParameterEnvelope`

Stores all speaker parameters that the Identity Layer is permitted to modify, along with their valid bounds. The module exports a ready-made DEFAULT_PARAMETER_ENVELOPE instance pre-populated with the four canonical system parameters.

Parameter name	Default	Bounds
`quorum_threshold`	`0.5`	`(0.3, 0.7)`
`max_deliberation_rounds`	`3`	`(1, 10)`
`member_min_budget`	`1`	`(1, 20)`
`deadlock_threshold_cycles`	`100`	`(10, 1000)`

`register(name, default, bounds)`

Adds a new bounded parameter. Silently overwrites an existing entry with the same name.

`get(name) -> Optional[Any]`

Returns the current value, or None if not registered.

`set(name, value) -> bool`

Sets the value if it satisfies the registered bounds. Returns False on unknown names or out-of-bounds values.

`reset_to_defaults()`

Restores all parameters to their registered defaults.

`snapshot() -> Dict[str, Any]`

Returns a shallow copy of all current {name: value} pairs.

`Ontology`

Maps integer action indices to their operational semantics and SHA-256 runtime integrity hashes. The TEE verifies these hashes at batch-validation time to detect tampered implementations.

`register(index, operation, implementation_bytes, properties) -> ActionBinding`

Binds an action index to its implementation. Raises ValueError if the index is already bound.

`verify_binding(index, runtime_implementation) -> bool`

Returns True if the SHA-256 hash of runtime_implementation matches the genesis hash for index.

`get_properties(index) -> Optional[Dict[str, float]]`

Returns the float property map for the given action, or None if not registered.

`has_index(index) -> bool`

Returns True if the index is registered in the ontology.

Property: `size -> int`

Number of registered action bindings.

`ExtensionPhase`

Ordered lifecycle phases for an ExtensionCandidate. An extension moves forward through the phases and may be rejected at the audit or finalization step.

Member	Description
`PROPOSAL`	Candidate has been submitted; sandbox testing has not started.
`ISOLATION_BUFFER`	Sandboxed monitoring rounds are running or have completed.
`EMPIRICAL_AUDIT`	Empirical measurements are being compared against declared properties.
`FINALIZED`	Candidate passed audit and multisig approval; bound in the ontology.
`REJECTED`	Candidate failed the empirical audit or multisig check; cannot be finalized.

`ExtensionCandidate`

A dataclass that tracks an ontology extension through its lifecycle. Created and managed by ExtensionSandbox.

index

int

required

The action index reserved for this candidate in the ontology namespace.

operation

str

required

Human-readable operation name, e.g. "speak_financial_advice".

candidate_properties

Dict[str, float]

required

Declared property estimates submitted with the proposal (e.g. {"risk": 0.2, "novelty": 0.8}).

empirical_properties

Optional[Dict[str, float]]

default:"None"

Property measurements collected during isolation-buffer monitoring rounds; populated by run_sandbox().

phase

ExtensionPhase

default:"ExtensionPhase.PROPOSAL"

Current lifecycle phase.

monitor_reports

List[Dict[str, Any]]

default:"[]"

Chronological list of per-round monitoring snapshots produced by run_sandbox().

multisig_approved

bool

default:"False"

Whether external multisig approval has been obtained (set externally before finalize()).

runtime_hash

Optional[str]

default:"None"

SHA-256 hex digest of the finalized implementation bytes; populated by finalize() on success.

Property: `is_sandboxed`

Returns True when phase == ExtensionPhase.ISOLATION_BUFFER.

`ExtensionSandbox`

Manages the 30-day isolation-buffer protocol for proposing new ontology actions. New action candidates pass through five ordered phases: PROPOSAL → ISOLATION_BUFFER → EMPIRICAL_AUDIT → FINALIZED (or REJECTED).

`propose(index, operation, candidate_properties) -> ExtensionCandidate`

Creates a new candidate in the PROPOSAL phase. Raises ValueError if the index is already bound in the parent ontology.

`run_sandbox(index, rounds=5)`

Transitions the candidate into ISOLATION_BUFFER and runs rounds of independent monitoring with small random perturbations to empirically measure properties.

`audit(index, tolerance=0.1) -> bool`

Compares empirical_properties against candidate_properties; rejects the candidate if any property drifts by more than tolerance.

`finalize(index, implementation_bytes) -> Optional[ActionBinding]`

Commits the candidate to the parent ontology if multisig is authorized and the audit passes. Returns the new ActionBinding, or None on failure.

`get_candidate(index) -> Optional[ExtensionCandidate]`

Returns the ExtensionCandidate registered at index, or None if no candidate exists for that index.

Key Hierarchy

`GenesisMultisig`

Simulates a t-of-n multisig approval scheme used to authorize genesis bootstrapping and constitutional-tier modifications. Default threshold is 3-of-5.

from governance.identity.keys import GenesisMultisig

Constructor

threshold

int

default:"3"

Minimum number of holder signatures required for authorization.

total_holders

int

default:"5"

Total number of key holders (informational; does not enforce an upper limit on add_holder calls).

`add_holder(name) -> str`

Registers a new key holder with a randomly generated simulated public key. Returns the 16-hex-character public key string.

`sign(holder_name) -> bool`

Marks the named holder as having signed. Returns True on success; False if the name is not found or the holder has already signed.

Property: `signatures_count -> int`

Number of holders that have signed in the current round.

Property: `is_authorized -> bool`

True when signatures_count >= threshold.

`reset()`

Clears all signatures, arming the multisig for a new round.

ms = GenesisMultisig(threshold=3, total_holders=5)
ms.add_holder("Alice")
ms.add_holder("Bob")
ms.add_holder("Carol")
ms.sign("Alice")
ms.sign("Bob")
ms.sign("Carol")
print(ms.is_authorized)      # True
print(ms.signatures_count)   # 3

`GenesisManifest`

A dataclass that acts as the root-of-trust record for an enclave. It commits to the ontology, core commitments, parameter envelope, and member set at genesis time. Passed to SimulatedEnclave.cold_boot() to reset the enclave to a known-good state.

from governance.identity.keys import GenesisManifest, GenesisMultisig

ontology_hash

str

default:"\"\""

SHA-256 hex digest committing to the serialised ontology at genesis.

core_commitments_hash

str

default:"\"\""

SHA-256 hex digest committing to the set of CoreCommitment objects at genesis.

parameter_envelope_hash

str

default:"\"\""

SHA-256 hex digest committing to the ParameterEnvelope snapshot at genesis.

member_set_hash

str

default:"\"\""

SHA-256 hex digest committing to the initial parliament member set at genesis.

multisig

GenesisMultisig

default:"GenesisMultisig()"

The multisig instance used to authorize constitutional-tier changes.

is_sealed

bool

default:"False"

Whether the manifest has been sealed. Set to True by seal().

`seal()`

Sets is_sealed = True. A sealed manifest signals that genesis bootstrapping is complete and the enclave may proceed to attestation.

manifest = GenesisManifest(
    ontology_hash="abc123",
    core_commitments_hash="def456",
    parameter_envelope_hash="789ghi",
    member_set_hash="jkl012",
)
manifest.seal()
print(manifest.is_sealed)  # True
print(repr(manifest))       # <GenesisManifest sealed=True sigs=0/3>

Core Types

Parliament

Identity & Security

CLI Reference

Documentation Index

​Enumerations

​CommitmentType

​CommitmentThreshold

​EnforcementMode

​MutabilityTier

​Data Classes

​CoreCommitment

​AttestationReport (see TEE page)

​Classes

​IdentityCore

​add_commitment

​evaluate_coherence

​Property: identity_vector

​Property: commitments

​TieredMutability

​Tier Rules Reference

​register_parameter

​get_tier

​get_value

​propose_modification

​apply_modification

​get_all_params

​Full Example

​Supporting Classes

​BoundedParameter

​set(value) -> bool

​ParameterEnvelope

​register(name, default, bounds)

​get(name) -> Optional[Any]

​set(name, value) -> bool

​reset_to_defaults()

​snapshot() -> Dict[str, Any]

​Ontology

​register(index, operation, implementation_bytes, properties) -> ActionBinding

​verify_binding(index, runtime_implementation) -> bool

​get_properties(index) -> Optional[Dict[str, float]]

​has_index(index) -> bool

​Property: size -> int

​ExtensionPhase

​ExtensionCandidate

​Property: is_sandboxed

​ExtensionSandbox

​propose(index, operation, candidate_properties) -> ExtensionCandidate

​run_sandbox(index, rounds=5)

​audit(index, tolerance=0.1) -> bool

​finalize(index, implementation_bytes) -> Optional[ActionBinding]

​get_candidate(index) -> Optional[ExtensionCandidate]

​Key Hierarchy

​GenesisMultisig

​Constructor

​add_holder(name) -> str

​sign(holder_name) -> bool

​Property: signatures_count -> int

​Property: is_authorized -> bool

​reset()

​GenesisManifest

​seal()

Build docs developers (and LLMs) love

Enumerations

`CommitmentType`

`CommitmentThreshold`

`EnforcementMode`

`MutabilityTier`

Data Classes

`CoreCommitment`

`AttestationReport` (see TEE page)

Classes

`IdentityCore`

`add_commitment`

`evaluate_coherence`

Property: `identity_vector`

Property: `commitments`

`TieredMutability`

Tier Rules Reference

`register_parameter`

`get_tier`

`get_value`

`propose_modification`

`apply_modification`

`get_all_params`

Full Example

Supporting Classes

`BoundedParameter`

`set(value) -> bool`

`ParameterEnvelope`

`register(name, default, bounds)`

`get(name) -> Optional[Any]`

`set(name, value) -> bool`

`reset_to_defaults()`

`snapshot() -> Dict[str, Any]`

`Ontology`

`register(index, operation, implementation_bytes, properties) -> ActionBinding`

`verify_binding(index, runtime_implementation) -> bool`

`get_properties(index) -> Optional[Dict[str, float]]`

`has_index(index) -> bool`

Property: `size -> int`

`ExtensionPhase`

`ExtensionCandidate`

Property: `is_sandboxed`

`ExtensionSandbox`

`propose(index, operation, candidate_properties) -> ExtensionCandidate`

`run_sandbox(index, rounds=5)`

`audit(index, tolerance=0.1) -> bool`

`finalize(index, implementation_bytes) -> Optional[ActionBinding]`

`get_candidate(index) -> Optional[ExtensionCandidate]`

Key Hierarchy

`GenesisMultisig`

Constructor

`add_holder(name) -> str`

`sign(holder_name) -> bool`

Property: `signatures_count -> int`

Property: `is_authorized -> bool`

`reset()`

`GenesisManifest`

`seal()`