Merge feature/digital-twin-mesh-artifacts

# Conflicts:
#	internal/api/handlers.go
#	internal/api/handlers_test.go
#	internal/api/ledger_sql.go
#	requirements-ci.txt

Author: rwilliamspbg-ops

Documentation/Security/QUANTUM_KEX_DRILL_RETENTION_POLICY.md

@@ -0,0 +1,47 @@
+<!-- markdownlint-disable MD022 MD032 -->
+
+# Quantum KEX Drill Retention Policy
+
+## Purpose
+Define incident-grade retention controls for Quantum KEX drill evidence bundles.
+
+## Policy Controls
+- Classification: security-compliance-evidence
+- Minimum retention window: 2555 days (7 years)
+- Immutability requirement: required
+- Integrity requirement: required checksum catalog (`checksums.sha256`)
+
+## Required Storage Controls
+- Use immutable object storage with object lock/WORM semantics.
+- Enable cross-region replication for disaster resilience.
+- Restrict deletion permissions to break-glass roles only.
+
+## Transfer and Verification Procedure
+1. Generate artifact bundle with `make quantum-kex-rotation-drill`.
+1. Validate local checksums:
+
+```bash
+cd artifacts/quantum-kex-rotation/<drill-id>
+sha256sum -c checksums.sha256
+```
+
+1. Upload to immutable storage path:
+
+```text
+security-evidence/quantum-kex-rotation/<drill-id>/
+```
+
+1. Re-validate checksums after download from immutable storage.
+1. Record storage URI and verification timestamp in your governance ledger/report.
+
+## Audit Expectations
+- Every drill must include:
+  - `drill-summary.json`
+  - `checksums.sha256`
+  - `retention-policy.json`
+  - `immutability-notice.txt`
+- Keep the rolling public index (`public-drill-index.md`) aligned with the latest 12 drills.
+
+## Exception Handling
+- If immutable storage is unavailable, mark the drill as provisional and complete immutable archival within 24 hours.
+- If checksum verification fails at any stage, open incident triage and invalidate public claims for that drill until remediated.

Documentation/Security/QUANTUM_KEX_ROTATION_DRILL_RUNBOOK.md

