Module ctx 

The boundary between the controller and its environment.

ClusterControllerCtx is the single, strategy-agnostic boundary through which the controller pulls the signals a tick examines and applies the catalog mutations it derives. It carries primitive signals in and primitive catalog mutations out; it has no per-strategy state or vocabulary. The controller crate knows nothing about the Coordinator. The Coordinator implements this trait, which is what makes the controller testable against a fake implementation and extractable later without touching controller code.

The interface is pull-based: a tick fetches only the signals it actually examines (no eager all-clusters-all-replicas snapshot is pushed in), and the controller drives what is fetched. Read methods are batched so a separate-task deployment can bound its round-trips to the Coordinator.

Structs

AvailabilityZones

The availability zones a managed cluster’s replicas are provisioned across, in configured provisioning order.

BurstRecord

An active hydration-burst record, mirrored from durable state.

BurstWrite

A write to the burst record, bundled with its audit intent. See ReconfigurationWrite. A bookkeeping rewrite of an existing record (the linger stamp and its reset) declares audit: None.

ClusterState

The durable state of a single managed cluster plus its observed replicas, as pulled through the ctx for one reconcile tick.

ExpectedClusterState

Compare-and-append witness over a managed cluster’s durable config: the fields a conditional write is conditioned on. The applier applies the write only if the cluster’s current config still projects to an equal witness.

ObservedReplica

A replica that actually exists on a cluster, as observed through the ctx.

ReconfigurationRecord

The latest graceful reconfiguration record, mirrored from durable state.

ReconfigurationTarget

The full config shape a reconfiguration is moving the cluster to. Distinct from a replica shape because it additionally carries replication_factor, a cluster-level rather than replica-level dimension.

ReconfigurationWrite

A write to the reconfiguration record, bundled with the audit intent declaring which lifecycle transition the write represents.

ReplicaShape

The config dimensions that distinguish one replica from another. Two replicas with equal shape are interchangeable. An AVAILABILITY ZONES difference is a shape difference, but only as an unordered pool: reordering the same zones does not change a replica’s shape (see ReplicaShape::matches).

StateWrite

A durable state mutation a strategy’s update_state asks for: cut over the realized config to a target and/or write or clear the reconfiguration/burst records. The reconcile kernel pairs it with the ExpectedClusterState it was derived from for the compare-and-append guard.

Enums

ApplyOutcome

The outcome of applying one tick’s batch of Decisions.

BurstAudit

The lifecycle transition a write to the burst record represents, declared by the writer like ReconfigurationAudit. A burst record is also rewritten in place for bookkeeping (stamping or resetting the linger clock), which is not a lifecycle transition and declares no audit.

BurstFinishCause

Why a hydration burst finished, known only to the strategy arm that decided the teardown.

Decision

A single command the controller emits for the environment to transact. The apply path interprets these and turns them into catalog operations.

OnTimeout

The action a graceful reconfiguration applies once its deadline passes with the target replicas not yet hydrated. Success always takes precedence: a hydrated target cuts over regardless of this. A plain-data mirror of mz_sql::plan::OnTimeoutAction, free of a dependency on the SQL layer.

ReconfigurationAudit

The lifecycle transition a write to the reconfiguration record represents, declared by the writer at the decision point and carried alongside the state so the audit event is emitted in the same catalog transaction as the write. A plain-data mirror of the audit-log lifecycle vocabulary, free of a dependency on mz-audit-log.

ReconfigurationStatus

The status of the latest graceful reconfiguration record.

Traits

ClusterControllerCtx

The strategy-agnostic pull/apply interface between the controller and its environment.