Files
prometeu-studio/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md
T
bquarkz ea1cc26fe3
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): improve compiler reliability and AI diagnostics
Preserve structured diagnostics, source attribution, phase outcomes and revision context through compiler, Studio, LSP, MCP and JavaFX. Add project service discovery and resilient VS Code reconnection.

Correct all eight reproduced PBS production failures in expression context, sibling executable bindings and nominal owner identity. Consolidate specs, lessons, immutable baseline evidence and the maintained source-to-guest qualification runner.

Validation: required Gradle gate recorded 724 tests, with 711 passed and 13 skipped. Full corpus passed 168 compilation observations and 108 guest runs (104 successes and four deliberate faults); supplemental controls passed 42 compilations and 16 guest runs. TypeScript compilation, two Node discovery tests and discussion validation passed.
2026-11-10 12:36:25 +00:00

17 KiB

PBS Lowering IRBackend Specification

Status: Draft v1 (PBS Frontend Scope + Common Handoff Emission)
Applies to: first lowering boundary from bound PBS frontend model into the common IRBackend/IRBackendFile handoff

1. Purpose

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

Its purpose is to keep PBS lowering deterministic while preserving the common frontend-to-backend contract owned by compiler-general backend specs.

2. Scope

This document defines:

  • required preconditions before lowering starts,
  • AST invariants that lowering may assume as hard contract,
  • semantic obligations preserved in IRBackend,
  • deterministic rejection behavior for unsupported frontend-lowering forms,
  • diagnostics attribution obligations for lowering failures in frontend scope,
  • PBS obligations for emitting the common executable IRBackend handoff,
  • and backend-owned symbolic lowering obligations for asset-facing references.

This document does not define:

  • VM lowering (IRVM),
  • bytecode/PBX mapping,
  • runtime execution behavior,
  • verifier/loader internals,
  • or common backend ownership of the IRBackend -> IRVM contract.

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

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
  • docs/specs/compiler/20. IRBackend to IRVM Lowering 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. AST output satisfies 11 required invariants for this source unit, including:
    • one root per file,
    • deterministic child ordering,
    • mandatory node attribution (file/start/end) on nodes consumed by lowering,
    • mandatory declaration metadata on declaration nodes required by the active source slice,
    • and structural coherence after any parser recovery.
  4. linking/name-resolution outcomes required for the current lowering slice are available,
  5. and no unresolved semantic ambiguity is deferred to lowering.

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

When the active source slice depends on a backend-owned symbolic surface such as PBS asset references:

  • the frontend may assume access to the admitted frontend surface context selected for the build;
  • the frontend must not query domain services directly to discover operational assets;
  • and lowering must preserve enough identity for the backend to complete final operational resolution.

6. PBS IRBackend Emission Obligations

For each admitted PBS source unit and callable in the current lowering slice, PBS lowering must emit IRBackend that preserves 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,
  5. source-observable parse intent for statement/expression structure (including precedence/associativity outcome already fixed by AST shape).
  6. deterministic requiredCapabilities derived from admitted host-binding metadata for packer/runtime-manifest assistance.
  7. a typed IRLifecycleDeclaration for executable programs, with file-init fragment, optional project-init, and required frame-root references,
  8. explicit user globals and frontend-lowered file-init fragments required by later common lifecycle assembly,
  9. backend-owned symbolic identities that must survive to later executable lowering, including symbolic asset references when admitted by the source slice.

PBS lowering MUST NOT emit module init, project-init wrapper, published frame wrapper, physical entrypoint, or boot guard. Those artifacts are produced exclusively by common lifecycle assembly.

Lowering must not collapse source categories in a way that erases required declaration/callable identity needed by downstream diagnostics or conformance assertions.

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

IRBackend itself is the common frontend-to-backend executable handoff. This PBS spec owns only the PBS-specific admission and translation path into that handoff. Common backend rules for consuming IRBackend are owned by docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md.

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, phase, message template id, and primary attribution,
  3. and unsupported forms must not silently degrade into different valid lowered behavior.

Lowering must not convert a required syntax/static rejection into accepted lowered behavior.

For multi-module builds, lowering admission must apply dependency-scoped fail-fast:

  1. a module rejected in syntax, static semantics, linking, host-admission, or load-facing gates must not be emitted;
  2. any module that imports a rejected module (directly or transitively) must also be excluded from IRBackend emission;
  3. modules independent from the rejected dependency subgraph may continue to lower and emit in the same build.

