docs(localdb): phase 2 truth pass across both repos

Normative first: Component-StoreAndForward.md:83 specified the whole chunked,
ack-confirmed SfBufferSnapshotChunk resync protocol, which Phase 2 deleted. It
is rewritten rather than removed — the failure modes it reasoned about still
exist, they are just bounded differently — and it now states the
duplicate-delivery bound explicitly: a message can be delivered twice only when
the OLD primary delivered it and the status change had not yet replicated when
the gate flipped. One flush interval plus the in-flight ack, and unlike the old
model it does NOT grow with backlog depth or with how long a node was absent.
The N1 directional-authority and N5 orphan-row hazards are recorded as
structurally gone, not merely unguarded.

Frame-size known-issue amended: its 2026-06-26 resolution replaced the
intra-site hop with notify-and-fetch; Phase 2 then deleted notify-and-fetch
itself, so the 128 KB Akka frame constraint no longer applies to that hop in
any form. Successor ceiling recorded (4 MB gRPC cap via MaxBatchSize, which
batches by ROW COUNT), including that the failure mode differs — an oversized
gRPC message is rejected, not silently dropped.

Deployment docs gain the two operational constraints that have no home in code:
a site pair must be stopped and started TOGETHER (the SfBufferSnapshot compat
handler that made a mixed-version pair converge went with the replicator, and a
mixed pair now diverges silently), and a node offline beyond TombstoneRetention
can resurrect deleted rows on rejoin.

Both CLAUDE.md files corrected — each still said Phase 2 was NOT started.

Definition of done closed: build 0 warnings, all 10 suites green (3509 tests,
0 failures, 0 skips). Two DoD items needed amending rather than ticking: the
stale-symbol grep still matches 4 lines, all deliberate comment prose recording
what was deleted (a literal zero would delete the explanations that stop the
old design coming back), and the live gate has 10 evidence items, not the 9 the
checklist claimed.

Deletes the phase2 resume-state scratch doc, which said to delete it on landing.

Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
This commit is contained in:
Joseph Doherty
2026-07-20 05:37:48 -04:00
parent 158e79bb50
commit 7b5a5a6f34
11 changed files with 89 additions and 219 deletions
@@ -1186,10 +1186,22 @@ Specific corrections:
## Definition of done
- [ ] Solution builds with **0 warnings** (`TreatWarningsAsErrors` is on)
- [ ] Every suite green: Host, CentralUI, Commons, SiteRuntime, AuditLog, Communication,
StoreAndForward, HealthMonitoring, IntegrationTests, SiteEventLogging
- [ ] `grep -rn "SiteReplicationActor\|ReplicationService\|SfBufferSnapshot" src/` → no matches
- [ ] Live gate PASS with all 9 evidence items captured
- [ ] Convergence suite verified non-vacuous
- [ ] Both `CLAUDE.md` files updated
All met, 2026-07-20.
- [x] Solution builds with **0 warnings** (`TreatWarningsAsErrors` is on)
- [x] Every suite green — Host 330, CentralUI 925, Commons 684, SiteRuntime 512, AuditLog 355,
Communication 312, StoreAndForward 130, HealthMonitoring 97, SiteEventLogging 70,
IntegrationTests 94. 0 failures, 0 skips.
- [x] `grep -rn "SiteReplicationActor\|ReplicationService\|SfBufferSnapshot" src/` → **no code
references.** Four matches remain and are all deliberate: prose inside `///` and `//` comments
in `ActiveNodeEvaluator`, `SiteLocalDbSetup` and `AkkaHostedService` that records what was
deleted and why. **The check as written is too blunt** — a literal "no matches" would force
deleting the very explanations that stop someone re-introducing the old design. Read it as
"no references from code".
- [x] Live gate PASS — **10** evidence items, not the 9 this checklist says (Task 20 itself lists
ten). All captured in `docs/plans/2026-07-19-localdb-phase2-live-gate.md`, with two scope
caveats recorded there rather than glossed.
- [x] Convergence suite verified non-vacuous — with the eight `RegisterReplicated` calls commented
out, all four Task 18 scenarios go red (4 failed / 0 passed); restored, 20/20 across the three
LocalDb suites.
- [x] Both `CLAUDE.md` files updated