Skip to main content

onetrace

onetrace is an SDK for emitting and verifying stage receipts: a hash-chained, not signed, record of what a pipeline actually did at each step, checkable independently of the code that produced it. Anchoring a record to a public log — proving when it existed, not merely that it is unaltered — is planned for a later release; it is not in 0.1.1. onetrace does not check whether a pipeline's output is true — it checks what was recorded, and whether an independent verifier can confirm that record is internally consistent and unbroken. Truth is a claim about the world; onetrace only ever speaks to what was recorded and what a verifier could confirm about it.

Install and quickstart

pip install onetrace

onetrace-verify (the reference verifier, standard library only) comes along automatically — it is a declared dependency, not an extra step.

Save this as demo.py. It emits a two-stage run with no network, no model, and no file beyond itself:

#!/usr/bin/env python3
"""onetrace quickstart demo: two stages, no network, no model, deterministic."""
import json
import sys
from pathlib import Path

from onetrace.emit import Instrument, Recorder

QUESTION = "What does the warranty cover?"
CORPUS = [
    {"id": "p1", "text": "The warranty covers manufacturing defects for twelve months."},
    {"id": "p2", "text": "Shipping delays are handled by the logistics partner, not the warranty."},
    {"id": "p3", "text": "Batteries are covered by a separate six-month warranty."},
]


def main(out_dir: str, run_id: str) -> None:
    out = Path(out_dir)
    out.mkdir(parents=True, exist_ok=True)
    corpus_path = out / "corpus.json"
    corpus_path.write_text(json.dumps(CORPUS), encoding="utf-8")

    rec = Recorder(out_dir, run_id=run_id, declared_stages=["retrieve", "answer"],
                   manifest=Path(__file__), policy="fail-closed",
                   anchor_reason="quickstart demo; epoch anchoring is not implemented")

    retrieve_cfg = {"tokenizer": "lower-split", "top_k": "1"}

    @rec.stage("retrieve", Instrument("word-overlap", "retriever", "1.0.0", retrieve_cfg))
    def retrieve(ctx):
        corpus = json.loads(
            ctx.read_external(corpus_path, "application/json", name="corpus",
                              trust_class="operator-authored").decode("utf-8"))
        qwords = set(QUESTION.lower().split())
        scored = [(p["id"], p["text"], len(qwords & set(p["text"].lower().split())))
                 for p in corpus]
        scored.sort(key=lambda s: (-s[2], s[0]))
        best_id, best_text, _ = scored[0]
        for k, v in retrieve_cfg.items():
            ctx.constant(k, v)
        ctx.assertion("candidate_count", str(len(corpus)))
        return ctx.write_json("retrieved.json", {"id": best_id, "text": best_text})

    answer_cfg = {"method": "extractive"}

    @rec.stage("answer", Instrument("extractive", "answerer", "1.0.0", answer_cfg))
    def answer(ctx, retrieved_artifact):
        retrieved = ctx.read_json(retrieved_artifact)
        for k, v in answer_cfg.items():
            ctx.constant(k, v)
        ctx.assertion("source", retrieved["id"])
        return ctx.write_json("answer.json", {"answer": retrieved["text"], "cited": retrieved["id"]})

    retrieved = retrieve()
    answer(retrieved)


if __name__ == "__main__":
    main(sys.argv[1], sys.argv[2])

Emit two runs of it:

python demo.py run_a run-a
python demo.py run_b run-b

Verify one with the reference verifier:

cd run_a && onetrace-verify .
[PASS   ] receipts/01-retrieve.json: bytes are canonical
...
[PASS   ] manifest: chain head matches the last receipt

54 pass, 0 fail, 2 not-run  ->  PASS

The 2 not-run rows are originality — this run is unanchored (no epoch anchoring configured), so the verifier checks that the record is internally consistent, not that it is first-published.

Compare the two runs:

onetrace diff run_a run_b --out diff_report
baseline   run_a  run-a  (run)
candidate  run_b  run-b  (run)

diff: identical

stage         baseline            candidate           verdict
--------------------------------------------------------------------
retrieve      51bd312473c4        51bd312473c4        same
answer        35a281ec6835        35a281ec6835        same

first difference  none
comparisons performed 2; stages identical before the first difference 2

onetrace localize takes the same two runs (or just one, to find the first unclean stage in it alone) and finds the first point of divergence:

onetrace localize run_a run_b --out localize_report
baseline   run_a  run-a  (run)
candidate  run_b  run-b  (run)

localize: identical

