boost-skill-cli 1.2.72__tar.gz → 1.2.73__tar.gz

{boost_skill_cli-1.2.72/boost_skill_cli.egg-info → boost_skill_cli-1.2.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.72
+Version: 1.2.73
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.72'
-__version_tuple__ = version_tuple = (1, 2, 72)
+__version__ = version = '1.2.73'
+__version_tuple__ = version_tuple = (1, 2, 73)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73}/boost_cli/commands/discovery.py

@@ -96,6 +96,12 @@ def cmd_search(argv):
                    help="rerank the top hits with Claude")
     p.add_argument("--limit", type=util.positive_int, default=15,
                    help="max results (default 15)")
+    p.add_argument("--collapse-near-duplicates", action="store_true",
+                   dest="collapse_dupes",
+                   help="collapse near-identical entries (translations, "
+                        "paraphrases) via dense embeddings — opt-in, needs a "
+                        "built dense index; threshold not yet validated "
+                        "against a real corpus, see the roadmap")
     p.add_argument("--json", action="store_true", dest="as_json",
                    help="machine-readable output")
     args = p.parse_args(argv)
@@ -127,7 +133,9 @@ def cmd_search(argv):
         # retrieve_any, not retrieve: this picks the dense backend when one is
         # built and floors to BM25 otherwise, so the CLI and the MCP server
         # answer from the same engine instead of the CLI being BM25-only.
-        hits, engine = rag.retrieve_any(query, k=max(60, args.limit * 4))
+        hits, engine = rag.retrieve_any(
+            query, k=max(60, args.limit * 4),
+            collapse_near_duplicates=args.collapse_dupes)
         scored = [(h["entry"], h["score"]) for h in (hits or [])]
     else:
         scored = catalog.search(query)

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73}/boost_cli/core/dense.py

@@ -1561,6 +1561,51 @@ def _knn(con: sqlite3.Connection, qblob: bytes,
     return _expand(con, ranked, pool)
 
 
+def entry_vectors(entry_keys: list[tuple[str, str]],
+                  ) -> dict[tuple[str, str], bytes]:
+    """Raw float32 embedding for each entry's first chunk, keyed by ``(tap, path)``.
+
+    Feeds `rag.collapse_near_duplicate_hits`, whose clustering needs one
+    representative vector per *entry* rather than per chunk. The lowest-``cix``
+    chunk is that representative: `rag.chunk` always emits the name+description
+    chunk first, which is enough signal to place a translation or a paraphrase
+    near its original without reading the rest of the body.
+
+    Only a quantized store answers this cheaply: `vec_raw` is a plain
+    rowid-keyed table, so looking vectors up by id is an index probe (see
+    `_knn`'s comment on why the same lookup against a `vec0` table plans as a
+    full scan instead). A legacy float32 store returns ``{}``, and near-dup
+    collapsing degrades to a no-op there — the same way every other feature on
+    that path degrades, rather than paying a full-scan cost per entry.
+    """
+    if not entry_keys:
+        return {}
+    con = _connect()
+    if con is None:
+        return {}
+    try:
+        if not quantized(con):
+            return {}
+        col = _vid_col(con)
+        vids: dict[tuple[str, str], int] = {}
+        for tap, path in entry_keys:
+            row = con.execute(
+                "SELECT %s FROM chunks WHERE tap = ? AND path = ? "  # noqa: S608  col is a literal from _vid_col; tap/path are bound
+                "ORDER BY cix LIMIT 1" % col, (tap, path)).fetchone()
+            if row is not None and row[0] is not None:
+                vids[(tap, path)] = row[0]
+        if not vids:
+            return {}
+        ids = sorted(set(vids.values()))
+        rows = con.execute(
+            "SELECT id, embedding FROM vec_raw WHERE id IN (%s)"  # noqa: S608  interpolates only `?` placeholders; ids are bound
+            % ",".join("?" * len(ids)), ids).fetchall()
+        blobs = dict(rows)
+        return {key: blobs[vid] for key, vid in vids.items() if vid in blobs}
+    finally:
+        con.close()
+
+
 def retrieve(query: str, k: int = 60, kind: str | None = None,
              entries: list[dict] | None = None) -> list[Hit] | None:
     """Top-k dense hits for ``query``, or None to signal 'fall back to BM25'."""

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73}/boost_cli/core/rag.py

