fix(vector): separate write transport fields

harness/tht/adapters/vector/legacy_direct.py

@@ -2,7 +2,12 @@
 
 from sqlalchemy import Engine
 
-from tht.ports.vector import VectorCapabilities, VectorHealth, VectorRecord, VectorWriteUnavailable
+from tht.ports.vector import (
+    VectorCapabilities,
+    VectorHealth,
+    VectorWriteRecord,
+    VectorWriteUnavailable,
+)
 from tht.vectorstore.store import VectorHit, VectorStore as TableVectorStore
 
 
@@ -43,5 +48,5 @@ class LegacyDirectVectorStore:
     def existing_hashes(self, collection: str, kinds: list[str]) -> dict[str, str]:
         raise VectorWriteUnavailable("Legacy direct reader has no writer interface")
 
-    def upsert(self, collection: str, records: list[VectorRecord]) -> int:
+    def upsert(self, collection: str, records: list[VectorWriteRecord]) -> int:
         raise VectorWriteUnavailable("Legacy direct reader has no writer interface")

harness/tht/adapters/vector/thoth_http.py

@@ -4,12 +4,11 @@ from tht.ports.vector import (
     VectorCapabilities,
     VectorHealth,
     VectorHit,
-    VectorRecord,
-    VectorStoreError,
+    VectorWriteRecord,
     VectorWriteUnavailable,
 )
 from tht.vectorstore.rest_client import VectorRestClient
-from tht.vectorstore.store import content_hash, hit_from_metadata
+from tht.vectorstore.store import hit_from_metadata
 
 
 def _merge(hits: list[VectorHit], limit: int) -> list[VectorHit]:
@@ -63,31 +62,26 @@ class ThothHttpVectorStore:
     def existing_hashes(self, collection: str, kinds: list[str]) -> dict[str, str]:
         return self._require_writer().existing_hashes(collection, kinds)
 
-    def upsert(self, collection: str, records: list[VectorRecord]) -> int:
+    def upsert(self, collection: str, records: list[VectorWriteRecord]) -> int:
         writer = self._require_writer()
         rows = [self._row(record) for record in records]
         return writer.upsert_records(collection, rows)
 
     @staticmethod
-    def _row(record: VectorRecord) -> dict:
-        extra = dict(record.metadata)
-        try:
-            embedding = extra.pop("embedding")
-        except KeyError as exc:
-            raise VectorStoreError(f"Vector record {record.id!r} has no embedding") from exc
-        digest = extra.pop("content_hash", content_hash(record.content))
+    def _row(write_record: VectorWriteRecord) -> dict:
+        record = write_record.record
         metadata = {
             "kind": record.kind,
             "ref": record.ref,
             "record_key": record.id,
             "title": record.title,
             "content": record.content,
-            **extra,
+            **record.metadata,
         }
         return {
             "record_key": record.id,
             "kind": record.kind,
-            "content_hash": digest,
+            "content_hash": write_record.content_hash,
             "metadata": metadata,
-            "embedding": embedding,
+            "embedding": write_record.embedding,
         }

harness/tht/ports/__init__.py

@@ -7,6 +7,16 @@ from tht.ports.dwh import (
     DistinctValues,
     UnsupportedCapability,
 )
+from tht.ports.vector import (
+    VectorCapabilities,
+    VectorHealth,
+    VectorHit,
+    VectorRecord,
+    VectorStore,
+    VectorStoreError,
+    VectorWriteRecord,
+    VectorWriteUnavailable,
+)
 
 __all__ = [
     "DwhAdapter",
@@ -14,4 +24,12 @@ __all__ = [
     "DwhHealth",
     "DistinctValues",
     "UnsupportedCapability",
+    "VectorCapabilities",
+    "VectorHealth",
+    "VectorHit",
+    "VectorRecord",
+    "VectorStore",
+    "VectorStoreError",
+    "VectorWriteRecord",
+    "VectorWriteUnavailable",
 ]

harness/tht/ports/vector.py

@@ -20,6 +20,15 @@ class VectorHealth:
     detail: str | None = None
 
 
+@dataclass(frozen=True)
+class VectorWriteRecord:
+    """A canonical record plus transport-neutral, precomputed vector data."""
+
+    record: VectorRecord
+    embedding: list[float]
+    content_hash: str
+
+
 class VectorStoreError(Exception):
     """Base error exposed by vector adapters."""
 
@@ -46,7 +55,7 @@ class VectorStore(Protocol):
 
     def existing_hashes(self, collection: str, kinds: list[str]) -> dict[str, str]: ...
 
-    def upsert(self, collection: str, records: list[VectorRecord]) -> int: ...
+    def upsert(self, collection: str, records: list[VectorWriteRecord]) -> int: ...
 
 
 __all__ = [
@@ -56,5 +65,6 @@ __all__ = [
     "VectorRecord",
     "VectorStore",
     "VectorStoreError",
+    "VectorWriteRecord",
     "VectorWriteUnavailable",
 ]