Provenance 证据链

专题结论

Semantica 的来源追踪不是给实体附加一个来源 URL，而是把实体、来源、活动、Agent、版本、派生、作废和摘要校验组织成可查询记录。该模型与“证据从哪里来、谁处理过、为何发生变化”的需求高度匹配。

建议：优先参照数据模型并隔离验证 SQLite 实现；生产接入必须强制写入、统一事务、外部锚定并限制物理修改。

1. 模型与管理边界

原始调用链

以图构建接入为例，GraphBuilderWithProvenance.build()（包装底层图构建并遍历结果追加来源的方法）调用 ProvenanceManager.track_entity()（在来源事务中创建或版本化实体记录的方法）；管理器再通过 ProvenanceManager._save_entry()（补齐序列与哈希链后写入存储的方法）进入 ProvenanceStorage.store()（来源存储抽象的写入接口）。输入是图构建结果及来源上下文，输出是图和独立来源记录；包装器被绕过时，这条链不会自动执行。

2. 版本、派生与作废语义

track_entity()（创建实体来源记录并处理版本关系的方法，约第 268 行）会保存来源、活动、Agent 和版本关系。模型明确区分两个重要字段：

• previous_version_id（指向同一实体上一版本的重要字段）表达版本演进；
• derived_from_id（指向语义派生来源的重要字段）表达新实体由其他实体计算或抽取得到。

两者不能合并：版本演进回答“它以前是什么”，语义派生回答“它由什么产生”。

invalidate()（追加实体作废信息而保留历史的方法，约第 1032 行）适合审计和撤回传播。生产设计应把作废视为新事件，而不是更新或删除旧行；同时要求作废理由、操作者、审批、时间和受影响下游对象。

3. 血缘查询与审计

4. 存储与完整性边界

ProvenanceStorage（定义存储、读取、血缘、事务和链头能力的抽象接口，约第 35 行）有内存与 SQLite 两种实现。

SQLiteStorage（把来源记录、版本和链信息持久化到 SQLite 的存储实现，约第 391 行）适合单机 PoC 和小规模审计，但不等同于分布式不可变账本。它的事务边界只覆盖自身存储；若业务数据库先成功而来源写入失败，仍会出现证据缺口。

compute_checksum()（对规范化来源记录计算 SHA-256 摘要的函数，约第 27 行）和 verify_checksum()（验证记录摘要是否匹配的函数，约第 119 行）能够发现意外修改。由于密钥签名、外部可信时间戳和外部锚点不在该实现中，拥有完全写权限的人仍可能重写数据后重算链。

原项目关键片段——ProvenanceManager.verify_chain()（检查来源记录摘要和序列断链的方法片段）。

固定提交片段：来源链断链检查 原项目关键片段

broken_links: List[Dict[str, Any]] = []
expected_previous: Optional[str] = None
expected_sequence: Optional[int] = None
for entry in entries:
    if not verify_checksum(entry):
        broken_links.append({
            "entity_id": entry.entity_id,
            "sequence_id": entry.sequence_id,
            "reason": "checksum_mismatch",
        })
    else:
        sequence_gap = (
            expected_sequence is not None
            and entry.sequence_id != expected_sequence + 1
        )
        checksum_break = entry.previous_checksum != expected_previous
        if sequence_gap or checksum_break:
            broken_links.append({
                "entity_id": entry.entity_id,
                "sequence_id": entry.sequence_id,
                "reason": "chain_break",
                "expected_previous_checksum": expected_previous,
                "actual_previous_checksum": entry.previous_checksum,
                "expected_sequence_id": (
                    expected_sequence + 1 if expected_sequence is not None else None
                ),
            })

这段实现同时检查条目自身摘要、全局序列连续性和前序摘要连接，支持“能发现意外修改或删除”的事实判断。可借鉴的是把多种断链信号合并为结构化结果；不能照搬的是把无密钥的本地哈希链解释为抵抗数据库完全写权限攻击者的不可否认证据。

生产增强建议：

• 业务事件与来源事件在同一事务中写 outbox；
• 审计存储使用追加权限模型，普通服务账号不能更新历史；
• 批次摘要签名后锚定到独立审计系统或可信时间戳服务；
• 定期离线校验链头、版本连续性和来源对象可访问性；
• 数据保留、删除请求与审计留存规则由合规策略明确协调。

5. 与主链路的接入现状

Semantica 通过包装器把来源能力接入不同子系统：

• GraphBuilderWithProvenance（包装图构建并记录实体与关系来源的组件，约第 62 行）；
• PipelineWithProvenance（包装流水线运行并记录输入输出来源的组件，约第 32 行）；
• ContextManagerWithProvenance（包装上下文写入并追加来源记录的组件，约第 19 行）；
• ReasoningEngineWithProvenance（包装推理运行并记录前提和结果来源的组件，约第 21 行）。

这种装饰器式接入便于渐进采用，却意味着调用方可以绕过包装器。后两个包装器还导入仓库中不存在的底层模块，因此不能把当前端到端来源链视为已打通。

6. 抽象代码示例

下面是伪代码（不是原项目原样代码），展示生产系统应如何把业务写入与来源事件绑定：

with business_transaction() as tx:
    fact_version = fact_repository.append(new_fact, tx=tx)
    outbox.append(
        event_type="provenance.recorded",
        entity_id=fact_version.id,
        source_ids=source_ids,
        activity_id=activity_id,
        agent_id=agent_id,
        tx=tx,
    )

audit_worker.persist_and_anchor(outbox_event)

关键点是：来源写入不是“尽力而为”的日志，而是业务提交不可绕过的组成部分。

7. 可借鉴的交互设计

1. 实体详情固定展示来源数量、最新来源、处理活动、责任 Agent、版本和完整性状态。
2. 来源泳道把 Agent、Activity、Entity 分层，并允许从任意节点追上游或下游。
3. 每个事实字段可直接跳到来源文件、页码、时间片或数据行，而不是只链接文档首页。
4. 作废前展示所有后代事实、推理结果和决策，支持批量创建重审任务。
5. 完整性状态区分“摘要匹配”“外部锚定成功”“签名有效”，避免一个绿色图标掩盖不同保证等级。

8. 引入或参照结论

9. 源码依据

返回 Semantica 项目分析主报告