> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Trajectory and readers

> QitOS public API: trajectory

default\_reader selects the canonical journal and supported historical readers. Reading and replay are observation operations, not execution or recovery. Export with REDACTED\_PUBLIC explicitly declares loss; reimporting the same count of records is not a raw-data equivalence proof. `StoreTrajectoryReader.from_journal` and the existing file/default adapters expose `read_page(query, cursor=None)`. `page.records`, `page.next_cursor` and `page.watermark` describe one fixed snapshot. Warm pages hash all snapshot bytes but decode only addressed frames; a temporary disk index and bounded caches avoid retaining the full history. Old complete reads and re-import remain materializing. `export_file` stages and atomically replaces a canonical JSON file only after final verification; failure preserves existing output. The qit/qita command reference documents exact CLI usage and exit behavior.

[完整可运行教程 / Complete tutorial](/guides/observability) · [API index](/reference/api)

Signatures and fields below are extracted from the pinned source. Signatures are reference material, not standalone programs. Source links bind the same runtime baseline. Any does not imply arbitrary objects are supported; use the behavioral contract above and the linked tutorial.

Continuous `iter_records` and file export validate the full snapshot at the start and end, and each addressed frame during traversal. Iterator values are **partial until exhaustion**; early close releases resources but does not establish a completed traversal. File output is published only after final validation. Independent `read_page` calls retain full-history verification on every page.

<span id="qitos-core-conversation-exchangelog" />

## ExchangeLog

```python theme={null}
from qitos.core.conversation import ExchangeLog
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/core/conversation.py#L480)

[Usage and executable example](/guides/observability)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
log = ExchangeLog.from_dict(conversation_payload)
```

```text theme={null}
Append-only persistent exchange facts and queued safe-boundary steering.
```

```text theme={null}
ExchangeLog(log_id: Optional[str]=None, *, items: Optional[Iterable[ExchangeItem]]=None, queued_steering: Optional[Iterable[SteeringItem]]=None, schema_version: str=EXCHANGE_LOG_SCHEMA_VERSION) -> None
```

| Parameter         | Type                               | Default                       |
| ----------------- | ---------------------------------- | ----------------------------- |
| `log_id`          | `Optional[str]`                    | `None`                        |
| `items`           | `Optional[Iterable[ExchangeItem]]` | `None`                        |
| `queued_steering` | `Optional[Iterable[SteeringItem]]` | `None`                        |
| `schema_version`  | `str`                              | `EXCHANGE_LOG_SCHEMA_VERSION` |

<span id="qitos-core-conversation-exchangelog-from-dict" />

### ExchangeLog.from\_dict

```text theme={null}
from_dict(payload: Mapping[str, Any]) -> 'ExchangeLog'
```

| Parameter | Type                | Default    |
| --------- | ------------------- | ---------- |
| `payload` | `Mapping[str, Any]` | `required` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/core/conversation.py#L870)

<span id="qitos-core-conversation-exchangelog-declared-calls" />

### ExchangeLog.declared\_calls

```text theme={null}
declared_calls(batch_id: str) -> List[ToolCall]
```

| Parameter  | Type  | Default    |
| ---------- | ----- | ---------- |
| `batch_id` | `str` | `required` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/core/conversation.py#L702)

<span id="qitos-core-conversation-exchangelog-results-for-batch" />

### ExchangeLog.results\_for\_batch

```text theme={null}
results_for_batch(batch_id: str) -> List[ToolResultItem]
```

| Parameter  | Type  | Default    |
| ---------- | ----- | ---------- |
| `batch_id` | `str` | `required` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/core/conversation.py#L710)

<span id="qitos-core-conversation-exchangelog-results-for-batch-in-declaration-order" />

### ExchangeLog.results\_for\_batch\_in\_declaration\_order

```text theme={null}
results_for_batch_in_declaration_order(batch_id: str) -> List[ToolResultItem]
```

| Parameter  | Type  | Default    |
| ---------- | ----- | ---------- |
| `batch_id` | `str` | `required` |

```text theme={null}
Derive results in call declaration order without rewriting facts.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/core/conversation.py#L717)

<span id="qitos-core-conversation-exchangelog-open-batch-id" />

### ExchangeLog.open\_batch\_id

```text theme={null}
open_batch_id() -> Optional[str]
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/core/conversation.py#L732)

<span id="qitos-tracing-journal_store-journaltrajectorystore" />

## JournalTrajectoryStore

