group_policy_update.go

/*
  Copyright 2026 The ARCORIS Authors

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
*/

package bufferpool

import "time"

// group_policy_update.go owns live PoolGroup policy publication. The flow is
// validate the candidate, admit the group runtime gate, plan group-to-partition
// budget publication, admit and lock children top-down, publish the group
// runtime snapshot, and then apply only prevalidated partition budget plans.

const (
	// groupPolicyPublicationNoBudgetTarget reports a group policy publication
	// that changed group policy state but carried no retained parent target to
	// publish into child partitions.
	groupPolicyPublicationNoBudgetTarget = "no_budget_target"
)

// PoolGroupPolicyPublicationResult reports one group-level live policy
// publication.
//
// PoolGroup policy publication is a foreground group control operation. It is
// serialized with hard Close by runtimeMu, preserves the current pressure
// signal, may publish a new immutable group runtime policy snapshot, and may
// publish retained-budget targets into owned PoolPartitions. It never scans Pool
// shards, never executes Pool trim, never calls Pool.Get or Pool.Put, and never
// computes class EWMA. Scheduler changes are owner-local and are applied after
// publication releases locks that scheduled TickInto may need.
type PoolGroupPolicyPublicationResult struct {
	// PreviousGeneration is the group runtime-policy generation observed before
	// the publication attempt.
	PreviousGeneration Generation

	// Generation is the group runtime-policy generation published by this
	// attempt. It remains NoGeneration when validation, feasibility, lifecycle,
	// or child precheck rejects the publication before the runtime snapshot
	// changes.
	Generation Generation

	// Published reports whether the group accepted the candidate policy and all
	// required child partition budget targets were accepted.
	Published bool

	// RuntimePublished reports whether a new immutable group runtime snapshot was
	// stored.
	RuntimePublished bool

	// Contracted reports whether group retained-budget limits became more
	// restrictive.
	//
	// Contraction lowers future partition targets only. It does not scan shards,
	// trim Pool storage, or force active leases.
	Contracted bool

	// FailureReason is empty on success and contains stable diagnostic text on
	// rejection or observable partial publication.
	FailureReason string

	// SchedulerChange reports the owner-local scheduler reconfiguration planned
	// by this publication attempt. Stable values are "none", "enable",
	// "disable", and "retime".
	SchedulerChange string

	// SchedulerPreviousEnabled reports whether the previous runtime policy had
	// the group-level coordinator scheduler enabled.
	SchedulerPreviousEnabled bool

	// SchedulerNextEnabled reports whether the candidate runtime policy enables
	// the group-level coordinator scheduler.
	SchedulerNextEnabled bool

	// SchedulerPreviousInterval is the previous scheduler cadence after policy
	// normalization.
	SchedulerPreviousInterval time.Duration

	// SchedulerNextInterval is the candidate scheduler cadence after policy
	// normalization.
	SchedulerNextInterval time.Duration

	// SchedulerApplied reports whether PublishPolicy mutated the scheduler
	// runtime. It is false for no-change attempts because no runtime scheduler
	// mutation was needed.
	SchedulerApplied bool

	// SchedulerFailureReason is empty unless owner-local scheduler
	// reconfiguration failed. It uses stable policy_update_* vocabulary and does
	// not expose raw error text.
	SchedulerFailureReason string

	// Diff describes which group policy sections changed.
	Diff PolicyUpdateDiffDiagnostics

	// PreviousPolicy is the normalized group policy observed before publication.
	PreviousPolicy PoolGroupPolicy

	// Policy is the normalized candidate group policy.
	Policy PoolGroupPolicy

	// BudgetPublication reports group-to-partition retained-budget feasibility
	// and publication status.
	BudgetPublication PoolGroupBudgetPublicationReport

	// SkippedPartitions records child partitions that could not accept target
	// publication.
	SkippedPartitions []PoolGroupSkippedPartition

	// PressurePreserved reports whether the pressure signal observed before
	// publication was preserved in the new group runtime snapshot.
	PressurePreserved bool
}

// PublishPolicy publishes a live PoolGroup runtime policy update.
//
// The operation validates the candidate policy, computes group-to-partition
// retained targets when a retained parent target exists, admits every target
// partition, and asks each partition to build a complete no-mutation
// application plan before the group runtime snapshot is stored. Only after those
// child plans and their Pool control gates are admitted does the group publish
// its own immutable runtime snapshot. Applying the prevalidated partition plans
// is expected to be no-fail for normal policy, feasibility, and lifecycle
// reasons.
//
// This ordering is owner-level and report-driven, not a distributed
// transaction: no rollback is attempted, and internal corruption still remains
// an internal invariant failure. The guarantee is narrower and intentional:
// ordinary validation, infeasible budget, closed-child, and Pool-control
// admission failures are detected before group runtime publication. Live
// scheduler enable, disable, and retime changes are planned with the policy
// update and applied after runtimeMu is released. Scheduler start and retime
// prepare their ticker before runtime publication; the prepared ticker is either
// transferred to the scheduler runtime on success or stopped on every later
// error path. If a scheduler apply failure appears after runtime publication,
// the report keeps RuntimePublished accurate and records stable scheduler
// diagnostics instead of attempting rollback.
func (g *PoolGroup) PublishPolicy(policy PoolGroupPolicy) (PoolGroupPolicyPublicationResult, error) {
	g.mustBeInitialized()

	// Validate the candidate before taking the group write gate so malformed
	// policy values do not block unrelated foreground group work.
	normalized := policy.Normalize()
	initial := g.currentRuntimeSnapshot()
	result := newPoolGroupPolicyPublicationResult(initial, normalized)
	if err := validateGroupPolicyPublicationCandidate(normalized, &result); err != nil {
		return result, err
	}

	g.schedulerReconfigMu.Lock()
	defer g.schedulerReconfigMu.Unlock()

	result, schedulerChange, preparedScheduler, err := g.publishPolicyAndPlanSchedulerReconfiguration(normalized)
	if err != nil {
		return result, err
	}

	if err := g.applyPublishedCoordinatorSchedulerPolicyChange(&result, schedulerChange, preparedScheduler); err != nil {
		return result, err
	}

	return result, nil
}

