cctally 1.71.0 → 1.73.0

package/bin/_cctally_cache.py

@@ -178,6 +178,11 @@ _should_replace = _lib_jsonl._should_replace
 _lib_conversation = _load_lib("_lib_conversation")
 _iter_message_rows = _lib_conversation.iter_message_rows
 
+# #294 S6: the pure Codex conversation normalization kernel. Pure stdlib leaf
+# (imports only the _lib_conversation / _lib_conversation_query display helpers),
+# so it loads at module-load time alongside _lib_conversation.
+_lib_codex_conversation = _load_lib("_lib_codex_conversation")
+
 # Opt-in backend phase-instrumentation collector (issue #276, Session A). Pure
 # stdlib leaf; near-noop when CCTALLY_PERF_TRACE is unset (phase() returns a
 # shared no-op singleton), so the sync_cache seam wraps below cost nothing on
@@ -320,6 +325,10 @@ _CACHE_MIGRATIONS = _cctally_db_sib._CACHE_MIGRATIONS
 # drop/recreate dance so the per-row delete trigger never fires O(rows) under
 # the held lock on a rebuild / truncation escalation.
 clear_conversation_messages = _cctally_db_sib.clear_conversation_messages
+# #294 S6: storm-free FULL clear of the Codex normalized derived tables (drop
+# triggers -> truncate -> 'delete-all' -> recreate triggers). Used only by the
+# cache-rebuild path + migration 025; partial deletes ride the per-row triggers.
+_codex_conversation_fts_full_clear = _cctally_db_sib._codex_conversation_fts_full_clear
 # cache_meta key/value upsert helper — reused by the resumable reingest cursor
 # writes (#179) so the ON CONFLICT idiom lives in one place. Caller commits.
 _set_cache_meta = _cctally_db_sib._set_cache_meta
@@ -683,6 +692,78 @@ def _discover_codex_files_with_roots() -> list[CodexDiscoveredFile]:
     return discovered
 
 
