bbs.profullstack/logicsrc
1
0
Fork 0
mirror of https://github.com/profullstack/logicsrc.git synced 2026-10-01 20:33:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

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

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

6
docs/openstream.md
View file

@ -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.