K R Y   —   Proof-of-Efficiency Compute Credit
  earn by avoiding inference cost · a stranger verifies the ledger · stdlib only

━━━━━━ FULL LIFECYCLE  —  earn → mint → attest → STRANGER-verifies → carbon ━━━━━━
The whole loop, on sample efficiency events, in one program:

──────────────────────────────────────────────────────────────────────
1. EARN — efficiency events become KRY (edge-weighted by what they avoided)
──────────────────────────────────────────────────────────────────────
  balance:            2,436.00 KRY
  lifetime earned:    2,436.00 KRY
  frontier basis: $25.0/M output tokens   (40,000 KRY / USD)

──────────────────────────────────────────────────────────────────────
2. RETAIN — the honest value TODAY (money kept, no counterparty needed)
──────────────────────────────────────────────────────────────────────
  retained_usd:                 $0.0609
  value_type:                   retained_dollars (money kept) — NOT a tradeable token
  external_counterparty_exists: False  (honest label)

──────────────────────────────────────────────────────────────────────
3. MINT — every earn is a SHA-256 hash-chain receipt (tamper-evident)
──────────────────────────────────────────────────────────────────────
  receipts:    3
  chain_tip:   2bcb408aefd147b6...
  chain_valid: True
  veracity_floor: 0.3924  (fraction anchored by more than self-report — external OR operator-run)

──────────────────────────────────────────────────────────────────────
4. ATTEST — a public, content-sealed proof of the balance
──────────────────────────────────────────────────────────────────────
  wrote 3 links, total 2,436.00 KRY -> <tmpdir>/attestation.json
  (contains only hashes + aggregates — no prompts, responses, or model
   names beyond the event type; safe to hand to a third party)

──────────────────────────────────────────────────────────────────────
5. VERIFY — a STRANGER checks it with stdlib only (the differentiator)
──────────────────────────────────────────────────────────────────────
KRY external verification — attestation
  receipts:        3 (recomputed from links)
  total_kry:       2436.0 (recomputed from links, not the declared field)
  veracity_floor:  0.3924 (fraction anchored by more than self-report — external OR operator-run; witnesses the event, NOT the magnitude)
                   ↳ anchored tiers are chain-bound LABELS — run kry_tee_verify /
                     kry_tlsn_verify to independently check the underlying evidence doc
  price basis:     $25.0/M frontier, as of 2026-09-15 (magnitude recomputed from the public price table)
  anchor check:    NONE — ⚠ the anchored fraction is OPERATOR-ASSERTED
                   here: a genesis re-mint with upgraded tiers passes this check.
                   Re-run with --anchor <operator's pre-published chain head> to make
                   a retroactive re-mint detectable.
  VERDICT: VALID — integrity + conservation + magnitude (where checkable) hold; trust surface honest (read veracity_floor for what is operator-asserted).

──────────────────────────────────────────────────────────────────────
6. CARBON — second denomination: avoided inference -> CO2 (ESTIMATE)
──────────────────────────────────────────────────────────────────────
  kry_avoided:        2,436.00
  energy_kwh_avoided: 0.001353 kWh
  co2_grams_avoided:  0.5413 g
  status:             ESTIMATE — not a certified carbon credit (grid region unknowable: inference_geo redacted)

══════════════════════════════════════════════════════════════════════
Done. The balance was minted from sample efficiency events, anchored in a
tamper-evident chain, and verified by a program that trusts nothing in
this package. That is what 'proof-of-efficiency' means in practice.
(temp data dir <tmpdir> — safe to delete)
══════════════════════════════════════════════════════════════════════

