idea33-buildledger-verifiable-oss/README.md

BuildLedger

BuildLedger is a compact provenance ledger for reproducible OSS builds.

It provides:

• strict build provenance models
• a versioned schema registry
• append-only SQLite ledger storage
• tamper-evident hash chaining
• detached Ed25519 signing for build contracts
• delta-sync packets for partial connectivity
• anchor records for external attestation
• CI context adapters for GitHub Actions, GitLab CI, and CircleCI

What It Solves

Build outputs are only useful when they can be trusted, replayed, and compared. BuildLedger captures the build contract, environment, dependency graph, artifacts, and reproducibility metadata in one validated object, then persists that object into a verifiable ledger.

Package Layout

• buildledger.models - core domain objects
• buildledger.schemas - versioned registry and validation
• buildledger.ledger - SQLite-backed append-only log
• buildledger.sync - delta packet generation and application
• buildledger.anchors - anchor records for ledger heads
• buildledger.adapters - CI context normalization
• buildledger.cli - local operational commands

Quick Start

bash test.sh

Example

from buildledger import SQLiteLedger

ledger = SQLiteLedger("buildledger.sqlite")
entry = ledger.append("build.contract", {"contract_id": "demo"})
ok, issues = ledger.verify_chain()

CLI

python -m buildledger schema-manifest
python -m buildledger init-ledger buildledger.sqlite
python -m buildledger append-sample buildledger.sqlite
python -m buildledger verify buildledger.sqlite
python -m buildledger sign-contract contract.json private-key.pem --output signed-contract.json
python -m buildledger verify-contract signed-contract.json public-key.pem

Testing

• bash test.sh
• pytest
• python3 -m build

Status

This repository currently implements the core ledger, schema, sync, anchor, CI-adapter, and contract-signing foundation. Registry publishing adapters and full distributed integrations can be added on top of this base.