```python theme={null}
from qitos.tracing.journal_store import JournalTrajectoryStore
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/journal_store.py#L59)

[Usage and executable example](/guides/observability)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
store = JournalTrajectoryStore("trajectory.journal", read_only=True)
```

```text theme={null}
Durable local store with framed append, recovery, and a derived index.
```

```text theme={null}
JournalTrajectoryStore(path: str | Path, *, recover_partial_tail: bool=True, max_query_records: int=10000, read_only: bool=False) -> None
```

| Parameter              | Type          | Default    |
| ---------------------- | ------------- | ---------- |
| `path`                 | `str \| Path` | `required` |
| `recover_partial_tail` | `bool`        | `True`     |
| `max_query_records`    | `int`         | `10000`    |
| `read_only`            | `bool`        | `False`    |

<span id="qitos-tracing-journal_store-journaltrajectorystore-read-session" />

### JournalTrajectoryStore.read\_session

```text theme={null}
read_session(session_id: str) -> Trajectory
```

| Parameter    | Type  | Default    |
| ------------ | ----- | ---------- |
| `session_id` | `str` | `required` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/journal_store.py#L473)

<span id="qitos-qita-reader-default_reader" />

## default\_reader

```python theme={null}
from qitos.qita.reader import default_reader
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/qita/reader.py#L12)

[Usage and executable example](/guides/observability)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
reader = default_reader(root)
trajectory = reader.read_session(identity, view=PrivacyView.RAW_PRIVATE)
print(len(trajectory.records))
```

```text theme={null}
Select canonical data with bounded trace compatibility, or explicit rollback.
```

```text theme={null}
default_reader(root: str | Path, *, selector: str='trajectory') -> Any
```

| Parameter  | Type          | Default        |
| ---------- | ------------- | -------------- |
| `root`     | `str \| Path` | `required`     |
| `selector` | `str`         | `'trajectory'` |

<span id="qitos-tracing-exporter-canonicaltrajectoryexporter" />

## CanonicalTrajectoryExporter

```python theme={null}
from qitos.tracing.exporter import CanonicalTrajectoryExporter
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/exporter.py#L95)

[Usage and executable example](/guides/observability)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
exporter = CanonicalTrajectoryExporter()
receipt = exporter.export_file(reader, query, root / "public-trajectory.json")
print(receipt.record_count)
```

```text theme={null}
Canonical JSON exporter; exact for the selected projection.
```

<span id="qitos-tracing-exporter-canonicaltrajectoryexporter-export" />

### CanonicalTrajectoryExporter.export

```text theme={null}
export(trajectory: Trajectory, *, view: PrivacyView=PrivacyView.REDACTED_PUBLIC) -> ExportArtifact
```

| Parameter    | Type          | Default                       |
| ------------ | ------------- | ----------------------------- |
| `trajectory` | `Trajectory`  | `required`                    |
| `view`       | `PrivacyView` | `PrivacyView.REDACTED_PUBLIC` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/exporter.py#L111)

<span id="qitos-tracing-exporter-canonicaltrajectoryexporter-export-file" />

### CanonicalTrajectoryExporter.export\_file

```text theme={null}
export_file(reader: Any, query: Any, target: Any, *, view: PrivacyView=PrivacyView.REDACTED_PUBLIC, cancelled: Any=None) -> Any
```

| Parameter   | Type          | Default                       |
| ----------- | ------------- | ----------------------------- |
| `reader`    | `Any`         | `required`                    |
| `query`     | `Any`         | `required`                    |
| `target`    | `Any`         | `required`                    |
| `view`      | `PrivacyView` | `PrivacyView.REDACTED_PUBLIC` |
| `cancelled` | `Any`         | `None`                        |

```text theme={null}
Export a bounded snapshot through owned staging and atomic replacement.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/exporter.py#L141)

<span id="qitos-tracing-exporter-canonicaltrajectoryexporter-reimport" />

### CanonicalTrajectoryExporter.reimport

```text theme={null}
reimport(artifact: ExportArtifact) -> Trajectory
```

| Parameter  | Type             | Default    |
| ---------- | ---------------- | ---------- |
| `artifact` | `ExportArtifact` | `required` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/exporter.py#L148)

<span id="qitos-tracing-trajectory-privacyview" />

## PrivacyView

```python theme={null}
from qitos.tracing.trajectory import PrivacyView
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/trajectory.py#L91)

[Usage and executable example](/guides/observability)

