Bound interoperability claims to tested behavior

README.md

@@ -11,7 +11,7 @@ library_name: kernels
 license: apache-2.0
 szl-governance:
   verdict: INTEROP-PROVENANCE
-  interop: "in-toto Statement v1 + SLSA provenance v1 — spec-exact, signer/verifier-ready"
+  interop: "in-toto Statement v1 + SLSA provenance v1 shapes — repository-selfchecked; external compatibility must be tested"
   lambda: "Conjecture 1 (open) — proven_trust structurally locked False"
   energy: "MEASURED-only — real NVML per-kernel delta; None when no GPU, never fabricated"
   honest_blocked: "BLOCKED nodes are surfaced in the provenance DAG, never silently dropped"
@@ -19,9 +19,16 @@ szl-governance:
 
 # szl-provctl — provenance-DAG control + supply-chain interop
 
-**The lane the supply-chain leaders leave open.** Sigstore, SLSA and in-toto define the *formats*; CodeCarbon *measures* joules; NeMo Guardrails / Llama Guard *block*. But as of 2026, **no tool** (a) emits a governed run as a spec-exact in-toto v1 Statement + SLSA provenance, (b) walks an **ML provenance DAG and verifies every edge**, or (c) measures energy **per kernel call** bound to a signable provenance chain. `szl-provctl` does all three — turning a [`szl-kernels`](https://huggingface.co/SZLHOLDINGS/szl-kernels) `UnifiedReceiptChain` into the exact shapes the rest of the ecosystem already verifies.
+**A provenance-DAG and supply-chain interoperability kernel.** `szl-provctl`
+emits declared in-toto Statement v1 and SLSA provenance v1 shapes, walks an ML
+provenance DAG and checks its recorded edges, and can bind a per-kernel NVML
+energy observation to a signable provenance chain. It converts a
+[`szl-kernels`](https://huggingface.co/SZLHOLDINGS/szl-kernels)
+`UnifiedReceiptChain` into these documented forms. No exhaustive ecosystem or
+novelty claim is made; compatibility with a particular external verifier must
+be tested separately.
 
-> Part of the [`szl-kernels`](https://huggingface.co/SZLHOLDINGS/szl-kernels) governed-kernel series. Where [`szl-govsign`](https://huggingface.co/SZLHOLDINGS/szl-govsign) *signs* a verdict and [`szl-blocked`](https://huggingface.co/SZLHOLDINGS/szl-blocked) *records a refusal*, `szl-provctl` makes a governed run **interoperable** — a standard attestation the whole supply-chain world can read, and a DAG anyone can re-verify.
+> Part of the [`szl-kernels`](https://huggingface.co/SZLHOLDINGS/szl-kernels) governed-kernel series. Where [`szl-govsign`](https://huggingface.co/SZLHOLDINGS/szl-govsign) *signs* a verdict and [`szl-blocked`](https://huggingface.co/SZLHOLDINGS/szl-blocked) *records a refusal*, `szl-provctl` serializes a governed run into documented attestation shapes and provides an offline DAG verifier for the records it produces.
 
 ## Quickstart
 
@@ -40,7 +47,7 @@ print(pc.selfcheck()["ok"])   # True — 23 checks: interop shapes, DAG verify/t
 chain = pc.UnifiedReceiptChain()
 chain.emit("governed_norm", "rms_norm", {"in_shape": [4, 64], "eps": 1e-6})
 
-# 1) Interop — the exact payload the ecosystem verifies
+# 1) Interop — documented payload shapes for compatibility testing
 stmt = pc.statement_from_chain(chain, lambda_score=0.9, decision="ALLOWED")
 assert stmt["_type"] == "https://in-toto.io/Statement/v1"
 assert stmt["subject"][0]["digest"]["sha3_256"] == chain.head()   # bound to the chain head
@@ -67,15 +74,15 @@ r = pc.measure_kernel_energy(chain, lambda x: x * 2, kernel="governed_norm", op=
 print(r["receipt"]["attrs"]["label"], r["receipt"]["attrs"]["joules"])
 ```
 
-## Three frontiers it owns
+## Three implemented capabilities
 
-1. **Interop bridge → the standard world.** `statement_from_chain(...)` emits a spec-exact **in-toto v1 Statement** (`https://in-toto.io/Statement/v1`) whose `subject` digest *is* the chain head and whose `predicateType` is the governance predicate — the exact payload a DSSE envelope / Sigstore Bundle wraps (cosign v2.6 `--statement`). `slsa_statement(...)` emits a **SLSA v1.0 provenance** predicate (`https://slsa.dev/provenance/v1`) so a governed run is a first-class build-provenance event.
-2. **Provenance-DAG traversal — the open frontier.** SLSA/in-toto define `resolvedDependencies` but ship no tool that recursively verifies an ML provenance DAG. `ProvenanceDAG.verify_dag()` topologically resolves the graph, verifies **each** chain's internal hash-chain *and* **each** edge's asserted dependency head, and returns the first break. **honest-BLOCKED nodes are surfaced, never dropped.**
+1. **Interop shapes.** `statement_from_chain(...)` emits a declared **in-toto v1 Statement** (`https://in-toto.io/Statement/v1`) whose `subject` digest is the chain head and whose `predicateType` is the governance predicate. `slsa_statement(...)` emits a declared **SLSA v1.0 provenance** predicate (`https://slsa.dev/provenance/v1`). The repository selfcheck covers required fields and bindings; validate against your chosen external verifier before production use.
+2. **Provenance-DAG traversal.** `ProvenanceDAG.verify_dag()` topologically resolves the graph, verifies **each** chain's internal hash-chain and **each** recorded edge's asserted dependency head, and returns the first break. **honest-BLOCKED nodes are surfaced, never dropped.** This is verification of the supplied records, not independent proof that omitted events never occurred.
 3. **Per-kernel MEASURED energy.** `measure_kernel_energy(...)` reads the **real NVML cumulative-energy counter delta** around a *single* kernel call and writes a receipt naming the exact kernel/op measured — energy bound to kernel identity. No GPU/NVML → `joules=None`, `UNAVAILABLE_NO_NVML`. **Never fabricated.**
 
 ## What it proves — and what it does NOT
 
-- ✅ The in-toto/SLSA output is **field-name spec-exact** (verified against the in-toto v1 Statement spec and slsa.dev/spec/v1.0/provenance) — a real signer/verifier can consume it.
+- ✅ The repository selfcheck validates the documented in-toto/SLSA field shapes and chain-head bindings. External signer/verifier compatibility is **not** claimed until tested with that implementation.
 - ❌ It does **NOT** prove Λ uniqueness — `proven_trust` is **structurally locked `False`** (no code path sets it True). Λ = **Conjecture 1 (OPEN)**, advisory only.
 - ❌ It does **NOT** fabricate energy — a non-`MEASURED` joule value is **rejected at build time**.
 - The hash-chain digest is an **integrity fingerprint**, not a signature; signing is `szl-govsign`'s job (DSSE / Sigstore, out of band).