cctally 1.72.0 → 1.74.0

package/bin/_lib_codex_conversation_watch.py

@@ -0,0 +1,323 @@
+"""Pure directory-frontier kernel for Codex live-tail child discovery (spec §5.4).
+
+Layout-agnostic, budget-bounded, incremental discovery of brand-new Codex
+rollout files that no table yet knows — the second of the two live-tail child-
+discovery layers (the first being the driver's DB re-resolve of the watched
+conversation's file set). This module has NO I/O of its own: the filesystem
+``scandir`` / directory-``mtime`` / file-``size`` reads and the clock are
+injected as callables, so the whole cycle is unit-testable without a real tree,
+real timing, or a DB. The thin SSE driver in
+``bin/_cctally_dashboard_conversation.py`` owns the DB re-resolve, the targeted
+ingest of the paths this kernel surfaces, and the child classification that
+feeds ``reap``; this kernel owns only the directory frontier, the pending-
+candidate set, and the shared per-cycle operation budget.
+
+All six §5.4 bullets are contract:
+
+1. **walk_root-only seed.** The frontier index starts as JUST the configured
+   ``CodexProviderRoot.walk_root`` — construction walks nothing. Directories are
+   discovered incrementally as the frontier is enumerated.
+2. **One shared per-cycle operation budget** covering directory ``stat``s,
+   directory enumerations, and pending-candidate ``stat``s, with round-robin
+   fairness across the three work classes and rotating continuation cursors, so
+   a large tree or a large candidate population can neither starve the frontier
+   nor blow the cycle's ceiling. Every known directory / candidate is
+   *eventually* visited — not all of them every cycle.
+3. **Re-enumeration on own-mtime change** or new frontier membership — never on
+   an ancestor's mtime (POSIX/APFS bumps only the immediate parent's mtime on
+   entry creation, so ancestor-mtime pruning would be unsound).
+4. **Symlink boundary.** Descendant directory/file entries are traversed with
+   ``follow_symlinks=False`` semantics: a symlinked entry is NEVER traversed, so
+   every directory the frontier reaches is connected to ``walk_root`` by a chain
+   of physical (non-symlink) parent links and therefore stays physically inside
+   the canonical ``walk_root`` — the realpath-containment guarantee, achieved
+   structurally. The configured ``walk_root`` spelling itself is preserved (it is
+   the seed and is never realpath-rewritten), matching discovery's configured-
+   spelling-vs-physical distinction.
+5. **Rotation watermark pinned to rotation-start.** A "rotation" is one full pass
+   of the stat cursor over the frontier. The completed-rotation watermark
+   advances only when a rotation completes and is pinned to that rotation's
+   START time, so an entry created mid-rotation (which changes its own
+   directory's mtime) is re-examined on the next rotation.
+6. **Pending candidates.** Every newly discovered file joins ``pending`` BEFORE
+   its first ingest attempt (so a discovered file is never lost even if its
+   first ingest is dirty/lock-contended and leaves no cursor row). A path is
+   retried while unclassified: with no committed cursor it is surfaced every
+   time it is visited; with a committed cursor it is surfaced only when its size
+   exceeds that cursor (an incomplete-``session_meta`` tail completing without
+   any directory-mtime change). A path leaves the set when the driver ``reap``s
+   it (it gained a thread row — child or non-child), when it vanishes, or on a
+   bounded per-candidate expiry (handed to the next full sync).
+"""
+from __future__ import annotations
+
+import os
+
+
+# ── production-default injected callables ─────────────────────────────────────
+
+
+def default_scandir(dirpath):
+    """Yield ``(name, path, is_dir, is_symlink)`` for the entries of ``dirpath``.
+
+    ``is_dir`` uses ``follow_symlinks=False`` (a symlink-to-dir reads as NOT a
+    dir), and ``is_symlink`` flags any symlink so the frontier can refuse to
+    traverse it. Returns ``[]`` on any ``OSError`` (vanished / permission)."""
+    out = []
+    try:
+        with os.scandir(dirpath) as it:
+            for de in it:
+                try:
+                    is_sym = de.is_symlink()
+                    is_dir = de.is_dir(follow_symlinks=False)
+                except OSError:
+                    continue
+                out.append((de.name, de.path, is_dir, is_sym))
+    except OSError:
+        return []
+    return out
+
+
+def default_dir_mtime(dirpath):
+    """The directory's own mtime (``st_mtime_ns``), or ``None`` if it can't be
+    stat'd. Follows a symlinked ``walk_root`` (the seed is intentionally the
+    configured spelling)."""
+    try:
+        return os.stat(dirpath).st_mtime_ns
+    except OSError:
+        return None
+
+
+def default_file_size(filepath):
+    """Regular-file size in bytes, or ``None`` if the path is gone or not a
+    regular file (size-only, matching sync_codex_cache's append-only delta)."""
+    try:
+        st = os.stat(filepath)
+    except OSError:
+        return None
+    import stat as _stat
+    if not _stat.S_ISREG(st.st_mode):
+        return None
+    return st.st_size
+
+
+_SENTINEL = object()
+
+
+class CodexChildFrontier:
+    """The budgeted directory frontier + pending-candidate set for one watched
+    Codex conversation's root (spec §5.4). See the module docstring for the
+    contract. ``cycle`` is the only per-tick entry point; ``reap`` is called by
+    the driver after a targeted ingest classifies discovered candidates."""
+
+    def __init__(
+        self,
+        walk_root,
+        *,
+        op_budget: int = 64,
+        pending_expiry_cycles: int = 50,
+        scandir_fn=default_scandir,
+        dir_mtime_fn=default_dir_mtime,
+        file_size_fn=default_file_size,
+        clock_fn=None,
+    ):
+        self._walk_root = str(walk_root)
+        self._op_budget = max(1, int(op_budget))
+        self._pending_expiry = max(1, int(pending_expiry_cycles))
+        self._scandir = scandir_fn
+        self._dir_mtime = dir_mtime_fn
+        self._file_size = file_size_fn
+        self._clock = clock_fn or (lambda: 0)
+
+        # Frontier index — seeded with JUST walk_root (no enumeration at start).
+        self._dirs: list[str] = [self._walk_root]
+        self._dir_set: set[str] = {self._walk_root}
+        # dir -> mtime observed when it was last enumerated (absent => never).
+        self._enum_mtime: dict[str, int] = {}
+        # dirs awaiting a scandir, each carried with the mtime that triggered it.
+        self._enum_queue: list[tuple[str, int]] = []
+
+        # Pending candidates: path -> age (cycles since registration).
+        self._pending: dict[str, int] = {}
+
+        # Rotating continuation cursors (persist across cycles).
+        self._stat_cursor = 0
+        self._pending_rr = 0                 # where the pending sweep resumes
+        self._rotation_start = None
+        self._completed_rotation_watermark = None
+        self._rotation_count = 0
+
+    # ── introspection (tests / diagnostics) ──────────────────────────────────
+
+    def known_directories(self) -> set[str]:
+        return set(self._dir_set)
+
+    def pending_candidates(self) -> set[str]:
+        return set(self._pending)
+
+    @property
+    def rotation_watermark(self):
+        return self._completed_rotation_watermark
+
+    # ── driver feedback ───────────────────────────────────────────────────────
+
+    def reap(self, classified_paths) -> None:
+        """Drop pending candidates the driver has classified (they gained a
+        thread row — child or non-child). A child is now in the watched file set
+        and tailed by the main loop; a non-child needs no further attention."""
+        for p in classified_paths:
+            self._pending.pop(p, None)
+
+    # ── one discovery cycle ───────────────────────────────────────────────────
+
+    def cycle(self, *, known_paths, committed_sizes) -> set[str]:
+        """One budgeted discovery cycle (§5.4).
+
+        ``known_paths`` — every path already tracked in ``codex_session_files``,
+        so a newly enumerated file already known to some table is not
+        re-registered. ``committed_sizes`` — ``{path: size_bytes}`` committed
+        cursors, for the pending-growth check.
+
+        Returns the set of candidate paths to targeted-ingest this cycle (new
+        discoveries whose first ingest hasn't landed + pending retries that grew
+        or remain unclassified). Bounded to ``op_budget`` filesystem operations,
+        round-robin fair across directory stats, enumerations, and pending
+        checks."""
+        self._known = set(known_paths)
+        self._committed = committed_sizes or {}
+        ingest: set[str] = set()
+
+        # Start (or continue) a rotation of the stat cursor over the frontier.
+        if self._rotation_start is None or self._stat_cursor >= len(self._dirs):
+            self._begin_rotation()
+
+        # Per-cycle pending sweep window: a stable snapshot of the pending keys
+        # plus a persistent rotating start offset, so a large candidate
+        # population is visited over successive cycles (never all every cycle).
+        self._pending_keys = list(self._pending.keys())
+        self._pending_start = (
+            self._pending_rr % len(self._pending_keys)
+            if self._pending_keys else 0)
+        self._pending_checked = 0
+
+        ops = 0
+        stalled = 0
+        lane_idx = 0
+        while ops < self._op_budget and stalled < 3:
+            lane = lane_idx % 3
+            if lane == 0:
+                did = self._op_stat()
+            elif lane == 1:
+                did = self._op_enum(ingest)
+            else:
+                did = self._op_pending(ingest)
+            if did:
+                ops += 1
+                stalled = 0
+            else:
+                stalled += 1
+            lane_idx += 1
+
+        # Persist the pending rotation offset so the next cycle resumes past the
+        # candidates already visited this cycle (round-robin continuation).
+        if self._pending_keys:
+            self._pending_rr = self._pending_start + self._pending_checked
+
+        self._age_pending()
+        return ingest
+
+    # ── work lanes (each does at most ONE filesystem op per call) ─────────────
+
+    def _op_stat(self) -> bool:
+        """Stat one frontier directory (rotating cursor). A directory that is new
+        to the frontier or whose own mtime changed since its last enumeration is
+        queued for (re-)enumeration (§5.4 bullet 3). Returns True iff it consumed
+        a filesystem op."""
+        if self._stat_cursor >= len(self._dirs):
+            return False
+        d = self._dirs[self._stat_cursor]
+        self._stat_cursor += 1
+        mt = self._dir_mtime(d)                       # 1 fs op
+        if mt is not None:
+            prev = self._enum_mtime.get(d, _SENTINEL)
+            if (prev is _SENTINEL or prev != mt) and not self._is_queued(d):
+                self._enum_queue.append((d, mt))
+        if self._stat_cursor >= len(self._dirs):
+            self._complete_rotation()
+        return True
+
+    def _op_enum(self, ingest: set) -> bool:
+        """Enumerate one queued directory (scandir). Records the pre-enumeration
+        mtime as the dir's baseline (so a create landing during the enumeration
+        is re-examined next rotation), skips symlinked descendants (the
+        ``follow_symlinks=False`` boundary), adds real subdirectories to the
+        frontier, and registers brand-new ``*.jsonl`` files in ``pending`` BEFORE
+        their first ingest — surfacing each for that first ingest attempt in the
+        SAME cycle it is discovered (the pending sweep then owns the retries).
+        Returns True iff it consumed a filesystem op."""
+        if not self._enum_queue:
+            return False
+        d, mt = self._enum_queue.pop(0)
+        entries = self._scandir(d)                    # 1 fs op
+        self._enum_mtime[d] = mt
+        for (name, path, is_dir, is_sym) in entries:
+            if is_sym:
+                continue                              # never traverse a symlink
+            if is_dir:
+                if path not in self._dir_set:
+                    self._dir_set.add(path)
+                    self._dirs.append(path)           # new subdir joins frontier
+            elif path.endswith(".jsonl"):
+                if path not in self._known and path not in self._pending:
+                    self._pending[path] = 0           # register BEFORE first ingest
+                    ingest.add(path)                  # first ingest attempt now
+        return True
+
+    def _op_pending(self, ingest: set) -> bool:
+        """Check one pending candidate (rotating cursor). Vanished → dropped; no
+        committed cursor (brand-new / lock-contended first ingest) → surfaced for
+        (re-)ingest; grown beyond its committed cursor → surfaced. Returns True
+        iff it consumed a filesystem op."""
+        keys = self._pending_keys
+        n = len(keys)
+        while self._pending_checked < n:
+            idx = (self._pending_start + self._pending_checked) % n
+            self._pending_checked += 1
+            p = keys[idx]
+            if p not in self._pending:                # reaped/dropped mid-cycle
+                continue
+            size = self._file_size(p)                 # 1 fs op
+            if size is None:
+                self._pending.pop(p, None)            # vanished → drop
+            else:
+                committed = self._committed.get(p)
+                if committed is None or size > committed:
+                    ingest.add(p)
+            return True
+        return False
+
+    # ── rotation + expiry bookkeeping (no filesystem ops) ─────────────────────
+
+    def _begin_rotation(self) -> None:
+        self._stat_cursor = 0
+        self._rotation_start = self._clock()
+
+    def _complete_rotation(self) -> None:
+        # Pinned to the rotation's START time (§5.4 bullet 5): an entry created
+        # mid-rotation bumps its own directory's mtime and is re-examined next
+        # rotation. The cursor stays at len(_dirs); the next cycle's
+        # _begin_rotation resets it.
+        self._completed_rotation_watermark = self._rotation_start
+        self._rotation_count += 1
+
+    def _is_queued(self, d: str) -> bool:
+        return any(qd == d for (qd, _mt) in self._enum_queue)
+
+    def _age_pending(self) -> None:
+        expired = []
+        for p in list(self._pending.keys()):
+            self._pending[p] += 1
+            if self._pending[p] > self._pending_expiry:
+                expired.append(p)
+        for p in expired:
+            self._pending.pop(p, None)

