verify-outcomes 0.4.1__py3-none-any.whl

verify/__init__.py

@@ -0,0 +1,5 @@
+"""Verify: never trust an agent's own "done". Read the system of record back."""
+from .core import Blocked, Ledger, check, evaluate, verify
+
+__all__ = ["Blocked", "Ledger", "check", "evaluate", "verify"]
+__version__ = "0.4.1"

verify/__main__.py

@@ -0,0 +1,3 @@
+import sys
+from .cli import main
+sys.exit(main())

verify/cli.py

@@ -0,0 +1,135 @@
+"""usage:
+  verify check <contract.json> <claim.json> [--ledger verify.db]   exit 0 only on pass
+  verify check-batch <contract.json> <claims.jsonl> [--ledger verify.db]   one line per claim; exit 0 only if all pass
+  verify push <ledger.db> --to <url>      upload to the hosted ledger (key: env VERIFY_HOSTED_KEY)
+  verify validate <contract.json>...
+  verify ledger <db>
+  verify ledger export <db> [out.jsonl]     hash-chained JSONL + chain head
+  verify ledger verify <export.jsonl>      check an export offline
+  verify init {stripe,zendesk,hubspot,intercom,shopify} [dir]
+  verify --version
+  verify demo {local,stripe,zendesk}
+  verify selfcheck
+"""
+import json, os, sys
+from . import contract, hubspot, intercom, local, shopify, stripe, zendesk
+from . import __version__
+from .core import BadClaim, Ledger, verify, verify_export
+
+
+def reader_for(c):
+    """Pick the read-only adapter from the contract's target_system. Credentials only from env."""
+    t = c["target_system"]
+    if t == "stripe":
+        key = stripe.test_key("STRIPE_VERIFY_KEY")
+        if not key: sys.exit("Set STRIPE_VERIFY_KEY (restricted rk_test_ key, Charges+Refunds Read).")
+        return stripe.make_reader(stripe.stripe_http, key)
+    if t == "zendesk":
+        sub, tok = os.environ.get("ZENDESK_SUBDOMAIN"), os.environ.get("ZENDESK_VERIFY_TOKEN")
+        if not (sub and tok): sys.exit("Set ZENDESK_SUBDOMAIN and ZENDESK_VERIFY_TOKEN (OAuth, scope read).")
+        return zendesk.make_reader(zendesk.zd_http(sub, f"Bearer {tok}"))
+    if t == "hubspot":
+        tok = os.environ.get("HUBSPOT_VERIFY_TOKEN")
+        if not tok: sys.exit("Set HUBSPOT_VERIFY_TOKEN (private app, crm.objects.deals.read only).")
+        return hubspot.make_reader(hubspot.hs_http(tok))
+    if t == "intercom":
+        tok = os.environ.get("INTERCOM_VERIFY_TOKEN")
+        if not tok: sys.exit("Set INTERCOM_VERIFY_TOKEN (Intercom app access token, Read conversations permission only).")
+        return intercom.make_reader(intercom.ic_http(tok))
+    if t == "shopify":
+        shop, tok = os.environ.get("SHOPIFY_SHOP"), os.environ.get("SHOPIFY_VERIFY_TOKEN")
+        if not (shop and tok): sys.exit("Set SHOPIFY_SHOP (subdomain of .myshopify.com) and SHOPIFY_VERIFY_TOKEN (custom app Admin API token, read_orders scope only).")
+        return shopify.make_reader(shopify.sh_http(shop, tok))
+    sys.exit(f"no adapter for target_system {t!r} (have: stripe, zendesk, hubspot, intercom, shopify)")
+
+
+def check(contract_path, claim_path, ledger_path="verify.db"):
+    c = contract.load(contract_path)
+    with open(claim_path) as f: claim = json.load(f)
+    try: run_id, v, level, reasons = verify(Ledger(ledger_path), None, claim, c, reader_for(c), actor=claim.get("actor", "unknown"))
+    except BadClaim as e: print(f"error: {e}", file=sys.stderr); return 2
+    print(json.dumps({"run_id": run_id, "verdict": v, "level": level, "reasons": reasons, "ledger": ledger_path}, indent=1))
+    return 0 if v == "pass" else 1
+
+
+def check_batch(contract_path, claims_path, ledger_path="verify.db", reader=None):
+    c = contract.load(contract_path)
+    led, reader = Ledger(ledger_path), reader or reader_for(c)
+    counts = {}
+    with open(claims_path) as f:
+        for n, line in enumerate(f, 1):
+            if not line.strip(): continue
+            claim = json.loads(line)
+            try: run_id, v, level, reasons = verify(led, None, claim, c, reader, actor=claim.get("actor", "unknown"))
+            except BadClaim as e: run_id, v, level, reasons = None, "bad_claim", "-", [str(e)]
+            counts[v] = counts.get(v, 0) + 1
+            print(json.dumps({"line": n, "run_id": run_id, "verdict": v, "level": level, "reasons": reasons}))
+    total = sum(counts.values())
+    print(f"# {counts.get('pass', 0)}/{total} pass  " + "  ".join(f"{k}={v}" for k, v in sorted(counts.items())), file=sys.stderr)
+    return 0 if total and counts.get("pass", 0) == total else 1
+
+
+CLAIMS = {"stripe": {"actor": "support-agent", "charge_id": "ch_...", "refund_id": "re_...", "amount": 5000},
+          "zendesk": {"actor": "support-agent", "ticket": 123},
+          "hubspot": {"actor": "revops-agent", "deal": "123", "amount": 4200.0, "company": "456"},
+          "intercom": {"actor": "support-agent", "conversation": "123"},
+          "shopify": {"actor": "support-agent", "order": "123", "refund_id": "456", "amount": 50.0}}
+
+
+def init(system, d="."):
+    mod = {"stripe": stripe, "zendesk": zendesk, "hubspot": hubspot, "intercom": intercom, "shopify": shopify}[system]
+    os.makedirs(os.path.join(d, "contracts"), exist_ok=True)
+    paths = [os.path.join(d, "contracts", mod.CONTRACT["id"] + ".json"), os.path.join(d, f"claim.{system}.json")]
+    for p, body in zip(paths, (mod.CONTRACT, CLAIMS[system])):
+        if os.path.exists(p): print(f"exists, kept: {p}"); continue
+        with open(p, "w") as f: json.dump(body, f, indent=2); f.write("\n")
+        print(f"wrote {p}")
+    print(f"next: edit {paths[1]}, then  verify check {paths[0]} {paths[1]}")
+    return 0
+
+
+def main(argv=None):
+    a = sys.argv[1:] if argv is None else argv
+    if a[:1] in (["--version"], ["-V"]): print(f"verify {__version__}"); return 0
+    if a[:1] == ["init"] and len(a) in (2, 3) and a[1] in CLAIMS: return init(*a[1:])
+    if a[:2] == ["ledger", "export"] and len(a) in (3, 4):
+        out = open(a[3], "w") if len(a) == 4 else sys.stdout
+        head = Ledger(a[2]).export(out)
+        if out is not sys.stdout: out.close(); print(f"chain head {head}")
+        return 0
+    if a[:2] == ["ledger", "verify"] and len(a) == 3:
+        with open(a[2]) as f: ok, n, head = verify_export(f)
+        print(f"{n} events, chain {'intact' if ok else 'BROKEN'}" + (f", head {head}" if ok else ""))
+        return 0 if ok else 1
+    if a[:1] == ["check"] and len(a) in (3, 5) and (len(a) == 3 or a[3] == "--ledger"):
+        return check(a[1], a[2], *a[4:5])
+    if a[:1] == ["check-batch"] and len(a) in (3, 5) and (len(a) == 3 or a[3] == "--ledger"):
+        return check_batch(a[1], a[2], *a[4:5])
+    if a[:1] == ["push"] and len(a) == 4 and a[2] == "--to":
+        from .push import push
+        key = os.environ.get("VERIFY_HOSTED_KEY")
+        if not key: print("error: set VERIFY_HOSTED_KEY", file=sys.stderr); return 2
+        r = push(a[1], a[3], key); print(f"pushed {r['pushed']} events, head {r['head']}"); return 0
+    if a[:1] == ["validate"] and len(a) > 1:
+        bad = 0
+        for p in a[1:]:
+            errs = contract.validate(json.load(open(p)))
+            print(f"{p}: " + ("ok" if not errs else "INVALID\n  " + "\n  ".join(errs)))
+            bad += bool(errs)
+        return 1 if bad else 0
+    if a[:1] == ["ledger"] and len(a) == 2:
+        led = Ledger(a[1])
+        for row in led.db.execute("SELECT run_id, verdict, level_reached, independence, reasons_json FROM verdict"):
+            print(*row, sep="  ")
+        ok = led.verify_chain()
+        print("hash chain intact:", ok)
+        return 0 if ok else 1
+    if a[:2] == ["demo", "local"]: local.demo(); return 0
+    if a[:2] == ["demo", "stripe"]: stripe.main(); return 0
+    if a[:2] == ["demo", "zendesk"]: zendesk.main(); return 0
+    if a[:1] == ["selfcheck"]: local.check(); stripe.check(); zendesk.check(); hubspot.check(); intercom.check(); shopify.check(); return 0
+    print(__doc__); return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

