cctally 1.64.0 → 1.66.0

package/bin/_lib_conversation_query.py

@@ -21,7 +21,7 @@ from datetime import datetime as _datetime, timezone as _timezone
 # Public surface (Plan 2): shipped in the npm tarball + brew formula + public
 # mirror — imported by the dashboard's conversation endpoints at runtime.
 
-from _lib_pricing import _calculate_entry_cost
+from _lib_pricing import _calculate_entry_cost, _chip_for_model
 # #178: the on-demand load-full re-read helper re-stringifies a raw tool_result
 # content block the same way the parser does at ingest — reuse the parser's
 # _stringify so the full (un-capped) result text matches the cached/capped one.
@@ -55,6 +55,65 @@ from _lib_conversation import (
     _strip_remote_control_prefix,
 )
 
+# ── Opt-in phase instrumentation (issue #276, Session C / M5) ────────────────
+# This kernel is imported DIRECTLY by several tests (tests/test_conversation_*),
+# NOT always through cctally._load_sibling, so it must NOT reach through
+# sys.modules["cctally"]._load_sibling("_lib_perf") (Codex F1 — that becomes
+# import-order dependent / KeyErrors when the kernel is loaded standalone). It
+# instead resolves the SHARED _lib_perf instance so the assemble.* sub-tree
+# nests under an endpoint / bench --trace root on the SAME thread-local stack:
+# an `import _lib_perf` first (a hit in sys.modules — set by the dashboard's
+# _perf_gate / bench pin / conftest — or resolvable via bin/ on sys.path), then
+# a __file__-relative path-load registered under "_lib_perf" so later importers
+# reuse it, then a no-op shim so a perf-import failure never breaks assembly.
+import importlib.util as _importlib_util
+import pathlib as _pathlib
+import sys as _sys
+
+
+class _PerfShim:
+    """No-op _lib_perf stand-in: phase() returns a context-manager no-op so the
+    kernel never hard-fails when the sibling is somehow unloadable."""
+
+    class _NullPhase:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *_exc):
+            return False
+
+        def set_count(self, *_a):
+            pass
+
+        def set_meta(self, **_kw):
+            pass
+
+    def phase(self, *_a, **_k):
+        return self._NullPhase()
+
+
+_PERF = None
+
+
+def _perf():
+    """Return the shared _lib_perf collector (near-noop when tracing is off)."""
+    global _PERF
+    if _PERF is None:
+        try:
+            import _lib_perf as _mod
+            _PERF = _mod
+        except Exception:
+            try:
+                _p = _pathlib.Path(__file__).with_name("_lib_perf.py")
+                _spec = _importlib_util.spec_from_file_location("_lib_perf", _p)
+                _mod = _importlib_util.module_from_spec(_spec)
+                _sys.modules.setdefault("_lib_perf", _mod)
+                _spec.loader.exec_module(_mod)
+                _PERF = _mod
+            except Exception:
+                _PERF = _PerfShim()
+    return _PERF
+
 
 _TITLE_MAX = 120
 
@@ -974,9 +1033,13 @@ def _rollup_authoritative(conn) -> bool:
 # last_activity_utc string, so the caller MUST pass UTC-ISO bounds in the same
 # format (...Z) — see bin/_lib_dashboard_dates.parse_filter_date_range.
 _FILTER_KEYS = ("date_from", "date_to", "projects",
-                "cost_min", "cost_max", "rebuild_min")
+                "cost_min", "cost_max", "rebuild_min", "models")
 # The rollup-only axes — the ones the live fallback cannot express. Used to set
 # the page's filter_degraded flag when one is requested under the live branch.
+# NOTE (#278 Theme C): "models" is deliberately NOT here. The model axis is a
+# live session_id IN (…conversation_messages.model…) restriction that applies on
+# BOTH branches, so a model-only filter under a pending rollup still applies and
+# must NEVER set filter_degraded.
 _ROLLUP_ONLY_FILTER_KEYS = ("projects", "cost_min", "cost_max", "rebuild_min")
 
 
@@ -986,7 +1049,50 @@ def _empty_filters() -> dict:
     return {k: None for k in _FILTER_KEYS}
 
 
