clean up

docs/runtime/agendas/001-vm-owned-builtins-protocol-and-system-services.md

@@ -2,9 +2,11 @@
 
 ## Escopo Ja Fechado (Nao Reabrir)
 
-Input VM-owned v1 ja foi fechado na decisao abaixo e saiu desta agenda:
+Input VM-owned v1 ja foi fechado nas specs abaixo e saiu desta agenda:
 
-- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
+- `../specs/06-input-peripheral.md`
+- `../specs/16-host-abi-and-syscalls.md`
+- `../specs/16a-syscall-policies.md`
 
 ## Problema Desta Agenda
 
@@ -81,8 +83,7 @@ Definir um protocolo canonico de recursos VM-owned stateful, preservando:
 - `../specs/16-host-abi-and-syscalls.md`
 - `../specs/16a-syscall-policies.md`
 - `../decisions/003-vm-owned-byte-transfer-protocol.md`
-- `../decisions/004-host-fault-taxonomy.md`
-- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
+- `../specs/06-input-peripheral.md`
 
 ## Fora de Escopo
 

docs/runtime/agendas/002-filesystem-surface-and-semantics.md

@@ -77,7 +77,7 @@ Definir a superficie canonica do dominio `fs` no runtime, separando claramente:
 ## Dependencias
 
 - `../decisions/003-vm-owned-byte-transfer-protocol.md` para transporte de bytes;
-- `../decisions/004-host-fault-taxonomy.md` para shape de erro;
+- `../specs/16a-syscall-policies.md` para shape de erro/fault;
 - specs de portabilidade para alinhamento com sandbox logico.
 
 ## Fora de Escopo

docs/runtime/agendas/003-filesystem-fault-semantics.md

@@ -5,13 +5,13 @@
 O dominio `fs` certamente precisara de politica de fault propria, mas ainda depende de duas discussoes anteriores:
 
 - a decisao `003` sobre transporte de bytes;
-- a agenda `009` sobre superficie e semantica funcional de filesystem.
+- a agenda `002` sobre superficie e semantica funcional de filesystem.
 
 Discutir fault semantics antes disso tende a cristalizar classificacao em cima de uma API que ainda pode mudar.
 
 ## Alvo da Discussao
 
-Fechar a politica de fault de `fs` somente depois da agenda `009`.
+Fechar a politica de fault de `fs` somente depois da agenda `002`.
 
 ## O Que Precisa Ser Definido
 
@@ -31,12 +31,12 @@ Fechar a politica de fault de `fs` somente depois da agenda `009`.
 ## Dependencias
 
 - `../decisions/003-vm-owned-byte-transfer-protocol.md`
-- `../decisions/004-host-fault-taxonomy.md`
+- `../specs/16a-syscall-policies.md`
 - `002-filesystem-surface-and-semantics.md`
 
 ## Regra de Sequenciamento
 
-Esta agenda nao deve ser discutida antes da `009`.
+Esta agenda nao deve ser discutida antes da `002`.
 
 ## Critério de Saida Desta Agenda
 

docs/runtime/agendas/004-gfx-fault-semantics-and-command-contract.md

@@ -51,7 +51,7 @@ Fixar a politica de fault de `gfx` como dominio de comando.
 
 ## Dependencias
 
-- `../decisions/004-host-fault-taxonomy.md`
+- `../specs/16a-syscall-policies.md`
 
 ## Critério de Saida Desta Agenda
 

docs/runtime/agendas/005-audio-fault-semantics-and-surface.md

@@ -51,7 +51,7 @@ Fechar a politica de fault e surface de `audio` para o MVP.
 
 ## Dependencias
 
-- `../decisions/004-host-fault-taxonomy.md`
+- `../specs/16a-syscall-policies.md`
 - spec de audio
 
 ## Critério de Saida Desta Agenda

docs/runtime/agendas/006-asset-fault-semantics-and-surface.md

@@ -11,7 +11,7 @@ Exemplo atual:
 Ao mesmo tempo:
 
 - `AssetStatus` ja expoe um status numerico do dominio;
-- a decisao `004` ja aponta `asset` como dominio `status-first`;
+- a spec `16a` ja aponta direcao `status-first` para falhas operacionais;
 - a decisao `003` reforca a preferencia por status quando existir contrato funcional recuperavel.
 
 ## Dor
