Readiness

When the agent runs readiness

Readiness is Marivo’s explicit certification and diagnostic check for selected semantic objects. Run it after authoring or changing an object, or when a workflow asks for technical certification. It identifies incomplete objects, unknown references, and missing current validation or preview evidence.

The explicit semantic definitions are the governed source of business meaning. Inspection, snapshots, discovery, and preview provide evidence for authoring and diagnosis; their absence does not override an approved, structurally valid definition or make it unavailable to analysis.

A blocked report does not mean the analysis question is invalid. It means the selected objects have a semantic or technical blocker. Missing snapshot or runtime preview certification is reported as a warning instead: disclose it, continue routine analysis when no blocker remains, and repair it before declaring a new or changed semantic object complete.

Analysis APIs do not invoke readiness automatically. Routine analysis of unchanged objects relies on live catalog loading, semantic input resolution, planning, and runtime execution checks instead of refreshing authoring snapshots before every call.

How to respond

Most readiness issues belong to the agent: it can repair declarations, acquire the relevant evidence, and rerun the scoped check through marivo-semantic. You only need to step in when the fix requires a business decision, such as the meaning of a metric, an inclusion rule, or the correct time axis.

Confirm or correct that business choice, then let the agent continue. You do not need to request validation, preview, dependency traversal, or report fields individually.

What ready means

ready means the selected semantic objects have no readiness blocker. ready_with_warnings may include missing datasource snapshot or stale preview evidence, while analysis_ready_inputs identifies the directly requested refs and runtime metric expressions whose dependency closures have no blocker. analysis_ready_refs remains the refs-only projection. Neither status is a runtime authorization token: readiness does not record the user’s approval, guarantee every future query, or decide whether a conclusion is suitable for a business decision.

The sections below document the report and API behavior for readers who need to inspect the technical contract.

Zero-query closeout after scoped runtime evidence

catalog.readiness(refs=[...]) is a pure in-memory check. It never opens a datasource connection — it reasons about the declarations themselves and lowers closed runtime metric expressions through the same bounded graph contract used by analysis. It checks missing definitions, unknown governed leaves, graph budgets, datasource compatibility, fragile string references, and SQL parity status. It does not inspect GitHub/GitLab approval state or make audit-approval judgments.

Backend-touching validation is separate and runs on demand:

Check	What it does	Touches backend?
catalog.verify(ref)	Static ref validation	No
catalog.preview(ref, using=snapshot)	Executes the scoped runtime smoke check and records metadata, never rows	Yes
catalog.preview_many(refs, using=snapshot_or_mapping)	Batches compatible runtime smoke checks while recording evidence per ref	Yes
catalog.readiness(refs=[revenue])	Reads matching persisted preview evidence	No
ms.parity_check(ref)	Optional, potentially unbounded metric/provenance SQL diagnostic	Yes
ms.richness()	Advisory coverage/depth report; never blocks	No

Readiness does not prove the query runs

A non-blocked report means the selected definitions passed the semantic readiness gate. Snapshot and preview evidence is advisory authoring metadata; its absence or age does not block readiness or trigger reacquisition. The report does not prove every future analysis query or full-source truth. Parity is never required for readiness.

The report

catalog.readiness(refs=[...]) returns a frozen ReadinessReport:

Field	Type	Meaning
scope	"semantic_static"	The report certifies semantic dependency closures, not operation-specific executability.
status	"ready" | "ready_with_warnings" | "blocked"	Overall verdict (see below).
blockers	tuple[ReadinessIssue, ...]	Issues that prevent the selected refs from completing certification.
warnings	tuple[ReadinessIssue, ...]	Advisory issues that do not block.
analysis_ready_inputs	`tuple[Ref	RuntimeMetricExpr, …]`
analysis_ready_refs	tuple[Ref, ...]	Directly requested refs whose dependency closures contain no blocker.
preview_required_refs	tuple[Ref, ...]	Typed executable refs with missing or stale preview certification.
input_summary	ReadinessInputSummary	What was checked: datasources, refs, and tables.
checked_at	str	ISO-8601 timestamp of the check.
catalog_definition_fingerprint	str	Exact compiled catalog graph used by this report.

status is derived from severity: any blocker ⇒ blocked; warnings only ⇒ ready_with_warnings; otherwise ready.

Snapshot identity, temporal-fold, grain, and artifact-shape requirements are checked by the consuming analysis operation. A ready report therefore does not promise that every possible session.observe(...) call will execute.

