--- id: PLN-0006 ticket: pbs-game-facing-asset-refs-and-call-result-discard title: Implement DEC-0005 Addressable Surface, FESurfaceContext, and Backend Asset Lowering status: review created: 2026-03-27 completed: tags: [compiler, pbs, implementation, addressable, lowering, be-fe-contract, asset-identity] --- ## Objective Implement the executable and semantic infrastructure required by `DEC-0005` so PBS can consume a backend-owned asset surface, type symbolic asset references as `Addressable`, and lower them to runtime-facing `asset_id` before the final `LowAssets` call path. ## Background `DEC-0005` locks: - `assets...` as the symbolic compile-time surface; - `Addressable` as the PBS editorial/public type shape; - `FESurfaceContext` as a backend-owned contract delivered to the frontend; - `List` as the v1 asset payload; - backend-owned validation and final lowering to `asset_id`. The repository already has: - `LowAssets` in stdlib and tests; - `FrontendPhaseContext` as the frontend request surface; - `PBSFrontendPhaseService` as the main orchestration point for PBS frontend compilation; - executable lowering infrastructure that can already carry host-binding metadata. What is missing is the symbolic asset surface and the backend-owned path from frontend-visible `Addressable` to low-level `asset_id`. ## Scope ### Included - Extend frontend API models to carry a minimal asset `FESurfaceContext`. - Thread the new surface through PBS frontend compilation entrypoints. - Introduce or adapt PBS semantic handling for `Addressable` and asset namespace resolution. - Add backend-owned validation and lowering hooks for asset-aware callsites. - Add or update tests for compile surface ingestion, semantic acceptance, and lowering behavior. ### Excluded - Designing richer future `FESurfaceContext` slices beyond assets. - Implementing bank-internal member addressing. - Designing rename/move tooling or LSP UX beyond what is needed for compile surface wiring. - Changing the already accepted low-level `LowAssets` ABI. ## Execution Steps ### Step 1 - Add Frontend API Surface Models For Assets **What:** Introduce the minimal backend-to-frontend asset surface contract. **How:** Add new API models so the frontend request context can carry: - a `FESurfaceContext`; - an asset slice represented as `List`; - `Addressable(address, asset_id)` entries. Keep the contract intentionally small and backend-owned. Avoid leaking raw packer snapshot structures into the frontend API. **File(s):** - `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/messages/FrontendPhaseContext.java` - new companion model files under `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/messages/` - tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/` ### Step 2 - Thread FESurfaceContext Through PBS Frontend Orchestration **What:** Make `PBSFrontendPhaseService` and related assembly services consume the backend-provided asset surface. **How:** Propagate the new context data through the PBS frontend pipeline so semantic and lowering phases can read the v1 asset list without querying packer services directly. Keep ownership clear: the frontend consumes the surface, but the backend still owns final validation and lowering. **File(s):** - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PBSFrontendPhaseService.java` - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsModuleAssemblyService.java` - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/services/PbsImportedSemanticContextService.java` - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/services/PBSFrontendPhaseServiceTest.java` ### Step 3 - Implement PBS Symbolic Addressable Semantics **What:** Teach PBS semantics and binding layers how to recognize the symbolic asset surface and treat terminal asset leaves as `Addressable`. **How:** Add semantic support for: - hierarchical `assets...` namespace resolution; - terminal asset leaves typed as `Addressable`; - rejection of unresolved or structurally invalid asset references; - preventing intermediate namespace nodes from being treated as terminal addressable values. Do not move operational validation ownership out of the backend; semantic handling should remain a frontend-facing interpretation of backend-provided surface data. **File(s):** - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsNamespaceBinder.java` - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowExpressionAnalyzer.java` - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowStructuralExpressionAnalyzer.java` - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java` - parser/AST files only if the current source form requires parser changes - tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/` ### Step 4 - Add Backend-Owned Asset Lowering Hooks **What:** Implement final backend validation and lowering from symbolic `Addressable` references to runtime-facing `asset_id`. **How:** Extend lowering metadata and executable lowering so asset-aware callsites can: - identify which argument is asset-facing; - validate that the referenced value maps to a backend-owned `Addressable`; - lower the symbolic reference to the numeric `asset_id`; - continue into the already-existing `LowAssets` low-level host path. Keep this logic backend-owned rather than embedding operational resolution inside frontend-only semantics or service wrapper bodies. **File(s):** - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/PbsReservedMetadataExtractor.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/PbsExecutableBodyLowerer.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/PbsExecutableMetadataIndexFactory.java` - tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/` ### Step 5 - Add Conformance And Regression Coverage **What:** Pin the new contract with tests that cover both frontend surface consumption and backend lowering behavior. **How:** Add tests that prove: - `FESurfaceContext` asset data is visible to the PBS frontend; - symbolic asset references resolve only when present in the backend-provided list; - invalid namespace collisions or unresolved terminal references are rejected deterministically; - valid asset-facing callsites lower to the same low-level `asset_id` path expected by `LowAssets`. **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/PbsGateUStdlibCompileTest.java` - `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsGateUSdkInterfaceConformanceTest.java` ## Test Requirements ### Unit Tests - Semantics tests for `Addressable` terminals, intermediate namespace rejection, and unresolved symbolic asset references. - Metadata/lowering tests for asset-aware callsites and `asset_id` substitution. ### Integration Tests - `PBSFrontendPhaseService` tests that compile a project with a supplied `FESurfaceContext`. - End-to-end frontend compilation tests that import the low-level `@sdk:asset` surface and confirm the final lowering path stays aligned with `LowAssets`. ### Manual Verification - Inspect the new frontend API types and verify they expose only `List` for v1. - Verify no frontend code path queries packer services directly. - Re-run targeted PBS frontend test suites after implementation. ## Acceptance Criteria - [ ] `FrontendPhaseContext` or equivalent frontend API entrypoints can carry a backend-owned asset `FESurfaceContext`. - [ ] PBS can interpret terminal symbolic asset references as `Addressable` values using backend-provided surface data. - [ ] Backend lowering validates symbolic asset references and resolves them to runtime-facing `asset_id`. - [ ] Valid asset-facing calls still lower into the `LowAssets` contract from `DEC-0004`. - [ ] Missing or structurally invalid symbolic asset references fail deterministically with stable diagnostics. ## Dependencies - `DEC-0005-pbs-asset-address-surface-and-be-lowering` - Existing `DEC-0004` low-level asset surface - Existing frontend request and lowering infrastructure in `prometeu-compiler` ## Risks - The current frontend API may need more structural changes than expected to pass backend-owned surface data cleanly. - If `Addressable` is introduced inconsistently across semantics and lowering, the frontend may accept states the backend cannot lower. - Mixing frontend convenience with backend ownership could accidentally reintroduce direct packer coupling unless boundaries are enforced carefully.