pr 2.1
This commit is contained in:
@@ -268,6 +268,124 @@ Required behavior:
|
||||
|
||||
- patch before `Verifier::verify(...)`
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
Implementation should be staged so each phase leaves the workspace in a coherent state and keeps the verifier/VM contract intact.
|
||||
|
||||
### Commit Checklist
|
||||
|
||||
1. `prometeu-bytecode: add SyscallDecl model and mandatory SYSC section`
|
||||
2. `prometeu-bytecode: add SYSC parser validation and load errors`
|
||||
3. `prometeu-bytecode: add phase-1 coverage for empty/valid/invalid SYSC`
|
||||
4. `prometeu-bytecode: wire downstream constructors to new BytecodeModule.syscalls field`
|
||||
5. `prometeu-bytecode: clean up naming/docs after phase-1 passes`
|
||||
|
||||
### Phase 1 - Extend PBX module format
|
||||
|
||||
Target crates:
|
||||
|
||||
- `crates/console/prometeu-bytecode`
|
||||
|
||||
Steps:
|
||||
|
||||
1. add `SyscallDecl` to `src/model.rs` and extend `BytecodeModule` with `syscalls: Vec<SyscallDecl>`
|
||||
2. reserve a new section kind for `SYSC` in module serialization/deserialization
|
||||
3. enforce the mandatory-section rule: valid PBS images always carry `SYSC`, including `count = 0`
|
||||
4. reject malformed payloads, invalid UTF-8, and duplicate canonical identities during load
|
||||
5. update `src/lib.rs` exports if needed so the VM and HAL can consume the new declarations
|
||||
|
||||
Checkpoint:
|
||||
|
||||
- `BytecodeLoader::load(...)` returns `BytecodeModule` with canonical syscall declarations preserved from PBX
|
||||
|
||||
### Phase 2 - Add pre-load opcode support
|
||||
|
||||
Target crates:
|
||||
|
||||
- `crates/console/prometeu-bytecode`
|
||||
|
||||
Steps:
|
||||
|
||||
1. add `HOSTCALL` to `src/opcode.rs` with a `u32` immediate
|
||||
2. extend `src/opcode_spec.rs` and `src/decoder.rs` so the loader can scan and decode `HOSTCALL`
|
||||
3. update `src/assembler.rs` and `src/disassembler.rs` so tests and fixtures can produce/read pre-load artifacts
|
||||
4. keep the runtime contract explicit: `HOSTCALL` is representable in bytecode artifacts but must not survive loader patching
|
||||
|
||||
Checkpoint:
|
||||
|
||||
- bytecode tooling round-trips `HOSTCALL <index>` correctly, while runtime execution still depends on patched `SYSCALL <id>`
|
||||
|
||||
### Phase 3 - Bridge PBX declarations to host metadata
|
||||
|
||||
Target crates:
|
||||
|
||||
- `crates/console/prometeu-hal`
|
||||
|
||||
Steps:
|
||||
|
||||
1. add a resolver path that accepts program-owned syscall declarations instead of only `&'static str` identities
|
||||
2. resolve each `(module, name, version)` against `src/syscalls.rs`
|
||||
3. validate `arg_slots` and `ret_slots` against authoritative `SyscallMeta`
|
||||
4. validate required capabilities against cartridge-derived `CapFlags`
|
||||
5. return deterministic, load-facing errors for unknown syscalls, ABI mismatches, and missing capabilities
|
||||
|
||||
Design note:
|
||||
|
||||
- this phase likely needs a small owned-string adapter or a new helper alongside `resolve_program_syscalls(...)`, because PBX strings are runtime data, not `&'static str`
|
||||
|
||||
Checkpoint:
|
||||
|
||||
- given only `BytecodeModule.syscalls` plus granted `CapFlags`, the loader can produce a resolved table `sysc_index -> syscall_id`
|
||||
|
||||
### Phase 4 - Patch before verification
|
||||
|
||||
Target crates:
|
||||
|
||||
- `crates/console/prometeu-vm`
|
||||
|
||||
Steps:
|
||||
|
||||
1. add a load-time patching helper near `src/virtual_machine.rs` or a small dedicated module
|
||||
2. run that helper immediately after `BytecodeLoader::load(...)` and before `Verifier::verify(...)`
|
||||
3. scan `module.code`, decode every instruction, and rewrite `HOSTCALL <index>` into `SYSCALL <resolved_id>`
|
||||
4. reject out-of-bounds `HOSTCALL` indices during the scan
|
||||
5. track `SYSC` usage and reject declarations that are never referenced
|
||||
6. assert that no `HOSTCALL` remains before handing code to the verifier
|
||||
7. only then call `Verifier::verify(...)`, compute `max_stack_slots`, and build `ProgramImage::from(module)`
|
||||
|
||||
Why the sequencing matters:
|
||||
|
||||
- the current load path in `crates/console/prometeu-vm/src/virtual_machine.rs` verifies the raw module immediately after `BytecodeLoader::load(...)`
|
||||
- `ProgramImage` currently stores only the final ROM/functions/constants and does not preserve a syscall declaration table, so patching must happen while the code is still a `BytecodeModule`
|
||||
|
||||
Checkpoint:
|
||||
|
||||
- the verifier sees only numeric `SYSCALL <id>` instructions, preserving the existing verifier and VM execution model
|
||||
|
||||
### Phase 5 - Tests and failure matrix
|
||||
|
||||
Target crates:
|
||||
|
||||
- `crates/console/prometeu-bytecode`
|
||||
- `crates/console/prometeu-hal`
|
||||
- `crates/console/prometeu-vm`
|
||||
|
||||
Steps:
|
||||
|
||||
1. add serialization/deserialization tests for missing, empty, valid, malformed, and duplicate `SYSC`
|
||||
2. add opcode tests for `HOSTCALL` decoding and assembler/disassembler coverage
|
||||
3. add resolver tests for unknown identity, ABI mismatch, and capability mismatch
|
||||
4. add VM load-path tests proving patch-before-verify behavior
|
||||
5. add an assertion that final executable images contain only numeric `SYSCALL`
|
||||
|
||||
Suggested PR slicing:
|
||||
|
||||
1. bytecode format + tests
|
||||
2. `HOSTCALL` opcode plumbing
|
||||
3. HAL resolution/ABI validation
|
||||
4. VM loader patching
|
||||
5. integration and regression tests
|
||||
|
||||
## Deterministic Load Errors
|
||||
|
||||
Load must fail for at least:
|
||||
|
||||
Reference in New Issue
Block a user