`mod catalog_rpc`¶

module catalog_rpc¶

Versioned cooperative catalog protocol. Versioned, ensemble-isolated cooperative catalog wire types.

Modules

Variables

const INCUMBENT_SAMPLE_DRAW: u64¶: Sample draw that returns the active-catalog incumbent.

const PROTOCOL_VERSION: u16¶: Wire protocol version accepted by this release.

const SPARSE_SAMPLE_DRAW: u64¶

Sample draw that returns a representative of the packing family the fewest live replicas are standing on.

A replica leaving a crowded packing cannot reach another funnel by perturbing within its own: a move drawn inside a funnel and relaxed downhill lands back in it, which is what a funnel is. Crossing has to be a draw from somewhere else. This is that draw, with the catalog standing in for a fitted model of each funnel.

Functions

fn decode_request(bytes: &[u8]) -> Result<CatalogRequest, ProtocolError>¶: Decode one request and enforce its protocol version and digest shape.

fn encode_request(request: &CatalogRequest) -> Result<Vec<u8>, ProtocolError>¶: Encode one checked request as an unpacked Cap’n Proto message.

fn validate_identity(expected: &CatalogIdentity, received: &CatalogIdentity) -> Result<(), ProtocolError>¶: Reject a request whose mutation identity differs from the coordinator.

Enums

enum AcceptedPayload¶

Scientific record an accepted reply carries alongside the snapshot.

None¶: Snapshot or mutation response without an additional scientific record.

Candidate(CatalogCandidate)¶: Sampled validated catalog candidate.

DescriptorHole(DescriptorHoleProposal)¶: Seeded target-free descriptor-hole proposal.

BoundaryCrossing(BoundaryCrossingRecord)¶: Observed crossing selected from the current attraction region.

PolicyState(PolicyState)¶: Exact census and active-catalog policy evidence.

PopulationEpoch(PopulationEpochState)¶: Pending barrier state or a complete synchronous population plan.

CatalogMutation(CatalogMutation)¶: Exact active-catalog admission result.

CoordinatorStatus(CoordinatorStatus)¶: Read-only aggregate status for an observer.

BridgeAssignment(BridgeAssignmentRecord)¶: A bridge segment assignment for the requesting replica.

FrontierPost(CatalogFrontierPost)¶: One shared frontier excursion state from the ladder.

RideWork(CatalogRideWork)¶: Exclusive transition experiment and its validated source minimum.

RideCredit(RideCredit)¶: Coordinator-computed novelty credit for a transition report.

Roster(RosterReply)¶: Versioned live roster after attach, detach, tick, or scale.

enum CatalogMutationKind¶

Exact serialized outcome of one active-catalog admission attempt.

Added¶: Candidate filled an available active slot.

ReplacedSameBasin¶: Candidate improved its basin’s active representative.

ReplacedConflicts¶: Candidate replaced its complete packing-conflict set.

ReplacedCapacity¶: Candidate replaced the eligible entry at capacity.

RejectedSameBasin¶: Same-basin representative had lower or equal energy.

RejectedConflict¶: A packing-conflict representative had lower or equal energy.

RejectedCapacity¶: The eligible entry at capacity had lower or equal energy.

Implementations

impl CatalogMutationKind¶

Functions

const fn admitted(self) -> bool¶: Whether the active catalog changed.

const fn code(self) -> &'static str¶: Stable event-stream code.

Traits implemented

impl From<WireCatalogMutationKind> for CatalogMutationKind¶

enum CatalogOperation¶

Mutation or read operation carried by a catalog request.

Snapshot¶: Read the current versioned snapshot.

RecordVisit¶

Record one exact fixed-census observation.

candidate: CatalogCandidate¶: Candidate that must pass coordinator validation before observation.

OfferCandidate¶

Offer one validated candidate to the active catalog.

candidate: CatalogCandidate¶: Candidate that must pass coordinator validation before admission.

Sample¶

Sample an admissible active representative.

draw: u64¶: Explicit deterministic random draw.

SampleBasin¶

Retrieve one immutable census basin’s validated representative.

basin: u64¶: Coordinator-assigned basin identity.

DescriptorHole¶

Request a sampled farthest-hole proposal.