@@ -17,6 +17,7 @@ no AI -> the BM25 order is returned as-is.
 """
 from __future__ import annotations
 
+import array
 import contextlib
 import hashlib
 import json
@@ -773,6 +774,91 @@ def dedupe_by_content(hits: list[Hit], limit: int) -> list[Hit]:
     return out[:limit]
 
 
+#: Cosine-similarity floor for two entries to collapse as near-duplicates.
+#:
+#: Deliberately conservative and deliberately unproven. `dedupe_by_content`
+#: above shipped only after one count settled its safety: of 14,153 distinct
+#: bodies, the clusters spanning more than one *name* numbered zero, so
+#: collapsing on content hash could not merge two different skills. No
+#: equivalent count exists yet for near-identical clustering — the measurement
+#: the roadmap card asks for is "over a real corpus, at the chosen threshold,
+#: count clusters spanning more than one meaning" and nobody has run it. Until
+#: someone does, `collapse_near_duplicate_hits` stays reachable only opt-in
+#: (see `retrieve_any`'s `collapse_near_duplicates` parameter), so the default
+#: search path is unaffected by a threshold nobody has validated.
+NEAR_DUPLICATE_THRESHOLD = 0.97
+
+
+def _decode_vector(blob: bytes) -> array.array:
+    """A stored float32 embedding blob as a sequence of floats."""
+    vec = array.array("f")
+    vec.frombytes(blob)
+    return vec
+
+
+def _cosine(a: array.array, b: array.array) -> float:
+    """Cosine similarity of two float32 vectors, 0.0 for any comparison that
+    cannot be trusted: a dimension mismatch (different embedding models) or
+    either side being the zero vector. An ambiguous comparison must never read
+    as a match, the same rule a missing content hash follows above.
+    """
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b, strict=True))
+    norm_a = math.sqrt(sum(x * x for x in a))
+    norm_b = math.sqrt(sum(x * x for x in b))
+    if 0.0 in (norm_a, norm_b):
+        return 0.0
+    return dot / (norm_a * norm_b)
+
+
+def collapse_near_duplicate_hits(hits: list[Hit],
+                                  vectors: dict[tuple[str, str], bytes],
+                                  limit: int,
+                                  threshold: float = NEAR_DUPLICATE_THRESHOLD,
+                                  ) -> list[Hit]:
+    """Collapse entries whose embeddings are near-identical, then take ``limit``.
+
+    Runs on the output of :func:`dedupe_by_content`, on the same contract —
+    keep the earliest rank slot, promote a better source into it — for the
+    residual that survives byte-identical dedup: the same skill translated or
+    paraphrased across mirrors. Observed on a real 466-tap install: the query
+    ``exa search`` returned ten rows that were all one skill in Japanese,
+    Chinese, and five English variants, none sharing a body digest, so
+    ``dedupe_by_content`` correctly kept every one of them apart.
+
+    ``vectors`` maps ``entry_key(hit["entry"])`` to a raw float32 embedding
+    blob, looked up by the caller (:func:`boost_cli.core.dense.entry_vectors`)
+    rather than fetched here — this stays pure so it is cheap to test with
+    synthetic vectors, and clustering ``hits`` is O(n * clusters), never
+    O(n^2) against the whole store.
+
+    A hit with no vector — no dense store built, or the entry never got one —
+    is never merged into anything: two unknowns must not collapse into each
+    other, the same rule :func:`dedupe_by_content` follows for a missing
+    content hash.
+    """
+    out: list[Hit] = []
+    reps: list[array.array | None] = []   # parallel to `out`
+    for hit in hits:
+        blob = vectors.get(entry_key(hit["entry"]))
+        vec = _decode_vector(blob) if blob else None
+        merge_at = None
+        if vec is not None:
+            for i, rep in enumerate(reps):
+                if rep is not None and _cosine(vec, rep) >= threshold:
+                    merge_at = i
+                    break
+        if merge_at is None:
+            out.append(hit)
+            reps.append(vec)
+            continue
+        kept = out[merge_at]
+        if source_rank(hit["entry"]) < source_rank(kept["entry"]):
+            out[merge_at] = cast(Hit, {**kept, "entry": hit["entry"]})
+    return out[:limit]
+
+
 def _windowed(hits: list[Hit], terms: Sequence[str]) -> list[Hit]:
     """Window each hit's raw stored snip onto the query terms.
 
