embedflow 0.7.0__tar.gz → 0.8.0__tar.gz

{embedflow-0.7.0 → embedflow-0.8.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.8.0 — Traffic-aware target-vector prewarming
+
+- Added bounded `prewarm plan`, `prewarm run`, and `prewarm status` workflows
+  that select uncached target documents by observed Shadow Mode candidate
+  occurrences.
+- Added privacy-safe aggregate document popularity telemetry, content/model
+  fingerprint checks, deterministic tie-breaking, hard document/storage/time
+  budgets, atomic plan/run artifacts, and resumable materialization through the
+  existing target cache and worker.
+- Observed candidate-occurrence coverage remains an operational warming signal;
+  it is not retrieval quality or recall evidence.
+
 ## v0.7.0 — Source-authoritative Shadow Mode
 
 - Added bounded, deterministic, source-authoritative Shadow Mode for observing

{embedflow-0.7.0 → embedflow-0.8.0}/CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 title: "EmbedFlow: Upgrading Legacy Embeddings Without Full Upfront Re-Embedding"
 message: "If EmbedFlow contributes to your work, please cite this software release."
 type: software
-version: 0.7.0
-date-released: 2026-09-13
+version: 0.8.0
+date-released: 2026-09-15
 repository-code: "https://github.com/arnsri33/embedflow"
 url: "https://github.com/arnsri33/embedflow"
 license: AGPL-3.0-only

{embedflow-0.7.0 → embedflow-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: embedflow
-Version: 0.7.0
+Version: 0.8.0
 Summary: Progressive embedding-model migration over existing vector indexes.
 Author: Arnav Srivastav
 License-Expression: AGPL-3.0-only
@@ -224,6 +224,17 @@ Reports contain operational and ranking-disagreement diagnostics—not qrel-base
 quality guarantees—and recommendations never route canary traffic. See the
 [Shadow Mode guide](https://github.com/arnsri33/embedflow/blob/main/docs/shadow-mode.md).
 
+After collecting Shadow traffic, prioritize uncached target vectors by observed
+candidate popularity:
+
+```bash
+embedflow prewarm plan --config ./embedflow.yaml --since 24h --max-docs 50000 --output prewarm-plan.json
+embedflow prewarm run --config ./embedflow.yaml --plan prewarm-plan.json
+```
+
+Observed candidate-occurrence coverage is an operational warming signal, not
+retrieval quality or recall. See the [prewarming guide](https://github.com/arnsri33/embedflow/blob/main/docs/prewarming.md).
+
 ## Research
 
 For candidate depth `K`, EmbedFlow measures:
@@ -278,7 +289,7 @@ cover the remaining commands and endpoints.
 
 ## Status
 
-EmbedFlow v0.7.0 is a pre-1.0 release for research and early real-world
+EmbedFlow v0.8.0 is a pre-1.0 release for research and early real-world
 testing. T2-v1 is an empirical finite-tail diagnostic, partial rankings can
 differ from fully warm target reranking, and ANN fidelity needs a reference
 comparison to audit.

{embedflow-0.7.0 → embedflow-0.8.0}/README.md

@@ -174,6 +174,17 @@ coverage, latency, and ranking-disagreement diagnostics; it does not claim
 retrieval-quality preservation without qrels and never routes canary traffic.
 See [`docs/shadow-mode.md`](https://github.com/arnsri33/embedflow/blob/main/docs/shadow-mode.md).
 
+After collecting Shadow traffic, prioritize uncached target vectors by observed
+candidate popularity:
+
+```bash
+embedflow prewarm plan --config ./embedflow.yaml --since 24h --max-docs 50000 --output prewarm-plan.json
+embedflow prewarm run --config ./embedflow.yaml --plan prewarm-plan.json
+```
+
+Observed candidate-occurrence coverage is an operational warming signal, not
+retrieval quality or recall. See [`docs/prewarming.md`](https://github.com/arnsri33/embedflow/blob/main/docs/prewarming.md).
+
 Search responses expose `COLD`, `PARTIAL`, or `WARM`, cache hits and misses,
 synchronous work, queued work, and stage timings. Once the candidate vectors
 are warm, target scoring over that candidate set is deterministic.
@@ -288,7 +299,7 @@ OpenAPI documentation; see
 
 ## Status
 
-EmbedFlow v0.7.0 is a pre-1.0 release for research and early real-world
+EmbedFlow v0.8.0 is a pre-1.0 release for research and early real-world
 testing.
 
 - T2-v1 reports an empirical finite-tail diagnostic.

{embedflow-0.7.0 → embedflow-0.8.0}/README_PYPI.md

@@ -158,6 +158,17 @@ Reports contain operational and ranking-disagreement diagnostics—not qrel-base
 quality guarantees—and recommendations never route canary traffic. See the
 [Shadow Mode guide](https://github.com/arnsri33/embedflow/blob/main/docs/shadow-mode.md).
 
+After collecting Shadow traffic, prioritize uncached target vectors by observed
+candidate popularity:
+
+```bash
+embedflow prewarm plan --config ./embedflow.yaml --since 24h --max-docs 50000 --output prewarm-plan.json
+embedflow prewarm run --config ./embedflow.yaml --plan prewarm-plan.json
+```
+
+Observed candidate-occurrence coverage is an operational warming signal, not
+retrieval quality or recall. See the [prewarming guide](https://github.com/arnsri33/embedflow/blob/main/docs/prewarming.md).
+
 ## Research
 
 For candidate depth `K`, EmbedFlow measures:
@@ -212,7 +223,7 @@ cover the remaining commands and endpoints.
 
 ## Status
 
-EmbedFlow v0.7.0 is a pre-1.0 release for research and early real-world
+EmbedFlow v0.8.0 is a pre-1.0 release for research and early real-world
 testing. T2-v1 is an empirical finite-tail diagnostic, partial rankings can
 differ from fully warm target reranking, and ANN fidelity needs a reference
 comparison to audit.

{embedflow-0.7.0 → embedflow-0.8.0}/docs/cli.md

@@ -11,6 +11,9 @@ embedflow analyze --config ./embedflow.yaml --output-dir ./analysis
 embedflow evaluate --config ./experiment.yaml --output-dir ./results
 embedflow plan --config ./embedflow.yaml --queries ./probe_queries.jsonl
 embedflow shadow report --config ./embedflow.yaml --since 24h
+embedflow prewarm plan --config ./embedflow.yaml --since 24h --max-docs 50000 --output prewarm-plan.json
+embedflow prewarm run --config ./embedflow.yaml --plan prewarm-plan.json
+embedflow prewarm status --config ./embedflow.yaml
 ```
 
 `analyze` is the no-target-index workflow. It uses probe queries and frozen
@@ -41,7 +44,13 @@ embedflow export-target --config ./embedflow.yaml --output-index ./target.index
 `status` reports cache coverage, hit/miss counters, queue depth, and
 materialization throughput. `audit-index` checks the source index against an
 exact/reference configuration where supported. `prewarm` schedules target
-document work; it does not change source-index results.
+document work; it does not change source-index results. `prewarm plan` ranks
+uncached IDs by privacy-safe Shadow candidate occurrence counts and is always
+bounded by `--max-docs` (or the configured `prewarm.max_docs`). `prewarm run`
+refuses mismatched/tampered fingerprints, skips vectors that became warm, and
+uses the existing durable materializer. Observed candidate-occurrence coverage
+is not retrieval quality or recall. Use `--docs-per-second` and
+`--gpu-hourly-cost` only for explicitly labeled modeled economics.
 
 Use `embedflow serve --mode shadow` to opt into source-authoritative Shadow
 Mode for one process. `embedflow shadow report` reads the bounded telemetry

{embedflow-0.7.0 → embedflow-0.8.0}/docs/configuration.md

@@ -77,6 +77,18 @@ planner:
   corpus_name: null
   corpus_fingerprint: null
 
+# Optional bounded traffic-aware target-cache prewarming defaults. CLI flags
+# override these values for one invocation; there is no implicit full-corpus
+# prewarm operation.
+prewarm:
+  max_docs: 1000
+  strategy: traffic_hotset
+  target_observed_coverage: null
+  max_storage_gb: null
+  max_runtime_seconds: null
+  batch_size: null
+  max_retries: null
+
 # Source-authoritative observation mode.  ``runtime.mode: migration`` (the
 # default) leaves Shadow Mode inactive.  ``mode: shadow`` is an explicit opt-in.
 runtime:

{embedflow-0.7.0 → embedflow-0.8.0}/docs/limitations.md

@@ -1,6 +1,6 @@
 # Limitations and release scope
 
-EmbedFlow v0.7.0 is a pre-1.0 release for research and early real-world
+EmbedFlow v0.8.0 is a pre-1.0 release for research and early real-world
 testing. The serving path is designed to make migration experiments concrete;
 production rollout still requires application-specific validation.
 

embedflow-0.8.0/docs/prewarming.md

@@ -0,0 +1,84 @@
+# Traffic-aware prewarming
+
+Traffic-aware prewarming uses privacy-safe Shadow Mode aggregates to select the
+uncached target documents that occurred most often in the source candidate
+pool. It is a bounded operational warming tool in the existing migration
+workflow:
+
+```text
+PLAN -> SHADOW -> PREWARM -> CANARY -> MIGRATE
+```
+
+It never writes the source index. `prewarm plan` only reads Shadow telemetry
+and the target cache. `prewarm run` delegates document lookup, target encoding,
+and cache writes to the existing materialization worker.
+
+## Plan and run
+
+```bash
+embedflow prewarm plan \
+  --config embedflow.yaml --since 24h --max-docs 50000 \
+  --output prewarm-plan.json
+embedflow prewarm run --config embedflow.yaml --plan prewarm-plan.json
+embedflow prewarm status --config embedflow.yaml
+```
+
+Plans are schema-versioned (`schema_version: 1`), deterministically ranked by
+`candidate_occurrences DESC, document_id ASC`, and fingerprinted with the
+source/target contracts, source-index identity, candidate K, and Shadow
+configuration. Execution refuses a stale or tampered plan. A plan is always
+bounded by `max_docs`; there is no implicit full-corpus operation.
+
+Optional configuration defaults are available under `prewarm`:
+
+```yaml
+prewarm:
+  max_docs: 1000
+  strategy: traffic_hotset
+  batch_size: 32
+  max_retries: 3
+```
+
+`--target-observed-coverage`, `--max-storage-gb`, and `--max-runtime` (when a
+real measured/user-supplied `--docs-per-second` is supplied) further reduce
+the hard selection cap. `--gpu-hourly-cost` (or the existing planner/economics
+configuration value) adds a user-supplied modeled cost. Runtime, cost, and
+storage values are explicitly marked as modeled/unknown; no cloud price or
+throughput is guessed.
+
+## Coverage and privacy
+
+The plan reports **observed candidate-occurrence coverage**:
+
+```text
+occurrences with a valid target vector / all source candidate occurrences
+```
+
+This is not retrieval coverage, recall, nDCG, or a guarantee of migration
+quality. It only describes the selected Shadow window and candidate K. Ties are
+stable, and current target-cache entries count as warm only when their target
+model and (when document text is available) content fingerprints match. Legacy
+cache rows created before content bindings were introduced remain usable but
+are treated as content-unknown.
+
+Shadow aggregation stores document IDs and counters, not raw query text,
+document text, vectors, or credentials. Treat the generated plan/ID list as
+application data because selected document IDs are needed to execute it.
+
+## Resume and idempotence
+
+The runner stores a plan-specific queue/state beside the target cache and uses
+the target cache as the execution source of truth. Re-running a completed plan
+skips already-warm vectors. Interrupts leave completed vectors valid and a
+subsequent run can continue the remaining IDs. Documents that disappear or
+change are resolved again at run time; stale content is not silently reused.
+
+Two concurrent runners use the existing durable queue/cache deduplication. The
+queue is at-least-once under process crashes, so operators should inspect
+`prewarm status` and the run report for failures.
+
+The source FAISS/Qdrant/pgvector/Pinecone/Milvus/Weaviate index is never
+created, altered, rebuilt, upserted, or deleted by this feature. The API for
+prewarming is currently Python/core plus CLI; dashboard execution controls are
+intentionally not added to avoid turning an advisory plan into autonomous
+traffic routing.

{embedflow-0.7.0 → embedflow-0.8.0}/docs/releasing.md

@@ -18,8 +18,8 @@ python -m twine check dist/*
 Inspect both archives before uploading:
 
 ```bash
-unzip -l dist/embedflow-0.7.0-py3-none-any.whl
-tar -tzf dist/embedflow-0.7.0.tar.gz
+unzip -l dist/embedflow-0.8.0-py3-none-any.whl
+tar -tzf dist/embedflow-0.8.0.tar.gz
 sha256sum dist/*
 ```
 
@@ -32,7 +32,7 @@ Test the wheel outside the source tree:
 ```bash
 python -m venv /tmp/embedflow-wheel-test
 /tmp/embedflow-wheel-test/bin/python -m pip install --upgrade pip
-/tmp/embedflow-wheel-test/bin/python -m pip install dist/embedflow-0.7.0-py3-none-any.whl
+/tmp/embedflow-wheel-test/bin/python -m pip install dist/embedflow-0.8.0-py3-none-any.whl
 cd /tmp
 /tmp/embedflow-wheel-test/bin/python -c "import embedflow; print(embedflow.__version__)"
 /tmp/embedflow-wheel-test/bin/embedflow --help
@@ -65,7 +65,7 @@ python -m venv /tmp/embedflow-testpypi
 /tmp/embedflow-testpypi/bin/python -m pip install \
   --index-url https://test.pypi.org/simple/ \
   --extra-index-url https://pypi.org/simple/ \
-  embedflow==0.7.0
+  embedflow==0.8.0
 cd /tmp
 /tmp/embedflow-testpypi/bin/python -c "import embedflow; print(embedflow.__version__)"
 /tmp/embedflow-testpypi/bin/embedflow --help
@@ -79,7 +79,7 @@ Test optional integrations in a second clean environment:
 /tmp/embedflow-testpypi/bin/python -m pip install \
   --index-url https://test.pypi.org/simple/ \
   --extra-index-url https://pypi.org/simple/ \
-  "embedflow[faiss,dashboard,pinecone,milvus,weaviate]==0.7.0"
+  "embedflow[faiss,dashboard,pinecone,milvus,weaviate]==0.8.0"
 ```
 
 If the same filename already exists on TestPyPI, use a pre-release for the
@@ -115,7 +115,7 @@ above keeps the test step explicit.
 3. Run the final release gate and review the generated report.
 4. Configure the PyPI pending publisher and protected `pypi` environment.
 5. Create a Git tag and GitHub Release for the exact package version, for
-   example `v0.7.0`.
+   example `v0.8.0`.
 6. Approve the `pypi` environment when the release workflow is ready.
 7. Verify the files and metadata on PyPI.
 8. Install from production PyPI in a directory outside this checkout.

embedflow-0.8.0/embedflow/__init__.py

@@ -0,0 +1,59 @@
+"""EmbedFlow: progressive embedding-model migration for existing indexes."""
+
+__version__ = "0.8.0"
+
+from .config import (
+    EmbedFlowConfig,
+    PlannerConfig,
+    PrewarmConfig,
+    RuntimeConfig,
+    ShadowConfig,
+    ShadowTelemetryConfig,
+    load_config,
+)
+from .prewarm import PrewarmPlan, PrewarmPlanner, PrewarmRunner, TrafficHotsetPlanner, load_prewarm_plan
+
+
+def plan(*args, **kwargs):
+    """Generate an advisory migration plan without changing source traffic."""
+    from .planner import plan_migration
+    return plan_migration(*args, **kwargs)
+
+
+def migrate(*args, **kwargs):
+    """Start progressive migration over an existing FAISS, Qdrant, pgvector, Pinecone, Milvus, or Weaviate index.
+
+    Imported lazily to keep the lightweight configuration package free of
+    model-serving dependencies at import time.  See ``embedflow.migration``
+    for the ``MigrationSession`` type.
+    """
+    from .migration.facade import migrate as _migrate
+    return _migrate(*args, **kwargs)
+
+
+def analyze_migration(*args, **kwargs):
+    """Run the leakage-safe no-target-index analysis programmatically."""
+    from .analysis import analyze_migration as _analyze_migration
+    return _analyze_migration(*args, **kwargs)
+
+
+def prewarm_plan(telemetry, cache, **kwargs):
+    """Build a bounded traffic-hotset plan through the reusable API.
+
+    Planner-constructor options and ``plan`` options may be supplied together;
+    recognized plan options are routed to :meth:`PrewarmPlanner.plan`.
+    """
+    plan_keys = {"since_seconds", "start", "end", "max_docs", "target_observed_coverage",
+                 "max_storage_gb", "max_runtime_seconds", "docs_per_second", "gpu_hourly_cost", "strategy"}
+    plan_kwargs = {key: kwargs.pop(key) for key in tuple(kwargs) if key in plan_keys}
+    return PrewarmPlanner(telemetry, cache, **kwargs).plan(**plan_kwargs)
+
+
+def prewarm_run(plan, *args, **kwargs):
+    """Execute a validated prewarm plan through the existing materializer."""
+    run_keys = {"max_runtime_seconds", "progress"}
+    run_kwargs = {key: kwargs.pop(key) for key in tuple(kwargs) if key in run_keys}
+    return PrewarmRunner(*args, **kwargs).run(plan, **run_kwargs)
+
+
+__all__ = ["EmbedFlowConfig", "PlannerConfig", "PrewarmConfig", "RuntimeConfig", "ShadowConfig", "ShadowTelemetryConfig", "load_config", "migrate", "plan", "analyze_migration", "prewarm_plan", "prewarm_run", "PrewarmPlan", "PrewarmPlanner", "TrafficHotsetPlanner", "PrewarmRunner", "load_prewarm_plan", "__version__"]

{embedflow-0.7.0 → embedflow-0.8.0}/embedflow/cache/base.py

@@ -8,15 +8,15 @@ import numpy as np
 
 class TargetVectorCache(ABC):
     @abstractmethod
-    def get(self, document_ids: list[str]) -> dict[str, np.ndarray]:
+    def get(self, document_ids: list[str], content_fingerprints: Any = None) -> dict[str, np.ndarray]:
         raise NotImplementedError
 
     @abstractmethod
-    def put(self, document_ids: list[str], vectors: np.ndarray) -> None:
+    def put(self, document_ids: list[str], vectors: np.ndarray, content_fingerprints: Any = None) -> None:
         raise NotImplementedError
 
     @abstractmethod
-    def contains(self, document_ids: list[str]) -> set[str]:
+    def contains(self, document_ids: list[str], content_fingerprints: Any = None) -> set[str]:
         raise NotImplementedError
 
     @abstractmethod

{embedflow-0.7.0 → embedflow-0.8.0}/embedflow/cache/persistent_cache.py

@@ -4,6 +4,7 @@ import hashlib
 import sqlite3
 import threading
 import time
+from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
 
@@ -25,7 +26,7 @@ class SQLiteVectorCache(TargetVectorCache):
     _LOOKUP_BATCH_SIZE = 900
 
     def __init__(self, path: str | Path, model_fingerprint: str, dimension: int,
-                 dtype: str = "float32"):
+                 dtype: str = "float32", *, read_only: bool = False):
         p = Path(path)
         if p.suffix in {".sqlite", ".sqlite3", ".db"}:
             self.db_path = p
@@ -33,7 +34,13 @@ class SQLiteVectorCache(TargetVectorCache):
         else:
             self.root = p
             self.db_path = p / "cache.sqlite3"
-        self.root.mkdir(parents=True, exist_ok=True)
+        self.read_only = bool(read_only)
+        # A planning/status inspection must not create a cache directory or
+        # migrate its schema.  Normal serving retains the historical
+        # create-or-open behavior; read-only callers use SQLite's URI mode and
+        # receive an empty view when the cache has not been initialized yet.
+        if not self.read_only:
+            self.root.mkdir(parents=True, exist_ok=True)
         self.model_fingerprint = str(model_fingerprint).strip()
         if not self.model_fingerprint:
             raise ValueError("model_fingerprint must be non-empty")
@@ -53,7 +60,20 @@ class SQLiteVectorCache(TargetVectorCache):
             raise ValueError("cache dtype must be a numeric vector dtype")
         self._lock = threading.RLock()
         self._db = None
+        self._has_content_fingerprint = True
+        self._has_target_vectors = True
         try:
+            if self.read_only:
+                if self.db_path.exists():
+                    self._db = sqlite3.connect(f"file:{self.db_path}?mode=ro", uri=True,
+                                                check_same_thread=False, timeout=30)
+                    self._db.execute("PRAGMA busy_timeout=30000")
+                    columns = {str(row[1]) for row in self._db.execute(
+                        "PRAGMA table_info(target_vectors)").fetchall()}
+                    self._has_target_vectors = bool(columns)
+                    self._has_content_fingerprint = "content_fingerprint" in columns
+                self._closed = False
+                return
             self._db = sqlite3.connect(str(self.db_path), check_same_thread=False, timeout=30)
             self._db.execute("PRAGMA busy_timeout=30000")
             self._db.execute("PRAGMA journal_mode=WAL")
@@ -67,8 +87,18 @@ class SQLiteVectorCache(TargetVectorCache):
                 checksum TEXT NOT NULL,
                 created_at REAL NOT NULL,
                 accessed_at REAL NOT NULL,
+                content_fingerprint TEXT,
                 PRIMARY KEY(document_id, model_fingerprint)
             )""")
+            # Caches created by pre-0.8 releases do not have a content
+            # fingerprint.  Keep those vectors readable for existing serving
+            # callers, while allowing prewarming to require a current-content
+            # match when one is available.
+            columns = {str(row[1]) for row in self._db.execute("PRAGMA table_info(target_vectors)").fetchall()}
+            if "content_fingerprint" not in columns:
+                self._db.execute("ALTER TABLE target_vectors ADD COLUMN content_fingerprint TEXT")
+            self._has_content_fingerprint = True
+            self._has_target_vectors = True
             self._db.execute("CREATE INDEX IF NOT EXISTS idx_target_vectors_model ON target_vectors(model_fingerprint)")
             self._db.execute("""CREATE TABLE IF NOT EXISTS cache_counters (
                 model_fingerprint TEXT PRIMARY KEY,
@@ -92,7 +122,7 @@ class SQLiteVectorCache(TargetVectorCache):
         self._closed = False
 
     def _ensure_open(self) -> None:
-        if self._closed or self._db is None:
+        if self._closed or (self._db is None and not self.read_only):
             raise RuntimeError("target vector cache is closed")
 
     def _decode(self, row: tuple[Any, ...]) -> np.ndarray:
@@ -106,20 +136,53 @@ class SQLiteVectorCache(TargetVectorCache):
             raise CacheCorruptionError(f"invalid cached vector for document {document_id}")
         return value.astype("float32", copy=False)
 
-    def get(self, document_ids: list[str]) -> dict[str, np.ndarray]:
+    @staticmethod
+    def content_fingerprint(text: Any) -> str:
+        """Return the stable fingerprint used to bind a vector to content."""
+        return hashlib.sha256(str(text).encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def _normalize_content_fingerprints(document_ids: list[str], values: Any) -> dict[str, str] | None:
+        if values is None:
+            return None
+        if isinstance(values, Mapping):
+            return {str(key): str(value) for key, value in values.items()}
+        try:
+            sequence = list(values)
+        except TypeError as exc:
+            raise ValueError("content_fingerprints must be a mapping or sequence") from exc
+        if len(sequence) != len(document_ids):
+            raise ValueError("content_fingerprints must match document_ids length")
+        return {str(document_id): str(value) for document_id, value in zip(document_ids, sequence)}
+
+    def get(self, document_ids: list[str], content_fingerprints: Any = None) -> dict[str, np.ndarray]:
+        if self.read_only:
+            # Preserve the familiar lookup contract for inspection callers
+            # without updating hit/miss/access timestamps in a read-only
+            # SQLite connection.
+            return self.peek(document_ids, content_fingerprints=content_fingerprints)
         ids = [str(x) for x in document_ids]
         if not ids: return {}
+        expected_content = self._normalize_content_fingerprints(ids, content_fingerprints)
         with self._lock:
             self._ensure_open()
             rows: list[tuple[Any, ...]] = []
             for start in range(0, len(ids), self._LOOKUP_BATCH_SIZE):
                 chunk = ids[start:start + self._LOOKUP_BATCH_SIZE]
                 placeholders = ",".join("?" for _ in chunk)
+                columns = ",content_fingerprint" if self._has_content_fingerprint else ""
                 rows.extend(self._db.execute(
-                    f"SELECT document_id,model_fingerprint,dimension,dtype,vector,checksum,created_at,accessed_at "
+                    f"SELECT document_id,model_fingerprint,dimension,dtype,vector,checksum,created_at,accessed_at{columns} "
                     f"FROM target_vectors WHERE model_fingerprint=? AND document_id IN ({placeholders})",
                     [self.model_fingerprint, *chunk]).fetchall())
             now = time.time()
+            if expected_content is not None:
+                # Rows from pre-0.8 caches have no content binding.  Preserve
+                # their historical serving behavior while requiring an exact
+                # match whenever a binding is present (new writes and
+                # materialized vectors).
+                if self._has_content_fingerprint:
+                    rows = [row for row in rows if row[8] is None or str(row[8]) == expected_content.get(str(row[0]))]
             values = {str(row[0]): self._decode(row) for row in rows}
             if rows:
                 self._db.executemany("UPDATE target_vectors SET accessed_at=? WHERE document_id=? AND model_fingerprint=?",
@@ -141,7 +204,7 @@ class SQLiteVectorCache(TargetVectorCache):
             self._db.commit()
             return values
 
-    def peek(self, document_ids: list[str]) -> dict[str, np.ndarray]:
+    def peek(self, document_ids: list[str], content_fingerprints: Any = None) -> dict[str, np.ndarray]:
         """Read cached vectors without changing hit/miss telemetry.
 
         Shadow analysis with ``materialize=false`` must not make ordinary
@@ -152,19 +215,27 @@ class SQLiteVectorCache(TargetVectorCache):
         ids = [str(x) for x in document_ids]
         if not ids:
             return {}
+        expected_content = self._normalize_content_fingerprints(ids, content_fingerprints)
         with self._lock:
             self._ensure_open()
+            if self._db is None or not self._has_target_vectors:
+                return {}
             rows: list[tuple[Any, ...]] = []
             for start in range(0, len(ids), self._LOOKUP_BATCH_SIZE):
                 chunk = ids[start:start + self._LOOKUP_BATCH_SIZE]
                 placeholders = ",".join("?" for _ in chunk)
+                columns = ",content_fingerprint" if self._has_content_fingerprint else ""
                 rows.extend(self._db.execute(
-                    f"SELECT document_id,model_fingerprint,dimension,dtype,vector,checksum,created_at,accessed_at "
+                    f"SELECT document_id,model_fingerprint,dimension,dtype,vector,checksum,created_at,accessed_at{columns} "
                     f"FROM target_vectors WHERE model_fingerprint=? AND document_id IN ({placeholders})",
                     [self.model_fingerprint, *chunk]).fetchall())
+            if expected_content is not None and self._has_content_fingerprint:
+                rows = [row for row in rows if row[8] is None or str(row[8]) == expected_content.get(str(row[0]))]
             return {str(row[0]): self._decode(row) for row in rows}
 
-    def put(self, document_ids: list[str], vectors: np.ndarray) -> None:
+    def put(self, document_ids: list[str], vectors: np.ndarray, content_fingerprints: Any = None) -> None:
+        if self.read_only:
+            raise RuntimeError("target vector cache is read-only")
         ids = [str(x) for x in document_ids]
         values = np.asarray(vectors, dtype=self.dtype)
         if values.ndim != 2 or values.shape != (len(ids), self.dimension):
@@ -173,27 +244,70 @@ class SQLiteVectorCache(TargetVectorCache):
             raise ValueError("duplicate IDs in cache write")
         if not np.isfinite(values).all():
             raise ValueError("cannot cache non-finite vectors")
+        content = self._normalize_content_fingerprints(ids, content_fingerprints)
         now = time.time(); records = []
         for document_id, value in zip(ids, values):
             blob = np.ascontiguousarray(value).tobytes()
             records.append((document_id, self.model_fingerprint, self.dimension, self.dtype.name, sqlite3.Binary(blob),
-                            hashlib.sha256(blob).hexdigest(), now, now))
+                            hashlib.sha256(blob).hexdigest(), now, now,
+                            content.get(document_id) if content is not None else None))
         with self._lock:
             self._ensure_open()
-            self._db.executemany("""INSERT INTO target_vectors
-                (document_id,model_fingerprint,dimension,dtype,vector,checksum,created_at,accessed_at)
-                VALUES (?,?,?,?,?,?,?,?)
-                ON CONFLICT(document_id,model_fingerprint) DO UPDATE SET
-                    dimension=excluded.dimension,dtype=excluded.dtype,vector=excluded.vector,
-                    checksum=excluded.checksum,accessed_at=excluded.accessed_at""", records)
+            if content is None:
+                # Older callers do not know document content.  Updating the
+                # vector must not erase a binding written by the new
+                # materializer, otherwise a later content change could be
+                # mistaken for a valid cache hit.  New rows remain unbound and
+                # therefore retain historical compatibility.
+                self._db.executemany("""INSERT INTO target_vectors
+                    (document_id,model_fingerprint,dimension,dtype,vector,checksum,created_at,accessed_at,content_fingerprint)
+                    VALUES (?,?,?,?,?,?,?,?,NULL)
+                    ON CONFLICT(document_id,model_fingerprint) DO UPDATE SET
+                        dimension=excluded.dimension,dtype=excluded.dtype,vector=excluded.vector,
+                        checksum=excluded.checksum,accessed_at=excluded.accessed_at""",
+                                       [record[:8] for record in records])
+            else:
+                self._db.executemany("""INSERT INTO target_vectors
+                    (document_id,model_fingerprint,dimension,dtype,vector,checksum,created_at,accessed_at,content_fingerprint)
+                    VALUES (?,?,?,?,?,?,?,?,?)
+                    ON CONFLICT(document_id,model_fingerprint) DO UPDATE SET
+                        dimension=excluded.dimension,dtype=excluded.dtype,vector=excluded.vector,
+                        checksum=excluded.checksum,accessed_at=excluded.accessed_at,
+                        content_fingerprint=excluded.content_fingerprint""", records)
             self._db.commit()
 
-    def contains(self, document_ids: list[str]) -> set[str]:
-        return set(self.get(document_ids))
+    def contains(self, document_ids: list[str], content_fingerprints: Any = None) -> set[str]:
+        if self.read_only:
+            return set(self.peek(document_ids, content_fingerprints=content_fingerprints))
+        return set(self.get(document_ids, content_fingerprints=content_fingerprints))
+
+    def content_fingerprints(self, document_ids: list[str]) -> dict[str, str | None]:
+        """Inspect content bindings without changing cache hit/miss counters."""
+        ids = [str(x) for x in document_ids]
+        if not ids:
+            return {}
+        with self._lock:
+            self._ensure_open()
+            if self._db is None or not self._has_target_vectors or not self._has_content_fingerprint:
+                return {}
+            rows: list[tuple[Any, ...]] = []
+            for start in range(0, len(ids), self._LOOKUP_BATCH_SIZE):
+                chunk = ids[start:start + self._LOOKUP_BATCH_SIZE]
+                placeholders = ",".join("?" for _ in chunk)
+                rows.extend(self._db.execute(
+                    f"SELECT document_id,content_fingerprint FROM target_vectors "
+                    f"WHERE model_fingerprint=? AND document_id IN ({placeholders})",
+                    [self.model_fingerprint, *chunk]).fetchall())
+            return {str(row[0]): (None if row[1] is None else str(row[1])) for row in rows}
 
     def stats(self) -> dict[str, Any]:
         with self._lock:
             self._ensure_open()
+            if self._db is None or not self._has_target_vectors:
+                return {"cached_target_vectors": 0, "all_model_vectors": 0,
+                        "model_fingerprint": self.model_fingerprint, "dimension": self.dimension,
+                        "cache_path": str(self.db_path), "total_cache_hits": 0,
+                        "total_cache_misses": 0, "recent_hit_rate": 0.0}
             count = self._db.execute("SELECT COUNT(*) FROM target_vectors WHERE model_fingerprint=?", (self.model_fingerprint,)).fetchone()[0]
             total = self._db.execute("SELECT COUNT(*) FROM target_vectors").fetchone()[0]
             counters = self._db.execute("SELECT hits,misses FROM cache_counters WHERE model_fingerprint=?",
@@ -213,7 +327,8 @@ class SQLiteVectorCache(TargetVectorCache):
     def close(self) -> None:
         with self._lock:
             if not self._closed:
-                self._db.close()
+                if self._db is not None:
+                    self._db.close()
                 self._db = None
                 self._closed = True