# What Information Does the Run Struct in orx Store? A Complete Field Guide

> Discover what the Run struct in orx stores. Learn how id, experiment_id, status, commit_sha, duration_secs, updated_display, and result_markdown create readable CLI output for experiment tracking.

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

---

**The `Run` struct in `orx` stores seven key fields—`id`, `experiment_id`, `status`, `commit_sha`, `duration_secs`, `updated_display`, and `result_markdown`—that transform raw SQLite database records into human-readable CLI output for experiment tracking.**

The `orx` CLI tool (part of the [alphaXiv/OpenResearch](https://github.com/alphaXiv/OpenResearch) repository) uses a layered data model where persistent storage is decoupled from user-facing displays. Understanding what information the `Run` struct stores helps developers interact with experiment metadata programmatically and build custom tooling around the local SQLite backend.

## Core Fields Stored in the Run Struct

Located in **src/plane.rs**, the `Run` struct acts as a presentation-layer wrapper around the database-backed `StoredRun`. It enriches raw timestamp data with human-readable formatting while preserving all identifying metadata:

- **`id`** (`String`): The unique run identifier serving as the primary key in the `runs` table.
- **`experiment_id`** (`String`): Foreign key linking the run to its parent experiment.
- **`status`** (`String`): Human-readable execution state such as `"starting"`, `"running"`, `"done"`, or `"failed"`.
- **`commit_sha`** (`Option<String>`): The Git commit SHA active at launch time, present only when version control metadata is available.
- **`duration_secs`** (`i64`): Computed elapsed time in seconds, derived from stored start and end timestamps.
- **`updated_display`** (`String`): Friendly "time-ago" string (e.g., "5 minutes ago") generated from the `updated_at` timestamp.
- **`result_markdown`** (`Option<String>`): Optional markdown content containing either successful results or error output from the run.

According to the source code in **src/plane.rs** lines 6-14, these fields are populated via the `From<&StoredRun>` implementation, which bridges the database schema with CLI display logic.

## Converting from StoredRun to Run

The transformation from persistent storage to the `Run` struct happens through a dedicated conversion trait. In **src/plane.rs**, the `impl From<&StoredRun> for Run` block handles data mapping while invoking helper functions from the `local` module to calculate derived values.

```rust
use orx::store::StoredRun;
use orx::plane::Run;

// Fetch from SQLite store and convert to display format
let stored: StoredRun = store.get_run("run_abc123")?.expect("run not found");
let run: Run = Run::from(&stored);

```

The conversion process performs two critical enrichments:

1. **Duration calculation**: Computes `duration_secs` by subtracting the run's start timestamp from its end timestamp.
2. **Time formatting**: Generates `updated_display` by converting the raw `updated_at` timestamp into a relative time string.

## Accessing Run Metadata Programmatically

Once converted, the `Run` struct exposes all fields directly for inspection and logging workflows:

```rust
// Basic metadata inspection
println!("Run {} (experiment {}): {}", run.id, run.experiment_id, run.status);

// Optional Git context
if let Some(sha) = &run.commit_sha {
    println!("Built from commit: {}", sha);
}

// Timing information
println!("Duration: {} seconds", run.duration_secs);
println!("Last activity: {}", run.updated_display);

// Result inspection
if let Some(output) = &run.result_markdown {
    println!("Output:\n{}", output);
}

```

The underlying `StoredRun` definition in **src/store.rs** lines 98-124 provides the raw database schema, while `Run` in **src/plane.rs** adds the presentation layer necessary for CLI tables and terminal output.

## Handling Failed Runs with failure_detail()

Beyond field storage, the `Run` struct provides specialized error handling through the `failure_detail()` method (implemented in **src/plane.rs** lines 30-42). This helper returns `Option<String>` containing either:

- The contents of `result_markdown` if error output was captured, or
- A pointer instructing users to run `orx logs <run-id>` to view the local log file.

```rust
// Check for failures with automatic messaging
if let Some(error_msg) = run.failure_detail() {
    eprintln!("Run failed: {}", error_msg);
}

```

This method simplifies CLI error reporting by unifying the two possible failure information sources (stored markdown vs. log files) into a single API call.

## Summary

- The `Run` struct stores seven fields in **src/plane.rs**: identifiers, status, Git context, computed duration, human-readable timestamps, and optional results.
- Data originates from the `StoredRun` struct in **src/store.rs** and is enriched during conversion with calculated duration and relative time displays.
- The `failure_detail()` method provides standardized error reporting for failed experiment runs.
- All fields use standard Rust types (`String`, `Option<String>`, `i64`) optimized for CLI serialization and display formatting.

## Frequently Asked Questions

### How is the duration calculated in the Run struct?

The `duration_secs` field is computed during the `From<&StoredRun>` conversion in **src/plane.rs** by subtracting the run's start timestamp from its end timestamp, yielding a signed 64-bit integer representing elapsed seconds.

### What is the difference between Run and StoredRun?

`StoredRun` (defined in **src/store.rs**) represents the raw database schema with column-for-column SQLite mapping, while `Run` (in **src/plane.rs**) is the CLI-specific representation that adds derived display fields like `updated_display` and `duration_secs`.

### Can the Run struct be constructed without a database record?

While the `Run` struct is primarily instantiated via `Run::from(&stored_run)`, the fields are all public (or accessible through standard Rust patterns), allowing manual construction for testing or mocking purposes, though the codebase expects database-backed creation for production use.

### Where does the failure_detail() method look for error information?

The `failure_detail()` method first checks the `result_markdown` field for stored error content; if that is `None`, it returns a default message directing users to execute `orx logs <run-id>` to inspect the local log files on disk.