━━━━━━ OPERATOR VIEW  —  a sample routing log → a verifiable savings statement ━━━━━━
SAVED vs SPEND + veracity_floor; --mint anchors it, --attest emits the public proof.
  
    minted savings into the chain; attestation -> <tmp>/att.json
  KRY savings report
    records analysed:     48  {'cache_hit': 10, 'holdout': 35, 'displacement': 1, 'paid_call': 2, 'free_call': 0}
    SAVED (retained):         3,080.50 KRY   = $0.0770
    SPEND (real):            17,017.60 KRY   = $0.4254
    efficiency_ratio:     15.33%  (saved / (saved+spend))
    veracity_floor:       70.78%  (holdout-validated + provider-metered share of savings)
      self_reported:            900.00 KRY
      holdout_validated:      1,798.10 KRY
      provider_metered:         382.40 KRY
    holdout measurement:  1 class(es) measured; cost 15,000.00 KRY ($0.3750) — the price of veracity
    prompt cache:         provider prompt-cache discount, computed from reported usage at list price; not minted, not attested, self-reported (list prices as of 2026-09-16)
      records:            priced 0, unpriced 38, modifier-excluded 0, malformed 0; 1-hour write price assumed for 0
    by request-class:
      code                                 treated=0     holdout=0    p̂=—                saved=    382.40 KRY [provider_metered]
      greet                                treated=2     holdout=0    p̂=—                saved=      0.00 KRY [self_reported]
      summarize                            treated=5     holdout=35   p̂=86% (CI≥71%)     saved=  1,798.10 KRY [holdout_validated]
      translate                            treated=3     holdout=0    p̂=—                saved=    900.00 KRY [self_reported]

━━━━━━ STRANGER CHECK  —  verify that statement with stdlib only (imports nothing from KRY) ━━━━━━
  KRY external verification — attestation
    receipts:        11 (recomputed from links)
    total_kry:       3080.4984 (recomputed from links, not the declared field)
    veracity_floor:  0.7078 (fraction anchored by more than self-report — external OR operator-run; witnesses the event, NOT the magnitude)
                     ↳ anchored tiers are chain-bound LABELS — run kry_tee_verify /
                       kry_tlsn_verify to independently check the underlying evidence doc
    price basis:     $25.0/M frontier, as of 2026-09-15 (magnitude recomputed from the public price table)
    anchor check:    NONE — ⚠ the anchored fraction is OPERATOR-ASSERTED
                     here: a genesis re-mint with upgraded tiers passes this check.
                     Re-run with --anchor <operator's pre-published chain head> to make
                     a retroactive re-mint detectable.
    VERDICT: VALID — integrity + conservation + magnitude (where checkable) hold; trust surface honest (read veracity_floor for what is operator-asserted).
  ↑ confirmed by code that does NOT trust the producer — the whole point.

━━━━━━ T2  —  the same trust model, anchored to a REAL provider's TLS response ━━━━━━
TLSNotary proves what openrouter.ai returned, verifiable by a stranger with real CA roots.
Mechanism proven (2026-06-04) — NOT yet trustless: self-hosted notary != neutral party (§5).
  docs/KRY_T2_FINDINGS_REPORT.md  ·  tlsnotary/

  earn → mint → attest → verify → (T1 reconcile / T2 notarize).  That is proof-of-efficiency.

KRY is earned by avoiding inference cost (a cache hit, a compression, a cheaper-model displacement) and spent on routing permission. The interesting part is not the ledger — it's that the whole system is built around a single uncomfortable question:

A hash chain can prove a balance is intact. It cannot prove the savings happened. So how much do you have to trust the operator — and can that number be made explicit, machine-checkable, and driven toward zero?

That question — integrity ≠ veracity — is the spine of this project. Everything below is organized so the answer is computed and labeled, never asserted.

Contents

• The idea in 60 seconds
• Quickstart
• How it works
• Veracity: the trust ladder
• Honest limitations
• Authenticity (optional): who signed this attestation
• Magnitude: publicly-checkable arithmetic
• Readiness: a computed grade, not a claim
• Modules
• Verifying as a stranger
• Repository layout
• Legal posture
• Documentation

The idea in 60 seconds

