Public Roadmap And Known-Issues Closure Ledger

Archived 2026-07-16: This is a planning snapshot, not an executable queue. The completed 1.0 release program owns R0-R7. Every undelivered direction is now POST-1.0 and owned by the public roadmap; no row in this file remains actionable for the release.

Purpose

This is the accountability map for clearing the current public Roadmap and Known Issues. Every public item must have exactly one disposition, one owning archived checkpoint, and objective evidence. A public row may not remain open only because it says “future”, “consider”, or “measure later”.

Inventory snapshot for 2026-07-09:

  • 6 Open Source V1 rows;
  • 10 Near-Term Roadmap rows;
  • 14 Reserved/Future rows;
  • 2 substantive future-work sections outside the tables;
  • 21 active Known Issues;
  • 4 resolved Known Issues awaiting retirement.

Status And Disposition

Value Meaning
ARCHIVED Historical state from before the 1.0 closure.
RESOLVED-RETIRE Behavior is shipped; verify release evidence and remove it from active Known Issues.
DEFER-TRIGGER Remove it from the active roadmap and record an explicit revisit trigger/non-goal.
CLOSED Evidence is linked and public docs have been updated.
POST-1.0 Active roadmap work that does not block the 1.0 release.

Allowed final dispositions:

  1. Graduate: move delivered capability into Roadmap Current Baseline and release notes, then remove its planned/reserved row.
  2. Retire: remove a resolved limitation from active Known Issues after its regression and release evidence is durable.
  3. Reject: remove the roadmap row and record the rationale/non-goal.
  4. Defer with trigger: remove it from active work and record the exact event that reopens it. “Someday” is not a trigger.

Closure Protocol

For each row:

  1. Start with the named failing/acceptance tests.
  2. Implement through the owning plan/checkpoint.
  3. Record exact commands, results, compatibility, migration, and performance evidence in progress.md or its linked report.
  4. Update API/operations docs and release notes.
  5. Graduate/retire/reject/defer the public row in the same checkpoint commit.
  6. Run a drift check proving every remaining public item appears exactly once in this ledger.

Add a repository check that inventories Roadmap table rows and KI-NNN IDs, compares them with stable IDs in this ledger, and fails on missing/duplicate coverage. Completed IDs remain in a short archive so identifiers are never reused.

Version 1.0 Public-Surface Rows

These rows are owned by R6 and R7 in the 1.0 release program.

ID Public item Owner Closure evidence Status
V1-DOC Documentation Quality and operations Docs inventory, internal/external link check, no duplicate SSOT pages, current install/query/ops/security examples. CLOSED
V1-PKG Packaging Quality and operations PG14-18 source/package/fresh-install/upgrade matrix green; PG19 joins only through PG19-0. CLOSED
V1-CI CI/CD Quality and operations Required unit/static, pgrx, heavy, fuzz, low-memory, concurrency, and release jobs exist at their documented cadence and retain evidence. CLOSED
V1-EXAMPLE Examples Quality plan plus this ledger Every maintained quick/realistic example executes in smoke CI and is linked from docs; stale examples are removed. CLOSED
V1-API API clarity GQL conformance and quality plans Generated/drift-gated inventory covers exported SQL functions, GUCs, reserved options, SQLSTATEs, volatility/security context, permissions, and version support. CLOSED
V1-OPS Operations Quality and operations Reproducible backup/restore, crash, concurrency, memory, package, generation rollback, and cleanup procedures pass release gates. CLOSED

Engine Roadmap Rows

ID Public item Owner Closure evidence Status
RM-01 Correctness and security Checkpoints 0, 1A, 1C and Rust boundary plan KI-014 through KI-025 closed; two-role, multigraph, filter/value, mapped-soundness, error-guard, definer-path, relation-identity, transaction, publication, and failure tests green. CLOSED
RM-02 Resource governance Memory governance, checkpoints 1B, 3, 5 Build/load/query/sync/compaction/analytics stay within hard envelopes or return typed resource errors. CLOSED
RM-03 Out-of-core build Memory/storage plans, checkpoint 2 Forced-spill build completes below heap requirement and is equivalent at a declared source watermark. CLOSED
RM-04 Full GQL conformance GQL plan, checkpoint 6 Every applicable ISO GQL row is green and generated public docs do not overclaim. POST-1.0
RM-05 Planner/runtime Planner plan, checkpoint 5 Costed streaming IR, spill, explain estimates/actuals, bounded pathological queries, and differential plan equivalence are green. The bounded subset required by the advertised 1.0 profile remains in R5. POST-1.0
RM-06 Storage and sync Storage plan, checkpoints 1C-3 Identity-preserving vNext generations, watermark catch-up, mmap residency, bounded compaction, crash/CAS tests green. CLOSED
RM-07 PostgreSQL 19 PG19 native property graphs, checkpoint 7 PG19-0 through PG19-5 complete; native mapping needs no duplicate registration; PG14-18 remain green. POST-1.0
RM-08 Refactoring Refactor plan, Rust boundary plan, checkpoint 4 Proposed mega-modules split with acyclic dependencies; canonical enums/newtypes and pgrx adapters replace stringly/raw boundaries; unsafe is allowlisted; SQL contracts and tests/benchmarks remain green. Release-risk subsets remain in R4. POST-1.0
RM-09 CI/CD rollout V1-CI and quality plan Each documented tier has a versioned workflow definition and retained release evidence. CLOSED
RM-10 Competitive evidence Planner/quality plans, checkpoint 8 Reproducible checked scorecards publish p50/p95/p99, throughput, RSS/PSS, spill, build/load, sync lag, and semantics. POST-1.0