@@ -1087,7 +1173,8 @@ def _with_content(hits: list[Hit]) -> list[Hit]:
 
 
 def retrieve_any(query: str, k: int = 60, kind: str | None = None,
-                 entries: list[dict] | None = None
+                 entries: list[dict] | None = None,
+                 collapse_near_duplicates: bool = False,
                  ) -> tuple[list[Hit] | None, str]:
     """Fuse BM25 and dense when both are available; floor to whichever is.
 
@@ -1107,6 +1194,12 @@ def retrieve_any(query: str, k: int = 60, kind: str | None = None,
     Both engines are over-fetched to ``RRF_K`` before fusing. Fusing only the
     top-k of each would discard exactly the candidates the other engine was
     going to promote, which is most of the value.
+
+    ``collapse_near_duplicates`` runs :func:`collapse_near_duplicate_hits` over
+    the result, on top of the byte-identical dedup every branch below already
+    does — off by default (see :data:`NEAR_DUPLICATE_THRESHOLD` for why) and a
+    no-op whenever no dense store is built, since that is the only source of
+    the embeddings the collapse needs.
     """
     from . import dense
     pool = max(k, RRF_K)
@@ -1127,13 +1220,20 @@ def retrieve_any(query: str, k: int = 60, kind: str | None = None,
     # no reason to treat them as one.
     if dense_hits and bm25_hits:
         fused = rrf_fuse([bm25_hits, dense_hits], limit=max(k, RRF_K))
-        return (dedupe_by_content(_with_content(fused), k),
-                "hybrid RRF (BM25 + dense)")
-    if dense_hits:
-        return dedupe_by_content(_with_content(dense_hits), k), "dense vectors"
-    if bm25_hits is not None:
-        return bm25_hits[:k], "BM25 full-content"     # already deduped
-    return None, ""
+        hits, engine = dedupe_by_content(_with_content(fused), k), \
+            "hybrid RRF (BM25 + dense)"
+    elif dense_hits:
+        hits, engine = dedupe_by_content(_with_content(dense_hits), k), \
+            "dense vectors"
+    elif bm25_hits is not None:
+        hits, engine = bm25_hits[:k], "BM25 full-content"     # already deduped
+    else:
+        return None, ""
+    if collapse_near_duplicates and hits and dense.ready():
+        vectors = dense.entry_vectors([entry_key(h["entry"]) for h in hits])
+        if vectors:
+            hits = collapse_near_duplicate_hits(hits, vectors, k)
+    return hits, engine
 
 
 def search(query: str, limit: int = 10, kind: str | None = None,

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.72
+Version: 1.2.73
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73}/boost_skill_cli.egg-info/SOURCES.txt

@@ -803,6 +803,7 @@ tests/unit/test_dense.py
 tests/unit/test_dense_boilerplate_cluster.py
 tests/unit/test_dense_embed_dedupe.py
 tests/unit/test_dense_entry_reuse.py
+tests/unit/test_dense_entry_vectors.py
 tests/unit/test_dense_fallback.py
 tests/unit/test_dense_fix_hint.py
 tests/unit/test_dense_progress.py
@@ -869,6 +870,7 @@ tests/unit/test_mutation_hardening.py
 tests/unit/test_mutation_shards.py
 tests/unit/test_mutation_subfile_shards.py
 tests/unit/test_mutmut_source_paths.py
+tests/unit/test_near_duplicate_collapse.py
 tests/unit/test_nethttp.py
 tests/unit/test_normalize_sdist.py
 tests/unit/test_output.py
@@ -898,6 +900,7 @@ tests/unit/test_release_preflight.py
 tests/unit/test_required_checks.py
 tests/unit/test_rerank_cache.py
 tests/unit/test_resolve.py
+tests/unit/test_retrieve_any_near_duplicates.py
 tests/unit/test_roadmap_fresh.py
 tests/unit/test_rules.py
 tests/unit/test_scale_corpus.py

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73}/docs/commands.html