current: Vec<f64>¶: Current replica descriptor.

samples: u32¶: Number of unit-sphere samples.

draw: u64¶: Explicit deterministic random draw.

BoundaryCrossing¶

Request an observed crossing usable from the query’s attraction region.

current: Vec<f64>¶: Current replica descriptor under the fixed catalogue schema.

draw: u64¶: Explicit deterministic random draw.

PolicyState¶

Read exact census and active-catalog evidence for one descriptor.

descriptor: Vec<f64>¶: Descriptor to classify against the fixed census and active catalog.

energy: f64¶: Candidate energy used to compare an unrelated incumbent anchor.

leftover_lambda: f64¶: Highest leftover-SOAP (lambda) on this replica’s Leave path.

LedgerEvent¶

Submit one replay-safe charged-work event.

kind: u16¶: Stable charge-kind discriminant.

charged_calls: u64¶: Potential calls charged by this event.

cumulative_charged: u64¶: Replica counter including this event.

LedgerBatch¶

Submit consecutive exact charged-work events in one durable request.

events: Vec<CatalogLedgerEvent>¶: Boundaries in strictly increasing replica request order.

PopulationSubmit¶

Submit one validated representative to a synchronous population epoch.

epoch: u64¶: Charged-work synchronization epoch.

candidate: CatalogCandidate¶: Representative requiring receiving-side scientific validation.

PopulationPlan¶

Poll an immutable synchronous population plan.

epoch: u64¶: Charged-work synchronization epoch.

PopulationAbstain¶

Decline to submit to one epoch, releasing the replicas waiting on it.

epoch: u64¶: Charged-work synchronization epoch.

PopulationJoin¶

Join one epoch by reference to the best validated candidate on file.

epoch: u64¶: Charged-work synchronization epoch.

ObserverStatus¶: Read-only aggregate status for an observer naming the same campaign, ensemble, and system signature. Observer replica membership is not required.

BridgeAssignment¶

Poll for a bridge segment assignment; the argument selects an entry state from the assigned region’s stored entries.

draw: u64¶: Caller-supplied draw for entry selection.

BridgeCrossing¶

Report one attempted exit from a bridge region.

crossing: BridgeCrossingRecord¶: Crossing record: bridge, regions, descriptor, state, energy.

PostFrontier¶

Post one raw frontier excursion state to the shared ladder.

post: CatalogFrontierPost¶: The live excursion state and its gap.

DrawFrontier¶

Draw one shared frontier post, if any is banked.

draw: u64¶: Explicit deterministic random draw.

RecordTransition¶

Record one action-conditioned transition from the replica’s live basin.

action: String¶: Stable target-blind proposal-action identifier.

destination: TransitionDestination¶: Resolved validated endpoint or explicit unresolved outcome.

adopted: bool¶: Whether the reached endpoint became the replica’s live state.

ClaimRide¶

Claim one exclusive same-system transition experiment.

seed: u64¶: Deterministic seed used if a new claim is issued.

ReportRide¶

Share the charged result of a claimed transition experiment.

report: CatalogRideReport¶: Work identity, cost, and scientific outcome.

Attach¶: Admit a replica that is not yet on the live roster.

Detach¶

Retire a live replica and record why.

reason: String¶: Human-readable retirement reason.

Tick¶

Advance the coordinator clock by one tick of the given period.

millis: u64¶: Tick period in milliseconds.

Scale¶

Request a manual live-population target.

live_target: u32¶: Desired number of live replicas.

enum CatalogRelation¶

Relation between a replica candidate and the active catalog.

Empty¶: The active catalog has no entries.

Incumbent¶: The candidate belongs to the incumbent basin.

SameBasin¶: The candidate belongs to another active basin.

UnrelatedNoAnchor¶: The candidate is unrelated and no lower incumbent anchors exploitation.

UnrelatedLowerAnchor¶: The candidate is unrelated and a lower incumbent anchors exploitation.

Traits implemented

impl From<WireCatalogRelation> for CatalogRelation¶

enum CatalogReply¶

Decoded coordinator response.

Accepted(AcceptedReply)¶: Request was accepted or replayed idempotently.

Rejected¶

Request was rejected without state mutation.

event_sequence: u64¶: Request sequence being rejected.

