WAI Extension: Route Record

Mirrored from the canonical text at commit 260cbd09 (2026-11-08).

Status: Draft. Registers the record wai.route.record: what a router considered for one media job and why it chose. A job names an operation of WAI’s catalogue, a capability and a fallback (SPEC §4), the quantities it expects, hard limits that remove candidates and soft preferences that reorder the rest. A router reads its candidates from a price book, removes those a hard limit removes, ranks the survivors under a named and versioned routing policy, tries them in that order, and signs a route record: every candidate with the figures the price book stated for it and the limits that removed it, the order, the decision and why, and every attempt with its hop’s OER/2 receipt and whether it was billed. A verifier given the record, the request, the price book and the policy recomputes the candidates, every removal, the ranking, the order and the decision, holds the attempts to the order and the billing rules, and, given the hops’ receipts, holds each attempt to its receipt; it refuses a record those inputs do not give. No transport, no payment and no account: a route record is the recomputable account of a routing decision. The reference implementation is the route_record module of wai-rs (feature route_record); the corpus is live-conformance/routes/, and its second implementation is live-conformance/route_record_verify.py. Keywords MUST, MUST NOT, SHOULD, MAY are RFC 2119/8174.

This revision adds version 2 of the price book and of the record (§3.4): an entry prices one operation of an endpoint, so an encode and a decode are estimated, capped and ranked at their own prices; it states the endpoint’s measured failures with their basis, and the ranking reads the expected cost and the expected time to first byte per successful job they give (§4.2, §4.4), while the job pays the list price; and the attempt that served states its outputs, to which its hop’s receipt is held (§6). Documents and records of version 1 are read and verified exactly as before.

This revision adds version 3 of the record (§3.4), on a price book of version 2: the attempt that served states what it delivered by its count and the root its hop’s receipt names (§5.2, §6), not by a list, so a hop may deliver any number of objects and the record is the same size whatever it delivered; an object is shown to be one of them by its inclusion proof (§6.1). Records of versions 1 and 2 are read and verified exactly as before.

This revision adds the third-party hop record (§6.2): what a router sent a third party for one hop, what came back and what the provider bills, signed by the router and bound to the hop’s attempt and receipt. A verification document without one is read exactly as before.

This revision adds the delivery-decision record (§6.3): why a delivery of a job’s output took the route it took. A delivery is routed as a job is, from its own request, price book and policy (§3, §4); its record states every route considered with the figures its price book stated and the limits that removed it, the rule that chose and by which key each other route was passed over, and every input it read by digest. It is signed by the job’s router, names the job’s route record as its parent and the delivery decided before it, and holds what it delivers to what the job’s served hop delivered. A verification document without one is read exactly as before.

This revision adds version 3 of the price book and version 2 of the delivery-decision record (§3.4, §6.4): an entry states its energy figure’s declared uncertainty; a decision states its offer, what its route was taken at; and a verifier given the route’s OER/2 receipt holds it to the decision and to the offer: graded no higher than the offer, its figure within one declared uncertainty of the offer’s, or flagged price_exceeded by the hop that signed it. Documents and records of earlier versions are read and verified exactly as before.

Texts read for this revision: the WAI texts this one cites; RFC 8259; RFC 8785; RFC 8032; ISO 4217 (the alphabetic currency code); FIPS 180-4; the BLAKE3 specification.

1. Scope

In scope: the three documents a routing decision rests on, the request, the price book and the policy (§3); how a router computes its candidates, their removals, their ranking and its decision from them (§4); the record, its attempts and its signature (§5); how an attempt is held to its hop’s OER/2 receipt, and in versions 2 and 3 to the outputs it delivered (§6); an output’s inclusion proof (§6.1); a third party’s hop (§6.2); a delivery’s decision, routed as a job is and chained to its job’s record (§6.3); a delivery’s offer and its route’s receipt (§6.4); verification (§7); and the reference implementation and corpus (§10).

Out of scope: a transport; how a router learns its prices and measures its endpoints’ failures, which the price book states and this extension takes as stated; accounts, credit and payment; the contents of the job’s output and its own receipts, which their extensions define (a record of version 2 names the output by its content hash and nothing more, and one of version 3 by its count and root); and the energy of a hop, which its OER/2 receipt states (oer-receipts). An invoice that bills a job from its route record is the receipt ledger’s (receipt-ledger §5).

Relationship to the core spec: wai.route.record is a record (SPEC §5): a signed record a WAI tool emits and verifies. It names no payload format and is not dispatchable.

2. Terms and encodings

• Router: an Ed25519 key (RFC 8032) that signs route records. Signer: the record’s signer.
• Time: microseconds since 1970-01-01T00:00:00Z, an integer.
• Amount: an integer of millionths of a currency’s minor unit (ISO 4217), as the receipt ledger’s amounts are (receipt-ledger §2). A price is an amount per divisor units of a unit.
• Document: a JSON text (RFC 8259) read strictly: no member name repeated within an object, no string holding an unpaired surrogate, arrays and objects nested at most 64 deep (the document counting as one), and every number an integer from 0 to 2⁵³ − 1 written in plain decimal (no sign, fraction or exponent). A text that is not such a document is malformed. Every value of a document is therefore in the subset RFC 8785 canonicalises without a choice (the subset wai::jcs writes), and its canonical form is RFC 8785’s.
• Digest: SHA-256 (FIPS 180-4) over a document’s canonical form, written as 64 lowercase hexadecimal digits.
• Token: a string of 1 to 128 bytes, each an ASCII letter or digit or one of ., _, -, : and /. Endpoints, providers, regions, residencies and a policy’s name are tokens. Tokens are ordered by their bytes.
• Unit: a string of 1 to 64 bytes, a lowercase ASCII letter and then lowercase letters, digits and _ (subpixels, seconds, packages): the name of what a quantity counts.
• Capability: a string of 1 to 128 bytes of lowercase ASCII letters, digits, _ and ., beginning wai.: a capability of WAI’s registry (SPEC §5), which a router SHOULD name only when it is registered.
• Operation: the id of an operation of WAI’s catalogue (wai/catalogue/ops.json): two words joined by ., each a lowercase ASCII letter and then lowercase letters and digits (media.encode).
• Key and signature: 64 and 128 lowercase hexadecimal digits.
• Content hash: an object’s content hash as jwp-receipts §2.1 computes it, BLAKE3-256 over the domain moq-jwp:object\x01 and the object’s bytes (a WAI envelope’s whole bytes, for an envelope), written as 64 lowercase hexadecimal digits.
• Basis: the hops a measured figure was read from and the period they were sent in (§3.2.1).
• Class: an acquisition class of energy-measurement §2, by its label: CalibratedInstrument, OnChipCounter, ModelBased or Estimator.
• Grade: an evidential grade of oer-receipts §2, by its label: projected, simulated, derived or measured, weakest first.
• ⌊x⌋ is x rounded down; products are computed in integers wide enough not to overflow.