@@ -117,7 +117,7 @@
     </div>
     <div class="group" data-group="find">
       <div class="group-h">Find &amp; search</div>
-      <a class="cmd-link" href="#cmd-search" data-search="search search skills across tap registries (ai-ranked)  --smart --limit limit --json query">search</a>
+      <a class="cmd-link" href="#cmd-search" data-search="search search skills across tap registries (ai-ranked)  --smart --limit limit --collapse-near-duplicates --json query">search</a>
       <a class="cmd-link" href="#cmd-reindex" data-search="reindex build/refresh the full-content search index build or refresh the full-content search index --force --dense --export-shard tap --import-shard file --fetch-shards --json">reindex</a>
       <a class="cmd-link" href="#cmd-discover" data-search="discover search github for skill repos you have not tapped yet search github for skill repositories you have not tapped yet --limit limit --json --local query">discover</a>
       <a class="cmd-link" href="#cmd-recommend" data-search="recommend suggest skills based on your project&#x27;s tech stack  --path path --limit limit --json">recommend</a>
@@ -397,10 +397,10 @@
         </div>
       </section>
       <h2 class="group-h" id="grp-find">Find &amp; search</h2>
-      <section class="cmd" id="cmd-search" data-search="search search skills across tap registries (ai-ranked)  --smart --limit limit --json query">
+      <section class="cmd" id="cmd-search" data-search="search search skills across tap registries (ai-ranked)  --smart --limit limit --collapse-near-duplicates --json query">
         <h3><span class="cname">search</span><span class="gtag">find</span></h3>
         <p class="summary">Search skills across tap registries (AI-ranked)</p>
-        <pre class="syn">boost search [--smart] [--limit LIMIT] [--json] query [query ...]</pre>
+        <pre class="syn">boost search [--smart] [--limit LIMIT] [--collapse-near-duplicates] [--json] query [query ...]</pre>
         <div class="args-h">Arguments</div>
         <div class="args">
           <div class="arg"><code>query</code><span>search terms</span></div>
@@ -409,6 +409,7 @@
         <div class="args">
           <div class="arg"><code>--smart</code><span>rerank the top hits with Claude</span></div>
           <div class="arg"><code>--limit LIMIT</code><span>max results (default 15)</span></div>
+          <div class="arg"><code>--collapse-near-duplicates</code><span>collapse near-identical entries (translations, paraphrases) via dense embeddings — opt-in, needs a built dense index; threshold not yet validated against a real corpus, see the roadmap</span></div>
           <div class="arg"><code>--json</code><span>machine-readable output</span></div>
         </div>
       </section>

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73}/docs/roadmap/items/near-identical-copies-still-eat-the-slots.md

@@ -2,12 +2,13 @@
 id: near-identical-copies-still-eat-the-slots
 board: code
 section: planned
-status: planned
+status: inflight
+owner: loop/near-dup-collapse
 category: Search · Ranking
 complexity: M
 impact: High
 wow: 4
-note: 10 of 10 slots on a real 466-tap install, all past byte-identical dedup
+note: mechanism + tests shipped opt-in; corpus safety proof and default-on still open
 order: 131
 title: Near-identical copies survive content-hash dedup and take the whole result page
 ---
@@ -67,3 +68,28 @@ install from.
 <b>Not to be confused with <code>#629</code></b>, which deduplicated vector <em>storage</em> (one
 row per distinct embedding, 39.7% repeats reclaimed). That is a disk-size fix beneath the index and
 changes no ranking; this is about which rows reach the user's screen.
