# 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`.

---

## 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.