From 9f42ce222a131626ca4df1044255716b477799f9 Mon Sep 17 00:00:00 2001 From: Anthony Ettinger Date: Sat, 12 Sep 2026 06:23:46 -0700 Subject: [PATCH] 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 .json (canonical, with a versioned schema) and a rendered .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/ (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 --- .../src/app/docs/[slug]/reports/[id]/page.tsx | 75 ++ .../src/app/docs/[slug]/reports/page.tsx | 80 ++ apps/logicsrc-web/src/app/sitemap.ts | 12 +- apps/logicsrc-web/src/lib/reports.ts | 116 +++ docs/openstream.md | 6 + .../2026-09-12-nixamp-0.17.1-synthetic.json | 793 ++++++++++++++++++ .../2026-09-12-nixamp-0.17.1-synthetic.md | 38 + docs/openstream/reports/README.md | 26 + 8 files changed, 1145 insertions(+), 1 deletion(-) create mode 100644 apps/logicsrc-web/src/app/docs/[slug]/reports/[id]/page.tsx create mode 100644 apps/logicsrc-web/src/app/docs/[slug]/reports/page.tsx create mode 100644 apps/logicsrc-web/src/lib/reports.ts create mode 100644 docs/openstream/reports/2026-09-12-nixamp-0.17.1-synthetic.json create mode 100644 docs/openstream/reports/2026-09-12-nixamp-0.17.1-synthetic.md create mode 100644 docs/openstream/reports/README.md diff --git a/apps/logicsrc-web/src/app/docs/[slug]/reports/[id]/page.tsx b/apps/logicsrc-web/src/app/docs/[slug]/reports/[id]/page.tsx new file mode 100644 index 0000000..cdd1cf7 --- /dev/null +++ b/apps/logicsrc-web/src/app/docs/[slug]/reports/[id]/page.tsx @@ -0,0 +1,75 @@ +import Link from "next/link"; +import { notFound } from "next/navigation"; +import type { ReactNode } from "react"; +import type { Metadata } from "next"; +import { marked } from "marked"; +import { hasReports, readReportJson, readReportMarkdown, reportIds, REPORTED_SPECS } from "@/lib/reports"; +import { SiteShell } from "@/components/site-shell"; +import { sanitizeRenderedHtml } from "@/lib/html"; + +// Statically generate every published report of every reported spec. +export function generateStaticParams(): Array<{ slug: string; id: string }> { + const out: Array<{ slug: string; id: string }> = []; + for (const slug of REPORTED_SPECS) { + for (const id of reportIds(slug)) out.push({ slug, id }); + } + return out; +} + +export const dynamicParams = false; + +export async function generateMetadata({ + params, +}: { + params: Promise<{ slug: string; id: string }>; +}): Promise { + const { slug, id } = await params; + const r = readReportJson(slug, id); + if (!r) return { title: "Not found · LogicSRC" }; + return { + title: `${r.implementation.name} ${r.implementation.version} benchmark · ${slug} · LogicSRC`, + description: `Reproducible ${slug} benchmark: ${r.environment.runtime} on ${r.environment.os}, generated ${r.generatedAt}.`, + alternates: { canonical: `/docs/${slug}/reports/${id}` }, + }; +} + +export default async function ReportPage({ + params, +}: { + params: Promise<{ slug: string; id: string }>; +}): Promise { + const { slug, id } = await params; + if (!hasReports(slug)) notFound(); + const md = readReportMarkdown(slug, id); + const json = readReportJson(slug, id); + if (!md || !json) notFound(); + + const rawHtml = await marked.parse(md); + const html = sanitizeRenderedHtml(rawHtml); + const repoJson = `https://github.com/profullstack/logicsrc/blob/master/docs/${slug}/reports/${id}.json`; + + return ( + +
+

+ + ← Benchmark reports + +

+
+

+ Machine-readable source:{" "} + + {id}.json + {" "} + (schema {json.schema}). Reproduce it by running the reference + implementation's benchmark and comparing on your own hardware. +

+
+ + ); +} diff --git a/apps/logicsrc-web/src/app/docs/[slug]/reports/page.tsx b/apps/logicsrc-web/src/app/docs/[slug]/reports/page.tsx new file mode 100644 index 0000000..617b29f --- /dev/null +++ b/apps/logicsrc-web/src/app/docs/[slug]/reports/page.tsx @@ -0,0 +1,80 @@ +import Link from "next/link"; +import { notFound } from "next/navigation"; +import type { ReactNode } from "react"; +import type { Metadata } from "next"; +import { docTitle, readDoc } from "@/lib/docs"; +import { hasReports, listReports, REPORTED_SPECS } from "@/lib/reports"; +import { SiteShell } from "@/components/site-shell"; + +// One reports index per spec that has one. Kept under the dynamic /docs/[slug] +// tree so it never shadows the spec's own doc page. +export function generateStaticParams(): Array<{ slug: string }> { + return REPORTED_SPECS.map((slug) => ({ slug })); +} + +export const dynamicParams = false; + +export async function generateMetadata({ + params, +}: { + params: Promise<{ slug: string }>; +}): Promise { + const { slug } = await params; + return { + title: `Benchmark reports · ${slug} · LogicSRC`, + description: `Reproducible benchmark reports published with each release of the ${slug} reference implementation.`, + alternates: { canonical: `/docs/${slug}/reports` }, + }; +} + +export default async function ReportsIndex({ + params, +}: { + params: Promise<{ slug: string }>; +}): Promise { + const { slug } = await params; + if (!hasReports(slug)) notFound(); + const md = readDoc(slug); + const specTitle = md ? docTitle(md, slug) : slug; + const reports = listReports(slug); + + return ( + +
+

