validate

type AssertionOpts struct {
	// PanelPolicy controls how the panel-survival assertion converts
	// adapter outcomes into a pass/fail verdict. PR26.3+ wires this
	// from the operator's --no-panel flag and any future policy
	// flags through the installer's globalPhaseData.
	PanelPolicy panelfw.PanelPolicy

	// PanelAdapters is an optional adapter slice override. When nil,
	// the assertion uses panelfw.RegisteredAdapters(). Tests pass a
	// fixture-controlled slice (typically containing FakePanelAdapter)
	// to exercise the framework without touching the global registry.
	PanelAdapters []panelfw.PanelAdapter

	// HealthResource is the v1.222.1 health-resource reconciliation verdict
	// produced in phaseConfigure. When non-nil, the health_resource_policy_active
	// assertion consumes it (single policy path — no recomputation). Nil in
	// contexts that did not run the reconciler (assertion is skipped/PASS).
	HealthResource *healthresource.Verdict

	// SystemdPayloadInputs, when non-nil, is used VERBATIM by RunAssertionsWithOpts
	// in place of GatherSystemdPayloadInputs(real host). v1.223.0 verdict-truth:
	// DATA-only dependency-injection so the systemd-payload assertions are
	// exercisable off-host WITHOUT a mutable package global or var-func seam.
	// Production leaves it nil → the real host gather runs (byte-identical default).
	// Fail-safe is PRESERVED: an empty/zero injected value is fed to
	// ValidateInstalledSystemdPayload exactly like an empty real gather — there is
	// NO nil/empty→PASS shortcut, so PAYLOAD-INVENTORY-001 (and the failed-unit
	// query-error fail-closed) still fire on injected inputs that warrant them.
	SystemdPayloadInputs *SystemdPayloadInputs

	// LogRetentionValidator, when non-nil, overrides the logrotate policy validator
	// used by the logretention_policy_ready assertion. v1.223.0 verdict-truth: nil in
	// production (the assertion then uses the package readinessValidator → the real
	// `logrotate -d`); execution-path tests inject a deterministic validator so the
	// assertion does NOT depend on the `logrotate` binary being installed (it is
	// absent in CI containers). Bounded DI, mirrors SystemdPayloadInputs.
	LogRetentionValidator lr.Validator

	// FailedUnitsOut, when non-nil, receives the FINAL-pass FATAL failed-unit set
	// (spr.FailedUnits) so the caller (phaseValidate) can propagate the STRUCTURED
	// names into install_state SERVICES_FAILED — the v1.222.1 Lane 4 fix for
	// BUG-INSTALLER-FAILED-UNITS-STRUCTURED-STATE-NOT-POPULATED. Recovered/auxiliary
	// units are excluded (only fatal, DEGRADED-causing units).
	FailedUnitsOut *[]FailedUnitPostInstall

	// WhitelistConvergence is the v1.228.5 durable whitelist convergence verdict
	// as persisted in install_state WHITELIST_CONVERGENCE. Callers pass the value
	// they hold (phaseValidate: the verdict phaseConfigure just recorded on the
	// live StateFile; revalidate: the value read back from disk). Consumed by the
	// whitelist_convergence_ok assertion — DATA only, no recomputation here
	// (SyncWhitelist is a mutation and must never run inside validation).
	//
	// BACKWARD COMPATIBILITY (explicit, not incidental): "" means NOT EVALUATED —
	// either an install_state written before v1.228.5 (no WHITELIST_CONVERGENCE=
	// line at all → the parser leaves the field zero) or a caller that does not
	// evaluate this dimension. "" is never read as CONVERGED and never converted
	// into a FAILED. It mirrors the nil-HealthResource SKIP convention above.
	WhitelistConvergence string

	// ConvergenceVerified is the v1.230.0 Gate 6R post-update convergence verdict as
	// persisted in install_state CONVERGENCE_VERIFIED. DATA only — the verification
	// itself (switchop.VerifyPostUpdateConvergence) runs in phaseSwitch, where the
	// BEFORE reading of the effective generation exists; re-probing here could only see
	// the AFTER value and would prove nothing.
	//
	// "" means NOT EVALUATED — a pre-v1.230.0 install_state, or a caller that does not
	// evaluate this dimension. ⛔ Never read as VERIFIED, never converted into a FAIL.
	ConvergenceVerified string
	// contains filtered or unexported fields
}