package/bin/_lib_conversation_dispatch.py

@@ -433,6 +433,34 @@ def _claude_outline(
 # ── Claude adapter: search (§5.6 / §6.2) ──────────────────────────────────────
 
 
+def _claude_search_hit_fields(conn: sqlite3.Connection, session_ids: list) -> dict:
+    """``{session_id: (last_activity_utc, project_label)}`` for the search hits'
+    conversations (§3.7). ``last_activity_utc`` is the conversation's
+    ``MAX(timestamp_utc)`` (conversation-level, explicitly NOT the matched row's
+    own time); ``project_label`` is the session's display-only project attribution.
+    Resolved once per distinct non-empty session id."""
+    sids = [s for s in dict.fromkeys(session_ids) if s]
+    if not sids:
+        return {}
+    last_map: dict = {}
+    placeholders = ",".join("?" for _ in sids)
+    try:
+        for sid, last in conn.execute(
+                f"SELECT session_id, MAX(timestamp_utc) FROM conversation_messages "
+                f"WHERE session_id IN ({placeholders}) GROUP BY session_id", sids):
+            last_map[sid] = last
+    except sqlite3.OperationalError:
+        pass
+    meta = lcq._session_latest_meta_map(conn, sids)
+    attribution_cache: dict = {}
+    out: dict = {}
+    for sid in sids:
+        cwd = meta.get(sid, (None, None))[0]
+        _pk, project_label = _claude_project_attribution(cwd, attribution_cache)
+        out[sid] = (last_map.get(sid), project_label)
+    return out
+
+
 def _claude_search(
     conn: sqlite3.Connection,
     query: str,
@@ -451,16 +479,23 @@ def _claude_search(
         offset = 0
     res = lcq.search_conversations(
         conn, query, kind=kind, limit=limit, offset=max(0, offset))
+    raw_hits = res.get("hits", [])
+    # §3.7 conversation-level fields, resolved once per distinct session.
+    fields = _claude_search_hit_fields(
+        conn, [h.get("session_id") for h in raw_hits])
     hits = []
-    for h in res.get("hits", []):
+    for h in raw_hits:
         sid = h.get("session_id")
         uuid = h.get("uuid")
+        last_act, project_label = fields.get(sid, (None, None))
         hits.append({
             "conversation_key": _mint_claude_conversation_key(sid) if sid else None,
             "item_key": _claude_item_key(sid, uuid) if (sid and uuid) else None,
             "title": h.get("title"),
             "snippet": h.get("snippet"),
             "badges": list(h.get("match_kinds") or []),
+            "last_activity_utc": last_act,
+            "project_label": project_label,
         })
     total = res.get("total", len(hits))
     returned = len(hits)
@@ -536,12 +571,239 @@ def neutral_search(
     effective_speed: str | None = None, limit: int = 20, cursor: str | None = None,
 ) -> dict:
     """Search envelope for one source (§5.6). Search is per-source by
-    construction — the kernels never merge providers."""
+    construction — the kernels never merge providers.
+
+    §4.3 external cursor codec: the ``cursor`` argument is the EXTERNAL
+    (base64url) form and the returned ``page.cursor`` is likewise external — the
+    kernel's raw cursor (a NUL-separated ``conversation_key\\x00item_key`` for
+    Codex; an offset for Claude) never leaves the process. An undecodable incoming
+    cursor raises :class:`InvalidSearchCursor` (the route/CLI maps it to 400 /
+    exit 2)."""
     speed = effective_speed or _DEFAULT_SPEED
+    raw_cursor = decode_search_cursor(cursor) if cursor is not None else None
     if source == "codex":
-        return q.search_codex_conversations(
+        env = q.search_codex_conversations(
             conn, query, kind=kind, effective_speed=speed,
-            limit=limit, cursor=cursor)
-    if source == "claude":
-        return _claude_search(conn, query, kind=kind, limit=limit, cursor=cursor)
-    raise ValueError(f"unknown source: {source!r}")
+            limit=limit, cursor=raw_cursor)
+    elif source == "claude":
+        env = _claude_search(conn, query, kind=kind, limit=limit, cursor=raw_cursor)
+    else:
+        raise ValueError(f"unknown source: {source!r}")
+    page = env.get("page")
+    if isinstance(page, dict) and page.get("cursor") is not None:
+        page["cursor"] = encode_search_cursor(page["cursor"])
+    return env
+
+
+def neutral_events_preflight(conn: sqlite3.Connection, ref: str) -> dict:
+    """Live-tail SSE preflight for a ``v1.`` key (spec §5.2): resolve →
+    normalization authority (Codex) → conversation existence. The ``/events``
+    route answers a non-``ok`` result as plain JSON per §2.3 BEFORE committing
+    any SSE bytes — never a 200-SSE stream with nothing to say.
+
+    Returns a status dict:
+    - ``ok`` — carries ``source`` (``"claude"``/``"codex"``) and ``native_key``
+      for the watch loop's provider-specific mechanics;
+    - ``normalization_pending`` — Codex only, migration 025 not yet stamped (a
+      legitimate empty state → HTTP 200 JSON);
+    - ``not_found`` — an unresolvable/garbage ref, or a resolved ref whose
+      conversation has no rows (→ HTTP 404 JSON).
+
+    Cheap: a resolve + one authority probe + one existence probe — never a full
+    detail assembly. Uniform for both providers (a ``v1.`` Claude key preflights
+    the same way, then reuses the existing Claude mechanics internally)."""
+    cref = resolve_conversation_ref(ref)
+    if cref is None:
+        return {"status": "not_found", "conversation_key": ref}
+    if cref.source == "codex":
+        if not q.codex_normalization_authoritative(conn):
+            return {"status": "normalization_pending",
+                    "conversation_key": cref.conversation_key}
+        if not q.codex_conversation_exists(conn, cref.conversation_key):
+            return {"status": "not_found",
+                    "conversation_key": cref.conversation_key}
+        return {"status": "ok", "conversation_key": cref.conversation_key,
+                "source": "codex", "native_key": cref.native_key}
+    # claude — the bare-session path reached via a v1.claude key.
+    if not lcq.conversation_exists(conn, cref.native_key):
+        return {"status": "not_found", "conversation_key": cref.conversation_key}
+    return {"status": "ok", "conversation_key": cref.conversation_key,
+            "source": "claude", "native_key": cref.native_key}
+
+
+# ── external search-cursor codec (§4.3) ───────────────────────────────────────
+
+
+class InvalidSearchCursor(ValueError):
+    """An external search cursor that is not well-formed unpadded base64url over a
+    UTF-8 kernel cursor (§4.3). The route/CLI maps it to 400 / exit 2."""
+
+
+def encode_search_cursor(raw: str | None) -> str | None:
+    """Encode a raw kernel search cursor to its external unpadded-base64url form
+    (§4.3). ``None`` (no next page) stays ``None``. The kernel cursor embeds a NUL
+    separator for Codex, so the raw value never leaves the process."""
+    if raw is None:
+        return None
+    return base64.urlsafe_b64encode(raw.encode("utf-8")).decode("ascii").rstrip("=")
+
+
+def decode_search_cursor(external: str | None) -> str | None:
+    """Decode an external unpadded-base64url search cursor back to the raw kernel
+    cursor (§4.3). ``None`` stays ``None``; an undecodable value raises
+    :class:`InvalidSearchCursor`."""
+    if external is None:
+        return None
+    if not isinstance(external, str):
+        raise InvalidSearchCursor(external)
+    padded = external + "=" * (-len(external) % 4)
+    try:
+        return base64.urlsafe_b64decode(padded.encode("ascii")).decode("utf-8")
+    except (ValueError, TypeError):
+        raise InvalidSearchCursor(external)
+
+
+# ── S7 entity operations: find / prompts / export / payload (§3) ──────────────
+
+# Shared in-conversation find taxonomy (both providers; byte-equal tuples).
+_FIND_KINDS = lcq._FIND_KINDS
+# The whole-conversation export scope (the only scope a Codex ref accepts, §3.3).
+_EXPORT_DEFAULT_SCOPE = "all"
+
+
+def _claude_find(
+    conn: sqlite3.Connection, session_id: str, conversation_key: str, query: str,
+    *, kind: str, regex: bool, case: bool,
+) -> dict:
+    """Claude ``neutral_find`` adapter (§3.1): wraps ``find_in_conversation`` and
+    re-anchors each uuid anchor to its neutral ``item_key`` — byte-equal to the
+    ones detail serves — so S8's FindBar navigates both providers with one
+    contract. Never emits ``normalization_pending`` (Claude is authoritative)."""
+    res = lcq.find_in_conversation(
+        conn, session_id, query, kind=kind, regex=regex, case=case)
+    if res is None:
+        return {"status": "not_found", "conversation_key": conversation_key}
+    anchors = [
+        {"item_key": _claude_item_key(session_id, a["uuid"]),
+         "match_kinds": a["match_kinds"]}
+        for a in res["anchors"]
+    ]
+    return {
+        "status": "ok", "conversation_key": conversation_key,
+        "total": res["total"], "anchors": anchors,
+        "anchors_truncated": res["anchors_truncated"],
+        "search_depth": res["search_depth"], "kind": res["kind"], "mode": res["mode"],
+    }
+
+
+def _claude_prompts(
+    conn: sqlite3.Connection, session_id: str, conversation_key: str
+) -> dict:
+    """Claude ``neutral_prompts`` adapter (§3.2): wraps ``get_conversation_prompts``
+    and re-anchors each uuid to its neutral ``item_key``."""
+    res = lcq.get_conversation_prompts(conn, session_id)
+    if res is None:
+        return {"status": "not_found", "conversation_key": conversation_key}
+    prompts = [
+        {"item_key": _claude_item_key(session_id, p["uuid"]), "text": p["text"]}
+        for p in res["prompts"]
+    ]
+    return {"status": "ok", "conversation_key": conversation_key, "prompts": prompts}
+
+
+def _claude_export(
+    conn: sqlite3.Connection, session_id: str, conversation_key: str, scope: str
+) -> dict:
+    """Claude ``neutral_export`` adapter (§3.3): wraps ``get_conversation_export``,
+    passing ``scope`` through — all existing Claude scopes keep working unchanged."""
+    md = lcq.get_conversation_export(conn, session_id, scope)
+    if md is None:
+        return {"status": "not_found", "conversation_key": conversation_key}
+    return {"status": "ok", "conversation_key": conversation_key, "markdown": md}
+
+
+def neutral_find(
+    conn: sqlite3.Connection, ref: str, query: str, *, kind: str = "all",
+    regex: bool = False, case: bool = False, effective_speed: str | None = None,
+) -> dict:
+    """In-conversation find for a neutral reference (§3.1). An unknown ``kind``
+    raises ``ValueError`` (route → 400); an unknown/garbage ref → ``not_found``.
+    Find never prices (``effective_speed`` accepted for signature symmetry)."""
+    del effective_speed  # find never prices
+    if kind not in _FIND_KINDS:
+        raise ValueError(f"unknown kind: {kind}")
+    cref = resolve_conversation_ref(ref)
+    if cref is None:
+        return {"status": "not_found", "conversation_key": ref}
+    if cref.source == "codex":
+        return q.find_in_codex_conversation(
+            conn, cref.conversation_key, query, kind=kind, regex=regex, case=case)
+    return _claude_find(
+        conn, cref.native_key, cref.conversation_key, query,
+        kind=kind, regex=regex, case=case)
+
+
+def neutral_prompts(conn: sqlite3.Connection, ref: str) -> dict:
+    """Prompt spine for a neutral reference (§3.2)."""
+    cref = resolve_conversation_ref(ref)
+    if cref is None:
+        return {"status": "not_found", "conversation_key": ref}
+    if cref.source == "codex":
+        return q.codex_conversation_prompts(conn, cref.conversation_key)
+    return _claude_prompts(conn, cref.native_key, cref.conversation_key)
+
+
+def neutral_export(
+    conn: sqlite3.Connection, ref: str, *, scope: str = _EXPORT_DEFAULT_SCOPE,
+    effective_speed: str | None = None,
+) -> dict:
+    """Whole-conversation Markdown export for a neutral reference (§3.3).
+
+    Claude passes ``scope`` through unchanged. The Codex adapter accepts ONLY the
+    default whole-conversation scope; any other scope value for a Codex ref is a
+    ``validation_error`` status (the route/CLI maps it to 400 / exit 2), never a
+    silent fallback."""
+    cref = resolve_conversation_ref(ref)
+    if cref is None:
+        return {"status": "not_found", "conversation_key": ref}
+    if cref.source == "codex":
+        if scope not in (None, _EXPORT_DEFAULT_SCOPE):
+            return {"status": "validation_error",
+                    "conversation_key": cref.conversation_key,
+                    "reason": "scope", "detail": scope}
+        speed = effective_speed or _DEFAULT_SPEED
+        return q.get_codex_conversation_export(
+            conn, cref.conversation_key, effective_speed=speed)
+    return _claude_export(
+        conn, cref.native_key, cref.conversation_key,
+        scope if scope is not None else _EXPORT_DEFAULT_SCOPE)
+
+
+def neutral_payload(
+    conn: sqlite3.Connection, ref: str, *, which: str,
+    tool_use_id: str | None = None, block_key: str | None = None,
+) -> dict:
+    """Full-payload readback for a neutral reference (§3.4).
+
+    Provider-specific selectors: Claude keeps its existing contract (``tool_use_id``
+    + ``which ∈ {input, result}``), Codex uses ``block_key`` + ``which ∈ {call,
+    output}``. Statuses: ``ok`` | ``not_found`` (404) | ``gone`` (410 — the physical
+    record moved/mutated)."""
+    cref = resolve_conversation_ref(ref)
+    if cref is None:
+        return {"status": "not_found", "conversation_key": ref}
+    if cref.source == "codex":
+        if not block_key or which not in ("call", "output"):
+            return {"status": "not_found", "block_key": block_key, "which": which}
+        return q.read_codex_payload(conn, cref.conversation_key, block_key, which)
+    # Claude: tool_use_id + which={input,result}, contract unchanged.
+    if not tool_use_id or which not in ("input", "result"):
+        return {"status": "not_found", "tool_use_id": tool_use_id, "which": which}
+    loc = lcq.locate_tool_payload(conn, cref.native_key, tool_use_id, which)
+    if loc is None:
+        return {"status": "not_found", "tool_use_id": tool_use_id, "which": which}
+    source_path, byte_offset = loc
+    payload = lcq.read_full_payload(source_path, byte_offset, tool_use_id, which)
+    if payload is None:
+        return {"status": "gone", "tool_use_id": tool_use_id, "which": which}
+    return {"status": "ok", **payload}