Metric status is a trust signal, not paperwork.

The short version

• Metric lifecycle labels like draft, published, and certified were documentation in the human era. Once agents read the catalog, a status that does not gate invocation programmatically might as well not exist.
• Every state has to answer three questions in a policy file an agent loads at startup: who can invoke a metric in this state and in what mode, how the agent describes it to the user, and how much the definition can change silently.
• Enforcement takes four gates, not one: retrieval filters the candidate set, the planner checks named metrics, the compiler resolves the full dependency chain, and the executor re-verifies state and hash before running.
• Certified stands for four guarantees at once: an accountable signed review, a hash bound to the definition, monitored upstream freshness, and automatic downgrade on drift. Without that machinery the badge and the metric's health quietly come apart.
• Deprecation works as two states: deprecated redirects to its replacement instead of executing, and retired stays readable for lineage but no longer compiles.

An analyst asks a chat assistant: what was our net revenue retention last quarter? The agent finds a metric called net_revenue_retention, runs it, returns 118%. The analyst nods. The number goes into a board deck.

Nobody in that loop checked whether the metric that ran was the one finance actually uses. There are three definitions of NRR in the catalog. One came from a 2022 spreadsheet a departing PM committed as YAML. One is what the controller uses in the monthly close. One is a draft someone started when the CFO asked for a new cut, then abandoned. All three compile. All three return numbers. Two of them are wrong.

The assistant did exactly what it was asked. The failure is in retrieval: the agent reaches the catalog through a tool server, semantic search ranks the candidate definitions by embedding similarity, and all three come back as plausible matches for the same question. The agent picks one. The candidate set should never have contained two of the three.

Agents lost the periphery that made sloppy status survivable.

Every semantic layer has a lifecycle. Draft, published, certified, deprecated, retired. The names vary across dbt Semantic Layer, Cube, LookML, and the homegrown YAML trees most teams actually run, but the shape is the same. In the human era these labels were mostly documentation. A steward set them, a dashboard grouped by them, someone occasionally remembered to check.

They could be sloppy because the human running the query brought their own trust calibration in parallel. They knew who owned the metric. They noticed when a number felt off. They asked in Slack. Status was one signal among many, and usually the weakest one.

Agents have no such periphery. They see the catalog, the definition, the compiled query, the result. Nothing else. If status does not gate the invocation programmatically, it might as well not exist.

The stakes differ from ordinary retrieval failure, too. When a document pipeline surfaces the wrong source, the user gets text that reads slightly off, and an attentive reader catches it. When metric retrieval surfaces the wrong definition, the user gets a number. Numbers do not read as off. They get pasted into decks.

What a status has to actually specify.

So what does it take to make a state name executable rather than decorative? For every state in your catalog, whether that is draft, published, certified, deprecated, retired, or whatever custom one your team invented, you have to be able to answer three questions in a config file that an agent loads at startup.

1. Who is allowed to use a metric in this state, and in what mode? Can a background agent pull it on a schedule? Only if a user names it directly? Only inside a chat where a human reads the answer before acting on it? Nobody at all?
2. How does the agent describe it to the user? "This is the certified NRR metric" is a very different sentence from "this is a draft owned by Jamie, not reviewed." The state decides which one the agent is permitted to say.
3. How much can the definition change silently? A draft should churn freely; its author is still iterating. A certified metric changing without a signal is a bug, because whoever reads the result believes they are getting the same number they got yesterday.

The first question has three answers rather than one, and that split carries more weight than it looks. There are three ways a metric gets invoked and they run very different risks. A scheduled agent picks the metric itself and no human reads the result before it lands somewhere. A user in a chat names a metric explicitly, so they chose it and they will read what comes back. Or a user asks a topical question and the agent chooses on their behalf, with a human still reading the answer. The more discretion the agent has, and the less oversight there is downstream, the higher the bar a metric has to clear.

Written out, that is a policy file rather than a planner prompt or a condition scattered through retrieval SQL:

