# Revised Build Sequence — v2 (Supersedes Doc 07)

Date: 2026-07-16
Status: **authoritative build sequence.** Supersedes
`07-completed-plan-build-sequence.md`, which remains valid as the baseline —
every slice ID from doc 07 keeps its meaning here. The changes come from
`06-path-to-full-graph-engine.md` (strategy) via
`08-plan-delta-for-graph-engine-strategy.md` (delta rationale).

**Note for the agent currently building from doc 07:** nothing you have built
from Stages 0–2 is invalidated. Change markers below:
`[=]` unchanged from doc 07 · `[^]` promoted/gate changed · `[+]` new in v2.
If you are mid-slice on anything marked `[=]`, continue as specified in doc 07.
The only doc 07 content that changed meaning is: C2 and O3 gained a
benchmark-publication gate, the validation cache left Stage 5's
"measure-first" bucket, and WAL sync design moved earlier. Everything else new
is additive (Stage 2P and Stage 5 additions).

External anchor: **PG19 GA (~fall 2026)** — P1 must land before it.

---

## Stage 0 — CI first `[=]`

**S0 (KI-017).** `cargo fmt --check`, `clippy`, `cargo test`, `cargo doc`,
`scripts/check_docs_drift.sh` in a PR workflow; pgrx integration as a second
job. Gate: green on a no-op PR, red on a seeded violation.
*Everything below depends on S0.*

## Stage 1 — Correctness and security

Parallel after S0. All `[=]` except C2's gate.

| Slice | Register | What | Merge gate |
|---|---|---|---|
| C1 `[=]` | KI-012 | Advisory-lock durable ingest (per-graph lock as `sql_build.rs` does, around `projection/ingest.rs` + `manifest.rs` publication) | Two-backend concurrent `apply_sync()` stress: no lost generation; throughput unchanged |
| C2 `[^]` | KI-015 | Bidirectional BFS: finish level, pick minimal combined-distance meeting node | Two-meeting-point regression; existing tests green; bench unregressed. **New gate: blocks any published benchmark (P2 publication)** |
| C3 `[=]` | KI-016 | `_sync_log` retention: checkpointed prune below durable-watermark minimum, from `maintenance()` + `run_scheduled_maintenance()` | Proptest: never deletes unapplied rows; log bounded under write-heavy test |
| C4 `[=]` | KI-013 | RLS topology boundary: security-docs section now; refuse-or-warn GUC for RLS-enabled tables | Docs drift green; pgrx test for warn/refuse |
| C5 `[=]` | KI-014 | Tenant filter-vs-isolation docs + enforcement decision | Docs updated; decision recorded |

## Stage 2 — Operational hardening

All `[=]` except O3's gate.

| Slice | Register | What | Merge gate |
|---|---|---|---|
| O1 `[=]` | KI-018 | Poison-row dead-lettering via `_sync_log.error_message`; count in `sync_health()` | Repeated-failure row skipped + surfaced; recovery documented |
| O2 `[=]` | KI-019 | Atomic artifact+sidecar commit; parent-dir fsync after rename | Crash-window test recovers correctly |
| O3 `[^]` | KI-020 | `truncated` signal on capped traversal/path results | Contract documented; false-"no path" covered. **New gate: blocks P2 publication** |
| O4 `[=]` | KI-021 | `mutable_overlay` production-status row + quickstart caveat | Row live until L4 signoff |
| O5 `[=]` | KI-024 | `README_zh.md` version parity in drift check | Fails on stale translation |

## Stage 2P — SQL/PGQ compatibility track `[+]`

New parallel track after S0. Owns the PG19 GA clock. Source: doc 06 Pillar A,
doc 08 §3.

