Metadata-Version: 2.4
Name: accountable-record-py
Version: 0.4.1
Author-email: Structural Explainability <se@structural-explainability.org>
License: MIT License
        
        Copyright (c) 2025-2026 Denise M. Case
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: accountability,accountable-record,accountable-record-py,auditability,conformance,contract-validation,diagnostics,manifest-validation,repository-verification,staged-verification,structural-explainability,traceability
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: se-contract-kit
Requires-Dist: se-manifest-schema
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pyright; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Requires-Dist: zensical; extra == 'docs'
Description-Content-Type: text/markdown

# accountable-record-py

[![PyPI](https://img.shields.io/pypi/v/accountable-record-py?logo=pypi&label=pypi)](https://pypi.org/project/accountable-record-py/)
[![Docs Site](https://img.shields.io/badge/docs-site-blue?logo=github)](https://structural-explainability.github.io/accountable-record-py/)
[![Repo](https://img.shields.io/badge/repo-GitHub-black?logo=github)](https://github.com/structural-explainability/accountable-record-py)
[![Python 3.14](https://img.shields.io/badge/python-3.14%2B-blue?logo=python)](./pyproject.toml)
[![Python 3.15 Ready](https://github.com/structural-explainability/accountable-record-py/actions/workflows/python-315-ready.yml/badge.svg?branch=main)](https://github.com/structural-explainability/accountable-record-py/actions/workflows/python-315-ready.yml)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE)

[![CI](https://github.com/structural-explainability/accountable-record-py/actions/workflows/ci-python-zensical.yml/badge.svg?branch=main)](https://github.com/structural-explainability/accountable-record-py/actions/workflows/ci-python-zensical.yml)
[![Docs-Deploy](https://github.com/structural-explainability/accountable-record-py/actions/workflows/deploy-zensical.yml/badge.svg?branch=main)](https://github.com/structural-explainability/accountable-record-py/actions/workflows/deploy-zensical.yml)
[![Pre-Release](https://github.com/structural-explainability/accountable-record-py/actions/workflows/pre-release.yml/badge.svg?branch=main)](https://github.com/structural-explainability/accountable-record-py/actions/workflows/pre-release.yml)
[![Release](https://github.com/structural-explainability/accountable-record-py/actions/workflows/release-pypi.yml/badge.svg)](https://github.com/structural-explainability/accountable-record-py/actions/workflows/release-pypi.yml)
[![Links](https://github.com/structural-explainability/accountable-record-py/actions/workflows/links.yml/badge.svg?branch=main)](https://github.com/structural-explainability/accountable-record-py/actions/workflows/links.yml)
[![Dependabot](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/structural-explainability/accountable-record-py/security)

> 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

| Stage  | Concern | Artifact              | Main purpose                                          |
| ------ | ------- | --------------------- | ----------------------------------------------------- |
| `s010` | `ID`    | Identity artifact     | Establish repository identity.                        |
| `s020` | `CT`    | Contract artifact     | Establish contract context.                           |
| `s030` | `SR`    | Sources artifact      | Validate source material declarations.                |
| `s040` | `EL`    | Elements artifact     | Validate verifiable element quartets.                 |
| `s050` | `CA`    | Catalog artifact      | Build and reconcile the element catalog.              |
| `s060` | `EX`    | Exports artifact      | Validate machine-readable export artifacts.           |
| `s070` | `RS`    | Resolution artifact   | Resolve references and verify lock state.             |
| `s080` | `RP`    | Reports artifact      | Render and validate generated human-readable reports. |
| `s090` | `VF`    | Verification artifact | Verify whole-pipeline coherence.                      |

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

<details>
<summary>Show command reference</summary>

### In a machine terminal

Open a machine terminal where you want the project:

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

cd accountable-record-py
code .
```

### In a VS Code terminal

```shell
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 --from import-linter --with-editable . lint-imports --config .github/.importlinter

# 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:

```text
LOC: 12111
LLOC: 4638
SLOC: 6534
COMMENTS: 370
MULTI: 2488
BLANK: 2328
SINGLE_COMMENTS: 761
```

Expected output:

```text
> 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 RP] ok  Render and validate reports.
[s090 VF] ok  Verify whole-pipeline coherence.
```

```text
---------
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.
```

</details>

## Citation

[CITATION.cff](./CITATION.cff)

## License

[MIT](./LICENSE)

## Manifest

[SE_MANIFEST.toml](./SE_MANIFEST.toml)
