route-record: version 2 prices per operation, ranks by measured failure, binds a hop receipt to its output #552

Merged

dcharlot merged 4 commits from wai/route-physics into main 2026-10-31 08:05:26 -04:00

Conversation 0 Commits 4 Files changed 12 +2258 -133

dcharlot commented 2026-10-31 02:52:54 -04:00

Owner

Copy link

What this changes

WAI's route record (wai/extensions/route-record.md) gets a version 2 of its price book and its record. It fixes three places where the record did not follow the physics of the work:

1. The price book prices per operation. A version-2 entry names the catalogue operation it prices. Entries are ordered by endpoint, then operation. A job's candidates are the entries for its own (capability, operation). An encode and a decode now get their own estimates (§4.2), their own unit-price limit (§4.3) and their own place in the ranking (§4.4).
2. Measured failure counts in the ranking, and each entry states its basis. A version-2 entry states failures: hops, from, to (the basis), failed, billed_price (what the provider billed per divisor units for the failed hops) and failed_ms (the mean time a failed hop took), or null.
   • The physics. A job sent to an endpoint until it is served meets failed / (hops − failed) failures on average (a geometric count). Each failure costs the router what the provider billed for it, and costs the job the time it took.
   • The derived terms. That gives a candidate an expected cost and an expected time to first byte per successful job:
     • expected cost = cost + ⌊F·failed/(hops−failed)⌋, with F = ⌊q·billed_price/divisor⌋;
     • expected time to first byte = ttfb_ms + ⌊failed_ms·failed/(hops−failed)⌋.
   • How the ranking reads them. The price, ttfb and targets keys read these first, then the list figures.
   • Why this order. §4.4 gives an exchange argument: if each attempt costs C on average and serves with probability s, ordering the survivors by C/s minimises the expected spend over the attempts. C/s is exactly the expected figure per successful job.
   • The basis. A basis under 100 hops is too thin. Below 97 hops, the 95% confidence interval of a failure rate near one half is wider than ±0.1. Failures with a thin basis, and null failures, are unknown.
   • Unknown failures. Their expected figures are null. The rule the text already applies to every null figure then ranks them after every stated figure, and among themselves by the list figure. Unknown is never read as "no failures", which would reward going unmeasured, and never as a worst case. No limit reads failures.
   • The job pays the list price. unit_price and spend read the list price and the list cost. A line bills the billed attempt.
   • What the record carries. It restates every basis and every derived term. Everything the ranking uses is in the request, price book and policy, so the verifier recomputes the order from them.
   • This is the failure_cost waiTransport proposed (wai-additions §27), built on the physics with its basis stated. One difference: an unknown failure is not counted as 0.
3. A hop receipt is bound to its output.
   • In version 2, the attempt that served states outputs: the jwp-receipts §2.1 content hashes of what it delivered, in order.
   • Its OER/2 receipt's subject.output must equal their commitment. Otherwise the record is refused receipt_output_mismatch.
   • oer-receipts.md §3 now defines that commitment (Output): one output is named by its content hash, which is what the text already implied through jwp-receipts §2.4.5. Several outputs are named by the jwp-receipts §2.2 Merkle root over their content hashes in delivery order, with unlabelled leaves. The objects must be distinct, so that one root names one list.
   • jwp-receipts §2.4.5 now points to that definition. No OER/2 reason or vector changes.
   • A served hop is bound whether or not it is billed: one that served past the deadline still delivered its outputs.

Version 1 documents and records read, route and verify exactly as before. A version-1 reader refuses version 2 (pricebook_invalid, unknown_version) rather than misreading it. A record's version must match its price book's version, or the record is refused pricebook_mismatch at record.version.

Corpus and implementations