Every avoided inference call has a dollar value: the price you would have paid the frontier model, minus what the cheaper path actually cost. KRY mints that retained value into a tamper-evident, hash-chained ledger, and exposes a public proof surface so a third party can independently re-derive the numbers without seeing a single prompt.

What KRY refuses to do is pretend the proof is stronger than it is. A cache hit is a counterfactual — a call that never happened — and nothing outside your runtime can witness a call that was never made. KRY makes that limit a first-class, labeled property (veracity_floor) instead of hiding it behind a green checkmark.

Claims hierarchy. docs/CLAIMS_BOUNDARY.md is the authoritative scope for what KRY does and does not claim — it governs this README's prose, the demos, and every module docstring. Where any of those read stronger than the boundary, the boundary wins.

Quickstart

No runtime package dependencies, and pip install -e . needs no build-time downloads. Tests use pytest and lint uses ruff; step 0 installs both, pinned, through the dev extra, and step 4 uses them.

To see a receipt verified without cloning (optional, separate from the steps below): python3 -m pip install kry-attest, then run kry-try and kry-verify. Verify your first receipt walks through it in about five minutes. The steps below use a checkout.

# 0) Create a virtual environment (Python 3.11 or newer), then install this checkout with the test tools
python3 -m venv .venv && . .venv/bin/activate
python3 -m pip install -e ".[dev]" # the package itself has no runtime dependencies

# 1) Watch the whole thing run, narrated and paced (the GIF above, live)
bash examples/demo.sh

# 2) Or the core lifecycle directly (uses a throwaway temp data dir)
python3 examples/try_kry.py
# earn → retained_dollars → mint (hash chain) → attest → a STRANGER verifies → carbon estimate

# 3) Turn a routing log into a verifiable savings statement
# examples/sample_usage_log.jsonl is synthetic; use real logs for external validation.
tmp=$(mktemp -d "${TMPDIR:-/tmp}/kry-quickstart.XXXXXX")
export KRY_DATA_DIR="$tmp/kry_data"
python3 scripts/kry_doctor.py
# local health check for the verifier/reviewer surface; warns that external evidence is still required
# (WARN lines for the optional modules cryptography and oqs concern the TEE and post-quantum
#  tiers and appear only when those modules are not installed; safe to ignore here)
python3 scripts/kry_savings_report.py examples/sample_usage_log.jsonl
# reports SAVED vs SPEND and the veracity_floor (holdout-validated vs self-reported)
python3 scripts/kry_savings_report.py examples/sample_usage_log.jsonl --mint --attest "$tmp/att.json"
python3 scripts/kry_verify.py "$tmp/att.json" # the stranger's check — stdlib only
# ↑ WITHOUT --anchor, the anchored fraction is operator-asserted (a genesis re-mint
#   passes). The operator PUBLISHES this anchor out-of-band, then a stranger checks against it:
python3 scripts/kry_chain_anchor.py export > "$tmp/anchor.json"
python3 scripts/kry_verify.py "$tmp/att.json" --anchor "$tmp/anchor.json" # re-mint now detectable
# NOTE: writing anchor.json into $tmp publishes nothing. A stranger can rely on it only once it
#   sits somewhere you cannot quietly rewrite, placed there BEFORE the attestation is shared.
#   Skip that step and a full re-mint from an edited log still verifies VALID without --anchor.
python3 scripts/kry_verified_artifact.py examples/sample_usage_log.jsonl \
 --attestation "$tmp/att.json" --mint-log "$KRY_DATA_DIR/kry_mint_log.jsonl" --bundle-dir "$tmp/packet"
# ↑ exits 0. On the sample, its JSON shows "ok": false for evidence the sample cannot supply and FAIL
#   for the science and external_review gates; its closing note says that is expected for sample
#   data and is not a run error. The check that must pass is the next one ("ok": true).
python3 scripts/kry_verified_artifact.py --verify-artifact "$tmp/packet/artifact.json"
python3 scripts/kry_finops_report.py "$tmp/packet/artifact.json"
python3 scripts/kry_verified_artifact.py examples/sample_usage_log.jsonl \
 --attestation "$tmp/att.json" --template-dir "$tmp/evidence_templates"
