simulate

type Action ¶

type Action interface {
	// Name is a short identifier for the action (for example "promote").
	Name() string

	// Describe returns a one-line human-readable summary of the action.
	Describe() string

	// Apply replays the action against the clone manifest and returns the
	// effects plus the after-state path.
	Apply(ctx ActionContext) (*ActionOutcome, error)
}

Action is a hypothetical operation the what-if engine can replay against a cloned manifest. Implementations drive the real orchestration logic in record-only mode and report the effects it would produce.

type ActionContext ¶

type ActionContext struct {
	// ClonePath is the path to the temp clone of the manifest the action may
	// mutate. The real promoter writes its transitions here.
	ClonePath string

	// Actor is the identity that performs the hypothetical action.
	Actor string

	// Deploys is the deploy-stub model for the manifest's build and deploy
	// callbacks. The simulator validates orchestration, not the user's real
	// build and deploy scripts, so an action records each callback as a stubbed
	// effect with a simulated outcome and gates finalize on the result rather
	// than executing anything. It is never nil when supplied by the engine.
	Deploys *DeployStub
}

ActionContext carries the inputs an Action needs to replay orchestration against the cloned manifest. ClonePath points at the temp copy of the user's manifest; the real file is never handed to an action.

type ActionOutcome ¶

type ActionOutcome struct {
	// Effects is the ordered list of steps the orchestration would take.
	Effects []Effect

	// AfterStatePath is the manifest path holding the after-state.
	AfterStatePath string
}

ActionOutcome is what an Action returns after replaying orchestration. It carries the ordered effects plus the path holding the resolved after-state (the clone path, since the real promoter writes there).

type DeployDiff ¶

type DeployDiff struct {
	Name    string      `json:"name"`
	SHA     FieldChange `json:"sha"`
	Version FieldChange `json:"version"`
}

DeployDiff captures the field changes for a single named deploy within an environment.

type DeployOutcome ¶

type DeployOutcome string

DeployOutcome is the simulated result of a single build or deploy callback. The simulator never runs the user's real build and deploy scripts, so each callback resolves to one of these recorded outcomes instead of an execution.

const (
	// OutcomeSuccess marks a callback the simulation treats as having succeeded.
	// It is the default when no outcome is injected for a callback.
	OutcomeSuccess DeployOutcome = "success"

	// OutcomeFailure marks a callback the simulation treats as having failed.
	// A failed deploy gates the downstream finalize, matching how the real
	// finalizers refuse to record state when a deploy did not succeed.
	OutcomeFailure DeployOutcome = "failure"

	// OutcomeSkipped marks a callback the simulation treats as not run. A
	// skipped deploy is never a failure, but it does not count as a success
	// either, so a step whose only deploys were skipped still gates.
	OutcomeSkipped DeployOutcome = "skipped"
)

type DeployStub ¶

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

DeployStub is the simulate-side model of the build and deploy callbacks a manifest declares. It exists to make one boundary explicit: the simulator validates cascade's ORCHESTRATION, meaning the run, skip, and gate decisions and the state transitions, not the user's real build and deploy scripts. Those scripts never execute in a what-if. Each callback is therefore recorded as a stubbed effect carrying a simulated outcome rather than run.

Outcomes default to success, so the orchestration sequences exactly as it would with real callbacks that all passed. A caller can inject a failure or skipped outcome per callback to preview the orchestration's gating behavior. The gate mirrors the DEPLOY_RESULT_<name> inputs the real finalizers read from the environment (see internal/promote/finalize.go and internal/rollback/command_subcommands.go): a deploy that did not succeed refuses to advance trunk state, so the simulated finalize is held back.

type Disposition ¶

type Disposition string

Disposition classifies how the orchestration treats a single effect when the hypothetical action is replayed in record-only mode.

const (
	// DispositionRun marks an effect the orchestration would carry out.
	DispositionRun Disposition = "run"

	// DispositionSkip marks an effect the orchestration would skip as a no-op.
	DispositionSkip Disposition = "skip"

	// DispositionGate marks an effect held back behind a gate or guard.
	DispositionGate Disposition = "gate"
)

type Effect ¶

type Effect struct {
	Disposition Disposition `json:"disposition"`
	Action      string      `json:"action"`
	Target      string      `json:"target"`
	Detail      string      `json:"detail"`
}

Effect is one ordered step the orchestration would take for the simulated action. It carries the disposition (run, skip, or gate), the kind of action, the target it acts on, and a human-readable detail string.

type Engine ¶

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

Engine runs hypothetical actions against a clone of the user's manifest and reports the resulting state diff and effect sequence. It never mutates the user's real manifest and never touches git or the network.

func NewEngine(manifestPath string, opts ...Option) (*Engine, error)

