discussion framework migration

This commit is contained in:
bQUARKz 2026-03-27 04:54:27 +00:00
parent 7e3e8c81f5
commit 6b08633798
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
18 changed files with 194 additions and 92 deletions

View File

@ -1,2 +1,18 @@
{"type":"meta","next_id":{"DSC":2,"AGD":1,"DEC":1,"PLN":1,"LSN":19,"CLSN":1}}
{"type":"meta","next_id":{"DSC":18,"AGD":17,"DEC":1,"PLN":1,"LSN":19,"CLSN":1}}
{"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":[]}

View File

@ -1,3 +1,14 @@
---
id: AGD-0001
ticket: runtime-edge-test-plan
title: Agenda - Runtime Edge Test Plan
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - Runtime Edge Test Plan
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0002
ticket: packed-cartridge-loader-pmc
title: Agenda - Packed Cartridge Loader PMC
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - Packed Cartridge Loader PMC
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0003
ticket: system-run-cart
title: Agenda - System Run Cart
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - System Run Cart
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0004
ticket: system-fault-semantics-and-control-surface
title: Agenda - System Fault Semantics and Control Surface
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - System Fault Semantics and Control Surface
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0005
ticket: vm-owned-random-service
title: Agenda - VM-Owned Random Service
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - VM-Owned Random Service
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0006
ticket: app-home-filesystem-surface-and-semantics
title: Agenda - App Home Filesystem Surface and Semantics
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - App Home Filesystem Surface and Semantics
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0007
ticket: perf-runtime-telemetry-hot-path
title: Agenda - [PERF] Runtime Telemetry Hot Path
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Runtime Telemetry Hot Path
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0008
ticket: perf-async-background-work-lanes-for-assets-and-fs
title: Agenda - [PERF] Async Background Work Lanes for Assets and FS
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Async Background Work Lanes for Assets and FS
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0009
ticket: perf-host-desktop-frame-pacing-and-presentation
title: Agenda - [PERF] Host Desktop Frame Pacing and Presentation
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Host Desktop Frame Pacing and Presentation
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0010
ticket: perf-gfx-render-pipeline-and-dirty-regions
title: Agenda - [PERF] GFX Render Pipeline and Dirty Regions
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] GFX Render Pipeline and Dirty Regions
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0011
ticket: perf-runtime-introspection-syscalls
title: Agenda - [PERF] Runtime Introspection Syscalls
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Runtime Introspection Syscalls
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0012
ticket: perf-host-debug-overlay-isolation
title: Agenda - [PERF] Host Debug Overlay Isolation
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Host Debug Overlay Isolation
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0013
ticket: perf-vm-allocation-and-copy-pressure
title: Agenda - [PERF] VM Allocation and Copy Pressure
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] VM Allocation and Copy Pressure
## Problema

View File

@ -1,3 +1,14 @@
---
id: AGD-0014
ticket: perf-cartridge-boot-and-program-ownership
title: Agenda - [PERF] Cartridge Boot and Program Ownership
status: open
created: 2026-03-27
resolved:
decision:
tags: []
---
# Agenda - [PERF] Cartridge Boot and Program Ownership
## Problema

View File

@ -1,3 +1,14 @@
---
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

View File

