# Secondary Review — Overview

Date: 2026-07-16 · pgGraph v0.1.8 · review only, no code changed.

This folder answers three questions: are there issues with pgGraph (including
the todo register), is anything seriously wrong with the implementation, and
how should the write→graph syncing story evolve into CSR / live / hybrid
operating modes.

## Documents

| File | Contents |
|---|---|
| `01-sync-architecture-review.md` | Exact trace of what happens on a write in each mode; how complete `mutable_overlay` is; sync weaknesses W1–W7 |
| `02-dual-mode-design-proposal.md` | The CSR / live / hybrid mode design; phased work plan; "what we'd have done differently" |
| `03-implementation-review-findings.md` | Core-engine findings ranked H/M/L; what's well done |
| `04-docs-and-todo-audit.md` | Docs-vs-code drift; assessment of known-issues/roadmap as a todo list |
| `05-suggested-todos.md` | Prioritized staging list to merge into the official registers |
| `06-path-to-full-graph-engine.md` | Strategy: SQL/PGQ (PG19) compatibility, performance vs. native graph DBs, and the path to replacing them |
| `07-completed-plan-build-sequence.md` | **Plan complete (2026-07-16):** all findings merged into `docs/known-issues.mdx` (KI-012…KI-026) and `docs/roadmap.mdx` (Projection Operating Modes); this file is the dependency-ordered build sequence with merge gates |
| `08-plan-delta-for-graph-engine-strategy.md` | What doc 06 changes in the doc 07 sequence: new SQL/PGQ parallel track (P1–P4), three promotions, PG19-GA clock, two register/positioning edits |
| `09-revised-build-sequence.md` | Build sequence v2 (supersedes 07) — doc 07 slices with `[=]`/`[^]`/`[+]` markers; adds Stage 2P (SQL/PGQ), L5 (WAL design), F1/F4/F5. **Written against main/v0.1.8 — read doc 10 for current status** |
| `10-reconciliation-with-dev-1.0.md` | **Authoritative status map (2026-07-17)** — every doc 09 slice reconciled against the dev 1.0 release line; corrected next-actions list; release-takeover record (full-matrix 16/17, sanitizer deferred to Linux, sfw Dockerfile change rejected) |

## Headline Answers

**Is anything seriously wrong?** No architectural rot — the base design
(Postgres authoritative, immutable mmap CSR + layered deltas + compaction,
PostgreSQL-first writes) is sound and the unsafe/persistence code is genuinely
defensive. But five findings deserve immediate attention:

1. **RLS is not enforced on topology reads** — traverse/paths/components leak
   PKs, adjacency, and connectivity of RLS-hidden rows to anyone with
   table-level SELECT (03 · H1).
2. **Durable ingest can race across backends** — process-local mutex only;
   concurrent `apply_sync()` can silently drop a segment generation
   (01 · W1, 03 · H2).
3. **Bidirectional BFS can return a non-minimal shortest path** — breaks on
   first intersection instead of minimal combined distance (03 · M1).
4. **`graph._sync_log` is never pruned** — unbounded growth on write-heavy
   graphs (01 · W2).
5. **Tenant scope is a filter, not isolation** for bitmap-tenanted graphs
   (03 · H3).

**Is the todo register healthy?** Mostly — docs are unusually accurate.
Gaps: no automated PR CI exists despite docs implying it; `mutable_overlay`
production status has no known-issues row; `README_zh.md` is stale at 0.1.5;
resolved KI rows clutter the active section; and none of the five findings
above were tracked anywhere.

**The syncing issue.** The premise "a write requires a rebuild for traversal"
is already false in the default configuration: trigger sync + default
`query_freshness = 'apply_pending_sync'` makes topology reads catch up before
executing, and the `mutable_overlay` mode already implements the
"write goes into the graph" design (durable LSM-style segments, layered reads,
compaction, GC, crash recovery, cross-backend visibility). What's genuinely
missing is not a storage engine but the **policy layer**: automation that
consumes the `sync_health()` recommendation signals, weighted-path support
over overlays, an ingest lock, sync-log retention, and an `auto` mode that
escalates under write pressure. Rebuilds remain only for weighted-path
staleness, edge-buffer overflow, TRUNCATE, schema drift, and periodic
compaction back to a clean base. See `02-dual-mode-design-proposal.md`.