add headless automation
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-09-22 13:28:31 +01:00
parent 5b106af0f3
commit e0c08c8b00
15 changed files with 883 additions and 47 deletions
@@ -83,4 +83,36 @@ Pode virar PR quando houver definição escrita de:
- arquivos obrigatórios;
- erros canônicos;
- invariantes de segurança;
- estratégia de testes de compatibilidade entre diretório e pacote.
- estratégia de testes de compatibilidade entre diretório e pacote;
- equivalência observável entre diretório e `.pmc` para qualquer host que use `CartridgeLoader`, incluindo o host desktop e o host headless de `AGD-0052`.
## Revalidação — 2026-09-22
Revalidada contra o código atual e contra `AGD-0052` / `DSC-0049` (Headless Automation Host and Deterministic Runtime Control). A agenda permanece aberta.
### O que permanece
`PackedCartridgeLoader::load` ainda retorna `CartridgeError::InvalidFormat` sem ler o arquivo. O dispatcher continua aceitando a extensão `.pmc` e delegando para esse stub. O loader de diretório é o caminho real: `manifest.json`, `program.pbx` e `assets.pa` quando a capability de asset exige. Boot direto (`BootTarget::Cartridge`) e o host desktop usam esse mesmo `CartridgeLoader`.
O problema original segue válido: a plataforma anuncia dois formatos e só o diretório funciona.
### Efeito da direção headless
`AGD-0052` coloca o host headless como consumidor novo do loader, e deixa o formato `.pmc` fora do primeiro ciclo. O primeiro boot automatizado usa cartucho de diretório, o mesmo artefato que o host desktop já carrega.
Consequências para esta agenda:
- headless, CI e agente não definem o container;
- quando `.pmc` existir, diretório e pacote precisam materializar o mesmo cartucho lógico, para o determinismo não depender da origem dos bytes;
- a ordem física do container continua impedida de alterar o resultado, como o item de segurança e determinismo já pedia;
- esta agenda não absorve captura de framebuffer, replay ou protocolo de automação.
### O que não mudou no critério
Formato, arquivos obrigatórios, erros canônicos, invariantes de segurança e testes de equivalência continuam sendo o fechamento. O critério de saída ganhou só a exigência de que essa equivalência valha para todo host do `CartridgeLoader`.
### Perguntas que continuam abertas
- [ ] O `.pmc` é zip, tar, formato próprio ou envelope com header e blobs?
- [ ] Quais entradas são obrigatórias além das que o loader de diretório já exige?
- [ ] Qual matriz de erro determinística substitui o `InvalidFormat` genérico do stub?
@@ -13,53 +13,72 @@ tags: []
## Problema
O dominio `system` e pequeno, mas mistura consulta simples com superficie de controle de fluxo.
O domínio `system` exposto à userland ficou pequeno, e a política de retorno dele ainda não está escrita.
Hoje:
Estado em 2026-09-22:
- `SystemHasCart` responde diretamente;
- `SystemRunCart` ainda nao tem efeito real;
- a agenda `009` resolve semantica funcional, mas nao fecha por si so a politica de fault do dominio.
- a superfície gerada é só `system.has_cart` (`Syscall::SystemHasCart`), com 1 retorno e capability `SYSTEM`;
- o dispatch devolve `true` fixo, sem consultar cartucho e sem `status`;
- `system.run_cart` saiu da ABI de userland. Launch de cartucho é ação de SystemOS/firmware/host (`LSN-0051`, `DSC-0004`);
- fault de execução da VM já tem forma estruturada em `CrashReport` (`VmTrap`, `VmPanic`, `VmInit`), observada pelo host e pelo debugger.
O texto de 2026-03-27 tratava `SystemRunCart` como operação ainda sem efeito e apontava a agenda `009` e `virtual_machine_runtime/dispatch.rs`. Esses dois pontos ficaram obsoletos. A política de fault do que permanece no domínio `system` continua aberta.
## Dor
- sem uma agenda propria, `system` pode herdar fault semantics por acidente;
- `run_cart` pode acabar consolidando `Panic` ou `Trap` onde deveria existir retorno operacional;
- a fronteira entre falha do app, falha do firmware e falha do runtime fica opaca.
- `has_cart` pode permanecer um bool fixo e mascarar ausência, cartucho inválido ou consulta fora de autoridade;
- uma futura operação de `system` pode herdar `Trap` ou `Panic` onde o contrato transversal pede `status`;
- automação headless (`AGD-0052`) precisa observar fault estruturado sem que esta agenda redesenhe `CrashReport` nem invente syscall de controle para CI ou agente.
## Hotspots Atuais
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L114)
- [system.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/system.rs#L4)
- [009-system-run-cart.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/runtime/agendas/009-system-run-cart.md)
- `crates/console/prometeu-hal/src/syscalls/domains/system.rs`
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` (`SystemHasCart` retorna `true`)
- `crates/console/prometeu-system/src/crash_report.rs`
- `docs/specs/runtime/16a-syscall-policies.md`
- `discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md`
## Alvo da Discussao
Fechar a politica de fault e retorno do dominio `system`.
Fechar a política de fault e retorno do domínio `system` que ainda é visível à userland, e separar essa política da observação de fault de VM feita pelo host.
## O Que Precisa Ser Definido
1. Queries simples.
Decidir a politica de fault para consultas como `has_cart`.
Decidir a política de `has_cart`: bool atual, `status` mais payload, ou outra forma compatível com `16a`. Incluir o que a consulta realmente observa.
2. `run_cart`.
Decidir como falhas operacionais de transicao devem ser expostas:
- `status`;
- `Trap`;
- `Panic`.
2. Operações que não voltam para a userland.
`run_cart` permanece fora da ABI de convidado. Falha de boot direto continua no caminho de host/firmware (`CartridgeError`, `CrashReport::VmInit`, transição de firmware), não como syscall de app.
3. Relacao com firmware.
Delimitar quando a falha pertence ao app, ao firmware ou ao runtime.
3. Relação com firmware e com o host.
Delimitar falha de app, falha de firmware e falha de runtime. `CrashReport` é a observação estruturada de Trap/Panic/init. `summary()` e log são apresentação, não o contrato.
## Dependencias
- `../specs/16a-syscall-policies.md`
- `009-system-run-cart.md`
- `docs/specs/runtime/16a-syscall-policies.md`
- `LSN-0051` / `DSC-0004`
- `AGD-0052` / `DSC-0049`, apenas como consumidor da observação estruturada
## Critério de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
Pode virar decision quando houver definição escrita sobre:
- matriz de `status`/`Trap`/`Panic` para `system`;
- politica de retorno/falha de `run_cart`;
- relacao com firmware e crash surface.
- matriz de `status` / `Trap` / `Panic` para as operações userland que o domínio `system` mantém, começando por `has_cart`;
- confirmação de que launch de cartucho permanece fora da ABI de convidado;
- fronteira entre retorno operacional de syscall, erro de loader/boot e `CrashReport`.
## Revalidação — 2026-09-22
Revalidada contra o código atual e contra `AGD-0052`. A agenda permanece aberta. O alvo encolheu: ela não reabre `run_cart`.
### O que a direção headless muda
`AGD-0052` exige que automação distinga execução em curso, pause, término, `Trap` e `Panic` lendo dados estruturados. Esse requisito observa `CrashReport` e o estado da VM. Ele não altera a semântica normativa de fault de outros domínios e não cria syscall `system` para controle headless.
Esta agenda continua dona da matriz de retorno de `system`. A agenda headless continua dona de como o host expõe o fault que já existe.
### Perguntas que continuam abertas
- [ ] `has_cart` passa a ter `status` e um significado real de presença de cartucho, ou o bool atual é o contrato e o stub `true` é o bug a corrigir em outra discussão?
- [ ] Alguma falha de boot direto precisa ser visível ao convidado, ou toda falha de launch permanece em host, firmware e `CrashReport`?
- [ ] Quais campos de `CrashReport` são o contrato observável (`kind`, `pc`, `trap.code`) e quais são só texto de log?
@@ -50,30 +50,50 @@ Fechar o perfil minimo de random VM-owned em cima do core definido na decisao `0
## Open Questions de Arquitetura
1. v1 aceita apenas modo deterministico por seed ou tambem entropy host?
1. O caminho determinístico aceita só seed explícita. Entropia de host, se um dia existir, é modo separado e fica fora da timeline automatizada?
2. `next` retorna apenas `int` ou precisamos variantes (`u32`, `float`) no mesmo ciclo?
3. precisamos de clone/split de gerador no MVP?
4. destruicao explicita deve ser obrigatoria para certificacao/custo ou opcional?
5. O primeiro oráculo de `AGD-0052` pode provar determinismo com cartucho que não chama random, e qualquer cartucho que chame random espera o fechamento desta agenda?
## Dependencias
- `../decisions/006-vm-owned-stateful-core-contract.md`
- `../virtual-machine/ISA_CORE.md`
- `../specs/16-host-abi-and-syscalls.md`
- `../specs/16a-syscall-policies.md`
- contexto histórico, já aposentado como decisão viva: `discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md` cita `006-vm-owned-stateful-core-contract.md`
- `docs/vm-arch/ISA_CORE.md`
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
- `docs/specs/runtime/16a-syscall-policies.md`
- `AGD-0052` / `DSC-0049`, como consumidor do contrato determinístico
Não há arquivo vivo em `discussion/workflow/decisions/` para a decisão `006`. Esta agenda não trata esse texto como contrato atual.
## Fora de Escopo
- entropy nao deterministica como contrato base;
- PRNGs multiplos no mesmo ciclo de fechamento;
- APIs de colecoes stateful;
- window/app model.
- entropia não determinística como contrato base;
- PRNGs múltiplos no mesmo ciclo de fechamento;
- APIs de coleções stateful;
- window/app model;
- formato persistente de replay. Esta agenda define reprodução em memória: seed explícita mais sequência de `next`. Arquivo, versão e timeline de input ficam para a agenda de replay citada por `AGD-0052`.
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
Pode virar decision quando houver definição escrita sobre:
- surface minima de random VM-owned;
- contrato de determinismo/replay;
- surface mínima de random VM-owned;
- contrato de determinismo: seed explícita, ausência de entropia implícita de host, reprodução da sequência;
- fault/status de random;
- IDs/versionamento e validacoes de verifier para as operacoes do dominio.
- IDs/versionamento e validações de verifier para as operações do domínio;
- o que um host automatizado precisa fixar (seeds iniciais) para que duas execuções coincidam.
## Revalidação — 2026-09-22
Revalidada contra o código atual e contra `AGD-0052`. A agenda permanece aberta. Não existe serviço de random na VM. O scheduler declara ausência de randomness. `prometeu-test-support` oferece `StdRng` semeado para testes Rust; isso não é random de convidado.
### Efeito da direção headless
`AGD-0052` diz que random VM-owned usado em execução automatizada obedece ao contrato desta agenda, e que entropia implícita do host não entra no caminho determinístico. Isso reforça a pergunta 1 na direção de seed explícita como único modo determinístico.
O primeiro teste end-to-end headless pode usar um cartucho que não chama random. Esse teste prova input, frame e fault. Ele não prova random. Cartucho cujo resultado depende de random só serve como oráculo depois que esta agenda fechar seeds, sequência e faults.
Relógio de parede em telemetria (`host_cpu_time_us`, timestamp de certificação) não é fonte de random e não entra neste contrato.
Replay em arquivo continua fora daqui e fora do primeiro ciclo headless. O que esta agenda precisa deixar pronto é a reprodução em memória da sequência a partir das seeds.
@@ -107,7 +107,7 @@ O caminho recomendado e:
- [ ] Handheld Linux exige controles/gamepad, fullscreen, scaling, latency, sleep/resume, framebuffer/display mode ou packaging especificos desde o primeiro corte?
- [ ] Qual e o "Linux base" minimo que um futuro hardware DIY precisaria expor para rodar o host portatil sem fork?
- [ ] Android customizado deve ser criterio de escolha entre SDL2 e SDL3 agora, ou deve ficar como compatibilidade futura?
- [ ] Como validar input e pacing de forma automatizada sem depender de janela real em CI?
- [ ] Como validar input e pacing de forma automatizada sem depender de janela real em CI? Encaminhada para `AGD-0052` / `DSC-0049`: o host headless é o lugar dessa prova. Esta agenda continua dona da escolha de backend portátil, não do controle determinístico.
- [ ] O nome do crate deve ser `prometeu-host-desktop-sdl`, `prometeu-host-desktop-sdl2`, ou algo neutro a versao?
## Criterio para Encerrar
@@ -135,4 +135,6 @@ Clarificacao: "mobile" nesta agenda nao se refere primariamente a telefone/table
Clarificacao: a agenda tambem deve preservar a opcao de um futuro hardware DIY. A premissa desejada e que, se esse hardware expuser um Linux base suficiente, o runtime ja tenha um host portatil pronto para rodar nele.
Atualizacao 2026-09-22: `AGD-0052` abre um terceiro host, headless, para teste, CI e controle determinístico em memória. Esse host não substitui o candidato portátil desta agenda e não escolhe SDL. A pergunta de validar input e pacing sem janela em CI passa a ser respondida lá. Extração de loop comum entre winit, SDL e headless continua esperando duplicação real.
## Resolution