ACP Cache File

AI Context Protocol cache file format for storing indexed codebase metadata

Type object
File match .acp.cache.json
Schema URL https://catalog.lintel.tools/schemas/schemastore/acp-cache-file/latest.json
Source https://acp-protocol.dev/schemas/v1/cache.schema.json

Validate with Lintel

npx @lintel/lintel check
Type: object

AI Context Protocol cache file format (.acp.cache.json)

Properties

version string required

ACP specification version

Examples: "1.0.0"
pattern=^\d+\.\d+\.\d+
generated_at string required

ISO 8601 timestamp when cache was generated

format=date-time
project object required

Project metadata

3 nested properties
name string required

Project name

root string required

Absolute path to project root

description string

Project description

stats object required

Aggregate statistics

3 nested properties
files integer required

Total indexed files

min=0
symbols integer required

Total indexed symbols

min=0
lines integer required

Total lines of code

min=0
source_files Record<string, string> required

Map of relative file paths to modification times for staleness detection

files Record<string, object> required

Map of relative file paths to file entries

symbols Record<string, object> required

Map of qualified symbol names to symbol entries

git_commit string | null

Git commit SHA if project is in a git repository

pattern=^[a-f0-9]{40}$
graph object

Call graph relationships

2 nested properties
forward Record<string, string[]>

Map of symbol to symbols it calls

reverse Record<string, string[]>

Map of symbol to symbols that call it

domains Record<string, object>

Domain index

constraints object

Constraint index

2 nested properties
by_file Record<string, object>

Map of file path to constraints

by_lock_level Record<string, string[]>

Map of lock level to file paths

provenance object

Annotation provenance statistics (RFC-0003)

3 nested properties
summary object

Aggregate provenance statistics

5 nested properties
total integer

Total annotations tracked

min=0
bySource object

Count by source type

5 nested properties
explicit integer
min=0
converted integer
min=0
heuristic integer
min=0
refined integer
min=0
inferred integer
min=0
needsReview integer

Annotations flagged for review

min=0
reviewed integer

Annotations that have been reviewed

min=0
averageConfidence object

Average confidence by source type

2 nested properties
converted number
min=0max=1
heuristic number
min=0max=1
lowConfidence object[]

Annotations with confidence below threshold

lastGeneration object

Last annotation generation run

4 nested properties
id string

Generation batch ID

timestamp string
format=date-time
annotationsGenerated integer
min=0
filesAffected integer
min=0
documentation object

Project-wide documentation index (RFC-0002)

3 nested properties
sources Record<string, object>

Map of source ID to usage info

styles Record<string, object>

Map of style guide to usage info

unresolvedRefs object[]

References that could not be resolved

bridge object

Project-wide bridging statistics (RFC-0006)

5 nested properties
enabled boolean

Whether bridging was enabled during indexing

precedence string

Precedence mode used

Values: "acp-first" "native-first" "merge"
summary object

Aggregate statistics

4 nested properties
totalAnnotations integer

Total annotations from all sources

min=0
convertedCount integer

Annotations converted from native docs

min=0
mergedCount integer

Annotations merged (native + ACP)

min=0
explicitCount integer

Pure ACP annotations

min=0
byFormat Record<string, integer>

Counts by source format

byLanguage Record<string, object>

Counts by programming language

Definitions

annotation_provenance object

Annotation provenance entry (RFC-0003)

value string required

The annotation value

source string

Origin of the annotation

Default: "explicit"
Values: "explicit" "converted" "heuristic" "refined" "inferred"
confidence number

Confidence score for auto-generated annotations (0.0-1.0)

min=0max=1
needsReview boolean

Whether annotation is flagged for human review

Default: false
reviewed boolean

Whether annotation has been reviewed by human

Default: false
reviewedAt string

When the annotation was reviewed

format=date-time
generatedAt string

When the annotation was auto-generated

format=date-time
generationId string

Batch identifier for generation run

inline_annotation object

Inline annotation entry (RFC-001)

type string required

Inline annotation type

Values: "critical" "todo" "fixme" "perf" "hack"
line integer required

Line number

min=1
directive string required

Self-documenting directive for AI (RFC-001)

value string

Annotation value (task description, issue, etc.)

ticket string

Related issue/ticket reference

expires string

Expiration date for hacks

format=date
auto_generated boolean

True if directive was auto-generated (RFC-001)

Default: false
param_entry object

Parameter documentation entry (RFC-001, RFC-0006)

name string required

Parameter name

type string | null

Parameter type (RFC-0006)

typeSource string

