feat(v1.100 PR-P2-1): prior-authority record hardening — 5-state classification + required RecordedAt/InstallerVersion/ActiveAtInstall (#484)

Pre-PR-23 blocker #1. Strengthens prior-authority records so PR-24
restore-enforcement can rely on them without inheriting weak semantics.

**Scope-locked per repair contract:**
- schema additions (recorded_at, installer_version, *bool active_at_install)
- 5-state classification (NoRecord / Malformed / Incomplete /
  UsableActive / UsableInactive)
- backward-safe degradation of old weak records to Incomplete
- render/JSON symmetry — PriorActiveAtInstall field + render line
- tests + contract/doc updates only
- NO restore execution, NO lifecycle mutation, NO signature/checksum
  framework, NO unrelated refactors

## Schema additions (prior.go)

```go
type PriorRecord struct {
    SchemaVersion    string
    FirewallType     string
    RecordedAt       *time.Time  // NEW — required for usable
    InstallerVersion string      // NEW — required for usable
    ActiveAtInstall  *bool       // CHANGED from bool — tri-state:
                                 //   nil   = record writer did not commit
                                 //   &true = prior was active
                                 //   &false = prior was explicitly inactive
}
```

## 5-state classification

| State | Condition |
|---|---|
| NoRecord | no artifact on disk |
| RecordMalformed | JSON does not parse (was folded into Incomplete before) |
| RecordIncomplete | parses but required field missing/invalid |
| RecordUsableActive | all required + ActiveAtInstall=&true |
| RecordUsableInactive | all required + ActiveAtInstall=&false |

`PriorRecordState.IsUsable()` helper returns true for both Usable*
variants — RestoreAuthorized uses it.

`IncompleteReason` enum provides machine-consumable reason codes:
Unreadable, SchemaMismatch, MissingFirewallType, UnknownFirewallType,
MissingRecordedAt, MissingInstallerVersion, MissingActiveAtInstall.

## Backward-safety

Older records from before PR-P2-1 that lack recorded_at /
installer_version / explicit active_at_install are intentionally
reclassified as RecordIncomplete. Migration-style silent upgrade is
forbidden. Test `TestProbe_OldStyleRecord_DegradesToIncomplete`
falsifies this path directly.

> **Migration note:** Older prior-authority records may now classify
> as Incomplete by design. This is intentional safety tightening, not
> a functional regression. Records produced by the install-side writer
> that lands alongside PR-23 will carry all required fields.

## Plan integration (plan.go)

- `Plan.RestoreAuthorized` now uses `PriorState.IsUsable()` — both
  Usable variants authorize, active/inactive is separate dimension
- new `Plan.PriorIncompleteReason` surfaces typed reason in JSON
- new `Plan.PriorActiveAtInstall *bool` surfaces the tri-state
  (nil = unknown, &true/&false = explicit) — PR-24 uses this to
  decide whether restoration needs a second confirmation prompt
- new Render line `Prior firewall at install : active|inactive`
  only emitted when record is usable — no defaulted values
- new warning when restore requested on UsableInactive record

## Tests

Added (uninstall_test.go):

- `TestProbe_RecordUsableActive` (rename of TestProbe_RecordUsable)
- `TestProbe_RecordUsableInactive` — active_at_install=false path
- `TestProbe_RecordMalformed_BadJSON` — split from Incomplete
- `TestProbe_RecordIncomplete_MissingRecordedAt`
- `TestProbe_RecordIncomplete_MissingInstallerVersion`
- `TestProbe_RecordIncomplete_MissingActiveAtInstall`
- `TestProbe_OldStyleRecord_DegradesToIncomplete` — backward-safety
- `TestBuildPlan_Restore_UsableInactive_AuthorizedButWarned`
- All existing tests updated: fixtures carry all 5 required fields;
  JSON strings updated to `record_usable_active`

Every Incomplete* test also asserts the specific IncompleteReason
(not just the state) so regressions attribute cleanly.

## Doc update (contract.md)

Added "PR-P2-1 hardening" section under the prior-authority record
definition: describes the 5 states, what "usable" now means, explicit
backward-safety rule.

## Non-goals (strict scope lock)

- no restore execution
- no lifecycle mutation
- no signature/checksum framework
- no unrelated refactors

Refs: internal/installer/uninstall/contract.md §"Pre-PR-23 blockers"
Authorization: locked repair contract (pre-PR-23 Phase 2 item #1)

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

Author: itcmsgr

internal/installer/uninstall/contract.md

@@ -85,6 +85,40 @@ PR-23). PR-22 only reads — it does not write any prior-authority
 artifact (that's install-side expansion per v1.100 Q9, tracked for
 PR-23 or a companion install-mode PR).
 
+### PR-P2-1 hardening (landed pre-PR-23)
+
+The 3-state classification above was tightened to 5 states so PR-24
+restore-enforcement has a stricter foundation:
+
+| State | Meaning |
+|---|---|
+| `NoRecord` | no artifact on disk |
+| `RecordMalformed` | artifact exists but JSON does not parse |
+| `RecordIncomplete` | JSON parses but required fields missing, unknown, or semantically unusable |
+| `RecordUsableActive` | all required fields present AND prior firewall was active at install time |
+| `RecordUsableInactive` | all required fields present AND prior firewall was explicitly NOT active at install time |
+
+"Usable" now requires:
+
+- JSON parses
+- schema version matches
+- firewall type is one of the known types
+- `recorded_at` timestamp present
+- `installer_version` present
+- `active_at_install` explicitly committed (pointer non-nil, not just
+  Go's zero-value false)
+
+**Usable does not imply "restore/re-enable now."** It means the record
+itself is trustworthy — PR-24 will still define its own restoration
+authorization rules on top of that.
+
+**Backward-safety note:** older records from before PR-P2-1 that lack
+`recorded_at` / `installer_version` / explicit `active_at_install` are
+intentionally reclassified as `RecordIncomplete` by the new Probe logic.
+This is safety tightening, not a functional regression. Records
+produced by the install-side writer that lands alongside PR-23 will
+carry all required fields.
+
 ---
 
 ## Plan output — contract-language rendering

internal/installer/uninstall/plan.go

@@ -78,15 +78,38 @@ type Plan struct {
 	RestoreRequested bool `json:"restore_requested"`
 
 	// RestoreAuthorized is true only when RestoreRequested AND
-	// PriorState == PriorRecordUsable. This is the PR-22 classifier
-	// output; PR-24 enforces it.
+	// PriorState.IsUsable() returns true (both UsableActive and
+	// UsableInactive qualify — active/inactive is a separate semantic
+	// dimension surfaced via PriorActiveAtInstall). PR-24 enforces
+	// this gate.
 	RestoreAuthorized bool `json:"restore_authorized"`
 
-	// PriorState is the 3-state probe result for the prior-authority
-	// record. Populated regardless of RestoreRequested so the operator
-	// always sees the underlying ambiguity.
+	// PriorState is the 5-state probe result for the prior-authority
+	// record (PR-P2-1 hardened). Populated regardless of RestoreRequested
+	// so the operator always sees the underlying ambiguity.
 	PriorState PriorRecordState `json:"prior_state"`
 
+	// PriorIncompleteReason is populated when PriorState ==
+	// RecordIncomplete and gives a machine-consumable reason code so
+	// downstream tooling doesn't have to substring-match human notes.
+	// Empty string when the state is not Incomplete.
+	PriorIncompleteReason IncompleteReason `json:"prior_incomplete_reason,omitempty"`
+
+	// PriorActiveAtInstall surfaces the active-at-install-time
+	// distinction when the record is usable. Three values:
+	//
+	//   *true  — the prior firewall was actively holding authority at
+	//            install time; restore = re-enable a firewall that was
+	//            running
+	//   *false — the prior firewall was present but NOT active at install
+	//            time; restore = enable a firewall that was NOT running
+	//            (a different operation; operator should see this)
+	//   nil    — unknown (usable state not reached)
+	//
+	// PR-24 uses this to decide whether restoration needs a second
+	// confirmation prompt.
+	PriorActiveAtInstall *bool `json:"prior_active_at_install,omitempty"`
+
 	// Warnings is the operator-visible list of concerns that do NOT
 	// abort the plan but should be surfaced. Example: "restore flag
 	// set but no prior-authority record on disk".
@@ -123,14 +146,15 @@ const PlanSchemaVersion = "1.100.0"
 // --restore-prior-authority flag at call time.
 func BuildPlan(mode Mode, auth *ClassifyResult, prior *ProbeResult, restoreRequested bool) *Plan {
 	p := &Plan{
-		SchemaVersion:     PlanSchemaVersion,
-		RequestedMode:     mode,
-		ArtifactPolicy:    artifactPolicyFor(mode),
-		CurrentAuthority:  auth.State,
-		DetectedExternal:  auth.External,
-		RestoreRequested:  restoreRequested,
-		PriorState:        prior.State,
-		RestoreAuthorized: restoreRequested && prior.State == PriorRecordUsable,
+		SchemaVersion:         PlanSchemaVersion,
+		RequestedMode:         mode,
+		ArtifactPolicy:        artifactPolicyFor(mode),
+		CurrentAuthority:      auth.State,
+		DetectedExternal:      auth.External,
+		RestoreRequested:      restoreRequested,
+		PriorState:            prior.State,
+		PriorIncompleteReason: prior.IncompleteReason,
+		RestoreAuthorized:     restoreRequested && prior.State.IsUsable(),
 		// Scope boundary is carried in the struct so JSON + text both see
 		// it. No text/JSON drift (audit D.5).
 		ScopeBoundary: "PR-22 scope: detect + plan only. No mutation code " +
@@ -139,6 +163,15 @@ func BuildPlan(mode Mode, auth *ClassifyResult, prior *ProbeResult, restoreReque
 		NoMutationPerformed: true,
 	}
 
+	// PR-P2-1: surface the active-at-install distinction when the
+	// record is usable. Populated only when the record parsed and was
+	// classified as UsableActive/UsableInactive — otherwise nil so
+	// downstream consumers see "unknown," not a defaulted false.
+	if prior.State.IsUsable() && prior.Record != nil && prior.Record.ActiveAtInstall != nil {
+		v := *prior.Record.ActiveAtInstall
+		p.PriorActiveAtInstall = &v
+	}
+
 	// TargetAuthority — per Q2=C (frozen), default is None; restore is
 	// opt-in AND authorized (needs recorded usable prior).
 	switch {
@@ -154,9 +187,21 @@ func BuildPlan(mode Mode, auth *ClassifyResult, prior *ProbeResult, restoreReque
 		p.Warnings = append(p.Warnings,
 			"--restore-prior-authority requested but no prior-authority record exists — PR-24 will refuse this combination")
 	}
+	if restoreRequested && prior.State == PriorRecordMalformed {
+		p.Warnings = append(p.Warnings,
+			"--restore-prior-authority requested but prior-authority record is malformed (JSON parse failed) — PR-24 will refuse this combination")
+	}
 	if restoreRequested && prior.State == PriorRecordIncomplete {
 		p.Warnings = append(p.Warnings,
-			"--restore-prior-authority requested but prior-authority record is incomplete/unparseable — PR-24 will refuse this combination")
+			"--restore-prior-authority requested but prior-authority record is incomplete — PR-24 will refuse this combination")
+	}
+	// PR-P2-1: restoring an inactive prior is a semantically different
+	// operation (you're starting a firewall that was NOT running). Flag
+	// it even when restore is authorized so the operator sees the
+	// distinction before PR-24 runs.
+	if restoreRequested && prior.State == PriorRecordUsableInactive {
+		p.Warnings = append(p.Warnings,
+			"--restore-prior-authority requested; prior-authority record is usable but records the prior firewall as NOT active at install time — restoration would re-enable a firewall the operator was not running")
 	}
 	if auth.State == AuthorityAmbiguous {
 		p.Warnings = append(p.Warnings,
@@ -220,6 +265,20 @@ func (p *Plan) Render(w io.Writer) {
 	fmt.Fprintf(w, "  Restore requested           : %s\n", yesNo(p.RestoreRequested))
 	fmt.Fprintf(w, "  Restore authorized          : %s\n", yesNo(p.RestoreAuthorized))
 	fmt.Fprintf(w, "  Prior-authority record      : %s\n", p.PriorState)
+	// PR-P2-1: surface the active-at-install distinction when the
+	// record is usable. Operator must see the semantic difference
+	// between "restore a running firewall" and "enable a firewall that
+	// was not running." Unknown states (non-usable record) intentionally
+	// skip this line rather than display a defaulted value.
+	switch {
+	case p.PriorActiveAtInstall != nil && *p.PriorActiveAtInstall:
+		fmt.Fprintln(w, "  Prior firewall at install   : active (was running when nftban installed)")
+	case p.PriorActiveAtInstall != nil && !*p.PriorActiveAtInstall:
+		fmt.Fprintln(w, "  Prior firewall at install   : inactive (was NOT running when nftban installed)")
+	}
+	if p.PriorIncompleteReason != "" {
+		fmt.Fprintf(w, "  Prior-record issue          : %s\n", p.PriorIncompleteReason)
+	}
 	fmt.Fprintln(w, "")
 
 	if len(p.Warnings) > 0 {