snapshot_version: u64¶: Coordinator version at rejection.

reason: ProtocolRejection¶: Stable rejection reason.

enum CatalogRideOutcome¶

Producer evidence for one claimed transition experiment.

Certified(CatalogRideConnection)¶: Stationary structures requiring fresh receiving-side certification.

Unresolved(CatalogRideSaddleEvidence)¶: A stationary saddle retained despite unresolved branch connectivity.

Failed(RideFailure)¶: Explicit local failure retained as shared negative evidence.

enum CoordinatorEvent¶

Event pushed to every attached subscriber.

EpochClosed(u64)¶: A synchronous population epoch closed.

RosterChanged(u64)¶: The live or retired roster changed.

Retire(String)¶: A replica was retired from the live population.

Spawn(u32)¶: The coordinator asked for more live replicas.

Tick(u64)¶: Periodic liveness tick.

enum PopulationSelection¶

Which selection produced a barrier’s parent map.

The two branches carry different weights, so a reader that cannot tell them apart cannot interpret the weights it is given.

Unspecified¶: Written before the branch was recorded.

SystematicResampling¶: Systematic resampling of the Feynman-Kac weights.

MinimumInformation¶: GIBBON information about the same-system minimum energy.

Implementations

impl PopulationSelection¶

Functions

fn as_trace_str(self) -> &'static str¶: Stable token used in the replica event stream.

enum ProtocolError¶

Protocol validation or decoding failure.

UnsupportedVersion¶

The request version is not supported.

received: u16¶: Received version.

supported: u16¶: Supported version.

CampaignMismatch¶: Campaign identities differ.

EnsembleMismatch¶: Ensemble identities differ.

ReplicaMismatch¶: Replica identities differ.

SignatureMismatch¶: System signature digests differ.

SignatureDigestLength¶

Signature digest has a noncanonical length.

actual: usize¶: Received digest length.

Malformed(String)¶: Cap’n Proto input is malformed or outside the schema.

enum ProtocolRejection¶

Typed coordinator rejection returned on the wire.

Malformed¶: Request bytes do not satisfy the schema.

UnsupportedVersion¶: Protocol version is unsupported.

CampaignMismatch¶: Campaign identity differs.

EnsembleMismatch¶: Ensemble identity differs.

ReplicaMismatch¶: Replica is outside the configured ensemble.

SignatureMismatch¶: System signature differs.

SequenceReplay¶: Sequence was already used by different content.

SequenceRegression¶: Sequence moves backward.

SnapshotRegression¶: Client snapshot version exceeds coordinator state.

ValidationRejected¶: Scientific validation rejected the record.

Traits implemented

impl From<RejectionKind> for ProtocolRejection¶

enum TransitionDestination¶

Resolved or unresolved result of one action-labelled perturb–quench step.

Unresolved¶: The step did not yield a valid classified minimum.

Resolved(CatalogCandidate)¶: The step reached a candidate requiring receiving-side validation.

Structs and Unions

struct AcceptedReply¶

Accepted coordinator response.

event_sequence: u64¶: Request sequence being acknowledged.

duplicate: bool¶: Whether an identical request was replayed.

snapshot: CatalogSnapshot¶: Coordinator state after the request.

payload: AcceptedPayload¶: Operation-specific scientific result.

struct BoundaryCrossingRecord¶

One validated adopted crossing shared across cooperative replicas.

action: String¶: Target-blind move family that generated the crossing.

from: Vec<f64>¶: Validated source minimum coordinates.

to: Vec<f64>¶: Validated destination minimum coordinates.

source_basin: u64¶: Fixed-census source basin.

destination_basin: u64¶: Fixed-census destination basin.

struct BridgeAssignmentRecord¶

A bridge segment assignment: the string, the region to confine to, and an entry state when one is stored.

bridge: u64¶: Bridge identifier.

from_basin: u64¶: Catalog basin at the A endpoint.

to_basin: u64¶: Catalog basin at the B endpoint.

images: Vec<f64>¶: String images, row-major: image_count rows of the descriptor dimension.

image_count: u32¶: Number of images.

region: u32¶: Region index this replica confines to.

tube_radius: f64¶: Distance from the endpoint chord beyond which a state has left the bridge tube.

