SUM — chain of custody for AI-transformed text

What it is, plainly. SUM is a knowledge distiller: drop in a text and a slider renders it anywhere from a single tag to a full tome — and it hands back a signed, offline-checkable receipt of how much of the original meaning survived. So you can vouch for AI-transformed text to a skeptic without asking them to trust you. The distiller is the long-term aim; the signed receipt is the rung that makes lossy distillation trustworthy enough to build on.

SUM lets people and agents transform knowledge without losing the ability to verify what changed, what stayed the same, who signed it, and what remains unproven.

See what an AI transform silently dropped. sum meaning-diff reads out, per document, which source claims survived a rewrite and which vanished. Here it is on a shipped fixture — a four-clause lease notice rewritten as verse:

$ sum meaning-diff examples/poetry_frontier/source.txt examples/poetry_frontier/sonnet.txt --scorer nli
Meaning readout — measured for THIS document (not a certified bound)
  judge: nli:MoritzLaurer/DeBERTa-v3-base-mnli-fever-anli v1
  preservation: 55%   (loss 0.450)
  source claims: 4 — 1 preserved, 3 DROPPED:
     ✗ Late payment after the fifth day incurs a 50 dollar fee.
     ✗ The landlord must give 24 hours notice before entering the unit.
     ✗ Either party may terminate this lease with 30 days written notice.
  added / unsupported claims: none ✓

  → 3 dropped — review before relying on this rendering.
  (measured for THIS document under the named judge — a per-document MEASUREMENT, not a certified bound or a guarantee; for a (1-δ) bound use a meaning_risk receipt over a named corpus.)

To run that exact command: pip install 'sum-engine[research,judge]' (meaning-diff needs [research]; the --scorer nli judge needs [judge]) from a git checkout — examples/ ships in the repo, not in the wheel. The zero-clone path is the receipt replay in Verify it yourself in 60 seconds below.

Every transformation — extract triples from prose, render a tome at a controlled slider position, compose bundles across documents, share a render — emits a cryptographically-signed receipt that any third party can verify offline. The receipt attests that the transformation happened and what its inputs were. Separate per-axis benchmarks attest how much the transformation preserved meaning. Both are kept honest by separate proof discipline — and the project never blurs the line between them.

Live trust loop: https://sum-demo.ototao.workers.dev — three runtimes (Python, Node, modern browsers) produce byte-identical Ed25519 signatures over the same JCS-canonical bytes; verify offline against /.well-known/jwks.json. Mechanically proven; locked in CI on every PR.

Built for: journalists working under deepfake-era citation requirements, academic survey writers who need provenance back to source PDFs, agentic-AI builders who need their agents to pass verifiable evidence and not just messages, and regulated-domain content (EU AI Act Article 12, FTC AI disclosure, HIPAA, SOC 2, PCI DSS) where "we say it's true" isn't enough.

The cryptographic side is mechanically proven — three independent verifier implementations agreeing byte-for-byte on every signed bundle, locked in CI on every PR. The semantic side (extraction quality, slider fact preservation) is empirically measured with explicit per-corpus numbers and explicit per-corpus boundaries. docs/PROOF_BOUNDARY.md is the arbiter.

Headline supporting numbers (each links to its source of truth):

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 §5 for the explicit trust scope.

More of what people read is now produced or reshaped by AI — summarised, translated, distilled, rewritten. As that grows, the ability to check what changed, what was preserved, and what was lost stops being a nicety and becomes shared infrastructure for a trustworthy information commons.

SUM is built to be that layer in the open: Apache-2.0, offline-verifiable by anyone, and aligned with open standards (C2PA digital_source_type, W3C VC 2.0, JOSE / JWS / JWKS) rather than a proprietary trust silo. It does not ask you to trust SUM — any third party verifies the receipt themselves, in three independent runtimes, and the project states plainly where proof ends and measurement begins. The aim is a checkable chain of custody for knowledge in motion, not another walled garden.

