prometeu-runtime/docs/bytecode/RESET_LEGACY_MAP.md

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.