verify/contract.py

@@ -0,0 +1,33 @@
+"""Load and validate outcome contracts (JSON). Rules from the outcome contract schema v0.1."""
+import json
+from .core import OPS
+
+REQUIRED = ("id", "version", "owner", "target_system", "subject_ref", "postconditions",
+            "required_level", "settle_window_s", "max_attempts", "scope")
+LEVELS = ("L1", "L2", "L3", "L4")
+
+
+def validate(c):
+    """Return a list of problems; empty means valid. Rejected at registration, never at runtime."""
+    errs = [f"missing field: {f}" for f in REQUIRED if f not in c]
+    if errs: return errs
+    if not c["postconditions"]: errs.append("postconditions must not be empty")
+    if c["required_level"] not in LEVELS: errs.append(f"required_level must be one of {LEVELS}")
+    if not isinstance(c["max_attempts"], int) or c["max_attempts"] < 1: errs.append("max_attempts must be an int >= 1")
+    if not isinstance(c["settle_window_s"], (int, float)) or c["settle_window_s"] < 0: errs.append("settle_window_s must be >= 0")
+    scope = set(c["scope"])
+    for group in ("preconditions", "postconditions", "forbidden"):
+        for i, chk in enumerate(c.get(group, [])):
+            where = f"{group}[{i}]"
+            if chk.get("op") not in OPS: errs.append(f"{where}: unknown op {chk.get('op')!r}")
+            if chk.get("path") not in scope: errs.append(f"{where}: path {chk.get('path')!r} not in scope")
+    sp = c.get("subject_present")
+    if sp and sp not in scope: errs.append(f"subject_present {sp!r} not in scope")
+    return errs
+
+
+def load(path):
+    with open(path) as f: c = json.load(f)
+    errs = validate(c)
+    if errs: raise ValueError(f"{path}: invalid contract:\n  " + "\n  ".join(errs))
+    return c

