add spec docs

This commit is contained in:
2026-03-24 13:42:16 +00:00
parent f3be4f7946
commit aa1e0860d2
17 changed files with 2412 additions and 0 deletions
@@ -0,0 +1,144 @@
# PBS - Compatibility and Evolution Policy v1 (Draft)
Status: Draft (Normative policy for language/runtime evolution)
Scope: Compatibility contract for PBS features across hardware/runtime updates
Language: English
## 1. Purpose
This document defines how PBS remains stable while the logical hardware evolves.
Goals:
- preserve existing cartridge behavior across updates,
- allow additive platform growth without silent regressions,
- keep evolution deterministic and verifier-friendly,
- define explicit upgrade/rejection rules for toolchains and firmware.
## 2. Authority and precedence
Normative precedence order:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
3. `PBS - Language Syntax Specification v0.md`
4. `PBS - Game Language Profile v1 (Draft).md`
5. `PBS - Game Profile Syntax Specification v1 (Draft).md`
6. This document
7. Legacy references (`docs/specs/pbs_old/*`)
If any rule here conflicts with higher authority, this document is invalid for that rule.
## 3. Core stability model
### 3.1 Frozen core contract
The following contracts MUST remain stable once released in a major line:
- frame synchronization semantics (`FRAME_SYNC` as deterministic safepoint),
- trap and verifier invariants,
- stack/call/return discipline for valid bytecode,
- deterministic scheduling and host-call contract rules.
Behavioral changes to frozen core contracts require a new major line.
### 3.2 Additive extension rule
New features SHOULD be additive by default.
Existing valid programs MUST keep their previous behavior unless they explicitly target a newer incompatible major.
## 4. Primitive and host API versioning
### 4.1 Canonical identity
Host-call primitives MUST be versioned by canonical identity:
`(module, name, version)`
An incompatible change MUST create a new `version`.
The old version MUST remain resolvable during its supported compatibility window.
### 4.2 No semantic retcon
Implementations MUST NOT silently change semantics of an existing canonical identity.
If semantics must change incompatibly, publish a new identity version and deprecate the old one by policy.
## 5. Cartridge target contract
Each cartridge/app manifest MUST declare, at minimum:
- target VM/runtime major (or compatible range),
- language profile and profile version,
- required canonical host-call identities and versions,
- required capabilities.
Loader behavior MUST be deterministic:
- load and run when all requirements resolve,
- reject with explicit diagnostic when requirements are missing or incompatible.
Implicit fallback to a different major/version is forbidden.
## 6. Evolution policy (major/minor)
### 6.1 Minor updates
Minor updates MUST be backward compatible.
Allowed examples:
- adding new host-call identities,
- adding optional metadata/diagnostics,
- adding syntax/features gated behind explicit profile selection.
### 6.2 Major updates
Major updates MAY introduce incompatible changes.
When this happens, maintainers MUST provide:
- explicit migration notes,
- compatibility window policy for prior majors,
- deterministic loader diagnostics for unsupported targets.
## 7. Compatibility layer policy
Runtime/firmware SHOULD provide compatibility shims for older identity versions for a defined window.
If shims are provided:
- shim behavior MUST be deterministic,
- shim scope and support horizon MUST be documented,
- shim removal MUST occur only in a new major line.
## 8. Toolchain requirements
Compiler/linker/tooling MUST:
- resolve host calls by canonical identity and declared version,
- fail deterministically on unresolved identities,
- emit target/profile metadata in output artifacts,
- avoid emitting instructions/features not supported by selected target contracts.
## 9. Conformance and replay guarantees
Each release MUST pass compatibility conformance suites that include:
- bytecode verifier invariants,
- host-call resolution checks by version,
- deterministic replay checks under fixed input/event traces.
For supported target contracts, the same cartridge plus the same input/event sequence MUST produce the same observable behavior.
## 10. Deprecation policy
Deprecation MUST be explicit and non-breaking during its support window.
Required stages:
1. Mark as deprecated (tooling warning + documentation).
2. Maintain compatibility through declared window.
3. Remove only in a subsequent major line.
## 11. Non-goals
- Defining subsystem-specific syscall tables.
- Defining game-stdlib API surfaces.
- Replacing runtime authority with PBS-layer policy.
@@ -0,0 +1,106 @@
# PBS - Game Language Profile v1 (Draft)
Status: Draft (Language/Product direction)
Scope: PBS game-first language contract for 2D workloads
Language: English
## 1. Purpose
This document defines the language-level direction for PBS as a game-first scripting language.
The profile targets:
- intuitive onboarding for beginners,
- predictable frame behavior for real-time 2D games,
- explicit performance/cost surfaces for advanced developers,
- strict compatibility with a closed VM and its bytecode/runtime authority.
This document is language-contract oriented. It does not define bytecode encoding details.
## 2. Authority and compatibility
Normative precedence order:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
3. `PBS - Language Syntax Specification v0.md`
4. This document (Game Profile direction and requirements)
5. Legacy references (`docs/specs/pbs_old/*`)
If any rule here conflicts with runtime or bytecode authority, this document is invalid for that rule.
## 3. Design constraints
- The VM is a closed execution target.
- Language features must lower to supported VM/bytecode behavior.
- Determinism and frame synchronization are non-negotiable.
- GC is the baseline memory strategy.
## 4. Ten normative rules
### Rule 1 - Frame-first semantics
PBS game-facing language features MUST preserve deterministic frame execution.
Language constructs MUST NOT imply hidden asynchronous callbacks or preemptive execution.
### Rule 2 - Closed-VM compatibility
PBS MUST only define features that can be represented by the closed VM contract.
Language design MUST NOT require custom allocators, hidden host threads, or runtime behaviors outside VM authority.
### Rule 3 - GC-first memory model
PBS MUST treat GC-managed heap semantics as the default and beginner path.
Any future lifetime tools (such as pools/arena-like workflows) MUST be additive at API/library level unless runtime authority changes.
### Rule 4 - Explicit cost surfaces
PBS SHOULD make high-cost operations visible to users through language diagnostics and tooling contracts.
At minimum, allocation pressure, frequent host calls, and hot-loop risk points SHOULD be reportable in deterministic diagnostics.
### Rule 5 - 2D game-native type surface
PBS SHOULD provide a first-class game-oriented type surface through core language + standard library alignment.
The profile MUST support fluent expression of common 2D tasks (positions, velocities, bounds, colors, sprite/tile identifiers, frame counters).
### Rule 6 - Service boundary as gameplay architecture
`service` MUST remain the primary executable boundary for gameplay systems.
Language guidance SHOULD promote service-oriented decomposition for input, simulation, rendering orchestration, audio, and UI flows.
### Rule 7 - Typed host contract boundary
Host interactions MUST remain typed and explicit at language level.
Language constructs for host-facing APIs MUST preserve capability checks and syscall determinism from runtime authority.
### Rule 8 - Frame-based event and timer model
Game-facing event/timer language patterns MUST be frame-based and deterministic.
Language evolution MUST NOT reintroduce interrupt-like user execution semantics.
### Rule 9 - Progressive complexity in one language
PBS MUST support both beginner and advanced developers without forking into separate languages.
The beginner path MUST keep defaults simple and safe; advanced control MUST be explicit and opt-in.
### Rule 10 - Fluency for game loops
PBS syntax and standard patterns SHOULD optimize for high-frequency game-loop code:
- concise state updates,
- clear system boundaries,
- predictable data flow across update/render stages,
- minimal boilerplate for frame-driven logic.
## 5. Non-goals for this draft
- Defining new bytecode opcodes.
- Replacing runtime GC with a new mandatory memory subsystem.
- Adding language-level async callbacks or non-deterministic host behavior.
## 6. Planned follow-up specs
1. Game Profile syntax additions (if needed), layered on top of v0 Core.
2. Game-oriented standard library contract (collections, timers, ECS-adjacent utilities).
3. Tooling diagnostics spec for frame-cost visibility.
4. Host API declaration surface aligned with capability and syscall metadata.
@@ -0,0 +1,186 @@
# PBS - Game Profile Syntax Specification v1 (Draft)
Status: Draft (Normative for Game Profile parser/lowering work)
Scope: Syntax delta over `PBS - Language Syntax Specification v0.md`
Language: English
## 1. Purpose
This document defines the parser-facing syntax additions for the PBS Game Profile.
Goals:
- keep beginner usage fluid for 2D game construction,
- preserve deterministic/frame-oriented execution,
- remain compatible with closed VM + bytecode/runtime authority,
- avoid introducing hidden runtime behavior in language syntax.
## 2. Authority and precedence
Normative precedence order:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
3. `PBS - Language Syntax Specification v0.md`
4. This document
5. Legacy references (`docs/specs/pbs_old/*`)
If a rule here conflicts with higher authority, the rule is invalid.
## 3. Profile activation
Game Profile syntax is enabled by toolchain profile selection (`game` profile).
Without this profile, v0 Core syntax rules remain in effect.
## 4. Lexical delta (keywords)
### 4.1 Newly active keywords in Game Profile
- `host`
- `while`
- `break`
- `continue`
### 4.2 Still reserved in this draft
- `alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`
- `spawn`, `yield`, `sleep`
- `handle`
This draft does not activate heap-specialized syntax or coroutine syntax.
## 5. Top-level grammar delta
Game Profile extends top-level declarations with host function declarations.
```ebnf
TopDecl ::= TypeDecl | ServiceDecl | FunctionDecl | HostFnDecl
HostFnDecl ::= 'host' 'fn' Identifier ParamList ReturnType? ';'
```
Rules:
- `host fn` declares a host-provided call surface only (no body).
- Calling `host fn` lowers to syscall-linked call sites.
- Host functions are callable entities, never first-class function values.
- Service-shaped facades over host functions belong to stdlib design, not to host syntax.
Examples:
```pbs
host fn input_state(): (int, int, int);
host fn gfx_present();
```
## 6. Statement grammar delta
Game Profile adds imperative loop/control and assignment statements.
```ebnf
Stmt ::= LetStmt
| AssignStmt
| ReturnStmt
| IfStmt
| ForStmt
| WhileStmt
| BreakStmt
| ContinueStmt
| ExprStmt
WhileStmt ::= 'while' Expr Block
BreakStmt ::= 'break' ';'
ContinueStmt ::= 'continue' ';'
AssignStmt ::= LValue AssignOp Expr ';'
AssignOp ::= '=' | '+=' | '-=' | '*=' | '/=' | '%='
LValue ::= Identifier LValueSuffix*
LValueSuffix ::= '.' Identifier | '[' Expr ']'
```
Rules:
- `break` and `continue` are valid only inside `for`/`while`.
- Assignment is a statement, not an expression.
- `LValue` cannot contain function calls.
- Compound assignments are semantic sugar over read/compute/write.
## 7. Expression grammar delta
Game Profile adds postfix member/index access chains for fluent gameplay code.
```ebnf
UnaryExpr ::= ('!' | '-') UnaryExpr | PostfixExpr
PostfixExpr ::= PrimaryExpr PostfixSuffix*
PostfixSuffix ::= CallSuffix | MemberSuffix | IndexSuffix
CallSuffix ::= '(' ArgList? ')'
MemberSuffix ::= '.' Identifier
IndexSuffix ::= '[' Expr ']'
```
This replaces the v0 Core `CallExpr` chain and enables expressions such as:
```pbs
gfx_present();
player.transform.position.x;
tiles[i].id;
```
## 8. Determinism and lowering constraints
Game Profile syntax additions MUST preserve:
- deterministic control flow,
- verifier-friendly stack effects,
- explicit host call boundaries.
Lowering requirements:
- `host` call sites map to resolved syscall identities.
- `while`/`break`/`continue` lower to structured jumps compatible with verifier rules.
- Member/index read-write operations must lower to deterministic, type-checked access paths.
## 9. Diagnostics requirements (parser + early semantic phase)
Implementations MUST produce deterministic diagnostics for:
- `break`/`continue` outside loops,
- invalid `LValue` targets,
- duplicate host signatures in the same scope,
- unresolved host declarations at link/resolve stage,
- use of still-reserved keywords as active syntax.
## 10. Minimal canonical examples
### 10.1 Frame loop style with while
```pbs
host fn gfx_present();
fn run(): int {
let running = true;
while running {
update_world();
render_world();
gfx_present();
}
return 0;
}
```
### 10.2 Assignment and member/index access
```pbs
fn integrate(p: Vec2, v: Vec2): Vec2 {
let out = p;
out.x += v.x;
out.y += v.y;
return out;
}
```
## 11. Non-goals of this syntax draft
- Defining pool/arena memory syntax.
- Enabling `alloc/borrow/mutate` in surface syntax.
- Defining coroutine syntax (`spawn/yield/sleep`) before bytecode/runtime profile activation.
@@ -0,0 +1,373 @@
# PBS - Language Syntax Specification v0
Status: Draft (Normative for FE rewrite)
Scope: PBS v0 Core syntax (lexer + parser contract)
Language: English only
## 1. Goals
This document defines the canonical PBS v0 Core syntax.
It is designed to:
- be deterministic to parse,
- be stable for tests and tooling,
- align with runtime authority,
- provide a clear baseline for frontend rewrite.
This document defines syntax only. Runtime behavior, bytecode encoding, scheduling, and GC internals are out of scope.
## 2. Authority and precedence
Normative precedence order:
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
3. This syntax specification
4. Legacy references (`docs/specs/pbs_old/*`)
If a syntax rule from legacy material conflicts with runtime or bytecode authority, that rule is invalid.
## 3. Source model
- Source encoding: UTF-8.
- Line terminators: `\n` and `\r\n` are both valid.
- Whitespace is insignificant except as separator.
- A source file is a declaration unit; top-level executable statements are forbidden.
## 4. Lexical specification
### 4.1 Tokens
The lexer must produce at least:
- identifiers,
- keywords,
- numeric literals,
- string literals,
- punctuation,
- operators,
- comments,
- EOF.
Each token must carry a source span (byte offsets).
### 4.2 Comments
- Line comment: `// ...` until line end.
- Block comments are not part of v0 Core.
### 4.3 Identifiers
Identifier:
- starts with `_` or alphabetic character,
- continues with `_`, alphabetic, or digit characters.
Keywords cannot be used as identifiers.
### 4.4 Keywords
Active keywords in `.pbs` files (v0 Core):
- `import`, `from`, `as`
- `service`, `fn`
- `declare`, `struct`, `contract`, `error`
- `let`
- `if`, `else`, `when`, `for`, `in`, `return`
- `true`, `false`
Barrel-only keywords:
- `pub`, `mod`
- `type`
Reserved (not active in `.pbs` v0 Core grammar, but reserved):
- `host`, `handle`
- `alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`
- `spawn`, `yield`, `sleep`
### 4.5 Literals
Numeric literals:
- `IntLit`: decimal integer (`0`, `42`, `1000`)
- `FloatLit`: decimal float with dot (`3.14`, `0.5`)
- `BoundedLit`: decimal integer with `b` suffix (`0b`, `255b`)
String literals:
- delimited by `"`.
- support escapes: `\\`, `\"`, `\n`, `\r`, `\t`.
Booleans:
- `true`, `false`.
## 5. Module and barrel model
### 5.1 Required files
A module is valid only if it contains:
- one or more `.pbs` source files,
- exactly one `mod.barrel` file.
Missing `mod.barrel` is a compile-time error.
### 5.2 Barrel responsibility
`mod.barrel` is the only place where module visibility is defined.
Visibility levels:
- `mod`: visible across files in the same module.
- `pub`: visible to other modules through imports.
Any top-level declaration not listed in `mod.barrel` is file-private.
Using `mod` or `pub` as top-level declaration modifiers in `.pbs` files is a syntax error.
### 5.3 Barrel grammar
```ebnf
BarrelFile ::= BarrelItem* EOF
BarrelItem ::= BarrelVisibility BarrelKind Identifier ';'
BarrelVisibility ::= 'mod' | 'pub'
BarrelKind ::= 'fn' | 'type' | 'service'
```
Rules:
- `mod.barrel` cannot declare aliases.
- Barrel item order has no semantic meaning.
- The same symbol cannot appear more than once in `mod.barrel`.
- Each barrel item must resolve to an existing top-level declaration in the module.
- Alias syntax is allowed only in `import` declarations.
- Importing modules may only import symbols marked as `pub` in the target module barrel.
Examples:
```barrel
mod fn clamp;
pub fn sum;
pub type Vector;
mod service Audio;
```
## 6. File and declaration grammar
EBNF conventions used:
- `A?` optional
- `A*` zero or more
- `A+` one or more
- terminals in single quotes
### 6.1 File
```ebnf
File ::= ImportDecl* TopDecl* EOF
```
### 6.2 Imports
Imports must target modules, never files.
```ebnf
ImportDecl ::= 'import' ( ModuleRef | '{' ImportList '}' 'from' ModuleRef ) ';'
ImportList ::= ImportItem (',' ImportItem)*
ImportItem ::= Identifier ('as' Identifier)?
ModuleRef ::= '@' Identifier ':' ModulePath
ModulePath ::= Identifier ('/' Identifier)*
```
Examples:
```pbs
import @core:math;
import { Vector, Matrix as Mat } from @core:math;
```
### 6.3 Top-level declarations
```ebnf
TopDecl ::= TypeDecl | ServiceDecl | FunctionDecl
```
Top-level `let` and top-level statements are not allowed.
### 6.4 Type declarations
```ebnf
TypeDecl ::= 'declare' TypeKind Identifier TypeBody
TypeKind ::= 'struct' | 'contract' | 'error'
TypeBody ::= '{' TypeMember* '}'
TypeMember ::= FieldDecl | FnSigDecl
FieldDecl ::= Identifier ':' TypeRef ';'
FnSigDecl ::= 'fn' Identifier ParamList ReturnType? ';'
```
### 6.5 Services
```ebnf
ServiceDecl ::= 'service' Identifier (':' Identifier)? ServiceBody
ServiceBody ::= '{' ServiceMember* '}'
ServiceMember ::= 'fn' Identifier ParamList ReturnType? Block
```
### 6.6 Functions
```ebnf
FunctionDecl ::= 'fn' Identifier ParamList ReturnType? ElseFallback? Block
ParamList ::= '(' Param (',' Param)* ')'
Param ::= Identifier ':' TypeRef
ReturnType ::= ':' TypeRef
ElseFallback ::= 'else' Expr
```
## 7. Type syntax
```ebnf
TypeRef ::= TypePrimary
TypePrimary ::= SimpleType | GenericType | TupleType
SimpleType ::= Identifier
GenericType ::= Identifier '<' TypeRef (',' TypeRef)* '>'
TupleType ::= '(' TypeRef ',' TypeRef (',' TypeRef){0,4} ')'
```
Runtime alignment:
- Tuple type arity in v0 Core is 2..6.
- This aligns with runtime multi-return slot limits.
## 8. Statements and blocks
```ebnf
Block ::= '{' Stmt* TailExpr? '}'
Stmt ::= LetStmt | ReturnStmt | IfStmt | ForStmt | ExprStmt
TailExpr ::= Expr
LetStmt ::= 'let' Identifier (':' TypeRef)? '=' Expr ';'
ReturnStmt ::= 'return' Expr? ';'
ExprStmt ::= Expr ';'
IfStmt ::= 'if' Expr Block ('else' (IfStmt | Block))?
ForStmt ::= 'for' Identifier 'in' RangeExpr Block
RangeExpr ::= '[' Expr? '..' Expr? ']'
```
Notes:
- `if` is a statement in v0 Core.
- `when` is an expression.
- `break` and `continue` are deferred from v0 Core syntax.
## 9. Expression grammar and precedence
Assignment is not an expression in v0 Core.
```ebnf
Expr ::= WhenExpr
WhenExpr ::= 'when' OrExpr 'then' Expr 'else' Expr | OrExpr
OrExpr ::= AndExpr ('||' AndExpr)*
AndExpr ::= EqualityExpr ('&&' EqualityExpr)*
EqualityExpr ::= CompareExpr (('==' | '!=') CompareExpr)?
CompareExpr ::= CastExpr (('<' | '<=' | '>' | '>=') CastExpr)?
CastExpr ::= AddExpr ('as' TypeRef)*
AddExpr ::= MulExpr (('+' | '-') MulExpr)*
MulExpr ::= UnaryExpr (('*' | '/' | '%') UnaryExpr)*
UnaryExpr ::= ('!' | '-') UnaryExpr | CallExpr
CallExpr ::= PrimaryExpr ('(' ArgList? ')')*
ArgList ::= Expr (',' Expr)*
Literal ::= IntLit | FloatLit | BoundedLit | StringLit | BoolLit
BoolLit ::= 'true' | 'false'
PrimaryExpr ::= Literal | Identifier | GroupExpr | Block
GroupExpr ::= '(' Expr ')'
```
Non-associative constraints:
- `a < b < c` is invalid.
- `a == b == c` is invalid.
## 10. Runtime authority alignment constraints
These are hard constraints for frontend and syntax decisions:
- Runtime is deterministic and frame-synchronized.
- `FRAME_SYNC` is runtime safepoint and not surface syntax.
- Heap semantics are GC-based at runtime authority level.
- Host interaction is via `SYSCALL` in bytecode and host ABI mapping.
- Syscalls are callable but not first-class.
Syntax implications for v0 Core:
- No RC/HIP/gate-specific syntax is active.
- No closure literal syntax in v0 Core.
- No coroutine syntax (`spawn`, `yield`, `sleep`) in v0 Core.
## 11. Deferred syntax (explicitly out of v0 Core)
Deferred for later profiles:
- heap-specialized syntax: `alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`
- first-class closure/lambda surface syntax
- coroutine surface syntax
- pattern matching
- macro system
These words stay reserved so later profiles do not break source compatibility.
## 12. Conformance requirements for frontend rewrite
A v0 Core frontend is conformant if:
- tokenization follows this lexical spec,
- barrel parsing and validation follows Section 5,
- parsing follows this grammar and precedence,
- parser is deterministic,
- each token and AST node keeps stable spans,
- forbidden constructs produce deterministic diagnostics.
## 13. Minimal canonical examples
### 13.1 Function
```pbs
fn sum(a: int, b: int): int {
return a + b;
}
```
### 13.2 Local function + barrel visibility
```pbs
fn clamp(x: int, lo: int, hi: int): int {
if x < lo {
return lo;
}
if x > hi {
return hi;
}
return x;
}
```
```barrel
mod fn clamp;
```
### 13.3 Imports
```pbs
import @core:math;
import { Vec2 as V2 } from @core:math;
```
+24
View File
@@ -0,0 +1,24 @@
# PBS Specifications (Current)
This directory contains the current PBS specifications for frontend and language work.
## Authority model
- Runtime authority: `docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`.
- Bytecode authority: `docs/specs/bytecode/ISA_CORE.md`.
- Legacy reference only: `docs/specs/pbs_old/*`.
When a rule conflicts with runtime or bytecode authority, runtime and bytecode authority win.
## Purpose
- Define a stable syntax contract for PBS.
- Support a full frontend rewrite (lexer, parser, AST, lowering).
- Keep grammar deterministic and implementation-friendly.
## Files
- `PBS - Language Syntax Specification v0.md`: normative syntax and grammar for PBS v0 Core profile, including mandatory `mod.barrel` visibility rules.
- `PBS - Game Language Profile v1 (Draft).md`: game-first language direction for 2D workloads, defining ten normative design rules aligned with the closed VM and GC-first baseline.
- `PBS - Game Profile Syntax Specification v1 (Draft).md`: parser/lowering syntax delta for Game Profile over v0 Core (host `fn` declarations, assignment, while/break/continue, member/index postfix access).
- `PBS - Compatibility and Evolution Policy v1 (Draft).md`: compatibility contract for PBS across logical hardware updates (frozen core rules, canonical versioning, target manifests, major/minor policy, replay/conformance guarantees).
@@ -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.
@@ -0,0 +1,321 @@
# Prometeu PBS v0 — Unified Project, Module, Linking & Execution Specification
> **Status:** Canonical / Replaces all previous module & linking specs
>
> This document **fully replaces**:
>
> * "PBS – Module and Linking Model"
> * Any partial or implicit module/linking descriptions in earlier PBS documents
>
> After this document, there must be **no parallel or competing spec** describing project structure, modules, imports, or linking for PBS v0.
---
## 1. Purpose
This specification defines the **single authoritative model** for how a Prometeu PBS v0 program is:
1. Organized as a project
2. Structured into modules
3. Resolved and linked at compile time
4. Emitted as one executable bytecode blob
5. Loaded and executed by the Prometeu Virtual Machine
The primary objective is to **eliminate ambiguity** by enforcing a strict separation of responsibilities:
* **Compiler / Tooling**: all symbolic, structural, and linking work
* **Runtime / VM**: verification and execution only
---
## 2. Core Principles
### 2.1 Compiler Finality Principle
All operations involving **names, symbols, structure, or intent** must be completed at compile time.
The VM **never**:
* Resolves symbols or names
* Loads or links multiple modules
* Applies relocations or fixups
* Interprets imports or dependencies
### 2.2 Single-Blob Execution Principle
A PBS v0 program is executed as **one fully linked, self-contained bytecode blob**.
At runtime there is no concept of:
* Projects
* Modules
* Imports
* Dependencies
These concepts exist **only in the compiler**.
---
## 3. Project Model
### 3.1 Project Root
A Prometeu project is defined by a directory containing:
* `prometeu.json` — project manifest (required)
* One or more module directories
### 3.2 `prometeu.json` Manifest
The project manifest is mandatory and must define:
```json
{
"name": "example_project",
"version": "0.1.0",
"dependencies": {
"core": "../core",
"input": "../input"
}
}
```
#### Fields
* `name` (string, required)
* Canonical project identifier
* `version` (string, required)
* `dependencies` (map, optional)
* Key: dependency project name
* Value: filesystem path or resolver hint
Dependency resolution is **purely a compiler concern**.
---
## 4. Module Model (Compile-Time Only)
### 4.1 Module Definition
* A module is a directory inside a project
* Each module contains one or more `.pbs` source files
### 4.2 Visibility Rules
Visibility is enforced **exclusively at compile time**:
* `file`: visible only within the same source file
* `mod`: visible within the same module
* `pub`: visible to importing modules or projects
The VM has **zero awareness** of visibility.
---
## 5. Imports & Dependency Resolution
### 5.1 Import Syntax
Imports reference **projects and modules**, never files:
```
import @core:math
import @input:pad
```
### 5.2 Resolution Pipeline
The compiler performs the following phases:
1. Project dependency graph resolution (via `prometeu.json`)
2. Module discovery
3. Symbol table construction
4. Name and visibility resolution
5. Type checking
Any failure aborts compilation and **never reaches the VM**.
---
## 6. Linking Model (Compiler Responsibility)
### 6.1 Link Stage
After semantic validation, the compiler executes a **mandatory link stage**.
The linker:
* Assigns final `func_id` indices
* Assigns constant pool indices
* Computes final `code_offset` and `code_len`
* Resolves all jumps and calls
* Merges all module bytecode into one contiguous code segment
### 6.2 Link Output Format
The output of linking is a **Linked PBS Program** with the following layout:
```text
[ Header ]
[ Constant Pool ]
[ Function Table ]
[ Code Segment ]
```
All references are:
* Absolute
* Final
* Fully resolved
No relocations or fixups remain.
---
## 7. Runtime Execution Contract
### 7.1 VM Input Requirements
The Prometeu VM accepts **only linked PBS blobs**.
It assumes:
* All function references are valid
* All jumps target instruction boundaries
* No unresolved imports exist
### 7.2 VM Responsibilities
The VM is responsible for:
1. Loading the bytecode blob
2. Structural and control-flow verification
3. Stack discipline verification
4. Deterministic execution
The VM **must not**:
* Perform linking
* Resolve symbols
* Modify code offsets
* Load multiple modules
---
## 8. Errors and Runtime Traps
### 8.1 Compile-Time Errors
Handled exclusively by the compiler:
* Unresolved imports
* Visibility violations
* Type errors
* Circular dependencies
These errors **never produce bytecode**.
### 8.2 Runtime Traps
Runtime traps represent **deterministic execution faults**, such as:
* Stack underflow
* Invalid local access
* Invalid syscall invocation
* Explicit `TRAP` opcode
Traps are part of the **execution model**, not debugging.
---
## 9. Versioning and Scope
### 9.1 PBS v0 Guarantees
PBS v0 guarantees:
* Single-blob execution
* No runtime linking
* Deterministic behavior
### 9.2 Out of Scope for v0
The following are explicitly excluded from PBS v0:
* Dynamic module loading
* Runtime imports
* Hot reloading
* Partial linking
---
## 10. Canonical Ownership Summary
| Concern | Owner |
| ----------------- | ------------- |
| Project structure | Compiler |
| Dependencies | Compiler |
| Modules & imports | Compiler |
| Linking | Compiler |
| Bytecode format | Bytecode spec |
| Verification | VM |
| Execution | VM |
> **Rule of thumb:**
> If it requires names, symbols, or intent → compiler.
> If it requires bytes, slots, or PCs → VM.
---
## 11. Final Note
After adoption of this document:
* Any existing or future document describing PBS modules or linking **must defer to this spec**
* Any behavior conflicting with this spec is considered **non-compliant**
* The Prometeu VM is formally defined as a **pure executor**, not a linker
---
## Addendum — `prometeu.json` and Dependency Management
This specification intentionally **does not standardize the full dependency resolution algorithm** for `prometeu.json`.
### Scope Clarification
* `prometeu.json` **defines project identity and declared dependencies only**.
* **Dependency resolution, fetching, version selection, and conflict handling are responsibilities of the Prometeu Compiler**, not the VM and not the runtime bytecode format.
* The Virtual Machine **never reads or interprets `prometeu.json`**.
### Compiler Responsibility
The compiler is responsible for:
* Resolving dependency sources (`path`, `git`, registry, etc.)
* Selecting versions (exact, range, or `latest`)
* Applying aliasing / renaming rules
* Detecting conflicts and incompatibilities
* Producing a **fully linked, closed-world Program Image**
After compilation and linking:
* All symbols are resolved
* All function indices are fixed
* All imports are flattened into the final bytecode image
The VM consumes **only the resulting bytecode blob** and associated metadata.
### Separate Specification
A **dedicated specification** will define:
* The complete schema of `prometeu.json`
* Dependency version semantics
* Resolution order and override rules
* Tooling expectations (compiler, build system, CI)
This addendum exists to explicitly state the boundary:
> **`prometeu.json` is a compiler concern; dependency management is not part of the VM or bytecode execution model.**
@@ -0,0 +1,268 @@
# Prometeu.json — Project Manifest Specification
## Status
Draft · Complementary specification to the PBS Linking & Module Model
## Purpose
`prometeu.json` is the **project manifest** for Prometeu-based software.
Its role is to:
* Identify a Prometeu project
* Declare its dependencies
* Provide **input metadata to the compiler and linker**
It is **not** consumed by the Virtual Machine.
---
## Design Principles
1. **Compiler-owned**
* Only the Prometeu Compiler reads `prometeu.json`.
* The VM and runtime never see this file.
2. **Declarative, not procedural**
* The manifest declares *what* the project depends on, not *how* to resolve it.
3. **Closed-world output**
* Compilation + linking produce a single, fully resolved bytecode blob.
4. **Stable identity**
* Project identity is explicit and versioned.
---
## File Location
`prometeu.json` must be located at the **root of the project**.
---
## Top-level Structure
```json
{
"name": "my_project",
"version": "0.1.0",
"kind": "app",
"dependencies": {
"std": {
"git": "https://github.com/prometeu/std",
"version": ">=0.2.0"
}
}
}
```
---
## Fields
### `name`
**Required**
* Logical name of the project
* Used as the **default module namespace**
Rules:
* ASCII lowercase recommended
* Must be unique within the dependency graph
Example:
```json
"name": "sector_crawl"
```
---
### `version`
**Required**
* Semantic version of the project
* Used by the compiler for compatibility checks
Format:
```
MAJOR.MINOR.PATCH
```
---
### `kind`
**Optional** (default: `app`)
Defines how the project is treated by tooling.
Allowed values:
* `app` — executable program
* `lib` — reusable module/library
* `system` — firmware / system component
---
### `dependencies`
**Optional**
A map of **dependency aliases** to dependency specifications.
```json
"dependencies": {
"alias": { /* spec */ }
}
```
#### Alias semantics
* The **key** is the name by which the dependency is referenced **inside this project**.
* It acts as a **rename / namespace alias**.
Example:
```json
"dependencies": {
"gfx": {
"path": "../prometeu-gfx"
}
}
```
Internally, the dependency will be referenced as `gfx`, regardless of its original project name.
---
## Dependency Specification
Each dependency entry supports the following fields.
### `path`
Local filesystem dependency.
```json
{
"path": "../std"
}
```
Rules:
* Relative paths are resolved from the current `prometeu.json`
* Absolute paths are allowed but discouraged
---
### `git`
Git-based dependency.
```json
{
"git": "https://github.com/prometeu/std",
"version": "^0.3.0"
}
```
The compiler is responsible for:
* Cloning / fetching
* Version selection
* Caching
---
### `version`
Optional version constraint.
Examples:
* Exact:
```json
"version": "0.3.1"
```
* Range:
```json
"version": ">=0.2.0 <1.0.0"
```
* Latest:
```json
"version": "latest"
```
Semantics are defined by the compiler.
---
## Resolution Model (Compiler-side)
The compiler must:
1. Load root `prometeu.json`
2. Resolve all dependencies recursively
3. Apply aliasing rules
4. Detect:
* Cycles
* Version conflicts
* Name collisions
5. Produce a **flat module graph**
6. Invoke the linker to generate a **single Program Image**
---
## Interaction with the Linker
* `prometeu.json` feeds the **module graph**
* The linker:
* Assigns final function indices
* Fixes imports/exports
* Emits a closed bytecode image
After linking:
> No module boundaries or dependency information remain at runtime.
---
## Explicit Non-Goals
This specification does **not** define:
* Lockfiles
* Registry formats
* Caching strategies
* Build profiles
* Conditional dependencies
These may be added in future specs.
---
## Summary
* `prometeu.json` is the **single source of truth for project identity and dependencies**
* Dependency management is **compiler-owned**
* The VM executes **only fully linked bytecode**
This file completes the boundary between **project structure** and **runtime execution**.
@@ -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 ::= Visibility? 'fn' Identifier ParamList ReturnType? ElseFallback? Block
```
Top‑level `fn` are `mod` or `file-private` (default). They cannot be `pub`.
---
### 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,175 @@
# Runtime Traps v0 — Prometeu VM Specification
> **Status:** Proposed (requires explicit owner approval)
>
> **Scope:** Prometeu VM / PBS v0 execution model
---
## 1. Motivation
Prometeu aims to be a **deterministic, industrial-grade virtual machine**.
To achieve this, execution errors that are:
* caused by **user programs**,
* predictable by the execution model,
* and recoverable at the tooling / host level,
must be **explicitly represented** and **ABI-stable**.
This specification introduces **Runtime Traps** as a *formal concept*, consolidating behavior that already existed implicitly in the VM.
---
## 2. Definition
A **Runtime Trap** is a **controlled interruption of program execution** caused by a semantic violation detected at runtime.
A trap:
* **terminates the current execution frame** (or program, depending on host policy)
* **does not corrupt VM state**
* **returns structured diagnostic information** (`TrapInfo`)
* **is deterministic** for a given bytecode + state
A trap is **not**:
* a debugger breakpoint
* undefined behavior
* a VM panic
* a verifier/load-time error
---
## 3. Trap vs Other Failure Modes
| Category | When | Recoverable | ABI-stable | Example |
| ------------------ | ---------------------- | ----------- | ---------- | -------------------------------- |
| **Verifier error** | Load-time | ❌ | ❌ | Stack underflow, bad CFG join |
| **Runtime trap** | Execution | ✅ | ✅ | OOB access, invalid local |
| **VM panic** | VM invariant violation | ❌ | ❌ | Handler returns wrong slot count |
| **Breakpoint** | Debug only | ✅ | ❌ | Developer inspection |
---
## 4. Trap Information (`TrapInfo`)
All runtime traps must produce a `TrapInfo` structure with the following fields:
```text
TrapInfo {
code: u32, // ABI-stable trap code
opcode: u16, // opcode that triggered the trap
pc: u32, // program counter (relative to module)
message: String, // human-readable explanation (non-ABI)
}
```
### ABI Guarantees
* `code`, `opcode`, and `pc` are ABI-relevant and stable
* `message` is diagnostic only and may change
---
## 5. Standard Trap Codes (v0)
### 5.1 Memory & Bounds
| Code | Name | Meaning |
| -------------------- | ------------- | ------------------------------ |
| `TRAP_OOB` | Out of bounds | Access beyond allowed bounds |
| `TRAP_INVALID_LOCAL` | Invalid local | Local slot index out of bounds |
### 5.2 Execution & Types
| Code | Name | Meaning |
| ------------------------- | -------------------- | ------------------------------------------------------ |
| `TRAP_ILLEGAL_INSTRUCTION`| Illegal instruction | Unknown/invalid opcode encountered |
| `TRAP_TYPE` | Type violation | Type mismatch for operation or syscall argument types |
| `TRAP_DIV_ZERO` | Divide by zero | Division/modulo by zero |
| `TRAP_INVALID_FUNC` | Invalid function | Function index not present in function table |
| `TRAP_BAD_RET_SLOTS` | Bad return slots | Stack height mismatch at return |
### 5.3 System
| Code | Name | Meaning |
| ---------------------- | --------------- | --------------------------------------- |
| `TRAP_INVALID_SYSCALL` | Invalid syscall | Unknown syscall ID |
| `TRAP_STACK_UNDERFLOW` | Stack underflow | Missing arguments for syscall or opcode |
> This list is **closed for PBS v0** unless explicitly extended.
---
## 6. Trap Semantics
### 6.1 Execution
When a trap occurs:
1. The current instruction **does not complete**
2. No partial side effects are committed
3. Execution stops and returns `TrapInfo` to the host
### 6.2 Stack & Frames
* Operand stack is left in a **valid but unspecified** state
* Call frames above the trapping frame are not resumed
### 6.3 Host Policy
The host decides:
* whether the trap terminates the whole program
* whether execution may be restarted
* how the trap is surfaced to the user (error, log, UI, etc.)
---
## 7. Verifier Interaction
The verifier **must prevent** traps that are statically provable, including:
* stack underflow
* invalid control-flow joins
* invalid syscall IDs
* incorrect return slot counts
If a verifier rejects a module, **no runtime traps should occur for those causes**.
---
## 8. What Is *Not* a Trap
The following are **VM bugs or tooling errors**, not traps:
* handler returns wrong number of slots
* opcode implementation violates `OpcodeSpec`
* verifier and runtime disagree on stack effects
These must result in **VM panic**, not a trap.
---
## 9. Versioning Policy
* Trap codes are **ABI-stable within a major version** (v0)
* New trap codes may only be added in a **new major ABI version** (v1)
* Removing or reinterpreting trap codes is forbidden
---
## 10. Summary
Runtime traps are:
* an explicit part of the Prometeu execution model
* deterministic and ABI-stable
* reserved for **user-program semantic errors**
They are **not** debugging tools and **not** VM panics.
This spec formalizes existing behavior and freezes it for PBS v0.
---
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,359 @@
# Prometeu VM Memory Model v0
> **Status:** v0 (normative, implementer-facing)
>
> **Purpose:** define the runtime memory model required to execute PBS programs with stable bytecode.
>
> This specification describes the four memory regions and their interactions:
>
> 1. **Constant Pool** (read-only)
> 2. **Stack** (SAFE)
> 3. **Heap** (HIP storage bytes/slots)
> 4. **Gate Pool** (HIP handles, RC, metadata)
---
## 1. Design Goals
1. **Bytecode stability**: instruction meanings and data formats must remain stable across versions.
2. **Deterministic behavior**: no tracing GC; reclamation is defined by reference counts and safe points.
3. **Explicit costs**: HIP allocation and aliasing are explicit via gates.
4. **PBS alignment**: SAFE vs HIP semantics match PBS model.
---
## 2. Memory Regions Overview
### 2.1 Constant Pool (RO)
A program-wide immutable pool containing:
* integers, floats, bounded ints
* strings
* (optional in future) constant composite literals
Properties:
* read-only during execution
* indexed by `ConstId`
* VM bytecode uses `PUSH_CONST(ConstId)`
---
### 2.2 Stack (SAFE)
The **stack** contains:
* local variables (by slot)
* operand stack values for instruction evaluation
SAFE properties:
* values are copied by value
* no aliasing across variables unless the value is a gate handle
* stack values are reclaimed automatically when frames unwind
---
### 2.3 Heap (HIP storage)
The **heap** is a contiguous array of machine slots (e.g., `Value` slots), used only as **storage backing** for HIP objects.
Heap properties:
* heap cells are not directly addressable by bytecode
* heap is accessed only via **Gate Pool resolution**
The heap may implement:
* bump allocation (v0)
* free list (optional)
* compaction is **not** required in v0
---
### 2.4 Gate Pool (HIP handles)
The **gate pool** is the authoritative table mapping a small integer handle (`GateId`) to a storage object.
Gate Pool entry (conceptual):
```text
GateEntry {
alive: bool,
base: HeapIndex,
slots: u32,
strong_rc: u32,
weak_rc: u32, // optional in v0; may be reserved
type_id: TypeId, // required for layout + debug
flags: GateFlags,
}
```
Properties:
* `GateId` is stable during the lifetime of an entry
* `GateId` values may be reused only after an entry is fully reclaimed (v0 may choose to never reuse)
* any invalid `GateId` access is a **runtime trap** (deterministic)
---
## 3. SAFE vs HIP
### 3.1 SAFE
SAFE is stack-only execution:
* primitives
* structs / arrays as **value copies**
* temporaries
SAFE values are always reclaimed by frame unwinding.
### 3.2 HIP
HIP is heap-backed storage:
* storage objects allocated with `alloc`
* accessed through **gates**
* aliasing occurs by copying a gate handle
HIP values are reclaimed by **reference counting**.
---
## 4. Value Representation
### 4.1 Stack Values
A VM `Value` type must minimally support:
* `Int(i64)`
* `Float(f64)`
* `Bounded(u32)`
* `Bool(bool)`
* `String(ConstId)` or `StringRef(ConstId)` (strings live in const pool)
* `Gate(GateId)` ← **this is the only HIP pointer form in v0**
* `Unit`
**Rule:** any former `Ref` pointer type must be reinterpreted as `GateId`.
---
## 5. Allocation (`alloc`) and Gate Creation
### 5.1 Concept
PBS `alloc` creates:
1. heap backing storage (N slots)
2. a gate pool entry
3. returns a gate handle onto the stack
### 5.2 Required inputs
Allocation must be shape-explicit:
* `TypeId` describing the allocated storage type
* `slots` describing the storage size
### 5.3 Runtime steps (normative)
On `ALLOC(type_id, slots)`:
1. allocate `slots` contiguous heap cells
2. create gate entry:
* `base = heap_index`
* `slots = slots`
* `strong_rc = 1`
* `type_id = type_id`
3. push `Gate(gate_id)` to stack
### 5.4 Example
PBS:
```pbs
let v: Box<Vector> = box(Vector.ZERO);
```
Lowering conceptually:
* compute value `Vector.ZERO` (SAFE)
* `ALLOC(TypeId(Vector), slots=2)` → returns `Gate(g0)`
* store the two fields into heap via `STORE_GATE_FIELD`
---
## 6. Gate Access (Read/Write)
### 6.1 Access Principle
Heap is never accessed directly.
All reads/writes go through:
1. gate validation
2. gate → (base, slots)
3. bounds check
4. heap read/write
### 6.2 Read / Peek
`peek` copies from HIP storage to SAFE value.
* no RC changes
* no aliasing is created
### 6.3 Borrow (read-only view)
Borrow provides temporary read-only access.
* runtime may enforce with a borrow stack (debug)
* v0 may treat borrow as a checked read scope
### 6.4 Mutate (mutable view)
Mutate provides temporary mutable access.
* v0 may treat mutate as:
* read into scratch (SAFE)
* write back on `EndMutate`
Or (preferred later):
* direct heap writes within a guarded scope
---
## 7. Reference Counting (RC)
### 7.1 Strong RC
Strong RC counts how many **live gate handles** exist.
A `GateId` is considered live if it exists in:
* a stack slot
* a global slot
* a heap storage cell (HIP) (future refinement)
### 7.2 RC operations
When copying a gate handle into a new location:
* increment `strong_rc`
When a gate handle is removed/overwritten:
* decrement `strong_rc`
**Rule:** RC updates are required for any VM instruction that:
* assigns locals/globals
* stores into heap cells
* pops stack values
### 7.3 Release and Reclamation
When `strong_rc` reaches 0:
* gate entry becomes **eligible for reclamation**
* actual reclamation occurs at a **safe point**
Safe points (v0):
* end of frame
* explicit `FRAME_SYNC` (if present)
Reclamation:
1. mark gate entry `alive = false`
2. optionally add heap region to a free list
3. gate id may be recycled (optional)
**No tracing GC** is performed.
---
## 8. Weak Gates (Reserved / Optional)
v0 may reserve the field `weak_rc` but does not require full weak semantics.
If implemented:
* weak handles do not keep storage alive
* upgrading weak → strong requires a runtime check
---
## 9. Runtime Traps (Deterministic)
The VM must trap deterministically on:
* invalid `GateId`
* accessing a dead gate
* out-of-bounds offset
* type mismatch in a typed store/load (if enforced)
Traps must include:
* opcode
* span (if debug info present)
* message
---
## 10. Examples
### 10.1 Aliasing via gates
```pbs
let a: Box<Vector> = box(Vector.ZERO);
let b: Box<Vector> = a; // copy handle, RC++
mutate b {
it.x += 10;
}
let v: Vector = unbox(a); // observes mutation
```
Explanation:
* `a` and `b` are `GateId` copies
* mutation writes to the same heap storage
* `unbox(a)` peeks/copies storage into SAFE value
### 10.2 No HIP for strings
```pbs
let s: string = "hello";
```
* string literal lives in constant pool
* `s` is a SAFE value referencing `ConstId`
---
## 11. Conformance Checklist
A VM is conformant with this spec if:
* it implements the four memory regions
* `GateId` is the only HIP pointer form
* `ALLOC(type_id, slots)` returns `GateId`
* heap access is only via gate resolution
* RC increments/decrements occur on gate copies/drops
* reclamation happens only at safe points
---
## Appendix A — Implementation Notes (Non-normative)
* Start with bump-alloc heap + never-reuse GateIds (simplest v0)
* Add free list later
* Add borrow/mutate enforcement later as debug-only checks