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