8. Conformance Boundary

PBS emission into IRBackend is the first PBS lowering boundary (frontend responsibility).

Conformance-valid claims at this boundary require Gate U evidence from docs/specs/compiler/13. Conformance Test Specification.md.

For this frontier, Gate U evidence is expected to cover at minimum:

  • lexer behavior for covered inputs,
  • parser behavior and AST shape invariants required by 11,
  • lowering outcomes at IRBackend boundary,
  • and deterministic diagnostics identity/attribution for rejection cases.

Conformance at this boundary may be claimed only when the full claimed PBS source 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.

12. PBS Executable Handoff Emission Obligations (v1)

For executable backends, PBS lowering must emit IRBackend satisfying the additional handoff obligations below before common backend lowering starts.

12.1 Callable obligations

For each executable callable admitted into IRBackend, the frontend must preserve:

  1. stable callable identity in the current build graph,
  2. observable callable signature (input arity and return shape),
  3. callable category needed by downstream lowering,
  4. source attribution anchor (fileId, start, end),
  5. and executable body representation that is backend-lowerable.

12.2 Callsite classification obligations

Each executable callsite in IRBackend must be classified into exactly one category:

  1. CALL_FUNC,
  2. CALL_HOST,
  3. CALL_INTRINSIC.

PBS lowering must not leave this category for backend inference by textual heuristics.

12.3 Host-backed metadata obligations

Each host-backed callsite admitted at this boundary must preserve canonical host identity:

  1. module,
  2. name,
  3. version.

When available at this boundary, declared host ABI shape (arg_slots, ret_slots) must also be preserved for downstream validation.

When a host-backed callsite also depends on backend-owned symbolic asset lowering:

  • the frontend boundary MUST preserve which callsite argument is asset-facing;
  • for PBS v1 this asset-facing designation is carried by reserved host metadata [AssetLowering(param = N)];
  • the preserved symbolic operand MUST remain attributable to a backend-provided Addressable identity;
  • common backend stages MUST be able to rewrite that symbolic operand into runtime-facing asset_id before the final low-level host path is emitted.

When an expression statement leaves a materialized runtime value on the stack:

  • PBS lowering into IRBackend MUST emit explicit discard behavior rather than relying on implicit backend stack cleanup;
  • for single-slot materialized values this discard is represented by POP;
  • and the discard path MUST preserve stack-accounting validity for subsequent backend lowering stages.

12.4 VM-owned metadata obligations

VM-owned intrinsic callsites admitted at this boundary must preserve canonical intrinsic identity:

  1. canonicalName,
  2. canonicalVersion.

VM-owned builtin projections/constants/intrinsics must not be reclassified as host bindings.

12.5 Deterministic capability obligations

requiredCapabilities derived at this boundary must be deterministic for the same admitted input graph.

12.6 Boundary with backend lowering specs

This addendum defines obligations preserved at the IRBackend boundary only.

It does not replace:

  1. docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md,
  2. docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md,
  3. or docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md.

12.7 Executable Lifecycle Declaration Obligation

For executable PBS frontends, PBS lowering MUST emit a typed IRLifecycleDeclaration rather than assembling the published lifecycle.

At frontend IRBackend emission time:

  1. PBS MUST retain marker admission for [Init], [Frame], [BeforePause], [BeforeResume], and InitAllowed,
  2. PBS MUST emit typed references for:
    • file-init fragments that include global materialization and non-project [Init],
    • the optional project-init callable, which is the [Init] colocated with [Frame],
    • and the required frame-root callable marked with [Frame],
  3. the colocated project init MUST be excluded from file-init fragments,
  4. module order in the declaration MUST propagate the explicit dependency order already derived from resolved project/module data, without sorting by FileId, textual module name, or synthetic callable name,
  5. PBS MUST NOT emit module init, project-init wrapper, published frame wrapper, physical entrypoint, or boot guard,
  6. and common lifecycle assembly remains the owner of derived artifacts, including the published wrapper that becomes the physical entrypoint and owns the final frame return.

Existing values and input runtime alignment

The PBS input and value alignment contract governs int/Int32, long/Int64, exact builtin carriers, the Pad/Button/LowPad and Touch API, named-argument evaluation order, migration diagnostics and executable conformance. It supersedes older input-object and untyped executable-lowering descriptions.

Typed arrays and optional execution extension

The Array owner chapter defines the complete type, optional-flow and storage contract. This chapter owns source-to-common-IR projection; the owner chapter defines Array storage, optional carriers and complete-group requirements.

