# 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.