feat: complete open ecosystem upgrade package with marketplace ops, observability, tests, and docs

Author: rwilliamspbg-ops

Dockerfile.frontend

@@ -4,6 +4,8 @@ WORKDIR /app
 COPY frontend/package*.json ./
 RUN npm install
 COPY frontend/ ./
+ARG VITE_DEFAULT_VIEW=hud
+ENV VITE_DEFAULT_VIEW=${VITE_DEFAULT_VIEW}
 RUN npm run build
 
 # Stage 2: Serve

Makefile

@@ -164,9 +164,9 @@ check: fmt vet lint-soft test
 alerts-test:
 	@echo "🚨 Running Prometheus alert rule tests..."
 	@docker run --rm --entrypoint /bin/promtool -v "$$(pwd):/workspace" -w /workspace prom/prometheus:v2.48.0 \
-		check rules fl_slo_alerts.yml fl_detailed_alerts.yml tpm_alerts.yml
+		check rules fl_slo_alerts.yml fl_detailed_alerts.yml tpm_alerts.yml marketplace_alerts.yml
 	@docker run --rm --entrypoint /bin/promtool -v "$$(pwd):/workspace" -w /workspace prom/prometheus:v2.48.0 \
-		test rules fl_slo_alerts.test.yml fl_detailed_alerts.test.yml tpm_alerts.test.yml
+		test rules fl_slo_alerts.test.yml fl_detailed_alerts.test.yml tpm_alerts.test.yml marketplace_alerts.test.yml
 	@$(GO) test ./internal/monitoring -run "TestAlertmanagerRoutingPolicy|TestAlertmanagerInhibitionPolicy"
 	@echo "✅ Alert rule tests passed"
 

README.md

