execweave 0.6.0__py3-none-any.whl

execweave/overhead_benchmark.py

@@ -0,0 +1,440 @@
+from __future__ import annotations
+
+import argparse
+import html
+import importlib.metadata
+import json
+import math
+import platform
+import shutil
+import statistics
+import subprocess
+import sys
+import tempfile
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import psutil
+
+from . import __version__
+
+_SAMPLE_INTERVAL_SECONDS = 0.005
+_WORKLOAD_ID = "agent_like_files_and_subprocesses_v1"
+_WORKLOAD_CODE = """
+from pathlib import Path
+import hashlib
+import subprocess
+import sys
+
+root = Path("payload")
+root.mkdir(exist_ok=True)
+payload = (b"execweave-reference-workload-" * 2048)[:32768]
+for index in range(256):
+    path = root / f"file-{index % 16}.bin"
+    path.write_bytes(payload)
+    hashlib.sha256(path.read_bytes()).digest()
+for path in root.iterdir():
+    path.unlink()
+root.rmdir()
+for _ in range(6):
+    subprocess.run(
+        [sys.executable, "-c", "sum(i*i for i in range(20000))"],
+        check=True,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+""".strip()
+
+
+def _workload_command() -> list[str]:
+    return [sys.executable, "-c", _WORKLOAD_CODE]
+
+
+def _tree_rss_bytes(pid: int) -> int:
+    try:
+        root = psutil.Process(pid)
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        return 0
+    processes = [root]
+    try:
+        processes.extend(root.children(recursive=True))
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        pass
+    rss = 0
+    for process in processes:
+        try:
+            rss += process.memory_info().rss
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            continue
+    return rss
+
+
+def _directory_size_bytes(path: Path) -> int:
+    total = 0
+    if not path.exists():
+        return 0
+    for candidate in path.rglob("*"):
+        try:
+            if candidate.is_file():
+                total += candidate.stat().st_size
+        except OSError:
+            continue
+    return total
+
+
+def _measure_command(command: list[str], *, cwd: Path) -> dict[str, float | int]:
+    start = time.perf_counter()
+    process = subprocess.Popen(
+        command,
+        cwd=cwd,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    peak_rss = 0
+    while True:
+        peak_rss = max(peak_rss, _tree_rss_bytes(process.pid))
+        return_code = process.poll()
+        if return_code is not None:
+            break
+        time.sleep(_SAMPLE_INTERVAL_SECONDS)
+    elapsed = time.perf_counter() - start
+    if return_code != 0:
+        raise RuntimeError(f"benchmark command failed with exit code {return_code}")
+    return {
+        "wall_seconds": elapsed,
+        "peak_tree_rss_bytes": peak_rss,
+        "artifact_bytes": _directory_size_bytes(cwd),
+    }
+
+
+def _instrumented_command(backend: str, *, cwd: Path, output: Path) -> list[str]:
+    return [
+        sys.executable,
+        "-m",
+        "execweave",
+        "run",
+        "--backend",
+        backend,
+        "--watch-root",
+        str(cwd),
+        "--interval",
+        "0.05",
+        "--no-network",
+        "--output",
+        str(output),
+        "--",
+        *_workload_command(),
+    ]
+
+
+def _run_one(profile: str, *, root: Path, index: str) -> dict[str, float | int]:
+    run_dir = root / f"{profile}-{index}"
+    run_dir.mkdir(parents=True, exist_ok=True)
+    if profile == "off":
+        measurement = _measure_command(_workload_command(), cwd=run_dir)
+    else:
+        output = run_dir / "events.jsonl"
+        measurement = _measure_command(
+            _instrumented_command(profile, cwd=run_dir, output=output),
+            cwd=run_dir,
+        )
+    measurement["artifact_bytes"] = _directory_size_bytes(run_dir)
+    return measurement
+
+
+def _median(values: list[float]) -> float:
+    return float(statistics.median(values))
+
+
+def _percentile(values: list[float], fraction: float) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    index = max(0, min(len(ordered) - 1, math.ceil(len(ordered) * fraction) - 1))
+    return float(ordered[index])
+
+
+def _summarize(
+    name: str,
+    backend: str,
+    measurements: list[dict[str, float | int]],
+    *,
+    baseline: dict[str, Any] | None,
+) -> dict[str, Any]:
+    walls = [float(item["wall_seconds"]) for item in measurements]
+    rss = [float(item["peak_tree_rss_bytes"]) for item in measurements]
+    artifacts = [float(item["artifact_bytes"]) for item in measurements]
+    wall_median_ms = _median(walls) * 1000.0
+    rss_median_mb = _median(rss) / (1024.0 * 1024.0)
+    artifact_median_kb = _median(artifacts) / 1024.0
+    if baseline is None:
+        overhead_percent = 0.0
+        rss_delta_mb = 0.0
+    else:
+        baseline_wall = float(baseline["wall_median_ms"])
+        baseline_rss = float(baseline["peak_tree_rss_median_mb"])
+        overhead_percent = (
+            ((wall_median_ms / baseline_wall) - 1.0) * 100.0 if baseline_wall else 0.0
+        )
+        rss_delta_mb = rss_median_mb - baseline_rss
+    return {
+        "name": name,
+        "backend": backend,
+        "samples": len(measurements),
+        "wall_median_ms": round(wall_median_ms, 3),
+        "wall_p95_ms": round(_percentile(walls, 0.95) * 1000.0, 3),
+        "runtime_overhead_percent": round(overhead_percent, 3),
+        "peak_tree_rss_median_mb": round(rss_median_mb, 3),
+        "peak_tree_rss_delta_mb": round(rss_delta_mb, 3),
+        "additional_peak_rss_mb": round(max(0.0, rss_delta_mb), 3),
+        "artifact_median_kb": round(artifact_median_kb, 3),
+    }
+
+
+def _cpu_model() -> str:
+    cpuinfo = Path("/proc/cpuinfo")
+    if cpuinfo.exists():
+        try:
+            for line in cpuinfo.read_text(encoding="utf-8", errors="replace").splitlines():
+                if line.lower().startswith("model name") and ":" in line:
+                    return line.split(":", 1)[1].strip()
+        except OSError:
+            pass
+    return platform.processor() or platform.machine() or "unknown"
+
+
+def _distribution_size_bytes() -> int | None:
+    try:
+        distribution = importlib.metadata.distribution("execweave")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+    total = 0
+    seen = False
+    for relative in distribution.files or []:
+        try:
+            candidate = Path(distribution.locate_file(relative))
+            if candidate.is_file():
+                total += candidate.stat().st_size
+                seen = True
+        except OSError:
+            continue
+    return total if seen else None
+
+
+def run_reference_benchmark(*, iterations: int = 7, strace: str = "auto") -> dict[str, Any]:
+    if iterations < 1:
+        raise ValueError("iterations must be >= 1")
+    if strace not in {"auto", "on", "off"}:
+        raise ValueError("strace must be auto, on, or off")
+    strace_available = platform.system() == "Linux" and shutil.which("strace") is not None
+    if strace == "on" and not strace_available:
+        raise RuntimeError("strace was requested but is unavailable")
+    backends = ["portable"]
+    if strace_available and strace != "off":
+        backends.append("strace")
+
+    with tempfile.TemporaryDirectory(prefix="execweave-reference-benchmark-") as temp:
+        root = Path(temp)
+        _run_one("off", root=root, index="warmup")
+        for backend in backends:
+            _run_one(backend, root=root, index="warmup")
+
+        baseline_measurements = [
+            _run_one("off", root=root, index=str(index)) for index in range(iterations)
+        ]
+        baseline = _summarize(
+            "ExecWeave OFF",
+            "off",
+            baseline_measurements,
+            baseline=None,
+        )
+        profiles = [baseline]
+        for backend in backends:
+            measurements = [
+                _run_one(backend, root=root, index=str(index)) for index in range(iterations)
+            ]
+            profiles.append(
+                _summarize(
+                    f"{backend.capitalize()} ON",
+                    backend,
+                    measurements,
+                    baseline=baseline,
+                )
+            )
+
+    distribution_bytes = _distribution_size_bytes()
+    return {
+        "schema_version": "0.1",
+        "generated_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "execweave_version": __version__,
+        "workload": {
+            "id": _WORKLOAD_ID,
+            "description": "fixed file read/write/hash operations plus short-lived Python subprocesses",
+        },
+        "iterations": iterations,
+        "environment": {
+            "os": platform.platform(),
+            "python": platform.python_version(),
+            "machine": platform.machine(),
+            "cpu_model": _cpu_model(),
+            "logical_cpus": psutil.cpu_count(logical=True),
+            "memory_total_mb": round(psutil.virtual_memory().total / (1024.0 * 1024.0), 1),
+        },
+        "package": {
+            "distribution_kb": (
+                round(distribution_bytes / 1024.0, 3) if distribution_bytes is not None else None
+            ),
+            "scope": "ExecWeave distribution files only; Python and dependency footprints excluded",
+        },
+        "profiles": profiles,
+        "interpretation": {
+            "x": "additional_peak_rss_mb",
+            "y": "runtime_overhead_percent",
+            "bubble": "artifact_median_kb",
+            "preferred_region": "lower-left",
+            "warning": "Reference microbenchmark only; rerun on the target host before making capacity claims.",
+        },
+    }
+
+
+def _nice_ceiling(value: float, minimum: float) -> float:
+    value = max(value, minimum)
+    magnitude = 10 ** math.floor(math.log10(value)) if value > 0 else 1
+    scaled = value / magnitude
+    if scaled <= 1:
+        step = 1
+    elif scaled <= 2:
+        step = 2
+    elif scaled <= 5:
+        step = 5
+    else:
+        step = 10
+    return step * magnitude
+
+
+def render_tradeoff_svg(report: dict[str, Any]) -> str:
+    profiles = [profile for profile in report.get("profiles", []) if isinstance(profile, dict)]
+    x_values = [max(0.0, float(profile.get("additional_peak_rss_mb", 0.0))) for profile in profiles]
+    y_values = [float(profile.get("runtime_overhead_percent", 0.0)) for profile in profiles]
+    x_max = _nice_ceiling(max(x_values, default=0.0) * 1.25, 8.0)
+    y_min = min(0.0, min(y_values, default=0.0) * 1.15)
+    y_max = _nice_ceiling(max(y_values, default=0.0) * 1.25, 10.0)
+    if y_max <= y_min:
+        y_max = y_min + 10.0
+
+    width, height = 980, 640
+    left, right, top, bottom = 110, 70, 125, 110
+    plot_w = width - left - right
+    plot_h = height - top - bottom
+
+    def sx(value: float) -> float:
+        return left + (max(0.0, value) / x_max) * plot_w
+
+    def sy(value: float) -> float:
+        return top + ((y_max - value) / (y_max - y_min)) * plot_h
+
+    colors = {"off": "#64748b", "portable": "#2563eb", "strace": "#7c3aed"}
+    env = report.get("environment") or {}
+    subtitle = f"{env.get('os', 'unknown OS')} · Python {env.get('python', '?')} · n={report.get('iterations', '?')}"
+    lines = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {width} {height}" role="img" aria-labelledby="title desc">',
+        '<title id="title">ExecWeave runtime overhead versus memory footprint</title>',
+        '<desc id="desc">Lower-left is better. Bubble area indicates median artifact size per reference run.</desc>',
+        '<rect width="100%" height="100%" rx="24" fill="#ffffff"/>',
+        '<text x="70" y="54" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="28" font-weight="700" fill="#0f172a">ExecWeave overhead trade-off</text>',
+        f'<text x="70" y="83" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="14" fill="#64748b">{html.escape(subtitle)}</text>',
+        '<text x="910" y="54" text-anchor="end" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="13" font-weight="600" fill="#16a34a">LOWER-LEFT IS BETTER ↙</text>',
+    ]
+
+    for index in range(6):
+        fraction = index / 5
+        x = left + fraction * plot_w
+        value = fraction * x_max
+        lines.append(f'<line x1="{x:.1f}" y1="{top}" x2="{x:.1f}" y2="{top + plot_h}" stroke="#e2e8f0" stroke-width="1"/>')
+        lines.append(f'<text x="{x:.1f}" y="{top + plot_h + 28}" text-anchor="middle" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="12" fill="#64748b">{value:.0f}</text>')
+    for index in range(6):
+        fraction = index / 5
+        y = top + fraction * plot_h
+        value = y_max - fraction * (y_max - y_min)
+        lines.append(f'<line x1="{left}" y1="{y:.1f}" x2="{left + plot_w}" y2="{y:.1f}" stroke="#e2e8f0" stroke-width="1"/>')
+        lines.append(f'<text x="{left - 18}" y="{y + 4:.1f}" text-anchor="end" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="12" fill="#64748b">{value:.0f}</text>')
+
+    lines.extend(
+        [
+            f'<line x1="{left}" y1="{top + plot_h}" x2="{left + plot_w}" y2="{top + plot_h}" stroke="#334155" stroke-width="1.5"/>',
+            f'<line x1="{left}" y1="{top}" x2="{left}" y2="{top + plot_h}" stroke="#334155" stroke-width="1.5"/>',
+            f'<text x="{left + plot_w / 2:.1f}" y="{height - 45}" text-anchor="middle" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="15" font-weight="600" fill="#334155">Additional peak process-tree RSS (MB) → higher</text>',
+            f'<text x="32" y="{top + plot_h / 2:.1f}" transform="rotate(-90 32 {top + plot_h / 2:.1f})" text-anchor="middle" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="15" font-weight="600" fill="#334155">Runtime overhead (%) → higher</text>',
+        ]
+    )
+
+    for profile in profiles:
+        backend = str(profile.get("backend", "unknown"))
+        x_value = max(0.0, float(profile.get("additional_peak_rss_mb", 0.0)))
+        y_value = float(profile.get("runtime_overhead_percent", 0.0))
+        artifact = max(0.0, float(profile.get("artifact_median_kb", 0.0)))
+        radius = 8.0 if backend == "off" else min(28.0, 10.0 + math.sqrt(artifact) * 0.9)
+        x, y = sx(x_value), sy(y_value)
+        color = colors.get(backend, "#0f766e")
+        name = html.escape(str(profile.get("name", backend)))
+        detail = html.escape(f"+{x_value:.1f} MB RSS · {y_value:+.1f}% time · {artifact:.1f} KB/run")
+        label_x = x + 16
+        label_y = y - radius - 8
+        if backend == "off":
+            label_y = y - 18
+        lines.append(f'<circle cx="{x:.1f}" cy="{y:.1f}" r="{radius:.1f}" fill="{color}" fill-opacity="0.88" stroke="#ffffff" stroke-width="3"/>')
+        lines.append(f'<text x="{label_x:.1f}" y="{label_y:.1f}" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="14" font-weight="700" fill="#0f172a">{name}</text>')
+        lines.append(f'<text x="{label_x:.1f}" y="{label_y + 19:.1f}" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="11" fill="#64748b">{detail}</text>')
+
+    package = report.get("package") or {}
+    package_kb = package.get("distribution_kb")
+    package_text = f"Package footprint: {package_kb:.1f} KB (ExecWeave files only)" if isinstance(package_kb, (int, float)) else "Package footprint unavailable"
+    lines.extend(
+        [
+            f'<text x="{left}" y="{height - 18}" font-family="system-ui,-apple-system,Segoe UI,sans-serif" font-size="11" fill="#94a3b8">Bubble area ≈ median residual artifact size per run · {html.escape(package_text)}</text>',
+            '</svg>',
+        ]
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _write_text(path: Path, content: str) -> Path:
+    destination = path.expanduser().resolve()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(content, encoding="utf-8")
+    return destination
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="execweave-overhead",
+        description="Measure ExecWeave runtime overhead and render a reproducible trade-off chart.",
+    )
+    parser.add_argument("--iterations", type=int, default=7)
+    parser.add_argument("--strace", choices=["auto", "on", "off"], default="auto")
+    parser.add_argument("--output-json", type=Path, default=None)
+    parser.add_argument("--output-svg", type=Path, default=None)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        report = run_reference_benchmark(iterations=args.iterations, strace=args.strace)
+    except (RuntimeError, ValueError) as exc:
+        parser.error(str(exc))
+    rendered = json.dumps(report, indent=2, sort_keys=True)
+    print(rendered)
+    print("EXECWEAVE_BENCHMARK_RESULT=" + json.dumps(report, sort_keys=True, separators=(",", ":")))
+    if args.output_json is not None:
+        _write_text(args.output_json, rendered + "\n")
+    if args.output_svg is not None:
+        _write_text(args.output_svg, render_tradeoff_svg(report))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