Where the type was extracted from (RFC-0006)

Values: "type_hint" "jsdoc" "docstring" "inferred"
optional boolean

Whether parameter is optional

Default: false
default string | null

Default value if optional

description string

Parameter description

directive string

Directive for parameter usage (RFC-001)

source string

Provenance of this entry (RFC-0006)

Values: "explicit" "converted" "merged" "heuristic"
sourceFormat string | null

Original format (jsdoc, docstring:google, etc.) (RFC-0006)

sourceFormats string[]

All formats that contributed for merged entries (RFC-0006)

returns_entry object

Return value documentation entry (RFC-001, RFC-0006)

type string | null

Return type (RFC-0006)

typeSource string

Where the type was extracted from (RFC-0006)

Values: "type_hint" "jsdoc" "docstring" "inferred"
description string

Return value description

directive string

Directive for handling return value (RFC-001)

source string

Provenance of this entry (RFC-0006)

Values: "explicit" "converted" "merged" "heuristic"
sourceFormat string | null

Original format (RFC-0006)

sourceFormats string[]

All formats that contributed for merged entries (RFC-0006)

throws_entry object

Exception documentation entry (RFC-001, RFC-0006)

exception string required

Exception type

description string

When exception is thrown

directive string

How to handle the exception (RFC-001)

source string

Provenance of this entry (RFC-0006)

Values: "explicit" "converted" "merged" "heuristic"
sourceFormat string | null

Original format (RFC-0006)

symbol_constraints object

Symbol-level constraints (RFC-001)

lock_level string

Lock level constraint

Values: "frozen" "restricted" "approval-required" "tests-required" "docs-required" "review-required" "normal" "experimental"
lock_reason string

Structured reason for lock

directive string

Self-documenting directive for AI (RFC-001)

auto_generated boolean

True if directive was auto-generated (RFC-001)

Default: false
file_entry object
path string required

Relative path from project root

lines integer required

Line count

min=0
language string required

Programming language identifier

Values: "typescript" "javascript" "python" "rust" "go" "java" "c-sharp" "cpp" "c" "ruby" "php" "swift" "kotlin"
exports string[] required

Exported symbols (qualified names)

Default:
[]
imports string[] required

Imported modules

Default:
[]
module string | null

Human-readable module name (from @acp:module)

summary string | null

Brief file description (from @acp:summary)

purpose string | null

File purpose from @acp:purpose (RFC-001)

owner string | null

Team ownership from @acp:owner (RFC-001)

inline inline_annotation[]

Inline annotations (RFC-001)

Default:
[]
domains string[]

Domain classifications (from @acp:domain)

Default:
[]
layer string | null

Architectural layer (from @acp:layer)

stability string | null

Stability level

Values: null "stable" "experimental" "deprecated"
ai_hints string[]

AI behavioral hints (e.g., 'ai-careful', 'ai-readonly')

Default:
[]
git object

Git metadata for a file

5 nested properties
last_commit string required

SHA of the last commit that modified this file

pattern=^[a-f0-9]{40}$
last_author string required

Author of the last commit

last_modified string required

ISO 8601 timestamp of the last modification

format=date-time
commit_count integer required

Number of commits that have modified this file

min=0
contributors string[] required

List of unique contributors to this file

refs ref_entry[]

Documentation references (RFC-0002)

Default:
[]
style object

Style guide configuration entry (RFC-0002)

8 nested properties
name string

Style guide name or ID

extends string | null

Parent style guide (from @acp:style-extends)

source string | null

Documentation source ID for this style

url string | null

Direct URL to style guide documentation

format=uri
rules string[]

Specific style rules applied

Default:
[]
scope string

Style scope

Default: "file"
Values: "file" "symbol"
symbolName string | null

Symbol name if scope is 'symbol'

line integer

Line number where style is declared

min=1
annotations Record<string, object>

Annotation provenance tracking (RFC-0003)

bridge object

Documentation bridging metadata (RFC-0006)

6 nested properties
enabled boolean

Whether bridging was enabled for this file

detectedStyle string | null

Auto-detected docstring style (google, numpy, sphinx, etc.)

convertedCount integer

Number of annotations bridged from native docs

min=0
mergedCount integer

Number of annotations merged (native + ACP)

min=0
explicitCount integer

Number of pure ACP annotations

min=0
sourceFormats string[]

Documentation formats found in this file

version string | null

File version (from @acp:version) (RFC-0009)

since string | null

Version when file was introduced (from @acp:since) (RFC-0009)

license string | null

File license (from @acp:license) (RFC-0009)

