prometeu-studio/discussion/workflow/plans/PLN-0029-pbs-sdk-executable-service-bodies.md

id	ticket	title	status	created	completed	tags
PLN-0029	pbs-service-facade-reserved-metadata	Implement Restricted Executable SDK Service Bodies for Intrinsic-Backed Public Services	review	2026-04-03		compiler pbs sdk stdlib lowering service intrinsic sdk-interface

Objective

Implement the DEC-0013 model for restricted executable SDK service bodies so public SDK services such as @sdk:input compile as ordinary PBS service code while preserving host and intrinsic lowering inside imported SDK service bodies.

Background

DEC-0013 accepts the model where:

• SDK_INTERFACE remains non-executable by default;
• eligible SDK service methods gain a narrow executable path;
• user callsites lower as ordinary callable invocations of imported SDK service methods;
• host and intrinsic lowering continue to happen inside the imported SDK service body;
• returned reserved values preserve owner and chaining behavior;
• dedicated diagnostics replace generic unresolved-callee failures for unsupported cases.

The current compiler exposes imported SDK service signatures but does not provide an executable-body path for intrinsic-backed service wrappers such as Input.touch() and Input.pad(). The plan below closes that gap without generalizing arbitrary executable code across all interface declarations.

Scope

Included

• Defining and validating eligibility rules for executable SDK service methods.
• Representing eligible SDK service method bodies so imported user callsites can lower them as ordinary callable invocations.
• Lowering imported SDK service bodies under a restricted executable subset.
• Preserving owner propagation and chained reserved behavior for returned intrinsic-backed values.
• Adding dedicated diagnostics for unsupported executable SDK service bodies.
• Updating frontend and integration tests to reflect the accepted model.

Excluded

• General executable support for arbitrary SDK_INTERFACE functions, globals, or unrestricted declarations.
• Public exposure of private reserved builtin roots.
• Expansion of the restricted executable subset beyond the first explicitly supported wave unless needed to satisfy DEC-0013.
• Editorial changes to unrelated SDK modules.

Execution Steps

Step 1 - Define the Executable SDK Service Eligibility Boundary

What: Introduce the compiler-side concept of an eligible executable SDK service method and enforce the first restricted subset accepted by DEC-0013.

How: Add validation logic that runs on SourceKind.SDK_INTERFACE service methods and classifies each method as either executable/importable or rejected with a dedicated diagnostic. The first supported subset must explicitly allow local bindings, ordinary returns, calls to reserved hosts, calls to reserved builtin const proxies, intrinsic-return chaining, and straightforward wrapper-style expression composition. Any construct outside that subset must fail deterministically with a dedicated diagnostic instead of reaching generic lowering failure.

File(s):

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationSemanticsValidator.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/... as needed for executable-subset validation
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsSemanticsErrors.java

Step 2 - Expose Imported SDK Service Bodies to the Lowering Pipeline

What: Extend imported SDK context assembly so eligible SDK service methods are available not only as callable signatures but also as executable bodies that user modules can target.

How: Enrich the imported semantic/lowering context with per-method executable metadata for eligible SDK service methods, including module identity, owning service, signature shape, AST/body reference, and any lowering metadata required to compile the imported method body exactly once in a controlled way. Preserve the existing lightweight path for non-executable interface declarations.

File(s):

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContextService.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContext.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsFrontendCompiler.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/messages/FESurfaceContext.java

Step 3 - Lower Public SDK Service Calls as Callable Invocations of Imported Bodies

What: Make user callsites such as Input.touch() and Input.pad() resolve as callable invocations of imported executable SDK service methods.

How: Update callable resolution and lowering metadata so eligible imported SDK service methods participate as ordinary callable targets with executable bodies rather than metadata-only surfaces. Ensure public service callsites resolve to CALL_FUNC-style lowering when appropriate and do not require public facade metadata or direct builtin-root identity at the callsite itself.

File(s):

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableCallsiteEmitter.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringService.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringContext.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringModels.java

Step 4 - Lower Imported SDK Service Method Bodies Under the Restricted Subset

What: Add the executable-body lowering path for eligible imported SDK service methods so reserved host and intrinsic calls continue to lower inside the SDK method body itself.

How: Reuse as much of the existing executable lowering pipeline as possible, but constrain it to imported eligible SDK service methods. Ensure the lowering path supports locals, returns, reserved host calls, reserved builtin const proxy calls, and direct wrapper-style logic. Prevent accidental lowering of unsupported or non-eligible interface code.

File(s):

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableBodyLowerer.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableMetadataIndexFactory.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableCallsiteEmitter.java

