pr1.1
This commit is contained in:
parent
c7786fa8b0
commit
73dc0c4cb2
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
184
docs/bytecode/RESET_LEGACY_MAP.md
Normal file
184
docs/bytecode/RESET_LEGACY_MAP.md
Normal file
@ -0,0 +1,184 @@
|
|||||||
|
PR-1.1 — Bytecode Legacy Inventory & Deletion Map
|
||||||
|
|
||||||
|
Goal
|
||||||
|
- Provide an explicit, reviewable inventory of all RC/HIP-era artifacts (opcodes, traps, types, helpers, docs, tests) and a deletion map for the ISA reset.
|
||||||
|
- No code changes in this PR — documentation only. Follow-up PRs will execute the deletions/edits.
|
||||||
|
|
||||||
|
Repository root
|
||||||
|
- runtime (this file lives at docs/bytecode/RESET_LEGACY_MAP.md)
|
||||||
|
|
||||||
|
Quick grep guide (reviewers)
|
||||||
|
- Use these commands from the project root. They avoid target/ and other generated dirs.
|
||||||
|
|
||||||
|
```
|
||||||
|
# Core RC/HIP signal words
|
||||||
|
grep -RIn --exclude-dir target --exclude-dir dist-staging --exclude-dir dist-workspace \
|
||||||
|
-e '\bHIP\b' -e '\bgate\b' -e 'GATE_' -e '\bretain\b' -e '\brelease\b' -e '\bscope\b' .
|
||||||
|
|
||||||
|
# Legacy opcodes (bytecode + VM handlers)
|
||||||
|
grep -RIn --exclude-dir target \
|
||||||
|
-e 'GateLoad' -e 'GateStore' -e 'GateBeginPeek' -e 'GateEndPeek' \
|
||||||
|
-e 'GateBeginBorrow' -e 'GateEndBorrow' -e 'GateBeginMutate' -e 'GateEndMutate' \
|
||||||
|
-e 'GateRetain' -e 'GateRelease' -e 'Alloc' \
|
||||||
|
crates/console/prometeu-bytecode crates/console/prometeu-vm
|
||||||
|
|
||||||
|
# Scope-related (inventory only; not necessarily to delete)
|
||||||
|
grep -RIn --exclude-dir target -e 'PushScope' -e 'PopScope' crates/console
|
||||||
|
|
||||||
|
# Trap codes with HIP/RC semantics
|
||||||
|
grep -RIn --exclude-dir target \
|
||||||
|
-e 'TRAP_INVALID_GATE' -e 'TRAP_DEAD_GATE' -e 'TRAP_TYPE' \
|
||||||
|
crates/console/prometeu-bytecode crates/console/prometeu-vm
|
||||||
|
|
||||||
|
# Value::Gate usages
|
||||||
|
grep -RIn --exclude-dir target -e 'Value::Gate' crates/console
|
||||||
|
|
||||||
|
# Docs that describe HIP/RC model
|
||||||
|
grep -RIn --exclude-dir target --include '*.md' -e '\bHIP\b' docs files
|
||||||
|
```
|
||||||
|
|
||||||
|
Legend for the deletion map
|
||||||
|
- Remove: file or symbol slated for deletion in follow-up PRs.
|
||||||
|
- Edit: file will survive but needs edits to remove/rename legacy parts.
|
||||||
|
- Keep: file or symbol remains under the GC stack+heap model (not part of RC/HIP removal) — listed here when helpful for context.
|
||||||
|
|
||||||
|
|
||||||
|
1) Legacy opcodes (RC/HIP)
|
||||||
|
|
||||||
|
Remove — OpCode variants (definitions and all references)
|
||||||
|
- prometeu-bytecode
|
||||||
|
- crates/console/prometeu-bytecode/src/opcode.rs
|
||||||
|
- OpCode::Alloc
|
||||||
|
- OpCode::GateLoad
|
||||||
|
- OpCode::GateStore
|
||||||
|
- OpCode::GateBeginPeek, OpCode::GateEndPeek
|
||||||
|
- OpCode::GateBeginBorrow, OpCode::GateEndBorrow
|
||||||
|
- OpCode::GateBeginMutate, OpCode::GateEndMutate
|
||||||
|
- OpCode::GateRetain, OpCode::GateRelease
|
||||||
|
- Notes: also appears in TryFrom<u16> mapping and in cycles() table inside same file.
|
||||||
|
- crates/console/prometeu-bytecode/src/opcode_spec.rs
|
||||||
|
- Spec entries for each of the above (names: GATE_LOAD, GATE_STORE, GATE_BEGIN_PEEK, ... GATE_RELEASE; ALLOC).
|
||||||
|
- crates/console/prometeu-bytecode/src/decoder.rs
|
||||||
|
- Keep file. No direct legacy handling beyond general decoding; remains after removing legacy opcodes.
|
||||||
|
- crates/console/prometeu-bytecode/src/model.rs
|
||||||
|
- Keep file. No opcode definitions here; only payload helpers like imm_u32x2 are generic. No deletion but re-check comments if they reference ALLOC semantics.
|
||||||
|
- crates/console/prometeu-bytecode/src/value.rs
|
||||||
|
- Edit: enum Value includes Gate(usize). This is HIP-only; plan to remove variant and downstream usages when ISA reset lands.
|
||||||
|
- crates/console/prometeu-bytecode/src/program_image.rs
|
||||||
|
- Edit: maps Value to ConstantPoolEntry; has a Value::Gate arm that turns into Null. Will be adjusted once Value::Gate is removed.
|
||||||
|
|
||||||
|
- prometeu-vm (execution semantics for legacy opcodes)
|
||||||
|
- crates/console/prometeu-vm/src/virtual_machine.rs
|
||||||
|
- Match arms for: Alloc, GateLoad/Store, GateBegin*/End* (Peek/Borrow/Mutate), GateRetain/Release.
|
||||||
|
- Gate pool and heap structures (GateEntry, GateId), resolve_gate() helper, and related fields in VM state.
|
||||||
|
- Unit tests tied to HIP/RC model, e.g.:
|
||||||
|
- fn test_hip_traps_oob()
|
||||||
|
- fn test_hip_traps_type()
|
||||||
|
- fn test_invalid_gate_traps()
|
||||||
|
- fn test_gate_ids_distinct_and_round_trip()
|
||||||
|
- crates/console/prometeu-vm/src/scope_frame.rs
|
||||||
|
- Inventory only (scope handling). Scope is not inherently HIP, keep or revise later under GC if needed.
|
||||||
|
|
||||||
|
- prometeu-hal / prometeu-system (touch points)
|
||||||
|
- crates/console/prometeu-hal/src/host_return.rs
|
||||||
|
- Pushes Value::Gate in some host return paths. Will require edits once Value::Gate is removed.
|
||||||
|
- crates/console/prometeu-system/*
|
||||||
|
- No direct HIP opcode handling expected, but grep for Value::Gate and GATE_ in formatting/printing if any.
|
||||||
|
|
||||||
|
|
||||||
|
2) Trap codes (RC/HIP)
|
||||||
|
|
||||||
|
Remove — HIP-specific traps (delete constants and all usages)
|
||||||
|
- crates/console/prometeu-bytecode/src/abi.rs
|
||||||
|
- TRAP_INVALID_GATE (0x01)
|
||||||
|
- TRAP_DEAD_GATE (0x02)
|
||||||
|
- TRAP_TYPE (0x04) — typed storage/gate mismatch (legacy)
|
||||||
|
|
||||||
|
Keep — still meaningful under GC model (names may be revised later, but remain functionally)
|
||||||
|
- crates/console/prometeu-bytecode/src/abi.rs
|
||||||
|
- TRAP_OOB (0x03) — out-of-bounds (generic)
|
||||||
|
- TRAP_INVALID_SYSCALL (0x0000_0007)
|
||||||
|
- TRAP_STACK_UNDERFLOW (0x0000_0008)
|
||||||
|
- TRAP_INVALID_LOCAL (0x0000_0009)
|
||||||
|
- TRAP_DIV_ZERO (0x0000_000A)
|
||||||
|
- TRAP_INVALID_FUNC (0x0000_000B)
|
||||||
|
- TRAP_BAD_RET_SLOTS (0x0000_000C)
|
||||||
|
|
||||||
|
Usages to edit alongside removal
|
||||||
|
- crates/console/prometeu-vm/src/virtual_machine.rs
|
||||||
|
- Imports: TRAP_INVALID_GATE, TRAP_DEAD_GATE, TRAP_TYPE
|
||||||
|
- resolve_gate() and gate handlers construct TrapInfo with those codes
|
||||||
|
- Tests asserting these trap codes
|
||||||
|
|
||||||
|
|
||||||
|
3) Legacy terminology occurrences (inventory)
|
||||||
|
|
||||||
|
Gate/GATE_
|
||||||
|
- Files containing gate-centric logic or names:
|
||||||
|
- crates/console/prometeu-bytecode/src/opcode.rs — Gate* opcodes
|
||||||
|
- crates/console/prometeu-bytecode/src/opcode_spec.rs — GATE_* names
|
||||||
|
- crates/console/prometeu-bytecode/src/value.rs — Value::Gate
|
||||||
|
- crates/console/prometeu-vm/src/virtual_machine.rs — GateEntry, GateId, handlers, tests
|
||||||
|
- docs/specs/pbs/Prometeu VM Memory model.md — extensive HIP/gate sections
|
||||||
|
- docs/specs/pbs/Prometeu Scripting - Prometeu Bytecode Script (PBS).md — HIP/gate model and APIs
|
||||||
|
|
||||||
|
Retain/Release (RC semantics)
|
||||||
|
- Opcode names: GateRetain, GateRelease — bytecode + VM
|
||||||
|
- Docs: reference counting sections in PBS and VM Memory model docs
|
||||||
|
|
||||||
|
Scope
|
||||||
|
- Opcode names: PushScope, PopScope — present in opcode.rs/opcode_spec.rs and executed in VM
|
||||||
|
- VM scope_frame.rs and scope_stack usage — not inherently HIP, but inventoried here per task wording
|
||||||
|
|
||||||
|
HIP (Heap Interface Protocol)
|
||||||
|
- Labelled sections/comments:
|
||||||
|
- crates/console/prometeu-bytecode/src/opcode.rs — comment header “HIP (Heap Interface Protocol)” above Gate* opcodes
|
||||||
|
- docs/specs/pbs/Prometeu VM Memory model.md — HIP-specific architecture
|
||||||
|
- docs/specs/pbs/Prometeu Scripting - Prometeu Bytecode Script (PBS).md — HIP world, borrow/mutate/peek, RC
|
||||||
|
- files/Borrow Mutate - Compiler GC.md — discusses removing RC/HIP in favor of GC; keep as design context but will need text updates after reset
|
||||||
|
|
||||||
|
|
||||||
|
4) Deletion map (by module)
|
||||||
|
|
||||||
|
Will be removed outright (symbols or blocks)
|
||||||
|
- prometeu-bytecode
|
||||||
|
- opcode.rs: all Gate* variants and Alloc variant; TryFrom/encoding IDs and cycles for those
|
||||||
|
- opcode_spec.rs: corresponding spec arms (GATE_*, ALLOC)
|
||||||
|
- abi.rs: TRAP_INVALID_GATE, TRAP_DEAD_GATE, TRAP_TYPE constants
|
||||||
|
- prometeu-vm
|
||||||
|
- virtual_machine.rs: handlers for Alloc and all Gate* opcodes; GateEntry/GateId data structures; resolve_gate(); HIP-focused unit tests listed above
|
||||||
|
|
||||||
|
Will be edited (kept but changed)
|
||||||
|
- prometeu-bytecode
|
||||||
|
- value.rs: remove Value::Gate and update Display/eq code paths
|
||||||
|
- program_image.rs: remove/adjust Value::Gate mapping in constant pool materialization
|
||||||
|
- decoder.rs: no semantic change; ensure UnknownOpcode remains deterministic (already the case)
|
||||||
|
- prometeu-vm
|
||||||
|
- virtual_machine.rs: remove trap imports for legacy codes; update match to exclude removed opcodes; prune gate/heap fields
|
||||||
|
- scope_frame.rs: keep unless later ISA changes require scope model changes (not part of HIP removal)
|
||||||
|
- prometeu-hal
|
||||||
|
- host_return.rs: stop producing Value::Gate once Value enum loses Gate
|
||||||
|
|
||||||
|
Docs to remove or rewrite (architecture reset)
|
||||||
|
- docs/specs/pbs/Prometeu VM Memory model.md — replace HIP/RC model with GC stack+heap model
|
||||||
|
- docs/specs/pbs/Prometeu Scripting - Prometeu Bytecode Script (PBS).md — remove HIP world/RC sections; update storage semantics
|
||||||
|
- Any disasm examples or golden outputs referring to GATE_* or ALLOC — update after opcode removal
|
||||||
|
|
||||||
|
Tests/fixtures affected
|
||||||
|
- Unit tests in prometeu-vm referencing HIP traps or Gate behavior:
|
||||||
|
- test_hip_traps_oob, test_hip_traps_type, test_invalid_gate_traps, test_gate_ids_distinct_and_round_trip
|
||||||
|
- Golden disassemblies under test-cartridges/*/build/program.disasm.txt may include GATE_* lines — grep and update in follow-up PRs
|
||||||
|
|
||||||
|
|
||||||
|
5) Reviewer checklist for follow-up PRs
|
||||||
|
- Bytecode enum/spec cleaned: no Gate*/Alloc variants remain
|
||||||
|
- VM execution has no references to Gate/GateEntry/resolve_gate
|
||||||
|
- Value enum no longer has Gate; all Display/eq/serde paths fixed
|
||||||
|
- Trap ABI contains only GC-era traps (OOB, stack underflow, invalid func/local/syscall, div by zero, bad ret slots, etc.)
|
||||||
|
- Disassembler/printers do not print legacy names (GATE_*, ALLOC)
|
||||||
|
- Docs no longer mention HIP/RC; updated to GC model
|
||||||
|
- All tests green (`cargo test`) after deletions and necessary test updates
|
||||||
|
|
||||||
|
|
||||||
|
6) Notes
|
||||||
|
- This document inventories occurrences proactively, but exact refactors in the reset may slightly shift responsibilities (e.g., how storage allocation appears under GC). Use the grep guide to double-check any stragglers during code deletion PRs.
|
||||||
205
files/TODOs.md
Normal file
205
files/TODOs.md
Normal file
@ -0,0 +1,205 @@
|
|||||||
|
# PR-1.2 — Remove HIP/RC Trap Codes From ABI
|
||||||
|
|
||||||
|
### Briefing
|
||||||
|
|
||||||
|
The new architecture removes HIP/RC completely. Any ABI surface describing HIP traps or gate-related traps must be deleted.
|
||||||
|
|
||||||
|
### Target
|
||||||
|
|
||||||
|
* Delete HIP/RC trap codes from bytecode ABI.
|
||||||
|
* Replace with a minimal, architecture-aligned trap/error taxonomy.
|
||||||
|
|
||||||
|
### Work items
|
||||||
|
|
||||||
|
* Remove HIP trap constants/enums (e.g., anything like `TRAP_INVALID_GATE`, `TRAP_DEAD_GATE`, and related HIP trap identifiers).
|
||||||
|
* If there is a shared trap enum used by VM/tooling:
|
||||||
|
|
||||||
|
* Keep only traps that remain meaningful in the GC stack+heap model (e.g., OOB, illegal instruction, stack underflow), as specified.
|
||||||
|
* Rename/restructure as needed to reflect the reset.
|
||||||
|
* Update any match arms / formatting / disasm text that referenced HIP traps.
|
||||||
|
* Update tests and fixtures accordingly.
|
||||||
|
|
||||||
|
### Acceptance checklist
|
||||||
|
|
||||||
|
* [ ] No HIP/gate trap identifiers remain in the codebase.
|
||||||
|
* [ ] Bytecode crates compile.
|
||||||
|
* [ ] Disassembler / printers compile and produce readable output for remaining traps.
|
||||||
|
* [ ] `cargo test` passes.
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
|
||||||
|
* Update/adjust any trap-related unit tests.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# PR-1.3 — Remove RC/HIP Opcodes From `opcode` and Decode/Encode Paths
|
||||||
|
|
||||||
|
### Briefing
|
||||||
|
|
||||||
|
Legacy opcodes must be removed entirely. Decoder/encoder must not recognize them, and there must be no compatibility decoding.
|
||||||
|
|
||||||
|
### Target
|
||||||
|
|
||||||
|
* Remove all RC/HIP opcodes and their textual/structural representation.
|
||||||
|
* Ensure decoding fails deterministically for unknown opcodes.
|
||||||
|
|
||||||
|
### Work items
|
||||||
|
|
||||||
|
* Delete RC/HIP-related opcode variants from `prometeu-bytecode` opcode definitions.
|
||||||
|
* Remove any encode/decode logic for those opcodes.
|
||||||
|
* Ensure decoder behavior for unknown opcodes is:
|
||||||
|
|
||||||
|
* Deterministic.
|
||||||
|
* Produces an actionable error message.
|
||||||
|
* Has no fallback to “legacy”.
|
||||||
|
* Update disasm formatting tables and opcode-name maps.
|
||||||
|
* Update tests/fixtures that referenced removed opcodes.
|
||||||
|
|
||||||
|
### Acceptance checklist
|
||||||
|
|
||||||
|
* [ ] Opcode enum(s) no longer include RC/HIP concepts.
|
||||||
|
* [ ] Encoder/decoder do not accept legacy opcodes.
|
||||||
|
* [ ] Disasm no longer prints legacy opcode names.
|
||||||
|
* [ ] `cargo test` passes.
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
|
||||||
|
* Add/adjust a unit test ensuring decoding an unknown/removed opcode produces the expected error.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# PR-1.4 — Define the Minimal Core ISA Surface (Bytecode-Only)
|
||||||
|
|
||||||
|
### Briefing
|
||||||
|
|
||||||
|
After deleting legacy opcodes, we must explicitly define the **minimal ISA** that remains. This PR establishes the canonical core ISA module boundary and documentation.
|
||||||
|
|
||||||
|
### Target
|
||||||
|
|
||||||
|
* Introduce a “core ISA” definition that is small and stable.
|
||||||
|
* Provide clear docs for stack effects and operand encoding at a bytecode level.
|
||||||
|
|
||||||
|
### Work items
|
||||||
|
|
||||||
|
* Create/reshape modules so the “core ISA” is clearly isolated (e.g., `isa/core` or similar).
|
||||||
|
* Add module docs describing:
|
||||||
|
|
||||||
|
* Instruction encoding rules.
|
||||||
|
* Stack-based evaluation model (bytecode-level).
|
||||||
|
* Which instructions exist at this stage (no closures/coroutines yet unless already in the spec subset).
|
||||||
|
* Add a `docs/bytecode/ISA_CORE.md` (or equivalent) that is short but precise.
|
||||||
|
* Ensure the ISA definition is used by:
|
||||||
|
|
||||||
|
* Encoder/decoder.
|
||||||
|
* Disasm.
|
||||||
|
* Verifier (later).
|
||||||
|
|
||||||
|
### Acceptance checklist
|
||||||
|
|
||||||
|
* [ ] Minimal ISA is explicitly defined and documented.
|
||||||
|
* [ ] No legacy instructions remain.
|
||||||
|
* [ ] `cargo test` passes.
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
|
||||||
|
* Existing tests only.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# PR-1.5 — Bytecode Module Pruning (Delete Unused/Experimental Modules)
|
||||||
|
|
||||||
|
### Briefing
|
||||||
|
|
||||||
|
The bytecode crate should be minimal. Anything experimental, unused, or legacy should be removed to reduce mental load.
|
||||||
|
|
||||||
|
### Target
|
||||||
|
|
||||||
|
* Delete unused bytecode modules.
|
||||||
|
* Keep only essential components for: encoding/decoding, layout, disasm, and data structures required by spec.
|
||||||
|
|
||||||
|
### Work items
|
||||||
|
|
||||||
|
* Remove unused files/modules identified in PR-1.1 map.
|
||||||
|
* Update `mod.rs` trees and public exports.
|
||||||
|
* Ensure no downstream crate relies on removed exports; if they do, fix the downstream usage **by deleting legacy use**, not by keeping legacy APIs.
|
||||||
|
|
||||||
|
### Acceptance checklist
|
||||||
|
|
||||||
|
* [ ] Unused modules are deleted and no longer referenced.
|
||||||
|
* [ ] Public API surface is smaller and cleaner.
|
||||||
|
* [ ] `cargo test` passes.
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
|
||||||
|
* Existing tests only.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# PR-1.6 — Canonical Function Boundaries & `FRAME_SYNC` Placement (Bytecode Layout)
|
||||||
|
|
||||||
|
### Briefing
|
||||||
|
|
||||||
|
GC and coroutine scheduling rely on deterministic safepoints. The bytecode layout must define canonical function boundaries and `FRAME_SYNC` semantics at the bytecode layer.
|
||||||
|
|
||||||
|
### Target
|
||||||
|
|
||||||
|
* Enforce canonical function ranges and end labels.
|
||||||
|
* Ensure `FRAME_SYNC` placement rules are representable and checkable.
|
||||||
|
|
||||||
|
### Work items
|
||||||
|
|
||||||
|
* Review current layout utilities and make them canonical for:
|
||||||
|
|
||||||
|
* Computing function `code_len`.
|
||||||
|
* Determining valid jump targets (instruction boundaries).
|
||||||
|
* Determining function end boundary.
|
||||||
|
* Document `FRAME_SYNC` at the bytecode level:
|
||||||
|
|
||||||
|
* What it signals.
|
||||||
|
* Where it is required (as per updated specs).
|
||||||
|
* Update disasm to clearly display `FRAME_SYNC`.
|
||||||
|
|
||||||
|
### Acceptance checklist
|
||||||
|
|
||||||
|
* [ ] Function boundaries are computed via a single canonical routine.
|
||||||
|
* [ ] `FRAME_SYNC` is clearly represented and documented.
|
||||||
|
* [ ] Existing verifier/layout tests (if any) are updated.
|
||||||
|
* [ ] `cargo test` passes.
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
|
||||||
|
* Add or update unit tests for layout boundary correctness (e.g., end-exclusive semantics).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# PR-1.7 — Bytecode Roundtrip Tests (Encode/Decode/Disasm Sanity)
|
||||||
|
|
||||||
|
### Briefing
|
||||||
|
|
||||||
|
Before touching VM behavior, we want confidence that the bytecode toolchain is coherent after the ISA reset.
|
||||||
|
|
||||||
|
### Target
|
||||||
|
|
||||||
|
* Add roundtrip tests that validate:
|
||||||
|
|
||||||
|
* Encode → decode preserves structure.
|
||||||
|
* Disasm prints stable, readable output.
|
||||||
|
|
||||||
|
### Work items
|
||||||
|
|
||||||
|
* Add a small set of “known-good” bytecode samples built using the new minimal ISA.
|
||||||
|
* Implement tests:
|
||||||
|
|
||||||
|
* Encode then decode equals original structure.
|
||||||
|
* Disasm output contains expected instruction names and operands.
|
||||||
|
* Keep samples intentionally tiny and deterministic.
|
||||||
|
|
||||||
|
### Acceptance checklist
|
||||||
|
|
||||||
|
* [ ] Roundtrip tests exist and pass.
|
||||||
|
* [ ] Samples do not depend on legacy semantics.
|
||||||
|
* [ ] `cargo test` passes.
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
|
||||||
|
* New unit tests for encode/decode/disasm roundtrip.
|
||||||
Loading…
x
Reference in New Issue
Block a user