Stabilize temporal allocation records as a public API

Is there an existing proposal for this?

• I have searched the existing proposals

Is your feature request related to a problem?

This is a narrower follow-up to #637. FileReader.get_temporal_allocation_records() already exposes the allocation lifetime data used by the temporal flamegraph, and TemporalAllocationRecord and Interval are declared in _memray.pyi. However, the temporal interface is not documented in the public API documentation, and its record types are not exported from the top-level memray namespace.

As a result, users who want machine-readable temporal allocation data cannot tell whether this interface is intended to be supported or whether they must depend on private implementation details or parse the generated HTML reports.

Describe the solution you'd like

Clarify and stabilize the existing temporal allocation interface as a supported public API, without changing the capture format or introducing a new indexing engine.

A narrow first version could include:

• documenting FileReader.get_temporal_allocation_records() and the semantics of its snapshot intervals;
• exposing TemporalAllocationRecord and Interval through an approved public import path, or defining another public representation if that is preferred;
• documenting merge_threads, open-ended lifetimes, and the relationship between interval indices and memory snapshots; and
• adding tests that treat the machine-readable temporal records as a supported interface and validate them against the data consumed by the existing temporal flamegraph.

Would you prefer to stabilize the existing record classes directly, or introduce a separate documented wrapper or result type? I would be happy to implement the narrower approach you prefer, including type declarations, API documentation, and regression tests.

This proposal intentionally does not include persistent indexes, a new capture format, module or function grouping, or a higher-level query engine. Those could be considered separately after the underlying temporal data interface is supported.

Alternatives you considered

Users can currently call the existing method and rely on types from memray._memray, but that depends on an underscored implementation module and undocumented semantics. Parsing temporal flamegraph HTML is another workaround, but it couples downstream analysis to a presentation format. Implementing the broader analysis API proposed in #637 all at once would address more use cases, but would require substantially more API and architectural design than this narrower first step.