dev/ajustments-asset-entry (#12)
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

Reviewed-on: #12
Co-authored-by: bQUARKz <bquarkz@gmail.com>
Co-committed-by: bQUARKz <bquarkz@gmail.com>
This commit was merged in pull request #12.
This commit is contained in:
2026-04-10 05:31:57 +00:00
committed by bquarkz
parent c4aca95635
commit 035e9d5676
32 changed files with 584 additions and 813 deletions
+20 -19
View File
@@ -1,22 +1,23 @@
{"type":"meta","next_id":{"DSC":21,"AGD":19,"DEC":3,"PLN":3,"LSN":21,"CLSN":1}}
... (mantendo as linhas anteriores) ...
{"type":"meta","next_id":{"DSC":23,"AGD":21,"DEC":7,"PLN":6,"LSN":26,"CLSN":1}}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"workflow/agendas/AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"workflow/decisions/DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"workflow/plans/PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"asset-entry-codec-enum-with-metadata","title":"Asset Entry Codec Enum Contract","created_at":"2026-04-09","updated_at":"2026-04-09","tags":["asset","runtime","codec","metadata"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"lessons/DSC-0021-asset-entry-codec-enum-contract/LSN-0024-string-on-the-wire-enum-in-runtime.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"open","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0007","file":"AGD-0007-perf-runtime-telemetry-hot-path.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0013","status":"open","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0012","file":"AGD-0012-perf-host-debug-overlay-isolation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"open","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0015","file":"AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0017","status":"open","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0016","file":"AGD-0016-asset-entry-metadata-normalization-contract.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0001","file":"workflow/agendas/AGD-0001-runtime-edge-test-plan.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"workflow/agendas/AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"workflow/agendas/AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"workflow/agendas/AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"workflow/agendas/AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0008","status":"open","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0007","file":"workflow/agendas/AGD-0007-perf-runtime-telemetry-hot-path.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0009","status":"open","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0008","file":"workflow/agendas/AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"open","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0009","file":"workflow/agendas/AGD-0009-perf-host-desktop-frame-pacing-and-presentation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0011","status":"open","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0010","file":"workflow/agendas/AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0012","status":"open","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0011","file":"workflow/agendas/AGD-0011-perf-runtime-introspection-syscalls.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0013","status":"open","ticket":"perf-host-debug-overlay-isolation","title":"Agenda - [PERF] Host Debug Overlay Isolation","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0012","file":"workflow/agendas/AGD-0012-perf-host-debug-overlay-isolation.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0014","status":"open","ticket":"perf-vm-allocation-and-copy-pressure","title":"Agenda - [PERF] VM Allocation and Copy Pressure","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0013","file":"workflow/agendas/AGD-0013-perf-vm-allocation-and-copy-pressure.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0015","status":"open","ticket":"perf-cartridge-boot-and-program-ownership","title":"Agenda - [PERF] Cartridge Boot and Program Ownership","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0014","file":"workflow/agendas/AGD-0014-perf-cartridge-boot-and-program-ownership.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0016","status":"done","ticket":"tilemap-empty-cell-vs-tile-id-zero","title":"Tilemap Empty Cell vs Tile ID Zero","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0015","file":"workflow/agendas/AGD-0015-tilemap-empty-cell-vs-tile-id-zero.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"lessons/DSC-0016-tilemap-empty-cell-semantics/LSN-0022-tilemap-empty-cell-convergence.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0017","status":"done","ticket":"asset-entry-metadata-normalization-contract","title":"Asset Entry Metadata Normalization Contract","created_at":"2026-03-27","updated_at":"2026-04-09","tags":[],"agendas":[{"id":"AGD-0016","file":"workflow/agendas/AGD-0016-asset-entry-metadata-normalization-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-04-09"}],"decisions":[{"id":"DEC-0004","file":"workflow/decisions/DEC-0004-asset-entry-metadata-normalization-contract.md","status":"accepted","created_at":"2026-04-09","updated_at":"2026-04-09"}],"plans":[],"lessons":[{"id":"LSN-0023","file":"lessons/DSC-0017-asset-metadata-normalization/LSN-0023-typed-asset-metadata-helpers.md","status":"done","created_at":"2026-04-09","updated_at":"2026-04-09"}]}
{"type":"discussion","id":"DSC-0018","status":"done","ticket":"asset-load-asset-id-int-contract","title":"Asset Load Asset ID Int Contract","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["asset","runtime","abi"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0019","file":"lessons/DSC-0018-asset-load-asset-id-int-contract/LSN-0019-asset-load-id-abi-convergence.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"jenkinsfile-correction","title":"Jenkinsfile Correction and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins"],"agendas":[{"id":"AGD-0017","file":"workflow/agendas/AGD-0017-jenkinsfile-correction.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0002","file":"workflow/decisions/DEC-0002-jenkinsfile-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0002","file":"workflow/plans/PLN-0002-jenkinsfile-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0020","file":"lessons/DSC-0019-jenkins-ci-standardization/LSN-0020-jenkins-standard-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
@@ -123,7 +123,7 @@ The current asset model works better if you do not treat every bank as equally g
Some banks are specialized:
- `TILES`
- `GLYPH`
- `SOUNDS`
For these, the bank contract already carries most of the important format rules. That means:
@@ -163,7 +163,7 @@ It does not say:
One of the most important asset-management lessons in the current runtime is that `codec = NONE` does not mean "bitwise identical to in-memory layout".
The tile-bank path is the concrete example:
The glyph-bank path is the concrete example:
- there is no additional generic codec layer for the asset;
- the serialized payload stores indexed pixels as packed `4bpp`;
@@ -182,13 +182,13 @@ That is why `AssetEntry.size` and `AssetEntry.decoded_size` must be thought of a
If those two numbers are treated as interchangeable, telemetry, budgets, and validation all become misleading.
## Tile Banks Teach The Real Boundary
## Glyph Banks Teach The Real Boundary
Tile banks are useful because they show the real separation of concerns:
Glyph banks are useful because they show the real separation of concerns:
- `assets.pa` defines the serialized envelope and metadata needed to reconstruct the bank;
- the runtime validates that metadata against the expected v1 contract;
- the resident `TileBank` is a runtime object, not a direct view over the cold bytes.
- the resident `GlyphBank` is a runtime object, not a direct view over the cold bytes.
This is the right PROMETEU mental model:
@@ -18,7 +18,7 @@ PROMETEU treats graphics as an explicit peripheral, not as a modern GPU.
The right mental model is a retro 2D machine with:
- framebuffer;
- tile banks;
- glyph banks;
- tile layers;
- sprites ordered by draw order;
- deterministic composition per frame.
@@ -67,7 +67,7 @@ That enables:
- HUD themes;
- day and night cycles.
In the current tile-bank v1 baseline, this palette model is intentionally bounded:
In the current glyph-bank v1 baseline, this palette model is intentionally bounded:
- each bank carries `64` palettes;
- each palette carries `16` colors;
@@ -75,7 +75,7 @@ In the current tile-bank v1 baseline, this palette model is intentionally bounde
That limit is not incidental bookkeeping. It is part of how art packaging, runtime validation, and rendering stay aligned.
## Tile Banks Are Decoded Runtime Objects
## Glyph Banks Are Decoded Runtime Objects
The most useful intuition is to separate three layers:
@@ -83,13 +83,13 @@ The most useful intuition is to separate three layers:
- serialized cart payload;
- resident runtime bank.
For tile banks in v1:
For glyph banks in v1:
- authored pixels are logical indices `0..15`;
- serialized payload stores those indices as packed `4bpp`;
- runtime memory expands them to one `u8` index per pixel after decode.
So when reading the graphics model, do not imagine the renderer reading packed nibbles directly from cartridge storage. The renderer consumes a decoded `TileBank` object whose memory shape is optimized for runtime lookup, not for transport density.
So when reading the graphics model, do not imagine the renderer reading packed nibbles directly from cartridge storage. The renderer consumes a decoded `GlyphBank` object whose memory shape is optimized for runtime lookup, not for transport density.
## Use Cases
@@ -0,0 +1,20 @@
# LSN-0022: Tilemap Empty Cell Semantics and Glyph Convergence
## Context
During the initial runtime design, `tile_id = 0` was used as a sentinel value for "empty" or "missing" tiles in tilemaps. However, as the asset banking and packer systems evolved, it became clear that `0` should be a valid index for any asset bank, including glyph banks. This conflict was formally tracked in `AGD-0015`.
## Lessons Learned
### 1. Explicit Presence Over Magic Values
Modeling absence with a magic value (like `tile_id = 0`) creates friction when that value is also a valid member of the domain (index 0). The project moved towards explicit presence checks.
### 2. Convergence During Parallel Implementation
The resolution of the tilemap empty cell semantics (moving to explicit presence) was crystallized during the implementation of the `glyph` system. Instead of maintaining two different ways of handling "empty" slots, the tilemap logic was harmonized with the newer, cleaner approach used for glyphs and other render paths.
### 3. Impact on Render Pipeline
By allowing `tile_id = 0` to be a valid tile, the render pipeline now relies on a separate bit or `Option`-like structure to determine if a cell should be drawn. This makes the code more robust and the asset indices more intuitive.
## References
- Discussion: `DSC-0016`
- Agenda: `AGD-0015` (Tilemap Empty Cell vs Tile ID Zero)
- Implementation: Glyph system integration
@@ -0,0 +1,33 @@
# LSN-0023: Typed Helpers for Asset Metadata
Status: Published
Decisions: [[DEC-0004]]
Tags: [asset, runtime, rust, pattern]
## Contexto
A decisão [[DEC-0004]] estabeleceu um contrato de metadados segmentados para assets, mantendo campos críticos na raiz do JSON e detalhes técnicos em subárvores (`codec`, `pipeline`). No entanto, o `AssetEntry.metadata` no runtime é um `serde_json::Value` dinâmico.
## Lição
O uso de `serde_json::Value` diretamente nos loaders do runtime introduz riscos de runtime (erros de tipo, campos ausentes) e polui o código com chamadas repetitivas de `.get()`, `.as_u64()`, etc.
### Abordagem Adotada
Para mitigar isso, implementamos o padrão de **Typed Metadata Helpers**:
1. **Structs Dedicadas**: Criamos structs Rust (ex: `GlyphsMetadata`, `SoundsMetadata`) que representam o contrato exato de cada banco.
2. **Conversion Methods**: Adicionamos métodos ao `AssetEntry` (ex: `metadata_as_glyphs()`) que utilizam `serde_json::from_value` para realizar o "cast" do JSON dinâmico para a struct tipada.
3. **Fail-Fast**: A falha no parsing dos metadados deve ser tratada como erro de carregamento do asset, garantindo que o motor não opere com metadados corrompidos ou incompletos.
### Benefícios
- **Segurança de Tipo**: Erros de estrutura de metadados são detectados no momento do carregamento.
- **Ergonomia**: O código dos drivers passa a usar `meta.tile_size` em vez de parsing manual.
- **Desacoplamento**: A complexidade do JSON fica encapsulada nos helpers de conversão.
## Referências
- DEC-0004: Asset Entry Metadata Normalization Contract
- `prometeu-hal/src/asset.rs`
- `prometeu-drivers/src/asset.rs`
@@ -0,0 +1,45 @@
---
id: LSN-0024
ticket: asset-entry-codec-enum-with-metadata
title: String on the Wire, Enum in the Runtime
created: 2026-04-09
tags: [asset, runtime, codec, rust, contract]
---
## Context
This discussion closed the contract for `AssetEntry.codec` in the runtime asset model. The system already serialized `assets.pa` as JSON produced by the Studio in Java, while the runtime consumed that JSON in Rust. The original runtime model kept `codec` as a free-form `String`, which allowed legacy aliases such as `RAW` and pushed validation and branching into scattered string comparisons.
The implemented change moved the runtime to a typed enum while preserving the existing transport simplicity of the pack format.
## Key Decisions
### Asset Entry Codec Enum Contract
**What:**
Keep `codec` as a JSON string in `assets.pa`, but deserialize it directly into a Rust enum in `AssetEntry`. The initial codec set contains only `None`, serialized canonically as `NONE` in `SCREAMING_SNAKE_CASE`.
**Why:**
This preserves a simple cross-language wire contract for the Studio packer while making the runtime honest about the domain model it operates on. The loader now rejects unknown codecs early, and runtime consumers branch on enum variants instead of raw strings.
**Trade-offs:**
The runtime loses open-ended tolerance for arbitrary codec names, which is intentional. Future codecs with payload-specific metadata still require a dedicated follow-up decision once a real codec exists.
## Patterns and Algorithms
- Use a stable textual discriminant on the wire and a typed enum in the runtime model.
- Let deserialization enforce the supported variant set instead of adding compatibility shims deeper in the execution path.
- Keep the discriminant contract canonical across producers and consumers; do not allow per-producer aliases.
- Preserve editorial or bank-specific metadata outside the codec discriminant so future codec payload metadata can be added without collapsing the whole asset model into an untyped blob.
## Pitfalls
- A runtime that accepts legacy aliases such as `RAW` keeps historical ambiguity alive and makes it harder to reason about the true contract.
- If fixtures are constructed directly in tests, typed metadata helpers can expose missing required fields that were previously masked by weaker validation.
- Cross-language contracts become fragile if the wire spelling is not explicitly canonized. The producer must conform exactly to the runtime contract.
## Takeaways
- Use a string on the wire when cross-language transport simplicity matters, but deserialize into an enum as soon as the runtime needs semantic guarantees.
- Canonical spelling belongs to the shared contract, not to whichever producer happens to serialize first.
- Rejecting unknown codec values at asset-entry validation time keeps failures local, early, and easier to debug.
@@ -0,0 +1,45 @@
---
id: LSN-0025
ticket: tile-bank-vs-glyph-bank-domain-naming
title: Rename Artifact by Meaning, Not by Token
created: 2026-04-10
tags: [gfx, runtime, naming, refactor, documentation]
---
## Context
The runtime used `TileBank` as the name of the concrete graphical bank artifact while also using `tile` for map, layer, and geometric concepts such as `TileLayer`, `TileMap`, and `TileSize`. This overloaded the term `tile` across two different meanings.
The implemented migration renamed only the concrete bank artifact to `GlyphBank` and renamed the corresponding asset-bank contract from `BankType::TILES` to `BankType::GLYPH`, while explicitly preserving `TileLayer`, `TileMap`, and `TileSize`.
## Key Decisions
### Glyph Bank Domain Naming Contract
**What:**
Rename the concrete graphical bank artifact and its runtime interfaces to `GlyphBank`, but keep tile-domain structures unchanged where `tile` still correctly describes layers, maps, grids, and geometry.
**Why:**
The goal was domain clarity, not behavior change. The project needed a more precise name for the concrete graphical bank without reopening rendering architecture or erasing valid uses of `tile`.
**Trade-offs:**
This requires more care than a blind search-and-replace. The migration is broader editorially, but safer semantically, because it avoids damaging concepts that still belong in the tile domain.
## Patterns and Algorithms
- Rename by artifact meaning, not by string token frequency.
- When a term is overloaded, split the rename along domain boundaries instead of trying to enforce total lexical uniformity.
- Let the runtime contract adopt the new canonical artifact name (`GlyphBank`, `BankType::GLYPH`) while preserving existing terms for excluded concepts (`TileLayer`, `TileMap`, `TileSize`).
- Apply the same semantic rule to docs and lessons, not only to code.
## Pitfalls
- Blind replacement would have incorrectly renamed tile-layer and tile-size concepts that were intentionally out of scope.
- Partial renames create mixed vocabulary, which is worse than either old or new terminology used consistently.
- Historical documentation is especially easy to corrupt if rewritten mechanically instead of by artifact meaning.
## Takeaways
- A naming refactor can be rename-only in behavior while still requiring architectural discipline in wording.
- Use one canonical name per artifact, but do not force unrelated domains to share that rename.
- Documentation migrations should follow the same semantic boundary as code migrations, or the codebase will drift back into conceptual ambiguity.
@@ -1,110 +0,0 @@
---
id: AGD-0015
ticket: tilemap-empty-cell-vs-tile-id-zero
title: Tilemap Empty Cell vs Tile ID Zero
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Tilemap Empty Cell vs Tile ID Zero
## Contexto
O runtime hoje usa `tile.id == 0` como atalho para "tile ausente" no caminho de render de tilemap.
Ao mesmo tempo, o contrato de `tile bank` em evolucao no packer quer permitir que `tile_id = 0` seja um tile real e valido dentro do bank.
Isso cria conflito direto entre:
- semantica atual do tilemap no runtime;
- e o contrato de packing/runtime asset bank que trata `tile_id` como indice valido do bank desde zero.
## Problema
Precisamos decidir qual e a semantica correta para representar ausencia de tile em tilemaps.
Hoje o comportamento implicito e:
- `tile.id == 0` significa "nao desenhar";
- portanto o tile de indice `0` no bank fica inutilizavel no caminho de tilemap;
- sprites, por outro lado, nao carregam a mesma semantica implicita de vazio.
Isso deixa o modelo inconsistente:
1. o mesmo `tile_id` nao significa a mesma coisa em todos os consumidores;
2. o bank `TileBank` nao explicita reserva de `tile_id = 0`;
3. o packer teria que compensar uma regra de consumidor que nao esta modelada no contrato do asset bank.
## Pontos Criticos
- `tile_id` deve representar um indice valido no bank, nao um sentinel escondido, sempre que possivel;
- ausencia de tile e um conceito de tilemap/layer, nao necessariamente de bank asset;
- usar indices fora da faixa como sentinel tende a piorar validacao e debug;
- mudar o shape do tilemap pode ter custo de ABI/runtime, mas pode deixar o contrato mais honesto;
- manter o comportamento atual preserva compatibilidade local, mas cristaliza uma semantica implicita fraca.
## Opcoes
### Opcao A - Manter `tile.id == 0` como empty sentinel
O runtime segue tratando `tile_id = 0` como ausencia de tile no tilemap.
Consequencia:
- o primeiro tile real do bank precisaria comecar em `1` para o caminho de tilemap;
- o packer precisaria compensar isso;
- sprites e tilemaps continuariam com semanticas diferentes para o mesmo id.
### Opcao B - Tornar vazio explicito no tilemap model
O tilemap passa a representar vazio explicitamente, por exemplo com:
- `Option<Tile>`;
- ou `Tile { active/present, ... }`.
Consequencia:
- `tile_id = 0` volta a ser um tile valido no bank;
- ausencia de tile deixa de depender de valor especial do id;
- o runtime fica semanticamente mais consistente.
### Opcao C - Usar sentinel fora da faixa valida
O tilemap passa a tratar um `tile_id >= tile_capacity` como "empty".
Consequencia:
- evita usar `0` como sentinel;
- mas cria acoplamento ruim entre tilemap e capacidade do bank;
- e torna a validacao mais fragil e menos didatica.
## Sugestao / Recomendacao
Adotar `Opcao B`.
Ausencia de tile deve ser modelada explicitamente no tilemap/layer, e nao por um `tile_id` especial.
Direcao recomendada:
1. `tile_id` deve significar apenas "indice do tile no bank";
2. `tile_id = 0` deve ser permitido como tile real;
3. tilemaps devem ter vazio explicito no proprio modelo;
4. o render do tilemap deve testar esse estado explicito, nao `tile.id == 0`.
## Perguntas em Aberto
1. Qual shape e melhor para o primeiro wave:
`Option<Tile>` ou `Tile` com flag `active/present`?
2. Essa mudanca afeta apenas o tilemap path ou tambem deve harmonizar outros consumidores do modelo `Tile`?
3. Precisamos de estrategia de compatibilidade/migracao para codigo e testes que hoje assumem `tile.id == 0` como vazio?
## Criterio para Encerrar
Esta agenda pode ser encerrada quando houver decisao clara sobre:
- como vazio e representado no tilemap;
- se `tile_id = 0` volta a ser indice valido universal do bank;
- e quais pontos de spec/codigo do runtime precisam de propagacao.
@@ -1,100 +0,0 @@
---
id: AGD-0016
ticket: asset-entry-metadata-normalization-contract
title: Asset Entry Metadata Normalization Contract
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Asset Entry Metadata Normalization Contract
Status: Open
Domain Owner: `docs/runtime`
Cross-Domain Impact: `../studio/docs/packer`, `shipper`, `asset` loader
## Purpose
Normatizar como `AssetEntry.metadata` deve preservar a convergencia entre metadata autoral, metadata de codec e metadata de pipeline sem colapsar tudo num mapa plano ambiguo.
## Problem
O lado produtor (`packer`) ja convergiu para um contrato em que o runtime precisa ler campos obrigatorios diretamente de `AssetEntry.metadata`, mas tambem precisa manter segmentacao suficiente para nao perder significado entre:
- `asset.json.output.metadata`
- `asset.json.output.codec_configuration`
- `asset.json.output.pipeline`
Sem um contrato explicito no runtime:
- o packer pode materializar estruturas diferentes entre formatos;
- o loader/runtime pode passar a depender de flattening incidental;
- tooling e debug surfaces perdem previsibilidade;
- futuros formatos tendem a misturar metadata efetiva com detalhe interno de pipeline.
## Context
No ciclo atual de `tile bank`, o produtor ja fechou esta direcao:
- `asset.json.output.metadata` -> `AssetEntry.metadata`
- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec`
- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline`
Ao mesmo tempo, o runtime ainda consome alguns campos obrigatorios do tile bank diretamente no nivel raiz de `AssetEntry.metadata`, em especial:
- `tile_size`
- `width`
- `height`
- `palette_count`
A agenda precisa fechar se esse shape vira contrato geral de runtime para metadata normalizada de assets, e como o consumidor deve tratar campos obrigatorios format-specific versus subtrees segmentadas.
## Options
### Option A - Flat effective metadata map only
Tudo converge para um unico mapa plano em `AssetEntry.metadata`.
### Option B - Root effective metadata plus stable segmented subtrees
Campos runtime-obrigatorios ficam legiveis no nivel raiz, enquanto dados de codec e pipeline ficam em subtrees estaveis:
- `metadata.<field>`
- `metadata.codec.<field>`
- `metadata.pipeline.<field>`
### Option C - Fully segmented metadata only
Nada fica no nivel raiz; todo consumo passa por subtrees por origem.
## Tradeoffs
- Option A simplifica leitura curta, mas perde origem semantica e aumenta risco de colisao.
- Option B preserva leitura direta para campos obrigatorios do runtime e mantem segmentacao estavel para evolucao futura.
- Option C e semanticamente limpa, mas quebra o consumo direto atual de formatos como `tile bank` e introduz custo de migracao desnecessario agora.
## Recommendation
Adotar `Option B`.
Direcao recomendada:
- campos format-specific obrigatorios para decode/runtime continuam legiveis no nivel raiz de `AssetEntry.metadata`;
- `output.codec_configuration` materializa em `AssetEntry.metadata.codec`;
- `output.pipeline` materializa em `AssetEntry.metadata.pipeline`;
- o runtime nao deve exigir flattening total para consumir metadata segmentada;
- specs format-specific devem declarar explicitamente quais campos sao obrigatorios no nivel raiz.
## Open Questions
1. O contrato deve tratar o subtree raiz como semanticamente equivalente a `output.metadata` ou como effective metadata map mais amplo?
2. Quais readers/helpers do runtime devem ser criados para evitar parsing manual disperso de `metadata.codec` e `metadata.pipeline`?
## Expected Follow-up
1. Converter esta agenda em decision no `runtime`.
2. Propagar a decisao para `15-asset-management.md`.
3. Ajustar loaders format-specific para usar helpers consistentes de metadata quando necessario.
4. Alinhar o `packer` e testes de conformance com o shape final.
@@ -1,49 +0,0 @@
---
id: AGD-0017
ticket: jenkinsfile-correction
title: Agenda - Jenkinsfile Correction and Relocation
status: open
created: 2026-04-07
resolved:
decision:
tags: ["ci", "jenkins", "infrastructure"]
---
# Agenda - Jenkinsfile Correction and Relocation
## Contexto
O projeto possui um `Jenkinsfile` localizado em `files/config/Jenkinsfile`. O conteúdo deste arquivo está básico e utiliza uma versão do Rust (`1.77`) que pode não ser a ideal em comparação com o resto do projeto que usa a versão estável definida em `rust-toolchain.toml`. Além disso, o pipeline de CI principal do projeto está definido no GitHub Actions e o comportamento esperado de CI (formatação, clippy, testes) também está documentado no `Makefile`.
## Problema
1. **Localização Não Convencional**: O `Jenkinsfile` na pasta `files/config/` dificulta a descoberta e manutenção, além de fugir do padrão do Jenkins de buscar o arquivo na raiz do repositório.
2. **Desalinhamento de Comandos**: O `Jenkinsfile` atual executa comandos de forma ligeiramente diferente do `Makefile` e do GitHub Actions (ex: `cargo fmt --all` vs `cargo fmt -- --check`).
3. **Falta de Padronização**: Não há garantias de que o pipeline do Jenkins execute as mesmas verificações de qualidade que o pipeline do GitHub.
## Pontos Críticos
- **Sincronia com o Makefile**: O `Jenkinsfile` deve idealmente delegar para o `Makefile` para evitar duplicidade de lógica de comandos.
- **Ambiente Docker**: A imagem Docker utilizada deve ser compatível com as ferramentas necessárias (ex: `make`, `cargo`).
- **Workspace Completo**: Deve garantir que todas as crates do workspace sejam testadas.
## Opções
1. **Manter como está**: Apenas corrigir o conteúdo no local atual.
2. **Mover para a raiz e atualizar**: Seguir o padrão de mercado movendo para a raiz e alinhando o conteúdo com o `Makefile`.
3. **Remover o Jenkinsfile**: Se o projeto foca apenas no GitHub Actions (como sugere o `dist-workspace.toml`), o Jenkinsfile pode ser redundante. Contudo, a solicitação explícita foi para corrigi-lo.
## Sugestão / Recomendação
**Opção 2**: Mover o `Jenkinsfile` para a raiz do projeto e atualizar seu conteúdo para utilizar o comando `make ci` definido no `Makefile`. Isso garante consistência entre o ambiente local, o Jenkins e o GitHub Actions.
## Perguntas em Aberto
- Existe alguma restrição técnica no ambiente Jenkins deste projeto que exija o arquivo em `files/config/`? (Assumindo que não, dada a solicitação de "corrigir").
- A imagem Docker `rust:stable` (ou similar) possui as dependências necessárias para rodar o `Makefile`?
## Criterio para Encerrar
- O `Jenkinsfile` estar na raiz do projeto.
- O conteúdo refletir as mesmas etapas de validação do resto do projeto (fmt, clippy, test).
- O arquivo antigo em `files/config/` ter sido removido.
@@ -1,48 +0,0 @@
---
id: AGD-0018
ticket: jenkins-gitea-integration-and-relocation
title: Agenda - Jenkins Gitea Integration and Relocation
status: open
created: 2026-04-07
resolved:
decision:
tags: ["ci", "jenkins", "gitea"]
---
# Agenda - Jenkins Gitea Integration and Relocation
## Contexto
Na sessão anterior, o `Jenkinsfile` foi movido para a raiz do repositório para seguir padrões comuns de mercado. No entanto, o usuário solicitou explicitamente que ele permaneça em `files/config/Jenkinsfile`. Além disso, a estratégia de CI mudou de GitHub Actions para Jenkins integrado ao Gitea.
## Problema
1. O local atual do `Jenkinsfile` (raiz no histórico, mas residindo em `files/config` no FS atual) precisa ser consolidado como `files/config/Jenkinsfile` para cumprir o requisito do usuário.
2. A integração do CI deve ser com o Gitea, exigindo a propagação de status dos commits.
3. Não deve haver dependência ou uso do GitHub CI para este projeto.
## Pontos Críticos
- **Sincronização de Status**: Garantir que o Jenkins envie o feedback de `make ci` (testes/lint) corretamente para o Gitea.
- **Localização não-padrão**: Jenkins precisa ser configurado no lado do servidor para buscar o script de pipeline em `files/config/Jenkinsfile` (o que é trivial, mas foge do padrão `Jenkinsfile` na raiz).
- **Abandono do GitHub CI**: Remover qualquer resquício de configuração voltada ao GitHub.
## Opções
1. **Opção A**: Manter na raiz (rejeitada pelo usuário).
2. **Opção B**: Manter em `files/config/Jenkinsfile` e usar o plugin de Gitea no Jenkins para notificação automática ou via `giteaStatus` no pipeline.
## Sugestão / Recomendação
Adotar a **Opção B**. Atualizar o `Jenkinsfile` para incluir blocos de `post` que notifiquem o Gitea sobre o sucesso ou falha do pipeline.
## Perguntas em Aberto
- O Jenkins em questão já tem o plugin do Gitea configurado? (Assumiremos que sim ou que o pipeline deve usar o comando padrão `giteaStatus`).
- Existem arquivos `.github/workflows` que devem ser removidos? (Verificar e remover).
## Criterio para Encerrar
- `Jenkinsfile` atualizado e testado localmente (validado sintaticamente).
- Documentação da decisão no framework.
- Localização confirmada em `files/config/Jenkinsfile`.
@@ -1,52 +0,0 @@
---
id: DEC-0002
discussion: DSC-0019
title: Decision - Jenkinsfile Location and Strategy
status: accepted
created: 2026-04-07
resolved:
tags: ["ci", "jenkins"]
---
# Decision - Jenkinsfile Location and Strategy
## Status
Accepted.
## Contexto
O arquivo `Jenkinsfile` estava localizado em `files/config/Jenkinsfile`, o que dificultava a manutenção e automação via Jenkins (que por padrão busca na raiz). Além disso, o conteúdo estava divergente das definições de CI do `Makefile` e do GitHub Actions.
## Decisao
1. **Mover** o `Jenkinsfile` para a raiz do repositório.
2. **Atualizar** o conteúdo do `Jenkinsfile` para utilizar uma imagem Docker `rust:stable` (conforme `rust-toolchain.toml`).
3. **Delegar** a execução do pipeline para o comando `make ci` definido no `Makefile`.
4. **Remover** o arquivo residual em `files/config/Jenkinsfile`.
## Rationale
- **Padronização**: Seguir o padrão de mercado de manter o arquivo de configuração de pipeline na raiz.
- **DRY (Don't Repeat Yourself)**: Ao usar o `Makefile`, evitamos duplicar os comandos de `fmt`, `clippy` e `test` em múltiplos lugares (Makefile, GHA e Jenkins).
- **Consistência**: Garante que o desenvolvedor rodando `make ci` localmente tenha o mesmo resultado que o servidor de CI.
## Invariantes / Contrato
- O comando `make ci` deve sempre englobar as verificações mínimas de qualidade (format, clippy, tests).
- O `Jenkinsfile` deve sempre usar um ambiente que possua `make` e `rust`.
## Impactos
- **Jenkins**: A configuração do job no Jenkins pode precisar ser atualizada se o "Script Path" estiver explicitamente apontando para `files/config/Jenkinsfile`. (Geralmente aponta para `Jenkinsfile` na raiz).
- **Manutenção**: Facilita a manutenção, pois mudanças no processo de build só precisam ser feitas no `Makefile`.
## Referencias
- `.github/workflows/ci.yml`
- `Makefile`
- `rust-toolchain.toml`
## Propagacao Necessaria
- N/A.
@@ -1,48 +0,0 @@
---
id: DEC-0003
agenda: AGD-0018
title: Decisão - Jenkins Gitea Integration and Relocation
status: accepted
created: 2026-04-07
tags: ["ci", "jenkins", "gitea"]
---
# Decisão - Jenkins Gitea Integration and Relocation
## Status
Aceito.
## Contexto
O projeto deve utilizar Jenkins integrado ao Gitea para o pipeline de CI, ignorando o GitHub Actions. O arquivo `Jenkinsfile` deve residir em um local específico solicitado pelo usuário: `files/config/Jenkinsfile`.
## Decisao
1. **Localização**: O `Jenkinsfile` será mantido em `files/config/Jenkinsfile`.
2. **Integração Gitea**: O pipeline deve utilizar comandos compatíveis com o plugin do Gitea no Jenkins para propagar o status da execução (Success/Failure/Pending).
3. **Remoção de GitHub CI**: Qualquer configuração de `.github/workflows` relacionada ao CI será removida para evitar confusão.
## Rationale
- Cumpre o requisito direto do usuário sobre a localização do arquivo.
- Alinha a infraestrutura de CI com o servidor Git interno (Gitea).
- Centraliza a execução no `Makefile` (`make ci`) para manter o `Jenkinsfile` simples e portável.
## Invariantes / Contrato
- O `Jenkinsfile` deve sempre chamar `make ci` para garantir que o mesmo padrão de qualidade seja aplicado localmente e no CI.
- Notificações de status devem ser enviadas ao Gitea no início e no fim da execução.
## Impactos
- **Jenkins**: O job no Jenkins deve ser configurado para apontar o "Script Path" para `files/config/Jenkinsfile`.
- **Desenvolvedores**: Devem focar no Gitea para verificar o status dos builds.
## Referencias
- AGD-0018
## Propagacao Necessaria
- Comunicar ao time de infraestrutura sobre o novo local do `Jenkinsfile` para ajuste no Job do Jenkins.
@@ -1,56 +0,0 @@
---
id: PLN-0002
discussion: DSC-0019
title: Plan - Jenkinsfile Relocation and Content Alignment
status: open
created: 2026-04-07
resolved:
tags: ["ci", "jenkins"]
---
# Plan - Jenkinsfile Relocation and Content Alignment
## Briefing
Este plano descreve as etapas técnicas para mover o `Jenkinsfile` de sua localização atual para a raiz do repositório e atualizar seu conteúdo para delegar as tarefas de CI ao `Makefile`.
## Decisions de Origem
- DEC-0002: Jenkinsfile Location and Strategy
## Alvo
- `files/config/Jenkinsfile` (Remoção)
- `/Jenkinsfile` (Criação/Movimentação)
## Escopo
- Movimentação do arquivo no sistema de arquivos.
- Edição do conteúdo Groovy do Jenkinsfile.
- Validação básica da sintaxe.
## Fora de Escopo
- Configuração do servidor Jenkins externo.
- Criação de novos comandos no `Makefile` (usaremos o `make ci` existente).
## Plano de Execucao
1. Criar o novo `Jenkinsfile` na raiz com o conteúdo atualizado.
2. Remover o arquivo original em `files/config/Jenkinsfile`.
3. Validar se o `Makefile` está acessível no ambiente Docker especificado.
## Criterios de Aceite
- O arquivo `Jenkinsfile` deve existir na raiz.
- O arquivo `files/config/Jenkinsfile` não deve mais existir.
- O novo `Jenkinsfile` deve conter uma chamada para `make ci`.
## Tests / Validacao
- Verificar a existência dos arquivos via terminal.
- Simular a execução do comando `make ci` (opcional, já validado pelo GHA).
## Riscos
- **Quebra de Pipeline Existente**: Se o Jenkins estiver configurado para ler especificamente de `files/config/Jenkinsfile`, o pipeline quebrará até que a configuração do Job seja atualizada. (Risco baixo, pois o padrão é a raiz).
@@ -1,55 +0,0 @@
---
id: PLN-0003
decisions: ["DEC-0003"]
title: Plano de Execução - Jenkins Gitea Integration
status: open
created: 2026-04-07
---
# Plano de Execução - Jenkins Gitea Integration
## Briefing
Atualizar o Jenkinsfile para integração com Gitea e garantir sua localização em `files/config/Jenkinsfile`. Remover resquícios de GitHub CI.
## Decisions de Origem
- DEC-0003
## Alvo
- `files/config/Jenkinsfile`
- `.github/workflows/` (limpeza)
## Escopo
- Atualização do script Groovy do `Jenkinsfile` com suporte a `giteaStatus`.
- Garantir que o diretório `files/config` existe.
- Remover diretório `.github/workflows` se existir.
## Fora de Escopo
- Configuração real do servidor Jenkins (fora do repositório).
## Plano de Execucao
1. Verificar existência do diretório `files/config` e criar se necessário.
2. Atualizar/Mover o `Jenkinsfile` para `files/config/Jenkinsfile`.
3. Adicionar blocos `post` no `Jenkinsfile` para notificação ao Gitea.
4. Excluir `.github/workflows` se presente.
5. Validar sintaxe básica do Jenkinsfile.
## Criterios de Aceite
- O arquivo `Jenkinsfile` reside em `files/config/Jenkinsfile`.
- O conteúdo do `Jenkinsfile` inclui `make ci` e chamadas ao Gitea.
- Não existem workflows de GitHub CI.
## Tests / Validacao
- Execução manual de `make ci` para garantir que o comando base funciona.
- Verificação visual do `Jenkinsfile`.
## Riscos
- **Incompatibilidade de Plugin**: Se o Jenkins do usuário não tiver o plugin do Gitea, as chamadas `giteaStatus` podem falhar. No entanto, estamos seguindo o requisito de "propagar resultados para gitea".