# Refined Math Rust adapter SDK v1

Use this project to write and build your own executable adapter. The SDK contains the public data contracts, serialization helpers and example algorithms. The Refined search implementation is separate. After you import the resulting `*.adapter.json` package, the application executes its Wasm module in the calculation server's native worker and uses the supplied operators with Refined. With the local server, execution takes place on that computer.

## Build, change and import

Install Rust and Node.js, then extract the project archive. Run the following commands from the extracted directory containing `Cargo.toml` and `package.mjs`. Rust 1.93.0 is the reference toolchain:

```text
rustup toolchain install 1.93.0 --profile minimal
rustup target add wasm32-unknown-unknown --toolchain 1.93.0
cargo +1.93.0 build --release --target wasm32-unknown-unknown -p refined_custom_qap
cargo +1.93.0 run --locked --release -p refined_adapter_checker -- target/wasm32-unknown-unknown/release/refined_custom_qap.wasm examples/qap/fixtures.json
node package.mjs qap target/wasm32-unknown-unknown/release/refined_custom_qap.wasm qap.adapter.json
```

In Refined Math, choose **Import adapter or task**, select `qap.adapter.json`, and wait for the executable checks to finish. The adapter appears in **My adapters**. Review or change its matrix data, choose **Validate input**, then **Calculate**. To change the algorithm, edit `examples/qap/src/lib.rs`, rebuild the module and package it under a new filename. Importing changed package content creates a new definition revision for the same author adapter ID. Earlier calculations keep their original package and module identities.

The second project uses real-valued states and incrementally updated residuals:

```text
cargo +1.93.0 build --release --target wasm32-unknown-unknown -p refined_custom_weighted_fit
cargo +1.93.0 run --locked --release -p refined_adapter_checker -- target/wasm32-unknown-unknown/release/refined_custom_weighted_fit.wasm examples/weighted-fit/fixtures.json
node package.mjs weighted-fit target/wasm32-unknown-unknown/release/refined_custom_weighted_fit.wasm weighted-fit.adapter.json
```

`package.mjs` combines an already compiled binary, its source and its manifest into an importable document. Before writing, it uses the included `package-contract.cjs`, a copy of the application's public package validator, to check the package format, source paths, cumulative source size and bounded data. It does not compile or execute the module; server executable admission remains a separate step. Existing output files are not overwritten, so choose a new output filename for each changed package. Import the complete package rather than an individual `.rs` or `.wasm` file. Keep the executable package: exporting a definition or task that refers to its digest does not copy the executable to another installation.

## Check your adapter before import

The source project includes a standalone native author checker under `checker/`, fixtures for both examples and the fixture contract in `checker/FIXTURES.md`. Build/run it from the extracted SDK workspace with the commands above. It needs no Refined Math server, account, private worker or Refined dependency. Cargo builds the public native checker; the checker then calls the supplied Wasm module with the trusted fixtures. It does not compile source or generate code from fixture text.

The first argument may also be the complete executable package:

```text
cargo +1.93.0 run --locked --release -p refined_adapter_checker -- qap.adapter.json examples/qap/fixtures.json
```

Fixtures contain the expected executable `description`, matching the example manifest's `descriptionContract`, and explicit reference cases for the calls being checked. The description is read from the supplied module and compared with that contract. Keep fixtures under your control: write independently checked states, moves, scores and validation expectations for your problem, rather than treating the module's own output as its reference. Follow `checker/FIXTURES.md` when adapting the examples. Exact `i128` scores use decimal strings; finite `f64` scores use the fixture's declared tolerance.

Reference tolerance never permits the module's own score to drift: repeated evaluation, fresh-instance evaluation and author validation must agree exactly after numeric parsing, with signed zero normalized.

The checker reports actual callback checks as JSON on standard output and exits with a nonzero status when a check fails. Its report states `coreUsed:false`: this is a bounded interface/behavior check, not a Refined solve or an optimality proof. Passing trusted small cases does not establish that an arbitrary model represents the intended problem or that every input is correct. Import admission and an actual Refined Math calculation remain separate steps.

