open-standards/pool/SPEC.md

Pool v0.1 — A Standard for Energy-Accounted Multi-Tenant Scheduling

Standard	pool
Status	v0.1.0 draft for review
Profile	pool/1
Licence	Specification text CC-BY-4.0 (LICENSE-SPEC); reference code Apache-2.0 (LICENSE)
Reference	pool-rs/

A vendor-neutral standard for deciding who gets contended compute, on a budget denominated in energy. Pool specifies an entitlement tree whose guarantees are microjoules and devices together, an admission rule for all-or-nothing gangs, and a preemption order derived from what workloads have actually delivered per joule.

Pool is one of the Transaction Science open standards. Transaction Science is the steward, not the proprietor.

---

1. Scope and doctrine

1.1 What Pool decides

Pool decides three questions and no others: may this claim start, what is reserved against whom, and if capacity must be reclaimed, in what order. It does not place workloads on hosts, does not read counters, and does not execute anything. Placement is the caller's; energy figures arrive already graded from whatever meter produced them (§2.3).

1.2 Energy is the unit of entitlement

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. A guarantee of "eight accelerators" cannot express "this team may spend 40 MJ this window", so under a device-denominated quota the energy budget is enforced nowhere and reconciled, if at all, after the fact.

In pool/1 an entitlement carries both a microjoule guarantee and a device guarantee, and both bind (§2.1). Devices describe what is occupied; joules describe what is spent. A claim that fits one and not the other does not fit.

1.3 A figure's grade is part of the decision

Every energy figure in pool/1 carries the grade of whatever produced it (§2.3). The grade is not a label attached after the decision; it changes the decision (§4.3). An estimate nobody measured is the figure most likely to be wrong in the direction that overcommits, and a scheduler that cannot tell a reading from a guess cannot bound that error.

1.4 Unknown is not an extreme

Where pool/1 lacks a figure it says so, and never substitutes a best or worst value for it. A ratio with no denominator is undefined (§5.1); a claim that cannot be satisfied today is distinct from one that can never be satisfied (§4.5). Both substitutions change outcomes: an undefined cost read as zero makes a workload unreclaimable, and read as infinity makes it the first victim.

---

2. Objects

2.1 The entitlement

An entitlement is a node of a tree — a department, a project, a team. It carries:

field	meaning
id	the node's name
parent	its parent, or absent for a root
guarantee_uj	microjoules it is owed and may always spend
guarantee_devices	devices it is owed and may always occupy
over_quota_weight	its relative share of a parent's surplus; 0 never borrows
limit_uj	a hard ceiling including anything borrowed; absent means the only ceiling is available surplus
priority	declared ordering, used only where evidence is absent (§5.2)

Both guarantees bind. An implementation MUST refuse a claim that exceeds either (§4).

2.2 Surplus and borrowing

Surplus is the part of a sibling's guarantee it has not spent. Siblings are nodes sharing one parent; surplus MUST NOT cross roots.

A borrower's share is its over_quota_weight against the summed weight of every node under that parent, rounded down. A borrower MUST NOT receive more than its weighted share merely by claiming first: the share is a property of the tree, not of arrival order.

2.3 Energy and its grade

An energy figure is a microjoule count and a provenance, one of:

grade	meaning
HwShunt	a counter read for this work, at its honest resolution
ModelBased	a model the host calibrated — a real curve, not a reading
Estimator	a default-power guess; nobody measured or modelled this host

HwShunt and ModelBased are observed. Estimator is not. The grade never silently improves.

2.4 The claim

A claim requests capacity for a gang — one or more members that must start together. Its figures describe the whole gang, never a member: gang_size, devices_per_member, and an estimate for the gang's total energy at its grade.

2.5 Shared devices, and what division does to a figure

Fractional accelerators are how a scheduler stops stranding capacity: several workloads on one device, each bounded by a memory fence. The fence is enforceable because memory is partitioned. Energy is not. A device-level counter reports one figure for the whole device and has no notion of which tenant caused which joule.

An attributed per-tenant figure is therefore a split of a measurement, not a measurement, and two rules follow.

