state

type Backend struct {
	// Provider is the name of a registered provider with CapabilityState (e.g., "file").
	Provider string `json:"provider" yaml:"provider" doc:"Provider name with CapabilityState" maxLength:"253" example:"file"`

	// Inputs are provider-specific inputs. Each value is a ValueRef for dynamic resolution.
	//
	// CEL expressions use __params for CLI parameters (e.g. __params.project) and _ for
	// resolver outputs (available at save time only, not load time).
	//
	// Go templates spread resolver data at top level (e.g. {{ .name }}) and expose CLI
	// parameters under __params (e.g. {{ .__params.project }}).
	Inputs map[string]*spec.ValueRef `json:"inputs" yaml:"inputs" doc:"Provider-specific inputs (ValueRef for dynamic resolution)"`

	// SaveOverrides are provider-specific inputs resolved only at save time when
	// resolver data (_) is available. Keys that overlap with Inputs override them
	// at save time. This enables patterns like loading state from a fixed branch
	// (via Inputs) and saving to a resolver-derived branch (via SaveOverrides).
	//
	// At load time, SaveOverrides are completely ignored -- no errors are raised
	// for resolver-dependent expressions.
	SaveOverrides map[string]*spec.ValueRef `json:"saveOverrides,omitempty" yaml:"saveOverrides,omitempty" doc:"Save-time-only inputs that override Inputs keys"`
}

type CommandInfo struct {
	// Subcommand is the CLI subcommand used (e.g., "run solution").
	Subcommand string `json:"subcommand" doc:"CLI subcommand used" maxLength:"100" example:"run solution"`

	// Parameters are the key-value pairs from --parameter flags for the most recent run.
	Parameters map[string]string `json:"parameters" doc:"Key-value pairs from --parameter flags"`
}

type Config struct {
	// Enabled controls whether state persistence is active. Supports literal bool, CEL expression, or template.
	// Resolver references (rslvr:) are not supported because state is loaded before resolver execution.
	// Use __params to reference CLI parameters (e.g. expr: "__params.enable_state == true").
	Enabled *spec.ValueRef `json:"enabled" yaml:"enabled" doc:"Dynamic activation of state persistence"`

	// Backend configures which provider handles state persistence.
	Backend Backend `json:"backend" yaml:"backend" doc:"Backend provider configuration"`
}

type Data struct {
	// SchemaVersion enables forward-compatible format migrations.
	SchemaVersion int `json:"schemaVersion" doc:"Format version for migrations"`

	// Metadata identifies the solution and tracks timestamps.
	Metadata Metadata `json:"metadata" doc:"Solution identity and timestamps"`

	// Command captures the most recent invocation for validation replay.
	Command CommandInfo `json:"command" doc:"Most recent invocation"`

	// Parameters stores the merged parameter set used for replay. On each run,
	// CLI parameters are merged into this map (CLI wins on conflict, new keys added).
	// When no CLI params are provided, these saved parameters drive replay.
	Parameters map[string]any `json:"parameters" doc:"Merged parameter set for replay"`

	// Resolvers maps resolver names to their persisted outputs. Resolvers marked
	// persist: true have their value recorded here after each successful run for
	// later retrieval via the state provider. Resolvers marked immutable: true are
	// also stored here (with Immutable set) and verified on subsequent runs.
	Resolvers map[string]*PersistedEntry `json:"resolvers" doc:"Persisted resolver values"`

	// Fingerprints stores file and input hashes for action up-to-date checks.
	// Keys use the format "__fingerprint:<actionName>:<type>".
	Fingerprints map[string]*FingerprintEntry `json:"fingerprints" doc:"Action fingerprint hashes"`
}

type FingerprintEntry struct {
	// Value is the stored hash string.
	Value string `json:"value" doc:"Stored hash value"`

	// UpdatedAt is when this fingerprint was last written.
	UpdatedAt time.Time `json:"updatedAt" doc:"When this fingerprint was last written"`
}

type ListView struct {
	// Sections are the ordered display groups derived from Data.
	Sections []Section `json:"sections"`
}

type LoadResult struct {
	// Ctx is the context enriched with state.WithState.
	Ctx context.Context

	// Data is the loaded (or empty) state data.
	Data *Data

	// MergedParams is the effective parameter set (saved params merged with CLI params).
	// CLI params override saved params; new CLI keys are added.
	MergedParams map[string]any

	// Skipped is true when state is disabled or the enabled ValueRef is falsy.
	Skipped bool
}

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