type AssertionResult struct {
	Name   string
	Passed bool
	Detail string
}

type ExecDirective struct {
	// Directive is one of ExecStart, ExecStartPre, ExecStartPost,
	// ExecStop, ExecStopPost, ExecReload.
	Directive string

	// Raw is the full RHS as written in the unit file (after the "=").
	Raw string

	// Binary is the resolved primary executable absolute path.
	// For wrapper invocations like "/bin/sh -c '...'", this is "/bin/sh"
	// and EmbeddedNftbanPaths captures any nftban-owned absolute paths
	// found inside the quoted argument.
	Binary string

	// EmbeddedNftbanPaths lists any nftban-owned absolute paths
	// discovered inside Raw that are NOT the primary Binary. Caught
	// from common shell-wrapper patterns ("/bin/sh -c '/usr/lib/...sh'",
	// "/usr/bin/env BAR=1 /usr/lib/...bin").
	EmbeddedNftbanPaths []string
}

type FailedUnitFinding struct {
	Unit   string
	Active string // e.g., "failed"
	Sub    string // e.g., "failed", "exit-code"
	Detail string // best-effort short description, may be empty

	// FailureTime is the unit's last-failure timestamp (most recent of
	// InactiveEnterTimestamp / ExecMainExitTimestamp from `systemctl show`).
	// v1.174 D-INSTALL-FAILED-UNITS-STALE-LATCHED-STATE: used to classify
	// a failed unit as pre-existing (failed before the install window) vs
	// in-window. Zero value when unknown.
	FailureTime time.Time

	// FailureTimeKnown is true only when FailureTime was parsed
	// successfully. When false, the unit is treated as a hard failure
	// (fail closed) — an unparseable timestamp can never be classified as
	// pre-existing/recovered.
	FailureTimeKnown bool

	// OwnedWindowReverifyDone / OwnedWindowReverifyClean carry the result of
	// the v1.201 host-side gated re-verify, performed ONLY for
	// isCadenceReverifiableOneshot units (watchdog/soak/maintenance). The
	// gatherer reset-failed the unit and issued a fresh `systemctl start`;
	// Clean is true ONLY when that re-run succeeded and the unit is no longer
	// failed. The classifier consults these to tolerate a transient
	// (re-verified-clean) cadence-oneshot latch as non-fatal; an absent or
	// false result keeps the unit FATAL (no-mask: a persistent failure that
	// re-fails its run is never cleared). Zero value = no re-verify attempted.
	OwnedWindowReverifyDone  bool
	OwnedWindowReverifyClean bool

	// Ownership records WHY this unit is in the findings list. v1.228.5:
	// enumeration previously filtered on IsNftbanUnit at gather time, so a SYSTEM
	// unit that NFTBan itself had broken was never collected. MEASURED 2026-08-06:
	// INSTALL_STATE reached COMMITTED while logrotate.service was failed on
	// NFTBan's own generated /etc/logrotate.d/nftban stanza.
	// NFTBAN_UNIT_PREFIX != NFTBAN_FAILURE_OWNERSHIP.
	//
	// Empty on findings produced before this field existed; treat "" as
	// OwnNftbanPackageUnit for backward compatibility (every pre-v1.228.5 finding
	// had already passed the IsNftbanUnit filter).
	Ownership FailureOwnership
	// OwnershipWhy explains a non-package attribution so an operator can act on a
	// blocked install that names a unit not called nftban-*.
	OwnershipWhy string
}

type FailedUnitPostInstall struct {
	Unit   string
	Detail string

	// Classification is the v1.174 disposition of the failure, one of:
	// "" (default / in-window fatal), "IN_WINDOW", "PRE_EXISTING_FATAL"
	// (pre-existing but live health not clean/unknown), or
	// "WARN_PRE_EXISTING_RECOVERED" (pre-existing + live health clean —
	// non-fatal). Diagnostic only; the fatal/non-fatal decision is encoded
	// by which result bucket the entry lands in.
	Classification string
}

type FailureOwnership string

type MissingExecPath struct {
	UnitFile  string
	Directive string
	Path      string
	RawLine   string
}

type MissingTimerTarget struct {
	TimerUnit  string
	TargetUnit string
}

