docs: OpenStream benchmark reports, published per release (#150)

Adds a reports section to the OpenStream spec so its claims rest on a
reproducible measurement rather than an assertion. Each report is a run of
the envelope over a defined corpus on real hardware: proof that
decompression restores every byte, that an incompressible input costs only
the framing overhead, that a compressible one saves what it claims against
the complete wire size, and how long each codec takes.

- docs/openstream/reports/ holds a machine-readable <id>.json (canonical,
  with a versioned schema) and a rendered <id>.md per report, plus a README
  on the shape and on submitting one. The seed report is nixamp 0.17.1 over
  the synthetic corpus, labelled synthetic so no one reads a padded-fixture
  number as production.
- The site renders them at /docs/openstream/reports (index) and
  /docs/openstream/reports/<id> (one report), under the dynamic /docs/[slug]
  tree so the reports routes never shadow a spec's own doc page. A small
  lib/reports.ts reads the JSON at build time; REPORTED_SPECS keeps the
  route surface explicit. sitemap includes the index and every report.
- The spec doc gains a Benchmark reports section linking there, and repeats
  the honest caveats: OpenStream frames Zstandard and gzip rather than being
  a new algorithm, synthetic padding flatters a codec, an efficient real
  feed saves little, and round-trip exactness is the one pass/fail.

The report format is produced by `nixamp compression benchmark` (in the
nixamp repo); a release runs it and commits the two files here.


Claude-Session: https://claude.ai/code/session_01MxNif5tsYq4LczgG7aE8Jp

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Anthony Ettinger 2026-09-12 06:23:46 -07:00 • committed by GitHub
parent 692bfa0a2a
commit 9f42ce222a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 1145 additions and 1 deletions

View file

@ -1,6 +1,7 @@
import type { MetadataRoute } from "next";
import { publicClient } from "@/lib/supabase";
import { DOC_SLUGS } from "@/lib/docs";
import { REPORTED_SPECS, reportIds } from "@/lib/reports";
export const dynamic = "force-dynamic";
@ -49,6 +50,15 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
priority: 0.6,
}));
// Benchmark reports: the index per reported spec, and each published report.
const reportEntries: MetadataRoute.Sitemap = [];
for (const slug of REPORTED_SPECS) {
reportEntries.push({ url: `${base}/docs/${slug}/reports`, changeFrequency: "monthly", priority: 0.5 });
for (const id of reportIds(slug)) {
reportEntries.push({ url: `${base}/docs/${slug}/reports/${id}`, changeFrequency: "yearly", priority: 0.4 });
}
}
let postEntries: MetadataRoute.Sitemap = [];
try {
const supabase = publicClient();
@ -68,5 +78,5 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
postEntries = [];
}
return [...staticEntries, ...docEntries, ...postEntries];
return [...staticEntries, ...docEntries, ...reportEntries, ...postEntries];
}