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-gen emits a C++ header per schema, with a class per message extending the cpp-json-msg base classes.

  • npm-iface-gen emits 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.

Implementations