codebase-memory-mcp 运行时 Trace 观察模型：为知识图谱设计版本化的运行时观测 Sidecar

本文基于 codebase-memory-mcp 仓库中的架构契约文档 docs/RUNTIME_TRACE_MODEL.md，完整解析其"运行时观察与静态索引分离"的设计：如何为 span、生产者贡献、端点、观察与复合发布定义稳定身份，如何用确定性聚合与原子事务保证多生产者、可重放、可回滚的运行时数据摄入，以及如何通过显式 RUNTIME_CALL overlay 让调用者按需查看运行时证据而不污染静态 CALLS 图。读完后，你将掌握该模型的五层身份体系、六个逻辑表、九步发布事务与全部验收不变量，并能对照仓库现有源码（ingest_traces 处理器、OTLP trace 助手、SQLite 边 upsert）理解契约与现状之间的距离。

一、这是一份"架构契约"，而不是实现

文档开宗明义：它是 architecture contract，推荐一个持久化、版本化的运行时观察 sidecar，其发布物可以与"钉住的静态索引代"（pinned static index generation）一起被读取。核心约束有三条：

• 运行时观察 MUST NOT 修补静态 CALLS 边；
• MUST NOT 为运行时身份伪造静态节点；
• MUST NOT 作为持久边出现在默认图中。

该模型刻意把"运行时观察到的事实"与"从源码推导出的事实"分开：调用者可以显式请求 RUNTIME_CALL overlay，而现有的静态搜索、架构分析与默认 trace 行为保持不变。文档同时强调：这份文档级变更不改变任何版本号——wire 版本、runtime schema 版本、runtime semantic 版本、runtime artifact 版本、静态语义索引版本（保持为 3）与 artifact schema 版本全部不动。

仓库现状与该描述一致：当前 MCP 工具列表中已经暴露了 ingest_traces（见 src/mcp/mcp.c 的工具注册与 src/cli/cli.c 的工具清单），但其处理器只是占位实现——它解析 traces 数组、统计条数，返回 status="accepted"、traces_received 和一条"尚未实现"的备注，并不打开或变更任何存储（见 handle_ingest_traces）。文档中"六个有界实现包"一节明确写着 Implementation remains deferred，即本文契约正是为未来的落地划定的边界。

二、范围与非目标

2.1 契约定义的内容

• 为 span、生产者贡献（producer contribution）、观察（observation）、端点（endpoint）与复合发布（composite publication）定义稳定身份；
• 确定性的摄入、聚合、发布与重放语义；
• 以代（generation）为范围的、从运行时端点到静态符号的解析；
• 不改动所存静态图的可选运行时调用 overlay；
• 并发、重试、冲突、恢复、隐私与基数边界；
• 六个可独立评审、独立交付的有界实现包。

2.2 明确不做的事

文档的 Non-goals 一节逐条列出了被排除的范围，这些"不做"与"做"同样构成契约的一部分：

• 不推断新的静态 CALLS 边，也不改变现有 CALLS 边的置信度；
• 不为运行时专属身份在静态图中创建占位节点；
• 不把运行时边持久化到通用图边表；
• 除非请求 overlay，否则不对现有图工具暴露运行时数据；
• 不定义分布式 tracing 传输、采样策略或 collector 部署；
• 不承诺完整 trace、仅凭时序的因果证明或源码行级归因；
• 不存储任意 span 载荷、headers、请求体、查询串或密钥；
• 不做百分位数平均，也不把某个生产者的 p99 当作可合并的百分位；
• 在未来 mutation API 的版本化契约出现之前，不提供兼容性承诺；
• 不因为增加本文档而改动任何运行时或静态版本号。

三、当前接口面：契约的起点

3.1 ingest_traces 的现有行为

当前 ingest_traces 表面要求 project 和 traces[]；每个 trace 条目允许 caller、callee、count，但这些字段目前并不逐条强制。处理器统计提供的记录数，返回 status="accepted"、traces_received 与一条未实现备注——文档明确指出：这不是被接受的持久 mutation，处理器不打开也不变更 store。这一点可直接在源码中验证：handle_ingest_traces 全程只做 JSON 解析与响应构造，没有任何 store 句柄调用。

