thread-archive 0.0.2__py3-none-any.whl

thread_archive/_config.py

@@ -0,0 +1,126 @@
+"""Filesystem layout for a thread-archive instance.
+
+A single archive lives under one *home* directory:
+
+    <home>/
+      truth/              # the durable JSONL truth (the backup)
+        manifest.json     # shard depth + checkpoint watermark
+        threads/          # one file per thread: <id>.jsonl (metadata record + events)
+        kg_events.jsonl   # append-only curatorial log (topics / links / citations)
+        thread_links.jsonl    # cross-thread overlay (topic-graph edges, folded from kg_events)
+        topic_messages.jsonl  # cross-thread overlay (topic evidence, folded from kg_events)
+      index.db            # SQLite projection, rebuildable from truth/ via `archive reindex`
+      dumps/              # drop zone: account exports dropped here are auto-imported
+      config.json         # operator choices (source opt-outs, setup state); absent = all defaults
+
+`home` resolves from ``THREAD_ARCHIVE_HOME`` (env), else ``~/.thread/archive``
+(the family's ``~/.thread/<product>/`` namespace; ``~/.thread_archive``
+survives as a compat symlink on some boxes).
+Truth and index paths can be overridden individually (e.g. for tests).
+
+``config.json`` is the durable form of the choices a user makes in the
+``thread_archive`` setup flow — which sources to ingest, what setup decided —
+and every ingest path (the watcher daemon, lazy MCP catch-up, ``archive
+watch``) consults it via :func:`source_enabled`. A missing or unreadable file
+means "all defaults": every source enabled, exactly the pre-config behavior.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+ENV_HOME = "THREAD_ARCHIVE_HOME"
+ENV_TRUTH = "THREAD_ARCHIVE_TRUTH_DIR"
+ENV_INDEX = "THREAD_ARCHIVE_INDEX"
+
+DEFAULT_HOME = Path.home() / ".thread" / "archive"
+
+
+@dataclass(frozen=True)
+class ArchivePaths:
+    """Resolved on-disk locations for one archive instance."""
+
+    home: Path
+    truth_dir: Path
+    index_path: Path
+
+    def ensure(self) -> "ArchivePaths":
+        """Create the home + truth directories if absent. Idempotent."""
+        self.home.mkdir(parents=True, exist_ok=True)
+        self.truth_dir.mkdir(parents=True, exist_ok=True)
+        return self
+
+    @property
+    def sqlalchemy_url(self) -> str:
+        return f"sqlite:///{self.index_path}"
+
+    @property
+    def dumps_dir(self) -> Path:
+        """Drop zone for downloaded account exports (auto-imported by the watcher)."""
+        return self.home / "dumps"
+
+
+def resolve_paths(
+    home: str | os.PathLike[str] | None = None,
+    *,
+    truth_dir: str | os.PathLike[str] | None = None,
+    index_path: str | os.PathLike[str] | None = None,
+) -> ArchivePaths:
+    """Resolve archive paths from explicit args, then env, then defaults."""
+    base = Path(home) if home is not None else Path(os.environ.get(ENV_HOME, DEFAULT_HOME))
+    base = base.expanduser()
+
+    truth = (
+        Path(truth_dir).expanduser()
+        if truth_dir is not None
+        else Path(os.environ.get(ENV_TRUTH, base / "truth")).expanduser()
+    )
+    index = (
+        Path(index_path).expanduser()
+        if index_path is not None
+        else Path(os.environ.get(ENV_INDEX, base / "index.db")).expanduser()
+    )
+    return ArchivePaths(home=base, truth_dir=truth, index_path=index)
+
+
+# ── config.json: durable operator choices ────────────────────────────────────
+
+CONFIG_FILE = "config.json"
+
+
+def config_path(home: str | os.PathLike[str] | None = None) -> Path:
+    return resolve_paths(home).home / CONFIG_FILE
+
+
+def load_config(home: str | os.PathLike[str] | None = None) -> dict:
+    """The parsed config, or ``{}`` when absent/unreadable (all defaults).
+
+    Fail-soft on purpose: a corrupt config file must degrade to default
+    behavior (ingest everything), never take an ingest path down.
+    """
+    try:
+        data = json.loads(config_path(home).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save_config(cfg: dict, home: str | os.PathLike[str] | None = None) -> Path:
+    """Write the config atomically (tmp + rename). Returns the path."""
+    path = config_path(home)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(cfg, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    tmp.replace(path)
+    return path
+
+
+def source_enabled(cfg: dict, source_name: str) -> bool:
+    """Whether a source watcher may ingest. Unlisted sources default to enabled."""
+    entry = cfg.get("sources", {}).get(source_name, {})
+    if not isinstance(entry, dict):
+        return True
+    return bool(entry.get("enabled", True))

thread_archive/_importers/__init__.py

@@ -0,0 +1,81 @@
+"""Incremental import: provider transcripts → events (over the JSONL truth seam).
+
+Two shapes: single-file line-stream importers (Claude Code, Codex, Grok,
+Antigravity, cloth) and SQLite-DB scanners (Cursor, OpenCode). All converge on the
+same ``assemble_events`` build → dedup → write loop, and all are atomic per unit of
+import. (cloth is Claude-Code-shaped, so its importer delegates to the claude_code
+path under ``source="cloth"``.)
+"""
+
+from __future__ import annotations
+
+from ._result import IncrementalImportResult
+from .antigravity import import_antigravity_session_incremental
+from .claude_code import import_session_incremental
+from .claude_science import (
+    ClaudeScienceDbScanResult,
+    ClaudeScienceImportResult,
+    import_claude_science_db,
+    import_claude_science_frame,
+)
+from .cloth import import_cloth_session_incremental
+from .codex import import_codex_session_incremental
+from .cowork import import_cowork_session_incremental
+from .cursor import (
+    CursorDbScanResult,
+    CursorImportResult,
+    import_cursor_db,
+    import_cursor_from_payload,
+)
+from .grok import import_grok_session_incremental
+from .opencode import (
+    OpenCodeDbScanResult,
+    OpenCodeImportResult,
+    import_opencode_db,
+    import_opencode_from_payload,
+)
+
+# Provider name → single-file line-stream importer. (Cursor / OpenCode scan a DB
+# of many sessions and are dispatched separately.)
+LINE_STREAM_IMPORTERS = {
+    "claude-code": import_session_incremental,
+    "codex": import_codex_session_incremental,
+    "grok": import_grok_session_incremental,
+    "antigravity": import_antigravity_session_incremental,
+    "cloth": import_cloth_session_incremental,
+}
+
+DB_SCANNERS = {
+    "cursor": import_cursor_db,
+    "opencode": import_opencode_db,
+}
+
+# Claude Science scans a DB of many frames per org, dispatched per-org by the watcher
+# (not a single fixed DB path like Cursor/OpenCode), so it's tracked separately.
+
+PROVIDERS = list(LINE_STREAM_IMPORTERS) + list(DB_SCANNERS)
+
+__all__ = [
+    "IncrementalImportResult",
+    "import_session_incremental",
+    "import_cloth_session_incremental",
+    "import_codex_session_incremental",
+    "import_cowork_session_incremental",
+    "import_claude_science_db",
+    "import_claude_science_frame",
+    "ClaudeScienceImportResult",
+    "ClaudeScienceDbScanResult",
+    "import_grok_session_incremental",
+    "import_antigravity_session_incremental",
+    "import_cursor_db",
+    "import_cursor_from_payload",
+    "import_opencode_db",
+    "import_opencode_from_payload",
+    "CursorImportResult",
+    "CursorDbScanResult",
+    "OpenCodeImportResult",
+    "OpenCodeDbScanResult",
+    "LINE_STREAM_IMPORTERS",
+    "DB_SCANNERS",
+    "PROVIDERS",
+]

thread_archive/_importers/_continuation.py

@@ -0,0 +1,136 @@
+"""Continuation / fork detection for the CC incremental import.
+
+Decides whether a fresh Claude Code JSONL is a *continuation* of an existing
+thread (merge into it) or a new/forked session (mint its own). Ported from
+canonical ``streaming/incremental_import/_continuation.py``; the Postgres
+``payload->>'content'`` becomes SQLite ``json_extract(payload, '$.content')``,
+and the candidate lookup validates each same-first-message thread by the
+prefix-consistency walk rather than disambiguating on a timestamp match.
+
+Two detectors:
+
+- ``detect_continuation_parent`` — the modern ``compact_boundary`` case: CC opens
+  the post-compaction file with a boundary line + a user message pointing at the
+  parent session's ``.jsonl`` path. Pull the parent UUID, resolve its thread.
+- ``find_thread_by_first_message`` — older no-boundary compactions replay the whole
+  conversation with fresh UUIDs (a strict prefix-superset of the parent). A *fork*
+  shares a prefix then diverges; the prefix-consistency walk tells them apart.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Optional
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from .._store import Event
+from ._state import lookup_parent_thread
+from ._titles import _user_content_texts
+
+if TYPE_CHECKING:
+    from thread_archive._thread_import.parsers.claude_code import ClaudeCodeParser
+
+_PARENT_JSONL_RE = re.compile(r"/([0-9a-f-]{36})\.jsonl")
+
+
+def detect_continuation_parent(
+    session: Session, lines: list[dict], source_id: str
+) -> Optional[int]:
+    """If this is a ``compact_boundary`` continuation, return the parent thread_id."""
+    has_boundary = any(line.get("subtype") == "compact_boundary" for line in lines[:3])
+    if not has_boundary:
+        return None
+
+    project_prefix = source_id.rsplit(":", 1)[0]
+    for line in lines[:5]:
+        if line.get("type") != "user":
+            continue
+        for txt in _user_content_texts(line.get("message", {}).get("content", "")):
+            match = _PARENT_JSONL_RE.search(txt)
+            if match:
+                parent_source_id = f"{project_prefix}:{match.group(1)}"
+                return lookup_parent_thread(session, parent_source_id)
+    return None
+
+
+def find_thread_by_first_message(
+    session: Session, lines: list[dict], parser: "ClaudeCodeParser", builder
+) -> Optional[int]:
+    """Find an existing thread this session is a no-boundary *continuation* of.
+
+    Match the first user message's **content + timestamp** (content-only over-merges
+    distinct sessions that happen to share a first message), then require prefix-
+    consistency across the whole user-message overlap (a fork diverges → reject) and
+    that the incoming session is at least as long as the candidate (a strict prefix is
+    a not-yet-diverged fork → reject). Returns the thread to merge into, else None.
+
+    The first message's ``occurred_at`` is taken from a probe build of that message —
+    the deterministic parse of its source timestamp — so it matches the value the
+    original import stored through the same column processor."""
+    session_data = {
+        "provider": "claude-code",
+        "sessions": [{"session_id": "check", "project": "check", "lines": lines[:2000]}],
+    }
+    try:
+        messages = parser.parse_export(session_data)
+    except Exception:
+        return None
+
+    incoming_users = [
+        m.get("content_text", "")
+        for m in messages
+        if m.get("role") == "user" and m.get("content_text")
+    ]
+    if not incoming_users:
+        return None
+    first_content = incoming_users[0]
+
+    first_msg = next(
+        (m for m in messages if m.get("role") == "user" and m.get("content_text") == first_content),
+        None,
+    )
+    probe = builder.build_events(first_msg, "probe") if first_msg is not None else []
+    anchor = next((e for e in probe if e.event_type == "user_message_sent"), None)
+    if anchor is None:
+        return None
+
+    content_col = func.json_extract(Event.payload, "$.content")
+    candidate = session.execute(
+        select(Event.thread_id)
+        .where(
+            Event.event_type == "user_message_sent",
+            content_col == first_content,
+            Event.occurred_at == anchor.occurred_at,
+        )
+        .order_by(Event.id)
+        .limit(1)
+    ).scalar()
+    if candidate is None:
+        return None
+
+    parent_users = session.execute(
+        select(content_col)
+        .where(Event.thread_id == candidate, Event.event_type == "user_message_sent")
+        .order_by(Event.occurred_at, Event.id)
+    ).scalars().all()
+    # Prefix-consistency: any mismatch over the overlap → fork, not a continuation.
+    if any(inc != par for inc, par in zip(incoming_users, parent_users)):
+        return None
+    # A real no-boundary continuation replays the parent's whole history then adds
+    # more, so it's a superset; a strict prefix is a not-yet-diverged fork.
+    if len(incoming_users) < len(parent_users):
+        return None
+    return candidate
+
+
+def resolve_continuation_thread(
+    session: Session, lines: list[dict], source_id: str, parser: "ClaudeCodeParser", builder
+) -> Optional[int]:
+    """The parent thread to merge this session into (boundary parent, else
+    first-message superset), or None when it's a genuinely new/forked session."""
+    parent = detect_continuation_parent(session, lines, source_id)
+    if parent is not None:
+        return parent
+    return find_thread_by_first_message(session, lines, parser, builder)

