Skip to content

Generated C++ code

python -m wireforge.generate <project> -o <dir> [--tests] validates the project and writes, below <dir>/<project>/:

File Content
user_prelude.hpp user_includes headers and prelude lines; static_asserts that application constants match the model (per profile via WIREFORGE_PROFILE_<name>)
interfaces/<name>.hpp per interface, in namespace <ns>::<interface>::inline v<major>_<minor>: version constants, message ids and per-interface encodings, frame/buffer sizes, FrameFormat/HeaderLayout, Decoder/Dispatcher/Link types, Header, encode_frame(), decode_header(), Handler (on<Message>Raw, on<Message>Received), Receiver, Endpoint
model.hpp define constants, checksum types, enums with is_valid(), types and messages, validate(), min_wire_size(), max_wire_size(), encode()/decode(), serialize()/deserialize()

Include directories: <dir>, runtime/include and the project's user_includes.include_dirs. Generated files are regenerated only when their content changes. The output does not depend on the profile: build a profile by passing its defines (-DPLATFORM_B=1 -DMAX_TRACKS=5 ...) and -DWIREFORGE_PROFILE_<name>.

Data types (decision D28)

namespace demo::telemetry {
struct SensorReading {
    std::uint8_t sensorId{1U};
    SensorState state{SensorState::ready};
    float temperature{20.0F};
    Vec3 accel{};
    wireforge::StaticVector<std::uint16_t, 4U> samples;   // count field sampleCount is wire-only
};
constexpr wireforge::Status validate(const SensorReading& value) noexcept;
constexpr std::size_t min_wire_size(wireforge::TypeTag<SensorReading>) noexcept;
constexpr std::size_t max_wire_size(wireforge::TypeTag<SensorReading>) noexcept;
}
- Plain aggregates: SensorReading{} holds the model defaults. Each struct is documented with Defined in <file>:<line> (<JSON pointer>) and each member with its file:line (traceability, docs/SAFETY.md). A project with a requirements catalog adds Requirements: <HLR ids>; <LLR ids> to every struct, enum, checksum and interface; a project without one generates exactly the same code as before. - Fixed arrays are std::array<T, N>, counted or fill arrays wireforge::StaticVector<T, N> (an optional field is StaticVector<T, 1>), char arrays wireforge::FixedString<N>. - const, reserved, checksum fields and count fields used only as occurs.count: name exist only on the wire. - validate() checks min/max (also opaque user constants), enum membership, bit widths, element counts and nested values; it returns the first error. - Sizes are constexpr and follow the build's defines and #if blocks; call them as max_wire_size(wireforge::type_tag<SensorReading>).

Requirement vectors

With a vectors section the test project also has hlr_vector_test.cpp (TEST(HlrVector, <name>), one per profile a vector applies to) and the self-test checks the same vectors without a test framework. Each test decodes or encodes the vector's bytes and compares with the values written in the model, never with the reference codec, and records the requirement ids of the vector (docs/SCHEMA_SPEC.md section 18). A project without vectors gets neither file.

User types

A user_types entry declares a field type WireForge never looks inside — only its fixed size_bytes:

user_types:
  Fixed16:
    cpp: app::Fixed16
    size_bytes: 2
    include: app/fixed16.hpp
WireForge emits only the size query, into user_prelude.hpp:
namespace wireforge {
constexpr std::size_t max_wire_size(TypeTag<app::Fixed16> /*tag*/) noexcept { return 2U; }
constexpr std::size_t min_wire_size(TypeTag<app::Fixed16> /*tag*/) noexcept { return 2U; }
} // namespace wireforge
The user writes the type itself (app/fixed16.hpp, included by user_prelude.hpp) plus its encode/decode, found by ADL exactly like a generated struct's:
namespace app {
struct Fixed16 { std::int16_t raw{}; };
void encode(const Fixed16& value, wireforge::Encoder& encoder) noexcept {
    const auto bytes = std::bit_cast<std::array<std::uint8_t, 2U>>(value.raw);
    encoder.write_bytes(wireforge::Span<const std::uint8_t>(bytes));
}
void decode(Fixed16& value, wireforge::Decoder& decoder) noexcept {
    std::array<std::uint8_t, 2U> bytes{};
    decoder.read_bytes(wireforge::Span<std::uint8_t>(bytes));
    value.raw = std::bit_cast<std::int16_t>(bytes);
}
}
A field of this type (occurs, arrays and nesting inside other types all work) is used exactly like a struct field; Encoder::write_bytes/Decoder::read_bytes (docs/RUNTIME.md) copy bytes onto/from the wire unchanged, leaving the type's own encoding entirely up to these two functions. Fixed16 must be default-constructible.

