add PBS docs

This commit is contained in:
2026-03-24 13:40:22 +00:00
parent 62e68bf7ff
commit c795eeb3dc
24 changed files with 6386 additions and 649 deletions
+359
View File
@@ -0,0 +1,359 @@
# PBS v0 Canonical Addenda
> **Purpose:** eliminate ambiguity for Junie and for golden tests.
>
> This document is **normative** for PBS Frontend v0 and complements:
>
> * **PBS Frontend Spec v0 — Implementer Edition**
> * **Junie PR Plan**
>
> These addenda define:
>
> 1. operator precedence & associativity
> 2. canonical AST JSON shape (v0)
> 3. canonical diagnostic codes (v0)
---
## 1) Operator Precedence and Associativity (v0)
### 1.1 Guiding rule
PBS v0 prioritizes **minimal ambiguity** and **easy parsing**.
* Most operators are **left-associative**.
* Assignment is **not** an expression in v0 (no `=` operator expressions).
* Member access and indexing are not part of v0 surface syntax unless already defined elsewhere.
### 1.2 Precedence table
From **highest** to **lowest**:
1. **Primary**
* literals (`10`, `3.14`, `"text"`, `none`, `some(x)`, `ok(x)`, `err(e)`)
* identifiers (`foo`)
* parenthesized expression (`(expr)`)
* block expression (`{ ... }`) (when allowed as `Expr`)
2. **Call** (left-associative)
* `callee(arg1, arg2, ...)`
3. **Unary prefix** (right-associative)
* `-expr`
* `!expr`
* `as` casts are **not unary**; see level 6.
4. **Multiplicative** (left-associative)
* `*`, `/`, `%`
5. **Additive** (left-associative)
* `+`, `-`
6. **Cast** (left-associative)
* `expr as Type`
7. **Comparison** (non-associative)
* `<`, `<=`, `>`, `>=`
8. **Equality** (non-associative)
* `==`, `!=`
9. **Logical AND** (left-associative)
* `&&`
10. **Logical OR** (left-associative)
* `||`
11. **Control expressions** (special)
* `if ... { ... } else { ... }` (expression form only if your v0 allows it; otherwise statement)
* `when { ... }` (expression)
### 1.3 Non-associative rule
Comparison and equality are **non-associative**:
* `a < b < c` is an error
* `a == b == c` is an error
Diagnostic: `E_PARSE_NON_ASSOC`.
### 1.4 Notes on `when`
`when` binds weaker than all binary operators.
Example:
```pbs
let x = a + b when { ... };
```
Parses as:
```
let x = (a + b) when { ... };
```
---
## 2) Canonical AST JSON (v0)
### 2.1 Canonicalization goals
Canonical AST JSON is used for:
* golden tests
* frontend determinism validation
* diff-friendly debugging
Rules:
* JSON keys are **stable** and **ordered** (when writing JSON)
* All nodes include `kind` and `span`
* Spans are byte offsets into the file content
### 2.2 Span encoding
```json
{"file":"main.pbs","start":12,"end":18}
```
Where:
* `start` is inclusive
* `end` is exclusive
### 2.3 Root
```json
{
"kind": "File",
"span": {"file":"...","start":0,"end":123},
"imports": [ ... ],
"decls": [ ... ]
}
```
### 2.4 Import node
```json
{
"kind": "Import",
"span": {"file":"...","start":0,"end":20},
"spec": {"kind":"ImportSpec","path":["Foo","Bar"]},
"from": "./lib.pbs"
}
```
`ImportSpec.path` is an array of identifiers.
### 2.5 Declarations
#### 2.5.1 Service
```json
{
"kind": "ServiceDecl",
"span": {"file":"...","start":0,"end":50},
"vis": "pub",
"name": "Audio",
"extends": null,
"members": [ ... ]
}
```
A service member (method signature only in v0):
```json
{
"kind": "ServiceFnSig",
"span": {"file":"...","start":0,"end":10},
"name": "play",
"params": [ {"name":"sound","ty": {"kind":"TypeName","name":"Sound"}} ],
"ret": {"kind":"TypeName","name":"void"}
}
```
#### 2.5.2 Function
```json
{
"kind": "FnDecl",
"span": {"file":"...","start":0,"end":80},
"name": "main",
"params": [],
"ret": null,
"else": null,
"body": {"kind":"Block", ... }
}
```
#### 2.5.3 TypeDecl (struct/contract/error)
```json
{
"kind": "TypeDecl",
"span": {"file":"...","start":0,"end":100},
"vis": "pub",
"typeKind": "struct",
"name": "Vector",
"body": {"kind":"TypeBody","members":[ ... ]}
}
```
### 2.6 Blocks and statements
Block:
```json
{
"kind": "Block",
"span": {"file":"...","start":0,"end":20},
"stmts": [ ... ],
"tail": null
}
```
* `stmts` are statements.
* `tail` is an optional final expression (only if your parser supports expression blocks).
Statement kinds (v0 minimum):
* `LetStmt`
* `ExprStmt`
* `ReturnStmt`
Let:
```json
{
"kind": "LetStmt",
"span": {"file":"...","start":0,"end":20},
"name": "x",
"isMut": false,
"ty": null,
"init": {"kind":"IntLit", "value": 10, "span": ...}
}
```
Return:
```json
{
"kind": "ReturnStmt",
"span": {"file":"...","start":0,"end":10},
"expr": null
}
```
### 2.7 Expressions
All expressions include `kind` and `span`.
Minimal v0 expression node kinds:
* `IntLit` `{ value: i64 }`
* `FloatLit` `{ value: f64 }`
* `BoundedLit` `{ value: u32 }`
* `StringLit` `{ value: string }`
* `Ident` `{ name: string }`
* `Call` `{ callee: Expr, args: Expr[] }`
* `Unary` `{ op: "-"|"!", expr: Expr }`
* `Binary` `{ op: string, left: Expr, right: Expr }`
* `Cast` `{ expr: Expr, ty: TypeRef }`
* `IfExpr` `{ cond: Expr, then: Block, els: Block }` (if expression is supported)
* `WhenExpr` `{ arms: WhenArm[] }`
Type references:
```json
{"kind":"TypeName","name":"int"}
```
Generics:
```json
{"kind":"TypeApp","base":"optional","args":[{"kind":"TypeName","name":"int"}]}
```
### 2.8 Canonical JSON ordering
When writing AST JSON, always order fields as:
1. `kind`
2. `span`
3. semantic fields (stable order)
This makes diffs deterministic.
---
## 3) Diagnostic Codes (v0)
### 3.1 Diagnostic format
All diagnostics must be serializable to canonical JSON:
```json
{
"severity": "error",
"code": "E_PARSE_UNEXPECTED_TOKEN",
"message": "Unexpected token '}'",
"span": {"file":"main.pbs","start":12,"end":13}
}
```
Severity is one of: `error`, `warning`.
### 3.2 Parse/Lex errors (E_PARSE_*)
* `E_LEX_INVALID_CHAR` — invalid character
* `E_LEX_UNTERMINATED_STRING` — string literal not closed
* `E_PARSE_UNEXPECTED_TOKEN` — token not expected in current context
* `E_PARSE_EXPECTED_TOKEN` — missing required token
* `E_PARSE_NON_ASSOC` — chained comparison/equality (non-associative)
### 3.3 Symbol/Resolve errors (E_RESOLVE_*)
* `E_RESOLVE_UNDEFINED` — undefined identifier
* `E_RESOLVE_DUPLICATE_SYMBOL` — duplicate symbol in same namespace
* `E_RESOLVE_NAMESPACE_COLLISION` — name exists in both type and value namespaces
* `E_RESOLVE_VISIBILITY` — symbol not visible from this scope/module
* `E_RESOLVE_INVALID_IMPORT` — import spec/path invalid
### 3.4 Type errors (E_TYPE_*)
* `E_TYPE_MISMATCH` — type mismatch
* `E_TYPE_UNKNOWN_TYPE` — unknown type name
* `E_TYPE_MUTABILITY` — mutability violation
* `E_TYPE_RETURN_PATH` — not all paths return a value
* `E_TYPE_INVALID_CAST` — invalid cast
### 3.5 Lowering errors (E_LOWER_*)
* `E_LOWER_UNSUPPORTED` — feature not supported in v0 lowering
### 3.6 Warnings (W_*)
Warnings are allowed in v0 but should be used sparingly.
* `W_UNUSED_LET` — unused local binding
* `W_SHADOWING` — local shadows another binding
---
## Implementation Notes (Non-normative)
* Keep these addenda in `spec/` in the repo.
* Use them to drive golden tests for AST and diagnostics.
* If a future change alters canonical AST, bump a version and regenerate goldens deliberately.
+357
View File
@@ -0,0 +1,357 @@
# 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.
@@ -0,0 +1,446 @@
# Prometeu Base Script (PBS)
## Frontend Spec v0 — Implementer Edition
> **Normative specification for building a PBS frontend (lexer, parser, AST, resolver, typechecker) targeting the Prometeu Fantasy Console runtime.**
>
> This document is **not** a user guide.
> It exists to make PBS *implementable*, *deterministic*, and *testable*.
---
## 0. Scope and Non‑Goals
### 0.1 Scope
This specification defines:
* lexical structure (tokens)
* grammar and parsing rules
* canonical AST shapes
* frontend phases and their responsibilities
* name resolution and visibility rules
* type system rules
* desugaring and lowering rules
* diagnostic categories (errors vs warnings)
* required guarantees for runtime integration
The goal is that **two independent frontends** built from this spec:
* accept the same programs
* reject the same programs
* produce equivalent ASTs
* emit equivalent diagnostics
### 0.2 Non‑Goals
This spec does **not** define:
* runtime performance characteristics
* bytecode layout
* JIT or interpreter design
* editor tooling or IDE features
Those are explicitly out of scope.
---
## 1. Frontend Pipeline Overview
A PBS frontend **must** be structured as the following pipeline:
```
Source Text
↓
Lexer
↓
Parser
↓
Raw AST
↓
Symbol Collection
↓
Resolver
↓
Typed AST
↓
Desugaring / Lowering
↓
Runtime‑ready IR / AST
```
Each stage has **strict responsibilities**.
No stage may perform work assigned to a later stage.
---
## 2. Lexical Structure
### 2.1 Tokens
A PBS lexer must recognize at minimum the following token classes:
* identifiers
* keywords
* numeric literals
* string literals
* punctuation
* operators
* comments
Whitespace is insignificant except as a separator.
---
### 2.2 Keywords (Reserved)
The following keywords are **reserved** and may not be used as identifiers:
```
import
pub
mod
service
fn
let
mut
declare
struct
contract
host
error
optional
result
some
none
ok
err
if
else
when
for
in
return
handle
borrow
mutate
peek
take
alloc
weak
as
```
---
### 2.3 Literals
#### Numeric Literals
* `int` — decimal digits
* `float` — decimal with `.`
* `bounded` — decimal digits suffixed with `b`
Examples:
```pbs
10
42
3.14
0b
255b
```
#### String Literals
* delimited by `"`
* UTF‑8 encoded
* immutable
---
### 2.4 Comments
* line comment: `// until end of line`
* block comments are **not supported** in v0
---
## 3. Grammar (EBNF‑style)
> This grammar is **normative** but simplified for readability.
> Implementers may refactor internally as long as semantics are preserved.
### 3.1 File Structure
```
File ::= Import* TopLevelDecl*
Import ::= 'import' ImportSpec 'from' StringLiteral
TopLevelDecl::= TypeDecl | ServiceDecl | FnDecl
```
---
### 3.2 Type Declarations
```
TypeDecl ::= Visibility? 'declare' TypeKind Identifier TypeBody
TypeKind ::= 'struct' | 'contract' | 'error'
```
---
### 3.3 Services
```
ServiceDecl ::= Visibility 'service' Identifier (':' Identifier)? Block
```
Visibility is mandatory for services.
---
### 3.4 Functions
```
FnDecl ::= 'fn' Identifier ParamList ReturnType? ElseFallback? Block
```
Top‑level `fn` are always file‑private.
---
### 3.5 Expressions (Partial)
```
Expr ::= Literal
| Identifier
| CallExpr
| Block
| IfExpr
| WhenExpr
| ForExpr
| ReturnExpr
```
Expression grammar is intentionally restricted in v0.
---
## 4. Canonical AST
The frontend **must** produce a canonical AST.
### 4.1 AST Invariants
* AST nodes are immutable after creation
* Parent pointers are optional
* Source spans must be preserved for diagnostics
---
### 4.2 Core Node Kinds
Minimal required node kinds:
* `FileNode`
* `ImportNode`
* `ServiceNode`
* `FunctionNode`
* `StructDeclNode`
* `ContractDeclNode`
* `BlockNode`
* `LetNode`
* `CallNode`
* `IfNode`
* `WhenNode`
* `ForNode`
* `ReturnNode`
Implementers may add internal nodes but must normalize before later phases.
---
## 5. Symbol Collection Phase
### 5.1 Purpose
Symbol Collection builds **module‑level symbol tables** without resolving bodies.
Collected symbols:
* `pub` and `mod` type declarations
* `pub` and `mod` services
Excluded:
* function bodies
* expressions
* local bindings
---
### 5.2 Namespaces
PBS has **two namespaces**:
* Type namespace
* Value namespace
Rules:
* A name may not exist in both namespaces
* Violations are compile‑time errors
---
## 6. Resolver Phase
### 6.1 Responsibilities
Resolver must:
* resolve all identifiers
* enforce visibility rules
* bind references to symbols
Resolution order (per namespace):
1. local bindings
2. file‑private declarations
3. module symbols
4. imported symbols
---
### 6.2 Visibility Rules (Normative)
* file‑private: visible only in the same file
* `mod`: visible within the module
* `pub`: visible across modules via import
Violations are errors.
---
## 7. Type Checking
### 7.1 Type Categories
Frontend must support:
* primitive types
* struct value types
* `optional<T>`
* `result<T, E>`
* gate‑backed types (opaque at frontend level)
---
### 7.2 Mutability Rules
* mutability belongs to bindings, not types
* `mut` is part of binding metadata
* mutability violations are compile‑time errors
---
### 7.3 Function Checking
Rules:
* all paths must return a value unless `else` fallback exists
* `optional<T>` may implicitly return `none`
* `result<T,E>` must return explicitly
---
## 8. Desugaring and Lowering
### 8.1 Purpose
Lowering transforms surface syntax into a minimal core language.
Examples:
* `take x.push(v)` → `mutate x as t { t.push(v) }`
* `when` → conditional expression node
* implicit `return none` for `optional<T>`
Lowered AST must contain **no syntactic sugar**.
---
## 9. Diagnostics Model
Diagnostics are first‑class frontend outputs.
### 9.1 Categories
* Error — compilation must fail
* Warning — compilation may continue
---
### 9.2 Required Errors
Examples:
* unresolved identifier
* visibility violation
* type mismatch
* mutability violation
* invalid gate conversion
---
## 10. Runtime Interface Assumptions
Frontend assumes:
* host‑bound contracts map to runtime syscalls
* allocation primitives exist (`alloc`)
* reference counting is handled by runtime
Frontend must **not** assume GC or heap layout.
---
## 11. Determinism Guarantees
A valid PBS frontend **must guarantee**:
* deterministic parsing
* deterministic name resolution
* deterministic type checking
* deterministic diagnostics
No frontend stage may depend on execution order or host state.
---
## 12. Conformance Criteria
A frontend is PBS‑v0‑conformant if:
* it implements all rules in this document
* it produces canonical ASTs
* it rejects all invalid programs defined herein
This document is the **source of truth** for PBS v0 frontend behavior.
---
## 13. Future Evolution (Non‑Normative)
Future versions may add:
* pattern matching
* richer type inference
* macros
No v0 frontend is required to support these.
---
## End of Spec
@@ -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.
File diff suppressed because it is too large Load Diff