Joseph Doherty
b64857c8d6
Task 14. A GATE document, not an implementation plan - the plan explicitly wants Phase 2 planned against post-Phase-1 reality, which means after this record exists rather than from the original design alone. Records what Phase 1 actually established (ordering constraints, where registration lives and why, the fail-closed interceptor, the silent meter allowlist), what must be ported before anything is deleted (both bespoke replicator test files, treated as specifications, plus the accepted N5 bounded-duplicate race), and why Phase 2 is a harder risk class than Phase 1: it REPLACES a working mechanism rather than adding one where none existed, sf_messages has external side effects, config tables drive deployment, there is no dual-mechanism period, and the migration is real this time rather than the usual no-op. The most important line is an open question, not an answer: choosing MaxOplogRows / MaxOplogAge / snapshot-resync thresholds for sf_messages write rates needs a Phase-1 rig SOAK that has not been run. The live gate proved correctness, not steady-state behaviour over time. Phase 2 should not be planned without it. tasks.json finalized: all 15 tasks completed, every deviation from the plan recorded with its reason. Claude-Session: https://claude.ai/code/session_01BL2Vu1ESDQ9SCN4gVKkdts
195 lines
9.1 KiB
JSON
195 lines
9.1 KiB
JSON
{
|
|
"planPath": "docs/plans/2026-07-19-localdb-adoption-phase1.md",
|
|
"execution": {
|
|
"mode": "parallel-waves",
|
|
"implementerModel": "opus",
|
|
"isolation": "worktree",
|
|
"branch": "feat/localdb-phase1",
|
|
"note": "Dispatch every unblocked task concurrently (waves in the plan header). Parallel implementers MUST use worktree isolation - concurrent git in one worktree races destructively."
|
|
},
|
|
"amendments": [
|
|
{
|
|
"date": "2026-07-19",
|
|
"by": "execution review",
|
|
"change": "Task 5 split into 5a (id 5, writer) and 5b (id 15, read path). Code recon found the integer site_events.id load-bearing in the keyset cursor (EventLogQueryService:70,141,153), the storage-cap purge (EventLogPurgeService:164), and long-typed DTOs crossing the site<->central Akka boundary (EventLogEntry.Id, both ContinuationTokens) - none of which were in the original Task 5 file set. 5b is high-risk. Task 10 gains a blockedBy on 15."
|
|
},
|
|
{
|
|
"date": "2026-07-19",
|
|
"by": "execution",
|
|
"change": "Task 2 in isolation left the production writer broken (site_events.id NOT NULL, nothing minting it) - 40 tests red. Per the plan's own 'one PR-sized push' guidance, 5a's GUID minting and all of 5b landed together with Task 2 in commit 727fa48c. Task 5a remains OPEN for its other half: the ILocalDb.CreateConnection() swap, which still needs Task 3."
|
|
}
|
|
],
|
|
"prerequisites": [
|
|
{
|
|
"commit": "4715f2f9",
|
|
"what": "gRPC 2.71.0 -> 2.76.0 + Protobuf 3.34.1. Forced by LocalDb.Replication 0.1.0's nuspec floor; restore fails NU1605 below it. Directory.Packages.props had deferred this bump to 'its own reviewed commit' - honored."
|
|
},
|
|
{
|
|
"commit": "f056b67e",
|
|
"what": "AngleSharp GHSA-pgww-w46g-26qg scoped suppression in CentralUI.Tests (supersedes the wrong pin in ecf6b628). Pre-existing: the solution build was RED on clean main, making every task's verification gate meaningless. No patched-and-working version exists upstream - 1.5.x breaks bunit at runtime, and bunit 2.7.2 still resolves vulnerable 1.4.0."
|
|
}
|
|
],
|
|
"tasks": [
|
|
{
|
|
"id": 1,
|
|
"subject": "Task 1: Add LocalDb packages to the build",
|
|
"status": "completed",
|
|
"commit": "7370b331"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"subject": "Task 2: Shared schema helpers (tracking + events, GUID PK)",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
1
|
|
],
|
|
"commit": "727fa48c"
|
|
},
|
|
{
|
|
"id": 3,
|
|
"subject": "Task 3: Register LocalDb in the site composition root",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
2
|
|
],
|
|
"commit": "2977e6c4",
|
|
"note": "LocalDb:Path added to 10 configs (8 site nodes incl. docker-env2 site-x, dev template, wonder prod sample) - it is REQUIRED via ValidateOnStart, so any site config missing it fails startup."
|
|
},
|
|
{
|
|
"id": 4,
|
|
"subject": "Task 4: Rewire OperationTrackingStore onto ILocalDb connections",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
3
|
|
],
|
|
"commit": "0b5e9b44",
|
|
"note": "Ctor takes ILocalDb, not IOptions<OperationTrackingOptions>; both ad-hoc reader paths switched too and their OpenAsync calls removed (CreateConnection returns an OPEN connection). Three DI fixtures needed LocalDb:Path added because resolving IOperationTrackingStore now forces ILocalDb construction."
|
|
},
|
|
{
|
|
"id": 5,
|
|
"subject": "Task 5a: Rewire SiteEventLogger onto ILocalDb + mint GUID ids",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
3
|
|
],
|
|
"commit": "727fa48c + 0d8a80aa",
|
|
"note": "GUID minting landed early with Task 2 (727fa48c) to avoid committing a writer that violated site_events.id NOT NULL. The ILocalDb.CreateConnection() swap is 0d8a80aa. connectionStringOverride DELETED, not preserved: site_events is replicated, so a raw connection lacks zb_hlc_next() and fails closed."
|
|
},
|
|
{
|
|
"id": 15,
|
|
"subject": "Task 5b: Migrate the event-log read path off integer ids",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
5
|
|
],
|
|
"commit": "727fa48c"
|
|
},
|
|
{
|
|
"id": 6,
|
|
"subject": "Task 6: One-time legacy data migrator",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
4,
|
|
5
|
|
],
|
|
"commit": "98b94771",
|
|
"note": "Runs AFTER RegisterReplicated (pinned by an oplog assertion). Deterministic mig-{NodeName}-{legacyId} event ids, not fresh GUIDs, so a crash between commit and rename cannot duplicate. DEVIATION: sync transaction on a CreateConnection() connection instead of BeginTransactionAsync - OnReady is a synchronous Action<ILocalDb>."
|
|
},
|
|
{
|
|
"id": 7,
|
|
"subject": "Task 7: Replication registration + sync endpoint (default OFF)",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
3
|
|
],
|
|
"commit": "a560e9ea",
|
|
"note": "DEVIATION: AddZbLocalDbReplication moved from Program.cs (where the plan put it) into SiteServiceRegistration, because the composition-root tests build that graph and not Program.cs - in Program.cs a missing registration would still show green. MapZbLocalDbSync stays in Program.cs (needs the WebApplication). Endpoint is UNAUTHENTICATED until Task 8; no config in this repo sets a peer."
|
|
},
|
|
{
|
|
"id": 8,
|
|
"subject": "Task 8: Bearer auth interceptor for the sync endpoint",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
7
|
|
],
|
|
"commit": "59c69519",
|
|
"note": "Fail-closed: no configured ApiKey rejects ALL sync streams. All four handler shapes gated, not just unary (the real RPC is a duplex stream). DEVIATION: Grpc.Core.Testing does not exist on grpc-dotnet; hand-rolled FakeServerCallContext instead of adding the retired native package."
|
|
},
|
|
{
|
|
"id": 9,
|
|
"subject": "Task 9: Surface ISyncStatus as site health signal",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
7
|
|
],
|
|
"commit": "59c69519",
|
|
"note": "Additive init properties on SiteHealthReport so the Akka DTO ctor is untouched. Both fields nullable: null = no data, false/0 = a real reading (which is the healthy default-OFF state). Collector stores one tuple, read once, so a torn read cannot pair fresh Connected with stale backlog."
|
|
},
|
|
{
|
|
"id": 10,
|
|
"subject": "Task 10: Two-node in-process convergence test",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
6,
|
|
8,
|
|
15
|
|
],
|
|
"commit": "3c395d79",
|
|
"note": "5 scenarios over real loopback gRPC + the real interceptor, initialized via SiteLocalDbSetup.OnReady. Verified NON-vacuous: mismatching the two ApiKeys turns all 5 red with 2m30s of timeouts."
|
|
},
|
|
{
|
|
"id": 11,
|
|
"subject": "Task 11: Docker rig enablement (site-a pair)",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
8
|
|
],
|
|
"commit": "(with Task 11 commit)",
|
|
"note": "site-a replicated, site-b/site-c deliberately not, so default-OFF is proven side-by-side on one rig."
|
|
},
|
|
{
|
|
"id": 12,
|
|
"subject": "Task 12: Live gate on the docker rig",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
9,
|
|
10,
|
|
11
|
|
],
|
|
"commit": "95c108f1",
|
|
"note": "PASS. Found one REAL defect: ZbTelemetryOptions.Meters is a silent allowlist, so localdb_* was absent from /metrics - the plan's 'flows through automatically' claim was wrong. Fixed + pinned. Evidence: identical row_version/HLC/originating node_id across the pair, 0 dead letters, oplog drained, site failover + rejoin catch-up, localdb_* scraped, site-b inert. NOTE: docker/failover-drill.sh targets CENTRAL nodes and does NOT exercise the site-pair claim; the site flip was run directly."
|
|
},
|
|
{
|
|
"id": 13,
|
|
"subject": "Task 13: Documentation truth pass",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
12
|
|
],
|
|
"commit": "(docs commit)",
|
|
"note": "Both CLAUDE.md files + the false 'starts a fresh log' XML doc + the two now-migration-only option properties."
|
|
},
|
|
{
|
|
"id": 14,
|
|
"subject": "Task 14: Phase 2 gate - plan the bespoke-replicator migration",
|
|
"status": "completed",
|
|
"blockedBy": [
|
|
12
|
|
],
|
|
"commit": "(gate commit)",
|
|
"note": "Gate document only, per the plan - Phase 2 gets its own implementation plan. docs/plans/2026-07-19-localdb-phase2-gate.md. KEY FINDING: the rig SOAK that Phase 2's oplog-cap tuning needs has NOT been run; the live gate proved correctness, not steady-state behaviour."
|
|
}
|
|
],
|
|
"knownFlakes": [
|
|
{
|
|
"test": "SiteRuntime.Tests InstanceActorChildAttributeRaceTests.ChildActors_AreSeededFromAnIsolatedCopy_NotTheLiveAttributesDictionary",
|
|
"note": "Intermittent ActorNotFoundException under full-suite load; passes in isolation and in most full runs. Pre-existing, unrelated to LocalDb. Worth its own issue."
|
|
},
|
|
{
|
|
"test": "AuditLog.Tests ParentExecutionIdCorrelationTests.InboundRoutedRun_AllRoutedRows_CarryInboundExecutionId_AsParentExecutionId",
|
|
"note": "Cold-MSSQL-fixture timing: ~91s and AwaitAssert-times-out on a cold fixture, ~1s and passes warm. Baselined against a stashed tree to confirm it is not a LocalDb regression."
|
|
}
|
|
],
|
|
"lastUpdated": "2026-07-19",
|
|
"phase1Status": "COMPLETE - all 15 tasks done, live gate PASS. Branch feat/localdb-phase1 NOT merged/pushed."
|
|
} |