feat(bindings): expose ontology lifecycle parity in Python and Node

[DecisionNerd]

Problem

The Rust GraphForge facade has durable ontology operations including workspace_ontology(), adopt_ontology(), and clear_ontology(), while Python and Node expose only session-scoped load_ontology() and ontology-mode inspection.

The user guide compounds the mismatch by presenting Python examples for runtime_catalog(), suggest_ontology(), export_ontology(), and set_ontology_mode() even though those binding APIs do not exist. A standalone mode setter would also allow mode and durable ontology authority to drift; mode transitions should remain coupled to load/adopt/clear semantics.

Objective

Expose thin, behaviorally equivalent Python and Node ontology lifecycle bindings over the Rust-owned contract, and make the public documentation executable and authority-safe.

Dependency

• Blocked by feat(api): add deterministic ontology suggestion, validation, and export #236, which owns the Rust ontology inspection/suggestion/validation/export contract.
• Existing durable adoption, inspection, and clear operations may be wrapped in preparation, but the final parity gate must target the frozen Rust surface from that issue.

Debt / regime

• Debt types: development, documentation, test/proof
• Quality regime: A (deterministic compute)

Requirements

• Expose the Rust-owned runtime-catalog inspection, ontology suggestion, non-mutating validation, and explicit-source export operations in Python and Node.
• Expose existing durable workspace_ontology, adopt_ontology, and clear_ontology operations in both bindings.
• Preserve the existing session-scoped load_ontology() behavior and clearly distinguish it from durable adoption.
• Map request/result types and structured errors consistently across Python and Node.
• Return Arrow or ordinary typed binding values according to the frozen Rust contract; do not reimplement suggestion, validation, serialization, or authority decisions in Python or TypeScript.
• Do not add a free-standing set_ontology_mode() API. Mode changes must occur through load, adopt, or clear operations with their documented authority semantics.
• Update [Unreleased] for the binding behavior.

Acceptance Criteria

• Python and Node expose the same in-scope ontology lifecycle capabilities and defaults as Rust.
• No Python or JavaScript fallback engine or duplicate ontology inference logic exists.
• Session load remains non-durable across reopen; adoption and clearing remain generation-managed and durable across reopen.
• Binding exports are deterministic and byte-equivalent to Rust for the same source, format, and options.
• Python and Node receive equivalent structured errors for invalid content, invalid mode/source/format, idempotency conflicts, and storage failures.
• Public examples execute against freshly built same-SHA Python and Node packages.

BDD Completion Scenarios

Scenario: Python and Node inspect and suggest through Rust
Given equivalent exploratory projects opened from Python and Node
When each caller inspects the catalog and requests an ontology suggestion
Then both receive the same ordered contract and canonical draft
And neither binding contains independent inference behavior

Scenario: Session loading remains distinct from durable adoption
Given a persistent exploratory project
When a binding caller uses load_ontology() and reopens the project
Then the reopened project remains exploratory
When the caller instead adopts the ontology with an operation UUID and reopens
Then the adopted ontology and enforcement mode persist

Scenario: Durable clear is atomic and idempotent
Given a project with an adopted ontology
When Python or Node clears it using the same idempotent operation twice
Then the project has one deterministic exploratory outcome
And reopen observes explicit ontology absence

Scenario: Documented examples are executable
Given freshly built Python and Node packages from the same commit
When the ontology lifecycle examples run
Then every documented method exists and produces the documented authority behavior
And no example relies on a standalone mode setter

Implementation Notes

• Likely surfaces: crates/gf-bindings-py, crates/gf-bindings-node, binding type declarations, smoke/release tests, BDD steps, and non-Cypher parity manifests.
• Request objects should preserve operation UUID and optional actor identity for durable writes.
• Keep ontology document serialization and validation in Rust.
• Update generated or checked-in type declarations through the repository's normal generation path.

Observability

• No new external telemetry is required.
• Preserve structured GraphForge error codes/details through both binding error hierarchies; do not log ontology contents by default.

Security And Privacy

• Validate all path, mode, format, and operation-identity inputs in Rust.
• Ensure exceptions do not expose unrelated filesystem contents.
• Suggestions and exported documents must not contain graph property values or sampled user data beyond the Rust contract.

Testing

• Python and Node unit/smoke coverage for every added method and error mapping.
• Cross-binding parity fixtures comparing Rust, Python, and Node results and exported bytes.
• Persistent reopen tests for load versus adopt versus clear.
• Fresh native package acceptance from the same SHA; no NetworkX, igraph, or binding-side ontology implementation.
• Update non-Cypher surface/parity inventories and run binding format, type, build, and targeted test gates.

Documentation

• Rewrite the exploratory analyst examples to use the actual binding APIs.
• Explain session load versus durable adoption, explicit clear, draft suggestion, ontology export, and whole-project portable interchange.
• Remove or replace the nonexistent set_ontology_mode() examples.
• Add an [Unreleased] changelog entry.

Non-Goals

• Reimplementing ontology behavior outside Rust.
• Swift or Kotlin parity.
• Graph-data migration between ontology versions.
• CLI or agent-skill lifecycle commands tracked by feat(dx): add repository-local GraphForge lifecycle CLIs and project skills #219.
• Automatic ontology adoption.

Related Issues

• feat(dx): add repository-local GraphForge lifecycle CLIs and project skills #219 tracks repository lifecycle CLIs and skills.
• feat(api): add deterministic ontology suggestion, validation, and export #236 provides the Rust-owned ontology lifecycle contract this issue exposes.
• feat: add portable project interchange #234 added whole-project portable interchange.

Open Questions

• None after the blocking Rust contract freezes its request and result schemas.

[coderabbitai]

🔗 Related PRs

#206 - ci: move job transfers to Blacksmith storage [merged]
#208 - ci: minimize Blacksmith cache storage [merged]
#217 - feat(api): add embedded write modes [merged]
#220 - feat(bindings): expose embedded write modes [merged]
#234 - feat: add portable project interchange [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!