pikuri-vectordb 0.0.7 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec687bac82be3582807685133b88fa03a93099fbf082854ea8e99a5447ae3e3b
-  data.tar.gz: 8128964835740ade33e032f60aa71514997cd32a4c974fb4371031a30ba40e16
+  metadata.gz: 041cfbc12058abab95bdf6a38340c69096b49fc14b7c779aa8f30c2cece76153
+  data.tar.gz: 23e98ff1fcbdfae0fab697c632ec71cbb6a51ea6b28e32fbb80999b277cbd68a
 SHA512:
-  metadata.gz: 906cae6365352f1483ef3aa9f06399dba225d34c663f5c5a6e1e1d47880ef7f4927943cb639387bd901cf56e0f2667905e35ab811438850aedf68240907566c5
-  data.tar.gz: 3de16d8630e589d30a67067bfd36b06475840633a1c99ec451eaafb2f2cf8c9a448d80865d1c3b01d8ad0b00083ddb26f3342a44e1766c6f9ff80ccd661455af
+  metadata.gz: 3bdba1b9a8eae36a3c70f5a25eec021d35b476b8f9463b9e1a1c25a099f5905ac6edf2cade908b866ce6ec5b0dbed824c86030edba9363a7e96abe6f62d0639b
+  data.tar.gz: 16c1a6b59c540007c2386cd5df6b679f38af6bc7a3b3e31f72ad6e35a19a2a9fa7ce948eb3b7ede0f0005ad58e0a30ae8bea70a2e6fd8f12cfa8225eab3094ef

data/README.md

