9. Conformance & Verification (fleetmesh_core.conformance)
The fleetmesh_core.conformance package provides tools, vectors, and test
harnesses to formally verify conformance against the Fleetmesh protocol specifications.
9.1. Conformance Engine
The conformance protocol: how a harness drives any implementation.
A harness and an implementation under test speak JSON lines over a pipe. One request per line in, one reply per line out, matched by id:
-> {“id”: 1, “op”: “fingerprint.of”, “args”: {“ids”: [“00..01”, “00..02”]}} <- {“id”: 1, “result”: “9f3c…”}
-> {“id”: 2, “op”: “no.such.op”, “args”: {}} <- {“id”: 2, “error”: {“code”: “unsupported”, “message”: “no.such.op”}}
The first request is always hello with no args; the reply names the implementation and lists the ops it answers. Ops the implementation does not list are SKIPPED by the harness, never failed - a partial implementation gets an honest score for the planes it speaks. Three error codes exist:
unsupported the op is not in this implementation’s catalogue bad_args the args did not have the shape the catalogue says internal the implementation fell over; always a bug in it
An op whose protocol answer can be a refusal (a malformed event, a rejected URL) returns that refusal as its RESULT in the shape the catalogue states - usually {“refused”: “<why>”} - so a harness can pin the reason. Protocol errors are reserved for the harness-implementation contract itself.
Bytes are hex strings; there are no other encodings. Every value is plain JSON so an implementation in any language can take part. The catalogue of ops, their plane and their argument shapes lives in conformance_ops.py; this module is the wire and the loop. Run the reference implementation as
python3 -m fleetmesh_core.conformance # from a checkout with the ref symlink python3 -m fleetmesh_core.conformance # from the core package
- exception fleetmesh_core.conformance.conformance.ArgError[source]
Bases:
ValueErrorRaised by a handler when args is not what the catalogue promised.
- exception fleetmesh_core.conformance.conformance.Refused[source]
Bases:
ExceptionA protocol-level refusal a handler wants returned as {‘refused’: why}.
- fleetmesh_core.conformance.conformance.answer(ops, request)[source]
Answer one request against a catalogue. Never raises.
9.2. Conformance Operations Catalogue
The conformance op catalogue: every operation a harness may ask of a node.
Each op is a name, the plane it belongs to (docs/implementing.md), one line about it and a handler that takes the JSON args and returns a JSON result. Names are <domain>.<verb>; the domain is a wire surface or a mechanism named in the spec, never a Python module. Argument shapes are the vector files’ shapes - fleetmesh.org/scripts/conform.py derives its requests straight from vectors/*.json, so the catalogue and the vectors cannot say different things.
Everything that crosses this boundary is plain JSON: bytes are hex, bounds and items are lists, refusals are {“refused”: why} results (see conformance.py). This file is marshalling only; the mechanisms live in their own modules.
The catalogue is NOT inside the schema digest yet: op names may still move while a second implementation pushes on them. They are promoted into schema/ at the first non-draft tag.
9.3. Test Harness
Line harness for fleetmesh_core/storage/negentropy.py, speaking hoytech’s conformance protocol.
The negentropy project drives every implementation it tests through one stdin protocol: item,<created>,<id> to load, seal, then initiate or msg,<hex>, answering with have,<id>, need,<id>, msg,<hex> or done. Its own harnesses are test/js/harness.js and test/cpp/harness.cpp; this is the same program for ours, so the reference’s driver can put the two implementations on opposite ends of a reconciliation without either knowing.
python3 -m fleetmesh_core.conformance.harness < commands
Only the client is told anything by the protocol, so have and need are printed by whichever side received initiate.
9.4. Conformance Errors
The one base class every error this library raises on purpose shares.
The modules each define their own exception, and each keeps the standard base that makes it behave where it is caught today: Malformed is still a ValueError, Reached is still a RuntimeError, Declined is still a plain Exception. What was missing was a name for “this library refused”, so a caller that does not care which refusal could catch one thing instead of six - and a bug (TypeError, KeyError) could keep falling through, which is what distinguishes a refusal from a defect.
Standard library only. Nothing here reads the network or the wall clock.
- exception fleetmesh_core.conformance.errors.FleetmeshError[source]
Bases:
ExceptionBase of every exception fleetmesh_core raises deliberately.
Subclasses add it beside their existing base (class Malformed( FleetmeshError, ValueError)) so no except ValueError anywhere stops matching. Catching FleetmeshError means “the library declined or could not parse”; anything else escaping is a defect to be fixed, not caught.