3. The documents

Each document is an object of exactly the members its table lists, each of its form; a document that breaks a rule of this section is refused with its own reason (request_invalid, pricebook_invalid, policy_invalid).

3.1 The request

What the job asked for, as the router received it.

limits, the hard limits:

3.2 The price book

What each endpoint offers and costs, as the router read it. A price book is of version 1, 2 or 3 (§3.4); one of version 1 has no version member and its entries neither operation nor failures, and only the entries of version 3 state energy_ppm.

An entry:

A price book states each figure as its endpoint’s provider gave it, and its failures as the router measured them; a value that is not known is null, and §4.3 reads every null limit as the most restrictive value.

In version 2 an entry prices one operation of one endpoint, and an endpoint has an entry for each operation it serves, each with its own price, figures and failures. Within one capability an encode (a motion search, then a codestream written) and a decode (a reconstruction) spend different energy and are priced differently: one entry for both would misstate one of them to the estimates (§4.2), to the unit-price limit (§4.3) and to the ranking (§4.4).

3.2.1 Failures (version 2)

failures states how often the endpoint’s hops of the entry’s operation failed, what the provider billed for those failures, and how long they took, with the basis they were read from. It is an object of exactly:

hops, from and to are the basis of the three figures: the failure rate is failed over hops, and billed_price and failed_ms are read from the failed hops of the basis. When failed is 0 there is no failed hop to read them from, and both are 0: nothing was billed and no time was spent. A failures object that breaks a rule of this table is pricebook_invalid.

A thin basis. A basis of fewer than 100 hops is too thin to mean anything. A failure rate read from n hops has a 95% confidence interval of half-width up to 1.96 × ½ / √n (its widest, at a rate of one half): ±0.098 at 100 hops, and wider than ±0.1 below 97. A rate known no better than that cannot weigh one endpoint against another, and the rule rounds the bound to 100. Failures of a thin basis, and null failures, are unknown (§4.2).

3.3 The policy

How survivors are ranked and how many are tried.

A policy is named and versioned so that a deployment pins it: the record states its name, version and digest, and a policy whose rules change takes a new version.

3.4 Versions

The request and the policy have one form. The price book has three: version 1, this extension’s first; version 2, which adds the members that price an operation and state an endpoint’s failures; and version 3, version 2’s with energy_ppm in each entry, so that a delivery’s route states the uncertainty its energy is offered at (§6.4). What this text says of a price book of version 2, its entries and its candidates, it says of one of version 3. The record has three: version 1; version 2, which adds those members and names a hop’s outputs by their list; and version 3, version 2’s but for naming them by their count and root (§5.2). A record of version 1 rests on a price book of version 1, and one of version 2 or 3 on a price book of version 2 (§7.2 step 5); no record rests on a price book of version 3. A delivery-decision record of version 1 rests on a price book of version 2, and one of version 2 on a price book of version 3 (§7.2 step 10). A router writes one version of record over a price book of version 2; a reader holds each as its version says.

A reader of version 1 reads every document of version 1 as before, and refuses one of version 2 rather than misreading it: a price book with a version member, or an entry with operation or failures, is not of version 1’s members (pricebook_invalid), and a record of version 2 is unknown_version; a reader of version 2 refuses a record of version 3 so. A price book whose version is other than 2 and 3 is pricebook_invalid; a record whose version is other than 1, 2 and 3 is unknown_version, and so is a delivery-decision record whose version is other than 1 and 2.

Version 3 exists because a list bounds what a hop may deliver and grows with it: version 2 states at most 1024 outputs, and a package of a long title holds an object per piece and rung, thousands of them. The count and the root are an integer and 32 bytes whatever was delivered, and the root is the commitment the hop’s receipt already names (§6), so nothing a hop signs changes.

4. Routing

A router computes the following from the request, the price book and the policy, and a verifier computes the same. Nothing in it depends on the order of a document’s members, on the time, or on anything the three documents do not state.

4.1 Candidates

The candidates are the price book’s entries whose capability is the request’s capability, which are direct (via_fallback false), and, when the request names a fallback, those whose capability is the fallback (via_fallback true), in the price book’s order. An entry of any other capability is not a candidate, and the record does not list it. In a price book of version 2 a candidate’s entry is also of the request’s operation: an entry of another operation is not a candidate either, and since an endpoint has at most one entry of an operation, an endpoint is at most one candidate.

4.2 Estimates

For a candidate whose unit the request states a quantity q for:

• its cost is ⌊q × price / divisor⌋;
• its energy is ⌊q × energy_uj / divisor⌋ when energy_uj is stated.

An estimate is null when the request states no quantity in the candidate’s unit, when energy_uj is null (for the energy), and when it exceeds 2⁵³ − 1, which no document can state. Units are never converted: a candidate priced in seconds is estimated from the request’s seconds and from nothing else. An estimate is the router’s, from the request’s own quantities; what a job costs is what its invoice bills from its receipts.

In a price book of version 2 a candidate also has two expected figures, per successful job, which count its failures. An attempt at the endpoint fails with probability f = failed / hops and serves with s = 1 − f, attempts taken as independent; a job sent there until it is served meets f / s = failed / (hops − failed) failures on average before it is (a geometric count). Each failure costs the router what the provider bills for it, and costs the job the time it took before the next survivor ran. So, per successful job:

