\input macros.tex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\beginruby
  WIDTH  = 210
  HEIGHT = 297
  HMARGIN = 50
  VMARGIN = 50
\endruby%
\pdfpagewidth⟦WIDTH⟧mm
\pdfpageheight=⟦HEIGHT⟧mm
\hoffset=⟦(HMARGIN-25.4).round(3)⟧mm
\voffset=⟦(VMARGIN-25.4).round(3)⟧mm
\hsize=⟦( WIDTH-HMARGIN*2).round(3)⟧mm
\vsize=⟦(HEIGHT-VMARGIN*2).round(3)⟧mm
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\currentfamily={Alegreya Sans}%
\currentweight={}%
\currentsize=11%
\syncfonts%
\hangpun%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\pretolerance=1000
\baselineskip=16pt
\parskip=8pt
\parindent=0pt
\raggedbottom
\nopagenumbers
\setbox0=\lastbox
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\def\comment#1{\ltgrey{#1}}%
\newcount\majorcount
\newcount\minorcount
\def\major{\advance\majorcount by 1\minorcount=0\leavevmode\llap{\ltgrey{\the\majorcount}\hem}}%
\def\minor{\advance\minorcount by 1\leavevmode\llap{\ltgrey{\the\majorcount·\the\minorcount}\hem}}%
\def\fw{%
\advance\currentsize by -1
\currentfamily={Operator}%
\currentweight={ Book}%
\syncfonts
}%
\def\sup#1{{%
\currentsize=8
\currentfamily={Operator}%
\currentweight={ Book}%
\syncfonts
\raise0.8ex\hbox{#1}%
}}%
\def\n{\hfil\penalty-10000}%
\long\def\item#1{%
  \par
  \vskip-\parskip
  \leavevmode
  {\leftskip=0.9em\llap{\hbox to 0.9em{▶\hfil}}#1\par}%
}%
\def\inset#1{%
  \par
  \vskip-\parskip
  \leavevmode
  {\leftskip=0.9em #1\par}%
}%
\def\noskip{\vskip-\parskip}%
\def\uni#1{{\caps u+#1}}%
\def\cmd#1{\teal{#1}}%
\def\tok#1{\teal{\fw #1}}%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\centerline{\letterspace{8}\caps UNIVERSAL CHESS INTERFACE}
\centerline{\letterspace{4}\caps 2022 dec 29 • draft}
\vskip2\baselineskip
\major{\bf Introduction}\par
\minor This specification governs the interaction between two processes named
the \purple{client} and the \purple{engine}. \comment{Graphical interfaces,
terminals, and scripts or utilities are examples of clients.}

\minor The engine's stdin, stdout, and stderr must all be open file descriptors.

\minor The sequence of bytes that the client sends to the engine (via the
engine's stdin) must be valid {\caps utf-8}, and the Unicode scalar values that
the client sends must be \uni{000a line feed}, \uni{000d carriage return}, or in
the range \uni{0020} to \uni{007e} inclusive \comment{(in other words, printable
{\caps ascii} characters and space)}. When the scalar value \uni{000d} appears
it must be immediately followed by \uni{000a}.

\minor The sequence of bytes that the engine sends to the client (via the
engine's stdout) must be valid {\caps utf-8}. \comment{Non-{\caps ascii}
characters are permitted so that the engine name, author names, and info
messages can be represented.} When the scalar value \uni{000d} appears it must
be immediately followed by \uni{000a}.

\minor No requirements are placed upon the engine's stderr \comment{(for
example, the engine's stderr may be directed to a null file, to the client's
stdout or stderr, or to a log file)}, and there are no restrictions on the
sequence of bytes that the engine writes to its stderr.

\minor When the client or engine violate the requirements of this
specification, a \purple{violation} is said to have occurred. When a violation
occurs, or when the requirements of this specification are otherwise not met,
this specification imposes no further requirements on the behavior of the client
or engine.

\minor There are conditions that resemble violations but that the client and
engine are expected to handle; these are called \purple{errors}.

