openframe-core 3.4.0__tar.gz → 3.6.0__tar.gz

{openframe_core-3.4.0 → openframe_core-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: openframe-core
-Version: 3.4.0
+Version: 3.6.0
 Summary: OpenFrame Microservice Suite - platform kernel. Port contracts, testing utilities, plugin registry, and composition root.
 Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-core
 Project-URL: Documentation, https://furious-meteors.github.io/openframe-core/

{openframe_core-3.4.0 → openframe_core-3.6.0}/openframe/core/ports/__init__.py

@@ -29,7 +29,7 @@ old ``openframe.core.contracts`` path — update all imports to
 top of BasePort, defined in ``ports/outbound/`` (see that sub-module's
 docstring for the intake rule on future capabilities)::
 
-    from openframe.core.ports import BaseRepository, BaseProducer, BaseConsumer
+    from openframe.core.ports import BaseRepository, BaseProducer, BaseConsumer, BaseVectorStore, BaseGraphStore
 
 Runtime isinstance checks::
 
@@ -43,7 +43,13 @@ from openframe.core.ports.context import PrincipalContext, TenantContext
 from openframe.core.ports.health import PluginContext, PluginHealth, PluginStatus
 from openframe.core.ports.identity import Identity
 from openframe.core.ports.lifecycle import Lifecycle
-from openframe.core.ports.outbound import BaseConsumer, BaseProducer, BaseRepository
+from openframe.core.ports.outbound import (
+    BaseConsumer,
+    BaseGraphStore,
+    BaseProducer,
+    BaseRepository,
+    BaseVectorStore,
+)
 from openframe.core.ports.port import BasePort
 
 __all__ = [
@@ -61,4 +67,6 @@ __all__ = [
     "BaseRepository",
     "BaseProducer",
     "BaseConsumer",
+    "BaseVectorStore",
+    "BaseGraphStore",
 ]

{openframe_core-3.4.0 → openframe_core-3.6.0}/openframe/core/ports/outbound/__init__.py

@@ -14,6 +14,16 @@ outbound capability:
   message publishing (``QUEUE`` capability).
 - :class:`~openframe.core.ports.outbound.consumer.BaseConsumer` —
   message consumption (``QUEUE`` capability).
+- :class:`~openframe.core.ports.outbound.repository.BaseVectorStore` —
+  id-addressable CRUD plus similarity search (``SEARCH`` capability).
+  Extends ``BaseRepository`` directly (defined in the same module) rather
+  than sitting as a sibling of it — see ``repository.py``'s own
+  docstring for why.
+- :class:`~openframe.core.ports.outbound.repository.BaseGraphStore` —
+  id-addressable node CRUD plus pattern-matching traversal (``SEARCH``
+  capability). Also extends ``BaseRepository`` directly (defined in the
+  same module) — see ``repository.py``'s own docstring for why, and for
+  why relationships/edges are not given their own port method.
 
 Future outbound capabilities (openframe-infra: ``BaseSecretsProvider``,
 ``BaseObjectStore``, ``BaseFeatureFlagProvider``) will be added here
@@ -25,7 +35,7 @@ Implementations live in openframe-adapters.
 
 Usage::
 
-    from openframe.core.ports import BaseRepository, BaseProducer, BaseConsumer
+    from openframe.core.ports import BaseRepository, BaseProducer, BaseConsumer, BaseVectorStore, BaseGraphStore
 
 Or via explicit path if needed::
 
@@ -35,6 +45,16 @@ from __future__ import annotations
 
 from openframe.core.ports.outbound.consumer import BaseConsumer
 from openframe.core.ports.outbound.producer import BaseProducer
-from openframe.core.ports.outbound.repository import BaseRepository
-
-__all__ = ["BaseRepository", "BaseProducer", "BaseConsumer"]
+from openframe.core.ports.outbound.repository import (
+    BaseGraphStore,
+    BaseRepository,
+    BaseVectorStore,
+)
+
+__all__ = [
+    "BaseRepository",
+    "BaseProducer",
+    "BaseConsumer",
+    "BaseVectorStore",
+    "BaseGraphStore",
+]

openframe_core-3.6.0/openframe/core/ports/outbound/repository.py

@@ -0,0 +1,372 @@
+"""
+openframe/core/ports/outbound/repository.py
+==============================================
+Generic persistence port for the OpenFrame ecosystem (ADR-006).
+
+``BaseRepository[T]`` extends
+:class:`~openframe.core.ports.port.BasePort` directly — it is
+``Identity + Lifecycle`` plus its own domain methods. There is exactly one
+lifecycle-aware definition of this port; the pre-v3 lifecycle-free version
+no longer exists.
+
+Adapters satisfy this protocol by structural subtyping — no inheritance
+from ``BaseRepository`` is required or desired. Any class whose async
+method signatures match, and that also satisfies ``BasePort``
+(``name``/``version``/``capability``/``initialize``/``shutdown``/
+``health``), is accepted.
+
+Runtime isinstance check::
+
+    isinstance(repo, BaseRepository)       # ✓ works — checks method names
+    isinstance(repo, BaseRepository[str])  # ✗ raises TypeError — not supported
+
+The parameterised form is a static-analysis-only annotation. At runtime,
+always check against the unparameterised ``BaseRepository``.
+
+This module also defines :class:`BaseVectorStore`, which extends
+``BaseRepository`` directly rather than sitting in its own file or as a
+disjoint sibling port (the way ``BaseProducer``/``BaseConsumer`` are
+siblings of ``BaseRepository``, not subtypes). Most vector databases ARE
+genuinely id-addressable — insert/upsert-with-id, fetch-by-id,
+delete-by-id, list/scroll — so the five CRUD methods below are real
+operations for them too, not fakes forced to satisfy an interface. The
+only operation with no equivalent here is similarity search, so
+``BaseVectorStore`` adds exactly one new method, :meth:`BaseVectorStore.search`,
+on top of everything below. A vector store that satisfies
+``BaseVectorStore`` also satisfies ``BaseRepository`` for free — existing
+code written against ``BaseRepository`` keeps working unmodified against
+a vector-backed implementation.
+
+``BaseVectorStore`` is deliberately not a universal fit for every
+vector backend. FAISS (a bare in-process index with no native
+id→metadata store, and some index types that don't support deletion
+without a full rebuild) was evaluated and explicitly excluded from this
+port's intended adopters.
+
+This module also defines :class:`BaseGraphStore`, which — like
+``BaseVectorStore`` — extends ``BaseRepository`` directly. A graph
+database's nodes ARE genuinely id-addressable: create/get/update/delete
+map onto real `CREATE`/`MATCH ... WHERE n.<key> = $id`/`SET`/`DETACH
+DELETE` operations, provided the adapter addresses nodes by an
+application-level unique property (with a backing index/constraint the
+adapter is responsible for creating), not a backend-internal node
+identity. FalkorDB's own ``id()`` function is explicitly documented as
+unstable — deleted nodes' higher internal ids can be migrated down to
+fill vacated lower ones — so it is unsuitable as this port's addressing
+key; this is exactly why adapters must key off their own property, not
+why graph databases don't fit this port at all. The one operation with
+no CRUD equivalent is traversal/pattern-matching, so ``BaseGraphStore``
+adds exactly one new method, :meth:`BaseGraphStore.traverse`, which also
+serves as the escape hatch for relationship/edge creation and querying
+(Cypher's ``CREATE``/``MATCH`` handle nodes and edges in the same
+statement) — this port does not model edges as their own first-class
+method, the same way it does not invent a bespoke query language.
+
+Dependency order:
+    ports/port                → ports/identity + ports/lifecycle
+    ports/outbound/repository → ports/port
+"""
+from __future__ import annotations
+
+from typing import Protocol, TypeVar, runtime_checkable
+
+from openframe.core.ports.port import BasePort
+
+__all__ = ["BaseRepository", "BaseVectorStore", "BaseGraphStore"]
+
+T = TypeVar("T")
+
+
+@runtime_checkable
+class BaseRepository(BasePort, Protocol[T]):
+    """
+    Generic persistence port. ``BasePort`` (Identity + Lifecycle) plus
+    domain-specific CRUD methods.
+
+    Adapters implement this protocol structurally — no inheritance needed.
+    Any class with matching async method signatures, plus the
+    ``BasePort`` members, satisfies ``BaseRepository``.
+
+    Type parameter ``T`` is the domain entity the repository manages.
+
+    Runtime check::
+
+        isinstance(repo, BaseRepository)       # ✓ works
+        isinstance(repo, BaseRepository[str])  # ✗ raises TypeError
+
+    Domain methods:
+        get:    Retrieve a single entity by ID.
+        list:   Return a paginated slice plus total count.
+        create: Persist a new entity and return it with any backend-assigned
+                fields populated (e.g. generated primary key, created_at).
+        update: Persist changes to an existing entity. Returns the updated
+                entity or None if the entity did not exist.
+        delete: Remove an entity by ID. Returns True if deleted, False if
+                the entity did not exist.
+
+    Plus, inherited from ``BasePort``: ``name``, ``version``, ``capability``,
+    ``initialize``, ``shutdown``, ``health``.
+    """
+
+    async def get(self, entity_id: str) -> T | None:
+        """
+        Retrieve a single entity by its identifier.
+
+        Args:
+            entity_id: The unique identifier of the entity.
+
+        Returns:
+            The entity if found, None if it does not exist.
+
+        Raises:
+            AdapterConnectionError: If the backend is unreachable.
+            AdapterQueryError:      If the query fails for any other reason.
+            AdapterTimeoutError:    If the operation exceeds ``operation_timeout``.
+        """
+        ...
+
+    async def list(self, limit: int, offset: int) -> tuple[list[T], int]:
+        """
+        Return a paginated slice of all entities plus the total count.
+
+        Args:
+            limit:  Maximum number of entities to return.
+            offset: Number of entities to skip from the beginning.
+
+        Returns:
+            A 2-tuple of (entities, total_count). ``total_count`` is the
+            count of all matching entities, not just the returned slice.
+
+        Raises:
+            AdapterConnectionError: If the backend is unreachable.
+            AdapterQueryError:      If the query fails.
+            AdapterTimeoutError:    If the operation exceeds ``operation_timeout``.
+        """
+        ...
+
+    async def create(self, entity: T) -> T:
+        """
+        Persist a new entity and return it with backend-assigned fields.
+
+        Args:
+            entity: The entity to create. Backend may assign fields like
+                    primary key or timestamps.
+
+        Returns:
+            The entity as stored, including any backend-assigned fields.
+
+        Raises:
+            AdapterConnectionError: If the backend is unreachable.
+            AdapterQueryError:      If the insert fails (e.g. constraint violation).
+            AdapterTimeoutError:    If the operation exceeds ``operation_timeout``.
+        """
+        ...
+
+    async def update(self, entity: T) -> T | None:
+        """
+        Persist changes to an existing entity.
+
+        Args:
+            entity: The entity with updated fields. Must have a valid identifier.
+
+        Returns:
+            The updated entity as stored, or None if the entity did not exist.
+
+        Raises:
+            AdapterConnectionError: If the backend is unreachable.
+            AdapterQueryError:      If the update fails.
+            AdapterTimeoutError:    If the operation exceeds ``operation_timeout``.
+        """
+        ...
+
+    async def delete(self, entity_id: str) -> bool:
+        """
+        Remove an entity by its identifier.
+
+        Args:
+            entity_id: The unique identifier of the entity to delete.
+
+        Returns:
+            True if the entity was deleted, False if it did not exist.
+
+        Raises:
+            AdapterConnectionError: If the backend is unreachable.
+            AdapterQueryError:      If the deletion fails.
+            AdapterTimeoutError:    If the operation exceeds ``operation_timeout``.
+        """
+        ...
+
+
+@runtime_checkable
+class BaseVectorStore(BaseRepository[T], Protocol[T]):
+    """
+    Generic vector store port. ``BaseRepository[T]`` (id-addressable CRUD)
+    plus one additional domain method, :meth:`search`.
+
+    See this module's own docstring for why this extends ``BaseRepository``
+    directly rather than being a disjoint sibling port, and why FAISS/
+    FalkorDB are explicitly excluded from this port's intended adopters.
+
+    Adapters implement this protocol structurally — no inheritance needed.
+    Any class with matching async method signatures, plus everything
+    ``BaseRepository``/``BasePort`` require, satisfies ``BaseVectorStore``.
+
+    Type parameter ``T`` is the domain entity the vector store manages —
+    typically a dataclass or Pydantic model carrying an id, an embedding
+    vector, and whatever metadata fields the caller's domain needs.
+
+    .. stability: experimental
+       New port, added alongside the first vector-store adapter packages.
+       API may change based on real usage. ``BaseRepository`` above is
+       unaffected by this — it remains stable; only ``BaseVectorStore``
+       itself is experimental.
+
+    Runtime check::
+
+        isinstance(store, BaseVectorStore)   # ✓ works
+        isinstance(store, BaseRepository)    # ✓ also true
+
+    Inherited from ``BaseRepository[T]`` — id-addressable CRUD:
+        get:    Fetch a single entity by id.
+        list:   Return a paginated slice plus total count.
+        create: Upsert a new entity (most vector DBs treat insert as
+                upsert-by-id natively; adapters document their own
+                create-vs-upsert semantics if they diverge).
+        update: Upsert an existing entity's vector/metadata.
+        delete: Remove an entity by id.
+
+    New in this port:
+        search: Similarity search — the operation ``BaseRepository`` has
+                no equivalent for.
+
+    Plus, inherited from ``BasePort`` (via ``BaseRepository``): ``name``,
+    ``version``, ``capability``, ``initialize``, ``shutdown``, ``health``.
+    """
+
+    async def search(self, query_vector: list[float], k: int) -> list[T]:
+        """
+        Return the ``k`` entities whose vectors are most similar to
+        ``query_vector``.
+
+        The distance/similarity metric (cosine, L2, dot product, ...) is
+        an adapter/backend-level configuration concern, not part of this
+        port's signature — different backends default to different
+        metrics, and some let it be configured per-collection at index
+        creation time. Document the active metric in the adapter's own
+        docstring.
+
+        Args:
+            query_vector: The embedding to search against. Must match the
+                          dimensionality the backend collection/index was
+                          created with — a mismatch is a configuration
+                          error, not a query error, but adapters may
+                          surface it as either depending on when the
+                          backend itself detects it.
+            k: Maximum number of results to return, ordered from most to
+               least similar. Returning fewer than ``k`` results (if the
+               collection has fewer than ``k`` entities, or the backend
+               applies its own relevance cutoff) is not an error.
+
+        Returns:
+            Up to ``k`` entities, ordered from most to least similar.
+            Empty list if nothing matches (never ``None`` — unlike
+            ``get()``, "no results" is a normal outcome of a search, not
+            a not-found case).
+
+        Raises:
+            AdapterConnectionError:    If the backend is unreachable.
+            AdapterQueryError:         If the query fails (e.g.
+                                       ``query_vector``'s dimensionality
+                                       doesn't match the collection).
+            AdapterTimeoutError:       If the operation exceeds
+                                       ``operation_timeout``.
+        """
+        ...
+
+
+@runtime_checkable
+class BaseGraphStore(BaseRepository[T], Protocol[T]):
+    """
+    Generic graph store port. ``BaseRepository[T]`` (id-addressable node
+    CRUD) plus one additional domain method, :meth:`traverse`.
+
+    See this module's own docstring for why this extends ``BaseRepository``
+    directly rather than being a disjoint sibling port, why FalkorDB's
+    internal ``id()`` is not a suitable addressing key, and why
+    relationships/edges are not given their own port method.
+
+    Adapters implement this protocol structurally — no inheritance needed.
+    Any class with matching async method signatures, plus everything
+    ``BaseRepository``/``BasePort`` require, satisfies ``BaseGraphStore``.
+
+    Type parameter ``T`` is the domain entity representing a **node** —
+    typically a dataclass or Pydantic model carrying an application-level
+    unique id, labels, and whatever properties the caller's domain needs.
+    Edges are not modeled by ``T`` or by any method on this port; they are
+    created and queried exclusively through :meth:`traverse`.
+
+    .. stability: experimental
+       New port, added alongside the first graph-store adapter packages.
+       API may change based on real usage. ``BaseRepository`` above is
+       unaffected by this — it remains stable; only ``BaseGraphStore``
+       itself is experimental.
+
+    Runtime check::
+
+        isinstance(store, BaseGraphStore)    # ✓ works
+        isinstance(store, BaseRepository)    # ✓ also true
+
+    Inherited from ``BaseRepository[T]`` — id-addressable node CRUD:
+        get:    Fetch a single node by its application-level id.
+        list:   Return a paginated slice of nodes plus total count.
+        create: Create a new node. Adapters are responsible for ensuring
+                a unique constraint/index exists on the id property they
+                address nodes by — without one, every get/update/delete
+                degrades to an unindexed label scan.
+        update: Update an existing node's properties.
+        delete: Remove a node by id. Adapters should detach (remove
+                incident edges) before deleting, since most graph backends
+                reject deleting a node that still has relationships.
+
+    New in this port:
+        traverse: Arbitrary pattern-matching/traversal query — the
+                  operation ``BaseRepository`` has no equivalent for, and
+                  also the only way to create, update, or query edges.
+
+    Plus, inherited from ``BasePort`` (via ``BaseRepository``): ``name``,
+    ``version``, ``capability``, ``initialize``, ``shutdown``, ``health``.
+    """
+
+    async def traverse(
+        self, query: str, params: dict[str, object] | None = None
+    ) -> list[T]:
+        """
+        Execute an arbitrary pattern-matching/traversal query against the
+        graph and return the matching entities.
+
+        This is the escape hatch for everything ``BaseRepository``'s CRUD
+        methods cannot express: multi-hop traversals, relationship/edge
+        creation and querying, variable-length paths, aggregations. The
+        query language itself (Cypher, Gremlin, ...) is an adapter/backend
+        concern, not part of this port's signature — adapters document
+        which language their ``query`` argument expects.
+
+        Args:
+            query:  A query string in the backend's native query language.
+            params: Named parameters substituted into the query, keyed by
+                    name as the backend's driver expects. None if the
+                    query has no parameters.
+
+        Returns:
+            The entities the query's `RETURN`-equivalent clause produces.
+            Empty list if the query matches nothing (not an error).
+
+        Raises:
+            AdapterConnectionError: If the backend is unreachable.
+            AdapterQueryError:      If the query is malformed or fails
+                                     (e.g. a syntax error, or a
+                                     constraint violation on a write).
+            AdapterTimeoutError:    If the operation exceeds
+                                     ``operation_timeout``.
+        """
+        ...

{openframe_core-3.4.0 → openframe_core-3.6.0}/openframe/core/testing/__init__.py

@@ -33,6 +33,7 @@ Quick reference::
 from __future__ import annotations
 
 from openframe.core.testing.contracts.consumer import ConsumerContractTests
+from openframe.core.testing.contracts.graph_store import GraphStoreContractTests
 from openframe.core.testing.contracts.inbound import (
     CommandHandlerContractTests,
     QueryHandlerContractTests,
@@ -42,7 +43,9 @@ from openframe.core.testing.contracts.lifecycle import LifecycleContractTests
 from openframe.core.testing.contracts.port import PortContractTests
 from openframe.core.testing.contracts.producer import ProducerContractTests
 from openframe.core.testing.contracts.repository import RepositoryContractTests
+from openframe.core.testing.contracts.vector_store import VectorStoreContractTests
 from openframe.core.testing.fakes.consumer import FakeConsumer
+from openframe.core.testing.fakes.graph_store import InMemoryGraphStore
 from openframe.core.testing.fakes.inbound import (
     EchoUseCase,
     SpyCommandHandler,
@@ -50,9 +53,12 @@ from openframe.core.testing.fakes.inbound import (
 )
 from openframe.core.testing.fakes.producer import FakeProducer
 from openframe.core.testing.fakes.repository import InMemoryRepository
+from openframe.core.testing.fakes.vector_store import InMemoryVectorStore
 
 __all__ = [
     "InMemoryRepository",
+    "InMemoryVectorStore",
+    "InMemoryGraphStore",
     "FakeProducer",
     "FakeConsumer",
     "EchoUseCase",
@@ -61,6 +67,8 @@ __all__ = [
     "LifecycleContractTests",
     "PortContractTests",
     "RepositoryContractTests",
+    "VectorStoreContractTests",
+    "GraphStoreContractTests",
     "ProducerContractTests",
     "ConsumerContractTests",
     "UseCaseContractTests",

{openframe_core-3.4.0 → openframe_core-3.6.0}/openframe/core/testing/contracts/__init__.py

@@ -7,6 +7,12 @@ Outbound: ``PortContractTests``/``LifecycleContractTests`` cover the
 shared ``BasePort`` identity/lifecycle suite; ``RepositoryContractTests``,
 ``ProducerContractTests``, ``ConsumerContractTests`` build on
 ``PortContractTests`` with domain-specific assertions.
+``VectorStoreContractTests`` builds on ``RepositoryContractTests`` itself
+(not directly on ``PortContractTests``), adding search-specific
+assertions — mirroring how ``BaseVectorStore`` extends ``BaseRepository``.
+``GraphStoreContractTests`` likewise builds on ``RepositoryContractTests``,
+adding traverse-specific assertions — mirroring how ``BaseGraphStore``
+extends ``BaseRepository``.
 
 Inbound: ``UseCaseContractTests``, ``CommandHandlerContractTests``,
 ``QueryHandlerContractTests`` mirror the outbound contract classes for
@@ -22,6 +28,7 @@ pytest installed.
 from __future__ import annotations
 
 from openframe.core.testing.contracts.consumer import ConsumerContractTests
+from openframe.core.testing.contracts.graph_store import GraphStoreContractTests
 from openframe.core.testing.contracts.inbound import (
     CommandHandlerContractTests,
     QueryHandlerContractTests,
@@ -31,11 +38,14 @@ from openframe.core.testing.contracts.lifecycle import LifecycleContractTests
 from openframe.core.testing.contracts.port import PortContractTests
 from openframe.core.testing.contracts.producer import ProducerContractTests
 from openframe.core.testing.contracts.repository import RepositoryContractTests
+from openframe.core.testing.contracts.vector_store import VectorStoreContractTests
 
 __all__ = [
     "LifecycleContractTests",
     "PortContractTests",
     "RepositoryContractTests",
+    "VectorStoreContractTests",
+    "GraphStoreContractTests",
     "ProducerContractTests",
     "ConsumerContractTests",
     "UseCaseContractTests",

openframe_core-3.6.0/openframe/core/testing/contracts/graph_store.py

@@ -0,0 +1,143 @@
+"""
+openframe/core/testing/contracts/graph_store.py
+==================================================
+GraphStoreContractTests — reusable pytest base class.
+
+Every ``openframe-adapters-db-{falkordb,...}`` package must inherit this
+class and pass every test. Builds on
+:class:`~openframe.core.testing.contracts.repository.RepositoryContractTests`
+for the full id-addressable node CRUD contract (which itself builds on
+:class:`~openframe.core.testing.contracts.port.PortContractTests` for
+``BasePort`` identity + lifecycle), adding
+:meth:`~openframe.core.ports.BaseGraphStore.traverse`-specific assertions
+on top.
+
+The traverse assertions are deliberately query-language-agnostic — they
+never hardcode Cypher (or any other graph query language) syntax, since
+different backends use different languages. Instead, each assertion asks
+a fixture, ``traverse_query_for``, to produce a ``(query, params)`` pair
+in whatever language the adapter under test actually speaks, that is
+guaranteed to return exactly the one entity passed to it. This mirrors
+how :class:`~openframe.core.testing.contracts.vector_store.VectorStoreContractTests`
+asks for an ``entity_vector`` extractor rather than assuming a specific
+similarity metric.
+
+No top-level pytest import — this module can be imported without pytest
+installed, matching every other module in this package.
+
+.. stability: experimental
+   New alongside :class:`~openframe.core.ports.BaseGraphStore` itself.
+
+Dependency order:
+    testing/contracts/graph_store → testing/contracts/repository + ports
+
+Subclass usage::
+
+    class TestFalkorDBGraphStore(GraphStoreContractTests):
+        @pytest.fixture
+        async def repository(self, falkordb_settings):
+            return FalkorDBNodeStore(falkordb_settings)
+
+        @pytest.fixture
+        def port(self, repository):
+            return repository
+
+        @pytest.fixture
+        def make_entity(self):
+            def _make(id: str, name: str = "test") -> Node:
+                return Node(id=id, name=name)
+            return _make
+
+        @pytest.fixture
+        def traverse_query_for(self):
+            # Given an entity, return a (query, params) pair that, run
+            # through traverse(), returns exactly that entity.
+            def _query_for(entity):
+                return "MATCH (n) WHERE n.id = $id RETURN n", {"id": entity.id}
+            return _query_for
+"""
+from __future__ import annotations
+
+from openframe.core.testing.contracts.repository import RepositoryContractTests
+
+__all__ = ["GraphStoreContractTests"]
+
+__stability__ = "experimental"
+
+
+class GraphStoreContractTests(RepositoryContractTests):
+    """
+    Reusable pytest base class for graph store contract tests.
+
+    Subclasses must provide everything
+    :class:`~openframe.core.testing.contracts.repository.RepositoryContractTests`
+    requires (``repository``, ``port``, ``make_entity``), plus:
+
+    ``traverse_query_for``
+        A callable ``(entity: T) -> tuple[str, dict[str, object]]`` that,
+        given an entity, returns a ``(query, params)`` pair in the
+        adapter's own query language that — once the entity has been
+        created — returns exactly that one entity when passed to
+        :meth:`~openframe.core.ports.BaseGraphStore.traverse`. Lets these
+        contract tests exercise ``traverse()`` without hardcoding Cypher
+        (or any other) syntax.
+
+    .. stability: experimental
+    """
+
+    # ------------------------------------------------------------------
+    # traverse
+    # ------------------------------------------------------------------
+
+    async def test_traverse_returns_empty_list_when_nothing_matches(
+        self, repository, make_entity, traverse_query_for
+    ) -> None:
+        """traverse() returns an empty list, never None, when nothing matches."""
+        entity = make_entity(id="traverse-absent")
+        query, params = traverse_query_for(entity)
+
+        results = await repository.traverse(query, params)
+
+        assert results == []
+
+    async def test_traverse_returns_created_entity(
+        self, repository, make_entity, traverse_query_for
+    ) -> None:
+        """traverse() returns an entity once it has been created."""
+        entity = make_entity(id="traverse-target")
+        await repository.create(entity)
+        query, params = traverse_query_for(entity)
+
+        results = await repository.traverse(query, params)
+
+        assert entity in results
+
+    async def test_traverse_result_is_a_list(
+        self, repository, make_entity, traverse_query_for
+    ) -> None:
+        """traverse() always returns a list, regardless of match count."""
+        entity = make_entity(id="traverse-shape")
+        query, params = traverse_query_for(entity)
+
+        results = await repository.traverse(query, params)
+
+        assert isinstance(results, list)
+
+    async def test_traverse_accepts_no_params(self, repository) -> None:
+        """traverse() accepts params=None for queries with no parameters."""
+        results = await repository.traverse("RETURN 1", None)
+        assert isinstance(results, list)
+
+    # ------------------------------------------------------------------
+    # Protocol isinstance check
+    # ------------------------------------------------------------------
+
+    async def test_satisfies_base_graph_store_protocol(self, repository) -> None:
+        """Graph store satisfies BaseGraphStore via structural subtyping."""
+        from openframe.core.ports import BaseGraphStore
+
+        assert isinstance(repository, BaseGraphStore), (
+            f"{type(repository).__name__} does not satisfy BaseGraphStore. "
+            "Ensure it implements traverse, plus everything BaseRepository/"
+            "BasePort require."
+        )