# Known Issues

<Callout type="warning">
pgGraph is currently alpha software. Do not use it for production workloads
until the next correctness, SQL contract, persistence, and operational
hardening update lands.
</Callout>

<Callout type="info">
pgGraph is built around a simple launch standard: the most critical correctness,
durability, safety, and operational paths should be solid first. There is always
another way to optimize a graph engine, especially inside PostgreSQL, so we are
launching with the critical paths working and then continuously improving in
the open.
</Callout>

This page documents known alpha limitations, next-update hardening work, and
lower-priority follow-up items. The list is ranked by expected user impact, not
by implementation difficulty.

This page is the authoritative register for known limitations and correctness,
operational, performance, or maintainability risks. Future product direction,
new APIs, and feature expansion belong in [Roadmap](./roadmap). Completed
hardening work remains documented in historical release notes and the resolved
summaries below.

Low-level PostgreSQL extension work involves real tradeoffs. Some optimizations
make a query faster by keeping more data in memory, while others reduce memory
pressure by doing more work per request. pgGraph has to weigh those choices
carefully because it runs inside PostgreSQL backend processes rather than a
separate service with its own resource envelope.

## Next Update Scope

The next update is focused on issues that are either hard to change after users
depend on SQL behavior, or important enough to fix before recommending
production use.

### Data Correctness and Corruption

| ID | Issue | Status | Notes |
|---|---|---|---|
| KI-001 | GQL mutable writes should re-check matched predicates at the final PostgreSQL write boundary under concurrent source-row changes. | Planned hardening | Current narrow writes use PostgreSQL-first DML and row-level behavior, but the remaining hardening item is to make stale-match drift explicit for `SET`, `REMOVE`, `DELETE`, and `DETACH DELETE` weak paths. |

### SQL Contract and Query Semantics

| ID | Issue | Status | Notes |
|---|---|---|---|
| KI-002 | Transaction-created nodes are visible to node-only GQL reads, but traversal/path entry-point behavior for those tx-local nodes remains intentionally narrow. | Planned clarification | Either reject unsupported traversal/path use with a typed error or add temporary-ID traversal support. Keep the documented mutable-overlay contract aligned with the implemented policy. |
| KI-003 | The GQL and Cypher parser surfaces need dedicated fuzz targets beyond unit and pgrx coverage. | Planned test hardening | Parser totality has unit coverage for representative corpora, but fuzz targets should be added for sustained random input coverage before broadening language syntax. |

### SQL Safety and Schema Plumbing

<Callout type="info">
No currently tracked next-update items remain in this category after dynamic
table SQL and discovery SQL parameterization work.
</Callout>

### Persistence and File Format

<Callout type="info">
No currently tracked next-update items remain in this category after artifact
writes moved to a streaming writer for fixed graph sections.
</Callout>

### Sync, Jobs, and Operator Semantics

| ID | Issue | Status | Notes |
|---|---|---|---|
| KI-004 | pgGraph has a scheduler-safe `graph.run_scheduled_maintenance()` entry point, but no always-on internal scheduler for trigger-sync apply and overlay compaction in non-Docker installs. | Planned operational hardening | Docker installs can use the bundled `pg_cron` schedule, and other deployments can call `graph.run_scheduled_maintenance()` from `pg_cron`, cron, or an application scheduler. A future built-in scheduler should make the default trigger-sync experience require less external orchestration while preserving operator control over rebuild cost. |

### Internal Construction and Performance

| ID | Issue | Status | Notes |
|---|---|---|---|
| KI-005 | Overlay neighbor merging and transaction-delta lookups still have optimization opportunities in traversal hot paths. | Measure before optimizing | Current behavior is correctness-gated. Future work should use benchmarks before changing duplicate suppression, overlay indexing, or transaction delta snapshotting. |

## P0: Operational Visibility and Resource Predictability

These are the highest-priority public follow-ups because they affect operators
running larger graphs or higher sync volume.

<Callout type="info">
No currently tracked P0 rows remain after `graph.memory_profile()` added
instance-level sizing visibility for concurrent graph-using backends. Memory
limits remain per backend; use `graph.memory_profile(concurrent_backends)` for
capacity planning rather than treating `graph.memory_limit_mb` as a
cluster-wide hard cap.
</Callout>

## P1: Query Performance Follow-Ups

These items are expected to improve latency or memory pressure, but they are
not changes to the public SQL contract.

| ID | Issue | Status | Notes |
|---|---|---|---|
| KI-005 | Overlay neighbor merging and transaction-delta lookups still have optimization opportunities in traversal hot paths. | Measure before optimizing | Duplicated here because it is an internal construction item with user-visible latency implications on dirty mutable projections. |

## P2: SQL Ergonomics and Documented Semantics

These items clarify behavior or broaden the API. They are planned, but should
not block use of the current documented SQL surface.

| ID | Issue | Status | Notes |
|---|---|---|---|
| KI-006 | `graph.cypher()` is a narrow openCypher compatibility preview over pgGraph's supported GQL subset, not full openCypher compatibility. | Documented limitation | Keep compatibility rows honest and route broader openCypher expansion through [Roadmap](./roadmap), not this register. |
| KI-007 | SQL/PGQ remains an internal adapter seam, not a public SQL API. | Deferred public surface | Track public SQL/PGQ exposure in [Roadmap](./roadmap) after PostgreSQL graph-pattern hooks stabilize. |

## P3: Internals and Maintainability

| ID | Issue | Status | Notes |
|---|---|---|---|
| KI-008 | Several implementation and test files exceed 1,000 lines, making review and focused weak-path testing harder. | Planned refactor | Highest-priority split candidates are `graph/src/pg_tests/gql.rs`, `graph/src/sql_facade/gql.rs`, `graph/src/query/tests.rs`, `graph/src/engine.rs`, `graph/src/query/semantics.rs`, `graph/src/query/value.rs`, `graph/src/bfs.rs`, and `graph/src/gql/parser.rs`. |
| KI-009 | GQL write weak-path tests can be expanded for more SQLSTATE and rollback scenarios. | Planned test hardening | Current release-gate coverage includes GQL transaction lifecycle scripts, pgrx GQL tests, playground fixtures, and unit tests. Additional weak paths should be added close to the code they constrain. |

## Roadmap-Owned Future Work

Do not use this known-issues register for broad feature wishes that are not
current limitations. Track these in [Roadmap](./roadmap) instead:

- broader GQL syntax and multi-pattern planning;
- public SQL/PGQ exposure;
- broader openCypher compatibility;
- semantic-guided search and pgVector ranking;
- WAL-driven sync;
- COPY build scanning;
- additional graph analytics;
- distributed graph execution.

## Lower-Priority Optimizations

These are intentionally deferred until measurement shows they matter:

- Avoiding small string allocations in config parsing and UUID parsing.
- Replacing bitmap serialized-size estimates with native roaring helpers if the
  pinned crate exposes them.
- Reducing low-level clone counts in builder, traversal, weighted path, and
  aggregation paths.
- Combining duplicate path reconstruction passes after the larger traversal
  allocation work is complete.
- Cleaning up long internal function signatures when the surrounding traversal
  parameters stabilize.
- Replacing manual pointer alignment checks with newer standard-library helpers
  once the supported Rust version makes that clean.
- Cleaning up padding-bit handling in `active_count()`.
- Moving from custom parse helpers to `FromStr` for SQL-facing enums.
- Introducing production newtypes for node indices and edge type IDs after
  benchmarking the hot paths.