validator

type AnchorCheck struct {
	RequiredCount int      `json:"required_count"`
	FoundCount    int      `json:"found_count"`
	Ordered       bool     `json:"ordered"`
	AnchorsFound  []string `json:"anchors_found"`
	Missing       []string `json:"missing"`
	OrderExpected []string `json:"order_expected"`
	OrderActual   []string `json:"order_actual"`
	FinalPresent  bool     `json:"final_present"` // FINAL GUARD invariant
}

type BlacklistHealth struct {
	Manual BlacklistSubHealth `json:"manual"`
	Feeds  BlacklistSubHealth `json:"feeds"`
	Geoban BlacklistSubHealth `json:"geoban"`
}

type BlacklistJSON struct {
	Manual BlacklistSubJSON `json:"manual"`
	Feeds  BlacklistSubJSON `json:"feeds"`
	Geoban BlacklistSubJSON `json:"geoban"`
}

type BlacklistSubHealth struct {
	State   string `json:"state"`             // enforcing|primed|idle|loaded|stale|disabled
	Entries int    `json:"entries,omitempty"` // element count (manual/feeds)
	Drops   int64  `json:"drops,omitempty"`   // counter value (manual only — attributable)
}

type BlacklistSubJSON struct {
	State   string `json:"state"`             // enforcing|primed|idle|loaded|stale|degraded|disabled
	Entries int    `json:"entries,omitempty"` // element count (omitted if 0 or not applicable)
	Drops   int64  `json:"drops,omitempty"`   // counter value (omitted if 0 or not attributable)
}

type BotGuardCountersJSON struct {
	Decisions     FamilyCounts `json:"decisions"`      // IP-backed (also by decision in Prometheus)
	EventbusDrops uint64       `json:"eventbus_drops"` // not IP-backed → no family
}

type BotScanCountersJSON struct {
	ScannedEntries FamilyCounts `json:"scanned_entries"`
	Matched        FamilyCounts `json:"matched"`        // also by category in Prometheus
	Signals        FamilyCounts `json:"signals"`        // also ban vs grey in Prometheus
	Bans           FamilyCounts `json:"bans"`           // also by reason/category in Prometheus
	CrawlerVerify  FamilyCounts `json:"crawler_verify"` // also ok/bad/timeout/cachehit in Prometheus
	FilesDeferred  uint64       `json:"files_deferred"` // per-file rotation/budget — NOT IP-backed, no family
}

type CSFConflictResult struct {
	State    CSFConflictState
	Evidence []string
}

type CSFConflictState string

type ChainCheck struct {
	Required []string `json:"required"`
	Found    []string `json:"found"`
	Missing  []string `json:"missing"`
	AllFound bool     `json:"all_found"`
}

type ChainCounts struct {
	IPv4Total   int `json:"ipv4_total"`
	IPv4Base    int `json:"ipv4_base"`
	IPv4Helper  int `json:"ipv4_helper"`
	IPv6Total   int `json:"ipv6_total"`
	IPv6Base    int `json:"ipv6_base"`
	IPv6Helper  int `json:"ipv6_helper"`
	TotalChains int `json:"total_chains"`
}

type ConfigState string

type ConsistencyCheck struct {
	Module string `json:"module"`
	Check  string `json:"check"`  // what was compared
	Result string `json:"result"` // "ok" | "mismatch"
	Detail string `json:"detail,omitempty"`
}

type ConsistencyJSON struct {
	KernelVsValidator string `json:"kernel_vs_validator"` // ok|mismatch|unknown (v1.229.7)
}

type ConsistencyResult struct {
	Overall  string             `json:"overall"` // "ok" | "mismatch" | "unknown" (v1.229.7)
	Checks   []ConsistencyCheck `json:"checks"`
	Findings []Finding          `json:"-"` // collected, appended to main result
}

type CountersJSON struct {
	BotScan   *BotScanCountersJSON   `json:"botscan,omitempty"`
	BotGuard  *BotGuardCountersJSON  `json:"botguard,omitempty"`
	Whitelist *WhitelistCountersJSON `json:"whitelist,omitempty"`
}