• its expected cost is cost + ⌊F × failed / (hops − failed)⌋, where F = ⌊q × billed_price / divisor⌋ is what the provider bills one failed hop of this job;
• its expected time to first byte is ttfb_ms + ⌊failed_ms × failed / (hops − failed)⌋, in milliseconds.

An expected figure is null when the candidate’s failures are unknown (§3.2.1), when the figure it adds to (cost, ttfb_ms) is null, when every hop of the basis failed (there is no finite expectation), and when F or the figure exceeds 2⁵³ − 1, as an estimate is.

Unknown failures are not read as no failures, which would rank an endpoint nobody measured ahead of one measured to fail rarely, nor as a worst case, which this text states nowhere: the expected figures are null, and the rules this text gives every null figure apply to them unchanged. §4.4 ranks a null after every stated figure and then, within the same key, by the list figure, as version 1 ranks every candidate; and since no limit reads failures, unknown failures remove nothing.

The job pays the list price. The expected cost is the router’s figure for ranking, of what failures cost it; the job is never charged it. The limits of §4.3 read the list price and the cost, what the job pays, and an invoice bills a job from its billed attempt alone (§5.2, receipt-ledger §5), so no failure reaches the job’s line.

4.3 Hard limits

Each candidate is held to every limit in this order, and its removals list each limit that holds, in this order, each with the candidate’s value the limit read (null when the price book does not know it):

So a value the price book does not know counts as the most restrictive one: an endpoint that does not say it never trains on its inputs is removed by no_training, one with no stated retention by zero_retention, and a cost that cannot be estimated, or a ceiling in another currency, by spend. A candidate with no removal is a survivor. In version 2 the limits read the candidate’s own entry, its operation’s, and unit_price and spend read the list price and the cost, never the expected cost (§4.2).

4.4 Ranking

The survivors are ordered by a list of keys, the key list:

1. targets, when the request’s prefer.ttfb_ms or prefer.quality is not null: a survivor meets the targets when, for each target stated, its ttfb_ms is stated and at most prefer.ttfb_ms, and its quality is stated and at least prefer.quality;
2. the request’s prefer.sort, when it is not null;
3. the policy’s keys, in its order, without prefer.sort;
4. endpoint.

Two survivors compare by the first key of the list on which they differ, and the one that comes first under that key ranks first:

A null figure comes after every stated one, and two nulls do not differ; a key of two figures compares the second only when the first does not differ. Endpoints are distinct, so the order is total. The order is the survivors’ endpoints in it, and each survivor’s rank is its position there, from 1. The energy compared is each figure as its provider states it, whatever its class: the record states every class beside its figure, so a reader sees what was compared.

Why per successful job. A router tries survivors in turn until one serves. For one quantity, cost to the router or time to the job, let an attempt at survivor i spend Cᵢ on average (sᵢ × its list figure + fᵢ × its failure’s) and serve with probability sᵢ. The attempts of an order spend C₁ + f₁C₂ + f₁f₂C₃ + … on average, each attempt weighted by the chance that every one before it failed. Exchanging two neighbours i, j changes that sum by a term whose sign is that of Cᵢ / sᵢ − Cⱼ / sⱼ, so the order that minimises it ranks by C / s = the list figure + (f / s) × the failure’s: the expected figure per successful job (§4.2). An endpoint that fails often is tried first only where it is cheaper, or faster, per job served. The policy is unchanged: it names its keys, and a price book of version 2 gives price and ttfb these figures.

4.5 The decision

decided_by is none when there is no survivor, only_survivor when there is one, and otherwise the first key of the key list on which the first two survivors of the order differ: the reason the first was tried before the second. runner_up is the second survivor’s endpoint, or null when there are fewer than two.

The number of survivors the router may try is the smaller of the survivors’ number and the policy’s max_attempts, the allowed attempts.

5. The record

5.1 Members

A route record is a document of exactly these members:

A candidate:

So a record of version 2 states, for every candidate, the failures it was ranked by with their basis, and the terms the ranking derived from them.

5.2 Attempts

An attempt is one hop the router sent the job to:

The attempts MUST follow the order: the attempt at position i names the i-th survivor of the order, and there are at most the allowed attempts (§4.5). So no attempt names a removed candidate, and no survivor is tried before one ranked above it. Only the last attempt may be served; a job whose last attempt failed was tried on every allowed survivor before the router gave up. The times are in order: accepted is at most the first attempt’s start, each attempt’s start is at most its end, and each attempt starts no earlier than the one before it ended.

Billing:

• a failed attempt is not billed, not_billed failed: a hop that returned no output costs the job nothing, whatever the provider charged the router;
• a served attempt that ended after the deadline is not billed, not_billed deadline_missed: a job that missed the deadline it declared is not billed;
• every other served attempt is billed.

So at most one attempt of a record is billed, and a reader finds the hop that served, whether it was billed and why not, and the receipt of every hop, failed ones too.

5.3 Signature and digest

The record’s sig is Ed25519 by signer over the 17 bytes wai:route-record (ASCII) and 0x01, followed by the canonical form of the record without sig. It is verified strictly, as SPEC §7 Signatures requires: a key that fails step 1 or 2 is bad_key, and a signature that fails a later step is bad_signature. The record’s digest, which names it (receipt-ledger §5.2), is the digest of the whole record, sig included.

6. Hop receipts

Every hop is receipted under oer-receipts: a job receipt whose capability is oer.job. followed by the record’s operation (oer-receipts §3), whose work.status is 1 for a hop that served and -1 for one that failed, and whose figure is the hop’s energy, or the unmetered marker where nobody measured it (oer-receipts §3.1). When a verifier is given the receipts and the keys they are published under (oer-receipts §5), it holds each attempt to its receipt:

• a receipt whose receipt_id is the attempt’s receipt is given: otherwise receipt_missing;
• it verifies under oer-receipts on its own, with no reason (§7 there): otherwise receipt_invalid;
• it is a job receipt of the record’s operation whose work.status is the attempt’s outcome’s: otherwise receipt_mismatch;
• in a record of version 2, the receipt of the attempt that served names the outputs the attempt states: its subject.output is their commitment, as oer-receipts §3 Output defines it, the content hash of the one output, or the jwp-receipts §2.2 root over their content hashes in their order, every leaf of the unlabelled form, as 64 lowercase hexadecimal digits: otherwise receipt_output_mismatch;
• in a record of version 3, its subject.output is the attempt’s root: otherwise receipt_output_mismatch.