states:
  draft:
    eligibility: { autonomous: false, hitl_named: true, hitl_topic: false }
    confidence_framing: "draft; not reviewed"
    change_discipline: { hash_stable: false, notify_on_change: false }
  certified:
    eligibility: { autonomous: true, hitl_named: true, hitl_topic: true }
    confidence_framing: "certified"
    change_discipline: { hash_stable: true, notify_on_change: true }

Fill those rows in for every state you have defined. If you can, the state model is real, and an agent can act on it. If you cannot, if certified sits in your catalog but you cannot say what it authorizes an agent to do that published does not, then certified is a badge. Delete it, merge it into its neighbor, or work out the rule.

If you cannot answer eligibility programmatically for a state, it is not a lifecycle stage. It is a label. And agents do not read labels.

Four gates, not one.

The obvious place to enforce that policy is retrieval. Filter the candidate set before the agent ever sees it:

WHERE state IN (:allowed_states)
  AND (visibility = 'global' OR owning_team IN :caller_teams)

Do this first. It solves the three-NRR problem in its most common form. But there is a decision inside the retrieval step that most catalogs get wrong, and it quietly undermines everything built on top of it.

Being findable by name and being selectable by topic are two different privileges. A team-local metric should have the first and not the second: its owners can call it up whenever they want it, but it never surfaces as the answer to someone else's general question. That takes two retrieval paths with two different filters.

-- topical retrieval: only globally eligible states
WHERE state IN ('published', 'certified') AND visibility = 'global'

-- name resolution: broader, scoped to the caller
WHERE name = :requested
  AND (visibility = 'global' OR owning_team IN :caller_teams)

Collapse those into one path and unpublished metrics either leak into everyone's search results or become invisible even to the people who wrote them. Either way, the organization starts treating unpublished as a backlog to clear. Certification turns into an OKR, the OKR turns into a rubber stamp, and the catalog fills up with certified definitions nobody uses. Two paths let unpublished stay what it usually should be: a perfectly good place for a metric to end up, whether it was exploratory, team-local, or written to answer one question in one meeting.

Even with both paths correct, retrieval by itself still leaks in three ways. Each one needs its own gate.

A user can name the metric outright. Ask for the draft NRR that Jamie was building and retrieval never ran at all; the planner resolved that name directly. So the planner needs a check of its own. Is this caller, working in this mode, allowed to invoke a metric in this state?

A clean metric can rest on a broken one. A certified definition references dimensions, joins and sources that carry states of their own, and any one of them might be deprecated or retired. Filtering the metric tells you nothing about what sits underneath it. Compiler has to resolve the full dependency chain and fail closed if any link in it is ineligible.

Status can change after the plan is made. In a long-running autonomous workflow, minutes pass between choosing a metric and running it. A definition that was published at 09:03 can be deprecated by 09:11 because someone found a bug. So the executor takes one last cheap look at state and definition hash, and aborts and re-plans if either moved.

Four gates, not one. The useful question is never where to put the status check. It is what each layer is responsible for guaranteeing.

Certified means the contract, not the label.

That last gate is only worth running if the contract it checks is worth something. So what should certification actually guarantee?

Done properly, certified:true is exactly the signal you want an agent to trust, because it stands for four guarantees at once. An accountable owner reviewed and signed the definition. That signature is bound to a hash of the definition. Upstream freshness is monitored against an agreed SLA. And any drift, in the definition, the pipeline, or the source data, downgrades the state automatically. When all four hold, the green badge really does mean the number is trustworthy. That is what the contract is for.

The trap is shipping certification without any of that machinery, as a decorative label on a YAML file. Two things that ought to be the same thing then come apart: the badge, stamped once when somebody reviewed it, and the metric's actual health, determined fresh on every run. Nothing keeps them in sync, and nobody notices, because every interface shows the badge and none of them show the health.

Keeping the two together means returning them together. The answer envelope should carry the evidence, not just the verdict:

