Trace API

Status: Generated from current Python docstrings and type hints.

ARM Trace schema, manifests, hash chain primitives, and review report helpers used by the independent gaia trace CLI sub-app (verify / review / show).

gaia.engine.trace

ARM Trace — 7th modality of ARM v1 (4/27).

提供： - Trace / TraceEvent / TraceManifest / ClaimRef pydantic schema - canonical-json + sha256 hash chain（事件级抗作弊） - 11 个确定性 detector（无 LLM 参与） - TraceReviewReport 八段 review（与 gaia.inquiry 设计同质） - run_trace_review(path, *, mode="trace") 端到端入口

目标：审计/debug/学习一段 ARM 执行轨迹时，给出可解释、可重算、不易作弊的报告。

TraceReviewReport dataclass

TraceReviewReport(trace_review_id: str, created_at: str, path: str, mode: str, manifest_status: str, manifest_hash: str | None, counts: dict[str, int] = dict(), hash_chain: dict[str, Any] = dict(), causal_health: dict[str, Any] = dict(), reference_validity: list[dict[str, Any]] = list(), tampering: list[dict[str, Any]] = list(), execution_stats: dict[str, Any] = dict(), diagnostics: list[Diagnostic] = list(), next_edits: list[str] = list(), next_edits_structured: list[NextEdit] = list())

Represent the eight-section ARM trace review report.

section mapping（参 PLAN 与 gaia.inquiry.ReviewReport）： §1 Header — trace_review_id / created_at / path / mode §2 Manifest — manifest_status / manifest_hash / counts §3 Hash Chain — hash_chain (ok / broken_at_seq / recomputed_root) §4 Causal Health — causal_health (tool_pairing / decision_grounds / parent_links / actor_continuity) §5 Reference Validity — reference_validity (claim_ref 解析摘要) §6 Tampering Signals — tampering (篡改信号集中视图) §7 Execution Stats — execution_stats (actors / kind 分布 / retry / time_span) §8 Diagnostics + NextEdits — diagnostics / next_edits / next_edits_structured

to_json_dict

to_json_dict() -> dict[str, Any]

Return the JSON-compatible report payload.

Source code in gaia/engine/trace/review.py

def to_json_dict(self) -> dict[str, Any]:
    """Return the JSON-compatible report payload."""
    d: dict[str, Any] = {
        "trace_review_id": self.trace_review_id,
        "created_at": self.created_at,
        "path": self.path,
        "mode": self.mode,
        "manifest_status": self.manifest_status,
        "manifest_hash": self.manifest_hash,
        "counts": dict(self.counts),
        "hash_chain": dict(self.hash_chain),
        "causal_health": dict(self.causal_health),
        "reference_validity": [dict(x) for x in self.reference_validity],
        "tampering": [dict(x) for x in self.tampering],
        "execution_stats": dict(self.execution_stats),
        "diagnostics": [d.to_dict() for d in self.diagnostics],
        "next_edits": list(self.next_edits),
        "next_edits_structured": [e.to_dict() for e in self.next_edits_structured],
    }
    return d

ClaimRef

Bases: BaseModel

Reference one Gaia knowledge claim from a trace event.

Trace

Bases: BaseModel

Represent a complete trace as a manifest plus ordered events.

TraceEvent

Bases: BaseModel

Represent the smallest accounting unit in an ARM trace.

• prev_hash：前一事件的 canonical-json sha256（首事件 ""）
• seq：单调递增整数，从 0 起，reviewer 校验连续
• ts：utc datetime；reviewer 校验单调非降
• parent_event_id：retry / sub-call 父子关系（None ⇒ root 事件）

TraceManifest

Bases: BaseModel

Describe trace metadata and hash anchors.

events_root / manifest_hash 在写入端计算后冻结， reviewer 端独立重算比对——任何字段被改 ⇒ 哈希不一致。

signature 字段是 v2 hook，v1 不验签也不强求填。

run_trace_review

run_trace_review(path: str | Path, *, mode: str = 'trace', resolver: ReviewIdResolver | None = None, package_path: str | Path | None = None, retry_chain_limit: int = RETRY_CHAIN_LIMIT_DEFAULT, snapshot_dir: str | Path | None = None) -> TraceReviewReport

Load a trace, run detectors, build sections, and save a snapshot.

mode 与 ranking 的 mode 表对齐；默认 "trace"。 mode == "publish" 时 ranking 套 publish 表，warning 也会被前置。 snapshot_dir=None 走默认 <cwd>/.gaia/trace/reviews/。

Source code in gaia/engine/trace/review.py

def run_trace_review(
    path: str | Path,
    *,
    mode: str = "trace",
    resolver: ReviewIdResolver | None = None,
    package_path: str | Path | None = None,
    retry_chain_limit: int = RETRY_CHAIN_LIMIT_DEFAULT,
    snapshot_dir: str | Path | None = None,
) -> TraceReviewReport:
    """Load a trace, run detectors, build sections, and save a snapshot.

    ``mode`` 与 ranking 的 mode 表对齐；默认 ``"trace"``。
    ``mode == "publish"`` 时 ranking 套 publish 表，warning 也会被前置。
    ``snapshot_dir=None`` 走默认 ``<cwd>/.gaia/trace/reviews/``。
    """
    load_result: LoadResult = load_trace(path)
    trace = load_result.trace

    diags: list[Diagnostic] = []
    diags.extend(from_schema_issues(load_result.issues))
    if trace is not None:
        diags.extend(detect_hash_chain(trace))
        diags.extend(detect_manifest_hash(trace))
        diags.extend(detect_timestamps(trace))
        diags.extend(detect_seq(trace))
        diags.extend(detect_decision_grounds(trace))
        diags.extend(detect_tool_pairing(trace))
        diags.extend(detect_claim_refs(trace, resolver=resolver, package_path=package_path))
        diags.extend(detect_parent_links(trace))
        diags.extend(detect_retry(trace, max_chain=retry_chain_limit))
        diags.extend(detect_actor(trace))

    diags = rank_diagnostics(diags, mode)

    next_edits_structured = [_to_next_edit(d) for d in diags]
    next_edits_structured = rank_next_edits(next_edits_structured, mode)
    next_edits = [edit.text for edit in next_edits_structured if edit.text]

    manifest_status, manifest_hash, counts = _build_manifest_section(trace)
    hash_chain = _build_hash_chain_section(trace)
    causal_health = _build_causal_health_section(diags, trace)
    reference_validity = _build_reference_section(
        trace, resolver=resolver, package_path=package_path
    )
    tampering = _build_tampering_section(diags)
    execution_stats = _build_execution_stats(trace)

    ir_hash = manifest_hash or hash_chain.get("recomputed_root", "") or "nohash"
    review_id = mint_review_id(ir_hash, mode)

    report = TraceReviewReport(
        trace_review_id=review_id,
        created_at=_utcnow_iso(),
        path=str(path),
        mode=mode,
        manifest_status=manifest_status,
        manifest_hash=manifest_hash,
        counts=counts,
        hash_chain=hash_chain,
        causal_health=causal_health,
        reference_validity=reference_validity,
        tampering=tampering,
        execution_stats=execution_stats,
        diagnostics=diags,
        next_edits=next_edits,
        next_edits_structured=next_edits_structured,
    )

    # 写 snapshot——失败不应让 review 失败
    try:
        from gaia.engine.trace.snapshot import save_trace_review_snapshot

        save_trace_review_snapshot(report, snapshot_dir=snapshot_dir)
    except Exception:
        pass

    return report