+ + ← {specTitle} + +

+
+

Benchmark reports

+

+ Each report is a reproducible run of the {specTitle} benchmark over a + defined corpus, published with a release so the standard's claims + rest on a measurement rather than an assertion. Anyone can reproduce + one; the machine-readable JSON and the run's environment travel + with every report. +

+
+ {reports.length === 0 ? ( +

No reports published yet.

+ ) : ( +
    + {reports.map((r) => ( +
  • + +

    + {r.implementation} +

    + +

    + {new Date(r.generatedAt).toISOString().slice(0, 10)} · {r.headline} +

    +
    • + ))} +
+ )} +
+ + ); +} diff --git a/apps/logicsrc-web/src/app/sitemap.ts b/apps/logicsrc-web/src/app/sitemap.ts index 04e46eb..243dfd0 100644 --- a/apps/logicsrc-web/src/app/sitemap.ts +++ b/apps/logicsrc-web/src/app/sitemap.ts @@ -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 { 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 { postEntries = []; } - return [...staticEntries, ...docEntries, ...postEntries]; + return [...staticEntries, ...docEntries, ...reportEntries, ...postEntries]; } diff --git a/apps/logicsrc-web/src/lib/reports.ts b/apps/logicsrc-web/src/lib/reports.ts new file mode 100644 index 0000000..9e522aa --- /dev/null +++ b/apps/logicsrc-web/src/lib/reports.ts @@ -0,0 +1,116 @@ +import { existsSync, readdirSync, readFileSync } from "node:fs"; +import { resolve } from "node:path"; + +// Benchmark reports published alongside a spec, at docs//reports/. +// Each report is a machine-readable .json (the canonical artifact, +// produced by a reference implementation and committed on a release) and a +// rendered .md that this site displays. Read at build time, so the +// deployed image has no runtime filesystem dependency. +const DOCS_DIR = resolve(process.cwd(), "../../docs"); + +// Specs that carry a reports section. Kept explicit so a stray directory +// never becomes a route. +export const REPORTED_SPECS = ["openstream"] as const; +export type ReportedSpec = (typeof REPORTED_SPECS)[number]; + +export function hasReports(spec: string): spec is ReportedSpec { + return (REPORTED_SPECS as readonly string[]).includes(spec); +} + +function reportsDir(spec: string): string { + return resolve(DOCS_DIR, spec, "reports"); +} + +const ID = /^[a-z0-9][a-z0-9._-]{0,80}$/; + +/** The report ids published for a spec, newest first by filename. */ +export function reportIds(spec: string): string[] { + if (!hasReports(spec)) return []; + const dir = reportsDir(spec); + if (!existsSync(dir)) return []; + const ids = new Set(); + for (const name of readdirSync(dir)) { + const m = /^(.+)\.json$/.exec(name); + if (m && ID.test(m[1] as string)) ids.add(m[1] as string); + } + return [...ids].sort().reverse(); +} + +export interface ReportEnvironment { + runtime: string; + zstd: string; + zlib: string; + os: string; + arch: string; + cpu: string; + cores: number; + memoryGiB: number; +} + +export interface ReportModeSummary { + mode: string; + level: number; + wireBytes: number; + savingsPercent: number; + roundTrip: boolean; + encodeMs: number; + decodeMs: number; +} + +export interface Report { + schema: number; + spec: string; + specVersion: string; + generatedAt: string; + implementation: { name: string; version: string }; + environment: ReportEnvironment; + summary: { corpusBytes: number; byMode: ReportModeSummary[] }; + caveats: string[]; + // Other fields (samples, policy, envelope) are present in the JSON but not + // needed for the listing; the detail page renders the committed Markdown. + [key: string]: unknown; +} + +export function readReportJson(spec: string, id: string): Report | null { + if (!hasReports(spec) || !ID.test(id)) return null; + try { + return JSON.parse(readFileSync(resolve(reportsDir(spec), `${id}.json`), "utf8")) as Report; + } catch { + return null; + } +} + +export function readReportMarkdown(spec: string, id: string): string | null { + if (!hasReports(spec) || !ID.test(id)) return null; + try { + return readFileSync(resolve(reportsDir(spec), `${id}.md`), "utf8"); + } catch { + return null; + } +} + +export interface ReportSummary { + id: string; + generatedAt: string; + implementation: string; + /** The best round-tripping saving on the corpus, for the listing line. */ + headline: string; +} + +export function listReports(spec: string): ReportSummary[] { + const out: ReportSummary[] = []; + for (const id of reportIds(spec)) { + const r = readReportJson(spec, id); + if (!r) continue; + const best = r.summary?.byMode + ?.filter((m) => m.roundTrip && m.mode !== "stored") + .sort((a, b) => b.savingsPercent - a.savingsPercent)[0]; + out.push({ + id, + generatedAt: r.generatedAt, + implementation: `${r.implementation.name} ${r.implementation.version}`, + headline: best ? `${best.mode} saved ${best.savingsPercent}% across the corpus` : "no codec beat stored on this corpus", + }); + } + return out; +} diff --git a/docs/openstream.md b/docs/openstream.md index 7cf7ea1..b615636 100644 --- a/docs/openstream.md +++ b/docs/openstream.md @@ -129,6 +129,12 @@ An implementation conforms when it: [NixAmp](https://nixamp.com) is the reference implementation. It relays a live channel or a static file between servers under this envelope, choosing Zstandard per block where it pays and storing the rest, and it publishes the same byte layout and test vectors alongside its code. The format carries any byte stream; media is only its first use. +## Benchmark reports + +A claim about compression is only as good as a run anyone can reproduce, so every release of a reference implementation publishes a benchmark report: the envelope run over a defined corpus on real hardware, with recorded runtime and codec versions, proving byte-exact round trips, the overhead floor on incompressible input, the saving on compressible input, and the timings. Published reports are at [/docs/openstream/reports](/docs/openstream/reports). + +Read the caveats in any report before quoting a number. OpenStream frames Zstandard and gzip; it is not a new algorithm, a synthetic padded stream flatters a codec by its padding, and an efficient real feed saves little. The one pass/fail is round-trip exactness, which must hold for every applicable codec on every sample. + ## Status OpenStream is at version 1 (`NXS1`). The wire format above is stable; future versions bump the magic and the stream-header version together, and a receiver refuses a version it does not understand rather than guessing. diff --git a/docs/openstream/reports/2026-09-12-nixamp-0.17.1-synthetic.json b/docs/openstream/reports/2026-09-12-nixamp-0.17.1-synthetic.json new file mode 100644 index 0000000..05fa85a --- /dev/null +++ b/docs/openstream/reports/2026-09-12-nixamp-0.17.1-synthetic.json @@ -0,0 +1,793 @@ +{ + "schema": 1, + "spec": "openstream", + "specVersion": "NXS1", + "generatedAt": "2026-09-12T13:13:15.713Z", + "implementation": { + "name": "nixamp", + "version": "0.17.1" + }, + "environment": { + "runtime": "bun 1.4.0", + "zstd": "f8745da6ff1ad1e7bab384bd1f9d742439278e99", + "zlib": "12731092979c6d07f42da27da673a9f6c7b13586", + "os": "linux 7.0.0-30-generic", + "arch": "x64", + "cpu": "DO-Premium-Intel", + "cores": 8, + "memoryGiB": 15.6 + }, + "envelope": { + "magic": "NXS1", + "streamHeaderBytes": 16, + "frameHeaderBytes": 48 + }, + "policy": { + "minSavingsPercent": 3, + "minSavingsBytes": 512, + "maxBlockBytes": 262144, + "zstdLevels": [ + 1, + 3, + 9 + ] + }, + "samples": [ + { + "sample": "random-1mib", + "kind": "synthetic", + "inputBytes": 1048576, + "sha256": "562a223dca6ae12049e4e88ded6b6c0c7d18f29d5b941309fcd1f5cc19bc15b0", + "container": "bytes", + "rows": [ + { + "mode": "stored", + "level": 0, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 1048576, + "wireBytes": 1048832, + "storedBlocks": 4, + "compressedBlocks": 0, + "savingsPercent": -0.02, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "gzip", + "level": 6, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 1048576, + "wireBytes": 1048832, + "storedBlocks": 4, + "compressedBlocks": 0, + "savingsPercent": -0.02, + "encodeMs": 51.89, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 1, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 1048576, + "wireBytes": 1048832, + "storedBlocks": 4, + "compressedBlocks": 0, + "savingsPercent": -0.02, + "encodeMs": 7.69, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 3, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 1048576, + "wireBytes": 1048832, + "storedBlocks": 4, + "compressedBlocks": 0, + "savingsPercent": -0.02, + "encodeMs": 6.04, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 9, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 1048576, + "wireBytes": 1048832, + "storedBlocks": 4, + "compressedBlocks": 0, + "savingsPercent": -0.02, + "encodeMs": 8.08, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "ts-zstd", + "level": 1, + "blocks": 1, + "inputBytes": 1048576, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": 99.99, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": false, + "note": "not a transport stream: ts-zstd does not apply" + } + ], + "recommendation": { + "mode": "stored", + "level": 0, + "reason": "no codec beat stored by the configured margin" + } + }, + { + "sample": "zeros-1mib", + "kind": "synthetic", + "inputBytes": 1048576, + "sha256": "30e14955ebf1352266dc2ff8067e68104607e750abb9d3b36582b8af909fcb58", + "container": "bytes", + "rows": [ + { + "mode": "stored", + "level": 0, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 1048576, + "wireBytes": 1048832, + "storedBlocks": 4, + "compressedBlocks": 0, + "savingsPercent": -0.02, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "gzip", + "level": 6, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 1156, + "wireBytes": 1412, + "storedBlocks": 0, + "compressedBlocks": 4, + "savingsPercent": 99.87, + "encodeMs": 2.14, + "decodeMs": 5.25, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 1, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 116, + "wireBytes": 372, + "storedBlocks": 0, + "compressedBlocks": 4, + "savingsPercent": 99.96, + "encodeMs": 2.1, + "decodeMs": 6.9, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 3, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 116, + "wireBytes": 372, + "storedBlocks": 0, + "compressedBlocks": 4, + "savingsPercent": 99.96, + "encodeMs": 2.38, + "decodeMs": 4.25, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 9, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 112, + "wireBytes": 368, + "storedBlocks": 0, + "compressedBlocks": 4, + "savingsPercent": 99.96, + "encodeMs": 7.79, + "decodeMs": 5.76, + "roundTrip": true + }, + { + "mode": "ts-zstd", + "level": 1, + "blocks": 1, + "inputBytes": 1048576, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": 99.99, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": false, + "note": "not a transport stream: ts-zstd does not apply" + } + ], + "recommendation": { + "mode": "zstd", + "level": 9, + "reason": "saves 99.96% of the complete wire size" + } + }, + { + "sample": "text-repeat-1mib", + "kind": "synthetic", + "inputBytes": 1048576, + "sha256": "d05bf128d112bfd591628a68880676f643191beeb91d1250ce8c98212bf6e464", + "container": "bytes", + "rows": [ + { + "mode": "stored", + "level": 0, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 1048576, + "wireBytes": 1048832, + "storedBlocks": 4, + "compressedBlocks": 0, + "savingsPercent": -0.02, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "gzip", + "level": 6, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 6946, + "wireBytes": 7202, + "storedBlocks": 0, + "compressedBlocks": 4, + "savingsPercent": 99.31, + "encodeMs": 2.02, + "decodeMs": 4.48, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 1, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 324, + "wireBytes": 580, + "storedBlocks": 0, + "compressedBlocks": 4, + "savingsPercent": 99.94, + "encodeMs": 1.62, + "decodeMs": 12.04, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 3, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 318, + "wireBytes": 574, + "storedBlocks": 0, + "compressedBlocks": 4, + "savingsPercent": 99.95, + "encodeMs": 1.82, + "decodeMs": 3.89, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 9, + "blocks": 4, + "inputBytes": 1048576, + "payloadBytes": 316, + "wireBytes": 572, + "storedBlocks": 0, + "compressedBlocks": 4, + "savingsPercent": 99.95, + "encodeMs": 2.78, + "decodeMs": 3.18, + "roundTrip": true + }, + { + "mode": "ts-zstd", + "level": 1, + "blocks": 1, + "inputBytes": 1048576, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": 99.99, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": false, + "note": "not a transport stream: ts-zstd does not apply" + } + ], + "recommendation": { + "mode": "zstd", + "level": 9, + "reason": "saves 99.95% of the complete wire size" + } + }, + { + "sample": "ts-padded-50pct", + "kind": "synthetic", + "inputBytes": 752000, + "sha256": "fbbe8a14abcd5d36e40ccf8d5d80eca805580cccd632842a4f1cea9461863a6d", + "container": "mpegts", + "rows": [ + { + "mode": "stored", + "level": 0, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 752000, + "wireBytes": 752208, + "storedBlocks": 3, + "compressedBlocks": 0, + "savingsPercent": -0.03, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "gzip", + "level": 6, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 379358, + "wireBytes": 379566, + "storedBlocks": 0, + "compressedBlocks": 3, + "savingsPercent": 49.53, + "encodeMs": 13.4, + "decodeMs": 4.05, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 1, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 377821, + "wireBytes": 378029, + "storedBlocks": 0, + "compressedBlocks": 3, + "savingsPercent": 49.73, + "encodeMs": 3.59, + "decodeMs": 4.18, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 3, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 375595, + "wireBytes": 375803, + "storedBlocks": 0, + "compressedBlocks": 3, + "savingsPercent": 50.03, + "encodeMs": 5.7, + "decodeMs": 3.53, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 9, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 375109, + "wireBytes": 375317, + "storedBlocks": 0, + "compressedBlocks": 3, + "savingsPercent": 50.09, + "encodeMs": 17.19, + "decodeMs": 4.56, + "roundTrip": true + }, + { + "mode": "ts-zstd", + "level": 1, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 375481, + "wireBytes": 375689, + "storedBlocks": 0, + "compressedBlocks": 3, + "savingsPercent": 50.04, + "encodeMs": 9.3, + "decodeMs": 9.8, + "roundTrip": true + } + ], + "recommendation": { + "mode": "zstd", + "level": 9, + "reason": "saves 50.09% of the complete wire size" + } + }, + { + "sample": "ts-unpadded", + "kind": "synthetic", + "inputBytes": 752000, + "sha256": "675352f64a65d9ec2c3d7b69f11bb253cd882c3fcea85dd4a994675b5767c2c5", + "container": "mpegts", + "rows": [ + { + "mode": "stored", + "level": 0, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 752000, + "wireBytes": 752208, + "storedBlocks": 3, + "compressedBlocks": 0, + "savingsPercent": -0.03, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "gzip", + "level": 6, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 752000, + "wireBytes": 752208, + "storedBlocks": 3, + "compressedBlocks": 0, + "savingsPercent": -0.03, + "encodeMs": 26.52, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 1, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 752000, + "wireBytes": 752208, + "storedBlocks": 3, + "compressedBlocks": 0, + "savingsPercent": -0.03, + "encodeMs": 3.62, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 3, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 752000, + "wireBytes": 752208, + "storedBlocks": 3, + "compressedBlocks": 0, + "savingsPercent": -0.03, + "encodeMs": 8.11, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 9, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 752000, + "wireBytes": 752208, + "storedBlocks": 3, + "compressedBlocks": 0, + "savingsPercent": -0.03, + "encodeMs": 17.49, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "ts-zstd", + "level": 1, + "blocks": 3, + "inputBytes": 752000, + "payloadBytes": 752000, + "wireBytes": 752208, + "storedBlocks": 3, + "compressedBlocks": 0, + "savingsPercent": -0.03, + "encodeMs": 6.1, + "decodeMs": 0, + "roundTrip": true + } + ], + "recommendation": { + "mode": "stored", + "level": 0, + "reason": "no codec beat stored by the configured margin" + } + }, + { + "sample": "tiny-3b", + "kind": "synthetic", + "inputBytes": 3, + "sha256": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad", + "container": "bytes", + "rows": [ + { + "mode": "stored", + "level": 0, + "blocks": 1, + "inputBytes": 3, + "payloadBytes": 3, + "wireBytes": 115, + "storedBlocks": 1, + "compressedBlocks": 0, + "savingsPercent": -3733.33, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "gzip", + "level": 6, + "blocks": 1, + "inputBytes": 3, + "payloadBytes": 3, + "wireBytes": 115, + "storedBlocks": 1, + "compressedBlocks": 0, + "savingsPercent": -3733.33, + "encodeMs": 0.37, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 1, + "blocks": 1, + "inputBytes": 3, + "payloadBytes": 3, + "wireBytes": 115, + "storedBlocks": 1, + "compressedBlocks": 0, + "savingsPercent": -3733.33, + "encodeMs": 0.22, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 3, + "blocks": 1, + "inputBytes": 3, + "payloadBytes": 3, + "wireBytes": 115, + "storedBlocks": 1, + "compressedBlocks": 0, + "savingsPercent": -3733.33, + "encodeMs": 0.18, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 9, + "blocks": 1, + "inputBytes": 3, + "payloadBytes": 3, + "wireBytes": 115, + "storedBlocks": 1, + "compressedBlocks": 0, + "savingsPercent": -3733.33, + "encodeMs": 0.18, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "ts-zstd", + "level": 1, + "blocks": 1, + "inputBytes": 3, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": -2033.33, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": false, + "note": "not a transport stream: ts-zstd does not apply" + } + ], + "recommendation": { + "mode": "stored", + "level": 0, + "reason": "no codec beat stored by the configured margin" + } + }, + { + "sample": "empty", + "kind": "synthetic", + "inputBytes": 0, + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "container": "bytes", + "rows": [ + { + "mode": "stored", + "level": 0, + "blocks": 0, + "inputBytes": 0, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": 0, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "gzip", + "level": 6, + "blocks": 0, + "inputBytes": 0, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": 0, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 1, + "blocks": 0, + "inputBytes": 0, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": 0, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 3, + "blocks": 0, + "inputBytes": 0, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": 0, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "zstd", + "level": 9, + "blocks": 0, + "inputBytes": 0, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": 0, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + }, + { + "mode": "ts-zstd", + "level": 1, + "blocks": 0, + "inputBytes": 0, + "payloadBytes": 0, + "wireBytes": 64, + "storedBlocks": 0, + "compressedBlocks": 0, + "savingsPercent": 0, + "encodeMs": 0, + "decodeMs": 0, + "roundTrip": true + } + ], + "recommendation": { + "mode": "stored", + "level": 0, + "reason": "no codec beat stored by the configured margin" + } + } + ], + "summary": { + "corpusBytes": 4649731, + "byMode": [ + { + "mode": "stored", + "level": 0, + "wireBytes": 4651091, + "savingsPercent": -0.03, + "roundTrip": true, + "encodeMs": 0, + "decodeMs": 0 + }, + { + "mode": "gzip", + "level": 6, + "wireBytes": 2189399, + "savingsPercent": 52.91, + "roundTrip": true, + "encodeMs": 96.34, + "decodeMs": 13.78 + }, + { + "mode": "zstd", + "level": 1, + "wireBytes": 2180200, + "savingsPercent": 53.11, + "roundTrip": true, + "encodeMs": 18.84, + "decodeMs": 23.12 + }, + { + "mode": "zstd", + "level": 3, + "wireBytes": 2177968, + "savingsPercent": 53.16, + "roundTrip": true, + "encodeMs": 24.23, + "decodeMs": 11.67 + }, + { + "mode": "zstd", + "level": 9, + "wireBytes": 2177476, + "savingsPercent": 53.17, + "roundTrip": true, + "encodeMs": 53.51, + "decodeMs": 13.5 + }, + { + "mode": "ts-zstd", + "level": 1, + "wireBytes": 1127961, + "savingsPercent": 25, + "roundTrip": true, + "encodeMs": 15.4, + "decodeMs": 9.8 + } + ] + }, + "caveats": [ + "Envelope v1: a 16-byte stream header, a 48-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." + ] +} \ No newline at end of file diff --git a/docs/openstream/reports/2026-09-12-nixamp-0.17.1-synthetic.md b/docs/openstream/reports/2026-09-12-nixamp-0.17.1-synthetic.md new file mode 100644 index 0000000..f105b61 --- /dev/null +++ b/docs/openstream/reports/2026-09-12-nixamp-0.17.1-synthetic.md @@ -0,0 +1,38 @@ +# OpenStream benchmark — nixamp 0.17.1 + +Generated 2026-09-12T13:13:15.713Z · envelope NXS1 · schema 1 + +**Environment.** bun 1.4.0, zstd f8745da6ff1ad1e7bab384bd1f9d742439278e99, zlib 12731092979c6d07f42da27da673a9f6c7b13586, on linux 7.0.0-30-generic x64, 8× DO-Premium-Intel, 15.6 GiB. + +**Policy.** block 262144 B; eligible at 3% and 512 B; zstd levels 1, 3, 9. + +## Corpus + +| sample | kind | bytes | container | best mode | saves | +| --- | --- | ---: | --- | --- | ---: | +| random-1mib | synthetic | 1048576 | bytes | stored | stored | +| zeros-1mib | synthetic | 1048576 | bytes | zstd L9 | 99.96% | +| text-repeat-1mib | synthetic | 1048576 | bytes | zstd L9 | 99.95% | +| ts-padded-50pct | synthetic | 752000 | mpegts | zstd L9 | 50.09% | +| ts-unpadded | synthetic | 752000 | mpegts | stored | stored | +| tiny-3b | synthetic | 3 | bytes | stored | stored | +| empty | synthetic | 0 | bytes | stored | stored | + +## Aggregate, per mode across the corpus + +| mode | wire bytes | saving | enc ms | dec ms | round trip | +| --- | ---: | ---: | ---: | ---: | --- | +| stored | 4651091 | -0.03% | 0 | 0 | ok | +| gzip L6 | 2189399 | +52.91% | 96.34 | 13.78 | ok | +| zstd L1 | 2180200 | +53.11% | 18.84 | 23.12 | ok | +| zstd L3 | 2177968 | +53.16% | 24.23 | 11.67 | ok | +| zstd L9 | 2177476 | +53.17% | 53.51 | 13.5 | ok | +| ts-zstd L1 | 1127961 | +25% | 15.4 | 9.8 | ok | + +## Caveats + +- Envelope v1: a 16-byte stream header, a 48-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. diff --git a/docs/openstream/reports/README.md b/docs/openstream/reports/README.md new file mode 100644 index 0000000..b5ad561 --- /dev/null +++ b/docs/openstream/reports/README.md @@ -0,0 +1,26 @@ +# OpenStream benchmark reports + +Each file here is a reproducible run of the [OpenStream](../../openstream.md) benchmark: proof, on real hardware with recorded versions, that the envelope 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. The site renders them at `/docs/openstream/reports`. + +A report is two files sharing one id: + +- `.json` — the machine-readable report (canonical). Its `schema` field is the version of the shape below. +- `.md` — the same run rendered for reading, shown on the site. + +The id is `YYYY-MM-DD--[-]`, for example `2026-09-12-nixamp-0.17.1-synthetic`. Append the corpus label when the run used the built-in synthetic corpus rather than authorized real samples, so no one mistakes a padded-fixture number for a production one. + +## Publishing one + +The reference implementation emits both files: + +``` +nixamp compression benchmark --out . +``` + +writes `openstream-report.json` and `openstream-report.md`. Rename them to the id, drop them in this directory, and open a pull request. The command exits non-zero if any codec that applied failed to restore byte-for-byte, so a report that would not build is caught before it is committed. + +**A report is published with every release** of a reference implementation. The release step runs the benchmark, commits the two files here, and the site picks them up on its next deploy. Prefer a run over authorized real samples (`--corpus DIR`); a synthetic run is acceptable as a floor but is labelled as such and is not evidence of production savings. + +## What the numbers mean, and do not + +OpenStream is a framing envelope over Zstandard and gzip, not a new compression algorithm. A report measures those codecs at the block boundary, framed honestly. Read the `caveats` array in every report: a synthetic padded transport stream saves about its padding share and says more about the padding than the codec; an efficient real feed saves little; timings are for the one machine named in `environment`. The one number that is a pass/fail rather than a measurement is round-trip exactness, and it must hold for every applicable codec on every sample.