cseq 0.0.1__py3-none-any.whl

cseq/static_store.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Iterable, Iterator
+
+from .model import CompactFunctionRecord, FunctionRecord, SourceRange
+
+
+class StaticSymbolStore:
+    """Disk-backed function metadata store for very large projects.
+
+    The store preserves the FunctionRecord-facing contract while allowing parse
+    artifacts to release their per-TU function tables after ingestion.
+    """
+
+    SCHEMA_VERSION = 7
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.connection = sqlite3.connect(self.path)
+        # The Static Symbol Store is a reproducible analysis cache, not the
+        # authoritative source. Keep writes fast on million-function projects.
+        # Reuse only requires that we avoid EXCLUSIVE locking; journaling can be
+        # disabled because an interrupted/corrupt store is safely rebuilt from
+        # source fingerprints on the next run.
+        self.connection.execute("PRAGMA busy_timeout=5000")
+        self.connection.execute("PRAGMA journal_mode=OFF")
+        self.connection.execute("PRAGMA synchronous=OFF")
+        self.connection.execute("PRAGMA temp_store=MEMORY")
+        self.connection.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS meta(
+              key TEXT PRIMARY KEY,
+              value TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS functions(
+              qid TEXT NOT NULL,
+              name TEXT NOT NULL,
+              source_path TEXT NOT NULL,
+              start_line INTEGER,
+              start_column INTEGER,
+              end_line INTEGER,
+              end_column INTEGER,
+              storage_class TEXT,
+              type_qualifier TEXT,
+              parameters_json TEXT NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS translation_units(
+              source_path TEXT PRIMARY KEY,
+              fingerprint TEXT NOT NULL,
+              function_count INTEGER NOT NULL,
+              artifact_json TEXT NOT NULL DEFAULT '{}'
+            ) WITHOUT ROWID;
+            """
+        )
+        row = self.connection.execute(
+            "SELECT value FROM meta WHERE key='schema_version'"
+        ).fetchone()
+        old_schema = int(row[0]) if row and str(row[0]).isdigit() else None
+        columns = {r[1] for r in self.connection.execute("PRAGMA table_info(translation_units)")}
+        if "artifact_json" not in columns:
+            self.connection.execute(
+                "ALTER TABLE translation_units ADD COLUMN artifact_json TEXT NOT NULL DEFAULT '{}'"
+            )
+        self.connection.execute("DROP INDEX IF EXISTS idx_functions_source")
+        if old_schema != self.SCHEMA_VERSION:
+            # Schema v7 changes the function table from a random TEXT-primary-key
+            # B-tree into an append-oriented rowid table. The store is a rebuildable
+            # cache, so recreate it rather than paying a migration cost.
+            self.connection.execute("DROP TABLE IF EXISTS functions")
+            self.connection.execute(
+                """CREATE TABLE functions(
+                     qid TEXT NOT NULL, name TEXT NOT NULL, source_path TEXT NOT NULL,
+                     start_line INTEGER, start_column INTEGER, end_line INTEGER, end_column INTEGER,
+                     storage_class TEXT, type_qualifier TEXT, parameters_json TEXT NOT NULL
+                   )"""
+            )
+            self.connection.execute("DELETE FROM translation_units")
+            self.connection.execute("DROP INDEX IF EXISTS idx_functions_name")
+        # A permanent name index is deliberately avoided. Project-wide call
+        # resolution asks only for names that actually appear at CallSites.
+        self.connection.execute(
+            "INSERT OR REPLACE INTO meta(key,value) VALUES('schema_version',?)",
+            (str(self.SCHEMA_VERSION),),
+        )
+        self.connection.commit()
+
+    def reset(self) -> None:
+        self.connection.execute("DELETE FROM functions")
+        self.connection.execute("DELETE FROM translation_units")
+        self.connection.execute("DROP INDEX IF EXISTS idx_functions_name")
+        self.connection.commit()
+
+    def ensure_project(self, root: str | Path) -> bool:
+        """Bind the store to one project root.
+
+        Returns True when an existing compatible project binding is reused.
+        A different root invalidates relative-path keyed contents safely.
+        """
+        root_text = str(Path(root).resolve())
+        row = self.connection.execute(
+            "SELECT value FROM meta WHERE key='project_root'"
+        ).fetchone()
+        reused = bool(row and row[0] == root_text)
+        if row and row[0] != root_text:
+            self.reset()
+        self.connection.execute(
+            "INSERT OR REPLACE INTO meta(key,value) VALUES('project_root',?)",
+            (root_text,),
+        )
+        self.connection.commit()
+        return reused
+
+    def has_translation_unit(self, source_path: str, fingerprint: str) -> bool:
+        row = self.connection.execute(
+            "SELECT fingerprint FROM translation_units WHERE source_path=?",
+            (source_path,),
+        ).fetchone()
+        return bool(row and row[0] == fingerprint)
+
+    def translation_unit_state_raw(self) -> dict[str, tuple[str, str]]:
+        """Return the small TU reuse index without materializing functions."""
+        return {
+            source_path: (fingerprint, artifact_json)
+            for source_path, fingerprint, artifact_json in self.connection.execute(
+                "SELECT source_path,fingerprint,artifact_json FROM translation_units"
+            )
+        }
+
+    def replace_translation_unit(
+        self,
+        source_path: str,
+        fingerprint: str,
+        functions: Iterable[FunctionRecord | CompactFunctionRecord],
+        artifact_payload: dict | None = None,
+    ) -> int:
+        rows = [self._row(fn) for fn in functions]
+        old = self.connection.execute(
+            "SELECT 1 FROM translation_units WHERE source_path=?", (source_path,)
+        ).fetchone()
+        if old:
+            # Changed/removed TUs are rare compared with cold insertion. Avoid a
+            # permanent source_path secondary index and scan only on mutation.
+            self.connection.execute("DELETE FROM functions WHERE source_path=?", (source_path,))
+        if rows:
+            self.connection.executemany(
+                """
+                INSERT INTO functions(
+                  qid,name,source_path,start_line,start_column,end_line,end_column,
+                  storage_class,type_qualifier,parameters_json
+                ) VALUES(?,?,?,?,?,?,?,?,?,?)
+                """,
+                rows,
+            )
+        artifact_json = json.dumps(artifact_payload or {}, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        self.connection.execute(
+            """INSERT OR REPLACE INTO translation_units(source_path,fingerprint,function_count,artifact_json)
+               VALUES(?,?,?,?)""",
+            (source_path, fingerprint, len(rows), artifact_json),
+        )
+        return len(rows)
+
+    def remove_missing_translation_units(self, current_source_paths: set[str]) -> int:
+        rows = [r[0] for r in self.connection.execute("SELECT source_path FROM translation_units")]
+        stale = [path for path in rows if path not in current_source_paths]
+        for path in stale:
+            self.connection.execute("DELETE FROM functions WHERE source_path=?", (path,))
+            self.connection.execute("DELETE FROM translation_units WHERE source_path=?", (path,))
+        return len(stale)
+
+    def translation_unit_count(self) -> int:
+        return int(self.connection.execute("SELECT COUNT(*) FROM translation_units").fetchone()[0])
+
+    @staticmethod
+    def _row(fn: FunctionRecord | CompactFunctionRecord):
+        r = fn.source_range
+        return (
+            fn.qualified_id,
+            fn.name,
+            fn.source_path,
+            r.start_line,
+            r.start_column,
+            r.end_line,
+            r.end_column,
+            fn.storage_class,
+            fn.type_qualifier,
+            json.dumps(list(fn.parameters), ensure_ascii=False, separators=(",", ":")),
+        )
+
+    def add_functions(self, functions: Iterable[FunctionRecord | CompactFunctionRecord]) -> int:
+        rows = [self._row(fn) for fn in functions]
+        if not rows:
+            return 0
+        self.connection.executemany(
+            """
+            INSERT INTO functions(
+              qid,name,source_path,start_line,start_column,end_line,end_column,
+              storage_class,type_qualifier,parameters_json
+            ) VALUES(?,?,?,?,?,?,?,?,?,?)
+            """,
+            rows,
+        )
+        return len(rows)
+
+    def flush(self) -> None:
+        """Commit current row batches without forcing secondary-index creation."""
+        self.connection.commit()
+
+    def commit(self) -> None:
+        self.connection.commit()
+
+    def count(self) -> int:
+        return int(self.connection.execute("SELECT COUNT(*) FROM functions").fetchone()[0])
+
+    @staticmethod
+    def _record(row) -> FunctionRecord:
+        return FunctionRecord(
+            name=row[1],
+            qualified_id=row[0],
+            source_path=row[2],
+            source_range=SourceRange(row[3], row[4], row[5], row[6]),
+            storage_class=row[7],
+            type_qualifier=row[8],
+            parameters=tuple(json.loads(row[9]) if row[9] else ()),
+        )
+
+    def iter_functions(self, fetch_size: int = 4096) -> Iterator[FunctionRecord]:
+        cur = self.connection.execute(
+            """SELECT qid,name,source_path,start_line,start_column,end_line,end_column,
+                      storage_class,type_qualifier,parameters_json
+               FROM functions ORDER BY source_path,start_line,start_column"""
+        )
+        while True:
+            rows = cur.fetchmany(fetch_size)
+            if not rows:
+                break
+            for row in rows:
+                yield self._record(row)
+
+    def iter_named(self, names: set[str]) -> Iterator[FunctionRecord]:
+        if not names:
+            return
+        ordered = sorted(names)
+        # No persistent name index and no TEMP-table writes: each chunk performs
+        # one sequential scan of the disk-backed store. Most real resolution
+        # queries fit in a single chunk because they contain only names observed
+        # at reachable CallSites.
+        for start in range(0, len(ordered), 800):
+            chunk = ordered[start:start + 800]
+            placeholders = ",".join("?" for _ in chunk)
+            cur = self.connection.execute(
+                f"""SELECT qid,name,source_path,start_line,start_column,end_line,end_column,
+                           storage_class,type_qualifier,parameters_json
+                    FROM functions WHERE name IN ({placeholders})""",
+                chunk,
+            )
+            for row in cur:
+                yield self._record(row)
+
+    def iter_ids(self, qids: set[str]) -> Iterator[FunctionRecord]:
+        if not qids:
+            return
+        ordered = sorted(qids)
+        for start in range(0, len(ordered), 400):
+            chunk = ordered[start:start + 400]
+            placeholders = ",".join("?" for _ in chunk)
+            cur = self.connection.execute(
+                f"""SELECT qid,name,source_path,start_line,start_column,end_line,end_column,
+                           storage_class,type_qualifier,parameters_json
+                    FROM functions WHERE qid IN ({placeholders})""",
+                chunk,
+            )
+            for row in cur:
+                yield self._record(row)
+
+    def close(self) -> None:
+        self.connection.close()

cseq/trace_analysis.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from collections import defaultdict, deque
+
+from .model import CallTargetKind, ProjectIndex
+from .runtime import RuntimeEvent
+
+
+class RuntimeRelationType(str, Enum):
+    CORRELATED_EXACT = "CORRELATED_EXACT"
+    CORRELATED_POSSIBLE = "CORRELATED_POSSIBLE"
+    TEMPORAL_ONLY = "TEMPORAL_ONLY"
+    CONCURRENT_UNKNOWN = "CONCURRENT_UNKNOWN"
+    UNKNOWN_GAP = "UNKNOWN_GAP"
+
+
+@dataclass(frozen=True, slots=True)
+class CorrelationRelation:
+    left_event_index: int
+    right_event_index: int
+    relation_type: RuntimeRelationType
+    keys: tuple[str, ...]
+    values: tuple[str, ...]
+    score: float
+
+
+@dataclass(frozen=True, slots=True)
+class ClockAlignment:
+    source_domain: str
+    target_domain: str
+    scale: float
+    offset_seconds: float
+    anchor_count: int
+    max_abs_residual_seconds: float
+    confidence: str
+
+    def transform_seconds(self, source_seconds: float) -> float:
+        return self.scale * source_seconds + self.offset_seconds
+
+
+class ReconstructionState(str, Enum):
+    EXACT_PATH = "EXACT_PATH"
+    AMBIGUOUS_PATH = "AMBIGUOUS_PATH"
+    UNKNOWN_GAP = "UNKNOWN_GAP"
+
+
+@dataclass(frozen=True, slots=True)
+class ReconstructedPath:
+    start_function: str
+    end_function: str
+    state: ReconstructionState
+    paths: tuple[tuple[str, ...], ...]
+
+
+def discover_correlations(
+    events: list[RuntimeEvent],
+    *,
+    exact_min_repetitions: int = 3,
+) -> list[CorrelationRelation]:
+    """Find conservative payload correlations and optionally promote stable ones.
+
+    A relation is promoted to CORRELATED_EXACT only when the *same field* links
+    the same marker pair across at least ``exact_min_repetitions`` distinct values,
+    and each of those values occurs in exactly two events. A single matching value
+    or time proximity is never enough. Set ``exact_min_repetitions <= 0`` to
+    disable automatic exact promotion.
+    """
+    occurrence: dict[tuple[str, str], list[int]] = defaultdict(list)
+    for e in events:
+        for key, value in e.payload:
+            occurrence[(key, value)].append(e.event_index)
+
+    by_index = {e.event_index: e for e in events}
+    pair_fields: dict[tuple[int, int], list[tuple[str, str, float]]] = defaultdict(list)
+    for (key, value), indexes in occurrence.items():
+        # Very common values are weak and create too many false edges.
+        if len(indexes) < 2 or len(indexes) > 8:
+            continue
+        uniqueness = 1.0 / len(indexes)
+        for i, left in enumerate(indexes):
+            for right in indexes[i + 1:]:
+                a, b = by_index[left], by_index[right]
+                # Same marker repeated is useful for repetition, not transaction linking.
+                if a.marker_id == b.marker_id:
+                    continue
+                pair_fields[(left, right)].append((key, value, uniqueness))
+
+    stable_exact: set[tuple[str, tuple[str, str]]] = set()
+    if exact_min_repetitions > 0:
+        # key + marker-pair -> distinct values that uniquely link exactly two events
+        stable_values: dict[tuple[str, tuple[str, str]], set[str]] = defaultdict(set)
+        for (key, value), indexes in occurrence.items():
+            if len(indexes) != 2:
+                continue
+            a, b = by_index[indexes[0]], by_index[indexes[1]]
+            if a.marker_id == b.marker_id:
+                continue
+            marker_pair = tuple(sorted((a.marker_id, b.marker_id)))
+            stable_values[(key, marker_pair)].add(value)
+        stable_exact = {
+            group for group, values in stable_values.items()
+            if len(values) >= exact_min_repetitions
+        }
+
+    out: list[CorrelationRelation] = []
+    for (left, right), fields in sorted(pair_fields.items()):
+        a, b = by_index[left], by_index[right]
+        keys = tuple(x[0] for x in fields)
+        values = tuple(x[1] for x in fields)
+        score = sum(x[2] for x in fields)
+        if a.cpu_hint and b.cpu_hint and a.cpu_hint != b.cpu_hint:
+            score += 0.25
+        if a.task_hint and b.task_hint and a.task_hint != b.task_hint:
+            score += 0.10
+        marker_pair = tuple(sorted((a.marker_id, b.marker_id)))
+        exact_keys = [key for key, _value, _u in fields if (key, marker_pair) in stable_exact]
+        relation_type = (
+            RuntimeRelationType.CORRELATED_EXACT
+            if exact_keys
+            else RuntimeRelationType.CORRELATED_POSSIBLE
+        )
+        out.append(CorrelationRelation(
+            left_event_index=left,
+            right_event_index=right,
+            relation_type=relation_type,
+            keys=keys,
+            values=values,
+            score=score,
+        ))
+    return sorted(out, key=lambda r: (-r.score, r.left_event_index, r.right_event_index))
+
+
+def fit_clock_alignments(
+    events: list[RuntimeEvent],
+    relations: list[CorrelationRelation],
+    *,
+    min_anchors: int = 3,
+) -> list[ClockAlignment]:
+    """Fit affine clock mappings using CORRELATED_EXACT anchors only.
+
+    Possible correlations are deliberately excluded to avoid circularly turning a
+    weak payload/time coincidence into stronger temporal evidence.
+    """
+    by_index = {e.event_index: e for e in events}
+    pairs: dict[tuple[str, str], list[tuple[float, float]]] = defaultdict(list)
+    for rel in relations:
+        if rel.relation_type != RuntimeRelationType.CORRELATED_EXACT:
+            continue
+        left, right = by_index.get(rel.left_event_index), by_index.get(rel.right_event_index)
+        if left is None or right is None or left.timestamp is None or right.timestamp is None:
+            continue
+        ld = left.clock_domain or left.cpu_hint or "default"
+        rd = right.clock_domain or right.cpu_hint or "default"
+        if ld == rd:
+            continue
+        pairs[(ld, rd)].append((_datetime_seconds(left.timestamp), _datetime_seconds(right.timestamp)))
+
+    out: list[ClockAlignment] = []
+    for (source, target), anchors in sorted(pairs.items()):
+        if len(anchors) < min_anchors:
+            continue
+        xs = [x for x, _ in anchors]
+        ys = [y for _, y in anchors]
+        xbar, ybar = sum(xs) / len(xs), sum(ys) / len(ys)
+        denom = sum((x - xbar) ** 2 for x in xs)
+        scale = 1.0 if denom == 0 else sum((x - xbar) * (y - ybar) for x, y in anchors) / denom
+        offset = ybar - scale * xbar
+        residuals = [abs((scale * x + offset) - y) for x, y in anchors]
+        max_residual = max(residuals, default=0.0)
+        if max_residual <= 0.001:
+            confidence = "HIGH"
+        elif max_residual <= 0.100:
+            confidence = "MEDIUM"
+        else:
+            confidence = "LOW"
+        out.append(ClockAlignment(
+            source_domain=source, target_domain=target, scale=scale,
+            offset_seconds=offset, anchor_count=len(anchors),
+            max_abs_residual_seconds=max_residual, confidence=confidence,
+        ))
+    return out
+
+
+def _datetime_seconds(value) -> float:
+    # Stable naive-clock numeric representation without local-timezone conversion.
+    return (
+        value.toordinal() * 86400.0
+        + value.hour * 3600.0
+        + value.minute * 60.0
+        + value.second
+        + value.microsecond / 1_000_000.0
+    )
+
+
+def reconstruct_static_paths(
+    index: ProjectIndex,
+    start_function: str,
+    end_function: str,
+    *,
+    max_paths: int = 8,
+    max_depth: int = 64,
+) -> ReconstructedPath:
+    graph: dict[str, set[str]] = defaultdict(set)
+    functions_by_id = {f.qualified_id: f for f in index.functions()}
+
+    for call in index.callsites:
+        targets: list[str] = []
+        if call.target_kind == CallTargetKind.INTERNAL_EXACT and call.target_function_id:
+            target = functions_by_id.get(call.target_function_id)
+            if target:
+                targets.append(target.name)
+        elif call.target_kind in {CallTargetKind.INTERNAL_POSSIBLE, CallTargetKind.INDIRECT_EXACT, CallTargetKind.INDIRECT_POSSIBLE}:
+            for tid in call.target_function_ids:
+                target = functions_by_id.get(tid)
+                if target:
+                    targets.append(target.name)
+        for target_name in targets:
+            graph[call.caller_name].add(target_name)
+
+    paths: list[tuple[str, ...]] = []
+    q: deque[tuple[str, tuple[str, ...]]] = deque([(start_function, (start_function,))])
+    shortest_len: int | None = None
+    while q and len(paths) < max_paths:
+        node, path = q.popleft()
+        if shortest_len is not None and len(path) > shortest_len:
+            continue
+        if len(path) > max_depth:
+            continue
+        if node == end_function:
+            paths.append(path)
+            shortest_len = len(path) if shortest_len is None else shortest_len
+            continue
+        for nxt in sorted(graph.get(node, ())):
+            if nxt in path:  # avoid recursion/SCC infinite expansion in the PoC path search
+                continue
+            q.append((nxt, path + (nxt,)))
+
+    if not paths:
+        state = ReconstructionState.UNKNOWN_GAP
+    elif len(paths) == 1:
+        state = ReconstructionState.EXACT_PATH
+    else:
+        state = ReconstructionState.AMBIGUOUS_PATH
+    return ReconstructedPath(start_function, end_function, state, tuple(paths))
+
+@dataclass(frozen=True, slots=True)
+class MarkerSuggestion:
+    function_name: str
+    distinguished_path_pairs: int
+    total_path_pairs: int
+    information_gain_score: float
+    reason: str
+
+
+def suggest_markers_for_paths(paths: tuple[tuple[str, ...], ...], *, count: int = 1) -> list[MarkerSuggestion]:
+    """Rank function nodes by how many ambiguous path pairs they distinguish.
+
+    This is the PoC core of marker suggestion. Entry/end nodes and nodes shared
+    by every path have zero discrimination and are excluded. Runtime cost and
+    existing-log reuse are intentionally separate scoring factors to add later.
+    """
+    if len(paths) < 2 or count <= 0:
+        return []
+    path_sets = [set(p) for p in paths]
+    endpoints = {paths[0][0], paths[0][-1]}
+    candidates = sorted(set().union(*path_sets) - endpoints)
+    total_pairs = len(paths) * (len(paths) - 1) // 2
+    ranked: list[MarkerSuggestion] = []
+    for fn in candidates:
+        distinguished = 0
+        for i in range(len(paths)):
+            for j in range(i + 1, len(paths)):
+                if (fn in path_sets[i]) != (fn in path_sets[j]):
+                    distinguished += 1
+        if distinguished == 0:
+            continue
+        score = distinguished / total_pairs if total_pairs else 0.0
+        ranked.append(MarkerSuggestion(
+            function_name=fn,
+            distinguished_path_pairs=distinguished,
+            total_path_pairs=total_pairs,
+            information_gain_score=score,
+            reason=f"present on a subset of ambiguous paths; distinguishes {distinguished}/{total_pairs} path pairs",
+        ))
+    ranked.sort(key=lambda x: (-x.information_gain_score, x.function_name))
+    return ranked[:count]
+
+@dataclass(frozen=True, slots=True)
+class MarkerCandidateContext:
+    has_existing_log: bool = False
+    hotness: float = 0.0
+    source_stability: float = 1.0
+
+
+def score_marker_suggestions(
+    paths: tuple[tuple[str, ...], ...],
+    *,
+    count: int = 1,
+    contexts: dict[str, MarkerCandidateContext] | None = None,
+) -> list[MarkerSuggestion]:
+    """Rank ambiguous-path marker points with transparent multi-factor scoring.
+
+    Information gain remains the dominant factor. Existing-log reuse is a bonus;
+    hot-path and unstable-source locations are penalties. All factors are bounded
+    so a low-information point cannot outrank a clearly discriminating point only
+    because it already has a log call.
+    """
+    contexts = contexts or {}
+    base = suggest_markers_for_paths(paths, count=10_000)
+    rescored: list[MarkerSuggestion] = []
+    for item in base:
+        ctx = contexts.get(item.function_name, MarkerCandidateContext())
+        hotness = min(max(ctx.hotness, 0.0), 1.0)
+        stability = min(max(ctx.source_stability, 0.0), 1.0)
+        reuse_bonus = 0.12 if ctx.has_existing_log else 0.0
+        hot_penalty = 0.20 * hotness
+        instability_penalty = 0.10 * (1.0 - stability)
+        total = max(0.0, item.information_gain_score + reuse_bonus - hot_penalty - instability_penalty)
+        reason = (
+            f"information_gain={item.information_gain_score:.3f}; "
+            f"existing_log_bonus={reuse_bonus:.3f}; "
+            f"hotness_penalty={hot_penalty:.3f}; "
+            f"source_instability_penalty={instability_penalty:.3f}; "
+            f"total={total:.3f}"
+        )
+        rescored.append(MarkerSuggestion(
+            function_name=item.function_name,
+            distinguished_path_pairs=item.distinguished_path_pairs,
+            total_path_pairs=item.total_path_pairs,
+            information_gain_score=total,
+            reason=reason,
+        ))
+    rescored.sort(key=lambda x: (-x.information_gain_score, x.function_name))
+    return rescored[:count]

cseq/trace_diff.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from collections import Counter
+from .runtime import TraceSession
+
+
+@dataclass(frozen=True, slots=True)
+class TraceDiffResult:
+    left_session: str
+    right_session: str
+    added_markers: tuple[tuple[str, int], ...]
+    missing_markers: tuple[tuple[str, int], ...]
+    changed_cpu: tuple[tuple[str, tuple[str, ...], tuple[str, ...]], ...]
+    changed_task: tuple[tuple[str, tuple[str, ...], tuple[str, ...]], ...]
+    order_changes: tuple[tuple[str, int, int], ...] = ()
+    timing_changes: tuple[tuple[str, str | None, str | None], ...] = ()
+
+
+def diff_sessions(left: TraceSession, right: TraceSession) -> TraceDiffResult:
+    lc = Counter(e.marker_id for e in left.events)
+    rc = Counter(e.marker_id for e in right.events)
+    added = tuple(sorted((m, rc[m] - lc[m]) for m in rc if rc[m] > lc[m]))
+    missing = tuple(sorted((m, lc[m] - rc[m]) for m in lc if lc[m] > rc[m]))
+
+    def domains(session: TraceSession, attr: str) -> dict[str, tuple[str, ...]]:
+        out: dict[str, set[str]] = {}
+        for e in session.events:
+            value = getattr(e, attr)
+            if value:
+                out.setdefault(e.marker_id, set()).add(value)
+        return {k: tuple(sorted(v)) for k, v in out.items()}
+
+    lcpu, rcpu = domains(left, "cpu_hint"), domains(right, "cpu_hint")
+    ltask, rtask = domains(left, "task_hint"), domains(right, "task_hint")
+    shared = sorted(set(lc) & set(rc))
+    changed_cpu = tuple((m, lcpu.get(m, ()), rcpu.get(m, ())) for m in shared if lcpu.get(m, ()) != rcpu.get(m, ()))
+    changed_task = tuple((m, ltask.get(m, ()), rtask.get(m, ())) for m in shared if ltask.get(m, ()) != rtask.get(m, ()))
+
+    def first_positions(session: TraceSession) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for e in session.events:
+            out.setdefault(e.marker_id, e.event_index)
+        return out
+
+    def first_times(session: TraceSession) -> dict[str, str | None]:
+        out: dict[str, str | None] = {}
+        for e in session.events:
+            out.setdefault(e.marker_id, e.timestamp_raw)
+        return out
+
+    lp, rp = first_positions(left), first_positions(right)
+    lt, rt = first_times(left), first_times(right)
+    order_changes = tuple((m, lp[m], rp[m]) for m in shared if lp[m] != rp[m])
+    timing_changes = tuple((m, lt.get(m), rt.get(m)) for m in shared if lt.get(m) != rt.get(m))
+    return TraceDiffResult(left.name, right.name, added, missing, changed_cpu, changed_task, order_changes, timing_changes)