Step 5 - Preserve Return Owner and Chaining Semantics Across SDK Service Returns

What: Ensure values returned by imported SDK service methods keep the same reserved owner identity and chaining behavior as the intrinsic/host-backed values produced inside the method body.

How: Propagate owner metadata from the lowered reserved call through the return path of the imported SDK service method so downstream user expressions such as Input.touch().x() and Input.pad().a().pressed() retain resolvable chained semantics. Add targeted validation when the compiler cannot preserve this owner chain safely.

File(s):

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableMetadataIndexFactory.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableCallsiteEmitter.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringContext.java

Step 6 - Introduce Dedicated Diagnostics for Non-Lowerable SDK Service Bodies

What: Replace generic unresolved-callee failures with dedicated diagnostics for unsupported executable SDK service bodies.

How: Add explicit error codes and reporting paths for:

• non-eligible executable SDK service methods;
• unsupported constructs inside executable SDK service bodies;
• signature/body inconsistencies for imported executable SDK service methods;
• unpreservable reserved owner/chaining cases.

Wire these diagnostics so failures are emitted at validation/lowering time with stable code identity and source spans.

File(s):

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsSemanticsErrors.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/...
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/... diagnostic contract tests

Step 7 - Update and Expand Tests to Match DEC-0013

What: Align the PBS frontend and pipeline test suite with the accepted executable SDK service body model.

How: Update existing @sdk:input tests that currently assume public callsites lower directly to intrinsics. Add coverage for:

• public Input.touch() and Input.pad() callsites lowering successfully through imported SDK service bodies;
• intrinsic lowering occurring inside those imported bodies;
• locals and intermediate processing inside SDK service bodies;
• returned owner and chained calls such as touch.x() and Input.pad().a().pressed();
• dedicated diagnostics when an executable SDK service body violates the restricted subset.

File(s):

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsFrontendCompilerTest.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUSdkInterfaceConformanceTest.java
• prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/integration/MainProjectPipelineIntegrationTest.java
• related diagnostic/lowering tests as needed

Test Requirements

Unit Tests

• Validation tests for executable SDK service method eligibility and restricted-subset rejection.
• Lowering tests for imported SDK service callsites resolving as callable invocations.
• Lowering tests for intrinsic and host operations inside imported SDK service bodies.
• Owner-propagation tests for returned reserved values and chained member calls.
• Diagnostic identity tests for each new SDK executable-service failure mode.

Integration Tests

• Pipeline test proving test-projects/main compiles successfully when @sdk:input is expressed as a public service over a private builtin proxy.
• Integration coverage for mixed SDK modules so existing host-backed wrappers (Log, Gfx, Assets) continue to work unchanged alongside the new intrinsic-backed service model.

Manual Verification

• Run the compile pipeline against the main test project with the service-based @sdk:input shape.
• Verify the resulting IR contains callable lowering for the public SDK service entrypoint and intrinsic lowering inside the imported SDK service body.
• Confirm unsupported SDK executable constructs emit the new dedicated diagnostics rather than E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE.

Acceptance Criteria

• Eligible SDK service methods in SDK_INTERFACE can be imported with executable bodies while the rest of the interface surface remains non-executable by default.
• Public callsites such as Input.touch() and Input.pad() lower as callable invocations of imported SDK service methods.
• Reserved host and intrinsic calls inside imported SDK service bodies lower correctly through the existing reserved machinery.
• Returned reserved values preserve owner/chaining semantics for expressions such as Input.touch().x() and Input.pad().a().pressed().
• Unsupported executable SDK service bodies fail with dedicated diagnostics instead of generic unresolved-callee errors.
• Existing host-backed SDK services continue to compile without regression.
• Frontend and integration tests reflect and enforce the accepted model from DEC-0013.

Dependencies

• Accepted decision: DEC-0013.
• Existing reserved metadata and intrinsic lowering infrastructure in the PBS frontend.
• Existing imported semantic-context assembly for SDK modules.
• Existing host-backed SDK service behavior must remain as the regression baseline.

Risks

• The executable-service exception for SDK_INTERFACE could accidentally broaden into support for arbitrary interface code if the eligibility boundary is not enforced centrally.
• Owner propagation across imported SDK service returns may require careful threading of metadata through call/return paths and could regress chained intrinsic resolution if partially implemented.
• Reusing ordinary executable lowering for imported SDK bodies may expose assumptions that currently only hold for project-local executable functions.
• Test expectations that currently assert direct intrinsic callsites may need careful revision to avoid preserving obsolete invariants.