The differentiator — replay a meaning-loss bound, fully offline. SUM's flagship receipt is a signed, replayable certificate over a named meaning-loss proxy. The verifier is dependency-light — sum_verify imports only cryptography and joserfc, with no numpy / scipy / torch, no GPU, and no network — and a real binding-gate golden over public-domain text (BillSum, CC0) ships inside the wheel, so this works straight from pip, no clone:

pip install 'sum-engine[verify]'        # no numpy/scipy/torch; see note below
python -m sum_verify --demo             # replays the bundled BillSum golden, offline
# → {"verified": true, "schema": "sum.meaning_risk_receipt.v1", "replayed": true,
#    "scorer": "bidirectional-entailment[minilm-cosine-0.5]",
#    "not_covered": ["arrangement","sound","connotation","implicature"],
#    "proxy_caveat": "verified=true is a cryptographic fact ... the proxy
#       correlated only modestly at summary level (Spearman rho 0.267-0.291 on
#       SummEval; NLI ~0.29 replicates on FRANK; the embedding judge is
#       corpus-dependent, near zero on abstractive FRANK-XSum). Not a
#       substitute for human review."}

What [verify] actually installs. cryptography, joserfc, and sympy (a base dependency of the package, used by the state-integer path — not imported by sum_verify). The load-bearing promise is the one above: no numpy, scipy, torch, GPU, or network on the verification path.

To verify your own receipt — or the source goldens from a git checkout — pass the files explicitly:

python -m sum_verify <receipt.json> --jwks <jwks.json> --losses <losses.json>
# from a checkout, the binding-gate goldens live in fixtures/meaning_receipts_billsum/

verified: true + replayed: true means the committed per-pair losses hash to the receipt's anchor and re-certify to its stated bound (≤ 0.6454 at 95%) by exact integer equality — on your machine, against the issuer's JWKS, trusting nobody. Read the proxy_caveat: that PASS is a cryptographic fact, not proof meaning was preserved — the bound is over a proxy that tracks human judgment only modestly. The richer readout (the bound itself, perspective cohorts) is sum verify-meaning (which needs the heavier pip install "sum-engine[research,receipt-verify]" — the no-numpy promise above is scoped to python -m sum_verify); for non-extractive rewrites use --scorer nli — examples/poetry_frontier/ shows exactly where the embedding judge's blind spot is.

Verifying someone else's receipt is half the loop. To issue one over your own corpus:

pip install 'sum-engine[research,receipt-verify,judge]'
sum mint-meaning --pairs pairs.jsonl --scorer nli \
    --corpus-id my-corpus --transform my-transform \
    --out out/receipt.json --gen-key out/
# self-verifies through the verify path before handing you the file,
# and prints the exact `sum verify-meaning …` line a third party runs

pairs.jsonl is your own data, one {"source": "…", "rendering": "…"} per line. Aim for n ≥ ~32: the bound is distribution-free and valid at any n, but at n = 1 it degenerates to ≤ 1.0 and certifies nothing, and the CLI says so. (--source FILE --rendering FILE mints from a single pair, which is exactly that vacuous case.) --gen-key writes a fresh keypair plus JWKS; the private half is mode 0600 and never leaves your machine.

docs/THIRD_PARTY_VERIFY.md walks the full mint-then-verify round trip, and examples/issue_meaning_receipt.py is the scripted version. Read the vacuity and exchangeability warnings it prints — a bound over a corpus your text does not resemble is not evidence about your text.

The render trust loop (signed provenance). The other receipt family attests that a transformation happened (issuer, inputs, slider position, model, time) — the same JWS verifiable byte-for-byte in three independent runtimes:

# JWKS — single Ed25519 OKP JWK, application/jwk-set+json
curl -sS https://sum-demo.ototao.workers.dev/.well-known/jwks.json | jq .

