feat(v1.99 PR-18): update apply orchestration (G3-U5..U10) — CONTRACT-ENFORCED

[itcmsgr]

0. Executive Summary

This PR introduces the update apply phase as a strictly orchestration-only layer that delegates all state mutation, validation, recovery, and authority enforcement to the existing rebuild/lifecycle authority.

No new apply logic is introduced.

This PR enforces that:

• Update apply is not an execution engine
• Update apply is not a second authority path
• Update apply is only a controlled entrypoint into rebuild

---

1. Core Contract (Hard Gate)

Invariant:

Update apply may only orchestrate payload application through the existing rebuild/lifecycle authority.

Explicitly:

• Apply MUST NOT implement its own:

  • configuration mutation
  • rendering logic
  • authority takeover
  • validation logic
  • recovery/rollback logic
  • service convergence logic

• Apply MUST:

  • call existing lifecycle/rebuild entrypoints
  • rely on existing validator gates
  • rely on existing recovery/rollback mechanisms
  • converge state through lifecycle authority only

---

2. Enforced Invariants

ID	Invariant	Enforcement
INV-U-001	No custom apply logic outside rebuild	Call graph + diff audit
INV-U-002	No partial switch without recovery	Mandatory rebuild recovery path
INV-U-003	No hidden authority expansion	Authority checks + post-state validation

Violation of any invariant = automatic NO-GO

---

3. Scope (G3-U5..U10)

G3-U5 — .conf.local Byte Preservation

• Apply MUST NOT modify .conf.local
• Verified via pre/post byte hash equality; rebuild path only reads, never mutates

G3-U6 — Base Config Safety

• No unsafe mutation of base config
• All config transitions only via existing template → render → rebuild pipeline

G3-U7 — Rebuild Recovery Integration (INV-U-002)

• Any failure during apply MUST trigger existing rebuild recovery/rollback
• Never leave partial state active

G3-U8 — Post-Update Validator Gate

• After apply: nftban-validate MUST run; invalid state MUST block success; recovery MUST be triggered on failure

G3-U9 — Service-State Convergence

• Final state MUST converge to lifecycle authority truth: nftables active, nftband state aligned, kernel == validator == CLI

G3-U10 — Authority Safety (INV-U-003)

• Apply MUST NOT expand authority scope, remove/disable external firewalls outside allowed model, or introduce new takeover paths

---

4. Non-Goals (Strictly Out of Scope)

• ❌ Any update-specific apply engine
• ❌ Direct config file mutation
• ❌ Alternative rendering pipeline
• ❌ Independent validation logic
• ❌ Custom rollback/recovery logic
• ❌ Authority takeover or firewall removal logic
• ❌ Service manipulation outside lifecycle authority

If any of the above becomes necessary → STOP and split into new design PR

---

5. Call Graph (Critical Proof)

update_apply
   ↓
lifecycle entrypoint (existing)
   ↓
rebuild pipeline (existing)
   ↓
validator (existing)
   ↓
recovery (existing, if needed)

There are NO parallel or side paths.

Concrete binding (today):

• runUpdateApply → exec.Run("nftban", "firewall", "rebuild") → firewall_rebuild (cli/lib/nftban/cli/cmd_firewall.sh:1070)
• → exec.Run("nftban-validate", "--json") → validator gate (cmd/nftban-validate)
• Recovery: delegated to firewall_rebuild's own _rebuild_* family (nftban_rebuild_recovery.sh) — PR-18 adds NO new recovery code

---

6. Execution Flow

1. Pre-check (read-only) — update.Preflight
2. Trigger lifecycle/rebuild entrypoint — nftban firewall rebuild
3. Rebuild executes: render → apply to kernel → enforce authority
4. Validator gate runs — nftban-validate --json
5. If failure: recovery/rollback via rebuild (not owned by apply)
6. If success: service state converges to lifecycle truth

---

7. Merge Evidence Requirements (Hard Checklist)

PR cannot merge without ALL of the following:

A. Structural Proof

• Call graph shows no apply-owned mutation path
• No new renderer/config writer introduced
• No new authority manipulation logic

B. .conf.local Preservation (G3-U5)

• Byte hash identical pre/post apply

C. Base Config Safety (G3-U6)

• No direct edits outside rebuild pipeline

D. Recovery Integrity (G3-U7)

• Forced failure test triggers rollback via rebuild
• No partial state remains active

E. Validator Gate (G3-U8)

• Invalid state blocks success
• Validator result matches kernel truth

F. Service Convergence (G3-U9)

• nftables/nftband consistent post-apply
• No drift between kernel / validator / CLI

G. Authority Safety (G3-U10)

• No unintended firewall removal
• No authority expansion detected

---

8. CI Gates (Blocking)

• G3-U5 → .conf.local preservation test
• G3-U6 → config mutation audit
• G3-U7 → recovery failure simulation
• G3-U8 → validator enforcement
• G3-U9 → convergence validation
• G3-U10 → authority safety check

All must be green and enforced (blocking)

---

9. Failure Model

Failure Type	Expected Behavior
Rebuild fails	rollback via lifecycle recovery
Validator fails	block + rollback
Partial apply	must not exist
Authority conflict	must be detected and blocked

---

10. Risk Assessment

Risk	Mitigation
Hidden apply logic creep	invariant enforcement + diff audit
Partial state activation	recovery integration (INV-U-002)
Authority drift	validator + authority checks
CI false positives	validator as source of truth

---

11. Definition of Done

PR-18 is DONE only if:

• Update apply is provably orchestration-only
• Rebuild remains the single mutation authority
• Validator is the single truth gate
• Recovery is always enforced
• No invariant is weakened or bypassed

---

12. Final Statement

This PR establishes that:

Update apply is not a system that changes state —
it is a controlled mechanism to request the existing system to do so safely.

Any deviation from this model invalidates the PR.

---

13. Stop Condition

If at any point implementation requires:

• new apply logic
• bypass of rebuild
• direct mutation
• custom recovery

→ STOP PR-18 immediately and escalate to design/audit.

---

Implementation plan (commit-by-commit)

1. Contract + proof skeleton — internal/installer/update/apply_contract.md + call-path audit test (this PR's seed commit already landed)
2. Minimal orchestration — runUpdateApply that invokes nftban firewall rebuild + nftban-validate and nothing else
3. Recovery/validator integration — delegate apply failures to rebuild's own recovery; validator gate blocks bad post-state
4. Convergence + authority proofs + CI gates G3-U5..U10

Status: Draft — standard v1.99 pattern, un-drafts after CI green. Each commit keeps the PR diff auditable.

🤖 Generated with Claude Code

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None