Customer Program SDK v1

Use this SDK to create an executable adapter from the supported JSON instructions. You supply initialization, objective and violation calculations, operators that change the candidate state, and a final validator. The native Rust worker executes these instructions and provides the operations to the unchanged Refined core. The program controls its own candidate changes instead of using the general mathematical model adapter's neighborhood.

The contract and examples are public authoring material. The Refined search implementation and the bridge to it remain private. No core source, search loop, internal configuration, signing key or native implementation dependency is part of this SDK.

Supported programs

Supported states are binary vectors, bounded integer vectors and zero-based permutations. Program SDK v1 uses checked integer arithmetic, bounded loops and an explicit instruction set. It does not load arbitrary Rust, JavaScript, Wasm, DLLs, Python, shell commands or external dependencies. Compiled Wasm adapters use the separate Rust SDK v1 workflow and package format. Installed specialized native adapters retain their own implementations.

You can import a new operator program without rebuilding the core or worker. This profile supports the states and instructions described here. Advanced native hooks, GPU services and real-valued state are outside the Program SDK v1 contract.

The current localhost host provides private browser sessions, owner-scoped program storage and persistent calculation history. Browser-local definitions and projects are separate from server-stored calculations and admission artifacts. The current workflow does not provide registered customer accounts or cross-device synchronization.

Import and reuse

• Choose Import adapter or task in Refined Math and select balanced-exchange.definition.json or assignment.definition.json. The named definition is saved in My adapters, and its program is checked by the private worker.
• The server compiles the closed instruction representation, validates input and stores an integrity-checked private artifact. The browser receives its digest and compatibility metadata, not the artifact or core implementation.
• Choose Validate input, then Calculate in the workspace. Inspect the returned values, feasibility, the author's fresh validation result, actual core statistics and per-operator counters.
• For assignment, import assignment-small.instance.json. Confirm the data preview. The program and definition revision stay the same while the matrix size/data change.
• Export the result to retain its complete input, definition/data lineage and admission digest.

The source-only *.program.json files are reference source for authoring. The importable adapter document is *.definition.json, which includes that program, its input contract and reference data. A new author can also start from the installed customer-program profile, replace defaultTask.payload.input.program and .data, edit the explanatory metadata, then import the profile and export the resulting definition. The app computes definition identities; do not invent their checksums.

Separate datasets use refined.math.data with payload.input containing only the named data arrays. They do not repeat or replace the program. Keep the exact exported definition reference. Omit the optional data document ID/digest when authoring new values. Changes to the program require a new adapter revision and a separate admission digest.

Program envelope

The program has format: refined.math.program, schemaVersion: 1, a name, parameters, state, optional inputChecks, initialize, evaluation, validation, operators, goal, and optional scalar outputs. See program.schema.json and the complete example files.

Each parameter declares name, optional minLength (default 1), and optional maxLength (default 4096). Data is an object mapping exactly those names to integer arrays. A scalar is a one-element array. Input integers may be JSON integers or exact integer strings, within +/-1e9.

State examples:

{"kind":"binary","size":["len","weights"]}

{"kind":"integer","size":8,"lower":0,"upper":7}

{"kind":"permutation","size":["data","n",0]}

Binary bounds are 0..1. Permutations contain every integer in 0..size-1 once. Their bounds are implicit. Integer states require lower/upper expressions, evaluated from the input. The host checks representation invariants after initialization and state changes.

Expressions

An expression is an integer constant, a local variable name, or an opcode array. Constants are within +/-1e9; intermediate arithmetic uses checked signed 128-bit integers. Division truncates toward zero. Overflow and division by zero fail explicitly.

All state/data indices are zero-based in this SDK, unlike the one-based ModelSpec expression language. size is a read-only local containing the candidate length. Local names are ASCII identifiers of at most 32 characters. size, state, __proto__, prototype and constructor cannot be declared as user names.

and and or short-circuit. Randomness is available only in initialization and operator bodies; evaluation, validation, input predicates and scalar outputs must be deterministic. The PRNG implementation is an internal runtime detail, not part of the author contract.

Statements

{"let":"total","value":0}

Declares or updates a local. At most 64 author locals may be active. Locals are fresh for every hook invocation; evaluation cannot read operator-local scratch state.

{"set":"i","value":["-",1,["state","i"]]}

Writes a candidate slot. set, swap and reverse are allowed only in initialization/operators.

