accountable-surface-spec 0.1.0

Canonical accountable surface manifest schema and validation for the Structural Explainability ecosystem.

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

.accountability/surfaces.toml

Citation

CITATION.cff

License

MIT

Repository Manifest

SE_MANIFEST.toml