func (e *Engine) Simulate(a Action) (*Result, error)

type EnvDiff ¶

type EnvDiff struct {
	Environment  string       `json:"environment"`
	Version      FieldChange  `json:"version"`
	SHA          FieldChange  `json:"sha"`
	Divergence   FieldChange  `json:"divergence"`
	PreviousRing FieldChange  `json:"previous_ring"`
	Deploys      []DeployDiff `json:"deploys,omitempty"`
}

EnvDiff captures the field-by-field changes for a single environment. The run-stamped CommittedAt and CommittedBy fields are deliberately excluded: timestamps are run-stamped and not part of the what-if outcome.

type FieldChange ¶

type FieldChange struct {
	Field   string `json:"field"`
	From    string `json:"from"`
	To      string `json:"to"`
	Changed bool   `json:"changed"`
}

FieldChange records a single field transitioning from one value to another. Changed is true only when From and To differ.

type HotfixAction ¶

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

HotfixAction replays the real hotfix finalize orchestration against a cloned manifest. It drives hotfix.Finalizer in record-only mode so the genuine divergence state machine runs: it allocates the next hotfix version, snapshots the prior state into the deploy-history ring, and writes the divergence fields (Ref, BaseSHA, Patches) to the clone only. Git, the trunk read, the manifest push, and the release API are all replaced with record-only seams, so the simulation touches no git and no network.

func NewHotfixAction(targetEnv string, fixSHAs []string, mergeSHA string) *HotfixAction

func (a *HotfixAction) Apply(ctx ActionContext) (*ActionOutcome, error)

func (a *HotfixAction) Describe() string

func (a *HotfixAction) Name() string

type Option ¶

type Option func(*Engine)

Option configures an Engine.

func WithActor(actor string) Option

func WithDeployResults(outcomes map[string]DeployOutcome) Option

type PromoteAction ¶

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

PromoteAction replays the real promotion orchestration against a cloned manifest. It drives promote.NewPromoter in non-dry-run mode so the genuine state-machine computes transitions and writes them to the clone only.

func NewPromoteAction(mode promote.PromotionMode, target string) *PromoteAction

func (a *PromoteAction) Apply(ctx ActionContext) (*ActionOutcome, error)

func (a *PromoteAction) Describe() string

func (a *PromoteAction) Name() string

type ReleaseAction ¶

type ReleaseAction struct{}

ReleaseAction replays the real promotion state-machine across the release boundary against a cloned manifest. The promoter is the orchestration brain that decides whether a crossing is a prerelease promotion or a publish, and it computes the rc-to-publish version carry; this action drives it and surfaces that decision as the release-marker effect.

The network-bound release executor (internal/release Manager) is not invoked: the simulator validates orchestration, meaning the state transitions and the release decision, not the GitHub release API calls. The marker effect labels the step with the internal/release action vocabulary so the simulator and the executor name the step identically.

func NewReleaseAction() *ReleaseAction

func (a *ReleaseAction) Apply(ctx ActionContext) (*ActionOutcome, error)

func (a *ReleaseAction) Describe() string

func (a *ReleaseAction) Name() string

type Result ¶

type Result struct {
	// ActionName is the short identifier of the simulated action.
	ActionName string `json:"action"`

	// ActionDescribe is the one-line human-readable summary of the action.
	ActionDescribe string `json:"describe"`

	// Diff is the before and after state difference.
	Diff StateDiff `json:"diff"`

	// Effects is the ordered list of orchestration steps.
	Effects []Effect `json:"effects"`

	// Note states the orchestration-not-deploys boundary so a green simulation
	// is never read as a passing deploy.
	Note string `json:"note,omitempty"`
}

Result is the outcome of one simulation: the action identity, the before and after state diff, and the ordered effect sequence.

func (r *Result) RenderHuman(w io.Writer) error

func (r *Result) RenderJSON(w io.Writer) error

type RollbackAction ¶

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

RollbackAction replays the real rollback orchestration against a cloned manifest. It drives rollback.New, Plan, and Apply so the genuine target resolution and state revert run, writing the reverted state to the clone only.

func NewRollbackAction(env, to, deployable string) *RollbackAction

func (a *RollbackAction) Apply(ctx ActionContext) (*ActionOutcome, error)

func (a *RollbackAction) Describe() string

func (a *RollbackAction) Name() string

type StateDiff ¶

type StateDiff struct {
	// Envs holds the per-environment diffs in sorted-key order.
	Envs []EnvDiff `json:"envs"`
}

StateDiff is the difference between a before and after manifest state, keyed by environment name in deterministic (sorted) order.

func DiffState(before, after map[string]*config.EnvState) StateDiff

func (s StateDiff) Changed() bool

func (s StateDiff) Env(name string) (EnvDiff, bool)