Quorum & Anti-Eclipse

What a quorum report settles

An operator who wants to act on a listing published by someone else has a problem the listing itself cannot solve: a single registry that answers can also be the only registry the reader can reach. The answer in the tree is not a protocol. It is a document. chio.federation-quorum-report.v1 collects one observation per publisher for one listing in one namespace, declares the policy those observations were judged against, and carries a final state that a reader can check against the observations without contacting anyone.

The scope is a validator and a schema. validate_federation_quorum_report is a pure function over a struct. It fetches nothing, verifies no signature, resolves no registryUrl, and compares no two observations for agreement. Everything it decides, it decides from the fields in front of it. Nothing else in the workspace constructs a FederationQuorumReport: a repo-wide search finds the module, its own unit tests, an integration smoke test, the reference JSON under docs/standards/, and no producer, no route, and no chio subcommand.

Read that as the boundary between two jobs. Deciding whether mirrors disagree is the aggregator’s job, and it already exists: aggregate_generic_listing_reports in chio-listing groups listings by a divergence key, compares each group against a canonical fingerprint of source digest, status, owner id, and registry URL, and emits a GenericListingDivergence when they differ. Recording that decision so a second operator can audit it is this page’s job. The two types line up almost exactly, and nothing in the tree converts one into the other.

The report, field by field

Every field below is required unless the table says otherwise. The struct carries deny_unknown_fields and rename_all = "camelCase", so an unrecognized top-level key is a parse failure before the validator ever runs.

SignedFederationQuorumReport is declared as SignedExportEnvelope<FederationQuorumReport>, the same body-plus-key-plus-signature envelope the other four federation contracts use, with sign and verify_signature over the canonical JSON of the body. The alias has no other occurrence in the workspace, and the validator takes the bare body. Signing a report is available; nothing in the tree does it, and validation never asks whether it happened.

One publisher observation

An observation is one operator’s answer to "what does this listing look like from where you stand, and how far from the source are you".

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FederationPublisherObservation {
    pub publisher: GenericRegistryPublisher,
    pub report_ref: FederationArtifactReference,
    pub observed_listing_sha256: String,
    pub freshness: GenericListingReplicaFreshness,
    pub observed_at: u64,
    pub upstream_hop_count: u32,
}

publisher comes from chio-listing unchanged: role (origin, mirror, or indexer), operatorId, an optional operatorName, a registryUrl, and a possibly empty upstreamRegistryUrls list. Its own validate requires a non-empty operator id and requires the registry URL and every upstream URL to start with http:// or https://. That is the entire URL check: no host resolution, no scheme preference, no reachability.

reportRef is a FederationArtifactReference and carries two constraints the validator enforces by hand. Its kind must be listing_report, and its operatorId must equal the enclosing publisher’s operatorId. That second rule is what stops one operator from submitting an observation whose evidence pointer belongs to another. The rest of the reference is checked for shape and nothing else. validate_federation_artifact_reference asks that schema, artifactId, and operatorId be non-empty and that sha256 be a hex digest, so the reference’s own schema string is never matched against chio.registry.listing-report.v1 even though its kind must be listing_report, and its optional uri is neither validated nor resolved, not even for a scheme.

Both digests run through one helper. The reference’s sha256 and the observation’s observedListingSha256 each pass validate_hex_digest, which requires exactly 64 ASCII hex characters with no surrounding whitespace. A blank value fails one step earlier: validate_hex_digest calls ensure_non_empty first, so an empty or whitespace-only digest comes back as MissingField under the same field name rather than InvalidReference. Uppercase passes despite the error text saying "lowercase-compatible", and hex_digest_helper_preserves_exact_uppercase_compatible_digest_contract pins that on purpose.

observedAt is read by nothing. It is not bounded by generatedAt, not compared to the freshness block that sits beside it, and not ordered against other observations. Treat it as an annotation for a human reader.

The anti-eclipse policy is four numbers