Each ReadinessIssue carries a typed repair instead of free-form next-step text, so the next action is machine-readable and points at the owning live help target:

Attribute	Meaning
kind	The issue kind (see table below).
severity	"blocker" or "warning".
refs	The semantic refs the issue applies to.
catalog_definition_fingerprint	The same compiled catalog graph fingerprint carried by the report.
message	What was expected and what was found.
repair	A typed AuthoringRepair | None carrying action, help_target, optional snippet, and candidates — the concrete next step and where to read its contract.

report.show() groups multiple runtime_preview_missing warnings into one batch repair hint while report.warnings retains per-ref detail. report.to_dict() returns the full machine list; report.contract() exposes one batch preview transition when preview evidence is missing. Certified roots remain available through analysis_ready_inputs; analysis_ready_refs is the refs-only projection.

Optional guardrails enrichment is reported by readiness and richness; it does not block certification.

Issue kinds

Kind	Severity	Trigger	Next step
load_error	blocker	A declaration failed to load.	Fix the semantic load errors and reload.
unknown_ref	blocker	A requested ref is not in the registry.	Fix the ref or remove it from the readiness scope.
missing_business_definition	blocker	A checked object has no ai_context.business_definition.	Add a business_definition.
cross_datasource_unfederated	blocker	A metric spans more than one datasource without federation.	Move integration upstream, enable a federated backend, or split the metric.
metric_graph_invalid	blocker	A catalog/runtime graph violates a governed-leaf, weighted-mean, datasource-domain, depth, or occurrence constraint.	Repair the reported leaf or rebuild the closed expression within the graph limits.
missing_guardrails	warning	A checked metric, entity, dimension, measure, or time dimension has no ai_context.guardrails. Guardrails are recommended enrichment, not a certification requirement.	Add guardrails when explicit usage constraints would help.
sql_parity_unverified	warning	A metric has provenance SQL but parity is unconfirmed.	Run ms.parity_check(ref).
fragile_string_ref	warning	An object uses a fragile string reference.	Replace it with a stable object ref.
time_dimension_pushdown_advisory	warning	A time dimension may not push down to the partition.	Keep the raw partition column and declare its parse if the business axis matches it.
snapshot_missing	warning	No structurally matching datasource snapshot metadata exists for an executable ref. The semantic definition remains analysis-ready when no blocker exists; expiration alone never triggers this issue.	This warning does not require another read. Acquire a matching scoped snapshot only when the caller’s remaining data-access budget permits and no acquisition blocker has reached its stop boundary; otherwise report runtime evidence as unavailable.
runtime_preview_missing	warning	No v1 preview check matches the exact ref payload, catalog definition fingerprint, semantic dependency digest, entity-snapshot bindings, and backend. Expiration alone never triggers this issue.	Routine analysis may proceed; run the scoped preview before declaring a new or changed object complete.

Scope the check

Pass exact current entries, their exact refs, or closed RuntimeMetricExpr values through refs= to scope readiness to the objects and runtime roots being certified. Entries normalize immediately to refs, and mixed lists retain their order. Marivo resolves governed leaves and their full dependency closure (metrics, measures, dimensions, entities, and datasources) for you:

revenue = catalog.metrics.get("sales.revenue")
report = catalog.readiness(refs=[revenue])
if report.preview_required_refs:  # required for authoring closeout; optional for routine analysis
    catalog.preview_many(report.preview_required_refs, using=orders_snapshot)
    report = catalog.readiness(refs=[revenue])

Batch preview validates every binding before connecting, groups compatible entity/field/measure and metric execution plans, and still records one exact preview check per ref. An entity preview never certifies its children.

Use this report to close out semantic changes or satisfy a stricter workflow’s certification requirement. Routine analysis does not call it automatically. For how analysis records what it concludes, see Evidence.

Continue to analysis

When readiness is not blocked, analysis_ready_inputs contains the directly requested refs and runtime expressions whose dependency closures have no blocker. analysis_ready_refs remains the refs-only projection. Warnings remain visible on the same report and must be disclosed before the caller chooses to proceed. snapshot_missing and runtime_preview_missing warnings do not stop routine analysis. There is no second transfer object.

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

Readiness remains explicit: analysis operators do not run it automatically. Pass only the listed inputs to the ordinary analysis APIs after handling warnings.