thread_archive/_importers/_cursor.py

@@ -0,0 +1,103 @@
+"""The append-proving cursor for the JSONL line-stream importers.
+
+A file watermark has to answer one question: *are the lines I already imported still
+the first lines of this file?* Size alone cannot answer it. A rewritten line of the
+same serialized length, a truncate-and-regrow between polls, or a malformed line
+repaired in place all leave the size equal or larger while the content underneath the
+cursor changed — and a line-count cursor then indexes into content that no longer
+means what it meant, skipping the difference for good.
+
+So the watermark carries a **digest of the exact bytes it was computed over**
+(``ImportState.last_content_hash``, the sha256 of the whole file as of that import).
+On the next poll we hash the current file's first ``last_file_size`` bytes: match ⇒
+the file was only appended to, and the line cursor is still valid; mismatch (or a
+file now shorter than the watermark) ⇒ the source was rewritten, so we rewind to line
+0 and re-import the whole thing. The ``dedup_key`` membership check collapses
+everything already held, so a rewind costs work, never duplicates.
+
+That one check subsumes several silent-loss modes at once: same-size rewrites, a
+shrink, and — the sharp one — the *logical* line cursor drifting out of step with the
+file. ``read_session_lines`` drops malformed lines, so the cursor counts parsed lines,
+not physical ones; repairing a malformed line in the middle of a file shifts every
+later line's index and the tail slice would silently skip a turn. A repair changes the
+prefix bytes, so it rewinds instead.
+
+A torn final line — a poll catching the writer mid-append — is *not* a rewrite: the
+partial bytes are a prefix of the completed line, so the digest still matches and the
+unparsed tail simply imports on the next poll.
+
+Watermarks written before this hash existed carry ``last_content_hash = None``: they
+can't be verified, so they keep the old size-only behavior for exactly one poll and
+are backfilled with a digest as they go (a blanket rewind of every source would be a
+correct but pointlessly expensive way to learn nothing).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+from .._store import ImportState
+
+logger = logging.getLogger(__name__)
+
+
+def content_digest(data: bytes) -> str:
+    """The watermark's proof-of-content: sha256 of the bytes the cursor covers."""
+    return hashlib.sha256(data).hexdigest()
+
+
+@dataclass(frozen=True)
+class SourceCursor:
+    """Where to resume in a re-read source file, and the digest to watermark it with.
+
+    ``unchanged`` = byte-identical to the last import (nothing to do). ``rewound`` =
+    the source was rewritten under us, so ``start_line`` is 0 and the whole file
+    re-imports.
+    """
+
+    start_line: int
+    content_hash: str
+    unchanged: bool = False
+    rewound: bool = False
+
+
+def resolve_source_cursor(
+    state: Optional[ImportState], data: bytes, *, source: str, source_id: str
+) -> SourceCursor:
+    """Resolve where this poll should resume in ``data`` (see the module docstring)."""
+    size = len(data)
+    digest = content_digest(data)
+
+    if state is None:
+        return SourceCursor(start_line=0, content_hash=digest)
+
+    start_line = state.last_line_count
+    last_size = state.last_file_size
+
+    if not state.last_content_hash:
+        # Unverifiable pre-digest watermark: trust size for one more poll, and stamp a
+        # digest so the next one is provable.
+        if size == last_size:
+            return SourceCursor(start_line, digest, unchanged=True)
+        if size < last_size:
+            return _rewind(source, source_id, f"source shrank ({last_size} → {size} bytes)", digest)
+        return SourceCursor(start_line, digest)
+
+    if size == last_size and digest == state.last_content_hash:
+        return SourceCursor(start_line, digest, unchanged=True)
+    if size < last_size:
+        return _rewind(source, source_id, f"source shrank ({last_size} → {size} bytes)", digest)
+    if content_digest(data[:last_size]) != state.last_content_hash:
+        return _rewind(source, source_id, "content under the cursor changed", digest)
+    return SourceCursor(start_line, digest)
+
+
+def _rewind(source: str, source_id: str, why: str, digest: str) -> SourceCursor:
+    logger.warning(
+        "%s %s: %s — rewinding cursor, re-importing from line 0 (dedup collapses what we hold)",
+        source, source_id, why,
+    )
+    return SourceCursor(start_line=0, content_hash=digest, rewound=True)

