hwcontract 0.1.0__py3-none-any.whl

hwcontract/__init__.py

@@ -0,0 +1,2 @@
+"""hwcontract: judge hardware timing/serial behavior against a contract."""
+__version__ = "0.1.0"

hwcontract/examples/boot.contract.yaml

@@ -0,0 +1,11 @@
+# Serial/boot-log contract: what the firmware must (and must not) print on boot.
+# Judged with run_serial -> patterns are Python regex.
+contract: boot
+kind: serial
+expect:
+  - "IMU init OK"       # required success line
+  - "boot v\\d+"        # a version banner
+forbid:
+  - "panic"             # crash markers must be absent
+  - "Guru Meditation"   # ESP32 exception handler
+  - "\\bnan\\b"         # NaN sensor reads

hwcontract/examples/dshot.contract.yaml

@@ -0,0 +1,10 @@
+# DShot600: the digital signal a flight controller sends a drone ESC. 16-bit frames,
+# 600 kbit/s, bit period ~1667ns. Bits encoded by high-pulse width (like WS2812).
+# Same timing schema; capture with DShot thresholds (high_split ~937, low_split ~730).
+contract: dshot600
+headroom_pct: 15            # ESCs are less forgiving than LEDs
+edges:
+  - {name: T0H, min: 562,  typ: 625,  max: 688}    # '0' bit high (~37.5% of period)
+  - {name: T1H, min: 1125, typ: 1250, max: 1375}   # '1' bit high (75% of period)
+  - {name: T0L, min: 938,  typ: 1042, max: 1146}   # '0' bit low  (period - T0H)
+  - {name: T1L, min: 292,  typ: 417,  max: 542}    # '1' bit low  (period - T1H)

hwcontract/examples/observations.example.json

@@ -0,0 +1,7 @@
+[
+  {"name": "T0H",   "value": 340,   "unit": "ns"},
+  {"name": "T0L",   "value": 810,   "unit": "ns"},
+  {"name": "T1H",   "value": 520,   "unit": "ns"},
+  {"name": "T1L",   "value": 470,   "unit": "ns"},
+  {"name": "RESET", "value": 62000, "unit": "ns"}
+]

hwcontract/examples/ws2812.contract.yaml

@@ -0,0 +1,11 @@
+# What "correct" looks like on the wire for a WS2812 / NeoPixel LED.
+# Bits are encoded by how long the data line stays HIGH. Times are nanoseconds.
+# assert.py measures the real pulses and compares them to these rows.
+contract: ws2812
+headroom_pct: 20            # inside [min,max] but within 20% of a rail => "marginal"
+edges:
+  - {name: T0H,   min: 200,   typ: 350,   max: 500}    # '0' bit, high time
+  - {name: T0L,   min: 650,   typ: 800,   max: 950}    # '0' bit, low time
+  - {name: T1H,   min: 550,   typ: 700,   max: 850}    # '1' bit, high time
+  - {name: T1L,   min: 450,   typ: 600,   max: 750}    # '1' bit, low time
+  - {name: RESET, min: 50000, typ: 50000, max: null}   # latch/show; WS2812B clones want >280000

