[GreenGrassBlueOcean]

Overview

This PR integrates direct, low-latency empirical firmware verification into openwebnet-mcp, grounding OpenWebNet frame validation and agent queries in verified ground truth from the own-firmware-oracle project.

In own-firmware-oracle, OpenWebNet frames are executed inside QEMU-emulated physical gateways (BTicino MH200N firmware 010108 and MyHomeServer1 firmware 028206), capturing exact client session replies (ACK/NACK/SILENT/No reply), bus telegram emissions (hex bytes), and SHA-256 target hashes.

This PR equips openwebnet-mcp to serve these empirical verdicts directly to AI agents and developers during tool calls.

---

Changes

1. Multi-Tier Path Discovery with Provenance Tracking (src/openwebnet_mcp/_paths.py)

• Added resolve_oracle_index() -> tuple[Path | None, str] and get_oracle_index_path() -> Path | None with 3-tier discovery:
  1. OPENWEBNET_ORACLE_INDEX environment variable (explicit file path, logs warning if invalid)
  2. Sibling checkout: ../own-firmware-oracle/results/mcp_index.json
  3. Bundled internal data fallback: src/openwebnet_mcp/data/oracle_index.json
• Exposes source_tier ("env", "sibling", "bundled", "explicit").

2. Bundled Reference Index (src/openwebnet_mcp/data/oracle_index.json)

• Bundled snapshot of mcp_index.json covering 89 unique frames across MH200N (010108) and MyHomeServer1 (028206) firmwares. Ensures standalone distributions (uvx, isolated containers) have immediate out-of-the-box access without requiring a local clone of own-firmware-oracle.

3. Firmware Oracle Engine with Cryptographic Verification (src/openwebnet_mcp/firmware_oracle.py)

• Implemented FirmwareOracle:
  • load() / reload(): Fast JSON parser with format compatibility checking.
  • Cryptographic Hash Verification: Computes canonical JSON SHA-256 digest of verdicts (sort_keys=True, separators=(",", ":")) and compares with verdicts_sha256 recorded in the index. Exposes hash_verified in diagnostics and reports status (verified / MISMATCH).
  • lookup(frame): Exact match lookup with fallback to normalized frame (normalize_frame).
  • format_verdict_markdown(frame, verdicts): Renders a structured markdown table with Gateway, Firmware, Reply (ACK (*#*1##), NACK (*#*0##), SILENT, *No client reply*), Verdict (OUT (Bus), SILENT (Drop)), Bus Frames Emitted, Emitted OWN, Suite, Target SHA, followed by a detailed Ground Truth Analysis section and provenance/integrity footer.
  • Failure Isolation: Clearly distinguishes between index load failure (*⚠️ Oracle index unavailable: ...*) and unverified frames (*Frame has not yet been replayed...*).
  • status(): Diagnostic information on loaded index, gateway targets, verdict counts, source tier, and cryptographic hash verification status.

4. FastMCP Tool & Resource Augmentation (src/openwebnet_mcp/server.py)

• Enriched Tool: parse_and_validate_frame(frame) now includes a ## 🛡️ Empirical Firmware Oracle Verification section showing replay behavior on tested gateways whenever available. The oracle call is isolated in its own exception block so that any oracle error degrades gracefully without failing grammar validation.
• Dedicated Tool: Added @mcp.tool() async def lookup_firmware_verdict(frame: str) -> str backed by _oracle_cache (10 min TTL) for direct programmatic queries.
• Resource: Added @mcp.resource("oracle://index") returning diagnostic status and metadata.
• Cache Management: rescan_documentation flushes _oracle_cache in addition to other caches, ensuring reloaded indexes take effect immediately.
• Rescan Integration: rescan_manager.py reloads the oracle index upon rescan_documentation.
• Boost Prompt: Updated @mcp.prompt("boost") to direct agents to empirical verification tools.

---

Testing & Verification

• Added tests/test_firmware_oracle.py testing frame normalization, index loading, canonical hash verification (success and mismatch), verdict lookups, markdown generation (ACK, NACK, silent, custom, no client reply), status reporting, format version warning, cache reload, and corrupt/missing file resilience.
• Updated tests/test_paths.py testing 3-tier oracle path resolution hierarchy, source tiers, and invalid environment variable warning.
• Updated tests/test_rescan_manager.py verifying oracle reload during rescan.
• Updated tests/test_server.py verifying lookup_firmware_verdict, enriched parse_and_validate_frame, graceful oracle degradation on error, _oracle_cache invalidation on rescan, and oracle://index resource.
• Full Test Suite: 134 passed in 34.53s.
• Coverage: 100% on firmware_oracle.py, 100% on rescan_manager.py, 99% on _paths.py, 95% on server.py, 96% repo-wide.