Provenance degrades on division. A HwShunt device total becomes ModelBased the moment it is divided between two or more occupants, because the division is a model however good the counter was. It degrades no further and never improves: an Estimator total stays Estimator, since dividing a guess does not make it a model. Dividing by one is not a division, so a sole occupant keeps the device's own grade.

An implementation MUST NOT report a per-tenant figure from a shared device as HwShunt. That grade asserts a counter was read for this work, and on a shared device none was.

The shares sum to the measurement, exactly. Attribution is integer microjoules and MUST conserve the total: no joule invented, none lost. The remainder left by flooring is distributed by a deterministic rule — largest remainder first, ties broken on a stable key — so two implementations divide the same device the same way. Conservation is what makes a tenant's figure reconcilable against the device that produced it.

A weight basis is the operator's to choose (allotted memory, time slices, partitions). pool/1 requires only that one basis is used for every occupant of one device, and that the result is graded as the model it is.

An implementation MUST refuse to attribute a device with no occupants, or one whose occupants all carry zero weight: there is then no basis to divide on, and discarding the figure would lose energy the counter really read.

2.6 Earning an observed estimate

§4.4 refuses a guess the right to spend a neighbour's capacity. That rule is only fair if a guess can stop being a guess. On its own it is a permanent penalty with no exit: a tenant nobody has measured can never be measured, because it can never run against surplus.

The evidence already exists. Every completed claim appended a Released carrying what it actually consumed, at the grade of whatever read it (§6.2). An implementation MAY derive a claim's estimate from that history, and where it does, four rules bind.

A guess is not evidence. An observation whose own figure is Estimator is excluded, not averaged in. Nobody measured or modelled it, so it says nothing about what the work costs, and counting it would launder guesses into a grade asserting they were observed. This is what makes the exit real rather than circular: a tenant earns an observed estimate by being measured, not by having run.

A derived estimate is a model, never a reading. Its grade MUST be capped at ModelBased, even where every observation was read by a hardware counter, because a figure for the next run is a prediction. The cap is a ceiling and not a floor: modelled inputs give a modelled output.

One run is not a sample. Below a required count of evidence an implementation MUST NOT derive an estimate, and MUST report what it had — how many observations of the class it saw, and how many of those were evidence. The two say different things to an operator: plenty of history that is all guesses needs a meter, while little history needs patience. The required count is a policy value, not a derived one; pool/1 states a default of three and does not pretend to know the right number for a workload it has never seen.

The absence of a class is not a class. Comparability is the operator's assertion (§2.4), and an empty class asserts nothing. Deriving across an empty class, or across differing classes, MUST be refused rather than pooling unlike work into one figure.

A derived reservation SHOULD take the upper end of the observed figures rather than their mean. Under-reserving is the failure §4.4 exists to prevent — a reservation below what the work costs is admitted and then overspends, and the joules it overspends may be a sibling's — and a mean under-reserves roughly half the time by construction. The spread SHOULD be reported beside the reservation so a reader can see how thin the evidence is.

The limit. The maximum of a small sample is itself an underestimate of the true tail. A derived reservation is better evidence than a guess; it is not a bound on what the work can cost, and pool/1 does not claim it is one.

2.7 Reclaiming capacity from work that is not working

A workload holding accelerators while consuming almost no energy is holding capacity it is not using. A device ledger cannot see this: a held device is a held device, whether it is saturated or parked at an interactive prompt. Energy can, which makes idle reclamation a question pool/1 can ask at all.

It is also the most dangerous question in this standard, because the obvious implementation destroys running work. The reading "this workload spent 0 µJ" arrives identically from a workload that is genuinely parked and from a meter that is not there:

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

Unknown is not idle. A figure nobody measured or modelled (Estimator) MUST NOT establish idleness, whatever its value. A workload is reclaimed on evidence that it is idle, never on the absence of evidence that it is busy. An implementation MUST test the grade before comparing the value to any threshold, so that no threshold setting can let a guess through.

