coda-node 0.1.0__tar.gz → 0.1.1__tar.gz

coda_node-0.1.1/.agents/skills/update-changelog/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: update-changelog
+description: Add an entry to CHANGELOG.md for a new version.
+disable-model-invocation: true
+argument-hint: [version]
+---
+
+# Update Changelog
+
+Add a new entry to `CHANGELOG.md` for the given version.
+
+## Steps
+
+1. Read `CHANGELOG.md`.
+2. Review recent commits since the last tagged release with `git log`.
+3. Add a new `## [x.y.z] - YYYY-MM-DD` section below the header, above the previous entry.
+4. Summarise changes concisely under `### Added`, `### Changed`, `### Fixed`, or `### Removed` subsections as appropriate.
+5. Follow the existing style — short bullet points, no links.
+
+## Arguments
+
+`/update-changelog 0.3.0` — the version string to use in the heading. If omitted, ask the user.

{coda_node-0.1.0 → coda_node-0.1.1}/.github/workflows/ci.yml

@@ -4,6 +4,7 @@ on:
   push:
   pull_request:
   workflow_dispatch:
+  workflow_call:
 
 jobs:
   test:

{coda_node-0.1.0 → coda_node-0.1.1}/.github/workflows/publish.yml

@@ -1,6 +1,12 @@
 name: Publish to PyPI
 
 on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing release tag to publish (e.g. v0.2.0)"
+        required: true
+        type: string
   release:
     types:
       - created
@@ -15,6 +21,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          ref: refs/tags/${{ inputs.tag || github.event.release.tag_name }}
 
       - name: Set up Python
         uses: actions/setup-python@v6

coda_node-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,118 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 0.2.0)"
+        required: true
+        type: string
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+env:
+  VERSION: ${{ inputs.version }}
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Require main branch
+        run: |
+          if [ "$GITHUB_REF" != "refs/heads/main" ]; then
+            echo "::error::Releases must be run from main"
+            exit 1
+          fi
+
+      - name: Validate semver format
+        run: |
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Version '$VERSION' is not valid semver (expected x.y.z)"
+            exit 1
+          fi
+
+      - name: Check tag does not already exist
+        run: |
+          if git show-ref --verify --quiet "refs/tags/v${VERSION}"; then
+            echo "::error::Tag v${VERSION} already exists"
+            exit 1
+          fi
+
+      - name: Check CHANGELOG has entry for version
+        run: |
+          if ! awk -v heading="## [$VERSION]" '
+            index($0, heading) == 1 {found=1}
+            END {exit !found}
+          ' CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no entry for version $VERSION"
+            exit 1
+          fi
+
+  ci:
+    needs: validate
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: ci
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.sha }}
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Bump version in pyproject.toml
+        run: sed -i "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml
+
+      - name: Bump version in __init__.py
+        run: sed -i "s/^__version__ = \".*\"/__version__ = \"${VERSION}\"/" src/coda_node/__init__.py
+
+      - name: Refresh lockfile
+        run: uv lock
+
+      - name: Commit and tag
+        run: |
+          git add pyproject.toml src/coda_node/__init__.py uv.lock
+          if ! git diff --cached --quiet; then
+            git commit -m "release: v${VERSION}"
+          fi
+          git tag "v${VERSION}"
+          git push --atomic origin HEAD:refs/heads/main "refs/tags/v${VERSION}"
+
+      - name: Extract release notes from CHANGELOG
+        run: |
+          awk -v heading="## [$VERSION]" '
+            index($0, heading) == 1 {found=1; next}
+            found && /^## \[/ {exit}
+            found
+          ' CHANGELOG.md > release-notes.md
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "v${VERSION}" \
+            --verify-tag \
+            --title "v${VERSION}" \
+            --notes-file release-notes.md
+
+      - name: Start PyPI publishing
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run publish.yml --ref main --field "tag=v${VERSION}"

coda_node-0.1.1/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.1] - 2026-04-06
+
+### Added
+
+- Connectivity reporting in heartbeat and connect payloads.
+- `HeartbeatRejectedError` when the platform rejects a heartbeat.
+
+## [0.1.0] - 2026-04-01
+
+### Added
+
+- Initial release: JWT auth, VPN management, Redis job consumer, webhook delivery, heartbeat, IR/QASM support, `JobExecutor` protocol, daemon mode, and CLI.

