# Declared Versus Observed

> Extend the governed read to live systems — compare declarations against runtime observations without ever letting observation rewrite declaration.

**Tier:** 2 · **Normative weight:** implements `TM-OBS-005`–`TM-OBS-009`
**Requires:** [Governed Read](/docs/truth-machine/kit/governed-read/)

## Problem it removes

Monitoring collapses "could not tell" into pass or fail: an unreachable
service reads as stopped, a timeout reads as healthy-enough, and drift
between what was declared and what is running is discovered during an
incident instead of a read.

## Mechanism

A `--live` mode (or equivalent) on the governed read that observes the
running system — service states, remote file digests, HTTP contracts — and
compares each observation against the declaration. The rules are exactly
the conditional observation requirements:

- Declared and observed stay separate values; an observation never
  rewrites the declaration it was checking (`TM-OBS-005`).
- Each observation records source, time, method, expected value, observed
  value when available, and operational meaning (`TM-OBS-006`).
- Every comparison is three-valued: `match`, `mismatch`, `unknown`
  (`TM-OBS-007`).
- Inaccessibility, timeout, permission failure, or parse failure is
  `unknown` — never normalized into an expected state (`TM-OBS-008`).
- The aggregate is mismatch if any check mismatched, else unknown if any is
  unknown, else match (`TM-OBS-009`).

Include deliberate negative checks — an expected `401` proving
authentication is enforced is as much a declaration as an expected `200`.

## Cost

Authoring: days, not hours — each observation kind (service, artifact,
endpoint) needs expected values declared and a probe written. Per change:
the declaration and the probe move together. Per session: seconds for the
offline read; the live read runs when the runtime is the question.

## Do not adopt when

Nothing runs — the repository declares no state outside its own tree. The
offline governed read already covers it.

## Evidence

Assessed in [inference-ops](/docs/truth-machine/implementations/inference-ops/),
whose `--live` read observes hosts, service units, remote artifacts, and
authenticated endpoints under exactly these semantics.
[cloud-ops](/docs/truth-machine/implementations/cloud-ops/) applies the
same rules to hosting state.

## Template

None — grow it inside the copied
[governed read](/docs/truth-machine/templates/governed-read/state_reader.py);
the check shape is already there.

## Related patterns

[Authority Boundary](/docs/truth-machine/kit/authority-boundary/) decides
which observed facts this repository may declare expectations about at all.