3.2 现有 trace 助手面

仓库中已有一组用于 OTLP span 的纯函数助手，位于 src/traces/traces.h 与 src/traces/traces.c，注释标明它们"由 MCP ingest_traces 处理器使用"。文档所称"现有 trace 助手面"正是这组函数，可提取：

• service.name（资源属性，见 cbm_extract_service_name）；
• HTTP method、HTTP path、HTTP status、span kind、duration、URL path；
• p99（cbm_calculate_p99：对原始批次排序后取 0.99 * count 位置的值，空数组返回 0）。

cbm_extract_http_info 识别的属性键包括新旧两套语义约定：http.method / http.request.method、http.route / http.target / url.path、http.status_code，以及从 url.full 中截取路径（第三个 / 之后、? 之前，见 cbm_extract_path_from_url）。这些助手在 tests/test_traces.c 中有对应的纯函数测试（服务名提取、HTTP 信息提取、非 HTTP span 等），文档中"已验证的 span kind 取值"与之完全吻合：

kind 值	含义
1	internal
2	server
3	client

（kind 语义的注释见 traces.h 中 cbm_trace_span_t.kind 字段。）

3.3 静态图的既有规则（为什么不能直接复用）

文档特别说明了静态存储的规则，以解释为什么 sidecar 不能照搬：

• 通用图边按 source、target、type 与 local-name 判别器唯一；
• 通用边 upsert 用 json_patch 合并属性——这一规则对静态图合适，但不是本文档要求的贡献/聚合规则；
• store 已暴露 BEGIN IMMEDIATE、COMMIT、ROLLBACK；
• 静态发布已使用不透明代（opaque generations）与请求作用域的读取。

这些都可以对照仓库源码：边插入使用 ON CONFLICT(source_id, target_id, type, local_name_gen) DO UPDATE SET properties = json_patch(properties, ?5)（见 cbm_store_insert_edge），批量节点写入使用 BEGIN IMMEDIATE / COMMIT / ROLLBACK（见 cbm_store_upsert_node_batch），CALLS 等边类型在 src/store/store.h 中有定义。文档的立场是：json_patch 既不是所需的交换律图并集（map union），也不是冲突检测器，因此 sidecar MUST NOT 复用它做贡献合并。

四、规范性术语

MUST、MUST NOT、SHOULD、MAY 为规范性用语。"Canonical JSON"指 UTF-8 JSON，且满足：固定 schema、对象键按字典序排序、数组保持规定顺序、无无关空白、使用整数而非依赖地区或平台的数字字符串；哈希在这些规范化字节上计算。这条定义是后文所有身份哈希与"字节级一致"不变量的基础。

五、身份体系：五层不可互换的身份

文档最核心的贡献是一套分层身份模型。以下身份各不相同，MUST NOT 互相顶替。

5.1 Trace 与 span 身份

一个 span 在一个生产者命名空间内由五元组标识：

(project, producer_id, producer_epoch, trace_id, span_id)

• trace_id 与 span_id 是不透明字节串，在边界处以统一的规范小写 hex 渲染；
• producer_epoch 是 span 身份的一部分，使生产者在后续 epoch 可以重用 trace/span 标识而不冲突；
• 该五元组标识的是"用于诊断与去重的输入 span"，不是静态节点，也不是聚合。

5.2 生产者贡献身份

每个被接受的批次拥有一个生产者稳定的标识：

contribution_id = H(canonical JSON {
  producer_id,
  producer_epoch,
  source_batch_id
})

• producer_id 命名的是受认证的逻辑生产者，而不是瞬态进程；
• producer_epoch 仅在该生产者有意开启新的身份域时变化；
• source_batch_id 在投递重试间保持稳定；
• 得到的 contribution_id 按 project 限定作用域。

被接受的贡献是不可变的，围绕它有两条重试规则：

1. 以相同的 (project, producer_id, contribution_id) 加相同的规范化载荷哈希重试，是幂等成功，返回原始处置结果；
2. 以不同的规范化字节重试，是冲突，MUST 被拒绝且不产生任何变更；生产者 MUST NOT 复用其他生产者的命名空间，服务端也 MUST NOT 悄悄铸造一个替代 ID 把冲突变成第二个贡献。