# Render — tome + render_receipt (signed JWS over JCS payload)
curl -sS -X POST https://sum-demo.ototao.workers.dev/api/render \
  -H 'content-type: application/json' \
  -d '{"triples":[["alice","graduated","2012"],["alice","born","1990"]],
       "slider_position":{"density":1.0,"length":0.5,"formality":0.7,"audience":0.5,"perspective":0.5}}' \
  | jq '.render_receipt | {schema, kid, payload, jws_segments: (.jws | split(".") | length)}'

A render receipt attests the render, not the truth of its content (trust scope in docs/RENDER_RECEIPT_FORMAT.md §5); a minimal Node verifier using jose + canonicalize is in §A.5, and the same format is reachable from Python (joserfc + jcs), Go, and Rust per §3.

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. 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); see the reproducibility-status note in docs/SLIDER_CONTRACT.md.

The operational compass — read in this order if you want the project's intent + how it operates + where it's going:

• docs/CHARTER_2026-05-17.md — intent, the Why, strategy, objectives, success criteria, constraints, and the operational loop. The compass every other doc resolves to.
• docs/PRODUCT_VISION.md — the product vision (the slider workbench: drop text → render it from a tag to a tome, with a signed receipt of what was preserved) and the positioning: SUM is the chain-of-custody standard for AI-transformed text — provenance-first, attest-don't-detect (a cryptographic guarantee robust to rewriting; an "is this AI?" answer ships only as an honest advisory signal, never a "99 %").
• docs/PRODUCT_DELIBERATION_2026-05-14.md — three-option strategic analysis + grant-outcome decision tree.
• docs/ZENITH_FRAMING_2026-05-16.md — destination framing (SUM as chain-of-custody for AI-transformed knowledge) plus three new concepts (Perspective Receipts, Trust Profiles, Epistemic Nutrition Label) on the design queue.
• docs/BENCH_HARDENING_FROM_QCVV.md — five-task empirical-benchmark hardening plan (T5 shipped 2026-05-17; T1 closed 2026-05-21; T4 closed 2026-05-22; T2 + T3 still open, gated on sum.slider_drift_bench.v1 receipts).
• docs/DOGFOOD_QUICKSTART.md — five-minute guide to running SUM on your own writing.

The hardest measurement in PROOF_BOUNDARY.md is the full LLM narrative round-trip (text → LLM-extract → axioms → LLM-generate → prose' → LLM-extract → axioms'). The unprompted-pipeline baseline on seed_v1 was drift = 107.75% / exact-match recall = 0.12 — facts preserved, keys not.

A two-layer generator-side intervention (canonical-first generator prompt + constrained-decoding extractor with vocab-pinned Literal enums + lemma-exclusion of source-predicate lemmas from the canonical-padding set) now closes this across every measured corpus shape:

The combined intervention lands ≥ 0.97 recall and ≤ 5 % drift on every measured corpus shape — single-fact short-form, multi-fact difficulty-pattern, and multi-paragraph dense-prose. The §2.5 closure is corpus-independent. The remaining gap on each corpus traces to upstream LLM source-extraction artifacts (corrupted axioms on seed_v2 doc_015, semantically-duplicate predicates on seed_long solar_system), not to the intervention pattern.

Receipt artifacts:

• fixtures/bench_receipts/s25_generator_side_2026-04-28.json — full ablation matrix on seed_v1.
• fixtures/bench_receipts/s25_residual_closure_2026-04-28.json — combined + lemma-exclusion on seed_v1.
• fixtures/bench_receipts/s25_generator_side_seed_v2_2026-04-28.json — all three ablations on seed_v2.
• fixtures/bench_receipts/s25_generator_side_seed_long_combined_2026-04-28.json — combined ablation on seed_long_paragraphs.

Reproducible: python -m scripts.bench.runners.s25_generator_side --ablation combined --corpus <path> --out <path> (~$0.07–$0.20 OpenAI per corpus, ~3–8 min wall clock). Full attribution + per-ablation breakdowns + per-doc failure analysis in docs/PROOF_BOUNDARY.md §2.5.

The deterministic canonical round-trip (the one sum attest | sum verify exercises) is mechanically proven (§1.1, 0.00% drift). The LLM round-trip is not, and this section is here to keep that distinction above the fold.