@@ -60,7 +60,7 @@ Fechar a taxonomia de fault e, se necessario, ajustar a surface publica de `asse
 
 ## Dependencias
 
-- `../decisions/004-host-fault-taxonomy.md`
+- `../specs/16a-syscall-policies.md`
 
 ## Critério de Saida Desta Agenda
 

docs/runtime/agendas/010-system-fault-semantics-and-control-surface.md

@@ -42,7 +42,7 @@ Fechar a politica de fault e retorno do dominio `system`.
 
 ## Dependencias
 
-- `../decisions/004-host-fault-taxonomy.md`
+- `../specs/16a-syscall-policies.md`
 - `009-system-run-cart.md`
 
 ## Critério de Saida Desta Agenda

docs/runtime/agendas/README.md

@@ -40,23 +40,23 @@ Justificativa curta:
 
 - `001` vem primeiro para fechar o protocolo VM-owned stateful que destrava extensoes como random/window resources sem mexer em syscall host-backed.
 - `002` e `003` ficam na sequencia para fechar `fs` com superficie e fault semantics consistentes.
-- `004`, `005` e `006` consolidam fault semantics por dominio com base na decisao `004`.
+- `004`, `005` e `006` consolidam fault semantics por dominio com base em `16a`.
 - `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
 - `008` e importante, mas nao bloqueia bytecode/backend agora.
 - `009` e `010` ficam no fim porque `run_cart` nao e objetivo do ciclo atual.
 
 Dependências principais:
 
-- `001` deve alinhar com `16`/`16a`, alem das decisoes `003`, `004` e `005`
-- `002` depende das decisoes `003` e `004`
-- `003` depende das decisoes `003`, `004` e da `002`
-- `004` depende da decisao `004`
-- `005` depende da decisao `004`
-- `006` depende da decisao `004`
+- `001` deve alinhar com `06`, `16` e `16a`, alem da decisao `003`
+- `002` depende da decisao `003` e de `16a`
+- `003` depende da decisao `003`, de `16a` e da `002`
+- `004` depende de `16a`
+- `005` depende de `16a`
+- `006` depende de `16a`
 - `007` depende da estabilizacao minima das agendas de superficie/fault por dominio
 - `008` depende de contrato fechado de `13-cartridge.md` + comportamento equivalente ao loader de diretorio
-- `009` depende das decisoes `003`, `004`, `005` e deve alinhar com `002` quando usar `fs`
-- `010` depende da decisao `004` e da `009`
+- `009` depende da decisao `003`, de `16a` e de `06`, e deve alinhar com `002` quando usar `fs`
+- `010` depende de `16a` e da `009`
 
 Regra de uso:
 

docs/runtime/decisions/004-host-fault-taxonomy.md

