cc-transcript 8.1.0__tar.gz → 9.0.1__tar.gz

{cc_transcript-8.1.0 → cc_transcript-9.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-transcript
-Version: 8.1.0
+Version: 9.0.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -18,10 +18,14 @@ Requires-Dist: tree-sitter-bash>=0.25
 Requires-Dist: pytest>=8.0 ; extra == 'dev'
 Requires-Dist: ty>=0.0.44 ; extra == 'dev'
 Requires-Dist: ruff>=0.8 ; extra == 'dev'
+Requires-Dist: sqlite-vec>=0.1.9 ; extra == 'judge'
+Requires-Dist: model2vec>=0.8.2 ; extra == 'judge'
+Requires-Dist: numpy>=1.26 ; extra == 'judge'
 Requires-Dist: spawnllm>=0.5.4,<0.6 ; extra == 'llm'
 Requires-Dist: spacy>=3.8 ; extra == 'sentiment'
 Requires-Dist: afinn>=0.1 ; extra == 'sentiment'
 Provides-Extra: dev
+Provides-Extra: judge
 Provides-Extra: llm
 Provides-Extra: sentiment
 License-File: LICENSE

{cc_transcript-8.1.0 → cc_transcript-9.0.1}/cc_transcript/judge/__init__.py

@@ -13,7 +13,18 @@ prompts, the verdict model, and any SQL views over the verdict table.
 from __future__ import annotations
 
 from cc_transcript.judge.llm import default_backend, resolved_model, structured_judge
+from cc_transcript.judge.similar import (
+    Evidence,
+    KeyOverlap,
+    Suggestion,
+    default_embedder,
+    embed_evidence,
+    near_duplicate_keys,
+    record_evidence,
+    suggest_canonical_keys,
+)
 from cc_transcript.judge.verdicts import (
+    SLUG_PATTERN,
     AuditEstimate,
     AuditSample,
     Disagreement,
@@ -25,7 +36,9 @@ from cc_transcript.judge.verdicts import (
     JudgeError,
     Metrics,
     VerdictLike,
+    VerdictSchemaError,
     VerdictStoreMixin,
+    canonical_slug,
     exact_upper_bound,
     flip_pairs,
     golden_result,

{cc_transcript-8.1.0 → cc_transcript-9.0.1}/cc_transcript/judge/llm.py

@@ -11,6 +11,7 @@ needs no extra installed.
 
 from __future__ import annotations
 
+import json
 from functools import cache
 from typing import TYPE_CHECKING
 
@@ -69,7 +70,7 @@ def structured_judge[M: BaseModel](
     async def judge(prompt: str) -> M:
         try:
             return await extract(prompt, response_model, backend=default_backend(), model=tier, timeout=timeout)
-        except (BackendCallError, BackendUnavailable, TimeoutError, ValidationError) as error:
+        except (BackendCallError, BackendUnavailable, TimeoutError, ValidationError, json.JSONDecodeError) as error:
             raise JudgeError(str(error)) from error
 
     return judge

cc_transcript-9.0.1/cc_transcript/judge/similar.py

@@ -0,0 +1,371 @@
+"""Canonical-key retrieval over verdict evidence, via a sqlite-vec companion store.
+
+When a verdict assigns a ``canonical_key``, :func:`record_evidence` embeds the
+judged event's feedback with a static text model (``potion-retrieval-32M``) and
+upserts the vector into a sqlite-vec table that lives in the verdict store's own
+database — created on first use, never part of the base schema. Two read paths
+sit on top: :func:`suggest_canonical_keys` ranks stored keys by evidence
+similarity to a new correction, and :func:`near_duplicate_keys` flags distinct
+keys whose evidence centroids nearly coincide (split detection; nothing merges).
+
+The vector deps (``sqlite-vec``, ``model2vec``, ``numpy``) live behind the
+``cc-transcript[judge]`` extra and load lazily, so importing this module needs
+none of them installed; an app that assigns canonical keys without the extra
+fails loud with an :class:`ImportError` naming it.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from importlib.util import find_spec
+from typing import TYPE_CHECKING, NamedTuple
+from weakref import WeakSet
+
+import anyio.to_thread
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import aiosqlite
+    import numpy as np
+
+    from cc_transcript.mining.candidates import DedupKey
+    from cc_transcript.mining.store import FeedbackStore
+    from cc_transcript.store import FileStateStore
+
+EMBED_MODEL = "minishlab/potion-retrieval-32M"
+EMBED_DIM = 512
+JUDGE_EXTRA = "cc-transcript[judge]"
+JUDGE_DEPS = ("model2vec", "numpy", "sqlite_vec")
+
+VECTOR_SCHEMA = f"""
+CREATE VIRTUAL TABLE IF NOT EXISTS verdict_vectors USING vec0(
+  vector_id TEXT PRIMARY KEY,
+  embedding float[{EMBED_DIM}] distance_metric=cosine
+);
+CREATE TABLE IF NOT EXISTS verdict_evidence (
+  vector_id TEXT PRIMARY KEY,
+  dedup_key TEXT NOT NULL,
+  role TEXT NOT NULL,
+  prompt_version INTEGER NOT NULL,
+  canonical_key TEXT NOT NULL,
+  evidence_text TEXT NOT NULL
+);
+"""
+
+type Embedder = Callable[[str], np.ndarray]
+
+PREPARED_CONNECTIONS: WeakSet[aiosqlite.Connection] = WeakSet()
+
+
+class Suggestion(NamedTuple):
+    """One canonical-key suggestion ranked by evidence similarity.
+
+    Attributes:
+        canonical_key: The suggested durable-rule key.
+        score: Cosine similarity of the query to the key's nearest evidence
+            vector, in ``[-1, 1]``; higher is closer.
+        sentences: Up to three evidence texts backing the key, most similar first.
+    """
+
+    canonical_key: str
+    score: float
+    sentences: tuple[str, ...]
+
+
+class Evidence(NamedTuple):
+    """A judged event's embedded feedback, ready to upsert inside the verdict transaction.
+
+    Attributes:
+        vector: The serialized 512-dim embedding of the feedback plus the verdict summary.
+        text: The event's feedback text, stored verbatim as the evidence sentence.
+        canonical_key: The durable-rule key the verdict assigned.
+    """
+
+    vector: bytes
+    text: str
+    canonical_key: str
+
+
+class KeyOverlap(NamedTuple):
+    """Two distinct canonical keys whose evidence centroids nearly coincide.
+
+    Attributes:
+        key_a: The lexicographically smaller key.
+        key_b: The lexicographically larger key.
+        similarity: Cosine similarity of the two evidence centroids.
+    """
+
+    key_a: str
+    key_b: str
+    similarity: float
+
+
+def require_judge_extra() -> None:
+    """Raises a clear :class:`ImportError` naming the extra when a vector dep is missing."""
+    if any(find_spec(name) is None for name in JUDGE_DEPS):
+        raise ImportError(f"canonical-key retrieval needs the vector-store deps; install {JUDGE_EXTRA}")
+
+
+@cache
+def default_embedder() -> Embedder:
+    """The ``potion-retrieval-32M`` static embedder, loaded once and cached per process.
+
+    Returns a callable mapping one text to its L2-normalized 512-dim ``float32``
+    embedding. The model downloads from the Hugging Face hub on first use and is
+    cached there; inference is numpy-only. Tests inject a deterministic stand-in
+    by monkeypatching this loader.
+
+    Raises:
+        ImportError: When the ``cc-transcript[judge]`` extra is not installed.
+    """
+    require_judge_extra()
+    import numpy as np
+    from model2vec import StaticModel
+
+    model = StaticModel.from_pretrained(EMBED_MODEL)
+
+    def embed(text: str) -> np.ndarray:
+        vector = model.encode([text])[0].astype(np.float32)
+        return vector / np.linalg.norm(vector)
+
+    return embed
+
+
+async def prepare_connection(store: FileStateStore) -> None:
+    """Loads the sqlite-vec extension and creates the companion tables, once per connection.
+
+    Holds ``store.lock`` around the check-and-prepare so the schema-creating
+    ``executescript`` — which implicitly commits the connection — can never fire
+    while another task holds an open :meth:`~cc_transcript.store.FileStateStore.transaction`,
+    and so the "already prepared" test-and-set stays atomic under concurrent
+    :meth:`~cc_transcript.judge.verdicts.VerdictStoreMixin.record_verdict` fan-out.
+    """
+    import sqlite_vec
+
+    async with store.lock:
+        if store.conn in PREPARED_CONNECTIONS:
+            return
+        await store.conn.enable_load_extension(True)
+        await store.conn.load_extension(sqlite_vec.loadable_path())
+        await store.conn.enable_load_extension(False)
+        await store.conn.executescript(VECTOR_SCHEMA)
+        PREPARED_CONNECTIONS.add(store.conn)
+
+
+def serialize_vector(vector: np.ndarray) -> bytes:
+    import sqlite_vec
+
+    return sqlite_vec.serialize_float32(vector.tolist())
+
+
+async def embed_evidence(store: FileStateStore, *, dedup_key: DedupKey, canonical_key: str, summary: str) -> Evidence:
+    """Prepares the vector store and embeds a judged event's feedback for upsert.
+
+    Fetches the event's feedback text from ``feedback_events`` and embeds it
+    together with ``summary``, off the event loop. Runs the schema-creating
+    :func:`prepare_connection` and the feedback read under ``store.lock``, both
+    outside the caller's transaction: ``prepare_connection``'s ``executescript``
+    implicitly commits an open transaction, so the caller calls this before
+    ``BEGIN`` and then upserts the returned :class:`Evidence` atomically via
+    :func:`record_evidence`. Called from
+    :meth:`~cc_transcript.judge.verdicts.VerdictStoreMixin.record_verdict`
+    whenever a verdict assigns a ``canonical_key``.
+
+    Args:
+        store: The verdict store; the vectors live in its database.
+        dedup_key: The judged event's dedup key.
+        canonical_key: The durable-rule key the verdict assigned.
+        summary: The verdict's one-sentence summary, embedded with the feedback.
+
+    Returns:
+        The serialized vector, evidence text, and canonical key, ready to upsert.
+
+    Raises:
+        ImportError: When the ``cc-transcript[judge]`` extra is not installed.
+    """
+    require_judge_extra()
+    await prepare_connection(store)
+    async with store.lock:
+        cursor = await store.conn.execute("SELECT text FROM feedback_events WHERE dedup_key = ?", (dedup_key,))
+        text = (await cursor.fetchone())["text"]
+    embedder = await anyio.to_thread.run_sync(default_embedder)
+    vector = await anyio.to_thread.run_sync(embedder, f"{text}\n{summary}")
+    return Evidence(serialize_vector(vector), text, canonical_key)
+
+
+def evidence_vector_id(dedup_key: DedupKey, role: str, prompt_version: int) -> str:
+    return f"{dedup_key}::{role}::{prompt_version}"
+
+
+async def clear_evidence(conn: aiosqlite.Connection, *, dedup_key: DedupKey, role: str, prompt_version: int) -> None:
+    """Deletes any evidence vector for one verdict identity, on the caller's transaction.
+
+    Both the delete pair :func:`record_evidence` runs before it re-inserts, and
+    the sole cleanup when a verdict is upgraded to name no ``canonical_key``: the
+    removal commits atomically with the verdict row that dropped the key, so a
+    dropped rule never leaves stale evidence for :func:`suggest_canonical_keys`
+    to surface.
+
+    Args:
+        conn: The verdict store's connection, inside the caller's write transaction.
+        dedup_key: The judged event's dedup key.
+        role: Who produced the verdict, e.g. ``judge`` or ``auditor``.
+        prompt_version: The prompt version that produced the verdict.
+    """
+    vector_id = evidence_vector_id(dedup_key, role, prompt_version)
+    await conn.execute("DELETE FROM verdict_vectors WHERE vector_id = ?", (vector_id,))
+    await conn.execute("DELETE FROM verdict_evidence WHERE vector_id = ?", (vector_id,))
+
+
+async def record_evidence(
+    conn: aiosqlite.Connection, *, dedup_key: DedupKey, role: str, prompt_version: int, evidence: Evidence
+) -> None:
+    """Upserts a judged event's evidence vector inside the caller's open transaction.
+
+    Replaces any prior vector keyed ``(dedup_key, role, prompt_version)`` — one
+    vector per event per role per prompt version, mirroring the verdict's own
+    identity so a ``judge`` and an ``auditor`` verdict on the same event never
+    overwrite each other's evidence. The delete/insert pairs run on the caller's
+    already-begun transaction, so a failure rolls the verdict row back with them;
+    the failure-prone prepare and embed happen earlier in :func:`embed_evidence`.
+
+    Args:
+        conn: The verdict store's connection, inside the caller's write transaction.
+        dedup_key: The judged event's dedup key.
+        role: Who produced the verdict, e.g. ``judge`` or ``auditor``.
+        prompt_version: The prompt version that produced the verdict.
+        evidence: The embedded feedback from :func:`embed_evidence`.
+    """
+    await clear_evidence(conn, dedup_key=dedup_key, role=role, prompt_version=prompt_version)
+    vector_id = evidence_vector_id(dedup_key, role, prompt_version)
+    await conn.execute("INSERT INTO verdict_vectors(vector_id, embedding) VALUES (?, ?)", (vector_id, evidence.vector))
+    await conn.execute(
+        "INSERT INTO verdict_evidence(vector_id, dedup_key, role, prompt_version, canonical_key, evidence_text) "
+        "VALUES (?, ?, ?, ?, ?, ?)",
+        (vector_id, dedup_key, role, prompt_version, evidence.canonical_key, evidence.text),
+    )
+
+
+async def prepare_evidence_removal(store: FileStateStore) -> bool:
+    """Readies the vec companion so an in-transaction :func:`clear_evidence` can reach it.
+
+    Returns False — skip the removal — whenever no evidence could exist: ``sqlite_vec``
+    is absent, or the companion tables were never created. The removal path embeds
+    nothing, so it gates on ``sqlite_vec`` alone — the ``model2vec``/``numpy``
+    embedder deps that :func:`require_judge_extra` guards belong to the insert side,
+    and a partial install (``sqlite_vec`` present, embedder absent) must still clear
+    stranded evidence. Otherwise loads the extension onto the connection (a no-op
+    once the connection is prepared) so a later :func:`clear_evidence` on the
+    caller's transaction can delete from the ``vec0`` virtual table, and returns
+    True. Called before the verdict transaction opens, mirroring
+    :func:`embed_evidence`, because :func:`prepare_connection`'s ``executescript``
+    commits.
+
+    Args:
+        store: The verdict store; the vectors live in its database.
+    """
+    if store.conn in PREPARED_CONNECTIONS:
+        return True
+    if find_spec("sqlite_vec") is None:
+        return False
+    async with store.lock:
+        cursor = await store.conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'verdict_evidence'"
+        )
+        if await cursor.fetchone() is None:
+            return False
+    await prepare_connection(store)
+    return True
+
+
+async def suggest_canonical_keys(
+    store: FeedbackStore, text: str, *, prompt_version: int, k: int = 5
+) -> list[Suggestion]:
+    """Ranks stored canonical keys by evidence similarity to ``text``.
+
+    Embeds ``text`` and scans every evidence vector recorded at ``prompt_version``,
+    ranking each key by its single closest evidence vector (cosine similarity).
+    Returns the top ``k`` keys, each with up to three backing evidence sentences
+    ordered most-similar first.
+
+    Args:
+        store: The verdict store whose database holds the evidence vectors.
+        text: The free text to find canonical keys for, e.g. a new correction.
+        prompt_version: The prompt version whose evidence to search.
+        k: The maximum number of distinct canonical keys to return.
+
+    Returns:
+        Up to ``k`` :class:`Suggestion`s, highest score first.
+
+    Raises:
+        ImportError: When the ``cc-transcript[judge]`` extra is not installed.
+    """
+    require_judge_extra()
+    conn = store.store.conn
+    await prepare_connection(store.store)
+    embedder = await anyio.to_thread.run_sync(default_embedder)
+    query = serialize_vector(await anyio.to_thread.run_sync(embedder, text))
+    cur = await conn.execute(
+        "SELECT e.canonical_key AS ck, e.evidence_text AS ev, vec_distance_cosine(v.embedding, ?) AS dist "
+        "FROM verdict_vectors v JOIN verdict_evidence e ON e.vector_id = v.vector_id "
+        "WHERE e.prompt_version = ? ORDER BY dist",
+        (query, prompt_version),
+    )
+    ranked: dict[str, list[tuple[float, str]]] = {}
+    async for row in cur:
+        ranked.setdefault(row["ck"], []).append((1.0 - row["dist"], row["ev"]))
+    return sorted(
+        (Suggestion(ck, hits[0][0], tuple(ev for _, ev in hits[:3])) for ck, hits in ranked.items()),
+        key=lambda suggestion: suggestion.score,
+        reverse=True,
+    )[:k]
+
+
+async def near_duplicate_keys(store: FeedbackStore, *, prompt_version: int, threshold: float) -> list[KeyOverlap]:
+    """Finds distinct canonical keys whose evidence centroids nearly coincide.
+
+    Groups the evidence vectors recorded at ``prompt_version`` by canonical key,
+    reduces each group to a normalized centroid, and returns every pair of
+    distinct keys whose centroid cosine similarity exceeds ``threshold`` — a
+    split-detection signal that two keys may name the same rule. Nothing merges;
+    the caller decides.
+
+    Args:
+        store: The verdict store whose database holds the evidence vectors.
+        prompt_version: The prompt version whose evidence to compare.
+        threshold: The exclusive cosine-similarity floor a pair must clear.
+
+    Returns:
+        Overlapping key pairs, highest similarity first, each pair's keys ordered
+        lexicographically.
+
+    Raises:
+        ImportError: When the ``cc-transcript[judge]`` extra is not installed.
+    """
+    require_judge_extra()
+    import numpy as np
+
+    conn = store.store.conn
+    await prepare_connection(store.store)
+    cur = await conn.execute(
+        "SELECT e.canonical_key AS ck, v.embedding AS emb "
+        "FROM verdict_vectors v JOIN verdict_evidence e ON e.vector_id = v.vector_id "
+        "WHERE e.prompt_version = ?",
+        (prompt_version,),
+    )
+    groups: dict[str, list[np.ndarray]] = {}
+    async for row in cur:
+        groups.setdefault(row["ck"], []).append(np.frombuffer(row["emb"], dtype=np.float32))
+    centroids = {ck: (mean := np.mean(vectors, axis=0)) / np.linalg.norm(mean) for ck, vectors in groups.items()}
+    keys = sorted(centroids)
+    return sorted(
+        (
+            KeyOverlap(key_a, key_b, similarity)
+            for i, key_a in enumerate(keys)
+            for key_b in keys[i + 1 :]
+            if (similarity := float(np.dot(centroids[key_a], centroids[key_b]))) > threshold
+        ),
+        key=lambda overlap: overlap.similarity,
+        reverse=True,
+    )

{cc_transcript-8.1.0 → cc_transcript-9.0.1}/cc_transcript/judge/verdicts.py

@@ -9,10 +9,12 @@ prompts, the verdict model, and any SQL views over the verdict table.
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 from math import comb
 from random import Random
 from typing import TYPE_CHECKING, ClassVar, Protocol
+from weakref import WeakKeyDictionary
 
 import anyio
 
@@ -21,6 +23,8 @@ from cc_transcript.mining.store import now
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable, Mapping, Sequence
 
+    import aiosqlite
+
     from cc_transcript.context import Fidelity
     from cc_transcript.mining.candidates import DedupKey
     from cc_transcript.store import FileStateStore
@@ -42,13 +46,46 @@ CREATE TABLE IF NOT EXISTS {table} (
   {summary} TEXT NOT NULL,
   confidence REAL NOT NULL,
   rationale TEXT NOT NULL,
+  canonical_key TEXT,
   fidelity TEXT NOT NULL CHECK(fidelity IN ('full','summary')),
   judged_at TEXT NOT NULL,
-  UNIQUE(dedup_key, role, prompt_version, model)
+  UNIQUE(dedup_key, role, prompt_version)
 );
 CREATE INDEX IF NOT EXISTS idx_{table}_dedup ON {table}(dedup_key);
 """
 
+SLUG_PATTERN = re.compile(r"^[a-z0-9]+(-[a-z0-9]+){1,5}$")
+"""Matches a durable rule slug: two to six ``[a-z0-9]`` groups joined by single hyphens.
+
+The two-group floor rejects a bare word, and the six-group ceiling — together
+with the hyphen requirement — can never match a 64-character hex digest, so a
+slug and a content digest never collide.
+"""
+
+VALIDATED_VERDICT_TABLES: WeakKeyDictionary[aiosqlite.Connection, set[str]] = WeakKeyDictionary()
+"""Per-connection sets of verdict table names that passed :meth:`VerdictStoreMixin.ensure_verdict_schema`.
+
+A table's schema is fixed for a connection's lifetime, so the v8/v9 check runs
+once per table per connection; membership short-circuits the repeat calls from
+every :meth:`~VerdictStoreMixin.judged`, :meth:`~VerdictStoreMixin.unjudged`, and
+:meth:`~VerdictStoreMixin.record_verdict`. Scoped by table, not connection alone,
+because the mixin is explicitly multi-table — two subclasses with different
+``VERDICT_TABLE`` may share one connection, and validating one must not vouch for
+the other.
+"""
+
+
+class VerdictSchemaError(RuntimeError):
+    """The verdict table predates the v9 schema and must be rebuilt by hand.
+
+    Raised by :class:`VerdictStoreMixin`'s read and write paths when the physical
+    table lacks the ``canonical_key`` column or its unique index still covers the
+    v8 identity ``(dedup_key, role, prompt_version, model)``. ``CREATE TABLE IF
+    NOT EXISTS`` leaves such a table untouched, and :meth:`~VerdictStoreMixin.judged`
+    neither selects ``canonical_key`` nor joins on ``model``, so a v8 table would
+    otherwise read without error while silently returning per-model duplicates.
+    """
+
 
 class JudgeError(RuntimeError):
     """A provider or transport failure from one judge call.
@@ -75,6 +112,8 @@ class VerdictLike(Protocol):
         confidence: The judge's probability that its accept-vs-reject call is right.
         rationale: One short clause explaining the call.
         accepted: Whether the verdict accepts the row.
+        canonical_key: The canonical, normalized key of the durable rule the
+            verdict names, or ``None`` when the verdict names no durable rule.
     """
 
     @property
@@ -87,6 +126,8 @@ class VerdictLike(Protocol):
     def rationale(self) -> str: ...
     @property
     def accepted(self) -> bool: ...
+    @property
+    def canonical_key(self) -> str | None: ...
 
 
 class VerdictStoreMixin:
@@ -99,6 +140,12 @@ class VerdictStoreMixin:
     shape. An app with an existing verdict table (cc-pushback's ``triage``)
     adopts the mixin by overriding the params — zero migration.
 
+    Verdict identity is ``(dedup_key, role, prompt_version)``: one verdict per
+    event per role per prompt version. ``model`` is provenance only — recorded
+    and reported, never filtered on — so a judge-backend flip cannot mass-re-judge
+    the corpus and :meth:`judged`'s consumers never double-count per-model
+    duplicates.
+
     Example:
         >>> class Store(VerdictStoreMixin, FeedbackStore):
         ...     VERDICT_TABLE = "triage"
@@ -118,86 +165,173 @@ class VerdictStoreMixin:
             table=cls.VERDICT_TABLE, accepted=cls.ACCEPTED_COLUMN, summary=cls.SUMMARY_COLUMN
         )
 
+    async def ensure_verdict_schema(self) -> None:
+        """Validates the verdict table matches the v9 schema, once per table per connection.
+
+        ``CREATE TABLE IF NOT EXISTS`` leaves an existing v8 table (no
+        ``canonical_key`` column, unique index over ``(dedup_key, role,
+        prompt_version, model)``) in place, and neither :meth:`judged` nor
+        :meth:`unjudged` selects ``canonical_key`` or joins on ``model`` — so a v8
+        table reads without error while returning per-model duplicates. The read
+        and write paths call this first so the mismatch fails loud instead.
+
+        Raises:
+            VerdictSchemaError: When the table lacks a ``canonical_key`` column or
+                no unique index covers exactly ``(dedup_key, role, prompt_version)``.
+        """
+        if self.VERDICT_TABLE in VALIDATED_VERDICT_TABLES.setdefault(self.store.conn, set()):
+            return
+        columns = {
+            row["name"] async for row in await self.store.conn.execute(f"PRAGMA table_info({self.VERDICT_TABLE})")
+        }
+        indexes = [dict(row) async for row in await self.store.conn.execute(f"PRAGMA index_list({self.VERDICT_TABLE})")]
+        unique_columns = [
+            tuple([col["name"] async for col in await self.store.conn.execute(f"PRAGMA index_info({index['name']})")])
+            for index in indexes
+            if index["unique"]
+        ]
+        if "canonical_key" not in columns or ("dedup_key", "role", "prompt_version") not in unique_columns:
+            raise VerdictSchemaError(
+                f"verdict table {self.VERDICT_TABLE!r} predates the v9 schema: it needs a canonical_key column and a "
+                f"UNIQUE(dedup_key, role, prompt_version) index. Rebuild it with the manual v8-to-v9 migration "
+                f"(recreate {self.VERDICT_TABLE!r} from verdicts_ddl() and copy the rows over) before reading "
+                f"or writing."
+            )
+        VALIDATED_VERDICT_TABLES[self.store.conn].add(self.VERDICT_TABLE)
+
     async def record_verdict(
         self, key: DedupKey, verdict: VerdictLike, *, role: str, prompt_version: int, model: str, fidelity: Fidelity
     ) -> None:
-        """Records one verdict, idempotently, keyed by ``(dedup_key, role, prompt_version, model)``.
-
-        Fidelity sits outside the unique key: re-recording an existing verdict
-        is a no-op, except that a ``'full'``-fidelity verdict replaces a
-        ``'summary'`` one — the re-judge path :meth:`unjudged` opens with
-        ``refresh_summary=True``.
+        """Records one verdict, idempotently, keyed by ``(dedup_key, role, prompt_version)``.
+
+        One verdict per event per role per prompt version — ``model`` is pure
+        provenance, recorded and reported but never part of the identity, so a
+        judge-backend flip never mass-re-judges the corpus. Re-recording is a
+        no-op, with one exception: a ``'full'``-fidelity verdict replaces a
+        ``'summary'`` one at the same key (any model), carrying the new model,
+        content, and ``canonical_key`` across — the re-judge path
+        :meth:`unjudged` opens with ``refresh_summary=True``. A different-model
+        ``'full'``-to-``'full'`` re-record is a deliberate silent no-op:
+        first-full-wins.
 
         Args:
             key: The judged event's dedup key.
             verdict: The structured verdict to persist.
             role: Who produced it, e.g. ``judge`` or ``auditor``.
             prompt_version: The prompt version that produced it.
-            model: The resolved model name that produced it.
+            model: The resolved model name that produced it, kept as provenance.
             fidelity: Whether the judged window rendered at ``'full'`` fidelity
                 or from ``'summary'`` previews.
         """
-        await self.store.conn.execute(
-            f"INSERT INTO {self.VERDICT_TABLE} ("
-            f"dedup_key, role, prompt_version, model, category, {self.ACCEPTED_COLUMN}, "
-            f"{self.SUMMARY_COLUMN}, confidence, rationale, fidelity, judged_at"
-            ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
-            "ON CONFLICT(dedup_key, role, prompt_version, model) DO UPDATE SET "
-            f"category = excluded.category, {self.ACCEPTED_COLUMN} = excluded.{self.ACCEPTED_COLUMN}, "
-            f"{self.SUMMARY_COLUMN} = excluded.{self.SUMMARY_COLUMN}, confidence = excluded.confidence, "
-            "rationale = excluded.rationale, fidelity = excluded.fidelity, judged_at = excluded.judged_at "
-            "WHERE fidelity = 'summary' AND excluded.fidelity = 'full'",
-            (
-                key,
-                role,
-                prompt_version,
-                model,
-                verdict.category,
-                verdict.accepted,
-                verdict.summary,
-                verdict.confidence,
-                verdict.rationale,
-                fidelity,
-                now(),
-            ),
+        from cc_transcript.judge.similar import (
+            clear_evidence,
+            embed_evidence,
+            prepare_evidence_removal,
+            record_evidence,
         )
 
+        await self.ensure_verdict_schema()
+        evidence = (
+            await embed_evidence(
+                self.store, dedup_key=key, canonical_key=verdict.canonical_key, summary=verdict.summary
+            )
+            if verdict.canonical_key is not None
+            else None
+        )
+        removable = evidence is None and await prepare_evidence_removal(self.store)
+        async with self.store.transaction() as conn:
+            cursor = await conn.execute(
+                f"INSERT INTO {self.VERDICT_TABLE} ("
+                f"dedup_key, role, prompt_version, model, category, {self.ACCEPTED_COLUMN}, "
+                f"{self.SUMMARY_COLUMN}, confidence, rationale, canonical_key, fidelity, judged_at"
+                ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) "
+                "ON CONFLICT(dedup_key, role, prompt_version) DO UPDATE SET "
+                f"model = excluded.model, category = excluded.category, "
+                f"{self.ACCEPTED_COLUMN} = excluded.{self.ACCEPTED_COLUMN}, "
+                f"{self.SUMMARY_COLUMN} = excluded.{self.SUMMARY_COLUMN}, confidence = excluded.confidence, "
+                "rationale = excluded.rationale, canonical_key = excluded.canonical_key, "
+                "fidelity = excluded.fidelity, judged_at = excluded.judged_at "
+                "WHERE fidelity = 'summary' AND excluded.fidelity = 'full'",
+                (
+                    key,
+                    role,
+                    prompt_version,
+                    model,
+                    verdict.category,
+                    verdict.accepted,
+                    verdict.summary,
+                    verdict.confidence,
+                    verdict.rationale,
+                    verdict.canonical_key,
+                    fidelity,
+                    now(),
+                ),
+            )
+            if cursor.rowcount > 0:
+                if evidence is not None:
+                    await record_evidence(
+                        conn, dedup_key=key, role=role, prompt_version=prompt_version, evidence=evidence
+                    )
+                elif removable:
+                    await clear_evidence(conn, dedup_key=key, role=role, prompt_version=prompt_version)
+
     async def unjudged(
         self,
         *,
         role: str,
         prompt_version: int,
-        model: str,
         limit: int | None = None,
         refresh_summary: bool = False,
     ) -> list[dict[str, object]]:
-        """Returns events lacking a verdict for ``(role, prompt_version, model)``, oldest first.
+        """Returns events lacking a verdict for ``(role, prompt_version)``, unjudged first.
+
+        Truly-unjudged events (no verdict at all) sort ahead of summary-refresh
+        rows, then by event id, so a backlog of summary rows never starves fresh
+        events under ``limit``.
 
         Args:
             role: The verdict role to check.
             prompt_version: The prompt version the verdict must carry.
-            model: The resolved model name the verdict must carry.
             limit: When set, the maximum number of rows to return.
             refresh_summary: When True, also re-yields events whose verdict was
                 recorded at ``fidelity='summary'``, so they can be re-judged at
-                full fidelity once their windows hydrate again.
+                full fidelity once their windows hydrate again. A summary row
+                whose context window no longer hydrates — its transcript expired
+                or a ref was compacted away — is dropped, so a dead transcript
+                stops burning the cap.
 
         Returns:
             One dict per event with the columns needed to build its prompt.
         """
-        miss = "(t.id IS NULL OR t.fidelity = 'summary')" if refresh_summary else "t.id IS NULL"
-        query = (
-            f"SELECT {EVENT_COLUMNS} FROM feedback_events e "
+        await self.ensure_verdict_schema()
+        if not refresh_summary:
+            sql = (
+                f"SELECT {EVENT_COLUMNS} FROM feedback_events e "
+                f"LEFT JOIN {self.VERDICT_TABLE} t ON t.dedup_key = e.dedup_key "
+                "AND t.role = ? AND t.prompt_version = ? "
+                "WHERE t.id IS NULL ORDER BY e.id"
+            )
+            params: tuple[object, ...] = (role, prompt_version)
+            if limit is not None:
+                sql += " LIMIT ?"
+                params = (*params, limit)
+            async with self.store.conn.execute(sql, params) as cur:
+                return [dict(row) async for row in cur]
+        kept: list[dict[str, object]] = []
+        async with self.store.conn.execute(
+            f"SELECT {EVENT_COLUMNS}, t.id AS verdict_id FROM feedback_events e "
             f"LEFT JOIN {self.VERDICT_TABLE} t ON t.dedup_key = e.dedup_key "
-            "AND t.role = ? AND t.prompt_version = ? AND t.model = ? "
-            f"WHERE {miss} ORDER BY e.id"
-        )
-        params: tuple[object, ...] = (role, prompt_version, model)
-        if limit is not None:
-            query += " LIMIT ?"
-            params = (*params, limit)
-        cur = await self.store.conn.execute(query, params)
-        return [dict(row) async for row in cur]
+            "AND t.role = ? AND t.prompt_version = ? "
+            "WHERE (t.id IS NULL OR t.fidelity = 'summary') ORDER BY (t.id IS NOT NULL), e.id",
+            (role, prompt_version),
+        ) as cur:
+            async for raw in cur:
+                row = dict(raw)
+                if row.pop("verdict_id") is None or await hydratable(str(row["context_json"])):
+                    kept.append(row)
+                    if limit is not None and len(kept) >= limit:
+                        break
+        return kept
 
     async def judged(self, *, role: str, prompt_version: int) -> list[dict[str, object]]:
         """Returns events joined with their ``(role, prompt_version)`` verdicts, oldest first.
@@ -214,6 +348,7 @@ class VerdictStoreMixin:
             verdict's ``category``, ``accepted``, ``confidence``, ``summary``,
             ``rationale``, and ``model``.
         """
+        await self.ensure_verdict_schema()
         cur = await self.store.conn.execute(
             f"SELECT {EVENT_COLUMNS}, t.category, t.{self.ACCEPTED_COLUMN} AS accepted, t.confidence, "
             f"t.{self.SUMMARY_COLUMN} AS summary, t.rationale, t.model "
@@ -431,6 +566,26 @@ class FlipReport:
         return len(self.flips) / self.common if self.common else None
 
 
+def canonical_slug(text: str) -> str:
+    """Normalizes free text into a hyphenated slug candidate.
+
+    Lowercases ``text`` and reduces every run of non-alphanumeric characters to a
+    single hyphen, trimming leading and trailing hyphens — so a judge can turn a
+    durable-rule phrase into a stable :data:`SLUG_PATTERN` ``canonical_key``.
+
+    Example:
+        >>> canonical_slug("Use UV, not pip!")
+        'use-uv-not-pip'
+    """
+    return re.sub(r"[^a-z0-9]+", "-", text.strip().lower()).strip("-")
+
+
+async def hydratable(context_json: str) -> bool:
+    from cc_transcript.context import ContextWindow
+
+    return await ContextWindow.from_json(context_json).hydrate() is not None
+
+
 async def run_verdicts[V](
     rows: Sequence[Mapping[str, object]],
     prompt_for: Callable[[Mapping[str, object]], Awaitable[str]],

{cc_transcript-8.1.0 → cc_transcript-9.0.1}/cc_transcript/mining/signals.py

@@ -537,7 +537,9 @@ def question_answer_signal(
         text=text,
         cc_version=event.meta.cc_version,
         trigger_index=nearest_assistant_index(events, index),
-        signal=weak("option_pick") if option_pick else calibrated(spec.calibrated, text, seed="freeform_answer"),
+        signal=weak("option_pick")
+        if option_pick and not pair.notes
+        else calibrated(spec.calibrated, text, seed="freeform_answer"),
         evidence=evidence,
     )
 
@@ -552,9 +554,7 @@ def iter_ask_user_question_signals(events: Sequence[TranscriptEvent], spec: Mini
         if (use := uses.get(block.tool_use_id)) is not None
         if use.name == "AskUserQuestion"
         if block.content.endswith(ANSWERED_TRAILER)
-        for pair in answered_pairs(
-            block.content[len(ANSWERED_PREFIX) : -len(ANSWERED_TRAILER)], use.input["questions"]
-        )
+        for pair in answered_pairs(block.content[len(ANSWERED_PREFIX) : -len(ANSWERED_TRAILER)], use.input["questions"])
         if (signal := question_answer_signal(events, event, index, pair, spec)) is not None
     )
 

{cc_transcript-8.1.0 → cc_transcript-9.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cc-transcript"
-version = "8.1.0"
+version = "9.0.1"
 description = "Grep every Claude Code session you've ever run."
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"
@@ -49,6 +49,11 @@ sentiment = [
     "afinn>=0.1",
 ]
 llm = ["spawnllm>=0.5.4,<0.6"]
+judge = [
+    "sqlite-vec>=0.1.9",
+    "model2vec>=0.8.2",
+    "numpy>=1.26",
+]
 
 [project.scripts]
 cc-transcript = "cc_transcript.cli:cli"

{cc_transcript-8.1.0 → cc_transcript-9.0.1}/rust/src/mining.rs

@@ -1362,7 +1362,7 @@ fn iter_ask_user_question<'py>(
                 let (picked, option_pick) = resolve_pick(pair.answer, &labels);
                 let recommended = picked.iter().any(|label| label.contains("(Recommended)"));
                 let Some(text) = pair.notes.or(pair.answer) else { continue };
-                let sig = if option_pick {
+                let sig = if option_pick && pair.notes.map_or(true, str::is_empty) {
                     weak("option_pick")
                 } else {
                     calibrated(&spec.calibrated, text, "freeform_answer")