From 763f7c3e8478e897ff89e06f19d3db34efa12d80 Mon Sep 17 00:00:00 2001 From: zzstoatzz Date: Thu, 30 Jul 2026 06:13:10 -0500 Subject: [PATCH] docs: the two jss format specs pin a different upstream commit than the rest jss-format-v1.md and jss-seal-spec.md are pinned to upstream 0c45f29. Every other doc that cites upstream -- semantic-parity, upstream-bootstrap-spec, configuration-parity, upstream-harness, bootstrap-semantic-parity, opentelemetry, grafana-dashboard -- pins f29815c391fc2644f8a3dd36b899fb3697dd1ea6. Seven against two, with no explanation on either side. Nothing is known to be wrong: every constant in the file was checked against storage/segment.zig and matches -- magic "jss0", header_size 256, the four reader sanity caps (1<<18, 1<<20, 1<<20, 1<<30), 4096 events/block. Recorded that verification inline with its date. But this is a byte-exact wire contract, so an unexplained pin fork is worth resolving on purpose rather than inheriting. Deciding which commit is right means reading upstream at both, which cannot be done from this repository, so the discrepancy is flagged rather than guessed at. Also marks the segment/*.go paths and the docs/README.md 3.1-3.4 citation as upstream's, consistent with the other upstream specs. I passed jss-seal-spec.md first this session and missed the shared pin then. Co-Authored-By: Claude Opus 5 (1M context) --- docs/jss-format-v1.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/jss-format-v1.md b/docs/jss-format-v1.md index bc509a8..592d42f 100644 --- a/docs/jss-format-v1.md +++ b/docs/jss-format-v1.md @@ -1,9 +1,29 @@ # jss sealed segment format v1 (byte-exact, from upstream source @ 0c45f29) -condensed from `bluesky-social/jetstream` `segment/*.go` + docs/README.md §3.1–3.4 (2026-07-08). +condensed from `bluesky-social/jetstream` `segment/*.go` + §3.1–3.4 of upstream's +`docs/README.md` (2026-07-08). **Those are upstream Go paths and upstream's +README — neither is in this repository.** this format is wire-visible contract (getSegment/getBlock serve raw bytes) — implement as-specified. all integers little-endian, all offsets absolute. extension `.jss`. +> **This file pins a different upstream commit than the rest of the docs.** The +> title says `0c45f29`; `semantic-parity.md`, `upstream-bootstrap-spec.md`, +> `configuration-parity.md`, `upstream-harness.md`, +> `bootstrap-semantic-parity.md`, `opentelemetry.md` and +> `grafana-dashboard.md` all pin `f29815c391fc2644f8a3dd36b899fb3697dd1ea6`. +> `jss-seal-spec.md` is the only other file on `0c45f29`. +> +> Nothing here is known to be wrong — every constant below was checked against +> `storage/segment.zig` and matches — but for a *byte-exact wire contract* the +> discrepancy is worth resolving deliberately rather than leaving as an +> unexplained fork. Either the format was audited earlier and never re-checked +> against `f29815c`, or `0c45f29` is a stale hash. Confirming which requires +> reading upstream at both commits; it is not decidable from this repository. + +Verified against `storage/segment.zig` on 2026-07-30: magic `"jss0"`, +`header_size = 256`, the four reader sanity caps (`1 << 18`, `1 << 20`, +`1 << 20`, `1 << 30`), and 4096 events/block all match the values below. + ## constants - magic `"jss0"`; header 256 bytes; header version 1 - block index entry 52 bytes; default 4096 events/block -- 2.51.2