feat(io-board-interface): CPU->MCU command-gate reference oracle + vectors - #70
Merged
Merged
Conversation
…ctors Add a host-side reference oracle for the MCU ingress command gate under a new contributor folder (contributions/io-board-interface/smailzhu/): - oomwoo_command_gate.py: validate_command() restating the firmware gate rules (version -> known type -> direction -> payload length -> field values), with the applicable oomwoo_cpu_ingress_result_t reason codes. - command_gate_vectors_v1.json: 57 accept/reject vectors with expected outcomes authored by hand from the firmware rules (not computed by the oracle), so the test checks the oracle against independent fixtures. - generate_gate_vectors.py --check keeps the corpus fresh. - test_command_gate.py: oracle-vs-corpus, schema, coverage, and a drift guard that requires the message set + struct formats to match the contract manifest. Decoupled: structure restated from protocol_v1.json; nothing imports another contributor's codec at runtime. Scope is the decoded-frame command gate only (no framing/CRC). A firmware consumer of the same JSON is proposed as follow-up. Wired into the host CI python job (generate --check + unittest discover).
Collaborator
|
Thank you! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A host-side reference oracle for the MCU ingress command gate, in a new
contributor folder
contributions/io-board-interface/smailzhu/.validate_command(message_type, version, payload)restates the firmware gate'saccept/reject decision in Python, backed by a language-neutral accept/reject
vector corpus.
Why
The firmware's gate rules (
oomwoo_cpu_ingress_validate_frame) and the writtencontract can drift silently. This makes the gate decisions explicit, versioned,
and testable — and the corpus is language-neutral so the firmware repo can later
run the same cases against the C gate.
Contents
tools/oomwoo_command_gate.py—validate_command+GateResultconformance/command_gate_vectors_v1.json— 57 accept/reject vectorsconformance/generate_gate_vectors.py— regenerates;--checkfails if staletests/test_command_gate.py— oracle-vs-corpus, schema, coverage, drift guardREADME.mdRules (mirror firmware)
Precedence: version → known type → direction → payload length → field values.
Reason codes:
OK, BAD_VERSION, UNKNOWN_TYPE, WRONG_DIRECTION, WRONG_PAYLOAD_LENGTH, VALUE_OUT_OF_RANGE.Design
struct_format) restated fromprotocol_v1.json; nothing imports another contributor's codec at runtime. Atest drift-checks the message set + struct formats against the manifest.
firmware rules — never computed by
validate_command.StreamDecoder), not the safety gate itself — a reference oracle.
CI
Adds two steps to the existing
pythonjob:generate_gate_vectors.py --checkand
unittest discoverover the new tests. Stdlib only, no new dependency.Testing
6 tests pass locally (~0.04s); existing io-board-interface suite still green.
Verified green on fork CI.
Proposed follow-up
A consumer in
makerspet/oomwoo-firmwarethat runs this same JSON againstoomwoo_cpu_ingress_validate_frameand asserts the C result matches eachvector's reason. That is what enforces cross-repo agreement; this PR ships the
oracle and corpus that make it possible.