Governance Charters and Cases

Charter and Case Records

Both record types scope to a namespace and a governing operator, and both reference a listing identity from chio-listing. A charter is issued once and authorizes a set of case kinds; cases are issued against individual listings under that charter.

Each record is wrapped in a SignedExportEnvelope<T> containing the body, an Ed25519 signer key, and a signature over the RFC 8785 canonical JSON body. The aliases are SignedGenericGovernanceCharter and SignedGenericGovernanceCase. The crate is re-exported by chio-core and chio-open-market as governance.

The charters on this page govern registry listings: their dispute, freeze, sanction, and appeal lifecycle. The economic parameters an economy runs on, credit tiers, discount curves, premium schedules, fees, and bonds, are governed by a separate, specialized charter family whose amendments move through a propose, m-of-n approval, timelock, then activate lifecycle before they take effect. That fiscal system is documented in Fiscal Constitutions.

The Charter

A charter names the governing operator, the namespace it covers, the case kinds it may open, and an optional set of escalation operators. Its authority_scope can pin the charter to specific listing publishers and actor kinds; an empty list on either field means the scope is unrestricted on that axis.

pub const GENERIC_GOVERNANCE_CHARTER_ARTIFACT_SCHEMA: &str =
    "chio.registry.governance-charter.v1";

pub struct GenericGovernanceCharterArtifact {
    pub schema: String,                       // chio.registry.governance-charter.v1
    pub charter_id: String,                   // "charter-{sha256}", derived by the builder
    pub governing_operator_id: String,
    pub governing_operator_name: Option<String>,
    pub authority_scope: GenericGovernanceAuthorityScope,
    pub allowed_case_kinds: Vec<GenericGovernanceCaseKind>,
    pub escalation_operator_ids: Vec<String>, // operators a case may be escalated to
    pub issued_at: u64,
    pub expires_at: Option<u64>,              // must be greater than issued_at
    pub issued_by: String,
    pub note: Option<String>,
}

pub struct GenericGovernanceAuthorityScope {
    pub namespace: String,
    pub allowed_listing_operator_ids: Vec<String>,     // empty = any publisher
    pub allowed_actor_kinds: Vec<GenericListingActorKind>, // empty = any actor kind
    pub policy_reference: Option<String>,
}

allowed_case_kinds must be non-empty, and a validated charter with an expires_at requires it to be strictly greater than issued_at. The builder derives the identifier as a content hash so the same inputs always yield the same charter id:

pub fn build_generic_governance_charter_artifact(
    local_operator_id: &str,
    local_operator_name: Option<String>,
    request: &GenericGovernanceCharterIssueRequest,
    issued_at: u64,
) -> Result<GenericGovernanceCharterArtifact, String>;

// charter_id = "charter-" + sha256_hex(canonical_json_bytes((
//     local_operator_id,
//     normalize_namespace(namespace),
//     allowed_case_kinds,
//     issued_at,
// )))

The builder returns an unsigned body; the governing operator signs it with a governance-authority keypair issued through chio-federation-authority:

let charter = build_generic_governance_charter_artifact(
    "origin-a",
    Some("Origin A".to_string()),
    &request,
    130,
)?;
let signed = SignedGenericGovernanceCharter::sign(charter, &authority_keypair)?;

The Case

A case binds a charter to one listing and carries the case kind, its lifecycle state, at least one evidence reference, and optional links to a prior case for appeals and supersession.

pub const GENERIC_GOVERNANCE_CASE_ARTIFACT_SCHEMA: &str =
    "chio.registry.governance-case.v1";

