prometeu-studio/discussion/workflow/plans/PLN-0008-pbs-assetlowering-host-metadata-and-callsite-rewrite.md

id	ticket	title	status	created	completed	tags
PLN-0008	pbs-game-facing-asset-refs-and-call-result-discard	Implement Mandatory AssetLowering Host Metadata and Backend Callsite Rewrite	done	2026-03-27	2026-03-27	compiler pbs implementation assetlowering host-metadata backend-lowering correction

Objective

Complete the missing normative part of DEC-0005 by implementing mandatory host-backed AssetLowering metadata and using it to rewrite Addressable arguments into runtime-facing asset_id at backend callsite lowering time.

Background

DEC-0005 did not only require:

• FESurfaceContext = List<Addressable(address, asset_id)>,
• symbolic assets... semantics,
• and backend ownership of final validation.

It also normatively locked a second requirement:

• asset-aware lowering metadata must live on the host-backed declaration surface;
• the backend must use that metadata to identify which host parameter is asset-facing;
• and host-backed lowering must rewrite the Addressable argument to operational asset_id before the final LowAssets path.

PLN-0006 implemented the symbolic surface and direct symbolic-to-asset_id expression lowering, but it did not implement:

• reserved attribute [AssetLowering(param = N)],
• reserved-metadata propagation for host bindings,
• host-signature validation for asset-lowered parameters,
• or host-callsite rewriting driven by parameter metadata.

This plan exists to correct that gap without reinterpreting DEC-0005.

Scope

Included

• Add AssetLowering(param = N) as a PBS reserved attribute on host-backed signatures.
• Validate the attribute shape and its admissible target surface.
• Extend backend host-binding metadata to carry asset-lowering parameter information.
• Rewrite host call lowering so asset-facing parameters consume symbolic Addressable values and lower them to asset_id according to host metadata.
• Align tests and specs so the normative path is explicit and covered.
• Correct any now-misleading tests or implementation shortcuts introduced by PLN-0006.

Excluded

• Redesign of DEC-0005.
• Changes to the LowAssets ABI already fixed by DEC-0004.
• Generalization to non-asset metadata families beyond the exact AssetLowering rule.
• Runtime-dynamic asset lookup exceptions.

Execution Steps

Step 1 - Add Reserved Attribute Surface For AssetLowering

What: Introduce [AssetLowering(param = N)] as a normative reserved attribute on host-backed callable surfaces.

How: Extend the PBS reserved attribute extractor and declaration validation so:

• AssetLowering is recognized as reserved metadata;
• it is admitted only on supported host-backed callable declarations;
• param is mandatory and must be a valid zero-based parameter index;
• the targeted parameter must match the Addressable author-facing contract required by DEC-0005;
• duplicate or malformed declarations fail deterministically.

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/semantics/PbsDeclarationSemanticsValidator.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java
• tests under prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/

Step 2 - Propagate AssetLowering Through Reserved Metadata

What: Make host binding metadata carry the asset-lowering contract instead of relying on implicit expression-level lowering.

How: Extend IRReservedMetadata.HostMethodBinding or the equivalent host-binding metadata shape so each binding can expose:

• whether asset lowering is required;
• which parameter index is asset-facing.

Update metadata construction, merging, indexing, and any downstream readers so the information survives all backend-facing frontend phases.

File(s):

• prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRReservedMetadata.java
• 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/PbsExecutableLoweringModels.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableMetadataIndexFactory.java
• metadata conformance tests under prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/

Step 3 - Rewrite Host Calls Using AssetLowering Metadata

What: Move final Addressable -> asset_id host-argument rewriting into the backend-owned host call path mandated by DEC-0005.

How: Update executable lowering so:

• host callsites inspect AssetLowering(param = N) metadata from the resolved host binding;
• the backend validates that the selected argument is a terminal backend-known Addressable;
• the selected argument is lowered to operational asset_id;
• non-asset-facing arguments are lowered normally;
• the final emitted host call matches the already accepted LowAssets runtime path.

This step must remove reliance on the current shortcut where symbolic asset references are lowered generically without host-parameter ownership.

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/PbsExecutableCallsiteEmitter.java
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/PbsExecutableLoweringContext.java
• related lowering metadata/index files
• targeted lowering tests under prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/

Step 4 - Realign Symbolic Expression Lowering With The Host-Metadata Contract

What: Correct the partial implementation from PLN-0006 so symbolic asset expressions support the normative host-metadata path instead of bypassing it.

How: Review the current direct lowering of assets... expressions and keep only the behavior that remains valid under DEC-0005.

At minimum:

• standalone symbolic Addressable semantics must remain correct;
• host-backed AssetLowering callsites must no longer depend on an implicit generic shortcut;
• tests that previously “passed” through direct expression lowering must be updated to assert the host-metadata path explicitly.

If any PLN-0006 behavior contradicts DEC-0005, correct the code and the tests rather than preserving the shortcut.

File(s):

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/
• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lowering/
• 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/services/PBSFrontendPhaseServiceTest.java

Step 5 - Propagate And Pin The Contract In Specs And Tests

What: Ensure the normative wording and regression coverage now match the corrected implementation.

How: Update specs and tests so they explicitly cover:

• AssetLowering(param = N) as mandatory host-backed metadata for asset-aware lowering;
• the backend-owned rewrite from symbolic Addressable to operational asset_id;
• rejection of malformed attribute usage and invalid parameter targeting;
• a representative LowAssets-aligned host call path using the metadata-bearing surface.

File(s):

• docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md
• docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md
• docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md
• docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md
• targeted PBS frontend/compiler tests

Test Requirements

Unit Tests

• Reserved-attribute tests for valid and invalid AssetLowering(param = N) usage.
• Metadata tests proving host bindings preserve the asset-lowering parameter index.
• Negative tests for duplicate, malformed, or out-of-range AssetLowering declarations.

Integration Tests

• End-to-end PBS frontend compilation tests where a host-backed asset API uses Addressable plus [AssetLowering(param = N)].
• Lowering tests proving the backend rewrites the marked argument to asset_id before the final host call.
• Regression tests proving LowAssets-aligned callsites still lower correctly after removing the shortcut path.

Manual Verification

• Inspect extracted reserved metadata and verify AssetLowering is carried on the host binding.
• Inspect lowered instruction streams for an asset-aware host call and verify the asset-facing argument becomes asset_id.
• Confirm malformed host metadata fails with deterministic source-facing diagnostics.

Acceptance Criteria

• PBS supports [AssetLowering(param = N)] as a validated reserved attribute on the correct host-backed surface.
• Host binding metadata preserves the asset-lowering parameter contract through backend lowering preparation.
• Backend host-call lowering uses the metadata to rewrite the selected Addressable argument into runtime-facing asset_id.
• The final asset-aware host path remains aligned with LowAssets and no longer depends on a generic shortcut that bypasses host metadata.
• Tests and specs explicitly cover the normative AssetLowering path from DEC-0005.

Dependencies

• DEC-0005-pbs-asset-address-surface-and-be-lowering
• DEC-0004 low-level LowAssets contract
• existing PLN-0006 implementation as the correction baseline

Risks

• The current direct symbolic lowering path may overlap with the normative host-metadata path and require careful removal or restriction.
• Extending host metadata may require synchronized updates across multiple compiler layers, increasing the chance of partial propagation if done carelessly.
• If tests keep asserting the shortcut path instead of the normative path, the repository may regress into the same discrepancy again.