+def _qualify_codex_targets(only_paths: "set[str]") -> list[CodexDiscoveredFile]:
+    """Resolve each requested path through the ordered configured roots exactly
+    as full discovery would (spec §5.1) — producing the same per-file facts a
+    ``CodexDiscoveredFile`` carries (configured spelling, physical path, provider
+    root, walk root, source-root key) with first-match containment + physical
+    dedup. A path resolving under no configured root, not a ``*.jsonl`` file, or
+    an alias of an already-resolved physical file is DROPPED (clean, not
+    ingested). Targeted mode's analogue of ``_discover_codex_files_with_roots``:
+    it does NOT walk any tree — it qualifies only the caller's exact paths."""
+    roots = _codex_provider_roots()
+    resolved: list[CodexDiscoveredFile] = []
+    seen_physical: set[pathlib.Path] = set()
+    # Deterministic order so first-match physical dedup is stable across a set.
+    for p in sorted(only_paths):
+        candidate = pathlib.Path(p)
+        for root in roots:
+            try:
+                inside = candidate.is_relative_to(root.walk_root)
+            except (ValueError, TypeError):
+                inside = False
+            if not inside:
+                continue
+            # Under this root's walk boundary: it is qualified here (first match)
+            # or dropped — a different-spelled alias never re-qualifies under a
+            # later root, matching full discovery's yielded-source-path identity.
+            if candidate.suffix != ".jsonl" or not candidate.is_file():
+                break  # vanished / non-rollout under this root → drop (clean)
+            physical = _canonical_codex_path(candidate)
+            if physical in seen_physical:
+                break  # first-match physical dedup → drop the alias
+            seen_physical.add(physical)
+            resolved.append(CodexDiscoveredFile(
+                source_path=candidate,
+                physical_path=physical,
+                provider_root=root.provider_root,
+                walk_root=root.walk_root,
+                source_root_key=root.source_root_key,
+            ))
+            break
+    return resolved
+
+
+def _load_codex_session_files_rows(
+    conn: sqlite3.Connection, paths: "list[str]"
+) -> dict:
+    """Cursor rows from ``codex_session_files`` for ONLY the given paths (spec
+    §5.1 — the targeted preload must never load every row like the full-sync
+    path). Same 12-tuple value shape as ``sync_codex_cache``'s full ``existing``
+    map, so the per-file delta logic is byte-identical between the two modes."""
+    out: dict = {}
+    if not paths:
+        return out
+    cols = (
+        "path, size_bytes, mtime_ns, last_byte_offset, "
+        "last_session_id, last_model, last_total_tokens, source_root_key, "
+        "last_native_thread_id, last_root_thread_id, last_parent_thread_id, "
+        "last_conversation_key, last_turn_id"
+    )
+    for i in range(0, len(paths), 400):
+        chunk = paths[i:i + 400]
+        placeholders = ",".join("?" for _ in chunk)
+        for row in conn.execute(
+            f"SELECT {cols} FROM codex_session_files WHERE path IN ({placeholders})",
+            chunk,
+        ):
+            out[row[0]] = (
+                row[1], row[2], row[3], row[4], row[5], row[6], row[7],
+                row[8], row[9], row[10], row[11], row[12],
+            )
+    return out
+
+
 def _delete_codex_file_derived_rows(
     conn: sqlite3.Connection,
     path_str: str,
@@ -711,6 +792,21 @@ def _delete_codex_file_derived_rows(
         "DELETE FROM codex_conversation_threads WHERE source_path = ?" + root_clause,
         params,
     )
+    # #294 S6: normalized rows + file touches for this file. This is a PARTIAL
+    # delete (one file), so it rides the per-row FTS delete trigger — surviving
+    # conversations keep their postings (§3.4 two-path policy). File touches have
+    # no source_root_key column; a source_path maps to exactly one file/root, so
+    # scoping them by source_path alone is exact. Rollups are repaired by the
+    # caller's _recompute_codex_rollups (§3.2), which needs the affected keys
+    # captured BEFORE this delete.
+    conn.execute(
+        "DELETE FROM codex_conversation_file_touches WHERE source_path = ?",
+        (path_str,),
+    )
+    conn.execute(
+        "DELETE FROM codex_conversation_messages WHERE source_path = ?" + root_clause,
+        params,
+    )
     conn.execute(
         "DELETE FROM codex_session_files WHERE path = ?" + root_clause,
         params,
@@ -725,6 +821,10 @@ def _clear_codex_derived_rows(conn: sqlite3.Connection) -> None:
     conn.execute("DELETE FROM codex_conversation_events")
     conn.execute("DELETE FROM codex_session_files")
     conn.execute("DELETE FROM codex_source_roots")
+    # #294 S6: FULL clear of the normalized derived tables (messages + touches +
+    # rollups) via the storm-free helper — this is a whole-corpus rebuild, so
+    # 'delete-all' resets the FTS shadow tables cleanly (§3.4 full-clear path).
+    _codex_conversation_fts_full_clear(conn)
     # F3: this clears the Codex physical quota state, so any stored
     # quota-projection certificate would become stale-valid (its cache
     # sequence unchanged) and let the reconcile short-circuit skip over
@@ -743,6 +843,181 @@ def _bump_codex_physical_mutation_seq(conn: sqlite3.Connection) -> None:
     )
 
 
+# ── #294 S6: normalized-conversation write helpers (kernel-backed) ────────────
+
+_CODEX_NORM_COLS = (
+    "conversation_key, source_root_key, source_path, line_offset, timestamp_utc, "
+    "turn_id, call_id, kind, event_type, record_family, model, text, "
+    "content_digest, content_len, detail_json, search_tool, search_thinking"
+)
+_CODEX_MSG_INSERT_SQL = (
+    "INSERT OR IGNORE INTO codex_conversation_messages (" + _CODEX_NORM_COLS + ") "
+    "VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)"
+)
+
+
+def _codex_conversation_project_attribution(
+    source_root_key: str | None, cwd: object, git_json: object,
+) -> tuple[str | None, str | None]:
+    """(project_key, project_label) for one conversation's thread facts (§3.2).
+
+    Mirrors the S3 read-time attribution (cwd git-root resolution → basename
+    label, else git identity, else unassigned) so the browse live-recompute
+    fallback matches the stored rollup. Degrades to (None, None) when the S3
+    kernel or a valid source root is unavailable — never guesses.
+    """
+    if not source_root_key:
+        return None, None
+    try:
+        from _cctally_source_analytics import _project_label, _git_resolved_key
+        from _lib_source_analytics import opaque_project_key
+    except Exception:
+        return None, None
+    if isinstance(cwd, str) and cwd:
+        project = _resolve_project_key(cwd, "git-root", {})
+        resolved_key = project.bucket_path
+        cwd_label = _project_label(cwd)
+        project_label = (
+            cwd_label if cwd_label in {"(home)", "(root)"}
+            else _project_label(project.display_key)
+        )
+    elif isinstance(git_json, str) and git_json:
+        git_key = _git_resolved_key(git_json)
+        if git_key is None:
+            resolved_key, project_label = "(unassigned)", "(unassigned)"
+        else:
+            resolved_key, project_label = git_key, "Git project"
+    else:
+        resolved_key, project_label = "(unassigned)", "(unassigned)"
+    try:
+        return opaque_project_key("codex", source_root_key, resolved_key), project_label
+    except ValueError:
+        return None, None
+
+
+def _load_codex_normalized_rows(
+    conn: sqlite3.Connection, conversation_key: str,
+) -> list:
+    """Load a conversation's normalized rows (all files) in physical order as
+    kernel CodexNormalizedRow objects."""
+    return [
+        _lib_codex_conversation.CodexNormalizedRow(*row)
+        for row in conn.execute(
+            "SELECT " + _CODEX_NORM_COLS + " FROM codex_conversation_messages "
+            "WHERE conversation_key = ? "
+            "ORDER BY timestamp_utc, source_path, line_offset",
+            (conversation_key,),
+        )
+    ]
+
+
+def _insert_codex_normalized_rows(conn: sqlite3.Connection, rows: list, touches: list) -> None:
+    """Insert normalized rows (INSERT OR IGNORE on the physical key) + their file
+    touches (message linkage resolved via (source_path, line_offset))."""
+    if rows:
+        conn.executemany(_CODEX_MSG_INSERT_SQL, [
+            (r.conversation_key, r.source_root_key, r.source_path, r.line_offset,
+             r.timestamp_utc, r.turn_id, r.call_id, r.kind, r.event_type,
+             r.record_family, r.model, r.text, r.content_digest, r.content_len,
+             r.detail_json, r.search_tool, r.search_thinking)
+            for r in rows
+        ])
+    for touch in touches:
+        conn.execute(
+            "INSERT OR IGNORE INTO codex_conversation_file_touches "
+            "(message_id, conversation_key, source_path, file_path, tool) "
+            "SELECT m.id, ?, ?, ?, ? FROM codex_conversation_messages m "
+            "WHERE m.source_path = ? AND m.line_offset = ?",
+            (touch.conversation_key, touch.source_path, touch.file_path, touch.tool,
+             touch.source_path, touch.line_offset),
+        )
+
+
+def _recompute_codex_rollups(conn: sqlite3.Connection, conversation_keys) -> None:
+    """Recompute-affected-or-delete the rollup for each conversation (§3.2).
+
+    A rollup is a pure function of surviving codex_conversation_messages (+ thread
+    metadata): aggregate across ALL files of the conversation, delete emptied
+    rollups, stamp item_count (rendered LOGICAL items), title, project attribution,
+    times, and models. Called by every write/delete path so no stale rollup
+    survives.
+    """
+    kern = _lib_codex_conversation
+    for conversation_key in {key for key in conversation_keys if key}:
+        rows = _load_codex_normalized_rows(conn, conversation_key)
+        if not rows:
+            conn.execute(
+                "DELETE FROM codex_conversation_rollups WHERE conversation_key = ?",
+                (conversation_key,),
+            )
+            continue
+        item_count = kern.rollup_item_count(rows)
+        title = kern.derive_title(rows)
+        timestamps = [r.timestamp_utc for r in rows if r.timestamp_utc]
+        started = min(timestamps) if timestamps else None
+        last_activity = max(timestamps) if timestamps else None
+        models = sorted({r.model for r in rows if r.model})
+        models_json = json.dumps(models) if models else None
+        source_root_key = rows[0].source_root_key
+        thread = conn.execute(
+            "SELECT cwd, git_json, parent_thread_id, source_root_key "
+            "FROM codex_conversation_threads WHERE conversation_key = ?",
+            (conversation_key,),
+        ).fetchone()
+        cwd = git_json = parent_thread_id = None
+        if thread is not None:
+            cwd, git_json, parent_thread_id, thread_root = thread
+            if thread_root:
+                source_root_key = thread_root
+        project_key, project_label = _codex_conversation_project_attribution(
+            source_root_key, cwd, git_json)
+        conn.execute(
+            "INSERT INTO codex_conversation_rollups "
+            "(conversation_key, source_root_key, parent_thread_id, item_count, "
+            " started_utc, last_activity_utc, project_key, project_label, "
+            " models_json, title) VALUES (?,?,?,?,?,?,?,?,?,?) "
+            "ON CONFLICT(conversation_key) DO UPDATE SET "
+            " source_root_key=excluded.source_root_key, "
+            " parent_thread_id=excluded.parent_thread_id, "
+            " item_count=excluded.item_count, started_utc=excluded.started_utc, "
+            " last_activity_utc=excluded.last_activity_utc, "
+            " project_key=excluded.project_key, project_label=excluded.project_label, "
+            " models_json=excluded.models_json, title=excluded.title",
+            (conversation_key, source_root_key, parent_thread_id, item_count,
+             started, last_activity, project_key, project_label, models_json, title),
+        )
+
+
+def _replay_codex_normalization(conn: sqlite3.Connection) -> None:
+    """Re-derive ALL normalized rows/touches/rollups from stored
+    codex_conversation_events, per file in (source_path ASC, line_offset ASC)
+    order (migration 025). Runs inside the caller's transaction — the caller
+    full-clears first (§3.4 helper) and owns the commit. Deterministic order +
+    the plain rowid alias make a re-run byte-idempotent."""
+    kern = _lib_codex_conversation
+    events_by_file: dict[str, list] = {}
+    order: list[str] = []
+    for row in conn.execute(
+        "SELECT source_path, line_offset, source_root_key, conversation_key, "
+        "native_thread_id, root_thread_id, parent_thread_id, timestamp_utc, "
+        "record_type, event_type, turn_id, call_id, payload_json "
+        "FROM codex_conversation_events "
+        "ORDER BY source_path ASC, line_offset ASC"
+    ):
+        event = _lib_jsonl.CodexPhysicalEvent(*row)
+        if event.source_path not in events_by_file:
+            events_by_file[event.source_path] = []
+            order.append(event.source_path)
+        events_by_file[event.source_path].append(event)
+    affected: set = set()
+    for source_path in order:
+        result = kern.normalize_codex_events(
+            events_by_file[source_path], initial=kern.CodexStickyState())
+        _insert_codex_normalized_rows(conn, result.rows, result.touches)
+        affected.update(r.conversation_key for r in result.rows)
+    _recompute_codex_rollups(conn, affected)
+
+
 def _collect_inactive_codex_paths_and_roots(
     conn: sqlite3.Connection,
     current_file_identities: set[tuple[str, str]],
@@ -863,16 +1138,33 @@ def _write_codex_file_batch(
     last_root_thread_id: str | None,
     last_parent_thread_id: str | None,
     last_conversation_key: str | None,
+    last_turn_id: str | None,
     reset_file: bool,
     accounting_rows: list[tuple[Any, ...]],
     quota_rows: list[tuple[Any, ...]],
     thread_rows: list[tuple[Any, ...]],
     event_rows: list[tuple[Any, ...]],
+    normalized_rows: list,
+    normalized_touches: list,
     active_root_keys: set[str],
+    prune_roots: bool = True,
 ) -> int:
-    """Write one fully-buffered Codex file atomically and return entry changes."""
+    """Write one fully-buffered Codex file atomically and return entry changes.
+
+    ``prune_roots`` gates the whole-tree ``_prune_inactive_codex_source_roots``
+    call: a targeted (only_paths) ingest passes ``False`` so it never deletes a
+    ``codex_source_roots`` row for a root it wasn't asked about (spec §5.1
+    whole-tree bypass — ``active_root_keys`` then covers only the targets)."""
     now_iso = dt.datetime.now(dt.timezone.utc).isoformat()
+    # #294 S6: rollups are recomputed-affected-or-deleted (§3.2), so capture the
+    # conversation keys this file's normalized rows touch BEFORE a reset delete
+    # removes them.
+    affected_keys: set = set()
     if reset_file:
+        affected_keys.update(
+            row[0] for row in conn.execute(
+                "SELECT DISTINCT conversation_key FROM codex_conversation_messages "
+                "WHERE source_path = ?", (path_str,)) if row[0])
         _delete_codex_file_derived_rows(conn, path_str)
     conn.execute(
         """INSERT INTO codex_source_roots
@@ -937,21 +1229,31 @@ def _write_codex_file_batch(
                VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)""",
             event_rows,
         )
+    # #294 S6: normalized rows + file touches ride the same per-file transaction
+    # as the events themselves. INSERT OR IGNORE on the physical key keeps a delta
+    # re-read idempotent; the per-row FTS triggers index them. Then recompute the
+    # rollup for every affected conversation (aggregating across all its files),
+    # deleting emptied rollups. Threads were inserted above, so project
+    # attribution can read them.
+    _insert_codex_normalized_rows(conn, normalized_rows, normalized_touches)
+    affected_keys.update(r.conversation_key for r in normalized_rows)
+    _recompute_codex_rollups(conn, affected_keys)
     conn.execute(
         """INSERT OR REPLACE INTO codex_session_files
            (path, size_bytes, mtime_ns, last_byte_offset, last_ingested_at,
             last_session_id, last_model, last_total_tokens, source_root_key,
             last_native_thread_id, last_root_thread_id, last_parent_thread_id,
-            last_conversation_key)
-           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+            last_conversation_key, last_turn_id)
+           VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
         (
             path_str, size, mtime_ns, final_offset, now_iso, last_session_id,
             last_model, last_total_tokens, discovered.source_root_key,
             last_native_thread_id, last_root_thread_id, last_parent_thread_id,
-            last_conversation_key,
+            last_conversation_key, last_turn_id,
         ),
     )
-    _prune_inactive_codex_source_roots(conn, active_root_keys)
+    if prune_roots:
+        _prune_inactive_codex_source_roots(conn, active_root_keys)
     # A file batch owns accounting, quota, thread, event, root, and cursor
     # facts as one physical unit. Keep the version bump in that same commit so
     # a rolled-back batch never appears newer to the dashboard signature.
@@ -3496,6 +3798,25 @@ class CodexIngestStats:
     lines_malformed: int = 0
     token_events_skipped: int = 0
     skip_reasons: dict = field(default_factory=dict)
+    # #294 S7 targeted (only_paths) live-tail fast-path fields. Default-clean so
+    # every existing only_paths=None caller reads targeted_clean=True and is
+    # otherwise unaffected — the exact Claude ``IngestStats`` semantics (§5.1).
+    # ``deferred_reason`` carries the whole-call preflight decline
+    # (shrink/requalification — Codex's ENTIRE pending-global condition; there is
+    # NO ``cache_meta`` decline-marker tuple, pinned §5.1). ``files_failed``
+    # counts per-file declines (post-preflight late shrink/requalification, I/O,
+    # normalization, DB exception).
+    files_failed: int = 0
+    deferred_reason: "str | None" = None
+
+    @property
+    def targeted_clean(self) -> bool:
+        """True ⇔ a targeted ingest fully applied: not contended, not deferred,
+        and no per-file failure (§5.1). The watch loop emits + advances ``seen``
+        only when this is True — byte-for-byte the Claude ``IngestStats`` rule."""
+        return (not self.lock_contended
+                and self.deferred_reason is None
+                and self.files_failed == 0)
 
 
 def _progress_codex_stderr(stats: CodexIngestStats, *, force: bool = False) -> None:
@@ -3513,8 +3834,10 @@ def sync_codex_cache(
     *,
     progress: Callable[[CodexIngestStats], None] | None = None,
     rebuild: bool = False,
+    only_paths: "set[str] | None" = None,
     lock_timeout: "float | None" = None,
     _on_first_file_rollback: Callable[[], None] | None = None,
+    _on_file_committed: Callable[[str], None] | None = None,
 ) -> CodexIngestStats:
     """Read-through delta ingest of ~/.codex/sessions/**/*.jsonl.
 
@@ -3554,6 +3877,16 @@ def sync_codex_cache(
             stats.lock_contended = True
             return stats
 
+        # #294 S7 targeted (only_paths) live-tail fast path (§5.1). Mutually
+        # exclusive with rebuild (matches the Claude rule). Targeted mode
+        # qualifies ONLY the caller's paths, scopes the cursor preload to them,
+        # and bypasses every whole-tree operation (orphan prune, root prune,
+        # global quota reconcile) — see the guards threaded through below.
+        targeted = only_paths is not None
+        if targeted and rebuild:
+            raise ValueError(
+                "sync_codex_cache: only_paths is incompatible with rebuild")
+
         # F4 (#313): the reconcile trigger gate is "did the Codex physical
         # mutation sequence advance during this sync", NOT rows_changed —
         # rows_changed counts only inserted accounting rows and misses
@@ -3578,9 +3911,13 @@ def sync_codex_cache(
             eprint("[cache-sync] rebuild: cleared Codex cached entries")
 
         # Pure read (glob + is_file only); safe to run before the SELECT and
-        # the per-file loop, where no cache.db write lock may be held.
+        # the per-file loop, where no cache.db write lock may be held. Targeted
+        # mode qualifies ONLY the requested paths — never a tree walk (§5.1).
         with _perf.phase("discover") as _p_disc:
-            files = _discover_codex_files_with_roots()
+            if targeted:
+                files = _qualify_codex_targets(only_paths)
+            else:
+                files = _discover_codex_files_with_roots()
             stats.files_total = len(files)
             _p_disc.set_count(len(files))
 
@@ -3597,7 +3934,7 @@ def sync_codex_cache(
         # ingest (same invariant as the --rebuild clear above). Concurrent
         # processes with different $CODEX_HOME would prune each other; the
         # flock serializes them and that is a pathological configuration.
-        if not rebuild:  # --rebuild already cleared both tables above
+        if not rebuild and not targeted:  # --rebuild already cleared; targeted bypasses
             current_file_identities = {
                 (str(item.source_path), item.source_root_key) for item in files
             }
@@ -3615,7 +3952,14 @@ def sync_codex_cache(
             )
             if orphan_sources or orphan_root_keys:
                 before_prune = conn.total_changes
+                # #294 S6: capture the conversation keys the orphan rows belong to
+                # BEFORE deleting, so the rollups can be repaired/deleted after.
+                orphan_keys: set = set()
                 for orphan_path, orphan_root_key in orphan_sources:
+                    orphan_keys.update(
+                        row[0] for row in conn.execute(
+                            "SELECT DISTINCT conversation_key FROM codex_conversation_messages "
+                            "WHERE source_path = ?", (orphan_path,)) if row[0])
                     _delete_codex_file_derived_rows(
                         conn,
                         orphan_path,
@@ -3626,6 +3970,10 @@ def sync_codex_cache(
                     conn, active_root_keys,
                     candidate_root_keys=orphan_root_keys,
                 )
+                # Recompute-affected-or-delete the rollups the prune touched (§3.2):
+                # a conversation with no surviving rows loses its rollup, one that
+                # survives in another file is recomputed from the survivors.
+                _recompute_codex_rollups(conn, orphan_keys)
                 if conn.total_changes != before_prune:
                     _bump_codex_physical_mutation_seq(conn)
                 conn.commit()
@@ -3641,19 +3989,53 @@ def sync_codex_cache(
         # delta detection consults size alone (Codex rollout JSONLs are
         # append-only, so a size change is a sufficient signal and mtime
         # is prone to clock-skew false-positives).
-        existing = {
-            row[0]: (
-                row[1], row[2], row[3], row[4], row[5], row[6], row[7],
-                row[8], row[9], row[10], row[11],
-            )
-            for row in conn.execute(
-                "SELECT path, size_bytes, mtime_ns, last_byte_offset, "
-                "last_session_id, last_model, last_total_tokens, source_root_key, "
-                "last_native_thread_id, last_root_thread_id, last_parent_thread_id, "
-                "last_conversation_key "
-                "FROM codex_session_files"
-            )
-        }
+        if targeted:
+            # §5.1: the cursor preload queries codex_session_files for the
+            # REQUESTED paths only (the full-sync path loads every row; targeted
+            # must not, so its cost stays proportional to its targets).
+            existing = _load_codex_session_files_rows(
+                conn, [str(item.source_path) for item in files])
+        else:
+            existing = {
+                row[0]: (
+                    row[1], row[2], row[3], row[4], row[5], row[6], row[7],
+                    row[8], row[9], row[10], row[11], row[12],
+                )
+                for row in conn.execute(
+                    "SELECT path, size_bytes, mtime_ns, last_byte_offset, "
+                    "last_session_id, last_model, last_total_tokens, source_root_key, "
+                    "last_native_thread_id, last_root_thread_id, last_parent_thread_id, "
+                    "last_conversation_key, last_turn_id "
+                    "FROM codex_session_files"
+                )
+            }
+
+        # §5.1 whole-call read-only shrink/requalification preflight. Because
+        # ``targeted_clean`` is CALL-wide while the Codex path commits per file,
+        # a shrink/requalification on ANY resolved target declines the whole call
+        # with ZERO mutations (no partial commit where a healthy file's cursor
+        # advances but no event can be emitted). A shrink landing AFTER this
+        # snapshot is caught per-file at its write turn (below). This is Codex's
+        # ENTIRE pending-global condition — there is NO cache_meta decline-marker
+        # tuple (pinned §5.1). A target that vanished between qualification and
+        # here is skipped, not declined — the per-file loop clean-drops it.
+        if targeted:
+            for discovered in files:
+                prev = existing.get(str(discovered.source_path))
+                if prev is None:
+                    continue  # brand-new file: nothing to shrink/requalify
+                prev_size = prev[0]
+                prev_root_key = prev[6]
+                if prev_root_key != discovered.source_root_key:
+                    stats.deferred_reason = "requalification"
+                    return stats
+                try:
+                    cur_size = discovered.source_path.stat().st_size
+                except OSError:
+                    continue  # vanished post-qualify → clean-drop in the loop
+                if cur_size < prev_size:
+                    stats.deferred_reason = "truncation"
+                    return stats
 
         # #279 S2 F4: ONE coarse `walk` phase bracketing the per-file loop
         # (count = files_processed, never per-row — §2 rule). Manual CM so
@@ -3667,6 +4049,8 @@ def sync_codex_cache(
                 st = jp.stat()
             except OSError as exc:
                 eprint(f"[codex-cache] stat failed for {jp}: {exc}")
+                if targeted:
+                    stats.files_failed += 1  # §5.1 I/O decline → call dirty
                 continue
 
             size = st.st_size
@@ -3677,6 +4061,8 @@ def sync_codex_cache(
             initial_session_id: str | None = None
             initial_model: str | None = None
             initial_total_tokens = 0
+            # #294 S6: the sticky-turn resume seed (parallel to initial_model).
+            initial_turn_id: str | None = None
             prev_total_tokens: int | None = None
             prev_native_thread_id: str | None = None
             prev_root_thread_id: str | None = None
@@ -3687,12 +4073,23 @@ def sync_codex_cache(
                 (
                     prev_size, _, prev_offset, prev_sid, prev_model, prev_ttot,
                     prev_root_key, prev_native_thread_id, prev_root_thread_id,
-                    prev_parent_thread_id, prev_conversation_key,
+                    prev_parent_thread_id, prev_conversation_key, prev_turn_id,
                 ) = prev
                 prev_total_tokens = (
                     int(prev_ttot) if prev_ttot is not None else None
                 )
                 requalified = prev_root_key != discovered.source_root_key
+                if targeted and (requalified or size < prev_size):
+                    # §5.1 preflight-snapshot scoped: a shrink or requalification
+                    # landing AFTER the preflight is declined HERE, per file —
+                    # earlier per-file commits in this call stand, the call still
+                    # reports dirty (files_failed → not targeted_clean), so the
+                    # watch advances no cursor and emits nothing, and recovery
+                    # rides the next full sync's per-file reset. Targeted mode
+                    # NEVER runs the full-file offset-0 reset re-ingest (below)
+                    # — that whole-cache-affecting escalation is the full sync's.
+                    stats.files_failed += 1
+                    continue
                 if not requalified and size == prev_size:
                     stats.files_skipped_unchanged += 1
                     continue
@@ -3701,18 +4098,23 @@ def sync_codex_cache(
                     initial_session_id = prev_sid
                     initial_model = prev_model
                     initial_total_tokens = prev_total_tokens or 0
+                    initial_turn_id = prev_turn_id
                 else:
                     truncated = True
                     start_offset = 0
                     initial_session_id = None
                     initial_model = None
                     initial_total_tokens = 0
+                    initial_turn_id = None
                     prev_total_tokens = None
 
             accounting_rows: list[tuple[Any, ...]] = []
             quota_rows: list[tuple[Any, ...]] = []
             thread_rows: list[tuple[Any, ...]] = []
             event_rows: list[tuple[Any, ...]] = []
+            # #294 S6: the physical event objects for this file window, fed to the
+            # normalization kernel after the drain (in offset order).
+            events_list: list = []
             final_offset = start_offset
             # Mutable tracker that the iterator updates on every
             # session_meta / turn_context record, regardless of whether a
@@ -3766,6 +4168,7 @@ def sync_codex_cache(
                         state=iter_state,
                     ):
                         event = emission.event
+                        events_list.append(event)
                         event_rows.append((
                             event.source_path, event.line_offset,
                             event.source_root_key, event.conversation_key,
@@ -3828,6 +4231,8 @@ def sync_codex_cache(
                         stats.skip_reasons[_r] = stats.skip_reasons.get(_r, 0) + _n
             except OSError as exc:
                 eprint(f"[codex-cache] could not read {jp}: {exc}")
+                if targeted:
+                    stats.files_failed += 1  # §5.1 I/O decline → call dirty
                 continue
 
             # Pull terminal session_id/model from the iterator's tracker.
@@ -3872,6 +4277,29 @@ def sync_codex_cache(
                 if terminal_thread is not None else prev_conversation_key
             )
 
+            # #294 S6: normalize this file window's physical events into
+            # normalized rows + file touches, replaying sticky turn/model state
+            # seeded from the persisted resume seed. Buffered before the first DML
+            # (like every other family), so the single retry re-runs the same
+            # in-memory batch. The terminal sticky turn persists as last_turn_id.
+            try:
+                norm_result = _lib_codex_conversation.normalize_codex_events(
+                    events_list,
+                    initial=_lib_codex_conversation.CodexStickyState(
+                        turn_id=initial_turn_id, model=initial_model),
+                )
+            except Exception as exc:  # noqa: BLE001
+                # §5.1: a normalization exception during a targeted ingest is a
+                # per-file decline → the call is dirty (files_failed) but earlier
+                # commits stand. A full sync keeps its historical crash-loud
+                # behavior (there the whole walk is authoritative).
+                if not targeted:
+                    raise
+                eprint(f"[codex-cache] normalization failed for {jp}: {exc}")
+                stats.files_failed += 1
+                continue
+            new_last_turn_id = norm_result.terminal.turn_id
+
             # Every derived row above was buffered before the first DML. A
             # late database failure therefore rolls the whole file back and
             # retries that same in-memory batch exactly once.
@@ -3892,12 +4320,18 @@ def sync_codex_cache(
                         last_root_thread_id=new_last_root_thread_id,
                         last_parent_thread_id=new_last_parent_thread_id,
                         last_conversation_key=new_last_conversation_key,
+                        last_turn_id=new_last_turn_id,
                         reset_file=truncated or requalified,
                         accounting_rows=accounting_rows,
                         quota_rows=quota_rows,
                         thread_rows=thread_rows,
                         event_rows=event_rows,
+                        normalized_rows=norm_result.rows,
+                        normalized_touches=norm_result.touches,
                         active_root_keys={item.source_root_key for item in files},
+                        # §5.1 whole-tree bypass: targeted mode never prunes
+                        # codex_source_roots for roots outside its target set.
+                        prune_roots=not targeted,
                     )
                 except sqlite3.DatabaseError as exc:
                     conn.rollback()
@@ -3917,8 +4351,16 @@ def sync_codex_cache(
                 committed = True
                 break
             if not committed:
+                if targeted:
+                    stats.files_failed += 1  # §5.1 DB-exception decline → dirty
                 continue
 
+            # Private test seam (§5.1 post-preflight late-shrink race): fires
+            # after each file's successful commit, so a race test can shrink a
+            # not-yet-written target and assert the earlier commit stands.
+            if _on_file_committed is not None:
+                _on_file_committed(path_str)
+
             if progress is not None:
                 progress(stats)
 
@@ -3973,36 +4415,46 @@ def sync_codex_cache(
         # projection, so the skip decision on that branch is DEFERRED to the
         # post-flock stats-side signature check below — making the gate's
         # skip-condition identical to reconcile's own short-circuit-condition.
-        cur_seq = codex_physical_mutation_seq(conn)
-        if cur_seq != seq_before:
-            project_after_unlock = True
-        else:
-            active_roots = _cache_root_keys(conn)
-            if not active_roots:
-                project_after_unlock = False
+        #
+        # §5.1: a targeted (only_paths) ingest NEVER invokes the global quota
+        # reconciler (its observation load reconciles all roots at seconds-scale
+        # cost). Quota projection is deferred to the next full sync, which the
+        # ordinary hook cadence supplies. Skip the whole decision block so
+        # project_after_unlock / deferred_cert_* / did_from_zero_replay keep
+        # their no-op defaults — the post-flock reconcile paths below then all
+        # short-circuit for a targeted call.
+        if not targeted:
+            cur_seq = codex_physical_mutation_seq(conn)
+            if cur_seq != seq_before:
+                project_after_unlock = True
             else:
-                certificate = load_codex_quota_projection_certificate(conn)
-                certificate_current = (
-                    certificate is not None
-                    and certificate[0] == cur_seq
-                    and active_roots <= set(certificate[1])
-                )
-                if certificate_current:
-                    # The CACHE certificate is current, but that alone does NOT
-                    # prove stats.db still holds the projection (F1). Defer the
-                    # stats-side signature match until AFTER the Codex flock
-                    # releases below — only then may the reconcile be skipped.
+                active_roots = _cache_root_keys(conn)
+                if not active_roots:
                     project_after_unlock = False
-                    deferred_cert_roots = set(active_roots)
-                    assert certificate is not None
-                    deferred_cert_sigs = dict(certificate[1])
                 else:
-                    project_after_unlock = True
-        # #313 P3 (F9): a Codex rebuild or a truncation/requalification
-        # re-ingest replays from offset 0 and restores >retention-day
-        # codex_conversation_events. Force an unthrottled prune after the flock
-        # releases (below), so restored old rows don't persist for up to 24h.
-        did_from_zero_replay = rebuild or stats.files_reset_truncated > 0
+                    certificate = load_codex_quota_projection_certificate(conn)
+                    certificate_current = (
+                        certificate is not None
+                        and certificate[0] == cur_seq
+                        and active_roots <= set(certificate[1])
+                    )
+                    if certificate_current:
+                        # The CACHE certificate is current, but that alone does
+                        # NOT prove stats.db still holds the projection (F1).
+                        # Defer the stats-side signature match until AFTER the
+                        # Codex flock releases below — only then may the
+                        # reconcile be skipped.
+                        project_after_unlock = False
+                        deferred_cert_roots = set(active_roots)
+                        assert certificate is not None
+                        deferred_cert_sigs = dict(certificate[1])
+                    else:
+                        project_after_unlock = True
+            # #313 P3 (F9): a Codex rebuild or a truncation/requalification
+            # re-ingest replays from offset 0 and restores >retention-day
+            # codex_conversation_events. Force an unthrottled prune after the
+            # flock releases (below), so restored old rows don't persist for 24h.
+            did_from_zero_replay = rebuild or stats.files_reset_truncated > 0
     finally:
         try:
             fcntl.flock(lock_fh, fcntl.LOCK_UN)