So a receipt cannot be moved to vouch for an output it did not produce. The hop signs what it produced, in its receipt; the router signs what the job delivered and which receipt is the hop’s, in its record; and a record that pairs a hop’s receipt with outputs the receipt does not name is refused. A holder of the job’s output checks the remaining step, that its objects’ content hashes are the record’s outputs (§7.3), or in version 3 that their count is the record’s and their commitment its root: the receipt names the root alone, so the count is the router’s statement, which the objects check. The attempt that served is held to its outputs whether or not it is billed: one that served past the deadline delivered them too. A failed attempt delivered nothing, and its receipt is not held to an output.

6.1 An output’s inclusion proof (version 3)

A record of version 3 does not list what the hop delivered. A reader that must show one object to be among them, as a receipt ledger shows a billed output to be (receipt-ledger §5.1), gives that object’s inclusion proof: an object of exactly index, an integer, the object’s place in the order the hop delivered, from 0, and siblings, a list of content hashes’ texts (§2). The proof holds the object whose content hash is h to an attempt that delivered count objects under root when:

• index is below count, and siblings holds exactly ⌈log₂ count⌉ hashes, none for one object;
• for one object, h is the root (oer-receipts §3 Output); otherwise, from h’s leaf (jwp-receipts §2.2, the unlabelled form), each sibling in turn combined with the value so far by jwp-receipts §2.2’s node, the sibling on the left where bit i of index is 1 and on the right where it is 0, at level i from 0, ends at root.

A router makes it from the tree §6 commits to: the sibling at each level, the last node of an odd level paired with itself. The count and the bits fix the place, as jwp-receipts §3 step 5 fixes an object’s, so a node paired with itself is proved at its own index only, and two proofs at one index are of one object. The leaf and node domains alone keep a walk of another length from ending at the root; the number of siblings is checked all the same, as jwp-receipts checks it, so such a proof is refused before anything is hashed. This extension’s verification (§7) is given no object and checks no proof; the reader that is given them checks it, with its own refusal.

A receipt states the hop’s energy with its grade, and, in minor version 1, its class or the unmetered marker; the record states no figure of its own. A reader of the hops’ energy reads it from their receipts, and an invoice bills a job from them (receipt-ledger §5).

6.2 A third party’s hop

A hop a router sends to a third party’s endpoint is work it did not do: the provider did it, behind an API the router called. Its receipt (§6) is the router’s, and says the hop served or failed; what the router sent, to whom, what came back, when, and what the provider bills, it states in a third-party hop record, a document (§2) of exactly these members:

An exchange is one HTTP request and what came back:

A record that is not of these members, each of its form, is third_party_invalid, and so is one whose json holds a string that begins https:// or http:// and holds a ? or a #. No secret is in it. The key the hop ran on is never stated, only whose account it is; an exchange states no header, since a key travels in one; and every URL is stated without its query, since a provider’s signed download link is a bearer token, its query the key to the object. What was sent and received is named by digest and length, which a holder of the bytes checks, and the response is kept as JSON where the provider answered with JSON, so that what it said about the job (its id, its status, the usage it billed) can be read from the record itself.

The record is signed by the router, over the domain wai:route-third-party-hop\x01 and the canonical form of the record without sig, under the strict rule of SPEC §7, and named by its digest (§2), over its canonical form with sig. It is bound to its hop: given the route record and the hop receipts (§7.2 step 9), a record is held to

• the route record’s router: its signer is the record’s, and its job the record’s;
• its attempt: hop names one, whose endpoint, receipt and outcome are the record’s and, when it failed, whose error is the record’s error.class; whose candidate’s provider is its provider, and whose candidate’s unit is its usage.unit when it states a usage; and whose start is at most the record’s start and whose end at least its end. No two records are of one hop. Otherwise third_party_mismatch;
• what the hop delivered: when it served, the commitment of its outputs’ content hashes in their order (oer-receipts §3 Output) is its receipt’s subject.output, to which §6 holds the attempt’s outputs or root, and in a route record of version 3 their number is the attempt’s count, which the receipt does not name. Otherwise third_party_output_mismatch.

So the provider’s work is tied to the hop that paid for it: the receipt says the hop served these objects, the record says which calls produced them and what the provider bills, and the route record names both. The charge is the provider’s own figure, in its own terms, beside the usage and never added to it; a reader who compares what the provider says it charged with what a job was billed reads both from signed documents. A tariff of version 6 bills a billed hop by the record’s usage (receipt-ledger §4.9). The record states no energy figure: the hop’s receipt states it, or the unmetered marker where the provider gave none (oer-receipts §3.1).

6.3 A delivery’s decision

A job’s output is then delivered: sent to who asked for it, by one of the routes that could carry it, an origin, a cache or a bearer among them. A router that routes a delivery reads the delivery’s own documents, of §3’s forms: its request, whose job is the delivery’s id and whose quantities are what the delivery carries, unit by unit (bytes, for one); its price book, of version 2, whose entries are the routes, each priced for the operation it performs; and its policy. From them §4 computes the delivery’s candidates, every limit that removes one, the ranking, the order and the decision, as it computes a job’s. The router states why the delivery took the route it took in a delivery-decision record, a document (§2) of exactly these members:

A record that is not of these members, each of its form, is delivery_invalid; the relations between its members, and between it and its documents, its parent and the decisions before it, are those below.

Why, in full. The record restates each route as its price book stated it, with its estimates, its expected figures and every limit that removed it; it names the rule that chose, the policy by its name, version and digest, and for every survivor the key that ranked the route the delivery took above it, the runner-up’s being the decision’s decided_by; and it names by digest every input the rule read: the delivery’s three documents and, by its parent, the job and the objects it delivers. A verifier recomputes all of it (§7.2 step 10), so a router cannot state a route the rule did not choose, nor a reason it did not have.

