Files
prometeu-studio/docs/specs/compiler-languages/pbs
..
2026-07-15 06:55:26 +01:00

PBS Specs

This directory contains the normative PBS specification set.

Installed Quickstart (Informative)

This guide and the numbered specifications are packaged with the PBS frontend. They describe the installed distribution, not a promise of a numbered language release. A spec's Draft v1 status is not the compiler version or SDK version. The project manifest selects the SDK major with stdlib; current packaged Game SDK resources use major 1. Unknown language/compiler versions remain unknown in Studio's context.

For an external coding agent:

  1. Request studio_project_context for the absolute root of the open project.
  2. Read pbs:quickstart, pbs:spec:3 (syntax), pbs:spec:4 (static semantics) and the relevant SDK reference IDs returned in that context. Continue pages until nextOffset is null. References are IDs, not filesystem paths.
  3. Inspect the project and its dependencies before changing source. Only edit the project's editable scope, excluding read-only SDK/external libraries.
  4. Use the installed LSP and compiler to check changes. When the corresponding MCP tools are available, acquire project control after the developer's DEV grant, then use the advertised language/build tools. Documentation reads do not require that grant. Missing tools/capabilities must not be assumed.
  5. Build and test small changes. Runtime execution also requires a compatible configured runtime; reading references does not install one.

Small Game Project

The installed example has three separately indexed files:

  • pbs:example:game:1:prometeu.json: a Game manifest with language: pbs, stdlib: 1 (serialized as a string), and no external dependencies;
  • pbs:example:game:1:src/main.pbs: [Init] and [Frame] functions drawing a moving rectangle through Gfx and constructing colors through Color;
  • pbs:example:game:1:src/mod.barrel: the module's public declarations.

Copy these reference texts to the corresponding paths only when creating that example in your editable project. The example is compiled in the test suite; it is not a complete game or a claim that every requested gameplay abstraction already exists. If a project has no external dependencies, no registry is needed. For dependencies, follow the installed compiler's manifest/registry requirements.

PBS source lives under src for the installed provider. Functions use fn, typed parameters and -> return types. let declares a local binding; declare global declares persistent global state. Imports name exports and a module address, for example import { Gfx } from @sdk:gfx;. A mod.barrel describes a module's public surface. Read the syntax/static-semantics chapters for exact rules rather than inferring compatibility with another language.

SDK Navigation and Limits

pbs:sdk:game:1:sdk/gfx/main.pbs exposes the actual installed Gfx source, including documentation comments and signatures. Its mod.barrel reference defines exports. Equivalent references exist for sdk/asset, sdk/composer, sdk/input, sdk/log, and core/color. Read those interfaces before calling them. Game SDK 1 does not currently ship audio or core/math modules.

Ordinary game source uses public services such as Gfx; it must not manufacture host bindings or mutate SDK declarations. Asset/composer workflows require their real asset/scene data and runtime capabilities. Reference availability does not guarantee those project resources exist. SDK or tooling limitations should be reported for separate work, not patched in read-only dependencies.

The reference index is generated from these owner-maintained documents and the frontend's SDK/example resources. The index schema revision is not a language version. Source hashes bind texts to the installed bundle; no repository checkout or network is needed to read them. The numbered specifications remain normative; this onboarding section and example are explanatory, not a second specification.

Purpose

Specs define the official PBS language/frontend contract.

They exist to make behavior, constraints, and interfaces stable across implementations and reviews.

Cross-language acceptance rules are not defined here. Those are maintained in docs/general/specs.

Expected Format

The exact structure may vary by document, but a spec should usually contain:

  1. Title
  2. Status
  3. Scope or Applies To
  4. Purpose
  5. Authority and Precedence
  6. Normative Inputs
  7. Core Rules
  8. Non-Goals
  9. Exit Criteria

Some specs may also include:

  • already-settled inputs,
  • initial section targets,
  • TODO sections for tracked unresolved items,
  • cross-references to adjacent specs.

Writing Rules

  • Write in normative language.
  • Integrate only decisions that have already been closed.
  • Keep debate history and exploratory alternatives out of the spec body.
  • Preserve clear boundaries between adjacent specs.
  • Use TODO only for explicitly tracked unresolved items, not as a substitute for agenda work.

Upstream Rule

Specs should normally be fed by:

  1. agendas that frame the open topic,
  2. decisions that close the architectural question,
  3. then spec integration.

If a spec edit would require guessing an unresolved design choice, the correct action is to stop and surface the missing decision first.

Current Chapter Focus

The active PBS chapter focus is:

  • 11. AST Specification.md
  • 12. Diagnostics Specification.md
  • 13. Lowering IRBackend Specification.md

Frontend-Owned Semantic Presentation Rule

PBS, as a frontend, owns its semantic vocabulary and semantic editor presentation contract.

That means:

  • PBS semantic keys are PBS-owned contract data,
  • PBS semantic highlight resources belong to PBS rather than to Studio or LSP,
  • PBS publishes that contract through FrontendSpec,
  • and Studio/LSP consume that contract without becoming owners of PBS semantic presentation assets.