pip install 'sum-engine[sieve]'

echo "Alice likes cats. Bob owns a dog." \
  | sum attest --extractor=sieve > bundle.json

sum verify --input bundle.json
# → sum: ✓ verified 2 axiom(s), state integer matches (hmac=absent, ed25519=absent, extractor=sieve (verifiable))

sum render < bundle.json > tome.md
# → bundle's axioms re-emitted as canonical prose; round-trips to the same state integer

The reverse direction also runs under explicit slider control. The local path actions only the density slider; non-neutral length / formality / audience / perspective require the LLM extrapolator and route through the hosted Worker:

sum render --density 0.5 < bundle.json
# → keeps the lex-prefix half of the axioms; @sliders header records what was requested

sum render --length 0.9 --use-worker https://sum-demo.ototao.workers.dev --json < bundle.json
# → LLM-conditioned tome + signed render_receipt (sum.render_receipt.v1) on stdout

Add cryptographic attestation with one flag:

# Ed25519 / W3C VC 2.0 (eddsa-jcs-2022)
python -m scripts.generate_did_web --domain your.example --private-key-out keys/issuer.pem
sum attest --ed25519-key keys/issuer.pem < prose.txt | sum verify --strict
# → hmac=absent, ed25519=verified, extractor=sieve (verifiable)

The same bundle bytes verify under sum verify (Python), node standalone_verifier/verify.js (WebCrypto), and the in-browser demo (SubtleCrypto). docs/DID_SETUP.md walks the did:key / did:web issuer setup. docs/PROOF_BOUNDARY.md §1.3.1 documents what the cross-runtime Ed25519 contract proves.

pip install 'sum-engine[mcp,sieve]'
# Claude Desktop / Claude Code / Cursor / Continue: add to MCP config:
#   { "mcpServers": { "sum": { "command": "sum-mcp" } } }

sum-mcp exposes the bundle verbs (extract, attest, verify, inspect, render, schema) plus the meaning layer (verify_receipt, meaning_diff, depth_frontier, mint_meaning_receipt, mint_chain_receipt — BYO private key only; the server never generates or stores keys) as MCP tools. Bundles attested via MCP verify byte-identically through the CLI / Node / browser verifiers — same canonical codec — and receipt verdicts carry the same honesty fields (proxy_caveat, budget_scope) the CLI prints. See docs/MCP_INTEGRATION.md for the full client wiring and the measured concurrency story.

The hosted Worker at https://sum-demo.ototao.workers.dev exposes /api/render, /api/transform, /api/complete, /api/qid, and the /.well-known/{jwks,revoked-kids}.json verification surfaces. docs/API_REFERENCE.md is the wire spec — request/response shapes, error codes, the six-step receipt-verification flow, working Node + Python examples. Use this when the caller is a web app, mobile app, or server-side service; use the MCP server when the caller is a local LLM client.

prose ─► /api/render ─►  tome
                         + render_receipt {kid, payload, jws}
                                              │
                                              ▼
                                  /.well-known/jwks.json
                                  (Ed25519 OKP JWK by kid)
                                              │
                                              ▼
                              jose.flattenedVerify(JCS(payload))
                                              │
                                              ▼
                          render attested ✓ — issuer signed
                          (this tome, these triples, this slider
                          position, this model, at this time)

The receipt is a render attestation, not a truth oracle. Fact preservation is verified by the bench (NLI audit on weak cells). The receipt is what a downstream system keeps as durable proof; the tome is what a reader consumes. See docs/RENDER_RECEIPT_FORMAT.md §5.

Below the slider sits the substrate that earlier phases shipped and verified. Pointers, not paraphrase — every claim links to its source-of-truth doc.