• live-conformance/routes/vectors.json: every version-1 vector is byte for byte the same except one. The control record_version_2 is now record_version_3, because version 2 is now defined; it is still refused unknown_version. 36 version-2 vectors are added: 10 accepted, plus a control for each new rule. Each control is refused at the reason and place it declares.
• wai::route_record: adds Failures, the expected figures, output_commitment, content_hash and seal_delivered. seal is unchanged, so PR #550's corpus helpers compile as they are.
• route_record_verify.py is written from the text. It computes the commitment with claim-conformance/_blake3.py, and drops 11 more of its own checks (45 in all).
• The receipt ledger's files are untouched (PR #550). Its corpus reads routes/vectors.json by vector name, and every vector it reads is unchanged.

Tests (Framework, 192.168.4.47)

• cargo test --no-default-features --features route_record --lib route_record::: 8 passed. The new tests cover the expected figures, when they are unknown or unbounded, and the commitment.
• cargo test --no-default-features --features route_record --test route_record: 7 passed. The new tests cover version 2's cases and wai route verify on version-2 vectors.
• wai_route_record_vectors verify: the corpus regenerates byte for byte, and every vector gets its outcome.
• python3 -I live-conformance/route_record_verify.py live-conformance/routes (Python 3.14 with cryptography):
  • every vector passes;
  • 22 added reasons and 4 reused codes are each refused;
  • all 590 mutated copies fail;
  • with each of the 45 checks dropped in turn, the corpus catches the weakened verifier.
• cargo clippy --no-default-features --features route_record --lib --tests --bin wai_route_record_vectors --bin wai: no warning in the touched files. The warnings it does print are in other modules and come from main.
• wai breaking --against 4902e6679: 9 breaks, each acknowledged in wai/CHANGELOG.md: the corpus control, plus 8 Rust API changes (new fields and the new reason). It reports "no unacknowledged breaking change".
• The ledger, unchanged, still passes against this route record:
  • --features receipt_ledger --lib receipt_ledger::: 8 passed;
  • --test receipt_ledger: 4 passed;
  • receipt_ledger_verify.py live-conformance/ledger: status 0.
• Merging with #550. git merge-tree against #550's head 8642b1394 merges cleanly. The CHANGELOG section sits above "Routed media jobs", not at the top of Unreleased, so that it does not collide with #550's insertion. On that trial merge (Framework, never pushed):
  • --test route_record: 7 passed;
  • --lib receipt_ledger::: 10 passed;
  • --lib route_record::: 8 passed;
  • --test receipt_ledger: 5 passed;
  • route_record_verify.py: status 0;
  • receipt_ledger_verify.py: status 0.

Falsifications

Every new rule was broken in src/route_record.rs, one mutation at a time. For each, wai_route_record_vectors verify ran against the committed corpus, then the source was restored. The tree verified clean before the first mutation and after the last.

All 29 mutations were caught. In each case the vector that names the rule failed, the run exited 1, and no run panicked. Each line below gives the broken rule, then the vector that caught it.

• §4.1, the operation filter: v2_a_decode_at_its_own_price, along with every version-2 ranking.
• §4.4, the ranking keys:
  • price read as the list cost: v2_ranked_by_the_expected_cost;
  • ttfb read as the list time: v2_ranked_by_the_expected_time_to_first_byte;
  • targets read from the list time: v2_the_targets_read_the_expected_time_to_first_byte.
• §3.2.1, the thin basis, from both sides:
  • 99 hops counted: im.delta moves;
  • 100 hops not counted: im.iota moves.
• §4.2, the expected figures:
  • every hop failed, read as no failure: im.epsilon moves;
  • unknown failures read as no failure: im.gamma moves;
  • failures counted per attempt (f) instead of per success (f/s): the expected figures change.
• §4.3, the spend ceiling read against the expected cost: v2_the_ceiling_reads_the_list_cost.
• §3.2.1, each relation dropped alone (failed at most hops; from at most to; to at most issued; no billed price, and no failure time, without a failed hop; at least one hop): each one's control is refused pricebook_mismatch instead of pricebook_invalid.
• §3.2, entries ordered by endpoint, then operation: v2_price_book_out_of_order_by_operation.
• §3.4, a price book's version must be 2: price_book_version_3.
• §7.2 step 5, a record's version must be its price book's: both version-crossing controls fall through to candidate_mismatch.
• §7.2 step 4, version 3 unknown: record_version_3.
• §5.2, the outputs' form, each sub-rule alone:
  • a served attempt with no output;
  • a failed attempt with an output;
  • an output repeated.
