Terminology

ACP Version: 1.0.0 Document Version: 1.0.0 Last Updated: 2024-12-18 Status: Draft

Table of Contents

1. RFC 2119 Keywords
2. Core Concepts
3. File Types
4. Annotations
5. Constraints
6. Variables
7. Symbols
8. Organization
9. Conformance
10. Glossary

1. RFC 2119 Keywords

This specification uses requirement level keywords as defined in RFC 2119. These keywords indicate the level of requirement for conformant implementations.

1.1 Absolute Requirements

1.2 Recommendations

1.3 Optional Features

1.4 Usage in This Specification

Throughout ACP documentation:

• Requirements for implementations (tools, CLIs, libraries) use these keywords to specify conformance requirements
• Requirements for AI systems use these keywords to specify expected behavior when claiming ACP conformance
• Requirements for file formats use these keywords to specify validation rules

Example usage:

Cache files MUST use UTF-8 encoding.
Implementations SHOULD support incremental updates.
Extensions MAY define custom annotation namespaces.

2. Core Concepts

2.1 AI Context Protocol (ACP)

A standardized protocol for embedding machine-readable documentation and constraints in source code. ACP enables AI systems to understand code structure, respect developer intentions, and navigate codebases efficiently.

2.2 Annotation

A structured comment in source code that provides machine-readable metadata. All ACP annotations use the @acp: prefix.

Example:

/**
 * @acp:module "Authentication Service"
 * @acp:domain authentication
 * @acp:lock restricted
 */

2.3 Constraint

An advisory rule that guides how AI systems should interact with code. Constraints are not enforced at runtime but MUST be respected by conformant AI systems.

Types: Lock, Style, Behavior, Quality

2.4 Variable

A token-efficient reference to a code element. Variables use the $PREFIX_NAME format and expand to full context.

Example: $SYM_VALIDATE_SESSION expands to full symbol information.

2.5 Cache

A pre-computed JSON file (.acp.cache.json) containing indexed codebase structure. The cache enables efficient queries without parsing source files on every request.

2.6 Index

The process of scanning source files to extract annotations, symbols, and relationships, producing a cache file.

2.7 Query

A request for information from the cache. Queries can be made via CLI, jq, or programmatic API.

3. File Types

3.1 Cache File (.acp.cache.json)

The pre-computed codebase index containing:

• File metadata
• Symbol definitions
• Call graphs
• Domain classifications
• Constraint index

Status: Required for ACP functionality Generation: Created by acp index command Location: Project root (default)

3.2 Config File (.acp.config.json)

Project-level configuration controlling:

• File inclusion/exclusion patterns
• Error handling strictness
• Default constraints
• Domain patterns
• Implementation limits

Status: Optional (sensible defaults apply) Generation: Created by acp init or manually Location: Project root

3.3 Variables File (.acp.vars.json)

Variable definitions for token-efficient references:

• Symbol variables (SYM_*)
• File variables (FILE_*)
• Domain variables (DOM_*)

Status: Optional Generation: Created by acp vars command Location: Project root (default)

3.4 Directory Config (.acp.dir.json)

Directory-level configuration that applies to all files in a directory tree. Used for setting constraints on entire directories.

Status: Optional Generation: Manual Location: Any directory

4. Annotations

4.1 Annotation Prefix

The literal string @acp: that begins all ACP annotations. Case-sensitive; @ACP: is invalid.

4.2 Namespace

The category identifier following the prefix. Identifies the type of annotation.

Examples: module, domain, lock, summary

4.3 Sub-namespace

An optional secondary identifier following the namespace, separated by a colon.

Example: @acp:lock-reason (where lock-reason could be considered a sub-namespace)

4.4 Value

The content following the namespace. May be quoted (for strings with spaces) or unquoted (for simple values).

Examples:

• Quoted: @acp:module "User Authentication"
• Unquoted: @acp:lock frozen

4.5 Reserved Namespaces

