feat(client): track CoordiNode 0.5.5 and make the demo stack real

.github/workflows/ci.yml

@@ -16,9 +16,21 @@
         with:
           python-version: "3.11"
 
-      - run: uv sync
-      - run: uv run ruff check coordinode/ langchain-coordinode/ llama-index-coordinode/ tests/
-      - run: uv run ruff format --check coordinode/ langchain-coordinode/ llama-index-coordinode/ tests/
+      # --locked fails the job when uv.lock does not match pyproject, so CI
+      # resolves exactly what a developer resolved rather than picking up a
+      # newer release mid-run. --no-build installs from wheels only, which
+      # keeps a dependency's setup.py from executing on the runner.
+      #
+      # The editable workspace members install regardless: --no-build refuses
+      # source distributions of dependencies, not a local editable install.
+      # Verified both ways, since the flag reads as though it would block them:
+      # a sync with an empty UV_CACHE_DIR into a fresh environment installs
+      # coordinode, langchain-coordinode and llama-index-graph-stores-coordinode
+      # and imports them, and every job below has run green with the flag on a
+      # clean runner. Remove it only with evidence, not on the wording.
+      - run: uv sync --locked --no-build
+      - run: uv run --locked --no-build ruff check coordinode/ langchain-coordinode/ llama-index-coordinode/ tests/
+      - run: uv run --locked --no-build ruff format --check coordinode/ langchain-coordinode/ llama-index-coordinode/ tests/
 
   test:
     name: Test (Python ${{ matrix.python-version }})
@@ -37,13 +49,13 @@
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --all-packages
+        run: uv sync --locked --no-build --all-packages
 
       - name: Generate proto stubs
-        run: uv run make proto
+        run: uv run --locked --no-build make proto
 
       - name: Unit tests
-        run: uv run pytest tests/unit/ -v
+        run: uv run --locked --no-build pytest tests/unit/ -v
 
   build-embedded:
     name: Build embedded (CI check)
@@ -83,8 +95,17 @@
           WHL=$(ls dist/coordinode_embedded-*.whl | head -1)
           test -n "$WHL"
           uv venv --python 3.12 /tmp/test-venv
-          uv pip install --python /tmp/test-venv/bin/python "$WHL" numpy pytest pytest-timeout
-          OUTPUT=$(/tmp/test-venv/bin/python -m pytest tests/unit/test_hnsw.py -v --strict-markers -ra 2>&1)
+          # Pinned to the versions uv.lock already resolves for the workspace,
+          # so this throwaway venv tests against the same stack as the other
+          # jobs instead of whatever is newest on PyPI that morning.
+          uv pip install --python /tmp/test-venv/bin/python "$WHL" \
+            numpy==2.4.6 pytest==9.1.1 pytest-timeout==2.4.0
+          # Every test file that needs the extension belongs here: the main
+          # `test` job skips them all for want of a wheel, so a file left out
+          # of this list runs in no job at all.
+          OUTPUT=$(/tmp/test-venv/bin/python -m pytest \
+            tests/unit/test_hnsw.py tests/unit/test_embedded_values.py \
+            -v --strict-markers -ra 2>&1)
           echo "$OUTPUT"
           # `-ra` prints a "SKIPPED [N]" short summary header when anything was
           # skipped; importorskip-based skip also surfaces this way.  Use the
@@ -104,7 +125,11 @@
     runs-on: ubuntu-latest
     services:
       coordinode:
-        image: ghcr.io/structured-world/coordinode:latest
+        # Pinned by digest, not by tag: the proto submodule pins a server
+        # version, and a tag can be re-pushed, so `:0.5.5` alone does not name
+        # one fixed server. The digest below is 0.5.5; bump both together with
+        # the submodule.
+        image: ghcr.io/structured-world/coordinode@sha256:8d3554be7680aa2cea7b6e773037aee97513865f4698b6df0ffc2daf845c42b8
         ports:
           - 7080:7080
           - 7084:7084
