update

type ApplyForbiddenSubstring struct {
	Pattern string
	Why     string
}

type ApplyForbiddenWritePath struct {
	Prefix string
	Why    string
}

type Plan struct {
	// SchemaVersion locks the on-wire contract. Bump on any breaking change.
	SchemaVersion string `json:"schema_version"`

	// CurrentVersion is the version currently installed on the host,
	// read from /usr/lib/nftban/VERSION (or the canonical lookup chain
	// documented in cli/lib/nftban/lib/version.sh).
	CurrentVersion string `json:"current_version"`

	// TargetVersion is the version that would be installed if apply ran.
	// For source installs this is the VERSION file in the source tree;
	// for package installs this is the package's Version field.
	TargetVersion string `json:"target_version"`

	// InstallOrigin is "rpm", "deb", or "source" — determines which apply
	// path would execute in PR-18.
	InstallOrigin string `json:"install_origin"`

	// NeedsUpdate is true when CurrentVersion != TargetVersion. False means
	// a run would be a bounded no-op per G3-U16 (idempotency).
	NeedsUpdate bool `json:"needs_update"`

	// Preflight records the preflight result that was folded into this plan.
	Preflight *PreflightResult `json:"preflight"`

	// Warnings are non-fatal notes the operator should see (e.g. "current
	// state is DEGRADED — update will proceed with caution").
	Warnings []string `json:"warnings,omitempty"`

	// Actions is a human-oriented list of what apply would do. PR-16 keeps
	// this abstract ("reuse rebuild pipeline"); PR-18 fills in concrete
	// steps.
	Actions []string `json:"actions,omitempty"`

	// Recovery carries planning-only metadata about the rollback route that
	// PR-18's apply step will rely on. PR-17 populates this but does NOT
	// execute any recovery — that's PR-18 scope per INV-U-002.
	Recovery *RecoveryPlan `json:"recovery,omitempty"`
}

type PreflightCheck struct {
	Name   string `json:"name"`
	Passed bool   `json:"passed"`
	Detail string `json:"detail,omitempty"`
	// Severity is "critical" (abort) or "warning" (continue with warning).
	// Only "critical" failures contribute to Passed=false at the result level.
	Severity string `json:"severity"`
}

type PreflightResult struct {
	Passed bool             `json:"passed"`
	Checks []PreflightCheck `json:"checks"`
}

type RecoveryPlan struct {
	// Available reports whether a rollback to the prior known-good state
	// is possible without operator intervention.
	Available bool `json:"available"`

	// Mechanism is the rollback mechanism that would be used — currently
	// "rebuild" (validate-in-namespace + flush+load + v1.96 recovery), the
	// only canonized recovery surface today.
	Mechanism string `json:"mechanism"`

	// Notes carries human-oriented context that helps an operator reason
	// about recovery without digging into code (e.g. "prior state file
	// present and terminal", "no prior install_state — fresh recovery").
	Notes []string `json:"notes,omitempty"`
}