Idleness is a rate over a stated window, never an instant. Any workload is momentarily between steps. An implementation MUST state the window a verdict rests on, and MUST NOT reach a verdict from an observation shorter than the window it requires: startup is not idleness. A window of zero yields no rate — not a rate of zero, which is the one value that reads as idle.

A workload holding no devices is not a candidate. It occupies no contended capacity, so there is nothing to reclaim.

The verdicts are distinct. Idle, working, no verdict and nothing held are four answers, and only the first permits reclamation. A workload with no verdict MUST be absent from a reclamation ordering rather than ranked last in it: it is not a worse candidate than an idle workload, it is not a candidate.

The check order is therefore normative: nothing held, then the window, then the grade, then the rate. A later check never rescues an earlier refusal.

Why there is no default threshold. A parked accelerator still draws power. A threshold has to sit above the hardware's idle draw or nothing is ever idle, and below its working draw or everything is — and both are properties of the device, not of this standard. pool/1 does not guess them. An unconfigured policy MUST reclaim nothing: the failure of an unconfigured destructive action should be a missed optimisation, not destroyed work.

This is not preemption. §5.2 answers who is spending badly under contention, ranking by cost per completed unit. This answers who is not spending at all. A workload burning energy while completing nothing is thrashing, not idle, and §5.2 is the question that catches it.

---

3. Reservation

On admission the claim's whole estimated energy is reserved against the entitlement before the work runs. Two claims decided in the same window therefore cannot both spend the same joule.

A reservation is only as sound as the figure behind it, so the verdict carries that figure's grade (§4.6). An implementation MUST NOT report a reservation without it.

---

4. Admission

An implementation MUST evaluate a claim in the order below. The order is normative because a different order yields a different verdict.

4.1 Resolution and shape

A claim naming an entitlement the pool does not hold is refused. A gang of no members, or members occupying no devices, is refused: it is not a claim on anything.

4.2 Impossibility before pendency

A claim whose devices exceed guarantee_devices, or whose energy exceeds limit_uj, is refused before any test that could queue it. Queueing a claim that can never be satisfied fills a queue with work that will never run and reports it as pending.

4.3 Inside the guarantee

If the entitlement's spent energy plus the claim's estimate is within guarantee_uj, and its held devices plus the claim's devices are within guarantee_devices, the claim is admitted — at any grade. A tenant may spend its own guarantee on a guess.

4.4 Past the guarantee: an unobserved estimate does not borrow

A claim exceeding guarantee_uj may be admitted only against borrowed surplus, and only if all hold:

1. its estimate is observed (§2.3) — an Estimator figure MUST NOT draw on surplus;
2. its entitlement's over_quota_weight is non-zero;
3. the total after admission is within limit_uj, where one is set;
4. the borrowed part is within the entitlement's weighted share (§2.2).

Rule 1 is the substance of §1.3. Inside its own guarantee a tenant bears its own mis-estimate. Surplus belongs to a sibling that has not spent it, and an unobserved estimate is not a sound basis for spending it.

4.5 Pending and refused are different verdicts

A claim that does not fit now is Queue, with the reason: the guarantee is exhausted and it may not borrow, the surplus is insufficient, or the devices are held. A claim that can never fit as written is Deny, with the reason. An implementation MUST NOT report the second as the first.

4.6 The verdict

An admission carries the reserved microjoules, the devices, how much of the reservation was borrowed, and the grade of the estimate it rests on.

---

5. Preemption

5.1 Realised cost

A running workload's realised cost is its spent microjoules divided by the units it has completed — not attempted. Where nothing has completed the ratio is undefined, and an implementation MUST represent it as such (§1.4).

Completion is what makes the ratio meaningful: energy spent on work that was abandoned is waste, and a denominator of attempts would score a workload well for failing quickly.

5.2 The order

Capacity is reclaimed in this order:

1. Workloads with a defined realised cost, most expensive first. There is evidence they are spending badly.
2. Workloads with an undefined realised cost, lowest priority first. They are unmeasured, not wasteful.

Ties MUST break on a stable key so the order is total and a replay reproduces it.

