Accountable Surface Specification
Defines the portable manifest format for declaring authority-gated repository surfaces.
Protected-surface thesis
A protected surface is one where the technical capability to change it is not sufficient authority to change it.
Access control can grant the capability to perform an operation. It does not by itself establish that the capability is sufficient authority to modify a protected repository surface.
Accountable Surfaces records where capability is insufficient authority, and binds each crossing of that gap to required human review, supporting evidence, and permitted AI participation.
Scope
This repository defines the structure and conformance rules for:
.accountability/surfaces.toml- protected surface declarations
- surface object and role structure
- review and evidence requirements
- AI authority limits
- manifest self-protection
- declared-vs-satisfied obligation checks
- enforcement mappings to existing external mechanisms
This repository is the source of truth for the accountable surface manifest format. It does not define all vocabulary terms directly. Vocabulary terms are defined in the accountable authority, surface, review, and evidence vocabulary repositories.
Core rule
Technical capability is not authority.
Repository surfaces that carry authority-bearing roles must be declared explicitly, reviewed explicitly, evidenced explicitly, and enforced externally.
Status
Draft v0.1.0.
The specification is intentionally repository-first. It is validated first against concrete software and theory repositories before any broader portability claim is considered.
Related repositories
| Repository | Purpose |
|---|---|
accountable-authority-vocabulary |
Permission, AI authority level, denial state, and revocation terms. |
accountable-surface-vocabulary |
Surface object, surface role, downstream effect, and reserved lifecycle-gate terms. |
accountable-review-vocabulary |
Review kind, review scope, reviewer authority, and review satisfaction terms. |
accountable-evidence-vocabulary |
Evidence, verification, attribution, and attestation terms. |
Initial profiles
| Profile | Purpose |
|---|---|
repository-protected-surface |
General repository profile for protected files, directories, commands, workflows, generated artifacts, and releases. |
lean-theory-repository |
Profile for Lean theory repositories with public theorem surfaces, reference artifacts, generated contracts, and validation commands. |
Validate .accountability in a Repository
uvx accountable-surface-spec validate --path .accountability/surfaces.toml --strict
Developer Command Reference
Python tooling is used to verify internal consistency and generate artifacts.
Show command reference
In a machine terminal
Open a machine terminal where you want the project:
git clone https://github.com/structural-explainability/accountable-surface-spec
cd accountable-surface-spec
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
# validate SE manifest
uvx se-manifest-schema validate-manifest --path SE_MANIFEST.toml --strict
# validate accountable surface manifests
uv run accountable-surface-spec validate
uv run accountable-surface-spec validate --path .accountability/surfaces.toml --strict
uv run accountable-surface-spec check-examples
uv run accountable-surface-spec export-schema --check
# do chores
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
Authority Manifest
Citation
License
Repository Manifest
Metadata
Release files for accountable-surface-spec 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| accountable_surface_spec-0.1.0.tar.gz | 13.4 kB | With provenance | Details for accountable_surface_spec-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| accountable_surface_spec-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for accountable_surface_spec-0.1.0-py3-none-any.whl |
Total release size: 32.5 kB
Release files / accountable_surface_spec-0.1.0.tar.gz
| Download URL | accountable_surface_spec-0.1.0.tar.gz |
|---|---|
| Size | 13.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5d8f49becf4fb1034e70568add82082cfd0c93ebc04dc51a945b3ed9b6f95ad1
|
|
BLAKE2b-256 checksum How to use checksums |
26e54a3b653626a0c742ca5199650581f74e75099a82995a7f75e3e8d0cccfa5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 3, 2026.
Transparency logRelease files / accountable_surface_spec-0.1.0-py3-none-any.whl
| Download URL | accountable_surface_spec-0.1.0-py3-none-any.whl |
|---|---|
| Size | 19.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0c78b37105a3c817129ded1c4d3f4ea56c9065950553e874184ec3fcd067da49
|
|
BLAKE2b-256 checksum How to use checksums |
1d2699c8389a8916d29a5bf1af22678ed55b9e32b1df4d357fc2e26a746a2f71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 3, 2026.
Transparency logSecurity for accountable-surface-spec 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for accountable_surface_spec-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.