Signed and chained. The record is signed by the job’s router, over the domain wai:route-delivery-decision\x01 and the canonical form of the record without sig, under the strict rule of SPEC §7, and named by its digest (§2), over its canonical form with sig. It is chained to its job: parent names the job’s route record, and each decision after the first names the one before it by prev, so a job’s decisions are one sequence from its record, in which a decision left out before a later one, moved or given out of order is refused. The sequence proves nothing of decisions after its last: a verifier is not told how many deliveries were decided, and a list that ends early verifies.

Given the job’s route record and its decisions, from the first and in order (§7.2 step 10), a decision is held to:

• its documents, as step 5 holds a record to its job’s: its delivery, operation, capability, fallback, quantities and request are the delivery’s request’s job, operation, capability, fallback, quantities and digest (request_mismatch); its policy the delivery’s policy’s (policy_mismatch); and its pricebook the delivery’s price book’s digest, currency and issued, the book of the version its own rests on (§3.4: pricebook_mismatch);
• §4 over them, as step 6 holds a record’s candidates, order and decision (candidate_mismatch, removal_mismatch, rank_mismatch, decision_mismatch); and its route the first of the order, or null for none, and its passed each later survivor’s endpoint with its key, in the order (delivery_route_mismatch);
• its parent: its signer and job are the route record’s, its parent the route record’s digest, and its objects what the route record’s served attempt delivered: in a record of version 3, its delivered; in one of version 2, the count of its outputs and their commitment (§6). A record of version 1 states no output, and one no hop served delivered nothing, so neither has a delivery. Otherwise delivery_parent_mismatch;
• its chain: its seq is its place in the list, from 1; its prev is null for the first and the digest of the decision before it for every other; its decided is at least the served attempt’s end, when the objects first existed, and at least the decided of the decision before it; and its delivery is not that of a decision before it. Otherwise delivery_chain_broken.

The route a delivery took is a decision, not a delivery: whether the route carried the objects is for the delivery’s own receipts to state (bearer-receipts), and what it costs for the tariff that bills it (receipt-ledger §4). The record states no energy figure and no amount of its own, only the figures its price book stated and the estimates §4 derives from them.

6.4 A delivery’s offer and its route’s receipt

A decision of version 2 rests on a price book of version 3 and states its offer: what the delivery took its route at, as the route’s entry states it and §4.2 estimates it. Its offer is null when no route survives, and otherwise an object of exactly these members:

The decision’s pricebook digest and the offer’s entry name what was offered, and the rest restates it, so a holder of the decision reads what the route was taken at without the book. An offer that is not of these members, each of its form, is delivery_invalid; one that is not what the route’s entry and §4.2 give, or null while a route survives, or not null while none does, is delivery_offer_mismatch.

The route’s receipt. A route is one hop, and every hop is receipted (§6). A verification document may give a delivery’s receipt, the OER/2 receipt of the hop that carried it. It comes after the decision, which the hop names; no signed document of the router’s states it. It is held to its delivery:

• it verifies under oer-receipts on its own, with no reason: otherwise receipt_invalid;
• it is a job receipt of the decision’s operation whose work.status is 1, whose chain.signer is the decision’s route, and whose subject.inputs holds the text sha256: and the decision’s digest: otherwise receipt_mismatch;
• its subject.output is the root of the decision’s objects: otherwise receipt_output_mismatch.

So the receipt is the route’s, of this delivery. The hop signs which decision it carried out, and a receipt moved from another delivery of the same objects names another decision. A decision of version 1 states no offer, and a delivery no route took has no receipt: a receipt given with either is delivery_offer_mismatch.

Conformance. The receipt is then held to the offer, in this order:

1. Its grade. Its provenance.how is no higher than the offer’s grade in oer-receipts §2’s order, when grade is not null: otherwise delivery_grade_exceeded, whatever its figure and its flag. A route was taken at the evidence its entry states, and a receipt does not raise that after the fact: a route that reads better evidence states it in its next price book. A receipt graded below the offer is held like any other, and its grade is stated beside its verdict.
2. Its figure. The receipt’s figure is its energy.joules_total in microjoules, rounded to the nearest and a half to the even one, as receipt-ledger §5.1 reads a hop’s. The unmetered marker (oer-receipts §3.1) states none; a figure that is negative or past what a u64 holds is receipt_mismatch. With u the offer’s energy_ppm, or 0 when it is null, a figure J is above the offer when the offer’s energy is not null and J × 10⁶ exceeds energy × (10⁶ + u): more than one declared uncertainty above the offer’s figure, and for a class that declares none, more than the figure.
3. Its flag. A receipt whose figure is above the offer states price_exceeded as its work.outcome, and no other receipt does: otherwise delivery_price_unflagged and delivery_price_misflagged.

The flag is the hop’s, in what it signs, and a verifier recomputes it, so a receipt neither hides a figure above its offer nor claims one. A flagged receipt is accepted: it says what happened. Its verdict is one of:

One declared uncertainty is a term of the offer, as rung-price §6.4 takes it for a ranking, and not a limit on an error: a standard uncertainty bounds nothing (energy-measurement §2.1), so a figure above the offer is shown past what the route was taken at and not shown wrong. The offer holds the receipt’s figure and grade, and not the uncertainty the receipt declares of its own figure (energy.class), which this section does not compare with energy_ppm: a figure is held to the offer’s uncertainty, wider or narrower than its own. So a verdict turns on the figure alone: what a hop declares of its figure neither buys a verdict nor costs one, and a receipt that declares nothing, as a ModelBased or Estimator class and a receipt of no class do, is held by the same rule. A declaration wider than the offer’s is weaker evidence, as a lower grade is, and a reader finds it in the receipt the verdict names. The offer is for the quantity the delivery’s request states, and the receipt’s figure is the hop’s for the whole delivery. What a flagged delivery costs is the tariff’s to say (receipt-ledger §4).

7. Verification

7.1 Inputs

A verifier is given a verification document: a JSON object of exactly request, pricebook, policy and record, each a string holding that document’s text, receipts, null or a list of strings each holding an OER/2 receipt’s text, and keys, null or an object of a receipt’s chain.signer names to keys, as oer-receipts §5 publishes them. It may also have third_party, a list of strings each holding a third-party hop record’s text (§6.2). It may also have deliveries, a list of objects of exactly request, pricebook, policy and decision, each a string holding that document’s text: a delivery’s three documents and its delivery-decision record (§6.3), the job’s decisions from the first, in order. Each may also have receipt, a string holding the text of the OER/2 receipt of its route (§6.4). The texts are carried as strings so that each is read as written. A verification document that is not such an object, whose receipts is a list while its keys is null, or that has third_party while its receipts is null, is malformed, and so is one whose deliveries is not such a list or that gives a receipt while its keys is null.

