Docs & Todo-Register Audit

Date: 2026-07-16 Scope: docs/known-issues.mdx, docs/roadmap.mdx, README.md, README_zh.md, .github/workflows/, verified against graph/src/. This repo only.

The project’s effective todo list is docs/known-issues.mdx (limitations register) + docs/roadmap.mdx (direction). There is no separate todo file in this repo.

Verdict

The docs are unusually well-synchronized with the code. Every specific technical claim spot-checked was accurate. Two real drift items exist (Chinese README version, CI reality vs. wording), and three important work items are missing from the register entirely.

Verified Accurate (spot-checks)

  • graph.sync_mode = 'wal' reserved-and-rejected: parser accepts (config.rs:420), resolution rejects (sql_sync.rs:29), covered by test pg_tests/sync_config_build.rs:124.
  • graph.build_scan_mode = 'copy' reserved-and-rejected: builder.rs:258-260, test at pg_tests/sync_config_build.rs:505.
  • graph.memory_profile() (sql_facade/admin.rs:1453), graph.run_scheduled_maintenance() (admin.rs:1572), graph.sync_health() (admin.rs:1492), graph.status() (admin.rs:1009) all exist with documented signatures.
  • mutable_overlay exists exactly as the roadmap “Reserved Features” rows describe, including the graph.mutable_enabled gate (sql_build.rs:355-367) and write rejection on csr_readonly (sql_facade/gql.rs:2393).
  • Version/toolchain coherence: 0.1.8 / Rust 1.96.0 / pgrx 0.19.1 / PG 14–18 agree across README.md, META.json, graph/Cargo.toml, graph/rust-toolchain.toml, docs/index.mdx, installation docs.
  • KI-008 mega-file list is real and current — all eight files still exceed 1,000 lines: query/tests.rs 5,577; pg_tests/gql.rs 4,616; query/semantics.rs 3,932; sql_facade/gql.rs 3,275; engine.rs 2,557; query/value.rs 2,508; bfs.rs 1,444; gql/parser.rs 1,251.

Drift / Contradictions

D1 — README_zh.md is stale at v0.1.5

Badge, docker pull …:0.1.5 (lines 95, 100), and “从 v0.1.5 开始…” (line 162) all lag the English README’s 0.1.8 — while its prerequisites already say Rust 1.96, so the file is internally inconsistent. It drifts on every release; scripts/check_docs_drift.sh does not gate it.

D2 — Docs imply automated CI that does not exist

Roadmap (roadmap.mdx:45,63) and several release notes describe a CI gate ladder (fmt/clippy/test/doc drift “on every change”, then pgrx integration, then heavy gates). Reality: the only workflow is .github/workflows/release.yml, a manual workflow_dispatch packaging pipeline (metadata validation → PGXN zip → Docker matrix pg14–18). It runs no cargo fmt/clippy/test/pgrx test. There is no push/PR CI at all — the gates exist only as local scripts (graph/tests/heavy/run_release_gate.sh, scripts/check_docs_drift.sh) and a human checklist. The roadmap’s future tense softens this, but release-note readers would assume per-change CI exists. (The Docker matrix itself — pg 14–18, amd64+arm64, pg17 default — does match the documented support range.)

Missing From The Todo Register (untracked gaps)

M1 — No PR/push CI workflow item

The single most valuable untracked engineering task: wire the existing release-gate static checks (fmt, clippy, test, doc drift) into an automated PR workflow. Everything needed already exists as scripts.

M2 — mutable_overlay production-readiness has no known-issues row

Roadmap line 158 admits durable projection needs “production verification, release documentation, and benchmark signoff” — but the known-issues register (described as “the authoritative register for known limitations”) has no row for it, and the quickstart (docs/quickstart.mdx:175) offers the playground mutable mode with no caveat. An operator enabling it gets no limitations-level warning.

M3 — README_zh.md release-parity is untracked

Either a tracked release-checklist item or an extension to check_docs_drift.sh to enforce version parity.

Also untracked (found in the code review, see 01-sync-architecture-review.md and 03-implementation-review-findings.md): unbounded _sync_log growth, missing advisory lock on durable ingest, and unused _sync_log.error_message/no poison-row dead-lettering.

Stale / Completed Items Still Listed

  • KI-001, KI-002, KI-003 sit under “Next Update Scope” but are all resolved (“Hardened” / “Coverage added”). Same for KI-011. They read as audit trail but inflate the apparent open backlog under a heading framed as pre-production blockers — move them to a resolved section.
  • KI-005 is listed twice (Internal Construction + P1). The duplication is flagged as deliberate, but a register should say it once and cross-reference.
  • The P0 “no rows remain” callout is accurate (memory_profile shipped) — not drift.

Assessment Of The Register As A Todo List

Strengths: disciplined known-issues/roadmap split, honest status wording, impact-ranked, IDs are stable and referenced from code review docs.

Weaknesses: completed items accumulate in active sections; operational gaps discovered only by reading code (sync-log growth, ingest locking, CI absence) never made it in; and the register tracks limitations well but engineering debt with user impact (the hybrid-mode automation gap) lives only as soft roadmap prose. 05-suggested-todos.md proposes concrete additions.