open-standards/wai/live-conformance/ads/README.md

# live-conformance/ads — live ads

The corpus of [`extensions/live-ads.md`](../../extensions/live-ads.md) §11: rooms whose `cue`
events open ad breaks, each a room (its `WRD1` descriptor, `WRG1` grants, key-log head or none,
and each principal's `WEV1` chain, the break annotations `WAB1` among them), its `WAP1` ad
policy, the presentation time of `t0` on the DASH Period (`pt0_ms`), and the break-form
`wai.video.ssai` receipts of its viewers, each with the pod its decision ran over; what a
verifier states of them; and each accepted room's HLS tags, byte for byte. Receipts of version
2 bind the consent signal their decision was made under and the supply chain of each impression
(§8.6, §8.7), and the vectors that hold them name the sellers files and authorised-sellers
files they are checked against.

**Ads equivalence.** For each vector, a conforming ads verifier given its `descriptor`,
`grants`, `key_log`, `chains`, `policy`, `pt0_ms`, `receipts` and `pods`, and the files its
`supply_files` names when it has that member, each as its bytes (§9.1), reaches the outcome the
vector states
(§9.4):

- `refuse`: the `reason` and where, `at`: `["room", …]` with the room verifier's own place
  (live-rooms §9.1), `["policy"]`, `["record", c, i]` for record `i` of chain `c`, or
  `["receipt", k]`;
- `gap`: the room's `gaps`, each `principal`, `first` and `last`;
- `accept`: the `room` id; the `breaks` (§4.3), each its `digest`, `id` and `event_id` (§4.4),
  `author`, `cue_id`, `t`, `type` (`out` or `break`), `placement` (`mid` or `post`),
  `planned_ms`, `avail_ms`, `duration_ms`, `closed_by` and `end` (`null` while it is open),
  and its `hls_list_uri` and `dash_list_uri` (§7.2, §7.3); the `chapters`, each `digest`, `t`
  and `duration_ms`; `hls`, the file holding the room's HLS tags; `dash`, the Period's event
  streams (§6.3); `dash_open`, each out's event as written before its in, by the out's index
  among the `breaks`; `receipt_facts`, each receipt's `identity` (§8.4), the `asset_list` it
  binds as the verifier writes it, and its `spend_micros`, and, for a receipt of version 2,
  its `consent` (`gpp`, `gpp_sid`, `child_directed`) and its `supply_chains`, one for each
  impression, each `null` or its `complete`, its `nodes` (each `asi`, `sid`,
  `sellers_checked`, `seller_type` and `relationship`) and `authorised_checked`; and
  `spend_micros`, the spend of every receipt together.

Each tag file, `NAME.m3u8`, is the HLS tags of vector `NAME` (§5.1 to §5.3), one tag a line in
the order §5.4 gives, each line ended by a line feed. It is the date ranges of the room's Media
Playlists, not a whole playlist: the segments are the room's tracks.

A verifier that reaches another outcome, reason, place, break, tag byte, event byte, asset-list
byte, identity or spend does not conform.

**Provenance.** Generated here: `wai_live_ads_vectors gen` writes every file from rooms
authored in code, from fixed seeds. Each principal's key is SHA-256 of a fixed label and the
principal's index; each creative's hash and each session id likewise; every time is a
constant (the rooms' `t0` is 2026-10-16T00:00:00Z); every origin and base URI is an
`.example` name (RFC 2606); and Ed25519 signing is deterministic (RFC 8032), so every file is
the same bytes on every machine. The GPP string is the example the GPP string's text gives for
a service reached by a URL, with its section 2; the sellers files and the authorised-sellers
files are fixtures written for their cases under `.example` names, none fetched from a service.
The generator asserts that each vector reaches the outcome it
was written to have, and that the corpus gives every reason of §10, before it writes. No
recorded data.

## Layout

- `vectors.json`: `principals` (the keys, by name, informative) and `vectors`.
- `NAME.m3u8`: the HLS tags of each accepted room.
- `supply.NAME`: the sellers files (`supply.ssp.example.sellers.json`,
  `supply.exchange.example.sellers.json`, and `supply.gateway.example.sellers.json`, which
  reads only by RFC 8259's grammar outside what §8.7 reads), the channel's authorised-sellers
  files (`supply.channel.example.app-ads.txt`, and `supply.channel.example.ads.txt`, whose
  records need each reading rule of §8.7), and files that do not read or authorise:
  `supply.not-sellers.json` (no sellers), `supply.too-deep.sellers.json`,
  `supply.lone-surrogate.sellers.json`, `supply.sellers-twice.sellers.json`,
  `supply.nan.sellers.json`, `supply.not-utf8.app-ads.txt` and
  `supply.passed-over.app-ads.txt`. They are read as bytes: some end lines with CR LF or a CR
  alone, and one is not UTF-8. `wai/.gitattributes` keeps every line ending as it is.

Every room has a producer, whose grant permits `cue`, `meta` and `chat`; a viewer, whose grant
permits `chat`; and the decider, whose grant permits no event and carries the room's ad budget,
2 minor units of EUR (2 000 000 millionths), and which never joins. The clock admits the
producer and the viewer at the room's start.

The rooms:

- `live_break`: an out at 60 s with no planned duration and its in at 90 s, under a policy
  whose open avail is 30 s and whose preload is 4 s. One viewer, present at the break's start,
  is filled with two 15 s ads from an HLS asset list (its decision energy model-based); a
  second joins 12 s into the break and is filled with what remains, one ad, from a DASH list
  MPD (its decision energy an on-chip counter's reading). No pre-roll.
- `mid_roll`: a 30 s break, annotated mid-roll, under a policy that restricts skipping and
  jumping, snaps both ways and offers a skip control after 5 s, with `pt0_ms` 5000. One
  viewer's pod has two ads at one price, ordered by `ad_id`, and three fill the avail; another
  viewer's only ad costs more than its funds, so its fill is empty and its DASH list MPD is no
  bytes.
- `post_roll`: two chapters, a 15 s mid-roll at 30 s, and a 20 s break annotated post-roll at
  120 s; one viewer filled in both breaks, another in the post-roll only.
- `chapters`: a chapter of a stated length and one of none, then an out with a planned
  duration of 15 s and its in, which states no duration.
- `gap`: `live_break`'s room as a subscriber holds it when the out was not delivered.
- refused, one defect each: `cue_kind_not_permitted` (refused by the room,
  `kind_not_permitted`), `policy_slots_zero`, `policy_wrong_room`, `policy_bad_signature`,
  `decider_grant_unknown`, `decider_grant_revoked` (a room whose key log revokes the decider
  grant, `grant_revoked`), `annotation_placement`, `annotation_on_out`, `cue_after_post_roll`,
  `overlapping_breaks`, `open_break_no_avail`, `break_of_no_duration`, `in_without_out`,
  `in_duration_mismatch`, `receipt_extra_member`, `receipt_wrong_room`,
  `receipt_bad_signature`, `receipt_quartile_six` and, for the other rules of §8.5 each
  broken alone, `receipt_format_three`, `receipt_work_below_fill`,
  `receipt_figure_without_class`, `receipt_below_resolution` and `receipt_over_its_ceiling`
  (all `receipt_invalid`), `receipt_not_decider`,
  `receipt_grant_mismatch`, `receipt_names_the_in`, `decider_grant_expired`
  (`outside_grant_window`), `pod_mismatch`, `decision_mismatch`, `asset_list_mismatch`,
  `receipt_duplicate` and `funds_exceeded` (a budget of 1 minor unit, and two viewers each
  billed 600 000 millionths).
- `consent_and_chain`: `live_break`'s room under a policy of version 3. The first viewer's
  receipt states the GPP string its player gave, with section 2, and a chain for each of its
  two ads, which answered two requests: a complete chain from the channel's own account at
  `ssp.example` (`pub-1001`, `PUBLISHER`, `DIRECT`) through `exchange.example` (the SSP's
  account `ssp-77`, `INTERMEDIARY`, `RESELLER`), and a complete chain of one node, the
  channel's own account at the exchange (`pub-2001`, `PUBLISHER`, `DIRECT`), each checked
  against the sellers files and the channel's app-ads.txt. The joining viewer's states no
  string, a child-directed request, and an incomplete chain of one node whose sellers file the
  verifier does not hold: unchecked.
- `child_room`: a 15 s break in a room whose policy marks it as directed to children; the
  receipt states the request child-directed and no chain for its ad.
- `authorised_read_liberally`: the first viewer's two ads answered one request, so its receipt
  states one chain twice: four nodes, each authorised by `supply.channel.example.ads.txt` only
  when it is read by §8.7's rules (a record of four fields; one whose advertising system is in
  other letter cases and that ends with CR LF; one whose relationship is in lower case and that
  ends with a CR alone; one with an extension field).
- `sellers_read_by_grammar`: the first viewer's first ad sold through the gateway's seller
  `pub-4001`, which `supply.gateway.example.sellers.json` lists only when what §8.7 does not
  read is read by RFC 8259's grammar alone: a number past binary64's range, one of 400 digits,
  escapes of lone surrogates in members skipped, a member name escaping a character with a
  pair of surrogates, a member nested 64 deep with the file's object, and a seller id that
  escapes one of its characters. Its second ad states no chain.
- refused, one defect each: `receipt_consent_altered`, `receipt_child_flag_cleared`,
  `receipt_chain_altered` and `receipt_chains_swapped` (a GPP string, a child-directed flag, a
  first node's seller id and the order of the two chains changed after signing, each
  `bad_signature`); `receipt_version_three`, `receipt_v1_with_consent` and
  `receipt_v2_without_chains` (`receipt_malformed`); `receipt_gpp_empty_section`,
  `receipt_gpp_not_url_safe`, `receipt_sections_without_string`, `receipt_section_repeated`
  and `receipt_child_flag_two` (`consent_invalid`); `receipt_chain_ver`,
  `receipt_chain_complete_two`, `receipt_asi_url`, `receipt_authorised_file`,
  `receipt_authorised_domain` and `receipt_chains_count` (`supply_chain_invalid`);
  `receipt_without_terms` (a receipt of version 1 under a policy of version 3,
  `request_terms_absent`); `child_flag_unset` (`child_directed_unset`);
  `sellers_file_malformed`, `sellers_file_too_deep`, `sellers_file_lone_surrogate`,
  `sellers_file_sellers_twice`, `sellers_file_nan` and `authorised_file_not_utf8`
  (`supply_file_malformed`); `seller_unlisted` (`supply_seller_unlisted`);
  `seller_unauthorised` (a chain stated complete whose first node is a reseller's account),
  `seller_absent_from_authorised` and `authorised_record_passed_over` (a node named only in a
  comment and in a line of five fields) (`supply_seller_unauthorised`); and
  `policy_audience_bit` (`ad_policy_malformed`).

## Running

```
cd ../../wai-rs
cargo run --no-default-features --features live_ads --bin wai_live_ads_vectors -- verify ../live-conformance/ads
cargo run --no-default-features --features live_ads --bin wai_live_ads_vectors -- gen    ../live-conformance/ads   # regenerate
cargo test --no-default-features --features live_ads --test live_ads
cd ../live-conformance
python3 -I live_ads_verify.py ads
```

`wai_live_ads_vectors verify` and `tests/live_ads.rs` require every file to regenerate byte for
byte, no other file but this one to be there, and `wai-rs` to give every case its outcome; the
test also requires §10 to list exactly the reasons the reference reports, and the generator
that the corpus gives each of them. `live_ads_verify.py` is the second implementation, written
from the extension's text and sharing no code with `wai-rs`: it verifies each room with
`live_rooms_verify.py`, writes every tag, event and asset list itself, verifies every receipt's
signature with WAI's strict Ed25519 rule and computes its BLAKE3 hashes from the specification,
reads every receipt's request terms and every supply file itself, as bytes, reads §10 from the
extension, gives every case the same outcome, requires every reason of §10 to appear, and then mutates
copies of the corpus, one defect each, each of which must fail.
Pass = an exit status of 0 from each.