infrastructure-timeline

Generic multi-source chronological timeline: a precision-preserving TimelineEntry DTO, a TimelineSource trait, a cursor-paginated aggregator that k-way merges N sources (with an Undated bucket), and a StubTimelineSource for tests. No rendering, no domain logic — the consumer owns tables and presentation.

What it is for

infrastructure-timeline — a generic, multi-source chronological timeline aggregator.

The surface is deliberately small and dependency-light (mirrors infrastructure-embeddings): a precision-preserving TimelineEntry DTO, a TimelineSource trait a consumer implements once per feed, a TimelineAggregator that k-way merges N sources into one cursor-paginated stream, and a StubTimelineSource so the whole flow builds and unit-tests with zero backing store.

Scope boundary (upstream half). This crate does NO rendering and holds NO domain knowledge — no party colors, no legal/deadline semantics, no tables. It aggregates the consumer's existing tables via the source trait; the consumer owns storage, presentation, and any color/party logic. It is the reusable upstream half of case-forge Sprint 09 (the legal timeline render stays in the consumer).

Two invariants that make it trustworthy for evidentiary use:

• Precision is preserved, never faked. A year-only fact reports

TimePrecision::Year and is not passed off as a real 2019-01-01T00:00:00Z; among entries at the same instant, precision_rank is the deterministic tiebreaker (coarse before fine).

• Fail-closed. If any source errors, the whole page errors — a dropped feed

never silently masquerades as "no more entries".

use std::sync::Arc;
use infrastructure_timeline::{
StubTimelineSource, TimelineAggregator, TimelineEntry, TimePrecision,
};
use uuid::Uuid;

# async fn demo() -> Result<(), infrastructure_timeline::TimelineError> {
let now = "2020-01-01T00:00:00Z".parse().ok();
let source = StubTimelineSource::new(
"communication",
vecTimelineEntry::new(
"communication", Uuid::from_u128(1), now,
TimePrecision::Second, "call", None, serde_json::Value::Null,
),
);
let agg = TimelineAggregator::new().with_source(Arc::new(source));
let page = agg.page(None, 50).await?;
assert_eq!(page.entries.len(), 1);
# Ok(()) }

Capabilities

No public items.

How to use it

From this crate's own rustdoc:

use std::sync::Arc;
use infrastructure_timeline::{
    StubTimelineSource, TimelineAggregator, TimelineEntry, TimePrecision,
};
use uuid::Uuid;

# async fn demo() -> Result<(), infrastructure_timeline::TimelineError> {
let now = "2020-01-01T00:00:00Z".parse().ok();
let source = StubTimelineSource::new(
    "communication",
    vec![TimelineEntry::new(
        "communication", Uuid::from_u128(1), now,
        TimePrecision::Second, "call", None, serde_json::Value::Null,
    )],
);
let agg = TimelineAggregator::new().with_source(Arc::new(source));
let page = agg.page(None, 50).await?;
assert_eq!(page.entries.len(), 1);
# Ok(()) }

Module structure

No public modules: the crate root is its whole surface.

Public surface

No public items.

Re-exports. Exported here, defined elsewhere.

Boundary

Depends on no other workspace tier.

Shares tier infrastructure with 82 other crates: infrastructure-acquire, infrastructure-adapters-google-calendar, infrastructure-adapters-google-gmail, infrastructure-adapters-google-places, infrastructure-adapters-google-trends, infrastructure-adapters-shodan, infrastructure-adapters-yelp, infrastructure-agent, … (82 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Dependencies

Runtime, from outside the workspace.

Development, from outside the workspace.

Build. None.

Depended on by. Nothing in this workspace.

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Error model

No public error type was detected: no public item declares a type named *Error, and no public signature returns one.

Operational characteristics

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.

Related capabilities

No workspace crate depends on this one.

Verification

What the tests establish, by name:

• cursor_pagination_is_stable_and_complete — src/aggregator.rs
• empty_aggregator_yields_empty_page — src/aggregator.rs
• merges_two_sources_chronologically — src/aggregator.rs
• precision_tiebreak_holds_across_the_merge — src/aggregator.rs
• dated_sorts_before_undated — src/entry.rs
• new_keeps_rank_in_sync_with_precision — src/entry.rs
• precision_rank_is_coarse_to_fine — src/entry.rs
• same_instant_orders_coarse_before_fine — src/entry.rs
• undated_entries_are_returned_after_dated — src/source.rs
• window_respects_cursor — src/source.rs
• window_sorts_and_limits — src/source.rs

Documentation coverage

Metrics

pie showData
    title Rust source composition
    "Code" : 538
    "Blank or comment" : 268

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.