wire-contract.md

# Wire contract for hand-written JSON clients

What a client that speaks Connect + JSON to `sysml-grpc` **without a generated library** has
to know to decode every answer correctly: MATLAB's `webwrite`, R's `httr2`, Julia's `HTTP.jl`,
C with `libcurl`, or `curl` in a shell script. It picks up where
[service transports](service-transports.md#two-things-a-hand-written-json-client-must-know)
stops. That page explains the four protocols on one port and why a generated protobuf client
is the better choice when one exists; this page assumes JSON is the choice you have, and
states, field by field, what the bytes mean.

Every request and response below was captured from a `sysml-grpc` built from this repository
(`go build -o bin/sysml-grpc ./cmd/sysml-grpc`, started with `-port 50099`, its default
transport) and is pasted as the service wrote it, with one exception: responses too long
for a line are re-indented, and an omitted part is marked `…` and named in the text. Request
bodies that are one of the conformance fixtures under
[`conformance/fixtures/`](https://github.com/Open-MBEE/OpenSysML/tree/main/conformance/fixtures)
name the fixture instead of repeating it.

```console
$ curl -s -X POST http://localhost:50099/sysml.SysMLService/<Method> \
    -H 'Content-Type: application/json' -d '<request>'
```

The Python client's decoding (`client/python/opensysml/values.py`, `errors.py`) is the
reference for what follows; where this page says a client *must* do something, that is what
the Python client does, stated so that it can be reproduced in a language that has no
client.

## The request line, and what an HTTP client sees before the body

One URL per method: `POST /sysml.SysMLService/<Method>`, where `<Method>` is the RPC's name as
spelled in `api/proto/sysml.proto` (`ParseSources`, `Evaluate`, `Instantiate`, …), with
`Content-Type: application/json`. Three things go wrong before the service reads a body, and
none of them answers a JSON error:

| Request | Status | Body |
|---|---|---|
| Unknown method (`/sysml.SysMLService/NoSuchMethod`) | `404 Not Found` | `404 page not found` (plain text) |
| `GET` instead of `POST` | `405 Method Not Allowed` | empty, with `Allow: POST` |
| No `Content-Type`, or one not served | `415 Unsupported Media Type` | empty, with `Accept-Post: …, application/json, …` |

So a client checks the response's `Content-Type` is `application/json` **before** parsing.
Every answer the service itself produces, success or failure, is JSON.

### Field names and JSON types

Field names are the proto3 JSON mapping of the proto names: `model_hash` on the wire is
`modelHash`, `strict_conformance` is `strictConformance`, `states_visited` is `statesVisited`.
The proto file is the authority; take a name from it and lowerCamelCase it. Types follow the
same mapping, and three of its rules matter here:

1. **`int64` is a JSON string.** `{"intValue":"4"}`, `{"id":"1"}`, `{"instanceId":"3"}`. On
   input the service accepts either spelling — `{"intValue":10}` and `{"intValue":"10"}` produce
   the same call — but it always *writes* a string, so a decoder that reads `intValue` as a
   number is wrong on output even when its requests work.
2. **A field at its default value is omitted.** `holds:false`, `error:""`, `materialized:false`,
   an empty `diagnostics` list, a zero `real` inside `complex` — none of these appear. Absent
   means default, and the decoder must supply it. The exception is a `oneof` arm, which is
   written even at its default (`{"intValue":"0"}`, `{"boolValue":false}`, `{"realValue":0}`,
   `{"stringValue":""}`) because the arm's presence is the information.
3. **Unknown request fields are silently dropped.** A misspelled field is not an error:
   `{"modelHash":"…","expresion":"1 + 1"}` is the same call as one with no expression, and the
   answer is the *empty-expression* answer (below), not a complaint about `expresion`. Check your
   spelling against the proto; the service will not.

```console
$ … /Evaluate -d '{"modelHash":"2af52c50cee63699ece8f9021b6344e4fe9f2fe6eeb0f3f8edd9feaa5443dea2","expresion":"1 + 1"}'
{"error":"expression parse failed","diagnostics":[{"severity":"error","message":"expected an expression","span":{"file":"<expression>","startLine":1,"startCol":1,"endLine":1,"endCol":1},"code":"syntax"}]}
```

A body that is not valid JSON, by contrast, is refused with a Connect error (see
[Three places a failure can be](#three-places-a-failure-can-be)):

```console
$ … /Evaluate -d '{"modelHash": nope}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"unmarshal message: unmarshal into *proto.EvaluateRequest: proto: syntax error (line 1:15): invalid value nope"}
```

## The session: `ParseSources` and the model hash

There is no session object. A client parses a model once, receives a **model hash**, and
passes that hash to every later call. `ParseSources` takes `documents` (not `sources`), each
with either `content` plus a `name` and an optional `language` (`sysml`, the default, or
`kerml`), or a `filePath` the *service's* process can read (its language follows the file
extension); and an optional `strictConformance` flag.

```console
$ … /ParseSources -d '{"documents":[{"name":"vehicle.sysml","content":"…"}]}'
{"modelHash":"2af52c50cee63699ece8f9021b6344e4fe9f2fe6eeb0f3f8edd9feaa5443dea2","roots":[{"kind":"RootNamespace","childIds":["Demo"]}]}
```

`content` above is `conformance/fixtures/vehicle.sysml` as one JSON string. Several documents
form one model, in which imports between them resolve and a diagnostic names the document it
came from:

```console
$ … /ParseSources -d '{"documents":[{"name":"behavior.sysml","content":"…"},{"name":"verification.sysml","content":"…"}]}'
{"modelHash":"97949455341222bd3f8a0b0d6d44263dfaa01bf7cad948b008f0a062287a8610","roots":[{"kind":"RootNamespace","childIds":["Test"]},{"kind":"RootNamespace","childIds":["Demo"]}]}
```

The response has three fields a client reads:

- `modelHash` — the handle for every later call. Present even when the model has errors.
- `roots` — one `SymbolInfo` per document, in request order; `childIds` are the fully
  qualified names of its top-level members. Every `id` in this API is a fully qualified name
  (`Demo::Vehicle::mass`), and that is what `symbolId`, `contextSymbolId`, `elementId` and
  friends take.
- `diagnostics` — the parse and validation findings, absent when there are none. Their shape is
  in [Diagnostics](#diagnostics-the-shape-of-a-finding).

A syntax error is **not** a failed call. The status is 200, the model is cached, and the hash
is usable for what did parse, but a client that treats a hash as "the model is good" must
check `diagnostics` for `"severity":"error"` first:

```console
$ … /ParseSources -d '{"documents":[{"name":"syntax_error.sysml","content":"package Test { invalid syntax ((( }\n"}]}'
{"modelHash":"da0e2628154910330555183af59d8f803233352122b69f64da8ff138094f0c50","roots":[{"kind":"RootNamespace","childIds":["Test"]}],"diagnostics":[{"severity":"error","message":"expected a namespace member","span":{"file":"syntax_error.sysml","startLine":1,"startCol":16,"endLine":1,"endCol":23},"code":"syntax"}]}
```

What *is* refused, with a Connect error, is a request the service cannot make a model from at
all:

```console
$ … /ParseSources -d '{"documents":[]}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"documents must name at least one document"}

$ … /ParseSources -d '{"documents":[{"name":"a.sysml","content":"package A {}"},{"name":"a.sysml","content":"package B {}"}]}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"documents 0 and 1 are both named \"a.sysml\": each document of a model needs its own name"}
```

### `GetElementProperties`

`GetElementProperties` answers the metamodel properties of one element by their specification
names (`inheritedFeature`, `connectorEnd`, `directedFeature`, `payloadType`, `isComposite`, …), as
the model's API element form — `Convert` to `api-json` — spells them, without converting the whole
model. `elementId` is a qualified name, the positional id of an unnamed member (`Owner::@2`) or the
form's own `@id`; `properties` names what to read, and empty reads every property the form carries
for the element. Each `ElementProperty` carries its `definingClass`, `many` and `derived` from the
metamodel, its `values` — an `element` (`id`, `qualifiedName`, `metaclass`; the id is accepted back as
`elementId`, so a client walks the graph), a `stringValue` (an enumeration literal included), a
`boolValue`, an `intValue`, a `realValue` or a `number` — an integer beyond int64 or a real beyond
double, as decimal text — and `unsupported`, set with the reason when the element's metaclass
declares no such property, when the metamodel evaluator could not derive it for this element (the
form then omits it, and the reason says why — a dependency it does not derive, a reference it could
not resolve), or when OpenSysML does not derive the property at all; a property that is declared,
derived and empty answers no values and no reason. A standard-library element — one an `element`
value references, or a library qualified name such as `Parts::Part` — is read from the form of the
bundled library document declaring it, converted once per process, so a walk from a model into the
library continues; a library member no name catalogues — the documentation, invariants and
connectors a part inherits from `Occurrences::Occurrence`, a declared multiplicity range — and its
owning membership read back under the ids an answer carried them by, so every id an answer returns
is accepted back. A missing element is an in-band `error`; a model whose document the parser could
not read whole has no element form and reports that the same way. The `element_properties`
capability advertises the RPC.

### `GetSymbol` and the `SymbolInfo` metadata keys

`GetSymbol` answers one `SymbolInfo` for a symbol id: a fully qualified name, or the
positional id an unnamed declaration has in the query API and the export (`Owner::@3` for
the fourth member of `Owner`, `Owner::@3::wheel` for a named member of it). `childIds` are the
members the element itself declares under the same ids, named and unnamed alike (a `bind`, a
`connect`, a `part : P;`, a `@M { … }` or `#M` annotation), each of which `GetSymbol` resolves;
a member no id reaches, such as a body-local declaration, is not listed. `members` is every
member it has (KerML `Type::member`) — the owned ones first, in declaration order, then the
inherited ones in inheritance order, each with its `kind`, `inherited` and `inheritedFrom`, a
redefinition masking what it redefines and a private member of a supertype left out. Members
inherited from standard-library content are withheld and counted in `withheldLibraryMembers`
unless the request sets `includeLibraryMembers`, which lists them marked `library`. The
`symbol_members` capability advertises the field; a service without it answers no `members`.
Beside the other typed fields (`typeInfo`, `multiplicity`, `specializations`, `attributes`),
`metadata` is a string map of facts about the declaration, each present only when it holds:

For a named package or namespace declared in several documents, `childIds` is the sorted,
deduplicated union of its declarations' children. Model declarations and standard-library
homonyms remain separate. Document roots retain only their own document's children; other
declaration kinds are not merged.

| Key | Value | When |
|-----|-------|------|
| `visibility` | `default` (none written), `public`, `private` or `protected` | always |
| `type` | the first typing target as written (`Engine`), or the metadata definition an annotation names (`FailureMode`) | a typed usage, a `@M`/`#M` metadata usage |
| `multiplicity` | the declared range as written (`1`, `0..*`) | a usage declaring one |
| `direction` | `in`, `out` or `inout` | a directed usage |
| `specializes` | the first specialization target as written | a definition specializing one |
| `abstract` | `true` | an `abstract` definition or usage, and every variation (a variation is always abstract, SysML v2.1 §7.6.7) |
| `variation` | `true` | a `variation` definition or usage, and every enumeration definition (SysML v2.1 §8.3: an enumeration is a variation of its values) |
| `variant` | `true` | a `variant` usage, and every enumerated value of an enumeration definition |

```console
$ … /GetSymbol -d '{"modelHash":"…","symbolId":"PLE::EngineChoices"}'
{"symbol":{"id":"PLE::EngineChoices","name":"EngineChoices","kind":"partDef","metadata":{"abstract":"true","specializes":"Engine","variation":"true","visibility":"default"},"childIds":["PLE::EngineChoices::fourCyl"],…}}
```

A client telling a variation point from an ordinary part, or a variant from an ordinary member,
reads `variation` and `variant`; `kind` alone does not say (`partDef` for both).

### What a model hash is

A model hash is the lowercase hex SHA-256 (64 characters) of the request that produced it: the
conformance mode (`default` or `strict`), the number of documents, and each document's name,
language and content, length-delimited (`internal/frontend/grpc/service.go`, `parseSources`). It is
**deterministic**: the same documents in the same order with the same flag give the same hash
from any service of the same version, so a client may compute nothing and simply compare
hashes to know whether two models are the same text. It is also *only* a hash of the
text — the same `vehicle.sysml` parsed with `strictConformance:true` is a different model with
a different hash, because the mode is part of the key:

```console
$ … /ParseSources -d '{"documents":[{"name":"vehicle.sysml","content":"…"}],"strictConformance":true}'
{"modelHash":"39e81db405bd2c37d99f7cb6097b4ec6736737090a025a50d8d3f6c500ee955b","roots":[{"kind":"RootNamespace","childIds":["Demo"]}]}
```

`strictConformance` makes OpenSysML's extension notation a parse error rather than an accepted
extension, and a namespace whose memberships are indistinguishable (`Duplicate of other owned
member name` and its alias and inherited wordings) an error rather than a warning; what that
covers is under [Strict conformance](../guide/03-command-line.md#strict-conformance)
in the guide.

### How long a hash is valid

The service keeps parsed models in an in-memory **LRU cache of fixed capacity**
(`internal/frontend/grpc/cache.go`), sized by the `-cache-size` flag, **default 100**. There is no
time-to-live: a model stays until it is one of the least recently *used* when the cache is full
and a new model arrives, or until the process exits. Every call that names a hash counts as a
use, so a model in active use is not evicted. Re-parsing a model the cache still holds returns
the same hash and does not re-parse.

The consequence for a client: a hash is a **cache key, not a durable identifier**. Store the
documents, not the hash; recompute by re-parsing whenever the service says the hash is gone.
Here it is happening, against a service started with `-cache-size 1`:

```console
$ … /ParseSources -d '{"documents":[{"name":"a.sysml","content":"package A { attribute x = 1; }"}]}'
{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","roots":[{"kind":"RootNamespace","childIds":["A"]}]}

$ … /Evaluate -d '{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","expression":"A::x"}'
{"result":{"intValue":"1"}}

$ … /ParseSources -d '{"documents":[{"name":"b.sysml","content":"package B { attribute y = 2; }"}]}'
{"modelHash":"ca693643bf449df4d2904900963596195409a34bbc51f243964952077ab99eb3","roots":[{"kind":"RootNamespace","childIds":["B"]}]}

$ … /Evaluate -d '{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","expression":"A::x"}'
HTTP/1.1 404 Not Found
{"code":"not_found","message":"model not found: f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae"}

$ … /ParseSources -d '{"documents":[{"name":"a.sysml","content":"package A { attribute x = 1; }"}]}'
{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","roots":[{"kind":"RootNamespace","childIds":["A"]}]}
```

### Parsing the same documents again after an edit

A client that re-parses one model after each edit (an editor, a build that recompiles) sends the
same documents by name with some contents changed. From the second parse of a document set, the
service answers from an incremental workspace it keeps for that set
(`internal/frontend/grpc/lineage.go`): it re-parses only the documents whose content changed, and
re-analyzes only those and the documents whose analysis read them. Nothing in the request or the
answer changes. The model, its hash, its diagnostics and every later call on it are what a first
parse of the same documents gives; only the time differs. A set is keyed by its documents' names
and languages and the conformance mode, and the service keeps the four most recently used.
`ParseFile` parses its one document whole.

Under the `parse_sources_affected` capability a client can also ask which documents an edit
reached. It sends the hash it was answered last as `base_model_hash`, and the answer's `affected`
names, in the request's document order, every document whose results may differ from the base
model's. A document left out was answered from the very analysis the base was, so its
diagnostics are the base's and `Convert` with `documents` naming it writes exactly what it wrote
for the base: a client that keeps each document's conversion re-converts only the affected ones.
A request without `base_model_hash` gets no `affected`. The list errs towards naming too
many. Every document is named when the service holds no base of that hash, when the base was
answered fresh rather than from the set's workspace (the first parse of a set, a document that
did not parse clean), when the base is another document set's, or when a document of either
model names `ProjectRef`: how many identity scopes a model declares decides whether its ids are
qualified, which can change every document's conversion without changing its analysis. A
document is named whenever the workspace analyzed it again, which can be for a name it read being
declared again unchanged. A base hash sent to a service without the capability is
refused with `UNIMPLEMENTED`.

A **stale or unknown hash** is therefore always HTTP 404 with `"code":"not_found"`, on every
method that takes one. The message is `model not found: <hash>` everywhere except `ApplyEdits`
and `Convert`, which say `model <hash> is no longer cached: parse it again …`. The Python
client turns the `model not found:` message into `ModelNotFoundError`; the right recovery is to
re-parse and retry, and since the hash is deterministic the retry can reuse the stored hash.
Note that `not_found` is also the status for an unknown *symbol* on some methods
(`RunDocumentQuery`, below) and for a `filePath` the service cannot read — the message says
which (`model not found:`, `symbol not found:`, `file not found:`), and a client that recovers
by re-parsing must read it.

## `Value`: twenty-three arms, exactly one present

Every value the engine returns — an expression result, a feature of an instance, an action
output, a state-machine context variable — is a `Value`, which is a proto `oneof` of twenty-three
arms. In JSON that is **an object with exactly one key**, and the key is the discriminator.
A decoder therefore does not look for a `kind` field: it looks at which key is present. The
arms, each captured from `Evaluate` against the model at the end of this section:

| Key | JSON type | Captured | Meaning |
|---|---|---|---|
| `intValue` | string | `{"result":{"intValue":"4"}}` | Integer within 64 bits; string because `int64` |
| `bigIntValue` | string | `{"result":{"bigIntValue":"1180591620717411303424"}}` | Integer beyond 64 bits, in decimal; KerML Integers are unbounded |
| `realValue` | number | `{"result":{"realValue":1.4142135623730951}}` | Real (IEEE-754 double), or a Rational a double holds exactly |
| `rationalValue` | object | `{"result":{"rationalValue":{"numerator":"1","denominator":"3"}}}` | Rational in lowest terms; KerML Rationals are exact. Answered only for one no double holds, accepted for any |
| `boolValue` | boolean | `{"result":{"boolValue":true}}` | Boolean |
| `stringValue` | string | `{"result":{"stringValue":"abc"}}` | String |
| `instanceId` | string | `{"result":{"instanceId":"2"}}` | A reference to a runtime instance, by id |
| `sequence` | object | `{"result":{"sequence":{"elements":[{"stringValue":"nav"},{"stringValue":"sci"}]}}}` | Ordered collection; `elements` are `Value`s |
| `null` | string | `{"result":{"null":""}}` | The SysML `null`, or an unsupported value (non-empty string) |
| `quantity` | object | `{"result":{"quantity":{"rationalMagnitude":{"numerator":"27","denominator":"5"},"unit":"SI::km/SI::h","unitTerm":{…}}}}` | Magnitude with a unit |
| `enumLiteral` | object | `{"result":{"enumLiteral":{"literalId":"Rover::Mode::idle","enumerationId":"Rover::Mode","name":"Mode::idle"}}}` | Enumeration literal; a scalar-valued one (`high = 3`) also carries `value` |
| `unset` | boolean | `{"result":{"unset":true}}` | A feature that exists and has no value |
| `complex` | object | `{"result":{"complex":{"real":1.5,"imaginary":-2}}}` | Complex number |
| `array` | object | `{"result":{"array":{"dimensions":["2","3"],"elements":[{"intValue":"1"},…,{"intValue":"6"}]}}}` | Multi-dimensional array; `elements` are `Value`s in row-major order |
| `vector` | object | `{"result":{"vector":{"components":[{"realValue":3},{"realValue":4}]}}}` | Numeric vector; each component an `intValue` or `realValue` |
| `vectorQuantity` | object | `{"result":{"vectorQuantity":{"components":[{"realMagnitude":3,"unit":"m","unitTerm":{…}},…]}}}` | Vector of quantities; one `quantity` body per component |
| `measurementRef` | object | `{"result":{"measurementRef":{"unit":"m","unitTerm":{…},"unitId":"SI::metre"}}}` | A measurement reference on its own: a unit, its reduction, and the declaration it names |
| `infinity` | boolean | `{"result":{"infinity":true}}` | The unbounded value `*`, which is no number and no string |
| `function` | object | `{"result":{"function":{"calcId":"F::Sq"}}}` | A calc held as a value: the calc it names and, when it was read off an object, that object |
| `set` | object | `{"result":{"set":{"elements":[{"intValue":"1"},{"intValue":"2"},{"intValue":"3"}]}}}` | Unordered collection without duplicates; `elements` are `Value`s, listed in canonical order |
| `tensorQuantity` | object | `{"result":{"tensorQuantity":{"dimensions":["2","2","2"],"components":[{"realMagnitude":1,"unit":"m","unitTerm":{…}},…]}}}` | Tensor of quantities of any rank; one `quantity` body per component, row-major |
| `metaobject` | object | `{"result":{"metaobject":{"elementId":"Meta::seatBelt","metaclassId":"SysML::Systems::PartUsage"}}}` | An element of the model held as an instance of its metaclass (`x meta T`, the last member of `x.metadata`): the element it reflects on, by the id a client keeps for any element (qualified name, positional id `Owner::@2`, or the element form's `@id`), and the metaclass that classifies it |
| `undetermined` | object | `{"result":{"undetermined":{"reason":"P::Q::d has no value in the model","count":{"lower":"1","upper":"1"}}}}` | A model-level result the model leaves open: a read of a feature with no value, or of one whose count is not fixed, or an operation over such a read. `count` bounds the values it would hold |

The `array`, `vector` and `vectorQuantity` rows were captured against
`conformance/fixtures/structured.sysml` (`S::grid`, `S::v`, `S::d`), `measurementRef` against
`conformance/fixtures/measurement_ref.sysml` (`M::u`), `function` against
`conformance/fixtures/function.sysml` (`F::pick`), `set` and `tensorQuantity` against
`conformance/fixtures/set_tensor.sysml` (`T::s.elements`, `T::cube`), `metaobject` against
`conformance/fixtures/metaobject.sysml` (`(Meta::seatBelt meta KerML::Feature)#(1)`); the rest against the model below, with requests of the form
`{"modelHash":"5a89…277c","expression":"<expr>","contextSymbolId":"Rover"}` with `rover.count`,
`RealFunctions::sqrt(2.0)`, `1.0 / 3.0`, `rover.armed`, `"abc"`, `rover.wheel`, `rover.tags`, `null`, `rover.speed`,
`Mode::idle`, `rover.serial` and `rover.z`, and the model was:

```sysml
package Rover {
	private import ScalarValues::*;
	private import SI::*;
	private import ComplexFunctions::*;

	enum def Mode { idle; driving; }

	part def Wheel {
		attribute radius : Real = 0.25;
	}

	part def Vehicle {
		attribute count : Integer = 4;
		attribute mass : Real default = 12.5;
		attribute armed : Boolean = true;
		attribute callsign : String = "R-1";
		attribute speed : ISQ::SpeedValue = 5.4 [SI::km/SI::h];
		attribute mode : Mode = Mode::driving;
		attribute z : Complex = rect(1.5, -2.0);
		attribute serial : Integer;
		attribute tags : String[2] = ("nav", "sci");
		part wheel : Wheel;
	}

	part rover : Vehicle {
		attribute :>> mass = 20.0;
	}
}
```

### The decoding rule

```text
decode(v):
  if v is absent                → no value was produced (see "result vs unset vs null")
  key := the single key of v
  intValue     → parse the string as a 64-bit integer; never as a double
  bigIntValue  → parse the decimal string as an arbitrary-precision integer (it is always
                 outside int64); never as a double
  realValue    → the number, as a double
  rationalValue → numerator / denominator, each a decimal string, as an exact rational;
                 never as a double
  boolValue    → the boolean
  stringValue  → the string
  instanceId   → an opaque reference; parse as 64-bit integer, keep it a reference
  sequence     → map decode over v.sequence.elements (absent elements = empty list)
  null         → if v.null == "" then the language's null, else an error naming v.null
  unset        → the language's "unset" sentinel, distinct from null and from false
  quantity     → see below
  enumLiteral  → identity is literalId; enumerationId is its type; name is for display;
                 value, when present, is the scalar Value the literal equals
  complex      → complex(v.complex.real or 0, v.complex.imaginary or 0)
  array        → shape v.array.dimensions (parse each as int64); elements := map decode over
                 v.array.elements; require len(elements) == product(dimensions), else an error
  vector       → map over v.vector.components: intValue or bigIntValue → integer,
                 rationalValue → exact rational, realValue → double,
                 anything else → an error
  vectorQuantity → map the quantity rule over v.vectorQuantity.components; empty → an error
  measurementRef → unit := v.measurementRef.unit, id := v.measurementRef.unitId;
                 require v.measurementRef.unitTerm when either is present, else an error;
                 require unit or id, else an error; id absent means a composed unit
  infinity     → the language's unbounded sentinel, distinct from a number and from the
                 string "*"; it compares above every finite number and equals itself.
                 The arm is the value itself, so only true carries it: a caller sending
                 infinity: false, directly or nested, is answered with an error rather
                 than with the unbounded value
  function     → calc := v.function.calcId, require it non-empty, else an error;
                 self := v.function.selfId when present and not "0", an opaque reference
                 under the instanceId rule (this response only), else no object
  set          → map decode over v.set.elements (absent elements = the empty set); require
                 no two equal, else an error; keep it a set, not a list
  tensorQuantity → shape v.tensorQuantity.dimensions (parse each as int64, every one positive);
                 components := map the quantity rule over v.tensorQuantity.components;
                 require len(components) == product(dimensions), else an error
  metaobject   → element := v.metaobject.elementId, require it non-empty, else an error;
                 metaclass := v.metaobject.metaclassId; the element is the identity, in
                 whichever id form it arrived (qualified name, positional id, form @id)
  undetermined → the language's "undetermined" sentinel carrying v.undetermined.reason (a
                 string) and v.undetermined.count (lower and upper as strings, upper "*"
                 when unbounded); distinct from unset, from null and from false. Never
                 send it: a request carrying one is answered with INVALID_ARGUMENT
  anything else → an error: a newer service than this decoder
```

The arms in detail, where a detail exists:

**`intValue`.** A string holding a decimal integer, possibly negative, up to the full `int64`
range. Parse it to an integer type of at least 64 bits. **Do not** convert it to a double:
above 2^53 that loses digits silently, and the engine's Integer is exact —

```console
$ … /Evaluate -d '{"modelHash":"5a897a97ae46b32a0ac8c79adaf94d674cdf95d3f751de0eb4748b1d3f31277c","expression":"9007199254740993"}'
{"result":{"intValue":"9007199254740993"}}
```

A double would read that as `9007199254740992`.

**`bigIntValue`.** An Integer outside the `int64` range, as canonical decimal digits: an optional
`-`, no leading zero, no `+`. KerML Integers are the mathematical integers, so `2**70` answers
`{"result":{"bigIntValue":"1180591620717411303424"}}`. A value within `int64` is always sent as
`intValue`, never as `bigIntValue`, so a client that never meets a wide Integer sees no change,
and the two arms never spell the same number; a decoder rejects a `bigIntValue` that fits
`int64` or is not canonical. The service accepts `bigIntValue` on input under the same rule.
The arm is negotiated by the `big_int_values` capability: a service that does not advertise it
sends a wide Integer (bare, nested, or as a `bigIntMagnitude`) as an unsupported `null` naming it
(a vector holding one is withheld whole), refuses a document query bound to one or answering one
with `UNIMPLEMENTED` naming the capability, since a document value has no unsupported arm, and,
since such a service would read an unknown arm as `null`, the bundled clients refuse to send one
to it, document-query bindings included, before the call.

**`rationalValue`.** A KerML `Rational` is a rational number (KerML 1.0 §9.3.2.2.8), held
exactly: `1 / 3` answers `{"result":{"rationalValue":{"numerator":"1","denominator":"3"}}}` and
`0.1 + 0.2` answers `{"numerator":"3","denominator":"10"}`. `numerator` and `denominator` are
canonical decimal strings (no `+`, no leading zero), the fraction is in lowest terms and the
denominator is positive. The service answers a Rational a double holds exactly (`0.5`,
`2.0 ** 70`) as `realValue`, so its answers never spell one number two ways; an Integer is never
answered here, though a whole Rational no double holds is (denominator `1`). A client decoder
rejects an answered `rationalValue` that is not in lowest terms or that a double holds.

On input the direction of the rule is reversed. The service accepts any `rationalValue` in lowest
terms, one a double holds included, as that exact Rational: `{"numerator":"1","denominator":"4"}`
bound to `in x : Rational` evaluates `x + 1/3` to `7/12`. A `realValue` sent to it is always a
binary64 Real, never a Rational: `0.25` bound to the same parameter evaluates `x + 1/3` to
`0.5833333333333333`. Evaluation does not depend on which arm carried a value beyond that: once
read, an exact Rational behaves the same whether it arrived as `rationalValue` or was written in
the model. So the bundled clients send every exact Rational (`Fraction(1, 4)`, `1//4`,
`Rational.of(1, 4)`) as `rationalValue` to a service that advertises `rational_values`.

A value declared `Real` is IEEE 754 binary64 and always answers `realValue` (`rover.mass` is
`{"realValue":20}`). The arm is negotiated by the `rational_values` capability exactly as
`big_int_values` negotiates `bigIntValue`: a service that does not advertise it sends such a
Rational (bare, nested, or as a `rationalMagnitude`) as an unsupported `null` naming it, and
refuses a document query bound to or answering one with `UNIMPLEMENTED` naming the capability.
To such a service the bundled clients send a Rational a double holds exactly as that `realValue`,
the only form it reads, and refuse to send any other Rational before the call.

MATLAB's `jsondecode` gives you a `char`
array, which `int64(str2double(...))` corrupts and `sscanf(s, '%ld')` does not; R needs
`bit64::as.integer64`; Julia's `parse(Int64, s)` and C's `strtoll` are exact.

**`realValue`.** A JSON number. A whole double is written without a fraction — `20.0` arrives as
`20` — so a parser that types by spelling (Julia's `JSON.parse`, R's `jsonlite`, MATLAB's
`jsondecode`) gives an integer type; convert to double unconditionally. **NaN and the two
infinities:** the proto3 JSON mapping spells them as the strings `"NaN"`, `"Infinity"` and
`"-Infinity"`, and that is what this service's serializer (`protojson`) would write if it were
ever handed one. In practice it is not: the engine refuses to produce a non-finite Real and
reports it as an in-body error instead —

```console
$ … /Evaluate -d '{"modelHash":"5a89…277c","expression":"1.0 / 0.0","contextSymbolId":"Rover"}'
{"error":"evaluation failed: division by zero"}

$ … /Evaluate -d '{"modelHash":"5a89…277c","expression":"1.0e308 * 10.0","contextSymbolId":"Rover"}'
{"error":"evaluation failed: arithmetic overflow: result is not a finite Real"}
```

A defensive decoder still accepts a string in `realValue` and maps the three spellings to the
language's NaN/±Inf, so that it never fails on a value the mapping allows; it should not
expect to see one.

**`instanceId`.** The id of an instance the call created. It is meaningful **only within the
response that carries it**: instances are built fresh per call and are not addressable
afterwards. `Instantiate` and the `Verify*` calls return an `instances` table in the same
response that an `instanceId` indexes; `Evaluate` does not, so `rover.wheel` above yields
`{"instanceId":"2"}` and nothing to look `2` up in. Ids are small integers assigned in
creation order and restart at 1 for every call; do not persist them, compare them across
calls, or read them as anything but a key into the sibling `instances` list.

**`sequence`.** `elements` is a list of `Value`s, recursively; an empty sequence has no
`elements` key at all (the default-omission rule). Elements may be of different arms:

```console
$ … /Evaluate -d '{"modelHash":"5a89…277c","expression":"(1, 2.5, \"a\")","contextSymbolId":"Rover"}'
{"result":{"sequence":{"elements":[{"intValue":"1"},{"realValue":2.5},{"stringValue":"a"}]}}}
```

**`null`.** The arm is a string. Empty means the SysML `null` value. **Non-empty** means the
engine held a value it has no wire representation for, and the string says what it was — the
Python client raises `UnsupportedValueError(text)` for that case rather than returning `None`,
and a hand-written client should not silently equate the two either.

**`unset`, `undetermined`, and the four ways to have no value.** Four different things look
like "nothing" and a client must keep them apart:

| Shape | Meaning |
|---|---|
| `result` key **absent** from the response | The call produced no value: it failed (`error` is present), or the method has no result for this input |
| `{"result":{"unset":true}}` | The call produced a value, and it is *unset*: the feature exists on an object and nothing has been assigned to it |
| `{"result":{"undetermined":{…}}}` | The call produced a value, and it is *undetermined*: the model alone was asked and fixes no answer |
| `{"result":{"null":""}}` | The call produced the SysML `null` |

Here is a definition with an attribute that has a type and no value, from
`conformance/fixtures/unset.sysml` (`attribute d : Real;` beside `attribute k : Real = 2.0;`),
read on an instantiated object and then at model level:

```console
$ … /Evaluate -d '{"modelHash":"07bfcf7c99b9bc7176279e47f22e7c6deabae0e012fdae8cc94811e9a73b564f","expression":"d","subjectSymbolId":"P::Q"}'
{"result":{"unset":true}}

$ … /Evaluate -d '{"modelHash":"07bfcf7c99b9bc7176279e47f22e7c6deabae0e012fdae8cc94811e9a73b564f","expression":"d + 1.0","subjectSymbolId":"P::Q"}'
{"error":"evaluation failed: type mismatch: operator '+' is not defined for an instance and a Real"}

$ … /Evaluate -d '{"modelHash":"07bfcf7c99b9bc7176279e47f22e7c6deabae0e012fdae8cc94811e9a73b564f","expression":"P::Q::d"}'
{"result":{"undetermined":{"reason":"P::Q::d has no value in the model","count":{"lower":"1","upper":"1"}}}}

$ … /Evaluate -d '{"modelHash":"07bfcf7c99b9bc7176279e47f22e7c6deabae0e012fdae8cc94811e9a73b564f","expression":"P::Q::d + 1.0"}'
{"result":{"undetermined":{"reason":"P::Q::d has no value in the model","count":{"lower":"1","upper":"1"}}}}

$ … /Evaluate -d '{"modelHash":"07bfcf7c99b9bc7176279e47f22e7c6deabae0e012fdae8cc94811e9a73b564f","expression":"(P::Q::d > 1.0) and false"}'
{"result":{"boolValue":false}}
```

`unset` is written `true` whenever the arm is present; it is never `false`. Reading it as a
boolean and testing it for truth is therefore a bug waiting for the arm to be absent: the
question is "is the `unset` key present", never "is `unset` true".

`undetermined` is the engine declining to invent an answer the model does not give: with a
`subjectSymbolId` the feature is read on the object standing for the subject, and a required
value that object lacks is `unset`; without one the model alone is asked, `d` is a feature no
object holds, and what it would hold is not determined. An operation over an undetermined
operand is undetermined too unless another operand fixes the result (`x and false`,
`x or true`, `x implies true`, `includes((1, x), 1)`), so a client reads it as a result, not
as a failure. `count` is the multiplicity the values conform to — `[1]` for a bare attribute,
`{"lower":"1","upper":"*"}` for a `[1..*]` part — and lets a client answer what the bounds
fix (a `[1..*]` feature is not empty) without asking again. The bundled clients decode it to
`Undetermined` (Go, Java, Rust), `opensysml.Undetermined` (Python, which refuses `bool()` on
it) and `UndeterminedValue` (Node), each printing as `<undetermined>`; none accepts one as an
input. A service that does not advertise `undetermined_value` sends the arm as an unsupported
`null` naming it.

**`quantity`.** A magnitude with a unit:

```json
{"quantity":{"rationalMagnitude":{"numerator":"27","denominator":"5"},"unit":"SI::km/SI::h","unitTerm":{"scaleNum":5,"scaleDen":18,"factors":[{"unitId":"SI::metre","exponent":1},{"unitId":"SI::second","exponent":-1}]}}}
```

- The magnitude is its own `oneof`: **`intMagnitude`** (a string, same rule as `intValue`),
  **`bigIntMagnitude`** (a string, same rule as `bigIntValue`), **`rationalMagnitude`** (same
  rule as `rationalValue`) or **`realMagnitude`** (a number). Exactly one is present. The
  literal `5.4` is the exact Rational 27/5, which no double holds, so it is a `rationalMagnitude`.
- `unit` is the unit expression as written, by fully qualified name of each unit; it is the
  display form and the identity of the unit *as declared*.
- `unitTerm` is the same unit reduced to base units: `factors` are `(unitId, exponent)` pairs
  and `scaleNum/scaleDen` is the exact rational scale to those base units (here 5/18: one
  km/h is 5/18 m/s). A client converting between units multiplies by this ratio; a client
  comparing two quantities for the same dimension compares `factors`. The scale is a
  *ratio*, not a decimal — do not read `scaleNum` alone as "the scale".

**`enumLiteral`.** Three strings: `literalId`, the fully qualified name of the literal and its
**identity**; `enumerationId`, the fully qualified name of its enumeration; and `name`, a
display label. Compare literals by `literalId`. `name` is what the model author wrote at the
reference site relative to a scope (`Mode::idle` here, but `idle` or `Rover::Mode::idle` from
another scope for the same literal), so two equal literals can carry different `name`s and two
literals of different enumerations can carry the same one.

A literal of an enumeration that specializes a scalar type (`enum def Level :> Integer { low = 1;
high = 3; }`) is still a literal on the wire — `Level::high`, a feature `l : Level = Level::high`
and a successful `3 as Level` all arrive as `enumLiteral` — and additionally carries `value`, the
scalar `Value` it equals: `{"enumLiteral":{"literalId":"D::Level::high","enumerationId":"D::Level",
"name":"Level::high","value":{"intValue":"3"}}}`. `value` is absent for a literal that is only its
identity (`Mode::idle`). A client that computes with the scalar reads `value`; one that only
compares identity ignores it. A bare `3` that no enumeration value holds stays `intValue`.

**`complex`.** `real` and `imaginary`, both doubles, **either omitted when zero**:
`rect(0.0, 2.0)` is `{"result":{"complex":{"imaginary":2}}}`. Read each with a default of 0.

**`array`.** The shape and the elements, flattened:

```console
$ … /Evaluate -d '{"modelHash":"42cc…54b0","expression":"S::grid"}'
{"result":{"array":{"dimensions":["2", "3"], "elements":[{"intValue":"1"}, {"intValue":"2"}, {"intValue":"3"}, {"intValue":"4"}, {"intValue":"5"}, {"intValue":"6"}]}}}
```

- `dimensions` is the rank and extents, `int64` strings like `intValue`; a rank-0 array has no
  `dimensions` key (default omission) and exactly one element.
- `elements` is the array flattened in **row-major** order — the last dimension varies fastest,
  so the element at `(i, j)` of a `(2, 3)` array is `elements[i*3 + j]` — and every element is a
  `Value` of any arm, so an array of quantities, or of arrays, nests without a second encoding.
- The element count is the product of the dimensions; a client must check it (and that every
  extent is positive) before indexing, and reject a message that disagrees. The service applies
  the same rule to an array sent to it.

**`vector`.** `components` is a list of `Value`s each of which is an `intValue`, a
`bigIntValue`, a `rationalValue` or a `realValue` — nothing else — so an Integer and a Real component stay distinct, as they do in
a `sequence`. A `vector` is not a `sequence`: `VectorOf((3.0, 4.0))` is one value with a
dimension, and the engine's vector functions accept it where a sequence of numbers would be
read element by element. A component of any other arm is an error, on both sides.

**`vectorQuantity`.** `components` is a list of `quantity` bodies — each with its own
magnitude, `unit` and `unitTerm`, exactly as the `quantity` arm carries them:

```console
$ … /Evaluate -d '{"modelHash":"42cc…54b0","expression":"S::d"}'
{"result":{"vectorQuantity":{"components":[{"realMagnitude":3, "unit":"m", "unitTerm":{"scaleNum":1, "scaleDen":1, "factors":[{"unitId":"SI::metre", "exponent":1}]}}, {"realMagnitude":4, "unit":"m", "unitTerm":{"scaleNum":1, "scaleDen":1, "factors":[{"unitId":"SI::metre", "exponent":1}]}}]}}}
```

The unit is carried per component rather than once, so a vector whose components were
composed in different units arrives as it was computed; a client wanting one unit checks that
every component names the same one. An empty `components` list is an error: a vector quantity
has at least one component. A component sent without its `unitTerm` is refused by the rule
under `quantity`.

**`measurementRef`.** A unit on its own — what `SI::m`, `m / s` or a quantity's `.mRef`
evaluate to — with no magnitude:

```console
$ … /Evaluate -d '{"modelHash":"5b0f…40d5","expression":"M::u"}'
{"result":{"measurementRef":{"unit":"m", "unitTerm":{"scaleNum":1, "scaleDen":1, "factors":[{"unitId":"SI::metre", "exponent":1}]}, "unitId":"SI::metre"}}}

$ … /Evaluate -d '{"modelHash":"5b0f…40d5","expression":"M::speed"}'
{"result":{"measurementRef":{"unit":"m/s", "unitTerm":{"scaleNum":1, "scaleDen":1, "factors":[{"unitId":"SI::metre", "exponent":1}, {"unitId":"SI::second", "exponent":-1}]}}}}
```

- `unit` and `unitTerm` are the `quantity` arm's, under the same rule: a `unit` that names one
  is never sent without its reduction, and a client sending one without it is refused.
- `unitId` is the fully qualified name of the unit *declaration* the reference is — the
  canonical name, `SI::metre` for `m` and for the alias `SI::m` — and is the identity a client
  keeps to send the same reference back. It is **absent for a composed unit** (`m / s` above,
  `km / h`): a unit computed from others names no one declaration, and a client must not
  fabricate one. A reference sent with a `unitId` is resolved against the model's own
  declaration, and refused when the id names nothing, names something that is not a unit,
  or its `unitTerm` disagrees with the declaration's own reduction (see `EvaluateCalc`).
- A `measurementRef` is not a `quantity` with magnitude one: `ConvertQuantity(q, ref)` takes
  one, `q * ref` does not.

**`function`.** A calc held as a value — a calc definition or usage named where a value is
expected, or bound to an `in calc` parameter — travels as the calc it names, not as what the
calc would compute:

```console
$ … /Evaluate -d '{"modelHash":"e587…f81e","expression":"F::pick"}'
{"result":{"function":{"calcId":"F::Sq"}}}

$ … /Evaluate -d '{"modelHash":"e587…f81e","expression":"F::scaler"}'
{"result":{"function":{"calcId":"F::Scaler::scale", "selfId":"1"}}}
```

- `calcId` is the fully qualified name of the calc declaration, and is the identity a client
  keeps to send the same function back. It is never empty: a `function` with no `calcId` is
  malformed, and a decoder refuses it rather than reading it as "no function".
- `selfId` is present when the calc is a usage owned by an object and was read off that object
  (`holder.scale` above reads `holder.k` when invoked). It is an `instanceId` under that arm's
  rules: a 64-bit integer sent as a string, valid within the response it arrived in, and
  indexing that response's `instances` where the method returns them. Absent (or `"0"`, the
  proto default) means the calc computes over no object.
- A function carrying a `selfId` cannot be sent back. Every call instantiates the model afresh
  and numbers its objects from 1, so the object the function was read off does not exist in any
  later call — and another call's object may well carry the same number. A request `function`
  with a non-zero `selfId` is therefore refused in band, whatever the number, rather than bound
  to whichever object that call numbered the same. To apply a calc over an object, name both
  in one expression — `Evaluate` of `F::apply(F::holder.scale, 3.0)` reads the object and
  applies the calc within the call that holds it.
- Two functions are the same function when their `calcId`s are equal and both name the same
  object or neither names one; the engine's `==` says the same.
- A calc that closes over the bindings of a behavior body — one returned by another calc, or
  read inside an action step — has no wire form: the frames it captured belong to a run that
  has ended and cannot be reconstructed remotely. It is sent as the unsupported null
  `{"null":"unsupported: function <calcId> closing over a body's bindings"}`, under the `null`
  arm's rule.
- The arm is gated by the `function_values` capability (see [Capabilities, and what an absent one does](service-transports.md#capabilities-and-what-an-absent-one-does)).
  A service without it sends every function, at any depth, as
  `{"null":"unsupported: function <calcId>"}` and refuses a request that carries one.

**`set`.** `elements` is a list of `Value`s with no two equal — what a `Collections::Set`'s
`elements`, or any collection the library declares unique and not ordered, evaluates to:

```console
$ … /Evaluate -d '{"modelHash":"c409…1a4a","expression":"T::s.elements"}'
{"result":{"set":{"elements":[{"intValue":"1"},{"intValue":"2"},{"intValue":"3"}]}}}
```

- The model wrote `(3, 1, 2, 2, 3)`; the set has three members. The service lists them in the
  engine's **canonical order** — the order `FormatTraceValue` prints and every ordered
  operation on a set reads (nulls, then Booleans, numbers by value, complex numbers, strings,
  quantities, enumeration literals, then objects by identity), each member placed by the value
  it equals whichever arm carries it (`1.0 + 0.0i` among the numbers, an empty collection with
  `null`) — so two equal sets are sent identically, but the order carries no meaning and a
  client must not read one into it.
- A `set` is not a `sequence`: `(1, 2) == (2, 1)` is false, the sets they populate are equal.
  A client compares sets by membership and sends one back in any order it likes. As members
  of a set, a `set` and the `sequence` of its members are two members, on both sides; only
  `==` in the model, an ordered context, reads the set as its canonical sequence.
- Membership is the engine's value equality: numbers by value, so `1` and `1.0` are one member
  and so are `1.5` and the complex `1.5 + 0.0i`, exactly — an Integer past 2^53 is not the Real
  it would round to; a Boolean is never a number; sequences in order; sets by membership;
  quantities by magnitude, converting commensurable units, so `1 [m]` and `100 [cm]` are one
  member; a `measurementRef` by its reduction at its scale, however it is spelt or which
  declaration names it (`SI::'m/s'` and `m / s` are one member, `km / m` and `m / mm` too),
  except that a named unit of dimension one reduces to nothing and so is only its own
  declaration (`rad` is not `sr`); an `enumLiteral` by its `literalId` alone; a `null`, an
  empty `sequence` and an empty `set` as one member, the model's absent value however spelt
  (`unset` stays apart). The bundled clients' equality helpers judge the same way, converting
  a quantity through its `unitTerm` (exactly, while the magnitude is an integer and the scale
  a whole ratio); a quantity sent without a `unitTerm` they compare in its unit as written.
- An empty set has no `elements` key (default omission). A `set` listing a member twice is
  refused on both sides, as is a `set` where the model wants a sequence's order or a sequence
  where it wants a set; a set flowing into an ordered parameter is read in canonical order.
- Members nest: a set of sets, or of arrays, needs no second encoding.
- A set holding a member that has no wire form — one the rule under `null` would send as a
  non-empty `null`, whether because no arm carries it (a coordinate frame, a function closing
  over a body) or because the service withholds its arm (a complex number without
  `complex_values`) — is withheld **whole**, as `{"null":"unsupported: set Set{…} holding
  <the member's reason>"}`. Two such members would otherwise cross as two equal nulls, which a
  set may not hold; a `sequence` of the same members keeps each in its place, so a set nested
  in one is the null in the set's place. This also applies to a set nesting such a set.

**`tensorQuantity`.** `dimensions` is the shape, `components` the quantities flattened in
row-major order, each a `quantity` body with its own magnitude, `unit` and `unitTerm`:

```console
$ … /Evaluate -d '{"modelHash":"c409…1a4a","expression":"T::cube"}'
{"result":{"tensorQuantity":{"dimensions":["2","2","2"],"components":[{"realMagnitude":1,"unit":"m","unitTerm":{"scaleNum":1,"scaleDen":1,"factors":[{"unitId":"SI::metre","exponent":1}]}},{"realMagnitude":2,"unit":"m","unitTerm":{…}},…,{"realMagnitude":8,"unit":"m","unitTerm":{…}}]}}}

$ … /Evaluate -d '{"modelHash":"c409…1a4a","expression":"T::cube#(2, 1, 2)"}'
{"result":{"quantity":{"realMagnitude":6,"unit":"m","unitTerm":{"scaleNum":1,"scaleDen":1,"factors":[{"unitId":"SI::metre","exponent":1}]}}}}
```

- `dimensions` follows the `array` rule: `int64` strings, every extent positive, the component
  count their product, checked on both sides; the component at `(i, j, k)` of a `(2, 2, 2)`
  tensor is `components[(i*2 + j)*2 + k]`. Indexing in the model is one-based and needs one
  index per dimension — `T::cube#(2, 1, 2)` above is the sixth component — and the wrong
  count or an index outside its dimension is an evaluation failure, not a value.
- A rank-one tensor is a `tensorQuantity`, not a `vectorQuantity`: the model's
  `TensorQuantityValue` and `VectorQuantityValue` are different types and stay apart on the
  wire. A `vectorQuantity` never arrives with `dimensions`.
- The unit is per component, as in `vectorQuantity`; a component without its `unitTerm` is
  refused by the rule under `quantity`.

**`metaobject`.** An element of the model held as a value — what `x meta T` yields when the
element `x` names is an instance of the metaclass `T`, and the last member of `x.metadata`
after the element's metadata annotations — travels as the element it reflects on and the
metaclass that classifies it, not as the metaclass it was cast to and not as its features:

```console
$ … /Evaluate -d '{"modelHash":"07a0…b5ca","expression":"(Meta::seatBelt meta KerML::Feature)#(1)"}'
{"result":{"metaobject":{"elementId":"Meta::seatBelt","metaclassId":"SysML::Systems::PartUsage"}}}

$ … /Evaluate -d '{"modelHash":"07a0…b5ca","expression":"Meta::everything"}'
{"result":{"sequence":{"elements":[{"instanceId":"1"},{"metaobject":{"elementId":"Meta::seatBelt","metaclassId":"SysML::Systems::PartUsage"}}]}}}

$ … /Evaluate -d '{"modelHash":"07a0…b5ca","expression":"Meta::notADefinition"}'
{"result":{"sequence":{}}}
```

- `elementId` is the identity a client keeps to send the same metaobject back, and is one of
  the ids the tree already addresses an element by — the same ids `GetElementProperties`
  accepts and reports in its `ElementRef`s, so a client hands a metaobject's `elementId` to
  `GetElementProperties` or `GetSymbol` and hands back what those report:
    - the fully qualified name, for an element one identifies (`Meta::seatBelt`);
    - the positional id of an unnamed member (`Meta::outer::@0`, the `@N` segment
      [`GetElementProperties`](#getelementproperties) and `GetSymbol` address one by), for an
      unnamed declaration;
    - the element form's `@id` (the `convert` to `api-json`), for an element the semantic side
      tables synthesize and no scope declares: a send's or accept's parameter and its argument
      value (`Meta__Monitor__sm__relay___40trigger___401_pvalue` is the `receiverArgument` of
      the accept of `Meta::Monitor::sm::relay`), a transition's guard, an expression's
      operands and parameters, a feature-chain Feature at a connector end
      (`Meta__holder___402_pend0_pchain`).
  It is never empty: a `metaobject` with no `elementId` is malformed, and a decoder refuses it
  rather than reading it as "no element". A decoder keeps the id opaque; it never parses one.
  The WebAssembly engine, whose size budget excludes the exporter and the positional naming,
  names an element by its qualified name only and sends a metaobject of one with none as the
  unsupported null below.
- `metaclassId` is the fully qualified name of the reflective metaclass that classifies the
  element — a part usage is a `SysML::Systems::PartUsage` however it was cast — so a client
  learns what the element is, not what the model asked for. A cast to a metaclass the element
  is not an instance of is the empty sequence (`Meta::notADefinition` above), never a
  `metaobject` under that metaclass.
- Two metaobjects are the same metaobject when their `elementId`s are equal; the engine's
  `===` and `==` say the same, whatever metaclass either was cast to. `metaclassId` does not
  enter the comparison, and cannot differ for one element.
- The element's reflective features (`declaredName`, `qualifiedName`, `ownedFeature`, …) are
  not on the wire. They are read from the model, so a client that needs one evaluates it —
  `(Meta::seatBelt meta KerML::Feature)#(1).qualifiedName` is `{"stringValue":"Meta::seatBelt"}` —
  and a feature the engine does not derive is an evaluation failure naming the feature, not a
  guess.
- A metaobject of an element none of those ids reaches (the implied `Multiplicity` a usage
  owns) is the unsupported null `{"null":"unsupported: metaobject of an element with no
  identity"}`, under the `null` arm's rule. A named element nested in an anonymous one keeps
  its name (`Mid::inner`).
- An `element_id` sent that two declarations of the model share (the same qualified name in two
  documents) identifies neither and is refused in band as ambiguous, never bound to whichever the
  index lists first. A form `@id` is resolved under the nearest element a qualified or
  positional id reaches, among what it owns; one that reaches nothing is unbound, and one a
  declaration's qualified name also spells (`package D__outer___400`) is ambiguous between the two.
- The arm is gated by the `metaobject_values` capability (see [Capabilities, and what an absent one does](service-transports.md#capabilities-and-what-an-absent-one-does)).
  A service without it sends every metaobject, at any depth, as
  `{"null":"unsupported: metaobject Meta::seatBelt : SysML::Systems::PartUsage"}` and refuses a
  request carrying one.

### What a client must not do

- **Do not compare enum literals by `name`.** Compare `literalId`.
- **Do not read `intValue`, `bigIntValue` or `rationalValue` (or `intMagnitude`,
  `bigIntMagnitude`, `rationalMagnitude`, `id`, `instanceId`) as a double.** Above 2^53 the
  digits are gone and nothing tells you.
- **Do not read `unset` as a boolean.** Its presence is the fact; a missing `result` is a
  different fact (no value), `{"null":""}` a third (the null value), and `undetermined` a
  fourth (the model fixes no answer).
- **Do not treat a non-empty `null` string as null.** It names a value that could not be sent.
- **Do not keep an `instanceId` past the response it arrived in**, or use one to index a
  different response's `instances`.
- **Do not default a missing `realValue` to 0 or a missing `boolValue` to false to "make it
  work".** If the key you expected is not the one present, the value is of another kind, and
  the decoder must say so.
- **Do not read an `array` or a `vector` as a `sequence`.** The first has a shape and the
  second a dimension; flattening either into a list loses what the arm exists to carry.
- **Do not index an `array` before checking `len(elements) == product(dimensions)`.**
- **Do not invent a `unitId` for a `measurementRef` that has none.** A composed unit names no
  declaration; send it back as it came, with its `unit` and `unitTerm` only.
- **Do not read a `function` as the value the calc computes, or invoke it locally.** It is a
  reference: hand it back as an argument (`EvaluateCalc`) and let the service invoke it.
- **Do not send back a `function` that carries a `selfId`.** It is an `instanceId`, with that
  arm's lifetime: no later call holds the object, and the service refuses the function rather
  than guess. Only a function over no object (`selfId` absent or `"0"`) is an argument.
- **Do not read a `set` as a `sequence`, or its element order as meaning anything.** Two sets
  are equal when their members are; the order the service lists them in is canonical, not
  significant, and a `set` sent back may list them in any order — but never twice.
- **Do not index a `tensorQuantity` before checking `len(components) == product(dimensions)`**,
  and do not read a rank-one tensor as a `vectorQuantity`.
- **Do not read a `metaobject` as the element's values, or compare two by `metaclassId`.** It
  is the element itself, identified by `elementId`; its features live in the model and are
  evaluated there, and the metaclass says what the element is, not which cast produced it.

## Three places a failure can be

A call can fail at three levels, and a client's classification starts by telling them apart:

1. **The transport refused the call.** HTTP status is not 200 and the body is
   `{"code":"<connect code>","message":"…"}`. Nothing was done. This is a Connect error.
2. **The service ran the call and the model failed.** HTTP 200; the response has a non-empty
   `error` string (and on some methods a `failureReason` and/or `diagnostics`). The result
   fields are absent. This is an in-body failure.
3. **The call succeeded and reports findings.** HTTP 200, result fields present, plus a
   `diagnostics` list (`ParseSources`, and `Evaluate` when the *expression* did not parse).
   Whether an error-severity diagnostic is a failure is the client's decision, and for a parse it
   almost always is.

The rule of thumb from the service's side: a Connect error means **the request itself was not
acceptable** — malformed, naming a model or capability the service does not have, or asking
for two exclusive things — while a 200 with `error` means the request was fine and **the model
did not do what was asked** — a symbol is missing or of the wrong kind, an expression does not
type-check, an action has no start, a value overflowed.

### Diagnostics: the shape of a finding

```json
{"severity":"error","message":"expected a namespace member","span":{"file":"syntax_error.sysml","startLine":1,"startCol":16,"endLine":1,"endCol":23},"code":"syntax"}
```

`GetDiagnostics` reads a parsed model's findings again under a lint selection: `disableLint`
(`-disable-lint`) names lint codes left out, and `enableLint` (`-enable-lint`) names opt-in
lints, off by default, kept in. The selection is per request; the model's cached diagnostics,
as `ParseSources` reported them, are unchanged. An unknown lint code is an `invalid_argument`.

| Field | Type | Meaning |
|---|---|---|
| `severity` | string | `"error"`, `"warning"` or `"info"` |
| `message` | string | The finding, worded for a person; may change between releases |
| `span` | `Span` | Where it is; omitted when there is no location |
| `code` | string | What it is, stable across wording; `""` when the producer assigned none |

`span` locates it: `file` is the document's `name` from the request (or `<expression>` for an
`Evaluate` expression), lines and columns are **1-based**, `end*` is exclusive, and the whole
`span` is omitted when there is no location. Line and column are `int32`, so unlike `int64`
they are JSON *numbers*.

`code` is the identifier to branch on; `message` is not. A syntax error is `"syntax"`, whether
it came from a document, an `Evaluate` expression, an edit's new value or a `Convert` input. A
validation finding carries its pass or rule code, the same one the LSP reports as the
diagnostic's code (`"unresolved"` for a name that resolves to nothing, for instance). A run's
notes are `"choice-point"` and `"guard-unevaluable"` (see [`ExecuteAction`](#executeaction)).
The field is a proto3 string, so a producer that assigns no code sends `""`, which the JSON
encoding omits; treat a missing `code` as empty, never as an error. A service that populates
the field advertises the `diagnostic_codes` capability; from one that does not, every `code` is
empty and says nothing about the finding, so check the capability before branching on it. New
codes may appear in a release; a code, once published, keeps its meaning.

### In-body failures

`error` is text for a person; do not parse it for control flow beyond the prefix. Where a
client needs to branch, the service gives a field for it:

```console
$ … /EvaluateCalc -d '{"modelHash":"9794…8610","symbolId":"Demo::sedan"}'
{"error":"calc invocation failed: not a calc: Demo::sedan is a part usage, not a calc definition or usage","failureReason":"FAILURE_REASON_WRONG_KIND"}
```

`failureReason` is a proto enum, written as its **name**, not its number. The names are in
`api/proto/sysml.proto` (`FailureReason`); `FAILURE_REASON_WRONG_KIND` means the symbol exists
but is not the kind the method operates on, and the Python client raises `WrongKindError` for
it, a subclass of its general `ExecutionError`. A `failureReason` that is absent with an `error`
present is an unspecified execution failure. The other common in-body failures, all HTTP 200:

```text
{"error":"symbol not found: Demo::Nope"}                                    Instantiate
{"error":"state machine not found: Test::NoMachine"}                        ExecuteState
{"error":"action execution failed: initialize action: invalid action flow: no initial node found in action noStart: the successions form a cycle among the steps, leaving none to start at"}
{"error":"evaluation failed: object has no such feature: member nothing not found in instance"}  Evaluate
{"error":"evaluation failed: unresolved reference: sqrt — did you mean RealFunctions::sqrt or QuantityCalculations::sqrt?"}
```

The Python client maps `symbol not found:` to `SymbolNotFoundError` and every other in-body
`error` to `ModelError` (for `Instantiate`) or `ExecutionError` (for the behavior calls),
keeping the text as the message.

### Connect errors: the code table

The body is always `{"code":"…","message":"…"}`; the HTTP status is a function of the code, and
the code is the one to switch on. The full Connect table, and which of its rows this service
actually produces and for what:

| `code` | HTTP | This service answers it for | Client class (Python name) |
|---|---|---|---|
| `invalid_argument` | 400 | Body is not valid JSON for the request type; `documents` empty or with duplicate names; an `ApplyEdits` `document` that is not one of the model's; `query` and `oslcQuery` both present; unknown query property; a document query given no binding for a required parameter, or a `queryId` that is not a document query | `InvalidRequestError` — fix the request |
| `failed_precondition` | 400 | The request is well-formed but the model is not in the state the operation needs: a `Convert` of a multi-document model, which writes one document back out; an `ApplyEdits` of a multi-document model without `acceptDocuments`, which reads one document's `content`; a document query whose own definition is faulty when planned or run; a document whose own definition is faulty when planned | `InvalidRequestError` |
| `out_of_range` | 400 | Not currently produced; reserved by the protocol for a value outside its valid range | `InvalidRequestError` |
| `not_found` | 404 | `model not found: <hash>` (or `model <hash> is no longer cached: …` on `ApplyEdits`/`Convert`) — stale or unknown model hash, on every method that takes one; `symbol not found: <id>` on `RunDocumentQuery` and `RenderDocument`; `file not found: …` for a `filePath` the service could not read | `ModelNotFoundError` / `SymbolNotFoundError` / `ModelFileNotFoundError`, by message prefix — re-parse, fix the name, fix the path |
| `unimplemented` | 501 | A capability the running service was started without (`capability "query" is unavailable`) or a method it does not have | `UnsupportedOperationError` — do not retry |
| `unavailable` | 503 | Not produced by the service itself; a proxy or a shutting-down process answers it | `ConnectionError` — retry with backoff |
| `deadline_exceeded` | 504 | The client's deadline passed | `ServiceTimeoutError` |
| `canceled` | 499 | The client cancelled | `ServiceTimeoutError` |
| `resource_exhausted` | 429 | A document query (`RunDocumentQuery`, or one a `RenderDocument` runs) exhausted its visit, invocation or invocation-depth budget | `ServiceError` — the query, not the request, is at fault |
| `already_exists` | 409 | Not currently produced | `ServiceError` |
| `aborted` | 409 | Not currently produced | `ServiceError` |
| `permission_denied` | 403 | Not produced by the service itself, which has one token and no roles; a proxy in front of it answers it | `ServiceError` |
| `unauthenticated` | 401 | A service started with a token refused the call: no `Authorization` header (or `authorization` metadata), one that is not `Bearer`, or the wrong token (see [Service transports](service-transports.md#authentication)). The HTTP answer carries `WWW-Authenticate: Bearer realm="sysml-grpc"` (with `error="invalid_token"` for a wrong one); a grpc-go answer carries the same in its `www-authenticate` trailer. A malformed header is 400 `invalid_request`, which gRPC reports as `invalid_argument` | `AuthenticationError` (a `ConnectionError`) — supply the service's token |
| `internal` | 500 | A bug in the service: something that should not have failed did (an edit that could not be applied, a document-query library that could not be loaded, a document whose evaluation failed for a reason other than one of its queries) | `ServiceError` — report it |
| `unknown` | 500 | An error the service could not classify | `ServiceError` |
| `data_loss` | 500 | Not currently produced | `ServiceError` |

Examples of the rows this service produces, each captured:

```console
$ … /Query -d '{"modelHash":"2af5…dea2","query":{},"oslcQuery":"sysml:type=PartUsage"}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"query and oslc_query are mutually exclusive"}

$ … /Query -d '{"modelHash":"2af5…dea2","query":{"where":{"primitive":{"property":"colour","operator":"PRIMITIVE_OPERATOR_EQUAL","value":["red"]}}}}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"unknown query property \"colour\"; queryable properties are @id, @type, body, declaredName, declaredShortName, documentation, elementId, general, isAbstract, isIndividual, language, locale, multiplicityLower, multiplicityUpper, name, owner, payloadArgument, qualifiedName, receiverArgument, satisfiedRequirement, satisfyingFeature, senderArgument, shortName, textualRepresentation, type"}

$ … /ApplyEdits -d '{"modelHash":"997e…6134","acceptDocuments":true,"document":"nope.sysml","operations":[{"rename":{"target":"EngineUser::Car","newName":"Automobile"}}]}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"document \"nope.sysml\" is not one of the model's: it has engine_library.sysml, engine_user.sysml"}

$ … /ApplyEdits -d '{"modelHash":"997e…6134","operations":[{"rename":{"target":"EngineLibrary::Engine","newName":"Motor"}}]}'
HTTP/1.1 400 Bad Request
{"code":"failed_precondition","message":"the model has 2 documents, and the request reads only content: set accept_documents to have each edited document answered in documents"}

$ … /Convert -d '{"modelHash":"997e…6134","format":"CONVERT_FORMAT_TURTLE"}'
HTTP/1.1 400 Bad Request
{"code":"failed_precondition","message":"this operation is defined on one document, and the model has 2: name the document to operate on by parsing it on its own"}

$ … /RunDocumentQuery -d '{"modelHash":"7e6a…a687","queryId":"Observatory::NoSuchQuery"}'
HTTP/1.1 404 Not Found
{"code":"not_found","message":"symbol not found: Observatory::NoSuchQuery"}
```

A `filePath` that does not exist for the service's process:

```console
$ … /ParseSources -d '{"documents":[{"filePath":"/nonexistent/x.sysml"}]}'
HTTP/1.1 404 Not Found
{"code":"not_found","message":"file not found: open /nonexistent/x.sysml: no such file or directory"}
```

And a method whose capability the service does not have — which in practice means a service
older than the method; a service built from this repository advertises all of them, and the
conformance runner withholds one only through a test-only environment variable, which is how
this was captured with `query` withheld:

```text
HTTP/1.1 501 Not Implemented
{"code":"unimplemented","message":"capability \"query\" is unavailable"}
```

Capabilities, and how a client discovers them up front with `GetServerInfo`, are on
[service transports](service-transports.md#capabilities-and-what-an-absent-one-does).

### Classifying, in order

```text
if HTTP status != 200:
    parse {"code","message"}                (Content-Type must be application/json)
    switch code: not_found → by message prefix; unimplemented → give up on the method;
                 unavailable/deadline_exceeded → retry; invalid_argument/failed_precondition →
                 caller's bug; internal/unknown → report
elif body.error is present and non-empty:
    model/execution failure; failureReason (if present) says which kind
elif body.diagnostics has an entry with severity "error":
    the call ran but the input did not parse/validate; decide per call
else:
    success; read the result fields
```

## Behavior calls

Every behavior call takes a `modelHash` and a fully qualified `symbolId` (spelled
`actionSymbolId` / `stateMachineSymbolId` on the two execution calls), builds a fresh runtime,
runs, and returns the result plus any `error`/`diagnostics`. The examples use
`conformance/fixtures/behavior.sysml` and `verification.sysml`, parsed together as model
`97949455341222bd3f8a0b0d6d44263dfaa01bf7cad948b008f0a062287a8610`, and the `Rover` model above.

### `Instantiate` and the `Instance` shape

```console
$ … /Instantiate -d '{"modelHash":"5a897a97ae46b32a0ac8c79adaf94d674cdf95d3f751de0eb4748b1d3f31277c","symbolId":"Rover::rover"}'
```

```json
{
  "instance": {
    "id": "1",
    "typeSymbolId": "Rover::rover",
    "featureValues": {
      "armed":    {"featureName": "armed",    "value": {"boolValue": true},   "materialized": true},
      "callsign": {"featureName": "callsign", "value": {"stringValue": "R-1"}, "materialized": true},
      "count":    {"featureName": "count",    "value": {"intValue": "4"},     "materialized": true},
      "mass":     {"featureName": "mass",     "value": {"realValue": 20},     "materialized": true},
      "mode": {
        "featureName": "mode",
        "value": {"enumLiteral": {"literalId": "Rover::Mode::driving", "enumerationId": "Rover::Mode", "name": "Mode::driving"}},
        "materialized": true
      },
      "serial":   {"featureName": "serial",   "value": {"unset": true},       "materialized": true},
      "speed": {
        "featureName": "speed",
        "value": {"quantity": {"realMagnitude": 5.4, "unit": "SI::km/SI::h", "unitTerm": {"scaleNum": 5, "scaleDen": 18, "factors": [{"unitId": "SI::metre", "exponent": 1}, {"unitId": "SI::second", "exponent": -1}]}}},
        "materialized": true
      },
      "tags":     {"featureName": "tags",     "values": [{"stringValue": "nav"}, {"stringValue": "sci"}], "materialized": true},
      "wheel":    {"featureName": "wheel",    "value": {"instanceId": "3"},   "materialized": true},
      "z":        {"featureName": "z",        "value": {"complex": {"real": 1.5, "imaginary": -2}}, "materialized": true}
    }
  },
  "instances": [ … ]
}
```

(Re-indented; `instances` holds two entries, the object above as `"id":"1"` and the `Wheel` as
`"id":"3"` with `radius` `{"realValue":0.25}`.) The shape:

- `instance` is the root; `instances` is **every** instance the call created, root included,
  each with its `id`. An `instanceId` anywhere in the response is a key into this list. Ids
  are strings (`int64`).
- `typeSymbolId` is the fully qualified name of the definition or usage the instance is of.
- `featureValues` is a map from feature name to `FeatureValue`. The map key and `featureName`
  are the same string. Each `FeatureValue` has one of:
  - `value` — a single `Value`, for a feature of multiplicity at most 1;
  - `values` — a list of `Value`s, for a multi-valued feature (`tags`, multiplicity `[2]`).
    Absent when empty. **Which of the two appears is decided by the feature's multiplicity,
    not by how many values it has**; a decoder must accept either;
  - `error` — the feature could not be evaluated; neither `value` nor `values` is present;
  - neither — the feature is single-valued and **not materialized** (the runtime did not
    compute it; see `materialized`).
- `materialized` is `true` when the runtime computed the feature's value for this instance.
  It is omitted when false, and when false there is no `value`. A `Verify*` response shows
  this: constraint and requirement features of the subject are reported unmaterialized.
- `reachedBy` (capability `instance_paths`) says how the traversal that produced the graph
  reached the instance: `instanceId` is the instance holding it, `featureName` the holder's
  feature it is a value of and `featureSymbolId` that feature's qualified name as declared,
  `index` its position within a multi-valued feature counted from 1 (`0` for a single-valued
  one) and `path` the whole path from the root (`powertrain.engine.fuelIn`, `wheels[2]`). The
  root has no `reachedBy`. The traversal is depth-first from the root over the features of
  an instance in name order — those the model declares first, then those the standard
  library derives (`subparts`, `ownedPorts`) — and the values of a feature in their order,
  and reaches an instance once, the first time, which decides `instances`' order too. One
  object is often a value of several features (a port and the connector end referencing it
  are one object): `reachedBy` is the one path the traversal came by, and `InstancePaths`
  below lists every path.

### `InstancePaths`: every path to one object

```console
$ … /InstancePaths -d '{"modelHash":"…","object":{"path":"Fuel::vehicle.powertrain.engine.fuelIn"}}'
```

```json
{
  "paths": [
    {
      "root": {"instanceId": "1", "symbolId": "Fuel::vehicle"},
      "path": "fuelLine.consumer",
      "steps": [
        {"featureName": "fuelLine", "featureSymbolId": "Fuel::vehicle::fuelLine", "instanceId": "2"},
        {"featureName": "consumer", "featureSymbolId": "Fuel::FuelLine::consumer", "instanceId": "7"}
      ]
    },
    {
      "root": {"instanceId": "1", "symbolId": "Fuel::vehicle"},
      "path": "powertrain.engine.fuelIn",
      "steps": [ … ]
    }
  ]
}
```

`object` names the object as `RunDocumentQuery` binds one: by `instanceId`, or by `path` — the
qualified name an object was instantiated as, `#<id>`, or a path through feature values from
either (`Fuel::vehicle.wheels[2]`; indexes count from 1). The response lists every
root-relative path that reaches it from every root the model's population holds (each object
`Instantiate` created), in traversal order: the roots in id order and, from each, depth-first
over the features the model declares in name order and the values of a feature in their
order. Aliases through connector ends and reference usages are paths of their own; the
collections the standard library derives (`subparts`, `ownedPorts`) are not, and a path
visits no object twice nor, as the instance graph, an object whose type is already on the
path. `root.symbolId` is the name the root was instantiated as, empty once
another object took the name (`#<id>` still addresses it). An object that is a root has the
empty path. The search is bounded: past 1000 paths over all roots, or when a path cut at
eight steps ended at an object from which the target is reachable, the response is
`truncated`. An object no root reaches lists no
path; an id or name nothing materialized is `NOT_FOUND`, a path through no object
`INVALID_ARGUMENT`, and a service without the capability `UNIMPLEMENTED`.

An error on one feature does not fail the call. `conformance/fixtures/cyclic.sysml` defines
`a = b + 1.0` and `b = a + 1.0`:

```console
$ … /Instantiate -d '{"modelHash":"5a85c5777a29e42321bdd577aa814c74c40914a569b354949b5f55be29a6c15b","symbolId":"Demo::Cyclic"}'
{"instance":{"id":"1","typeSymbolId":"Demo::Cyclic","featureValues":{"a":{"featureName":"a","error":"feature value Cyclic.a: feature value Cyclic.b: cyclic feature value dependency: Cyclic.a"},"b":{"featureName":"b","error":"feature value Cyclic.b: feature value Cyclic.a: cyclic feature value dependency: Cyclic.b"}}},"instances":[…]}
```

(`instances` repeats the root.) The Python client raises `FeatureValueError` when such a feature
is *read*, not when the instance is received; a hand-written client should likewise keep the
error beside the feature.

A symbol the model does not have is an in-body failure:

```console
$ … /Instantiate -d '{"modelHash":"5a85…c15b","symbolId":"Demo::Nope"}'
{"error":"symbol not found: Demo::Nope"}
```

### `ExecuteAction`

`inputs` is a map from parameter name to `Value`; `outputs` is the same shape back. A missing
input keeps its declared default:

```console
$ … /ExecuteAction -d '{"modelHash":"9794…8610","actionSymbolId":"Test::addFive","inputs":{"result":{"intValue":"10"}}}'
{"outputs":{"result":{"intValue":"15"}}}

$ … /ExecuteAction -d '{"modelHash":"9794…8610","actionSymbolId":"Test::addFive"}'
{"outputs":{"result":{"intValue":"5"}}}

$ … /ExecuteAction -d '{"modelHash":"9794…8610","actionSymbolId":"Test::noStart"}'
{"error":"action execution failed: initialize action: invalid action flow: no initial node found in action noStart: the successions form a cycle among the steps, leaving none to start at"}
```

An action with no outputs answers `{}` (captured for `action nop { first start; done;
succession first start then done; }`). The response carries no step trace; ordering-sensitive
behavior is pinned by the engine's golden traces, not exposed on this call. What it does carry
is every *choice point* the run made — a step in which the executor picked among alternatives
the library leaves unordered (several steppable tokens, several holding decision guards, two
tokens writing one feature in one step; see [Choice points](../guide/06-behavior.md)) — as an
`"info"` diagnostic located at the action, present beside `outputs` on success and beside
`error` when the run failed after making one (captured for `action tally { attribute leftCount :
Integer = 0; attribute rightCount : Integer = 0; first start; fork split; action left { assign
leftCount := leftCount + 1; } action right { assign rightCount := rightCount + 10; } join sync;
done; … }` with a succession from `split` to each branch and from each to `sync`, in `tally.sysml`):

```console
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally"}'
{"outputs":{"leftCount":{"intValue":"1"},"rightCount":{"intValue":"10"}},"diagnostics":[{"severity":"info","message":"choice point: step 3: tokens 2@left, 3@right (unordered; took 3@right first)","span":{"file":"tally.sysml","startLine":2,"startCol":2,"endLine":20,"endCol":2},"code":"choice-point"}]}
```

A run with no `diagnostics` had exactly one order to take. The order taken is the engine's fixed
rule, the same on every call, so the outputs are reproducible; the diagnostics say where another
rule would have been equally valid.

`schedule` asks for another rule. It names the *scheduling policy* the run resolves every choice
point under, spelled as `sysml -schedule` spells it: `"reverse"` is the fixed rule above and the
default (an empty or absent field), `"declared"` takes tokens in the order they were spawned and
guards and transitions in declaration order, and `"seed:<n>"` draws each pick from a pseudo-random
sequence the non-negative integer `n` fixes, so the same seed replays the same run on every
platform. The `took …` in each diagnostic is what the named policy took; the policy changes which
linearization runs, never whether a choice point is reported (captured for `Test::tally` above):

```console
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally","schedule":"declared"}'
{"outputs":{"leftCount":{"intValue":"1"},"rightCount":{"intValue":"10"}},"diagnostics":[{"severity":"info","message":"choice point: step 3: tokens 2@left, 3@right (unordered; took 2@left first)","span":{"file":"tally.sysml","startLine":2,"startCol":2,"endLine":20,"endCol":2},"code":"choice-point"}]}

$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally","schedule":"seed:abc"}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"invalid scheduling policy \"seed:abc\": seed \"abc\" is not a non-negative decimal integer"}
```

A spelling naming no policy — an unknown name, `seed` or `seed:` without a number, a negative or
non-decimal seed — is `INVALID_ARGUMENT` before the model is looked up, so a mistyped policy
never runs anything under the default. So is `"replay:<file>"`, which `sysml -schedule` accepts:
it follows a witness file of the caller's, which a request does not carry, and the service reads
no file of its own on a client's word. The field is advertised as the `schedule` capability: a
service withholding it refuses a non-empty `schedule` with `UNIMPLEMENTED`, and a service that
predates the field would drop it and run under the default, which is why every client this
repository ships checks the advertised list before sending one. `ExecuteState` and `RunAnalysis`
carry the same field with the same spellings and the same refusals.

`"explore"` is the fourth spelling, and it changes the shape of the answer: instead of one run's
`outputs` the response carries `outcomes`, every distinct outcome any linearization reaches, and
`exploration`, how the search ended. The service replays the run from the start, each replay a
fresh executor over the same lowered model, following the recorded choices of an earlier run up
to a frontier and taking the next untried alternative there — the first run's choice points each
varied once, earliest first, before any is varied twice — until no alternative is untried or a
budget is hit. Two runs that agree on the observables — an action's outputs — are
one outcome, with `linearizations` counting how many reached it, and `witness` the choice sequence
of one that did, one entry per choice point spelling the alternatives and the one taken. When a
committed run made a weighted model choice, `probability_range` carries the outcome's minimum and
maximum model-draw probability over schedulers; `probability` is the exact value when that range
is exact and is zero otherwise. Scheduling choices have no probability. If no weighted choice
occurred, neither field represents an outcome probability. A run failing after its initial model
behavior begins is an error outcome; a root executor creation failure or a pure structural
start-check failure before behavior runs is instead returned in the response's error field, with
no outcomes or exploration status. `diagnostics` is what that witness run noted, shaped as the
single-run `diagnostics` above.
Outcomes are in canonical order — by outputs, sorted by name and value — so the same model
answers the same list on every call (captured for `Test::tally` above and for `action race` with
three branches `a`, `b`, `c` each assigning `winner`):

```console
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally","schedule":"explore"}'
{"outcomes":[{"outputs":{"leftCount":{"intValue":"1"},"rightCount":{"intValue":"10"}},"linearizations":2,"witness":["step 3: 2@left first of 2@left, 3@right"],"diagnostics":[{"severity":"info","message":"choice point: step 3: tokens 2@left, 3@right (unordered; took 2@left first)","span":{"file":"tally.sysml",…},"code":"choice-point"}]}],"exploration":{"complete":true,"runs":2,"runsBudget":1024,"depthBudget":64}}

$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::race","schedule":"explore"}'
{"outcomes":[{"outputs":{"winner":{"intValue":"1"}},"linearizations":2,"witness":["step 3: 3@b first of 2@a, 3@b, 4@c","step 4: 4@c first of 2@a, 4@c"],"diagnostics":[…]},{"outputs":{"winner":{"intValue":"2"}},"linearizations":2,"witness":["step 3: 2@a first of 2@a, 3@b, 4@c","step 4: 4@c first of 3@b, 4@c"],"diagnostics":[…]},{"outputs":{"winner":{"intValue":"3"}},"linearizations":2,"witness":["step 3: 2@a first of 2@a, 3@b, 4@c","step 4: 3@b first of 3@b, 4@c"],"diagnostics":[…]}],"exploration":{"complete":true,"runs":6,"runsBudget":1024,"depthBudget":64}}
```

`tally`'s two orders write two different features, so its two linearizations are one outcome;
`race`'s six linearizations end on whichever branch ran last, three outcomes of two each. A run
with no choice point explores in exactly one run.

`exploration.complete` is true when every linearization within the budget was run, so
`outcomes` is the whole set. Probabilities are not schedule shares and need not sum to `1` across
the displayed outcome ranges: each range bounds model-weighted draws for one outcome over the
schedulers that resolve scheduling choices. An unweighted exploration has no outcome
probabilities. `failed_linearizations` counts the runs represented by runtime-error outcomes.
The budget is spelled in the policy, `"explore:runs=<n>,depth=<d>"`
in either order and either alone — `runs` bounds how many runs the search makes (default 1024),
`depth` how many choice points one run may resolve before the rest take their first alternative
(default 64). Hitting either ends the search with `complete` false and the budget named in
`budgetsHit` (`"runs"` before `"depth"` when both), the outcomes reached so far still listed and
`probabilitiesLowerBound` true only when the exploration is incomplete and has a weighted model
choice, since unexplored runs can only add to those model probabilities;
`runsBudget` and `depthBudget` echo the budget the search ran under. `coverage` (`Coverage`) is
what every run entered and took, not only the witness of each outcome: `states` and
`transitions`, each a `CoverageEntry` whose `path` is qualified by the instance that ran the
machine (`Cov::sys#1.m.run: s0 -> viaB`), whose `declaration` is qualified by the declaration
(`Cov::M::run::s0 -> viaB`), and whose `runs` counts the runs that did so. A budget hit is never an
error and never silent:

```console
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::race","schedule":"explore:runs=2"}'
{"outcomes":[{"outputs":{"winner":{"intValue":"2"}},"linearizations":1,"witness":[…],"diagnostics":[…]},{"outputs":{"winner":{"intValue":"3"}},"linearizations":1,"witness":[…],"diagnostics":[…]}],"exploration":{"runs":2,"budgetsHit":["runs"],"runsBudget":2,"depthBudget":64}}

$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::race","schedule":"explore:runs=0"}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"invalid scheduling policy \"explore:runs=0\": explore runs \"0\" is not a decimal integer of at least 1"}
```

A run that fails under exploration is an outcome of its own — `error` set on the outcome, its
`outputs` empty — beside the outcomes of the runs that completed, so a failure some orders reach
and others do not is reported as exactly that. The response's own `error` is reserved for what
stops exploring altogether, an unknown action or a model that will not build, and is then the
only field set, as for a single run. `outputs` and `diagnostics` on the response are empty under
`"explore"`; a client reading them would read an empty run, which is why every client this
repository ships gives exploration a method of its own. The policy is advertised as the
`schedule_explore` capability beside `schedule`: a service withholding it refuses an
`"explore…"` spelling with `UNIMPLEMENTED`.

An action that waits on time — `accept after 5 [SI::s]`, or `accept at` an instant — runs on
the simulation clock of its own run, which starts at 0 and advances to each instant a token
waits for; the call answers once the action completes, and `finalTime` is the clock when it
did, in seconds. It is omitted when the run ended at 0, so an action that never waited on time
answers as before (captured for `action delayed { attribute count : Integer = 0; first start;
then action wait accept after 5 [SI::s]; then action tick assign count := count + 1; then
done; }`):

```console
$ … /ExecuteAction -d '{"modelHash":"70ee…0c59","actionSymbolId":"Test::delayed"}'
{"outputs":{"count":{"intValue":"1"}},"finalTime":5}
```

The field is advertised as the `final_time` capability; a service withholding it answers
without the field whatever the run waited on. The response has no field to bound the clock: a
run goes as far as its waits require, and a machine that re-arms a timer forever ends at the
event budget, as it does on the CLI without `-advance`.

`performerSymbolId` names the object the action is performed by, as the CLI's
`sysml -action "<action> <object>"` does: empty, the action runs outside any object, as every
call above; the FQN of a part definition or usage creates an object of it for the run; and a
path from such a declaration through its parts — `Mission::mission.vehicle`,
`Fleet::convoy.escorts[2]` for a multi-valued part — creates the declaration and reaches the
object at the end of the path, so the action's `this` is a part *inside* its assembly and the
assembly's connectors reach it. When the object reached performs the action (`perform action
run : Run { in ref :>> ctx = this; }` in its definition, say), the call runs that performance
rather than a second one — with or without `advance`, which bounds how far it proceeds and
nothing else — so `outputs`, `performerAttributes` and the occurrence are the object's own;
`inputs` for it are refused, as its declaration binds its arguments, and an object performing
the action under two usages is refused as ambiguous. An object not performing the action
performs a fresh one, as an empty performer does outside any object. Each explored run creates the declaration anew, and each
outcome's `outputs` carry the object's attributes as the run left them under `this.`
(`this.pinged`), beside the action's own, so runs that differ only in what they left the
object holding are distinct outcomes. An executed run reports the same entries, spelled and
selected as an outcome's are, in `performerAttributes` (`this.pinged`), and keeps `outputs` the
action's output parameters alone; `performerAttributes` is empty without a performer and under
`"explore"`, whose outcomes carry them. A path that reaches no object is the call's `error` —
the feature the root has none of
(`Mission::mission has no feature "pilot"`), a multi-valued part named without an index
(`escorts of Fleet::convoy holds 2 objects: pick one by index`), an
index past the end (`escorts[3] names none`), an object named by id (`performer #1 names an
object by id, which a call creates none of`), or an unknown root (`symbol not found`) — or,
under `"explore"`, the one failed outcome of every run. Objects the service's own session holds
are never named this way: a request creates what it runs on. The field is advertised as the
`performer` capability: a service withholding it refuses a non-empty `performerSymbolId` with
`UNIMPLEMENTED`, since a service that predates the field would drop it and run the behavior
outside any object.

To report a decision's choice the engine reads the guards after the first holding one in a
preview it undoes, so reading them costs and changes nothing. One it cannot evaluate there is
not an alternative and not an error — a guard with no result is not true, so its branch is not
selected — and is reported as a second kind of `"info"` diagnostic, `guard not evaluable: …`,
naming the step, the decision, the branch by position and target, and the failure, located at
the guard (for `action route { attribute level : Integer = 75; … then decide select; if level > 50
then warn; if 1 / (level - 75) > 0 then alarm; … }`):

```console
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::route"}'
{"outputs":{"level":{"intValue":"75"},"handler":{"intValue":"1"}},"diagnostics":[{"severity":"info","message":"guard not evaluable: step 2: decision select branch 2->alarm: division by zero (not selected)","span":{"file":"tally.sysml","startLine":31,"startCol":10,"endLine":31,"endCol":30},"code":"guard-unevaluable"}]}
```

The first guard read is the run's own, not a preview: when it cannot be evaluated the run fails
with `error` as it always has, and no `guard not evaluable` diagnostic is added. The two kinds are
told apart by `code`, `"choice-point"` and `"guard-unevaluable"`; both are `"info"`, and the
message prefixes `choice point: ` and `guard not evaluable: ` are for reading, not branching.
`RunAnalysis` carries the same two codes for the runs it makes.

#### Run options

`ExecuteActionRequest` and `ExecuteStateRequest` take the run options the `sysml` command does,
under the flags' names. `advance` (`-advance`) is a simulated duration in seconds: the run is
started, the clock advanced by that much, and the response's `finalTime` reports where the
clock stopped; a run that has not completed by then is an in-body failure ("without
completing"), still carrying `finalTime`. Absent, the run goes to completion. `seed` (`-seed`)
seeds the model's own draws so a `RandomFunctions` call answers the same values each run, and
`draws` (`-draws`) chooses how those draws resolve: `random` (the default), or `min`, `max` or
`average`, which replace every draw by that moment of its distribution. `clockStep`
(`-clock-step`) is the tick, in seconds, the run's clock advances by, so an `accept after` wait
rounds up to the next tick; `0` is a continuous clock. A negative or non-finite `advance`, an
unknown `draws` or a bad `clockStep` is an `invalid_argument` naming the field; neither changes
the `schedule` the choice points resolve under.

### `ExecuteState`

`events` is an ordered list of event names to feed the machine after it enters; `statesVisited`
is the trace of state names in the order entered, and `finalContext` the machine's variables
when it stopped, as a name → `Value` map. `conformance/fixtures/behavior.sysml`'s `Test::Machine`
runs to `done` on its own:

```console
$ … /ExecuteState -d '{"modelHash":"9794…8610","stateMachineSymbolId":"Test::Machine"}'
{"statesVisited":["init","Running","done"]}
```

A machine with an attribute and event-triggered transitions (`state Controller { attribute
cycles : Integer = 0; entry; then off; state off; state on; transition first off accept start
do assign cycles := cycles + 1 then on; transition first on accept stop then off; }` in package
`Pump`):

```console
$ … /ExecuteState -d '{"modelHash":"449e7db990943f08c1918829b0c730cc9d9bf415b236a70debe93592d2477b6b","stateMachineSymbolId":"Pump::Controller","events":["start","stop","start"]}'
{"statesVisited":["off","on","off","on"],"finalContext":{"cycles":{"intValue":"2"}}}

$ … /ExecuteState -d '{"modelHash":"9794…8610","stateMachineSymbolId":"Test::NoMachine"}'
{"error":"state machine not found: Test::NoMachine"}
```

`finalContext` is absent when the machine has no variables; `statesVisited` lists a state each
time it is entered, so a state entered twice appears twice. `diagnostics` carries an `"info"`
entry for each event that enabled several transitions out of one state, located at the
transition taken, as `ExecuteAction`'s does for its steps, and a `guard not evaluable: <state> on
<trigger>: transition <n>-><target>: <failure> (not selected)` entry for a transition after the
first enabled one whose guard it could not evaluate in its preview. Both belong to the transition
that fires: a transition out of a parallel state that several of its regions select is one entry,
and a transition on a substate beating one on the state enclosing it is spec-defined order, so
nothing about the beaten state's transitions is reported. For `state def Hub { entry;
then Idle; state Idle; state A; state B; transition first Idle accept Go then A; transition first
Idle accept Go then B; }` in the same document:

```console
$ … /ExecuteState -d '{"modelHash":"81b1…73fc","stateMachineSymbolId":"Test::Hub","events":["Go"]}'
{"statesVisited":["Idle","A"],"diagnostics":[{"severity":"info","message":"choice point: state Idle on accept Go: transitions 1->A, 2->B (unordered; took 1->A)","span":{"file":"tally.sysml","startLine":25,"startCol":3,"endLine":26,"endCol":3},"code":"choice-point"}]}

$ … /ExecuteState -d '{"modelHash":"81b1…73fc","stateMachineSymbolId":"Test::Hub","events":["Go"],"schedule":"seed:1"}'
{"statesVisited":["Idle","B"],"diagnostics":[{"severity":"info","message":"choice point: state Idle on accept Go: transitions 1->A, 2->B (unordered; took 2->B)","span":{"file":"tally.sysml",…},"code":"choice-point"}]}
```

`schedule` names the policy the machine's transition picks — and the token order of any action
its states perform — are resolved under, as `ExecuteAction`'s does; the diagnostic's span moves
to the transition the policy took. Under `"explore"` the response carries `outcomes` and
`exploration` as `ExecuteAction`'s does, `statesVisited` and `finalContext` then empty; a state
machine's outcome is its `finalState`, its `statesVisited` and, as `outputs`, its final context,
so two runs resting in the same state by the same path with the same variables are one outcome:

```console
$ … /ExecuteState -d '{"modelHash":"81b1…73fc","stateMachineSymbolId":"Test::Hub","events":["Go"],"schedule":"explore"}'
{"outcomes":[{"finalState":"A","statesVisited":["Idle","A"],"linearizations":1,"witness":["state Idle on accept Go -> 1->A"],"diagnostics":[{"severity":"info","message":"choice point: state Idle on accept Go: transitions 1->A, 2->B (unordered; took 1->A)","span":{"file":"tally.sysml",…},"code":"choice-point"}]},{"finalState":"B","statesVisited":["Idle","B"],"linearizations":1,"witness":["state Idle on accept Go -> 2->B"],"diagnostics":[{"severity":"info","message":"choice point: state Idle on accept Go: transitions 1->A, 2->B (unordered; took 2->B)","span":{"file":"tally.sysml",…},"code":"choice-point"}]}],"exploration":{"complete":true,"runs":2,"runsBudget":1024,"depthBudget":64}}
```

`finalTime` is the machine's simulation clock when the run ended, in seconds from the 0 it
started at: the clock advances to each time-triggered transition (`accept after`, `accept at`)
the machine takes, and the field is omitted when it never moved. It is advertised as the
`final_time` capability, as `ExecuteAction`'s is (captured for `state Timer { attribute fired :
Integer = 0; entry; then armed; state armed; transition armed then done accept after 3 [SI::s]
do assign fired := fired + 1; }`):

```console
$ … /ExecuteState -d '{"modelHash":"70ee…0c59","stateMachineSymbolId":"Test::Timer"}'
{"statesVisited":["armed","done"],"finalContext":{"fired":{"intValue":"1"}},"finalTime":3}
```

`performerSymbolId` names the object the machine runs on, spelled as `ExecuteAction`'s is —
empty, a declaration's FQN, or a path from one such as `Mission::mission.vehicle` — with the
same errors. When the object reached exhibits the machine (`exhibit state modes;` in the part
definition of a vehicle, say), the call runs that exhibited machine rather than a second copy —
with or without `advance` — so the object's own transitions, the messages its ports receive over the assembly's
connectors and the features it assigns are the run's; a path reaching the exhibited usage itself
(`Mission::mission.vehicle.modes`, as the CLI's `-state` names it) runs that same machine, since the
object held under an `exhibit state` is the performance its owner runs; an object exhibiting the machine under
two usages is refused as ambiguous, since the call cannot tell which it means. An object not
exhibiting the machine performs a fresh one, as an empty performer does outside any object.
Either way the machine's guards, effects and state behaviors read and write the object's feature
values — by name in a machine the object's definition exhibits, through the `in ref` parameter
the object binds in a state definition run on it — and `finalContext` carries, besides the
machine's own data, every attribute the object holds when the run ends under `this.`
(`this.speed`, `this.seen`), so two objects of one definition differing in a feature value that
a guard reads rest in different states and report different contexts.
Under `"explore"` every run creates the object graph anew, so the machine is explored inside
its assembly and each outcome's `outputs` are the object's features as that run left them,
spelled as the executed `finalContext` spells them.

Set `trace: true` to include the run's documented `accept`, `send`, `transition`, `entry`,
`exit`, `do`, `choice` and `guard` records in `trace`, in execution order. Each record carries
its clock instant as `time`, along with fields relevant to its kind; `text` is the line the
trace prints. This transition record was captured from a traced `ExecuteState` call for
`Test::Machine` in `conformance/fixtures/behavior.sysml`:

```json
{"kind":"transition", "time":{"quantity":{"realMagnitude":0, "unit":"s", "unitTerm":{"scaleNum":1, "scaleDen":1, "factors":[{"unitId":"SI::second", "exponent":1}]}}}, "machine":"Machine", "from":"init", "to":"Running", "text":"transition: init -> Running"}
```

`ExecuteActionRequest.trace` (capability `action_trace`) answers the same `DocumentEvent`
records for an action: `step` (a token entering a node, `token` and `step` numbering it), `wait`
(an accept parked on `event`), `accept`, `send`, `decide` (`alternatives` and `taken`), `assign`
(`feature` and `value` as the engine wrote them) and `complete`. `ExecuteActionRequest.events`
posts signals or items to the performer in order, each once every token waits, so the accept
takes it on the next step; it needs `performer_symbol_id`, and a run whose tokens wait with no
event left fails with its partial trace. The `state_trace` capability is checked before sending
the option; a service that withholds it refuses the request with `UNIMPLEMENTED`. Tracing an explore schedule is `INVALID_ARGUMENT`,
because one trace describes one run, not the outcomes of several runs. A failed run still returns
the records made before failure. The response retains the newest records up to the service's
held-event limit and reports discarded older records as `traceDropped`; without the option,
`trace` and `traceDropped` are omitted.

### `EvaluateCalc`

`arguments` is a positional list of `Value`s matching the calc's `in` parameters in order.
`result` is the calc's value:

```console
$ … /EvaluateCalc -d '{"modelHash":"9794…8610","symbolId":"Demo::add","arguments":[{"intValue":"2"},{"realValue":3.5}]}'
{"result":{"realValue":5.5}}
```

A structured argument goes back the way it came — the same `array`, `vector` or
`vectorQuantity` body the service writes — and a malformed one is an in-body failure naming
the fault, not a value read some other way:

```console
$ … /EvaluateCalc -d '{"modelHash":"42cc…54b0","symbolId":"S::length","arguments":[{"vector":{"components":[{"realValue":3.0},{"realValue":4.0}]}}]}'
{"result":{"realValue":5}}

$ … /EvaluateCalc -d '{"modelHash":"42cc…54b0","symbolId":"S::length","arguments":[{"vector":{"components":[{"realValue":3.0},{"stringValue":"4"}]}}]}'
{"error":"calc argument could not be read: vector component is not a number: component 2", "failureReason":"FAILURE_REASON_EVALUATION"}
```

A `measurementRef` argument goes back the same way, and is read against the model's own unit
declaration when it names one — a named unit without its reduction, or with a reduction that
is not the declaration's, is the same kind of in-body failure:

```console
$ … /EvaluateCalc -d '{"modelHash":"5b0f…40d5","symbolId":"M::toUnit","arguments":[{"quantity":{"intMagnitude":"3","unit":"km","unitTerm":{"scaleNum":1000,"scaleDen":1,"factors":[{"unitId":"SI::metre","exponent":1}]}}},{"measurementRef":{"unit":"m","unitTerm":{"scaleNum":1,"scaleDen":1,"factors":[{"unitId":"SI::metre","exponent":1}]},"unitId":"SI::metre"}}]}'
{"result":{"quantity":{"realMagnitude":3000, "unit":"m", "unitTerm":{"scaleNum":1, "scaleDen":1, "factors":[{"unitId":"SI::metre", "exponent":1}]}}}}

$ … /EvaluateCalc -d '{"modelHash":"5b0f…40d5","symbolId":"M::toUnit","arguments":[…,{"measurementRef":{"unit":"m","unitId":"SI::metre"}}]}'
{"error":"calc argument could not be read: unit carries no reduction to base units: m", "failureReason":"FAILURE_REASON_EVALUATION"}

$ … /EvaluateCalc -d '{"modelHash":"5b0f…40d5","symbolId":"M::toUnit","arguments":[…,{"measurementRef":{"unit":"m","unitTerm":{"scaleNum":1000,"scaleDen":1,"factors":[{"unitId":"SI::metre","exponent":1}]},"unitId":"SI::metre"}}]}'
{"error":"calc argument could not be read: unit as written does not reduce to its unit_term: SI::metre reduces to metre, unit_term is 1000·metre", "failureReason":"FAILURE_REASON_EVALUATION"}
```

A `function` argument binds an `in calc` parameter to the calc it names, resolved against the
model, over no object. A name that is empty, names nothing, or names something that is not a
calc is an in-body failure, at any depth; so is any non-zero `selfId`, since the object it
named lived only in the response that sent it and no call can hold it again:

```console
$ … /EvaluateCalc -d '{"modelHash":"e587…f81e","symbolId":"F::apply","arguments":[{"function":{"calcId":"F::Sq"}},{"realValue":3.0}]}'
{"result":{"realValue":9}}

$ … /EvaluateCalc -d '{"modelHash":"e587…f81e","symbolId":"F::apply","arguments":[{"function":{"calcId":"F::holder"}},{"realValue":2.0}]}'
{"error":"calc argument could not be read: function names no calc of this model: F::holder is not a calc", "failureReason":"FAILURE_REASON_EVALUATION"}

$ … /EvaluateCalc -d '{"modelHash":"e587…f81e","symbolId":"F::apply","arguments":[{"function":{"calcId":"F::Scaler::scale","selfId":"3"}},{"realValue":2.0}]}'
{"error":"calc argument could not be read: function names no calc of this model: F::Scaler::scale: self_id 3 names no object of this call: an object lives only within the response that created it", "failureReason":"FAILURE_REASON_EVALUATION"}
```

A service without the `structured_values` capability refuses a structured argument, one
without `measurement_refs` a `measurementRef` argument, and one without `function_values` a
`function` argument, with the `unimplemented` Connect error instead, naming the capability;
check `GetServerInfo` first.

A `set` or a `tensorQuantity` argument goes back the same way; a set's members reach a
multi-valued parameter in canonical order, and a repeated member or a tensor whose components
do not fill its dimensions is the same kind of in-body failure:

```console
$ … /EvaluateCalc -d '{"modelHash":"c409…1a4a","symbolId":"T::members","arguments":[{"set":{"elements":[{"intValue":"7"},{"intValue":"5"},{"intValue":"9"}]}}]}'
{"result":{"intValue":"3"}}

$ … /EvaluateCalc -d '{"modelHash":"c409…1a4a","symbolId":"T::members","arguments":[{"set":{"elements":[{"intValue":"7"},{"intValue":"7"}]}}]}'
{"error":"calc argument could not be read: set element is repeated: element 2, 7","failureReason":"FAILURE_REASON_EVALUATION"}

$ … /EvaluateCalc -d '{"modelHash":"c409…1a4a","symbolId":"T::corner","arguments":[{"tensorQuantity":{"dimensions":["2","2","3"],"components":[…the eight above…]}}]}'
{"error":"calc argument could not be read: tensor components do not fill its dimensions: 8 elements under dimensions [2 2 3] (flattenedSize 12)","failureReason":"FAILURE_REASON_EVALUATION"}

$ … /EvaluateCalc -d '{"modelHash":"c409…1a4a","symbolId":"T::corner","arguments":[{"tensorQuantity":{"dimensions":["0"],"components":[]}}]}'
{"error":"calc argument could not be read: tensor dimension is not positive: dimension 1 is 0","failureReason":"FAILURE_REASON_EVALUATION"}
```

A service without `set_values` refuses a `set` argument and one without `tensor_values` a
`tensorQuantity` — nested anywhere in the argument — the same way, and answers a set or a
tensor it cannot send as the non-empty `null` arm (`{"null":"unsupported: set Set{1, 2, 3}"}`),
the rule under `null`.

A `metaobject` argument binds a parameter typed by a metaclass to the element its `elementId`
names, resolved against the model; the element's reflective features are then read there,
so only the identity crosses. `metaclassId` may be omitted — the service derives it — but
one that is present must be the metaclass that classifies the element: a name that is empty
or names nothing, or a metaclass the element is not an instance of, is an in-body failure,
at any depth, rather than a binding to a guess:

```console
$ … /EvaluateCalc -d '{"modelHash":"07a0…b5ca","symbolId":"Meta::nameOf","arguments":[{"metaobject":{"elementId":"Meta::seatBelt"}}]}'
{"result":{"stringValue":"seatBelt"}}

$ … /EvaluateCalc -d '{"modelHash":"07a0…b5ca","symbolId":"Meta::nameOf","arguments":[{"metaobject":{"elementId":"Meta::nobody"}}]}'
{"error":"calc argument could not be read: metaobject names no element of this model: Meta::nobody","failureReason":"FAILURE_REASON_EVALUATION"}

$ … /EvaluateCalc -d '{"modelHash":"07a0…b5ca","symbolId":"Meta::nameOf","arguments":[{"metaobject":{"elementId":"Meta::seatBelt","metaclassId":"SysML::Systems::PartDefinition"}}]}'
{"error":"calc argument could not be read: metaclass_id is not the element's metaclass: Meta::seatBelt is classified by SysML::Systems::PartUsage, not SysML::Systems::PartDefinition","failureReason":"FAILURE_REASON_EVALUATION"}
```

A service without `metaobject_values` refuses a `metaobject` argument — nested anywhere in
the argument — with the `unimplemented` Connect error naming the capability.

A calc *usage* whose output features are evaluated from its own members (no `arguments`)
answers them as `outputs`, a list of `{"name":…,"value":<Value>}` in declaration order, in
place of `result`; a client reads whichever of the two is present. A symbol that is not a calc
is the `FAILURE_REASON_WRONG_KIND` failure shown under [In-body failures](#in-body-failures);
for an analysis case the message says to use `RunAnalysis`.

### `RunAnalysis`

`symbolId` names an analysis or verification definition or usage. `subjectSymbolId` optionally names a part or
usage to instantiate as the case's `subject`, as `VerifyRequirement` takes one; a usage that
binds its own subject (`subject s = ship;`) needs none, and a definition or unbinding usage
run without one is an in-body failure naming the subject. The subject may also be a path from
a declaration into its parts, `Fleet::convoy.lead` or `Fleet::convoy.escorts[2]`, spelled and
refused as `ExecuteAction`'s `performerSymbolId` is: the declaration is instantiated and the
case runs on the object the path reaches, so `instances` opens with that object and its
features read as its assembly binds them. `arguments` is a positional list of
`Value`s for the case's other `in` parameters in declaration order and `namedArguments` binds
them by name; a parameter left without a value or default is an in-body failure. `outputs`
are the case's `out` and `return` values as `EvaluateCalc` reports a usage's, a returned value
with no name under `result`; `verdicts` is one `Verdict` per `objective` and per
`assert constraint` in the body, in that order, with `kind` `objective` or `assertion`,
`holds` for a satisfied one, `condition` for one that is not, and `error` for one that could
not be decided; `verificationVerdicts` is the verdict the body of a verification case produced
and the verdict of each verification case it performs (see below); `evaluations` is each
application the run made of one of the case's own calcs as a value — a trade study's scoring of
each alternative (see [Case evaluations](#case-evaluations)); `instances` is the subject's
object graph when one was instantiated, and every object an evaluation is of:

```console
$ … /RunAnalysis -d '{"modelHash":"e43c…9a2a","symbolId":"An::shipCost"}'
{"outputs":[{"name":"total","value":{"realValue":12}}],"verdicts":[{"kind":"objective","elementId":"An::CostAnalysis::affordable","element":"affordable","holds":true}]}

$ … /RunAnalysis -d '{"modelHash":"e43c…9a2a","symbolId":"An::CostAnalysis","subjectSymbolId":"An::barge","namedArguments":{"limit":{"realValue":50.0}}}'
{"outputs":[{"name":"total","value":{"realValue":37}}],"verdicts":[{"kind":"objective","elementId":"An::CostAnalysis::affordable","element":"affordable","holds":true,"instanceId":"1","instanceTypeId":"An::barge"}],"instances":[{"id":"1","typeSymbolId":"An::barge",…}]}

$ … /RunAnalysis -d '{"modelHash":"e43c…9a2a","symbolId":"An::CostAnalysis"}'
{"error":"analysis run failed: analysis An::CostAnalysis: s subject is unbound: bind it (`subject s = <element>`) or run it on an object","failureReason":"FAILURE_REASON_EVALUATION"}

$ … /RunAnalysis -d '{"modelHash":"e43c…9a2a","symbolId":"An::Ship"}'
{"error":"not an analysis case: An::Ship is a part def, not an analysis or verification case definition or usage","failureReason":"FAILURE_REASON_WRONG_KIND"}

$ … /RunAnalysis -d '{"modelHash":"96c9…994d","symbolId":"Ver::checkSlow"}'
{"outputs":[{"name":"result","value":{"enumLiteral":{"literalId":"VerificationCases::VerdictKind::pass","enumerationId":"VerificationCases::VerdictKind","name":"VerdictKind::pass"}}}],"verdicts":[{"kind":"objective","element":"obj","holds":true,"instanceId":"1","instanceTypeId":"Ver::slow"}],"instances":[…],"verificationVerdicts":[{"caseId":"Ver::checkSlow","kind":"pass"}]}
```

#### Tool dry run

`toolDryRun` (`-tool-dry-run`) runs the case up to its first `ToolExecution`-annotated action
and, instead of starting the external tool, answers the call that would have been made as a
`ToolDryRun`: `action`, `tool`, `version`, `manifest` and `executable` identify the step and the
manifest entry it resolved to; `protocol`, `args`, `env`, `cwd`, `stdin`, `stdinData`,
`inputFile`, `outputDir`, `inputs` and `outputs` are the process and the values it would have
been handed and asked for; `replySource` says where the reply would be read from; and `lines`
is the preview the command prints. A dry run reaches no result, so `outputs`, `verdicts` and
`instances` stay empty; a case that calls no tool is an in-body failure saying so, and a dry
run under `"schedule":"explore"` or `"engine":"explore"` is an `invalid_argument`, since an
exploration runs the case many times.

### Verification verdicts

`verificationVerdicts` is a repeated `VerificationVerdict` on `RunAnalysisResponse`,
`VerifyRequirementResponse` and `VerifySatisfactionResponse`, advertised as the
`verification_verdicts` capability. It reports what running the body of a verification case
answered, beside — never instead of — the requirement and objective verdicts the same response
already carries: a service withholding the capability omits the field, and the other fields mean
what they meant before.

- `caseId` — the qualified name of the verification case that ran.
- `kind` — `"pass"` or `"fail"` as the library's own `VerificationCases::PassIf` calculation
  computed it, the `VerdictKind` literal a body bound directly, `"inconclusive"` for a body that
  produced no verdict value or for a case a definition owns that no object of the definition
  exists to run on, or `"error"` for a body whose run could not be carried out.
- `detail` — why an `error` or `inconclusive` verdict decided nothing, carrying the message the
  run failed with (`needs an object of <Definition>: none is instantiated` for a case with no
  object to run on, which then carries no `instanceId`). Omitted for `pass` and `fail`.
- `subcase` — true for a verification case the run performed as a step of another. The library
  states no roll-up of a subcase's verdict into its parent's, so each is reported on its own.
- `requirementId` — the qualified name of the requirement the case was reported for, the one its
  objective verifies. A `VerifySatisfaction` response covering several requirements is kept apart
  by it: a `"satisfy"` verdict carries the same `requirementId` for the requirement it asserts
  satisfied, so a client reads a verdict's own cases rather than the whole response's. Empty for a
  case run for itself by `RunAnalysis`, and for a requirement no qualified name reaches.
- `instanceId` — the ID of the object the case ran on as its owner, resolving to an entry of the
  response's `instances`. A case a part definition owns runs once per object of that definition,
  so two verdicts of one `caseId` are told apart by it. `0` (omitted in JSON) when the case ran on
  no object.
- `instanceTypeId` — the qualified name of that object's type, as the `instanceTypeId` of a
  requirement verdict spells it, for naming the object in a report. Empty with `instanceId` `0`.

```console
$ … /VerifyRequirement -d '{"modelHash":"96c9…994d","symbolId":"Ver::touchdown"}'
{"verdict":{"kind":"requirement","elementId":"Ver::touchdown","element":"Ver::touchdown","holds":true},"verificationVerdicts":[{"caseId":"Ver::checkSlow","kind":"pass"},{"caseId":"Ver::checkFast","kind":"fail"}]}
```

### Case evaluations

`evaluations` is a repeated `CaseEvaluation` on `RunAnalysisResponse` and on each `RunSweep`
`SweepRow`, advertised as the `case_evaluations` capability. A `TradeStudies::TradeStudy`
evaluates its `evaluationFunction` once per alternative the subject lists — the library's
`minimize`/`maximize` and `selectOne` bodies apply the calc held in `eval` — and each such
application is reported, in subject order, once per distinct argument. A service withholding the
capability omits the field; the `outputs` and `verdicts` beside it mean what they meant before.

- `functionId` — the qualified name of the calc applied, the case's `evaluationFunction`.
- `arguments` — what it was applied to, as `Value`s in parameter order (a named argument at
  its parameter's position, `null` for a parameter left to the calc before a later one); an
  alternative is an `instanceId` resolving in the response's `instances`.
- `result` — what it computed. Absent when `error` says why nothing was.
- `error` — why the evaluation computed nothing (a division by zero, a feature with no value,
  a calc with no return expression). The objective is then `undecided` with the same reason and
  nothing is `selected`.
- `selected` — true for the evaluation whose argument the library's `selectOne` picked and the
  case returned: the first alternative whose score is `best`. A case whose result merely equals
  an argument of an evaluation, with no `selectOne` picking it, selects nothing.
- `tied` — true for a later evaluation that computed what the selected one did without being
  selected, so a tie is visible rather than a silent first-wins.

```console
$ … /RunAnalysis -d '{"modelHash":"3f1a…50c2","symbolId":"Trade::lightest"}'
{"outputs":[{"name":"selectedAlternative","value":{"instanceId":"2"}}],
 "verdicts":[{"kind":"objective","elementId":"Trade::lightest::tradeStudyObjective","element":"tradeStudyObjective","holds":true}],
 "instances":[{"id":"1","typeSymbolId":"Trade::a",…},{"id":"2","typeSymbolId":"Trade::b",…},{"id":"3","typeSymbolId":"Trade::c",…}],
 "evaluations":[{"functionId":"Trade::lightest::evaluationFunction","arguments":[{"instanceId":"1"}],"result":{"realValue":30}},
                {"functionId":"Trade::lightest::evaluationFunction","arguments":[{"instanceId":"2"}],"result":{"realValue":10},"selected":true},
                {"functionId":"Trade::lightest::evaluationFunction","arguments":[{"instanceId":"3"}],"result":{"realValue":10},"tied":true}]}
```

A run whose `evaluationFunction` fails for one alternative answers `error` with
`FAILURE_REASON_EVALUATION` naming the case, as any failing step does — and, under this
capability, beside it the `evaluations` the run made (the earlier ones with their results, the
failing one with its `error`), the objective as a `Verdict` with `error`, and the `instances`
they are of; `outputs` is empty, nothing having been selected. A service without the capability
answers the error alone.

A step that fails, a body that deadlocks or exhausts its step budget and a case that runs itself are
`FAILURE_REASON_EVALUATION` failures naming the case. Structured and complex arguments are
capability-gated as `EvaluateCalc`'s are. The choice points the case's steps made are its
`diagnostics`, shaped as `ExecuteAction`'s, and `schedule` names the policy the actions the case
performs resolve them under, with `ExecuteAction`'s spellings and refusals. Under `"explore"`
the response carries `outcomes` and `exploration` as `ExecuteAction`'s does, `outputs`,
`verdicts`, `instances` and `verificationVerdicts` then empty. A case's outcome is its outputs
and its verdicts together, the verdicts as strings among the outcome's `outputs` named
`"objective <name>"`, `"assertion <name>"` and `"verdict <case>"` — `"satisfied"`, `"not
satisfied: <condition>"` or `"undecided: <error>"` — so an objective that holds under one order
and not another is two outcomes, which is what exploring a case is for (for `analysis def Raced {
out winner : Integer; perform action race : Race; objective obj { require constraint { winner > 1
} } return : Integer = winner; }` where `Race` forks two branches assigning `winner`):

```console
$ … /RunAnalysis -d '{"modelHash":"9f2c…41aa","symbolId":"Test::Raced","schedule":"explore"}'
{"outcomes":[{"outputs":{"objective obj":{"stringValue":"not satisfied: winner > 1"},"result":{"intValue":"1"},"winner":{"intValue":"1"}},"linearizations":1,"witness":["step 3: 3@b first of 2@a, 3@b"],"diagnostics":[…]},{"outputs":{"objective obj":{"stringValue":"satisfied"},"result":{"intValue":"2"},"winner":{"intValue":"2"}},"linearizations":1,"witness":["step 3: 2@a first of 2@a, 3@b"],"diagnostics":[…]}],"exploration":{"complete":true,"runs":2,"runsBudget":1024,"depthBudget":64}}
```

### `RunSweep`

The same request as `RunAnalysis` — `symbolId` naming an analysis case **or** a calc,
`subjectSymbolId`, `arguments`, `namedArguments` — plus `ranges`, and `samples` with `seed`.
Each `SweepRange` names a `parameter` the target declares and the arguments do not bind, with
`start`, `end` and an optional `step` as `Value`s; `end` is included where the step lands on it,
a range between whole numbers with no step steps by one, and one with a fractional endpoint and
no step is refused. The row values are typed by the parameter each range binds, not by the
`Value`s the range is written with: a `Real` parameter swept over Integer `start`/`end` binds
and reports Reals, an `Integer` one over integral Reals binds Integers, and a range the
parameter's type cannot take is refused before any row runs — an Integer `start`, `end` or
`step` a Real does not hold without rounding, or a step the reals cannot tell rows apart by,
included where the range is read as reals. The response's `parameters` are
the swept parameters in request order and `rows` is one run each, in lexicographic order over
them (the first range varying slowest). A row carries the
`inputs` bound for that run, its `outputs` (a calc's returned value under `result`, as
`EvaluateCalc` reports it), its `verdicts` where the case has an objective, its `evaluations`
where the case applied one of its own calcs as a value ([Case evaluations](#case-evaluations), a
trade study's scoring of each alternative), and `elapsedMicros`, the wall time of that run in
microseconds — the one fixed unit, absent for a run that took under one:

```console
$ … /RunSweep -d '{"modelHash":"a6dc…4849","symbolId":"An::Fall","ranges":[{"parameter":"t","start":{"realValue":0.0},"end":{"realValue":2.0},"step":{"realValue":1.0}}]}'
{"rows":[{"inputs":[{"name":"t","value":{"realValue":0}}],"outputs":[{"name":"result","value":{"realValue":0}}],"elapsedMicros":"31"},
         {"inputs":[{"name":"t","value":{"realValue":1}}],"outputs":[{"name":"result","value":{"realValue":4.905}}]},
         {"inputs":[{"name":"t","value":{"realValue":2}}],"outputs":[{"name":"result","value":{"realValue":19.62}}]}],
 "parameters":["t"]}

$ … /RunSweep -d '{"modelHash":"a6dc…4849","symbolId":"An::CostAnalysis","subjectSymbolId":"An::barge","ranges":[{"parameter":"tax","start":{"realValue":0.0},"end":{"realValue":1.0},"step":{"realValue":0.5}}]}'
{"rows":[…,
         {"inputs":[{"name":"tax","value":{"realValue":1}}],"outputs":[{"name":"total","value":{"realValue":10}}],
          "verdicts":[{"kind":"objective","element":"obj","condition":"total <= 8.0","instanceId":"1","instanceTypeId":"An::barge"}],"elapsedMicros":"16"}],
 "parameters":["tax"],
 "instances":[{"id":"1","typeSymbolId":"An::barge","featureValues":{"cost":{"featureName":"cost","value":{"realValue":5}}}}]}
```

A row carries no `verificationVerdicts`, so a verification case is refused with
`FAILURE_REASON_WRONG_KIND` rather than swept as an analysis case; run one through `RunAnalysis`,
which reports the verdict of its body.

`instances` carries every object a row's verdict or evaluation is about, each once over the whole
table, so a verdict's `instanceId` and an evaluation's `arguments` resolve there as they do in a
`RunAnalysis` response — a client can read what made a row fail. Each row runs in a context of
its own, so the objects of one row are not those of another even when they are of the same
declaration: a row's objects are numbered after the rows before it (the first row's from `1`, as a
`RunAnalysis` response numbers them), and a row's references resolve to the objects that row made,
holding what that row's run left in them.

A run that fails is a row of its own, carrying `error` and `failureReason` in place of its
`outputs`, and the runs after it are still made. The row keeps what the run decided before
failing: a trade study whose `evaluationFunction` fails for one alternative carries the
evaluations it made — the earlier ones with their results, the failing one with its `error` —
and its objective as a `Verdict` with `error`, none `selected`:

```console
$ … /RunSweep -d '{"modelHash":"ed8c…2ec4","symbolId":"An::Ratio","namedArguments":{"a":{"realValue":4.0}},"ranges":[{"parameter":"b","start":{"intValue":"-1"},"end":{"intValue":"1"}}]}'
{"rows":[{"inputs":[{"name":"b","value":{"intValue":"-1"}}],"outputs":[{"name":"result","value":{"realValue":-4}}],"elapsedMicros":"18"},
         {"inputs":[{"name":"b","value":{"intValue":"0"}}],"elapsedMicros":"6",
          "error":"calc An::Ratio: evaluating the returned expression: division by zero","failureReason":"FAILURE_REASON_EVALUATION"},
         {"inputs":[{"name":"b","value":{"intValue":"1"}}],"outputs":[{"name":"result","value":{"realValue":4}}]}],
 "parameters":["b"]}
```

`samples` draws that many values for each range instead of running every value of it —
uniformly, in draw order, from `math/rand/v2`'s `PCG` seeded from `seed`, which the response
echoes alongside `sampled` — and a sampled range needs no `step`:

```console
$ … /RunSweep -d '{"modelHash":"a6dc…4849","symbolId":"An::Fall","ranges":[{"parameter":"t","start":{"realValue":0.0},"end":{"realValue":10.0}}],"samples":"2","seed":"42"}'
{"rows":[{"inputs":[{"name":"t","value":{"realValue":8.254725069980449}}],"outputs":[{"name":"result","value":{"realValue":334.22908373662705}}],"elapsedMicros":"7"},
         {"inputs":[{"name":"t","value":{"realValue":0.4281995136143024}}],"outputs":[{"name":"result","value":{"realValue":0.8993554090689709}}]}],
 "parameters":["t"],"sampled":true,"seed":"42"}
```

A request the plan cannot be built from answers `error` with no rows at all, so a client
distinguishes a refused plan from a table of failed runs by whether `rows` is present: a symbol
that is neither an analysis case nor a calc is `FAILURE_REASON_WRONG_KIND`, and a missing range,
a step of zero, a step whose sign never reaches `end`, incompatible units, an undeclared
parameter, the case's subject, one the arguments bind — by name or by holding the position it is
bound from — a negative `samples`, and a plan asking for more runs than
`OPENSYSML_MAX_SWEEP_RUNS` allows are `FAILURE_REASON_EVALUATION`. `seed` is a `uint64` with no
unset state on the wire, so a request that draws without naming one draws from seed 0 (where the
CLI's `-samples` requires `-seed` rather than choosing a seed for you):

```console
$ … /RunSweep -d '{"modelHash":"a6dc…4849","symbolId":"An::Ship","ranges":[{"parameter":"t","start":{"intValue":"1"},"end":{"intValue":"3"}}]}'
{"error":"not a calc: An::Ship declares neither an analysis case nor a calc","failureReason":"FAILURE_REASON_WRONG_KIND"}

$ … /RunSweep -d '{"modelHash":"a6dc…4849","symbolId":"An::Fall"}'
{"error":"no sweep range: name a range as <parameter>=<from>..<to>","failureReason":"FAILURE_REASON_EVALUATION"}
```

A call the client cancels or lets time out stops between runs: the next run is not started, the
call fails with that status rather than answering a partial table, and the model it held is
released.

### `Evaluate`

Not a behavior in the model, but the general-purpose call that every other example here uses:
`expression` is SysML expression text, `contextSymbolId` names the scope names resolve in, and
`subjectSymbolId` optionally names a usage whose features the expression may refer to directly
(the expression is evaluated *on* an instance of it):

```console
$ … /Evaluate -d '{"modelHash":"5a89…277c","expression":"mass * 2.0","subjectSymbolId":"Rover::rover"}'
{"result":{"realValue":40}}
```

The response is `result` **or** `error` (with `diagnostics` when the expression did not parse),
never both.

### `VerifyConstraint`, `VerifyRequirement`, `VerifySatisfaction` and the `Verdict` shape

`VerifyConstraint` and `VerifyRequirement` take a `symbolId` and an optional `subjectSymbolId`
— the usage to instantiate and evaluate the condition against — and return one `verdict`.
`VerifySatisfaction` takes the element that owns `satisfy` assertions and returns `verdicts`,
one per assertion. All three return the `instances` they built, in the same shape as
`Instantiate`.

With no `subjectSymbolId`, the three — and `RunAnalysis` — evaluate over the objects
`Instantiate` holds for the model, as the REPL's `%constraint`, `%requirement`, `%satisfy` and
`%analysis` are about the objects a session holds: a constraint or requirement a definition owns
is checked on the one held object carrying it (ambiguous over several, as the REPL answers —
objects of distinct declarations and the two objects one declaration instantiated twice leaves
alike, the one the name no longer denotes named `Bolt #1 (displaced from b)`), a verification
case a definition owns runs once per held object of that definition — every live one, the object
a second `Instantiate` of its name displaced included — and reports a `verificationVerdicts`
entry about each, naming the object by `instanceId`, and a `satisfy`
a definition states is decided per held object with `instancePath` spelling the object's path
from the root it was instantiated under (`cheap[2]`; `small` or `smalls[2]` for an object a
subsetting usage declares), as `ValidateInstance` spells it. The
`instances` carry every object a verdict is about. With nothing held, the answer is about
declared defaults, and a definition-owned case is `inconclusive` asking for an object. A
sweep that would make one more object than `OPENSYSML_GRPC_MAX_HELD_OBJECTS` allows is
`RESOURCE_EXHAUSTED`, as `Instantiate` is, and leaves the population as it was. A `RunAnalysis`
tool dry run over the held population leaves it as it was too: the preview's writes are undone
and the runner it previewed with is taken off. An `explore` schedule is the exception: its runs
are made on runtimes of their own, one per linearization, holding nothing, as the REPL's are.

A constraint or requirement whose condition reads `in` parameters takes their values on the
request: `arguments` is a positional list bound in declaration order, `namedArguments` binds by
parameter name, and the two may be mixed, as `RunAnalysis` binds a case's inputs; the values are
`Value` messages in the shapes [`EvaluateCalc`](#evaluatecalc) accepts. A name no parameter has,
more positional values than parameters, a parameter left without a value, default or same-named value on the checked object, or a value
not of the parameter's type is an undecided `verdict` whose `error` names it, not a status error.
Only the evaluate question takes them: `holds` and `satisfiable` with any argument are
`INVALID_ARGUMENT`, since the solver chooses the free features' values. The service advertises the
fields as the `verification_arguments` capability; a request binding none needs it no more than
before.

```console
$ … /VerifyRequirement -d '{"modelHash":"9794…8610","symbolId":"Demo::Under","subjectSymbolId":"Demo::sedan","namedArguments":{"limit":{"intValue":"5"}}}'
{"verdict":{"kind":"requirement","elementId":"Demo::Under","element":"Demo::Under","holds":true,"instanceId":"1","instanceTypeId":"Demo::sedan"},"instances":[…]}
```

```console
$ … /VerifyConstraint -d '{"modelHash":"9794…8610","symbolId":"Demo::Vehicle::massPositive"}'
{"verdict":{"kind":"constraint","elementId":"Demo::Vehicle::massPositive","element":"Demo::Vehicle::massPositive","holds":true}}

$ … /VerifyRequirement -d '{"modelHash":"9794…8610","symbolId":"Demo::Vehicle::lightEnough"}'
{"verdict":{"kind":"requirement","elementId":"Demo::Vehicle::lightEnough","element":"Demo::Vehicle::lightEnough","holds":true}}

$ … /VerifyConstraint -d '{"modelHash":"9794…8610","symbolId":"Demo::Vehicle::massLight","subjectSymbolId":"Demo::sedan"}'
```

```json
{
  "verdict": {
    "kind": "constraint",
    "elementId": "Demo::Vehicle::massLight",
    "element": "Demo::Vehicle::massLight",
    "condition": "mass < 100.0",
    "instanceId": "1",
    "instanceTypeId": "Demo::sedan"
  },
  "instances": [
    {
      "id": "1",
      "typeSymbolId": "Demo::sedan",
      "featureValues": {
        "lightEnough":  {"featureName": "lightEnough"},
        "mass":         {"featureName": "mass", "value": {"realValue": 1200}, "materialized": true},
        "massLight":    {"featureName": "massLight"},
        "massPositive": {"featureName": "massPositive"},
        "tiny":         {"featureName": "tiny"}
      }
    }
  ]
}
```

Reading a `Verdict`:

- `kind` — `"constraint"`, `"requirement"` or `"satisfy"`; `"object"` for the summary
  [`ValidateInstance`](#validateinstance-every-assertion-about-one-object) returns about a
  whole object.
- `holds` — the verdict. **Omitted when false** (the default-omission rule), so the second and
  third examples say `massLight` does *not* hold for `sedan` (1200 is not < 100) by having no
  `holds` key. Read it with a default of `false`, and read `error` first.
- `error` — non-empty when the condition **could not be evaluated**. Then `holds` is
  meaningless (and absent), and the answer is neither true nor false: it is a failure. The
  Python client raises for it rather than returning `False`. `failureReason` accompanies it
  when the reason is classified:

  ```console
  $ … /VerifyConstraint -d '{"modelHash":"9794…8610","symbolId":"Demo::sedan"}'
  {"verdict":{"kind":"constraint","elementId":"Demo::sedan","element":"Demo::sedan","error":"not a constraint: sedan is a part usage, not a constraint definition or usage","failureReason":"FAILURE_REASON_WRONG_KIND"}}
  ```

  So: `holds:true` → holds; no `holds`, no `error` → does not hold; `error` → could not decide.
- `condition` — the condition that evaluated to false, as written, when the runtime can name
  one; omitted when the verdict holds, when the false verdict is not attributed to a single
  condition, and on a failure (the `not a constraint` example above has none).
- `elementId` / `element` — the id of the element checked, and its display form. For a
  `satisfy` assertion, which has no name, `elementId` is absent and `element` is the assertion
  text.
- `instanceId` / `instanceTypeId` — the instance the condition was evaluated on, a key into
  `instances`, and its type. Absent when no subject was instantiated (the first two examples,
  which evaluated against the definition's own defaults).
- `requirementId` — for a `"satisfy"` verdict, the qualified name of the requirement it asserts
  satisfied, which is the key into the response's `verificationVerdicts`. Absent for every other
  kind, and for a requirement no qualified name reaches.

`VerifySatisfaction` over `Demo::analysis`, which asserts `massLimit` (max 2000) and `massTiny`
(max 10) are satisfied by `sedan`:

```console
$ … /VerifySatisfaction -d '{"modelHash":"9794…8610","symbolId":"Demo::analysis"}'
```

```json
{
  "verdicts": [
    {"kind": "satisfy", "element": "satisfy massLimit by sedan", "holds": true, "instanceId": "1", "instanceTypeId": "Demo::sedan"},
    {"kind": "satisfy", "element": "satisfy massTiny by sedan", "condition": "vehicle.mass <= maxMass", "instanceId": "2", "instanceTypeId": "Demo::sedan"}
  ],
  "instances": [ … ]
}
```

(`instances` holds `"id":"1"` and `"id":"2"`, both `Demo::sedan` with the feature values shown
for the `massLight` example.) Each assertion instantiated its own `sedan`, hence two ids; the
second verdict has no `holds` and no `error`, so it is a real *false*.

### `ValidateInstance`: every assertion about one object

`ValidateInstance` takes the `symbolId` of a part definition or usage, builds one object of it,
and answers every assertion about that object and the objects it holds — each `assert
constraint` the carrier's type declares or inherits, each requirement usage it carries, and each
`satisfy` assertion whose subject is an object in the tree — as `sysml -validate=<object>` and
the REPL's `%validate` do. It is served under the `verification` capability and takes the
`engine` field. The response is `verdicts`, one per (assertion, object), root first and then
each held object in traversal order; `summary`, one `Verdict` of kind `"object"` about the root;
`instances`, the whole tree in the shape `Instantiate` returns; `bounded`, present and `true`
when the walk stopped at its depth bound before reaching every held object; and
`verificationVerdicts` as `VerifyRequirement` returns them, keyed by `requirementId`. Over a
model whose `Car` asserts `massOk`, carries requirement `light` (mass < 1000, violated by its
1500 kg) and holds two `wheels : Wheel[2]` at 20 psi against `Wheel`'s asserted `pressure >=
30.0`, with the standing fields omitted:

```console
$ … /ValidateInstance -d '{"modelHash":"6457…5d2c","symbolId":"Fleet::car"}'
```

```json
{
  "verdicts": [
    {"kind": "constraint", "elementId": "Fleet::Car::massOk", "element": "assert constraint massOk", "holds": true, "instanceId": "1", "instanceTypeId": "Fleet::car"},
    {"kind": "requirement", "elementId": "Fleet::Car::light", "element": "requirement light", "condition": "mass < 1000.0", "instanceId": "1", "instanceTypeId": "Fleet::car", "requirementId": "Fleet::Car::light"},
    {"kind": "constraint", "elementId": "Fleet::Wheel::pressureOk", "element": "assert constraint pressureOk", "condition": "pressure >= 30.0", "instanceId": "2", "instanceTypeId": "Fleet::Car::wheels", "instancePath": "wheels[1]"},
    {"kind": "constraint", "elementId": "Fleet::Wheel::pressureOk", "element": "assert constraint pressureOk", "condition": "pressure >= 30.0", "instanceId": "3", "instanceTypeId": "Fleet::Car::wheels", "instancePath": "wheels[2]"}
  ],
  "summary": {"kind": "object", "elementId": "Fleet::car", "element": "Fleet::car", "instanceId": "1", "instanceTypeId": "Fleet::car"},
  "instances": [ … ]
}
```

Reading the response:

- Each of `verdicts` is a `Verdict` as above — `kind` is `"constraint"`, `"requirement"` or
  `"satisfy"`, and `holds`, `condition`, `error`, `requirementId` mean what they mean there — with
  one field more: `instancePath`, where the object the verdict is about sits under the root
  (`engine.injector`, `wheels[2]`, one-based for a collection element; `small` or `smalls[2]`
  for an object a subsetting usage declares, never its position in the collection it subsets),
  omitted for the root itself. `instanceId` keys the object in `instances` as before.
- `summary.holds` is `true` only when every verdict holds **and** the walk was complete. The
  example's summary has no `holds` and no `error`, so the object is a real *not valid*: three
  of its four assertions are false. A summary with `error` is undecided — an assertion that could
  not be evaluated, a feature value that could not be read, or a walk that `bounded` cut short —
  and says which; read `error` first, as for any `Verdict`.
- An object no assertion is about decides nothing: `verdicts` is empty and `summary` neither
  holds nor is a violation — its `error` says the object `states no assertion to validate`, with
  `failureReason` `FAILURE_REASON_EVALUATION` — so an object is shown valid only by at least one
  assertion holding.
- An unknown `symbolId`, or one that has no object to validate — a package, an attribute, an
  enumeration — is answered in-band, as the other verification calls answer it: `error` at the
  top level with `failureReason` (`FAILURE_REASON_WRONG_KIND` for a symbol of the wrong kind),
  and no `verdicts` or `summary`:

  ```console
  $ … /ValidateInstance -d '{"modelHash":"6457…5d2c","symbolId":"Fleet::nope"}'
  {"error":"symbol not found: Fleet::nope","failureReason":"FAILURE_REASON_EVALUATION"}
  $ … /ValidateInstance -d '{"modelHash":"6457…5d2c","symbolId":"Fleet"}'
  {"error":"not an object: Fleet is a package, which has no object to validate","failureReason":"FAILURE_REASON_WRONG_KIND"}
  ```

A constraint declared without `assert` is not swept — it is what `VerifyConstraint` is for.

### `ListEngines`, the `engine` field and the standing of an answer

Every verification, analysis and sweep request is a question put to an analysis engine, and a
service advertising the `engines` capability reports which engine answered and how strongly.
The transcripts above omit these fields for brevity; a service with the capability adds them.

`ListEngines` takes a request with one optional field, `probe` (`-probe`): set, the service
starts each external engine it serves and checks its handshake, so `ready` and `unavailable`
report what the process actually said rather than whether it was found. Unset, it returns the engines of the build in name order, each
an `EngineInfo`: `name`; `authority`, the strongest evidence the engine can produce, spelled as
`strength` is; `answers`, the question kinds it covers; `bounds`, the budget bounds it takes;
`process` and `processFound` for an engine that needs an external process, where it was found;
`ready`, and `unavailable` with the reason when it is not; `kind`, `built-in` for the build's
own engines or the manifest entry kind (`tool`, `engine`, `policy`, `sampler`, `module`) that
registered it; `protocol`, how it is spoken to (`-`, `object` for a tool's one JSON object each
way, `stdio/1` for an external engine); `source`, `command` and `version` for a manifest
entry, its file, the program it runs and the version the manifest states; and `served`, whether
this service runs the engine when a request names it. An external engine of
`OPENSYSML_ENGINES` is listed with `served` false and `ready` false until the service is started
with `-serve-external-engines <name>,…` or `-serve-external-engines all`, which also advertises
the `engines_external` capability; `unavailable` stays empty, since nothing is wrong with the
engine — the service declines to run a program for its clients until told to
([External engines](external-engines.md#listing-probing-selecting)).

```console
$ … /ListEngines -d '{}'
{"engines":[
  {"name":"explore","authority":"proved","answers":["outcomes"],"bounds":["runs","depth"],"ready":true,"kind":"built-in","protocol":"-","served":true},
  {"name":"run","authority":"observed","answers":["evaluate"],"bounds":["steps","elements"],"ready":true,"kind":"built-in","protocol":"-","served":true},
  {"name":"solve","authority":"proved","answers":["satisfiable"],"bounds":["runs","solver"],"process":"z3","processFound":"/usr/bin/z3","ready":true,"kind":"built-in","protocol":"-","served":true},
  {"name":"spin-bridge","authority":"bounded","answers":["holds","outcomes"],"bounds":["depth","steps","runs"],"process":"/opt/spin-bridge/bin/spin-bridge","processFound":"/opt/spin-bridge/bin/spin-bridge","kind":"engine","protocol":"stdio/1","source":"/etc/opensysml/engines/spin-bridge.json","command":"/opt/spin-bridge/bin/spin-bridge","version":"1.4.0"},
  {"name":"sweep","authority":"observed","answers":["sweep"],"bounds":["runs"],"ready":true,"kind":"built-in","protocol":"-","served":true}]}
```

The `engine` field on `VerifyConstraintRequest`, `VerifyRequirementRequest`,
`VerifySatisfactionRequest`, `ValidateInstanceRequest`, `EvaluateCalcRequest`,
`RunAnalysisRequest` and `RunSweepRequest` selects: unset or `"auto"` puts the question to the engine of highest authority covering it,
advancing past one that refuses; a name puts it to that engine alone, whose refusal is then the
answer (`VerifyConstraint` with `"engine":"explore"` returns a verdict whose `error` is the
refusal); `"all"` puts it to every covering engine, one after another in name order, and
composes their answers. `"engine":"explore"` on `RunAnalysisRequest` asks what
`"schedule":"explore"` asks, and the response answers alike. A name no engine is registered
under is the `invalid_argument` Connect error; the name of an external engine the service lists
but does not serve is the `failed_precondition` error `engine 'spin-bridge' is not served by
this service`, and `auto` and `all` pass over it. Send the field only to a service advertising
`engines`: one without the capability does not read it and answers under `auto`.

Every `Verdict`, and `EvaluateCalcResponse`, `RunAnalysisResponse` and `RunSweepResponse`,
carry the standing of the answer: `engine`, the engine whose answer it is; `strength`, one of
`"not covered"`, `"observed"`, `"witnessed"`, `"bounded"` and `"proved"`; and `bounds`, one
`Bound` per limit the engine ran under — `name`, `limit` and `reached`, true when the run
stopped at the limit, which is what lowers the strength. An answer decided before any engine
was asked (a failure classified before the run) carries none of the three.

```console
$ … /VerifyConstraint -d '{"modelHash":"9794…8610","symbolId":"Demo::Vehicle::massLight","subjectSymbolId":"Demo::sedan"}'
{"verdict":{"kind":"constraint", …, "condition":"mass < 100.0","engine":"run","strength":"witnessed",
  "bounds":[{"name":"steps","limit":"10000000"},{"name":"elements","limit":"1000000"}]}, "instances":[…]}
```

`limit` is an `int64`, so it arrives as a string in JSON, and `reached` is omitted when false
(the default-omission rule). The other fields keep their meaning: `holds`, `error` and
`condition` are read exactly as before, and the standing says how much the answer is worth.
The Python client reads them as `Verdict.engine`, `Verdict.strength` and `Verdict.bounds`
and lists engines with `Connection.list_engines()`.

## Conversion: `Convert`

`Convert` writes a model out in another representation, and needs the `convert` capability. The
request names its source in a `oneof`: a `filePath` the service reads afresh, `content` carried
inline, or a `modelHash` whose parsed source is converted. `toFormat` is required and is one of
`sysml`, `kerml`, `text` (SysML v2 notation), `ttl`, `turtle`, `rdf` (RDF in Turtle) or `api-json`,
`json` (the API's JSON element form). `fromFormat` takes the same names. Omitted, it is inferred
from `filePath`'s extension (`.sysml`, `.kerml`, `.ttl`, `.turtle`, `.json`), is notation for a
`modelHash`, and is `invalid_argument` for inline `content`, which has no extension. A SysML v1
model — `fromFormat` of `xmi`, `uml` or `mdzip`, or a `filePath` ending in `.xmi`, `.uml` or
`.mdzip` — is **not converted**: it is refused as `invalid_argument` before anything is read, with
the message the command prints, because what happens to it is a [migration](#migration-migrate),
which accounts for every element rather than carrying all of them:

```text
{"code":"invalid_argument","message":"Vehicle.xmi is a SysML v1 model, which is migrated, not converted: every element is mapped, approximated or left unmapped and reported element by element; call Migrate with the same source"}
```

A `modelHash` from `ParseSources` of several documents converts the whole model to `ttl` or
`api-json` as one graph: a reference from one document to an element another declares links that
element, as a reference within one document does, and each document's root elements carry
`sysx:sourceDocument`, the name the request gave it. Notation is written for one document, so a
`sysml`/`kerml` target for such a model is `failed_precondition`. A document with syntax errors is
reported in `error` and `diagnostics`, as a single document is, and so is an element two documents
both declare (`package P` in each), which one graph would merge into one. Ids are scope-qualified
when the documents together declare more than one identity scope. The command line does the same
for several files, to a file or standard output: `sysml a.sysml b.sysml -convert api-json`.

`documents`, under the `convert_documents` capability, writes only some documents of such a model:
each name is one the parse gave a document, and only the elements those documents declare are
written, with the root namespace of each in the API element form. The model's other documents
are still read: a reference into one is an `@id` link to the element as a conversion of its own
document writes it, and an element one of them declares that a written document also declares is
refused as above. So a client that holds a model's conversion can convert again only the documents
an edit changed and replace their elements by `@id`. Empty `documents` writes every document. A name
the model does not hold, or `documents` for a `filePath` or `content`, is `invalid_argument`.

`compact`, under the `convert_compact` capability, writes `api-json` from notation as one smaller
object in place of the element array; `omit_derived` and `keep_derived` leave out the metamodel's
derived properties. Expanded, it is the element array. The format is defined in
[Compact API JSON](api-json-compact.md).

`libraryReferences` on a successful API JSON response, including a compact conversion,
names every standard-library element the output references: each entry has `id` (the
literal normative ID), `qualifiedName` and `type` (the API JSON metaclass). Entries are
sorted by ID and do not declare elements or roots. It needs no request option and is
advertised as `convert_library_references`; an empty table means no library references.
`qualifiedName` is empty for an unnamed library relationship, such as an owning membership;
an unnamed library member (a documentation comment, an invariant, an unnamed connector) has
`libraryPath` instead, the positional path `Owner::qualifiedName/Metaclass[i]`.
The compact document also carries the table outside `elements`, using the API JSON keys
`@id`, `qualifiedName` (or `libraryPath`) and `@type`. For graph input, only library metadata present in the
graph can be reported. Other target formats and failed conversions return no table.

`includeLibraryStubs`, advertised as `convert_library_stubs`, restores the ownerless
library stubs written before 0.11.0 inside the API JSON element array (or compact
`elements`). It is default-off and is `invalid_argument` for any other target. The
stubs carry `@id`, `@type`, `declaredName`, `elementId`, `isLibraryElement: true` and
`qualifiedName`; an OMG API reader treats them as roots. Prefer the separate table
for new clients. It composes with `documents`, `idForm` and `compact`.

The Node client exposes `Conversion.libraryReferences` and the
`includeLibraryStubs` option on `Connection.convert` and `Model.convert`.
The MCP `convert` tool accepts the same flag and returns the table as `libraryReferences`.

`includeCheckDiagnostics`, under the `convert_check_diagnostics` capability, adds the semantic
check's diagnostics to `diagnostics` alongside the output, each with its own `severity` (`error`,
`warning` or `info`) and `code`, as `ParseFile` and
`GetDiagnostics` [report them](#diagnostics-the-shape-of-a-finding): the notation is analyzed as a parse analyzes it, so an unresolved
type is an `error` here while the conversion itself succeeds or fails exactly as it does without
the field. It is for notation sources only — a graph has no notation to check — so one with a
`ttl`, `api-json` or XMI source is `invalid_argument`. A source with syntax errors reports those
alone, as before: the check passes do not run on a model that did not parse, whether the
conversion refused it or `tolerateSyntaxErrors` let it through. For a `modelHash` the analysis
the parse cached is reported, and with `documents`, that of the written documents only. Off, the
default, `diagnostics` holds the syntax errors alone, as it always has.

```console
$ … /Convert -d '{"content":"package P { part x : NoSuchType; }","toFormat":"api-json","includeCheckDiagnostics":true}'
{
  "content": "[\n  {\n    \"@type\": \"Namespace\",\n…",
  "fromFormat": "sysml",
  "toFormat": "api-json",
  "diagnostics": [
    {
      "severity": "error",
      "message": "unresolved reference: NoSuchType",
      "span": {"file": "<content>", "startLine": 1, "startColumn": 21, "endLine": 1, "endColumn": 31},
      "code": "unresolved"
    }
  ],
  "experimental": true,
  "experimentalNotice": "…"
}
```

```console
$ … /Convert -d '{"filePath":"Vehicle.sysml","toFormat":"ttl"}'
{
  "content": "@prefix sysml: <https://www.omg.org/spec/SysML/20230201#> .\n…",
  "fromFormat": "sysml",
  "toFormat": "ttl",
  "experimental": true,
  "experimentalNotice": "The RDF mapping is experimental: …"
}
```

`fromFormat` and `toFormat` come back **canonical** — `sysml`, `ttl` or `api-json` whichever
alias was sent — so a client that let the format be inferred learns what it was read as.
`experimental` is set, and `experimentalNotice` says why, when either format is RDF or the API's
JSON form; notation to notation leaves both unset. It is set on a refusal too, so read it before
`error`. The Python client raises `ExperimentalFeatureWarning` from it.

A conversion that could not be done is HTTP 200 with `error` set and `content` absent; its
`diagnostics` explain a syntax error in notation input, with spans.

A request the service will not attempt is a Connect error instead: `toFormat` naming a v1 format
is `invalid_argument` with `cannot write xmi: …; convert to sysml or ttl`, since a v2 model has no
v1 form; an unknown format name and a missing `fromFormat` for inline content are
`invalid_argument` too; an unreadable `filePath` is `not_found` with `file not found:`, and a
stale `modelHash` is `not_found` as described under [the model hash](#how-long-a-hash-is-valid).

## Migration: `Migrate`

A SysML v1 model is **migrated, not converted**, and `Migrate` is the RPC for it, needing the
`migrate` capability. A conversion is lossless; a migration lands every v1 element in a ledger as
**mapped**, **approximated**, **unmapped** or **skipped**, and the response says so, which is why
`Convert` refuses the input rather than quietly doing this. The request names its source in a
`oneof`: a `filePath` the service reads, or `content` carried inline — proto `bytes`, so a
`.mdzip` archive travels as well as XMI text (base64 in Connect JSON). `fromFormat` is `xmi`,
`uml` or `mdzip` — UML XMI 2.5.1 with the SysML profile applied, an Eclipse UML2 `.uml` file, or a
`.mdzip` archive, all read as XMI and answered as the canonical `xmi`; inferred from `filePath`'s
extension when omitted, and required for inline `content`. `toFormat` is notation (`sysml`,
`kerml`, `text`) or RDF (`ttl`, `turtle`, `rdf`). The companion options are the command's flags:
`report` asks for every element's verdict and the report text `-migration-report` writes;
`results` for the run-configuration index `-migration-results` writes; `layoutPath` or inline
`layoutContent` (a `oneof`) for an MTIP export whose diagram geometry lays out the migrated
views (`-layout`); `imageBaseUrl` for the server a comment's relative image is resolved against
(`-image-base-url`); and `strict` for portable output (`-strict`).

```console
$ … /Migrate -d '{"filePath":"Vehicle.xmi","toFormat":"sysml"}'
{
  "content": "doc /* Author: demo team\n * Created: 2026-09-05\n */\npackage 'Vehicle Design' {\n    doc /* Structural model of the demo v…",
  "fromFormat": "xmi",
  "toFormat": "sysml",
  "experimental": true,
  "experimentalNotice": "SysML v1 migration is experimental: the mapping covers structure, ports and connectors, requirements, constraints, instances and allocations, reports every element it approximates or leaves behind, and what it writes for a v1 element may change without a compatibility path; see docs/reference/sysml-v1-migration.md § Status",
  "report": {
    "source": "Vehicle.xmi",
    "exporter": "Example UML Tool",
    "summary": "migrated 95 element(s): 77 mapped, 15 approximated, 3 unmapped (2 skipped as profile, library or notation-only content, 0 as model elements nothing refers to)",
    "mapped": 77,
    "approximated": 15,
    "unmapped": 3,
    "skipped": 2
  }
}
```

Every migration is `experimental`, with the notice; the Python client raises
`ExperimentalFeatureWarning` from it and the Go client reports it on the `Migration`. The
`report` always carries the `summary` line the command prints and the four counts, so a client
can gate on the verdicts without asking for more. With `report: true` it also carries `entries` —
one per v1 element, in report order, each with the element's `id`, `kind`, `name`, the v2
`target` it became when it did, its `verdict` (`mapped`, `approximated`, `unmapped` or `skipped`)
and a `note` saying how or why not — and `text`, the report the command writes to a file:

```text
{"id":"_unit_kg","kind":"«Unit» InstanceSpecification","name":"Vehicle Design::Value Types::kilogram","verdict":"unmapped","note":"units and quantity kinds are not migrated; use the SI and ISQ libraries; applied stereotypes «Unit» (quantityKind = Vehicle Design::Value Types::mass; symbol = kg)"}
```

With `results: true`, `results` is the JSON sidecar `-migration-results` writes, as a string.
Image files the migration extracts from the archive — a comment's `<img>` without an
`imageBaseUrl` — come back as `files`, each a `path` relative to the written document and its
`content` bytes, in path order, so a client writing the notation to disk writes them beside it.
What the migration maps, approximates and leaves behind is in
[sysml-v1-migration.md](sysml-v1-migration.md).

A migration that could not be done is HTTP 200 with `error` set and `content` absent, with the
formats and the experimental notice still filled; malformed XMI is reported this way:

```text
{"fromFormat":"xmi","toFormat":"sysml","error":"<content>: not an XMI document: expected an xmi:XMI or uml:Model root element","experimental":true,"experimentalNotice":"SysML v1 migration is experimental: …"}
```

A request the service will not attempt is a Connect error instead, every one `invalid_argument`:
v2 input, by `fromFormat` or by extension, is refused with the mirror of `Convert`'s help —
`Vehicle.sysml is sysml input, which is converted, not migrated: only a SysML v1 model (xmi, uml
or mdzip) is migrated; call Convert with the same source`; `toFormat` naming a v1 format with
`cannot write xmi: …`, since a v2 model has no v1 form; inline `content` without `fromFormat` with
`from_format is required for inline content: expected xmi, uml or mdzip`; and an MTIP layout that
is not one with what is wrong with it. An unreadable `filePath` or `layoutPath` is `not_found`
with `file not found:`.

## `RenderView`

`RenderView` returns the machine-readable fields of a named view or targeted pseudo-view. The
response preserves node and edge order, parent links, ports, source spans, table and matrix rows, notes and
notices; optional canvas, geometry and style messages are absent when the model states none.
Pictures are not included; a refused picture contributes its reason to `notices`. An omitted or
`minimal` `ports` value includes only ports used by rendered connections; `full` includes every
declared port. The service advertises this method as
the `render_view` capability.

This excerpt was captured by calling the gRPC service with
`RenderViewDemo::connections` from `conformance/fixtures/views.sysml` and marshaling the response
with protobuf JSON:

```json
{
  "view": "RenderViewDemo::connections",
  "kind": "interconnection",
  "stated": "render asInterconnectionDiagram",
  "nodes": [
    {
      "id": "n0",
      "kind": "part def",
      "name": "RenderViewDemo::Assembly",
      "origin": {
        "file": "<content>",
        "startLine": 21,
        "startCol": 5,
        "endLine": 25,
        "endCol": 6
      }
    },
    {
      "id": "n1",
      "kind": "part",
      "name": "sender",
      "type": "Sender",
      "parent": "n0",
      "ports": [
        {"id": "n1.0", "name": "api", "type": "API"}
      ],
      "origin": {
        "file": "<content>",
        "startLine": 22,
        "startCol": 9,
        "endLine": 22,
        "endCol": 30
      }
    },
    {
      "id": "n2",
      "kind": "part",
      "name": "receiver",
      "type": "Receiver",
      "parent": "n0",
      "ports": [
        {"id": "n2.0", "name": "api", "type": "API"}
      ],
      "origin": {
        "file": "<content>",
        "startLine": 23,
        "startCol": 9,
        "endLine": 23,
        "endCol": 34
      }
    }
  ],
  "edges": [
    {
      "from": "n1",
      "to": "n2",
      "fromPort": "n1.0",
      "toPort": "n2.0",
      "label": "link",
      "kind": "connection",
      "origin": {
        "file": "<content>",
        "startLine": 24,
        "startCol": 9,
        "endLine": 24,
        "endCol": 87
      }
    }
  ]
}
```

## `ExportGraphs`

`ExportGraphs` returns the lowered graph of an action or state machine — the subject's
`ActionGraph`/`StateGraph` IR and that of every behavior it performs — as the canonical
`graphs:1` JSON an external analysis engine is sent ([the `graphs:1` model
form](external-engines.md#the-graphs1-model-form)). `content` is that JSON with one trailing
newline, byte for byte what `sysml -graphs <subject>` writes; `version` is its `version` field and
`subject` the qualified name as resolved. The subject names an action or state machine, definition
or usage, by qualified name: a name no element has is `NOT_FOUND` (`symbol not found:
Test::Missing`), one that is no behavior (`Test: graphs: subject has no lowered graph: Test is a
package`) is `INVALID_ARGUMENT`, and so is a name the model declares more than once (`P::Run is
ambiguous: the model declares 2 elements under that name`); a declaration of the model's shadows
the library's of the same name. The service advertises this method as the `export_graphs`
capability.

This excerpt was captured by calling the gRPC service with `Test::race` from
`conformance/fixtures/behavior.sysml` and marshaling the response with protobuf JSON; the
`content` string is shown pretty-printed and cut after the first two nodes:

```json
{
  "content": "{\"version\":1,\"subject\":\"Test::race\",\"actions\":[{\"name\":\"Test::race\",\"kind\":\"actionUsage\", …}]}\n",
  "version": 1,
  "subject": "Test::race"
}
```

```json
{
  "version": 1,
  "subject": "Test::race",
  "actions": [
    {
      "name": "Test::race",
      "kind": "actionUsage",
      "scope": "Test::race",
      "attributes": [
        {
          "name": "winner",
          "types": ["ScalarValues::Integer"],
          "value": {"text": "0", "span": {"document": "<content>", "offset": 401, "len": 1}},
          "span": {"document": "<content>", "offset": 372, "len": 31}
        }
      ],
      "nodes": [
        {
          "id": 0,
          "kind": "start",
          "name": "start",
          "span": {"document": "<content>", "offset": 406, "len": 12},
          "footprint": {}
        },
        {
          "id": 2,
          "kind": "action usage",
          "name": "left",
          "span": {"document": "<content>", "offset": 435, "len": 40},
          "scope": "Test::race::left",
          "body": [
            {
              "kind": "assign",
              "span": {"document": "<content>", "offset": 452, "len": 19},
              "scope": "Test::race::left",
              "name": "winner",
              "value": {"text": "1", "span": {"document": "<content>", "offset": 469, "len": 1}}
            }
          ],
          "footprint": {
            "writes": [{"symbol": "Test::race::winner", "name": "winner"}],
            "control": [4]
          }
        }
      ],
      "initial": 0,
      "finals": [5],
      "edges": [{"source": 0, "target": 1, "decl": {"document": "<content>", "offset": 543, "len": 34}}]
    }
  ]
}
```

A node's `kind`, `name`, `scope` and `span` identify the step; `body` carries its statements as the
runtime executes them; `footprint` records what it reads and writes and the nodes it hands control
to. `edges` are successions by node id, `flows` item flows between pins, `parameters` the subject's
own pins; a state machine's graph lists `states`, `transitions` with their guards, triggers and
effects, and pseudostates in the same way. A behavior a node `performs` is exported after the
subject under its own name, so the form is closed over everything the subject runs.

## `RunRuns`

`RunRuns` runs an action or a Monte Carlo case `runs` times and tables the result: what
`sysml -runs N -observe f` prints, as data. `RunRunsRequest` names what runs by exactly one of
`action_symbol_id` and `analysis_symbol_id`, binds it through `inputs`, `performer_symbol_id`,
`subject_symbol_id`, `arguments` and `named_arguments` as `ExecuteActionRequest` and
`RunAnalysisRequest` do, and carries the CLI's flags under their names: `runs` (int64), `seed`
(optional uint64, required unless `draws` is `min`, `max` or `average`), `draws`, `clock_step`
(double seconds), `observe` (repeated feature names) and `engine`. `RunRunsResponse` carries
`rows` (one `SweepRow` per run, each with its `inputs`, `outputs`, `verdicts` and `error`),
`observables`, `distributions` (`RunDistribution`: `name`, `unit`, `count`, `numeric`, `min`,
`max`, `mean`, `deviation`, `percentiles`, `histogram`, `values`), `lines`, `outputs`,
`verdicts`, `unconcluded`, `seed`, `instances`, `engine`, `strength`, `bounds`, `diagnostics`,
`error` and `failure_reason`. A count below one, an unseeded random run and an ambiguous request
are `INVALID_ARGUMENT`; an action, case or subject the model lacks is answered in band through
`error`. The service advertises this method as the `runs` capability, and one without it refuses
the call with `UNIMPLEMENTED`.

## `SelfCheck`

`SelfCheck` applies the `SysMLValidation` rule constraints to the model's own elements: what
`sysml -self-check` prints, as data. `SelfCheckRequest` carries `model_hash` and
`self_check_package` (repeated; rule packages applied beside `SysMLValidation`).
`SelfCheckResponse` carries `status` (`holds` or `fails`), `findings` (`SelfCheckFinding`:
`status`, `subject`, `location`, `constraint`, `element`, `message`, `line`), the int64 counts
`elements`, `checks`, `violations`, `unevaluated` and `evaluation_errors`, `applications`
(`SelfCheckApplication`: `constraint`, `count`), `summary`, `diagnostics` and `error`. A rule
package the model lacks is answered in band through `error`. The service advertises this method
as the `self_check` capability.

## `RecordRun`

`RecordRun` runs a case and records the result into the model: what `sysml -record-run` writes,
as a new model the service holds. `RecordRunRequest` carries `model_hash`, `analysis_symbol_id`,
`subject_symbol_id`, `arguments`, `named_arguments`, `ranges` (a sweep), `runs` and `seed` (a
Monte Carlo sample), `record_into` (the target package; `Records` when empty), `engine` and
`accept_documents`, which must be true because the answer rewrites documents.
`RecordRunResponse` carries exactly one of `run` (`RunAnalysisResponse`), `sweep`
(`RunSweepResponse`) and `sample` (`RunRunsResponse`), then `package`, `definition`, `records`
(qualified names, `<Package>::<Case>_run<n>`), `source`, `content` (the whole document when the
model has one and the records joined it), `documents` (`EditedDocument`; a standalone record
document is named after its package, `Records.sysml`), `skipped`, `reasons`, `diagnostics`,
`model_hash` (the recorded model; every record resolves through `GetSymbol` under it), `error`
and `failure_reason`. A case or subject the model lacks, and a record that would leave the model
with new errors, are answered in band through `error` with the model unchanged. The service
advertises this method as the `record_run` capability.

## `ImportData`

`ImportData` sets the feature values tabular or JSON data assigns: what `sysml -import` does, as
data. `ImportDataRequest` carries `model_hash`, `imports` (repeated `DataImport`: `name`,
`content`, `import_format` — `csv`, `tsv`, `json` or `jsonl`, the name's extension when empty —
and `import_map`, the mapping file's content), `import_as` (`values` when empty), `import_dry_run`
and `accept_documents`. `ImportDataResponse` carries `files` (one `ImportedFile` per import, in
order: `name`, the int64 `values` and `elements`, and `assignments` of `ImportedValue`: `element`,
`feature`, `value`, `redefines`, `where`, `description`), `documents` (`EditedDocument`),
`content` (a one-document model's edited text), `model_hash` (the imported model the service now
holds; unset on a dry run), `diagnostics` and `error`. A request with no `imports` is
`INVALID_ARGUMENT`; an import the model refuses is answered in band through `error` with `files`,
`content` and `model_hash` unset and the model unchanged. The service advertises this method as
the `import_data` capability, and one without it refuses the call with `UNIMPLEMENTED`.

## `CompareResults`

`CompareResults` runs the configurations a SysML v1 tool's results index names and tables the
tool's distributions beside the runs': what `sysml -compare-results` prints, as data.
`CompareResultsRequest` carries `model_hash`, `results` (the index JSON `-migration-results`
writes), `actions` (repeated names or ids; all when empty), `runs` (int64; 0 for as many as the
tool stored), `seed` (optional uint64), `draws`, `clock_step` (optional double seconds), `observe`
(repeated `ObservablePair`: `stored`, `feature`) and `engine`. `CompareResultsResponse` carries
`configurations` (`ConfigurationComparison`: `id`, `name`, `behavior`, `target`,
`result_location`, `status`, `unresolved`, `stored_runs`, `stored_snapshots`, `runs`,
`completed`, `draws`, `seed`, `clock_step`, `rows` of `SweepRow`, `instances`, `observables`,
`errors`, `notes`, `lines`), `source`, `error`, `diagnostics`, `failure_reason`, `engine`,
`strength` and `bounds`. Each `ObservableComparison` carries `stored`, `feature`, `unit`, the
tool's `ComparedDistribution` (`count`, `min`, `mean`, `p50`, `p90`, `max`, `deviation`) with
`pooled` and `unstored`, the runs' `run` distribution with `produced`, `compared`, the
`StatisticDifference` (`min`, `mean`, `p50`, `p90`, `max`, each a signed percentage as text),
the case's `declared` statistics (`CaseStatistics`: `analysis`, `rows` of `CaseStatistic`, `notes`)
and `notes`. A malformed index, a negative `runs` and an unknown `draws` are `INVALID_ARGUMENT`;
a configuration that cannot run is answered as `unresolved` within the list. The service
advertises this method as the `compare_results` capability.


## `CheckBehavior`

`CheckBehavior` searches every schedule of an action or state machine for a violated
property, a deadlock, a failure or a divergent value: what `sysml -check-property` prints,
as data. `CheckBehaviorRequest` names the behavior by exactly one of `action_symbol_id` and
`state_machine_symbol_id`, binds it through `inputs` and `performer_symbol_id` as
`ExecuteActionRequest` does, and carries the CLI's flags under their names: `check_property`,
`check_diverge`, `check_input`, `check_assume` (repeated strings), `check_witness` (bool),
`check_depth`, `check_states`, `check_unroll` (int32 counts, 0 for the engine's default),
`check_timeout` (double seconds, 0 for none) and `engine`. `CheckBehaviorResponse` carries
`verdict`, `lines`, `search` (`CheckSearch`, whose `coverage` is the `Coverage` every searched
schedule entered and took, `runs` counting schedules), `violations` (`CheckViolation`), `divergences`
(`CheckDivergence`, each value a `CheckDivergentValue`), `finals` (`CheckFinal`), `claim`,
`free_inputs`, `assumptions`, `witness`, `contrast`, `engine`, `strength`, `bounds`, `reason`
and `error`; every witness is a `CheckWitness` whose `schedule` any run replays.
Malformed bounds and an ambiguous behavior are `INVALID_ARGUMENT`; a behavior, property or
performer the model lacks is answered in band through `error`. The service advertises this
method as the `check` capability, and one without it refuses the call with `UNIMPLEMENTED`.

## Queries

Two query surfaces exist and answer differently shaped tables. Their semantics — what may be
selected, filtered and bound — are on the Go API page and are not repeated here:
[SysML v2 API & Services `Query`](api.md#sysml-v2-api--services-query) and
[Native document queries and rendering over gRPC](api.md#native-documents-and-views-over-grpc).
Each is its own capability: `Query` needs `query` (and `oslc_query` when the request uses
`oslcQuery`); `RunDocumentQuery` needs `document_query`, and `inline_document_query` too when the
request writes the query in `inlineQuery`; `RenderDocument` needs
`render_document`, and `render_document_html` too when its `form` is `html`; its `file_name` (the
file a rendered set writes the document to, which the other documents' links to it name) is
populated under `render_document_file_name`.

### `Query`

The request carries a structured `query` (`scope`, `select`, `where`) **or** an `oslcQuery`
string in the OSLC syntax of [OSLC Query text](oslc-query.md), never both. `where` is a
`Constraint`, itself a `oneof` of `primitive` and `composite`; the operator is a proto enum and
is written as its **name**; `value` is a list of strings:

```console
$ … /Query -d '{"modelHash":"2af52c50cee63699ece8f9021b6344e4fe9f2fe6eeb0f3f8edd9feaa5443dea2","query":{"select":["name","owner","type"],"where":{"primitive":{"property":"@type","operator":"PRIMITIVE_OPERATOR_EQUAL","value":["PartUsage"]}}}}'
```

```json
{
  "elements": [
    {"id": "Demo::Vehicle::engine", "type": "PartUsage", "properties": {"name": "engine", "owner": "Demo::Vehicle", "type": "Demo::Engine"}},
    {"id": "Demo::sedan",           "type": "PartUsage", "properties": {"name": "sedan",  "owner": "Demo",          "type": "Demo::Vehicle"}}
  ]
}
```

Each element has its `id` (fully qualified name), its `type` (the SysML metaclass name), and
`properties`, a **string → string** map holding exactly the `select`ed properties that the
element has a value for. Everything in `properties` is a string, including numbers such as
`multiplicityLower`; there are no `Value` objects on this call. An element without a selected
property simply lacks the key. No matches is `{}` (captured for `"property":"name"` equal to
`"nobody"`).

### `RunDocumentQuery`

A document query is a `calc def` in the model specializing `DocumentQueries::Query`; the request
names it by `queryId`, or writes one in `inlineQuery` (below), and supplies `bindings` for its
`in` parameters. Each binding is a
`parameter` name and a list of `values`, and each value is a `DocumentValue` — a `oneof` whose
arm says what was bound:

- **`elementId`** binds a model element by fully qualified name. *This is how a parameter
  of type `Element` is bound.*
- **`stringValue`, `intValue` (string), `realValue`, `boolValue`, `infinity`** bind a literal;
  the query treats it as a value, not a name. A string that happens to be a qualified name
  bound as `stringValue` is a string.
- **`quantity`** binds a magnitude with a unit, the same object a `Value` carries (`unit`,
  `unitTerm` and one of `intMagnitude`/`realMagnitude`); it is how a projected
  `attribute :>> mass = 2290000 [kg];` is answered. Bound, it conforms to a parameter typed
  by a quantity value type of the same dimension (`MassValue` for a mass, any for
  `ScalarQuantityValue`); a parameter of another dimension or of a scalar type such as
  `String` refuses it with `invalid_argument`.
- **`object`** binds an object the service holds for the model — one `Instantiate` created —
  as a `DocumentObject` with `instanceId` (the `id` `Instantiate` answered, an int64 so a
  string in JSON) or `path` (the usage it was instantiated as, `car` or `Garage::car`; its id,
  `#2`; or a walk through feature values from either, `car.wheels[2]`, indexes from 1) or
  both, in which case the path is followed and must reach the object with that id. *This is
  how a parameter of type `Element` is bound to an object rather than to its declaration*;
  the query then reads the object's current values. The answer-side `element` of a
  `DocumentObject` is ignored in a request.

`inlineQuery` carries the result expression such a `calc def` would hold, planned and run as a
named query is, in the model's context (the `DocumentQueries` library imported, the model's names
reachable, held objects behind `Objects`/`Verdicts`/`States`/`Events`); exactly one of `queryId`
and `inlineQuery` is set, and both or neither is `invalid_argument`. The field needs the
`inline_document_query` capability, refused with `unimplemented` otherwise. Text that does not
parse or plan is `invalid_argument` with the position within the expression —
`inline query 1:30: expected ')'` — and a failure while running keeps the named form's status
and `QueryOutcome` detail:

```console
$ … /RunDocumentQuery -d '{"modelHash":"7e6a…a687","inlineQuery":"Project(WhereType(Descendants(Observatory::telescope), \"PartUsage\"), (\"name\", \"mass\"))"}'
```

answers the same `columns` and `rows` shape as a named query, in document order.

Model `7e6a…a687` is `conformance/fixtures/document.sysml`; `HeavySubsystemNames` takes
`root : Element` and `threshold : String`:

```console
$ … /RunDocumentQuery -d '{"modelHash":"7e6a2c9c119fa1b951f0db8fbac36e2b94899144999085b0e27ee124cb57a687","queryId":"Observatory::HeavySubsystemNames","bindings":[{"parameter":"root","values":[{"elementId":"Observatory::telescope"}]},{"parameter":"threshold","values":[{"stringValue":"10"}]}]}'
```

```json
{
  "columns": [{"name": "name"}],
  "rows": [
    {"element": {"elementId": "Observatory::telescope::mount",          "elementType": "PartUsage"}, "cells": [{"values": [{"stringValue": "mount"}]}]},
    {"element": {"elementId": "Observatory::telescope::segmentControl", "elementType": "PartUsage"}, "cells": [{"values": [{"stringValue": "segmentControl"}]}]}
  ]
}
```

The answer is a table: `columns` in order, and `rows` each with `element` (the row's subject as
a `DocumentValue`, here always `elementId` plus `elementType`) and `cells` **positionally
aligned with `columns`**. A cell holds `values`, a list of `DocumentValue`s (several for a
multi-valued property, none for a missing one, in which case `values` is absent). A
`DocumentValue` decodes like a `Value` — one arm present — but its arms are the eight above plus
the answer-only `verdict` below, `bigIntValue` for an Integer beyond `int64` and `rationalValue`
for a Rational no double holds (same rules as on `Value`), and never a nested sequence or enum. `SubsystemTable` projects two columns and shows a
`realValue` cell:

```console
$ … /RunDocumentQuery -d '{"modelHash":"7e6a…a687","queryId":"Observatory::SubsystemTable","bindings":[{"parameter":"root","values":[{"elementId":"Observatory::telescope"}]}]}'
{"columns":[{"name":"name"},{"name":"mass"}],"rows":[{"element":{"elementId":"Observatory::telescope::baffle|shroud *tricky*","elementType":"PartUsage"},"cells":[{"values":[{"stringValue":"baffle|shroud *tricky*"}]},{"values":[{"realValue":1.5}]}]},{"element":{"elementId":"Observatory::telescope::mount","elementType":"PartUsage"},"cells":[{"values":[{"stringValue":"mount"}]},{"values":[{"realValue":15}]}]},{"element":{"elementId":"Observatory::telescope::optics","elementType":"PartUsage"},"cells":[{"values":[{"stringValue":"optics"}]},{"values":[{"realValue":8.5}]}]},{"element":{"elementId":"Observatory::telescope::segmentControl","elementType":"PartUsage"},"cells":[{"values":[{"stringValue":"segmentControl"}]},{"values":[{"realValue":20}]}]}]}
```

#### Objects the service holds

The service keeps every object `Instantiate` creates for a model, under the qualified name it
was instantiated as, for as long as the model stays cached; instantiating the name again makes
it denote the new object, and the earlier one stays held, reached by its id. A query runs over
that population: a binding names one of its objects, `DocumentQueries::Objects(type = T)`
enumerates it — named objects by qualified name, then displaced ones by id — and answers no
rows while nothing is held, and `RenderDocument` renders over it, so a document rendered after
an `Instantiate` reports the objects' current values rather than their declared defaults.

A row that is an object, and a cell whose value is one, is answered with the **`object`** arm:
`instanceId`, `path` (the label the object is reached under, from the binding down —
`Garage::car.wheels[2]`, or `#1.wheels[2]` when the binding was by id) and `element`, the
usage the object stands for as an `elementId` `DocumentValue` with its `elementType`. Model
`0ff2…48a0` is `internal/doc/docrender/testdata/object_report.sysml`; after
`Instantiate` of `Garage::car` (answered id `1`, its engine `2` and wheels `3` and `4`) and of
`Garage::spare` (`5`), `Drive` projects the car's `name`, `engine` and `wheels`:

```console
$ … /RunDocumentQuery -d '{"modelHash":"0ff27b91eb544169523526daec8007f6d4e05a66c8d1bca59f9224561ea348a0","queryId":"Garage::Drive","bindings":[{"parameter":"root","values":[{"object":{"path":"car"}}]}]}'
```

```json
{
  "columns": [{"name": "name"}, {"name": "engine"}, {"name": "wheels"}],
  "rows": [
    {
      "element": {"object": {"instanceId": "1", "path": "Garage::car", "element": {"elementId": "Garage::car", "elementType": "PartUsage"}}},
      "cells": [
        {"values": [{"stringValue": "car"}]},
        {"values": [{"object": {"instanceId": "2", "path": "Garage::car.engine",    "element": {"elementId": "Garage::Car::engine", "elementType": "PartUsage"}}}]},
        {"values": [{"object": {"instanceId": "3", "path": "Garage::car.wheels[1]", "element": {"elementId": "Garage::Car::wheels", "elementType": "PartUsage"}},
                     {"object": {"instanceId": "4", "path": "Garage::car.wheels[2]", "element": {"elementId": "Garage::Car::wheels", "elementType": "PartUsage"}}]}
      ]
    }
  ]
}
```

Bound by id instead, the same objects are reported under `#1`; `Parts` walks the car's
descendants and shows a projected `pressure` of the wheels — a `Descendants` walk over an
object follows its feature values, so a wheel bound by path (`car.wheels[2]`) has no rows:

```console
$ … /RunDocumentQuery -d '{"modelHash":"0ff2…48a0","queryId":"Garage::Parts","bindings":[{"parameter":"root","values":[{"object":{"instanceId":"1"}}]}]}'
{"columns":[{"name":"name"},{"name":"qualifiedName"},{"name":"pressure"}],"rows":[{"element":{"object":{"instanceId":"2","path":"#1.engine","element":{"elementId":"Garage::Car::engine","elementType":"PartUsage"}}},"cells":[{"values":[{"stringValue":"engine"}]},{"values":[{"stringValue":"#1.engine"}]},{}]},{"element":{"object":{"instanceId":"3","path":"#1.wheels[1]","element":{"elementId":"Garage::Car::wheels","elementType":"PartUsage"}}},"cells":[{"values":[{"stringValue":"wheels[1]"}]},{"values":[{"stringValue":"#1.wheels[1]"}]},{"values":[{"intValue":"30"}]}]},{"element":{"object":{"instanceId":"4","path":"#1.wheels[2]","element":{"elementId":"Garage::Car::wheels","elementType":"PartUsage"}}},"cells":[{"values":[{"stringValue":"wheels[2]"}]},{"values":[{"stringValue":"#1.wheels[2]"}]},{"values":[{"intValue":"30"}]}]}]}

$ … /RunDocumentQuery -d '{"modelHash":"0ff2…48a0","queryId":"Garage::Wheels"}'
{"columns":[{"name":"qualifiedName"},{"name":"pressure"}],"rows":[{"element":{"object":{"instanceId":"5","path":"Garage::spare","element":{"elementId":"Garage::spare","elementType":"PartUsage"}}},"cells":[{"values":[{"stringValue":"Garage::spare"}]},{"values":[{"intValue":"20"}]}]},{"element":{"object":{"instanceId":"3","path":"Garage::car.wheels[1]","element":{"elementId":"Garage::Car::wheels","elementType":"PartUsage"}}},"cells":[{"values":[{"stringValue":"Garage::car.wheels[1]"}]},{"values":[{"intValue":"30"}]}]},{"element":{"object":{"instanceId":"4","path":"Garage::car.wheels[2]","element":{"elementId":"Garage::Car::wheels","elementType":"PartUsage"}}},"cells":[{"values":[{"stringValue":"Garage::car.wheels[2]"}]},{"values":[{"intValue":"30"}]}]}]}
```

`Wheels` takes no binding: it is an `OrderBy` over `Objects(type = "Wheel")`, so it answers the
three wheels the model holds, spare first by its lower pressure. An object binding the model
cannot honor is a Connect error naming the parameter — `not_found` while nothing is held or
for an id or a usage no `Instantiate` created, `invalid_argument` for a path that does not
reach an object or an id the path disagrees with:

```console
$ … /RunDocumentQuery -d '{"modelHash":"0ff2…48a0","queryId":"Garage::Parts","bindings":[{"parameter":"root","values":[{"object":{"path":"car"}}]}]}'
HTTP/1.1 404 Not Found
{"code":"not_found","message":"binding root: the model holds no objects (Instantiate creates one)"}

$ … /RunDocumentQuery -d '{"modelHash":"0ff2…48a0","queryId":"Garage::Parts","bindings":[{"parameter":"root","values":[{"object":{"instanceId":"9"}}]}]}'
HTTP/1.1 404 Not Found
{"code":"not_found","message":"binding root: no object #9 for this model: nothing materialized has that identity (the objects are #1, #2, #3, #4, #5)"}

$ … /RunDocumentQuery -d '{"modelHash":"0ff2…48a0","queryId":"Garage::Parts","bindings":[{"parameter":"root","values":[{"object":{"path":"car.wheels[3]"}}]}]}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"binding root: wheels of Garage::car holds 2 objects, so wheels[3] names none (indexes run from 1 to 2)"}

$ … /RunDocumentQuery -d '{"modelHash":"0ff2…48a0","queryId":"Garage::Parts","bindings":[{"parameter":"root","values":[{"object":{"path":"spare.pressure"}}]}]}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"binding root: pressure of Garage::spare holds a value (20), not an object"}

$ … /RunDocumentQuery -d '{"modelHash":"0ff2…48a0","queryId":"Garage::Parts","bindings":[{"parameter":"root","values":[{"object":{"instanceId":"5","path":"car.wheels[2]"}}]}]}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"binding root: Garage::car.wheels[2] is object #4, not #5"}
```

A query over `DocumentQueries::Verdicts` answers **verdict rows**: the row's `element` is the
ninth arm, **`verdict`**, a `DocumentVerdict` with `assertion` (the assertion checked, as an
`elementId` `DocumentValue` — an anonymous `satisfy` keeps its `elementType` and has an empty
`elementId`), `kind` (`constraint`, `requirement`, `satisfaction`, `binding`, `verification`), `text`
(the assertion as written), `path` (the object checked, from the bound element down —
`Garage::car.wheels[2]`, an object a subsetting usage declares by that usage, `Garage::assembly.small`),
`verdict` (`holds`, `violated`, `undecided`), and, where they apply,
`condition` (the expression found false), `reason` (why a row is violated or undecided — an
undecided row always carries one) and `verification` (the verdict kinds — `pass`, `fail`,
`inconclusive`, `error` — of the verification cases verifying the requirement). An element
bound by `elementId` is checked **as declared** — definition defaults and the usage's
redefinitions; an object bound by `object` is checked as it is, its current values, and the
rows' `path`s start from the label it was bound under. Model `a3d6…0d43` is `conformance/fixtures/verdicts.sysml`;
`Failing` keeps the rows whose `verdict` is not `holds`:

```console
$ … /RunDocumentQuery -d '{"modelHash":"a3d6af37675d0e1d866cb2c59b88147a9eba7ebf00dbedcd51d7a29d12e60d43","queryId":"Garage::Failing","bindings":[{"parameter":"root","values":[{"elementId":"Garage::car"}]}]}'
```

```json
{
  "rows": [
    {"element": {"verdict": {"assertion": {"elementId": "Garage::Car::fits",        "elementType": "ConstraintUsage"}, "kind": "constraint", "text": "assert constraint fits",       "path": "Garage::car",           "verdict": "undecided", "reason": "constraint fits: assertion evaluation failed: no value for feature capacity"}}},
    {"element": {"verdict": {"assertion": {"elementId": "Garage::Engine::powerLow",  "elementType": "ConstraintUsage"}, "kind": "constraint", "text": "assert constraint powerLow",   "path": "Garage::car.engine",    "verdict": "violated",  "condition": "power < 200.0",    "reason": "constraint powerLow: assertion evaluated to false: power < 200.0"}}},
    {"element": {"verdict": {"assertion": {"elementId": "Garage::Wheel::pressureOk", "elementType": "ConstraintUsage"}, "kind": "constraint", "text": "assert constraint pressureOk", "path": "Garage::car.wheels[1]", "verdict": "violated",  "condition": "pressure >= 30.0", "reason": "constraint pressureOk: assertion evaluated to false: pressure >= 30.0"}}},
    {"element": {"verdict": {"assertion": {"elementId": "Garage::Wheel::pressureOk", "elementType": "ConstraintUsage"}, "kind": "constraint", "text": "assert constraint pressureOk", "path": "Garage::car.wheels[2]", "verdict": "violated",  "condition": "pressure >= 30.0", "reason": "constraint pressureOk: assertion evaluated to false: pressure >= 30.0"}}}
  ]
}
```

A `WhereFeature` query projects no columns, so `columns` is absent and each row is its
`element` alone. `Checks` projects `path`, `name`, `verdict` and `reason`; a satisfaction row
shows how a verdict relates to the verification of its requirement:

```console
$ … /RunDocumentQuery -d '{"modelHash":"a3d6…0d43","queryId":"Garage::Checks","bindings":[{"parameter":"root","values":[{"elementId":"Garage::car"}]}]}'
{"columns":[{"name":"path"},{"name":"name"},{"name":"verdict"},{"name":"reason"}],"rows":[…,{"element":{"verdict":{"assertion":{"elementId":"","elementType":"SatisfyRequirementUsage"},"kind":"satisfaction","text":"satisfy strongEngine by car.engine","path":"Garage::car.engine","verdict":"holds","verification":["pass"]}},"cells":[{"values":[{"stringValue":"Garage::car.engine"}]},{},{"values":[{"stringValue":"holds"}]},{}]},{"element":{"verdict":{"assertion":{"elementId":"Garage::checkEngine","elementType":"VerificationCaseUsage"},"kind":"verification","text":"verification Garage::checkEngine","path":"Garage::car.engine","verdict":"holds","verification":["pass"]}},"cells":[{"values":[{"stringValue":"Garage::car.engine"}]},{"values":[{"stringValue":"checkEngine"}]},{"values":[{"stringValue":"holds"}]},{}]},…]}
```

A verdict is answered, never bound: a binding carrying the `verdict` arm is refused with
`invalid_argument` (`binding root: a verdict is answered by queries, not bound to them`). A
client that decodes `DocumentValue` by its one present arm therefore has nine arms to read in
an answer and eight to write in a request.

The request-side failures are Connect errors, because the request — not the model — is wrong:

```console
$ … /RunDocumentQuery -d '{"modelHash":"7e6a…a687","queryId":"Observatory::SubsystemTable"}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"query Observatory::SubsystemTable requires binding root (declared in document.sysml)"}

$ … /RunDocumentQuery -d '{"modelHash":"7e6a…a687","queryId":"Observatory::telescope"}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"Observatory::telescope is not a document query: one is a calc def specializing DocumentQueries::Query"}
```

## `ApplyEdits`: one document or several

`ApplyEdits` rewrites the source a cached model was parsed from. Its answer names the edited
notation twice, and a client reads one or the other by what it knows — and says which, by
the request's `acceptDocuments`:

- **`documents`** is the answer for every model. Each entry is one document the batch rewrote,
  `name` the name the parse request gave it (`documents[].name` of `ParseSources`, the
  `filePath` of a `ParseFile`, or `<content>` for inline content), `content` its whole edited
  notation. The document the operations targeted comes first when it changed, then the others
  in name order. A document the batch did not touch is **not** listed, so a client
  writes back exactly the entries it receives.
- **`content`** is the edited notation of a model of **exactly one** document, and is empty
  for a model of several — including when the batch rewrote only one of them. It is the
  field the sole-document contract answered before `documents` existed, and it keeps that
  meaning: a client written against it sees the same answers it always did, and never a
  multi-document model's, because such a model is edited only for a request that sets
  **`acceptDocuments`** (`ApplyEditsRequest` field 4). A request leaving it unset — every
  request a client of the previous schema can send — is refused on a model of several
  documents with `failed_precondition`, as such a model refused every edit before, so a
  client that reads `content` alone is never handed an empty one to write back. A model of
  one document ignores the flag: its edit fills both fields either way.

So an empty `content` beside a non-empty `documents` means "a model of several documents", not
"nothing changed": every operation splices the document its target is declared in, so a
successful edit always lists at least that one, and a document is listed when an operation
reached it, whether or not the bytes it wrote differ from the ones it replaced. A new client
sets `acceptDocuments`, reads `documents` only, and has one code path for both shapes;
`content` is for the client that predates it, which keeps the refusal it always had.

A model of one document, edited (fixture `engine_library.sysml`, parsed by `ParseSources`
under that name; the two fields carry the same bytes):

```console
$ … /ApplyEdits -d '{"modelHash":"234e…95d4","operations":[{"setValue":{"target":"EngineLibrary::Engine::power","value":"200"}}]}'
{"content":"package EngineLibrary {\n\tprivate import ScalarValues::*;\n\tpart def Engine {\n\t\tattribute power : Integer = 200;\n\t}\n}\n",
 "applied":[{"target":"EngineLibrary::Engine::power","offset":106,"length":3,"oldText":"150","newText":"200","document":"engine_library.sysml"}],
 "documents":[{"name":"engine_library.sysml","content":"package EngineLibrary {\n\tprivate import ScalarValues::*;\n\tpart def Engine {\n\t\tattribute power : Integer = 200;\n\t}\n}\n"}]}
```

A model of two (`engine_library.sysml` and `engine_user.sysml`, parsed together), where a
rename in the first is followed into the reference the second makes. The batch is applied as
one: every document is spliced, re-parsed and re-analysed together, and either all of them are
answered or none is. Each `applied` entry names the `document` its bytes belong to, and
`content` is absent:

```console
$ … /ApplyEdits -d '{"modelHash":"997e…6134","acceptDocuments":true,"operations":[{"rename":{"target":"EngineLibrary::Engine","newName":"Motor"}}]}'
{"applied":[{"target":"EngineLibrary::Engine","offset":67,"length":6,"oldText":"Engine","newText":"Motor","document":"engine_library.sysml"},
            {"target":"EngineLibrary::Engine","offset":86,"length":6,"oldText":"Engine","newText":"Motor","document":"engine_user.sysml"}],
 "documents":[{"name":"engine_library.sysml","content":"package EngineLibrary {\n\tprivate import ScalarValues::*;\n\tpart def Motor {\n\t\tattribute power : Integer = 150;\n\t}\n}\n"},
              {"name":"engine_user.sysml","content":"package EngineUser {\n\tprivate import EngineLibrary::*;\n\tpart def Car {\n\t\tpart motor : Motor;\n\t}\n}\n"}]}
```

An operation's target must be declared in one document of the model, which by default is the
model's first. The request's `document` names another, by its parse name; a name that is not
one of the model's is `invalid_argument` (the code table below). An edit that touches only
that document answers only that document:

```console
$ … /ApplyEdits -d '{"modelHash":"997e…6134","acceptDocuments":true,"document":"engine_user.sysml","operations":[{"rename":{"target":"EngineUser::Car","newName":"Automobile"}}]}'
{"applied":[{"target":"EngineUser::Car","offset":65,"length":3,"oldText":"Car","newText":"Automobile","document":"engine_user.sysml"}],
 "documents":[{"name":"engine_user.sysml","content":"package EngineUser {\n\tprivate import EngineLibrary::*;\n\tpart def Automobile {\n\t\tpart motor : Engine;\n\t}\n}\n"}]}
```

The same rename sent without `acceptDocuments` is a call failure, before any document is
spliced — the answer every request against a model of several documents received before
`documents` existed:

```console
$ … /ApplyEdits -d '{"modelHash":"997e…6134","operations":[{"rename":{"target":"EngineLibrary::Engine","newName":"Motor"}}]}'
HTTP/1.1 400 Bad Request
{"code":"failed_precondition","message":"the model has 2 documents, and the request reads only content: set accept_documents to have each edited document answered in documents"}
```

A refusal is an in-body failure, HTTP 200, and carries **no** edited notation: neither
`content` nor `documents` nor `applied` is present, only `error`, the `failure` kind, any
`diagnostics`, and for a refused non-cascade delete or a refused rename, what still refers to
the target. `referringElements` spells each referrer as text, `<name> (<document>)`, as it
always has; `referrers` is the same list with `name` and `document` as separate fields, for a
client that opens the file:

```console
$ … /ApplyEdits -d '{"modelHash":"997e…6134","operations":[{"delete":{"target":"EngineLibrary::Engine"}}]}'
{"error":"EngineLibrary::Engine is referenced by EngineUser::Car::motor (engine_user.sysml); delete it with cascade to remove those declarations",
 "failure":"EDIT_FAILURE_DELETE_REFERENCED",
 "referringElements":["EngineUser::Car::motor (engine_user.sysml)"],
 "referrers":[{"name":"EngineUser::Car::motor","document":"engine_user.sysml"}]}
```

`EDIT_FAILURE_REFERENCED_ELSEWHERE` is the kind for a rename, delete or move whose target is
referred to from a document the edit cannot rewrite; a move respells references in its own
document only, so a move of a declaration another document refers to is refused this way, and
`referrers` names each. Every refusal that names a referrer fills both fields: a delete or move
of a referenced declaration, a rename another namespace's declaration would capture
(`EDIT_FAILURE_INVALID_NAME`, naming the namespace the captured reference is read in), and a
move whose reference cannot be respelled (`EDIT_FAILURE_MOVE_REFERENCED`). An empty batch is
`EDIT_FAILURE_NO_OPERATIONS`, with nothing else in the body, as it was before `documents`
existed.

The edited notation is judged at the conformance mode the model was parsed under, which the
model hash already encodes: an edit that writes extension notation into a model parsed with
`strictConformance:true` is refused as `EDIT_FAILURE_RESULT_INVALID` with the extension
reported as an error, where the same edit of the default-mode model is applied and the
extension is a warning. What is judged is the set of documents the batch rewrote, re-analysed
together against the model's other documents as they stand; a document the batch leaves
byte-for-byte unchanged is not re-analysed, so an edit whose only effect on it is through name
resolution — a `part def X` added to a package it imports, taking over a name its `attribute`
was typed by from another import — is applied, and the next parse of the edited documents
reports what the untouched document now says. This is the scope the LSP's
`opensysml/applyModelEdit` validates as well.

Every field named here keeps its number and type in `api/proto/sysml.proto`; `documents`
(7), `referrers` (8), `AppliedEdit.document` (7), `ApplyEditsRequest.document` (3) and
`ApplyEditsRequest.acceptDocuments` (4) were appended, and the new `EditFailure` value
appended after the last, so a generated client of the previous schema decodes every answer
above and ignores what it does not know — and, never setting `acceptDocuments`, is answered
exactly as before.

The other direction is a capability: a service advertises `edit_documents` in `GetServerInfo`
when it fills `documents`, `referrers` and each applied edit's `document`, edits a model of
several documents for a request setting `acceptDocuments`, and targets the document a request
names. A service without it — one built before those fields existed — edits a model of one
document and answers `content` alone, with those three fields omitted; it refuses a model of
several with `FAILED_PRECONDITION` whatever the request sets, and a request naming a `document`
with `UNIMPLEMENTED` naming the capability. So a client written against `documents` checks the
capability before reading them, and reads `content` from a service that lacks it, rather than
taking an empty `documents` for a batch that rewrote nothing.

## Minimal clients: four illustrations

The four snippets below are **illustrations, not shipped code**. They are not in `client/`, not
tested, and not run by CI; they exist to show how short a correct decoder is in each language
and where its pitfalls lie. The Julia and MATLAB illustrations have since grown into the shipped
[`client/julia`](../../client/julia/OpenSysML/README.md) and
[`client/matlab`](../../client/matlab/README.md) packages, which run the conformance suite
through their own APIs; the R and C snippets remain illustrations only. A real client for any of
these languages is one that passes the scenarios in `conformance/scenarios/*.json` through its
own public API, as every shipped client
does ([Every client runs the same conformance suite](clients.md#every-client-runs-the-same-conformance-suite)).
Each snippet is a POST helper that classifies Connect errors, plus the `Value` decoder from
[The decoding rule](#the-decoding-rule); everything else (the `Instance` table, verdicts,
query rows) is plain JSON once the `Value`s inside it are decoded.

### R (`httr2` + `jsonlite`)

```r
library(httr2); library(jsonlite)
`%||%` <- function(a, b) if (is.null(a)) b else a

sysml_post <- function(method, body, base = "http://localhost:50051") {
  resp <- request(paste0(base, "/sysml.SysMLService/", method)) |>
    req_body_json(body, auto_unbox = TRUE, digits = NA) |>   # wrap lists in I() to keep them arrays
    req_error(is_error = function(r) FALSE) |>
    req_perform()
  out <- resp_body_json(resp, simplifyVector = FALSE)
  if (resp_status(resp) != 200) stop(sprintf("connect %s: %s", out$code, out$message))
  out
}

decode_value <- function(v) {
  if (is.null(v)) return(structure(list(), class = "sysml_no_result"))
  switch(names(v)[[1]],
    intValue    = bit64::as.integer64(v$intValue),          # never as.numeric: exact past 2^53
    realValue   = as.double(v$realValue),                    # "NaN"/"Infinity" strings decode via as.double too
    boolValue   = v$boolValue,
    stringValue = v$stringValue,
    instanceId  = structure(v$instanceId, class = "sysml_instance_ref"),
    sequence    = lapply(v$sequence$elements, decode_value),
    null        = if (nzchar(v[["null"]])) stop("unsupported value: ", v[["null"]]) else NULL,
    unset       = structure(NA, class = "sysml_unset"),
    quantity    = list(magnitude = if (!is.null(v$quantity$intMagnitude))
                                     bit64::as.integer64(v$quantity$intMagnitude)
                                   else as.double(v$quantity$realMagnitude),
                       unit = v$quantity$unit, unit_term = v$quantity$unitTerm),
    enumLiteral = structure(v$enumLiteral$literalId, class = "sysml_enum_literal",
                            enumeration = v$enumLiteral$enumerationId, label = v$enumLiteral$name),
    complex     = complex(real = v$complex$real %||% 0, imaginary = v$complex$imaginary %||% 0),
    stop("unknown Value arm: ", names(v)[[1]]))
}

m <- sysml_post("ParseSources", list(documents = list(list(name = "a.sysml", content = "package A { attribute x = 1; }"))))
decode_value(sysml_post("Evaluate", list(modelHash = m$modelHash, expression = "A::x"))$result)
```

### Julia (`HTTP.jl` + `JSON.jl`)

```julia
using HTTP, JSON

function sysml_post(method, body; base = "http://localhost:50051")
    r = HTTP.post("$base/sysml.SysMLService/$method",
                  ["Content-Type" => "application/json"], JSON.json(body); status_exception = false)
    out = JSON.parse(String(r.body))
    r.status == 200 || error("connect $(out["code"]): $(out["message"])")
    out
end

struct Unset end
struct InstanceRef; id::Int64; end
struct EnumLiteral; literal::String; enumeration::String; label::String; end
struct Quantity; magnitude::Union{Int64,Float64}; unit::String; term::Any; end

asreal(x) = x isa AbstractString ? parse(Float64, x) : Float64(x)   # "NaN"/"Infinity" and 20 → 20.0

function decode_value(v)
    v === nothing && return missing                       # no result at all
    haskey(v, "intValue")    && return parse(Int64, v["intValue"])
    haskey(v, "realValue")   && return asreal(v["realValue"])
    haskey(v, "boolValue")   && return v["boolValue"]::Bool
    haskey(v, "stringValue") && return v["stringValue"]::String
    haskey(v, "instanceId")  && return InstanceRef(parse(Int64, v["instanceId"]))
    haskey(v, "sequence")    && return [decode_value(e) for e in get(v["sequence"], "elements", [])]
    haskey(v, "null")        && return isempty(v["null"]) ? nothing : error("unsupported value: ", v["null"])
    haskey(v, "unset")       && return Unset()
    haskey(v, "quantity")    && (q = v["quantity"]; return Quantity(
        haskey(q, "intMagnitude") ? parse(Int64, q["intMagnitude"]) : asreal(q["realMagnitude"]),
        get(q, "unit", ""), get(q, "unitTerm", nothing)))
    haskey(v, "enumLiteral") && (l = v["enumLiteral"]; return EnumLiteral(l["literalId"], l["enumerationId"], l["name"]))
    haskey(v, "complex")     && (c = v["complex"]; return complex(asreal(get(c, "real", 0.0)), asreal(get(c, "imaginary", 0.0))))
    error("unknown Value arm: ", first(keys(v)))
end

m = sysml_post("ParseSources", Dict("documents" => [Dict("name" => "a.sysml", "content" => "package A { attribute x = 1; }")]))
decode_value(get(sysml_post("Evaluate", Dict("modelHash" => m["modelHash"], "expression" => "A::x")), "result", nothing))
```

### MATLAB (`matlab.net.http` + `jsondecode`)

`webwrite` posts the same body and decodes a 200 the same way, but it raises on any other
status without exposing the `{"code","message"}` body, so the helper uses `matlab.net.http`.

```matlab
function out = sysmlPost(method, body, base)
    if nargin < 3, base = 'http://localhost:50051'; end
    import matlab.net.http.*
    req = RequestMessage('POST', HeaderField('Content-Type', 'application/json'), MessageBody(jsonencode(body)));
    resp = req.send(sprintf('%s/sysml.SysMLService/%s', base, method), HTTPOptions('ConvertResponse', false));
    out = jsondecode(char(resp.Body.Data));       % 404/405/415 answer plain text; this would raise on it
    if resp.StatusCode ~= 200, error('sysml:connect', 'connect %s: %s', out.code, out.message); end
end

function val = decodeValue(v)
    % jsondecode turns {"intValue":"4"} into a struct with field intValue = '4' (char),
    % {"realValue":20} into double 20, and an array of mixed objects into a cell array.
    if isempty(v), val = []; return; end                  % no result (field absent)
    kind = fieldnames(v); kind = kind{1};
    asInt64 = @(s) int64(java.lang.Long.parseLong(s));   % exact; str2double/sscanf go through double
    asReal  = @(x) realOf(x);
    switch kind
        case 'intValue',    val = asInt64(v.intValue);
        case 'realValue',   val = asReal(v.realValue);
        case 'boolValue',   val = logical(v.boolValue);
        case 'stringValue', val = string(v.stringValue);
        case 'instanceId',  val = struct('instanceRef', asInt64(v.instanceId));
        case 'sequence',    el = {};
                            if isfield(v.sequence, 'elements'), el = v.sequence.elements; end
                            if isstruct(el), el = num2cell(el); end    % uniform objects arrive as a struct array
                            val = cellfun(@decodeValue, el, 'UniformOutput', false);
        case 'null',        if ~isempty(v.null), error('sysml:unsupported', '%s', v.null); end; val = missing;
        case 'unset',       val = struct('unset', true);                % test isfield(val,'unset'), never val.unset
        case 'quantity',    q = v.quantity;
                            if isfield(q, 'intMagnitude'), mag = asInt64(q.intMagnitude); else, mag = asReal(q.realMagnitude); end
                            val = struct('magnitude', mag, 'unit', q.unit, 'unitTerm', q.unitTerm);
        case 'enumLiteral', val = struct('literalId', v.enumLiteral.literalId, 'enumerationId', v.enumLiteral.enumerationId, 'name', v.enumLiteral.name);
        case 'complex',     re = 0; im = 0;                             % each omitted when zero
                            if isfield(v.complex, 'real'), re = v.complex.real; end
                            if isfield(v.complex, 'imaginary'), im = v.complex.imaginary; end
                            val = complex(re, im);
        otherwise,          error('sysml:unknownArm', 'unknown Value arm: %s', kind);
    end
end

function x = realOf(x)                        % "NaN", "Infinity", "-Infinity" arrive as char
    if ischar(x) || isstring(x)
        switch char(x), case 'Infinity', x = Inf; case '-Infinity', x = -Inf; otherwise, x = NaN; end
    else
        x = double(x);
    end
end
```

### C (`libcurl` + `cJSON`)

```c
#include <curl/curl.h>
#include <cjson/cJSON.h>
#include <stdlib.h>
#include <string.h>

struct buf { char *p; size_t n; };
static size_t grow(void *d, size_t s, size_t n, void *u) {
    struct buf *b = u; b->p = realloc(b->p, b->n + s * n + 1);
    memcpy(b->p + b->n, d, s * n); b->n += s * n; b->p[b->n] = 0; return s * n;
}

/* Returns the parsed body; *status receives the HTTP status. On != 200 the body is {"code","message"}. */
cJSON *sysml_post(const char *base, const char *method, const char *json, long *status) {
    char url[512]; snprintf(url, sizeof url, "%s/sysml.SysMLService/%s", base, method);
    struct buf b = {0}; CURL *c = curl_easy_init();
    struct curl_slist *h = curl_slist_append(NULL, "Content-Type: application/json");
    curl_easy_setopt(c, CURLOPT_URL, url); curl_easy_setopt(c, CURLOPT_HTTPHEADER, h);
    curl_easy_setopt(c, CURLOPT_POSTFIELDS, json);
    curl_easy_setopt(c, CURLOPT_WRITEFUNCTION, grow); curl_easy_setopt(c, CURLOPT_WRITEDATA, &b);
    if (curl_easy_perform(c) != CURLE_OK) { *status = 0; return NULL; }
    curl_easy_getinfo(c, CURLINFO_RESPONSE_CODE, status);
    curl_slist_free_all(h); curl_easy_cleanup(c);
    cJSON *out = cJSON_Parse(b.p); free(b.p); return out;   /* NULL for the plain-text 404/405/415 bodies */
}

enum kind { NO_RESULT, INT, REAL, BOOL, STR, INSTANCE, SEQ, NUL, QUANTITY, ENUM, UNSET, COMPLEX, UNKNOWN };
struct value { enum kind kind; long long i; double d; const char *s; const cJSON *node; };

/* Discriminate by the single key present. Strings for int64; doubles may be "NaN"/"Infinity". */
struct value decode_value(const cJSON *v) {
    struct value r = { NO_RESULT, 0, 0, NULL, v };
    if (!v) return r;
    const cJSON *a;
    if ((a = cJSON_GetObjectItem(v, "intValue")))    { r.kind = INT;  r.i = strtoll(a->valuestring, NULL, 10); }
    else if ((a = cJSON_GetObjectItem(v, "realValue")))   { r.kind = REAL; r.d = cJSON_IsString(a) ? strtod(a->valuestring, NULL) : a->valuedouble; }
    else if ((a = cJSON_GetObjectItem(v, "boolValue")))   { r.kind = BOOL; r.i = cJSON_IsTrue(a); }
    else if ((a = cJSON_GetObjectItem(v, "stringValue"))) { r.kind = STR;  r.s = a->valuestring; }
    else if ((a = cJSON_GetObjectItem(v, "instanceId")))  { r.kind = INSTANCE; r.i = strtoll(a->valuestring, NULL, 10); }
    else if ((a = cJSON_GetObjectItem(v, "sequence")))    { r.kind = SEQ;  r.node = cJSON_GetObjectItem(a, "elements"); /* recurse over cJSON_ArrayForEach */ }
    else if ((a = cJSON_GetObjectItem(v, "null")))        { r.kind = NUL;  r.s = a->valuestring; /* non-empty: unsupported value, not null */ }
    else if ((a = cJSON_GetObjectItem(v, "unset")))       { r.kind = UNSET; }
    else if ((a = cJSON_GetObjectItem(v, "quantity")))    { r.kind = QUANTITY; r.node = a; /* intMagnitude (string) or realMagnitude; unit; unitTerm */ }
    else if ((a = cJSON_GetObjectItem(v, "enumLiteral"))) { r.kind = ENUM; r.s = cJSON_GetObjectItem(a, "literalId")->valuestring; r.node = a; }
    else if ((a = cJSON_GetObjectItem(v, "complex")))     { r.kind = COMPLEX; r.node = a; /* "real"/"imaginary", each absent when 0 */ }
    else { r.kind = UNKNOWN; r.s = v->child ? v->child->string : ""; /* a newer service than this decoder */ }
    return r;
}
```

A conformance-grade client in any of these languages additionally: reads `error` before
`result` on every response; keeps `instanceId` scoped to its response; classifies Connect codes
per the table above; and re-parses on `model not found:`. The scenarios that pin all of this
are `conformance/scenarios/*.json`; run them through your client's public API, as
`make conformance` does for the shipped ones.

## Further reading

- [Service transports](service-transports.md) — the four protocols on one port, capabilities,
  and why protobuf bodies are the default for a generated client
- [Client libraries](clients.md) — the shipped clients, their lifecycle modes and the
  conformance suite they share
- [Go packages](api.md) — `Query` and document-query semantics this page's examples exercise
- `api/proto/sysml.proto` — the authority for every field name and type on this page