parti

type AlertLevel int

type Assignment = types.Assignment

type AssignmentDivergenceMetricsRecorder = types.AssignmentDivergenceMetricsRecorder

type AssignmentMetrics = types.AssignmentMetrics

type AssignmentStrategy = types.AssignmentStrategy

type AuthorityChoice int

type CalculatorMetrics = types.CalculatorMetrics

type CapabilityReporter interface {
	// Capabilities returns the OR of capability bits this reporter has
	// successfully wired at runtime. Must be safe for concurrent use,
	// non-blocking, and monotonic for runtime-wireup bits.
	Capabilities() uint32
}

type CompositeConsumerUpdater struct {
	// contains filtered or unexported fields
}

type Config struct {
	// WorkerIDPrefix is the prefix for worker IDs (e.g., "worker" produces "worker-0", "worker-1").
	WorkerIDPrefix string `yaml:"workerIdPrefix" default:"worker" validate:"required"`

	// WorkerLabels is this worker's label set, fixed at process startup.
	// Labeled partitions (Partition.Label) are assigned only to workers
	// whose set contains the partition's label. Validated with
	// partition-key charset rules; sorted and deduplicated. At most 16
	// labels, each at most 64 bytes. Empty = unlabeled worker.
	// WithWorkerLabels overrides this field when both are set.
	WorkerLabels []string `yaml:"workerLabels"`

	// UnlabeledPartitionPolicy controls which workers receive unlabeled
	// partitions. "dedicated" (default): unlabeled workers only, falling
	// back to all workers when no unlabeled worker is live. "shared":
	// all workers. Leader-side; MUST be identical across every manager
	// in the fleet (same contract as the AssignmentStrategy choice).
	UnlabeledPartitionPolicy string `yaml:"unlabeledPartitionPolicy" default:"dedicated" validate:"oneof=dedicated shared"`

	// LabelSpillGrace is how long a label's worker pool must be
	// continuously empty before its partitions spill to the fallback
	// ladder. 0 spills immediately. Leader-side; MUST be fleet-uniform.
	LabelSpillGrace time.Duration `yaml:"labelSpillGrace" default:"60s" validate:"gte=0"`

	// WorkerIDMin is the minimum stable ID number (inclusive).
	// Set to 0 for most use cases.
	WorkerIDMin int `yaml:"workerIdMin" default:"0" validate:"gte=0"`

	// WorkerIDMax is the maximum stable ID number (inclusive).
	// Determines the maximum number of concurrent workers: (WorkerIDMax - WorkerIDMin + 1).
	// For example, WorkerIDMin=0 and WorkerIDMax=999 allows up to 1000 workers.
	WorkerIDMax int `yaml:"workerIdMax" default:"999" validate:"gtefield=WorkerIDMin"`

	// WorkerIDTTL is how long a worker ID claim remains valid in the key-value store.
	// Must be >= HeartbeatTTL (validated via the `gtefield=HeartbeatTTL` tag below;
	// setting WorkerIDTTL below HeartbeatTTL causes Manager.Start to fail
	// validation). Renewal writes one KV op per worker every
	// WorkerIDTTL/3, so longer values reduce steady-state IOPS at the cost of slower
	// ID reclamation after a worker exits.
	// Recommended: 3-5x HeartbeatTTL. Default 75s is 5x the default HeartbeatTTL (15s).
	// The stableID KV bucket's MaxAge is reconciled to exactly WorkerIDTTL on
	// Manager.Start: an existing bucket whose TTL differs (most dangerously 0,
	// which leaks worker IDs on ungraceful restart) is corrected, and a
	// deliberately-longer operator TTL is shortened to WorkerIDTTL.
	WorkerIDTTL time.Duration `yaml:"workerIdTtl" default:"75s" validate:"gt=0,gtefield=HeartbeatTTL"`

	// HeartbeatInterval is how often workers publish heartbeat messages.
	// Shorter intervals provide faster failure detection but increase KV write load
	// (one write per worker per interval, amplified by JetStream replication and fsync).
	// Recommended: 3-10 seconds.
	HeartbeatInterval time.Duration `yaml:"heartbeatInterval" default:"5s" validate:"gt=0"`

	// HeartbeatTTL is how long heartbeat messages remain valid before a worker is considered failed.
	// Must be greater than HeartbeatInterval.
	// Recommended: 3x HeartbeatInterval.
	HeartbeatTTL time.Duration `yaml:"heartbeatTtl" default:"15s" validate:"gt=0"`

	// ColdStartWindow is the stabilization period when starting workers from zero.
	// During this window, partition assignment is delayed to allow all initial workers to join.
	// Recommended: 30 seconds.
	ColdStartWindow time.Duration `yaml:"coldStartWindow" default:"30s" validate:"gt=0,gtefield=PlannedScaleWindow"`

	// PlannedScaleWindow is the stabilization period during rolling updates or planned scaling.
	// Shorter than ColdStartWindow to minimize disruption during controlled changes.
	// Recommended: 10 seconds.
	PlannedScaleWindow time.Duration `yaml:"plannedScaleWindow" default:"10s" validate:"gt=0"`

	// EmergencyGracePeriod is the minimum time a worker must be missing before
	// triggering emergency rebalance. Prevents false positives from transient
	// network issues or brief connectivity loss.
	//
	// Default: 0 (auto-calculated as 1.5 * HeartbeatInterval)
	// Recommended: 1.5-2.0 * HeartbeatInterval
	// Constraint: Must be <= HeartbeatTTL
	EmergencyGracePeriod time.Duration `yaml:"emergencyGracePeriod" validate:"ltefield=HeartbeatTTL"`

	// RestartDetectionRatio historically classified a restart as cold start vs
	// planned (if failed/total > ratio, treat as cold start).
	//
	// NOTE: this knob is currently a NO-OP. The cold-start-vs-planned-scale window
	// selector that consumed it was removed as dead code, so the value is still
	// accepted and validated for config compatibility but no longer affects
	// behavior. Its removal is deferred to a future major version (public-API change).
	RestartDetectionRatio float64 `yaml:"restartDetectionRatio" default:"0.5" validate:"gte=0,lte=1"`

	// OperationTimeout is the timeout for KV operations (get, put, delete).
	// Recommended: 10 seconds.
	OperationTimeout time.Duration `yaml:"operationTimeout" default:"10s" validate:"gt=0"`

	// BucketEpochProbeInterval is how often the bucket-epoch fence (see
	// monitorBucketEpochs) polls each Parti-owned KV bucket for a
	// wipe-and-recreate event. This was previously coupled to
	// OperationTimeout — the same knob that bounds every individual KV
	// operation's deadline — so changing one unintentionally changed the
	// other. This field decouples the probe cadence from that deadline.
	// Default 10s preserves the prior default behavior for deployments
	// that left OperationTimeout at its own 10s default; deployments that
	// TUNED OperationTimeout and relied on the old coupled cadence must set
	// this field to their previous OperationTimeout value to preserve it.
	// The per-probe deadline is still OperationTimeout (see
	// probeBucketCreated); this field controls only how often a probe pass
	// runs.
	BucketEpochProbeInterval time.Duration `yaml:"bucketEpochProbeInterval" default:"10s" validate:"gt=0"`

	// ElectionTimeout is the maximum time to wait for leader election to complete.
	// Also drives leader lease renewal frequency (ElectionTimeout/3). Longer values
	// reduce KV write load at the cost of slower failover detection.
	// Recommended: 5-15 seconds.
	ElectionTimeout time.Duration `yaml:"electionTimeout" default:"10s" validate:"gt=0"`

	// StartupTimeout is the maximum time to wait for the manager to fully start.
	// Includes worker ID claiming, leader election, and initial partition assignment.
	// Must be at least ColdStartWindow + ElectionTimeout with some headroom.
	// Recommended: 60 seconds.
	StartupTimeout time.Duration `yaml:"startupTimeout" default:"60s" validate:"gt=0"`

	// ShutdownTimeout is the maximum time to wait for graceful shutdown.
	// Includes releasing worker ID, stopping heartbeats, and cleanup operations.
	// Recommended: 10 seconds.
	ShutdownTimeout time.Duration `yaml:"shutdownTimeout" default:"10s" validate:"gt=0"`

	// RebalanceCooldown is the minimum time between rebalancing operations.
	//
	// Enforces rate limiting BEFORE stabilization windows to prevent thrashing
	// during rapid topology changes. If a rebalance was completed <RebalanceCooldown
	// ago, new topology changes are deferred until the interval expires.
	//
	// Default: 10 seconds
	// Recommendation: Should be <= PlannedScaleWindow for proper coordination
	//
	// Note: This was renamed from MinRebalanceInterval in v0.x for semantic clarity.
	RebalanceCooldown time.Duration `yaml:"rebalanceCooldown" default:"10s" validate:"gt=0,ltefield=PlannedScaleWindow"`

	// KVBuckets controls NATS JetStream KV bucket configuration.
	KVBuckets KVBucketConfig `yaml:"kvBuckets"`

	// DegradedAlert controls alert emission during degraded mode operation.
	DegradedAlert DegradedAlertConfig `yaml:"degradedAlert"`

	// DegradedBehavior controls when the manager enters and exits degraded mode.
	DegradedBehavior DegradedBehaviorConfig `yaml:"degradedBehavior"`

	// EnableTwoPhaseHandoff gates the manager-side two-phase handoff coordinator.
	//
	// When false (default), assignment changes are applied directly via the
	// WorkerConsumerUpdater in a simple "remove/add" sequence managed by the
	// manager without KV claims. This keeps the control plane minimal but can
	// permit a brief duplicate-consumption window during reassignment.
	//
	// When true, the manager initializes a modular handoff coordinator which
	// can implement a prepare/commit protocol to make ownership transitions
	// atomic, single-owner, auditable, and crash-resumable. This feature is
	// wired behind a clean interface and can be enabled/disabled without
	// scattering conditional logic throughout the manager code path.
	EnableTwoPhaseHandoff bool `yaml:"enableTwoPhaseHandoff" default:"false"`

	// Handoff controls two-phase handoff tuning knobs.
	// Only applied when EnableTwoPhaseHandoff is true.
	Handoff HandoffConfig `yaml:"handoff"`

	// ApplyStartJitter, when > 0, randomly delays fresh-version applies
	// (watcher / commit / alias / initial-bootstrap, all funneled through
	// applyAssignmentWithPrev) by a uniformly distributed duration in
	// [0, ApplyStartJitter) before taking applyStoreMu. This spreads
	// JetStream consumer create/destroy load across a worker fleet that
	// observed the same new assignment version simultaneously (e.g. after
	// a leader re-election).
	//
	// Retries (scheduleApplyRetry) do NOT pay this jitter. The retry path
	// has its own exponential-backoff envelope with decorrelated jitter;
	// compounding apply-start jitter on top would inflate recovery latency
	// without spreading any fleet because a retry is one worker, not a fleet.
	//
	// Default 0 disables jitter (backwards compatible). Recommended starting
	// point for a 20-worker fleet creating 100 consumers each: 500ms.
	//
	// Hard-capped at 10s by Validate(): a larger value would dwarf the
	// LSR-advancement bookkeeping and risk masking apply failures behind
	// what would look like apply latency.
	//
	// Startup-runner consequence: the startup background runner's first
	// apply (applyInitialAssignment, manager_startup_async.go) also funnels
	// through applyAssignmentWithPrev for non-empty commits/aliases. With
	// jitter enabled, the runner sleeps up to ApplyStartJitter before its
	// first apply attempt. The soft watchdog measures StartupTimeout from
	// Start invocation (AGENTS.md "Apply boundedness" section), so operators
	// MUST configure ApplyStartJitter << StartupTimeout. Recommended:
	// ApplyStartJitter <= StartupTimeout / 4. A focused test pins this
	// (TestApplyStartJitter_StartupBudget).
	ApplyStartJitter time.Duration `yaml:"applyStartJitter" default:"0" validate:"gte=0"`

	// AssignmentWatcherDebounce is the idle-window duration used to coalesce
	// rapid bursts of assignment delivery watcher events into a single apply.
	// It applies to both the legacy per-worker assignment alias watcher and
	// the assignment._commit watcher. When > 0, each watcher path keeps the
	// latest observed assignment target in a pending slot and processes it
	// after the stream has been idle for the full window.
	//
	// Early-flush conditions (commit watcher only): the pending commit is
	// flushed BEFORE the idle window elapses when (a) the watcher channel
	// closes mid-window, or (b) a same-or-higher commit arrives that
	// changes this worker's effective partition set — either a Workers
	// membership flip (this worker added or removed) or a
	// Payloads[workerID].PayloadHash difference. Both shapes are treated
	// as ownership transitions; debounce collapses only commits whose
	// per-worker partition set is unchanged. This preserves the two-phase
	// handoff invariant that every ownership transition for this worker is
	// observed as a discrete apply. Stale lower-version commits arriving
	// after a higher pending version are dropped without flushing pending.
	// On context cancellation (Stop), the pending commit is dropped
	// without flushing — see the alias watcher's matching shutdown
	// semantics. The legacy alias watcher does NOT yet have the "flush on
	// assignment change" rule; harmonization is a follow-up.
	//
	// Default 0 disables debouncing (preserves pre-PR-3 behavior). Recommended
	// value derived from the apply-coalescing diagnostic
	// (PARTI_RUN_HERD_DIAGNOSTIC=1) plus a 50 ms safety margin — typically
	// in the 100–300 ms range.
	//
	// Hard-capped at 1 second by Validate(): a larger window would dwarf
	// reasonable reassignment-latency budgets and risk masking real apply
	// failures behind what looks like apply slowness.
	AssignmentWatcherDebounce time.Duration `yaml:"assignmentWatcherDebounce" default:"0" validate:"gte=0"`
}