An implementation MUST NOT rank an unmeasured workload as though its cost were known. Reclaiming unmeasured work first destroys the work that would have produced the measurement, so the scheduler never learns anything about it.

---

6. The entitlement ledger

6.1 Usage is derived, not stored

A scheduler that restarts with empty usage hands every tenant its whole guarantee back, and admits the next claim against a budget already spent. A quota that refills on every deploy, crash or config reload is not a quota.

An implementation MUST be able to rebuild every entitlement's usage by replaying its own ledger. The ledger is the durable state; there is no second store to drift from it.

6.2 What moves the ledger

Two events, and only two:

event	effect
Admitted	the claim's estimate is reserved against its entitlement, and the class it declared is recorded beside it
Released	the reservation is lifted and the actual figure charged in its place

The class is recorded in the Admitted entry rather than kept by the scheduler. §6.1 makes the ledger the only durable state, and a caller-side map from claim to class would be exactly the second store that can drift from it. Without it the history cannot be read back as evidence about a kind of work, which is what §2.6 needs.

A Queue or a Deny reserves nothing and changes no tenant's usage, so it is not a ledger event. Recording it would make the ledger a decision log — a different artifact, with a different retention story.

On release the actual figure replaces the reservation; it is not added to it. The reservation was a hold on capacity, and what the tenant spent is what it spent. An admission still open at the end of a stream keeps its reservation, because the work is still running and the capacity is still held.

6.3 Overrun

A workload that exceeds its estimate is charged what it cost (§6.2). The reservation bounded what could start, not what was ultimately spent (§8). Attribution of the overrun is what the grade on each figure is for.

6.4 The chain

Entries are hash-chained: each records the hash of the entry before it, from a genesis sentinel. Replay MUST verify the chain before deriving any usage, and MUST report the index of the first broken link rather than a shorter history.

A release naming a claim that was never admitted, or was released already, is an inconsistent stream and MUST be refused at its index. It is not a shorter history; it is a history that did not happen.

6.5 The sealed entry

Each entry is a pool/1 JCR-1 receipt: a canonical det-CBOR signed core (RFC 8949 §4.2.1 — length-first key order, shortest integer form, no floats, bools or nulls) inside a COSE_Sign1 envelope (RFC 9052, EdDSA/Ed25519, alg = -8), with the steward's identifier as kid. The core carries pool_receipt, seq, prev, steward, and the event's own fields.

This is the wire format the rest of this family seals with, so a pool/1 receipt verifies under a tool that has never heard of Pool.

Two properties, kept distinct because they fail separately, and an implementation MUST check both:

• Authenticity. Every entry verifies under the steward's key. An entry this steward did not seal is refused, whoever wrote the file.
• Sequence. Every entry's seq is its position and its prev is the content address of the entry before it, from a genesis sentinel.

Neither alone suffices. Signatures without a chain admit a bag of valid receipts in any order with any subset removed; a chain without signatures admits a consistent stream written by anyone.

6.6 Canonicity is checked, not assumed

A signature covers exact bytes. A verifier that accepted a non-canonical encoding of the same document would let two distinct byte strings share one signature, so an implementation MUST refuse a core that decodes but does not re-encode to the bytes it arrived as.

6.7 Witnessing

A steward seals its own decisions, so a ledger alone establishes that this steward wrote this sequence — nothing more. A steward able to rewrite its whole stream can rewrite a consistent one, because it holds the only key involved.

A witness is a party holding a key the steward does not. It signs the ledger's head at a stated length, producing a pool-witness/1 receipt: a statement that the chain reached exactly that head at exactly that length. A steward that later rewrites its history produces a different head, and the receipt no longer covers it.

An implementation MUST refuse a witness whose key is the steward's. A countersignature from the party being countersigned establishes nothing, and reporting it as a witnessed ledger would be the most misleading reading of the word available.

6.8 Attestation is a grade, not a gate

An unwitnessed ledger is still a ledger. An implementation MUST grade it self-attested rather than refuse it, and MUST NOT report a self-attested ledger and a witnessed one as the same thing. The reader weighs the difference; the standard's duty is to make it legible.

