asset addressable PBS surface
This commit is contained in:
parent
afd59d04f4
commit
124c6d078e
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
9
discussion/.backups/index.ndjson.20260327-165050.bak
Normal file
9
discussion/.backups/index.ndjson.20260327-165050.bak
Normal file
@ -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"}]}
|
||||
9
discussion/.backups/index.ndjson.20260327-165348.bak
Normal file
9
discussion/.backups/index.ndjson.20260327-165348.bak
Normal file
@ -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"}]}
|
||||
@ -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"}]}
|
||||
|
||||
@ -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<Addressable>`
|
||||
- `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<Addressable>`, 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<Addressable(address, asset_id)>`;
|
||||
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<Addressable(address, asset_id)>`.
|
||||
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;
|
||||
|
||||
@ -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<Addressable>`
|
||||
|
||||
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<Addressable(address, asset_id)>`.
|
||||
- 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<Addressable(address, asset_id)>`.
|
||||
- 2026-03-27: Locked backend ownership of final `Addressable` validation and lowering.
|
||||
@ -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.
|
||||
@ -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<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.
|
||||
@ -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<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.
|
||||
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user