type EffectiveState string

type ErrKind string

type FamilyCounts struct {
	IPv4    uint64 `json:"ipv4,omitempty"`
	IPv6    uint64 `json:"ipv6,omitempty"`
	Inet    uint64 `json:"inet,omitempty"`    // table-level only (e.g. inet-chain forward/output)
	Unknown uint64 `json:"unknown,omitempty"` // last-resort; on per-IP counters indicates a classification gap
}

type FamilyResult struct {
	Family       string      `json:"family"` // "ip" or "ip6"
	Status       Status      `json:"status"`
	TablePresent bool        `json:"table_present"`
	ChainCount   int         `json:"chain_count"`
	SetCount     int         `json:"set_count"`
	BaseChains   ChainCheck  `json:"base_chains"`
	HelperChains ChainCheck  `json:"helper_chains"`
	Anchors      AnchorCheck `json:"anchors"`
	Sets         SetCheck    `json:"sets"`
}

type Finding struct {
	Code        string   `json:"code"`
	Severity    Severity `json:"severity"`
	Component   string   `json:"component"`
	Family      string   `json:"family,omitempty"`
	Message     string   `json:"message"`
	Remediation string   `json:"remediation,omitempty"`
}

type FindingJSON struct {
	Code        string `json:"code"`
	Severity    string `json:"severity"` // info|warn|error|critical
	Component   string `json:"component"`
	Family      string `json:"family,omitempty"`
	Message     string `json:"message"`
	Remediation string `json:"remediation,omitempty"`
}

type HealthOutput struct {
	SchemaVersion string           `json:"schema_version"`
	Status        string           `json:"status"`
	Timestamp     string           `json:"timestamp"`
	ServiceState  ServiceStateJSON `json:"service_state"`
	Modules       ModulesJSON      `json:"modules"`
	Consistency   ConsistencyJSON  `json:"consistency"`
	Findings      []FindingJSON    `json:"findings"`
	ChainCounts   ChainCounts      `json:"chain_counts"`
	Summary       SummaryCounts    `json:"summary"`
	// v1.84 SCHEMA-UNFREEZE counters contract (additive).
	CountersPhase string        `json:"counters_phase"`     // "contract" (v1.190.0) | "populated" (v1.191.0); the anti-false-zero gate
	Counters      *CountersJSON `json:"counters,omitempty"` // nil/ABSENT until v1.191.0 populates — absent ≠ zero (no false-zero dashboards)
	// v1.84 NFT counting-model contract view (additive; nil/ABSENT until v1.191.0).
	NFT *NFTCountersJSON `json:"nft,omitempty"` // interpreted JSON VIEW over existing nft named counters — NOT a new Prometheus family (SOS-2 Option A)
}

type InputState string

type JournalEvidence struct {
	Found        bool    // true if at least one pattern matched
	MatchedLine  string  // first matching line (newest-first order)
	MatchedIndex int     // index of matched line in output (0-based)
	LinesRead    int     // total lines read from journal
	Truncated    bool    // true if journalctl hit -n limit
	ErrKind      ErrKind // failure classification
	Err          error   // underlying error (nil on success)
}

type JournalQuery struct {
	Unit     string        // systemd unit to filter (e.g. "nftband")
	Patterns []string      // substring patterns to match (first match wins)
	Since    time.Duration // how far back to look (default 15m)
	MaxLines int           // max lines from journalctl -n (default 200)
	Timeout  time.Duration // exec timeout (default 2s)
}

type JournalReader interface {
	Query(ctx context.Context, q JournalQuery) JournalEvidence
}

type ModuleClass string

