This commit is contained in:
Nilton Constantino
2026-01-29 17:00:27 +00:00
parent c34166435f
commit fe00eda925
11 changed files with 140 additions and 125 deletions
@@ -0,0 +1,27 @@
# PBS ⇄ VM Alignment — Junie PRs (HIP Semantics Hardening)
> **Purpose:** fix semantic mismatches between the PBS frontend (Core IR) and the VM **before** any VM heap/gate implementation.
>
> These PRs are **surgical**, **mandatory**, and **non-creative**.
> Junie must follow them **exactly**.
> **Context:**
>
> * PBS frontend is implemented and produces Core IR.
> * Bytecode stability is a hard requirement.
> * VM currently has stack + const pool; heap exists but is unused.
> * HIP semantics (gates/storage) are currently **incorrectly lowered**.
> * `ir_vm` is feature-frozen at the moment. we are going to validate only `ir_core`
> * Lowering is the only place `ir_core` and `ir_vm` touch each other.
> - VM IR is never imported from Core IR.
> - Core IR never imports VM IR.
---
## Global Rules (Read Before Any PR)
1. **No new features.** Only semantic correction.
2. **No new VM opcodes yet.** VM changes come later.
3. **No fallback values** (e.g. `FunctionId(0)`). Fail with diagnostics.
4. **Every PR must include tests** (golden or unit).
5. **Core IR is the source of semantic truth.**
+142
View File
@@ -0,0 +1,142 @@
# PR-21 — Distinguish `peek`, `borrow`, and `mutate` in Core IR
### Goal
Restore the semantic distinction mandated by PBS.
### Required Semantics
| Operation | Effect |
| --------- | ------------------------------- |
| `peek` | Copy storage → stack value |
| `borrow` | Temporary read-only view |
| `mutate` | Temporary mutable view + commit |
### Required Changes
* Lower PBS `peek` → `BeginPeek` / `EndPeek`
* Lower PBS `borrow` → `BeginBorrow` / `EndBorrow`
* Lower PBS `mutate` → `BeginMutate` / `EndMutate`
These **must not** share the same lowering path.
### Tests
* PBS snippet with all three operations
* Assert distinct Core IR instruction sequences
---
# PR-22 — Make Allocation Shape Explicit in Core IR
### Goal
Stop implicit / guessed heap layouts.
### Required Changes
* Replace any shape-less `Alloc` with:
```rust
Alloc { ty: TypeId, slots: u32 }
```
Rules:
* `TypeId` comes from frontend type checking
* `slots` is derived deterministically (struct fields / array size)
### Tests
* Allocating storage struct emits correct `slots`
* Allocating array emits correct `slots`
---
# PR-23 — Eliminate Invalid Call Fallbacks
### Goal
Prevent invalid bytecode generation.
### Required Changes
* Remove **all** fallbacks to `FunctionId(0)` or equivalent
* On unresolved symbols during lowering:
* Emit canonical diagnostic (`E_RESOLVE_UNDEFINED` or `E_LOWER_UNSUPPORTED`)
* Abort lowering
### Tests
* PBS program calling missing function → compile error
* No Core IR or VM IR emitted
---
# PR-24 — Validate Contract Calls in Frontend (Arity + Types)
### Goal
Move contract validation to compile time.
### Required Changes
* During PBS type checking:
* Validate argument count against contract signature
* Validate argument types
* Lower only validated calls to `HostCall`
### Tests
* Wrong arity → `E_TYPE_MISMATCH`
* Correct call lowers to Core IR `HostCall`
---
# PR-25 — Core IR Invariants Test Suite
### Goal
Lock in correct semantics before touching the VM.
### Required Invariants
* Every `Begin*` has a matching `End*`
* Gate passed to `Begin*` is available at `End*`
* No storage writes without `BeginMutate`
* No silent fallbacks
### Tests
* Property-style tests or golden IR assertions
---
## STOP POINT
After PR-25:
* Core IR correctly represents PBS HIP semantics
* Lowering is deterministic and safe
* VM is still unchanged
**Only after this point may VM PRs begin.**
Any VM work before this is a hard rejection.
---
## Instruction to Junie
If any rule in this document is unclear:
* Stop
* Add a failing test
* Document the ambiguity
Do not invent behavior.
This document is binding.
@@ -0,0 +1,341 @@
# Prometeu Base Script (PBS)
> **A didactic scripting language for game development with explicit cost, explicit memory, and predictable runtime.**
---
## 0. What PBS Is (and What It Is Not)
PBS (Prometeu Base Script) is a **small, explicit scripting language designed for game engines and real‑time runtimes**.
Its core goals are:
* **Didactic clarity** — the language teaches how memory, data, and APIs really work.
* **Game‑friendly execution** — predictable runtime, no hidden allocation, no tracing GC.
* **Explicit cost model** — you always know *when* you allocate, *where* data lives, and *who* can mutate it.
PBS is **not**:
* a general‑purpose application language
* a productivity scripting language like Python or Lua
* a language that hides runtime cost
PBS is intentionally opinionated. It is built for developers who want **control, predictability, and understanding**, especially in **game and engine contexts**.
---
## 1. The Core Philosophy
PBS is built around one rule:
> **If you do not allocate, you are safe. If you allocate, you are responsible.**
From this rule, everything else follows.
### 1.1 Two Worlds
PBS has **two explicit memory worlds**:
| World | Purpose | Properties |
| ----- | -------------- | ---------------------------------------------- |
| SAFE | Stack / values | No aliasing, no leaks, no shared mutation |
| HIP | Storage / heap | Explicit aliasing, shared mutation, refcounted |
You never cross between these worlds implicitly.
---
## 2. First Contact: SAFE‑Only PBS
A PBS program that never allocates lives entirely in the SAFE world.
SAFE code:
* uses value semantics
* copies data on assignment (conceptually)
* cannot leak memory
* cannot accidentally share mutable state
This makes SAFE PBS ideal for:
* gameplay logic
* math and simulation
* AI logic
* scripting without fear
Example:
```pbs
let a = Vector(1, 2);
let b = a; // conceptual copy
b.scale(2);
// a is unchanged
```
No pointers. No references. No surprises.
---
## 3. Values, Not Objects
PBS does not have objects with identity by default.
### 3.1 Value Types
All basic types are **values**:
* numbers
* bool
* string (immutable)
* tuples
* user‑defined `struct`
A value:
* has no identity
* has no lifetime beyond its scope
* is safe to copy
This matches how most gameplay data *should* behave.
---
## 4. Structs (Data First)
Structs are **pure data models**.
```pbs
declare struct Vector(x: float, y: float)
{
pub fn len(self: this): float { ... }
pub fn scale(self: mut this, s: float): void { ... }
}
```
Rules:
* fields are private
* mutation is explicit (`mut this`)
* no inheritance
* no identity
Structs are designed to be:
* cache‑friendly
* predictable
* easy to reason about
---
## 5. Mutability Is a Property of Bindings
In PBS, **types are never mutable**. Bindings are.
```pbs
let v = Vector.ZERO;
v.scale(); // ERROR
let w = mut Vector.ZERO;
w.scale(); // OK
```
This single rule eliminates entire classes of bugs.
---
## 6. When You Need Power: Allocation (HIP World)
Allocation is **explicit**.
```pbs
let enemies = alloc list<Enemy>();
```
Once you allocate:
* data lives in Storage (heap)
* access happens through **gates** (handles)
* aliasing is real and visible
This is intentional and explicit.
---
## 7. Gates (Handles, Not Pointers)
A gate is a small value that refers to heap storage.
Properties:
* cheap to copy
* may alias shared data
* managed by reference counting
### 7.1 Strong vs Weak Gates
* **Strong gate** — keeps data alive
* **Weak gate** — observes without ownership
```pbs
let a = alloc Node;
let w: weak<Node> = a as weak;
let maybeA = w as strong;
```
This model mirrors real engine constraints without hiding them.
---
## 8. Controlled Access to Storage
Heap data is never accessed directly.
You must choose *how*:
* `peek` — copy to SAFE
* `borrow` — temporary read‑only access
* `mutate` — temporary mutable access
```pbs
mutate enemies as e
{
e.push(newEnemy);
}
```
This keeps mutation visible and scoped.
---
## 9. Errors Are Values
PBS has no exceptions.
### 9.1 `optional<T>`
Used when absence is normal.
```pbs
let x = maybeValue else 0;
```
### 9.2 `result<T, E>`
Used when failure matters.
```pbs
let v = loadTexture(path)?;
```
Error propagation is explicit and typed.
---
## 10. Control Flow Without Surprises
PBS favors explicit flow:
* `if` — control only
* `when` — expression
* `for` — bounded loops only
```pbs
for i in [0b..count] {
update(i);
}
```
No unbounded iteration by accident.
---
## 11. Services: Explicit API Boundaries
A `service` is how behavior crosses module boundaries.
```pbs
pub service Audio
{
fn play(sound: Sound): void;
}
```
Services are:
* explicit
* statically checked
* singleton‑like
They map naturally to engine subsystems.
---
## 12. Contracts: Static Guarantees
Contracts define **what exists**, not how.
```pbs
pub declare contract Gfx host
{
fn drawText(x: int, y: int, msg: string): void;
}
```
Contracts:
* have no runtime cost
* are validated at compile time
* define engine ↔ script boundaries
---
## 13. Modules (Simple and Predictable)
* one directory = one module
* only `pub` symbols cross modules
* no side effects on import
This keeps build and runtime deterministic.
---
## 14. Why PBS Works for Games
PBS is designed around real engine needs:
* frame‑based execution
* explicit allocation
* deterministic cleanup
* predictable performance
It teaches developers **why engines are written the way they are**, instead of hiding reality.
---
## 15. Who PBS Is For
PBS is for:
* game developers who want control
* engine developers
* students learning systems concepts
* educators teaching memory and runtime models
PBS is *not* for:
* rapid prototyping without constraints
* general app scripting
* hiding complexity
---
## 16. Design Promise
PBS makes one promise:
> **Nothing happens behind your back.**
If you understand PBS, you understand your runtime.
That is the product.