https://raw.githubusercontent.com/acp-protocol/acp-spec/main/schemas/v1/cache.schema.json

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "$id": "https://acp-protocol.dev/schemas/v1/cache.schema.json",
  "title": "ACP Cache File",
  "description": "AI Context Protocol cache file format (.acp.cache.json)",
  "type": "object",
  "required": [
    "version",
    "generated_at",
    "project",
    "stats",
    "source_files",
    "files",
    "symbols"
  ],
  "properties": {
    "version": {
      "type": "string",
      "description": "ACP specification version",
      "pattern": "^\\d+\\.\\d+\\.\\d+",
      "examples": [
        "1.0.0"
      ]
    },
    "generated_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when cache was generated"
    },
    "git_commit": {
      "type": [
        "string",
        "null"
      ],
      "description": "Git commit SHA if project is in a git repository",
      "pattern": "^[a-f0-9]{40}$"
    },
    "project": {
      "type": "object",
      "description": "Project metadata",
      "required": [
        "name",
        "root"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Project name"
        },
        "root": {
          "type": "string",
          "description": "Absolute path to project root"
        },
        "description": {
          "type": "string",
          "description": "Project description"
        }
      }
    },
    "stats": {
      "type": "object",
      "description": "Aggregate statistics",
      "required": [
        "files",
        "symbols",
        "lines"
      ],
      "properties": {
        "files": {
          "type": "integer",
          "minimum": 0,
          "description": "Total indexed files"
        },
        "symbols": {
          "type": "integer",
          "minimum": 0,
          "description": "Total indexed symbols"
        },
        "lines": {
          "type": "integer",
          "minimum": 0,
          "description": "Total lines of code"
        }
      }
    },
    "source_files": {
      "type": "object",
      "description": "Map of relative file paths to modification times for staleness detection",
      "additionalProperties": {
        "type": "string",
        "format": "date-time",
        "description": "ISO 8601 timestamp of last modification"
      }
    },
    "files": {
      "type": "object",
      "description": "Map of relative file paths to file entries",
      "additionalProperties": {
        "$ref": "#/$defs/file_entry"
      }
    },
    "symbols": {
      "type": "object",
      "description": "Map of qualified symbol names to symbol entries",
      "additionalProperties": {
        "$ref": "#/$defs/symbol_entry"
      }
    },
    "graph": {
      "type": "object",
      "description": "Call graph relationships",
      "properties": {
        "forward": {
          "type": "object",
          "description": "Map of symbol to symbols it calls",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "reverse": {
          "type": "object",
          "description": "Map of symbol to symbols that call it",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "domains": {
      "type": "object",
      "description": "Domain index",
      "additionalProperties": {
        "$ref": "#/$defs/domain_entry"
      }
    },
    "constraints": {
      "type": "object",
      "description": "Constraint index",
      "properties": {
        "by_file": {
          "type": "object",
          "description": "Map of file path to constraints",
          "additionalProperties": {
            "$ref": "#/$defs/file_constraints"
          }
        },
        "by_lock_level": {
          "type": "object",
          "description": "Map of lock level to file paths",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "provenance": {
      "type": "object",
      "description": "Annotation provenance statistics (RFC-0003)",
      "properties": {
        "summary": {
          "type": "object",
          "description": "Aggregate provenance statistics",
          "properties": {
            "total": {
              "type": "integer",
              "minimum": 0,
              "description": "Total annotations tracked"
            },
            "bySource": {
              "type": "object",
              "description": "Count by source type",
              "properties": {
                "explicit": {
                  "type": "integer",
                  "minimum": 0
                },
                "converted": {
                  "type": "integer",
                  "minimum": 0
                },
                "heuristic": {
                  "type": "integer",
                  "minimum": 0
                },
                "refined": {
                  "type": "integer",
                  "minimum": 0
                },
                "inferred": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            },
            "needsReview": {
              "type": "integer",
              "minimum": 0,
              "description": "Annotations flagged for review"
            },
            "reviewed": {
              "type": "integer",
              "minimum": 0,
              "description": "Annotations that have been reviewed"
            },
            "averageConfidence": {
              "type": "object",
              "description": "Average confidence by source type",
              "properties": {
                "converted": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                },
                "heuristic": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 1
                }
              }
            }
          }
        },
        "lowConfidence": {
          "type": "array",
          "description": "Annotations with confidence below threshold",
          "items": {
            "type": "object",
            "properties": {
              "target": {
                "type": "string",
                "description": "File path or symbol qualified name"
              },
              "annotation": {
                "type": "string",
                "description": "Annotation type (e.g., summary, domain)"
              },
              "confidence": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "value": {
                "type": "string",
                "description": "The annotation value"
              }
            }
          }
        },
        "lastGeneration": {
          "type": "object",
          "description": "Last annotation generation run",
          "properties": {
            "id": {
              "type": "string",
              "description": "Generation batch ID"
            },
            "timestamp": {
              "type": "string",
              "format": "date-time"
            },
            "annotationsGenerated": {
              "type": "integer",
              "minimum": 0
            },
            "filesAffected": {
              "type": "integer",
              "minimum": 0
            }
          }
        }
      }
    },
    "documentation": {
      "type": "object",
      "description": "Project-wide documentation index (RFC-0002)",
      "properties": {
        "sources": {
          "type": "object",
          "description": "Map of source ID to usage info",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Documentation URL"
              },
              "version": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Documentation version"
              },
              "fileCount": {
                "type": "integer",
                "minimum": 0,
                "description": "Number of files referencing this source"
              },
              "files": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Files referencing this source"
              }
            }
          }
        },
        "styles": {
          "type": "object",
          "description": "Map of style guide to usage info",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "fileCount": {
                "type": "integer",
                "minimum": 0,
                "description": "Number of files using this style"
              },
              "files": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Files using this style"
              },
              "source": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Associated documentation source ID"
              }
            }
          }
        },
        "unresolvedRefs": {
          "type": "array",
          "description": "References that could not be resolved",
          "items": {
            "type": "object",
            "properties": {
              "file": {
                "type": "string",
                "description": "File containing the unresolved reference"
              },
              "ref": {
                "type": "string",
                "description": "The unresolved reference value"
              },
              "reason": {
                "type": "string",
                "description": "Why the reference could not be resolved"
              }
            }
          }
        }
      }
    },
    "bridge": {
      "type": "object",
      "description": "Project-wide bridging statistics (RFC-0006)",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether bridging was enabled during indexing"
        },
        "precedence": {
          "type": "string",
          "enum": [
            "acp-first",
            "native-first",
            "merge"
          ],
          "description": "Precedence mode used"
        },
        "summary": {
          "type": "object",
          "description": "Aggregate statistics",
          "properties": {
            "totalAnnotations": {
              "type": "integer",
              "minimum": 0,
              "description": "Total annotations from all sources"
            },
            "convertedCount": {
              "type": "integer",
              "minimum": 0,
              "description": "Annotations converted from native docs"
            },
            "mergedCount": {
              "type": "integer",
              "minimum": 0,
              "description": "Annotations merged (native + ACP)"
            },
            "explicitCount": {
              "type": "integer",
              "minimum": 0,
              "description": "Pure ACP annotations"
            }
          }
        },
        "byFormat": {
          "type": "object",
          "description": "Counts by source format",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "byLanguage": {
          "type": "object",
          "description": "Counts by programming language",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "fileCount": {
                "type": "integer",
                "minimum": 0
              },
              "convertedCount": {
                "type": "integer",
                "minimum": 0
              },
              "detectedStyles": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "$defs": {
    "annotation_provenance": {
      "type": "object",
      "description": "Annotation provenance entry (RFC-0003)",
      "required": [
        "value"
      ],
      "properties": {
        "value": {
          "type": "string",
          "description": "The annotation value"
        },
        "source": {
          "type": "string",
          "enum": [
            "explicit",
            "converted",
            "heuristic",
            "refined",
            "inferred"
          ],
          "default": "explicit",
          "description": "Origin of the annotation"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Confidence score for auto-generated annotations (0.0-1.0)"
        },
        "needsReview": {
          "type": "boolean",
          "default": false,
          "description": "Whether annotation is flagged for human review"
        },
        "reviewed": {
          "type": "boolean",
          "default": false,
          "description": "Whether annotation has been reviewed by human"
        },
        "reviewedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the annotation was reviewed"
        },
        "generatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the annotation was auto-generated"
        },
        "generationId": {
          "type": "string",
          "description": "Batch identifier for generation run"
        }
      }
    },
    "inline_annotation": {
      "type": "object",
      "description": "Inline annotation entry (RFC-001)",
      "required": [
        "type",
        "line",
        "directive"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "critical",
            "todo",
            "fixme",
            "perf",
            "hack"
          ],
          "description": "Inline annotation type"
        },
        "value": {
          "type": "string",
          "description": "Annotation value (task description, issue, etc.)"
        },
        "line": {
          "type": "integer",
          "minimum": 1,
          "description": "Line number"
        },
        "directive": {
          "type": "string",
          "description": "Self-documenting directive for AI (RFC-001)"
        },
        "ticket": {
          "type": "string",
          "description": "Related issue/ticket reference"
        },
        "expires": {
          "type": "string",
          "format": "date",
          "description": "Expiration date for hacks"
        },
        "auto_generated": {
          "type": "boolean",
          "default": false,
          "description": "True if directive was auto-generated (RFC-001)"
        }
      }
    },
    "param_entry": {
      "type": "object",
      "description": "Parameter documentation entry (RFC-001, RFC-0006)",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Parameter name"
        },
        "type": {
          "type": [
            "string",
            "null"
          ],
          "description": "Parameter type (RFC-0006)"
        },
        "typeSource": {
          "type": "string",
          "enum": [
            "type_hint",
            "jsdoc",
            "docstring",
            "inferred"
          ],
          "description": "Where the type was extracted from (RFC-0006)"
        },
        "optional": {
          "type": "boolean",
          "default": false,
          "description": "Whether parameter is optional"
        },
        "default": {
          "type": [
            "string",
            "null"
          ],
          "description": "Default value if optional"
        },
        "description": {
          "type": "string",
          "description": "Parameter description"
        },
        "directive": {
          "type": "string",
          "description": "Directive for parameter usage (RFC-001)"
        },
        "source": {
          "type": "string",
          "enum": [
            "explicit",
            "converted",
            "merged",
            "heuristic"
          ],
          "description": "Provenance of this entry (RFC-0006)"
        },
        "sourceFormat": {
          "type": [
            "string",
            "null"
          ],
          "description": "Original format (jsdoc, docstring:google, etc.) (RFC-0006)"
        },
        "sourceFormats": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "All formats that contributed for merged entries (RFC-0006)"
        }
      }
    },
    "returns_entry": {
      "type": "object",
      "description": "Return value documentation entry (RFC-001, RFC-0006)",
      "properties": {
        "type": {
          "type": [
            "string",
            "null"
          ],
          "description": "Return type (RFC-0006)"
        },
        "typeSource": {
          "type": "string",
          "enum": [
            "type_hint",
            "jsdoc",
            "docstring",
            "inferred"
          ],
          "description": "Where the type was extracted from (RFC-0006)"
        },
        "description": {
          "type": "string",
          "description": "Return value description"
        },
        "directive": {
          "type": "string",
          "description": "Directive for handling return value (RFC-001)"
        },
        "source": {
          "type": "string",
          "enum": [
            "explicit",
            "converted",
            "merged",
            "heuristic"
          ],
          "description": "Provenance of this entry (RFC-0006)"
        },
        "sourceFormat": {
          "type": [
            "string",
            "null"
          ],
          "description": "Original format (RFC-0006)"
        },
        "sourceFormats": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "All formats that contributed for merged entries (RFC-0006)"
        }
      }
    },
    "throws_entry": {
      "type": "object",
      "description": "Exception documentation entry (RFC-001, RFC-0006)",
      "required": [
        "exception"
      ],
      "properties": {
        "exception": {
          "type": "string",
          "description": "Exception type"
        },
        "description": {
          "type": "string",
          "description": "When exception is thrown"
        },
        "directive": {
          "type": "string",
          "description": "How to handle the exception (RFC-001)"
        },
        "source": {
          "type": "string",
          "enum": [
            "explicit",
            "converted",
            "merged",
            "heuristic"
          ],
          "description": "Provenance of this entry (RFC-0006)"
        },
        "sourceFormat": {
          "type": [
            "string",
            "null"
          ],
          "description": "Original format (RFC-0006)"
        }
      }
    },
    "symbol_constraints": {
      "type": "object",
      "description": "Symbol-level constraints (RFC-001)",
      "properties": {
        "lock_level": {
          "type": "string",
          "enum": [
            "frozen",
            "restricted",
            "approval-required",
            "tests-required",
            "docs-required",
            "review-required",
            "normal",
            "experimental"
          ],
          "description": "Lock level constraint"
        },
        "lock_reason": {
          "type": "string",
          "description": "Structured reason for lock"
        },
        "directive": {
          "type": "string",
          "description": "Self-documenting directive for AI (RFC-001)"
        },
        "auto_generated": {
          "type": "boolean",
          "default": false,
          "description": "True if directive was auto-generated (RFC-001)"
        }
      }
    },
    "file_entry": {
      "type": "object",
      "required": [
        "path",
        "lines",
        "language",
        "exports",
        "imports"
      ],
      "properties": {
        "path": {
          "type": "string",
          "description": "Relative path from project root"
        },
        "module": {
          "type": [
            "string",
            "null"
          ],
          "description": "Human-readable module name (from @acp:module)"
        },
        "summary": {
          "type": [
            "string",
            "null"
          ],
          "description": "Brief file description (from @acp:summary)"
        },
        "purpose": {
          "type": [
            "string",
            "null"
          ],
          "description": "File purpose from @acp:purpose (RFC-001)"
        },
        "owner": {
          "type": [
            "string",
            "null"
          ],
          "description": "Team ownership from @acp:owner (RFC-001)"
        },
        "inline": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/inline_annotation"
          },
          "default": [],
          "description": "Inline annotations (RFC-001)"
        },
        "lines": {
          "type": "integer",
          "minimum": 0,
          "description": "Line count"
        },
        "language": {
          "type": "string",
          "description": "Programming language identifier",
          "enum": [
            "typescript",
            "javascript",
            "python",
            "rust",
            "go",
            "java",
            "c-sharp",
            "cpp",
            "c",
            "ruby",
            "php",
            "swift",
            "kotlin"
          ]
        },
        "domains": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Domain classifications (from @acp:domain)"
        },
        "layer": {
          "type": [
            "string",
            "null"
          ],
          "description": "Architectural layer (from @acp:layer)"
        },
        "stability": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            null,
            "stable",
            "experimental",
            "deprecated"
          ],
          "description": "Stability level"
        },
        "exports": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Exported symbols (qualified names)"
        },
        "imports": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Imported modules"
        },
        "ai_hints": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "AI behavioral hints (e.g., 'ai-careful', 'ai-readonly')"
        },
        "git": {
          "$ref": "#/$defs/git_file_info",
          "description": "Git metadata for the file"
        },
        "refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ref_entry"
          },
          "default": [],
          "description": "Documentation references (RFC-0002)"
        },
        "style": {
          "$ref": "#/$defs/style_entry",
          "description": "Style guide configuration (RFC-0002)"
        },
        "annotations": {
          "type": "object",
          "description": "Annotation provenance tracking (RFC-0003)",
          "additionalProperties": {
            "$ref": "#/$defs/annotation_provenance"
          }
        },
        "bridge": {
          "$ref": "#/$defs/bridge_metadata",
          "description": "Documentation bridging metadata (RFC-0006)"
        },
        "version": {
          "type": [
            "string",
            "null"
          ],
          "description": "File version (from @acp:version) (RFC-0009)"
        },
        "since": {
          "type": [
            "string",
            "null"
          ],
          "description": "Version when file was introduced (from @acp:since) (RFC-0009)"
        },
        "license": {
          "type": [
            "string",
            "null"
          ],
          "description": "File license (from @acp:license) (RFC-0009)"
        },
        "author": {
          "type": [
            "string",
            "null"
          ],
          "description": "File author (from @acp:author) (RFC-0009)"
        },
        "lifecycle": {
          "$ref": "#/$defs/lifecycle_annotations",
          "description": "Lifecycle status (RFC-0009)"
        }
      }
    },
    "symbol_entry": {
      "type": "object",
      "required": [
        "name",
        "qualified_name",
        "type",
        "file",
        "lines",
        "exported"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Simple symbol name"
        },
        "qualified_name": {
          "type": "string",
          "description": "Format: file_path:class.symbol"
        },
        "type": {
          "type": "string",
          "enum": [
            "function",
            "method",
            "class",
            "interface",
            "type",
            "enum",
            "struct",
            "trait",
            "const"
          ],
          "description": "Symbol type"
        },
        "file": {
          "type": "string",
          "description": "Containing file path"
        },
        "lines": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "minItems": 2,
          "maxItems": 2,
          "description": "[start_line, end_line]"
        },
        "signature": {
          "type": [
            "string",
            "null"
          ],
          "description": "Function signature if applicable"
        },
        "summary": {
          "type": [
            "string",
            "null"
          ],
          "description": "Brief description (from @acp:summary)"
        },
        "purpose": {
          "type": [
            "string",
            "null"
          ],
          "description": "Symbol purpose from @acp:fn/@acp:class/etc (RFC-001)"
        },
        "params": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/param_entry"
          },
          "default": [],
          "description": "Parameter descriptions (RFC-001)"
        },
        "returns": {
          "$ref": "#/$defs/returns_entry",
          "description": "Return value description (RFC-001)"
        },
        "throws": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/throws_entry"
          },
          "default": [],
          "description": "Exception descriptions (RFC-001)"
        },
        "constraints": {
          "$ref": "#/$defs/symbol_constraints",
          "description": "Symbol-level constraints (RFC-001)"
        },
        "async": {
          "type": "boolean",
          "default": false,
          "description": "Whether async"
        },
        "exported": {
          "type": "boolean",
          "description": "Whether exported"
        },
        "visibility": {
          "type": "string",
          "enum": [
            "public",
            "private",
            "protected"
          ],
          "default": "public",
          "description": "Symbol visibility"
        },
        "calls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Symbols this calls (qualified names)"
        },
        "called_by": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Symbols calling this (qualified names)"
        },
        "git": {
          "$ref": "#/$defs/git_symbol_info",
          "description": "Git metadata for the symbol"
        },
        "annotations": {
          "type": "object",
          "description": "Annotation provenance tracking (RFC-0003)",
          "additionalProperties": {
            "$ref": "#/$defs/annotation_provenance"
          }
        },
        "behavioral": {
          "$ref": "#/$defs/behavioral_annotations",
          "description": "Behavioral characteristics (RFC-0009)"
        },
        "lifecycle": {
          "$ref": "#/$defs/lifecycle_annotations",
          "description": "Lifecycle status (RFC-0009)"
        },
        "documentation": {
          "$ref": "#/$defs/documentation_annotations",
          "description": "Documentation metadata (RFC-0009)"
        },
        "performance": {
          "$ref": "#/$defs/performance_annotations",
          "description": "Performance characteristics (RFC-0009)"
        }
      }
    },
    "domain_entry": {
      "type": "object",
      "required": [
        "name",
        "files",
        "symbols"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Domain identifier"
        },
        "description": {
          "type": "string",
          "description": "Human description"
        },
        "files": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Files in this domain"
        },
        "symbols": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Symbols in this domain (qualified names)"
        }
      }
    },
    "file_constraints": {
      "type": "object",
      "properties": {
        "lock_level": {
          "type": "string",
          "enum": [
            "frozen",
            "restricted",
            "approval-required",
            "tests-required",
            "docs-required",
            "review-required",
            "normal",
            "experimental"
          ],
          "description": "Lock level constraint"
        },
        "lock_reason": {
          "type": "string",
          "description": "Reason for lock level"
        },
        "directive": {
          "type": "string",
          "description": "Self-documenting directive for AI (RFC-001)"
        },
        "auto_generated": {
          "type": "boolean",
          "default": false,
          "description": "True if directive was auto-generated from defaults (RFC-001)"
        },
        "style": {
          "type": "string",
          "description": "Style guide constraint"
        },
        "behavior": {
          "type": "string",
          "enum": [
            "conservative",
            "balanced",
            "aggressive"
          ],
          "description": "AI behavior constraint (matches config.schema.json)"
        },
        "quality": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Quality constraints"
        }
      }
    },
    "git_file_info": {
      "type": "object",
      "description": "Git metadata for a file",
      "required": [
        "last_commit",
        "last_author",
        "last_modified",
        "commit_count",
        "contributors"
      ],
      "properties": {
        "last_commit": {
          "type": "string",
          "description": "SHA of the last commit that modified this file",
          "pattern": "^[a-f0-9]{40}$"
        },
        "last_author": {
          "type": "string",
          "description": "Author of the last commit"
        },
        "last_modified": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of the last modification"
        },
        "commit_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of commits that have modified this file"
        },
        "contributors": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of unique contributors to this file"
        }
      }
    },
    "git_symbol_info": {
      "type": "object",
      "description": "Git metadata for a symbol",
      "required": [
        "last_commit",
        "last_author",
        "code_age_days"
      ],
      "properties": {
        "last_commit": {
          "type": "string",
          "description": "SHA of the last commit that modified this symbol",
          "pattern": "^[a-f0-9]{40}$"
        },
        "last_author": {
          "type": "string",
          "description": "Author of the last commit that modified this symbol"
        },
        "code_age_days": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of days since this code was last modified"
        }
      }
    },
    "ref_entry": {
      "type": "object",
      "description": "Documentation reference entry (RFC-0002)",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Documentation URL"
        },
        "sourceId": {
          "type": [
            "string",
            "null"
          ],
          "description": "Approved source ID from config (if applicable)"
        },
        "version": {
          "type": [
            "string",
            "null"
          ],
          "description": "Documentation version (from @acp:ref-version)"
        },
        "section": {
          "type": [
            "string",
            "null"
          ],
          "description": "Section within documentation (from @acp:ref-section)"
        },
        "fetch": {
          "type": "boolean",
          "default": false,
          "description": "Whether AI should fetch this reference (from @acp:ref-fetch)"
        },
        "scope": {
          "type": "string",
          "enum": [
            "file",
            "symbol"
          ],
          "default": "file",
          "description": "Reference scope"
        },
        "symbolName": {
          "type": [
            "string",
            "null"
          ],
          "description": "Symbol name if scope is 'symbol'"
        },
        "line": {
          "type": "integer",
          "minimum": 1,
          "description": "Line number where reference appears"
        }
      }
    },
    "bridge_metadata": {
      "type": "object",
      "description": "Documentation bridging metadata (RFC-0006)",
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether bridging was enabled for this file"
        },
        "detectedStyle": {
          "type": [
            "string",
            "null"
          ],
          "description": "Auto-detected docstring style (google, numpy, sphinx, etc.)"
        },
        "convertedCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of annotations bridged from native docs"
        },
        "mergedCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of annotations merged (native + ACP)"
        },
        "explicitCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of pure ACP annotations"
        },
        "sourceFormats": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Documentation formats found in this file"
        }
      }
    },
    "style_entry": {
      "type": "object",
      "description": "Style guide configuration entry (RFC-0002)",
      "properties": {
        "name": {
          "type": "string",
          "description": "Style guide name or ID"
        },
        "extends": {
          "type": [
            "string",
            "null"
          ],
          "description": "Parent style guide (from @acp:style-extends)"
        },
        "source": {
          "type": [
            "string",
            "null"
          ],
          "description": "Documentation source ID for this style"
        },
        "url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "Direct URL to style guide documentation"
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Specific style rules applied"
        },
        "scope": {
          "type": "string",
          "enum": [
            "file",
            "symbol"
          ],
          "default": "file",
          "description": "Style scope"
        },
        "symbolName": {
          "type": [
            "string",
            "null"
          ],
          "description": "Symbol name if scope is 'symbol'"
        },
        "line": {
          "type": "integer",
          "minimum": 1,
          "description": "Line number where style is declared"
        }
      }
    },
    "behavioral_annotations": {
      "type": "object",
      "description": "Behavioral characteristics of a symbol (RFC-0009)",
      "properties": {
        "pure": {
          "type": "boolean",
          "description": "Function has no side effects (from @acp:pure)"
        },
        "idempotent": {
          "type": "boolean",
          "description": "Function is safe to call multiple times (from @acp:idempotent)"
        },
        "memoized": {
          "type": [
            "boolean",
            "string"
          ],
          "description": "Results are cached; string for duration (from @acp:memoized)"
        },
        "async": {
          "type": "boolean",
          "description": "Function is asynchronous (from @acp:async)"
        },
        "generator": {
          "type": "boolean",
          "description": "Function is a generator (from @acp:generator)"
        },
        "throttled": {
          "type": [
            "string",
            "null"
          ],
          "description": "Rate limit specification (from @acp:throttled)"
        },
        "transactional": {
          "type": "boolean",
          "description": "Function runs in a database transaction (from @acp:transactional)"
        },
        "sideEffects": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of side effects (from @acp:side-effects)"
        }
      }
    },
    "lifecycle_annotations": {
      "type": "object",
      "description": "Lifecycle status of a symbol or file (RFC-0009)",
      "properties": {
        "deprecated": {
          "type": [
            "string",
            "null"
          ],
          "description": "Deprecation message with version/replacement (from @acp:deprecated)"
        },
        "experimental": {
          "type": "boolean",
          "description": "API may change without notice (from @acp:experimental)"
        },
        "beta": {
          "type": "boolean",
          "description": "Feature in beta testing (from @acp:beta)"
        },
        "internal": {
          "type": "boolean",
          "description": "Not intended for external use (from @acp:internal)"
        },
        "publicApi": {
          "type": "boolean",
          "description": "Stable public interface (from @acp:public-api)"
        },
        "since": {
          "type": [
            "string",
            "null"
          ],
          "description": "Version when introduced (from @acp:since)"
        }
      }
    },
    "documentation_annotations": {
      "type": "object",
      "description": "Documentation metadata for a symbol (RFC-0009)",
      "properties": {
        "examples": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Code examples (from @acp:example)"
        },
        "seeAlso": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "References to related symbols (from @acp:see)"
        },
        "links": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "External documentation URLs (from @acp:link)"
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Important notes (from @acp:note)"
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Warnings about usage (from @acp:warning)"
        },
        "todos": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Pending work items (from @acp:todo)"
        }
      }
    },
    "performance_annotations": {
      "type": "object",
      "description": "Performance characteristics of a symbol (RFC-0009)",
      "properties": {
        "complexity": {
          "type": [
            "string",
            "null"
          ],
          "description": "Time complexity notation (from @acp:perf)"
        },
        "memory": {
          "type": [
            "string",
            "null"
          ],
          "description": "Space complexity notation (from @acp:memory)"
        },
        "cached": {
          "type": [
            "string",
            "null"
          ],
          "description": "Caching duration or strategy (from @acp:cached)"
        }
      }
    }
  }
}