verifyIndexIntegrity method

void verifyIndexIntegrity()

Verifies that kSeatMemoryFileName COVERS this disc: every persistent note is named by exactly one pointer line, and every pointer line names a file that is here. Returns normally when it does; throws one SeatDiscIntegrityException naming EVERY offender when it does not.

Why this exists. A disc note is findable only through the index — it is the one file loaded wholesale, and the notes load on relevance — so an index that stops naming a note retires it in silence. Observed 2026-09-12 on the live governor disc: a seat banking ONE lesson rewrote its own index wholesale instead of appending, and the file went from seventy-seven pointer lines to one. Eighty-one markdown files stayed on the disc; the index named two. Nothing failed, nothing warned, and it was found by accident four hours later.

This is a CHECK and never a writer (power_station#seat-disc-index-integrity-is-checked-not-written): it reports after the fact, which is why it catches a wholesale rewrite, a hand edit and a bad merge alike, and it never repairs the index. It creates, appends to, renames and deletes NOTHING.

A kind: handoff note is exempt from the coverage count: a handoff is consumed rather than kept, so it is indexed for exactly one succession and SeatSuccessionService is what holds it to one pointer line at the moment it consumes it. An absent index is EMPTY, not an error — a disc that holds only a handoff, or nothing at all, verifies.

Implementation

void verifyIndexIntegrity() {
  final memoryFile = File(p.join(directory, kSeatMemoryFileName));
  final memory = memoryFile.existsSync() ? memoryFile.readAsStringSync() : '';

  final unindexed = <String>[];
  final multiplyIndexed = <String>[];
  final dir = Directory(directory);
  if (dir.existsSync()) {
    for (final file in dir.listSync().whereType<File>()) {
      final name = p.basename(file.path);
      if (p.extension(name) != '.md' || name == kSeatMemoryFileName) continue;
      final handoff = parseSeatHandoff(
        path: file.path,
        relativePath: p.relative(file.path, from: gridHome),
        contents: file.readAsStringSync(),
      );
      if (handoff != null) continue;
      final pointers = memoryPointerLines(memory: memory, target: name);
      if (pointers.isEmpty) unindexed.add(name);
      if (pointers.length > 1) multiplyIndexed.add(name);
    }
  }

  final missing = <String>[
    for (final target in _inlineLinkTargets(memory))
      if (!_pointsAtANoteHere(target)) target,
  ];

  if (unindexed.isEmpty && missing.isEmpty && multiplyIndexed.isEmpty) return;
  throw SeatDiscIntegrityException(
    directory: directory,
    unindexedFiles: unindexed,
    missingTargets: missing,
    multiplyIndexedFiles: multiplyIndexed,
  );
}