route-record: a third party's hop has a signed record of what was sent, what came back, and what the provider bills #572

Merged

dcharlot merged 3 commits from wai/third-party-hop into main 2026-11-02 11:04:26 -05:00

Conversation 0 Commits 3 Files changed 12 +4387 -16

dcharlot commented 2026-11-02 05:04:03 -05:00

Owner

Copy link

A hop sent to a third party's endpoint is work the router did not do. Its OER/2 receipt says the hop served or failed. Nothing WAI defines says what was sent, to whom, what came back, or what the provider bills, so an implementation has to carry that in a record of its own that WAI's verifier cannot read. This adds WAI's record for it.

The record (route-record §6.2)

wai-route-third-party-hop, signed by the router under its own domain and named by its digest:

• Who and how: the provider and its API origin, whose account the hop ran on (operator or customer, never the key), and the provider's id for the work.
• Each exchange: method, URL, times, status, and the bodies sent and received by SHA-256 and length. A response is kept where it was JSON.
• What came of it: the outputs by name and content hash, the usage the provider bills in the endpoint's unit, and what it reported charging, in its own terms and never added to anything.

It holds no secret. No header has a member, since a key travels in one, and no URL states its query, since a provider's signed link is a bearer token. third_party::kept_response and url_without_query make a response and a URL what a record may state, and a record that keeps one is refused.

Three design choices

• No route record changes. The record names the hop's receipt, which the route record already names, so the chain closes without a new record version.
• No energy member. The hop's receipt already states the figure, or the unmetered marker where the provider gave none.
• Usage in the entry's unit. A record's usage.unit must be the unit of its endpoint's candidate. A ledger line can then bill the record's usage at the entry's price, which is the next step.

Verification (§7.2 step 9)

A verification document may carry third_party, the records' texts, beside its receipts. Each record is held to:

• the route record's signer and job;
• its attempt's endpoint, receipt, outcome, error and times;
• that endpoint's candidate's provider and unit;
• when it served, its outputs to what the hop's receipt names and the attempt's count.

Three new reasons: third_party_invalid, third_party_mismatch, third_party_output_mismatch. A document without third_party reads exactly as before, and its outcome has no such member.

Tests

Routes corpus 126 → 236 vectors: nine accepted and 101 controls of one defect each, including every form and bound of §6.2 at its first value past the limit.

• Rust: the corpus regenerates byte for byte and tests/route_record.rs passes. Each of 79 mutations of third_party.rs and of verify's step 9, one per rule, is caught by the corpus, and the restored tree passes. wai breaking reports nothing unacknowledged.
• Python: route_record_verify.py, written from the text, gives every vector its outcome. All 1,119 mutated copies fail, and the corpus catches each of its 103 checks when dropped. It now stops a mutated copy at its first failure, since it only asks whether one fails.

Not covered: the record states what the router says it sent and received. The provider signs nothing, so the record proves the router's statement and binds it by digest to the bytes, which only a holder of the bytes can check. §11 says so.

Not in this PR

Ledger kind 17, a job line billing the record's usage, and the provider's charge beside the line come next, then the catalogue operations and kinds for exact upscale and tonemap. This record is usable and verifiable without them.

🤖 Generated with Claude Code