# emits explicit product/science/review/kill gates; sample data stays internal_or_demo_only
# the bundled sample cannot satisfy --corpus real, even if copied elsewhere.
# template mode also writes hash-bound request briefs for provider/reviewer/buyer/legal evidence.
# bundle mode derives packet/t1_manifest.json and packet/finops_report.md; it does not copy the private mint log.
# after collecting real provider data, use --write-provider-export-manifest and
# --write-corpus-manifest to generate the live science-gate provenance files.

# 4) Run the release checks
python3 -m pytest tests/ -q # stdlib suite; optional crypto tests skip closed if unavailable
bash lab/reproduce.sh 10 # reproducibility proof loop
python3 scripts/kry_release_verify.py --full # one-command release gate
# ↑ the gate builds its own temporary virtualenvs, so its result does not depend on, or vouch for,
#   the environment you ran the steps above in

How it works

 EARN SPEND
 cache hit ┐ ┌ routing permission
 compression ┼──► value_multiplier(model) ──► KRY ──► (free tiers cost 0,
 displacement ┘ × EARN_RATES[event] ▲ paid tiers debit)
 │
 │ every mutation
 ▼
 ┌───────────────────────────────────────────────────────────────────────────┐
 │ MINT — SHA-256 hash-chained receipt │
 │ chain_hash[i] = SHA256(chain_hash[i-1] : receipt_hash[i] : public_block[i]) │
 │ public_block (v4+) binds tier (T0/T1/T2), T1 metered counts, amounts, ts │
 └───────────────────────────────────────────────────────────────────────────┘
 │
 ┌──────────────────────────────┼──────────────────────────────┐
 ▼ ▼ ▼
 ATTEST (public proof) SETTLE (federated transfer) RECONCILE (F1, auditor)
 content-sealed balance + the conservation + double-spend match T1 mints to the
 veracity_floor surface guard (+ HOLE F rollback guard) provider's own usage record
 │
 ▼
 VERIFY (any stranger, stdlib only)
 chain integrity + conservation + magnitude (F2) + veracity surface

The lifecycle is append-only and deterministic. Each chain_hash is SHA-256 over the colon-joined string prev_chain_hash:receipt_hash:public_block (SPEC §3.3). public_block is canonical JSON (json.dumps(sort_keys=True, separators=(",", ":"))) of the receipt's public fields, with the economic numbers and ts encoded as exact IEEE-754 hex from hash_version 5 on, so any party re-derives the same digest from the attestation alone. receipt_hash is itself a colon-joined string (numbers in Python's float formatting) that includes the sealed evidence hash, so a verifier treats it as opaque and never recomputes it. The attestation_hash is SHA-256 over the canonical JSON of the whole attestation (SPEC §3.1). Runtime ledgers live under KRY_DATA_DIR (default ./kry_data, gitignored) and are never committed — they're tied to real traffic.

Veracity: the trust ladder

The hash chain proves integrity (untampered + conserved). It says nothing about whether the efficiency events actually happened — that is veracity. Every mint is classified by how the event was witnessed, weakest to strongest:

