AGE: add native ShortestPath support after Apache AGE 1.8.0 releases

[savasp-agent]

Outcome

Implement native AGE support for ShortestPath and AllShortestPaths only after Apache AGE 1.8.0 is officially released and the released capability can meet the CVOYA semantics below.

This is a v1.x feature. It is explicitly postponed from the v1.0 release by @savasp; it no longer blocks #481, #393, #417, or v1.0 closeout.

v1.0 disposition — required current contract

Apache AGE 1.7 is the current official release. As of 2026-07-22, Apache AGE's official download page lists 1.7.0 as the latest stable release; master code, release candidates, or an unreleased upgrade script are not a supported basis for CVOYA Graph.

Until a released, supportable AGE 1.8.0 is available:

• AGE must not declare GraphCapability.ShortestPath.
• The packaged TCK ShortestPaths_PinSelectionEndpointDirectionNoPathAndSameNodeSemantics test remains capability-gated and is reported as an expected AGE skip.
• AGE translation must reject reachable shortest-path queries with GraphQueryTranslationException naming GraphCapability.ShortestPath; it must not use a finite-depth, client-side, or PostgreSQL fallback.
• Public provider guidance, querying documentation, and src/Graph.Age/COMPLIANCE.md must report ShortestPath as unsupported on AGE. The v1.0 documentation PR (Point the CVOYA Graph README at the first tagged source release #345/Correct in-memory full-text-search XML documentation #392/Correct provider/TCK guidance for capabilities, infrastructure failures, and disposal #394/Refresh public documentation for the current API, layout, examples, and package set #396/Document the keyless identity model and migration path #482) owns final public wording.
• v1.0 certification must report this intentional unsupported capability separately from unplanned skips, alongside the intentional lack of bare-entity ordering.

The release-candidate report must not claim that AGE implements shortest path merely because Neo4j and InMemory do.

Future start gate

Do not start implementation until all of these are true:

1. Apache publishes an official, non-RC 1.8.0 release artifact and release notes.
2. A reproducible supported AGE/PostgreSQL container or installation path is available for the repository test matrix.
3. The released public API—not an internal master-only function—can provide the required unbounded shortest-path semantics.
4. The implementer has re-read the released documentation and confirms this brief still fits it. If its semantics, licensing, or operational model do not fit, stop and push back with evidence rather than approximating the feature.

Required implementation after the gate

1. Verify the released AGE 1.8.0 API, installation/upgrade path, licensing, and supported runtime matrix.
2. Lower ShortestPath and AllShortestPaths to the released native capability—not client-side enumeration, a finite maximum depth, or a provider-local PostgreSQL graph algorithm.
3. Preserve independent selection for every source/endpoint pair and apply endpoint predicates before shortest-path selection.
4. Support outgoing, incoming, and both directions; exclude the source as an endpoint; preserve no-path and same-node behavior.
5. Return one minimum path for ShortestPath and every tied minimum path for AllShortestPaths.
6. Hydrate path segments/entities through the existing AGE result pipeline.
7. Declare GraphCapability.ShortestPath only after the complete inherited TCK contract passes on the pinned released version.
8. Update the support matrix, release container/image, dialect tests, provider guide, querying docs, and compliance documentation together.

Test plan

Cover cycles, ties, multiple sources/endpoints, all directions, endpoint filtering, no path, source exclusion, same-node behavior, one-path/all-tied-path semantics, parameter stability, and path/entity hydration. Run the complete strict AGE provider suite against the released pinned version and record the new capability in the compliance report.

Non-goals

• A v1.0 fallback, partial emulation, or release-skip workaround.
• Using an unreleased AGE build in the supported matrix.
• Legacy identity/storage support or alpha database compatibility.

Acceptance criteria

• Until the start gate is met, AGE remains explicitly unsupported in its capability declaration, the capability-gated TCK result, translation failure, provider guide, querying docs, and AGE compliance matrix.
• The AGE support matrix pins a released 1.8.0 runtime that exposes the native capability.
• The full inherited ShortestPath TCK contract passes without a hard-coded maximum depth.
• Provider integration tests cover cycles, ties, multiple sources/endpoints, direction, endpoint filtering, no path, and source exclusion.
• One-path and all-tied-path results hydrate correctly.
• The capability declaration, dialect tests, provider map, public docs, and compliance report agree.
• No client-side traversal fallback, legacy identity/storage path, or alpha compatibility code is introduced.

[savasp-agent]

v1.0 re-triage — 2026-07-21

Promoted to v1.0. Implement as the first standalone PR in the serial AGE-capability lane; it may start now and runs in parallel with the identity cutover and non-AGE lanes.

The existing technical brief and acceptance criteria remain authoritative, with this architecture correction: implement only against native logical AGE labels/types and private graphid correlation. Do not use universal Id lookup, CvoyaNode/CvoyaRelationship roots, or legacy database compatibility. Rebase before merge if the active cutover changes shared fixtures.

This PR must remove the ShortestPath capability skip, add provider-contract coverage for one/all shortest-path semantics and edge cases, and leave no declared-vs-executed inventory mismatch. Final #481 and #393 certification treat this as a required capability, not an accepted skip. Keep #356/#357 in later PRs to contain AGE planner/dialect conflicts.

[savasp-agent]

#355 has been deferred until Apache AGE 1.8 is released. PR #512 no longer implements or closes this issue: the interim PostgreSQL BFS fallback was removed, AGE 1.7 continues to omit GraphCapability.ShortestPath, and the provider-neutral TCK contract remains capability-skipped.

The issue body now requires the eventual implementation to use AGE 1.8's released native capability. Release evidence: AGE 1.7.0 remains the published download; master contains the internal shortest-path functions, installed by the unreleased 1.7.0--1.8.0 upgrade.

[savasp-agent]

Status correction — 2026-07-21 PT

The earlier “deferred until AGE 1.8” wording described the technical wait but was not an explicit @savasp deferral. #355 remains in v1.0 and blocks #481/#393/#417. PR #512 correctly leaves AGE 1.7 without the capability; its merge does not close or de-scope this issue.

The issue body now defines the AGE 1.8 gate and prohibits accepting the remaining ShortestPath skip for final certification without a future explicit maintainer deferral.