# Proposal: an integer conformance point for DRED feature decoding

> **Not filed.** This is a draft kept in this repository. It has not been submitted to the IETF,
> sent to the mlcodec working group, or posted anywhere. It is written so that an implementer, or
> the working group, could read it as a proposed optional addition to
> draft-ietf-mlcodec-opus-dred-07. WAI's own registration of the same profile is
> [`extensions/opus-dred.md`](../extensions/opus-dred.md), which this text summarizes.

## Problem

draft-ietf-mlcodec-opus-dred-07 §4.1 makes DRED feature decoding normative and lets an
implementation quantize the weights and approximate the network's arithmetic, its activation
functions included, provided its features pass a comparison with reference features
(`total ≤ 0.5`, `max ≤ 0.15`, `pitch ≤ 0.02`). That is the right default for interoperable
speech: every conforming decoder rebuilds speech that sounds alike.

It leaves no point at which two decoders produce the *same* features. Measured on the draft's own
test vectors, two builds of the draft's reference decoder on one host (its default configuration,
which reads the 8-bit weights, and one that reads the float weights) give features about 0.13 apart
in `total`, and neither reproduces the test vectors, which a third build wrote. Each is conforming.

Some applications need one answer: a recording that rebuilds lost speech from DRED and is later
checked against what a listener heard; a gateway that must log what it rebuilt; a test harness
that compares two implementations exactly; any receipt that signs the rebuilt features. For them,
"within tolerance" cannot be signed.

## Proposal

Add to §4.1 an **optional integer conformance point**: a decoder that claims it produces, from a
given payload, exactly the integer features this section defines, using exactly the weights the
document references (`[DRED-Weights]`, by SHA-256). A decoder that claims it is tested by
equality of its output with integer test vectors, not by the comparison tool. A decoder that
does not claim it is unaffected.

The integer point is the existing network, with:

1. **Inputs** at `2^16`: a dequantized coefficient `x·256/max(1, s)` rounded to the nearest
   integer (ties up), and `q/8 − 1` exactly.
2. **Weights** at `2^24` and biases at the accumulator's scale (`2^40` for the two layers whose
   inputs are dequantized latents, `2^39` elsewhere), each rounded half to even from the float32
   value's exact binary value, so that every implementation obtains the same integers from the
   same file.
3. **Activations** at `2^15`. `tanh` read at `2^12` and the sigmoid at `2^11` from two 65,536-entry
   tables whose entries are defined by an integer computation from one 64-bit constant
   (`⌊e^(−1/2048)·2^62⌋`, squared repeatedly, multiplied by the bits of the input). The tables'
   SHA-256 values are stated so an implementation can check them.
4. **Every layer** as an integer multiply-accumulate with a stated rounding (half up) and
   saturation at the table's input range; the GRU update written as `hc + z·(h − hc)` so that it
   rounds once.
5. **The entropy decode** unchanged, with two clarifications the integer point needs: the
   magnitude of a coefficient is `1 +` the sum of the escape symbols (as the reference decodes it),
   and a magnitude above `2^16` makes the payload invalid, which bounds the work a crafted payload
   can cause past its last byte.

Everything fits 64-bit accumulators (128-bit for the tables' construction only), uses no
floating point, and runs at the same cost order as the reference network. The full text, with
every shift and every table, is §3.3 and §4 of `extensions/opus-dred.md`.

## What it costs, measured

On the draft's eight test vectors (16,000 feature frames), against the network computed in
double-precision floating point from the same weights:

| figure | value |
|---|---|
| `total` | 0.0021 |
| `max` | 0.0013 |
| `pitch` | 0.00011 |
| largest difference in any feature | 0.0084 |
| band log-spectral distance, mean | 0.005 dB |

Against the draft's reference features the integer point passes §4.1's test on all eight vectors
(`total` 0.131, `max` 0.077, `pitch` 0.0049 over all of them), at the same distance as the
floating-point network itself: the reference features carry the arithmetic of the build that
wrote them.

## Test material

A set of payloads and streams, with the integer features they decode to by SHA-256 and the
graphs' identities, is in `live-conformance/dred/`; it names the weights by digest and does not
copy them. Two independent implementations (one in a systems language over a general integer
operator set, one in a scripting language written from the text) agree on every vector.

## Security considerations

The integer point adds no input the decoder did not already parse. Its magnitude bound removes
an unbounded loop on crafted input, and the absence of floating point removes the
data-dependent slowdowns §6 of the draft mentions.