docs: fix spec-vs-implementation gaps per audit findings#8
docs: fix spec-vs-implementation gaps per audit findings#8SuperInstance wants to merge 1 commit intomainfrom
Conversation
Address open issues #1-#7: - Add CONFORMANCE.md: canonical spec vs implementation divergence documentation, legacy opcode mapping table, migration path, conformance levels (closes #1, #2, #3, #5) - Note that ENCODING-FORMATS.md (1131 lines) formally defines all 7 encoding formats (A-G) with bit-level diagrams (closes #4, #6) - Update ISA.md: add Appendix C with conformance notes pointing to CONFORMANCE.md and ENCODING-FORMATS.md - Update SIGNAL.md §18: add Amendment 1 review status, link each open question to its proposed resolution (addresses #7) - Update README.md: add ENCODING-FORMATS.md and CONFORMANCE.md to document index, update line counts
![beta-devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/2443040?s=60&v=4){kind=small}
| 0x20 0x00 0x01 0x02 ; ADD R0, R1, R2 (Format E) | ||
| 0x00 ; HALT (Format A) | ||
| ; Expected: R0 = 59, halted = true |
There was a problem hiding this comment.
🔴 Smoke test writes ADD result to R0, which is hardwired to zero — expected result is wrong
The conformance smoke test uses ADD R0, R1, R2 (line 183) and expects R0 = 59 (line 185), but R0 is hardwired to zero throughout the specification. ISA.md:193 states "R0 | ZERO | Hardwired to 0 (writes ignored)", ENCODING-FORMATS.md:74 states "Writes are silently discarded", and the same CONFORMANCE.md:116 says "Register file: R0 hardwired to 0". A conformant VM must discard the write, so R0 will remain 0 — not 59. This self-contradictory test vector will mislead implementers into either thinking their VM is broken or incorrectly implementing R0 as writable. The fix is to use a different destination register (e.g., ADD R3, R1, R2 → R3 = 59).
| 0x20 0x00 0x01 0x02 ; ADD R0, R1, R2 (Format E) | |
| 0x00 ; HALT (Format A) | |
| ; Expected: R0 = 59, halted = true | |
| 0x20 0x03 0x01 0x02 ; ADD R3, R1, R2 (Format E) | |
| 0x00 ; HALT (Format A) | |
| ; Expected: R3 = 59, halted = true |
Was this helpful? React with 👍 or 👎 to provide feedback.
Debug
1 participant
Summary
Addressed all 7 open issues in the flux-spec repo by documenting and resolving spec-vs-implementation gaps.
Issues Addressed
Changes