storage

type AnonymousVolume struct {
	Name        string
	Created     time.Time
	UnusedSince time.Time
}

type BackedOffError struct {
	// Path is where the distress was observed.
	Path string
	Err  error
}

type BudgetUnreachableError struct {
	// Cache names the cache ("shared go build cache").
	Cache string
	// Estimated is the cache's estimated size, Budget its size budget, and
	// Young the estimated bytes last used inside Floor (the safety floor, or the
	// age of the oldest running build plus its margin when that is longer), in bytes.
	Estimated, Budget, Young uint64
	Floor                    time.Duration
}

type CutOffError struct{ Err error }

type DanglingImage struct {
	ID string
	// Repository is the repository the image was pushed to, from its digest
	// reference, or "". It is for the person reading the plan; no decision
	// reads it.
	Repository string
	Created    time.Time
	Size       uint64
}

type Disk struct {
	Path      string `json:"path"`
	Available uint64 `json:"available_bytes"`
	Capacity  uint64 `json:"capacity_bytes"`
}

type Facts struct {
	// Project is the project directory whose rotated logs forge may expire.
	// Stored absolute.
	Project string
	// Contexts are kubectl contexts whose workloads protect images in the
	// registry. Only local `k3d-` contexts are accepted: retention reads the
	// protected set from them, and a remote cluster forge cannot list would
	// make deletion unsafe.
	Contexts []string
	// Registry is the local registry's CONTAINER name (`k3d-…`), which is
	// also how `forge storage gc` addresses it.
	Registry string
	// Aliases are every host name under which that one registry is pushed to
	// or pulled from — the containerd mirror keys plus the in-network
	// `<container>:5000`. A repository is attributed to this registry only
	// when its host is one of these.
	Aliases []string
	// Repositories are full image references, registry host included. The
	// host is matched against Aliases and then stripped: retention works in
	// repository paths, as the registry API does.
	Repositories []string
	// Pins are image digests that must survive retention regardless of age.
	Pins []string
	// Repos are git repositories (any path inside one) whose worktrees the
	// worktree layer may reclaim: the project's own and its build siblings.
	Repos []string
}

type GCResult struct {
	At time.Time `json:"at"`
	OK bool      `json:"ok"`
	// FailedLayers names each layer that failed: "logs", "temp sweep",
	// "source cache", "builder <name>", "registry <container>", "docker".
	FailedLayers []string `json:"failed_layers,omitempty"`
	// Error is the combined error text, for a human reading the record.
	Error string `json:"error,omitempty"`
	// CutOffLayers names each layer that ran out of its time slice (or the
	// pass out of its budget) after doing what it could. That is not a
	// failure: the layer reclaimed what it reached and resumes next pass. A
	// pass whose only problems are cut-offs is OK.
	CutOffLayers []string `json:"cut_off_layers,omitempty"`
	// BackedOffLayers names each layer that stopped, or never started,
	// because the filesystem reported distress (EMFILE, ENFILE, ENOTCONN,
	// EIO). Like a cut-off it retained the rest for the next pass and is not
	// a failure, but it says the MACHINE is unwell, so it is reported apart.
	BackedOffLayers []string `json:"backed_off_layers,omitempty"`
	// OverBudget describes each cache the pass could not bring under its size
	// budget because more than the budget is younger than the trim's safety
	// floor (BudgetUnreachableError). Not a failure — the pass removed what it
	// safely could — but a budget that is not being held, so it is reported
	// on every pass until the fill slows.
	OverBudget []string `json:"over_budget,omitempty"`
	// GoCaches is what each Go-format cache trim in the pass measured and
	// did (Runner.OnGoCacheTrim). Set by the caller that ran the pass.
	GoCaches []GoCacheTrim `json:"go_caches,omitempty"`
}

type GoCacheTrim struct {
	// Cache names the cache ("shared go build cache"); Root is its directory.
	Cache string `json:"cache"`
	Root  string `json:"root"`
	// Applied is false for a dry run, which removes nothing.
	Applied bool `json:"applied"`
	// EstimatedBytes is the cache's estimated size before the trim,
	// BudgetBytes its size budget, and YoungBytes the estimated bytes last
	// used inside the safety floor, which no trim deletes.
	EstimatedBytes uint64 `json:"estimated_bytes"`
	BudgetBytes    uint64 `json:"budget_bytes"`
	YoungBytes     uint64 `json:"young_bytes"`
	// Cutoff is the last-use time below which entries were removed.
	Cutoff time.Time `json:"cutoff"`
	// Removed and FreedBytes are what the trim removed (or, dry, would have).
	Removed    int    `json:"removed"`
	FreedBytes uint64 `json:"freed_bytes"`
	// ShardsCovered of ShardsTotal were walked to the end; Finished is true
	// when that is all of them. A trim that did not finish resumes at the
	// first uncovered shard next pass.
	ShardsCovered int  `json:"shards_covered"`
	ShardsTotal   int  `json:"shards_total"`
	Finished      bool `json:"finished"`
	// OldestLiveBuild is the age of the oldest running Go build that held the
	// cutoff back past the floor (gocache_livebuild.go); zero when none did.
	OldestLiveBuild time.Duration `json:"oldest_live_build_ns,omitempty"`
}

