prometeu-runtime/docs/specs/pbs/Prometeu Base Script (PBS) - Implementation Spec.md

# 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