Transaction-Science/open-standards
Watch
1
0
Fork
You've already forked open-standards
 0
Code Issues Pull requests Projects Releases 15 Packages Wiki Activity Actions 13

wai: energy-aware content steering, each client's pathway chosen by the joules its hops signed (L15) #330

Merged
dcharlot merged 10 commits from wai/steering into main 2026-10-19 06:00:24 -04:00
Conversation 0 Commits 10 Files changed 21 +7932 -11
21 changed files with 7932 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

34
.github/workflows/wai-conformance.yml vendored
View file

@ -88,6 +88,10 @@ on:
# reports, live_metering_verify.py reads that table, and the registry's wire identifiers
# test reads its sections.
- 'wai/extensions/live-metering.md'
# tests/energy_steering.rs requires this extension's §10 to list the codes the reference
# reports, energy_steering_verify.py reads that table, and the registry's wire
# identifiers test reads its sections.
- 'wai/extensions/energy-steering.md'
- 'wai/wai-web/**'
# The audio provenance check below reads the corpora above with this tool.
- 'wai/tools/wai_audio_provenance_check.py'
@ -147,6 +151,10 @@ on:
# reports, live_metering_verify.py reads that table, and the registry's wire identifiers
# test reads its sections.
- 'wai/extensions/live-metering.md'
# tests/energy_steering.rs requires this extension's §10 to list the codes the reference
# reports, energy_steering_verify.py reads that table, and the registry's wire
# identifiers test reads its sections.
- 'wai/extensions/energy-steering.md'
- 'wai/wai-web/**'
# The audio provenance check below reads the corpora above with this tool.
- 'wai/tools/wai_audio_provenance_check.py'
@ -811,8 +819,9 @@ jobs:
# live_events_verify.py (the live-events corpus), and live_rooms_verify.py (the
# live-rooms corpus), and capture_take_verify.py (the capture-binding corpus), and
# live_compose_verify.py (the live-compose corpus), live_record_verify.py (the
# live-recording corpus), timed_text_verify.py (the timed-text corpus), and
# live_metering_verify.py (the live-metering corpus).
# live-recording corpus), timed_text_verify.py (the timed-text corpus),
# live_metering_verify.py (the live-metering corpus), and energy_steering_verify.py (the
# energy-steering corpus).
# Each exits non-zero on any failure or any difference, and the step fails with it.
# One platform: what they check is the reading of the text, not the architecture.
independent-verifiers:
@ -1062,6 +1071,27 @@ jobs:
(cd wai-rs && cargo test --no-default-features --features live_metering --lib live_metering::)
(cd wai-rs && cargo test --no-default-features --features live_metering --test live_metering)
python3 -I live-conformance/live_metering_verify.py live-conformance/metering
# wai.live.steering (extensions/energy-steering.md): the reference module's unit tests
# (policies and decisions round-trip and their rules refuse, the window, the request
# reader over HLS, DASH and CMCD, the RFC 9651 parser, exact products at their limits,
# the margin at its boundary, figures compared only within a class, and a pathway with
# no figure never placed first by its rank while one with a figure is within the
# limits) and tests/energy_steering.rs (the committed corpus regenerates byte for byte
# from its fixed seeds, wai-rs gives every request and vector its stated outcome, every
# reason of §10 refuses a vector, and §10 lists exactly the reference's codes); then the
# corpus's second implementation, energy_steering_verify.py, written from the
# extension's text and sharing no code with wai-rs, which reads the room with
# live_rooms_verify.py and the per-hop records with live_metering_verify.py, parses RFC
# 9651 itself, recomputes every report, figure, decision and manifest, and requires
# every mutated copy of the corpus to fail; standard library only, run isolated (-I).
- name: energy steering · wai-rs and energy_steering_verify.py
working-directory: wai
shell: bash
run: |
set -euo pipefail
(cd wai-rs && cargo test --no-default-features --features energy_steering --lib energy_steering::)
(cd wai-rs && cargo test --no-default-features --features energy_steering --test energy_steering)
python3 -I live-conformance/energy_steering_verify.py live-conformance/steering
# The quantum corpus's second implementation (quantum-sim extension), integers only:
# it derives the circuit/1 phase table by its recurrence and the circuit2 table by an
# interval-certified procedure, and requires both literal tables and their digests,

42
wai/CHANGELOG.md
View file

@ -6,6 +6,48 @@ wire format may change and such changes are recorded here.
## v0.4.0 — current
### `wai.live.steering`: each client's pathway, chosen by the joules its hops signed
- **The extension** ([energy-steering](extensions/energy-steering.md)) registers the record
`wai.live.steering`. The operator signs a **steering policy**, `WSP1`: the pathways (each a
pathway ID of the content description or a clone of one, through another host), each
pathway's hops (edge or interior, a hop in one pathway only), the quality floor, the latency
ceiling, each pathway's capacity and minimum share, the hysteresis margin, the TTLs, and the
period and window over which the hops' per-hop records (`WMH1`) are read. The new key-log
authority `live/steer` lets an operator key sign policies and decisions.
- **The evidence.** A pathway's figure is its hops' joules over the window, per media byte its
edge hops delivered or per microsecond of delivery at the floor tier or above, with the
records' common acquisition class. The window ends on the last period past a lag, and every
hop's records must tile it exactly, so every pathway is read over the same span and a
record left out makes the pathway **stale**, never cheaper. A pathway with an unmetered hop,
hops of two classes, stale records or no delivery has **no figure**: a decision that gives
one a figure is refused `unmetered_as_zero` or `classes_summed`.
- **The rule.** Pathways are ordered by class (calibrated instrument, counter, model,
estimate), within a class by figure, compared by exact products, and then by ID; a pathway
with no figure comes after every pathway with one, so not measuring is never rewarded. A
client with a short buffer or at its quality floor is held; a session's draw, fixed for the
session, places it on a pathway by that pathway's minimum share whatever its evidence; a
client moves off its pathway only for a figure lower by more than the margin. The output is
the priority, the TTL and the reason the first pathway is first.
- **The steering decision**, `WSD1`, names the policy, the records by digest, the client's
report (read from `_HLS_pathway` and `_HLS_throughput`, `_DASH_pathway` and
`_DASH_throughput`, and CMCD's `bl` and `mtp` in the query or the `CMCD-Request` header), the
server's session and loads, each pathway's evidence and limits, and the output; a verifier
recomputes all of it; ten refusal reasons.
- **The mappings.** The steering manifest of `draft-pantos-content-steering-04`, which HLS
(`draft-pantos-hls-rfc8216bis-22` §7) and DASH (ETSI TS 103 998 V1.1.1) read, written byte
for byte with `PATHWAY-CLONES`, a `RELOAD-URI` carrying the session, and one member,
`science.transaction.wai-decision`, naming the decision's URI, which players ignore; the
`EXT-X-CONTENT-STEERING` tag and the DASH `ContentSteering` element.
- **Reference and corpus.** `wai-rs` feature `energy_steering` (`src/energy_steering.rs`, with
an RFC 9651 parser of its own); `live-conformance/steering/`, written from fixed seeds by
`wai_energy_steering_vectors`, its figures synthetic, and checked by
`tests/energy_steering.rs` and by `live-conformance/energy_steering_verify.py`, a second
implementation that shares no code with `wai-rs`, reads the room and the per-hop records
with their corpora's second implementations, recomputes every report, figure, decision and
manifest, and requires every mutated copy of the corpus to fail. The registry lists the
record and the magics `WSP1` and `WSD1`; jwp-receipts §7.5 lists `live/steer`.
### Live ingest and egress: WHIP and WHEP onto a room's tracks, E-RTMP v2 and SRT mapped
- **The extension** ([live-ingest](extensions/live-ingest.md)) binds the contribution and

7
wai/REGISTRY.md
View file

@ -40,8 +40,8 @@ Every registered string has one kind.
- **record** — a signed record a WAI tool emits and verifies (a receipt kind:
`wai.asset.provenance`, the quantum-operations receipts, the delivery records
`wai.video.manifest` and its siblings; the live records `wai.live.events`,
`wai.live.room`, `wai.capture.take`, `wai.live.compose`, `wai.live.recording` and
`wai.live.metering`; timed text, `wai.text.timed`).
`wai.live.room`, `wai.capture.take`, `wai.live.compose`, `wai.live.recording`,
`wai.live.metering` and `wai.live.steering`; timed text, `wai.text.timed`).
It names no payload format.
A derivation or record string is not a payload capability, so it is not
@ -200,6 +200,7 @@ and a role are fixed once registered.
| `wai.live.metering` | record | registered | — | — | — | — | — | §5 Interactive, temporal & computed content |
| `wai.live.recording` | record | registered | — | — | — | — | — | §5 Interactive, temporal & computed content |
| `wai.live.room` | record | registered | — | — | — | — | — | §5 Interactive, temporal & computed content |
| `wai.live.steering` | record | registered | — | — | — | — | — | §5 Interactive, temporal & computed content |
| `wai.mesh.draco` | payload | registered | volumetric | standalone | royalty-free | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
| `wai.mesh.glb` | payload | registered | volumetric | standalone | royalty-free | standard-unclassified | — | §5 Interactive, temporal & computed content |
| `wai.meta.dovi` | companion | registered | metadata | companion | proprietary | standard-unclassified | — | §5 Immersive audio, cinema, volumetric, haptics, HDR |
@ -314,7 +315,9 @@ and a role are fixed once registered.
| `WRG1` | magic | defined | live-rooms §4.1 |
| `WRM1` | magic | defined | live-recording §4.1 |
| `WRP1` | magic | defined | live-rooms §10.5.1 |
| `WSD1` | magic | defined | energy-steering §7.1 |
| `WSIX` | magic | defined | packaging §6 |
| `WSP1` | magic | defined | energy-steering §3.1 |
| `WTM1` | magic | defined | capture-binding §7.1 |
| `WTX1` | magic | defined | timed-text §4.2 |
| `WUR1` | magic | defined | capture-binding §6.2 |

18
wai/SPEC.md
View file

@ -592,8 +592,9 @@ kind:
`wai.asset.provenance`, `wai.quantum.calibration`, `wai.quantum.job`, and the
delivery records `wai.video.manifest`, `wai.video.ssai`, `wai.video.keys`,
`wai.video.package` and `wai.video.channel`; and the live records `wai.live.events`,
`wai.live.room`, `wai.capture.take`, `wai.live.compose`, `wai.live.recording` and
`wai.live.metering`, and timed text, `wai.text.timed`), which names no payload format.
`wai.live.room`, `wai.capture.take`, `wai.live.compose`, `wai.live.recording`,
`wai.live.metering` and `wai.live.steering`, and timed text, `wai.text.timed`), which names
no payload format.
Only payload, companion and refinement capabilities have a media class, a
fidelity tier, a replicate class and a role. A derivation or record string is not a payload
@ -965,6 +966,19 @@ WHEP (`draft-ietf-wish-whep-05`) out of them, every object verified against its
before a player gets it; and, as mappings, Enhanced RTMP v2 multitrack and SRT:
[`extensions/live-ingest.md`](extensions/live-ingest.md).
And for **which pathway** delivers a room's stream to each client — `wai.live.steering`: the
operator signs a steering policy, `WSP1`, naming the pathways (CDNs, relay trees, an origin
path, and their clones), the hops of each, the quality floor, the latency ceiling, each
pathway's capacity and minimum share, and the window over which the hops' per-hop records are
read. A steering server derives each pathway's joules per delivered byte, or per delivered
second at the floor tier, from those records with their acquisition class, compares figures
only within a class, ranks a pathway whose energy is not known (an unmetered hop, two
classes, stale records) after every pathway whose energy is, holds a client against a figure
within a margin, and signs a steering decision, `WSD1`, naming the records, the client's
report, its own inputs and the output, which a verifier recomputes. The output is the steering
manifest HLS and DASH players already read, written byte for byte, with the decision's URI in
one member players ignore: [`extensions/energy-steering.md`](extensions/energy-steering.md).
### Payloads of the WAI-native integer codecs
This revision pins a payload format to each WAI-native integer codec whose row named

690
wai/extensions/energy-steering.md Normal file
View file