type DegradedAlertConfig struct {
	// InfoThreshold is the duration in degraded mode before emitting Info-level alerts.
	// Default: 30 seconds.
	InfoThreshold time.Duration `yaml:"infoThreshold" default:"30s" validate:"gt=0"`

	// WarnThreshold is the duration in degraded mode before emitting Warn-level alerts.
	// Default: 2 minutes.
	WarnThreshold time.Duration `yaml:"warnThreshold" default:"2m" validate:"gt=0,gtefield=InfoThreshold"`

	// ErrorThreshold is the duration in degraded mode before emitting Error-level alerts.
	// Default: 5 minutes.
	ErrorThreshold time.Duration `yaml:"errorThreshold" default:"5m" validate:"gt=0,gtefield=WarnThreshold"`

	// CriticalThreshold is the duration in degraded mode before emitting Critical-level alerts.
	// Default: 10 minutes.
	CriticalThreshold time.Duration `yaml:"criticalThreshold" default:"10m" validate:"gt=0,gtefield=ErrorThreshold"`

	// AlertInterval is the time between repeated alerts at the same severity level.
	// Default: 1 minute.
	AlertInterval time.Duration `yaml:"alertInterval" default:"1m" validate:"gt=0"`
}

type DegradedBehaviorConfig struct {
	// EnterThreshold is how long NATS connectivity errors must persist before entering degraded mode.
	// Provides hysteresis to prevent flapping during transient issues.
	// Default: 10 seconds.
	EnterThreshold time.Duration `yaml:"enterThreshold" default:"10s" validate:"gte=0"`

	// ExitThreshold is how long NATS connectivity must be stable before exiting degraded mode.
	// Should be shorter than EnterThreshold to recover quickly.
	// Default: 5 seconds.
	ExitThreshold time.Duration `yaml:"exitThreshold" default:"5s" validate:"gte=0"`

	// KVErrorThreshold is the number of KV operation errors within KVErrorWindow
	// that trigger degraded mode. Whole-bucket-loss errors accumulate across the
	// window; connected-but-KV-unavailable timeouts are reset by any successful
	// periodic KV op while not degraded, so for that class it is a consecutive
	// run with no intervening success rather than blips summed across the window.
	// Default: 5 errors.
	KVErrorThreshold int `yaml:"kvErrorThreshold" default:"5" validate:"gte=0"`

	// KVErrorWindow is the time window for counting KV errors toward
	// KVErrorThreshold. Errors outside this window are not counted.
	// Default: 30 seconds.
	KVErrorWindow time.Duration `yaml:"kvErrorWindow" default:"30s" validate:"gte=0"`

	// RecoveryGracePeriod is the minimum time the leader must wait after recovering from
	// degraded mode before declaring missing workers as failed (emergency rebalance).
	// Prevents false emergencies when workers recover slightly slower than the leader.
	// Default: 15 seconds.
	RecoveryGracePeriod time.Duration `yaml:"recoveryGracePeriod" default:"15s" validate:"gte=0"`
}

