From 124c6d078ea24aa479066a443c6a846e2e598f8b Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 27 Mar 2026 16:58:20 +0000 Subject: [PATCH] asset addressable PBS surface --- .../.backups/index.ndjson.20260327-165050.bak | 9 + .../.backups/index.ndjson.20260327-165348.bak | 9 + discussion/index.ndjson | 4 +- ...cing-asset-refs-and-call-result-discard.md | 85 ++++---- ...s-asset-address-surface-and-be-lowering.md | 147 ++++++++++++++ ...pbs-ignored-values-lowering-and-warning.md | 88 +++++++++ ...-asset-address-surface-spec-propagation.md | 152 +++++++++++++++ ...bs-asset-address-surface-implementation.md | 184 ++++++++++++++++++ ...s-ignored-values-warning-implementation.md | 151 ++++++++++++++ 9 files changed, 785 insertions(+), 44 deletions(-) create mode 100644 discussion/.backups/index.ndjson.20260327-165050.bak create mode 100644 discussion/.backups/index.ndjson.20260327-165348.bak create mode 100644 discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md create mode 100644 discussion/workflow/decisions/DEC-0006-pbs-ignored-values-lowering-and-warning.md create mode 100644 discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md create mode 100644 discussion/workflow/plans/PLN-0006-pbs-asset-address-surface-implementation.md create mode 100644 discussion/workflow/plans/PLN-0007-pbs-ignored-values-warning-implementation.md diff --git a/discussion/.backups/index.ndjson.20260327-165050.bak b/discussion/.backups/index.ndjson.20260327-165050.bak new file mode 100644 index 00000000..bf4f5ae1 --- /dev/null +++ b/discussion/.backups/index.ndjson.20260327-165050.bak @@ -0,0 +1,9 @@ +{"type":"meta","next_id":{"DSC":9,"AGD":9,"DEC":5,"PLN":5,"LSN":24,"CLSN":1}} +{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} +{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} diff --git a/discussion/.backups/index.ndjson.20260327-165348.bak b/discussion/.backups/index.ndjson.20260327-165348.bak new file mode 100644 index 00000000..fdd6c2d0 --- /dev/null +++ b/discussion/.backups/index.ndjson.20260327-165348.bak @@ -0,0 +1,9 @@ +{"type":"meta","next_id":{"DSC":9,"AGD":9,"DEC":7,"PLN":5,"LSN":24,"CLSN":1}} +{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} +{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[{"id":"DEC-0005","file":"DEC-0005-pbs-asset-address-surface-and-be-lowering.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"},{"id":"DEC-0006","file":"DEC-0006-pbs-ignored-values-lowering-and-warning.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"}],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} +{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} diff --git a/discussion/index.ndjson b/discussion/index.ndjson index bf4f5ae1..98c81a5a 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,9 +1,9 @@ -{"type":"meta","next_id":{"DSC":9,"AGD":9,"DEC":5,"PLN":5,"LSN":24,"CLSN":1}} +{"type":"meta","next_id":{"DSC":9,"AGD":9,"DEC":7,"PLN":8,"LSN":24,"CLSN":1}} {"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} {"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]} {"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} {"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]} -{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]} +{"type":"discussion","id":"DSC-0006","status":"open","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[{"id":"AGD-0006","file":"AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[{"id":"DEC-0005","file":"DEC-0005-pbs-asset-address-surface-and-be-lowering.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"},{"id":"DEC-0006","file":"DEC-0006-pbs-ignored-values-lowering-and-warning.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-03-27","ref_agenda":"AGD-0006"}],"plans":[{"id":"PLN-0005","file":"PLN-0005-pbs-asset-address-surface-spec-propagation.md","status":"review","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0005"]},{"id":"PLN-0006","file":"PLN-0006-pbs-asset-address-surface-implementation.md","status":"review","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0005"]},{"id":"PLN-0007","file":"PLN-0007-pbs-ignored-values-warning-implementation.md","status":"review","created_at":"2026-03-27","updated_at":"2026-03-27","ref_decisions":["DEC-0006"]}],"lessons":[]} {"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} {"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]} diff --git a/discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md b/discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md index 12b9cbe5..ed1421a1 100644 --- a/discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md +++ b/discussion/workflow/agendas/AGD-0006-pbs-game-facing-asset-refs-and-call-result-discard.md @@ -2,10 +2,10 @@ id: AGD-0006 ticket: pbs-game-facing-asset-refs-and-call-result-discard title: PBS Game-Facing Asset References and Ignored Call Result Lowering -status: open +status: accepted created: 2026-03-27 -resolved: -decision: +resolved: 2026-03-27 +decision: DEC-0005, DEC-0006 tags: [compiler, pbs, ergonomics, lowering, runtime, asset-identity, expression-statements] --- @@ -46,9 +46,10 @@ O novo ponto importante é que, para referências a asset, essa “superfície a Ela pode ser tratada como uma projeção simbólica derivada da autoridade operacional já existente no packer: - `PackerRuntimeSnapshot` como fonte operacional coerente do conjunto de assets visíveis; -- Studio como host capaz de sintetizar uma superfície tipada a partir desse snapshot; -- PBS como consumidor dessa superfície simbólica; -- compiler como responsável por lowerar essa superfície para identidade estável de runtime. +- backend/compiler como owner de uma `FESurfaceContext` derivada desse snapshot, sem expor o snapshot bruto ao frontend; +- Studio como IDE que consome e exibe essa superfície, mas não a possui normativamente; +- PBS como consumidor frontend dessa superfície tipada; +- backend/compiler como responsável final por validar e lowerar essa superfície para identidade estável de runtime. O entendimento atual desta discussão mudou um ponto importante do modelo anterior: @@ -174,19 +175,22 @@ Isso impede uma confusão comum: Como diferentes bancos têm semânticas distintas (`tile bank`, `sound bank`, e futuros bancos), o endereçamento de internos é family-specific e provavelmente pertence a uma spec transversal de runtime/banks, não à política básica de asset references. -Também surge uma separação importante entre pipeline de compile e runtime packer: +Tambem surge uma separação importante entre pipeline de compile e runtime packer: - o frontend PBS não deveria consultar o packer diretamente para descobrir a superfície de assets; -- a estrutura simbólica de assets deve chegar ao compile como dado já preparado na borda backend/orquestradora; -- isso significa que o backend de compile precisa transportar para o frontend PBS uma projeção dos assets visíveis; -- essa mesma porta abre precedente para outras estruturas futuras entrarem no frontend via request de compile, em vez de acoplá-lo a serviços externos em tempo de frontend. +- o backend deve expor ao frontend uma `FESurfaceContext` mínima, derivada da autoridade operacional já existente no packer; +- essa `FESurfaceContext` não é o `PackerRuntimeSnapshot` nem transfere ownership da resolução para o frontend; +- o frontend usa a superfície para semântica e tooling locais, enquanto o backend continua responsável por validar o valor concreto e realizar o lowering final; +- essa mesma porta abre precedente para outras estruturas futuras entrarem no frontend por um contrato estável de surface, sem acoplá-lo diretamente a serviços externos. -For the current agenda scope, the minimum compile projection is intentionally small: +For the current agenda scope, the initial `FESurfaceContext` asset payload is intentionally small: -- `address` -- `asset_id` +- `List` + - `address` + - `asset_id` No richer asset payload is required yet for this policy discussion. +For PBS specifically, the frontend-facing fake/public type may also be named `Addressable`, as a homonymous language surface over the backend-owned `FESurfaceContext` payload. Outro recorte importante: @@ -197,33 +201,7 @@ Outro recorte importante: ## Open Questions -- [ ] Referências a asset devem permanecer nomeadas na superfície PBS, mesmo se o lowering resolver parte delas para identidade estável? -- [ ] A superfície simbólica de asset em PBS deve ser derivada explicitamente do `PackerRuntimeSnapshot` mantido pelo packer para o projeto ativo? -- [ ] O enum ou namespace sintético derivado de assets pertence ao Studio como host/tooling, ao packer como serviço, ou a uma fronteira compartilhada formalizada entre ambos? -- [ ] `asset_name` deve ser removido como variável operacional e substituído pelo address normatizado derivado do root do asset? -- [ ] Studio deve adotar esse address como identidade primária visível ao usuário em vez de exibir um nome livre fornecido pelo autor? -- [ ] O address simbólico canônico deve ser derivado do path relativo em `assets/` segmentado como namespace (`assets.foo.bar.baz`)? -- [ ] A superfície `assets...` deve ser normatizada como árvore hierárquica com namespaces intermediários e folhas terminais `Addressable`, em vez de enum flat? -- [ ] A plataforma deve proibir colisões onde um asset terminal também precisaria atuar como namespace-prefixo de outros assets? -- [ ] A projeção de assets consumida pelo frontend PBS deve entrar pelo backend no request de compile, em vez de o frontend consultar diretamente o packer? -- [ ] Quais outras estruturas além de assets podem, no futuro, seguir esse mesmo padrão de entrada BE -> FE no compile? -- [ ] A resolução de `address` para `asset_id` acontece dentro da função pública do SDK, no tipo/símbolo sintetizado (`Addressable` ou equivalente), ou no lowering do compiler antes da chamada? -- [ ] Se existir um tipo público como `Addressable`, ele representa só a superfície simbólica autoral ou já embute a identidade operacional necessária para a chamada low-level? -- [ ] A API pública do SDK deve permanecer centrada em argumentos simbólicos (`address`, `Addressable`) mesmo quando o backend final consome `asset_id`? -- [ ] O compiler deve reescrever chamadas de SDK asset-facing para formas normalizadas por `asset_id`, mantendo a superfície autoral intacta? -- [ ] Como separar, normativamente, a superfície de referência ao `asset` da futura superfície de endereçamento dos members expostos por um `bank` após instalação? -- [ ] Esse contrato de members expostos por `bank` deve viver em spec transversal (`vm-arch`/runtime surface) em vez de ficar embutido na política de asset references do PBS? -- [ ] O descarte de retorno ignorado deve ser uma regra geral de `expression statement`, ou uma exceção localizada para certos callsites? -- [ ] Até onde PBS quer empurrar “surface ergonomics, compiler normalization” como princípio geral para APIs de jogo? -- [ ] Quais casos precisam continuar dinâmicos em runtime e portanto não podem ser lowered agressivamente em compile time? -- [ ] Devemos publicar warnings opcionais para retorno ignorado ou rename-fragile asset references, ou isso fica fora do escopo inicial? - -Open questions still considered active after the current discussion: - -- [ ] Qual é o shape mínimo e normativo do modelo de assets entregue ao compile/LSP além de `address` e `asset_id`, se algum enriquecimento futuro se mostrar necessário? -- [ ] Quais outras estruturas além de assets podem, no futuro, seguir esse mesmo padrão de entrada BE -> FE no compile? -- [ ] O descarte de retorno ignorado deve virar warning geral de `expression statement` com valor, ou warning apenas para superfícies específicas? -- [ ] Quais casos, além de disponibilidade em runtime, realmente precisam permanecer dinâmicos e fora da resolução estática baseada no snapshot? +- [ ] Quais outras estruturas além de assets podem, no futuro, seguir esse mesmo padrão de `FESurfaceContext` BE -> FE? ## Options @@ -304,13 +282,36 @@ Ao mesmo tempo, a discussão de root references passa a ter três frentes explí No momento, a direção técnica mais forte para essa ponte é: -- `Addressable` permanece como superfície simbólica de autoria; +- `Addressable` permanece como a surface simbólica de autoria do PBS; +- a `FESurfaceContext` mínima de assets carrega uma `List`, cujas entradas são compostas por `address` e `asset_id`; +- o frontend PBS usa um tipo fake homônimo `Addressable` para consumir essa surface de forma editorial e tipada; - `declare host` asset-backed recebe metadata reservada como `[AssetLowering(param = N)]`; -- o compiler resolve esse parâmetro durante o lowering da chamada host-backed; +- o backend continua validando o valor concreto e resolve esse parâmetro durante o lowering da chamada host-backed; - `declare service` público permanece apenas como wrapper ergonômico sobre esse contrato. +Additional convergence already accepted in this discussion: + +1. the v1 `FESurfaceContext` asset shape is limited to `List`; +2. ignored call results in `expression statement` follow a general lowering rule in v1 and SHOULD also emit a warning in the first version; +3. asset-facing references should be resolved at compile time whenever possible; no runtime-dynamic exception is currently required for this policy; +4. future editorial refinement may tune warning policy severity or suppression rules, but the baseline v1 direction already includes an `ignored values` warning. + ## Resolution +Accepted on 2026-03-27. + +This agenda now resolves into two sibling decisions: + +1. `DEC-0005` for PBS asset address surface, `FESurfaceContext`, and backend-owned `Addressable` lowering. +2. `DEC-0006` for ignored values general lowering and warning policy. + +What is now locked: + +1. PBS asset-facing authoring is symbolic and based on `Addressable`. +2. The backend exposes a minimal `FESurfaceContext` with `List`. +3. The backend remains owner of final validation and lowering to runtime-facing `asset_id`. +4. Ignored values in `expression statement` follow a general lowering rule and emit a warning in v1. + Direção recomendada por enquanto: 1. tratar os dois temas como uma única discussão de política de surface-versus-lowering em PBS; diff --git a/discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md b/discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md new file mode 100644 index 00000000..bd0241c2 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0005-pbs-asset-address-surface-and-be-lowering.md @@ -0,0 +1,147 @@ +--- +id: DEC-0005 +ticket: pbs-game-facing-asset-refs-and-call-result-discard +title: PBS Asset Address Surface and Backend-Lowered Addressable Resolution +status: accepted +created: 2026-03-27 +accepted: 2026-03-27 +agenda: AGD-0006 +plans: [PLN-0005, PLN-0006] +tags: [compiler, pbs, ergonomics, lowering, runtime, asset-identity, asset-surface, be-fe-contract] +--- + +## Context + +PBS precisava fechar a superfície author-facing de referência a assets depois que `DSC-0008` fixou a base low-level em `LowAssets` e no contrato runtime `asset_id + slot`. + +O ponto restante já não era o ABI low-level. +O ponto restante era como a autoria em PBS referencia assets de forma ergonômica sem reintroduzir lookup tardio por `asset_name`, sem acoplar o frontend diretamente ao packer, e sem mover para o frontend a ownership do lowering final. + +O estado aceito desta discussão também reconhece que: + +- o packer continua sendo a autoridade operacional do conjunto de assets; +- o backend do compiler expõe ao frontend apenas uma surface derivada, não o `PackerRuntimeSnapshot` bruto; +- o backend permanece owner da validação final do valor concreto e do lowering `address -> asset_id`. + +## Decision + +PBS SHALL adotar uma superfície author-facing baseada em `Addressable` e em addresses canônicos derivados do path relativo do asset root dentro de `assets/`. + +O shape canônico da autoria PBS SHALL seguir uma árvore hierárquica: + +- `assets` como namespace raiz; +- namespaces intermediários para prefixos estruturais; +- folhas terminais representando assets reais como valores `Addressable`. + +O address simbólico SHALL ser derivado do path relativo do asset root e SHALL substituir `asset_name` como identidade operacional de referência para compile-time asset lookup. + +O compiler backend SHALL expor ao frontend uma `FESurfaceContext` derivada da surface operacional do backend. +Para v1, essa `FESurfaceContext` SHALL carregar apenas: + +- `List` + +em que cada entrada `Addressable` contém: + +- `address` +- `asset_id` + +O frontend PBS MAY usar um tipo fake/public homônimo `Addressable` como surface editorial e de semântica local. +Esse tipo frontend-owned MUST NOT transferir ao frontend a responsabilidade de validação final ou de lowering operacional. + +O backend SHALL continuar responsável por: + +- validar o valor concreto referenciado no programa; +- resolver `address -> asset_id`; +- realizar o lowering final para o contrato low-level já fixado em `LowAssets`. + +PBS asset-facing APIs SHOULD permanecer simbólicas na surface pública. +Quando uma chamada exigir lowering asset-aware, o contrato host-backed SHALL carregar metadata reservada de lowering, e o backend SHALL usar essa metadata para reescrever a chamada para a forma operacional em `asset_id`. + +PBS MUST NOT consultar o packer diretamente a partir do frontend para descobrir assets visíveis. + +PBS MUST NOT tratar `asset` como superfície de addressing de membros internos carregados em runtime. +O contrato de members expostos por `bank` SHALL permanecer separado da política de asset references. + +Asset-facing references SHOULD be resolved at compile time whenever possible. +For the current policy, no runtime-dynamic exception is required. + +## Rationale + +Essa decisão preserva três fronteiras importantes ao mesmo tempo: + +1. ergonomia de autoria no source; +2. autoridade operacional no backend; +3. lowering final alinhado ao runtime já consolidado. + +Ela evita o pior dos dois extremos: + +- um frontend cego que não consegue oferecer semântica/tooling razoáveis; +- ou um frontend acoplado ao packer e responsável por decisões que pertencem ao backend. + +O uso de `Addressable` como nome em ambos os lados é aceitável porque: + +- no backend, ele representa a entrada da `FESurfaceContext`; +- no PBS, ele representa a surface editorial/fake type consumida pelo frontend. + +O nome é homônimo, mas a ownership continua explícita: + +- a surface chega do backend; +- a validação final e o lowering permanecem no backend. + +## Technical Specification + +### 1. Canonical Authoring Surface + +- PBS SHALL treat `assets` as a compile-time hierarchical namespace root. +- A terminal asset root SHALL map to a terminal `Addressable` leaf. +- Intermediate namespace nodes MUST NOT be treated as terminal assets. +- A terminal asset path MUST NOT also act as a namespace prefix for descendant assets. + +### 2. Canonical Address Identity + +- The canonical symbolic identity SHALL be the normalized address derived from the asset root path under `assets/`. +- `asset_name` MUST NOT remain the operational compile-time identity for asset lookup. +- Rename or move operations MAY change the canonical address and thereby invalidate compile-time references. + +### 3. Backend-To-Frontend Surface Contract + +- The backend SHALL expose a `FESurfaceContext` to the frontend. +- The v1 asset slice of that context SHALL be `List`. +- The frontend MAY use this surface for parsing-adjacent semantics, typing, diagnostics, and tooling. +- The frontend MUST NOT be treated as the canonical resolver of operational asset identity. + +### 4. Lowering Ownership + +- Asset-aware lowering metadata SHALL be carried on the host-backed declaration surface. +- The backend SHALL validate the referenced `Addressable` value against the backend-owned surface. +- The backend SHALL lower the symbolic asset reference to the runtime-facing `asset_id`. +- The resulting low-level call SHALL target the `LowAssets` contract already fixed by `DEC-0004`. + +### 5. Scope Boundary + +This decision covers: + +- symbolic asset references in PBS source; +- the minimal backend-to-frontend surface contract for assets; +- backend ownership of final validation and lowering. + +This decision does NOT cover: + +- bank-internal member addressing; +- richer future `FESurfaceContext` structures beyond assets; +- suppression or editorial warning policy for rename fragility; +- the low-level `LowAssets` ABI itself, already fixed elsewhere. + +## Constraints + +- The frontend MUST NOT query packer services directly for asset discovery. +- The backend MUST NOT expose the raw `PackerRuntimeSnapshot` as the frontend contract. +- The backend-to-frontend contract MUST remain small and explicitly extensible. +- The source-level `Addressable` surface MUST preserve the backend as owner of executable semantics. +- Any future richer asset APIs MUST still lower into backend-resolved `asset_id` before the final `LowAssets` host call. + +## Revision Log + +- 2026-03-27: Initial accepted decision from AGD-0006. +- 2026-03-27: Locked `FESurfaceContext` v1 asset shape to `List`. +- 2026-03-27: Locked backend ownership of final `Addressable` validation and lowering. diff --git a/discussion/workflow/decisions/DEC-0006-pbs-ignored-values-lowering-and-warning.md b/discussion/workflow/decisions/DEC-0006-pbs-ignored-values-lowering-and-warning.md new file mode 100644 index 00000000..a1986aa7 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0006-pbs-ignored-values-lowering-and-warning.md @@ -0,0 +1,88 @@ +--- +id: DEC-0006 +ticket: pbs-game-facing-asset-refs-and-call-result-discard +title: PBS Ignored Values Lowering and Warning Policy +status: accepted +created: 2026-03-27 +accepted: 2026-03-27 +agenda: AGD-0006 +plans: [PLN-0007] +tags: [compiler, pbs, ergonomics, lowering, diagnostics, expression-statements, warnings] +--- + +## Context + +PBS ainda precisava fixar o comportamento de `expression statements` cujo valor produzido não é consumido. + +Sem essa decisão, a disciplina de stack do backend continua vazando para a surface do autor: + +- alguns callsites com retorno materializado ficam semanticamente ambíguos; +- a política de descarte pode ficar implícita demais ou inconsistente entre passes; +- o usuário não recebe feedback claro quando ignora um valor que a linguagem materializou. + +Essa discussão não exige uma exceção por API específica. +Ela exige uma regra geral de linguagem com lowering e diagnóstico previsíveis. + +## Decision + +PBS SHALL adotar uma regra geral para ignored values em `expression statement`. + +Quando uma expressão usada como statement produzir um valor materializado que não seja consumido, o compiler SHALL: + +1. lowerar explicitamente o descarte desse valor; +2. emitir um warning na v1. + +Essa política SHALL ser geral, e não uma exceção localizada para certos callsites ou certas superfícies de API. + +O warning inicial SHALL existir como baseline diagnóstica da linguagem. +Refinamentos futuros de severidade, suppressions ou subcategorias MAY acontecer depois, mas não bloqueiam esta decisão. + +## Rationale + +Essa regra resolve a tensão principal da agenda: + +- a autoria continua simples, porque o usuário pode escrever uma expressão como statement; +- o protocolo executável continua explícito, porque o compiler assume o descarte; +- a linguagem continua honesta, porque o usuário recebe um warning quando ignora um valor material. + +Isso é superior a duas alternativas piores: + +- exigir consumo explícito de todo valor sempre, empurrando ruído operacional para o source; +- ou descartar silenciosamente tudo, removendo feedback útil em situações potencialmente equivocadas. + +## Technical Specification + +### 1. General Rule + +- Any PBS `expression statement` that produces a materialized value and does not consume it SHALL trigger ignored-value handling. +- Ignored-value handling SHALL consist of: + - explicit lowering for value discard; + - a warning diagnostic. + +### 2. Scope + +- The rule SHALL apply generally across expression statements. +- The rule MUST NOT be restricted to asset-facing APIs, host-backed calls, or any single subsystem. +- The rule MAY apply equally to pure or impure expressions if the language surface materializes a value that is then ignored. + +### 3. Lowering Ownership + +- The compiler backend SHALL remain responsible for the executable lowering that discards the value. +- Frontend diagnostics MAY identify the situation earlier if architecture permits, but the normative executable behavior remains compiler-owned. + +### 4. Diagnostic Policy + +- The baseline v1 diagnostic level SHALL be warning. +- Future work MAY define suppression mechanisms, lint categories, escalation rules, or context-sensitive exemptions. +- No such refinement is required to consider this decision accepted. + +## Constraints + +- PBS MUST keep the rule general and easy to explain. +- PBS MUST NOT depend on backend stack discipline leaking into source-level author decisions. +- PBS MUST NOT require API-by-API bespoke ignored-value semantics as the baseline language policy. + +## Revision Log + +- 2026-03-27: Initial accepted decision from AGD-0006. +- 2026-03-27: Locked ignored values as a general lowering rule with warning severity in v1. diff --git a/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md b/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md new file mode 100644 index 00000000..4b745fd0 --- /dev/null +++ b/discussion/workflow/plans/PLN-0005-pbs-asset-address-surface-spec-propagation.md @@ -0,0 +1,152 @@ +--- +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: review +created: 2026-03-27 +completed: +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` 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`; +- 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. diff --git a/discussion/workflow/plans/PLN-0006-pbs-asset-address-surface-implementation.md b/discussion/workflow/plans/PLN-0006-pbs-asset-address-surface-implementation.md new file mode 100644 index 00000000..836c4b6e --- /dev/null +++ b/discussion/workflow/plans/PLN-0006-pbs-asset-address-surface-implementation.md @@ -0,0 +1,184 @@ +--- +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: review +created: 2026-03-27 +completed: +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` 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(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` 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. diff --git a/discussion/workflow/plans/PLN-0007-pbs-ignored-values-warning-implementation.md b/discussion/workflow/plans/PLN-0007-pbs-ignored-values-warning-implementation.md new file mode 100644 index 00000000..12d2aa85 --- /dev/null +++ b/discussion/workflow/plans/PLN-0007-pbs-ignored-values-warning-implementation.md @@ -0,0 +1,151 @@ +--- +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.