载荷哈希覆盖的是"规范化的、白名单内的贡献 map"加上其钉住的 wire 版本与 runtime semantic 版本字段；不覆盖原始信封顺序、不受支持字段、被丢弃字段或原始载荷字节。

5.3 端点身份

每个端点都有显式 tag 和规范化 key，共三类：

1. symbol：源自源码的符号引用 (project, qualified_name)。这个稳定的端点身份刻意不含静态代；另一条解析记录把它映射到某个具名静态代与 resolver 版本内。后续代MUST 重新解析，MUST NOT 从旧代继承节点标识。
2. runtime：仅运行时的端点，来自白名单协议身份（例如规范化服务名 + 归一化 HTTP 路由与方法）。它只存储在 sidecar 中，永不创建静态节点。
3. unknown：不透明、带作用域的端点，用于白名单证据既不能识别 symbol 也不能识别运行时服务端点时。unknown key 只在文档规定的作用域内（例如 producer + trace）保持稳定，MUST NOT 把互不相关的缺失值塌缩成一个全局端点。

端点规范化由 runtime_semantic_version 版本化：所有字符串做 Unicode 规范化，方法与协议 token 使用规定的规范大小写，缺失值与空值不同；原始 URL 的 query、fragment 与凭据一律排除。

5.4 观察身份

一个观察描述一个有向的运行时视角，而不是"一次投递"。其规范 key 为：

observation_key = H(canonical JSON {
  runtime_semantic_version,
  project,
  protocol,
  perspective,
  source_endpoint_key,
  target_endpoint_key,
  operation_key
})

该 key 排除计数器、时间戳、duration 汇总、状态汇总、贡献 ID 与静态库行 ID。operation_key 只包含版本化的白名单操作身份（例如规范 HTTP 方法 + 归一化路由模板）。结果是：来自多个生产者的相同观察会收敛，而语义上不同方向或不同操作保持区分。

5.5 复合发布身份

读者可见的快照由原子对标识：

{ static_generation, runtime_generation }

该 pair 是 head 身份，但两半是相互独立的不可变发布。runtime generation 标识运行时贡献与聚合，不内嵌静态代；代范围的符号解析与 overlay 投影由"pair + resolver 版本"作 key。请求正在使用该 pair 时，两半均不得被悄悄推进。

六、协议与视角映射

摄入阶段只解析并规范化版本化的、白名单内的 span 字段进入贡献，然后从证据推导视角；原始 span 载荷不被持久保留。HTTP mapper 复用的是文档 3.2 节描述的现有助手（服务名、HTTP 方法、HTTP path 或 URL path、status、span-kind、duration）。路由字段在源提供模板时按路由模板规范化；MUST NOT 靠猜测把高基数的原始 URL 路径提升为模板。

对三种已验证的 span kind，映射规则如下：

• client（3）：代表一次出站尝试。source 是（在可得时）解析出的本地 symbol，否则是带 tag 的本地 runtime 或带作用域的 unknown 端点；target 是白名单远端服务/HTTP 端点或带作用域的 unknown 端点。perspective token 为 outbound。
• server（2）：代表一次入站处理尝试。source 是白名单对端/runtime 端点或带作用域的 unknown 端点；target 是（在可得时）解析出的本地 handler，否则是本地服务/HTTP runtime 端点。perspective token 为 inbound。
• internal（1）：代表本地工作。只有当显式的 parent/child 证据提供两个端点时，才产生有向调用投影；否则观察保持为可查询的"内部活动"，不成为 RUNTIME_CALL。perspective token 为 internal。

不受支持或缺失的 span kind：若策略允许，仅作为规范化的、白名单内的非调用观察元数据保留；不受支持字段与原始载荷字节被丢弃；MUST NOT 猜测归入三种视角之一。status 与 duration 只参与汇总，永不参与观察身份。

符号解析是尽力而为的、代范围的（best-effort, generation-scoped）：歧义匹配保持 runtime 或 unknown 标签。解析 MUST fail closed——不得凭文件名子串、短名巧合、时序或插入顺序来选一个 symbol。

