Shared job API
The job envelope optimization.job/0.1, the result contract
optimization.result/0.2, the worker SDK and the optimization-run runner
live in optimization-jobs,
shared with LP-IP-craft and
SQP-craft. This repository depends on
its crates optimization-job-api and optimization-runner at the revision
pinned in the root Cargo.toml, and contributes the fcmaes workers.
The shared guide
| Topic | Section of the guide |
|---|---|
| Envelope fields, inputs and validation | Envelope |
cpu_slots, outer_workers and inner_threads | Eight CPU slots |
| Commands, lifecycle states and cancellation | Run, inspect and stop |
| Error codes | Errors |
| Claims, evidence and refutations | Termination, claim and evidence |
| Journals, accounting and recovery | Accounting and recovery |
| Logs and snapshots a worker declares, read while a job runs and in pages | Artifacts |
| Agents and MCP | Agents and MCP |
| JSON Schemas of jobs and results | docs/job-api/schemas |
| Implementation history and gates | Plan |
fcmaes in this repository
| Part | Where |
|---|---|
fcmaes-job-worker: fcmaes.retry/1, fcmaes.mode/1, fcmaes.map-elites/1, fcmaes.evaluate/1 | Tutorial |
Experimental fcmaes.surrogate/1, small-budget exact GP and simulation context | API guide, tutorial |
| Your own models in an application worker | Application models |
fcmaes-native-worker and fcmaes-run, the legacy fcmaes.job/0.1 jobs | Experiment runner |
| Acceptance record of the fcmaes worker | Validation |
cargo build --release --locked -p optimization-runner -p fcmaes-job-worker
builds the runner, the MCP server and the worker here; Cargo fetches the
shared crates.
Agents: the MCP server
The same build makes optimization-mcp, an MCP server over one node
(Agents and MCP). On a node with the
fcmaes worker registered, connect an MCP client, for example Claude Code:
claude mcp add fcmaes-jobs -- "$PWD/target/release/optimization-mcp" --root /abs/node
Its tools describe the node and the worker, validate and submit jobs, wait for them, read their claims and evidence, and cancel or repair them; with the MCP Tasks extension, a submitted job is a task that completes with its result. The tutorial connects it to the tutorial’s node.
Running the shared tests here
The shared harness runs from Cargo’s checkout of optimization-jobs at the pinned revision, against this repository’s binaries:
cargo build --release --locked -p optimization-runner -p fcmaes-job-worker
SHARED=$(python3 scripts/job-api/shared_root.py)
export JOB_API_TARGET="$PWD/target/release" JOB_API_TUTORIALS="$PWD/tutorials/job-api"
python3 "$SHARED/scripts/job-api/test_integration.py"
python3 "$SHARED/scripts/job-api/test_review.py"
python3 "$SHARED/scripts/job-api/test_mcp.py"
A change to the shared crates lands in optimization-jobs first. Then change
rev in the root Cargo.toml and run
cargo update -p optimization-job-api -p optimization-runner; the GTOC1
route-search tutorial pins the same rev in its own Cargo.toml (then run
cargo update -p optimization-job-api there), and the dependency example in
application models names it too. To develop both
at once, add a [patch."https://github.com/dietmarwo/optimization-jobs"]
section with path dependencies to a local checkout, as the
optimization-jobs README
shows.