feat: add lance_dataset_versions for listing dataset version history (#17)

## Summary

- Adds `lance_dataset_versions` — returns an opaque `LanceVersions`
snapshot
- Accessors: `lance_versions_count`, `lance_versions_id_at`,
`lance_versions_timestamp_ms_at`, `lance_versions_close`
- C++: new `lance::VersionInfo` struct and a
`lance::Dataset::versions()` member returning `std::vector<VersionInfo>`

## Motivation

C/C++ callers can read the current version and the latest version today,
but there's no way to list the full history. This covers the read side
of version management and is a prerequisite for restore (#12).

## Notes

- Handle pattern matches `LanceScanner` / `LanceBatch` (opaque handle +
index-based accessors).
- Each entry carries the monotonic version id and a Unix epoch
millisecond timestamp.
- Per-version metadata and tags are out of scope here — they're separate
features.

## Test plan

- `cargo test` — 7 new tests: single-version, multi-version ordering,
NULL on each entrypoint, out-of-range index (boundary + far), close-null
safety
- `cargo clippy --all-targets -- -D warnings` and `cargo fmt --check`
clean
- `cargo test --test compile_and_run_test -- --ignored` — C and C++
smoke tests iterate the snapshot

Closes #11.

Author: LuciferYang

include/lance.h

@@ -91,9 +91,10 @@ void lance_free_string(const char* s);
 
 /* ─── Opaque handles ─── */
 
-typedef struct LanceDataset LanceDataset;
+typedef struct LanceDataset  LanceDataset;
 typedef struct LanceScanner  LanceScanner;
 typedef struct LanceBatch    LanceBatch;
+typedef struct LanceVersions LanceVersions;
 
 /* ─── Dataset lifecycle ─── */
 
@@ -125,6 +126,35 @@ uint64_t lance_dataset_count_rows(const LanceDataset* dataset);
 /** Return the latest version ID (I/O). Returns 0 on error. */
 uint64_t lance_dataset_latest_version(const LanceDataset* dataset);
 
+/* ─── Version history ─── */
+
+/**
+ * Snapshot the dataset's version history. Caller frees the returned handle
+ * with lance_versions_close().
+ * @return handle on success, or NULL on error
+ */
+LanceVersions* lance_dataset_versions(const LanceDataset* dataset);
+
+/** Number of versions in the snapshot. Returns 0 on error. */
+uint64_t lance_versions_count(const LanceVersions* versions);
+
+/**
+ * Monotonic version id at `index` (0 <= index < count).
+ * Returns 0 on error (NULL handle or out-of-range index) — check
+ * lance_last_error_code().
+ */
+uint64_t lance_versions_id_at(const LanceVersions* versions, size_t index);
+
+/**
+ * Version timestamp at `index`, as Unix epoch milliseconds.
+ * Returns 0 on error (NULL handle or out-of-range index) — check
+ * lance_last_error_code().
+ */
+int64_t lance_versions_timestamp_ms_at(const LanceVersions* versions, size_t index);
+
+/** Close and free a versions handle. Safe to call with NULL. */
+void lance_versions_close(LanceVersions* versions);
+
 /**
  * Export the dataset schema via Arrow C Data Interface.
  * @param out  Pointer to caller-allocated ArrowSchema struct

include/lance.hpp

@@ -84,6 +84,16 @@ class Handle {
 
 class Scanner;
 
+// ─── Version history ─────────────────────────────────────────────────────────
+
+/// Metadata for a single dataset version.
+/// `id` mirrors the upstream Version::version (monotonic manifest version);
+/// `timestamp_ms` is Unix epoch milliseconds.
+struct VersionInfo {
+    uint64_t id;
+    int64_t  timestamp_ms;
+};
+
 // ─── Dataset ─────────────────────────────────────────────────────────────────
 
 class Dataset {
@@ -131,6 +141,27 @@ class Dataset {
         return v;
     }
 
+    /// Snapshot the dataset's version history, ordered by version id.
+    /// Throws lance::Error on failure.
+    std::vector<VersionInfo> versions() const {
+        auto* raw = lance_dataset_versions(handle_.get());
+        if (!raw) check_error();
+        Handle<LanceVersions, lance_versions_close> snap(raw);
+
+        uint64_t n = lance_versions_count(snap.get());
+        std::vector<VersionInfo> out;
+        out.reserve(static_cast<size_t>(n));
+        for (uint64_t i = 0; i < n; i++) {
+            VersionInfo info;
+            info.id = lance_versions_id_at(snap.get(), static_cast<size_t>(i));
+            info.timestamp_ms =
+                lance_versions_timestamp_ms_at(snap.get(), static_cast<size_t>(i));
+            if (lance_last_error_code() != LANCE_OK) check_error();
+            out.push_back(info);
+        }
+        return out;
+    }
+
     /// Export the schema as an Arrow C Data Interface struct.
     void schema(ArrowSchema* out) const {
         if (lance_dataset_schema(handle_.get(), out) != 0) {

src/lib.rs

@@ -23,6 +23,7 @@ mod fragment_writer;
 mod helpers;
 pub mod runtime;
 mod scanner;
+mod versions;
 
 // Re-export all extern "C" symbols so they appear in the cdylib.
 pub use batch::*;
@@ -32,3 +33,4 @@ pub use error::{
 };
 pub use fragment_writer::*;
 pub use scanner::*;
+pub use versions::*;

src/versions.rs

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The Lance Authors
+
+//! Versions C API: list all versions of a Lance dataset.
+//!
+//! `lance_dataset_versions` returns an opaque `LanceVersions` snapshot;
+//! accessors read entries by index, and `lance_versions_close` frees it.
+
+use lance_core::Result;
+
+use crate::dataset::LanceDataset;
+use crate::error::{LanceErrorCode, clear_last_error, ffi_try, set_last_error};
+use crate::runtime::block_on;
+
+/// Opaque snapshot of a dataset's version history.
+pub struct LanceVersions {
+    entries: Vec<VersionEntry>,
+}
+
+#[derive(Clone, Copy)]
+struct VersionEntry {
+    id: u64,
+    timestamp_ms: i64,
+}
+
+/// Return a snapshot of the dataset's version list. The caller frees the
+/// returned handle with `lance_versions_close`. Returns NULL on error.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn lance_dataset_versions(
+    dataset: *const LanceDataset,
+) -> *mut LanceVersions {
+    ffi_try!(unsafe { versions_inner(dataset) }, null)
+}
+
+unsafe fn versions_inner(dataset: *const LanceDataset) -> Result<*mut LanceVersions> {
+    if dataset.is_null() {
+        return Err(lance_core::Error::InvalidInput {
+            source: "dataset must not be NULL".into(),
+            location: snafu::location!(),
+        });
+    }
+    let ds = unsafe { &*dataset };
+    let versions = block_on(ds.inner.versions())?;
+    let entries = versions
+        .into_iter()
+        .map(|v| VersionEntry {
+            id: v.version,
+            timestamp_ms: v.timestamp.timestamp_millis(),
+        })
+        .collect();
+    Ok(Box::into_raw(Box::new(LanceVersions { entries })))
+}
+
+/// Return the number of versions. Returns 0 on error (NULL handle).
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn lance_versions_count(versions: *const LanceVersions) -> u64 {
+    if versions.is_null() {
+        set_last_error(LanceErrorCode::InvalidArgument, "versions is NULL");
+        return 0;
+    }
+    let v = unsafe { &*versions };
+    clear_last_error();
+    v.entries.len() as u64
+}
+
+/// Return the monotonic version id at `index` (0 <= index < count).
+/// Returns 0 and sets the thread-local error on NULL or out-of-range input.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn lance_versions_id_at(versions: *const LanceVersions, index: usize) -> u64 {
+    unsafe { entry_at(versions, index) }
+        .map(|e| e.id)
+        .unwrap_or(0)
+}
+
+/// Return the Unix epoch millisecond timestamp at `index`.
+/// Returns 0 and sets the thread-local error on NULL or out-of-range input.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn lance_versions_timestamp_ms_at(
+    versions: *const LanceVersions,
+    index: usize,
+) -> i64 {
+    unsafe { entry_at(versions, index) }
+        .map(|e| e.timestamp_ms)
+        .unwrap_or(0)
+}
+
+/// Close and free a versions handle. Safe to call with NULL.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn lance_versions_close(versions: *mut LanceVersions) {
+    if !versions.is_null() {
+        unsafe {
+            let _ = Box::from_raw(versions);
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/// Copy the entry at `index` out of the versions handle. Sets the thread-local
+/// error and returns `None` on NULL handle or out-of-range index.
+unsafe fn entry_at(versions: *const LanceVersions, index: usize) -> Option<VersionEntry> {
+    if versions.is_null() {
+        set_last_error(LanceErrorCode::InvalidArgument, "versions is NULL");
+        return None;
+    }
+    let v = unsafe { &*versions };
+    match v.entries.get(index).copied() {
+        Some(e) => {
+            clear_last_error();
+            Some(e)
+        }
+        None => {
+            set_last_error(
+                LanceErrorCode::InvalidArgument,
+                format!(
+                    "version index {} out of range; count = {}",
+                    index,
+                    v.entries.len()
+                ),
+            );
+            None
+        }
+    }
+}

tests/c_api_test.rs

@@ -1655,3 +1655,131 @@ fn test_robotics_e2e_write_then_finalize() {
 
     unsafe { lance_dataset_close(ds) };
 }
+
+// ---------------------------------------------------------------------------
+// Version history (lance_dataset_versions)
+// ---------------------------------------------------------------------------
+
+/// Helper: open an existing dataset and append a batch, creating a new version.
+fn append_batch(uri: &str, schema: Arc<Schema>, batch: RecordBatch) {
+    lance_c::runtime::block_on(async {
+        let mut ds = Dataset::open(uri).await.unwrap();
+        ds.append(
+            arrow::record_batch::RecordBatchIterator::new(vec![Ok(batch)], schema),
+            None,
+        )
+        .await
+        .unwrap();
+    });
+}
+
+#[test]
+fn test_dataset_versions_single_version() {
+    let (_tmp, uri) = create_test_dataset();
+    let c_uri = c_str(&uri);
+    let ds = unsafe { lance_dataset_open(c_uri.as_ptr(), ptr::null(), 0) };
+
+    let vs = unsafe { lance_dataset_versions(ds) };
+    assert!(!vs.is_null());
+    assert_eq!(unsafe { lance_versions_count(vs) }, 1);
+    assert_eq!(unsafe { lance_versions_id_at(vs, 0) }, 1);
+    assert!(unsafe { lance_versions_timestamp_ms_at(vs, 0) } > 0);
+
+    unsafe { lance_versions_close(vs) };
+    unsafe { lance_dataset_close(ds) };
+}
+
+#[test]
+fn test_dataset_versions_multiple_versions() {
+    let (_tmp, uri) = create_test_dataset();
+    let schema = Arc::new(Schema::new(vec![
+        Field::new("id", DataType::Int32, false),
+        Field::new("name", DataType::Utf8, true),
+    ]));
+    let batch = RecordBatch::try_new(
+        schema.clone(),
+        vec![
+            Arc::new(Int32Array::from(vec![6, 7])),
+            Arc::new(StringArray::from(vec!["frank", "grace"])),
+        ],
+    )
+    .unwrap();
+    append_batch(&uri, schema, batch);
+
+    let c_uri = c_str(&uri);
+    let ds = unsafe { lance_dataset_open(c_uri.as_ptr(), ptr::null(), 0) };
+    let vs = unsafe { lance_dataset_versions(ds) };
+
+    let count = unsafe { lance_versions_count(vs) };
+    assert_eq!(count, 2);
+
+    let id0 = unsafe { lance_versions_id_at(vs, 0) };
+    let id1 = unsafe { lance_versions_id_at(vs, 1) };
+    assert_eq!(id0, 1);
+    assert_eq!(id1, 2);
+
+    let ts0 = unsafe { lance_versions_timestamp_ms_at(vs, 0) };
+    let ts1 = unsafe { lance_versions_timestamp_ms_at(vs, 1) };
+    assert!(ts0 > 0, "timestamps should be populated");
+    assert!(
+        ts1 >= ts0,
+        "timestamps should be monotonic by version order"
+    );
+
+    unsafe { lance_versions_close(vs) };
+    unsafe { lance_dataset_close(ds) };
+}
+
+#[test]
+fn test_dataset_versions_null_dataset() {
+    let vs = unsafe { lance_dataset_versions(ptr::null()) };
+    assert!(vs.is_null());
+    assert_eq!(lance_last_error_code(), LanceErrorCode::InvalidArgument);
+}
+
+#[test]
+fn test_versions_count_null_handle() {
+    let n = unsafe { lance_versions_count(ptr::null()) };
+    assert_eq!(n, 0);
+    assert_eq!(lance_last_error_code(), LanceErrorCode::InvalidArgument);
+}
+
+#[test]
+fn test_versions_index_out_of_range() {
+    let (_tmp, uri) = create_test_dataset();
+    let c_uri = c_str(&uri);
+    let ds = unsafe { lance_dataset_open(c_uri.as_ptr(), ptr::null(), 0) };
+    let vs = unsafe { lance_dataset_versions(ds) };
+
+    // Count is 1 for a freshly-created dataset. Exercise both the exact
+    // boundary (index == count) and a clearly-out-of-range index.
+    let count = unsafe { lance_versions_count(vs) };
+    for index in [count as usize, 5] {
+        let id = unsafe { lance_versions_id_at(vs, index) };
+        assert_eq!(id, 0);
+        assert_eq!(lance_last_error_code(), LanceErrorCode::InvalidArgument);
+
+        let ts = unsafe { lance_versions_timestamp_ms_at(vs, index) };
+        assert_eq!(ts, 0);
+        assert_eq!(lance_last_error_code(), LanceErrorCode::InvalidArgument);
+    }
+
+    unsafe { lance_versions_close(vs) };
+    unsafe { lance_dataset_close(ds) };
+}
+
+#[test]
+fn test_versions_accessors_null_handle() {
+    let id = unsafe { lance_versions_id_at(ptr::null(), 0) };
+    assert_eq!(id, 0);
+    assert_eq!(lance_last_error_code(), LanceErrorCode::InvalidArgument);
+
+    let ts = unsafe { lance_versions_timestamp_ms_at(ptr::null(), 0) };
+    assert_eq!(ts, 0);
+    assert_eq!(lance_last_error_code(), LanceErrorCode::InvalidArgument);
+}
+
+#[test]
+fn test_versions_close_null_is_safe() {
+    unsafe { lance_versions_close(ptr::null_mut()) };
+}