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
uvx pre-commit run --all-files

uv run accountable-record write-lock
uv run accountable-record verify-lock

uv run accountable-record run all

# or through a stage
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

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

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

# contract checks (should be all kept, 0 broken)
uvx --with-editable . import-linter lint

# find dead code
uvx --with-editable . vulture src/accountable_record

# complexity on all (only A and B allowed)
uvx radon cc src/accountable_record -s -a

# complexity (check for any C ratings, should return nothing)
uvx radon cc src/accountable_record -s -a -n C


# maintainability on all (should be A)
uvx radon cc src/accountable_record -s

# hal
uvx radon cc src/accountable_record

# raw
uvx radon cc src/accountable_record

# raw (totals)
uvx radon raw src/accountable_record -j | uv run python -c "import json, sys; data=json.load(sys.stdin); keys=('loc','lloc','sloc','comments','multi','blank','single_comments'); totals={k:sum(file[k] for file in data.values()) for k in keys}; print('\n'.join(f'{k.upper()}: {v}' for k,v in totals.items()))"

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

Current snapshot shows modest size and significant documentation:

LOC: 11547
LLOC: 4370
SLOC: 6136
COMMENTS: 367
MULTI: 2478
BLANK: 2210
SINGLE_COMMENTS: 723

Expected output:

> uv run accountable-record run all

[s010 ID] ok  Validate repository identity metadata.
[s020 CT] ok  Establish and validate contract context.
[s030 SR] ok  Validate repository source materials.
[s040 EL] ok  Validate verifiable element declarations.
[s050 CA] ok  Build and validate the normalized catalog.
[s060 EX] ok  Write and validate machine-readable exports.
[s070 RS] ok  Resolve references and verify lock state.
[s080 GN] ok  Validate generated artifacts.
[s090 DC] ok  Render and validate documentation.

---------
Contracts
---------

Analyzed 119 files, 213 dependencies.
-------------------------------------

Pipeline must not import stage packages KEPT
Stage 010 must not import later stages KEPT
Stage 020 must not import later stages KEPT
Stage 030 must not import later stages KEPT
Stage 040 must not import later stages KEPT
Stage 050 must not import later stages KEPT
Stage 060 must not import later stages KEPT
Stage 070 must not import later stages KEPT
Stage 080 must not import later stages KEPT

Contracts: 9 kept, 0 broken.

Citation

CITATION.cff

License

MIT

Manifest

SE_MANIFEST.toml