The Context Layer

ClariLayer is the context layer for business metrics. Warehouses compute data. Semantic layers translate approved logic into runtime queries. The context layer explains what a metric means, who owns it, which version is approved, when it should be used, how it was validated, and why the definition was shaped this way.

That distinction matters because AI agents do not only need a number. They need the business contract behind the number. If an agent sees three churn definitions, the useful answer is not "all three can be queried." The useful answer is "this definition is approved for board reporting, this one is exploratory, and this objection is still unresolved."

Metric Lifecycle Management

Metric Lifecycle Management is the discipline that produces the context layer. It treats metric logic like a governed asset instead of a loose warehouse query. A metric moves through definition, validation, approval, release, observation, and iteration with explicit state and evidence.

The lifecycle gives different audiences the part they need:

• Business owners see meaning, caveats, and accountability.
• Reviewers see approval state, validation evidence, and release history.
• AI agents see a stable contract instead of raw, drifting warehouse artifacts.
• BI and analytics teams see which version should be used for which purpose.

Metric Lifecycle Management is not a replacement for your warehouse or semantic layer. It is the upstream protocol for deciding which metric meaning is trusted before downstream systems consume it.

For the operational docs behind those stages, read Metric Studio, Metric Registry, Warehouse Validation, and Governance and Release.

The three-layer model

The modern data stack already has powerful computation and execution surfaces:

• Databricks, Snowflake, and BigQuery store and compute the data.
• dbt, Cube, BI semantic models, and warehouse-native semantic features help translate logic into queries.
• ClariLayer governs the business context that those systems cannot infer from SQL alone.

The warehouse can tell an agent how to run a query. The semantic layer can tell it how a measure is modeled. The context layer tells it whether this is the definition Finance approved, whether it has been validated, whether it is deprecated, and whether a human pinned caveats for downstream consumers.

Warehouse boundaries

ClariLayer's shared warehouse product path covers live catalog browse, validation, direct deployment, and rollback across Databricks, Snowflake, and BigQuery. Those surfaces share the same catalog/validation/deploy/rollback workflow at the product layer.

Observe and query-history ingest are intentionally narrower today. The live Observe ingest path remains Databricks-only. Snowflake and BigQuery are part of the shared catalog, validation, deployment, and rollback path, but they do not yet have Observe/query-history ingest parity.

This boundary is important for evaluation scope and for AI-agent copy. A cross-warehouse metric can be governed, validated, released, deployed, rolled back, and exposed through the API. Query-history-driven Observe evidence is only available from Databricks today.

Read the Warehouse Validation docs

Managed variants

Some metric disagreements are defects. Others are legitimate variants. Finance and Sales may both need a "Greenfield Account" metric, but each may use it for a different operating decision. Forcing one brittle golden definition can hide the disagreement instead of resolving it.

Managed variants make the difference explicit. A shared core captures the common meaning, while each approved variant carries its own scope, owner, lifecycle state, and reasoning. That gives downstream systems the vocabulary to choose the right version instead of pretending only one version exists.

A managed variant should be created when the difference is intentional, durable, and tied to a consumer context. A temporary data issue, an unreviewed analyst draft, or a one-off spreadsheet adjustment should not become a managed variant until it has an owner and governance path.

The Reasoning Trail

The Reasoning Trail is the human explanation layer inside the context layer. It records questions, proposals, objections, clarifications, and decision rationale beside the metric definition.

Pinned Reasoning Trail notes are especially important for AI systems. A normal note is human-to-human discussion. A pinned note is a curator saying, "this fact should be available to agents and downstream consumers." That lets a contract response include not only the approved definition but also the material caveats and unresolved objections that make the answer trustworthy.

Read the Reasoning Trail concept

How this becomes an API contract

The v1 API exposes governed context through read-only routes. List and detail endpoints help consumers discover metrics and read definition metadata. The metric contract endpoint returns the agent-facing envelope: business definition, current approved version, validation timestamp, lifecycle status, disambiguation hints, Reasoning Trail signals, and pinned notes.

That envelope is the contract layer for AI agents. It lets an agent ground an answer in a specific governed definition version and surface uncertainty when the human context says uncertainty still exists.

See the API overview and metrics contract endpoint

Design principles

Use these principles when deciding what belongs in the context layer:

• Prefer explicit lifecycle state over vague freshness language.
• Preserve the reason for a definition, not only the SQL expression.
• Make legitimate variants visible and governed.
• Keep agent-readable context curated; do not dump every discussion into a prompt.
• Keep warehouse capability claims tied to live runtime reality.

The context layer is useful because it stays truthful. If a metric is draft, say draft. If a Snowflake metric is validated but has no Observe/query-history evidence, say that. If an objection is unresolved, preserve it. That honesty is what lets humans and AI systems trust the metric.