fix(sdk,demo): validate causal-read precondition; clarify embedded install path

- cypher() now raises ValueError client-side when after_index > 0 is
  combined with non-majority write_concern. The server rejects this
  combination; surfacing it earlier gives a clearer error and matches
  the documented contract. Unit coverage added.
- Notebook ImportError message on missing coordinode-embedded now lists
  the explicit local install path (git+ pip install from the repo
  subdirectory, Rust toolchain note, ~5 min build) alongside the Colab
  install-cell hint and the server-mode escape hatch.
- Notebook 00 markdown drops the hard-coded /tmp fallback phrasing;
  success print shows the runtime COORDINODE_EMBEDDED_PATH verbatim.
- Notebook 01/02 comment block now accurately describes coordinode as
  git-pinned in Colab and unpinned outside, rather than claiming it is
  always unpinned.

Author: polaz

coordinode/coordinode/client.py

@@ -275,6 +275,14 @@ async def cypher(
             ExecuteCypherRequest,
         )
 
+        # Causal reads (after_index > 0) are only satisfiable when writes were
+        # acknowledged by a majority; otherwise the referenced index may never
+        # replicate and the read would hang. Mirror the server's rejection.
+        if after_index is not None and after_index > 0 and (write_concern or "").lower() != "majority":
+            raise ValueError(
+                "after_index > 0 requires write_concern='majority' — causal reads "
+                "depend on majority-committed writes. Pass write_concern='majority'."
+            )
         req = ExecuteCypherRequest(
             query=query,
             parameters=dict_to_props(params or {}),

demo/notebooks/00_seed_data.ipynb

@@ -12,7 +12,7 @@
     "Populates CoordiNode with a **tech industry knowledge graph**.\n",
     "\n",
     "> **Note:** Embedded mode writes to `COORDINODE_EMBEDDED_PATH` (default\n",
-    "> `/content/coordinode-demo.db` in Colab, `/tmp/coordinode-demo.db` locally), so\n",
+    "> `/content/coordinode-demo.db` in Colab, the OS temp dir locally), so\n",
     "> the seeded graph persists across cell reruns and is visible to sibling demo\n",
     "> notebooks within the same runtime. Delete the file or set a different path to\n",
     "> reset. Connecting to a real CoordiNode server via `COORDINODE_ADDR` is also\n",
@@ -146,7 +146,7 @@
     "\n",
     "- **Colab**: uses `LocalClient(COORDINODE_EMBEDDED_PATH)` \u2014 in-process embedded engine backed by a file under `/content/`, no server required.\n",
     "- **Local with server**: set `COORDINODE_ADDR=host:port` to point at a running CoordiNode (no auto-probe \u2014 explicit only).\n",
-    "- **Local without server**: uses `coordinode-embedded` (file-backed at `COORDINODE_EMBEDDED_PATH`, default `/tmp/coordinode-demo.db`). Raises `RuntimeError` with install instructions if the package is missing."
+    "- **Local without server**: uses `coordinode-embedded` (file-backed at `COORDINODE_EMBEDDED_PATH`, defaulting to the OS temp dir). Raises `RuntimeError` with install instructions if the package is missing."
    ]
   },
   {
@@ -186,7 +186,11 @@
     "    except ImportError as exc:\n",
     "        raise RuntimeError(\n",
     "            \"coordinode-embedded is not installed. \"\n",
-    "            \"Run the install cell above, or start a CoordiNode server and set COORDINODE_ADDR.\"\n",
+    "            \"In Colab, rerun the install cell above. \"\n",
+    "            \"Locally, install from source: \"\n",
+    "            \"pip install 'git+https://github.com/structured-world/coordinode-python.git#subdirectory=coordinode-embedded' \"\n",
+    "            \"(requires Rust toolchain, ~5 min build). \"\n",
+    "            \"Alternatively start a CoordiNode server and set COORDINODE_ADDR.\"\n",
     "        ) from exc\n",
     "\n",
     "    client = LocalClient(COORDINODE_EMBEDDED_PATH)\n",
@@ -466,7 +470,7 @@
     "\n",
     "print(\"\\n\u2713 Demo data seeded.\")\n",
     "print(\"To query it from notebooks 01\u201303:\")\n",
-    "print(\"  - Embedded mode: open them with the same COORDINODE_EMBEDDED_PATH (default /content/coordinode-demo.db in Colab, /tmp/coordinode-demo.db locally) \u2014 they will see this seeded graph.\")\n",
+    "print(f\"  - Embedded mode: open them with the same COORDINODE_EMBEDDED_PATH (this run: {COORDINODE_EMBEDDED_PATH}) \u2014 they will see this seeded graph.\")\n",
     "print(\"  - Server mode: point them at the same running CoordiNode via COORDINODE_ADDR.\")\n",
     "client.close()"
    ]

demo/notebooks/01_llama_index_property_graph.ipynb

@@ -99,8 +99,10 @@
     "\n",
     "# coordinode-embedded is pinned to a specific git commit because it requires a Rust\n",
     "# build (maturin/pyo3) and the embedded engine must match the Python SDK version.\n",