author string | null

File author (from @acp:author) (RFC-0009)

lifecycle object

Lifecycle status of a symbol or file (RFC-0009)

6 nested properties
deprecated string | null

Deprecation message with version/replacement (from @acp:deprecated)

experimental boolean

API may change without notice (from @acp:experimental)

beta boolean

Feature in beta testing (from @acp:beta)

internal boolean

Not intended for external use (from @acp:internal)

publicApi boolean

Stable public interface (from @acp:public-api)

since string | null

Version when introduced (from @acp:since)

symbol_entry object
name string required

Simple symbol name

qualified_name string required

Format: file_path:class.symbol

type string required

Symbol type

Values: "function" "method" "class" "interface" "type" "enum" "struct" "trait" "const"
file string required

Containing file path

lines integer[] required

[start_line, end_line]

minItems=2maxItems=2
exported boolean required

Whether exported

signature string | null

Function signature if applicable

summary string | null

Brief description (from @acp:summary)

purpose string | null

Symbol purpose from @acp:fn/@acp:class/etc (RFC-001)

params param_entry[]

Parameter descriptions (RFC-001)

Default:
[]
returns object

Return value documentation entry (RFC-001, RFC-0006)

7 nested properties
type string | null

Return type (RFC-0006)

typeSource string

Where the type was extracted from (RFC-0006)

Values: "type_hint" "jsdoc" "docstring" "inferred"
description string

Return value description

directive string

Directive for handling return value (RFC-001)

source string

Provenance of this entry (RFC-0006)

Values: "explicit" "converted" "merged" "heuristic"
sourceFormat string | null

Original format (RFC-0006)

sourceFormats string[]

All formats that contributed for merged entries (RFC-0006)

throws throws_entry[]

Exception descriptions (RFC-001)

Default:
[]
constraints object

Symbol-level constraints (RFC-001)

4 nested properties
lock_level string

Lock level constraint

Values: "frozen" "restricted" "approval-required" "tests-required" "docs-required" "review-required" "normal" "experimental"
lock_reason string

Structured reason for lock

directive string

Self-documenting directive for AI (RFC-001)

auto_generated boolean

True if directive was auto-generated (RFC-001)

Default: false
async boolean

Whether async

Default: false
visibility string

Symbol visibility

Default: "public"
Values: "public" "private" "protected"
calls string[]

Symbols this calls (qualified names)

Default:
[]
called_by string[]

Symbols calling this (qualified names)

Default:
[]
git object

Git metadata for a symbol

3 nested properties
last_commit string required

SHA of the last commit that modified this symbol

pattern=^[a-f0-9]{40}$
last_author string required

Author of the last commit that modified this symbol

code_age_days integer required

Number of days since this code was last modified

min=0
annotations Record<string, object>

Annotation provenance tracking (RFC-0003)

behavioral object

Behavioral characteristics of a symbol (RFC-0009)

8 nested properties
pure boolean

Function has no side effects (from @acp:pure)

idempotent boolean

Function is safe to call multiple times (from @acp:idempotent)

memoized boolean | string

Results are cached; string for duration (from @acp:memoized)

async boolean

Function is asynchronous (from @acp:async)

generator boolean

Function is a generator (from @acp:generator)

throttled string | null

Rate limit specification (from @acp:throttled)

transactional boolean

Function runs in a database transaction (from @acp:transactional)

sideEffects string[]

List of side effects (from @acp:side-effects)

lifecycle object

Lifecycle status of a symbol or file (RFC-0009)

6 nested properties
deprecated string | null

Deprecation message with version/replacement (from @acp:deprecated)

experimental boolean

API may change without notice (from @acp:experimental)

beta boolean

Feature in beta testing (from @acp:beta)

internal boolean

Not intended for external use (from @acp:internal)

publicApi boolean

Stable public interface (from @acp:public-api)

since string | null

Version when introduced (from @acp:since)

documentation object

Documentation metadata for a symbol (RFC-0009)

6 nested properties
examples string[]

Code examples (from @acp:example)

seeAlso string[]

References to related symbols (from @acp:see)

links string[]

External documentation URLs (from @acp:link)

notes string[]

Important notes (from @acp:note)

warnings string[]

Warnings about usage (from @acp:warning)

todos string[]

Pending work items (from @acp:todo)

performance object

Performance characteristics of a symbol (RFC-0009)

3 nested properties
complexity string | null

Time complexity notation (from @acp:perf)

memory string | null

Space complexity notation (from @acp:memory)

cached string | null