• Canonical round-trip conservation (provable). reconstruct(parse(canonical_tome(S))) == S for every Gödel state S. 0.00% drift on seed_tiny_v1 / seed_v1 / seed_v2. docs/PROOF_BOUNDARY.md §1.1.
• Cross-runtime state equivalence (provable). Python (sympy), Node (BigInt + Miller-Rabin), in-browser JS produce byte-identical state integers. Locked by 4 harnesses (make xruntime + make xruntime-adversarial). docs/PROOF_BOUNDARY.md §1.2.
• 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 §1.3.1.
• Merkle hash-chain integrity (provable, including under concurrent writers). 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 §2.1.
• 170 numbered features, each with a reproducible verification command, in docs/FEATURE_CATALOG.md.

Less-surfaced but shipped:

• MinHash-LSH bundle similarity index (research/lsh/) — near-duplicate bundle detection at scale.
• Robust PCA corruption score (research/robust_pca/) — corruption_score field in bundle metadata; flags adversarially-perturbed bundles.
• Sequential & conformal-prediction (research/sequential/, research/conformal/) — bench-side confidence bounds with documented coverage guarantees.
• MMD distribution distance (research/mmd/) — axiom_distribution_mmd field on bundles; surfaces when an attested bundle is structurally unlike its baseline corpus.
• Spectral entropy (research/spectral_entropy/) — axiom-graph entropy on every bundle, with confidence interval.
• Bootstrap multiplier spike detection (research/bootstrap/) — see docs/MULTIPLIER_BOOTSTRAP_SPIKE_FINDINGS.md.
• SMT consistency checking (research/smt_consistency/) — z3-backed axiom_consistency_check on every bundle.
• Sheaf-Laplacian hallucination detection — see docs/SHEAF_HALLUCINATION_DETECTOR.md (research direction).

• Trust-root manifest (sum_engine_internal/trust_root/) — operator-issued signed manifest binding kid lifecycle, revocation policy, and verifier expectations.
• Merkle sidecar format (sum_engine_internal/merkle_sidecar/) — see docs/MERKLE_SIDECAR_FORMAT.md.
• Evidence-chain layer (sum_engine_internal/evidence/) — substrate behind source_chain_hash (T4).
• Algorithm registry — see docs/ALGORITHM_REGISTRY.md (the in-tree list of permitted signing algs; crypto-agility gate).
• Audit log format — every CLI operation can emit sum.audit_log.v1 events; see docs/AUDIT_LOG_FORMAT.md.
• Agent surface (sum_engine_internal/agent_surface/) — see docs/AGENT_SURFACE_FINDINGS.md.

• api/quantum_router.py + quantum_main.py — FastAPI surface with 26+ endpoints (branchable knowledge graph, ZK semantic proofs, federated KG sync, JWT multi-tenant API). 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.

# Short corpus (n=8, 4–12 triples/doc, ~$0.30, ~2 min with NLI)
bash scripts/bench/run_paragraphs.sh

# Long corpus (n=16, 9–24 triples/doc, ~$1.50, ~10 min with NLI)
bash scripts/bench/run_long_paragraphs.sh

Both runners require OPENAI_API_KEY (NLI audit + extraction). Pinned model snapshots are mandatory; the harness raises SystemExit on unpinned identifiers (see docs/PROOF_BOUNDARY.md §2.6). Output is NDJSON sum.slider_drift_bench.v1, with per-cell strict / normalized / semantic / NLI fact-preservation columns.

This roadmap names only unshipped work. Items already landed live in CHANGELOG.md [Unreleased]. Detailed sequencing lives in docs/NEXT_SESSION_PLAYBOOK.md.

Generalising the LLM round-trip result beyond the measured corpora. The round-trip gap itself is closed — see the section above and docs/PROOF_BOUNDARY.md §2.5 (closed 2026-05-21 across all measured corpora; the unprompted baseline was 107.75 % drift / 0.12 recall on seed_v1, now 0.00 % / 1.00 there). What is not shipped is evidence that the intervention (canonical-first generator prompt + constrained-decoding extractor + lemma-exclusion) holds on corpora nobody has measured yet, and a same-commit replay receipt for it. Treat the closure as an empirical result with a stated envelope, not a universal guarantee.

