clean up
This commit is contained in:
@@ -1,152 +0,0 @@
|
||||
---
|
||||
id: PLN-0005
|
||||
ticket: pbs-game-facing-asset-refs-and-call-result-discard
|
||||
title: Propagate DEC-0005 Asset Address Surface into Compiler, Packer, and Studio Specs
|
||||
status: done
|
||||
created: 2026-03-27
|
||||
completed: 2026-03-27
|
||||
tags: [compiler, pbs, packer, studio, specs, addressable, asset-identity, be-fe-contract]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Propagate `DEC-0005` into the normative documentation so PBS asset authoring, backend-owned `FESurfaceContext`, and the separation between `asset` and `bank` become explicit, cross-domain, and implementation-ready.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0005` locks the symbolic authoring surface for assets around:
|
||||
|
||||
- hierarchical `assets...` addressing;
|
||||
- `Addressable` as the public/editorial PBS type shape;
|
||||
- `FESurfaceContext` as a backend-owned contract delivered to the frontend;
|
||||
- `List<Addressable(address, asset_id)>` as the v1 asset slice;
|
||||
- backend-owned validation and lowering from symbolic address to runtime-facing `asset_id`;
|
||||
- explicit separation between asset references and bank-internal addressing.
|
||||
|
||||
The repository already documents:
|
||||
|
||||
- packer ownership of `asset_id`;
|
||||
- Studio ownership of asset workspace UX;
|
||||
- PBS low-level runtime asset access through `LowAssets`.
|
||||
|
||||
What is still missing is the normative bridge between these surfaces.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Update PBS language specs to define the symbolic asset address model and the backend-to-frontend contract.
|
||||
- Update packer specs to state how the operational snapshot projects canonical asset addresses without turning `asset_name` into a first-class operational identity.
|
||||
- Update Studio specs to state that UI-facing asset identity aligns with the canonical address surface and namespace collision rules.
|
||||
- Add or update compiler-level specs so backend-owned asset lowering and `FESurfaceContext` ownership are normatively visible.
|
||||
|
||||
### Excluded
|
||||
- Implementing parser, semantic, lowering, or diagnostics code.
|
||||
- Designing bank-internal member addressing.
|
||||
- Defining richer future `FESurfaceContext` slices beyond assets.
|
||||
- Introducing rename-fragility warnings or LSP-only UX refinements.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update PBS Normative Surface Documents
|
||||
|
||||
**What:**
|
||||
Document the symbolic PBS surface for asset references and the `Addressable` model.
|
||||
|
||||
**How:**
|
||||
Revise the PBS specs so they state:
|
||||
|
||||
- `assets` is a compile-time namespace root;
|
||||
- leaves correspond to terminal `Addressable` values;
|
||||
- the canonical symbolic identity is the normalized asset-root-derived address;
|
||||
- `asset_name` is not the operational compile-time identity;
|
||||
- the PBS frontend may use a fake/editorial `Addressable` type while the backend remains the owner of executable semantics.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
|
||||
|
||||
### Step 2 - Update Backend Contract and Lowering Specs
|
||||
|
||||
**What:**
|
||||
Make the backend-owned `FESurfaceContext` and asset-lowering ownership explicit in compiler-wide specs.
|
||||
|
||||
**How:**
|
||||
Add or revise sections that state:
|
||||
|
||||
- the frontend receives a minimal backend-derived surface, not the raw packer snapshot;
|
||||
- v1 assets arrive as `List<Addressable(address, asset_id)>`;
|
||||
- backend validation and final lowering ownership remain backend-only;
|
||||
- symbolic asset references lower into the already-accepted `LowAssets` contract before runtime execution.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/compiler/18. Standard Library Surface Specification.md`
|
||||
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
|
||||
- optional conformance/matrix sync if needed: `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`
|
||||
|
||||
### Step 3 - Update Packer And Studio Domain Specs
|
||||
|
||||
**What:**
|
||||
Align packer and Studio domain specs with the symbolic address model and namespace rules.
|
||||
|
||||
**How:**
|
||||
Revise the specs so they state:
|
||||
|
||||
- packer remains owner of operational asset identity and derives canonical addresses from asset roots;
|
||||
- `asset_name` is not required as an operational registry field;
|
||||
- Studio should expose canonical address identity in UX where appropriate;
|
||||
- Studio must prevent terminal-vs-namespace collisions on asset root creation and moves.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/packer/2. Workspace, Registry, and Asset Identity Specification.md`
|
||||
- `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
||||
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
||||
|
||||
### Step 4 - Cross-Check Decision Boundaries
|
||||
|
||||
**What:**
|
||||
Verify that the edited specs preserve the intended scope split between `DEC-0004`, `DEC-0005`, and bank-specific addressing.
|
||||
|
||||
**How:**
|
||||
Check that:
|
||||
|
||||
- `DEC-0004` still owns only the low-level `LowAssets` ABI;
|
||||
- `DEC-0005` owns the symbolic authoring and backend-owned surface contract;
|
||||
- no updated document accidentally defines bank-internal member addressing or future richer `FESurfaceContext` slices.
|
||||
|
||||
**File(s):**
|
||||
- `discussion/workflow/decisions/DEC-0004-pbs-low-level-asset-manager-surface.md` if restored for reference, otherwise use `discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md`
|
||||
- `discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- None required for the editorial plan itself.
|
||||
|
||||
### Integration Tests
|
||||
- None required for the editorial plan itself.
|
||||
|
||||
### Manual Verification
|
||||
- Read updated specs together and verify the same terminology is used for `Addressable`, canonical address, `asset_id`, and `FESurfaceContext`.
|
||||
- Verify no document reintroduces `asset_name` as the normative compile-time identity.
|
||||
- Verify no document collapses `asset` references with bank-internal addressing.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] PBS specs describe hierarchical asset addressing and `Addressable` as the symbolic authoring surface.
|
||||
- [ ] Compiler specs state that the backend exposes a minimal `FESurfaceContext` and retains final validation/lowering ownership.
|
||||
- [ ] Packer specs state that canonical asset addresses are derived operationally without promoting `asset_name` back to first-class identity.
|
||||
- [ ] Studio specs state the namespace-collision rule for asset root creation and moves.
|
||||
- [ ] Updated docs preserve the scope boundary between low-level `LowAssets` ABI and symbolic asset references.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0005-pbs-asset-address-surface-and-be-lowering`
|
||||
- Existing `DEC-0004` low-level `LowAssets` contract
|
||||
|
||||
## Risks
|
||||
|
||||
- Cross-domain wording may drift if compiler, packer, and Studio specs are updated independently.
|
||||
- Over-documenting future `FESurfaceContext` expansion now would make the contract harder to keep stable.
|
||||
- It is easy to accidentally reintroduce `asset_name` as an editorial convenience unless the operational/authoring distinction stays explicit.
|
||||
@@ -1,184 +0,0 @@
|
||||
---
|
||||
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: done
|
||||
created: 2026-03-27
|
||||
completed: 2026-03-27
|
||||
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.
|
||||
@@ -1,151 +0,0 @@
|
||||
---
|
||||
id: PLN-0007
|
||||
ticket: pbs-game-facing-asset-refs-and-call-result-discard
|
||||
title: Implement DEC-0006 Ignored Values Lowering and Warning
|
||||
status: done
|
||||
created: 2026-03-27
|
||||
completed: 2026-03-27
|
||||
tags: [compiler, pbs, implementation, diagnostics, lowering, expression-statements, warnings]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `DEC-0006` so ignored materialized values in PBS `expression statement` positions are always explicitly discarded during lowering and also emit a warning in v1.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0006` locks a general language rule:
|
||||
|
||||
- `expression statement` forms that produce a materialized value must not silently leak backend stack discipline into source semantics;
|
||||
- the compiler must lower explicit discard behavior;
|
||||
- the compiler must also emit a warning in v1.
|
||||
|
||||
The current lowering path already lowers expression statements as plain expression evaluation.
|
||||
The existing executable stack analyzer already understands `POP`, but expression-statement lowering does not yet make discard behavior explicit.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Update PBS specs and diagnostics docs for ignored-value behavior.
|
||||
- Add a warning diagnostic contract for ignored materialized values.
|
||||
- Implement explicit discard lowering for expression statements that leave a materialized value.
|
||||
- Add frontend and lowering tests covering both the warning and the discard behavior.
|
||||
|
||||
### Excluded
|
||||
- Suppression syntax, lint categories, or configurable severity policy.
|
||||
- API-specific special cases for ignored values.
|
||||
- Non-PBS frontend work.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Propagate The Rule Into PBS Specs
|
||||
|
||||
**What:**
|
||||
Make the ignored-values rule explicit in PBS normative docs.
|
||||
|
||||
**How:**
|
||||
Update the specs so they state:
|
||||
|
||||
- `expression statement` may produce a value;
|
||||
- if that value is materialized and not consumed, the compiler must lower an explicit discard;
|
||||
- the v1 diagnostic policy is warning.
|
||||
|
||||
**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`
|
||||
- optional compiler-wide sync if needed: `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
|
||||
|
||||
### Step 2 - Add A Stable Warning Diagnostic Contract
|
||||
|
||||
**What:**
|
||||
Define the PBS diagnostic identity for ignored values.
|
||||
|
||||
**How:**
|
||||
Add a stable warning code and wire it through the diagnostics contract so tests can assert identity, phase, severity, and attribution.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/PbsDiagnosticsContractTest.java`
|
||||
- semantics tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/`
|
||||
|
||||
### Step 3 - Emit Ignored-Value Warnings During Semantics
|
||||
|
||||
**What:**
|
||||
Detect ignored materialized values at the statement-analysis boundary and emit the new warning.
|
||||
|
||||
**How:**
|
||||
Use the existing flow/statement analyzers to identify expression statements whose resulting type is materialized rather than unit-like, and emit the warning without blocking lowering.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowBodyAnalyzer.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowStatementAnalyzer.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsFlowExpressionAnalyzer.java`
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/PbsSemanticsOptionalResultTest.java`
|
||||
- new focused test file if needed for ignored-value warnings
|
||||
|
||||
### Step 4 - Lower Explicit Discard Operations
|
||||
|
||||
**What:**
|
||||
Make expression-statement lowering explicitly discard ignored values rather than implicitly leaving them to backend behavior.
|
||||
|
||||
**How:**
|
||||
Update executable lowering so expression statements that produce materialized values emit the appropriate discard instruction sequence, then verify stack accounting remains correct.
|
||||
|
||||
**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/PbsExecutableStackAnalyzer.java`
|
||||
- lowering tests under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/`
|
||||
|
||||
### Step 5 - Add Regression And Contract Coverage
|
||||
|
||||
**What:**
|
||||
Pin both the warning and the executable discard behavior with tests.
|
||||
|
||||
**How:**
|
||||
Add tests that cover:
|
||||
|
||||
- pure expression statements returning a value;
|
||||
- call expressions returning a value that is ignored;
|
||||
- unit-returning expression statements that must not warn;
|
||||
- executable lowering shape and stack behavior after explicit discard insertion.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/semantics/`
|
||||
- `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`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Semantics tests for warning emission on ignored non-unit values.
|
||||
- Negative tests ensuring unit-valued expression statements do not warn.
|
||||
- Lowering tests verifying discard instruction emission and stack balance.
|
||||
|
||||
### Integration Tests
|
||||
- End-to-end frontend compilation tests showing warning emission without turning the program into an error.
|
||||
- Targeted pipeline tests proving explicit discard lowering survives later executable lowering phases.
|
||||
|
||||
### Manual Verification
|
||||
- Inspect diagnostics and confirm ignored-value reports are warnings, not errors.
|
||||
- Inspect lowered instruction streams for representative ignored-value cases and confirm explicit discard behavior.
|
||||
- Re-run targeted PBS frontend and lowering test suites.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] PBS emits a stable warning diagnostic for ignored materialized values in expression statements.
|
||||
- [ ] Unit-like expression statements do not emit the ignored-value warning.
|
||||
- [ ] Executable lowering emits explicit discard behavior for ignored materialized values.
|
||||
- [ ] Stack analysis remains valid after the discard instruction path is added.
|
||||
- [ ] The rule applies generally and is not limited to one API family.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0006-pbs-ignored-values-lowering-and-warning`
|
||||
- Existing PBS flow semantics and executable lowering infrastructure
|
||||
|
||||
## Risks
|
||||
|
||||
- The current semantics/lowering split may make it easy to warn in one place but forget to lower explicit discard in another.
|
||||
- If the implementation does not distinguish unit-like from materialized values carefully, it may over-warn or under-warn.
|
||||
- Later severity/suppression refinements may require reshaping the diagnostics API, so the first version should keep the contract minimal and stable.
|
||||
-196
@@ -1,196 +0,0 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user