docs(vector): add local backup restore and parity gate

harness/tht/adapters/vector/pgvector.py

@@ -257,7 +257,7 @@ class PgVectorStore:
                     where = sql.SQL(" WHERE kind = ANY(%s)") if collection_kinds else sql.SQL("")
                     query = sql.SQL(
                         "SELECT metadata, 1 - (embedding {} %s::{}) AS similarity "
-                        "FROM {}{} ORDER BY embedding {} %s::{} LIMIT %s"
+                        "FROM {}{} ORDER BY embedding {} %s::{}, record_key LIMIT %s"
                     ).format(
                         _cosine_operator(self._schema),
                         _vector_type(self._schema),
@@ -274,7 +274,7 @@ class PgVectorStore:
                     hits.extend(hit_from_metadata(row[1], row[0]) for row in cursor.fetchall())
         finally:
             raw.close()
-        return sorted(hits, key=lambda hit: hit.similarity, reverse=True)[:limit]
+        return sorted(hits, key=lambda hit: (-hit.similarity, hit.id))[:limit]
 
     def _require_writer(self) -> Engine:
         if self._writer is None:

harness/tht/adapters/vector/thoth_http.py

@@ -5,16 +5,22 @@ from tht.ports.vector import (
     VectorHealth,
     VectorHit,
     VectorReadUnavailable,
+    VectorStoreError,
     VectorWriteRecord,
     VectorWriteUnavailable,
     require_positive_limit,
 )
 from tht.vectorstore.rest_client import VectorRestClient
 from tht.vectorstore.store import hit_from_metadata
+from tht.adapters.vector.pgvector import (
+    _collection,
+    _validate_collection_kinds,
+    _validate_known_kinds,
+)
 
 
 def _merge(hits: list[VectorHit], limit: int) -> list[VectorHit]:
-    return sorted(hits, key=lambda hit: hit.similarity, reverse=True)[:limit]
+    return sorted(hits, key=lambda hit: (-hit.similarity, hit.id))[:limit]
 
 
 class ThothHttpVectorStore:
@@ -89,8 +95,13 @@ class ThothHttpVectorStore:
         require_positive_limit(limit)
         if self._reader is None:
             raise VectorReadUnavailable("Vector reader credential is not configured")
+        if self._expected_dimension is not None and len(embedding) != self._expected_dimension:
+            raise VectorStoreError("Query embedding dimension does not match configured dimension")
+        if kinds:
+            _validate_known_kinds(kinds)
         hits: list[VectorHit] = []
         for collection in collections:
+            _collection("vectors", collection)
             rows = self._reader.search_similar(collection, embedding, limit, kinds=kinds)
             hits.extend(
                 hit_from_metadata(row.get("similarity", 0.0), row.get("metadata"))
@@ -107,10 +118,20 @@ class ThothHttpVectorStore:
         return self._writer
 
     def existing_hashes(self, collection: str, kinds: list[str]) -> dict[str, str]:
+        _collection("vectors", collection)
+        _validate_collection_kinds(collection, kinds)
         return self._require_writer().existing_hashes(collection, kinds)
 
     def upsert(self, collection: str, records: list[VectorWriteRecord]) -> int:
         writer = self._require_writer()
+        _collection("vectors", collection)
+        for record in records:
+            _validate_collection_kinds(collection, [record.record.kind])
+            if (
+                self._expected_dimension is not None
+                and len(record.embedding) != self._expected_dimension
+            ):
+                raise VectorStoreError("Embedding dimension does not match configured dimension")
         rows = [self._row(record) for record in records]
         return writer.upsert_records(collection, rows)