7.2 Steps

A verifier runs these steps and stops at the first refusal, which it reports with its reason and where (at, a list: the member, then indexes or members within it):

1. The request (§3.1), at request: malformed, request_invalid.
2. The price book (§3.2), at pricebook: malformed, pricebook_invalid.
3. The policy (§3.3), at policy: malformed, policy_invalid.
4. The record (§5), at record: a text that is not a document, or whose kind is not wai-route-record, is malformed; a version that is an integer other than 1, 2 and 3 is unknown_version, at record, version; one that is not of §5.1’s and §5.2’s members for its version, each of the form its table gives it (a restated member of a candidate, the form §3.2 gives it for the record’s price book version, and of failures, each member an integer and hops at least 1), is record_invalid (an attempt whose hop is not its position, or whose error, outputs or delivered is not as its outcome requires, among them; the relations between a candidate’s members, such as an energy figure and its class, or a failure count and its hops, are step 6’s); then its signature (§5.3): bad_key, bad_signature, at record, sig.
5. The binding, at record and the member: its job, operation, capability, fallback, quantities, request and deadline are not the request’s (request_mismatch); its policy is not the policy’s name, version and digest (policy_mismatch); its version is not one that rests on the price book’s (§3.4: pricebook_mismatch, at record, version), or its pricebook is not the price book’s digest, currency and issued (pricebook_mismatch).
6. The candidates, at record, candidates and the index, recomputed by §4, each in turn and for each these three in this order: a candidate missing, added or out of order, or with a member other than removed and rank not what §4 gives it (candidate_mismatch); its removed not its removals (removal_mismatch); its rank not its rank (rank_mismatch). A list of the wrong length is a candidate_mismatch at the first index past the shorter. Then, at record, order, the order (rank_mismatch); and at record, decision, the decision (decision_mismatch).
7. The attempts, at record, attempts and the index, each in turn, by §5.2: an attempt past the allowed number (attempts_exceeded); one that names an endpoint that is not a survivor (attempt_removed); one that names a survivor not at its position in the order (attempt_out_of_order); a served attempt that is not the last (served_not_last); times out of order (times_invalid); billed and not_billed not what §5.2 gives (billing_invalid). Then, at record, attempts: a job whose last attempt failed, or that made none while a survivor was allowed, with fewer attempts than allowed (attempts_incomplete).
8. The hop receipts (§6), when receipts is not null: first each receipt’s text, at receipts and its index, which a receipt that is not a document under oer-receipts §4 fails (receipt_invalid); then each attempt in turn, at record, attempts, its index and receipt: receipt_missing, receipt_invalid, receipt_mismatch, receipt_output_mismatch, the first receipt of the list whose receipt_id is the attempt’s being its receipt.
9. The third-party hop records (§6.2), when the document has third_party, each in turn, at third_party and its index: a text that is not a document, or whose kind is not wai-route-third-party-hop, is malformed; a version that is an integer other than 1 is unknown_version, at version within it; one that is not of §6.2’s members and forms is third_party_invalid; then its signature, bad_key, bad_signature, at sig within it; then its binding, third_party_mismatch, at the member; then what its hop delivered, third_party_output_mismatch, at outputs within it.
10. The delivery decisions (§6.3), when the document has deliveries, each in turn, at deliveries, its index and the member: its request, pricebook and policy, as steps 1 to 3 read the job’s (malformed, request_invalid, pricebook_invalid, policy_invalid); then its decision: a text that is not a document, or whose kind is not wai-route-delivery-decision, is malformed; a version that is an integer other than 1 and 2 is unknown_version, at version within it; one that is not of §6.3’s and §6.4’s members and forms is delivery_invalid; then its signature, bad_key, bad_signature, at sig within it; then, at the member within it, its documents, §4 over them (a candidate at candidates and its index), its route, its offer (§6.4), its parent and its chain, in that order and each as §6.3 holds it; then, when the entry has receipt, that receipt, as §6.4 holds it, at receipt but for a decision of version 1, at version within the decision.

7.3 Outcome

• refuse: the reason and where.
• accept: the record’s digest; the job and its operation; the served endpoint and the hop that served it, and in a record of version 2 the content hashes of its outputs, in their order, or in one of version 3 their delivered count and root, or nulls for a job no hop served; the billed hop, or null; the deadline, none when none was declared and otherwise met or missed by the served hop, or none too when no hop served; the order; the decision; each removed candidate’s endpoint with the limits that removed it; whether the hop receipts were checked or not_checked; and, when checked, the hops whose receipts state the unmetered marker (oer-receipts §3.1), which a reader MUST NOT present as hops of zero joules. When the document has third_party, each record’s hop, digest, account, usage and charge, in the order of their hops. When it has deliveries, each decision’s seq, delivery, digest, route, decision and passed, in their order, and of a decision of version 2 its offer and its conformance, an object of exactly verdict (§6.4), receipt, the receipt’s receipt_id, energy, its figure, and grade, its provenance.how, each null where no receipt or no figure gives it.

8. Reasons

The codes this extension adds, each with where it is raised:

A verifier of this extension also raises malformed for a text that is not a document (§2) or a verification document that is not §7.1’s, unknown_version for a record of another version, and bad_key and bad_signature for its signature (SPEC §7).

9. Operation

The catalogue’s operation route.verify (wai route verify <document>) verifies a verification document (§7.1) and prints its outcome (§7.3), offline; it exits 0 when the record is accepted and 1 when it is refused.

10. Conformance

live-conformance/routes/ holds the corpus, in one file, vectors.json, written by wai_route_record_vectors gen from fixed seeds: a router’s key and a hop’s, and the OER/2 receipts of minor version 1 the hops sign. Each vector is a verification document with the outcome §7.3 gives it:

