feat(v1.100 PR-24): authority restoration policy decision engine

[itcmsgr]

Implements the pure decision engine locked by PR #493 (contract seed). PR-24 is POLICY ONLY — zero kernel, service, or filesystem mutation. Refusal and intent-required are valid and expected outcomes.

Scope (locked per seed §2)

• ✅ internal/installer/restore/ decision engine (pure function over 4 axes)
• ✅ --mode=restore CLI dispatcher
• ✅ State-machine entries: StateRestoreRefused, StateRestoreIntentRequired (terminal, non-failed, non-apply-terminal) + StateRestoreDecided (non-terminal handoff marker, per seed §7 locked constraints)
• ✅ Exit codes: ExitRefused=5, ExitIntentRequired=6
• ✅ 4 CI gates in G4-RESTORE-* namespace
• ❌ No kernel mutation
• ❌ No service mutation
• ❌ No filesystem writes (static-scan enforced)
• ❌ No history write (IsApplyTerminal=false + cfg.mode != "restore" gate)
• ❌ No restoration-execution code (belongs to PR-25+)

Lattice (seed §6 v2 + locked amendments)

Top-down precedence (§5, load-bearing):

1. Classifier hard-stops
2. Input / flag validity
3. Prior-record integrity gates
4. Panel context gates
5. Proceed decisions

Locked amendments implemented:

• NoRecord + --restore → REQUIRE_EXPLICIT_INTENT (not PROCEED — --restore requires a recorded target)
• Legacy prior records missing ActiveAtInstall → classified as Incomplete by uninstall.Probe (PR-P2-1) → flows to REQUIRE_EXPLICIT_INTENT
• Staleness window fixed at 365 days (seed §3.B); configurability deferred
• StateRestoreDecided non-terminal, non-apply-terminal, excluded from history, not evidence of restoration

Output discipline

Closed Go enum of exactly three values:

OutputProceed               Output = "PROCEED"
OutputRefuse                Output = "REFUSE"
OutputRequireExplicitIntent Output = "REQUIRE_EXPLICIT_INTENT"

No fourth value. No default branch. Unreached code paths panic() as contract-regression guards (CI catches them).

Tests

Fixture matrix in internal/installer/restore/engine_test.go:

• TestDecide_FixtureMatrix — 24 rule-path fixtures (every declared rule exercised)
• TestRuleCoverage_EveryRuleExercised — bidirectional coverage assertion (declared ↔ fixtures)
• TestDecide_Determinism — reflect.DeepEqual on back-to-back evaluations
• TestDecide_OutputClosedEnum — no path emits outside the 3-value enum
• TestDecide_LockedAmendment_NoRecordRestoreRequiresIntent — explicit guard for the locked amendment in both AuthorityNone + AmbiguityOrphanNFTBan paths
• TestDecide_HardStopsDominateAnyFlag — exhaustive matrix: 3 hard-stops × 4 flag combos × 5 priors × 2 panel states = 120 cells per hard-stop, all must REFUSE
• TestDecide_OrphanPanelAutoRefused — orphan + --panel-auto-takeover REFUSES under every prior

CI gates

.github/workflows/ci-restore-canonization.yml (matrix: ubuntu-24.04 + almalinux-9):

Gate	What it asserts
G4-RESTORE-NO-IMPLICIT-EXEC	Static scan: restore package has zero forbidden symbols (exec.*, os.Create/WriteFile/Rename/Remove/Mkdir, nft/iptables/systemctl literal calls, service helpers, rebuild/switchop mutation helpers)
G4-RESTORE-DECISION-CORRECTNESS	Runs the full fixture matrix + rule-path coverage assertion
G4-RESTORE-REFUSAL-INTEGRITY	Structural layering: restore package does not import executor; dispatcher does not import switchop/services
G4-RESTORE-DETERMINISM	Two independent test runs; normalized output diff must be empty

