spck-conformance 0.1.0__tar.gz

spck_conformance-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: spck-conformance
+Version: 0.1.0
+Summary: Unofficial, capability-adaptive conformance runner for the Universal Commerce Protocol (UCP)
+Author: spck.dev
+License: MIT
+Project-URL: Homepage, https://spck.dev
+Project-URL: Source, https://github.com/vishkaty/ucp-conformance
+Keywords: ucp,universal-commerce-protocol,conformance,agentic-commerce
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: certifi>=2023.7.22
+
+# spck-conformance
+
+Unofficial, capability-adaptive conformance runner for the **Universal Commerce
+Protocol (UCP)**. Point it at any UCP server and get an honest, capability-scoped
+report — it runs only the checks that apply to what the server declares, and every
+check is kill-rate-validated (proven to catch its own defects) before it ships.
+
+> Independent project. Not affiliated with, endorsed by, or a substitute for the
+> official UCP conformance suite. It reports only the checks it actually runs.
+
+## Install
+
+```bash
+pip install spck-conformance
+```
+
+No third-party dependencies (Python ≥ 3.9, stdlib only).
+
+## Use
+
+```bash
+spck-conformance --server https://api.example.com \
+    [--config merchant.json] [--json] [--junit report.xml]
+```
+
+### Quickstart (30 seconds)
+
+```bash
+# 1. point it at your server — no config needed for the discovery + structure checks
+spck-conformance --server https://api.example.com
+
+# 2. scaffold a config tailored to YOUR server's declared capabilities
+spck-conformance --server https://api.example.com --init merchant.json
+#    -> fill in the FILL_ME placeholders (a product id, discount code, payment token…)
+
+# 3. re-run with the config to unlock the data-dependent checks
+spck-conformance --server https://api.example.com --config merchant.json
+```
+
+On a deviation the report shows **expected (the requirement) vs observed (your actual
+response)** so you can fix it directly, and the footer's **Next steps** tells you how to
+unlock any `not-tested` checks.
+
+### Use in CI (GitHub Action)
+
+```yaml
+# .github/workflows/ucp.yml
+jobs:
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: vishkaty/ucp-conformance@main
+        with:
+          server: https://api.example.com
+          config: merchant.json        # optional
+          # fail-on-deviation: false   # report-only mode
+```
+
+The job fails on any MUST deviation and writes a JUnit report (`ucp-conformance.xml`)
+your CI can display as a test run.
+
+- **`--config`** — optional JSON supplying data-dependent inputs (product id, discount
+  codes, a succeeding/failing payment, an out-of-stock id). Without it, those checks
+  are honestly `not-tested` rather than silently passed.
+- **`--json`** — full machine-readable report; each check cites its normative clause
+  (id, verbatim text, spec source).
+- **`--junit FILE`** — JUnit XML for CI (deviation → `<failure>`, not-applicable /
+  not-tested → `<skipped>`).
+- **Exit code** — `2` if any MUST deviates, else `0` (partial coverage is not a failure).
+
+## What it checks
+
+Discovery + profile structure, checkout lifecycle, idempotency, validation,
+fulfillment, order completion, payment-credential handling, discounts, catalog
+(search/lookup), and cart — scoped to the capabilities the target declares. The
+profile-schema check requires the native `ucp-schema` validator (not shipped in the
+wheel), so it reports `not-tested` here; run it from the source repo for full fidelity.
+
+Source, methodology, and the self-validating CI harness:
+<https://github.com/vishkaty/ucp-conformance>.

spck_conformance-0.1.0/README.md

@@ -0,0 +1,80 @@
+# spck-conformance
+
+Unofficial, capability-adaptive conformance runner for the **Universal Commerce
+Protocol (UCP)**. Point it at any UCP server and get an honest, capability-scoped
+report — it runs only the checks that apply to what the server declares, and every
+check is kill-rate-validated (proven to catch its own defects) before it ships.
+
+> Independent project. Not affiliated with, endorsed by, or a substitute for the
+> official UCP conformance suite. It reports only the checks it actually runs.
+
+## Install
+
+```bash
+pip install spck-conformance
+```
+
+No third-party dependencies (Python ≥ 3.9, stdlib only).
+
+## Use
+
+```bash
+spck-conformance --server https://api.example.com \
+    [--config merchant.json] [--json] [--junit report.xml]
+```
+
+### Quickstart (30 seconds)
+
+```bash
+# 1. point it at your server — no config needed for the discovery + structure checks
+spck-conformance --server https://api.example.com
+
+# 2. scaffold a config tailored to YOUR server's declared capabilities
+spck-conformance --server https://api.example.com --init merchant.json
+#    -> fill in the FILL_ME placeholders (a product id, discount code, payment token…)
+
+# 3. re-run with the config to unlock the data-dependent checks
+spck-conformance --server https://api.example.com --config merchant.json
+```
+
+On a deviation the report shows **expected (the requirement) vs observed (your actual
+response)** so you can fix it directly, and the footer's **Next steps** tells you how to
+unlock any `not-tested` checks.
+
+### Use in CI (GitHub Action)
+
+```yaml
+# .github/workflows/ucp.yml
+jobs:
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: vishkaty/ucp-conformance@main
+        with:
+          server: https://api.example.com
+          config: merchant.json        # optional
+          # fail-on-deviation: false   # report-only mode
+```
+
+The job fails on any MUST deviation and writes a JUnit report (`ucp-conformance.xml`)
+your CI can display as a test run.
+
+- **`--config`** — optional JSON supplying data-dependent inputs (product id, discount
+  codes, a succeeding/failing payment, an out-of-stock id). Without it, those checks
+  are honestly `not-tested` rather than silently passed.
+- **`--json`** — full machine-readable report; each check cites its normative clause
+  (id, verbatim text, spec source).
+- **`--junit FILE`** — JUnit XML for CI (deviation → `<failure>`, not-applicable /
+  not-tested → `<skipped>`).
+- **Exit code** — `2` if any MUST deviates, else `0` (partial coverage is not a failure).
+
+## What it checks
+
+Discovery + profile structure, checkout lifecycle, idempotency, validation,
+fulfillment, order completion, payment-credential handling, discounts, catalog
+(search/lookup), and cart — scoped to the capabilities the target declares. The
+profile-schema check requires the native `ucp-schema` validator (not shipped in the
+wheel), so it reports `not-tested` here; run it from the source repo for full fidelity.
+
+Source, methodology, and the self-validating CI harness:
+<https://github.com/vishkaty/ucp-conformance>.

