Preserve Aggregation Invariants

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