This is the part that gives the page its name, and it is small enough to read whole.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FederationAntiEclipsePolicy {
    pub minimum_distinct_operators: u32,
    pub require_origin_publisher: bool,
    pub require_indexer_observation: bool,
    pub max_upstream_hops: u32,
}

impl Default for FederationAntiEclipsePolicy {
    fn default() -> Self {
        Self {
            minimum_distinct_operators: 2,
            require_origin_publisher: true,
            require_indexer_observation: true,
            max_upstream_hops: 1,
        }
    }
}

The defaults are the shape the profile argues for: an origin, an indexer, at least two distinct operators, and nobody more than one hop from the source. tests/integration_smoke.rs pins all four values and the schema string in one test, federation_defaults_require_multi_party_visibility, which is the only place in the workspace that asserts them.

The hop count is self-declared in the same way. upstreamHopCount is never checked against upstreamRegistryUrls, which is the only other place a publisher describes its distance from the source. In the reference fixture the origin declares zero hops and an empty upstream list while the mirror and the indexer declare one hop and one upstream URL each, but that correspondence is a property of the fixture and not of the validator.

The order the validator checks in

Order matters here more than it usually does, because the anti-eclipse gates run before the final state is read, and they reject rather than classify.

The per-publisher loop validates the publisher, the reference, both digests, the freshness block, the hop count, and the operator id, and accumulates four running values: fresh_count, stale_count, has_origin, and has_indexer, plus a set of operator ids. The hop-count check reads the report’s own policy from inside the loop, so a hop violation is found before the policy gates run and reports a different message than they do.

if report.anti_eclipse_policy.require_origin_publisher && !has_origin {
    return Err(FederationContractError::InvalidQuorum(
        "anti-eclipse policy requires an origin publisher observation".to_string(),
    ));
}
if report.anti_eclipse_policy.require_indexer_observation && !has_indexer {
    return Err(FederationContractError::InvalidQuorum(
        "anti-eclipse policy requires an indexer observation".to_string(),
    ));
}
if publisher_ids.len() < report.anti_eclipse_policy.minimum_distinct_operators as usize {
    return Err(FederationContractError::InvalidQuorum(
        "insufficient distinct operators for anti-eclipse policy".to_string(),
    ));
}

This is the design decision the page exists to name. An eclipse condition is not a state a report can be in. It is a reason the report is invalid. A reader handed a document whose observations all come from one operator’s mirrors does not receive an insufficient_quorum verdict to weigh; it receives an InvalidQuorum error and has nothing to weigh at all. Three unit assertions cover the three gates: dropping the origin observation, retaining only the non-indexer observations, and raising minimum_distinct_operators to 4 against a three-publisher body each produce InvalidQuorum.

The four final states

FederationQuorumState is a snake-cased enum with four members, and the validator matches on it last. Each arm is a consistency rule between the label and the body, not a computation of the label from the body.

The insufficient_quorum arm looks like a four-part test and behaves like a one-part test:

FederationQuorumState::InsufficientQuorum => {
    if fresh_count >= report.quorum_threshold
        && publisher_ids.len()
            >= report.anti_eclipse_policy.minimum_distinct_operators as usize
        && (!report.anti_eclipse_policy.require_origin_publisher || has_origin)
        && (!report.anti_eclipse_policy.require_indexer_observation || has_indexer)
    {
        return Err(FederationContractError::InvalidQuorum(
            "insufficient_quorum requires a real quorum shortfall".to_string(),
        ));
    }
}

Three of those four conjuncts are already guaranteed by the gates that ran a few lines earlier. The distinct-operator count cleared its minimum, require_origin_publisher implies has_origin, and require_indexer_observation implies has_indexer. What remains is fresh_count >= quorum_threshold. So a report may call itself insufficient_quorum exactly when its fresh count falls short of its threshold, and never for an anti-eclipse reason, because an anti-eclipse reason already refused the document.

Conflict evidence itself is three fields: divergenceKey, publisherOperatorIds, and reason, all free text apart from the uniqueness rules. The key and the reason must be non-empty, the operator id list must have no empty and no repeated entry, and no two conflict entries may share a divergence key. Nothing checks that the ids listed in a conflict appear among the report’s publishers.