• The tier is bound into the receipt hash (hash_version >= 2): editing one receipt's tier in place breaks the chain, and a legacy v1 receipt (which does not bind the tier) may only be self_reported — a v1 receipt claiming a higher tier is rejected. New T1 receipts also hash-bind their metered_tokens (hash_version = 3), so provider reconciliation cannot swap token counts under the same receipt hash. The current format (hash_version = 7) also binds each receipt's receipt_id (so a T2 tier-promotion's supersedes target cannot be relabeled onto a different, larger receipt to inflate the anchored fraction) and its event_type (so a link cannot be relabeled between two same-earn_rate event types).
• verify_chain proves integrity, not veracity. It cannot distinguish an honest chain from one an operator re-derived from genesis (keyless SHA-256 + a local checkpoint): a full re-mint with upgraded tiers and inflated value passes it clean. The external root of trust that closes this is the chain-head anchor — export a content-free {count, tip} commitment and publish it to an append-only medium (scripts/kry_chain_anchor.py); a verifier holding the published anchor then catches any retroactive re-mint (kry_verify.py --anchor). Absent a published anchor, a self-reported balance is operator-trusted by construction — which is exactly what veracity_floor discloses.
• An attestation exposes a veracity_floor = the fraction backed by something stronger than bare self-report — an external anchor (provider-metered / TEE / TLSNotary) or an operator-run randomized holdout (holdout_validated). verify_attestation() re-derives the floor from the per-link tiers (so it can't be misstated relative to the tiers shown) and only credits a tier the public surface actually binds (v4) — a pre-v4 link claiming any tier other than self_reported makes the attestation INVALID, and its value is counted as self_reported when the floor is re-derived (SPEC §3.4 step 4). That is tamper-evident against anyone who cannot recompute the chain; against the operator (who can), publish a chain anchor to be re-mint-evident.
• A balance with no external traffic reads veracity_floor = 0.0 (100% self-reported). That is the honest label for what KRY is by default: internal-operator measurement. It is published as-is, never hidden.

Why cache hits are structurally hard. A cache hit is a call that did not happen — zero provider-side footprint — so no external party can attest to it even in principle, short of a witness inside the runtime (a TEE; a TLS notary can only witness a call that reached the provider). Displacement is different: the cheap leg that did happen leaves a real provider record. This asymmetry is the honest core of the problem, and it is why "just meter it" does not rescue the bulk of a cache-dominated balance. Full design: docs/KRY_VERACITY_BINDING.md.

Honest limitations (disclosed, not hidden)

These are scope boundaries, disclosed rather than hidden. The first three are permanent, by design, and declared not_guaranteed in the capability matrix. The others are not permanent: cross-node settlement is scaffolded there, with a default-off fix; the locking limit is documented in src/kry/_locks.py rather than the matrix; and real-world validation is not_guaranteed today but closable with external evidence (docs/KRY_READINESS.md).

• Per-event counterfactual proof — a single cache hit cannot be externally witnessed; the holdout gives a statistical answer, never a per-event one.
• Source-truth of self-report — a determined operator can still author conserved T0 events for savings that didn't occur, and (controlling the runtime) re-derive the whole chain from genesis with upgraded tiers; verify_chain proves integrity, not veracity. The attestation says so (veracity_floor = 0.0), which is the contribution; publishing a kry_chain_anchor makes a retroactive re-mint detectable, but neither prevents it.
• Sybil-resistant identity — settlement assumes parties are who they claim; KRY does not solve identity.
• Cross-node settlement (HOLE D) — the double-spend guard is real-time atomic on a single HOST (multi-process: the ceiling is re-checked at commit under a cross-process lock), and a published export_registry_anchor() catches a rollback/un-spend. What is NOT real-time-safe by default is cross-NODE: two nodes settling the same balance against unmerged registries aren't caught until merge. The top-ranked fix, a shared lease/nonce/TTL authority, is implemented but off by default: set KRY_SETTLE_LEASE_DIR to storage every node reaches (tests/test_settlement_lease.py). Its O_EXCL lock is best-effort on some NFS servers, and periodic registry merge remains the long-term backstop.
• Cross-process locking assumes a local filesystem — the mint/settlement/action writers serialize via fcntl/msvcrt file locks, and flock over NFS (or an SMB/synced share) is unreliable: on a networked data dir the cross-process guarantee can silently degrade. Keep writers on one host with a local data dir; for multi-node, prefer per-node state + chain reconciliation over one shared mutable file (src/kry/_locks.py documents this; a platform with neither lock primitive warns once and falls back to in-process locks only).
• Real-world validation — apart from one small real reconciliation (n=52 free-tier :free, $0 self-traffic, token counts checked against the provider's records, which grounds that the calls existed, not that dollars were saved), every result here is on synthetic or internal data. "Tested on synthetic data" ≠ "validated on real traffic," and this README will not blur the two.

Authenticity (optional): who signed this attestation

Integrity proves the ledger is untampered; veracity proves the events happened. Neither proves who vouched for an attestation — to a stranger, a real ledger and a fabricated one are cryptographically indistinguishable, because the stdlib core has no public-key crypto. The optional kry_pqc/ tier fills exactly that gap: it signs an attestation's raw bytes with NIST ML-DSA (FIPS 204) so the holder of a published public key is provably the signer to a verifier who supplies that published key out-of-band (--public-key / --expect-fingerprint) — a signature under the artifact's own embedded key proves nothing (anyone can self-sign), so the verifier reports it UNVERIFIED. The m-of-n council mode distributes that trust as long as the council's public keys are themselves published/pinned (otherwise an operator who generates all N keys is the council). It is opt-in and zero-impact on the core: src/kry/* stays pure stdlib and imports neither oqs nor kry_pqc (grep -rn "import oqs\|import kry_pqc" src/kry → nothing; only a one-line comment mentions the optional tier). Signatures are post-quantum, so a credit meant to retain value cannot be retroactively forged. This adds authenticity + trust-distribution + quantum-proofing — not veracity: it proves who attested, never that the savings were real (that remains the job of the T1/T2 tiers above). See kry_pqc/README.md.

Magnitude: publicly-checkable arithmetic

Veracity is "did the event happen"; magnitude is "is the KRY amount right". They are separate, and magnitude is fully fixable in software. Each receipt's amount is tokens_saved × EARN_RATES[event] × value_multiplier(avoided_model), against a dated, versioned price basis (PRICE_BASIS_AS_OF, per-model list vs honest estimate quality, with provenance). The attestation exposes each link's tokens_saved + earn_rate (counts and a rate — no content, no model name), so the stranger's verifier recomputes every amount and rejects any receipt whose implied multiplier isn't a published value. This catches inflation even when conservation is kept internally consistent — a class of forgery the chain alone misses (the F2 check).

Cross-language verification (hash_version 7): new chains bind the economic numbers and ts into the chain hash as the exact IEEE-754 double in big-endian hex (struct.pack('>d'), the v5 encoding), so a non-Python verifier (Rust / JS / Go) reproduces every hash byte-for-byte — no dependence on CPython's float→JSON formatting, no precision loss, no rounding or integer-size choice. v6 binds the receipt's receipt_id and v7 binds its event_type (both plain strings — emit them verbatim into the block) so a promotion's supersedes target cannot be re-pointed to a different receipt, and a link cannot be relabeled between two same-earn_rate event types. A cross-language verifier adds the receipt_id (v6+) and event_type (v7+) fields to the block it reconstructs. Legacy v4/v5/v6 receipts keep their original encoding and remain fully verifiable — the change is additive and version-dispatched, so existing receipts, anchors, and the evidence bundle are byte-unchanged.

The promotion overlay is an optional conformance profile (SPEC §3.7, v1.1). Re-tiering via a supersedes link is enforced under five invariants plus an outcome guard (the SAFETY CONTRACT on kry_mint._apply_promotion_overlay; four prior HIGH-severity findings landed in exactly this mechanism), now pinned by a dedicated vector category (vectors/savings/overlay/ — one valid promotion, four adversarial). An independent verifier either implements the profile exactly — the bundled verifiers/js does, and agrees with the reference on the full corpus — or fails closed on any attestation containing a supersedes link; silently ignoring promotions would mis-state veracity_floor.

Readiness: a computed grade, not a claim

KRY grades itself against an external, pre-dated rubric (a prior epistemic-readiness ladder), mechanically — readiness_label() computes it; nobody narrates it.

prototype < prototype_plus < internally_consistent < research_grade < production_ready

The top label structurally requires external evidence — the grader refuses to let more code buy a grade only real data can earn (enforced by tests/test_capabilities.py). The two steps to production_ready are both external and both already have tooling: run real provider_metered/holdout traffic, then kry_or_fetch.py → kry_reconcile.py (Step 1), then a live holdout through kry_savings_report.py (Step 2). See docs/KRY_READINESS.md.

Real-data evidence (2026-06-09/10). The external mechanism has been exercised on real traffic, well beyond the first anchor: provider reconciliation 18/18, agreement 1.00; an accepted-savings run (8/8); a real-corpus cache-holdout replay of organic WildChat traffic (kept as a historical record only: its 2026-06-10 attestation uses legacy hash_version 1 links labelled holdout_validated, which every current verifier rejects since commit e1195c1 (2026-06-15), and its holdout-cost and net figures no longer reproduce under current pricing — details); and validated cheap-model adequacy on real paid calls (GSM8K 87%; code-routing 84% adequacy → up to ~75% cost-avoidance — model-pair-specific and assuming the avoided frontier call would have been kept, which is not separately tested; 71% prefix-cacheable, 5-fold/bootstrap). The acceptance gate's correctness specificity was measured (0% measured) and a default-off correctness layer built + wired. Committed research_grade (2026-06-10): the host system wired confirm() to the general gate, confirmed within TTL (the stall broken), and the fresh corpus reconciled 52/52 at agreement 1.00 → research_grade — graded the --since fresh-run window; the all-time ~0.12 is dominated by OpenRouter-purged legacy gen-ids (un-fetchable, not refuted). production_ready still needs live real-world traffic + a real counterparty. Evidence: docs/evidence/ · research-grade anchor · first anchor · savings.

Modules

All under src/kry/, stdlib only (wc -l src/kry/*.py gives the current size).

Verifying as a stranger

The point of KRY is that someone who does not trust you can check the claim with nothing but the Python standard library and the published attestation.

You don't even need Python: SPEC.md is the normative wire format, vectors/ is its conformance corpus (exact-bytes primitives plus valid/adversarial attestations, generated from the reference so they cannot drift), and verifiers/js/ is an independent, dependency-free JS verifier (node verifiers/js/cli.mjs attestation.json, or --vectors vectors to run the corpus) with a static browser page at verifiers/web/ — hosted live (with tamper/truncation/re-mint demos) at thequantumfalcon.github.io/kry. CI re-runs the JS verifier against the corpus and a regenerate-and-diff drift guard on every push.

python3 scripts/kry_verify.py attestation.json
# integrity (hash chain) + conservation + magnitude (F2) + veracity surface

python3 scripts/kry_reconcile.py kry_data/kry_mint_log.jsonl --provider-export usage.json
# F1 (operator/auditor): match each T1 mint to the provider's OWN usage record.
# --mode per-request (OpenRouter/OpenAI per-call)
# --mode aggregate (Google billing totals) requires --since/--until; here --tolerance-pct defaults to 2.0 (max 5.0).
# An aggregate-mode external packet (kry_verified_artifact.py) is capped at --tolerance-pct 2.0, and that
# script defaults to 5.0, so pass --tolerance-pct 2 (or lower) to it explicitly.

python3 scripts/kry_verified_artifact.py --mint-log kry_data/kry_mint_log.jsonl \
 --write-t1-manifest t1_manifest.json
python3 scripts/kry_verified_artifact.py usage.jsonl --attestation attestation.json \
 --t1-manifest t1_manifest.json --provider-export usage.json --corpus real \
 --provider-export-manifest provider_export_manifest.json \
 --corpus-manifest corpus_manifest.json \
 --outside-review outside_review.json --buyer-feedback buyer_feedback.json \
 --legal-review legal_review.json --bundle-dir packet
python3 scripts/kry_verified_artifact.py --verify-artifact packet/artifact.json
# final packet gate: product + science + external-review evidence + kill triggers
# packet/t1_manifest.json is the shareable T1 reconciliation source; the private mint log stays local.

python3 scripts/kry_finops_report.py packet/artifact.json
# smallest FinOps-facing retained-dollars report; verifies artifact.json first and
# keeps blocked external claims blocked in the human-facing output.
# includes the doctor command buyers should run before trusting the packet surface.

python3 scripts/kry_doctor.py --artifact packet/artifact.json
# local health check: Python/config/docs/verifier surface + saved-packet/checklist/report verification.
# fails if artifact ship_scope is do_not_ship; warns if it is internal_or_demo_only.
# reports artifact-specific external_evidence_status from the verified claim_register.
# treats externally claimable artifacts as packet-shaped handoffs.
# fails if a packet-shaped artifact is missing its checklist or report.
# fails if handoff packet command_inputs depend on absolute local paths.
# fails if private mint-log or ledger material appears in the shareable packet.
# fails if symlinks appear in the shareable packet.
# fails if unbound directories, files, or non-regular entries appear in the shareable packet.
# WARN items are not proof failures; the external evidence warning stays until real
# provider export, outside review, buyer feedback, and legal review exist.

kry_verify.py imports no part of the package — it re-implements the checks from the spec, so passing it is meaningful precisely because it doesn't trust the producer's code.

Repository layout

src/kry/ the package (stdlib only) — see Modules
scripts/ kry_verify · kry_chain_anchor (re-mint/rollback evidence) · kry_reconcile (F1) · kry_or_fetch · kry_savings_report · kry_verified_artifact · kry_finops_report · kry_doctor · kry_litellm_callback (proxy integration)
examples/ try_kry.py (30s demo) · gen_dataset.py (synthetic logs) · sample_usage_log.jsonl
tests/ unit, adversarial regressions (test_hardening), at-scale + fuzz (test_stress)
vectors/ KRY-SPEC conformance corpus, generated from the reference (vectors/generate.py)
verifiers/ independent JS verifier + corpus runner (js/) · static browser verify page (web/)
docs/ CLAIMS_BOUNDARY · VERACITY_BINDING · COUNTERFACTUAL_HOLDOUT · BIOMIMICRY · READINESS · ... (see Documentation)
SPEC.md the normative wire format (repo root)
kry_data/ runtime ledgers (gitignored — never committed)

python3 -m pip install -e ".[dev]" # installs pytest/ruff; runtime package remains dependency-free
python3 scripts/kry_release_verify.py # install + lint + tests + packet + reproducibility smoke
python3 scripts/kry_release_verify.py --full # same gate + 10-round reproducibility proof
python3 -m pytest tests/ -q # stdlib suite; optional crypto tests skip closed if unavailable
ruff check src/ scripts/ tests/ examples/ lab/ # must stay clean
bash lab/reproduce.sh 10 # full local reproducibility loop

Legal posture

Designed as a closed-loop, non-transferable consumptive credit (rebate basis). Settlement is federated, not an open exchange. Nothing here is an offer of a security or a tradeable instrument. Consult securities counsel before any external or tradeable use. Licensed under the Apache License 2.0 (see LICENSE.md): a permissive OSI license — free for any use including commercial, with an explicit patent grant and defensive-termination clause; provided as is, without warranty. Copyright 2026 Thomas Albrecht thequantumfalcon@gmail.com.

Trademarks & no affiliation. Model and product names — OpenAI, GPT, Anthropic, Claude, Opus, Sonnet, OpenRouter, and any others — are trademarks of their respective owners, used here descriptively (nominative fair use) only to identify the systems measured. kry is not affiliated with, endorsed by, or sponsored by any of them. Figures are labelled measured vs projected; the measured ones come from the evidence bundles under docs/evidence/, which state their own scope. Not all of them come from public benchmarks (the n=52 reconciliation is the operator's own traffic), and not all still reproduce under the current code (see the WildChat note above); nothing here is a guarantee of savings, financial advice, or a security, and the software is provided as is, without warranty of any kind.

Documentation