# 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` * `result` * 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` may implicitly return `none` * `result` 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` 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