type LayerError struct {
	Layer string
	Err   error
}

type PlanEntry struct {
	Version
	// Untagged marks a manifest no tag points at: an orphan left behind by a
	// re-push of a reused tag, unreachable from anything retained.
	Untagged bool
	// Tags are the aliases that disappear with this manifest.
	Tags  []string
	Bytes uint64
	Sized bool
}

type Policy struct {
	Projects         []string `json:"projects,omitempty"`
	LogBudgetGiB     uint64   `json:"log_budget_gib"`
	HostReserveGiB   uint64   `json:"host_reserve_gib"`
	HostPaths        []string `json:"host_paths,omitempty"`
	BuildCacheGiB    uint64   `json:"build_cache_gib"`
	BuildCacheUnused string   `json:"build_cache_unused"`
	ImageUnused      string   `json:"image_unused"`
	// GoCacheUnused is how long a shared Go build cache entry (and the
	// golangci-lint cache) may sit unused before it is trimmed. Minimum 2h:
	// Go refreshes an entry's mtime on use once it is an hour stale, so that
	// floor is what keeps the trim safe under running builds.
	GoCacheUnused string `json:"go_cache_unused"`
	// GoCacheGiB is the size the shared Go caches are trimmed down to,
	// oldest first, when age alone leaves them larger.
	GoCacheGiB uint64 `json:"go_cache_gib"`
	// GoCacheVolumePercent caps that budget at this share of the volume the
	// cache lives on, so the default works on a 40 GiB build volume as well as
	// on a 1 TB laptop: the budget is the smaller of go_cache_gib and this
	// share. Zero means the default (15); 100 leaves go_cache_gib alone.
	GoCacheVolumePercent int `json:"go_cache_volume_percent,omitempty"`
	// GolangciCacheGiB is the size the golangci-lint cache is trimmed down
	// to, least recently used first, like go_cache_gib for the build cache
	// and capped the same way. Its own budget because its entries are tiny
	// and recomputed in seconds: under go_cache_gib it was never trimmed.
	GolangciCacheGiB uint64 `json:"golangci_cache_gib"`
	// SourceCacheUnused is how long a cross-repo source clone may go
	// unresolved before it becomes an eviction candidate. Longer than the
	// image and build-cache windows because the cost of being wrong is a
	// full re-clone of a repository, not a re-pull of a layer.
	SourceCacheUnused string `json:"source_cache_unused"`
	// SourceCacheKeep is how many of the most recently used clones of one
	// repository are retained regardless of age. This is the floor that
	// keeps an idle project's current pin warm, so it is validated at 1 or
	// more: a policy that can empty a repository's only pin is not a policy
	// anyone wants by accident.
	SourceCacheKeep int `json:"source_cache_keep"`
	// SourceCacheGiB is the size the source cache is evicted down to, least
	// recently used clone first, never touching the newest source_cache_keep
	// clones of a repository. The age rule alone does not bound it: a project
	// that bumps its pin every few hours produces more clones in
	// source_cache_unused than any age can hold.
	SourceCacheGiB uint64 `json:"source_cache_gib"`
	// SourceCacheSlimAfter is how long a clone beyond the newest
	// source_cache_keep of its repository may sit unused before its installed
	// dependencies (node_modules) are removed. Those are 80% of a clone's
	// bytes and a build reinstalls them (frontenddeps.Ensure); the pristine
	// checkout stays.
	SourceCacheSlimAfter string     `json:"source_cache_slim_after"`
	RegistryDays         int        `json:"registry_days"`
	RegistryKeep         int        `json:"registry_keep"`
	DockerContext        string     `json:"docker_context,omitempty"`
	Builders             []string   `json:"builders"`
	Registries           []Registry `json:"registries,omitempty"`
	Clusters             []string   `json:"clusters,omitempty"`
	Pins                 []string   `json:"pins,omitempty"`

	// Repos are git repositories whose linked worktrees the worktree layer
	// reclaims, beyond the repository of each registered project: sibling
	// repos a project builds from (docker.build_contexts, go.mod replaces).
	// Filled by Converge; git itself enumerates the worktrees, wherever they live.
	Repos []string `json:"repos,omitempty"`
	// WorktreeRebuildable replaces the built-in allowlist of ignored paths a
	// removable worktree may contain. Nil means the defaults.
	WorktreeRebuildable []string `json:"worktree_rebuildable,omitempty"`
	// WorktreeReap lets an explicit `forge storage gc --apply` remove
	// worktrees. Off, the layer only reports. No automatic pass ever removes
	// one, whatever this says (Runner.Explicit).
	WorktreeReap bool `json:"worktree_reap,omitempty"`
	// WorktreeReapReliantManaged extends worktree_reap to worktrees under
	// Reliant's worktree root (~/.reliant/worktrees). Reliant owns those: it
	// knows which chat each one is bound to, and reclaims them itself. Off,
	// they are held like a locked worktree.
	WorktreeReapReliantManaged bool `json:"worktree_reap_reliant_managed,omitempty"`

	// MaxDeletesPerPass bounds how many filesystem entries one maintenance
	// pass may unlink, across every layer. What is left is retained and the
	// next pass continues, so a budget is reached over several passes rather
	// than by one burst of six-figure unlinks. Zero means the default.
	MaxDeletesPerPass int `json:"max_deletes_per_pass"`
	// DeleteRatePerSec paces those unlinks. Zero means the default.
	DeleteRatePerSec int `json:"delete_rate_per_sec"`

	// AnonymousVolumeUnused is how long forge must have seen an anonymous
	// Docker volume referenced by no container, running or stopped, before
	// an explicit `forge storage gc --apply` may remove it (anonvolumes.go).
	// Minimum 24h; "off" disables the layer. Named volumes are never removed,
	// whatever this says.
	AnonymousVolumeUnused string `json:"anonymous_volume_unused"`
	// MaxDockerRemovalsPerPass bounds how many Docker images and volumes one
	// pass asks the daemon to remove. Zero means the default.
	MaxDockerRemovalsPerPass int `json:"max_docker_removals_per_pass"`
}