@@ -1,151 +0,0 @@
-# Decision Record - Host Fault Taxonomy
-
-## Status
-
-Accepted
-
-## Contexto
-
-A fronteira host-backed do runtime misturava quatro coisas diferentes:
-
-- fault recuperavel de servico;
-- quebra terminal do app/VM;
-- falha estrutural grave do runtime;
-- indisponibilidade do host.
-
-Ao mesmo tempo, a decisao `003-vm-owned-byte-transfer-protocol.md` ja fixou uma direcao importante:
-
-- quando existir contrato funcional de retorno, o protocolo deve preferir `status`;
-- `Trap` nao deve ser usado para carregar erro operacional comum;
-- `Panic` deve ficar restrito a inconsistencia interna.
-
-O codigo atual ainda revela severidade errada em varios pontos, por exemplo:
-
-- `AssetLoad` promovendo erro operacional para `Panic`;
-- helpers de extracao promovendo argumento ausente para `Panic`;
-- `VmFault::Unavailable` sendo degradado para `Panic` no loop da VM.
-
-## Decisao
-
-### 1. Classes canonicas
-
-A taxonomia canonica na fronteira host-backed passa a ser:
-
-- `status`
-- `Trap`
-- `Panic`
-
-`Unavailable` deixa de ser classe desejada do modelo.
-
-### 2. `status`
-
-- `status` representa fault recuperavel do servico.
-- Cada dominio pode ter seus proprios codigos/status.
-- Nao sera criado enum global unico de status para todos os dominios.
-- Quando a surface da operacao comportar retorno funcional, deve-se preferir `status` ao maximo.
-
-Exemplos:
-
-- recurso ausente;
-- handle desconhecido de dominio;
-- path nao encontrado;
-- permissao negada;
-- EOF;
-- escrita parcial/falha operacional;
-- indisponibilidade funcional recuperavel.
-
-### 3. `Trap`
-
-- `Trap` quebra a VM/app atual.
-- O firmware assume a partir da tela de crash.
-- `Trap` deve ser usado para erro estrutural de chamada, uso incorreto da ABI ou contrato que o guest nao recupera em runtime.
-
-Exemplos:
-
-- tipo de argumento errado;
-- aridade invalida;
-- syscall ou intrinsic invalido;
-- capability ausente;
-- shape de chamada impossivel para a ABI.
-
-### 4. `Panic`
-
-- `Panic` representa falha estrutural grave do runtime.
-- `Panic` nao descreve erro do app, e sim risco de quebra do proprio Prometeu/runtime/host integration.
-- `Panic` fica reservado para bug interno ou inconsistencia de implementacao.
-
-Exemplos:
-
-- metadata incoerente;
-- mismatch entre `ret_slots` declarados e retorno efetivo;
-- invariantes internas quebradas;
-- branch impossivel do runtime.
-
-### 5. `Unavailable`
-
-- `Unavailable` torna-se candidato a remocao do modelo.
-- A direcao aceita e:
-  - indisponibilidade funcional recuperavel deve virar `status`;
-  - colapso estrutural de integracao host/runtime deve virar `Panic`;
-  - `Unavailable` nao deve ser expandido para novos dominios.
-
-## Aplicacao por Dominio
-
-### Assets
-
-- `assets` e dominio `status-first`.
-- `AssetLoad` nao deve promover erro operacional comum para `Panic`.
-- `AssetStatus` confirma que o dominio ja tem semantica de status.
-- `commit`/`cancel` podem precisar de surface mais rica para evitar `Panic` indevido.
-
-### Audio
-
-- `audio` e dominio command-driven.
-- A direcao aceita e `Trap` estrutural + no-op/fallback deterministico ou `status` quando a surface passar a expor isso.
-- `audio` nao deve ser `panic-first`.
-
-### Gfx
-
-- `gfx` e dominio command-style.
-- A direcao aceita e `Trap` para erro estrutural de chamada e no-op/fallback/clamp para casos de dominio, conforme a semantica de cada comando.
-- `Panic` em `gfx` deve ficar restrito a colapso estrutural do runtime grafico.
-
-### System
-
-- `system` deve evitar `Panic` para falhas funcionais normais.
-- A taxonomia final de `run_cart` depende da agenda `009-system-run-cart.md`.
-
-### Byte transfer
-
-Para `read`/`write` e ops que reutilizem a decisao `003`:
-
-- erros observaveis do protocolo devem virar `status`;
-- `Trap` praticamente sai da jogada;
-- `Panic` fica restrito a inconsistencia interna.
-
-## Consequencias
-
-### Positivas
-
-- o runtime separa erro recuperavel de colapso terminal;
-- dominios host-backed ficam livres para usar `HostReturn` de forma rica;
-- `Panic` encolhe e passa a carregar gravidade real;
-- crash reports e telemetria ficam semanticamente melhores.
-
-### Custos
-
-- algumas surfaces publicas podem precisar mudar para devolver `status`;
-- o uso atual de `VmFault` precisara de limpeza por dominio;
-- o loop da VM precisara deixar de tratar `Unavailable` como caminho normal.
-
-## Follow-up Obrigatorio
-
-As seguintes agendas derivam desta decisao:
-
-- `006-asset-fault-semantics-and-surface.md`
-- `005-audio-fault-semantics-and-surface.md`
-- `004-gfx-fault-semantics-and-command-contract.md`
-- `010-system-fault-semantics-and-control-surface.md`
-- `003-filesystem-fault-semantics.md`
-
-`003-filesystem-fault-semantics.md` so deve ser discutida depois da `002-filesystem-surface-and-semantics.md`.

docs/runtime/decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md

