197 lines
10 KiB
Markdown
197 lines
10 KiB
Markdown
---
|
|
id: PLN-0008
|
|
ticket: pbs-game-facing-asset-refs-and-call-result-discard
|
|
title: Implement Mandatory AssetLowering Host Metadata and Backend Callsite Rewrite
|
|
status: done
|
|
created: 2026-03-27
|
|
completed: 2026-03-27
|
|
tags: [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.
|