# Suggested Secondary Todo List

Date: 2026-07-16
Source: `01`–`04` review documents in this folder. Ranked by impact.
These are *suggestions* to merge into `docs/known-issues.mdx` /
`docs/roadmap.mdx` (the authoritative registers) — this file is a staging
area, not a third register.

## P0 — Correctness & security (do before promoting mutable mode)

- [ ] **Advisory-lock durable projection ingest.** Take the per-graph
      PostgreSQL advisory lock (as build/vacuum do, `sql_build.rs:315-330`)
      around ingest + manifest publication (`projection/ingest.rs:86-111`,
      `manifest.rs:225-230`). Two concurrent `apply_sync()` backends can
      currently drop a segment generation (last-writer-wins rename).
- [ ] **Document (or gate) the RLS boundary on topology reads.** Topology
      functions return PKs/adjacency from a builder-scoped artifact; RLS is
      never consulted (`acl.rs:52-68`, `engine.rs:678-777`). Minimum: loud
      section in administration-and-security docs + known-issues row. Better:
      refuse or warn on RLS-enabled tables without an explicit opt-in GUC.
- [ ] **Clarify tenant scoping is a filter, not isolation** for
      bitmap-tenanted graphs (`sql_sync.rs:1883-1927`); align docs and
      consider an enforcement option.
- [ ] **Fix bidirectional BFS first-intersection break**
      (`path_finder.rs:165-172,201-208`) — finish the level and pick the
      minimal combined-distance meeting node; add a two-meeting-point
      regression test. Shortest paths may currently be one hop too long.
- [ ] **Add `_sync_log` retention/pruning.** Applied rows are never deleted
      anywhere; the log grows without bound and apply scans degrade. Prune
      below the durable watermark from maintenance /
      `run_scheduled_maintenance()`.

## P1 — Operational hardening

- [ ] **Wire fmt/clippy/test/doc-drift into an automated PR CI workflow.**
      Docs describe a CI gate ladder; the repo has only a manual packaging
      workflow (`.github/workflows/release.yml`). All needed scripts already
      exist (`graph/tests/heavy/run_release_gate.sh`,
      `scripts/check_docs_drift.sh`).
- [ ] **Poison-row dead-lettering for sync apply.** Wire the unused
      `_sync_log.error_message` column; skip-and-mark after repeated failure;
      surface a count in `sync_health()`.
- [ ] **Atomic artifact+sidecar commit.** `.sync` / `.projection_mode` are
      written after the `.pggraph` rename (`persistence.rs:615-622`) — crash
      window pairs a new artifact with a stale watermark. Also add parent-dir
      fsync after rename (manifest path already does this).
- [ ] **Truncation signal in traversal results.** `max_nodes`/`max_frontier`
      caps return partial results indistinguishable from complete ones
      (`bfs.rs:304-324`); shortest-path truncation can yield a false
      "no path". Add a `truncated` column / error contract.
- [ ] **Known-issues row for `mutable_overlay` production status.** Roadmap
      admits it needs verification + benchmark signoff; the limitations
      register says nothing and the quickstart offers `mutable` with no
      caveat.

## P2 — Performance follow-ups (benchmark-driven)

- [ ] **Stop cloning tenant state per traversal** — borrow
      `tenant_membership`/`tenanted_table_oids` in `BfsConfig`
      (`engine.rs:733-737`).
- [ ] **Empty-overlay fast path**: short-circuit
      `traversal_edge_overlay`/layered-provider assembly when edge buffer +
      tx delta are empty (`engine.rs:725,816-871`); prerequisite for "hybrid
      reads at CSR speed".
- [ ] **Per-generation load validation cache.** Full-file CRC + full content
      walk on every backend's first query (`persistence.rs:312-408,773`)
      likely dominates the known ~4.4 s first-backend cost; validate once per
      artifact generation instead.
- [ ] **Clamp frontier pre-allocation** to `min(max_frontier, node_count)`
      (`bfs.rs:248,362,510`).
- [ ] **Weighted shortest path over overlays** — extend Dijkstra to the
      layered neighbor source so writes stop disabling weighted queries
      (`engine.rs:966-980`). (Also a mode-design prerequisite, see doc 02.)

## P3 — Hygiene & docs

- [ ] **Bump `README_zh.md` to 0.1.8** (currently 0.1.5 badges/pulls, lines
      18/95/100/162) and add version parity to `check_docs_drift.sh`.
- [ ] **Move resolved KI rows (KI-001/002/003/011) out of "Next Update
      Scope"** into a resolved section; de-duplicate KI-005.
- [ ] **Builder table-name resolution parity**: use the OID-stable regclass
      path hydration uses instead of raw `format!` names
      (`builder.rs:341,478-482`) — search_path stability at build time.
- [ ] **Document little-endian-only mmap format** and add a
      `cfg!(target_endian)` guard (`edge_store.rs:508-509`,
      `node_store.rs:321-445`).
- [ ] **Unify the two overlay systems** (legacy `edge_buffer` vs durable
      segments) per the direction in `02-dual-mode-design-proposal.md` —
      larger refactor; roadmap-owned.

## Mode-design work (see `02-dual-mode-design-proposal.md` for detail)

- [ ] Phase 1 prerequisites: ingest lock, sync-log retention, dead-lettering
      (items above).
- [ ] Phase 2 "live" mode: auto-maintenance consuming the existing
      `sync_health()` recommendation booleans; require persistence for
      `mutable_overlay` builds; weighted paths over overlays; benchmark
      signoff; consider relaxing the `mutable_enabled` double gate.
- [ ] Phase 3 hybrid: `projection_mode = 'auto'` policy layer (escalate
      apply/compaction cadence and optionally mode on write pressure), with
      the empty-overlay read fast path making clean generations read at CSR
      speed.
- [ ] Phase 4: background pre-applier; WAL/logical-replication sync to remove
      trigger overhead for high-write tables.