Add QIHSE compaction recovery coverage

Author: john

plans/qihse_persistence_layer.md

@@ -13,9 +13,9 @@ Current landed state:
 - PR-2 is complete for the planned WAL structure: file-backed adds write ADD and COMMIT WAL records, records carry previous-record offsets, open replays committed batches newer than the snapshot, and writable open truncates torn or uncommitted WAL tails.
 - PR-3 read-only mmap candidate work now covers `vectors.qvec`, `metadata.qmeta`, validated `idmap.qid`, and validated direct mapping of `index.qidx` for clean snapshots.
 - PR-4 physical compaction is complete for the current row model: `compact()` rewrites the in-memory table, vector blob, and metadata arena with live rows only, then publishes the compact snapshot and regenerated `idmap.qid`/`vectors.qtri` through the existing atomic flush path.
-- PR-4 compaction fixtures now verify compact-after-mutation row/index/idmap/trinary behavior, high-ID idmap consistency, and stale/corrupt derived sidecar rebuild.
+- PR-4 compaction fixtures now verify compact-after-mutation row/index/idmap/trinary behavior, high-ID idmap consistency, stale/corrupt derived sidecar rebuild, stale `.tmp` file ignore-on-open behavior, and WAL mutation compaction clearing WAL without resurrecting pruned rows.
 - PR-5 search-path benchmark scaffolding is present: `make bench-trinary-search-path` compares full float32 DB search against DB-backed `vectors.qtri` candidate selection plus exact float32 rerank and reports recall/order/latency. Pure trinary storage remains out of scope.
-- Latest pushed checkpoint before this slice: `7df0e3e` on `codex/qihse-file-persistence`.
+- Latest pushed checkpoint before this slice: `b8a37a3` on `codex/qihse-file-persistence`.
 
 Resume commands:
 
@@ -45,15 +45,15 @@ trinary_search_path_bench rows=2048 dims=64 qtri_row_bytes=13 candidates=64 topk
 Current continuation:
 
 - PR-3: validate the newly landed `index.qidx` mmap path under more corruption and compatibility cases, then decide whether UMA should wrap mapped rows directly or keep the current vector DB-owned mapping path.
-- PR-4: add compaction crash/recovery fixtures around tmp files, manifest publication, and WAL-plus-compaction interactions. Public mutation APIs, mutation WAL replay/truncation, and physical compaction are present.
+- PR-4: add deeper manifest-publication crash fixtures if needed. Public mutation APIs, mutation WAL replay/truncation, physical compaction, stale temp-file handling coverage, and WAL-plus-compaction interaction coverage are present.
 - PR-5: use the search-path benchmark to drive optional vector DB trinary acceleration. Current benchmark proves recall/order on the synthetic fixture and exposes latency variance; it is not yet a production search-path optimization.
 - PR-6: add persisted anchor hints and optimizer statistics only as rebuildable, explicit-format sidecars.
 
 Recommended 3-agent split:
 
-- Agent 1 owns PR-4 compaction crash/recovery fixtures.
-- Agent 2 owns WAL-plus-compaction interaction tests and any recovery fixes they expose.
-- Agent 3 owns PR-5 optional search-path acceleration and broader recall/performance datasets.
+- Agent 1 owns any remaining manifest-publication crash fixtures.
+- Agent 2 owns PR-5 optional search-path acceleration wiring.
+- Agent 3 owns broader recall/performance datasets for trinary candidate generation.
 
 ## 1. Background
 

plans/qihse_persistence_pr0_pr1_enhancement.md

@@ -29,9 +29,9 @@ Current implementation state:
 - PR-2 WAL/recovery hardening is implemented for ADD/COMMIT records, previous-record offsets, committed-batch replay, and writable torn-tail truncation.
 - PR-3 candidate work has started: read-only mmap mode maps `vectors.qvec`, `metadata.qmeta`, validated `idmap.qid`, and validated direct `index.qidx` rows for clean snapshots.
 - PR-4 physical compaction is present: delete/update/upsert API symbols write committed WAL records, replay committed mutation batches newer than the snapshot, writable open truncates torn/uncommitted mutation tails, and `compact()` rewrites live rows only before publishing the regenerated snapshot/sidecars.
-- PR-4 compaction fixture coverage now enforces row/index/live/idmap counts after physical pruning, high unsigned IDs, valid `vectors.qtri` after compact, and stale/corrupt derived sidecar rebuild.
+- PR-4 compaction fixture coverage now enforces row/index/live/idmap counts after physical pruning, high unsigned IDs, valid `vectors.qtri` after compact, stale/corrupt derived sidecar rebuild, stale `.tmp` file ignore-on-open behavior, and WAL mutation compaction clearing WAL without resurrecting pruned rows.
 - PR-5 search-path benchmark scaffolding is present: standalone tryte top-k exists with `make bench-trinary-codec`, DB-backed candidate generation plus exact float32 rerank exists with `make bench-trinary-db-candidate`, and `make bench-trinary-search-path` compares full float32 DB search against trinary candidates plus rerank with recall/order/latency reporting.