type ModuleHealth struct {
	Config     ConfigState     `json:"config"`
	Structural StructuralState `json:"structural,omitempty"`
	Runtime    RuntimeState    `json:"runtime,omitempty"`
	Effective  EffectiveState  `json:"effective,omitempty"`
	Input      InputState      `json:"-"` // internal (v1.183); surfaced via CodeLoginMonNoInput finding, not the frozen schema
	// StructuralReason carries WHY the structural verdict is what it is.
	// Internal (v1.229.7 PR-3A), same schema-safe pattern as Input above: it is
	// surfaced through the consistency detail and the findings array, never as a
	// new field in the frozen M81-6 ModuleJSON.
	//
	// It exists because the three-value axis cannot distinguish causes that are
	// operationally opposite:
	//   MISSING  — expected objects absent  vs  the OTHER mode's objects PRESENT
	//   UNKNOWN  — the EXPECTATION failed   vs  the OBSERVATION failed
	// Reporting "objects missing" for cross-mode drift is a false statement, and
	// merging the two unknowns hides which side of the contract broke.
	StructuralReason StructuralReason `json:"-"`
}

type ModuleHealthMap struct {
	BotGuard  *ModuleHealth    `json:"botguard,omitempty"`
	DDoS      *ModuleHealth    `json:"ddos,omitempty"`
	Portscan  *ModuleHealth    `json:"portscan,omitempty"`
	LoginMon  *ModuleHealth    `json:"loginmon,omitempty"`
	Blacklist *BlacklistHealth `json:"blacklist,omitempty"`
}

type ModuleJSON struct {
	Config     string `json:"config"`               // enabled|disabled (always present)
	Structural string `json:"structural,omitempty"` // present|missing|unknown (omitted if disabled); unknown = expectation unestablished (v1.229.7)
	Runtime    string `json:"runtime,omitempty"`    // running|stopped (omitted if not daemon-dependent)
	Effective  string `json:"effective,omitempty"`  // enforcing|observing|idle (omitted if disabled)

}

type ModulesJSON struct {
	BotGuard  *ModuleJSON    `json:"botguard,omitempty"`
	DDoS      *ModuleJSON    `json:"ddos,omitempty"`
	Portscan  *ModuleJSON    `json:"portscan,omitempty"`
	LoginMon  *ModuleJSON    `json:"loginmon,omitempty"`
	Blacklist *BlacklistJSON `json:"blacklist,omitempty"`
}

type NFTAnchorJSON struct {
	Family  string `json:"family"`  // ipv4|ipv6 (normalized from nft ip/ip6); anchors never inet/unknown — unknown ⇒ collection defect
	Anchor  string `json:"anchor"`  // anchor_hygiene|anchor_trusted|anchor_ban|anchor_established|anchor_detect|anchor_service|anchor_final
	Packets uint64 `json:"packets"` // from the named counter (real value once populated v1.191.0)
	Bytes   uint64 `json:"bytes"`   // from the named counter
}

type NFTCountersJSON struct {
	Anchors []NFTAnchorJSON `json:"anchors,omitempty"` // phase-boundary view; see NFTAnchorJSON
}

type NftChain struct {
	Family   string `json:"family"`
	Table    string `json:"table"`
	Name     string `json:"name"`
	Type     string `json:"type,omitempty"`
	Hook     string `json:"hook,omitempty"`
	Priority int    `json:"prio,omitempty"`
	Policy   string `json:"policy,omitempty"`
	Handle   int    `json:"handle,omitempty"`
}

type NftCounter struct {
	Family  string `json:"family"`
	Table   string `json:"table"`
	Name    string `json:"name"`
	Handle  int    `json:"handle,omitempty"`
	Packets int64  `json:"packets,omitempty"`
	Bytes   int64  `json:"bytes,omitempty"`
}

type NftMetainfo struct {
	Version           string `json:"version"`
	ReleaseName       string `json:"release_name"`
	JsonSchemaVersion int    `json:"json_schema_version"`
}

type NftObject struct {
	Metainfo *NftMetainfo `json:"metainfo,omitempty"`
	Table    *NftTable    `json:"table,omitempty"`
	Chain    *NftChain    `json:"chain,omitempty"`
	Set      *NftSet      `json:"set,omitempty"`
	Rule     *NftRule     `json:"rule,omitempty"`
	Counter  *NftCounter  `json:"counter,omitempty"`
}

type NftRule struct {
	Family  string        `json:"family"`
	Table   string        `json:"table"`
	Chain   string        `json:"chain"`
	Handle  int           `json:"handle,omitempty"`
	Comment string        `json:"comment,omitempty"`
	Expr    []interface{} `json:"expr,omitempty"`
}

