Completed Plan — Build Sequence For The Post-v0.1.8 Work

Date: 2026-07-16 Status: plan complete; findings merged into the authoritative registers.

This closes the loop on this review folder: every finding from docs 01–05 is now either a tracked row in docs/known-issues.mdx (KI-012 … KI-026), a sequenced item in docs/roadmap.mdx → “Projection Operating Modes”, or intentionally dropped (nothing was dropped). This file is the single dependency-ordered build sequence. Each slice is an independently mergeable, TDD’d PR; stop anywhere and what’s merged is shippable.

Stage 0 — CI first (KI-017)

S0. Automated PR CI. Wire cargo fmt --check, clippy, cargo test, cargo doc, and scripts/check_docs_drift.sh into a PR workflow; pgrx integration as a second job. Why first: every slice below is riskier without it, and all the scripts already exist. Gate: CI green on a no-op PR and red on a seeded fmt/clippy violation.

Stage 1 — Correctness and security (before promoting mutable mode)

Independent of each other; can proceed in parallel after S0.

Slice Register What Merge gate
C1 KI-012 Advisory-lock durable ingest: take the per-graph advisory lock (as sql_build.rs does) around projection/ingest.rs + manifest.rs publication Two-backend concurrent apply_sync() stress test proves no lost generation; single-backend throughput unchanged
C2 KI-015 Bidirectional BFS: finish the level, select minimal combined-distance meeting node Two-meeting-point regression test; existing path tests green; bfs_bench unregressed
C3 KI-016 _sync_log retention: checkpointed prune below the durable-watermark minimum, from maintenance() + run_scheduled_maintenance() Prune never deletes unapplied rows (proptest over watermark orderings); log size bounded in a write-heavy heavy test
C4 KI-013 RLS topology boundary: loud security-docs section now; then refuse-or-warn GUC for registering RLS-enabled tables Docs drift check green; pgrx test for the warn/refuse path
C5 KI-014 Tenant-scope docs: state filter-vs-isolation plainly; evaluate enforcement option Docs updated; decision recorded (enforce or explicitly not)

Stage 2 — Operational hardening

Slice Register What Merge gate
O1 KI-018 Poison-row dead-lettering via _sync_log.error_message; count in sync_health() Repeated-failure row is skipped + surfaced; recovery documented
O2 KI-019 Atomic artifact+sidecar commit; parent-dir fsync after rename Crash-window test (kill between rename and sidecar) recovers correctly
O3 KI-020 truncated signal on capped traversal/path results Contract documented; false-“no path” case covered
O4 KI-021 mutable_overlay production-status row + quickstart caveat Row live until Stage 3 benchmark signoff clears it
O5 KI-024 README_zh.md version parity in check_docs_drift.sh Drift check fails on stale translation version

Stage 3 — Make live mode real (roadmap Projection Modes phase 2)

Depends on Stage 1 (C1, C3 are hard prerequisites).

Slice Register What Merge gate
L1 roadmap Auto-maintenance consumes sync_health() recommendation booleans; adaptive cadence; non-Docker setup documented Recommendations acted on in a soak test; cadence tightens under write pressure
L2 roadmap mutable_overlay build requires persist_on_build = on (refuse or warn, no silent degrade) pgrx test for refusal path; docs updated
L3 KI-023 Weighted shortest path over layered overlays (segments already carry weights) Weighted results on dirty overlay ≡ post-compaction results (proptest); rejection path removed
L4 KI-021 Benchmark + verification signoff: dirty-read amplification vs segment fanout, apply throughput, compaction pauses Published numbers; then relax the mutable_enabled double gate and clear KI-021

Stage 4 — Hybrid auto mode (roadmap phase 3)

Depends on Stage 3.

Slice What Merge gate
H1 Empty-overlay read fast path (part of KI-005): short-circuit overlay assembly when buffer + tx delta are empty Clean-generation reads benchmark at CSR speed
H2 projection_mode = 'auto' policy layer: act on pressure signals; opt-in mode escalation/demotion at maintenance windows, loudly logged Policy soak test: escalates under write pressure, demotes when idle, never flaps

Stage 5 — Performance follow-ups (benchmark-driven, any time after S0)

All under KI-005’s measure-before-optimizing rule: tenant-state borrow, per-generation artifact validation cache, frontier pre-allocation clamp. Each lands only with a benchmark showing it matters.

Stage 6 — Larger refactors (roadmap-owned, last)

Slice Register What
R1 KI-022 Unify overlays: durable segments become the only edge overlay for persisted graphs; edge_buffer retires to transaction-local duty
R2 KI-025 Builder regclass/OID-stable table resolution parity with hydration
R3 KI-026 Little-endian format doc + cfg!(target_endian) load guard
R4 roadmap Background pre-applier; WAL/logical-replication sync (sync_mode = 'wal')

Cross-cutting rules (unchanged from the shipped program)

TDD every slice; pgrx-free internals where possible; no Result<_, String> across layers; no new unsafe; docs-contract gate before public surface changes; benchmark against the current baselines before claiming completion.