test: add Node interoperability

.github/workflows/interoperability.yml

@@ -0,0 +1,67 @@
+name: Node.js interoperability
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/interoperability.yml"
+      - "Makefile"
+      - "pyproject.toml"
+      - "scripts/node_interoperability.py"
+      - "scripts/run-node-interoperability.sh"
+      - "scripts/verify-node-interoperability.mjs"
+      - "src/**"
+      - "uv.lock"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  interoperability:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: aep-python
+
+      - uses: actions/checkout@v7
+        with:
+          repository: aep-foundation/aep-node
+          path: aep-node
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          version: "0.11.8"
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - run: corepack enable
+
+      - name: Install Python dependencies
+        working-directory: aep-python
+        run: uv sync --all-groups --locked
+
+      - name: Install Node.js dependencies
+        working-directory: aep-node
+        run: pnpm install --frozen-lockfile
+
+      - name: Run bidirectional interoperability
+        working-directory: aep-python
+        run: make interoperability
+        env:
+          AEP_INTEROP_OUTPUT_DIR: .interop/reports
+          AEP_NODE_DIR: ../aep-node
+
+      - name: Upload interoperability report
+        uses: actions/upload-artifact@v7
+        with:
+          name: aep-python-node-interoperability
+          path: aep-python/.interop/reports/aep-python-node-interoperability.json
+          if-no-files-found: error
+          retention-days: 7

.gitignore

@@ -1,5 +1,6 @@
 /.conformance/aep-specs/
 /.conformance/reports/
+/.interop/
 /.mypy_cache/
 /.pytest_cache/
 /.ruff_cache/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build conformance consumer-smoke examples format format-check lint sync test typecheck verify
+.PHONY: build conformance consumer-smoke examples format format-check interoperability lint sync test typecheck verify
 
 sync:
 	uv sync --all-groups --locked
@@ -34,4 +34,8 @@ examples:
 conformance:
 	./scripts/run-conformance.sh
 
+interoperability:
+	uv run mypy scripts/node_interoperability.py
+	./scripts/run-node-interoperability.sh
+
 verify: lint typecheck test examples consumer-smoke

README.md

@@ -200,6 +200,16 @@ make conformance
 The command reads the adjacent `../aep-specs` checkout by default and writes role reports to
 `.conformance/reports/`. Set `AEP_SPECS_DIR` when the specifications are checked out elsewhere.
 
+Run bidirectional Agent, Service, and Platform interoperability against the Node.js SDK:
+
+```sh
+make interoperability
+```
+
+The command reads the adjacent `../aep-node` checkout by default and writes a four-row evidence
+report to `.interop/reports/aep-python-node-interoperability.json`. Set `AEP_NODE_DIR` when the
+Node.js SDK is checked out elsewhere.
+
 See [`aep-specs`](https://github.com/aep-foundation/aep-specs) for the normative drafts, schemas,
 registries, examples, and test vectors.
 

pyproject.toml

@@ -47,6 +47,7 @@ dev = [
   "pytest-cov==7.1.0",
   "ruff==0.16.5",
   "twine==7.0.0",
+  "uvicorn==0.52.4",
 ]
 
 [tool.hatch.build.targets.sdist]