hwcontract/judge.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""The judge: join a hardware contract against observations -> pass/marginal/fail.
+
+Pure logic, no hardware, no framework. Imported by server.py (MCP) and runnable
+standalone:  python judge.py ws2812.contract.yaml observations.json
+             python judge.py --demo
+"""
+import json
+import os
+import sys
+from functools import lru_cache
+
+import yaml
+
+try:                       # google-re2: linear-time, ReDoS-immune. `pip install google-re2`
+    import re2 as re       # used automatically when installed -> safe for UNTRUSTED contracts
+except ImportError:
+    import re              # stdlib fallback; ReDoS-bounded only by the input cap in run_serial
+
+
+@lru_cache(maxsize=64)
+def _load(path, _mtime):
+    return yaml.safe_load(open(path))
+
+
+def load_contract(path):
+    """Parse a contract YAML, cached until the file's mtime changes."""
+    return _load(path, os.path.getmtime(path))
+
+
+def judge(edge, obs, headroom_pct):
+    """(status, hint) for one edge given its observation (or None)."""
+    if obs is None:
+        return "MISSING", "no observation for this edge"
+
+    v, lo, hi, typ = obs["value"], edge["min"], edge["max"], edge["typ"]
+
+    if v < lo or (hi is not None and v > hi):
+        short = typ - v
+        return "FAIL", f"{abs(short)}ns {'short' if short > 0 else 'long'} (typ {typ})"
+
+    if hi is not None:                                  # flag rail-hugging (marginal)
+        threshold = headroom_pct / 100 * (hi - lo)
+        if min(v - lo, hi - v) < threshold:
+            near = "min" if v - lo < hi - v else "max"
+            return "marginal", f"only {min(v - lo, hi - v)}ns from {near}; nudge toward typ {typ}"
+
+    return "pass", ""
+
+
+def run(contract, observations):
+    """Return (results, ok). results = list of dicts; ok False if any FAIL/MISSING."""
+    by_name = {o["name"]: o for o in observations}
+    results, ok = [], True
+    for edge in contract["edges"]:
+        status, hint = judge(edge, by_name.get(edge["name"]), contract["headroom_pct"])
+        if status in ("FAIL", "MISSING"):
+            ok = False
+        obs = by_name.get(edge["name"])
+        results.append({"edge": edge["name"], "typ": edge["typ"],
+                        "actual": obs["value"] if obs else None,
+                        "status": status, "hint": hint})
+    return results, ok
+
+
+def run_serial(contract, log):
+    """Check a captured serial log against expect/forbid patterns. Same (results, ok) shape."""
+    # Bound the regex input (memory + ReDoS blast radius under stdlib re). With
+    # google-re2 installed, matching is linear-time and contracts can be untrusted.
+    log = log[:1_000_000]
+    results, ok = [], True
+
+    def search(pat):
+        try:
+            return re.search(pat, log), None
+        except Exception as e:                       # invalid regex in a contract -> report, don't crash
+            return None, f"{type(e).__name__}: {e}"
+
+    for pat in contract.get("expect", []):
+        hit, err = search(pat)
+        good = hit and not err
+        ok = ok and bool(good)
+        results.append({"edge": pat, "typ": "expect", "actual": "seen" if good else "absent",
+                        "status": "pass" if good else "FAIL",
+                        "hint": err or ("" if good else "expected pattern not in capture")})
+    for pat in contract.get("forbid", []):
+        hit, err = search(pat)
+        bad = bool(hit) or bool(err)                 # a broken forbid-rule fails closed
+        ok = ok and not bad
+        results.append({"edge": pat, "typ": "forbid",
+                        "actual": hit.group(0) if hit else "absent",
+                        "status": "FAIL" if bad else "pass",
+                        "hint": err or (f"forbidden match: {hit.group(0)}" if hit else "")})
+    return results, ok
+
+
+def render(results):
+    lines = [f"{'edge':<7} {'typ':>7} {'actual':>8}  {'status':<9} hint", "-" * 60]
+    for r in results:
+        lines.append(f"{r['edge']:<7} {r['typ']:>7} {str(r['actual'] if r['actual'] is not None else '-'):>8}"
+                     f"  {r['status']:<9} {r['hint']}")
+    return "\n".join(lines)
+
+
+def demo():
+    contract = {"headroom_pct": 20, "edges": [
+        {"name": "T0H", "typ": 350, "min": 200, "max": 500},
+        {"name": "T1H", "typ": 700, "min": 550, "max": 850},
+        {"name": "RESET", "typ": 50000, "min": 50000, "max": None},
+    ]}
+    obs = [{"name": "T0H", "value": 340},   # pass
+           {"name": "T1H", "value": 560}]   # marginal; RESET omitted -> MISSING
+    results, ok = run(contract, obs)
+    print(render(results))
+    st = {r["edge"]: r["status"] for r in results}
+    assert st["T0H"] == "pass"
+    assert st["T1H"] == "marginal"
+    assert st["RESET"] == "MISSING"
+    assert ok is False
+    print("\nself-check OK")
+
+
+if __name__ == "__main__":
+    if "--demo" in sys.argv:
+        demo()
+        sys.exit(0)
+    if len(sys.argv) != 3:
+        sys.exit(__doc__)
+    results, ok = run(load_contract(sys.argv[1]), json.load(open(sys.argv[2])))
+    print(render(results))
+    sys.exit(0 if ok else 1)

