> ## 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 与 reader

> QitOS public API: trajectory

default\_reader 选择 canonical journal 和支持的历史 reader。读取与回放是观察，不执行或恢复 Agent。REDACTED\_PUBLIC 导出明确声明损失；重新导入后记录数相同不能证明 raw 数据等价。旧完整读取仍会全量加载 journal。qit/qita 命令参考说明 CLI 的实际用法与退出行为。

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

以下签名和字段由固定源码提取；签名是参考，不是可直接运行的程序。每个条目的源码链接绑定同一 runtime baseline。类型中的 Any 不代表任意对象均受支持，应结合上述行为契约和教程使用。

`StoreTrajectoryReader.from_journal` 与现有 file/default adapter 提供 `read_page(query, cursor=None)`。`page.records`、`page.next_cursor`、`page.watermark` 描述固定快照。warm page 仍 hash 全部快照字节，但仅解析寻址 frame；临时磁盘索引和固定 cache 避免保留全历史。旧完整读取和 re-import 仍物化。`export_file` 在最终校验后原子替换文件，失败保留原目标。

连续 `iter_records` 与文件导出在开始、结束时校验完整快照，遍历时逐 frame 校验。迭代值在**耗尽前属于 partial**；提前 close 释放资源，但不证明遍历完成。文件仅在最终校验后发布。独立 `read_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)

[用法与可执行示例](/zh/guides/observability)

用法片段：接续上方完整教程中的对象，不是独立程序。

```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)

[用法与可执行示例](/zh/guides/observability)

用法片段：接续上方完整教程中的对象，不是独立程序。

```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)

[用法与可执行示例](/zh/guides/observability)

用法片段：接续上方完整教程中的对象，不是独立程序。

```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)

[用法与可执行示例](/zh/guides/observability)

用法片段：接续上方完整教程中的对象，不是独立程序。

```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)

[用法与可执行示例](/zh/guides/observability)

用法片段：接续上方完整教程中的对象，不是独立程序。

```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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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)

[用法与可执行示例](/zh/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`     |