Testing and troubleshooting
Run checks for the subsystem you changed. A syntax check, import, unit test, benchmark, live provider call, native build, and proof check establish different things.
Research routing
From the repository root, with the environment from Getting started:
cd research/sparse-routing
python -m pytest tests/ -q
cd ../..
python scripts/benchmark_sparse_routing.py --trials 10 --output docs/benchmarks/sparse-routing-local.json
The runner records versions, source commit, warmups, trials, timings, and traced allocations. The historical artifact lacks some machine metadata; do not interpret a different machine's timings as a code speedup.
Documentation examples
The Python examples in Routing, Tools, Continuity, Security, and Machine runtime are standalone files run from the repository root. Tool registration additionally needs jsonschema. Check the validation record for actual executions.
Other check surfaces
| Surface | Command or location | Scope |
|---|---|---|
| Engine VM stress script | python tests/stress_test_no_drift.py |
Deterministic operations; read assertions first |
| Trace endpoint examples | test_routing_trace_endpoints.py | Requires inspection of server assumptions |
| Live routing demonstration | live_routing_test.py | Can use a mock fallback |
| Bash router | bash src/routing/sparse-latency-routing/tests/run_tests.sh |
Separate reference implementation |
| Cobalt | cabal build, cabal test inside cobalt/ |
Haskell package and its declared suites |
| Desktop | npm run verify inside ide/desktop/ |
TypeScript/build and Jest, after npm ci |
| Native IDE | IDE guide | Windows CMake project |
| Formal sources | research/formal/ | Requires individual proof-project dependencies |
These are check entry points, not a claim that all currently pass.
Troubleshooting
| Symptom | Check |
|---|---|
No module named sparse_routing |
Run research tests from research/sparse-routing; use the root wrapper for repeated benchmarks |
Missing numpy, scipy, pytest, or hypothesis |
Install the research requirements with the selected environment's python -m pip |
Missing aiohttp |
Provider/bridge modules use it; it is absent from the root requirements list |
| “object dict can't be used in await” / awaitable error | Expert callbacks must be async; see Routing |
Unexpected context argument or missing continuity task method |
Known engine integration mismatch; see deployment readiness |
| Bedrock credential/model error | Confirm the backend's configured region/model and your account access; no live call is part of the offline benchmark |
| Ollama connection or model error | Confirm the service URL and a locally installed model; inspect direct provider health/list methods |
Bridge ignores --port |
Its module entrypoint does not parse CLI flags |
| Native CMake failure on another OS | The IDE's CMake project explicitly requires Windows |
| Desktop Vite input not found | Check that the declared desktop/index.html renderer exists in your checkout |
Record failures without replacing them with simulated success output. Keep test data and benchmark artifacts separate from credentials and trained model weights.