182 lines
13 KiB
Markdown
182 lines
13 KiB
Markdown
---
|
|
id: PLN-0029
|
|
ticket: pbs-service-facade-reserved-metadata
|
|
title: Implement Restricted Executable SDK Service Bodies for Intrinsic-Backed Public Services
|
|
status: review
|
|
created: 2026-04-03
|
|
completed:
|
|
tags: [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.
|