What counts as fresh

Freshness decides the counter that converged and stale are checked against, and the rule is one expression:

if publisher.freshness.age_secs > report.max_replica_age_secs
    || publisher.freshness.state == GenericListingFreshnessState::Stale
{
    stale_count += 1;
} else {
    fresh_count += 1;
}

Two consequences follow, and both are easy to get wrong from the type names alone.

The first is that the ceiling is the report’s, not the observation’s. GenericListingReplicaFreshness carries its own maxAgeSecs and validUntil, and its validate only requires maxAgeSecs to be greater than zero and validUntil to be greater than generatedAt. It never compares ageSecs against either. So an observation may declare state: fresh with an ageSecs far past its own maxAgeSecs and still be counted fresh, as long as it stays inside the report’s maxReplicaAgeSecs. The report-level number is the one to set carefully.

The second is that GenericListingFreshnessState has three members and only one of them is tested here. Divergent is not Stale, so a divergent observation inside the age ceiling increments fresh_count and can carry a report to converged.

A negative fixture pins the interaction from the other direction. Marking two of the three sample observations Stale with age_secs: 400 against a 300-second ceiling, while leaving final_state at Converged, drops fresh_count to 1 under a threshold of 2 and produces InvalidQuorum.

What agreement does not mean

Every observation carries an observedListingSha256, and the validator checks each one is a well-formed 64-character hex digest. It never compares two of them. A report in which the origin, the mirror, and the indexer each observed a different listing body, with an empty conflicts array and three fresh observations against a threshold of 2, validates as converged.

That is not an oversight to route around, it is the division of labour stated at the top. Detecting divergence is the aggregator’s job. aggregate_generic_listing_reports builds a divergence key from actor kind, actor id, and the compatibility source schema and id, groups candidate listings under it, and compares every member against the first one’s fingerprint of source digest, status, owner id, and registry URL. On a mismatch it emits a GenericListingDivergence carrying the divergence key, the actor, the publisher operator ids, and the fixed reason conflicting source artifact, lifecycle state, or namespace ownership across publishers, and drops the group from the results entirely.

FederationConflictEvidence is that output minus the actor fields. The federation contract is the durable, cross-operator record of a decision the listing layer already knows how to make. What is missing between them is the conversion: no function in the workspace turns a GenericListingSearchResponse into a FederationQuorumReport, so an operator publishing one today is transcribing by hand. Capability Discovery covers the aggregator, its ranking, and its freshness gate.

Every refusal this validator can produce

FederationContractError is shared across all five federation contract validators. The quorum path reaches five of its nine variants. The table is exhaustive for this validator, in check order.

The four variants this path never returns are InvalidExchange, InvalidAdmission, InvalidClearing, and InvalidQualificationCase, which belong to the activation, open-admission, reputation-clearing, and qualification validators. Matching on InvalidQuorum alone is not enough to catch a quorum failure: all five variants above are reachable from this one function, and the distinctions among them live in the payload strings rather than in the type.

Authoring a report that validates

The reference document lives at docs/standards/CHIO_FEDERATION_QUORUM_REPORT_EXAMPLE.json and is not decorative: reference_artifacts_parse_and_validate pulls it in with include_str!, parses it into the struct, and runs the validator over it alongside the other four federation reference documents. If the schema drifts, that test fails. The body below is that file with two of its three publishers elided.