{
  "value": 104.1,
  "metric": "net_revenue_retention",
  "state": "certified",
  "cert_actor": { "role": "finance_controller", "at": "2026-07-01" },
  "definition_hash": "sha256:9c1b…",
  "upstream_freshness_at": "2026-07-10T03:14:00Z"
}

cert_actor is in there because who signed matters as much as the fact that somebody did, and most state models throw that away. A metric certified by an automated lint pass is a different claim from one certified by the finance controller. Both are legitimate. They justify different things. Keeping the distinction means recording transitions as append-only events instead of overwriting a column:

(metric_id, from_state, to_state, actor_role, basis_ref, at)

basis_ref points at whatever authorized the change: the controller's memo, the reviewed PDF, the ticket. Policy then reads the actor rather than the bare label. A controller-signed metric can run in an autonomous workflow; a lint-signed one stays restricted to sessions where a human reads the answer.

The hash does the rest of the work. Certification signs the definition, the same way a build signature covers an artifact in a software supply chain, so if the definition changes the signature stops matching and the state downgrades on its own. Nobody has to re-run a review to catch silent tampering. Freshness comes from the pipeline and travels alongside, which means a stale certified metric is visibly stale rather than quietly wrong.

Build it that way and certified:true earns the trust it asks for. Build it as a label and it lies to you.

Deprecation has to have teeth.

Retirement is where the real damage accumulates. A metric gets superseded, the replacement gets certified, and the old definition keeps sitting in the catalog because nothing actively removes it. It still compiles. It still returns a number.

An agent scanning for net_revenue_retention finds both. Absent an enforced deprecation state, there is no reason to expect it picks the current one. Which is why deprecation is cleaner as two states rather than one.

A deprecated metric fails topical retrieval outright. If a user names it explicitly, the resolver hands back a replaced_by pointer instead of an execution plan, and the agent surfaces that redirect rather than quietly running the successor. A retired metric stays readable for lineage and back-testing but is no longer executable, so compile fails closed.

The two-step matters. It keeps historical metrics auditable without leaving them armed in the live path. Skipping the deprecated step is why most metric graveyards are indistinguishable from most metric catalogs.

What happens to the three NRRs.

Run the opening scene again with the contract in place. The 2022 spreadsheet definition is a draft, so retrieval excludes it from the topical candidate set and the analyst's question never surfaces it. The planner will only invoke it if someone on the owning team names it outright. The abandoned CFO cut is the same story. The controller's monthly-close definition is certified, hash-signed against the controller's own sign-off with freshness live from the pipeline, so it comes back as the single eligible candidate. The agent returns 104% and frames it as certified. The number that ships is the number that is right.

Now the harder version of the question, and the one worth sitting with: what if two of the three were both certified? Suppose an EMEA finance team certifies its own regional NRR under the same public name. The state contract alone does not resolve that, and pretending otherwise would be dishonest.

Two things narrow it. Actor and scope. A controller-signed, globally-scoped metric outranks a team-signed, locally-scoped one at topical retrieval, because a topical question from an unscoped user is asking for the globally eligible answer. That is precisely why cert_actor belongs in the envelope rather than being flattened into a boolean. And if two candidates genuinely tie on both axes, the honest answer is that runtime is the wrong place to fix it. Name uniqueness within the certified tier is a governance rule the catalog owner enforces at authoring time. A runtime contract can refuse to guess; it cannot invent an authority that was never established.

The label and the contract.

Status was paperwork when humans were in the loop. It is runtime infrastructure now that agents are. Every state your semantic layer defines has to answer, in code rather than in a wiki page: what can an agent do with a metric in this state, at each gate in the pipeline, and what does it owe the user when it does?

If you cannot answer that programmatically for a state you have defined, that state is not a lifecycle stage. It is a label. And agents do not read labels.

Sharvari is an engineer on the Intelligence pod at zaimler, the runtime context layer for AI agents.