Hwcontract MCP server

<!-- mcp-name: io.github.MohibShaikh/hwcontract -->

hwcontract

Your firmware is correct on paper and wrong on the wire.

Coding agents write WS2812 drivers, ESC bitstreams, and boot logs that pass review and then fail the moment the signal hits a real chip. hwcontract closes that loop. It captures what the hardware actually did and returns a verdict you can act on:

cold board in the field. It fails the verdict: the judge will not ship it.

• pass: within spec
• marginal: in spec but too close to a rail. Works on your bench, dies on a

• fail: out of spec, with the measured value and how far off it is

Two things a green verdict gives you beyond the table:

pulse distribution; a glitchy tail that a median hides comes back as marginal or fail, with the violating-pulse count in the hint.

• Every pulse is judged, not just the median. Captures carry the full

parameters, tool version, timestamp. A green build in CI traces back to the exact bytes that produced it.

• Evidence on every verdict: contract hash, capture hash, capture

No hardware in your hand? The demo below runs the whole thing on a real recorded signal, so you can see exactly what you get before wiring anything up.

See it work in 30 seconds

pip install hwcontract
python3 -m hwcontract.judge --demo

That judges a real 24-LED NeoPixel capture against two contracts. Same signal, two verdicts:

measured on the real WS2812B signal (300000 samples @24MHz):
  T0H 333 ns   T1H 833 ns   T1L 417 ns   T0L 917 ns   RESET 992250 ns

=== generic WS2812 contract -> FAIL ===
  T0H     350   333  PASS
  T0L     800   917  MARGINAL  only 33ns from max; nudge toward typ 800
  T1H     700   833  MARGINAL  only 17ns from max; nudge toward typ 700
  T1L     600   417  FAIL      183ns short (typ 600)
  RESET 50000    -  PASS

=== matching WS2812B contract -> PASS ===
  (all five edges PASS)

Same hardware, two contracts: the generic one fails, the chip-specific one passes. A WS2812B isn't a WS2812. Measure the real signal, hold it to a spec, and match the contract to the actual chip.

See the temporal engine catch a DMA bug

python3 demo/spi_dma_temporal.py

100 synthesized SPI frames as raw CS/SCK/MOSI waveforms at 100MHz, reduced to pin edges and judged against the bundled spi-frame contract. Frame 77 has the Zephyr LPSPI DMA fault: chip-select asserts after the clock starts. Frame 42 settles MOSI 10ns before the sampling edge. Both come back with exact timestamps, and the same broken edges are re-imported as sigrok-style B/E jsontrace annotations:

cs-precedes-first-clock  800  1  FAIL  trigger at 1540310ns: no gpio.cs.falling
                                          in [1530310ns, 1540310ns] (first of 1)
mosi-setup               800  1  FAIL  forbidden spi.mosi.* at 843300ns is 10ns
                                          before spi.sck.rising at 843310ns

The data is perfect in all 100 frames; a loopback test passes. The ordering is broken in two, and only a cross-signal assertion notices.

What you get

Shortened. The full README is on GitHub.