stage         baseline            candidate           verdict
--------------------------------------------------------------------
retrieve      51bd312473c4        51bd312473c4        same
answer        35a281ec6835        35a281ec6835        same

first difference  none
comparisons performed 2; stages identical before the first difference 2

onetrace reproduce re-executes a recorded stage and compares its output against what the receipt claims — it needs the original pipeline code available to re-run, so it isn't part of this quickstart.

This transcript was run word for word in a fresh virtual environment (pip install onetrace from a locally-built wheel, no editable install, no repository checkout) before being written here.

Five verdicts

Every stage in a comparison gets exactly one of five verdicts, and nothing else:

  • same — the stage's output digest matches on both sides.
  • FIRST DIFFERENCE — the first stage, in order, whose output digest does not match.
  • downstream — after the first difference, still different; the divergence propagated.
  • reconverged — after diverging, a later stage's output matches again (different work, same result — this happens in practice and is reported honestly, not hidden).
  • COULD NOT CHECK — the stage can't be evaluated (an unimplemented format version, a declared boundary, a file that can't be read). This is not a pass, and it is not silently folded into "same."

A verdict is always about a stage's output. A difference in the instrument, its configuration, or the declared constants never changes a verdict by itself — it appears as an annotation alongside the ladder, naming exactly what differs, so a same result never hides that something about how the output was produced changed even though the bytes didn't.

diff and localize each also report one overall result word for the whole comparison (identical, diverged, not comparable, refused, or could not check, with exit codes 0/1/2/3/4 respectively — localize on a single run instead reports clean or located, exit 0 or 1); reproduce reports each stage as REPRODUCED, DIVERGED, or COULD NOT CHECK.

Documentation and the trust model

This package's source distribution ships its own documentation, rather than linking out to it: docs/ (the format in plain words, the five verdicts, the three verbs, one page per adapter, what onetrace does not claim, and docs/manual.md, the full developer manual), the stage-receipt format itself (an Internet-Draft, draft/), and the reference verifier with its rejection vectors (verifier/). A wheel install (pip install onetrace) does not include these — get the sdist instead: pip download --no-binary :all: --no-deps onetrace, then unpack the .tar.gz.

The verifier does not trust the SDK that emitted a record. Every record this SDK produces is checked the same way a record from any other emitter would be — the verifier reads bytes, not intentions, and it owes nothing to the code that wrote them.

Stability

The current record format is stage-receipt/0.2 (format major version 0), specified by an Internet-Draft that has not yet reached RFC status. Anything in the format — required members, canonical-form rules, the rejection vectors — may still change before major version 1. Format major version is carried in every record: a manifest declaring one the reference verifier does not implement is refused outright, by name, rather than silently accepted (verify a manifest with an unrecognized format and it prints [REFUSED] manifest: format -- ... and exits non-zero); a verb comparing individual stages reports the stage's own verdict as COULD NOT CHECK for the same reason. Neither ever guesses.

License, security, and reporting a problem

Licensed under Apache-2.0 (LICENSE, in the source distribution).

This is pre-release software (see the classifiers in pyproject.toml). See SECURITY.md (in the source distribution) for what's in scope; report a vulnerability to onetrace@oneproof.dev, not as a public issue. For anything else — a bug, a question, a feature request — open an issue at github.com/shamiksaharcciit-oss/onetrace-issues.

Metadata

Release files for onetrace 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for onetrace 0.1.1
File Size Uploaded Provenance Actions
onetrace-0.1.1.tar.gz 4.8 MB Without provenance Details for onetrace-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for onetrace 0.1.1
File Interpreter ABI Platform Actions
onetrace-0.1.1-py3-none-any.whl Python 3 none any Details for onetrace-0.1.1-py3-none-any.whl

Total release size: 4.9 MB

Release files / onetrace-0.1.1.tar.gz

Download URL onetrace-0.1.1.tar.gz
Size 4.8 MB
Tags Source
SHA-256 checksum
How to use checksums
4e728db5495284c905866880d57c4c924c93eb9b2bfddadc975b0b311e442b70
BLAKE2b-256 checksum
How to use checksums
84ab56580b6554ba8b002b77b10ea410e9facf37a7db96530b7fa74b5a6073b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / onetrace-0.1.1-py3-none-any.whl

Download URL onetrace-0.1.1-py3-none-any.whl
Size 88.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eccc509e80ac782dd89aa8e2f84d34aa21bc582cc84e306d362340b361e3d6cf
BLAKE2b-256 checksum
How to use checksums
ae47284a7de99d6ae43f5430434ad5142bcab1e01d4322463a873e3a9f80635e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for onetrace 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page