七、Sidecar 模型：六个逻辑关系

持久 sidecar 在概念上与静态图存储分离（即使实现初期共享同一个数据库文件）。它包含以下逻辑表，且没有一张是静态图的节点表或边表；实现 MUST NOT 复用通用 json_patch 边 upsert 做贡献合并。

7.1 runtime_endpoints

存储端点 tag、规范端点 key 与规范的白名单身份。对 symbol 端点，持久身份包含 project + qualified name，不含静态代。代与静态库行 ID 只属于解析记录或缓存，不属于持久端点身份。

7.2 runtime_contributions

存储 project、producer ID、contribution ID、规范化载荷哈希、摄入状态与不可变的规范化贡献元数据。状态至少包括 staged 与 finalized；被中止的事务不留下任何可见状态。

7.3 runtime_observation_contributions

把 (contribution_id, observation_key) 映射到该贡献的规范化汇总。map 条目在 finalization 后不可变；替换它需要新的贡献身份。

7.4 runtime_aggregates

存储每个 observation key 与 runtime generation 下，已 finalized 贡献 map 条目的确定性 fold。它是派生状态，可从 finalized 贡献重建。

7.5 runtime_resolutions

把稳定的 runtime 或 unknown 端点 key 映射到可选的稳定 SymbolEndpoint (project, qualified_name) 及其当前静态节点/缓存结果、未解析结果或歧义结果。每条记录以 project、runtime generation、static generation、稳定端点 key 与 resolver version 作 key。解析记录是派生缓存而非端点或观察身份；某一静态代的记录 MUST NOT 被复用于另一个代。

7.6 runtime_publications

存储与静态代独立的不可变 runtime generations。另有一个按 project 的原子复合 head，把当前 runtime generation 与当前 static generation 配对。发布元数据包含相关运行时版本；复合 head 记录用于兼容性检查的静态索引/artifact 版本。

八、确定性聚合

在存储不可变汇总之前，一个贡献按以下顺序被确定性规范化：

1. 只规范化白名单字段，并计算精确 span 身份 (project, producer_id, producer_epoch, trace_id, span_id)；
2. 对 span 身份相同且规范化字节相同的记录去重；
3. 若同一 span 身份出现不同规范化字节，拒绝整个贡献；
4. 把剩余唯一规范化记录按 observation_key 分组；
5. 在"按 key 的精确 span 去重/集合并"提供幂等性之后，对唯一规范化 span map 用结合且交换的精确加法 fold 整型计数、duration 总和、固定状态桶与固定 schema 的直方图 bin；
6. 在哈希或存储前，排序 key 并做规范序列化。

规范化贡献 map 及其不可变汇总，对同一唯一规范化 span 集的任何输入顺序与 worker 分区，MUST 字节级一致；被丢弃或不受支持的字段不能改变载荷哈希。

对每个观察，聚合是按贡献身份为 key 的 map 并集：

aggregate(observation) = fold(sorted union {
  contribution_id -> canonical contribution summary
})

相同 key/value 条目的并集是幂等的；同一 key 下值不同是冲突，而不是"胜者选择"。map 并集结合且交换；按贡献 ID 排序后再序列化，使结果字节独立于生产者、重试、事务或 worker 顺序。

规范贡献汇总 MAY 包含：整型计数、固定单位的整型 duration 总和、固定 schema 状态桶、以及由 runtime_semantic_version 钉住编码的可合并 duration 分布。聚合总量是对贡献 map 的精确整型和；派生展示值在 fold 之后计算。

百分位数不可加。 一批数据的 p99 MUST NOT 被平均、加权平均或挑选为聚合 p99。现有 p99 助手（即 cbm_calculate_p99）可以为诊断汇总单个原始批次，但跨贡献发布的 p99 需要一个版本化的可合并分布（例如固定直方图边界）；没有这样的分布时，聚合 p99 就不可用——这是契约明文规定的"宁可不可用，也不许算错"。

规范聚合 JSON 对同一 finalized 贡献集的任何排列与任何结合方式 MUST 字节级一致。