verify/core.py

@@ -0,0 +1,152 @@
+"""Verify core: contracts -> independent readback -> 5 verdicts -> hash-chained ledger."""
+import sqlite3, json, hashlib, time, uuid
+from datetime import datetime, timezone
+
+def now(): return datetime.now(timezone.utc).isoformat()
+
+class Blocked(Exception):
+    """Readback impossible (auth, outage, rate limit). retry_after: seconds the system asked us to wait."""
+    def __init__(self, msg, retry_after=None):
+        super().__init__(msg); self.retry_after = retry_after
+
+# ---------------- evaluation ----------------
+OPS = {"eq": lambda a, b: a == b, "ne": lambda a, b: a != b, "gt": lambda a, b: a is not None and a > b,
+       "lt": lambda a, b: a is not None and a < b, "exists": lambda a, b: a is not None}
+
+def resolve(v, claim):
+    if isinstance(v, str) and v.startswith("{") and v.endswith("}"): return claim[v[1:-1]]
+    return v
+
+def evaluate(contract, fields, claim):
+    """Returns (verdict, level, reasons). Unknown fails closed."""
+    def run(checks): return [(c, fields.get(c["path"]), OPS[c["op"]](fields.get(c["path"]), resolve(c["value"], claim)))
+                             for c in checks]
+    pre = run(contract["preconditions"])
+    if not all(ok for *_, ok in pre):
+        return "inapplicable", "L0", [f"precondition {c['path']}={got!r}" for c, got, ok in pre if not ok]
+    if fields.get(contract.get("subject_present", "refund.amount")) in (None, False):   # subject record absent
+        return "not_observed", "L1", [f"{contract['subject_ref'].format(**claim)} not found in system of record"]
+    bad = [f"forbidden {c['path']}={got!r}" for c, got, hit in run(contract["forbidden"]) if hit]
+    bad += [f"{c['path']} = {got!r}, expected {c['op']} {resolve(c['value'], claim)!r}"
+            for c, got, ok in run(contract["postconditions"]) if not ok]
+    return ("fail", "L2", bad) if bad else ("pass", contract["required_level"], [])
+
+# ---------------- ledger (doc 03) ----------------
+LEDGER_SQL = """
+CREATE TABLE IF NOT EXISTS contract(id TEXT, version TEXT, body_json TEXT NOT NULL, body_hash TEXT NOT NULL,
+  registered_at TEXT NOT NULL, owner TEXT NOT NULL, PRIMARY KEY(id, version));
+CREATE TABLE IF NOT EXISTS run(run_id TEXT PRIMARY KEY, contract_id TEXT NOT NULL, contract_version TEXT NOT NULL,
+  subject_ref TEXT NOT NULL, actor TEXT NOT NULL, started_at TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS event(seq INTEGER PRIMARY KEY AUTOINCREMENT, run_id TEXT NOT NULL, type TEXT NOT NULL,
+  at TEXT NOT NULL, clock_source TEXT NOT NULL, payload_json TEXT NOT NULL, evidence_hash TEXT, prev_hash TEXT, hash TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS verdict(run_id TEXT PRIMARY KEY, verdict TEXT NOT NULL
+  CHECK (verdict IN ('pass','fail','inapplicable','not_observed','blocked')),
+  level_reached TEXT NOT NULL, independence TEXT NOT NULL, reasons_json TEXT NOT NULL, final_event_seq INTEGER NOT NULL);
+"""
+
+class Ledger:
+    def __init__(self, path):
+        self.db = sqlite3.connect(path)
+        self.db.execute("PRAGMA journal_mode=WAL"); self.db.execute("PRAGMA synchronous=FULL")
+        self.db.executescript(LEDGER_SQL)
+
+    def event(self, run_id, type_, payload, evidence=None):
+        prev = (self.db.execute("SELECT hash FROM event ORDER BY seq DESC LIMIT 1").fetchone() or [""])[0]
+        row = dict(run_id=run_id, type=type_, at=now(), clock_source="system", payload_json=json.dumps(payload, sort_keys=True),
+                   evidence_hash=hashlib.sha256(evidence.encode()).hexdigest() if evidence else None)
+        h = hashlib.sha256((prev + json.dumps(row, sort_keys=True)).encode()).hexdigest()
+        cur = self.db.execute("INSERT INTO event(run_id,type,at,clock_source,payload_json,evidence_hash,prev_hash,hash) VALUES (?,?,?,?,?,?,?,?)",
+                              (*row.values(), prev, h))
+        self.db.commit(); return cur.lastrowid
+
+    EVENT_KEYS = ["run_id", "type", "at", "clock_source", "payload_json", "evidence_hash"]
+
+    def export(self, out):
+        """Write every event as JSONL, then a final line with the chain head. Returns the head hash."""
+        head = ""
+        for seq, *row, p, h in self.db.execute("SELECT seq,run_id,type,at,clock_source,payload_json,evidence_hash,prev_hash,hash FROM event ORDER BY seq"):
+            out.write(json.dumps(dict(seq=seq, **dict(zip(self.EVENT_KEYS, row)), prev_hash=p, hash=h), sort_keys=True) + "\n")
+            head = h
+        out.write(json.dumps({"chain_head": head}) + "\n")
+        return head
+
+    def verify_chain(self):
+        prev = ""
+        for *row, p, h in self.db.execute("SELECT run_id,type,at,clock_source,payload_json,evidence_hash,prev_hash,hash FROM event ORDER BY seq"):
+            keys = ["run_id", "type", "at", "clock_source", "payload_json", "evidence_hash"]
+            if p != prev or h != hashlib.sha256((prev + json.dumps(dict(zip(keys, row)), sort_keys=True)).encode()).hexdigest():
+                return False
+            prev = h
+        return True
+
+def verify_export(lines):
+    """Check an exported JSONL ledger offline. Returns (ok, events, head)."""
+    prev, n, head = "", 0, None
+    for line in lines:
+        e = json.loads(line)
+        if "chain_head" in e: head = e["chain_head"]; break
+        row = {k: e[k] for k in Ledger.EVENT_KEYS}
+        if e["prev_hash"] != prev or e["hash"] != hashlib.sha256((prev + json.dumps(row, sort_keys=True)).encode()).hexdigest():
+            return False, n, None
+        prev, n = e["hash"], n + 1
+    return head == prev, n, head
+
+# ---------------- Verify ----------------
+def claim_fields(contract):
+    """Claim keys the contract needs: {placeholders} in subject_ref and in check values."""
+    import string
+    need = {f for _, f, _, _ in string.Formatter().parse(contract["subject_ref"]) if f}
+    for g in ("preconditions", "postconditions", "forbidden"):
+        for c in contract.get(g, []):
+            v = c.get("value")
+            if isinstance(v, str) and v.startswith("{") and v.endswith("}"): need.add(v[1:-1])
+    return need
+
+
+class BadClaim(ValueError): pass
+
+
+def verify(ledger, sor_path, claim, contract, reader, actor="support-agent", independence="full"):
+    missing = sorted(claim_fields(contract) - set(claim))
+    if missing: raise BadClaim(f"claim is missing {', '.join(missing)} (needed by contract {contract['id']})")   # before any ledger write
+    body = json.dumps(contract, sort_keys=True)
+    ledger.db.execute("INSERT OR IGNORE INTO contract VALUES (?,?,?,?,?,?)", (contract["id"], contract["version"], body,
+                      hashlib.sha256(body.encode()).hexdigest(), now(), contract["owner"]))
+    run_id = uuid.uuid4().hex[:8]
+    ledger.db.execute("INSERT INTO run VALUES (?,?,?,?,?,?)", (run_id, contract["id"], contract["version"],
+                      contract["subject_ref"].format(**claim), actor, now()))
+    ledger.event(run_id, "action_claimed", claim)            # claim recorded, never used as evidence
+    verdict, level, reasons = "not_observed", "L1", []
+    wait = contract["settle_window_s"]
+    for attempt in range(1, contract["max_attempts"] + 1):
+        time.sleep(wait)
+        wait = contract["settle_window_s"]
+        ledger.event(run_id, "readback_started", {"attempt": attempt})
+        try:
+            fields, raw = reader(sor_path, claim)
+        except Blocked as e:
+            ledger.event(run_id, "readback_blocked", {"error": str(e), "retry_after": e.retry_after})
+            wait = min(e.retry_after if e.retry_after is not None else max(1, wait) * 2 ** attempt, 60)   # backoff, capped
+            verdict, level, reasons = "blocked", "L0", [str(e)]
+            continue
+        ledger.event(run_id, "readback_observed", fields, evidence=raw)
+        verdict, level, reasons = evaluate(contract, fields, claim)
+        if verdict != "not_observed": break                    # retry only missing evidence
+    seq = ledger.event(run_id, "verdict_final", {"verdict": verdict, "reasons": reasons})
+    ledger.db.execute("INSERT INTO verdict VALUES (?,?,?,?,?,?)", (run_id, verdict, level, independence, json.dumps(reasons), seq))
+    ledger.db.commit()
+    return run_id, verdict, level, reasons
+
+
+
+def check(contract, claim, reader, ledger="verify.db", actor=None, independence="full"):
+    """Python API. contract: dict or path; claim: dict; reader(sor, claim) -> (fields, raw_json).
+    Returns dict with verdict, level, reasons, run_id. Only verdict == "pass" means success."""
+    from . import contract as _c
+    c = _c.load(contract) if isinstance(contract, str) else contract
+    if not isinstance(contract, str):
+        errs = _c.validate(c)
+        if errs: raise ValueError("invalid contract: " + "; ".join(errs))
+    led = ledger if isinstance(ledger, Ledger) else Ledger(ledger)
+    run_id, v, level, reasons = verify(led, None, claim, c, reader, actor=actor or claim.get("actor", "unknown"), independence=independence)
+    return {"run_id": run_id, "verdict": v, "level": level, "reasons": reasons, "ok": v == "pass"}