Hardening backlog

• sha256_128_v2 default-activation — Python ↔ Node byte-identity now locked (12-key K1-v2 + 6-state K2-v2 gate runs on every PR; scripts/verify_godel_v2_cross_runtime.py). The default scheme stays sha256_64_v1; flipping the default is a separate operator decision that requires a bundle_version minor bump per docs/COMPATIBILITY_POLICY.md. The migration path is now empirically open.
• /api/qid accuracy floor — measured 2026-04-28 on a 30-term hand-curated corpus across people, places, concepts, and common nouns: hit-rate 100% (30/30), label-substring-match 100% (24/24, excluding 6 common-noun rows). Receipt at fixtures/bench_receipts/qid_accuracy_2026-04-28.json under schema sum.qid_resolution_accuracy.v1. Boundary: label-substring match accepted relativity → Q201607 (Relativity Records) — a music-label entity, not the physics theory. The two-tier metric is robust to wbsearchentities's quirks but does not measure semantic-accuracy against canonical Q-IDs; that's a follow-on with hand-verified ground-truth pairs. The current resolver is a thin layer over wbsearchentities; SPARQL-driven disambiguation that prefers the most-linked-to entity for ambiguous terms remains an unshipped enhancement.
• Threat-model validation — every documented defence in docs/THREAT_MODEL.md gets an executable test.
• Delta-bundle composition semantics — specifies what bundle.is_delta means cross-runtime.
• Sigstore / cosign signing of release artifacts.
• LLM-extraction honesty guardrails — extraction.verifiable: true | false so signed ≠ true is visible at the consumer interface.
• Calibration-set authoring for the Venn-Abers conformal-interval implementation that already ships.
• Remaining sieve recall work on seed_v2 (apposition / relative-clause / compound-conjunct) — gated on the §2.5 work, see docs/PROOF_BOUNDARY.md §6.

Platform surface (post-hardening)

Source anchoring in the bundle schema, bundle explorer / viewer, sum tutorial onboarding, shareable bundle URLs /b/{hash}, PWA-installable demo, sum attest <url> fetch mode. Each item names its dependency in docs/NEXT_SESSION_PLAYBOOK.md.

make help lists every dev command. Common targets:

make install              # editable install with sieve + dev extras
make test                 # full pytest run (2000+ tests)
make xruntime             # cross-runtime K1/K1-mw/K2/K3/K4 (Python ↔ Node)
make xruntime-adversarial # rejection-matrix A1–A6
make fortress             # 21-check pure-math invariants
make smoke                # fresh-venv install + attest|verify round-trip
make demo                 # open the single-file browser demo

CI runs the full suite on every push (.github/workflows/quantum-ci.yml); the cross-runtime-harness job runs K1–K4 + A1–A6 on Node 22; pypi-install-smoke builds the wheel and runs echo prose | sum attest | sum verify in a throwaway venv.

Every claim in this repo carries an explicit epistemic status — provable, certified, empirical-benchmark, or expert-opinion. The arbiter is docs/PROOF_BOUNDARY.md. A summary surface that quotes an empirical-benchmark number alongside language like "mathematically guaranteed" is a policy violation per §5 and must be corrected.

Performance language (fast, efficient, low-latency, scalable) requires a benchmark in the same commit. Adversarial input agreement (the A-matrix) is a separate proof from valid-input agreement (the K-matrix); both run in CI.

If a number in this README disagrees with docs/PROOF_BOUNDARY.md or docs/SLIDER_CONTRACT.md, the docs are canonical and this README is wrong.

1. Fork and branch.
2. make install && make test && make xruntime.
3. Read docs/NEXT_SESSION_PLAYBOOK.md for principles, stop-the-line triggers, and the work-ordering rule.
4. Open a PR. Every claim added to docs or commit messages must trace to a test, a measurement, or an explicit designed, not proved label.

CONTRIBUTING.md has the test-gate matrix and the verification-gate runbook.

Apache 2.0. See LICENSE.