nixamp 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/channels.ts

@@ -80,6 +80,13 @@ export interface ChannelInfo {
    * a member may have on at once.
    */
   startedBy?: string;
+  /**
+   * Set when nixamp reads the source itself and hands ffmpeg the bytes down
+   * a pipe, so the original bytes pass through this process and can be
+   * relayed exactly as they came. Only a transport stream from a file or a
+   * plain URL is read this way, and only when a policy asks for it.
+   */
+  teed?: boolean;
 }
 
 /** Where a pulled source is picked up from, and whether it can be at all. */
@@ -90,6 +97,24 @@ export interface PullResume {
   position: number;
 }
 
+/**
+ * A source read by us rather than by ffmpeg: what to tell ffmpeg it is,
+ * and how to open it. Opened once per dial; the signal is pulled when that
+ * dial is over.
+ */
+export interface PullThrough {
+  /** ffmpeg's name for the container, e.g. `mpegts`. */
+  format: string;
+  open(signal: AbortSignal): Promise<AsyncIterable<Uint8Array>>;
+}
+
+/**
+ * Asked at every dial whether this source should be read through us. Null
+ * means ffmpeg dials it as it always has. `from` is where a film is being
+ * picked up from; a source read through us cannot be joined mid-way.
+ */
+export type ThroughProvider = (info: ChannelInfo, from: number, input: string[], audio: string) => PullThrough | null;
+
 /**
  * How far back of the saved place a film is picked up from, in seconds. The
  * place is written down every so often and a restart lands between two
@@ -203,6 +228,8 @@ export interface ChannelOptions {
   maxListenerQueueBytes?: number;
   /** How long a rate is measured over before the backlog is sized off it. Tests shorten it. */
   rateWindowMs?: number;
+  /** Whether a pulled source is read here and piped to ffmpeg. See `Channels.setThrough`. */
+  through?: ThroughProvider;
 }
 
 /**
@@ -249,6 +276,10 @@ export class Channel {
    */
   ephemeral = false;
   private idle: ReturnType<typeof setTimeout> | null = null;