\vskip\parskip
\major{\bf Other Definitions}\par
\minor A \purple{message} is a sequence consisting of
\item{zero or more scalar values that are not \uni{000a}}\noskip
followed by
\item{the scalar value \uni{000a}.}

\minor The scalar value \uni{000a} (or, if the scalar value \uni{000a} is
preceded by the scalar value \uni{000d}, the sequence \uni{000d} \uni{000a})
is the message \purple{termination}. \comment{Note that both client and engine
are required to handle both Unix- and Windows-style line endings.}

\minor The sequence of scalar values in a message before the message
termi\-nation is the message \purple{body}.

\minor A \purple{token} is a maximally contiguous sequence of scalar values that
are not \uni{0020 space} in the message body. \comment{Tokens are separated by
whitespace. White\-space is any contiguous sequence of \uni{0020} in the message
body.}

\minor An \purple{algebraic} token is a token of the form
[\tok{a}−\tok{h}][\tok{1}–\tok{8}][\tok{a}−\tok{h}][\tok{1}–\tok{8}][\tok{qrbn}]?.

\minor A message whose body does not contain any tokens is \purple{empty}.

\minor The first token of a message from the client to the engine is a
\purple{command}. For any token \tok{\it cmd}, a message whose command is
\tok{\it cmd} is a \purple{{\it cmd} message}.

\minor The first token of a message from the engine to the client is a
\purple{remark}. For any token \tok{\it rmk}, a message whose remark is
\tok{\it rmk} is an \purple{{\it rmk} message}.

\vskip\parskip
\major{\bf States and Transitions}