type Metadata struct {
	// Solution is the solution name from metadata.name.
	Solution string `json:"solution" doc:"Solution name from metadata.name" maxLength:"253"`

	// Version is the solution semver string.
	Version string `json:"version" doc:"Solution semver" maxLength:"30"`

	// CreatedAt is when the state file was first created.
	CreatedAt time.Time `json:"createdAt" doc:"First state file creation"`

	// LastUpdatedAt is when the state file was most recently saved.
	LastUpdatedAt time.Time `json:"lastUpdatedAt" doc:"Most recent save"`

	// Runtime records the execution provenance that last wrote the state,
	// separating the engine (library) identity from the invoking CLI/frontend.
	Runtime Runtime `json:"runtime" doc:"Execution provenance that last wrote the state"`
}

type MissingParamsError struct {
	// Missing is the sorted list of __params keys not found in the supplied params.
	Missing []string `json:"missing" yaml:"missing" doc:"Parameter names required by state configuration"`

	// Original is the underlying evaluation error.
	Original error `json:"-" yaml:"-" doc:"Underlying evaluation error"`
}

type PersistedEntry struct {
	// Value is the persisted resolver value.
	Value any `json:"value" doc:"Persisted resolver value"`

	// Type is the resolver's declared type.
	Type string `json:"type" doc:"Resolver declared type" maxLength:"30" example:"string"`

	// Immutable discriminates immutable entries (locked and verified) from
	// persist-only entries (overwritten each run).
	Immutable bool `json:"immutable,omitempty" doc:"Whether the entry is locked and verified across runs"`

	// CreatedAt is when the entry was first stored and never changes thereafter.
	// For entries created immutable this is the lock time. For an entry promoted
	// from persist-only to immutable it is the original persist time, not the
	// lock time.
	CreatedAt time.Time `json:"createdAt" doc:"When the value was first stored"`

	// UpdatedAt is when the entry was last written. For persist-only entries it
	// advances each run. For entries created immutable it equals CreatedAt. For
	// an entry promoted from persist-only to immutable it is the promotion (lock)
	// time and is later than CreatedAt.
	UpdatedAt time.Time `json:"updatedAt" doc:"When the value was last written"`
}

type Runtime struct {
	// Engine identifies the execution engine (the scafctl library) that
	// performed the run.
	Engine RuntimeComponent `json:"engine" doc:"Execution engine (scafctl library) identity"`

	// CLI identifies the CLI/frontend that invoked execution. For embedded
	// runners this is the wrapper binary; for direct scafctl use it mirrors
	// Engine.
	CLI RuntimeComponent `json:"cli" doc:"Invoking CLI/frontend identity"`
}

type RuntimeComponent struct {
	// Name is the component's binary/identifier name.
	Name string `json:"name" doc:"Component name" maxLength:"64" example:"scafctl"`

	// Version is the component's version string. May be empty when unknown.
	Version string `json:"version" doc:"Component version" maxLength:"64" example:"0.5.0"`
}

type Section struct {
	// Name is the section identifier (json-tag name of the source field).
	Name string `json:"name"`

	// Kind is either SectionKindKeyValue or SectionKindRows.
	Kind string `json:"kind"`

	// Fields holds the key/value pairs for a SectionKindKeyValue section.
	Fields map[string]any `json:"fields,omitempty"`

	// Rows holds the ordered rows for a SectionKindRows section.
	Rows []map[string]any `json:"rows,omitempty"`
}

type SolutionMeta struct {
	Name    string
	Version string
}

type Summary struct {
	// Solution is the solution name the state belongs to (may be empty).
	Solution string `json:"solution"`

	// Version is the solution semver the state belongs to (may be empty).
	Version string `json:"version"`

	// SchemaVersion is the state file format version.
	SchemaVersion int `json:"schemaVersion"`

	// LastUpdated is when the state was most recently saved (zero if never).
	LastUpdated time.Time `json:"lastUpdated"`

	// ParameterCount is the number of stored replay parameters.
	ParameterCount int `json:"parameterCount"`

	// ResolverCount is the number of persisted resolver entries.
	ResolverCount int `json:"resolverCount"`

	// FingerprintCount is the number of stored action fingerprints.
	FingerprintCount int `json:"fingerprintCount"`
}