fix(validator): CF-1..4 spec-conformance audit fixes for v1.81 release

Resolves 4 critical failures from SPEC_CONFORMANCE_AUDIT_v1.81.md.

CF-1: service_state.nftband now emits uppercase ("RUNNING"|"STOPPED"|
"ERROR") matching JSON_SCHEMA_SPEC §5. Module runtime fields remain
lowercase per spec. Fix: removed normalizeRuntime() call for
service_state, using raw RuntimeState enum string directly.

CF-2: geoban DB missing now emits "stale" (in allowed blacklist sub-state
enum) instead of "degraded" (not in enum). Also emits VAL-GEOBAN-001
finding (SeverityWarn) for visibility. New finding code registered in
types.go. Module findings collected via moduleFindings slice and
appended to result.Findings.

CF-3: JSON_SCHEMA_SPEC_v1.81.md updated to mark families and module_truth
as "legacy-only (ToJSONLegacy), not part of M81-6 primary schema."
The M81-6 HealthOutput replaces module_truth with the richer modules
block. No code change — spec alignment only.

CF-4: countSetElements() stub documented as v1.81 known limitation with
explicit consequence description and v1.82 fix target. BotGuard
ENFORCING/OBSERVING and blacklist PRIMED states are unreachable
from the validator until per-set queries are implemented.

All tests pass on lab4. Live output verified: uppercase service_state,
geoban="stale" with VAL-GEOBAN-001 finding, no schema violations.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: itcmsgr

internal/validator/health_mapper.go

@@ -34,7 +34,7 @@ func MapToHealthOutput(r *ValidationResult) HealthOutput {
 		Status:        string(r.Status),
 		Timestamp:     r.Timestamp.UTC().Format("2006-01-02T15:04:05Z"),
 		ServiceState: ServiceStateJSON{
-			Nftband:       normalizeRuntime(r.ServiceState.Nftband), // lowercase in JSON
+			Nftband:       string(r.ServiceState.Nftband), // UPPERCASE per spec §5: RUNNING|STOPPED|ERROR
 			NftbandDetail: r.ServiceState.NftbandDetail,
 		},
 		Modules:     mapModules(r.Modules),

internal/validator/module_health.go

@@ -32,7 +32,11 @@ var ConfigDir = "/etc/nftban"
 
 // evaluateModuleHealth evaluates all modules and returns the health map.
 // Called from ValidateKernel after structural + runtime checks.
+// evaluateModuleHealth evaluates all modules and returns the health map.
+// Also populates moduleFindings with any module-specific findings.
+// The caller MUST append moduleFindings to result.Findings after this call.
 func evaluateModuleHealth(doc *RulesetDocument, svcState ServiceState) ModuleHealthMap {
+	moduleFindings = nil // reset for this evaluation cycle
 	m := ModuleHealthMap{}
 
 	m.BotGuard = evaluateBotGuard(doc, svcState)
@@ -249,6 +253,10 @@ func evaluateLoginMon(svcState ServiceState) *ModuleHealth {
 // Blacklist — unified: manual + feeds + geoban
 // =============================================================================
 
+// ModuleFindings collects findings from module health evaluation.
+// These are appended to the main ValidationResult.Findings by the caller.
+var moduleFindings []Finding
+
 func evaluateBlacklist(doc *RulesetDocument) *BlacklistHealth {
 	bh := &BlacklistHealth{}
 
@@ -285,10 +293,20 @@ func evaluateBlacklist(doc *RulesetDocument) *BlacklistHealth {
 		// Check if geoip database exists.
 		// Per M81-3 contract: enabled + DB missing = DEGRADED (not just stale).
 		// Stale = DB exists but older than 45 days (future: check mtime).
+		// Per CF-2 resolution: geoban DB missing uses "stale" (in allowed enum)
+		// and emits a finding for visibility. "degraded" is not in the blacklist
+		// sub-state enum (enforcing|primed|idle|loaded|stale|disabled).
 		dbPath := "/var/cache/nftban/geoban/dbip-country-lite.mmdb"
 		info, err := os.Stat(dbPath)
 		if err != nil || info.Size() == 0 {
-			bh.Geoban = BlacklistSubHealth{State: "degraded"} // missing or empty = DEGRADED
+			bh.Geoban = BlacklistSubHealth{State: "stale"} // missing DB = stale data
+			moduleFindings = append(moduleFindings, Finding{
+				Code:        CodeGeobanDBMissing,
+				Severity:    SeverityWarn,
+				Component:   "module",
+				Message:     "GeoIP database missing or empty — geoban enforcement unavailable",
+				Remediation: "Run: nftban geoban sync",
+			})
 		} else {
 			// DB exists. Future: check mtime > 45 days → "stale".
 			bh.Geoban = BlacklistSubHealth{State: "loaded"}
@@ -359,19 +377,21 @@ func feedsExist() bool {
 
 // countSetElements returns the number of elements in a kernel set.
 //
-// NOTE: nft -j list ruleset does NOT include set elements in its output
-// (only set metadata: name, type, flags). Actual element counting requires
-// a separate `nft -j list set <family> <table> <name>` command per set,
-// which is expensive and outside the current single-command validator model.
+// countSetElements is a STUB — v1.81 KNOWN LIMITATION (CF-4).
+//
+// nft -j list ruleset does NOT include set elements in its output (only set
+// metadata: name, type, flags). Actual element counting requires a separate
+// `nft -j list set <family> <table> <name>` command per set, which is
+// expensive and outside the current single-command validator model.
 //
-// For now, this returns 0. BotGuard enforcement evidence and blacklist
-// element counting require per-set queries which are a Day 2+ enhancement.
-// The validator's current evidence model handles this correctly:
-// - zero = NEUTRAL per vocabulary Rule 1
-// - BotGuard defaults to IDLE (not DEGRADED)
-// - manual blacklist defaults to IDLE (not false PRIMED)
+// Consequence: BotGuard can never reach ENFORCING or OBSERVING states from
+// the validator (requires ban/suspect set population > 0). Manual blacklist
+// can never reach PRIMED (requires manual set population > 0). Both default
+// to IDLE, which is correct per vocabulary Rule 1 (zero = NEUTRAL).
 //
-// Future: add targeted set queries for enforcement-critical sets only.
+// This is documented in the v1.81 release notes as a known limitation.
+// Real fix: v1.82 — add targeted per-set queries for enforcement-critical
+// sets (http_bot_ban, http_bot_suspect, blacklist_manual_ipv4).
 func countSetElements(_ *RulesetDocument, _, _ string) int {
 	return 0
 }

internal/validator/types.go

@@ -257,6 +257,9 @@ const (
 	// Service findings (B80-4)
 	CodeServiceDown = "VAL-SERVICE-001" // required service not active
 
+	// Module-specific findings (M81-4)
+	CodeGeobanDBMissing = "VAL-GEOBAN-001" // geoip database missing/empty
+
 	// System findings
 	CodeNftFailed    = "VAL-SYSTEM-001"
 	CodeNftNoOutput  = "VAL-SYSTEM-002"

internal/validator/validator.go

@@ -173,6 +173,8 @@ func ValidateKernel(ctx context.Context) (*ValidationResult, error) {
 
 	// M81-4: Per-module health evaluation
 	result.Modules = evaluateModuleHealth(doc, result.ServiceState)
+	// Collect any module-specific findings (e.g. VAL-GEOBAN-001)
+	result.Findings = append(result.Findings, moduleFindings...)
 
 	// Compute summary
 	result.Summary = computeSummary(result)