-def _rollup_where(filters):
+def _model_clause(conn, families):
+    """Resolve a model-family filter to a ``session_id`` predicate fragment
+    (#278 Theme C). Returns ``(clause_sql, params)``:
+
+      * ``families`` falsy (axis ABSENT)         -> ``("", [])``  (no restriction —
+        the byte-stable unfiltered path).
+      * ``families`` present, resolves to ids    -> a ``session_id IN (subquery)``
+        predicate over ``conversation_messages.model``.
+      * ``families`` present, resolves to NO ids -> a match-NOTHING predicate.
+
+    The middle/last split is load-bearing: an axis that is PRESENT but matches no
+    models (a family with no sessions, an 'other'/synthetic-only selection, a
+    typo'd family in a hand-crafted URL) must restrict to ZERO rows, never widen
+    to everything. Family classification goes through ``_chip_for_model`` — the
+    SAME classifier ``list_conversation_facets`` uses — so a family's facet count
+    equals the rows its chip yields, and 'any appearance' semantics + correct
+    'other'-exclusion come for free. 'other' is unreachable as a selectable
+    family (never emitted by the client) and is simply never collected here.
+
+    The fragment ANDs into any WHERE that has a ``session_id`` column, so the
+    IDENTICAL string composes into both the ``conversation_sessions`` rollup and
+    the ``conversation_messages`` live branch verbatim (spec §1)."""
+    if not families:
+        return "", []
+    wanted = set(families)
+    ids = [
+        m for (m,) in conn.execute(
+            "SELECT DISTINCT model FROM conversation_messages "
+            "WHERE model IS NOT NULL AND model != ''"
+        )
+        if _chip_for_model(m) in wanted
+    ]
+    if not ids:
+        # Present-but-empty: match nothing (NOT ("", []) which would be unfiltered).
+        return "session_id IN (SELECT session_id FROM conversation_messages WHERE 0)", []
+    ph = ",".join("?" for _ in ids)
+    return (
+        "session_id IN (SELECT DISTINCT session_id FROM conversation_messages "
+        "WHERE session_id IS NOT NULL AND model IN (%s))" % ph,
+        ids,
+    )
+
+
+def _rollup_where(filters, model_clause=("", [])):
     """(sql_fragment, params) for the ROLLUP branch — all four axes are stored
     columns. Returns (" WHERE ...", [params]) or ("", []) when no axis is set.
     Project IN-list naturally excludes empty/NULL project_label (neither the ''
@@ -997,7 +1103,12 @@ def _rollup_where(filters):
     (``<``) emitted by ``_lib_dashboard_dates.parse_filter_date_range``. The
     strict ``<`` is load-bearing: it makes the lex compare against the stored
     mixed-precision ``last_activity_utc`` (whole-second AND millisecond ``...Z``)
-    chronologically correct at the day edge (review Finding 1)."""
+    chronologically correct at the day edge (review Finding 1).
+
+    ``model_clause`` (#278 Theme C) is the precomputed ``(clause_sql, params)``
+    from ``_model_clause`` — resolved ONCE per request by the caller (which has
+    ``conn``), so ``_rollup_where`` stays connection-free. The model predicate is
+    a ``session_id IN (…)`` fragment that ANDs cleanly into the rollup WHERE."""
     clauses, params = [], []
     if filters["date_from"] is not None:
         clauses.append("last_activity_utc >= ?"); params.append(filters["date_from"])
@@ -1012,6 +1123,9 @@ def _rollup_where(filters):
         clauses.append("cost_usd <= ?"); params.append(filters["cost_max"])
     if filters["rebuild_min"] is not None:
         clauses.append("cache_rebuild_count >= ?"); params.append(filters["rebuild_min"])
+    mc_sql, mc_params = model_clause
+    if mc_sql:
+        clauses.append(mc_sql); params.extend(mc_params)
     return (" WHERE " + " AND ".join(clauses)) if clauses else "", params
 
 
@@ -1060,19 +1174,29 @@ def _resolve_search_session_filter(conn, filters):
     any_axis = any(filters[k] is not None for k in _FILTER_KEYS)
     if not any_axis:
         return "", [], False
+    # #278 Theme C: resolve the model-family clause once and AND it onto whatever
+    # session-scope restriction this returns — including the model-only case
+    # (where the model clause BECOMES the restriction). It applies on BOTH
+    # branches and never degrades (model is not a rollup-only axis).
+    model_clause = _model_clause(conn, filters["models"])
+    mc_sql, mc_params = model_clause
     if _rollup_authoritative(conn):
-        where, params = _rollup_where(filters)
+        where, params = _rollup_where(filters, model_clause)   # model folded in
         return "SELECT session_id FROM conversation_sessions" + where, params, False
-    # Live fallback: only the date axis is expressible over raw messages.
+    # Live fallback: only the date axis + the (live-expressible) model axis apply
+    # over raw messages; the rollup-only axes drop and degrade.
     degraded = any(filters[k] is not None for k in _ROLLUP_ONLY_FILTER_KEYS)
     having, hparams = _live_having(filters)
+    where_extra = (" AND " + mc_sql) if mc_sql else ""
     sub = (
         "SELECT session_id FROM conversation_messages "
-        "WHERE session_id IS NOT NULL GROUP BY session_id" + having)
-    return sub, hparams, degraded
+        "WHERE session_id IS NOT NULL" + where_extra +
+        " GROUP BY session_id" + having)
+    return sub, [*mc_params, *hparams], degraded
 
 
-def _list_session_rows_rollup(conn, order, limit, offset, filters=None):
+def _list_session_rows_rollup(conn, order, limit, offset, filters=None,
+                              model_clause=("", [])):
     """FAST path: read the pre-aggregated rail rows straight from the
     conversation_sessions rollup (spec §3). No GROUP BY, no temp B-tree for the
     ``recent`` sort. Returns (session_id, msg_count, started, last_activity)
@@ -1080,8 +1204,9 @@ def _list_session_rows_rollup(conn, order, limit, offset, filters=None):
     assembly is identical. The optional ``filters`` dict pushes the four-axis
     browse predicate (date/project/cost/rebuild — all stored columns) into the
     WHERE BEFORE LIMIT/OFFSET, so ``has_more``/``next_offset`` stay correct over
-    the filtered set."""
-    where, params = _rollup_where(filters or _empty_filters())
+    the filtered set. ``model_clause`` (#278 Theme C) is the precomputed model
+    predicate folded into the same WHERE."""
+    where, params = _rollup_where(filters or _empty_filters(), model_clause)
     return conn.execute(
         "SELECT session_id, msg_count, "
         "       started_utc AS started, last_activity_utc AS last_activity "
@@ -1092,7 +1217,8 @@ def _list_session_rows_rollup(conn, order, limit, offset, filters=None):
     ).fetchall()
 
 
-def _list_session_rows_live(conn, order, limit, offset, filters=None):
+def _list_session_rows_live(conn, order, limit, offset, filters=None,
+                            model_clause=("", [])):
     """RETAINED fallback (Codex gate BLOCKER 2): the original live GROUP BY over
     conversation_messages, used while the rollup is not authoritative (the flag
     is set — e.g. an existing install before its first sync, or permanently
@@ -1100,38 +1226,81 @@ def _list_session_rows_live(conn, order, limit, offset, filters=None):
     construction; ``order`` here is the _SORTS_LIVE aggregate expression. The
     optional ``filters`` dict applies ONLY the date axis (via HAVING over
     MAX(timestamp_utc)); the rollup-only axes (project/cost/rebuild) cannot be
-    expressed here and are dropped — the caller flags filter_degraded."""
+    expressed here and are dropped — the caller flags filter_degraded.
+
+    ``model_clause`` (#278 Theme C) IS expressible here (the model lives on
+    ``conversation_messages``), so it folds into the WHERE (before GROUP BY) and
+    the axis never degrades. The existing ``session_id IS NOT NULL`` guard ANDs
+    cleanly with the model predicate; ``mc_params`` precede ``hparams`` because
+    the model clause precedes the HAVING in the SQL text."""
     having, hparams = _live_having(filters or _empty_filters())
+    mc_sql, mc_params = model_clause
+    where_extra = (" AND " + mc_sql) if mc_sql else ""
     return conn.execute(
         "SELECT session_id, COUNT(*) AS msg_count, "
         "       MIN(timestamp_utc) AS started, MAX(timestamp_utc) AS last_activity "
         "FROM conversation_messages "
-        "WHERE session_id IS NOT NULL "
+        "WHERE session_id IS NOT NULL" + where_extra + " "
         "GROUP BY session_id"
         + having +
         " ORDER BY " + order + " LIMIT ? OFFSET ?",
-        (*hparams, limit + 1, offset),
+        (*mc_params, *hparams, limit + 1, offset),
     ).fetchall()
 
 
+_MODEL_FAMILY_ORDER = ("opus", "sonnet", "haiku", "fable")  # display order; 'other' excluded
+
+
 def list_conversation_facets(conn) -> dict:
-    """Distinct projects (+ conversation counts) for the browse filter
-    multi-select (spec §2). Reads the rollup; cheap GROUP BY. Empty/NULL
-    project labels are dropped (a no-cwd session stores '' and a not-yet-filled
-    row stores NULL — neither is a real selectable project). Sorted ascending
-    by label so the popover renders a stable list. Returns
-    ``{"projects": [{"project_label": str, "count": int}, ...]}``."""
+    """Distinct projects (+ conversation counts) AND per-model-family session
+    counts for the browse filter multi-selects (spec §2 + #278 Theme C).
+
+    ``projects`` reads the rollup; cheap GROUP BY. Empty/NULL project labels are
+    dropped (a no-cwd session stores '' and a not-yet-filled row stores NULL —
+    neither is a real selectable project). Sorted ascending by label so the
+    popover renders a stable list.
+
+    ``models`` folds distinct ``(session_id, model)`` pairs from
+    ``conversation_messages`` (where ``session_id IS NOT NULL`` — matching the
+    browse/live row sources, so a null-session row can't inflate a count above
+    the filterable sessions) to distinct ``(session_id, family)`` via
+    ``_chip_for_model``, then counts sessions per family. Fold-then-count, NOT
+    sum-of-per-model-distinct: a session that used two Opus point-releases counts
+    ONCE under opus, and an Opus+Haiku session counts under BOTH. Families are
+    emitted present-only, excluding ``other``, in a fixed display order so the
+    popover list is stable — so a family's facet count equals the rows selecting
+    its chip yields (self-consistent with the §1 filter semantics).
+
+    Returns ``{"projects": [{"project_label", "count"}, ...],
+                "models": [{"family", "count"}, ...]}``."""
     rows = conn.execute(
         "SELECT project_label, COUNT(*) FROM conversation_sessions "
         "WHERE project_label IS NOT NULL AND project_label != '' "
         "GROUP BY project_label ORDER BY project_label"
     ).fetchall()
-    return {"projects": [{"project_label": p, "count": n} for p, n in rows]}
+    projects = [{"project_label": p, "count": n} for p, n in rows]
+
+    fam_sessions: dict = {}
+    for sid, model in conn.execute(
+        "SELECT DISTINCT session_id, model FROM conversation_messages "
+        "WHERE session_id IS NOT NULL AND model IS NOT NULL AND model != ''"
+    ):
+        fam = _chip_for_model(model)
+        if fam == "other":
+            continue
+        fam_sessions.setdefault(fam, set()).add(sid)
+    models = [
+        {"family": fam, "count": len(fam_sessions[fam])}
+        for fam in _MODEL_FAMILY_ORDER
+        if fam in fam_sessions
+    ]
+    return {"projects": projects, "models": models}
 
 
 def list_conversations(conn, *, sort="recent", limit=50, offset=0,
                        date_from=None, date_to=None, projects=None,
-                       cost_min=None, cost_max=None, rebuild_min=None) -> dict:
+                       cost_min=None, cost_max=None, rebuild_min=None,
+                       models=None) -> dict:
     """All-history per-session browse rows (spec §3.1). NOT 365-day bounded.
 
     Reads the conversation_sessions rollup (Task A) when it is authoritative —
@@ -1161,12 +1330,18 @@ def list_conversations(conn, *, sort="recent", limit=50, offset=0,
         "cost_min": cost_min,
         "cost_max": cost_max,
         "rebuild_min": rebuild_min,
+        "models": list(models) if models else None,
     }
+    # Resolve the model-family clause ONCE (needs conn; the WHERE builders stay
+    # connection-free). It applies on BOTH branches and never degrades — model is
+    # NOT a rollup-only axis (#278 Theme C).
+    model_clause = _model_clause(conn, filters["models"])
     degraded = False
     sort_degraded = False
     if _rollup_authoritative(conn):
         order = _SORTS.get(sort, _SORTS["recent"])
-        rows = _list_session_rows_rollup(conn, order, limit, offset, filters)
+        rows = _list_session_rows_rollup(conn, order, limit, offset, filters,
+                                         model_clause)
     else:
         order = _SORTS_LIVE.get(sort, _SORTS_LIVE["recent"])
         degraded = any(
@@ -1175,7 +1350,8 @@ def list_conversations(conn, *, sort="recent", limit=50, offset=0,
         # an unknown sort ALSO falls back to recent here (via _SORTS_LIVE.get),
         # but must stay byte-stable, so only the known rollup-only sorts flag it.
         sort_degraded = sort in _DEGRADABLE_SORTS
-        rows = _list_session_rows_live(conn, order, limit, offset, filters)
+        rows = _list_session_rows_live(conn, order, limit, offset, filters,
+                                       model_clause)
     has_more = len(rows) > limit
     rows = rows[:limit]
     session_ids = [r[0] for r in rows]
@@ -1271,10 +1447,21 @@ def _assemble_session(conn, session_id):
     BY CONSTRUCTION (Codex F8 — one grouping pass, never two implementations).
     Returns None for an unknown session.
     """
+    # Opt-in phase instrumentation (issue #276 M5): an outer `assemble` root
+    # wrapping eight structural child seams. Explicit __enter__/__exit__ (not a
+    # `with` re-indent) so the existing body stays byte-for-byte unchanged; each
+    # stage is closed before the next opens, and the identity-aware Phase.__exit__
+    # makes the outer close survive the unknown-session early return. Near-noop
+    # when CCTALLY_PERF_TRACE is off (sp.phase() -> the shared _NULL_PHASE).
+    sp = _perf()
+    _root = sp.phase("assemble"); _root.__enter__()
+    _ph = sp.phase("assemble.read"); _ph.__enter__()
     exists = conn.execute(
         "SELECT 1 FROM conversation_messages WHERE session_id=? LIMIT 1",
         (session_id,)).fetchone()
     if exists is None:
+        _ph.__exit__(None, None, None)
+        _root.__exit__(None, None, None)
         return None
 
     # Pull the session ordered; dedup logical messages by (session_id, uuid),
@@ -1290,7 +1477,9 @@ def _assemble_session(conn, session_id):
         "       source_tool_use_id, stop_reason, attribution_skill, attribution_plugin "
         "FROM conversation_messages WHERE session_id=? "
         "ORDER BY timestamp_utc, id", (session_id,)).fetchall()
+    _ph.set_count(len(raw)); _ph.__exit__(None, None, None)
 
+    _ph = sp.phase("assemble.dedup"); _ph.__enter__()
     seen_uuid = set()
     logical = []   # canonical physical rows, in order
     for row in raw:
@@ -1299,7 +1488,9 @@ def _assemble_session(conn, session_id):
             continue
         seen_uuid.add(u)
         logical.append(row)
+    _ph.set_count(len(logical)); _ph.__exit__(None, None, None)
 
+    _ph = sp.phase("assemble.build"); _ph.__enter__()
     # Group assistant fragments sharing (msg_id, req_id) into one turn item over
     # the WHOLE logical list — NOT by adjacency. Real tool-using transcripts
     # interleave a tool_result (a `user`/tool_result item) between fragments of
@@ -1353,7 +1544,9 @@ def _assemble_session(conn, session_id):
             items.append(it)
             if etype == "assistant":             # null-msg_id assistant: index its uses too
                 _index_tool_uses(it)
+    _ph.set_count(len(items)); _ph.__exit__(None, None, None)
 
+    _ph = sp.phase("assemble.correlate"); _ph.__enter__()
     # ---- Subagent-kind correlation (#166); MUST run before Phase 2 fold ----
     # Reads AND strips (pop) the parser-only keys in one pass, so the returned
     # tool_call/tool_result block shapes are unchanged — the only new output is
@@ -1473,7 +1666,9 @@ def _assemble_session(conn, session_id):
         _entry["parent_subagent_key"] = _owner["subagent_key"]
         _entry["spawn_uuid"] = _owner["anchor"]["uuid"]
         _entry["spawn_tool_use_id"] = _tuid
+    _ph.set_meta(subagents=len(subagent_meta)); _ph.__exit__(None, None, None)
 
+    _ph = sp.phase("assemble.fold"); _ph.__enter__()
     # ---- Phase 2: fold each tool_result item into its owning assistant item ----
     drop = set()                                 # id() of folded placeholder items
     for tr in tool_result_items:
@@ -1545,7 +1740,9 @@ def _assemble_session(conn, session_id):
 
     # ---- Phase 3b: fold the Task* op stream into per-run checklist snapshots ----
     _fold_task_runs(items, task_link)
+    _ph.__exit__(None, None, None)
 
+    _ph = sp.phase("assemble.classify"); _ph.__enter__()
     # ---- Phase 4: classify injected meta items (skill / command / context) ----
     # `meta` rows (the parser's isMeta classification) AND — only while the 005
     # reingest is still pending — not-yet-reingested `human` rows whose body is a
@@ -1620,7 +1817,16 @@ def _assemble_session(conn, session_id):
         _skill_drop.add(id(it))
     if _skill_drop:
         items = [it for it in items if id(it) not in _skill_drop]
-
+    _ph.__exit__(None, None, None)
+
+    _ph = sp.phase("assemble.cost"); _ph.__enter__()
+    # DB-read shape (Codex F4): _turn_cost_map / _turn_usage_map each chunk their
+    # session_entries reads at 400 keys, so a big session is many SELECTs in the
+    # cost stage, not two. Record the key count + both chunk counts.
+    _turn_keys = len(turn_index)
+    _cost_chunks = (_turn_keys + 399) // 400 if _turn_keys else 0
+    _ph.set_meta(turn_keys=_turn_keys, cost_chunks=_cost_chunks,
+                 usage_chunks=_cost_chunks)
     costs = _turn_cost_map(conn, list(turn_index))
     # #177: per-turn token usage from the SAME deduped session_entries row cost
     # uses (a separate map; _turn_cost_map is unchanged for the search path).
@@ -1646,7 +1852,9 @@ def _assemble_session(conn, session_id):
             del it["_req_id"]
             it.pop("_has_prose", None)
     header_cost = round(header_cost, 6)
+    _ph.__exit__(None, None, None)
 
+    _ph = sp.phase("assemble.finalize"); _ph.__enter__()
     # §4 1c — async completion. A background subagent's launch result carries
     # status:"async_launched" and NO totals; completion arrives as a separate
     # <task-notification> meta row (text populated by Phase 4). Join it back, and
@@ -1712,6 +1920,7 @@ def _assemble_session(conn, session_id):
     # order-dependent). Healthy turns get no key (absent, not zero). Shared
     # assembly -> the flag reaches BOTH the reader detail and the outline.
     _stamp_cache_failures(items)
+    _ph.set_count(len(items)); _ph.__exit__(None, None, None)
 
     # Strip the internal Phase-4b threading key from EVERY item (meta/human items
     # carry it too, not just assistant turns) so it never surfaces in the public
@@ -1719,10 +1928,81 @@ def _assemble_session(conn, session_id):
     for it in items:
         it.pop("_source_tool_use_id", None)
 
+    _root.__exit__(None, None, None)
     return {"items": items, "logical": logical,
             "subagent_meta": subagent_meta, "header_cost": header_cost}
 
 
+# --- Assembly memo (issue #278 Theme B) ------------------------------------
+# A tiny thread-safe LRU in FRONT of _assemble_session so the always-open reader
+# stops re-running the full pipeline on every idle SSE tick. Keyed by the
+# conversation_sessions watermark PLUS the #270 session_entries_mutation_seq
+# (the latter catches id-stable cost/token finalization the watermark misses —
+# Codex F1). Bypassed (and cleared) when the rollup is non-authoritative so a
+# destructive reingest can never serve a stale entry under an unchanged
+# watermark (Codex F2). Module-level + threading.Lock, following the
+# _DOCTOR_MEMO precedent (the dashboard is a threading HTTP server).
+import threading as _threading
+from collections import OrderedDict as _OrderedDict
+
+_ASM_MEMO_LOCK = _threading.Lock()
+_ASM_MEMO: "_OrderedDict" = _OrderedDict()   # key -> asm dict
+_ASM_MEMO_CAP = 4                            # main reader + comparison pair + 1 switch
+
+
+def _assemble_memo_clear() -> None:
+    """Drop every memo entry (tests; and the non-authoritative bypass)."""
+    with _ASM_MEMO_LOCK:
+        _ASM_MEMO.clear()
+
+
+def _assemble_memo_key(conn, session_id):
+    """Return (session_id, msg_count, last_activity_utc, entry_mutation_seq), or
+    None to signal 'bypass the memo' — a missing rollup row or an unreadable
+    cache_meta (bare/path-less conn). The caller has already confirmed the
+    rollup is authoritative."""
+    try:
+        row = conn.execute(
+            "SELECT msg_count, last_activity_utc FROM conversation_sessions "
+            "WHERE session_id=?", (session_id,)).fetchone()
+    except sqlite3.OperationalError:
+        return None
+    if row is None:
+        return None
+    try:
+        seq_row = conn.execute(
+            "SELECT value FROM cache_meta "
+            "WHERE key='session_entries_mutation_seq'").fetchone()
+    except sqlite3.OperationalError:
+        return None
+    seq = int(seq_row[0]) if seq_row and seq_row[0] is not None else 0
+    return (session_id, row[0], row[1], seq)
+
+
+def _assemble_session_memoized(conn, session_id):
+    """Memoized _assemble_session. Same return contract (dict or None)."""
+    if not _rollup_authoritative(conn):
+        _assemble_memo_clear()               # Codex F2: no pre-reingest survivors
+        return _assemble_session(conn, session_id)
+    key = _assemble_memo_key(conn, session_id)
+    if key is None:
+        return _assemble_session(conn, session_id)
+    with _ASM_MEMO_LOCK:
+        hit = _ASM_MEMO.get(key)
+        if hit is not None:
+            _ASM_MEMO.move_to_end(key)
+            return hit
+    asm = _assemble_session(conn, session_id)
+    if asm is None:
+        return None                          # don't cache unknown-session negatives
+    with _ASM_MEMO_LOCK:
+        _ASM_MEMO[key] = asm
+        _ASM_MEMO.move_to_end(key)
+        while len(_ASM_MEMO) > _ASM_MEMO_CAP:
+            _ASM_MEMO.popitem(last=False)
+    return asm
+
+
 def get_conversation(conn, session_id, *, after=None, before=None, tail=False,
                      limit=500):
     """Reader payload for one session (spec §3.2). Returns None for an unknown
@@ -1745,8 +2025,18 @@ def get_conversation(conn, session_id, *, after=None, before=None, tail=False,
     if sum(1 for x in (after is not None, before is not None, bool(tail)) if x) > 1:
         raise ValueError("after/before/tail are mutually exclusive")
     limit = max(1, min(int(limit), 1000))
-    asm = _assemble_session(conn, session_id)
+    # Reader-path phases (#276 M5): an outer `conversation.detail` (cursor meta)
+    # nesting the `assemble` sub-tree, plus a `conversation.paginate` child over
+    # the page slice. Explicit __enter__/__exit__ so the multiple early returns
+    # each close cleanly. Near-noop when tracing is off.
+    _rp = _perf()
+    _det = _rp.phase("conversation.detail"); _det.__enter__()
+    _det.set_meta(cursor=("after" if after is not None else
+                          "before" if before is not None else
+                          "tail" if tail else "none"))
+    asm = _assemble_session_memoized(conn, session_id)
     if asm is None:
+        _det.__exit__(None, None, None)
         return None
     items = asm["items"]
     logical = asm["logical"]
@@ -1812,12 +2102,14 @@ def get_conversation(conn, session_id, *, after=None, before=None, tail=False,
     elif before is not None:
         b = _idx(before)
         if b is None:                       # stale cursor → empty page (M1)
+            _det.__exit__(None, None, None)
             return _stale_empty_page()
         end = b
         start = max(0, end - limit)
     elif after is not None:
         a = _idx(after)
         if a is None:                       # stale cursor → empty page (M1)
+            _det.__exit__(None, None, None)
             return _stale_empty_page()
         start = a + 1
         end = min(start + limit, N)
@@ -1825,6 +2117,7 @@ def get_conversation(conn, session_id, *, after=None, before=None, tail=False,
         start = 0
         end = min(limit, N)
 
+    _pg = _rp.phase("conversation.paginate"); _pg.__enter__()
     page = items[start:end]
     has_more = end < N
     has_prev = start > 0
@@ -1838,19 +2131,34 @@ def get_conversation(conn, session_id, *, after=None, before=None, tail=False,
     # item before emit, so a pre-fix row already indexed with raw SGR renders
     # clean (the read-time half of the no-forced-reingest contract). tool_result
     # blocks are EXCLUDED — Bash AnsiText (#177 S3) renders their SGR colors.
+    # #278: page items are shared out of the assembly memo, so build COPIES here
+    # rather than mutating in place. Bounded to <=1000 page items; cheap next to a
+    # full assemble, and it makes the memo provably safe.
+    patched = []
     for it in page:
-        it["anchor"]["session_id"] = session_id
-        if it.get("text"):
-            it["text"] = _strip_ansi(it["text"])
+        nit = dict(it)
+        nit["anchor"] = {**it["anchor"], "session_id": session_id}
+        if nit.get("text"):
+            nit["text"] = _strip_ansi(nit["text"])
+        new_blocks = []
         for b in it["blocks"]:
             if b.get("kind") in ("text", "thinking") and b.get("text"):
-                b["text"] = _strip_ansi(b["text"])
+                nb = dict(b)
+                nb["text"] = _strip_ansi(nb["text"])
+                new_blocks.append(nb)
+            else:
+                new_blocks.append(b)
+        nit["blocks"] = new_blocks
+        patched.append(nit)
+    page = patched
+    _pg.set_count(len(page)); _pg.__exit__(None, None, None)
 
     first = logical[0]
     last = logical[-1]
     # #243: main-session models first (r[6]=model, r[12]=source_path,
     # r[9]=is_sidechain) so opus outranks a haiku subagent, not sorted().
     models = _models_main_first((r[6], r[12], r[9]) for r in logical)
+    _det.__exit__(None, None, None)
     return {
         "session_id": session_id,
         "title": _title,
@@ -1898,7 +2206,7 @@ def get_conversation_outline(conn, session_id):
     every consumer tolerate it. Stats derive from the SAME assembled items the
     reader pages (Codex F8). Returns None for an unknown session.
     """
-    asm = _assemble_session(conn, session_id)
+    asm = _assemble_session_memoized(conn, session_id)
     if asm is None:
         return None
     items, logical = asm["items"], asm["logical"]
@@ -2044,7 +2352,7 @@ def get_conversation_prompts(conn, session_id):
     (the handler's 404 sentinel) — the same contract ``get_conversation_outline``
     uses (``asm is None``).
     """
-    asm = _assemble_session(conn, session_id)
+    asm = _assemble_session_memoized(conn, session_id)
     if asm is None:
         return None
     from _lib_conversation_export import extract_prompt_entries
@@ -2062,7 +2370,7 @@ def get_conversation_export(conn, session_id, scope):
     or ``None`` for an unknown session (the handler's 404 sentinel). ``scope`` is
     pre-validated by the handler (an unknown scope never reaches here)."""
     from _lib_conversation_export import export_session_markdown
-    asm = _assemble_session(conn, session_id)
+    asm = _assemble_session_memoized(conn, session_id)
     if asm is None:
         return None
     items = asm["items"]
@@ -2314,7 +2622,8 @@ def _search_depth(conn) -> str:
 def search_conversations(conn, query, *, limit=50, offset=0,
                          kind="all", fts_available=None,
                          date_from=None, date_to=None, projects=None,
-                         cost_min=None, cost_max=None, rebuild_min=None) -> dict:
+                         cost_min=None, cost_max=None, rebuild_min=None,
+                         models=None) -> dict:
     """Cross-session search (spec §3.3). Uses FTS5 when available (bm25 rank +
     snippet); else a LIKE scan with a manual snippet. Hits deduped by
     (session_id, uuid); each carries the turn's cost. `fts_available` overrides
@@ -2362,6 +2671,10 @@ def search_conversations(conn, query, *, limit=50, offset=0,
         "date_from": date_from, "date_to": date_to,
         "projects": list(projects) if projects else None,
         "cost_min": cost_min, "cost_max": cost_max, "rebuild_min": rebuild_min,
+        # #278 Theme C: the model-family axis, folded in verbatim like projects.
+        # Applies to EVERY search kind via _resolve_search_session_filter, on
+        # both the rollup and live branches, and never degrades.
+        "models": list(models) if models else None,
     }
     filt_sql, filt_params, degraded = _resolve_search_session_filter(conn, filters)
     if degraded:
@@ -3110,7 +3423,7 @@ def find_in_conversation(conn, session_id, query, *, kind="all",
             conn, session_id, q, kind, depth, fts_available)
     if not matched:
         return {**base, "mode": mode}
-    asm = _assemble_session(conn, session_id)
+    asm = _assemble_session_memoized(conn, session_id)
     if asm is None:
         return None
     anchors = _find_anchors_from_matched(asm, matched)