Problem
Confirmed on current main at 6dc51fa47a9658d26a3f6e51e8a8261aaf9b4b86.
docs/book/architecture/overview.md:35-41 says all methods return Arrow tables and no public surface returns bespoke result types. Public Rust APIs intentionally return Vec<String>, u64, String, (), and construction handles at:
crates/graphforge-api/src/lib.rs:2593-2632crates/graphforge-api/src/lib.rs:2743-2761crates/graphforge-api/src/construction.rs:20-24crates/graphforge-api/src/construction.rs:79-85
Python and Node mirror these control, metadata, explanation, lifecycle, and construction surfaces. The central overview overclaims the Arrow contract.
Objective
State the contract precisely: tabular query/algorithm data remains Arrow in and Arrow out, while identified control, metadata, lifecycle, explanation, and construction operations may return scalars, collections, unit, or handles.
Requirements
- Replace the universal overview claim with a precise data-plane versus control/construction-plane contract.
- Inventory intentional non-Arrow return categories across Rust, Python, and Node.
- Explain construction handles versus metadata/control results.
- Preserve that bindings do not reshape tabular engine results into binding-owned objects.
- Reconcile API, binding, architecture, and contributor docs repeating the universal claim.
Acceptance Criteria
BDD Completion Scenarios
Scenario: A client author selects the correct result type
Given a client author reads architecture and binding docs
When calling a Cypher/analyst operation versus metadata/construction
Then the documented result category matches the signature
And tabular graph results remain Rust-owned Arrow data.
Scenario: Thin bindings remain explicit
Given Python and Node expose the same operation
When its return contract is documented
Then any scalar/handle is identified as a thin facade value
And no binding-side graph execution or tabular reconstruction is implied.
Implementation Notes
Start from Rust facade signatures and mechanically compare Python stubs and Node declarations. Keep the Arrow data-result claim strong; narrow only the false universal quantifier.
Observability
No production change. Documentation/signature inventory checks are sufficient.
Security And Privacy
No new security/privacy surface.
Testing
Compare Rust public signatures with Python stubs and Node declarations. Run docs checks and searches for contradictions. Do not change runtime types merely to make prose true.
Documentation
Primary surfaces: docs/book/architecture/overview.md, public API/binding docs, and contributor architecture references.
Non-Goals
- Converting lifecycle/metadata/explanation/construction APIs to Arrow.
- Binding-owned result models.
- Changing the data-bearing Arrow contract.
Related Issues
- Parent tracker will be attached through GitHub's native sub-issue relationship.
Problem
Confirmed on current
mainat6dc51fa47a9658d26a3f6e51e8a8261aaf9b4b86.docs/book/architecture/overview.md:35-41says all methods return Arrow tables and no public surface returns bespoke result types. Public Rust APIs intentionally returnVec<String>,u64,String,(), and construction handles at:crates/graphforge-api/src/lib.rs:2593-2632crates/graphforge-api/src/lib.rs:2743-2761crates/graphforge-api/src/construction.rs:20-24crates/graphforge-api/src/construction.rs:79-85Python and Node mirror these control, metadata, explanation, lifecycle, and construction surfaces. The central overview overclaims the Arrow contract.
Objective
State the contract precisely: tabular query/algorithm data remains Arrow in and Arrow out, while identified control, metadata, lifecycle, explanation, and construction operations may return scalars, collections, unit, or handles.
Requirements
Acceptance Criteria
BDD Completion Scenarios
Scenario: A client author selects the correct result type
Given a client author reads architecture and binding docs
When calling a Cypher/analyst operation versus metadata/construction
Then the documented result category matches the signature
And tabular graph results remain Rust-owned Arrow data.
Scenario: Thin bindings remain explicit
Given Python and Node expose the same operation
When its return contract is documented
Then any scalar/handle is identified as a thin facade value
And no binding-side graph execution or tabular reconstruction is implied.
Implementation Notes
Start from Rust facade signatures and mechanically compare Python stubs and Node declarations. Keep the Arrow data-result claim strong; narrow only the false universal quantifier.
Observability
No production change. Documentation/signature inventory checks are sufficient.
Security And Privacy
No new security/privacy surface.
Testing
Compare Rust public signatures with Python stubs and Node declarations. Run docs checks and searches for contradictions. Do not change runtime types merely to make prose true.
Documentation
Primary surfaces:
docs/book/architecture/overview.md, public API/binding docs, and contributor architecture references.Non-Goals
Related Issues