Files
zelda-1-prometeu-port/docs/prometeu-feedback.md
T

967 lines
59 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Feedback de interface e produção do Prometeu
Registro contínuo das facilidades e dificuldades encontradas ao portar Zelda 1.
O objetivo é orientar melhorias no Prometeu com casos concretos de produção.
Atualizar durante o desenvolvimento, incluindo o que vale preservar.
Iniciado em 2026-11-06. As observações iniciais vêm desta sessão de trabalho.
Os previews de sprites e frames do runtime foram inspecionados; a disposição
visual dos painéis do Studio ainda não foi avaliada diretamente.
## Como registrar
- Identificar a tarefa, o comportamento observado e seu impacto na produção.
- Distinguir fato observado, hipótese de causa e sugestão de melhoria.
- Incluir erro, arquivo, captura ou passos úteis para uma reprodução mínima.
- Registrar também facilidades que devem ser preservadas.
- Acrescentar novas ocorrências ao item existente quando for o mesmo problema.
- Marcar correções e revalidar; não apagar o histórico da dificuldade.
- Usar P1 para bloqueio ou desvio relevante no trabalho, P2 para atrito recorrente
e P3 para acabamento. Prioridades são propostas iniciais, não decisões de produto.
## O que está funcionando bem
| ID | Observação | Evidência e valor para produção |
| --- | --- | --- |
| BOM-01 | Banco de glyphs e animações têm identidade verificável | Os 16 frames de corpo foram preservados ao acrescentar quatro imagens da espada. UUID, artifact ID, glyph ID e fingerprint permitem conferir os vínculos. Evita depender apenas de nomes e posições de arquivos. |
| BOM-02 | Preview de animação recebe ticks explícitos | Foi possível consultar a segunda pose da caminhada no tick 6 e verificar o término dos clipes Once. Ajuda a depurar tempos sem depender de observação em tempo real. |
| BOM-03 | Build, pack e runtime podem ser usados no mesmo fluxo | A integração de sprites e o controle foram compilados, empacotados e executados pelas ferramentas do Studio. O runtime aceita entradas controladas e avanço limitado de frames. |
| BOM-04 | Capturas do runtime permitem validar regressões visuais | A divisão do código passou por 58 comparações de imagens anteriores e posteriores, todas idênticas. Ver [resultado da comparação](../extracted/link/refactor-validation.json). |
| BOM-05 | Diagnósticos trazem código e posição no fonte | Erros de sintaxe e resolução de símbolos incluem intervalo e arquivo. Depois da divisão, os oito arquivos retornaram diagnostics vazios. |
| BOM-06 | Revisão esperada na gravação de animações e concessão de controle são explícitas | As definições foram salvas com revisão esperada. O agente só adquiriu controle após a liberação em DEV e devolveu o projeto ao estado MANUAL nas entregas finais. Preservar essas garantias ao melhorar a ergonomia. |
| BOM-07 | Estruturas com estado por referência permitem organizar o jogo | A implementação atual passa um único LinkState entre movimento, atualização e desenho, mantendo a ordem do NES. Os objetos são criados uma vez; não há criação desses sistemas a cada frame. |
| BOM-08 | Bancos de cena, camadas e câmera alinham cenário e sprites sem redimensionar assets | A sala inicial usa 21 glyphs 8×8 no fundo e Link/espada na camada seguinte. A câmera posiciona a área NES na caixa 1:1; três capturas corresponderam à composição dos pixels extraídos. Ver [validação da sala](../extracted/overworld/start/runtime-validation.json). |
| BOM-09 | Stage com dados privados e services compõe cenário e colisão sem alterar a apresentação | A sala inicial exporta sua API, o Link consulta `Stage` e sete arquivos tiveram diagnostics vazios. Quatorze capturas de caminhos e bloqueios corresponderam pixel a pixel ao modelo. |
| BOM-10 | Banco independente com tiles 32×32 e paleta de nove cores preservou o HUD NES | O HUD foi publicado com 16 blocos sem redimensionar os padrões 8×8 originais. `Hud.draw()` compartilha o render entre stages; quatro capturas completas corresponderam pixel a pixel, inclusive espada acima do fundo do HUD. Formato e limite de paleta foram conferidos na especificação pública do packer; não foi necessário consultar Java. |
| BOM-11 | Troca de scene bank e reaplicação da câmera suportaram uma segunda stage | Caverna e overworld mantiveram bancos e colisões próprios, HUD compartilhado e atores alinhados. Build na primeira tentativa; 11 fontes sem diagnostics e 20 capturas de ida/volta sem diferenças. Não foi necessário consultar Java. |
| BOM-12 | Arrays tipados e módulos privados comportaram o estado original do inventário | O bloco de 40 slots Items e os 128 bytes de flags OW são arrays fixos por referência, com mutações encapsuladas. As tabelas de 36 itens foram preservadas. Quinze fontes sem diagnostics e 28 capturas da aquisição/revisita/reinício coincidiram pixel a pixel. A especificação pública de arrays foi suficiente, sem consulta a Java. |
Nota de validação visual: a pose de aquisição inicialmente omitiu o flip OAM
`$40` da metade direita. As comparações anteriores usavam o próprio PNG extraído
como referência e, por isso, não detectaram o erro de composição. A correção
conferiu a metade direita diretamente com os padrões `$08/$09` espelhados e
recapturou aquisição, bloqueio e término da pose. Isso é um limite da validação
do port, não evidência de defeito do Studio. Preservar inspeção visual e uma
referência independente dos atributos de montagem dos sprites.
| BOM-13 | Arrays compartilhados permitiram portar vida sem duplicar o estado do inventário | Items `$18/$19` são usados pela aritmética e pelo HUD. Um cartucho de teste executou 79 casos e 21 capturas sem diferenças; o jogo normal confirmou seis contatos de fogo, morte e continuação. Vinte e oito imagens de aquisição permaneceram iguais. As rotinas 6502 foram referência independente para 8.064 casos numéricos. |
## Dificuldades observadas
### ATR-01 Nomes de projeto aceitos não são todos endereçáveis em imports
**P1 · Observado; causa sugerida pela gramática consultada.**
O manifesto aceita `zelda-1`, mas `@zelda-1:generated/animations/...` gerou
`E_PARSE_EXPECTED_TOKEN`, encontrando `MINUS` onde era esperado `:`.
A gramática de referência de módulo consome um identificador simples para o projeto.
Impacto: não foi possível consumir diretamente a factory virtual de animação
com o nome atual do projeto. Foi necessário gerar uma consulta local de glyphs.
Melhoria: alinhar validação dos nomes e sintaxe de import; suportar nomes aceitos
pelo manifesto ou fornecer uma referência estável ao próprio projeto.
`@app` no exemplo não é uma solução demonstrada: o projeto do exemplo chama-se
`app`; tratá-lo como alias universal foi uma suposição incorreta do agente.
Contorno adotado na divisão em módulos: ajustar o identificador técnico do
manifesto para `zelda1`, preservando pasta e `app_id`. Os imports reais e o build
passaram. O problema do Prometeu continua aberto para nomes com hífen.
### ATR-02 Divisão em arquivos tem diagnósticos difíceis de interpretar
**P1 · Observado; reprodução mínima e causa ainda pendentes.**
Ao extrair funções para arquivos do mesmo módulo e declará-las com `mod fn`
no barrel, surgiram `E_SEM_APPLY_NON_CALLABLE_TARGET` em chamadas internas.
A tentativa com globais compartilhados também apresentou
`E_SEM_ASSIGN_TARGET_UNRESOLVED` nas atribuições de outro arquivo.
Uma tentativa com services alcançou a etapa seguinte e falhou com
`E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE` em chamadas qualificadas.
Impacto: uma divisão de aproximadamente 300 linhas exigiu sucessivas adaptações
de organização. A versão com structs, métodos e estado passado explicitamente
compilou e preservou as 58 capturas.
Melhoria: criar casos mínimos de funções, globais e services internos entre
arquivos; confrontar com a regra documentada de visibilidade `mod`.
Explicar no diagnóstico se falta visibilidade, assinatura ou suporte de lowering.
Não considerar a solução atual prova da causa dos erros anteriores.
Ocorrência na introdução das stages: `this.colliding_tile(...)` em service
falhou com `E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE`. Após extrair a sonda para
um struct privado, a expressão `probe.colliding_tile(...) <
OverworldStart.first_unwalkable()` também falhou, agora com intervalo localizado.
Atribuir os dois resultados a variáveis locais antes da comparação compilou e
passou nos testes visuais. Esse contorno foi encontrado sem consultar Java;
a causa do lowering permanece pendente de reprodução mínima no compilador.
### ATR-03 Erro de lowering expõe identificadores internos sem localizar a causa
**P1 · Observado; reprodução mínima pendente.**
Durante uma tentativa de consumir Animator por uma factory local, o build falhou
com `MARSHAL_VERIFY_PRECHECK_BAD_RET_STACK_HEIGHT`,
`expected=0 actual=1 [fn=52] [pc=392]`.
Impacto: o diagnóstico não permitiu identificar a expressão PBS responsável.
A consulta direta aos frames foi a alternativa que compilou.
Melhoria: anexar nome da função, arquivo, intervalo de fonte e caminho de chamada.
Investigar o caso antes de atribuir o defeito ao tipo result ou ao Animator.
### ATR-04 Misturar Gfx e Composer pode ocultar sprites
**P2 · Observado em capturas e confirmado pela leitura do pipeline.**
Uma área desenhada com `Gfx.clear` e `Gfx.fill_rect` cobriu Link, embora a emissão
do sprite tivesse sido aceita. Nesse pipeline, as primitivas Gfx são aplicadas
como overlay depois da composição canônica.
Impacto: a cena pareceu não desenhar o personagem, sem erro de execução.
Melhoria: documentar a ordem de desenho perto das APIs e do exemplo inicial;
fornecer um exemplo de fundo de cena com sprite, distinguindo-o de overlays.
O comportamento observado é compatível com a ordem implementada; não foi
demonstrado um defeito do rasterizador.
### ATR-05 Sprites sem cena deixaram rastros entre frames
**P2 · Observado em capturas e confirmado pela leitura do caminho sem cena.**
Depois de remover o overlay, desenhar apenas sprites sem vincular uma cena
manteve pixels de frames anteriores. Vincular uma cena vazia resolveu os rastros.
Impacto: até um teste simples de movimento precisou de um banco de cena adicional.
Melhoria: tornar explícita a política de limpeza de frames sem cena e oferecer
um caminho mínimo de produção para fundo vazio com sprites, sem configuração
manual inesperada.
### ATR-06 Estado de devolução de controle ficou ambíguo
**P2 · Uma ocorrência observada.**
Uma chamada de release retornou `CLEANUP_FAILED: Project control: BUSY`.
A chamada seguinte retornou `WAITING_FOR_ACCESS`. Em entregas posteriores,
shutdown do runtime seguido de release retornou `MANUAL` normalmente.
Impacto: ficou incerto se o controle já havia sido devolvido e se a interface
precisaria de atualização. A causa do primeiro episódio não foi identificada.
Melhoria: retornar o estado final de autoridade mesmo quando o cleanup falha,
separar pendências de limpeza de concessão de controle e indicar recuperação.
### ATR-07 Mensagens de sucesso intermediário coexistem com falha do build
**P2 · Observado no erro inicial do projeto.**
O log mostrou `builder pipeline completed successfully` após
`E_LINK_UNRESOLVED_BARREL_ENTRY` e terminou com
`issues found on pipeline stage: analyze`.
Impacto: o usuário precisa interpretar linhas aparentemente contraditórias
para entender se o jogo compilou.
Melhoria: distinguir etapa executada de resultado válido e destacar um único
resultado final. Para o barrel exportando `init` inexistente, oferecer navegação
ao símbolo e explicar as opções de declarar a função ou ajustar a exportação.
### ATR-08 Importação de bancos pelo agente exige edição de manifestos
**P2 · Lacuna nas ferramentas disponíveis nesta sessão.**
Havia ferramentas para animações, linguagem, build e runtime. Não havia uma
operação anunciada de importação/criação/registro de banco de PNGs. Foi necessário
escrever `asset.json`, seleção de artefatos e o índice de registro pelo filesystem.
Impacto: o fluxo de produção precisou conhecer formatos de persistência e IDs.
Isso não demonstra ausência dessas operações na interface manual do Studio.
Melhoria: expor importação em lote, criação e registro de banco, composição e
consulta de layout com as mesmas validações e proteção de revisão do editor.
Nova ocorrência ao montar a sala inicial: foi preciso registrar um banco de
21 tiles, gerar a requisição de cena 32×30 e excluir o banco vazio do build
editando os formatos de persistência. O fluxo compilou, mas uma operação de
importação de tilemap pelo conector reduziria o conhecimento de formatos exigido.
### ATR-09 Boot com escolha explícita de memória falhou
**P2 · Uma ocorrência observada; causa ainda pendente.**
`studio_headless_boot` com `memcardChoice=memory_fresh` retornou
`MEMCARD_ERROR`, `boot: invalid_state`. A consulta seguinte informou ausência
de sessão ativa. Boot sem esse parâmetro funcionou.
Impacto: uma escolha explícita anunciada pela ferramenta interrompeu o teste.
Melhoria: reproduzir a sequência em uma sessão nova e documentar/validar as
precondições da escolha antes de iniciar o boot. Não há evidência de perda de dados.
### ATR-10 Uso normal do PBS depende de consultar a implementação Java
**P1 · Atrito observado repetidamente pelo agente e apontado pelo usuário.**
Para dividir arquivos, interpretar visibilidade, resolver imports e compreender
falhas de lowering, o agente consultou parser, serviços semânticos e testes Java
do compilador. Esse caminho exige acesso e familiaridade com o código interno
do Prometeu para realizar tarefas comuns de autoria de um jogo.
Impacto: aumenta o tempo de produção e dificulta o uso por quem conhece apenas
PBS e o Studio. A consulta ao Java também pode refletir uma investigação de bug,
não necessariamente uma regra ausente da linguagem; registrar essa distinção.
Melhoria: oferecer um guia de produção com exemplos completos e compiláveis de
módulos, barrels, estado mutável, construtores, imports e consumo de animações.
Vincular cada diagnóstico à regra e ao exemplo correspondente. Manter exemplos
validados contra o SDK instalado e explicitar limitações conhecidas.
Conduta neste port: consultar primeiro as referências e exemplos expostos pelo
Studio; recorrer à implementação somente quando houver lacuna, contradição ou
um defeito a investigar. As referências `pbs:spec:3` e `pbs:spec:5` do Studio
foram consultadas para a divisão atual em módulos.
Exemplo concreto de desatualização: `pbs:spec:5`, seção 5.2, apresenta
`import { Gfx, color } from @sdk:gfx` e `Gfx.draw_pixel(...)`. A referência
instalada `pbs:sdk:game:1:sdk/gfx/main.pbs` usa `Color` de `@core:color` e não
declara `draw_pixel`. Isso reforça a necessidade de validar exemplos contra
o SDK distribuído.
### ATR-11 Tipo de cena importado falhou no build sem diagnóstico de fonte
**P1 · Observado na divisão em módulos; causa e reprodução mínima pendentes.**
Uma versão com `pub struct Scene`, `new Scene.make()` na raiz e uma referência
Scene recebida pelo módulo Link falhou no build com
`Unsupported PBS runtime type: Scene`. Quatro consultas de diagnostics retornaram
`INFRASTRUCTURE_FAILURE: LSP query failed`, sem apontar um intervalo PBS.
Impacto: a tentativa de encapsular objetos entre módulos não forneceu informação
suficiente para distinguir uma limitação de autoria de um defeito do compilador.
Isso não demonstra que todos os structs importados sejam incompatíveis.
Alternativa validada: APIs públicas `Link` e `Scene` como services, com structs
internos no módulo Link. Build e diagnostics passaram, e as 58 capturas de
regressão continuaram idênticas. A documentação de services foi consultada pela
API de referências, sem uma nova consulta às fontes Java para essa alternativa.
Melhoria: reduzir o caso com tipos e construtores importados, produzir um erro
com localização no fonte e manter o LSP funcional mesmo quando o lowering falha.
### ATR-12 Apresentação de uma área de jogo menor exige composição manual
**P2 · Lacuna na superfície de autoria consultada; solução local validada.**
O port mantém a área NES de 256×240 dentro do framebuffer 480×270. A referência
`@sdk:composer` consultada expõe câmera, vínculo de cena e emissão de sprites,
sem parâmetros de retângulo de viewport, clipping ou escala de apresentação.
A especificação GFX documenta resolução base fixa e escala pelo host.
O usuário preferiu manter 1:1 e colocar a imagem numa caixa. A implementação
local calcula centralização, desenha uma moldura externa e encobre as regiões
fora da área NES com overlays. Os seis testes visuais passaram, preservando os
pixels internos e limitando a espada na borda inferior.
Impacto: um encaixe comum de jogo com outra resolução lógica exige conhecer a
ordem Composer/Gfx e implementar manualmente máscara e moldura. Não foi provada
a ausência de todo suporte interno a viewport no runtime; a lacuna constatada
é a configuração disponível ao autor do projeto nas referências consultadas.
Melhoria: oferecer uma configuração documentada para área lógica, encaixe 1:1,
clipping e, futuramente, escala inteira no host. Preservar a imagem canônica
do runtime e tornar explícita a diferença entre área de jogo e apresentação.
### ATR-13 Reset headless retornou sucesso, mas a sessão ficou terminada
**P2 · Uma ocorrência observada; causa pendente.**
Após boot e um frame correto, `studio_headless_reset` retornou sem erro.
O avanço seguinte pediu 200 frames e devolveu `TERMINATED`, com zero frames
executados. `studio_headless_state` mostrou appId 0, pc 0, logicalFrameIndex 0.
Encerrar e iniciar outra sessão com o mesmo build permitiu executar os 200
frames. As 14 verificações usaram sessões novas, evitando depender do reset.
Melhoria: investigar o reset e retornar explicitamente um estado que permita
saber se o aplicativo continua executável; cobrir reset seguido de avanço.
Não foi constatada uma falha do código PBS nesse episódio.
### ATR-14 Prioridade do sprite em relação aos pixels do fundo não tem contrato explícito na referência consultada
**P2 · Lacuna de documentação observada; não demonstra ausência de suporte interno.**
A entrada e saída da caverna NES usam o bit de prioridade do sprite para esconder
partes de Link atrás dos pixels de fundo cujo índice não é zero. A referência
pública `@sdk:composer` documenta `layer` e `priority`, mas não descreve um modo
com essa semântica por pixel em relação ao tilemap.
O port optou por gerar 68 variantes locais do corpo, mascaradas conforme os
índices originais do terreno em cada posição da porta. As capturas de entrada
e saída corresponderam à composição esperada. Essa solução adiciona assets e
acopla as máscaras à abertura específica. Nenhum defeito do parâmetro `priority`
foi demonstrado; sua equivalência à regra NES não foi assumida.
Melhoria: documentar a relação entre prioridade de sprites, camadas e fundo,
com um exemplo de oclusão de atores por tiles e índice transparente. Avaliar
uma configuração de oclusão no cenário para dispensar variantes por posição.
### ATR-15 Compor elementos mutáveis sobre o terreno fixo
**Aprendizado de composição do port · escolha estática corrigida. Não é defeito do runtime.**
A primeira implementação incorporou texto, velho e espada ao tilemap e usou
três scenes para coleta e desaparecimento. Essa escolha nossa gerou rebinds
ao piscar o velho; não era uma necessidade do Prometeu nem uma restrição de
sprites. Não atribuir esse custo ao runtime.
A refatoração mantém o terreno numa única scene ativa e emite velho, espada,
fogo e letras como sprites/glyphs independentes, com visibilidade comandada
pelos estados existentes. O fundo do inventário contém só terreno e recebe
os mesmos objetos deslocados durante sua rolagem. A identidade visual da
stage permanece constante durante coleta e piscadas. IDs de assets e glyphs
anteriores são preservados; scenes 2/3 ficam reservadas para não deslocar
os IDs das demais telas.
Aplicar o mesmo padrão às paredes bombáveis: passagem no terreno base,
cobertura mutável desenhada à parte, e uma flag persistente compartilhada
por render, colisão e entrada. Não multiplicar scenes por combinações de
objetos/segredos. Referência prática: `docs/scene-composition.md`.
Revalidação: dez capturas de terreno + sprites foram idênticas aos compostos
NES anteriores, incluindo velho visível/oculto, espada/texto removidos e duas
rolagens parciais do inventário. 2.573 sondas da caverna continuaram iguais à
rotina nativa. Asserções conferiram coleta, flag, posse, timer, pausa e revisita,
com chave de scene e variante do inventário constantes. No build normal,
inputs percorreram a entrada e a coleta com Link erguendo a espada; o submenu
abriu depois da coleta. Nenhum perfil foi escrito no cartão do usuário.
Regeneração idempotente em 1.176 arquivos; os 44 glyphs legados mantiveram seus
bytes e IDs. Evidências em `extracted/cave/start/composition-validation`.
Build final 5e713d48 aprovado, diagnostics vazios nas cinco fontes consultadas.
### ATR-16 Ensaiar serviços de gameplay exigiu trocar temporariamente a entrada do projeto
**P2 · Custo observado na superfície de testes utilizada.**
Para testar cura, limites e morte sem adicionar teclas de debug ao jogo,
foi gerado um `main.pbs` de ensaio e compilado temporariamente no mesmo projeto.
A entrada normal foi copiada de volta antes do build jogável. A ferramenta
`studio_build_start` consultada recebe a raiz do projeto e não uma entrada ou
target de teste separado.
Impacto: aumenta o cuidado com restauração e rastreamento do build testado.
Não foi demonstrado que todo mecanismo interno de testes tenha essa limitação.
Melhoria: oferecer um target de testes com entrada própria, assertions e estado
consultável, preservando o source de produção e o fluxo de Play normal.
O ensaio usou apenas referências públicas e PBS, sem acesso às fontes Java.
## Primeiras prioridades propostas
1. Resolver endereçamento de projetos e reprodução mínima da divisão em arquivos
(ATR-01 e ATR-02), pois afetam a organização normal de um jogo.
2. Tornar erros de lowering localizáveis no PBS (ATR-03).
3. Entregar um exemplo mínimo de sprites com fundo e limpeza corretos
(ATR-04 e ATR-05).
4. Melhorar resultado final do build, importação de assets e estados de controle
(ATR-06 a ATR-09).
## Avaliação de interface ainda a fazer
Observar diretamente os fluxos do editor: importar PNGs, encontrar um banco,
montar/reordenar frames, escolher paleta, dar Play e retornar ao código.
Anotar ações necessárias, passos repetidos, retorno visual e recuperação de
erro. Ainda não atribuir problemas de layout, descoberta ou usabilidade visual
a painéis que não foram inspecionados.
## Abertura e ciclo principal — 2026-11-06
### BOM-14 — Composição fiel com bancos indexados e sprites
Título extraído da ROM usa atributos, paletas, flips e prioridade de sprites.
Trinta e sete comparações de capturas do Studio passaram sem diferença de pixels,
abrangendo também menu e transições. A composição reutiliza Scene e o viewport
existentes; onze consultas de diagnostics ficaram vazias. Evidência e protocolo:
`extracted/game_flow/validation`. Referências públicas foram consultadas antes
originalmente; nenhuma consulta Java foi necessária nesta etapa.
### ATR-17 — Limite de bancos aparece como falha genérica no boot
Uma versão inicial pré-carregava 17 cenas, incluindo slot 16. O build aceitou,
mas o boot headless falhou com BackendError, sem identificar o asset/slot.
Após consultar as referências disponíveis, a investigação em
`runtime/crates/console/prometeu-drivers/src/memory_banks.rs` confirmou arrays
com 16 posições; `asset.rs` reduz falhas de preload a BackendError. Esta é
investigação do runtime Rust, não consulta Java para aprender PBS.
Impacto: um build aprovado não garantia cartucho inicializável e o diagnóstico
não apontava a configuração responsável. Sugestão: validar limites no pack/build
e propagar asset, tipo de banco e slot no erro de boot. Contorno aplicado:
compartilhar quatro cenas entre as oito fases de brilho; total atual 13 cenas.
Boot e ciclo completo revalidados. A validação antecipada do produto continua
pendente; o contorno no jogo não representa correção do runtime.
Lição do port: offsets de tabelas em disassembly de referência divergiam da ROM
fornecida. A extração passou a seguir os ponteiros reais do cartucho. Isso não
é defeito do Prometeu e não deve ser contabilizado como problema de interface.
## Sala norte e Octoroks — 2026-11-06
### BOM-15 — Composição e testes determinísticos sustentam o port
Cenário norte e encontro extraídos da ROM, publicados em bancos separados e
observados no Studio. Três capturas completas coincidiram pixel a pixel com
composição dos patterns/paletas originais; 32 asserções executadas no guest
passaram. As 3.672 sondas confrontadas com a rotina 6502 verificam o modelo de
colisão fora do Studio. Referências SDK foram lidas pelo conector; nenhuma
consulta Java foi necessária. Evidências em `extracted/overworld/north/validation`.
### ATR-02 / ATR-03 — Reincidência em expressões com chamadas
O build falhou em lowering com `MARSHAL_VERIFY_PRECHECK_BAD_RET_STACK_HEIGHT`,
`expected=1 actual=2 [fn=72] [pc=363]`; após contornar expressões, outro ponto
surgiu como `[fn=235] [pc=78]`. A fixture também expôs retorno `expected=0
actual=5 [fn=70]`. Guardar resultados de chamadas em locais antes de comparações,
expressões e argumentos resolveu o conjunto. Não foi isolada a causa de cada
caso: esses IDs não mapeiam diretamente a arquivos PBS no diagnóstico. Manter
como reincidência do problema já registrado, não nova causa confirmada.
Chamadas entre serviços de arquivos do mesmo módulo na fixture também precisaram
import explícito do serviço; o compilador retornou erro localizado de overload.
### ATR-04 — HUD durante rolagem exige camada acima do cenário
Primeira captura da câmera vertical mostrou o mapa cobrindo o HUD que era emitido
na camada 0. Passar o HUD para a camada 2, preservando personagens na 1, resolveu
e foi verificado nas capturas. A referência de Composer documenta câmera/camada,
mas não explica suficientemente a interação de tilemap ativo com sprites na
mesma camada. Sugestão: exemplo de HUD fixo com cenário em rolagem e ordem de
composição explícita. O sintoma foi observado no runtime; não é avaliação visual
de painel do editor. A camada atual está anotada no código e nas orientações.
Lição de extração: nuvens usam CHR herdada da abertura, fora do bloco de sprites
OW. A conferência visual encontrou a omissão e a ordem de carga foi corrigida.
Isso é particularidade do cartucho, não defeito do Prometeu.
## Correção dos gráficos do Octorok — 2026-11-06
Erro do port, não do Prometeu: o extrator omitia o incremento de tipo no caminho
DrawObjectWithType e ignorava flip vertical dos frames para cima. Octoroks usavam
frames de outra animação e a pedra selecionava tile $98 em vez de $9E.
O validador copiava a hipótese de índice incorreta; suas três capturas não
incluíam pedra visível. Assim, a evidência pixel a pixel de BOM-15 não provava
fidelidade da interpretação dos descritores. Os testes de colisão e dano eram
separados e não detectariam esse erro de composição.
Correção de produção: descritores obtidos por execução limitada do código 6502
original, sem consultar Java. Uma fixture no Studio desenha os oito frames e
uma pedra visível simultaneamente; as nove imagens e o framebuffer completo
coincidiram com os descritores da ROM. A fixture foi removida antes do build
jogável. Evidência: `extracted/overworld/north/validation/graphics_fix`.
Lição: validar todos os estados visuais relevantes e usar um oráculo que não
repita a mesma suposição do extrator. Não atribuir a falha ao renderer ou à UI.
## Ciclo de combate, drops e projéteis — 2026-11-06
### BOM-16 — Produção modular e validação de estados visíveis
Histórico, inventário, loot, personagem e apresentação permaneceram separados.
Um banco de 30 patterns 8×8 atende itens, projétil, dispersão e dígitos, incluindo
sprite NES ímpar que seleciona a tabela de background. Comparações das folhas
visuais no Studio passaram sem diferença de pixels; o HUD inicial permaneceu
idêntico após trocar os contadores fixos por valores de Items. Dados e imagens
em `extracted/combat`. Os testes no guest verificaram 2.214 condições, além das
verificações internas de projétil e ricochete, e foram seguidos por sessão real
com coleta e histórico de mortes. Dezenove fontes tiveram diagnostics vazios.
Referências SDK e código 6502 foram suficientes; nenhuma consulta Java.
### ATR-18 — Inicialização global limita uso de factories encapsuladas
**Restrição observada; não classificada como defeito do compilador.**
Declarações globais `loot0: DroppedItem = Loot.new_item()` foram rejeitadas com
`E_SEM_GLOBAL_UNSUPPORTED_INITIALIZER`, com nome do global e localização. A
construção direta com `new DroppedItem(new FairyFlight(...),...)` compilou, mas
exigiu expor o tipo auxiliar FairyFlight no barrel para o módulo consumidor.
Impacto: composição de estado de módulos precisa expor mais detalhes ou criar
uma estratégia adicional de inicialização. Sugestão: documentar o padrão
recomendado de factory/Init e considerar factory pura suportada em globals.
O diagnóstico foi localizado; não foi necessário consultar a implementação.
### Procedimento de teste — watchdog e lotes por frame
Executar toda a fixture grande no Init atingiu o watchdog headless de 100.000
ticks de firmware, com resultado tipado `INFRASTRUCTURE_FAILURE` e
`watchdog_expired`. Distribuir casos em 93 frames resolveu sem alterar runtime
ou orçamento do jogo. Guardar esse padrão nos exemplos de testes guest; não
tratar o limite acionado pelo teste como falha de gameplay ou defeito de UI.
Lição de validação mantida da correção anterior: conferir os estados visíveis
por descritores executados da ROM, não apenas por tabelas reinterpretadas pelo
mesmo extrator. As folhas desta etapa incluem todos os drops relevantes, as
quatro direções do projétil e o ricochete em fases diferentes.
## Tela de inventário — validação no Studio
**Bom:** APIs de input, composição, camadas, câmera e sprites indexados foram
suficientes para portar o submenu sem consultar fontes Java. O HUD conserva
layer 2 e acompanha a rolagem; seleção e posse ficaram separadas de Link e da
stage. Os quatro bancos nativos de paleta de sprites atendem todos os ícones.
**Evidência:** build de produção aprovado, quinze documentos PBS com diagnostics
vazios, 1.104 comparações da busca de seleção contra execução 6502 da ROM e três
veredictos de integração no guest: bombas, pausa/retomada e poções/seleção. Todos
passaram. A comparação visual independente encontrou igualdade nas 1.125 amostras
opacas dos ícones (retângulo sobreposto pelo cursor excluído). Gerador de assets
reexecutado sem mudança em 245 arquivos. Fixtures ficaram fora de src após o teste.
Resultados e capturas em `extracted/inventory_screen/validation`.
**Restrição de produção:** há 16 slots de scene. O submenu ocupa o último,
compartilhando os cinco fundos congelados em faixas de uma única scene longa.
Isso compilou e executou no Studio. Ajuda futura: mostrar orçamento de scenes
no editor e documentar padrões de carregamento/reutilização para jogos maiores.
**Limite de fidelidade ainda aberto:** a API Gfx/Assets consultada não documenta
um controle de grayscale global equivalente ao PPUMASK do NES. A bomba mantém
fusível, nuvens, dano e consumo, mas falta esse flash global. Não foi necessário
alterar o runtime para concluir o menu; avaliar filtro de tela/paleta no SDK.
**Diagnóstico do compilador em fixture:** uma versão de teste recebeu
`MARSHAL_VERIFY_PRECHECK_BAD_RET_STACK_HEIGHT`, identificando função por número
(`fn=201`, `pc`) sem arquivo PBS. Foi possível concluir os mesmos objetivos em
rotinas menores com resultados intermediários explícitos. Causa não isolada;
não atribuir genericamente a chamadas aninhadas. Sugestão: mapear o verificador
para nome de função/arquivo/span, preservando o detalhe técnico para investigação.
## Percurso de bombas — salas OW $66/$65/$64
**Bom:** reaproveitar as scenes 13/14/15 como atlas permitiu acrescentar três
stages independentes, três transições horizontais reversíveis, HUD e inventário
por sala sem ultrapassar 16 scenes. Câmera X/Y e glyphs com paletas alternativas
atenderam cenários de cores diferentes. Nenhuma consulta Java nem alteração do
runtime. O pool de inimigos/drops foi ampliado para cinco.
**Validação:** build final aprovado, quinze fontes com diagnostics vazios,
2.560 execuções nativas do drop de azul sem divergências. Fixture guest passou
ida/volta nas três salas, HP de dois golpes, imunidade, geração nativa do drop,
coleta de quatro bombas e consumo de uma pelo B. Capturas e resultados em
`extracted/overworld/northwest`; fontes de teste removidas de src antes do build
final. Não há alegação de equivalência completa por frame com o jogo emulado.
**Produção:** a regeneração de assets ainda exige ordem explícita: north,
bomb_route, inventory_screen. Como o último banco de cena já foi ocupado,
novas stages dependem de layout e orçamento dos atlas compartilhados. Sugestão:
manifesto de geração com dependências e visualização do orçamento no Studio.
**Diagnóstico:** o verificador backend voltou a informar erro de altura de
stack somente com número de função e PC em uma fixture. Resultados locais
explícitos permitiram concluir o teste. Consolidar com o registro anterior;
a ausência de nome/arquivo continua sendo a dificuldade observada.
**Lição do port:** a pesquisa na internet identificou duas fontes legítimas de
bombas (loja e Octoroks azuis). A ROM foi necessária para escolher o menor
percurso atual: atributo D bit 7 integra o ID de lista. O valor C=$69 nas salas
intermediárias resolve para uma lista mista vermelha, não para tipo $09. Dados
publicados incluem ponteiro e bytes completos das listas; não basear spawns
apenas nos seis bits baixos de C.
## Bomba temporária para teste solicitado pelo usuário
Exceção explícita à fidelidade dos itens iniciais: um pacote nativo de quatro
bombas foi colocado em ($98,$8D), à direita de Link. A posse continua passando
por Inventory.take_drop; o objeto de teste pertence à stage inicial e não muda
as tabelas da ROM nem o inventário inicial. Um único const em
`src/stages/overworld_start/test_bomb.pbs` permite desativá-lo. O registro de
coleta dura até partida nova; Continue e retorno à sala não recriam o pacote.
Respawn foi conferido novamente em ModifyObjCountByHistoryOW: sala limpa e
presente no histórico de seis entradas permanece limpa. O código atual mantém
essa regra; não trocar por respawn imediato para facilitar o teste de bombas.
Durante a verificação por input headless, capturas não corresponderam à
sequência esperada de botões (por exemplo, um comando right foi seguido por
menu aberto). Causa não isolada; não atribuir a defeito do teclado do Studio.
O teste de coleta/consumo foi executado também diretamente na máquina GameFlow,
sem depender dessa automação de botões. Capturas ficam separadas por nome.
Resultado: os seis checkpoints guest passaram (zero inicial, coleta +4, B -1,
menu sem consumo, retorno sem recriar, partida nova recria). HUD capturado
mostrou 4 após coleta e 3 após uso; a explosão foi renderizada. Fixture removida
de src antes do build final. Nenhum novo asset ou slot de scene foi necessário.
## Parede bombável — mecanismo OW e montagem temporária
**Bom:** os glyphs de terreno existentes e composição de sprites foram
suficientes para cobrir a abertura, inclusive no fundo congelado do inventário
e durante ambas as rolagens verticais. Não foi necessário mais um asset, slot
de scene ou alteração de runtime. A caverna, a espada e as transições existentes
foram reutilizadas. Nenhuma consulta a fontes Java.
**Evidência:** 121 casos de colisão executados no leaf 6502 real foram conferidos
no guest. Passaram também flags independentes, fusível sem revelar, detonação,
prioridade de bomba, entrada bloqueada/aberta, coleta da espada, saída da
caverna, Continue e reset de partida. Cinco recortes 16×16 de terreno (fechado,
inventário, duas rolagens e abertura restaurada) coincidiram exatamente com os
PNGs nativos. Fontes de fixture restauradas antes do build de produção; dados
em `extracted/bomb_wall`.
**Dificuldade de PBS:** após acrescentar dependências à stage inicial, chamadas
para RoomData.tile_at/normalize_tile/first_unwalkable/contains_player passaram a
receber `E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE`, sem mudança nesses métodos.
Renomear apenas a variável global não resolveu; dar ao tipo o nome específico
StartRoomData resolveu as quatro chamadas. Outras stages têm tipos locais
chamados RoomData. Causa interna não isolada; registrar como suspeita de
resolução de identidades com nomes repetidos/ciclos, não como diagnóstico
confirmado. Sugestão: incluir módulo/identidade do receiver no diagnóstico e
cobrir essa composição nos testes do compilador.
## Encerramento dos testes temporários de bomba
Após aprovação do usuário, os dois toggles de teste foram desativados: pacote
inicial e parede na entrada da espada. A abertura e o inventário inicial voltam
ao comportamento original; drops dos Octoroks, bombas, flags e mecanismo de
paredes permanecem. Os toggles permitiram encerrar a montagem sem tocar em
assets nem na lógica de produção validada. Capturas anteriores são históricas.
Verificação do encerramento: build de produção aprovado e diagnostics vazios
nas duas fontes alteradas; ambos os toggles conferidos como false.
## Save no memcard — perfil único
**Bom:** referências instaladas MEMCARD.md, exemplo e @sdk:mem foram suficientes
para implementar bootstrap, metadados/ícone, RAM do slot, commit, query e
release sem consultar Java. O resultado tipado separa aceitação de pedido,
durabilidade e memória apenas. O jogo só mostra GAME SAVED após state 1;
state 4 recebe MEMORY ONLY / NOT SAVED TO CARD. O runtime continua responsável
por montagem, publicação, recuperação e descarte de sessão.
**Evidência:** gravação durável confirmada, processo encerrado e mesmo cartão
reaberto em novo processo; os 180 bytes coincidiram com payload independente
Python/Adler-32, incluindo 00/7f/80/ff. Progresso, três corações com capacidade
preservada, relógio temporário e história reconstruída foram conferidos no
guest. App version 1.0.0→1.0.1 manteve acesso com app_id estável. Cartão RO em
memory_existing bloqueou Save e permaneceu idêntico byte a byte; memory_fresh
terminou sem alegar gravação. Magic inválida, schema não suportado e slot
truncado foram rejeitados sem alterar seus payloads. Dois recortes de UI
coincidiram pixel a pixel com composição independente de patterns NES.
Dados, capturas, limites e testes em `extracted/save`.
**Proteção útil do host:** PERSISTENT com mídia RO foi recusado antes de admitir
o jogo, com reason read_only; memory_existing permitiu carregar essa mídia.
Após teste em memory_fresh, shutdown/build recusou RAM suja com unsaved_changes.
Só a RAM da fixture descartável foi descartada explicitamente para continuar.
Não transformar essas recusas em sucesso nem descartar progresso do usuário.
**Produção:** fonte NES e ícone de Link foram gerados a partir dos assets/ROM,
reutilizando o banco de glyphs e a scene do menu. Nenhum slot de scene adicional.
Regeneração idempotente em 49 arquivos; prepare_game_screens encadeia a etapa
save_ui para não restaurar inadvertidamente o antigo menu sem SAVE.
**PBS:** imports de services privados do próprio módulo foram recusados com
E_LINK_IMPORT_SYMBOL_NOT_PUBLIC; convertê-los em structs auxiliares privados,
como os demais módulos, manteve o codec/ícone encapsulados e compilou. Registrar
esse padrão nos exemplos de composição de módulos; não foi necessário expor
helpers de serialização ao jogo nem recorrer às fontes Java.
**Lição de fidelidade:** copiar os bytes completos de WorldFlags segue o save
original; não mascarar todos os kills por suposição. O histórico de seis salas
não é salvo. Conferir offsets absolutos também importa: InvClock=$066C menos
Items=$0657 é slot $15, não $14. A fixture distingue e preserva o slot vizinho.
Nenhuma alegação de teste de corte de energia durante IO ou emulação lockstep.
**Verificação final pela interface do jogo:** em build sem fixtures, inputs
headless com dois frames de pressão/liberação percorreram título, New Game,
menu vivo, seleção de Save, confirmação, GAME SAVED, encerramento do processo
e Continue no boot seguinte. O cartão padrão `.studio/memcard.pmc` foi criado
pelo host sem receber perfis de teste; todos os testes de payload ficaram em
imagens separadas de .tmp. A captura inicial SAVING permaneceu correta até o
Frame observar o commit já retornado pelo runtime: não confundir fim do avanço
de frames com espera de IO. Não foi necessário alterar o input do jogo.
Esse procedimento também evita atribuir ao teclado um possível erro de
sequenciamento das capturas headless mencionado no teste temporário anterior.
Build final aprovado e diagnostics vazios em 12 fontes PBS; nenhuma fixture
permaneceu em src. O boot de produção com o cartão padrão foi revalidado.
## Expansão do overworld — nove salas
**Produção positiva:** atlas compartilhados permitiram adicionar quatro salas,
18 conexões direcionadas e 12 faixas de inventário mantendo os 16 slots de
scene existentes. Cada stage continua dona da colisão e do render, com catálogo
ROM compartilhado para identidade, inimigos e apresentação. Não foi necessário
consultar fontes Java. Build/pack e headless permitiram conferir dados e pixels.
**PBS observado:** `return data.edges(stage)!=0` produziu
E_SEM_EXEC_LOWERING_UNRESOLVED_CALLEE na chamada, apesar do método existir.
Separar em `let value=data.edges(stage); return value!=0` compilou. Causa interna
não investigada; sugerir cobertura/documentação desse formato de expressão e
um diagnóstico mais específico. A consulta LSP localizou o mesmo intervalo.
**Limite de fixture:** uma função de Frame com 1.814 condicionais sequenciais
foi recusada com MARSHAL_VERIFY_REGISTRY_INVALID / verification scratch limit.
Agrupar ações repetidas por intervalo resolveu o build. O jogo normal já
compilava. Melhorar a mensagem com a função/limite relevante; isso foi um
limite de produção de teste, não um defeito visual da interface.
**Evidência de fidelidade:** 16.524 sondas contra a rotina de colisão nativa e
192 buscas de entrada contra FindNextEdgeSpawnCell 6502 passaram. A fixture
executou 1.814 frames, conferiu as 18 transições, os quatro encontros com
entrada pelas bordas e a expulsão do histórico de seis salas preservando item.
45 comparações de terreno/HUD/inventário/destinos foram exatas. A primeira
fixture esqueceu de zerar o offset de HUD como GameFlow faz; foi corrigida na
fixture, sem atribuir esse erro ao runtime. Evidências em
extracted/overworld/expansion. O save mantém seu formato e os IDs nativos.
**Limites explícitos:** as quatro novas salas não têm Zora; o catálogo revelou
que a antiga $65 tem essa flag e o port desse inimigo continua pendente.
Entradas de cavernas e segredos das novas salas ainda não têm interação.
Build final e5d139e4 aprovado; diagnostics vazios nas seis fontes centrais
consultadas. Regeneração idempotente em 1.148 arquivos. No build normal, inputs
percorreram título, New Game e a ligação $77→$78; Octorok entrou pela borda e
o inventário abriu na sala nova. Testes usaram memory_fresh; o cartão do usuário
não recebeu gravações. Fixtures restauradas e controle do Studio devolvido.
## Retomada — Zora da sala $65 (09/11/2026)
**Lacuna de conteúdo encerrada:** o encontro extra do atributo A&$08 está em
src/enemies/zora, separado dos Octoroks e da contagem de mortes da sala.
Submersão natural permite novo surgimento; morte bloqueia o ator nessa visita.
Bola de fogo usa mira/tabela angular nativas e exige escudo mágico para bloqueio.
**Produção positiva:** referências PBS e exemplos do projeto bastaram; não
foram consultadas fontes Java. Sete glyphs foram acrescentados ao banco 11,
preservando os anteriores e sem nova scene. O ciclo foi comparado no guest a
388 ticks da rotina 6502; 1.369 pares de distâncias conferiram o cálculo de
ângulo. Sete comparações de assets e doze de composição foram exatas.
Headless permitiu também observar Zora, tiro, Octoroks, inventário e saída da
sala usando Game.frame, com posicionamento inicial isolado para teste.
**Erro de port detectado pelo runtime:** a rotina NES lê Random+$0D, byte
adjacente ao array de 13 bytes. Uma tradução que usou random[13] produziu trap
Bounds em Zora.update, com função e span identificados. O fallback `else 0`
não torna esse índice válido. O byte adjacente foi modelado explicitamente,
sem ampliar indevidamente o array de random nem enfraquecer a checagem.
Esse foi um erro nosso de acesso, não um defeito do runtime. A fixture passou
após a correção. `spawn` e `step` também foram identificados como palavras
reservadas e os nomes da implementação foram corrigidos.
**Limites explícitos:** não se alega equivalência integral de todo o alocador
NES; seis instâncias de Fireball atendem ao encontro atual e respeitam o teto
contabilizado de onze slots com os atores/tiros/drops existentes. Armas ainda
não portadas permanecem fora da validação. Evidência: extracted/zora e docs/zora.md.
Regeneração idempotente em 1.188 arquivos; fixtures restauradas. Nenhuma gravação
no cartão do usuário; testes em memory_fresh. O próximo recorte da lista aceita
é um segredo bombável real, seguido de loja e expansão com objetivo.
Build final dee2921c aprovado; diagnostics vazios em seis fontes consultadas.
Boot e New Game conferidos novamente com entrada de produção restaurada.
## Segredo bombável real da sala $67 (09/11/2026)
**Conteúdo nativo integrado:** tile object $E6 em (112,80), entrada (112,77),
caverna $7B com Moblin e prêmio de 30 rupias. Tipo, preços, texto e quest
foram conferidos nos bytes da ROM. Estado de abertura ($80), coleta ($10) e
mortes baixas permanecem separados no mesmo byte OW103. O NPC/texto/prêmio
permanecem na visita da coleta; na seguinte ficam somente os fogos.
**Composição adequada ao Prometeu:** passagem no terreno e cobertura opaca de
quatro glyphs enquanto fechada; sprites independentes no interior. A parede
segue os offsets das quatro direções de scroll e do submenu. Nenhuma scene
por estado e nenhum slot adicional. A stage interna 10 reutiliza o terreno 1,
mas mantém módulo e colisão próprios. A API is_cave evita registrar visitas
fictícias no histórico de inimigos. Retorno guarda origem/X da entrada.
**Fidelidade:** a abertura imediata usa quatro tiles $24; a reconstrução de
sala usa secundário $0C ($F3/$24 por coluna). Ambos os patterns são pretos,
mas os IDs diferem; wall_fresh mantém a distinção por visita. A máscara de
porta inicial só foi reutilizada após comparar seus 4.352 pixels de suporte
com a geometria da entrada real. O descritor de Moblin precisa do ObjAttr=$81
que SetUpCommonCaveObjects aplica; ler a tabela genérica produz meia figura.
Essas eram decisões/regras do port, não falhas do compositor.
**Verificação:** 121 contatos contra a rotina 6502, oito recortes visuais
exatos, sequência com bomba/fusível/consumo/entrada/crédito/saída/revisita e
commit em cartão descartável. Payload reaberto com checksum válido, bombas=3,
rupias=30 e flags=$91; o cartão padrão do usuário não foi usado. No build normal,
foram testadas a caverna da espada com coleta/saída e a caminhada após Continue
até a caverna secreta já coletada, usando o cartão de teste somente para leitura.
**Lição de fixture:** consultar disponibilidade do save no Init ainda retornava
false nesse ensaio; a leitura foi movida para o primeiro Frame, após MemcardBoot.
As primeiras asserções verdes cobriam o ramo de partida nova e não provavam
reload. A comparação visual detectou a parede fechada e impediu o falso sucesso;
após corrigir a fixture, imagens e checks de flags/moeda/carga passaram.
Não foi necessário alterar o fluxo de produção nem atribuir isso ao runtime.
A regressão de overworld foi reexecutada com draw_objects na fixture: 18
transições, 45 recortes exatos e seis capturas intermediárias exatas da parede
nas ligações da sala norte. As 16.524 sondas nativas e 192 buscas de borda
continuam aprovadas. O instalador da fixture agora usa marcador de instalação
para aceitar novos backups de produção e impedir restauração indevida.
Regeneração idempotente em 1.226 arquivos. Evidências em extracted/real_secret.
Próximo recorte da lista: loja; depois expansão de percurso com objetivo.
Build final dc681b23-7485-4a72-bcfc-7a29f3ac376b aprovado; diagnostics vazios em sete fontes consultadas.
Fixtures removidas/restauradas antes da compilação final; controle devolvido.
### ATR-19 Validação visual nativa e serviço local de automação do Studio
**P2 · Custo recorrente de produção observado; proposta do usuário em 09/11/2026. Não demonstra defeito do runtime.**
**Evidência:** o headless já fornece avanço por frames, captura, identidade da
sessão/build/frame e operações consultáveis. Essas capacidades permitiram
regressões precisas e devem ser preservadas. Entretanto, no fluxo utilizado,
a imagem chega como conteúdo base64 da ferramenta; o agente monta uma chamada
Python para decodificá-la e gravar um PNG, depois executa outros scripts para
recortar regiões, aplicar exclusões e comparar pixels com referências.
Exemplos: `tools/validate_real_secret_captures.py`,
`tools/validate_real_secret_scroll.py` e `tools/validate_overworld_captures.py`.
O último recorte usou oito comparações do segredo, seis de scroll e 45 do
regressor de overworld, com essa infraestrutura externa de imagens.
**Impacto:** repetição de código de transporte, gerenciamento de caminhos,
sequenciamento de captura e comparação; passagem de blobs grandes por chamadas
do agente; mais pontos de falha entre o frame observado e a evidência salva.
O custo aqui é automatizar o ensaio e manipular suas imagens. Isso não significa
que os testes em Python sejam desnecessários ou que o Studio tenha falhado ao
renderizar. Também não foi demonstrado que inexista uma API interna equivalente;
o que faltou no fluxo exposto/utilizado foi uma operação pronta para esse trabalho.
**Direção sugerida:** tratar a automação do Studio como um serviço de backend
local, com contrato público, acessível por HTTP sobre socket local e, se útil,
WebSocket para eventos de progresso/conclusão. HTTP atende comandos, consulta
de jobs e download de artefatos; WebSocket pode reduzir polling, mas não precisa
ser requisito inicial. As ferramentas do agente e a interface do Studio podem
ser clientes desse mesmo serviço. O protocolo sozinho não resolve o atrito:
a capacidade de capturar, comparar e publicar evidências precisa existir nele.
Um primeiro recorte útil seria:
- Avançar até um checkpoint e capturar o frame na mesma operação, vinculando
explicitamente projeto, task, sessão, build e índice lógico do frame.
- Gravar a captura no armazenamento de artefatos do Studio e devolver um
identificador, hash e referência para leitura/download. Servir PNG binário
por HTTP, ou um handle equivalente na ferramenta, evitando obrigar o agente
a transportar e decodificar base64. Base64 pode continuar como alternativa.
- Comparar captura e referência por identificador de artefato ou referência
de arquivo autorizada, com recorte/ROI, máscaras de exclusão e política
explícita para cores/alpha e tolerância. Comparação exata deve estar disponível.
- Retornar resultado estruturado: aprovado/reprovado, dimensões, pixels
comparados/diferentes, erro máximo e caixa das diferenças; publicar imagens
atual, esperada e diff/overlay como artefatos inspecionáveis.
- Executar uma sequência de inputs/checkpoints e gerar relatório por lote,
preservando o transcript para reprodução. Não aprovar baselines novas
automaticamente: atualizá-las deve ser uma ação explícita e revisável.
**Contrato a preservar:** IDs de requisição para recuperar respostas sem repetir
avanços, status consultável, término real do worker em cancelamentos, validade
ou obsolescência da captura e associação exata do resultado ao build/frame.
Reutilizar o controle por projeto/task e a autorização do Studio existentes;
o serviço não deve contornar esses limites nem usar o cartão do usuário como
mídia implícita de teste. As URLs/handles de artefato precisam ter escopo de
acesso e ciclo de vida definidos. Esta é uma proposta de arquitetura, não uma
API que já existe nem uma conclusão de que HTTP seja obrigatório.
**Separação importante:** o Studio pode assumir execução, captura, comparação
genérica e apresentação de resultados. Os oráculos específicos deste port —
extração de assets, interpretação das tabelas e execução delimitada de rotinas
6502 da ROM — continuam externos ou fornecem referências ao serviço. Não embutir
conhecimento de Zelda no runtime nem substituir uma referência independente
pelo mesmo algoritmo que está sendo testado.
**Critério de sucesso proposto:** reproduzir uma comparação de tela, uma ROI de
HUD e um checkpoint no meio do scroll usando somente operações do serviço,
sem script de decodificação base64 ou montagem de diff. O agente receberia um
resumo pequeno e abriria as imagens apenas quando necessário. Um comando de
lote deveria produzir as mesmas evidências verificáveis atualmente mantidas em
`extracted/real_secret`, incluindo falhas e diferenças, com menos infraestrutura
específica no projeto.
## Evidência adicional — loja $66 (09/11/2026)
**Positivo observado:** terreno fixo compartilhado e objetos/texto em sprites
permitiram vendedor piscante, remoção individual de produto, preços persistentes
e rolagem do inventário sem variantes de scene nem novos slots. Foram aprovadas
13 comparações exatas de composição/poses. O save existente preservou uma compra
com débito ainda pendente; reabertura do cartão de teste liquidou a fila sem
alteração de formato. Referências do Studio bastaram para PBS; não foi necessário
consultar Java neste recorte.
**Custo observado:** as capturas e comparações ainda exigiram decodificação local
de base64 e script específico para ROI/exclusões. Consolida a evidência da
proposta ATR-19 acima: comparação estruturada de artefatos no Studio reduziria
essa infraestrutura. Não é defeito visual observado nem confirmação de causa
no runtime. O oráculo das regras e descritores nativos continua externo.
## Evidências do percurso oeste e segunda loja — 09/11/2026
**Positivo / ATR-11:** um struct público `ShopVisit`, importado com construtor
explícito, compartilhou as regras das duas lojas. A loja anterior passou
novamente nos 150 casos; a nova passou em 400 casos, com compra/saída/revisita
via Game.frame. Isso reforça que o erro histórico com Scene não demonstra
inviabilidade geral de structs entre módulos. Sem consulta a Java neste recorte.
**Positivo / ATR-15:** quatro mapas e mais um interior foram integrados sem
novos slots de scene. Inventário passou de 12 para 16 faixas no mesmo banco.
69 comparações do overworld e 12 da loja foram exatas. Terreno fixo, produtos,
texto e vendedor separados dispensaram variantes de scene durante compra.
A regeneração completa preservou os hashes dos fontes/assets conferidos.
**Produção / ATR-08:** o gerador do port deixou buracos 28/29 no HUD ao derivar
índices de IDs de stages que incluem interiores. Pack recusou corretamente
com `Tile bank artifacts must form a contiguous index range starting at 0.`
O gerador foi corrigido, mantendo os índices antigos. Não é defeito do runtime.
No resultado consultado, o texto identificava a classe de asset, sem caminho
explícito do banco; incluir caminho e índices ausentes reduziria a busca manual.
**Produção / ATR-02–03:** a fixture usou `tick<150 && !verify_old(tick)` e
alcançou OldShopOracle.get fora da tabela no tick 150. O runtime forneceu
Bounds, função e span; a guarda foi substituída por if aninhado e toda a
sequência passou. A referência dinâmica consultada descreve avaliação estrita
da esquerda para a direita e ramo de if não selecionado sem execução, mas não
foi localizada nela uma garantia de curto-circuito para &&. Não atribuir causa
a lowering/runtime sem reprodução mínima e contrato explícito. Exemplo de
guarda com chamada e documentação da avaliação booleana evitaria a suposição.
A falha era do harness temporário, não de gameplay nem da interface visual.
**ATR-19:** as 81 comparações exatas deste recorte ainda exigiram captura em
base64, decodificação e comparação local. Mantém-se a proposta de artefatos,
ROI/máscaras e relatório estruturado no Studio; oráculos 6502 continuam externos.
### ATR-20 Watchdog no primeiro advance após reabrir cartão, sem guest fault
**P2 · Uma ocorrência observada; causa e reprodução mínima não confirmadas.**
No build de fixture `49b8a4a0-fe91-4ded-8d64-131420672e2a`, abrir cartão existente
retornou sucesso. O primeiro advance de um frame terminou em
`INFRASTRUCTURE_FAILURE`, `watchdog_expired`, limite 100000 host ticks e zero
frames concluídos. get_state mostrou lógico0, tick3, PC233, paused; get_fault
retornou null e memcard estava resident/running, sem ação requerida.
Após consultar os estados, um novo advance com ID distinto completou exatamente
um frame; os 299 seguintes passaram, com load e débito corretos. Não houve
reexecução cega de um lote já avançado, alteração do payload ou guest trap.
Evidência em `extracted/supply_shop/save-validation.json`. Não concluir que o
save do jogo esteja defeituoso nem que seja o mesmo caso histórico de reset.
Impacto: foi necessário reconciliar manualmente progresso e estado de boot.
Sugestão: incluir fase/bloqueio atual do firmware no diagnóstico do watchdog e
indicar se a sessão pode continuar. Investigar primeiro um caso mínimo de boot
com mídia existente; manter zero frames concluídos explicitamente no resultado.
**ATR-11 / LSP no fechamento deste recorte:** diagnostics retornou
INFRASTRUCTURE_FAILURE em fontes novas e existentes, embora o build final
passasse. ShopVisit falhou na primeira consulta e respondeu vazio na seguinte;
CaveSupplyShop falhou duas vezes; Link e Overworld também falharam. StageFlow
e Stage responderam vazios. Não há evidência suficiente para atribuir a causa
a criação de arquivos novos. Impacto: verificação LSP parcial, mantida como
limitação explícita. O build/pack e os testes runtime forneceram a validação
executável; seria útil preservar o erro interno no resultado da consulta.