• §6, the output binding:
  • binding dropped: all five receipt_output_mismatch controls;
  • binding limited to billed hops: v2_a_late_hops_receipt_moved_from_another_job.
• oer-receipts §3, the commitment:
  • one output named by its leaf instead of its content hash;
  • no padding of an odd level;
  • the wrong leaf domain;
    each caught by v2_served_three_outputs and the single-output vectors.
• §5.1, a candidate restating its expected figures: every version-2 vector.

route_record_verify.py has its own falsification loop: it drops each of its 45 checks in turn, the 11 new ones included, and the corpus caught every one.

Ledger follow-ups (after #550; this PR does not touch the ledger)

• Hold a job's billed output to the record's outputs.
  • Under a version-2 record, the ledger's job outputs (each int_motion decode receipt with its codestream) should be checked against the billed hop's outputs: the content hashes of the envelopes it delivered.
  • Otherwise a line can bill the subpixels of an output that the billed hop did not deliver.
  • The ledger's source then needs the delivered envelope, or the envelope's content hash, beside each codestream. Today it carries only the WIV1 payload.
• Under #550's version-3 tariff, cite the output by the record's content hash. A version-2 record names the job's output by the content hash its hop's receipt is bound to. The chain can cite the output by that hash, beside or in place of the decode receipt that #550 makes cited-but-not-billed.
• State in receipt-ledger §5.1 that expected_cost is never a charge. A job is billed from its billed attempt at the tariff's price. A version-2 record's expected_cost and failures are the router's ranking figures and are never read into a line. No ledger code reads them today.
• Add version-2 job sources to the ledger corpus, so that the ledger's two verifiers run against version-2 records. The route corpus already has them: v2_ranked_by_the_expected_cost, v2_failover_whose_failed_hop_delivered_nothing, v2_served_three_outputs, v2_served_after_the_deadline, v2_a_decode_at_its_own_price. Neither verifier needs a code change: both call route_record::verify or RRV.verify, which now read version 2. A decode job also gives #550's per-operation tariff a version-2 decode to price.
• Note in receipt-ledger that tariff version 3's operation and the price book's operation agree. Under a version-2 record, the billed attempt's candidate states the same operation as the record, because §4.1 admits only entries of the request's operation. The ledger's lookup by (serving capability, operation) is therefore the price book's own key. It is one sentence, and needs no check.

🤖 Generated with Claude Code

## What this changes WAI's route record (`wai/extensions/route-record.md`) gets a **version 2** of its price book and its record. It fixes three places where the record did not follow the physics of the work: 1. **The price book prices per operation.** A version-2 entry names the catalogue `operation` it prices. Entries are ordered by endpoint, then operation. A job's candidates are the entries for its own (capability, operation). An encode and a decode now get their own estimates (§4.2), their own unit-price limit (§4.3) and their own place in the ranking (§4.4). 2. **Measured failure counts in the ranking, and each entry states its basis.** A version-2 entry states `failures`: `hops`, `from`, `to` (the basis), `failed`, `billed_price` (what the provider billed per `divisor` units for the failed hops) and `failed_ms` (the mean time a failed hop took), or `null`. - **The physics.** A job sent to an endpoint until it is served meets `failed / (hops − failed)` failures on average (a geometric count). Each failure costs the router what the provider billed for it, and costs the job the time it took. - **The derived terms.** That gives a candidate an **expected cost** and an **expected time to first byte per successful job**: - expected cost = `cost + ⌊F·failed/(hops−failed)⌋`, with `F = ⌊q·billed_price/divisor⌋`; - expected time to first byte = `ttfb_ms + ⌊failed_ms·failed/(hops−failed)⌋`. - **How the ranking reads them.** The `price`, `ttfb` and `targets` keys read these first, then the list figures. - **Why this order.** §4.4 gives an exchange argument: if each attempt costs `C` on average and serves with probability `s`, ordering the survivors by `C/s` minimises the expected spend over the attempts. `C/s` is exactly the expected figure per successful job. - **The basis.** A basis under **100 hops** is too thin. Below 97 hops, the 95% confidence interval of a failure rate near one half is wider than ±0.1. Failures with a thin basis, and `null` failures, are **unknown**. - **Unknown failures.** Their expected figures are `null`. The rule the text already applies to every `null` figure then ranks them after every stated figure, and among themselves by the list figure. Unknown is never read as "no failures", which would reward going unmeasured, and never as a worst case. No limit reads failures. - **The job pays the list price.** `unit_price` and `spend` read the list price and the list cost. A line bills the billed attempt. - **What the record carries.** It restates every basis and every derived term. Everything the ranking uses is in the request, price book and policy, so the verifier recomputes the order from them. - This is the `failure_cost` waiTransport proposed (wai-additions §27), built on the physics with its basis stated. One difference: an unknown failure is not counted as 0. 3. **A hop receipt is bound to its output.** - In version 2, the attempt that served states `outputs`: the jwp-receipts §2.1 content hashes of what it delivered, in order. - Its OER/2 receipt's `subject.output` must equal their commitment. Otherwise the record is refused **`receipt_output_mismatch`**. - `oer-receipts.md` §3 now defines that commitment (*Output*): one output is named by its content hash, which is what the text already implied through jwp-receipts §2.4.5. Several outputs are named by the jwp-receipts §2.2 Merkle root over their content hashes in delivery order, with unlabelled leaves. The objects must be distinct, so that one root names one list. - jwp-receipts §2.4.5 now points to that definition. No OER/2 reason or vector changes. - A served hop is bound whether or not it is billed: one that served past the deadline still delivered its outputs. Version 1 documents and records read, route and verify exactly as before. A version-1 reader refuses version 2 (`pricebook_invalid`, `unknown_version`) rather than misreading it. A record's version must match its price book's version, or the record is refused `pricebook_mismatch` at `record.version`. ## Corpus and implementations - `live-conformance/routes/vectors.json`: every version-1 vector is byte for byte the same except one. The control `record_version_2` is now `record_version_3`, because version 2 is now defined; it is still refused `unknown_version`. 36 version-2 vectors are added: 10 accepted, plus a control for each new rule. Each control is refused at the reason and place it declares. - `wai::route_record`: adds `Failures`, the expected figures, `output_commitment`, `content_hash` and `seal_delivered`. `seal` is unchanged, so PR #550's corpus helpers compile as they are. - `route_record_verify.py` is written from the text. It computes the commitment with `claim-conformance/_blake3.py`, and drops 11 more of its own checks (45 in all). - The receipt ledger's files are untouched (PR #550). Its corpus reads `routes/vectors.json` by vector name, and every vector it reads is unchanged. ## Tests (Framework, `192.168.4.47`) - `cargo test --no-default-features --features route_record --lib route_record::`: 8 passed. The new tests cover the expected figures, when they are unknown or unbounded, and the commitment. - `cargo test --no-default-features --features route_record --test route_record`: 7 passed. The new tests cover version 2's cases and `wai route verify` on version-2 vectors. - `wai_route_record_vectors verify`: the corpus regenerates byte for byte, and every vector gets its outcome. - `python3 -I live-conformance/route_record_verify.py live-conformance/routes` (Python 3.14 with `cryptography`): - every vector passes; - 22 added reasons and 4 reused codes are each refused; - all 590 mutated copies fail; - with each of the 45 checks dropped in turn, the corpus catches the weakened verifier. - `cargo clippy --no-default-features --features route_record --lib --tests --bin wai_route_record_vectors --bin wai`: no warning in the touched files. The warnings it does print are in other modules and come from main. - `wai breaking --against 4902e6679`: 9 breaks, each acknowledged in `wai/CHANGELOG.md`: the corpus control, plus 8 Rust API changes (new fields and the new reason). It reports "no unacknowledged breaking change". - **The ledger, unchanged, still passes against this route record:** - `--features receipt_ledger --lib receipt_ledger::`: 8 passed; - `--test receipt_ledger`: 4 passed; - `receipt_ledger_verify.py live-conformance/ledger`: status 0. - **Merging with #550.** `git merge-tree` against #550's head `8642b1394` merges cleanly. The CHANGELOG section sits above "Routed media jobs", not at the top of Unreleased, so that it does not collide with #550's insertion. On that trial merge (Framework, never pushed): - `--test route_record`: 7 passed; - `--lib receipt_ledger::`: 10 passed; - `--lib route_record::`: 8 passed; - `--test receipt_ledger`: 5 passed; - `route_record_verify.py`: status 0; - `receipt_ledger_verify.py`: status 0. ## Falsifications Every new rule was broken in `src/route_record.rs`, one mutation at a time. For each, `wai_route_record_vectors verify` ran against the committed corpus, then the source was restored. The tree verified clean before the first mutation and after the last. **All 29 mutations were caught.** In each case the vector that names the rule failed, the run exited 1, and no run panicked. Each line below gives the broken rule, then the vector that caught it. - **§4.1, the operation filter:** `v2_a_decode_at_its_own_price`, along with every version-2 ranking. - **§4.4, the ranking keys:** - price read as the list cost: `v2_ranked_by_the_expected_cost`; - ttfb read as the list time: `v2_ranked_by_the_expected_time_to_first_byte`; - targets read from the list time: `v2_the_targets_read_the_expected_time_to_first_byte`. - **§3.2.1, the thin basis**, from both sides: - 99 hops counted: `im.delta` moves; - 100 hops not counted: `im.iota` moves. - **§4.2, the expected figures:** - every hop failed, read as no failure: `im.epsilon` moves; - unknown failures read as no failure: `im.gamma` moves; - failures counted per attempt (f) instead of per success (f/s): the expected figures change. - **§4.3, the spend ceiling read against the expected cost:** `v2_the_ceiling_reads_the_list_cost`. - **§3.2.1, each relation dropped alone** (failed at most hops; `from` at most `to`; `to` at most `issued`; no billed price, and no failure time, without a failed hop; at least one hop): each one's control is refused `pricebook_mismatch` instead of `pricebook_invalid`. - **§3.2, entries ordered by endpoint, then operation:** `v2_price_book_out_of_order_by_operation`. - **§3.4, a price book's version must be 2:** `price_book_version_3`. - **§7.2 step 5, a record's version must be its price book's:** both version-crossing controls fall through to `candidate_mismatch`. - **§7.2 step 4, version 3 unknown:** `record_version_3`. - **§5.2, the outputs' form**, each sub-rule alone: - a served attempt with no output; - a failed attempt with an output; - an output repeated. - **§6, the output binding:** - binding dropped: all five `receipt_output_mismatch` controls; - binding limited to billed hops: `v2_a_late_hops_receipt_moved_from_another_job`. - **oer-receipts §3, the commitment:** - one output named by its leaf instead of its content hash; - no padding of an odd level; - the wrong leaf domain; each caught by `v2_served_three_outputs` and the single-output vectors. - **§5.1, a candidate restating its expected figures:** every version-2 vector. `route_record_verify.py` has its own falsification loop: it drops each of its 45 checks in turn, the 11 new ones included, and the corpus caught every one. ## Ledger follow-ups (after #550; this PR does not touch the ledger) - **Hold a job's billed output to the record's outputs.** - Under a version-2 record, the ledger's job `outputs` (each `int_motion` decode receipt with its codestream) should be checked against the billed hop's `outputs`: the content hashes of the envelopes it delivered. - Otherwise a line can bill the subpixels of an output that the billed hop did not deliver. - The ledger's source then needs the delivered envelope, or the envelope's content hash, beside each codestream. Today it carries only the `WIV1` payload. - **Under #550's version-3 tariff, cite the output by the record's content hash.** A version-2 record names the job's output by the content hash its hop's receipt is bound to. The chain can cite the output by that hash, beside or in place of the decode receipt that #550 makes cited-but-not-billed. - **State in receipt-ledger §5.1 that `expected_cost` is never a charge.** A job is billed from its billed attempt at the tariff's price. A version-2 record's `expected_cost` and `failures` are the router's ranking figures and are never read into a line. No ledger code reads them today. - **Add version-2 job sources to the ledger corpus**, so that the ledger's two verifiers run against version-2 records. The route corpus already has them: `v2_ranked_by_the_expected_cost`, `v2_failover_whose_failed_hop_delivered_nothing`, `v2_served_three_outputs`, `v2_served_after_the_deadline`, `v2_a_decode_at_its_own_price`. Neither verifier needs a code change: both call `route_record::verify` or `RRV.verify`, which now read version 2. A decode job also gives #550's per-operation tariff a version-2 decode to price. - **Note in receipt-ledger that tariff version 3's operation and the price book's operation agree.** Under a version-2 record, the billed attempt's candidate states the same operation as the record, because §4.1 admits only entries of the request's operation. The ledger's lookup by (serving capability, operation) is therefore the price book's own key. It is one sentence, and needs no check. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 3 commits 2026-10-31 02:52:54 -04:00

route-record: version 2 prices per operation, ranks by measured failure, binds a hop to its output ... 55ac87088c

A price book of version 2 prices each operation of an endpoint in its own entry, and a job's
candidates are the entries of its operation, so an encode and a decode are estimated, capped and
ranked at their own prices. An entry states its measured failures over a basis (hops, period),
and a candidate carries its expected cost and expected time to first byte per successful job
(the list figure plus failed/(hops - failed) failures' worth), which the price, ttfb and targets
keys read first: the order that minimises the expected spend over the attempts. A basis under
100 hops is too thin; thin or null failures are unknown, their expected figures null and ranked
by the existing rule for null. The job pays the list price: the limits read it and a line bills
the billed attempt. A record of version 2 states the served hop's outputs, and its OER/2
receipt's subject.output must be their commitment (oer-receipts §3 Output: the content hash of
one, the jwp-receipts §2.2 root over several), or receipt_output_mismatch.

Version 1 documents and records verify exactly as before; the corpus keeps every version-1
vector byte for byte but the unknown-version control (now version 3) and adds 36 of version 2.
route_record_verify.py reads version 2 from the text.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

route-record: SPEC's summary of a routed job states version 2; §4.4's rationale reflowed ... 6da0eb70e8

Co-Authored-By: Claude Opus 5.5 <[email protected]>

route-record corpus: the version-2 request's doc says what it is ... 7dad4f6c99

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot added 1 commit 2026-10-31 06:10:51 -04:00

Merge origin/main (#553: two arm64-heavy conformance jobs build without debuginfo) into wai/route-physics ... 3888ee51cf

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot merged commit 3de4b58922 into main 2026-10-31 08:05:26 -04:00

dcharlot referenced this pull request from a commit 2026-10-31 08:05:27 -04:00

Merge pull request 'route-record: version 2 prices per operation, ranks by measured failure, binds a hop receipt to its output' (#552) from wai/route-physics into main

dcharlot referenced this pull request 2026-10-31 09:54:00 -04:00

wai-quantum: exact gradients, deterministic optimisers, VQE, QAOA and algorithm builders, each answer checked or bounded, on every surface #555

dcharlot referenced this pull request 2026-10-31 11:33:03 -04:00

wai-quantum: jobs placed on certified GPU members or split over several, byte for byte the CPU's; Clifford+T as sums of stabilizer states #557

dcharlot referenced this pull request 2026-10-31 23:35:46 -04:00

receipt-ledger: version 5 holds a decode to the frames it delivered, its codestream what it read #559

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!552

No description provided.