poimen-memory/tasks/M2.5-obsidian-projector.md

# M2.5 — Obsidian projector

| Field | Value |
|---|---|
| Phase | M2 — Projections |
| Size | M — 1–3 days |
| Status | ⬜ Not started |
| Flags | — |
| Spec | inlined below |
| Blocks | M1.6 |

## Goal

Render the log as a vault a human reads, with the tier graph as the link graph.

## Facts (inlined — no spec read needed)

```
vault/<project>/
  index.md                  L2 synthesis, links every L1 note
  <query-id>.md             L1, one per standing query
  evidence/<source>-<t>.md  L0, only with --emit-evidence-notes
```

```markdown
---
project: poimen
level: L1
query_id: infra-root-causes
updated: 2026-08-17
chunks_seen: 412
chunks_used: 17
run_id: 01HXYZ...
---
# Infra root causes — poimen

<final memory text, verbatim>

## Provenance
- [[pi-2026-07-21-019f857d]] chunk 66 — Kong body buffer
```

**Deterministic output is the requirement, not a nicety.** M2.8 asserts that
rebuilding produces a byte-identical vault. That means: stable key order in
frontmatter, no timestamp of *generation* (only `updated` derived from the log),
sorted provenance lists, and `\n` line endings.

`updated` comes from the run's timestamp in the log — not `now()`. A generation
timestamp makes every rebuild a diff and destroys the gate.

L0 notes default off: 17 per query is fine, but it grows unbounded across
projects and queries. Citations inline give the same provenance without the file
count.

Wikilinks are `[[<source-note-name>]]`. The link target may not exist as a file
when evidence notes are off — that is fine and normal in Obsidian, and it still
shows in the graph view as an unresolved node.

## Steps

1. `ObsidianProjector::project(log_dir, vault_dir, opts)` in `mem-store`.
2. Read the log; take the final `memory` record per query for L1, and the L2
   record for `index.md`.
3. Frontmatter with a fixed key order; `updated` from the log.
4. Provenance section from `parents`, sorted by source then `t`.
5. `--emit-evidence-notes` writes L0 notes; default off.
6. Write with `\n`, no trailing whitespace, exactly one trailing newline.
7. A note whose L1 memory is empty is still written, with a body saying no
   evidence was found — an absent file is indistinguishable from a failed run.

## Acceptance

- Two projections of the same log produce byte-identical files.
- Frontmatter key order is stable.
- `updated` reflects the run, not the projection.
- Every L1 note links to its L2 index and vice versa.

## Verify

**Harness:** a committed log fixture and a committed expected vault tree.

**Integration test** — `tests/it_projector.rs`:
1. `a1_byte_identical_twice` — project into two temp dirs, assert every file's
   bytes are equal. This is M2.8's core property, tested early.
2. `a2_no_generation_timestamp` — project, sleep 1s, project again, assert equal.
   Catches `now()` leaking into output.
3. `a3_frontmatter_key_order` — assert the exact key sequence.
4. `a4_golden_tree` — diff the whole output against `expected/vault/`, empty diff.
5. `a5_empty_memory_still_writes` — a log with zero updates produces a note
   saying so.
6. `a6_links_bidirectional` — every L1 note appears in `index.md` and links back.
7. `a7_evidence_notes_flag` — off by default; on, produces one note per L0 node.
8. `a8_line_endings` — no `\r`, exactly one trailing `\n`.

**Command:** `cargo test -p mem-store projector`

**False pass:**
- Comparing files by parsed content rather than bytes. Key reordering and
  whitespace churn both pass, and both fail M2.8 later, where the cause is much
  harder to find.
- Testing with a single query. Assertion 6 needs at least two L1 notes to catch a
  link built from the wrong id.

## Traps

- `updated: {now}`. The most natural thing to write, and it makes every rebuild
  dirty, which trains everyone to ignore the diff that M2.8 depends on.
- Serializing frontmatter from a `HashMap`. Iteration order is unspecified and
  the output churns between runs on the same input.

---

Background: [DESIGN.md](../DESIGN.md) — Obsidian vault