verify/hubspot.py

@@ -0,0 +1,72 @@
+"""Verify reader for HubSpot CRM deals. Stdlib only.
+
+Env (never in code or chat):
+  HUBSPOT_VERIFY_TOKEN  private-app token with ONLY crm.objects.deals.read (Verify: read-only)
+
+Checks a RevOps agent's claim "deal moved to Closed Won for $X, linked to company Y".
+"""
+import json, os, tempfile, urllib.request, urllib.error
+from .core import Blocked, Ledger, verify
+
+CONTRACT = {
+    "id": "deal.closed_won.hubspot", "version": "1.0.0", "owner": "revops",
+    "target_system": "hubspot", "subject_ref": "deal:{deal}", "subject_present": "deal.exists",
+    "preconditions": [],
+    "postconditions": [{"path": "deal.dealstage", "op": "eq", "value": "closedwon"},
+                       {"path": "deal.amount", "op": "eq", "value": "{amount}"},
+                       {"path": "deal.company_id", "op": "eq", "value": "{company}"}],
+    "forbidden": [],
+    "required_level": "L2", "settle_window_s": 1.0, "max_attempts": 3,
+    "scope": ["deal.exists", "deal.dealstage", "deal.amount", "deal.company_id"],
+}
+
+
+def hs_http(token):
+    def http(method, path):
+        req = urllib.request.Request(f"https://api.hubapi.com{path}", method=method,
+                                     headers={"Authorization": f"Bearer {token}"})
+        try:
+            with urllib.request.urlopen(req, timeout=20) as r: return r.status, json.load(r)
+        except urllib.error.HTTPError as e:
+            if e.code == 404: return 404, {}
+            ra = e.headers.get("Retry-After")
+            raise Blocked(f"hubspot HTTP {e.code}", retry_after=float(ra) if ra else None)
+        except urllib.error.URLError as e:
+            raise Blocked(f"hubspot unreachable: {e.reason}")
+    return http
+
+
+def make_reader(http):
+    def reader(_unused, claim):
+        st, d = http("GET", f"/crm/v3/objects/deals/{claim['deal']}?properties=dealstage,amount&associations=companies")
+        p = d.get("properties", {}) if st == 200 else {}
+        companies = [a["id"] for a in d.get("associations", {}).get("companies", {}).get("results", [])] if st == 200 else []
+        amt = p.get("amount")
+        raw = {"deal.exists": st == 200, "deal.dealstage": p.get("dealstage"),
+               "deal.amount": float(amt) if amt not in (None, "") else None,     # HubSpot returns strings
+               "deal.company_id": companies[0] if len(companies) == 1 else (companies or None)}
+        return raw, json.dumps(raw, sort_keys=True)
+    return reader
+
+
+def fake_hubspot(deals):
+    def http(method, path):
+        if method != "GET": raise Blocked("hubspot HTTP 403: read-only scope")
+        d = deals.get(path.split("/")[5].split("?")[0])
+        if d is None: return 404, {}
+        return 200, {"properties": {"dealstage": d[0], "amount": d[1]},
+                     "associations": {"companies": {"results": [{"id": c} for c in d[2]]}}}
+    return http
+
+
+def check():
+    deals = {"1": ("closedwon", "4200", ["77"]), "2": ("contractsent", "4200", ["77"]),
+             "3": ("closedwon", "420", ["77"]), "4": ("closedwon", "4200", [])}
+    c = dict(CONTRACT, settle_window_s=0)
+    led, reader = Ledger(os.path.join(tempfile.mkdtemp(), "l.db")), make_reader(fake_hubspot(deals))
+    got = [verify(led, None, {"deal": d, "amount": 4200.0, "company": "77"}, c, reader)[1] for d in ("1", "2", "3", "4", "9")]
+    assert got == ["pass", "fail", "fail", "fail", "not_observed"], got
+    try: fake_hubspot(deals)("PATCH", "/crm/v3/objects/deals/1"); assert False
+    except Blocked: pass
+    assert led.verify_chain()
+    print("hubspot adapter offline check: ok")