entry: Option<Vec<f64>>¶: Stored entry state for the region, when any crossing has deposited one.

struct BridgeCrossingRecord¶

One attempted exit from a bridge region, as the confined replica reports it.

bridge: u64¶: Bridge identifier.

from_region: u32¶: Region the replica was confined to.

to_region: u32¶: Region the attempted exit entered.

descriptor: Vec<f64>¶: Descriptor at the crossing point.

state: Vec<f64>¶: Full state at the crossing point.

energy: f64¶: Energy at the crossing point.

struct CatalogCandidate¶

Complete scientific candidate carried under the request identity.

producer_replica: u32¶: Replica that produced the candidate.

coordinates: Vec<f64>¶: Cartesian coordinates in system-signature order.

cell: Option<[f64; 9]>¶: Row-major cell, or no cell for a finite nonperiodic system.

energy: f64¶: Producer-side quenched energy.

forces: Vec<f64>¶: Producer-side forces in coordinate order.

gradient_norm: f64¶: Producer-side Euclidean gradient norm.

descriptor: Vec<f64>¶: Descriptor under the declared schema.

descriptor_schema_version: u32¶: Descriptor schema version.

quench_converged: bool¶: Whether the producer quench met its convergence contract.

charged_work: u64¶: Producer charged-work counter at this candidate.

event_sequence: u64¶: Producer event sequence retained inside the immutable record.

seed: u64¶: Producer random-seed identity.

census_basin: Option<u64>¶: Coordinator-assigned fixed-census basin for returned representatives.

struct CatalogFrontierPost¶

A raw, unquenched excursion state on the road out of the occupied floor. The ensemble’s forward-flux ladder shares these so a stuck chain restarts from live progress instead of walking the whole road alone (Hop.cloning_dominates); a post is never a minimum and never enters the census.

gap: f64¶: DECAF L1 gap from the producer’s floor at capture.

energy: f64¶: Raw energy at capture, unquenched by construction.

coordinates: Vec<f64>¶: Cartesian coordinates of the live excursion state.

producer_replica: u32¶: Replica that walked there.

posted_sequence: u64¶: Producer event sequence at the post, for freshness accounting.

struct CatalogIdentity¶

Complete identity carried by every catalog request.

campaign: String¶: Campaign identity.

ensemble: String¶: Independent ensemble identity.

replica: u32¶: Replica identity within the ensemble.

signature_digest: [u8; 32]¶: Canonical system-signature digest.

struct CatalogLedgerEvent¶

One exact charged-work boundary carried inside a replay-safe batch.

sequence: u64¶: Replica-global request sequence assigned to this boundary.

kind: u16¶: Stable crate::cooperative_search::ledger::ChargeKind wire code.

charged_calls: u64¶: Potential calls charged at this boundary.

cumulative_charged: u64¶: Replica charged counter including this boundary.

struct CatalogMutation¶

Catalog identity changes returned by a serialized admission attempt.

basin_id: u64¶: Fixed-census basin assigned to the offered candidate.

new_basin: bool¶: Whether the exact witness opened this fixed-census basin.

kind: CatalogMutationKind¶: Exact admission or rejection class.

evicted: Vec<u64>¶: Fixed-census basins removed from the active catalog.

incumbent_basin: Option<u64>¶: Active incumbent after the attempt.

struct CatalogRequest¶

Complete catalog request.

protocol_version: u16¶: Requested protocol version.

identity: CatalogIdentity¶: Campaign, ensemble, replica, and system identity.

event_sequence: u64¶: Monotone replica event sequence.

snapshot_version: u64¶: Latest snapshot version observed by the replica.

operation: CatalogOperation¶: Requested operation.

struct CatalogRideConnection¶

Producer-side stationary structures proposed as one connection.

saddle: CatalogCandidate¶: Force-converged saddle candidate requiring receiving-side index certification.

endpoints: [CatalogCandidate; 2]¶: Force-converged downhill endpoints requiring receiving-side basin assignment.

struct CatalogRideReport¶

Charged producer report for one claimed transition experiment.

work: u64¶: Coordinator-issued work identifier.

charged_evaluations: u64¶: PES evaluations consumed by the complete ride and certification.

