mesh-contracts/README.md

mesh-contracts

The mesh's seat contracts (novox/hq ADR 0608 §5, ADR 0613, ADR 0620, ADR 0625, ADR 0627; design 26 A seat's definition): one language-neutral definition per seat, the Go and TypeScript code generated from it, and the client of a seat whose callers share logic over it. This repository holds contracts only and no seat: a seat's holder implements its contract, and no holder's code lives here.

Where a seat's code goes

• The definition, written by hand: seats/<seat>/seat.json, its fixtures in seats/<seat>/fixtures/, and the parts several seats include whole in parts/ (none here now: the registry seats' part is mesh-delivery-contracts'). mesh-sdk's seatdef is the one reader of the format; the indexer and the generators use it.
• A state, in the definition's states (ADR 0608 §1, ADR 0634 §6): {name, template, writer, key-forms, history, max-age-days, description}. template is one of ADR 0595's six (state, events, work-queue, log, objects, ledger); writer is holder (the default) or caller; each key form is {key, value, description}, the key a pattern of named parts between angle brackets (<asker>.<id>) and the value its JSON Schema. A definition names no holder module: a reader takes the holder from its own manifest's reads. A fixture of a state is state:<name>/<key>.
• The seat set, generated: go/seats (module git.novox.be/novox/mesh-contracts/go), every seat's name, scope, verbs and provision at the seat list's grain (ADR 0625 §2). mesh-sdk's catalogue is its only importer in mesh-sdk. A change of it rebuilds every importer of the seat set. Its npm package is ts/ (@novox/mesh-contracts, the seat list alone).
• A seat defined whole, generated: go/seats/<seat without hyphens>, a Go module of its own importing nothing, holding the seat's verbs, events and subjects, its message types and a test of its fixtures (ADR 0625 §1). A module imports only the seats it uses, so a change of one seat rebuilds only its users. Its npm package is ts/seats/<seat without hyphens> (@novox/mesh-contracts-<seat>), holding the parts it includes whole: the indexer counts the npm package a lock resolves, so here too a module is rebuilt only for the seats it uses.
• A seat's client, written by hand: go/clients/<seat without hyphens>client, a Go module of its own, only where two or more callers share logic over the seat (ADR 0625 §4, ADR 0627 §1): operator-channel's (checking an ask, its digest, a warrant's, and an asking module's keeping of its asks), node-engine's (checking compose-candidate's ask and answer). A client imports its own seat's contract and mesh-sdk's runtime, never another seat's client, and names no module's subject or tool.
• Not here: the value layouts of seats not yet defined whole (they stay in mesh-sdk until their domain moves, ADR 0625 §9), and a role only one module could ever play (that module's own tools and events, ADR 0625 §8).

How it is checked

Every file under go/ and ts/ outside go/clients/ is written by the generator (seatgen, the source of the Go and Node build modules' generate step) and compared on every build: a hand-written file there fails, named (ADR 0625 §5). seatgen -check (mesh-catalog modules/mesh-build-go/buildstep/cmd/seatgen) also runs the client check (each client is for a seat defined whole, a module of its own, importing only its seat's contract and mesh-sdk) and checks module.json's Go and npm package artifacts against the tree.

Made by the mesh from the gitea module's config value repositories (novox/hq ADR 0428). Main takes no push: a change reaches it by a pull request whose mesh/check passed: the checker's verdict on its head merged onto main, its tests run by their language's convention (novox/hq ADR 0447, ADR 0445).