--- id: PLN-0007 ticket: pbs-game-facing-asset-refs-and-call-result-discard title: Implement DEC-0006 Ignored Values Lowering and Warning status: review created: 2026-03-27 completed: 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.