ACC Implementer's Guide

Status: Non-normative guidance
Applies to: ACC v1

This guide helps teams turn ACC declarations into parsers, generators, gateways, policy components, or complete runtimes. It explains implementation patterns without prescribing a product architecture.

Normative ACC behavior is defined only by SPEC.md, the binding documents, and the versioned schema. If this guide conflicts with those sources, the normative sources win.

1. Reading Labels

This document uses four labels:

• Normative: behavior already required or recommended by ACC v1.
• Recommended: an implementation pattern that commonly produces safe, portable behavior.
• Optional: useful platform functionality that is not required for ACC compatibility.
• Example: one possible design. Examples do not define the standard.

ACC does not require a particular programming language, database, model provider, UI, deployment topology, tool transport, or approval product.

2. Choose an Implementation Profile

Before building, choose the claim that matches the component:

• ACC parser: reads and validates ACC declarations.
• ACC generator: produces ACC declarations from source code, annotations, or another contract.
• ACC runtime: applies ACC exposure and invocation semantics.
• ACC policy component: evaluates a documented subset of ACC governance semantics for another runtime or gateway.

The profiles and their minimum evidence are defined in conformance/PROFILES.md. A component should claim only the profile it actually implements.

3. Reference Architecture

The following architecture is a reference, not a required topology:

flowchart LR
    A["OpenAPI + ACC declaration"] --> B["Contract ingestion"]
    B --> C["Capability registry or adapter"]
    C --> D["Exposure policy"]
    D --> E["Agent, gateway, or caller"]
    E --> F["Pre-invocation governance"]
    F -->|"approval intent"| G["External approval owner"]
    G -->|"approved or denied"| F
    F --> H["Trusted subject and authority bridge"]
    H --> I["Business operation"]
    F --> J["Audit and diagnostics"]
    I --> J

Cost tracking, console UI, routing products, model orchestration, HMAC signatures, queues, and deployment tooling may be valuable, but they are not required by ACC v1.

4. Declaration Ingestion Lifecycle

Normative and recommended sequence:

1. Parse the OpenAPI operation and locate x-agent-capability.
2. Validate version, enabled, and scope.
3. Resolve standard OpenAPI parameters and requestBody schemas.
4. Validate that every approval.when.param resolves to a declared, typed argument.
5. Reject or skip unsupported major versions with diagnostics.
6. Ignore unknown ACC fields safely.
7. Preserve implementation-specific extensions without treating them as security policy.
8. Produce a normalized capability record or equivalent generated artifact.

A runtime should keep the original operation identity and source location so diagnostics can point back to the contract authors.

5. Exposure Lifecycle

Before a capability becomes visible to an agent or caller:

1. Exclude declarations with enabled: false or an empty scope.
2. Apply the runtime's documented scope allowlist semantics.
3. If subject.required is true, require a trusted acting subject before exposure or invocation.
4. Apply safe risk defaults when risk.level is omitted.
5. Preserve the standard parameter schema used for argument generation and validation.
6. Emit diagnostics for skipped or unsupported declarations.

For approval evaluation, approval.required: true is unconditional. Otherwise, approval.when uses ANY semantics: the first or any matching condition is sufficient to create an approval intent. Implementations may evaluate every condition for diagnostics, but a non-matching condition cannot cancel another matching condition.

ACC does not standardize a route object. A runtime may use routes, products, tenants, scenarios, or static policies as its exposure context, provided its matching behavior is documented.

6. Invocation Lifecycle

The following sequence is suitable for an LLM tool loop, API gateway, deterministic workflow, or another caller:

select capability
  -> validate arguments against OpenAPI
  -> resolve trusted acting subject
  -> evaluate scope and runtime policy
  -> evaluate risk and approval intent
  -> apply timeout/rate-limit policy
  -> request approval or continue
  -> invoke the business operation
  -> let the business system authorize the subject
  -> record result/failure with redaction
  -> return a typed result to the caller

The model or caller may propose a capability and arguments. It must not determine its own scope, risk, subject trust, approval decision, or audit policy.

Machine-readable reference inputs and abstract expected outcomes are published under conformance/v1. They test portable decisions rather than a particular queue, database, hash algorithm, or user interface.

7. Approval Intent Reference Flow

ACC declares that approval is required; it does not standardize the workflow owner or persistence model.

A portable reference state model is:

stateDiagram-v2
    [*] --> Pending: approval intent created
    Pending --> Approved: external authority approves
    Pending --> Denied: external authority denies
    Pending --> Expired: policy deadline reached
    Approved --> Consumed: authorized invocation is accepted
    Denied --> [*]
    Expired --> [*]
    Consumed --> [*]

Recommended safety properties:

• freeze or hash the capability identity and invocation arguments that were reviewed;
• bind the decision to a trusted approver or business authority;
• prevent an approval from authorizing different arguments;
• make an approval single-use unless the business policy explicitly says otherwise;
• record denial, expiry, and execution failure as distinct outcomes.

After approval, a runtime may resume a suspended invocation, enqueue a new invocation, or rerun a deterministic snapshot. Those are implementation choices, not ACC semantics.

8. Security Invariants and Failure Modes

These are specification-derived invariants, not claims about how often a particular implementation fails.

Implementation-specific incidents may be contributed as clearly labeled examples. A single product's internal failure should not be generalized into normative ACC behavior without portable semantics and conformance evidence.

9. Conformance Mapping

Use conformance/PROFILES.md to select the applicable profile and conformance/SELF_ASSESSMENT.md to publish evidence.

10. Registering an Implementation

ACC uses open registration and self-assessment, not official certification.

1. Select an implementation profile.
2. Complete the self-assessment template.
3. Publish evidence and known limitations in the implementation repository.
4. Submit a pull request that adds the implementation to IMPLEMENTATIONS.md.
5. Keep the declared ACC version and evidence current.

Registry inclusion means the declaration is complete enough to list. It is not a security audit, production-readiness guarantee, commercial endorsement, or certification.