ScadaBridge/docs/plans/2026-07-19-localdb-phase2-gate.md

LocalDb Phase 2 — Gate Document

Status: NOT STARTED. This is the gate, not the plan. Phase 2 work must not begin until an implementation plan is written against the facts below and the open questions in §5 are answered.

Phase 1 live gate: PASS (2026-07-19, docker rig). See the Task 12 commit for evidence.

Phase 2 goal (from the design doc, scadaproj docs/plans/2026-07-19-scadabridge-localdb-design.md §1): move scadabridge.db's config tables and StoreAndForward's sf_messages into the same consolidated LocalDb file, then delete SiteReplicationActor and StoreAndForward's ReplicationService outright. CDC triggers replace hand-shipped ops; the library's snapshot resync replaces the bespoke chunked anti-entropy. The design explicitly chose replace + delete, no dual-mechanism period — recoverable from git.

---

1. What Phase 1 actually established

Facts a Phase 2 plan can rely on, all verified rather than assumed:

• One ILocalDb per site process at LocalDb:Path, required (ValidateOnStart). A site config missing it fails to boot.
• SiteLocalDbSetup.OnReady is the single place tables are created and registered. Ordering is load-bearing: DDL → RegisterReplicated → writes, then the legacy migrator. Rows written before registration are invisible to the peer forever, silently.
• Replication is registered in SiteServiceRegistration (not Program.cs) so the composition-root tests cover it; only MapZbLocalDbSync lives in Program.cs.
• Inbound auth is LocalDbSyncAuthInterceptor, fail-closed, scoped to /localdb_sync.v1.LocalDbSync/, sharing the existing 8083 h2c listener.
• Default-OFF is real and proven side-by-side: rig site-a replicates, site-b/site-c do not.
• ZbTelemetryOptions.Meters is a silent allowlist (SiteServiceRegistration.ObservedMeters).
• Bidirectional sync works with only one node configured as initiator.

2. What Phase 2 must port before deleting anything

The bespoke replicator's tests encode behaviour that the design's CDC replacement must still satisfy. Port the test intents first, delete second — the plan should treat the existing tests as the specification, not as code to be removed alongside the implementation.

• tests/ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests/Actors/SiteReplicationActorTests.cs
• tests/ZB.MOM.WW.ScadaBridge.StoreAndForward.Tests/ReplicationServiceTests.cs

Implementation under deletion:

• src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/SiteReplicationActor.cs
• src/ZB.MOM.WW.ScadaBridge.StoreAndForward/ReplicationService.cs

Known accepted behaviour to carry forward, not silently drop: the N5 bounded-duplicate race the bespoke replicator documents and accepts. A Phase 2 plan must state whether CDC inherits the same bound, a tighter one, or a different failure shape.

3. Substantially harder than Phase 1

Phase 1 moved two tables that nothing replicated before, so the worst case was "no worse than today". Phase 2 replaces a working mechanism, which makes it a different risk class:

• sf_messages is an outbound buffer with side effects. Phase 1's tables are read-mostly records; a store-and-forward row that resurrects or double-delivers sends real traffic to an external system. Park/requeue/remove becoming ordinary captured row updates/deletes needs its own analysis of what LWW does to an in-flight send.
• Config tables drive deployment. A converged-but-wrong config row is a deployed instance behaving incorrectly, not a missing history entry.
• No dual-mechanism period. The chosen posture means the cutover is the test. That raises the bar on the offline convergence suite and the live gate considerably.
• Migration is not a no-op this time. Phase 1's migrator usually finds nothing, because the legacy files sat outside the volume. scadabridge.db and store-and-forward.db are real, populated, on the volume, and actively replicated while the migration runs.

4. Required inputs before writing the plan

1. The design doc §1 Phase 2 and §2 schema/migration sections, re-read against post-Phase-1 reality (several Phase 1 assumptions changed during execution — see the amendments array in 2026-07-19-localdb-adoption-phase1.md.tasks.json).
2. The two test files in §2, read as specifications.
3. Rig soak observations that do not exist yet — see §5.

5. Open questions — answer these first

• Oplog growth and churn under real config/S&F write rates. Phase 1's tables are low-volume; sf_messages is not. MaxOplogRows / MaxOplogAge / snapshot-resync thresholds cannot be chosen from first principles. This needs a Phase-1 rig soak that has not been run. The live gate proved correctness, not steady-state behaviour over time.
• LWW semantics for in-flight store-and-forward sends. What does last-writer-wins do when one node parks a message the other is mid-delivery on?
• Migration-under-load. How does the one-time copy of an actively-replicating scadabridge.db interact with the bespoke replicator still running during cutover?
• Rollback story. With no dual-mechanism period, what is the recovery path if the cutover fails in production — beyond "revert the commit"?
• Does the consolidated file stay appropriate? One-DB-per-process was chosen partly because Phase 1's tables were small. Adding config + S&F changes the size and write profile of that single file.

6. Not in scope (unchanged from the design)

auditlog.db (diverges per node by design — central pulls the union; replicating it would double-forward), the secrets store (has its own answer in Secrets.Replicator.SqlServer hub mode), and central nodes (SQL-Server-first, no LocalDb use case).