Reserved And Future Roadmap Rows

ID Public item Required task or decision Closure evidence Status
RF-01 WAL-driven sync Implement logical-decoding input behind the shared SourceChange boundary, or reject it after measured trigger-volume evidence. Cover commit/subtransaction ordering, slot restart, schema change, watermark recovery, backpressure, retention, permissions, and trigger-vs-WAL equivalence. Supported-version crash/restart/equivalence/resource tests and operations docs; otherwise a recorded no-go and row removal. POST-1.0
RF-02 COPY build scanner Implement only if it preserves snapshot, validation, ACL/RLS, error, cancellation, and memory semantics of bounded SPI scans; otherwise remove the reserved GUC after a documented benchmark/no-go decision. Forced-low-memory equivalence and failure tests, or rejected disposition with GUC cleanup. POST-1.0
RF-03 Out-of-core build and maintenance Same owner as RM-02/RM-03/RM-06. All memory-plan acceptance gates green; graduate into Current Baseline. POST-1.0
RF-04 Relationship registration helper Run a documented usability/support-ticket gate after relationship identity is fixed. Either ship an unambiguous helper for edge-table keys/endpoints/type or declare graph.add_edge() final and improve diagnostics/examples. API/SQL contract tests if shipped, or evidence-based rejection and roadmap-row removal. POST-1.0
RF-05 Full ISO GQL Same owner as RM-04. Full applicable conformance ledger green; graduate. POST-1.0
RF-06 PostgreSQL SQL/PGQ PG19 plan and separate SQL/PGQ registry. Native catalog interop, GRAPH_TABLE differential results, security/DDL/version gates, clear acceleration boundary. POST-1.0
RF-07 openCypher compatibility Generate a narrow compatibility matrix from shared GQL capability metadata; deterministic unsupported errors; no independent planner/runtime. Decide whether the compatibility facade is a permanent bounded product surface. Docs never imply broad conformance; matrix/tests green; then retire limitation from Known Issues without requiring full openCypher. POST-1.0
RF-08 Online mutable overlays Storage/sync plan and checkpoints 1C/3. Transaction, cross-backend, crash, upgrade, rollback, bounded-memory, compaction, and source-of-truth gates green. POST-1.0
RF-09 Full GQL writes GQL plan checkpoint 6. Applicable ISO data-modification rows, set-based DML, savepoints, concurrency, RLS, rollback, and SQLSTATE gates green. POST-1.0
RF-10 Non-CSR mutable projection Storage plan checkpoint 3 plus release gates. Supported-version concurrency/crash/upgrade/rebuild/rollback suite, bounded maintenance, release docs, and benchmark signoff with no open P0 projection issue. POST-1.0
RF-11 pgVector embedding cache Decide sidecar versus derived artifact section; define stable node-ID/generation keys, invalidation, source/RLS boundary, bounded residency, update/rebuild, and no source lookup in the hot loop. Correctness/security tests and benchmark showing useful recall/latency or a rejected disposition. POST-1.0
RF-12 Full A* Implement only after defining an admissible heuristic for an explicit cost model; otherwise keep semantic guidance approximate and remove A* from active roadmap. Optimality differential tests against Dijkstra plus bound tests, or recorded no-admissible-model rejection. POST-1.0
RF-13 Additional analytics Select algorithms by demonstrated demand; run them in quota-controlled workers with cancellation, progress, failure isolation, and bounded/checkpointed state. Correctness oracle and memory/performance evidence per algorithm; never an unbounded OLTP call. POST-1.0
RF-14 Distributed execution Keep as a non-goal until checkpoint 8 evidence shows a single-database ceiling that cannot be solved locally. Revisit only on documented workload/scale trigger; otherwise move to deferred archive and remove the active row. DEFER-TRIGGER

Other Roadmap Prose That Needs A Disposition