@@ -0,0 +1,128 @@
+<!-- markdownlint-disable MD022 MD032 -->
+
+# Quantum KEX Rotation Drill Runbook (Genesis Testnet)
+
+## Purpose
+This runbook defines a public, repeatable post-quantum key exchange (KEX) rotation drill on Genesis Testnet.
+
+The drill demonstrates three things in one auditable sequence:
+1. Transport security controls execute a key rotation path successfully.
+2. Proof verification and ledger writes remain healthy before and after rotation.
+3. Operators can publish a concrete evidence bundle for community and investor review.
+
+## Scope
+- Environment: Genesis Testnet
+- Runtime surface: node-agent auth-gated proof and ledger endpoints
+- Evidence source: local artifact bundle produced by the drill script
+
+## Controls Exercised
+- Session key rotation pathway in crypto transport tests:
+  - TestRotateSessionKeyNoDeadlock
+  - TestRotateSessionKeyReestablishesSharedSecret
+  - TestHandshakeVerification
+- Hybrid verification continuity:
+  - POST /api/v1/proof/hybrid/verify
+- Fallback backend rehearsal:
+  - POST /api/v1/proof/hybrid/verify with `stark_backend=winterfell_mock`
+- Ledger integrity continuity:
+  - GET /api/v1/ledger
+  - GET /api/v1/ledger/reconcile
+- Role policy enforcement negative-path:
+  - GET /api/v1/ledger with unauthorized role (expects 401/403)
+
+## Preconditions
+- Genesis Testnet stack reachable, with node-agent endpoint available.
+- API token available via one of:
+  - MOHAWK_API_TOKEN environment variable
+  - MOHAWK_API_TOKEN_FILE (default /run/secrets/mohawk_api_token)
+- Tooling: curl, go, python3
+
+## Execution
+### Recommended one-command path
+
+```bash
+make quantum-kex-rotation-drill
+```
+
+### Direct script path
+
+```bash
+NODE_AGENT_BASE_URL=http://localhost:8082 \
+MOHAWK_API_TOKEN_FILE=/run/secrets/mohawk_api_token \
+bash scripts/quantum-kex-rotation-drill.sh
+```
+
+### Optional explicit token override
+
+```bash
+NODE_AGENT_BASE_URL=http://localhost:8082 \
+MOHAWK_API_TOKEN="<redacted-token>" \
+bash scripts/quantum-kex-rotation-drill.sh
+```
+
+## Artifact Output
+Default output directory:
+
+```text
+artifacts/quantum-kex-rotation/<drill-id>/
+```
+
+Expected files:
+- readiness_pre.json
+- ledger_pre.json
+- hybrid_verify_pre_rotation.json
+- crypto_rotation_test.log
+- hybrid_verify_post_rotation.json
+- hybrid_verify_fallback_backend.json
+- role_failure_negative_response.txt
+- role_failure_negative_test.json
+- ledger_post.json
+- ledger_reconcile_post.json
+- retention-policy.json
+- immutability-notice.txt
+- checksums.sha256
+- drill-summary.json
+- drill-summary.md
+
+Generated cross-run index files:
+- artifacts/quantum-kex-rotation/public-drill-index.json
+- artifacts/quantum-kex-rotation/public-drill-index.md
+
+## Success Criteria
+- Readiness pre-check is true.
+- Hybrid verification accepted both before and after rotation tests.
+- Fallback backend rehearsal is accepted.
+- Unauthorized role negative test returns 401/403.
+- Ledger reconciliation healthy after the drill.
+- Ledger entry count increases by at least 2 during the drill.
+- All artifact files present and readable.
+
+## Public Disclosure Template
+Use the generated drill summary values and publish a concise statement:
+
+```text
+Genesis Testnet Quantum KEX Rotation Drill complete.
+
+- Drill ID: <drill-id>
+- Window (UTC): <start> -> <end>
+- Pre/Post hybrid verification accepted: true/true
+- Ledger reconcile healthy after drill: true
+- Ledger entries added: <n>
+
+Evidence bundle path: artifacts/quantum-kex-rotation/<drill-id>/
+```
+
+## Operational Notes
+- This drill is non-destructive and uses existing verification endpoints.
+- If auth fails, recheck token source and X-API-Role permissions.
+- If reconciliation fails, stop public messaging and open incident triage before rerun.
+
+## Retention and Compliance
+- Canonical policy: [Documentation/Security/QUANTUM_KEX_DRILL_RETENTION_POLICY.md](Documentation/Security/QUANTUM_KEX_DRILL_RETENTION_POLICY.md)
+- Treat each bundle as immutable security evidence for at least 2555 days.
+- Validate `checksums.sha256` before and after archival transfer.
+
+## Suggested Cadence Through 2027 Epoch Deadline
+- Public drill cadence: monthly
+- Add an additional ad hoc drill after any transport/auth policy change
+- Keep the last 12 drill summaries in release and governance reporting channels

Makefile

@@ -216,6 +216,10 @@ testnet-wallet-readiness:
 	@echo "🧪 Running testnet wallet readiness checks..."
 	@bash scripts/testnet-wallet-readiness.sh
 
+quantum-kex-rotation-drill:
+	@echo "🔐 Running Genesis Testnet Quantum KEX Rotation Drill..."
+	@bash scripts/quantum-kex-rotation-drill.sh
+
 # =============================================================================
 # Development Helpers
 # =============================================================================
@@ -281,5 +285,6 @@ help:
 	@echo "  make observability-live-smoke - Validate lower-half operations panel queries against live Prometheus"
 	@echo "  make compose-service-drift-check - Detect stale compose service names in scripts"
 	@echo "  make quickstart-verify - Run onboarding-safe baseline verification targets"
+	@echo "  make quantum-kex-rotation-drill - Run public Genesis Testnet KEX rotation evidence drill"
 	@echo "  make check   - Run all checks"
 	@echo ""

README.md

@@ -63,6 +63,32 @@ Documentation entrypoint: [docs/README.md](docs/README.md)
 
 For current roadmap status and remaining open items, see [Documentation/Performance/OPS_OPTIMIZATION_ROADMAP_2026-03-24.md](Documentation/Performance/OPS_OPTIMIZATION_ROADMAP_2026-03-24.md) and [Documentation/Project/ROADMAP.md](Documentation/Project/ROADMAP.md).
 