Namespaces defined by the ACP specification:

4.6 Extension Namespace

Custom namespaces defined by vendors, using the x- prefix.

Format: @acp:x-vendor-feature Example: @acp:x-acme-internal "team-only"

5. Constraints

5.1 Advisory Constraint

A rule that guides AI behavior without runtime enforcement. AI systems claiming ACP conformance MUST respect these constraints, but there is no technical mechanism to prevent violations.

5.2 Lock Level

A graduated scale of modification restrictions. Listed from most to least restrictive:

5.3 Style Constraint

A constraint specifying coding conventions and formatting requirements.

Example: @acp:style google-typescript

5.4 Style Rules

Custom rules extending a base style guide.

Example: @acp:style-rules max-line-length=100, no-any

5.5 Behavior Constraint

Guidance for AI decision-making approach.

5.6 Quality Constraint

Requirements for additional checks or validations.

Common values:

• security-review — Requires security audit
• performance-test — Requires performance validation
• manual-test — Requires manual testing
• regression-test — Requires regression testing

6. Variables

6.1 Variable Reference

A token in the format $PREFIX_NAME that expands to code element information.

Example: $SYM_VALIDATE_SESSION

6.2 Variable Prefix

The category identifier at the start of a variable name.

6.3 Variable Expansion

The process of replacing a variable reference with its full content.

Example:

• Input: $SYM_VALIDATE
• Output: validateSession (src/auth/session.ts:45-89) - Validates JWT tokens

6.4 Expansion Modifier

A suffix that controls what information is included in expansion.

6.5 Variable Scoping

Variables have global scope within a project. All variables in .acp.vars.json are accessible throughout the project.

7. Symbols

7.1 Symbol

A named code element: function, class, method, constant, type, etc.

7.2 Qualified Name

A unique identifier for a symbol, combining file path and symbol path.

Format: {relative_path}:{qualified_symbol}

Examples:

• src/auth/session.ts:SessionService.validateSession
• src/utils/helpers.ts:formatDate
• lib/core.py:CoreEngine.process

7.3 Symbol Types

7.4 Symbol Visibility

Access level for a symbol.

7.5 Exported Symbol

A symbol that is exported from its module and available for import by other modules.

8. Organization

8.1 Domain

A logical grouping of related code based on business or functional area.

Examples: authentication, billing, user-management, api, database

Usage: Declared via @acp:domain annotation; indexed in cache for filtering and navigation.

8.2 Layer

An architectural classification indicating a symbol's role in the application structure.

Standard layers:

8.3 Stability

An indicator of how likely a module's API is to change.

8.4 Call Graph

A data structure representing call relationships between symbols.

Components:

• Forward graph: Maps symbol → symbols it calls
• Reverse graph: Maps symbol → symbols that call it

9. Conformance

9.1 Conformance Level

A tier of implementation capability. ACP defines three levels:

9.2 Conformant Implementation

An implementation that meets all MUST requirements for its claimed conformance level.

9.3 Strictness Mode

A configuration option controlling error handling behavior.

9.4 Partial Conformance

An implementation that meets a base conformance level plus specific features from higher levels.

10. Glossary

Alphabetical listing of all defined terms.

Appendix A: Notation Conventions

A.1 Code Examples

Code examples in this specification use the following conventions:

// JavaScript/TypeScript examples use this comment style
/**
 * Block comments for annotations
 */

# Python examples use hash comments
"""
Or docstrings for annotations
"""

{
  "json_examples": "use standard JSON format",
  "field_names": "use snake_case per ACP convention"
}

A.2 Placeholders

A.3 Tables

Requirement level indicators in tables:

Appendix B: Related Documents

• Introduction — Overview and getting started
• Cache Format — Cache file specification
• Config Format — Configuration options
• Annotations — Annotation syntax
• Constraints — Constraint system
• Variables — Variable system
• Main Specification — Complete protocol specification

End of Terminology