Git-native, cryptographically verifiable, append-only ledgers with policy enforcement.
“What if Git’s content-addressed DAG could be constrained into a deterministic state machine with cryptographic proofs for every transition?”
Ledger-Kernel is a formal specification and reference implementation (libgitledger) for building verifiable, append-only ledgers directly on top of Git’s object model.
Unlike blockchains or SaaS audit logs, Ledger-Kernel is just Git. It adds deterministic replay, cryptographic attestation, and programmable policy enforcement without introducing new infrastructure.
It uses existing .git storage, requiring no daemons or databases. It enforces fast-forward-only semantics to ensure history is immutable and guarantees deterministic replay, where identical input always yields identical state. Every entry is attested for non-repudiable authorship, and the system supports WASM-based policies for validation.
✅ It's just Git! No custom storage, no daemons, just .git.
✅ Enforces fast-forward-only semantics. History is immutable by design.
✅ Provides deterministic replay. Same entries = same state, always.
✅ Cryptographically attests every entry. Non-repudiable authorship.
✅ Supports programmable policies. WASM-based rules for entry validation.
You need tamper-evident provenance for deployments, supply-chain attestations, configuration histories, or schema registries — but you don’t want to run a blockchain node, depend on a vendor SaaS, or invent another storage format.
Ledger-Kernel provides blockchain-grade guarantees using Git as the database.
# Append a deployment record
git ledger append --ref refs/_ledger/prod/deploys \
--payload '{"service":"api","version":"v1.2.3","who":"alice"}'
# Replay to verify deterministic state
git ledger replay --ref refs/_ledger/prod/deploys
# Verify invariants (signatures, policies, timestamps)
git ledger verify --ref refs/_ledger/prod/deploysLedger-Kernel and libgitledger introduce a new primitive: ledger entries — Git commits with meaning, policy, and proof. They’re quiet, boring, and perfectly auditable. You decide how to use them.
graph BT
A(User Interfaces<br/>Apps, TUIs, CLIs)
B(Edge Libraries<br/>Domain Logic, Schemas)
C(Adapters / Ports<br/>libgit2, FS, WASM, RPC)
D(libgitledger<br/>Reference Implementation)
E(Ledger-Kernel Specification<br/>Invariants & Model)
B --> A
C --> B
D --> C
E --> D
Data flows upward through distinct layers.
The architecture is layered. The Kernel Spec defines the formal model and invariants. libgitledger implements those rules in portable C. Adapters connect to Git, WASM policy engines, and RPC daemons. Edges (like Shiplog, Wesley, Git-Mind) apply them to real-world domains. Finally, UIs—CLIs, TUIs, and dashboards—wrap the edges for human use.
- Kernel Spec — Formal model, invariants, compliance tests
libgitledger— Portable C implementation with FFI bindings- Adapters — Git (
libgit2), WASM policy VM, RPC daemon - UIs — CLIs, TUIs, web dashboards
- Edges — Domain-specific tools (Shiplog, Wesley, Git-Mind)
Every compliant implementation MUST enforce:
| Invariant | Meaning |
|---|---|
| Append-Only | Entries cannot be modified or deleted |
| Fast-Forward Only | No rebases, no force pushes |
| Deterministic Replay | Identical inputs → identical state |
| Authenticated Entries | All entries are cryptographically signed |
| Policy Enforcement | Programmable rules gate entry acceptance |
| Temporal Monotonicity | Timestamps never regress |
| Namespace Isolation | Ledgers are independent |
-
Install libgitledger
git clone https://github.com/flyingrobots/ledger-kernel cd ledger-kernel && make && sudo make install
-
Initialize a Ledger
git init my-ledger cd my-ledger git ledger init --namespace prod/deploys -
Append an Entry
git ledger append \ --ref refs/_ledger/prod/deploys \ --payload '{"msg":"Deployed api@v1.0.0"}' \ --sign-with ~/.ssh/id_ed25519
-
Replay & Verify
git ledger replay --ref refs/_ledger/prod/deploys git ledger verify --ref refs/_ledger/prod/deploys
| Document | Purpose |
|---|---|
| SPEC.md | Formal specification and invariants |
| MODEL.md | Mathematical state-transition model |
| ARCHITECTURE.md | System design and layer responsibilities |
| IMPLEMENTATION.md | libgitledger implementation details |
| REFERENCE.md | Language-neutral API contract |
| COMPLIANCE.md | Test suite and conformance criteria |
🚢 Shiplog
Deployment provenance without SaaS
git shiplog run -- "kubectl apply -f deploy.yaml"- Captures
$PWD,$USER,$HOSTNAME,exitcode - Signs with SSH key
- Appends to ledger in
.git - Zero external dependencies
🧠 Git-Mind
Knowledge graphs in Git
git mind ingest notes/
git mind query "show me all TODO items"- RDF triples stored as ledger entries
- Deterministic graph replay
- SPARQL-like queries
Traceability: Every entry is cryptographically signed.
Non-Repudiation: Compliance proofs are emitted per operation.
Monotonic Atomicity: Ledger refs advance only by fast-forward.
Programmable Authorization: WASM policies act as rule gates.
Offline Verifiability: Anyone with read access can replay history.
make compliance # run invariant tests
make determinism # cross-platform determinism check
make proofs # emit proof artifactsCompliance levels progress from Core (eight mandatory invariants) to Verified (independent audit with signed report).
- The C language is the reference implementation (✅ Reference, libgitledger).
- Rust is currently in progress (🚧 In progress, —).
- Go, JS / WASM, and Python are all planned (🔜 Planned, —).
The specification is finalized (✅).
The libgitledger reference implementation and the compliance test suite are both in progress (🚧).
Shiplog integration using libgitledger and the WASM policy engine are planned for the future (🔜).
This project acknowledges
Git (Linus Torvalds) for the content-addressed DAG
Certificate Transparency for append-only logs
Sigstore for supply-chain attestations
and Nix for deterministic builds.
libgitledger is a portable, embeddable C library for append-only ledgers inside a Git repository. Each ledger is a linear history of Git commits on dedicated refs; entries are optionally signed, policy-checked, and indexed for instant queries. It enables both human-readable and binary-safe payloads via a pluggable encoder. 
Why this exists: I’ve built the pattern twice already. shiplog (battle-tested CLI & policy/trust) and git-mind (rigorous hexagonal architecture + roaring bitmap cache). libgitledger fuses them into one stable core library with bindings for Go/JS/Python.
🚢 Shiplog • Deployment Provenance Without SaaS
Shiplog turns your Git repo into a cryptographically-signed, append-only ledger for every deployment. Zero SaaS costs. Zero external infra. Just Git.
Run anything with:
git shiplog run <your-command>Shiplog captures stdout, stderr, exit code, timestamp, author, and reason - the stuff you'd normally lose to the void - and logs it in a signed, immutable ref right inside Git. Who/What/Where/When/Why/How; mystery solved. Deployment logs now live with your codebase, but apart from it. Provenance without clutter.
🛼 Wesley • The Data Layer Compiler
Stop describing your data model six times in six different files.
Everyone else generates GraphQL from databases. Wesley flips the stack and generates databases from GraphQL.
From one schema, Wesley compiles your entire backend:
- Postgres DDL & migrations
- TypeScript types & Zod validators
- Supabase RLS, Realtime & Storage rules
- tRPC endpoints & Prisma/Drizzle integration
- pgTAP tests
- A SHA-locked "Shipme" certification file for zero-downtime deployments
Your schema is the source of truth. Everything else is a compilation target.
Banish drift. Never think about migrations again. Describe your shapes once and let Wesley handle the rest.
Go on, deploy on a Friday.
🧠 Git-Mind • Knowledge Graphs in Git
git mind ingest notes/
git mind query "show me all TODO items"Version your thoughts. Branch your ideas. Merge understanding.
git-mind is an open-source protocol and toolkit that turns Git into a database-less, version-controlled semantic knowledge graph — a tool for distributed cognition, evolving interpretation, and human–AI co-thought.
Author: J. Kirby Ross
Email: james@flyingrobots.dev
GitHub: flyingrobots
MIT License (with Ethical Use Clause) · © 2025 J. Kirby Ross
See LICENSE and NOTICE for terms.
“Provenance without clutter. Policy as infrastructure. Zero SaaS, zero guesswork.”