verify-outcomes 0.4.1__tar.gz

verify_outcomes-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Shankar
+
+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.

verify_outcomes-0.4.1/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: verify-outcomes
+Version: 0.4.1
+Summary: Independent readback verification for AI agents and automations. Unknown fails closed.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/abhishekshankar/verify
+Project-URL: Issues, https://github.com/abhishekshankar/verify/issues
+Keywords: ai-agents,verification,audit,stripe,zendesk,hubspot,llmops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Verify
+
+Your agent says "done". Verify checks the system of record.
+
+AI agents and automations report success from their own logs. Verify ignores the claim, reads the
+system of record back with a **separate read-only credential**, and returns one of five verdicts.
+Anything it can't confirm fails closed.
+
+![Verify demo: agent claims 3/3 refunds, Stripe confirms 1/3](docs/verify-demo.gif)
+
+```
+Agent says:      3/3 "Refund issued ✅"
+Verify (Stripe test mode, independence=full):
+  PASS          L2
+  FAIL          L2   refund.amount 2500 ≠ 5000
+  NOT_OBSERVED  L1   refund never reached Stripe
+Verified success rate: 1/3   hash chain intact: True
+```
+Real output, Stripe test mode, 2026-11-07. The same run on Zendesk: 1/3.
+
+## Verdicts
+| Verdict | Meaning |
+|---|---|
+| `pass` | every postcondition observed in the system of record |
+| `fail` | a postcondition observed false, or a forbidden side effect observed |
+| `inapplicable` | preconditions not met; the action should never have run |
+| `not_observed` | the subject record is absent after the observe window |
+| `blocked` | readback impossible (auth, outage, rate limit) |
+
+Only `pass` counts as success.
+
+## Quick start
+Python 3.10+, no dependencies.
+```bash
+pip install verify-outcomes          # or: pip install git+https://github.com/abhishekshankar/verify
+verify --version
+verify init stripe                   # writes contracts/ and an example claim
+verify selfcheck        # all verdicts, tamper detection, every adapter offline
+verify demo local       # SQLite stands in for Stripe + Zendesk
+verify ledger demo_out/ledger.db
+verify validate contracts/*.json   # reject bad contracts before any action runs
+verify ledger export demo_out/ledger.db audit.jsonl && verify ledger verify audit.jsonl
+```
+
+Live adapters (test accounts only; keys come from env vars, never from code):
+```bash
+STRIPE_AGENT_KEY=sk_test_... STRIPE_VERIFY_KEY=rk_test_... verify demo stripe
+ZENDESK_SUBDOMAIN=... ZENDESK_AGENT_OAUTH=... ZENDESK_VERIFY_TOKEN=... verify demo zendesk
+```
+`STRIPE_VERIFY_KEY` should be a restricted key with Charges and Refunds set to Read.
+`ZENDESK_VERIFY_TOKEN` should be an OAuth token with scope `read`. `HUBSPOT_VERIFY_TOKEN` should be a private-app token with only `crm.objects.deals.read`. `INTERCOM_VERIFY_TOKEN` should be an Intercom app access token with only the Read conversations permission. `SHOPIFY_SHOP` (the `*.myshopify.com` subdomain) and `SHOPIFY_VERIFY_TOKEN` should come from a custom app with only `read_orders`. Live Stripe keys are refused.
+
+## Check one real action
+Write a contract once, then check each claim the agent makes. The exit code is 0 only on `pass`, so it can gate a pipeline. A claim missing a field the contract needs is rejected (exit 2) before anything is read.
+```bash
+STRIPE_VERIFY_KEY=rk_test_... verify check contracts/refund.full.stripe.json claim.json --ledger verify.db
+```
+`claim.json` holds what the agent says it did, e.g. `{"actor": "support-agent", "charge_id": "ch_...", "refund_id": "re_...", "amount": 5000}` (see `examples/`).
+
+Many claims at once (one JSON object per line; exit 0 only if every claim passes):
+```bash
+verify check-batch contracts/refund.full.stripe.json claims.jsonl --ledger verify.db
+```
+
+## Hosted ledger (optional)
+`hosted/` is an append-only, multi-tenant ledger API (SQLite or Postgres). Push a local ledger to it with
+`VERIFY_HOSTED_KEY=... verify push verify.db --to https://ledger.example.com`. Deployment to AWS us-east-2 is in `hosted/deploy/` (Terraform; not applied).
+
+## Use from an agent
+`python -m verify.mcp_server` is an MCP server with `verify_check` and `verify_validate` (see `docs/MCP.md`). Framework examples are in `examples/`.
+
+## How it works
+1. **Contract**, written before the action: subject, preconditions, postconditions, forbidden effects, windows, scope.
+2. **Claim**: the actor's "done" is recorded, never used as evidence.
+3. **Readback**: an adapter reads only the fields in scope, with its own credential.
+4. **Verdict**: evaluated, then written to an append-only SQLite ledger (`synchronous=FULL`) where each event hashes the one before it.
+
+## Layout
+Python API: `verify.check(contract, claim, reader)`; see `docs/ADAPTERS.md`. Contracts: `docs/CONTRACTS.md`.
+
+`src/verify/core.py` holds evaluation, the ledger and the verify loop; `contract.py` loads and validates contracts (`contracts/*.json`). The adapters are `stripe.py`, `zendesk.py`, `hubspot.py` (deals), `intercom.py` (conversations), `shopify.py` (refunds, Admin GraphQL) (the last three offline-tested, live run pending) and `local.py`.
+
+## Status
+v0.4, pre-production. Not yet a stable API. MIT licence.

