docs: snapshot & parallel-worktree audit (omnigraph comparison)#999
Conversation
Research pass comparing codegraph to omnigraph.dev. Documents three filed correctness bugs (#995 snapshot TOCTOU, #996 unlocked journal appends, #997 watcher never updates journal header) and records why a content-addressed parse cache was considered and rejected: parsing is ~10% of full-build time, so the cache would save ~10% on first- build-in-new-worktree and near-zero on incremental/watch. Also corrects the initial "structural failure in multi-worktree incremental updates" framing — each linked worktree gets its own DB (verified), and incremental builds within a worktree work correctly. The real gap is that first-build-in-new-worktree doesn't amortize work other worktrees already did, which is an optimization opportunity, not a structural failure.
|
Claude finished @carlos-alm's task —— View job PR Review: docs/snapshot-worktree-auditTodo List:
Root Cause AnalysisProblem Being Solved: Addresses the framing of "structural failure in multi-worktree incremental updates" by conducting a systematic comparison with omnigraph.dev to identify actual vs. perceived issues with codegraph's parallel worktree behavior. Why This Approach: The audit approach is methodical and well-justified. Rather than making architectural assumptions, the author:
Risk Assessment: Very low risk - documentation-only change with no behavioral impact. Phase 2-3: Configuration/Test Changes✅ Clean - No configuration changes, no test modifications, no code touched. Phase 4: Documentation QualityStrengths:
Technical accuracy verified through code references:
Minor areas for improvement:
Backlog Compliance
Critical ConcernsNone identified. This is exemplary technical documentation that:
Final Recommendation
|
Greptile SummaryThis PR adds a documentation audit report comparing codegraph's snapshot and incremental-build design against omnigraph, recording 3 correctness bugs (#995, #996, #997), evaluating and rejecting a content-addressed parse cache optimization, and correcting an earlier "structural failure" framing to a more precise "amortization gap." The document is well-reasoned, appropriately caveated about omnigraph internals, and the previously flagged missing-R2 gap is resolved in this version (table now reads Confidence Score: 5/5Docs-only change, safe to merge — no code behavior is affected. All findings are documentation artifacts with no runtime impact. The previously flagged R2 numbering issue is addressed in this version. The audit content is accurate, well-caveated, and internally consistent. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[snapshotSave called] --> B{existsSync?}
B -- yes --> C[unlinkSync existing .db]
C --> D[VACUUM INTO new .db]
B -- no --> D
D --> E[Done]
style C fill:#ffcccc,stroke:#cc0000
style D fill:#ffcccc,stroke:#cc0000
F[Watcher fires] --> G[appendJournalEntries fs.appendFileSync — unlocked]
H[Manual build fires] --> G
G --> I{Interleaved writes?}
I -- yes --> J[Corrupt journal entries]
I -- no --> K[Clean entries]
style G fill:#ffcccc,stroke:#cc0000
style J fill:#ffcccc,stroke:#cc0000
L[New linked worktree created] --> M[git rev-parse --show-toplevel returns worktree path]
M --> N[Own .codegraph/graph.db]
N --> O[First build — full cold parse]
O --> P[~10% of time is parsing — optimization gap not structural failure]
style N fill:#ccffcc,stroke:#00aa00
Reviews (6): Last reviewed commit: "Merge branch 'main' into docs/snapshot-w..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| | ID | Action | Status | | ||
| |---|---|---| | ||
| | **A1** | Fix #995 — snapshot save TOCTOU race. Use `<name>.db.tmp-<pid>` + atomic rename, or a real file lock. | **Do** | | ||
| | **A2** | Fix #996 — lock journal mutations (or replace with a per-line append-only log). | **Do** | | ||
| | **A3** | Fix #997 — watcher updates journal header in the same critical section as entry appends. | **Do** | | ||
| | ~~R1~~ | ~~Content-addressed parse cache.~~ | **Rejected** — 10% parse share | | ||
| | R3 | Bind snapshot names to git identity + metadata + GC. | Nice-to-have. Not urgent. | | ||
| | R4 | Share more than parses across worktrees (resolved edges, embeddings) by content hash. | Speculative — conditional on verifying content-purity. Not recommended now. | | ||
| | R5 | Replace SQLite-as-materialized-graph with append-only versioned store. | Long-horizon, out of scope. | |
There was a problem hiding this comment.
The recommendations table jumps from R1 directly to R3, with no mention of R2 anywhere in the document. Readers will naturally wonder what R2 was — whether it was merged into another item, deliberately removed, or an accidental numbering skip. A brief parenthetical (e.g. "R2 was merged into A2" or renumbering R3→R2, R4→R3, R5→R4) would prevent future confusion.
There was a problem hiding this comment.
Fixed in dcf3705 — renumbered R3→R2, R4→R3, R5→R4 so the table reads R1 (struck, rejected) / R2 / R3 / R4 with no visible gap. Also added a parenthetical on the R1 row pointing to §4 for the rejection rationale. Updated the one back-reference in §6 (was 'R4', now 'R3').
|
Addressed Greptile's orphaned-source finding (review #999 (review)):
Fix in e1fbd60. |
1 participant
Summary
docs/reports/snapshot-and-worktree-audit.md— a research pass comparing codegraph to omnigraph.dev, focused on our snapshot design and incremental-build behavior under parallel Claude Code worktrees.Key takeaway
The 3 filed bugs are the concrete action items. The omnigraph-inspired architectural rewrites (copy-on-write branches, commit-equals-snapshot storage model) don't fit codegraph because they couple graph freshness to git commits, which breaks the "graph tracks your working tree live" invariant.
Test plan