mirror

type DesiredAsset struct {
	Name   string
	Digest string // content digest, "" if unknown
	Size   int64
	Source forge.ReleaseAsset // remote source (mirror re-host)
	Local  string             // local file path (author upsert)
}

type DesiredLink struct {
	Name     string
	URL      string
	LinkType string
}

type DesiredRelease struct {
	Tag         string
	Ref         string
	Name        string
	Body        string
	Prerelease  bool
	Assets      []DesiredAsset // downloadable files: download from source → upload to mirror
	Links       []DesiredLink  // external references (registry/image): re-created as links
	Diagnostics []string       // explicit notes about assets that could not be classified
	Fingerprint string
}

type Destroyer interface {
	DeleteRelease(ctx context.Context, tag string) error
}

type Options struct {
	Prune   bool
	InScope func(tag string) bool

	// PreserveAdopted is called with the mirror's CURRENT release, once, immediately
	// before an unmarked in-scope release is overwritten by adoption. Adoption is the
	// only step that replaces content SF did not write, so it is also the only one that
	// can lose something — this is the hook that makes it recoverable. Returning an
	// error ABORTS that adoption: what cannot be preserved is not destroyed. Nil skips
	// preservation entirely (the caller accepts the loss).
	PreserveAdopted func(tag string, prior forge.ReleaseInfo) error
}

type RefOptions struct {
	Prune bool
	Force bool
	// ForceRef force-updates a SPECIFIC diverged ref even when Force is off — for a
	// ref that is mutable BY DESIGN (a rolling tag alias like "latest" that advances
	// each release and would otherwise perpetually diverge). Immutable refs are left to
	// the default keep-divergent path. nil means "no per-ref force". Force (the blanket
	// flag) still wins for every ref when set.
	ForceRef func(ref string) bool
	// IsAncestor reports whether the first commit is an ancestor of the second. It
	// distinguishes a fast-forward (the mirror ref is behind the source) from a true
	// divergence: a differing ref whose mirror commit is an ancestor of the source
	// commit fast-forwards (a non-force Update), everything else keeps divergent. It
	// must return false whenever either commit is not resolvable in local history — a
	// mirror commit absent locally IS the divergence signal. nil ⇒ every differing ref
	// is treated as diverged (the ancestry-blind behavior).
	IsAncestor func(ancestor, descendant string) bool
	InScope    func(ref string) bool
}

type RefPlan struct {
	Create   []RefUpdate // refs missing on the mirror
	Update   []RefUpdate // fast-forward, or forced when diverged+Force
	Diverged []string    // diverged, kept (Force off) — surfaced, never clobbered
	Prune    []RefUpdate // OUR refs (in scope) gone from source — deletes
	Foreign  []string    // mirror-only refs outside scope — left untouched
	InSync   int         // already matching
}

type RefUpdate struct {
	Ref    string // e.g. "refs/heads/main" or a bare branch/tag name (caller's convention)
	SHA    string // target commit (empty for a delete)
	Force  bool   // overwrite a diverged ref (only set when Force is enabled)
	Delete bool   // remove the ref on the mirror

	// Verified marks an update PROVEN to be a fast-forward by ancestry over peeled
	// commits. The executor may assert it instead of asking the transport to
	// re-derive the same answer from unpeeled ref hashes — which it cannot do for
	// an annotated tag, whose ref hash names a tag object rather than a commit.
	Verified bool
}

type Result struct {
	Created []string
	Updated []string
	Pruned  []string
	InSync  int      // skipped via fingerprint fast-path
	Adopted []string // in-scope tag existed unmarked — converged and marked as ours
	Errors  []error
	// Diagnostics are non-fatal notes surfaced separately from Errors — e.g. a source
	// asset that is neither a downloadable file nor an external link, disclosed instead of
	// silently 404-ing or being uploaded as a pretend-file.
	Diagnostics []string
}