185 lines
9.5 KiB
Markdown
185 lines
9.5 KiB
Markdown
---
|
|
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<Addressable(address, asset_id)>` 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>`;
|
|
- `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<Addressable(address, asset_id)>` 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.
|