func (g *PoolGroup) publishPolicyAndPlanSchedulerReconfiguration(
	normalized PoolGroupPolicy,
) (
	PoolGroupPolicyPublicationResult,
	schedulerPolicyChange,
	controllerSchedulerPreparedStart,
	error,
) {
	result := newPoolGroupPolicyPublicationResult(g.currentRuntimeSnapshot(), normalized)

	// Serialize live publication with group Close, group TickInto, and other
	// group-level runtime snapshot mutations. Scheduler Stop is intentionally
	// applied later, after runtimeMu is released.
	g.runtimeMu.Lock()
	defer g.runtimeMu.Unlock()

	if !g.lifecycle.AllowsWork() {
		result.FailureReason = policyUpdateFailureClosed
		return result, schedulerPolicyChange{}, controllerSchedulerPreparedStart{}, newError(ErrClosed, errGroupClosed)
	}

	plan, err := g.planGroupPolicyPublicationLocked(normalized, &result)
	if err != nil {
		g.releaseGroupPolicyPublicationPlan(&plan)
		return result, schedulerPolicyChange{}, controllerSchedulerPreparedStart{}, err
	}
	defer g.releaseGroupPolicyPublicationPlan(&plan)

	var preparedScheduler controllerSchedulerPreparedStart
	preparedSchedulerOwned := false
	if plan.schedulerChange.needsPreparedStart() {
		var err error
		preparedScheduler, err = g.prepareCoordinatorSchedulerStart(normalized.Coordinator)
		if err != nil {
			result.markSchedulerPolicyChangeFailed(plan.schedulerChange, policyUpdateFailureReasonForSchedulerChange(plan.schedulerChange))
			return result, schedulerPolicyChange{}, controllerSchedulerPreparedStart{}, err
		}
		preparedSchedulerOwned = true
		defer func() {
			if preparedSchedulerOwned {
				preparedScheduler.stop()
			}
		}()
	}

	if err := g.commitGroupPolicyPublicationLocked(normalized, &result, &plan); err != nil {
		return result, schedulerPolicyChange{}, controllerSchedulerPreparedStart{}, err
	}

	preparedSchedulerOwned = false
	return result, plan.schedulerChange, preparedScheduler, nil
}

// UpdatePolicy publishes policy and returns only the operation error.
func (g *PoolGroup) UpdatePolicy(policy PoolGroupPolicy) error {
	_, err := g.PublishPolicy(policy)
	return err
}

// newPoolGroupPolicyPublicationResult builds a stable report skeleton shared by
// successful and rejected publication paths.
func newPoolGroupPolicyPublicationResult(
	runtime *groupRuntimeSnapshot,
	candidate PoolGroupPolicy,
) PoolGroupPolicyPublicationResult {
	var previousPolicy PoolGroupPolicy
	var previousGeneration Generation
	if runtime != nil {
		previousPolicy = runtime.Policy.Normalize()
		previousGeneration = runtime.Generation
	}

	diff := classifyGroupPolicyUpdate(previousPolicy, candidate)

	result := PoolGroupPolicyPublicationResult{
		PreviousGeneration: previousGeneration,
		Contracted:         diff.RetentionContracted,

		Diff:           diff,
		PreviousPolicy: previousPolicy,
		Policy:         candidate.Normalize(),
	}
	result.setSchedulerPolicyChangeDiagnostics(
		classifyGroupSchedulerPolicyChange(previousPolicy.Coordinator, result.Policy.Coordinator),
	)
	return result
}

// validateGroupPolicyPublicationCandidate validates the candidate before any
// group runtime mutation is allowed.
func validateGroupPolicyPublicationCandidate(
	policy PoolGroupPolicy,
	result *PoolGroupPolicyPublicationResult,
) error {
	if err := policy.Validate(); err != nil {
		result.FailureReason = policyUpdateFailureInvalid
		return err
	}

	return nil
}

// classifyGroupPolicyUpdate maps group policy differences into shared
// publication diagnostics.
func classifyGroupPolicyUpdate(previous PoolGroupPolicy, next PoolGroupPolicy) PolicyUpdateDiffDiagnostics {
	previous = previous.Normalize()
	next = next.Normalize()
	return PolicyUpdateDiffDiagnostics{
		RetentionChanged:    previous.Budget != next.Budget,
		RetentionContracted: partitionBudgetContracts(previous.Budget, next.Budget),
		RetentionExpanded:   partitionBudgetExpands(previous.Budget, next.Budget),
		PressureChanged:     previous.Pressure != next.Pressure,
	}
}

func groupPolicyHasRetainedTarget(policy PoolGroupPolicy) bool {
	return !policy.Budget.MaxRetainedBytes.IsZero()
}