A receipt that verifies but covers a different head or length is distinct from one that does not verify at all, and an implementation MUST distinguish them. The second is a bad signature; the first is what a rewritten history looks like from the outside, and it is the more interesting of the two.

---

7. Conformance

A conforming implementation MUST:

1. Enforce both guarantees of §2.1, refusing a claim that exceeds either.
2. Confine surplus to siblings under one parent, and bound a borrower by its weighted share (§2.2).
3. Carry a grade with every energy figure, and never improve it silently (§2.3).
4. Evaluate admission in the order of §4, refusing the impossible before queueing anything (§4.2).
5. Refuse surplus to an unobserved estimate (§4.4).
6. Distinguish Queue from Deny, with a reason on each (§4.5).
7. Report a reservation together with the grade it rests on (§3, §4.6).
8. Represent an undefined realised cost as undefined (§5.1).
9. Order preemption by evidence before declaration (§5.2).
10. Rebuild usage by replaying its own ledger (§6.1), verifying the chain before deriving anything from it (§6.4).
11. Charge the actual figure in place of the reservation on release, not in addition to it (§6.2).
12. Refuse an inconsistent stream at its index rather than treating it as a shorter history (§6.4).
13. Seal every ledger entry as a pool/1 JCR-1 receipt, and verify both its authenticity and its place in the chain before deriving anything from it (§6.5).
14. Refuse a signed core that is not canonical (§6.6).
15. Refuse a witness whose key is the steward's (§6.7).
16. Grade an unwitnessed ledger self-attested rather than refusing it, and never report it as witnessed (§6.8).
17. Distinguish a witness receipt that does not verify from one that verifies and covers a different head (§6.8).
18. Degrade a divided figure's provenance, never report a shared device's per-tenant figure as HwShunt, and never improve a grade by dividing it (§2.5).
19. Conserve a device total exactly across its occupants, distributing the remainder by a deterministic rule (§2.5).
20. Refuse to attribute a device with no occupants or no weight (§2.5).

An implementation that derives estimates from history MUST also:

21. Exclude Estimator observations from the evidence rather than averaging them in, and report the two counts separately when it declines (§2.6).
22. Cap a derived estimate's grade at ModelBased, however the observations were read (§2.6).
23. Derive nothing below the required count of evidence, and treat a required count of zero as one (§2.6).
24. Refuse an empty class, and never pool observations of differing classes into one figure (§2.6).

An implementation that reclaims idle capacity MUST also:

25. Refuse to establish idleness from an Estimator figure, testing the grade before comparing any value to a threshold (§2.7).
26. Require a stated window, reach no verdict below it, and treat an empty window as no rate rather than a rate of zero (§2.7).
27. Omit a workload with no verdict from a reclamation ordering rather than ranking it last (§2.7).
28. Reclaim nothing under an unconfigured policy (§2.7).

---

8. The honest limit

pool/1 decides. It does not measure, place or execute, and a verdict is only as sound as the figures handed to it: a mis-graded estimate produces a sound decision about an unsound number. The grade travels with every figure (§2.3) so that a reader of a verdict can see which it was, but nothing here can detect a meter that lies about its own provenance.

Reservation (§3) bounds what may be started, not what is ultimately spent. A workload that overruns its estimate is a reconciliation problem for the accounting layer, not an admission problem; pool/1 reserves the estimate and records its grade so that the overrun is attributable.

A witness is available, and nothing compels one. §6.7 gives a second party a way to sign the ledger's head, so a rewritten history stops being covered. What pool/1 does not do is require it: an unwitnessed ledger is graded self-attested and still verifies (§6.8). So the guarantee a reader actually holds depends on a deployment choice the standard makes legible rather than makes for them.

A witness attests the sequence, not the decisions. A countersigned head establishes that the steward did not rewrite what it had already published. It does not establish that an admission was correct, that an estimate was honest, or that the witness examined anything beyond the head it signed. A witness is evidence against revision, not a second opinion on the scheduling.