141 lines
3.3 KiB
Markdown
141 lines
3.3 KiB
Markdown
## PR-09 — Debug info v0: spans, symbols, and traceable traps
|
|
|
|
**Why:** Industrial debugging requires actionable failures.
|
|
|
|
### Scope
|
|
|
|
* Add optional debug section:
|
|
|
|
* per-instruction span table (`pc -> (file_id, start, end)`)
|
|
* function names
|
|
* Enhance trap payload with debug span (if present)
|
|
|
|
### Tests
|
|
|
|
* trap includes span when debug present
|
|
* trap still works without debug
|
|
|
|
### Acceptance
|
|
|
|
* You can pinpoint “where” a trap happened reliably.
|
|
|
|
---
|
|
|
|
## PR-10 — Program image + linker: imports/exports resolved before VM run
|
|
|
|
**Why:** Imports are compile-time, but we need an industrial linking model for multi-module PBS.
|
|
|
|
### Scope
|
|
|
|
* Define in bytecode:
|
|
|
|
* `exports`: symbol -> func_id/service entry (as needed)
|
|
* `imports`: symbol refs -> relocation slots
|
|
* Implement a **linker** that:
|
|
|
|
* builds a `ProgramImage` from N modules
|
|
* resolves imports to exports
|
|
* produces a single final `FunctionTable` and code blob
|
|
|
|
### Notes
|
|
|
|
* VM **does not** do name lookup at runtime.
|
|
* Linking errors are deterministic: `LINK_UNRESOLVED_SYMBOL`, `LINK_DUP_EXPORT`, etc.
|
|
|
|
### Tests
|
|
|
|
* two-module link success
|
|
* unresolved import fails
|
|
* duplicate export fails
|
|
|
|
### Acceptance
|
|
|
|
* Multi-module PBS works; “import” is operationalized correctly.
|
|
|
|
---
|
|
|
|
## PR-11 — Canonical integration cartridge + golden bytecode snapshots
|
|
|
|
**Why:** One cartridge must be the unbreakable reference.
|
|
|
|
### Scope
|
|
|
|
* Create `CartridgeCanonical.pbs` that covers:
|
|
|
|
* locals
|
|
* arithmetic
|
|
* if
|
|
* function call
|
|
* syscall clear
|
|
* input snapshot
|
|
* Add `golden` artifacts:
|
|
|
|
* canonical AST JSON (frontend)
|
|
* IR Core (optional)
|
|
* IR VM / bytecode dump
|
|
* expected VM trace (optional)
|
|
|
|
### Tests
|
|
|
|
* CI runs cartridge and checks:
|
|
|
|
* no traps
|
|
* deterministic output state
|
|
|
|
### Acceptance
|
|
|
|
* This cartridge is the “VM heartbeat test”.
|
|
|
|
---
|
|
|
|
## PR-12 — VM test harness: stepper, trace, and property tests
|
|
|
|
**Why:** Industrial quality means test tooling, not just “it runs”.
|
|
|
|
### Scope
|
|
|
|
* Add `VmRunner` test harness:
|
|
|
|
* step limit
|
|
* deterministic trace of stack deltas
|
|
* snapshot of locals
|
|
* Add property tests (lightweight):
|
|
|
|
* stack never underflows in verified programs
|
|
* verified programs never jump out of bounds
|
|
|
|
### Acceptance
|
|
|
|
* Debugging is fast, and regressions are caught.
|
|
|
|
---
|
|
|
|
## PR-13 — Optional: Refactor Value representation (tagged slots) for clarity
|
|
|
|
**Why:** If current `Value` representation is the source of complexity/bugs, refactor now.
|
|
|
|
### Scope (only if needed)
|
|
|
|
* Make `Slot` explicit:
|
|
|
|
* `Slot::I32`, `Slot::I64`, `Slot::U32`, `Slot::Bool`, `Slot::ConstId`, `Slot::GateId`, `Slot::Unit`
|
|
* Multi-slot types become sequences of slots.
|
|
|
|
### Acceptance
|
|
|
|
* Simpler, more verifiable runtime.
|
|
|
|
---
|
|
|
|
## Definition of Done (DoD) for PBS v0 “minimum executable”
|
|
|
|
A single canonical cartridge runs end-to-end:
|
|
|
|
* `let` declarations (locals)
|
|
* arithmetic (+, -, *, /, %, comparisons)
|
|
* `if/else` control flow
|
|
* `when` expression (if present in lowering)
|
|
* function calls with params + returns (including `void`)
|
|
* multiple return slots (flattened structs / hardware value types)
|
|
* host syscalls (e.g., `GfxClear565`, `InputPadSnapshot`, `InputTouchSnapshot`)
|
|
* deterministic traps (OOB bounded, invalid local, invalid call target, stack underflow) |