+
+<b>What shipped, and what did not.</b> <code>rag.collapse_near_duplicate_hits</code> is the same
+"keep the earliest rank slot, promote a better source" contract as <code>dedupe_by_content</code>,
+run over cosine similarity of the entries' first-chunk embeddings
+(<code>dense.entry_vectors</code>, an index probe through <code>chunks_entry</code> on a quantized
+store) instead of a body hash, at the <code>retrieve_any</code> seam before <code>k</code> is
+applied. It is covered by unit tests down to the arithmetic (<code>_cosine</code>'s dimension-
+mismatch and zero-vector guards), the clustering contract (rank order, quality-prior promotion,
+limit-after-collapse), the <code>dense.entry_vectors</code> lookup against a real quantized
+sqlite-vec store, and the <code>retrieve_any</code>/<code>boost search
+--collapse-near-duplicates</code> wiring in both directions (on and off).
+
+It ships <b>opt-in and off by default</b> — <code>retrieve_any(..., collapse_near_duplicates=True)</code>
+or <code>boost search --collapse-near-duplicates</code> — rather than replacing
+<code>dedupe_by_content</code>'s output on the default path. Two things this card asks for are still
+open, and both need a real embedding backend (a built dense index, over a real multi-tap corpus)
+that the environment this was implemented in cannot reach — no network path to an embeddings
+provider or to the local ONNX model download, confirmed rather than assumed: <code>huggingface.co</code>
+and <code>pypi.org</code> both refuse at the network policy layer. <b>First</b>, the safety proof
+this card itself demands before defaulting the mechanism on &mdash; &ldquo;over a real corpus, at
+the chosen threshold, count clusters spanning more than one meaning&rdquo; &mdash; has not been run;
+<code>NEAR_DUPLICATE_THRESHOLD = 0.97</code> is a starting point, not a validated floor. <b>Second</b>,
+re-measuring the <code>exa search</code> case (and per-query maxima generally) against the fix needs
+that same corpus and index. Whoever runs that measurement should flip the CLI flag's default, fold
+the corpus count into this card's evidence, and only then consider this shipped.

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73}/docs/roadmap.html

@@ -1063,7 +1063,7 @@ checks fails on every invocation is the more expensive half of this card.</p></d
       </article>
 
       <article class="cap rcard" id="near-identical-copies-still-eat-the-slots">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">Search · Ranking</span></div>
+        <div class="head"><span class="pill inflight">In flight</span><span class="cat">Search · Ranking</span></div>
         <h3>Near-identical copies survive content-hash dedup and take the whole result page</h3>
         <p><a href="#near-duplicate-items-eat-the-result-slots">Content-hash dedup</a> shipped and worked:
 <code>rag.dedupe_by_content</code> took duplicate result slots from <b>4.94 to 0.60 per query</b>
@@ -1120,12 +1120,37 @@ install from.
 
 <b>Not to be confused with <code>#629</code></b>, which deduplicated vector <em>storage</em> (one
 row per distinct embedding, 39.7% repeats reclaimed). That is a disk-size fix beneath the index and