C99 code (--language c)

wireforge generate <project> -o <dir> --language c writes <project>/model.h and <project>/model.c instead of the C++ headers; wireforge test ... --language c also writes, builds and runs a GoogleTest project that calls the C functions (the tests are C++, the code under test is C99), and the coverage target requires 100 % of the lines, branches and functions of model.c. The rules are those of the C++ code: the same layout on the wire, the same checks in the same order, the same statuses (wireforge/c/, docs/RUNTIME.md). What differs is the shape: - Everything global starts with the namespace of the project, :: replaced by _ (gnss::ubx gives gnss_ubx_): types <prefix>_<Type>, functions <prefix>_<Type>_init/validate/encode/decode, macros <prefix>_<NAME>. - An enum is an integer type with one macro per member (<prefix>_<Enum>_<member>) and <prefix>_<Enum>_is_valid(). - An array of variable size (a counted array, a fill array, an optional field, a string) has a member <name>_count next to the array <name>[capacity]; a fixed array has none. - <prefix>_<Type>_init() sets the defaults, _validate() returns the first error, a message has _serialize()/_deserialize() (its own encoding) and _serialize_with()/_deserialize_with() (an explicit wf_encoding). <prefix>_<Type>_MIN_WIRE_SIZE and _MAX_WIRE_SIZE are macros. - A checksum is the function <prefix>_checksum_<name>(data, length); a custom one calls the c_impl of the model. - A field with scale has <prefix>_physical_<Type>_<field>() and <prefix>_set_physical_<Type>_<field>(). - Each interface has <project>/interfaces/<interface>.h and .c, prefix <prefix>_<interface>_: the id and size macros (_HEADER_SIZE, _TRAILER_SIZE, _MAX_FRAME_SIZE, _<Message>_ID), _header and _header_init(), _encode_<Message>() (a complete frame), _decode_header(), a _handler struct of callbacks, _dispatch_frame() and a _link that owns its buffers (_link_init(), _link_poll(), _link_send_<Message>(), _link_send_frame()). A handler has, per message, on_<Message>_received (decoded) and on_<Message>_raw (the bytes before decoding; <prefix>_<interface>_<Message>_default_raw() decodes and forwards). A null callback means the default; a handler without callbacks ignores the messages. The link reads and writes through a wf_transport (two functions) and is used by one thread at a time (docs/RUNTIME.md). Only the types and enums that a message or an interface uses get functions. User types are not supported yet. The test project builds the C library with malloc, calloc, realloc and free renamed to names that do not link, so C code that uses the heap fails the build.

From Rust, the C code is used through bindgen (examples/tutorial/drone_app_rust, also no_std): build.rs runs wireforge generate --language c, and wireforge runtime-dir prints the directory of the runtime headers.

In CMake, wireforge_generate(<target> PROJECT <dir> LANGUAGE c) generates the C code at configure time and makes <target> a static C99 library of it, with the C runtime headers; it needs no C++ compiler, so it also builds for a microcontroller (examples/tutorial/drone_firmware).

C++17 and C99 compared