{coda_node-0.1.0 → coda_node-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: coda-node
-Version: 0.1.0
+Version: 0.1.1
 Summary: Minimal server runtime for connecting execution backends to Coda.
 Author: Conductor Quantum
 License: MIT License

{coda_node-0.1.0 → coda_node-0.1.1}/docs/node/CONNECT_PROTOCOL.md

@@ -25,31 +25,32 @@ The cloud uses `token.split(".").length === 3` to detect JWTs.
 
 ```json
 {
-  "machine_fingerprint": "hostname-macaddr"
+  "machine_fingerprint": "hostname-macaddr",
+  "connectivity": [[1, 0], [2, 1]]
 }
 ```
 
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `machine_fingerprint` | `string` | Yes | Stable host identifier (`{hostname}-{mac_address}`). Generated by the node if not set. Stored on first run and verified on subsequent reconnects. |
+| `connectivity` | `number[][]` \| omitted | No | Live edge list from the executor device spec (same shape as heartbeat). When present, the cloud validates every endpoint against the registered `qpu_devices.qubits` / bootstrap token `num_qubits` **before** issuing the bundle, so a topology mismatch fails at connect time. Omitted when the executor has no device (e.g. `NoopExecutor`). |
 
 ### Node-Side Request Construction
 
-**Node** (`fetch_node_bundle` in `vpn/service.py`):
+**Node** (`fetch_node_bundle` / `fetch_reconnect_bundle` in `vpn/service.py`):
 
-```python
-payload = {"machine_fingerprint": settings.node_machine_fingerprint}
-auth_header = f"Bearer {settings.node_token}"
-```
-
-**Reconnect** (`fetch_reconnect_bundle` in `vpn/service.py`):
+After `connect_settings` loads the executor via `_connectivity_payload_for_connect()`,
+the JSON body includes `machine_fingerprint` and, when available, `connectivity`.
 
 ```python
 payload = {"machine_fingerprint": settings.node_machine_fingerprint}
-token = sign_token(settings.qpu_id, settings.jwt_private_key, key_id=settings.jwt_key_id)
-auth_header = f"Bearer {token}"
+if connectivity is not None:
+    payload["connectivity"] = connectivity
+auth_header = f"Bearer {settings.node_token}"  # or JWT for reconnect
 ```
 
+**Reconnect** uses the same payload shape with a JWT `Authorization` header.
+
 Both call `_post_connect()` with exponential-backoff retry on 5xx and
 transport errors (configurable via `CODA_NODE_CONNECT_RETRIES`,
 default 3).

{coda_node-0.1.0 → coda_node-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coda-node"
-version = "0.1.0"
+version = "0.1.1"
 description = "Minimal server runtime for connecting execution backends to Coda."
 readme = "README.md"
 requires-python = ">=3.11"

{coda_node-0.1.0 → coda_node-0.1.1}/src/coda_node/__init__.py

@@ -14,5 +14,5 @@ Typical usage::
 from coda_node.errors import CodaError
 from coda_node.server import app, create_app
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 __all__ = ["CodaError", "__version__", "app", "create_app"]

{coda_node-0.1.0 → coda_node-0.1.1}/src/coda_node/errors.py

@@ -10,6 +10,7 @@ __all__ = [
     "CodaError",
     "ConfigError",
     "ExecutorError",
+    "HeartbeatRejectedError",
     "NodeError",
     "VPNError",
     "WebhookError",
@@ -36,6 +37,10 @@ class NodeError(CodaError):
     """Node provisioning or reconnect failure."""
 
 
+class HeartbeatRejectedError(CodaError):
+    """Cloud returned a non-success response to a QPU heartbeat POST."""
+
+
 class ExecutorError(CodaError):
     """Executor loading or job execution failure."""
 

{coda_node-0.1.0 → coda_node-0.1.1}/src/coda_node/server/app.py

@@ -19,6 +19,7 @@ from fastapi.responses import JSONResponse
 
 from coda_node.server.config import Settings
 from coda_node.server.consumer import RedisConsumer
+from coda_node.server.device_topology import resolve_connectivity_from_device_spec
 from coda_node.server.executor import JobExecutor, load_executor
 from coda_node.server.heartbeat import HeartbeatClient
 from coda_node.server.webhook import WebhookClient
@@ -32,16 +33,6 @@ from coda_node.vpn import (
 logger = logging.getLogger(__name__)
 
 
-def _resolve_connectivity(device_spec: object | None) -> list[list[int]] | None:
-    """Extract qubit connectivity from a device spec, preferring directed edges."""
-    if device_spec is None:
-        return None
-    directed = getattr(device_spec, "directed_edges", None)
-    if directed:
-        return [list(e) for e in directed]
-    return [list(e) for e in device_spec.logical_edges]  # type: ignore[attr-defined]
-
-
 async def _on_vpn_state_change(state: ServiceState) -> None:
     """Log VPN state transitions at WARNING level."""
     logger.warning("VPN state changed: %s", state.value)
@@ -93,7 +84,7 @@ def create_app(executor: JobExecutor | None = None) -> FastAPI:
         runner = executor or load_executor(settings)
 
         device_spec = getattr(runner, "device", None)
-        connectivity = _resolve_connectivity(device_spec)
+        connectivity = resolve_connectivity_from_device_spec(device_spec)
 
         webhook = WebhookClient(
             qpu_id=settings.qpu_id,

coda_node-0.1.1/src/coda_node/server/device_topology.py

@@ -0,0 +1,20 @@
+"""Extract qubit connectivity from an executor device spec for cloud reporting."""
+
+from __future__ import annotations
+
+__all__ = ["resolve_connectivity_from_device_spec"]
+
+
+def resolve_connectivity_from_device_spec(
+    device_spec: object | None,
+) -> list[list[int]] | None:
+    """Extract qubit connectivity from a device spec, preferring directed edges.
+
+    Matches the shape sent in node heartbeats and connect payloads.
+    """
+    if device_spec is None:
+        return None
+    directed = getattr(device_spec, "directed_edges", None)
+    if directed:
+        return [list(e) for e in directed]
+    return [list(e) for e in device_spec.logical_edges]  # type: ignore[attr-defined]

{coda_node-0.1.0 → coda_node-0.1.1}/src/coda_node/server/heartbeat.py

@@ -18,6 +18,7 @@ from typing import TYPE_CHECKING
 
 import httpx
 
+from coda_node.errors import HeartbeatRejectedError
 from coda_node.server.auth import sign_token
 
 if TYPE_CHECKING:
@@ -31,6 +32,20 @@ _DEFAULT_INTERVAL = 30
 _HTTP_TIMEOUT = 10.0
 
 
+def _format_heartbeat_error_response(response: httpx.Response) -> str:
+    """Best-effort message from a failed heartbeat response body."""
+    try:
+        data = response.json()
+        if isinstance(data, dict) and "error" in data:
+            return str(data["error"])
+    except Exception:
+        pass
+    text = (response.text or "").strip()
+    if text:
+        return text[:800]
+    return response.reason_phrase or "unknown error"
+
+
 class HeartbeatClient:
     """Send periodic authenticated heartbeats to the Coda cloud.
 
@@ -87,7 +102,12 @@ class HeartbeatClient:
             json=body,
             headers={"Authorization": f"Bearer {token}", **self._extra_headers},
         )
-        response.raise_for_status()
+        if response.is_success:
+            return
+        detail = _format_heartbeat_error_response(response)
+        raise HeartbeatRejectedError(
+            f"HTTP {response.status_code} from heartbeat endpoint: {detail}"
+        )
 
     async def run(self) -> None:
         """Run the heartbeat loop until :meth:`stop` is called."""
@@ -99,6 +119,13 @@ class HeartbeatClient:
             try:
                 await self._send()
                 logger.debug("Heartbeat sent to %s", self._url)
+            except HeartbeatRejectedError as exc:
+                logger.warning(
+                    "Heartbeat rejected by cloud (%s). Fix configuration or align "
+                    "qpu_devices.qubits with the node's reported connectivity. %s",
+                    self._url,
+                    exc,
+                )
             except Exception:
                 logger.warning("Heartbeat to %s failed", self._url, exc_info=True)
             await asyncio.sleep(self._interval)

{coda_node-0.1.0 → coda_node-0.1.1}/src/coda_node/vpn/service.py

@@ -363,7 +363,34 @@ async def _post_connect(
     ) from last_exc
 
 
-async def fetch_node_bundle(settings: Settings) -> dict[str, Any]:
+def _connectivity_payload_for_connect(settings: Settings) -> list[list[int]] | None:
+    """Load the executor and derive live topology for the connect handshake.
+
+    If the executor cannot be loaded (missing config, import errors), returns
+    ``None`` so connect proceeds without ``connectivity`` (cloud skips validation).
+    """
+    try:
+        from coda_node.server.device_topology import (
+            resolve_connectivity_from_device_spec,
+        )
+        from coda_node.server.executor import load_executor
+
+        runner = load_executor(settings)
+        device_spec = getattr(runner, "device", None)
+        return resolve_connectivity_from_device_spec(device_spec)
+    except Exception as exc:
+        logger.warning(
+            "Skipping live connectivity on connect handshake (executor unavailable): %s",
+            exc,
+        )
+        return None
+
+
+async def fetch_node_bundle(
+    settings: Settings,
+    *,
+    connectivity: list[list[int]] | None = None,
+) -> dict[str, Any]:
     """Fetch the provisioning bundle using a one-time node token.
 
     POSTs the machine fingerprint to the Coda connect endpoint.  The
@@ -383,9 +410,11 @@ async def fetch_node_bundle(settings: Settings) -> dict[str, Any]:
     if not settings.node_token:
         raise NodeError("node token is empty")
 
-    payload = {
+    payload: dict[str, Any] = {
         "machine_fingerprint": _resolve_machine_fingerprint(settings),
     }
+    if connectivity is not None:
+        payload["connectivity"] = connectivity
     return await _post_connect(
         settings,
         auth_header=f"Bearer {settings.node_token}",
@@ -394,7 +423,11 @@ async def fetch_node_bundle(settings: Settings) -> dict[str, Any]:
     )
 
 
-async def fetch_reconnect_bundle(settings: Settings) -> dict[str, Any]:
+async def fetch_reconnect_bundle(
+    settings: Settings,
+    *,
+    connectivity: list[list[int]] | None = None,
+) -> dict[str, Any]:
     """Fetch a reconnect bundle using stored JWT credentials.
 
     Authenticates with a freshly signed JWT (instead of a node
@@ -411,9 +444,11 @@ async def fetch_reconnect_bundle(settings: Settings) -> dict[str, Any]:
     Raises:
         NodeError: If the HTTP request fails.
     """
-    payload = {
+    payload: dict[str, Any] = {
         "machine_fingerprint": _resolve_machine_fingerprint(settings),
     }
+    if connectivity is not None:
+        payload["connectivity"] = connectivity
     token = sign_token(
         settings.qpu_id,
         settings.jwt_private_key,
@@ -539,11 +574,12 @@ async def connect_settings(settings: Settings) -> None:
         NodeError: On provisioning or reconnect failure.
     """
     _resolve_machine_fingerprint(settings)
+    connectivity = _connectivity_payload_for_connect(settings)
     if settings.node_token:
-        bundle = await fetch_node_bundle(settings)
+        bundle = await fetch_node_bundle(settings, connectivity=connectivity)
     else:
         await ensure_persisted_vpn(settings)
-        bundle = await fetch_reconnect_bundle(settings)
+        bundle = await fetch_reconnect_bundle(settings, connectivity=connectivity)
     try:
         await apply_node_bundle(settings, bundle)
         await asyncio.to_thread(_persist_runtime_config, settings)

coda_node-0.1.1/tests/test_device_topology.py

@@ -0,0 +1,25 @@
+"""Tests for device topology helpers."""
+
+from coda_node.server.device_topology import resolve_connectivity_from_device_spec
+
+
+class _FakeDevice:
+    def __init__(
+        self, directed: list[tuple[int, int]] | None, logical: list[tuple[int, int]]
+    ) -> None:
+        self.directed_edges = directed
+        self.logical_edges = logical
+
+
+def test_prefers_directed_edges() -> None:
+    spec = _FakeDevice([(1, 0), (2, 1)], [(0, 1)])
+    assert resolve_connectivity_from_device_spec(spec) == [[1, 0], [2, 1]]
+
+
+def test_falls_back_to_logical_edges() -> None:
+    spec = _FakeDevice(None, [(0, 1), (1, 2)])
+    assert resolve_connectivity_from_device_spec(spec) == [[0, 1], [1, 2]]
+
+
+def test_none_spec() -> None:
+    assert resolve_connectivity_from_device_spec(None) is None

{coda_node-0.1.0 → coda_node-0.1.1}/tests/test_heartbeat.py

@@ -6,7 +6,8 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
-from coda_node.server.heartbeat import HeartbeatClient
+from coda_node.errors import HeartbeatRejectedError
+from coda_node.server.heartbeat import HeartbeatClient, _format_heartbeat_error_response
 
 
 def _make_consumer(**overrides: object) -> MagicMock:
@@ -18,6 +19,42 @@ def _make_consumer(**overrides: object) -> MagicMock:
     return consumer
 
 
+def test_format_heartbeat_error_response_prefers_json_error_field() -> None:
+    response = MagicMock()
+    response.json.return_value = {"error": "Connectivity edge (19, 18) outside [0, 19)"}
+    assert (
+        _format_heartbeat_error_response(response)
+        == "Connectivity edge (19, 18) outside [0, 19)"
+    )
+
+
+@patch("coda_node.server.heartbeat.sign_token", return_value="mock-jwt")
+async def test_send_raises_heartbeat_rejected_on_http_error(
+    _mock_sign: MagicMock,
+) -> None:
+    mock_response = MagicMock()
+    mock_response.is_success = False
+    mock_response.status_code = 400
+    mock_response.json.return_value = {"error": "topology mismatch"}
+    mock_response.reason_phrase = "Bad Request"
+    mock_response.text = '{"error": "topology mismatch"}'
+    mock_http = AsyncMock()
+    mock_http.post = AsyncMock(return_value=mock_response)
+
+    consumer = _make_consumer()
+    client = HeartbeatClient(
+        heartbeat_url="https://example.com/heartbeat",
+        qpu_id="qpu-1",
+        jwt_private_key="fake-key",
+        jwt_key_id="kid-1",
+        consumer=consumer,
+    )
+    client._client = mock_http
+
+    with pytest.raises(HeartbeatRejectedError, match=r"400.*topology mismatch"):
+        await client._send()
+
+
 @patch("coda_node.server.heartbeat.sign_token", return_value="mock-jwt")
 async def test_send_posts_authenticated_payload(_mock_sign: MagicMock) -> None:
     mock_response = AsyncMock()

{coda_node-0.1.0 → coda_node-0.1.1}/tests/test_main.py

@@ -9,7 +9,6 @@ from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 from fastapi.testclient import TestClient
 
-from coda_node.server.app import _resolve_connectivity
 from coda_node.vpn import ServiceState
 
 
@@ -104,30 +103,3 @@ def test_ready_endpoint_redis_unhealthy() -> None:
         body = response.json()
         assert body["ready"] is False
         assert body["redis_healthy"] is False
-
-
-def test_resolve_connectivity_prefers_directed_edges() -> None:
-    device = MagicMock()
-    device.directed_edges = [(1, 0), (2, 1)]
-    device.logical_edges = [(0, 1), (1, 2)]
-
-    assert _resolve_connectivity(device) == [[1, 0], [2, 1]]
-
-
-def test_resolve_connectivity_falls_back_to_logical_edges() -> None:
-    device = MagicMock(spec=["logical_edges"])
-    device.logical_edges = [(0, 1), (1, 2)]
-
-    assert _resolve_connectivity(device) == [[0, 1], [1, 2]]
-
-
-def test_resolve_connectivity_returns_none_without_device() -> None:
-    assert _resolve_connectivity(None) is None
-
-
-def test_resolve_connectivity_falls_back_when_directed_edges_empty() -> None:
-    device = MagicMock()
-    device.directed_edges = []
-    device.logical_edges = [(0, 1), (1, 2)]
-
-    assert _resolve_connectivity(device) == [[0, 1], [1, 2]]