[qiansheng91]

Summary

Add a gremlin GraphStore provider so UModel can persist models, entities, and topology through a TinkerPop Gremlin Server. umodel-server and umodel-mcp accept --graphstore gremlin, with verified TLS, optional SASL authentication, and the existing SPL/read-only Cypher query contracts.

Motivation

Gremlin-backed graphs could not previously be selected as UModel storage. The new provider is validated against real Gremlin Server 3.7.3 instances through the existing query and client suites, including application/database restarts and failure paths.

Changes

• Persist workspace-scoped vertices and relations over synchronous GraphSON 3 WebSocket requests. Support custom PEM CAs, bounded operations, parameter bindings, lifecycle/history semantics, and fail closed on transport cancellation without replaying writes.
• Add isolated test fixtures and make test-gremlin-matrix, covering plain and authenticated TLS connections, TinkerTransactionGraph rollback, TinkerGraph partial-write behavior, disconnection, and persistent graph restart. Run the matrix in CI and parameterize Query Service, REST, CLI, MCP, golden, and UI tests for Gremlin.
• Restore derived schema/search indexes from persisted records at startup; prevent rejected or superseded entity mutations from corrupting search state; fix planning-stage timeout errors and workspace pagination.
• Decode the current REST query matrix envelope in the Go service SDK and exercise its public methods against the real backend.
• Add aligned English/Chinese provider configuration and deployment limits.

Test plan

• make test-service and make guard
• make ci (service builds, race-enabled tests, SDK verification, schema/examples/docs checks)
• make expand
• UMODEL_CONTAINER_RUNTIME=podman make test-gremlin-matrix: complete plain/TLS/authenticated query and client suites, transactional rollback, non-transactional failure semantics, server disconnect, and database restart/search recovery
• Go 1.22 offline container: provider, query, bootstrap, entitystore, and workspace tests
• make test-ui with repository-pinned pnpm 9.15.9
• UMODEL_TEST_GRAPHSTORE=gremlin make test-ui-e2e: all 18 browser/API checks passed against the real Gremlin-backed quickstart
• git diff --check; Chinese README copies are identical

Compatibility

Requires a WebSocket endpoint with GraphSON 3 and bound gremlin-groovy scripts. Public reads continue through Query Service. One writing provider instance per graph is required, and requests are limited to 1 MiB. Backend-specific indexes and constraints remain operator-managed.

Rollback is verified on TinkerTransactionGraph; non-transactional TinkerGraph can retain partial writes after a server failure. graph-match is not advertised by this provider, and its PROVIDER_UNSUPPORTED response is tested. The default embedder remains noop; the matrix validates search routing and index recovery rather than embedding quality.

Out of scope

Arbitrary user Gremlin execution, distributed writer coordination, and compatibility certification for other hosted Gremlin backends.