-- Latest pushed checkpoint before this slice: `7df0e3e` on `codex/qihse-file-persistence`.
+- Latest pushed checkpoint before this slice: `b8a37a3` on `codex/qihse-file-persistence`.
 - `qihse/qihse_vector_db.c` was restored after a disk-full truncation and now contains the native persistence implementation.
 - `qihse_vector_db_create(..., db_path)` opens a file-backed native database.
 - `qihse_vector_db_open()` supports ephemeral, file-copy, read-only, and read-only mmap modes.
@@ -545,22 +545,22 @@ PR-1 is complete when:
 - Read-only open can search but cannot mutate.
 - Native persistence diagnostics report generation, storage mode, ID-map rebuild state, and trinary sidecar status.
 - Python has not implemented any storage format.
-- Writable mmap, production vector DB trinary acceleration, pure trinary storage, compaction crash fixtures, and anchor persistence are still deferred.
+- Writable mmap, production vector DB trinary acceleration, pure trinary storage, deeper manifest-publication crash fixtures, and anchor persistence are still deferred.
 
 ## Follow-On Phases
 
 After the current checkpoint:
 
 - PR-3: harden mmap compatibility and corruption tests now that read-only `vectors.qvec`, `metadata.qmeta`, `idmap.qid`, and `index.qidx` mapping are present for clean snapshots.
-- PR-4: public delete/update/upsert API behavior, mutation WAL replay/truncation, and physical tombstone compaction are implemented and covered by persistence tests. Compaction crash/recovery fixtures remain.
+- PR-4: public delete/update/upsert API behavior, mutation WAL replay/truncation, physical tombstone compaction, stale temp-file ignore behavior, and WAL-plus-compaction interactions are implemented and covered by persistence tests. Deeper manifest-publication crash fixtures can still be added.
 - PR-5: DB-backed candidate generation, exact rerank, and search-path benchmark scaffolding are present; production search-path acceleration, broader recall measurement, and optional pure trinary storage remain.
 - PR-6: optional persisted anchor hints and optimizer statistics as rebuildable sidecars.
 
 ## PR-4: Mutation and Compaction Plan
 
 PR-4 should make mutation explicit without changing QIHSE's program boundary. The public contract belongs to native QIHSE; Framewerx and other callers remain clients.
 
-Status: the public delete/update/upsert declarations are staged in `qihse/qihse_vector_db.h` and the native implementation is present in `qihse/qihse_vector_db.c`. Executable tests now cover delete, update, upsert, read-only rejection, compact-after-mutation search correctness, unflushed mutation WAL replay, and physical compact row pruning.
+Status: the public delete/update/upsert declarations are staged in `qihse/qihse_vector_db.h` and the native implementation is present in `qihse/qihse_vector_db.c`. Executable tests now cover delete, update, upsert, read-only rejection, compact-after-mutation search correctness, unflushed mutation WAL replay, physical compact row pruning, stale compact temp files, and WAL mutation compaction.
 
 ### Public API
 
@@ -704,23 +704,21 @@ The persistence test file carries a compile-safe TODO backlog for these cases. C
 
 Use this split when resuming the remaining plan with multiple agents. QIHSE remains its own native program; none of these tasks should introduce Framewerx-specific persistence behavior.
 
-Agent 1: PR-4 compaction crash fixtures.
+Agent 1: PR-4 manifest-publication crash fixtures.
 
-- Add tmp-file and manifest-publication crash/recovery fixtures around compact.
+- Add deeper manifest-publication crash/recovery fixtures around compact if the current atomic helper is extended to support injection.
 - Verify old generation remains authoritative when compact publication is incomplete.
 - Verify derived sidecars rebuild after compact interruption.
 - Keep compaction manual until stats-driven thresholds exist.
 
-Agent 2: PR-4 WAL-plus-compaction fixtures.
+Agent 2: PR-5 search-path trinary acceleration.
 
-- Add WAL-plus-compaction interaction tests.
-- Verify committed mutation WAL replay before compact, compact clearing checkpointed WAL, and no resurrection of pruned rows.
-- Fix any recovery bugs exposed by those tests.
-- Keep derived sidecar rebuild behavior explicit.
+- Wire the benchmarked qtri candidate path into optional vector DB search behavior.
+- Keep exact float32 rerank as the correctness boundary.
+- Preserve `vectors.qvec` as authoritative storage.
 
-Agent 3: PR-5 search-path trinary acceleration.
+Agent 3: PR-5 recall/performance dataset expansion.
 
-- Use the search-path benchmark to guide optional vector DB search acceleration.
 - Add broader recall/performance datasets beyond the synthetic fixture.
 - Keep reporting speed honestly; the current benchmark proves recall/order but not consistent speedup.
 - Keep `vectors.qvec` authoritative until pure trinary storage has recovery, migration, and recall tests.