九、摄入与发布事务

完整 wire 解析、规范化、载荷哈希，以及一切不依赖可变项目状态的校验，都在获取发布锁之前完成。发布由一把共享的按-project 发布锁串行化，静态与运行时发布者共用这把锁；实现 MUST NOT 引入允许复合 head 任一半丢失更新的独立 runtime 锁。

在该锁内，运行时发布者依次执行九步：

1. 以 BEGIN IMMEDIATE 开始写事务；
2. 读取并钉住当前复合 head，校验兼容版本；
3. 执行依赖状态的授权、配额、生产者身份、去重、贡献冲突与期望 head 检查；
4. stage 所有端点、不可变贡献 map 条目与重建的聚合；
5. 分配一个独立于钉住静态代的不透明 runtime generation；
6. 持久地 finalize 本次发布中的每个贡献；
7. 写入不可变的 runtime publication，并只原子地变更复合 head 的运行时半，保留其钉住的静态代；
8. 以 COMMIT 提交全部变更；
9. 释放按-project 发布锁。

commit 前任何校验或写失败都走 ROLLBACK——不存在可见的部分贡献、部分聚合、代或 head。finalization 与 head 推进在同一事务内，因此成功响应只在持久 commit 之后发出。

静态发布遵循同样的锁纪律，原子地只变更复合 head 的静态半，保留其钉住的 runtime generation；仅仅因为源码被重新索引，不创建新的 runtime generation。新 {static_generation, runtime_generation} pair 下的解析记录按"pair + resolver version" key 重新计算或物化；旧静态代的记录永不被当作新代的解析结果。

十、读者契约

• 选择运行时数据的请求在请求开始时钉住一个复合 head；该请求内的每一页、端点解析、聚合与 overlay 边都从这对代读取。
• 默认请求只钉住现有的静态请求作用域，不为 overlay 付费也不暴露它。
• 分页游标编码 project、复合 head、查询形状、overlay 模式与 runtime semantic version。若当前 head 不同，后续使用该游标的请求返回 stale-cursor 错误——永不在混合代上续读。
• 读者 MAY 显式请求仍被保留的历史复合 head；缺失或已被 GC 的 head 显式失败。

十一、RUNTIME_CALL overlay

运行时调用投影是一个显式读取选项，呈现派生自单一钉住 runtime generation 的有向 overlay 边。这些边：

• 使用不同的类型 RUNTIME_CALL；
• 携带端点 tag，让调用者区分 symbol、runtime、unknown 端；
• 包含确定性的聚合汇总与复合 head 身份；
• 永不修改、替换、增信或抑制静态 CALLS 边；
• 除非调用者请求 overlay，否则不出现在现有搜索、架构与默认 trace 响应中；
• 在复合发布的任一半变化时重新生成。

若投影出的运行时调用具有 symbol 端点，它在钉住的静态代内引用其 qualified-name 身份；仅运行时与 unknown 端点保持为 sidecar 对象，不被伪造为图节点。

十二、版本边界

兼容性被刻意切分为六个独立版本：

版本	覆盖范围
wire_version	请求/响应信封、字段编码、重试结果
runtime_schema_version	sidecar 表、索引与迁移兼容性
runtime_semantic_version	规范端点/观察 key、映射与聚合语义
runtime_artifact_version	导出/导入的 sidecar artifact 布局
static_semantic_index_version	源自代码的图语义
static_artifact_schema_version	静态 artifact 表示

一次变更只 bump 它实际改动的边界。运行时语义变更可以在不改变静态语义索引版本的情况下使 runtime generation 失效；纯存储迁移可以改变 runtime schema 版本而不改变观察身份。导入在任何 mutation 之前拒绝不兼容的 artifact 版本。本文档不改动其中任何一个。

十三、安全、隐私与基数

