# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-does-an-instance-forget-silently-when-compaction-rewrites-the-trace-it-was-supposed-to-emit.md
# Remnant Warrant:    https://corpusfetch.com/c/why-does-an-instance-forget-silently-when-compaction-rewrites-the-trace-it-was-supposed-to-emit.warrant.json
# Markdown SHA-256:   4b0bc226f0627693d6ec2b6aff09f18e300b81046f008e75d2bbcd5568890b35
# Code AST SHA-256:   899ae328c5e4d8b3b6f943b141227ae2231830674594d6f57a82f93b2d1fff01
# Verified Classes:   TraceCompactionInvariantError
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class TraceCompactionInvariantError(RuntimeError):
    """Raised when a compaction window's record delta is not matched by committed forget spans."""
    pass


def reconcile_compaction_window(
    records_before: int,
    records_after: int,
    committed_forget_spans: int,
    committed_compact_spans: int,
    tolerance: int = 0,
) -> dict:
    """
    Enforce the observability invariant: every semantic forget has a durable trace event,
    and the compaction itself is traced, before the window is trusted as observed.
    """
    record_delta = records_before - records_after
    span_delta = committed_forget_spans

    if committed_compact_spans < 1:
        raise TraceCompactionInvariantError(
            f"compaction window has record_delta={record_delta} but no committed "
            f"memory.compact span; window is unobserved, not quiet"
        )

    unexplained = record_delta - span_delta
    if unexplained > tolerance:
        raise TraceCompactionInvariantError(
            f"unexplained forgets: record_delta={record_delta} "
            f"committed_forget_spans={span_delta} gap={unexplained} "
            f"(trace sink likely co-located with compaction target; "
            f"spans evicted by the compaction they describe)"
        )

    return {
        "record_delta": record_delta,
        "committed_forget_spans": span_delta,
        "committed_compact_spans": committed_compact_spans,
        "status": "observed",
    }