janitor

type Options struct {
	// WorkDir is the project root; the janitor operates on WorkDir/.cloop.
	WorkDir string
	Policy  Policy

	// DryRun reports what a pass would reclaim without deleting or vacuuming.
	DryRun bool

	// InstanceID is the hub lease identity of the process running this pass.
	// When empty, the VACUUM step refuses if *any* hub holds the lease — the
	// correct behaviour for an out-of-process caller such as the CLI. When
	// set, it refuses only if the holder is somebody else.
	InstanceID string

	// SkipVacuum suppresses the VACUUM regardless of the freelist, and
	// SkipVacuumReason says why. The hub sets this for a project that is
	// currently executing a task: SQLite would serialise the rewrite against
	// the orchestrator's writes rather than corrupt anything, but stalling a
	// live run for the minutes a multi-gigabyte rewrite takes is not a
	// trade the janitor gets to make unprompted. The file-level steps still
	// run — pruning old snapshots is safe under a live writer.
	SkipVacuum       bool
	SkipVacuumReason string

	// Now is the clock, injectable for tests. Nil means time.Now.
	Now func() time.Time
}

type Policy struct {
	// Enabled gates the whole janitor. False means the hub starts no
	// background pass at all — the documented opt-out.
	Enabled bool

	// Interval is how often the hub runs a pass. Zero selects
	// DefaultInterval.
	Interval time.Duration

	// KeepSnapshots bounds .cloop/plan-history. Zero or less disables
	// plan-history pruning and keeps everything.
	KeepSnapshots int

	// ArchiveMaxBytes caps the total size of .cloop/audit-archive; the
	// oldest seals are deleted until the directory fits. Zero disables the
	// size cap.
	//
	// Both archive limits default to off, and deliberately so. A seal is the
	// only copy of audit rows that have already been deleted from the
	// database — deleting one destroys the record rather than relocating it,
	// which is the opposite of what the rest of the audit path does. It is
	// also not a default-install problem: archives exist only if the operator
	// opted into audit retention in the first place (config audit.retention_days
	// is itself zero by default), so an operator who has seals has already
	// made a retention decision and is the right person to make this one too.
	// `cloop doctor` reports the directory's size so that decision is
	// prompted by data rather than by a full disk.
	ArchiveMaxBytes int64

	// ArchiveMaxAgeDays deletes seals older than this many days. Zero
	// disables the age limit. See ArchiveMaxBytes for why this is opt-in.
	ArchiveMaxAgeDays int

	// VacuumFreeRatio is the freelist fraction at or above which the janitor
	// vacuums. Zero selects DefaultVacuumFreeRatio; a value >= 1 disables
	// vacuuming, since no database can be more than entirely free.
	VacuumFreeRatio float64

	// VacuumMinFreeBytes is an absolute floor beneath which the ratio is
	// ignored. Zero selects DefaultVacuumMinFreeBytes; negative disables the
	// floor.
	VacuumMinFreeBytes int64

	// VacuumMaxInlineBytes caps the live data an *in-process* VACUUM will
	// rewrite, protecting the hub's own lease heartbeat from a rewrite that
	// outlasts it. Zero selects DefaultVacuumMaxInlineBytes; negative removes
	// the cap. It applies only when Options.InstanceID is set — a caller with
	// no lease at stake has nothing to protect.
	VacuumMaxInlineBytes int64

	// ArchiveDir is the directory holding sealed audit exports. Empty means
	// <workDir>/.cloop/audit-archive, which is auditretention's default — but
	// a real deployment is advised to point audit.export_dir at storage the
	// hub does not otherwise own, and retention has to follow the seals there
	// or it silently bounds an empty directory while the real one grows.
	ArchiveDir string
}

type Report struct {
	WorkDir     string        `json:"work_dir"`
	StartedAt   time.Time     `json:"started_at"`
	Duration    time.Duration `json:"duration"`
	DryRun      bool          `json:"dry_run"`
	PlanHistory StepResult    `json:"plan_history"`
	Archive     StepResult    `json:"audit_archive"`
	Vacuum      StepResult    `json:"vacuum"`
	// Before and After are the .cloop breakdowns either side of the pass.
	// After is nil for a dry run, which changes nothing.
	Before *diskusage.Usage `json:"before,omitempty"`
	After  *diskusage.Usage `json:"after,omitempty"`
}

type StepResult struct {
	// Ran is false when the step was disabled or had nothing to do; Reason
	// then says which.
	Ran bool
	// Skipped marks a step that was applicable but deliberately not run —
	// principally the VACUUM below its threshold. Distinguished from "ran and
	// found nothing" so an operator can tell a working threshold from a
	// broken step.
	Skipped    bool
	Reason     string
	Deleted    int
	BytesFreed int64
	Err        error
}