A hop sent to a third party's endpoint is work the router did not do. Its OER/2 receipt says the hop served or failed. Nothing WAI defines says what was sent, to whom, what came back, or what the provider bills, so an implementation has to carry that in a record of its own that WAI's verifier cannot read. This adds WAI's record for it. ## The record (route-record §6.2) `wai-route-third-party-hop`, signed by the router under its own domain and named by its digest: - **Who and how:** the provider and its API origin, whose account the hop ran on (`operator` or `customer`, never the key), and the provider's id for the work. - **Each exchange:** method, URL, times, status, and the bodies sent and received by SHA-256 and length. A response is kept where it was JSON. - **What came of it:** the outputs by name and content hash, the usage the provider bills in the endpoint's unit, and what it reported charging, in its own terms and never added to anything. **It holds no secret.** No header has a member, since a key travels in one, and no URL states its query, since a provider's signed link is a bearer token. `third_party::kept_response` and `url_without_query` make a response and a URL what a record may state, and a record that keeps one is refused. ## Three design choices - **No route record changes.** The record names the hop's receipt, which the route record already names, so the chain closes without a new record version. - **No energy member.** The hop's receipt already states the figure, or the unmetered marker where the provider gave none. - **Usage in the entry's unit.** A record's `usage.unit` must be the unit of its endpoint's candidate. A ledger line can then bill the record's usage at the entry's price, which is the next step. ## Verification (§7.2 step 9) A verification document may carry `third_party`, the records' texts, beside its receipts. Each record is held to: - the route record's signer and job; - its attempt's endpoint, receipt, outcome, error and times; - that endpoint's candidate's provider and unit; - when it served, its outputs to what the hop's receipt names and the attempt's count. Three new reasons: `third_party_invalid`, `third_party_mismatch`, `third_party_output_mismatch`. A document without `third_party` reads exactly as before, and its outcome has no such member. ## Tests Routes corpus 126 → 236 vectors: nine accepted and 101 controls of one defect each, including every form and bound of §6.2 at its first value past the limit. - **Rust:** the corpus regenerates byte for byte and `tests/route_record.rs` passes. Each of 79 mutations of `third_party.rs` and of `verify`'s step 9, one per rule, is caught by the corpus, and the restored tree passes. `wai breaking` reports nothing unacknowledged. - **Python:** `route_record_verify.py`, written from the text, gives every vector its outcome. All 1,119 mutated copies fail, and the corpus catches each of its 103 checks when dropped. It now stops a mutated copy at its first failure, since it only asks whether one fails. **Not covered:** the record states what the router says it sent and received. The provider signs nothing, so the record proves the router's statement and binds it by digest to the bytes, which only a holder of the bytes can check. §11 says so. ## Not in this PR Ledger kind 17, a job line billing the record's usage, and the provider's charge beside the line come next, then the catalogue operations and kinds for exact upscale and tonemap. This record is usable and verifiable without them. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 3 commits 2026-11-02 05:04:03 -05:00

route-record §6.2: a third party's hop has a signed record of what was sent, what came back, and what the provider bills ... 8181d9b8f5

A hop sent to a third party's endpoint is work the router did not do. Its OER/2 receipt says the
hop served or failed; nothing WAI defines says what was sent, to whom, what came back, or what
the provider bills, so an implementation carries that in a record of its own that WAI's verifier
cannot read.

`wai-route-third-party-hop`, signed by the router and named by its digest: the provider and its
API origin, whose account the hop ran on (never the key), the provider's id for the work, each
exchange (method, URL without its query, times, status, the bodies by SHA-256 and length, the
response where it was JSON, with links' queries removed), the outputs by name and content hash,
the usage the provider bills, in the endpoint's unit, and what it reported charging, in its own
terms.

A verification document may carry the records beside its receipts (§7.2 step 9). Each is held to
the route record's signer and job, to its attempt and that attempt's candidate, and when it served,
its outputs to what the hop's receipt names and the attempt's count. No route record changes, since
the record names the receipt the route record already names.

routes corpus: 126 -> 202 vectors, from fixed seeds, every control refused at its own place.
route_record_verify.py verifies each from the text, shares no code with wai-rs, and catches each of
its 85 checks dropped and all 1,051 mutated copies.

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

route-record §6.2: every form and bound of the third-party hop record has its control ... 4918ed2e11

The Rust mutations showed a usage's quantity of the wrong type went uncaught, and the same held of
other forms and bounds the text states. Each now has a control, at its first value past the limit,
so the two implementations are held to the same limits. A clause `unhex` already made redundant
is gone. The document kind is in the registry.

The Python verifier stops a mutated copy at its first failure: it only asks whether one fails.

routes corpus: 236 vectors. route_record_verify.py: 103 checks, 1,119 mutated copies.

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

CHANGELOG: Reason::ALL's length is acknowledged as breaking ... 010c66d01e

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

dcharlot force-pushed wai/third-party-hop from 010c66d01e to 2e3f09bcf0 2026-11-02 08:03:26 -05:00 Compare

dcharlot merged commit cbc64f3100 into main 2026-11-02 11:04:26 -05:00

dcharlot referenced this pull request from a commit 2026-11-02 11:04:28 -05:00

Merge pull request 'route-record: a third party's hop has a signed record of what was sent, what came back, and what the provider bills' (#572) from wai/third-party-hop into main

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!572

No description provided.