accountable-record-py

Python reference implementation for staged Accountable Record repository verification.

Overview

This project validates Accountable Record-compatible repositories through a staged pipeline.

The verifier can validate its own repository or a target repository passed with --target.

Target validation is internal coherence by default: the target repository declares its identity in SE_MANIFEST.toml, and the pipeline checks that the repository's metadata and derived artifacts cohere with that declaration.

Package Interface

• The Python import package is accountable_record.
• The Python distribution package is accountable-record-py.
• The public command is accountable-record.

Staged Pipeline

s010_identity     repository identity
s020_contract     contract context
s030_sources      source materials
s040_elements     verifiable element declarations
s050_catalog      normalized catalog
s060_exports      machine-readable exports
s070_resolution   reference and lock resolution
s080_generated    generated artifact validation
s090_docs         documentation rendering

Stages run in increasing order. For example:

• run s040 runs s010 through s040.
• run all runs the full pipeline.

Architecture

A stage is a transform:

StageTransform = Callable[[PipelineState], PipelineState]

PipelineRunContext holds fixed run input, including the target repository. PipelineState is an immutable accumulator containing diagnostics and outputs from completed stages.

Identity validation is target-agnostic. SE_MANIFEST.toml is authoritative for repository identity. CITATION.cff is authoritative for contract/publication version when a version exists.

Command Reference

Show command reference

In a machine terminal

Open a machine terminal where you want the project:

git clone https://github.com/structural-explainability/accountable-record-py

cd accountable-record-py
code .

In a VS Code terminal

uv self update
uv python pin 3.14
uv sync --extra dev --extra docs --upgrade

uvx pre-commit install

git add -A
uvx pre-commit run --all-files
# repeat if changes were made
git add -A
uvx pre-commit run --all-files

uv run accountable-record run s010
uv run accountable-record run s020
uv run accountable-record run s030
uv run accountable-record run s040
uv run accountable-record run s050
uv run accountable-record run s060
uv run accountable-record run s070
uv run accountable-record run s080
uv run accountable-record run s090
uv run accountable-record run all

# validate another repository
uv run accountable-record --target ../judicial-record run all

# convenience aliases
uv run accountable-record check
uv run accountable-record build-catalog
uv run accountable-record export
uv run accountable-record resolve-packages
uv run accountable-record write-lock
uv run accountable-record verify-lock
uv run accountable-record validate-generated
uv run accountable-record render-docs

# types, tests, docs
uv run python -m pyright
uv run python -m pytest
uv run python -m zensical build

# save progress
git add -A
git commit -m "update"
git push -u origin main

Citation

CITATION.cff

License

MIT

Manifest

SE_MANIFEST.toml