# Governed Read

> A copied, owned, offline reader script that compares the declared current projection with the working tree and exits match, mismatch, or unknown.

**Tier:** 1 · **Normative weight:** implements `TM-OBS-001`, `TM-OBS-002`,
`TM-OBS-003`
**Requires:** [Typed Current Projection](/docs/truth-machine/kit/current-projection/)

## Problem it removes

The current projection and the human index are only as trustworthy as the
last person who remembered to update both. Without a check, agreement is a
habit; with one, disagreement is an exit code.

## Mechanism

A single stdlib-only script — copy it, own it, never import it — that loads
`current.toml`, verifies declared artifact digests against the working
tree, and asserts the human index names every declared record. Every check
carries an `id`, a `source` (where the observation came from), and a
`meaning` (what a failure signifies), which is what makes the read's
provenance inspectable (`TM-OBS-002`). Output is deterministic
(`TM-OBS-001`), available as prose or `--json`, and the script mutates
nothing and repairs nothing (`TM-OBS-003`) — a detected mismatch routes
back through ordinary review.

Exit codes are the contract: `0` match, `1` mismatch, `2` unknown. A check
that could not run — unreadable file, failed subprocess — is unknown, never
a pass. The read's material uncertainty is part of its answer: `unknown`
checks degrade the aggregate, so a partially observable tree never reads as
fully verified. That rule reaches the declaration itself: a malformed
projection entry becomes an `unknown` check naming the entry, never a
silent skip. The
`--json` form is published as
[`read-result.schema.json`](/docs/truth-machine/schemas/read-result.schema.json).

The template is a genuinely minimal skeleton, generalized from four
production readers. Real repositories grow it: live service checks, packet
grammar validation, cross-repository ownership seams. Grow yours in place;
that is what owning the copy means.

## Cost

Authoring: an afternoon to adapt the template to what the projection
declares. Per change: extend a check when the projection grows a new entry
type. Per session: seconds — it becomes the first command of any operating
session.

## Do not adopt when

There is no typed projection to read, or the repository's checks already
live in an adequate test suite. Adopt the projection first; the reader is
meaningless without it.

## Evidence

Assessed in [inference-ops](/docs/truth-machine/implementations/inference-ops/),
[cloud-ops](/docs/truth-machine/implementations/cloud-ops/), and
[kinra-corpus](/docs/truth-machine/implementations/kinra-corpus/) — four
independent readers, including this repository's own, share the shape the
template distills. The [flow](/docs/truth-machine/implementations/flow/)
read path applies the same contract inside an application.

## Template

[`templates/governed-read/state_reader.py`](/docs/truth-machine/templates/governed-read/state_reader.py)

## Related patterns

[Declared Versus Observed](/docs/truth-machine/kit/declared-versus-observed/)
extends the reader beyond the repository boundary to live systems.