state

const (
	StateFilesInstalled   InstallState = "FILES_INSTALLED"
	StateDetectComplete   InstallState = "DETECT_COMPLETE"
	StatePrepareComplete  InstallState = "PREPARE_COMPLETE"
	StateSwitchComplete   InstallState = "SWITCH_COMPLETE"
	StateServicesComplete InstallState = "SERVICES_COMPLETE"
	// StateCommitted is the ONLY install-class state that means "this transaction
	// succeeded". ⛔ See the OWNER RULING at the top of this file before making any
	// rebuild disposition — DEFERRED_RUNTIME above all — sufficient for it.
	StateCommitted        InstallState = "COMMITTED"
	StateDegraded         InstallState = "DEGRADED"
	StateFailedSSH        InstallState = "FAILED_SSH_UNKNOWN"
	StateFailedAbort      InstallState = "FAILED_AUTHORITY_ABORT"
	StateFailedRender     InstallState = "FAILED_RENDER"
	StateFailedRebuild    InstallState = "FAILED_REBUILD"
	StateFailedNoFirewall InstallState = "FAILED_NO_FIREWALL"
	StateFailedTakeover   InstallState = "FAILED_TAKEOVER"

	// StateRebuildRefusedBusy — every rebuild attempt inside the installer's
	// deadline was REFUSED because another nft operation held the convergence
	// lock. Established from the shell's REFUSED result contract, never from
	// stderr text and never from an exit code.
	StateRebuildRefusedBusy InstallState = "REBUILD_REFUSED_BUSY"

	// StateRebuildNotExecuted — no result contract AND no execution witness.
	// The root-cause guard for a missing record: "no record" means one of two
	// opposite things, and this state is the one where execution was NOT
	// established. When the witness DOES prove execution, a missing record
	// stays FAILED_REBUILD and stays fatal.
	StateRebuildNotExecuted InstallState = "REBUILD_NOT_EXECUTED"

	// StateFailedPreflightDiskSpace (V125 R-5) is the terminal failure
	// produced when the disk-space preflight at the end of phaseDetect
	// determines that the state-dir's filesystem has insufficient free
	// space to proceed safely (default threshold 500 MB; operator-tunable
	// via NFTBAN_MIN_DISK_FREE_MB). Refusing here is strictly safer than
	// proceeding into phasePrepare's dnf/apt installs + file writes,
	// which would ENOSPC mid-install and leave the host in an
	// inconsistent state.
	//
	// IsApplyTerminal=true (an apply was attempted and a definitive
	// outcome was reached). IsFailed=true (apply did not succeed).
	// ExitCode falls through to ExitFailed via the default branch,
	// matching the pattern of the other StateFailed* values.
	// ResumePhase falls through to PhaseDetect via the default branch —
	// after the operator frees disk space, --repair re-runs from
	// detection (which includes the preflight, so a still-low-disk
	// host correctly re-refuses).
	StateFailedPreflightDiskSpace InstallState = "FAILED_PREFLIGHT_DISK_SPACE"

	// StateUninstallPlanning is the terminal state for v1.100 PR-22's
	// detect + dry-run plan orchestrator. The planner reaches this
	// state after classifying current authority, probing the optional
	// prior-authority record, and rendering the release plan — without
	// invoking any mutation phase. Later v1.100 PRs (PR-23/25) add the
	// mutation-carrying uninstall states; PR-22 deliberately ships only
	// the planning state so the scope-boundary block in plan output
	// remains literally true: no phase beyond Planning exists yet.
	StateUninstallPlanning InstallState = "UNINSTALL_PLANNING"

	// StateUninstallReleased is the terminal success state for v1.100
	// PR-23's uninstall mutation (authority release core). Reached
	// after:
	//   - kernel nftban tables flushed + deleted
	//   - nftband.service stopped, disabled, masked
	//   - end-state validation passed (no nftban authority remaining)
	//   - emergency SSH table cleanly removed
	//
	// IsApplyTerminal() returns true for this state so downstream
	// lifecycle consumers see it as a completed apply outcome.
	// ExitCode() maps to ExitCommitted (0) — the operator asked for
	// uninstall and got it. However, the uninstall-history
	// representation is intentionally SKIPPED for this state in PR-23
	// (Option A locked 2026-04-20): update-history.json cannot
	// truthfully represent uninstall success under its install-centric
	// schema, and the separate-schema work is explicitly deferred to a
	// later PR. writeHistory is gated on cfg.mode != "uninstall" in
	// main.go, so this state does NOT produce a history entry.
	StateUninstallReleased InstallState = "UNINSTALL_RELEASED"

	// StateUninstallFailedRelease is the terminal failure state for
	// PR-23 when mutation started but did not complete cleanly. The
	// emergency SSH table may still be present (over-permissive SSH
	// is the deliberate fallback — losing SSH on a failure is a worse
	// outcome than a temporary permissive rule). Operator must
	// investigate kernel + service state and either retry or manually
	// resolve. IsApplyTerminal() returns true; ExitCode() maps to
	// ExitFailed (2).
	StateUninstallFailedRelease InstallState = "UNINSTALL_FAILED_RELEASE"

	// PR-24 authority restoration policy-engine states.
	//
	// These are produced ONLY by the pure decision engine in
	// internal/installer/restore. The engine performs no kernel,
	// service, or filesystem mutation; these states therefore represent
	// a policy outcome, not an apply outcome.
	//
	// StateRestoreRefused is the terminal state produced when the
	// lattice returns REFUSE. It is terminal, NOT failed (refusal is
	// not failure — it is a correct policy outcome), and deliberately
	// excluded from IsApplyTerminal so it does not flow through
	// update-history.json under the install-centric schema. ExitCode()
	// returns ExitRefused (5).
	StateRestoreRefused InstallState = "RESTORE_REFUSED"

	// StateRestoreIntentRequired is the terminal state produced when
	// the lattice returns REQUIRE_EXPLICIT_INTENT. Same discipline as
	// StateRestoreRefused: terminal, not failed, not apply-terminal,
	// not recorded in history. ExitCode() returns ExitIntentRequired
	// (6), distinct from refusal so operators and automation can tell
	// "engine said no" from "engine needs you to clarify".
	StateRestoreIntentRequired InstallState = "RESTORE_INTENT_REQUIRED"

	// StateRestoreDecided is the NON-TERMINAL policy-handoff marker
	// produced when the lattice returns PROCEED. Locked semantics per
	// contract seed §7 (merged as PR #493):
	//
	//   1. Policy-only: records that the decision engine said PROCEED.
	//   2. Non-terminal for apply semantics: IsApplyTerminal() and
	//      IsTerminal() both return false.
	//   3. Excluded from update-history.json: Option A discipline
	//      continues; main.go already gates history on cfg.mode !=
	//      "uninstall" AND state.IsApplyTerminal(). This state will
	//      eventually gain its own mode-guard if --mode=restore ever
	//      writes history; for now, IsApplyTerminal=false closes the
	//      write path defensively.
	//   4. Not evidence that restoration happened: no kernel, service,
	//      or filesystem change is implied. PR-25+ execution would
	//      change state further; in PR-24, PROCEED is a handoff
	//      outcome only.
	//
	// ExitCode() returns ExitCommitted (0) — the operator got the
	// decision they asked for, and the process exit code reflects
	// decision success, not execution success.
	StateRestoreDecided InstallState = "RESTORE_DECIDED"

	// StateRestoreExecuted is the full-success terminal: mutation
	// completed, inline verification (§21.1) passed, safety net was
	// removed. Operator's authorized restore is in effect.
	StateRestoreExecuted InstallState = "RESTORE_EXECUTED"

	// StateRestoreFailedExecution is the mid-flight failure terminal:
	// mutation failed before completion. Safety net is still present;
	// system is rolled to the known-safe state. Explicit operator
	// inspection required before any further mutation.
	StateRestoreFailedExecution InstallState = "RESTORE_FAILED_EXECUTION"

	// StateRestoreDegraded is the soft-fail-after-mutation terminal:
	// mutation completed, inline verification flagged a soft-fail
	// condition, safety net was removed under explicit policy. The
	// authorized restore is in effect but warrants operator follow-up.
	StateRestoreDegraded InstallState = "RESTORE_DEGRADED"

	// StateRestoreFailedVerification is the hard-fail-after-mutation
	// terminal: mutation completed but inline verification (§21.1)
	// hard-failed. Safety net is RETAINED (contract §21.3). Explicit
	// operator action required.
	StateRestoreFailedVerification InstallState = "RESTORE_FAILED_VERIFICATION"
)

const (
	PhaseDetect    Phase = "DETECT"
	PhasePrepare   Phase = "PREPARE"
	PhaseSwitch    Phase = "SWITCH"
	PhaseConfigure Phase = "CONFIGURE"
	PhaseValidate  Phase = "VALIDATE"
	PhaseReport    Phase = "REPORT"
)

const (
	// RecoveryRepair — `nftban-installer --repair` has a DEMONSTRATED route to
	// COMMITTED from this state.
	RecoveryRepair RecoveryClass = "REPAIR"

	// RecoveryRetryFullTransaction — --repair must NOT be advertised. The operator
	// must re-run the normal NFTBan update/install transaction.
	//
	// ⛔ WORDED BY OPERATION, NEVER BY PACKAGE MANAGER. The live proof is RPM-only and
	// the originating incident host is dpkg; encoding `rpm -Uvh --force` (or any
	// specific command) into the contract would be wrong on half the fleet. A concrete
	// command may only ever be an ADDITIONAL HINT, and only where the originating
	// package manager is RELIABLY known.
	RecoveryRetryFullTransaction RecoveryClass = "RETRY_FULL_TRANSACTION"
)