Usage fragment: continues with objects from the linked complete tutorial; not a standalone program.

```python theme={null}
view = PrivacyView.REDACTED_PUBLIC
print(view.value)
```

```text theme={null}
Named projections over canonical raw data.
```

<span id="qitos-tracing-readers-storetrajectoryreader" />

## StoreTrajectoryReader

```python theme={null}
from qitos.tracing.readers import StoreTrajectoryReader
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/readers.py#L479)

[Usage and executable example](/guides/observability)

```text theme={null}
Reader adapter for any conforming trajectory store.
```

```text theme={null}
StoreTrajectoryReader(store: TrajectoryStore) -> None
```

| Parameter | Type              | Default    |
| --------- | ----------------- | ---------- |
| `store`   | `TrajectoryStore` | `required` |

<span id="qitos-tracing-readers-storetrajectoryreader-from-journal" />

### StoreTrajectoryReader.from\_journal

```text theme={null}
from_journal(path: str | Path) -> 'StoreTrajectoryReader'
```

| Parameter | Type          | Default    |
| --------- | ------------- | ---------- |
| `path`    | `str \| Path` | `required` |

```text theme={null}
Open a validated read-only journal without materializing its history.
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/readers.py#L487)

<span id="qitos-tracing-readers-storetrajectoryreader-read-page" />

### StoreTrajectoryReader.read\_page

```text theme={null}
read_page(query: TrajectoryQuery, cursor: TrajectoryCursor | None=None, *, view: PrivacyView=PrivacyView.REDACTED_PUBLIC) -> TrajectoryPage
```

| Parameter | Type                       | Default                       |
| --------- | -------------------------- | ----------------------------- |
| `query`   | `TrajectoryQuery`          | `required`                    |
| `cursor`  | `TrajectoryCursor \| None` | `None`                        |
| `view`    | `PrivacyView`              | `PrivacyView.REDACTED_PUBLIC` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/readers.py#L508)

<span id="qitos-tracing-readers-storetrajectoryreader-close" />

### StoreTrajectoryReader.close

```text theme={null}
close() -> None
```

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/readers.py#L534)

<span id="qitos-tracing-paging-trajectorycursor" />

## TrajectoryCursor

```python theme={null}
from qitos.tracing.paging import TrajectoryCursor
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/paging.py#L38)

[Usage and executable example](/guides/observability)

```text theme={null}
Reader-local opaque token. No host path or credential is serialized.
```

| Field   | Type  | Default    |
| ------- | ----- | ---------- |
| `token` | `str` | `required` |

<span id="qitos-tracing-paging-trajectorypage" />

## TrajectoryPage

```python theme={null}
from qitos.tracing.paging import TrajectoryPage
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/paging.py#L45)

[Usage and executable example](/guides/observability)

| Field         | Type                           | Default    |
| ------------- | ------------------------------ | ---------- |
| `records`     | `tuple[TrajectoryRecord, ...]` | `required` |
| `next_cursor` | `TrajectoryCursor \| None`     | `required` |
| `snapshot`    | `TrajectoryCursor`             | `required` |
| `watermark`   | `int`                          | `required` |

<span id="qitos-tracing-paging-boundedreadunsupported" />

## BoundedReadUnsupported

```python theme={null}
from qitos.tracing.paging import BoundedReadUnsupported
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/paging.py#L29)

[Usage and executable example](/guides/observability)

```text theme={null}
The selected source has no bounded snapshot capability.
```

<span id="qitos-tracing-paging-cursorrejected" />

## CursorRejected

```python theme={null}
from qitos.tracing.paging import CursorRejected
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/paging.py#L33)

[Usage and executable example](/guides/observability)

```text theme={null}
A cursor or its source no longer describes the captured snapshot.
```

<span id="qitos-tracing-paging-iter_records" />

## iter\_records

```python theme={null}
from qitos.tracing.paging import iter_records
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/paging.py#L60)

[Usage and executable example](/guides/observability)

```text theme={null}
Iterate a snapshot; output is partial until exhaustion/final validation.