execweave/provider_record.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import os
+import webbrowser
+from dataclasses import dataclass
+from pathlib import Path
+from uuid import uuid4
+
+from .backends import BackendName
+from .correlation import CorrelationResult, correlate_tool_process
+from .graph import build_execution_graph, write_execution_graph
+from .semantic import SemanticMergeResult, merge_semantic_sidecar
+from .viewer import write_graph_html
+from .workflow import RecordResult, record_to_viewer
+
+_SEMANTIC_ENV = "EXECWEAVE_SEMANTIC_SIDECAR"
+
+
+@dataclass(frozen=True)
+class ProviderRecordResult:
+    runtime: RecordResult
+    semantic_status: str
+    semantic_sidecar: Path
+    merged_event_stream: Path | None
+    semantic_graph: Path | None
+    semantic_viewer: Path | None
+    semantic_merge: SemanticMergeResult | None
+    correlation_status: str
+    correlated_event_stream: Path | None
+    correlated_graph: Path | None
+    correlated_viewer: Path | None
+    correlation: CorrelationResult | None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "runtime": self.runtime.to_dict(),
+            "semantic_status": self.semantic_status,
+            "semantic_sidecar": str(self.semantic_sidecar),
+            "merged_event_stream": (
+                str(self.merged_event_stream) if self.merged_event_stream is not None else None
+            ),
+            "semantic_graph": str(self.semantic_graph) if self.semantic_graph is not None else None,
+            "semantic_viewer": str(self.semantic_viewer) if self.semantic_viewer is not None else None,
+            "semantic_merge": (
+                self.semantic_merge.to_dict() if self.semantic_merge is not None else None
+            ),
+            "correlation_status": self.correlation_status,
+            "correlated_event_stream": (
+                str(self.correlated_event_stream)
+                if self.correlated_event_stream is not None
+                else None
+            ),
+            "correlated_graph": (
+                str(self.correlated_graph) if self.correlated_graph is not None else None
+            ),
+            "correlated_viewer": (
+                str(self.correlated_viewer) if self.correlated_viewer is not None else None
+            ),
+            "correlation": self.correlation.to_dict() if self.correlation is not None else None,
+        }
+
+
+def _artifact_paths(run_dir: Path) -> dict[str, Path]:
+    return {
+        "semantic_sidecar": run_dir / "semantic.jsonl",
+        "merged_event_stream": run_dir / "events.semantic.jsonl",
+        "semantic_graph": run_dir / "graph.semantic.json",
+        "semantic_viewer": run_dir / "viewer.semantic.html",
+        "correlated_event_stream": run_dir / "events.correlated.jsonl",
+        "correlated_graph": run_dir / "graph.correlated.json",
+        "correlated_viewer": run_dir / "viewer.correlated.html",
+    }
+
+
+def _preflight(paths: list[Path], *, provider_name: str) -> None:
+    conflicts = [path for path in paths if path.exists() and path.stat().st_size > 0]
+    if conflicts:
+        rendered = ", ".join(str(path) for path in conflicts)
+        raise FileExistsError(
+            f"ExecWeave {provider_name} semantic artifacts already exist: {rendered}"
+        )
+
+
+def record_provider_to_viewer(
+    command: list[str],
+    *,
+    provider_name: str,
+    watch_root: str | Path,
+    output_dir: str | Path | None = None,
+    backend: BackendName = "auto",
+    poll_interval: float = 0.10,
+    collect_filesystem: bool = True,
+    collect_network: bool = True,
+    keep_raw_trace: bool = False,
+    correlation_window_ms: int = 3000,
+    open_browser: bool = False,
+) -> ProviderRecordResult:
+    """Record runtime + provider semantic evidence into layered local artifacts.
+
+    Provider-specific hooks must already be configured to write to the inherited
+    ``EXECWEAVE_SEMANTIC_SIDECAR`` path. This core never edits provider settings.
+    Raw runtime and semantic evidence remain separate; correlation always derives a
+    new stream and stays explicitly inferred/non-causal.
+    """
+    if not command:
+        raise ValueError("command must not be empty")
+    if not provider_name.strip():
+        raise ValueError("provider_name must not be empty")
+    if correlation_window_ms <= 0:
+        raise ValueError("correlation_window_ms must be greater than zero")
+
+    root = Path(watch_root).expanduser().resolve()
+    run_dir = (
+        Path(output_dir).expanduser().resolve()
+        if output_dir is not None
+        else root / ".execweave" / "runs" / uuid4().hex
+    )
+    run_dir.mkdir(parents=True, exist_ok=True)
+    paths = _artifact_paths(run_dir)
+    _preflight(list(paths.values()), provider_name=provider_name)
+
+    semantic_sidecar = paths["semantic_sidecar"]
+    previous = os.environ.get(_SEMANTIC_ENV)
+    os.environ[_SEMANTIC_ENV] = str(semantic_sidecar)
+    try:
+        runtime = record_to_viewer(
+            command,
+            watch_root=root,
+            output_dir=run_dir,
+            backend=backend,
+            poll_interval=poll_interval,
+            collect_filesystem=collect_filesystem,
+            collect_network=collect_network,
+            keep_raw_trace=keep_raw_trace,
+            open_browser=False,
+        )
+    finally:
+        if previous is None:
+            os.environ.pop(_SEMANTIC_ENV, None)
+        else:
+            os.environ[_SEMANTIC_ENV] = previous
+
+    if not semantic_sidecar.exists() or semantic_sidecar.stat().st_size == 0:
+        if open_browser:
+            webbrowser.open(runtime.viewer.resolve().as_uri())
+        return ProviderRecordResult(
+            runtime=runtime,
+            semantic_status="no_events",
+            semantic_sidecar=semantic_sidecar.resolve(),
+            merged_event_stream=None,
+            semantic_graph=None,
+            semantic_viewer=None,
+            semantic_merge=None,
+            correlation_status="not_run_no_semantic_events",
+            correlated_event_stream=None,
+            correlated_graph=None,
+            correlated_viewer=None,
+            correlation=None,
+        )
+
+    merged_event_stream = paths["merged_event_stream"]
+    semantic_graph = paths["semantic_graph"]
+    semantic_viewer = paths["semantic_viewer"]
+    correlated_event_stream = paths["correlated_event_stream"]
+    correlated_graph = paths["correlated_graph"]
+    correlated_viewer = paths["correlated_viewer"]
+
+    merge_result = merge_semantic_sidecar(
+        runtime.event_stream,
+        semantic_sidecar,
+        merged_event_stream,
+    )
+    execution_graph = build_execution_graph(merged_event_stream)
+    write_execution_graph(execution_graph, semantic_graph)
+    write_graph_html(execution_graph.to_dict(), semantic_viewer, open_browser=False)
+
+    correlation_result = correlate_tool_process(
+        merged_event_stream,
+        correlated_event_stream,
+        max_window_ms=correlation_window_ms,
+    )
+    correlated_execution_graph = build_execution_graph(correlated_event_stream)
+    correlation_metadata = {"correlation": correlation_result.to_dict()}
+    write_execution_graph(
+        correlated_execution_graph,
+        correlated_graph,
+        metadata=correlation_metadata,
+    )
+    correlated_graph_payload = correlated_execution_graph.to_dict()
+    correlated_graph_payload["metadata"] = correlation_metadata
+    write_graph_html(
+        correlated_graph_payload,
+        correlated_viewer,
+        open_browser=open_browser,
+    )
+
+    correlation_status = (
+        "correlated"
+        if correlation_result.correlated_tool_calls > 0
+        else "completed_no_matches"
+    )
+    return ProviderRecordResult(
+        runtime=runtime,
+        semantic_status="merged",
+        semantic_sidecar=semantic_sidecar.resolve(),
+        merged_event_stream=merged_event_stream.resolve(),
+        semantic_graph=semantic_graph.resolve(),
+        semantic_viewer=semantic_viewer.resolve(),
+        semantic_merge=merge_result,
+        correlation_status=correlation_status,
+        correlated_event_stream=correlated_event_stream.resolve(),
+        correlated_graph=correlated_graph.resolve(),
+        correlated_viewer=correlated_viewer.resolve(),
+        correlation=correlation_result,
+    )