mod client

module client

Timeout-bounded client for one isolated catalog coordinator.

Enums

enum CatalogAccess

Result of a coordinator read when local execution remains available.

Remote(CatalogSnapshot)

The coordinator returned a current snapshot.

LocalFallback

The coordinator was unavailable within the configured deadline.

enum CatalogClientError

Transport, wire, or typed coordinator rejection.

Transport(std::io::Error)

TCP or stream I/O failed.

Protocol(ProtocolError)

Cap’n Proto encoding or decoding failed.

Rejected(ProtocolRejection)

Coordinator rejected the request without mutation.

Traits implemented

impl PartialEq for CatalogClientError

enum CatalogClientEvent

Observable client-side events that affect cooperative execution.

LocalFallback

A coordinator operation failed and execution continued locally.

event_sequence: u64

Replica event sequence associated with the failed operation.

enum SyncScheduleError

Invalid cooperative synchronization schedule or slice charge.

ZeroBound

Synchronization bounds must be nonzero.

SliceChargeExceeded

One slice exceeded the declared maximum catalog calls.

charged: u64

Catalog calls charged to the completed slice.

maximum: u64

Declared maximum catalog calls per slice.

BoundOverflow

The staleness bound cannot be represented as a u64.

Structs and Unions

struct CatalogClient

Persistent client bound to one replica identity.

Implementations

impl CatalogClient

Functions

fn attach(&mut self, event_sequence: u64) -> Result<RosterReply, CatalogClientError>

Admit this client’s replica onto the live roster.

fn boundary_crossing(&mut self, event_sequence: u64, current: Vec<f64>, draw: u64) -> Result<Option<BoundaryCrossingRecord>, CatalogClientError>

Sample one observed adopted crossing from the query attraction region.

fn bridge_assignment(&mut self, event_sequence: u64, draw: u64) -> Result<Option<crate::catalog_rpc::BridgeAssignmentRecord>, CatalogClientError>

Poll for a bridge segment assignment. None when no bridge is commissioned; the draw selects among the region’s stored entries.

fn bridge_crossing(&mut self, event_sequence: u64, crossing: crate::catalog_rpc::BridgeCrossingRecord) -> Result<(), CatalogClientError>

Report one attempted exit from a bridge region.

fn claim_ride(&mut self, event_sequence: u64, seed: u64) -> Result<Option<CatalogRideWork>, CatalogClientError>

Claim one exclusive same-system transition experiment.

fn connect(addr: SocketAddr, identity: CatalogIdentity, config: ClientConfig) -> Result<Self, CatalogClientError>

Connect to a coordinator with explicit deadlines.

fn descriptor_hole(&mut self, event_sequence: u64, current: Vec<f64>, samples: u32, draw: u64) -> Result<DescriptorHoleProposal, CatalogClientError>

Request one seeded target-free descriptor-hole proposal.

fn detach(&mut self, event_sequence: u64, reason: impl Into<String>) -> Result<RosterReply, CatalogClientError>

Retire this client’s replica from the live roster.

fn draw_frontier(&mut self, event_sequence: u64, draw: u64) -> Result<Option<CatalogFrontierPost>, CatalogClientError>

Draw one shared frontier post, if the ladder holds any.

fn events(&mut self) -> Vec<CoordinatorEvent>

Drain queued coordinator events.

fn last_event_sequence(&self) -> u64

Highest event sequence this client has already sent.

fn observe(&mut self) -> Result<CoordinatorStatus, CatalogClientError>

Read coordinator status without presenting an identity.

fn observer_status(&mut self, event_sequence: u64) -> Result<crate::catalog_rpc::CoordinatorStatus, CatalogClientError>

Read-only aggregate status for an observer bound to the coordinator’s campaign, ensemble, and system signature. The replica id is ignored.

fn observer_status_frame(&mut self, event_sequence: u64) -> Result<Vec<u8>, CatalogClientError>

The framed Cap’n Proto reply to a status query, byte-exact as the coordinator sent it, validated as a status before it is handed on.

fn offer_candidate(&mut self, event_sequence: u64, candidate: CatalogCandidate) -> Result<MutationReceipt, CatalogClientError>

Validate, observe, and offer one candidate to the active catalog.

fn policy_state(&mut self, event_sequence: u64, descriptor: Vec<f64>, energy: f64) -> Result<PolicyState, CatalogClientError>

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

fn policy_state_with_lambda(&mut self, event_sequence: u64, descriptor: Vec<f64>, energy: f64, leftover_lambda: f64) -> Result<PolicyStateReceipt, CatalogClientError>

Policy evidence with the replica’s leftover-SOAP (lambda).

fn policy_state_with_snapshot(&mut self, event_sequence: u64, descriptor: Vec<f64>, energy: f64) -> Result<PolicyStateReceipt, CatalogClientError>

Read exact policy evidence together with its coordinator snapshot.

fn population_abstain_with_snapshot(&mut self, event_sequence: u64, epoch: u64) -> Result<PopulationEpochReceipt, CatalogClientError>

Decline to submit to one epoch and retain its coordinator snapshot.

Called when the barrier arrives and the replica’s own state yields no validated representative, so that the replicas already waiting are released instead of polling until their budgets drain.

fn population_join_with_snapshot(&mut self, event_sequence: u64, epoch: u64) -> Result<PopulationEpochReceipt, CatalogClientError>

Join an epoch by reference and retain its coordinator snapshot.

