LiteGraph Next Release Improvement Plan

Status Key: [ ] Not started | [~] In progress | [x] Complete | [!] Blocked | [?] Needs decision

Last updated: 2026-04-17

Release target: Next LiteGraph release

Audience: Public roadmap plus maintainer execution plan

Release Goal

This release is a strategic architecture release. The goal is to make LiteGraph more useful as a production graph database by adding:

a native graph query capability with familiar graph-query syntax
graph-scoped transactional mutations
provider-neutral storage with SQLite as the default and PostgreSQL as the recommended production backend
RBAC and scoped credentials at REST/MCP boundaries
production observability with Prometheus and OpenTelemetry

All five areas are P1 for this release. The release should be planned as one coordinated effort because these items overlap at the repository, request handling, authorization, testing, and SDK/MCP surfaces.

Non-Negotiable Constraints

SQLite remains the default zero-config backend.
PostgreSQL is the recommended production backend.
The storage architecture must be designed so MySQL and SQL Server can be added without redesign.
Storage backend implementations live inside the main LiteGraph project, following the provider folder pattern used in C:\code\Verbex\Verbex\src\Verbex\Database.
Query execution should prefer repository-level planning/execution. LiteGraphClient methods may be used where they are the correct abstraction.
Transactions are limited to one tenant and one graph.
Transactions can mutate graph child objects only: nodes, edges, labels, tags, and vectors.
Query mutations can mutate graph child objects only and must not update graph metadata.
Vector search in the query language accepts supplied embeddings/vectors. LiteGraph will not generate embeddings in this release.
RBAC is enforced at REST and MCP boundaries only. Core LiteGraphClient and repository APIs remain permission-agnostic.
Existing users and credentials must retain effective full access after migration.
Request history remains supported and should be used as a subordinate source for observability.
Test coverage should be built into Test.Shared and exposed through Test.Automated, Test.Xunit, and Test.Nunit.
SDK, MCP, and dashboard work is required where the feature has a relevant user-facing surface.

Release Sequencing

The work should be delivered in this order, even though all items are P1:

Storage architecture and request lifecycle foundations.
Transactions and repository execution primitives.
Query language design decisions, then parser/planner/executor.
RBAC and scoped credential enforcement at REST/MCP boundaries.
Observability instrumentation, metrics, traces, and dashboard/docs.
SDK, MCP, dashboard, and full test matrix completion.

This ordering reduces rework. Query execution, transactions, RBAC, and observability all depend on the storage and request lifecycle work.

0. Release Architecture Gates

Priority: P1 Status: [x] Complete for release gating; implementation is now unblocked Impact: Prevents incompatible implementations across query, storage, RBAC, SDKs, and MCP

0.1 Query Language Direction

Decision:

Selected profile: Cypher/GQL-inspired LiteGraph-native query profile.
Use Cypher-style graph pattern syntax for user familiarity.
Align with ISO GQL where practical.
Do not claim full openCypher, Neo4j Cypher, or ISO GQL conformance in this release.
Gremlin, SPARQL, SQL/PGQ, and GraphQL are not native query-language targets for this release.
Feature name in code and docs: native graph query or LiteGraph native graph query. Do not use "LiteQL" unless a separate naming decision revives it later.

Decision criteria:

familiar to graph database users
practical to implement in this release
maps cleanly to LiteGraph nodes, edges, labels, tags, data, and vectors
supports mutations without forcing graph metadata changes
supports repository-level planning
does not lock LiteGraph into Neo4j-specific behavior unless explicitly chosen

Deliverables:

Short design note comparing candidate query syntax options.
Final decision on syntax compatibility target.
Final naming decision for the feature.
- 20+ example queries covering reads, traversals, filters, vector search, and mutations.
Query feature marked unblocked only after this decision is recorded.

0.2 Query Parameter Model

Decision:

allow inline literals for simple constants
support separate parameters for user input, vectors, large JSON payloads, and reusable queries
require errors for missing parameters
preserve JSON/object parameter values instead of forcing string interpolation

Why separate parameters may be needed:

avoids string escaping bugs in generated queries
improves safety for mutation queries
preserves value types for GUIDs, numbers, booleans, arrays, objects, and vectors
avoids embedding large vector arrays directly in query text
enables query plan caching later
creates a cleaner SDK and MCP contract for user-provided values

Possible request shape:

{
  "Query": "MATCH (n:Person) WHERE n.data.age > $age RETURN n",
  "Parameters": {
    "age": 30
  }
}

Deliverables:

Decide whether parameter binding is required for this release.
Decide whether inline literals are supported.
Define parameter value types.
Define error behavior for missing, unused, or type-invalid parameters.
Define SDK/MCP request models after the decision.

Acceptance Criteria

Query language implementation started only after 0.1 and 0.2 were resolved.
The selected query syntax is documented with examples before full parser work begins.
SDK, MCP, REST, and tests all use the same query request contract when each surface is added.

1. Provider-Neutral Storage Backends