type Registry struct {
	Container    string   `json:"container"`
	Repositories []string `json:"repositories"`
	Aliases      []string `json:"aliases"`
	Contexts     []string `json:"contexts"`
}

type ReserveError struct {
	Path       string
	Available  uint64
	ReserveGiB uint64
}

type Revision struct {
	Version
	Modified time.Time
}

type Runner struct {
	Policy  Policy
	Out     io.Writer
	Command func(context.Context, string, ...string) ([]byte, error)
	// SourceCacheRoot overrides the cross-repo source cache the Sources
	// layer reclaims from. Empty means the real machine-local cache in
	// production, and is REFUSED under `go test` — see sources.go.
	SourceCacheRoot string
	// TempRoot overrides the system temp directory the TempSweep layer
	// reclaims from. Empty means os.TempDir() in production, and is
	// REFUSED under `go test` — see tempsweep.go.
	TempRoot string
	// PolicyPath is the policy file this pass was loaded from. Maintenance
	// state that must outlive the process — the marker recording that a
	// registry was stopped for GC — is kept beside it, so a later pass can
	// find and repair what an interrupted one left behind.
	PolicyPath string
	// Ctx bounds the host-filesystem layers (logs, temp sweep, source cache),
	// which take no context of their own. GC and NonDisruptiveGC set it from
	// theirs, so a pass's deadline bounds the whole pass — its lsof snapshot
	// and its walk over entries, not only its docker calls. Nil means
	// unbounded.
	Ctx context.Context

	// Explicit marks the one pass a person or agent invoked: `forge storage
	// gc` without --scheduled. Only it may remove what no observation can
	// prove abandoned — worktrees (and then only under the policy's
	// worktree_reap) and anonymous Docker volumes. Every automatic pass leaves
	// it false: the background auto-gc, the installed schedule and `forge
	// storage daemon`. An agent between two commands holds no process in its
	// worktree, and an orphaned volume may be the only copy of a database, so
	// to a pass nobody invoked either looks exactly like garbage.
	Explicit bool

	// Go-cache layer roots (gocache.go). Empty means the real machine
	// location in production and is REFUSED under `go test`.
	GoCacheRoot       string // shared GOCACHE
	GolangciCacheRoot string
	// OpenPaths is the lsof snapshot. REFUSED under test when unset.
	OpenPaths func(context.Context) (openfiles.Snapshot, error)
	// OnGoCacheTrim, when set, receives what each Go-format cache trim
	// measured and did (gocache.go). The CLI collects them into the pass's
	// record. It may be called from the layer's goroutine; it is never called
	// concurrently.
	OnGoCacheTrim func(GoCacheTrim)
	// LiveToolchainAges lists how long each running Go toolchain process has
	// lived (gocache_livebuild.go). Nil reads the process table in
	// production and means "no builds" under test.
	LiveToolchainAges func(context.Context) ([]time.Duration, error)
	// contains filtered or unexported fields
}

type StaleLocalImage struct {
	Ref string
	ID  string
}

type Tag struct {
	Repository string
	Name       string
	Digest     string
	Pushed     time.Time
}

type Version struct {
	Repository string
	Digest     string
}

type WorktreeHold struct {
	Path, Repo, Reason, Detail string
}

type WorktreeReport struct {
	// Removable are worktrees that passed every check (removed when applied).
	Removable []string
	// Removed is the subset actually removed.
	Removed []string
	Held    []WorktreeHold
}