reconcile

type ApplyOptions struct {
	// Yes permits emptying Units that dropped out of the desired set.
	// Required when the plan contains deletes.
	Yes bool
	// ChangeSetSlug is the slug used when opening a per-Space ChangeSet for
	// updates. Defaults to DefaultChangeSetSlug(time.Now()) chosen by the
	// caller — pass a non-empty, retry-stable slug for reproducibility.
	ChangeSetSlug string
	// ChangeSetDescription is the description on the opened ChangeSet.
	// Defaults to a generic line derived from the Space's DisplayName.
	ChangeSetDescription string
	// Stdout/Stderr override the I/O streams; nil uses os.Stdout/os.Stderr.
	Stdout io.Writer
	Stderr io.Writer
	// PostSpaceHook runs after each Space's changes. Nil = no-op.
	PostSpaceHook PostSpaceHook
}

type ApplyResult struct {
	Created          int
	Updated          int
	Deleted          int
	ChangeSetsOpened []ChangeSetRef
}

type BinaryRunner struct {
	Bin string
}

type ChangeSetRef struct {
	Space        string
	Slug         string
	Component    string
	UpdatedSlugs []string
}

type CubRunner interface {
	Run(ctx context.Context, args []string, stdout, stderr io.Writer) error
}

type DesiredUnit struct {
	// Slug is the Unit slug — its stable identity in the Space.
	Slug string
	// SourceName is the merge-external-source identity passed to cub on
	// create/update. The server picks the 3-way-merge base by source type
	// per Unit, so this value only labels the change, but keeping it stable
	// across runs (typically the source file's basename) keeps the audit
	// trail coherent. Defaults to baseName(Path), or Slug when Path is empty.
	SourceName string
	// Path is a file on disk holding the Unit body. Used when Content is nil.
	Path string
	// Content, when non-nil, is the Unit body; the engine stages it to a
	// temp file for cub. Takes precedence over Path — set it for bodies that
	// don't already exist as files (e.g. AppConfig raw env content).
	Content []byte
	// Toolchain, when set, is forwarded to `cub unit create --toolchain`.
	// Empty lets cub infer it. Ignored on update (cub uses the existing Unit).
	Toolchain string
	// Bodyless marks a Unit that should be recognized as present — kept out
	// of delete candidates — but never added or updated by this engine. Used
	// for Units whose body is maintained elsewhere, e.g. an AppConfig
	// placeholder populated by an Upsert link.
	Bodyless bool
}

type Engine struct {
	Cub CubRunner
}

type Plan struct {
	Spaces []SpacePlan
}

type PostSpaceHook func(ctx context.Context, sp SpacePlan) error

type SlugDiff struct {
	Slug       string
	SourceName string
	Path       string
	Content    []byte
	Toolchain  string
	// DiffText is the cub -o mutations diff (ANSI-stripped, bookkeeping
	// filtered). Set only for Updates.
	DiffText string
}

type SpacePlan struct {
	Space          string
	DisplayName    string
	DisplayVersion string
	// Adds exist in Desired but not in the live Space.
	Adds []SlugDiff
	// Updates exist in both and cub's dry-run reports non-bookkeeping changes.
	Updates []SlugDiff
	// Deletes are owned Units absent from Desired (Ignore/Bodyless excluded).
	Deletes []SlugDiff

	Target            string
	CreateLabels      []string
	CreateAnnotations []string
	UpdateAnnotations []string
}

type SpaceSource struct {
	// Space is the target Space slug.
	Space string
	// ListWhere scopes which existing Units this reconcile owns and may
	// therefore delete: the engine lists current Units matching this cub
	// where-clause (e.g. "Labels.Package='web'"). Empty means every Unit in
	// the Space is owned.
	ListWhere string
	// Ignore lists owned Unit slugs to never treat as delete candidates even
	// when absent from Desired (e.g. a bookkeeping record Unit).
	Ignore []string
	// Desired is the target Unit set.
	Desired []DesiredUnit
	// Target is the target ref forwarded to `cub unit create --target` for
	// adds. Empty means no target binding. Existing Units keep their binding.
	Target string
	// CreateLabels / CreateAnnotations are key=value pairs stamped on adds
	// only — never re-applied on update, which would clobber operator edits.
	CreateLabels      []string
	CreateAnnotations []string
	// UpdateAnnotations are key=value pairs re-stamped on every update via a
	// separate --patch (engine-owned bookkeeping the caller wants kept in
	// sync, e.g. a version marker). Empty skips the extra patch.
	UpdateAnnotations []string
	// DisplayName / DisplayVersion are presentation only, echoed in Apply's
	// per-Space banner and the default ChangeSet description.
	DisplayName    string
	DisplayVersion string
}