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

	// RunActive tells the pass that this project is currently executing a
	// task, and RunActiveReason says how the caller knows. It suppresses the
	// steps prune only.
	//
	// Separate from SkipVacuum because it protects against a different thing.
	// SkipVacuum is about latency: a rewrite would stall a live run's writes.
	// This is about correctness: a run keeps the whole step history in memory
	// and upserts all of it on every save, so rows deleted underneath it come
	// back. Every other row table here is append-only and safe to prune while a
	// task runs.
	RunActive       bool
	RunActiveReason 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

	// ProviderCallBodyMaxAge clears the prompt, system prompt and response of
	// provider_calls rows older than this, keeping the row. See
	// DefaultProviderCallBodyMaxAge for why the bodies and the row have
	// different lifetimes.
	ProviderCallBodyMaxAge time.Duration

	// ProviderCallMaxRows, StepMaxRows, EventMaxRows and CostMaxRows are the
	// per-table row ceilings; the newest rows survive.
	ProviderCallMaxRows int
	StepMaxRows         int
	EventMaxRows        int
	CostMaxRows         int

	// TelemetryMaxAge deletes browser telemetry older than this. Age rather
	// than count because the table already has a write-time row cap; what it
	// lacks is a way for a quiet trail to expire.
	TelemetryMaxAge time.Duration

	// 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"`
	// The row tables (Task 20291), pruned before the VACUUM so it has
	// something to reclaim.
	ProviderCalls StepResult `json:"provider_calls"`
	Steps         StepResult `json:"steps"`
	Events        StepResult `json:"events"`
	Costs         StepResult `json:"costs"`
	Telemetry     StepResult `json:"telemetry"`
	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 is space returned to the filesystem — files removed, or the
	// shrink a VACUUM achieved.
	BytesFreed int64
	// BytesReleased is space returned to the *database freelist* by deleting
	// rows. The file does not shrink until the VACUUM step runs, which is why
	// this is reported separately and is deliberately excluded from
	// Report.BytesFreed: adding both would count the same bytes twice, once
	// when the rows went and again when the rewrite handed the pages back.
	BytesReleased int64
	Err           error
}