fix(embedded): keep the value tags in a standalone install

The tags came from `coordinode`, which the embedded engine deliberately
does not depend on, so installing it alone left the lookup returning None
and both new types degrading to the plain container they were tagged to
be told apart from. The fallback was silent: a multi-vector read back
re-encoded as an array and a path as a map, exactly what the tags exist
to prevent.

They now live in `coordinode_embedded._types`, which re-exports
`coordinode`'s definitions when that package is present and defines
equivalents when it is not. With both installed the two names are the
same class object, so a value tagged through either is recognised by the
other.

Both are exported from their packages as well. Only an instance activates
the multi-vector and path wire types, so without a public constructor
there was no supported way to send one.

Verified in a venv holding the wheel alone, where `coordinode._types` is
not importable: the round-trip tests pass there rather than falling back.

Author: polaz

coordinode-embedded/python/coordinode_embedded/__init__.py

@@ -22,5 +22,6 @@
 """
 
 from ._coordinode_embedded import Hnsw, LocalClient
+from ._types import MultiVector, Path
 
-__all__ = ["Hnsw", "LocalClient"]
+__all__ = ["Hnsw", "LocalClient", "MultiVector", "Path"]

coordinode-embedded/python/coordinode_embedded/_types.py

@@ -0,0 +1,33 @@
+"""Value types whose wire form a plain Python container cannot express.
+
+A multi-vector is a list of lists and a path is a mapping, so neither can be
+told apart from the ordinary container it looks like once it has been handed
+to Python. These tags carry the distinction, and the conversion layer checks
+for them ahead of the generic list and dict branches: without one, reading a
+value and writing it straight back stores it as something else.
+
+`coordinode` owns the canonical definitions, and this package deliberately
+does not depend on it: the embedded engine is usable on its own. So when that
+package is present its classes are re-used here, and a value tagged through
+one is recognised by the other; a standalone install falls back to the
+equivalents below.
+"""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - exercised by whichever install shape is in use
+    from coordinode._types import MultiVector, Path
+except ImportError:
+
+    class MultiVector(list):  # type: ignore[no-redef]
+        """Several equal-width vectors describing one item."""
+
+        __slots__ = ()
+
+    class Path(dict):  # type: ignore[no-redef]
+        """A graph path: the node ids it runs through, and the hops between."""
+
+        __slots__ = ()
+
+
+__all__ = ["MultiVector", "Path"]

coordinode-embedded/src/lib.rs

@@ -26,26 +26,27 @@ use rmpv::Value as MsgpackValue;
 
 // ── Value → PyObject conversion ──────────────────────────────────────────────
 
-/// The `MultiVector` tag from the `coordinode` package, when it is installed.
+/// The `MultiVector` tag, from this package's own `_types` module.
 ///
 /// A list subclass, so a tagged value reads and compares exactly like the
-/// nested list it replaces; the type exists only to survive a round trip. This
-/// package does not depend on `coordinode` (the embedded engine is usable on
-/// its own), so a missing import is an ordinary outcome and the caller falls
-/// back to a plain list, which is what this returned before the tag existed.
+/// nested list it replaces; the type exists only to survive a round trip,
+/// since an untagged nested list re-encodes as an array and changes the
+/// property's type. That module re-exports `coordinode`'s definition when that
+/// package is installed and defines an equivalent when it is not, so the tag
+/// holds for a standalone install of the embedded engine too.
 fn multi_vector_type(py: Python<'_>) -> Option<Bound<'_, PyAny>> {
-    py.import("coordinode._types")
+    py.import("coordinode_embedded._types")
         .and_then(|m| m.getattr("MultiVector"))
         .ok()
 }
 
-/// The `Path` tag from the `coordinode` package, when it is installed.
+/// The `Path` tag, from this package's own `_types` module.
 ///
-/// A dict subclass, for the same reason and with the same fallback as
-/// [`multi_vector_type`]: without the tag a path read back is an ordinary
-/// mapping, and writing it out again would store a map.
+/// A dict subclass, for the same reason as [`multi_vector_type`]: without the
+/// tag a path read back is an ordinary mapping, and writing it out again would
+/// store a map.
 fn path_type(py: Python<'_>) -> Option<Bound<'_, PyAny>> {
-    py.import("coordinode._types")
+    py.import("coordinode_embedded._types")
         .and_then(|m| m.getattr("Path"))
         .ok()
 }

coordinode/coordinode/__init__.py

@@ -18,6 +18,7 @@
         result = await db.cypher("MATCH (n) RETURN count(n) AS total")
 """
 
+from coordinode._types import MultiVector, Path
 from coordinode.client import (
     AsyncCoordinodeClient,
     CoordinodeClient,
@@ -39,6 +40,11 @@
 __all__ = [
     "CoordinodeClient",
     "AsyncCoordinodeClient",
+    # Values whose wire type only a tag can carry: a plain nested list encodes
+    # as a list and a plain dict as a map, so sending either of these types
+    # requires the constructor, not just the shape.
+    "MultiVector",
+    "Path",
     "NodeResult",
     "EdgeResult",
     "VectorResult",

tests/unit/test_embedded_values.py

@@ -10,7 +10,10 @@
 
 ce = pytest.importorskip("coordinode_embedded")
 
-from coordinode._types import MultiVector, Path  # noqa: E402  (after the skip guard)
+# From the embedded package rather than `coordinode`, so this file runs where
+# only the wheel is installed. It re-exports `coordinode`'s definitions when
+# that package is present, so this is the same class either way.
+from coordinode_embedded import MultiVector, Path  # noqa: E402  (after the skip guard)
 
 
 @pytest.fixture