@@ -21,6 +21,8 @@ Production-grade federated learning platform that combines Byzantine-resilient a
 [![Dashboards Upgrade](https://img.shields.io/badge/Grafana-STARRED%20Live%20Dashboards-f59e0b?style=flat-square&logo=grafana&logoColor=white)](grafana/provisioning/dashboards)
 [![PySyft Demo](https://img.shields.io/badge/PySyft-Mohawk%20PoC%20Ready-10b981?style=flat-square)](examples/pysyft-integration)
 [![Prometheus Ready](https://img.shields.io/badge/Prometheus-Scrape%20Ready-ef4444?style=flat-square&logo=prometheus&logoColor=white)](prometheus.yml)
+[![Open Ecosystem](https://img.shields.io/badge/Open%20Ecosystem-Sprint%203%20Local--First-0ea5e9?style=flat-square)](docs/OPEN_ECOSYSTEM_FIRST_10_MINUTES.md)
+[![Marketplace Alerts](https://img.shields.io/badge/Alerts-Marketplace%20Guardrails-f97316?style=flat-square)](marketplace_alerts.yml)
 
 ## Mobile Shield Update March 2026
 
@@ -80,6 +82,34 @@ Operator validation commands:
 - `make observability-smoke`
 - `python3 scripts/check_dashboard_queries.py`
 
+## Open Ecosystem Upgrade March 2026
+
+This upgrade package adds a local-first marketplace and governance workflow with production-facing observability guardrails.
+
+What is included:
+
+- Marketplace flows: offers, intents, matching, escrow release, dispute workflows, and governance proposals/voting.
+- Network expansion flows: attestation sharing, self-service invite requests, admin approval/rejection/revocation.
+- Dashboard and metrics integration: marketplace/governance snapshots in `/metrics_summary` and expanded HUD browser demo controls.
+- Prometheus additions: `marketplace_alerts.yml` with stall/high-watermark detection plus promtool tests in `marketplace_alerts.test.yml`.
+- API contract tests: local positive-path and negative-path coverage under `tests/scripts/python/test_marketplace_local_contracts.py` and `tests/scripts/python/test_marketplace_negative_paths.py`.
+
+Primary references:
+
+- First 10 minutes guide: [docs/OPEN_ECOSYSTEM_FIRST_10_MINUTES.md](docs/OPEN_ECOSYSTEM_FIRST_10_MINUTES.md)
+- Sprint 1 roadmap: [docs/OPEN_ECOSYSTEM_SPRINT1_ROADMAP.md](docs/OPEN_ECOSYSTEM_SPRINT1_ROADMAP.md)
+- Sprint 2 roadmap: [docs/OPEN_ECOSYSTEM_SPRINT2_ROADMAP.md](docs/OPEN_ECOSYSTEM_SPRINT2_ROADMAP.md)
+- API examples: [docs/api/http-examples.md](docs/api/http-examples.md)
+- Backend implementation: [sovereignmap_production_backend_v2.py](sovereignmap_production_backend_v2.py)
+- Grafana operations dashboard: [grafana/provisioning/dashboards/operations_overview.json](grafana/provisioning/dashboards/operations_overview.json)
+
+Validation commands:
+
+- `make observability-smoke`
+- `make alerts-test`
+- `python3 tests/scripts/python/test_marketplace_local_contracts.py`
+- `python3 tests/scripts/python/test_marketplace_negative_paths.py`
+
 ## Performance Tuning Knobs
 
 The following environment variables are available for safe runtime tuning:

dashboard_compat_rules.yml

@@ -94,10 +94,10 @@ groups:
         expr: tpm_ca_certificate_valid
 
       # per-node trust score: verified/total ratio when certs exist;
-      # "> -Inf" filters out NaN (0/0 case) so the "or" fallback to CA validity
-      # triggers correctly when no certificates have been issued yet.
+      # clamp/min guards keep this finite and in the expected 0-100 range,
+      # while fallback uses CA validity when no certificates are present.
       - record: tpm_node_trust_score
-        expr: (tpm_certificates_verified_total / tpm_certificates_total > -Inf) or tpm_ca_certificate_valid
+        expr: (clamp_max(100 * (tpm_certificates_verified_total / clamp_min(tpm_certificates_total, 1)), 100) and (tpm_certificates_total > 0)) or (100 * tpm_ca_certificate_valid)
 
       # message signing operations — proxy via total certificate issuances
       - record: tpm_messages_signed_total

docker-compose.full.yml

@@ -4,6 +4,8 @@ services:
     build:
       context: .
       dockerfile: Dockerfile.frontend
+      args:
+        VITE_DEFAULT_VIEW: ${VITE_DEFAULT_VIEW:-hud}
     image: frontend:latest
     container_name: sovereign-frontend
     ports:
@@ -15,6 +17,24 @@ services:
     networks:
       - sovereign-network
     restart: always
+
+  frontend-admin:
+    build:
+      context: .
+      dockerfile: Dockerfile.frontend
+      args:
+        VITE_DEFAULT_VIEW: browser_demo
+    image: frontend-admin:latest
+    container_name: sovereign-frontend-admin
+    ports:
+      - "${FRONTEND_ADMIN_HOST_PORT:-3003}:80"
+    environment:
+      - NODE_ENV=production
+    depends_on:
+      - backend
+    networks:
+      - sovereign-network
+    restart: always
   # ========================================================================
   # SOVEREIGN MAPS BACKEND (Flower Aggregator + Flask Metrics)
   # ========================================================================

docs/ALERT_RUNBOOKS.md

@@ -7,8 +7,8 @@ This document defines first-response procedures for SLO and consensus alerts.
 ### Routing and Inhibition Baseline
 
 - Route policy source: [alertmanager.yml](../alertmanager.yml)
-- Rule sources: [fl_slo_alerts.yml](../fl_slo_alerts.yml), [fl_detailed_alerts.yml](../fl_detailed_alerts.yml), [tpm_alerts.yml](../tpm_alerts.yml)
-- Unit test sources: [fl_slo_alerts.test.yml](../fl_slo_alerts.test.yml), [fl_detailed_alerts.test.yml](../fl_detailed_alerts.test.yml), [tpm_alerts.test.yml](../tpm_alerts.test.yml), [internal/monitoring/alertmanager_config_test.go](../internal/monitoring/alertmanager_config_test.go)
+- Rule sources: [fl_slo_alerts.yml](../fl_slo_alerts.yml), [fl_detailed_alerts.yml](../fl_detailed_alerts.yml), [tpm_alerts.yml](../tpm_alerts.yml), [marketplace_alerts.yml](../marketplace_alerts.yml)
+- Unit test sources: [fl_slo_alerts.test.yml](../fl_slo_alerts.test.yml), [fl_detailed_alerts.test.yml](../fl_detailed_alerts.test.yml), [tpm_alerts.test.yml](../tpm_alerts.test.yml), [marketplace_alerts.test.yml](../marketplace_alerts.test.yml), [internal/monitoring/alertmanager_config_test.go](../internal/monitoring/alertmanager_config_test.go)
 
 Inhibition semantics:
 
@@ -66,9 +66,9 @@ Inhibition semantics:
 
 ### Coverage Summary
 
-- Total alerts configured: 34
-- Alerts with explicit runbook section in this document: 16
-- Alerts with promtool rule unit tests: 34
+- Total alerts configured: 36
+- Alerts with explicit runbook section in this document: 18
+- Alerts with promtool rule unit tests: 36
 - Alertmanager routing and inhibition policy tests: covered by internal/monitoring/alertmanager_config_test.go
 
 ## FLRoundStalled
@@ -166,3 +166,15 @@ Inhibition semantics:
 - Verify replay rate trend from `mohawk_tpm_nonce_replay_rejections_total` and determine whether it is expected (duplicate retries) or anomalous (nonce generation collision/replay attack).
 - Correlate with client retry storms and transport retransmissions; high replay without failure spikes usually indicates duplicate delivery.
 - If anomalous, rotate nonce derivation context for the affected round and audit ingress paths for duplicate submissions.
+
+## MarketplaceEscrowStalled
+
+- Confirm `sovereign_marketplace_escrow_locked` is non-zero and verify `increase(sovereign_marketplace_payout_total[30m]) == 0` in Prometheus UI.
+- Inspect pending contracts via `/marketplace/contracts?payout_status=pending` and verify no active disputes are blocking payout release.
+- Triage release path by checking `/marketplace/escrow/release` API logs and recent governance actions for moderation holds.
+
+## MarketplaceEscrowHighWatermark
+
+- Validate current locked amount against expected round budget and contract volume.
+- Inspect for stale contracts that remain pending after round completion and release in controlled batches.
+- If sustained, tighten intent budget limits or increase release cadence to keep escrow within policy bounds.

docs/OPEN_ECOSYSTEM_FIRST_10_MINUTES.md

@@ -0,0 +1,90 @@
+# Open Ecosystem First 10 Minutes (Local)
+
+This guide runs entirely local.
+
+## Prerequisites
+
+1. Backend API available at `http://localhost:8000`.
+2. Frontend available at `http://localhost:3000` (or local Vite port).
+
+## 1. Create Offer
+
+```bash
+curl -s -X POST http://localhost:8000/marketplace/offers \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "seller_node_id": "node-quickstart-1",
+    "dataset_fingerprint": "sha256:quickstart-local-001",
+    "title": "Quickstart Image Pack",
+    "modality": "image",
+    "quality_score": 0.84,
+    "allowed_tasks": ["classification"],
+    "price_per_round": 10.0,
+    "min_rounds": 1,
+    "attestation_status": "verified"
+  }' | jq
+```
+
+## 2. Create Intent
+
+```bash
+curl -s -X POST http://localhost:8000/marketplace/round_intents \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model_owner_id": "owner-quickstart",
+    "task_type": "classification",
+    "required_modalities": ["image"],
+    "min_quality_score": 0.7,
+    "budget_total": 100
+  }' | jq
+```
+
+Capture `round_intent_id` from the response.
+
+## 3. Match Contract
+
+```bash
+curl -s -X POST http://localhost:8000/marketplace/match \
+  -H 'Content-Type: application/json' \
+  -d '{"round_intent_id": "intent-REPLACE_ME", "max_offers": 3}' | jq
+```
+
+Capture `contract_id` from the response.
+
+## 4. Trigger One Training Round
+
+```bash
+curl -s -X POST http://localhost:8000/trigger_fl | jq
+```
+
+## 5. Release Escrow
+
+```bash
+curl -s -X POST http://localhost:8000/marketplace/escrow/release \
+  -H 'Content-Type: application/json' \
+  -d '{"contract_id": "contract-REPLACE_ME"}' | jq
+```
+
+## 6. Inspect Contract Timeline and Metrics
+
+```bash
+curl -s http://localhost:8000/marketplace/contracts | jq '.contracts[0].timeline'
+curl -s http://localhost:8000/training/status | jq '.marketplace_pending_contract'
+curl -s http://localhost:8000/metrics_summary | jq '.marketplace'
+```
+
+## Troubleshooting
+
+1. `no_compatible_offers_found`:
+
+- Check `details.rejection_reasons` in response.
+- Increase `budget_total` or reduce quality threshold.
+
+1. `round_intent_not_open`:
+
+- Intent was already matched/cancelled/closed.
+- Create a new intent or patch status appropriately.
+
+1. `contract_already_released`:
+
+- Escrow for that contract is already released.

docs/OPEN_ECOSYSTEM_SPRINT1_ROADMAP.md

@@ -0,0 +1,82 @@
+# Open Ecosystem Sprint 1 Roadmap
+
+## Sprint Goal
+
+Deliver a user-friendly local-first marketplace loop that a new user can complete in one session:
+
+1. Create offer
+2. Create intent
+3. Match contract
+4. Trigger training round
+5. Release escrow
+6. Inspect timeline and metrics
+
+## Duration
+
+- 2 weeks
+
+## Scope
+
+### P0 (Must Deliver)
+
+1. Deterministic marketplace API error codes and messages.
+2. Match failure diagnostics to explain why offers did not match.
+3. Contract lifecycle timeline (created -> bound_to_round -> escrow_released).
+4. Dashboard visibility for pending contracts and marketplace summary.
+5. Positive and negative-path local tests.
+6. First-10-minutes onboarding guide.
+
+### P1 (If Capacity Allows)
+
+1. UI score breakdown view (quality, cost, trust).
+2. Intent status workflow guardrails in controls.
+3. Lightweight policy preview before matching.
+
+## User Stories
+
+1. As a data provider, I can create an offer with clear field guidance and immediate validation.
+2. As a model owner, I can understand exactly why matching failed.
+3. As an operator, I can see contract state transitions in chronological order.
+4. As a reviewer, I can verify ecosystem activity through metrics and operation events.
+5. As a new integrator, I can finish the full local flow in 10 minutes.
+
+## Acceptance Criteria
+
+1. Marketplace endpoints return stable error codes and messages on all validation failures.
+2. Match failure includes machine-readable rejection reasons and counts.
+3. Every matched contract includes timeline events.
+4. `training/status` includes the pending contract summary.
+5. `metrics_summary` includes marketplace snapshot.
+6. Local smoke and negative tests pass.
+7. Frontend build passes.
+
+## Risks and Mitigations
+
+1. Risk: ambiguous match outcomes.
+
+- Mitigation: include rejection reason counters and budget rejection count.
+
+1. Risk: accidental status misuse.
+
+- Mitigation: enforce intent status transitions server-side.
+
+1. Risk: duplicate escrow release.
+
+- Mitigation: explicit `contract_already_released` error.
+
+## Definition of Done
+
+1. Backend, frontend, tests, and docs updated.
+2. No diagnostics errors in touched files.
+3. Local backend marketplace smoke test passes.
+4. Local backend negative-path test passes.
+5. Frontend production build passes.
+
+## Demo Checklist
+
+1. Create an offer from the UI.
+2. Create an intent from the UI.
+3. Run a match and inspect status.
+4. Trigger one FL round and inspect contract binding.
+5. Release escrow and confirm updated timeline.
+6. Inspect marketplace section in `/metrics_summary`.

docs/OPEN_ECOSYSTEM_SPRINT2_ROADMAP.md

@@ -0,0 +1,55 @@
+# Open Ecosystem Sprint 2 Roadmap
+
+## Sprint Goal
+
+Deliver trust and governance transparency for marketplace operations:
+
+1. Explainable scoring in matching outcomes.
+2. Local dispute workflow for contract issues.
+3. Governance action logging surfaces.
+4. Dashboard visibility for dispute and governance activity.
+
+## Duration
+
+- 2 weeks
+
+## Scope
+
+### P0 (Must Deliver)
+
+1. Match score breakdown included per selected offer.
+2. Governance activity endpoints (create/list).
+3. Dispute endpoints (create/list/update).
+4. Metrics summary governance snapshot.
+5. UI rendering of score breakdown and governance activity.
+6. Automated test coverage for new endpoints.
+
+### P1 (If Capacity Allows)
+
+1. Dispute SLA timers and escalation status.
+2. Governance action filtering by actor and source.
+3. Policy proposal voting workflow stub.
+
+## User Stories
+
+1. As a buyer, I can see why an offer was selected using score components.
+2. As an operator, I can submit disputes for problematic contracts.
+3. As a moderator, I can update dispute status and leave resolution notes.
+4. As a governance observer, I can see recent governance actions in one view.
+
+## Acceptance Criteria
+
+1. `/marketplace/match` includes `score_breakdown` and `selection_diagnostics`.
+2. `/marketplace/disputes` supports create/list.
+3. `/marketplace/disputes/<id>` supports status updates.
+4. `/governance/actions` supports create/list.
+5. `/metrics_summary` includes governance snapshot.
+6. Frontend displays score breakdown and recent governance actions.
+7. Local tests and frontend build pass.
+
+## Definition of Done
+
+1. Backend API endpoints implemented and documented.
+2. Frontend views expose explainability and governance visibility.
+3. Tests validate score, dispute, and governance workflows.
+4. No diagnostics errors in touched files.