@@ -134,10 +159,10 @@
 
       - name: Install + generate proto
         run: |
-          uv sync --all-packages
-          uv run make proto
+          uv sync --locked --no-build --all-packages
+          uv run --locked --no-build make proto
 
       - name: Integration tests
         env:
           COORDINODE_ADDR: "localhost:7080"
-        run: uv run pytest tests/integration/ -v --timeout=30
+        run: uv run --locked --no-build pytest tests/integration/ -v --timeout=30

Makefile

@@ -2,18 +2,33 @@
 
 PROTO_SRC  := proto
 PROTO_OUT  := coordinode/coordinode/_proto
-PYTHON     ?= python3
+# grpcio-tools lives in the synced environment, so both the include-path probe
+# below and the generation itself have to run through the same interpreter.
+# A bare python3 finds neither.
+PYTHON     ?= uv run python
+
+# Well-known types that ship with grpc_tools. The proto submodule vendors its
+# own google/protobuf/descriptor.proto so the Rust build works on hosts without
+# protobuf-devel; that copy is older than what this protoc expects and, if it
+# wins the include search, generation dies with "Malformed descriptor.proto
+# doesn't contain google.protobuf.FeatureSet". Searching here first keeps
+# descriptor.proto on protoc's own copy while google/api/* still resolves from
+# the submodule, which is the only place it exists.
+# Deferred, not `:=`: an immediate assignment would shell out to $(PYTHON) on
+# every make invocation, including `make clean` on a machine with no uv.
+GRPC_INC = $(shell $(PYTHON) -c "import grpc_tools, os; print(os.path.join(os.path.dirname(grpc_tools.__file__), '_proto'))")
 
 # Generate gRPC stubs from proto submodule into coordinode/_proto/
 proto:
 	@echo "==> Generating proto stubs..."
 	@mkdir -p $(PROTO_OUT)
 	$(PYTHON) -m grpc_tools.protoc \
+		-I"$(GRPC_INC)" \
 		-I$(PROTO_SRC) \
 		--python_out=$(PROTO_OUT) \
 		--grpc_python_out=$(PROTO_OUT) \
 		--pyi_out=$(PROTO_OUT) \
-		$$(find $(PROTO_SRC) -name '*.proto')
+		$$(find $(PROTO_SRC) -name '*.proto' -not -path '$(PROTO_SRC)/google/protobuf/*')
 	@# Add __init__.py to every generated package directory
 	@find $(PROTO_OUT) -type d -exec touch {}/__init__.py \;
 	@# Fix absolute imports in all generated pb2 files (grpc_tools generates absolute paths)
@@ -34,12 +49,21 @@ install:
 	uv sync
 	$(MAKE) proto
 
-# Install using pip (alternative — works without uv)
+# Install using pip (alternative that works without uv).
+#
+# PIP_PYTHON, not a bare `pip`: the whole point of this target is a machine
+# with no uv, and there `pip` and `python3` can be two different interpreters
+# (a pip from 3.11 on PATH ahead of a 3.13 python3, say). Installing through
+# one and generating stubs with the other puts grpcio-tools in an environment
+# the generation step cannot see. Everything below goes through the same
+# interpreter, and `make install-pip PIP_PYTHON=python3.12` picks another.
+PIP_PYTHON ?= python3
+
 install-pip:
-	pip install -e "coordinode[dev]"
-	pip install -e langchain-coordinode/
-	pip install -e llama-index-coordinode/
-	$(MAKE) proto
+	$(PIP_PYTHON) -m pip install -e "coordinode[dev]"
+	$(PIP_PYTHON) -m pip install -e langchain-coordinode/
+	$(PIP_PYTHON) -m pip install -e llama-index-coordinode/
+	$(MAKE) proto PYTHON="$(PIP_PYTHON)"
 
 test: proto-check test-unit