Encoding · Types · Structs · Enumerations · Constants · Vocabulary · Refusals · Protocol
Schema
One definition; this page and every encoder are emitted from it. Nothing below is written by hand, and each rule tag links the construct to the profile that admits it.
Encoding [DEF-E1]
| setting | value | rule |
|---|
escape | minimal | [DEF-E2] |
indent | 2 | [DEF-E3] |
map_keys | utf8-bytes | [DEF-E4] |
numbers | integer-decimal | [DEF-E5] |
opaque | verbatim | [DEF-E6] |
terminator | newline | [DEF-E7] |
duplicate_keys | refuse | [DEF-E8] |
depth_limit | 64 | [DEF-E9] |
Types
| kind | types |
|---|
| built in | bool i64 string |
| declared below | Caller Decision HostAllowance Observation |
| container [DEF-T3] | list<string> |
| repeated record [DEF-A9] | list<Alias> list<Ask> list<Family> list<HostState> |
Named types [DEF-T2]
One spelling is written [DEF-G2] and a wider set is read [DEF-G1]; the width between them is the interoperability guarantee.
| name | is | written | read |
|---|
timestamp | string | rfc3339-micros | rfc3339-wide |
Structs [DEF-T1]
A field is required, or says when it is omitted [DEF-A4]. Each struct says on its own what it does with a field name it has never heard of [DEF-A7]. A wire name never moves; where a language must spell it differently the field says so [DEF-A2].
HostAllowance
unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | hosts | list<string> | required | — |
PickRequest
the document [DEF-A1] · unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | model | string | required | — |
| 2 | fresh | bool | required | — |
| 3 | allowed | HostAllowance | optional · omitted when absent | — |
Caller
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | user_description | string | required | — |
| 2 | path_description | string | required | — |
Observation
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | caller | Caller | required | — |
| 2 | took_ms | i64 | required | — |
| 3 | cache_age_ms | i64 | required | — |
Alias
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | host | string | required | — |
| 2 | name | string | required | — |
| 3 | resident | bool | required | — |
| 4 | servable | bool | required | — |
Family
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | family | string | required | — |
| 2 | names | list<Alias> | required | — |
ModelsSnapshot
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | observation | Observation | required | — |
| 2 | models | list<Family> | required | — |
HostState
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | host | string | required | — |
| 2 | base | string | required | — |
| 3 | up | bool | required | — |
| 4 | why | string | required | — |
| 5 | installed | i64 | required | — |
| 6 | resident | list<string> | required | — |
| 7 | servable | bool | required | — |
Ask
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | at | timestamp | required | — |
| 2 | caller | string | required | — |
| 3 | user | string | required | — |
| 4 | model | string | required | — |
| 5 | family | string | required | — |
| 6 | verdict | string | required | — |
| 7 | host | string | required | — |
HostsSnapshot
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | observation | Observation | required | — |
| 2 | hosts | list<HostState> | required | — |
| 3 | doubled | list<string> | required | — |
| 4 | asked | list<Ask> | required | — |
Decision
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | asked | string | required | — |
| 2 | family | string | required | — |
| 3 | verdict | string | required | — |
| 4 | host | string | required | — |
| 5 | model | string | required | — |
| 6 | endpoint | string | required | — |
| 7 | installed_on | list<string> | required | — |
| 8 | authorised | HostAllowance | optional · omitted when absent | — |
| 9 | withheld | list<string> | required | — |
| 10 | loads | i64 | required | — |
| 11 | why | string | required | — |
PickResult
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | observation | Observation | required | — |
| 2 | decision | Decision | required | — |
Constants [DEF-A6]
| name | type | value |
|---|
verdicts | list<string> | resident, would-load, unservable, not-here, unparseable, unauthorised |
Refusal words [DEF-R1]
| order | word | stage |
|---|
| 1 | malformed | grammar |
| 2 | bad_string | grammar |
| 3 | number_spelling | grammar |
| 4 | wrong_type | grammar |
| 5 | bad_timestamp | grammar |
| 6 | depth_exceeded | grammar |
| 7 | duplicate_key | grammar |
| 8 | duplicate_field | structure |
| 9 | unknown_field | structure |
| 10 | missing_field | structure |
| 11 | trailing_bytes | document |
Service Router [DEF-S1]
Read existing model hosts and choose where a caller may ask. Decisions do not enforce access to hosts outside the router.
Wire identity: abstraction.router/router@1
Frames carry version, service, method and typed arguments. Transport owns framing, associated exchanges, deadlines and connections. Unknown version/service/method and malformed arguments are rejected before invoking a handler. One-way WriteFrame success means local submission, not remote acceptance or persistence.
Request-response methods use ExchangeFrame. Replies carry version, service, method, ok and payload; success payload contains typed value (or an empty object for void). Error payload contains nonempty code and message, which may be empty. ServiceError preserves unknown codes. Unexpected handler failures become handler_error without private details; invalid results become invalid_result. Clients validate reply identity and result before exposing it. A malformed frame or transport failure remains a local error; the transport must associate each response with its exchange. C++ dispatchers are pure protocol bindings, not listening servers.
Read model families and aliases. Fresh requests survey the existing hosts.
Models
request-response ModelsSnapshot
- Argument 1:
bool fresh (required, including zero/false/empty)
Read host residency, duplicate families and routing audit. GPU cost is outside this subset.
Hosts
request-response HostsSnapshot
- Argument 1:
bool fresh (required, including zero/false/empty)
Choose a permitted host without loading any model. Missing allowance permits all hosts; an explicit empty allowance permits none. Attribution comes from the bound caller.
Pick
request-response PickResult
- Argument 1:
PickRequest request (required, including zero/false/empty)