| Slice | What | Depends on | Merge gate | Target |
|---|---|---|---|---|
| P1 `[+]` | `graph.import_property_graph()`: read `pg_propgraph_*` → pgGraph registration; drift detection via `pg_get_propgraphdef()`; version-gated PG19+ | S0 | Round-trip on PG19 beta: CREATE PROPERTY GRAPH → import → build → traverse; drift flag on ALTER | **Before PG19 GA** |
| P2 `[+]` | LDBC SNB harness (`sandbox/benchmark` ldbc preset) incl. plain-PG19 `GRAPH_TABLE` same-box comparison | S0 (build now); C2 + O3 (publish) | Reproducible in-repo harness; baseline recorded | Harness now; publish post-C2/O3 |
| P3 `[+]` | `graph.graph_table()`: standard SQL/PGQ pattern grammar incl. variable-length forms core rejects, resolved against imported property graphs; GQL-parser frontend adaptation feeding the typed adapter seam (`query/sqlpgq_adapter.rs`) | P1 | Compatibility matrix function; differential test vs PG19 on fixed-depth patterns | GA + 0–6 mo |
| P4 `[+]` | CustomScan/planner-hook feasibility prototype on GRAPH_TABLE join trees; outcome is a written finding either way (feasible → slice; not → upstream hook proposal with LDBC evidence) | P1, P3 | Finding documented + decision | GA + 6–18 mo |

**Register edits required with P1/P3** (doc 08 §4): reword the roadmap
"Reserved Features" SQL/PGQ row and the `sqlpgq_adapter.rs` doc comment —
catalog import and the pattern-text surface no longer wait for PostgreSQL
hooks; only transparent acceleration (P4) does. Scope all "replace native
graph databases" language as *workload* replacement, cross-referenced to the
existing non-goals table.

## Stage 3 — Make `live` mode real

Depends on Stage 1 (C1, C3 hard prerequisites). All `[=]` plus one addition.

| Slice | Register | What | Merge gate |
|---|---|---|---|
| L1 `[=]` | roadmap | Auto-maintenance consumes `sync_health()` booleans; adaptive cadence; non-Docker setup documented | Soak test: recommendations acted on; cadence tightens under pressure |
| L2 `[=]` | roadmap | `mutable_overlay` requires `persist_on_build = on` (no silent degrade) | pgrx refusal test; docs |
| L3 `[=]` | KI-023 | Weighted shortest path over layered overlays | Proptest: dirty-overlay results ≡ post-compaction; rejection path removed |
| L4 `[=]` | KI-021 | Benchmark + verification signoff; then relax `mutable_enabled` double gate | Published numbers; KI-021 cleared |
| L5 `[+]` | roadmap | **WAL/logical-decoding sync design** (implementation stays Stage 6 R4): consumer shape, slot management, trigger-mode coexistence | Design doc reviewed; Stage 3 choices don't preclude it |

## Stage 4 — Hybrid `auto` mode `[=]`

Depends on Stage 3. H1 (empty-overlay fast path, part of KI-005) and H2
(`projection_mode = 'auto'` policy layer) exactly as doc 07.

## Stage 5 — Performance (benchmark-driven)

| Slice | What | Status |
|---|---|---|
| F1 `[^]` | **Per-generation artifact validation cache** (kills the ~4.4 s first-backend cost; validate once per generation cluster-wide, not per backend) | Promoted out of "measure first" — the measurement exists. Schedule after Stage 2; required before head-to-head marketing claims |
| F2 `[=]` | Tenant-state borrow in `BfsConfig` | Measure-first rule applies |
| F3 `[=]` | Frontier pre-allocation clamp | Measure-first rule applies |
| F4 `[+]` | Shared mmap sections for reverse CSR / filter index / edge-type registry (answers the `architecture-tradeoffs.mdx` open question: yes) | Prerequisite for F5; benchmark backend-count scaling |
| F5 `[+]` | Direction-optimizing BFS (top-down/bottom-up switching) | After F4; LDBC-verified win required |

## Stage 6 — Larger refactors `[=]`

R1 (KI-022 overlay unification), R2 (KI-025 builder regclass parity),
R3 (KI-026 endianness guard), R4 (WAL sync **implementation** — design done in
L5; background pre-applier).

## Cross-cutting rules `[=]`

Unchanged from doc 07: 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 current baselines before claiming
completion.

## Dependency picture

```text
S0 CI ──┬── Stage 1 (C1..C5) ─────────── Stage 3 (L1..L5) ── Stage 4 (H1,H2)
        ├── Stage 2 (O1..O5)                   │
        ├── Stage 2P: P1 import ── P3 graph_table() ── P4 hooks finding
        │        └── P2 harness ──(publish gated on C2+O3)
        ├── Stage 5: F1 now; F4 ── F5; F2/F3 measure-first
        └── Stage 6 last (R4 impl after L5 design)
```