Docs: Route solver in-depth guide + optimization theory (#310) #784

2026-06-05T09:58:31Z

PlasticDigits commented

2026-06-05 09:58:31 +00:00

(Migrated from gitlab.com)

Summary

Closes documentation gap for GitLab #310.

Adds docs/route-solver.md — the authoritative in-depth guide for contributors and integrators covering:

Glossary aligned with API JSON fields (quote_kind, optimality_scope, solver_version, hybrid legs, degraded hybrid)
Pipeline diagram (asset graph → top-K paths → joint hybrid optimization → LCD sim → winner → cache)
GET vs POST API matrix, pool_only escape hatch, amount_in requirements
Explicit non-goals and operational limits (cache TTL, amount bucketing, LCD budget)
Optimization theory mapping each shipped heuristic to code + literature (Yen/Eppstein, constrained routing, coordinate descent, AMM path routing, hybrid microstructure)

Also:

Cross-links from ADR 0002, indexer-invariants.md, docs/README.md, integrators.md, and skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md
OpenAPI schema doc comments on /route/solve request/response types aligned with glossary
Drift guard: scripts/check_route_solver_docs.py + make check-route-solver-docs

ADR 0002 remains the decision record; this doc expands it without changing decisions.

Acceptance checklist

Criterion	Verification	Result
New doc under `docs/` with glossary, pipeline, API matrix, non-goals	`docs/route-solver.md`	PASS
Optimization section maps each shipped heuristic to code + ≥3 references	§ Optimization theory in `docs/route-solver.md`	PASS
`indexer-invariants.md` and ADR 0002 link to new doc	grep / file review	PASS
OpenAPI `/route/solve` field descriptions align with glossary	`route_solver.rs`, `hybrid_route_opt.rs` doc comments	PASS
No contradiction with `optimality_scope` API string	Full `OPTIMALITY_SCOPE` quoted in doc; drift script	PASS
Doc accuracy (constants)	`python3 scripts/check_route_solver_docs.py`	PASS
Link integrity	Internal links spot-checked to existing paths	PASS
Term consistency	Glossary terms match JSON field names in doc + OpenAPI	PASS
Listed in docs index	`docs/README.md`	PASS
Drift guard (optional)	`make check-route-solver-docs`	PASS

Verification for third parties

python3 scripts/check_route_solver_docs.py
cd indexer && cargo test --lib route_solver --

Read docs/route-solver.md and interpret a sample:

curl -sS "http://127.0.0.1:3001/api/v1/route/solve?token_in=...&token_out=...&amount_in=1000000" | jq .

Issue left open pending maintainer technical review.

Note

Low Risk
Documentation, Makefile target, and OpenAPI comments only; no changes to solver logic or HTTP behavior.

Overview
Adds docs/route-solver.md as the expanded integrator/contributor guide for global_v1 route solving (glossary, pipeline, GET vs POST matrix, shipped constants, optimality_scope, non-goals, optimization theory, abuse notes) without changing ADR 0002 decisions.

Wiring: cross-links from docs/README.md, ADR 0002, indexer-invariants.md, integrators.md, and skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md. make check-route-solver-docs runs scripts/check_route_solver_docs.py to keep the doc aligned with Rust constants (OPTIMALITY_SCOPE, hop caps, grid size, cache TTL, LCD budget).

OpenAPI: richer utoipa doc comments on SolveRouteParams, POST body, RouteQuoteKind, RouteSolveResponse, and HybridHopJson in route_solver.rs / hybrid_route_opt.rs — documentation only, no routing behavior change.

^{Reviewed by Cursor Bugbot for commit b8a51aadc3. Bugbot is set up for automated code reviews on this repo. Configure here.}

## Summary Closes documentation gap for GitLab [#310](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/work_items/310). Adds **`docs/route-solver.md`** — the authoritative in-depth guide for contributors and integrators covering: - Glossary aligned with API JSON fields (`quote_kind`, `optimality_scope`, `solver_version`, hybrid legs, degraded hybrid) - Pipeline diagram (asset graph → top-K paths → joint hybrid optimization → LCD sim → winner → cache) - GET vs POST API matrix, `pool_only` escape hatch, `amount_in` requirements - Explicit non-goals and operational limits (cache TTL, amount bucketing, LCD budget) - Optimization theory mapping each **shipped** heuristic to code + literature (Yen/Eppstein, constrained routing, coordinate descent, AMM path routing, hybrid microstructure) Also: - Cross-links from ADR 0002, `indexer-invariants.md`, `docs/README.md`, `integrators.md`, and `skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md` - OpenAPI schema doc comments on `/route/solve` request/response types aligned with glossary - Drift guard: `scripts/check_route_solver_docs.py` + `make check-route-solver-docs` ADR 0002 remains the decision record; this doc expands it without changing decisions. ## Acceptance checklist | Criterion | Verification | Result | |-----------|--------------|--------| | New doc under `docs/` with glossary, pipeline, API matrix, non-goals | `docs/route-solver.md` | PASS | | Optimization section maps each shipped heuristic to code + ≥3 references | § Optimization theory in `docs/route-solver.md` | PASS | | `indexer-invariants.md` and ADR 0002 link to new doc | grep / file review | PASS | | OpenAPI `/route/solve` field descriptions align with glossary | `route_solver.rs`, `hybrid_route_opt.rs` doc comments | PASS | | No contradiction with `optimality_scope` API string | Full `OPTIMALITY_SCOPE` quoted in doc; drift script | PASS | | Doc accuracy (constants) | `python3 scripts/check_route_solver_docs.py` | PASS | | Link integrity | Internal links spot-checked to existing paths | PASS | | Term consistency | Glossary terms match JSON field names in doc + OpenAPI | PASS | | Listed in docs index | `docs/README.md` | PASS | | Drift guard (optional) | `make check-route-solver-docs` | PASS | ## Verification for third parties ```bash python3 scripts/check_route_solver_docs.py cd indexer && cargo test --lib route_solver -- ``` Read `docs/route-solver.md` and interpret a sample: ```bash curl -sS "http://127.0.0.1:3001/api/v1/route/solve?token_in=...&token_out=...&amount_in=1000000" | jq . ``` Issue left **open** pending maintainer technical review.  --- > [!NOTE] > **Low Risk** > Documentation, Makefile target, and OpenAPI comments only; no changes to solver logic or HTTP behavior. > > **Overview** > Adds **`docs/route-solver.md`** as the expanded integrator/contributor guide for **`global_v1`** route solving (glossary, pipeline, GET vs POST matrix, shipped constants, **`optimality_scope`**, non-goals, optimization theory, abuse notes) without changing ADR 0002 decisions. > > **Wiring:** cross-links from **`docs/README.md`**, ADR 0002, **`indexer-invariants.md`**, **`integrators.md`**, and **`skills/AGENTS_INDEXER_HYBRID_BEST_EXECUTION.md`**. **`make check-route-solver-docs`** runs **`scripts/check_route_solver_docs.py`** to keep the doc aligned with Rust constants (**`OPTIMALITY_SCOPE`**, hop caps, grid size, cache TTL, LCD budget). > > **OpenAPI:** richer **`utoipa`** doc comments on **`SolveRouteParams`**, POST body, **`RouteQuoteKind`**, **`RouteSolveResponse`**, and **`HybridHopJson`** in **`route_solver.rs`** / **`hybrid_route_opt.rs`** — documentation only, no routing behavior change. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit b8a51aadc3a98d1998c9781427041e7bc2646267. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>

PlasticDigits commented

2026-06-05 09:58:38 +00:00

(Migrated from gitlab.com)

mentioned in issue #310

ghost1 commented

2026-06-05 09:58:38 +00:00

(Migrated from gitlab.com)

changed the description

ghost1 commented

2026-06-05 09:58:45 +00:00

(Migrated from gitlab.com)

changed the description

PlasticDigits commented

2026-06-05 09:59:48 +00:00

(Migrated from gitlab.com)

Security review

Commit reviewed: b8a51aadc3a98d1998c9781427041e7bc2646267
Scope: 10 files — new docs/route-solver.md, cross-link/doc updates, OpenAPI utoipa doc comments on route-solve schemas (route_solver.rs, hybrid_route_opt.rs), drift guard scripts/check_route_solver_docs.py, make check-route-solver-docs.

Outcome: FINDINGS: 0 medium+

Security review: no medium+ findings on this diff.

Method

Reviewed added/modified code only; traced attacker-controlled input where applicable.
No prior security-review threads on this MR to reconcile.

Summary

This MR is documentation and schema-comment only — no runtime routing, HTTP handler, auth, or validation logic changes.

Area	Assessment
Injection / deserialization	No new sinks; Rust changes are doc comments only; drift script reads fixed repo paths with hardcoded constant names (no CLI/user input).
Authn / authz	Unchanged.
Secret leakage	No credentials or keys in diff.
SSRF / path traversal	Drift script uses `Path(__file__).resolve().parents[1]` + fixed relative paths; not exposed at runtime.
DoS / abuse	Doc restates existing caps (hop/path/LCD budget, rate limits, cache bucketing) already enforced in indexer code — informational only.

Inline threads: none (no findings).

Automated security review (Cursor Cloud Agent)

## Security review **Commit reviewed:** `b8a51aadc3a98d1998c9781427041e7bc2646267` **Scope:** 10 files — new `docs/route-solver.md`, cross-link/doc updates, OpenAPI `utoipa` doc comments on route-solve schemas (`route_solver.rs`, `hybrid_route_opt.rs`), drift guard `scripts/check_route_solver_docs.py`, `make check-route-solver-docs`. **Outcome:** `FINDINGS: 0` medium+ Security review: **no medium+ findings** on this diff. ### Method - Reviewed added/modified code only; traced attacker-controlled input where applicable. - No prior security-review threads on this MR to reconcile. ### Summary This MR is documentation and schema-comment only — **no runtime routing, HTTP handler, auth, or validation logic changes**. | Area | Assessment | |------|------------| | Injection / deserialization | No new sinks; Rust changes are doc comments only; drift script reads fixed repo paths with hardcoded constant names (no CLI/user input). | | Authn / authz | Unchanged. | | Secret leakage | No credentials or keys in diff. | | SSRF / path traversal | Drift script uses `Path(__file__).resolve().parents[1]` + fixed relative paths; not exposed at runtime. | | DoS / abuse | Doc restates existing caps (hop/path/LCD budget, rate limits, cache bucketing) already enforced in indexer code — informational only. | **Inline threads:** none (no findings). --- *Automated security review (Cursor Cloud Agent)*