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

# live-conformance/timeliness — when an object is of use, and whether it was held in time

The corpus of [`extensions/timeliness.md`](../../extensions/timeliness.md) §10, in one file,
`vectors.json`.

**Provenance.** Generated here by `wai_timeliness_vectors gen` (`wai-rs`, feature `timeliness`),
from Ed25519 keys on fixed 32-byte seeds, constant instants, and envelopes whose payloads are
opaque test bytes written by the generator; no media and no input from outside this repository.

`keys` names every key by its role, as 64 lowercase hexadecimal digits: the publisher's
(`did:web:publisher.example#d1`), another of its origin's (`publisher_other`,
`did:web:publisher.example#d2`), and three holders' (`holder_a`, `holder_b`, `holder_c`).
`groups` names the link hash of each group the cases use, all the publisher's, all starting at
2026-11-03T00:00:00.500Z: **G**, three bases and a layer of `wai.image.int_refine` (object 3);
**F**, a floor of each of G's objects, its manifest's `derived_from.motif` the content hash of G's
object at the same position; **F_other**, F with object 2's floor derived from G's object 1; and
**H**, two objects, the second a `WAI2`; and **E**, another floor of each of G's objects, derived
as F's are, the ladder's higher rung. G's entries, used throughout, have `from_ms`
1,793,664,000,000 (2026-11-03T00:00:00Z) and `by_ms` a minute later: entry 0 falls to 600,000 two
seconds after its deadline and to 0 ten seconds after, with F's object 0 at 400,000 as its
fallback; entry 1 is a hard deadline with no fallback; entry 2 holds 700,000 from one to five
seconds after, and 0 a second later, with F's object 2 at 1,000,000. The ladder cases and the runs
give entry 0 the ladder E's object 0 at 700,000, then F's object 0 at 400,000.

- `claims` (§4.1, §4.2; jwp-receipts §3.1 steps 1 to 4) are each a claim's wire form, `claim`,
  and its `outcome`: `accept`, or `reject step=N reason=R`.
- `values` (§5) are each an `entry` read alone and an instant `at_ms`; `outcome` gives the entry's
  `value_ppm` at that instant and its `end_ms` (§5.2). No value case's entry has a fallback.
- `verdicts` (§6) are each the `groups` given, in order, each its `group` receipt and its
  `objects`, a `receipt` and its `envelope` in hexadecimal or `null`; the `claims`, in order; the
  holdings `records` in hexadecimal; and a `statement` offered (§6.4), `{group, index, holder}`, or
  `null`. `outcome` is `refuse reason=R` when a group fails jwp-receipts §3 steps 1 and 2, and
  otherwise gives: `objects`, each group's object verdicts (`delivered-verified`,
  `inclusion-verified`, `reject reason=…`); `claims` (`accepted`, or `reject step=N reason=R`);
  `records` (`stands`, `set-aside reason=holdings_contradicted`, `reject reason=…`); `intents`,
  in the order of the groups given and then of `leaf_index`, each with its `group`, `leaf_index`,
  `intent` (`stands`, or `set-aside reason=timeliness_contradicted`), `end_ms` (`null` for one set
  aside) and `lines`, in increasing order of the holder's key bytes, each its `holder`, `held_ms`
  (*p*), `fallback_ms` (*f*: one instant or `null`, and for a fallback written as an array the list
  of each rung's, in the ladder's order), `outcome` and `value_ppm`; and `statement`,
  `{outcome, value_ppm}`, `reject reason=deadline_not_stated`, or `null`.
- `plans` (§7) are each a verdict's `groups`, `claims` (timeliness, transmission and schedule) and
  `records`; `loss_ppm` and `overhead`, both integers or both `null`; `at_ms`, an instant or the
  string `from_ms`; the `sources` in the asker's order, each exactly `{kind: "bearer", bearer_id}`,
  `{kind: "holder", holder, fetch_ms}` or `{kind: "origin", fetch_ms}`; the `wanted` objects, each
  `{group, index}`; and, in a plan that states what its asker holds, `symbols`, each
  `{bearer_id, group, index, held}`, `held` one number for each source block. `outcome` is `refuse reason=R`, or gives `claims` (`accepted`,
  `declared`, `stands`, `extended`, `set-aside reason=…`, `reject step=N reason=R`), `records` as a verdict's,
  and `choices`, one for each wanted object: `{outcome, object, rung, source, arrival_ms,
  value_ppm}`, with `object` `primary`, `fallback` or `null`, `rung` the rung's index in the ladder
  or `null` unless `object` is `fallback`, and `source` an index into `sources` or `null`, or
  `reject reason=deadline_not_stated`.
- `runs` (§7.5) are each a plan's `groups`, `claims`, `records`, `loss_ppm` and `overhead`, shared
  by the run; its `plans`, each `{at_ms, sources, wanted}` as a plan case writes them; and the
  sink's `arrivals`, each `{group, index, at_ms}`, the trace of what it first held and when. A run
  that states when the sink first held its groups, claims or records also has `groups_at_ms`,
  `claims_at_ms` or `records_at_ms`, a list with one entry for each, an instant or `null`, or
  `receipts_at_ms`, a list for each group with one such entry for each of its object receipts. A run
  that states what the sink held of objects on bearer instances also has `symbols`, each
  `{bearer_id, group, index, at_ms, held}`, in the order of its clock. A case meant to be refused for
  its form writes that form: an instant, a number or a position as a string or a fraction, a hash as
  anything but 64 lowercase hexadecimal digits, a list or an entry as an integer or `null`, or a member
  left out.
  `outcome` is `refuse reason=R`, or gives `plans`, each plan's `choices` as above, in a run that
  states instants of its groups, object receipts, claims or records `read`, each plan's
  `{claims, records}` labels with `not-held` for what it did not read, and `decisions`
  in the order taken, each `{at_ms, plan, action, group, index, object, rung, source, value_ppm}`:
  `action` is `fetch`, `abandon`, `present`, `passed` or `ended`, and a member that does not apply
  is `null`.

The plans' schedules are G's objects 0 to 2 on `urn:example:bearer:b1` and F's objects on `b1` and
on `urn:example:bearer:b3`, each declared `unidirectional`: RaptorQ, one source block of eight
symbols of 128 octets and two repair symbols a pass, `advance`, ten passes of a second every ten
seconds from 2026-11-03T00:00:00Z. At the plans' loss bound of 500,000 and overhead of 2 a receiver
gets 5 symbols a pass and needs 12, so it holds an object at the end of its third pass. The cases
that state symbols hold F's object 0 on `b2` under a schedule of four passes, so from
2026-11-03T00:00:16Z two passes are left, too few from nothing and enough from what they state.
`urn:example:bearer:b2` is declared `bidirectional`.

Everything is synthetic: keys attest nothing, the publisher's origin is a reserved example domain,
and bearer instances use the example URN namespace. Each case states the outcome it was written to
have, declared in the generator, never copied from a verifier.

`wai_timeliness_vectors verify` and `tests/timeliness.rs` check that the file regenerates byte for
byte and that `wai-rs` reaches every stated outcome, the runs' through `timeliness::scheduler`.
`../timeliness_verify.py` is the second implementation, written from the extension's text, which
also mutates copies of the corpus and drops each of its own checks in turn and requires each to be
caught.