atif-sql 0.2.0__py3-none-any.whl

atif_corpus/infrastructure/scanner.py

@@ -0,0 +1,316 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Filesystem discovery: sessions + side-files with their ``st_mtime_ns``.
+
+The one place atif-corpus stats the source corpus. WHERE it looks comes from a
+:class:`~atif_corpus.domain.source_layout.SourceLayout` — one per agent, so
+this module walks one algorithm instead of carrying a branch per transcript
+shape. Discovery follows CONTRACT.md exactly:
+
+* transcripts sit ``layout.transcript_depth`` directory levels under the source
+  root: ``<source_root>/<project>/<session>.jsonl`` for Claude Code,
+  ``<source_root>/<YYYY>/<MM>/<DD>/rollout-<ts>-<uuid>.jsonl`` for Codex;
+* the session id comes from the FILENAME via ``layout.session_id`` — the whole
+  stem for Claude Code, the trailing uuid for a Codex rollout — and must pass
+  :func:`~atif_corpus.domain.session_id.session_id_rejection` before it is
+  used for anything: it becomes a directory name in the corpus and, from
+  there, part of the paths atif-duck opens. A name that fails is REJECTED:
+  skipped this pass, logged with the reason, and reported in
+  :attr:`SourceScan.rejected_session_ids` so the skip is visible;
+* side-files are found by ``rglob`` over the session dir (the directory
+  named after the session stem) filtered to ``*.jsonl`` and ``*.meta.json``
+  — the rglob deliberately does NOT hardcode ``subagents/`` vs
+  ``subagents/workflows/wf_*/`` so any deeper future nesting is still
+  watermarked. The ``agent-*.meta.json`` sidecars are watched because the
+  converter reads them (subagent type and description), so a sidecar that
+  changes on its own has to make the session stale; the other files under the
+  side dir (``tool-results/`` spills) are archived but not watched. Only layouts that HAVE side-files are walked for them: a Codex
+  sub-agent writes its own rollout under its own session id, so a rollout is
+  always alone and looking for siblings would be a stat per session for a
+  directory that cannot exist.
+
+A scan reports two kinds of absence and they must never be conflated. A
+session whose main transcript is genuinely GONE is marked source-removed:
+its corpus dir is kept and its meta says the source is gone. A session whose
+``stat`` merely FAILED (EIO, ESTALE, an NFS or permission blip) is only
+unreadable this pass and its source may well still be there — marking it
+would record a live session as deleted over a transient error. :class:`SourceScan` keeps the two in
+separate fields so a caller cannot accidentally treat one as the other.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from atif_corpus.domain.session_id import session_id_rejection
+from atif_corpus.domain.sessions import SessionSource
+from atif_corpus.domain.source_layout import CLAUDE_CODE_LAYOUT, SourceLayout
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+#: The side-dir files whose mtimes are part of a session's watermark: the
+#: side-file transcripts, and the ``agent-*.meta.json`` sidecars the converter
+#: reads beside them.
+WATCHED_SIDE_FILE_GLOBS: tuple[str, ...] = ("*.jsonl", "*.meta.json")
+
+#: Shared empty default; a frozen dataclass must not hand out a mutable dict.
+_NO_UNREADABLE: Mapping[str, str] = MappingProxyType[str, str]({})
+
+
+@dataclass(frozen=True, slots=True)
+class SourceScan:
+    """One scan of the source root: sessions found, plus sessions it could not read."""
+
+    #: Sessions discovered this pass, sorted by session id.
+    sessions: tuple[SessionSource, ...] = ()
+    #: ``{session_id: main_jsonl}`` for sessions whose sources raised a
+    #: non-``FileNotFoundError`` ``OSError``. Absent from ``sessions`` (nothing
+    #: converts without an mtime), so callers MUST exclude them from source-removal
+    #: removal and retain their watermark entries — the main path is carried
+    #: because retention scopes entries by it. Wrapped read-only so the frozen
+    #: dataclass is actually frozen rather than frozen-except-this-field.
+    unreadable: Mapping[str, str] = field(default_factory=lambda: _NO_UNREADABLE)
+    #: Directories whose CONTENTS could not be listed at all (a project dir at
+    #: mode 000). Their sessions cannot appear in ``unreadable`` — that map is
+    #: keyed by discovered session, and nothing was discovered — so the
+    #: directory is reported instead and the caller resolves it to session ids
+    #: through the watermark.
+    unlistable_dirs: tuple[str, ...] = ()
+    #: Transcript names whose derived session id failed the boundary check
+    #: (:mod:`atif_corpus.domain.session_id`), sorted. Nothing from them is
+    #: materialized, they are never marked source-removed, and they are reported so an
+    #: operator can see why a transcript is missing from the corpus.
+    rejected_session_ids: tuple[str, ...] = ()
+
+    @property
+    def unreadable_session_ids(self) -> frozenset[str]:
+        """Ids of the sessions this scan could not read."""
+        return frozenset(self.unreadable)
+
+    def with_unreadable(self, extra: Mapping[str, str]) -> SourceScan:
+        """A copy of this scan carrying more unreadable ``{session_id: main_jsonl}``.
+
+        Lets a caller that resolved :attr:`unlistable_dirs` to session ids
+        fold them in, so source-removal marking, watermark retention and the pass
+        report all read one unreadable set instead of three.
+        """
+        if not extra:
+            return self
+        return SourceScan(
+            sessions=self.sessions,
+            unreadable=MappingProxyType({**self.unreadable, **extra}),
+            unlistable_dirs=self.unlistable_dirs,
+            rejected_session_ids=self.rejected_session_ids,
+        )
+
+
+def _mtime_ns(path: Path) -> int | None:
+    """``st_mtime_ns`` for ``path``; ``None`` when it vanished mid-scan.
+
+    Every other ``OSError`` propagates so the caller can tell "deleted" from
+    "could not read".
+    """
+    try:
+        return path.stat().st_mtime_ns
+    except FileNotFoundError:
+        # A transcript deleted between glob and stat is a normal race on a
+        # live corpus, not an error: it simply isn't part of this scan.
+        logger.debug("scan: {} vanished mid-scan; skipping", path)
+        return None
+
+
+def _session_mtimes(main_jsonl: Path, layout: SourceLayout) -> dict[str, int] | None:
+    """``{path: mtime_ns}`` for one session, or ``None`` when its main file vanished.
+
+    Side-files are the transcripts and ``*.meta.json`` sidecars under the
+    session dir (:data:`WATCHED_SIDE_FILE_GLOBS`). A vanished SIDE-file is
+    simply omitted: the session is still part of the scan, and the missing entry is exactly the staleness signal that makes it
+    re-materialize. Raises ``OSError`` when any source could not be stat'd.
+    """
+    main_mtime = _mtime_ns(main_jsonl)
+    if main_mtime is None:
+        return None
+    mtimes = {str(main_jsonl): main_mtime}
+
+    if not layout.has_side_files:
+        return mtimes
+    side_dir = main_jsonl.parent / main_jsonl.stem
+    if side_dir.is_dir():
+        watched = {path for pattern in WATCHED_SIDE_FILE_GLOBS for path in side_dir.rglob(pattern)}
+        for side_file in sorted(watched):
+            side_mtime = _mtime_ns(side_file)
+            if side_mtime is not None:
+                mtimes[str(side_file)] = side_mtime
+    return mtimes
+
+
+def _list_dir(directory: Path) -> list[Path] | None:
+    """Sorted entries of ``directory``; ``[]`` if it vanished, ``None`` if unlistable.
+
+    ``Path.glob`` swallows a ``PermissionError`` on a directory it cannot
+    open and simply yields nothing, which is indistinguishable from an empty
+    directory — and "empty" makes every session under it look deleted. Listing each
+    level explicitly is what keeps the two apart.
+    """
+    try:
+        return sorted(directory.iterdir())
+    except FileNotFoundError:
+        logger.debug("scan: directory {} vanished mid-scan; skipping", directory)
+        return []
+    except OSError as error:
+        logger.warning(
+            "scan: cannot list directory {} ({}); its sessions are unreadable "
+            "this pass and are NOT treated as deleted",
+            directory,
+            error,
+        )
+        return None
+
+
+def _transcript_dirs(source_root: Path, layout: SourceLayout) -> tuple[list[Path], list[str]]:
+    """The directories that hold transcripts, plus every dir that would not list.
+
+    Descends exactly ``layout.transcript_depth`` levels, listing each one, so an
+    unopenable directory at ANY level is reported as unlistable instead of
+    reading as empty. Claude Code stops at the project dirs; Codex walks
+    year -> month -> day.
+    """
+    level = [source_root]
+    unlistable: list[str] = []
+    for _ in range(layout.transcript_depth):
+        next_level: list[Path] = []
+        for directory in level:
+            entries = _list_dir(directory)
+            if entries is None:
+                unlistable.append(str(directory))
+                continue
+            next_level.extend(entry for entry in entries if entry.is_dir())
+        level = sorted(next_level)
+    return level, unlistable
+
+
+def _transcripts(transcript_dir: Path, layout: SourceLayout) -> list[Path] | None:
+    """List one dir's transcript files for this agent, or ``None`` if unlistable."""
+    entries = _list_dir(transcript_dir)
+    if entries is None:
+        return None
+    return [entry for entry in entries if layout.is_transcript(entry.name)]
+
+
+def scan_sources(
+    source_root: Path,
+    layout: SourceLayout = CLAUDE_CODE_LAYOUT,
+) -> SourceScan:
+    """Discover every session under ``source_root``, separating unreadable and rejected ones.
+
+    Sessions come back sorted by session id so the scan itself is
+    deterministic input to :func:`atif_corpus.domain.sessions.build_plan`.
+    An absent or empty root yields an empty scan — a fresh machine is not an
+    error condition.
+
+    Absence is separated from unreadability at EVERY level: a session whose
+    ``stat`` failed lands in :attr:`SourceScan.unreadable`, and any directory
+    that could not be LISTED — the root, a Claude Code project dir, a Codex
+    year/month/day dir — lands in :attr:`SourceScan.unlistable_dirs`. Its
+    sessions were never discovered, so only the caller's watermark knows which
+    ids they were.
+
+    ``layout`` defaults to Claude Code's shape, which is what every caller
+    predating Codex support meant.
+    """
+    if not source_root.is_dir():
+        logger.debug("scan: source root {} does not exist", source_root)
+        return SourceScan()
+
+    transcript_dirs, unlistable = _transcript_dirs(source_root, layout)
+
+    sessions: list[SessionSource] = []
+    unreadable: dict[str, str] = {}
+    rejected: list[str] = []
+    for transcript_dir in transcript_dirs:
+        transcripts = _transcripts(transcript_dir, layout)
+        if transcripts is None:
+            unlistable.append(str(transcript_dir))
+            continue
+        for main_jsonl in transcripts:
+            session_id = layout.session_id(main_jsonl.name)
+            if session_id is None:
+                logger.debug(
+                    "scan: {} is not a {} transcript name; skipping",
+                    main_jsonl,
+                    layout.agent.value,
+                )
+                continue
+            rejection = session_id_rejection(session_id)
+            if rejection is not None:
+                # The one outside influence on a corpus path. A name that fails
+                # here never becomes a directory, a watermark key, or a SQL
+                # parameter; it is reported instead of guessed at.
+                logger.warning(
+                    "scan: rejecting session name {!r} from {} ({}); nothing from it "
+                    "is materialized",
+                    session_id,
+                    main_jsonl,
+                    rejection,
+                )
+                rejected.append(session_id)
+                continue
+            try:
+                mtimes = _session_mtimes(main_jsonl, layout)
+            except OSError as error:
+                logger.warning(
+                    "scan: cannot stat sources of session {} ({}); skipping this pass "
+                    "and NOT treating it as deleted",
+                    session_id,
+                    error,
+                )
+                unreadable[session_id] = str(main_jsonl)
+                continue
+            if mtimes is None:
+                continue
+            sessions.append(
+                SessionSource(
+                    session_id=session_id,
+                    session_jsonl=str(main_jsonl),
+                    source_mtimes=mtimes,
+                )
+            )
+    sessions.sort(key=lambda s: s.session_id)
+    logger.debug(
+        "scan: {} sessions ({} unreadable, {} unlistable dirs, {} rejected names) under {} as {}",
+        len(sessions),
+        len(unreadable),
+        len(unlistable),
+        len(rejected),
+        source_root,
+        layout.agent.value,
+    )
+    return SourceScan(
+        sessions=tuple(sessions),
+        unreadable=MappingProxyType(dict(unreadable)),
+        unlistable_dirs=tuple(unlistable),
+        rejected_session_ids=tuple(sorted(rejected)),
+    )
+
+
+def scan_source_root(
+    source_root: Path,
+    layout: SourceLayout = CLAUDE_CODE_LAYOUT,
+) -> tuple[SessionSource, ...]:
+    """The sessions found under ``source_root`` — :func:`scan_sources` without diagnostics.
+
+    For read-only callers that plan but never mark: only source-removal
+    marking needs ``unreadable_session_ids``, and a caller that marks must
+    reach for :func:`scan_sources` and handle it. Dropping the
+    diagnostics loses no operator signal here — :func:`scan_sources` logs each
+    unreadable session and unlistable directory at WARNING, and the CLI's sink
+    is WARNING-and-up on stderr, so an unreadable source still announces
+    itself alongside the status output.
+    """
+    return scan_sources(source_root, layout).sessions