type ElectionAgent = types.ElectionAgent

type FleetSizeObserver interface {
	// ObserveWorkerCount reports the current committed cluster worker-count.
	ObserveWorkerCount(n int)
}

type HandoffClaim struct {
	PartitionID   string            `json:"partition_id"`
	Owner         string            `json:"owner"`
	PendingOwner  string            `json:"pending_owner,omitempty"`
	State         HandoffClaimState `json:"state"`
	Epoch         int64             `json:"epoch"`
	LastUpdated   time.Time         `json:"last_updated"`
	TTLSeconds    int64             `json:"ttl_seconds"`
	ConflictCount int64             `json:"conflict_count,omitempty"`
}

type HandoffClaimState string

type HandoffConfig struct {
	// SweepInterval controls how often stale/expired claims are opportunistically
	// swept during Apply calls. If zero or negative, a sweep is attempted on every Apply.
	SweepInterval time.Duration `yaml:"sweepInterval" default:"30s" validate:"gte=0"`

	// MaxRetries controls bounded CAS retries for claim updates. Zero uses default (3).
	MaxRetries int `yaml:"maxRetries" default:"3" validate:"gte=0"`

	// BaseBackoff is the initial backoff for CAS retry with exponential backoff.
	BaseBackoff time.Duration `yaml:"baseBackoff" default:"50ms" validate:"gte=0"`

	// MaxBackoff caps the exponential backoff duration.
	MaxBackoff time.Duration `yaml:"maxBackoff" default:"500ms" validate:"gte=0,gtefield=BaseBackoff"`

	// Jitter is a fractional value [0.0, 1.0] to randomize backoff durations.
	Jitter float64 `yaml:"jitter" default:"0.2" validate:"gte=0,lte=1"`

	// DelayAfterPrepare introduces an artificial delay after the prepare phase completes
	// and before the consumer updater is invoked. Useful for making intermediate states
	// observable in tests and demonstrations. Ignored if <= 0.
	DelayAfterPrepare time.Duration `yaml:"delayAfterPrepare" default:"0" validate:"gte=0"`

	// DelayBeforeStable introduces an artificial delay after entering the commit state
	// and before finalizing to stable. Useful for external observation of the commit state.
	// Ignored if <= 0.
	DelayBeforeStable time.Duration `yaml:"delayBeforeStable" default:"0" validate:"gte=0"`

	// PhaseConcurrency caps the number of in-flight per-partition KV operations
	// during each of the prepare, commit, and stabilize phases. Zero uses the
	// default of 20. Note: 0 means "use default", not "no parallelism"; set 1
	// for strictly serial execution.
	PhaseConcurrency int `yaml:"phaseConcurrency" default:"0" validate:"gte=0,lte=256"`

	// ClaimWritePerSec optionally enables a per-worker token-bucket rate limit
	// on every physical handoff claim-write (the KV PutIfEpoch the coordinator
	// and startup loops issue), measured in writes/second. It paces the
	// otherwise-unbounded startup hygiene/resume loops (which walk every claim
	// key sequentially) and the two-phase coordinator's per-partition CAS
	// writes — including CAS retries — so a large-fleet restart or rapid
	// rebalance cannot drive a back-to-back KV write burst that stresses the
	// NATS cluster. PhaseConcurrency bounds simultaneity; this bounds rate.
	//
	// Opt-in: 0 (the default) disables rate limiting and leaves behaviour
	// unchanged. A single budget is shared across all claim-write sites for
	// this worker. Must be >= 0.
	//
	// Note: the startup hygiene pass runs under OperationTimeout on the
	// synchronous Manager.Start path, so a low rate combined with many
	// pre-existing stale claims can extend Start's blocking return latency up
	// to OperationTimeout before the best-effort pass stops early; the
	// background resume pass and the coordinator are not OperationTimeout-bounded
	// and run off the Start path. Sizing guidance lives in docs/OPERATIONS.md.
	ClaimWritePerSec float64 `yaml:"claimWritePerSec" default:"0" validate:"gte=0"`

	// ClaimWriteBurst is the token-bucket burst size for ClaimWritePerSec. It
	// must be >= 1 when ClaimWritePerSec > 0 (rejected at Validate otherwise);
	// it is ignored when ClaimWritePerSec == 0. Recommended starting point:
	// burst ≈ PhaseConcurrency so a single rebalance wave is absorbed without
	// throttling and only sustained bursts are paced.
	ClaimWriteBurst int `yaml:"claimWriteBurst" default:"0" validate:"gte=0"`

	// ClaimWriteClusterRate, when > 0, makes claim-write rate limiting
	// fleet-size-aware: each worker enforces
	// min(ClaimWritePerSec, ClaimWriteClusterRate/N), where N is the observed
	// committed worker count. It bounds the STEADY-STATE cluster-wide
	// claim-write rate to ClaimWriteClusterRate instead of N*ClaimWritePerSec.
	// Requires ClaimWritePerSec > 0 (the per-worker ceiling and burst source)
	// and EnableTwoPhaseHandoff. Default 0 = static per-worker rate only.
	ClaimWriteClusterRate float64 `yaml:"claimWriteClusterRate" default:"0" validate:"gte=0"`
}