type NftRuleset struct {
	Nftables []NftObject `json:"nftables"`
}

type NftSet struct {
	Family  string     `json:"family"`
	Table   string     `json:"table"`
	Name    string     `json:"name"`
	Type    NftSetType `json:"type,omitempty"`
	Flags   []string   `json:"flags,omitempty"`
	Timeout int        `json:"timeout,omitempty"`
	Handle  int        `json:"handle,omitempty"`
}

type NftSetType struct {
	Types []string
}

type NftTable struct {
	Family string `json:"family"`
	Name   string `json:"name"`
	Handle int    `json:"handle,omitempty"`
}

type RulesetDocument struct {
	// contains filtered or unexported fields
}

type RuntimeState string

type ServiceChecker interface {
	// CheckUnit returns (RuntimeState, detail string).
	// RuntimeState: RUNNING / STOPPED / ERROR.
	// detail: the raw systemctl output (e.g. "active", "inactive", "failed").
	CheckUnit(unit string) (RuntimeState, string)
}

type ServiceState struct {
	Nftband       RuntimeState `json:"nftband"`
	NftbandDetail string       `json:"nftband_detail,omitempty"`
	TimerCount    int          `json:"timer_count"` // v1.83: active nftban-* timer count
}

type ServiceStateJSON struct {
	Nftband       string `json:"nftband"`                  // RUNNING|STOPPED|ERROR
	NftbandDetail string `json:"nftband_detail,omitempty"` // raw systemctl output
	TimerCount    int    `json:"timer_count"`              // v1.83: active nftban-* timer count
}

type SetCheck struct {
	Required []string `json:"required"`
	Found    []string `json:"found"`
	Missing  []string `json:"missing"`
	AllFound bool     `json:"all_found"`
}

type Severity string

type Status string

type StructuralReason string

type StructuralState string

type SummaryCounts struct {
	TotalFindings    int `json:"total_findings"`
	CriticalFindings int `json:"critical_findings"`
	ErrorFindings    int `json:"error_findings"`
	WarnFindings     int `json:"warn_findings"`
	CheckedFamilies  int `json:"checked_families"`
	ProtectedFams    int `json:"protected_families"`
	DegradedFams     int `json:"degraded_families"`
}

type SystemdChecker struct{}

type SystemdJournalReader struct{}

type SystemdTimerChecker struct{}

type TimerChecker interface {
	// CountActiveTimers returns the number of active nftban-* timers.
	// On query error it returns (0, error).
	CountActiveTimers() (int, error)
}

type ValidationResult struct {
	SchemaVersion      string          `json:"schema_version"`
	Status             Status          `json:"status"`
	Timestamp          time.Time       `json:"timestamp"`
	Families           []FamilyResult  `json:"families"`
	Findings           []Finding       `json:"findings"`
	Summary            SummaryCounts   `json:"summary"`
	ChainCount         ChainCounts     `json:"chain_counts"`
	ServiceState       ServiceState    `json:"service_state"`
	Modules            ModuleHealthMap `json:"modules"`             // M81-4
	ConsistencyOverall string          `json:"consistency_overall"` // v1.82: "ok" | "mismatch"

	// v1.89 INV-M-001/002: Expose kernel state for evidence layer.
	// These fields are internal — not serialized to the frozen JSON schema.
	Doc              *RulesetDocument `json:"-"` // parsed kernel ruleset (counters, chains, sets)
	SetElementCounts map[string]int   `json:"-"` // "family:set" → element count
	// v1.229.11: keys whose element count could NOT be observed (exec/decode
	// failure). ADDITIVE — a key present here has NO entry in SetElementCounts,
	// so a consumer can never read a failed observation as a count of zero.
	//   ABSENT COUNT + UNKNOWN=true  !=  COUNT 0
	SetElementUnknown map[string]bool `json:"-"` // "family:set" → observation failed
}

type WhitelistCountersJSON struct {
	Changes FamilyCounts `json:"changes"` // IP-backed (also by op add/remove/expire in Prometheus)
}