• 摄入是 project 级授权、生产者级认证的。producer ID、contribution ID 与 project 作用域由服务端校验；调用者提供的 project 或 producer 字段不授予任何访问权。读取对运行时与静态数据施加同样的 project 授权。
• 只有白名单属性进入规范身份或汇总。凭据、授权数据、cookie、请求/响应体、query 串、fragment、任意 baggage 与原始异常文本在持久化之前被拒绝或丢弃。日志与错误使用不透明 ID 与计数，而不是被拒的载荷。
• 服务强制有界的请求字节数、记录数、端点数、观察数、属性长度、路由模板段数、状态桶数与贡献 map 增长。原始 URL 路径不被接受为无界路由标签；unknown 端点带作用域，既避免意外的全局塌缩，也避免攻击者控制的全局基数。配额与保留按 project 与 producer 施加；限流失败是 all-or-nothing，除非未来 wire 版本显式定义，否则不发布被截断的贡献。

十四、失败与恢复矩阵

条件	必需处置	可见状态
相同 contribution ID、相同载荷哈希	幂等成功，返回先前结果	不变
相同 contribution ID、不同载荷哈希	冲突，拒绝整个请求	不变
未授权的 project 或 producer	stage 前拒绝	不变
无效/不受支持的 wire 或 semantic 版本	stage 前拒绝	不变
无效端点、属性或基数超限	拒绝整个贡献	不变
符号解析歧义	保持 runtime/unknown 标签，不猜测	仅有效的 sidecar 观察
客户端提供的期望复合 head 与锁下读到的 head 不同	按 stale 拒绝；从新读到的 head 重试	不变
staging 或聚合期间失败	ROLLBACK	无部分状态
commit 前崩溃	数据库恢复回滚事务	保留先前 head
commit 成功但响应丢失	生产者重试幂等解决	一个 finalized 贡献
派生聚合缺失或损坏	发布前从 finalized 贡献 map 重建	保留先前有效 head
游标引用不同或已删除的 head	返回 stale/missing cursor 错误	无混合代读取
不受支持的 span kind	仅保留规范化、白名单内的非调用观察元数据；丢弃不受支持字段与原始载荷字节	无猜测的调用 overlay
无可合并 duration 分布	发布计数/总和；报告 p99 不可用	无平均 p99

十五、备选方案与取舍

文档逐一评估并拒绝了四个备选，最终选定 sidecar 方案：

1. 修补静态 CALLS 边：好处是现有图查询无需 overlay 即可见运行时证据；代价是混淆观察与源码推导的语义、让被采样或恶意的遥测改变静态图、无法诚实地表示仅运行时端点、把运行时保留与静态索引耦合、回滚与溯源含糊。被拒绝。
2. 为运行时服务与未知对端伪造静态节点：好处是所有端点都符合现有节点/边形状；代价是伪造节点看起来像源码派生、身份不稳定、高基数、与未来符号解析冲突、污染架构/搜索结果。被拒绝。
3. 在默认图中存持久运行时边：好处是通用唯一性与 json_patch upsert 现成可用（正对应 src/store/store.c 的现有实现）；代价是通用唯一性没有不可变的生产者贡献维度，json_patch 既非所需交换律 map union 也非冲突检测器，默认读者会意外地混合代与数据类别。被拒绝。
4. 运行时观察完全临时（ephemeral）：好处是 schema、保留与迁移负担最小；代价是重启间无法幂等重试、结果不可复现不可分页、多生产者聚合不稳定、读者无法钉住一致的复合发布。作为主模型被拒绝，但临时预校验仍有价值。
5. 持久化版本化 sidecar + 可选 overlay（选定）：保留静态语义、给仅运行时端点诚实的身份、支持确定性重放与聚合、隔离保留与授权、提供跨代原子读取。代价是新增 schema 与版本边界、共享发布锁、端点解析、聚合重建、overlay 感知的 API 与显式运维限制。文档明确接受这些成本，因为它们让溯源、并发、故障恢复与兼容性可测试而非隐含。

十六、六个有界实现包

实现保持延迟状态；以下包刻意有序且受限，每个包都需要自己的 reproduce-first 测试与评审：

