jetstream v2 in zig stream.waow.tech

docs: timestamp import never explained which timestamp, or why that is safe master

The opening sentence distinguishes "the timestamp presented to subscribers" from "the immutable witness timestamp" and then never returns to it, though the entire design turns on that split. Added a table naming both (display/time_us, changed by an import; witness/witnessed_at, never) and what each is used for. The part worth stating is why the separation exists rather than that it does: witnessed_at defines segment ordering and is what a ?cursor=<microseconds> replay resolves against, so if an import could move it, every sealed segment header range and every timestamp cursor would become wrong and the "segments sort in creation order, and that order is time order" invariant in invariants.md would break. An import is a presentation layer over immutable history, not a rewrite. Also named the operator use case -- backfilled or migrated content whose real creation time predates when this instance first saw it. Verified rather than assumed: both flags exist in runtime/cli.zig and both XRPC routes are in serve/server.zig. Noted that the routes are matched as full literal /xrpc/... paths, so grepping for the bare NSID finds nothing -- which is how I briefly convinced myself they were missing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>


+27
1 changed file