prometeu-studio/docs/specs/compiler-languages/pbs/README.md

PBS Specs

This directory contains the normative PBS specification set.

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.