type ParsedUnit struct {
	// Name is the unit basename (e.g., "nftban-unified-exporter.service").
	Name string

	// Path is the absolute on-disk path of the unit file.
	Path string

	// IsTimer is true for *.timer units.
	IsTimer bool

	// Execs is the list of ExecStart/Pre/Post/Stop directives extracted
	// from [Service]. Order preserved for diagnostic output.
	Execs []ExecDirective

	// TimerUnit is the [Timer] Unit= value (or implicit basename.service
	// when the directive is absent). Empty for non-timer units.
	TimerUnit string
}

type PayloadInventory struct {
	// Paths is the set of absolute paths the staged install knows
	// about. Population strategy: populate from the install's payload
	// destination table (see internal/installer/payload).
	Paths map[string]bool

	// NftbanOwnedPrefixes lists absolute path prefixes that, if a unit
	// references a path under one of them, that path MUST be in Paths
	// or referenced via a system-binary wrapper. Typical:
	// "/usr/lib/nftban/", "/usr/sbin/nftban", "/etc/nftban/".
	NftbanOwnedPrefixes []string

	// SystemBinaryPrefixes lists absolute path prefixes whose contents
	// are NOT required to be in Paths. Typical: "/usr/bin/", "/bin/",
	// "/usr/sbin/" (excluding the singular "/usr/sbin/nftban"), "/sbin/".
	SystemBinaryPrefixes []string
}

type RevalidateResult struct {
	// Validate1Passed is true if initial assertions all passed.
	Validate1Passed bool

	// FixAttempted is true if bounded safe fix was run (only when V1 fails).
	FixAttempted bool

	// FixExitCode is the exit code of the permissions enforce command.
	FixExitCode int

	// Validate2Passed is true if re-validation passed after fix.
	// Only meaningful when FixAttempted is true.
	Validate2Passed bool

	// FinalPassed is the authoritative result: V1 if no fix needed, V2 if fix ran.
	FinalPassed bool

	// FailedNames contains assertion names that failed in the final validation.
	FailedNames []string
}

type SystemIntegration struct {
	// Unit is the system unit name as systemd reports it.
	Unit string
	// Artifacts are absolute paths NFTBan installs or generates which this unit reads.
	// Presence of ANY of them means NFTBan participates in the integration. Absence means
	// NFTBan does not, and a failure of Unit is NOT attributable to NFTBan.
	Artifacts []string
	// Why documents the causal link, so an operator reading a blocked install understands
	// why a non-nftban unit is being attributed to NFTBan.
	Why string
}

type SystemdPayloadInputs struct {
	// Units is the parsed nftban-owned unit set in the install scope.
	// Non-nftban units are filtered upstream by the gatherer; this
	// validator does NOT enforce invariants on third-party units.
	Units []ParsedUnit

	// PathExists reports whether an absolute path exists on disk.
	// Tests stub with a closure over a map; production wires through
	// the executor.
	PathExists func(absPath string) bool

	// Inventory holds payload-known paths and prefix policy.
	Inventory PayloadInventory

	// FailedNftbanUnits is the set of currently-failed nftban units.
	// Populated upstream from `systemctl list-units --state=failed`.
	FailedNftbanUnits []FailedUnitFinding

	// FailedUnitQueryError is non-empty when the upstream gatherer
	// could not enumerate failed units (e.g., systemctl missing,
	// non-zero exit, dbus unavailable). When set,
	// FAILED-UNIT-POSTINSTALL-001 fails closed: the absence of
	// findings cannot be distinguished from a healthy install.
	// Operator must resolve the enumeration error before
	// StateCommitted is permitted.
	FailedUnitQueryError string

	// AllUnitNames is the set of every unit basename present in the
	// install's unit directories (services + timers + sockets). Used
	// by SYSTEMD-TIMER-PAIR-001 to confirm a timer's target service
	// is installed alongside it.
	AllUnitNames map[string]bool

	// InstallWindowStart is the wall-clock instant the current installer
	// run began (set once at the very start of the run via
	// SetInstallWindowStart). A failed unit whose FailureTime is strictly
	// before this instant is "pre-existing"; one at/after is "in-window".
	// v1.174 D-INSTALL-FAILED-UNITS-STALE-LATCHED-STATE.
	InstallWindowStart time.Time

	// InstallWindowStartKnown is true only when InstallWindowStart was
	// set. When false, no failed unit can be classified as pre-existing —
	// all non-aux failures stay fatal (fail closed).
	InstallWindowStartKnown bool

	// LiveHealthClean reports whether a bounded live `nftban health` probe
	// returned a clean overall status (Overall OK/IDLE, Findings: none, no
	// CRITICAL). Only consulted to downgrade a PRE_EXISTING latched failure.
	LiveHealthClean bool

	// LiveHealthKnown is true only when the live-health probe produced a
	// confident clean/not-clean verdict. When false (probe timeout, missing
	// binary, unparseable output, non-zero exit), no downgrade is permitted
	// — pre-existing failures stay fatal (fail closed).
	LiveHealthKnown bool
}