The coordinator forms the member from the replica’s best candidate it has already validated, so no state crosses the wire at barrier time and no re-validation is charged. Rejected when nothing is on file, which the caller answers by abstaining.

fn population_plan(&mut self, event_sequence: u64, epoch: u64) -> Result<PopulationEpochState, CatalogClientError>

Poll a synchronous population epoch without resubmitting evidence.

fn population_plan_with_snapshot(&mut self, event_sequence: u64, epoch: u64) -> Result<PopulationEpochReceipt, CatalogClientError>

Poll a population plan and retain its coordinator snapshot.

fn post_frontier(&mut self, event_sequence: u64, post: CatalogFrontierPost) -> Result<(), CatalogClientError>

Post one raw frontier excursion state to the shared ladder.

fn record_ledger_batch(&mut self, event_sequence: u64, events: Vec<CatalogLedgerEvent>) -> Result<MutationReceipt, CatalogClientError>

Submit consecutive exact charged-work boundaries in one request.

fn record_ledger_event(&mut self, event_sequence: u64, kind: ChargeKind, charged_calls: u64, cumulative_charged: u64) -> Result<MutationReceipt, CatalogClientError>

Submit one exact replay-safe charged-work boundary.

fn record_transition(&mut self, event_sequence: u64, action: impl Into<String>, destination: TransitionDestination, adopted: bool) -> Result<MutationReceipt, CatalogClientError>

Record one action-conditioned transition from the registered live basin.

fn record_visit(&mut self, event_sequence: u64, candidate: CatalogCandidate) -> Result<MutationReceipt, CatalogClientError>

Record one exact census observation.

fn report_ride(&mut self, event_sequence: u64, report: CatalogRideReport) -> Result<crate::ride_ledger::RideCredit, CatalogClientError>

Share the charged result of one transition experiment.

fn sample_basin(&mut self, event_sequence: u64, basin: u64) -> Result<Option<CatalogCandidate>, CatalogClientError>

Retrieve the validated representative of one immutable census basin.

fn sample_candidate(&mut self, event_sequence: u64, draw: u64) -> Result<Option<CatalogCandidate>, CatalogClientError>

Draw one validated active-catalog candidate with an explicit seed.

fn scale(&mut self, event_sequence: u64, live_target: u32) -> Result<RosterReply, CatalogClientError>

Request a manual live-population target.

fn session_call(&mut self, request: CatalogRequest) -> Result<CatalogReply, CatalogClientError>

Send one catalog request on the bound session.

fn session_call_digest(&mut self, version: u16, digest: &[u8], sequence: u64) -> Result<CatalogReply, CatalogClientError>

Send a session call whose identity digest is not necessarily 32 bytes.

fn snapshot(&mut self, event_sequence: u64) -> Result<CatalogSnapshot, CatalogClientError>

Read the current coordinator snapshot.

fn snapshot_or_fallback(&mut self, event_sequence: u64, events: &mut Vec<CatalogClientEvent>) -> CatalogAccess

Read a snapshot or record an explicit local-fallback event.

fn submit_population(&mut self, event_sequence: u64, epoch: u64, candidate: CatalogCandidate) -> Result<PopulationEpochState, CatalogClientError>

Submit one validated representative to a synchronous population epoch.

fn submit_population_with_snapshot(&mut self, event_sequence: u64, epoch: u64, candidate: CatalogCandidate) -> Result<PopulationEpochReceipt, CatalogClientError>

Submit population evidence and retain its coordinator snapshot.

fn tick(&mut self, event_sequence: u64, millis: u64) -> Result<AcceptedPayload, CatalogClientError>

Advance the coordinator clock by one tick of millis milliseconds.

Traits implemented

impl Drop for CatalogClient

struct ClientConfig

Connection and I/O deadlines for a catalog client.

connect_timeout: Duration

TCP connection deadline.

io_timeout: Duration

Read and write deadline.

Traits implemented

impl Default for ClientConfig

struct MutationReceipt

Version and replay classification for one accepted mutation.

version: u64

Coordinator snapshot version after the mutation.

duplicate: bool

Whether the coordinator recognized an identical replay.

snapshot: CatalogSnapshot

Coordinator counters after the mutation or replay.

catalog: Option<CatalogMutation>

Exact active-catalog result for an offer operation.

struct PolicyStateReceipt

Exact policy evidence and the coordinator snapshot that carried it.

state: PolicyState

Exact census and active-catalog evidence.

snapshot: CatalogSnapshot

Coordinator snapshot observed with the evidence.

struct PopulationEpochReceipt

Synchronous population state and the coordinator snapshot that carried it.

state: PopulationEpochState

Pending barrier evidence or a complete parent plan.

snapshot: CatalogSnapshot

Coordinator snapshot observed with the evidence.

struct SyncSchedule

Counter-based synchronization schedule with a declared staleness bound.

Implementations

impl SyncSchedule

Functions

fn maximum_staleness_calls(&self) -> u64

Maximum catalog calls a replica can make between synchronizations.

fn new(interval_slices: u64, maximum_calls_per_slice: u64) -> Result<Self, SyncScheduleError>

Construct a schedule from a slice interval and per-slice call bound.

fn record_slice(&mut self, charged_calls: u64) -> Result<bool, SyncScheduleError>

Charge one completed slice and report whether synchronization is due.

fn synchronized(&mut self)

Reset the staleness counter after a successful synchronization.