verify/intercom.py

@@ -0,0 +1,82 @@
+"""Verify reader for Intercom conversations. Stdlib only.
+
+Env (never in code or chat):
+  INTERCOM_VERIFY_TOKEN  access token from an Intercom app granted only "Read conversations" (Verify: read-only)
+
+Checks a support agent's claim "conversation closed with a reply".
+Docs:
+  https://developers.intercom.com/docs/references/rest-api/api.intercom.io/conversations/retrieveconversation
+  https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/api-versioning
+  https://developers.intercom.com/docs/build-an-integration/learn-more/authentication
+  https://developers.intercom.com/docs/references/rest-api/errors/rate-limiting
+"""
+import json, os, tempfile, urllib.request, urllib.error
+from .core import Blocked, Ledger, verify
+
+API_VERSION = "2.17"   # pinned; bump deliberately after reading the changelog
+
+CONTRACT = {
+    "id": "conversation.closed_with_reply.intercom", "version": "1.0.0", "owner": "support",
+    "target_system": "intercom", "subject_ref": "conversation:{conversation}", "subject_present": "conversation.exists",
+    "preconditions": [],
+    "postconditions": [{"path": "conversation.state", "op": "eq", "value": "closed"},
+                       {"path": "conversation.admin_replies", "op": "gt", "value": 0}],
+    "forbidden": [{"path": "conversation.snoozed", "op": "eq", "value": True}],
+    "required_level": "L2", "settle_window_s": 1.0, "max_attempts": 3,
+    "scope": ["conversation.exists", "conversation.state", "conversation.admin_replies", "conversation.snoozed"],
+}
+
+
+def ic_http(token):
+    def http(method, path):
+        req = urllib.request.Request(f"https://api.intercom.io{path}", method=method, headers={
+            "Authorization": f"Bearer {token}", "Accept": "application/json", "Intercom-Version": API_VERSION})
+        try:
+            with urllib.request.urlopen(req, timeout=20) as r: return r.status, json.load(r)
+        except urllib.error.HTTPError as e:
+            if e.code == 404: return 404, {}
+            ra = e.headers.get("Retry-After")
+            raise Blocked(f"intercom HTTP {e.code}", retry_after=float(ra) if ra else None)
+        except urllib.error.URLError as e:
+            raise Blocked(f"intercom unreachable: {e.reason}")
+    return http
+
+
+def make_reader(http):
+    def reader(_unused, claim):
+        st, d = http("GET", f"/conversations/{claim['conversation']}?display_as=plaintext")
+        parts = d.get("conversation_parts", {}).get("conversation_parts", []) if st == 200 else []
+        replies = sum(1 for p in parts if p.get("part_type") == "comment"
+                      and (p.get("author") or {}).get("type") in ("admin", "bot"))
+        raw = {"conversation.exists": st == 200, "conversation.state": d.get("state"),
+               "conversation.admin_replies": replies if st == 200 else None,
+               "conversation.snoozed": (d.get("state") == "snoozed" or bool(d.get("snoozed_until"))) if st == 200 else None}
+        return raw, json.dumps(raw, sort_keys=True)
+    return reader
+
+
+def fake_intercom(convs):
+    """convs: id -> (state, snoozed_until, [(part_type, author_type), ...])"""
+    def http(method, path):
+        if method != "GET": raise Blocked("intercom HTTP 403: read-only token")
+        c = convs.get(path.split("/")[2].split("?")[0])
+        if c is None: return 404, {}
+        if c == "429": raise Blocked("intercom HTTP 429", retry_after=0)
+        return 200, {"state": c[0], "snoozed_until": c[1], "conversation_parts": {"conversation_parts": [
+            {"part_type": pt, "author": {"type": at}} for pt, at in c[2]]}}
+    return http
+
+
+def check():
+    convs = {"1": ("closed", None, [("comment", "user"), ("comment", "admin"), ("close", "admin")]),
+             "2": ("open", None, [("comment", "admin")]),
+             "3": ("closed", None, [("comment", "user"), ("close", "admin"), ("note", "admin")]),
+             "4": ("closed", 1900000000, [("comment", "bot")]), "5": "429"}
+    c = dict(CONTRACT, settle_window_s=0, max_attempts=1)
+    led, reader = Ledger(os.path.join(tempfile.mkdtemp(), "l.db")), make_reader(fake_intercom(convs))
+    got = [verify(led, None, {"conversation": i}, c, reader)[1] for i in ("1", "2", "3", "4", "9", "5")]
+    assert got == ["pass", "fail", "fail", "fail", "not_observed", "blocked"], got
+    try: fake_intercom(convs)("POST", "/conversations/1/reply"); assert False
+    except Blocked: pass
+    assert led.verify_chain()
+    print("intercom adapter offline check: ok")

