# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-compaction-aware-context-delta-reconstruction-as-unsound-and-how-is-the-boundary-detected-before-a-trace.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-compaction-aware-context-delta-reconstruction-as-unsound-and-how-is-the-boundary-detected-before-a-trace.warrant.json
# Markdown SHA-256:   733b8322034e37161454d2e4b248e44fed9de53fe9c43753571e6feff50a3a45
# Code AST SHA-256:   308c7391420f429904024d2e5384a2397ae2bbe08ad1961d5d69e334d908c84d
# Verified Classes:   UnsoundReconstructionError, DeltaRecord, CompactionWatermark
# Defensive Guards:   6 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Sequence, Optional


class UnsoundReconstructionError(RuntimeError):
    """Raised when a context-delta trace cannot be proven continuous across compaction."""
    pass


@dataclass(frozen=True)
class DeltaRecord:
    seq: int
    payload: dict
    is_net_delta: bool = False
    net_lo: Optional[int] = None
    net_hi: Optional[int] = None


@dataclass(frozen=True)
class CompactionWatermark:
    # Highest seq below which records may have been physically reclaimed.
    reclaimed_below: int


def reconstruct_context(
    records: Sequence[DeltaRecord],
    start_seq: int,
    end_seq: int,
    watermark: CompactionWatermark,
) -> dict:
    """
    Reconstruct request context from a delta chain, refusing to splice gaps.
    Returns a context dict annotated with explicit gap markers.
    """
    if not records:
        raise UnsoundReconstructionError("empty delta chain; cannot reconstruct")

    ordered = sorted(records, key=lambda r: r.seq)

    # Condition 3: requested start must not precede the reclaimed watermark.
    if start_seq < watermark.reclaimed_below:
        raise UnsoundReconstructionError(
            f"start_seq={start_seq} precedes compaction watermark "
            f"{watermark.reclaimed_below}; continuity proof was reclaimed"
        )

    # Condition 1: chain must begin exactly at requested start.
    if ordered[0].seq != start_seq:
        raise UnsoundReconstructionError(
            f"chain begins at seq {ordered[0].seq}, expected {start_seq}"
        )

    context: dict = {}
    gaps: list[tuple[int, int]] = []

    for prev, cur in zip(ordered, ordered[1:]):
        expected = prev.seq + (prev.net_hi - prev.net_lo if prev.is_net_delta and prev.net_hi is not None and prev.net_lo is not None else 0) + 1
        if cur.seq != expected:
            # A discontinuity: record it rather than splicing silently.
            gaps.append((prev.seq, cur.seq))
            if not cur.is_net_delta:
                raise UnsoundReconstructionError(
                    f"unmarked seq gap between {prev.seq} and {cur.seq}; "
                    f"cannot prove continuity (compaction likely merged records)"
                )

    for rec in ordered:
        if rec.is_net_delta:
            if rec.net_lo is None or rec.net_hi is None:
                raise UnsoundReconstructionError(
                    f"net-delta at seq {rec.seq} missing interval bounds"
                )
            context.setdefault("__net_deltas__", []).append(
                {"lo": rec.net_lo, "hi": rec.net_hi, "payload": rec.payload}
            )
        else:
            context.update(rec.payload)

    if ordered[-1].seq != end_seq and not ordered[-1].is_net_delta:
        raise UnsoundReconstructionError(
            f"chain ends at seq {ordered[-1].seq}, expected {end_seq}"
        )

    context["__gaps__"] = gaps
    context["__sound__"] = len(gaps) == 0
    return context