• Accepted: a job served by its first survivor, billed; a failover after a server error, the failed hop unmetered and not billed; a served hop past the deadline, not billed; a job every allowed survivor failed, with the policy’s max_attempts below the survivors’ number; a job no candidate survives; a ranking decided by the targets, by the request’s sort, by a key of the policy and by the endpoint; an unknown energy and time to first byte ranked last; every limit of §4.3 removing a candidate, a null value among them, and a candidate removed by several; a ceiling in another currency; the fallback’s candidates; and a record verified without its receipts.
• Accepted, version 2, over one price book whose endpoint prices its encode and its decode apart and whose encodes’ failures run from none in 1,000 hops to all of 500: a ranking by the expected cost, which puts an endpoint whose billed failures make it dearer after one of the same list price, a cheaper one that fails more after both, and the unmeasured endpoint, the basis of 99 hops and the basis whose every hop failed after every measured one, a basis of exactly 100 hops counting; a decode at its own price, under a unit-price cap its endpoint’s encode exceeds; a ranking and a target by the expected time to first byte, and one by the list cost where no failure was measured; a spend ceiling that reads the list cost; a failover whose failed hop delivered nothing; a hop that served three outputs, one that served past the deadline, its outputs bound all the same; and a record verified without its receipts.
• Refused: each reason of §8 at least once, each vector a control of one defect, its record signed again over the defect where the defect is not in the signature; and each code §8 reuses. In version 2, each rule of §3.2 and §3.2.1 broken once (an entry out of order by its operation, without its operation or its failures; more hops failed than were sent; a period ending after the book was issued, or reversed; a billed price or a time with no failed hop; a basis of no hop), an operation in a price book of version 1 and a price book of version 4; a record of either version on a price book of the other; an expected figure and a basis restated, and the other operation’s entry listed; a served hop with no output, a failed one with one, an output twice and one in capitals; and a served hop’s receipt moved from another job, a late hop’s too, outputs restated in another order, one output named by its leaf and three by the first of them (receipt_output_mismatch).
• Accepted, version 3, on version 2’s price book: a hop that served one output, whose root is its content hash; three; and 5,000, more than a list of version 2 holds, its record the size of the others; a failover whose failed hop delivered nothing; a hop that served past the deadline; and a record verified without its receipts.
• Refused, version 3: a served hop’s count of 0; a failed hop with a count, and with a root; a root in capitals; a count as text; a member besides the count and the root; outputs listed as version 2 lists them; delivered in a record of version 2 (record_invalid); a record of version 3 on a price book of version 1 (pricebook_mismatch); and a served hop’s receipt moved from another job, and a root not its receipt’s (receipt_output_mismatch). A record of version 4 is unknown_version.
• Accepted, third-party hops, under records of versions 2 and 3: a hop a third party served, on the operator’s account, whose provider reported no charge; one whose provider reported a charge and a provider’s own job id; a failed hop the provider bills beside a served one; a failed hop it does not bill; and a hop of the customer’s account.
• Refused, third-party hops: a document with third_party and no receipts (malformed); a record of version 2 (unknown_version); each form and bound of §6.2 past its limit; a member missing and a member added, a header among them; a URL with a query, one with a fragment, a response keeping a signed link and an origin with a path; a served record with no outputs and no usage, a failed one with outputs and with no error; a name twice and an object twice; exchanges out of order, before the record’s start and past its end (third_party_invalid); a changed record (bad_signature); and another router’s, another job’s, a hop that is not an attempt, another endpoint’s, provider’s, receipt’s, outcome’s and error’s, a usage in another unit, times outside the attempt’s and a second record of a hop (third_party_mismatch); and outputs that are not what the receipt names, the same in another order, and another number than the attempt’s count (third_party_output_mismatch).
• Accepted, delivery decisions, under records of versions 2 and 3: a job’s output delivered to Europe by the faster of two caches of one price, the dearer cache and the origin passed over by price, the second cache by time to first byte; a second delivery of it to another region by the one route that keeps no data there, chained to the first; a delivery no route survives; a record verified without its receipts; and a document whose deliveries is empty.
• Refused, delivery decisions: a deliveries that is not a list, an entry without its policy and a decision not as text (malformed); the delivery’s request, price book and policy each invalid; a decision that is not a document, of another kind and of version 3; a member missing and one added, a seq of 0, a prev in capitals, no object, objects with a member besides, a route passed by no key, a route as a number, a candidate of version 1’s members, decided as text and more routes passed than a list holds (delivery_invalid); a decision changed after it was signed, a signer of small order and one signed under the route record’s domain; another delivery’s id, operation, capability, quantities and request digest, and a fallback the request does not name (request_mismatch); another policy version, name and digest (policy_mismatch); another price book’s issued, digest and currency, and one of version 1 (pricebook_mismatch); a route’s price restated, a route left out, a removal left out, two ranks swapped, the order reversed and another decided_by; another route, none while one survives, a route passed by another key, a passed route left out, a removed route passed, and a route where none survives (delivery_route_mismatch); another router’s decision, another job’s, another parent, another count and root, and a decision of a job no hop served and of a record of version 1 (delivery_parent_mismatch); and a first decision at seq 2 and one naming a prev, a second with no prev and one naming another, decisions out of order, the first left out before the second, one decided before the output existed and one before the decision before it, and one delivery decided twice (delivery_chain_broken).
• Accepted, offers, over a delivery of 6 J offered by a counter’s figure declared to 20,000 ppm, by a model’s figure, by an estimate and with no figure: a receipt below the figure, at it, at one declared uncertainty above it, and one that rounds down to that edge; one a microjoule past it and one that rounds up past it, each flagged; a model’s figure a microjoule past its own, flagged; an estimate at its figure; a receipt graded below its offer; one declaring more uncertainty than its offer at the figure, and one declaring less at the edge; the unmetered marker; an offer of no figure; a decision with no receipt given and one no route survives; the largest uncertainty; a decision of version 2 after one of version 1; two deliveries each held to its own; and a delivery under a record of version 2.
• Refused, offers: each rule of energy_ppm broken once, and a price book of version 2 that states one (pricebook_invalid); a record on a price book of version 3, and a decision of either version on the other’s (pricebook_mismatch); an offer left out, one in a decision of version 1, and each of its forms past its limit (delivery_invalid); a route’s uncertainty restated (candidate_mismatch); each member of the offer another, the figure by one and the uncertainty by one each way, and an offer null while a route survives and stated while none does (delivery_offer_mismatch); a receipt not as text and one given with no keys (malformed); one that is not a receipt, changed after it was signed and under a key not published (receipt_invalid); one of another kind, operation and route, of a failed delivery, naming no decision and another, moved from another delivery of the same objects, and of a figure that is negative and one past what a u64 holds (receipt_mismatch); one of other objects (receipt_output_mismatch); one given with a decision of version 1 and one no route survives (delivery_offer_mismatch); a grade above the offer’s, a flagged one among them (delivery_grade_exceeded); a figure above the offer with no flag, by a microjoule, by rounding, of each class, under a declaration wider than the figure’s distance past the offer and under another outcome (delivery_price_unflagged); and a flag below the figure, at the edge, on the unmetered marker and with no figure offered (delivery_price_misflagged).