spck_conformance-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spck-conformance"
+version = "0.1.0"
+description = "Unofficial, capability-adaptive conformance runner for the Universal Commerce Protocol (UCP)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "spck.dev"}]
+keywords = ["ucp", "universal-commerce-protocol", "conformance", "agentic-commerce"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+]
+# certifi provides a CA bundle so TLS verification works on Pythons that ship none
+# (common on macOS python.org builds). Everything else is stdlib.
+dependencies = ["certifi>=2023.7.22"]
+
+[project.urls]
+Homepage = "https://spck.dev"
+Source = "https://github.com/vishkaty/ucp-conformance"
+
+[project.scripts]
+spck-conformance = "spck_conformance.cli:main"
+
+[tool.setuptools]
+packages = ["spck_conformance"]
+
+[tool.setuptools.package-data]
+spck_conformance = [
+  "_bundle/conformance/checks/*.py",
+  "_bundle/conformance/selfcheck/*.py",
+  "_bundle/conformance/requirements/*/*.json",
+]

spck_conformance-0.1.0/setup.cfg

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

spck_conformance-0.1.0/spck_conformance/__init__.py

@@ -0,0 +1,2 @@
+"""spck-conformance — unofficial capability-adaptive UCP conformance runner."""
+__version__ = "0.1.0"

