Problem
GraphForge.addNodes() and addEdges() are advertised in generated Node declarations and classified as equivalent, release-tested methods, but both delegate to Rust facade methods that always return GF_NOT_IMPLEMENTED.
The Rust conformance test currently treats those errors as success, while the corresponding Node BDD scenarios are skipped. Python methods with the same names are functional normalization conveniences over atomic Rust bulk publication, so the current parity classification is false.
Objective
Remove the nonfunctional Node/Rust convenience stubs and make canonical atomic bulk publication the documented Node contract.
Debt / Regime
- Debt type: architecture, development, test/proof, and documentation
- Quality regime: A — deterministic compute
Requirements
- Remove zero-argument GraphForge::add_nodes() and GraphForge::add_edges() stubs from the Rust facade and frozen public inventory.
- Remove Node addNodes() and addEdges() methods from the native binding and generated declarations.
- Preserve functional publishBulkNodes() and publishBulkEdges() as the Node bulk-construction APIs, including operation UUIDs, Arrow IPC receipts, atomic publication, idempotency, structured errors, and reopen behavior.
- Keep Python add_nodes() and add_edges() as language-specific container-normalization conveniences over the same Rust publication path; do not classify them as direct equivalents of removed Rust methods.
- Remove tests that accept GF_NOT_IMPLEMENTED.
- Replace skipped Node construction scenarios with functional canonical-publication coverage or explicitly language-specific scenarios.
- Update parity policies so method-name coincidence cannot establish behavioral equivalence.
- Document the intentional compile-time removal and migration path.
Acceptance Criteria
BDD Completion Scenarios
Scenario: Node publishes nodes atomically
Given canonical node Arrow IPC and a stable operation UUID
When Node calls publishBulkNodes()
Then Rust returns the canonical publication receipt
And the nodes are queryable after reopen.
Scenario: Node publishes edges atomically
Given committed endpoint UUIDs and canonical edge Arrow IPC
When Node calls publishBulkEdges()
Then the edge generation is published atomically
And relationship inspection and query readback observe it after reopen.
Scenario: Removed stubs cannot be called
Given freshly generated Node declarations and a clean-installed package
When a caller inspects the public surface
Then addNodes() and addEdges() are absent
And the canonical publication alternatives remain present and functional.
Scenario: Parity requires behavior
Given Rust, Python, and Node public-surface inventories
When parity validation runs
Then methods are equivalent only when their operation, inputs, outputs, errors, and persistence behavior correspond
And stable NotImplementedError behavior cannot satisfy release-tested evidence.
Implementation Notes
Likely surfaces:
- crates/graphforge-api/src/lib.rs
- crates/graphforge-api/tests/public_facade_remaining_conformance.rs
- crates/graphforge-bindings-node/src/lib.rs
- crates/graphforge-bindings-node/index.d.ts
- Node native bulk-construction tests
- Python and Node parity policies
- tests/contracts/non-cypher-rust-surface.json
- shared construction BDD features and steps
- public API and graph-construction documentation
Observability
No new telemetry is required. Preserve structured errors without logging input batches, labels, relationship types, properties, or queries.
Security and Privacy
Continue validating Arrow schemas, operation UUIDs, endpoints, sizes, and conflicts in Rust. Do not reconstruct or publish graph data in JavaScript.
Testing
- Rust surface-absence and inventory tests.
- Node declaration/runtime surface tests.
- Node publication, exact-retry, conflict, Arrow receipt, and reopen tests.
- Python convenience-method regression tests.
- Cross-language parity-policy mutation tests.
- Targeted tests followed by formatting, clippy, workspace tests, and make pre-push.
Documentation
Document publishBulkNodes() and publishBulkEdges() as the Node alternatives and explain Python's language-specific normalization helpers.
Non-Goals
- Adding a second Node bulk-publication implementation.
- Removing functional Python convenience methods.
- Reintroducing generic transactions.
- Changing canonical Arrow schemas or atomic-publication semantics.
Related Issues
Open Questions
Problem
GraphForge.addNodes() and addEdges() are advertised in generated Node declarations and classified as equivalent, release-tested methods, but both delegate to Rust facade methods that always return GF_NOT_IMPLEMENTED.
The Rust conformance test currently treats those errors as success, while the corresponding Node BDD scenarios are skipped. Python methods with the same names are functional normalization conveniences over atomic Rust bulk publication, so the current parity classification is false.
Objective
Remove the nonfunctional Node/Rust convenience stubs and make canonical atomic bulk publication the documented Node contract.
Debt / Regime
Requirements
Acceptance Criteria
BDD Completion Scenarios
Scenario: Node publishes nodes atomically
Given canonical node Arrow IPC and a stable operation UUID
When Node calls publishBulkNodes()
Then Rust returns the canonical publication receipt
And the nodes are queryable after reopen.
Scenario: Node publishes edges atomically
Given committed endpoint UUIDs and canonical edge Arrow IPC
When Node calls publishBulkEdges()
Then the edge generation is published atomically
And relationship inspection and query readback observe it after reopen.
Scenario: Removed stubs cannot be called
Given freshly generated Node declarations and a clean-installed package
When a caller inspects the public surface
Then addNodes() and addEdges() are absent
And the canonical publication alternatives remain present and functional.
Scenario: Parity requires behavior
Given Rust, Python, and Node public-surface inventories
When parity validation runs
Then methods are equivalent only when their operation, inputs, outputs, errors, and persistence behavior correspond
And stable NotImplementedError behavior cannot satisfy release-tested evidence.
Implementation Notes
Likely surfaces:
Observability
No new telemetry is required. Preserve structured errors without logging input batches, labels, relationship types, properties, or queries.
Security and Privacy
Continue validating Arrow schemas, operation UUIDs, endpoints, sizes, and conflicts in Rust. Do not reconstruct or publish graph data in JavaScript.
Testing
Documentation
Document publishBulkNodes() and publishBulkEdges() as the Node alternatives and explain Python's language-specific normalization helpers.
Non-Goals
Related Issues
Open Questions