No G3 gate weakened. Carry-forward uninstall gates (G3-UN-SHIM-LOCK, G3-UN-NO-MUTATION, G3-EXEC-TRACE, G3-KS-SNAPSHOT) continue to apply.

Dispatcher flow (cmd/nftban-installer/restore_decide.go)

1. uninstall.Classify → authority + ambiguity (single source of truth)
2. uninstall.Probe → prior-record (PR-P2-1 hardened schema)
3. Reduce probe + 365-day window → restore.PriorState normalized enum
4. detect.DetectPanel → panel type → boolean
5. Assemble DecisionInput
6. restore.Decide(input) — pure, no side effects
7. Log structured decision-path record (inputs + matched rule + output)
8. sf.Transition to terminal / non-terminal state
9. Return exit code

Preflight errors (malformed prior record, classifier Ambiguous without sub-kind) → ExitFatal=4 — does NOT emit a lattice output, keeping the three-output space closed per seed §9.

Reviewer checklist (merge-blocking, per seed §13 + code-phase §6)

Policy correctness:

• Every classifier state handled (no default branch)
• Every prior-record state handled
• Group 1 hard-stops dominate all flag/panel inputs
• Panel context never causes proceed without --panel-auto-takeover
• NoRecord + --restore returns REQUIRE_EXPLICIT_INTENT
• Legacy records missing ActiveAtInstall → Incomplete → REQUIRE_EXPLICIT_INTENT
• Staleness window fixed at 365 days (not configurable in PR-24)

Safety:

• AuthorityExternal never overridden
• AmbiguityConflictExternal never overridden
• Orphan + --panel-auto-takeover → REFUSE
• No auto-upgrade path from REQUIRE_EXPLICIT_INTENT to PROCEED

Purity:

• Zero kernel interaction
• Zero service interaction
• Zero filesystem writes in the restore package (G4-RESTORE-NO-IMPLICIT-EXEC green)
• update-history.json schema unchanged
• No executor dependency in restore package (G4-RESTORE-REFUSAL-INTEGRITY green)

Output discipline:

• Output is a closed Go enum of three
• StateRestoreDecided excluded from IsApplyTerminal and from history
• Exit codes distinct: ExitRefused=5, ExitIntentRequired=6

Evidence:

• All 4 G4 gates green on both DEB + RPM matrix
• lab4 decision-only evidence (bare → REQUIRE_EXPLICIT_INTENT; --restore-prior-authority → REQUIRE_EXPLICIT_INTENT; exec-trace clean)
• lab2 supplementary evidence (bare → REFUSE under G1/AuthorityNFTBan; exec-trace clean)

Real-host evidence (2026-04-20)

Required decision-only host matrix satisfied. Supplementary AuthorityNFTBan → REFUSE branch also proven on real host. Remaining dangerous branches (AuthorityExternal, AmbiguityConflictExternal, AmbiguityOrphanNFTBan, weak-record, panel-driven proceed) are fixture-only per seed §11 — simulating them at kernel level would violate the no-mutation gate via the test harness itself.

Binary provenance

Frozen CI artifact from commit 7330f8cb:

sha256 = 0cfe8db8f4192dfeefcd0e957cf5314e42ad8194ee8f665ace322d27847f5896

Identical binary used on both hosts.

lab4 — AlmaLinux 9.7 / RPM (required matrix)

Host state: AuthorityNone + NoRecord (released post-PR-23, never reinstalled).

Case	Rule	Output	Exit	Mutation spawns
--mode=restore (bare)	G3.3/NoRecord+NoFlag	REQUIRE_EXPLICIT_INTENT	6	0
--mode=restore --restore-prior-authority	G3.3/NoRecord+Restore	REQUIRE_EXPLICIT_INTENT	6	0

Terminal state on both: RESTORE_INTENT_REQUIRED. Panel: cpanel (informational; Group 3.3 bare/restore paths do not depend on panel context).

