# KI-027 Persisted Rebuild Manifest Plan

This plan closes the repeated-build failure where replacing `main.pggraph`
leaves the active mutable-projection manifest bound to the previous base
checksum.

## Invariants

- A successful persisted build publishes a new base-only projection generation
  whose path, format version, checksum, and sync watermark describe the newly
  written graph artifact.
- The new generation is monotonic, links to the prior generation, and carries
  forward operation timestamps used by status and maintenance.
- Segments, identity dictionaries, and base chunks superseded by the rebuild
  are declared obsolete for generation-aware garbage collection; the active
  base artifact is never marked obsolete.
- The rebuilt artifact is not loaded through a stale manifest. Manifest rebasing
  occurs after the artifact is fsynced and before mmap reload validation.
- Build, vacuum, recovery, and repeated-build paths share one rebasing helper
  and cannot publish duplicate generation identifiers.
- This checkpoint does not claim the final generation-specific base-artifact
  switch required by KI-018. A process crash between base replacement and
  manifest publication remains tracked there and must be closed before 1.0.

## Ordered Checkpoints

1. Add a projection recovery helper that derives the next generation, creates
   a base-only manifest for the current artifact, preserves status timestamps,
   and records superseded projection files.
2. Call the helper from persisted build/vacuum before mmap reload, and reconcile
   the full-recovery path so it does not publish a second generation.
3. Add unit coverage for checksum rebasing, generation linkage, obsolete-file
   accounting, and base-only reload.
4. Make the persisted two-session isolation matrix pass repeated builds and
   retain matching source/projection visibility.
5. Update public upgrade, sync, known-issue, and release documentation without
   overstating crash-atomic publication guarantees.

## Exit Evidence

- [x] Two consecutive persisted mutable builds load successfully with the
  latest manifest checksum matching `main.pggraph`.
- [x] Superseded projection artifacts remain protected by retained generations
  and become eligible for bounded garbage collection only under existing pin
  and retention rules.
- [x] The persisted READ COMMITTED, REPEATABLE READ, and SERIALIZABLE matrix is
  green on PostgreSQL 17.
- [x] Independent Rust review reports no KI-027 blocker.