agentloop-profiler 0.1.0__py3-none-any.whl

agentloop/html_report.py

@@ -0,0 +1,860 @@
+"""Offline HTML analysis artifact with escaped text and no executable trace markup."""
+
+from __future__ import annotations
+
+import html
+import json
+from typing import Any
+
+from agentloop.costs import format_cost_usd
+from agentloop.harness_evidence import METADATA_KEY, HarnessEvidenceError, read_evidence
+from agentloop.timing import event_interval_ms, format_duration_ms
+from agentloop.tracer import AgentTrace
+
+_CSS = """
+:root{color-scheme:light;--ink:#172c37;--muted:#526675;--line:#d6e1e6;--accent:#086d79;--paper:#f4f7f8}
+*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--paper);color:var(--ink);font:16px/1.55 system-ui,sans-serif}
+main{max-width:1160px;margin:auto;padding:36px 24px 80px}header{border-bottom:3px solid var(--accent);padding-bottom:24px}
+h1{font-size:2rem;line-height:1.2;overflow-wrap:anywhere}h2{margin-top:38px}h3{margin:0 0 12px}p{max-width:90ch}
+a{color:#075b86}a:focus-visible,summary:focus-visible{outline:3px solid #b76308;outline-offset:4px}
+nav{display:flex;flex-wrap:wrap;gap:18px;margin-top:18px}.eyebrow{letter-spacing:.09em;text-transform:uppercase;font-size:.8rem;color:var(--accent);font-weight:700}
+.muted{color:var(--muted)}.cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:14px}
+.metric,article,details.panel{background:white;border:1px solid var(--line);border-radius:9px;padding:18px}.metric strong{display:block;font-size:1.6rem}
+.badge{display:inline-block;background:#e4eef2;padding:2px 8px;border-radius:4px;font-size:.8rem;margin-right:6px}
+.prediction{border-left:4px solid #8a6200}.notice{padding:12px 16px;background:#fff2d8;border-left:4px solid #9c6800}
+.table-wrap{overflow-x:auto}table{width:100%;border-collapse:collapse;background:white}th,td{text-align:left;padding:11px;border-bottom:1px solid var(--line);vertical-align:top}
+th{background:#eaf0f3}caption{text-align:left;color:var(--muted);padding:8px 0}code,pre{font: .88rem/1.5 ui-monospace,monospace}code{overflow-wrap:anywhere}
+pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#edf2f4;padding:14px;border-radius:6px}summary{cursor:pointer;font-weight:600}details{margin:12px 0}
+article{margin:14px 0;scroll-margin-top:20px}tr:target{background:#fff2d8}.track{min-width:180px;background:#e8eff2;height:12px;border-radius:6px}.bar{height:12px;background:var(--accent);border-radius:6px}
+dl{display:grid;grid-template-columns:minmax(140px,1fr) 3fr;gap:7px 16px}dt{color:var(--muted)}dd{margin:0;overflow-wrap:anywhere}
+footer{margin-top:45px;padding-top:16px;border-top:1px solid var(--line);font-size:.85rem;color:var(--muted)}
+@media(max-width:600px){main{padding:20px 12px}h1{font-size:1.65rem}dl{display:block}dd{margin-bottom:10px}}
+@media print{body{background:white}main{max-width:none;padding:0}nav{display:none}article,.metric{break-inside:avoid}a{color:inherit}}
+@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}}
+"""
+
+
+def _text(value: Any) -> str:
+    return html.escape(str(value), quote=True)
+
+
+def _json(value: Any) -> str:
+    return (
+        "<pre>" + _text(json.dumps(value, indent=2, sort_keys=True, ensure_ascii=False)) + "</pre>"
+    )
+
+
+def _definition(items: list[tuple[str, Any]]) -> str:
+    return (
+        "<dl>"
+        + "".join(f"<dt>{_text(key)}</dt><dd>{_text(value)}</dd>" for key, value in items)
+        + "</dl>"
+    )
+
+
+def _table(headers: list[str], rows: list[list[str]], *, caption: str) -> str:
+    return (
+        '<div class="table-wrap"><table><caption>'
+        + _text(caption)
+        + "</caption><thead><tr>"
+        + "".join(f'<th scope="col">{_text(header)}</th>' for header in headers)
+        + "</tr></thead><tbody>"
+        + "".join("<tr>" + "".join(f"<td>{cell}</td>" for cell in row) + "</tr>" for row in rows)
+        + "</tbody></table></div>"
+    )
+
+
+def cohort_to_html(report: dict[str, Any]) -> str:
+    """Render full-population cohort evidence with the existing local report styles."""
+    sections = [
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        "<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'\">",
+        f"<title>{_text(report['name'])}</title><style>{_CSS}</style></head><body><main><h1>{_text(report['name'])}</h1>",
+        '<p class="notice">External source evidence. Correctness, execution and source coverage are independent gates. No causal harness effect or estimator attribution is invented.</p>',
+    ]
+    if report["synthetic"]:
+        sections.append(
+            '<p class="notice">Synthetic inputs: these reports demonstrate validation and do not establish empirical performance benefits.</p>'
+        )
+    sections.append(
+        _table(
+            ["Condition", "Attempts retained", "Accepted", "Rejected", "Indeterminate"],
+            [
+                [
+                    _text(condition),
+                    _text(population["denominator"]),
+                    _text(population["accepted"]),
+                    _text(population["rejected"]),
+                    _text(population["acceptance_indeterminate"]),
+                ]
+                for condition, population in report["conditions"].items()
+            ],
+            caption="Complete observed and planned attempt populations",
+        )
+    )
+    for condition, comparison in report["comparisons"].items():
+        sections.extend(
+            [
+                f"<h2>Baseline vs {_text(condition)}</h2>",
+                f"<p>Comparison: {_text(comparison['comparison_kind'])}; causal harness effect not established.</p>",
+                _table(
+                    ["Task", "Outcome", "Runtime improvement"],
+                    [
+                        [
+                            _text(pair["pairing_metadata"]["task_id"]),
+                            _text(pair["state"]),
+                            _text(
+                                pair["runtime_improvement_pct"]
+                                if pair["runtime_improvement_pct"] is not None
+                                else "unavailable"
+                            ),
+                        ]
+                        for pair in comparison["pairs"]
+                    ],
+                    caption="Independent task-quality and source-evidence gates",
+                ),
+                _definition(
+                    [
+                        ("Unpaired records", comparison["unpaired_count"]),
+                        (
+                            "Planned unidentified candidate attempts",
+                            comparison["quality_preserving_intervention_rate"][
+                                "unidentified_planned_attempts"
+                            ],
+                        ),
+                        (
+                            "Verified improvements / candidate attempts",
+                            f"{comparison['quality_preserving_intervention_rate']['numerator']} / {comparison['quality_preserving_intervention_rate']['denominator']}",
+                        ),
+                    ]
+                ),
+            ]
+        )
+    sections.append("</main></body></html>")
+    return "\n".join(sections)
+
+
+def coordination_to_html(report: dict[str, Any]) -> str:
+    """Render source-qualified bundle coordination with the local report styles."""
+    sections = [
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        "<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'\">",
+        f"<title>AgentLoop coordination</title><style>{_CSS}</style></head><body><main><h1>Recorded coordination</h1>",
+        '<p class="notice">External observations. Missing timing is unavailable, child runtime is not caller wait, and overlap does not prove independent work. Reviewer labels do not establish correctness.</p>',
+    ]
+    if report["synthetic"]:
+        sections.append(
+            '<p class="notice">Synthetic inputs: no empirical performance or quality benefit is established.</p>'
+        )
+    sections.append(
+        _definition(
+            [
+                ("Recorded handoffs", report["handoff_count"]),
+                (
+                    "Observed / unknown children",
+                    f"{report['observed_child_count']} / {report['unknown_child_count']}",
+                ),
+                ("Recorded child failures", report["child_failure_count"]),
+                ("Caller wait", format_duration_ms(report["handoff_wait_ms"])),
+                ("Observed overlap", format_duration_ms(report["parallel_overlap_ms"])),
+                ("Critical path", format_duration_ms(report["critical_path_ms"])),
+                (
+                    "Possible duplicate work",
+                    report["possible_duplicate_work_count"]
+                    if report["possible_duplicate_work_count"] is not None
+                    else "unavailable",
+                ),
+            ]
+        )
+    )
+    sections.append(
+        _table(
+            ["Agent", "Declared role", "Session / document", "Recorded runtime", "Status"],
+            [
+                [
+                    _text(actor["agent_name"] or "unknown"),
+                    _text(actor["declared_role"] or "unknown"),
+                    _text(
+                        actor["source_identity"]["trajectory_id"]
+                        or actor["session_id"]
+                        or "unknown"
+                    ),
+                    _text(format_duration_ms(actor["runtime_ms"])),
+                    _text(actor["execution_status"]),
+                ]
+                for actor in report["actors"]
+            ],
+            caption="Distinct source actors; shared sessions preserve document and trace identities",
+        )
+    )
+    sections.extend(
+        [
+            "<h2>Evidence coverage and limitations</h2>",
+            _json(report["overlap_coverage"]),
+            "<ul>"
+            + "".join("<li>" + _text(item) + "</li>" for item in report["limitations"])
+            + "</ul>",
+            "<p>Inclusive usage remains separate from attributed model leaves. Retries, safe reuse, review overhead and review quality effects require additional evidence.</p></main></body></html>",
+        ]
+    )
+    return "\n".join(sections)
+
+
+def analysis_to_html(payload: dict[str, Any], *, include_content: bool = False) -> str:
+    """Render the combined `analyze` payload. All source values enter as escaped text."""
+    required = {"trace", "report", "diagnosis", "optimization"}
+    if (
+        not isinstance(payload, dict)
+        or not required <= payload.keys()
+        or any(not isinstance(payload[key], dict) for key in required)
+    ):
+        raise ValueError("expected a combined trace, report, diagnosis, and optimization payload")
+    trace = AgentTrace.from_dict(payload["trace"])
+    report, diagnosis, plan = payload["report"], payload["diagnosis"], payload["optimization"]
+    nodes = plan.get("graph", {}).get("nodes", [])
+    anchors = {node["node_id"]: f"span-{index}" for index, node in enumerate(nodes)}
+    harness_link = (
+        '<a href="#harness">Harness decisions</a>' if METADATA_KEY in trace.metadata else ""
+    )
+    sections = [
+        '<!doctype html><html lang="en"><head><meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        "<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'\">",
+        f"<title>{_text(trace.name)} — AgentLoop analysis</title><style>{_CSS}</style></head><body><main>",
+        f'<header><div class="eyebrow">AgentLoop · analysis artifact</div><h1>{_text(trace.name)}</h1>',
+        f'<p class="muted">Run <code>{_text(trace.run_id)}</code></p>',
+        f'<nav aria-label="Report sections"><a href="#overview">Overview</a><a href="#timeline">Timeline</a><a href="#findings">Findings</a><a href="#comparison">Comparison</a>{harness_link}<a href="#metadata">Metadata</a></nav></header>',
+        '<section id="overview"><h2>Recorded execution</h2>',
+    ]
+    if trace.metadata.get("synthetic") is True:
+        sections.append(
+            '<p class="notice">Synthetic trace: these results demonstrate analysis and are not application performance evidence.</p>'
+        )
+    if trace.metadata.get("execution_data_present") is False:
+        sections.append(
+            '<p class="notice">No execution spans were supplied. This artifact contains external evaluation metadata.</p>'
+        )
+    if report.get("external_evidence") is not None:
+        external = report["external_evidence"]
+        sections.append(
+            '<p class="notice">External execution evidence: source status and usage are reported, not independently verified. Unavailable durations are not measured zero; task correctness requires a separate verifier.</p>'
+            + _definition(
+                [
+                    ("Source system", external["source"].get("system", "unknown")),
+                    ("Source format", external["source"].get("format", "unknown")),
+                    ("Source receipt", external["receipt_id"]),
+                    ("Source execution status", external["execution_status"]),
+                    ("Reported model call multiplicity", external["reported_model_call_count"]),
+                ]
+            )
+        )
+    if report.get("omnigent_observations") is not None:
+        observed = report["omnigent_observations"]
+        sections.append(
+            "<h3>Omnigent observations</h3>"
+            + _definition(
+                [
+                    ("Agents", ", ".join(observed["agent_names"]) or "unknown"),
+                    ("Session", observed["source_identity"]["session_id"] or "unknown"),
+                    ("Executor model coverage", observed["model_coverage"]),
+                    ("Policy enforcement", observed["enforcement"]),
+                    ("Task correctness", observed["task_correctness"]),
+                ]
+            )
+            + '<p class="notice">Policy verdicts and tool spans are external observations. A DENY or ASK does not prove prevention or approval. Sessions retain separate trace identities; links do not establish causal dependencies.</p>'
+            + _table(
+                ["Policy", "Phase", "Decision", "Dispatch prevention"],
+                [
+                    [
+                        _text(item["name"] or "unknown"),
+                        _text(item["phase"] or "unknown"),
+                        _text(item["action"]),
+                        _text(item["dispatch_prevention"]),
+                    ]
+                    for item in observed["policy_decisions"]
+                ],
+                caption="Externally reported policy decisions; enforcement remains unverified",
+            )
+            + _table(
+                ["Observed role", "Spans", "Interval union", "Coverage"],
+                [
+                    [
+                        _text(role),
+                        _text(value["spans"]),
+                        _text(format_duration_ms(value["interval_union_ms"])),
+                        _text(value["coverage"]),
+                    ]
+                    for role, value in observed["timing_by_role"].items()
+                ],
+                caption="Role intervals are separate observations; cumulative values can overlap",
+            )
+        )
+    if report.get("execution") is not None:
+        execution = report["execution"]
+        sections.append(
+            "<h3>Workflow</h3>"
+            + _definition(
+                [
+                    (key.replace("_", " ").title(), value)
+                    for key, value in execution.items()
+                    if value is not None
+                ]
+            )
+        )
+        sections.append(
+            '<p class="notice">Cost and token totals cover recorded model calls. A completed execution or outcome label is not independent task-quality evidence.</p>'
+        )
+    dependency_evidence = plan.get("graph", {}).get("dependency_evidence")
+    if "semantic_waste" in report:
+        semantic = report["semantic_waste"]
+        sections.append(
+            '<section id="semantic-investigations"><h2>Offline semantic investigations</h2>'
+            "<p>These investigations use explicit task criteria and source-bound evidence. "
+            "Unknowns, disagreement and stale evidence do not produce recommendations. "
+            "Any savings are conditional estimates requiring independent replay validation.</p>"
+            + _table(
+                ["Investigation", "Family", "Status", "Evidence basis"],
+                [
+                    [
+                        _text(item["definition"]["investigation_id"]),
+                        _text(item["definition"]["family"]),
+                        _text(item["status"]),
+                        _text(item["basis"]),
+                    ]
+                    for item in semantic["cases"]
+                ],
+                caption="Investigation completeness: " + semantic["status"],
+            )
+            + "</section>"
+        )
+    if "semantic_judgments" in report:
+        sections.append(
+            '<section id="judgments"><h2>Offline semantic judgments</h2>'
+            "<p>Recorded execution facts, deterministic rule inferences, and semantic "
+            "judge answers are separate evidence categories. Judge answers do not "
+            "establish task quality or calibrated confidence. Judge latency and cost "
+            "are analysis overhead, separate from workflow totals.</p>"
+            + _table(
+                [
+                    "Judge / version",
+                    "Question",
+                    "Status",
+                    "Answer",
+                    "Confidence basis",
+                    "Incurred cost USD",
+                ],
+                [
+                    [
+                        _text(f"{item['judge']['implementation']} / {item['judge']['version']}"),
+                        _text(item["request"]["spec"]["question"]),
+                        _text(item["effective_status"]),
+                        _text(
+                            "unavailable"
+                            if item["effective_value"] is None
+                            else item["effective_value"]
+                        ),
+                        _text(item["evaluation"]["uncertainty"]["calibration_status"]),
+                        _text(
+                            "unavailable"
+                            if item["invocation"]["usage"]["cost_usd"] is None
+                            else item["invocation"]["usage"]["cost_usd"]
+                        ),
+                    ]
+                    for item in report["semantic_judgments"]["records"]
+                ],
+                caption="Saved judgment evidence: " + report["semantic_judgments"]["status"],
+            )
+            + "<details><summary>Archived provenance and usage receipts</summary>"
+            + _json(report["semantic_judgments"])
+            + "</details>"
+            + "</section>"
+        )
+    if dependency_evidence is not None:
+        sections.append(
+            "<details><summary>Dependency declarations</summary>"
+            + _json(dependency_evidence)
+            + "</details>"
+        )
+    if not diagnosis.get("analysis_complete", True):
+        sections.append(
+            '<p class="notice">Analysis incomplete: one or more finding rules failed.</p>'
+            + _json(diagnosis.get("rule_errors", []))
+        )
+    metrics = [
+        ("Elapsed runtime", format_duration_ms(report["total_runtime_ms"], precision=3)),
+        ("Recorded spans", report["event_count"]),
+        ("Input / output tokens", f"{report['input_tokens']} / {report['output_tokens']}"),
+        (
+            "Cost from supplied pricing/usage",
+            format_cost_usd(
+                report.get("estimated_cost_usd"),
+                report.get("cost_status"),
+                token_status=report.get("token_status"),
+            ),
+        ),
+    ]
+    sections.append(
+        '<div class="cards">'
+        + "".join(
+            f'<div class="metric"><span>{_text(label)}</span><strong>{_text(value)}</strong></div>'
+            for label, value in metrics
+        )
+        + "</div>"
+    )
+    sections.append(
+        _definition(
+            [
+                ("Token basis", report.get("token_status", "unspecified")),
+                ("Cost completeness", report.get("cost_status", "unknown")),
+                (
+                    "Cumulative span time",
+                    format_duration_ms(report["cumulative_span_time_ms"], precision=3)
+                    + "; overlapping/nested work may exceed elapsed runtime",
+                ),
+            ]
+        )
+    )
+    sections.append("</section>" + _timeline(trace, nodes, anchors))
+    bottlenecks = plan.get("graph", {}).get("bottlenecks", [])
+    if bottlenecks:
+        rows = []
+        for node in bottlenecks:
+            label = _text(node["name"])
+            if node["node_id"] in anchors:
+                label = f'<a href="#{anchors[node["node_id"]]}">{label}</a>'
+            rows.append(
+                [
+                    label,
+                    _text(f"{node['duration_ms']:.3f} ms"),
+                    _text(f"{node['runtime_share']:.1%}"),
+                ]
+            )
+        sections.append(
+            "<h2>Longest recorded spans</h2>"
+            + _table(
+                ["Span", "Duration", "Elapsed runtime share"],
+                rows,
+                caption="Bottleneck candidates from recorded durations; nested spans can overlap.",
+            )
+        )
+    sections.append(
+        '<section id="findings"><h2>Predicted improvements</h2><p>Optimizer savings are uncalibrated hypotheses. Validate a candidate run and its quality before accepting a change.</p>'
+    )
+    after = plan["estimated_after"]
+    if (
+        plan.get("savings_aggregation", {}).get("latency_estimate_complete") is False
+        or plan.get("savings_aggregation", {}).get("cost_estimate_complete") is False
+    ):
+        sections.append(
+            '<p class="notice">Some savings are unavailable; totals cover modeled candidates only.</p>'
+        )
+    sections.append(
+        '<article class="prediction"><h3>Predicted outcome</h3>'
+        + _definition(
+            [
+                ("Estimated runtime", format_duration_ms(after["runtime_ms"], precision=3)),
+                (
+                    "Estimated latency reduction",
+                    "unavailable"
+                    if after["latency_reduction_pct"] is None
+                    else f"{after['latency_reduction_pct']:.2f}%",
+                ),
+                (
+                    "Estimated cost",
+                    format_cost_usd(after.get("estimated_cost_usd"), after.get("cost_status")),
+                ),
+            ]
+        )
+        + "<details><summary>Compatible finding selection</summary><p>Exact selection describes the chosen combination; it does not calibrate the savings predictions.</p>"
+        + _json(plan.get("savings_aggregation", {}))
+        + "</details></article>"
+    )
+    findings = diagnosis.get("findings", [])
+    if diagnosis.get("ranking"):
+        sections.append(
+            "<p>Investigation order: "
+            + _text(diagnosis["ranking"]["sort_by"])
+            + ". Readiness and missing inputs are separate from estimated savings; ranking does not authorize a change.</p>"
+        )
+    if not findings:
+        sections.append("<p>No optimization findings were detected.</p>")
+    for index, finding in enumerate(findings):
+        sections.append(_finding(finding, index, anchors))
+    sections.append(
+        '</section><section id="comparison"><h2>Observed baseline / candidate comparison</h2>'
+    )
+    replay = payload.get("replay")
+    if replay:
+        sections.append(_comparison(replay))
+    else:
+        sections.append(
+            "<p>No baseline was supplied. Predicted improvements above have not been verified by this report.</p>"
+        )
+    metadata = dict(trace.metadata)
+    harness_section = ""
+    if METADATA_KEY in metadata:
+        metadata.pop(METADATA_KEY)
+        harness_section = _harness_section(trace, anchors, include_content=include_content)
+    sections.append(
+        "</section>"
+        + harness_section
+        + '<section id="metadata"><h2>Trace and research metadata</h2><p class="notice">Metadata may contain private text or identifiers. Review it before sharing this file.</p>'
+        + _json(metadata)
+    )
+    if include_content:
+        sections.append(
+            '<p class="notice">Raw prompts, outputs, errors, and event metadata are included below. Review this content before sharing.</p><details class="panel"><summary>Included event content</summary>'
+            + _json([event.to_dict() for event in trace.events])
+            + "</details>"
+        )
+    else:
+        sections.append(
+            "<p>Raw event text and full event metadata are omitted. Finding evidence and trace metadata remain included.</p>"
+        )
+    sections.append(
+        "</section><footer>Generated by AgentLoop. This file contains embedded styles and requires no network connection.</footer></main></body></html>"
+    )
+    return "\n".join(sections) + "\n"
+
+
+def _harness_section(trace: AgentTrace, anchors: dict[str, str], *, include_content: bool) -> str:
+    opening = '<section id="harness"><h2>Harness decisions</h2>'
+    try:
+        evidence = read_evidence(trace)
+    except HarnessEvidenceError:
+        return (
+            opening
+            + '<p class="notice">Harness evidence is invalid or unsupported. Its raw content is omitted.</p></section>'
+        )
+    if evidence is None:
+        return opening + "<p>No decision evidence was retained.</p></section>"
+    records = dict(
+        sorted(
+            evidence["decisions"].items(),
+            key=lambda item: (
+                item[1]["run_id"],
+                -1 if item[1]["hook_sequence"] is None else item[1]["hook_sequence"],
+                item[1]["policy_order"],
+                item[0],
+            ),
+        )
+    )
+    links = {identity: f"harness-decision-{index}" for index, identity in enumerate(records)}
+    content = [
+        opening,
+        "<p>Decisions record proposed and applied controls, not proven benefits. Shadow proposals are not executed interventions. Individual policy effects remain unverified; use an intervention comparison with explicit quality gates.</p>",
+    ]
+    if evidence["capture_errors"]:
+        content.append(
+            '<p class="notice">Decision capture was incomplete.</p>'
+            + _json(evidence["capture_errors"])
+        )
+    hook_times = {}
+    for record in records.values():
+        hook_times.setdefault(record["hook_id"], record["timing"]["hook_duration_ms"])
+    known = [duration for duration in hook_times.values() if duration is not None]
+    content.append(
+        _definition(
+            [
+                ("Decision records", len(records)),
+                ("Distinct evaluated hooks", len(hook_times)),
+                (
+                    "Measured cumulative hook evaluation",
+                    f"{sum(known):.3f} ms across {len(known)} hooks; includes lock wait, excludes evidence serialization; concurrent hooks may overlap",
+                ),
+                (
+                    "Model/tool usage",
+                    "Policy timing is separate from model/tool spans and carries no invented token or cost usage",
+                ),
+            ]
+        )
+    )
+    for identity, record in records.items():
+        span = record["span_id"]
+        span_link = (
+            f'<a href="#{anchors[span]}">{_text(span)}</a>'
+            if span in anchors
+            else _text(span or "not recorded")
+        )
+        related = ([record["retry_of"]] if record["retry_of"] is not None else []) + record[
+            "conflicting_decision_ids"
+        ]
+        related_links = [
+            f'<a href="#{links[item]}">{_text(item)}</a>'
+            if item in links
+            else _text(item) + " (not retained)"
+            for item in related
+        ]
+        content.append(
+            f'<article id="{links[identity]}"><h3>{_text(record["policy_id"])} · {_text(record["outcome"])}</h3>'
+            + _definition(
+                [
+                    ("Decision", identity),
+                    ("Run / branch", f"{record['run_id']} / {record['branch_id']}"),
+                    ("Policy version", record["policy_version"]),
+                    ("Mode", record["mode"]),
+                    ("Boundary", f"{record['boundary']}/{record['phase']}"),
+                    (
+                        "Requested / resolved action",
+                        f"{record['requested_action']} / {record['resolved_action']}",
+                    ),
+                    ("Invocation attempted", record["dispatched"]),
+                    ("Execution status", record["execution_status"]),
+                    ("Reason", record["reason_code"]),
+                    ("Diagnostic feedback", record.get("feedback") or "none"),
+                    (
+                        "Budget snapshot",
+                        "unavailable" if record["budget_snapshot"] is None else "recorded",
+                    ),
+                ]
+            )
+            + f"<p>Parent span: {span_link}</p><p>Retry / conflict links: {', '.join(related_links) or 'none'}</p>"
+            + "<details><summary>Decision provenance and timing</summary>"
+            + _json(record)
+            + "</details></article>"
+        )
+    policies = evidence["policies"]
+    if not include_content:
+        for snapshot in policies.values():
+            snapshot["configuration"] = None
+            snapshot["configuration_capture"] = "redacted"
+    content.append(
+        "<details><summary>Historical policy declarations</summary><p>Configuration hashes identify snapshots; fingerprints do not anonymize data. Raw configuration requires explicit capture and content inclusion.</p>"
+        + _json(policies)
+        + "</details></section>"
+    )
+    return "".join(content)
+
+
+def _timeline(trace: AgentTrace, nodes: list[dict[str, Any]], anchors: dict[str, str]) -> str:
+    intervals = {event.event_id: event_interval_ms(event) for event in trace.events}
+    known = [interval for interval in intervals.values() if interval is not None]
+    start = min((interval[0] for interval in known), default=0)
+    extent = max((interval[1] for interval in known), default=start) - start
+    rows = []
+    for node in nodes:
+        interval = intervals.get(node["node_id"])
+        bar = "Timing unavailable"
+        if interval is not None and extent > 0:
+            offset = max(0.0, min(100.0, (interval[0] - start) / extent * 100))
+            width = max(0.0, min(100 - offset, (interval[1] - interval[0]) / extent * 100))
+            bar = f'<div class="track" aria-hidden="true"><div class="bar" style="margin-left:{offset:.4f}%;width:{width:.4f}%"></div></div>'
+        parent = node.get("parent_id")
+        parent_link = (
+            f'<a href="#{anchors[parent]}">{_text(parent)}</a>'
+            if parent in anchors
+            else _text(parent or "root")
+        )
+        stage = node.get("stage")
+        stage_detail = ""
+        if stage is not None:
+            stage_detail = (
+                "<details><summary>Stage: "
+                + _text(stage.get("stage_id") or stage.get("schema_status"))
+                + "</summary>"
+            )
+            stage_detail += _definition(
+                [
+                    (key.replace("_", " ").title(), stage.get(key))
+                    for key in (
+                        "version",
+                        "kind",
+                        "input_schema_ref",
+                        "output_schema_ref",
+                        "input_ref",
+                        "output_ref",
+                        "outcome",
+                    )
+                    if stage.get(key) is not None
+                ]
+            )
+            links = [
+                f'<a href="#{anchors[source]}">{_text(source)}</a>'
+                if source in anchors
+                else _text(source) + " (unresolved)"
+                for source in stage.get("depends_on", [])
+            ]
+            if links:
+                stage_detail += "<p>Depends on: " + ", ".join(links) + "</p>"
+            stage_detail += "</details>"
+        rows.append(
+            f'<tr id="{anchors[node["node_id"]]}"><td>{_text(node["name"])}<br><code>{_text(node["node_id"])}</code>{stage_detail}</td><td>{_text(node.get("operation_kind", node["event_type"]))}</td><td>{_text(format_duration_ms(node["duration_ms"], unit="ms", precision=3))}</td><td>{bar}</td><td>{parent_link}</td></tr>'
+        )
+    return (
+        '<section id="timeline"><h2>Execution timeline</h2><div class="table-wrap"><table><caption>Recorded span timing and parent structure. Bars show relative timestamps, not predicted savings.</caption><thead><tr><th scope="col">Span</th><th scope="col">Operation</th><th scope="col">Duration</th><th scope="col">Relative timing</th><th scope="col">Parent</th></tr></thead><tbody>'
+        + "".join(rows)
+        + "</tbody></table></div>"
+        + ("<p>No execution spans.</p>" if not rows else "")
+        + "</section>"
+    )
+
+
+def _finding(finding: dict[str, Any], index: int, anchors: dict[str, str]) -> str:
+    savings = finding["savings"]
+    evidence = finding.get("evidence_level", "inferred")
+    result = f'<article class="prediction" id="finding-{index}"><span class="badge">{_text(evidence)} evidence</span><span class="badge">{_text(finding["confidence"])} confidence</span><h3>{_text(finding["title"])}</h3>'
+    result += f"<p>{_text(finding.get('metadata', {}).get('why', ''))}</p>"
+    if finding.get("ranking"):
+        ranking = finding["ranking"]
+        result += _definition(
+            [
+                ("Investigation priority", ranking["priority_rank"]),
+                ("Test readiness", ranking["status"].replace("_", " ")),
+                (
+                    "Why",
+                    "; ".join(reason.replace("_", " ") for reason in ranking["reasons"])
+                    or "Required inputs are complete; compare the declared ranking components.",
+                ),
+            ]
+        )
+        result += (
+            "<details><summary>Ranking components, input references and ordering</summary>"
+            + _json(
+                {
+                    key: ranking[key]
+                    for key in (
+                        "method",
+                        "order",
+                        "components",
+                        "required_inputs",
+                        "reasons",
+                        "invalid_inputs",
+                        "automatic_application_allowed",
+                    )
+                }
+            )
+            + "</details>"
+        )
+    result += _definition(
+        [
+            ("Finding ID", finding["finding_id"]),
+            (
+                "Estimated latency savings",
+                format_duration_ms(savings["estimated_latency_savings_ms"], unit="ms", precision=3),
+            ),
+            ("Estimated cost savings", format_cost_usd(savings.get("estimated_cost_savings_usd"))),
+            ("Proposed change", finding["rewrite"]["hint"]),
+            ("Validation", finding["validation"]["acceptance_criteria"]),
+        ]
+    )
+    links = [
+        f'<a href="#{anchors[span]}">{_text(span)}</a>' if span in anchors else _text(span)
+        for span in finding.get("affected_spans", [])
+    ]
+    result += "<p>Evidence spans: " + (", ".join(links) or "none") + "</p>"
+    if finding.get("observations", {}).get("investigation_id"):
+        result += (
+            "<details><summary>Semantic investigation and judge provenance</summary>"
+            + _json(finding["observations"])
+            + "</details>"
+        )
+    estimate = finding.get("estimate")
+    if estimate:
+        result += (
+            "<details><summary>Estimator, assumptions, and observed inputs</summary>"
+            + _json(estimate)
+            + "</details>"
+        )
+    else:
+        result += (
+            "<details><summary>Assumptions and formula</summary>"
+            + _json(
+                {"assumptions": finding.get("assumptions", []), "formula": savings.get("formula")}
+            )
+            + "</details>"
+        )
+    result += (
+        "<details><summary>Recorded finding evidence</summary>"
+        + _json(finding.get("evidence", []))
+        + "</details></article>"
+    )
+    return result
+
+
+def _comparison(replay: dict[str, Any]) -> str:
+    rows = []
+    for label, key in (
+        ("Run", "run_id"),
+        ("Elapsed runtime (ms)", "runtime_ms"),
+        ("Cost", "estimated_cost_usd"),
+        ("Token basis", "token_status"),
+        ("Quality score", "quality_score"),
+    ):
+        values = []
+        for side in ("baseline", "candidate"):
+            run = replay[side]
+            value = run.get(key)
+            if key == "estimated_cost_usd":
+                value = format_cost_usd(
+                    value, run.get("cost_status"), token_status=run.get("token_status")
+                )
+            values.append(_text("unavailable" if value is None else value))
+        rows.append([_text(label), *values])
+    if "decision_count_delta" in replay["deltas"]:
+        for label, key in (
+            ("Recorded model calls", "model_call_count"),
+            ("Recorded tool calls", "tool_call_count"),
+            ("Recorded decision spans", "decision_count"),
+            ("Recorded error spans", "error_span_count"),
+        ):
+            rows.append(
+                [
+                    _text(label),
+                    *[_text(replay[side].get(key)) for side in ("baseline", "candidate")],
+                ]
+            )
+    result = _table(
+        ["Recorded metric", "Baseline", "Candidate"],
+        rows,
+        caption="Observed trace comparison; costs retain their recorded pricing and token basis.",
+    )
+    deltas = replay["deltas"]
+    result += "<h3>Observed deltas</h3>" + _table(
+        ["Metric", "Candidate minus baseline"],
+        [
+            [_text(label), _text("unavailable" if deltas.get(key) is None else deltas[key])]
+            for label, key in (
+                ("Runtime (ms)", "runtime_ms_delta"),
+                ("Cost (USD)", "cost_usd_delta"),
+                ("Input tokens", "input_tokens_delta"),
+                ("Output tokens", "output_tokens_delta"),
+            )
+        ],
+        caption="Negative deltas mean lower recorded values.",
+    )
+    result += (
+        "<p>Configured gates: <strong>"
+        + ("passed" if replay["gates"]["passed"] else "failed")
+        + "</strong>.</p>"
+    )
+    result += _table(
+        ["Gate", "Result", "Detail"],
+        [
+            [
+                _text(gate["name"]),
+                "indeterminate"
+                if gate.get("indeterminate")
+                else ("pass" if gate["passed"] else "fail"),
+                _text(gate["detail"]),
+            ]
+            for gate in replay["gates"]["results"]
+        ],
+        caption="Only configured checks determine this gate result.",
+    )
+    result += (
+        "<details><summary>Comparison configuration and provenance</summary>"
+        + _json({"gates": replay["gates"], "deltas": deltas})
+        + "</details>"
+    )
+    result += (
+        "<details><summary>Supplied quality evidence</summary><p>Quality evidence may contain raw task inputs and outputs; review it before sharing.</p>"
+        + (
+            _json(replay["quality"])
+            if replay.get("quality") is not None
+            else "<p>No quality checks were supplied.</p>"
+        )
+        + "</details>"
+    )
+    return result