type SystemdPayloadValidationResult struct {
	// OK is true iff every invariant passed.
	OK bool

	// MissingExecPaths is the SYSTEMD-EXECSTART-001 finding set.
	MissingExecPaths []MissingExecPath

	// MissingTimerTargets is the SYSTEMD-TIMER-PAIR-001 finding set.
	MissingTimerTargets []MissingTimerTarget

	// UnknownPayloadRefs is the PAYLOAD-INVENTORY-001 finding set.
	UnknownPayloadRefs []UnknownPayloadRef

	// FailedUnits is the FAILED-UNIT-POSTINSTALL-001 finding set, restricted
	// to protection-critical units. A non-empty slice fails the invariant.
	FailedUnits []FailedUnitPostInstall

	// FailedAuxiliaryUnits holds failed nftban units classified as auxiliary
	// (metrics/observability — see IsAuxiliaryUnit). These are surfaced as a
	// non-fatal warning and do NOT fail FAILED-UNIT-POSTINSTALL-001 (so a
	// transient exporter exit-2 cannot DEGRADE the install — D-EXPORTER-
	// SETTLE-WINDOW, v1.135).
	FailedAuxiliaryUnits []FailedUnitPostInstall

	// FailedUnitsPreExistingRecovered holds protection-critical nftban units
	// that were ALREADY in a failed state before this install window started
	// AND whose live `nftban health` probe is clean. v1.174 D-INSTALL-FAILED-
	// UNITS-STALE-LATCHED-STATE: these are a stale latch, not a fresh break,
	// so they are surfaced as WARN_PRE_EXISTING_RECOVERED and do NOT fail
	// FAILED-UNIT-POSTINSTALL-001 (install COMMITTED-with-warning). A newly-
	// failed unit, or a pre-existing one with live health not clean/unknown,
	// stays in FailedUnits (fatal) — fail safe toward DEGRADED.
	FailedUnitsPreExistingRecovered []FailedUnitPostInstall

	// FailedUnitsTransientRecovered holds cadence-oneshot nftban units
	// (isCadenceReverifiableOneshot: watchdog/soak/maintenance) whose failed
	// latch was recovered by the v1.201 host-side gated re-verify — the unit
	// was reset-failed and a fresh `systemctl start` ran CLEAN, proving the
	// latch was transient (the v1.198.3 watchdog/update-swap EXEC-203 class).
	// Surfaced as WARN_TRANSIENT_RECOVERED and does NOT fail
	// FAILED-UNIT-POSTINSTALL-001. A cadence-oneshot whose re-run still fails
	// (or was never re-verified) stays in FailedUnits (fatal) — no-mask.
	FailedUnitsTransientRecovered []FailedUnitPostInstall

	// FailedUnitQueryError mirrors SystemdPayloadInputs.FailedUnitQueryError
	// for the assertion-side detail message. When non-empty,
	// FAILED-UNIT-POSTINSTALL-001 fails closed regardless of
	// FailedUnits content.
	FailedUnitQueryError string
}

type TimerState struct {
	Enabled           bool // systemctl is-enabled (will start on boot)
	ActiveOrScheduled bool // .timer unit active (scheduled to fire)
}

type TimerValidationInputs struct {
	// ReconcileDisabled is true when NFTBAN_RECONCILE_CORE_TIMERS=false — an
	// intentional operator opt-out; validation passes (Skipped), not DEGRADED.
	ReconcileDisabled bool
	// Critical is the set of critical core timer unit names to check.
	Critical []string
	// States maps a critical timer unit -> observed state.
	States map[string]TimerState
}

type TimerValidationResult struct {
	OK      bool     // all critical timers enabled + active/scheduled (or Skipped)
	Skipped bool     // reconcile intentionally disabled
	Missing []string // critical timers not enabled+active (sorted)
}

type UnknownPayloadRef struct {
	UnitFile string
	Path     string
}