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
@@ -34,6 +34,7 @@ public class IRBackend implements IRBackendReader {
private final ReadOnlyList<IntrinsicReference> intrinsicPool = ReadOnlyList.empty();
@Builder.Default
private final IRReservedMetadata reservedMetadata = IRReservedMetadata.empty();
private final IRLifecycleDeclaration lifecycleDeclaration;
public static IRBackendAggregator aggregator() {
return new IRBackendAggregator();
@@ -53,6 +54,8 @@ public class IRBackend implements IRBackendReader {
private final ArrayList<IRReservedMetadata.BuiltinTypeSurface> builtinTypeSurfaces = new ArrayList<>();
private final ArrayList<IRReservedMetadata.BuiltinConstSurface> builtinConstSurfaces = new ArrayList<>();
private final LinkedHashSet<String> requiredCapabilities = new LinkedHashSet<>();
private final ArrayList<IRLifecycleFileDeclaration> lifecycleFiles = new ArrayList<>();
private ReadOnlyList<ModuleId> lifecycleModuleOrder = ReadOnlyList.empty();
public void merge(final IRBackendFile backendFile) {
if (backendFile == null) {
@@ -90,6 +93,12 @@ public class IRBackend implements IRBackendReader {
for (final var function : backendFile.executableFunctions()) {
executableFunctions.add(remapExecutableFunction(function, moduleRemap, callableRemap, intrinsicRemap));
}
if (backendFile.lifecycleDeclaration() != null && !backendFile.lifecycleDeclaration().isEmpty()) {
lifecycleFiles.add(remapLifecycleFileDeclaration(
backendFile.lifecycleDeclaration(),
moduleRemap,
callableRemap));
}
final var metadata = backendFile.reservedMetadata();
hostMethodBindings.addAll(metadata.hostMethodBindings().asList());
builtinTypeSurfaces.addAll(metadata.builtinTypeSurfaces().asList());
@@ -111,6 +120,11 @@ public class IRBackend implements IRBackendReader {
return this;
}
public IRBackendAggregator lifecycleModuleOrder(final ReadOnlyList<ModuleId> moduleOrder) {
lifecycleModuleOrder = moduleOrder == null ? ReadOnlyList.empty() : moduleOrder;
return this;
}
private ModuleId[] reindexModules(final ReadOnlyList<ModuleReference> localModulePool) {
if (localModulePool == null || localModulePool.isEmpty()) {
return new ModuleId[0];
@@ -203,6 +217,37 @@ public class IRBackend implements IRBackendReader {
function.span());
}
private IRLifecycleFileDeclaration remapLifecycleFileDeclaration(
final IRLifecycleFileDeclaration declaration,
final ModuleId[] moduleRemap,
final CallableId[] callableRemap) {
final var remappedModuleId = remapModuleId(
declaration.moduleId(),
moduleRemap,
"lifecycle file");
return new IRLifecycleFileDeclaration(
remappedModuleId,
declaration.fileId(),
remapLifecycleCallable(declaration.fileInitFragment(), moduleRemap, callableRemap),
remapLifecycleCallable(declaration.projectInit(), moduleRemap, callableRemap),
remapLifecycleCallable(declaration.frameRoot(), moduleRemap, callableRemap));
}
private IRLifecycleCallableReference remapLifecycleCallable(
final IRLifecycleCallableReference reference,
final ModuleId[] moduleRemap,
final CallableId[] callableRemap) {
if (reference == null) {
return null;
}
return new IRLifecycleCallableReference(
remapModuleId(reference.moduleId(), moduleRemap, "lifecycle callable"),
reference.fileId(),
remapCallableId(reference.callableId(), callableRemap, "lifecycle callable"),
reference.role(),
reference.origin());
}
private ModuleId remapModuleId(
final ModuleId localModuleId,
final ModuleId[] moduleRemap,
@@ -273,6 +318,52 @@ public class IRBackend implements IRBackendReader {
return ReadOnlyList.wrap(pool);
}
private IRLifecycleDeclaration emitLifecycleDeclaration() {
if (lifecycleFiles.isEmpty()) {
return null;
}
if (lifecycleModuleOrder.isEmpty()) {
throw new IllegalStateException("lifecycle module order is required for executable handoff");
}
final var modules = new ArrayList<IRLifecycleModuleDeclaration>();
IRLifecycleCallableReference projectInit = null;
IRLifecycleCallableReference frameRoot = null;
for (final var moduleId : lifecycleModuleOrder) {
final var fragments = new ArrayList<IRLifecycleCallableReference>();
var hasLifecycleContribution = false;
for (final var lifecycleFile : lifecycleFiles) {
if (!sameModuleId(moduleId, lifecycleFile.moduleId())) {
continue;
}
hasLifecycleContribution = true;
if (lifecycleFile.fileInitFragment() != null) {
fragments.add(lifecycleFile.fileInitFragment());
}
if (projectInit == null && lifecycleFile.projectInit() != null) {
projectInit = lifecycleFile.projectInit();
}
if (frameRoot == null && lifecycleFile.frameRoot() != null) {
frameRoot = lifecycleFile.frameRoot();
}
}
if (hasLifecycleContribution) {
modules.add(new IRLifecycleModuleDeclaration(moduleId, ReadOnlyList.wrap(fragments)));
}
}
return new IRLifecycleDeclaration(ReadOnlyList.wrap(modules), projectInit, frameRoot);
}
private boolean sameModuleId(final ModuleId left, final ModuleId right) {
if (left == null || right == null) {
return left == right;
}
if (left.isNone() || right.isNone()) {
return left.isNone() && right.isNone();
}
return left.getIndex() == right.getIndex();
}
public IRBackend emit() {
return IRBackend
.builder()
@@ -290,6 +381,7 @@ public class IRBackend implements IRBackendReader {
ReadOnlyList.wrap(builtinTypeSurfaces),
ReadOnlyList.wrap(builtinConstSurfaces),
ReadOnlyList.wrap(requiredCapabilities.stream().toList())))
.lifecycleDeclaration(emitLifecycleDeclaration())
.build();
}
@@ -321,6 +413,7 @@ public class IRBackend implements IRBackendReader {
.append(", builtinTypes=").append(reservedMetadata.builtinTypeSurfaces().size())
.append(", builtinConsts=").append(reservedMetadata.builtinConstSurfaces().size())
.append(", requiredCapabilities=").append(reservedMetadata.requiredCapabilities().size())
.append(", lifecycle=").append(lifecycleDeclaration == null ? "none" : "declared")
.append('}');
if (functions.isEmpty()) {
@@ -17,7 +17,8 @@ public record IRBackendFile(
IRReservedMetadata reservedMetadata,
ReadOnlyList<ModuleReference> modulePool,
ReadOnlyList<CallableSignatureRef> callableSignatures,
ReadOnlyList<IntrinsicReference> intrinsicPool) {
ReadOnlyList<IntrinsicReference> intrinsicPool,
IRLifecycleFileDeclaration lifecycleDeclaration) {
public IRBackendFile {
fileId = Objects.requireNonNull(fileId, "fileId");
functions = functions == null ? ReadOnlyList.empty() : functions;
@@ -30,6 +31,29 @@ public record IRBackendFile(
intrinsicPool = intrinsicPool == null ? ReadOnlyList.empty() : intrinsicPool;
}
public IRBackendFile(
final FileId fileId,
final ReadOnlyList<IRFunction> functions,
final ReadOnlyList<IRSyntheticFunction> syntheticFunctions,
final ReadOnlyList<IRGlobal> globals,
final ReadOnlyList<IRBackendExecutableFunction> executableFunctions,
final IRReservedMetadata reservedMetadata,
final ReadOnlyList<ModuleReference> modulePool,
final ReadOnlyList<CallableSignatureRef> callableSignatures,
final ReadOnlyList<IntrinsicReference> intrinsicPool) {
this(
fileId,
functions,
syntheticFunctions,
globals,
executableFunctions,
reservedMetadata,
modulePool,
callableSignatures,
intrinsicPool,
null);
}
public IRBackendFile(
final FileId fileId,
final ReadOnlyList<IRFunction> functions) {
@@ -42,7 +66,8 @@ public record IRBackendFile(
IRReservedMetadata.empty(),
ReadOnlyList.empty(),
ReadOnlyList.empty(),
ReadOnlyList.empty());
ReadOnlyList.empty(),
null);
}
public static IRBackendFile empty(final FileId fileId) {
@@ -55,7 +80,8 @@ public record IRBackendFile(
IRReservedMetadata.empty(),
ReadOnlyList.empty(),
ReadOnlyList.empty(),
ReadOnlyList.empty());
ReadOnlyList.empty(),
null);
}
public IRBackendFile(
@@ -71,7 +97,8 @@ public record IRBackendFile(
reservedMetadata,
ReadOnlyList.empty(),
ReadOnlyList.empty(),
ReadOnlyList.empty());
ReadOnlyList.empty(),
null);
}
public IRBackendFile(
@@ -90,7 +117,8 @@ public record IRBackendFile(
reservedMetadata,
ReadOnlyList.empty(),
callableSignatures,
intrinsicPool);
intrinsicPool,
null);
}
public IRBackendFile(
@@ -110,6 +138,7 @@ public record IRBackendFile(
reservedMetadata,
modulePool,
callableSignatures,
intrinsicPool);
intrinsicPool,
null);
}
}
@@ -17,4 +17,5 @@ public interface IRBackendReader {
ReadOnlyList<CallableSignatureRef> getCallableSignatures();
ReadOnlyList<IntrinsicReference> getIntrinsicPool();
IRReservedMetadata getReservedMetadata();
IRLifecycleDeclaration getLifecycleDeclaration();
}
@@ -0,0 +1,23 @@
package p.studio.compiler.models;
import p.studio.compiler.source.Span;
import p.studio.compiler.source.identifiers.CallableId;
import p.studio.compiler.source.identifiers.FileId;
import p.studio.compiler.source.identifiers.ModuleId;
import java.util.Objects;
public record IRLifecycleCallableReference(
ModuleId moduleId,
FileId fileId,
CallableId callableId,
IRLifecycleCallableRole role,
Span origin) {
public IRLifecycleCallableReference {
moduleId = Objects.requireNonNull(moduleId, "moduleId");
fileId = Objects.requireNonNull(fileId, "fileId");
callableId = Objects.requireNonNull(callableId, "callableId");
role = Objects.requireNonNull(role, "role");
origin = origin == null ? Span.none() : origin;
}
}
@@ -0,0 +1,7 @@
package p.studio.compiler.models;
public enum IRLifecycleCallableRole {
FILE_INIT_FRAGMENT,
PROJECT_INIT,
FRAME_ROOT
}
@@ -0,0 +1,12 @@
package p.studio.compiler.models;
import p.studio.utilities.structures.ReadOnlyList;
public record IRLifecycleDeclaration(
ReadOnlyList<IRLifecycleModuleDeclaration> modules,
IRLifecycleCallableReference projectInit,
IRLifecycleCallableReference frameRoot) {
public IRLifecycleDeclaration {
modules = modules == null ? ReadOnlyList.empty() : modules;
}
}
@@ -0,0 +1,22 @@
package p.studio.compiler.models;
import p.studio.compiler.source.identifiers.FileId;
import p.studio.compiler.source.identifiers.ModuleId;
import java.util.Objects;
public record IRLifecycleFileDeclaration(
ModuleId moduleId,
FileId fileId,
IRLifecycleCallableReference fileInitFragment,
IRLifecycleCallableReference projectInit,
IRLifecycleCallableReference frameRoot) {
public IRLifecycleFileDeclaration {
moduleId = Objects.requireNonNull(moduleId, "moduleId");
fileId = Objects.requireNonNull(fileId, "fileId");
}
public boolean isEmpty() {
return fileInitFragment == null && projectInit == null && frameRoot == null;
}
}
@@ -0,0 +1,15 @@
package p.studio.compiler.models;
import p.studio.compiler.source.identifiers.ModuleId;
import p.studio.utilities.structures.ReadOnlyList;
import java.util.Objects;
public record IRLifecycleModuleDeclaration(
ModuleId moduleId,
ReadOnlyList<IRLifecycleCallableReference> fileInitFragments) {
public IRLifecycleModuleDeclaration {
moduleId = Objects.requireNonNull(moduleId, "moduleId");
fileInitFragments = fileInitFragments == null ? ReadOnlyList.empty() : fileInitFragments;
}
}
@@ -58,6 +58,11 @@ class IRBackendExecutableContractTest {
IRGlobalOrigin.class,
IRGlobalVisibility.class,
IRHiddenGlobalKind.class,
IRLifecycleDeclaration.class,
IRLifecycleModuleDeclaration.class,
IRLifecycleFileDeclaration.class,
IRLifecycleCallableReference.class,
IRLifecycleCallableRole.class,
IRReservedMetadata.class,
IRReservedMetadata.HostMethodBinding.class,
IRReservedMetadata.BuiltinTypeSurface.class,
@@ -80,7 +85,12 @@ class IRBackendExecutableContractTest {
IRReservedMetadata.class,
IRSyntheticCallableKind.class,
IRSyntheticFunction.class,
IRSyntheticOrigin.class);
IRSyntheticOrigin.class,
IRLifecycleDeclaration.class,
IRLifecycleModuleDeclaration.class,
IRLifecycleFileDeclaration.class,
IRLifecycleCallableReference.class,
IRLifecycleCallableRole.class);
assertTrue(
PUBLIC_CONTRACT_TYPES.containsAll(expectedTopLevelModelTypes),
@@ -137,6 +147,14 @@ class IRBackendExecutableContractTest {
assertEquals(FileId.class, recordComponentType(IRSyntheticOrigin.class, "fileId"));
assertEquals(ModuleId.class, recordComponentType(IRSyntheticFunction.class, "moduleId"));
assertEquals(ModuleId.class, recordComponentType(IRLifecycleModuleDeclaration.class, "moduleId"));
assertEquals(ModuleId.class, recordComponentType(IRLifecycleFileDeclaration.class, "moduleId"));
assertEquals(FileId.class, recordComponentType(IRLifecycleFileDeclaration.class, "fileId"));
assertEquals(ModuleId.class, recordComponentType(IRLifecycleCallableReference.class, "moduleId"));
assertEquals(FileId.class, recordComponentType(IRLifecycleCallableReference.class, "fileId"));
assertEquals(CallableId.class, recordComponentType(IRLifecycleCallableReference.class, "callableId"));
assertEquals(Span.class, recordComponentType(IRLifecycleCallableReference.class, "origin"));
assertEquals(String.class, recordComponentType(ModuleReference.class, "project"));
assertEquals(String.class, recordComponentType(CallableSignatureRef.class, "callableName"));
assertEquals(String.class, recordComponentType(IntrinsicReference.class, "canonicalName"));
@@ -640,6 +658,146 @@ class IRBackendExecutableContractTest {
second.getExecutableFunctions().get(1).callableId());
}
@Test
void aggregatorMustRemapTypedLifecycleReferencesAndPreserveDeclaredModuleOrder() {
final var fileASpan = new Span(new FileId(10), 1, 8);
final var fileBSpan = new Span(new FileId(20), 2, 9);
final var fileA = new IRBackendFile(
new FileId(10),
ReadOnlyList.empty(),
ReadOnlyList.from(new IRSyntheticFunction(
new ModuleId(0),
"file_init_zzz",
IRSyntheticCallableKind.FILE_INIT_FRAGMENT,
new IRSyntheticOrigin(new FileId(10), "warmup", fileASpan))),
ReadOnlyList.empty(),
ReadOnlyList.from(executable("file_init_zzz", 10, 0, 0, fileASpan)),
IRReservedMetadata.empty(),
ReadOnlyList.from(new ModuleReference("app", ReadOnlyList.from("zzz"))),
ReadOnlyList.from(new CallableSignatureRef(new ModuleId(0), "file_init_zzz", 0, "() -> unit")),
ReadOnlyList.empty(),
new IRLifecycleFileDeclaration(
new ModuleId(0),
new FileId(10),
new IRLifecycleCallableReference(
new ModuleId(0),
new FileId(10),
new CallableId(0),
IRLifecycleCallableRole.FILE_INIT_FRAGMENT,
fileASpan),
null,
null));
final var fileB = new IRBackendFile(
new FileId(20),
ReadOnlyList.empty(),
ReadOnlyList.empty(),
ReadOnlyList.empty(),
ReadOnlyList.from(
executable("boot", 20, 0, 0, fileBSpan),
executable("frame", 20, 0, 1, fileBSpan)),
IRReservedMetadata.empty(),
ReadOnlyList.from(new ModuleReference("app", ReadOnlyList.from("aaa"))),
ReadOnlyList.from(
new CallableSignatureRef(new ModuleId(0), "boot", 0, "() -> unit"),
new CallableSignatureRef(new ModuleId(0), "frame", 0, "() -> unit")),
ReadOnlyList.empty(),
new IRLifecycleFileDeclaration(
new ModuleId(0),
new FileId(20),
null,
new IRLifecycleCallableReference(
new ModuleId(0),
new FileId(20),
new CallableId(0),
IRLifecycleCallableRole.PROJECT_INIT,
fileBSpan),
new IRLifecycleCallableReference(
new ModuleId(0),
new FileId(20),
new CallableId(1),
IRLifecycleCallableRole.FRAME_ROOT,
fileBSpan)));
final var aggregator = IRBackend.aggregator();
aggregator.merge(fileA);
aggregator.merge(fileB);
aggregator.lifecycleModuleOrder(ReadOnlyList.from(new ModuleId(1), new ModuleId(0)));
final var backend = aggregator.emit();
final var declaration = backend.getLifecycleDeclaration();
assertNotNull(declaration);
assertEquals(2, declaration.modules().size());
assertEquals(1, declaration.modules().get(0).moduleId().getIndex());
assertEquals(0, declaration.modules().get(1).moduleId().getIndex());
assertEquals("aaa", backend.getModulePool().get(1).pathSegments().getFirst());
assertEquals("zzz", backend.getModulePool().get(0).pathSegments().getFirst());
assertEquals(IRLifecycleCallableRole.FILE_INIT_FRAGMENT, declaration.modules().get(1).fileInitFragments().getFirst().role());
assertEquals(0, declaration.modules().get(1).fileInitFragments().getFirst().callableId().getIndex());
assertEquals(1, declaration.projectInit().callableId().getIndex());
assertEquals(2, declaration.frameRoot().callableId().getIndex());
assertEquals(20, declaration.frameRoot().fileId().getId());
assertEquals(2, declaration.frameRoot().origin().getStart());
assertEquals("boot", backend.getExecutableFunctions().get(1).callableName());
assertEquals("frame", backend.getExecutableFunctions().get(2).callableName());
}
@Test
void aggregatorMustOmitLifecycleDeclarationWhenNoFileContributesOne() {
final var aggregator = IRBackend.aggregator();
aggregator.merge(new IRBackendFile(
new FileId(1),
ReadOnlyList.empty(),
ReadOnlyList.from(new IRBackendExecutableFunction(
new FileId(1),
"entry",
new CallableId(0),
0,
10,
0,
0,
0,
1,
ReadOnlyList.from(new IRBackendExecutableFunction.Instruction(
IRBackendExecutableFunction.InstructionKind.RET,
"",
null,
null,
Span.none())),
Span.none())),
IRReservedMetadata.empty(),
ReadOnlyList.from(new CallableSignatureRef("entry", 0, "() -> unit")),
ReadOnlyList.empty()));
final var backend = aggregator.emit();
assertNull(backend.getLifecycleDeclaration());
}
private static IRBackendExecutableFunction executable(
final String name,
final int fileId,
final int moduleId,
final int callableId,
final Span span) {
return new IRBackendExecutableFunction(
new FileId(fileId),
new ModuleId(moduleId),
name,
new CallableId(callableId),
(int) span.getStart(),
(int) span.getEnd(),
0,
0,
0,
1,
ReadOnlyList.from(new IRBackendExecutableFunction.Instruction(
IRBackendExecutableFunction.InstructionKind.RET,
"",
null,
null,
span)),
span);
}
private static IRBackend emitDeterministicAggregateFixture() {
final var aggregator = IRBackend.aggregator();
aggregator.merge(new IRBackendFile(