spck_conformance-0.1.0/spck_conformance/_bundle/conformance/checks/engine.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+engine.py — Phase 1 register-driven conformance check engine.
+
+A check cites the register requirement(s) it verifies, evaluates a real server
+response, and declares the mutations that MUST break it. Before any check counts
+toward a verdict, the engine self-validates it: the check must pass on the clean
+response AND fail on every declared mutant (kill-rate). A check that isn't
+mutation-safe is reported kill_safe=False, which the verdict gate downgrades to
+inconclusive (so it can never produce a green). Results feed verdict_gate for an
+honest, coverage-gated report.
+
+Mutations here operate on the CAPTURED response (deterministic golden+mutation),
+which works for stateful checks too — we mutate the final response under test.
+The live mutation_proxy remains for integration/timing/replay cases.
+"""
+import json, sys, ssl, urllib.request, urllib.error, pathlib, glob
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "selfcheck"))
+from verdict_gate import CheckResult, aggregate, CLEAN, DEVIATION, INCONCLUSIVE  # noqa: E402
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+REQ_DIR = ROOT / "conformance" / "requirements"
+
+# ---- TLS: use certifi's CA bundle if available (many Pythons ship no bundle, so a
+# plain urlopen against https fails with CERTIFICATE_VERIFY_FAILED). --insecure skips
+# verification entirely (testing only). -------------------------------------------
+def _make_ssl_context(insecure=False):
+    if insecure:
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        return ctx
+    try:
+        import certifi
+        return ssl.create_default_context(cafile=certifi.where())
+    except Exception:
+        return ssl.create_default_context()
+
+INSECURE = False
+_SSL_CTX = _make_ssl_context()
+
+def set_insecure(v):
+    """Toggle TLS verification (used by the --insecure CLI flag)."""
+    global INSECURE, _SSL_CTX
+    INSECURE = bool(v)
+    _SSL_CTX = _make_ssl_context(INSECURE)
+
+class TLSError(Exception):
+    """Raised on a TLS certificate verification failure, with a friendly hint."""
+
+# ---- response capture -------------------------------------------------------
+class Resp:
+    def __init__(self, status, headers, body):
+        self.status, self.headers, self.body = status, dict(headers), body
+        try: self.json = json.loads(body)
+        except Exception: self.json = None
+    def clone(self):
+        return Resp(self.status, dict(self.headers), self.body)
+
+def fetch(base, path, method="GET", body=None, headers=None):
+    data = json.dumps(body).encode() if body is not None else None
+    h = {"Content-Type": "application/json", **(headers or {})}
+    req = urllib.request.Request(base.rstrip("/") + path, data=data, method=method, headers=h)
+    try:
+        with urllib.request.urlopen(req, context=_SSL_CTX) as r:
+            return Resp(r.status, r.getheaders(), r.read())
+    except urllib.error.HTTPError as e:
+        return Resp(e.code, e.headers.items(), e.read())
+    except Exception as e:
+        return Resp(0, {}, str(e).encode())
+
+# ---- mutations on a captured response (defect injection) --------------------
+def _reparse(r):
+    r.body = json.dumps(r.json).encode() if r.json is not None else r.body
+    return r
+def mutate(resp, mut):
+    r = resp.clone()
+    name, _, arg = mut.partition(":")
+    if name == "status":         r.status = int(arg); return r
+    if name == "empty":          r.body = b""; r.json = None; return r
+    if name == "corrupt-json":   r.body = (r.body or b"{}")[:-1]; r.json = None; return r
+    if name == "drop" and r.json is not None:
+        cur = r.json; parts = arg.split(".")
+        for p in parts[:-1]:
+            if isinstance(cur, list) and p.isdigit() and int(p) < len(cur): cur = cur[int(p)]
+            elif isinstance(cur, dict): cur = cur.get(p)
+            else: cur = None
+            if cur is None: break
+        last = parts[-1]
+        if isinstance(cur, dict): cur.pop(last, None)
+        elif isinstance(cur, list) and last.isdigit() and int(last) < len(cur): cur.pop(int(last))
+        return _reparse(r)
+    if name == "set" and r.json is not None:
+        path, _, v = arg.partition("="); val = json.loads(v)
+        cur = r.json; parts = path.split(".")
+        for p in parts[:-1]:
+            if isinstance(cur, list) and p.isdigit() and int(p) < len(cur): cur = cur[int(p)]
+            elif isinstance(cur, dict): cur = cur.get(p)
+            else: cur = None
+            if cur is None: break
+        last = parts[-1]
+        if isinstance(cur, dict): cur[last] = val
+        elif isinstance(cur, list) and last.isdigit() and int(last) < len(cur): cur[int(last)] = val
+        return _reparse(r)
+    if name == "hset":       # set/replace a response header (case-insensitive): hset:Content-Type=text/plain
+        k, _, v = arg.partition("=")
+        for hk in [h for h in r.headers if h.lower() == k.lower()]: r.headers.pop(hk)
+        r.headers[k] = v; return r
+    if name == "hdrop":      # remove a response header (case-insensitive)
+        for hk in [h for h in r.headers if h.lower() == arg.lower()]: r.headers.pop(hk)
+        return r
+    return r  # no-op (mutation not applicable)
+
+# ---- check spec -------------------------------------------------------------
+class Check:
+    def __init__(self, cid, req_ids, keyword, fetch_fn, predicate, mutations):
+        self.id, self.req_ids, self.keyword = cid, req_ids, keyword
+        self.fetch_fn, self.predicate, self.mutations = fetch_fn, predicate, mutations
+
+def run_check(chk, base):
+    """Returns (results: list[CheckResult], detail: dict). kill_safe is computed by
+    mutation: clean must pass, every declared mutant must deviate."""
+    try:
+        golden = chk.fetch_fn(base)
+    except Exception as e:
+        kill_safe = False
+        res = [CheckResult(rid, chk.keyword, INCONCLUSIVE, kill_safe) for rid in chk.req_ids]
+        return res, {"clean": "error:" + str(e), "kills": "", "kill_safe": kill_safe}
+    clean = chk.predicate(golden)
+    kills, survivors = 0, []
+    for m in chk.mutations:
+        if chk.predicate(mutate(golden, m)) == DEVIATION: kills += 1
+        else: survivors.append(m)
+    kill_safe = (clean == CLEAN and not survivors)
+    status = clean if kill_safe else (clean if clean == DEVIATION else INCONCLUSIVE)
+    res = [CheckResult(rid, chk.keyword, status, kill_safe) for rid in chk.req_ids]
+    return res, {"clean": clean, "kills": f"{kills}/{len(chk.mutations)}",
+                 "kill_safe": kill_safe, "survivors": survivors}
+
+# ---- inscope MUSTs from the register (coverage denominator) -----------------
+def inscope_musts(version, transports=("rest", "any")):
+    ids = set()
+    for f in glob.glob(str(REQ_DIR / version / "*.json")):
+        for r in json.load(open(f)).get("rows", []):
+            if r["keyword"] in ("MUST", "MUST NOT") and r["testability"] == "testable" \
+               and any(t in transports for t in r.get("transport", [])):
+                ids.add(r["id"])
+    return ids
+
+def run_report(checks, base, version, scope_stamp, disclaimer, transports=("rest", "any")):
+    all_results, details = [], []
+    for chk in checks:
+        res, det = run_check(chk, base)
+        all_results += res
+        details.append((chk, det))
+    rep = aggregate(all_results, inscope_musts(version, transports), scope_stamp, disclaimer)
+    return rep, details