Ordering — Weave Docs

TimestampOrdering orders by source timestamp, then source-agent string, then source index when stable sorting is enabled. Nexus supplies the writer public-key hex string as source_agent and reads timestamps from signed Strand headers. Clock timestamps are not consensus or proof of real-time ordering. CustomOrdering accepts a comparator; callers must make its behavior consistent for their application.

This example is checked against source signatures; it was not compiled or run during this documentation pass.

use nexus::{CustomOrdering, OrderingStrategy, TimestampOrdering, UnorderedEntry};
use std::time::{Duration, SystemTime};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Hand-craft entries from two notional writers. In production these come
    // from InputStrand replay; here we build them inline to demonstrate ordering.
    let base = SystemTime::now();
    let entries = vec![
        UnorderedEntry {
            source_agent: "did:l1fe:writer-a".into(),
            source_index: 0,
            data: b"first-from-a".to_vec(),
            timestamp: base + Duration::from_millis(5),
            metadata: None,
        },
        UnorderedEntry {
            source_agent: "did:l1fe:writer-b".into(),
            source_index: 0,
            data: b"first-from-b".to_vec(),
            timestamp: base + Duration::from_millis(2),
            metadata: None,
        },
    ];

    // TimestampOrdering sorts by wall-clock time, breaking ties by source-agent string, then sequence.
    let timestamped = TimestampOrdering::with_stable_sort(true);
    let view = timestamped.order(entries.clone());

    // CustomOrdering lets callers plug in any comparator — here, lexicographic by data.
    let lexicographic = CustomOrdering::new("lex".to_string(), |a: &UnorderedEntry, b: &UnorderedEntry| {
        a.data.cmp(&b.data)
    });
    let lex_view = lexicographic.order(entries);

    println!(
        "ts_strategy={} ts_first={:?} lex_first={:?}",
        timestamped.name(),
        std::str::from_utf8(&view[0].data).ok(),
        std::str::from_utf8(&lex_view[0].data).ok(),
    );
    Ok(())
}

Source declarations