chore: record AIE works and update cleaned submodules
This commit is contained in:
@@ -1,3 +1,3 @@
|
||||
---
|
||||
schemaVersion: 2
|
||||
lastWork: "0002"
|
||||
lastWork: "0010"
|
||||
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-0003"
|
||||
origin: "discussion-framework:runtime:AGD-0072:AGD-0072-licoes-de-engenharia-do-blitz3d-para-o-prometeu.md"
|
||||
purpose: "Original DF agenda AGD-0072"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "09732c4c27069ae9f77ddc47d3a8478318d2ca2d07dafd5c5ed306c237ab28ad"
|
||||
size: 18812
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.084604Z"
|
||||
+178
@@ -0,0 +1,178 @@
|
||||
---
|
||||
id: AGD-0072
|
||||
ticket: blitz3d-engineering-lessons
|
||||
title: Licoes de engenharia do Blitz3D para o Prometeu
|
||||
status: open
|
||||
created: 2026-11-04
|
||||
resolved:
|
||||
decision:
|
||||
tags: [architecture, runtime, tooling, research]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
**Worker:** Agenda Worker. **Dominio owner:** `runtime`, pesquisa comparativa de mecanismos internos da maquina, fronteiras de execucao e provider de metadata.
|
||||
|
||||
O usuario pediu uma analise do Blitz3D e esclareceu o objetivo: extrair licoes de engenharia de um engine experiente. Em 2026-11-04, solicitou separar runtime e Studio. Esta agenda conserva as ideias pertinentes ao runtime; autoria, core/SDK e ferramentas foram transferidos para [DSC-0100 / AGD-0102 no Studio](../../../../studio/discussion/workflow/agendas/AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md).
|
||||
|
||||
Base examinada:
|
||||
|
||||
- Blitz3D: commit [`f132a78c9f2da255905bf477cb845994324b865a`](https://github.com/blitz-research/blitz3d_soloud/commit/f132a78c9f2da255905bf477cb845994324b865a), datado de 2024-10-19, resolvido a partir de `main` na consulta de 2026-11-04.
|
||||
- Prometeu runtime: checkout `a4bec5bc4577850543f57c79f5124ca00169e1b3`, specs de GFX, audio, Registry/PBX, tempo, assets, portabilidade e debugging; composer/cache, audio desktop e catalogos nativos.
|
||||
- Metodo: leitura estatica de fontes, exemplos e build metadata. O Blitz3D nao foi compilado ou executado; nao foram medidos desempenho ou qualidade perceptual.
|
||||
|
||||
O runtime ja possui separacao entre producao logica e render, publicacao de comandos de audio, recursos com identidade/geracao e catalogos nativos. A comparacao procura mecanismos uteis para pensar essas responsabilidades e contraexemplos para verificar suas fronteiras. Nao parte da premissa de que exista uma falha equivalente no Prometeu.
|
||||
|
||||
## Problema
|
||||
|
||||
Quais escolhas do Blitz3D ajudam a avaliar validade de caches, compartilhamento de recursos, publicacao, isolamento entre fases, limites de trabalho e seguranca do runtime?
|
||||
|
||||
A avaliacao separa fato observado, licao inferida, aplicabilidade local e limite da evidencia. Conveniencias de linguagem, assinatura apresentada ao autor e bibliotecas de gameplay sao responsabilidades da agenda de Studio.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
### 1. Um cache precisa declarar de que mudanca depende
|
||||
|
||||
**Fato:** [`Surface::Monitor`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/surface.h) distingue alteracoes geometricas e de material. [`MeshModel::Rep`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/meshmodel.cpp) compara `geom_changes` com `box_valid`, `coll_valid` e `norms_valid`, reconstruindo bounding box, collider ou normais quando necessario. [`Entity`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/entity.cpp) invalida transforms descendentes e recompõe o resultado sob demanda.
|
||||
|
||||
**Licao:** a parte decisiva do cache e seu protocolo de validade: dependencias, evento invalidante e momento de reconstrucao. Contadores separados evitam tratar toda alteracao como mudanca de tudo.
|
||||
|
||||
**Aplicabilidade:** comparar esse modelo com `SceneViewportCache`, `SceneViewportResolver`, recursos de glyph/paleta e seus consumidores. O Prometeu ja atualiza linhas, colunas e regioes; a investigacao util e procurar invalidacao excessiva ou dependencias esquecidas em troca/reload de banco. E uma hipotese de revisao, nao um defeito demonstrado.
|
||||
|
||||
**Limite:** lazy rebuild pode concentrar trabalho no primeiro uso. Na fronteira assincrona Prometeu, ele precisa ocorrer no owner correto e nao pode exigir acesso mutavel do render ao estado vivo da VM. Em [`Surface::getMesh`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/surface.cpp), apesar dos marcadores de validade, o caminho ativo zera ambos antes do upload quando detecta trabalho. A existencia de dirty flags nao prova atualizacao parcial efetiva.
|
||||
|
||||
### 2. Dado compartilhado e configuracao da instancia merecem vidas distintas
|
||||
|
||||
**Fato:** [`CachedTexture`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/cachedtexture.cpp) compartilha frames por uma chave que considera arquivo, flags, dimensoes e recorte de animacao. [`Brush::write`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/brush.cpp) separa a representacao compartilhada quando uma copia precisa ser modificada.
|
||||
|
||||
**Licao:** copias baratas precisam de semantica de alias explicita. Compartilhar o payload e diferente de compartilhar toda configuracao mutavel. Uma chave de cache deve incluir os parametros que alteram o resultado.
|
||||
|
||||
**Aplicabilidade:** manter clara a distincao entre identidade do asset, residencia do banco, payload retido e parametros de cada uso. O modelo de samples imutaveis e owners retidos do Prometeu ja aplica parte dessa separacao. Copy-on-write e uma ferramenta possivel para descritores internos; nao e uma mudanca proposta para a semantica de objetos guest.
|
||||
|
||||
**Limite:** busca por path e refcount manual sao detalhes historicos, nao metas. Identidade por `asset_id`/geracao e as regras publicadas de unload devem continuar sendo avaliadas pelo contrato Prometeu. Compartilhamento tambem pode reter memoria e mover custo para a primeira escrita.
|
||||
|
||||
### 3. Atualizacao e apresentacao sao fases diferentes, mas a separacao deve ser real
|
||||
|
||||
**Fato:** [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) oferece `update`, `capture` e `render(tween)`. [`Object::capture` e `beginRender`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/object.cpp) preservam posicao/escala/rotacao e calculam transforms interpolados separados, usando interpolacao linear e quaternion slerp.
|
||||
|
||||
**Licao:** o estado simulado pode ser autoritativo enquanto a apresentacao usa um estado derivado. Isso ajuda a raciocinar sobre velocidades de simulacao e apresentacao diferentes.
|
||||
|
||||
**Aplicabilidade:** reforca o frame logico de 60 Hz, os snapshots fechados e a apresentacao host-owned do Prometeu. Interpolacao visual seria uma escolha adicional, dependente de necessidade real e de contrato proprio; o exemplo nao demonstra que ela seja necessaria ao pixel art atual.
|
||||
|
||||
**Contraponto concreto:** `Object::beginRender` chama `updateSounds`; `World::render` atualiza listeners, e [`Listener::renderListener`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/listener.cpp) envia estado espacial ao audio. Parte do audio espacial depende, portanto, da chamada de render e da enumeracao de objetos visiveis. O aprendizado para o Prometeu e verificar que render descartado, pausa de apresentacao ou execucao headless nao governem trabalho de simulacao/audio por acidente. Nao se afirma que um defeito equivalente exista aqui.
|
||||
|
||||
### 4. Configure a reproducao antes de torna-la observavel
|
||||
|
||||
**Fato:** em [`bbaudio_soloud.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime/bbaudio_soloud.cpp), `Sound` representa material/defaults e `channel` identifica uma reproducao. Quando existe pitch customizado, `bbPlaySound` inicia a voz pausada, ajusta o sample rate e so depois libera a reproducao. Musica usa `WavStream`, enquanto efeitos usam `Wav`.
|
||||
|
||||
**Licao:** preparar uma operacao e publica-la sao momentos distintos. Evitar observacao de estado parcialmente configurado pode ser mais importante que a simplicidade de cada setter. A separacao entre material e reproducao tambem deixa claras as responsabilidades dos controles.
|
||||
|
||||
**Aplicabilidade:** o `play` Prometeu ja fornece todos os parametros e o mixer consome comandos publicados. O padrao do Blitz reforca essa escolha. Streaming ensina que musica longa possui outro perfil de residencia e I/O; a necessidade concreta deve preceder qualquer proposta de novo servico.
|
||||
|
||||
**Limite:** o adapter do Blitz nao estabelece as garantias de callback, backpressure, pausas por sessao e reclamacao fora do callback presentes no contrato Prometeu. O simples uso de SoLoud nao resolve essas responsabilidades. Defaults mutaveis de `Sound` tambem diferem dos samples imutaveis atuais.
|
||||
|
||||
### 5. Limites de trabalho e fallback fazem parte de um algoritmo
|
||||
|
||||
**Fato:** o solver de [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) limita tentativas com `MAX_HITS=10` e restaura a posicao inicial ao atingir o limite. [`MeshCollider`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/meshcollider.cpp) descarta candidatos por uma hierarquia de AABBs antes de testar triangulos. A hierarquia e interna a cada mesh; as listas de objetos por tipo nao constituem um broad phase espacial global.
|
||||
|
||||
**Licao:** limitar trabalho, definir comportamento de esgotamento e distinguir filtragem barata de trabalho detalhado sao responsabilidades explicitas do algoritmo. A presenca de uma aceleracao local nao demonstra que o custo do sistema inteiro esteja limitado.
|
||||
|
||||
**Aplicabilidade:** usar esse exemplo como criterio de revisao dos mecanismos nativos que ja possuem quotas e limites: verificar a unidade de trabalho, onde o custo aparece, o estado preservado em recusa e a ausencia de efeitos parciais indevidos. Um algoritmo nativo novo precisaria definir esses aspectos antes de ser proposto como contrato de maquina.
|
||||
|
||||
**Limite e transferencia:** overlap/sweep 2D, movimento contra tilemap e respostas de gameplay passam para a pesquisa de core/SDK no Studio. Esta agenda nao propoe periferico de colisao, syscall, fisica ou 3D. Os limites e epsilons do Blitz nao sao valores recomendados para o Prometeu.
|
||||
|
||||
### 6. Metadata do provider precisa de autoridade e representacao explicitas
|
||||
|
||||
**Fato:** o Blitz registra interfaces em `rtSym` e as expoe por [`Runtime::nextSym`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime_dll/bbruntime_dll.cpp). O Prometeu ja oferece [`syscalls::catalogue()`](../../../crates/console/prometeu-hal/src/syscalls.rs), `intrinsic_catalog()` e [exportacao de catalogos](../../../crates/console/prometeu-vm/src/catalog.rs).
|
||||
|
||||
**Licao:** metadata com owner conhecido torna observavel o contrato que um consumer pretende usar. Identidade, ABI, custos e efeitos precisam permanecer coerentes com execucao e validacao; representacao compartilhavel nao significa compartilhar ponteiros ou layouts nativos.
|
||||
|
||||
**Aplicabilidade:** manter a distincao entre catalogo de intrinsics, catalogo de syscalls e Registry por imagem. Qualquer investigacao deve verificar a fidelidade do provider e suas evidencias de exportacao, sem presumir que catalogos distintos tenham os mesmos campos ou finalidade.
|
||||
|
||||
**Limite e transferencia:** porte do catalogo para Java, declaracoes SDK, nomes de parametros PBS, hover, completion, signature help e documentacao da API pertencem ao Studio. A pesquisa de coerencia desses consumidores foi transferida integralmente; nao e obrigacao de implementacao desta agenda. Nenhuma mudanca de formato de catalogo e proposta aqui.
|
||||
|
||||
### 7. Validacao da maquina e independente da experiencia de debug
|
||||
|
||||
**Fato:** verificacoes de existencia de banco e limites em [`bbbank.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime/bbbank.cpp) sao condicionadas a `debug`. O debugger Blitz tambem acessa declaracoes e estruturas do compilador por ponteiros.
|
||||
|
||||
**Licao:** informacao adicional de debug e validacao obrigatoria sao responsabilidades diferentes. A maquina precisa conservar suas regras de seguranca em todos os modos; representacoes consumidas fora do owner devem ter um contrato proprio.
|
||||
|
||||
**Aplicabilidade:** usar esse contraponto para avaliar loader/verifier, handles, limites e interpretacao de metadata/faults existentes, preservando o resultado logico entre modos. O runtime recebe metadados PBX e fornece contexto de execucao e faults pelos contratos publicados; isso nao o torna owner da sintaxe de origem ou da UI.
|
||||
|
||||
**Limite e transferencia:** emissao de nomes/spans pelo compilador e apresentacao de diagnosticos ao autor pertencem ao Studio. A agenda de Studio conserva os exemplos de `StmtNode::debug` e `debugtree.cpp`. Nenhuma perda de origem ou divergencia de validacao foi demonstrada no Prometeu por esta pesquisa.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Aprofundar caches e ownership a partir de um workload
|
||||
|
||||
- **Abordagem:** seguir invalidacao, retencao e reconstrucao no composer/asset/audio atual, motivado por uma carga ou erro observavel.
|
||||
- **Pro:** compara mecanismos concretos disponiveis neste repositorio.
|
||||
- **Contra:** pode nao encontrar problema; precisa medir antes de recomendar otimizacao.
|
||||
- **Tradeoff:** melhor ponto de partida para investigacao interna com alvo delimitado.
|
||||
|
||||
### Opcao B - Examinar fronteiras e publicacao em cenarios adversos
|
||||
|
||||
- **Abordagem:** usar render descartado, pausa, headless e esgotamento de trabalho para revisar independencia entre fases e efeitos de comandos.
|
||||
- **Pro:** aproveita os contraexemplos concretos do Blitz e os contratos ja publicados.
|
||||
- **Contra:** uma revisao ampla pode repetir evidencia existente sem acrescentar informacao.
|
||||
- **Tradeoff:** escolher somente um cenario com duvida concreta, preservando quotas, ordering e ownership vigentes.
|
||||
|
||||
### Opcao C - Reter a pesquisa como referencia para necessidades futuras
|
||||
|
||||
- **Abordagem:** manter mecanismos e limites documentados, retomando quando houver proposta ou problema correspondente.
|
||||
- **Pro:** evita inventar trabalho sem evidencia de necessidade.
|
||||
- **Contra:** nao produz uma nova medicao ou revisao interna agora.
|
||||
- **Tradeoff:** adequada enquanto os achados apenas corroborarem o desenho atual.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Manter **C** como estado desta pesquisa. Se surgir problema observavel de custo/retencao, priorizar **A**. Se a duvida for acoplamento ou ordem entre fases, selecionar um cenario de **B**.
|
||||
|
||||
Os aprendizados mais diretamente transferiveis ao runtime sao protocolos de validade de cache, separacao entre payload e uso, preparacao antes da publicacao e limites com fallback explicito. As fronteiras fechadas de render e audio do Prometeu ja respondem a parte dos riscos observados no Blitz. Nao ha evidencia, nesta analise, que justifique substitui-las.
|
||||
|
||||
## Transferencia e Fronteiras de Responsabilidade
|
||||
|
||||
Separacao solicitada pelo usuario em 2026-11-04. Destino de autoria/ferramentas: [DSC-0100 / AGD-0102](../../../../studio/discussion/workflow/agendas/AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md). Os IDs pertencem a indices independentes por repositorio.
|
||||
|
||||
| Tema da pesquisa original | Permanece no runtime | Responsabilidade transferida ao Studio |
|
||||
| --- | --- | --- |
|
||||
| API por tarefa completa | Somente respeito aos contratos de maquina consumidos | Ergonomia de linguagem/core/SDK, imports e percurso de autoria. |
|
||||
| Metadata ate a IDE | Autoridade, representacao e fidelidade dos catalogos do provider | Porte/importacao, projecoes semanticas, ajuda e documentacao da API. |
|
||||
| Caches e invalidacao | Protocolos de validade, dependencia e reconstrucao interna | Nenhuma investigacao interna de cache transferida. |
|
||||
| Recursos compartilhados | Identidade, residencia, owners e parametros por uso | Eventuais abstracoes de instancia de core/SDK, quando houver caso de uso. |
|
||||
| Atualizacao e apresentacao | Fases, snapshots, clocks e independencia do audio/render | Conveniencias de atualizacao/desenho de gameplay, respeitando suas discussoes locais. |
|
||||
| Preparar audio antes de publicar | Comandos completos, publicacao, callback e reclamacao | Nenhuma entrega de audio SDK criada ou reativada. |
|
||||
| Colisao e trabalho limitado | Principio de limite/fallback e custo das consultas | Hipoteses de helpers geometricos e respostas de gameplay em biblioteca. |
|
||||
| Exemplos pequenos | Fornecimento dos contratos/host de execucao existentes | Ensino, corpus de autoria e encaminhamento de qualificacao instalada ao owner existente. |
|
||||
| Debugging e origem | Validacao da maquina, leitura de metadata e faults | Emissao de origem pelo compilador e experiencia de diagnostico do autor. |
|
||||
|
||||
As perguntas e sugestoes de evidencia transferidas estao detalhadas na agenda de destino. A transferencia nao equivale a implementacao, validacao ou aceite tecnico. A agenda de runtime nao depende do fechamento de nenhuma agenda do Studio.
|
||||
|
||||
Escolha de host/backend continua com [DSC-0047 / AGD-0050](AGD-0050-portable-host-backend-strategy.md). Background service/media continua com [DSC-0045 / AGD-0048](AGD-0048-background-service-audio-execution.md). Esta pesquisa nao adiciona obrigacoes a essas discussoes.
|
||||
|
||||
Os achados continuam em agenda de pesquisa; nao sao publicados como `discussion/lessons/`, pois nao derivam de nova decisao executada no Prometeu.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] Existe workload ou erro observavel que justifique investigar invalidacao/reconstrucao de cache ou retencao de owners?
|
||||
- [ ] Qual dependencia interna especifica merece revisao, e qual estado publicado permitiria demonstra-la?
|
||||
- [ ] Ha cenario de render descartado, pausa ou headless cuja independencia de audio/simulacao ainda precise de evidencia?
|
||||
- [ ] Algum mecanismo nativo tem limite de trabalho ou fallback ainda insuficientemente demonstrado?
|
||||
- [ ] Ha inconsistencia concreta entre metadata exportada pelo provider e seu comportamento, sem confundir isso com a adaptacao feita pelos consumers?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
A pesquisa comparativa esta entregue com fontes, aplicabilidade e limites. A separacao organizacional esta concluida quando a agenda Studio preservar os itens recebidos, os links cruzados resolverem e os dois workflows validarem.
|
||||
|
||||
Para uma futura decisao de mudanca no runtime, selecionar um problema concreto de sua responsabilidade, confirmar evidencia e fechar alternativas/comportamento. A pesquisa nao cria um plano de implementacao nem uma exigencia de alterar mecanismos que ja cumprem seu contrato.
|
||||
|
||||
## Proximo Passo Sugerido
|
||||
|
||||
Retomar o achado correspondente quando houver workload, defeito ou proposta concreta de runtime. Autoria e ferramentas prosseguem na agenda Studio, com escopo independente.
|
||||
|
||||
## Validacao da Pesquisa
|
||||
|
||||
- Leitura estatica em commit fixo; fontes originais preservadas entre as duas agendas.
|
||||
- Implementacoes existentes de catalogos, snapshots, caches e staging reconhecidas explicitamente.
|
||||
- Sem benchmarks, teste de execucao ou avaliacao perceptual do Blitz.
|
||||
- Separacao editorial de agendas; nenhuma alteracao em specs ou implementacao e nenhum item transferido marcado como executado.
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-0003"
|
||||
origin: "discussion-framework:runtime:DSC-0069:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0069"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "adf9e90ed4893ead68f02e174d1afd999e11943d513794ee3d5a7e2e474a517e"
|
||||
size: 463
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.092793Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0069","status":"open","ticket":"blitz3d-engineering-lessons","title":"Licoes de engenharia do Blitz3D para o Prometeu","created_at":"2026-11-04","updated_at":"2026-11-04","tags":["architecture","runtime","tooling","research"],"agendas":[{"id":"AGD-0072","file":"AGD-0072-licoes-de-engenharia-do-blitz3d-para-o-prometeu.md","status":"open","created_at":"2026-11-04","updated_at":"2026-11-04"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-0003"
|
||||
origin: "ai-engineering:discussion-import:runtime:DSC-0069"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "391b9e56abbc5c9b81554c812c5153d8e4996bdc3b9b52ac9036ba4b364d8ad4"
|
||||
size: 701
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.097466Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0003",
|
||||
"sourceId" : "runtime",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime",
|
||||
"dscId" : "DSC-0069",
|
||||
"targets" : [ "runtime" ],
|
||||
"contentHash" : "f8d1f1911b72fd416054849259823dd781664d11f41cb5c1ce7775d64f0ec5fa",
|
||||
"dscSha256" : "adf9e90ed4893ead68f02e174d1afd999e11943d513794ee3d5a7e2e474a517e",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0072",
|
||||
"file" : "AGD-0072-licoes-de-engenharia-do-blitz3d-para-o-prometeu.md",
|
||||
"sha256" : "09732c4c27069ae9f77ddc47d3a8478318d2ca2d07dafd5c5ed306c237ab28ad",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+190
@@ -0,0 +1,190 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-0003"
|
||||
discussionId: "df:runtime:AGD-0072"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:runtime"
|
||||
createdAt: "2026-11-16T15:25:23.078491Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
id: AGD-0072
|
||||
ticket: blitz3d-engineering-lessons
|
||||
title: Licoes de engenharia do Blitz3D para o Prometeu
|
||||
status: open
|
||||
created: 2026-11-04
|
||||
resolved:
|
||||
decision:
|
||||
tags: [architecture, runtime, tooling, research]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
**Worker:** Agenda Worker. **Dominio owner:** `runtime`, pesquisa comparativa de mecanismos internos da maquina, fronteiras de execucao e provider de metadata.
|
||||
|
||||
O usuario pediu uma analise do Blitz3D e esclareceu o objetivo: extrair licoes de engenharia de um engine experiente. Em 2026-11-04, solicitou separar runtime e Studio. Esta agenda conserva as ideias pertinentes ao runtime; autoria, core/SDK e ferramentas foram transferidos para [DSC-0100 / AGD-0102 no Studio](../../../../studio/discussion/workflow/agendas/AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md).
|
||||
|
||||
Base examinada:
|
||||
|
||||
- Blitz3D: commit [`f132a78c9f2da255905bf477cb845994324b865a`](https://github.com/blitz-research/blitz3d_soloud/commit/f132a78c9f2da255905bf477cb845994324b865a), datado de 2024-10-19, resolvido a partir de `main` na consulta de 2026-11-04.
|
||||
- Prometeu runtime: checkout `a4bec5bc4577850543f57c79f5124ca00169e1b3`, specs de GFX, audio, Registry/PBX, tempo, assets, portabilidade e debugging; composer/cache, audio desktop e catalogos nativos.
|
||||
- Metodo: leitura estatica de fontes, exemplos e build metadata. O Blitz3D nao foi compilado ou executado; nao foram medidos desempenho ou qualidade perceptual.
|
||||
|
||||
O runtime ja possui separacao entre producao logica e render, publicacao de comandos de audio, recursos com identidade/geracao e catalogos nativos. A comparacao procura mecanismos uteis para pensar essas responsabilidades e contraexemplos para verificar suas fronteiras. Nao parte da premissa de que exista uma falha equivalente no Prometeu.
|
||||
|
||||
## Problema
|
||||
|
||||
Quais escolhas do Blitz3D ajudam a avaliar validade de caches, compartilhamento de recursos, publicacao, isolamento entre fases, limites de trabalho e seguranca do runtime?
|
||||
|
||||
A avaliacao separa fato observado, licao inferida, aplicabilidade local e limite da evidencia. Conveniencias de linguagem, assinatura apresentada ao autor e bibliotecas de gameplay sao responsabilidades da agenda de Studio.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
### 1. Um cache precisa declarar de que mudanca depende
|
||||
|
||||
**Fato:** [`Surface::Monitor`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/surface.h) distingue alteracoes geometricas e de material. [`MeshModel::Rep`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/meshmodel.cpp) compara `geom_changes` com `box_valid`, `coll_valid` e `norms_valid`, reconstruindo bounding box, collider ou normais quando necessario. [`Entity`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/entity.cpp) invalida transforms descendentes e recompõe o resultado sob demanda.
|
||||
|
||||
**Licao:** a parte decisiva do cache e seu protocolo de validade: dependencias, evento invalidante e momento de reconstrucao. Contadores separados evitam tratar toda alteracao como mudanca de tudo.
|
||||
|
||||
**Aplicabilidade:** comparar esse modelo com `SceneViewportCache`, `SceneViewportResolver`, recursos de glyph/paleta e seus consumidores. O Prometeu ja atualiza linhas, colunas e regioes; a investigacao util e procurar invalidacao excessiva ou dependencias esquecidas em troca/reload de banco. E uma hipotese de revisao, nao um defeito demonstrado.
|
||||
|
||||
**Limite:** lazy rebuild pode concentrar trabalho no primeiro uso. Na fronteira assincrona Prometeu, ele precisa ocorrer no owner correto e nao pode exigir acesso mutavel do render ao estado vivo da VM. Em [`Surface::getMesh`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/surface.cpp), apesar dos marcadores de validade, o caminho ativo zera ambos antes do upload quando detecta trabalho. A existencia de dirty flags nao prova atualizacao parcial efetiva.
|
||||
|
||||
### 2. Dado compartilhado e configuracao da instancia merecem vidas distintas
|
||||
|
||||
**Fato:** [`CachedTexture`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/cachedtexture.cpp) compartilha frames por uma chave que considera arquivo, flags, dimensoes e recorte de animacao. [`Brush::write`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/brush.cpp) separa a representacao compartilhada quando uma copia precisa ser modificada.
|
||||
|
||||
**Licao:** copias baratas precisam de semantica de alias explicita. Compartilhar o payload e diferente de compartilhar toda configuracao mutavel. Uma chave de cache deve incluir os parametros que alteram o resultado.
|
||||
|
||||
**Aplicabilidade:** manter clara a distincao entre identidade do asset, residencia do banco, payload retido e parametros de cada uso. O modelo de samples imutaveis e owners retidos do Prometeu ja aplica parte dessa separacao. Copy-on-write e uma ferramenta possivel para descritores internos; nao e uma mudanca proposta para a semantica de objetos guest.
|
||||
|
||||
**Limite:** busca por path e refcount manual sao detalhes historicos, nao metas. Identidade por `asset_id`/geracao e as regras publicadas de unload devem continuar sendo avaliadas pelo contrato Prometeu. Compartilhamento tambem pode reter memoria e mover custo para a primeira escrita.
|
||||
|
||||
### 3. Atualizacao e apresentacao sao fases diferentes, mas a separacao deve ser real
|
||||
|
||||
**Fato:** [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) oferece `update`, `capture` e `render(tween)`. [`Object::capture` e `beginRender`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/object.cpp) preservam posicao/escala/rotacao e calculam transforms interpolados separados, usando interpolacao linear e quaternion slerp.
|
||||
|
||||
**Licao:** o estado simulado pode ser autoritativo enquanto a apresentacao usa um estado derivado. Isso ajuda a raciocinar sobre velocidades de simulacao e apresentacao diferentes.
|
||||
|
||||
**Aplicabilidade:** reforca o frame logico de 60 Hz, os snapshots fechados e a apresentacao host-owned do Prometeu. Interpolacao visual seria uma escolha adicional, dependente de necessidade real e de contrato proprio; o exemplo nao demonstra que ela seja necessaria ao pixel art atual.
|
||||
|
||||
**Contraponto concreto:** `Object::beginRender` chama `updateSounds`; `World::render` atualiza listeners, e [`Listener::renderListener`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/listener.cpp) envia estado espacial ao audio. Parte do audio espacial depende, portanto, da chamada de render e da enumeracao de objetos visiveis. O aprendizado para o Prometeu e verificar que render descartado, pausa de apresentacao ou execucao headless nao governem trabalho de simulacao/audio por acidente. Nao se afirma que um defeito equivalente exista aqui.
|
||||
|
||||
### 4. Configure a reproducao antes de torna-la observavel
|
||||
|
||||
**Fato:** em [`bbaudio_soloud.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime/bbaudio_soloud.cpp), `Sound` representa material/defaults e `channel` identifica uma reproducao. Quando existe pitch customizado, `bbPlaySound` inicia a voz pausada, ajusta o sample rate e so depois libera a reproducao. Musica usa `WavStream`, enquanto efeitos usam `Wav`.
|
||||
|
||||
**Licao:** preparar uma operacao e publica-la sao momentos distintos. Evitar observacao de estado parcialmente configurado pode ser mais importante que a simplicidade de cada setter. A separacao entre material e reproducao tambem deixa claras as responsabilidades dos controles.
|
||||
|
||||
**Aplicabilidade:** o `play` Prometeu ja fornece todos os parametros e o mixer consome comandos publicados. O padrao do Blitz reforca essa escolha. Streaming ensina que musica longa possui outro perfil de residencia e I/O; a necessidade concreta deve preceder qualquer proposta de novo servico.
|
||||
|
||||
**Limite:** o adapter do Blitz nao estabelece as garantias de callback, backpressure, pausas por sessao e reclamacao fora do callback presentes no contrato Prometeu. O simples uso de SoLoud nao resolve essas responsabilidades. Defaults mutaveis de `Sound` tambem diferem dos samples imutaveis atuais.
|
||||
|
||||
### 5. Limites de trabalho e fallback fazem parte de um algoritmo
|
||||
|
||||
**Fato:** o solver de [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) limita tentativas com `MAX_HITS=10` e restaura a posicao inicial ao atingir o limite. [`MeshCollider`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/meshcollider.cpp) descarta candidatos por uma hierarquia de AABBs antes de testar triangulos. A hierarquia e interna a cada mesh; as listas de objetos por tipo nao constituem um broad phase espacial global.
|
||||
|
||||
**Licao:** limitar trabalho, definir comportamento de esgotamento e distinguir filtragem barata de trabalho detalhado sao responsabilidades explicitas do algoritmo. A presenca de uma aceleracao local nao demonstra que o custo do sistema inteiro esteja limitado.
|
||||
|
||||
**Aplicabilidade:** usar esse exemplo como criterio de revisao dos mecanismos nativos que ja possuem quotas e limites: verificar a unidade de trabalho, onde o custo aparece, o estado preservado em recusa e a ausencia de efeitos parciais indevidos. Um algoritmo nativo novo precisaria definir esses aspectos antes de ser proposto como contrato de maquina.
|
||||
|
||||
**Limite e transferencia:** overlap/sweep 2D, movimento contra tilemap e respostas de gameplay passam para a pesquisa de core/SDK no Studio. Esta agenda nao propoe periferico de colisao, syscall, fisica ou 3D. Os limites e epsilons do Blitz nao sao valores recomendados para o Prometeu.
|
||||
|
||||
### 6. Metadata do provider precisa de autoridade e representacao explicitas
|
||||
|
||||
**Fato:** o Blitz registra interfaces em `rtSym` e as expoe por [`Runtime::nextSym`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime_dll/bbruntime_dll.cpp). O Prometeu ja oferece [`syscalls::catalogue()`](../../../crates/console/prometeu-hal/src/syscalls.rs), `intrinsic_catalog()` e [exportacao de catalogos](../../../crates/console/prometeu-vm/src/catalog.rs).
|
||||
|
||||
**Licao:** metadata com owner conhecido torna observavel o contrato que um consumer pretende usar. Identidade, ABI, custos e efeitos precisam permanecer coerentes com execucao e validacao; representacao compartilhavel nao significa compartilhar ponteiros ou layouts nativos.
|
||||
|
||||
**Aplicabilidade:** manter a distincao entre catalogo de intrinsics, catalogo de syscalls e Registry por imagem. Qualquer investigacao deve verificar a fidelidade do provider e suas evidencias de exportacao, sem presumir que catalogos distintos tenham os mesmos campos ou finalidade.
|
||||
|
||||
**Limite e transferencia:** porte do catalogo para Java, declaracoes SDK, nomes de parametros PBS, hover, completion, signature help e documentacao da API pertencem ao Studio. A pesquisa de coerencia desses consumidores foi transferida integralmente; nao e obrigacao de implementacao desta agenda. Nenhuma mudanca de formato de catalogo e proposta aqui.
|
||||
|
||||
### 7. Validacao da maquina e independente da experiencia de debug
|
||||
|
||||
**Fato:** verificacoes de existencia de banco e limites em [`bbbank.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime/bbbank.cpp) sao condicionadas a `debug`. O debugger Blitz tambem acessa declaracoes e estruturas do compilador por ponteiros.
|
||||
|
||||
**Licao:** informacao adicional de debug e validacao obrigatoria sao responsabilidades diferentes. A maquina precisa conservar suas regras de seguranca em todos os modos; representacoes consumidas fora do owner devem ter um contrato proprio.
|
||||
|
||||
**Aplicabilidade:** usar esse contraponto para avaliar loader/verifier, handles, limites e interpretacao de metadata/faults existentes, preservando o resultado logico entre modos. O runtime recebe metadados PBX e fornece contexto de execucao e faults pelos contratos publicados; isso nao o torna owner da sintaxe de origem ou da UI.
|
||||
|
||||
**Limite e transferencia:** emissao de nomes/spans pelo compilador e apresentacao de diagnosticos ao autor pertencem ao Studio. A agenda de Studio conserva os exemplos de `StmtNode::debug` e `debugtree.cpp`. Nenhuma perda de origem ou divergencia de validacao foi demonstrada no Prometeu por esta pesquisa.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Aprofundar caches e ownership a partir de um workload
|
||||
|
||||
- **Abordagem:** seguir invalidacao, retencao e reconstrucao no composer/asset/audio atual, motivado por uma carga ou erro observavel.
|
||||
- **Pro:** compara mecanismos concretos disponiveis neste repositorio.
|
||||
- **Contra:** pode nao encontrar problema; precisa medir antes de recomendar otimizacao.
|
||||
- **Tradeoff:** melhor ponto de partida para investigacao interna com alvo delimitado.
|
||||
|
||||
### Opcao B - Examinar fronteiras e publicacao em cenarios adversos
|
||||
|
||||
- **Abordagem:** usar render descartado, pausa, headless e esgotamento de trabalho para revisar independencia entre fases e efeitos de comandos.
|
||||
- **Pro:** aproveita os contraexemplos concretos do Blitz e os contratos ja publicados.
|
||||
- **Contra:** uma revisao ampla pode repetir evidencia existente sem acrescentar informacao.
|
||||
- **Tradeoff:** escolher somente um cenario com duvida concreta, preservando quotas, ordering e ownership vigentes.
|
||||
|
||||
### Opcao C - Reter a pesquisa como referencia para necessidades futuras
|
||||
|
||||
- **Abordagem:** manter mecanismos e limites documentados, retomando quando houver proposta ou problema correspondente.
|
||||
- **Pro:** evita inventar trabalho sem evidencia de necessidade.
|
||||
- **Contra:** nao produz uma nova medicao ou revisao interna agora.
|
||||
- **Tradeoff:** adequada enquanto os achados apenas corroborarem o desenho atual.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Manter **C** como estado desta pesquisa. Se surgir problema observavel de custo/retencao, priorizar **A**. Se a duvida for acoplamento ou ordem entre fases, selecionar um cenario de **B**.
|
||||
|
||||
Os aprendizados mais diretamente transferiveis ao runtime sao protocolos de validade de cache, separacao entre payload e uso, preparacao antes da publicacao e limites com fallback explicito. As fronteiras fechadas de render e audio do Prometeu ja respondem a parte dos riscos observados no Blitz. Nao ha evidencia, nesta analise, que justifique substitui-las.
|
||||
|
||||
## Transferencia e Fronteiras de Responsabilidade
|
||||
|
||||
Separacao solicitada pelo usuario em 2026-11-04. Destino de autoria/ferramentas: [DSC-0100 / AGD-0102](../../../../studio/discussion/workflow/agendas/AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md). Os IDs pertencem a indices independentes por repositorio.
|
||||
|
||||
| Tema da pesquisa original | Permanece no runtime | Responsabilidade transferida ao Studio |
|
||||
| --- | --- | --- |
|
||||
| API por tarefa completa | Somente respeito aos contratos de maquina consumidos | Ergonomia de linguagem/core/SDK, imports e percurso de autoria. |
|
||||
| Metadata ate a IDE | Autoridade, representacao e fidelidade dos catalogos do provider | Porte/importacao, projecoes semanticas, ajuda e documentacao da API. |
|
||||
| Caches e invalidacao | Protocolos de validade, dependencia e reconstrucao interna | Nenhuma investigacao interna de cache transferida. |
|
||||
| Recursos compartilhados | Identidade, residencia, owners e parametros por uso | Eventuais abstracoes de instancia de core/SDK, quando houver caso de uso. |
|
||||
| Atualizacao e apresentacao | Fases, snapshots, clocks e independencia do audio/render | Conveniencias de atualizacao/desenho de gameplay, respeitando suas discussoes locais. |
|
||||
| Preparar audio antes de publicar | Comandos completos, publicacao, callback e reclamacao | Nenhuma entrega de audio SDK criada ou reativada. |
|
||||
| Colisao e trabalho limitado | Principio de limite/fallback e custo das consultas | Hipoteses de helpers geometricos e respostas de gameplay em biblioteca. |
|
||||
| Exemplos pequenos | Fornecimento dos contratos/host de execucao existentes | Ensino, corpus de autoria e encaminhamento de qualificacao instalada ao owner existente. |
|
||||
| Debugging e origem | Validacao da maquina, leitura de metadata e faults | Emissao de origem pelo compilador e experiencia de diagnostico do autor. |
|
||||
|
||||
As perguntas e sugestoes de evidencia transferidas estao detalhadas na agenda de destino. A transferencia nao equivale a implementacao, validacao ou aceite tecnico. A agenda de runtime nao depende do fechamento de nenhuma agenda do Studio.
|
||||
|
||||
Escolha de host/backend continua com [DSC-0047 / AGD-0050](AGD-0050-portable-host-backend-strategy.md). Background service/media continua com [DSC-0045 / AGD-0048](AGD-0048-background-service-audio-execution.md). Esta pesquisa nao adiciona obrigacoes a essas discussoes.
|
||||
|
||||
Os achados continuam em agenda de pesquisa; nao sao publicados como `discussion/lessons/`, pois nao derivam de nova decisao executada no Prometeu.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] Existe workload ou erro observavel que justifique investigar invalidacao/reconstrucao de cache ou retencao de owners?
|
||||
- [ ] Qual dependencia interna especifica merece revisao, e qual estado publicado permitiria demonstra-la?
|
||||
- [ ] Ha cenario de render descartado, pausa ou headless cuja independencia de audio/simulacao ainda precise de evidencia?
|
||||
- [ ] Algum mecanismo nativo tem limite de trabalho ou fallback ainda insuficientemente demonstrado?
|
||||
- [ ] Ha inconsistencia concreta entre metadata exportada pelo provider e seu comportamento, sem confundir isso com a adaptacao feita pelos consumers?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
A pesquisa comparativa esta entregue com fontes, aplicabilidade e limites. A separacao organizacional esta concluida quando a agenda Studio preservar os itens recebidos, os links cruzados resolverem e os dois workflows validarem.
|
||||
|
||||
Para uma futura decisao de mudanca no runtime, selecionar um problema concreto de sua responsabilidade, confirmar evidencia e fechar alternativas/comportamento. A pesquisa nao cria um plano de implementacao nem uma exigencia de alterar mecanismos que ja cumprem seu contrato.
|
||||
|
||||
## Proximo Passo Sugerido
|
||||
|
||||
Retomar o achado correspondente quando houver workload, defeito ou proposta concreta de runtime. Autoria e ferramentas prosseguem na agenda Studio, com escopo independente.
|
||||
|
||||
## Validacao da Pesquisa
|
||||
|
||||
- Leitura estatica em commit fixo; fontes originais preservadas entre as duas agendas.
|
||||
- Implementacoes existentes de catalogos, snapshots, caches e staging reconhecidas explicitamente.
|
||||
- Sem benchmarks, teste de execucao ou avaliacao perceptual do Blitz.
|
||||
- Separacao editorial de agendas; nenhuma alteracao em specs ou implementacao e nenhum item transferido marcado como executado.
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0002"
|
||||
workId: "WRK-0003"
|
||||
discussionId: "main"
|
||||
kind: "NOTE"
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T16:03:21.853210Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
Continuidade consolidada em WRK-000E, tópico TOP-0001, por solicitação do usuário de reunir o contexto do Blitz3D em um Work multi-repo. Pesquisa e evidências originais preservadas neste registro e copiadas integralmente para o novo Work. Este registro independente será cancelado e arquivado por consolidação organizacional; suas propostas continuam abertas no destino e nenhuma implementação foi declarada concluída. A identidade de importação é mantida neste Work para evitar duplicações em reimportações.
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-0003"
|
||||
title: "runtime: Licoes de engenharia do Blitz3D para o Prometeu"
|
||||
description: "Imported Discussion Framework discussion DSC-0069 from runtime (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime).\n\
|
||||
\nTargets:\n- runtime"
|
||||
goal: "Licoes de engenharia do Blitz3D para o Prometeu"
|
||||
motivation: "Continue the open agendas of runtime/DSC-0069"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "CANCELLED"
|
||||
createdAt: "2026-11-16T15:25:23.076931Z"
|
||||
updatedAt: "2026-11-16T16:03:23.635536Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
- "DSC-0002"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events:
|
||||
- action: "STATUS"
|
||||
by: "codex"
|
||||
reason: "Consolidado em WRK-000E (TOP-0001), Work multi-repo runtime e studio; contexto\
|
||||
\ e evidências preservados; pesquisa continua no destino."
|
||||
at: "2026-11-16T16:03:22.325384Z"
|
||||
- action: "ARCHIVE"
|
||||
by: "codex"
|
||||
reason: "Registro de origem preservado; continuidade em WRK-000E, tópico TOP-0001;\
|
||||
\ arquivamento por consolidação multi-repo."
|
||||
at: "2026-11-16T16:03:23.635536Z"
|
||||
archived: true
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-0004"
|
||||
origin: "discussion-framework:runtime:AGD-0002:AGD-0002-packed-cartridge-loader-pmc.md"
|
||||
purpose: "Original DF agenda AGD-0002"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "80ab84bd2df268e68bbf10c4195823ebde6d1424d3787d5d2ad4cd675ba5579e"
|
||||
size: 4715
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.118328Z"
|
||||
+118
@@ -0,0 +1,118 @@
|
||||
---
|
||||
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
|
||||
|
||||
O loader reconhece a extensão `.pmc`, mas o caminho empacotado ainda nao existe de verdade.
|
||||
|
||||
Hoje o dispatcher aceita a intenção e delega para um loader que sempre falha com `InvalidFormat`.
|
||||
|
||||
## Dor
|
||||
|
||||
- A plataforma declara dois formatos de entrada, mas só um funciona.
|
||||
- Distribuição real de cartuchos fica travada no layout de diretório.
|
||||
- Host, firmware e ferramentas nao conseguem validar o caminho de distribuição final.
|
||||
- O runtime continua dependente de estrutura de workspace em vez de artefato fechado.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Definir o formato e o contrato do cartucho empacotado `.pmc` como artefato de distribuição do runtime.
|
||||
|
||||
O objetivo nao é só "descompactar um zip", e sim fixar:
|
||||
|
||||
- layout interno;
|
||||
- regras de validação;
|
||||
- limites de compatibilidade;
|
||||
- superfície de erro;
|
||||
- impacto em assinatura/versionamento futuro.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Container.
|
||||
O `.pmc` é zip, tar, formato próprio, ou envelope simples com header e blobs?
|
||||
|
||||
2. Estrutura interna.
|
||||
Quais arquivos são obrigatórios e opcionais:
|
||||
- `manifest.json`
|
||||
- `program.pbx`
|
||||
- `assets.pa`
|
||||
- outros metadados
|
||||
|
||||
3. Regras de validação.
|
||||
Ordem de parsing, integridade, presença de arquivos, tamanho máximo, duplicatas e versão suportada.
|
||||
|
||||
4. Política de compatibilidade.
|
||||
Como o loader reage a versões futuras do container e do manifesto.
|
||||
|
||||
5. Segurança e determinismo.
|
||||
Como impedir traversal, nomes ambíguos, arquivos extras maliciosos e dependência da ordem física do container.
|
||||
|
||||
6. Relação com o loader de diretório.
|
||||
O comportamento validado deve ser idêntico entre diretório e `.pmc`, mudando apenas a origem dos bytes.
|
||||
|
||||
## O Que Necessita Para Resolver
|
||||
|
||||
- especificação mínima do container `.pmc`;
|
||||
- decisão sobre biblioteca/abordagem de parsing;
|
||||
- matriz de erros determinísticos;
|
||||
- testes com cartuchos sintéticos válidos e inválidos;
|
||||
- garantia de equivalência comportamental com o loader de diretório.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- compressão otimizada;
|
||||
- assinatura criptográfica;
|
||||
- distribuição incremental;
|
||||
- pipeline completo do builder/packer.
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver definição escrita de:
|
||||
|
||||
- formato do `.pmc`;
|
||||
- arquivos obrigatórios;
|
||||
- erros canônicos;
|
||||
- invariantes de segurança;
|
||||
- estratégia de testes de compatibilidade entre diretório e pacote;
|
||||
- equivalência observável entre diretório e `.pmc` para qualquer host que use `CartridgeLoader`, incluindo o host desktop e o host headless de `AGD-0052`.
|
||||
|
||||
## Revalidação — 2026-09-22
|
||||
|
||||
Revalidada contra o código atual e contra `AGD-0052` / `DSC-0049` (Headless Automation Host and Deterministic Runtime Control). A agenda permanece aberta.
|
||||
|
||||
### O que permanece
|
||||
|
||||
`PackedCartridgeLoader::load` ainda retorna `CartridgeError::InvalidFormat` sem ler o arquivo. O dispatcher continua aceitando a extensão `.pmc` e delegando para esse stub. O loader de diretório é o caminho real: `manifest.json`, `program.pbx` e `assets.pa` quando a capability de asset exige. Boot direto (`BootTarget::Cartridge`) e o host desktop usam esse mesmo `CartridgeLoader`.
|
||||
|
||||
O problema original segue válido: a plataforma anuncia dois formatos e só o diretório funciona.
|
||||
|
||||
### Efeito da direção headless
|
||||
|
||||
`AGD-0052` coloca o host headless como consumidor novo do loader, e deixa o formato `.pmc` fora do primeiro ciclo. O primeiro boot automatizado usa cartucho de diretório, o mesmo artefato que o host desktop já carrega.
|
||||
|
||||
Consequências para esta agenda:
|
||||
|
||||
- headless, CI e agente não definem o container;
|
||||
- quando `.pmc` existir, diretório e pacote precisam materializar o mesmo cartucho lógico, para o determinismo não depender da origem dos bytes;
|
||||
- a ordem física do container continua impedida de alterar o resultado, como o item de segurança e determinismo já pedia;
|
||||
- esta agenda não absorve captura de framebuffer, replay ou protocolo de automação.
|
||||
|
||||
### O que não mudou no critério
|
||||
|
||||
Formato, arquivos obrigatórios, erros canônicos, invariantes de segurança e testes de equivalência continuam sendo o fechamento. O critério de saída ganhou só a exigência de que essa equivalência valha para todo host do `CartridgeLoader`.
|
||||
|
||||
### Perguntas que continuam abertas
|
||||
|
||||
- [ ] O `.pmc` é zip, tar, formato próprio ou envelope com header e blobs?
|
||||
- [ ] Quais entradas são obrigatórias além das que o loader de diretório já exige?
|
||||
- [ ] Qual matriz de erro determinística substitui o `InvalidFormat` genérico do stub?
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-0004"
|
||||
origin: "discussion-framework:runtime:DSC-0003:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0003"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "ae5f9bda0000cf932e18634f8210dca991e80e66ecfc6eec6f23173dc18d5d32"
|
||||
size: 387
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.122184Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"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-09-22","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-09-22"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-0004"
|
||||
origin: "ai-engineering:discussion-import:runtime:DSC-0003"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "f394e07ec4a22ca1722a87da09a317d799d79444c0ec92245a714743a1ea273b"
|
||||
size: 681
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.128085Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0004",
|
||||
"sourceId" : "runtime",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime",
|
||||
"dscId" : "DSC-0003",
|
||||
"targets" : [ "runtime" ],
|
||||
"contentHash" : "f2a2fab6209dc491cbe9829c70c97a9a5fd96f9203ebfda734e868ee03adf370",
|
||||
"dscSha256" : "ae5f9bda0000cf932e18634f8210dca991e80e66ecfc6eec6f23173dc18d5d32",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0002",
|
||||
"file" : "AGD-0002-packed-cartridge-loader-pmc.md",
|
||||
"sha256" : "80ab84bd2df268e68bbf10c4195823ebde6d1424d3787d5d2ad4cd675ba5579e",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+130
@@ -0,0 +1,130 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-0004"
|
||||
discussionId: "df:runtime:AGD-0002"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:runtime"
|
||||
createdAt: "2026-11-16T15:25:23.114493Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
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
|
||||
|
||||
O loader reconhece a extensão `.pmc`, mas o caminho empacotado ainda nao existe de verdade.
|
||||
|
||||
Hoje o dispatcher aceita a intenção e delega para um loader que sempre falha com `InvalidFormat`.
|
||||
|
||||
## Dor
|
||||
|
||||
- A plataforma declara dois formatos de entrada, mas só um funciona.
|
||||
- Distribuição real de cartuchos fica travada no layout de diretório.
|
||||
- Host, firmware e ferramentas nao conseguem validar o caminho de distribuição final.
|
||||
- O runtime continua dependente de estrutura de workspace em vez de artefato fechado.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Definir o formato e o contrato do cartucho empacotado `.pmc` como artefato de distribuição do runtime.
|
||||
|
||||
O objetivo nao é só "descompactar um zip", e sim fixar:
|
||||
|
||||
- layout interno;
|
||||
- regras de validação;
|
||||
- limites de compatibilidade;
|
||||
- superfície de erro;
|
||||
- impacto em assinatura/versionamento futuro.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Container.
|
||||
O `.pmc` é zip, tar, formato próprio, ou envelope simples com header e blobs?
|
||||
|
||||
2. Estrutura interna.
|
||||
Quais arquivos são obrigatórios e opcionais:
|
||||
- `manifest.json`
|
||||
- `program.pbx`
|
||||
- `assets.pa`
|
||||
- outros metadados
|
||||
|
||||
3. Regras de validação.
|
||||
Ordem de parsing, integridade, presença de arquivos, tamanho máximo, duplicatas e versão suportada.
|
||||
|
||||
4. Política de compatibilidade.
|
||||
Como o loader reage a versões futuras do container e do manifesto.
|
||||
|
||||
5. Segurança e determinismo.
|
||||
Como impedir traversal, nomes ambíguos, arquivos extras maliciosos e dependência da ordem física do container.
|
||||
|
||||
6. Relação com o loader de diretório.
|
||||
O comportamento validado deve ser idêntico entre diretório e `.pmc`, mudando apenas a origem dos bytes.
|
||||
|
||||
## O Que Necessita Para Resolver
|
||||
|
||||
- especificação mínima do container `.pmc`;
|
||||
- decisão sobre biblioteca/abordagem de parsing;
|
||||
- matriz de erros determinísticos;
|
||||
- testes com cartuchos sintéticos válidos e inválidos;
|
||||
- garantia de equivalência comportamental com o loader de diretório.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- compressão otimizada;
|
||||
- assinatura criptográfica;
|
||||
- distribuição incremental;
|
||||
- pipeline completo do builder/packer.
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver definição escrita de:
|
||||
|
||||
- formato do `.pmc`;
|
||||
- arquivos obrigatórios;
|
||||
- erros canônicos;
|
||||
- invariantes de segurança;
|
||||
- estratégia de testes de compatibilidade entre diretório e pacote;
|
||||
- equivalência observável entre diretório e `.pmc` para qualquer host que use `CartridgeLoader`, incluindo o host desktop e o host headless de `AGD-0052`.
|
||||
|
||||
## Revalidação — 2026-09-22
|
||||
|
||||
Revalidada contra o código atual e contra `AGD-0052` / `DSC-0049` (Headless Automation Host and Deterministic Runtime Control). A agenda permanece aberta.
|
||||
|
||||
### O que permanece
|
||||
|
||||
`PackedCartridgeLoader::load` ainda retorna `CartridgeError::InvalidFormat` sem ler o arquivo. O dispatcher continua aceitando a extensão `.pmc` e delegando para esse stub. O loader de diretório é o caminho real: `manifest.json`, `program.pbx` e `assets.pa` quando a capability de asset exige. Boot direto (`BootTarget::Cartridge`) e o host desktop usam esse mesmo `CartridgeLoader`.
|
||||
|
||||
O problema original segue válido: a plataforma anuncia dois formatos e só o diretório funciona.
|
||||
|
||||
### Efeito da direção headless
|
||||
|
||||
`AGD-0052` coloca o host headless como consumidor novo do loader, e deixa o formato `.pmc` fora do primeiro ciclo. O primeiro boot automatizado usa cartucho de diretório, o mesmo artefato que o host desktop já carrega.
|
||||
|
||||
Consequências para esta agenda:
|
||||
|
||||
- headless, CI e agente não definem o container;
|
||||
- quando `.pmc` existir, diretório e pacote precisam materializar o mesmo cartucho lógico, para o determinismo não depender da origem dos bytes;
|
||||
- a ordem física do container continua impedida de alterar o resultado, como o item de segurança e determinismo já pedia;
|
||||
- esta agenda não absorve captura de framebuffer, replay ou protocolo de automação.
|
||||
|
||||
### O que não mudou no critério
|
||||
|
||||
Formato, arquivos obrigatórios, erros canônicos, invariantes de segurança e testes de equivalência continuam sendo o fechamento. O critério de saída ganhou só a exigência de que essa equivalência valha para todo host do `CartridgeLoader`.
|
||||
|
||||
### Perguntas que continuam abertas
|
||||
|
||||
- [ ] O `.pmc` é zip, tar, formato próprio ou envelope com header e blobs?
|
||||
- [ ] Quais entradas são obrigatórias além das que o loader de diretório já exige?
|
||||
- [ ] Qual matriz de erro determinística substitui o `InvalidFormat` genérico do stub?
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-0004"
|
||||
title: "runtime: Agenda - Packed Cartridge Loader PMC"
|
||||
description: "Imported Discussion Framework discussion DSC-0003 from runtime (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime).\n\
|
||||
\nTargets:\n- runtime"
|
||||
goal: "Agenda - Packed Cartridge Loader PMC"
|
||||
motivation: "Continue the open agendas of runtime/DSC-0003"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "OPEN"
|
||||
createdAt: "2026-11-16T15:25:23.113069Z"
|
||||
updatedAt: "2026-11-16T15:25:23.133316Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events: []
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-0005"
|
||||
origin: "discussion-framework:runtime:AGD-0004:AGD-0004-system-fault-semantics-and-control-surface.md"
|
||||
purpose: "Original DF agenda AGD-0004"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "bbb7b272ab0419fc99caadd6a4a5a18462ca48bce8ced321103a0bd58c9c8322"
|
||||
size: 4441
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.149270Z"
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
---
|
||||
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
|
||||
|
||||
O domínio `system` exposto à userland ficou pequeno, e a política de retorno dele ainda não está escrita.
|
||||
|
||||
Estado em 2026-09-22:
|
||||
|
||||
- a superfície gerada é só `system.has_cart` (`Syscall::SystemHasCart`), com 1 retorno e capability `SYSTEM`;
|
||||
- o dispatch devolve `true` fixo, sem consultar cartucho e sem `status`;
|
||||
- `system.run_cart` saiu da ABI de userland. Launch de cartucho é ação de SystemOS/firmware/host (`LSN-0051`, `DSC-0004`);
|
||||
- fault de execução da VM já tem forma estruturada em `CrashReport` (`VmTrap`, `VmPanic`, `VmInit`), observada pelo host e pelo debugger.
|
||||
|
||||
O texto de 2026-03-27 tratava `SystemRunCart` como operação ainda sem efeito e apontava a agenda `009` e `virtual_machine_runtime/dispatch.rs`. Esses dois pontos ficaram obsoletos. A política de fault do que permanece no domínio `system` continua aberta.
|
||||
|
||||
## Dor
|
||||
|
||||
- `has_cart` pode permanecer um bool fixo e mascarar ausência, cartucho inválido ou consulta fora de autoridade;
|
||||
- uma futura operação de `system` pode herdar `Trap` ou `Panic` onde o contrato transversal pede `status`;
|
||||
- automação headless (`AGD-0052`) precisa observar fault estruturado sem que esta agenda redesenhe `CrashReport` nem invente syscall de controle para CI ou agente.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- `crates/console/prometeu-hal/src/syscalls/domains/system.rs`
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` (`SystemHasCart` retorna `true`)
|
||||
- `crates/console/prometeu-system/src/crash_report.rs`
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md`
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar a política de fault e retorno do domínio `system` que ainda é visível à userland, e separar essa política da observação de fault de VM feita pelo host.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Queries simples.
|
||||
Decidir a política de `has_cart`: bool atual, `status` mais payload, ou outra forma compatível com `16a`. Incluir o que a consulta realmente observa.
|
||||
|
||||
2. Operações que não voltam para a userland.
|
||||
`run_cart` permanece fora da ABI de convidado. Falha de boot direto continua no caminho de host/firmware (`CartridgeError`, `CrashReport::VmInit`, transição de firmware), não como syscall de app.
|
||||
|
||||
3. Relação com firmware e com o host.
|
||||
Delimitar falha de app, falha de firmware e falha de runtime. `CrashReport` é a observação estruturada de Trap/Panic/init. `summary()` e log são apresentação, não o contrato.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `LSN-0051` / `DSC-0004`
|
||||
- `AGD-0052` / `DSC-0049`, apenas como consumidor da observação estruturada
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar decision quando houver definição escrita sobre:
|
||||
|
||||
- matriz de `status` / `Trap` / `Panic` para as operações userland que o domínio `system` mantém, começando por `has_cart`;
|
||||
- confirmação de que launch de cartucho permanece fora da ABI de convidado;
|
||||
- fronteira entre retorno operacional de syscall, erro de loader/boot e `CrashReport`.
|
||||
|
||||
## Revalidação — 2026-09-22
|
||||
|
||||
Revalidada contra o código atual e contra `AGD-0052`. A agenda permanece aberta. O alvo encolheu: ela não reabre `run_cart`.
|
||||
|
||||
### O que a direção headless muda
|
||||
|
||||
`AGD-0052` exige que automação distinga execução em curso, pause, término, `Trap` e `Panic` lendo dados estruturados. Esse requisito observa `CrashReport` e o estado da VM. Ele não altera a semântica normativa de fault de outros domínios e não cria syscall `system` para controle headless.
|
||||
|
||||
Esta agenda continua dona da matriz de retorno de `system`. A agenda headless continua dona de como o host expõe o fault que já existe.
|
||||
|
||||
### Perguntas que continuam abertas
|
||||
|
||||
- [ ] `has_cart` passa a ter `status` e um significado real de presença de cartucho, ou o bool atual é o contrato e o stub `true` é o bug a corrigir em outra discussão?
|
||||
- [ ] Alguma falha de boot direto precisa ser visível ao convidado, ou toda falha de launch permanece em host, firmware e `CrashReport`?
|
||||
- [ ] Quais campos de `CrashReport` são o contrato observável (`kind`, `pc`, `trap.code`) e quais são só texto de log?
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-0005"
|
||||
origin: "discussion-framework:runtime:DSC-0005:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0005"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "88505bb1e25db9b0fea8846a17033a2415e3f5cd07b6f48f7f234d1b35a6bffb"
|
||||
size: 432
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.155791Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"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-09-22","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-09-22"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-0005"
|
||||
origin: "ai-engineering:discussion-import:runtime:DSC-0005"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "cdd2da153e3516116074d07b4e8958a6e8a2f3057926b53a38ec69d23d063331"
|
||||
size: 696
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.162712Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0005",
|
||||
"sourceId" : "runtime",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime",
|
||||
"dscId" : "DSC-0005",
|
||||
"targets" : [ "runtime" ],
|
||||
"contentHash" : "f8dac3339cbf84bb502f09fbf526596662357aa5e2f0bb79b4808a30d794d70b",
|
||||
"dscSha256" : "88505bb1e25db9b0fea8846a17033a2415e3f5cd07b6f48f7f234d1b35a6bffb",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0004",
|
||||
"file" : "AGD-0004-system-fault-semantics-and-control-surface.md",
|
||||
"sha256" : "bbb7b272ab0419fc99caadd6a4a5a18462ca48bce8ced321103a0bd58c9c8322",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+96
@@ -0,0 +1,96 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-0005"
|
||||
discussionId: "df:runtime:AGD-0004"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:runtime"
|
||||
createdAt: "2026-11-16T15:25:23.145618Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
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
|
||||
|
||||
O domínio `system` exposto à userland ficou pequeno, e a política de retorno dele ainda não está escrita.
|
||||
|
||||
Estado em 2026-09-22:
|
||||
|
||||
- a superfície gerada é só `system.has_cart` (`Syscall::SystemHasCart`), com 1 retorno e capability `SYSTEM`;
|
||||
- o dispatch devolve `true` fixo, sem consultar cartucho e sem `status`;
|
||||
- `system.run_cart` saiu da ABI de userland. Launch de cartucho é ação de SystemOS/firmware/host (`LSN-0051`, `DSC-0004`);
|
||||
- fault de execução da VM já tem forma estruturada em `CrashReport` (`VmTrap`, `VmPanic`, `VmInit`), observada pelo host e pelo debugger.
|
||||
|
||||
O texto de 2026-03-27 tratava `SystemRunCart` como operação ainda sem efeito e apontava a agenda `009` e `virtual_machine_runtime/dispatch.rs`. Esses dois pontos ficaram obsoletos. A política de fault do que permanece no domínio `system` continua aberta.
|
||||
|
||||
## Dor
|
||||
|
||||
- `has_cart` pode permanecer um bool fixo e mascarar ausência, cartucho inválido ou consulta fora de autoridade;
|
||||
- uma futura operação de `system` pode herdar `Trap` ou `Panic` onde o contrato transversal pede `status`;
|
||||
- automação headless (`AGD-0052`) precisa observar fault estruturado sem que esta agenda redesenhe `CrashReport` nem invente syscall de controle para CI ou agente.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- `crates/console/prometeu-hal/src/syscalls/domains/system.rs`
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` (`SystemHasCart` retorna `true`)
|
||||
- `crates/console/prometeu-system/src/crash_report.rs`
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md`
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar a política de fault e retorno do domínio `system` que ainda é visível à userland, e separar essa política da observação de fault de VM feita pelo host.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Queries simples.
|
||||
Decidir a política de `has_cart`: bool atual, `status` mais payload, ou outra forma compatível com `16a`. Incluir o que a consulta realmente observa.
|
||||
|
||||
2. Operações que não voltam para a userland.
|
||||
`run_cart` permanece fora da ABI de convidado. Falha de boot direto continua no caminho de host/firmware (`CartridgeError`, `CrashReport::VmInit`, transição de firmware), não como syscall de app.
|
||||
|
||||
3. Relação com firmware e com o host.
|
||||
Delimitar falha de app, falha de firmware e falha de runtime. `CrashReport` é a observação estruturada de Trap/Panic/init. `summary()` e log são apresentação, não o contrato.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `LSN-0051` / `DSC-0004`
|
||||
- `AGD-0052` / `DSC-0049`, apenas como consumidor da observação estruturada
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar decision quando houver definição escrita sobre:
|
||||
|
||||
- matriz de `status` / `Trap` / `Panic` para as operações userland que o domínio `system` mantém, começando por `has_cart`;
|
||||
- confirmação de que launch de cartucho permanece fora da ABI de convidado;
|
||||
- fronteira entre retorno operacional de syscall, erro de loader/boot e `CrashReport`.
|
||||
|
||||
## Revalidação — 2026-09-22
|
||||
|
||||
Revalidada contra o código atual e contra `AGD-0052`. A agenda permanece aberta. O alvo encolheu: ela não reabre `run_cart`.
|
||||
|
||||
### O que a direção headless muda
|
||||
|
||||
`AGD-0052` exige que automação distinga execução em curso, pause, término, `Trap` e `Panic` lendo dados estruturados. Esse requisito observa `CrashReport` e o estado da VM. Ele não altera a semântica normativa de fault de outros domínios e não cria syscall `system` para controle headless.
|
||||
|
||||
Esta agenda continua dona da matriz de retorno de `system`. A agenda headless continua dona de como o host expõe o fault que já existe.
|
||||
|
||||
### Perguntas que continuam abertas
|
||||
|
||||
- [ ] `has_cart` passa a ter `status` e um significado real de presença de cartucho, ou o bool atual é o contrato e o stub `true` é o bug a corrigir em outra discussão?
|
||||
- [ ] Alguma falha de boot direto precisa ser visível ao convidado, ou toda falha de launch permanece em host, firmware e `CrashReport`?
|
||||
- [ ] Quais campos de `CrashReport` são o contrato observável (`kind`, `pc`, `trap.code`) e quais são só texto de log?
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-0005"
|
||||
title: "runtime: Agenda - System Fault Semantics and Control Surface"
|
||||
description: "Imported Discussion Framework discussion DSC-0005 from runtime (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime).\n\
|
||||
\nTargets:\n- runtime"
|
||||
goal: "Agenda - System Fault Semantics and Control Surface"
|
||||
motivation: "Continue the open agendas of runtime/DSC-0005"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "OPEN"
|
||||
createdAt: "2026-11-16T15:25:23.144144Z"
|
||||
updatedAt: "2026-11-16T15:25:23.169505Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events: []
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-0006"
|
||||
origin: "discussion-framework:runtime:AGD-0006:AGD-0006-app-home-filesystem-surface-and-semantics.md"
|
||||
purpose: "Original DF agenda AGD-0006"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "0c4f795341bb3fd75abda724b97a00ac51661651aac9dd2709ecf41d33038aad"
|
||||
size: 4827
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.187439Z"
|
||||
+157
@@ -0,0 +1,157 @@
|
||||
---
|
||||
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
|
||||
|
||||
Apps precisam de filesystem util para dados de usuario, cache e configuracao, mas sem acesso ao FS inteiro do host.
|
||||
|
||||
Sem um contrato claro de `home` por app, a API tende a crescer com semantica inconsistente entre plataformas.
|
||||
|
||||
## Inputs Ja Fechados
|
||||
|
||||
1. Todo `app` acessa somente sua `home` logica.
|
||||
2. Nunca ha acesso direto ao filesystem global do host pela userland.
|
||||
3. O runtime `fs` interno continua cobrindo tanto `game` quanto `app`.
|
||||
4. Existe uma async IO lane compartilhavel por assets, memcard e FS. Esta
|
||||
agenda deve decidir a API publica de FS considerando essa lane, mas a
|
||||
existencia da lane ja esta fechada por `DEC-0034`.
|
||||
|
||||
## Fronteira com a Async IO Lane
|
||||
|
||||
`DEC-0034` fecha a existencia de uma lane serial para trabalho async de IO. FS
|
||||
pode consumir essa lane internamente para escrita, configuracao, leitura ou
|
||||
listagem, conforme prioridade operacional definida pelo runtime.
|
||||
|
||||
Esta agenda continua dona da decisao sobre API publica de FS para `app home`.
|
||||
Portanto, a existencia da lane nao implica criar agora request handles, polling
|
||||
publico ou novas syscalls de FS. Esses shapes permanecem em aberto aqui.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar a superficie e semantica funcional de `fs` para perfil `app`, com sandbox por `app_id` e transporte de bytes via decisao `003`.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Surface minima do perfil `app`.
|
||||
Operacoes candidatas:
|
||||
- `read`;
|
||||
- `write`;
|
||||
- `exists`;
|
||||
- `stat`;
|
||||
- `list_dir`;
|
||||
- `delete`;
|
||||
- `mkdir`;
|
||||
- `rename`.
|
||||
|
||||
2. Modelo de caminho logico.
|
||||
Definir:
|
||||
- raiz virtual (`home`);
|
||||
- normalizacao de path;
|
||||
- bloqueio de path traversal;
|
||||
- limites de profundidade/tamanho.
|
||||
|
||||
3. Mapeamento host.
|
||||
Definir:
|
||||
- como `home` vira caminho fisico no host;
|
||||
- isolamento entre apps por `app_id`;
|
||||
- regras de portabilidade entre hosts.
|
||||
|
||||
4. Semantica de leitura/escrita.
|
||||
Definir:
|
||||
- leitura total vs parcial;
|
||||
- overwrite vs append;
|
||||
- truncation;
|
||||
- criacao implicita;
|
||||
- escrita atomica por arquivo (quando aplicavel).
|
||||
|
||||
5. Quotas e capacidade.
|
||||
Definir:
|
||||
- se v1 tem quota por app;
|
||||
- comportamento para `storage full`;
|
||||
- exposicao de metrica de uso livre/ocupado.
|
||||
|
||||
6. Metadados e listagem.
|
||||
Definir:
|
||||
- campos minimos de `stat`;
|
||||
- shape canonico de `list_dir`;
|
||||
- timestamps (sim/nao e com qual garantia).
|
||||
|
||||
7. Fault/status do dominio.
|
||||
Fechar fronteira de:
|
||||
- `status` operacional;
|
||||
- `Trap` estrutural;
|
||||
- `Panic` interno.
|
||||
E obrigatorio fechar, por operacao, a matriz final de retorno e fault class.
|
||||
|
||||
## Responsabilidade Absorvida da Agenda 003
|
||||
|
||||
No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para:
|
||||
|
||||
1. Catalogo de `status` de filesystem para app.
|
||||
Minimo esperado:
|
||||
- `OK`;
|
||||
- `NOT_FOUND`;
|
||||
- `PATH_INVALID`;
|
||||
- `ACCESS_DENIED`;
|
||||
- `NO_SPACE`;
|
||||
- `ALREADY_EXISTS`;
|
||||
- `UNAVAILABLE`.
|
||||
|
||||
2. Matriz por operacao (`read`, `write`, `exists`, `stat`, `list_dir`, `delete`, `mkdir`, `rename`).
|
||||
Para cada caso, classificar explicitamente:
|
||||
- `status`;
|
||||
- `Trap`;
|
||||
- `Panic`.
|
||||
|
||||
3. Shape de retorno por operacao.
|
||||
Definir, no minimo:
|
||||
- `status` como primeiro retorno;
|
||||
- `bytes_transferred` em `read`/`write` quando aplicavel;
|
||||
- payload de metadados/listagem com formato canonico.
|
||||
|
||||
4. Regra de escrita parcial.
|
||||
`write` nao pode reportar sucesso parcial silencioso.
|
||||
Quando a operacao nao puder ser concluida conforme contrato, deve retornar falha de dominio.
|
||||
|
||||
## Open Questions de Arquitetura
|
||||
|
||||
1. O v1 precisa de quota fixa por app ou apenas limites fisicos do host?
|
||||
2. `rename` entra no MVP ou pode ficar para fase seguinte?
|
||||
3. Qual conjunto minimo de metadados garante portabilidade real entre hosts?
|
||||
4. Qual grau de atomicidade e obrigatorio para escrita de arquivo no v1?
|
||||
5. Quais operacoes de FS devem consumir a async IO lane e quais permanecem
|
||||
sincrono-aparentes para a userland?
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../decisions/003-vm-owned-byte-transfer-protocol.md`
|
||||
- `../decisions/007-filesystem-fault-core-policy.md`
|
||||
- `../specs/13-cartridge.md`
|
||||
- `../specs/12-firmware-pos-and-prometeuhub.md`
|
||||
- `../specs/16a-syscall-policies.md`
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- slots de memcard para `game` (fechado na `spec 08`);
|
||||
- acesso cross-app;
|
||||
- sync remoto/cloud;
|
||||
- DB embutido como contrato de plataforma.
|
||||
|
||||
## Criterio de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- surface minima de `fs` para `app` em `home`;
|
||||
- sandbox e isolamento por `app_id`;
|
||||
- semantica final de path/read/write/listagem;
|
||||
- matriz completa de fault/status para as operacoes do perfil `app`.
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-0006"
|
||||
origin: "discussion-framework:runtime:DSC-0007:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0007"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "5e358004fc7e111aba402382e007c522ce400b4409c066e7fc6fdeedc74aca53"
|
||||
size: 429
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.192641Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"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":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-0006"
|
||||
origin: "ai-engineering:discussion-import:runtime:DSC-0007"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "9469bb205cb8741de2d7784085278bd91df07dccc5e93b3cdc16c841a0a5e0a8"
|
||||
size: 695
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.201142Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0006",
|
||||
"sourceId" : "runtime",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime",
|
||||
"dscId" : "DSC-0007",
|
||||
"targets" : [ "runtime" ],
|
||||
"contentHash" : "05f8ae299eecab1ff91b0dbad15246fc360c5ae63ff2f2e04a143b5e9b8e7812",
|
||||
"dscSha256" : "5e358004fc7e111aba402382e007c522ce400b4409c066e7fc6fdeedc74aca53",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0006",
|
||||
"file" : "AGD-0006-app-home-filesystem-surface-and-semantics.md",
|
||||
"sha256" : "0c4f795341bb3fd75abda724b97a00ac51661651aac9dd2709ecf41d33038aad",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+169
@@ -0,0 +1,169 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-0006"
|
||||
discussionId: "df:runtime:AGD-0006"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:runtime"
|
||||
createdAt: "2026-11-16T15:25:23.183505Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
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
|
||||
|
||||
Apps precisam de filesystem util para dados de usuario, cache e configuracao, mas sem acesso ao FS inteiro do host.
|
||||
|
||||
Sem um contrato claro de `home` por app, a API tende a crescer com semantica inconsistente entre plataformas.
|
||||
|
||||
## Inputs Ja Fechados
|
||||
|
||||
1. Todo `app` acessa somente sua `home` logica.
|
||||
2. Nunca ha acesso direto ao filesystem global do host pela userland.
|
||||
3. O runtime `fs` interno continua cobrindo tanto `game` quanto `app`.
|
||||
4. Existe uma async IO lane compartilhavel por assets, memcard e FS. Esta
|
||||
agenda deve decidir a API publica de FS considerando essa lane, mas a
|
||||
existencia da lane ja esta fechada por `DEC-0034`.
|
||||
|
||||
## Fronteira com a Async IO Lane
|
||||
|
||||
`DEC-0034` fecha a existencia de uma lane serial para trabalho async de IO. FS
|
||||
pode consumir essa lane internamente para escrita, configuracao, leitura ou
|
||||
listagem, conforme prioridade operacional definida pelo runtime.
|
||||
|
||||
Esta agenda continua dona da decisao sobre API publica de FS para `app home`.
|
||||
Portanto, a existencia da lane nao implica criar agora request handles, polling
|
||||
publico ou novas syscalls de FS. Esses shapes permanecem em aberto aqui.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar a superficie e semantica funcional de `fs` para perfil `app`, com sandbox por `app_id` e transporte de bytes via decisao `003`.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Surface minima do perfil `app`.
|
||||
Operacoes candidatas:
|
||||
- `read`;
|
||||
- `write`;
|
||||
- `exists`;
|
||||
- `stat`;
|
||||
- `list_dir`;
|
||||
- `delete`;
|
||||
- `mkdir`;
|
||||
- `rename`.
|
||||
|
||||
2. Modelo de caminho logico.
|
||||
Definir:
|
||||
- raiz virtual (`home`);
|
||||
- normalizacao de path;
|
||||
- bloqueio de path traversal;
|
||||
- limites de profundidade/tamanho.
|
||||
|
||||
3. Mapeamento host.
|
||||
Definir:
|
||||
- como `home` vira caminho fisico no host;
|
||||
- isolamento entre apps por `app_id`;
|
||||
- regras de portabilidade entre hosts.
|
||||
|
||||
4. Semantica de leitura/escrita.
|
||||
Definir:
|
||||
- leitura total vs parcial;
|
||||
- overwrite vs append;
|
||||
- truncation;
|
||||
- criacao implicita;
|
||||
- escrita atomica por arquivo (quando aplicavel).
|
||||
|
||||
5. Quotas e capacidade.
|
||||
Definir:
|
||||
- se v1 tem quota por app;
|
||||
- comportamento para `storage full`;
|
||||
- exposicao de metrica de uso livre/ocupado.
|
||||
|
||||
6. Metadados e listagem.
|
||||
Definir:
|
||||
- campos minimos de `stat`;
|
||||
- shape canonico de `list_dir`;
|
||||
- timestamps (sim/nao e com qual garantia).
|
||||
|
||||
7. Fault/status do dominio.
|
||||
Fechar fronteira de:
|
||||
- `status` operacional;
|
||||
- `Trap` estrutural;
|
||||
- `Panic` interno.
|
||||
E obrigatorio fechar, por operacao, a matriz final de retorno e fault class.
|
||||
|
||||
## Responsabilidade Absorvida da Agenda 003
|
||||
|
||||
No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para:
|
||||
|
||||
1. Catalogo de `status` de filesystem para app.
|
||||
Minimo esperado:
|
||||
- `OK`;
|
||||
- `NOT_FOUND`;
|
||||
- `PATH_INVALID`;
|
||||
- `ACCESS_DENIED`;
|
||||
- `NO_SPACE`;
|
||||
- `ALREADY_EXISTS`;
|
||||
- `UNAVAILABLE`.
|
||||
|
||||
2. Matriz por operacao (`read`, `write`, `exists`, `stat`, `list_dir`, `delete`, `mkdir`, `rename`).
|
||||
Para cada caso, classificar explicitamente:
|
||||
- `status`;
|
||||
- `Trap`;
|
||||
- `Panic`.
|
||||
|
||||
3. Shape de retorno por operacao.
|
||||
Definir, no minimo:
|
||||
- `status` como primeiro retorno;
|
||||
- `bytes_transferred` em `read`/`write` quando aplicavel;
|
||||
- payload de metadados/listagem com formato canonico.
|
||||
|
||||
4. Regra de escrita parcial.
|
||||
`write` nao pode reportar sucesso parcial silencioso.
|
||||
Quando a operacao nao puder ser concluida conforme contrato, deve retornar falha de dominio.
|
||||
|
||||
## Open Questions de Arquitetura
|
||||
|
||||
1. O v1 precisa de quota fixa por app ou apenas limites fisicos do host?
|
||||
2. `rename` entra no MVP ou pode ficar para fase seguinte?
|
||||
3. Qual conjunto minimo de metadados garante portabilidade real entre hosts?
|
||||
4. Qual grau de atomicidade e obrigatorio para escrita de arquivo no v1?
|
||||
5. Quais operacoes de FS devem consumir a async IO lane e quais permanecem
|
||||
sincrono-aparentes para a userland?
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../decisions/003-vm-owned-byte-transfer-protocol.md`
|
||||
- `../decisions/007-filesystem-fault-core-policy.md`
|
||||
- `../specs/13-cartridge.md`
|
||||
- `../specs/12-firmware-pos-and-prometeuhub.md`
|
||||
- `../specs/16a-syscall-policies.md`
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- slots de memcard para `game` (fechado na `spec 08`);
|
||||
- acesso cross-app;
|
||||
- sync remoto/cloud;
|
||||
- DB embutido como contrato de plataforma.
|
||||
|
||||
## Criterio de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- surface minima de `fs` para `app` em `home`;
|
||||
- sandbox e isolamento por `app_id`;
|
||||
- semantica final de path/read/write/listagem;
|
||||
- matriz completa de fault/status para as operacoes do perfil `app`.
|
||||
+32
@@ -0,0 +1,32 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-0006"
|
||||
title: "runtime: Agenda - App Home Filesystem Surface and Semantics"
|
||||
description: "Imported Discussion Framework discussion DSC-0007 from runtime (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime).\n\
|
||||
\nTargets:\n- runtime"
|
||||
goal: "Agenda - App Home Filesystem Surface and Semantics"
|
||||
motivation: "Continue the open agendas of runtime/DSC-0007"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "OPEN"
|
||||
createdAt: "2026-11-16T15:25:23.181794Z"
|
||||
updatedAt: "2026-11-16T15:25:23.206790Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events: []
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-0007"
|
||||
origin: "discussion-framework:runtime:AGD-0048:AGD-0048-background-service-audio-execution.md"
|
||||
purpose: "Original DF agenda AGD-0048"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "80e4ea2ff05e93f357973608729ac305f620a98520f4e7cb22ec04ddfefa298e"
|
||||
size: 8451
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.236546Z"
|
||||
+208
@@ -0,0 +1,208 @@
|
||||
---
|
||||
id: AGD-0048
|
||||
ticket: background-service-audio-execution
|
||||
title: Agenda - Background Service and Audio Execution
|
||||
status: open
|
||||
created: 2026-07-05
|
||||
resolved:
|
||||
decision:
|
||||
tags: [runtime, os, lifecycle, service, audio, background, architecture]
|
||||
---
|
||||
|
||||
# Agenda - Background Service and Audio Execution
|
||||
|
||||
## Contexto
|
||||
|
||||
O runtime ja tem sinais claros de preparacao para multitarefa controlada:
|
||||
|
||||
- `TaskState::Background` existe como estado de tarefa;
|
||||
- `VmSession` separa estado mutavel de VM por tarefa/processo;
|
||||
- `SystemOS` e dono de lifecycle, task/process, VM sessions, filesystem,
|
||||
memcard, windows e logging;
|
||||
- a spec de eventos separa foreground ownership de execution eligibility;
|
||||
- o contrato atual declara que execucao real em background fica fora do v1, mas
|
||||
o modelo foi desenhado para permitir servicos ou processos de midia no futuro.
|
||||
|
||||
O caso motivador e:
|
||||
|
||||
```text
|
||||
Game foreground -> Home -> music player -> escolher musica -> voltar ao Game
|
||||
```
|
||||
|
||||
Depois disso, o Game deve voltar ao foreground enquanto o player continua
|
||||
executando e produzindo audio junto com audio do Game.
|
||||
|
||||
## Problema
|
||||
|
||||
Hoje o runtime preserva sessoes, mas nao tem contrato para uma sessao continuar
|
||||
executando quando nao e foreground.
|
||||
|
||||
Os pontos atuais que bloqueiam o caso:
|
||||
|
||||
- `TaskKind` so distingue `Game` e `Shell`;
|
||||
- `ProcessKind` so distingue `VmGame`, `VmShell` e `NativeShell`;
|
||||
- `ProcessState` nao possui estado normativo de background-running;
|
||||
- `GameRunningStep` ticka apenas o Game foreground;
|
||||
- `ShellRunningStep` ticka apenas o Shell foreground;
|
||||
- `HubHomeStep` nao ticka sessoes VM em background;
|
||||
- `Audio` e `AudioMixer` usam vozes globais sem namespace por tarefa/sessao;
|
||||
- cada logical frame chama `platform.audio_mut().clear_commands()`, o que torna
|
||||
perigoso tickar dois produtores de audio no mesmo frame;
|
||||
- pausa de lifecycle hoje emite `MasterPause`, afetando o mixer inteiro.
|
||||
|
||||
Sem uma decisao, background service pode virar apenas "tickar mais uma VM", mas
|
||||
isso quebraria isolamento, audio, debugger, lifecycle e previsibilidade.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
1. **Execution eligibility nao e foreground.**
|
||||
O contrato atual ja separa os conceitos, mas a implementacao ainda so ticka o
|
||||
owner foreground. Precisamos introduzir uma politica explicita de quem pode
|
||||
executar em background.
|
||||
|
||||
2. **Servico nao e Shell escondido.**
|
||||
Um music player pode ter UI de Shell para escolher musica, mas a reproducao
|
||||
continua como servico quando a UI deixa o foreground. Fechar isso como
|
||||
`Shell` em background confundiria janela, tarefa, sessao e servico.
|
||||
|
||||
3. **Audio precisa de origem.**
|
||||
Hoje `voice_id` e global no mixer. Se Game e player usam `voice_id = 0`, um
|
||||
sobrescreve o outro. Precisamos decidir se o mixer tera namespaces por
|
||||
`AudioOwner`, se servicos terao pool dedicado, ou se o player nao usara a
|
||||
mesma superficie `audio.*`.
|
||||
|
||||
4. **Pausa de Game nao pode pausar servico de midia.**
|
||||
`MasterPause` global serve para o contrato atual de pausa/debug, mas nao
|
||||
expressa "pausar Game audio e manter music player". Pausa precisa virar
|
||||
escopo por origem ou politica de mixer.
|
||||
|
||||
5. **Servico precisa de lifecycle proprio.**
|
||||
Deve existir contrato para start, foreground UI, background-running, stop,
|
||||
crash, terminate, recurso negado, e talvez wake/resume de UI.
|
||||
|
||||
6. **Budget e determinismo precisam ser fechados.**
|
||||
Se servicos rodam junto com Game, precisamos decidir cota por frame, ordem de
|
||||
ticks, starvation, crash isolation, e se background service participa do
|
||||
mesmo tempo deterministico da maquina.
|
||||
|
||||
7. **Sistema de apps precisa descobrir e lancar o player.**
|
||||
Hoje Home lista Game cartridges e tem Shells nativos fixos. O caso de music
|
||||
player exige decidir se ele e cartridge `System`, app instalado, Shell nativo,
|
||||
ou novo perfil `Service`.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Background Service como novo tipo de processo/sessao
|
||||
|
||||
Criar contrato explicito para `Service`:
|
||||
|
||||
- `TaskKind::Service` ou entidade equivalente;
|
||||
- `ProcessKind::VmService` / `NativeService`;
|
||||
- execution eligibility independente de foreground;
|
||||
- UI de controle opcional via Shell task associada ao servico;
|
||||
- audio com origem por service/session;
|
||||
- lifecycle proprio: start, background, foreground-control, stop, crash.
|
||||
|
||||
**Pros:**
|
||||
- modela diretamente music player e futuros servicos;
|
||||
- preserva a separacao entre UI foreground e execucao;
|
||||
- evita transformar Shell em "processo que tambem e daemon";
|
||||
- facilita quotas, permissao e observabilidade.
|
||||
|
||||
**Contras:**
|
||||
- maior mudanca arquitetural;
|
||||
- exige novo contrato em specs, SystemOS, firmware, audio e testes;
|
||||
- precisa fechar politica de recursos antes de implementar.
|
||||
|
||||
**Manutencao:**
|
||||
- melhor base para crescer com qualidade, desde que o MVP seja pequeno.
|
||||
|
||||
### Opcao B - Shell em background com audio permitido
|
||||
|
||||
Permitir que uma VM Shell continue tickando quando sai do foreground e use audio
|
||||
normalmente.
|
||||
|
||||
**Pros:**
|
||||
- reaproveita Shell, WindowManager e VM session existentes;
|
||||
- menor numero de novos tipos no curto prazo.
|
||||
|
||||
**Contras:**
|
||||
- mistura UI e servico;
|
||||
- torna `TaskState::Background` semantico antes de definir `ProcessState`;
|
||||
- abre precedente para qualquer Shell continuar executando;
|
||||
- nao resolve sozinho namespace de audio, pause por origem, quotas e debugging.
|
||||
|
||||
**Manutencao:**
|
||||
- atraente como atalho, mas tende a espalhar excecoes pela firmware state
|
||||
machine.
|
||||
|
||||
### Opcao C - Audio player como servico nativo OS-owned, sem VM background
|
||||
|
||||
Implementar music player como servico nativo de SystemOS, controlado por uma
|
||||
Shell UI. A reproducao continua no host/OS sem tickar VM em background.
|
||||
|
||||
**Pros:**
|
||||
- entrega o caso de musica com menor risco para scheduler VM;
|
||||
- evita abrir execucao arbitraria de background agora;
|
||||
- audio service pode ser projetado como recurso OS-owned e depois exposto.
|
||||
|
||||
**Contras:**
|
||||
- nao resolve background VM services em geral;
|
||||
- player deixa de ser app userland completo no primeiro ciclo;
|
||||
- precisa ainda fechar origem/mixagem de audio e relacao com UI.
|
||||
|
||||
**Manutencao:**
|
||||
- bom MVP se o objetivo imediato for media playback, mas deve ser declarado como
|
||||
`media service` nativo, nao como contrato geral de background VM.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendo fechar em duas camadas:
|
||||
|
||||
1. **Decisao de arquitetura:** introduzir o conceito de service/background
|
||||
execution como contrato de SystemOS, separado de foreground Shell e Game.
|
||||
Essa decisao deve definir execution eligibility, lifecycle, quotas, crash
|
||||
policy, controle de UI e relacao com VM sessions.
|
||||
|
||||
2. **MVP de media:** implementar primeiro um `media/audio service` com escopo
|
||||
reduzido, preferencialmente OS-owned ou `Service` bem delimitado, antes de
|
||||
permitir background VM arbitrario.
|
||||
|
||||
Para excelente qualidade, o primeiro plano nao deve tentar "qualquer app em
|
||||
background". O alvo deve ser: um unico servico de audio/midia, com origem de
|
||||
audio propria, controle por Hub/Shell, execucao enquanto Game esta foreground,
|
||||
e testes end-to-end de mistura e lifecycle.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- O music player deve ser um cartridge `System`, um novo `Service`, ou um
|
||||
servico nativo do OS controlado por Shell?
|
||||
- A UI do player e a reproducao pertencem a mesma tarefa ou a tarefas
|
||||
separadas?
|
||||
- Um servico pode ter janela foreground temporaria e continuar sem janela?
|
||||
- Quantos servicos background podem existir no MVP: um media service ou N
|
||||
servicos?
|
||||
- O background service recebe ticks todo frame, tick rate reduzido, ou apenas
|
||||
eventos?
|
||||
- O audio mixer deve isolar vozes por `TaskId`, `ProcessId`, `VmSessionId`,
|
||||
`AppId`, ou novo `AudioOwner`?
|
||||
- Como pausar apenas o audio do Game durante Home/debug sem pausar musica?
|
||||
- O debugger inspeciona foreground session apenas ou tambem sessoes background?
|
||||
- Como crash de servico e exibido: toast/log, janela de crash, ou parada
|
||||
silenciosa com diagnostico?
|
||||
- Que capacidades sao necessarias para media service: `audio`, `fs`, `asset`,
|
||||
talvez `background_audio`?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode virar decisao quando houver resposta escrita para:
|
||||
|
||||
- modelo de entidade (`Service` novo vs Shell background vs native OS service);
|
||||
- execution eligibility e ordem de ticks;
|
||||
- lifecycle e estados de task/process;
|
||||
- ownership/namespace de audio e politica de pausa por origem;
|
||||
- relacao entre UI foreground do player e reproducao background;
|
||||
- escopo do MVP e explicitamente o que fica fora;
|
||||
- testes obrigatorios de lifecycle, audio mixing, crash isolation e regressao do
|
||||
contrato Game/Home/Shell existente.
|
||||
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-0007"
|
||||
origin: "discussion-framework:runtime:DSC-0045:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0045"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "9a01f9f16b023732c733084b3a8c1f7499b0af8a24169a9c1b845d82fa6b96a0"
|
||||
size: 475
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.243592Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0045","status":"open","ticket":"background-service-audio-execution","title":"Background Service and Audio Execution","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","service","audio","background","architecture"],"agendas":[{"id":"AGD-0048","file":"AGD-0048-background-service-audio-execution.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-0007"
|
||||
origin: "ai-engineering:discussion-import:runtime:DSC-0045"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "5b5aa25db4a35af4b4cfc3142f19d0502f470d9d31921bde46361e34c6b29acc"
|
||||
size: 688
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.251031Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0007",
|
||||
"sourceId" : "runtime",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime",
|
||||
"dscId" : "DSC-0045",
|
||||
"targets" : [ "runtime" ],
|
||||
"contentHash" : "04d7ed9a7fb64c4c7d9cb2f044d6dbd36ec7e30aa69a8288bc5cd9186ef17cfe",
|
||||
"dscSha256" : "9a01f9f16b023732c733084b3a8c1f7499b0af8a24169a9c1b845d82fa6b96a0",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0048",
|
||||
"file" : "AGD-0048-background-service-audio-execution.md",
|
||||
"sha256" : "80e4ea2ff05e93f357973608729ac305f620a98520f4e7cb22ec04ddfefa298e",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+220
@@ -0,0 +1,220 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-0007"
|
||||
discussionId: "df:runtime:AGD-0048"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:runtime"
|
||||
createdAt: "2026-11-16T15:25:23.232114Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
id: AGD-0048
|
||||
ticket: background-service-audio-execution
|
||||
title: Agenda - Background Service and Audio Execution
|
||||
status: open
|
||||
created: 2026-07-05
|
||||
resolved:
|
||||
decision:
|
||||
tags: [runtime, os, lifecycle, service, audio, background, architecture]
|
||||
---
|
||||
|
||||
# Agenda - Background Service and Audio Execution
|
||||
|
||||
## Contexto
|
||||
|
||||
O runtime ja tem sinais claros de preparacao para multitarefa controlada:
|
||||
|
||||
- `TaskState::Background` existe como estado de tarefa;
|
||||
- `VmSession` separa estado mutavel de VM por tarefa/processo;
|
||||
- `SystemOS` e dono de lifecycle, task/process, VM sessions, filesystem,
|
||||
memcard, windows e logging;
|
||||
- a spec de eventos separa foreground ownership de execution eligibility;
|
||||
- o contrato atual declara que execucao real em background fica fora do v1, mas
|
||||
o modelo foi desenhado para permitir servicos ou processos de midia no futuro.
|
||||
|
||||
O caso motivador e:
|
||||
|
||||
```text
|
||||
Game foreground -> Home -> music player -> escolher musica -> voltar ao Game
|
||||
```
|
||||
|
||||
Depois disso, o Game deve voltar ao foreground enquanto o player continua
|
||||
executando e produzindo audio junto com audio do Game.
|
||||
|
||||
## Problema
|
||||
|
||||
Hoje o runtime preserva sessoes, mas nao tem contrato para uma sessao continuar
|
||||
executando quando nao e foreground.
|
||||
|
||||
Os pontos atuais que bloqueiam o caso:
|
||||
|
||||
- `TaskKind` so distingue `Game` e `Shell`;
|
||||
- `ProcessKind` so distingue `VmGame`, `VmShell` e `NativeShell`;
|
||||
- `ProcessState` nao possui estado normativo de background-running;
|
||||
- `GameRunningStep` ticka apenas o Game foreground;
|
||||
- `ShellRunningStep` ticka apenas o Shell foreground;
|
||||
- `HubHomeStep` nao ticka sessoes VM em background;
|
||||
- `Audio` e `AudioMixer` usam vozes globais sem namespace por tarefa/sessao;
|
||||
- cada logical frame chama `platform.audio_mut().clear_commands()`, o que torna
|
||||
perigoso tickar dois produtores de audio no mesmo frame;
|
||||
- pausa de lifecycle hoje emite `MasterPause`, afetando o mixer inteiro.
|
||||
|
||||
Sem uma decisao, background service pode virar apenas "tickar mais uma VM", mas
|
||||
isso quebraria isolamento, audio, debugger, lifecycle e previsibilidade.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
1. **Execution eligibility nao e foreground.**
|
||||
O contrato atual ja separa os conceitos, mas a implementacao ainda so ticka o
|
||||
owner foreground. Precisamos introduzir uma politica explicita de quem pode
|
||||
executar em background.
|
||||
|
||||
2. **Servico nao e Shell escondido.**
|
||||
Um music player pode ter UI de Shell para escolher musica, mas a reproducao
|
||||
continua como servico quando a UI deixa o foreground. Fechar isso como
|
||||
`Shell` em background confundiria janela, tarefa, sessao e servico.
|
||||
|
||||
3. **Audio precisa de origem.**
|
||||
Hoje `voice_id` e global no mixer. Se Game e player usam `voice_id = 0`, um
|
||||
sobrescreve o outro. Precisamos decidir se o mixer tera namespaces por
|
||||
`AudioOwner`, se servicos terao pool dedicado, ou se o player nao usara a
|
||||
mesma superficie `audio.*`.
|
||||
|
||||
4. **Pausa de Game nao pode pausar servico de midia.**
|
||||
`MasterPause` global serve para o contrato atual de pausa/debug, mas nao
|
||||
expressa "pausar Game audio e manter music player". Pausa precisa virar
|
||||
escopo por origem ou politica de mixer.
|
||||
|
||||
5. **Servico precisa de lifecycle proprio.**
|
||||
Deve existir contrato para start, foreground UI, background-running, stop,
|
||||
crash, terminate, recurso negado, e talvez wake/resume de UI.
|
||||
|
||||
6. **Budget e determinismo precisam ser fechados.**
|
||||
Se servicos rodam junto com Game, precisamos decidir cota por frame, ordem de
|
||||
ticks, starvation, crash isolation, e se background service participa do
|
||||
mesmo tempo deterministico da maquina.
|
||||
|
||||
7. **Sistema de apps precisa descobrir e lancar o player.**
|
||||
Hoje Home lista Game cartridges e tem Shells nativos fixos. O caso de music
|
||||
player exige decidir se ele e cartridge `System`, app instalado, Shell nativo,
|
||||
ou novo perfil `Service`.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Background Service como novo tipo de processo/sessao
|
||||
|
||||
Criar contrato explicito para `Service`:
|
||||
|
||||
- `TaskKind::Service` ou entidade equivalente;
|
||||
- `ProcessKind::VmService` / `NativeService`;
|
||||
- execution eligibility independente de foreground;
|
||||
- UI de controle opcional via Shell task associada ao servico;
|
||||
- audio com origem por service/session;
|
||||
- lifecycle proprio: start, background, foreground-control, stop, crash.
|
||||
|
||||
**Pros:**
|
||||
- modela diretamente music player e futuros servicos;
|
||||
- preserva a separacao entre UI foreground e execucao;
|
||||
- evita transformar Shell em "processo que tambem e daemon";
|
||||
- facilita quotas, permissao e observabilidade.
|
||||
|
||||
**Contras:**
|
||||
- maior mudanca arquitetural;
|
||||
- exige novo contrato em specs, SystemOS, firmware, audio e testes;
|
||||
- precisa fechar politica de recursos antes de implementar.
|
||||
|
||||
**Manutencao:**
|
||||
- melhor base para crescer com qualidade, desde que o MVP seja pequeno.
|
||||
|
||||
### Opcao B - Shell em background com audio permitido
|
||||
|
||||
Permitir que uma VM Shell continue tickando quando sai do foreground e use audio
|
||||
normalmente.
|
||||
|
||||
**Pros:**
|
||||
- reaproveita Shell, WindowManager e VM session existentes;
|
||||
- menor numero de novos tipos no curto prazo.
|
||||
|
||||
**Contras:**
|
||||
- mistura UI e servico;
|
||||
- torna `TaskState::Background` semantico antes de definir `ProcessState`;
|
||||
- abre precedente para qualquer Shell continuar executando;
|
||||
- nao resolve sozinho namespace de audio, pause por origem, quotas e debugging.
|
||||
|
||||
**Manutencao:**
|
||||
- atraente como atalho, mas tende a espalhar excecoes pela firmware state
|
||||
machine.
|
||||
|
||||
### Opcao C - Audio player como servico nativo OS-owned, sem VM background
|
||||
|
||||
Implementar music player como servico nativo de SystemOS, controlado por uma
|
||||
Shell UI. A reproducao continua no host/OS sem tickar VM em background.
|
||||
|
||||
**Pros:**
|
||||
- entrega o caso de musica com menor risco para scheduler VM;
|
||||
- evita abrir execucao arbitraria de background agora;
|
||||
- audio service pode ser projetado como recurso OS-owned e depois exposto.
|
||||
|
||||
**Contras:**
|
||||
- nao resolve background VM services em geral;
|
||||
- player deixa de ser app userland completo no primeiro ciclo;
|
||||
- precisa ainda fechar origem/mixagem de audio e relacao com UI.
|
||||
|
||||
**Manutencao:**
|
||||
- bom MVP se o objetivo imediato for media playback, mas deve ser declarado como
|
||||
`media service` nativo, nao como contrato geral de background VM.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendo fechar em duas camadas:
|
||||
|
||||
1. **Decisao de arquitetura:** introduzir o conceito de service/background
|
||||
execution como contrato de SystemOS, separado de foreground Shell e Game.
|
||||
Essa decisao deve definir execution eligibility, lifecycle, quotas, crash
|
||||
policy, controle de UI e relacao com VM sessions.
|
||||
|
||||
2. **MVP de media:** implementar primeiro um `media/audio service` com escopo
|
||||
reduzido, preferencialmente OS-owned ou `Service` bem delimitado, antes de
|
||||
permitir background VM arbitrario.
|
||||
|
||||
Para excelente qualidade, o primeiro plano nao deve tentar "qualquer app em
|
||||
background". O alvo deve ser: um unico servico de audio/midia, com origem de
|
||||
audio propria, controle por Hub/Shell, execucao enquanto Game esta foreground,
|
||||
e testes end-to-end de mistura e lifecycle.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- O music player deve ser um cartridge `System`, um novo `Service`, ou um
|
||||
servico nativo do OS controlado por Shell?
|
||||
- A UI do player e a reproducao pertencem a mesma tarefa ou a tarefas
|
||||
separadas?
|
||||
- Um servico pode ter janela foreground temporaria e continuar sem janela?
|
||||
- Quantos servicos background podem existir no MVP: um media service ou N
|
||||
servicos?
|
||||
- O background service recebe ticks todo frame, tick rate reduzido, ou apenas
|
||||
eventos?
|
||||
- O audio mixer deve isolar vozes por `TaskId`, `ProcessId`, `VmSessionId`,
|
||||
`AppId`, ou novo `AudioOwner`?
|
||||
- Como pausar apenas o audio do Game durante Home/debug sem pausar musica?
|
||||
- O debugger inspeciona foreground session apenas ou tambem sessoes background?
|
||||
- Como crash de servico e exibido: toast/log, janela de crash, ou parada
|
||||
silenciosa com diagnostico?
|
||||
- Que capacidades sao necessarias para media service: `audio`, `fs`, `asset`,
|
||||
talvez `background_audio`?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode virar decisao quando houver resposta escrita para:
|
||||
|
||||
- modelo de entidade (`Service` novo vs Shell background vs native OS service);
|
||||
- execution eligibility e ordem de ticks;
|
||||
- lifecycle e estados de task/process;
|
||||
- ownership/namespace de audio e politica de pausa por origem;
|
||||
- relacao entre UI foreground do player e reproducao background;
|
||||
- escopo do MVP e explicitamente o que fica fora;
|
||||
- testes obrigatorios de lifecycle, audio mixing, crash isolation e regressao do
|
||||
contrato Game/Home/Shell existente.
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-0007"
|
||||
title: "runtime: Background Service and Audio Execution"
|
||||
description: "Imported Discussion Framework discussion DSC-0045 from runtime (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime).\n\
|
||||
\nTargets:\n- runtime"
|
||||
goal: "Background Service and Audio Execution"
|
||||
motivation: "Continue the open agendas of runtime/DSC-0045"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "OPEN"
|
||||
createdAt: "2026-11-16T15:25:23.229320Z"
|
||||
updatedAt: "2026-11-16T15:25:23.256651Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events: []
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-0008"
|
||||
origin: "discussion-framework:runtime:AGD-0050:AGD-0050-portable-host-backend-strategy.md"
|
||||
purpose: "Original DF agenda AGD-0050"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "7f49d61663aa42251286f12a135594c41bb10c97bdd0bfb1c4a66e217abc74e5"
|
||||
size: 11926
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.275465Z"
|
||||
+140
@@ -0,0 +1,140 @@
|
||||
---
|
||||
id: AGD-0050
|
||||
ticket: portable-host-backend-strategy
|
||||
title: Portable Host Backend Strategy
|
||||
status: open
|
||||
created: 2026-07-14
|
||||
resolved:
|
||||
decision:
|
||||
tags: [host, desktop, portable, sdl, backend, rendering, input, audio, linux, android, handheld]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
O runtime ja tem uma fronteira de host relativamente clara: o host desktop atual vive em `crates/host/prometeu-host-desktop-winit`, usando `winit`, `pixels` e `cpal` para janela, apresentacao de framebuffer, input e audio.
|
||||
|
||||
A direcao desejada nao e substituir esse host de forma disruptiva no primeiro corte. A proposta e estudar e construir um segundo host portatil para servir como runtime host em handhelds e consoles portateis, especialmente hardwares chineses que rodam Linux internamente e, em alguns casos, Android customizado. O mesmo host tambem deve servir como base para uma futura versao DIY do hardware, desde que ela rode sobre um Linux base compatível. SDL e a hipotese principal, mas a agenda tambem deve avaliar outras familias de host/backend antes de virar decisao normativa.
|
||||
|
||||
Esse novo host deve conviver com o host atual durante estabilizacao, mas nao e descartavel: ele e candidato a se tornar o host principal quando provar paridade e estabilidade.
|
||||
|
||||
A troca deve ficar isolada no dominio de host: contratos de runtime, firmware, frame, input semantico e audio semantico nao devem mudar por causa da escolha de backend. Essa separacao e justamente o objetivo arquitetural que permite que um host portatil evolua para principal sem arrastar o runtime.
|
||||
|
||||
## Problema
|
||||
|
||||
Hoje a existencia de um unico host desktop torna dificil separar problemas do runtime de problemas do adaptador de plataforma. Um novo host portatil pode ajudar em testes, portabilidade, comparacao operacional e reducao de dependencia de uma pilha unica de janela/render/audio. O alvo "mobile" desta agenda nao significa telefone/tablet como produto primario; significa hardware portatil dedicado, geralmente com controles fisicos, framebuffer/display integrado, Linux customizado e distribuicao fora do modelo desktop tradicional. O alvo tambem inclui um possivel handheld DIY futuro, em que o valor esperado e ja existir um host pronto se o dispositivo expuser um Linux base suficiente.
|
||||
|
||||
O risco e tratar uma tecnologia especifica como resposta antes de comparar os requisitos reais de Linux handheld e Android. A agenda precisa cravar o modelo de host paralelo em estabilizacao, com destino de host principal, e entao escolher a familia de backend que melhor atende esse objetivo.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- A troca de host deve ser simples e local ao host, sem exigir mudancas em runtime, firmware, asset protocol, render packet, VM ou syscalls.
|
||||
- O novo host precisa consumir as mesmas saidas canonicas do runtime: frames RGBA8888, comandos semanticos de audio e eventos de input normalizados.
|
||||
- A estrategia deve preservar o host `winit` enquanto o novo host ainda nao provar equivalencia operacional, mas o novo host e candidato a virar o host principal depois dessa prova.
|
||||
- O alvo primario e portabilidade operacional para handhelds Linux e consoles portateis com controles fisicos; Android customizado e um alvo possivel que deve influenciar a escolha de API, packaging e input/audio.
|
||||
- O host portatil deve ser viavel em um futuro hardware DIY rodando Linux base, sem exigir um runtime especial ou fork de contratos.
|
||||
- Testes devem distinguir contrato comum de host de detalhes especificos de backend.
|
||||
- SDL2 pode ter ecossistema Rust mais estabelecido; SDL3 pode estar mais alinhado com a direcao upstream. A escolha da versao e uma pergunta separada da decisao de criar um segundo host.
|
||||
- A arquitetura deve evitar duplicar logica de runtime loop, pacing, debugger, stats e presentation policy quando essa logica for comum a qualquer host.
|
||||
- Outras familias de host tambem devem ser avaliadas: evoluir `winit`, SDL2/SDL3, backend Android nativo, ou uma camada multiplataforma alternativa.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Manter apenas o host winit atual
|
||||
|
||||
- **Abordagem:** continuar evoluindo `prometeu-host-desktop-winit` como unico host desktop.
|
||||
- **Pro:** menor custo imediato; evita nova dependencia nativa.
|
||||
- **Con:** mantem a pilha de plataforma unica como ponto de acoplamento pratico.
|
||||
- **Tradeoff:** bom para estabilidade curta, fraco para provar independencia real do host.
|
||||
|
||||
### Opcao B - Migrar diretamente do host winit para outro backend
|
||||
|
||||
- **Abordagem:** substituir o host desktop atual por um novo backend portatil assim que a escolha tecnologica for feita.
|
||||
- **Pro:** reduz a manutencao para um unico host depois da migracao.
|
||||
- **Con:** aumenta risco de regressao e mistura decisao de backend com mudanca operacional.
|
||||
- **Tradeoff:** so faz sentido depois de prova local de superioridade e paridade, o que ainda nao existe.
|
||||
|
||||
### Opcao C - Criar um host SDL paralelo com destino de principal
|
||||
|
||||
- **Abordagem:** adicionar um novo crate/binario de host SDL que implemente os mesmos contratos externos do host atual, mantendo `winit` como referencia e rollback ate haver evidencia de equivalencia.
|
||||
- **Pro:** permite teste A/B, reduz risco, valida se a fronteira de host esta realmente limpa, atende a meta de handheld Linux/Android customizado/DIY e preserva caminho para tornar SDL o host principal.
|
||||
- **Con:** aumenta temporariamente manutencao e exige fatorar partes comuns se houver duplicacao.
|
||||
- **Tradeoff:** melhor caminho para chegar a um host principal portatil sem reabrir runtime.
|
||||
|
||||
### Opcao D - Evoluir winit/pixels/cpal como host portatil
|
||||
|
||||
- **Abordagem:** manter a familia atual e investir em configuracao, input, fullscreen, packaging e compatibilidade de Linux handheld/Android/DIY dentro dela.
|
||||
- **Pro:** reaproveita o host existente e reduz dependencias nativas novas.
|
||||
- **Con:** pode nao resolver os problemas praticos de distribuicao, gamepad/device handling, fullscreen/scaling, Android customizado e ambientes handheld.
|
||||
- **Tradeoff:** forte se a pilha atual suportar bem os alvos; fraco se o problema real for portabilidade operacional.
|
||||
|
||||
### Opcao E - Host Android nativo separado
|
||||
|
||||
- **Abordagem:** tratar Linux handheld e Android como hosts diferentes: SDL ou winit para Linux; Android com camada nativa/propria quando o alvo amadurecer.
|
||||
- **Pro:** permite respeitar o ciclo de vida, packaging, input e audio do Android sem contaminar o host Linux.
|
||||
- **Con:** duplica mais superficie e adia a promessa de um host portatil unico.
|
||||
- **Tradeoff:** bom se Android tiver requisitos proprios demais; ruim se SDL conseguir cobrir Android bem o bastante.
|
||||
|
||||
### Opcao F - Camada multiplataforma alternativa
|
||||
|
||||
- **Abordagem:** avaliar alternativas como uma camada Rust-first ou game-framework-level para janela, input, audio e render.
|
||||
- **Pro:** pode reduzir FFI nativa e integrar melhor com Cargo.
|
||||
- **Con:** pode ser menos madura para Linux handheld/Android real, packaging e controles.
|
||||
- **Tradeoff:** deve ser considerada, mas precisa provar vantagem concreta sobre SDL para justificar risco.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendacao inicial: manter a **Opcao C** como favorita, mas ampliar a fase de agenda para comparar SDL com as demais familias de host antes da decisao. O resultado desejado continua sendo um segundo host portatil, inicialmente paralelo, com destino explicito de se tornar o host principal quando atingir paridade e estabilidade.
|
||||
|
||||
O caminho recomendado e:
|
||||
|
||||
1. Definir o contrato minimo de equivalencia entre hosts: janela, framebuffer RGBA8888, input, audio, pacing, debugger/logs e encerramento.
|
||||
2. Identificar o que e comum ao host e o que e backend especifico.
|
||||
3. Comparar as familias candidatas contra esse contrato: SDL2, SDL3, winit atual evoluido, Android nativo separado e alternativas Rust-first.
|
||||
4. Implementar o candidato escolhido como novo crate/binario sem remover `prometeu-host-desktop-winit`.
|
||||
5. Permitir troca simples por binario/comando/feature, mantendo o runtime cego para a escolha.
|
||||
6. Tratar handheld Linux como alvo primario de produto para esse host; tratar Android customizado e DIY Linux como restricoes de desenho quando afetarem backend, packaging, input, audio ou boot/runtime integration.
|
||||
7. Promover o novo host a principal apenas depois de evidencia de estabilidade e paridade.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] A primeira implementacao SDL deve usar SDL2 ou SDL3?
|
||||
- [ ] SDL deve ser a familia escolhida, ou winit evoluido, Android nativo separado ou outra camada oferece melhor caminho?
|
||||
- [ ] A selecao do host deve ser por binario separado, feature Cargo, parametro CLI, ou combinacao desses mecanismos?
|
||||
- [ ] Qual e o menor conjunto de comportamento que define paridade aceitavel com o host winit?
|
||||
- [ ] Quais partes do host atual devem virar modulo comum antes do SDL, e quais devem ser duplicadas primeiro para evitar abstracao prematura?
|
||||
- [ ] O host SDL deve reutilizar `cpal` para audio inicialmente ou usar audio SDL desde o primeiro corte?
|
||||
- [ ] Quais familias de hardware handheld Linux devem ser usadas como referencia inicial?
|
||||
- [ ] Handheld Linux exige controles/gamepad, fullscreen, scaling, latency, sleep/resume, framebuffer/display mode ou packaging especificos desde o primeiro corte?
|
||||
- [ ] Qual e o "Linux base" minimo que um futuro hardware DIY precisaria expor para rodar o host portatil sem fork?
|
||||
- [ ] Android customizado deve ser criterio de escolha entre SDL2 e SDL3 agora, ou deve ficar como compatibilidade futura?
|
||||
- [ ] Como validar input e pacing de forma automatizada sem depender de janela real em CI? Encaminhada para `AGD-0052` / `DSC-0049`: o host headless é o lugar dessa prova. Esta agenda continua dona da escolha de backend portátil, não do controle determinístico.
|
||||
- [ ] O nome do crate deve ser `prometeu-host-desktop-sdl`, `prometeu-host-desktop-sdl2`, ou algo neutro a versao?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
A agenda pode virar decision quando estiver claro:
|
||||
|
||||
- se o novo host sera paralelo em estabilizacao, com destino de host principal;
|
||||
- qual familia de backend sera alvo inicial;
|
||||
- se SDL for escolhido, qual versao SDL sera alvo inicial;
|
||||
- como a selecao/troca de host deve funcionar;
|
||||
- quais contratos sao comuns e proibidos de mudar;
|
||||
- quais requisitos minimos de handheld Linux e possivel Android customizado entram no primeiro plano;
|
||||
- qual contrato minimo de Linux base mantem aberta a opcao de hardware DIY;
|
||||
- qual evidencia minima prova paridade suficiente para iniciar planos de implementacao.
|
||||
|
||||
## Discussion
|
||||
|
||||
Ponto inicial aceito pelo usuario: a intencao e ter um segundo host para testes, com troca simples e facil, aproveitando o trabalho ja feito para isolar essa troca no host sem envolver runtime ou outros dominios.
|
||||
|
||||
Atualizacao de escopo: o novo host nao e descartavel. O objetivo e servir como runtime host para sistemas Linux rodando em consoles portateis e hardwares handheld chineses, e possivelmente Android customizado. Assim que estiver estavel, ele deve poder virar o host principal.
|
||||
|
||||
Atualizacao de escopo: outras familias de host/backend tambem devem viver nesta agenda. SDL segue como hipotese forte, mas a decisao deve comparar opcoes antes de cravar a tecnologia.
|
||||
|
||||
Clarificacao: "mobile" nesta agenda nao se refere primariamente a telefone/tablet. O foco sao dispositivos portateis dedicados com Linux interno ou Android customizado, geralmente com controles fisicos e ambiente de distribuicao proprio.
|
||||
|
||||
Clarificacao: a agenda tambem deve preservar a opcao de um futuro hardware DIY. A premissa desejada e que, se esse hardware expuser um Linux base suficiente, o runtime ja tenha um host portatil pronto para rodar nele.
|
||||
|
||||
Atualizacao 2026-09-22: `AGD-0052` abre um terceiro host, headless, para teste, CI e controle determinístico em memória. Esse host não substitui o candidato portátil desta agenda e não escolhe SDL. A pergunta de validar input e pacing sem janela em CI passa a ser respondida lá. Extração de loop comum entre winit, SDL e headless continua esperando duplicação real.
|
||||
|
||||
## Resolution
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-0008"
|
||||
origin: "discussion-framework:runtime:DSC-0047:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0047"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "9a07ffe1c7dd8a46c2fb701579b7f11ade8943c83263cdc06eae452c80c0f66c"
|
||||
size: 487
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.282656Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0047","status":"open","ticket":"portable-host-backend-strategy","title":"Portable Host Backend Strategy","created_at":"2026-07-14","updated_at":"2026-09-22","tags":["host","desktop","portable","sdl","backend","rendering","input","audio","linux","android","handheld"],"agendas":[{"id":"AGD-0050","file":"AGD-0050-portable-host-backend-strategy.md","status":"open","created_at":"2026-07-14","updated_at":"2026-09-22"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-0008"
|
||||
origin: "ai-engineering:discussion-import:runtime:DSC-0047"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "a783ee0f0de5b5c211c6c514ce79198a59262575750416ac750036c0399cfd0d"
|
||||
size: 684
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:25:23.288429Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0008",
|
||||
"sourceId" : "runtime",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime",
|
||||
"dscId" : "DSC-0047",
|
||||
"targets" : [ "runtime" ],
|
||||
"contentHash" : "0bc1a131923b7e205a11ce5d3c190d3db3e83b9224a54a1892ad77363c30f3c7",
|
||||
"dscSha256" : "9a07ffe1c7dd8a46c2fb701579b7f11ade8943c83263cdc06eae452c80c0f66c",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0050",
|
||||
"file" : "AGD-0050-portable-host-backend-strategy.md",
|
||||
"sha256" : "7f49d61663aa42251286f12a135594c41bb10c97bdd0bfb1c4a66e217abc74e5",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+152
@@ -0,0 +1,152 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-0008"
|
||||
discussionId: "df:runtime:AGD-0050"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:runtime"
|
||||
createdAt: "2026-11-16T15:25:23.271470Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
id: AGD-0050
|
||||
ticket: portable-host-backend-strategy
|
||||
title: Portable Host Backend Strategy
|
||||
status: open
|
||||
created: 2026-07-14
|
||||
resolved:
|
||||
decision:
|
||||
tags: [host, desktop, portable, sdl, backend, rendering, input, audio, linux, android, handheld]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
O runtime ja tem uma fronteira de host relativamente clara: o host desktop atual vive em `crates/host/prometeu-host-desktop-winit`, usando `winit`, `pixels` e `cpal` para janela, apresentacao de framebuffer, input e audio.
|
||||
|
||||
A direcao desejada nao e substituir esse host de forma disruptiva no primeiro corte. A proposta e estudar e construir um segundo host portatil para servir como runtime host em handhelds e consoles portateis, especialmente hardwares chineses que rodam Linux internamente e, em alguns casos, Android customizado. O mesmo host tambem deve servir como base para uma futura versao DIY do hardware, desde que ela rode sobre um Linux base compatível. SDL e a hipotese principal, mas a agenda tambem deve avaliar outras familias de host/backend antes de virar decisao normativa.
|
||||
|
||||
Esse novo host deve conviver com o host atual durante estabilizacao, mas nao e descartavel: ele e candidato a se tornar o host principal quando provar paridade e estabilidade.
|
||||
|
||||
A troca deve ficar isolada no dominio de host: contratos de runtime, firmware, frame, input semantico e audio semantico nao devem mudar por causa da escolha de backend. Essa separacao e justamente o objetivo arquitetural que permite que um host portatil evolua para principal sem arrastar o runtime.
|
||||
|
||||
## Problema
|
||||
|
||||
Hoje a existencia de um unico host desktop torna dificil separar problemas do runtime de problemas do adaptador de plataforma. Um novo host portatil pode ajudar em testes, portabilidade, comparacao operacional e reducao de dependencia de uma pilha unica de janela/render/audio. O alvo "mobile" desta agenda nao significa telefone/tablet como produto primario; significa hardware portatil dedicado, geralmente com controles fisicos, framebuffer/display integrado, Linux customizado e distribuicao fora do modelo desktop tradicional. O alvo tambem inclui um possivel handheld DIY futuro, em que o valor esperado e ja existir um host pronto se o dispositivo expuser um Linux base suficiente.
|
||||
|
||||
O risco e tratar uma tecnologia especifica como resposta antes de comparar os requisitos reais de Linux handheld e Android. A agenda precisa cravar o modelo de host paralelo em estabilizacao, com destino de host principal, e entao escolher a familia de backend que melhor atende esse objetivo.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- A troca de host deve ser simples e local ao host, sem exigir mudancas em runtime, firmware, asset protocol, render packet, VM ou syscalls.
|
||||
- O novo host precisa consumir as mesmas saidas canonicas do runtime: frames RGBA8888, comandos semanticos de audio e eventos de input normalizados.
|
||||
- A estrategia deve preservar o host `winit` enquanto o novo host ainda nao provar equivalencia operacional, mas o novo host e candidato a virar o host principal depois dessa prova.
|
||||
- O alvo primario e portabilidade operacional para handhelds Linux e consoles portateis com controles fisicos; Android customizado e um alvo possivel que deve influenciar a escolha de API, packaging e input/audio.
|
||||
- O host portatil deve ser viavel em um futuro hardware DIY rodando Linux base, sem exigir um runtime especial ou fork de contratos.
|
||||
- Testes devem distinguir contrato comum de host de detalhes especificos de backend.
|
||||
- SDL2 pode ter ecossistema Rust mais estabelecido; SDL3 pode estar mais alinhado com a direcao upstream. A escolha da versao e uma pergunta separada da decisao de criar um segundo host.
|
||||
- A arquitetura deve evitar duplicar logica de runtime loop, pacing, debugger, stats e presentation policy quando essa logica for comum a qualquer host.
|
||||
- Outras familias de host tambem devem ser avaliadas: evoluir `winit`, SDL2/SDL3, backend Android nativo, ou uma camada multiplataforma alternativa.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Manter apenas o host winit atual
|
||||
|
||||
- **Abordagem:** continuar evoluindo `prometeu-host-desktop-winit` como unico host desktop.
|
||||
- **Pro:** menor custo imediato; evita nova dependencia nativa.
|
||||
- **Con:** mantem a pilha de plataforma unica como ponto de acoplamento pratico.
|
||||
- **Tradeoff:** bom para estabilidade curta, fraco para provar independencia real do host.
|
||||
|
||||
### Opcao B - Migrar diretamente do host winit para outro backend
|
||||
|
||||
- **Abordagem:** substituir o host desktop atual por um novo backend portatil assim que a escolha tecnologica for feita.
|
||||
- **Pro:** reduz a manutencao para um unico host depois da migracao.
|
||||
- **Con:** aumenta risco de regressao e mistura decisao de backend com mudanca operacional.
|
||||
- **Tradeoff:** so faz sentido depois de prova local de superioridade e paridade, o que ainda nao existe.
|
||||
|
||||
### Opcao C - Criar um host SDL paralelo com destino de principal
|
||||
|
||||
- **Abordagem:** adicionar um novo crate/binario de host SDL que implemente os mesmos contratos externos do host atual, mantendo `winit` como referencia e rollback ate haver evidencia de equivalencia.
|
||||
- **Pro:** permite teste A/B, reduz risco, valida se a fronteira de host esta realmente limpa, atende a meta de handheld Linux/Android customizado/DIY e preserva caminho para tornar SDL o host principal.
|
||||
- **Con:** aumenta temporariamente manutencao e exige fatorar partes comuns se houver duplicacao.
|
||||
- **Tradeoff:** melhor caminho para chegar a um host principal portatil sem reabrir runtime.
|
||||
|
||||
### Opcao D - Evoluir winit/pixels/cpal como host portatil
|
||||
|
||||
- **Abordagem:** manter a familia atual e investir em configuracao, input, fullscreen, packaging e compatibilidade de Linux handheld/Android/DIY dentro dela.
|
||||
- **Pro:** reaproveita o host existente e reduz dependencias nativas novas.
|
||||
- **Con:** pode nao resolver os problemas praticos de distribuicao, gamepad/device handling, fullscreen/scaling, Android customizado e ambientes handheld.
|
||||
- **Tradeoff:** forte se a pilha atual suportar bem os alvos; fraco se o problema real for portabilidade operacional.
|
||||
|
||||
### Opcao E - Host Android nativo separado
|
||||
|
||||
- **Abordagem:** tratar Linux handheld e Android como hosts diferentes: SDL ou winit para Linux; Android com camada nativa/propria quando o alvo amadurecer.
|
||||
- **Pro:** permite respeitar o ciclo de vida, packaging, input e audio do Android sem contaminar o host Linux.
|
||||
- **Con:** duplica mais superficie e adia a promessa de um host portatil unico.
|
||||
- **Tradeoff:** bom se Android tiver requisitos proprios demais; ruim se SDL conseguir cobrir Android bem o bastante.
|
||||
|
||||
### Opcao F - Camada multiplataforma alternativa
|
||||
|
||||
- **Abordagem:** avaliar alternativas como uma camada Rust-first ou game-framework-level para janela, input, audio e render.
|
||||
- **Pro:** pode reduzir FFI nativa e integrar melhor com Cargo.
|
||||
- **Con:** pode ser menos madura para Linux handheld/Android real, packaging e controles.
|
||||
- **Tradeoff:** deve ser considerada, mas precisa provar vantagem concreta sobre SDL para justificar risco.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendacao inicial: manter a **Opcao C** como favorita, mas ampliar a fase de agenda para comparar SDL com as demais familias de host antes da decisao. O resultado desejado continua sendo um segundo host portatil, inicialmente paralelo, com destino explicito de se tornar o host principal quando atingir paridade e estabilidade.
|
||||
|
||||
O caminho recomendado e:
|
||||
|
||||
1. Definir o contrato minimo de equivalencia entre hosts: janela, framebuffer RGBA8888, input, audio, pacing, debugger/logs e encerramento.
|
||||
2. Identificar o que e comum ao host e o que e backend especifico.
|
||||
3. Comparar as familias candidatas contra esse contrato: SDL2, SDL3, winit atual evoluido, Android nativo separado e alternativas Rust-first.
|
||||
4. Implementar o candidato escolhido como novo crate/binario sem remover `prometeu-host-desktop-winit`.
|
||||
5. Permitir troca simples por binario/comando/feature, mantendo o runtime cego para a escolha.
|
||||
6. Tratar handheld Linux como alvo primario de produto para esse host; tratar Android customizado e DIY Linux como restricoes de desenho quando afetarem backend, packaging, input, audio ou boot/runtime integration.
|
||||
7. Promover o novo host a principal apenas depois de evidencia de estabilidade e paridade.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] A primeira implementacao SDL deve usar SDL2 ou SDL3?
|
||||
- [ ] SDL deve ser a familia escolhida, ou winit evoluido, Android nativo separado ou outra camada oferece melhor caminho?
|
||||
- [ ] A selecao do host deve ser por binario separado, feature Cargo, parametro CLI, ou combinacao desses mecanismos?
|
||||
- [ ] Qual e o menor conjunto de comportamento que define paridade aceitavel com o host winit?
|
||||
- [ ] Quais partes do host atual devem virar modulo comum antes do SDL, e quais devem ser duplicadas primeiro para evitar abstracao prematura?
|
||||
- [ ] O host SDL deve reutilizar `cpal` para audio inicialmente ou usar audio SDL desde o primeiro corte?
|
||||
- [ ] Quais familias de hardware handheld Linux devem ser usadas como referencia inicial?
|
||||
- [ ] Handheld Linux exige controles/gamepad, fullscreen, scaling, latency, sleep/resume, framebuffer/display mode ou packaging especificos desde o primeiro corte?
|
||||
- [ ] Qual e o "Linux base" minimo que um futuro hardware DIY precisaria expor para rodar o host portatil sem fork?
|
||||
- [ ] Android customizado deve ser criterio de escolha entre SDL2 e SDL3 agora, ou deve ficar como compatibilidade futura?
|
||||
- [ ] Como validar input e pacing de forma automatizada sem depender de janela real em CI? Encaminhada para `AGD-0052` / `DSC-0049`: o host headless é o lugar dessa prova. Esta agenda continua dona da escolha de backend portátil, não do controle determinístico.
|
||||
- [ ] O nome do crate deve ser `prometeu-host-desktop-sdl`, `prometeu-host-desktop-sdl2`, ou algo neutro a versao?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
A agenda pode virar decision quando estiver claro:
|
||||
|
||||
- se o novo host sera paralelo em estabilizacao, com destino de host principal;
|
||||
- qual familia de backend sera alvo inicial;
|
||||
- se SDL for escolhido, qual versao SDL sera alvo inicial;
|
||||
- como a selecao/troca de host deve funcionar;
|
||||
- quais contratos sao comuns e proibidos de mudar;
|
||||
- quais requisitos minimos de handheld Linux e possivel Android customizado entram no primeiro plano;
|
||||
- qual contrato minimo de Linux base mantem aberta a opcao de hardware DIY;
|
||||
- qual evidencia minima prova paridade suficiente para iniciar planos de implementacao.
|
||||
|
||||
## Discussion
|
||||
|
||||
Ponto inicial aceito pelo usuario: a intencao e ter um segundo host para testes, com troca simples e facil, aproveitando o trabalho ja feito para isolar essa troca no host sem envolver runtime ou outros dominios.
|
||||
|
||||
Atualizacao de escopo: o novo host nao e descartavel. O objetivo e servir como runtime host para sistemas Linux rodando em consoles portateis e hardwares handheld chineses, e possivelmente Android customizado. Assim que estiver estavel, ele deve poder virar o host principal.
|
||||
|
||||
Atualizacao de escopo: outras familias de host/backend tambem devem viver nesta agenda. SDL segue como hipotese forte, mas a decisao deve comparar opcoes antes de cravar a tecnologia.
|
||||
|
||||
Clarificacao: "mobile" nesta agenda nao se refere primariamente a telefone/tablet. O foco sao dispositivos portateis dedicados com Linux interno ou Android customizado, geralmente com controles fisicos e ambiente de distribuicao proprio.
|
||||
|
||||
Clarificacao: a agenda tambem deve preservar a opcao de um futuro hardware DIY. A premissa desejada e que, se esse hardware expuser um Linux base suficiente, o runtime ja tenha um host portatil pronto para rodar nele.
|
||||
|
||||
Atualizacao 2026-09-22: `AGD-0052` abre um terceiro host, headless, para teste, CI e controle determinístico em memória. Esse host não substitui o candidato portátil desta agenda e não escolhe SDL. A pergunta de validar input e pacing sem janela em CI passa a ser respondida lá. Extração de loop comum entre winit, SDL e headless continua esperando duplicação real.
|
||||
|
||||
## Resolution
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-0008"
|
||||
title: "runtime: Portable Host Backend Strategy"
|
||||
description: "Imported Discussion Framework discussion DSC-0047 from runtime (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime).\n\
|
||||
\nTargets:\n- runtime"
|
||||
goal: "Portable Host Backend Strategy"
|
||||
motivation: "Continue the open agendas of runtime/DSC-0047"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "OPEN"
|
||||
createdAt: "2026-11-16T15:25:23.269863Z"
|
||||
updatedAt: "2026-11-16T15:25:23.293409Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events: []
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-0009"
|
||||
origin: "discussion-framework:studio:AGD-0102:AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md"
|
||||
purpose: "Original DF agenda AGD-0102"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "48ae15be84dac874e1d70cf56bf85b11c941dc94c696e75ffc5984095cf88e6a"
|
||||
size: 14981
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.562110Z"
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
---
|
||||
id: AGD-0102
|
||||
ticket: blitz3d-studio-engineering-lessons
|
||||
title: Licoes do Blitz3D para autoria e ferramentas
|
||||
status: open
|
||||
created: 2026-11-04
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, compiler, pbs, sdk, research]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
**Worker:** Agenda Worker. **Dominio owner:** `studio`, pesquisa de experiencia de autoria. **Interfaces:** `compiler/general` para metadata, emissao e diagnosticos comuns; `compiler/pbs` para linguagem, core/SDK e projecoes editoriais.
|
||||
|
||||
O usuario solicitou separar as licoes do Blitz3D entre runtime e Studio em 2026-11-04. Esta agenda recebe o conteudo de autoria/ferramentas da [agenda do runtime AGD-0072 / DSC-0069](../../../../runtime/discussion/workflow/agendas/AGD-0072-licoes-de-engenharia-do-blitz3d-para-o-prometeu.md). O objetivo e aprendizado de engenharia a partir de codigo existente.
|
||||
|
||||
Base da pesquisa: [`blitz-research/blitz3d_soloud`, commit `f132a78c9f2da255905bf477cb845994324b865a`](https://github.com/blitz-research/blitz3d_soloud/commit/f132a78c9f2da255905bf477cb845994324b865a), datado de 2024-10-19. Analise estatica; o engine nao foi compilado ou executado. Contexto local consultado: checkout Studio `1d8b8c21014b5b2e94bcd6621dbea177afc0d4eb`, specs de PBS, catalogos, atribuicao de debug e agendas ativas. Nenhuma implementacao foi auditada integralmente ou qualificada nesta transferencia.
|
||||
|
||||
O runtime conserva caches, ownership de recursos, fases de execucao/render/audio, publicacao de comandos, limites de trabalho e validacao da maquina. Esta agenda concentra a experiencia de quem escreve, compila, compreende e executa jogos pelo Studio.
|
||||
|
||||
## Problema
|
||||
|
||||
Como aproveitar a experiencia do Blitz3D para tornar tarefas comuns de jogo compreensiveis e concisas, mantendo coerencia entre SDK, compilador, ajuda editorial e resultado executado?
|
||||
|
||||
O Studio ja possui catalogos versionados, metadata semantica para parametros, signature help, exemplos instalados e discussoes proprias de sprites/animação, composicao e qualificacao de jogo. A comparacao precisa identificar ganhos concretos sobre essa base. A existencia de um padrao interessante no Blitz nao demonstra uma lacuna no Studio.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
### 1. Ergonomia de uma tarefa completa
|
||||
|
||||
**Fato:** os tutoriais de [movimento](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/BLITZ3D_INSTALL/tutorials/GCUK_Tuts/movement.bb) e [colisao](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/BLITZ3D_INSTALL/tutorials/GCUK_Tuts/collision.bb) conectam criacao, configuracao, input/movimento, atualizacao, desenho e consulta de contato em programas curtos.
|
||||
|
||||
**Licao:** avaliar a superficie publica pela tarefa que o autor consegue concluir, incluindo imports, recursos, inicializacao, parametros e erros. A quantidade de primitivas disponiveis nao mede esse percurso.
|
||||
|
||||
**Aplicabilidade:** comparar pequenos exemplos PBS de mover personagem, consultar representacao visual, avancar animacao, emitir desenho e persistir estado. Usar os principios ja publicados na [Language Charter](../../../docs/specs/compiler-languages/pbs/1.%20Language%20Charter.md). Identificar precisamente se eventual atrito pertence a linguagem, core, SDK, projeto ou UI.
|
||||
|
||||
**Limite:** simplicidade no chamador nao autoriza novo syscall, estado oculto ou alteracao do modelo de ciclos. A separacao entre avancar animacao e emitir desenho deve respeitar as discussoes locais existentes.
|
||||
|
||||
### 2. Coerencia entre assinatura aceita e ajuda exibida
|
||||
|
||||
**Fato:** [`blitz/libs.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz/libs.cpp) transforma registros do runtime em declaracoes do compilador; [`blitz/main.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz/main.cpp) exporta sintaxe com `+k`; [`blitzide/libs.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitzide/libs.cpp) usa essa saida para keywords e ajuda rapida.
|
||||
|
||||
**Licao:** as ferramentas devem explicar a mesma API que o compilador aceita, com origem e responsabilidade de cada metadado claras.
|
||||
|
||||
**Aplicabilidade:** seguir um callable real por declaracao SDK/core, modelo semantico, compilacao, hover, completion e signature help. O Studio ja tem `FrontendSignatureHelp`, `PbsEditorialSignatureHelp` e nomes canonicos no modelo semantico. Investigar divergencias demonstradas nesses caminhos, aproveitando o contrato existente.
|
||||
|
||||
**Limite normativo:** [Runtime Catalog Support](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md) exige catalogos locais versionados, porte manual dos consumidores e verificacao independente. Esta pesquisa preserva essa escolha: nao propoe geracao automatica de enums, parser de Rust, consulta ao checkout irmao em builds normais ou uma nova fonte de autoridade. Nomes de parametros da API PBS pertencem ao modelo semantico; ABI, custos e efeitos do provider continuam runtime-owned. O aprendizado do Blitz e a coerencia observavel, nao seu formato compacto de assinaturas.
|
||||
|
||||
### 3. Exemplos pequenos como instrumentos de ensino e avaliacao
|
||||
|
||||
**Fato:** `BLITZ3D_INSTALL` contem tutoriais isolados, samples visuais, jogos e um media viewer. O tutorial de colisao exercita uma cadeia de uso completa.
|
||||
|
||||
**Licao:** exemplos pequenos tornam o modelo ensinavel e revelam boilerplate, imports dificeis e combinacoes pouco naturais entre APIs. Um sample ganha valor de regressao quando tem caminho de execucao e resultado esperado definidos.
|
||||
|
||||
**Aplicabilidade:** aproveitar o corpus ja existente em `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/`, incluindo input/main, colecoes, lifecycle e memcard. Identificar uma tarefa mal explicada ou sem exemplo antes de criar outro corpus. Distinguir compilacao do fonte, empacotamento instalado e execucao do PBX resultante.
|
||||
|
||||
**Limite:** a [qualificacao do jogo de referencia](AGD-0088-studio-reference-game-qualification.md) ja e owner da prova integrada instalada. Esta agenda recebe criterios de ergonomia e aprendizado, sem absorver aquela entrega ou acrescentar seus gates. Audio permanece fora da wave dessa qualificacao, conforme sua revisao de escopo; o exemplo de audio do Blitz nao reativa a integracao de audio abandonada.
|
||||
|
||||
### 4. Helpers de gameplay pertencem primeiro a core/SDK
|
||||
|
||||
**Fato:** [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) organiza regras direcionais de colisao, consultas sobre movimento e respostas de parar/deslizar. [`Object`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/object.cpp) separa captura de estado e representacao interpolada.
|
||||
|
||||
**Licao:** uma camada de conveniencia pode combinar poucos mecanismos com comportamento explicito para resolver tarefas frequentes. Consulta, avancar estado e emitir desenho devem ter efeitos reconheciveis.
|
||||
|
||||
**Aplicabilidade:** investigar bibliotecas PBS de gameplay apenas a partir de um exemplo que demonstre necessidade: overlap/sweep 2D, movimento contra tilemap ou outra operacao pequena. Declarar ordem, custos, limites, resultados e fallback. Dados compartilhados e estado por instancia tambem podem orientar tipos de SDK, sem herdar implicitamente copy-on-write ou semantica de alias do C++.
|
||||
|
||||
**Limite e ownership:** Sprite/Animator pertencem a [DSC-0098 / AGD-0100](AGD-0100-pbs-core-sprite-and-animation.md); a abstracao de emissao pertence a [DSC-0099 / AGD-0101](AGD-0101-pbs-composer-facing-blitable-contract.md). Esta agenda nao escolhe API, modifica essas discussoes, exige sua conclusao ou inclui implementacao de colisao nelas. Helpers geometricos futuros precisam de escopo proprio quando houver demanda. Novas capacidades da maquina exigiriam handoff separado ao runtime, nunca uma dependencia presumida desta pesquisa.
|
||||
|
||||
### 5. Preservar a explicacao do programa ate o diagnostico
|
||||
|
||||
**Fato:** [`StmtNode::debug`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/compiler/stmtnode.cpp) emite hooks com posicao de origem; [`debugtree.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/debugger/debugtree.cpp) usa tipos e declaracoes para exibir variaveis e campos.
|
||||
|
||||
**Licao:** uma ferramenta precisa conservar origem, nomes e contexto suficientes para explicar o que falhou. Correcao do bytecode nao estabelece a qualidade dessa explicacao.
|
||||
|
||||
**Aplicabilidade:** seguir um erro atribuivel ao fonte por frontend, IR, PBX e retorno host/UI/MCP, verificando se a localizacao e a categoria sobrevivem. A [spec de emissao](../../../docs/specs/compiler/15.%20Bytecode%20and%20PBX%20Mapping%20Specification.md) ja exige `function_names` e `pc_to_span` minimos; nao tratar sua existencia como funcionalidade faltante. `BytecodeModule` ja carrega `DebugInfo`.
|
||||
|
||||
**Limite:** o acoplamento do debugger Blitz a ponteiros/estruturas do compilador e um contraponto, nao recomendacao de ABI. A emissao e apresentacao da origem pertencem ao Studio; a interpretacao dos metadados, faults e seguranca da execucao permanecem com o runtime. Load errors nao devem receber PC de instrucao executada inventado. O debug workspace/consumer externo conserva suas responsabilidades proprias; esta agenda nao incorpora trabalho daquele repositorio.
|
||||
|
||||
## Transferencia e Interfaces
|
||||
|
||||
| Tema recebido da pesquisa original | Owner e alvo de investigacao | Evidencia proposta para eventual aprofundamento |
|
||||
| --- | --- | --- |
|
||||
| APIs por tarefa completa | `compiler/pbs`: core/SDK, imports/barrels e exemplos PBS | Fonte curto pelo caminho real, efeitos e erros explicitos; comparar a tarefa antes/depois de qualquer proposta. |
|
||||
| Assinaturas e ajuda coerentes | `compiler/general` + `compiler/pbs`: consumidores do catalogo, metadata semantica, `FrontendSignatureHelp`, LSP | A mesma chamada apresenta nomes/tipos/ordem consistentes na compilacao e nas superficies editoriais; preservar catalogos e porte manual publicados. |
|
||||
| Exemplos ensinaveis e executaveis | `studio` + `compiler/pbs`: knowledge/examples instalados; handoff de prova integrada a DSC-0086 | Identificar fonte e distribuicao, compilar exemplo real e definir resultado esperado; nao chamar simples paridade de JAR de execucao do jogo. |
|
||||
| Helpers de gameplay | `compiler/pbs`: bibliotecas sobre os contratos atuais | Demonstrar necessidade e camada responsavel, com ordem/limite/fallback; encaminhar sprites/composicao aos owners existentes. |
|
||||
| Origem e diagnosticos do autor | `compiler/general` + `studio`: `DebugInfo`, atribuicao e retorno UI/MCP | Preservar origem real e categoria ao longo do pipeline; registrar lacuna concreta quando existir, sem inventar spans/PCs. |
|
||||
|
||||
Esta tabela transfere perguntas e sugestoes de evidencia. Nao declara implementacao, aceite tecnico ou novo gate mandatorio. Contratos publicados e discussoes existentes conservam sua autoridade. Os dois repositorios mantem indices e IDs independentes.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Comparacao focada de uma tarefa de autoria
|
||||
|
||||
- **Abordagem:** selecionar uma tarefa pequena e seguir sua API, metadata, ajuda e exemplo pelos mecanismos existentes.
|
||||
- **Pro:** produz evidencia concreta com escopo curto e reaproveita entregas existentes.
|
||||
- **Contra:** uma tarefa pode nao representar todos os perfis de usuario.
|
||||
- **Tradeoff:** melhor retorno inicial para distinguir qualidade de uso de cobertura de subsistema.
|
||||
|
||||
### Opcao B - Revisao transversal de metadata e diagnosticos
|
||||
|
||||
- **Abordagem:** avaliar varios tipos de callable e categorias de erro, mantendo fronteiras entre provider, compiler e editor.
|
||||
- **Pro:** pode localizar divergencias sistematicas entre consumidores.
|
||||
- **Contra:** exige corpus maior e pode repetir a qualificacao ja coberta por specs/testes.
|
||||
- **Tradeoff:** apropriada quando houver divergencia ou relato concreto que justifique a amplitude.
|
||||
|
||||
### Opcao C - Expandir primeiro bibliotecas e exemplos de gameplay
|
||||
|
||||
- **Abordagem:** escolher um helper ainda necessario e amadurecer sua API em agenda propria.
|
||||
- **Pro:** melhora diretamente a experiencia do autor quando a demanda e demonstrada.
|
||||
- **Contra:** risco de criar abstracoes antes do caso de uso ou duplicar sprites/composicao.
|
||||
- **Tradeoff:** depende de necessidade concreta e owner delimitado; nao e implementacao autorizada por esta transferencia.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Preferir **A**. O maior aprendizado do Blitz e oferecer um percurso curto entre intencao, codigo e feedback. Escolher uma tarefa suportada, comparar sua experiencia no Studio e registrar somente atritos reproduziveis.
|
||||
|
||||
Usar **B** quando a tarefa revelar divergencia de assinatura ou diagnostico. Considerar **C** apenas quando a dificuldade estiver na ausencia de uma composicao de gameplay, respeitando os owners de sprites/animação e emissao. O runtime permanece fornecedor dos contratos publicados; esta pesquisa de consumo pode avancar independentemente da agenda de runtime.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] Qual tarefa existente melhor representa a experiencia de autoria que se deseja avaliar?
|
||||
- [ ] A eventual dificuldade esta em linguagem/core/SDK, descoberta editorial, projeto ou UI?
|
||||
- [ ] Ha divergencia reproduzivel entre assinatura aceita e ajuda, ou a base atual ja cobre o achado do Blitz?
|
||||
- [ ] Quais exemplos instalados precisam apenas de melhor explicacao e quais demonstram uma composicao ainda ausente?
|
||||
- [ ] Existe demanda concreta de helper geometrico ou basta encaminhar os achados aos temas ativos de sprites/composicao?
|
||||
- [ ] Algum erro perde sua origem real entre emissao e apresentacao? Em qual consumer e com qual fixture?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Para convergir em uma futura decision, selecionar uma dificuldade observada, identificar owner e superficies afetadas, comparar alternativas e definir resultado verificavel. Quando o caso estiver coberto, registrar a evidencia em vez de inventar uma mudanca.
|
||||
|
||||
A transferencia solicitada esta concluida quando esta agenda preservar as fontes e perguntas recebidas, a agenda do runtime contiver somente suas responsabilidades e os links entre ambas resolverem. Essa conclusao organizacional nao fecha tecnicamente as propostas nem autoriza implementacao.
|
||||
|
||||
## Proximo Passo Sugerido
|
||||
|
||||
Escolher um pequeno fluxo de autoria ja suportado e comparar codigo, feedback editorial e resultado executado, considerando as discussoes existentes. As capacidades ainda em debate devem continuar com seus owners.
|
||||
|
||||
## Validacao e Estado
|
||||
|
||||
- Pesquisa e transferencia de responsabilidade; agenda aberta.
|
||||
- Sources do Blitz fixadas em commit, com fatos separados de aplicabilidade e limites.
|
||||
- Contratos locais e escopos de agendas existentes consultados; nenhuma qualificacao de comportamento reivindicada.
|
||||
- Sem mudancas em specs, SDK, compilador, runtime ou UI decorrentes desta transferencia.
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-0009"
|
||||
origin: "discussion-framework:studio:DSC-0100:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0100"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "b23f7ea52f027c46764bc12966ebe6d8d4a9a8425a7952f288753482d11e3fa2"
|
||||
size: 461
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.568596Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0100","status":"open","ticket":"blitz3d-studio-engineering-lessons","title":"Licoes do Blitz3D para autoria e ferramentas","created_at":"2026-11-04","updated_at":"2026-11-04","tags":["studio","compiler","pbs","sdk","research"],"agendas":[{"id":"AGD-0102","file":"AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md","status":"open","created_at":"2026-11-04","updated_at":"2026-11-04"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-0009"
|
||||
origin: "ai-engineering:discussion-import:studio:DSC-0100"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "7fe3c0b8679e70d608237792a34ce2ffd197dbe37f08c0f14bd7fe3ed3c18ad6"
|
||||
size: 695
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.574415Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0009",
|
||||
"sourceId" : "studio",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio",
|
||||
"dscId" : "DSC-0100",
|
||||
"targets" : [ "studio" ],
|
||||
"contentHash" : "a4698d062f7ea5d116da913fda81d44b59594a0917663b2f0b5cf2d4d70030cc",
|
||||
"dscSha256" : "b23f7ea52f027c46764bc12966ebe6d8d4a9a8425a7952f288753482d11e3fa2",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0102",
|
||||
"file" : "AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md",
|
||||
"sha256" : "48ae15be84dac874e1d70cf56bf85b11c941dc94c696e75ffc5984095cf88e6a",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+157
@@ -0,0 +1,157 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-0009"
|
||||
discussionId: "df:studio:AGD-0102"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:studio"
|
||||
createdAt: "2026-11-16T15:31:32.555949Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
id: AGD-0102
|
||||
ticket: blitz3d-studio-engineering-lessons
|
||||
title: Licoes do Blitz3D para autoria e ferramentas
|
||||
status: open
|
||||
created: 2026-11-04
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, compiler, pbs, sdk, research]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
**Worker:** Agenda Worker. **Dominio owner:** `studio`, pesquisa de experiencia de autoria. **Interfaces:** `compiler/general` para metadata, emissao e diagnosticos comuns; `compiler/pbs` para linguagem, core/SDK e projecoes editoriais.
|
||||
|
||||
O usuario solicitou separar as licoes do Blitz3D entre runtime e Studio em 2026-11-04. Esta agenda recebe o conteudo de autoria/ferramentas da [agenda do runtime AGD-0072 / DSC-0069](../../../../runtime/discussion/workflow/agendas/AGD-0072-licoes-de-engenharia-do-blitz3d-para-o-prometeu.md). O objetivo e aprendizado de engenharia a partir de codigo existente.
|
||||
|
||||
Base da pesquisa: [`blitz-research/blitz3d_soloud`, commit `f132a78c9f2da255905bf477cb845994324b865a`](https://github.com/blitz-research/blitz3d_soloud/commit/f132a78c9f2da255905bf477cb845994324b865a), datado de 2024-10-19. Analise estatica; o engine nao foi compilado ou executado. Contexto local consultado: checkout Studio `1d8b8c21014b5b2e94bcd6621dbea177afc0d4eb`, specs de PBS, catalogos, atribuicao de debug e agendas ativas. Nenhuma implementacao foi auditada integralmente ou qualificada nesta transferencia.
|
||||
|
||||
O runtime conserva caches, ownership de recursos, fases de execucao/render/audio, publicacao de comandos, limites de trabalho e validacao da maquina. Esta agenda concentra a experiencia de quem escreve, compila, compreende e executa jogos pelo Studio.
|
||||
|
||||
## Problema
|
||||
|
||||
Como aproveitar a experiencia do Blitz3D para tornar tarefas comuns de jogo compreensiveis e concisas, mantendo coerencia entre SDK, compilador, ajuda editorial e resultado executado?
|
||||
|
||||
O Studio ja possui catalogos versionados, metadata semantica para parametros, signature help, exemplos instalados e discussoes proprias de sprites/animação, composicao e qualificacao de jogo. A comparacao precisa identificar ganhos concretos sobre essa base. A existencia de um padrao interessante no Blitz nao demonstra uma lacuna no Studio.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
### 1. Ergonomia de uma tarefa completa
|
||||
|
||||
**Fato:** os tutoriais de [movimento](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/BLITZ3D_INSTALL/tutorials/GCUK_Tuts/movement.bb) e [colisao](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/BLITZ3D_INSTALL/tutorials/GCUK_Tuts/collision.bb) conectam criacao, configuracao, input/movimento, atualizacao, desenho e consulta de contato em programas curtos.
|
||||
|
||||
**Licao:** avaliar a superficie publica pela tarefa que o autor consegue concluir, incluindo imports, recursos, inicializacao, parametros e erros. A quantidade de primitivas disponiveis nao mede esse percurso.
|
||||
|
||||
**Aplicabilidade:** comparar pequenos exemplos PBS de mover personagem, consultar representacao visual, avancar animacao, emitir desenho e persistir estado. Usar os principios ja publicados na [Language Charter](../../../docs/specs/compiler-languages/pbs/1.%20Language%20Charter.md). Identificar precisamente se eventual atrito pertence a linguagem, core, SDK, projeto ou UI.
|
||||
|
||||
**Limite:** simplicidade no chamador nao autoriza novo syscall, estado oculto ou alteracao do modelo de ciclos. A separacao entre avancar animacao e emitir desenho deve respeitar as discussoes locais existentes.
|
||||
|
||||
### 2. Coerencia entre assinatura aceita e ajuda exibida
|
||||
|
||||
**Fato:** [`blitz/libs.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz/libs.cpp) transforma registros do runtime em declaracoes do compilador; [`blitz/main.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz/main.cpp) exporta sintaxe com `+k`; [`blitzide/libs.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitzide/libs.cpp) usa essa saida para keywords e ajuda rapida.
|
||||
|
||||
**Licao:** as ferramentas devem explicar a mesma API que o compilador aceita, com origem e responsabilidade de cada metadado claras.
|
||||
|
||||
**Aplicabilidade:** seguir um callable real por declaracao SDK/core, modelo semantico, compilacao, hover, completion e signature help. O Studio ja tem `FrontendSignatureHelp`, `PbsEditorialSignatureHelp` e nomes canonicos no modelo semantico. Investigar divergencias demonstradas nesses caminhos, aproveitando o contrato existente.
|
||||
|
||||
**Limite normativo:** [Runtime Catalog Support](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md) exige catalogos locais versionados, porte manual dos consumidores e verificacao independente. Esta pesquisa preserva essa escolha: nao propoe geracao automatica de enums, parser de Rust, consulta ao checkout irmao em builds normais ou uma nova fonte de autoridade. Nomes de parametros da API PBS pertencem ao modelo semantico; ABI, custos e efeitos do provider continuam runtime-owned. O aprendizado do Blitz e a coerencia observavel, nao seu formato compacto de assinaturas.
|
||||
|
||||
### 3. Exemplos pequenos como instrumentos de ensino e avaliacao
|
||||
|
||||
**Fato:** `BLITZ3D_INSTALL` contem tutoriais isolados, samples visuais, jogos e um media viewer. O tutorial de colisao exercita uma cadeia de uso completa.
|
||||
|
||||
**Licao:** exemplos pequenos tornam o modelo ensinavel e revelam boilerplate, imports dificeis e combinacoes pouco naturais entre APIs. Um sample ganha valor de regressao quando tem caminho de execucao e resultado esperado definidos.
|
||||
|
||||
**Aplicabilidade:** aproveitar o corpus ja existente em `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/`, incluindo input/main, colecoes, lifecycle e memcard. Identificar uma tarefa mal explicada ou sem exemplo antes de criar outro corpus. Distinguir compilacao do fonte, empacotamento instalado e execucao do PBX resultante.
|
||||
|
||||
**Limite:** a [qualificacao do jogo de referencia](AGD-0088-studio-reference-game-qualification.md) ja e owner da prova integrada instalada. Esta agenda recebe criterios de ergonomia e aprendizado, sem absorver aquela entrega ou acrescentar seus gates. Audio permanece fora da wave dessa qualificacao, conforme sua revisao de escopo; o exemplo de audio do Blitz nao reativa a integracao de audio abandonada.
|
||||
|
||||
### 4. Helpers de gameplay pertencem primeiro a core/SDK
|
||||
|
||||
**Fato:** [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) organiza regras direcionais de colisao, consultas sobre movimento e respostas de parar/deslizar. [`Object`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/object.cpp) separa captura de estado e representacao interpolada.
|
||||
|
||||
**Licao:** uma camada de conveniencia pode combinar poucos mecanismos com comportamento explicito para resolver tarefas frequentes. Consulta, avancar estado e emitir desenho devem ter efeitos reconheciveis.
|
||||
|
||||
**Aplicabilidade:** investigar bibliotecas PBS de gameplay apenas a partir de um exemplo que demonstre necessidade: overlap/sweep 2D, movimento contra tilemap ou outra operacao pequena. Declarar ordem, custos, limites, resultados e fallback. Dados compartilhados e estado por instancia tambem podem orientar tipos de SDK, sem herdar implicitamente copy-on-write ou semantica de alias do C++.
|
||||
|
||||
**Limite e ownership:** Sprite/Animator pertencem a [DSC-0098 / AGD-0100](AGD-0100-pbs-core-sprite-and-animation.md); a abstracao de emissao pertence a [DSC-0099 / AGD-0101](AGD-0101-pbs-composer-facing-blitable-contract.md). Esta agenda nao escolhe API, modifica essas discussoes, exige sua conclusao ou inclui implementacao de colisao nelas. Helpers geometricos futuros precisam de escopo proprio quando houver demanda. Novas capacidades da maquina exigiriam handoff separado ao runtime, nunca uma dependencia presumida desta pesquisa.
|
||||
|
||||
### 5. Preservar a explicacao do programa ate o diagnostico
|
||||
|
||||
**Fato:** [`StmtNode::debug`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/compiler/stmtnode.cpp) emite hooks com posicao de origem; [`debugtree.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/debugger/debugtree.cpp) usa tipos e declaracoes para exibir variaveis e campos.
|
||||
|
||||
**Licao:** uma ferramenta precisa conservar origem, nomes e contexto suficientes para explicar o que falhou. Correcao do bytecode nao estabelece a qualidade dessa explicacao.
|
||||
|
||||
**Aplicabilidade:** seguir um erro atribuivel ao fonte por frontend, IR, PBX e retorno host/UI/MCP, verificando se a localizacao e a categoria sobrevivem. A [spec de emissao](../../../docs/specs/compiler/15.%20Bytecode%20and%20PBX%20Mapping%20Specification.md) ja exige `function_names` e `pc_to_span` minimos; nao tratar sua existencia como funcionalidade faltante. `BytecodeModule` ja carrega `DebugInfo`.
|
||||
|
||||
**Limite:** o acoplamento do debugger Blitz a ponteiros/estruturas do compilador e um contraponto, nao recomendacao de ABI. A emissao e apresentacao da origem pertencem ao Studio; a interpretacao dos metadados, faults e seguranca da execucao permanecem com o runtime. Load errors nao devem receber PC de instrucao executada inventado. O debug workspace/consumer externo conserva suas responsabilidades proprias; esta agenda nao incorpora trabalho daquele repositorio.
|
||||
|
||||
## Transferencia e Interfaces
|
||||
|
||||
| Tema recebido da pesquisa original | Owner e alvo de investigacao | Evidencia proposta para eventual aprofundamento |
|
||||
| --- | --- | --- |
|
||||
| APIs por tarefa completa | `compiler/pbs`: core/SDK, imports/barrels e exemplos PBS | Fonte curto pelo caminho real, efeitos e erros explicitos; comparar a tarefa antes/depois de qualquer proposta. |
|
||||
| Assinaturas e ajuda coerentes | `compiler/general` + `compiler/pbs`: consumidores do catalogo, metadata semantica, `FrontendSignatureHelp`, LSP | A mesma chamada apresenta nomes/tipos/ordem consistentes na compilacao e nas superficies editoriais; preservar catalogos e porte manual publicados. |
|
||||
| Exemplos ensinaveis e executaveis | `studio` + `compiler/pbs`: knowledge/examples instalados; handoff de prova integrada a DSC-0086 | Identificar fonte e distribuicao, compilar exemplo real e definir resultado esperado; nao chamar simples paridade de JAR de execucao do jogo. |
|
||||
| Helpers de gameplay | `compiler/pbs`: bibliotecas sobre os contratos atuais | Demonstrar necessidade e camada responsavel, com ordem/limite/fallback; encaminhar sprites/composicao aos owners existentes. |
|
||||
| Origem e diagnosticos do autor | `compiler/general` + `studio`: `DebugInfo`, atribuicao e retorno UI/MCP | Preservar origem real e categoria ao longo do pipeline; registrar lacuna concreta quando existir, sem inventar spans/PCs. |
|
||||
|
||||
Esta tabela transfere perguntas e sugestoes de evidencia. Nao declara implementacao, aceite tecnico ou novo gate mandatorio. Contratos publicados e discussoes existentes conservam sua autoridade. Os dois repositorios mantem indices e IDs independentes.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Comparacao focada de uma tarefa de autoria
|
||||
|
||||
- **Abordagem:** selecionar uma tarefa pequena e seguir sua API, metadata, ajuda e exemplo pelos mecanismos existentes.
|
||||
- **Pro:** produz evidencia concreta com escopo curto e reaproveita entregas existentes.
|
||||
- **Contra:** uma tarefa pode nao representar todos os perfis de usuario.
|
||||
- **Tradeoff:** melhor retorno inicial para distinguir qualidade de uso de cobertura de subsistema.
|
||||
|
||||
### Opcao B - Revisao transversal de metadata e diagnosticos
|
||||
|
||||
- **Abordagem:** avaliar varios tipos de callable e categorias de erro, mantendo fronteiras entre provider, compiler e editor.
|
||||
- **Pro:** pode localizar divergencias sistematicas entre consumidores.
|
||||
- **Contra:** exige corpus maior e pode repetir a qualificacao ja coberta por specs/testes.
|
||||
- **Tradeoff:** apropriada quando houver divergencia ou relato concreto que justifique a amplitude.
|
||||
|
||||
### Opcao C - Expandir primeiro bibliotecas e exemplos de gameplay
|
||||
|
||||
- **Abordagem:** escolher um helper ainda necessario e amadurecer sua API em agenda propria.
|
||||
- **Pro:** melhora diretamente a experiencia do autor quando a demanda e demonstrada.
|
||||
- **Contra:** risco de criar abstracoes antes do caso de uso ou duplicar sprites/composicao.
|
||||
- **Tradeoff:** depende de necessidade concreta e owner delimitado; nao e implementacao autorizada por esta transferencia.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Preferir **A**. O maior aprendizado do Blitz e oferecer um percurso curto entre intencao, codigo e feedback. Escolher uma tarefa suportada, comparar sua experiencia no Studio e registrar somente atritos reproduziveis.
|
||||
|
||||
Usar **B** quando a tarefa revelar divergencia de assinatura ou diagnostico. Considerar **C** apenas quando a dificuldade estiver na ausencia de uma composicao de gameplay, respeitando os owners de sprites/animação e emissao. O runtime permanece fornecedor dos contratos publicados; esta pesquisa de consumo pode avancar independentemente da agenda de runtime.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] Qual tarefa existente melhor representa a experiencia de autoria que se deseja avaliar?
|
||||
- [ ] A eventual dificuldade esta em linguagem/core/SDK, descoberta editorial, projeto ou UI?
|
||||
- [ ] Ha divergencia reproduzivel entre assinatura aceita e ajuda, ou a base atual ja cobre o achado do Blitz?
|
||||
- [ ] Quais exemplos instalados precisam apenas de melhor explicacao e quais demonstram uma composicao ainda ausente?
|
||||
- [ ] Existe demanda concreta de helper geometrico ou basta encaminhar os achados aos temas ativos de sprites/composicao?
|
||||
- [ ] Algum erro perde sua origem real entre emissao e apresentacao? Em qual consumer e com qual fixture?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Para convergir em uma futura decision, selecionar uma dificuldade observada, identificar owner e superficies afetadas, comparar alternativas e definir resultado verificavel. Quando o caso estiver coberto, registrar a evidencia em vez de inventar uma mudanca.
|
||||
|
||||
A transferencia solicitada esta concluida quando esta agenda preservar as fontes e perguntas recebidas, a agenda do runtime contiver somente suas responsabilidades e os links entre ambas resolverem. Essa conclusao organizacional nao fecha tecnicamente as propostas nem autoriza implementacao.
|
||||
|
||||
## Proximo Passo Sugerido
|
||||
|
||||
Escolher um pequeno fluxo de autoria ja suportado e comparar codigo, feedback editorial e resultado executado, considerando as discussoes existentes. As capacidades ainda em debate devem continuar com seus owners.
|
||||
|
||||
## Validacao e Estado
|
||||
|
||||
- Pesquisa e transferencia de responsabilidade; agenda aberta.
|
||||
- Sources do Blitz fixadas em commit, com fatos separados de aplicabilidade e limites.
|
||||
- Contratos locais e escopos de agendas existentes consultados; nenhuma qualificacao de comportamento reivindicada.
|
||||
- Sem mudancas em specs, SDK, compilador, runtime ou UI decorrentes desta transferencia.
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0002"
|
||||
workId: "WRK-0009"
|
||||
discussionId: "main"
|
||||
kind: "NOTE"
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T16:03:23.992008Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
Continuidade consolidada em WRK-000E, tópico TOP-0002, por solicitação do usuário de reunir o contexto do Blitz3D em um Work multi-repo. Pesquisa e evidências originais preservadas neste registro e copiadas integralmente para o novo Work. Este registro independente será cancelado e arquivado por consolidação organizacional; suas propostas continuam abertas no destino e nenhuma implementação foi declarada concluída. A identidade de importação é mantida neste Work para evitar duplicações em reimportações.
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-0009"
|
||||
title: "studio: Licoes do Blitz3D para autoria e ferramentas"
|
||||
description: "Imported Discussion Framework discussion DSC-0100 from studio (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio).\n\
|
||||
\nTargets:\n- studio"
|
||||
goal: "Licoes do Blitz3D para autoria e ferramentas"
|
||||
motivation: "Continue the open agendas of studio/DSC-0100"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "CANCELLED"
|
||||
createdAt: "2026-11-16T15:31:32.554111Z"
|
||||
updatedAt: "2026-11-16T16:03:25.581819Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
- "DSC-0002"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events:
|
||||
- action: "STATUS"
|
||||
by: "codex"
|
||||
reason: "Consolidado em WRK-000E (TOP-0002), Work multi-repo runtime e studio; contexto\
|
||||
\ e evidências preservados; pesquisa continua no destino."
|
||||
at: "2026-11-16T16:03:24.463393Z"
|
||||
- action: "ARCHIVE"
|
||||
by: "codex"
|
||||
reason: "Registro de origem preservado; continuidade em WRK-000E, tópico TOP-0002;\
|
||||
\ arquivamento por consolidação multi-repo."
|
||||
at: "2026-11-16T16:03:25.581819Z"
|
||||
archived: true
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-000A"
|
||||
origin: "discussion-framework:studio:AGD-0101:AGD-0101-pbs-composer-facing-blitable-contract.md"
|
||||
purpose: "Original DF agenda AGD-0101"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "a9fa471194e20e5c67d129a4319302d0df98792472351d6a499f3a9aac4b4460"
|
||||
size: 7069
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.598012Z"
|
||||
+123
@@ -0,0 +1,123 @@
|
||||
---
|
||||
id: AGD-0101
|
||||
ticket: pbs-composer-blitable
|
||||
title: PBS Composer-facing Blitable Contract
|
||||
status: open
|
||||
created: 2026-11-04
|
||||
resolved:
|
||||
decision:
|
||||
tags: [compiler, pbs, sdk, composer, drawing]
|
||||
---
|
||||
|
||||
## Problema
|
||||
|
||||
Discutir uma abstração de desenho sobre o composer, candidata ao nome
|
||||
`Blitable`, sem acoplar o fechamento de `Sprite` e `Animator` a essa API.
|
||||
|
||||
**Worker:** Agenda Worker. **Domínio owner:** `compiler/pbs`, subdomínio
|
||||
SDK/composição. **Discussão:** DSC-0099. **Estado:** agenda aberta.
|
||||
|
||||
O usuário pediu explicitamente separar o tema da
|
||||
[AGD-0100 / DSC-0098](AGD-0100-pbs-core-sprite-and-animation.md) em 2026-11-04.
|
||||
Quando o contrato amadurecer, `Sprite` e `Animator` poderão implementá-lo;
|
||||
essa possibilidade não exige implementação nem antecipação do contrato agora.
|
||||
|
||||
## Contexto
|
||||
|
||||
1. `SpriteView`, na discussão de origem, oferece banco/glyph da representação
|
||||
corrente sem emitir comandos nem avançar animação.
|
||||
2. `Blitable` foi proposta como trait de emissão: quem a implementa sabe chamar
|
||||
o composer com a representação e os inputs de desenho.
|
||||
3. O usuário explicitou que `Composer` é SDK e não conhece `Sprite`. O desenho
|
||||
de alto nível deve chamar sua API existente externamente.
|
||||
4. A Game stdlib `1` expõe em `@sdk:composer`:
|
||||
`emit_sprite(glyph_id: int, palette_id: int, x: int, y: int, layer: int,
|
||||
bank_id: int, flip_x: bool, flip_y: bool, priority: int) -> int`, com identidade
|
||||
host `("composer", "emit_sprite", 1)` e capability `composer`.
|
||||
5. Posição e paleta são inputs externos na discussão de origem. Um método de
|
||||
desenho não pode introduzir armazenamento implícito desses inputs nos tipos.
|
||||
6. PBS representa traits por `declare contract`/`implements`. Implementações
|
||||
pertencem ao módulo que declara o tipo concreto. O desenho não pode presumir
|
||||
extensão arbitrária de tipos por um módulo terceiro.
|
||||
|
||||
## Escopo e fronteiras
|
||||
|
||||
- Fechar responsabilidade, assinatura, resultado e composição de `Blitable`,
|
||||
ou escolher uma operação externa de desenho como alternativa.
|
||||
- Preservar a independência entre consulta visual, avanço e emissão.
|
||||
- Identificar módulos e direção de dependências: implementar uma operação que
|
||||
chama `Composer` cria uma dependência de execução do SDK.
|
||||
- Avaliar a relação com um futuro gerenciador de draw de sprites sem incluir
|
||||
automaticamente sua implementação, filas, ordenação ou batching.
|
||||
- Não alterar o contrato host, criar um novo syscall ou reabrir o modelo de
|
||||
animação como consequência implícita desta agenda.
|
||||
|
||||
`compiler/pbs` é owner da API PBS. `compiler` participa se houver impacto no
|
||||
pipeline comum. `vm-arch`/runtime participam somente se uma proposta concreta
|
||||
demonstrar necessidade de mudança de execução. Nenhuma escrita no runtime é
|
||||
prevista ou autorizada por esta agenda.
|
||||
|
||||
## Opções e tradeoffs
|
||||
|
||||
| Opção | Abordagem | Benefícios | Custos e manutenção |
|
||||
| --- | --- | --- | --- |
|
||||
| A — Contract `Blitable` | Tipos implementam uma operação `blit` que recebe inputs de desenho e emite pelo composer. `Sprite` e `Animator` podem aderir posteriormente. | Chamador pode desenhar diferentes tipos pelo mesmo contract; cada tipo controla como obter e emitir sua representação. | Implementações assumem efeitos, dependência do SDK e preservação do resultado da emissão. Ownership PBS pode exigir mudanças nos módulos que declaram os tipos. |
|
||||
| B — Operação externa que consome `SpriteView` | Uma função ou serviço de desenho consulta banco/glyph e chama a API existente do composer. | Centraliza parâmetros e tratamento de emissão, mantendo consulta e dados independentes do SDK de composição. | Cobre diretamente representações de um banco/glyph. Objetos que emitam várias imagens exigiriam outro contrato explícito. |
|
||||
|
||||
A diferenciação útil é entre conhecer uma representação e saber emiti-la.
|
||||
Implementar as duas traits no mesmo tipo não as torna equivalentes. A escolha
|
||||
deve ser demonstrada com exemplos de consumo e com a direção de dependências,
|
||||
sem exigir duas abstrações que ofereçam apenas conveniências idênticas.
|
||||
|
||||
## Recomendação para debate
|
||||
|
||||
Manter `SpriteView` como consulta na discussão de origem e amadurecer esta
|
||||
abstração na camada de composição. Antes de escolher A ou B, comparar chamadas
|
||||
de sprite estático e animator com os mesmos parâmetros e erros do composer.
|
||||
|
||||
Se a intenção for que objetos saibam emitir seu próprio conteúdo, preferir A,
|
||||
explicitando dependências e ownership das implementações. Se a necessidade
|
||||
continuar sendo emitir um único banco/glyph consultado, B fornece um caminho
|
||||
centralizado com menos obrigações nos tipos de dados. A escolha permanece aberta.
|
||||
|
||||
## Perguntas em aberto
|
||||
|
||||
- [ ] `Blitable` representa emissão de uma imagem ou pode emitir vários comandos?
|
||||
Esse escopo deve preceder o desenho de qualquer gerenciador.
|
||||
- [ ] Quais parâmetros recebe: posição, paleta, layer, flips e priority
|
||||
individualmente ou por uma representação de inputs? Como manter seus custos
|
||||
e defaults explícitos?
|
||||
- [ ] Como preservar o resultado `int` e os erros da emissão existente? Se houver
|
||||
múltiplos comandos, qual resultado e política para emissão parcial?
|
||||
- [ ] Qual relação com `SpriteView`: uso interno opcional, dependência explícita
|
||||
ou contratos independentes? Emissão continua sem avanço de animação.
|
||||
- [ ] Onde declarar o contract e implementar sua adesão, respeitando ownership
|
||||
PBS e dependências? Como evitar ciclos entre módulos?
|
||||
- [ ] Como documentar e propagar a capability `composer` pelo caminho de desenho?
|
||||
- [ ] Qual é o escopo de uma futura integração de `Sprite`/`Animator` e quais
|
||||
exemplos e testes comprovam a conveniência do contrato?
|
||||
|
||||
## Evidências para convergir
|
||||
|
||||
Comparar emissão de um sprite e de um animator sem avançá-lo, emissão repetida
|
||||
no mesmo tick, troca de paleta/posição sem persistência e falha do composer.
|
||||
Comprovar imports/exports, ownership de implements e ausência de ciclos de
|
||||
dependência em compilação real antes de propor um plan de implementação.
|
||||
|
||||
## Referências
|
||||
|
||||
- [AGD-0100 — PBS Core Sprite and Animation](AGD-0100-pbs-core-sprite-and-animation.md).
|
||||
- [Composer empacotado](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/composer/main.pbs).
|
||||
- [PBS 5 — Manifest, Stdlib, and SDK Resolution](../../../docs/specs/compiler-languages/pbs/5.%20Manifest%2C%20Stdlib%2C%20and%20SDK%20Resolution%20Specification.md).
|
||||
- [Compiler 18 — Standard Library Surface](../../../docs/specs/compiler/18.%20Standard%20Library%20Surface%20Specification.md).
|
||||
|
||||
## Próximo passo sugerido
|
||||
|
||||
Retomar quando a discussão de composição amadurecer. Fechar escopo de emissão,
|
||||
comparar A/B com exemplos e então definir assinatura, ownership e propagação.
|
||||
Esta agenda não bloqueia a conclusão da AGD-0100.
|
||||
|
||||
## Resolução
|
||||
|
||||
Em aberto. O tema foi separado por solicitação do usuário; não houve escolha
|
||||
final de API, transição para decision ou autorização de implementação.
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-000A"
|
||||
origin: "discussion-framework:studio:DSC-0099:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0099"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "dac88b5917e9d862f88231484e985a320562da2482f22030da1fec105c3f4f99"
|
||||
size: 435
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.604269Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0099","status":"open","ticket":"pbs-composer-blitable","title":"PBS Composer-facing Blitable Contract","created_at":"2026-11-04","updated_at":"2026-11-04","tags":["compiler","pbs","sdk","composer","drawing"],"agendas":[{"id":"AGD-0101","file":"AGD-0101-pbs-composer-facing-blitable-contract.md","status":"open","created_at":"2026-11-04","updated_at":"2026-11-04"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-000A"
|
||||
origin: "ai-engineering:discussion-import:studio:DSC-0099"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "99fc7241984a59a667b7faac1ffd05dbb4696c544634e5eb3bd04ce98318fd9f"
|
||||
size: 688
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.612319Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-000A",
|
||||
"sourceId" : "studio",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio",
|
||||
"dscId" : "DSC-0099",
|
||||
"targets" : [ "studio" ],
|
||||
"contentHash" : "3c45aa0a6f5b60d8c5dd07373b90bbea5dc5be3ea5bf8e9e7d48036b94d5cff9",
|
||||
"dscSha256" : "dac88b5917e9d862f88231484e985a320562da2482f22030da1fec105c3f4f99",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0101",
|
||||
"file" : "AGD-0101-pbs-composer-facing-blitable-contract.md",
|
||||
"sha256" : "a9fa471194e20e5c67d129a4319302d0df98792472351d6a499f3a9aac4b4460",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+135
@@ -0,0 +1,135 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-000A"
|
||||
discussionId: "df:studio:AGD-0101"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:studio"
|
||||
createdAt: "2026-11-16T15:31:32.593832Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
id: AGD-0101
|
||||
ticket: pbs-composer-blitable
|
||||
title: PBS Composer-facing Blitable Contract
|
||||
status: open
|
||||
created: 2026-11-04
|
||||
resolved:
|
||||
decision:
|
||||
tags: [compiler, pbs, sdk, composer, drawing]
|
||||
---
|
||||
|
||||
## Problema
|
||||
|
||||
Discutir uma abstração de desenho sobre o composer, candidata ao nome
|
||||
`Blitable`, sem acoplar o fechamento de `Sprite` e `Animator` a essa API.
|
||||
|
||||
**Worker:** Agenda Worker. **Domínio owner:** `compiler/pbs`, subdomínio
|
||||
SDK/composição. **Discussão:** DSC-0099. **Estado:** agenda aberta.
|
||||
|
||||
O usuário pediu explicitamente separar o tema da
|
||||
[AGD-0100 / DSC-0098](AGD-0100-pbs-core-sprite-and-animation.md) em 2026-11-04.
|
||||
Quando o contrato amadurecer, `Sprite` e `Animator` poderão implementá-lo;
|
||||
essa possibilidade não exige implementação nem antecipação do contrato agora.
|
||||
|
||||
## Contexto
|
||||
|
||||
1. `SpriteView`, na discussão de origem, oferece banco/glyph da representação
|
||||
corrente sem emitir comandos nem avançar animação.
|
||||
2. `Blitable` foi proposta como trait de emissão: quem a implementa sabe chamar
|
||||
o composer com a representação e os inputs de desenho.
|
||||
3. O usuário explicitou que `Composer` é SDK e não conhece `Sprite`. O desenho
|
||||
de alto nível deve chamar sua API existente externamente.
|
||||
4. A Game stdlib `1` expõe em `@sdk:composer`:
|
||||
`emit_sprite(glyph_id: int, palette_id: int, x: int, y: int, layer: int,
|
||||
bank_id: int, flip_x: bool, flip_y: bool, priority: int) -> int`, com identidade
|
||||
host `("composer", "emit_sprite", 1)` e capability `composer`.
|
||||
5. Posição e paleta são inputs externos na discussão de origem. Um método de
|
||||
desenho não pode introduzir armazenamento implícito desses inputs nos tipos.
|
||||
6. PBS representa traits por `declare contract`/`implements`. Implementações
|
||||
pertencem ao módulo que declara o tipo concreto. O desenho não pode presumir
|
||||
extensão arbitrária de tipos por um módulo terceiro.
|
||||
|
||||
## Escopo e fronteiras
|
||||
|
||||
- Fechar responsabilidade, assinatura, resultado e composição de `Blitable`,
|
||||
ou escolher uma operação externa de desenho como alternativa.
|
||||
- Preservar a independência entre consulta visual, avanço e emissão.
|
||||
- Identificar módulos e direção de dependências: implementar uma operação que
|
||||
chama `Composer` cria uma dependência de execução do SDK.
|
||||
- Avaliar a relação com um futuro gerenciador de draw de sprites sem incluir
|
||||
automaticamente sua implementação, filas, ordenação ou batching.
|
||||
- Não alterar o contrato host, criar um novo syscall ou reabrir o modelo de
|
||||
animação como consequência implícita desta agenda.
|
||||
|
||||
`compiler/pbs` é owner da API PBS. `compiler` participa se houver impacto no
|
||||
pipeline comum. `vm-arch`/runtime participam somente se uma proposta concreta
|
||||
demonstrar necessidade de mudança de execução. Nenhuma escrita no runtime é
|
||||
prevista ou autorizada por esta agenda.
|
||||
|
||||
## Opções e tradeoffs
|
||||
|
||||
| Opção | Abordagem | Benefícios | Custos e manutenção |
|
||||
| --- | --- | --- | --- |
|
||||
| A — Contract `Blitable` | Tipos implementam uma operação `blit` que recebe inputs de desenho e emite pelo composer. `Sprite` e `Animator` podem aderir posteriormente. | Chamador pode desenhar diferentes tipos pelo mesmo contract; cada tipo controla como obter e emitir sua representação. | Implementações assumem efeitos, dependência do SDK e preservação do resultado da emissão. Ownership PBS pode exigir mudanças nos módulos que declaram os tipos. |
|
||||
| B — Operação externa que consome `SpriteView` | Uma função ou serviço de desenho consulta banco/glyph e chama a API existente do composer. | Centraliza parâmetros e tratamento de emissão, mantendo consulta e dados independentes do SDK de composição. | Cobre diretamente representações de um banco/glyph. Objetos que emitam várias imagens exigiriam outro contrato explícito. |
|
||||
|
||||
A diferenciação útil é entre conhecer uma representação e saber emiti-la.
|
||||
Implementar as duas traits no mesmo tipo não as torna equivalentes. A escolha
|
||||
deve ser demonstrada com exemplos de consumo e com a direção de dependências,
|
||||
sem exigir duas abstrações que ofereçam apenas conveniências idênticas.
|
||||
|
||||
## Recomendação para debate
|
||||
|
||||
Manter `SpriteView` como consulta na discussão de origem e amadurecer esta
|
||||
abstração na camada de composição. Antes de escolher A ou B, comparar chamadas
|
||||
de sprite estático e animator com os mesmos parâmetros e erros do composer.
|
||||
|
||||
Se a intenção for que objetos saibam emitir seu próprio conteúdo, preferir A,
|
||||
explicitando dependências e ownership das implementações. Se a necessidade
|
||||
continuar sendo emitir um único banco/glyph consultado, B fornece um caminho
|
||||
centralizado com menos obrigações nos tipos de dados. A escolha permanece aberta.
|
||||
|
||||
## Perguntas em aberto
|
||||
|
||||
- [ ] `Blitable` representa emissão de uma imagem ou pode emitir vários comandos?
|
||||
Esse escopo deve preceder o desenho de qualquer gerenciador.
|
||||
- [ ] Quais parâmetros recebe: posição, paleta, layer, flips e priority
|
||||
individualmente ou por uma representação de inputs? Como manter seus custos
|
||||
e defaults explícitos?
|
||||
- [ ] Como preservar o resultado `int` e os erros da emissão existente? Se houver
|
||||
múltiplos comandos, qual resultado e política para emissão parcial?
|
||||
- [ ] Qual relação com `SpriteView`: uso interno opcional, dependência explícita
|
||||
ou contratos independentes? Emissão continua sem avanço de animação.
|
||||
- [ ] Onde declarar o contract e implementar sua adesão, respeitando ownership
|
||||
PBS e dependências? Como evitar ciclos entre módulos?
|
||||
- [ ] Como documentar e propagar a capability `composer` pelo caminho de desenho?
|
||||
- [ ] Qual é o escopo de uma futura integração de `Sprite`/`Animator` e quais
|
||||
exemplos e testes comprovam a conveniência do contrato?
|
||||
|
||||
## Evidências para convergir
|
||||
|
||||
Comparar emissão de um sprite e de um animator sem avançá-lo, emissão repetida
|
||||
no mesmo tick, troca de paleta/posição sem persistência e falha do composer.
|
||||
Comprovar imports/exports, ownership de implements e ausência de ciclos de
|
||||
dependência em compilação real antes de propor um plan de implementação.
|
||||
|
||||
## Referências
|
||||
|
||||
- [AGD-0100 — PBS Core Sprite and Animation](AGD-0100-pbs-core-sprite-and-animation.md).
|
||||
- [Composer empacotado](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/sdk/composer/main.pbs).
|
||||
- [PBS 5 — Manifest, Stdlib, and SDK Resolution](../../../docs/specs/compiler-languages/pbs/5.%20Manifest%2C%20Stdlib%2C%20and%20SDK%20Resolution%20Specification.md).
|
||||
- [Compiler 18 — Standard Library Surface](../../../docs/specs/compiler/18.%20Standard%20Library%20Surface%20Specification.md).
|
||||
|
||||
## Próximo passo sugerido
|
||||
|
||||
Retomar quando a discussão de composição amadurecer. Fechar escopo de emissão,
|
||||
comparar A/B com exemplos e então definir assinatura, ownership e propagação.
|
||||
Esta agenda não bloqueia a conclusão da AGD-0100.
|
||||
|
||||
## Resolução
|
||||
|
||||
Em aberto. O tema foi separado por solicitação do usuário; não houve escolha
|
||||
final de API, transição para decision ou autorização de implementação.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-000A"
|
||||
title: "studio: PBS Composer-facing Blitable Contract"
|
||||
description: "Imported Discussion Framework discussion DSC-0099 from studio (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio).\n\
|
||||
\nTargets:\n- studio"
|
||||
goal: "PBS Composer-facing Blitable Contract"
|
||||
motivation: "Continue the open agendas of studio/DSC-0099"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "OPEN"
|
||||
createdAt: "2026-11-16T15:31:32.592364Z"
|
||||
updatedAt: "2026-11-16T15:31:32.617911Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events: []
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-000B"
|
||||
origin: "discussion-framework:studio:AGD-0075:AGD-0075-studio-runtime-readiness.md"
|
||||
purpose: "Original DF agenda AGD-0075"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "fbbdbbeb415d758f8fbc7343dab59fa7400bf427a48a91c4fcaed7c3683370d2"
|
||||
size: 26706
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.637240Z"
|
||||
+272
@@ -0,0 +1,272 @@
|
||||
---
|
||||
id: AGD-0075
|
||||
ticket: studio-runtime-readiness
|
||||
title: Studio Runtime Readiness
|
||||
status: open
|
||||
created: 2026-10-14
|
||||
resolved:
|
||||
decision:
|
||||
tags: [runtime-integration, game-readiness]
|
||||
---
|
||||
|
||||
## Problema e papel da umbrella
|
||||
|
||||
Coordenar a prontidão fonte → compiler → packer → cartucho → runtime sem concentrar decisões de múltiplos domínios numa única agenda.
|
||||
|
||||
**Worker:** Agenda Worker. **Domínio owner:** `studio`, coordenação da integração ponta a ponta. Em 2026-10-14, o usuário solicitou agendas próprias por escopo e manteve esta AGD-0075 / DSC-0073 apenas como umbrella. Os detalhes técnicos e perguntas foram distribuídos para as agendas abaixo.
|
||||
|
||||
Esta umbrella mantém mapa de cobertura, dependências e acompanhamento. Cada agenda filha conduz sua própria convergência, decision, plan, implementação e lesson. Nenhuma opção técnica foi aceita por este desmembramento; não há decision ou plano global autorizando código.
|
||||
|
||||
## Contexto e proveniência
|
||||
|
||||
Origem: AGD-0060 / DSC-0057 do runtime (referência histórica), auditoria estática de 2026-10-14, snapshots runtime `3946874` e Studio `a9ede541`, sem builds/testes naquela rodada. Na verificação desta decomposição, `discussion --root ../runtime context DSC-0057` informa status `abandoned` e arquivo da AGD-0060 ausente. Esta operação não alterou o runtime. A proveniência fica preservada por IDs e pelos escopos recebidos nas filhas; os contratos atuais permanecem referenciados nelas. IDs são locais a cada repositório.
|
||||
|
||||
O usuário informou que **a última versão do runtime estará disponível para testes**. Registrar revisão/hash, plataforma e configuração por rodada para reprodução. Disponibilidade não comprova execução nem conformidade.
|
||||
|
||||
## Mapa de agendas e dependências propostas
|
||||
|
||||
Todas as agendas foram abertas nesta decomposição. O estado atualizado pertence ao índice e deve ser consultado com `discussion status/context`; esta tabela é um mapa de escopo, não uma cópia de estados.
|
||||
|
||||
| Agenda / discussão | Domínio owner | Interfaces/dependências propostas |
|
||||
| --- | --- | --- |
|
||||
| [LSN-0079 / DSC-0074 — Compiler PBX Registry Conformance (AGD76 concluída)](../../lessons/DSC-0074-compiler-pbx-registry-conformance/LSN-0079-typed-common-ir-to-production-pbx.md) | `compiler/general` | Base |
|
||||
| [LSN-0080 / DSC-0075 — Compiler Runtime Catalog Parity (AGD77 concluída)](../../lessons/DSC-0075-compiler-runtime-catalog-parity/LSN-0080-manual-runtime-catalog-port-and-conformance.md) | `compiler/general` | Base |
|
||||
| [DSC-0076 — PBS Existing Types and Input Alignment (concluída)](../../lessons/DSC-0076-pbs-existing-types-input-alignment/LSN-0081-pbs-typed-values-and-input.md) | `compiler/pbs` | AGD-0076, AGD-0077 |
|
||||
| [DSC-0077 — Packer Contract Qualification (concluída)](../../lessons/DSC-0077-packer-runtime-graphics-conformance/LSN-0082-packer-contracts-and-ci-failure-evidence.md) | `packer` | AGD-0076 |
|
||||
| [LSN-0083 / DSC-0079 — Arrays, optional e Struct/contract (concluída)](../../lessons/DSC-0079-pbs-typed-collections-and-dynamic/LSN-0083-pbs-arrays-optional-and-contract-execution.md) | `compiler/pbs` | AGD-0076, AGD-0077, AGD-0078 |
|
||||
| [LSN-0084 / DSC-0080 — PBS Closures (completed)](../../lessons/DSC-0080-pbs-closures-and-indirect-calls/LSN-0084-pbs-function-values-and-explicit-captures.md) | `compiler/pbs` | AGD-0076, AGD-0081 |
|
||||
| [LSN-0085 / DSC-0081 — PBS Runtime Math Integration concluída](../../lessons/DSC-0081-pbs-runtime-math-integration/LSN-0085-service-constants-and-source-math-conformance.md) | `compiler/pbs` | AGD-0076, AGD-0077, AGD-0078 |
|
||||
| [LSN-0086 / DSC-0082 — PBS Runtime Random Integration (AGD84 concluída)](../../lessons/DSC-0082-pbs-runtime-random-integration/LSN-0086-explicit-random-handles-and-source-conformance.md) | `compiler/pbs` | AGD-0076, AGD-0077, AGD-0078 |
|
||||
| [AGD-0085 / DSC-0083 — PBS PCM Audio Integration (abandonada)](./AGD-0085-pbs-pcm-audio-integration.md) | `compiler/pbs` | Histórico; áudio fora desta wave por solicitação do usuário em 2026-10-27 |
|
||||
| [LSN-0097 / DSC-0084 — PBS Guest Lifecycle Hooks (concluída)](../../lessons/DSC-0084-pbs-guest-lifecycle-hooks/LSN-0097-explicit-guest-hooks-and-preserved-continuations.md) | `compiler/pbs` | AGD-0076, AGD-0078 |
|
||||
| [LSN-0099 / DSC-0085 — Studio Memcard Persistence Integration](../../lessons/DSC-0085-studio-memcard-persistence-integration/LSN-0099-explicit-buffers-and-process-proven-persistence.md) | `studio` | AGD-0076, AGD-0077, AGD-0081, AGD-0086 |
|
||||
| [AGD-0088 / DSC-0086 — Studio Reference Game Qualification (abandonada)](./AGD-0088-studio-reference-game-qualification.md) | `studio` | Histórico; Pong entregue na DSC-0101. Qualificação ampla abandonada por solicitação do usuário em 2026-11-05 |
|
||||
|
||||
Os links são relativos e recíprocos: cada filha referencia esta umbrella. A CLI registra criação/estado/IDs; as relações de umbrella são documentadas aqui e nas filhas, pois `discussion start` não oferece campo de parent/dependência. Fica registrada a lacuna de automação dessas relações no framework, sem editar o índice manualmente.
|
||||
|
||||
## Revisão de escopo — áudio fora da wave — 2026-10-27
|
||||
|
||||
Por solicitação explícita do usuário, AGD85 / DSC-0083 foi abandonada e áudio
|
||||
fica fora desta wave, inclusive o suporte mínimo discutido. SDK de áudio,
|
||||
produção SOUND/WAV, smoke audível e qualificação integrada de áudio deixam de
|
||||
ser entregas ou gates desta umbrella e da AGD88. A existência de áudio no runtime
|
||||
não representa entrega do consumidor. Lifecycle e persistência mantêm suas
|
||||
agendas próprias. Uma futura retomada requer solicitação e discussão próprias.
|
||||
|
||||
## Sequência recomendada e coordenação
|
||||
|
||||
**Atualização de escopo — 2026-11-05:** o usuário solicitou abandonar
|
||||
AGD-0088 / DSC-0086 após a entrega do primeiro Pong. A
|
||||
[LSN-0101](../../lessons/DSC-0101-pong-playable-test-project/LSN-0101-pong-as-the-first-studio-game.md)
|
||||
preserva o jogo entregue e a
|
||||
[LSN-0102](../../lessons/DSC-0102-sample-project-sdk-refresh/LSN-0102-refreshing-samples-without-changing-their-identity.md)
|
||||
preserva a atualização dos exemplos. A qualificação ampla não executada,
|
||||
incluindo o escopo incorporado da antiga AGD80, deixa de ser entrega ou gate
|
||||
ativo desta umbrella. Ela não foi validada pelo Pong nem transferida para outra
|
||||
agenda. Os encaminhamentos à DSC-0086 nas seções históricas abaixo descrevem a
|
||||
coordenação anterior ao abandono. As capacidades locais já concluídas mantêm
|
||||
suas próprias decisões, lessons e evidências; eventual retomada da qualificação
|
||||
integrada requer nova solicitação e discussão.
|
||||
|
||||
1. **Adequação do existente:** PBX/IR e catálogos estabelecem a base; tipos/input PBS e assets gráficos fecham seus contratos locais. A prova integrada de execução instalada foi incorporada à qualificação final na AGD88.
|
||||
2. **Novas capacidades:** coleções, closures, math, random, lifecycle e memcard fecham suas próprias escolhas e fixtures fonte → execução. Dependências indicam interfaces; não exigem esperar para iniciar as discussões.
|
||||
3. **Qualificação pelo jogo:** definir jogo e corpus cedo; executar a qualificação após as capacidades necessárias e fixtures auxiliares estarem prontas, incluindo Build/Play/headless/MCP contra distribuição instalada identificada, escopo incorporado da AGD80.
|
||||
|
||||
O schema PBX v0 completo integra a adequação inicial, inclusive tabelas vazias e role 0, mesmo que sintaxe de novas capacidades venha depois. Não exigir toda a expansão para restaurar a execução de um exemplo simples. A agenda do jogo consolida prova representativa, sem substituir o aceite técnico das demais.
|
||||
|
||||
## Cobertura e fronteiras transversais
|
||||
|
||||
- PBX/schema/verificação ficam na agenda de compiler/general; tipos/input existentes na de PBS. A AGD88, que incorporou a execução instalada, recebe apresentação/transporte de diagnósticos, sem duplicar regras do loader.
|
||||
- Catálogos têm política comum própria; cada API decide sua fachada e testes no domínio consumidor. Gfx/composer e assets gráficos ficam com packer. SOUND/WAV e áudio PCM ficam fora desta wave pela revisão de escopo de 2026-10-27.
|
||||
- Closures detêm captura/calls indiretas e fixtures de callbacks; coleções detêm estado estruturado e adaptações. Compartilham IR sem criar contratos concorrentes.
|
||||
- Lifecycle detém BeforePause/BeforeResume e mecanismo de declaração; memcard detém role 3, manifest, SDK, transporte e persistência. A qualificação desses hooks nesta wave independe de áudio.
|
||||
- A agenda do jogo recebe autoria/build reproduzível, replay/oráculos, headroom, recursos/GC, resets/reloads, soak, callbacks complementares, save/load e distinção diretório/PMC.
|
||||
- Runtime conserva contratos, loader, VM, firmware e hosts. Insuficiência de quota ou transporte gera handoff explícito; não alterar limites ou inventar capacidades no consumer.
|
||||
- WallClock é HAL/host; não inferir syscall guest. Strings não implicam biblioteca geral de bytes. APIs administrativas dependem de uso/capability, sem exposição indiscriminada.
|
||||
- Não herdar oito horas como bloqueio: a evidência anterior de cerca de 3h22 terminou por disco cheio; o requisito de oito horas foi dispensado naquela entrega. A agenda do jogo define duração e limites próprios antes da execução.
|
||||
|
||||
Fora desta wave: áudio (incluindo SDK, SOUND/WAV e smoke audível), 3D, multiplayer, novo host portátil, background services, nova linguagem, editor completo, jogo comercial e sequenciador/FM. PMC depende de loader próprio; cartucho em diretório pode ser primeiro aceite. Terminal embutido (DSC-0071) e gestão de dependências (DSC-0072) não têm bloqueio demonstrado para esta integração.
|
||||
|
||||
## Opções e tradeoffs de coordenação
|
||||
|
||||
- **A — Agendas por escopo, ligadas por esta umbrella (organização solicitada).** Permite decisions claras e entregas verificáveis; exige manter dependências e cobertura entre owners.
|
||||
- **B — Uma decision global de todos os temas.** Centraliza aceite, mas volta a misturar escolhas de linguagem, formatos, transporte e gameplay; descartada como organização pelo pedido do usuário.
|
||||
|
||||
Recomendação: manter a opção A e resolver cada questão técnica na agenda dona. A umbrella registra mudanças de dependência e lacunas sem sobrepor decisões aceitas.
|
||||
|
||||
## Perguntas de coordenação em aberto
|
||||
|
||||
- [ ] Qual prioridade de discussão entre as frentes da adequação inicial?
|
||||
- [ ] Após as decisões filhas, há dependências ou responsabilidades ainda sem owner?
|
||||
- [ ] A evidência agregada cobre todos os escopos recebidos e distingue entrega do provider de prova do consumidor?
|
||||
|
||||
Questões de sintaxe, catálogo, transporte, hosts, duração e jogo pertencem às agendas específicas.
|
||||
|
||||
## Critério para encerrar a umbrella
|
||||
|
||||
Confirmar que todas as obrigações recebidas têm destino e evidência rastreáveis, que as discussões filhas atingiram seus aceites ou tiveram escopo explicitamente revisto pelo usuário, e que a qualificação do jogo produziu seu resultado acordado. Encerrar pelo workflow com housekeeping apropriado; abrir filhas não constitui entrega e o abandono da origem runtime não comprova prontidão.
|
||||
|
||||
## Próximo passo sugerido
|
||||
|
||||
Convergir as capacidades ainda abertas e preparar o corpus da AGD88. Executar nela a qualificação final do jogo e da integração instalada; consultar as lessons das frentes concluídas e cada filha para suas perguntas e critérios próprios.
|
||||
|
||||
## Resolução
|
||||
|
||||
Desmembramento organizacional realizado por solicitação do usuário. Umbrella permanece aberta para coordenação; decisões técnicas continuam abertas nas respectivas agendas. Nenhum teste de execução foi realizado nesta operação documental.
|
||||
|
||||
## Evidência e handoff da AGD76 — 2026-10-14
|
||||
|
||||
Owner da entrega: compiler/general; consumo de diagnóstico: studio.
|
||||
O backend comum agora transporta Registry tipado completo, preserva metadados
|
||||
até PBX v0 e foi qualificado com frontend sintético e loader/VM reais.
|
||||
Referência permanente: [LSN-0079](../../lessons/DSC-0074-compiler-pbx-registry-conformance/LSN-0079-typed-common-ir-to-production-pbx.md).
|
||||
|
||||
- Runtime alvo: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, macOS 27.0.1 arm64.
|
||||
- Java: 462 aprovações, zero falhas, 15 testes de integração antigos ignorados.
|
||||
Inclui 245 testes PBS; isso não comprova migração executável completa do PBS.
|
||||
- Loader de produção: 12 imagens aceitas, 11 executadas e 32 recusas verificadas.
|
||||
Inclui closures/capturas, trait, Array/Dynamic, roles, intrínseco, binding nativo,
|
||||
bytes independentes, limites, código inalcançável e diagnósticos estruturados.
|
||||
- Correção Studio: preservar `error.details` integralmente em
|
||||
`AutomationFailure.runtimeError`, sem converter PC de verificação/offset em PC executado.
|
||||
- Pendência runtime comprovada: `response.schema.json` não enumera LifecycleRole,
|
||||
LifecycleSignature, DuplicateLifecycleRole e NonFiniteValue já presentes em
|
||||
LoadReason. LifecycleRole e NonFiniteValue foram observados no corpus e falham
|
||||
no schema publicado. Corrigir o enum no runtime; não reescrever payloads no Studio.
|
||||
- PBS continua responsável pelos tipos/representações e pelo lowering de
|
||||
Optional/Result; sem novas regras de linguagem no BE. Catálogos, input, novas
|
||||
capacidades, hooks e memcard continuam nos tickets consumidores existentes.
|
||||
- Conforme orientação do usuário, AGD75 será entregue integrada; migrações e
|
||||
testes dos outros setores não bloqueiam o fechamento do recorte comum AGD76.
|
||||
|
||||
## Evidência e handoff da AGD77 — 2026-10-15
|
||||
|
||||
Owner: `compiler/general`; consumidores: `compiler/pbs`, `vm-arch` e `studio`. Porte implementado no PLN-0143 e aceito pelo usuário em 2026-10-15, com revisão explícita do gate instalado. Referência permanente: [LSN-0080](../../lessons/DSC-0075-compiler-runtime-catalog-parity/LSN-0080-manual-runtime-catalog-port-and-conformance.md).
|
||||
|
||||
- Runtime alvo: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, checkout limpo, macOS 27.0.1 arm64; JDK 25 no build, JDK 21 no launcher instalado; Cargo test/default features.
|
||||
- CSVs exatos e proveniência versionada: 105 intrínsecos, 18 campos, 15 constantes/16 slots. Porte Java manual completo, validação de ABI/carriers e preservação de mutação/custos. Spec: `docs/compiler/general/specs/runtime-catalog-support.md`.
|
||||
- Regressões compiler/PBS: 420 aprovações, zero falhas, 12 skips antigos; paridade ativa. Verificação de fonte/hash e exportador real do provider passou. Harness com loader/VM reais passou, incluindo constantes por bits, vec2.zero, Random compartilhado com resultado descartado, input sem hardware e rejeição de ID removido inalcançável. Não é prova da fachada PBS nem do host instalado.
|
||||
- Recursos dos JARs compiler/SDK conferidos fora do checkout: identidade e hashes passaram. O gate instalado completo falha em `LOWER_IRVM_INVALID_TYPED_REGISTRY: typed function metadata required: Gfx.clear`; a mesma falha foi reproduzida no HEAD anterior `bd5694dbdf5b214b4295fc8e01ddbe0ba5479599`. O usuário aprovou explicitamente concluir a AGD77 com o gate de catálogos instalados e manter essa correção na AGD78. O teste completo permanece ativo e deve passar após a correção PBS; a integração instalada continua na AGD80. Esta exceção não declara esses consumidores concluídos.
|
||||
- Handoffs concretos registrados na AGD78 (tipos/input/metadados PBS e vec2), AGD83 (math/constants), AGD84 (Random) e AGD80 (recursos e execução instalada). A representação do catálogo não equivale à disponibilidade dessas APIs na autoria PBS. As lacunas de fault-schema do runtime já registradas na entrega AGD76 permanecem visíveis no harness.
|
||||
|
||||
## Entrega AGD78 / DSC-0076 — 2026-10-15
|
||||
|
||||
- Implementação de compiler/pbs concluída: Pad/Button/LowPad, seis queries Touch, int=Int32 e long=Int64, conversões explícitas, metadados tipados, grupos completos e constantes pelo catálogo.
|
||||
- Qualificação: 493 testes aprovados, 13 skips preexistentes, zero falhas; 114 programas PBS passaram pelo PBX e runtime real, incluindo 48 consultas Pad com valores locais/parâmetros e 48 com constantes, seis Touch, valores/grupos/faults e defaults dos oito tipos. Leituras controladas verificam um endpoint por consulta; ausência de plataforma verifica TRAP_UNAVAILABLE.
|
||||
- O gate completo installedKnowledgeTest agora passa (2 testes); a falha de metadados de Gfx.clear registrada na entrega AGD77 foi corrigida. AGD80 continua responsável pela integração desktop própria.
|
||||
- Evidência: runtime f7d7c167531bb662a1af9d73fc326bb476bf8aa7; Studio base 603ed012272b137361ba618f6887f015f7317803 com esta implementação; Darwin arm64. Runtime sem alterações; lacunas conhecidas de fault-schema permanecem explícitas no harness compartilhado.
|
||||
- [LSN-0081: contratos, comandos, resultados e pitfalls](../../lessons/DSC-0076-pbs-existing-types-input-alignment/LSN-0081-pbs-typed-values-and-input.md).
|
||||
|
||||
|
||||
## Entrega AGD79 / DSC-0077 — 2026-10-16
|
||||
|
||||
- Escopo explicitamente revisto pelo usuário: contratos do packer e melhoria Jenkins; sem provisionamento runtime no CI e sem novos testes automatizados contra runtime, inclusive locais. Integração manual com jogos existentes; não executada nesta entrega.
|
||||
- 119 testes packer passaram, incluindo cinco novos casos de payload GLYPH/SCENE completo, header interno, offsets, identidade/preload e recusa de paleta inválida. Nenhum writer ou formato alterado.
|
||||
- Jenkins usa wrapper, JVM headless, clean separado, --continue e publicação/arquivamento em post/always com publishers isolados. Gates de cobertura preservados. Sete cenários locais com doubles passaram; controlador Jenkins não executado.
|
||||
- Verificação geral: 897 testes, duas falhas em arquivos não alterados (allowlist PBS e exemplo de contrato MCP), 13 skips existentes. JaCoCo consolidado XML/HTML foi gerado apesar das falhas. O gate geral não está verde; falhas não foram ocultadas.
|
||||
- [LSN-0082: escopo, cobertura, comandos e limitações](../../lessons/DSC-0077-packer-runtime-graphics-conformance/LSN-0082-packer-contracts-and-ci-failure-evidence.md). A entrega não comprova loading/rendering no runtime nem execução de jogos.
|
||||
|
||||
## Consolidação AGD80 → AGD88 — 2026-10-16
|
||||
|
||||
O usuário solicitou concentrar a integração instalada na qualificação do jogo e remover a agenda separada. A AGD88 / DSC-0086 recebeu integralmente os targets, evidências propostas, três perguntas abertas, alternativas e fronteiras da AGD80 / DSC-0078, além do handoff de catálogos atualizado pela correção PBS da LSN-0081. Áudio, lifecycle e memcard passam a referenciar a AGD88 como interface de qualificação final, sem dependência circular para sua implementação local.
|
||||
|
||||
A DSC-0078 é encerrada por consolidação via `discussion housekeep --no-lesson`; o estado `done` registra o encerramento administrativo, não execução ou aceite técnico da integração. Não há lesson nova porque não houve implementação ou aprendizado técnico novo. Referências anteriores à AGD80 nesta umbrella são históricas; o owner atual de seu escopo é a AGD88. Nenhum teste runtime foi executado nesta operação.
|
||||
|
||||
## Follow-up de coleções SDK — AGD89 / DSC-0087
|
||||
|
||||
Por solicitação do usuário, [AGD89 — PBS SDK Collections](../../lessons/DSC-0087-pbs-sdk-collections/LSN-0096-shared-foundations-and-separate-collection-contracts.md) recebe List/Set/Map e suas operações/políticas antes discutidas na AGD81. Owner `compiler/pbs`; depende do contrato de arrays da AGD81 e coordena callbacks com AGD82 quando aplicável. Não bloqueia o fechamento da AGD81; a qualificação do jogo usa somente as coleções necessárias ao corpus acordado.
|
||||
|
||||
## Fechamento de DSC-0079
|
||||
|
||||
PLN-0146 concluído: arrays tipados/contextuais, optional/if let, Struct/contract/CALL_TRAIT, singleton importado e integração de tooling/conhecimento instalado. A base está consolidada em LSN-0083. Evidência: 500 testes executados sem falha, 27 novos casos PBS no loader/VM e 18 verificações de quota/ownership; 13 testes desabilitados e duas lacunas preexistentes de schema estão explicitados no relatório. AGD82 e AGD89 consomem a base; a qualificação instalada final permanece em AGD88.
|
||||
|
||||
## DSC-0080 / AGD82 concluída — 2026-10-17
|
||||
|
||||
PLN-0147 concluído: Fn estrutural, lambdas com capturas explícitas por valor,
|
||||
remoção de callback nominal/bind, imports, editor e conhecimento instalado.
|
||||
Closures seguem o lifecycle normal de objetos, sobrevivem entre frames enquanto
|
||||
alcançáveis e são coletáveis. A integração existente de [Frame] foi preservada;
|
||||
PBS não ganhou sync nem coroutines. Evidência: 513 testes executados sem falha,
|
||||
13 desabilitados preexistentes; nove casos PBS de closures executados na VM,
|
||||
seis casos de quotas/ownership e retenção/coleta em três frames reais.
|
||||
Runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, macOS 27.0.1 arm64,
|
||||
limites padrão fora dos casos explícitos de quota. As duas lacunas de schema
|
||||
preexistentes continuam registradas na [lesson de closures](../../lessons/DSC-0080-pbs-closures-and-indirect-calls/LSN-0084-pbs-function-values-and-explicit-captures.md).
|
||||
A qualificação do jogo instalado permanece em AGD88.
|
||||
|
||||
## Evidência math/mathf — DSC-0081 / PLN-0148 — 2026-10-17
|
||||
|
||||
Constantes em services de projeto e SDK, exportação/importação com alias e as 26
|
||||
assinaturas math/mathf foram implementadas. Pi/tau usam bits canônicos via
|
||||
BUILTIN_CONST; chamadas matemáticas permanecem executáveis. A LSN-0085 preserva
|
||||
contrato, implementação e comandos de reprodução.
|
||||
|
||||
Runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, checkout limpo e não alterado;
|
||||
macOS 27.0.1 arm64, dev/release, feature resource-diagnostics, limites padrão e
|
||||
capabilities NONE para math. O harness completo passou nos dois perfis, incluindo
|
||||
522 vetores fonte PBS → PBX → VM (261 casos com e sem otimização), comparação
|
||||
exata de bits/faults/ciclos, constantes e imports reais. Frontend: 249 testes;
|
||||
backend: 175 passaram e 12 skips preexistentes; suítes de integração afetadas e
|
||||
os dois gates de installedKnowledgeTest passaram.
|
||||
|
||||
Pendências explícitas: qualificação macOS/x86_64 e Linux/x86_64. Esta entrega não
|
||||
comprova jogo completo nem distribuição do runtime. Os gaps de schema do provider
|
||||
LifecycleRole/NonFiniteValue continuam reportados pelo harness sem alterar payloads.
|
||||
|
||||
|
||||
## Entrega AGD84 / DSC-0082 — 2026-10-17
|
||||
|
||||
- DEC-0070 / PLN-0149 executados: SDK `@sdk:random` com `Random` opaco e `random.new/next/nextf/range`, identidade em armazenamento/capturas, efeitos preservados e rejeição de construção/adaptação estrutural indevida.
|
||||
- Corpus fonte PBS → PBX → runtime: 227 fixtures por perfil debug/release, incluindo seis seeds, bits Float/Int64, aliases, replay, argumentos nomeados, limites/falhas/custos, typed null e GC (1.100 objetos descartados recuperados).
|
||||
- Regressões Java: 489 aprovações, 12 skips existentes, zero falhas; inclui `installedKnowledgeTest`. Catálogo e exportador do provider coincidem. Suites Random do provider: 13 contratos + 11 testes privados por perfil, separados da prova PBS.
|
||||
- Runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, macOS arm64. Sem alegação de qualificação de outros alvos, corpus do jogo ou execução pelo processo de runtime instalado. As lacunas conhecidas do schema de falhas permanecem explicitadas pelo harness.
|
||||
- Conhecimento e fingerprints: [LSN-0086](../../lessons/DSC-0082-pbs-runtime-random-integration/LSN-0086-explicit-random-handles-and-source-conformance.md) e seu `evidence.json`. Integração PBS concluída; qualificação do jogo permanece com DSC-0086.
|
||||
|
||||
|
||||
## Handoff de lifecycle — 2026-10-28
|
||||
|
||||
A DSC-0084 (AGD86 / DEC-0081 / PLN-0159) entregou `[BeforePause]` e
|
||||
`[BeforeResume]`, validação e unicidade por imagem, roles tipados preservados no
|
||||
pipeline e exemplo instalado compilável. A LSN-0097 acima consolida o contrato e
|
||||
os links para fontes, specs e evidências. Runtime qualificado:
|
||||
`dcf6561ea73446e0a3e1cf1c73eda20923b38df0`, macOS arm64, sem escrita/commit no
|
||||
checkout runtime.
|
||||
|
||||
Dezessete imagens PBS de produção e duas fixtures sintéticas de sync passaram
|
||||
em runtime dev/release, incluindo ambas as variantes do otimizador PBS. A prova
|
||||
usa VM e Firmware/SystemOS de produção: Home/resume, hooks independentes/ausentes,
|
||||
ordem de efeitos, PC/stacks/globals/init guard, contadores da sessão do jogo,
|
||||
suspensão direta/Shell, debugger/budget e falhas sem gameplay adicional.
|
||||
`./gradlew test :prometeu-app:installedKnowledgeTest --console=plain` passou;
|
||||
o exemplo compilado dos JARs instalados preserva ambos os roles.
|
||||
|
||||
Essa evidência fecha a capacidade local de lifecycle. MemcardBoot/bootstrap e
|
||||
persistência permanecem na DSC-0085; jogo, distribuição runtime instalada e
|
||||
integração Build/Play/headless/UI/MCP permanecem sob a qualificação da DSC-0086.
|
||||
Não promover a compilação do exemplo instalado a execução de processo runtime
|
||||
instalado ou a prova de save/load.
|
||||
|
||||
|
||||
## Handoff de memcard / MemcardBuffer — 2026-10-30
|
||||
|
||||
DSC-0085 concluída: identidade estável/slots, MemcardBoot/gate neutro, SDK completo
|
||||
com MemcardBuffer → Array<Int32> e integração pública do runtime 1.1/memcard.
|
||||
MCP preserva escolhas/estado nativos e recusas de encerramento; DEV pede consentimento
|
||||
separado para descarte após recusa. Debug/headless compartilham seleção local de mídia.
|
||||
|
||||
A prova do consumidor passou contra executáveis runtime dev/release e distribuição
|
||||
extraída, sempre com PBS com/sem otimização: SUCCESS → término do processo → novo
|
||||
processo → leitura exata, repetida nas versões 1 e 2 com mesmo app_id. O leitor não
|
||||
alcança chamadas de gravação e deixa a imagem inteira inalterada. Não é apenas remount
|
||||
nativo nem a prova neutra independente do provider. A matriz nativa também passou.
|
||||
Regressão: 1.118 testes, zero falhas, 13 skips; knowledge instalado 2, DEV JavaFX 5,
|
||||
headless existente 4 e memcard em processos 2 por perfil passaram.
|
||||
|
||||
O provider foi qualificado por hashes sobre dcf6561 e recebeu externamente o commit
|
||||
a4bec5b durante a finalização, sem mudança nesses hashes; este trabalho não escreveu
|
||||
nem criou commits no runtime. A capacidade
|
||||
memcard está qualificada. A qualificação integrada do jogo de referência/fluxo de
|
||||
distribuição continua na DSC-0086, sem promover estes testes a essa entrega.
|
||||
|
||||
Consolidação: [LSN-0099](../../lessons/DSC-0085-studio-memcard-persistence-integration/LSN-0099-explicit-buffers-and-process-proven-persistence.md).
|
||||
Evidência: [sumário](../../lessons/DSC-0085-studio-memcard-persistence-integration/evidence/summary.json).
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-000B"
|
||||
origin: "discussion-framework:studio:DSC-0073:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0073"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "e67949b9db471f62360d5cf7d545c3551380a4e66f8a7f4e5be7be84344d72b3"
|
||||
size: 407
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.645646Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0073","status":"open","ticket":"studio-runtime-readiness","title":"Studio Runtime Readiness","created_at":"2026-10-14","updated_at":"2026-10-27","tags":["runtime-integration","game-readiness"],"agendas":[{"id":"AGD-0075","file":"AGD-0075-studio-runtime-readiness.md","status":"open","created_at":"2026-10-14","updated_at":"2026-10-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-000B"
|
||||
origin: "ai-engineering:discussion-import:studio:DSC-0073"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "e4bdc14b5f72b4cf2d4999a8b9ddaa2596c3589741973226d2518fdad9b380fc"
|
||||
size: 675
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.652587Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-000B",
|
||||
"sourceId" : "studio",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio",
|
||||
"dscId" : "DSC-0073",
|
||||
"targets" : [ "studio" ],
|
||||
"contentHash" : "075e50ba1d97d3c53a5c3c44d4086923dfea792fd1fb54cd048ff266e8d1f664",
|
||||
"dscSha256" : "e67949b9db471f62360d5cf7d545c3551380a4e66f8a7f4e5be7be84344d72b3",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0075",
|
||||
"file" : "AGD-0075-studio-runtime-readiness.md",
|
||||
"sha256" : "fbbdbbeb415d758f8fbc7343dab59fa7400bf427a48a91c4fcaed7c3683370d2",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+284
@@ -0,0 +1,284 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-000B"
|
||||
discussionId: "df:studio:AGD-0075"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:studio"
|
||||
createdAt: "2026-11-16T15:31:32.633168Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
id: AGD-0075
|
||||
ticket: studio-runtime-readiness
|
||||
title: Studio Runtime Readiness
|
||||
status: open
|
||||
created: 2026-10-14
|
||||
resolved:
|
||||
decision:
|
||||
tags: [runtime-integration, game-readiness]
|
||||
---
|
||||
|
||||
## Problema e papel da umbrella
|
||||
|
||||
Coordenar a prontidão fonte → compiler → packer → cartucho → runtime sem concentrar decisões de múltiplos domínios numa única agenda.
|
||||
|
||||
**Worker:** Agenda Worker. **Domínio owner:** `studio`, coordenação da integração ponta a ponta. Em 2026-10-14, o usuário solicitou agendas próprias por escopo e manteve esta AGD-0075 / DSC-0073 apenas como umbrella. Os detalhes técnicos e perguntas foram distribuídos para as agendas abaixo.
|
||||
|
||||
Esta umbrella mantém mapa de cobertura, dependências e acompanhamento. Cada agenda filha conduz sua própria convergência, decision, plan, implementação e lesson. Nenhuma opção técnica foi aceita por este desmembramento; não há decision ou plano global autorizando código.
|
||||
|
||||
## Contexto e proveniência
|
||||
|
||||
Origem: AGD-0060 / DSC-0057 do runtime (referência histórica), auditoria estática de 2026-10-14, snapshots runtime `3946874` e Studio `a9ede541`, sem builds/testes naquela rodada. Na verificação desta decomposição, `discussion --root ../runtime context DSC-0057` informa status `abandoned` e arquivo da AGD-0060 ausente. Esta operação não alterou o runtime. A proveniência fica preservada por IDs e pelos escopos recebidos nas filhas; os contratos atuais permanecem referenciados nelas. IDs são locais a cada repositório.
|
||||
|
||||
O usuário informou que **a última versão do runtime estará disponível para testes**. Registrar revisão/hash, plataforma e configuração por rodada para reprodução. Disponibilidade não comprova execução nem conformidade.
|
||||
|
||||
## Mapa de agendas e dependências propostas
|
||||
|
||||
Todas as agendas foram abertas nesta decomposição. O estado atualizado pertence ao índice e deve ser consultado com `discussion status/context`; esta tabela é um mapa de escopo, não uma cópia de estados.
|
||||
|
||||
| Agenda / discussão | Domínio owner | Interfaces/dependências propostas |
|
||||
| --- | --- | --- |
|
||||
| [LSN-0079 / DSC-0074 — Compiler PBX Registry Conformance (AGD76 concluída)](../../lessons/DSC-0074-compiler-pbx-registry-conformance/LSN-0079-typed-common-ir-to-production-pbx.md) | `compiler/general` | Base |
|
||||
| [LSN-0080 / DSC-0075 — Compiler Runtime Catalog Parity (AGD77 concluída)](../../lessons/DSC-0075-compiler-runtime-catalog-parity/LSN-0080-manual-runtime-catalog-port-and-conformance.md) | `compiler/general` | Base |
|
||||
| [DSC-0076 — PBS Existing Types and Input Alignment (concluída)](../../lessons/DSC-0076-pbs-existing-types-input-alignment/LSN-0081-pbs-typed-values-and-input.md) | `compiler/pbs` | AGD-0076, AGD-0077 |
|
||||
| [DSC-0077 — Packer Contract Qualification (concluída)](../../lessons/DSC-0077-packer-runtime-graphics-conformance/LSN-0082-packer-contracts-and-ci-failure-evidence.md) | `packer` | AGD-0076 |
|
||||
| [LSN-0083 / DSC-0079 — Arrays, optional e Struct/contract (concluída)](../../lessons/DSC-0079-pbs-typed-collections-and-dynamic/LSN-0083-pbs-arrays-optional-and-contract-execution.md) | `compiler/pbs` | AGD-0076, AGD-0077, AGD-0078 |
|
||||
| [LSN-0084 / DSC-0080 — PBS Closures (completed)](../../lessons/DSC-0080-pbs-closures-and-indirect-calls/LSN-0084-pbs-function-values-and-explicit-captures.md) | `compiler/pbs` | AGD-0076, AGD-0081 |
|
||||
| [LSN-0085 / DSC-0081 — PBS Runtime Math Integration concluída](../../lessons/DSC-0081-pbs-runtime-math-integration/LSN-0085-service-constants-and-source-math-conformance.md) | `compiler/pbs` | AGD-0076, AGD-0077, AGD-0078 |
|
||||
| [LSN-0086 / DSC-0082 — PBS Runtime Random Integration (AGD84 concluída)](../../lessons/DSC-0082-pbs-runtime-random-integration/LSN-0086-explicit-random-handles-and-source-conformance.md) | `compiler/pbs` | AGD-0076, AGD-0077, AGD-0078 |
|
||||
| [AGD-0085 / DSC-0083 — PBS PCM Audio Integration (abandonada)](./AGD-0085-pbs-pcm-audio-integration.md) | `compiler/pbs` | Histórico; áudio fora desta wave por solicitação do usuário em 2026-10-27 |
|
||||
| [LSN-0097 / DSC-0084 — PBS Guest Lifecycle Hooks (concluída)](../../lessons/DSC-0084-pbs-guest-lifecycle-hooks/LSN-0097-explicit-guest-hooks-and-preserved-continuations.md) | `compiler/pbs` | AGD-0076, AGD-0078 |
|
||||
| [LSN-0099 / DSC-0085 — Studio Memcard Persistence Integration](../../lessons/DSC-0085-studio-memcard-persistence-integration/LSN-0099-explicit-buffers-and-process-proven-persistence.md) | `studio` | AGD-0076, AGD-0077, AGD-0081, AGD-0086 |
|
||||
| [AGD-0088 / DSC-0086 — Studio Reference Game Qualification (abandonada)](./AGD-0088-studio-reference-game-qualification.md) | `studio` | Histórico; Pong entregue na DSC-0101. Qualificação ampla abandonada por solicitação do usuário em 2026-11-05 |
|
||||
|
||||
Os links são relativos e recíprocos: cada filha referencia esta umbrella. A CLI registra criação/estado/IDs; as relações de umbrella são documentadas aqui e nas filhas, pois `discussion start` não oferece campo de parent/dependência. Fica registrada a lacuna de automação dessas relações no framework, sem editar o índice manualmente.
|
||||
|
||||
## Revisão de escopo — áudio fora da wave — 2026-10-27
|
||||
|
||||
Por solicitação explícita do usuário, AGD85 / DSC-0083 foi abandonada e áudio
|
||||
fica fora desta wave, inclusive o suporte mínimo discutido. SDK de áudio,
|
||||
produção SOUND/WAV, smoke audível e qualificação integrada de áudio deixam de
|
||||
ser entregas ou gates desta umbrella e da AGD88. A existência de áudio no runtime
|
||||
não representa entrega do consumidor. Lifecycle e persistência mantêm suas
|
||||
agendas próprias. Uma futura retomada requer solicitação e discussão próprias.
|
||||
|
||||
## Sequência recomendada e coordenação
|
||||
|
||||
**Atualização de escopo — 2026-11-05:** o usuário solicitou abandonar
|
||||
AGD-0088 / DSC-0086 após a entrega do primeiro Pong. A
|
||||
[LSN-0101](../../lessons/DSC-0101-pong-playable-test-project/LSN-0101-pong-as-the-first-studio-game.md)
|
||||
preserva o jogo entregue e a
|
||||
[LSN-0102](../../lessons/DSC-0102-sample-project-sdk-refresh/LSN-0102-refreshing-samples-without-changing-their-identity.md)
|
||||
preserva a atualização dos exemplos. A qualificação ampla não executada,
|
||||
incluindo o escopo incorporado da antiga AGD80, deixa de ser entrega ou gate
|
||||
ativo desta umbrella. Ela não foi validada pelo Pong nem transferida para outra
|
||||
agenda. Os encaminhamentos à DSC-0086 nas seções históricas abaixo descrevem a
|
||||
coordenação anterior ao abandono. As capacidades locais já concluídas mantêm
|
||||
suas próprias decisões, lessons e evidências; eventual retomada da qualificação
|
||||
integrada requer nova solicitação e discussão.
|
||||
|
||||
1. **Adequação do existente:** PBX/IR e catálogos estabelecem a base; tipos/input PBS e assets gráficos fecham seus contratos locais. A prova integrada de execução instalada foi incorporada à qualificação final na AGD88.
|
||||
2. **Novas capacidades:** coleções, closures, math, random, lifecycle e memcard fecham suas próprias escolhas e fixtures fonte → execução. Dependências indicam interfaces; não exigem esperar para iniciar as discussões.
|
||||
3. **Qualificação pelo jogo:** definir jogo e corpus cedo; executar a qualificação após as capacidades necessárias e fixtures auxiliares estarem prontas, incluindo Build/Play/headless/MCP contra distribuição instalada identificada, escopo incorporado da AGD80.
|
||||
|
||||
O schema PBX v0 completo integra a adequação inicial, inclusive tabelas vazias e role 0, mesmo que sintaxe de novas capacidades venha depois. Não exigir toda a expansão para restaurar a execução de um exemplo simples. A agenda do jogo consolida prova representativa, sem substituir o aceite técnico das demais.
|
||||
|
||||
## Cobertura e fronteiras transversais
|
||||
|
||||
- PBX/schema/verificação ficam na agenda de compiler/general; tipos/input existentes na de PBS. A AGD88, que incorporou a execução instalada, recebe apresentação/transporte de diagnósticos, sem duplicar regras do loader.
|
||||
- Catálogos têm política comum própria; cada API decide sua fachada e testes no domínio consumidor. Gfx/composer e assets gráficos ficam com packer. SOUND/WAV e áudio PCM ficam fora desta wave pela revisão de escopo de 2026-10-27.
|
||||
- Closures detêm captura/calls indiretas e fixtures de callbacks; coleções detêm estado estruturado e adaptações. Compartilham IR sem criar contratos concorrentes.
|
||||
- Lifecycle detém BeforePause/BeforeResume e mecanismo de declaração; memcard detém role 3, manifest, SDK, transporte e persistência. A qualificação desses hooks nesta wave independe de áudio.
|
||||
- A agenda do jogo recebe autoria/build reproduzível, replay/oráculos, headroom, recursos/GC, resets/reloads, soak, callbacks complementares, save/load e distinção diretório/PMC.
|
||||
- Runtime conserva contratos, loader, VM, firmware e hosts. Insuficiência de quota ou transporte gera handoff explícito; não alterar limites ou inventar capacidades no consumer.
|
||||
- WallClock é HAL/host; não inferir syscall guest. Strings não implicam biblioteca geral de bytes. APIs administrativas dependem de uso/capability, sem exposição indiscriminada.
|
||||
- Não herdar oito horas como bloqueio: a evidência anterior de cerca de 3h22 terminou por disco cheio; o requisito de oito horas foi dispensado naquela entrega. A agenda do jogo define duração e limites próprios antes da execução.
|
||||
|
||||
Fora desta wave: áudio (incluindo SDK, SOUND/WAV e smoke audível), 3D, multiplayer, novo host portátil, background services, nova linguagem, editor completo, jogo comercial e sequenciador/FM. PMC depende de loader próprio; cartucho em diretório pode ser primeiro aceite. Terminal embutido (DSC-0071) e gestão de dependências (DSC-0072) não têm bloqueio demonstrado para esta integração.
|
||||
|
||||
## Opções e tradeoffs de coordenação
|
||||
|
||||
- **A — Agendas por escopo, ligadas por esta umbrella (organização solicitada).** Permite decisions claras e entregas verificáveis; exige manter dependências e cobertura entre owners.
|
||||
- **B — Uma decision global de todos os temas.** Centraliza aceite, mas volta a misturar escolhas de linguagem, formatos, transporte e gameplay; descartada como organização pelo pedido do usuário.
|
||||
|
||||
Recomendação: manter a opção A e resolver cada questão técnica na agenda dona. A umbrella registra mudanças de dependência e lacunas sem sobrepor decisões aceitas.
|
||||
|
||||
## Perguntas de coordenação em aberto
|
||||
|
||||
- [ ] Qual prioridade de discussão entre as frentes da adequação inicial?
|
||||
- [ ] Após as decisões filhas, há dependências ou responsabilidades ainda sem owner?
|
||||
- [ ] A evidência agregada cobre todos os escopos recebidos e distingue entrega do provider de prova do consumidor?
|
||||
|
||||
Questões de sintaxe, catálogo, transporte, hosts, duração e jogo pertencem às agendas específicas.
|
||||
|
||||
## Critério para encerrar a umbrella
|
||||
|
||||
Confirmar que todas as obrigações recebidas têm destino e evidência rastreáveis, que as discussões filhas atingiram seus aceites ou tiveram escopo explicitamente revisto pelo usuário, e que a qualificação do jogo produziu seu resultado acordado. Encerrar pelo workflow com housekeeping apropriado; abrir filhas não constitui entrega e o abandono da origem runtime não comprova prontidão.
|
||||
|
||||
## Próximo passo sugerido
|
||||
|
||||
Convergir as capacidades ainda abertas e preparar o corpus da AGD88. Executar nela a qualificação final do jogo e da integração instalada; consultar as lessons das frentes concluídas e cada filha para suas perguntas e critérios próprios.
|
||||
|
||||
## Resolução
|
||||
|
||||
Desmembramento organizacional realizado por solicitação do usuário. Umbrella permanece aberta para coordenação; decisões técnicas continuam abertas nas respectivas agendas. Nenhum teste de execução foi realizado nesta operação documental.
|
||||
|
||||
## Evidência e handoff da AGD76 — 2026-10-14
|
||||
|
||||
Owner da entrega: compiler/general; consumo de diagnóstico: studio.
|
||||
O backend comum agora transporta Registry tipado completo, preserva metadados
|
||||
até PBX v0 e foi qualificado com frontend sintético e loader/VM reais.
|
||||
Referência permanente: [LSN-0079](../../lessons/DSC-0074-compiler-pbx-registry-conformance/LSN-0079-typed-common-ir-to-production-pbx.md).
|
||||
|
||||
- Runtime alvo: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, macOS 27.0.1 arm64.
|
||||
- Java: 462 aprovações, zero falhas, 15 testes de integração antigos ignorados.
|
||||
Inclui 245 testes PBS; isso não comprova migração executável completa do PBS.
|
||||
- Loader de produção: 12 imagens aceitas, 11 executadas e 32 recusas verificadas.
|
||||
Inclui closures/capturas, trait, Array/Dynamic, roles, intrínseco, binding nativo,
|
||||
bytes independentes, limites, código inalcançável e diagnósticos estruturados.
|
||||
- Correção Studio: preservar `error.details` integralmente em
|
||||
`AutomationFailure.runtimeError`, sem converter PC de verificação/offset em PC executado.
|
||||
- Pendência runtime comprovada: `response.schema.json` não enumera LifecycleRole,
|
||||
LifecycleSignature, DuplicateLifecycleRole e NonFiniteValue já presentes em
|
||||
LoadReason. LifecycleRole e NonFiniteValue foram observados no corpus e falham
|
||||
no schema publicado. Corrigir o enum no runtime; não reescrever payloads no Studio.
|
||||
- PBS continua responsável pelos tipos/representações e pelo lowering de
|
||||
Optional/Result; sem novas regras de linguagem no BE. Catálogos, input, novas
|
||||
capacidades, hooks e memcard continuam nos tickets consumidores existentes.
|
||||
- Conforme orientação do usuário, AGD75 será entregue integrada; migrações e
|
||||
testes dos outros setores não bloqueiam o fechamento do recorte comum AGD76.
|
||||
|
||||
## Evidência e handoff da AGD77 — 2026-10-15
|
||||
|
||||
Owner: `compiler/general`; consumidores: `compiler/pbs`, `vm-arch` e `studio`. Porte implementado no PLN-0143 e aceito pelo usuário em 2026-10-15, com revisão explícita do gate instalado. Referência permanente: [LSN-0080](../../lessons/DSC-0075-compiler-runtime-catalog-parity/LSN-0080-manual-runtime-catalog-port-and-conformance.md).
|
||||
|
||||
- Runtime alvo: `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, checkout limpo, macOS 27.0.1 arm64; JDK 25 no build, JDK 21 no launcher instalado; Cargo test/default features.
|
||||
- CSVs exatos e proveniência versionada: 105 intrínsecos, 18 campos, 15 constantes/16 slots. Porte Java manual completo, validação de ABI/carriers e preservação de mutação/custos. Spec: `docs/compiler/general/specs/runtime-catalog-support.md`.
|
||||
- Regressões compiler/PBS: 420 aprovações, zero falhas, 12 skips antigos; paridade ativa. Verificação de fonte/hash e exportador real do provider passou. Harness com loader/VM reais passou, incluindo constantes por bits, vec2.zero, Random compartilhado com resultado descartado, input sem hardware e rejeição de ID removido inalcançável. Não é prova da fachada PBS nem do host instalado.
|
||||
- Recursos dos JARs compiler/SDK conferidos fora do checkout: identidade e hashes passaram. O gate instalado completo falha em `LOWER_IRVM_INVALID_TYPED_REGISTRY: typed function metadata required: Gfx.clear`; a mesma falha foi reproduzida no HEAD anterior `bd5694dbdf5b214b4295fc8e01ddbe0ba5479599`. O usuário aprovou explicitamente concluir a AGD77 com o gate de catálogos instalados e manter essa correção na AGD78. O teste completo permanece ativo e deve passar após a correção PBS; a integração instalada continua na AGD80. Esta exceção não declara esses consumidores concluídos.
|
||||
- Handoffs concretos registrados na AGD78 (tipos/input/metadados PBS e vec2), AGD83 (math/constants), AGD84 (Random) e AGD80 (recursos e execução instalada). A representação do catálogo não equivale à disponibilidade dessas APIs na autoria PBS. As lacunas de fault-schema do runtime já registradas na entrega AGD76 permanecem visíveis no harness.
|
||||
|
||||
## Entrega AGD78 / DSC-0076 — 2026-10-15
|
||||
|
||||
- Implementação de compiler/pbs concluída: Pad/Button/LowPad, seis queries Touch, int=Int32 e long=Int64, conversões explícitas, metadados tipados, grupos completos e constantes pelo catálogo.
|
||||
- Qualificação: 493 testes aprovados, 13 skips preexistentes, zero falhas; 114 programas PBS passaram pelo PBX e runtime real, incluindo 48 consultas Pad com valores locais/parâmetros e 48 com constantes, seis Touch, valores/grupos/faults e defaults dos oito tipos. Leituras controladas verificam um endpoint por consulta; ausência de plataforma verifica TRAP_UNAVAILABLE.
|
||||
- O gate completo installedKnowledgeTest agora passa (2 testes); a falha de metadados de Gfx.clear registrada na entrega AGD77 foi corrigida. AGD80 continua responsável pela integração desktop própria.
|
||||
- Evidência: runtime f7d7c167531bb662a1af9d73fc326bb476bf8aa7; Studio base 603ed012272b137361ba618f6887f015f7317803 com esta implementação; Darwin arm64. Runtime sem alterações; lacunas conhecidas de fault-schema permanecem explícitas no harness compartilhado.
|
||||
- [LSN-0081: contratos, comandos, resultados e pitfalls](../../lessons/DSC-0076-pbs-existing-types-input-alignment/LSN-0081-pbs-typed-values-and-input.md).
|
||||
|
||||
|
||||
## Entrega AGD79 / DSC-0077 — 2026-10-16
|
||||
|
||||
- Escopo explicitamente revisto pelo usuário: contratos do packer e melhoria Jenkins; sem provisionamento runtime no CI e sem novos testes automatizados contra runtime, inclusive locais. Integração manual com jogos existentes; não executada nesta entrega.
|
||||
- 119 testes packer passaram, incluindo cinco novos casos de payload GLYPH/SCENE completo, header interno, offsets, identidade/preload e recusa de paleta inválida. Nenhum writer ou formato alterado.
|
||||
- Jenkins usa wrapper, JVM headless, clean separado, --continue e publicação/arquivamento em post/always com publishers isolados. Gates de cobertura preservados. Sete cenários locais com doubles passaram; controlador Jenkins não executado.
|
||||
- Verificação geral: 897 testes, duas falhas em arquivos não alterados (allowlist PBS e exemplo de contrato MCP), 13 skips existentes. JaCoCo consolidado XML/HTML foi gerado apesar das falhas. O gate geral não está verde; falhas não foram ocultadas.
|
||||
- [LSN-0082: escopo, cobertura, comandos e limitações](../../lessons/DSC-0077-packer-runtime-graphics-conformance/LSN-0082-packer-contracts-and-ci-failure-evidence.md). A entrega não comprova loading/rendering no runtime nem execução de jogos.
|
||||
|
||||
## Consolidação AGD80 → AGD88 — 2026-10-16
|
||||
|
||||
O usuário solicitou concentrar a integração instalada na qualificação do jogo e remover a agenda separada. A AGD88 / DSC-0086 recebeu integralmente os targets, evidências propostas, três perguntas abertas, alternativas e fronteiras da AGD80 / DSC-0078, além do handoff de catálogos atualizado pela correção PBS da LSN-0081. Áudio, lifecycle e memcard passam a referenciar a AGD88 como interface de qualificação final, sem dependência circular para sua implementação local.
|
||||
|
||||
A DSC-0078 é encerrada por consolidação via `discussion housekeep --no-lesson`; o estado `done` registra o encerramento administrativo, não execução ou aceite técnico da integração. Não há lesson nova porque não houve implementação ou aprendizado técnico novo. Referências anteriores à AGD80 nesta umbrella são históricas; o owner atual de seu escopo é a AGD88. Nenhum teste runtime foi executado nesta operação.
|
||||
|
||||
## Follow-up de coleções SDK — AGD89 / DSC-0087
|
||||
|
||||
Por solicitação do usuário, [AGD89 — PBS SDK Collections](../../lessons/DSC-0087-pbs-sdk-collections/LSN-0096-shared-foundations-and-separate-collection-contracts.md) recebe List/Set/Map e suas operações/políticas antes discutidas na AGD81. Owner `compiler/pbs`; depende do contrato de arrays da AGD81 e coordena callbacks com AGD82 quando aplicável. Não bloqueia o fechamento da AGD81; a qualificação do jogo usa somente as coleções necessárias ao corpus acordado.
|
||||
|
||||
## Fechamento de DSC-0079
|
||||
|
||||
PLN-0146 concluído: arrays tipados/contextuais, optional/if let, Struct/contract/CALL_TRAIT, singleton importado e integração de tooling/conhecimento instalado. A base está consolidada em LSN-0083. Evidência: 500 testes executados sem falha, 27 novos casos PBS no loader/VM e 18 verificações de quota/ownership; 13 testes desabilitados e duas lacunas preexistentes de schema estão explicitados no relatório. AGD82 e AGD89 consomem a base; a qualificação instalada final permanece em AGD88.
|
||||
|
||||
## DSC-0080 / AGD82 concluída — 2026-10-17
|
||||
|
||||
PLN-0147 concluído: Fn estrutural, lambdas com capturas explícitas por valor,
|
||||
remoção de callback nominal/bind, imports, editor e conhecimento instalado.
|
||||
Closures seguem o lifecycle normal de objetos, sobrevivem entre frames enquanto
|
||||
alcançáveis e são coletáveis. A integração existente de [Frame] foi preservada;
|
||||
PBS não ganhou sync nem coroutines. Evidência: 513 testes executados sem falha,
|
||||
13 desabilitados preexistentes; nove casos PBS de closures executados na VM,
|
||||
seis casos de quotas/ownership e retenção/coleta em três frames reais.
|
||||
Runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, macOS 27.0.1 arm64,
|
||||
limites padrão fora dos casos explícitos de quota. As duas lacunas de schema
|
||||
preexistentes continuam registradas na [lesson de closures](../../lessons/DSC-0080-pbs-closures-and-indirect-calls/LSN-0084-pbs-function-values-and-explicit-captures.md).
|
||||
A qualificação do jogo instalado permanece em AGD88.
|
||||
|
||||
## Evidência math/mathf — DSC-0081 / PLN-0148 — 2026-10-17
|
||||
|
||||
Constantes em services de projeto e SDK, exportação/importação com alias e as 26
|
||||
assinaturas math/mathf foram implementadas. Pi/tau usam bits canônicos via
|
||||
BUILTIN_CONST; chamadas matemáticas permanecem executáveis. A LSN-0085 preserva
|
||||
contrato, implementação e comandos de reprodução.
|
||||
|
||||
Runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, checkout limpo e não alterado;
|
||||
macOS 27.0.1 arm64, dev/release, feature resource-diagnostics, limites padrão e
|
||||
capabilities NONE para math. O harness completo passou nos dois perfis, incluindo
|
||||
522 vetores fonte PBS → PBX → VM (261 casos com e sem otimização), comparação
|
||||
exata de bits/faults/ciclos, constantes e imports reais. Frontend: 249 testes;
|
||||
backend: 175 passaram e 12 skips preexistentes; suítes de integração afetadas e
|
||||
os dois gates de installedKnowledgeTest passaram.
|
||||
|
||||
Pendências explícitas: qualificação macOS/x86_64 e Linux/x86_64. Esta entrega não
|
||||
comprova jogo completo nem distribuição do runtime. Os gaps de schema do provider
|
||||
LifecycleRole/NonFiniteValue continuam reportados pelo harness sem alterar payloads.
|
||||
|
||||
|
||||
## Entrega AGD84 / DSC-0082 — 2026-10-17
|
||||
|
||||
- DEC-0070 / PLN-0149 executados: SDK `@sdk:random` com `Random` opaco e `random.new/next/nextf/range`, identidade em armazenamento/capturas, efeitos preservados e rejeição de construção/adaptação estrutural indevida.
|
||||
- Corpus fonte PBS → PBX → runtime: 227 fixtures por perfil debug/release, incluindo seis seeds, bits Float/Int64, aliases, replay, argumentos nomeados, limites/falhas/custos, typed null e GC (1.100 objetos descartados recuperados).
|
||||
- Regressões Java: 489 aprovações, 12 skips existentes, zero falhas; inclui `installedKnowledgeTest`. Catálogo e exportador do provider coincidem. Suites Random do provider: 13 contratos + 11 testes privados por perfil, separados da prova PBS.
|
||||
- Runtime `f7d7c167531bb662a1af9d73fc326bb476bf8aa7`, macOS arm64. Sem alegação de qualificação de outros alvos, corpus do jogo ou execução pelo processo de runtime instalado. As lacunas conhecidas do schema de falhas permanecem explicitadas pelo harness.
|
||||
- Conhecimento e fingerprints: [LSN-0086](../../lessons/DSC-0082-pbs-runtime-random-integration/LSN-0086-explicit-random-handles-and-source-conformance.md) e seu `evidence.json`. Integração PBS concluída; qualificação do jogo permanece com DSC-0086.
|
||||
|
||||
|
||||
## Handoff de lifecycle — 2026-10-28
|
||||
|
||||
A DSC-0084 (AGD86 / DEC-0081 / PLN-0159) entregou `[BeforePause]` e
|
||||
`[BeforeResume]`, validação e unicidade por imagem, roles tipados preservados no
|
||||
pipeline e exemplo instalado compilável. A LSN-0097 acima consolida o contrato e
|
||||
os links para fontes, specs e evidências. Runtime qualificado:
|
||||
`dcf6561ea73446e0a3e1cf1c73eda20923b38df0`, macOS arm64, sem escrita/commit no
|
||||
checkout runtime.
|
||||
|
||||
Dezessete imagens PBS de produção e duas fixtures sintéticas de sync passaram
|
||||
em runtime dev/release, incluindo ambas as variantes do otimizador PBS. A prova
|
||||
usa VM e Firmware/SystemOS de produção: Home/resume, hooks independentes/ausentes,
|
||||
ordem de efeitos, PC/stacks/globals/init guard, contadores da sessão do jogo,
|
||||
suspensão direta/Shell, debugger/budget e falhas sem gameplay adicional.
|
||||
`./gradlew test :prometeu-app:installedKnowledgeTest --console=plain` passou;
|
||||
o exemplo compilado dos JARs instalados preserva ambos os roles.
|
||||
|
||||
Essa evidência fecha a capacidade local de lifecycle. MemcardBoot/bootstrap e
|
||||
persistência permanecem na DSC-0085; jogo, distribuição runtime instalada e
|
||||
integração Build/Play/headless/UI/MCP permanecem sob a qualificação da DSC-0086.
|
||||
Não promover a compilação do exemplo instalado a execução de processo runtime
|
||||
instalado ou a prova de save/load.
|
||||
|
||||
|
||||
## Handoff de memcard / MemcardBuffer — 2026-10-30
|
||||
|
||||
DSC-0085 concluída: identidade estável/slots, MemcardBoot/gate neutro, SDK completo
|
||||
com MemcardBuffer → Array<Int32> e integração pública do runtime 1.1/memcard.
|
||||
MCP preserva escolhas/estado nativos e recusas de encerramento; DEV pede consentimento
|
||||
separado para descarte após recusa. Debug/headless compartilham seleção local de mídia.
|
||||
|
||||
A prova do consumidor passou contra executáveis runtime dev/release e distribuição
|
||||
extraída, sempre com PBS com/sem otimização: SUCCESS → término do processo → novo
|
||||
processo → leitura exata, repetida nas versões 1 e 2 com mesmo app_id. O leitor não
|
||||
alcança chamadas de gravação e deixa a imagem inteira inalterada. Não é apenas remount
|
||||
nativo nem a prova neutra independente do provider. A matriz nativa também passou.
|
||||
Regressão: 1.118 testes, zero falhas, 13 skips; knowledge instalado 2, DEV JavaFX 5,
|
||||
headless existente 4 e memcard em processos 2 por perfil passaram.
|
||||
|
||||
O provider foi qualificado por hashes sobre dcf6561 e recebeu externamente o commit
|
||||
a4bec5b durante a finalização, sem mudança nesses hashes; este trabalho não escreveu
|
||||
nem criou commits no runtime. A capacidade
|
||||
memcard está qualificada. A qualificação integrada do jogo de referência/fluxo de
|
||||
distribuição continua na DSC-0086, sem promover estes testes a essa entrega.
|
||||
|
||||
Consolidação: [LSN-0099](../../lessons/DSC-0085-studio-memcard-persistence-integration/LSN-0099-explicit-buffers-and-process-proven-persistence.md).
|
||||
Evidência: [sumário](../../lessons/DSC-0085-studio-memcard-persistence-integration/evidence/summary.json).
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-000B"
|
||||
title: "studio: Studio Runtime Readiness"
|
||||
description: "Imported Discussion Framework discussion DSC-0073 from studio (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio).\n\
|
||||
\nTargets:\n- studio"
|
||||
goal: "Studio Runtime Readiness"
|
||||
motivation: "Continue the open agendas of studio/DSC-0073"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "OPEN"
|
||||
createdAt: "2026-11-16T15:31:32.631050Z"
|
||||
updatedAt: "2026-11-16T15:31:32.660077Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events: []
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-000C"
|
||||
origin: "discussion-framework:studio:AGD-0074:AGD-0074-studio-gerenciamento-e-reconstru-o-de-depend-ncias-locais.md"
|
||||
purpose: "Original DF agenda AGD-0074"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "ed981ce87b9e30bc5a757af088c4b928c2f91e559085c5fcb3e77f2038a01e9d"
|
||||
size: 3951
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.679901Z"
|
||||
+87
@@ -0,0 +1,87 @@
|
||||
---
|
||||
id: AGD-0074
|
||||
ticket: studio-dependency-management
|
||||
title: "Studio: gerenciamento e reconstrução de dependências locais"
|
||||
status: open
|
||||
created: 2026-10-06
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, dependencies]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio`
|
||||
|
||||
Worker: Agenda Worker. Impactos: `compiler/general` (resolução de dependências)
|
||||
e `compiler/pbs` (fontes reservadas SDK/core).
|
||||
|
||||
Necessidade essencial do produto: preparar e reconstruir cópias físicas das dependências do projeto, com uma área de gerenciamento no Studio.
|
||||
|
||||
## Context
|
||||
|
||||
Desdobramento da AGD-0071 / DSC-0069; fora do escopo daquela agenda. SDK/core acompanham o Studio; dependências externas inicialmente já existem na máquina. Cópias em .workspace/ ignorada pelo Git; download e cache ficam para avaliação futura.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Qual área do Studio apresenta dependências, origens locais e estado das cópias?
|
||||
- [ ] Quais metadados versionados permitem reconstrução, e quais paths pertencem à máquina?
|
||||
- [ ] Como identificar conteúdo e detectar alterações? Lockfile e hashes são propostas a avaliar.
|
||||
- [ ] Como preparar dependências transitivas e diagnosticar origens ausentes?
|
||||
- [ ] Como atualizar cópias sem invalidar consultas e sessões em andamento?
|
||||
- [ ] Como lidar com SDK/core indisponíveis na distribuição instalada?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A — Preparação local integrada ao Studio (recomendada)
|
||||
|
||||
Oferecer uma área de gerenciamento apoiada por serviço utilizável fora da UI.
|
||||
Copiar libs externas de diretórios locais para `.workspace/`; registrar os
|
||||
destinos físicos para o resolver existente. SDK/core permanecem bundled no
|
||||
Studio e não devem ser copiados para o projeto por necessidade editorial.
|
||||
Benefício: escopo compacto e reconstrução explícita. Custo: definir identidade,
|
||||
atualização e diagnóstico. Manutenção concentrada em um fluxo compartilhado.
|
||||
|
||||
### Option B — Preparação manual externa
|
||||
|
||||
Usuário copia arquivos e mantém o registry manualmente. Menor custo inicial,
|
||||
mas favorece divergências e não atende à necessidade de gerenciamento no produto.
|
||||
Pode servir como condição temporária para a AGD-0071, não como solução final.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Origens apenas locais reduzem complexidade, mas outra máquina precisa receber
|
||||
as bibliotecas antes da reconstrução. Cópias isolam o projeto de mudanças na
|
||||
origem e duplicam armazenamento. `.workspace/` permanece ignorada pelo Git;
|
||||
metadados de reconstrução não devem depender exclusivamente dela.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Planejar A como capacidade essencial do produto, sem data ou implementação
|
||||
autorizada nesta agenda. Começar por cópia local e atualização explícita.
|
||||
Download, registry remoto, resolução automática de versões e cache compartilhado
|
||||
ficam fora do recorte inicial; cache pode futuramente integrar essa mesma área.
|
||||
|
||||
## Discussion
|
||||
|
||||
Necessidade registrada explicitamente pelo usuário durante a AGD-0071. Não é
|
||||
um requisito opcional a descartar por funcionar a navegação sem UI de gestão.
|
||||
O desenho e a execução ainda precisam de discussão, decision e plan próprios.
|
||||
|
||||
Hoje `DependencyResolver` e `RegistryStore` resolvem diretórios existentes via
|
||||
path ou `.workspace/repos/registry.json`; não fazem instalação. SDK/core vêm
|
||||
de recursos do frontend. Preservar a distinção entre ambiente reservado e
|
||||
dependências comuns. O usuário escolheu documentos externos em memória
|
||||
read-only na AGD-0071, independentemente da origem bundled ou física.
|
||||
|
||||
Referência consolidada: [LSN-0078](../../lessons/DSC-0069-pbs-editorial-chains-sdk-navigation/LSN-0078-pbs-chains-and-revision-bound-external-sources.md),
|
||||
DSC-0069 concluída. A implementação consome fontes já disponíveis na origem e não entrega o gestor.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Retomar esta discussão ao planejar a capacidade de gerenciamento do Studio;
|
||||
fechar UX, metadados, reconstrução e lifecycle antes de emitir decision e plan.
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-000C"
|
||||
origin: "discussion-framework:studio:DSC-0072:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0072"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "8a9932e70dc0036cd8e900a1f404de95c478eb2f56ea57f34b22f47aa484989f"
|
||||
size: 467
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.686418Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0072","status":"open","ticket":"studio-dependency-management","title":"Studio: gerenciamento e reconstrução de dependências locais","created_at":"2026-10-06","updated_at":"2026-10-06","tags":["studio","dependencies"],"agendas":[{"id":"AGD-0074","file":"AGD-0074-studio-gerenciamento-e-reconstru-o-de-depend-ncias-locais.md","status":"open","created_at":"2026-10-06","updated_at":"2026-10-06"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-000C"
|
||||
origin: "ai-engineering:discussion-import:studio:DSC-0072"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "bc400014ff86ee46934476ffc3859682c8e04bd4db55dfdfe412ef439e3cadf8"
|
||||
size: 708
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.693349Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-000C",
|
||||
"sourceId" : "studio",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio",
|
||||
"dscId" : "DSC-0072",
|
||||
"targets" : [ "studio" ],
|
||||
"contentHash" : "34a804f6dcf20f3e208cbf965447822b08a68a87af9fa622db8956332f4a75df",
|
||||
"dscSha256" : "8a9932e70dc0036cd8e900a1f404de95c478eb2f56ea57f34b22f47aa484989f",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0074",
|
||||
"file" : "AGD-0074-studio-gerenciamento-e-reconstru-o-de-depend-ncias-locais.md",
|
||||
"sha256" : "ed981ce87b9e30bc5a757af088c4b928c2f91e559085c5fcb3e77f2038a01e9d",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+99
@@ -0,0 +1,99 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-000C"
|
||||
discussionId: "df:studio:AGD-0074"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:studio"
|
||||
createdAt: "2026-11-16T15:31:32.676859Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
id: AGD-0074
|
||||
ticket: studio-dependency-management
|
||||
title: "Studio: gerenciamento e reconstrução de dependências locais"
|
||||
status: open
|
||||
created: 2026-10-06
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, dependencies]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio`
|
||||
|
||||
Worker: Agenda Worker. Impactos: `compiler/general` (resolução de dependências)
|
||||
e `compiler/pbs` (fontes reservadas SDK/core).
|
||||
|
||||
Necessidade essencial do produto: preparar e reconstruir cópias físicas das dependências do projeto, com uma área de gerenciamento no Studio.
|
||||
|
||||
## Context
|
||||
|
||||
Desdobramento da AGD-0071 / DSC-0069; fora do escopo daquela agenda. SDK/core acompanham o Studio; dependências externas inicialmente já existem na máquina. Cópias em .workspace/ ignorada pelo Git; download e cache ficam para avaliação futura.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Qual área do Studio apresenta dependências, origens locais e estado das cópias?
|
||||
- [ ] Quais metadados versionados permitem reconstrução, e quais paths pertencem à máquina?
|
||||
- [ ] Como identificar conteúdo e detectar alterações? Lockfile e hashes são propostas a avaliar.
|
||||
- [ ] Como preparar dependências transitivas e diagnosticar origens ausentes?
|
||||
- [ ] Como atualizar cópias sem invalidar consultas e sessões em andamento?
|
||||
- [ ] Como lidar com SDK/core indisponíveis na distribuição instalada?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A — Preparação local integrada ao Studio (recomendada)
|
||||
|
||||
Oferecer uma área de gerenciamento apoiada por serviço utilizável fora da UI.
|
||||
Copiar libs externas de diretórios locais para `.workspace/`; registrar os
|
||||
destinos físicos para o resolver existente. SDK/core permanecem bundled no
|
||||
Studio e não devem ser copiados para o projeto por necessidade editorial.
|
||||
Benefício: escopo compacto e reconstrução explícita. Custo: definir identidade,
|
||||
atualização e diagnóstico. Manutenção concentrada em um fluxo compartilhado.
|
||||
|
||||
### Option B — Preparação manual externa
|
||||
|
||||
Usuário copia arquivos e mantém o registry manualmente. Menor custo inicial,
|
||||
mas favorece divergências e não atende à necessidade de gerenciamento no produto.
|
||||
Pode servir como condição temporária para a AGD-0071, não como solução final.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Origens apenas locais reduzem complexidade, mas outra máquina precisa receber
|
||||
as bibliotecas antes da reconstrução. Cópias isolam o projeto de mudanças na
|
||||
origem e duplicam armazenamento. `.workspace/` permanece ignorada pelo Git;
|
||||
metadados de reconstrução não devem depender exclusivamente dela.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Planejar A como capacidade essencial do produto, sem data ou implementação
|
||||
autorizada nesta agenda. Começar por cópia local e atualização explícita.
|
||||
Download, registry remoto, resolução automática de versões e cache compartilhado
|
||||
ficam fora do recorte inicial; cache pode futuramente integrar essa mesma área.
|
||||
|
||||
## Discussion
|
||||
|
||||
Necessidade registrada explicitamente pelo usuário durante a AGD-0071. Não é
|
||||
um requisito opcional a descartar por funcionar a navegação sem UI de gestão.
|
||||
O desenho e a execução ainda precisam de discussão, decision e plan próprios.
|
||||
|
||||
Hoje `DependencyResolver` e `RegistryStore` resolvem diretórios existentes via
|
||||
path ou `.workspace/repos/registry.json`; não fazem instalação. SDK/core vêm
|
||||
de recursos do frontend. Preservar a distinção entre ambiente reservado e
|
||||
dependências comuns. O usuário escolheu documentos externos em memória
|
||||
read-only na AGD-0071, independentemente da origem bundled ou física.
|
||||
|
||||
Referência consolidada: [LSN-0078](../../lessons/DSC-0069-pbs-editorial-chains-sdk-navigation/LSN-0078-pbs-chains-and-revision-bound-external-sources.md),
|
||||
DSC-0069 concluída. A implementação consome fontes já disponíveis na origem e não entrega o gestor.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
|
||||
## Next Step
|
||||
|
||||
Retomar esta discussão ao planejar a capacidade de gerenciamento do Studio;
|
||||
fechar UX, metadados, reconstrução e lifecycle antes de emitir decision e plan.
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0002"
|
||||
workId: "WRK-000C"
|
||||
discussionId: "main"
|
||||
kind: "NOTE"
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:45.736936Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
Autorização explícita do usuário nesta sessão: "sim, pontualemente para esse caso", em resposta à proposta de corrigir apenas as aspas do campo title da AGD-0074 e importar as 5 agendas abertas do Studio. Exceção pontual ao cadastro access.edit: false; nenhuma alteração geral de permissões autorizada. Correção aplicada: title: "Studio: gerenciamento e reconstrução de dependências locais". Importação executada pelo comando público aie import discussion com source studio=studio e fingerprint de preview validado.
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-000C"
|
||||
title: "studio: Studio: gerenciamento e reconstrução de dependências locais"
|
||||
description: "Imported Discussion Framework discussion DSC-0072 from studio (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio).\n\
|
||||
\nTargets:\n- studio"
|
||||
goal: "Studio: gerenciamento e reconstrução de dependências locais"
|
||||
motivation: "Continue the open agendas of studio/DSC-0072"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "OPEN"
|
||||
createdAt: "2026-11-16T15:31:32.675027Z"
|
||||
updatedAt: "2026-11-16T15:31:45.762260Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
- "DSC-0002"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events: []
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-000D"
|
||||
origin: "discussion-framework:studio:AGD-0073:AGD-0073-terminal-embutido-no-dev-do-studio.md"
|
||||
purpose: "Original DF agenda AGD-0073"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "d849ffc2e437ed56bd0deef941811df8a00789fdca63624ea38ad38e39b80501"
|
||||
size: 7730
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.721987Z"
|
||||
+102
@@ -0,0 +1,102 @@
|
||||
---
|
||||
id: AGD-0073
|
||||
ticket: studio-dev-embedded-terminal
|
||||
title: Terminal embutido no DEV do Studio
|
||||
status: open
|
||||
created: 2026-09-29
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, dev, terminal]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio`
|
||||
|
||||
O desenvolvedor precisa alternar entre Studio e um terminal externo para executar ferramentas e conversar com um agente de código. Um terminal embutido no DEV, iniciado na raiz do projeto, pode manter execução do agente, concessão de controle e observação do runtime no mesmo ambiente.
|
||||
|
||||
## Context
|
||||
|
||||
Owner: `studio`, subdomínio workspace DEV, apresentação e lifecycle de processos locais. Worker: Agenda Worker.
|
||||
|
||||
O usuário pediu uma agenda separada e aberta para explorar um terminal semelhante ao terminal embutido do IntelliJ. Esta discussão se relaciona à DSC-0070 (conexão MCP persistente), mas não condiciona sua entrega nem amplia implicitamente seu escopo.
|
||||
|
||||
Studio usa JavaFX, com API/Core independentes da UI e adaptadores de infraestrutura para processos externos. O terminal hospedaria o cliente externo do agente; o MCP continuaria sendo o canal para os serviços autorizados do Studio. A escolha de modelo, login e conversa continuaria pertencendo ao cliente externo.
|
||||
|
||||
Aplicações interativas precisam de emulação de terminal e PTY, incluindo cursor, sequências ANSI, redimensionamento e sinais. Apenas capturar stdout em uma área de texto não atende ao uso proposto. JediTerm/Pty4J são candidatos a avaliar; a integração Swing/JavaFX e o empacotamento por plataforma ainda não foram validados neste repositório.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Qual layout no DEV preserva a visibilidade de concessão/revogação e da observação do runtime: painel inferior, lateral ou aba?
|
||||
- [ ] Uma sessão por projeto atende à primeira entrega ou múltiplas abas são necessárias?
|
||||
- [ ] Quais SOs e arquiteturas entram no primeiro aceite?
|
||||
- [ ] Qual componente oferece compatibilidade suficiente com a interface interativa do Codex, teclado, Unicode, clipboard e redimensionamento?
|
||||
- [ ] Como selecionar shell e carregar PATH/ambiente quando Studio é iniciado pelo launcher gráfico?
|
||||
- [ ] Qual lifecycle ao sair do DEV, fechar o projeto e encerrar Studio? Recomenda-se preservar sessão ao trocar de workspace e explicitar encerramento de processos ao fechar projeto.
|
||||
- [ ] O primeiro fluxo apenas abre shell ou também oferece ação explícita para iniciar um cliente de agente instalado?
|
||||
- [ ] Como apresentar a independência entre terminal e controle MCP? Revogar autoridade do Studio não interrompe automaticamente shell ou escritas externas.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Componente de terminal JVM existente e PTY
|
||||
|
||||
- **Approach:** avaliar JediTerm/Pty4J, integrando apresentação ao JavaFX e mantendo supervisão de processos em infraestrutura.
|
||||
- **Pro:** reutiliza emulação e integração com processos locais existentes; evita implementar protocolo de terminal.
|
||||
- **Con:** exige validar interop Swing/JavaFX, foco, atalhos, renderização e bibliotecas nativas por plataforma.
|
||||
- **Maintainability:** acompanhar dependências, licenças e compatibilidade; manter contratos do Studio livres de tipos dessas bibliotecas.
|
||||
|
||||
### Option B - Terminal renderizado em WebView com PTY local
|
||||
|
||||
- **Approach:** avaliar um emulador de terminal web embutido, conectado por um adapter ao processo local.
|
||||
- **Pro:** alternativa de apresentação sem interop Swing; permite avaliar componentes web existentes.
|
||||
- **Con:** acrescenta engine web e bridge de eventos/bytes, com custo de foco, clipboard e distribuição; compatibilidade e enquadramento arquitetural precisam de avaliação explícita.
|
||||
- **Maintainability:** adiciona dependências e integração JVM/JavaScript. Não pressupõe autorização para servidor HTTP adicional ou substituição da UI JavaFX.
|
||||
|
||||
### Option C - Atalho para terminal externo na raiz do projeto
|
||||
|
||||
- **Approach:** Studio abre o terminal do sistema no diretório correto.
|
||||
- **Pro:** menor superfície de emulação e preserva preferências do usuário.
|
||||
- **Con:** mantém troca de janelas e não entrega o terminal embutido solicitado.
|
||||
- **Maintainability:** integração de lançamento específica por SO; alternativa de comparação ou fallback, não equivalente ao objetivo.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Reutilizar um componente reduz esforço inicial, mas não elimina validação de teclado, seleção, clipboard, fontes, escala e interfaces de tela inteira. Uma primeira versão útil parece de complexidade moderada; paridade com uma IDE madura é um escopo bem maior. Nenhum prazo está estabelecido sem validar integração e plataformas.
|
||||
|
||||
Manter sessões entre trocas de workspace favorece continuidade, mas exige separar lifecycle do processo e lifecycle do painel visual. Encerrar Studio pode interromper o agente hospedado e operações no shell; esse comportamento precisa ser claro e diferente de apenas revogar acesso aos serviços MCP.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Explorar a opção A primeiro, sem selecionar biblioteca definitivamente. Propor como primeiro escopo uma sessão por projeto dentro do DEV, shell configurável com padrão do sistema, cwd inicial na raiz do projeto, copiar/colar, scrollback limitado, redimensionamento, sinais e encerramento controlado.
|
||||
|
||||
Conservar o cliente do agente como programa externo hospedado no terminal, consumindo a integração MCP discutida na DSC-0070. Abrir o terminal não concede autoridade nem instala/inicia um agente sem ação explícita do usuário. Não ampliar a proposta para chat próprio, gestão de modelos ou credenciais de provedores.
|
||||
|
||||
## Discussion
|
||||
|
||||
### Evidências necessárias para uma futura decision
|
||||
|
||||
- Abrir shell na raiz correta, inclusive caminhos com espaços, e localizar executáveis no ambiente da aplicação empacotada.
|
||||
- Executar Codex interativamente e verificar foco, atalhos, Unicode, paste, scroll e resize sem corromper a tela.
|
||||
- Trocar de workspace e voltar sem perder a sessão, caso esse lifecycle seja aceito.
|
||||
- Definir tratamento de Ctrl+C, término do shell, processos filhos, fechamento de projeto e fechamento do Studio.
|
||||
- Validar independência de autoridade: terminal disponível não representa grant; revogação MCP não é encerramento de shell.
|
||||
- Verificar distribuição dos componentes nativos e cobertura por SO/arquitetura escolhidos.
|
||||
|
||||
### Referências e possíveis alvos de propagação
|
||||
|
||||
- DSC-0070 / [AGD-0072](../../lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md): configuração MCP do projeto, descoberta e conector oficial.
|
||||
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`: localização e comportamento visual.
|
||||
- `docs/specs/studio/9. Studio Core and Adapter Architecture Specification.md`: contratos neutros, adaptadores e lifecycle.
|
||||
- `docs/specs/studio/10. DEV and Automation Specification.md`: composição do DEV e separação de autoridade.
|
||||
- `docs/specs/studio/8. Project-Local Studio State Specification.md`: somente se houver configurações/restauração a definir; não presumir persistência de processos, conteúdo de terminal ou tarefas.
|
||||
- Candidatos técnicos: https://github.com/JetBrains/jediterm e https://github.com/JetBrains/pty4j, consultados na discussão inicial; seleção requer avaliação específica.
|
||||
|
||||
Os caminhos documentais refletem a árvore atual. Esta agenda não altera specs ou código.
|
||||
|
||||
## Resolution
|
||||
|
||||
Aberta a pedido do usuário. Nenhuma biblioteca, arquitetura final ou implementação foi aprovada.
|
||||
|
||||
## Next Step
|
||||
|
||||
Retomar quando o terminal for priorizado: fechar UX, lifecycle e plataformas, avaliar os candidatos e reunir evidências de compatibilidade. Depois convergir para uma decision própria, mantendo a DSC-0070 independente.
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-000D"
|
||||
origin: "discussion-framework:studio:DSC-0071:index-record"
|
||||
purpose: "Original DF discussion index record DSC-0071"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "716247ea458bc0f5bb3f230aecfd47d782b6455b7f24c9edee6095f7db1abe20"
|
||||
size: 418
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.729352Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0071","status":"open","ticket":"studio-dev-embedded-terminal","title":"Terminal embutido no DEV do Studio","created_at":"2026-09-29","updated_at":"2026-09-29","tags":["studio","dev","terminal"],"agendas":[{"id":"AGD-0073","file":"AGD-0073-terminal-embutido-no-dev-do-studio.md","status":"open","created_at":"2026-09-29","updated_at":"2026-09-29"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-000D"
|
||||
origin: "ai-engineering:discussion-import:studio:DSC-0071"
|
||||
purpose: "DF import identity and provenance"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "b49ec9cd6794a6cfd715c8104352c6c539c5279a3ef050cf8c1298ff1eeb272b"
|
||||
size: 685
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T15:31:32.736571Z"
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-000D",
|
||||
"sourceId" : "studio",
|
||||
"sourceRoot" : "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio",
|
||||
"dscId" : "DSC-0071",
|
||||
"targets" : [ "studio" ],
|
||||
"contentHash" : "c01fc418c3025f43a3590c50b9ecd964dce9f2c17c34c4e5a86df13aba88431c",
|
||||
"dscSha256" : "716247ea458bc0f5bb3f230aecfd47d782b6455b7f24c9edee6095f7db1abe20",
|
||||
"dscArtifactId" : "ART-0002",
|
||||
"agendas" : [ {
|
||||
"id" : "AGD-0073",
|
||||
"file" : "AGD-0073-terminal-embutido-no-dev-do-studio.md",
|
||||
"sha256" : "d849ffc2e437ed56bd0deef941811df8a00789fdca63624ea38ad38e39b80501",
|
||||
"discussionId" : "DSC-0001",
|
||||
"artifactId" : "ART-0001"
|
||||
} ]
|
||||
}
|
||||
+114
@@ -0,0 +1,114 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-000D"
|
||||
discussionId: "df:studio:AGD-0073"
|
||||
kind: "NOTE"
|
||||
author: "discussion-import:studio"
|
||||
createdAt: "2026-11-16T15:31:32.718984Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
---
|
||||
id: AGD-0073
|
||||
ticket: studio-dev-embedded-terminal
|
||||
title: Terminal embutido no DEV do Studio
|
||||
status: open
|
||||
created: 2026-09-29
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, dev, terminal]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
Domain owner: `studio`
|
||||
|
||||
O desenvolvedor precisa alternar entre Studio e um terminal externo para executar ferramentas e conversar com um agente de código. Um terminal embutido no DEV, iniciado na raiz do projeto, pode manter execução do agente, concessão de controle e observação do runtime no mesmo ambiente.
|
||||
|
||||
## Context
|
||||
|
||||
Owner: `studio`, subdomínio workspace DEV, apresentação e lifecycle de processos locais. Worker: Agenda Worker.
|
||||
|
||||
O usuário pediu uma agenda separada e aberta para explorar um terminal semelhante ao terminal embutido do IntelliJ. Esta discussão se relaciona à DSC-0070 (conexão MCP persistente), mas não condiciona sua entrega nem amplia implicitamente seu escopo.
|
||||
|
||||
Studio usa JavaFX, com API/Core independentes da UI e adaptadores de infraestrutura para processos externos. O terminal hospedaria o cliente externo do agente; o MCP continuaria sendo o canal para os serviços autorizados do Studio. A escolha de modelo, login e conversa continuaria pertencendo ao cliente externo.
|
||||
|
||||
Aplicações interativas precisam de emulação de terminal e PTY, incluindo cursor, sequências ANSI, redimensionamento e sinais. Apenas capturar stdout em uma área de texto não atende ao uso proposto. JediTerm/Pty4J são candidatos a avaliar; a integração Swing/JavaFX e o empacotamento por plataforma ainda não foram validados neste repositório.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Qual layout no DEV preserva a visibilidade de concessão/revogação e da observação do runtime: painel inferior, lateral ou aba?
|
||||
- [ ] Uma sessão por projeto atende à primeira entrega ou múltiplas abas são necessárias?
|
||||
- [ ] Quais SOs e arquiteturas entram no primeiro aceite?
|
||||
- [ ] Qual componente oferece compatibilidade suficiente com a interface interativa do Codex, teclado, Unicode, clipboard e redimensionamento?
|
||||
- [ ] Como selecionar shell e carregar PATH/ambiente quando Studio é iniciado pelo launcher gráfico?
|
||||
- [ ] Qual lifecycle ao sair do DEV, fechar o projeto e encerrar Studio? Recomenda-se preservar sessão ao trocar de workspace e explicitar encerramento de processos ao fechar projeto.
|
||||
- [ ] O primeiro fluxo apenas abre shell ou também oferece ação explícita para iniciar um cliente de agente instalado?
|
||||
- [ ] Como apresentar a independência entre terminal e controle MCP? Revogar autoridade do Studio não interrompe automaticamente shell ou escritas externas.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Componente de terminal JVM existente e PTY
|
||||
|
||||
- **Approach:** avaliar JediTerm/Pty4J, integrando apresentação ao JavaFX e mantendo supervisão de processos em infraestrutura.
|
||||
- **Pro:** reutiliza emulação e integração com processos locais existentes; evita implementar protocolo de terminal.
|
||||
- **Con:** exige validar interop Swing/JavaFX, foco, atalhos, renderização e bibliotecas nativas por plataforma.
|
||||
- **Maintainability:** acompanhar dependências, licenças e compatibilidade; manter contratos do Studio livres de tipos dessas bibliotecas.
|
||||
|
||||
### Option B - Terminal renderizado em WebView com PTY local
|
||||
|
||||
- **Approach:** avaliar um emulador de terminal web embutido, conectado por um adapter ao processo local.
|
||||
- **Pro:** alternativa de apresentação sem interop Swing; permite avaliar componentes web existentes.
|
||||
- **Con:** acrescenta engine web e bridge de eventos/bytes, com custo de foco, clipboard e distribuição; compatibilidade e enquadramento arquitetural precisam de avaliação explícita.
|
||||
- **Maintainability:** adiciona dependências e integração JVM/JavaScript. Não pressupõe autorização para servidor HTTP adicional ou substituição da UI JavaFX.
|
||||
|
||||
### Option C - Atalho para terminal externo na raiz do projeto
|
||||
|
||||
- **Approach:** Studio abre o terminal do sistema no diretório correto.
|
||||
- **Pro:** menor superfície de emulação e preserva preferências do usuário.
|
||||
- **Con:** mantém troca de janelas e não entrega o terminal embutido solicitado.
|
||||
- **Maintainability:** integração de lançamento específica por SO; alternativa de comparação ou fallback, não equivalente ao objetivo.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
Reutilizar um componente reduz esforço inicial, mas não elimina validação de teclado, seleção, clipboard, fontes, escala e interfaces de tela inteira. Uma primeira versão útil parece de complexidade moderada; paridade com uma IDE madura é um escopo bem maior. Nenhum prazo está estabelecido sem validar integração e plataformas.
|
||||
|
||||
Manter sessões entre trocas de workspace favorece continuidade, mas exige separar lifecycle do processo e lifecycle do painel visual. Encerrar Studio pode interromper o agente hospedado e operações no shell; esse comportamento precisa ser claro e diferente de apenas revogar acesso aos serviços MCP.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Explorar a opção A primeiro, sem selecionar biblioteca definitivamente. Propor como primeiro escopo uma sessão por projeto dentro do DEV, shell configurável com padrão do sistema, cwd inicial na raiz do projeto, copiar/colar, scrollback limitado, redimensionamento, sinais e encerramento controlado.
|
||||
|
||||
Conservar o cliente do agente como programa externo hospedado no terminal, consumindo a integração MCP discutida na DSC-0070. Abrir o terminal não concede autoridade nem instala/inicia um agente sem ação explícita do usuário. Não ampliar a proposta para chat próprio, gestão de modelos ou credenciais de provedores.
|
||||
|
||||
## Discussion
|
||||
|
||||
### Evidências necessárias para uma futura decision
|
||||
|
||||
- Abrir shell na raiz correta, inclusive caminhos com espaços, e localizar executáveis no ambiente da aplicação empacotada.
|
||||
- Executar Codex interativamente e verificar foco, atalhos, Unicode, paste, scroll e resize sem corromper a tela.
|
||||
- Trocar de workspace e voltar sem perder a sessão, caso esse lifecycle seja aceito.
|
||||
- Definir tratamento de Ctrl+C, término do shell, processos filhos, fechamento de projeto e fechamento do Studio.
|
||||
- Validar independência de autoridade: terminal disponível não representa grant; revogação MCP não é encerramento de shell.
|
||||
- Verificar distribuição dos componentes nativos e cobertura por SO/arquitetura escolhidos.
|
||||
|
||||
### Referências e possíveis alvos de propagação
|
||||
|
||||
- DSC-0070 / [AGD-0072](../../lessons/DSC-0070-studio-persistent-mcp-connector/LSN-0077-integrated-mcp-stable-setup-and-ephemeral-access.md): configuração MCP do projeto, descoberta e conector oficial.
|
||||
- `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md`: localização e comportamento visual.
|
||||
- `docs/specs/studio/9. Studio Core and Adapter Architecture Specification.md`: contratos neutros, adaptadores e lifecycle.
|
||||
- `docs/specs/studio/10. DEV and Automation Specification.md`: composição do DEV e separação de autoridade.
|
||||
- `docs/specs/studio/8. Project-Local Studio State Specification.md`: somente se houver configurações/restauração a definir; não presumir persistência de processos, conteúdo de terminal ou tarefas.
|
||||
- Candidatos técnicos: https://github.com/JetBrains/jediterm e https://github.com/JetBrains/pty4j, consultados na discussão inicial; seleção requer avaliação específica.
|
||||
|
||||
Os caminhos documentais refletem a árvore atual. Esta agenda não altera specs ou código.
|
||||
|
||||
## Resolution
|
||||
|
||||
Aberta a pedido do usuário. Nenhuma biblioteca, arquitetura final ou implementação foi aprovada.
|
||||
|
||||
## Next Step
|
||||
|
||||
Retomar quando o terminal for priorizado: fechar UX, lifecycle e plataformas, avaliar os candidatos e reunir evidências de compatibilidade. Depois convergir para uma decision própria, mantendo a DSC-0070 independente.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-000D"
|
||||
title: "studio: Terminal embutido no DEV do Studio"
|
||||
description: "Imported Discussion Framework discussion DSC-0071 from studio (/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio).\n\
|
||||
\nTargets:\n- studio"
|
||||
goal: "Terminal embutido no DEV do Studio"
|
||||
motivation: "Continue the open agendas of studio/DSC-0071"
|
||||
constraints: []
|
||||
acceptanceCriteria: []
|
||||
status: "OPEN"
|
||||
createdAt: "2026-11-16T15:31:32.717336Z"
|
||||
updatedAt: "2026-11-16T15:31:32.742237Z"
|
||||
author: "codex"
|
||||
repositories: []
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
- "ART-0003"
|
||||
plans: []
|
||||
completions: []
|
||||
events: []
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-000E"
|
||||
origin: "work-consolidation:WRK-0003:runtime:DSC-0069:AGD-0072:ART-0001"
|
||||
purpose: "Agenda original integral de runtime:DSC-0069:AGD-0072, preservado de WRK-0003"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "09732c4c27069ae9f77ddc47d3a8478318d2ca2d07dafd5c5ed306c237ab28ad"
|
||||
size: 18812
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T16:02:56.668472Z"
|
||||
+178
@@ -0,0 +1,178 @@
|
||||
---
|
||||
id: AGD-0072
|
||||
ticket: blitz3d-engineering-lessons
|
||||
title: Licoes de engenharia do Blitz3D para o Prometeu
|
||||
status: open
|
||||
created: 2026-11-04
|
||||
resolved:
|
||||
decision:
|
||||
tags: [architecture, runtime, tooling, research]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
**Worker:** Agenda Worker. **Dominio owner:** `runtime`, pesquisa comparativa de mecanismos internos da maquina, fronteiras de execucao e provider de metadata.
|
||||
|
||||
O usuario pediu uma analise do Blitz3D e esclareceu o objetivo: extrair licoes de engenharia de um engine experiente. Em 2026-11-04, solicitou separar runtime e Studio. Esta agenda conserva as ideias pertinentes ao runtime; autoria, core/SDK e ferramentas foram transferidos para [DSC-0100 / AGD-0102 no Studio](../../../../studio/discussion/workflow/agendas/AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md).
|
||||
|
||||
Base examinada:
|
||||
|
||||
- Blitz3D: commit [`f132a78c9f2da255905bf477cb845994324b865a`](https://github.com/blitz-research/blitz3d_soloud/commit/f132a78c9f2da255905bf477cb845994324b865a), datado de 2024-10-19, resolvido a partir de `main` na consulta de 2026-11-04.
|
||||
- Prometeu runtime: checkout `a4bec5bc4577850543f57c79f5124ca00169e1b3`, specs de GFX, audio, Registry/PBX, tempo, assets, portabilidade e debugging; composer/cache, audio desktop e catalogos nativos.
|
||||
- Metodo: leitura estatica de fontes, exemplos e build metadata. O Blitz3D nao foi compilado ou executado; nao foram medidos desempenho ou qualidade perceptual.
|
||||
|
||||
O runtime ja possui separacao entre producao logica e render, publicacao de comandos de audio, recursos com identidade/geracao e catalogos nativos. A comparacao procura mecanismos uteis para pensar essas responsabilidades e contraexemplos para verificar suas fronteiras. Nao parte da premissa de que exista uma falha equivalente no Prometeu.
|
||||
|
||||
## Problema
|
||||
|
||||
Quais escolhas do Blitz3D ajudam a avaliar validade de caches, compartilhamento de recursos, publicacao, isolamento entre fases, limites de trabalho e seguranca do runtime?
|
||||
|
||||
A avaliacao separa fato observado, licao inferida, aplicabilidade local e limite da evidencia. Conveniencias de linguagem, assinatura apresentada ao autor e bibliotecas de gameplay sao responsabilidades da agenda de Studio.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
### 1. Um cache precisa declarar de que mudanca depende
|
||||
|
||||
**Fato:** [`Surface::Monitor`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/surface.h) distingue alteracoes geometricas e de material. [`MeshModel::Rep`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/meshmodel.cpp) compara `geom_changes` com `box_valid`, `coll_valid` e `norms_valid`, reconstruindo bounding box, collider ou normais quando necessario. [`Entity`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/entity.cpp) invalida transforms descendentes e recompõe o resultado sob demanda.
|
||||
|
||||
**Licao:** a parte decisiva do cache e seu protocolo de validade: dependencias, evento invalidante e momento de reconstrucao. Contadores separados evitam tratar toda alteracao como mudanca de tudo.
|
||||
|
||||
**Aplicabilidade:** comparar esse modelo com `SceneViewportCache`, `SceneViewportResolver`, recursos de glyph/paleta e seus consumidores. O Prometeu ja atualiza linhas, colunas e regioes; a investigacao util e procurar invalidacao excessiva ou dependencias esquecidas em troca/reload de banco. E uma hipotese de revisao, nao um defeito demonstrado.
|
||||
|
||||
**Limite:** lazy rebuild pode concentrar trabalho no primeiro uso. Na fronteira assincrona Prometeu, ele precisa ocorrer no owner correto e nao pode exigir acesso mutavel do render ao estado vivo da VM. Em [`Surface::getMesh`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/surface.cpp), apesar dos marcadores de validade, o caminho ativo zera ambos antes do upload quando detecta trabalho. A existencia de dirty flags nao prova atualizacao parcial efetiva.
|
||||
|
||||
### 2. Dado compartilhado e configuracao da instancia merecem vidas distintas
|
||||
|
||||
**Fato:** [`CachedTexture`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/cachedtexture.cpp) compartilha frames por uma chave que considera arquivo, flags, dimensoes e recorte de animacao. [`Brush::write`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/brush.cpp) separa a representacao compartilhada quando uma copia precisa ser modificada.
|
||||
|
||||
**Licao:** copias baratas precisam de semantica de alias explicita. Compartilhar o payload e diferente de compartilhar toda configuracao mutavel. Uma chave de cache deve incluir os parametros que alteram o resultado.
|
||||
|
||||
**Aplicabilidade:** manter clara a distincao entre identidade do asset, residencia do banco, payload retido e parametros de cada uso. O modelo de samples imutaveis e owners retidos do Prometeu ja aplica parte dessa separacao. Copy-on-write e uma ferramenta possivel para descritores internos; nao e uma mudanca proposta para a semantica de objetos guest.
|
||||
|
||||
**Limite:** busca por path e refcount manual sao detalhes historicos, nao metas. Identidade por `asset_id`/geracao e as regras publicadas de unload devem continuar sendo avaliadas pelo contrato Prometeu. Compartilhamento tambem pode reter memoria e mover custo para a primeira escrita.
|
||||
|
||||
### 3. Atualizacao e apresentacao sao fases diferentes, mas a separacao deve ser real
|
||||
|
||||
**Fato:** [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) oferece `update`, `capture` e `render(tween)`. [`Object::capture` e `beginRender`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/object.cpp) preservam posicao/escala/rotacao e calculam transforms interpolados separados, usando interpolacao linear e quaternion slerp.
|
||||
|
||||
**Licao:** o estado simulado pode ser autoritativo enquanto a apresentacao usa um estado derivado. Isso ajuda a raciocinar sobre velocidades de simulacao e apresentacao diferentes.
|
||||
|
||||
**Aplicabilidade:** reforca o frame logico de 60 Hz, os snapshots fechados e a apresentacao host-owned do Prometeu. Interpolacao visual seria uma escolha adicional, dependente de necessidade real e de contrato proprio; o exemplo nao demonstra que ela seja necessaria ao pixel art atual.
|
||||
|
||||
**Contraponto concreto:** `Object::beginRender` chama `updateSounds`; `World::render` atualiza listeners, e [`Listener::renderListener`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/listener.cpp) envia estado espacial ao audio. Parte do audio espacial depende, portanto, da chamada de render e da enumeracao de objetos visiveis. O aprendizado para o Prometeu e verificar que render descartado, pausa de apresentacao ou execucao headless nao governem trabalho de simulacao/audio por acidente. Nao se afirma que um defeito equivalente exista aqui.
|
||||
|
||||
### 4. Configure a reproducao antes de torna-la observavel
|
||||
|
||||
**Fato:** em [`bbaudio_soloud.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime/bbaudio_soloud.cpp), `Sound` representa material/defaults e `channel` identifica uma reproducao. Quando existe pitch customizado, `bbPlaySound` inicia a voz pausada, ajusta o sample rate e so depois libera a reproducao. Musica usa `WavStream`, enquanto efeitos usam `Wav`.
|
||||
|
||||
**Licao:** preparar uma operacao e publica-la sao momentos distintos. Evitar observacao de estado parcialmente configurado pode ser mais importante que a simplicidade de cada setter. A separacao entre material e reproducao tambem deixa claras as responsabilidades dos controles.
|
||||
|
||||
**Aplicabilidade:** o `play` Prometeu ja fornece todos os parametros e o mixer consome comandos publicados. O padrao do Blitz reforca essa escolha. Streaming ensina que musica longa possui outro perfil de residencia e I/O; a necessidade concreta deve preceder qualquer proposta de novo servico.
|
||||
|
||||
**Limite:** o adapter do Blitz nao estabelece as garantias de callback, backpressure, pausas por sessao e reclamacao fora do callback presentes no contrato Prometeu. O simples uso de SoLoud nao resolve essas responsabilidades. Defaults mutaveis de `Sound` tambem diferem dos samples imutaveis atuais.
|
||||
|
||||
### 5. Limites de trabalho e fallback fazem parte de um algoritmo
|
||||
|
||||
**Fato:** o solver de [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) limita tentativas com `MAX_HITS=10` e restaura a posicao inicial ao atingir o limite. [`MeshCollider`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/meshcollider.cpp) descarta candidatos por uma hierarquia de AABBs antes de testar triangulos. A hierarquia e interna a cada mesh; as listas de objetos por tipo nao constituem um broad phase espacial global.
|
||||
|
||||
**Licao:** limitar trabalho, definir comportamento de esgotamento e distinguir filtragem barata de trabalho detalhado sao responsabilidades explicitas do algoritmo. A presenca de uma aceleracao local nao demonstra que o custo do sistema inteiro esteja limitado.
|
||||
|
||||
**Aplicabilidade:** usar esse exemplo como criterio de revisao dos mecanismos nativos que ja possuem quotas e limites: verificar a unidade de trabalho, onde o custo aparece, o estado preservado em recusa e a ausencia de efeitos parciais indevidos. Um algoritmo nativo novo precisaria definir esses aspectos antes de ser proposto como contrato de maquina.
|
||||
|
||||
**Limite e transferencia:** overlap/sweep 2D, movimento contra tilemap e respostas de gameplay passam para a pesquisa de core/SDK no Studio. Esta agenda nao propoe periferico de colisao, syscall, fisica ou 3D. Os limites e epsilons do Blitz nao sao valores recomendados para o Prometeu.
|
||||
|
||||
### 6. Metadata do provider precisa de autoridade e representacao explicitas
|
||||
|
||||
**Fato:** o Blitz registra interfaces em `rtSym` e as expoe por [`Runtime::nextSym`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime_dll/bbruntime_dll.cpp). O Prometeu ja oferece [`syscalls::catalogue()`](../../../crates/console/prometeu-hal/src/syscalls.rs), `intrinsic_catalog()` e [exportacao de catalogos](../../../crates/console/prometeu-vm/src/catalog.rs).
|
||||
|
||||
**Licao:** metadata com owner conhecido torna observavel o contrato que um consumer pretende usar. Identidade, ABI, custos e efeitos precisam permanecer coerentes com execucao e validacao; representacao compartilhavel nao significa compartilhar ponteiros ou layouts nativos.
|
||||
|
||||
**Aplicabilidade:** manter a distincao entre catalogo de intrinsics, catalogo de syscalls e Registry por imagem. Qualquer investigacao deve verificar a fidelidade do provider e suas evidencias de exportacao, sem presumir que catalogos distintos tenham os mesmos campos ou finalidade.
|
||||
|
||||
**Limite e transferencia:** porte do catalogo para Java, declaracoes SDK, nomes de parametros PBS, hover, completion, signature help e documentacao da API pertencem ao Studio. A pesquisa de coerencia desses consumidores foi transferida integralmente; nao e obrigacao de implementacao desta agenda. Nenhuma mudanca de formato de catalogo e proposta aqui.
|
||||
|
||||
### 7. Validacao da maquina e independente da experiencia de debug
|
||||
|
||||
**Fato:** verificacoes de existencia de banco e limites em [`bbbank.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/bbruntime/bbbank.cpp) sao condicionadas a `debug`. O debugger Blitz tambem acessa declaracoes e estruturas do compilador por ponteiros.
|
||||
|
||||
**Licao:** informacao adicional de debug e validacao obrigatoria sao responsabilidades diferentes. A maquina precisa conservar suas regras de seguranca em todos os modos; representacoes consumidas fora do owner devem ter um contrato proprio.
|
||||
|
||||
**Aplicabilidade:** usar esse contraponto para avaliar loader/verifier, handles, limites e interpretacao de metadata/faults existentes, preservando o resultado logico entre modos. O runtime recebe metadados PBX e fornece contexto de execucao e faults pelos contratos publicados; isso nao o torna owner da sintaxe de origem ou da UI.
|
||||
|
||||
**Limite e transferencia:** emissao de nomes/spans pelo compilador e apresentacao de diagnosticos ao autor pertencem ao Studio. A agenda de Studio conserva os exemplos de `StmtNode::debug` e `debugtree.cpp`. Nenhuma perda de origem ou divergencia de validacao foi demonstrada no Prometeu por esta pesquisa.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Aprofundar caches e ownership a partir de um workload
|
||||
|
||||
- **Abordagem:** seguir invalidacao, retencao e reconstrucao no composer/asset/audio atual, motivado por uma carga ou erro observavel.
|
||||
- **Pro:** compara mecanismos concretos disponiveis neste repositorio.
|
||||
- **Contra:** pode nao encontrar problema; precisa medir antes de recomendar otimizacao.
|
||||
- **Tradeoff:** melhor ponto de partida para investigacao interna com alvo delimitado.
|
||||
|
||||
### Opcao B - Examinar fronteiras e publicacao em cenarios adversos
|
||||
|
||||
- **Abordagem:** usar render descartado, pausa, headless e esgotamento de trabalho para revisar independencia entre fases e efeitos de comandos.
|
||||
- **Pro:** aproveita os contraexemplos concretos do Blitz e os contratos ja publicados.
|
||||
- **Contra:** uma revisao ampla pode repetir evidencia existente sem acrescentar informacao.
|
||||
- **Tradeoff:** escolher somente um cenario com duvida concreta, preservando quotas, ordering e ownership vigentes.
|
||||
|
||||
### Opcao C - Reter a pesquisa como referencia para necessidades futuras
|
||||
|
||||
- **Abordagem:** manter mecanismos e limites documentados, retomando quando houver proposta ou problema correspondente.
|
||||
- **Pro:** evita inventar trabalho sem evidencia de necessidade.
|
||||
- **Contra:** nao produz uma nova medicao ou revisao interna agora.
|
||||
- **Tradeoff:** adequada enquanto os achados apenas corroborarem o desenho atual.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Manter **C** como estado desta pesquisa. Se surgir problema observavel de custo/retencao, priorizar **A**. Se a duvida for acoplamento ou ordem entre fases, selecionar um cenario de **B**.
|
||||
|
||||
Os aprendizados mais diretamente transferiveis ao runtime sao protocolos de validade de cache, separacao entre payload e uso, preparacao antes da publicacao e limites com fallback explicito. As fronteiras fechadas de render e audio do Prometeu ja respondem a parte dos riscos observados no Blitz. Nao ha evidencia, nesta analise, que justifique substitui-las.
|
||||
|
||||
## Transferencia e Fronteiras de Responsabilidade
|
||||
|
||||
Separacao solicitada pelo usuario em 2026-11-04. Destino de autoria/ferramentas: [DSC-0100 / AGD-0102](../../../../studio/discussion/workflow/agendas/AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md). Os IDs pertencem a indices independentes por repositorio.
|
||||
|
||||
| Tema da pesquisa original | Permanece no runtime | Responsabilidade transferida ao Studio |
|
||||
| --- | --- | --- |
|
||||
| API por tarefa completa | Somente respeito aos contratos de maquina consumidos | Ergonomia de linguagem/core/SDK, imports e percurso de autoria. |
|
||||
| Metadata ate a IDE | Autoridade, representacao e fidelidade dos catalogos do provider | Porte/importacao, projecoes semanticas, ajuda e documentacao da API. |
|
||||
| Caches e invalidacao | Protocolos de validade, dependencia e reconstrucao interna | Nenhuma investigacao interna de cache transferida. |
|
||||
| Recursos compartilhados | Identidade, residencia, owners e parametros por uso | Eventuais abstracoes de instancia de core/SDK, quando houver caso de uso. |
|
||||
| Atualizacao e apresentacao | Fases, snapshots, clocks e independencia do audio/render | Conveniencias de atualizacao/desenho de gameplay, respeitando suas discussoes locais. |
|
||||
| Preparar audio antes de publicar | Comandos completos, publicacao, callback e reclamacao | Nenhuma entrega de audio SDK criada ou reativada. |
|
||||
| Colisao e trabalho limitado | Principio de limite/fallback e custo das consultas | Hipoteses de helpers geometricos e respostas de gameplay em biblioteca. |
|
||||
| Exemplos pequenos | Fornecimento dos contratos/host de execucao existentes | Ensino, corpus de autoria e encaminhamento de qualificacao instalada ao owner existente. |
|
||||
| Debugging e origem | Validacao da maquina, leitura de metadata e faults | Emissao de origem pelo compilador e experiencia de diagnostico do autor. |
|
||||
|
||||
As perguntas e sugestoes de evidencia transferidas estao detalhadas na agenda de destino. A transferencia nao equivale a implementacao, validacao ou aceite tecnico. A agenda de runtime nao depende do fechamento de nenhuma agenda do Studio.
|
||||
|
||||
Escolha de host/backend continua com [DSC-0047 / AGD-0050](AGD-0050-portable-host-backend-strategy.md). Background service/media continua com [DSC-0045 / AGD-0048](AGD-0048-background-service-audio-execution.md). Esta pesquisa nao adiciona obrigacoes a essas discussoes.
|
||||
|
||||
Os achados continuam em agenda de pesquisa; nao sao publicados como `discussion/lessons/`, pois nao derivam de nova decisao executada no Prometeu.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] Existe workload ou erro observavel que justifique investigar invalidacao/reconstrucao de cache ou retencao de owners?
|
||||
- [ ] Qual dependencia interna especifica merece revisao, e qual estado publicado permitiria demonstra-la?
|
||||
- [ ] Ha cenario de render descartado, pausa ou headless cuja independencia de audio/simulacao ainda precise de evidencia?
|
||||
- [ ] Algum mecanismo nativo tem limite de trabalho ou fallback ainda insuficientemente demonstrado?
|
||||
- [ ] Ha inconsistencia concreta entre metadata exportada pelo provider e seu comportamento, sem confundir isso com a adaptacao feita pelos consumers?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
A pesquisa comparativa esta entregue com fontes, aplicabilidade e limites. A separacao organizacional esta concluida quando a agenda Studio preservar os itens recebidos, os links cruzados resolverem e os dois workflows validarem.
|
||||
|
||||
Para uma futura decisao de mudanca no runtime, selecionar um problema concreto de sua responsabilidade, confirmar evidencia e fechar alternativas/comportamento. A pesquisa nao cria um plano de implementacao nem uma exigencia de alterar mecanismos que ja cumprem seu contrato.
|
||||
|
||||
## Proximo Passo Sugerido
|
||||
|
||||
Retomar o achado correspondente quando houver workload, defeito ou proposta concreta de runtime. Autoria e ferramentas prosseguem na agenda Studio, com escopo independente.
|
||||
|
||||
## Validacao da Pesquisa
|
||||
|
||||
- Leitura estatica em commit fixo; fontes originais preservadas entre as duas agendas.
|
||||
- Implementacoes existentes de catalogos, snapshots, caches e staging reconhecidas explicitamente.
|
||||
- Sem benchmarks, teste de execucao ou avaliacao perceptual do Blitz.
|
||||
- Separacao editorial de agendas; nenhuma alteracao em specs ou implementacao e nenhum item transferido marcado como executado.
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-000E"
|
||||
origin: "work-consolidation:WRK-0003:runtime:DSC-0069:AGD-0072:ART-0002"
|
||||
purpose: "Registro original do índice DF de runtime:DSC-0069:AGD-0072, preservado\
|
||||
\ de WRK-0003"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "adf9e90ed4893ead68f02e174d1afd999e11943d513794ee3d5a7e2e474a517e"
|
||||
size: 463
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T16:02:57.072991Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0069","status":"open","ticket":"blitz3d-engineering-lessons","title":"Licoes de engenharia do Blitz3D para o Prometeu","created_at":"2026-11-04","updated_at":"2026-11-04","tags":["architecture","runtime","tooling","research"],"agendas":[{"id":"AGD-0072","file":"AGD-0072-licoes-de-engenharia-do-blitz3d-para-o-prometeu.md","status":"open","created_at":"2026-11-04","updated_at":"2026-11-04"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0003"
|
||||
workId: "WRK-000E"
|
||||
origin: "work-consolidation:WRK-0009:studio:DSC-0100:AGD-0102:ART-0001"
|
||||
purpose: "Agenda original integral de studio:DSC-0100:AGD-0102, preservado de WRK-0009"
|
||||
path: "artifacts/evidence/ART-0003/payload"
|
||||
sha256: "48ae15be84dac874e1d70cf56bf85b11c941dc94c696e75ffc5984095cf88e6a"
|
||||
size: 14981
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T16:02:57.899763Z"
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
---
|
||||
id: AGD-0102
|
||||
ticket: blitz3d-studio-engineering-lessons
|
||||
title: Licoes do Blitz3D para autoria e ferramentas
|
||||
status: open
|
||||
created: 2026-11-04
|
||||
resolved:
|
||||
decision:
|
||||
tags: [studio, compiler, pbs, sdk, research]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
**Worker:** Agenda Worker. **Dominio owner:** `studio`, pesquisa de experiencia de autoria. **Interfaces:** `compiler/general` para metadata, emissao e diagnosticos comuns; `compiler/pbs` para linguagem, core/SDK e projecoes editoriais.
|
||||
|
||||
O usuario solicitou separar as licoes do Blitz3D entre runtime e Studio em 2026-11-04. Esta agenda recebe o conteudo de autoria/ferramentas da [agenda do runtime AGD-0072 / DSC-0069](../../../../runtime/discussion/workflow/agendas/AGD-0072-licoes-de-engenharia-do-blitz3d-para-o-prometeu.md). O objetivo e aprendizado de engenharia a partir de codigo existente.
|
||||
|
||||
Base da pesquisa: [`blitz-research/blitz3d_soloud`, commit `f132a78c9f2da255905bf477cb845994324b865a`](https://github.com/blitz-research/blitz3d_soloud/commit/f132a78c9f2da255905bf477cb845994324b865a), datado de 2024-10-19. Analise estatica; o engine nao foi compilado ou executado. Contexto local consultado: checkout Studio `1d8b8c21014b5b2e94bcd6621dbea177afc0d4eb`, specs de PBS, catalogos, atribuicao de debug e agendas ativas. Nenhuma implementacao foi auditada integralmente ou qualificada nesta transferencia.
|
||||
|
||||
O runtime conserva caches, ownership de recursos, fases de execucao/render/audio, publicacao de comandos, limites de trabalho e validacao da maquina. Esta agenda concentra a experiencia de quem escreve, compila, compreende e executa jogos pelo Studio.
|
||||
|
||||
## Problema
|
||||
|
||||
Como aproveitar a experiencia do Blitz3D para tornar tarefas comuns de jogo compreensiveis e concisas, mantendo coerencia entre SDK, compilador, ajuda editorial e resultado executado?
|
||||
|
||||
O Studio ja possui catalogos versionados, metadata semantica para parametros, signature help, exemplos instalados e discussoes proprias de sprites/animação, composicao e qualificacao de jogo. A comparacao precisa identificar ganhos concretos sobre essa base. A existencia de um padrao interessante no Blitz nao demonstra uma lacuna no Studio.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
### 1. Ergonomia de uma tarefa completa
|
||||
|
||||
**Fato:** os tutoriais de [movimento](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/BLITZ3D_INSTALL/tutorials/GCUK_Tuts/movement.bb) e [colisao](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/BLITZ3D_INSTALL/tutorials/GCUK_Tuts/collision.bb) conectam criacao, configuracao, input/movimento, atualizacao, desenho e consulta de contato em programas curtos.
|
||||
|
||||
**Licao:** avaliar a superficie publica pela tarefa que o autor consegue concluir, incluindo imports, recursos, inicializacao, parametros e erros. A quantidade de primitivas disponiveis nao mede esse percurso.
|
||||
|
||||
**Aplicabilidade:** comparar pequenos exemplos PBS de mover personagem, consultar representacao visual, avancar animacao, emitir desenho e persistir estado. Usar os principios ja publicados na [Language Charter](../../../docs/specs/compiler-languages/pbs/1.%20Language%20Charter.md). Identificar precisamente se eventual atrito pertence a linguagem, core, SDK, projeto ou UI.
|
||||
|
||||
**Limite:** simplicidade no chamador nao autoriza novo syscall, estado oculto ou alteracao do modelo de ciclos. A separacao entre avancar animacao e emitir desenho deve respeitar as discussoes locais existentes.
|
||||
|
||||
### 2. Coerencia entre assinatura aceita e ajuda exibida
|
||||
|
||||
**Fato:** [`blitz/libs.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz/libs.cpp) transforma registros do runtime em declaracoes do compilador; [`blitz/main.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz/main.cpp) exporta sintaxe com `+k`; [`blitzide/libs.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitzide/libs.cpp) usa essa saida para keywords e ajuda rapida.
|
||||
|
||||
**Licao:** as ferramentas devem explicar a mesma API que o compilador aceita, com origem e responsabilidade de cada metadado claras.
|
||||
|
||||
**Aplicabilidade:** seguir um callable real por declaracao SDK/core, modelo semantico, compilacao, hover, completion e signature help. O Studio ja tem `FrontendSignatureHelp`, `PbsEditorialSignatureHelp` e nomes canonicos no modelo semantico. Investigar divergencias demonstradas nesses caminhos, aproveitando o contrato existente.
|
||||
|
||||
**Limite normativo:** [Runtime Catalog Support](../../../docs/specs/compiler/24.%20Runtime%20Catalog%20Support%20Specification.md) exige catalogos locais versionados, porte manual dos consumidores e verificacao independente. Esta pesquisa preserva essa escolha: nao propoe geracao automatica de enums, parser de Rust, consulta ao checkout irmao em builds normais ou uma nova fonte de autoridade. Nomes de parametros da API PBS pertencem ao modelo semantico; ABI, custos e efeitos do provider continuam runtime-owned. O aprendizado do Blitz e a coerencia observavel, nao seu formato compacto de assinaturas.
|
||||
|
||||
### 3. Exemplos pequenos como instrumentos de ensino e avaliacao
|
||||
|
||||
**Fato:** `BLITZ3D_INSTALL` contem tutoriais isolados, samples visuais, jogos e um media viewer. O tutorial de colisao exercita uma cadeia de uso completa.
|
||||
|
||||
**Licao:** exemplos pequenos tornam o modelo ensinavel e revelam boilerplate, imports dificeis e combinacoes pouco naturais entre APIs. Um sample ganha valor de regressao quando tem caminho de execucao e resultado esperado definidos.
|
||||
|
||||
**Aplicabilidade:** aproveitar o corpus ja existente em `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/pbs-knowledge/examples/game/1/`, incluindo input/main, colecoes, lifecycle e memcard. Identificar uma tarefa mal explicada ou sem exemplo antes de criar outro corpus. Distinguir compilacao do fonte, empacotamento instalado e execucao do PBX resultante.
|
||||
|
||||
**Limite:** a [qualificacao do jogo de referencia](AGD-0088-studio-reference-game-qualification.md) ja e owner da prova integrada instalada. Esta agenda recebe criterios de ergonomia e aprendizado, sem absorver aquela entrega ou acrescentar seus gates. Audio permanece fora da wave dessa qualificacao, conforme sua revisao de escopo; o exemplo de audio do Blitz nao reativa a integracao de audio abandonada.
|
||||
|
||||
### 4. Helpers de gameplay pertencem primeiro a core/SDK
|
||||
|
||||
**Fato:** [`World`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/world.cpp) organiza regras direcionais de colisao, consultas sobre movimento e respostas de parar/deslizar. [`Object`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/blitz3d/object.cpp) separa captura de estado e representacao interpolada.
|
||||
|
||||
**Licao:** uma camada de conveniencia pode combinar poucos mecanismos com comportamento explicito para resolver tarefas frequentes. Consulta, avancar estado e emitir desenho devem ter efeitos reconheciveis.
|
||||
|
||||
**Aplicabilidade:** investigar bibliotecas PBS de gameplay apenas a partir de um exemplo que demonstre necessidade: overlap/sweep 2D, movimento contra tilemap ou outra operacao pequena. Declarar ordem, custos, limites, resultados e fallback. Dados compartilhados e estado por instancia tambem podem orientar tipos de SDK, sem herdar implicitamente copy-on-write ou semantica de alias do C++.
|
||||
|
||||
**Limite e ownership:** Sprite/Animator pertencem a [DSC-0098 / AGD-0100](AGD-0100-pbs-core-sprite-and-animation.md); a abstracao de emissao pertence a [DSC-0099 / AGD-0101](AGD-0101-pbs-composer-facing-blitable-contract.md). Esta agenda nao escolhe API, modifica essas discussoes, exige sua conclusao ou inclui implementacao de colisao nelas. Helpers geometricos futuros precisam de escopo proprio quando houver demanda. Novas capacidades da maquina exigiriam handoff separado ao runtime, nunca uma dependencia presumida desta pesquisa.
|
||||
|
||||
### 5. Preservar a explicacao do programa ate o diagnostico
|
||||
|
||||
**Fato:** [`StmtNode::debug`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/compiler/stmtnode.cpp) emite hooks com posicao de origem; [`debugtree.cpp`](https://github.com/blitz-research/blitz3d_soloud/blob/f132a78c9f2da255905bf477cb845994324b865a/debugger/debugtree.cpp) usa tipos e declaracoes para exibir variaveis e campos.
|
||||
|
||||
**Licao:** uma ferramenta precisa conservar origem, nomes e contexto suficientes para explicar o que falhou. Correcao do bytecode nao estabelece a qualidade dessa explicacao.
|
||||
|
||||
**Aplicabilidade:** seguir um erro atribuivel ao fonte por frontend, IR, PBX e retorno host/UI/MCP, verificando se a localizacao e a categoria sobrevivem. A [spec de emissao](../../../docs/specs/compiler/15.%20Bytecode%20and%20PBX%20Mapping%20Specification.md) ja exige `function_names` e `pc_to_span` minimos; nao tratar sua existencia como funcionalidade faltante. `BytecodeModule` ja carrega `DebugInfo`.
|
||||
|
||||
**Limite:** o acoplamento do debugger Blitz a ponteiros/estruturas do compilador e um contraponto, nao recomendacao de ABI. A emissao e apresentacao da origem pertencem ao Studio; a interpretacao dos metadados, faults e seguranca da execucao permanecem com o runtime. Load errors nao devem receber PC de instrucao executada inventado. O debug workspace/consumer externo conserva suas responsabilidades proprias; esta agenda nao incorpora trabalho daquele repositorio.
|
||||
|
||||
## Transferencia e Interfaces
|
||||
|
||||
| Tema recebido da pesquisa original | Owner e alvo de investigacao | Evidencia proposta para eventual aprofundamento |
|
||||
| --- | --- | --- |
|
||||
| APIs por tarefa completa | `compiler/pbs`: core/SDK, imports/barrels e exemplos PBS | Fonte curto pelo caminho real, efeitos e erros explicitos; comparar a tarefa antes/depois de qualquer proposta. |
|
||||
| Assinaturas e ajuda coerentes | `compiler/general` + `compiler/pbs`: consumidores do catalogo, metadata semantica, `FrontendSignatureHelp`, LSP | A mesma chamada apresenta nomes/tipos/ordem consistentes na compilacao e nas superficies editoriais; preservar catalogos e porte manual publicados. |
|
||||
| Exemplos ensinaveis e executaveis | `studio` + `compiler/pbs`: knowledge/examples instalados; handoff de prova integrada a DSC-0086 | Identificar fonte e distribuicao, compilar exemplo real e definir resultado esperado; nao chamar simples paridade de JAR de execucao do jogo. |
|
||||
| Helpers de gameplay | `compiler/pbs`: bibliotecas sobre os contratos atuais | Demonstrar necessidade e camada responsavel, com ordem/limite/fallback; encaminhar sprites/composicao aos owners existentes. |
|
||||
| Origem e diagnosticos do autor | `compiler/general` + `studio`: `DebugInfo`, atribuicao e retorno UI/MCP | Preservar origem real e categoria ao longo do pipeline; registrar lacuna concreta quando existir, sem inventar spans/PCs. |
|
||||
|
||||
Esta tabela transfere perguntas e sugestoes de evidencia. Nao declara implementacao, aceite tecnico ou novo gate mandatorio. Contratos publicados e discussoes existentes conservam sua autoridade. Os dois repositorios mantem indices e IDs independentes.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Comparacao focada de uma tarefa de autoria
|
||||
|
||||
- **Abordagem:** selecionar uma tarefa pequena e seguir sua API, metadata, ajuda e exemplo pelos mecanismos existentes.
|
||||
- **Pro:** produz evidencia concreta com escopo curto e reaproveita entregas existentes.
|
||||
- **Contra:** uma tarefa pode nao representar todos os perfis de usuario.
|
||||
- **Tradeoff:** melhor retorno inicial para distinguir qualidade de uso de cobertura de subsistema.
|
||||
|
||||
### Opcao B - Revisao transversal de metadata e diagnosticos
|
||||
|
||||
- **Abordagem:** avaliar varios tipos de callable e categorias de erro, mantendo fronteiras entre provider, compiler e editor.
|
||||
- **Pro:** pode localizar divergencias sistematicas entre consumidores.
|
||||
- **Contra:** exige corpus maior e pode repetir a qualificacao ja coberta por specs/testes.
|
||||
- **Tradeoff:** apropriada quando houver divergencia ou relato concreto que justifique a amplitude.
|
||||
|
||||
### Opcao C - Expandir primeiro bibliotecas e exemplos de gameplay
|
||||
|
||||
- **Abordagem:** escolher um helper ainda necessario e amadurecer sua API em agenda propria.
|
||||
- **Pro:** melhora diretamente a experiencia do autor quando a demanda e demonstrada.
|
||||
- **Contra:** risco de criar abstracoes antes do caso de uso ou duplicar sprites/composicao.
|
||||
- **Tradeoff:** depende de necessidade concreta e owner delimitado; nao e implementacao autorizada por esta transferencia.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Preferir **A**. O maior aprendizado do Blitz e oferecer um percurso curto entre intencao, codigo e feedback. Escolher uma tarefa suportada, comparar sua experiencia no Studio e registrar somente atritos reproduziveis.
|
||||
|
||||
Usar **B** quando a tarefa revelar divergencia de assinatura ou diagnostico. Considerar **C** apenas quando a dificuldade estiver na ausencia de uma composicao de gameplay, respeitando os owners de sprites/animação e emissao. O runtime permanece fornecedor dos contratos publicados; esta pesquisa de consumo pode avancar independentemente da agenda de runtime.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] Qual tarefa existente melhor representa a experiencia de autoria que se deseja avaliar?
|
||||
- [ ] A eventual dificuldade esta em linguagem/core/SDK, descoberta editorial, projeto ou UI?
|
||||
- [ ] Ha divergencia reproduzivel entre assinatura aceita e ajuda, ou a base atual ja cobre o achado do Blitz?
|
||||
- [ ] Quais exemplos instalados precisam apenas de melhor explicacao e quais demonstram uma composicao ainda ausente?
|
||||
- [ ] Existe demanda concreta de helper geometrico ou basta encaminhar os achados aos temas ativos de sprites/composicao?
|
||||
- [ ] Algum erro perde sua origem real entre emissao e apresentacao? Em qual consumer e com qual fixture?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Para convergir em uma futura decision, selecionar uma dificuldade observada, identificar owner e superficies afetadas, comparar alternativas e definir resultado verificavel. Quando o caso estiver coberto, registrar a evidencia em vez de inventar uma mudanca.
|
||||
|
||||
A transferencia solicitada esta concluida quando esta agenda preservar as fontes e perguntas recebidas, a agenda do runtime contiver somente suas responsabilidades e os links entre ambas resolverem. Essa conclusao organizacional nao fecha tecnicamente as propostas nem autoriza implementacao.
|
||||
|
||||
## Proximo Passo Sugerido
|
||||
|
||||
Escolher um pequeno fluxo de autoria ja suportado e comparar codigo, feedback editorial e resultado executado, considerando as discussoes existentes. As capacidades ainda em debate devem continuar com seus owners.
|
||||
|
||||
## Validacao e Estado
|
||||
|
||||
- Pesquisa e transferencia de responsabilidade; agenda aberta.
|
||||
- Sources do Blitz fixadas em commit, com fatos separados de aplicabilidade e limites.
|
||||
- Contratos locais e escopos de agendas existentes consultados; nenhuma qualificacao de comportamento reivindicada.
|
||||
- Sem mudancas em specs, SDK, compilador, runtime ou UI decorrentes desta transferencia.
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0004"
|
||||
workId: "WRK-000E"
|
||||
origin: "work-consolidation:WRK-0009:studio:DSC-0100:AGD-0102:ART-0002"
|
||||
purpose: "Registro original do índice DF de studio:DSC-0100:AGD-0102, preservado de\
|
||||
\ WRK-0009"
|
||||
path: "artifacts/evidence/ART-0004/payload"
|
||||
sha256: "b23f7ea52f027c46764bc12966ebe6d8d4a9a8425a7952f288753482d11e3fa2"
|
||||
size: 461
|
||||
author: "codex"
|
||||
createdAt: "2026-11-16T16:02:58.303251Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
{"type":"discussion","id":"DSC-0100","status":"open","ticket":"blitz3d-studio-engineering-lessons","title":"Licoes do Blitz3D para autoria e ferramentas","created_at":"2026-11-04","updated_at":"2026-11-04","tags":["studio","compiler","pbs","sdk","research"],"agendas":[{"id":"AGD-0102","file":"AGD-0102-licoes-do-blitz3d-para-autoria-e-ferramentas.md","status":"open","created_at":"2026-11-04","updated_at":"2026-11-04"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user