证据链

Marivo 是纯 Python 分析库。它不调用 LLM，不替智能体判断业务含义，也不替智能体选择下一步。证据引擎的职责，是让确定性的操作结果更容易读取和审计。

证据模型

每个已提交的操作结果只经过一条路径：

artifact -> typed findings -> bounded artifact digest

Finding 是从单个产物中提取出的类型化结果元素。ArtifactDigest 是面向当前一步读取的、按操作定义的证据项投影。跨产物综合、业务判断与下一步选择始终由智能体负责。

摘要不会把贡献升级为因果，把相关升级为效果，把候选升级为已确认异常，把统计检验升级为业务重要性，也不会把预测升级为已发生事实。boundaries 会明确记录操作没有支持的推断。

读取当前结果

使用唯一的结构化路径：

result = session.compare(current, baseline)

print(result.evidence_status)
digest = result.evidence_digest
result.show()

evidence_status 取值为 complete、partial 或 unavailable。 evidence_digest 是不可变的 commit-时间 ArtifactDigest；无法生成时为 None。 show() 在数据预览之前渲染的就是同一个有界摘要。

一个摘要最多保留 5 个类型化项和 3 个推断边界。omissions 记录被省略的数量， fallback 说明精确证据项与原始行是否可用。有界摘要中没有出现，不代表产物中不存在。

主要项与操作语义严格对应：

操作	摘要项	含义
`observe`	`ObservationFact`	观测值或分布摘要
`compare`	`ChangeFact`	代数变化
`attribute`	`ContributionFact`	代数贡献，不是因果
`correlate`	`AssociationFact`	估计的相关关系，不是因果
`hypothesis_test`	`TestDecision`	声明的统计检验下的决策
`forecast`	`ForecastOutput`	预测，不是已观测实际值
`discover.*`	`AnomalyCandidate`	等待复核的候选
`assess_quality`	`QualityCheckResult`	已求值的数据质量谓词
`transform.*` / `MetricFrame.metric(...)`	空摘要	仅保留血缘的变换或投影

查看边界与精确证据

问题涉及被省略的项、行级验证或操作推断边界之外的证据时，使用精确读取：

digest = session.evidence.digest(result.ref)
findings = session.evidence.findings(artifact_ref=result.ref, limit=50)
frame = session.get_frame(result.ref)

for finding in findings.items:
    print(finding.finding_type, finding.value)

可以把一个证据项追溯到声明的源字段与被保留的摘要项：

trace = session.evidence.trace(findings.items[0].finding_id)
print(trace.derivation.rule_id, trace.source_fields)

追踪是审计记录，不是系统生成的主张或判断。

用有界分页恢复会话

列表读取默认有界，并按最新记录优先：

frames = session.frame_summaries(limit=20)
digests = session.evidence.digests(limit=10)
findings = session.evidence.findings(limit=50)

if digests.has_more:
    digests = session.evidence.digests(
        limit=10,
        cursor=digests.next_cursor,
    )

页面暴露不可变的 items、limit、has_more 和 next_cursor。它采用普通 keyset 分页，而不是快照隔离；两次读取之间的新 commit 可能改变最新端。游标只能当作不透明续页令牌。

证据存储不可用时，列表和精确读取都会抛出 EvidenceStoreUnavailableError。空页面只表示健康存储没有匹配记录。

问题与修复建议

result.contract().issues 包含封闭的类型化问题：

DataQualityIssue：已求值的数据质量失败；
ComparabilityIssue：不兼容或近似的比较；
EvidenceAvailabilityIssue：提取、摘要或存储降级。

切换 A 是破坏性切换：非 v3 证据存储，以及包含已移除证据字段的 frame sidecar，都会被拒绝。应重新创建分析会话；Marivo 不迁移或重新解释判断时代的状态。

问题可以携带 AnalysisRepair，说明如何重试失败的能力。修复建议是局部错误恢复信息，不是持久化的后续项计划。是否以及如何继续仍由智能体决定。

审阅结论

重点检查三件事：

结果是否使用了预期的指标、范围与比较；
每个重要判断是否由产物或类型化证据项支撑；
结论是否遵守 omissions、质量问题与推断边界。

如果指标定义有误，应停止并通过 marivo-semantic 修复。继续分析不能补偿错误的业务契约。类型化操作循环参见分析流程。