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. The signals in are primitive and carry no per-strategy state; the decisions out are primitive catalog mutations plus per-tick audit attribution. A create carries the CreateReason of the winning strategy behind it, which the environment turns into the audit event. 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

AutoScalingPolicy

The user-configured autoscaling policy of a managed cluster, mirrored from durable state. A plain-data mirror of mz_sql::plan::AutoScalingStrategy, free of a dependency on the SQL layer.

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. Every replica physically on the cluster appears here, whether or not the controller owns it; Self::owned_shape is the ownership test.

OnHydrationPolicy

The ON HYDRATION burst sub-policy: while some object on the cluster is not hydrated on a steady replica, run one extra replica at hydration_size to accelerate hydration, lingering for linger_duration after the steady set hydrates.

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.

RefreshMvInfo

One REFRESH materialized view bound to a scheduled cluster, as the on-refresh strategy needs to see it.

RefreshWindowDecision

The on-refresh strategy’s per-tick window decision: which bound REFRESH MVs keep a scheduled cluster on, and why. The window is open iff either list is non-empty, so an open window always has an explanation.

RefreshWindowInputs

The live signals the on-refresh strategy reads to decide whether a scheduled cluster is inside a refresh window: the current read timestamp, the Persist-compaction time estimate, and the bound REFRESH MVs’ frontiers and schedules.

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.

ClusterSchedule

A managed cluster’s scheduling policy, mirrored from durable state. A plain-data mirror of mz_sql::plan::ClusterSchedule, free of a dependency on the SQL layer.

CreateReason

Why a strategy desires a replica slot: the audit attribution a create decision carries. When several strategies desire the same shape the winning reason is decided by CreateReason::outranks, since the audit event carries exactly one reason.

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.