pr 20
This commit is contained in:
@@ -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.**
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user