type HandoffMetricsRecorder = types.HandoffMetricsRecorder

type HandoffSweepMetricsRecorder = types.HandoffSweepMetricsRecorder

type Hooks = types.Hooks

type KVBucketConfig struct {
	// StableIDBucket is the bucket name for stable worker ID claims.
	StableIDBucket string `yaml:"stableIdBucket" default:"parti-stableid" validate:"required"`

	// ElectionBucket is the bucket name for leader election.
	ElectionBucket string `yaml:"electionBucket" default:"parti-election" validate:"required"`

	// HeartbeatBucket is the bucket name for worker heartbeats.
	HeartbeatBucket string `yaml:"heartbeatBucket" default:"parti-heartbeat" validate:"required"`

	// AssignmentBucket is the bucket name for partition assignments.
	AssignmentBucket string `yaml:"assignmentBucket" default:"parti-assignment" validate:"required"`

	// AssignmentTTL is how long assignments remain in KV (0 = no expiration).
	// Assignments should persist across leader changes for version continuity.
	// Recommended: 0 (no TTL) or very long (e.g., 1 hour).
	AssignmentTTL time.Duration `yaml:"assignmentTtl" default:"0" validate:"gte=0"`

	// HandoffBucket is the bucket name for two-phase handoff ownership claims.
	// Used only when EnableTwoPhaseHandoff is true. Stores per-partition claim
	// records that track prepare/commit/stable transitions to ensure atomic
	// ownership changes and crash-resumable state. Kept separate from assignment
	// data to allow independent TTL and operational policies (sweeps, compaction).
	// Recommended: distinct bucket to isolate churn from stable assignment data.
	HandoffBucket string `yaml:"handoffBucket" default:"parti-handoff"`

	// HandoffTTL is the advisory staleness threshold the two-phase handoff
	// coordinator uses to recover a STUCK in-flight handoff: the periodic claim
	// sweep resets a prepare/commit claim back to stable once it has gone
	// untouched for longer than HandoffTTL.
	//
	// It is NOT a KV bucket TTL. The handoff bucket is created with no MaxAge —
	// a bucket-level TTL would also age out healthy stable ownership claims
	// (which are written once and never refreshed), permanently suppressing
	// pull-gated consumers. Stable claims therefore never expire.
	//
	// Must be longer than the expected multi-phase handoff duration (including
	// retries). Recommended: 2-5 minutes in production; fast tests may use
	// seconds.
	HandoffTTL time.Duration `yaml:"handoffTtl" default:"2m"`

	// Replicas is the JetStream stream-replication factor applied to
	// Parti-owned KV buckets when the library creates them fresh. Zero
	// (the default) leaves the field unset, which nats.go normalizes to 1
	// server-side — equivalent to no replication, the legacy behavior.
	//
	// Not to be confused with worker-pod replicas: Parti does not
	// configure pod counts (that is the orchestrator's concern). This
	// setting controls JetStream-level data replication only.
	//
	// Applies uniformly to every Parti-owned bucket the library creates
	// (stableID, election, heartbeat, assignment, handoff). Per-bucket
	// precision requires pre-creating buckets with explicit configs (the
	// provision package supports this) — pre-created buckets keep their
	// existing replica count regardless of this setting, because the
	// library's ensure path is get-first.
	//
	// Post-create modification: NATS JetStream DOES support changing the
	// replica count on an existing bucket via `UpdateStream`, but Parti
	// does NOT auto-reconcile Replicas. Unlike MaxAge (which is reconciled
	// because it carries a correctness invariant), Replicas is a
	// per-deployment HA-quality decision; silently rewriting an existing
	// bucket's Replicas could trigger expensive cross-node replication
	// the operator did not ask for, or mask a deliberate downsize. When
	// Manager.Start observes a pre-existing bucket whose Replicas differs
	// from this setting, it emits a WARN log line naming the divergence
	// and pointing at the `nats stream update KV_<bucket> --replicas=<N>`
	// command operators can run to apply the change themselves.
	//
	// Cluster topology must support the value at create time or bucket
	// creation fails loudly at Manager.Start (e.g. Replicas=3 against a
	// single-node NATS server returns a stream-creation error).
	//
	// Recommended values:
	//   - 0 / 1 — single-node NATS or test environments (default)
	//   - 3   — production multi-node cluster (minimum for quorum)
	//   - 5   — high-availability tier
	Replicas int `yaml:"replicas,omitempty" default:"0" validate:"gte=0"`
}