C++17 (default) C99 (--language c)
Wire layout, checks, statuses, checksums, physical values yes the same rules
Framing, dispatch, link over a transport (interfaces) yes yes
Generated GoogleTest project, 100 % coverage gate yes yes (tests are C++, the code under test is C99)
User types (user_types) yes no: generation stops with "user type X is not supported in generated C"
Locks and atomics in the link yes no: a link belongs to one thread at a time (docs/RUNTIME.md)
Generated by the command line, Python API, server and web UI yes yes; MCP generates C++ only
CMake (wireforge_generate) yes yes, LANGUAGE c
Wireshark dissector yes the same (it depends on the model, not on the language)

Physical values

A field with scale and offset keeps its raw value in the struct (that is what the wire carries). Two functions next to the struct convert (SR-24 limits them to plain integer and floating-point fields):

double celsius = physical_Climate_temperature(climate);        // raw * scale + offset
bool fits = set_physical_Climate_temperature(climate, 21.5);   // false, field unchanged, when the raw value does not fit
The setter rounds to the nearest raw value (halves away from zero) and refuses a value outside the range of the type or bit width, and NaN or infinity. min and max are not applied by the setter: they are checked by validate() and on encode, as for every field. The generated tests set both ends of the raw range through the setter, a value just below zero, values outside each end, and for floating-point fields a normal value and both infinities. The reference codec adds the physical values of the scaled fields to its decode result (physical).

Codec

std::array<std::uint8_t, max_wire_size(wireforge::type_tag<SensorReading>)> buffer{};
std::size_t size = 0U;
wireforge::Status status = serialize(reading, wireforge::Span<std::uint8_t>(buffer), size);
status = deserialize(wireforge::Span<const std::uint8_t>(buffer.data(), size), reading);
- serialize/deserialize take an optional wireforge::Encoding (byte order, bit order, encode/decode range checks, trailing bytes); the default k<Message>Encoding uses the message and project settings. Interfaces pass their own encodings. - Per type, encode(const T&, wireforge::Encoder&) and decode(T&, wireforge::Decoder&) hold the field sequence. The encoder/decoder keep the first error, so the functions are straight-line code; statuses and their order match the reference codec (SPEC section 16). - Wire-only fields are produced by the encoder: consts, reserved values, checksums (checksums::<name> types) and count fields (from the array size); the decoder verifies them (ConstMismatch, ChecksumMismatch, count ranges). - Every golden vector is a test of the generated test project (see below): the C++ value built from the JSON value must encode to the golden payload, and the payload must decode and re-encode unchanged, for every profile.

Interfaces

namespace node_c = demo::avionics::our_to_nodeC;   // inline namespace v1_0 holds the version
class App final : public node_c::Handler {
    void onCommandReceived(const demo::avionics::Command& command) noexcept override { /* ... */ }
};
App app;
node_c::Endpoint endpoint(app);                      // frame decoder + dispatcher + receiver
node_c::Link<MyTransport> link(transport, endpoint.decoder(), endpoint.dispatcher());
link.send([&](wireforge::Span<std::uint8_t> buffer, std::size_t& size) {
    return node_c::encode_frame(command, buffer, size, node_c::Header{/* seq */});
});
link.poll();                                         // calls app.onCommandReceived(...)
- Header fields with roles sync, message_id, payload_length, protocol_version and constants are written and checked automatically; other header fields are members of Header. A protocol_version field without const carries the interface major version. - Supported subset (D30): header fields are byte-aligned integers; the trailer holds at most one checksum plus constants; checksums in headers are not supported. Unsupported layouts are reported by wireforge.generate. A header bit-field is supported when it is unsigned, not a constant, a whole number of bytes wide and the header bit order follows its byte order (little with lsb_first, big with msb_first): each such field then has bytes of its own and is written with Encoder::write_width (a 24-bit message id after an 8-bit component id, as in MAVLink 2). - With trim_trailing_zeros the frame writer sends the payload without its trailing zero bytes (wireforge::trimmed_size, the first byte stays), and the default on<Message>Raw decodes the payload extended with zeros to the size of the message (wireforge::ZeroExtended); an override of on<Message>Raw gets the bytes as they were received. The generated tests add TrimsTrailingZeros (the frame of every default message has the trimmed size); the dispatch and golden tests send frames whose payloads were trimmed by the reference codec. - Every message has a virtual on<Message>Raw(const wireforge::RawMessage& raw) in Handler. Its default decodes raw.payload and calls on<Message>Received when the decode succeeds, and returns the decode status. Override it to take the bytes without decoding: framing, the frame checksum and the message id were checked, the payload was not (no size, constant, range or payload checksum check). raw.frame is the whole frame. Call Handler::on<Message>Raw(raw) from an override to get both. The spans point into the link's receive buffer and are valid only during the call.