verify/local.py

@@ -0,0 +1,103 @@
+"""Local demo: SQLite stands in for Stripe + Zendesk. No accounts, no network."""
+import sqlite3, json, os, uuid, shutil, tempfile
+from .core import Ledger, Blocked, verify as _verify
+
+# ---------------- system of record (stands in for Stripe + Zendesk) ----------------
+def make_sor(path):
+    db = sqlite3.connect(path)
+    db.executescript("""
+    CREATE TABLE charge(id TEXT PRIMARY KEY, status TEXT, amount INT, amount_refunded INT DEFAULT 0);
+    CREATE TABLE refund(id TEXT PRIMARY KEY, charge_id TEXT, amount INT);
+    CREATE TABLE ticket(id TEXT PRIMARY KEY, charge_id TEXT, status TEXT);
+    CREATE TABLE comment(ticket_id TEXT, public INT, author TEXT);
+    INSERT INTO charge VALUES ('ch_1','succeeded',5000,0),('ch_2','succeeded',5000,0),('ch_3','succeeded',5000,0),('ch_4','failed',5000,0);
+    INSERT INTO ticket VALUES ('t_1','ch_1','open'),('t_2','ch_2','open'),('t_3','ch_3','open'),('t_4','ch_4','open');
+    """)
+    db.commit(); db.close()
+
+# ---------------- the agent (with injected faults) ----------------
+def agent_handle(sor_path, ticket, fault=None):
+    """Writes with the agent's own read-write connection. Always *claims* success."""
+    db = sqlite3.connect(sor_path)
+    charge_id = db.execute("SELECT charge_id FROM ticket WHERE id=?", (ticket,)).fetchone()[0]
+    amount = db.execute("SELECT amount FROM charge WHERE id=?", (charge_id,)).fetchone()[0]
+    refund_id = "re_" + ticket[2:] + "_" + uuid.uuid4().hex[:4]
+    if fault != "timeout":                       # timeout: tool call died, nothing written
+        amt = amount // 2 if fault == "half" else amount
+        db.execute("INSERT INTO refund VALUES (?,?,?)", (refund_id, charge_id, amt))
+        db.execute("UPDATE charge SET amount_refunded=amount_refunded+? WHERE id=?", (amt, charge_id))
+        db.execute("UPDATE ticket SET status='solved' WHERE id=?", (ticket,))
+        db.execute("INSERT INTO comment VALUES (?,1,'agent')", (ticket,))
+    db.commit(); db.close()
+    return {"ticket": ticket, "charge_id": charge_id, "refund_id": refund_id, "amount": amount,
+            "agent_says": "Refund issued ✅"}
+
+# ---------------- contract (doc 02, JSON form) ----------------
+CONTRACT = {
+    "id": "refund.full.with_reply", "version": "1.0.0", "owner": "support-ops",
+    "target_system": "demo_sor", "subject_ref": "refund:{refund_id}",
+    "preconditions":  [{"path": "charge.status", "op": "eq", "value": "succeeded"}],
+    "postconditions": [{"path": "refund.amount", "op": "eq", "value": "{amount}"},
+                       {"path": "charge.amount_refunded", "op": "eq", "value": "{amount}"},
+                       {"path": "ticket.status", "op": "eq", "value": "solved"},
+                       {"path": "ticket.public_agent_replies", "op": "gt", "value": 0}],
+    "forbidden":      [{"path": "charge.refund_count", "op": "gt", "value": 1}],
+    "required_level": "L3", "settle_window_s": 0.05, "max_attempts": 3,
+    "scope": ["charge.status", "charge.amount_refunded", "charge.refund_count", "refund.amount",
+              "ticket.status", "ticket.public_agent_replies"],
+}
+
+def readback(sor_path, claim):
+    """Separate credential analogue: SQLite read-only URI. Returns only scoped fields."""
+    if not os.path.exists(sor_path): raise Blocked("system of record unreachable")
+    try:
+        db = sqlite3.connect(f"file:{sor_path}?mode=ro", uri=True)
+        c = db.execute("SELECT status, amount_refunded FROM charge WHERE id=?", (claim["charge_id"],)).fetchone()
+        n = db.execute("SELECT count(*) FROM refund WHERE charge_id=?", (claim["charge_id"],)).fetchone()[0]
+        r = db.execute("SELECT amount FROM refund WHERE id=?", (claim["refund_id"],)).fetchone()
+        t = db.execute("SELECT status FROM ticket WHERE id=?", (claim["ticket"],)).fetchone()
+        k = db.execute("SELECT count(*) FROM comment WHERE ticket_id=? AND public=1 AND author='agent'", (claim["ticket"],)).fetchone()[0]
+        db.close()
+    except sqlite3.Error as e:
+        raise Blocked(str(e))
+    raw = {"charge.status": c and c[0], "charge.amount_refunded": c and c[1], "charge.refund_count": n,
+           "refund.amount": r and r[0], "ticket.status": t and t[0], "ticket.public_agent_replies": k}
+    return {k: v for k, v in raw.items() if k in CONTRACT["scope"]}, json.dumps(raw, sort_keys=True)
+
+
+def verify(led, sor, claim):
+    return _verify(led, sor, claim, CONTRACT, readback)
+
+# ---------------- demo ----------------
+def demo(out="demo_out"):
+    shutil.rmtree(out, ignore_errors=True); os.makedirs(out)
+    sor, led = os.path.join(out, "system_of_record.db"), Ledger(os.path.join(out, "ledger.db"))
+    make_sor(sor)
+    plan = [("t_1", None), ("t_2", "half"), ("t_3", "timeout")]
+    claims = [agent_handle(sor, t, f) for t, f in plan]
+    print("\n== What the agent says ==")
+    for c in claims: print(f"  {c['ticket']}: {c['agent_says']}")
+    print(f"  Agent success rate: {len(claims)}/{len(claims)}\n\n== What Verify observed in the system of record ==")
+    results = [verify(led, sor, c) for c in claims]
+    for c, (rid, v, lvl, why) in zip(claims, results):
+        print(f"  {c['ticket']}  {v.upper():13} {lvl}  run={rid}" + (f"\n      - " + "\n      - ".join(why) if why else ""))
+    ok = sum(v == "pass" for _, v, *_ in results)
+    print(f"\n  Verified success rate: {ok}/{len(results)}")
+    print(f"  Ledger hash chain intact: {led.verify_chain()}  ({out}/ledger.db)\n")
+    return results
+
+def check():
+    d = tempfile.mkdtemp(); sor = os.path.join(d, "sor.db"); make_sor(sor); led = Ledger(os.path.join(d, "l.db"))
+    v = lambda c: verify(led, sor, c)[1]
+    assert v(agent_handle(sor, "t_1")) == "pass"
+    assert v(agent_handle(sor, "t_2", "half")) == "fail"
+    assert v(agent_handle(sor, "t_3", "timeout")) == "not_observed"
+    assert v(agent_handle(sor, "t_4")) == "inapplicable"           # charge failed: refund should never run
+    assert verify(led, os.path.join(d, "gone.db"), {"ticket": "t_1", "charge_id": "ch_1", "refund_id": "re_1", "amount": 5000})[1] == "blocked"
+    dup = agent_handle(sor, "t_1")                                 # second refund on same charge
+    assert v(dup) == "fail"
+    assert led.verify_chain()
+    led.db.execute("UPDATE event SET payload_json='{}' WHERE seq=1"); led.db.commit()
+    assert not led.verify_chain(), "tamper must be detected"
+    print("all 5 verdicts + duplicate refund + tamper detection: ok")
+