+## Quantum KEX Rotation Drill (Genesis Testnet)
+
+The repository includes a public-facing Genesis Testnet drill to demonstrate post-quantum migration readiness with auditable artifacts.
+
+Run the drill:
+
+```bash
+make quantum-kex-rotation-drill
+```
+
+Or run directly with explicit endpoint/token inputs:
+
+```bash
+NODE_AGENT_BASE_URL=http://localhost:8082 \
+MOHAWK_API_TOKEN_FILE=/run/secrets/mohawk_api_token \
+bash scripts/quantum-kex-rotation-drill.sh
+```
+
+Operator runbook and disclosure guidance:
+
+- [Documentation/Security/QUANTUM_KEX_ROTATION_DRILL_RUNBOOK.md](Documentation/Security/QUANTUM_KEX_ROTATION_DRILL_RUNBOOK.md)
+
+Artifact output:
+
+- `artifacts/quantum-kex-rotation/<drill-id>/`
+
 ## New Contributor Fast Path
 
 If you just cloned the repo and want to run tests quickly, use this sequence.

internal/api/handlers.go

@@ -358,15 +358,17 @@ func (h *Handler) HealthCheck(w http.ResponseWriter, r *http.Request) {
 		status = "degraded"
 	}
 
+	// Error details are omitted from this unauthenticated endpoint to avoid
+	// leaking internal connection strings or credentials. Full details are
+	// available on the auth-protected /api/v1/ledger endpoint.
 	response := map[string]interface{}{
 		"status":  status,
 		"service": "sovereign-map-fl",
 		"time":    time.Now().UTC().Format(time.RFC3339),
 		"ledger": map[string]interface{}{
 			"ready":        ledgerReady,
 			"storage_mode": h.ledger.StorageMode(),
-			"init_error":   h.ledgerInitError,
-			"error":        ledgerErr,
+			"has_error":    strings.TrimSpace(ledgerErr) != "" || strings.TrimSpace(h.ledgerInitError) != "",
 		},
 	}
 
@@ -390,15 +392,17 @@ func (h *Handler) ReadinessCheck(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("X-API-Version", "v1")
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
+	// Error details are omitted from this unauthenticated endpoint to avoid
+	// leaking internal connection strings or credentials. Full details are
+	// available on the auth-protected /api/v1/ledger endpoint.
 	_ = json.NewEncoder(w).Encode(map[string]interface{}{
 		"ready":   ready,
 		"service": "sovereign-map-fl",
 		"time":    time.Now().UTC().Format(time.RFC3339),
 		"ledger": map[string]interface{}{
 			"ready":        ledgerReady,
 			"storage_mode": h.ledger.StorageMode(),
-			"init_error":   h.ledgerInitError,
-			"error":        ledgerErr,
+			"has_error":    strings.TrimSpace(ledgerErr) != "" || strings.TrimSpace(h.ledgerInitError) != "",
 		},
 	})
 }
@@ -1041,11 +1045,14 @@ func (h *Handler) GetCapabilities(w http.ResponseWriter, r *http.Request) {
 				"mohawk_ledger_events_total",
 				"mohawk_ledger_entries",
 			},
+			// Error details are omitted from this unauthenticated endpoint to avoid
+			// leaking internal connection strings or credentials. Full details are
+			// available on the auth-protected /api/v1/ledger endpoint.
 			"ledger_state": map[string]interface{}{
 				"entries":      h.ledger.Len(),
 				"capacity":     h.ledger.Capacity(),
 				"storage_mode": h.ledger.StorageMode(),
-				"init_error":   h.ledgerInitError,
+				"has_error":    strings.TrimSpace(h.ledgerInitError) != "",
 			},
 		},
 	}

internal/api/handlers_test.go

