Governance and Release

Governance is the part of Metric Lifecycle Management that decides what can become trusted context. A release bundle is the immutable handoff artifact for a specific metric version, environment, dependency snapshot, validation evidence, SQL artifact, and reviewer context.

This page covers the public operating model. The product page explains the value proposition at a higher level: Governance and Trust feature page.

Governance should be precise because release, deployment, rollback, and monitoring claims are easy to overstate. ClariLayer is handoff-first for higher-risk metrics. Direct deployment exists, but it is intentionally narrow and tied to RELEASED Tier 0 Experimental metrics.

Lifecycle states

A metric should move through explicit states instead of silently changing meaning under an old name.

DRAFT

The definition is being authored or revised. It may have useful business intent, imported SQL, template context, or reasoning notes, but it is not yet the trusted version.

VALIDATED

The candidate has validation evidence. Validation means the metric has been checked against available warehouse context according to the relevant workflow. It does not automatically mean the metric is approved for every downstream use.

CANDIDATE

The candidate is ready for release review. This is the point where the exact proposed version, dependency snapshot, validation evidence, owner context, and approval requirements should be evaluated together.

APPROVED

The required approval workflow has passed for the current release candidate. Approval belongs to the candidate under review, not to any future edit that happens to reuse the same metric name.

RELEASED

The metric version is the current released artifact for its target context. Meaning-changing edits should create a new version with its own validation evidence, review trail, and release bundle.

DEPRECATED

The metric remains visible for history but should not be treated as the current trusted definition. Deprecation should guide humans and agents toward the replacement or current approved version when one exists.

Tier-based approval expectations

Policy tiers let teams match rigor to risk.

Tier 0 Experimental metrics are the fast path for internal experiments and exploratory analysis. They can move with lighter governance than higher tiers. This is also the only tier eligible for current direct deployment and rollback once the metric is already RELEASED and the connected warehouse path is healthy.

Tier 1 Operational metrics support day-to-day team decisions. They should have warehouse validation before release, and policy can require owner review or additional approval depending on the organization workflow.

Tier 2 Financial metrics require the strongest review posture. They are intended for finance, board-level, or externally sensitive decisions. These definitions should carry current validation evidence and stronger approval before release.

Higher tiers remain release-bundle/handoff-first. The governed output is the release bundle, review trail, and connector handoff, with engineering or analytics owners retaining the higher-risk deployment step.

Candidate-scoped review

Review should be tied to the candidate being released. A candidate-scoped review evaluates the proposed definition, validation report, dependency snapshot, owner context, approval workflow, target environment, and release bundle content together.

This matters because a metric can change between validation and publish. If the candidate changes, the approval run needs to match the refreshed candidate before side effects happen. A previous approval should not silently bless a different SQL expression, dependency version, source assumption, or environment.

Candidate-scoped review also makes audit history more useful. A reviewer can later ask what exact version was approved, which validation evidence was attached, what dependency resolution was used, and why the bundle was allowed to move forward.

Immutable release bundles

Release bundles are the handoff format for governed metric releases. They preserve the contract metadata, SQL artifact, validation report, dependency metadata, reviewer context, and supporting readme for a specific version and target environment.

Immutable means the released bundle is not rewritten in place. When the business meaning changes, iteration creates a new metric version and a new bundle. That keeps downstream consumers from inheriting silent contract changes and lets reviewers compare versions honestly.

The bundle is especially important for AI and BI consumers because it gives systems a stable reference point. An agent should be able to say which released definition version it used. An analytics engineer should be able to inspect the SQL artifact and validation evidence behind a release. A business owner should be able to see why the definition was shaped the way it was.

GitHub and Jira handoff

The live release handoff path is intentionally narrow and auditable. Approved metrics can produce release-bundle artifacts for engineering review and handoff. Source-control handoff uses the organization-scoped GitHub connector configured in Settings. Ticketing handoff uses the organization-scoped Jira connector configured in Settings.

The saved org-scoped connector target is the release-readiness boundary. GitHub OAuth or Jira OAuth can be visible in connector state when available, but they do not replace the saved release target. GitHub App installation tracking, repo discovery, and Jira workspace discovery are supporting evidence, not standalone production publish paths.

This connector boundary matters for trust. A release should fail closed if required handoff side effects cannot be completed authoritatively. If the GitHub or Jira connector is not configured for the organization, handoff requires the active org-scoped connector; OAuth or installation state alone is not enough.

Direct deployment and rollback

Direct deployment is available only for RELEASED Tier 0 Experimental metrics through connected warehouse write paths. That boundary is deliberate.

In the signed-in product, deployment and rollback mutations are session-authenticated and role-gated before privileged lookup, token decryption, or warehouse-side effects. For machine automation, service accounts authenticate the versioned deployment and rollback routes. Those automation routes are authenticated machine surfaces, not public unauthenticated write APIs.

The live direct-deployment path uses the shared warehouse write interface across Databricks, Snowflake, and BigQuery. Eligible deployments create SQL views in the connected warehouse, record deployment state, verify the artifact, and support rollback by dropping the deployed view when the deployment is in a rollback-eligible state.

Two boundaries matter. First, direct deployment is not available for non-Experimental tiers today. Second, a verify failure after view creation can leave a warehouse artifact until manual recovery or a follow-up fix handles cleanup, so the product does not promise automatic rollback for every failure mode.

Monitoring and Observe boundaries

Monitoring is a trust-signal layer, not a promise that ClariLayer is in the query path for every warehouse.

Product health and Observe surfaces help teams inspect trust signals such as lifecycle state, validation recency, ownership, health alerts, usage or drift context, and follow-up work. They should be described as monitoring and trust-signal surfaces.

Live Observe/query-history ingest is Databricks-only today. Databricks remains the deepest live Observe path because it supplies the query-history loop. Snowflake and BigQuery share catalog browse, validation, deployment, rollback, registry, and API context paths, but they do not yet have live Observe/query-history ingest parity.

This means a Snowflake or BigQuery metric can still be governed and released. It simply should not be described as having query-history-driven Observe evidence until that path exists for those warehouses.

How release fits the lifecycle

Governance and release sit after authoring, registry review, and validation:

1. Author or import the metric in Metric Studio.
2. Check existing definitions and relationships with Metric Registry.
3. Attach validation evidence with Warehouse Validation.
4. Review the candidate under the correct policy tier.
5. Produce the immutable release bundle and perform the appropriate handoff or Tier 0 deployment action.
6. Monitor trust signals through product health surfaces, Observe where supported, the registry, and the API contract.

The point is not to slow every metric down. The point is to make the release path match the risk of the metric. Experimental work can move quickly. Operational and financial definitions keep validation, approval, bundle handoff, and audit history attached before downstream systems rely on them.

See how lifecycle status appears in the metrics contract