implements PLN-0125
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 61.95% (17766/28676) * Branch Coverage: 52.69% (6860/13019) * Lines of Code: 28676 * Cyclomatic Complexity: 11490 #### Quality Gates Summary Output truncated.
Test / Build skipped: 15, passed: 643
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good

Move lifecycle assembly out of the PBS frontend into a common
AssembleLifecyclePipelineStage. PBS emits a typed IRLifecycleDeclaration;
the assembler owns wrappers, boot guard, and single project-init execution.

Housekeep DSC-0059 with LSN-0062, and include the DSC-0062 PVM/PBX
neutrality spec and lesson already present on this branch.
This commit is contained in:
2026-09-19 00:19:45 +01:00
parent c6ef56114f
commit 46bd0c42d3
42 changed files with 2349 additions and 762 deletions
@@ -11,6 +11,12 @@ Its purpose is to make backend lowering deterministic, reviewable, and compatibl
`IRBackend` is the common frontend-to-backend executable handoff. It is emitted by frontends and consumed by common backend stages. Backend lowering MUST NOT require PBS AST nodes, PBS tokens, PBS parser structures, PBS semantic objects, PBS editorial objects, or equivalent language-owned objects from future frontends.
`IRVM` is an internal compiler representation. It MUST be consumed by common
compiler optimization and PBX emission stages, and it MUST NOT cross the
compiler/runtime boundary or become an input, dependency, public type, or
operational concept of the runtime loader, verifier, or PVM. PBX is the only
executable artifact boundary between compiler and runtime.
## 2. Scope
This document defines:
@@ -66,10 +72,32 @@ At this boundary, `IRBackend` may contain only language-neutral compiler concept
8. host-call metadata,
9. intrinsic metadata,
10. reserved metadata required for backend lowering,
11. and required runtime or platform capabilities.
11. required runtime or platform capabilities,
12. and an optional typed `IRLifecycleDeclaration` used as lifecycle provenance after common assembly.
The common backend contract MUST express these concepts as backend obligations, not as PBS syntax or PBS semantic rules. When a concept currently originates from PBS, the backend contract still owns only the language-neutral obligation carried by `IRBackend`.
### 4.3 IRLifecycleDeclaration
`IRLifecycleDeclaration` is the typed, immutable, serializable-by-design lifecycle provenance carried by `IRBackend`.
An executable handoff MUST contain exactly one declaration before common assembly. A deliberately non-executable handoff MAY omit it; absence MUST NOT synthesize a default `main` or published wrapper.
The declaration MUST represent, using ordered collections and typed ids:
1. modules in explicit dependency order,
2. each module's ordered file-init fragment references,
3. an optional project-init callable reference,
4. and exactly one frame-root callable reference.
References MUST use `ModuleId`, `FileId`, `CallableId`, a typed role, and source attribution. The public shape MUST NOT expose maps, sets, callbacks, compiler services, or frontend-owned types.
`AssembleLifecyclePipelineStage` MUST run after `FrontendPhasePipelineStage` and before `LowerToIRVMPipelineStage`. `LifecycleAssemblerService` is the only owner of derived lifecycle artifacts: module init, project-init wrapper, published frame wrapper, physical entrypoint, and hidden boot guard. Those artifacts MUST use deterministic neutral internal identities. Common code MUST NOT discover roles from `__pbs.*` prefixes or depend on PBS packages.
The declaration MUST remain available on the assembled `IRBackend` as typed provenance. Downstream inspection MUST use roles, ids, and origins rather than synthetic names.
Project init MUST be absent from file-init fragments and MUST execute exactly once, after all module initializers and before the frame root. Bootstrap failure MUST abort without retry. The boot guard MUST prevent a second bootstrap after successful completion. The published wrapper owns the final frame return.
The common backend contract MUST NOT expose or require:
1. `PbsExpression`, `PbsStatement`, `PbsToken`, or equivalent PBS-owned syntax objects,
@@ -114,11 +142,14 @@ Initial enforcement for this contract SHOULD be audit and guardrail based: specs
Lowering from `IRBackend` to `IRVM` may start only when:
1. frontend admission to `IRBackend` is complete for the active slice,
2. required callsite categories (`CALL_FUNC`/`CALL_HOST`/`CALL_INTRINSIC`) are available,
3. required canonical host/intrinsic metadata is available for admitted callsites,
4. dependency-scoped fail-fast exclusions have already been applied at the `IRBackend` boundary,
5. compiler-selected published-wrapper entrypoint identity is present and unambiguous,
6. and target `vm_profile` is selected deterministically.
2. common lifecycle assembly has already materialized derived artifacts for an executable handoff,
3. required callsite categories (`CALL_FUNC`/`CALL_HOST`/`CALL_INTRINSIC`) are available,
4. required canonical host/intrinsic metadata is available for admitted callsites,
5. dependency-scoped fail-fast exclusions have already been applied at the `IRBackend` boundary,
6. compiler-selected published-wrapper entrypoint identity is present and unambiguous,
7. and target `vm_profile` is selected deterministically.
Declaration validation, role uniqueness, explicit order, and rejection of frontend-preassembled derived artifacts belong to `LifecycleAssemblerService`. `IRBackend -> IRVM` MUST keep only backend preconditions on the assembled graph, such as published-wrapper identity, synthetic origin presence, and hidden boot-guard presence. It MUST NOT reconstruct lifecycle order from callable names.
## 6. IRVM Model Obligations
@@ -159,13 +190,14 @@ Function indexing must be deterministic:
4. manifest-owned or name-only entrypoint fallback is forbidden,
5. and identical admitted input graphs must produce identical function-id assignments.
For PBS executable lowering:
For executable lowering:
- the userland callable marked with `[Frame]` remains the logical frame root,
- the wrapper path must contain final `FRAME_RET`,
- the declared frame-root callable remains the logical frame root,
- the assembled published wrapper is the physical entrypoint,
- the wrapper path must contain the final frame return,
- and lowering must preserve that distinction through `IRVM`.
These PBS-facing names describe the current frontend source of the lifecycle structure. The backend-owned obligation is the neutral requirement that the compiler-selected published wrapper be the physical entrypoint and that lifecycle state remain explicit in `IRBackend`.
PBS `[Init]`/`[Frame]` markers are a frontend source of the declaration. The backend-owned obligation is the neutral requirement that the compiler-selected published wrapper be the physical entrypoint and that lifecycle provenance remain explicit in `IRBackend` through typed roles and ids. Neutral synthetic names are internal and are not a public ABI.
## 9. Callsite Lowering Obligations