add spec docs
This commit is contained in:
@@ -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;
|
||||
```
|
||||
@@ -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).
|
||||
Reference in New Issue
Block a user