sasa/wireguard-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add refactoring contract, terminology and behavior map

Browse Source
This commit is contained in:
sasa
2026-10-29 22:26:25 +02:00
parent 23d6180f24
commit ede45d224a
4 changed files with 689 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PLANS.md
+296 -4
View File
@@ -126,7 +126,17 @@ Each row is a delivery milestone, not a completion claim. Expand its record befo
| 14 | Restart verification for valid legacy peers | 13 | accepted |
| 15 | Diagnosable systemd restart and unloaded-unit resolution | 14 | accepted |
| 16 | Root systemd private peer restart transport | 15 | accepted |
| 17 | Adaptive client list, persistent details and clear states | 16 accepted; existing M7/M12 TUI | accepted || 18 | Readable, complete in-app help for implemented workflows | 17 | accepted |
| 17 | Adaptive client list, persistent details and clear states | 16 accepted; existing M7/M12 TUI | accepted |
| 18 | Readable, complete in-app help for implemented workflows | 17 | accepted |
| 19 | Refactoring contract, terminology and behavior map | 18 | accepted |
| 20 | Explicit vocabulary and named operation contexts | 19 | pending |
| 21 | Domain ownership of reservations and apply knowledge | 20 | pending |
| 22 | Transactional draft editing and client creation vertical slice | 21 | pending |
| 23 | Readable saved-state Commit and restore scenarios | 22 | pending |
| 24 | Session-owned first delivery and password reissue scenarios | 23 | pending |
| 25 | Explicit restart verification scenario | 24 | pending |
| 26 | Application read models and thin TUI command adapter | 25 | pending |
| 27 | Integrated refactoring acceptance and architecture handoff | 26 | pending |
### Milestone 1 — Rust foundation, settings, and domain states
@@ -3865,11 +3875,293 @@ A more detailed guide requires functional scrolling as well as rewritten text. K
Accepted for presentation and synthetic fixture scope after independent review, R1/R2 closure and pinned Rust gates. No manual terminal-emulator, Alpine, disposable-VM, live WireGuard or production result is claimed. Stop after M18; do not commit, publish, deploy, access production or resume VM work.
## Approved domain refactoring programme — milestones 19–27
Status: M19 accepted; M20–M27 are pending. The user approved the proposed direction and requested detailed milestones on 2026-10-29. This paragraph records that plan's origin; current task progress is in the milestone records and resume point below. M18 remains accepted. These milestones preserve the approved product contract and all existing acceptance limitations, including retired/unaccepted M9 and unverified real-system paths. They do not resume VM work.
### Shared execution contract for M19–M27
Read before each dispatch: AGENTS.md, docs/SPEC.md, CONTEXT.md, the three docs/adr/0001–0003 decisions, docs/PROJECT_LAYOUT.md, docs/DEVELOPMENT.md, docs/TESTING.md, docs/ENVIRONMENT.md, docs/DEPENDENCIES.md, docs/CODEX.md, docs/IMPLEMENTATION.md, docs/EXECUTION_RECORDS.md, this section, the active milestone and its predecessor's evidence. Read only relevant historical evidence/diagnostics when a concrete question requires it. The coordinator must use the configured model/effort prerequisites; no silent substitution. Implementer/reviewer/repairer are separate GPT-6-Luna/high agents. One writer at a time; coordinator owns PLANS.md, task boundaries, findings and acceptance. Each table row is a bounded dispatch, not a request to implement the whole programme. Supply exact owned files, relevant interfaces, prerequisites and expected checks to every agent. Inspect the current tree before dispatch because paths below describe planned destinations, not modules already present.
**Fixed constraints.** No product/UI workflow, shortcut, persisted schema/version, archive member, default path, cryptographic primitive, authentication policy, dependency, Cargo feature or transport behavior change. No new crates/workspace, generic repository framework, event sourcing, CQRS infrastructure, plugin system, speculative traits or arbitrary file-size targets. Concrete internal owners and narrow functions are preferred. Keep byte-preserving editing in wireguard, secure I/O and recovery in their adapters, and temporary secrets out of public projections/Debug/errors. Do not change Cargo.toml/Cargo.lock for this programme. If a correctness defect or requirement conflict appears, record it and isolate affected work; do not hide a behavior change in a move. Existing external API/test consumers must be inventoried before removing a public escape hatch. Retain a narrow forwarding API where needed during migration; remove it only after all actual callers have migrated.
**Target responsibilities.** Names are working names to finalize in M19. `ServerPeerRecord` means an authoritative document record, potentially malformed/ambiguous/inspection-only; it is not a second independently mutable registry. The existing `Client` remains a restricted management projection, not a universal representation of every WireGuard peer. `RuntimePeer` remains an observation. `DraftChanges` is a boundary for coordinated document/client/vault edits, not a pure-domain holder of filesystem or crypto operations. `AddressReservations` owns reservation rules. `ApplyStatus` describes present knowledge; historical verification and raw observations remain distinct. `FirstDeliverySession` owns creation-session eligibility and short-lived secrets. Pure rules belong in domain; use cases coordinate adapters. The server document remains authoritative.
**Preservation matrix (required throughout).** Check creation/rename/delete/discard/Commit; IPv4-only and dual-stack clients; duplicate aliases; metadata-free, subnet-route, missing-IPv4, malformed and duplicate-identity peers; import anomalies and mismatches; original file preservation; mandatory backup failure; partial install/recovery; restore cancellation/stale preview/settings path restrictions; first-delivery retry/overwrite/cleanup/publication uncertainty; password-per-client reissue; shared restart deadline, service submission uncertainty, complete-peer verification and durable publication failure; reservation release only after verified restart; reopening does not infer current application from historical success; responsive worker cancellation/shutdown, generation checks and explicit QR disclosure. Preserve successful behavior and honest failures, not just function signatures.
**Validation profiles.** `DOC` means inspect Markdown local links/anchors, register/status/resume consistency, task numbering and factual claims, then `git diff --check`. `RUST` means environment checks in docs/ENVIRONMENT.md, focused existing behavioral tests for owned responsibilities, followed by `cargo fmt --all -- --check`, `cargo clippy --locked --all-targets -- -D warnings`, `cargo test --locked`, `cargo build --locked --release`, and `git diff --check` on final integrated inputs. Commands assume the verified pinned-toolchain environment; do not use a different system Cargo silently. Expected outcome is exit 0; record actual counts/ignored tests rather than copying M18 results. Do not run full gates for every diagnostic edit. Use existing test adapters and synthetic fixtures; add tests only for uncovered behavioral boundaries, not private field names or forwarding methods. Existing tests may move with their owner, but do not weaken/delete assertions to make the refactor pass. Review final production paths independently of test results.
**Evidence and acceptance.** At each milestone, coordinator creates/updates docs/evidence/milestone-N.md with source identity including dirty inputs, commands and results, acceptance mapping, independent review and limitations. Create docs/diagnostics/milestone-N.md only when needed. Review findings use stable M<N>-R<N> IDs with location, impact, expected behavior and reproduction; repair and re-review before acceptance. No claims from commands not run. Root, production keys/configs/services and live VPN testing are forbidden. Alpine is separate opt-in evidence and never systemd evidence; unavailable prerequisites remain incomplete validation. A public item is not made private merely to satisfy a structural goal without checking binary, integration tests and container-driver callers. Update docs/PROJECT_LAYOUT.md when actual responsibilities move; keep CONTEXT.md a glossary, without module paths or implementation notes.
### Milestone 19 — Refactoring contract, terminology and behavior map
Status: accepted (2026-10-29T22:24:30+02:00). Prerequisite: M18 accepted; no code refactoring was performed in this milestone.
#### Outcome and scope
Provide a precise migration contract so subsequent workers can perform bounded changes without inventing domain semantics. Inspect current source and test callers; documentation only. Planned owned files: CONTEXT.md, docs/architecture/domain-refactoring.md (new, created for substantive content), docs/evidence/milestone-19.md. Coordinator alone updates PLANS.md. Do not rewrite SPEC/ADRs or historical evidence.
#### Tasks and implementation steps
| Task | Owner | State | Bounded deliverable |
| --- | --- | --- | --- |
| M19.1 | implementer `/root/m19_inventory` | complete | Inventoried authority, application/domain/TUI ownership, test callers and public escape hatches; no edits or tests |
| M19.2 | implementer `/root/m19_inventory` | complete | Added glossary and source-referenced architecture contract with transitions, ownership, caller audit and M20–M27 test map; no code changes |
| M19.3 | fresh reviewer `/root/m19_reviewer`; coordinator | complete | R1–R6 closed by independent re-review; integrated DOC passed; M19 accepted |
1. Trace src/domain.rs, src/app.rs, src/runtime.rs, src/wireguard/{document,edit}.rs, src/persistence.rs, src/backup.rs, src/vault{,/import,/source}.rs, src/delivery.rs and src/tui/{state,events,forms,terminal,render}.rs. Include startup.rs, lib.rs, container_driver.rs and tests as API consumers. Distinguish production lines from colocated tests; file length alone is not a reason to split.
2. In the architecture document, make a table: current type/function/field -> business meaning -> authoritative source -> proposed owner -> readers/writers -> existing tests -> migration milestone. Cover Application fields, ClientStates fields/mutators, display/projection logic, authorization contexts and worker generations. Use verified source references. Record public escape-hatch callers (`draft_mut`, `vault_draft_mut`, `add_client`, `open`) and whether they can be replaced safely.
3. Add glossary entries for saved state, applied state/verification, server peer record, manageable client, runtime observation, reserved address and first delivery. Preserve existing meanings and avoid introducing user/account identities. Explain that a malformed peer can lack a usable public key and must still be inspectable; a valid subnet-route peer can be restart-verifiable without being manageable. Unknown creation dates remain unknown. Implementation names belong in the architecture document only.
4. Write transition tables with trigger, preconditions, next state, side effects, failure/cancel outcome and existing proof. Cover draft lifecycle, reservation creation/release, current vs historical verification, first delivery stages (including publication uncertainty/manual cleanup), restore preview/confirmation and restart attempt identity. Distinguish cancellation before execution from a submitted service job that may still finish.
5. Agree concrete destination modules and dependency direction; prefer domain child modules, app child modules and an application-owned read model. Record incremental API compatibility/removal strategy, persisted-format compatibility fixtures, gaps needing focused tests, and responsibility-specific test commands discovered from actual test names. No empty modules or architecture-only traits.
#### Acceptance and validation
- [x] M19-A1: every proposed owner/transition maps to actual source and tests; unsupported peers and historical verification are explicitly covered, with the unprojectable-peer restore gap recorded for M23.
- [x] M19-A2: glossary is domain-only; architecture map specifies authority and prevents an independent client registry.
- [x] M19-A3: each later milestone has an unambiguous migration surface and existing behavioral baseline; no product changes or new dependency are implied.
- [x] M19-A4: separate reviewer checked actual source, R1–R6 closed; integrated DOC passed.
Review and repair: M19-R1 (P2, restore state) closed by corrected rewrite/history contract and re-review. M19-R2 (P2, historical M18 handoff) closed by plan clarification/re-review. M19-R3 (P2, unprojectable-peer restore reservations) closed by documenting current behavior, focused test gap and M23 repair under the existing requirement; re-review confirmed. M19-R4 (P3, programme/M17 handoff) closed by plan clarification/re-review. M19-R5 (P3, stale M19.3 task row) closed by correction and re-review. M19-R6 (P2, future task/test-map fidelity) closed after tuple arity and actual test targets were aligned and independently rechecked.
Evidence/handoff: [M19 evidence](docs/evidence/milestone-19.md) identifies the dirty source inputs, exact DOC checks, reviewer dispositions and limitations. The user confirmed the coordinator uses GPT-6-Sol/medium; workers were dispatched with GPT-6-Luna/high. M18 is accepted; M9 is retired/unaccepted and is not an M19 prerequisite. No Rust tests/build, Alpine or VM checks were required or run for this documentation-only milestone. Outcome: accepted for the migration contract; next action, only on a separate request, is M20.1.
### Milestone 20 — Explicit vocabulary and named operation contexts
Status: pending. Prerequisite: M19 accepted.
#### Outcome and scope
Remove name ambiguity and opaque tuples without moving business rules. Planned owners: src/domain.rs and optional domain child modules, src/runtime.rs, src/app.rs, src/tui/{events,state}.rs, actual callers/tests, docs/PROJECT_LAYOUT.md. Keep public forwarding names only where the M19 caller map justifies them.
| Task | Owner | State | Bounded deliverable |
| --- | --- | --- | --- |
| M20.1 | implementer | pending | Rename conflicting knowledge/observation types and migrate callers |
| M20.2 | implementer | pending | Replace prepared-operation tuples with private named structures |
| M20.3 | reviewer; repairer; coordinator | pending | Review semantic equivalence, repair, RUST acceptance |
1. Rename the domain `RuntimeObservation` (currently Unknown/Unavailable/Verified) to the M19 canonical knowledge name, such as `ApplyStatus`; retain runtime::RuntimeObservation for measured interface data. Decide whether tui::AppliedState is a necessary presentation mapping or an exact redundant copy. Remove only redundant representation; do not merge raw statistics and verification status. Inventory every `as Statistics`/`as TechnicalObservation` alias and change only aliases made unnecessary by clarified names.
2. Replace ApplicationExecutor.prepared_destination's six-element tuple with named fields for identity, QR choice, delivery mode, retry attempt, generation and PreparedDestination. Replace restore_preview's tuple similarly. Preserve secret ownership, clear-on-unrelated-command behavior, stale-generation refusal, overwrite confirmation and cancellation. Avoid adding Clone/Debug to secret-bearing types.
3. Introduce only justified value types from M19 (for example a typed delivery mode replacing `reissue: bool` inside the prepared context). Migrate constructors/pattern matches/callers atomically for each type; do not redesign public commands or retry flags in this milestone.
4. If splitting domain.rs, move coherent definitions/tests mechanically, preserve exports needed by callers and keep implementation separate from semantic edits. Inspect diff for changed branches/order/errors; those belong to later milestones or separately recorded defects.
#### Acceptance and validation
- [ ] M20-A1: present apply knowledge and measured observation have distinct canonical names; no accidental meaning change in UI labels.
- [ ] M20-A2: prepared contexts use named fields; generation/cancel/confirmation behavior and secret redaction remain equivalent.
- [ ] M20-A3: actual consumers compile, dependencies/formats untouched; focused worker/state tests and RUST pass after independent review.
Focused starting commands: `cargo test --locked domain::`, `cargo test --locked runtime::`, `cargo test --locked tui::events::`, `cargo test --locked tui::state::`; adjust filters only to actual moved modules and report executed tests. Evidence: docs/evidence/milestone-20.md. Outcome: not accepted. Handoff: M21 only after acceptance.
### Milestone 21 — Domain ownership of reservations and apply knowledge
Status: pending. Prerequisite: M20 accepted.
#### Outcome and scope
Encapsulate address retention and verification transitions without changing persistence or technical matching. Planned production owners: src/domain.rs, src/domain/{reservations,apply}.rs as needed, app.rs and persistence.rs caller migration. Runtime matching stays in runtime; serialization stays in persistence. Creation-session secret state is out of scope.
| Task | Owner | State | Bounded deliverable |
| --- | --- | --- | --- |
| M21.1 | implementer | pending | Encapsulated reservation rules and existing allocator integration |
| M21.2 | implementer | pending | Explicit current/historical verification transitions and caller migration |
| M21.3 | reviewer; repairer; coordinator | pending | Review invariant matrix, repair and RUST acceptance |
1. Extract `AddressReservations` with private storage and intention-revealing operations to retain removed host addresses, restore conservative persisted reservations and expose read-only iteration/availability. Preserve conflict rejection, draft unsupported-peer reservations, Commit timing, discard behavior, IPv4/IPv6 allocation and broad-route deletion restrictions. Do not enumerate networks or infer free addresses from unavailable runtime data.
2. Keep draft-only pending reservations distinct from committed reservations until publication. Follow M19's transition table; preserve reservations from unprojectable exact host routes, and reject unsafe broad-route deletion as before. Move policy, not filesystem/parsing/crypto, into domain.
3. Separate current apply knowledge, optional last applied management snapshot and historical verified timestamp/projection. Preserve the valid state in which complete technical matching is verified but no complete management Snapshot can represent all peers. A single enum must not force a fake/partial snapshot.
4. Replace scattered field assignments with narrow transitions: saved state changed; runtime knowledge lost/unavailable; verified result durably published. Technical comparison success alone must not clear reservations or publish applied state before required internal-state persistence succeeds. Keep attempt authorization/checks private to the restart scenario until M25; do not expose an unrestricted public `mark_applied` method.
5. Migrate PersistedState conversion without changing TOML fields/version/order semantics or archive compatibility. Round-trip pre-refactor synthetic state, including reservations and historical timestamp. Reopen must restore conservative reservations and Unknown current knowledge. Keep existing failure paths intact.
#### Acceptance and validation
- [ ] M21-A1: only named domain transitions can release committed reservations; backup/service/read/mismatch/persistence failures cannot release them.
- [ ] M21-A2: legacy technical verification without a management snapshot, reopening and current vs historical status retain prior semantics.
- [ ] M21-A3: allocator, reservation, persisted round-trip and app failure tests pass; independent invariant review and RUST pass.
Focused starting commands: `cargo test --locked domain::`, `cargo test --locked persistence::`, `cargo test --locked app::`; reviewer specifically inspects reservation-release callers, not only tests. Evidence: docs/evidence/milestone-21.md. Outcome: not accepted. Handoff: M22 after acceptance.
### Milestone 22 — Transactional draft editing and client creation vertical slice
Status: pending. Prerequisite: M21 accepted.
#### Outcome and scope
Give document/client/vault drafts one coordinated publication boundary and make create -> preview -> Commit readable end to end. Planned owners: src/app.rs, src/app/{draft,clients,import}.rs as warranted, necessary domain APIs, startup/test callers and focused tests. Preserve app::Application public entry points during extraction. Commit internals are refactored in M23; delivery internals in M24.
| Task | Owner | State | Bounded deliverable |
| --- | --- | --- | --- |
| M22.1 | implementer | pending | Internal draft owner and staged replacement API |
| M22.2 | implementer | pending | Create/rename/delete/discard and setup/import migration |
| M22.3 | reviewer; repairer; coordinator | pending | Vertical-slice/failure review, repair and RUST acceptance |
1. Build an internal `DraftChanges` owner containing the lossless document, restricted client projection, encrypted vault draft and draft-only reservation changes, or the concrete composition agreed in M19. It belongs to the application boundary because it coordinates crypto/document components. Avoid deep-cloning plaintext keys and avoid generic transactions/closures that obscure what is staged.
2. For each edit, prepare all fallible replacements locally, validate the edited document and corresponding public projection, then replace live draft components together. No file/runtime mutation is allowed. Document is authoritative: never rebuild it from Snapshot, and do not drop malformed/unsupported records merely because projection fails.
3. Migrate prepare_new_client first: resolve settings as currently required, calculate occupancy from full document plus reservations/server addresses, validate manual dual-stack addresses or allocate defaults, generate key, encrypt record, stage document/client/vault updates, and register session-first-delivery material only on successful publication. Preserve timestamp validation and key/error redaction. Keep first-delivery ownership temporarily behind its existing interface for M24.
4. Migrate add_client/rename_client/delete_client/discard_draft one at a time. Preserve alias validation/duplicates, metadata preservation, fallback labels, deletion restrictions, retained-address policy and precise revocation of session issue rights. Cancel/discard must restore saved data without writes or recreating consumed first-delivery eligibility.
5. Migrate initial vault setup and selected-file import through the same draft publication boundary; preserve all-or-nothing staging, key matching, anomaly reports and source-file preservation. Keep source scanning/reconciliation and encryption in existing adapters. Restrict `draft_mut`/`vault_draft_mut` only after replacing all real callers with intentional operations; tests must not be granted a production bypass.
6. Keep Application a facade delegating to cohesive owners; avoid moving the same large impl into a differently named catch-all file. Add focused failure tests only where no existing test proves that an error leaves every draft component and first-delivery eligibility unchanged. Update actual layout documentation.
#### Acceptance and validation
- [ ] M22-A1: create/rename/delete/import/setup/discard use coordinated draft publication; intermediate errors leave no partial draft or newly authorized issue.
- [ ] M22-A2: source bytes outside allowed edits, existing client parameters, unsupported records and original import files remain preserved.
- [ ] M22-A3: synthetic create -> preview -> Commit -> first delivery -> explicit fixture restart and deletion/discard flows still pass; no live runtime operation occurs during draft/Commit.
- [ ] M22-A4: independent review checks authority/secret lifetimes; RUST passes with unchanged formats/dependencies.
Focused commands: `cargo test --locked app::`, `cargo test --locked --test config_preservation`, `cargo test --locked --test client_delivery`, `cargo test --locked --test vault_import`, `cargo test --locked --test tui_workflow`. Evidence: docs/evidence/milestone-22.md. Outcome: not accepted. Handoff: M23 after acceptance.
### Milestone 23 — Readable saved-state Commit and restore scenarios
Status: pending. Prerequisite: M22 accepted.
#### Outcome and scope
Extract explicit saved-state scenarios with visible ordering and honest failure publication. Planned owners: src/app.rs, src/app/{commit,restore,backups}.rs, facade/private session interfaces, affected tests. Persistence journal, archive format, path security and low-level I/O algorithms stay in persistence.rs/backup.rs; only necessary call-site adjustments there.
| Task | Owner | State | Bounded deliverable |
| --- | --- | --- | --- |
| M23.1 | implementer | pending | Commit preparation, backup/install, in-memory publication |
| M23.2 | implementer | pending | Backup listing/creation and preview-confirm restore scenario |
| M23.3 | reviewer; repairer; coordinator | pending | Ordering/recovery/compatibility review, repair and RUST acceptance |
1. Extract Commit as readable preparation -> validate proposed saved bytes -> completed pre-Commit backup of installed state -> journaled install -> publish new session state. Keep a concrete prepared result if it clarifies which fallible work precedes mutation. Do not turn backup confirmation into a public forgeable permission or allow callers to skip it.
2. Preserve failure behavior: draft remains retryable, readback after failed install conservatively retains/revokes first-issue rights, saved/application history is not advanced on failure, and recovery on reopen follows the existing journal. Avoid an apparently infallible final publication that hides parsing or state-install errors.
3. Extract preview_restore and confirm_restore. Preview remains read-only and secret-safe; confirmation validates the bound saved generation/installation paths, creates precautionary backup and fully replaces the saved components (including absent optional components). Preserve draft warning/cancel and settings re-resolution. Restore never requests a vault password or touches the running interface.
4. Move manual/pre-restart backup entry points only as needed to establish a clear backup responsibility. Historical verification labels must refer to the archived generation, not the newest archive or current statistics. Keep cloned SavedBytes secret-bearing and out of ordinary read models/Debug.
5. Keep service/runtime dependencies unavailable to Commit and restore modules except shared public status types when necessary; reviewer must inspect actual dependency/call paths. Preserve existing callback failure seams with concrete narrow interfaces; do not add a general storage/service framework.
#### Acceptance and validation
- [ ] M23-A1: completed backup precedes protected mutation for Commit/restore; failures and cancel retain documented draft/saved/runtime behavior.
- [ ] M23-A2: restore compatibility, path restrictions, absent components, recovery and historical status tests retain their assertions.
- [ ] M23-A3: fixture old-state backups and state/vault/archive compatibility checks pass; no runtime/service call in saved-only paths; independent review and RUST pass.
Focused commands: `cargo test --locked app::`, `cargo test --locked persistence::`, `cargo test --locked backup::`, `cargo test --locked --test commit_restore`, `cargo test --locked --test client_delivery`. Evidence: docs/evidence/milestone-23.md. Outcome: not accepted. Handoff: M24 after acceptance.
### Milestone 24 — Session-owned first delivery and password reissue scenarios
Status: pending. Prerequisite: M23 accepted.
#### Outcome and scope
Isolate the session-first-delivery state machine and expose readable authenticated delivery scenarios. Planned owners: src/app.rs, src/app/{first_delivery,reissue}.rs or cohesive delivery children; affected facade/TUI adapter callers and tests. Cryptography, secure publication and QR encoding remain in vault/delivery adapters. No workflow or password policy change.
| Task | Owner | State | Bounded deliverable |
| --- | --- | --- | --- |
| M24.1 | implementer | pending | FirstDeliverySession eligibility, invalidation and retry transitions |
| M24.2 | implementer | pending | First-file/QR and password-reissue scenario extraction |
| M24.3 | reviewer; repairer; coordinator | pending | Secret/authorization/failure review, repair and RUST acceptance |
1. Move InitialIssue/IssueStage/IssueContext/token bookkeeping and matching/promote/retain helpers under one private owner. Keep ephemeral private keys in zeroizing/secret wrappers with no ordinary Clone/Debug/serialization. Use M19's transition table rather than simplifying PendingDraft/AwaitingFirstFile/RetryAvailable/Authorizing/overwrite/manual-cleanup states into one bool.
2. Expose narrow internal transitions for draft publication, successful Commit, discard/delete, changed peer/encrypted record, begin attempt and completed/failed publication. Tokens remain single-use, session-local, bound to client and saved context; no caller can manufacture a first-issue authorization. Preserve unrelated clients' rights when rename/restart does not invalidate their context.
3. Keep final saved-state authorization check adjacent to secure file publication with exclusive session ownership across the boundary. Extracting a component must not allow mutations between checking authorization and publishing a secret. Preserve retry to another directory and explicit overwrite/cleanup acknowledgements after uncertain failures.
4. Extract password reissue separately: selected client + password for this action -> decrypt/validate -> render -> mandatory file publication -> optional QR from the same payload. Never cache an unlocked vault or fall back to original plaintext files. Preserve imported parameters, discrepancy blockers and authoritative server values.
5. Preserve independent outcomes: file publication may succeed while QR fails; file may exist while bookkeeping is uncertain; warnings about not-yet-verified activation must survive failed/uncertain publication. Only successful mandatory publication consumes eligibility according to existing conservative uncertainty rules. Do not remove existing detailed failure variants or replace them with success/failure bools.
#### Acceptance and validation
- [ ] M24-A1: all first-delivery transitions/invalidation rules have one owner; pre-Commit, stale, consumed and reopened sessions cannot deliver without authorization.
- [ ] M24-A2: retry/uncertain publication/manual cleanup/bookkeeping failure and same-payload QR behavior remain covered; passwords and secrets absent from errors/Debug/projections.
- [ ] M24-A3: reissue asks per client/action and respects import mismatch policy; independent security-relevant path review and RUST pass.
Focused commands: `cargo test --locked app::`, `cargo test --locked delivery::`, `cargo test --locked vault::`, `cargo test --locked --test client_delivery`, `cargo test --locked --test tui_workflow`. Evidence: docs/evidence/milestone-24.md. Outcome: not accepted. Handoff: M25 after acceptance.
### Milestone 25 — Explicit restart verification scenario
Status: pending. Prerequisite: M24 accepted.
#### Outcome and scope
Make restart orchestration independently readable while preserving complete technical verification and every uncertainty boundary. Planned owners: src/app.rs, src/app/restart.rs and optional private restart children, facade/state transition interfaces, affected tests/container-driver imports. Netlink and systemd transports/decoders remain unchanged.
| Task | Owner | State | Bounded deliverable |
| --- | --- | --- | --- |
| M25.1 | implementer | pending | Restart preview, bound attempt and preparation extraction |
| M25.2 | implementer | pending | Ordered job/observation/verification/durable publication scenario |
| M25.3 | reviewer; repairer; coordinator | pending | Failure/deadline/legacy-peer review, repair and RUST acceptance |
1. Move preview/report/choice/diagnostic types and restart implementation coherently. Preserve current public imports with re-exports until callers migrate. Preview validates unsafe SaveConfig, structural ambiguity and complete SavedPeerProjection; it must not require every saved peer to fit Client/Snapshot.
2. Read the scenario in this order: validate preview against saved state -> honor cancel/draft choice -> complete backup -> discard draft at existing safe point -> submit configured service restart -> successful job completion -> bounded interface observation -> compare complete saved peer set -> durable verification bookkeeping -> publish applied knowledge/release reservations. Preserve actual existing ordering where this outline omits preparation; document it instead of introducing behavior changes.
3. Keep one shared monotonic deadline, existing clock/failure injection, restart attempt identity, generation checks and stale/duplicate-result rejection. An accepted job request is not a completed job. Timeout/submitted/may-still-complete/manual-recovery reporting must not collapse into one generic error.
4. Keep complete-peer technical projection/comparison in its existing responsibility; management metadata/aliases must not become technical match requirements. Preserve metadata-free, IPv4-only, subnet-route and missing-IPv4 valid peers, malformed/duplicate identities, incomplete dumps and peer mismatch behavior. Current statistics must not assert verification.
5. Persistence failure after successful matching must retain conservative apply knowledge/reservations and honest report. Do not introduce rollback or a second restart. Fixture apply callback must remain cfg(test)-only and unreachable from the production executable. Review both real transport call paths for unchanged use, without executing host services.
#### Acceptance and validation
- [ ] M25-A1: backup/job/read/verify/persist/publication sequence and cancellation semantics unchanged; current/saved generations and attempt identity remain bound.
- [ ] M25-A2: full-peer legacy cases, shared deadlines, service/transport distinctions, mismatch and post-verification persistence failure tests pass; reservations release only after durable verified success.
- [ ] M25-A3: no production fixture bypass, rollback or transport change; independent review and RUST pass. Real-system/IPv6 limits remain explicit.
Focused commands: `cargo test --locked app::`, `cargo test --locked runtime::`, `cargo test --locked service::`, `cargo test --locked --test commit_restore`, `cargo test --locked --test runtime_restart`. Run only synthetic non-ignored container-driver tests in ordinary gates. Evidence: docs/evidence/milestone-25.md. Outcome: not accepted. Handoff: M26 after acceptance.
### Milestone 26 — Application read models and thin TUI command adapter
Status: pending. Prerequisite: M25 accepted.
#### Outcome and scope
TUI consumes public application facts and action eligibility without parsing saved configuration or owning authorization rules. Planned owners: src/app/read_model.rs, app facade, src/tui/{state,events,forms,terminal,render}.rs and new cohesive TUI children, focused tests. Preserve output wording/geometry/keys/help, fixed footer and worker lifecycle.
| Task | Owner | State | Bounded deliverable |
| --- | --- | --- | --- |
| M26.1 | implementer | pending | Secret-free application view and per-action eligibility |
| M26.2 | implementer | pending | Migrate TUI projection and command execution adapter |
| M26.3 | implementer | pending | Split command/result/navigation responsibilities where justified |
| M26.4 | reviewer; repairer; coordinator | pending | UI parity/authorization/lifecycle review, repair and RUST acceptance |
1. Move ClientDisplay/SessionDisplay projection responsibilities to an application-owned read model. Include saved peer count, draft/saved public client differences, issue classification, reservation/apply facts and vault-initialized state. Keep UI-only selection, scroll, dialog focus, rendered strings/styles and worker generation in TUI. Raw ConfigDocument/SavedBytes/vault/password/payload must not be fields of the public view.
2. Represent action eligibility explicitly per action with typed reasons where useful. Audit current guards first: rename, delete, first delivery and restart do not necessarily have identical eligibility. In particular inspection-only management projection must not accidentally prohibit an already-supported deletion by public key. Never silently enable actions for malformed/ambiguous peers. Eligibility is guidance for presentation; application execution revalidates its actual preconditions.
3. Replace SessionView::from_application reparsing of saved bytes and recovery of business facts with the application view. Preserve unsupported peers without public keys, duplicate-identity records, removed-draft rows, selected public identity and safe peer-index inspection. Application view does not infer applied from handshake/counters or historical timestamp.
4. Extract ApplicationExecutor/prepared contexts/result adaptation from worker transport into a focused command adapter if it improves ownership. Keep the bounded single-owner worker, statistics generation filtering, prepared-preview/destination lifetime, cancellation, duplicate-submit protection, shutdown and terminal cleanup unchanged. No independent executor may share mutable Application or plaintext secrets.
5. Separate terminal lifecycle from key navigation/result messages only after the application boundary is clear. Split render.rs into cohesive list/details/help/footer modules if their responsibilities warrant it; preserve existing metrics, wrapping, QR disclosure and footer packing. Avoid generic dispatch registries or purely mechanical many-file splits. Each subtask must stay within one bounded responsibility and compile before the next begins.
6. Update internal help/user docs only for factual architecture references; no product wording/shortcut redesign. Keep masks and secret forms short-lived. Compare existing synthetic buffers and PTY workflows across established terminal dimensions, including 34x8, 40x9, 60x16, 80x24, 100x30 and 180x50.
#### Acceptance and validation
- [ ] M26-A1: TUI no longer parses saved server bytes to obtain application facts; read model is secret-free and includes all authoritative records.
- [ ] M26-A2: per-action availability matches existing handlers, with authoritative revalidation; selection/cancel/draft/QR behavior preserved.
- [ ] M26-A3: worker generation/continuation/shutdown tests, responsive help/list/footer buffer tests and synthetic PTY workflows pass without weakened assertions.
- [ ] M26-A4: reviewer checks UI parity and boundary direction; RUST passes; actual module layout documented.
Focused commands: `cargo test --locked tui::`, `cargo test --locked --test tui_workflow`, `cargo test --locked --test client_delivery`. Evidence: docs/evidence/milestone-26.md. Outcome: not accepted. Handoff: M27 after acceptance.
### Milestone 27 — Integrated refactoring acceptance and architecture handoff
Status: pending. Prerequisite: M26 accepted.
#### Outcome and scope
Verify the integrated refactoring against the original behavior map and demonstrate that common operations can be understood from their owning scenario. Owned scope: actual migrated APIs/tests, docs/architecture/domain-refactoring.md, CONTEXT.md, docs/PROJECT_LAYOUT.md and evidence. No new features or broad cleanup. Repairs must have named findings and bounded ownership.
| Task | Owner | State | Bounded deliverable |
| --- | --- | --- | --- |
| M27.1 | implementer | pending | Remove proven-obsolete compatibility paths and reconcile architecture map |
| M27.2 | independent reviewer | pending | Integrated behavior/authority/security/readability audit |
| M27.3 | repairer; reviewer; coordinator | pending | Bounded repairs, final integrated gates and handoff |
1. Compare every M19 source/test mapping with actual final owners. Remove obsolete forwarding APIs only after checking all binary, library, integration and container-driver callers. Remove stale milestone comments that incorrectly describe implemented paths as future work. Do not delete historical evidence or turn old verification limitations into new success claims.
2. Record a concise reading guide for create -> Commit -> first delivery -> explicit restart, delete -> Commit -> verified address release, and preview -> confirm restore. For each, name the entry point, rule owner, side-effect boundary and failure tests. A reviewer must be able to follow the scenario without discovering hidden UI authorization or independent metadata authority. Record justified exceptions instead of hiding them behind a size metric.
3. Independent reviewer audits the full preservation matrix and baseline-to-final diff, not only the latest milestone. Confirm persisted schemas/versions, archive members, cryptography/dependencies/defaults, public-key identity, byte-preserving authority, imported originals and short-lived secrets. Check for redundant mutable state and accidental widening of pub visibility. Existing fixtures from before the refactor must still load with unchanged meaning.
4. Run focused integrated tests and final RUST on identified final inputs. Establish which M8 Alpine evidence was invalidated by changed application inputs. If an explicitly authorized disposable Alpine environment is available, rebuild the current driver and follow docs/TESTING.md; otherwise record Alpine revalidation as incomplete, not a host-gate pass. No VM work is included, no systemd/IPv6 verification is inferred, and no release-readiness claim is authorized by this programme.
5. Accept the refactoring only for its documented host/synthetic scope after all required RUST checks and independent findings close. Report Alpine state separately; if any task explicitly made an Alpine check mandatory, keep that task incomplete until run. Final plan/evidence must state real-system limitations and identify the tested source. Stop after M27; do not commit/publish/deploy or launch another programme.
#### Acceptance and validation
- [ ] M27-A1: all M19 mappings resolved to actual owners/tests; glossary/layout/reading guide agree with code; obsolete bypasses removed or explicitly justified.
- [ ] M27-A2: integrated independent audit finds no unresolved behavior, authority, authorization or secret-handling regression.
- [ ] M27-A3: preserved-format synthetic fixtures and all required host RUST gates pass on final source; exact outcomes and separate Alpine/VM limitations recorded.
- [ ] M27-A4: milestone register, outcomes and current resume point agree; evidence contains reproducible source identity and final review disposition.
Evidence: docs/evidence/milestone-27.md. Outcome: not accepted. Handoff: stop after scoped acceptance; no subsequent milestone is authorized by this plan.
## Current progress and resume point
- M18 is accepted (2026-10-29): structured, accurate in-app Help, responsive wrapping and bounded scrolling passed independent R1/R2 closure, synthetic/PTY checks and pinned Rust completion gates. [M18 evidence](docs/evidence/milestone-18.md) records final inputs and limits. Stop here; no next milestone is started.
- M19 is accepted (2026-10-29T22:24:30+02:00): glossary and source-referenced migration contract passed independent R1–R6 closure and integrated DOC checks; [M19 evidence](docs/evidence/milestone-19.md) records inputs and limits. Stop after M19; M20–M27 remain pending. M18 remains accepted; M9 remains retired and real-system limitations remain unchanged.
- M17 is accepted (2026-10-28): adaptive columns, persistent selected-client details and explicit state/count presentation passed independent R1/R2 closure, synthetic/PTY checks and pinned Rust completion gates. [M17 evidence](docs/evidence/milestone-17.md) records final inputs and limits. Stop here; no next milestone is started.
- M18 was accepted on 2026-10-29: structured, accurate in-app Help, responsive wrapping and bounded scrolling passed independent R1/R2 closure, synthetic/PTY checks and pinned Rust completion gates. [M18 evidence](docs/evidence/milestone-18.md) records final inputs and limits. At that handoff, M19 had not started.
- M17 was accepted on 2026-10-28: adaptive columns, persistent selected-client details and explicit state/count presentation passed independent R1/R2 closure, synthetic/PTY checks and pinned Rust completion gates. [M17 evidence](docs/evidence/milestone-17.md) records final inputs and limits. At that handoff, M18 had not started.
- TUI-FL-001 is complete (2026-10-27): fixed-height two-row keyboard footer, narrow Help/overflow behavior and compact nine-row handling passed synthetic rendering tests, independent R1–R3 closure and pinned Rust gates. [Footer evidence](docs/evidence/tui-footer-layout.md) identifies source/artifact inputs.
- Milestone 16 is accepted by explicit user direction following a reported successful manual check. Earlier independent review/repair and pinned Rust gates passed; private-peer and both real transport paths still lack recorded disposable-VM evidence. [M16 evidence](docs/evidence/milestone-16.md) records the source and artifact. No production result is claimed by this execution.
@@ -3894,7 +4186,7 @@ Accepted for presentation and synthetic fixture scope after independent review,
- Milestone 8 delivered reviewed opt-in Alpine Testcontainers coverage for real IPv4 WireGuard peers, application lifecycle, saved/runtime separation, restoration, import/reissue, backup failures and the real Rustix reader. Host gates and three fresh real-container runs passed on one stable source fingerprint; M8-A1–A10 accepted. Real IPv6 behavior is unverified by user-authorized scope.
- Milestone 9 is retired and unaccepted: the reviewed disposable VM preparation and guarded first start did not establish Debian/systemd acceptance. The exact VM was powered off after the user stopped work. M9.2–M9.3 were not started; M9-A1–A9 are unchecked.
- Next action: none for M18. Stop after acceptance. Keep M16 validation limitations separate from TUI evidence. Do not access production, commit, deploy or resume VM work.
- M18 handoff remains complete. M19 is accepted; the next implementation action, when separately requested, is M20.1. Keep M16 validation limitations separate from TUI evidence. Do not access production, commit, deploy or resume VM work.
## Plan maintenance