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

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 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.

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:

// 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.

// 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}