Priority: P1 Effort: Very Large Status: [x] Completed for SQLite and PostgreSQL; MySQL and SQL Server remain explicit placeholders behind the provider-neutral contract Impact: Removes SQLite-only architecture assumptions and enables production deployment on PostgreSQL

Why This Matters

SQLite is excellent as the zero-config default.
Production deployments need server-backed storage, write concurrency, operational tooling, replication, and backup workflows.
PostgreSQL is the first production backend.
MySQL and SQL Server should be supported by architecture, settings, and provider boundaries without forcing a later redesign.

Implementation Steps

Verification

dotnet build src\LiteGraph.sln -f net8.0
dotnet run --project src\Test.Automated\Test.Automated.csproj --framework net8.0 with LITEGRAPH_TEST_POSTGRESQL_CONNECTION_STRING against a disposable PostgreSQL 16 container: 429 total, 427 passed, 0 failed, 2 skipped (Mysql, SqlServer placeholder suites).

Acceptance Criteria

SQLite remains default and backward compatible.
PostgreSQL passes the same core repository test suite as SQLite.
Server startup selects storage backend by configuration.
PostgreSQL supports concurrent writes from multiple server instances.
Existing LiteGraph data can be migrated from SQLite to PostgreSQL with verification.
MySQL and SQL Server can be added without changing public repository contracts.

2. Graph-Scoped Transactions

Priority: P1 Effort: Large Status: [x] Complete; graph-scoped transaction model, execution, SDK helpers, MCP, dashboard API Explorer support, and transaction coverage are implemented Impact: Provides all-or-nothing graph child mutations

Why This Matters

Creating a meaningful graph change often requires multiple node, edge, label, tag, and vector writes.
Today, failure in the middle of a multi-step workflow can leave partial graph state.
Transactions are required for reliable imports, migrations, agent operations, and query-language mutations.

Scope

Transactions are limited to:

one tenant
one graph
graph child objects only: nodes, edges, labels, tags, vectors

Transactions do not include:

tenant creation/update/delete
graph creation/update/delete
user or credential management
backup/restore
cross-graph operations
cross-tenant operations

Implementation Steps

Acceptance Criteria

Multi-operation graph child mutations succeed or fail atomically at the database layer.
Transactions cannot cross tenant or graph boundaries.
Failed transactions leave no partial DB mutations.
Failure response identifies the failing operation.
Vector index consistency is recoverable through dirty marking or rebuild.
SDK and MCP support is available where appropriate.

3. Native Graph Query Language

Priority: P1 Effort: Very Large Status: [x] Complete; parser/planner/executor-backed reads, fixed and bounded variable-length traversals, shortest and optional matches, graph-child CREATE/UPDATE/DELETE mutations, supplied-vector search, REST, C#/Python/JavaScript SDK helpers, MCP, API Explorer support, DSL docs, console execution, and shared test coverage are implemented Impact: Enables one-call graph traversal, filtering, vector search, and mutation

Why This Matters

Traversals often require multiple REST calls today.
A native query endpoint lets users express graph intent in a single request.
AI agents benefit from structured query and mutation capabilities.
The query language should use syntax familiar to the larger graph database user base while preserving LiteGraph-native behavior.

Scope

The query language must support:

graph-scoped execution only
reads and traversals
filtering by labels, tags, name, data fields, and vector similarity
returning full LiteGraph objects
mutations of nodes, edges, labels, tags, and vectors
repository-level planning and execution where possible
cancellation and timeout

The query language must not support:

cross-tenant queries
cross-graph queries in this release
graph metadata mutation
tenant/user/credential/admin mutation
embedding generation

Implementation Steps

Acceptance Criteria

A user can execute a single graph-scoped query that matches patterns, filters data, performs vector similarity, and returns full LiteGraph objects.
A user can execute graph child object mutations through the query endpoint.
Mutation queries are database-atomic through transaction infrastructure.
Syntax errors include line and column.
Query timeout prevents runaway queries.
Query execution uses repository-level planning where practical.
Query language decision and parameter model are documented before implementation.

4. RBAC and Scoped Credentials

Priority: P1 Effort: Large Status: [x] Complete; credential scopes, graph allow-lists, stored role/assignment policies, effective-permission caching/invalidation, authorization audit, REST role/scope management endpoints, MCP role/scope tools, MCP boundary enforcement for existing tools, PostgreSQL schema support, dashboard management UI, and dashboard tests are implemented Impact: Provides enterprise-grade access control at REST and MCP boundaries

Why This Matters

Current authorization primarily enforces tenant isolation.
Enterprises need read-only users, graph-level restrictions, scoped service credentials, and auditability.
RBAC must be added without breaking existing deployments.

Scope

RBAC applies to:

REST requests
MCP tools
dashboard workflows that call REST APIs

RBAC does not apply inside:

LiteGraphClient
repository interfaces
direct embedded use of LiteGraph

Implementation Steps

Acceptance Criteria