Caching duration or strategy (from @acp:cached)

domain_entry object
name string required

Domain identifier

files string[] required

Files in this domain

symbols string[] required

Symbols in this domain (qualified names)

description string

Human description

file_constraints object
lock_level string

Lock level constraint

Values: "frozen" "restricted" "approval-required" "tests-required" "docs-required" "review-required" "normal" "experimental"
lock_reason string

Reason for lock level

directive string

Self-documenting directive for AI (RFC-001)

auto_generated boolean

True if directive was auto-generated from defaults (RFC-001)

Default: false
style string

Style guide constraint

behavior string

AI behavior constraint (matches config.schema.json)

Values: "conservative" "balanced" "aggressive"
quality string[]

Quality constraints

git_file_info object

Git metadata for a file

last_commit string required

SHA of the last commit that modified this file

pattern=^[a-f0-9]{40}$
last_author string required

Author of the last commit

last_modified string required

ISO 8601 timestamp of the last modification

format=date-time
commit_count integer required

Number of commits that have modified this file

min=0
contributors string[] required

List of unique contributors to this file

git_symbol_info object

Git metadata for a symbol

last_commit string required

SHA of the last commit that modified this symbol

pattern=^[a-f0-9]{40}$
last_author string required

Author of the last commit that modified this symbol

code_age_days integer required

Number of days since this code was last modified

min=0
ref_entry object

Documentation reference entry (RFC-0002)

url string required

Documentation URL

format=uri
sourceId string | null

Approved source ID from config (if applicable)

version string | null

Documentation version (from @acp:ref-version)

section string | null

Section within documentation (from @acp:ref-section)

fetch boolean

Whether AI should fetch this reference (from @acp:ref-fetch)

Default: false
scope string

Reference scope

Default: "file"
Values: "file" "symbol"
symbolName string | null

Symbol name if scope is 'symbol'

line integer

Line number where reference appears

min=1
bridge_metadata object

Documentation bridging metadata (RFC-0006)

enabled boolean

Whether bridging was enabled for this file

detectedStyle string | null

Auto-detected docstring style (google, numpy, sphinx, etc.)

convertedCount integer

Number of annotations bridged from native docs

min=0
mergedCount integer

Number of annotations merged (native + ACP)

min=0
explicitCount integer

Number of pure ACP annotations

min=0
sourceFormats string[]

Documentation formats found in this file

style_entry object

Style guide configuration entry (RFC-0002)

name string

Style guide name or ID

extends string | null

Parent style guide (from @acp:style-extends)

source string | null

Documentation source ID for this style

url string | null

Direct URL to style guide documentation

format=uri
rules string[]

Specific style rules applied

Default:
[]
scope string

Style scope

Default: "file"
Values: "file" "symbol"
symbolName string | null

Symbol name if scope is 'symbol'

line integer

Line number where style is declared

min=1
behavioral_annotations object

Behavioral characteristics of a symbol (RFC-0009)

pure boolean

Function has no side effects (from @acp:pure)

idempotent boolean

Function is safe to call multiple times (from @acp:idempotent)

memoized boolean | string

Results are cached; string for duration (from @acp:memoized)

async boolean

Function is asynchronous (from @acp:async)

generator boolean

Function is a generator (from @acp:generator)

throttled string | null

Rate limit specification (from @acp:throttled)

transactional boolean

Function runs in a database transaction (from @acp:transactional)

sideEffects string[]

List of side effects (from @acp:side-effects)

lifecycle_annotations object

Lifecycle status of a symbol or file (RFC-0009)

deprecated string | null

Deprecation message with version/replacement (from @acp:deprecated)

experimental boolean

API may change without notice (from @acp:experimental)

beta boolean

Feature in beta testing (from @acp:beta)

internal boolean

Not intended for external use (from @acp:internal)

publicApi boolean

Stable public interface (from @acp:public-api)

since string | null

Version when introduced (from @acp:since)

documentation_annotations object

Documentation metadata for a symbol (RFC-0009)

examples string[]

Code examples (from @acp:example)

seeAlso string[]

References to related symbols (from @acp:see)

links string[]

External documentation URLs (from @acp:link)

notes string[]

Important notes (from @acp:note)

warnings string[]

Warnings about usage (from @acp:warning)

todos string[]

Pending work items (from @acp:todo)

performance_annotations object

Performance characteristics of a symbol (RFC-0009)

complexity string | null

Time complexity notation (from @acp:perf)

memory string | null

Space complexity notation (from @acp:memory)

cached string | null

Caching duration or strategy (from @acp:cached)