Add refactoring contract, terminology and behavior map

docs/evidence/milestone-19.md

@@ -0,0 +1,132 @@
+# Milestone 19 evidence: refactoring contract
+
+Recorded 2026-10-29T22:23:28+02:00. Base commit:
+`23d6180f2478f636c185d67b8bb3788d21656ce3`. The working tree is dirty:
+`PLANS.md` already held the user-approved M19–M27 plan before execution, and
+this milestone changed `PLANS.md` and `CONTEXT.md` and added
+`docs/architecture/domain-refactoring.md` and this report. No Rust source,
+manifest, lockfile, production configuration, or generated secret was changed.
+The reviewed substantive document inputs have these SHA256 fingerprints:
+
+| Input | SHA256 |
+| --- | --- |
+| `PLANS.md` (accepted snapshot) | `724bb710c2f8db7ceca7a059425be6a868e23ab9dd41cb1ff5ae5c32986a4b8e` |
+| `CONTEXT.md` | `06efa3f8bb91dbd3b7fb6a00f0035dde7c3be1c01d0a6fe9c096460d6d28deb8` |
+| `docs/architecture/domain-refactoring.md` | `7dbb01cfa85dd89a3d122ecf8a564dd204c805bea8a33cb09c4268d0308329c8` |
+
+## Scope and acceptance mapping
+
+M19.1 read-only inventory traced the domain/application, WireGuard document,
+runtime, persistence/backup, vault/import/source, delivery, startup, TUI,
+library, test-only container driver, and integration tests. M19.2 added a
+domain-only glossary and a source-referenced migration contract. The contract
+maps field/function authority, readers/writers, actual test names and M20–M27
+owners, and describes draft, reservation, verification, delivery, restore and
+restart transitions. It keeps the server document authoritative for malformed,
+metadata-free and unsupported peers, including valid subnet-route peers that
+can be verified technically without becoming manageable clients. Historical
+verification is distinct from current apply knowledge. This supports M19-A1–A3.
+
+The caller audit found `ClientStates::draft_mut` used by app production code and
+colocated tests; `Application::vault_draft_mut` by one colocated test;
+`Application::add_client` and `Application::open` by integration/test fixtures;
+and `open_from_saved_store` by production startup and the test-only container
+driver. The contract retains compatibility until actual callers migrate.
+M20 tuple arity is six; M22–M26 planned focused commands name present targets.
+No dependency, schema, archive, UI or behavior change is implied.
+
+The remaining behavior gap is explicit in the contract: current restore
+reservation coverage proves manageable saved clients, while
+`preview_restore` does not collect exact host routes from unprojectable current
+peers or `draft_unsupported_reservations`. M23 must add focused coverage and
+repair any uncovered preservation under the existing reserved-address policy.
+M19 does not claim that this behavior is already correct. M9 remains retired
+and unaccepted; M19 depends on accepted M18, not M9.
+
+## Independent review and repair
+
+A GPT-6-Luna/high implementer completed M19.1 and M19.2. A separate, fresh
+GPT-6-Luna/high reviewer inspected the actual source, callers, tests and
+documents. A GPT-6-Luna/high repairer corrected architecture wording; the
+coordinator alone corrected plan wording and later task commands. The reviewer
+rechecked each repair and reported no remaining actionable findings:
+
+| Finding | Final disposition |
+| --- | --- |
+| M19-R1 | Closed: restore rewrites internal state, retains conservative reservations and clears historical verification. |
+| M19-R2 | Closed: historical M18 handoff no longer contradicts active M19. |
+| M19-R3 | Closed for this documentation milestone: current unprojectable-peer restore reservation gap and M23 focused test/repair are recorded. |
+| M19-R4 | Closed: programme and historical M17 handoff wording reflect the current plan. |
+| M19-R5 | Closed: M19.3 task row reflects the current finding disposition. |
+| M19-R6 | Closed: tuple arity and later focused test targets match the actual repository. |
+
+This independent review supports M19-A4 subject to the final DOC checks below.
+
+## Validation and limits
+
+Final integrated DOC checks ran in the repository root on the accepted plan
+snapshot. The exact link/whitespace command was:
+
+```sh
+python3 - <<'PY'
+from pathlib import Path
+import re, sys
+files = [Path(p) for p in ('PLANS.md', 'CONTEXT.md', 'docs/architecture/domain-refactoring.md', 'docs/evidence/milestone-19.md')]
+errors = []
+links = anchors = 0
+for file in files:
+    body = file.read_text()
+    if not body.endswith('\n'): errors.append(f'{file}: final newline')
+    for number, line in enumerate(body.splitlines(), 1):
+        if line.rstrip() != line: errors.append(f'{file}:{number}: trailing whitespace')
+        for target in re.findall(r'(?<!!)\[[^]]+\]\(([^)]+)\)', line):
+            if '://' in target or target.startswith(('mailto:', 'plugin:')): continue
+            path, _, anchor = target.partition('#')
+            dest = (file.parent / path).resolve() if path else file.resolve()
+            links += 1
+            if not dest.exists(): errors.append(f'{file}:{number}: missing {target}'); continue
+            if anchor:
+                anchors += 1
+                headings = [re.sub(r'[^\w\- ]', '', h.lower()).strip().replace(' ', '-') for h in re.findall(r'^#{1,6}\s+(.+)$', dest.read_text(), re.M)]
+                if anchor not in headings: errors.append(f'{file}:{number}: missing anchor {target}')
+print(f'{len(files)} files, {links} local links, {anchors} anchors, {len(errors)} errors')
+for error in errors: print(error)
+sys.exit(bool(errors))
+PY
+```
+
+It exited 0: four files, 72 local links, zero anchors and zero errors. The
+new untracked documents were included in the final-newline and trailing-space
+check. The exact plan-consistency command was:
+
+```sh
+python3 - <<'PY'
+from pathlib import Path
+import re, sys
+plan = Path('PLANS.md').read_text()
+rows = [(int(i), state) for i, state in re.findall(r'^\|\s*(\d+)\s*\|[^\n]*?\|\s*(accepted|retired|pending|in_progress|in_review|needs_changes|blocked)\s*\|$', plan, re.M)]
+errors = []
+if [i for i, _ in rows] != list(range(1, 28)): errors.append('register numbering')
+states = dict(rows)
+if states.get(18) != 'accepted' or states.get(19) != 'accepted' or any(states.get(i) != 'pending' for i in range(20, 28)): errors.append('register states')
+record = plan.split('### Milestone 19 —', 1)[1].split('### Milestone 20 —', 1)[0]
+if 'Status: accepted' not in record or any(f'M19.{i} |' not in record for i in (1, 2, 3)): errors.append('M19 record/tasks')
+resume = plan.split('## Current progress and resume point', 1)[1].split('## Plan maintenance', 1)[0]
+if 'M19 is accepted' not in resume or 'Stop after M19' not in resume: errors.append('resume point')
+for target in set(re.findall(r'cargo test --locked --test ([a-z_]+)', plan.split('### Milestone 20 —', 1)[1].split('## Current progress and resume point', 1)[0])):
+    if not Path(f'tests/{target}.rs').exists(): errors.append(f'missing test target {target}')
+if "prepared_destination's six-element tuple" not in plan: errors.append('tuple arity')
+print(f'{len(rows)} register IDs, M19 tasks/status/resume, future test targets and tuple: {len(errors)} errors')
+for error in errors: print(error)
+sys.exit(bool(errors))
+PY
+```
+
+It exited 0: 27 ordered register IDs and no status, task, target or tuple
+errors. `git diff --check` exited 0. The coordinator also inspected factual
+claims and the final changed-file set; the independent reviewer compared
+the migration contract with production and test source. Rust formatting,
+Clippy, tests, release build, Alpine Testcontainers and disposable-VM checks
+were not required for documentation-only M19 and were not run. No production
+or live WireGuard access occurred.
+