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:

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