lab2 — Ubuntu 24.04 / DEB (supplementary)

Host state: AuthorityNFTBan (from PR-23 reinstall round-trip; intentionally not forced into AuthorityNone).

Case	Rule	Output	Exit	Mutation spawns
--mode=restore (bare)	G1/AuthorityNFTBan	REFUSE	5	0

Terminal state: RESTORE_REFUSED. Panel: plesk (informational; Group 1 dominates regardless of panel).

Purity proof (all three invocations)

Process spawns observed via strace -f -e trace=execve:

/usr/bin/systemctl       ← is-active / is-enabled probes (READ-ONLY)
/usr/sbin/iptables-save  ← ghost-rule count probe (READ-ONLY)
/usr/sbin/nft            ← list tables / list table probes (READ-ONLY)

Zero spawns of:

• nft with add/flush/delete/create/insert/replace
• systemctl with start/stop/enable/disable/mask/unmask/reload/restart/daemon-reload
• iptables/ip6tables/ufw/firewall-cmd (any args)

Host-state invariance

Host	Signal	BEFORE	AFTER
lab4	nft list tables	empty	empty
lab4	nftband.service	inactive + masked	inactive + masked
lab2	nft list tables	inet filter + ip nftban + ip6 nftban	identical
lab2	nftband.service	active + enabled	active + enabled

Zero host-state change across all three invocations.

Test plan

• Build & Test green — fixture matrix + coverage + determinism + closed-enum + locked-amendment + hard-stop dominance + orphan+panel-auto refusal
• Restore Canonization Gate green — G4-RESTORE-NO-IMPLICIT-EXEC + G4-RESTORE-DECISION-CORRECTNESS + G4-RESTORE-REFUSAL-INTEGRITY + G4-RESTORE-DETERMINISM across DEB + RPM matrix
• All existing gates green (no G3 weakening)
• lab4 decision-only evidence (required matrix)
• lab2 supplementary evidence (AuthorityNFTBan → REFUSE)

Follow-up items (seed §15, carried forward, not blocking PR-24)

1. ActiveAtInstall capture in new prior-record writes
2. Staleness-window configurability knob
3. Uninstall-history schema decision (carried from PR-23)
4. Panel-auto + prior-record-identity consistency (revisit in PR-25)

🤖 Generated with Claude Code

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
actions/actions/checkout	34e114876b0b11c390a56381ad16ebd13914f8d5	🟢 5.7	Details Check Score Reason Maintained ⚠️ 0 0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0 Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Binary-Artifacts 🟢 10 no binaries found in the repo Code-Review 🟢 10 all changesets reviewed Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Fuzzing ⚠️ 0 project is not fuzzed Packaging ⚠️ -1 packaging workflow not detected License 🟢 10 license file detected Signed-Releases ⚠️ -1 no releases found Pinned-Dependencies 🟢 3 dependency not pinned by hash detected -- score normalized to 3 Security-Policy 🟢 9 security policy file detected Branch-Protection 🟢 5 branch protection is not maximal on development and all release branches SAST 🟢 8 SAST tool detected but not run on all commits
actions/actions/setup-go	d35c59abb061a4a6fb18e82ac0862c26744d6ab5	🟢 5.7	Details Check Score Reason Maintained 🟢 6 7 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 6 Code-Review 🟢 10 all changesets reviewed Binary-Artifacts 🟢 10 no binaries found in the repo Packaging ⚠️ -1 packaging workflow not detected Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Pinned-Dependencies ⚠️ 0 dependency not pinned by hash detected -- score normalized to 0 Fuzzing ⚠️ 0 project is not fuzzed License 🟢 10 license file detected Signed-Releases ⚠️ -1 no releases found Security-Policy 🟢 9 security policy file detected Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches SAST 🟢 10 SAST tool is run on all commits

Scanned Files

• .github/workflows/ci-restore-canonization.yml