就绪检查

就绪检查是编写与分析之间的必经门禁。ms.readiness() 检查智能体即将使用的语义对象是否完整、规范，是否可以交接给分析，并返回一个 ReadinessReport。

新项目可以成功 ms.load()，但就绪检查仍然是 blocked。load 只负责解析声明；就绪检查负责阻止智能体基于半成品语义进行推理。把任何引用交给分析会话之前，都应先解决每一个阻塞项。

import marivo.semantic as ms

ms.load()
report = ms.readiness()                  # 检查每一个已加载对象
if report.status == "blocked":
    report.show()                        # 有界卡片：每个 blocker 及其下一步
    raise SystemExit("resolve readiness blockers before analysis")

结构性检查，不是运行时检查

ms.readiness() 是一次纯内存检查。它从不打开数据源连接 —— 它只针对声明本身进行推理：缺失定义、未知引用、跨数据源的 fan-out、脆弱的字符串引用，以及 SQL 一致性状态。它不检查 GitHub/GitLab 审批状态，也不做审计审批判断。

触及后端的校验是独立的，并按需运行：

检查	作用	是否触及后端？
`ms.readiness()`	结构性完整性门禁	否
`catalog.preview(ref)`	执行一个小查询，采样真实数据行	是
`ms.parity_check(ref)`	用指标对其 `provenance` SQL 跑一遍并比对结果	是
`ms.richness()`	关于覆盖度/深度的建议性报告；从不阻塞	否

报告

ms.readiness() 返回一个冻结的 ReadinessReport：

字段	类型	含义
`status`	`"ready" \| "ready_with_warnings" \| "blocked"`	总体结论（见下）。
`blockers`	`tuple[ReadinessIssue, ...]`	交接前必须修复的问题。
`warnings`	`tuple[ReadinessIssue, ...]`	不会阻塞的建议性问题。
`analysis_ready_refs`	`tuple[str, ...]`	通过检查的引用 —— 可安全交给分析。
`input_summary`	`ReadinessInputSummary`	检查了什么：数据源、引用、表。
`checked_at`	`str`	检查的 ISO-8601 时间戳。

status 由严重程度推导：只要有阻塞项 ⇒ blocked；只有警告 ⇒ ready_with_warnings；其余 ⇒ ready。

每个 ReadinessIssue 都采用相同的教学式结构：

属性	含义
`kind`	问题种类（见下表）。
`severity`	`"blocker"` 或 `"warning"`。
`refs`	问题涉及的语义引用。
`message`	期望是什么、实际是什么。
`suggested_action`	具体的下一步。

report.show() 打印一张有界卡片；report.to_dict() 返回完整的机器可读列表，便于程序化处理。

问题种类

类型	严重程度	触发条件	下一步
`load_error`	阻塞项	某个声明加载失败。	修复语义加载错误并重新加载。
`unknown_ref`	阻塞项	请求的引用不在 registry 中。	修正该引用，或将其从就绪检查范围中移除。
`missing_business_definition`	阻塞项	被检查的对象没有 `ai_context.business_definition`。	补充 `business_definition`。
`cross_datasource_unfederated`	阻塞项	某个指标在没有联邦的情况下跨越多个数据源。	把集成移到上游、启用联邦后端，或拆分指标。
`missing_guardrails`	警告	被检查的对象没有 `ai_context.guardrails`。	补充 `guardrails`。
`sql_parity_unverified`	警告	某个指标有 `provenance` SQL 但一致性未确认。	运行 `ms.parity_check(ref)`。
`fragile_string_ref`	警告	某个对象使用了脆弱的字符串引用。	用稳定的对象引用替换它。
`time_dimension_pushdown_advisory`	警告	某个时间维度可能无法下推到分区。	当业务时间轴与分区一致时，保留原始分区列并声明其解析。

限定检查范围

默认情况下，ms.readiness() 会检查每一个已加载对象。传入 refs= 可将范围限定到一次分析所需的对象；Marivo 会解析完整的依赖闭包（指标、它的度量、维度、实体与数据源）：

report = ms.readiness(refs=["sales.revenue"])
for issue in report.blockers:
    print(issue.kind, issue.refs, "→", issue.suggested_action)

这是分析之前必经的语义门禁。关于分析如何记录结论，参见证据链。