-changes no ranking; this is about which rows reach the user's screen.</p>
+changes no ranking; this is about which rows reach the user's screen.
+
+<b>What shipped, and what did not.</b> <code>rag.collapse_near_duplicate_hits</code> is the same
+"keep the earliest rank slot, promote a better source" contract as <code>dedupe_by_content</code>,
+run over cosine similarity of the entries' first-chunk embeddings
+(<code>dense.entry_vectors</code>, an index probe through <code>chunks_entry</code> on a quantized
+store) instead of a body hash, at the <code>retrieve_any</code> seam before <code>k</code> is
+applied. It is covered by unit tests down to the arithmetic (<code>_cosine</code>'s dimension-
+mismatch and zero-vector guards), the clustering contract (rank order, quality-prior promotion,
+limit-after-collapse), the <code>dense.entry_vectors</code> lookup against a real quantized
+sqlite-vec store, and the <code>retrieve_any</code>/<code>boost search
+--collapse-near-duplicates</code> wiring in both directions (on and off).
+
+It ships <b>opt-in and off by default</b> — <code>retrieve_any(..., collapse_near_duplicates=True)</code>
+or <code>boost search --collapse-near-duplicates</code> — rather than replacing
+<code>dedupe_by_content</code>'s output on the default path. Two things this card asks for are still
+open, and both need a real embedding backend (a built dense index, over a real multi-tap corpus)
+that the environment this was implemented in cannot reach — no network path to an embeddings
+provider or to the local ONNX model download, confirmed rather than assumed: <code>huggingface.co</code>
+and <code>pypi.org</code> both refuse at the network policy layer. <b>First</b>, the safety proof
+this card itself demands before defaulting the mechanism on &mdash; &ldquo;over a real corpus, at
+the chosen threshold, count clusters spanning more than one meaning&rdquo; &mdash; has not been run;
+<code>NEAR_DUPLICATE_THRESHOLD = 0.97</code> is a starting point, not a validated floor. <b>Second</b>,
+re-measuring the <code>exa search</code> case (and per-query maxima generally) against the fix needs
+that same corpus and index. Whoever runs that measurement should flip the CLI flag's default, fold
+the corpus count into this card's evidence, and only then consider this shipped.</p>
         <div class="meta">
           <span class="m">Complexity <b>M</b></span>
           <span class="m hi">Impact <b>High</b></span>
           <span class="m">Wow <b class="wow">★★★★</b></span>
-          <span class="m">10 of 10 slots on a real 466-tap install, all past byte-identical dedup</span>
+          <span class="m">mechanism + tests shipped opt-in; corpus safety proof and default-on still open</span>
         </div>
       </article>
       <!-- /ROADMAP:cards -->

{boost_skill_cli-1.2.72 → boost_skill_cli-1.2.73}/tests/functional/test_cli_discovery.py

@@ -264,6 +264,16 @@ class TestSearch:
         r = boost("search", "x", "--limit", "abc", expect=2)
         assert "invalid int value: 'abc'" in r.err
 
+    def test_collapse_near_duplicates_flag_is_a_no_op_without_a_dense_store(
+            self, boost, tapped):
+        # Opt-in and unwired into the default path (see
+        # rag.NEAR_DUPLICATE_THRESHOLD): with no dense index built, the flag
+        # must parse and change nothing about a plain BM25 search.
+        with_flag = boost("search", "commit", "messages",
+                          "--collapse-near-duplicates")
+        without_flag = boost("search", "commit", "messages")
+        assert with_flag.out == without_flag.out
+
 
 # ---------------------------------------------------------------- index
 

boost_skill_cli-1.2.73/tests/unit/test_dense_entry_vectors.py

