open-standards/pool/README.md

# Pool — Energy-Accounted Multi-Tenant Scheduling

**Version:** 0.1.0-draft.1 · **Status:** Draft · **Profile:** `pool/1`
**Specification text:** CC-BY-4.0 · **Reference code (`pool-rs/`):** Apache-2.0

Pool is the open standard for **deciding who gets contended compute, on a
budget denominated in energy**. An entitlement guarantees microjoules and
devices together; a gang is admitted whole or not at all; and when capacity
must be reclaimed, the order follows what workloads have delivered per joule.

Pool is one of the [Transaction Science open standards](../README.md).

## Why energy is the unit

A device count is a proxy for the thing consumed. The quantity that is paid
for, drawn from a grid and reported under an energy-disclosure regime is
energy — so a guarantee expressed only in accelerators leaves the energy budget
enforced nowhere and reconciled after the fact, if at all. In `pool/1` both
bind: devices describe what is occupied, joules describe what is spent.

## Three rules that need the energy unit

1. **A guess may not spend a neighbour's capacity** (SPEC §4.4). A claim whose
   estimate is `Estimator` — nobody measured or modelled it — is admitted only
   inside its own guarantee, never against surplus borrowed from a sibling. A
   tenant may bear its own mis-estimate; a sibling's unspent joules are not
   the tenant's to gamble.
2. **A gang is all-or-nothing in joules, not only in slots** (SPEC §2.4).
   Admitting part of a gang against a budget that cannot finish the whole gang
   spends real energy and delivers nothing.
3. **Preemption follows evidence, then declaration** (SPEC §5.2). Workloads
   with a measured cost per *completed* unit are reclaimed worst-first.
   Workloads that have completed nothing are unmeasured rather than wasteful,
   and fall back to declared priority — reclaiming them first would destroy
   the work that would have produced the measurement.

## Sharing a device, and what it costs a figure

Fractional accelerators stop capacity being stranded, and their memory fence is
enforceable because memory is partitioned. **Energy is not** — a device counter
reports one number for the whole device and cannot see tenants. So a per-tenant
figure is a split of a measurement, not a measurement (SPEC §2.5):

- **Provenance degrades on division.** A `HwShunt` device total becomes
  `ModelBased` as soon as it is split between two occupants. It never improves:
  dividing an `Estimator` guess does not make it a model. Dividing by one is
  not a division, so a sole occupant keeps the device's grade.
- **The shares sum to the measurement exactly** — integer microjoules, largest
  remainder, deterministic tie-break. Conservation is what makes a tenant's
  figure reconcilable against the device that produced it.

## A guess earns its way out

The admission rule that a guess may not spend a neighbour's capacity is only
fair if a guess can stop being one. The evidence is already in the ledger —
every completed claim recorded what it actually consumed — so an estimate can
be derived from what this *kind* of work really cost (SPEC §2.6):

- **A guess is not evidence.** `Estimator` observations are excluded, not
  averaged in. A tenant earns an observed estimate by being measured, not by
  having run.
- **A derived estimate is a model, never a reading** — capped at `ModelBased`
  even where every observation came from a counter, because a figure for the
  *next* run is a prediction.
- **One run is not a sample.** Below the required count nothing is derived, and
  the counts are reported: history that is all guesses needs a meter, while
  little history needs patience.
- **The absence of a class is not a class.** Comparability is the operator's
  assertion, so an empty class is refused rather than pooling unlike work.

The reservation takes the largest observed figure rather than the mean, because
under-reserving is the failure the borrowing rule exists to prevent. The limit
is stated: the maximum of a small sample underestimates the true tail.

## Reclaiming what is not working

A workload holding accelerators while spending almost no energy is holding
capacity it is not using — something a device count cannot see, since a held
device is a held device whether saturated or parked. It is also the most
dangerous question here, because the obvious implementation destroys running
work: *"spent 0 µJ"* arrives identically from a parked workload and from a
meter that is not there (SPEC §2.7).

```
  meter unavailable → 0 µJ → "idle" → reclaim → running work destroyed
```

So **unknown is not idle**, and the grade is tested *before* the value meets
any threshold — no threshold setting can let a guess through. Idleness is a
rate over a stated window, never an instant; startup is not idleness; an empty
window yields no rate rather than a rate of zero. A workload with no verdict is
**absent** from a reclamation ordering rather than ranked last in it: it is not
a worse candidate than an idle one, it is not a candidate.

There is no default threshold, because one has to sit above the hardware's idle
draw and below its working draw, and both belong to the device. An
unconfigured policy reclaims nothing — the failure of an unconfigured
destructive action should be a missed optimisation, not destroyed work.

## Usage survives the process

A scheduler that restarts with empty usage hands every tenant its whole
guarantee back. `pool/1` rebuilds every entitlement's usage by replaying its
own hash-chained ledger (SPEC §6), so the ledger is the durable state rather
than a report about it. On release the **actual** figure replaces the
reservation — the hold bounded what could start, not what was spent — and a
stream that does not verify is refused at the index of its first broken link.

Each entry is a **`pool/1` JCR-1 receipt** — canonical det-CBOR under
COSE_Sign1 with Ed25519, the wire format the rest of this family seals with,
so it verifies under a tool that has never heard of Pool (SPEC §6.5).
Authenticity and sequence are checked separately because they fail separately:
signatures without a chain admit a bag of valid receipts with any subset
removed, and a chain without signatures admits a consistent stream written by
anyone. A core that decodes but does not re-encode to the bytes it arrived as
is refused, so two encodings cannot share one signature (§6.6).

A **witness** — a party holding a key the steward does not — can sign the
ledger's head at a stated length (SPEC §6.7). A steward that later rewrites
its history produces a different head, and the receipt stops covering it. A
witness key equal to the steward's is refused outright: a countersignature
from the party being countersigned establishes nothing.

An unwitnessed ledger is still a ledger, graded `self-attested` rather than
refused (§6.8) — the reader weighs the difference, and the standard's duty is
to make it legible. What a witness establishes is bounded too: it is evidence
against revision, not a second opinion on whether an admission was right (§8).

## What it does not do

`pool/1` decides admission and preemption order. It does not place workloads,
read counters or execute anything (SPEC §1.1, §8). Energy figures arrive
already graded from whatever meter produced them, and a verdict is only as
sound as the figure behind it — which is why the grade is part of the verdict
rather than a footnote to it.

## Reference

[`pool-rs/crates/pool-core`](pool-rs/crates/pool-core) — the admission and
preemption kernel: the entitlement tree, weighted surplus, the §4 admission
order, and the §5.2 preemption order.