\minor At every point in time, given the history of messages between the client
and engine, there is a corresponding \purple{state}. When the client or engine
sends a message (that is, writes a message to the engine's stdin or stdout), the
state may change; this is a \purple{transition}. \comment{Note that transitions
occur when messages are written, not read.}

\minor Empty messages may always be sent and must be ignored by the client and
engine. Empty messages never cause a transition.

\minor This specification begins to govern the interaction between the client
and the engine when the client sends a well-formed \cmd{uci} message.
%\comment{An empty history (when no messages have yet been sent) does not
%correspond to any state.}

\minor In the initial state, the client may not send a non\-empty message to the
engine. The engine may send any message. If the engine sends a message that
is not a well-formed \cmd{id}, \cmd{option}, \cmd{protocol}, \cmd{info}, or
\cmd{uciok} message, the message must be ignored by the client. When the engine
sends a well-formed \cmd{uciok} message, the state changes to \purple{idle}.

\minor In the idle state, the client may send any message. If the client sends
a non\-empty message that is not a well-formed \cmd{setoption},
\cmd{ucinewgame}, \cmd{isready}, \cmd{position}, \cmd{go}, \cmd{stop},
\cmd{debug}, or \cmd{quit} message, an error has occurred, and the engine may
respond by sending an \cmd{info} message indicating that a client error has
occurred; besides sending an \cmd{info} message, the engine must ignore the
client message \comment{(in other words, the engine must behave as if no message
was sent)}. When the client sends a well-formed \cmd{isready} message, the state
changes to \purple{sync}. When the client sends a well-formed \cmd{go} message,
the state changes to \purple{active}. \comment{Note that the engine cannot
assume that a go message will be preceded by an isready message.}

\minor In the idle state, the engine may send any message. If the engine sends
a message that is not a well-formed \cmd{info} message, the message must be
ignored by the client. \comment{In the idle state, the engine should be asleep
or minimally utilize processing resources unless, for example, it is
reconfiguring itself in response to a setoption message.}

\minor In the sync state, the client may not send a non\-empty message to the
engine. The engine may send any message. If the engine sends a message that is
not a well-formed \cmd{info} or \cmd{readyok} message, the message must be
ignored by the client. When the engine sends a well-formed \cmd{readyok}
message, the state changes to idle.

\minor In the active state, the client may send any message. If the client sends
a non\-empty message that is not a well-formed \cmd{isready} or \cmd{stop}
message, an error has occurred, and the engine may respond by sending an
\cmd{info} message indicating that a client error has occurred; besides
sending an \cmd{info} message, the engine must ignore the client message.
When the client sends a well-formed \cmd{isready} message, the state changes to
\purple{ping}. When the client sends a well-formed \cmd{stop} message, the state
changes to \purple{halt}.

\minor In the active state, the engine may send any message. If the engine sends
a message that is not a well-formed \cmd{info} or \cmd{bestmove} message, the
message must be ignored by the client. When the engine sends a well-formed
\cmd{bestmove} message, the state changes to idle.

\minor In the ping state, the client may not send a non\-empty message to the
engine. The engine may send any message. If the engine sends a message that is
not a well-formed \cmd{info}, \cmd{readyok}, or \cmd{bestmove} message, the
message must be ignored by the client. When the engine sends a well-formed
\cmd{readyok} message, the state changes to active. When the engine sends a
well-formed \cmd{bestmove} message, the state changes to idle.

\minor In the halt state, the client may not send a non\-empty message to the
engine. If the engine sends a message that is not a well-formed \cmd{info} or
\cmd{bestmove} message, the message must be ignored by the client. When the
engine sends a well-formed \cmd{bestmove} message, the state changes to idle.

\minor This specification stops governing the interaction between the client and
the engine when the client sends a well-formed \cmd{quit} message in the idle
state. Engines are recommended to shut down and terminate themselves. Clients
are recommended to provide a grace period not less than 5 seconds before killing
the engine.

\comment{There is an interesting invariant that the state and transition rules
should satisfy due to the nature of stdin and stdout.}

\comment{The time that a message is read and processed necessarily occurs some
duration after the time that the message is written ({\it sending a message} is
merely {\it enqueuing,} not invoking a subroutine of the recipient's) and it
impossible to atomically perform both a read and a write. More particularly, it
is impossible for a process to guarantee that a write to stream {\caps f} is not
preceded by a write to stream {\caps g} by some other process. Even if the
process attempts to read {\caps g}, finds it empty, and immediately writes to
{\caps f}, it is possible for an intervening write to {\caps g} to occur before
the write to {\caps f} occurs.}

\comment{As a result, if the transition from state {\caps a} to state {\caps b}
is caused by the client sending a message, it is impossible to guarantee that a
message sent by the engine in state {\caps a} can actually be read by the client
in state {\caps a} (and not in state {\caps b}). Therefore, any message that the
engine is allowed to send in state {\caps a} should be allowed in state
{\caps b}. The same idea holds for transitions caused by the engine sending a
message, so we can state the invariant generally as follows:}

\comment{\it For distinct processes 1 and 2, for all pairs of states {\capsit a}
and {\capsit b}, if a transition from {\capsit a} to {\capsit b} can be caused
by process 1 sending a message, every messages that process 2 is allowed to send
in state {\capsit a} must also be allowed in state {\capsit b}.}

\vskip\parskip
\major{\bf Timeouts}

\minor The time between the client sending a well-formed \cmd{uci}
message and the client reading a well-formed \cmd{uciok} message may not exceed
an implementation-defined duration. \comment{For example, this may be caused by
transmission latency, by the client or engine failing to read data or flush
their writes, or by the engine performing excessive operations at startup.}
This duration (the \purple{initialization timeout}) must not be less than 5
seconds.

\minor The time between the client sending a well-formed \cmd{isready} message
in the idle state and the client reading a well-formed \cmd{readyok} message may
not exceed an implementation-defined duration. This duration (the
\purple{reconfiguration timeout}) must not be less than 5 seconds.

\minor The time between the client sending a well-formed \cmd{isready} message
in the active state and the client reading a well-formed \cmd{readyok} message
may not exceed an implementation-defined duration. This duration (the
\purple{ping timeout}) must not be less than 1 second.

\minor The time between the client sending a well-formed \cmd{stop} message
in the active state and the client reading a well-formed \cmd{bestmove} message
may not exceed an implementation-defined duration. This duration (the
\purple{halt timeout}) must not be less than 1 second.

\vskip\parskip
\major{\bf Engine Remarks}

\minor An \cmd{id} message is well-formed when its body is a sequence of three
or more tokens. It is recommended that engines notify the client of
\item{the engine's name using \tok{id name ...}\dt,}
\item{any authors' names using \tok{id author ...}\dt,}\noskip
where \tok{...}\ is any non\-empty sequence of tokens.

\comment{Recall that, in all states, a message sent by the engine that is not
well-formed must be ignored. All id messages that are long enough are considered
to be well-formed, then, so that implementation-defined id messages besides
engine and author names can be added.}

\minor An \cmd{option} message is well-formed when its body is of the form
\inset{\tok{option name ...¹ type ...² ...³}}\noskip
where
\item{\tok{...¹} is any non\-empty sequence of tokens that does not contain the
token \tok{type} or the token \tok{value} (the \purple{option name}),}
\item{\tok{...²} is \tok{check}, \tok{spin}, \tok{combo}, \tok{button}, or
\tok{string} (the \purple{option type}),}
\item{\tok{...³} is a well-formed \purple{option schema} given the option type.}

A well-formed option schema is a sequence of tokens of the form
\item{\tok{default true} or \tok{default false} when the option type is
\tok{check},}
\item{\tok{default ...\sup{a} min ...\sup{b} max ...\sup{c}} when the option
type is \tok{spin}, where \tok{...\sup{a}}, \tok{...\sup{b}}, and
\tok{...\sup{c}} are decimal integers in the range 0 to 2⁶³\ot−\pt1 inclusive,}
\item{\tok{default ...\sup{a} }(\pt\tok{var ...\sup{b}}\pt)+ when the option
type is \tok{combo}, where \tok{...\sup{a}} and \tok{...\sup{b}} are non\-empty
sequences of tokens that do not contain the token \tok{var},}
\item{the empty sequence when the option type is \tok{button},}
\item{\tok{default ...\sup{a}} when the option type is \tok{string}, where
\tok{...\sup{a}} is any non\-empty sequence of tokens. The one-token sequence
\tok{<empty>} must be interpreted by the client as if it were the empty
sequence.}

It is recommended that engines use the option name \tok{Hash} (with option type
\tok{spin}) for cache size in megabytes and the option name \tok{Threads} (with
option type \tok{spin}) for number of worker threads.

\minor A \cmd{protocol} message is well-formed when its body is of the form
\inset{\tok{protocol ...}}\noskip
where \tok{...}\ is a single token that is the \purple{protocol identifier} of a
version of this specification that the engine will conform to. The protocol
identifier of this version of the specification (in other words, the version
described in this particular document) is \tok{2}.

Clients should interpret the protocol identifier \tok{1} as a indication that
the engine will behave informally (in other words, as a warning that the engine
may cause a violation).

\minor The only well-formed \cmd{uciok} message body is the single-token
sequence \tok{uciok}.

\minor The only well-formed \cmd{ready} message body is the single-token
sequence \tok{readyok}.

\minor An \cmd{info} message is well-formed when its body is of the form
\inset{\tok{info} (\pt\tok{string}\pt|\pt\tok{error}\pt) \tok{...}}\noskip
where \tok{...}\ is any non\-empty sequence of tokens, or is of the form
\inset{\tok{info ...}}\noskip
where \tok{...}\ is a non\-empty sequence (\purple{search information}) of
well-formed \purple{fields}.

\comment{Engines should only send info messages beginning with {\fw info error}
when a client error has occurred. Info messages beginning with {\fw info string}
may be sent by the engine for any purpose. Both kinds of info messages may be
interpreted by the client in any implementation-defined manner; in fact, a
conforming client may simply ignore all such info messages (although it is
recommended that clients do not do this).}

A~field is a sequence of two or more tokens.
\item{Any number of fields may be omitted (subject to the aforementioned
constraint that at least one field must be present).}
\item{Each field may appear only once.}
\item{Fields may appear in any order, subject to the constraint that the
\tok{pv} field, if present, must be last.}\noskip
In the field descriptions below, the metatoken \tok{\it int} is any decimal
integer in the range 0 to 2⁶³\ot−\pt1 inclusive. The meaning of each field
is implementation-defined\comment{, but recommended use is given after an
equals sign as a comment}. The fields are:
\item{\tok{depth \it int} \comment{= for traditional α/β engines, the nominal
length in ply of the principal variation before extensions and reductions have
been applied and not including plies examined in a quiescing search},}
\item{\tok{seldepth \it int} \comment{= for traditional α/β engines, the length
in ply of the principal variation after extensions and reductions have been
applied, possibly including plies explored in a quiescing search, or the length
in ply of the longest line examined by the engine},}
\item{\tok{nodes \it int} \comment{= the number of positions (counted with
multiplicity) examined by the engine since the most recent go message was
read},}
\item{\tok{time \it int} \comment{= the time in milliseconds since the most
recent go message was read},}
\item{\tok{nps \it int} \comment{= the mean number of positions (counted with
multiplicity) examined per second since the most recent go message was read},}
\item{\tok{hashfull ...}, where \tok{...}\ is a decimal integer in the range 0
to 1000 inclusive \comment{= for traditional α/β engines, the number of unique
cache entries per mille written by the engine since the most recent go message
was read},}
\item{\tok{tbhits \it int} \comment{= the number of tablebase accesses since
the most recent go message was read},}
\item{\tok{currmove ...}, where \tok{...}\ is an algebraic token
\comment{= for traditional engines, when interpreted as long algebraic notation,
the first move of the lines currently being examined by the representative
worker (the thread that will determine which move is reported with the bestmove
message)},}
\item{\tok{currmovenumber \it int} \comment{= for traditional engines, an index
associated with the move given by {\fw currmove} in the same message, assigned
in order that those moves and their continuations are examined, where {\fw 1}
indicates the first move},}
\item{\tok{multipv \it int} \comment{= the rank of the line given in the
{\fw pv} field of the same message, where {\fw 1} indicates the principal
variation, {\fw 2} indicates the principal variation if the first move of line
1 were disallowed as the first move of the principal variation, {\fw
3}~indicates the principal variation if the first moves of lines 1 and 2 were
disallowed as the first move of the principal variation, and so on},}
\item{\tok{score cp ...¹} (\pt\tok{...²}\pt)?\ or \tok{score mate ...¹}, where
\tok{...¹} is a decimal integer in the range −2⁶³\ot+\pt1 to 2⁶³\ot−\pt1
inclusive (which may be written with a leading \tok{+}) and \tok{...²} is either
\tok{lowerbound} or \tok{upperbound} \comment{= when {\fw cp}, an estimate of
the advantage in centipawn for the side-to-move, where negative values of {\fw
...¹} indicate that the side-to-move is disadvantaged; when {\fw mate}, an
indication that a forced mate in this many full moves exists, where positive
values of {\fw ...¹} indicate that the side-to-move can deliver mate so that the
game is over after {\fw ...¹}\pt×\pt2 − 1 additional plies have been played
(including the move that the side-to-move is about to make) and negative values
of {\fw ...¹} indicate that the side-waiting can deliver mate so that the game
is over after {\fw ...¹}\pt×\pt2 additional plies have been played (including
the move that the side-to-move is about to make); when {\fw lowerbound} is
present, an indication that {\fw ...¹} is an estimated bound in centipawn for
the advantage for the side-to-move and the advantage is estimated to be
{\fw ...¹} or greater; when {\fw upperbound} is present, an indication that
{\fw ...¹} is a likewise an estimated bound and the advantage is estimated to be
{\fw ...¹} or less},}
\item{\tok{pv ...}, where \tok{...}\ is a sequence of algebraic tokens
\comment{= the principal variation, or when the {\fw currmove} field is present,
the principal variation if the move given by the {\fw currmove} field in the
same message were required to be the first move of the principal variation}.}

Additional implementation-defined fields besides those listed above may be
included in search information. Implementation-defined fields must not have any
contiguous subsequence of tokens matching the fields listed above.

\comment{The second token of the {\fw currmove} field, when interpreted as long
algebraic notation, should correspond to a legal move for the side-to-move in
the position defined by the last well-formed position message sent by the client
in the idle state (or in the starting position if no such position messages have
been sent), but the field is still well-formed even when this is not the case
(although clients may then ignore the field, since the meaning of the field is
implementation-defined).}

\comment{Likewise, the tokens of the {\fw pv} field following the token
{\fw pv}, when interpreted as long algebraic notation, should correspond to a
sequence of legal moves from the position defined by the last well-formed
position message sent by the client in the idle state (or from the starting
position if no such position messages have been sent), but the field is still
well-formed even when this is not the case (although clients may then ignore the
field, since the meaning of the field is implementation-defined).}

\comment{Many legacy clients require the {\fw multipv} field whenever the
{\fw pv} field is present, regardless of engine configuration. This behavior is
strongly discouraged.}

\minor A \cmd{bestmove} message is well-formed when its body is of the form
\inset{\tok{bestmove 0000}}\noskip
or is of the form
\inset{\tok{bestmove ...}}\noskip
where \tok{...}\ is an algebraic token that, when interpreted as long algebraic
notation, corresponds to a legal move for the side-to-move in the position
defined by the last well-formed position message sent by the client in the idle
state (or in the starting position if no such position messages have been sent).

\comment{The token {\fw 0000} (or {\it null move}) should generally be used to
indicate that the engine was unable or is not willing to recommend a move.}

All bestmove messages sent in the active, ping, and halt states must be
well-formed. \comment{In other words, when the engine sends a bestmove message
in these states that is not well-formed, a violation has occurred.}

\vskip\parskip
\major{\bf Client Commands}

\minor The only well-formed \cmd{uci} message body is the one-token sequence
\tok{uci}.

\minor A \cmd{setoption} message is well-formed when its body is of the form
\inset{\tok{setoption name ...¹ value ...²}}\noskip
where
\item{\tok{...¹} is a non\-empty sequence of tokens that match an option name
that has been advertised by the engine whose option type is \tok{check},
\tok{spin}, \tok{combo}, or \tok{string},}
\item{\tok{...²} is \tok{true} or \tok{false} when the option type is
\tok{check},}
\item{\tok{...²} is a decimal integer not less than the minimum value nor
greater than the maximum value advertised by the engine when the option type is
\tok{spin},}
\item{\tok{...²} is one of the token sequences advertised by the engine when the
option type is \tok{combo},}
\item{\tok{...²} is any non\-empty sequence of tokens when the option type is
\tok{string},}\noskip
or is of the form
\inset{\tok{setoption name ...}}\noskip
where \tok{...}\ is a non\-empty sequence of tokens that match an option name
that has been advertised by the engine whose option type is \tok{button}.

When the option type is \tok{string}, the single-token sequence \tok{<empty>}
must be interpreted by the engine as if it were the empty sequence.

\minor The only well-formed \cmd{debug} message bodies are the sequences
\tok{debug on} and \tok{debug off}.

\minor The only well-formed \cmd{ucinewgame} message body is the single-token
sequence \tok{ucinewgame}.

\minor The only well-formed \cmd{isready} message body is the single-token
sequence \tok{isready}.

\minor A \cmd{position} message is well-formed when its body is of the form
\inset{\tok{position ...¹} (\pt\tok{moves ...²}\pt)?}\noskip
where
\item{\tok{...¹} is the token \tok{startpos} or the seven-token sequence
\tok{fen ...\sup{f}}, where \tok{...\sup{f}} is the description of a position
in Forsyth-Edwards Notation,}
\item{\tok{...²} is a sequence of algebraic tokens that, when interpreted as
long algebraic notation, correspond to a sequence of legal moves from the
position described by \tok{...¹}.}

In the final position (the position described by the entirety of the
\cmd{position} message) there must be at least one legal move available for the
side-to-move \comment{(in other words, the game must not be over)}, otherwise
the message is not well-formed.

\comment{Recall that position messages sent in idle state that are not
well-formed must be ignored by the engine, so engines may not partially apply
position updates.}

\minor A \cmd{go} message is well-formed when its body is of the form
\inset{\tok{go infinite} (\pt\tok{...}\pt)?}\noskip
where \tok{...}\ is a non\-empty sequence of well-formed \purple{search
modifiers}, or of the form
\inset{\tok{go} (\pt\tok{...})?}\noskip
where \tok{...}\ is a non\-empty sequence of well-formed \purple{search
limits}, \purple{search context}, and/or modifiers.

Modifiers, limits, and context items are sequences of two or more tokens.
\item{Each limit, context item, or modifier may appear only once.}
\item{Limits, context items, and modifiers may appear in order, subject to the
constraint that the \tok{searchmoves} modifier, if present, must be last.}

The meaning of search modifiers, search limits, and search context is
implementation-defined\comment{, but recommended use is given after an equals
sign as a comment}.

In the descriptions below, the metatoken \tok{\it int16} is any decimal integer
in the range 1 to 2¹⁵\ot−\pt1 inclusive, the metatoken \tok{\it int32} is any
decimal integer in the range 0 to 2³¹\ot−\pt1 inclusive, and the metatoken
\tok{\it int64} is any decimal integer in the range 0 to 2⁶³\ot−\pt1 inclusive.
\comment{Note that, unlike {\fw\it int32} and {\fw\it int64}, an {\fw\it int16}
{\weight{Medium}cannot} be zero.}

\vfill\break
The search modifiers are:
\item{\tok{searchmoves ...}, where \tok{...}\ is a non\-empty sequence of
algebraic tokens that, when interpreted as long algebraic notation, each
correspond to a legal move for the side-to-move in the position defined by
the last well-formed position message sent by the client in the idle state
(or in the starting position if no such position messages have been sent)
\comment{= a collection of moves to which the engine should restrict its
consideration (in other words, the move reported with the bestmove message
should be one of the moves in this collection)},}
\item{\tok{mate \it int16} \comment{= an indication that the engine should
attempt to prove a mate in this many full moves (or twice this many plies)
and may assume that it does not need to examine lines beyond this many full
moves (or twice this many plies)}.}

The search context items are:
\item{\tok{wtime \it int32} \comment{= the number of milliseconds that the white
side has on their clock},}
\item{\tok{btime \it int32} \comment{= the number of milliseconds that the black
side has on their clock},}
\item{\tok{winc \it int32} \comment{= the number of milliseconds that will be
added to white's clock after each move by white},}
\item{\tok{binc \it int32} \comment{= the number of milliseconds that will be
added to black's clock after each move by black},}
\item{\tok{movestogo \it int16} \comment{= an indication that when the
side-to-move has played this many additional moves (including the move that
the side-to-move is about to make) a new time control will begin}.}

The search limits are:
\item{\tok{depth \it int16} \comment{= for traditional α/β engines, the maximum
length in ply of the principal variation (before extensions and reductions have
been applied, and not including plies examined in a quiescing search) that the
engine should explore},}
\item{\tok{nodes \it int64} \comment{= for traditional engines, the maximum
number of positions (counted with multiplicity) that the engine should
examine},}
\item{\tok{movetime \it int32} \comment{= the maximum time in milliseconds that
the engine should spend after reading this message before sending a bestmove
message}.}

\comment{When more than one limit is given, the halting condition should be
the logical {\caps or} of the limits rather than the logical {\caps and}.
In other words, the engine should stop and send a bestmove message when any
of the limiting conditions are met.}

\comment{Since the meaning of search modifiers, search limits, and search
context are implementation-defined, engines may ignore them (for example,
node limits). However, disregard or lack of support for search context and the
{\fw depth} and {\fw movetime} limits is strongly discouraged.}

\minor The only well-formed \cmd{stop} message body is the single-token
sequence \tok{stop}.

\minor The only well-formed \cmd{quit} message body is the single-token
sequence \tok{quit}.

\vskip\parskip
%\vfill\break
{\bf Revision Notes}\par
\def\uci{{\caps uci}}%
\def\spec{{\caps spec}}%
\def\hmk{{\caps hmk}}%
This specification (or \purple{\spec}) is primarily a formalization of the
{\it Description of the universal chess interface} (or \purple{\hmk}) by Rudolf
Huber and Stefan Meyer-Kahlen, but it differs in the following ways:

▶\hem\hmk\ states that, when the client sends the message \tok{go infinite},
the engine must ``not exit the search'' until it is sent a following \cmd{stop}
message, whereas in the active state \spec\ always allows engines to return a
\cmd{bestmove} message. \comment{This is meant to simplify the specification
and allow engines to signal that they have reached their maximum depth and
will make no further progress.}

▶\hem\spec\ allows the client to send the engine a \cmd{go} message without a
corresponding \cmd{position} message, whereas \hmk\ requires the client to send
a \cmd{position} message before it sends the first \cmd{go} message and in
between every pair of \cmd{go} messages.

▶\hem\hmk\ states that clients and engines should attempt to skip unknown or
malformed tokens and continue parsing the remainder of a message, whereas
\spec\ states that clients and engines should ignore the message.

▶\hem\hmk\ includes \uni{0009 character tabulation} in its definition of
white\-space (and possibly other scalar values as well), whereas \spec
\ implicitly defines white\-space as contiguous sequences of \uni{0020} only.

▶\hem\spec\ does not include the \cmd{register} command or \cmd{registration}
and \cmd{copyprotection} remarks. \comment{The effect of a register message may
be emulated with a setoption message, and registration and copyprotection
messages may be emulated with info messages.}

▶\hem\hmk\ allows search information to end with a \tok{string} field, whereas
\spec\ does not. {\caps Hmk} also disallows the \tok{seldepth} field when the
\tok{depth} field is not present, but \spec\ does not impose this restriction.

▶\hem\spec\ introduces the \cmd{protocol} remark.

Although \spec\ is designed so that conforming engines will be usable with
nonconforming, legacy clients (and vice versa), some configurations may be
incompatible.

In future versions of this specification, this section will also list changes
that have been made from prior versions.

\vskip\parskip
{\bf Outstanding Issues}\par
▶\hem The transition diagram needs to show that when the engine sends a
\cmd{bestmove} message in the active, ping, and halt states that is not
well-formed, a violation has occurred.

▶\hem Pondering still needs to be incorporated.

▶\hem Should \tok{refutation} and \tok{currline} be included in the list of
governed fields? or left as implementation-defined additions?

▶\hem Should this specification introduce {\caps wdl} scoring (or something
similar) in addition to centipawn-advantage scoring?

▶\hem Should \tok{upperbound} and \tok{lowerbound} not be required to come after
the score?

▶\hem Should the client be allowed to queue up messages in the halt state?

▶\hem Should the client be allowed to send a \cmd{quit} message anytime?

▶\hem Should a \cmd{stop} message in the idle state be considered an error? In
other words, should the engine notify the client with \tok{info error ...}\ that
it received a \cmd{stop} message in the idle state, rather than with a generic
\cmd{info} message?

▶\hem Should the value for \tok{string}-type options be a sequence of bytes
rather than a seqence of tokens? – since (\pt1\pt) file system paths may contain
\uni{0020}, where it's not a separator and the number of contiguous \uni{0020}
values is significant, and (\pt2\pt) file system paths are often just byte
sequences. This latter fact means that it'd be insufficient to relax the {\caps
ascii} restriction on client messages; the {\caps utf-8} restriction needs to be
relaxed as well. (In fact, it's worse than that: file system paths can also
include \uni{000a}, so an escape sequence would need to be devised.)

▶\hem Should this formalization of {\caps uci} be given a name? If so, what?

▶\hem There should be a set of conformance tests that client and engine
developers can use to find ways in which their programs do not adhere to
specification. (Help writing these would be welcome.)

\vfill
%\centerline{\purple{\fw *\pt\raise0.5ex\hbox{*}\pt*}}
%\vskip-\parskip
{\caps copyright 2022}\ \kern1pt\comment{\fw uci@expositor.dev}
\vskip-\parskip
Although interfaces are not copyrightable, this particular document is protected
by copyright. However, this work is licensed for use under the Creative Commons
Attribution-NoDerivatives license (\ot{\caps cc by-nd 4·0}\ot). Informally, this
means you are free to copy and redistribute this work so long as you give
appropriate attribution and notice of the license, but you are not allowed to
distribute modified copies or derivative works.
\eject\bye