ID Public item Required task or decision Closure evidence Status
RP-01 Semantic-guided search Define an explicitly approximate guided_path contract, signal normalization/weights, degree/type bias, deterministic ties, RLS-safe candidates, beam/work/memory caps, and result diagnostics. Recall/latency/resource benchmark against structural baselines, or reject until a user workload exists. POST-1.0
RP-02 Arena allocation Profile bounded parser/query scratch allocation after streaming runtime lands. Adopt only if allocator overhead is material; never present it as graph compaction. Before/after profile and unchanged budget/failure behavior, or remove the speculative paragraph. POST-1.0

Known-Issues Closure

Resolved rows remain here only until their release evidence is durable. They should not stay indefinitely on the active Known Issues page.

ID Owner/disposition Evidence required to remove from active Known Issues Status
KI-001 Retire hardened write recheck item Existing two-session stale-write gates green on release matrix; resolution retained in release notes. RETIRED
KI-002 Retire transaction-created-node item Existing read-your-writes and rollback tests green on release matrix; resolution retained in release notes. RETIRED
KI-003 Move parser fuzzing from issue to permanent quality policy Fuzz targets build, seed corpus runs in scheduled/release environment, and quality docs own ongoing campaigns. RETIRED
KI-004 Scheduler decision under V1-OPS Either ship a supervised per-database built-in scheduler with preload/auth/crash/quota tests, or declare external scheduling the supported final model with complete setup/health docs. POST-1.0
KI-005 Checkpoints 3, 5, 8 Representative dirty-overlay benchmarks identify and fix material regressions, or demonstrate current performance within an approved threshold; retain regression gate. POST-1.0
KI-006 RF-07 openCypher bounded-surface decision Generated compatibility matrix, deterministic rejection tests, and explicit non-conformance docs make the limitation a product boundary rather than an issue. POST-1.0
KI-007 RM-07/RF-06 and PG19 plan PG19-0 through PG19-5 and SQL/PGQ registry/differential gates green; release notes preserve the change. POST-1.0
KI-008 RM-08, refactor plan, and Rust boundary plan Named mega-modules are split at cohesive boundaries; RUST-2, RUST-3, and RUST-6 close stringly state, raw-ID, pgrx-adapter, and unsafe-allowlist gaps; SQL behavior remains stable. POST-1.0
KI-009 Checkpoints 0/6 and quality plan Enumerated write SQLSTATE, constraint, RLS, savepoint, concurrency, and rollback weak paths have permanent unit/pgrx/heavy tests. RETIRED
KI-010 Tooling maintenance task In a Nix-capable environment update both lock inputs, build the dev shell, run documented Rust/PostgreSQL/pgrx checks, and record versions; then retire. POST-1.0
KI-011 Retire serializer migration item Upgrade/rebuild documentation and corrupt/trailing-byte regression remain green; historical migration stays in release notes. RETIRED
KI-012 RM-02/RM-03, memory plan, checkpoints 1B/2 Read-only no longer masks over-budget build; stale/no stats and wide filters spill or fail before OOM under enforced RSS thresholds. RETIRED
KI-013 RM-02/RM-05/RM-06, checkpoints 1B/3/5 mmap load, paths, GQL, sync, projection reads, compaction, and analytics all use hard byte/work budgets and pathological stress gates. RETIRED
KI-014 RM-01 checkpoint 1A Two-role tests prove hidden nodes/relationships cannot affect coordinates, topology, counts, paths, existence, hydration, or error side channels. RETIRED
KI-015 RM-01/RM-06 checkpoints 1A/2 Stable source relationship identity preserves parallel edges through artifact, overlays, paths, writes, rollback, sync, hydration, and compaction. RETIRED
KI-016 RM-01 checkpoint 1A Same-named filter columns on different graph/table/attributes remain distinct through build, pushdown, persistence, sync, and load. RETIRED
KI-017 RM-01/RM-06 checkpoint 1C Two PostgreSQL backends cannot fork/overwrite a generation; lock/reload/CAS/crash tests preserve one current manifest. RETIRED
KI-018 RM-01/RM-06 checkpoints 1C/2 Injected write/checksum/mmap validation/catch-up failure leaves the old generation current and queryable. RETIRED
KI-019 RM-01/RF-09 checkpoints 1A/6 and QA-01 Mutable GQL writes support PostgreSQL savepoint rollback/release through per-subtransaction delta frames, with READ COMMITTED, REPEATABLE READ, and SERIALIZABLE two-session gates. RETIRED
KI-020 RM-01 and RUST-00A through RUST-00B Out-of-range/corrupt mapped-layout tests cannot reach unchecked pointer arithmetic; only an owning validated layout constructs stores; Miri/in-memory backing plus PostgreSQL sanitizer matrix is green. RETIRED
KI-021 RM-01 and RUST-00C Rust destructors unwind through the supported pgrx guard before PostgreSQL ERROR; SQLSTATE/diagnostic behavior is versioned and exact on every supported major; no deep raw errfinish() remains. RETIRED
KI-022 RM-01/RM-06 and RUST-00D/RUST-5 Every filter value domain roundtrips through build, sync, persisted segment, restart, and reload; old/new format behavior is documented and differential results match. RETIRED
KI-023 RM-01 and RUST-00E Every security-definer function has the vetted proconfig search path and shadow-schema attack tests prove catalog/function/operator resolution cannot be redirected. RETIRED
KI-024 RM-01/RM-06 and RUST-00F OID-stable relation identity survives rename/search-path change, serializes with concurrent DDL, and fails closed on drop/recreate across every supported major. RETIRED
KI-025 RM-01/RM-08 and RUST-1 Failure injection proves background-worker transactions do not commit unintended partial state or leave stuck jobs; intentional progress checkpoints are documented and tested. RETIRED
KI-026 RM-01/RM-06 Durable post-build node identity, cross-backend lifecycle, writer horizons, and publication locks remain exact across every supported PostgreSQL major. RETIRED

