When transforming/aggregating streamed or ranged data, explicitly define the invariants your algorithm depends on (index meaning, ownership/copy semantics, boundary semantics, and ordering), then implement collision- and edge-case-safe logic with targeted tests.
Practical rules:
1) Specify index/span semantics and keep them consistent across paths.
- If downstream expects character offsets, don’t silently pass byte offsets; document and align conversions.
2) Make boundary/range aggregation match the “exact predicate” semantics of the raw path.
- If using pre-aggregated/materialized views, split the window into interior vs boundary buckets so first/last bars count only in-window rows.
3) Enforce collision-safe dedup/remapping in stream accumulators.
- Terminal/final markers are common collision points; reserve remapped indices deterministically on first final delivery and only remap on genuine collisions.
4) Prevent unintended aliasing in accumulators/transform layers.
- Clone slices/maps that might be mutated later; keep other fields shallow only when you can prove they’re immutable.
5) Preserve deterministic ordering when output bytes matter.
- Avoid Go map re-marshaling with sorted keys when providers expect literal key order; use ordered data structures and lock it with tests.
Collision-safe terminal-chunk handling (adapted from the discussed fix):
if isFinalChunk && chunk.StreamResponse != nil {
if acc.TerminalResponseChunkIndex >= 0 {
chunk.ChunkIndex = acc.TerminalResponseChunkIndex
} else {
if chunk.ChunkIndex <= acc.MaxResponsesChunkIndex {
acc.MaxResponsesChunkIndex++
chunk.ChunkIndex = acc.MaxResponsesChunkIndex
}
acc.TerminalResponseChunkIndex = chunk.ChunkIndex
}
}
Test guidance:
- Add edge-case tests that reflect the violated invariants (e.g., monotonic streams where the final chunk arrives twice; mixed reasoning blocks where indices must not collapse; boundary histogram windows that split across the first/last bucket).