auditretention

type Options struct {
	// Before is the cutoff: rows with a timestamp strictly older are eligible.
	// Required — a zero value is rejected rather than silently interpreted as
	// "now", which would prune the entire trail.
	Before time.Time

	// ExportDir is the directory the seal is written to. Created if missing.
	ExportDir string

	// Actor is recorded on the anchor. Defaults to "system".
	Actor string

	// DryRun resolves and reports the candidate without writing or deleting
	// anything — not even the export.
	DryRun bool

	// BatchSize is how many rows are read and written per round trip. Zero
	// selects a sane default. Bounded internally.
	BatchSize int

	// Uncompressed writes plain JSONL instead of gzip. The zero value
	// compresses, which is the right default for a write-once, read-rarely,
	// highly repetitive archive.
	Uncompressed bool

	// Hold is how far the audit sinks forwarding this chain have all got
	// (Task 20426): the newest row every live cursor has acknowledged, from
	// auditforward.RetentionHold. Nil means no sink forwards the chain.
	// Unless Force is set the prune stops at it, so retention never removes a
	// row a configured sink has not received.
	Hold *statedb.AuditForwardHold

	// Force prunes past Hold. Rows a sink has not acknowledged are sealed and
	// removed anyway, and reach that sink only through the archive; the
	// forwarder records the loss as an audit.forward.discontinuity row.
	Force bool

	// Now is injected by tests. Production leaves it nil.
	Now func() time.Time
}

type Report struct {
	DryRun bool
	Cutoff time.Time

	// Candidate is the resolved prefix. Count == 0 means there was nothing
	// older than the cutoff and no other field is meaningful.
	Candidate statedb.AuditPruneCandidate

	ExportPath   string
	ExportSHA256 string
	ExportBytes  int64

	// Anchor is the row written. Zero when DryRun or when nothing was pruned.
	Anchor statedb.AuditAnchor

	// Pruned reports that rows were actually deleted.
	Pruned bool

	// Clamped reports that the cutoff was clamped to Options.Hold: rows
	// older than the cutoff that a sink has not acknowledged were kept.
	// HeldBy names the slowest sink, HeldThroughID the newest row it has
	// acknowledged, and Requested is the prefix the cutoff alone would have
	// removed. Candidate is what was removed instead.
	Clamped       bool
	HeldBy        string
	HeldThroughID int64
	Requested     statedb.AuditPruneCandidate

	// ForcedPast names the sinks a forced prune removed unacknowledged rows
	// from under, in name order.
	ForcedPast []string
}

type SealStatus struct {
	Anchor statedb.AuditAnchor
	// Present is false when the file is missing — which is not necessarily
	// wrong (archives get moved to cold storage on purpose) but is always
	// worth saying out loud.
	Present bool
	OK      bool
	Actual  string
	Err     error
}