{"swap":["i","j"]}

{"reverse":["i","j"]}

reverse reverses the inclusive interval between the two indices, regardless of their order.

{"if":["<","candidate","best"],"then":[{"let":"best","value":"candidate"}],"else":[]}

{"for":"i","from":0,"to":"size","do":[{"let":"total","value":["+","total",["state","i"]]}]}

Loop bounds are evaluated on entry, with an inclusive start and exclusive end. A reversed/empty range performs zero iterations. The loop index's prior binding is restored when the loop finishes. Other locals updated by the body remain available to the enclosing hook. There is no recursion, while loop, dynamic function invocation or host import.

Hooks and validity

• inputChecks: predicates over the supplied data and computed size. Each must be true before initialization.
• initialize: statements that construct a structurally valid candidate. Initialization is customer code, not a supplied answer. It may use deterministic randomness.
• evaluation.steps: read-only statements for scratch calculations; objective and violations are expressions evaluated afterward. Violation scores must be nonnegative.
• goal: minimize, maximize or find. Feasibility has priority over objective quality; find uses the violation score for search ordering.
• operators: one to sixteen named statement bodies. These bodies are the only source of proposed changes, including local improvement and perturbation. The host does not secretly replace them with generic mathematical moves.
• validation.steps and validation.valid: a fresh read-only customer check on the final candidate. A zero-violation candidate vetoed by this check is rejected as a validation failure.
• outputs: up to sixteen named scalar expressions evaluated in the fresh evaluation context, allowing readable domain totals alongside the generic solution vector.

The host validates structural bounds/permutation invariants, recomputes the score in a fresh machine, and invokes the author's validator separately. That is not an independent proof that the authored mathematical specification matches the real-world problem. Supply independently checkable small cases. These programs report best_found or feasible, not a global-optimality certificate.

Bounds and diagnostics

Current v1 limits: 1..512 state values, 32 parameter groups, 8192 total parameter values, 4096 values per parameter, 4096 compiled syntax nodes, nesting depth 32, 256 statements per block, 1024 iterations per loop, 64 author locals, 200000 instruction units per hook and 50000000 program units per run. Public import/request documents remain bounded to 128 KiB; whole imported documents also have a bounded nesting depth. Final validation has a separate bounded allowance.

These are application limits for Program SDK v1. Time and candidate limits also apply. Invalid indices, arithmetic errors, unsupported opcodes and excessive callback work produce structured errors. Proposals that violate the state representation are rejected and counted. adapterStats reports actual per-operator calls, program work and fresh-validation work; coreStats contains the Refined statistics record.

Why the core remains private

The program can access only its input arrays, candidate slots, locals and admitted random source. The language has no instruction for reading files, opening a network connection, spawning a process, loading a module or evaluating arbitrary text. The native worker interprets compiled typed instructions and calls Refined internally. No callbacks cross to a customer process or browser for each neighborhood step.

The host stores admission artifacts under its private runtime directory, keyed by a SHA-256 program digest and isolated by worker/core version. It checks artifact integrity on reload, reuses them across datasets and rejects uploaded compiled-artifact objects. Public responses contain admission metadata only. The executable/source core tree is outside the public asset root.

Conformance cases

The included balanced-partition program must select three of [9,8,7,6,5,3], producing equal weight totals 19 and objective 0. Its best_exchange body computes a domain-aware improvement. Replacing all operator bodies with empty arrays leaves the fixed initial solution at objective 10. This distinguishes actual customer-controlled moves from metadata selecting a hidden canned neighborhood.

The assignment program has a permutation representation and an operator that evaluates partner-swap deltas from the supplied cost matrix. The independent checker enumerates permutations and compares the returned costs with reference values 21 and 10 for the six- and four-facility data. The program source remains identical for both instances. Operator inspection and runtime tests must confirm these cases before the profile is declared validated.

Status

The recorded local verification on 2026-10-23 used the release worker: the supplied exchange program returned 0, the empty-operator variant remained at 10, and the two assignment datasets returned 21 and 10. It covered browser file import, previewing and applying separate data, actual calculation, result export and persistence after reload. The exported four-facility result retains its input, definition and data lineage, admission digest and actual operator counters. See docs/CUSTOMER_PROGRAM_VALIDATION.md in the source project for that verification record. These observations describe the recorded examples and budgets.