@@ -663,8 +663,8 @@ func TestCockroachBackendFallbackMetadata(t *testing.T) {
 	if ledgerState["storage_mode"] != "cockroach-compatible-inmemory" {
 		t.Fatalf("storage_mode = %v, want cockroach-compatible-inmemory fallback", ledgerState["storage_mode"])
 	}
-	if ledgerState["init_error"] == "" {
-		t.Fatalf("init_error should be populated for fallback: %v", ledgerState)
+	if ledgerState["has_error"] != true {
+		t.Fatalf("has_error should be true for fallback: %v", ledgerState)
 	}
 }
 

internal/api/ledger_sql.go

@@ -201,19 +201,29 @@ func (l *SQLProofLedger) RecordWithOptions(eventType string, proofBytes []byte,
 	return entry, false
 }
 
+// Entries returns ledger rows in ascending order. In SQL mode, l.cap limits only
+// how many rows are returned by this query; it does not prune or retain rows in
+// mohawk_ledger_entries. SQL retention must be managed externally (for example,
+// by a database TTL policy or cleanup job).
 func (l *SQLProofLedger) Entries() []LedgerEntry {
 	query := `SELECT id, entry_id, stream_id, seq_no, created_at, event_type, proof_hash, prev_hash, entry_hash, idempotency_key, role, accepted, latency_ms, error_text
 		FROM mohawk_ledger_entries ORDER BY id DESC`
 	args := []interface{}{}
 	if l.cap > 0 {
+		// cap is a read/query limit only; it does not enforce SQL row retention.
 		query += ` LIMIT $1`
 		args = append(args, l.cap)
 	}
 	rows, err := l.db.Query(query, args...)
 	if err != nil {
 		return []LedgerEntry{}
 	}
-	defer rows.Close()
+	defer func() {
+		if closeErr := rows.Close(); closeErr != nil {
+			// Preserve existing method contract (best-effort, empty-on-error behavior).
+			_ = closeErr
+		}
+	}()
 
 	entries := make([]LedgerEntry, 0)
 	for rows.Next() {
@@ -257,7 +267,12 @@ func (l *SQLProofLedger) Checkpoints() []LedgerCheckpoint {
 	if err != nil {
 		return []LedgerCheckpoint{}
 	}
-	defer rows.Close()
+	defer func() {
+		if closeErr := rows.Close(); closeErr != nil {
+			// Preserve existing method contract (best-effort, empty-on-error behavior).
+			_ = closeErr
+		}
+	}()
 
 	out := make([]LedgerCheckpoint, 0)
 	for rows.Next() {

internal/crypto/secure_comm_test.go

@@ -3,6 +3,7 @@
 package crypto
 
 import (
+	"bytes"
 	"crypto/ecdsa"
 	"crypto/elliptic"
 	"crypto/rand"
@@ -111,6 +112,46 @@ func TestRotateSessionKeyNoDeadlock(t *testing.T) {
 	}
 }
 
+func TestRotateSessionKeyReestablishesSharedSecret(t *testing.T) {
+	alice, _ := NewSecureChannel()
+	bob, _ := NewSecureChannel()
+	_ = alice.RegisterPeer("bob", bob.publicKey)
+
+	if _, err := alice.EncryptMessage("bob", []byte("baseline")); err != nil {
+		t.Fatalf("initial encrypt: %v", err)
+	}
+
+	alice.mu.RLock()
+	original := append([]byte(nil), alice.sessionKeys["bob"]...)
+	alice.mu.RUnlock()
+	if len(original) == 0 {
+		t.Fatal("expected non-empty pre-rotation session key")
+	}
+
+	// Simulate a bad cached key and verify rotation reconstructs the canonical key.
+	forged := bytes.Repeat([]byte{0x42}, len(original))
+	alice.mu.Lock()
+	alice.sessionKeys["bob"] = append([]byte(nil), forged...)
+	alice.mu.Unlock()
+
+	if err := alice.RotateSessionKey("bob"); err != nil {
+		t.Fatalf("RotateSessionKey: %v", err)
+	}
+
+	alice.mu.RLock()
+	after := append([]byte(nil), alice.sessionKeys["bob"]...)
+	alice.mu.RUnlock()
+	if len(after) == 0 {
+		t.Fatal("expected non-empty post-rotation session key")
+	}
+	if bytes.Equal(after, forged) {
+		t.Fatal("expected rotation to replace forged cached key")
+	}
+	if !bytes.Equal(after, original) {
+		t.Fatal("expected rotation to re-establish canonical shared secret")
+	}
+}
+
 // TestHandshakeVerification performs an in-memory TLS 1.3 handshake and
 // asserts the negotiated version is TLS 1.3.
 func TestHandshakeVerification(t *testing.T) {

requirements-ci.txt

@@ -1 +1 @@
-numpy==2.3.4
+numpy==2.4.4