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

59 KiB
Raw Blame History

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.
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.

| 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.