diff --git a/docs/bytecode/RESET_LEGACY_MAP.md b/docs/bytecode/RESET_LEGACY_MAP.md new file mode 100644 index 00000000..e14eedc3 --- /dev/null +++ b/docs/bytecode/RESET_LEGACY_MAP.md @@ -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 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. diff --git a/files/TODOs.md b/files/TODOs.md new file mode 100644 index 00000000..fa83c4e9 --- /dev/null +++ b/files/TODOs.md @@ -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.