KI-013 Subsystem Gates

KI-013 closed after every child became a permanent release gate:

  • [x] KI-013A load: preflight plus mmap inbound/filter metadata; failure keeps the old backend engine; repeated loads stay within private-memory cap.
  • [x] KI-013B query/path: candidates, degree, expansions, frontier, paths, hydration, sort, group, DISTINCT, result bytes, and interrupts are bounded.
  • [x] KI-013C sync ingest: input and normalized deltas obey byte/row/disk budgets and preserve watermark/idempotency under crash.
  • [x] KI-013D projection reads: one pinned mapped snapshot per generation; no per-query full-file decode/map rebuild.
  • [x] KI-013E compaction: source-range merge stays bounded and equivalent to clean rebuild across repeated cycles.
  • [x] KI-013F analytics: whole-graph work is worker-isolated, quota-bound, cancellable, observable, and cannot OOM an OLTP query backend.

Explicit Orphan Work Packages

These tasks had no sufficiently explicit owner in the original plans:

OPS-01 Maintenance Scheduler Decision

  • Either implement a supervised per-database scheduler with enable/disable, cadence, admission, no-duplicate two-backend behavior, crash/restart idempotency, role/database context, and PG14-19 tests;
  • or declare pg_cron/external scheduling the final supported contract, remove the built-in promise, and prove setup/health/failure docs are sufficient.

Closes KI-004.

PERF-01 Dirty Projection Benchmark

Benchmark base degree, segment depth, tx inserts/deletes/tombstones, directional reads, weighted/unweighted reads, and concurrency. Record correctness checksum, allocations, p95/p99, and an approved regression threshold.

Closes KI-005 when optimizations land or evidence shows no material problem.

QA-01 GQL Write Failure Matrix

For every supported write cover readonly/unmapped/type failures, constraints, triggers, ACL/RLS, stale/disappeared matches, cancellation, rollback, and savepoints. Verify both PostgreSQL rows and projection/transaction deltas after failure, with stable SQLSTATE assertions.

Closes KI-009 and contributes to KI-019.

QA-01 is complete. The permanent PG14-18 matrix covers the supported write families, SQLSTATE and rollback behavior, transaction isolation, durable projection visibility, and deterministic concurrent-writer races.

TOOL-01 Nix Input Refresh

In a Nix-capable environment update nixpkgs and rust-overlay, run nix flake check/show, enter and verify default plus PG14-18 shells, check Rust/cargo-pgrx/PG_CONFIG, run a representative build/test, and archive exact revisions/commands. Assign recurring freshness ownership.

Closes KI-010.

META-01 Public Backlog Drift Check

Add a CI script that extracts active Roadmap rows and every KI-NNN ID, checks for exactly one corresponding ledger ID/status, rejects duplicate/open orphan rows, and requires closed IDs to appear in the archive/release evidence.

Closes the traceability gap that allowed public work to exist without an executable work item.

“Public Backlog Clear” Gate

The current Roadmap and Known Issues are clear only when:

  • every 1.0 item above is CLOSED or RETIRED, and every undelivered direction is POST-1.0 with public-roadmap ownership;
  • every delivered roadmap row has graduated into Current Baseline and release notes;
  • every resolved KI row has left active Known Issues and its regression remains in CI;
  • no roadmap row, reserved feature, KI ID, or substantive future-work section is missing from the drift inventory;
  • progress.md points to the next remaining stable ID rather than duplicating its task text;
  • all checkpoint compatibility, docs, package, test, memory, security, and benchmark evidence is archived.

This gate clears the existing public backlog; new discoveries receive new stable IDs rather than silently extending a closed item.