@ -0,0 +1,690 @@
# WAI Extension: Energy-Aware Content Steering
> Status: Draft. Registers the record `wai.live.steering`: a steering server's choice, for
> one client, of the pathway that delivers a room's stream for the fewest joules within the
> operator's quality and latency limits, decided from the per-hop session records
> ([live-metering](live-metering.md) §3, `WMH1`) that each pathway's hops signed, and signed
> so that anyone holding those records can recompute it. The operator signs a **steering
> policy**, `WSP1`: the pathways, their hops, their limits and the window the evidence is
> read over. For each request the steering server derives each pathway's **evidence**, its
> joules per delivered byte (or per delivered second at the floor tier) with the
> acquisition class of [energy-measurement](energy-measurement.md) §2, applies one integer
> **decision rule**, and signs the **steering decision**, `WSD1`, which names the evidence
> records by digest, the client's report, the server's own inputs and the output. A figure
> is compared only with figures of its class; a pathway whose energy is not known, because a
> hop is unmetered, its classes differ or its evidence is stale, is never ranked above one
> whose energy is, so that not measuring is never rewarded. The output is the steering
> manifest that HLS and DASH players already read, written byte for byte, carrying the
> decision's URI in one key that players ignore. No new transport. The reference
> implementation is the `energy_steering` module of `wai-rs` (feature `energy_steering`);
> the corpus is [`live-conformance/steering/`](../live-conformance/steering/), and its
> second implementation is `live-conformance/energy_steering_verify.py`.
> Keywords **MUST**, **MUST NOT**, **SHOULD**, **MAY** are RFC 2119/8174.
>
> Texts read for this revision: `draft-pantos-hls-rfc8216bis-22` (§4.4.6.6, the
> `EXT-X-CONTENT-STEERING` tag, and §7, content steering in HLS) and
> `draft-pantos-content-steering-04` (§2 to §7: pathway IDs, the steering manifest, pathway
> cloning, query parameters and client behaviour), Internet-Drafts not past Working Group
> Last Call; ETSI TS 103 998 V1.1.1 (2024-01), content steering for DASH (clauses 5 to 8);
> CTA-5004-B (the CMCD keys `bl` and `mtp`, and the query and header modes); RFC 9651 §4.2;
> RFC 3986 §2; RFC 8259; RFC 8032; FIPS 180-4. A section number of one of those drafts in
> this text is that revision's.
## 1. Scope
In scope: the steering policy, its pathways and limits, and who signs it (§3); what a
steering server reads from a client's steering request (§4); a pathway's evidence and its
figure (§5); the decision rule (§6); the steering decision record and who signs it (§7);
the steering manifest, the HLS tag and the DASH element, written exactly, and how the
record rides beside them (§8); verification (§9).
Out of scope: a transport, and a steering server's network service, which this extension
describes only through its inputs and its output; how a hop measures its energy, which
energy-measurement governs; how an operator chooses its limits; and how a player applies a
steering manifest, which the three texts above fix and this extension does not change.
Relationship to the core spec: `wai.live.steering` is a **record** ([SPEC](../SPEC.md) §5):
a signed record a WAI tool emits and verifies. It names no payload format and is not
dispatchable.
## 2. Terms
- **Room**, **room clock**, **room key**, **hop**, **per-hop session record**, **unmetered
marker**: as in live-rooms §2 and live-metering §2. A record's **digest** is live-metering
§3.5's.
- **Pathway**, **pathway ID**, **pathway clone**, **base pathway**, **steering manifest**,
**steering server**: as in `draft-pantos-content-steering-04` §2. A pathway is an HLS
pathway (rfc8216bis-22 §7.1) and a DASH service location (ETSI TS 103 998 clause 5.1).
- **Content description**: the HLS multivariant playlist or the DASH MPD.
- **Edge hop** of a pathway: a hop whose sessions are clients of the stream; **interior
hop**: a hop of the pathway that feeds other hops.
- **Tier**: a quality level, numbered from 0, the lowest. Tier *i* is the room's layer
class *i* (live-metering §3.3), and the policy states its bitrate.
- **Class**: an acquisition class of energy-measurement §2, by its tag (§2.7): 2
`ModelBased`, 3 `Estimator`, 4 `OnChipCounter`, 5 `CalibratedInstrument`.
- *u128*, *u64*, *u32*, *u16*, *u8*: little-endian unsigned integers of that many bits. A
digest is SHA-256 (FIPS 180-4), 32 bytes. **ppm**: parts per million.
- Every quantity in this text is an integer and every operation is exact: a product is
formed in full, never rounded or saturated, and a quotient is named with its rounding.
## 3. The steering policy
### 3.1 Layout
The operator signs one policy for a room's steering, `WSP1`:
| field | size | meaning |
|---|---|---|
| `magic` | 4 | `WSP1` (ASCII) |
| `version` | 1 | 1 in this revision |
| `room` | 32 | the room id whose per-hop records are the evidence |
| `signer` | 32 | the key that signs the policy (§3.5) |
| `period_us` | 8 | u64: *P*, the period on which the pathways' hops cut their records (§5.1) |
| `window_us` | 8 | u64: *W*, the evidence window, a whole number of periods |
| `lag_us` | 8 | u64: *L*, how long after a period ends its records are first required |
| `basis` | 1 | 1: joules per delivered byte; 2: joules per delivered second at or above the floor tier (§5.3) |
| `floor` | 1 | *F*: the floor tier |
| `latency_ceiling_ms` | 4 | u32: the latency ceiling |
| `min_buffer_ms` | 4 | u32: below this buffer a client is not moved (§6.4) |
| `hysteresis_ppm` | 4 | u32: *h*, the margin by which a pathway must beat a client's current one (§6.4) |
| `ttl_s` | 4 | u32: the steering manifest's TTL |
| `min_ttl_s` | 4 | u32: the TTL when the decision holds a client or finds no pathway within the limits |
| `flags` | 1 | bit 0: DASH `queryBeforeStart`; every other bit 0 |
| `initial` | 1 | the index of the initial pathway of the content description |
| `tiers` | 1 + 8 × *n* | a u8 count *n*, then each tier's bitrate in bits per second (u64), tier 0 first |
| `server_uri` | 2 + … | a u16 length, then the steering server's URI, which the content description names |
| `reload_uri` | 2 + … | a u16 length, then the URI the manifest names for the next request (§8.1) |
| `decision_uri` | 2 + … | a u16 length, then the prefix of the URI at which a decision record is served (§8.4) |
| `pathways` | 1 + … | a u8 count, then each pathway entry (§3.2), in the policy's order |
| `sig` | 64 | §3.4 |
### 3.2 Pathway entries
| field | size | meaning |
|---|---|---|
| `id` | 1 + … | a u8 length, then the pathway ID |
| `base` | 1 | 255: a pathway of the content description; otherwise the index of the pathway it clones |
| `host` | 1 + … | a u8 length, then the clone's `HOST` (§8.1); length 0 for none |
| `params` | 1 + … | a u8 count, then each of the clone's `PARAMS`: a u8 length and the name, a u8 length and the value |
| `top_tier` | 1 | the highest tier the pathway carries |
| `latency_ms` | 4 | u32: the latency the operator states for the pathway |
| `capacity` | 4 | u32: the most sessions the server steers to it first at once; 2^32 − 1 for no limit |
| `min_share_ppm` | 4 | u32: the share of sessions it is placed first for whatever its evidence (§6.3) |
| `hops` | 1 + 33 × *k* | a u8 count *k*, then each hop: its key (32) and its place (u8: 1 edge, 2 interior) |
The pathways that are not clones are the content description's: each is the `PATHWAY-ID` of
its HLS variant streams (rfc8216bis-22 §4.4.6.2) and the `@serviceLocation` of its DASH
`BaseURL` elements (ETSI TS 103 998 clause 5.2). A clone is a pathway of its own, with its
own hops: the same content reached through another host.
### 3.3 Reading and rules
A reader reads exactly the bytes it is given, in the order of §3.1, as live-events §3.3
reads a record, with `WSP1` for `WEV1` (`truncated`, `malformed`, `unknown_version`). It
refuses as `clone_unknown` a policy with a clone whose `base` is not the index of a pathway
before it: a clone of a pathway the manifest would not yet define, which
`draft-pantos-content-steering-04` §5 has a client ignore. It refuses as `policy_invalid` a
policy that breaks any of these:
- `period_us` is above 0, and `window_us` is a multiple of it above 0;
- `basis` is 1 or 2; 1 ≤ `min_ttl_s` ≤ `ttl_s`; `hysteresis_ppm` ≤ 1 000 000; `flags` is 0
or 1;
- 1 ≤ *n* ≤ 8; the bitrates are above 0 and strictly ascending; `floor` < *n*;
- each URI is 1 to 2048 bytes of RFC 3986's characters (unreserved, reserved and `%`, never
`#`), and each `%` begins a percent-encoding of two hexadecimal digits;
- 1 to 32 pathways; each `id` is 1 to 64 bytes of `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `-` and
`_` (content-steering-04 §2), and no two are equal;
- `initial` is the index of a pathway that is not a clone;
- a pathway that is not a clone has no `host` and no `params`; a clone's `host` is at most
255 bytes of `A`–`Z`, `a`–`z`, `0`–`9`, `-` and `.`; its `params` have names of 1 to 64
bytes and values of 0 to 255 bytes, each of RFC 3986's unreserved characters and
percent-encodings, and names in strictly ascending bytewise order (content-steering-04
§5 appends them in UTF-8 order, which is bytewise for these characters);
- each pathway's `top_tier` < *n*; each has at least one hop and at least one edge hop; each
place is 1 or 2; no hop key appears twice in the policy, in one pathway or in two;
- the sum of the `min_share_ppm` is at most 1 000 000.
**A hop belongs to one pathway.** A hop that carries two pathways' traffic signs one figure
for both, and no record states how it divides; a share of it would be an allocation, not a
reading. A hop common to every pathway, such as the origin that feeds them all, changes no
comparison and is listed in none.
### 3.4 Digest and signature
The **digest** of a policy is SHA-256 over its bytes before `sig`. Its **signature** is
Ed25519 (RFC 8032) by `signer` over the 20 bytes `wai:steering-policy` (ASCII) and 0x01,
followed by the bytes the digest covers, verified strictly as [SPEC](../SPEC.md) §7
*Signatures* requires: a key that fails step 1 or 2 is `bad_key`, a signature that fails a
later step `bad_signature`.
### 3.5 Who signs: the steering authority
A policy and a decision are signed by the room authority, or by a **steering key**: a key
the room's origin's key log lists, not revoked, with the authority `live/steer` in its
`may_sign` (jwp-receipts §7.5). A decision restates figures with their classes, so its
signer's entry, the room authority's included, **MUST** also hold `energy/` followed by the
label of each class among its figures (§7.1), as jwp-receipts §7.5 requires of every signer
that restates a figure with its class. A room that names no origin has no key log, and only
its authority signs. A signer that is neither is `signer_not_authorised`, and a steering key
whose entry is `revoked` is `signer_revoked` (the codes of live-metering §4.3).
Steering is the operator's act, as metering is, and its key lives in the origin's key log
for the reason live-metering §4.3 gives: a decision moves every client of the room, and a
grant's powers are live-rooms' closed set.
## 4. The client's report
A steering request is an HTTP GET of the steering server's URI, or of the last manifest's
`RELOAD-URI`. The server reads three things from it, each **absent** when the request does
not carry it in the form below; a value that does not read is absent, never zero:
- the client's **current pathway**, *c*: the index of a pathway of the policy;
- its **throughput**, *T*: bits per second;
- its **buffer**, *B*: milliseconds.
### 4.1 The query
The query is the request target's bytes after its first `?` and before any `#`. It is cut
at each `&` into parts; a part is cut at its first `=` into a name and a value (a part with
no `=` has an empty value), and both are percent-decoded (RFC 3986 §2.1; `+` is not a
space). A part with a `%` not followed by two hexadecimal digits is skipped. Of the parts
with a name the server reads, the first is read and later ones are ignored. A value is
**unquoted** by removing one `"` at each end when it both begins and ends with one.
An **integer** here is 1 to 20 ASCII digits whose value is at most 2^64 − 1.
### 4.2 HLS
rfc8216bis-22 §7.4 has the client add `_HLS_pathway="<CURRENT-PATHWAY-ID>"` and
`_HLS_throughput=<THROUGHPUT>`, the throughput an integer number of bits per second:
- *c*: `_HLS_pathway`, unquoted, when it is the `id` of a pathway of the policy;
- *T*: `_HLS_throughput`, when it is an integer.
### 4.3 DASH
ETSI TS 103 998 clause 7 step 7 has the client add `_DASH_pathway`, the service locations it
used since its last request, comma-separated within one pair of double quotes, and
`_DASH_throughput`, a comma-separated list of integer bits per second, the *n*-th for the
*n*-th service location:
- *c*: of `_DASH_pathway`, unquoted and cut at each `,`, the first item that is the `id` of a
pathway of the policy, at position *j* of the list (from 0);
- *T*: of `_DASH_throughput`, cut at each `,`, the item at position *j*, or at 0 when no
pathway is current, when it is an integer.
The clause's own example writes `_DASH_pathway` without quotes, so both are read.
### 4.4 CMCD
A client that reports CMCD (CTA-5004-B) sends its keys as the query parameter `CMCD`, or in
the header shards; CTA-5004-B assigns `bl` (buffer length, milliseconds) and `mtp`
(measured throughput, kilobits per second) to the shard `CMCD-Request`. The server reads
the `CMCD` parameter's value or, when the query has no such part, the `CMCD-Request`
header's value, as an RFC 9651 Dictionary (§4.2.2 of that RFC, the whole grammar, Dates and
Display Strings included, and a Byte Sequence whose content is not base64 of RFC 4648 §4, its
padding supplied where it is missing, refused); a value that does not parse gives neither
key. A key read is:
- an Integer of 0 or above; or a non-empty Inner List of such Integers, each with any
parameters (CTA-5004-B carries one per object type, its token a parameter): the **least**
of them, the object type whose buffer runs out first, or the slowest measurement;
- anything else, absent.
Then *B* is `bl`, and when §4.2 or §4.3 gives no *T*, *T* is `mtp` × 1000.
## 5. A pathway's evidence
### 5.1 The window
A pathway's hops cut their per-hop records (live-metering §3.8) on the policy's period: each
record's span runs from one multiple of *P* on the room clock to a later one. At a decision's
instant *t* on the room clock the **window** is [*a*, *b*), with
b = ⌊(t − L) / P⌋ × P (0 when t < L)
a = b − W (0 when b < W)
so that the window ends on the last period that has been over for at least *L*: *L* gives a
hop's record of a period time to reach the steering server before the server needs it. A
record is **in the window** when *a* ≤ its `start` and its `end` ≤ *b*.
### 5.2 Coverage and staleness
A decision names, for each pathway, the records of its hops it read, grouped by hop in the
pathway's hop order and each hop's in ascending order of `start` (§7.1). A hop is
**covered** when the records named for it **tile** the window: there is at least one, the
first starts at *a*, each starts where the one before it ends, and the last ends at *b*. The
window is then empty for no hop: when *a* = *b* no hop is covered.
A pathway's evidence is **stale** when one of its hops is not covered: a period the hop has
not signed, or whose record has not reached the server within *L*; a gap; an overlap; a
record that does not reach to *b*. Its energy over the window is then not known, and §6
ranks it so. Because the window is tiled exactly, every hop of every pathway is read over
the same span, so the figures of two pathways describe the same stretch of room clock; and a
server that leaves out a record makes a pathway stale. It cannot make one look cheaper.
### 5.3 The figure
Over the records named for a pathway, its **status** is the first of these that holds:
1. **stale** (3): a hop is not covered (§5.2);
2. **unmetered** (1): a record's figure is the unmetered marker;
3. **mixed** (2): the records' classes are not all one;
4. **empty** (4): *D* = 0;
5. **figure** (0): otherwise.
Its **joules** *J* is the sum of the records' `joules`, in microjoules, and its **delivery**
*D* is, over the records of its edge hops:
- with `basis` 1, the sum of the `bytes` of every track entry of kind 1 (a media track) and
direction 2 (out): the media bytes the pathway delivered;
- with `basis` 2, the sum of `subscriber_us`[*c*] for the layer classes *c* from *F* to 7:
the microseconds of delivery at the floor tier or above.
A pathway of status figure has the **figure** *J* / *D*, in the records' common class; a
figure is never written as a quotient, and two figures are compared by their products (§6.2).
On `basis` 2 the pathway's every joule is charged to its delivery at the floor tier or above,
so the figure is never less than the joules per such second that any division of the hops'
joules among tiers would give.
### 5.4 What is not known is not zero
A pathway of any status other than figure has **no figure**, and its *J* and *D* are stated
as 0 (§7.2). In particular:
- **An unmetered hop is not a hop of zero joules.** A sum over a pathway's records that
leaves out an unmetered record would state less energy than the pathway spent, and the
less a pathway measured the cheaper it would look. A decision that gives a pathway with an
unmetered record a figure is refused `unmetered_as_zero`.
- **Figures of two classes are not summed.** A `ModelBased` figure added to an
`OnChipCounter` figure is neither, and labelled as either it would present a model as a
reading or a reading as a model (live-metering §4.5). A decision that gives a pathway of
mixed classes a figure is refused `classes_summed`.
- **Stale evidence is not current evidence**, and a pathway whose hops delivered nothing
(empty) has no rate to state.
## 6. The decision rule
The rule is a function of the policy; the evidence (§5); the client's report (§4); the
client's **session**, 16 bytes the server minted at the client's first request and carries
in the manifest's `RELOAD-URI` (§8.1); and each pathway's **load**, the number of sessions
the server is steering to it first, its own count. Its output is the order of the pathways,
a TTL and the reason the first was chosen.
### 6.1 Limits
A pathway *p* is **within the limits** for the request when all three hold:
- **latency**: its `latency_ms` ≤ `latency_ceiling_ms`;
- **quality**: its `top_tier` ≥ *F*: it carries the floor tier;
- **capacity**: its `capacity` is 2^32 − 1; or its load < `capacity`; or it is *c* and its
load ≤ `capacity`, since *c*'s load already counts the client.
### 6.2 The order
A pathway's **rank** is set by its evidence: 0 for a figure of class 5
(`CalibratedInstrument`), 1 of class 4 (`OnChipCounter`), 2 of class 2 (`ModelBased`), 3 of
class 3 (`Estimator`), and 4 for no figure. Pathway *p* comes before *q* when, of these, the
first that tells them apart says so:
1. *p*'s rank is below *q*'s;
2. both have a figure, of one class, and *J*<sub>*p*</sub> × *D*<sub>*q*</sub> <
*J*<sub>*q*</sub> × *D*<sub>*p*</sub>: *p*'s figure is the lower;
3. *p*'s `id` is below *q*'s, bytewise.
Every two pathways differ in `id`, so the order is total. Figures are compared only within a
class (step 2). Across classes the order is by what backs the figure, the order
energy-measurement §2 gives its classes, and never by the figures: no figure of one class
can be compared with one of another, so the rule cannot tell which of two such pathways
spends less, and it prefers the evidence it can rely on. A pathway with no figure comes after
every pathway with one (step 1), and among pathways with no figure only the `id` orders them
(step 3): being unknown cannot raise a pathway above any pathway whose energy is known, and
nothing about an unknown pathway's energy orders it.
### 6.3 The draw and the minimum shares
The client's **draw** is
d = u32(SHA-256("wai:steering-draw" ‖ 0x01 ‖ policy digest ‖ session)[0..4]) mod 1 000 000
the first four bytes read as a u32. It is fixed for the session, so it moves no client from
one decision to the next. The policy's pathways, in its order, divide [0, 1 000 000) from 0
into **bands**: pathway *i*'s band is [*S*<sub>*i*</sub>, *S*<sub>*i*</sub> +
`min_share_ppm`<sub>*i*</sub>), with *S*<sub>*i*</sub> the sum of the shares before it. A
session whose draw falls in a pathway's band is placed on that pathway first while it is
within the limits (§6.4 step 4), whatever its evidence.
The minimum shares are how evidence stays fresh: a pathway no client is steered to delivers
nothing, and its records soon state no delivery, or none at all. A pathway's share of
sessions from its band is its `min_share_ppm`, the same whether its energy is known or not,
so a pathway gains no session by being unknown.
### 6.4 The first pathway
The client's **sustainable tier** is, when *T* is known, the highest tier whose bitrate is
at most *T*, or none when tier 0's is above it. The client is **at its floor** when *T* is
known and its sustainable tier is none or at most *F*.
Let *w* be the first pathway of the order (§6.2) that is within the limits. *w* **beats** a
pathway *x* of its rank when both have a figure and
J_w × D_x × (1 000 000 + h) < J_x × D_w × 1 000 000
that is, *w*'s figure is below *x*'s by more than the margin *h*. The first pathway, and the
**reason** it is first, is given by the first of these steps that applies:
1. **buffer** (1): *c* is known and within the limits, *B* is known, and *B* <
`min_buffer_ms`: *c*. A switch costs a fresh start on the new pathway, which a short
buffer may not cover.
2. **floor** (2): *c* is known and within the limits, and the client is at its floor: *c*.
Its throughput was measured on *c*, and a client with no margin above the floor is not
moved to a pathway on which it was never measured.
3. **none** (6): no pathway is within the limits: *c* when it is known, otherwise the first
pathway of the order. The client is not moved for a limit no pathway meets
(content-steering-04 §7 step 5 has it stay).
4. **share** (3): the draw falls in the band of a pathway *e* within the limits: *e*.
5. **hold** (4): *c* is known and within the limits, *c* is not *w*, *c* has *w*'s rank, and
either that rank is 4 or *w* does not beat *c*: *c*. This is the **hysteresis**: a client
moves only for a figure lower than its own by more than the margin, so that two figures
within the margin of each other do not swap its pathway from one decision to the next.
Between two pathways with no figure nothing says that either is cheaper, and the client
stays.
6. **rank** (5): *w*.
Steps 1, 2 and 4 hold a client or place it whatever its pathway's evidence, and so do not
prefer a pathway for being unknown; step 5 holds a client only against a pathway of its own
rank, so a client on a pathway with no figure moves as soon as a pathway with a figure is
within the limits.
### 6.5 The priority and the TTL
The **priority** is the first pathway, then the pathways within the limits in the order
(§6.2), then the others in the order, each once. Every pathway is in it, so a client that
penalises its first pathway (content-steering-04 §7 step 3) falls back in the same order.
The **TTL** is `min_ttl_s` when the reason is buffer, floor or none, so that a client held
or left without a pathway within the limits asks again soon; and `ttl_s` otherwise.
## 7. The steering decision
### 7.1 Layout
For each request the steering server signs a decision, `WSD1`:
| field | size | meaning |
|---|---|---|
| `magic` | 4 | `WSD1` (ASCII) |
| `version` | 1 | 1 in this revision |
| `room` | 32 | the room id |
| `signer` | 32 | the key that signs the decision (§3.5) |
| `policy` | 32 | the policy's digest |
| `t` | 8 | u64: the decision's instant on the room clock, in microseconds |
| `session` | 16 | the client's session (§6) |
| `draw` | 4 | u32: *d* (§6.3) |
| `protocol` | 1 | 1 HLS (§4.2), 2 DASH (§4.3): which parameters the report was read from |
| `report` | 18 | `present` (u8: bit 0 *c*, bit 1 *T*, bit 2 *B*), `pathway` (u8: *c*), `throughput` (u64: *T*), `buffer` (u64: *B*); an absent value is 0 |
| `pathways` | 1 + … | a u8 count, the policy's, then for each pathway in the policy's order: `load` (u32); `limits` (u8: bit 0 latency, bit 1 quality, bit 2 capacity, each set when it holds, §6.1); `status` (u8, §5.3); `class` (u8: the figure's tag, 0 for no figure); `joules` (u128: *J*); `delivery` (u128: *D*); `evidence`, a u8 count and the digest of each record named (§5.2) |
| `ttl` | 4 | u32: the TTL (§6.5) |
| `reason` | 1 | the first pathway's reason (§6.4): 1 buffer, 2 floor, 3 share, 4 hold, 5 rank, 6 none |
| `priority` | 1 + *m* | a u8 count *m*, then the index of each pathway, the first first (§6.5) |
| `sig` | 64 | §7.3 |
### 7.2 Reading and rules
A reader reads the bytes as §3.3 reads a policy, with `WSD1` for `WSP1`, and refuses as
`decision_invalid` a decision that breaks any of these:
- `protocol` is 1 or 2; `draw` < 1 000 000; `ttl` ≥ 1; `reason` is 1 to 6;
- `present` has no bit above 2; an absent value is 0; a present `pathway` is below the
count of `pathways`;
- each pathway's `limits` has no bit above 2 and its `status` is 0 to 4; with status 0 its
`class` is 2 to 5 and its `joules` and `delivery` are above 0; with any other status its
`class`, `joules` and `delivery` are 0;
- no digest is named twice in the decision;
- `priority` names each pathway once: *m* is the count of `pathways` and its indices are a
permutation of 0 to *m* − 1.
### 7.3 Digest and signature
The **digest** of a decision is SHA-256 over its bytes before `sig`; its **signature** is
Ed25519 by `signer` over the 22 bytes `wai:steering-decision` (ASCII) and 0x01, followed by
the bytes the digest covers, verified strictly (SPEC §7 *Signatures*). Who may sign it is
§3.5's rule.
## 8. The mappings
### 8.1 The steering manifest
The output of a decision is one steering manifest (`draft-pantos-content-steering-04` §4,
the DASH Content Steering Manifest of ETSI TS 103 998 clause 6), served with the media type
§11.1 of that draft registers. It is the JSON text (RFC 8259) below, UTF-8, with no white
space outside its strings, its members in this order:
{"VERSION":1,"TTL":<ttl>,"RELOAD-URI":"<reload>","PATHWAY-PRIORITY":[<ids>],
"PATHWAY-CLONES":[<clones>],"science.transaction.wai-decision":"<decision>"}
(one line, cut here for legibility), where:
- `<ttl>` is the decision's `ttl` in decimal digits, with no leading zero;
- `<reload>` is the policy's `reload_uri`, then `&` when it holds a `?` and `?` otherwise,
then `wai_session=` and the session as 32 lowercase hexadecimal digits;
- `<ids>` is the `id` of each pathway of the `priority`, in its order, each in double
quotes, separated by `,`;
- `"PATHWAY-CLONES":[<clones>],` is written only when the policy has a clone. `<clones>` is,
for each clone in the policy's order, separated by `,`:
`{"BASE-ID":"<base id>","ID":"<id>","URI-REPLACEMENT":{<replacement>}}`, where
`<replacement>` is `"HOST":"<host>"` when the clone has a host, then (after a `,` when a
host was written) `"PARAMS":{<params>}` when it has params, `<params>` being
`"<name>":"<value>"` for each, in the policy's order, separated by `,`; and empty when it
has neither;
- `<decision>` is the policy's `decision_uri`, then the decision's digest as 64 lowercase
hexadecimal digits (§8.4).
§3.3's character rules leave nothing in these strings that JSON escapes, so the text is
fixed byte for byte. `PATHWAY-CLONES` is written for every clone, whether or not it is
first, so that a client can fall back to any pathway of the priority.
**HLS and DASH are the same bytes.** ETSI TS 103 998 clause 6.2 defines the same keys as
content-steering-04 §4 and §5, and a DASH client ignores the `URI-REPLACEMENT` keys HLS
adds (`PER-VARIANT-URIS`, `PER-RENDITION-URIS`, rfc8216bis-22 §7.3; clause 7 step 13),
which a policy of this revision does not state. A DASH `PATHWAY-PRIORITY` names service
locations, which are the same IDs (§3.2). The two protocols differ in the request (§4) and
in the content description (§8.2, §8.3).
### 8.2 HLS
The multivariant playlist carries the policy as one tag (rfc8216bis-22 §4.4.6.6):
#EXT-X-CONTENT-STEERING:SERVER-URI="<server_uri>",PATHWAY-ID="<initial id>"
with the policy's `server_uri` and the `id` of its `initial` pathway. The tag's
`PATHWAY-ID` is the pathway a client applies until its first steering manifest, and
content-steering-04 §4 asks that the first manifest's first pathway agree with it: a client
whose first request carries no report and whose draw is in no band gets the first pathway of
the order, which an operator **SHOULD** make the initial one when it writes the policy.
### 8.3 DASH
The MPD carries the policy as one element (ETSI TS 103 998 clause 5.2):
<ContentSteering defaultServiceLocation="<initial id>"
queryBeforeStart="<true|false>"><server_uri></ContentSteering>
(one line), `queryBeforeStart` `true` when the policy's flag bit 0 is set and `false`
otherwise, and the URI with each `&` written `&amp;`, the only character of §3.3's URIs that
XML text escapes. With `queryBeforeStart` `true` a client asks before it starts (clause 7
step 5), and its first request carries no `_DASH_` parameters, so its first decision has no
report.
### 8.4 Carrying the decision
The decision record is served at the URI the manifest's `science.transaction.wai-decision`
member names: the policy's `decision_uri` followed by the decision's digest in hexadecimal.
A player ignores the member: content-steering-04 §4 lets a manifest hold other keys and has
a client ignore any key it does not recognise, and ETSI TS 103 998 clause 6.1 does the same.
The member is the decision's digest, not its signature over the manifest: the manifest is a
function of the decision and the policy (§8.1), and its member names the decision, so there
is no loop between them. A party that holds the manifest fetches the record, verifies it
(§9), and requires that the manifest be the bytes §8.1 writes from it. A steering server
**SHOULD** keep each decision available for as long as the records it names are.
## 9. Verification
### 9.1 Inputs and steps
A verifier is given the room's descriptor and the head of its authority's key log, or none;
the policy; the decision; the per-hop records; and, optionally, the manifest that was served
with the decision. It runs these steps and stops at the first refusal, which it reports with
the reason and where:
1. **The room**, at `room`: the descriptor reads and verifies, and the head is held for its
origin and lists its authority (live-rooms §9.1 steps 1 and 2, with that section's
reasons).
2. **The policy** (§3), at `policy`: `truncated`, `malformed`, `unknown_version`,
`clone_unknown`, `policy_invalid`; `wrong_room` when its `room` is not the room id;
`bad_key`, `bad_signature`; its signer (§3.5), `signer_not_authorised`,
`signer_revoked`.
3. **The decision** (§7), at `decision`: `truncated`, `malformed`, `unknown_version`,
`decision_invalid`; `wrong_room`; `record_missing` when its `policy` is not the given
policy's digest; `decision_invalid` when its count of `pathways` is not the policy's, or a
present `pathway` is not a pathway of it; `bad_key`, `bad_signature`; its signer,
`signer_not_authorised`, `signer_revoked`.
4. **Each record it names**, in order, at `evidence` with the pathway's index and the
record's place in its list:
1. a record whose digest is the one named is given: otherwise `record_missing`;
2. it reads, its room is the room id and its signature verifies (live-metering §3.6:
`truncated`, `malformed`, `unknown_version`, `energy_invalid`, `record_invalid`,
`wrong_room`, `bad_key`, `bad_signature`);
3. its hop may sign it (live-metering §5.2: `hop_not_authorised`, `hop_revoked`): a key
the room's key log does not list for its role and class does not sign evidence;
4. its `hop` is a hop of the pathway it is named under: otherwise
`evidence_not_on_pathway`;
5. it is in the window of the decision's `t` (§5.1): otherwise `evidence_outside_window`;
6. it follows the record named before it under the pathway in the order of §5.2, a later
hop of the pathway or the same hop and a later `start`: otherwise `decision_invalid`.
5. **The evidence** (§5), at `pathway` and its index: each pathway's status, class, *J* and
*D* recompute from its records. A pathway stated with a figure whose records hold the
unmetered marker is `unmetered_as_zero`; one stated with a figure whose records are of
more than one class is `classes_summed`; any other difference is `evidence_mismatch`.
6. **The output** (§6), at `output`: the draw, each pathway's `limits`, the priority, the
TTL and the reason recompute from the policy, the evidence, the report, the session and
the loads. When they do not, the decision is `unknown_preferred` if its first pathway has
no figure while the first of the recomputed priority has one, and `decision_mismatch`
otherwise.
7. **The manifest**, at `manifest`, when one is given: it is the bytes §8.1 writes from the
decision and the policy, otherwise `manifest_mismatch`.
A decision that passes is **accepted**: the priority, the TTL and the reason are what the
rule gives for the evidence the records state, the report and the loads it names.
### 9.2 What is recomputed and what is stated
A decision has inputs of three kinds, and a verifier treats them differently:
- **The evidence** is signed by the hops and verified: its figures cannot be other than the
records give.
- **The report** is the client's, as the server read it (§4). The client does not sign it,
and the decision states it rather than the request, so that a request's other parameters
(tokens, the session) are not published with it.
- **The session and the loads** are the server's own. The decision states them; a verifier
recomputes the rule from them and the draw from the session, and an auditor that holds a
server's decisions checks over them that the loads and the bands' shares are what the
server claims.
### 9.3 Outcome
- **refuse**: the reason and where (§9.1).
- **accept**: the decision's digest; the priority by pathway ID; the TTL and the reason;
each pathway's status, class, *J*, *D* and limits; the steering manifest; and the record's
URI.
## 10. Reasons
The codes this extension adds, each with where it is raised:
| reason | raised at |
|---|---|
| `policy_invalid` | §3.3, §9.1 step 2 |
| `clone_unknown` | §3.3, §9.1 step 2 |
| `decision_invalid` | §7.2, §9.1 steps 3 and 4 |
| `evidence_not_on_pathway` | §9.1 step 4 |
| `evidence_outside_window` | §5.1, §9.1 step 4 |
| `evidence_mismatch` | §5.3, §9.1 step 5 |
| `unmetered_as_zero` | §5.4, §9.1 step 5 |
| `unknown_preferred` | §6.2, §9.1 step 6 |
| `decision_mismatch` | §6, §9.1 step 6 |
| `manifest_mismatch` | §8.1, §9.1 step 7 |
A verifier of this extension also raises `truncated`, `malformed` and `unknown_version` for a
policy, a decision or a record that does not read; `bad_key` and `bad_signature` for their
signatures; `wrong_room` for one of another room; live-metering's `classes_summed`,
`signer_not_authorised`, `signer_revoked`, `record_missing`, `energy_invalid`,
`record_invalid`, `hop_not_authorised` and `hop_revoked`; and live-rooms §9.1's codes for
the room, at `room`.
## 11. Conformance
[`live-conformance/steering/`](../live-conformance/steering/) holds the corpus, in one file,
`vectors.json`, written from fixed seeds by `wai_energy_steering_vectors gen`. It sits beside
the metering corpus because its evidence is per-hop records of live-metering, read by that
corpus's second implementation. It holds a room with its key log, policies, the per-hop
records of the pathways' hops, and:
- **requests**: steering requests over HLS and DASH, with and without CMCD in the query and
in the header, with the report §4 reads from each;
- **vectors**, each a policy, a decision, the records it names and the manifest served with
it, with the outcome §9.3 gives them. **Accepted**: three pathways with figures of one
class; mixed classes, ordered by class; a pathway with an unmetered hop, ranked after those
with figures though its metered hops alone are the cheapest; stale evidence; a client at
its floor, and one with a short buffer, held; hysteresis holding a client and, a period
later, moving it; pathway clones; a session placed by its band; a pathway at its capacity
and one past the latency ceiling; the per-second basis; DASH; and no pathway within the
limits; each with its steering manifest, HLS tag and DASH element byte for byte. Two
more show what has no figure: hops of two classes in one pathway, and, beside the session
its band places, one outside the band, whose unmetered pathway comes last.
**Refused**: each reason of §10, and the codes it reuses from the extensions it reads, at
least once, each vector a control of one defect.
A conforming verifier gives every request its report and every vector the outcome, the
reason, the place and the facts the corpus states. `wai_energy_steering_vectors verify` and
the test `tests/energy_steering.rs` check that the file regenerates byte for byte, that
`wai-rs` gives every request and vector its outcome, that every reason of §10 refuses a
vector, and that §10 lists exactly the reference's codes.
`live-conformance/energy_steering_verify.py` is the second implementation, written from
this text: it shares no code with `wai-rs`, verifies signatures with WAI's strict rule written
from RFC 8032 (`claim-conformance/_ed25519.py`), reads the room with `live_rooms_verify.py`
and the per-hop records with `live_metering_verify.py`, parses RFC 9651 itself, recomputes
every report, figure, decision and manifest with Python's integers, gives every request and
vector the same outcome, and requires every mutated copy of the corpus to fail.
The corpus's energy figures are synthetic, chosen to exercise the rule. It computes which
pathway the rule places first, and claims nothing about the energy any deployment spends or
saves.
## 12. Security and privacy considerations
- **The evidence is signed; the choice is checkable.** A steering server cannot state a
figure the records do not give, or a priority the rule does not, without its decision
being refused. What it can do is leave records out, which makes a pathway stale (§5.2)
and so ranks it lower, never higher; and state its own loads and sessions (§9.2), which
only an audit over its decisions checks.
- **Not measuring is never rewarded.** No status other than figure gives a pathway a
figure (§5.4), no pathway with no figure ranks above one with a figure (§6.2), and the
rules that place a client whatever its pathway's evidence (§6.4 steps 1, 2 and 4) give a
pathway with no figure no more than they give one with a figure. An operator that wants a
pathway preferred meters it.
- **Measuring better is rewarded, measuring worse is not penalised below unknown.** Across
classes the order is by what backs the figure; a pathway of the weakest class still ranks
above every pathway with no figure.
- **A hop's figure is its own statement** (energy-measurement §5): the decision makes the
choice recomputable from what the hops signed, not the figures true. A hop that understates
its energy wins traffic, and the remedies are those of live-metering §11: its class says
how the figure was obtained, the key log confines which classes a key may state, and an
upstream hop's record contradicts a downstream one's.
- **Flapping.** The draw is fixed for a session, the window moves one period at a time, and
the margin *h* keeps a client on its pathway against a figure within it (§6.4 step 5).
- **Privacy.** A decision holds no identifier of the client beyond its session, which the
server minted and which names no person; the report is the throughput and buffer the
client sends to every steering server; and the decision does not carry the request, so a
token in its query is not published with it (§9.2). A CMCD report is read for `bl` and
`mtp` alone, and the decision keeps nothing else of it.

1
wai/extensions/jwp-receipts.md
View file

@ -3250,6 +3250,7 @@ A confirmation needs every one of them:
| an upload receipt of a take ([capture-binding](capture-binding.md) §6) | `capture/store` |
| a per-hop session record ([live-metering](live-metering.md) §3) | `live/relay`, `live/compositor` or `live/ingest`, by its role; and `energy/<class>` for its figure's class where it is metered |
| a room-session receipt (live-metering §4) signed by a key other than the room authority | `live/meter`; and, from any signer, `energy/<class>` for each class it totals |
| a steering policy or steering decision ([energy-steering](energy-steering.md) §3.5) signed by a key other than the room authority | `live/steer`; and, from any signer of a decision, `energy/<class>` for each class among its figures |
A class registered in §2.4.4 registers its authority here with it, and a
family that needs a narrower authority than `receipt` registers one here.

9
wai/live-conformance/README.md
View file

@ -12,14 +12,16 @@ and the independent verifier of each, beside it.
| [`recordings/`](recordings/) | [live-recording](../extensions/live-recording.md) (`wai.live.recording`) | `live_record_verify.py` |
| [`captions/`](captions/) | [timed-text](../extensions/timed-text.md) (`wai.text.timed`) | `timed_text_verify.py` |
| [`metering/`](metering/) | [live-metering](../extensions/live-metering.md) (`wai.live.metering`) | `live_metering_verify.py` |
| [`steering/`](steering/) | [energy-steering](../extensions/energy-steering.md) (`wai.live.steering`) | `energy_steering_verify.py` |
**Provenance.** Generated here: `wai_live_events_vectors gen` writes `events/`,
`wai_live_room_vectors gen` writes `rooms/`, `wai_capture_take_vectors gen` writes
`takes/`, `wai_live_compose_vectors gen` writes `compose/`, `wai_live_record_vectors gen`
writes `recordings/`, `wai_timed_text_vectors gen` writes `captions/` and
`wai_live_metering_vectors gen` writes `metering/`, each from records authored in code, from
fixed seeds (`events/README.md`, `rooms/README.md`, `takes/README.md`, `compose/README.md`,
`recordings/README.md`, `captions/README.md`, `metering/README.md`). One recorded record:
`wai_live_metering_vectors gen` writes `metering/` and `wai_energy_steering_vectors gen` writes
`steering/`, each from records authored in code, from fixed seeds (`events/README.md`,
`rooms/README.md`, `takes/README.md`, `compose/README.md`, `recordings/README.md`,
`captions/README.md`, `metering/README.md`, `steering/README.md`). One recorded record:
`metering/relay-record.wmh` and its ledger, which the reference relay signed in its test.
Each verifier is written from its extension's text, shares no code with `wai-rs`, and is
@ -33,4 +35,5 @@ python3 live_compose_verify.py compose
python3 live_record_verify.py recordings
python3 timed_text_verify.py captions
python3 live_metering_verify.py metering
python3 energy_steering_verify.py steering
```

1022
wai/live-conformance/energy_steering_verify.py Normal file
View file

File diff suppressed because it is too large Load diff

82
wai/live-conformance/steering/README.md Normal file
View file

@ -0,0 +1,82 @@
# live-conformance/steering — energy-aware content steering
The corpus of [`extensions/energy-steering.md`](../../extensions/energy-steering.md) §11: a
room and its key log, steering policies (`WSP1`), the per-hop session records (`WMH1`,
[live-metering](../../extensions/live-metering.md) §3) of the pathways' hops, steering
requests with the report each gives, and vectors, each a steering decision (`WSD1`) with the
records and the manifest given with it, and the outcome a verifier gives it.
It sits beside [`metering/`](../metering/) because its evidence is live-metering's per-hop
records, read by that corpus's second implementation, `live_metering_verify.py`.
**Steering equivalence.** For each request, a conforming reader given the policy, the
protocol, the `target` and the `cmcd_header` reaches the `report` it states (§4). For each
vector, a conforming verifier given the room (`descriptor` and `key_log_head`), the vector's
`policy` (by name), its `decision`, the records it lists (by digest, from `records`) and its
`manifest` (or none, when `null`) reaches the outcome the vector states (§9.3):
- `refuse`: the `reason` and where, `at`: `["room"]`, `["policy"]`, `["decision"]`,
`["evidence", p, k]` for the record `k` named under pathway `p`, `["pathway", p]`,
`["output"]` or `["manifest"]`;
- `accept`: the decision's `digest`; the `priority` by pathway ID; the `ttl`; `why` the first
pathway is first; each pathway's `status`, `class`, `joules` and `delivery` (decimal
strings) and `limits` (the bits of §7.1); the `steering_manifest`; and the record's `uri`.
Every vector also states the decision's `inputs` as it reads (its instant, session, protocol,
report and loads), and a vector whose report came from a request states the `request`, which
gives that report. Each policy that reads states its `hls_tag` and `dash_element` (§8.2,
§8.3). A verifier that reaches another outcome, reason, place, fact or byte does not
conform.
**Provenance.** Generated here: `wai_energy_steering_vectors gen` writes `vectors.json` from
figures written in code, from fixed seeds: each key is SHA-256 of the corpus's fixed label and
the principal's index, each session SHA-256 of another fixed label and an index, every time is
a constant (the room's `t0` is 2026-10-16T00:00:00Z; the hops cut their records on a 10 s
period, and the decisions fall at 62 s and 72 s of room clock), and Ed25519 signing is
deterministic (RFC 8032), so the file is the same bytes on every machine. The per-hop records'
joule figures, bytes and subscriber time are synthetic constants, chosen to exercise the rule,
and were measured by nothing: the corpus computes which pathway the rule places first and
claims nothing about the energy any deployment spends or saves. The key-log head is sealed by
the reference's key log under a fixed root; the origin and the URIs are `.example` names (RFC
2606). The generator asserts that each vector reaches the outcome it was written to have
before it writes it.
## Layout
One file, `vectors.json`:
- `principals`: the keys, by name (informative).
- `room`: its `id`, `descriptor` (`WRD1`, hexadecimal) and `key_log_head` (a key-log revision,
JSON text), which lists the room authority, the steering key `live/steer` with every energy
authority, a revoked steering key, and each hop with `live/relay` and every energy
authority, one of them revoked. One hop key, `unlisted_edge`, is in no entry.
- `policies`: by name, each `policy` (hexadecimal) with its `hls_tag` and `dash_element`, or
`null` for a policy the rules refuse. `three` has three pathways (`edge-a`, `edge-b` and the
relay tree `tree`, each an edge hop and an interior hop); `explore` adds the unmetered
`origin` path with a 10% minimum share; `cloned` adds `edge-a2`, a clone of `edge-a`
through another host with its own edge hop; `latency` puts the tree past the latency
ceiling, `seconds` uses the per-second basis, `strict` has a ceiling no pathway meets;
`unlisted` and `revoked` give the tree an edge hop the key log does not list or has revoked;
`shares_over`, `clone_later` and `stranger_signed` are refused.
- `records`: every per-hop record a vector lists, by its digest. The hops sign them in four
worlds: every hop counter-metered; one class per pathway (calibrated, counter, estimate);
`edge-b`'s interior hop unmetered; `edge-a`'s hops of two classes.
- `requests`: steering requests over HLS and DASH, with CMCD in the query and in the
`CMCD-Request` header, and malformed values the reader leaves absent.
- `vectors`: accepted, three pathways with figures of one class, mixed classes, an unmetered
hop, hops of two classes, stale evidence, a client at its floor, a short buffer, hysteresis
holding and a period later moving a client, clones, a session placed by its band and one
outside it, capacity, latency, the per-second basis, DASH, and no pathway within the limits;
refused, each reason of §10 and the codes it reuses (`classes_summed`, `hop_not_authorised`,
`hop_revoked`, `record_missing`, `signer_not_authorised`, `signer_revoked`,
`bad_signature`), each a control of one defect.
## Regenerate and verify
```
cd wai/wai-rs
cargo run --no-default-features --features energy_steering --bin wai_energy_steering_vectors -- gen ../live-conformance/steering
cargo run --no-default-features --features energy_steering --bin wai_energy_steering_vectors -- verify ../live-conformance/steering
cargo test --no-default-features --features energy_steering --test energy_steering
python3 -I ../live-conformance/energy_steering_verify.py ../live-conformance/steering
```

2924
wai/live-conformance/steering/vectors.json Normal file
View file

File diff suppressed because it is too large Load diff

28
wai/registry/capabilities.json
View file

@ -672,6 +672,20 @@
"edition": null,
"registered": "2026-10-16"
},
{
"capability": "wai.live.steering",
"kind": "record",
"status": "registered",
"media": null,
"role": null,
"tier": null,
"licence": null,
"replicate": null,
"sets": [],
"spec_section": "§5 Interactive, temporal & computed content",
"edition": null,
"registered": "2026-10-18"
},
{
"capability": "wai.mesh.draco",
"kind": "payload",
@ -1955,6 +1969,13 @@
"section": "§10.5.1",
"status": "defined"
},
{
"name": "WSD1",
"kind": "magic",
"document": "extensions/energy-steering.md",
"section": "§7.1",
"status": "defined"
},
{
"name": "WSIX",
"kind": "magic",
@ -1962,6 +1983,13 @@
"section": "§6",
"status": "defined"
},
{
"name": "WSP1",
"kind": "magic",
"document": "extensions/energy-steering.md",
"section": "§3.1",
"status": "defined"
},
{
"name": "WTM1",
"kind": "magic",

7
wai/vocab/v2.ttl
View file

@ -569,6 +569,13 @@ wai:wai.live.room a wai:Capability ;
wai:specSection "§5 Interactive, temporal & computed content" ;
wai:registeredOn "2026-10-16"^^xsd:date .
wai:wai.live.steering a wai:Capability ;
rdfs:label "wai.live.steering" ;
wai:kind wai:kind-record ;
wai:status wai:status-registered ;
wai:specSection "§5 Interactive, temporal & computed content" ;
wai:registeredOn "2026-10-18"^^xsd:date .
wai:wai.mesh.draco a wai:Capability ;
rdfs:label "wai.mesh.draco" ;
wai:kind wai:kind-payload ;

19
wai/wai-rs/Cargo.toml
View file

@ -221,6 +221,15 @@ live_record = ["capture_take"]
# composition receipts through their modules and the logs through the telemetry module. SHA-256,
# Ed25519 and the key log only; no new dependency.
live_metering = ["live_compose", "capture_take", "telemetry"]
# Energy-aware content steering (extensions/energy-steering): `wai.live.steering` — the signed
# steering policy (WSP1) and steering decision (WSD1): each pathway's joules per delivered byte or
# per delivered second at the floor tier from its hops' per-hop records (live-metering's WMH1), with
# their acquisition class, compared only within a class, a pathway with no figure never ranked above
# one with a figure; the integer decision rule with limits, minimum shares and hysteresis; the client's
# report from HLS and DASH steering requests and CMCD (an RFC 9651 parser of its own); and the
# steering manifest, the HLS tag and the DASH element, written exactly. SHA-256, Ed25519 and the key
# log only; no new dependency.
energy_steering = ["live_metering"]
# Timed text and live captions (extensions/timed-text): `wai.text.timed` — the cue model,
# live caption revisions (`caption` events of wai.live.events with the WTX1 annotation),
# and their exact mappings onto WebVTT documents and segments, the IMSC1 Text Profile,
@ -685,6 +694,11 @@ name = "wai_live_metering_vectors"
path = "src/bin/wai_live_metering_vectors.rs"
required-features = ["live_metering"]
[[bin]]
name = "wai_energy_steering_vectors"
path = "src/bin/wai_energy_steering_vectors.rs"
required-features = ["energy_steering"]
[[bin]]
name = "wai_timed_text_vectors"
path = "src/bin/wai_timed_text_vectors.rs"
@ -1356,6 +1370,11 @@ name = "live_metering"
path = "tests/live_metering.rs"
required-features = ["live_metering"]
[[test]]
name = "energy_steering"
path = "tests/energy_steering.rs"
required-features = ["energy_steering"]
[[test]]
name = "timed_text"
path = "tests/timed_text.rs"

55
wai/wai-rs/src/bin/wai_energy_steering_vectors.rs Normal file
View file

@ -0,0 +1,55 @@
//! Conformance corpus for energy-aware content steering (`live-conformance/steering/`,
//! extensions/energy-steering.md §11).
//!
//! wai_energy_steering_vectors gen <corpus-dir> write vectors.json, from fixed seeds
//! wai_energy_steering_vectors verify <corpus-dir> vectors.json regenerates byte for byte,
//! and every request and vector gets the
//! outcome it states
//!
//! The generator and this verifier are one implementation. The corpus's second
//! implementation is `live-conformance/energy_steering_verify.py`, written from the
//! extension's text and sharing no code with this binary.
use std::path::Path;
use wai::energy_steering::corpus;
fn main() {
let a: Vec<String> = std::env::args().collect();
match (a.get(1).map(String::as_str), a.get(2)) {
(Some("gen"), Some(d)) => {
let p = Path::new(d).join("vectors.json");
if let Err(e) = std::fs::create_dir_all(d).and_then(|_| std::fs::write(&p, corpus::generate())) {
eprintln!("write {}: {e}", p.display());
std::process::exit(1);
}
println!("wrote {}", p.display());
}
(Some("verify"), Some(d)) => std::process::exit(verify(Path::new(d))),
_ => {
eprintln!("usage: wai_energy_steering_vectors gen|verify <corpus-dir>");
std::process::exit(2);
}
}
}
fn verify(dir: &Path) -> i32 {
let p = dir.join("vectors.json");
let doc = match std::fs::read_to_string(&p) {
Ok(s) => s,
Err(e) => {
eprintln!("read {}: {e}", p.display());
return 1;
}
};
let mut fail = 0;
let same = doc == corpus::generate();
println!("{} vectors.json regenerates byte for byte from its seeds", if same { "PASS" } else { "FAIL" });
fail += (!same) as i32;
let fails = corpus::verify(&doc);
for f in &fails {
println!("FAIL {f}");
}
println!("{} every request and vector gets the outcome the corpus states", if fails.is_empty() { "PASS" } else { "FAIL" });
fail += (!fails.is_empty()) as i32;
(fail != 0) as i32
}

7
wai/wai-rs/src/codecs/registry.rs
View file

@ -215,6 +215,7 @@ pub const CAP_CAPTURE_TAKE: &str = "wai.capture.take";
pub const CAP_LIVE_COMPOSE: &str = "wai.live.compose";
pub const CAP_LIVE_RECORDING: &str = "wai.live.recording";
pub const CAP_LIVE_METERING: &str = "wai.live.metering";
pub const CAP_LIVE_STEERING: &str = "wai.live.steering";
pub const CAP_TEXT_TIMED: &str = "wai.text.timed";
/// One row per string SPEC §5 registers that is a payload, companion or record:
@ -299,6 +300,7 @@ const ROWS: &[(&str, &str, Option<&str>, &str)] = &[
(CAP_LIVE_COMPOSE, S_INTERACTIVE, None, "2026-10-17"),
(CAP_LIVE_RECORDING, S_INTERACTIVE, None, "2026-10-17"),
(CAP_LIVE_METERING, S_INTERACTIVE, None, "2026-10-18"),
(CAP_LIVE_STEERING, S_INTERACTIVE, None, "2026-10-18"),
(CAP_TEXT_TIMED, S_INTERACTIVE, None, "2026-10-17"),
(CAP_AUDIO_IAMF, S_IMMERSIVE, None, "2026-06-17"),
(CAP_AUDIO_AC4, S_IMMERSIVE, None, "2026-06-17"),
@ -349,7 +351,7 @@ const RECORDS: &[&str] = &[
CAP_ASSET_PROVENANCE, CAP_QUANTUM_CALIBRATION, CAP_QUANTUM_JOB,
CAP_VIDEO_MANIFEST, CAP_VIDEO_SSAI, CAP_VIDEO_KEYS, CAP_VIDEO_PACKAGE, CAP_VIDEO_CHANNEL,
CAP_LIVE_EVENTS, CAP_LIVE_ROOM, CAP_CAPTURE_TAKE, CAP_LIVE_COMPOSE, CAP_LIVE_RECORDING,
CAP_LIVE_METERING, CAP_TEXT_TIMED,
CAP_LIVE_METERING, CAP_LIVE_STEERING, CAP_TEXT_TIMED,
];
/// A named identifier SPEC uses that has the shape of a capability string but is
@ -501,6 +503,7 @@ const LIVE_COMPOSE: &str = "extensions/live-compose.md";
const LIVE_RECORDING: &str = "extensions/live-recording.md";
const TIMED_TEXT: &str = "extensions/timed-text.md";
const LIVE_METERING: &str = "extensions/live-metering.md";
const ENERGY_STEERING: &str = "extensions/energy-steering.md";
const fn wire(name: &'static str, kind: WireKind, document: &'static str, section: &'static str,
status: WireStatus) -> WireIdentifier {
@ -584,6 +587,8 @@ pub const WIRE_IDENTIFIERS: &[WireIdentifier] = &[
wire("science.transaction.wai.timed-text", WireKind::DataId, TIMED_TEXT, "§10.5", WireStatus::Defined),
wire("WMH1", WireKind::Magic, LIVE_METERING, "§3.1", WireStatus::Defined),
wire("WMR1", WireKind::Magic, LIVE_METERING, "§4.1", WireStatus::Defined),
wire("WSP1", WireKind::Magic, ENERGY_STEERING, "§3.1", WireStatus::Defined),
wire("WSD1", WireKind::Magic, ENERGY_STEERING, "§7.1", WireStatus::Defined),
];
/// A string with the shape of a capability that the reference implementation uses

1771
wai/wai-rs/src/energy_steering.rs Normal file
View file

File diff suppressed because it is too large Load diff

837
wai/wai-rs/src/energy_steering/corpus.rs Normal file
View file

@ -0,0 +1,837 @@
//! The conformance corpus of extensions/energy-steering.md §11: `live-conformance/steering/vectors.json`.
//!
//! [`generate`] writes it from fixed seeds: every key is SHA-256 of this corpus's label and an
//! index, every session SHA-256 of another label and an index, every time a constant, and
//! Ed25519 signing is deterministic (RFC 8032). The pathways' hops sign their per-hop records
//! (live-metering §3) in **worlds**: one world is one set of figures the hops could have
//! signed, and a vector reads the records of its world. The figures are synthetic, chosen to
//! exercise the rule, and claim nothing about any deployment. Each vector states the outcome
//! it was written to have, and the generator asserts that this module reaches it.
//!
//! [`verify`] checks a corpus file against this module. `live-conformance/energy_steering_verify.py`
//! checks the same file from the extension's text, sharing no code with this module.
use std::collections::BTreeMap;
use super::*;
use crate::energy_class::{CounterFiltering, EnergyProvenance, Uncertainty};
use crate::key_log::{commitment, KeyEntry};
use crate::live_events::Policy as EventPolicy;
use crate::live_metering::{dir, kind, TrackEntry, CLASSES};
use crate::live_room::{registered_profile, Caps, Limits, Owner, Recording, Review, Role};
use serde_json::{json, Map, Value};
const S: u64 = 1_000_000;
/// The period the hops cut their records on, and the window.
const PERIOD: u64 = 10 * S;
const WINDOW: u64 = 30 * S;
const LAG: u64 = 2 * S;
/// The room's `t0`: 2026-10-16T00:00:00Z, as the live corpora's.
const T0_US: u64 = 1_792_108_800_000_000;
const ORIGIN: &str = "https://stream.example";
/// The decisions' instants: a window of [30 s, 60 s), and a period later [40 s, 70 s).
const T1: u64 = 62 * S;
const T2: u64 = 72 * S;
const AUTHORITY: u8 = 0;
const CLOCK: u8 = 1;
const STEER: u8 = 2;
const STEER_REVOKED: u8 = 3;
const STRANGER: u8 = 4;
const LOG_ROOT: u8 = 5;
const LOG_NEXT: u8 = 6;
const PUBLISHER: u8 = 7;
const A_EDGE: u8 = 10;
const A_CORE: u8 = 11;
const B_EDGE: u8 = 12;
const B_CORE: u8 = 13;
const C_EDGE: u8 = 14;
const C_CORE: u8 = 15;
const D_EDGE: u8 = 16;
const A2_EDGE: u8 = 17;
const UNLISTED_EDGE: u8 = 18;
const REVOKED_EDGE: u8 = 19;
const PRINCIPALS: [(&str, u8); 18] = [
("authority", AUTHORITY),
("clock", CLOCK),
("steer", STEER),
("steer_revoked", STEER_REVOKED),
("stranger", STRANGER),
("log_root", LOG_ROOT),
("log_next", LOG_NEXT),
("publisher", PUBLISHER),
("a_edge", A_EDGE),
("a_core", A_CORE),
("b_edge", B_EDGE),
("b_core", B_CORE),
("c_edge", C_EDGE),
("c_core", C_CORE),
("d_edge", D_EDGE),
("a2_edge", A2_EDGE),
("unlisted_edge", UNLISTED_EDGE),
("revoked_edge", REVOKED_EDGE),
];
const SERVER_URI: &str = "https://steer.stream.example/v1/room?asset=lesson&tk=a1";
const RELOAD_URI: &str = "https://steer.stream.example/v1/room?asset=lesson";
const DECISION_URI: &str = "https://steer.stream.example/v1/decisions/";
fn key(i: u8) -> SigningKey {
SigningKey::from_bytes(&sha256(&[b"wai:energy-steering/corpus/key\x00", &[i]]))
}
fn pk(i: u8) -> [u8; 32] {
key(i).verifying_key().to_bytes()
}
fn who(k: &[u8; 32]) -> u8 {
PRINCIPALS.iter().find(|(_, i)| pk(*i) == *k).map(|(_, i)| *i).expect("a principal of the corpus")
}
/// Session `i` of the corpus.
fn session(i: u32) -> [u8; 16] {
sha256(&[b"wai:energy-steering/corpus/session\x00", &i.to_le_bytes()])[..16].try_into().expect("16 bytes")
}
fn unhex(s: &str) -> Option<Vec<u8>> {
if !s.len().is_multiple_of(2) {
return None;
}
(0..s.len()).step_by(2).map(|i| u8::from_str_radix(s.get(i..i + 2)?, 16).ok()).collect()
}
// ---- the room ----
fn bits(ks: &[u8]) -> [u8; 32] {
let mut b = [0u8; 32];
for &k in ks {
b[(k / 8) as usize] |= 1 << (k % 8);
}
b
}
fn descriptor() -> Descriptor {
use events::kind::{CHAT, REACTION};
let role = |name: &str, publish: u8, max_layer: u8| Role { name: name.into(), caps: Caps { publish, subscribe: true, max_layer, powers: 0 }, events: bits(&[CHAT, REACTION]) };
Descriptor {
authority: pk(AUTHORITY),
clock: pk(CLOCK),
t0_us: T0_US,
tick_us: S,
origin: ORIGIN.into(),
limits: Limits { max_present: 8, max_publishers: 2, reval_s: 0, ceiling: EventPolicy::default() },
roles: vec![role("publisher", 1 | 2, 2), role("audience", 0, 1)],
slots: vec![],
profiles: vec![registered_profile("camera-720").expect("registered")],
review: Review { kinds: [0; 32], deadline_ms: 0, fallback: 0 },
recording: Recording { mode: 0, retention_days: 0, commit_interval_ms: 0, jitter_ms: 0, regions: vec![] },
sig: [0; 64],
}
.sign(&key(AUTHORITY))
}
const ENERGY: [&str; 4] = ["energy/CalibratedInstrument", "energy/OnChipCounter", "energy/ModelBased", "energy/Estimator"];
fn key_log() -> String {
let with = |base: &'static str| -> Vec<&'static str> { std::iter::once(base).chain(ENERGY).collect() };
let revoked = |id: &str, k: u8, may: &[&str]| KeyEntry { status: EntryStatus::Revoked, compromised_since: Some("2026-10-14T00:00:00Z".into()), ..KeyEntry::active(id, pk(k), may) };
let mut keys = vec![
KeyEntry::active("room-authority", pk(AUTHORITY), &[room::KEY_LOG_AUTHORITY]),
KeyEntry::active("steering", pk(STEER), &with(STEER_AUTHORITY)),
revoked("steering-old", STEER_REVOKED, &with(STEER_AUTHORITY)),
];
for (id, k) in [("a-edge", A_EDGE), ("a-core", A_CORE), ("b-edge", B_EDGE), ("b-core", B_CORE), ("c-edge", C_EDGE), ("c-core", C_CORE), ("d-edge", D_EDGE), ("a2-edge", A2_EDGE)] {
keys.push(KeyEntry::active(id, pk(k), &with("live/relay")));
}
keys.push(revoked("c-edge-old", REVOKED_EDGE, &with("live/relay")));
let revision = Revision {
origin: ORIGIN.into(),
seq: 0,
prev: None,
issued_at: "2026-10-15T00:00:00Z".into(),
root: [0; 32],
next_root: commitment(&pk(LOG_NEXT)),
keys,
revoked_modules: vec![],
grant_max_s: 86_400,
status_max_age_s: 3_600,
sig: [0; 64],
};
Revision::seal(&key(LOG_ROOT), revision).expect("a well-formed revision").to_json()
}
// ---- the records ----
/// How a hop's figure was acquired in a world.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Meter {
Calibrated,
OnChip,
Model,
Estimate,
Off,
}
fn class_of(m: Meter) -> Option<EnergyProvenance> {
let u = |ppm| Uncertainty::new(ppm, PERIOD).expect("a declaration");
match m {
Meter::Calibrated => Some(EnergyProvenance::calibrated_instrument(u(5_000), "cal-2026-0042").expect("a class")),
Meter::OnChip => Some(EnergyProvenance::on_chip_counter(u(20_000), CounterFiltering::Off).expect("a class")),
Meter::Model => Some(EnergyProvenance::ModelBased),
Meter::Estimate => Some(EnergyProvenance::Estimator),
Meter::Off => None,
}
}
/// The worlds the corpus's hops sign records in.
#[derive(Clone, Copy, PartialEq, Eq)]
enum World {
/// Every hop counter-metered.
Base,
/// `edge-a` by calibrated instrument, `edge-b` by counter, `tree` by estimate.
Classes,
/// `edge-b`'s interior hop unmetered.
Unmetered,
/// `edge-a`'s interior hop by model, its edge by counter.
MixedHops,
}
/// A hop's figure for one period in a world: joules, how acquired, media bytes out, and its
/// subscriber sessions by layer class.
struct Figure {
joules_j: u64,
meter: Meter,
bytes_out: u64,
sessions: &'static [(usize, u64)],
}
fn figure(world: World, hop: u8, k: u64) -> Figure {
let f = |joules_j, meter, bytes_out, sessions| Figure { joules_j, meter, bytes_out, sessions };
let base = match hop {
A_EDGE => f(400, Meter::OnChip, 200_000_000, &[(2, 10), (3, 30)][..]),
A_CORE => f(300, Meter::OnChip, 10_000_000, &[][..]),
B_EDGE => f(500, Meter::OnChip, 200_000_000, &[(2, 40)][..]),
B_CORE => f(300, Meter::OnChip, 10_000_000, &[][..]),
C_EDGE | UNLISTED_EDGE | REVOKED_EDGE => f(300, Meter::OnChip, 250_000_000, &[(0, 30), (2, 30)][..]),
// The relay tree's interior hop spends less in the period from 60 s.
C_CORE => f(if k == 6 { 150 } else { 450 }, Meter::OnChip, 10_000_000, &[][..]),
D_EDGE => f(0, Meter::Off, 50_000_000, &[(1, 10)][..]),
A2_EDGE => f(350, Meter::OnChip, 250_000_000, &[(3, 50)][..]),
_ => unreachable!("a hop of the corpus"),
};
match (world, hop) {
(World::Classes, A_EDGE | A_CORE) => Figure { meter: Meter::Calibrated, ..base },
(World::Classes, C_EDGE | C_CORE) => Figure { joules_j: 200, meter: Meter::Estimate, ..base },
(World::Unmetered, B_CORE) => Figure { joules_j: 0, meter: Meter::Off, ..base },
(World::MixedHops, A_CORE) => Figure { meter: Meter::Model, ..base },
_ => base,
}
}
/// The record `hop` signs for period `k` in `world`.
fn record(room_id: &[u8; 32], world: World, hop: u8, k: u64) -> HopRecord {
let fig = figure(world, hop, k);
let track = crate::live_metering::corpus::track(room_id, &Owner::Principal(pk(PUBLISHER)), "video", 2);
let bytes_in = 5_000_000;
let mut subscriber_us = [0u64; CLASSES];
let mut sessions = 0u32;
for &(c, n) in fig.sessions {
subscriber_us[c] += n * PERIOD;
sessions += n as u32;
}
let class = class_of(fig.meter);
HopRecord {
room: *room_id,
hop: pk(hop),
role: metering::role::RELAY,
start: k * PERIOD,
end: (k + 1) * PERIOD,
joules: if class.is_some() { fig.joules_j * S } else { 0 },
class,
tracks: vec![
TrackEntry { kind: kind::MEDIA, track, dir: dir::IN, objects: bytes_in / 1250, bytes: bytes_in, ..TrackEntry::default() },
TrackEntry { kind: kind::MEDIA, track, dir: dir::OUT, objects: fig.bytes_out / 1250, bytes: fig.bytes_out, ..TrackEntry::default() },
],
sessions,
subscriber_us,
events: 0,
grants: 0,
ledger: [0; 32],
sig: [0; 64],
}
.sign(&key(hop))
}
/// The records a server read for each pathway at `t` in `world`: each hop's records of the
/// window's periods, in the order of §5.2, leaving out the `(hop, period)` pairs of `skip`.
fn named(p: &Policy, world: World, t: u64, skip: &[(u8, u64)]) -> Vec<Vec<HopRecord>> {
let (a, b) = window(p, t);
p.pathways
.iter()
.map(|x| {
let mut out = Vec::new();
for (h, _) in &x.hops {
let hop = who(h);
for k in a / PERIOD..b / PERIOD {
if !skip.contains(&(hop, k)) {
out.push(record(&p.room, world, hop, k));
}
}
}
out
})
.collect()
}
// ---- the policies ----
fn pathway(id: &str, hops: &[(u8, u8)], top_tier: u8, latency_ms: u32, capacity: u32, min_share_ppm: u32) -> Pathway {
Pathway {
id: id.into(),
base: NOT_CLONE,
host: String::new(),
params: vec![],
top_tier,
latency_ms,
capacity,
min_share_ppm,
hops: hops.iter().map(|&(k, pl)| (pk(k), pl)).collect(),
}
}
fn edge_a() -> Pathway {
pathway("edge-a", &[(A_EDGE, place::EDGE), (A_CORE, place::INTERIOR)], 3, 400, NO_CAPACITY, 0)
}
fn edge_b() -> Pathway {
pathway("edge-b", &[(B_EDGE, place::EDGE), (B_CORE, place::INTERIOR)], 3, 450, NO_CAPACITY, 0)
}
fn tree(edge: u8) -> Pathway {
pathway("tree", &[(edge, place::EDGE), (C_CORE, place::INTERIOR)], 3, 500, 1_000, 0)
}
fn base_policy(room_id: [u8; 32], pathways: Vec<Pathway>) -> Policy {
Policy {
room: room_id,
signer: [0; 32],
period_us: PERIOD,
window_us: WINDOW,
lag_us: LAG,
basis: basis::BYTES,
floor: 1,
latency_ceiling_ms: 600,
min_buffer_ms: 4_000,
hysteresis_ppm: 200_000,
ttl_s: 300,
min_ttl_s: 30,
flags: 1,
initial: 0,
tiers: vec![800_000, 1_600_000, 3_200_000, 6_400_000],
server_uri: SERVER_URI.into(),
reload_uri: RELOAD_URI.into(),
decision_uri: DECISION_URI.into(),
pathways,
sig: [0; 64],
}
}
/// The corpus's policies, by name, as signed bytes. A policy that the rules refuse is signed
/// all the same: §9.1 reads a policy before it checks its signature.
fn policies(room_id: [u8; 32]) -> Vec<(&'static str, Vec<u8>)> {
let three = || vec![edge_a(), edge_b(), tree(C_EDGE)];
let origin = pathway("origin", &[(D_EDGE, place::EDGE)], 1, 300, NO_CAPACITY, 100_000);
let clone = Pathway {
base: 0,
host: "a2.edge.stream.example".into(),
params: vec![("pop".into(), "east-2".into()), ("tk".into(), "x%2Fy".into())],
..pathway("edge-a2", &[(A2_EDGE, place::EDGE)], 3, 400, NO_CAPACITY, 0)
};
let signed = |p: Policy| p.sign(&key(STEER)).to_bytes();
let mut latency = three();
latency[2].latency_ms = 900;
let mut over = three();
over[0].min_share_ppm = 600_000;
over[1].min_share_ppm = 500_000;
let mut later = vec![edge_a(), edge_b(), tree(C_EDGE), clone.clone()];
later[3].base = 3;
vec![
("three", signed(base_policy(room_id, three()))),
("explore", signed(base_policy(room_id, vec![edge_a(), edge_b(), tree(C_EDGE), origin]))),
("cloned", signed(base_policy(room_id, vec![edge_a(), edge_b(), tree(C_EDGE), clone]))),
("latency", signed(base_policy(room_id, latency))),
("seconds", signed(Policy { basis: basis::SECONDS, ..base_policy(room_id, three()) })),
("strict", signed(Policy { latency_ceiling_ms: 100, ..base_policy(room_id, three()) })),
("unlisted", signed(base_policy(room_id, vec![edge_a(), edge_b(), tree(UNLISTED_EDGE)]))),
("revoked", signed(base_policy(room_id, vec![edge_a(), edge_b(), tree(REVOKED_EDGE)]))),
("shares_over", signed(base_policy(room_id, over))),
("clone_later", signed(base_policy(room_id, later))),
("stranger_signed", base_policy(room_id, three()).sign(&key(STRANGER)).to_bytes()),
]
}
// ---- the requests ----
/// The steering requests of §11, by protocol, target and `CMCD-Request` header.
const REQUESTS: [(&str, u8, &str, Option<&str>); 27] = [
("hls_quoted", protocol::HLS, "/v1/room?asset=lesson&_HLS_pathway=%22edge-a%22&_HLS_throughput=4000000", None),
("hls_unquoted", protocol::HLS, "/v1/room?_HLS_pathway=edge-b&_HLS_throughput=123", None),
("hls_literal_quotes", protocol::HLS, "/v1/room?_HLS_pathway=\"tree\"", None),
("hls_unknown_pathway", protocol::HLS, "/v1/room?_HLS_pathway=%22cdn-z%22&_HLS_throughput=5000000", None),
("hls_throughput_not_integer", protocol::HLS, "/v1/room?_HLS_pathway=edge-a&_HLS_throughput=4e6", None),
("hls_throughput_past_u64", protocol::HLS, "/v1/room?_HLS_throughput=18446744073709551616", None),
("hls_throughput_u64_max", protocol::HLS, "/v1/room?_HLS_throughput=18446744073709551615", None),
("hls_first_part_wins", protocol::HLS, "/v1/room?_HLS_pathway=tree&_HLS_pathway=edge-a", None),
("hls_bad_percent_skipped", protocol::HLS, "/v1/room?_HLS_pathway=%2&_HLS_throughput=500", None),
("hls_fragment_cut", protocol::HLS, "/v1/room?_HLS_throughput=9#_HLS_pathway=edge-a", None),
("hls_no_query", protocol::HLS, "/v1/room", None),
("hls_dash_parameters_ignored", protocol::HLS, "/v1/room?_DASH_pathway=edge-a&_DASH_throughput=7", None),
("hls_cmcd_v2_lists", protocol::HLS, "/v1/room?_HLS_pathway=%22tree%22&CMCD=bl%3D%2821300%3Bv%2013000%3Ba%29%2Cmtp%3D%2848000%3Bv%29%2Csid%3D%22abc%22", None),
("hls_cmcd_v1_integers", protocol::HLS, "/v1/room?CMCD=bl%3D4100%2Cmtp%3D25400", None),
("hls_cmcd_throughput_parameter_first", protocol::HLS, "/v1/room?_HLS_throughput=3000000&CMCD=mtp%3D25400%2Cbl%3D900", None),
("hls_cmcd_header", protocol::HLS, "/v1/room?_HLS_pathway=edge-a", Some("bl=(8000;v),br=(3200;v),mtp=(12000;v)")),
("hls_cmcd_query_over_header", protocol::HLS, "/v1/room?CMCD=bl%3D700", Some("bl=(8000;v),mtp=(12000;v)")),
("hls_cmcd_unterminated", protocol::HLS, "/v1/room?CMCD=bl%3D%281200", None),
("hls_cmcd_trailing_comma", protocol::HLS, "/v1/room?CMCD=bl%3D300%2C", None),
("hls_cmcd_negative", protocol::HLS, "/v1/room?CMCD=bl%3D-5%2Cmtp%3D(-1)", None),
("hls_cmcd_decimal_in_list", protocol::HLS, "/v1/room?CMCD=bl%3D%281.5%3Bv%29", None),
("hls_cmcd_display_string_and_date", protocol::HLS, "/v1/room?CMCD=bl%3D300%2Cx%3D%25%22caf%25c3%25a9%22%2Cy%3D%401700000000%2Cz%3D%3AAQID%3A", None),
("hls_cmcd_bytes_not_base64", protocol::HLS, "/v1/room?CMCD=bl%3D300%2Cz%3D%3AA%3A", None),
("dash_list_second_known", protocol::DASH, "/v1/room?_DASH_pathway=%22cdn-z,edge-b%22&_DASH_throughput=1000,2000", None),
("dash_unquoted_single", protocol::DASH, "/v1/room?steeringToken=12345&_DASH_pathway=tree&_DASH_throughput=5140000", None),
("dash_throughput_list_short", protocol::DASH, "/v1/room?_DASH_pathway=%22cdn-z,edge-b%22&_DASH_throughput=1000", None),
("dash_no_pathway_first_throughput", protocol::DASH, "/v1/room?_DASH_throughput=777,888&_HLS_pathway=edge-a", None),
];
fn report_json(p: &Policy, r: &Report) -> Value {
json!({
"pathway": r.pathway().map(|i| Value::from(p.pathways[i].id.clone())).unwrap_or(Value::Null),
"throughput": r.throughput().map(Value::from).unwrap_or(Value::Null),
"buffer": r.buffer().map(Value::from).unwrap_or(Value::Null),
})
}
fn protocol_label(x: u8) -> &'static str {
if x == protocol::HLS { "hls" } else { "dash" }
}
// ---- the vectors ----
enum Intent {
Accept(u8),
Refuse(&'static str),
}
struct Vector {
name: &'static str,
about: &'static str,
policy: &'static str,
decision: Vec<u8>,
/// The digests of the records the verifier is given.
records: Vec<[u8; 32]>,
manifest: Option<String>,
request: Option<(u8, String, Option<String>)>,
intent: Intent,
}
struct Builder {
room_id: [u8; 32],
policies: Vec<(&'static str, Vec<u8>)>,
pool: BTreeMap<[u8; 32], Vec<u8>>,
}
impl Builder {
fn policy(&self, name: &str) -> Policy {
let b = &self.policies.iter().find(|(n, _)| *n == name).expect("a policy").1;
Policy::read(b).expect("a policy that reads")
}
fn add(&mut self, named: &[Vec<HopRecord>]) -> Vec<[u8; 32]> {
let mut out = Vec::new();
for r in named.iter().flatten() {
self.pool.insert(r.digest(), r.to_bytes());
out.push(r.digest());
}
out
}
/// A decision the reference steering server signs, with the records it names.
#[allow(clippy::too_many_arguments)]
fn decide(&mut self, policy: &str, world: World, t: u64, sess: u32, proto: u8, report: Report, loads: &[u32], skip: &[(u8, u64)]) -> (Decision, Vec<[u8; 32]>, Vec<Vec<HopRecord>>) {
let p = self.policy(policy);
let named = named(&p, world, t, skip);
let given = self.add(&named);
(steer(&p, t, session(sess), proto, report, loads, &named, &key(STEER)), given, named)
}
}
const LOADS: [u32; 4] = [120, 80, 300, 40];
#[allow(clippy::too_many_arguments)]
fn accept(name: &'static str, about: &'static str, policy: &'static str, d: &Decision, records: Vec<[u8; 32]>, b: &Builder, request: Option<(u8, String, Option<String>)>, why_: u8) -> Vector {
let m = manifest(&b.policy(policy), d);
Vector { name, about, policy, decision: d.to_bytes(), records, manifest: Some(m), request, intent: Intent::Accept(why_) }
}
fn refused(name: &'static str, about: &'static str, policy: &'static str, decision: Vec<u8>, records: Vec<[u8; 32]>, manifest: Option<String>, code: &'static str) -> Vector {
Vector { name, about, policy, decision, records, manifest, request: None, intent: Intent::Refuse(code) }
}
fn resign(d: Decision, who_: u8) -> Vec<u8> {
d.sign(&key(who_)).to_bytes()
}
fn vectors(b: &mut Builder) -> Vec<Vector> {
let mut v = Vec::new();
let none = Report::default();
let three = b.policy("three");
let req = |proto: u8, target: &str, header: Option<&str>| (proto, target.to_string(), header.map(String::from));
let read = |p: &Policy, r: &(u8, String, Option<String>)| read_request(r.0, r.1.as_bytes(), r.2.as_deref().map(str::as_bytes), p);
// ---- accepted ----
let (d3, g3, n3) = b.decide("three", World::Base, T1, 0, protocol::HLS, none, &LOADS[..3], &[]);
v.push(accept("three_metered", "three pathways counter-metered: the relay tree's figure is the lowest, and it is first", "three", &d3, g3.clone(), b, None, why::RANK));
let (d, g, _) = b.decide("three", World::Classes, T1, 0, protocol::HLS, none, &LOADS[..3], &[]);
v.push(accept("mixed_classes", "one class per pathway, three classes: ordered by what backs each figure, the calibrated pathway first and the estimated one last though its figure is the lowest", "three", &d, g, b, None, why::RANK));
let (du, gu, nu) = b.decide("three", World::Unmetered, T1, 0, protocol::HLS, none, &LOADS[..3], &[]);
v.push(accept("one_unmetered", "edge-b's interior hop is unmetered: edge-b has no figure and comes last, though its metered hop alone is the cheapest of all", "three", &du, gu.clone(), b, None, why::RANK));
let (dm, gm, nm) = b.decide("three", World::MixedHops, T1, 0, protocol::HLS, none, &LOADS[..3], &[]);
v.push(accept("mixed_hops", "edge-a's hops are of two classes: edge-a has no figure and comes after both pathways with one", "three", &dm, gm.clone(), b, None, why::RANK));
let (ds, gs, _) = b.decide("three", World::Base, T1, 0, protocol::HLS, none, &LOADS[..3], &[(C_CORE, 5)]);
v.push(accept("stale", "the relay tree's interior hop has no record of its last period: its evidence is stale, and the cheapest pathway of three_metered comes last", "three", &ds, gs.clone(), b, None, why::RANK));
let r = req(protocol::HLS, "/v1/room?asset=lesson&_HLS_pathway=%22edge-b%22&_HLS_throughput=1500000", None);
let (d, g, _) = b.decide("three", World::Base, T1, 0, protocol::HLS, read(&three, &r), &LOADS[..3], &[]);
v.push(accept("floor_client", "a client on edge-b whose throughput sustains only tier 0, at or below the floor: held on edge-b, with the short TTL", "three", &d, g, b, Some(r), why::FLOOR));
let r = req(protocol::HLS, "/v1/room?_HLS_pathway=%22edge-b%22&_HLS_throughput=8000000&CMCD=bl%3D%281200%3Bv%201800%3Ba%29", None);
let (d, g, _) = b.decide("three", World::Base, T1, 0, protocol::HLS, read(&three, &r), &LOADS[..3], &[]);
v.push(accept("buffer_guard", "a client on edge-b with 1.2 s of video buffered, below the policy's 4 s: held", "three", &d, g, b, Some(r), why::BUFFER));
let r = req(protocol::HLS, "/v1/room?_HLS_pathway=%22edge-a%22&_HLS_throughput=8000000&CMCD=bl%3D20000", None);
let (d, g, _) = b.decide("three", World::Base, T1, 0, protocol::HLS, read(&three, &r), &LOADS[..3], &[]);
v.push(accept("hysteresis_hold", "a client on edge-a: the relay tree's figure is lower by less than the 20% margin, so the client stays", "three", &d, g, b, Some(r.clone()), why::HOLD));
let (d, g, _) = b.decide("three", World::Base, T2, 0, protocol::HLS, read(&three, &r), &LOADS[..3], &[]);
v.push(accept("hysteresis_switch", "the same client a period later: the relay tree's newest period brings its figure below edge-a's by more than the margin, and the client moves", "three", &d, g, b, Some(r), why::RANK));
let (dc, gc, _) = b.decide("cloned", World::Base, T1, 0, protocol::HLS, none, &LOADS, &[]);
v.push(accept("clones", "a clone of edge-a through another host, with its own edge hop: first, and every clone written in PATHWAY-CLONES", "cloned", &dc, gc.clone(), b, None, why::RANK));
let explore = b.policy("explore");
let digest = explore.digest();
let inside = (0u32..).find(|&i| draw(&digest, &session(i)) < 100_000).expect("a session in the band");
let outside = (0u32..).find(|&i| draw(&digest, &session(i)) >= 100_000).expect("a session outside the band");
let (d, g, _) = b.decide("explore", World::Base, T1, inside, protocol::HLS, none, &LOADS, &[]);
v.push(accept("share", "the origin path is unmetered and holds a 10% minimum share: a session whose draw is in its band is placed on it first", "explore", &d, g, b, None, why::SHARE));
let (d, g, _) = b.decide("explore", World::Base, T1, outside, protocol::HLS, none, &LOADS, &[]);
v.push(accept("share_outside", "a session whose draw is outside the origin path's band: the origin path has no figure and comes last", "explore", &d, g, b, None, why::RANK));
let (d, g, _) = b.decide("three", World::Base, T1, 0, protocol::HLS, none, &[120, 80, 1_000], &[]);
v.push(accept("capacity", "the relay tree is at its capacity of 1000 sessions: edge-a is first and the relay tree last", "three", &d, g, b, None, why::RANK));
let (d, g, _) = b.decide("latency", World::Base, T1, 0, protocol::HLS, none, &LOADS[..3], &[]);
v.push(accept("latency", "the relay tree's latency is past the ceiling: it comes after the pathways within the limits", "latency", &d, g, b, None, why::RANK));
let (d, g, _) = b.decide("seconds", World::Base, T1, 0, protocol::HLS, none, &LOADS[..3], &[]);
v.push(accept("per_second", "the per-second basis: the relay tree delivers the most bytes but half its sessions below the floor tier, and comes last", "seconds", &d, g, b, None, why::RANK));
let r = req(protocol::DASH, "/v1/room?asset=lesson&wai_session=00&_DASH_pathway=%22edge-b,edge-a%22&_DASH_throughput=9000000,7000000", Some("bl=(25000;v 30000;a)"));
let (d, g, _) = b.decide("three", World::Base, T1, 1, protocol::DASH, read(&three, &r), &LOADS[..3], &[]);
v.push(accept("dash", "DASH: the client used edge-b then edge-a; edge-b is current, and the relay tree beats it by more than the margin", "three", &d, g, b, Some(r), why::RANK));
let r = req(protocol::HLS, "/v1/room?_HLS_pathway=edge-a&_HLS_throughput=8000000", None);
let strict = b.policy("strict");
let (d, g, _) = b.decide("strict", World::Base, T1, 0, protocol::HLS, read(&strict, &r), &LOADS[..3], &[]);
v.push(accept("none_within", "a latency ceiling no pathway meets: the client stays on edge-a, with the short TTL", "strict", &d, g, b, Some(r), why::NONE));
// ---- refused ----
let m3 = manifest(&three, &d3);
v.push(refused("policy_invalid", "the policy's minimum shares sum past one million", "shares_over", d3.to_bytes(), g3.clone(), None, "policy_invalid"));
v.push(refused("clone_unknown", "a clone whose base is itself, a pathway not before it", "clone_later", d3.to_bytes(), g3.clone(), None, "clone_unknown"));
v.push(refused("policy_signer_not_authorised", "a policy signed by a key the key log does not list", "stranger_signed", d3.to_bytes(), g3.clone(), None, "signer_not_authorised"));
v.push(refused("decision_policy_missing", "a decision under another policy than the one given", "latency", d3.to_bytes(), g3.clone(), None, "record_missing"));
let mut sig = d3.to_bytes();
let last = sig.len() - 1;
sig[last] ^= 0x01;
v.push(refused("decision_bad_signature", "the decision's signature with one bit flipped", "three", sig, g3.clone(), None, "bad_signature"));
v.push(refused("decision_signer_not_authorised", "a decision signed by a key the key log does not list", "three", resign(d3.clone(), STRANGER), g3.clone(), None, "signer_not_authorised"));
v.push(refused("decision_signer_revoked", "a decision signed by a revoked steering key", "three", resign(d3.clone(), STEER_REVOKED), g3.clone(), None, "signer_revoked"));
let mut x = d3.clone();
x.priority = vec![2, 2, 0];
v.push(refused("decision_invalid", "a priority that names a pathway twice", "three", resign(x, STEER), g3.clone(), None, "decision_invalid"));
let mut x = d3.clone();
x.pathways[0].evidence.reverse();
v.push(refused("evidence_out_of_order", "edge-a's records named in reverse order", "three", resign(x, STEER), g3.clone(), None, "decision_invalid"));
let missing = n3[2][4].digest();
v.push(refused("record_missing", "a record the decision names is not given", "three", d3.to_bytes(), g3.iter().copied().filter(|g| *g != missing).collect(), None, "record_missing"));
let (d, g, _) = b.decide("unlisted", World::Base, T1, 0, protocol::HLS, none, &LOADS[..3], &[]);
v.push(refused("hop_not_authorised", "evidence signed by a hop key the key log does not list", "unlisted", d.to_bytes(), g, None, "hop_not_authorised"));
let (d, g, _) = b.decide("revoked", World::Base, T1, 0, protocol::HLS, none, &LOADS[..3], &[]);
v.push(refused("hop_revoked", "evidence signed by a hop key the key log revoked", "revoked", d.to_bytes(), g, None, "hop_revoked"));
let mut x = d3.clone();
let moved = x.pathways[1].evidence.remove(0);
x.pathways[0].evidence.push(moved);
v.push(refused("evidence_not_on_pathway", "edge-b's edge record named under edge-a", "three", resign(x, STEER), g3.clone(), None, "evidence_not_on_pathway"));
let p3 = three.clone();
let late = record(&p3.room, World::Base, A_EDGE, 6);
b.pool.insert(late.digest(), late.to_bytes());
let mut x = d3.clone();
x.pathways[0].evidence.insert(3, late.digest());
let mut gl = g3.clone();
gl.push(late.digest());
v.push(refused("evidence_outside_window", "a record of the period from 60 s named at 62 s, whose window ends at 60 s", "three", resign(x, STEER), gl, None, "evidence_outside_window"));
let mut x = d3.clone();
x.pathways[2].delivery += 1;
v.push(refused("evidence_mismatch", "the relay tree's delivery stated one byte more than its records give", "three", resign(x, STEER), g3.clone(), None, "evidence_mismatch"));
let mut x = du.clone();
let metered: u128 = nu[1].iter().map(|r| r.joules as u128).sum();
let delivered: u128 = nu[1].iter().filter(|r| r.hop == pk(B_EDGE)).flat_map(|r| &r.tracks).filter(|e| e.dir == dir::OUT).map(|e| e.bytes as u128).sum();
x.pathways[1] = PathwayState { status: status::FIGURE, class: 4, joules: metered, delivery: delivered, ..x.pathways[1].clone() };
v.push(refused("unmetered_as_zero", "edge-b stated with a figure that counts its unmetered hop as zero joules", "three", resign(x, STEER), gu, None, "unmetered_as_zero"));
let mut x = dm.clone();
let all: u128 = nm[0].iter().map(|r| r.joules as u128).sum();
let delivered: u128 = nm[0].iter().filter(|r| r.hop == pk(A_EDGE)).flat_map(|r| &r.tracks).filter(|e| e.dir == dir::OUT).map(|e| e.bytes as u128).sum();
x.pathways[0] = PathwayState { status: status::FIGURE, class: 4, joules: all, delivery: delivered, ..x.pathways[0].clone() };
v.push(refused("classes_summed", "edge-a stated with one figure that sums a counter reading and a model's output", "three", resign(x, STEER), gm, None, "classes_summed"));
let mut x = ds.clone();
x.priority = vec![2, 0, 1];
v.push(refused("unknown_preferred", "the stale relay tree placed first", "three", resign(x, STEER), gs, None, "unknown_preferred"));
let mut x = d3.clone();
x.priority = vec![2, 1, 0];
v.push(refused("decision_mismatch", "the second and third pathways swapped", "three", resign(x, STEER), g3.clone(), None, "decision_mismatch"));
let mut x = d3.clone();
x.ttl += 1;
v.push(refused("ttl_mismatch", "a TTL one second longer than the rule gives", "three", resign(x, STEER), g3.clone(), None, "decision_mismatch"));
let extra = m3.replacen("\"PATHWAY-PRIORITY\":[", "\"PATHWAY-PRIORITY\":[\"cdn-z\",", 1);
v.push(refused("manifest_mismatch", "a manifest with a pathway the policy does not have", "three", d3.to_bytes(), g3.clone(), Some(extra), "manifest_mismatch"));
let cloned = b.policy("cloned");
let bad_base = manifest(&cloned, &dc).replacen("\"BASE-ID\":\"edge-a\"", "\"BASE-ID\":\"cdn-z\"", 1);
v.push(refused("manifest_clone_unknown", "a manifest whose clone names an unknown base pathway", "cloned", dc.to_bytes(), gc, Some(bad_base), "manifest_mismatch"));
v
}
// ---- writing ----
fn status_label(s: u8) -> &'static str {
["figure", "unmetered", "mixed", "stale", "empty"][s as usize]
}
fn why_label(w: u8) -> &'static str {
["", "buffer", "floor", "share", "hold", "rank", "none"][w as usize]
}
fn at_json(at: &Place) -> Value {
match at {
Place::Room => json!(["room"]),
Place::Policy => json!(["policy"]),
Place::Decision => json!(["decision"]),
Place::Evidence(p, k) => json!(["evidence", p, k]),
Place::Pathway(p) => json!(["pathway", p]),
Place::Output => json!(["output"]),
Place::Manifest => json!(["manifest"]),
}
}
fn outcome_json(policy: Option<&Policy>, o: &Outcome) -> Map<String, Value> {
let mut m = Map::new();
match o {
Outcome::Refuse { at, reason } => {
m.insert("outcome".into(), "refuse".into());
m.insert("reason".into(), reason.code().into());
m.insert("at".into(), at_json(at));
}
Outcome::Accept(a) => {
let p = policy.expect("an accepted decision's policy reads");
m.insert("outcome".into(), "accept".into());
m.insert("digest".into(), hex(&a.digest).into());
m.insert("priority".into(), a.priority.clone().into());
m.insert("ttl".into(), a.ttl.into());
m.insert("why".into(), why_label(a.reason).into());
let ps: Vec<Value> = p
.pathways
.iter()
.zip(&a.evidence)
.zip(&a.limits)
.map(|((x, e), l)| {
json!({
"id": x.id,
"status": status_label(e.status),
"class": if e.has_figure() { Value::from(metering::tag_label(e.class)) } else { Value::Null },
"joules": e.joules.to_string(),
"delivery": e.delivery.to_string(),
"limits": l,
})
})
.collect();
m.insert("pathways".into(), ps.into());
m.insert("steering_manifest".into(), a.manifest.clone().into());
m.insert("uri".into(), a.uri.clone().into());
}
}
m
}
fn inputs_json(policy: Option<&Policy>, decision: &[u8]) -> Value {
let (Some(p), Ok(d)) = (policy, Decision::read(decision)) else { return Value::Null };
if d.pathways.len() != p.pathways.len() {
return Value::Null;
}
json!({
"t": d.t,
"session": hex(&d.session),
"protocol": protocol_label(d.protocol),
"report": report_json(p, &d.report),
"loads": d.pathways.iter().map(|s| s.load).collect::<Vec<_>>(),
})
}
fn request_json(r: &Option<(u8, String, Option<String>)>) -> Value {
match r {
None => Value::Null,
Some((proto, target, header)) => json!({ "protocol": protocol_label(*proto), "target": target, "cmcd_header": header }),
}
}
fn inputs<'a>(desc: &'a [u8], head: &'a str, policy: &'a [u8], v: &'a VectorView, records: &'a [Vec<u8>]) -> Inputs<'a> {
Inputs { descriptor: desc, head: Some(head), policy, decision: &v.decision, records, manifest: v.manifest.as_deref() }
}
/// What a vector gives a verifier, read back from the file or as written.
struct VectorView {
decision: Vec<u8>,
manifest: Option<String>,
}
fn reached(intent: &Intent, o: &Outcome) -> bool {
match (intent, o) {
(Intent::Accept(w), Outcome::Accept(a)) => a.reason == *w,
(Intent::Refuse(code), Outcome::Refuse { reason, .. }) => reason.code() == *code,
_ => false,
}
}
/// Write the corpus.
pub fn generate() -> String {
let d = descriptor();
let room_id = d.room_id();
let desc = d.to_bytes();
let head = key_log();
let mut b = Builder { room_id, policies: policies(room_id), pool: BTreeMap::new() };
let vs = vectors(&mut b);
let mut out = Map::new();
out.insert("corpus".into(), CAPABILITY.into());
out.insert("extension".into(), "extensions/energy-steering.md".into());
out.insert("principals".into(), PRINCIPALS.iter().map(|(n, i)| (n.to_string(), Value::from(hex(&pk(*i))))).collect::<Map<_, _>>().into());
out.insert("room".into(), json!({ "id": hex(&b.room_id), "descriptor": hex(&desc), "key_log_head": head }));
let mut ps = Map::new();
for (n, bytes) in &b.policies {
let read = Policy::read(bytes).ok();
ps.insert(
n.to_string(),
json!({
"policy": hex(bytes),
"hls_tag": read.as_ref().map(hls_tag),
"dash_element": read.as_ref().map(dash_element),
}),
);
}
out.insert("policies".into(), ps.into());
let three = b.policy("three");
let reqs: Vec<Value> = REQUESTS
.iter()
.map(|(name, proto, target, header)| {
let r = read_request(*proto, target.as_bytes(), header.map(str::as_bytes), &three);
json!({ "name": name, "protocol": protocol_label(*proto), "policy": "three", "target": target, "cmcd_header": header, "report": report_json(&three, &r) })
})
.collect();
out.insert("requests".into(), reqs.into());
let mut jv = Vec::new();
for v in &vs {
let pbytes = &b.policies.iter().find(|(n, _)| *n == v.policy).expect("a policy").1;
let policy = Policy::read(pbytes).ok();
let records: Vec<Vec<u8>> = v.records.iter().map(|g| b.pool[g].clone()).collect();
let view = VectorView { decision: v.decision.clone(), manifest: v.manifest.clone() };
let o = super::verify(&inputs(&desc, &head, pbytes, &view, &records));
assert!(reached(&v.intent, &o), "vector {} reaches {:?}", v.name, o);
if let (Some(r), Some(p), Ok(dec)) = (&v.request, &policy, Decision::read(&v.decision)) {
assert_eq!(read_request(r.0, r.1.as_bytes(), r.2.as_deref().map(str::as_bytes), p), dec.report, "vector {}: the request gives the decision's report", v.name);
}
let mut m = Map::new();
m.insert("name".into(), v.name.into());
m.insert("about".into(), v.about.into());
m.insert("policy".into(), v.policy.into());
m.insert("request".into(), request_json(&v.request));
m.insert("inputs".into(), inputs_json(policy.as_ref(), &v.decision));
m.insert("decision".into(), hex(&v.decision).into());
m.insert("records".into(), v.records.iter().map(|g| Value::from(hex(g))).collect::<Vec<_>>().into());
m.insert("manifest".into(), v.manifest.clone().map(Value::from).unwrap_or(Value::Null));
m.extend(outcome_json(policy.as_ref(), &o));
jv.push(Value::Object(m));
}
out.insert("records".into(), b.pool.iter().map(|(g, r)| (hex(g), Value::from(hex(r)))).collect::<Map<_, _>>().into());
out.insert("vectors".into(), jv.into());
serde_json::to_string_pretty(&Value::Object(out)).expect("JSON") + "\n"
}
fn bytes(v: &Value) -> Option<Vec<u8>> {
unhex(v.as_str()?)
}
/// Check a corpus file against this module: every request gets the report, and every vector
/// the outcome, reason, place and facts the file states. Returns what differs.
pub fn verify(doc: &str) -> Vec<String> {
let mut fails = Vec::new();
let d: Value = match serde_json::from_str(doc) {
Ok(d) => d,
Err(e) => return vec![format!("vectors.json: {e}")],
};
let (Some(desc), Some(head)) = (bytes(&d["room"]["descriptor"]), d["room"]["key_log_head"].as_str()) else {
return vec!["vectors.json: no room".into()];
};
let Some(pols) = d["policies"].as_object() else { return vec!["vectors.json: no policies".into()] };
let pool: BTreeMap<String, Vec<u8>> = d["records"].as_object().into_iter().flatten().filter_map(|(k, v)| Some((k.clone(), bytes(v)?))).collect();
let policy_bytes = |n: &str| pols.get(n).and_then(|p| bytes(&p["policy"]));
for (n, p) in pols {
let read = bytes(&p["policy"]).and_then(|b| Policy::read(&b).ok());
let want = |k: &str, f: fn(&Policy) -> String| read.as_ref().map(|r| Value::from(f(r))).unwrap_or(Value::Null) == p[k];
if !want("hls_tag", hls_tag) || !want("dash_element", dash_element) {
fails.push(format!("policy {n}: its HLS tag or DASH element differs"));
}
}
for r in d["requests"].as_array().into_iter().flatten() {
let name = r["name"].as_str().unwrap_or("?");
let Some(p) = r["policy"].as_str().and_then(policy_bytes).and_then(|b| Policy::read(&b).ok()) else {
fails.push(format!("request {name}: no policy"));
continue;
};
let proto = if r["protocol"] == "hls" { protocol::HLS } else { protocol::DASH };
let got = read_request(proto, r["target"].as_str().unwrap_or("").as_bytes(), r["cmcd_header"].as_str().map(str::as_bytes), &p);
if report_json(&p, &got) != r["report"] {
fails.push(format!("request {name}: the report is {}, the corpus states {}", report_json(&p, &got), r["report"]));
}
}
for v in d["vectors"].as_array().into_iter().flatten() {
let name = v["name"].as_str().unwrap_or("?");
let (Some(pb), Some(decision)) = (v["policy"].as_str().and_then(policy_bytes), bytes(&v["decision"])) else {
fails.push(format!("{name}: the vector does not read"));
continue;
};
let Some(records) = v["records"].as_array().and_then(|a| a.iter().map(|g| g.as_str().and_then(|g| pool.get(g)).cloned()).collect::<Option<Vec<_>>>()) else {
fails.push(format!("{name}: a record it lists is not in the corpus"));
continue;
};
let policy = Policy::read(&pb).ok();
let view = VectorView { decision: decision.clone(), manifest: v["manifest"].as_str().map(String::from) };
let o = verify_inputs(&desc, head, &pb, &view, &records);
let mut got = outcome_json(policy.as_ref(), &o);
got.insert("inputs".into(), inputs_json(policy.as_ref(), &decision));
for (k, want) in &got {
if v.get(k) != Some(want) {
fails.push(format!("{name}: {k} is {want}, the corpus states {}", v.get(k).unwrap_or(&Value::Null)));
}
}
if let (Some(r), Some(p), Ok(dec)) = (v["request"].as_object(), &policy, Decision::read(&decision)) {
let proto = if r["protocol"] == "hls" { protocol::HLS } else { protocol::DASH };
let got = read_request(proto, r["target"].as_str().unwrap_or("").as_bytes(), r["cmcd_header"].as_str().map(str::as_bytes), p);
if got != dec.report {
fails.push(format!("{name}: its request does not give the decision's report"));
}
}
}
fails
}
fn verify_inputs(desc: &[u8], head: &str, policy: &[u8], v: &VectorView, records: &[Vec<u8>]) -> Outcome {
super::verify(&inputs(desc, head, policy, v, records))
}

274
wai/wai-rs/src/energy_steering/tests.rs Normal file
View file

@ -0,0 +1,274 @@
//! Unit tests of the steering module: the records round-trip and are refused by their rules,
//! the request reader and its RFC 9651 parser, the exact products at their limits, the margin
//! at its boundary, and the rule's guarantee that a pathway with no figure is never placed
//! first by its rank while a pathway with a figure is within the limits.
use super::*;
fn k(i: u8) -> SigningKey {
SigningKey::from_bytes(&sha256(&[b"wai:energy-steering/test/key\x00", &[i]]))
}
fn pathway(id: &str, hop: u8) -> Pathway {
Pathway {
id: id.into(),
base: NOT_CLONE,
host: String::new(),
params: vec![],
top_tier: 2,
latency_ms: 100,
capacity: NO_CAPACITY,
min_share_ppm: 0,
hops: vec![(k(hop).verifying_key().to_bytes(), place::EDGE)],
}
}
fn policy(pathways: Vec<Pathway>) -> Policy {
Policy {
room: [7; 32],
signer: [0; 32],
period_us: 10,
window_us: 30,
lag_us: 2,
basis: basis::BYTES,
floor: 1,
latency_ceiling_ms: 500,
min_buffer_ms: 1000,
hysteresis_ppm: 100_000,
ttl_s: 300,
min_ttl_s: 30,
flags: 0,
initial: 0,
tiers: vec![1_000, 2_000, 4_000],
server_uri: "https://s.example/steer?a=1&b=2".into(),
reload_uri: "https://s.example/steer".into(),
decision_uri: "https://s.example/d/".into(),
pathways,
sig: [0; 64],
}
.sign(&k(0))
}
fn two() -> Policy {
policy(vec![pathway("a", 1), pathway("b", 2)])
}
fn fig(class: u8, joules: u128, delivery: u128) -> Evidence {
Evidence { status: status::FIGURE, class, joules, delivery }
}
const NO_FIGURE: Evidence = Evidence { status: status::STALE, class: 0, joules: 0, delivery: 0 };
#[test]
fn a_policy_round_trips_and_its_rules_refuse() {
let p = two();
let b = p.to_bytes();
assert_eq!(Policy::read(&b).unwrap(), p);
let reread = |f: &dyn Fn(&mut Policy)| {
let mut q = two();
f(&mut q);
Policy::read(&q.to_bytes())
};
assert_eq!(reread(&|q| q.window_us = 25), Err(Reason::PolicyInvalid), "a window that is not whole periods");
assert_eq!(reread(&|q| q.pathways[1].id = "a".into()), Err(Reason::PolicyInvalid), "two pathways of one id");
assert_eq!(reread(&|q| q.pathways[1].hops = q.pathways[0].hops.clone()), Err(Reason::PolicyInvalid), "a hop in two pathways");
assert_eq!(reread(&|q| q.reload_uri = "https://s.example/#x".into()), Err(Reason::PolicyInvalid), "a fragment");
assert_eq!(reread(&|q| q.reload_uri = "https://s.example/%4".into()), Err(Reason::PolicyInvalid), "a broken percent-encoding");
assert_eq!(reread(&|q| q.pathways[0].hops[0].1 = place::INTERIOR), Err(Reason::PolicyInvalid), "no edge hop");
assert_eq!(reread(&|q| q.pathways[1].base = 1), Err(Reason::CloneUnknown), "a clone of itself");
assert_eq!(reread(&|q| q.pathways[0].base = 1), Err(Reason::CloneUnknown), "a clone of a later pathway");
assert_eq!(reread(&|q| q.pathways[1].host = "h.example".into()), Err(Reason::PolicyInvalid), "a host on a pathway that is no clone");
assert!(reread(&|q| {
q.pathways[1].base = 0;
q.pathways[1].host = "h.example".into();
q.pathways[1].params = vec![("x".into(), "%2F".into())];
})
.is_ok());
let mut short = b.clone();
short.truncate(b.len() - 1);
assert_eq!(Policy::read(&short), Err(TRUNCATED));
let mut long = b.clone();
long.push(0);
assert_eq!(Policy::read(&long), Err(MALFORMED));
}
#[test]
fn the_window_ends_on_the_last_period_past_the_lag() {
let p = two();
assert_eq!(window(&p, 0), (0, 0));
assert_eq!(window(&p, 11), (0, 0));
assert_eq!(window(&p, 12), (0, 10));
assert_eq!(window(&p, 41), (0, 30));
assert_eq!(window(&p, 52), (20, 50));
}
#[test]
fn the_request_reader_takes_what_each_protocol_sends() {
let p = two();
let hls = |t: &str| read_request(protocol::HLS, t.as_bytes(), None, &p);
let dash = |t: &str| read_request(protocol::DASH, t.as_bytes(), None, &p);
assert_eq!(hls("/s?_HLS_pathway=%22b%22&_HLS_throughput=4000"), Report::new(Some(1), Some(4000), None));
assert_eq!(hls("/s?_HLS_pathway=b&_HLS_pathway=a"), Report::new(Some(1), None, None));
assert_eq!(hls("/s?_HLS_pathway=%22z%22&_HLS_throughput=-1"), Report::default());
assert_eq!(hls("/s?_HLS_throughput=4%3"), Report::default());
assert_eq!(dash("/s?_DASH_pathway=%22z,b%22&_DASH_throughput=5,6"), Report::new(Some(1), Some(6), None));
assert_eq!(dash("/s?_DASH_pathway=a&_DASH_throughput=5,6"), Report::new(Some(0), Some(5), None));
let cmcd = read_request(protocol::HLS, b"/s?CMCD=bl%3D%2821300%3Bv%2013000%3Ba%29%2Cmtp%3D48000", None, &p);
assert_eq!(cmcd, Report::new(None, Some(48_000_000), Some(13_000)));
let header = read_request(protocol::HLS, b"/s", Some(b"bl=(900;v),mtp=(2;v 3;a)"), &p);
assert_eq!(header, Report::new(None, Some(2_000), Some(900)));
}
#[test]
fn the_structured_field_parser_reads_rfc_9651_dictionaries() {
use sf::{parse_dictionary as d, Bare, Member};
let ok = d("a=1, b=?0, c=\"x\\\"y\", d=tok/en:1, e=:AQID:, f=-1.25;p=@12, g=%\"caf%c3%a9\", h, i=(1 2;q);r").unwrap();
assert_eq!(ok.len(), 9);
assert_eq!(ok[0].1, Member::Item(sf::Item { bare: Bare::Integer(1), params: vec![] }));
assert_eq!(ok[5].1, Member::Item(sf::Item { bare: Bare::Decimal(-1250), params: vec![("p".into(), Bare::Date(12))] }));
assert_eq!(ok[6].1, Member::Item(sf::Item { bare: Bare::Display("café".into()), params: vec![] }));
assert_eq!(ok[7].1, Member::Item(sf::Item { bare: Bare::Boolean(true), params: vec![] }));
assert!(matches!(&ok[8].1, Member::Inner(items, ps) if items.len() == 2 && ps.len() == 1));
assert_eq!(d("").unwrap(), vec![]);
for good in ["a=::", "a=:AQ:", "a=:AQ==:", "a=:AQI:", "a=:AQI=:", "a=:AQID:"] {
assert!(d(good).is_some(), "{good} does not parse");
}
assert_eq!(d("a=1,a=2").unwrap().len(), 1, "a key given twice keeps one place");
for bad in ["a=1,", "A=1", "a=(1", "a=1 b=2", "a=1234567890123456", "a=1.2345", "a=1.", "a=\"x", "a=?2", "a=%\"\u{e9}\"", "a=%\"%C3\"", "[email protected]", "a=:a*b:", "a=:A:", "a=:AQ=:", "a=:A=Q=:", "a=:AQ===:"] {
assert!(d(bad).is_none(), "{bad} parses");
}
}
#[test]
fn products_are_exact_at_their_limits() {
let m = u128::MAX;
let a = fig(4, m, m - 1);
let b = fig(4, m - 1, m);
// J_a × D_b = m × m; J_b × D_a = (m − 1)²: a's figure is the higher.
assert_eq!(cmp_figures(&a, &b), Ordering::Greater);
assert_eq!(cmp_figures(&b, &a), Ordering::Less);
assert_eq!(cmp_figures(&a, &a), Ordering::Equal);
// 2^64 × 2^64 is 2^128: one limb set, two above the u128 range's limbs.
let p = product(&[1u128 << 64, 1u128 << 64]);
assert!(p.iter().enumerate().all(|(i, &l)| l == u64::from(i == 2)), "{p:?}");
assert_eq!(cmp_limbs(&product(&[m, m, 3]), &product(&[m, m, 2])), Ordering::Greater);
assert_eq!(cmp_limbs(&product(&[m, m, PPM as u128 + 1]), &product(&[m, m, PPM as u128])), Ordering::Greater);
}
#[test]
fn the_margin_is_strict() {
// w's figure is exactly 10% below x's: it does not beat x by more than 10%.
let x = fig(4, 110, 100);
let w = fig(4, 100, 100);
assert!(!beats(&w, &x, 100_000));
assert!(beats(&w, &x, 99_999));
assert!(!beats(&w, &NO_FIGURE, 0));
}
#[test]
fn the_order_compares_figures_only_within_a_class() {
let p = policy(vec![pathway("a", 1), pathway("b", 2), pathway("c", 3), pathway("d", 4)]);
// "a" is the cheapest but estimated, "b" counter-read, "c" calibrated, "d" unknown.
let ev = [fig(3, 1, 100), fig(4, 50, 100), fig(5, 90, 100), NO_FIGURE];
assert_eq!(order(&p, &ev), vec![2, 1, 0, 3]);
let ev = [fig(4, 3, 1), fig(4, 6, 2), NO_FIGURE, NO_FIGURE];
assert_eq!(order(&p, &ev), vec![0, 1, 2, 3], "equal figures fall to the ids");
}
/// Over every evidence of four pathways drawn from a small set, with and without a current
/// pathway: when some pathway with a figure is within the limits, the rule never places a
/// pathway with no figure first by its rank or by holding a client on it.
#[test]
fn a_pathway_with_no_figure_is_never_preferred_for_it() {
let p = policy(vec![pathway("a", 1), pathway("b", 2), pathway("c", 3), pathway("d", 4)]);
let set = [NO_FIGURE, fig(4, 1, 100), fig(4, 9, 100), fig(2, 1, 1000), Evidence { status: status::UNMETERED, ..NO_FIGURE }];
let digest = p.digest();
let session = [0u8; 16];
let mut seen = 0;
for i in 0..set.len().pow(4) {
let ev: Vec<Evidence> = (0..4).map(|j| set[i / set.len().pow(j) % set.len()]).collect();
for c in [None, Some(0), Some(3)] {
let out = decide(&p, &digest, &session, &Report::new(c, Some(10_000), Some(5_000)), &[0; 4], &ev);
let any_figure = ev.iter().any(Evidence::has_figure);
if any_figure && matches!(out.reason, why::RANK | why::HOLD) {
assert!(ev[out.priority[0] as usize].has_figure(), "{ev:?} with c {c:?} gives {out:?}");
seen += 1;
}
// Every pathway is within the limits here, so after the first the priority is the
// order: every pathway with a figure before every pathway with none.
let tail: Vec<bool> = out.priority[1..].iter().map(|&x| ev[x as usize].has_figure()).collect();
assert!(tail.windows(2).all(|w| w[0] >= w[1]), "a pathway with a figure after one with none: {ev:?} gives {out:?}");
}
}
assert!(seen > 0);
}
#[test]
fn a_decision_round_trips_and_its_rules_refuse() {
let p = two();
let d = Decision {
room: p.room,
signer: [0; 32],
policy: p.digest(),
t: 52,
session: [9; 16],
draw: draw(&p.digest(), &[9; 16]),
protocol: protocol::HLS,
report: Report::new(Some(1), Some(5_000), None),
pathways: vec![
PathwayState { load: 1, limits: limit::ALL, status: status::FIGURE, class: 4, joules: 10, delivery: 20, evidence: vec![[1; 32]] },
PathwayState { load: 2, limits: limit::ALL, status: status::STALE, class: 0, joules: 0, delivery: 0, evidence: vec![] },
],
ttl: 300,
reason: why::RANK,
priority: vec![0, 1],
sig: [0; 64],
}
.sign(&k(0));
assert_eq!(Decision::read(&d.to_bytes()).unwrap(), d);
let reread = |f: &dyn Fn(&mut Decision)| {
let mut x = d.clone();
f(&mut x);
Decision::read(&x.to_bytes())
};
assert_eq!(reread(&|x| x.priority = vec![0, 0]), Err(Reason::DecisionInvalid));
assert_eq!(reread(&|x| x.pathways[1].joules = 5), Err(Reason::DecisionInvalid), "a figure on a stale pathway");
assert_eq!(reread(&|x| x.pathways[0].class = 0), Err(Reason::DecisionInvalid), "a figure with no class");
assert_eq!(reread(&|x| x.pathways[1].evidence = vec![[1; 32]]), Err(Reason::DecisionInvalid), "a record named twice");
assert_eq!(reread(&|x| x.report.throughput = 0), Ok(Decision { report: Report { throughput: 0, ..d.report }, ..d.clone() }));
assert_eq!(reread(&|x| x.report.present &= !present::THROUGHPUT), Err(Reason::DecisionInvalid), "an absent value that is not 0");
assert_eq!(reread(&|x| x.reason = 7), Err(Reason::DecisionInvalid));
}
#[test]
fn the_manifest_and_the_content_descriptions_are_fixed_bytes() {
let mut p = two();
p.pathways[1].base = 0;
p.pathways[1].host = "h.example".into();
p.pathways[1].params = vec![("k".into(), "v".into()), ("t".into(), "%2F".into())];
let d = Decision {
room: p.room,
signer: [0; 32],
policy: p.digest(),
t: 0,
session: [0xab; 16],
draw: 0,
protocol: protocol::DASH,
report: Report::default(),
pathways: vec![PathwayState::default(), PathwayState::default()],
ttl: 30,
reason: why::NONE,
priority: vec![1, 0],
sig: [0; 64],
};
let m = manifest(&p, &d);
let want = format!(
"{{\"VERSION\":1,\"TTL\":30,\"RELOAD-URI\":\"https://s.example/steer?wai_session={}\",\"PATHWAY-PRIORITY\":[\"b\",\"a\"],\"PATHWAY-CLONES\":[{{\"BASE-ID\":\"a\",\"ID\":\"b\",\"URI-REPLACEMENT\":{{\"HOST\":\"h.example\",\"PARAMS\":{{\"k\":\"v\",\"t\":\"%2F\"}}}}}}],\"science.transaction.wai-decision\":\"https://s.example/d/{}\"}}",
"ab".repeat(16),
hex(&d.digest())
);
assert_eq!(m, want);
assert!(serde_json::from_str::<serde_json::Value>(&m).is_ok());
assert_eq!(hls_tag(&p), "#EXT-X-CONTENT-STEERING:SERVER-URI=\"https://s.example/steer?a=1&b=2\",PATHWAY-ID=\"a\"");
assert_eq!(dash_element(&p), "<ContentSteering defaultServiceLocation=\"a\" queryBeforeStart=\"false\">https://s.example/steer?a=1&amp;b=2</ContentSteering>");
}

9
wai/wai-rs/src/lib.rs
View file

@ -442,6 +442,15 @@ pub mod live_record;
/// cbindgen:ignore
#[cfg(feature = "live_metering")]
pub mod live_metering;
// Energy-aware content steering (extensions/energy-steering.md): `wai.live.steering` — a signed
// steering policy (WSP1) and a signed steering decision (WSD1) that chooses each client's pathway
// from the joules its hops' per-hop records state, compared only within an acquisition class, a
// pathway with no figure never ranked above one with a figure, and writes the HLS and DASH steering
// manifests exactly. Rust-only, like the other live modules: its constants must not become macros in
// include/wai.h.
/// cbindgen:ignore
#[cfg(feature = "energy_steering")]
pub mod energy_steering;
// Timed text and live captions (extensions/timed-text.md): `wai.text.timed` — the cue model
// both WebVTT and the IMSC1 Text Profile express, live caption revisions as `caption`
// events of `wai.live.events` with the WTX1 annotation, and the exact mappings onto WebVTT

105
wai/wai-rs/tests/energy_steering.rs Normal file
View file

@ -0,0 +1,105 @@
//! `wai.live.steering` (extensions/energy-steering.md): the committed corpus
//! `live-conformance/steering/vectors.json` regenerates byte for byte from its fixed seeds,
//! every request and vector in it gets the outcome it states, every reason the extension
//! adds refuses a vector, the accepted vectors are the cases §11 names with the reasons they
//! were written for, and the extension's §10 lists exactly the reasons the reference reports.
#![cfg(feature = "energy_steering")]
use std::collections::BTreeSet;
use std::path::PathBuf;
use wai::energy_steering::{corpus, Reason};
fn wai_dir() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("..")
}
fn read(p: &str) -> String {
std::fs::read_to_string(wai_dir().join(p)).unwrap_or_else(|e| panic!("{p}: {e}"))
}
fn committed() -> String {
read("live-conformance/steering/vectors.json")
}
#[test]
fn the_committed_corpus_regenerates_from_its_seeds() {
assert!(committed() == corpus::generate(), "live-conformance/steering/vectors.json differs from `wai_energy_steering_vectors gen`");
}
#[test]
fn every_request_and_vector_gets_its_stated_outcome() {
let fails = corpus::verify(&committed());
assert!(fails.is_empty(), "{}", fails.join("\n"));
}
/// Every reason this extension adds refuses a vector; the accepted vectors are §11's, each
/// first for the reason it was written for; a pathway with no figure is last wherever a
/// figure decides; and HLS and DASH content descriptions are written for every policy that
/// reads.
#[test]
fn the_corpus_covers_every_reason_and_case() {
let doc: serde_json::Value = serde_json::from_str(&committed()).unwrap();
let vectors = doc["vectors"].as_array().unwrap();
let seen: BTreeSet<&str> = vectors.iter().filter_map(|v| v["reason"].as_str()).collect();
for r in Reason::ALL {
assert!(seen.contains(r.code()), "nothing in the corpus is refused {r}");
}
for r in ["classes_summed", "hop_not_authorised", "hop_revoked", "record_missing", "signer_not_authorised", "signer_revoked", "bad_signature"] {
assert!(seen.contains(r), "nothing in the corpus is refused {r}");
}
let get = |n: &str| vectors.iter().find(|v| v["name"] == n).unwrap_or_else(|| panic!("no vector {n}"));
let first = |n: &str| get(n)["priority"][0].as_str().unwrap().to_string();
let last = |n: &str| get(n)["priority"].as_array().unwrap().last().unwrap().as_str().unwrap().to_string();
for (n, why) in [
("three_metered", "rank"),
("mixed_classes", "rank"),
("one_unmetered", "rank"),
("mixed_hops", "rank"),
("stale", "rank"),
("floor_client", "floor"),
("buffer_guard", "buffer"),
("hysteresis_hold", "hold"),
("hysteresis_switch", "rank"),
("clones", "rank"),
("share", "share"),
("share_outside", "rank"),
("capacity", "rank"),
("latency", "rank"),
("per_second", "rank"),
("dash", "rank"),
("none_within", "none"),
] {
assert_eq!(get(n)["outcome"], "accept", "{n}");
assert_eq!(get(n)["why"], why, "{n}");
}
assert_eq!(first("three_metered"), "tree");
assert_eq!(get("mixed_classes")["priority"], serde_json::json!(["edge-a", "edge-b", "tree"]), "ordered by class, not by figure");
for (n, unknown) in [("one_unmetered", "edge-b"), ("mixed_hops", "edge-a"), ("stale", "tree"), ("share_outside", "origin")] {
assert_eq!(last(n), unknown, "{n}: the pathway with no figure is last");
}
assert_eq!(first("share"), "origin", "a minimum share places the unmetered origin path whatever its evidence");
assert_eq!((first("hysteresis_hold"), first("hysteresis_switch")), ("edge-a".into(), "tree".into()));
assert_eq!(first("clones"), "edge-a2");
assert!(get("clones")["steering_manifest"].as_str().unwrap().contains("\"PATHWAY-CLONES\":[{\"BASE-ID\":\"edge-a\",\"ID\":\"edge-a2\""));
assert_eq!(get("per_second")["priority"], serde_json::json!(["edge-a", "edge-b", "tree"]));
assert_eq!(get("dash")["inputs"]["protocol"], "dash");
for n in ["floor_client", "buffer_guard", "none_within"] {
assert_eq!(get(n)["ttl"], 30, "{n}: the short TTL");
}
for (n, p) in doc["policies"].as_object().unwrap() {
let reads = !["shares_over", "clone_later"].contains(&n.as_str());
assert_eq!(p["hls_tag"].is_string(), reads, "{n}");
assert_eq!(p["dash_element"].is_string(), reads, "{n}");
}
}
/// §10 of the extension lists exactly the codes `Reason::ALL` has, each once, in order.
#[test]
fn the_extension_lists_the_reasons() {
let text = read("extensions/energy-steering.md");
let at = text.find("\n## 10. Reasons").expect("a §10");
let end = text[at + 1..].find("\n## ").map_or(text.len(), |e| at + 1 + e);
let listed: Vec<String> = text[at..end].lines().filter(|l| l.starts_with("| `")).filter_map(|l| l.split('`').nth(1).map(String::from)).collect();
let want: Vec<String> = Reason::ALL.iter().map(|r| r.code().to_string()).collect();
assert_eq!(listed, want, "§10's table and Reason::ALL differ");
}