Viewer and Editor roles work out of the box.
Graph-level permissions isolate restricted graphs within a tenant.
API credentials can be scoped to least privilege.
Existing deployments retain effective access after migration.
Authorization is enforced consistently at REST and MCP boundaries.
Permission checks add minimal request overhead when cached.

5. Observability

Priority: P1 Effort: Large Status: [x] Complete for this release slice; Prometheus, OpenTelemetry/OTLP, profiling, request-history correlation, JSON request logs, dashboard, docs, and tests are implemented Impact: Enables production debugging, metrics, tracing, and performance analysis

Why This Matters

Production users need standard monitoring and tracing.
Prometheus and OpenTelemetry are the priority targets.
Existing request history should be used as supporting operational data, not replaced.

Implementation Steps

Acceptance Criteria

Prometheus metrics cover the primary operational signals.
OpenTelemetry traces cover REST, auth, repository, query, transaction, and vector search work.
/metrics works out of the box.
Request history remains available and is correlated with observability IDs.
Sensitive data is not exposed in metrics, traces, logs, or request history.

6. SDK, MCP, Dashboard, and Documentation Integration

Priority: P1 Effort: Medium to Large Impact: Makes the release usable across all LiteGraph entry points

Implementation Steps

Acceptance Criteria

Each new user-facing feature has REST documentation.
SDKs expose the features where appropriate.
MCP exposes the features where appropriate.
Dashboard includes support where appropriate.
Documentation includes migration and operational setup guidance.

7. Test Strategy

Priority: P1 Effort: Large Impact: Ensures the release is safe across backends and entry points

Required Test Suites

Runner Requirements

Test descriptors live in src/Test.Shared.
Console execution through src/Test.Automated.
xUnit exposure through src/Test.Xunit.
NUnit exposure through src/Test.Nunit.
Tests create and clean up their own data.
Provider-specific tests can be skipped with clear skip reasons when dependencies are unavailable.

Acceptance Criteria

The same core behavior tests run against SQLite and PostgreSQL.
Release blockers are visible from Test.Automated.
xUnit and NUnit runners expose the shared suites.
Performance and benchmark tests are documented even if not run on every commit.

Release Acceptance Criteria

The release is complete when:

SQLite remains backward compatible and default.
PostgreSQL is production-ready and documented.
Storage architecture can support MySQL and SQL Server without redesign.
Graph-scoped transactions work for nodes, edges, labels, tags, and vectors.
Native query endpoint supports reads, traversals, vector search, and child-object mutations.
Query language syntax and parameter model decisions are documented in DSL.md.
LiteGraphConsole is available as a solution project and can be installed as the lg global tool for local database or remote endpoint sessions.
RBAC and scoped credentials are enforced at REST and MCP boundaries.
Existing users and credentials retain effective full access after migration.
Prometheus metrics and OpenTelemetry tracing work out of the box.
Request history is correlated with observability IDs.
SDK, MCP, dashboard, and docs are updated where appropriate.
Tests are implemented in Test.Shared and exposed through automated, xUnit, and NUnit runners.

Remaining Query Work

The query language is no longer blocked by product decisions. The current implementation is a parser-backed Cypher/GQL-inspired LiteGraph-native profile for node MATCH, edge MATCH, fixed directed multi-hop MATCH, bounded variable-length path MATCH, MATCH SHORTEST, top-level read-only OPTIONAL MATCH, equality predicates over GUID/name/data fields, numeric comparison predicates over data fields, string predicates over supported name/data fields, OR/NOT/AND predicate expressions, list predicates, tag predicates, aggregate returns, ORDER BY, node/edge/label/tag/vector CREATE, graph-child SET and DELETE mutations, supplied-vector search through CALL litegraph.vector.searchNodes(...), REST execution, C#/Python/JavaScript SDK execution, MCP graph/query, API Explorer execution templates, and LiteGraphConsole execution.

FilesExpand file tree

IMPROVEMENTS.md

Latest commit

History

IMPROVEMENTS.md

File metadata and controls

LiteGraph Next Release Improvement Plan

Release Goal

Non-Negotiable Constraints

Release Sequencing

0. Release Architecture Gates

0.1 Query Language Direction

0.2 Query Parameter Model

Acceptance Criteria

1. Provider-Neutral Storage Backends

Why This Matters

Implementation Steps

Verification

Acceptance Criteria

2. Graph-Scoped Transactions

Why This Matters

Scope

Implementation Steps

Acceptance Criteria

3. Native Graph Query Language

Why This Matters

Scope

Implementation Steps

Acceptance Criteria

4. RBAC and Scoped Credentials

Why This Matters

Scope

Implementation Steps

Acceptance Criteria

5. Observability

Why This Matters

Implementation Steps

Acceptance Criteria

6. SDK, MCP, Dashboard, and Documentation Integration

Implementation Steps

Acceptance Criteria

7. Test Strategy

Required Test Suites

Runner Requirements

Acceptance Criteria

Release Acceptance Criteria

Remaining Query Work