restore

type DecisionInput struct {
	// Authority is the classifier state. Taken verbatim from
	// uninstall.ClassifyResult.State; AmbiguityKind is carried in the
	// dedicated field below so the engine does not have to re-import
	// or re-derive sub-classification.
	Authority uninstall.CurrentAuthority

	// Ambiguity is the sub-classification of AuthorityAmbiguous.
	// MUST be uninstall.AmbiguityNone for any Authority !=
	// AuthorityAmbiguous. Violations are treated as a preflight
	// invariant error in the dispatcher, not a lattice output.
	Ambiguity uninstall.AmbiguityKind

	// Prior is the normalized prior-record state (see PriorState).
	Prior PriorState

	// Flags captures operator intent.
	Flags Flags

	// PanelPresent is a single boolean rather than the raw panel type.
	// The lattice treats panel context as "panel or no panel"; any
	// specific panel (DA / cPanel / Plesk / Hestia / etc.) is
	// equivalent for policy purposes for §6 Groups 1–5.
	PanelPresent bool

	// Panel is the typed panel identity. Required by Amendment 2 §54
	// evidence row E.1 (the orphan-intent PROCEED path activates only
	// for Panel == detect.PanelDirectAdmin). Outside the Amendment 2
	// G1/AuthorityNFTBan split, the lattice ignores this field —
	// PanelPresent remains the sole panel input for §6 Groups 3 and 4.
	Panel detect.PanelType

	// OrphanEvidence carries the §54.1 read-only evidence predicate
	// result, populated by the dispatcher only when the candidate
	// triple (AuthorityNFTBan + Prior=NoRecord + Panel=DirectAdmin +
	// Flags.PanelAutoTakeover + Flags.AcceptOrphanNFTBan) is present.
	// Nil for every other input pattern — the engine MUST NOT
	// dereference it outside the Amendment 2 split.
	//
	// For the Amendment 3 path (G1/AmbiguityConflictExternal split,
	// §62-§69), the same OrphanEvidence struct is reused with
	// AllTrueAmendment3() / FailedRowIDAmendment3() — they evaluate
	// the same rows EXCEPT E.12 (omitted because AmbiguityConflictExternal
	// is the §62 entry condition, incompatible with E.12 by construction).
	// E.2 is reframed semantically by the dispatcher (the row-bool now
	// represents AuthorityAmbiguous + AmbiguityConflictExternal +
	// external=csf rather than AuthorityNFTBan); the predicate
	// implementation remains shared.
	OrphanEvidence *OrphanEvidence

	// ExternalIndicator is the classifier's external-authority string
	// (e.g. "csf", "ufw", "firewalld"; "csf,ufw" for multi-external;
	// empty when classifier did not flag a conflict). Required for the
	// Amendment 3 §62 entry condition: the orphan-intent-candidate-csf
	// sub-row activates only when ExternalIndicator == "csf" (single,
	// case-sensitive). For every other lattice path, this field is
	// ignored. Multi-external strings (e.g. "csf,ufw") and empty strings
	// fall through to G1/AmbiguityConflictExternal/default REFUSE per
	// §65 (multi-external out of scope) and §67 row AMD3-13 (empty-external
	// defensive guard).
	ExternalIndicator string
}

type DecisionResult struct {
	// Output is one of OutputProceed / OutputRefuse /
	// OutputRequireExplicitIntent. No fourth value.
	Output Output

	// Rule identifies the lattice rule that matched. The string is
	// stable (contract-level); tests and CI gates assert on it. Format:
	// "G{group}.{subgroup}/{flag-or-condition}", e.g. "G1/AuthorityNFTBan",
	// "G3.3/NoRecord+Restore", "G4.3/PanelAutoOnOrphan". See engine.go
	// for the canonical list.
	Rule string

	// Reason is a short human-readable explanation of the output. Not
	// contract-stable; kept for operator-facing output and logging.
	Reason string
}

type ExecuteDeps struct {
	Preflight    PreflightDep
	SafetyNet    SafetyNetDep
	Mutation     MutationDep
	InlineVerify InlineVerifyDep
}

type ExecuteResult struct {
	// Terminal is the §22 terminal state the caller should record.
	// One of:
	//   StateRestoreExecuted              — full success
	//   StateRestoreFailedExecution       — preflight refusal,
	//                                       insert failure, mutate
	//                                       failure
	//   StateRestoreFailedVerification    — inline verification
	//                                       failed (assertion or dep
	//                                       error); safety net retained
	// StateRestoreDegraded is NOT returned by this commit; per the
	// locked plan, it is used only if the contract defines a
	// degraded-but-executed condition, and no such condition is
	// implemented in commit 3C. Adding it requires a contract
	// amendment.
	Terminal state.InstallState

	// Stage names the §23 step that produced the terminal state.
	// Useful for logging and ordering tests. Values are constants
	// declared below (StagePreflight, StageInsert, StageMutate,
	// StageVerify, StageRemove, StageComplete).
	Stage string

	// Err is non-nil when a dep call returned an error or an input
	// invariant was violated. nil on the success path.
	Err error

	// VerifyResult is captured when verification ran (Stage ==
	// StageVerify or later). Empty otherwise.
	VerifyResult VerifyResult
}

