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 binding parser: extracts and validates ACC declarations from a named carrier protocol.
• ACC binding generator: produces a named binding 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["Binding-native operation + ACC declaration"] --> B["Binding 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 a supported binding and locate its ACC declaration carrier.
2. Validate version, enabled, and scope.
3. Resolve the binding-native input schema and map it to the ACC JSON value model.
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.

For the OpenAPI binding, steps 1 and 3 mean locating operation-level x-agent-capability and resolving standard OpenAPI parameters plus requestBody schemas. Other bindings must define equivalent extraction and mapping under Binding Requirements.

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 binding-native input 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.

Per-Invocation Conditions Do Not Limit Cumulative Effects

approval.when evaluates one invocation at a time. Consider a refund operation with this condition:

approval:
  when:
    - param: amount
      op: ">"
      value: 1000

The condition creates approval intent for one refund above 1000. It does not prevent an agent from proposing 60 separate refunds of 999, and it does not calculate a customer's daily, tenant-wide, or rolling-window total.

Do not represent cumulative fraud controls, velocity limits, account balances, or other stateful business invariants as if a per-invocation ACC condition enforced them. Keep those controls in the authoritative business or policy layer, evaluate them against current state, and let that layer reject or escalate the operation even when the individual ACC condition does not match.

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 the binding-native input schema
  -> 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.

6.1 Trust Across Multiple Hops

subject.required: true distinguishes a capability that needs a trusted acting subject from one that does not. It does not make an arbitrary inbound subject field trustworthy, and it does not establish an end-to-end delegation chain.

For a chain such as Agent A -> Runtime B -> Runtime C -> business operation, every trust boundary must answer separately:

• who asserted the subject;
• how that assertion was authenticated or verified;
• whether delegation to the next hop is allowed;
• what capability, arguments, task, audience, and time window the delegation covers;
• what happens when verification, freshness, or replay checks fail.

A runtime must not upgrade model output or an unverified upstream claim into trusted subject context. Deployments that need cross-hop continuity should use a complementary identity or delegation mechanism and document its binding to ACC capability identity and invocation arguments. ACC compatibility alone is not evidence that the subject at the final hop is the subject authenticated at the first hop.

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.

7.1 Traceability And Independently Verifiable Evidence

An audit trail written by the same runtime that resolves the subject and enforces approval can provide useful operational traceability inside that runtime's trust domain. It is not independent proof against compromise of that runtime.

Where a deployment requires approval evidence that another party can verify, it should bind at least the subject, capability identity, canonical invocation arguments, task or request identity, decision, issuer, and validity context before execution. The deployment must also define:

• one canonical byte representation shared by signer and verifier;
• signature and key-discovery rules;
• freshness and clock assumptions;
• nonce, sequence, or other replay protection;
• fail-closed behavior when any verification step is unavailable or ambiguous.

These details are deliberately not ACC v1 semantics. A deployment may use a separate approval-evidence or delegation protocol, provided it does not present that protocol's guarantees as guarantees of ACC itself.

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.