planning

type PlanOpts struct {
	// Mode is the planning mode to use.
	//
	// Planning modes are mutually-exclusive and each represent significantly
	// different goals for the planning process. Whereas most other options
	// just change specific details of how we plan, a different planning mode
	// has a far more drastic, cross-cutting effect.
	Mode plans.Mode

	ForceReplace []addrs.AbsResourceInstance
}

type Tracer struct {

	// StartManagedResourceInstanceObjectPlanning and
	// EndManagedResourceInstanceObjectPlanning mark the beginning and end of
	// the overall planning work for the identified managed resource instance
	// object.
	//
	// These events cover the whole planning process for the given resource
	// instance object, including the state upgrade and refresh steps alongside
	// the actual call to ask the provider to determine if any changes are
	// needed. There are other more specific events below, which nest inside
	// this pair of events.
	StartManagedResourceInstanceObjectPlanning func(ctx context.Context, addr addrs.AbsResourceInstanceObject) context.Context
	EndManagedResourceInstanceObjectPlanning   func(ctx context.Context, addr addrs.AbsResourceInstanceObject, diags tfdiags.Diagnostics)

	// StartManagedResourceInstanceObjectUpgrade and
	// EndManagedResourceInstanceObjectUpgrade mark the beginning and end
	// of the "state upgrade" step for the identified managed resource instance
	// object.
	//
	// These events always occur between calls to
	// StartManagedResourceInstanceObjectPlanning and
	// EndManagedResourceInstanceObjectPlanning for the same object address.
	StartManagedResourceInstanceObjectUpgrade func(ctx context.Context, addr addrs.AbsResourceInstanceObject) context.Context
	EndManagedResourceInstanceObjectUpgrade   func(ctx context.Context, addr addrs.AbsResourceInstanceObject, upgradedVal cty.Value, diags tfdiags.Diagnostics)

	// StartManagedResourceInstanceObjectRefresh and
	// EndManagedResourceInstanceObjectRefresh mark the beginning and end
	// of the "refresh" step for the identified managed resource instance
	// object.
	//
	// These events always occur between calls to
	// StartManagedResourceInstanceObjectPlanning and
	// EndManagedResourceInstanceObjectPlanning for the same object address.
	StartManagedResourceInstanceObjectRefresh func(ctx context.Context, addr addrs.AbsResourceInstanceObject, prevRoundVal cty.Value) context.Context
	EndManagedResourceInstanceObjectRefresh   func(ctx context.Context, addr addrs.AbsResourceInstanceObject, prevRoundVal, refreshedVal cty.Value, diags tfdiags.Diagnostics)

	// StartManagedResourceInstanceObjectPlanChanges and
	// EndManagedResourceInstanceObjectPlanChanges mark the beginning and end
	// of the step where we actually ask the provider to plan changes for
	// the identified resource instance object.
	//
	// These events always occur between calls to
	// StartManagedResourceInstanceObjectPlanning and
	// EndManagedResourceInstanceObjectPlanning for the same object address,
	// which act as a container for the upgrade, refresh, and change-planning
	// sequence.
	StartManagedResourceInstanceObjectPlanChanges func(ctx context.Context, addr addrs.AbsResourceInstanceObject, priorVal, configVal cty.Value) context.Context
	EndManagedResourceInstanceObjectPlanChanges   func(ctx context.Context, addr addrs.AbsResourceInstanceObject, action plans.Action, priorVal, plannedVal cty.Value, diags tfdiags.Diagnostics)

	// StartDataResourceInstancePlanning and EndDataResourceInstancePlanning
	// mark the beginning and end of the overall planning work for the
	// identified data resource instance.
	//
	// These events cover the whole planning process for the given resource
	// instance. There are other more specific events below, which nest inside
	// this pair of events.
	StartDataResourceInstancePlanning func(ctx context.Context, addr addrs.AbsResourceInstance) context.Context
	EndDataResourceInstancePlanning   func(ctx context.Context, addr addrs.AbsResourceInstance, diags tfdiags.Diagnostics)

	// StartDataResourceInstanceRead and EndDataResourceInstanceRead mark the
	// beginning and end of the work to read data for the identified data
	// resource instance.
	//
	// These events occur only when the data resource instance is readable
	// during the planning phase. Some data resource instances get delayed until
	// the apply phase because there isn't enough information to read them
	// during the planning phase.
	//
	// These events always occur between calls to
	// StartDataResourceInstancePlanning and EndDataResourceInstancePlanning for
	// the same instance address.
	StartDataResourceInstanceRead func(ctx context.Context, addr addrs.AbsResourceInstance) context.Context
	EndDataResourceInstanceRead   func(ctx context.Context, addr addrs.AbsResourceInstance, resultVal cty.Value, diags tfdiags.Diagnostics)

	// We also embed [shared.Tracer] for some events that are common across
	// plan and apply. [PlanChanges] automatically ensures that this nested
	// tracer reaches the shared codepaths that rely on it.
	shared.Tracer
}