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