pr 48
This commit is contained in:
@@ -0,0 +1,173 @@
|
||||
# Runtime Traps v0 — Prometeu VM Specification
|
||||
|
||||
> **Status:** Proposed (requires explicit owner approval)
|
||||
>
|
||||
> **Scope:** Prometeu VM / PBS v0 execution model
|
||||
|
||||
---
|
||||
|
||||
## 1. Motivation
|
||||
|
||||
Prometeu aims to be a **deterministic, industrial-grade virtual machine**.
|
||||
To achieve this, execution errors that are:
|
||||
|
||||
* caused by **user programs**,
|
||||
* predictable by the execution model,
|
||||
* and recoverable at the tooling / host level,
|
||||
|
||||
must be **explicitly represented** and **ABI-stable**.
|
||||
|
||||
This specification introduces **Runtime Traps** as a *formal concept*, consolidating behavior that already existed implicitly in the VM.
|
||||
|
||||
---
|
||||
|
||||
## 2. Definition
|
||||
|
||||
A **Runtime Trap** is a **controlled interruption of program execution** caused by a semantic violation detected at runtime.
|
||||
|
||||
A trap:
|
||||
|
||||
* **terminates the current execution frame** (or program, depending on host policy)
|
||||
* **does not corrupt VM state**
|
||||
* **returns structured diagnostic information** (`TrapInfo`)
|
||||
* **is deterministic** for a given bytecode + state
|
||||
|
||||
A trap is **not**:
|
||||
|
||||
* a debugger breakpoint
|
||||
* undefined behavior
|
||||
* a VM panic
|
||||
* a verifier/load-time error
|
||||
|
||||
---
|
||||
|
||||
## 3. Trap vs Other Failure Modes
|
||||
|
||||
| Category | When | Recoverable | ABI-stable | Example |
|
||||
| ------------------ | ---------------------- | ----------- | ---------- | -------------------------------- |
|
||||
| **Verifier error** | Load-time | ❌ | ❌ | Stack underflow, bad CFG join |
|
||||
| **Runtime trap** | Execution | ✅ | ✅ | OOB access, invalid local |
|
||||
| **VM panic** | VM invariant violation | ❌ | ❌ | Handler returns wrong slot count |
|
||||
| **Breakpoint** | Debug only | ✅ | ❌ | Developer inspection |
|
||||
|
||||
---
|
||||
|
||||
## 4. Trap Information (`TrapInfo`)
|
||||
|
||||
All runtime traps must produce a `TrapInfo` structure with the following fields:
|
||||
|
||||
```text
|
||||
TrapInfo {
|
||||
code: u32, // ABI-stable trap code
|
||||
opcode: u16, // opcode that triggered the trap
|
||||
pc: u32, // program counter (relative to module)
|
||||
message: String, // human-readable explanation (non-ABI)
|
||||
}
|
||||
```
|
||||
|
||||
### ABI Guarantees
|
||||
|
||||
* `code`, `opcode`, and `pc` are ABI-relevant and stable
|
||||
* `message` is diagnostic only and may change
|
||||
|
||||
---
|
||||
|
||||
## 5. Standard Trap Codes (v0)
|
||||
|
||||
### 5.1 Memory & Bounds
|
||||
|
||||
| Code | Name | Meaning |
|
||||
| -------------------- | ------------- | ------------------------------ |
|
||||
| `TRAP_OOB` | Out of bounds | Access beyond allowed bounds |
|
||||
| `TRAP_INVALID_LOCAL` | Invalid local | Local slot index out of bounds |
|
||||
|
||||
### 5.2 Heap / Gate
|
||||
|
||||
| Code | Name | Meaning |
|
||||
| ------------------- | -------------- | -------------------------- |
|
||||
| `TRAP_INVALID_GATE` | Invalid gate | Non-existent gate handle |
|
||||
| `TRAP_DEAD_GATE` | Dead gate | Gate with refcount = 0 |
|
||||
| `TRAP_TYPE` | Type violation | Heap or gate type mismatch |
|
||||
|
||||
### 5.3 System
|
||||
|
||||
| Code | Name | Meaning |
|
||||
| ---------------------- | --------------- | --------------------------------------- |
|
||||
| `TRAP_INVALID_SYSCALL` | Invalid syscall | Unknown syscall ID |
|
||||
| `TRAP_STACK_UNDERFLOW` | Stack underflow | Missing arguments for syscall or opcode |
|
||||
|
||||
> This list is **closed for PBS v0** unless explicitly extended.
|
||||
|
||||
---
|
||||
|
||||
## 6. Trap Semantics
|
||||
|
||||
### 6.1 Execution
|
||||
|
||||
When a trap occurs:
|
||||
|
||||
1. The current instruction **does not complete**
|
||||
2. No partial side effects are committed
|
||||
3. Execution stops and returns `TrapInfo` to the host
|
||||
|
||||
### 6.2 Stack & Frames
|
||||
|
||||
* Operand stack is left in a **valid but unspecified** state
|
||||
* Call frames above the trapping frame are not resumed
|
||||
|
||||
### 6.3 Host Policy
|
||||
|
||||
The host decides:
|
||||
|
||||
* whether the trap terminates the whole program
|
||||
* whether execution may be restarted
|
||||
* how the trap is surfaced to the user (error, log, UI, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 7. Verifier Interaction
|
||||
|
||||
The verifier **must prevent** traps that are statically provable, including:
|
||||
|
||||
* stack underflow
|
||||
* invalid control-flow joins
|
||||
* invalid syscall IDs
|
||||
* incorrect return slot counts
|
||||
|
||||
If a verifier rejects a module, **no runtime traps should occur for those causes**.
|
||||
|
||||
---
|
||||
|
||||
## 8. What Is *Not* a Trap
|
||||
|
||||
The following are **VM bugs or tooling errors**, not traps:
|
||||
|
||||
* handler returns wrong number of slots
|
||||
* opcode implementation violates `OpcodeSpec`
|
||||
* verifier and runtime disagree on stack effects
|
||||
|
||||
These must result in **VM panic**, not a trap.
|
||||
|
||||
---
|
||||
|
||||
## 9. Versioning Policy
|
||||
|
||||
* Trap codes are **ABI-stable within a major version** (v0)
|
||||
* New trap codes may only be added in a **new major ABI version** (v1)
|
||||
* Removing or reinterpreting trap codes is forbidden
|
||||
|
||||
---
|
||||
|
||||
## 10. Summary
|
||||
|
||||
Runtime traps are:
|
||||
|
||||
* an explicit part of the Prometeu execution model
|
||||
* deterministic and ABI-stable
|
||||
* reserved for **user-program semantic errors**
|
||||
|
||||
They are **not** debugging tools and **not** VM panics.
|
||||
|
||||
This spec formalizes existing behavior and freezes it for PBS v0.
|
||||
|
||||
---
|
||||
@@ -1,26 +1,3 @@
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user