@@ -1,114 +0,0 @@
-# Decision Record - V1 VM-Owned Input Intrinsics and Language-Agnostic Surface
-
-## Status
-
-Accepted
-
-## Contexto
-
-Para destravar bytecode/backend no v1, precisamos fechar o caminho de input sem:
-
-- quebrar a fronteira host-backed atual (`HOSTCALL`/`SYSCALL`);
-- copiar estruturas grandes de input na stack a cada consulta;
-- acoplar a decisao a uma unica linguagem de frontend.
-
-As discussoes das agendas historicas de input (intrinsics surface + frame semantics) e da agenda VM-owned convergiram para:
-
-- input deve sair do caminho de syscall legado;
-- input deve ser VM-owned, leitura-only e deterministico por frame;
-- a linguagem pode expor API encadeada ergonomica (ex.: PBS), mas isso nao define o contrato normativo do runtime.
-
-## Decisao
-
-### 1. Fronteira host-backed permanece inalterada
-
-- `HOSTCALL` + tabela `SYSC` + `SYSCALL` continuam como caminho host-backed oficial.
-- Esta decisao nao unifica nem altera o contrato de syscall atual.
-
-### 2. Input v1 e VM-owned por intrinsics finais
-
-- Input v1 e exposto por intrinsics VM-owned.
-- O backend emite `INTRINSIC <id_final>` diretamente.
-- Nao sera introduzida tabela de pre-load adicional para VM-owned no v1.
-
-### 3. Surface de linguagem e livre (nao hardcoded)
-
-- O contrato normativo e de VM/bytecode, nao de sintaxe de uma linguagem.
-- Frontends podem expor APIs diferentes, desde que mapeiem 1:1 para intrinsics versionados.
-- Exemplo PBS (nao normativo): `Input.pad().up().hold()`.
-
-### 4. Semantica de snapshot por frame
-
-- O host captura estado de input no inicio do frame logico.
-- A VM usa esse snapshot congelado durante todo o frame.
-- Leitura repetida no mesmo frame retorna o mesmo valor observavel.
-
-### 5. Modelo de dispositivos v1
-
-- Elementos obrigatorios de input em todas as plataformas: `button`, `pad`, `touch`.
-- Perfil Prometeu handheld v1: um `pad` e um `touch` single-point.
-- `touch` preserva ultimo valor conhecido (incluindo arraste) conforme snapshot vigente.
-
-### 6. Politica de acesso e fault
-
-- Input e leitura-only para userland.
-- Nao ha capability gate nem impacto de certificacao para leitura de input.
-- Falhas operacionais devem seguir a taxonomia de fault vigente (`status` quando aplicavel; `Trap` para erro estrutural).
-
-### 7. Consequencia de arquitetura imediata
-
-- Builtins de input devem ser tratados como referencias/superficies VM-owned, sem copia "mastodonte" por chamada.
-- O executor de intrinsic atual pode atender casos read-only de snapshot no v1.
-- Casos stateful com alocacao/lifecycle (ex.: RNG com instancia, mapas VM-owned, window resources) ficam para agenda posterior.
-
-## Exemplo de Mapeamento (Ilustrativo, nao normativo)
-
-Objetivo da linguagem:
-
-```text
-Input.pad().up().hold()
-```
-
-Possivel lowering:
-
-```text
-INTRINSIC input.pad@1
-INTRINSIC input.pad.up@1
-INTRINSIC input.button.hold@1
-```
-
-Os nomes acima sao apenas ilustrativos; o contrato real e o ID/versionamento canonico do intrinsic definido pelo toolchain/runtime.
-
-## Consequencias
-
-### Positivas
-
-- destrava o fechamento do bytecode para backend no v1;
-- elimina dependencia de syscall para consulta de input;
-- preserva compatibilidade da infraestrutura host-backed existente;
-- evita acoplamento prematuro a uma unica linguagem.
-
-### Custos
-
-- exige registry de intrinsics VM-owned consistente entre FE/backend/runtime;
-- exige disciplina de versionamento 1:1 por operacao;
-- adia para etapa posterior o protocolo stateful completo com `HeapRef`.
-
-## Fora de Escopo
-
-- protocolo generico VM-owned stateful com lifecycle de recursos;
-- random com instancia alocada e ownership explicito;
-- window system/app model completo;
-- redesign de `HOSTCALL`/`SYSCALL`.
-
-## Follow-up Obrigatorio
-
-- as agendas historicas de input (`010-input-intrinsics-surface.md` e `011-input-frame-semantics-and-portability.md`) foram encerradas e seu conteudo foi absorvido por esta decisao;
-- agenda `001-vm-owned-builtins-protocol-and-system-services.md` fica restrita a pos-v1 (stateful/`HeapRef`).
-
-Specs a alinhar/confirmar:
-
-- `../virtual-machine/ISA_CORE.md`
-- `../specs/16-host-abi-and-syscalls.md`
-- `../specs/06-input-peripheral.md`
-- `../specs/07-touch-peripheral.md`