hwcontract/serial_adapter.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Serial-log adapter: get UART text for the serial-kind judge.
+
+Offline/replay:  python serial_adapter.py --file boot.log
+Live (needs pyserial): python serial_adapter.py --port /dev/ttyUSB0 --baud 115200 --seconds 3
+Self-check:      python serial_adapter.py --demo
+
+Owns no device config beyond baud - it just reads what the port (or serial-mcp,
+or a saved log) emits. The whole capture window IS the time bound: a pattern seen
+in an N-second capture was seen within N seconds.
+"""
+import sys
+import time
+
+
+def read_log(path):
+    return open(path, errors="replace").read()
+
+
+def capture(port, baud=115200, seconds=3.0):
+    import serial  # optional dep, only for live capture
+    ser = serial.Serial(port, baud, timeout=0.1)
+    end = time.monotonic() + seconds
+    buf = []
+    try:
+        while time.monotonic() < end:
+            buf.append(ser.read(4096).decode(errors="replace"))
+    finally:
+        ser.close()
+    return "".join(buf)
+
+
+def demo():
+    from hwcontract.judge import run_serial, render
+    contract = {"expect": ["IMU init OK", r"boot v\d+"],
+                "forbid": ["panic", "Guru Meditation", r"\bnan\b"]}
+    good = "boot v3\nsensor warmup...\nIMU init OK\nready\n"
+    results, ok = run_serial(contract, good)
+    print(render(results))
+    assert ok is True
+    _, bad_ok = run_serial(contract, "boot v3\nGuru Meditation Error\n")
+    assert bad_ok is False
+    print("\nself-check OK")
+
+
+if __name__ == "__main__":
+    import argparse
+    if "--demo" in sys.argv:
+        demo()
+        sys.exit(0)
+    p = argparse.ArgumentParser()
+    p.add_argument("--file")
+    p.add_argument("--port")
+    p.add_argument("--baud", type=int, default=115200)
+    p.add_argument("--seconds", type=float, default=3.0)
+    a = p.parse_args()
+    sys.stdout.write(read_log(a.file) if a.file else capture(a.port, a.baud, a.seconds))

hwcontract/server.py

@@ -0,0 +1,343 @@
+#!/usr/bin/env python3
+"""Zero-dependency MCP server exposing the hardware-contract judge.
+
+Speaks MCP over stdio (newline-delimited JSON-RPC 2.0) so any MCP client -
+Claude Code, Codex, opencode - can call it with no pip install:
+
+    { "mcpServers": { "hwcontract": {
+        "command": "python3", "args": ["/abs/path/server.py"] } } }
+
+Transport is stdlib only. All real work lives in judge.py / sigrok_adapter.py
+(pure, tested). Add a tool = append one entry to TOOLS.  Self-test: --selftest
+"""
+import json
+import os
+import re
+import sys
+
+from hwcontract.judge import load_contract, run, run_serial, render
+from hwcontract.sigrok_adapter import capture, observe
+from hwcontract import serial_adapter
+
+PROTOCOL_VERSION = "2024-11-05"
+SERVER_INFO = {"name": "hwcontract", "version": "0.1.0"}
+
+# DShot600 pulse-width thresholds for the shared timing adapter (ns).
+DSHOT600 = {"high_split": 937, "low_split": 730, "reset_ns": 1800}
+
+# ---- security boundary: this server is called by an LLM that can be prompt-
+# injected, so every argument is treated as hostile ------------------------------
+_HERE = os.path.dirname(os.path.abspath(__file__))
+EXAMPLES = os.path.join(_HERE, "examples")     # bundled example contracts, found regardless of cwd
+# Contracts/paths are confined here (default: the working dir where the agent runs,
+# i.e. the user's project). Override with HWCONTRACT_ROOT. Traversal outside -> rejected.
+ROOT = os.path.realpath(os.environ.get("HWCONTRACT_ROOT", os.getcwd()))
+MAX_SAMPLES, MAX_SECONDS, MAX_SR = 5_000_000, 60, 500_000_000
+_TOKEN = re.compile(r"^[A-Za-z0-9:_./=-]{1,64}$")   # driver/channel/port charset
+
+# Kill switch: set HWCONTRACT_SAFE=1, or drop a file named KILLSWITCH next to this
+# server, to make every hardware-touching tool refuse. Pure judge tools still work.
+_KILLSWITCH = os.path.join(_HERE, "KILLSWITCH")
+
+
+def _guard():
+    if os.environ.get("HWCONTRACT_SAFE") == "1" or os.path.exists(_KILLSWITCH):
+        raise RuntimeError("hardware disabled by kill switch (HWCONTRACT_SAFE / KILLSWITCH)")
+
+
+def _path(p):
+    """Confine a contract path to ROOT — block traversal / arbitrary file read."""
+    full = os.path.realpath(p if os.path.isabs(p) else os.path.join(ROOT, p))
+    if full != ROOT and not full.startswith(ROOT + os.sep):
+        raise ValueError(f"path escapes allowed root: {p}")
+    return full
+
+
+def _tok(name, v):
+    """Charset-validate a value handed to sigrok-cli / pyserial (arg-injection defense)."""
+    if not _TOKEN.match(str(v)):
+        raise ValueError(f"invalid {name}: {v!r}")
+    return str(v)
+
+
+def _int(v, hi, lo=1):
+    return max(lo, min(int(v), hi))
+
+
+# ---- tool implementations (thin wrappers over the pure core) ----------------
+
+def _summarize(results, ok):
+    return {"ok": ok, "results": results, "table": render(results)}
+
+
+def tool_judge_contract(contract_path, observations):
+    return _summarize(*run(load_contract(_path(contract_path)), observations))
+
+
+def tool_judge_serial(contract_path, log):
+    return _summarize(*run_serial(load_contract(_path(contract_path)), log))
+
+
+def _capture(driver, channel, samplerate, samples):
+    _guard()
+    sr = _int(samplerate, MAX_SR)
+    return observe(capture(_tok("driver", driver), _tok("channel", channel),
+                           sr, _int(samples, MAX_SAMPLES)), 1e9 / sr), sr
+
+
+def tool_capture_ws2812(driver="fx2lafw", channel="D0",
+                        samplerate=24_000_000, samples=200_000):
+    obs, _ = _capture(driver, channel, samplerate, samples)
+    return {"observations": obs}
+
+
+def tool_check_ws2812(contract_path, driver="fx2lafw", channel="D0",
+                      samplerate=24_000_000, samples=200_000):
+    obs, _ = _capture(driver, channel, samplerate, samples)
+    return _summarize(*run(load_contract(_path(contract_path)), obs))
+
+
+def tool_check_dshot(contract_path, driver="fx2lafw", channel="D0",
+                     samplerate=24_000_000, samples=200_000):
+    _guard()
+    sr = _int(samplerate, MAX_SR)
+    obs = observe(capture(_tok("driver", driver), _tok("channel", channel),
+                          sr, _int(samples, MAX_SAMPLES)), 1e9 / sr, **DSHOT600)
+    return _summarize(*run(load_contract(_path(contract_path)), obs))
+
+
+def tool_check_serial(contract_path, port, baud=115200, seconds=3.0):
+    _guard()
+    log = serial_adapter.capture(_tok("port", port), _int(baud, 4_000_000, 50),
+                                 min(float(seconds), MAX_SECONDS))
+    return _summarize(*run_serial(load_contract(_path(contract_path)), log))
+
+
+_NUM = {"type": "number"}
+_STR = {"type": "string"}
+_CAP = {"driver": _STR, "channel": _STR, "samplerate": _NUM, "samples": _NUM}
+
+TOOLS = {
+    "judge_contract": {
+        "fn": tool_judge_contract,
+        "description": "Judge observations against a contract -> pass/marginal/fail. "
+                       "No hardware; use for replay or when an adapter already captured.",
+        "schema": {"type": "object",
+                   "properties": {"contract_path": _STR,
+                                  "observations": {"type": "array", "items": {"type": "object"}}},
+                   "required": ["contract_path", "observations"]},
+    },
+    "capture_ws2812": {
+        "fn": tool_capture_ws2812,
+        "description": "Capture the WS2812 data line via sigrok and return measured "
+                       "pulse-width observations (T0H/T1H/...).",
+        "schema": {"type": "object", "properties": dict(_CAP)},
+    },
+    "check_ws2812": {
+        "fn": tool_check_ws2812,
+        "description": "Capture a live WS2812 signal AND judge it against a contract in "
+                       "one call. The one-shot an agent reaches for.",
+        "schema": {"type": "object",
+                   "properties": {"contract_path": _STR, **_CAP},
+                   "required": ["contract_path"]},
+    },
+    "check_dshot": {
+        "fn": tool_check_dshot,
+        "description": "Capture a live DShot600 ESC signal AND judge it against a contract "
+                       "in one call.",
+        "schema": {"type": "object",
+                   "properties": {"contract_path": _STR, **_CAP},
+                   "required": ["contract_path"]},
+    },
+    "judge_serial": {
+        "fn": tool_judge_serial,
+        "description": "Judge a captured serial log against expect/forbid patterns. "
+                       "No hardware; use for replay or logs another tool already captured.",
+        "schema": {"type": "object",
+                   "properties": {"contract_path": _STR, "log": _STR},
+                   "required": ["contract_path", "log"]},
+    },
+    "check_serial": {
+        "fn": tool_check_serial,
+        "description": "Read a serial port for N seconds AND judge its log against a "
+                       "contract's expect/forbid patterns.",
+        "schema": {"type": "object",
+                   "properties": {"contract_path": _STR, "port": _STR,
+                                  "baud": _NUM, "seconds": _NUM},
+                   "required": ["contract_path", "port"]},
+    },
+}
+
+
+# ---- MCP stdio transport (JSON-RPC 2.0, newline-delimited) -------------------
+
+def _handle(msg):
+    """Return a response dict, or None for notifications."""
+    method, mid = msg.get("method"), msg.get("id")
+
+    if method == "initialize":
+        return _ok(mid, {"protocolVersion": PROTOCOL_VERSION,
+                         "capabilities": {"tools": {}},
+                         "serverInfo": SERVER_INFO})
+    if method == "tools/list":
+        return _ok(mid, {"tools": [{"name": n, "description": t["description"],
+                                    "inputSchema": t["schema"]}
+                                   for n, t in TOOLS.items()]})
+    if method == "tools/call":
+        name = msg["params"]["name"]
+        args = msg["params"].get("arguments", {})
+        tool = TOOLS.get(name)
+        if tool is None:
+            return _text(mid, f"unknown tool: {name}", is_error=True)
+        try:
+            result = tool["fn"](**args)
+            return _text(mid, json.dumps(result, indent=2))
+        except Exception as e:                          # tool errors are results, not protocol errors
+            return _text(mid, f"{type(e).__name__}: {e}", is_error=True)
+    if mid is None:                                     # a notification (e.g. initialized)
+        return None
+    return {"jsonrpc": "2.0", "id": mid,
+            "error": {"code": -32601, "message": f"method not found: {method}"}}
+
+
+def _ok(mid, result):
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def _text(mid, text, is_error=False):
+    return _ok(mid, {"content": [{"type": "text", "text": text}], "isError": is_error})
+
+
+def serve(stdin, stdout):
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            _emit(stdout, {"jsonrpc": "2.0", "id": None,
+                           "error": {"code": -32700, "message": "parse error"}})
+            continue
+        resp = _handle(msg)
+        if resp is not None:
+            _emit(stdout, resp)
+
+
+def _emit(stdout, obj):
+    stdout.write(json.dumps(obj) + "\n")
+    stdout.flush()
+
+
+# ---- MCP HTTP transport (for remote-only clients, e.g. ChatGPT connectors) ----
+# Minimal Streamable-HTTP: one POST endpoint, JSON-RPC in -> JSON-RPC out. No SSE
+# (these tools are request/response, no server-initiated messages). Binds localhost;
+# set HWCONTRACT_TOKEN to require `Authorization: Bearer <token>` before exposing it.
+
+def serve_http(port, host="127.0.0.1"):
+    import hmac
+    from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+    token = os.environ.get("HWCONTRACT_TOKEN")
+    expected = f"Bearer {token}" if token else None
+    MAX_BODY = 8 * 1024 * 1024                       # cap request body to bound memory (DoS)
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_POST(self):
+            # constant-time auth check (no token-length/prefix timing oracle)
+            if expected and not hmac.compare_digest(self.headers.get("Authorization", ""), expected):
+                self.send_error(401, "unauthorized")
+                return
+            try:
+                length = int(self.headers.get("Content-Length", 0) or 0)
+            except ValueError:
+                length = -1
+            if length < 0 or length > MAX_BODY:
+                self.send_error(413, "payload too large")
+                return
+            try:
+                msg = json.loads(self.rfile.read(length) or b"{}")
+            except (ValueError, json.JSONDecodeError):
+                return self._send(200, {"jsonrpc": "2.0", "id": None,
+                                        "error": {"code": -32700, "message": "parse error"}})
+            resp = _handle(msg)
+            if resp is None:                            # notification -> 202, no body
+                self.send_response(202)
+                self.end_headers()
+            else:
+                self._send(200, resp)
+
+        def _send(self, code, obj):
+            data = json.dumps(obj).encode()
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+
+        def log_message(self, *a):
+            pass
+
+    srv = ThreadingHTTPServer((host, port), Handler)
+    print(f"hwcontract MCP on http://{host}:{port}  (auth: {'on' if token else 'OFF'})", file=sys.stderr)
+    srv.serve_forever()
+
+
+def selftest():
+    """Drive initialize/tools/list/tools/call in-process, no hardware, no cwd dependency."""
+    global ROOT
+    import io
+    from hwcontract.sigrok_adapter import synth, observe as _obs
+    ROOT = os.path.realpath(EXAMPLES)           # confine to the bundled examples, wherever installed
+    dt = 1e9 / 24_000_000
+    obs = _obs(synth(dt), dt)
+
+    dshot_obs = [{"name": "T0H", "value": 625}, {"name": "T1H", "value": 1250},
+                 {"name": "T0L", "value": 1042}, {"name": "T1L", "value": 417}]
+    good_log = "boot v3\nsensor warmup\nIMU init OK\nready\n"
+
+    def call(i, name, **args):
+        return {"jsonrpc": "2.0", "id": i, "method": "tools/call",
+                "params": {"name": name, "arguments": args}}
+
+    def ex(name):
+        return os.path.join(EXAMPLES, name)     # absolute path into the bundled examples
+
+    msgs = [
+        {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}},
+        {"jsonrpc": "2.0", "method": "notifications/initialized"},   # no id -> no response
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}},
+        call(3, "judge_contract", contract_path=ex("ws2812.contract.yaml"), observations=obs),
+        call(4, "judge_contract", contract_path=ex("dshot.contract.yaml"), observations=dshot_obs),
+        call(5, "judge_serial", contract_path=ex("boot.contract.yaml"), log=good_log),
+        call(6, "capture_ws2812"),                  # hardware -> should error cleanly (no sigrok here)
+    ]
+    out = io.StringIO()
+    serve(io.StringIO("\n".join(json.dumps(m) for m in msgs)), out)
+    r = {m["id"]: m for m in (json.loads(l) for l in out.getvalue().splitlines())}
+
+    assert len(r) == 6                              # the notification produced no response
+    assert r[1]["result"]["protocolVersion"] == PROTOCOL_VERSION
+    assert {t["name"] for t in r[2]["result"]["tools"]} == set(TOOLS)
+    assert json.loads(r[3]["result"]["content"][0]["text"])["ok"] is True    # WS2812 in-spec
+    assert json.loads(r[4]["result"]["content"][0]["text"])["ok"] is True    # DShot  in-spec
+    assert json.loads(r[5]["result"]["content"][0]["text"])["ok"] is True    # boot log clean
+    assert r[6]["result"]["isError"] is True        # hardware tool fails gracefully, no crash
+    print(render(json.loads(r[5]["result"]["content"][0]["text"])["results"]))
+    print("\nself-check OK")
+
+
+def main(argv=None):
+    argv = sys.argv if argv is None else argv
+    if "--selftest" in argv:
+        selftest()
+    elif "--http" in argv:
+        serve_http(int(argv[argv.index("--http") + 1]))
+    else:
+        try:
+            serve(sys.stdin, sys.stdout)                 # default: stdio
+        except (KeyboardInterrupt, BrokenPipeError):
+            pass
+
+
+if __name__ == "__main__":
+    main()

hwcontract/sigrok_adapter.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Turn a logic-analyzer capture of a WS2812 data line into observations JSON.
+
+    # live capture (needs sigrok-cli + a $10 fx2lafw analyzer on D0):
+    python sigrok_adapter.py --driver fx2lafw --channel D0 --samplerate 24000000 \
+        --samples 200000 > observations.json
+    python assert.py ws2812.contract.yaml observations.json
+
+    # offline: feed a CSV of one 0/1 sample per line (for testing / replay):
+    python sigrok_adapter.py --csv capture.csv --samplerate 24000000 > observations.json
+    python sigrok_adapter.py --demo        # self-check, no hardware
+
+We measure every HIGH/LOW pulse width, split highs and lows into two clusters by
+a threshold (short=0-bit, long=1-bit), and report the median of each -> robust to
+jitter. The thresholds are the calibration knobs: real strips and clone chips vary.
+"""
+import json
+import subprocess
+import sys
+from statistics import median
+
+# calibration knobs (ns). WS2812: 0-bit high ~350, 1-bit high ~700; lows ~800/600.
+HIGH_SPLIT = 525     # high pulse >  this => T1H, else T0H
+LOW_SPLIT = 700      # low  pulse <  this => T1L, else T0L
+RESET_NS = 5000      # low pulse > this => the latch/RESET gap, not a bit
+
+
+def runs(samples, dt_ns):
+    """(level, width_ns) for every run, boundary runs included."""
+    out, prev, n = [], samples[0], 0
+    for s in samples:
+        if s == prev:
+            n += 1
+        else:
+            out.append((prev, n * dt_ns))
+            prev, n = s, 1
+    out.append((prev, n * dt_ns))
+    return out
+
+
+def observe(samples, dt_ns, high_split=HIGH_SPLIT, low_split=LOW_SPLIT, reset_ns=RESET_NS):
+    """Bucket pulse widths into bit encodings. Thresholds are the calibration knobs;
+    defaults are WS2812. Pass DShot's splits to reuse this for DShot."""
+    all_runs = runs(samples, dt_ns)
+    interior = all_runs[1:-1]                        # drop capture-boundary partials for bit widths
+    highs = [w for lvl, w in interior if lvl == 1]
+    lows = [w for lvl, w in interior if lvl == 0 and w <= reset_ns]
+    buckets = {
+        "T0H": [w for w in highs if w <= high_split],
+        "T1H": [w for w in highs if w > high_split],
+        "T1L": [w for w in lows if w < low_split],
+        "T0L": [w for w in lows if w >= low_split],
+        # RESET scanned across ALL runs so a latch gap at the capture edge isn't lost
+        "RESET": [w for lvl, w in all_runs if lvl == 0 and w > reset_ns],
+    }
+    return [{"name": k, "value": round(median(v)), "unit": "ns"}
+            for k, v in buckets.items() if v]
+
+
+def read_csv(path):
+    return [int(t) for line in open(path)
+            for t in [line.strip()] if t in ("0", "1")]
+
+
+def capture(driver, channel, samplerate, samples, timeout=30):
+    cmd = ["sigrok-cli", "--driver", driver, "--channels", channel,
+           "--config", f"samplerate={samplerate}",
+           "--samples", str(samples), "-O", "csv"]
+    out = subprocess.run(cmd, capture_output=True, text=True,
+                         check=True, timeout=timeout).stdout   # don't hang on a stuck analyzer
+    return [int(t) for line in out.splitlines()
+            for t in [line.strip()] if t in ("0", "1")]
+
+
+def synth(dt_ns):
+    """Fake a clean-ish stream: a few 0 and 1 bits, then a reset gap."""
+    def pulse(width, level):
+        return [level] * max(1, round(width / dt_ns))
+    s = [0] * 3
+    for _ in range(4):
+        s += pulse(350, 1) + pulse(800, 0)   # '0' bits
+        s += pulse(700, 1) + pulse(600, 0)   # '1' bits
+    return s + pulse(60000, 0)                 # RESET as the LAST run — must still be caught
+
+
+def demo():
+    dt = 1e9 / 24_000_000
+    obs = {o["name"]: o["value"] for o in observe(synth(dt), dt)}
+    print(json.dumps(obs, indent=2))
+    assert abs(obs["T0H"] - 350) < dt * 2      # recovered within one sample
+    assert abs(obs["T1H"] - 700) < dt * 2
+    assert obs["RESET"] > 50000
+    print("\nself-check OK")
+
+
+if __name__ == "__main__":
+    import argparse
+    p = argparse.ArgumentParser()
+    p.add_argument("--csv")
+    p.add_argument("--driver", default="fx2lafw")
+    p.add_argument("--channel", default="D0")
+    p.add_argument("--samplerate", type=int, default=24_000_000)
+    p.add_argument("--samples", type=int, default=200_000)
+    p.add_argument("--demo", action="store_true")
+    a = p.parse_args()
+
+    if a.demo:
+        demo()
+        sys.exit(0)
+    samples = read_csv(a.csv) if a.csv else capture(a.driver, a.channel, a.samplerate, a.samples)
+    json.dump(observe(samples, 1e9 / a.samplerate), sys.stdout, indent=2)
+    print()

