Skip to content

Manifest Model

This document defines the semantic model for .accountability/surfaces.toml.

The JSON schema defines the manifest's structural shape. This document defines how conforming tools interpret that structure.

Manifest purpose

An accountable surface manifest declares repository and lifecycle surfaces where technical capability is not sufficient authority.

The manifest records:

  • which surfaces are authority-bearing;
  • what kind of object each surface is;
  • what authority-bearing roles each surface performs;
  • what review is required for each role;
  • what evidence is required for each role;
  • what AI authority is permitted for each role;
  • what downstream effects may follow from changes;
  • what revocation behavior, if any, is permitted.

The manifest records authority boundaries. It does not confer authority, legitimacy, obligation, or enforcement as substrate facts.

Document structure

A manifest has three primary levels:

repository
  -> surface
      -> surface.role

repository identifies the repository and selected profile.

surface identifies a protected object or pattern of objects.

surface.role identifies an authority-bearing function performed by that surface.

Repository table

The [repository] table identifies the manifest context.

Required fields:

[repository]
name = "example-repository"
profile = "repository-protected-surface"

Recommended fields:

description = "Example repository using accountable surface declarations."

name identifies the repository.

profile identifies the profile whose rules apply to the manifest.

description gives human-readable context.

Surface declaration

Each [[surface]] declaration identifies one protected surface.

Required fields:

[[surface]]
id = "project-configuration"
object_kind = "file"
paths = ["pyproject.toml"]

Recommended fields:

description = "Project metadata, dependencies, tools, and release-affecting configuration."

id is a stable local identifier for the surface.

object_kind describes what the surface is.

paths identifies the file, directory, workflow, generated artifact, command, schema artifact, release artifact, or lifecycle gate covered by the declaration.

A surface MUST have exactly one object_kind.

A surface MUST have one or more roles.

Object kind and role kind

Object kind and role kind are separate axes.

object_kind describes what the surface is.

surface.role.kind describes the authority-bearing function the surface performs.

Example:

[[surface]]
id = "project-configuration"
object_kind = "file"
paths = ["pyproject.toml"]

[[surface.role]]
kind = "project_identity_surface"

[[surface.role]]
kind = "dependency_boundary"

[[surface.role]]
kind = "public_command_surface"

In this example, pyproject.toml is one file. It performs multiple authority-bearing roles.

A manifest MUST NOT use the same term ambiguously as both an object kind and a role kind unless the specification defines separate object and role forms.

For example:

schema_artifact = object kind
schema_authority = role kind
release_artifact = object kind
release_authority = role kind

Surface role declaration

Each [[surface.role]] declaration defines one authority-bearing role for the current surface.

Typical fields:

[[surface.role]]
kind = "dependency_boundary"
requires_review = ["human_review", "security_review"]
requires_evidence = ["verification_command_result"]
ai_max_authority = "drafting"

kind identifies the authority-bearing role.

requires_review declares review requirements.

requires_evidence declares evidence requirements.

ai_max_authority declares the maximum AI authority permitted for that role.

Multi-role composition

A single surface may have multiple roles.

For multi-role surfaces:

  • review requirements compose by union;
  • evidence requirements compose by union;
  • downstream effects compose by union;
  • AI authority resolves by the most restrictive applicable value;
  • revocation permissions resolve by the most restrictive applicable value.

A tool MUST preserve the role that introduced each requirement.

A tool MUST NOT collapse all roles into one untyped approval.

Effective authority

The effective AI authority for a surface is the most restrictive applicable authority across all roles covering the relevant scope.

Example:

[[surface.role]]
kind = "documentation_contract"
ai_max_authority = "drafting"

[[surface.role]]
kind = "release_authority"
ai_max_authority = "advisory"

The effective AI authority for the surface is advisory unless the roles are scoped separately.

If any applicable role sets ai_max_authority = "prohibited", effective AI authority is prohibited.

Declared vs satisfied requirements

The manifest declares requirements.

It does not prove those requirements are satisfied.

A validator or enforcement layer may inspect external evidence to determine whether declared review and evidence requirements have been satisfied.

A conforming tool MUST distinguish:

declared review requirement
satisfied review requirement
declared evidence requirement
satisfied evidence requirement

Review satisfaction

AI systems may assist review, but may not satisfy human review authority.

AI-generated review notes, summaries, diffs, or evidence checklists MAY support a human reviewer.

They MUST NOT satisfy a human review requirement.

A human review requirement is satisfied only by attributable review from a human reviewer with the required reviewer authority.

Evidence attribution

Satisfied evidence SHOULD identify:

  • evidence kind;
  • evidence source;
  • producing actor or system;
  • timestamp or run identifier when available;
  • related surface;
  • related role;
  • related review requirement;
  • reviewer authority when evidence satisfies human review.

Human review evidence MUST identify reviewer authority.

Revocation model

Revocation is authority-bearing.

A role MAY declare allowed revocation kinds:

[[surface.role]]
kind = "security_boundary"
allowed_revocation_kinds = ["protective_revoke", "authoritative_revoke"]
ai_allowed_revocation_kinds = ["protective_revoke"]
requires_review = ["human_review", "security_review"]
requires_evidence = ["audit_log", "incident_report", "rollback_record"]

allowed_revocation_kinds declares which revocation kinds may occur for the role when all required review and evidence conditions are satisfied.

ai_allowed_revocation_kinds declares which revocation kinds, if any, AI systems may participate in for the role.

AI systems MUST NOT perform or satisfy authority for authoritative_revoke by default.

protective_revoke MAY be permitted only under narrow, logged, bounded, reversible, or reviewable safety and recovery rules.

authoritative_revoke requires human or institutional approval.

If a role omits allowed_revocation_kinds, no revocation authority is implied.

If a role omits ai_allowed_revocation_kinds, no AI revocation authority is implied.

Manifest self-protection

The authority manifest is itself a protected surface.

A manifest MUST declare .accountability/surfaces.toml as a protected surface.

AI authority over the manifest MUST be prohibited.

The manifest MUST require human review and evidence of review for changes.

Extension fields

Profiles MAY define additional fields.

Tools MAY preserve unknown fields.

Unknown fields MUST NOT be interpreted as granting authority.

Unknown fields MUST NOT weaken manifest self-protection, review satisfaction, or AI authority limits.

Validator interpretation

A validator SHOULD check:

  • manifest structure;
  • required repository fields;
  • required surface fields;
  • required role fields;
  • manifest self-protection;
  • object-kind and role-kind separation;
  • multi-role composition;
  • known vocabulary terms;
  • declared review requirements;
  • declared evidence requirements;
  • declared-vs-satisfied distinction;
  • prohibited AI authority over the manifest;
  • absence of default AI authority over sensitive permissions;
  • revocation restrictions where declared.

A validator MUST NOT present declared requirements as satisfied requirements without inspecting attributable evidence.