docs/runtime/decisions/README.md

@@ -14,8 +14,15 @@ Regra de uso:
 - decision records existem para registrar o que foi decidido;
 - quando uma agenda for resolvida, ela deve sair de `agendas/` e virar decision record aqui.
 
-Decisoes atuais:
+Decisoes ativas:
 
 - `003-vm-owned-byte-transfer-protocol.md`
-- `004-host-fault-taxonomy.md`
-- `005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
+
+Decisoes aposentadas que ja viraram spec:
+
+- `004-host-fault-taxonomy.md` -> `../specs/16a-syscall-policies.md`
+- `005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md` -> `../specs/06-input-peripheral.md`, `../specs/16-host-abi-and-syscalls.md`, `../specs/16a-syscall-policies.md`
+
+Racional historico (nao normativo):
+
+- `../learn/retired-decisions-004-005-history.md`

docs/runtime/learn/README.md

@@ -20,6 +20,7 @@ Ela existe para explicar o modelo mental da fantasy handheld, suas influências,
 - [`observability-and-debugging.md`](observability-and-debugging.md)
 - [`portability-and-cross-platform.md`](portability-and-cross-platform.md)
 - [`time-model-and-cycles.md`](time-model-and-cycles.md)
+- [`retired-decisions-004-005-history.md`](retired-decisions-004-005-history.md)
 
 ## Rules
 

docs/runtime/learn/retired-decisions-004-005-history.md

@@ -0,0 +1,37 @@
+# Retired Decisions 004-005 (Historical Notes)
+
+This file keeps historical rationale from decisions that were retired after being absorbed by specs.
+
+Status: pedagogical / historical (not normative).
+
+## Mapping
+
+- Retired `004-host-fault-taxonomy.md`
+  - Canonical source now: `../specs/16a-syscall-policies.md`
+- Retired `005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
+  - Canonical sources now:
+    - `../specs/06-input-peripheral.md`
+    - `../specs/16-host-abi-and-syscalls.md`
+    - `../specs/16a-syscall-policies.md`
+
+## Historical Rationale Snapshot
+
+### 1) Why input left syscall path in v1
+
+- repeated input reads through syscall would force large value transport;
+- deterministic frame snapshot works better as VM-owned intrinsic surface;
+- frontend syntax should stay language-specific while VM contract stays language-agnostic.
+
+### 2) Why fault taxonomy was tightened
+
+- operational domain outcomes should be returned as `status`;
+- `Trap` should represent structural ABI misuse from guest side;
+- `Panic` should represent runtime invariant break;
+- broad `Unavailable` usage was causing severity ambiguity.
+
+## Practical Outcome
+
+- Input is VM-owned and deterministic per logical frame.
+- Host-backed syscall ABI remains structurally stable.
+- Domain agendas now anchor fault discussions on spec `16a`, not on retired decisions.
+

docs/runtime/specs/16a-syscall-policies.md

@@ -23,6 +23,16 @@ The VM faults when contract rules are violated, for example:
 
 These are not ordinary domain statuses.
 
+Faults are split into two runtime classes:
+
+- `Trap`: guest-visible structural violation (ABI misuse / invalid call shape).
+- `Panic`: runtime invariant break (internal inconsistency).
+
+`Unavailable` is not a canonical fault class in this policy model.
+
+- operational unavailability should be represented as `status`;
+- structural host/runtime collapse should be treated as `Panic`.
+
 ### Status returns
 
 Normal operational conditions should be represented as values in return slots.