# Evidence basis — where we know, and where we guess

A counted object and an assumed hourly rate are both numbers. They are not both
knowledge. Every quantity in this repository declares **how it was obtained**,
so a decision can be graded by the weakest thing it actually rests on.

**The vocabulary is canon, owned by ITC-GOV.** resource-control originated the
concept, filed it as `demand/EvidenceBasis.md`, and info-tech-canon adopted it in
canon 0.4.0 as `infospace/models/governance/evidence-basis.yaml`. `tools/basis.py`
now *reads* that catalog rather than defining its own — the same discipline we
apply to the capability catalog. Drift in either repository fails our suite.
`CAP-R10` requires a basis on every `CapabilityConsumption` row.

## The scale

Strength is a **tier**, not a total order. Members of one tier are peers and do
not rank against each other — asserting an order between them would make the
propagation rule claim something it cannot know.

| Tier | Rank | Bases | Example here |
|---|---|---|---|
| `observed` | 0 | `invoiced`, `measured` | 8 objects, 6 604 031 B in the backup prefix |
| `quoted` | 1 | `quoted` | Scaleway €0.01606/GB-month |
| `projected` | 2 | `projected` | 457.968 GB stored at month 12 |
| `judgement` | 3 | `estimated`, `assumed` | apps-pg 6 operator-hours setup; €60/hour rate |
| `unknown` | 4 | `unknown` | railiance01 monthly price |

`derived` belongs to **no tier**: it resolves against its inputs, and asking for
its tier before resolution is an error.

`observed` and `quoted` are both **evidenced** — they assert an observed or
contracted fact. `quoted` sits below `observed` for propagation while still
counting as evidenced for a decision grade; the canon separates those two uses
deliberately, because a counterparty's stated price is a fact about a claim and
a measurement is a fact about the world.

An invoice is authoritative for a payment and a measurement is authoritative for
a quantity, so neither outranks the other — they are peers in `observed`. Our
first implementation used a strict list order and got this wrong; the canon
carries the corrected form as a normative rule.

## The propagation rule

> A derived value is only as strong as its weakest input.

Without this rule a precise-looking figure launders weak assumptions. The
monthly labour line for the backup store is €60.00, which reads like a
measurement. It is `derived` from an `assumed` operator-hour allowance and an
`assumed` hourly rate, so it resolves to **`assumed`** — the weakest class of
input we have.

Deriving in the other direction is not penalised: GB computed from measured
bytes resolves to `measured`, because both inputs are.

## Two orthogonal qualifiers

**`proxy_for`** — the value is a genuine measurement of a *different* quantity
than the one being reasoned about. It does not weaken the measurement; it
weakens the inference. The apps-pg allocation driver measures database bytes
accurately, and one of those databases has never recorded a transaction, so as
a driver for cost it is a proxy whose validity is separate from its precision.

**`observed_at`** — a measurement has an age. A single sample from a
four-hour-old resource is `measured` and still thin.

## Unknown is never zero

A value with basis `unknown` carries no quantity and must name the gap and its
owner. A value with any other basis must carry a quantity. Zero means "measured
and none"; unknown means "not measured". The validator enforces both directions.

## Decision grades

`decision_grade(values)` reports the distribution, the weakest basis, the
evidenced ratio, and a grade:

| Grade | Condition |
|---|---|
| `evidenced` | Every load-bearing value is invoiced, measured, or quoted |
| `projected` | The conclusion rests on values projected from observations |
| `indicative` | The conclusion is no stronger than an estimated or assumed value |
| `insufficient` | At least one load-bearing value is unknown |

### The first real application

The provider comparison that selected Scaleway over Hetzner — a €29.14/month
difference stated to the cent — grades **`indicative`**:

```
by_basis: {quoted: 1, projected: 1, assumed: 2}
weakest:  assumed
evidenced_ratio: 0.25
```

One of four load-bearing values is evidenced. The two labour figures, which are
what actually inverted the ranking, are both `assumed` on top of `assumed`.

This does not overturn the decision. The direction is robust — Hetzner needs
more operator time under any plausible rate, and the alternative was five times
dearer. But it does say plainly that the *magnitude* is a model output, not a
measurement, and that the cheapest way to strengthen it is to record real
operator hours rather than to refine the arithmetic.

That is the whole purpose of the scale: to make the difference between a firm
conclusion and a confident-looking one visible before it is acted on.

## Where it applies today

- `data/capability/*.json` — every consumption row and evidence item.
- Provider comparisons carried in a capability restatement.

Not yet retrofitted: `data/actuals/`, `data/control-cycle/`, and the option
fields of `data/optimization/`. Those already distinguish known from unknown and
carry `measurement_gaps` and `uncertainty` notes, but they do not yet grade a
present value. That is the next step, and it is the one that would let
`make thresholds` report a breach alongside the strength of the evidence
producing it.