fix(generations): a sealed segment may only declare the generations it holds

Diagnosis of the "packed history is damaged" narration that fires on every
run of the affected stores. It is a WRITER defect, and the reader's refusal
was the symptom rather than the cause.

A sealed segment declares one contiguous range [firstGeneration,
lastGeneration], and every reader treats that range as containment:
coveringSegment is an interval test, hasGeneration returns true for anything
inside it, and open() seeds committedRanges from it.

repackHistory handed fold() a SPARSE batch. Three filters punch holes in its
candidate list mid-run — a generation absent from committedRanges never
appears, one still in the pending buffer is skipped, one whose tx.json will
not read is skipped — and fold() then computed the range from the first and
last survivor, claiming every generation in between. The next open merged
that mis-declared range back into committedRanges, re-admitting the hole as
committed history, so the following auto-compaction pass asked the packed
tier for a frame that was never written and failed. Re-merged at every open,
which is why it repeated on every run.

Confirmed against a forensic fixture: generation directories 1..2503 present
except exactly one, 1416; and its fact-log segment already showed the tell —
seg-...1410.bfl declaring 1410..1940 (531 generations) while recording 530
facts.

Three changes:

  - repackHistory folds each contiguous RUN as its own segment
    (`contiguousRuns`), so ranges describe exactly what the segments contain.
  - fold() REFUSES a non-contiguous batch, naming the gap and its width. The
    density law is now mechanical, so no future caller can reintroduce it. A
    refusal loses nothing: the generations stay live and readable.
  - Stores already carrying the damage heal instead of wedging. A segment
    whose declared span exceeds its frame count is SPARSE; `actualRanges()`
    reads the real generation list from its sidecar so open() never re-admits
    the holes, and readFrame reports such a hole as unpacked with a narration
    naming the segment, rather than throwing. A DENSE segment missing a frame
    is still loud damage — that one means the manifest and sidecar disagree.

Pins: nine unit cases (refusal and its message, honest ranges for separately
folded runs, a reconstructed pre-fix sparse segment serving its real frames
while reporting holes as unpacked, holes excluded from actualRanges, and the
dense-segment damage path still throwing) plus an end-to-end case that
deletes a generation directory and drives the real sequence — ordinary
close()-time repacking folds over the hole, then reopen and compact must both
complete. Verified red without the fix: the segment declared an
11-generation span while holding 10 frames.

src/db/generationSegments.ts

@@ -147,6 +147,60 @@ export class GenerationSegmentStore {
     return this.coveringSegment(gen) !== null
   }
 