1. 版本化 wire 校验与规范化：认证生产者身份与 epoch、contribution ID、精确 span 身份去重、冲突重复拒绝、规范贡献 map 与载荷哈希、白名单 HTTP/span 映射、限制、dry-run 校验。不改 store。
2. Sidecar schema 与不可变贡献：runtime schema 迁移、端点、贡献记录、观察-贡献 map、幂等重试、冲突拒绝、事务回滚。无发布 head 或 overlay。
3. 确定性聚合：贡献内规范分组、按 key 的精确 span 幂等集合并/去重、结合交换的精确整型/状态/直方图加法、跨贡献 map-union fold、固定可合并 duration 分布、输入/worker/合并顺序排列测试、重建校验、显式的 p99 不可用行为。
4. 代范围的解析与发布：共享按-project 锁、独立 runtime generation 分配、持久 finalization、pair+version 解析记录、原子复合 head 更新（保留另一半）、崩溃/重试恢复测试。
5. 钉住读取与 RUNTIME_CALL overlay：可选查询、带 tag 端点、请求作用域复合 pin、stale cursor、历史 head 处理，以及"默认静态工具保持逐字节不变"的证明。
6. Artifact、保留与运维强化：版本化 runtime artifact 导入/导出、配额/保留策略、授权审计、损坏重建、迁移/回滚测试、指标、多生产者并发测试。

任何包不得悄悄吞并后一个包的公共表面或持久化模型。

十七、验收不变量

实现只有在以下全部成立时才可接受：

1. 同一源码输入下，无论运行时摄入开或关，静态节点与 CALLS 边逐字节一致；
2. 现有搜索、架构与默认 trace 响应不含运行时数据；
3. 运行时数据仅通过显式的、版本化的 overlay 请求出现；
4. 相同生产者贡献 + 相同载荷在重试与重启间幂等；该身份下不同载荷是无变更冲突；
5. 对同一唯一规范化 span 集，规范化贡献与聚合字节在一切输入、投递、worker 与合并顺序下一致（包括相同重复重放）；冲突的重复 span 身份拒绝整个贡献且不变更；
6. 聚合 p99 只从钉住的可合并分布派生，否则不可用；生产者 p99 永不被平均；
7. 符号解析基于 qualified name、代范围、歧义时 fail-closed；runtime 与 unknown 端点永不伪造静态节点；
8. runtime generation 状态包含其全部 finalized 贡献、端点与聚合，读者可见性要求独立的原子复合 head 更新；事务要么同时暴露完整代与 head 更新，要么两者都不暴露；
9. 每次 overlay 读取与翻页使用同一不可变 {static_generation, runtime_generation} pair；stale cursor 显式失败；
10. 静态与运行时发布经同一按-project 锁串行化；每个发布者只变更复合 head 自己那半、保留另一半；符号解析记录永不被跨静态代或 resolver 版本复用；
11. 不受支持的 span kind、缺失身份与限额违规永不变成猜测的调用或部分发布；
12. 授权、隐私过滤、配额与保留在数据变得持久或读者可见之前被强制执行；
13. wire、runtime schema、runtime semantic、runtime artifact、static semantic 与 static artifact 版本可按各自边界独立变化；
14. 仅文档级的采用使全部六个版本值与全部运行时行为保持不变。

十八、对照现状：契约与仓库之间还差什么

从源码结构看，仓库当前的 trace 能力由三块拼成：ingest_traces 的占位处理器（src/mcp/mcp.c）、OTLP 纯函数助手（src/traces/traces.c）与助手测试（tests/test_traces.c，其文件头注明完整 MCP 管线的集成测试被推迟）。静态存储侧已具备 sidecar 事务所需的原语：BEGIN IMMEDIATE / COMMIT / ROLLBACK（见 src/store/store.c）与通用边 upsert（src/store/store.c），但文档明确要求 sidecar 不得复用后者的 json_patch 合并语义。

这份契约的价值在于：它把"运行时证据进入知识图谱"这件事的全部难点——身份稳定性、幂等重试、冲突检测、多生产者聚合的字节级确定性、百分位数的正确合并、代范围解析与原子复合读取——提前固化成可测试的不变量与失败矩阵，并拆成六个可独立交付的包。对后续维护者与贡献者而言，docs/RUNTIME_TRACE_MODEL.md 是任何运行时 trace 实现都必须逐条对照的合同文本，而 tests/test_traces.c 与 src/traces/traces.h 则是其现有地基的直接入口。