feat(v1.100 Amendment 2): code-A — G1/AuthorityNFTBan split + §54 evidence predicate + --accept-orphan-nftban (#519)

Decision-layer implementation of Amendment 2 (contract.md §§52–61).
Splits the existing G1/AuthorityNFTBan row into two evaluated-within-
Group-1 sub-rules:

- G1/AuthorityNFTBan/default — REFUSE, unchanged behavior for all flag
  patterns outside the candidate triple.
- G1/AuthorityNFTBan/orphan-intent-candidate — delegates to the §54
  evidence predicate; G1/AuthorityNFTBan/OrphanProceed on all-true,
  G1/EvidenceMismatch on any-false.

Split is ENTIRELY within Group 1; no later group ever defeats a Group 1
outcome and §5 precedence is preserved.

Implementation surface
======================

- Add CLI flag --accept-orphan-nftban (cmd/nftban-installer/flags.go).
  Restore-mode only. CLI argv only — no env-var fallback per §55. Help
  text contains zero "force"/"override" tokens.
- Extend restore.Flags + restore.DecisionInput with:
  - AcceptOrphanNFTBan bool
  - Panel detect.PanelType
  - OrphanEvidence *OrphanEvidence
- New OrphanEvidence struct with 13 boolean rows + AllTrue() + FailedRowID().
- New decideAuthorityNFTBan in restore/engine.go: candidate-triple gate
  → §54 evidence predicate → PROCEED PanelNative/csf or REFUSE.
- New cmd/nftban-installer/restore_decide_evidence.go: read-only §54
  reader. Uses existing typed surfaces (FileExists, ServiceActive,
  NftTableExists). E.6 csf.service state uses raw Run("systemctl",
  "status"|"is-enabled","csf.service") per §43.3 (read-only probes
  authorized). NO mutating systemctl verbs. Zero new typed mutation
  surfaces.
- Dispatcher (restore_decide.go) gathers evidence ONLY when candidate
  triple is otherwise present, avoiding unnecessary live reads on every
  restore-mode invocation.

Tests
=====

- engine_amendment2_test.go: §56.1 unit fixtures (rows 01–20 + 7d
  acceptable-fallback variant), §56.2 regression (R1–R6), §56.4
  mutation-surface AST scan, FailedRowID per-row coverage.
- restore_decide_evidence_test.go: gatherOrphanEvidence per-row
  coverage (15 cases including E.6 sub-variants: active forbidden,
  not-found forbidden, enabled forbidden, static forbidden,
  disabled-acceptable). NFTBAN_ACCEPT_ORPHAN env-var-fallback
  source-scan invariant.
- engine_test.go: existing G1/AuthorityNFTBan fixture re-pinned to
  G1/AuthorityNFTBan/default; declaredRules now lists three sub-rule
  consts; two new allFixtures entries pin OrphanProceed and
  EvidenceMismatch.

CI gates (§56.3) implemented as in-process tests, NOT as GitHub
Actions edits — per operator direction. Source-scan tests in
engine_amendment2_test.go (force/override scan) and
restore_decide_evidence_test.go (env-var fallback scan).

Invariants preserved
====================

- §5 precedence: split is entirely within Group 1.
- INV-PR25-AUTHORITY-IMMUTABILITY: §54 evidence read once at decision
  time, never re-read.
- §19.2 layer 4 / main.go:132 history gate: untouched.
- §20.1 panel mapping: PROCEED resolves PanelNative/csf via the
  existing static map.
- §22 four terminals + §19.4 exit codes: unchanged.
- §32 11-step ordering: unchanged.
- §43.3 read-only Run policy: §54 E.6 uses status/is-enabled only.
- §51.3 Option B: zero iptables introspection added.
- INV-PR26-NEW-MUTATION-SURFACES-BOUNDED: zero new mutation surfaces.
- INV-AMD2-EXPLICIT-INTENT-IS-NARROW: §53.4 13 explicit-REFUSE rows
  test-pinned in §56.1.

Test results
============

- go test ./internal/installer/restore/...   PASS
- go test ./cmd/nftban-installer/...         PASS
- go test ./...                              64 packages PASS, 0 FAIL

Grep gates (scoped to Amendment 2 changed files)
================================================

- iptables-(save|restore|nft)              0 hits → PASS
- build[ -]set[ ]+csf                      0 hits → PASS
- WriteFileAtomic.*update-history|...      0 hits → PASS
- force|override in --accept-orphan-nftban 0 hits → PASS

Out of scope (deferred)
=======================

- §59 Q3/Q4 — typed read-only ServiceListed/ServiceEnabled/NftListTables
  not added; raw Run for E.6 + existing NftTableExists used instead.
- §59 Q5 — final --help text wording locked here; further refinement
  optional.
- amendment-2-code-E real-host srv3 destructive evidence — separate PR.

No srv3 action. No CI workflow edit. No §32 mutation path change. No
new state terminals. No new exit codes. No update-history writes.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: itcmsgr

cmd/nftban-installer/flags.go

@@ -58,6 +58,16 @@ type config struct {
 	// behind an explicit default-off flag. Operators that relied on the
 	// prior behaviour must now pass --panel-auto-takeover.
 	panelAutoTakeover bool // --panel-auto-takeover: allow panel presence to auto-approve takeover (default OFF)
+	// v1.100 Amendment 2: --accept-orphan-nftban — explicit operator
+	// intent for the narrow restore-from-orphan-NFTBan-on-DirectAdmin
+	// path (contract.md §52–61). MUST be CLI argv only — no env-var
+	// fallback, no config-file key, no implicit default. Activates the
+	// G1/AuthorityNFTBan split's orphan-intent candidate row only when
+	// combined with --panel-auto-takeover, Panel=DirectAdmin,
+	// Authority=AuthorityNFTBan, Prior=NoRecord, and ALL §54.1
+	// evidence rows true. Standalone or under any other classifier the
+	// flag has zero effect — REFUSE remains.
+	acceptOrphanNFTBan bool // --accept-orphan-nftban: explicit-intent CSF restore from orphan NFTBan on DirectAdmin (Amendment 2)
 	// v1.100 PR-23: --confirm-mutation replaces the PR-22 auto-elevate
 	// shim. --mode=uninstall now requires exactly one of:
 	//   --dry-run          (observational plan)
@@ -97,6 +107,10 @@ func parseFlags() *config {
 	flag.BoolVar(&cfg.restorePriorAuthority, "restore-prior-authority", false, "Restore pre-install external firewall authority. Requires recorded prior-authority record. Plan-only in PR-22.")
 	// v1.100 PR-22B: explicit panel-auto-takeover gate (see config field doc).
 	flag.BoolVar(&cfg.panelAutoTakeover, "panel-auto-takeover", false, "Allow control-panel presence to auto-approve takeover of conflicting firewalls. Default OFF. Set explicitly to preserve pre-PR-22B behaviour.")
+	// v1.100 Amendment 2: --accept-orphan-nftban — explicit-intent
+	// orphan restore. CLI argv only; no env mirror; help text MUST NOT
+	// include "force" or "override" (Amendment 2 §55).
+	flag.BoolVar(&cfg.acceptOrphanNFTBan, "accept-orphan-nftban", false, "Explicit-intent CSF restore on a DirectAdmin host where NFTBan is the current authority and no prior-authority record exists. Requires --mode=restore AND --panel-auto-takeover AND DirectAdmin AND on-disk evidence that NFTBan previously took over from CSF. Without all preconditions the restore refuses (Amendment 2).")
 	// v1.100 PR-23: --confirm-mutation — explicit uninstall mutation entry.
 	flag.BoolVar(&cfg.confirmMutation, "confirm-mutation", false, "Authorize uninstall authority release (real kernel + service mutation). Required for --mode=uninstall without --dry-run. Mutually exclusive with --dry-run.")
 
@@ -161,6 +175,11 @@ func parseFlags() *config {
 				fmt.Fprintln(os.Stderr, "       --mode=restore invokes the PR-24 decision engine; it performs NO mutation.")
 				os.Exit(state.ExitFatal)
 			}
+			// Amendment 2 §55 — `--accept-orphan-nftban` is a
+			// restore-mode-only flag. Reject early in any other mode.
+			// (`cfg.mode == "restore"` here, but ANY mode other than
+			// restore that received the flag must refuse before the
+			// fall-through return below.)
 			if cfg.dryRun {
 				fmt.Fprintln(os.Stderr, "error: --dry-run is not valid with --mode=restore")
 				fmt.Fprintln(os.Stderr, "       --mode=restore is ALWAYS pure policy decision — no mutation path exists.")
@@ -270,6 +289,14 @@ func parseFlags() *config {
 		os.Exit(state.ExitFatal)
 	}
 
+	// Amendment 2 §55: --accept-orphan-nftban is restore-mode only.
+	// Reject explicitly so operators don't get a silent no-op in
+	// install / upgrade / uninstall.
+	if cfg.acceptOrphanNFTBan && cfg.mode != "restore" {
+		fmt.Fprintln(os.Stderr, "error: --accept-orphan-nftban is only valid with --mode=restore")
+		os.Exit(state.ExitFatal)
+	}
+
 	// --source is mutually exclusive with packaging-origin flags.
 	if cfg.source && (cfg.rpm || cfg.deb) {
 		fmt.Fprintln(os.Stderr, "error: --source cannot be combined with --rpm or --deb")

cmd/nftban-installer/restore_decide.go

@@ -128,10 +128,28 @@ func runRestoreDecide(ctx context.Context, exec executor.Executor, sf *state.Sta
 		Ambiguity: auth.Ambiguity,
 		Prior:     priorState,
 		Flags: restore.Flags{
-			Restore:           cfg.restorePriorAuthority,
-			PanelAutoTakeover: cfg.panelAutoTakeover,
+			Restore:            cfg.restorePriorAuthority,
+			PanelAutoTakeover:  cfg.panelAutoTakeover,
+			AcceptOrphanNFTBan: cfg.acceptOrphanNFTBan,
 		},
 		PanelPresent: panelPresent,
+		Panel:        panel,
+	}
+
+	// 6b. Amendment 2 §54.3: gather orphan-restore evidence ONLY when
+	// the candidate triple is otherwise present. This avoids
+	// unnecessary live reads on every restore-mode invocation, and
+	// preserves the §51.3 Option B boundary (no iptables introspection)
+	// by only running the predicate where it matters.
+	if auth.State == uninstall.AuthorityNFTBan &&
+		priorState == restore.PriorStateNoRecord &&
+		panel == detect.PanelDirectAdmin &&
+		cfg.panelAutoTakeover &&
+		cfg.acceptOrphanNFTBan {
+		ev := gatherOrphanEvidence(exec, log, panel, auth, probe, cfg)
+		input.OrphanEvidence = &ev
+		log.Info("restore decide: orphan-evidence gathered all_true=%v failed_row=%q",
+			ev.AllTrue(), ev.FailedRowID())
 	}
 
 	// 7. Evaluate — pure, deterministic, no side effects.

cmd/nftban-installer/restore_decide_evidence.go

@@ -0,0 +1,160 @@
+// =============================================================================
+// NFTBan v1.100 Amendment 2 — Orphan-NFTBan restore evidence reader
+// =============================================================================
+// SPDX-License-Identifier: MPL-2.0
+// meta:name="nftban-installer-restore-decide-evidence"
+// meta:type="cmd"
+// meta:owner="Antonios Voulvoulis <contact@nftban.com>"
+// meta:created_date="2026-04-28"
+// meta:description="§54.1 read-only evidence predicate for the G1 orphan-intent split"
+// meta:inventory.files="cmd/nftban-installer/restore_decide_evidence.go"
+// meta:inventory.binaries=""
+// meta:inventory.env_vars=""
+// meta:inventory.config_files=""
+// meta:inventory.systemd_units=""
+// meta:inventory.network=""
+// meta:inventory.privileges="root"
+// =============================================================================
+//
+// Amendment 2 (contract.md §§52–61) defines a 13-row evidence predicate
+// (§54.1) that gates the G1/AuthorityNFTBan/OrphanProceed sub-rule. This
+// file implements the predicate as a pure read-only reader against the
+// live host state.
+//
+// Discipline:
+//   - Read-only only. NO mutating systemctl verbs (start/stop/enable/
+//     disable/mask/unmask/restart/daemon-reload). NO file writes. NO
+//     nft mutation. NO iptables introspection (preserves §51.3 Option B).
+//   - Read failures map to false on the failing row, NOT to
+//     REQUIRE_EXPLICIT_INTENT (§54.2 final bullet).
+//   - Caller (`runRestoreDecide`) invokes this only when the candidate
+//     triple is present, to avoid unnecessary live reads.
+//
+// =============================================================================
+package main
+
+import (
+	"strings"
+
+	"github.com/itcmsgr/nftban/internal/installer/detect"
+	"github.com/itcmsgr/nftban/internal/installer/executor"
+	"github.com/itcmsgr/nftban/internal/installer/logging"
+	"github.com/itcmsgr/nftban/internal/installer/restore"
+	"github.com/itcmsgr/nftban/internal/installer/uninstall"
+)
+
+const (
+	csfServiceUnitForEvidence = "csf.service"
+	nftbandServiceUnit        = "nftband.service"
+	csfBinaryPath             = "/usr/sbin/csf"
+	csfDisabledBinaryPath     = "/usr/sbin/csf.disabled"
+)
+
+// gatherOrphanEvidence reads the 13 §54.1 rows from the live host
+// using only read-only executor surfaces. Returns a populated
+// restore.OrphanEvidence struct; AllTrue() reports whether every row
+// holds.
+//
+// Rows E.1, E.2, E.3, E.4, E.5 are derived from inputs the dispatcher
+// already gathered (`detect.DetectPanel`, `uninstall.Classify`,
+// `uninstall.Probe`, CLI flags). Rows E.6–E.13 are read from the
+// kernel/service/file surfaces.
+func gatherOrphanEvidence(
+	exec executor.Executor,
+	log *logging.Logger,
+	panel detect.PanelType,
+	auth *uninstall.ClassifyResult,
+	probe *uninstall.ProbeResult,
+	cfg *config,
+) restore.OrphanEvidence {
+	ev := restore.OrphanEvidence{}
+
+	// E.1 panel = DirectAdmin
+	ev.E1PanelDirectAdmin = panel == detect.PanelDirectAdmin
+
+	// E.2 authority = AuthorityNFTBan
+	ev.E2AuthorityNFTBan = auth.State == uninstall.AuthorityNFTBan
+
+	// E.3 prior = NoRecord
+	ev.E3PriorNoRecord = probe.State == uninstall.PriorNoRecord
+
+	// E.4 --panel-auto-takeover present
+	ev.E4PanelAutoTakeover = cfg.panelAutoTakeover
+
+	// E.5 --accept-orphan-nftban present (CLI argv only — env-var
+	// fallback is rejected at flag-parse time per §55).
+	ev.E5AcceptOrphanNFTBan = cfg.acceptOrphanNFTBan
+
+	// E.6 csf.service exists AND not active AND is-enabled in {masked, disabled}.
+	// Three sub-checks. Any failure → E6 false.
+	ev.E6CSFServiceDisabled = csfServiceIsDisabledOrMasked(exec, log)
+
+	// E.7 /usr/sbin/csf.disabled exists
+	ev.E7CSFDisabledExists = exec.FileExists(csfDisabledBinaryPath)
+
+	// E.8 /usr/sbin/csf does NOT exist
+	ev.E8CSFAbsent = !exec.FileExists(csfBinaryPath)
+
+	// E.9 ip:nftban table present
+	ev.E9NftIPNftbanPresent = exec.NftTableExists("ip", "nftban")
+
+	// E.10 ip6:nftban table present
+	ev.E10NftIP6NftbanPres = exec.NftTableExists("ip6", "nftban")
+
+	// E.11 nftband.service active
+	ev.E11NftbandActive = exec.ServiceActive(nftbandServiceUnit)
+
+	// E.12 no AuthorityExternal / no AmbiguityConflictExternal.
+	// Classifier output already established AuthorityNFTBan (caller),
+	// so this is implicit; recorded explicitly per §54.1 to avoid
+	// inferential gaps.
+	ev.E12NoConflictExternal = auth.State != uninstall.AuthorityExternal &&
+		auth.Ambiguity != uninstall.AmbiguityConflictExternal
+
+	// E.13 no Ambiguous classification
+	ev.E13NoAmbiguous = auth.State != uninstall.AuthorityAmbiguous
+
+	return ev
+}
+
+// csfServiceIsDisabledOrMasked returns true iff csf.service:
+//   - exists (systemctl status is parseable, not "could not be found")
+//   - is NOT active (is-active returns "inactive" or "failed")
+//   - is-enabled is one of {"masked", "disabled"}; "enabled" or
+//     "static" or anything else returns false.
+//
+// Routes through the executor's Run abstraction for read-only
+// systemctl probes (§43.3 — raw Run permitted in restore deps for
+// read-only probes only). NO mutating systemctl verb is invoked.
+func csfServiceIsDisabledOrMasked(exec executor.Executor, log *logging.Logger) bool {
+	// Sub-check 1: existence via `systemctl status csf.service`.
+	statusRes := exec.Run("systemctl", "status", "--no-pager", "--lines=0", csfServiceUnitForEvidence)
+	combined := statusRes.Stdout + statusRes.Stderr
+	if strings.Contains(combined, "could not be found") || strings.Contains(combined, "not-found") {
+		log.Info("amd2-evidence: E.6 csf.service not present on host")
+		return false
+	}
+
+	// Sub-check 2: must NOT be active. Use the typed read-only seam.
+	if exec.ServiceActive(csfServiceUnitForEvidence) {
+		log.Info("amd2-evidence: E.6 csf.service is active — orphan precondition violated")
+		return false
+	}
+
+	// Sub-check 3: is-enabled must be in {masked, disabled}. Reject
+	// {enabled, static, anything else}. Forbidden values:
+	//   - "enabled"  — csf would return at next boot
+	//   - "static"   — csf has no install dependency relations; would
+	//                  re-arm via Wants= at boot
+	enabledRes := exec.Run("systemctl", "is-enabled", csfServiceUnitForEvidence)
+	enabledState := strings.TrimSpace(enabledRes.Stdout)
+	switch enabledState {
+	case "masked", "disabled":
+		// Acceptable. (masked = strongest, matches install-time
+		// switchop.DisableConflicts; disabled = acceptable fallback.)
+		return true
+	default:
+		log.Info("amd2-evidence: E.6 csf.service is-enabled=%q (forbidden; want masked or disabled)", enabledState)
+		return false
+	}
+}

cmd/nftban-installer/restore_decide_evidence_helper_test.go

@@ -0,0 +1,26 @@
+// =============================================================================
+// NFTBan v1.100 Amendment 2 — Test helper: read source files for invariants
+// =============================================================================
+// SPDX-License-Identifier: MPL-2.0
+// meta:name="nftban-installer-restore-decide-evidence-test-helper"
+// meta:type="test"
+// meta:owner="Antonios Voulvoulis <contact@nftban.com>"
+// meta:created_date="2026-04-28"
+// meta:description="Filesystem reader for source-scan invariants (§56.3 / §56.4)"
+// meta:inventory.files="cmd/nftban-installer/restore_decide_evidence_test_helper.go"
+// meta:inventory.binaries=""
+// meta:inventory.env_vars=""
+// meta:inventory.config_files=""
+// meta:inventory.systemd_units=""
+// meta:inventory.network=""
+// meta:inventory.privileges="none"
+// =============================================================================
+package main
+
+import "os"
+
+// readFileImpl reads a file path relative to the test working
+// directory. Used by the Amendment 2 source-scan invariant tests.
+func readFileImpl(path string) ([]byte, error) {
+	return os.ReadFile(path)
+}