prometeu-studio/discussion/workflow/plans/PLN-0006-pbs-asset-address-surface-implementation.md

id	ticket	title	status	created	completed	tags
PLN-0006	pbs-game-facing-asset-refs-and-call-result-discard	Implement DEC-0005 Addressable Surface, FESurfaceContext, and Backend Asset Lowering	done	2026-03-27	2026-03-27	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.