# M2.7 — `mem verify` — edge closure

| Field | Value |
|---|---|
| Phase | M2 — Projections |
| Size | S — under 1 day |
| Status | ⬜ Not started |
| Flags | — |
| Spec | inlined below |
| Blocks | M2.6 |

## Goal

Assert the provenance graph is well-formed, so a memory with no traceable
evidence is caught rather than believed.

## Facts (inlined — no spec read needed)

Invariants, checked against the log and the database independently:

1. Every L1 `memory` record has at least one L0 parent. A memory with no evidence
   came from somewhere the record does not explain.
2. Every `parents` sha resolves to a node that exists.
3. Every `evidence` sha appears as a parent of at least one memory. Evidence that
   nothing cites was written for no reason.
4. `evidence` count equals `gate.update == true` count (also M1.6 a2, re-checked
   here across the whole project rather than one run).
5. No edge is self-referential; no cycles.
6. Levels are consistent: an L1 node's parents are L0; an L2 node's are L1.

Invariant 6 is the one that catches a tier confusion, and it is the one most
likely to break when M3.1 adds the L2 pass — an L2 node accidentally parented to
L0 evidence would still look plausible in the vault.

`mem verify` is a read-only diagnostic. It never repairs; repair is `mem rebuild`.

## Steps

1. `mem verify --project P [--db] [--log]`, defaulting to both.
2. Check invariants 1–6, collecting **all** violations rather than failing on the
   first — one run should tell you everything wrong.
3. Report per violation: invariant, level, sha, run id, and the log line number.
4. Exit non-zero on any violation.
5. `--format json` for machine consumption.

## Acceptance

- A clean project reports zero violations, exit 0.
- Each invariant has a fixture that violates it and is detected.
- All violations are reported in one run, not just the first.

## Verify

**Harness:** hand-built log fixtures, one per invariant, plus a clean one.

**Integration test** — `tests/it_verify.rs`:
1. `a1_clean_passes` — the good fixture, zero violations, exit 0.
2. `a2_orphan_memory` — L1 with empty `parents`; detected as invariant 1.
3. `a3_dangling_parent` — parent sha not present; invariant 2.
4. `a4_uncited_evidence` — evidence nothing references; invariant 3.
5. `a5_evidence_gate_mismatch` — 3 update-gates but 2 evidence records;
   invariant 4.
6. `a6_cycle` — A parents B, B parents A; invariant 5.
7. `a7_level_mismatch` — L2 node parented directly to an L0 node; invariant 6.
8. `a8_reports_all` — a fixture violating three invariants at once; assert all
   three appear in one run's output.
9. `a9_db_and_log_agree` — introduce a violation in the database only; assert
   `--db` catches it and `--log` does not, proving the two checks are independent.

**Command:** `cargo test -p mem-cli verify`

**False pass:**
- Checking the database only. The log is authoritative; a log-level violation
  that rebuild happens to smooth over is still a bug in the writer, and
  assertion 9 is what keeps the two checks honest.
- Failing fast on the first violation. It passes every single-violation fixture
  and makes assertion 8 impossible, which in practice means three rebuild cycles
  to find three problems.

## Traps

- Treating invariant 3 as fatal. Uncited evidence is a real smell, but a
  legitimate case exists: the final turn updates memory and the run is cut short
  before the memory record flushes. Report it, and let the gate decide severity.
- Skipping invariant 6 because L2 does not exist yet. It is cheap now and it is
  precisely what M3.1 will break.

---

Background: [DESIGN.md](../DESIGN.md) — tier model, Verification