Checker execution uses `wasmi`, rejects module imports and start functions, and bounds each instance to 32 MiB of linear memory. Calls allow at most 50 million fuel units and a suite allows at most 500 million. These are instruction/memory bounds, not a wall-time guarantee. The checker is a local author tool for trusted fixture files; it is not an application service for arbitrary uploaded workloads.

Both `source.zip` and the source attached to a new single-example executable package include the SDK, checker, fixture documentation and the matching example fixtures. The single-example workspace keeps `sdk`, `checker` and that example as members, so it can be rebuilt and checked independently. Dependencies must be available to Cargo; `--locked` preserves the supplied dependency resolution.

## What the adapter controls

Implement the `Adapter` trait in `sdk/src/lib.rs`. Your code supplies initialization, evaluation, validation, proposed moves, application, the entire local-search loop and perturbation. Optional hooks provide guidance, repair, recombination, path relinking and stable features. Rust structs, integer or real state, helper functions and private per-instance caches are supported. Cache contents must not change mathematical semantics: instances can be reused by different core threads and final validation starts fresh.

Scores prioritize nonnegative constraint violations, then up to eight declared lexicographic objectives. `i128` objectives are exact decimal integers; `f64` objectives must be finite decimal values. State, moves and data cross the boundary as bounded JSON. Inner local-search iterations stay inside the module; there is no browser or process callback per iteration.

The QAP example uses exact swap deltas, best-improvement local search and order-preserving recombination. Its `frozen-operators` Cargo feature exists for conformance testing: it disables changes while keeping the same starting state. The fit example keeps residuals inside its local search and updates them after coordinate changes. Both examples are standalone author implementations using this public contract; their package digests identify their own executable versions, not the built-in adapters' source versions.

## Execution boundary and current profile limits

SDK v1 uses a bounded CPU Wasm interpreter. Modules have no host imports or WASI access, so they cannot access the network, filesystem, processes or native libraries through the application. The application accepts compiled packages and does not compile user source. This execution profile is separate from installed native adapters and does not expose GPU services or every private core hook. Core learning can use supplied operator keys and stable features. CPU core parallelism uses at most four isolated module instances. Interpreter execution and serialization have different costs from specialized native adapters, so their performance may differ.

Current ceilings: 512 KiB module, 4 MiB import package, 2 MiB accompanying source, 64 KiB decision state, 128 KiB request/response and 32 MiB memory per instance. A callback may return up to 256 guidance or move hints. Repair, recombination and path-relinking calls may return at most 24 candidate states, also bounded by the requested candidate limit. Execution allows 50 million fuel units per callback and 500 million across search instances. Initialization, allocation, cleanup and calls consume fuel. Fresh final validation has a separate bounded allowance. The outer native resource guard also enforces process memory and wall time. Limits are enforced independently of author-supplied counters.

The online edition additionally bounds each complete guest JSON response to 8,192 counted values/object keys and depth 40, and applies strict Wasmi module-structure and stack limits. The full saved calculation (input, result and lifecycle metadata) is bounded to 50,000 counted values/keys, with shared owner/global retention reservations. A small byte count alone is not sufficient admission evidence. Search instances are released before the independent final validator is created.

Server admission and execution require the configured Linux isolation runtime. If it is unavailable, the service rejects executable adapter operations rather than running them unconfined. Author tools can still be used locally. A runtime/security identity change requires reimport before an old package can execute; the original package remains exportable. The standalone author checker is a conformance tool and does not replace these server protections.

Actual Wasm fuel, host-checked state evaluations and author-reported inner work are separate statistics. A fresh evaluation plus the author's validator checks consistency with the supplied algorithm; it does not independently prove that the author's model represents the intended mathematics. Imported modules cannot award themselves global-optimality certificates.

## Source and identity

The package includes the module SHA-256 and its declared executable interface. Admission checks the binary and compares the module's actual interface to that declaration. The complete package receives a host-computed digest. Source files are author-supplied reference material; source-to-binary equivalence is not attested. The source viewer must not label supplied source as independently proven to match arbitrary uploaded binaries.

Keep reusable code and separate data distinct. Export data from the workspace to reuse the same executable with other inputs. Use **Download executable package** in the source viewer to move the complete adapter to another installation.