From 977674c2d07597fe9b2f60158a092addb5811ab8 Mon Sep 17 00:00:00 2001
From: Dawn
 <c6237ef84fa537c78dcee78efd2d4e59f728859c7f194da42ac51ededfa0be05@buzz.block.builderlab.xyz>
Date: Fri, 14 Aug 2026 12:21:26 -0400
Subject: [PATCH] test(buzz-media): assert header-page granule in the Ogg
 contract oracle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The oracle blessed output that leaked the RFC 3533 6.2 "no packet completes
on this page" sentinel (0xFF..FF) onto the Vorbis comment page. Decoders
ignore granule on header pages, so such a file decodes, reports exact
duration, and compares PCM-identical while being wire-invalid — and the
relay validator correctly rejects it.

Assert granule 0 on any of the first three pages that completes a packet.
Pages that complete nothing (a spanning setup continuation) legitimately
carry the sentinel and are exempt.

Verified both directions: fails on the leaking output, passes on the
corrected output and on the reference strippers.

Co-authored-by: Dawn <c6237ef84fa537c78dcee78efd2d4e59f728859c7f194da42ac51ededfa0be05@buzz.block.builderlab.xyz>
Signed-off-by: Dawn <c6237ef84fa537c78dcee78efd2d4e59f728859c7f194da42ac51ededfa0be05@buzz.block.builderlab.xyz>
---
 crates/buzz-media/tests/fixtures/audio/README.md  | 15 ++++++++++++---
 .../tests/fixtures/audio/verify_contract.py       | 12 ++++++++++++
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/crates/buzz-media/tests/fixtures/audio/README.md b/crates/buzz-media/tests/fixtures/audio/README.md
index 5f27c5a9c..34c90a369 100644
--- a/crates/buzz-media/tests/fixtures/audio/README.md
+++ b/crates/buzz-media/tests/fixtures/audio/README.md
@@ -72,6 +72,15 @@ python3 verify_contract.py <file.ogg>...
 Asserts the canonical layout the client emits: one logical stream, page
 sequence contiguous from 0, every page CRC recomputed and re-verified, the
 identification packet alone on the BOS page, the canonical empty comment
-packet alone on page 1 with a single lacing value, and the setup packet
-isolated on its own page(s). Written from RFC 3533 rather than from any
-particular stripper implementation, so it is an independent oracle.
+packet alone on page 1 with a single lacing value, the setup packet
+isolated on its own page(s), and granule 0 (never the `-1` sentinel) on
+every header page that completes a packet. Written from RFC 3533 rather than
+from any particular stripper implementation, so it is an independent oracle.
+
+The granule assertion was added after all four instruments above — plus this
+oracle's earlier revision — passed an implementation that leaked the RFC 3533
+§6.2 "no packet completes here" sentinel (`0xFF..FF`) onto the comment page.
+Every decoder ignores that field on header pages, so the file decoded, timed,
+and PCM-compared perfectly while being wire-invalid. An oracle is only as
+strong as its strictest clause; when the relay validator rejects something
+this script blesses, the script is what's wrong.
diff --git a/crates/buzz-media/tests/fixtures/audio/verify_contract.py b/crates/buzz-media/tests/fixtures/audio/verify_contract.py
index 3d614f6f1..5c9cecc08 100644
--- a/crates/buzz-media/tests/fixtures/audio/verify_contract.py
+++ b/crates/buzz-media/tests/fixtures/audio/verify_contract.py
@@ -13,10 +13,22 @@ def check(path):
         page=d[off:off+body];pay=d[off+hdr:off+body]
         seq=struct.unpack('<I',page[18:22])[0]
         stored=struct.unpack('<I',page[22:26])[0]
+        granule=struct.unpack('<Q',page[6:14])[0]
         calc=crc32_ogg(page[:22]+b'\x00'*4+page[26:])
         serials.add(page[14:18])
         if stored!=calc: errs.append(f"page{i}: CRC mismatch")
         if seq!=i: errs.append(f"page{i}: seq={seq} not contiguous")
+        # RFC 3533 6.2: granule -1 (0xFF..FF) means "no packet completes on this
+        # page". The three Vorbis header packets carry no sample position, so a
+        # header page that DOES complete a packet has granule 0 — never the -1
+        # sentinel. (A header page that completes nothing, i.e. a spanning setup
+        # continuation, legitimately carries -1.) Leaking -1 onto a completing
+        # header page decodes fine everywhere, so only a structural check sees
+        # it; the relay validator rejects it.
+        completes = len(seg)>0 and seg[-1]!=255
+        if i<3 and completes and granule!=0:
+            shown="-1 (0xFF..FF sentinel)" if granule==0xFFFFFFFFFFFFFFFF else granule
+            errs.append(f"page{i}: header-page granule={shown}, want 0")
         if i==0:
             if not (page[5]&0x02): errs.append("page0: BOS flag not set")
             if pay[:7]!=b'\x01vorbis': errs.append("page0: not identification")