Schema
Use this reference to inspect fields, methods, accepted values and failure outcomes. For setup and working examples, start with the API guide.
Definition: abstraction.router
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
Handler error codes, declared by router_error_codes: internal, invalid_request, caller_refused, unknown_operation, unavailable, forbidden. Generated bindings name each as a ServiceErrorCode member beside the dispatcher's own codes.
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. Who holds the card is abstraction.resource/table@1, 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)
List the families a caller may ask for a profile, one name each and the conservative context, after the request's placement and answer reserve. Gated by abstraction.router/inventory.read.
Offer
request-response OfferSnapshot
- Argument 1:
OfferRequest request (required, including zero/false/empty)
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 | AvailabilityCause ContextSource OfferOutcome Placement bool i64 string |
| declared below | Caller Decision HostAllowance Observation |
| container [DEF-T3] | list<string> |
| repeated record [DEF-A9] | list<Alias> list<Ask> list<Component> list<Family> list<HostState> list<Offer> |
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 | — |
| 4 | profile | string | optional · omitted when zero | — |
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 | — |
| 5 | hosted | bool | optional · omitted when zero | — |
| 6 | profiles | list<string> | optional · omitted when zero | — |
| 7 | held_in | list<string> | optional · omitted when zero | — |
| 8 | context_length | i64 | optional · omitted when zero | — |
| 9 | effective_context_length | i64 | optional · omitted when zero | — |
Component
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | store | string | required | — |
| 2 | role | string | required | — |
| 3 | name | string | optional · omitted when zero | — |
Family
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | family | string | required | — |
| 2 | names | list<Alias> | required | — |
| 3 | held_in | list<string> | optional · omitted when zero | — |
| 4 | family_source | string | optional · omitted when zero | — |
| 5 | components | list<Component> | optional · omitted when zero | — |
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 | — |
| 8 | hosted | bool | optional · omitted when zero | — |
| 9 | wire | string | optional · omitted when zero | — |
| 10 | credential | string | optional · omitted when zero | — |
| 11 | declared_by | string | optional · omitted when zero | — |
| 12 | profiles | list<string> | optional · omitted when zero | — |
| 13 | domain | string | optional · omitted when zero | — |
| 14 | availability_cause | AvailabilityCause | optional · omitted when absent | — |
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 | — |
OfferRequest
unknown fields refuse
| id | field | type | presence | named elsewhere |
|---|
| 1 | profile | string | required | — |
| 2 | placement | Placement | required | — |
| 3 | reserve | i64 | required | — |
| 4 | fresh | bool | required | — |
Offer
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | family | string | required | — |
| 2 | names | list<string> | required | — |
| 3 | servers | list<string> | required | — |
| 4 | context | i64 | required | — |
| 5 | context_source | ContextSource | required | — |
| 6 | input | i64 | required | — |
| 7 | unknown | list<string> | optional · omitted when zero | — |
OfferSnapshot
unknown fields grant
| id | field | type | presence | named elsewhere |
|---|
| 1 | observation | Observation | required | — |
| 2 | offers | list<Offer> | required | — |
| 3 | outcome | OfferOutcome | required | — |
Enumerations [DEF-T5]
Enum fields carry JSON strings containing exact member wire spellings, never numeric IDs. Unknown names are preserved with grant and refused as bad_enum with refuse on read and write. Optional absent fields preserve presence separately from an empty string.
An enumeration is a closed vocabulary of wire names, and each one says on its own what a reader does with a member it has never heard of [DEF-A5].
AvailabilityCause
a member this reader does not know is grant
| id | member | wire |
|---|
| 1 | transport_unavailable | transport_unavailable |
| 2 | credential | credential |
| 3 | rights | rights |
| 4 | configuration | configuration |
| 5 | malformed | malformed |
| 6 | unknown | unknown |
| 7 | other | other |
Placement
a member this reader does not know is refuse
| id | member | wire |
|---|
| 1 | local | local |
| 2 | hosted | hosted |
| 3 | any | any |
ContextSource
a member this reader does not know is grant
| id | member | wire |
|---|
| 1 | effective | effective |
| 2 | maximum | maximum |
| 3 | default | default |
| 4 | unknown | unknown |
| 5 | none | none |
OfferOutcome
a member this reader does not know is refuse
| id | member | wire |
|---|
| 1 | offered | offered |
| 2 | invalid | invalid |
| 3 | unavailable | unavailable |
| 4 | forbidden | forbidden |
| 5 | not_permitted | not_permitted |
Constants [DEF-A6]
| name | type | value |
|---|
profiles | list<string> | chat, embed, transcription, speech, image |
verdicts | list<string> | resident, would-load, hosted, unservable, not-here, unparseable, unauthorised, no-host |
wire_kinds | list<string> | openai-compatible, anthropic-messages, deepgram-prerecorded, elevenlabs-stream, stability-v2beta, fal-queue, replicate-predictions, openai-realtime, oa-remote@1 |
credential_consumers | list<string> | abstraction.router/router@1 |
router_error_codes | list<string> | internal, invalid_request, caller_refused, unknown_operation, unavailable, forbidden |
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 | bad_enum | structure |
| 12 | trailing_bytes | document |