就绪检查

智能体什么时候运行就绪检查

就绪检查是针对所选语义对象的显式技术认证和诊断。新建或修改对象后，或者 流程要求技术认证时运行它。它会识别不完整对象、未知引用，以及 缺少当前验证或预览证据的情况。

显式语义定义是受治理的业务语义真源。检查、快照、发现和 预览为编写与诊断提供辅助证据；缺少这些证据不会覆盖已经批准且结构合法的定义， 也不会使其无法用于分析。

阻塞报告不代表业务问题不能分析，而是说明所选对象存在语义或技术阻塞项。 缺少数据源快照或运行时预览认证时报告警告：没有其他阻塞项 时，披露后可继续日常分析，但在声明新建或修改的语义对象已完成前仍需修复。

分析 API 不会自动调用就绪检查。日常分析复用未变化的对象时，依赖实时目录 加载、语义输入解析、规划和运行时执行检查，不会在每次调用前刷新 编写快照。

用户怎么处理

大部分就绪问题都由智能体通过 marivo-semantic 处理，例如修复声明、取得相关证据并重新 检查。只有修复过程涉及业务判断时，才需要用户参与，例如确认指标含义、纳入规则或正确的 时间轴。

确认或纠正这项业务选择后，让智能体继续即可。用户不需要分别安排验证、预览、依赖检查或 报告字段。

就绪表示什么

ready 表示所选语义对象没有就绪阻塞项。 ready_with_warnings 可能包含缺失的数据源快照或不匹配的预览证据；此时 analysis_ready_inputs 会按顺序列出受治理的依赖闭包中没有阻塞项的直接请求 引用与运行时指标表达式；analysis_ready_refs 是其中仅含引用的投影。两种状态都不是运行时 授权令牌：就绪检查不记录用户的批准行为，不保证所有后续查询都能成功，也不会 替用户判断结论是否适合业务决策。

需要检查技术契约的读者，可以继续查看下面的报告和 API 参考。

限定范围的运行时证据之后的零查询收尾

catalog.readiness(refs=[...]) 是一次纯内存检查。它从不打开数据源连接；除声明 外，它还会让封闭运行时指标表达式通过分析使用的同一套有界图契约。 检查内容包括缺失定义、未知受治理的叶节点、图 budgets、数据源兼容性、脆弱的 字符串引用与 SQL 一致性状态。它不检查 GitHub/GitLab 审批状态，也不做审计审批判断。

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

检查	作用	是否触及后端？
catalog.verify(ref)	静态引用验证	否
catalog.preview(ref, using=snapshot)	执行限定范围的运行时冒烟检查，只记录元数据，不持久化行	是
catalog.preview_many(refs, using=snapshot_or_mapping)	合并兼容的运行时冒烟检查，同时按引用分别记录证据	是
catalog.readiness(refs=[revenue])	读取匹配已持久化预览证据	否
ms.parity_check(ref)	可选且可能无界的指标/来源信息 SQL 诊断	是
ms.richness()	关于覆盖度/深度的建议性报告；从不阻塞	否

就绪检查不证明查询能跑通

非阻塞报告表示所选定义已通过语义就绪检查门禁。快照和预览 是建议性的编写元数据；缺少或过期都不会阻塞就绪检查，也不会触发重新采样。 它不证明每一种未来分析查询或完整来源事实。一致性从不作为就绪检查要求。

报告

catalog.readiness(refs=[...]) 返回一个冻结的 ReadinessReport：

字段	类型	含义
scope	"semantic_static"	本报告认证语义依赖闭包，不认证具体分析操作的可执行性。
status	"ready" | "ready_with_warnings" | "blocked"	总体结论（见下）。
blockers	tuple[ReadinessIssue, ...]	阻止所选引用完成认证的问题。
warnings	tuple[ReadinessIssue, ...]	不会阻塞的建议性问题。
analysis_ready_inputs	tuple[Ref | RuntimeMetricExpr, ...]	按原顺序保留受治理的依赖闭包中没有阻塞项的直接请求根。
analysis_ready_refs	tuple[Ref, ...]	依赖闭包中没有阻塞项的直接请求引用。
preview_required_refs	tuple[Ref, ...]	缺少或没有匹配预览认证的类型化可执行引用。
input_summary	ReadinessInputSummary	检查了什么：数据源、引用、表。
checked_at	str	检查的 ISO-8601 时间戳。
catalog_definition_fingerprint	str	本报告使用的精确编译后的目录图。

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

快照身份、时间折叠、粒度与产物形状等要求由实际消费它的 分析操作检查。因此就绪报告不承诺任意 session.observe(...) 调用都一定能够执行。