class Relay final : public node_c::Handler {
    wireforge::Status onCommandRaw(const wireforge::RawMessage& raw) noexcept override {
        return forward(raw.frame);   // the frame as received, without decoding
    }
    void onCommandReceived(const demo::avionics::Command& /*command*/) noexcept override {}
};
- Without nodes both directions are generated for every interface (direction is documentation), so any interface can be looped back in tests; with nodes see Units and system output. The golden tests encode every golden frame with encode_frame, compare it byte for byte and send it through a loopback Link to the generated Handler.

Units and system output

A project with nodes describes a system of units: programs that send and receive messages. Every interface lists its nodes and every message entry says who sends it with from; the other participants receive it. wireforge generate writes the code of every unit separately and --node <unit> only one unit, with the same bytes as in the full run:

Item Without nodes With nodes (unit B, project avionics, namespace demo::avionics)
C++ namespace demo::avionics demo::avionics::B
C prefix demo_avionics_ demo_avionics_B_
Include root <out>/ with avionics/ below <out>/nodes/B/ with avionics_B/ below
Generated tests <out>/avionics/generated_tests/ <out>/nodes/B/generated_tests/
Banner model hash unit name and unit hash
System output <out>/system/: system_icd.md and, with --tests, the system test

The language of a unit is its language (cpp or c), else the one of the command (--language, default cpp).

  • Only the messages of the unit. The unit's model header holds the messages it sends or receives and the types they use. The handler has a callback (on<Name>Received, on<Name>Raw) for every message the unit receives, and none for the ones it only sends. encode_frame, Endpoint::send (C: <ip>_encode_<Name>, <ip>_link_send_<Name>) exist for the messages it sends. A message the unit only sends is still known to its dispatcher: a valid frame of it is not for this unit, so the receiver calls onUnhandled with UnhandledReason::NotForThisNode and returns Status::NotForThisNode (C: WF_NOT_FOR_THIS_NODE). That is not an error: the poll result counts neither a frame nor an error for it, and the link counts it in rx_not_for_node.
  • onUnhandled. Every Handler (also without nodes) has virtual void onUnhandled(const wireforge::UnhandledFrame&); the default does nothing (C: the on_unhandled member of the handler, NULL means "only count"). It gets a valid frame that reaches no received callback: an unknown message id, a message that is not for this unit, or a payload the default on<Name>Raw could not decode (UnhandledReason::DecodeError). Frames the frame decoder rejects (checksum, length, lost sync) do not reach it; the link counts them in rx_rejected.
  • Endpoint::send. endpoint.send(link, message, header) encodes the message and sends it on a link; it exists for every message that can be sent, in every project. The older encode_frame with link.send(...) still works.
  • Link counters. LinkCounters (C: wf_link_counters) has rx_frames, rx_rejected, rx_unknown_id, rx_not_for_node, rx_decode_errors, rx_bytes, tx_frames, tx_bytes, tx_errors; Link::reset_counters() (C: wf_link_reset_counters) sets them to zero.
  • Counters per message. With message_counters: true on an interface the generated code has a struct MessageCounters with rx_<Name> for the messages the unit receives and tx_<Name> for the ones it sends (every message twice without nodes). Endpoint::message_counters() and reset_message_counters() give access (C: <ip>_link_message_counters, <ip>_link_reset_message_counters). MessageCounters is a struct of the interface namespace, not nested in Endpoint, because the receiver is declared before the endpoint and needs it. rx_<Name> counts a message when its raw callback returns Ok: the default decodes the payload, but an override that returns Ok without decoding is counted too. tx_<Name> counts a message that Endpoint::send (C: <ip>_link_send_<Name>) sent; a frame sent with encode_frame and link.send is not counted. Without the flag no counter exists, so no RAM is used.
  • The unit hash. wireforge.nodes.node_hash is the sha256 of the canonical form of the unit's view: its interfaces, the messages, types, enums and checksums they use, the units that take part, the requirements catalog, the defines, the profiles and the user constants (so a change to one of these last four changes the hash of every unit). Where an element was written is not part of it. A change that does not reach a unit leaves its hash unchanged.
  • Source lines. The generated comments say where each element is written (/// Defined in messages/a_b.yaml:12). With the whole model in one file, a line inserted above shifts the line numbers of every later element, so those comments change in the files of units the change did not concern, though their code and hash did not. Split the model into files per unit or per interface with include, so that a change elsewhere does not move the source lines of your unit's elements (examples/08_system).
  • The system test. wireforge generate <project> -o <out> --tests also writes <out>/system/, a GoogleTest project that encodes every message with its sender's generated code, decodes it with the generated code of every other participant and compares the result with the reference codec. All C++ units are built into one executable (the namespaces keep them apart); a unit written in C is linked as a static library (its prefix keeps its names apart). wireforge test <project> -o <out> --system builds and runs it; wireforge test ... --node <unit> runs the tests of one unit. Messages with an opaque user type are left out.

Quality

Generated code compiles with the full warning set (-Werror), passes clang-tidy, cppcheck and the GCC analyzer and is completely documented for doxygen. Snapshots of the generated examples live in tests/python/snapshots/; after an intended change run WIREFORGE_UPDATE_SNAPSHOTS=1 pytest tests/python/test_generate.py and review the diff. The generated code contains no branch that the generated tests cannot reach: checks that cannot fail are written with wireforge::status_if() and wireforge::size_if_ok() (runtime, D46). The generated tests cover every enum member and the decode errors and raw hooks of every message. The generated test project gates line, branch and function coverage of the generated headers; for the examples each is 100 %.

Generated test project

python -m wireforge.generate <project> -o <dir> --tests [--plugins plugins.py] [--runtime runtime/include] [--coverage-threshold 100] also writes <dir>/<project>/generated_tests/, a standalone CMake project:

File Content
CMakeLists.txt one GoogleTest executable per profile (profile defines + WIREFORGE_PROFILE_<name>), the quality-policy warning flags as errors, WIREFORGE_SANITIZE, WIREFORGE_CLANG_TIDY, WIREFORGE_COVERAGE with a coverage target (gcovr, fails below WIREFORGE_COVERAGE_MIN_LINE percent line coverage, or below 100 percent branch and function coverage (WIREFORGE_COVERAGE_MIN_BRANCH, WIREFORGE_COVERAGE_MIN_FUNCTION), of the generated headers)
CMakePresets.json dev, asan-ubsan, tsan, coverage, clang-tidy
.clang-tidy the repository's check set, warnings as errors
golden_test.cpp golden vectors: payload round trip, encode_frame equals the golden frame, decode_header, loopback through Link/Endpoint/Handler
message_test.cpp per message: defaults (T{}), every scalar member and the first element of every array at its minimum and maximum and one step outside (when the member type can hold it), an invalid enum value, every variable-size array emptied (the pattern value fills arrays to capacity), and single-byte mutations of the encoded pattern (the first one per distinct decode error and field: checksum, count above the maximum, constant, range), truncation and an extra byte
interface_test.cpp per interface: every message dispatched to its handler, byte-wise delivery, bytes before the sync, a corrupted frame followed by a good one, encode_frame into too small buffers, raw delivery without decoding, raw delivery forwarded to the decoder, decode errors returned by the raw hook
no_allocation_test.cpp, allocation_counter.cpp per interface and message: decoding, encoding, sending and dispatching the frame make no heap allocation, counted by replacing the global operator new of the test executable
handlers.hpp, test_support.hpp, wire_support.hpp recording handlers with a loopback link per interface; assertion and byte helpers
diff_harness.cpp <project>_diff[_<profile>]: line-based harness of the differential test (see below)
selftest.cpp <project>_selftest[_<profile>] (CTest): framework-free self-test without exceptions, RTTI or heap (golden vectors: payload, frame, loopback; decode cases), for embedded and cross targets
fuzz_target.cpp <project>_fuzz[_<profile>] (with -DWIREFORGE_FUZZ=ON, Clang): libFuzzer target; the first byte selects a message (deserialize, then a value that encodes must decode and encode to the same bytes) or an interface (bytes streamed in input-defined chunks through the loopback link)

Every expectation (payload bytes or the status) is computed by the reference codec (wireforge.test_cases), so the generated code is checked against the reference semantics; validate() must report the status the reference encoder reports with range checks forced on. Custom checksums need their Python plugin (--plugins) to compute expectations. After resynchronisation (resync: true without sync bytes, or sync bytes inside the corrupted frame) the number of rejected frames is not predictable byte by byte; the test then checks only that the corrupted frame is rejected.

The CMake paths to the runtime headers and the project's user_includes.include_dirs are relative to the test project when they share a directory with it, otherwise absolute; both are cache variables (WIREFORGE_RUNTIME_INCLUDE_DIR, WIREFORGE_MODEL_DIR). GoogleTest 1.14 is found or downloaded (FETCHCONTENT_SOURCE_DIR_GOOGLETEST reuses a local copy). In this repository tests/generated builds the test sources of every example with all gates (warnings, sanitizers, clang-tidy, cppcheck), and quality/run_generated_tests.sh builds each project standalone with its own CMake files and runs its coverage target (line, branch and function threshold 100 %, the default of --coverage-threshold; the examples and the models of tests/models/ reach 100 % in all three).

Coverage of the generated code for any model

The 100 % gate of the generated headers is not shown on four examples alone; three checks stand behind it for every model a user can write: - quality/feature_matrix.py lists the features of the schema (every field type, bit-field form, occurrence form, header role, framing kind, checksum form, profile and condition) and fails when one is used by no built and measured model, or when a property of the schema is not mapped to a feature. The models are the examples, tests/models/ and the random models below. - quality/random_models.py writes valid random models (a fixed seed always gives the same model), generates their code and tests, builds them with the warning set as errors, runs them and measures the generated headers; any warning, failing test or coverage below 100 % of lines, branches and functions fails and leaves the model in build/random-models/failures/<seed>/. CI runs seeds 0 to 23 on every pull request and the workflow random-models-nightly runs 1000 more each night. A failure is a defect of the generator: fix it, reduce the model and add it to tests/models/. - SR-23: an enum field without a default needs a member with the value 0, because init() starts it at zero. - SR-24: scale and offset are allowed on plain integer and floating-point fields only.

A fourth check is made while the tests are written (wireforge.coverage_points): the model decides which points the tests must exercise (the frame writer of every message with too little room, the receiver check of every message, serialize without room, the decode error and the edit of every field, ...), every test records the points it covers, and a point that no test covers stops the generation with "defect of the generator". A generator that tests only the first message of an interface can no longer produce a project that misses the 100 % gate in a user's hands.

The checks found, and the generator now handles: the frame writer of every message of an interface (not only the first) is tried with too little room; a raw-decode error test uses the byte order of the interface; a message that is on no interface has a golden round trip of its own; serialize into a buffer without room is tested for every message; a message that exists only in some profiles is left out of the profiles without it; an unused pattern helper is no longer emitted. This is evidence over many models, not a proof; the user's own gate (coverage target, wireforge docs --strict) stays the last line.

Results of a test run

The coverage target also writes machine-readable results to <build>/results/, which wireforge docs --results <build> turns into the test report, the resource document and the toolchain section (docs/LIFECYCLE.md):

On Windows the JUnit file of each test is named <suite>.<test>.xml; a path over 260 characters makes GoogleTest abort that test (exit code 0xc0000409), so keep the project and build directories short or enable long paths.

File Content
junit/<executable>/*.xml GoogleTest result of every test, with the requirement ids it recorded
ctest.xml CTest result, which includes the self-tests
coverage.json, coverage_summary.json, coverage.cobertura.xml statement and branch coverage of the generated headers (gcovr; the Cobertura file is for other tools)
coverage_runtime.json statement coverage of the runtime headers, only with WIREFORGE_COVERAGE_RUNTIME=ON
toolchain.json compiler, CMake and gcovr versions, build type and the warning flags (no path)

WIREFORGE_COVERAGE_RUNTIME adds a second report for the runtime headers and fails below WIREFORGE_COVERAGE_RUNTIME_MIN_LINE percent of the statements (default 100). Only code that reaches the binary is counted, which is the code that flies; wireforge test --coverage-runtime sets the option. With coverage on, the tests are also built with -fstack-usage; the .su files next to the objects give the stack use of the generated and runtime functions. The coverage build is -O0, so these values are indicative; measure on the target.

A line the tests do not reach is either closed with a test or justified in an optional deviations.yaml in the project directory (not part of the model, no effect on the model hash):

schema_version: 1
deviations:
  - kind: coverage
    file: wireforge/ring_buffer.hpp          # runtime header relative to the include directory
    function: "wireforge::StaticSpscByteRing<*>::push"   # as gcov names it; * matches anything
    lines: [118, 119]                        # optional; absent: every uncovered line of the function
    category: defensive                      # deactivated | defensive | unreachable-by-design
    rationale: The ring cannot be full with this link.
    reviewer: J. Doe
A deviation with lines stops matching when a runtime update moves them, which makes the gap unjustified again so that the reason is reviewed. kind: rule entries are accepted by the schema and ignored for now.

Differential and fuzz testing

python -m wireforge.differential <project> --harness <dir>/<project>_diff[_<profile>] [--profile P] [--plugins F] [--seed N] [--values N] [--mutations N] [--frames N] [--regressions DIR] sends inputs to the generated harness and compares every answer with the reference codec:

  • payloads (M <message> <hex>): random valid values of every message (every field random inside its range, random array lengths), the boundary and decode cases of the generated tests, and random mutations (replaced byte, flipped bit, truncation, appended bytes); the decode status, the status of encoding the decoded value again and the re-encoded bytes must be equal;
  • frames (F <interface> <hex>): random valid frames and their mutations through a loopback link; a frame the reference accepts must be dispatched with the same payload, a frame it rejects must not be dispatched cleanly (the stream decoder may split a rejected frame differently). Interfaces that resynchronise without sync bytes get only valid frames, and appended bytes are not used on framed interfaces (they start the next frame of a stream);
  • stored inputs in --regressions are replayed first and new mismatches are appended to found.txt there (tests/regressions/<project>/<profile or default>/).

--fuzz-seeds DIR writes the golden payloads and frames as seeds of the generated fuzz target. The random generator is a deterministic xorshift, so a seed reproduces a run. The runtime has its own fuzz targets (tests/fuzz/, preset fuzz): checksum_fuzz (table and bitwise CRC engines agree, split updates equal one-shot updates, six CRC variants) and frame_decoder_fuzz (three framings streamed in random chunks; every delivered frame is complete, has the sync value and a correct checksum, the ring always gets free space).

Gates: quality/run_generated_tests.sh runs the differential test for every example and profile; quality/run_fuzz.sh builds all fuzz targets with Clang and runs each for WIREFORGE_FUZZ_SECONDS (20 locally, 60 in CI, 900 in the weekly fuzz-long workflow, whose four jobs take every fourth target each through WIREFORGE_FUZZ_SHARD=k/4), WIREFORGE_FUZZ_JOBS targets at a time (default: the number of CPUs), seeded with tests/regressions/fuzz/<target>/ and the golden vectors; a crash leaves its input in build/fuzz/artifacts/.