+  /**
+   * @description True when `meta` declares more generations than it holds
+   * frames — a segment sealed by a writer that folded across a hole. The
+   * manifest records `frames` at fold time, so this is an O(1) comparison
+   * against the declared span and needs no I/O.
+   */
+  private isSparse(meta: SegmentMeta): boolean {
+    return meta.lastGeneration - meta.firstGeneration + 1 !== meta.frames
+  }
+
+  /**
+   * @description The generations this tier ACTUALLY holds, as coalesced
+   * ascending intervals — not what the segments declare.
+   *
+   * Dense segments (every one a current writer produces) contribute their
+   * declared range with no I/O. A SPARSE segment — one sealed before the
+   * density law was enforced, whose declared range spans generations it has
+   * no frame for — has its real generation list read from its sidecar and
+   * contributed instead, with the discrepancy narrated once.
+   *
+   * This is what keeps a store that already carries the damage from wedging.
+   * `open()` seeds `committedRanges` from these intervals, so a hole is never
+   * re-admitted as a committed generation, and the auto-compaction pass that
+   * used to fail on every run with "packed history is damaged" simply never
+   * asks for the missing frame.
+   *
+   * @returns Ascending, non-overlapping `[first, last]` intervals.
+   */
+  async actualRanges(): Promise<Array<[number, number]>> {
+    const out: Array<[number, number]> = []
+    for (const meta of this.manifest.segments) {
+      if (!this.isSparse(meta)) {
+        out.push([meta.firstGeneration, meta.lastGeneration])
+        continue
+      }
+      const missing = meta.lastGeneration - meta.firstGeneration + 1 - meta.frames
+      prodLog.warn(
+        `[GenerationSegments] sealed segment ${meta.file} declares generations ` +
+          `${meta.firstGeneration}..${meta.lastGeneration} but holds only ${meta.frames} ` +
+          `frame(s) — ${missing} generation(s) in that span were never folded into it. ` +
+          `Serving the frames it actually holds; the declared span is not treated as ` +
+          `committed history. (Written by a pre-density-law writer that folded across a ` +
+          `gap; the segment itself is intact and no record is lost.)`
+      )
+      const idx = await this.sidecarFor(meta)
+      for (const [gen] of idx.generations) {
+        const last = out[out.length - 1]
+        if (last !== undefined && gen === last[1] + 1) last[1] = gen
+        else out.push([gen, gen])
+      }
+    }
+    return out
+  }
+
   /**
    * Fold consecutive generations into ONE new sealed segment + sidecar and
    * append it to the manifest atomically. Caller guarantees: `gens` is
@@ -164,6 +218,38 @@ export class GenerationSegmentStore {
         throw new Error('[GenerationSegments] fold() input must be strictly ascending')
       }
     }
+    // THE DENSITY LAW, MADE MECHANICAL.
+    //
+    // A sealed segment declares a CONTIGUOUS range [firstGeneration,
+    // lastGeneration] and every reader treats that range as containment:
+    // `coveringSegment` is an interval test, `hasGeneration` returns true for
+    // anything inside it, and `open()` seeds committedRanges from it. So a
+    // segment folded from a SPARSE input silently claims generations it does
+    // not hold, and the first read of one of those holes throws
+    // "inside sealed segment ... but has no frame — packed history is damaged".
+    //
+    // That is exactly how the damage was produced. `repackHistory` skipped
+    // generations mid-batch — ones absent from committedRanges, ones still in
+    // the pending buffer, ones whose tx.json would not read — and handed the
+    // survivors here, where the range was computed from the first and last of
+    // them. Worse, the mis-declared range was then merged back into
+    // committedRanges at the next open, which is what turned a quiet hole into
+    // a repeating auto-compaction failure on every subsequent run.
+    //
+    // Callers now split at discontinuities; this refusal is what keeps any
+    // future caller from reintroducing the class. A refusal here loses
+    // nothing — the generations stay in the live tier, readable, and the next
+    // pass folds them correctly.
+    for (let i = 1; i < gens.length; i++) {
+      if (gens[i].generation !== gens[i - 1].generation + 1) {
+        throw new Error(
+          `[GenerationSegments] fold() input is not contiguous: ${gens[i - 1].generation} → ` +
+            `${gens[i].generation} skips ${gens[i].generation - gens[i - 1].generation - 1} ` +
+            `generation(s). A sealed segment declares a dense range, so folding a sparse ` +
+            `batch would claim generations it does not hold. Split the batch at the gap.`
+        )
+      }
+    }
     const last = this.manifest.segments[this.manifest.segments.length - 1]
     if (last && gens[0].generation <= last.lastGeneration) {
       throw new Error(
@@ -364,12 +450,37 @@ export class GenerationSegmentStore {
         return this.decodeFrame(payload)
       }
     }
-    // In the covering range but not present: the packed tier is dense by
-    // construction (fold packs every generation it is handed, including
-    // record-less ones) — absence inside a sealed range is damage.
+    // Inside the covering range but with no frame. Two very different causes,
+    // and conflating them is what made this class wedge every maintenance pass
+    // on the affected stores.
+    //
+    // (1) A SPARSE SEGMENT — the manifest's own `frames` count is smaller than
+    //     the span it declares. That segment was sealed by a writer that
+    //     folded across a hole (the class this file's density law now bars).
+    //     The segment is INTACT and nothing is lost; it simply never held this
+    //     generation. Answering "not packed" is the honest answer, and it lets
+    //     the caller's two-tier read decide what a genuinely absent generation
+    //     means, instead of every compaction pass dying on a repeating throw.
+    //     `actualRanges()` keeps such holes out of committedRanges at open, so
+    //     in a healed store nobody asks this question in the first place.
+    //
+    // (2) A DENSE SEGMENT missing a frame it says it has — the manifest and
+    //     the sidecar disagree about a segment that claims to be complete.
+    //     That IS damage, and it stays loud.
+    if (this.isSparse(meta)) {
+      prodLog.warn(
+        `[GenerationSegments] generation ${gen} falls inside sealed segment ${meta.file}'s ` +
+          `declared range ${meta.firstGeneration}..${meta.lastGeneration}, but that segment ` +
+          `holds ${meta.frames} frame(s) for a ${meta.lastGeneration - meta.firstGeneration + 1}` +
+          `-generation span — it was sealed across a gap and never held this generation. ` +
+          `Reporting it as unpacked rather than as damage; no record is lost.`
+      )
+      return null
+    }
     throw new Error(
       `[GenerationSegments] generation ${gen} is inside sealed segment ${meta.file}'s declared ` +
-        `range but has no frame — packed history is damaged`
+        `range but has no frame, and that segment declares a complete ${meta.frames}-frame ` +
+        `span — the manifest and the sidecar disagree; packed history is damaged`
     )
   }