每个 ReadinessIssue 都携带一个类型化的 repair，而不是自由文本的下一步描述，因此下一步 动作是机器可读的，并指向所属的实时帮助目标：

属性	含义
kind	问题种类（见下表）。
severity	"blocker" 或 "warning"。
refs	问题涉及的语义引用。
catalog_definition_fingerprint	与报告相同的编译后的目录图指纹。
message	期望是什么、实际是什么。
repair	类型化的 AuthoringRepair | None，包含 action、help_target、可选的 snippet 与 candidates —— 即具体的下一步及其契约的查阅位置。

report.show() 会把多个 runtime_preview_missing 警告合并成一条批量修复建议提示， 同时 report.warnings 仍保留逐引用细节；report.to_dict() 返回完整机器可读列表； report.contract() 在缺失预览证据时暴露一个批量 preview 转换。 通过认证的根保留在 analysis_ready_inputs 中；analysis_ready_refs 是仅含引用投影。

问题种类

类型	严重程度	触发条件	下一步
load_error	阻塞项	某个声明加载失败。	修复语义加载错误并重新加载。
unknown_ref	阻塞项	请求的引用不在 registry 中。	修正该引用，或将其从就绪检查范围中移除。
missing_business_definition	阻塞项	被检查的对象没有 ai_context.business_definition。	补充 business_definition。
cross_datasource_unfederated	阻塞项	某个指标在没有联邦的情况下跨越多个数据源。	把集成移到上游、启用联邦后端，或拆分指标。
metric_graph_invalid	阻塞项	目录/运行时图违反受治理的叶节点、加权平均、数据源领域、深度或发生项约束。	修复报告中的 leaf，或在图限制内重建封闭表达式。
missing_guardrails	警告	被检查的指标、实体、维度、度量或时间维度没有 ai_context.guardrails。约束是建议性的丰富化，不是认证必需项。	当显式使用约束有帮助时补充 guardrails。
sql_parity_unverified	警告	某个指标有 provenance SQL 但一致性未确认。	运行 ms.parity_check(ref)。
fragile_string_ref	警告	某个对象使用了脆弱的字符串引用。	用稳定的对象引用替换它。
time_dimension_pushdown_advisory	警告	某个时间维度可能无法下推到分区。	当业务时间轴与分区一致时，保留原始分区列并声明其解析。
snapshot_missing	警告	可执行引用没有结构上匹配的数据源快照元数据；没有其他阻塞项时语义定义仍可用于分析，仅仅过期不会触发。	该警告不要求再次读取。仅在调用者剩余的数据访问预算允许、且获取阻塞项尚未达到停止边界时获取匹配限定范围的快照；否则报告运行时证据不可用。
runtime_preview_missing	警告	没有 v1 预览检查精确匹配引用负载、目录 definition 指纹、语义依赖摘要、实体-快照绑定与后端；仅仅过期不会触发。	日常分析可以继续；在声明新建或修改的对象已完成前运行限定范围的预览。

限定检查范围

通过 refs= 传入精确当前条目、它们的精确引用或封闭 RuntimeMetricExpr，把 就绪检查限定到正在明确认证的对象与运行时根。条目会立即归一化为引用， 混合列表保持原顺序。Marivo 会解析受治理的叶节点及其完整依赖闭包（指标、度量、 维度、实体与数据源）：

revenue = catalog.metrics.get("sales.revenue")
report = catalog.readiness(refs=[revenue])
if report.preview_required_refs:  # authoring closeout 必须修复；日常分析可选
    catalog.preview_many(report.preview_required_refs, using=orders_snapshot)
    report = catalog.readiness(refs=[revenue])

批量预览会在连接前校验全部绑定，合并兼容的实体/字段/度量与指标 执行计划，并继续为每个引用记录独立、精确的预览检查。实体预览不会认证其子对象。

使用该报告完成语义变更的收尾，或满足更严格流程的认证要求。日常分析 不会自动调用它。关于分析如何记录结论，参见 证据链。

继续进入分析

当就绪检查未被阻塞时，analysis_ready_inputs 按原顺序包含依赖闭包中没有阻塞项的 直接请求引用与运行时表达式；analysis_ready_refs 是仅含引用投影。警告继续显示在同一份报告上，调用方必须在决定继续前明确披露； snapshot_missing 与 runtime_preview_missing 警告都不会阻止日常分析。中间不再创建 额外的传递对象。

import marivo.semantic as ms

catalog = ms.load()
revenue = catalog.metrics.get("sales.revenue")
report = catalog.readiness(refs=[revenue])
if report.status == "blocked":
    report.show()
    raise SystemExit
ready_inputs = report.analysis_ready_inputs

就绪检查仍需显式调用；分析操作不会自动执行它。处理警告后，只把列出的 输入传给普通分析 API。