@@ -0,0 +1,121 @@
+# Copyright the boost contributors.
+# SPDX-License-Identifier: Apache-2.0
+"""`dense.entry_vectors`: one representative embedding per entry.
+
+Feeds `rag.collapse_near_duplicate_hits`, which needs a vector per *entry*
+(keyed by ``(tap, path)``) rather than per chunk. The lowest-``cix`` chunk —
+the name+description chunk `rag.chunk` always emits first — is the
+representative, fetched from `vec_raw` through `chunks_entry`, the same index
+`_ensure_schema` documents as the reason that table is a plain rowid-keyed
+table rather than a `vec0` one: an ``id IN (...)`` against `vec0` plans as a
+full scan (see `dense._knn`).
+
+The 8-d toy fixture is shared with `test_dense_quantized.py`'s premise: 8 is
+the smallest width `bit[N]` accepts, so this is the quantized layout — the
+only one `entry_vectors` supports (a legacy float32 store has no cheap way to
+look up an arbitrary vector by id, and returns `{}` there, same as the rest of
+this module degrades on that path).
+"""
+from __future__ import annotations
+
+import math
+import sqlite3
+
+import pytest
+
+from boost_cli.core import dense, embed, rag
+
+
+def _vec_loadable() -> bool:
+    con = sqlite3.connect(":memory:")
+    try:
+        import sqlite_vec
+        con.enable_load_extension(True)
+        sqlite_vec.load(con)
+        con.enable_load_extension(False)
+        con.execute("create virtual table t using vec0(embedding bit[8])")
+        return True
+    except Exception:
+        return False
+    finally:
+        con.close()
+
+
+pytestmark = pytest.mark.skipif(
+    not _vec_loadable(), reason="sqlite-vec extension not loadable here")
+
+
+def _vec_for(seed: int) -> list[float]:
+    v = [math.sin(seed * 1.7 + i * 0.9) for i in range(8)]
+    n = math.sqrt(sum(x * x for x in v)) or 1.0
+    return [x / n for x in v]
+
+
+_BODIES = {"skill-%02d" % i: "body of skill %02d" % i for i in range(4)}
+_VEC = {name: _vec_for(i) for i, name in enumerate(sorted(_BODIES))}
+
+
+def _toy_embed(texts, input_type=None, timeout=60):
+    return [_VEC.get(t.split("\n", 1)[0].strip(), _vec_for(999)) for t in texts]
+
+
+def _e(name, tap="acme/skills"):
+    return {"name": name, "tap": tap, "kind": "skill",
+            "skill_md": "skills/%s/SKILL.md" % name}
+
+
+_ENTRIES = [_e(n) for n in sorted(_BODIES)]
+
+
+@pytest.fixture()
+def dense_env(sandbox, monkeypatch):
+    monkeypatch.setattr(embed, "embed", _toy_embed)
+    monkeypatch.setattr(embed, "provider", lambda: "openai")
+    monkeypatch.setattr(embed, "model", lambda: "toy-8")
+    monkeypatch.setattr(embed, "dimension", lambda: 8)
+    monkeypatch.setattr(embed, "available", lambda: True)
+    monkeypatch.setattr(rag, "_tap_paths", lambda: {"acme/skills": "/x"})
+    monkeypatch.setattr(rag, "_tap_commits", lambda: {"acme__skills": "c1"})
+    monkeypatch.setattr(dense, "read_body", lambda e, tp=None: e["name"])
+    return monkeypatch
+
+
+class TestEntryVectors:
+    def test_returns_the_stored_vector_for_each_entry(self, dense_env):
+        dense.build(entries=_ENTRIES, force=True)
+        keys = [("acme/skills", e["skill_md"]) for e in _ENTRIES]
+        got = dense.entry_vectors(keys)
+        assert set(got) == set(keys)
+
+    def test_the_vector_decodes_to_the_embedding_that_was_stored(self, dense_env):
+        dense.build(entries=_ENTRIES, force=True)
+        key = ("acme/skills", "skills/skill-00/SKILL.md")
+        got = dense.entry_vectors([key])
+        decoded = rag._decode_vector(got[key])
+        expected = _VEC["skill-00"]
+        assert all(math.isclose(a, b, abs_tol=1e-5)
+                  for a, b in zip(decoded, expected, strict=True))
+
+    def test_an_unknown_entry_is_absent_from_the_result(self, dense_env):
+        dense.build(entries=_ENTRIES, force=True)
+        got = dense.entry_vectors([("acme/skills", "skills/nope/SKILL.md")])
+        assert got == {}
+
+    def test_empty_input_is_empty_output(self, dense_env):
+        dense.build(entries=_ENTRIES, force=True)
+        assert dense.entry_vectors([]) == {}
+
+    def test_no_store_at_all_degrades_to_empty(self, sandbox):
+        assert dense.entry_vectors([("t", "p")]) == {}
+
+    def test_a_non_quantized_store_degrades_to_empty(self, sandbox, monkeypatch):
+        # `dim=3` keeps the legacy float32 layout (see `_quantizable`); that
+        # layout has no cheap per-id lookup, so this must not attempt one.
+        monkeypatch.setattr(embed, "dimension", lambda: 3)
+        con = dense._connect()
+        try:
+            dense._ensure_schema(con, 3)
+            con.commit()
+        finally:
+            con.close()
+        assert dense.entry_vectors([("t", "p")]) == {}