wai_route_record_vectors verify and the test tests/route_record.rs check that the file regenerates byte for byte, that wai-rs gives every vector its outcome, that every reason of §8 refuses a vector, and that §8 lists exactly the reference’s codes. live-conformance/route_record_verify.py is the second implementation, written from this text: it shares no code with wai-rs, verifies the router’s signature with WAI’s strict rule written from RFC 8032 (claim-conformance/_ed25519.py), verifies the hop receipts with the OER/2 reference verifier (oer-conformance/oer2_verify.py), computes the outputs’ commitment with BLAKE3 written from its specification (claim-conformance/_blake3.py), recomputes every candidate, removal, expected figure, rank, order, decision and attempt itself, and every delivery’s routing, route, passed routes, offer, parent, chain and receipt, gives every vector the same outcome, requires every mutated copy of the corpus to fail, and requires the corpus to catch the verifier with each of its checks dropped.

11. Security and privacy considerations

• What the record proves. That the router, holding these three documents, chose by their rules, and tried and billed as it says. It does not prove that the price book states what the providers charge, or that an endpoint’s stated retention or training is true: the price book is the router’s statement, pinned by digest, and a buyer who holds the published price book of that digest compares it. A record whose candidates differ from its price book’s entries is refused (candidate_mismatch), so a router cannot list a price it did not state.
• Removed means never tried. An attempt that names a removed candidate is refused (attempt_removed): a job whose limits removed an endpoint was not sent there, by this router’s own signed account. Whether a hop’s provider kept the data it was sent is outside any record; the limit that removed a provider that says it keeps data is not.
• Failed hops are not billed. A record that bills a failed attempt, or a served one past the declared deadline, is refused (billing_invalid); the receipt ledger bills a job from the billed attempt alone.
• Unknown is restrictive. Every null a limit reads removes the candidate (§4.3), so a price book that omits what a buyer cares about removes the endpoint rather than admitting it.
• Failures are measured, and stated with their basis. A price book of version 2 states each endpoint’s failures as the router measured them, with the hops and the period they were read from, and the record restates them beside the expected figures the ranking read. The record does not prove the measurement, as it does not prove a price: a reader sees what the order rests on, and a basis too thin to mean anything is read as no measurement at all (§3.2.1). Leaving an endpoint unmeasured gains it nothing: its expected figures are null, ranked after every measured one (§4.2).
• The job pays the list price. What failures cost is the router’s: it orders the survivors and is never billed to the job, whose limits and line read the list price (§4.2).
• A receipt is bound to its output. In version 2, a served hop’s receipt names the outputs the record states it delivered (§6), so a receipt cannot vouch, in another record, for an output its hop did not produce; and a holder of the output who finds its content hashes in the record knows which hop’s receipt is about it.
• A third party’s record holds no secret. A third-party hop record states whose account the hop ran on, never the key; no header, since a key travels in one; and no URL’s query, since a provider’s signed link is a bearer token (§6.2). A record that keeps one is refused, so a router that signs one has signed something a verifier will not read.
• What a third-party record proves. That the router says it made these calls and read these answers: the provider signs nothing, so the record is the router’s statement of what passed between them, bound by digest to the bytes, which a holder of them checks. A provider’s charge is what the provider reported, as the router read it, and is never a price.
• A delivery’s route is the rule’s. A delivery-decision record whose route, or whose reason for passing a route over, is not what §4 gives over the delivery’s own documents is refused (delivery_route_mismatch), so a router that sends a delivery to a route its rule did not choose cannot sign a record that verifies. Each decision names the job’s route record and the decision before it, so one left out before a later one, moved or put in another job’s deliveries is refused (delivery_chain_broken, delivery_parent_mismatch). The decisions after the last one given are not proved absent: a verifier is not told how many there were.
• What a delivery decision proves. That the router, holding the delivery’s three documents, chose its route by their rules, for the output the job’s served hop delivered. It does not prove that a route’s terms are as its price book states, which a holder of the published price book of that digest compares, nor that the route carried the objects, which the delivery’s own receipts state.
• A delivery is held to its offer. A decision states what its route was taken at, and the route’s receipt is held to it: a figure above the offer that its hop does not flag is refused (delivery_price_unflagged), and so is a flag on a figure that is not (delivery_price_misflagged), so what a hop signs says which it was. A receipt names its decision and is signed by the route, so it cannot be moved to another delivery of the same objects, and a receipt graded above the offer is refused whatever it states.
• What conformance proves. That the route’s own receipt, under the key published for it, states a figure within or above the offer. It does not prove the figure, which is the hop’s reading at the grade it states: a receipt graded below its offer is held all the same, and the outcome states its grade beside its verdict. A delivery with no receipt given is not_checked, and a verifier is not told that a receipt exists.
• What a record reveals. Its job id, its operation and its quantities, every endpoint and provider that could have served the job with their prices, and when each hop ran; in version 2, every candidate’s measured failures and the content hashes of the job’s outputs. A third-party hop record reveals, besides, what the provider answered about the job, and a delivery decision every route that could have carried the job’s output, with its terms, and where the delivery was to go, by the regions and residencies its request names. They travel between the router, the job’s owner and an auditor they choose.