type LabelState struct {
	// PoolSizes maps each label present in the last published rebalance to
	// the number of live workers eligible for it.
	PoolSizes map[string]int

	// Parked maps each such label to the number of partitions currently
	// parked (intentionally left unassigned) for it.
	Parked map[string]int
}

type Logger = types.Logger

type Manager struct {
	// contains filtered or unexported fields
}

type ManagerMetrics = types.ManagerMetrics

type MetricsCollector = types.MetricsCollector

type Option func(*managerOptions)

type Partition = types.Partition

type PartitionSource = types.PartitionSource

type PartitionSourceUpdater = types.PartitionSourceUpdater

type PartitionUpdater = types.PartitionUpdater

type State = types.State

type StreamMissingHook = types.StreamMissingHook

type WatchablePartitionSource = types.WatchablePartitionSource

type WorkerConsumerMetrics = types.WorkerConsumerMetrics

type WorkerConsumerUpdater interface {
	// UpdateWorkerConsumer applies the given partition assignment to the worker's durable consumer.
	//
	// See interface documentation for semantics and concurrency guarantees.
	//
	// Parameters:
	//   - ctx: Context for cancellation and deadline
	//   - workerID: Stable worker ID claimed by Manager
	//   - partitions: Complete assignment slice (may be empty for zero subjects)
	//
	// Returns:
	//   - error: Non-nil only on unrecoverable configuration or API failure after retries
	UpdateWorkerConsumer(ctx context.Context, workerID string, partitions []Partition) error
}

type WorkerMetrics = types.WorkerMetrics