Reference

Temporal and provenance utilities

Behavior

Operation	Inputs	Output
Interval overlap	Two valid-time intervals	Boolean and intersection
Temporal join	Keyed, interval-bearing records	Pairs valid at overlapping times
Lineage traversal	Artifact ID and `parents(id)`	Ancestors with depth
Taint composition	Input artifact IDs and `taints(id)`	Stable union with source trace

Use these operations with caller-defined time boundaries, parent relationships, and source policies. Supply timezone-aware timestamps consistently.

How it works

Temporal functions treat intervals as half-open [start, end), which gives adjacent boundaries one interpretation. Provenance functions walk IDs through caller callbacks and work with caller-owned artifacts. Cycle reports expose malformed lineage. Visit limits bound traversal.

Join temporal records and explain a derived result

from mari_components.graph import temporal_join, trace_lineage_edges
from mari_components.knowledge import Assertion, valid_at

pairs = temporal_join(
    prices,
    contracts,
    left_key=lambda price: price.product_id,
    right_key=lambda contract: contract.product_id,
    left_interval=lambda price: price.validity,
    right_interval=lambda contract: contract.validity,
)

trace = trace_lineage_edges(
    "summary:q3",
    parents=provenance_store.parent_edges,
    max_depth=20,
)

current = valid_at(query_time, interval=lambda assertion: assertion.valid_time)
eligible_assertions = [assertion for assertion in assertions if current(assertion)]

Assertion binds caller-defined subject, predicate, and value fields to valid time, transaction time, artifact evidence, and explicit supersession IDs. group_assertions groups by caller semantics. plan_assertion_update implements mechanics after the caller selects supersede, retract, coexist, or dispute. It leaves disposition semantics to the caller.

Metadata-preserving lineage edges retain input role, operation, and arbitrary parameters during traversal. Plain ID lineage remains available through trace_lineage.

Lineage accepts hashable IDs, including shared RevisionRef and DependencyKey values. Reuse those identities across evidence, retrieval, and update planning. A provenance edge explains an origin. A computational dependency additionally declares which input facet affects an output. Record the complete input set in a derivation specification to drive refreshes.

grouped_interval_overlaps uses a within-group sweep. Each overlapping pair appears once. Self-pairs are excluded. An overlap is a candidate relationship. The caller assigns conflict, precedence, and violation semantics.

Find unique effective-time collisions inside caller scopes

from mari_components.graph import grouped_interval_overlaps

candidates = grouped_interval_overlaps(
    clauses,
    group=lambda clause: (clause.control, clause.jurisdiction),
    interval=lambda clause: clause.valid_time,
)

The half-open overlap condition matches the semantics used by interval-tree implementations: adjacent [a, b) and [b, c) intervals avoid overlap. IntervalTree implementation

Keep evidence and temporal accuracy as separate measurements

from mari_components.evaluation import evaluate_graph_context

metrics = evaluate_graph_context(
    selected_nodes=context.nodes,
    evidence_required=gold.evidence_nodes,
    temporally_valid=valid_node_ids,
    edges=context_edges,
)

assert metrics.evidence_coverage == 1.0
print(metrics.temporal_precision)  # measured precision

Measures

Property	Cases
Interval semantics	Adjacent, open-ended, contained, and zero-overlap intervals
Temporal join	Multiple overlaps and stable ordering
Provenance completeness	Every declared parent reachable in the trace
Cycle handling	Cycle reported once, followed by bounded traversal exit
Taint conservation	Derived output contains the union of source taints
Temporal context	Report evidence coverage and temporal precision separately

Papers and standards

Temporal databases Temporal knowledge graph survey W3C PROV Graphiti temporal model

These are value and traversal utilities. Mari leaves bitemporality and provenance storage layout to the application.