stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

fix(platform): make topology probe fallback truthful

Browse Source 
Signed-off-by: master <>
This commit is contained in:
master
2026-03-31 23:44:40 +03:00
parent 152c1b1357
commit 0d858ba9d1
13 changed files with 153 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs-archived/implplan/SPRINT_20260331_006_Platform_probe_truthfulness_and_topology_test_hygiene.md Normal file
View File

@@ -0,0 +1,91 @@
# Sprint 006 - Platform Probe Truthfulness And Topology Test Hygiene
## Topic & Scope
- Replace synthetic topology probe health with a truthful fallback so `/api/v2/topology/hosts` stops presenting release-sync timestamps as runtime probe heartbeats.
- Add a focused Web unit-test target for maintained app specs so topology verification can run without compiling stale `src/tests/**` suites.
- Remove topology-slice warning debt that currently obscures verification output: deprecated `allowSignalWrites`, obsolete Vitest 4 config, and `color-mix()` styles that trigger jsdom parse noise in the maintained topology surfaces.
- Working directory: `src/Platform/StellaOps.Platform.WebService/`.
- Cross-module edits allowed for this sprint: `src/Platform/__Tests/StellaOps.Platform.WebService.Tests/`, `src/Web/StellaOps.Web/`, `docs/modules/platform/`, `src/Platform/StellaOps.Platform.WebService/TASKS.md`.
- Expected evidence: targeted Platform test pass, focused Angular/Vitest topology pass, docs updated, archived sprint.
## Dependencies & Concurrency
- Follow-up from archived sprint `docs-archived/implplan/SPRINT_20260331_003_FE_host_ui_and_environment_verification.md`, which exposed synthetic probe status and noisy topology test verification.
- Stale sprint `docs/implplan/SPRINT_20260331_002_BE_host_infrastructure_and_inventory.md` claimed a Signals/runtime-agent integration path that does not exist in the current Platform runtime. This sprint does not implement that missing integration; it makes the current read model truthful and documents the contract gap.
- Safe parallelism: Platform read-model changes and Web test-runner changes are independent after the contract decision is fixed.
## Documentation Prerequisites
- `src/Platform/StellaOps.Platform.WebService/AGENTS.md`
- `src/Web/StellaOps.Web/AGENTS.md`
- `docs/modules/platform/platform-service.md`
- `src/Platform/StellaOps.Platform.WebService/Services/TopologyReadModelService.cs`
- `src/Platform/__Tests/StellaOps.Platform.WebService.Tests/TopologyReadModelEndpointsTests.cs`
## Delivery Tracker
### TASK-001 - Make topology probe status truthful
Status: DONE
Dependency: none
Owners: Developer (BE), Documentation author
Task description:
- Remove the placeholder probe-status heuristic in `TopologyReadModelService` that derives `"active"` from `LastSeenAt` using `ProjectionEpoch.AddMinutes(2)`. That rule is not runtime evidence; it is a release-projection timestamp check and currently marks any modern timestamp as active.
- The replacement behavior for the current runtime boundary is explicit: when no real probe evidence source is wired into the Platform runtime, hosts must return `ProbeStatus = "not_installed"`, `ProbeType = null`, and `ProbeLastHeartbeat = null`.
- Keep the host-level `LastSeenAt` deployment projection intact so release activity remains visible, but stop conflating it with runtime-probe heartbeats.
- Update Platform docs to state that runtime probe evidence is currently absent from the topology read model and that future `"active"` / `"offline"` states require an explicit runtime inventory/heartbeat query contract.
Completion criteria:
- [ ] `/api/v2/topology/hosts` no longer derives probe status from `LastSeenAt`
- [ ] Hosts without explicit runtime evidence return `not_installed` with null probe heartbeat/type
- [ ] Platform endpoint tests assert the truthful fallback contract
- [ ] Platform module docs describe the current limitation and future contract requirement
### TASK-002 - Add a focused Angular test target for maintained topology specs
Status: DONE
Dependency: none
Owners: Developer (FE)
Task description:
- Add a dedicated Angular/Vitest target and TypeScript spec config for the maintained topology spec harness under `src/app/core/testing/**` so topology verification stops compiling unrelated Web specs.
- Provide a package script that exercises the focused target directly so topology verification no longer depends on ad hoc command lines or the legacy test surface.
- The focused target must still support `--include` so individual maintained specs can be run in isolation.
Completion criteria:
- [ ] New focused topology test target exists in `angular.json`
- [ ] New focused topology spec tsconfig scopes compilation to `src/app/core/testing/**/*.spec.ts`
- [ ] Package script exists for the focused target
- [ ] Focused topology specs run without compiling unrelated Web spec suites
### TASK-003 - Remove warning debt from maintained topology verification paths
Status: DONE
Dependency: TASK-002
Owners: Developer (FE)
Task description:
- Remove deprecated `allowSignalWrites` effect options from the maintained topology/reachability surfaces used by the focused topology verification path.
- Update `vitest.codex.config.ts` to a Vitest 4 compatible shape so focused verification stops emitting the `poolOptions` deprecation warning.
- Replace topology-slice `color-mix()` CSS usage that causes jsdom parser warnings in the maintained topology component tests with deterministic styles that preserve the existing UI intent.
Completion criteria:
- [ ] Focused topology verification surfaces no longer use `allowSignalWrites`
- [ ] Focused topology Vitest run no longer emits the `poolOptions` deprecation warning
- [ ] Focused topology Vitest run no longer emits topology `color-mix()` parse warnings
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-31 | Sprint created to convert synthetic probe status into truthful fallback behavior and to isolate maintained topology verification from stale Web test suites. | Planning |
| 2026-03-31 | TASK-001 completed. `/api/v2/topology/hosts` now returns truthful probe fallback fields (`not_installed`, null type, null heartbeat) instead of inferring runtime health from deployment timestamps. Platform service docs updated to document the explicit runtime-evidence contract gap. | Developer (BE) |
| 2026-03-31 | TASK-002 completed. Added topology-only Angular/Vitest target `test-topology` with `tsconfig.spec.topology.json`, allowing `--include` runs against `src/app/core/testing/**` without compiling unrelated Web specs. | Developer (FE) |
| 2026-03-31 | TASK-003 completed. Updated `vitest.codex.config.ts` for Vitest 4, removed deprecated `allowSignalWrites` from focused topology verification surfaces, and replaced topology `color-mix()` usage that was triggering jsdom parser noise in the maintained topology tests. | Developer (FE) |
| 2026-03-31 | Verification completed. `StellaOps.Platform.WebService.Tests.exe -class StellaOps.Platform.WebService.Tests.TopologyReadModelEndpointsTests -parallel none` passed (`4/4`). `npx ng run stellaops-web:test-topology --watch=false --include ...` passed (`3/3`). `npx tsc -p tsconfig.app.json --noEmit` passed. `npx ng build --configuration development` passed with unrelated `NG8113` warnings in non-topology files. | Developer |
## Decisions & Risks
- Decision: this sprint fixes correctness by degrading probe state to `not_installed` until a real runtime evidence source exists. It does not invent another heuristic.
- Decision: the focused Web test target is additive and topology-specific; default `ng test` behavior remains untouched because the broader test suite is already under active churn elsewhere in the repo.
- Risk: topology UI will show more `Not monitored` states after the backend fix. This is intentional and preferable to false verification.
- Risk: a future runtime evidence integration still needs an explicit query contract inside Platform rather than a hidden dependency on foreign persistence or synthetic timestamps.
- Verification note: `dotnet test ... --filter` is ineffective for this Platform test assembly under Microsoft.Testing.Platform (`MTP0001` warns that the filter is ignored), so topology verification used the xUnit v3 assembly runner with a class filter instead.
- Residual risk: topology-focused Vitest runs still emit Angular sanitization warnings from shared HTML-icon rendering outside this sprint's change scope. These warnings are non-fatal and separate from the removed `poolOptions` / `color-mix()` noise.
- Residual risk: `npx ng build --configuration development` still reports unrelated `NG8113` unused-import warnings in [`src/Web/StellaOps.Web/src/app/features/doctor/doctor-dashboard.component.ts`](/C:/dev/New%20folder/git.stella-ops.org/src/Web/StellaOps.Web/src/app/features/doctor/doctor-dashboard.component.ts) and [`src/Web/StellaOps.Web/src/app/features/releases/releases-activity.component.ts`](/C:/dev/New%20folder/git.stella-ops.org/src/Web/StellaOps.Web/src/app/features/releases/releases-activity.component.ts).
## Next Checkpoints
- Implement an explicit Platform runtime-evidence query contract before reintroducing `"active"` or `"offline"` probe states to `/api/v2/topology/hosts`.
- Triage the remaining shared-component sanitization warnings in the topology Vitest run.
- Clean the unrelated `NG8113` warnings so `ng build` returns warning-free for the maintained Web surfaces.