Chapter 14

Variance isolation

Reflects Holonograph v0.23.0 · ~7 min read

When your evaluation scores move, some of the movement is real change in your system and some is just the noise of measuring with a language model. Variance isolation returns a cleaned reading: how much of the spread reflects your system versus measurement noise — plus a verdict that tells you whether to trust the reading yet.

What it is

A per-surface, per-dimension analysis over a window that returns two things: a cleaned variance figure and a confidence verdict. The verdict is the load-bearing output — it tells you whether the cleaned figure is trustworthy right now, or whether the reading needs more data (or different data) before you act on it.

What you get

A cleaned variance figure and a confidence verdict. There are four:

Verdict	Meaning
`viable`	Trustworthy. Act on it.
`degenerate`	Too few distinct conditions to separate signal from noise. Gather more data.
`contaminated`	Inputs weren't held constant enough. Re-run under controlled conditions.
`instrument-limited`	Measurement noise dominates. Don't trust the reading yet.

The verdict is what decides whether the number is worth acting on. A viable reading is the one you use; the other three are diagnostic — each names why the reading isn't ready and what would fix it.

How to run it

Three endpoints, in order. The first produces the reading; the second gives it a verdict; the third governs what happens to it.

1. Produce the reading

POST /lens/decomposeVariance
Authorization: Bearer <token>
x-holonograph-run-mode: production
Content-Type: application/json

{
  "surfaceId": "classify-intent",
  "dimensionId": "correctness",
  "since": "2026-06-01T00:00:00Z",
  "until": "2026-07-05T00:00:00Z"
}

Response: an analysis record you'll reference by eventId in the next step.

{
  "eventId": "evt_01H...",
  "surfaceId": "classify-intent",
  "dimensionId": "correctness"
}

2. Get the verdict

POST /lens/decomposition/evaluate
Content-Type: application/json

{ "targetEventId": "evt_01H..." }

Response: the confidence verdict and guidance for what to do next.

3. Govern the result

Once you've seen the verdict, decide what to do with the reading. Governance is one of four actions:

POST /lens/decomposition/lifecycle
Content-Type: application/json

{
  "targetEventId": "evt_01H...",
  "status": "lock",
  "approverId": "brian",
  "pinnedLabel": "billing-triage-baseline-2026-Q3"
}

Status	Effect
`quarantine`	Hold the reading aside; don't use it in downstream comparisons until reviewed.
`approve`	Accept the reading as trustworthy. Requires an `approverId`.
`lock`	Freeze this reading as the reference against a `pinnedLabel`. Requires an `approverId` and the `pinnedLabel`.
`reject`	Discard the reading. Requires an `approverId` and a comment.

The lifecycle response returns the persisted status alongside the original targetEventId. Governance decisions are themselves substrate events — they become part of the record, attributable in future drift readings like any other change.

What to do with each verdict

Verdict	Next action
`viable`	Read the cleaned variance figure. If you want to hold this specific reading as a reference, `lock` it with a `pinnedLabel`. Otherwise `approve` and move on.
`degenerate`	The window doesn't have enough distinct conditions for the analysis to separate signal from noise. Widen the window, or drive more variety through the surface before re-running.
`contaminated`	The inputs weren't held constant enough to trust the reading. Re-run under controlled conditions — a replay through the surface at a fixed input panel is the usual fix.
`instrument-limited`	Measurement noise dominates whatever real movement is present. Don't trust the reading yet; if the reading matters, `quarantine` it while you widen the window or reduce input variability.

Reference

Endpoints

Method & path	Purpose
`POST /lens/decomposeVariance`	Produce a cleaned variance reading for a surface + dimension over a window. Returns an analysis record `eventId`.
`POST /lens/decomposition/evaluate`	Return the confidence verdict for the analysis record.
`POST /lens/decomposition/lifecycle`	Govern the reading: `quarantine`, `approve`, `lock`, or `reject`.

`POST /lens/decomposeVariance` — request

Field	Shape	Notes
`surfaceId`	string (req)	The surface.
`dimensionId`	string (req)	The dimension to isolate variance for.
`since`	ISO 8601 (opt)	Inclusive lower bound on events considered.
`until`	ISO 8601 (opt)	Exclusive upper bound.

`POST /lens/decomposition/lifecycle` — request

Field	Shape	Notes
`targetEventId`	string (req)	The analysis record from `decomposeVariance`.
`status`	enum (req)	`quarantine`, `approve`, `lock`, or `reject`.
`approverId`	string	Required for `approve`, `lock`, `reject`.
`comment`	string (opt)	Free-form explanation. Required for `reject`.
`pinnedLabel`	string	Required for `lock`. The label under which this reading is held as a reference.