atif-sql 0.2.0__py3-none-any.whl

atif_converter/infrastructure/claude_code_converter.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: Apache-2.0
+# Ported from harbor 0.23.0, src/harbor/agents/installed/claude_code.py
+# (Apache-2.0, Copyright the Harbor authors), onto the ATIF models vendored in
+# atif_converter.domain.atif, so atif-converter doesn't depend on harbor.
+
+"""Read one Claude Code session from disk and convert it, with no staging.
+
+The file half of harbor's ``_convert_events_to_trajectory``: the JSONL reading
+loop is harbor's (blank lines skipped, a malformed line logged and skipped,
+the rest parsed), and side-file discovery is what the old adapter's staging
+did before harbor ever saw the session — ``<parent>/<stem>/`` walked with
+``rglob("*.jsonl")``, a leading ``subagents`` path part dropped, the remaining
+parts joined with ``__``. That joined name is the key the domain function
+sorts on, so a workflow-nested ``subagents/workflows/wf_1/agent-a.jsonl`` is
+read in the same position it was when staged flat as
+``subagents/workflows__wf_1__agent-a.jsonl``. When two side-files flatten to
+the same name the first in ``rglob`` order wins, which is what the adapter's
+``if not staged.exists()`` guard did.
+
+No temp dir, no symlinks, no ``harbor.agents`` import. ``*.meta.json``
+sidecars are excluded by the ``*.jsonl`` suffix filter, as before.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from atif_converter.domain.atif import Trajectory
+from atif_converter.domain.claude_code_conversion import convert_claude_code_records
+from atif_converter.infrastructure.raw_records import LoadedSession, parse_jsonl_records
+
+
+def read_session_records(path: Path) -> list[dict[str, Any]]:
+    """Parse one JSONL transcript the way harbor's reading loop does.
+
+    Blank lines are skipped; a line that is not JSON is logged at debug and
+    skipped rather than failing the session. A line that IS JSON but not an
+    object is kept as-is, as harbor keeps it (it fails later, in the same
+    place harbor fails).
+    """
+    with path.open(encoding="utf-8") as handle:
+        return parse_jsonl_records(handle, path)
+
+
+def staged_side_name(side_file: Path, side_dir: Path) -> str:
+    """The flat name harbor saw a side-file under: path parts joined with ``__``.
+
+    A leading ``subagents`` part is dropped, so
+    ``subagents/workflows/wf_1/agent-a.jsonl`` becomes
+    ``workflows__wf_1__agent-a.jsonl``. The domain converter sorts on this name.
+    """
+    rel_parts = side_file.relative_to(side_dir).parts
+    if rel_parts and rel_parts[0] == "subagents":
+        rel_parts = rel_parts[1:]
+    return "__".join(rel_parts)
+
+
+def discover_side_files(session_jsonl: Path, *, include_subagents: bool = True) -> dict[str, Path]:
+    """Staged side-file name -> side-file path, for one session's ``<stem>/`` dir.
+
+    Empty when ``include_subagents`` is false or the session has no side dir.
+    """
+    side_files: dict[str, Path] = {}
+    side_dir = session_jsonl.parent / session_jsonl.stem
+    if include_subagents and side_dir.is_dir():
+        for side_file in sorted(side_dir.rglob("*.jsonl")):
+            side_files.setdefault(staged_side_name(side_file, side_dir), side_file)
+    return side_files
+
+
+def convert_loaded_claude_code_session(
+    loaded: LoadedSession, *, include_subagents: bool = True
+) -> Trajectory | None:
+    """Convert an already-read session: the records of :func:`~atif_converter.infrastructure.raw_records.load_session`.
+
+    Same result as :func:`convert_claude_code_session` on the same bytes, with
+    no second read: the main transcript is the loaded main file and the
+    side-files are the loaded side-files keyed by their staged name, first in
+    sorted order winning on a name collision exactly as
+    :func:`discover_side_files` resolves it. ``include_subagents`` off converts
+    the main transcript alone, as before.
+    """
+    session_jsonl = loaded.snapshot.session_jsonl
+    side_dir = session_jsonl.parent / session_jsonl.stem
+    side_records: dict[str, list[Any]] = {}
+    if include_subagents:
+        for path, records in loaded.records_by_file.items():
+            if path != session_jsonl:
+                side_records.setdefault(staged_side_name(path, side_dir), records)
+    return convert_claude_code_records(
+        loaded.main_records,
+        side_records,
+        fallback_session_id=session_jsonl.parent.name or "-unknown",
+    )
+
+
+def convert_claude_code_session(
+    session_jsonl: Path, *, include_subagents: bool = True
+) -> Trajectory | None:
+    """Convert one Claude Code session JSONL (plus side-files) into an ATIF trajectory.
+
+    Parameters
+    ----------
+    session_jsonl
+        The main ``<session-id>.jsonl``. Read errors propagate as ``OSError``.
+    include_subagents
+        Whether to read the ``<stem>/`` side-files; off, only the main
+        transcript is converted.
+
+    Returns
+    -------
+    Trajectory | None
+        ``None`` when the session yields no steps, as harbor returns ``None``.
+    """
+    main_records = read_session_records(session_jsonl)
+    side_records = {
+        name: read_session_records(path)
+        for name, path in discover_side_files(
+            session_jsonl, include_subagents=include_subagents
+        ).items()
+    }
+    return convert_claude_code_records(
+        main_records,
+        side_records,
+        fallback_session_id=session_jsonl.parent.name or "-unknown",
+    )

atif_converter/infrastructure/codex_adapter.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""The Codex conversion seam: our converter in, a validated ATIF dict out.
+
+The raw rollout -> ``Trajectory`` conversion is ours, in
+:mod:`atif_converter.domain.codex_conversion` via
+:mod:`atif_converter.infrastructure.codex_converter`, ported from harbor 0.22.0
+and held to parity with it by the oracle in this package's tests. harbor itself
+supplies only the public data classes and the validator. One rollout in, one
+trajectory out, by construction: the converter reads the file it is given, so
+the directory-globbing hazard the old wrapper staged around no longer exists.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+from atif_converter.domain.errors import (
+    ConversionError,
+    EmptySessionError,
+    InvalidSessionInput,
+)
+from atif_converter.infrastructure.harbor_adapter import (
+    ConversionResult,
+    validate_trajectory,
+)
+from atif_converter.infrastructure.raw_records import LoadedSession
+
+if TYPE_CHECKING:
+    from atif_converter.domain.atif import Trajectory
+
+#: A Codex rollout's filename shape. harbor's own
+#: ``Codex._ROLLOUT_FILENAME_RE`` requires the same prefix for its upload path,
+#: and the session id is the filename's trailing uuid — so a file that does not
+#: match this is not a rollout and must not be guessed at.
+_ROLLOUT_PREFIX = "rollout-"
+
+
+def codex_session_id(rollout_jsonl: Path) -> str:
+    """The session id a rollout filename carries.
+
+    ``rollout-<ISO-ish timestamp>-<uuid>.jsonl`` — the uuid is the last five
+    hyphen-separated groups of the stem, and it equals the ``id`` inside the
+    file's ``session_meta`` record (verified 2026-09-11 over the local
+    rollouts). Read from the NAME rather than the contents because discovery
+    needs a session id before anything parses the file.
+
+    Raises
+    ------
+        InvalidSessionInput: the name is not a rollout filename.
+    """
+    stem = rollout_jsonl.stem
+    if not stem.startswith(_ROLLOUT_PREFIX):
+        msg = f"not a Codex rollout filename (expected rollout-<ts>-<uuid>.jsonl): {rollout_jsonl}"
+        raise InvalidSessionInput(msg)
+    parts = stem.split("-")
+    uuid_groups = 5
+    if len(parts) < uuid_groups + 1:
+        msg = f"Codex rollout filename carries no session uuid: {rollout_jsonl}"
+        raise InvalidSessionInput(msg)
+    return "-".join(parts[-uuid_groups:])
+
+
+def convert_codex_session(rollout_jsonl: Path) -> ConversionResult:
+    """Convert one Codex rollout JSONL into a validated ATIF trajectory.
+
+    Raises
+    ------
+        InvalidSessionInput: not an existing ``.jsonl`` file.
+        EmptySessionError: the converter found no convertible events.
+        ConversionError: any unexpected failure inside the converter.
+    """
+    from atif_converter.infrastructure.codex_converter import convert_codex_rollout
+
+    if rollout_jsonl.suffix != ".jsonl" or not rollout_jsonl.is_file():
+        msg = f"not a rollout JSONL file: {rollout_jsonl}"
+        raise InvalidSessionInput(msg)
+
+    try:
+        trajectory = convert_codex_rollout(rollout_jsonl)
+    except (
+        Exception
+    ) as exc:  # the converter is a port of untyped upstream code; classify at the seam
+        msg = f"Codex conversion failed for {rollout_jsonl}"
+        raise ConversionError(msg) from exc
+
+    if trajectory is None:
+        msg = f"no convertible events in {rollout_jsonl}"
+        raise EmptySessionError(msg)
+
+    return _result_from(trajectory, rollout_jsonl)
+
+
+def convert_loaded_codex_session(loaded: LoadedSession) -> ConversionResult:
+    """Convert an already-read rollout into a validated ATIF trajectory.
+
+    The records are :func:`~atif_converter.infrastructure.harbor_adapter.read_session`'s;
+    nothing is read from disk here.
+
+    Raises
+    ------
+        EmptySessionError: the converter found no convertible events.
+        ConversionError: any unexpected failure inside the converter.
+    """
+    from atif_converter.infrastructure.codex_converter import convert_loaded_codex_rollout
+
+    rollout_jsonl = loaded.snapshot.session_jsonl
+    try:
+        trajectory = convert_loaded_codex_rollout(loaded)
+    except (
+        Exception
+    ) as exc:  # the converter is a port of untyped upstream code; classify at the seam
+        msg = f"Codex conversion failed for {rollout_jsonl}"
+        raise ConversionError(msg) from exc
+    return _result_from(trajectory, rollout_jsonl)
+
+
+def _result_from(trajectory: Trajectory | None, rollout_jsonl: Path) -> ConversionResult:
+    if trajectory is None:
+        msg = f"no convertible events in {rollout_jsonl}"
+        raise EmptySessionError(msg)
+
+    trajectory_dict: dict[str, Any] = trajectory.model_dump(mode="json", exclude_none=True)
+
+    errors = validate_trajectory(trajectory_dict)
+    if errors:
+        logger.warning("codex trajectory for {} failed validation: {}", rollout_jsonl, errors)
+
+    return ConversionResult(trajectory=trajectory_dict, validation_errors=errors)

atif_converter/infrastructure/codex_census.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Raw-side census of a Codex rollout: the input half of its LossReport.
+
+The Codex counterpart of :mod:`atif_converter.infrastructure.census`, and it
+counts the same way: over records already parsed out of a
+:class:`~atif_converter.infrastructure.raw_records.SessionSnapshot`, with no
+second parse, no disk access, no harbor, no env and no network.
+
+Two things differ from the Claude Code census, both because a rollout is one
+file rather than a main transcript plus a side-file tree:
+
+* there are no subagent side-files to classify — a Codex sub-agent writes its
+  own rollout under its own session id, so it is a separate session, not a
+  side-file of this one;
+* the convertible subset is finer than a record type. Only ``response_item``
+  records become steps, and only SOME payload types within them do
+  (:data:`~atif_converter.domain.codex_fidelity.CODEX_CONVERTIBLE_ITEM_TYPES`),
+  so the census counts the convertible items separately instead of declaring
+  every response item converted.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from atif_converter.domain.codex_fidelity import (
+    CODEX_CONVERTIBLE_ITEM_TYPES,
+    CodexRecordType,
+)
+
+_KNOWN_TYPES: dict[str, CodexRecordType] = {
+    rt.value: rt for rt in CodexRecordType if rt is not CodexRecordType.OTHER
+}
+
+
+@dataclass(frozen=True, slots=True)
+class CodexSessionCensus:
+    """Raw record counts for one rollout, plus the convertible-item detail.
+
+    ``record_counts`` covers EVERY record of the rollout, so it agrees
+    line-for-line with edges.jsonl. ``convertible_items`` is the subset of
+    ``response_item`` records whose payload type reaches a step, and
+    ``item_type_counts`` is the full response-item breakdown — which is what
+    makes a dropped ``tool_search_call`` visible as a number rather than as an
+    absence.
+    """
+
+    session_jsonl: Path
+    record_counts: dict[CodexRecordType, int] = field(default_factory=dict)
+    item_type_counts: dict[str, int] = field(default_factory=dict)
+    convertible_items: int = 0
+
+    @property
+    def response_items(self) -> int:
+        """Total ``response_item`` records, convertible or not."""
+        return self.record_counts.get(CodexRecordType.RESPONSE_ITEM, 0)
+
+
+def _record_type(record: dict[str, Any]) -> CodexRecordType:
+    raw_type = record.get("type")
+    if isinstance(raw_type, str):
+        return _KNOWN_TYPES.get(raw_type, CodexRecordType.OTHER)
+    return CodexRecordType.OTHER
+
+
+def codex_census_from_records(
+    session_jsonl: Path,
+    records: Iterable[tuple[dict[str, Any], str]],
+) -> CodexSessionCensus:
+    """Census one rollout's parsed records.
+
+    Only each record's ``type`` and, for a response item, its payload
+    ``type`` are read, so a generator whose records are discarded as they are
+    consumed counts the same as a list.
+    """
+    counts: dict[CodexRecordType, int] = {}
+    item_counts: dict[str, int] = {}
+    convertible = 0
+    for record, _source_file in records:
+        record_type = _record_type(record)
+        counts[record_type] = counts.get(record_type, 0) + 1
+        if record_type is not CodexRecordType.RESPONSE_ITEM:
+            continue
+        payload = record.get("payload")
+        item_type = payload.get("type") if isinstance(payload, dict) else None
+        key = item_type if isinstance(item_type, str) and item_type else "unknown"
+        item_counts[key] = item_counts.get(key, 0) + 1
+        if key in CODEX_CONVERTIBLE_ITEM_TYPES:
+            convertible += 1
+
+    return CodexSessionCensus(
+        session_jsonl=session_jsonl,
+        record_counts=counts,
+        item_type_counts=item_counts,
+        convertible_items=convertible,
+    )

atif_converter/infrastructure/codex_converter.py

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: Apache-2.0
+# Ported from harbor 0.22.0, src/harbor/agents/installed/codex.py (Apache-2.0,
+# Copyright the Harbor authors), so that atif-converter depends on harbor's
+# PUBLIC trajectory models only.
+
+"""Read one Codex rollout and convert it — the file half of the Codex port.
+
+harbor's ``Codex._convert_events_to_trajectory`` takes a DIRECTORY: it globs
+``*.jsonl`` inside it, converts ``max(...)`` of the matches (one file, chosen
+by name, the rest dropped) and reads that file line by line. The adapter this
+replaces satisfied that shape by symlinking one rollout alone into a scratch
+directory. This module reads the rollout directly instead, and the two are
+the same thing by construction: with exactly one file in the directory,
+``max`` is that file, so "the directory's one file" and "this file" are one
+read.
+
+The line loop is harbor's, kept exact rather than replaced with
+``read_text().splitlines()``: iterating the handle splits on newlines only,
+where ``str.splitlines`` also splits on U+2028 / U+2029 / form feed, which are
+legal unescaped inside a JSON string — a rollout carrying one would parse into
+different records under the two loops.
+
+What differs from harbor's read is the ``session_id`` fallback for a rollout
+with no ``session_meta``: harbor uses the directory's name, which in its own
+layout is the ``<DD>`` day directory; here that is the rollout's parent
+directory name, the same value on a real Codex tree.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from atif_converter.domain.atif import Trajectory
+from atif_converter.domain.codex_conversion import convert_codex_records
+from atif_converter.infrastructure.raw_records import LoadedSession, parse_jsonl_records
+
+
+def read_codex_rollout(rollout_jsonl: Path) -> list[dict[str, Any]]:
+    """The rollout's JSON records in file order, malformed lines skipped.
+
+    harbor's read loop: blank lines are ignored, a line that is not JSON is
+    logged at debug level and dropped, and everything that parses is kept
+    (harbor does not check that a parsed line is an object).
+
+    Raises
+    ------
+        OSError: the file cannot be opened or read.
+    """
+    with rollout_jsonl.open(encoding="utf-8") as handle:
+        return parse_jsonl_records(handle, rollout_jsonl)
+
+
+def convert_codex_rollout(rollout_jsonl: Path) -> Trajectory | None:
+    """Convert one Codex rollout JSONL into an ATIF trajectory.
+
+    ``None`` exactly when harbor's converter returns ``None`` for the same
+    file staged alone: the rollout has no records, or none that becomes a
+    step. Validation and the domain error taxonomy are the application
+    layer's business, as they were for the adapter this replaces.
+
+    Raises
+    ------
+        OSError: the file cannot be opened or read.
+    """
+    raw_events = read_codex_rollout(rollout_jsonl)
+    return convert_codex_records(raw_events, fallback_session_id=rollout_jsonl.parent.name)
+
+
+def convert_loaded_codex_rollout(loaded: LoadedSession) -> Trajectory | None:
+    """Convert an already-read rollout: the records of :func:`~atif_converter.infrastructure.raw_records.load_session`.
+
+    Same result as :func:`convert_codex_rollout` on the same bytes, with no
+    second read. Only the main file's records are converted; a rollout has no
+    side-files, so anything else the loader discovered is the audit's
+    business, as it was before.
+    """
+    rollout_jsonl = loaded.snapshot.session_jsonl
+    return convert_codex_records(loaded.main_records, fallback_session_id=rollout_jsonl.parent.name)
+
+
+__all__ = ["convert_codex_rollout", "convert_loaded_codex_rollout", "read_codex_rollout"]

