# 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 remains the authoritative issue register. Higher-priority hardening
work from the previous completion plan is now recorded in the completed-items
table 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

<Callout type="info">
No currently tracked next-update items remain in this category after `v0.1.2`.
The previously listed edge endpoint validation and hydration numeric comparison
issues were completed: invalid edge endpoints now fail as structural errors, and
large JSON integers preserve exactness without implicit string/number matches.
</Callout>

### SQL Contract and Query Semantics

<Callout type="info">
No currently tracked next-update items remain in this category after the filter
model and legacy numeric filter work moved public traversal filtering onto the
structured typed-filter path only.
</Callout>

### 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

<Callout type="info">
No currently tracked next-update items remain in this category after scheduler
ownership and background-job failure handling were completed.
</Callout>

### Internal Construction and Performance

<Callout type="info">
No currently tracked next-update items remain in this category after traversal
result metadata became adaptive for sparse visit budgets while retaining dense
metadata for high-coverage result conversion.
</Callout>

## 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 items remain after persistence status phases and
interrupt checks were added while preserving synchronous durability.
</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.

<Callout type="info">
No currently tracked P1 query-performance rows remain after source-search
rechecks, aggregation hydration lookup ownership, and traversal result metadata
were completed.
</Callout>

## 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.

<Callout type="info">
No currently tracked P2 rows remain after structured traversal filters gained
text substring and prefix predicates alongside equality, membership, range, and
null checks.
</Callout>

## P3: Internals and Maintainability

These are mostly contributor-facing improvements. They help long-term velocity,
but they do not change core user behavior.

| Area | Current limitation | Planned direction |
|---|---|---|
| pg test layout | Some PostgreSQL integration test files are still included textually from `lib.rs` because pgrx `#[pg_schema]` currently requires an inline `mod {}` body for generated SQL tests. | Revisit when the pgrx macro supports out-of-line modules or when the pg test harness is reorganized around macro-compatible test modules. |

## 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.