+  /** Whoever wants the source's own bytes, when the source is read through us. */
+  private readonly sourceTaps = new Set<Listener>();
+  /** Pulls the plug on the current read-through, when there is one. */
+  private throughAbort: AbortController | null = null;
 
   constructor(
     readonly info: ChannelInfo,
@@ -337,6 +368,15 @@ export class Channel {
       // and a film that has barely started is started.
       const from = resume.live ? 0 : Math.max(0, Math.floor((this.info.position ?? 0) - REWIND));
       const seek = from > 0 ? ["-ss", String(from)] : [];
+      // Read the source here rather than in ffmpeg, when a policy wants the
+      // original bytes and the source is the kind that can be. ffmpeg then
+      // reads a pipe, and every byte that goes down it is also handed to
+      // whoever has tapped the source. Asked again at every dial, so a
+      // policy set after the channel started applies at its next restart.
+      this.throughAbort?.abort();
+      this.throughAbort = null;
+      const through = this.options.through?.(this.info, from, input, audio) ?? null;
+      this.info.teed = through !== null;
       const child = spawn(
         command,
         [
@@ -348,36 +388,54 @@ export class Channel {
           // to. Not stderr, which is for what went wrong.
           "-progress", "pipe:3",
           "-stats_period", "1",
-          // A dropped source is normal over hours, and a channel that dies
-          // the first time a CDN hiccups is not a channel anybody can rely
-          // on. ffmpeg redials on its own before we have to.
-          // A connection that stops answering is an error after this long,
-          // and an error is a thing the reconnect knows what to do with.
-          // Without it a silent socket is waited on for ever. In
-          // microseconds, as ffmpeg wants it.
-          ...remoteArgs,
-          // Real time, always. A file read as fast as the disk allows is an
-          // hour of film in ninety seconds and a room that cannot be in it
-          // together; a live source is already paced and loses nothing.
-          ...(paced ? ["-re"] : []),
-          // What the source's site expects on the request: a user agent, a
-          // referer, a cookie. A link resolved by yt-dlp comes with these,
-          // and a CDN that got them from yt-dlp and not from us answers 403.
-          ...input,
-          ...seek,
-          "-i", source,
-          // The sound, when the site keeps it apart from the picture: a
-          // second input, dialled the same way, that the encode maps in.
-          ...(audio ? [...remoteArgs, ...(paced ? ["-re"] : []), ...input, ...seek, "-i", audio] : []),
+          ...(through
+            ? [
+                // Stated, as for a publisher: ffmpeg mis-probes a pipe. Paced
+                // the same way, since a pipe is read as fast as it is written.
+                // The source's own input tuning still applies -- a transport
+                // stream read from a pipe needs the same probe depth and
+                // generated timestamps it would off a socket -- but request
+                // headers, which only a source read through us leaves out,
+                // are no use to a pipe and are not here (a source that needs
+                // them is not read through us in the first place).
+                ...input,
+                "-f", through.format,
+                ...(paced ? ["-re"] : []),
+                "-i", "pipe:0",
+              ]
+            : [
+                // A dropped source is normal over hours, and a channel that dies
+                // the first time a CDN hiccups is not a channel anybody can rely
+                // on. ffmpeg redials on its own before we have to.
+                // A connection that stops answering is an error after this long,
+                // and an error is a thing the reconnect knows what to do with.
+                // Without it a silent socket is waited on for ever. In
+                // microseconds, as ffmpeg wants it.
+                ...remoteArgs,
+                // Real time, always. A file read as fast as the disk allows is an
+                // hour of film in ninety seconds and a room that cannot be in it
+                // together; a live source is already paced and loses nothing.
+                ...(paced ? ["-re"] : []),
+                // What the source's site expects on the request: a user agent, a
+                // referer, a cookie. A link resolved by yt-dlp comes with these,
+                // and a CDN that got them from yt-dlp and not from us answers 403.
+                ...input,
+                ...seek,
+                "-i", source,
+                // The sound, when the site keeps it apart from the picture: a
+                // second input, dialled the same way, that the encode maps in.
+                ...(audio ? [...remoteArgs, ...(paced ? ["-re"] : []), ...input, ...seek, "-i", audio] : []),
+              ]),
           ...encode,
           "pipe:1",
         ],
-        { stdio: ["ignore", "pipe", "pipe", "pipe"] },
+        { stdio: [through ? "pipe" : "ignore", "pipe", "pipe", "pipe"] },
       );
 
       let sent = false;
       this.child = child;
       this.rearm(child);
+      if (through) void this.feedThrough(child, through);
       // ffmpeg's progress: key=value lines, out_time_us being how much it
       // has written, from where it was told to start. Read whole lines,
       // since a chunk can end mid-number. Drained whatever it says, for
@@ -463,6 +521,22 @@ export class Channel {
     this.rateBytes = 0;
     this.rate = 0;
     this.hangUp();
+    // The source's own bytes start over too: a new dial is a new stream
+    // from its beginning, and whoever was tapping it must not be handed the
+    // new beginning after the old middle.
+    this.endTaps();
+  }
+
+  /** Everybody tapping the source is told it ended. */
+  private endTaps(): void {
+    for (const tap of this.sourceTaps) {
+      try {
+        tap.end();
+      } catch {
+        // Gone already.
+      }
+    }
+    this.sourceTaps.clear();
   }
 
   /** Expect output within STALL, or treat the source as gone and dial again. */
@@ -671,6 +745,69 @@ export class Channel {
     this.startOver();
   }
 
+  /**
+   * Hear the source's own bytes, as they go down the pipe to ffmpeg. Only
+   * a channel read through us has any; for the rest this attaches nothing
+   * and returns null. Ended, like a listener, when the source starts over.
+   */
+  tapSource(tap: Listener): (() => void) | null {
+    if (!this.info.teed || this.closing) return null;
+    this.sourceTaps.add(tap);
+    return () => {
+      this.sourceTaps.delete(tap);
+    };
+  }
+
+  private tap(chunk: Buffer): void {
+    for (const tap of this.sourceTaps) {
+      try {
+        tap.write(chunk);
+      } catch {
+        this.sourceTaps.delete(tap);
+      }
+    }
+  }
+
+  /**
+   * Read the source and write it to this ffmpeg's stdin, at the rate ffmpeg
+   * takes it. Every chunk is handed to the taps first, so a tap sees exactly
+   * the bytes ffmpeg does. When the source ends, stdin is ended, ffmpeg
+   * finishes, and its close handler dials again -- the same path a source
+   * that ffmpeg read itself takes when it drops.
+   */
+  private async feedThrough(child: ChildProcess, through: PullThrough): Promise<void> {
+    const controller = new AbortController();
+    this.throughAbort = controller;
+    const stdin = child.stdin;
+    if (!stdin) return;
+    stdin.on("error", () => undefined);
+    try {
+      const body = await through.open(controller.signal);
+      for await (const raw of body) {
+        if (this.child !== child || this.closing || controller.signal.aborted) break;
+        const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+        this.tap(chunk);
+        if (!stdin.write(chunk)) {
+          // Wait for ffmpeg to take it, or for the pipe to go: a pipe that
+          // closed never drains, and waiting on it would hold the read open.
+          await new Promise<void>((done) => {
+            stdin.once("drain", done);
+            stdin.once("close", done);
+          });
+        }
+      }
+    } catch (error) {
+      if (this.child === child && !controller.signal.aborted) this.info.error = (error as Error).message;
+    } finally {
+      try {
+        stdin.end();
+      } catch {
+        // Already gone.
+      }
+      if (this.throughAbort === controller) this.throughAbort = null;
+    }
+  }
+
   listen(listener: Listener): () => void {
     // What the stream is, before any of what it is currently saying. Without
     // this a listener who arrives after the first second gets fragments that
@@ -735,6 +872,9 @@ export class Channel {
     if (said && !this.info.error) this.info.error = said;
     const child = this.child;
     this.child = null;
+    this.throughAbort?.abort();
+    this.throughAbort = null;
+    this.endTaps();
     try {
       child?.stdin?.end();
     } catch {
@@ -838,6 +978,7 @@ export class Channels {
     input: string[] = [],
     audio = "",
     resume: PullResume = { live: true, position: 0 },
+    codecs?: ChannelInfo["codecs"],
   ): Channel | null {
     if (this.open.has(id)) return null;
     const channel = new Channel(
@@ -851,6 +992,9 @@ export class Channels {
         listeners: 0,
         kind,
         source,
+        // Known before the first dial, so whether to read the source here
+        // can be decided from what it holds.
+        ...(codecs ? { codecs } : {}),
       },
       this.options,
       (gone) => this.open.delete(gone),
@@ -965,6 +1109,20 @@ export class Channels {
     return this.open.get(id)?.opening() ?? [];
   }
 
+  /** Hear a channel's source bytes, when it is read through us. Null otherwise. */
+  tapSource(id: string, tap: Listener): (() => void) | null {
+    return this.open.get(id)?.tapSource(tap) ?? null;
+  }
+
+  /**
+   * Who decides whether a pulled source is read here and piped to ffmpeg.
+   * Set once by whoever owns the policies; asked at every dial.
+   */
+  setThrough(provider: ThroughProvider | null): void {
+    if (provider) this.options.through = provider;
+    else delete this.options.through;
+  }
+
   /** The kind of a channel, for a relay to say what it is carrying. */
   kindOf(id: string): "audio" | "video" | undefined {
     return this.open.get(id)?.info.kind;

package/src/compression/benchmark.ts

@@ -0,0 +1,297 @@
+/**
+ * The OpenStream benchmark: what a codec makes of a defined corpus, on this
+ * machine, with every number reproducible and nothing claimed that was not
+ * measured.
+ *
+ * It proves the honest things: that decompression restores every byte, that
+ * an incompressible sample costs only the envelope overhead and never more,
+ * that a compressible one saves what it says against the complete wire size,
+ * and how long each takes. It does not prove a production saving -- a
+ * synthetic padded stream compresses to almost nothing, which says more about
+ * the padding than the codec, and the report labels it so. Point it at real
+ * authorized samples with `--corpus` for numbers that mean something.
+ *
+ * The corpus is built from bytes alone by default, so anyone can run it with
+ * no ffmpeg and no media: random data, zeros, repetitive text, tiny and empty
+ * inputs, and hand-built transport-stream packets with a known share of null
+ * padding. ffmpeg, when present, adds real encoded media; a directory of your
+ * own files replaces the lot.
+ */
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { arch, cpus, platform, release, totalmem } from "node:os";
+import { join } from "node:path";
+import { type BenchRow, benchmark } from "./analyze.ts";
+import { toolVersions } from "./codec.ts";
+import { ENVELOPE_VERSION, FRAME_HEADER_BYTES, MAGIC, STREAM_HEADER_BYTES } from "./envelope.ts";
+import { DEFAULT_LOSSLESS } from "./policy.ts";
+import { SYNC, TS_PACKET } from "./ts-transform.ts";
+
+/** The report schema version, bumped when the shape below changes. */
+export const REPORT_SCHEMA = 1;
+
+export interface Sample {
+  name: string;
+  /** synthetic bytes we generated, or a real file the runner supplied. */
+  kind: "synthetic" | "real";
+  bytes: Buffer;
+  /** A word on what it is and why it is in the corpus. */
+  notes: string;
+}
+
+export interface SampleResult {
+  sample: string;
+  kind: Sample["kind"];
+  inputBytes: number;
+  sha256: string;
+  container: string;
+  rows: BenchRow[];
+  /** The mode the policy would pick for this sample, and why. */
+  recommendation: { mode: string; level: number; reason: string };
+}
+
+export interface BenchmarkReport {
+  schema: number;
+  spec: "openstream";
+  specVersion: string;
+  generatedAt: string;
+  implementation: { name: string; version: string };
+  environment: {
+    runtime: string;
+    zstd: string;
+    zlib: string;
+    os: string;
+    arch: string;
+    cpu: string;
+    cores: number;
+    memoryGiB: number;
+  };
+  envelope: { magic: string; streamHeaderBytes: number; frameHeaderBytes: number };
+  policy: { minSavingsPercent: number; minSavingsBytes: number; maxBlockBytes: number; zstdLevels: number[] };
+  samples: SampleResult[];
+  /** Per mode, summed across the corpus: the honest aggregate. */
+  summary: {
+    corpusBytes: number;
+    byMode: { mode: string; level: number; wireBytes: number; savingsPercent: number; roundTrip: boolean; encodeMs: number; decodeMs: number }[];
+  };
+  caveats: string[];
+}
+
+/**
+ * A deterministic, genuinely incompressible fill: a SHA-256 keystream from a
+ * fixed seed. Reproducible byte-for-byte across runs (so two reports compare)
+ * and uncompressible (so the "floor" sample is really the floor, unlike a
+ * linear-congruential stream, whose periodicity a compressor crushes).
+ */
+function keystream(size: number, seed: string): Buffer {
+  const out = Buffer.alloc(size);
+  let block = createHash("sha256").update(seed).digest();
+  let at = 0;
+  while (at < size) {
+    const take = Math.min(block.length, size - at);
+    block.copy(out, at, 0, take);
+    at += take;
+    block = createHash("sha256").update(block).digest();
+  }
+  return out;
+}
+
+/** Transport-stream packets, a given share of them null padding, payloads incompressible. */
+function fakeTs(packets: number, nullEvery: number, seed = "ts"): Buffer {
+  const out = Buffer.alloc(packets * TS_PACKET);
+  const fill = keystream(packets * TS_PACKET, seed);
+  for (let i = 0; i < packets; i += 1) {
+    const at = i * TS_PACKET;
+    const isNull = nullEvery > 0 && i % nullEvery === 0;
+    const pid = isNull ? 0x1fff : [0x100, 0x101, 0x102][i % 3] as number;
+    out[at] = SYNC;
+    out[at + 1] = (pid >> 8) & 0x1f;
+    out[at + 2] = pid & 0xff;
+    out[at + 3] = 0x10 | (i & 0xf);
+    for (let j = at + 4; j < at + TS_PACKET; j += 1) out[j] = isNull ? 0xff : (fill[j] as number);
+  }
+  return out;
+}
+
+/** The default corpus: bytes only, no ffmpeg, deterministic. */
+export function syntheticCorpus(): Sample[] {
+  return [
+    { name: "random-1mib", kind: "synthetic", bytes: keystream(1024 * 1024, "random"), notes: "incompressible: the floor, where a codec must not grow the data beyond envelope overhead" },
+    { name: "zeros-1mib", kind: "synthetic", bytes: Buffer.alloc(1024 * 1024, 0), notes: "maximally compressible: the ceiling" },
+    { name: "text-repeat-1mib", kind: "synthetic", bytes: Buffer.from("the quick brown fox jumps over the lazy dog\n".repeat(24000)).subarray(0, 1024 * 1024), notes: "repetitive text: ordinary redundancy" },
+    { name: "ts-padded-50pct", kind: "synthetic", bytes: fakeTs(4000, 2), notes: "transport stream, half null packets: padding a copy must keep and a codec removes; the synthetic case that flatters a codec" },
+    { name: "ts-unpadded", kind: "synthetic", bytes: fakeTs(4000, 0), notes: "transport stream, no padding: closer to an efficient real feed" },
+    { name: "tiny-3b", kind: "synthetic", bytes: Buffer.from("abc"), notes: "smaller than a frame header: proves overhead is reported honestly" },
+    { name: "empty", kind: "synthetic", bytes: Buffer.alloc(0), notes: "the empty stream" },
+  ];
+}
+
+/** Real files a runner points us at, each read whole (capped) as a sample. */
+export function fileCorpus(dir: string, capBytes = 64 * 1024 * 1024): Sample[] {
+  const out: Sample[] = [];
+  for (const name of readdirSync(dir).sort()) {
+    const path = join(dir, name);
+    try {
+      if (!statSync(path).isFile()) continue;
+      const whole = readFileSync(path);
+      out.push({ name, kind: "real", bytes: whole.subarray(0, capBytes), notes: whole.length > capBytes ? `real file, first ${capBytes} bytes of ${whole.length}` : "real file" });
+    } catch {
+      // Unreadable entries are skipped, not fatal.
+    }
+  }
+  return out;
+}
+
+export interface RunOptions {
+  implementationVersion: string;
+  zstdLevels?: number[];
+  blockBytes?: number;
+  signal?: AbortSignal;
+}
+
+/** Run the corpus and build the report. */
+export async function runBenchmark(corpus: Sample[], options: RunOptions): Promise<BenchmarkReport> {
+  const zstdLevels = options.zstdLevels ?? [1, 3, 9];
+  const blockBytes = options.blockBytes ?? DEFAULT_LOSSLESS.maxBlockBytes;
+  const policy = { minSavingsPercent: DEFAULT_LOSSLESS.minSavingsPercent, minSavingsBytes: DEFAULT_LOSSLESS.minSavingsBytes };
+  const samples: SampleResult[] = [];
+  for (const sample of corpus) {
+    if (options.signal?.aborted) break;
+    const rows = await benchmark(sample.bytes, { blockBytes, zstdLevels, tsAware: true, policy, ...(options.signal ? { signal: options.signal } : {}) });
+    const stored = rows.find((r) => r.mode === "stored");
+    const best = rows.filter((r) => r.roundTrip && r.mode !== "stored").sort((a, b) => a.wireBytes - b.wireBytes)[0];
+    const beats = stored && best && stored.wireBytes - best.wireBytes >= policy.minSavingsBytes && ((stored.wireBytes - best.wireBytes) * 100) / stored.wireBytes >= policy.minSavingsPercent;
+    samples.push({
+      sample: sample.name,
+      kind: sample.kind,
+      inputBytes: sample.bytes.length,
+      sha256: createHash("sha256").update(sample.bytes).digest("hex"),
+      container: rows.length ? sniff(sample.bytes) : "empty",
+      rows,
+      recommendation: beats && best
+        ? { mode: best.mode, level: best.level, reason: `saves ${best.savingsPercent}% of the complete wire size` }
+        : { mode: "stored", level: 0, reason: "no codec beat stored by the configured margin" },
+    });
+  }
+  const byMode = aggregate(samples);
+  const cpu = cpus()[0]?.model ?? "unknown";
+  return {
+    schema: REPORT_SCHEMA,
+    spec: "openstream",
+    specVersion: MAGIC,
+    generatedAt: new Date().toISOString(),
+    implementation: { name: "nixamp", version: options.implementationVersion },
+    environment: {
+      ...toolVersions(),
+      os: `${platform()} ${release()}`,
+      arch: arch(),
+      cpu,
+      cores: cpus().length,
+      memoryGiB: Math.round((totalmem() / 1024 ** 3) * 10) / 10,
+    },
+    envelope: { magic: MAGIC, streamHeaderBytes: STREAM_HEADER_BYTES, frameHeaderBytes: FRAME_HEADER_BYTES },
+    policy: { ...policy, maxBlockBytes: blockBytes, zstdLevels },
+    samples,
+    summary: { corpusBytes: corpus.reduce((n, s) => n + s.bytes.length, 0), byMode },
+    caveats: [
+      `Envelope v${ENVELOPE_VERSION}: a ${STREAM_HEADER_BYTES}-byte stream header, a ${FRAME_HEADER_BYTES}-byte header per frame, plus one end frame.`,
+      "OpenStream is a framing envelope over Zstandard and gzip, not a new compression algorithm; these numbers are those codecs at the block boundary, honestly framed.",
+      "Synthetic samples do not predict production savings. A padded transport stream flatters a codec by its padding; an efficient real feed saves far less. Use --corpus with authorized real samples for numbers that mean something.",
+      "Timings are wall-clock on the machine and runtime named in `environment` and do not transfer to other hardware.",
+      "roundTrip:false in any row is a failure of exactness and must block a release.",
+    ],
+  };
+}
+
+function sniff(bytes: Buffer): string {
+  // A light container guess for the report; the full analyzer is elsewhere.
+  if (bytes.length >= 8 && bytes.toString("latin1", 4, 8) === "ftyp") return "mp4";
+  if (bytes.length >= TS_PACKET && bytes[0] === SYNC && bytes[TS_PACKET] === SYNC) return "mpegts";
+  return "bytes";
+}
+
+function aggregate(samples: SampleResult[]): BenchmarkReport["summary"]["byMode"] {
+  const modes = new Map<string, { mode: string; level: number; wireBytes: number; input: number; roundTrip: boolean; encodeMs: number; decodeMs: number }>();
+  for (const sample of samples) {
+    for (const row of sample.rows) {
+      // A row with a note is a mode that did not apply to this sample (ts-zstd
+      // on non-transport bytes, say). It is not a saving and not a failure, so
+      // it is left out of the aggregate rather than dragging a mode down.
+      if (row.note) continue;
+      const key = `${row.mode}:${row.level}`;
+      const acc = modes.get(key) ?? { mode: row.mode, level: row.level, wireBytes: 0, input: 0, roundTrip: true, encodeMs: 0, decodeMs: 0 };
+      acc.wireBytes += row.wireBytes;
+      acc.input += row.inputBytes;
+      acc.roundTrip = acc.roundTrip && row.roundTrip;
+      acc.encodeMs += row.encodeMs;
+      acc.decodeMs += row.decodeMs;
+      modes.set(key, acc);
+    }
+  }
+  return [...modes.values()].map((m) => ({
+    mode: m.mode,
+    level: m.level,
+    wireBytes: m.wireBytes,
+    savingsPercent: m.input === 0 ? 0 : Math.round(((m.input - m.wireBytes) * 100) / m.input * 100) / 100,
+    roundTrip: m.roundTrip,
+    encodeMs: Math.round(m.encodeMs * 100) / 100,
+    decodeMs: Math.round(m.decodeMs * 100) / 100,
+  }));
+}
+
+/** The report as Markdown, for a human and for the reports page. */
+export function reportMarkdown(report: BenchmarkReport): string {
+  const e = report.environment;
+  const lines: string[] = [];
+  lines.push(`# OpenStream benchmark — ${report.implementation.name} ${report.implementation.version}`);
+  lines.push("");
+  lines.push(`Generated ${report.generatedAt} · envelope ${report.specVersion} · schema ${report.schema}`);
+  lines.push("");
+  lines.push(`**Environment.** ${e.runtime}, zstd ${e.zstd}, zlib ${e.zlib}, on ${e.os} ${e.arch}, ${e.cores}× ${e.cpu}, ${e.memoryGiB} GiB.`);
+  lines.push("");
+  lines.push(`**Policy.** block ${report.policy.maxBlockBytes} B; eligible at ${report.policy.minSavingsPercent}% and ${report.policy.minSavingsBytes} B; zstd levels ${report.policy.zstdLevels.join(", ")}.`);
+  lines.push("");
+  lines.push("## Corpus");
+  lines.push("");
+  lines.push("| sample | kind | bytes | container | best mode | saves |");
+  lines.push("| --- | --- | ---: | --- | --- | ---: |");
+  for (const s of report.samples) {
+    const best = s.rows.filter((r) => r.roundTrip && r.mode !== "stored").sort((a, b) => a.wireBytes - b.wireBytes)[0];
+    const saves = s.recommendation.mode === "stored" ? "stored" : `${best?.savingsPercent ?? 0}%`;
+    lines.push(`| ${s.sample} | ${s.kind} | ${s.inputBytes} | ${s.container} | ${s.recommendation.mode}${s.recommendation.level ? ` L${s.recommendation.level}` : ""} | ${saves} |`);
+  }
+  lines.push("");
+  lines.push("## Aggregate, per mode across the corpus");
+  lines.push("");
+  lines.push("| mode | wire bytes | saving | enc ms | dec ms | round trip |");
+  lines.push("| --- | ---: | ---: | ---: | ---: | --- |");
+  for (const m of report.summary.byMode) {
+    lines.push(`| ${m.mode}${m.level ? ` L${m.level}` : ""} | ${m.wireBytes} | ${m.savingsPercent >= 0 ? "+" : ""}${m.savingsPercent}% | ${m.encodeMs} | ${m.decodeMs} | ${m.roundTrip ? "ok" : "FAILED"} |`);
+  }
+  lines.push("");
+  lines.push("## Caveats");
+  lines.push("");
+  for (const c of report.caveats) lines.push(`- ${c}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Whether every applicable codec restored exactly: the gate a release must
+ * pass. A row with a note is a mode that did not apply to that sample, not a
+ * corrupted round trip, so it does not fail the gate.
+ */
+export function reportPasses(report: BenchmarkReport): boolean {
+  return report.samples.every((s) => s.rows.every((r) => r.roundTrip || Boolean(r.note)));
+}
+
+/** The rows that are a real exactness failure: ran, and did not restore. */
+export function exactnessFailures(report: BenchmarkReport): { sample: string; mode: string; level: number }[] {
+  const out: { sample: string; mode: string; level: number }[] = [];
+  for (const s of report.samples) {
+    for (const r of s.rows) {
+      if (!r.roundTrip && !r.note) out.push({ sample: s.sample, mode: r.mode, level: r.level });
+    }
+  }
+  return out;
+}