atif_converter/infrastructure/harbor_adapter.py

@@ -0,0 +1,187 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""The Claude Code conversion seam: our converter in, a validated ATIF dict out.
+
+The ATIF validator and data classes are harbor's, vendored as
+:mod:`atif_converter.domain.atif` (the module keeps its historical name; harbor
+itself isn't a runtime dependency). The raw-JSONL -> ``Trajectory`` conversion
+is ours, in :mod:`atif_converter.domain.claude_code_conversion` via
+:mod:`atif_converter.infrastructure.claude_code_converter`, ported from harbor
+and held to parity with harbor 0.24.0 by the oracle in this package's tests.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from atif_converter.domain.atif import Trajectory
+
+from atif_converter.domain.blobs import Blob
+from atif_converter.domain.errors import (
+    ConversionError,
+    EmptySessionError,
+    InvalidSessionInput,
+)
+from atif_converter.infrastructure.raw_records import LoadedSession, load_session
+
+
+@dataclass(frozen=True, slots=True)
+class ConversionResult:
+    """Output of one conversion: trajectory dict + validation verdict.
+
+    ``convert_session`` returns the raw harbor output (``edges_lines`` and
+    ``events_lines`` empty); ``convert_and_audit`` returns the ENRICHED
+    trajectory plus the ready-to-write edges.jsonl and session_events.jsonl
+    lines derived from the raw records, and the inline attachments it lifted
+    out of the trajectory (``blobs``, one per distinct content hash) for the
+    corpus to store.
+    """
+
+    trajectory: dict[str, Any]
+    validation_errors: tuple[str, ...]
+    edges_lines: tuple[str, ...] = ()
+    #: session_events.jsonl lines (:mod:`atif_converter.domain.session_events`).
+    events_lines: tuple[str, ...] = ()
+    blobs: tuple[Blob, ...] = ()
+
+    @property
+    def is_valid(self) -> bool:
+        """True when the ATIF ``TrajectoryValidator`` accepted the trajectory."""
+        return not self.validation_errors
+
+
+def require_transcript_file(path: Path) -> None:
+    """Refuse anything that is not an existing ``.jsonl`` transcript.
+
+    Called at the TOP of each use case, before the fingerprint snapshot: the
+    snapshot stats every discovered file, so a path that does not exist reached
+    ``OSError`` from inside the snapshot and surfaced as an uncaught
+    ``FileNotFoundError`` — exit 1 from the CLI, indistinguishable from a crash
+    — instead of the terminal input verdict the caller can act on.
+
+    Raises
+    ------
+        InvalidSessionInput: the path is absent, or not a ``.jsonl`` file.
+    """
+    if path.suffix != ".jsonl" or not path.is_file():
+        msg = f"not a session JSONL file: {path}"
+        raise InvalidSessionInput(msg)
+
+
+def validate_trajectory(trajectory: dict[str, Any]) -> tuple[str, ...]:
+    """Run the ATIF ``TrajectoryValidator``; return its errors (empty = valid).
+
+    Used to re-validate after the enrichment pass mutates ``extra`` fields
+    (contract: TrajectoryValidator MUST pass post-enrichment).
+    """
+    from atif_converter.domain.atif.trajectory_validator import (
+        TrajectoryValidator,
+    )
+
+    validator = TrajectoryValidator()
+    ok = validator.validate(trajectory)
+    return () if ok else tuple(str(e) for e in validator.errors)
+
+
+def read_session(session_jsonl: Path) -> LoadedSession:
+    """Read one session's files once, fingerprinted and parsed in the same pass.
+
+    The reader half of the seam: :func:`convert_loaded_session` converts what
+    this returns, and the use case audits the same records, so the files are
+    read once for everything. A transcript that is not UTF-8 is classified as
+    a ``ConversionError`` here, as it was when the converter did its own read,
+    so a materialize pass records one per-session failure and continues.
+
+    Raises
+    ------
+        InvalidSessionInput: ``session_jsonl`` is not an existing ``.jsonl`` file.
+        ConversionError: a discovered file is not UTF-8.
+    """
+    require_transcript_file(session_jsonl)
+    try:
+        return load_session(session_jsonl)
+    except UnicodeDecodeError as exc:
+        msg = f"conversion failed for {session_jsonl}"
+        raise ConversionError(msg) from exc
+
+
+def _result_from(trajectory: Trajectory | None, session_jsonl: Path) -> ConversionResult:
+    """Validate a converted trajectory into the seam's result, or raise on ``None``."""
+    if trajectory is None:
+        msg = f"no convertible events in {session_jsonl}"
+        raise EmptySessionError(msg)
+
+    trajectory_dict: dict[str, Any] = trajectory.model_dump(mode="json", exclude_none=True)
+
+    errors = validate_trajectory(trajectory_dict)
+    if errors:
+        logger.warning("trajectory for {} failed validation: {}", session_jsonl, errors)
+
+    return ConversionResult(trajectory=trajectory_dict, validation_errors=errors)
+
+
+def convert_loaded_session(
+    loaded: LoadedSession,
+    *,
+    include_subagents: bool = True,
+) -> ConversionResult:
+    """Convert an already-read Claude Code session into a validated ATIF trajectory.
+
+    The records are :func:`read_session`'s; nothing is read from disk here.
+
+    Raises
+    ------
+        EmptySessionError: the converter found no convertible events.
+        ConversionError: any unexpected failure inside the converter.
+    """
+    from atif_converter.infrastructure.claude_code_converter import (
+        convert_loaded_claude_code_session,
+    )
+
+    session_jsonl = loaded.snapshot.session_jsonl
+    try:
+        trajectory = convert_loaded_claude_code_session(loaded, include_subagents=include_subagents)
+    except (
+        Exception
+    ) as exc:  # the converter is a port of untyped upstream code; classify at the seam
+        msg = f"conversion failed for {session_jsonl}"
+        raise ConversionError(msg) from exc
+    return _result_from(trajectory, session_jsonl)
+
+
+def convert_session(
+    session_jsonl: Path,
+    *,
+    include_subagents: bool = True,
+) -> ConversionResult:
+    """Convert one Claude Code session JSONL into a validated ATIF trajectory.
+
+    Reads the session and its side files through our converter and validates
+    the result with the ATIF ``TrajectoryValidator``. The use case goes through
+    :func:`read_session` + :func:`convert_loaded_session` instead so the audit
+    shares the read; this is the plain path for a caller that wants the
+    trajectory alone.
+
+    Raises
+    ------
+        InvalidSessionInput: ``session_jsonl`` is not an existing ``.jsonl`` file.
+        EmptySessionError: the converter found no convertible events.
+        ConversionError: any unexpected failure inside the converter.
+    """
+    from atif_converter.infrastructure.claude_code_converter import convert_claude_code_session
+
+    require_transcript_file(session_jsonl)
+
+    try:
+        trajectory = convert_claude_code_session(session_jsonl, include_subagents=include_subagents)
+    except (
+        Exception
+    ) as exc:  # the converter is a port of untyped upstream code; classify at the seam
+        msg = f"conversion failed for {session_jsonl}"
+        raise ConversionError(msg) from exc
+    return _result_from(trajectory, session_jsonl)