outcome: CatalogRideOutcome¶: Candidate connection or explicit failure class.

struct CatalogRideSaddleEvidence¶

Producer-side index-one saddle whose branch identity remains unresolved.

saddle: CatalogCandidate¶: Force-converged saddle requiring fresh receiving-side certification.

failure: RideFailure¶: Connectivity classification produced after saddle convergence.

struct CatalogRideWork¶

Exclusive ride assignment and its validated source minimum.

order: RideWorkOrder¶: Portfolio arm, representative atom, attempt, and seed.

source: CatalogCandidate¶: Receiving-side validated source structure.

avoid_saddles: Vec<CatalogCandidate>¶: Receiving-certified same-source saddles that new modes must avoid.

struct CatalogSnapshot¶

Snapshot counters returned by every accepted request.

version: u64¶: Monotone coordinator snapshot version.

census_visits: u64¶: Exact fixed-census visit total.

active_entries: u32¶: Number of finite active entries.

aggregate_charged: u64¶: Sum of the latest exact charged counters from all replicas.

aggregate_budget: u64¶: Declared ensemble charged-work budget.

struct CoordinatorStatus¶

Read-only aggregate state for an observer outside the ensemble.

snapshot_version: u64¶: Monotone coordinator snapshot version.

open_epoch: u64¶: Population epoch currently open.

epoch_submitted: u32¶: Members submitted to the open epoch.

epoch_required: u32¶: Members the open epoch still requires.

census_visits: u64¶: Exact census visit total.

active_entries: u32¶: Active catalog entries.

aggregate_charged: u64¶: Sum of the replicas’ recorded force evaluations.

aggregate_budget: u64¶: Declared ensemble budget.

replicas: Vec<ReplicaProgress>¶: Per-replica progress, in replica order.

landscape_basins: u32¶: Basins the transition stream has linked into the referee’s graph.

unique_saddles: u64¶: Unique exact index-one saddles certified by the coordinator.

unique_edges: u64¶: Unique unordered pairs of distinct exact basins.

unique_degenerate_rearrangements: u64¶: Unique saddles connecting symmetry-equivalent basin representatives.

certified_connections: u64¶: Accepted index-one reports, including exact reobservations.

seam: Option<LandscapeSeam>¶: The referee’s seam, when at least two basins have been linked.

roster_version: u64¶: Monotone live-roster version.

live_replicas: Vec<u32>¶: Replica identities currently live on the coordinator roster.

ticks: u64¶: Coordinator clock ticks delivered so far.

spawn_requested: u32¶: Spawn count still outstanding from the scaling policy.

struct DescriptorHoleProposal¶

Seeded target-free descriptor-hole result.

target: Vec<f64>¶: Selected unit-sphere descriptor target.

increment: Vec<f64>¶: Descriptor increment from the supplied current point.

nearest_catalog_distance: f64¶: Distance from the target to its nearest catalog descriptor.

struct LandscapeSeam¶

The seam between the two most weakly coupled communities of the explored landscape, as the referee reports it to an observer.

algebraic_connectivity: f64¶: Second Laplacian eigenvalue of the basin transition graph.

conductance: f64¶: Cut weight over the smaller community’s volume.

community_left: u32¶: Basin count on the left side.

community_right: u32¶: Basin count on the right side.

left_basin: u64¶: Best-anchored basin of the left community.

right_basin: u64¶: Best-anchored basin of the right community.

struct PolicyState¶

Exact coordinator evidence used by the cooperative policy.

total_visits: u64¶: Exact number of fixed-census observations.

singleton_basins: u64¶: Exact number of singleton basins in the fixed census.

local_basin_visits: u64¶: Exact visits assigned to the candidate’s basin, or zero if unassigned.

globally_saturated: bool¶: Whether the fixed census meets its declared saturation rule.

relation: CatalogRelation¶: Candidate relation to the active catalog.

aggregate_charged: u64¶: Sum of the latest exact charged counters from all replicas.

aggregate_budget: u64¶: Declared ensemble charged-work budget.

local_basin: Option<u64>¶: Stable census-basin identifier, or None for an unassigned descriptor.

local_basin_distance: f64¶: Distance from the query descriptor to its assigned immutable medoid.