thread_archive/_importers/_events.py

@@ -0,0 +1,244 @@
+"""The shared parse/build → dedup → write loop.
+
+Every provider's import is the same loop: walk NormalizedMessages, mint a stream id
+per user turn (the following assistant turns reuse it), build events via
+``DefaultEventBuilder`` with monotonic timestamp inheritance, and write. That loop
+lives in one function, :func:`assemble_events`.
+
+Idempotence is enforced on the ``dedup_key`` the builder computes (timestamp-free,
+content-inclusive, scoped per thread). A re-import — even one that re-reads
+already-imported lines after a watermark loss — adds nothing.
+
+A turn straddles polls: the user line can land in one poll and its assistant reply in
+the next. So both of the loop's carried anchors are seeded from what the thread
+already holds — the stream id (:func:`_last_stream_id`) and, for the providers that
+pass it, the timestamp (``base_prev_ts``). Without that seed the continuing assistant
+turn would open its own stream and orphan itself from the user turn it answers.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import datetime
+from typing import Iterable, Optional
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from thread_archive._thread_import import DefaultEventBuilder
+
+from .._store import Event
+from .._truth import write_events
+
+logger = logging.getLogger(__name__)
+
+# SQLite's default host-parameter ceiling is 999; stay well under it per IN (...).
+_KEY_CHUNK = 500
+
+
+def _existing_dedup_keys(
+    session: Session, thread_id: int, keys: Optional[Iterable[str]] = None
+) -> set[str]:
+    """Which of ``keys`` the thread already holds — or *all* its keys when ``keys``
+    is None.
+
+    The import loop asks only about the keys it built this pass. Loading every key in
+    the thread instead makes each poll of a long session pay for the whole session's
+    history, which is the shape of quadratic work on a transcript that grows by a line
+    at a time.
+    """
+    stmt = select(Event.dedup_key).where(
+        Event.thread_id == thread_id, Event.dedup_key.is_not(None)
+    )
+    if keys is None:
+        return set(session.execute(stmt).scalars().all())
+
+    candidates = list(keys)
+    found: set[str] = set()
+    for i in range(0, len(candidates), _KEY_CHUNK):
+        chunk = candidates[i : i + _KEY_CHUNK]
+        found.update(session.execute(stmt.where(Event.dedup_key.in_(chunk))).scalars().all())
+    return found
+
+
+def _last_stream_id(session: Session, thread_id: int) -> Optional[str]:
+    """The stream id of the thread's newest event — the open turn a continuing
+    assistant message belongs to. None on a thread with no events yet."""
+    return session.execute(
+        select(Event.stream_id)
+        .where(Event.thread_id == thread_id)
+        .order_by(Event.id.desc())
+        .limit(1)
+    ).scalars().first()
+
+
+def _anchor_event(events: list, event_type: str):
+    """The content-bearing anchor event of a built message (the user_message_sent
+    of a user turn, the api_request_completed of an assistant turn), or None."""
+    for ev in events:
+        if ev.event_type == event_type:
+            return ev
+    return None
+
+
+def _message_already_present(session: Session, thread_id: int, anchor) -> bool:
+    """True when an event with the same (type, content, occurred_at) already exists
+    in the thread. Used to suppress the replayed prefix when a CC continuation /
+    fork-resume merges into an existing thread (its fresh UUIDs defeat the dedup_key
+    check). The built ``anchor.occurred_at`` is the deterministic parse of the source
+    line's timestamp, so passing it as a bind param matches the value the original
+    import stored through the same column processor — robust across tz/format."""
+    if anchor is None:
+        return False
+    content = anchor.payload.get("content")
+    if content is None:
+        return False
+    return session.execute(
+        select(Event.id)
+        .where(
+            Event.thread_id == thread_id,
+            Event.event_type == anchor.event_type,
+            func.json_extract(Event.payload, "$.content") == content,
+            Event.occurred_at == anchor.occurred_at,
+        )
+        .limit(1)
+    ).first() is not None
+
+
+def _to_event(thread_id: int, te) -> Event:
+    """Map a portable ThreadEvent onto an Event row (thread_id added at write time)."""
+    return Event(
+        thread_id=thread_id,
+        stream_id=te.stream_id,
+        api_call_id=te.api_call_id,
+        event_type=te.event_type,
+        payload=te.payload,
+        occurred_at=te.occurred_at,
+        correlation_id=te.correlation_id,
+        dedup_key=te.dedup_key,
+    )
+
+
+def assemble_events(
+    session: Session,
+    thread_id: int,
+    messages: list,
+    builder: DefaultEventBuilder,
+    *,
+    base_prev_ts: Optional[datetime] = None,
+    cross_pass_dedup: bool = False,
+) -> tuple[int, Optional[str]]:
+    """Build events from NormalizedMessages and write the not-yet-seen ones.
+
+    ``base_prev_ts`` seeds the timestamp-inheritance anchor (grok/opencode seed it
+    from the newest persisted event so a later incremental pass doesn't sort to the
+    top of the thread). Returns ``(events_created, last_message_uuid)``.
+
+    ``cross_pass_dedup`` adds a message-level (content + timestamp) existence check
+    on top of the dedup_key membership check. It is enabled only when merging a CC
+    continuation / fork-resume into an existing thread, where the replayed prefix
+    carries fresh UUIDs (so its dedup_keys won't match) but identical content +
+    timestamps. A matched user turn is skipped along with its following assistant
+    turns (until the next genuinely-new user turn), mirroring canonical.
+    """
+    if not messages:
+        return 0, None
+
+    last_uuid: Optional[str] = None
+    prev_occurred_at: Optional[datetime] = base_prev_ts
+    # Seed from the thread's open turn so an assistant reply that arrives in a later
+    # poll than its user line joins that turn instead of stranding itself in a new one.
+    current_stream_id: Optional[str] = _last_stream_id(session, thread_id)
+
+    built: list[tuple[str, list]] = []
+    for msg in messages:
+        role = msg.get("role", "")
+        # The parser emits the provider id as `provider_message_id`; older CC line
+        # dicts use `uuid`. Track whichever is present.
+        message_id = msg.get("uuid") or msg.get("provider_message_id")
+        if message_id:
+            last_uuid = message_id
+
+        if role == "user":
+            current_stream_id = str(uuid.uuid4())
+            events = builder.build_events(msg, current_stream_id, prev_occurred_at=prev_occurred_at)
+        elif role == "assistant":
+            if not current_stream_id:
+                current_stream_id = str(uuid.uuid4())
+            events = builder.build_events(
+                msg, current_stream_id, str(uuid.uuid4()), prev_occurred_at=prev_occurred_at
+            )
+        else:
+            # 'system', or a role the builder doesn't specifically model (tool/function/
+            # developer/model/… from non-CC harnesses). Preserve the turn, don't drop it.
+            events = builder.build_events(
+                msg, current_stream_id or str(uuid.uuid4()), prev_occurred_at=prev_occurred_at
+            )
+
+        if events:
+            # Advance the anchor even for deduped messages so a later new message
+            # inherits a monotonic time (never a silent now()).
+            prev_occurred_at = events[-1].occurred_at
+        built.append((role, events))
+
+    seen = _existing_dedup_keys(
+        session, thread_id, {te.dedup_key for _, evs in built for te in evs if te.dedup_key}
+    )
+    batch: list[Event] = []
+    skip_until_next_user = False
+
+    for role, events in built:
+        # Cross-pass message-level dedup (continuation/fork merge only): skip a turn
+        # whose anchor (content + timestamp) is already in the thread.
+        if cross_pass_dedup:
+            if role == "user":
+                skip_until_next_user = _message_already_present(
+                    session, thread_id, _anchor_event(events, "user_message_sent")
+                )
+                if skip_until_next_user:
+                    continue
+            elif role == "assistant":
+                if skip_until_next_user:
+                    continue
+                if _message_already_present(
+                    session, thread_id, _anchor_event(events, "api_request_completed")
+                ):
+                    continue
+
+        for te in events:
+            if te.dedup_key and te.dedup_key in seen:
+                continue
+            if te.dedup_key:
+                seen.add(te.dedup_key)
+            batch.append(_to_event(thread_id, te))
+
+    if batch:
+        write_events(session, batch)
+        # Index the new events into the FTS surface in the same transaction, so
+        # search stays current without a full rebuild and FTS commits atomically
+        # with the events + truth log.
+        from .._retrieval.fts import index_events
+
+        index_events(session, batch)
+    return len(batch), last_uuid
+
+
+def import_lines(
+    session: Session,
+    thread_id: int,
+    lines: list[dict],
+    parser,
+    builder: DefaultEventBuilder,
+    *,
+    source: str = "claude-code",
+    source_id: str = "",
+    cross_pass_dedup: bool = False,
+) -> tuple[int, Optional[str]]:
+    """Claude Code: parse a line bundle via the thread_import parser, then assemble."""
+    session_data = {
+        "provider": "claude-code",
+        "sessions": [{"session_id": "incremental", "project": "incremental", "lines": lines}],
+    }
+    messages = parser.parse_export(session_data)
+    return assemble_events(session, thread_id, messages, builder, cross_pass_dedup=cross_pass_dedup)