@@ -119,14 +119,14 @@ From a source checkout (not installed by `gem install`):
 ./pikuri-vectordb/bin/pikuri-corpus --qdrant --watch
 ```
 
-A single recall agent over `docs/guide/` (the pikuri guide itself)
+A single recall agent over `book/` (the pikuri guide itself)
 with **no egress** — its tools are the three above plus
 `calculator`; no web search, no fetch, no bash. The corpus stands
 in for private data, and an agent that can read it must not also be
 able to send it out. `--qdrant` / `--chroma` persist the index
 across runs, `--watch` keeps it live, `--no-reranker` drops the
 reranker requirement. The guide's
-[chapter 3](../docs/guide/03-vectordb.md) is the full walkthrough.
+[the vector-DB chapter](../book/vectordb.md) is the full walkthrough.
 
 ## The LIBRARIAN persona
 
@@ -157,8 +157,8 @@ whichever model each request asks for. Requires a recent enough
 `llama.cpp` build to include the
 [model-management feature](https://huggingface.co/blog/ggml-org/model-management-in-llamacpp);
 Ubuntu 26.04+ packages one. The guide's
-[chapter 1](../docs/guide/01-chat.md) walks through the setup;
-[chapter 3](../docs/guide/03-vectordb.md) adds the embedder and
+[the first-conversation chapter](../book/chat.md) walks through the setup;
+[the vector-DB chapter](../book/vectordb.md) adds the embedder and
 reranker on top.
 
 If you'd rather pin the reranker in its own process — to avoid
@@ -186,7 +186,7 @@ events for the `Watcher`; loaded only when a `Watcher` starts).
 ## Further reading
 
 - **Guide chapter:** [Agentic search and the vector
-  DB](../docs/guide/03-vectordb.md) — concepts, model setup, the
+  DB](../book/vectordb.md) — concepts, model setup, the
   no-egress argument, `--qdrant --watch` day-to-day shape.
 - **Design notes:** [`DESIGN.md`](DESIGN.md) — the Chroma-vs-Qdrant
   engine survey.

data/lib/pikuri/vector_db/backend/chroma.rb

@@ -6,147 +6,67 @@ require 'json'
 module Pikuri
   module VectorDb
     module Backend
-      # Thin Faraday HTTP client against a self-hosted Chroma
-      # server (v2 API). The persistent backend, behind the same
-      # duck-typed {Backend} protocol as {InMemory}: same method
-      # names, same return shapes, same +ArgumentError+ contract
-      # on empty input + non-positive +top_k+. Where the two
-      # diverge is the vector-dim contract — see below.
+      # Thin Faraday HTTP client against a self-hosted Chroma server (v2 API),
+      # targeting Chroma 0.5.x+. The persistent backend, behind the same
+      # duck-typed {Backend} protocol as {InMemory} (same method names, return
+      # shapes, and +ArgumentError+ contract on empty input / non-positive
+      # +top_k+; the vector-dim contract diverges — see below). Hand-rolled
+      # rather than a +chroma-db+ gem dep so the wire protocol stays auditable
+      # in one readable file; the cost is tracking the v2 API by hand.
       #
-      # The client is hand-rolled rather than a dependency on a
-      # +chroma-db+ gem: only a handful of v2 endpoints are needed
-      # (listed below), Faraday is already in the dependency closure,
-      # and a thin first-party client keeps the wire protocol
-      # auditable in one readable file — consistent with the
-      # read-it-in-an-evening ceiling. The cost is tracking Chroma's
-      # v2 API by hand if it changes.
+      # Two ways to get one: **bring your own** — +Chroma.new(host:, port:,
+      # collection:)+ against an existing deployment (this class is purely the
+      # HTTP client); or **let pikuri manage it** —
+      # {Server::Chroma.ensure_running}'s +#client(collection:)+ returns a
+      # +Chroma+ pointed at a supervised container. Docker lifecycle and HTTP
+      # wire protocol share nothing, so each is its own class.
       #
-      # == Two ways to get one
+      # v2 endpoints used: +collections+ (get-or-create), +.../upsert+,
+      # +.../query+, +.../count+, +DELETE .../{id}+, +.../delete+ (where-filtered),
+      # +.../get+ (where-filtered projection).
       #
-      # * **Bring your own.** +Backend::Chroma.new(host:, port:,
-      #   collection:)+ against an existing chroma deployment
-      #   (production cluster, docker-compose stack, a chroma
-      #   already running on the host for an unrelated project).
-      #   The host owns the process; this class is purely the
-      #   HTTP client.
-      # * **Let pikuri manage it.** {Server::Chroma.ensure_running}
-      #   spawns and supervises a chroma container under the
-      #   +pikuri-internal-chroma+ name, against a pinned image,
-      #   with a bind-mounted volume in the user's cache dir.
-      #   Its +#client(collection:)+ returns a +Backend::Chroma+
-      #   pre-pointed at the supervised container. The split is
-      #   deliberate: docker lifecycle and HTTP wire protocol
-      #   have nothing in common, so each lives in its own class.
+      # == BYO embeddings (Chroma's embedder is never invoked)
       #
-      # == Chroma v2 API
+      # Chroma collections can carry a server-side embedding function; we always
+      # send pre-computed +embeddings+ and never use it. pikuri's {Embedder} is
+      # the single source of truth — a parallel Chroma-side embedder would split
+      # it invisibly (local embedder in pikuri + +OpenAIEmbeddingFunction+ in
+      # Chroma ⇒ every indexed document silently lands at OpenAI).
       #
-      # Endpoints used:
+      # == Contracts
       #
-      # * +POST /api/v2/tenants/{tenant}/databases/{db}/collections+
-      #   with +get_or_create: true+ — idempotent collection
-      #   creation. Returns +{id, name, ...}+.
-      # * +POST /api/v2/.../collections/{id}/upsert+ — insert or
-      #   replace by id. Body carries parallel arrays of +ids+,
-      #   +embeddings+, +documents+, +metadatas+.
-      # * +POST /api/v2/.../collections/{id}/query+ — k-NN
-      #   search. Body: +{query_embeddings, n_results, include}+.
-      # * +GET /api/v2/.../collections/{id}/count+ — integer
-      #   count.
-      # * +DELETE /api/v2/.../collections/{id}+ — drop the
-      #   collection (used by +#delete_all+).
-      # * +POST /api/v2/.../collections/{id}/delete+ — metadata-
-      #   filtered delete (+{where:}+); used by +#delete_by_source+.
-      # * +POST /api/v2/.../collections/{id}/get+ — fetch rows by
-      #   +{where:}+ filter with an +include:+ projection; used by
-      #   +#sources_with_hashes+.
-      #
-      # == BYO embeddings (not Chroma's embedder)
-      #
-      # Chroma collections can carry an embedding function in
-      # their metadata — Chroma's term for what pikuri calls an
-      # {Embedder}. When configured, +add+ / +query+ accept raw
-      # text via +documents+ / +query_texts+ and Chroma embeds
-      # server-side. We deliberately don't use this: pikuri's
-      # +Embedder+ is the one source of truth for embedder
-      # choice, the provider-cliff visibility lives in pikuri's
-      # config, and a parallel Chroma-side embedder config would
-      # split the truth without pikuri noticing (e.g. local
-      # embedder in pikuri + +OpenAIEmbeddingFunction+ in Chroma
-      # — every indexed document silently lands at OpenAI). We
-      # always send pre-computed +embeddings+; Chroma's
-      # collection embedder is never invoked.
-      #
-      # == Vector-dim contract diverges from InMemory
-      #
-      # +InMemory+ enforces vector-dim consistency client-side
-      # (locks on first upsert, raises +ArgumentError+ on
-      # mismatch). +Chroma+ enforces server-side — first upsert
-      # to a collection establishes the dim; mismatched
-      # subsequent upserts produce HTTP 4xx which propagates
-      # as +RuntimeError+. Different exception class, same
-      # loud-failure shape. Documented divergence; not worth
-      # parsing Chroma's error envelope to coerce to +ArgumentError+.
-      #
-      # == Lazy collection resolution
-      #
-      # +Backend::Chroma.new+ doesn't talk to the server. The
-      # first +#upsert+ / +#query+ / +#count+ call resolves
-      # (and creates if missing) the collection by name, caches
-      # the id, and uses it thereafter. +#delete_all+ drops the
-      # collection and clears the cached id; the next +#upsert+
-      # re-creates from scratch.
-      #
-      # == Cosine distance (matches InMemory)
-      #
-      # Collection is created with +hnsw.space: 'cosine'+.
-      # Chroma returns cosine *distance* (range +[0, 2]+ where
-      # +0+ = identical, +1+ = orthogonal); +#query+ converts
-      # to similarity via +1 - distance+ so the {Backend::Result}
-      # score has the same meaning across backends.
-      #
-      # == Metadata key normalization
-      #
-      # Chroma serializes through JSON, so Symbol metadata keys
-      # become Strings on round-trip. +#upsert+ converts the
-      # incoming {Chunk}'s +metadata+ keys to Strings before
-      # sending; +#query+ converts them back to Symbols on the
-      # way out, so the {Chunk} a caller pulls from a query
-      # looks identical to one stored in InMemory. +source+
-      # rides as a special metadata key (Chroma has no native
-      # +source+ concept).
-      #
-      # == Testing posture
-      #
-      # Specs use +Faraday::Adapter::Test+ stubs only — they
-      # verify "we send what we think we're sending" against
-      # the v2 API shape but don't catch real-Chroma protocol
-      # drift. Real-Chroma smoke testing is wired into the demo
-      # binary in a later phase. Targets Chroma 0.5.x+ (v2 API).
+      # * *Vector-dim* diverges from {InMemory}: enforced server-side (first
+      #   upsert sets the dim; a mismatch is HTTP 4xx → +RuntimeError+, not the
+      #   +ArgumentError+ InMemory raises). Same loud-failure shape; not worth
+      #   parsing Chroma's error envelope to coerce the class.
+      # * *Lazy collection resolution*: +new+ doesn't touch the server; the first
+      #   +#upsert+/+#query+/+#count+ resolves (creating if missing) the
+      #   collection by name and caches the id. +#delete_all+ clears it; the next
+      #   +#upsert+ re-creates.
+      # * *Cosine*: collection created +hnsw.space: 'cosine'+; Chroma returns
+      #   *distance* +[0,2]+, +#query+ converts via +1 - distance+ so the
+      #   {Backend::Result} score matches InMemory's similarity scale.
+      # * *Metadata keys*: JSON round-trips Symbol keys to Strings, so +#upsert+
+      #   stringifies and +#query+ re-symbolizes — a queried {Chunk} looks
+      #   identical to one stored in InMemory. +source+ rides as a reserved
+      #   metadata key (Chroma has no native +source+).
       class Chroma
-        # Rows per +/get+ page in {#sources_with_hashes}. Caps the
-        # JSON burst + parse working set of the boot manifest read on
-        # a large corpus; small corpora finish in one page. Chunky but
-        # not arbitrary — one round trip per this-many *files*, and the
-        # manifest is one row per file (the +offset 0+ chunk), so a
-        # 50k-file corpus is ~50 localhost round trips instead of one
-        # multi-MB response.
+        # Rows per +/get+ page in {#sources_with_hashes} — caps the parse
+        # working set of the boot manifest on a large corpus (one row per file,
+        # so a 50k-file corpus is ~50 localhost round trips, not one multi-MB
+        # response). Small corpora finish in one page.
         MANIFEST_PAGE_SIZE = 1_000
 
         # @param host [String]
         # @param port [Integer]
-        # @param collection [String] collection name in Chroma.
-        #   This is a Chroma-specific identifier, so it lives
-        #   here rather than on +VectorDb::Extension+ (where
-        #   it'd be a no-op for +Backend::InMemory+).
-        # @param tenant [String] Chroma v2 tenant; defaults to
-        #   Chroma's own default.
-        # @param database [String] Chroma v2 database; defaults
-        #   to Chroma's own default.
-        # @param connection [Faraday::Connection, nil] optional
-        #   dependency-injection point for tests.
+        # @param collection [String] Chroma collection name — a Chroma-specific
+        #   identifier, so it lives here, not on +VectorDb::Extension+ (a no-op
+        #   for {InMemory}).
+        # @param tenant [String] Chroma v2 tenant; defaults to Chroma's default.
+        # @param database [String] Chroma v2 database; defaults to Chroma's default.
+        # @param connection [Faraday::Connection, nil] DI point for tests.
         # @return [Chroma]
-        # @raise [ArgumentError] on empty +host+ or empty
-        #   +collection+.
+        # @raise [ArgumentError] on empty +host+ or empty +collection+.
         def initialize(host:, port:, collection:,
                        tenant: 'default_tenant',
                        database: 'default_database',
@@ -167,13 +87,9 @@ module Pikuri
           end
         end
 
-        # Insert-or-replace by +chunk.id+. Parallel arrays of
-        # equal length; raises on empty input or length mismatch
-        # (same contract as {InMemory}). Chroma server enforces
-        # vector-dim consistency; mismatched dims surface as
-        # +RuntimeError+ from a 4xx response (the InMemory
-        # backend raises +ArgumentError+ for the same case —
-        # documented divergence).
+        # Insert-or-replace by +chunk.id+ (parallel equal-length arrays).
+        # Vector-dim mismatch surfaces as +RuntimeError+ server-side (InMemory
+        # raises +ArgumentError+ — see the class header).
         #
         # @param chunks [Array<Chunk>]
         # @param vectors [Array<Array<Float>>]
@@ -254,12 +170,9 @@ module Pikuri
           end
         end
 
-        # Drop the collection. Next +#upsert+ re-creates from
-        # scratch — that's the v1 nuke-and-reload reindex path
-        # the {Indexer} drives. No-op if no collection was ever
-        # created (consistent with {InMemory}'s clear-on-empty
-        # behaviour). 404 on the DELETE is treated as "already
-        # gone" — idempotent.
+        # Drop the collection (the nuke-and-reload reindex path the {Indexer}
+        # drives); the next +#upsert+ re-creates. No-op if none was created; a
+        # 404 on the DELETE is treated as "already gone" — idempotent.
         #
         # @return [void]
         def delete_all
@@ -309,22 +222,16 @@ module Pikuri
           nil
         end
 
-        # Replace all chunks for one +source+: delete the old set,
-        # then upsert the new one. The incremental-reindex unit
-        # (see {Indexer#reindex_file!}).
-        #
-        # == Not transactional (the InMemory divergence)
+        # Replace all chunks for one +source+: delete the old set, then upsert
+        # the new (the incremental-reindex unit, {Indexer#reindex_file!}).
         #
-        # These are two HTTP calls, so a +#query+ landing between
-        # them can see the source with zero chunks — a window
-        # {InMemory#replace_source} closes with its monitor but
-        # Chroma cannot, short of server-side transactions it
-        # doesn't expose. The window is small and the
-        # {Indexer} mitigates the *common* failure: it embeds
-        # before calling here, so an embedder outage never reaches
-        # this method and the old chunks stay put. Delete-then-upsert
-        # (not the reverse): upserting first then deleting by source
-        # would delete the just-written chunks.
+        # *Not transactional* (the InMemory divergence): two HTTP calls, so a
+        # +#query+ between them can see the source with zero chunks — a window
+        # {InMemory#replace_source} closes with its monitor but Chroma can't. The
+        # {Indexer} mitigates the common failure by embedding *before* calling
+        # here, so an embedder outage never reaches this and the old chunks stay.
+        # Delete-then-upsert, not the reverse — the reverse would delete the
+        # just-written chunks.
         #
         # @param source [String] the {Chunk#source} being replaced.
         # @param chunks [Array<Chunk>] the new chunk set.
@@ -338,28 +245,20 @@ module Pikuri
           nil
         end
 
-        # The boot-sweep reference: +source+ → stored content hash
-        # for every indexed document. Reads one metadata row per
-        # *file*, not per chunk, via three Chroma +/get+ knobs:
-        #
-        # * +where: { offset: 0 }+ — every file has exactly one
-        #   chunk at offset 0, so this returns one row per source.
-        # * +include: ['metadatas']+ — drops the heavy +embeddings+
-        #   and +documents+ from the response; we pull only the
-        #   metadata projection, never the vectors.
-        # * +limit+ / +offset+ — page the read in
-        #   {MANIFEST_PAGE_SIZE} chunks so a large corpus never
-        #   materializes one multi-MB response. (Two unrelated
-        #   +offset+s collide in the wording: the +where+ +offset+ is
-        #   a *chunk* metadata field; the top-level +offset+ is the
-        #   *pagination* cursor — different namespaces in the API.)
+        # The boot-sweep reference: +source+ → stored content hash, one metadata
+        # row per *file* (not per chunk) via +where: { offset: 0 }+ (every file
+        # has one chunk at offset 0), +include: ['metadatas']+ (drops the heavy
+        # embeddings/documents), and {MANIFEST_PAGE_SIZE} +limit+/+offset+
+        # paging so a large corpus never materializes one multi-MB response.
+        # (Two +offset+s collide in wording: the +where+ one is a *chunk*
+        # metadata field, the top-level one is the *pagination* cursor.)
         #
-        # Pagination assumes the manifest isn't mutating mid-read; the
-        # {Watcher} drives this from its single worker thread, so no
-        # reindex runs concurrently with the boot sweep that calls it.
+        # Pagination assumes the manifest isn't mutating mid-read; the {Watcher}
+        # drives this from its single worker thread, so no reindex runs
+        # concurrently.
         #
-        # @return [Hash{String => String, nil}] +source+ → content
-        #   hash. Empty when the collection doesn't exist yet.
+        # @return [Hash{String => String, nil}] +source+ → content hash. Empty
+        #   when the collection doesn't exist yet.
         # @raise [RuntimeError] on HTTP failure.
         def sources_with_hashes
           return {} if @collection_id.nil? && !collection_exists?

data/lib/pikuri/vector_db/backend/in_memory.rb

@@ -5,72 +5,40 @@ require 'monitor'
 module Pikuri
   module VectorDb
     module Backend
-      # Pure-Ruby vector store. The educational default backend —
-      # the "small enough to audit" first stop the demo + guide walk
-      # through before promoting users to +Chroma+ for persistence.
+      # Pure-Ruby vector store — the educational default backend, the "small
+      # enough to audit" first stop before users promote to {Qdrant} / {Chroma}
+      # for persistence. Holds a Hash from chunk id to +[Chunk, vector]+;
+      # +#query+ scores cosine similarity against every stored vector, O(n) per
+      # query — fine for thousands of chunks (a notes folder), slow for millions.
       #
-      # == What it does
+      # Deliberately no persistence (RAM-only; reloads from sources every boot,
+      # which is *why* it's the teaching shape — the boot code path is the one a
+      # newcomer inspects to learn what "indexing" means) and no approximate-search
+      # index (exhaustive scan; HNSW/IVF adds complexity that teaches nothing once
+      # the cosine math is clear).
       #
-      # Holds an in-memory Hash from chunk id to +[Chunk, vector]+;
-      # +#query+ computes cosine similarity against every stored
-      # vector, sorts descending, returns the top-k as
-      # +Backend::Result+ instances. O(n) per query, where n is
-      # the number of stored chunks. Fine for thousands of chunks
-      # (a personal notes folder, a single product's docs); slow
-      # for millions (a full corporate knowledge base — that's the
-      # +Chroma+ use case).
+      # == Thread-safe (the one backend that locks)
       #
-      # == What it deliberately doesn't do
+      # Every method runs under a reentrant +Monitor+ — real concurrency once
+      # auto-watch is wired (the main thread queries while the {Watcher} thread
+      # replaces/deletes). The lock's load-bearing job is {#replace_source}: it
+      # holds the monitor across the delete-then-upsert so a concurrent +#query+
+      # never sees the zero-chunk gap. +Monitor+ not +Mutex+ because
+      # +#replace_source+ re-enters via +#delete_by_source+ + +#upsert+. Chroma
+      # / Qdrant need no client-side lock — the server serializes.
       #
-      # * **No persistence.** RAM-only, intentional — the user who
-      #   wants persistence picks +Chroma+. Reloads from sources on
-      #   every boot, which makes the in-memory backend the natural
-      #   teaching shape: the same code path the demo binary walks
-      #   on startup is the one the user inspects when they're
-      #   learning what "indexing" actually means.
-      # * **No approximate search.** Exhaustive scan. Approximate
-      #   nearest neighbor (HNSW, IVF) adds complexity that doesn't
-      #   teach anything additional once the cosine math is clear.
-      # * **No approximate-search index.** Exhaustive scan only.
-      #
-      # == Thread safety
-      #
-      # Every public method runs under a single reentrant
-      # +Monitor+. The agent's main thread calls +#query+ while a
-      # background {Watcher} thread calls +#replace_source+ /
-      # +#delete_by_source+, so concurrent access is real once
-      # auto-watch is wired. The lock's load-bearing job is
-      # {#replace_source}: it holds the monitor across the
-      # delete-then-upsert so a concurrent +#query+ never observes
-      # the gap where a source has zero chunks. +Monitor+ (not a
-      # bare +Mutex+) because +#replace_source+ re-enters the lock
-      # via +#delete_by_source+ + +#upsert+, which a non-reentrant
-      # +Mutex+ would deadlock on. +Chroma+ needs no client-side
-      # lock — the server serializes — so this is the one backend
-      # that locks.
-      #
-      # == Cosine, not dot product
-      #
-      # Some embedders return pre-normalized vectors (text-embedding-3,
-      # most sentence-transformers); others don't. Cosine normalizes
-      # at compute time, so the backend works regardless of whether
-      # the embedder did. The readable two-pass form below (compute
-      # dot + magnitudes separately) is intentional over the
-      # single-loop micro-optimization — this is the file the
-      # newcomer reads to understand what's happening.
+      # Cosine (not dot product) so the backend works whether or not the embedder
+      # pre-normalizes; the readable two-pass {#cosine} is intentional over a
+      # single-loop micro-opt — this is the file the newcomer reads.
       class InMemory
         # @return [InMemory]
         def initialize
           # id (String) → [Chunk, vector (Array<Float>)]
           @entries = {}
-          # Dimension of every stored vector. +nil+ before the first
-          # +#upsert+; locked to the dim of the first vector seen and
-          # enforced for every subsequent +#upsert+ + +#query+ — see
-          # the Backend protocol's "Vector-dim contract" yardoc.
+          # Vector dim; +nil+ until the first +#upsert+ locks it, then enforced
+          # on every +#upsert+/+#query+ — see the Backend "Vector-dim contract".
           @dim = nil
-          # Reentrant so +#replace_source+ can call +#delete_by_source+
-          # + +#upsert+ while holding the lock — see the class yardoc's
-          # "Thread safety" section.
+          # Reentrant — see the class header's "Thread-safe" section.
           @lock = Monitor.new
         end
 
@@ -167,20 +135,17 @@ module Pikuri
           nil
         end
 
-        # Atomically replace all chunks for one +source+: delete the
-        # old set, then upsert the new one, under a single hold of the
-        # monitor. The incremental-reindex unit (see {Indexer#reindex_file!}).
-        # Holding the lock across both halves is the point — a
-        # concurrent {#query} sees either the old chunks or the new
-        # ones, never the empty gap between.
+        # Atomically replace all chunks for one +source+ (delete-then-upsert
+        # under a single monitor hold — the point: a concurrent {#query} sees
+        # the old or new chunks, never the empty gap). The incremental-reindex
+        # unit (see {Indexer#reindex_file!}).
         #
         # @param source [String] the {Chunk#source} being replaced.
-        # @param chunks [Array<Chunk>] the new chunk set; every
-        #   +chunk.source+ should equal +source+.
+        # @param chunks [Array<Chunk>] the new chunk set (each +chunk.source+
+        #   should equal +source+).
         # @param vectors [Array<Array<Float>>] parallel to +chunks+.
         # @return [void]
-        # @raise [ArgumentError] on empty input, length mismatch, or
-        #   vector-dim mismatch (from the inner {#upsert}).
+        # @raise [ArgumentError] on empty input, length or vector-dim mismatch.
         def replace_source(source:, chunks:, vectors:)
           @lock.synchronize do
             delete_by_source(source)
@@ -189,17 +154,13 @@ module Pikuri
           nil
         end
 
-        # The boot-sweep reference: a map from each indexed +source+
-        # to the content hash stored on its chunks. {Watcher} (via
-        # {Indexer#reconcile_plan}) diffs this against the hashes of
-        # the files currently on disk to decide what to reindex.
-        # Built from chunk metadata; a chunk indexed before the
-        # +hash+ metadata existed maps its source to +nil+, which the
-        # diff treats as "changed" and reindexes — self-healing.
+        # The boot-sweep reference: each indexed +source+ → the content hash on
+        # its chunks, which {Indexer#reconcile_plan} diffs against disk. A chunk
+        # with no +hash+ metadata maps to +nil+, which the diff treats as
+        # "changed" and reindexes — self-healing.
         #
-        # @return [Hash{String => String, nil}] +source+ → content
-        #   hash. Empty when nothing is indexed (the InMemory case at
-        #   every boot, since RAM resets).
+        # @return [Hash{String => String, nil}] +source+ → content hash. Empty
+        #   when nothing is indexed (the InMemory case at every boot).
         def sources_with_hashes
           @lock.synchronize do
             result = {}
@@ -225,15 +186,12 @@ module Pikuri
 
         private
 
-        # Cosine similarity. Two-pass form is the readable shape;
-        # micro-optimizing into a single loop saves an array
-        # traversal but obscures what's happening for the reader
-        # who's here to learn how a vector store works.
+        # Cosine similarity (readable two-pass — see the class header).
         #
         # @param a [Array<Float>]
         # @param b [Array<Float>]
-        # @return [Float] cosine in +[-1.0, 1.0]+, or +0.0+ if
-        #   either vector is zero (degenerate but valid input).
+        # @return [Float] cosine in +[-1.0, 1.0]+, or +0.0+ if either vector is
+        #   zero (degenerate but valid input).
         def cosine(a, b)
           dot = a.zip(b).sum { |x, y| x * y }
           mag_a = Math.sqrt(a.sum { |x| x * x })