pub struct GenericGovernanceCaseArtifact {
    pub schema: String,                       // chio.registry.governance-case.v1
    pub case_id: String,                      // "case-{sha256}", derived by the builder
    pub charter_id: String,
    pub governing_operator_id: String,
    pub kind: GenericGovernanceCaseKind,      // dispute | freeze | sanction | appeal
    pub state: GenericGovernanceCaseState,    // open | escalated | enforced |
                                              // resolved | denied | superseded
    pub namespace: String,
    pub listing_id: String,
    pub activation_id: Option<String>,        // required for freeze / sanction
    pub subject_operator_id: Option<String>,
    pub opened_at: u64,
    pub updated_at: u64,                       // must be >= opened_at
    pub expires_at: Option<u64>,              // must be greater than opened_at
    pub escalated_to_operator_ids: Vec<String>, // required when state = escalated
    pub evidence_refs: Vec<GenericGovernanceEvidenceReference>, // must be non-empty
    pub appeal_of_case_id: Option<String>,    // required for, and only valid on, appeals
    pub supersedes_case_id: Option<String>,
    pub issued_by: String,
    pub note: Option<String>,
}

pub struct GenericGovernanceEvidenceReference {
    pub kind: GenericGovernanceEvidenceKind,  // listing | trust_activation | certification |
                                              // registry_search | operator_report | external
    pub reference_id: String,
    pub uri: Option<String>,
    pub sha256: Option<String>,               // 64-char hex digest when present
}

Body validation enforces the shape independently of any evaluation context: the schema must match, evidence_refs must be non-empty, an appeal must carry appeal_of_case_id (and no other kind may), and an escalated case must list at least one escalated_to_operator_ids.

The case builder verifies the signatures on the charter, listing, and (when present) trust activation before minting the body, and it refuses a case whose charter is governed by a different operator, or whose trust activation was issued by anyone other than the governing operator:

pub fn build_generic_governance_case_artifact(
    local_operator_id: &str,
    request: &GenericGovernanceCaseIssueRequest,
    issued_at: u64,
) -> Result<GenericGovernanceCaseArtifact, String>;

// case_id = "case-" + sha256_hex(canonical_json_bytes((
//     local_operator_id, charter_id, listing_id,
//     kind, state, opened_at,
//     appeal_of_case_id, supersedes_case_id,
// )))

Case Kinds

Four kinds cover the adjudication lifecycle. A charter must list a kind in allowed_case_kinds before a case of that kind evaluates.

Effective State and Admission

Evaluation resolves a case to a GenericGovernanceEffectiveState (one of clear, disputed, frozen, sanctioned, appealed) and a boolean blocks_admission. The mapping is driven by the case lifecycle state and kind together.

Case Evaluation

evaluate_generic_governance_case takes the current listing, the current publisher, the charter, the case, and optionally a trust activation and a prior case. It returns a GenericGovernanceCaseEvaluation.

pub fn evaluate_generic_governance_case(
    request: &GenericGovernanceCaseEvaluationRequest,
    now: u64,
) -> Result<GenericGovernanceCaseEvaluation, String>;

pub struct GenericGovernanceCaseEvaluationRequest {
    pub listing: SignedGenericListing,
    pub current_publisher: GenericRegistryPublisher,
    pub activation: Option<SignedGenericTrustActivation>,
    pub charter: SignedGenericGovernanceCharter,
    pub case: SignedGenericGovernanceCase,
    pub prior_case: Option<SignedGenericGovernanceCase>,
    pub evaluated_at: Option<u64>,           // defaults to now
}

pub struct GenericGovernanceCaseEvaluation {
    pub listing_id: String,
    pub namespace: String,
    pub charter_id: String,
    pub case_id: String,
    pub governing_operator_id: String,
    pub kind: GenericGovernanceCaseKind,
    pub state: GenericGovernanceCaseState,
    pub effective_state: GenericGovernanceEffectiveState,
    pub evaluated_at: u64,
    pub blocks_admission: bool,
    pub findings: Vec<GenericGovernanceFinding>,
}

Evaluation is ordered. The first failure ends evaluation and returns a finding without an Err:

• Validate the listing body and the current_publisher shape. These are the only hard Err paths, alongside an internal crypto or canonicalization error.
• Verify the signature and body of the listing, charter, and case, and of the activation and prior case when present.
• If an activation is present, its local_operator_id must equal the charter's governing_operator_id.
• Charter, case, and listing must agree on governing operator, charter id, namespace, and listing id.
• Neither the charter nor the case may be expired as of evaluated_at; expiry is exclusive at the boundary (expires_at <= evaluated_at is rejected).
• The charter must allow the case's kind and, where its scope is set, admit the current publisher operator id and the listing subject actor kind.
• A freeze or sanction case requires a trust activation whose activation_id matches the case; a superseding case requires a matching prior_case; an appeal requires a matching non-appeal prior_case.
• On success, the case state and kind map to an effective state and the blocks_admission flag, and the evaluation carries an empty findings list.

Finding Codes

When evaluation short-circuits it emits one GenericGovernanceFinding with a typed code and a human-readable message. The codes:

Worked Example: An Enforced Freeze

Operator origin-a governs the namespace https://registry.chio.example under a charter that allows all four case kinds. It freezes listing listing-artifact-1 and signs the case, referencing a trust activation it also issued. On the wire the case envelope uses camelCase fields and snake_case enum values:

{
  "body": {
    "schema": "chio.registry.governance-case.v1",
    "caseId": "case-6f2a9c...",
    "charterId": "charter-1d4b0e...",
    "governingOperatorId": "origin-a",
    "kind": "freeze",
    "state": "enforced",
    "namespace": "https://registry.chio.example",
    "listingId": "listing-artifact-1",
    "activationId": "activation-8c71...",
    "subjectOperatorId": "origin-a",
    "openedAt": 140,
    "updatedAt": 140,
    "expiresAt": 500,
    "evidenceRefs": [
      { "kind": "trust_activation", "referenceId": "activation-8c71..." }
    ],
    "issuedBy": "governance@chio.example",
    "note": "freeze"
  },
  "signerKey": "9f2c1a...",
  "signature": "b0e4d7..."
}

A relying party evaluates it against the live listing at now = 150:

let evaluation = evaluate_generic_governance_case(
    &GenericGovernanceCaseEvaluationRequest {
        listing,
        current_publisher,
        activation: Some(activation),
        charter,
        case,
        prior_case: None,
        evaluated_at: Some(150),
    },
    150,
)?;

assert!(evaluation.findings.is_empty());
assert_eq!(evaluation.effective_state, GenericGovernanceEffectiveState::Frozen);
assert!(evaluation.blocks_admission);

Drop the activation from the request and the same case resolves to a single MissingActivation finding with blocks_admission = false: a freeze the crate cannot substantiate does not silently take effect. Move the case to resolved and the effective state becomes clear with no block, which is how a lifted freeze reads.

Leases and Receipts in the Same Crate

chio-governance defines charter and case records plus two other record groups. The other groups govern action authority instead of listing status and use the same signature and schema checks:

• Capability leases (chio.capability-lease.v1) carry an action class — ScopedObservation, DelegatedAction, or NarrowDestructive — and a scope digest. verify_capability_lease checks schema, signature, the validity window, and an exact scope_digest match.
• Destructive-action governance receipts (chio.governance-receipt.v1) authorize a single destructive workflow step. verify_destructive_authorization binds a receipt to an expected lease id, workflow id, and step hash, and verify_step_governance_boundary requires a valid, unexpired receipt for any step marked destructive and none otherwise.

See Capabilities for the scoped, time-bounded authority these leases attenuate, and Mandates & Capabilities for how the kernel enforces a destructive-step boundary at runtime.

Related Reading

• Capability Discovery · the chio-listing marketplace module whose listing identity a case references
• Operating an Economy · how an operator wires governance authority into a running economy
• Trust Model · the admission and trust-activation decisions a governance case gates
• Compliance Certificates · the session-scoped attestation that shares this crate's canonical-JSON signing substrate