refactor(vector): define store contract

harness/tht/ports/vector.py

@@ -0,0 +1,60 @@
+"""Transport-neutral vector-store contract and canonical vector models."""
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+from tht.vectorstore.records import VectorRecord
+from tht.vectorstore.store import VectorHit
+
+
+@dataclass(frozen=True)
+class VectorCapabilities:
+    search: bool = True
+    existing_hashes: bool = False
+    upsert: bool = False
+
+
+@dataclass(frozen=True)
+class VectorHealth:
+    ok: bool
+    detail: str | None = None
+
+
+class VectorStoreError(Exception):
+    """Base error exposed by vector adapters."""
+
+
+class VectorWriteUnavailable(VectorStoreError):
+    """Raised when a deployment has no vector writer credential."""
+
+
+@runtime_checkable
+class VectorStore(Protocol):
+    @property
+    def capabilities(self) -> VectorCapabilities: ...
+
+    def health(self) -> VectorHealth: ...
+
+    def search(
+        self,
+        collections: list[str],
+        embedding: list[float],
+        *,
+        limit: int,
+        kinds: list[str] | None = None,
+    ) -> list[VectorHit]: ...
+
+    def existing_hashes(self, collection: str, kinds: list[str]) -> dict[str, str]: ...
+
+    def upsert(self, collection: str, records: list[VectorRecord]) -> int: ...
+
+
+__all__ = [
+    "VectorCapabilities",
+    "VectorHealth",
+    "VectorHit",
+    "VectorRecord",
+    "VectorStore",
+    "VectorStoreError",
+    "VectorWriteUnavailable",
+]