prometeu-studio/docs/pbs/specs/13. Lowering IRBackend Specification.md

PBS Lowering IRBackend Specification

Status: Draft v1 (Frontend Scope)
Applies to: first lowering boundary from bound PBS frontend model into IRBackend/IRBackendFile

1. Purpose

This document defines the normative frontend lowering contract from PBS source semantics to IRBackend.

Its purpose is to keep the first lowering deterministic and shared across implementations while PBS and backend design evolve.

2. Scope

This document defines:

• required preconditions before lowering starts,
• semantic obligations preserved in IRBackend,
• deterministic rejection behavior for unsupported frontend-lowering forms,
• and diagnostics attribution obligations for lowering failures in frontend scope.

This document does not define:

• VM lowering (IRVM),
• bytecode/PBX mapping,
• runtime execution behavior,
• verifier/loader internals.

Those concerns belong to shared acceptance specs under docs/general/specs.

3. Authority and Precedence

Normative precedence:

1. 3. Core Syntax Specification.md
2. 4. Static Semantics Specification.md
3. 11. AST Specification.md
4. 12. Diagnostics Specification.md
5. This document

If a lowering rule here conflicts with higher-precedence syntax/semantics rules, the higher-precedence rule wins.

4. Normative Inputs

This document depends on:

• 3. Core Syntax Specification.md
• 4. Static Semantics Specification.md
• 11. AST Specification.md
• 12. Diagnostics Specification.md

5. Lowering Preconditions

Frontend lowering into IRBackend may start only when:

1. source has been tokenized and parsed,
2. required syntax diagnostics have been emitted,
3. linking/name-resolution outcomes required for the current lowering slice are available,
4. and no unresolved semantic ambiguity is deferred to lowering.

Lowering must not invent unresolved semantic answers that belong to syntax/static/linking phases.

6. IRBackend Preserved Obligations

For each callable admitted by the current lowering slice, IRBackend must preserve at minimum:

1. callable identity (name/category as applicable),
2. callable arity,
3. declared return surface information,
4. source attribution anchor (file + span) for diagnostics and traceability.

The normative contract is obligation-based, not tied to one mandatory in-memory class graph.

7. Deterministic Rejection Policy

If a source form is outside current frontend-lowering support:

1. rejection must be deterministic,
2. diagnostics must expose stable code, severity, and primary attribution,
3. and unsupported forms must not silently degrade into different valid lowered behavior.

8. Conformance Boundary

IRBackend is the first lowering boundary (frontend responsibility).

Conformance-valid claims at this boundary require evidence from docs/general/specs/13. Conformance Test Specification.md and must only be published when the full claimed PBS surface is implemented at IRBackend level.

9. Explicit Deferrals

The following are intentionally out of scope for this document:

• IRBackend -> IRVM lowering,
• artifact encoding and binary layout,
• runtime lifecycle behavior,
• verifier and loader checks.

10. Non-Goals

• Freezing one optimizer strategy.
• Freezing one compiler architecture.
• Repeating runtime or bytecode authority.

11. Exit Criteria

This document is healthy when:

1. lowering preconditions are explicit,
2. preserved IRBackend obligations are explicit,
3. deterministic rejection policy is explicit and test-backed,
4. and scope boundaries with general/backend acceptance specs are explicit.