{
  "schema": "chio.federation-quorum-report.v1",
  "reportId": "fqr-1",
  "generatedAt": 1743552060,
  "namespace": "registry.chio.example/liability",
  "listingId": "listing-liability-provider-1",
  "originOperatorId": "origin-operator",
  "quorumThreshold": 2,
  "maxReplicaAgeSecs": 300,
  "publishers": [
    {
      "publisher": {
        "role": "origin",
        "operatorId": "origin-operator",
        "operatorName": "Origin Operator",
        "registryUrl": "https://origin.chio.example/registry",
        "upstreamRegistryUrls": []
      },
      "reportRef": {
        "kind": "listing_report",
        "schema": "chio.registry.listing-report.v1",
        "artifactId": "report-origin-1",
        "operatorId": "origin-operator",
        "sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
        "uri": "https://origin-operator.chio.example/artifacts/report-origin-1"
      },
      "observedListingSha256": "1111111111111111111111111111111111111111111111111111111111111111",
      "freshness": {
        "state": "fresh",
        "ageSecs": 30,
        "maxAgeSecs": 300,
        "validUntil": 1743552360,
        "generatedAt": 1743552030
      },
      "observedAt": 1743552030,
      "upstreamHopCount": 0
    }
  ],
  "antiEclipsePolicy": {
    "minimumDistinctOperators": 2,
    "requireOriginPublisher": true,
    "requireIndexerObservation": true,
    "maxUpstreamHops": 1
  },
  "finalState": "converged",
  "note": "Requires origin plus independent mirror/indexer observation before a remote listing is treated as converged."
}

The full fixture adds a mirror at mirror-operator-a and an indexer at indexer-operator-a, both declaring one upstream registry URL and upstreamHopCount: 1, and all three publishers report the same observedListingSha256. Three fresh observations against a threshold of 2, three distinct operators against a minimum of 2, an origin whose operator id matches originOperatorId, an indexer present, no hop above 1, and an empty conflict list: converged.

Four things to get right when you build one. The digest fields need exactly 64 hex characters and no padding; a trimmed comparison is not applied, and hex_digest_validation_rejects_padded_digest pins that a space on either side fails. Each reportRef.operatorId must repeat its own publisher’s operator id. The origin observation needs both the origin role and the exact operator id named in originOperatorId, which is the rule most likely to be missed under a default policy. And every observation’s ageSecs is judged against maxReplicaAgeSecs on the report, so setting a generous per-observation maxAgeSecs buys nothing.

Why this is filed here and not under Swarm

Chio has two joint-authorization mechanisms on the write path, and a quorum report fires neither. Under Bilateral Co-Sign two kernels sign one receipt and a verifier refuses the invocation without both. Under FROST Quorum a threshold roster produces one aggregated signature bound to an action digest, a roster digest, a key epoch, a resource fence, and an issue and expiry window, over one of eight authorization domains, seven of which map to a registered action class, including chio.frost.settle-commitment.v1 and chio.frost.credentials-passport-revoke.v1. Both answer "may this mutation proceed". A quorum report answers "do independent observers describe the same thing", and its acceptance changes nothing anyone may do.

The federation profile is explicit about the boundary that keeps those separate. Its non-goals list rules out "mirror or indexer visibility as ambient runtime trust", and FederationImportControl carries it in code: five booleans, every one of which the activation validator requires to be true, including explicitLocalActivationRequired and prohibitAmbientRuntimeAdmission. A converged report widens what an operator can see. Turning that into runtime trust is a separate, reviewed, locally signed step covered under Federation.

The report does appear as evidence in one other contract. FederationQualificationMatrix carries a required non-empty quorumReportRef alongside an exchange reference and a reputation-clearing reference, and its validator refuses any matrix that does not cover all five requirement ids TRUSTMAX-01 through TRUSTMAX-05. Two of the six scenario kinds it can label a case with, insufficient_quorum and eclipse_attempt, name this page’s subject. The reference matrix maps them to TRUSTMAX-02 and TRUSTMAX-05. The reference is a string; nothing resolves it to a report.

Guarantees and limits

Next Steps

• FROST Quorum · the write-path quorum this page is deliberately not: roster, epoch checkpoint, one-shot slot, and the seven action classes registered across its eight authorization domains
• Federation · the five federation contracts side by side, and the import controls that keep visibility from becoming runtime trust
• Capability Discovery · the aggregator that actually detects divergence across mirrors, and the freshness gate feeding it
• Revocation Oracle · the other cross-operator read path, where a signed epoch root and a reader-set freshness window replace a publisher count
• Portable Reputation · the sibling contract that does carry an issuer independence group, and the sybil controls built on it