CodeGraph 从调用方提供的快照材料中提取代码事实，由语言规则建立组织与绑定， 原子发布携带来源位置、关系证据和局部覆盖信息的代码图。 调用方负责获取材料，并将查询结果解释为评审、影响分析或执行决策。
| 层次 | 责任 |
|---|---|
| CodeGraph | 代码身份、声明与关系、来源证据、局部诊断、通用图查询 |
| 分析消费者（如 repocli） | 变化入口、探索范围、影响传播、路径排序、受影响文件与候选测试 |
| 执行消费者（如 devloop） | 按项目契约选择并执行检查，处理分析失败时的回退 |
评审工具也可查询声明、关系与 marker，自行组织 review unit、上下文和预算。 不同消费者可以选择不同范围与遍历方向，共用可追溯的原始事实。
Document 表达一份输入材料：逻辑路径对应源码内容或 gitlink 固定 commit。 Extractor 负责有界解析并产出 Facts，Facts 保存脱离 AST 的完整单文件材料，包括词法线索、 语言专有证据、候选关系与局部诊断。Facts 的身份由路径和材料内容决定，可以跨快照复用。
Builder 接纳 Facts 和快照专属 ResolutionContext，执行组织、绑定与解析，原子发布只读 Graph。 ResolutionContext 承载调用方已获得的模块根和导入路径证据，候选只与本轮材料集合连接， 其精度限制后续绑定。获取文件、理解仓库配置与选择探索范围属于调用方。
Graph 是一次成功构建的节点、关系和诊断读模型。Builder 补充材料后产生新 Graph， 已返回的结果保持不变。类型化访问直接读取图事实，Cypher 索引在首次查询时建立。 兼容入口 New 和包级 Build 通过独立 Builder 提供逐批补料接口。
每份材料都有 Document 节点身份；没有解析能力时仍保留材料及其诊断。 因此，局部图中没有某条关系不能证明仓库中不存在关联。 材料身份、接纳与不展开边界见 Document 契约。
Node.Kind 使用 Document、Package、Module、Class、Function 等具体代码类别，并映射为 Cypher 标签。 Symbol 表达代码声明，Namespace 表达名称与成员组织；二者是可重叠的逻辑角色。 例如 Class 同时承担声明与成员组织，图中仍是同一个 Class 节点。 语言显式 namespace 声明使用具体 Namespace Kind。
declares 记录 Document 对声明或组织的源码贡献；contains 记录直接语义归属。
两种关系分别保存来源与成员组织，使跨文件包、接收者方法和嵌套组织共用同一模型。
Namespace 是实体的成员组织视图，不分配第二份身份。身份和嵌套规则见 命名空间组织。
节点以源码侧身份寻址，图引擎内部数字 ID 不暴露为持久化身份。 相同快照与输入应得到可复现身份；跨版本重命名匹配由消费者另行判断。
Scope 表达源码中的可见范围及查找父级；Binding 表达该范围引入的名称、声明来源与类型线索。 Namespace 的成员组织与词法可见性各有含义，contains 不决定名称查找顺序。 BuildScope 表达本轮构建材料集合。
语言实现登记可见性与遮蔽规则，共享索引供引用、调用和接收者线索使用。 保留未知局部绑定可以阻止错误的同名回退；未证明的动态行为以局部缺口表达。
Relation 表达一次有向代码关系，种类包括 declares、contains、imports、references、calls、extends、implements。 身份由 Source、Target、Kind 与发生位置组成，位置使用路径及字节范围。 相同端点之间的不同关系或不同调用位置保留为独立边，也允许自递归。
Evidence 记录建立关系的依据：Basis 说明推导规则，Confidence 说明证据强度， 可选 Location 指向支撑语法。同一次发生的多条依据合并、去重并确定性排序，避免最后写入覆盖证据。
| Confidence | 证据语义 |
|---|---|
exact |
在给定材料与已支持的静态语义下，绑定或结构关系已确定 |
scoped |
已有词法绑定、导入、接收者或类型等实际约束，但尚不足以确定绑定 |
name_only |
主要依据名称匹配，未证明名称在该位置的绑定 |
heuristic |
依赖约定、模式或不完整的结构相似性 |
精度顺序为 heuristic < name_only < scoped < exact，不按字符串排序。
目标数量与精度相互独立：只有一个同名目标也不能自动升级；多个合理目标继续保留。
Basis 描述“如何得到这条证据”，Confidence 描述“这条证据能证明到什么程度”；
同一种 Basis 可以因材料和约束不同而得到不同档位，不建立 Basis 到 Confidence 的固定映射表。
Relation.Confidence 由 Evidence[].Confidence 推导，不是另一份独立判断。
- 同一关系的独立证据取最高档，并保留全部 Evidence；重复或更多弱证据不会投票升级。
- 一条证据依赖多个必要推导环节时，取这些环节中的最低档；例如导入、转导出、继承查找不能丢失上游的不确定性。
- Confidence 不参与关系身份，调整分级不会制造另一条同位置关系。
- 同一调用或引用位置出现不同目标的 exact 断言时，保留关系并报告
conflicting_binding；较低档的备选目标不构成该冲突。
例如，同一调用关系有 name_only 的名称证据和 scoped 的接收者证据，关系投影为 scoped； 导入为 scoped、转导出为 exact 的必要推导链，最终证据仍为 scoped。 无法提出目标的引用保留诊断，不虚构关系端点。
confidence 不是概率，exact 也不承诺运行时行为或完整编译器类型检查。 Path 与 Subgraph 保留原始关系及其证据；跨关系的多跳衰减、影响阈值、筛选与排序由消费者决定。
spec、case、rule、link、doc 是声明上的结构化意图标记，保留内容及源码位置。 图提供这些代码事实，消费者决定如何用于评审或检查。
构建或查询的执行失败通过 error 报告；BuildReport 描述已发布范围及局部信息缺口。 诊断标明涉及的材料、声明、关系、上下文或资源，并保留可获得的源码位置。 局部缺口不否定无关事实，也不自动触发消费者的全量回退。
- 调用方将 Document 交给 Extractor，获得可独立复用的 Facts。
- 消费者读取 Facts 探索依赖，把选定材料与 ResolutionContext 交给 Builder。
- Organize 提供实体与组织贡献；全部实体登记后建立成员索引。
- Bind 建立导入、类型及接收者归属。所有语言完成 Bind 后，Resolve 才解析引用与调用。
- Builder 校验端点和预算，原子发布 Graph；构建失败保留上一次成功结果。
- 消费者通过类型化访问或按需建立的 Cypher 索引查询，结合覆盖信息形成业务结果。
阶段屏障使跨文件基类和接收者能在调用解析前进入索引，避免输入顺序决定绑定结果。 具体接口、共享算法与语言接入见 语言构建流程。
根包直接定义 Document、Facts、Extractor、Builder、Graph 及公共图值。Extractor 拥有提取 与缓存，Builder 拥有接纳、预算和发布，Graph 拥有不可变结果、类型化访问及延迟查询索引。 异步补料由根包内独立的私有 session 协调，公共对象与自己的状态和行为在同一包维护。
根包调用内部机制，并负责分析材料与公共值、图值与引擎引用之间的转换。internal/graphstore 封装 GoGraph、查询限制及引擎值转换；内部包不依赖根包，也不持有公共 Graph 的生命周期。
internal/analysis 定义分析事实及阶段契约；pipeline 根据语言注册信息编排阶段，语言适配器 提供语义规则。AST 和引擎对象留在适配层，公共 API 返回独立的领域值。
解析的复用单位是 Facts，关系绑定的单位是 Builder 当前接纳的材料集合。 同一份 Facts 可以进入多个快照；新增、删除或重命名依赖、改变模块配置，都需要重新绑定。 Facts 的只读材料与公开检查视图分离，修改视图不会改变后续构图输入。
Extractor 限制并发、单文件字节和解析时间，可选择调用方持有的有界 ExtractionCache。 显式传递 Facts 不依赖缓存命中。缓存身份包含路径、材料类型和内容，容量不足时照常提取。 共享 Extractor 使多个快照服从同一解析并发上限。
Builder 按材料规模和关系预算接纳与构图，整个构建成功后才替换 Result。 输入上下文取消和执行失败阻止发布；消费者可通过 AddFailure 保留单文件解析缺口。 兼容的异步补料接口按需创建独立的私有 session，由它协调解析任务与待发布批次；普通 Builder 只持有已接纳的材料与构图状态。Wait 只等待既有工作，取消等待不会取消构建。 取消与接纳的精确契约见 使用指南。
gotreesitter 提供语法解析与事实提取，GoGraph 提供进程内属性图及 Cypher，pond 提供有界任务调度。 CodeGraph 拥有它们之间的代码语义契约，依赖已有能力完成基础工作。
图存储采用有向多重图，按独立 edge handle 写入属性，保留相同端点的不同关系发生。 公开查询只读，节点、关系与路径还原为 CodeGraph 领域值；访问器返回独立副本，防止调用方修改图状态。 Marker 与 Evidence 同时提供可过滤属性和完整结构投影，由往返契约验证一致性。
构建预算限制材料及事实规模，查询预算限制时间、路径深度和结果规模。 LIMIT 不能独自限制遍历工作量；预算失败不能伪装成完整的空结果。 提取并发由 Extractor 限制；共享一个 Extractor 可统一多快照的解析容量。
grammar 可用、声明可提取、引用可解析是不同能力层次。语言注册项同时声明能力与限制， 仅具备 outline 的语言保留声明并报告关系覆盖缺口。具体支持范围见 语言能力。
库契约测试验证事实、身份、证据、查询与发布不变量；固定语料使用独立参照测量语义覆盖。 消费者的影响结论与执行行为由其自身回归验证，大仓性能需要结合实际材料与消费流程测量。 评测方法见 真实仓库评测，历史测量保存在 tests/corpus。
依赖与工具链版本以 go.mod 为准；Cypher 支持范围以所锁定依赖及契约测试为准， 不承诺完整 Neo4j 兼容。