Interface Gen
iface-gen turns the schemas published on this site into code. The schemas listed under Schemas (for example
Discovery) each describe the messages of one protocol, every message annotated with the
JSON_Msg base it extends (x-base: JSON_Msg, JSON_Eff, JSON_Ack, or none for a plain
JSON object). Each schema file is published byte-exact under https://root-interface.se/protocols/<sha256>; the hash
is the schema’s identity, so two participants speak the same dialect when their hashes match.
The two packages are the generators, one per language. Each reads a schema and emits one typed interface for it:
-
cpp-iface-genemits a C++ header per schema, with a class per message extending thecpp-json-msgbase classes. -
npm-iface-genemits a granular npm package per schema, whose message namespaces delegate to@rootintf/json-msg.
Per message the interface offers validate, which checks only the message’s own fields (the base is validated once,
upstream in the responder chain) and is the drop primitive of a participant, and a constructor (merge, or
create_with_cause_merge for an effect) that produces a real envelope. Both generators take every name from the
schema’s $id segments, so a C++ and a JS participant generated from the same schema agree on all of them.
Schemas and generators meet in a project’s ifacegenconfig.json: it lists the schemas the participant speaks, each
pinned by the SHA-256 shown on its schema page, and the generator verifies the schema bytes against that pin before
emitting anything. The same pins are emitted as an introspection table, interface name to SHA-256, which is the
interfaces map a Discovery message carries, so a participant declares exactly the dialects it was generated
against. Nothing per protocol is written by hand: when a schema changes, its hash changes, the pin is updated, and
the interfaces are regenerated.