-    "# The remaining packages (coordinode, llama-index, etc.) are installed without pins:\n",
-    "# they are pure Python, release frequently, and pip resolves a compatible version.\n",
+    "# coordinode (SDK) is git-pinned in Colab via _coordinode_spec to keep the\n",
+    "# SDK/proto in sync with this PR; outside Colab it resolves from PyPI.\n",
+    "# Other packages (LangChain / llama-index / nest_asyncio) are unpinned \u2014 pure\n",
+    "# Python, release frequently, pip resolves a compatible version.\n",
     "_coordinode_spec = (\n",
     "    \"git+https://github.com/structured-world/coordinode-python.git@c2d62b0595867651df43c2b3d3fdbec4341d6642#subdirectory=coordinode\"\n",
     "    if IN_COLAB\n",
@@ -220,7 +222,11 @@
     "    except ImportError as exc:\n",
     "        raise RuntimeError(\n",
     "            \"coordinode-embedded is not installed. \"\n",
-    "            \"Run the install cell above, or start a CoordiNode server and set COORDINODE_ADDR.\"\n",
+    "            \"In Colab, rerun the install cell above. \"\n",
+    "            \"Locally, install from source: \"\n",
+    "            \"pip install 'git+https://github.com/structured-world/coordinode-python.git#subdirectory=coordinode-embedded' \"\n",
+    "            \"(requires Rust toolchain, ~5 min build). \"\n",
+    "            \"Alternatively start a CoordiNode server and set COORDINODE_ADDR.\"\n",
     "        ) from exc\n",
     "\n",
     "    _lc = LocalClient(COORDINODE_EMBEDDED_PATH)\n",

demo/notebooks/02_langchain_graph_chain.ipynb

@@ -99,8 +99,10 @@
     "#   must match the Python SDK version.\n",
     "# - langchain-coordinode is pinned to the same commit so CoordinodeGraph(client=...)\n",
     "#   is available; this parameter is not yet released to PyPI.\n",
-    "# The remaining packages (coordinode, LangChain, etc.) are installed without pins:\n",
-    "# they are pure Python, release frequently, and pip resolves a compatible version.\n",
+    "# coordinode (SDK) is git-pinned in Colab via _coordinode_spec to keep the\n",
+    "# SDK/proto in sync with this PR; outside Colab it resolves from PyPI.\n",
+    "# Other packages (LangChain / llama-index / nest_asyncio) are unpinned \u2014 pure\n",
+    "# Python, release frequently, pip resolves a compatible version.\n",
     "_coordinode_spec = (\n",
     "    \"git+https://github.com/structured-world/coordinode-python.git@c2d62b0595867651df43c2b3d3fdbec4341d6642#subdirectory=coordinode\"\n",
     "    if IN_COLAB\n",
@@ -221,7 +223,11 @@
     "    except ImportError as exc:\n",
     "        raise RuntimeError(\n",
     "            \"coordinode-embedded is not installed. \"\n",
-    "            \"Run the install cell above, or start a CoordiNode server and set COORDINODE_ADDR.\"\n",
+    "            \"In Colab, rerun the install cell above. \"\n",
+    "            \"Locally, install from source: \"\n",
+    "            \"pip install 'git+https://github.com/structured-world/coordinode-python.git#subdirectory=coordinode-embedded' \"\n",
+    "            \"(requires Rust toolchain, ~5 min build). \"\n",
+    "            \"Alternatively start a CoordiNode server and set COORDINODE_ADDR.\"\n",
     "        ) from exc\n",
     "\n",
     "    _lc = LocalClient(COORDINODE_EMBEDDED_PATH)\n",

demo/notebooks/03_langgraph_agent.ipynb

@@ -174,7 +174,11 @@
     "    except ImportError as exc:\n",
     "        raise RuntimeError(\n",
     "            \"coordinode-embedded is not installed. \"\n",
-    "            \"Run the install cell above, or start a CoordiNode server and set COORDINODE_ADDR.\"\n",
+    "            \"In Colab, rerun the install cell above. \"\n",
+    "            \"Locally, install from source: \"\n",
+    "            \"pip install 'git+https://github.com/structured-world/coordinode-python.git#subdirectory=coordinode-embedded' \"\n",
+    "            \"(requires Rust toolchain, ~5 min build). \"\n",
+    "            \"Alternatively start a CoordiNode server and set COORDINODE_ADDR.\"\n",
     "        ) from exc\n",
     "\n",
     "    client = LocalClient(COORDINODE_EMBEDDED_PATH)\n",

tests/integration/test_sdk.py

@@ -728,3 +728,8 @@ def test_cypher_rejects_invalid_consistency_values(client):
         client.cypher("RETURN 1", read_preference="leader")
     with pytest.raises(ValueError, match="after_index must be a non-negative integer"):
         client.cypher("RETURN 1", after_index=-1)
+    # Causal reads (after_index > 0) require write_concern='majority'.
+    with pytest.raises(ValueError, match="after_index > 0 requires write_concern='majority'"):
+        client.cypher("RETURN 1", after_index=42)
+    with pytest.raises(ValueError, match="after_index > 0 requires write_concern='majority'"):
+        client.cypher("RETURN 1", after_index=42, write_concern="w1")