sum-engine 0.7.0__tar.gz → 0.7.1__tar.gz

{sum_engine-0.7.0/sum_engine.egg-info → sum_engine-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sum-engine
-Version: 0.7.0
+Version: 0.7.1
 Summary: SUM — bidirectional knowledge distillation with optional cryptographic attestation. Pipe prose, get a CanonicalBundle (HMAC / Ed25519 / W3C VC 2.0), verify anywhere.
 Author: ototao
 License: Apache-2.0
@@ -24,7 +24,8 @@ License-File: LICENSE
 Requires-Dist: cryptography>=41.0.0
 Requires-Dist: sympy>=1.12
 Provides-Extra: sieve
-Requires-Dist: spacy>=3.7.0; extra == "sieve"
+Requires-Dist: spacy>=3.8.0; extra == "sieve"
+Requires-Dist: click>=8.0; extra == "sieve"
 Provides-Extra: openai
 Requires-Dist: openai<3.0.0,>=1.40.0; extra == "openai"
 Requires-Dist: pydantic>=2.0.0; extra == "openai"
@@ -34,7 +35,7 @@ Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.97.0; extra == "anthropic"
 Requires-Dist: pydantic>=2.0.0; extra == "anthropic"
 Provides-Extra: receipt-verify
-Requires-Dist: joserfc>=1.0.0; extra == "receipt-verify"
+Requires-Dist: joserfc<2.0.0,>=1.0.0; extra == "receipt-verify"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == "mcp"
 Provides-Extra: research
@@ -85,7 +86,7 @@ Headline supporting numbers (each links to its source of truth):
 | Three-runtime byte-symmetric Ed25519 over JCS bytes | provable; locked by `make xruntime` (K1–K4) + `make xruntime-adversarial` (A1–A6) | [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.2, §1.3.1 |
 | Canonical round-trip `reconstruct(parse(canonical_tome(S))) == S` | provable; 0.00% drift on every CI run | [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.1 |
 | Render receipt — `sum.render_receipt.v1`, Ed25519 / JCS / detached JWS | shipped; verifier in three runtimes | [`docs/RENDER_RECEIPT_FORMAT.md`](docs/RENDER_RECEIPT_FORMAT.md) |
-| Slider fact preservation: median 1.000, p10 0.769 (long n=16) / 0.818 (short n=8) | empirical-benchmark | [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md) |
+| Slider fact preservation: median 1.000, p10 0.769 (long n=16) / 0.818 (short n=8) | empirical-benchmark — measured; same-commit replay receipt still pending (bench-hardening T2/T3) | [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md) |
 | Extraction F1 = 1.000 (`seed_v1`), 0.762 with precision 1.000 (`seed_v2`) | empirical-benchmark | [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §2.1 |
 
 A render receipt verifies the *render attestation* (issuer signed this tome, these triples, this slider position, this model, at this time). It does not verify the truth of the tome's content — that is what the slider bench measures separately. See [`docs/RENDER_RECEIPT_FORMAT.md`](docs/RENDER_RECEIPT_FORMAT.md) §5 for the explicit trust scope.
@@ -123,13 +124,13 @@ A minimal Node verifier using `jose` + `canonicalize` is in [`docs/RENDER_RECEIP
 | Cross-runtime trust triangle | locked by CI (`make xruntime`) | K1 / K1-mw / K2 / K3 / K4 — Python ↔ Node ↔ Browser agree byte-for-byte on valid bundles. `make xruntime-adversarial` adds A1–A6 rejection-class equivalence. |
 | 5-axis slider rendering surface | density actioned deterministically; length / formality / audience / perspective LLM-conditioned. Two dispatch paths: Worker `/api/render` (Anthropic + Cloudflare AI Gateway optional) producing `sum.render_receipt.v1`, OR Python `sum transform apply slider` (OpenAI via `OPENAI_API_KEY`) producing `sum.transform_receipt.v1` | bench: median LLM-axis fact preservation 1.000, p10 0.769 (long, n=16) / 0.818 (short, n=8), order preservation 1.000 wherever measurable. Tightening worktrail at [`docs/BENCH_HARDENING_FROM_QCVV.md`](docs/BENCH_HARDENING_FROM_QCVV.md) adds iteration-stability + DKW worst-case bounds + capability-region headlines |
 | MCP server (`sum-mcp` console script) | shipped | five tools (`extract` / `attest` / `verify` / `inspect` / `schema`) exposed over stdio; bundles attested via MCP verify byte-identically through the CLI / Node / browser verifiers |
-| Transform substrate (`sum.transform_receipt.v1` + registry) | shipped (CLI in repo HEAD; PyPI catch-up tag pending) | `sum transform list` / `sum transform apply <name>` — three registered transforms (`slider` / `extract` / `compose`); receipts via Ed25519 / JCS / detached JWS just like render-receipts; 20-fixture cross-runtime K-matrix locks accept + reject across Python ↔ Node ↔ browser; T4 `source_chain_hash` binds receipts to source byte ranges; T5 `ShareableRender` round-trips signed renders for offline verification; T6 multi-school extract runs two extractors in tandem for adversarial-divergence detection. Wire spec at [`docs/TRANSFORM_RECEIPT_FORMAT.md`](docs/TRANSFORM_RECEIPT_FORMAT.md); design at [`docs/TRANSFORM_REGISTRY.md`](docs/TRANSFORM_REGISTRY.md). |
+| Transform substrate (`sum.transform_receipt.v1` + registry) | shipped on PyPI ≥ 0.7.0 | `sum transform list` / `sum transform apply <name>` — three registered transforms (`slider` / `extract` / `compose`); receipts via Ed25519 / JCS / detached JWS just like render-receipts; 20-fixture cross-runtime K-matrix locks accept + reject across Python ↔ Node ↔ browser; T4 `source_chain_hash` binds receipts to source byte ranges; T5 `ShareableRender` round-trips signed renders for offline verification; T6 multi-school extract runs two extractors in tandem for adversarial-divergence detection. Wire spec at [`docs/TRANSFORM_RECEIPT_FORMAT.md`](docs/TRANSFORM_RECEIPT_FORMAT.md); design at [`docs/TRANSFORM_REGISTRY.md`](docs/TRANSFORM_REGISTRY.md). |
 | Replay-defense window (`signed_at_out_of_window`) | shipped | opt-in `max_age_seconds` parameter across all four verifier surfaces (Python render / Python transform / JS render / JS transform). Default-off preserves archival use; receivers opt in per use-case (agent-swarm 60s, real-time 600s, newsletter 1d, legal-discovery no window). |
 | `sum verify --explain` layered output | shipped | Per-dimension report (`sum.verify_explained.v1`): cryptographic integrity / canonical reconstruction / axiom consistency / extraction provenance / source evidence coverage / semantic preservation / truth of content. Each carries `epistemic_status` (`provable` / `certified` / `empirical-benchmark` / `not-asserted`). Truth of content is ALWAYS `not_asserted` — locked by test. |
 | Negative-control corpus (T5 of bench-hardening) | shipped | 20 hand-authored documents across 5 failure modes (ambiguous coref / predicate-alias / contradictions / entity-resolution-adversarial / non-extractable). Runner exits 1 if observed failures don't match annotations. Baseline at [`fixtures/bench_receipts/negative_control_2026-05-17.json`](fixtures/bench_receipts/negative_control_2026-05-17.json). |
 | Compliance validators (six regimes) | shipped | `sum compliance check --regime <id> --audit-log <path>` — EU AI Act Article 12, GDPR Article 30, HIPAA § 164.312(b), ISO/IEC 27001 A.8.15, SOC 2 CC 7.2, PCI DSS v4.0 Req 10. All six produce the same `sum.compliance_report.v1` schema; per-regime docs at `docs/COMPLIANCE_*.md`. |
 
-The slider's product claim — *axis changes do not lose facts* — is the load-bearing empirical result. It is verified by NLI audit on every embedding-flagged "loss" cell; full attribution in [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md).
+The slider's product claim — *axis changes do not lose facts* — is the load-bearing empirical result. It is verified by NLI audit on every embedding-flagged "loss" cell; full attribution in [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md). In keeping with the "what remains unproven" half of the promise above: these headline numbers are **measured observations**, not yet same-commit-replayable — the bench harness (`Tests/benchmarks/slider_drift_bench.py`) is scaffold-state and no `sum.slider_drift_bench.v1` receipt is committed. Closing that to a replayable receipt is bench-hardening tasks T2 / T3 ([`docs/BENCH_HARDENING_FROM_QCVV.md`](docs/BENCH_HARDENING_FROM_QCVV.md)); see the reproducibility-status note in [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md).
 
 ## Strategic context
 
@@ -251,7 +252,7 @@ Below the slider sits the substrate that earlier phases shipped and verified. Po
 - **Bundle public-key attestation (provable).** Ed25519-signed CanonicalBundles are tamper-detectable by any third party in any of the three runtimes. [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.3.1.
 - **Merkle hash-chain integrity (provable, including under concurrent writers).** [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.7.
 - **Extraction F1 (empirical-benchmark).** 1.000 on `seed_v1` (50 simple-SVO docs); 0.762 with precision 1.000 on `seed_v2` (20-doc difficulty corpus). Every remaining `seed_v2` failure is a recall miss, not a truth inversion. [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §2.1.
-- **168 numbered features**, each with a reproducible verification command, in [`docs/FEATURE_CATALOG.md`](docs/FEATURE_CATALOG.md).
+- **170 numbered features**, each with a reproducible verification command, in [`docs/FEATURE_CATALOG.md`](docs/FEATURE_CATALOG.md).
 
 ### Research substrate (under `sum_engine_internal/research/`)
 
@@ -275,6 +276,10 @@ Less-surfaced but shipped:
 - **Audit log format** — every CLI operation can emit `sum.audit_log.v1` events; see [`docs/AUDIT_LOG_FORMAT.md`](docs/AUDIT_LOG_FORMAT.md).
 - **Agent surface** (`sum_engine_internal/agent_surface/`) — see [`docs/AGENT_SURFACE_FINDINGS.md`](docs/AGENT_SURFACE_FINDINGS.md).
 
+### Internal research surfaces (NOT shipped, present in repo)
+
+- **`api/quantum_router.py` + `quantum_main.py`** — FastAPI surface with 26+ endpoints (branchable knowledge graph, ZK semantic proofs, federated KG sync, JWT-tenant knowledge OS). 1,684 LOC; 58/58 tests pass; runs locally via `uvicorn quantum_main:app`. **NOT in the PyPI wheel** (`pyproject.toml` excludes `api*`), **NOT in the live Worker**, **NOT in the dogfood quickstart**. The substrate it composes is load-bearing for the shipping surfaces above; only the FastAPI HTTP layer is internal-research. Promote to a shipping `[api]` extra only if a named buyer or grant deliverable explicitly references one of the endpoint clusters. See top-of-file banner in `api/quantum_router.py` for the full triage rationale.
+
 ---
 
 ## Reproduce the bench

{sum_engine-0.7.0 → sum_engine-0.7.1}/README.md

@@ -22,7 +22,7 @@ Headline supporting numbers (each links to its source of truth):
 | Three-runtime byte-symmetric Ed25519 over JCS bytes | provable; locked by `make xruntime` (K1–K4) + `make xruntime-adversarial` (A1–A6) | [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.2, §1.3.1 |
 | Canonical round-trip `reconstruct(parse(canonical_tome(S))) == S` | provable; 0.00% drift on every CI run | [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.1 |
 | Render receipt — `sum.render_receipt.v1`, Ed25519 / JCS / detached JWS | shipped; verifier in three runtimes | [`docs/RENDER_RECEIPT_FORMAT.md`](docs/RENDER_RECEIPT_FORMAT.md) |
-| Slider fact preservation: median 1.000, p10 0.769 (long n=16) / 0.818 (short n=8) | empirical-benchmark | [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md) |
+| Slider fact preservation: median 1.000, p10 0.769 (long n=16) / 0.818 (short n=8) | empirical-benchmark — measured; same-commit replay receipt still pending (bench-hardening T2/T3) | [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md) |
 | Extraction F1 = 1.000 (`seed_v1`), 0.762 with precision 1.000 (`seed_v2`) | empirical-benchmark | [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §2.1 |
 
 A render receipt verifies the *render attestation* (issuer signed this tome, these triples, this slider position, this model, at this time). It does not verify the truth of the tome's content — that is what the slider bench measures separately. See [`docs/RENDER_RECEIPT_FORMAT.md`](docs/RENDER_RECEIPT_FORMAT.md) §5 for the explicit trust scope.
@@ -60,13 +60,13 @@ A minimal Node verifier using `jose` + `canonicalize` is in [`docs/RENDER_RECEIP
 | Cross-runtime trust triangle | locked by CI (`make xruntime`) | K1 / K1-mw / K2 / K3 / K4 — Python ↔ Node ↔ Browser agree byte-for-byte on valid bundles. `make xruntime-adversarial` adds A1–A6 rejection-class equivalence. |
 | 5-axis slider rendering surface | density actioned deterministically; length / formality / audience / perspective LLM-conditioned. Two dispatch paths: Worker `/api/render` (Anthropic + Cloudflare AI Gateway optional) producing `sum.render_receipt.v1`, OR Python `sum transform apply slider` (OpenAI via `OPENAI_API_KEY`) producing `sum.transform_receipt.v1` | bench: median LLM-axis fact preservation 1.000, p10 0.769 (long, n=16) / 0.818 (short, n=8), order preservation 1.000 wherever measurable. Tightening worktrail at [`docs/BENCH_HARDENING_FROM_QCVV.md`](docs/BENCH_HARDENING_FROM_QCVV.md) adds iteration-stability + DKW worst-case bounds + capability-region headlines |
 | MCP server (`sum-mcp` console script) | shipped | five tools (`extract` / `attest` / `verify` / `inspect` / `schema`) exposed over stdio; bundles attested via MCP verify byte-identically through the CLI / Node / browser verifiers |
-| Transform substrate (`sum.transform_receipt.v1` + registry) | shipped (CLI in repo HEAD; PyPI catch-up tag pending) | `sum transform list` / `sum transform apply <name>` — three registered transforms (`slider` / `extract` / `compose`); receipts via Ed25519 / JCS / detached JWS just like render-receipts; 20-fixture cross-runtime K-matrix locks accept + reject across Python ↔ Node ↔ browser; T4 `source_chain_hash` binds receipts to source byte ranges; T5 `ShareableRender` round-trips signed renders for offline verification; T6 multi-school extract runs two extractors in tandem for adversarial-divergence detection. Wire spec at [`docs/TRANSFORM_RECEIPT_FORMAT.md`](docs/TRANSFORM_RECEIPT_FORMAT.md); design at [`docs/TRANSFORM_REGISTRY.md`](docs/TRANSFORM_REGISTRY.md). |
+| Transform substrate (`sum.transform_receipt.v1` + registry) | shipped on PyPI ≥ 0.7.0 | `sum transform list` / `sum transform apply <name>` — three registered transforms (`slider` / `extract` / `compose`); receipts via Ed25519 / JCS / detached JWS just like render-receipts; 20-fixture cross-runtime K-matrix locks accept + reject across Python ↔ Node ↔ browser; T4 `source_chain_hash` binds receipts to source byte ranges; T5 `ShareableRender` round-trips signed renders for offline verification; T6 multi-school extract runs two extractors in tandem for adversarial-divergence detection. Wire spec at [`docs/TRANSFORM_RECEIPT_FORMAT.md`](docs/TRANSFORM_RECEIPT_FORMAT.md); design at [`docs/TRANSFORM_REGISTRY.md`](docs/TRANSFORM_REGISTRY.md). |
 | Replay-defense window (`signed_at_out_of_window`) | shipped | opt-in `max_age_seconds` parameter across all four verifier surfaces (Python render / Python transform / JS render / JS transform). Default-off preserves archival use; receivers opt in per use-case (agent-swarm 60s, real-time 600s, newsletter 1d, legal-discovery no window). |
 | `sum verify --explain` layered output | shipped | Per-dimension report (`sum.verify_explained.v1`): cryptographic integrity / canonical reconstruction / axiom consistency / extraction provenance / source evidence coverage / semantic preservation / truth of content. Each carries `epistemic_status` (`provable` / `certified` / `empirical-benchmark` / `not-asserted`). Truth of content is ALWAYS `not_asserted` — locked by test. |
 | Negative-control corpus (T5 of bench-hardening) | shipped | 20 hand-authored documents across 5 failure modes (ambiguous coref / predicate-alias / contradictions / entity-resolution-adversarial / non-extractable). Runner exits 1 if observed failures don't match annotations. Baseline at [`fixtures/bench_receipts/negative_control_2026-05-17.json`](fixtures/bench_receipts/negative_control_2026-05-17.json). |
 | Compliance validators (six regimes) | shipped | `sum compliance check --regime <id> --audit-log <path>` — EU AI Act Article 12, GDPR Article 30, HIPAA § 164.312(b), ISO/IEC 27001 A.8.15, SOC 2 CC 7.2, PCI DSS v4.0 Req 10. All six produce the same `sum.compliance_report.v1` schema; per-regime docs at `docs/COMPLIANCE_*.md`. |
 
-The slider's product claim — *axis changes do not lose facts* — is the load-bearing empirical result. It is verified by NLI audit on every embedding-flagged "loss" cell; full attribution in [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md).
+The slider's product claim — *axis changes do not lose facts* — is the load-bearing empirical result. It is verified by NLI audit on every embedding-flagged "loss" cell; full attribution in [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md). In keeping with the "what remains unproven" half of the promise above: these headline numbers are **measured observations**, not yet same-commit-replayable — the bench harness (`Tests/benchmarks/slider_drift_bench.py`) is scaffold-state and no `sum.slider_drift_bench.v1` receipt is committed. Closing that to a replayable receipt is bench-hardening tasks T2 / T3 ([`docs/BENCH_HARDENING_FROM_QCVV.md`](docs/BENCH_HARDENING_FROM_QCVV.md)); see the reproducibility-status note in [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md).
 
 ## Strategic context
 
@@ -188,7 +188,7 @@ Below the slider sits the substrate that earlier phases shipped and verified. Po
 - **Bundle public-key attestation (provable).** Ed25519-signed CanonicalBundles are tamper-detectable by any third party in any of the three runtimes. [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.3.1.
 - **Merkle hash-chain integrity (provable, including under concurrent writers).** [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.7.
 - **Extraction F1 (empirical-benchmark).** 1.000 on `seed_v1` (50 simple-SVO docs); 0.762 with precision 1.000 on `seed_v2` (20-doc difficulty corpus). Every remaining `seed_v2` failure is a recall miss, not a truth inversion. [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §2.1.
-- **168 numbered features**, each with a reproducible verification command, in [`docs/FEATURE_CATALOG.md`](docs/FEATURE_CATALOG.md).
+- **170 numbered features**, each with a reproducible verification command, in [`docs/FEATURE_CATALOG.md`](docs/FEATURE_CATALOG.md).
 
 ### Research substrate (under `sum_engine_internal/research/`)
 
@@ -212,6 +212,10 @@ Less-surfaced but shipped:
 - **Audit log format** — every CLI operation can emit `sum.audit_log.v1` events; see [`docs/AUDIT_LOG_FORMAT.md`](docs/AUDIT_LOG_FORMAT.md).
 - **Agent surface** (`sum_engine_internal/agent_surface/`) — see [`docs/AGENT_SURFACE_FINDINGS.md`](docs/AGENT_SURFACE_FINDINGS.md).
 
+### Internal research surfaces (NOT shipped, present in repo)
+
+- **`api/quantum_router.py` + `quantum_main.py`** — FastAPI surface with 26+ endpoints (branchable knowledge graph, ZK semantic proofs, federated KG sync, JWT-tenant knowledge OS). 1,684 LOC; 58/58 tests pass; runs locally via `uvicorn quantum_main:app`. **NOT in the PyPI wheel** (`pyproject.toml` excludes `api*`), **NOT in the live Worker**, **NOT in the dogfood quickstart**. The substrate it composes is load-bearing for the shipping surfaces above; only the FastAPI HTTP layer is internal-research. Promote to a shipping `[api]` extra only if a named buyer or grant deliverable explicitly references one of the endpoint clusters. See top-of-file banner in `api/quantum_router.py` for the full triage rationale.
+
 ---
 
 ## Reproduce the bench

{sum_engine-0.7.0 → sum_engine-0.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sum-engine"
-version = "0.7.0"
+version = "0.7.1"
 description = "SUM — bidirectional knowledge distillation with optional cryptographic attestation. Pipe prose, get a CanonicalBundle (HMAC / Ed25519 / W3C VC 2.0), verify anywhere."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -42,7 +42,26 @@ dependencies = [
 #   pip install sum-engine[openai]  # OpenAI structured-output path
 #   pip install sum-engine[llm]     # alias for [openai] (legacy name)
 #   pip install sum-engine[all]     # everything, plus dev tooling
-sieve = ["spacy>=3.7.0"]
+sieve = [
+  # Floor bumped 3.7.0 → 3.8.0 on 2026-05-29 (F14). At spacy 3.7.0
+  # the auto-downloaded en_core_web_sm now resolves to a 3.8-series
+  # model the older runtime cannot load, and the fallback download
+  # builds a malformed URL (`download/-en_core_web_sm/-…`) because
+  # spacy.io's compatibility table no longer serves 3.7-compatible
+  # entries. Bumping the floor to the empirically-operable version
+  # keeps the declared floor honest. CI: new `pip install sum-engine
+  # (floor venv smoke)` job pins to floor and runs the full smoke,
+  # so the next time the floor decays we catch it before users do.
+  # See `docs/DOGFOOD_FINDINGS_2026-05-29.md` F14.
+  "spacy>=3.8.0",
+  # spacy ≥ 3.8 imports `from click import NoSuchOption` at module
+  # load (spacy/cli/_util.py); typer ≥ 0.13 stopped pulling click
+  # transitively. Pin click explicitly so a fresh
+  # `pip install sum-engine[sieve]` does not ImportError on first
+  # spacy import. CI: `pip install sum-engine (fresh venv smoke)`
+  # caught this 2026-05-28. See F13.
+  "click>=8.0",
+]
 # `[openai]` is the canonical, vendor-named extra; `[llm]` is kept as a
 # back-compat alias because it predates the multi-provider dispatcher
 # (Anthropic and OpenAI now have their own named extras). Both install
@@ -62,7 +81,11 @@ anthropic = ["anthropic>=0.97.0", "pydantic>=2.0.0"]
 # detached-JWS / RFC 7797 b64=false machinery; the existing pure-Python
 # JCS module at sum_engine_internal/infrastructure/jcs.py handles
 # canonicalization. Cryptography is already a hard dep above.
-receipt-verify = ["joserfc>=1.0.0"]
+# Upper bound: joserfc>=1.x warns that the "EdDSA" JWS alg is deprecated
+# (RFC 9864 favours explicit Ed25519/Ed448 alg identifiers). The whole
+# render-receipt trust loop signs with "EdDSA", so we pin below 2.0.0
+# until we confirm a major release does not drop the "EdDSA" alias.
+receipt-verify = ["joserfc>=1.0.0,<2.0.0"]
 # MCP (Model Context Protocol) server. Exposes SUM verbs as MCP
 # tools so any MCP-aware LLM client (Claude Desktop, Claude Code,
 # Cursor, Continue, custom agents) can call SUM directly. The

{sum_engine-0.7.0 → sum_engine-0.7.1}/sum_cli/main.py

@@ -379,6 +379,20 @@ def cmd_attest(args: argparse.Namespace) -> int:
         title=args.title,
     )
 
+    # Surface the extracted axioms on the bundle so downstream transforms
+    # (`sum transform apply compose`, slider input shape) can consume the
+    # attest output directly without re-parsing canonical_tome. The data
+    # exists internally as ``triples``; before this it was dropped at
+    # serialization. Additive — the signature covers
+    # ``canonical_tome|state_integer|timestamp``, not the bundle JSON, so
+    # writing a new top-level key does not invalidate any existing
+    # signature. Format mirrors what compose._bundle_triples expects:
+    # list of {subject, predicate, object} dicts.
+    bundle["axioms"] = [
+        {"subject": s, "predicate": p, "object": o}
+        for (s, p, o) in triples
+    ]
+
     # Optional: attach a lightweight sidecar naming the extractor + source
     # URI so downstream consumers can trace provenance without the full
     # AkashicLedger. This is additive — the CanonicalBundle schema

{sum_engine-0.7.0 → sum_engine-0.7.1/sum_engine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sum-engine
-Version: 0.7.0
+Version: 0.7.1
 Summary: SUM — bidirectional knowledge distillation with optional cryptographic attestation. Pipe prose, get a CanonicalBundle (HMAC / Ed25519 / W3C VC 2.0), verify anywhere.
 Author: ototao
 License: Apache-2.0
@@ -24,7 +24,8 @@ License-File: LICENSE
 Requires-Dist: cryptography>=41.0.0
 Requires-Dist: sympy>=1.12
 Provides-Extra: sieve
-Requires-Dist: spacy>=3.7.0; extra == "sieve"
+Requires-Dist: spacy>=3.8.0; extra == "sieve"
+Requires-Dist: click>=8.0; extra == "sieve"
 Provides-Extra: openai
 Requires-Dist: openai<3.0.0,>=1.40.0; extra == "openai"
 Requires-Dist: pydantic>=2.0.0; extra == "openai"
@@ -34,7 +35,7 @@ Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.97.0; extra == "anthropic"
 Requires-Dist: pydantic>=2.0.0; extra == "anthropic"
 Provides-Extra: receipt-verify
-Requires-Dist: joserfc>=1.0.0; extra == "receipt-verify"
+Requires-Dist: joserfc<2.0.0,>=1.0.0; extra == "receipt-verify"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == "mcp"
 Provides-Extra: research
@@ -85,7 +86,7 @@ Headline supporting numbers (each links to its source of truth):
 | Three-runtime byte-symmetric Ed25519 over JCS bytes | provable; locked by `make xruntime` (K1–K4) + `make xruntime-adversarial` (A1–A6) | [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.2, §1.3.1 |
 | Canonical round-trip `reconstruct(parse(canonical_tome(S))) == S` | provable; 0.00% drift on every CI run | [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.1 |
 | Render receipt — `sum.render_receipt.v1`, Ed25519 / JCS / detached JWS | shipped; verifier in three runtimes | [`docs/RENDER_RECEIPT_FORMAT.md`](docs/RENDER_RECEIPT_FORMAT.md) |
-| Slider fact preservation: median 1.000, p10 0.769 (long n=16) / 0.818 (short n=8) | empirical-benchmark | [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md) |
+| Slider fact preservation: median 1.000, p10 0.769 (long n=16) / 0.818 (short n=8) | empirical-benchmark — measured; same-commit replay receipt still pending (bench-hardening T2/T3) | [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md) |
 | Extraction F1 = 1.000 (`seed_v1`), 0.762 with precision 1.000 (`seed_v2`) | empirical-benchmark | [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §2.1 |
 
 A render receipt verifies the *render attestation* (issuer signed this tome, these triples, this slider position, this model, at this time). It does not verify the truth of the tome's content — that is what the slider bench measures separately. See [`docs/RENDER_RECEIPT_FORMAT.md`](docs/RENDER_RECEIPT_FORMAT.md) §5 for the explicit trust scope.
@@ -123,13 +124,13 @@ A minimal Node verifier using `jose` + `canonicalize` is in [`docs/RENDER_RECEIP
 | Cross-runtime trust triangle | locked by CI (`make xruntime`) | K1 / K1-mw / K2 / K3 / K4 — Python ↔ Node ↔ Browser agree byte-for-byte on valid bundles. `make xruntime-adversarial` adds A1–A6 rejection-class equivalence. |
 | 5-axis slider rendering surface | density actioned deterministically; length / formality / audience / perspective LLM-conditioned. Two dispatch paths: Worker `/api/render` (Anthropic + Cloudflare AI Gateway optional) producing `sum.render_receipt.v1`, OR Python `sum transform apply slider` (OpenAI via `OPENAI_API_KEY`) producing `sum.transform_receipt.v1` | bench: median LLM-axis fact preservation 1.000, p10 0.769 (long, n=16) / 0.818 (short, n=8), order preservation 1.000 wherever measurable. Tightening worktrail at [`docs/BENCH_HARDENING_FROM_QCVV.md`](docs/BENCH_HARDENING_FROM_QCVV.md) adds iteration-stability + DKW worst-case bounds + capability-region headlines |
 | MCP server (`sum-mcp` console script) | shipped | five tools (`extract` / `attest` / `verify` / `inspect` / `schema`) exposed over stdio; bundles attested via MCP verify byte-identically through the CLI / Node / browser verifiers |
-| Transform substrate (`sum.transform_receipt.v1` + registry) | shipped (CLI in repo HEAD; PyPI catch-up tag pending) | `sum transform list` / `sum transform apply <name>` — three registered transforms (`slider` / `extract` / `compose`); receipts via Ed25519 / JCS / detached JWS just like render-receipts; 20-fixture cross-runtime K-matrix locks accept + reject across Python ↔ Node ↔ browser; T4 `source_chain_hash` binds receipts to source byte ranges; T5 `ShareableRender` round-trips signed renders for offline verification; T6 multi-school extract runs two extractors in tandem for adversarial-divergence detection. Wire spec at [`docs/TRANSFORM_RECEIPT_FORMAT.md`](docs/TRANSFORM_RECEIPT_FORMAT.md); design at [`docs/TRANSFORM_REGISTRY.md`](docs/TRANSFORM_REGISTRY.md). |
+| Transform substrate (`sum.transform_receipt.v1` + registry) | shipped on PyPI ≥ 0.7.0 | `sum transform list` / `sum transform apply <name>` — three registered transforms (`slider` / `extract` / `compose`); receipts via Ed25519 / JCS / detached JWS just like render-receipts; 20-fixture cross-runtime K-matrix locks accept + reject across Python ↔ Node ↔ browser; T4 `source_chain_hash` binds receipts to source byte ranges; T5 `ShareableRender` round-trips signed renders for offline verification; T6 multi-school extract runs two extractors in tandem for adversarial-divergence detection. Wire spec at [`docs/TRANSFORM_RECEIPT_FORMAT.md`](docs/TRANSFORM_RECEIPT_FORMAT.md); design at [`docs/TRANSFORM_REGISTRY.md`](docs/TRANSFORM_REGISTRY.md). |
 | Replay-defense window (`signed_at_out_of_window`) | shipped | opt-in `max_age_seconds` parameter across all four verifier surfaces (Python render / Python transform / JS render / JS transform). Default-off preserves archival use; receivers opt in per use-case (agent-swarm 60s, real-time 600s, newsletter 1d, legal-discovery no window). |
 | `sum verify --explain` layered output | shipped | Per-dimension report (`sum.verify_explained.v1`): cryptographic integrity / canonical reconstruction / axiom consistency / extraction provenance / source evidence coverage / semantic preservation / truth of content. Each carries `epistemic_status` (`provable` / `certified` / `empirical-benchmark` / `not-asserted`). Truth of content is ALWAYS `not_asserted` — locked by test. |
 | Negative-control corpus (T5 of bench-hardening) | shipped | 20 hand-authored documents across 5 failure modes (ambiguous coref / predicate-alias / contradictions / entity-resolution-adversarial / non-extractable). Runner exits 1 if observed failures don't match annotations. Baseline at [`fixtures/bench_receipts/negative_control_2026-05-17.json`](fixtures/bench_receipts/negative_control_2026-05-17.json). |
 | Compliance validators (six regimes) | shipped | `sum compliance check --regime <id> --audit-log <path>` — EU AI Act Article 12, GDPR Article 30, HIPAA § 164.312(b), ISO/IEC 27001 A.8.15, SOC 2 CC 7.2, PCI DSS v4.0 Req 10. All six produce the same `sum.compliance_report.v1` schema; per-regime docs at `docs/COMPLIANCE_*.md`. |
 
-The slider's product claim — *axis changes do not lose facts* — is the load-bearing empirical result. It is verified by NLI audit on every embedding-flagged "loss" cell; full attribution in [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md).
+The slider's product claim — *axis changes do not lose facts* — is the load-bearing empirical result. It is verified by NLI audit on every embedding-flagged "loss" cell; full attribution in [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md). In keeping with the "what remains unproven" half of the promise above: these headline numbers are **measured observations**, not yet same-commit-replayable — the bench harness (`Tests/benchmarks/slider_drift_bench.py`) is scaffold-state and no `sum.slider_drift_bench.v1` receipt is committed. Closing that to a replayable receipt is bench-hardening tasks T2 / T3 ([`docs/BENCH_HARDENING_FROM_QCVV.md`](docs/BENCH_HARDENING_FROM_QCVV.md)); see the reproducibility-status note in [`docs/SLIDER_CONTRACT.md`](docs/SLIDER_CONTRACT.md).
 
 ## Strategic context
 
@@ -251,7 +252,7 @@ Below the slider sits the substrate that earlier phases shipped and verified. Po
 - **Bundle public-key attestation (provable).** Ed25519-signed CanonicalBundles are tamper-detectable by any third party in any of the three runtimes. [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.3.1.
 - **Merkle hash-chain integrity (provable, including under concurrent writers).** [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §1.7.
 - **Extraction F1 (empirical-benchmark).** 1.000 on `seed_v1` (50 simple-SVO docs); 0.762 with precision 1.000 on `seed_v2` (20-doc difficulty corpus). Every remaining `seed_v2` failure is a recall miss, not a truth inversion. [`docs/PROOF_BOUNDARY.md`](docs/PROOF_BOUNDARY.md) §2.1.
-- **168 numbered features**, each with a reproducible verification command, in [`docs/FEATURE_CATALOG.md`](docs/FEATURE_CATALOG.md).
+- **170 numbered features**, each with a reproducible verification command, in [`docs/FEATURE_CATALOG.md`](docs/FEATURE_CATALOG.md).
 
 ### Research substrate (under `sum_engine_internal/research/`)
 
@@ -275,6 +276,10 @@ Less-surfaced but shipped:
 - **Audit log format** — every CLI operation can emit `sum.audit_log.v1` events; see [`docs/AUDIT_LOG_FORMAT.md`](docs/AUDIT_LOG_FORMAT.md).
 - **Agent surface** (`sum_engine_internal/agent_surface/`) — see [`docs/AGENT_SURFACE_FINDINGS.md`](docs/AGENT_SURFACE_FINDINGS.md).
 
+### Internal research surfaces (NOT shipped, present in repo)
+
+- **`api/quantum_router.py` + `quantum_main.py`** — FastAPI surface with 26+ endpoints (branchable knowledge graph, ZK semantic proofs, federated KG sync, JWT-tenant knowledge OS). 1,684 LOC; 58/58 tests pass; runs locally via `uvicorn quantum_main:app`. **NOT in the PyPI wheel** (`pyproject.toml` excludes `api*`), **NOT in the live Worker**, **NOT in the dogfood quickstart**. The substrate it composes is load-bearing for the shipping surfaces above; only the FastAPI HTTP layer is internal-research. Promote to a shipping `[api]` extra only if a named buyer or grant deliverable explicitly references one of the endpoint clusters. See top-of-file banner in `api/quantum_router.py` for the full triage rationale.
+
 ---
 
 ## Reproduce the bench

{sum_engine-0.7.0 → sum_engine-0.7.1}/sum_engine.egg-info/SOURCES.txt

@@ -97,6 +97,7 @@ sum_engine_internal/research/bootstrap/__init__.py
 sum_engine_internal/research/bootstrap/multiplier_bootstrap.py
 sum_engine_internal/research/conformal/__init__.py
 sum_engine_internal/research/conformal/entropy_baseline.py
+sum_engine_internal/research/conformal/risk_control.py
 sum_engine_internal/research/conformal/split_conformal.py
 sum_engine_internal/research/lsh/__init__.py
 sum_engine_internal/research/lsh/bundle_index.py

{sum_engine-0.7.0 → sum_engine-0.7.1}/sum_engine.egg-info/requires.txt

@@ -38,11 +38,12 @@ openai<3.0.0,>=1.40.0
 pydantic>=2.0.0
 
 [receipt-verify]
-joserfc>=1.0.0
+joserfc<2.0.0,>=1.0.0
 
 [research]
 numpy>=1.24.0
 scipy>=1.10.0
 
 [sieve]
-spacy>=3.7.0
+spacy>=3.8.0
+click>=8.0

{sum_engine-0.7.0 → sum_engine-0.7.1}/sum_engine_internal/infrastructure/akashic_ledger.py

@@ -31,9 +31,11 @@ License: Apache License 2.0
 import math
 import hashlib
 import json
+import random
 import sqlite3
 import asyncio
 import logging
+import time
 from contextlib import contextmanager
 from typing import Any, Dict, Iterator, List, Optional, Sequence, Tuple
 
@@ -86,11 +88,22 @@ class AkashicLedger:
 
     # SQLite busy_timeout (ms) applied to every connection. Lets
     # writers wait for the lock instead of failing immediately —
-    # eliminates "database is locked" under concurrent-writer
-    # contention without changing logic. 5 s is comfortably above
-    # the worst-case test scenario (1000 concurrent inserts).
+    # the first line of defence against "database is locked" under
+    # concurrent-writer contention.
     _BUSY_TIMEOUT_MS = 5000
 
+    # Second line of defence: busy_timeout is NOT starvation-free. Under
+    # sustained many-writer contention (and on a loaded CI runner), an
+    # unlucky writer can be repeatedly passed over and still see
+    # SQLITE_BUSY after the timeout. A bounded retry-with-jittered-backoff
+    # around BEGIN IMMEDIATE turns that probabilistic failure into an
+    # eventual success. Retrying BEGIN IMMEDIATE is safe — it acquires the
+    # write lock before any SQL runs, so a failed attempt leaves no
+    # partial state. Worst case ~ attempts × busy_timeout, but in practice
+    # the lock is grabbed on the first or second try.
+    _BEGIN_RETRY_ATTEMPTS = 6
+    _BEGIN_RETRY_BASE_SLEEP_S = 0.05
+
     def __init__(self, db_path: str = "akashic.db"):
         self.db_path = db_path
         self._init_db()
@@ -208,9 +221,32 @@ class AkashicLedger:
         Tests/test_ledger_concurrency.py exercises this discipline.
         """
         with self._connect() as conn:
-            conn.execute("BEGIN IMMEDIATE")
+            self._begin_immediate(conn)
             yield conn
 
+    def _begin_immediate(self, conn: sqlite3.Connection) -> None:
+        """Acquire the reserved write-lock, retrying on transient
+        "database is locked" with jittered exponential backoff.
+
+        See ``_BEGIN_RETRY_ATTEMPTS`` for why busy_timeout alone is not
+        sufficient under heavy contention. Only SQLITE_BUSY/locked is
+        retried; any other OperationalError propagates immediately.
+        """
+        last_exc: sqlite3.OperationalError | None = None
+        for attempt in range(self._BEGIN_RETRY_ATTEMPTS):
+            try:
+                conn.execute("BEGIN IMMEDIATE")
+                return
+            except sqlite3.OperationalError as exc:
+                if "locked" not in str(exc).lower():
+                    raise
+                last_exc = exc
+                if attempt < self._BEGIN_RETRY_ATTEMPTS - 1:
+                    backoff = self._BEGIN_RETRY_BASE_SLEEP_S * (2 ** attempt)
+                    time.sleep(backoff + random.uniform(0.0, 0.02))
+        assert last_exc is not None  # loop ran at least once
+        raise last_exc
+
     def _migrate_structured_provenance(self, conn: sqlite3.Connection) -> None:
         """M1: Structured ProvenanceRecord side-table + axiom linking.
 

{sum_engine-0.7.0 → sum_engine-0.7.1}/sum_engine_internal/research/conformal/__init__.py

@@ -33,6 +33,13 @@ from sum_engine_internal.research.conformal.entropy_baseline import (
     BaselineEntropyPredictor,
     get_default_predictor,
 )
+from sum_engine_internal.research.conformal.risk_control import (
+    RateGuarantee,
+    certify_rate,
+    clopper_pearson_lower_bound,
+    empirical_bound_coverage,
+    hoeffding_lower_bound,
+)
 
 __all__ = [
     "SplitConformal",
@@ -41,4 +48,9 @@ __all__ = [
     "average_interval_width",
     "BaselineEntropyPredictor",
     "get_default_predictor",
+    "RateGuarantee",
+    "certify_rate",
+    "clopper_pearson_lower_bound",
+    "hoeffding_lower_bound",
+    "empirical_bound_coverage",
 ]

sum_engine-0.7.1/sum_engine_internal/research/conformal/risk_control.py

@@ -0,0 +1,207 @@
+"""Distribution-free lower confidence bounds on a preservation rate.
+
+The split-conformal kernel (`split_conformal.py`) wraps a point
+predictor in a calibrated *interval*. This module answers the
+complementary, one-sided question that SUM's slider contract actually
+asks:
+
+    "With confidence ≥ 1 - δ, what is the largest X such that the
+     fact-preservation rate ≥ X?"
+
+That is a one-sided lower confidence bound on the mean of bounded
+[0, 1] observations (per-cell preservation fractions) or on a binomial
+proportion (per-fact preserved / lost). It is the certifier shape the
+bench-hardening plan's T3 names — "fact preservation ≥ X with 95 %
+confidence over the tested envelope" — expressed as a finite-sample,
+distribution-free guarantee rather than a tail percentile of an
+empirical distribution.
+
+Two bounds ship, both finite-sample and distribution-free:
+
+  - **Hoeffding** — for any observations in [0, 1]. From Hoeffding's
+    inequality P(μ̂ - μ ≥ t) ≤ exp(-2 n t²), the (1-δ) one-sided lower
+    bound is μ̂ - sqrt(ln(1/δ) / (2n)). Always valid; conservative.   [provable]
+
+  - **Clopper–Pearson** — exact one-sided lower limit for a binomial
+    proportion (per-fact preserved/lost), the β-quantile
+    Beta(δ; k, n-k+1). Tighter than Hoeffding for the binary view and
+    the most interpretable framing ("≥ X % of facts preserved").      [provable]
+
+Relationship to DKW (the other T3 tool): DKW bounds the *entire* drift
+CDF uniformly, which is the right tool for a quantile statement over a
+distribution. For a single *rate* (a mean / proportion), the bounds
+here are the tighter, purpose-built instrument. Use DKW for the
+full-distribution worst-case envelope and these for the headline rate;
+they are complementary, not redundant.
+
+Honest boundary: like all conformal-family guarantees, validity rests
+on **exchangeability** between the calibration sample and deployment —
+i.e. the bound holds *within the tested envelope* (the T2 capability
+region), degrading on out-of-distribution inputs. State the envelope
+alongside the bound; never quote the rate without it.
+
+Author: ototao
+License: Apache License 2.0
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Literal, Sequence
+
+import numpy as np
+
+
+@dataclass(frozen=True, slots=True)
+class RateGuarantee:
+    """A finite-sample, distribution-free lower bound on a rate.
+
+    Reads as: "with confidence ≥ ``confidence``, the true rate is
+    ≥ ``rate_lower_bound``", valid under exchangeability of the
+    sample with deployment (i.e. within the tested envelope).
+    """
+    rate_lower_bound: float   # the certified floor X
+    point_estimate: float     # observed mean / proportion
+    n: int                    # sample size
+    delta: float              # miscoverage allowance (confidence = 1 - delta)
+    method: str               # "hoeffding" | "clopper_pearson"
+
+    @property
+    def confidence(self) -> float:
+        return 1.0 - self.delta
+
+    @property
+    def slack(self) -> float:
+        """Gap between the point estimate and the certified floor —
+        the price of finite-sample, distribution-free rigour."""
+        return self.point_estimate - self.rate_lower_bound
+
+
+def _validate_delta(delta: float) -> None:
+    if not (0.0 < delta < 1.0):
+        raise ValueError(f"delta must be in (0, 1); got {delta}")
+
+
+def hoeffding_lower_bound(values: Sequence[float], delta: float = 0.05) -> float:
+    """One-sided (1-δ) lower confidence bound on the mean of [0, 1]
+    observations, via Hoeffding's inequality. Distribution-free,
+    finite-sample. Clamped to [0, 1]."""
+    _validate_delta(delta)
+    arr = np.asarray(values, dtype=np.float64)
+    if arr.ndim != 1:
+        raise ValueError(f"values must be 1-D; got shape {arr.shape}")
+    n = arr.size
+    if n < 1:
+        raise ValueError("values must be non-empty")
+    # Reject non-finite FIRST: NaN slips past the [0,1] range check below
+    # (every NaN comparison is False), and a NaN/inf observation would
+    # otherwise poison the mean into a silently-invalid bound — observed
+    # to yield LCB=1.0 (a maximal "guarantee" from garbage input).
+    if not np.all(np.isfinite(arr)):
+        raise ValueError("values must all be finite (no NaN/inf)")
+    if np.any(arr < 0.0) or np.any(arr > 1.0):
+        raise ValueError("Hoeffding bound requires all values in [0, 1]")
+    mean = float(arr.mean())
+    radius = math.sqrt(math.log(1.0 / delta) / (2.0 * n))
+    return max(0.0, min(1.0, mean - radius))
+
+
+def clopper_pearson_lower_bound(successes: int, n: int, delta: float = 0.05) -> float:
+    """Exact one-sided (1-δ) lower confidence limit for a binomial
+    proportion (``successes`` of ``n`` Bernoulli trials).
+
+    The limit is the δ-quantile of Beta(successes, n - successes + 1),
+    with the standard convention that the bound is 0 when there are no
+    successes. Tighter than Hoeffding for binary data and exact (never
+    under-covers)."""
+    _validate_delta(delta)
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    if not (0 <= successes <= n):
+        raise ValueError(f"successes must be in [0, n]; got {successes} of {n}")
+    if successes == 0:
+        return 0.0
+    # Lazy import: keeps the module usable (Hoeffding path) without scipy.
+    from scipy.stats import beta  # type: ignore
+    return float(beta.ppf(delta, successes, n - successes + 1))
+
+
+def certify_rate(
+    observations: Sequence[float],
+    delta: float = 0.05,
+    method: Literal["auto", "hoeffding", "clopper_pearson"] = "auto",
+) -> RateGuarantee:
+    """Certify a distribution-free lower bound on the preservation rate.
+
+    ``method="auto"`` picks Clopper–Pearson when every observation is
+    exactly 0 or 1 (the per-fact preserved/lost view — exact and
+    tightest) and Hoeffding otherwise (the per-cell [0, 1] fraction
+    view — always valid).
+    """
+    arr = np.asarray(observations, dtype=np.float64)
+    if arr.ndim != 1:
+        raise ValueError(f"observations must be 1-D; got shape {arr.shape}")
+    n = arr.size
+    if n < 1:
+        raise ValueError("observations must be non-empty")
+    # Non-finite rejection before range check (NaN evades < / > and would
+    # poison the bound — see risk_control hardening note in hoeffding).
+    if not np.all(np.isfinite(arr)):
+        raise ValueError("observations must all be finite (no NaN/inf)")
+    if np.any(arr < 0.0) or np.any(arr > 1.0):
+        raise ValueError("observations must lie in [0, 1]")
+
+    is_binary = bool(np.all(np.isin(arr, (0.0, 1.0))))
+    chosen = method
+    if method == "auto":
+        chosen = "clopper_pearson" if is_binary else "hoeffding"
+
+    if chosen == "clopper_pearson":
+        if not is_binary:
+            raise ValueError(
+                "clopper_pearson requires binary (0/1) observations; "
+                "use 'hoeffding' for fractional [0, 1] values"
+            )
+        successes = int(round(float(arr.sum())))
+        lb = clopper_pearson_lower_bound(successes, n, delta)
+    elif chosen == "hoeffding":
+        lb = hoeffding_lower_bound(arr, delta)
+    else:
+        raise ValueError(f"unknown method {method!r}")
+
+    return RateGuarantee(
+        rate_lower_bound=lb,
+        point_estimate=float(arr.mean()),
+        n=n,
+        delta=float(delta),
+        method=chosen,
+    )
+
+
+# -- Diagnostics --------------------------------------------------------
+
+
+def empirical_bound_coverage(
+    true_rate: float,
+    n: int,
+    delta: float,
+    method: Literal["hoeffding", "clopper_pearson"],
+    n_trials: int = 2000,
+    seed: int = 0,
+) -> float:
+    """Fraction of trials in which the certified lower bound does not
+    exceed ``true_rate``. A valid (1-δ) bound must achieve coverage
+    ≥ 1-δ. This is the empirical check of the provable guarantee."""
+    if not (0.0 <= true_rate <= 1.0):
+        raise ValueError("true_rate must be in [0, 1]")
+    rng = np.random.RandomState(seed)
+    covered = 0
+    for _ in range(n_trials):
+        draws = (rng.uniform(size=n) < true_rate).astype(np.float64)
+        if method == "clopper_pearson":
+            lb = clopper_pearson_lower_bound(int(draws.sum()), n, delta)
+        else:
+            lb = hoeffding_lower_bound(draws, delta)
+        if lb <= true_rate:
+            covered += 1
+    return covered / n_trials