type Flags struct {
	// Restore corresponds to --restore-prior-authority in the CLI
	// surface. Semantic: "restore the recorded prior firewall."
	Restore bool
	// PanelAutoTakeover corresponds to --panel-auto-takeover.
	// Semantic: "install the panel-native firewall." Target is the
	// panel, not the prior record — this asymmetry is the policy
	// hinge in seed §3.3 / §4.2.
	PanelAutoTakeover bool
	// AcceptOrphanNFTBan corresponds to --accept-orphan-nftban
	// (Amendment 2, locked 2026-04-28). Semantic: "explicit operator
	// intent to restore CSF on a DirectAdmin host where NFTBan is the
	// current authority and no prior-authority record exists." Combined
	// with PanelAutoTakeover + DirectAdmin + strong CSF-disabled
	// evidence, this activates the §53 G1 split orphan-intent path.
	// Standalone (without PanelAutoTakeover, or under any other
	// classifier) the flag has no effect — REFUSE remains.
	//
	// MUST be supplied via CLI argv only. No env-var, no config-file,
	// no implicit default — see Amendment 2 §55.
	AcceptOrphanNFTBan bool
}

type InlineVerifyDep interface {
	// IsTargetFirewallActive reports whether the panel-auto-mapped or
	// recorded-prior firewallType is currently active on the host.
	// firewallType is one of the §18.2 known values
	// ({ufw, firewalld, iptables, csf}); callers MUST NOT pass any
	// other value. Returns (active, err).
	//
	// Active means: the firewall's runtime presence is observable
	// (e.g. service running, kernel rules loaded). The exact
	// observability mechanism is the production implementation's
	// concern; it is NOT defined here.
	IsTargetFirewallActive(ctx context.Context, firewallType string) (bool, error)

	// CurrentAuthorityClass returns the host's current authority
	// class as classified after the PR-25 mutation has completed.
	// Returns the same uninstall.CurrentAuthority enum that PR-22 /
	// PR-23 / PR-24 use, so callers can compare the post-mutation
	// classification against an expected value.
	//
	// This MUST reflect a fresh classification, but the *call* is
	// allowed to be expensive — production implementations may
	// shell out. It is NOT a hot-path primitive.
	CurrentAuthorityClass(ctx context.Context) (uninstall.CurrentAuthority, error)

	// IsSafetyNetRemovalSafe reports whether removing the
	// emergency-SSH safety net at this moment is safe. Production
	// implementations must check, at minimum, that:
	//
	//   - SSH connectivity remains observable on the post-mutation
	//     ruleset, OR
	//   - an equivalent operator-recovery path exists that does not
	//     depend on the safety-net rule.
	//
	// The exact predicate is the production implementation's concern.
	// This primitive only carries the boolean result.
	IsSafetyNetRemovalSafe(ctx context.Context) (bool, error)
}

type MutationDep interface {
	// MutateToTarget performs the kernel + run-state mutation
	// required to make firewallType the authoritative firewall.
	// Returns nil on success, non-nil error on any failure.
	// Implementations MUST leave the safety net (inserted by Execute
	// step 2 prior to this call) in place even on failure — Execute
	// chooses the terminal state and decides safety-net handling.
	MutateToTarget(ctx context.Context, firewallType string) error
}

type OrphanEvidence struct {
	E1PanelDirectAdmin    bool // detect.DetectPanel == PanelDirectAdmin
	E2AuthorityNFTBan     bool // uninstall.Classify == AuthorityNFTBan
	E3PriorNoRecord       bool // uninstall.Probe == PriorNoRecord
	E4PanelAutoTakeover   bool // --panel-auto-takeover present
	E5AcceptOrphanNFTBan  bool // --accept-orphan-nftban present (CLI argv only)
	E6CSFServiceDisabled  bool // csf.service exists AND not active AND is-enabled in {masked, disabled}
	E7CSFDisabledExists   bool // /usr/sbin/csf.disabled exists
	E8CSFAbsent           bool // /usr/sbin/csf does NOT exist
	E9NftIPNftbanPresent  bool // nft table ip nftban present
	E10NftIP6NftbanPres   bool // nft table ip6 nftban present
	E11NftbandActive      bool // nftband.service active
	E12NoConflictExternal bool // classifier did not return AmbiguityConflictExternal
	E13NoAmbiguous        bool // classifier did not return AuthorityAmbiguous
}

type Output string

type PreflightDep interface {
	// PreflightTarget reports whether the resolved firewallType is
	// still a valid execution target right now. Returns nil error +
	// true on go. Returns nil error + false on logical refusal.
	// Returns non-nil error on dep failure (treated as a hard
	// refusal: §23.1 refusal must be non-mutating).
	PreflightTarget(ctx context.Context, firewallType string) (bool, error)
}

type PriorState string

type SafetyNetDep interface {
	// InsertEmergencySSH inserts the single emergency-SSH allow rule.
	// It MUST NOT perform any other firewall edit. Returns an error
	// describing the failure on any non-success outcome.
	InsertEmergencySSH(ctx context.Context) error

	// RemoveEmergencySSH removes the previously-inserted rule.
	// It MUST NOT perform any other firewall edit. It MUST NOT
	// re-flush, rebuild, or otherwise touch unrelated rules. Returns
	// an error describing the failure on any non-success outcome.
	RemoveEmergencySSH(ctx context.Context) error
}

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

type TargetAuthorityKind string

type VerifyResult struct {
	TargetFirewallActive  bool
	AuthorityClassCorrect bool
	SafetyNetRemovalSafe  bool

	// SafeToRemove is true ONLY when all three assertions are true
	// AND no dep error occurred. It is the §21.3 gate value the
	// caller passes to RemoveSafetyNet.
	SafeToRemove bool

	// ObservedAuthority is the value returned by
	// dep.CurrentAuthorityClass — included in the result for caller
	// logging and terminal-state selection (commit 3C). Empty on
	// dep-error path.
	ObservedAuthority uninstall.CurrentAuthority

	// Err is non-nil only when a dep call returned an error.
	// Verification logical-FAIL (one or more assertions returning
	// false) does NOT produce an Err — it produces SafeToRemove=false.
	Err error
}