Design decisions
The reasons behind the main design choices. Other documents refer to them by number.
| # | Topic | Decision |
|---|---|---|
| D1 | Optional fields | Unified with dynamic arrays as an occurrence model: every field has occurs {min,max}; optional = max 1, array = max N. Count comes from: a variable (any integer/bool field), an expression, or a constant. Count 0 = field absent on the wire. C++ repr: StaticVector<T,MAX>-like (count + storage), no heap. |
| D2 | Bits | Bit-fields supported (bits: n, bool1, enums, nested groups). |
| D3 | Endian | Message level only (interface may define default, message may override). No per-field endian. |
| D4 | Checksums | Optional. CRC32 built in; parametric CRC engine; user-defined checksum via a documented C++ contract + schema reference. |
| D5 | Thread safety | Runtime is thread-safe by design (docs/ARCHITECTURE.md, Thread safety). Generated codec code is pure/reentrant. |
| D6 | Portability | C++17 only, platform/compiler/endianness independent, no host-layout assumptions. |
| D7 | Versioning | Two levels: schema_version (file format, with migrations) and interface.version (ICD semantic version, coexisting versions, compat checker). |
| D8 | Test generation | Generator also emits a ready CMake project with GoogleTest tests and a coverage target. |
| D9 | Static analysis | Zero warnings / errors / notes policy for runtime AND generated code (see quality/QUALITY_POLICY.md). |
| D10 | Bit order | Selectable per message: bit_order: msb_first (default) or lsb_first. Applies to all bit-fields in that message; layout analyzer shows the effective bit map. |
| D11 | Floating point | IEEE-754 only: f32 (binary32) and f64 (binary64), written/read via fixed-width integer bit patterns (memcpy), message-level endian. No scale/offset or fixed-point attributes in v1. |
| D12 | Static analysis rule set | Baseline set only (compiler warnings + clang-tidy + cppcheck + analyzers + sanitizers). MISRA/AUTOSAR out of scope for v1. |
| D13 | Default lock policy | StdMutexLock (std::mutex) is the default; NullLock and user-defined locks remain opt-in. |
| D14 | Server/tooling language | Python for core, CLI, codegen, server (FastAPI), MCP (official Python SDK); TypeScript only for the UI. UI types are generated from the JSON Schema + OpenAPI so no logic is duplicated. |
| D15 | Authoring modes | Files are the single source of truth. Everything is editable by GUI or by text/script: YAML files, wireforge CLI, Python API. GUI writes through the same canonical formatter, preserving comments and key order, so both modes coexist in git. |
| D16 | Checksum contract | Static member functions only: kSize (1..8), State, init(), update(State&, Span<const uint8_t>), finalize(const State&) -> uint64_t, all noexcept; checked by is_checksum_v. The value is written with the message endianness. |
| D17 | Lock default without <mutex> |
WIREFORGE_DEFAULT_LOCK selects the default policy; otherwise StdMutexLock, or NullLock when WIREFORGE_NO_STD_MUTEX is set (bare-metal single-core default; RTOS ports set the macro). |
| D18 | Span conversions | Every Span constructor is explicit, including Span<T> -> Span<const T>, so no analyzer suppression is needed (cppcheck noExplicitConstructor). |
| D19 | Bit-group container | A bit group is packed into ONE container integer (8..64 bits, multiple of 8): msb_first gives the first field the most significant bits, lsb_first the least significant; the container is then written with the message endianness. Groups wider than 64 bits are not supported by the runtime. |
| D20 | Expression back ends | One AST, three back ends: the Python evaluator wireforge.expr.evaluate (reference semantics, used directly by the tools and the reference codec, so no Python source is emitted), to_cpp (int64 C++ expression) and to_preprocessor (#if). Python is stricter than C++17 where C++ would be implementation-defined (shifting negative values): such models are rejected. Equality is proven by compiling truth tables with g++. |
| D21 | Validation variants | Expressions are evaluated per profile when the project has profiles (profile defines override root defines), otherwise once with the root defines. Errors inside a profile are SR-16, otherwise SR-5. |
| D22 | Names in expressions | Field names are allowed only in occurs.count (SR-7); min/max, capacities and sizes are static. In if: plain names must be root defines (always emitted as macros); profile-only macros are tested with defined(NAME); user constants (C++ symbols, not macros) are not allowed in if:. |
| D23 | Generated C++ name space | Defines, enums, types, messages and interfaces share one generated C++ scope, so their names must be unique across these sections (SR-2); names that are C++ keywords or reserved identifiers (__x, _X) are rejected. Messages cannot be field types (shared layouts go to types). |
| D24 | Frame decoder | Sync and length header fields are whole bytes in the frame byte order; the frame checksum is a trailer field. A rejected frame is reported once; resync: true skips one byte and rescans, resync: false drops all buffered bytes. Wrong sync bytes are skipped silently (counted). A frame larger than the ring capacity is InvalidLength. Framing none bypasses the decoder. |
| D25 | Transport interface | The runtime defines a generic non-blocking transport (send/receive over spans, checked by is_transport_v, optional ITransport base) instead of depending on a particular driver API; existing drivers are connected through a small adapter class. |
| D26 | Compat classification | Wire-level comparison per profile with three classes (breaking / compatible / doc) mapped to major / minor / patch, also for 0.x versions. Any range or enum value change is breaking (either peer may reject the other's values). Appended trailing fields are compatible only when the old interface allows trailing bytes. |
| D27 | Codec details | Plain-name counts are written from the element count; expression counts must match. Fixed char arrays are zero padded and stripped on decode. Fixed framing never pads. Count overflow is reported as CountExceedsMax before the count field's own range. Custom checksums use plugins in Python (PLUGINS dict in a file next to the example). See SPEC section 16. |
| D28 | Generated C++ shape | Types and messages are plain aggregates with default member initializers; validate(), min_wire_size()/max_wire_size() and the codec are free functions found through ADL (wireforge::type_tag<T> for size queries). Storage: fixed arrays std::array, counted/fill arrays StaticVector, char arrays FixedString. const, reserved, checksum fields and count fields referenced only as plain occurs.count names are wire-only (no member; the array size is the count). Defines become overridable constants, never macros. One generated tree serves every profile (#if blocks, define constants). |
| D29 | Generated codec | Free serialize/deserialize per message with a runtime wireforge::Encoding argument (one code path for every interface); Encoder/Decoder with a sticky first error keep generated functions branch-free. NaN is outside every min/max range (reference codec and C++ agree). |
| D30 | Generated interfaces | One header per interface in an inline version namespace (v<major>_<minor>). Handlers are virtual on<Message>Received(const M&) noexcept (no RTTI needed); Receiver decodes on the stack (reentrant) and Endpoint bundles decoder, dispatcher and receiver. Header fields must be byte-aligned integers and the trailer may hold one checksum plus constants; both directions are always generated. |
| D31 | Generated test project | generate --tests writes a standalone CMake/GoogleTest project next to the generated code. Expectations are computed by the reference codec at generation time (no hand-written oracle in C++): golden vectors, boundary values, emptied arrays and single-byte decode mutations (first per distinct status and field). One executable per profile. Coverage is line coverage of the generated headers via gcovr (default threshold 90 %, repository gate 95 %); runtime headers are covered by the runtime tests. Unknown message ids are covered by the runtime dispatcher tests, not per interface. |
| D32 | Layout analyzer | One analyzer for every profile; offsets are ranges after variable-size fields, element fields are shown for the first element, bit positions count from the container's least significant bit. The RAM budget counts the buffers the generated Link owns (receive ring, receive frame, transmit frame); buffers.tx_bytes sets kTxBufferBytes (checked to hold a frame) but the link's transmit buffer is one frame. Generated tests assert the analyzer's sizes against the generated constants. |
| D33 | Differential and fuzz testing | The generated project contains a line-based harness (one process per profile, all inputs in one batch) instead of linking Python and C++; the reference codec computes every expectation. Rejected frames are compared only for "not dispatched cleanly" because a byte-stream decoder may consume a bad frame in other pieces than the one-frame reference. Findings: an unframed read longer than the frame buffer was split by Link::poll() and its first part dispatched; it is now InvalidLength and dropped. The reference codec keeps NaN bit patterns (WireNaN) so signaling NaNs round-trip bit-exactly like the C++ code. Fuzzing uses libFuzzer (Clang) with ASan/UBSan. |
| D34 | Portability matrix | Cross builds use Debian/Ubuntu cross compilers (s390x big-endian, i686 32-bit) with qemu user emulation through CTest's emulator, so the same test suites (runtime, generated GoogleTest, self-tests) run on every target; locally the toolchains can be extracted without root (quality/fetch_cross_toolchains.sh). A generated framework-free selftest.cpp (golden vectors, decode cases) is built with -fno-exceptions -fno-rtti like embedded code. Platform-width conversions use narrow_to<T>() (a template, so 32-bit targets get no useless-cast warning). Clang -Weverything gates production code with four documented exclusions. |
| D35 | CLI, service layer and canonical format | One service layer (wireforge.service) returns Result objects for the CLI, Python API, server and MCP. Edits address elements by JSON pointer, edit the defining file with ruamel round-trip and write the canonical layout; the canonical key order follows the schema but matches the hand-written examples (e.g. field units after the range), so formatting the examples is a no-op. Exit codes: 0 ok, 1 failed check, 2 usage, 3 cannot run. |
| D36 | Server storage | No server-side cache or database: requests read the project files, so hand edits and git operations are visible at once. Optimistic locking with ETags (per file for file writes, per project for entry/value edits; 428 without If-Match, 412 when stale) and one write lock per project. External changes are announced by a long-poll endpoint instead of a file-system watcher (portable, no extra dependency). Auth is a shared bearer token or OIDC (D48). FastAPI/uvicorn are an optional extra (wireforge[server]). |
| D37 | Server tools | generate returns a self-contained zip (generated code, test project, runtime, model copy) built in a temporary directory so every CMake path is relative inside the zip. Checksum plugins are found by convention in plugins/*.py (defining PLUGINS); the server therefore executes project code and serves trusted workspaces only. Compatibility compares two projects of the workspace (e.g. a released copy and the working copy). |
| D38 | UI stack | React 18 + Vite + TypeScript strict; types generated from the JSON Schema and the OpenAPI document (checked in, verified by check:types), so the UI carries no hand-written model or API shapes. The server's result routes declare a ResultResponse model for that purpose. UI tests run against a real server process instead of mocks. Edits are saved explicitly (Save button) per entry, not on every keystroke. |
| D39 | MCP server | Official Python SDK 2.x (MCPServer, stdio). The tools wrap the service layer like the CLI and the HTTP server, work on a workspace like the server, return the service Result as structured output and report bad arguments as tool errors. Besides the listed tools there are create_project, upsert_entry (all other sections) and run_tests, so an agent can go from an ICD to passing tests without leaving MCP. |
| D40 | Importers | A documented one-row-per-field ICD table (CSV, or the first Excel sheet via optional openpyxl) and a C-header subset (fixed-width types, bit-fields, arrays, enums, integer defines) import into a new single-file project written in the canonical layout and validated at once; anything outside the subset is an error with file and line instead of a guess. Interfaces, framing and checksums are not part of the import. |
| D41 | Safety evidence | The no-heap check inspects object files built like embedded code (no exceptions, no RTTI, no std::mutex, -O0 and -O2) with an allow list instead of a deny list. Findings fixed on the way: std::array::at (exception path) replaced by wireforge::array_at, virtual destructors of Handler/ITransport (deleting destructor referenced operator delete) made protected and non-virtual. Trace data comes from the model's source locations; generated code carries Defined in file:line comments. The coding-rule mapping is informative, not a conformance claim. |
| D42 | Packaging | One wheel (pip install wireforge[server,mcp,import]) carries the JSON Schemas, runtime headers, CMake package and the built UI below wireforge/_data (copied by setup.py at build time; a checkout uses the repository files). The CMake package is hand-written and relocatable, so the same files work from cmake --install prefixes and from the wheel (wireforge cmake-dir); wireforge_generate() runs the generator at configure time and reconfigures when model files change. The Docker image adds the C++ toolchain and serves the UI. |
| D43 | License | runtime/ is MIT licensed. Everything else (CLI, codegen, server, UI, MCP server) is Business Source License 1.1, free for non-production use, with each version converting to MIT four years after its release; production use requires a commercial license. Generated code is output of the tool from the user's model; WireForge claims no rights to it, and it only depends on the MIT-licensed runtime, so it carries no restriction. |
| D44 | Wireshark dissector | One self-contained Lua plugin per project: a generated data table (every profile's layout, fields expanded per message so bit masks follow each message's bit order) plus a fixed interpreter that mirrors the reference codec, instead of generating Lua code per field. One protocol per interface; profiles are a protocol preference, so the ProtoFields are the union of all profiles. Fields of up to 4 bytes use Wireshark's own decoding (masks, sign extension, valuestrings); wider bit groups and 64-bit bounds use UInt64/Int64, so Lua 5.2 (doubles) and 5.4 behave the same. Only the 3.6 Lua API is used; bit operations come from bit32 or, on Lua 5.3+, native operators. The dissector reports every problem it finds, with the codec status as the expert text prefix. Plugins run in separate Lua environments, so custom checksums are hooks on _G.wireforge_checksums. Tests run real tshark 3.6, 4.2 and 4.6 against the reference codec, using packages fetched without root. |
| D45 | Raw delivery | Whether a message is decoded is the consumer's choice, not part of the wire format, so it is not in the model and needs no setting. Every generated Handler has a virtual on<Message>Raw(const wireforge::RawMessage&) per message whose default decodes and calls on<Message>Received; the on<Message>Received stays pure virtual, so a forgotten message is still a compile error. MessageHandler and FallbackHandler receive the payload and the whole frame. The raw path does no size check; its spans are valid only during the call. |
| D46 | Branch-free generated code | Generated code holds no branch of its own: a condition that the generator needs is written as a call to a runtime helper (status_if(), size_if_ok(), first_error()), and the runtime helpers are unit tested for both outcomes. The generated test project gates 100 % branch and function coverage of the generated headers next to the line gate. Checks that cannot fail after validation (for example that a frame fits max_frame_size, which SR-16 guarantees, or that attach fails, which SR-9 excludes) are kept as status expressions instead of being removed, so a future change that breaks the guarantee still reports an error. |
| D47 | User types | A field type may be a user-owned, opaque C++ type: declared by size_bytes only, serialized by the user's own encode/decode free functions (ADL, same contract as generated structs, D28/D29); WireForge generates only min_wire_size/max_wire_size (both equal to size_bytes, since the size never varies). The reference codec and test generator never interpret the type's internal semantics: its Python-side value is raw bytes, generated tests skip per-field value assertions on it, and the Wireshark dissector shows it as raw hex (FT_BYTES). Occurs, nested structs and arrays all work (treated like a struct field for codegen purposes); bits, checksums, occurs.count, and min/max/default/const are rejected (already caught by existing rules, no new ones needed). |
| D48 | Server OIDC | wireforge serve --oidc-issuer URL --oidc-audience A verifies Authorization: Bearer <JWT> (signature from the issuer's JWKS found by discovery, iss, aud, exp/nbf with 60 s skew, asymmetric algorithms only) and is exclusive with --token (usage error, exit 2). The sub/email claims are kept on the request only, so the no-database rule of D36 holds. The JWKS is cached in memory and refetched lazily after --oidc-jwks-cache-seconds, without a background thread. Verification uses joserfc (authlib.jose is deprecated) in the optional extra oidc. Still no roles, per-project permissions or audit log: every authenticated user has the access of a token holder. |
| D49 | Requirements and LLR | The user owns the high-level requirements (the requirements catalog); model elements point at them with reqs. Low-level requirements are derived from the model, never stored, and keyed by names (Owner[.field].KIND) so reordering fields keeps them and a rename changes them; the displayed id comes from one function. Fields of a nested type belong to the type, so a requirement is stated once. Generated tests, not naming conventions, carry the link: each records its LLR ids with RecordProperty and the trace report reads them from the test sources. The layout analyzer's static size assertions became WireSize tests so SIZE and FRAME_MAX have a real test; every interface gets FRAME_ENCODE, FRAME_MAX, DISPATCH and RAW, so no generated test lacks a requirement. The generator is not qualified: generated code is verified like hand-written code and WireForge produces the evidence. Defaults do not change: validate only checks references (SR-21), a project without a catalog generates the same code (only the format banner moves to 1.1), and the Requirements: Doxygen lines exist only with a catalog. Requirement ids are the user's data, so the rule that comments never cite decision numbers does not apply to them. DISPATCH_UNKNOWN is verified by the runtime tests (D31). RANGE, ENUM and BITS are derived only for the directions where range_check is on. |
| D50 | Lifecycle documents | The documents come from one pure renderer (wireforge.lifecycle) over the model, the derived low-level requirements, the trace and the layout analysis, and the CLI, server and MCP only wrap it. The output is deterministic (no date, user name or absolute path) so it can be committed and diffed. The default run never fails because requirements are missing: --strict turns four review findings into an exit code, so existing projects keep working. Derived low-level requirements are reported, not rejected, because the standard allows them. The DO-178C table quotes no text, only objective numbers and our own wording, and rows we could not settle without the standard are marked check for the owner of the licensed copy. No output says certified or compliant; the generator stays unqualified and the files are evidence for the applicant's process. |
| D51 | Coding-rule coverage | The baseline of D12 stays the only gating rule set. MISRA C++:2023 and AUTOSAR C++14 appear as a topic-level coverage map (docs/CODING_RULES.md) that quotes no rule text; rows we could not settle are marked for the owner of the licensed copy. cppcheck's open-source MISRA addon implements MISRA C:2012, so it runs only as an advisory proxy (quality/run_misra.sh, non-required CI job) and is never presented as MISRA C++ coverage. Conformance needs a licensed checker and a deviation process, which WireForge does not provide. |
| D52 | HLR vectors as independent oracle | The reference codec and the generated C++ share the model reader, so a misreading of the model would turn both wrong and leave every generated test green. Vectors written by the user from the ICD give a second source: the generated test compares with the vector's own values, and the codec only confirms the vector when the project is validated (SR-22), which finds a wrong vector or a wrong model early without moving the oracle. A vector must name requirements; a requirement verified by test needs one (strict rule DS-4), so verification is claimed only where an independent expectation exists. Vectors stay apart from the golden files, which are a regression baseline produced by the codec. The format minor moved to 2 because an older tool must reject a file with vectors by version and not by an unknown-key error. |
| D53 | Results and runtime coverage | The test results, the coverage and the toolchain of a run are files the generated CMake project writes (results/), and the lifecycle documents read them with a strict reader: a missing or damaged file is an error, so a report cannot be silently empty. The user's build measures the runtime too (opt-in, statements of the code that reaches the binary), which updates D31: the runtime headers were covered only by the repository's own tests before. The generated-header gate (100 % branch and function) is unchanged. A gap is closed by a test or justified in deviations.yaml, matched by file and function and optionally by lines so that a moved line asks for a new review; one record format serves coverage now and rule findings later. Stack values come from -fstack-usage of the -O0 coverage build and are labeled indicative. Without results strict mode checks the model only and says so. |
| D54 | Runtime dossier | The runtime is hand-written, so its requirements are written and reviewed by people and not derived: they live in runtime/requirements.yaml (MIT with the library), are checked against the headers, and every unit test records the ones it verifies. The first draft came from the headers and the tests, which makes it circular; the file says so and the pull request that changes it records the reviewer. Generated low-level requirements point to the runtime requirements that realize their kind, and a requirement that only the runtime tests verify needs one, so "the runtime verifies it" is no longer a claim without evidence. Concurrency claims are analysis and the evidence is for single-threaded use with the null lock. The dossier is ours: CI produces it per release and projects refer to it. Runtime statement coverage is measured and the gaps are listed; they are closed with tests or justified in runtime/deviations.yaml. The license of the library (D43) covers the requirements file. |
| D55 | Process integration | WireForge fits into the customer's DO-178C process by files and stable ids, not by a connection to their tool. The high-level requirements stay in the customer's tool; WireForge keeps a read-only snapshot of one baseline, with the tool, the baseline and a content hash, and refuses to overwrite a snapshot edited by hand. Low-level requirements are numbered in an append-only lock file, so a number is never changed or reused, also across renames. ReqIF is read and written without a dependency, with deterministic identifiers and the time of the last commit; the written files have not been validated against the schema of the standard or imported by a commercial tool yet, which the integration pages say. The tag convention and the CSV columns are interfaces: changing them is breaking. Permalinks are made only for model files and only from a committed working copy, because generated files may not be in git. The generator stays unqualified and the documents make no claim of certification. |
| D56 | Change impact | docs --since REV compares the working copy with a git revision that is read with git archive into a temporary directory, so the working tree is never touched. It reports what the change did to the requirements, the low-level requirements, the generated files and declarations, the tests and the wire compatibility, and ends with the tests to run and review again. The list errs on the side of more tests: a limit can change a test that does not verify its own requirement. |
| D57 | Rule checker results | WireForge does not check coding rules; it reads what the customer's licensed checker reported (SARIF 2.1.0 or cppcheck XML version 2) and puts it into code_standard.md. Only findings in generated code and the runtime count, the rest is counted. A finding is justified by a kind: rule deviation matched by tool, rule, file and function, and an unjustified finding is DS-9 under --strict. Without results the document says so and makes no conformance claim. The readers have not been tried against a licensed checker yet. |
| D58 | Runtime coverage gate | The runtime line coverage gate counts every template instance that reaches a binary, as gcovr reports it, and is raised by running more code, never by excluding any. Targets that were only compiled run in the normal test run: the differential harness of every example and profile, and the fuzz target of every generated project with deterministic inputs (random bytes, every length, every read length of a link, the golden inputs cut at every length and changed at every byte). The gate follows the measurement, rounded down, and is measured with the compilers of the CI image. |
| D59 | Architecture matrix | The runtime and the generated code are tested on the four combinations of 32/64 bit and little/big endian, with one x86 and one ARM target among the little-endian ones: s390x (64-bit BE), powerpc (32-bit BE), i686 and armhf (32-bit LE), aarch64 (64-bit LE) and the host. Each target is a CI job of its own that runs every suite under qemu user emulation; one required check, portability, depends on all of them. Emulation is not hardware, which the documents say. The runtime uses only atomics of pointer size, so a 32-bit target without 64-bit atomics links without libatomic; the tests follow the same rule. ARM big endian is not tested because the distributions have no toolchain for it. |
| D60 | Operating-system matrix | The runtime and the generated code contain nothing that belongs to an operating system: an allow list of standard headers and no test for an OS macro, checked by a script. They are proved on Linux, Windows (three toolchains), macOS, Android and FreeRTOS. Android is built and linked for three ABIs but not run, because a Bionic binary needs the Android loader and a statically linked one aborts under user emulation; no emulator image is started in CI. FreeRTOS runs on QEMU with its own small test harness, because GoogleTest needs an operating system: it runs the generated self-tests and the runtime with the kernel's mutex as the lock. The kernel's lock is not part of the library; a lock policy is a user type, and the harness shows one. The single required check of the matrix is os-matrix. |
| D61 | Coverage of generated code over any model | A 100 % coverage gate measured on four examples says little about a user's model. The claim rests on three checks: a matrix of schema features that every built and measured model set has to cover (and that the schema's properties are mapped to), valid random models generated from a fixed seed through the whole chain with the same gates, and a rule that an enum field without a default needs a member 0. The random run found defects of the generator in its first run (a test for only the first message of an interface, the interface byte order in raw decode errors, messages outside any interface, conditional messages in profiles without them), so it stays in CI and runs wider each night. Unreachable code is not excluded: it is not generated. It is evidence over many models, not a proof, and the user's gate remains. |
| D62 | Project templates | A new user starts from a working project instead of a blank file: wireforge init (also an MCP argument and a field of the project creation of the REST API and the web UI) copies one of three small templates, telemetry, command and raw, and replaces its name, namespace and version. The templates are ordinary projects kept as data files; CI builds and measures them like the examples, so a template never drifts from the generator. They show the common shapes and no advanced feature (profiles, conditions, user types, requirements), which stay in the YAML. init never overwrites: the directory must be empty. |
| D63 | CI check | The check a CI system runs is one command, wireforge ci, and the GitHub action and the GitLab example only call it, so every system and a developer's machine give the same answer. It validates, compares the project with the project at a git revision (the base of a pull request) for wire compatibility and the version bump, optionally builds and runs the tests, and writes one Markdown summary; the exit code is red when any of them fails. The action installs the WireForge it is part of, so pinning the action pins the tool. A base that cannot be read is reported in the summary and does not fail the check. |
| D64 | Distribution | The wheel and the source distribution are built with a fixed timestamp (the last commit) and must come out the same twice (the wheel byte for byte, the source distribution file for file), carry everything the tool needs at run time, and install and work in a clean environment. Python 3.10 to 3.13 are tested; ruff and mypy are pinned to one minor version. The version has one source. A release is a tag: the workflow builds, writes an SBOM and a dependency audit that must be clean, and publishes a GitHub release; PyPI upload is a separate job behind the pypi environment (the owner approves) and the variable PUBLISH_TO_PYPI, off until a trusted publisher is configured on PyPI. The package declares both licenses as an SPDX expression (BUSL-1.1 AND MIT). |
| D65 | Published protocols as examples | A model that is only checked against itself can share a wrong reading with the reference codec and the generated code. Two published protocols (Modbus RTU and Modbus TCP) are written from their specifications; their vectors are bytes from the examples of the specifications, never produced by WireForge, and an independent implementation (pymodbus, pinned) must agree byte for byte. What the schema cannot say is recorded as a finding and not bent to fit. The first comparison found a defect: a receiver on a link without a frame decoder did not check the checksum, and no receiver checked a header constant that is not the sync word; the generated receiver now does, with a test for the frame of every message. |
| D66 | Coverage points | The tests of a generated project are checked against the model while they are written: the model decides which points they must exercise, each test records what it covers, and a gap stops the generation as a defect of the generator. The points are the ones where a generator went wrong before (a test for the first message only, a check that is emitted for every message but tested for one). The required set comes from the cases of the model and from predicates the code generator shares with the test writer, not from the loops that write the tests, so a skipped message shows. It does not model individual compiler branches; the random models and the coverage gate stay the evidence for those. |
| D67 | Physical values and CAN databases | A field can carry scale and offset (physical = raw * scale + offset): the wire, the ranges, the defaults and the constants stay raw, the generated code adds a getter and a rounding, range-checking setter per field, and the reference codec adds the physical values to its result. The CAN database importer is written in the tool (a DBC file is a small, line-oriented format; a dependency would only be needed for the independent comparison, which cantools does in the tests, byte for byte on the example and on edge cases of both byte orders). A message takes one byte order; multiplexing, frames longer than 8 bytes and overlapping signals are refused with their line, because WireForge lays fields out one after the other and a layout that depends on a field value or on a second byte order would need a different model, and a wrong guess is worse than a refusal. --skip-unsupported lists what was left out. The CAN identifier is carried by the header of the interface (bit 31 is the extended-frame flag, as in DBC and SocketCAN), so a DBC network is an ordinary interface with the usual dispatch, framing and tests. |
| D68 | Published protocol library | The models of published protocols live in protocols/ (Modbus RTU and TCP moved there from examples/; examples/ keeps the tutorials), ship in the wheel and start a project with wireforge init --protocol (also the MCP and REST creation calls and the web UI list; the template mechanism of D62 serves both). A model enters the library only with an independent implementation of the same protocol to compare against byte for byte (D65), vectors that are the examples of the documents where there are any, a README that names the source, what is covered and what is not, and the same gates as every model (100 % coverage, feature matrix, matrices, fuzz). The models are written from the public documents without copying their text, and name the owner of the protocol as not affiliated. A protocol the schema cannot say is not bent into it: a small schema decision comes first or the protocol stays out and the README says so (UBX needed none: the id is little endian class | id << 8, and a checksum that skips the sync characters is a custom checksum). |
| D69 | C runtime | The generator will write C99 as well as C++17, and C code needs a runtime of its own: runtime/include/wireforge/c/, header-only and static inline, with the semantics of the C++ runtime (the status values and their order, the first error kept by the encoder and the decoder, the byte and bit rules, the checks, the CRC engine) so that the same model gives the same bytes and the same statuses in both languages. It is plain C99 and is tested as plain C (a program without a framework) with a stricter warning set than the C++ code gets, because C converts silently where C++ would need a cast. A checksum is a function over the covered bytes, not a type with a state: the encoder and the decoder have those bytes in memory, and the Python reference implementations of the custom checksums are one-shot functions as well. |
| D70 | C99 code of the model | --language c writes model.h and model.c with the rules of the C++ code and the runtime of D69. The types are plain structs: an array of variable size has a count member, an enum is an integer type with a macro per member, every name starts with the namespace of the project. Checks are chained with wf_first_error so that the generated functions have no branch of their own for them, which keeps the 100 % branch gate reachable. The tests are C++ (GoogleTest) that call the C functions, and every expectation still comes from the reference codec; the test project builds the C code with the warning set of C code as errors. Functions are generated only for the types and enums that a message or an interface uses, because a function nothing calls cannot be tested and the gate is 100 %. A custom checksum is a C function over the covered bytes, named in the model (c_impl, c_include), as the Python plugins already are. User types and the interface layer are not generated in C yet. |
| D71 | C99 interfaces | The interface layer of generated C is a handler struct of callbacks, one dispatch function and a link that owns its buffers, over a runtime of a ring, a frame decoder and a link (D69) that keep the behaviour of the C++ ones (the same framing rules, the same statuses, the same resynchronisation) and drop what C99 cannot express: locks and atomics. A link belongs to one thread at a time and the application guards it where it shares a ring with an interrupt. A null callback means the default (decode and forward, or ignore), so a handler can be as small as the application needs, and the generated tests cover both. Interface code is tested like the model: the cases come from the reference codec, short_frame, unknown_id and ignored are coverage points, and the 100 % gate covers the interface sources as well. |
| D72 | GitHub Marketplace listing | The WireForge check action is listed from the main repository: no separate repository and no PyPI pin, because the action installs the WireForge of the ref written after uses: and stars and traffic stay with the project. Documentation names a full release tag (@v0.1.0), and no moving major tag is kept before 1.0. The licenses already in the repository serve as the end-user terms (LICENSE, runtime/LICENSE), the action collects no data, support is the issue tracker, and the listing is free. Running wireforge ci (validation, comparison with earlier revisions, generated tests) is non-production use even in commercial product repositories; this is written into the Additional Use Grant rather than only into the documentation. |
| D73 | Wiki as the entry layer | The repository wiki is a short entry layer for new users: what the tool does, install, the published protocols, importers, integrations and a FAQ with the license summary. It links to docs/ instead of copying it, so there is one source of truth for the reference, and its links name a release tag so that it stays consistent with a published version. It is edited by hand by collaborators only, with no synchronisation from docs/. The licensing summary is stated as a summary that points to LICENSE, with one contact address for commercial licensing. |
| D74 | Payloads without trailing zeros | An interface can send every payload without its trailing zero bytes (trim_trailing_zeros), the rule that MAVLink 2 depends on. It is a property of the frame, not of the message: serialize() still writes the whole payload, the frame writer shortens it with a runtime helper and the default raw handler extends a shorter payload with zeros before decoding, so the generated code gains no branch and the 100 % branch gate holds. The receiver restores zeros up to the size of the message, so every message of such an interface has a fixed size (SR-25), and switching the setting is a breaking change. A payload longer than the message stays TrailingBytes unless allow_trailing_bytes is set; the MAVLink 2 model leaves it off, because with it nothing could make its messages fail to decode and the error path of the generated handler would be unreachable. The tests the generator writes take truncated payloads out of the decode-error cases of such an interface and check the trimmed frame size of every message (FRAME_TRIM). |
| D75 | Whole-byte header bit-fields | A header field may be a bit-field 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). Under those orders every such field of a bit group has bytes of its own, so generated code writes and reads it as a field of that width (write_width, wf_enc_unsigned) instead of packing bits, and the frame decoder finds a message id of any width from 1 to 8 bytes. This gives the 24-bit message id of MAVLink 2 without a new integer type. Other header bit-fields stay outside the supported subset of the interface generator. |
| D76 | One tutorial that runs in CI | The tutorial (docs/tutorial/) follows one example from start to end, the MAVLink 2 link of a small drone, because a protocol readers know and an independent implementation to talk to (pymavlink) make every step checkable: the reader adds a message, generates code, builds a vehicle and sees a ground station written without WireForge understand it. The commands of the chapters run in the quickstart job with the wheel a user installs (quality/run_tutorial.py): a fenced block after <!-- tutorial: run --> runs as shown, a <!-- tutorial: hidden --> comment holds the terminal equivalent of a step done in an editor or the web UI, and blocks that need a GUI, Wireshark or an agent are not run. The example application lives next to the tutorial (examples/tutorial/drone_app/) and builds against the reader's own model. Screenshots are taken from the real web UI over a fresh workspace, with numbered marks the text refers to. |
| D77 | MAVLink dialects as projects | wireforge import-mavlink reads a MAVLink XML dialect and its includes and writes a MAVLink 2 project with the frame of the published model, so every message of common.xml, ArduPilot's or a user's dialect becomes a model in one step. The CRC_EXTRA byte is computed from the definition with the rule of the MAVLink generators and written to the one list the C, C++ and Python checksum code reads, instead of being copied by hand. Fields keep their integer types although the XML names an enum, because a MAVLink receiver must accept values that a newer dialect added and an enum field would reject them; the enums are imported for their names and values. Only MAVLink 2 frames are written, and only the command line and the Python service offer the importer, since it reads files of the machine it runs on; a document type is refused, so the XML parser never expands entities. The test imports every dialect pymavlink ships and compares the byte and the field order of each message, and every message of common.xml byte for byte; a ten-message import under tests/models runs through all generated-code gates and must equal what the importer writes. |
| D78 | The tutorial on a microcontroller | The vehicle of the tutorial is written once in C99 against the generated C code and a two-function transport, and runs unchanged on a desktop over UDP and as bare-metal firmware on a Cortex-M4 over its UART. The firmware runs in QEMU's MPS2 board (mps2-an386), so the chapter needs no hardware and runs in CI where the Arm toolchain and QEMU are installed; a chapter declares the tools it needs and is skipped elsewhere. For this, wireforge_generate() takes LANGUAGE c and gives a static C99 library without the C++ runtime, so a C-only cross build works. The MAVLink 2 Wireshark hook reads the CRC_EXTRA bytes from the project's crc_extra.h (found from its own place in the project, with its built-in table as the fallback), so the list of CRC_EXTRA bytes stays one file. Against ArduPilot, the tutorial shows a C ground station built from the import of the whole ardupilotmega.xml talking to the ArduCopter simulator; that step needs a download from ArduPilot and is not run in CI. |
| D79 | The no-heap claim for every model | The claim that generated code uses no heap has to hold for any model, not only for those in the repository. Three layers back it: the object-level symbol check now also takes the test models (an import of a MAVLink dialect among them) and the generated C, and fails when a message of an interface has no self-test, because header objects hold no template or inline code and only the self-tests instantiate it; the generated C++ test project counts operator new around decoding, encoding, sending and dispatching every message; the generated C test project renames the heap functions so that their use does not link, since operator new cannot be counted in C and wrapping malloc is not portable. A heap call put into the runtime on purpose is caught by all three. The wider check found FixedString calling string_view::substr, whose exception path stays in the object at -O0; it no longer does. |
| D80 | Rust through the generated C | Rust users call the generated C code through bindgen (examples/tutorial/drone_app_rust) instead of a Rust generator. A generator would need its own runtime, tests, coverage gate and CI for every feature, and Rust has good derive-based libraries for binary formats, so the need is unproven; the C code needs no heap, so the no_std library works already. A Rust target can follow if users ask for one. The example needs a Rust toolchain and is not run in CI. wireforge runtime-dir gives a build script the runtime headers. |
| D81 | The tutorial on real hardware | examples/tutorial/drone_firmware_stm32h7 runs the same vehicle.c on a NUCLEO-H743ZI2 without a vendor library, MAVLink 2 over the ST-LINK's serial port. A real UART is slower than the emulated one and has a small FIFO, so a loop moves bytes between the UART and two ring buffers and the link only touches the rings. CI compiles the firmware with the tutorial; flashing needs the board, so running it is a manual check. A second toolchain file gives the Cortex-M7 flags and libraries. |
| D82 | Systems of units | One model describes all the programs of a system: nodes at the project level, nodes per interface and from per message, because the direction belongs to a message (who sends it) and not to an interface, and a message is defined once. Each unit gets a view of the model (its interfaces, its messages and what they use) and the generators run on that view, so the code, tests and documents of a unit are the same in a full run and with --node, and a change that does not reach a unit leaves its hash. The unit sees a message only as sent or received: the handler has callbacks for what it receives, and a frame of a message it only sends is NotForThisNode, not an error. The hook for a frame that reaches no callback only counts by default and never prints, so the runtime has no output of its own. Link counters are always present; counters per message are a model setting (message_counters) because they cost RAM. Not in scope: question and answer pairing, timing, addressing, several instances of one unit, unit versions, hiding parts of the model in a bundle. |