prometeu-studio/discussion/workflow/plans/PLN-0007-pbs-ignored-values-warning-implementation.md

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