Early close releases resources but does not claim a completed traversal.
Independent read_page calls always reverify the complete snapshot.
```

```text theme={null}
iter_records(reader: Any, query: TrajectoryQuery, *, view: PrivacyView=PrivacyView.REDACTED_PUBLIC) -> Iterator[TrajectoryRecord]
```

| Parameter | Type              | Default                       |
| --------- | ----------------- | ----------------------------- |
| `reader`  | `Any`             | `required`                    |
| `query`   | `TrajectoryQuery` | `required`                    |
| `view`    | `PrivacyView`     | `PrivacyView.REDACTED_PUBLIC` |

<span id="qitos-tracing-paging-read_page" />

## read\_page

```python theme={null}
from qitos.tracing.paging import read_page
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/paging.py#L52)

[Usage and executable example](/guides/observability)

```text theme={null}
Require bounded capability; never materialize a third-party fallback.
```

```text theme={null}
read_page(reader: Any, query: TrajectoryQuery, cursor: TrajectoryCursor | None=None, *, view: PrivacyView=PrivacyView.REDACTED_PUBLIC) -> TrajectoryPage
```

| Parameter | Type                       | Default                       |
| --------- | -------------------------- | ----------------------------- |
| `reader`  | `Any`                      | `required`                    |
| `query`   | `TrajectoryQuery`          | `required`                    |
| `cursor`  | `TrajectoryCursor \| None` | `None`                        |
| `view`    | `PrivacyView`              | `PrivacyView.REDACTED_PUBLIC` |

<span id="qitos-tracing-trajectory-trajectoryquery" />

## TrajectoryQuery

```python theme={null}
from qitos.tracing.trajectory import TrajectoryQuery
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/trajectory.py#L413)

[Usage and executable example](/guides/observability)

```text theme={null}
Store-independent declarative trajectory query.
```

| Field            | Type                     | Default |
| ---------------- | ------------------------ | ------- |
| `session_id`     | `Optional[str]`          | `None`  |
| `run_id`         | `Optional[str]`          | `None`  |
| `work_item_id`   | `Optional[str]`          | `None`  |
| `kinds`          | `Tuple[RecordKind, ...]` | `()`    |
| `after_sequence` | `Optional[int]`          | `None`  |
| `limit`          | `Optional[int]`          | `None`  |

<span id="qitos-tracing-trajectory-lossreport" />

## LossReport

```python theme={null}
from qitos.tracing.trajectory import LossReport
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/trajectory.py#L122)

[Usage and executable example](/guides/observability)

```text theme={null}
Explicit fidelity report carried by readers, exporters and evaluators.
```

| Field       | Type                    | Default             |
| ----------- | ----------------------- | ------------------- |
| `policy_id` | `str`                   | `'qitos.loss/none'` |
| `entries`   | `Tuple[LossEntry, ...]` | `()`                |

<span id="qitos-tracing-trajectory-lossreport-from-dict" />

### LossReport.from\_dict

```text theme={null}
from_dict(value: Mapping[str, Any]) -> 'LossReport'
```

| Parameter | Type                | Default    |
| --------- | ------------------- | ---------- |
| `value`   | `Mapping[str, Any]` | `required` |

[Source](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/trajectory.py#L149)

<span id="qitos-tracing-exporter-exportartifact" />

## ExportArtifact

```python theme={null}
from qitos.tracing.exporter import ExportArtifact
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/exporter.py#L40)

[Usage and executable example](/guides/observability)

| Field            | Type             | Default    |
| ---------------- | ---------------- | ---------- |
| `exporter_id`    | `str`            | `required` |
| `format_version` | `str`            | `required` |
| `content_type`   | `str`            | `required` |
| `data`           | `bytes`          | `required` |
| `digest`         | `str`            | `required` |
| `privacy_view`   | `PrivacyView`    | `required` |
| `exact_reimport` | `bool`           | `required` |
| `provenance`     | `Dict[str, Any]` | `required` |
| `loss`           | `LossReport`     | `required` |

<span id="qitos-tracing-streaming-fileexportreceipt" />

## FileExportReceipt

```python theme={null}
from qitos.tracing.streaming import FileExportReceipt
```

[Source @ f7d4b2d](https://github.com/WhitzardAgent/WhitzardOS/blob/f7d4b2d666a156d361da496a41868278f84ffabf/qitos/tracing/streaming.py#L22)

[Usage and executable example](/guides/observability)

```text theme={null}
Returned only after full validation, fsync and atomic replacement.
```

| Field          | Type          | Default    |
| -------------- | ------------- | ---------- |
| `record_count` | `int`         | `required` |
| `size_bytes`   | `int`         | `required` |
| `digest`       | `str`         | `required` |
| `privacy_view` | `PrivacyView` | `required` |
| `completed`    | `bool`        | `True`     |