adjustments on capabilities on cartridges
This commit is contained in:
@@ -0,0 +1,324 @@
|
||||
# PR-2 - PBX SYSC and HOSTCALL Loader Patching
|
||||
|
||||
## Goal
|
||||
|
||||
Teach the runtime to load canonical host bindings from PBX, resolve them at load time, validate ABI and capabilities, and rewrite pre-load host calls into final numeric syscalls.
|
||||
|
||||
This PR assumes PR-1 is already available, so cartridge capabilities are exposed to the loader as internal `CapFlags`.
|
||||
|
||||
## Why
|
||||
|
||||
Prometeu's hardware contract is:
|
||||
|
||||
- source- and SDK-level host APIs map to canonical identities `(module, name, version)`
|
||||
- load-time resolution maps those identities to numeric syscall ids
|
||||
- runtime execution is numeric-only via `SYSCALL <id>`
|
||||
|
||||
The runtime already has the important building blocks:
|
||||
|
||||
- canonical syscall registry
|
||||
- load-time `resolve_program_syscalls`
|
||||
- verifier support for numeric `SYSCALL <id>`
|
||||
- VM dispatch by numeric id
|
||||
|
||||
What is missing is the PBX and loader wiring.
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- add a mandatory PBX `SYSC` section
|
||||
- extend each `SYSC` entry with ABI shape
|
||||
- add pre-load opcode `HOSTCALL <sysc_index>`
|
||||
- parse `SYSC` at load time
|
||||
- resolve `SYSC` against the host syscall registry
|
||||
- validate declared ABI against authoritative host metadata
|
||||
- validate capabilities using cartridge-granted `CapFlags`
|
||||
- reject unused `SYSC` entries
|
||||
- reject out-of-bounds `HOSTCALL` indices
|
||||
- patch all `HOSTCALL <sysc_index>` to `SYSCALL <id>`
|
||||
- ensure verifier runs only on the patched image
|
||||
|
||||
Out of scope:
|
||||
|
||||
- compiler emission
|
||||
- stdlib SDK pack format
|
||||
- final external tooling for PBX generation
|
||||
- platform policy beyond current manifest-derived granted capabilities
|
||||
|
||||
## Architectural Contract
|
||||
|
||||
### PBX `SYSC`
|
||||
|
||||
`SYSC` is a unique, deduplicated, program-wide table of declared host bindings.
|
||||
|
||||
Each entry carries:
|
||||
|
||||
- `module`
|
||||
- `name`
|
||||
- `version`
|
||||
- `arg_slots`
|
||||
- `ret_slots`
|
||||
|
||||
`SYSC` is mandatory for every valid PBX.
|
||||
If the program requires no host bindings, `SYSC` is present with `count = 0`.
|
||||
|
||||
### Pre-load callsites
|
||||
|
||||
The compiler-side artifact form is:
|
||||
|
||||
```text
|
||||
HOSTCALL <u32 sysc_index>
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `sysc_index` is zero-based into the `SYSC` table
|
||||
- code must not contain final `SYSCALL <id>` for unresolved host-backed SDK calls
|
||||
- the final executable image given to the VM must contain no `HOSTCALL`
|
||||
|
||||
### Load-time responsibilities
|
||||
|
||||
The loader must:
|
||||
|
||||
1. parse `SYSC`
|
||||
2. resolve each entry to `syscall_id`
|
||||
3. validate `arg_slots` and `ret_slots`
|
||||
4. validate capabilities
|
||||
5. scan code for `HOSTCALL`
|
||||
6. mark used `SYSC` indices
|
||||
7. reject out-of-bounds indices
|
||||
8. reject unused `SYSC` entries
|
||||
9. rewrite `HOSTCALL <index>` into `SYSCALL <id>`
|
||||
10. ensure no `HOSTCALL` remains
|
||||
11. only then hand the image to the verifier
|
||||
|
||||
## PBX Format Changes
|
||||
|
||||
### `prometeu-bytecode`
|
||||
|
||||
Add a new section kind:
|
||||
|
||||
- `SYSC`
|
||||
|
||||
Recommended temporary binary layout:
|
||||
|
||||
```text
|
||||
u32 count
|
||||
repeat count times:
|
||||
u16 module_len
|
||||
[module_len bytes UTF-8]
|
||||
u16 name_len
|
||||
[name_len bytes UTF-8]
|
||||
u16 version
|
||||
u16 arg_slots
|
||||
u16 ret_slots
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- strings are UTF-8
|
||||
- duplicate canonical identities are invalid
|
||||
- malformed lengths are invalid
|
||||
- missing `SYSC` is invalid
|
||||
|
||||
### Bytecode model changes
|
||||
|
||||
Extend `BytecodeModule` with a syscall declaration vector.
|
||||
|
||||
Suggested shape:
|
||||
|
||||
```rust
|
||||
pub struct SyscallDecl {
|
||||
pub module: String,
|
||||
pub name: String,
|
||||
pub version: u16,
|
||||
pub arg_slots: u16,
|
||||
pub ret_slots: u16,
|
||||
}
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```rust
|
||||
pub syscalls: Vec<SyscallDecl>
|
||||
```
|
||||
|
||||
Serialization/deserialization must include section kind for `SYSC`.
|
||||
|
||||
## Opcode Changes
|
||||
|
||||
### Add `HOSTCALL`
|
||||
|
||||
Add a new opcode:
|
||||
|
||||
- `HOSTCALL`
|
||||
|
||||
Immediate:
|
||||
|
||||
- `u32 sysc_index`
|
||||
|
||||
Recommended behavior:
|
||||
|
||||
- valid only in pre-load artifact form
|
||||
- not allowed to reach final verifier/VM execution path
|
||||
|
||||
Required code updates:
|
||||
|
||||
- opcode enum
|
||||
- decoder
|
||||
- opcode spec
|
||||
- assembler
|
||||
- disassembler
|
||||
|
||||
Verifier recommendation:
|
||||
|
||||
- the verifier does not need to support `HOSTCALL`
|
||||
- it should continue to run after loader patching only
|
||||
|
||||
## Loader Integration
|
||||
|
||||
### Resolution
|
||||
|
||||
Use the existing canonical resolver in `prometeu-hal::syscalls`.
|
||||
|
||||
For each `SYSC` entry:
|
||||
|
||||
1. resolve `(module, name, version)`
|
||||
2. obtain `SyscallResolved`
|
||||
3. compare `arg_slots`
|
||||
4. compare `ret_slots`
|
||||
5. compare required capability against granted cartridge flags
|
||||
|
||||
If any check fails, load fails deterministically.
|
||||
|
||||
### Capability source
|
||||
|
||||
Capabilities come from the already-loaded cartridge manifest via PR-1.
|
||||
|
||||
This PR must not invent authority from PBX contents.
|
||||
|
||||
### Code patching
|
||||
|
||||
Recommended algorithm:
|
||||
|
||||
1. parse code buffer
|
||||
2. whenever `HOSTCALL <index>` is found:
|
||||
3. validate `index < syscalls.len()`
|
||||
4. mark that `SYSC[index]` is used
|
||||
5. rewrite opcode/immediate in place or rebuild the code buffer
|
||||
6. emit final `SYSCALL <resolved_id>`
|
||||
|
||||
After scan:
|
||||
|
||||
1. every `SYSC` entry must be marked used
|
||||
2. no `HOSTCALL` may remain
|
||||
|
||||
Either patching strategy is acceptable:
|
||||
|
||||
- mutate byte buffer in place
|
||||
- rebuild a fresh patched buffer
|
||||
|
||||
The final `ProgramImage` must contain only numeric `SYSCALL <id>`.
|
||||
|
||||
## Verifier Contract
|
||||
|
||||
No verifier redesign is required.
|
||||
|
||||
The intended contract is:
|
||||
|
||||
- loader validates interface compatibility
|
||||
- verifier validates final numeric program structure
|
||||
|
||||
This means:
|
||||
|
||||
- loader checks `SYSC`-declared ABI against host metadata
|
||||
- verifier checks stack effects of final `SYSCALL <id>` using existing runtime metadata
|
||||
|
||||
This is intentional and not considered harmful duplication.
|
||||
|
||||
## Proposed Code Areas
|
||||
|
||||
### `prometeu-bytecode`
|
||||
|
||||
Likely files:
|
||||
|
||||
- `src/model.rs`
|
||||
- `src/opcode.rs`
|
||||
- `src/opcode_spec.rs`
|
||||
- `src/decoder.rs`
|
||||
- `src/assembler.rs`
|
||||
- `src/disassembler.rs`
|
||||
- `src/lib.rs`
|
||||
|
||||
### `prometeu-hal`
|
||||
|
||||
Likely files:
|
||||
|
||||
- `src/cartridge_loader.rs`
|
||||
- possibly helper types or resolver glue near syscall loading logic
|
||||
|
||||
### `prometeu-vm`
|
||||
|
||||
Likely files:
|
||||
|
||||
- load path in `src/virtual_machine.rs`
|
||||
|
||||
Required behavior:
|
||||
|
||||
- patch before `Verifier::verify(...)`
|
||||
|
||||
## Deterministic Load Errors
|
||||
|
||||
Load must fail for at least:
|
||||
|
||||
1. missing `SYSC`
|
||||
2. malformed `SYSC`
|
||||
3. invalid UTF-8
|
||||
4. duplicate syscall identities
|
||||
5. unknown syscall identity
|
||||
6. ABI mismatch between `SYSC` and host metadata
|
||||
7. missing capability
|
||||
8. `HOSTCALL` with out-of-bounds `sysc_index`
|
||||
9. declared `SYSC` entry unused by all `HOSTCALL`s
|
||||
10. `HOSTCALL` still present after patch
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- PBX parser supports mandatory `SYSC`
|
||||
- `BytecodeModule` carries syscall declarations
|
||||
- runtime understands `HOSTCALL`
|
||||
- loader resolves `SYSC` entries before verification
|
||||
- loader validates `arg_slots` and `ret_slots`
|
||||
- loader validates capabilities against cartridge flags
|
||||
- loader rewrites `HOSTCALL` to `SYSCALL`
|
||||
- verifier runs only on patched code
|
||||
- final VM execution path remains numeric-only
|
||||
|
||||
## Tests
|
||||
|
||||
Add tests covering:
|
||||
|
||||
1. valid PBX with empty `SYSC` and no `HOSTCALL`
|
||||
2. valid PBX with one syscall and one `HOSTCALL`
|
||||
3. unknown syscall identity
|
||||
4. capability mismatch
|
||||
5. ABI mismatch
|
||||
6. missing `SYSC`
|
||||
7. duplicate `SYSC` entries
|
||||
8. malformed `SYSC` payload
|
||||
9. `HOSTCALL` index out of bounds
|
||||
10. unused `SYSC` entry
|
||||
11. patched image contains only `SYSCALL`
|
||||
|
||||
Prefer synthetic in-memory PBX images in tests.
|
||||
|
||||
## Definition of Done
|
||||
|
||||
After this PR:
|
||||
|
||||
- PBX declares canonical host bindings in `SYSC`
|
||||
- pre-load code references those bindings with `HOSTCALL`
|
||||
- the loader resolves and validates them during load
|
||||
- the loader patches executable code to `SYSCALL <id>`
|
||||
- the verifier and VM continue to operate on numeric syscalls only
|
||||
Reference in New Issue
Block a user