tracefold

Purpose

TraceFold's positioning is: AI agents should not make irreversible changes. It escrows the inverse operation of an effect before the effect lands, or refuses the effect from landing, and issues receipts that anyone can verify offline. It explicitly states that it is not an observability tool (Not an observability tool), but rather sits before the effect (It sits before the effect).

Main Capabilities

• Escrow the inverse operation before the effect: Before an AI agent's write operation lands, a hook hands the write operation to escrow, first ensuring the inverse operation exists, otherwise refusing the effect.
• Reversible undo: Through gx undo <txid> to initiate a new transformation, data is not deleted, but the original write is superseded.
• Byte-level verification: Execute sha256sumon the restored file, and the result is exactly identical to the hash before the write.
• Offline verifiable receipts: Through gx receipt verify --pretty verify the signature, canonical CID, and inclusion, all completed offline, without needing to trust a third party.
• Offline verification webpage: Open tracefold.github.io/tracefold/verify.html, paste the receipt and key to verify, 100% run through WebAssembly within the tab, with strictly 0 network requests.
• Deterministic reproducible demo: examples/openclaw-plugin-demo/ runs the same before_tool_call escrow path (refuse before landing, retrieve afterward), against the real gx binary and real filesystem, scripted, with no API key required.

Usage

• Install a single binary gx, which is the CLI run by the above demo (gx undo、gx receipt verify). It has been published on crates.io, version 0.1.2, under the Apache-2.0 license, and can also be built from source.
• The repository's tags no longer include prebuilt binaries after v0.1.1-alpha, and that version is only for Linux x86_64; for multi-platform builds, see issue #7.
• Documentation index: docs/README.md lists the reading order for all documents and articles in this repository.
• Formal technical report: docs/TRACEFOLD_TR.md contains the complete mathematical proof and receipt encoding.
• Formal verification specification: lean/README.md provides a machine-checked Lean 4 theorem suite.
• Exclusion taxonomy: docs/LIMITS.md sets out the category boundaries and limits enforced by tests.
• Adapter guide: docs/ADAPTER_GUIDE.md explains what is needed to connect a new substrate to the managed gate, how cost is measured, and the consistency requirements.
• Error taxonomy: docs/ERROR_TAXONOMY.md provides the error classification and exit code specification.
• Recoverability mechanism: docs/RECOVERABILITY.md defines reversible execution states.
• Development tree tests: docs/DEVELOPMENT_TREE_TESTS.md provides a taxonomy of full-lineage test probes.
• Users can also run tools/e2e.sh in their own clone to obtain numbers from their own machine.

Applicable scenarios

It is suitable for scenarios where an AI agent needs to perform write operations, but those operations are required to be reversible or rejectable, especially for write operations on real repositories rather than fixtures. The example demonstration shows a real OpenClaw agent (deepseek/deepseek-chat, real API calls rather than fixtures) dispatching a write tool call, gx's before_tool_call hook triggering and handing the write to the managed gate before it lands; after the write is committed,gx undo <txid> initiates a new transformation to replace the original write; then byte verification and offline receipt verification are performed.

Limitations

• The project deliberately does not provide CI/build badges. The reason is stated truthfully: this repository has never carried a workflow file, no commit has touched .github/workflows/, and all Actions runs visible here are GitHub's own defaults (CodeQL and Pages), completed on push since September 1, 2026. The CI described in the next sentence comes from the private tree from which this repository is synchronized. f65aac2f cannot be resolved here either, because during the period when that account was blocked by billing (req/908), any push from it since 2026-08-15T17:25:29Z ran zero jobs; the last run covered 16 of this project's 17 workspace crates. The TypeScript SDK's tests have never run under CI. Nothing on this page was produced by a build of this repository. The repository status was checked via the GitHub API on September 4, 2026; complete and dated details are in item 8 of docs/LIMITS.md.
• Regarding the db/ subproject: it is a self-contained crate that compiles a Markdown corpus into addressable atoms, records what it accepts in an append-only log, and answers queries from a SQLite index that can be deleted and rebuilt. It is licensed under Apache-2.0. It is its own cargo workspace, not a member of the root workspace, so the cargo build --workspace here will not touch it, and none of this repository's checks cover it either—it must be built and tested separately:cd db && cargo test -p db(all 21 checks pass when added). On the measurement corpus, for the same question it returns 14.7 times fewer bytes than grep, but takes about 62 milliseconds, whereas grep takes only 2 milliseconds; that tradeoff, along with the two lines the test harness refuses to time, are in db/README.md.
• Pricing and charging: everything published here is free—verification, receipts, self-hosting—and remains free as long as a single person uses it. Nothing is for sale, and paying does not change what you get. If you still wish to fund it, there is only one channel: supporting TraceFold via Stripe's "pay what you want" (switched from Polar to Stripe on September 1, 2026, because onboarding for the Polar checkout account was not completed). Either way, no return is promised.
• The project also cites a foundational paper, "A Mechanical World Model for Agents" (DOI: 10.5281/zenodo.22168558), as well as a mechanical world model for agents. Other details not explicitly provided in the above materials are not yet available.