Prepare SpWKit 1.0 stable software contract

[Inczert]

Goal

Define and execute the work required for SpWKit v1.0.0 as a stable open-source software toolkit, independent of whether a proprietary/private FPGA implementation is available.

v1.0 means the software-facing contract is mature enough for external applications and future hardware providers to depend on it without redesigning the application layer.

Proposed v1.0 promise

SpWKit 1.0 defines a stable SpaceWire-facing software API and backend contract for simulation, distributed testing, virtual devices, embedded systems, and hardware drivers. Applications developed against the virtual backends can migrate to a conforming hardware backend without changing their SpaceWire-facing application logic.

What v1.0 must guarantee

• stable authoritative C11 public API for the 1.x line;
• explicit source/ABI compatibility policy;
• stable backend/DRIVER integration contract;
• consistent lifecycle, packet, EOP/EEP, timeout, error, readiness, statistics and zero-copy ownership semantics;
• documented threading/resource guarantees;
• deterministic simulator that is independently useful for software development;
• executable cross-backend behavioral equivalence evidence;
• install/package usability and maintained examples;
• ABI/exported-symbol regression gates;
• robustness evidence appropriate to a stable infrastructure library;
• positive, evidence-backed conformance claims for the applicable software-facing requirements of ECSS-E-ST-50-12C Rev.1, with a traceability/applicability matrix that distinguishes software-verified requirements from provider/hardware-delegated, not-applicable, and not-yet-implemented requirements.

ECSS conformance boundary

SpWKit must not use a blanket disclaimer that it makes no ECSS conformance claim. It should claim conformity where the requirement falls within the public software/runtime abstraction and evidence exists.

Physical/controller/PHY/electrical implementation requirements belong to the concrete hardware provider. A provider such as the private spwkit-fpga project is responsible for its own ECSS hardware-side conformance evidence. Full end-to-end SpaceWire conformance therefore depends on combining the software contract with a conforming physical provider; neither repository inherits the other repository's evidence automatically.

What does not block v1.0

• a specific FPGA/HDL implementation;
• physical SpaceWire PHY/electrical HIL for the generic SpWKit software package;
• USB-to-SpaceWire hardware;
• ASIC implementation;
• RMAP or other optional upper layers;
• router implementation.

The absence of a specific physical implementation does not remove the requirement to document and claim the ECSS requirements that SpWKit itself can satisfy and verify in software.

Immediate v0.6.1 consolidation

Before intentional pre-1 contract changes:

• Add benchmark backend capability discovery #171 benchmark backend capability discovery
• Add benchmark host environment metadata #173 benchmark host environment metadata
• Synchronize post-v0.6 documentation and v0.6.1 results #208 synchronize post-v0.6 documentation and v0.6.1 results

v0.6.1 records and packages the completed profiling/performance work without intentionally breaking the public contract.

Pre-v1 workstreams

• Harden public ABI and structure extension rules before v1.0 #210 harden public ABI and structure extension rules
• Run the portable DRIVER backend through the reusable public contract suite #211 run DRIVER through the reusable public backend contract
• Define stable 1.x threading, error, timeout and resource semantics #212 define stable threading/error/timeout/resource semantics
• Add 1.x source, ABI and exported-symbol compatibility gates #213 add source/ABI/exported-symbol compatibility gates
• Formalize simulator-to-backend behavioral equivalence for v1.0 #214 formalize simulator-to-backend behavioral equivalence
• Add pre-v1 robustness, fuzz and soak evidence #215 add robustness/fuzz/soak evidence
• Enforce protected main/develop release governance before v1.0 #216 enforce protected main/develop release governance
• Complete v0.7.0 ECSS software-conformance and performance release gate #224 complete the v0.7.0 ECSS software-conformance and performance release gate
• Decouple VSPW-TP from UDP and add transport-provider abstraction #229 decouple VSPW-TP from UDP and introduce a transport-provider boundary
• Quantify performance impact of transport-independent VSPW and raw Ethernet #230 quantify transport-abstraction and raw-Ethernet performance implications

Release-quality performance policy

Before each release, changes that can affect performance must be identified from the release delta and profiled with the existing controlled measurement infrastructure where applicable. Reproducible regressions outside normal measurement noise must be investigated. Avoidable regressions are optimized before release; necessary correctness/semantic tradeoffs may be accepted only when quantified and documented.

Patch releases are for defects discovered after a release, not a convenient place to knowingly postpone avoidable performance cleanup from the release candidate.

Suggested release progression

• v0.6.1: profiling/performance consolidation and documentation sync; no intentional public contract break.
• v0.7.x: behavioral/backend contract hardening and simulator acceptance, followed by software-scope ECSS traceability and a final performance-regression gate before v0.7.0 publication.
• v0.8.x: public API/ABI and DRIVER contract candidate; perform any necessary breaking cleanup while still pre-1, including the VSPW transport-provider refactor and its performance validation if ready.
• v0.9.x: 1.0 release candidate; API frozen, compatibility and robustness gates active.
• v1.0.0: stable software contract with documented software-scope ECSS conformance and provider boundaries.

The exact number of intermediate releases is evidence-driven, not ceremonial.