hwcontract-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: hwcontract
+Version: 0.1.0
+Summary: MCP server that judges hardware timing/serial behavior against a contract (pass/marginal/fail)
+Author: hwcontract authors
+License: MIT
+Keywords: mcp,hardware,firmware,embedded,logic-analyzer,ws2812,dshot,sigrok
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: untrusted
+Requires-Dist: google-re2>=1.1; extra == "untrusted"
+Provides-Extra: all
+Requires-Dist: pyserial>=3.5; extra == "all"
+Requires-Dist: google-re2>=1.1; extra == "all"
+Dynamic: license-file
+
+# hwcontract
+
+A zero-dependency **MCP server that judges hardware against a contract**. Coding
+agents (Claude Code, Codex, opencode) write firmware that's correct on paper but
+wrong on the wire — a WS2812 pulse 180ns short, an ESC bit out of spec, a boot log
+that silently panics. This closes the loop: it captures what the hardware *actually*
+did and returns **pass / marginal / fail** the agent can iterate on.
+
+`marginal` is the valuable verdict — in-spec but low-headroom, the bug that works on
+your bench and fails on a cold board in the field.
+
+## How it fits together
+
+```
+  observers (capture)                judge (this repo)
+  ─────────────────────              ─────────────────
+  logic analyzer  ─ pulse widths ─┐
+  serial port     ─ log text ─────┼─►  contract × observation  ─►  pass/marginal/fail
+                                  ┘         (judge.py)
+```
+
+- **`judge.py`** — the pure judge (timing + serial). No hardware, no framework, cached.
+- **`sigrok_adapter.py`** — logic-analyzer capture → pulse-width observations (WS2812/DShot).
+- **`serial_adapter.py`** — serial log capture (or replay a saved log).
+- **`server.py`** — the MCP server (stdio JSON-RPC, stdlib only).
+- **`*.contract.yaml`** — what "correct" looks like. Human-editable. Also serve as regression tests.
+
+## Install
+
+```bash
+pip install hwcontract              # judge + logic-analyzer adapter
+pip install "hwcontract[serial]"    # + live serial capture (pyserial)
+pip install "hwcontract[untrusted]" # + google-re2 (ReDoS-immune, for untrusted contracts)
+pip install "hwcontract[all]"       # everything
+```
+
+Also needs `sigrok-cli` on PATH for live logic-analyzer capture (`check_ws2812` /
+`check_dshot`). Judge-only tools (`judge_contract`, `judge_serial`) need nothing extra.
+
+## Wire it into an agent
+
+One stanza per client (not auto-discovered — add it once). After `pip install`, the
+`hwcontract` command is on your PATH.
+
+**Claude Code**
+```bash
+claude mcp add hwcontract -- hwcontract
+```
+
+**Codex CLI** — `~/.codex/config.toml`
+```toml
+[mcp_servers.hwcontract]
+command = "hwcontract"
+```
+
+**opencode / Cursor / Gemini / any stdio MCP client**
+```json
+{ "mcpServers": { "hwcontract": { "command": "hwcontract" } } }
+```
+
+> Transport is **stdio** by default (local, no auth surface). For remote-only clients
+> (e.g. ChatGPT connectors), run `hwcontract --http 8791` and expose it via a tunnel
+> with `HWCONTRACT_TOKEN` set for bearer auth.
+
+### If the client can't find `hwcontract` (PATH issues)
+
+GUI apps and some agents don't inherit your shell `PATH`, so a bare `hwcontract`
+can fail with "command not found". Two robust fixes:
+
+- Use the **absolute path**: `which hwcontract` → put that full path in `command`.
+- Or invoke via Python (no PATH lookup for the script): `command: "python3"`,
+  `args: ["-m", "hwcontract.server"]` — works from any directory once installed.
+
+**Contract paths:** pass an **absolute** `contract_path`, or set `HWCONTRACT_ROOT`
+to your contracts folder — relative paths resolve against it (default: the process's
+working directory, which the client controls and may not be your project). Paths
+outside the root are rejected. Bundled examples install with the package under
+`hwcontract/examples/`.
+
+## Tools
+
+| Tool | Hardware? | What it does |
+|------|-----------|--------------|
+| `judge_contract` | no | Judge given observations against a timing contract. Replay / testing. |
+| `judge_serial` | no | Judge a given log string against a serial contract's expect/forbid. |
+| `check_ws2812` | yes | Capture a live WS2812 line **and** judge it, one call. |
+| `check_dshot` | yes | Same, for a DShot600 ESC signal. |
+| `capture_ws2812` | yes | Just capture → observations (no judging). |
+| `check_serial` | yes | Read a serial port for N seconds and judge the log. |
+
+## Contracts
+
+Timing (`ws2812.contract.yaml`, `dshot.contract.yaml`) — pulse widths in ns:
+```yaml
+contract: ws2812
+headroom_pct: 20         # in-spec but within 20% of a rail => "marginal"
+edges:
+  - {name: T0H, min: 200, typ: 350, max: 500}   # '0' bit high time
+```
+Serial (`boot.contract.yaml`) — Python regex:
+```yaml
+contract: boot
+kind: serial
+expect: ["IMU init OK", "boot v\\d+"]
+forbid: ["panic", "Guru Meditation", "\\bnan\\b"]
+```
+Add a protocol = drop a new YAML. No code change for another timing signal.
+
+## Kill switch
+
+Instantly disable every hardware-touching tool (captures) while leaving the pure
+judge tools working:
+
+```bash
+export HWCONTRACT_SAFE=1          # env, or:
+touch /home/tsd/projects/hardware/KILLSWITCH   # file next to server.py
+```
+
+## Security
+
+Every tool argument is treated as hostile (the caller is an LLM that can be prompt-
+injected): contract paths are confined to the server dir (override `HWCONTRACT_ROOT`),
+`driver`/`channel`/`port` are charset-validated, `samples`/`seconds`/`samplerate` are
+clamped, `sigrok-cli` runs with a timeout, YAML is `safe_load`. Do not expose this
+server over the network without adding authentication.
+
+## Self-tests (no hardware, run from anywhere)
+
+```bash
+hwcontract --selftest                       # full MCP round-trip
+python3 -m hwcontract.judge --demo
+python3 -m hwcontract.sigrok_adapter --demo
+python3 -m hwcontract.serial_adapter --demo
+```