novelty: f64¶: Universal descriptor acquisition from novelty, GP uncertainty, model disagreement, expected improvement, and graph residual uncertainty.

transition_uncertainty: f64¶: Posterior uncertainty of the latent Gaussian basin-transition field.

explore_collapsed: bool¶: Explore-role chains have mixed onto one attractor.

certified_attractor: bool¶: Incumbent attractor won the occupancy contest against competitors.

pruned: bool¶: Successive halving discarded this walk at a rung.

leftover_lambda: f64¶

Leftover-SOAP (lambda) of the descriptor in this request.

One frame, not the replica’s path maximum: the coordinator holds the maximum for the interface ladder, and a client that tagged every frame with it would have a non-decreasing series in which no frame is further from the occupied well than any other.

interface_rank: u32¶: TIS interface rank. u32::MAX is the occupied-packing champion.

interface_threshold: f64¶: Threshold (lambda_i) this extra must reach.

interface_count: u32¶: Number of leftover-SOAP interfaces in the current ladder.

occupied_family_count: u32¶: Occupied DECAF families on the packing book.

packing_saturated: bool¶: DECAF-family Good–Turing: unseen packing mass is small.

leftover_dwell: bool¶: Consecutive leftover-SOAP occupancy_gt records under the ceiling.

ei_exhausted: bool¶: FunnelModel Jones EI on seen packings is at most the model noise.

min_families: u32¶: Measured Fiedler-and-DECAF family floor for this hop graph.

discovery_role: DiscoveryRole¶: Joint-minimum-information role for this same-system replica.

discovery_epoch: u64¶: Coordinator evidence epoch behind the stable shared-batch assignment.

basin_unseen_mass_upper: f64¶: One-sided upper bound on unseen exact-basin mass.

saddle_unseen_mass_upper: f64¶: One-sided upper bound on unseen exact-saddle mass.

basin_discovery_attempts: u64¶: Same-system basin-escape attempts retained by the replay-safe ledger.

basin_discovery_charged: u64¶: Potential calls charged to same-system basin-escape attempts.

saddle_discovery_attempts: u64¶: Same-system saddle-ride attempts retained by the replay-safe ledger.

saddle_discovery_charged: u64¶: Potential calls charged to same-system saddle-ride attempts.

saddle_coverage_saturated: bool¶: Whether exact-saddle reobservations meet the declared coverage rule.

retired: bool¶: Successive-halving retire decision for this replica’s next checkpoint.

struct PopulationEpochState¶

Barrier state for one synchronous population epoch.

epoch: u64¶: Charged-work synchronization epoch.

submitted: u32¶: Unique replica submissions received.

required: u32¶: Complete population size required.

plan: Option<PopulationPlan>¶: Immutable plan once every replica has submitted.

struct PopulationPlan¶

Replica-addressed fixed-population plan returned by the coordinator.

epoch: u64¶: Charged-work synchronization epoch.

destinations: Vec<u32>¶: Destination replicas in stable order.

parents: Vec<u32>¶: Parent replica paired with every destination.

weights: Vec<f64>¶: Normalized source weights in stable replica order.

effective_sample_size: f64¶: Kish effective sample size before resampling.

unique_parents: u32¶: Number of represented source replicas.

max_family_size: u32¶: Largest realized offspring family.

offspring_variance: f64¶: Population variance of offspring counts.

parent_candidates: Vec<CatalogCandidate>¶: Validated parent record paired with every destination.

selection: PopulationSelection¶: Branch that produced this parent map.

struct ReplicaProgress¶

Optional scientific payload returned by an accepted operation. One replica’s progress inside a coordinator status report.

replica: u32¶: Replica identifier.

charged_work: u64¶: Force evaluations the replica has recorded.

best_energy: f64¶: Lowest validated energy the coordinator holds for the replica.

struct RosterReply¶

Versioned live roster returned by attach, detach, tick, and scale.

version: u64¶: Monotone roster version after the operation.

live: Vec<u32>¶: Replica identities currently live.

retired: Vec<u32>¶: Replica identities retired from the live set.

spawn_requested: u32¶: Spawn count still outstanding from the scaling policy.

mod catalog_rpc¶

`mod catalog_rpc`¶