atif_corpus/infrastructure/settings.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Runtime configuration for atif-corpus.
+
+Pydantic v2 ``BaseSettings`` populated from env vars prefixed with
+``ATIF_SQL_`` (workspace convention). Reading process env is I/O, so this
+lives in ``infrastructure`` and never in ``domain``. Every ``_default_*()``
+factory reads env at CALL time — not import time — so tests and long-lived
+processes that re-point ``CLAUDE_CONFIG_DIR`` observe the new value without
+a module reload.
+
+TWO AGENTS, TWO DEFAULT ROOTS. ``agent`` selects which pair of defaults the
+unset roots take: ``<CLAUDE_CONFIG_DIR>/projects`` for Claude Code,
+``<CODEX_HOME>/sessions`` for Codex, each with its own slugged corpus root so
+one agent's corpus can never overwrite the other's. An EXPLICIT root — passed
+in or set in the env — always wins over the agent default, which is what keeps
+``ATIF_SQL_SOURCE_ROOT`` meaning exactly what it meant before Codex existed.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from atif_corpus.domain.agents import DEFAULT_AGENT, AgentSource
+from atif_corpus.domain.slug import corpus_slug
+
+
+def _claude_config_root() -> str:
+    """Return Claude Code's config-dir root, honoring ``CLAUDE_CONFIG_DIR``."""
+    return str(Path(os.environ.get("CLAUDE_CONFIG_DIR", "~/.claude")).expanduser())
+
+
+def _default_source_root() -> Path:
+    """Root directory holding per-project session transcript directories."""
+    return Path(_claude_config_root()) / "projects"
+
+
+def _codex_config_root() -> str:
+    """Return Codex CLI's config-dir root, honoring ``CODEX_HOME``.
+
+    ``CODEX_HOME`` is Codex's own variable, not one this workspace invents, so
+    a user who already re-points Codex gets their rollouts discovered with no
+    extra configuration.
+    """
+    return str(Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser())
+
+
+def _default_codex_source_root() -> Path:
+    """Root directory holding Codex's per-day rollout directories."""
+    return Path(_codex_config_root()) / "sessions"
+
+
+def _corpus_root_for(source_root: Path) -> Path:
+    """Materialized corpus root: ``~/.atif-sql/corpus/<slug of source root>``.
+
+    Slugging the SOURCE root (not a fixed name) keeps corpora for different
+    inputs separate: re-pointing ``CLAUDE_CONFIG_DIR``, or switching agents,
+    must never overwrite another corpus's artifacts.
+    """
+    return Path.home() / ".atif-sql" / "corpus" / corpus_slug(source_root)
+
+
+def _default_corpus_root() -> Path:
+    """The Claude Code corpus root — the default when no agent is named."""
+    return _corpus_root_for(_default_source_root())
+
+
+#: Ceiling on the default pool size. Conversion is CPU-bound and the corpus
+#: filesystem takes the writes, so past this the pool stops earning its
+#: process starts; an operator who has measured otherwise sets the env var.
+MAX_DEFAULT_MATERIALIZE_WORKERS = 8
+
+
+def default_materialize_workers() -> int:
+    """``min(8, cpu_count)`` — the pool size a bare ``materialize`` uses.
+
+    Read at CALL time like every other default here. ``os.cpu_count()`` can
+    answer ``None`` on an exotic platform, which reads as one worker: the
+    inline path, never a pool of nothing.
+    """
+    return max(1, min(MAX_DEFAULT_MATERIALIZE_WORKERS, os.cpu_count() or 1))
+
+
+class CorpusSettings(BaseSettings):
+    """Env-driven settings for corpus materialization."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="ATIF_SQL_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    #: Which agent's transcripts this corpus holds (``ATIF_SQL_AGENT``).
+    agent: AgentSource = DEFAULT_AGENT
+    #: Where raw transcripts live: ``<config>/projects`` for Claude Code,
+    #: ``<CODEX_HOME>/sessions`` for Codex.
+    source_root: Path = Field(default_factory=_default_source_root)
+    #: Where materialized artifacts are written (CONTRACT.md layout root).
+    corpus_root: Path = Field(default_factory=_default_corpus_root)
+    #: Seconds of source silence before a session may (re)materialize.
+    quiesce_seconds: int = 300
+    #: Processes for a materialize pass's convert+write stage
+    #: (``ATIF_SQL_MATERIALIZE_WORKERS``). ``1`` is the inline reference path.
+    materialize_workers: int = Field(default_factory=default_materialize_workers, ge=1)
+
+    @model_validator(mode="after")
+    def _apply_agent_defaults(self) -> CorpusSettings:
+        """Re-derive the roots the caller left unset from ``agent``.
+
+        ``model_fields_set`` is the test, and it is the right one: a field
+        filled by its ``default_factory`` is absent from that set while a field
+        populated from the environment or from a keyword is present. So an
+        explicit ``ATIF_SQL_SOURCE_ROOT`` (or an explicit ``corpus_root=``)
+        still wins over the agent default, and only a genuinely unset root
+        moves. With ``agent`` at its default this method changes nothing, which
+        is why every pre-Codex caller observes exactly the previous behavior.
+        """
+        if self.agent is DEFAULT_AGENT:
+            return self
+        source_root = self.source_root
+        if "source_root" not in self.model_fields_set:
+            source_root = _default_codex_source_root()
+            self.source_root = source_root
+        if "corpus_root" not in self.model_fields_set:
+            self.corpus_root = _corpus_root_for(source_root)
+        return self

atif_corpus/infrastructure/source_archive.py

@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""A session's raw source archive: its ``meta.json`` manifest, and restoring it.
+
+Every session materialized from a live source carries ``source/`` in its corpus
+dir: one ``<relative path>.zst`` per source file (the main transcript, every
+side-file transcript, and every other file under the session's side directory),
+written by the converter from the exact bytes it parsed. ``meta.json`` describes
+it under ``source_archive``::
+
+    {
+        "codec": "zstd",
+        "source_dir": "-home-me-proj",  # the main transcript's parent, relative
+        # to the source root it was scanned under
+        "main": "<session>.jsonl",  # the main transcript, relative to source_dir
+        "files": [{"path": "<session>.jsonl", "size": 123, "sha256": "..."}, ...],
+    }
+
+The archive is what lets a future converter re-run a session after Claude Code or
+Codex deleted the original. :func:`restore_session_sources` rebuilds the source
+tree under a directory the caller owns and returns the main transcript's path
+there; materialize uses it to re-convert a source-removed session whose recorded
+generation is stale, and any caller can use it to point a converter at the
+restored copy. ``source_dir`` is restored too because the converters read the
+transcript's parent directory name (the fallback session id).
+
+Every path in the manifest becomes a filesystem path, so each one is checked
+before use: relative, no empty, ``.`` or ``..`` part, no backslash or NUL.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING, Any
+
+import zstandard
+
+from atif_corpus.domain.layout import META_FILENAME, SOURCE_ARCHIVE_DIRNAME
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from atif_corpus.domain.ports import ArchivedSource
+
+#: The meta.json key that holds the manifest.
+META_SOURCE_ARCHIVE_KEY = "source_archive"
+
+#: The only codec written so far.
+ARCHIVE_CODEC = "zstd"
+
+#: Suffix of every archived file.
+ARCHIVE_SUFFIX = ".zst"
+
+#: Decompression read size.
+_CHUNK_BYTES = 1024 * 1024
+
+
+class SourceArchiveError(RuntimeError):
+    """The archive is missing, malformed, or does not decompress to what it claims."""
+
+
+def archive_path_rejection(path: str) -> str | None:
+    """Why ``path`` may not become a path under the archive, or ``None`` if it may."""
+    if not path:
+        return "empty path"
+    if "\\" in path or "\x00" in path:
+        return "backslash or NUL in path"
+    pure = PurePosixPath(path)
+    if pure.is_absolute():
+        return "absolute path"
+    if any(part in {"", ".", ".."} for part in path.split("/")):
+        return "empty, '.' or '..' component"
+    return None
+
+
+def _require_safe(path: str, what: str) -> str:
+    rejection = archive_path_rejection(path)
+    if rejection is not None:
+        msg = f"source archive {what} {path!r} rejected: {rejection}"
+        raise SourceArchiveError(msg)
+    return path
+
+
+def archive_manifest(
+    files: Sequence[ArchivedSource],
+    *,
+    source_dir: str,
+    main: str,
+) -> dict[str, Any]:
+    """The ``meta.json`` ``source_archive`` value for one freshly archived session.
+
+    Raises :class:`SourceArchiveError` when a path is unsafe or the main
+    transcript is not among the files, so a converter that archived the wrong
+    thing fails the session rather than publishing an archive nothing can
+    restore.
+    """
+    if source_dir != ".":
+        _require_safe(source_dir, "source_dir")
+    _require_safe(main, "main")
+    entries = [
+        {"path": _require_safe(f.relative_path, "file"), "size": f.size, "sha256": f.sha256}
+        for f in sorted(files, key=lambda f: f.relative_path)
+    ]
+    if main not in {entry["path"] for entry in entries}:
+        msg = f"source archive does not contain its main transcript {main!r}"
+        raise SourceArchiveError(msg)
+    return {"codec": ARCHIVE_CODEC, "source_dir": source_dir, "main": main, "files": entries}
+
+
+def verify_archive_on_disk(archive_dir: Path, files: Sequence[ArchivedSource]) -> None:
+    """Every file the converter claims to have archived exists under ``archive_dir``."""
+    for archived in files:
+        _require_safe(archived.relative_path, "file")
+        member = archive_dir / f"{archived.relative_path}{ARCHIVE_SUFFIX}"
+        if not member.is_file():
+            msg = f"converter listed {archived.relative_path!r} but wrote no {member}"
+            raise SourceArchiveError(msg)
+
+
+def read_manifest(session_dir: Path) -> dict[str, Any] | None:
+    """The ``source_archive`` manifest of one corpus session dir, or ``None`` without one."""
+    try:
+        meta = json.loads((session_dir / META_FILENAME).read_text(encoding="utf-8"))
+    except (OSError, ValueError) as error:
+        msg = f"cannot read {session_dir / META_FILENAME}: {error}"
+        raise SourceArchiveError(msg) from error
+    if not isinstance(meta, dict):
+        msg = f"{session_dir / META_FILENAME} is not a JSON object"
+        raise SourceArchiveError(msg)
+    manifest = meta.get(META_SOURCE_ARCHIVE_KEY)
+    if manifest is None:
+        return None
+    if not isinstance(manifest, dict):
+        msg = f"{session_dir / META_FILENAME} has a malformed {META_SOURCE_ARCHIVE_KEY}"
+        raise SourceArchiveError(msg)
+    return manifest
+
+
+def _restore_one(member: Path, target: Path, *, size: int, sha256: str) -> None:
+    digest = hashlib.sha256()
+    written = 0
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with member.open("rb") as compressed, target.open("wb") as out:
+        reader = zstandard.ZstdDecompressor().stream_reader(compressed)
+        for chunk in iter(lambda: reader.read(_CHUNK_BYTES), b""):
+            digest.update(chunk)
+            out.write(chunk)
+            written += len(chunk)
+    if written != size or digest.hexdigest() != sha256:
+        msg = (
+            f"{member} decompressed to {written} bytes with sha256 {digest.hexdigest()}, "
+            f"expected {size} bytes with sha256 {sha256}"
+        )
+        raise SourceArchiveError(msg)
+
+
+def restore_session_sources(session_dir: Path, dest_root: Path) -> Path:
+    """Rebuild one session's raw source tree under ``dest_root``; return the main transcript.
+
+    ``session_dir`` is a corpus session dir (``<corpus>/sessions/<id>``). Files
+    land at ``dest_root/<source_dir>/<path>`` with their original bytes, each
+    verified against its recorded size and sha256, so ``dest_root`` stands in
+    for the source root the session was scanned under and the returned path
+    can be handed to the same converter the live source would have been.
+
+    ``dest_root`` must be a directory the caller owns and removes; nothing
+    here cleans it up. Raises :class:`SourceArchiveError` when the session has
+    no archive, the manifest is malformed, or a file fails verification.
+    """
+    manifest = read_manifest(session_dir)
+    if manifest is None:
+        msg = f"{session_dir} has no source archive"
+        raise SourceArchiveError(msg)
+    if manifest.get("codec") != ARCHIVE_CODEC:
+        msg = f"{session_dir} source archive codec {manifest.get('codec')!r} is not supported"
+        raise SourceArchiveError(msg)
+    source_dir = str(manifest.get("source_dir", ""))
+    main = _require_safe(str(manifest.get("main", "")), "main")
+    base = dest_root if source_dir == "." else dest_root / _require_safe(source_dir, "source_dir")
+    files = manifest.get("files")
+    if not isinstance(files, list) or not files:
+        msg = f"{session_dir} source archive lists no files"
+        raise SourceArchiveError(msg)
+    archive_dir = session_dir / SOURCE_ARCHIVE_DIRNAME
+    for entry in files:
+        if not isinstance(entry, dict):
+            msg = f"{session_dir} source archive has a malformed file entry"
+            raise SourceArchiveError(msg)
+        path = _require_safe(str(entry.get("path", "")), "file")
+        _restore_one(
+            archive_dir / f"{path}{ARCHIVE_SUFFIX}",
+            base / path,
+            size=int(entry.get("size", -1)),
+            sha256=str(entry.get("sha256", "")),
+        )
+    restored_main = base / main
+    if not restored_main.is_file():
+        msg = f"{session_dir} source archive does not contain its main transcript {main!r}"
+        raise SourceArchiveError(msg)
+    return restored_main