Array spelling and construction are owned by Core Syntax and the Array chapter; AST, diagnostics and lowering MUST consume that same syntax.

Parameterized contracts

The frontend substitutes each closed application and emits a concrete nominal Trait descriptor shared by equivalent uses. Distinct logical applications remain distinct despite shared physical carriers. Concrete implementation functions take the receiver first. CALL_TRAIT evaluates and roots the receiver before arguments, evaluates arguments left to right, then places the complete receiver/ImplementationId view after the argument groups as required by the runtime ABI. Preserve exact signatures, absence, ImplementationId zero, ownership, GC and quotas; generic calls do not add a Dynamic ABI or adaptation wrapper.

See PBS generic contracts.

Concrete generic structs and free functions

Instantiate structs, free functions and owner-bound implementations within PBS before publishing executable descriptors. Registry receives concrete fields, signatures, bodies, capture groups and targets. Specialized free-function references use existing empty-environment Closure values; Fn remains structural. Preserve receiver identity, implementation zero, singletons, rooting, GC, ownership, evaluation/fault order and quotas. No generic Dynamic/boxing ABI, opcode, descriptor category or runtime instantiation engine is introduced.

See Concrete generic structs and free functions.

Lowering optional runtime hook roles

Map BEFORE_PAUSE/BEFORE_RESUME to IRRegistry.Role.BEFORE_PAUSE (1) / BEFORE_RESUME (2) in typed FunctionMetadata. Preserve the declaration/callable identity, empty signature and capture list; no hidden receiver or parameter is introduced. INIT/FRAME and ordinary functions retain role None (0). Function names/exports/manifests are not role binding mechanisms. No MemcardBoot role is inferred or emitted by these markers.

Each role target and its dependencies are externally entered retention roots, even without source callers. Merge, lifecycle assembly, linking and optimization MUST preserve bodies and metadata. Common code consumes neutral typed roles, never PBS ASTs/names. The ordinary assembled entry remains physical FunctionId zero; hook targets are nonzero after deterministic linking. Common Registry/PBX validation and production runtime admission remain mandatory defenses.

Memcard integration

The Memcard Bootstrap and SDK contract defines the additional [MemcardBoot] marker, exact signature, neutral once-only bootstrap, project identity/slot validation and complete installed mem ABI. Its requirements apply in addition to this chapter; pause/resume remain independent.

Executable result return groups

Emit an existing typed return group: Int32 status 0 for success or canonical nominal error case index 1..N, followed by the complete plain payload group. Unit result has only status. Error payloads use admitted typed defaults, including nullable references, without constructing payload objects. Preserve typed reference/builtin/Fn/trait groups across signatures, Registry, direct/contract calls, branches and discard. Propagation fills the enclosing inactive payload and returns immediately; handle recovers locally or remaps outward. The common backend consumes neutral typed IR with no PBS branches.

See Core Sprite and Animation for the complete API, ranges, state table and conformance obligations.

Production binding preservation

Comparison lowering MUST scope expected types to the operands rather than leaking the enclosing bool result expectation into nested calls. Type inference does not execute an operand; emission evaluates each receiver and explicit argument once in the existing order. Legitimate contextual overload selection remains available at the owning expression boundary.

The module assembly supplies admitted sibling declaration/signature identities. Lowering references ordinary sibling functions and service methods/accessors in their defining module. Global accesses resolve to the defining file's single storage slot; they MUST NOT allocate or initialize another global in each caller. Services retain one canonical singleton/accessor at their definition. Internal symbolic global bindings MUST be fully resolved within PBS before publishing common IR; the common instruction contract, ABI and backend remain unchanged.

Runtime owner lookup and imported callable selection MUST preserve canonical declaration origin, rather than flattening private types into a name-only owner map. Synthesized receiver parameter types retain the defining source scope. Callable shape matching is qualified by the known owner declaration so distinct private owners with identical method spelling cannot replace or ambiguate one another. Aliases remain source-facing names for their original declaration.

Conformance includes F1-direct/two-calls/service-this, F3-function/global/service and F4-same-dependency/direct with their original files/names/imports. All original F1/F2/F3/F4/F5 controls, file-private rejection and deliberate guest fault remain mandatory. An investigation-only unoptimized probe omits OptimizeIRVMPipelineStage and emits original IRVM; this is not a public compiler optimization option. See Static Semantics and Diagnostics.