verify_outcomes-0.4.1/README.md

@@ -0,0 +1,84 @@
+# Verify
+
+Your agent says "done". Verify checks the system of record.
+
+AI agents and automations report success from their own logs. Verify ignores the claim, reads the
+system of record back with a **separate read-only credential**, and returns one of five verdicts.
+Anything it can't confirm fails closed.
+
+![Verify demo: agent claims 3/3 refunds, Stripe confirms 1/3](docs/verify-demo.gif)
+
+```
+Agent says:      3/3 "Refund issued ✅"
+Verify (Stripe test mode, independence=full):
+  PASS          L2
+  FAIL          L2   refund.amount 2500 ≠ 5000
+  NOT_OBSERVED  L1   refund never reached Stripe
+Verified success rate: 1/3   hash chain intact: True
+```
+Real output, Stripe test mode, 2026-11-07. The same run on Zendesk: 1/3.
+
+## Verdicts
+| Verdict | Meaning |
+|---|---|
+| `pass` | every postcondition observed in the system of record |
+| `fail` | a postcondition observed false, or a forbidden side effect observed |
+| `inapplicable` | preconditions not met; the action should never have run |
+| `not_observed` | the subject record is absent after the observe window |
+| `blocked` | readback impossible (auth, outage, rate limit) |
+
+Only `pass` counts as success.
+
+## Quick start
+Python 3.10+, no dependencies.
+```bash
+pip install verify-outcomes          # or: pip install git+https://github.com/abhishekshankar/verify
+verify --version
+verify init stripe                   # writes contracts/ and an example claim
+verify selfcheck        # all verdicts, tamper detection, every adapter offline
+verify demo local       # SQLite stands in for Stripe + Zendesk
+verify ledger demo_out/ledger.db
+verify validate contracts/*.json   # reject bad contracts before any action runs
+verify ledger export demo_out/ledger.db audit.jsonl && verify ledger verify audit.jsonl
+```
+
+Live adapters (test accounts only; keys come from env vars, never from code):
+```bash
+STRIPE_AGENT_KEY=sk_test_... STRIPE_VERIFY_KEY=rk_test_... verify demo stripe
+ZENDESK_SUBDOMAIN=... ZENDESK_AGENT_OAUTH=... ZENDESK_VERIFY_TOKEN=... verify demo zendesk
+```
+`STRIPE_VERIFY_KEY` should be a restricted key with Charges and Refunds set to Read.
+`ZENDESK_VERIFY_TOKEN` should be an OAuth token with scope `read`. `HUBSPOT_VERIFY_TOKEN` should be a private-app token with only `crm.objects.deals.read`. `INTERCOM_VERIFY_TOKEN` should be an Intercom app access token with only the Read conversations permission. `SHOPIFY_SHOP` (the `*.myshopify.com` subdomain) and `SHOPIFY_VERIFY_TOKEN` should come from a custom app with only `read_orders`. Live Stripe keys are refused.
+
+## Check one real action
+Write a contract once, then check each claim the agent makes. The exit code is 0 only on `pass`, so it can gate a pipeline. A claim missing a field the contract needs is rejected (exit 2) before anything is read.
+```bash
+STRIPE_VERIFY_KEY=rk_test_... verify check contracts/refund.full.stripe.json claim.json --ledger verify.db
+```
+`claim.json` holds what the agent says it did, e.g. `{"actor": "support-agent", "charge_id": "ch_...", "refund_id": "re_...", "amount": 5000}` (see `examples/`).
+
+Many claims at once (one JSON object per line; exit 0 only if every claim passes):
+```bash
+verify check-batch contracts/refund.full.stripe.json claims.jsonl --ledger verify.db
+```
+
+## Hosted ledger (optional)
+`hosted/` is an append-only, multi-tenant ledger API (SQLite or Postgres). Push a local ledger to it with
+`VERIFY_HOSTED_KEY=... verify push verify.db --to https://ledger.example.com`. Deployment to AWS us-east-2 is in `hosted/deploy/` (Terraform; not applied).
+
+## Use from an agent
+`python -m verify.mcp_server` is an MCP server with `verify_check` and `verify_validate` (see `docs/MCP.md`). Framework examples are in `examples/`.
+
+## How it works
+1. **Contract**, written before the action: subject, preconditions, postconditions, forbidden effects, windows, scope.
+2. **Claim**: the actor's "done" is recorded, never used as evidence.
+3. **Readback**: an adapter reads only the fields in scope, with its own credential.
+4. **Verdict**: evaluated, then written to an append-only SQLite ledger (`synchronous=FULL`) where each event hashes the one before it.
+
+## Layout
+Python API: `verify.check(contract, claim, reader)`; see `docs/ADAPTERS.md`. Contracts: `docs/CONTRACTS.md`.
+
+`src/verify/core.py` holds evaluation, the ledger and the verify loop; `contract.py` loads and validates contracts (`contracts/*.json`). The adapters are `stripe.py`, `zendesk.py`, `hubspot.py` (deals), `intercom.py` (conversations), `shopify.py` (refunds, Admin GraphQL) (the last three offline-tested, live run pending) and `local.py`.
+
+## Status
+v0.4, pre-production. Not yet a stable API. MIT licence.

verify_outcomes-0.4.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "verify-outcomes"
+version = "0.4.1"
+description = "Independent readback verification for AI agents and automations. Unknown fails closed."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["ai-agents", "verification", "audit", "stripe", "zendesk", "hubspot", "llmops"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Testing",
+  "Topic :: System :: Monitoring",
+]
+
+[project.urls]
+Homepage = "https://github.com/abhishekshankar/verify"
+Issues = "https://github.com/abhishekshankar/verify/issues"
+
+[project.scripts]
+verify = "verify.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

verify_outcomes-0.4.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

verify_outcomes-0.4.1/src/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_outcomes-0.4.1/src/verify/__main__.py

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

verify_outcomes-0.4.1/src/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_outcomes-0.4.1/src/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_outcomes-0.4.1/src/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"}