texts fixes, search bar fixes, global menu fixes.
This commit is contained in:
master
@@ -74,6 +74,8 @@ The example file ships with working local-dev defaults. For production, change `
|
||||
|
||||
Stella Ops services bind to unique loopback IPs so all can use port 443 without collisions. Add the entries from `devops/compose/hosts.stellaops.local` to your hosts file:
|
||||
|
||||
Runtime URL convention remains `*.stella-ops.local`; `hosts.stellaops.local` is the template file name only.
|
||||
|
||||
- **Windows:** `C:\Windows\System32\drivers\etc\hosts` (run editor as Administrator)
|
||||
- **Linux / macOS:** `sudo sh -c 'cat devops/compose/hosts.stellaops.local >> /etc/hosts'`
|
||||
|
||||
|
||||
@@ -16,15 +16,15 @@
|
||||
| Doctor | 1 | Doctor | in-memory |
|
||||
| EvidenceLocker | 1 | EvidenceLocker | postgres |
|
||||
| ExportCenter | 1 | ExportCenter | postgres |
|
||||
| Findings | 2 | Findings.Ledger, RiskEngine | in-memory, postgres |
|
||||
| Findings | 2 | Findings.Ledger, RiskEngine | postgres (in-memory fallback in RiskEngine test profile) |
|
||||
| Integrations | 1 | Integrations | postgres |
|
||||
| JobEngine | 4 | JobEngine, PacksRegistry, Scheduler, TaskRunner | file-backed, postgres |
|
||||
| JobEngine | 4 | JobEngine, PacksRegistry, Scheduler, TaskRunner | postgres, seed-fs object-store |
|
||||
| Notifier | 1 | Notifier | postgres |
|
||||
| Notify | 1 | Notify | postgres |
|
||||
| Platform | 1 | Platform | postgres |
|
||||
| ReachGraph | 1 | ReachGraph | postgres |
|
||||
| Remediation | 1 | Remediation | postgres |
|
||||
| Replay | 1 | Replay | in-memory |
|
||||
| Replay | 1 | Replay | postgres, seed-fs object-store |
|
||||
| Router | 1 | Gateway | no-persistence |
|
||||
| Scanner | 1 | Scanner | postgres |
|
||||
| Timeline | 2 | Timeline, TimelineIndexer | postgres |
|
||||
@@ -47,18 +47,18 @@
|
||||
| EvidenceLocker | EvidenceLocker | Evidence ingest/scoring, snapshots, bundle download/portable package, verify, legal hold, plus export/verdict/evidence-thread adapters | EvidenceLockerDbContext | src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.WebService/Program.cs; src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.Infrastructure/EfCore/Context/EvidenceLockerDbContext.cs |
|
||||
| ExportCenter | ExportCenter | Endpoints: Attestation, AuditBundle, ExceptionReport, ExportApi (+6 more); routes: audit-bundles, exports, incidents, lineage (+4 more) | ExportCenterDbContext | src/ExportCenter/StellaOps.ExportCenter/StellaOps.ExportCenter.WebService/Program.cs; src/ExportCenter/StellaOps.ExportCenter/StellaOps.ExportCenter.Infrastructure/EfCore/Context/ExportCenterDbContext.cs |
|
||||
| Findings | Findings.Ledger | Endpoints: Backport, EvidenceGraph, FindingSummary, ReachabilityMap (+4 more); routes: findings, scoring | FindingsLedgerDbContext | src/Findings/StellaOps.Findings.Ledger.WebService/Program.cs; src/Findings/StellaOps.Findings.Ledger/EfCore/Context/FindingsLedgerDbContext.cs |
|
||||
| Findings | RiskEngine | Endpoints: ExploitMaturity; routes: exploit-maturity | No service DB; InMemoryRiskScoreResultStore | src/Findings/StellaOps.RiskEngine.WebService/Program.cs; src/Findings/__Libraries/StellaOps.RiskEngine.Infrastructure/Stores/InMemoryRiskScoreResultStore.cs |
|
||||
| Findings | RiskEngine | Endpoints: ExploitMaturity; routes: exploit-maturity | PostgresRiskScoreResultStore (in-memory fallback retained for explicit test profile) | src/Findings/StellaOps.RiskEngine.WebService/Program.cs; src/Findings/__Libraries/StellaOps.RiskEngine.Infrastructure/Stores/PostgresRiskScoreResultStore.cs |
|
||||
| Integrations | Integrations | Endpoints: Integration; routes: integrations | IntegrationDbContext | src/Integrations/StellaOps.Integrations.WebService/Program.cs; src/Integrations/__Libraries/StellaOps.Integrations.Persistence/IntegrationDbContext.cs |
|
||||
| JobEngine | JobEngine | Endpoints: Approval, Audit, CircuitBreaker, Dag (+21 more); routes: approvals, environments, jobengine, metrics (+2 more) | JobEngineDbContext | src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Program.cs; src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Infrastructure/EfCore/Context/JobEngineDbContext.cs |
|
||||
| JobEngine | PacksRegistry | Packs upload/list/content/provenance/manifest/signature, attestations, parity/lifecycle, mirrors sync, compliance summary, offline-seed export | No relational DB; filesystem repositories (packs/parity/lifecycle/audit/attestations/mirrors) | src/JobEngine/StellaOps.PacksRegistry/StellaOps.PacksRegistry.WebService/Program.cs; src/JobEngine/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Infrastructure/FileSystem/FilePackRepository.cs |
|
||||
| JobEngine | PacksRegistry | Packs upload/list/content/provenance/manifest/signature, attestations, parity/lifecycle, mirrors sync, compliance summary, offline-seed export | Postgres metadata/state repositories + seed-fs blob channel (`SeedFsPacksRegistryBlobStore`) | src/JobEngine/StellaOps.PacksRegistry/StellaOps.PacksRegistry.WebService/Program.cs; src/JobEngine/StellaOps.PacksRegistry.__Libraries/StellaOps.PacksRegistry.Persistence/Postgres/BlobStorage/SeedFsPacksRegistryBlobStore.cs |
|
||||
| JobEngine | Scheduler | Endpoints: FailureSignature, Run, Schedule; routes: events, graphs, scheduler | SchedulerDataSource, SchedulerDbContext | src/JobEngine/StellaOps.Scheduler.WebService/Program.cs; src/JobEngine/StellaOps.Scheduler.__Libraries/StellaOps.Scheduler.Persistence/EfCore/Context/SchedulerDbContext.cs |
|
||||
| JobEngine | TaskRunner | Run simulation/execution state/logs/artifacts/approvals/cancel, attestation APIs, incident-mode APIs, SLO breach webhook | No relational DB; filesystem stores for run state/logs/approvals/artifacts | src/JobEngine/StellaOps.TaskRunner/StellaOps.TaskRunner.WebService/Program.cs; src/JobEngine/StellaOps.TaskRunner/StellaOps.TaskRunner.Infrastructure/Execution/FilePackRunStateStore.cs |
|
||||
| JobEngine | TaskRunner | Run simulation/execution state/logs/artifacts/approvals/cancel, attestation APIs, incident-mode APIs, SLO breach webhook | Postgres run state/log/approval stores + seed-fs artifact/provenance payload channel | src/JobEngine/StellaOps.TaskRunner/StellaOps.TaskRunner.WebService/Program.cs; src/JobEngine/StellaOps.TaskRunner.__Libraries/StellaOps.TaskRunner.Persistence/Postgres/Repositories/PostgresPackRunStateStore.cs |
|
||||
| Notifier | Notifier | Endpoints: Escalation, Fallback, Incident, Localization (+10 more); routes: ack, escalation-policies, escalations, fallback (+13 more) | NotifyDataSource, NotifyDbContext | src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Program.cs; src/Notify/__Libraries/StellaOps.Notify.Persistence/EfCore/Context/NotifyDbContext.cs |
|
||||
| Notify | Notify | Rules/channels/templates CRUD, deliveries history, digests, audit trail, lock APIs, internal normalize endpoints | NotifyDataSource, NotifyDbContext | src/Notify/StellaOps.Notify.WebService/Program.cs; src/Notify/__Libraries/StellaOps.Notify.Persistence/EfCore/Context/NotifyDbContext.cs |
|
||||
| Platform | Platform | Endpoints: AdministrationTrustSigningMutation, Analytics, Context, EnvironmentSettings (+19 more); routes: admin, administration, analytics, authority (+26 more) | PlatformDbContext plus read-model access to Authority/Concelier/Excititor/Scheduler/Notify/Policy contexts | src/Platform/StellaOps.Platform.WebService/Program.cs; src/Authority/__Libraries/StellaOps.Authority.Persistence/EfCore/Context/AuthorityDbContext.cs |
|
||||
| Platform | Platform | Endpoints: AdministrationTrustSigningMutation, Analytics, Context, EnvironmentSettings (+19 more); routes: admin, administration, analytics, authority (+26 more) | PlatformDbContext + module-local runtime contracts (`IReleaseControlBundleStore`, `IPlatformContextQuery`); migration-only foreign persistence references are allowlisted | src/Platform/StellaOps.Platform.WebService/Program.cs; src/Platform/StellaOps.Platform.WebService/Services/PlatformContextService.cs |
|
||||
| ReachGraph | ReachGraph | Endpoints: CveMapping, Reachability, ReachGraph | ReachGraphDataSource, ReachGraphDbContext | src/ReachGraph/StellaOps.ReachGraph.WebService/Program.cs; src/__Libraries/StellaOps.ReachGraph.Persistence/EfCore/Context/ReachGraphDbContext.cs |
|
||||
| Remediation | Remediation | Endpoints: RemediationMatch, RemediationRegistry, RemediationSource; routes: remediation | RemediationDataSource, RemediationDbContext | src/Remediation/StellaOps.Remediation.WebService/Program.cs; src/Remediation/StellaOps.Remediation.Persistence/EfCore/Context/RemediationDbContext.cs |
|
||||
| Replay | Replay | Endpoints: PointInTimeQuery, VerdictReplay; routes: pit, replay | No service DB; in-memory feed snapshot blob/index stores | src/Replay/StellaOps.Replay.WebService/Program.cs; src/Replay/StellaOps.Replay.WebService/FeedSnapshotSupport.cs |
|
||||
| Replay | Replay | Endpoints: PointInTimeQuery, VerdictReplay; routes: pit, replay | Postgres snapshot index store + seed-fs snapshot blob store | src/Replay/StellaOps.Replay.WebService/Program.cs; src/Replay/StellaOps.Replay.WebService/FeedSnapshotSupport.cs |
|
||||
| Router | Gateway | Gateway route dispatch pipeline, authz/header enforcement, transport routing, OpenAPI aggregation | No application DB; gateway routing/middleware service | src/Router/StellaOps.Gateway.WebService/Program.cs |
|
||||
| Scanner | Scanner | Endpoints: Actionables, Approval, Baseline, BatchTriage (+43 more); routes: drift, epss, github, hot-lookup (+12 more) | ScannerDbContext + ScannerSourcesDataSource + TriageDbContext (+ AuthorityDbContext path) | src/Scanner/StellaOps.Scanner.WebService/Program.cs; src/Authority/__Libraries/StellaOps.Authority.Persistence/EfCore/Context/AuthorityDbContext.cs |
|
||||
| Timeline | Timeline | Endpoints: Export, Health, Replay, Timeline (+1 more); routes: audit, timeline | EventingDataSource, EventingDbContext, TimelineCoreDataSource, TimelineCoreDbContext | src/Timeline/StellaOps.Timeline.WebService/Program.cs; src/__Libraries/StellaOps.Eventing/EfCore/Context/EventingDbContext.cs |
|
||||
@@ -76,10 +76,10 @@
|
||||
## Policy Gaps (Postgres First, RustFS for Blobs)
|
||||
| Service | Current Runtime Wiring | Compose Signal | Gap | Required Remediation |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| PacksRegistry | File repositories (`src/JobEngine/StellaOps.PacksRegistry/StellaOps.PacksRegistry.WebService/Program.cs` lines 29-34) | Main compose provides `ConnectionStrings__Default` (line 1769); testing compose expects `PACKSREGISTRY__STORAGE__DRIVER=postgres` (line 253) | High | Add storage driver contract; move metadata (pack/parity/lifecycle/mirror/audit) to Postgres; keep pack/provenance/attestation payloads in RustFS/seed-fs blob path. |
|
||||
| TaskRunner | File stores/readers (`src/JobEngine/StellaOps.TaskRunner/StellaOps.TaskRunner.WebService/Program.cs` lines 61,66,71,76) | Main compose provides `ConnectionStrings__Default` (line 1150); testing compose expects `TASKRUNNER__STORAGE__DRIVER=postgres` (line 271) | High | Add Postgres storage driver for run state/logs/approvals; move large artifacts to RustFS/seed-fs blob path; keep deterministic replay semantics. |
|
||||
| RiskEngine | In-memory result store (`src/Findings/StellaOps.RiskEngine.WebService/Program.cs` line 21) | Main compose provides `ConnectionStrings__Default` (line 1048) | Medium-High | Implement Postgres-backed result store with deterministic ordering/query semantics; keep in-memory only for explicit test profile. |
|
||||
| Replay | In-memory snapshot blob/index stores (`src/Replay/StellaOps.Replay.WebService/Program.cs` lines 61-62) | Main compose provides `ConnectionStrings__Default` (line 2037) | Medium-High | Persist replay snapshot index/state in Postgres; move snapshot blobs to RustFS/seed-fs object path. |
|
||||
| PacksRegistry | `Storage:Driver=postgres` plus Postgres repositories for metadata/state; `Storage:ObjectStore:Driver=seed-fs` for blob payloads; startup rejects `rustfs` and unknown object-store drivers. | Main/testing compose provide Postgres connection and service storage-driver keys. | Closed (Sprint 312 + 2026-03-05 hardening) | Keep contract seed-fs-only until a dedicated RustFS adapter sprint lands with parity tests. |
|
||||
| TaskRunner | `Storage:Driver=postgres` plus Postgres repositories for state/log/approval; `Storage:ObjectStore:Driver=seed-fs` for artifact payloads; startup rejects `rustfs` and unknown object-store drivers in WebService and Worker. | Main/testing compose provide Postgres connection and service storage-driver keys. | Closed (Sprint 312 + 2026-03-05 hardening) | Keep contract seed-fs-only until a dedicated RustFS adapter sprint lands with parity tests. |
|
||||
| RiskEngine | Postgres-backed result store (`PostgresRiskScoreResultStore`) with explicit in-memory fallback for tests. | Main compose provides `ConnectionStrings__Default` (line 1048). | Closed (Sprint 312) | Keep in-memory fallback scoped to explicit test profile only; maintain parity tests for Postgres path. |
|
||||
| Replay | `Storage:Driver=postgres` for snapshot index and `Storage:ObjectStore:Driver=seed-fs` for snapshot blobs; startup rejects `rustfs` and unknown object-store values. | Main compose provides `ConnectionStrings__Default` and storage driver keys for replay. | Closed (Sprint 312 + 2026-03-05 hardening) | Keep contract seed-fs-only until a dedicated RustFS adapter sprint lands with deterministic parity tests. |
|
||||
| OpsMemory | Postgres store exists but connection key is `ConnectionStrings:OpsMemory` with localhost fallback (`src/AdvisoryAI/StellaOps.OpsMemory.WebService/Program.cs` lines 19-20) | Main compose sets only `ConnectionStrings__Default` (line 1537) | Medium | Accept `ConnectionStrings:Default` as primary fallback or map explicit `ConnectionStrings:OpsMemory` in compose; remove localhost fallback in non-dev runtime. |
|
||||
| Scanner | Postgres + RustFS split already configured (`src/Scanner` + compose lines 652-659/720-725) | Explicitly aligned in compose | None | Use as reference implementation for storage-driver conventions. |
|
||||
|
||||
|
||||
@@ -1,104 +0,0 @@
|
||||
# Sprint 20260305-002 - JobEngine Storage Completion (PacksRegistry and TaskRunner)
|
||||
|
||||
## Topic & Scope
|
||||
- Complete the remaining delivery gap for Point 1: Postgres-first metadata/state with production-ready object-store blob handling for `PacksRegistry` and `TaskRunner`.
|
||||
- Preserve deterministic replay semantics while removing non-dev ambiguity in storage-driver behavior.
|
||||
- Align runtime wiring, compose overlays, and tests so storage mode is explicit and verifiable.
|
||||
- Working directory: `src/JobEngine`.
|
||||
- Expected evidence: targeted persistence/integration test passes, compose config validation output, and updated JobEngine/platform architecture docs.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on shared storage contract documented in `docs/modules/platform/architecture.md`.
|
||||
- Can run in parallel with Replay, Remediation, and Platform boundary sprints.
|
||||
- Documentation cleanup sprint (`SPRINT_20260305_006_DOCS_webservice_catalog_and_domain_consistency.md`) depends on final runtime behavior from this sprint.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/modules/platform/architecture.md`
|
||||
- `docs/modules/jobengine/architecture.md`
|
||||
- `src/JobEngine/StellaOps.PacksRegistry/StellaOps.PacksRegistry.WebService/Program.cs`
|
||||
- `src/JobEngine/StellaOps.TaskRunner/StellaOps.TaskRunner.WebService/Program.cs`
|
||||
- `docs/implplan/CONSOLIDATION_WEBSERVICE_FUNCTION_DB_MATRIX_20260305.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### JOBENG-STOR-001 - Reconcile declared driver contract with actual runtime behavior
|
||||
Status: TODO
|
||||
Dependency: none
|
||||
Owners: Project Manager, Implementer
|
||||
Task description:
|
||||
- Produce a precise behavior matrix for `Storage:Driver` and `Storage:ObjectStore:Driver` for both services.
|
||||
- Confirm and document current mismatch points (for example, drivers accepted by validation but not backed by concrete adapter behavior).
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Behavior matrix committed under module docs with config keys, defaults, and startup fail-fast rules.
|
||||
- [ ] Every accepted driver value is either fully implemented or explicitly rejected with deterministic startup failure.
|
||||
|
||||
### JOBENG-STOR-002 - Implement production RustFS object-store adapters for blob payloads
|
||||
Status: TODO
|
||||
Dependency: JOBENG-STOR-001
|
||||
Owners: Implementer, Test Automation
|
||||
Task description:
|
||||
- Implement and wire RustFS/S3-compatible blob adapters for:
|
||||
- `PacksRegistry` pack/provenance/attestation payload channels.
|
||||
- `TaskRunner` run artifact payload channel.
|
||||
- Preserve existing Postgres-backed metadata stores and deterministic ordering semantics.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] `Storage:ObjectStore:Driver=rustfs` uses concrete RustFS adapter implementations in both services.
|
||||
- [ ] Existing `seed-fs` behavior remains supported for local/offline deterministic workflows.
|
||||
- [ ] Non-development startup fails when RustFS is configured without required endpoint/credentials settings.
|
||||
|
||||
### JOBENG-STOR-003 - Harden non-development startup behavior and fallback policy
|
||||
Status: TODO
|
||||
Dependency: JOBENG-STOR-002
|
||||
Owners: Implementer
|
||||
Task description:
|
||||
- Remove silent non-dev behavior drift by enforcing explicit fail-fast for missing Postgres/object-store configuration.
|
||||
- Ensure development-only fallback behavior is intentional, documented, and test-covered.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Non-development runtime has no implicit filesystem fallback for stores expected to be Postgres-backed.
|
||||
- [ ] Error messages are actionable and identify missing config keys.
|
||||
- [ ] Startup behavior is covered by automated tests for success/failure modes.
|
||||
|
||||
### JOBENG-STOR-004 - Expand deterministic storage tests across drivers
|
||||
Status: TODO
|
||||
Dependency: JOBENG-STOR-002
|
||||
Owners: Test Automation
|
||||
Task description:
|
||||
- Add targeted tests that validate parity across `postgres + seed-fs` and `postgres + rustfs`.
|
||||
- Include replay-critical assertions for stable ordering, digest consistency, and tenant isolation.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Targeted test projects include both happy-path and misconfiguration-path assertions.
|
||||
- [ ] Evidence captures command output and test counts for each driver profile.
|
||||
- [ ] No regression in existing persistence tests for Postgres repositories.
|
||||
|
||||
### JOBENG-STOR-005 - Update architecture and operations docs for final storage contract
|
||||
Status: TODO
|
||||
Dependency: JOBENG-STOR-003
|
||||
Owners: Documentation author, Implementer
|
||||
Task description:
|
||||
- Update JobEngine and platform storage docs with final runtime contract, config examples, and migration notes.
|
||||
- Record decisions and residual risks in sprint log and link to docs changed.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] `docs/modules/jobengine/architecture.md` and `docs/modules/platform/architecture.md` reflect final behavior.
|
||||
- [ ] Compose/ops guidance references valid config keys for both services.
|
||||
- [ ] Sprint Decisions & Risks includes links to all updated docs.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-05 | Sprint created from architecture review; points 1 and 2 were partially implemented and require completion/hardening work. | Project Manager |
|
||||
|
||||
## Decisions & Risks
|
||||
- Current code already wires Postgres state stores for TaskRunner and Postgres persistence extension for PacksRegistry, but remaining object-store adapter parity and fallback hardening are unresolved.
|
||||
- `PacksRegistry` currently carries an explicit RustFS-not-implemented guard in runtime contract paths; this blocks full completion of Point 1 in production modes.
|
||||
- `TaskRunner` currently accepts object-store driver values while artifact reading remains filesystem-root based; implementation parity must be enforced to avoid config drift.
|
||||
- Mitigation: complete adapter implementation and add startup contract tests before documentation sprint declares Point 1 as complete.
|
||||
|
||||
## Next Checkpoints
|
||||
- Driver matrix and gap report complete.
|
||||
- RustFS adapter PR ready with targeted test evidence.
|
||||
- Docs and compose parity review complete before marking DONE.
|
||||
@@ -1,93 +0,0 @@
|
||||
# Sprint 20260305-003 - Replay Feed Snapshot Storage Completion
|
||||
|
||||
## Topic & Scope
|
||||
- Complete the remaining Replay portion of Point 2: durable Postgres index plus production-ready object-store blob channel behavior.
|
||||
- Preserve deterministic replay guarantees across storage drivers and deployment profiles.
|
||||
- Remove ambiguous driver semantics for Replay object storage in non-development runtime.
|
||||
- Working directory: `src/Replay`.
|
||||
- Expected evidence: targeted Replay storage tests, startup contract tests, and updated Replay/platform docs.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on shared storage contract in `docs/modules/platform/architecture.md`.
|
||||
- Can run in parallel with JobEngine and Remediation workstreams.
|
||||
- Documentation cleanup sprint depends on this sprint's final object-store behavior.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/modules/replay/architecture.md`
|
||||
- `docs/modules/platform/architecture.md`
|
||||
- `src/Replay/StellaOps.Replay.WebService/Program.cs`
|
||||
- `src/Replay/__Tests/StellaOps.Replay.Core.Tests/FeedSnapshots/ReplayFeedSnapshotStoresTests.cs`
|
||||
- `docs/implplan/CONSOLIDATION_WEBSERVICE_FUNCTION_DB_MATRIX_20260305.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### REPLAY-STOR-001 - Finalize Replay storage driver contract and reject unsupported runtime paths
|
||||
Status: DOING
|
||||
Dependency: none
|
||||
Owners: Project Manager, Implementer
|
||||
Task description:
|
||||
- Review current `Storage:Driver` and `Storage:ObjectStore:Driver` behavior and define final accepted production combinations.
|
||||
- Ensure unsupported combinations fail deterministically at startup with precise error text.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Contract table is documented with defaults, required keys, and non-dev fail-fast behavior.
|
||||
- [ ] Contract tests cover valid and invalid storage configuration paths.
|
||||
|
||||
### REPLAY-STOR-002 - Implement RustFS blob adapter path or narrow contract explicitly
|
||||
Status: DOING
|
||||
Dependency: REPLAY-STOR-001
|
||||
Owners: Implementer
|
||||
Task description:
|
||||
- Implement a concrete RustFS blob adapter for Replay snapshots, or formally narrow the contract to `seed-fs` and remove ambiguous `rustfs` acceptance.
|
||||
- Keep Postgres index storage unchanged and deterministic.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Runtime behavior matches documented contract without hidden fallback semantics.
|
||||
- [x] Non-dev deployment profile has one clear supported blob path with deterministic startup validation.
|
||||
- [ ] Blob read/write paths are integration-tested.
|
||||
|
||||
### REPLAY-STOR-003 - Validate deterministic replay behavior under finalized storage modes
|
||||
Status: BLOCKED
|
||||
Dependency: REPLAY-STOR-002
|
||||
Owners: Test Automation
|
||||
Task description:
|
||||
- Add or extend tests to verify index/blob persistence consistency, stable ordering, and deterministic replay outputs.
|
||||
- Execute targeted test runs against Replay core and webservice projects for selected storage modes.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Replay storage tests cover create/read/list flows and deterministic ordering.
|
||||
- [ ] Test evidence includes command lines, test counts, and pass/fail status.
|
||||
- [ ] No regression in existing point-in-time query and verdict replay tests.
|
||||
|
||||
### REPLAY-STOR-004 - Update replay docs and storage runbook references
|
||||
Status: DOING
|
||||
Dependency: REPLAY-STOR-003
|
||||
Owners: Documentation author, Implementer
|
||||
Task description:
|
||||
- Update Replay module architecture docs with finalized storage contract and operator guidance.
|
||||
- Link the final contract from platform architecture docs and sprint Decisions & Risks.
|
||||
|
||||
Completion criteria:
|
||||
- [x] `docs/modules/replay/architecture.md` reflects final storage behavior and required config.
|
||||
- [ ] Platform-level storage contract docs reference Replay accurately.
|
||||
- [ ] Sprint log links to all updated docs and evidence artifacts.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-05 | Sprint created from architecture review; Replay index persistence is in place, but object-store driver contract remains incomplete for production parity. | Project Manager |
|
||||
| 2026-03-05 | Started REPLAY-STOR-001/002/004: narrowed object-store contract by rejecting `rustfs` at startup and keeping `seed-fs` as the only supported blob driver. | Implementer |
|
||||
| 2026-03-05 | Updated `docs/modules/replay/architecture.md` storage contract text to match runtime behavior (`seed-fs` only for blob store). | Documentation author |
|
||||
| 2026-03-05 | REPLAY-STOR-003 blocked by unrelated replay API auth regressions in existing suite: `dotnet test src/Replay/__Tests/StellaOps.Replay.Core.Tests/StellaOps.Replay.Core.Tests.csproj --filter FullyQualifiedName~FeedSnapshots -m:1 -v minimal` ran full suite (`MTP0001` indicates filter ignored) and failed `2/99` with `401` on point-in-time API integration tests. | Test Automation |
|
||||
|
||||
## Decisions & Risks
|
||||
- Replay already resolves Postgres index store with non-dev fail-fast when connection is missing.
|
||||
- Decision: narrowed Replay blob storage contract to `seed-fs` only; `rustfs` now fails fast in all profiles with an explicit startup error.
|
||||
- Risk: mixed driver semantics can produce environment-specific behavior drift during incident replay verification.
|
||||
- Risk: existing replay API integration auth failures currently block a clean green run of the targeted feed-snapshot suite and prevent closing REPLAY-STOR-003.
|
||||
- Mitigation: resolve/triage auth regression in replay API tests, then rerun targeted storage suite and complete platform-level doc linkage.
|
||||
|
||||
## Next Checkpoints
|
||||
- Storage contract decision recorded (narrowed to `seed-fs` blob driver).
|
||||
- Resolve replay API auth test failures and rerun targeted feed-snapshot suite.
|
||||
- Complete platform storage-contract doc linkage once REPLAY-STOR-003 is unblocked.
|
||||
@@ -1,116 +0,0 @@
|
||||
# Sprint 20260305-004 - Remediation Postgres Runtime Wiring and Service Standardization
|
||||
|
||||
## Topic & Scope
|
||||
- Complete Point 3 by wiring Remediation runtime to real Postgres data source and removing implicit in-memory production behavior.
|
||||
- Bring Remediation webservice in line with StellaOps webservice baseline (router/local hostname integration, explicit storage contract, deterministic startup rules).
|
||||
- Add missing module-level AGENTS contract for `src/Remediation`.
|
||||
- Working directory: `src/Remediation`.
|
||||
- Expected evidence: Remediation webservice startup contract tests, persistence integration tests, and updated module docs/AGENTS.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on platform storage contract from `docs/modules/platform/architecture.md`.
|
||||
- Can run in parallel with JobEngine, Replay, and Platform boundary sprints.
|
||||
- Documentation cleanup sprint depends on this sprint for final Remediation inventory and host/path metadata.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/modules/remediation/architecture.md`
|
||||
- `src/Remediation/StellaOps.Remediation.WebService/Program.cs`
|
||||
- `src/Remediation/StellaOps.Remediation.Persistence/Postgres/RemediationDataSource.cs`
|
||||
- `src/Remediation/StellaOps.Remediation.Persistence/Repositories/PostgresFixTemplateRepository.cs`
|
||||
- `src/Remediation/StellaOps.Remediation.Persistence/Repositories/PostgresPrSubmissionRepository.cs`
|
||||
- `src/Remediation/StellaOps.Remediation.Persistence/Repositories/PostgresMarketplaceSourceRepository.cs`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### REMED-RUNTIME-001 - Create module-local AGENTS contract for Remediation
|
||||
Status: DONE
|
||||
Dependency: none
|
||||
Owners: Project Manager, Documentation author
|
||||
Task description:
|
||||
- Add `src/Remediation/AGENTS.md` with required reading, working directory scope, deterministic/testing requirements, and endpoint metadata.
|
||||
- Ensure repo-wide and module-level instructions are aligned and enforceable for implementers.
|
||||
|
||||
Completion criteria:
|
||||
- [x] `src/Remediation/AGENTS.md` exists and is consistent with repo-wide AGENTS rules.
|
||||
- [x] Sprint docs reference the new module-local AGENTS contract.
|
||||
|
||||
### REMED-RUNTIME-002 - Replace parameterless repository wiring with data-source-backed DI
|
||||
Status: DONE
|
||||
Dependency: REMED-RUNTIME-001
|
||||
Owners: Implementer
|
||||
Task description:
|
||||
- Register and inject `RemediationDataSource` and remove parameterless repository construction from webservice runtime.
|
||||
- Preserve deterministic behavior while ensuring non-dev runtime does not silently degrade to in-memory mode.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Webservice DI uses data-source-backed repository constructors.
|
||||
- [x] Non-development startup fails fast when required Postgres config is missing.
|
||||
- [x] In-memory mode remains explicit and test-profile scoped only.
|
||||
|
||||
### REMED-RUNTIME-003 - Add standard webservice integration hooks and policy-safe defaults
|
||||
Status: DONE
|
||||
Dependency: REMED-RUNTIME-002
|
||||
Owners: Implementer
|
||||
Task description:
|
||||
- Align Remediation host with standard middleware and service integrations used by peer webservices:
|
||||
- Router microservice integration.
|
||||
- Local hostname logging/binding.
|
||||
- Explicit CORS and auth policy conventions matching module scope.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Remediation host exposes deterministic local alias behavior (`*.stella-ops.local`) consistent with platform conventions.
|
||||
- [x] Router integration and endpoint exposure are documented and test-verified.
|
||||
- [x] Authz policy behavior is explicit and covered in tests.
|
||||
|
||||
### REMED-RUNTIME-004 - Add persistence and startup contract tests
|
||||
Status: DONE
|
||||
Dependency: REMED-RUNTIME-002
|
||||
Owners: Test Automation
|
||||
Task description:
|
||||
- Add targeted tests validating startup contract behavior for:
|
||||
- valid Postgres configuration.
|
||||
- missing Postgres configuration in non-development profile.
|
||||
- explicit in-memory test profile behavior.
|
||||
- Add integration tests for repository CRUD paths against Postgres fixture.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Tests assert deterministic ordering and tenant-safe behavior for repository operations.
|
||||
- [x] Startup contract tests fail when configuration contract is violated.
|
||||
- [x] Evidence includes command output and test counts.
|
||||
|
||||
### REMED-RUNTIME-005 - Update Remediation architecture docs and migration notes
|
||||
Status: DONE
|
||||
Dependency: REMED-RUNTIME-004
|
||||
Owners: Documentation author, Implementer
|
||||
Task description:
|
||||
- Update module architecture docs to reflect final runtime wiring and configuration contract.
|
||||
- Record migration guidance from current behavior to finalized storage mode.
|
||||
|
||||
Completion criteria:
|
||||
- [x] `docs/modules/remediation/architecture.md` matches implemented runtime behavior.
|
||||
- [x] Sprint Decisions & Risks links all relevant docs and test evidence.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-05 | Sprint created after architecture review identified Remediation runtime still using parameterless repository constructors and in-memory fallback behavior. | Project Manager |
|
||||
| 2026-03-05 | REMED-RUNTIME-001 completed: added `src/Remediation/AGENTS.md` with scope, required reading, and deterministic/testing rules. | Implementer |
|
||||
| 2026-03-05 | Started REMED-RUNTIME-002/003/004/005: switched webservice to storage-driver contract wiring, added router/local-hostname integration, and added startup-contract tests plus architecture doc updates. | Implementer |
|
||||
| 2026-03-05 | Test evidence: `dotnet test src/Remediation/__Tests/StellaOps.Remediation.WebService.Tests/StellaOps.Remediation.WebService.Tests.csproj -m:1 -v minimal` -> Passed `8/8`; includes startup contract and source endpoint integration checks. | Test Automation |
|
||||
| 2026-03-05 | Test evidence: `dotnet test src/Remediation/__Tests/StellaOps.Remediation.Tests/StellaOps.Remediation.Tests.csproj -m:1 -v minimal` -> Passed `28/28` (with existing `MTP0001` warning from project settings). | Test Automation |
|
||||
| 2026-03-05 | REMED-RUNTIME-002/003/004/005 marked DONE after runtime wiring, router/local alias integration, startup tests, and architecture migration notes were merged. | Implementer |
|
||||
|
||||
## Decisions & Risks
|
||||
- Decision: Remediation webservice now defaults to `Storage:Driver=postgres` with explicit startup failure when Postgres connection settings are absent.
|
||||
- Decision: `Storage:Driver=inmemory` is allowed only in `Test`/`Testing` profiles to keep non-test deployments from silently degrading to process memory.
|
||||
- Decision: Remediation host now follows baseline webservice integration (`AddRouterMicroservice`, `TryAddStellaOpsLocalBinding`, `LogStellaOpsLocalHostname`, `UseStellaOpsCors`).
|
||||
- References:
|
||||
- `src/Remediation/AGENTS.md`
|
||||
- `src/Remediation/StellaOps.Remediation.WebService/Program.cs`
|
||||
- `src/Remediation/__Tests/StellaOps.Remediation.WebService.Tests/RemediationStartupContractTests.cs`
|
||||
- `docs/modules/remediation/architecture.md`
|
||||
- Residual risk: production startup still cannot validate Postgres connectivity without invoking repository operations.
|
||||
- Mitigation: add explicit connectivity health probe in follow-up ops hardening if required.
|
||||
|
||||
## Next Checkpoints
|
||||
- Completed for this sprint stream; handoff can proceed to cross-sprint docs synchronization (`SPRINT_20260305_006_DOCS_webservice_catalog_and_domain_consistency.md`).
|
||||
@@ -1,95 +0,0 @@
|
||||
# Sprint 20260305-005 - Platform Read-Model Boundary Enforcement
|
||||
|
||||
## Topic & Scope
|
||||
- Execute Point 4 by formalizing and enforcing Platform read-model boundaries to prevent cross-module persistence coupling drift.
|
||||
- Preserve aggregation behavior while introducing explicit contract and test guardrails for future changes.
|
||||
- Ensure migration-management dependencies are clearly separated from runtime query dependencies.
|
||||
- Working directory: `src/Platform`.
|
||||
- Expected evidence: boundary inventory, guard tests, updated architecture dossier/ADR, and endpoint-level verification.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on current Platform architecture docs and runtime service inventory.
|
||||
- Can run in parallel with storage sprints for JobEngine/Replay/Remediation.
|
||||
- Documentation cleanup sprint depends on final boundary statement from this sprint.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
- `docs/modules/platform/architecture.md`
|
||||
- `src/Platform/StellaOps.Platform.WebService/Program.cs`
|
||||
- `src/Platform/StellaOps.Platform.WebService/Services/TopologyReadModelService.cs`
|
||||
- `src/Platform/StellaOps.Platform.WebService/Services/SecurityReadModelService.cs`
|
||||
- `src/Platform/StellaOps.Platform.WebService/Services/IntegrationsReadModelService.cs`
|
||||
- `src/Platform/__Libraries/StellaOps.Platform.Database/MigrationModulePlugins.cs`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### PLATFORM-BOUND-001 - Produce runtime dependency inventory and classify boundary risks
|
||||
Status: TODO
|
||||
Dependency: none
|
||||
Owners: Project Manager, Implementer
|
||||
Task description:
|
||||
- Inventory Platform runtime dependencies and classify each as:
|
||||
- allowed runtime read-model dependency.
|
||||
- migration-only dependency.
|
||||
- prohibited cross-module persistence coupling.
|
||||
- Capture inventory output in module docs so future reviewers can validate changes quickly.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Inventory table committed with explicit allowed/prohibited categories.
|
||||
- [ ] Every cross-module reference in Platform runtime code is justified or queued for remediation.
|
||||
|
||||
### PLATFORM-BOUND-002 - Add enforceable guard tests for persistence boundary violations
|
||||
Status: TODO
|
||||
Dependency: PLATFORM-BOUND-001
|
||||
Owners: Implementer, Test Automation
|
||||
Task description:
|
||||
- Add architecture-style tests that fail if `StellaOps.Platform.WebService` references foreign module DbContext/persistence internals outside approved contracts.
|
||||
- Keep migration plugin assembly scanning excluded from runtime boundary assertions by explicit allowlist.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Guard tests fail on introduced boundary violations.
|
||||
- [ ] Allowlist exceptions are minimal and documented.
|
||||
- [ ] Test project and commands are documented in sprint evidence.
|
||||
|
||||
### PLATFORM-BOUND-003 - Introduce explicit query contract interfaces where boundary is implicit
|
||||
Status: TODO
|
||||
Dependency: PLATFORM-BOUND-001
|
||||
Owners: Implementer
|
||||
Task description:
|
||||
- For any remaining implicit data coupling paths, introduce explicit query interfaces/adapters to make dependency direction clear.
|
||||
- Preserve deterministic ordering and tenant isolation semantics of existing read-model endpoints.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Runtime read-model services depend on explicit contracts rather than ad-hoc persistence internals.
|
||||
- [ ] Endpoint behavior remains backward-compatible or includes versioned contract notes.
|
||||
- [ ] Deterministic ordering tests remain green.
|
||||
|
||||
### PLATFORM-BOUND-004 - Document boundary policy and migration/runtime separation
|
||||
Status: TODO
|
||||
Dependency: PLATFORM-BOUND-002
|
||||
Owners: Documentation author, Implementer
|
||||
Task description:
|
||||
- Update Platform architecture docs with a "runtime boundary policy" section.
|
||||
- Add clear guidance differentiating:
|
||||
- migration orchestration references (allowed in database module plugins).
|
||||
- runtime read-model dependencies (must stay behind explicit contracts).
|
||||
|
||||
Completion criteria:
|
||||
- [ ] `docs/modules/platform/architecture.md` and/or `architecture-overview.md` include boundary policy text and examples.
|
||||
- [ ] Decision log links to updated docs and guard test evidence.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-05 | Sprint created to execute architecture Point 4 and prevent Platform cross-module coupling regressions. | Project Manager |
|
||||
|
||||
## Decisions & Risks
|
||||
- Platform runtime currently uses in-service read-model services; this sprint codifies and enforces that boundary rather than assuming it remains stable.
|
||||
- `StellaOps.Platform.Database` migration plugins intentionally reference multiple module persistence assemblies; runtime boundary tests must not conflate migration wiring with runtime coupling.
|
||||
- Risk: over-restrictive guards can block valid evolution.
|
||||
- Mitigation: maintain explicit allowlist and update via documented architectural decisions only.
|
||||
|
||||
## Next Checkpoints
|
||||
- Dependency inventory reviewed.
|
||||
- Guard tests merged and running in CI.
|
||||
- Boundary policy documented and referenced by docs sprint.
|
||||
@@ -1,129 +0,0 @@
|
||||
# Sprint 20260305-006 - Docs Webservice Catalog and Domain Consistency
|
||||
|
||||
## Topic & Scope
|
||||
- Deliver the documentation improvements needed to support points 1-4 implementation and handoff.
|
||||
- Create one canonical service catalog for webservice domain, hostname, purpose, and persistence backing.
|
||||
- Resolve stale path/hostname inconsistencies across architecture and operations docs.
|
||||
- Working directory: `docs`.
|
||||
- Expected evidence: updated docs pages, link/path validation output, and cross-sprint references in Decisions & Risks.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Depends on finalized behavior from:
|
||||
- `SPRINT_20260305_002_JobEngine_packsregistry_taskrunner_storage_completion.md`
|
||||
- `SPRINT_20260305_003_Replay_feed_snapshot_storage_completion.md`
|
||||
- `SPRINT_20260305_004_Remediation_postgres_runtime_wiring.md`
|
||||
- `SPRINT_20260305_005_Platform_read_model_boundary_enforcement.md`
|
||||
- Can start in parallel for baseline cleanup, then finalize after implementation sprints converge.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/implplan/CONSOLIDATION_WEBSERVICE_FUNCTION_DB_MATRIX_20260305.md`
|
||||
- `docs/technical/architecture/port-registry.md`
|
||||
- `docs/modules/router/webservices-valkey-rollout-matrix.md`
|
||||
- `docs/quickstart.md`
|
||||
- `docs/INSTALL_GUIDE.md`
|
||||
- `docs/modules/platform/architecture.md`
|
||||
- `docs/technical/architecture/README.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### DOCS-SVC-001 - Publish canonical webservice catalog page
|
||||
Status: TODO
|
||||
Dependency: none
|
||||
Owners: Documentation author, Project Manager
|
||||
Task description:
|
||||
- Create a canonical service-catalog doc listing each webservice with:
|
||||
- module domain.
|
||||
- local hostname/domain alias.
|
||||
- purpose/functional surface summary.
|
||||
- persistence mode and primary backing technology.
|
||||
- source path and owner module.
|
||||
- Mark this catalog as source-of-truth and link it from architecture index pages.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Canonical catalog exists under `docs/technical/architecture/`.
|
||||
- [ ] `docs/technical/architecture/README.md` links to the catalog.
|
||||
- [ ] Catalog includes all active webservices, including Remediation.
|
||||
|
||||
### DOCS-SVC-002 - Correct stale path and service-name drift in port registry
|
||||
Status: TODO
|
||||
Dependency: DOCS-SVC-001
|
||||
Owners: Documentation author
|
||||
Task description:
|
||||
- Update `docs/technical/architecture/port-registry.md` entries whose source paths no longer match repository layout.
|
||||
- Add or correct missing service rows where runtime services exist but are absent/inaccurate.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] All path references in the port table resolve to existing directories.
|
||||
- [ ] Service naming/path mapping matches current module consolidation layout.
|
||||
- [ ] Port registry includes Remediation or documents its absence with explicit rationale and follow-up.
|
||||
|
||||
### DOCS-SVC-003 - Standardize runtime hostname/domain convention guidance
|
||||
Status: TODO
|
||||
Dependency: DOCS-SVC-001
|
||||
Owners: Documentation author
|
||||
Task description:
|
||||
- Define canonical runtime hostname form (`*.stella-ops.local`) and document permitted exceptions.
|
||||
- Normalize conflicting usage examples across quickstart, operations, and API docs.
|
||||
- Preserve intentional schema ID and non-runtime examples where needed, with explicit explanation.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Runtime URL examples are consistent with canonical hostname convention.
|
||||
- [ ] Exception policy is documented (schema IDs, synthetic examples, external references).
|
||||
- [ ] Search audit evidence is captured in sprint log.
|
||||
|
||||
### DOCS-SVC-004 - Update router rollout inventory and service integration docs
|
||||
Status: TODO
|
||||
Dependency: DOCS-SVC-002
|
||||
Owners: Documentation author, Implementer
|
||||
Task description:
|
||||
- Update router rollout matrix and integration guide to include missing/renamed services and current route ownership.
|
||||
- Ensure service hostnames and route prefixes align with the canonical service catalog.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] `docs/modules/router/webservices-valkey-rollout-matrix.md` is synchronized with active service inventory.
|
||||
- [ ] Missing Remediation routing status is explicitly tracked.
|
||||
- [ ] Route ownership and fallback notes are current and actionable.
|
||||
|
||||
### DOCS-SVC-005 - Synchronize consolidation matrix with verified runtime state
|
||||
Status: TODO
|
||||
Dependency: DOCS-SVC-001
|
||||
Owners: Documentation author, Project Manager
|
||||
Task description:
|
||||
- Refresh `CONSOLIDATION_WEBSERVICE_FUNCTION_DB_MATRIX_20260305.md` so per-service DB rows match current code.
|
||||
- Remove contradictory statements between matrix rows and later remediation-status sections.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] DB/Persistence column reflects verified runtime wiring.
|
||||
- [ ] Contradictions are removed and replaced by one clear status statement.
|
||||
- [ ] Matrix references point to current source file paths.
|
||||
|
||||
### DOCS-SVC-006 - Add lightweight docs validation for service-path and hostname drift
|
||||
Status: TODO
|
||||
Dependency: DOCS-SVC-002
|
||||
Owners: Test Automation, Documentation author
|
||||
Task description:
|
||||
- Add a deterministic docs validation script/check for:
|
||||
- unresolved service path references in registry tables.
|
||||
- forbidden runtime hostname variants where canonical form is required.
|
||||
- Integrate check into docs/testing guidance and optionally CI path filters.
|
||||
|
||||
Completion criteria:
|
||||
- [ ] Validation command/script is documented and runnable locally.
|
||||
- [ ] At least one failing fixture/case demonstrates drift detection.
|
||||
- [ ] Sprint log captures validation command output.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-03-05 | Sprint created to execute documentation improvements and provide an actionable handoff surface for points 1-4. | Project Manager |
|
||||
|
||||
## Decisions & Risks
|
||||
- Current docs contain drift between inventory, runtime wiring notes, and path/domain conventions; this blocks efficient multi-agent execution.
|
||||
- Canonical catalog and validation checks are required to keep docs synchronized after module consolidation work.
|
||||
- Risk: broad doc edits can unintentionally rewrite historical examples.
|
||||
- Mitigation: document exception policy and scope normalization to runtime/service-discovery contexts first.
|
||||
|
||||
## Next Checkpoints
|
||||
- Canonical service catalog draft completed and linked.
|
||||
- Port registry and router inventory path verification complete.
|
||||
- Hostname normalization pass completed with validation evidence.
|
||||
@@ -173,6 +173,8 @@ The TaskRunner provides the execution substrate for Orchestrator jobs. Workers p
|
||||
- `Storage:Driver=postgres` is the production default for run state, logs, and approvals.
|
||||
- Postgres-backed stores: `PostgresPackRunStateStore`, `PostgresPackRunLogStore`, `PostgresPackRunApprovalStore` via `TaskRunnerDataSource`.
|
||||
- Artifact payload channel uses object storage path (`seed-fs` driver) configured with `TaskRunner:Storage:ObjectStore:SeedFs:RootPath`.
|
||||
- Startup fails fast when `Storage:ObjectStore:Driver` is set to `rustfs` (not implemented) or any unsupported driver value.
|
||||
- Non-development startup fails fast when `Storage:Driver=postgres` and no connection string is configured.
|
||||
- Explicit non-production overrides remain available (`filesystem`, `inmemory`) but are no longer implicit defaults.
|
||||
|
||||
### 8.3) PacksRegistry subdomain
|
||||
@@ -186,6 +188,8 @@ The PacksRegistry manages compliance/automation pack definitions, versions, and
|
||||
**Database and storage contract (Sprint 312):**
|
||||
- `Storage:Driver=postgres` is the production default for metadata/state repositories (`pack`, `parity`, `lifecycle`, `mirror`, `audit`, `attestation metadata`).
|
||||
- Blob/object payloads (`pack content`, `provenance content`, `attestation content`) are persisted through the seed-fs object-store channel (`SeedFsPacksRegistryBlobStore`).
|
||||
- Startup fails fast when `Storage:ObjectStore:Driver` is set to `rustfs` (not implemented) or any unsupported driver value.
|
||||
- Non-development startup fails fast when `Storage:Driver=postgres` and no connection string is configured.
|
||||
- PostgreSQL keeps metadata and compatibility placeholders; payload retrieval resolves from object storage first.
|
||||
- Explicit non-production overrides remain available (`filesystem`, `inmemory`) but are no longer implicit defaults.
|
||||
|
||||
|
||||
@@ -29,7 +29,8 @@ This contract is the default for all stateful StellaOps webservices unless a mod
|
||||
- Production default: `postgres`.
|
||||
- `inmemory` and `filesystem` are non-production/testing-only and must be explicitly configured.
|
||||
- `Storage:ObjectStore:Driver`
|
||||
- Accepted values: `rustfs`, `seed-fs`.
|
||||
- Accepted values at platform key level: `rustfs`, `seed-fs`.
|
||||
- Module runtime contracts may narrow this set and must fail fast for unsupported values.
|
||||
- Use only for blob/object payload channels (artifacts, snapshots, package blobs).
|
||||
- `ConnectionStrings:Default`
|
||||
- Required when `Storage:Driver=postgres` unless a service-specific connection key is provided.
|
||||
@@ -40,12 +41,43 @@ Fail-fast policy:
|
||||
- Development runtime may use localhost/file defaults only when explicitly intended for local workflows.
|
||||
|
||||
Current implementation status (2026-03-05):
|
||||
- `PacksRegistry`: Postgres metadata/state + seed-fs payload channel for pack/provenance/attestation blobs.
|
||||
- `TaskRunner`: Postgres run state/log/approval + seed-fs artifact payload channel.
|
||||
- `PacksRegistry`: Postgres metadata/state + seed-fs payload channel for pack/provenance/attestation blobs; startup rejects `rustfs` and unknown object-store drivers.
|
||||
- `TaskRunner`: Postgres run state/log/approval + seed-fs artifact payload channel; startup rejects `rustfs` and unknown object-store drivers in both WebService and Worker.
|
||||
- `RiskEngine`: Postgres-backed result store (`riskengine.risk_score_results`) with explicit in-memory test fallback.
|
||||
- `Replay`: Postgres snapshot index + seed-fs snapshot blob store.
|
||||
- `Replay`: Postgres snapshot index + seed-fs snapshot blob store; startup rejects `rustfs` and unknown object-store drivers.
|
||||
- `OpsMemory`: connection precedence aligned to `ConnectionStrings:OpsMemory -> ConnectionStrings:Default`, with non-development fail-fast.
|
||||
|
||||
## Platform Runtime Read-Model Boundary Policy (Point 4 / Sprint 20260305-005)
|
||||
|
||||
Platform runtime read-model APIs are aggregation-only and must stay behind explicit query contracts. Runtime read handlers must not take direct dependencies on foreign module persistence internals.
|
||||
|
||||
Approved runtime query contracts:
|
||||
- `IReleaseControlBundleStore` (release/topology/security/integration projections over release-control bundles + runs).
|
||||
- `IPlatformContextQuery` (read-only access to region/environment context inventory).
|
||||
|
||||
Prohibited in runtime read-model services:
|
||||
- Direct constructor dependencies on foreign `StellaOps.*.Persistence*` namespaces.
|
||||
- Direct `DbContext`, `NpgsqlDataSource`, or module-specific migration runner dependencies from non-admin read endpoints.
|
||||
|
||||
Migration/admin allowlist (explicit boundary exceptions):
|
||||
- `src/Platform/StellaOps.Platform.WebService/Endpoints/SeedEndpoints.cs`
|
||||
- `src/Platform/__Libraries/StellaOps.Platform.Database/MigrationModulePlugins.cs`
|
||||
|
||||
Enforcement:
|
||||
- Guard tests in `src/Platform/__Tests/StellaOps.Platform.WebService.Tests/PlatformRuntimeBoundaryGuardTests.cs` fail when constructor contracts drift or foreign persistence references appear outside the allowlist above.
|
||||
|
||||
### Runtime Dependency Inventory (2026-03-05)
|
||||
|
||||
| Component | Dependency category | Classification | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `ReleaseReadModelService` | `IReleaseControlBundleStore` | Allowed runtime read-model dependency | Release projection reads only via Platform-owned bundle-store contract. |
|
||||
| `TopologyReadModelService` | `IReleaseControlBundleStore`, `IPlatformContextQuery` | Allowed runtime read-model dependency | Topology projection composes release bundles with context inventory through explicit query contracts. |
|
||||
| `SecurityReadModelService` | `IReleaseControlBundleStore`, `IPlatformContextQuery` | Allowed runtime read-model dependency | Security projection remains synthetic/read-only and does not call VEX/exception write stores directly. |
|
||||
| `IntegrationsReadModelService` | `IReleaseControlBundleStore`, `IPlatformContextQuery` | Allowed runtime read-model dependency | Integration freshness projection uses release run metadata and context inventory only. |
|
||||
| `PlatformContextService` | `IPlatformContextStore` (`InMemory`/`Postgres`) | Allowed runtime dependency (module-local persistence) | Exposes read-only `IPlatformContextQuery` plus preference write APIs; no foreign module coupling. |
|
||||
| `SeedEndpoints` | Foreign `StellaOps.*.Persistence*` migration assemblies | Migration/admin-only dependency | Allowed exception for demo seed execution only (`platform.setup.admin`). |
|
||||
| `MigrationModulePlugins` | Foreign module migration assemblies | Migration-only dependency | Allowed exception for schema migration orchestration, not part of runtime read endpoint execution path. |
|
||||
|
||||
## Advisory Commitments (2026-02-26 Batch)
|
||||
|
||||
- `SPRINT_20260226_223_Platform_score_explain_contract_and_replay_alignment` defines deterministic score/explain/replay contract behavior for CLI and Web consumers.
|
||||
|
||||
@@ -161,6 +161,14 @@ Provide a single, deterministic aggregation layer for cross-service UX workflows
|
||||
- Notifier (alert policies and delivery status)
|
||||
- Policy/Scanner/Registry/VexHub (search aggregation sources)
|
||||
|
||||
## Runtime boundary policy
|
||||
- Runtime read-model services (`/api/v2/releases`, `/api/v2/topology/*`, `/api/v2/security/*`, `/api/v2/integrations/*`) must depend only on explicit query contracts:
|
||||
- `IReleaseControlBundleStore`
|
||||
- `IPlatformContextQuery`
|
||||
- Foreign module persistence references are migration/admin-only and limited to explicit allowlist surfaces (`SeedEndpoints`, `MigrationModulePlugins`).
|
||||
- Runtime read endpoints must not inject foreign `*.Persistence*` types, `DbContext` from other modules, or migration runners directly.
|
||||
- Guard tests: `src/Platform/__Tests/StellaOps.Platform.WebService.Tests/PlatformRuntimeBoundaryGuardTests.cs`.
|
||||
|
||||
## Security and scopes
|
||||
- Health: `ops.health` (summary), `ops.admin` (metrics)
|
||||
- Quotas: `quota.read` (summary), `quota.admin` (alerts/config)
|
||||
|
||||
@@ -42,6 +42,7 @@ Legend:
|
||||
| policy-engine.stella-ops.local | policy-engine | /api/risk, /api/risk-budget, /api/v1/determinization, /policyEngine | C | Developer + Test Automation (Wave C) | Migrate API prefixes first; keep root compatibility path until control-plane verification completes. | Route type revert + `POLICY_ENGINE_ROUTER_ENABLED=false` (RMW-03). |
|
||||
| policy-gateway.stella-ops.local | policy | /api/cvss, /api/exceptions, /api/gate, /api/policy, /api/v1/governance, /api/v1/policy, /policy, /policyGateway | C | Developer + Test Automation (Wave C) | Migrate API prefixes first; keep `/policy` and `/policyGateway` compatibility paths until final cutover. | Route type revert + `POLICY_GATEWAY_ROUTER_ENABLED=false` (RMW-03). |
|
||||
| reachgraph.stella-ops.local | reachgraph-web | /api/v1/reachability, /reachgraph | D | Developer + Test Automation (Wave D) | Migrate API prefix first, then root compatibility path. | Route type revert + `REACHGRAPH_ROUTER_ENABLED=false` (RMW-03). |
|
||||
| remediation.stella-ops.local | — (not in compose snapshot) | — (no ReverseProxy route in 2026-02-21 snapshot) | C | Developer + Test Automation (Wave C) | `StellaOps.Remediation.WebService` exists, but router/compose mapping is missing. Add explicit remediation API route inventory and then migrate to Microservice route type in control-plane wave. | Missing rollback key; add `REMEDIATION_ROUTER_ENABLED` once route is added. |
|
||||
| registry-token.stella-ops.local | registry-token | /registryTokenservice | A | Developer + Test Automation (Wave A) | Migrate compatibility route with token flow validation in Wave A. | Route type revert + `REGISTRY_TOKEN_ROUTER_ENABLED=false` (RMW-03). |
|
||||
| replay.stella-ops.local | replay-web | /replay | A | Developer + Test Automation (Wave A) | Migrate compatibility route in Wave A; add API-form alias if needed. | Route type revert + `REPLAY_ROUTER_ENABLED=false` (RMW-03). |
|
||||
| riskengine.stella-ops.local | riskengine-web | /riskengine | C | Developer + Test Automation (Wave C) | Migrate compatibility route in control-plane wave; add API alias if required. | Route type revert + `RISKENGINE_ROUTER_ENABLED=false` (RMW-03). |
|
||||
|
||||
@@ -4,6 +4,18 @@
|
||||
|
||||
This document defines the information architecture (IA) for the StellaOps web interface, including navigation structure, route hierarchy, and role-based access patterns.
|
||||
|
||||
## 2026-03-05 Shell IA Update
|
||||
|
||||
The global shell navigation was updated to improve visual scanability and mobile usability:
|
||||
|
||||
- Sidebar global menus are now grouped into:
|
||||
- `Release Control`
|
||||
- `Security & Evidence`
|
||||
- `Platform & Setup`
|
||||
- Group headers act as direct links to each group's landing route for faster navigation.
|
||||
- Mobile topbar secondary controls now open through an explicit `Context` toggle instead of always occupying visible row space.
|
||||
- Findings compare panes and Releases deployment list were updated for mobile-safe layouts (no forced clipping).
|
||||
|
||||
## Navigation Structure
|
||||
|
||||
### Primary Navigation
|
||||
|
||||
@@ -112,6 +112,9 @@ After a full setup, you'll have 60+ services running locally:
|
||||
|
||||
Full service list: `devops/compose/docker-compose.stella-ops.yml`
|
||||
|
||||
Runtime URL convention: use `*.stella-ops.local` hostnames for services.
|
||||
Exception: `hosts.stellaops.local` is a file name, not a runtime host.
|
||||
|
||||
Optional Sigstore services (`rekor-v2`, `rekor-cli`, `cosign`) are enabled only with:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -11,12 +11,28 @@ Use this index to locate platform-level architecture references and per-module d
|
||||
- [Component map](component-map.md) (quick descriptions of every module under `src/`)
|
||||
|
||||
## Detailed references
|
||||
- [Canonical webservice catalog](webservice-catalog.md)
|
||||
- [Platform topology](platform-topology.md)
|
||||
- [Infrastructure dependencies](infrastructure-dependencies.md)
|
||||
- [Request and data flows](request-flows.md)
|
||||
- [Data isolation model](data-isolation.md)
|
||||
- [Security boundaries](security-boundaries.md)
|
||||
|
||||
## Docs validation
|
||||
|
||||
Use the architecture docs validation check to detect service-path and hostname drift:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File ./docs/technical/architecture/scripts/validate-webservice-docs.ps1
|
||||
```
|
||||
|
||||
Intentional failing fixture (sanity check for the validator):
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File ./docs/technical/architecture/scripts/validate-webservice-docs.ps1 `
|
||||
-Files "docs/technical/architecture/fixtures/webservice-docs-invalid-fixture.md"
|
||||
```
|
||||
|
||||
## User-centric views (NEW)
|
||||
- [User flows (UML diagrams)](user-flows.md) - End-to-end flows from user perspective
|
||||
- [Module matrix](module-matrix.md) - Complete 46-module inventory with categorization
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
# Validation Fixture: Expected to fail
|
||||
|
||||
This fixture intentionally includes drift so `validate-webservice-docs.ps1` can prove detection.
|
||||
|
||||
| Service | Hostname | Path |
|
||||
| --- | --- | --- |
|
||||
| DemoService | `demo.stellaops.local` | `src/DoesNotExist/Missing.WebService` |
|
||||
|
||||
Runtime URL sample: https://demo.stellaops.local/api/v1/demo
|
||||
@@ -2,6 +2,9 @@
|
||||
|
||||
All Stella Ops web services are assigned deterministic HTTPS/HTTP port pairs to avoid collisions during local development and simplify service discovery configuration.
|
||||
|
||||
Service inventory source-of-truth: `docs/technical/architecture/webservice-catalog.md`.
|
||||
This page focuses on deterministic slot/port allocation and may include legacy or unassigned notes.
|
||||
|
||||
## Port Assignment Scheme
|
||||
|
||||
- **Formula**: Service at slot N → HTTPS = `10000 + N×10`, HTTP = `10000 + N×10 + 1`
|
||||
@@ -22,7 +25,7 @@ All Stella Ops web services are assigned deterministic HTTPS/HTTP port pairs to
|
||||
| 7 | 10070 | 10071 | Evidence Locker Aggregator | — | `src/EvidenceLocker/StellaOps.EvidenceLocker` | `STELLAOPS_EVIDENCELOCKER_AGGREGATOR_URL` |
|
||||
| 8 | 10080 | 10081 | Scanner | `scanner.stella-ops.local` | `src/Scanner/StellaOps.Scanner.WebService` | `STELLAOPS_SCANNER_URL` |
|
||||
| 9 | 10090 | 10091 | Concelier | `concelier.stella-ops.local` | `src/Concelier/StellaOps.Concelier.WebService` | `STELLAOPS_CONCELIER_URL` |
|
||||
| 10 | 10100 | 10101 | Excititor | `excititor.stella-ops.local` | `src/Excititor/StellaOps.Excititor.WebService` | `STELLAOPS_EXCITITOR_URL` |
|
||||
| 10 | 10100 | 10101 | Excititor | `excititor.stella-ops.local` | `src/Concelier/StellaOps.Excititor.WebService` | `STELLAOPS_EXCITITOR_URL` |
|
||||
| 11 | 10110 | 10111 | VexHub | `vexhub.stella-ops.local` | `src/VexHub/StellaOps.VexHub.WebService` | `STELLAOPS_VEXHUB_URL` |
|
||||
| 12 | 10120 | 10121 | VexLens | `vexlens.stella-ops.local` | `src/VexLens/StellaOps.VexLens.WebService` | `STELLAOPS_VEXLENS_URL` |
|
||||
| 13 | 10130 | 10131 | VulnExplorer | `vulnexplorer.stella-ops.local` | `src/Findings/StellaOps.VulnExplorer.Api` | `STELLAOPS_VULNEXPLORER_URL` |
|
||||
@@ -30,8 +33,8 @@ All Stella Ops web services are assigned deterministic HTTPS/HTTP port pairs to
|
||||
| 15 | 10150 | 10151 | Policy Gateway | `policy-gateway.stella-ops.local` | `src/Policy/StellaOps.Policy.Gateway` | `STELLAOPS_POLICY_GATEWAY_URL` |
|
||||
| 16 | 10160 | 10161 | RiskEngine | `riskengine.stella-ops.local` | `src/Findings/StellaOps.RiskEngine.WebService` | `STELLAOPS_RISKENGINE_URL` |
|
||||
| 17 | 10170 | 10171 | Orchestrator | `jobengine.stella-ops.local` | `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService` | `STELLAOPS_JOBENGINE_URL` |
|
||||
| 18 | 10180 | 10181 | TaskRunner | `taskrunner.stella-ops.local` | `src/TaskRunner/StellaOps.TaskRunner/StellaOps.TaskRunner.WebService` | `STELLAOPS_TASKRUNNER_URL` |
|
||||
| 19 | 10190 | 10191 | Scheduler | `scheduler.stella-ops.local` | `src/Scheduler/StellaOps.Scheduler.WebService` | `STELLAOPS_SCHEDULER_URL` |
|
||||
| 18 | 10180 | 10181 | TaskRunner | `taskrunner.stella-ops.local` | `src/JobEngine/StellaOps.TaskRunner/StellaOps.TaskRunner.WebService` | `STELLAOPS_TASKRUNNER_URL` |
|
||||
| 19 | 10190 | 10191 | Scheduler | `scheduler.stella-ops.local` | `src/JobEngine/StellaOps.Scheduler.WebService` | `STELLAOPS_SCHEDULER_URL` |
|
||||
| 20 | 10200 | 10201 | Graph API | `graph.stella-ops.local` | `src/Graph/StellaOps.Graph.Api` | `STELLAOPS_GRAPH_URL` |
|
||||
| 21 | 10210 | 10211 | Cartographer | `cartographer.stella-ops.local` | `src/Scanner/StellaOps.Scanner.Cartographer` | `STELLAOPS_CARTOGRAPHER_URL` |
|
||||
| 22 | 10220 | 10221 | ReachGraph | `reachgraph.stella-ops.local` | `src/ReachGraph/StellaOps.ReachGraph.WebService` | `STELLAOPS_REACHGRAPH_URL` |
|
||||
@@ -42,14 +45,14 @@ All Stella Ops web services are assigned deterministic HTTPS/HTTP port pairs to
|
||||
| 27 | 10270 | 10271 | OpsMemory | `opsmemory.stella-ops.local` | `src/AdvisoryAI/StellaOps.OpsMemory.WebService` | `STELLAOPS_OPSMEMORY_URL` |
|
||||
| 28 | 10280 | 10281 | Notifier | `notifier.stella-ops.local` | `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService` | `STELLAOPS_NOTIFIER_URL` |
|
||||
| 29 | 10290 | 10291 | Notify | `notify.stella-ops.local` | `src/Notify/StellaOps.Notify.WebService` | `STELLAOPS_NOTIFY_URL` |
|
||||
| 30 | 10300 | 10301 | Signer | `signer.stella-ops.local` | `src/Signer/StellaOps.Signer/StellaOps.Signer.WebService` | `STELLAOPS_SIGNER_URL` |
|
||||
| 30 | 10300 | 10301 | Signer | `signer.stella-ops.local` | `src/Attestor/StellaOps.Signer/StellaOps.Signer.WebService` | `STELLAOPS_SIGNER_URL` |
|
||||
| 31 | 10310 | 10311 | SmRemote | `smremote.stella-ops.local` | `src/SmRemote/StellaOps.SmRemote.Service` | `STELLAOPS_SMREMOTE_URL` |
|
||||
| 32 | 10320 | 10321 | AirGap Controller | `airgap-controller.stella-ops.local` | `src/AirGap/StellaOps.AirGap.Controller` | `STELLAOPS_AIRGAP_CONTROLLER_URL` |
|
||||
| 33 | 10330 | 10331 | AirGap Time | `airgap-time.stella-ops.local` | `src/AirGap/StellaOps.AirGap.Time` | `STELLAOPS_AIRGAP_TIME_URL` |
|
||||
| 34 | 10340 | 10341 | PacksRegistry | `packsregistry.stella-ops.local` | `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.WebService` | `STELLAOPS_PACKSREGISTRY_URL` |
|
||||
| 34 | 10340 | 10341 | PacksRegistry | `packsregistry.stella-ops.local` | `src/JobEngine/StellaOps.PacksRegistry/StellaOps.PacksRegistry.WebService` | `STELLAOPS_PACKSREGISTRY_URL` |
|
||||
| 35 | 10350 | 10351 | Registry Token | `registry-token.stella-ops.local` | `src/Registry/StellaOps.Registry.TokenService` | `STELLAOPS_REGISTRY_TOKENSERVICE_URL` |
|
||||
| 36 | 10360 | 10361 | BinaryIndex | `binaryindex.stella-ops.local` | `src/BinaryIndex/StellaOps.BinaryIndex.WebService` | `STELLAOPS_BINARYINDEX_URL` |
|
||||
| 37 | 10370 | 10371 | IssuerDirectory | `issuerdirectory.stella-ops.local` | `src/IssuerDirectory/StellaOps.IssuerDirectory/StellaOps.IssuerDirectory.WebService` | `STELLAOPS_ISSUERDIRECTORY_URL` |
|
||||
| 37 | 10370 | 10371 | IssuerDirectory | `issuerdirectory.stella-ops.local` | `src/Authority/StellaOps.IssuerDirectory/StellaOps.IssuerDirectory.WebService` | `STELLAOPS_ISSUERDIRECTORY_URL` |
|
||||
| 38 | 10380 | 10381 | Symbols | `symbols.stella-ops.local` | `src/BinaryIndex/StellaOps.Symbols.Server` | `STELLAOPS_SYMBOLS_URL` |
|
||||
| 39 | 10390 | 10391 | SbomService | `sbomservice.stella-ops.local` | `src/SbomService/StellaOps.SbomService` | `STELLAOPS_SBOMSERVICE_URL` |
|
||||
| 40 | 10400 | 10401 | ExportCenter | `exportcenter.stella-ops.local` | `src/ExportCenter/StellaOps.ExportCenter/StellaOps.ExportCenter.WebService` | `STELLAOPS_EXPORTCENTER_URL` |
|
||||
@@ -62,6 +65,8 @@ All Stella Ops web services are assigned deterministic HTTPS/HTTP port pairs to
|
||||
| 90 | 10900 | 10901 | Examples.Gateway | — | `src/Router/examples/Examples.Gateway` | — |
|
||||
| 91 | 10910 | 10911 | Examples.MultiTransport | — | `src/Router/examples/Examples.MultiTransport.Gateway` | — |
|
||||
|
||||
> Remediation runtime note: `src/Remediation/StellaOps.Remediation.WebService` is active and binds `remediation.stella-ops.local`, but no deterministic slot is currently published in this table because compose/router inventory does not yet expose a stable route mapping. Track status in `docs/modules/router/webservices-valkey-rollout-matrix.md`.
|
||||
|
||||
## Worker Services
|
||||
|
||||
Worker services associated with a web service use ports offset by +2/+3 from the web service slot:
|
||||
@@ -71,17 +76,17 @@ Worker services associated with a web service use ports offset by +2/+3 from the
|
||||
| 10062 | 10063 | EvidenceLocker Worker | `src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.Worker` |
|
||||
| 10162 | 10163 | RiskEngine Worker | `src/Findings/StellaOps.RiskEngine.Worker` |
|
||||
| 10172 | 10173 | Orchestrator Worker | `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.Worker` |
|
||||
| 10182 | 10183 | TaskRunner Worker | `src/TaskRunner/StellaOps.TaskRunner/StellaOps.TaskRunner.Worker` |
|
||||
| 10182 | 10183 | TaskRunner Worker | `src/JobEngine/StellaOps.TaskRunner/StellaOps.TaskRunner.Worker` |
|
||||
| 10232 | 10233 | TimelineIndexer Worker | `src/Timeline/StellaOps.TimelineIndexer.Worker` |
|
||||
| 10282 | 10283 | Notifier Worker | `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker` |
|
||||
| 10342 | 10343 | PacksRegistry Worker | `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Worker` |
|
||||
| 10342 | 10343 | PacksRegistry Worker | `src/JobEngine/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Worker` |
|
||||
| 10402 | 10403 | ExportCenter Worker | `src/ExportCenter/StellaOps.ExportCenter/StellaOps.ExportCenter.Worker` |
|
||||
|
||||
## Environment Variable Convention
|
||||
|
||||
Each web service has a corresponding `STELLAOPS_{SERVICE}_URL` environment variable. The Platform service reads these at startup (Layer 1 of the 3-layer configuration) and maps them into `ApiBaseUrls` for the Angular frontend.
|
||||
|
||||
Example: `STELLAOPS_SCANNER_URL=https://scanner.internal:10080` maps to `ApiBaseUrls["scanner"]`.
|
||||
Example: `STELLAOPS_SCANNER_URL=https://scanner.stella-ops.local` maps to `ApiBaseUrls["scanner"]`.
|
||||
|
||||
See also: [3-Layer Service URL Configuration](../../modules/platform/architecture-overview.md)
|
||||
|
||||
|
||||
103
docs/technical/architecture/scripts/validate-webservice-docs.ps1
Normal file
103
docs/technical/architecture/scripts/validate-webservice-docs.ps1
Normal file
@@ -0,0 +1,103 @@
|
||||
param(
|
||||
[string[]] $Files = @(
|
||||
"docs/technical/architecture/port-registry.md",
|
||||
"docs/technical/architecture/webservice-catalog.md"
|
||||
)
|
||||
)
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
function Get-RepositoryRoot {
|
||||
param([string] $Start)
|
||||
|
||||
$current = Resolve-Path $Start
|
||||
while ($null -ne $current) {
|
||||
if (Test-Path (Join-Path $current "docs")) {
|
||||
return $current
|
||||
}
|
||||
|
||||
$parent = Split-Path -Parent $current
|
||||
if ($parent -eq $current) {
|
||||
break
|
||||
}
|
||||
|
||||
$current = $parent
|
||||
}
|
||||
|
||||
throw "Could not locate repository root from '$Start'."
|
||||
}
|
||||
|
||||
$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
|
||||
$repoRoot = Get-RepositoryRoot -Start $scriptDir
|
||||
|
||||
$pathViolations = [System.Collections.Generic.List[string]]::new()
|
||||
$hostViolations = [System.Collections.Generic.List[string]]::new()
|
||||
|
||||
$pathPattern = [regex]'`(?<path>src/[^`]+)`'
|
||||
$urlPattern = [regex]'https?://(?<host>[A-Za-z0-9.-]+)'
|
||||
$legacyHostPattern = [regex]'\b(?<host>[a-z0-9.-]+\.stellaops\.local)\b'
|
||||
|
||||
foreach ($relativeFile in $Files) {
|
||||
$normalizedRelative = $relativeFile.Replace('\\', '/').Trim()
|
||||
$absoluteFile = Join-Path $repoRoot $normalizedRelative
|
||||
|
||||
if (-not (Test-Path $absoluteFile)) {
|
||||
throw "Validation file not found: $normalizedRelative"
|
||||
}
|
||||
|
||||
$lineNumber = 0
|
||||
foreach ($line in Get-Content $absoluteFile) {
|
||||
$lineNumber++
|
||||
|
||||
foreach ($match in $pathPattern.Matches($line)) {
|
||||
$pathValue = $match.Groups['path'].Value.Trim()
|
||||
$absolutePath = Join-Path $repoRoot ($pathValue.Replace('/', [IO.Path]::DirectorySeparatorChar))
|
||||
if (-not (Test-Path $absolutePath)) {
|
||||
$pathViolations.Add("${normalizedRelative}:$lineNumber unresolved path '$pathValue'")
|
||||
}
|
||||
}
|
||||
|
||||
foreach ($match in $urlPattern.Matches($line)) {
|
||||
$hostValue = $match.Groups['host'].Value.ToLowerInvariant()
|
||||
if ($hostValue -eq "localhost") {
|
||||
continue
|
||||
}
|
||||
|
||||
if ($hostValue.StartsWith("127.")) {
|
||||
continue
|
||||
}
|
||||
|
||||
if ($hostValue -eq "stella-ops.local" -or $hostValue.EndsWith(".stella-ops.local")) {
|
||||
continue
|
||||
}
|
||||
|
||||
$hostViolations.Add("${normalizedRelative}:$lineNumber non-canonical runtime host '$hostValue'")
|
||||
}
|
||||
|
||||
foreach ($match in $legacyHostPattern.Matches($line)) {
|
||||
$hostValue = $match.Groups['host'].Value.ToLowerInvariant()
|
||||
if ($hostValue -eq "hosts.stellaops.local") {
|
||||
continue
|
||||
}
|
||||
|
||||
$hostViolations.Add("${normalizedRelative}:$lineNumber forbidden legacy hostname '$hostValue' (expected .stella-ops.local)")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if ($pathViolations.Count -eq 0 -and $hostViolations.Count -eq 0) {
|
||||
Write-Output "PASS validate-webservice-docs: files=$($Files.Count), pathViolations=0, hostViolations=0"
|
||||
exit 0
|
||||
}
|
||||
|
||||
Write-Output "FAIL validate-webservice-docs"
|
||||
foreach ($violation in $pathViolations) {
|
||||
Write-Output "PATH: $violation"
|
||||
}
|
||||
|
||||
foreach ($violation in $hostViolations) {
|
||||
Write-Output "HOST: $violation"
|
||||
}
|
||||
|
||||
exit 1
|
||||
56
docs/technical/architecture/webservice-catalog.md
Normal file
56
docs/technical/architecture/webservice-catalog.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Canonical Webservice Catalog
|
||||
|
||||
This page is the source-of-truth inventory for Stella Ops `*.WebService` runtime services.
|
||||
|
||||
## Scope and contract
|
||||
- Inventory source: `rg --files src -g "*WebService.csproj"`.
|
||||
- Includes active runtime webservices only (31 services).
|
||||
- Excludes non-`WebService` API binaries (for example `StellaOps.Policy.Engine`, `StellaOps.Policy.Gateway`, `StellaOps.Graph.Api`, `StellaOps.VulnExplorer.Api`, `StellaOps.Symbols.Server`, `StellaOps.Registry.TokenService`, `StellaOps.SmRemote.Service`) even though they may bind `*.stella-ops.local` aliases.
|
||||
- Canonical runtime hostname form: `<service>.stella-ops.local`.
|
||||
|
||||
## Runtime hostname convention and exceptions
|
||||
- Runtime service-discovery URLs in docs should use `https://<service>.stella-ops.local` (or the HTTP equivalent when TLS is intentionally not shown).
|
||||
- Permitted exceptions:
|
||||
- Infrastructure aliases (`db.stella-ops.local`, `cache.stella-ops.local`, `s3.stella-ops.local`, `rekor.stella-ops.local`, `registry.stella-ops.local`).
|
||||
- Loopback/dev diagnostics (`localhost`, `127.x.y.z`) where transport wiring is the point of the example.
|
||||
- Non-runtime identifiers/file names (for example `hosts.stellaops.local` file path).
|
||||
|
||||
## Active webservices
|
||||
| Domain | Webservice | Local hostname | Purpose | Persistence | Source path | Owner module |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| AdvisoryAI | AdvisoryAI | `advisoryai.stella-ops.local` | Advisory assistant APIs (chat, evidence-pack, knowledge search). | postgres | `src/AdvisoryAI/StellaOps.AdvisoryAI.WebService` | `src/AdvisoryAI` |
|
||||
| AdvisoryAI | OpsMemory | `opsmemory.stella-ops.local` | Operational memory/query APIs for advisory workflows. | postgres | `src/AdvisoryAI/StellaOps.OpsMemory.WebService` | `src/AdvisoryAI` |
|
||||
| Attestor | Attestor | `attestor.stella-ops.local` | Attestation, witness, and proof-chain APIs. | postgres | `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService` | `src/Attestor` |
|
||||
| Attestor | Signer | `signer.stella-ops.local` | Signing and key-ceremony APIs. | postgres | `src/Attestor/StellaOps.Signer/StellaOps.Signer.WebService` | `src/Attestor` |
|
||||
| Authority | IssuerDirectory | `issuerdirectory.stella-ops.local` | Issuer metadata and trust directory APIs. | postgres | `src/Authority/StellaOps.IssuerDirectory/StellaOps.IssuerDirectory.WebService` | `src/Authority` |
|
||||
| BinaryIndex | BinaryIndex | `binaryindex.stella-ops.local` | Binary index, patch coverage, and resolution APIs. | postgres | `src/BinaryIndex/StellaOps.BinaryIndex.WebService` | `src/BinaryIndex` |
|
||||
| Concelier | Concelier | `concelier.stella-ops.local` | Advisory ingestion and source-management APIs. | postgres | `src/Concelier/StellaOps.Concelier.WebService` | `src/Concelier` |
|
||||
| Concelier | Excititor | `excititor.stella-ops.local` | VEX ingest, linkset, and evidence APIs. | postgres | `src/Concelier/StellaOps.Excititor.WebService` | `src/Concelier` |
|
||||
| Doctor | Doctor | `doctor.stella-ops.local` | Health diagnostics and setup-check APIs. | in-memory (no service DB) | `src/Doctor/StellaOps.Doctor.WebService` | `src/Doctor` |
|
||||
| EvidenceLocker | EvidenceLocker | `evidencelocker.stella-ops.local` | Evidence ingest, bundle, legal hold, and verification APIs. | postgres | `src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.WebService` | `src/EvidenceLocker` |
|
||||
| ExportCenter | ExportCenter | `exportcenter.stella-ops.local` | Export/audit bundle/report APIs. | postgres | `src/ExportCenter/StellaOps.ExportCenter/StellaOps.ExportCenter.WebService` | `src/ExportCenter` |
|
||||
| Findings | Findings.Ledger | `findings.stella-ops.local` | Findings ledger, summary, and evidence graph APIs. | postgres | `src/Findings/StellaOps.Findings.Ledger.WebService` | `src/Findings` |
|
||||
| Findings | RiskEngine | `riskengine.stella-ops.local` | Exploit maturity and risk score APIs. | postgres (in-memory fallback for explicit test profile) | `src/Findings/StellaOps.RiskEngine.WebService` | `src/Findings` |
|
||||
| Integrations | Integrations | `integrations.stella-ops.local` | Integration adapters and endpoint management APIs. | postgres | `src/Integrations/StellaOps.Integrations.WebService` | `src/Integrations` |
|
||||
| JobEngine | JobEngine | `jobengine.stella-ops.local` | Release orchestration, approvals, DAG/workflow APIs. | postgres | `src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService` | `src/JobEngine` |
|
||||
| JobEngine | PacksRegistry | `packsregistry.stella-ops.local` | Pack/provenance/attestation registry APIs. | postgres + seed-fs object payloads | `src/JobEngine/StellaOps.PacksRegistry/StellaOps.PacksRegistry.WebService` | `src/JobEngine` |
|
||||
| JobEngine | Scheduler | `scheduler.stella-ops.local` | Schedule/run planning and event APIs. | postgres | `src/JobEngine/StellaOps.Scheduler.WebService` | `src/JobEngine` |
|
||||
| JobEngine | TaskRunner | `taskrunner.stella-ops.local` | Task execution, run state/log, approval, and artifact APIs. | postgres + seed-fs object payloads | `src/JobEngine/StellaOps.TaskRunner/StellaOps.TaskRunner.WebService` | `src/JobEngine` |
|
||||
| Notifier | Notifier | `notifier.stella-ops.local` | Escalation and incident notification APIs. | postgres | `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService` | `src/Notifier` |
|
||||
| Notify | Notify | `notify.stella-ops.local` | Notification rule/channel/template and delivery APIs. | postgres | `src/Notify/StellaOps.Notify.WebService` | `src/Notify` |
|
||||
| Platform | Platform | `platform.stella-ops.local` | Console aggregation, setup, admin, and read-model APIs. | postgres | `src/Platform/StellaOps.Platform.WebService` | `src/Platform` |
|
||||
| ReachGraph | ReachGraph | `reachgraph.stella-ops.local` | Reachability graph and CVE mapping APIs. | postgres | `src/ReachGraph/StellaOps.ReachGraph.WebService` | `src/ReachGraph` |
|
||||
| Remediation | Remediation | `remediation.stella-ops.local` | Remediation source, registry, and match APIs. | postgres | `src/Remediation/StellaOps.Remediation.WebService` | `src/Remediation` |
|
||||
| Replay | Replay | `replay.stella-ops.local` | Point-in-time query and verdict replay APIs. | postgres + seed-fs snapshot blobs | `src/Replay/StellaOps.Replay.WebService` | `src/Replay` |
|
||||
| Router | Gateway | `router.stella-ops.local` | Gateway dispatch, auth, and reverse-proxy APIs. | no-persistence | `src/Router/StellaOps.Gateway.WebService` | `src/Router` |
|
||||
| Scanner | Scanner | `scanner.stella-ops.local` | Scan submission, triage, drift, and scan data APIs. | postgres | `src/Scanner/StellaOps.Scanner.WebService` | `src/Scanner` |
|
||||
| Timeline | Timeline | `timeline.stella-ops.local` | Timeline query/export/replay APIs. | postgres | `src/Timeline/StellaOps.Timeline.WebService` | `src/Timeline` |
|
||||
| Timeline | TimelineIndexer | `timelineindexer.stella-ops.local` | Timeline indexer control/status APIs. | postgres | `src/Timeline/StellaOps.TimelineIndexer.WebService` | `src/Timeline` |
|
||||
| Unknowns | Unknowns | `unknowns.stella-ops.local` | Unknowns queue and triage APIs. | postgres | `src/Unknowns/StellaOps.Unknowns.WebService` | `src/Unknowns` |
|
||||
| VexHub | VexHub | `vexhub.stella-ops.local` | VEX ingest and distribution APIs. | postgres | `src/VexHub/StellaOps.VexHub.WebService` | `src/VexHub` |
|
||||
| VexLens | VexLens | `vexlens.stella-ops.local` | VEX lens, delta, and gate-view APIs. | postgres | `src/VexLens/StellaOps.VexLens.WebService` | `src/VexLens` |
|
||||
|
||||
## Related references
|
||||
- `docs/technical/architecture/port-registry.md`
|
||||
- `docs/modules/router/webservices-valkey-rollout-matrix.md`
|
||||
- `docs/implplan/CONSOLIDATION_WEBSERVICE_FUNCTION_DB_MATRIX_20260305.md`
|
||||
Reference in New Issue
Block a user