# Evidence Task 5C report

## Delivered

- Added `vector.retain_published_generations` (default `3`, validation minimum `1`).
- Retention runs only after publication. It keeps ACTIVE, the newest configured generations,
  and generations referenced by running or resumable failed job checkpoints.
- Cleanup deletes the exact Evidence generation from the vector store before removing its
  immutable filesystem directory. Vector failures retain filesystem metadata for retry and
  produce credential-free partial reports.
- Added idempotent `tht preprocess evidence gc [--dry-run] --json` reconciliation with pristine
  JSON output.
- Materialized document reads now open generation/documents components with directory file
  descriptors and `O_NOFOLLOW`, require a regular file owned by the process with one link, and
  hash the bytes read from the same descriptor against the canonical manifest.
- HTTP generation deletion is pinned to `delete_vector_generation` with exact
  table/kind/generation arguments. Legacy 404 responses fail closed with an actionable,
  sanitized migration message.

## Evidence

- Focused retention, safe-read, CLI, and HTTP contract tests: `51 passed` (Docker-backed direct
  parametrizations excluded from that focused invocation).
- Real Docker pgvector adapter suites: `33 passed`.
- Full harness suite, including Docker-backed tests: `668 passed, 5 deselected`.
- Changed-file Ruff: clean.
- `git diff --check`: clean.

The five deselected tests are the repository's opt-in `l2` tests requiring external services;
they are not local pgvector tests. Test output retains pre-existing Pydantic serialization and
legacy-config deprecation warnings.

## Review fix wave

- Publication is now explicit and durable (`PUBLISHED` marker). Retention candidates require a
  valid generation manifest and publication marker (ACTIVE remains backward-compatible), so
  staged and malformed directories neither consume retention slots nor become deletion targets.
- The policy retains ACTIVE plus exactly `N-1` newest rollback publications, ordered by durable
  publication time and generation id. Running and failed-resumable JobRunner checkpoints protect
  every referenced plan generation.
- `VectorStore` now exposes exact Evidence generation inventory. Direct pgvector uses a constrained
  `SELECT DISTINCT` over `kind='evidence'` and `metadata.vector_generation`; HTTP uses the
  allowlisted `list_evidence_generations` RPC and fails closed on legacy 404. The writer RPC SQL,
  revokes, and grants are packaged in `create_vector_writer_rpc.sql`.
- Explicit GC reconciles the union of published filesystem generations and vector-only orphans,
  preserving vector-before-filesystem deletion and retry semantics.
- `run_as_job` holds the same corpus writer lock across checkpoint recovery, staging, publish, and
  retention. Explicit GC already uses this lock, serializing candidate snapshots with publishers.
- Session artifact consumers no longer receive the corpus source path after validation. They get
  an owned, read-only copy atomically written from the bytes read and hash-validated on the same
  descriptor.

Fresh verification after the fix wave: full harness `672 passed, 5 deselected`; Docker pgvector,
HTTP parity, and migration suites `43 passed`; exact direct inventory/delete integration `1 passed`;
changed-file Ruff and `git diff --check` clean.