Skip to main content

Accountable Surface Specification

PyPI Docs Site Repo Python 3.14 License

CI Docs-Deploy Pre-Release Release Links Dependabot

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.

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

.accountability/surfaces.toml

Citation

CITATION.cff

License

MIT

Repository Manifest

SE_MANIFEST.toml

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)

Source distribution for accountable-surface-spec 0.1.0
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)

Table of built distributions (wheels) for accountable-surface-spec 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page