hwcontract-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+hwcontract/__init__.py,sha256=7s_VUBC3ap6dwVvkqv5e7tYgLPb4sN9WoT7Z9fmAQwc,98
+hwcontract/judge.py,sha256=zg5b63Gq2mvcyq2SdVN3jMNYeXqjy0T6AgYBIZHCeXo,5056
+hwcontract/serial_adapter.py,sha256=W__HrRQ6feSYrr26I811FYziJUid0fRPAsa7uMeWiqc,1873
+hwcontract/server.py,sha256=0HAPkMG6BlA9aBcDv6B6v1vi3JaSHckCGwjqIeczUCw,14360
+hwcontract/sigrok_adapter.py,sha256=nsAZ6ovZa5BiSdP_iQqrdIV2Ftxa6teeO6g5gLLbhhQ,4536
+hwcontract/examples/boot.contract.yaml,sha256=AW6KHsr2Y9r2InNP-DT-gGKFPvMb2hb3fMWfMKoOSTQ,419
+hwcontract/examples/dshot.contract.yaml,sha256=YZ5GzcExLRsafmrbzJ0HkdQTF4nY2xmx822qI95TWtc,673
+hwcontract/examples/observations.example.json,sha256=iOV_jVPjPKc9-0ecrR4wyq9kxqdI8xGVSsNJIbvIJT0,258
+hwcontract/examples/ws2812.contract.yaml,sha256=ZmYmFsfOSeVRhCjrza5uHmzV9X0xk8BR23qkCpHCKIk,728
+hwcontract-0.1.0.dist-info/licenses/LICENSE,sha256=lvEupdlIxwFN4KAW9iriK4bsao_d5Mnb6c6rhA7_LKI,1075
+hwcontract-0.1.0.dist-info/METADATA,sha256=nedmEL8Ji-G4TPUFRPgy3v56jsmOksN2DY9w1JTKnnA,6228
+hwcontract-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+hwcontract-0.1.0.dist-info/entry_points.txt,sha256=_C0_cLvVB5pMN_VaBPJZljx2kC3IfMLX8OYUF4rE8E0,54
+hwcontract-0.1.0.dist-info/top_level.txt,sha256=9tKjSf8K6UtjB2pdlfvVx4VIJX56HwHp2OomjdiZSIc,11
+hwcontract-0.1.0.dist-info/RECORD,,

hwcontract-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hwcontract-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hwcontract = hwcontract.server:main

hwcontract-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hwcontract authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hwcontract-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hwcontract