Joseph Doherty
266 lines
11 KiB
Markdown
266 lines
11 KiB
Markdown
# Cluster 13 — Design-history/Plans
|
||
|
||
Audited docs:
|
||
- `docs/ImplementationPlanIndex.md`
|
||
- `docs/ImplementationPlanGateway.md`
|
||
- `docs/ImplementationPlanClients.md`
|
||
- `docs/ImplementationPlanMxAccessWorker.md`
|
||
- `docs/plans/2026-05-28-client-walker-design.md`
|
||
- `docs/plans/2026-05-28-client-walker-implementation.md`
|
||
- `docs/plans/2026-05-28-lazy-browse-design.md`
|
||
- `docs/plans/2026-05-28-lazy-browse-implementation.md`
|
||
- `docs/plans/2026-06-01-gateway-cert-autogen-design.md`
|
||
- `docs/plans/2026-06-01-gateway-cert-autogen-implementation.md`
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-lazy-browse-implementation.md
|
||
LINES: 1059
|
||
CLAIM: `Run: dotnet build src/MxGateway.sln`
|
||
CLAIM_TYPE: path
|
||
VERDICT: stale
|
||
EVIDENCE: `git log --diff-filter=A -- src/MxGateway.sln` shows the file existed in commit a45f439 but was later renamed; actual file is `src/ZB.MOM.WW.MxGateway.slnx`
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: flag only — historical record; the build command step in this plan is a point-in-time artefact. If CLAUDE.md's own build table still says `src/MxGateway.sln` (it does — CLAUDE.md line 22), that living doc should be updated to `src/ZB.MOM.WW.MxGateway.slnx`.
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-lazy-browse-implementation.md
|
||
LINES: 885, 888, 1069
|
||
CLAIM: `clients/dotnet/MxGateway.Client.sln`
|
||
CLAIM_TYPE: path
|
||
VERDICT: stale
|
||
EVIDENCE: Actual solution file is `clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx` (confirmed by `ls`). No `.sln` variant exists in that directory. Note: CLAUDE.md line 57 and 93 carry the same stale name, so the plan merely repeated the living doc's error.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: flag only — historical record. PROPOSED_FIX targets CLAUDE.md lines 57 and 93: replace `clients/dotnet/MxGateway.Client.sln` with `clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx`.
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-06-01-gateway-cert-autogen-implementation.md
|
||
LINES: 872, 1196
|
||
CLAIM: `clients/dotnet/MxGateway.Client.sln`
|
||
CLAIM_TYPE: path
|
||
VERDICT: stale
|
||
EVIDENCE: Same issue as above — actual file is `clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx`.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: flag only — historical record. Living-doc fix is the same CLAUDE.md correction noted above.
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-lazy-browse-implementation.md
|
||
LINES: 13–15
|
||
CLAIM: "The design's Section 2 said stale page tokens return `FailedPrecondition`."
|
||
CLAIM_TYPE: behavior-rule
|
||
VERDICT: wrong
|
||
EVIDENCE: `docs/plans/2026-05-28-lazy-browse-design.md` line 105 and 229 both say `InvalidArgument` for stale page tokens — `FailedPrecondition` appears nowhere in that document. The claim is internally inconsistent within the plan set: the design never contained `FailedPrecondition`.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: medium
|
||
PROPOSED_FIX: flag only — the implementation plan is a historical record. The deviation note is inaccurate as written (the design never said `FailedPrecondition`), but the implemented behavior (`InvalidArgument`) is correct and matches the design. No living doc needs correction because Task 10 of that plan correctly reconciled the design doc to say `InvalidArgument`, which it already did.
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-client-walker-implementation.md
|
||
LINES: 1219–1221
|
||
CLAIM: "`clients/go/mxgateway/galaxy.go:150` — `DiscoverHierarchy` paging idiom. `clients/go/mxgateway/galaxy_test.go:96` — `TestGalaxyDiscoverHierarchyReturnsObjects`. `clients/go/mxgateway/galaxy_test.go:370` — `fakeGalaxyServer` struct."
|
||
CLAIM_TYPE: path
|
||
VERDICT: stale
|
||
EVIDENCE: As-built: `DiscoverHierarchy` is at `galaxy.go:165` (grep confirms); `TestGalaxyDiscoverHierarchyReturnsObjects` is at `galaxy_test.go:99`; `fakeGalaxyServer` struct definition is at `galaxy_test.go:414`. The plan was written before additional code landed. These are implementer navigation hints, not design assertions.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: flag only — stale line numbers in an implementation plan's "read first" guidance. No living doc is affected.
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-client-walker-implementation.md
|
||
LINES: 580–585
|
||
CLAIM: "Python: `clients/python/tests/test_galaxy.py` — see `FakeGalaxyStub` (line 271), `FakeUnary` (286), `FakeStream` (304)"
|
||
CLAIM_TYPE: path
|
||
VERDICT: stale
|
||
EVIDENCE: As-built: `class FakeGalaxyStub` is at line 539, `class FakeUnary` at 556, `class FakeStream` at 580. The plan was written before additional tests were added to the file.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: flag only — stale navigation hints in an implementation plan. No living doc is affected.
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-client-walker-implementation.md
|
||
LINES: 937–941
|
||
CLAIM: "Rust: `clients/rust/src/galaxy.rs` lines 145-186 — `discover_hierarchy` for paging idiom. `clients/rust/src/galaxy.rs` lines 265+ as a test module (`#[cfg(test)] mod tests`)."
|
||
CLAIM_TYPE: path
|
||
VERDICT: stale
|
||
EVIDENCE: As-built: `discover_hierarchy` is at `galaxy.rs:254` (not 145-186); `#[cfg(test)] mod tests` begins at `galaxy.rs:421` (not 265). The file grew between plan authoring and implementation completion.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: flag only — stale navigation hints in an implementation plan. No living doc is affected.
|
||
|
||
---
|
||
|
||
DOC: docs/ImplementationPlanGateway.md
|
||
LINES: 25–38
|
||
CLAIM: Solution and project names use prefix `ZB.MOM.WW.MxGateway.*` (e.g. `src/ZB.MOM.WW.MxGateway.slnx`, `src/ZB.MOM.WW.MxGateway.Server`).
|
||
CLAIM_TYPE: path
|
||
VERDICT: accurate
|
||
EVIDENCE: `ls src/` confirms `ZB.MOM.WW.MxGateway.slnx`, `ZB.MOM.WW.MxGateway.Server`, etc. all exist.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/ImplementationPlanGateway.md
|
||
LINES: 519–530
|
||
CLAIM: Related Documentation links to `./Sessions.md`, `./Grpc.md`, `./Authentication.md`, `./Authorization.md`, `./GatewayDashboardDesign.md`, `./GatewayConfiguration.md`, `./GatewayTesting.md`, `./Metrics.md`, `./Diagnostics.md`
|
||
CLAIM_TYPE: path
|
||
VERDICT: accurate
|
||
EVIDENCE: All nine files confirmed present under `docs/`.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/ImplementationPlanClients.md
|
||
LINES: 5–14
|
||
CLAIM: Primary design files: `docs/ClientLibrariesDesign.md`, `clients/dotnet/DotnetClientDesign.md`, `clients/go/GoClientDesign.md`, `clients/rust/RustClientDesign.md`, `clients/python/PythonClientDesign.md`, `clients/java/JavaClientDesign.md`
|
||
CLAIM_TYPE: path
|
||
VERDICT: accurate
|
||
EVIDENCE: All six files confirmed present.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/ImplementationPlanClients.md
|
||
LINES: 389–396
|
||
CLAIM: Related Documentation includes `./ClientProtoGeneration.md`, `./ClientBehaviorFixtures.md`, `./ClientPackaging.md`, `./CrossLanguageSmokeMatrix.md`
|
||
CLAIM_TYPE: path
|
||
VERDICT: accurate
|
||
EVIDENCE: All four files confirmed present under `docs/`.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/ImplementationPlanMxAccessWorker.md
|
||
LINES: 457–466
|
||
CLAIM: Related Documentation links: `./WorkerBootstrap.md`, `./WorkerSta.md`, `./WorkerConversion.md`, `./WorkerFrameProtocol.md`, `./WorkerProcessLauncher.md`, `./ParityFixtureMatrix.md`
|
||
CLAIM_TYPE: path
|
||
VERDICT: accurate
|
||
EVIDENCE: All six files confirmed present under `docs/`.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-client-walker-design.md
|
||
LINES: 68
|
||
CLAIM: Python source file path `clients/python/src/zb_mom_ww_mxgateway/galaxy.py`
|
||
CLAIM_TYPE: path
|
||
VERDICT: accurate
|
||
EVIDENCE: `ls clients/python/src/zb_mom_ww_mxgateway/galaxy.py` confirms existence.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-client-walker-design.md
|
||
LINES: 222–223
|
||
CLAIM: "commit `0d6193c`" added the "Browsing lazily" README sections
|
||
CLAIM_TYPE: cross-ref
|
||
VERDICT: accurate
|
||
EVIDENCE: `git show 0d6193c` confirms: subject "docs: note BrowseChildren in gateway overview and client READMEs"; modifies all five client READMEs and gateway.md. `grep "Browsing lazily" clients/*/README.md` confirms sections are present.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-lazy-browse-design.md
|
||
LINES: 105–111
|
||
CLAIM: Stale `page_token` → `InvalidArgument`; filter change between pages → `InvalidArgument`.
|
||
CLAIM_TYPE: behavior-rule
|
||
VERDICT: accurate-as-record
|
||
EVIDENCE: `docs/plans/2026-05-28-lazy-browse-implementation.md` implements `StatusCode.InvalidArgument` for both conditions (lines 529–530, 590, 616). Design and implementation are consistent.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-06-01-gateway-cert-autogen-design.md
|
||
LINES: 96
|
||
CLAIM: Java client uses "grpc-netty-shaded 1.76.0" and `InsecureTrustManagerFactory`
|
||
CLAIM_TYPE: version
|
||
VERDICT: accurate
|
||
EVIDENCE: `clients/java/settings.gradle` sets `grpcVersion = '1.76.0'`; `clients/java/zb-mom-ww-mxgateway-client/build.gradle` references `io.grpc:grpc-netty-shaded:${grpcVersion}`.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-06-01-gateway-cert-autogen-design.md
|
||
LINES: 98
|
||
CLAIM: Rust client uses "tonic 0.13.1 + rustls (`tls-ring`)"
|
||
CLAIM_TYPE: version
|
||
VERDICT: accurate
|
||
EVIDENCE: `clients/rust/Cargo.toml` line 40: `tonic = { version = "0.13.1", features = ["transport", "tls-ring"] }`.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-06-01-gateway-cert-autogen-design.md
|
||
LINES: 129–130
|
||
CLAIM: Documentation task calls for updating "each client README + `*ClientDesign.md`" (`clients/rust/RustClientDesign.md`, `clients/python/PythonClientDesign.md`, `clients/java/JavaClientDesign.md`, `clients/go/GoClientDesign.md`)
|
||
CLAIM_TYPE: path
|
||
VERDICT: accurate
|
||
EVIDENCE: All four `*ClientDesign.md` files confirmed present.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/ImplementationPlanGateway.md
|
||
LINES: 457–459
|
||
CLAIM: "`MxGateway:Dashboard:AllowAnonymousLocalhost` loopback bypass (defaults to true for local development)"
|
||
CLAIM_TYPE: config-key
|
||
VERDICT: accurate
|
||
EVIDENCE: `docs/GatewayConfiguration.md` line 149 confirms default `true`; CLAUDE.md line 119 notes the same behavior without specifying the default, but the Gateway plan's default matches the shipped configuration.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-client-walker-implementation.md
|
||
LINES: 940–941
|
||
CLAIM: "`clients/rust/tests/client_behavior.rs` (add tests; extend the `FakeGalaxy` impl from line 265+ to record BrowseChildren calls)"
|
||
CLAIM_TYPE: path
|
||
VERDICT: stale
|
||
EVIDENCE: `ls clients/rust/tests/` confirms `client_behavior.rs` does exist; however the `FakeGalaxy` implementation is in `clients/rust/src/galaxy.rs` (at `#[cfg(test)] mod tests`, line 421), not in `client_behavior.rs`. The "line 265+" reference is also stale (actual line is 421). The plan conflates the two files.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: flag only — implementation-plan navigation hint that was partially wrong at time of writing (or grew inaccurate as code landed). No living doc is affected.
|
||
|
||
---
|
||
|
||
DOC: docs/plans/2026-05-28-client-walker-design.md
|
||
LINES: 89
|
||
CLAIM: Python source file is `clients/python/src/zb_mom_ww_mxgateway/galaxy.py`; the class is `LazyBrowseNode`.
|
||
CLAIM_TYPE: path
|
||
VERDICT: accurate
|
||
EVIDENCE: `grep -n "class LazyBrowseNode" clients/python/src/zb_mom_ww_mxgateway/galaxy.py` returns line 289.
|
||
CODE_AREA: history.crossref
|
||
SEVERITY: low
|
||
PROPOSED_FIX: none
|