2
wai/wai-rs/tests/int_kernels_vectors.rs
View file

@ -223,7 +223,7 @@ fn every_decoded_output_states_a_sha256() {
("pin-conformance", "parameter-set pins: every digest there is a SHA-256 of a parameter set"),
("ops-conformance", "integer operators: every operator, stage and graph vector, the lower_* decodes of the sets under sets/ among them, states its output integers in full or its refusal code, never a digest of them; certificates/ states each lowered set's SHA-256 (a parameter-set identity) and holds the lowered graphs as bytes, compared byte for byte; the output digests a capability decoded through its lowering reproduces (integer-operators §14.4) are stated by that capability's own corpus"),
("signer-conformance", "key logs, grants and statuses: signed documents, no decoded output"),
("live-conformance", "live events, rooms, takes, compositions, recordings, captions and metering: signed records, commitments, packages, clips, cues and their renderings, per-hop records, ledgers and session receipts with their units and joules recomputed, and their verdicts, and layouts and mixes stated in full, rectangle for rectangle and sample for sample; nothing decoded against a parameter set"),
("live-conformance", "live events, rooms, takes, compositions, recordings, captions, metering and steering: signed records, commitments, packages, clips, cues and their renderings, per-hop records, ledgers and session receipts with their units and joules recomputed, steering policies and decisions with each pathway's evidence and the steering manifests recomputed byte for byte, and their verdicts, and layouts and mixes stated in full, rectangle for rectangle and sample for sample; nothing decoded against a parameter set"),
("http-conformance", "objects and head proofs for transport: no case decodes a payload, and the component a fetch case picks is stated by its SHA-256"),
("cache-conformance", "cache rules: a driver, its controls and their reports, with no objects of its own"),
("byte-exact-conformance", "goldens over tests/vectors, whose sidecars state the SHA-256"),