@ -1,4 +1,15 @@
# 024-asset-entry-metadata-normalization-contract
---
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`

View File

@ -1,90 +0,0 @@
# Agendas
Este diretório reúne agendas de discussão arquitetural para itens pendentes ou frágeis do runtime.
Objetivo:
- explicitar a dor real do sistema;
- delimitar o que precisa ser decidido antes de codar;
- servir de base para futuras PRs de implementação JVM-grade.
As agendas atuais são:
- `007-runtime-edge-test-plan.md`
- `008-packed-cartridge-loader-pmc.md`
- `009-system-run-cart.md`
- `010-system-fault-semantics-and-control-surface.md`
- `012-vm-owned-random-service.md`
- `014-app-home-filesystem-surface-and-semantics.md`
- `015-perf-runtime-telemetry-hot-path.md`
- `016-perf-async-background-work-lanes-for-assets-and-fs.md`
- `017-perf-host-desktop-frame-pacing-and-presentation.md`
- `018-perf-gfx-render-pipeline-and-dirty-regions.md`
- `019-perf-runtime-introspection-syscalls.md`
- `020-perf-host-debug-overlay-isolation.md`
- `021-perf-vm-allocation-and-copy-pressure.md`
- `022-perf-cartridge-boot-and-program-ownership.md`
- `024-asset-entry-metadata-normalization-contract.md`
## Sequenciamento Recomendado [PERF]
Ordem sugerida para discussao das agendas de performance:
1. `015-perf-runtime-telemetry-hot-path.md`
2. `016-perf-async-background-work-lanes-for-assets-and-fs.md`
3. `017-perf-host-desktop-frame-pacing-and-presentation.md`
4. `018-perf-gfx-render-pipeline-and-dirty-regions.md`
5. `019-perf-runtime-introspection-syscalls.md`
6. `020-perf-host-debug-overlay-isolation.md`
7. `021-perf-vm-allocation-and-copy-pressure.md`
8. `022-perf-cartridge-boot-and-program-ownership.md`
Justificativa curta:
- `015` e o imposto mais imediato no hot path do runtime.
- `016` fecha a topologia de trabalho assincrono antes de codarmos otimizaoes isoladas.
- `017` impede que o host desktop continue mascarando custo real com busy-poll.
- `018` define o teto de custo do renderer antes de micro-otimizacoes locais.
- `019` separa observabilidade de superficie operacional normal.
- `020` impede que tooling de debug distorca medicao de render e frame pacing.
- `021` entra depois que os gargalos estruturais maiores estiverem delimitados.
- `022` fecha ownership e custo de boot, importante mas menos quente que o frame loop.
## Sequenciamento Recomendado
Ordem sugerida para discussão e futura execução:
1. `012-vm-owned-random-service.md`
2. `014-app-home-filesystem-surface-and-semantics.md`
3. `007-runtime-edge-test-plan.md`
4. `008-packed-cartridge-loader-pmc.md`
5. `009-system-run-cart.md`
6. `010-system-fault-semantics-and-control-surface.md`
Justificativa curta:
- `011` foi fechada pela decisao `006`.
- `012` e o primeiro consumidor da base stateful VM-owned fechada em `006`.
- `013` foi fechada e absorvida por `spec 08` (historico em `learn/historical-game-memcard-slots-surface-and-semantics.md`).
- `014` fecha o contrato de `home` para apps sem abrir FS global.
- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos entre `spec 08` (`game`) e agenda `014` (`app`).
- a decisao `008` fixa o contrato status-first de `gfx`.
- a decisao `009` fixa o contrato status-first de `audio`.
- a decisao `010` fixa o contrato status-first de `asset`.
- a agenda `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
- `008` depende da decisao `011`, porque o `shipper` do `.pmc` nao deve decidir o contrato interno do packer de assets no meio da implementacao.
- `009` e `010` ficam no fim porque `run_cart` nao e objetivo do ciclo atual.
Dependências principais:
- `012` depende da decisao `006` e de `16`/`16a`
- `014` depende das decisoes `003`/`007`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`)
- `007` depende da estabilizacao minima das agendas de superficie/fault por dominio
- `008` depende da decisao `011`, de contrato fechado de `13-cartridge.md` e de comportamento equivalente ao loader de diretorio
- `009` depende da decisao `003`, de `16a` e da decisao `006`, e deve alinhar com `spec 08`/agenda `014` quando usar `fs`
- `010` depende de `16a` e da `009`
Regra de uso:
- se a implementação exigir decisão estrutural, ela deve nascer daqui antes de virar PR de código;
- se uma agenda já estiver resolvida, a PR derivada deve citar explicitamente qual decisão foi tomada;
- se a agenda revelar ambiguidade demais, ela não deve ser convertida em PR até o alvo ficar preciso.