85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
---
|
|
id: AGD-0004
|
|
ticket: system-fault-semantics-and-control-surface
|
|
title: Agenda - System Fault Semantics and Control Surface
|
|
status: open
|
|
created: 2026-03-27
|
|
resolved:
|
|
decision:
|
|
tags: []
|
|
---
|
|
|
|
# Agenda - System Fault Semantics and Control Surface
|
|
|
|
## Problema
|
|
|
|
O domínio `system` exposto à userland ficou pequeno, e a política de retorno dele ainda não está escrita.
|
|
|
|
Estado em 2026-09-22:
|
|
|
|
- a superfície gerada é só `system.has_cart` (`Syscall::SystemHasCart`), com 1 retorno e capability `SYSTEM`;
|
|
- o dispatch devolve `true` fixo, sem consultar cartucho e sem `status`;
|
|
- `system.run_cart` saiu da ABI de userland. Launch de cartucho é ação de SystemOS/firmware/host (`LSN-0051`, `DSC-0004`);
|
|
- fault de execução da VM já tem forma estruturada em `CrashReport` (`VmTrap`, `VmPanic`, `VmInit`), observada pelo host e pelo debugger.
|
|
|
|
O texto de 2026-03-27 tratava `SystemRunCart` como operação ainda sem efeito e apontava a agenda `009` e `virtual_machine_runtime/dispatch.rs`. Esses dois pontos ficaram obsoletos. A política de fault do que permanece no domínio `system` continua aberta.
|
|
|
|
## Dor
|
|
|
|
- `has_cart` pode permanecer um bool fixo e mascarar ausência, cartucho inválido ou consulta fora de autoridade;
|
|
- uma futura operação de `system` pode herdar `Trap` ou `Panic` onde o contrato transversal pede `status`;
|
|
- automação headless (`AGD-0052`) precisa observar fault estruturado sem que esta agenda redesenhe `CrashReport` nem invente syscall de controle para CI ou agente.
|
|
|
|
## Hotspots Atuais
|
|
|
|
- `crates/console/prometeu-hal/src/syscalls/domains/system.rs`
|
|
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` (`SystemHasCart` retorna `true`)
|
|
- `crates/console/prometeu-system/src/crash_report.rs`
|
|
- `docs/specs/runtime/16a-syscall-policies.md`
|
|
- `discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md`
|
|
|
|
## Alvo da Discussao
|
|
|
|
Fechar a política de fault e retorno do domínio `system` que ainda é visível à userland, e separar essa política da observação de fault de VM feita pelo host.
|
|
|
|
## O Que Precisa Ser Definido
|
|
|
|
1. Queries simples.
|
|
Decidir a política de `has_cart`: bool atual, `status` mais payload, ou outra forma compatível com `16a`. Incluir o que a consulta realmente observa.
|
|
|
|
2. Operações que não voltam para a userland.
|
|
`run_cart` permanece fora da ABI de convidado. Falha de boot direto continua no caminho de host/firmware (`CartridgeError`, `CrashReport::VmInit`, transição de firmware), não como syscall de app.
|
|
|
|
3. Relação com firmware e com o host.
|
|
Delimitar falha de app, falha de firmware e falha de runtime. `CrashReport` é a observação estruturada de Trap/Panic/init. `summary()` e log são apresentação, não o contrato.
|
|
|
|
## Dependencias
|
|
|
|
- `docs/specs/runtime/16a-syscall-policies.md`
|
|
- `LSN-0051` / `DSC-0004`
|
|
- `AGD-0052` / `DSC-0049`, apenas como consumidor da observação estruturada
|
|
|
|
## Critério de Saida Desta Agenda
|
|
|
|
Pode virar decision quando houver definição escrita sobre:
|
|
|
|
- matriz de `status` / `Trap` / `Panic` para as operações userland que o domínio `system` mantém, começando por `has_cart`;
|
|
- confirmação de que launch de cartucho permanece fora da ABI de convidado;
|
|
- fronteira entre retorno operacional de syscall, erro de loader/boot e `CrashReport`.
|
|
|
|
## Revalidação — 2026-09-22
|
|
|
|
Revalidada contra o código atual e contra `AGD-0052`. A agenda permanece aberta. O alvo encolheu: ela não reabre `run_cart`.
|
|
|
|
### O que a direção headless muda
|
|
|
|
`AGD-0052` exige que automação distinga execução em curso, pause, término, `Trap` e `Panic` lendo dados estruturados. Esse requisito observa `CrashReport` e o estado da VM. Ele não altera a semântica normativa de fault de outros domínios e não cria syscall `system` para controle headless.
|
|
|
|
Esta agenda continua dona da matriz de retorno de `system`. A agenda headless continua dona de como o host expõe o fault que já existe.
|
|
|
|
### Perguntas que continuam abertas
|
|
|
|
- [ ] `has_cart` passa a ter `status` e um significado real de presença de cartucho, ou o bool atual é o contrato e o stub `true` é o bug a corrigir em outra discussão?
|
|
- [ ] Alguma falha de boot direto precisa ser visível ao convidado, ou toda falha de launch permanece em host, firmware e `CrashReport`?
|
|
- [ ] Quais campos de `CrashReport` são o contrato observável (`kind`, `pc`, `trap.code`) e quais são só texto de log?
|