idea33-buildledger-verifiable-oss/AGENTS.md

BuildLedger Agent Guide

Architecture

• buildledger.models defines the canonical provenance objects.
• buildledger.ledger stores immutable entries in SQLite and verifies chain integrity.
• buildledger.schemas provides a versioned schema registry over the core models.
• buildledger.sync emits and applies delta packets for reconnect/resync workflows.
• buildledger.anchors records tamper-evident head anchors.
• buildledger.adapters normalizes CI context into build contracts.
• buildledger.cli offers small operational commands for local use.

Tech Stack

• Python 3.11+
• pydantic for strict model validation
• sqlite3 for local persistence
• pytest for tests
• build for packaging verification

Testing

• Run bash test.sh from the repo root.
• test.sh must succeed with pytest and python3 -m build.

Rules

• Keep ledger records append-only and hash-verified.
• Prefer canonical JSON serialization for hashes and sync packets.
• Keep adapters thin and deterministic.
• Add or update tests when changing model, storage, or sync logic.
• Preserve ASCII unless a file already requires otherwise.