# How the Plane Abstraction in OpenResearch Shares Data Structures Across the CLI

> Learn how the Plane abstraction in alphaXiv/OpenResearch shares data structures like Run, RunLog, and ProjectEdit across its CLI. Discover its single source of truth.

- Repository: [alphaXiv/OpenResearch](https://github.com/alphaXiv/OpenResearch)
- Tags: internals
- Published: 2026-09-13

---

**The Plane abstraction centralizes data structures like `Run`, `RunLog`, and `ProjectEdit` in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs), then exposes them through a `LocalPlane` implementation that transforms stored database rows into these shared structs, creating a single source of truth for all CLI commands.**

The OpenResearch CLI (alphaXiv/OpenResearch) manages machine learning research projects through a unified interface for experiments, runs, and logs. At the heart of this architecture lies the **Plane** abstraction, which consolidates data definitions in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) and implements concrete operations in `LocalPlane`. This design ensures that commands like `orx project view` and `orx logs` operate on consistent, type-safe data structures without duplicating logic.

## Centralizing Data Structures in src/plane.rs

The file [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) serves as the canonical source for data shapes used throughout the CLI. Rather than scattering definitions across command modules, the Plane abstraction declares shared structs that represent printable run fields, log metadata, and edit payloads.

Key structures defined here include ([plane.rs#L6-L22](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs#L6), [plane.rs#L45-L99](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs#L45), [plane.rs#L101-L146](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs#L101)):

- `Run` – Printable run fields and status
- `RunLog` – Log content with byte-range metadata
- `RunListing` – Paginated run collections
- `LogRequest` – Parameters for reading log segments
- `DescInput` – Description payloads for experiments
- `ProjectEdit` – Updates to project configuration
- `CreateExperimentSpec` – Specifications for new experiments

By housing these types in a single file, [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) establishes a shared contract. Any change to the data model—such as adding a field to `Run`—automatically propagates to every command that consumes the Plane abstraction.

## Resolving Operations with LocalPlane

While [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) defines *what* data looks like, [`src/plane/local_plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane/local_plane.rs) defines *how* to fetch and manipulate it. The `LocalPlane` struct bundles a `Store` handle (database connection) with resolved project or experiment rows, acting as the concrete implementation of the Plane abstraction.

Resolver functions in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) construct these instances:

- `resolve_project` ([plane.rs#L123-L131](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs#L123)) creates a `LocalPlane` bound to a specific project
- `resolve_experiment` ([plane.rs#L133-L141](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs#L133)) binds to an experiment context
- `resolve_run` ([plane.rs#L143-L151](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs#L143)) prepares a plane for run-specific operations

The `LocalPlane` type itself lives in [`src/plane/local_plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane/local_plane.rs) ([local_plane.rs#L16-L25](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane/local_plane.rs#L16)) and encapsulates the logic for transforming raw database rows into the public structs defined in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs).

## Transforming Stored Data into Shared Structs

Methods on `LocalPlane` query the underlying `Store` and map internal types (like `StoredRun`) into the shared abstractions defined in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs). This ensures CLI commands receive fully-formed, validated data structures rather than raw database records.

**Listing runs:** The `list_runs` method queries the store and converts each `StoredRun` into the public `Run` struct using `Run::from` ([local_plane.rs#L41-L53](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane/local_plane.rs#L41)):

```rust
let plane = resolve_project(store, "proj123")?;
let listing = plane.list_runs().await?;
for run in listing.runs {
    println!("{} – {}", run.id, run.status);
}

```

**Reading logs:** The `read_log` method builds a `RunLog` containing raw bytes plus pagination metadata ([local_plane.rs#L55-L100](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane/local_plane.rs#L55)):

```rust
let plane = resolve_run(store, "run456")?;
let log = plane
    .read_log(LogRequest { 
        mode: "head".into(), 
        max_bytes: Some(1024), 
        ..Default::default() 
    })
    .await?;
println!("Log ({} bytes): {}", log.content.len(), log.footer());

```

**Editing projects:** High-level operations like `edit_project` accept the shared `ProjectEdit` struct defined in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs), ensuring type consistency across the boundary:

```rust
let plane = resolve_project(store, "proj123")?;
plane.edit_project(ProjectEdit { 
    name: Some("New Name".into()), 
    run_command: None 
}).await?;

```

## Hiding Implementation Details with Re-Exports

To maintain clean separation between interface and implementation, [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) re-exports `LocalPlane` at the bottom of the file ([plane.rs#L155-L156](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs#L155)):

```rust
pub(crate) use local_plane::LocalPlane;

```

This pattern allows CLI command modules to import from `crate::plane` without knowing whether they are interacting with a local or remote implementation. The abstraction cleanly separates the shared data structures from their retrieval logic, enabling future extensions (such as a remote API plane) without changing consumer code.

## Maintaining a Single Source of Truth

Because all high-level CLI commands flow through `resolve_*` → `LocalPlane` → shared structs, the Plane abstraction guarantees consistency. When a developer modifies `Run` in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs), the change immediately affects `list_runs` in [`local_plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/local_plane.rs) and every command that displays run information.

This architecture eliminates data drift between commands. Whether executing `orx exp launch`, `orx project view`, or `orx logs`, the CLI operates on the same validated structures defined in the central Plane module.

## Summary

- **Central definitions:** All shared data structures (`Run`, `RunLog`, `ProjectEdit`, etc.) live in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs), creating a type contract for the entire CLI.
- **Concrete implementation:** `LocalPlane` in [`src/plane/local_plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane/local_plane.rs) implements the logic for fetching and transforming database rows into these shared structs.
- **Resolver pattern:** Functions like `resolve_project` and `resolve_run` construct `LocalPlane` instances bound to specific contexts, ensuring proper `Store` initialization.
- **Method mapping:** Operations like `list_runs` and `read_log` convert internal storage types into public Plane structs, maintaining abstraction boundaries.
- **Clean imports:** Re-exporting `LocalPlane` from [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) hides implementation details while exposing a unified interface to command modules.

## Frequently Asked Questions

### What is the Plane abstraction in OpenResearch?

The Plane abstraction is an architectural layer in the OpenResearch CLI (alphaXiv/OpenResearch) that unifies how commands interact with projects, experiments, runs, and logs. It consists of shared data structures defined in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) and a concrete `LocalPlane` implementation that handles data retrieval and transformation, allowing CLI commands to work with consistent, type-safe structs regardless of the underlying storage mechanism.

### Which data structures are shared in src/plane.rs?

The file defines critical CLI-facing structs including `Run` (run metadata and status), `RunLog` (log content with pagination info), `RunListing` (collections of runs), `LogRequest` (parameters for log queries), `DescInput` (experiment descriptions), `ProjectEdit` (project configuration updates), and `CreateExperimentSpec` (experiment creation parameters). These types form the common language used across all CLI operations.

### How does LocalPlane differ from the structs in plane.rs?

While [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) declares the **shape** of data (structs like `Run` and `RunLog`), `LocalPlane` in [`src/plane/local_plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane/local_plane.rs) provides the **behavior** for obtaining and manipulating that data. It wraps a `Store` handle and implements methods like `list_runs` and `read_log` that query the database and transform internal storage types into the public structs defined in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs).

### Why does OpenResearch use resolver functions instead of direct instantiation?

Resolver functions like `resolve_project`, `resolve_experiment`, and `resolve_run` in [`src/plane.rs`](https://github.com/alphaXiv/OpenResearch/blob/main/src/plane.rs) ensure that every `LocalPlane` instance is properly initialized with both a `Store` connection and validated context (such as a resolved project row). This pattern centralizes error handling for "not found" scenarios and guarantees that CLI commands receive a fully configured Plane abstraction ready for operations, rather than constructing dependencies manually in each command handler.