prometeu-runtime/docs/specs/pbs/PRs para Junie.md

PBS Compiler — Junie PR Plan

Purpose: this document defines a sequence of small, focused Pull Requests to be implemented by Junie, one at a time.

Audience: compiler implementer (AI or human).

Scope: PBS-first compiler architecture. TS and Lua frontends are assumed removed.

Hard rules:

• Each PR must compile and pass tests.
• Each PR must include tests.
• No speculative features.
• Follow the Prometeu Base Script (PBS) - Implementation Spec.
• VM IR is frozen: new opcodes are forbidden unless explicitly planned in a PR titled “VM Instruction Set Change” with a full rationale + golden bytecode tests.

---

Global Architectural Direction (Non-negotiable)

• PBS is the primary language.
• Frontend is implemented before runtime integration.
• Architecture uses two IR layers:
  • Core IR (PBS-semantic, typed, resolved)
  • VM IR (stack-based, backend-friendly)
• VM IR remains simple and stable.
• Lowering is explicit and testable.

---

PR-01 — ProjectConfig and Frontend Selection

Goal

Introduce a project-level configuration that selects the frontend and entry file explicitly.

Motivation

The compiler must not hardcode entry points or languages. PBS will be the first frontend, others may return later.

Scope

• Add ProjectConfig (serde-deserializable) loaded from prometeu.json

• Fields (v0):

  • script_fe: "pbs"
  • entry: "main.pbs"

• Refactor compiler entry point to:

  • load config
  • select frontend by script_fe
  • resolve entry path relative to project root

Files Likely Touched

• compiler/mod.rs
• compiler/driver.rs
• common/config.rs (new)

Tests (mandatory)

• unit test: load valid prometeu.json
• unit test: invalid frontend → diagnostic
• integration test: project root + entry resolution

Notes to Junie

Do not add PBS parsing yet. This PR is infrastructure only.

---

PR-02 — Core IR Skeleton (PBS-first)

Goal

Introduce a Core IR layer independent from the VM IR.

Motivation

PBS semantics must be represented before lowering to VM instructions.

Scope

• Add new module: ir_core

• Define minimal structures:

  • Program
  • Module
  • Function
  • Block
  • Instr
  • Terminator

• IDs only (no string-based calls):

  • FunctionId
  • ConstId
  • TypeId

Constraints

• Core IR must NOT reference VM opcodes
• No lowering yet

Tests

• construct Core IR manually in tests
• snapshot test (JSON) for deterministic shape

---

PR-03 — Constant Pool and IDs

Goal

Introduce a stable constant pool shared by Core IR and VM IR.

Scope

• Add ConstPool:

  • strings
  • numbers

• Replace inline literals in VM IR with ConstId

• Update existing VM IR to accept PushConst(ConstId)

Tests

• const pool deduplication
• deterministic ConstId assignment
• IR snapshot stability

---

PR-04 — VM IR Cleanup (Stabilization)

Goal

Stabilize VM IR as a lowering target, not a language IR.

Scope

• Replace string-based calls with FunctionId
• Ensure locals are accessed via slots
• Remove or internalize PushScope / PopScope

Tests

• golden VM IR tests
• lowering smoke test (Core IR → VM IR)

---

PR-05 — Core IR → VM IR Lowering Pass

Goal

Implement the lowering pass from Core IR to VM IR.

Scope

• New module: lowering/core_to_vm.rs

• Lowering rules:

  • Core blocks → labels
  • Core calls → VM calls
  • Host calls preserved

• No PBS frontend yet

Tests

• lowering correctness
• instruction ordering
• label resolution

---

PR-06 — PBS Frontend: Lexer

Goal

Implement PBS lexer according to the spec.

Scope

• Token kinds
• Keyword table
• Span tracking

Tests

• tokenization tests
• keyword vs identifier tests
• bounded literals

---

PR-07 — PBS Frontend: Parser (Raw AST)

Goal

Parse PBS source into a raw AST.

Scope

• Imports
• Top-level declarations
• Blocks
• Expressions (calls, literals, control flow)

Tests

• valid programs
• syntax error recovery

---

PR-08 — PBS Frontend: Symbol Collection and Resolver

Goal

Resolve names, modules, and visibility.

Scope

• Type namespace vs value namespace
• Visibility rules
• Import resolution

Tests

• duplicate symbols
• invalid imports
• visibility errors

---

PR-09 — PBS Frontend: Type Checking

Goal

Validate PBS semantics.

Scope

• Primitive types
• Structs
• optional<T> and result<T, E>
• Mutability rules
• Return path validation

Tests

• type mismatch
• mutability violations
• implicit none behavior

---

PR-10 — PBS Frontend: Semantic Lowering to Core IR

Goal

Lower typed PBS AST into Core IR.

Scope

• ID-based calls
• ConstPool usage
• Control flow lowering
• SAFE vs HIP effects represented explicitly

Tests

• PBS → Core IR snapshots
• semantic correctness

---

PR-11 — Host-bound Contracts and Syscall Mapping

Goal

Connect PBS host-bound contracts to runtime syscalls (without executing them).

Scope

• Contract registry
• Mapping: contract.method → syscall id
• Core IR host call nodes

Tests

• invalid contract calls
• correct syscall mapping

---

PR-12 — Diagnostics Canonicalization

Goal

Standardize diagnostics output.

Scope

• Error codes (E_*, W_*)
• Stable messages
• Span accuracy

Tests

• golden diagnostics

---

PR-13 — Backend Integration (VM IR → Bytecode)

Goal

Reconnect the pipeline to the Prometeu runtime backend.

Scope

• VM IR → bytecode emission
• No PBS semantics here

Tests

• bytecode emission smoke test

---

PR-14 — End-to-End PBS Compile Test

Goal

Prove the full pipeline works.

Scope

• Sample PBS project
• Compile → bytecode
• Diagnostics only (no execution)

Tests

• golden bytecode snapshot

---

Final Note to Junie

Do not skip PRs. Do not merge multiple PRs together. If the spec is unclear, create a failing test and document the ambiguity.

This plan is the authoritative roadmap for PBS frontend implementation.