diff --git a/docs/runtime/agendas/001-vm-owned-builtins-protocol-and-system-services.md b/docs/runtime/agendas/001-vm-owned-builtins-protocol-and-system-services.md index d6ab38f8..20fef1f0 100644 --- a/docs/runtime/agendas/001-vm-owned-builtins-protocol-and-system-services.md +++ b/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 diff --git a/docs/runtime/agendas/002-filesystem-surface-and-semantics.md b/docs/runtime/agendas/002-filesystem-surface-and-semantics.md index 02e44c84..42a33a5e 100644 --- a/docs/runtime/agendas/002-filesystem-surface-and-semantics.md +++ b/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 diff --git a/docs/runtime/agendas/003-filesystem-fault-semantics.md b/docs/runtime/agendas/003-filesystem-fault-semantics.md index f8f4aebc..711be0b6 100644 --- a/docs/runtime/agendas/003-filesystem-fault-semantics.md +++ b/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 diff --git a/docs/runtime/agendas/004-gfx-fault-semantics-and-command-contract.md b/docs/runtime/agendas/004-gfx-fault-semantics-and-command-contract.md index aba98cb2..dd32dd73 100644 --- a/docs/runtime/agendas/004-gfx-fault-semantics-and-command-contract.md +++ b/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 diff --git a/docs/runtime/agendas/005-audio-fault-semantics-and-surface.md b/docs/runtime/agendas/005-audio-fault-semantics-and-surface.md index 5bebafcb..2cfd18fe 100644 --- a/docs/runtime/agendas/005-audio-fault-semantics-and-surface.md +++ b/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 diff --git a/docs/runtime/agendas/006-asset-fault-semantics-and-surface.md b/docs/runtime/agendas/006-asset-fault-semantics-and-surface.md index 58eb1979..7b4d90fe 100644 --- a/docs/runtime/agendas/006-asset-fault-semantics-and-surface.md +++ b/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 diff --git a/docs/runtime/agendas/010-system-fault-semantics-and-control-surface.md b/docs/runtime/agendas/010-system-fault-semantics-and-control-surface.md index 51044931..ca4df76d 100644 --- a/docs/runtime/agendas/010-system-fault-semantics-and-control-surface.md +++ b/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 diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 7a31a55f..de39bd53 100644 --- a/docs/runtime/agendas/README.md +++ b/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: diff --git a/docs/runtime/decisions/004-host-fault-taxonomy.md b/docs/runtime/decisions/004-host-fault-taxonomy.md deleted file mode 100644 index d25bbb94..00000000 --- a/docs/runtime/decisions/004-host-fault-taxonomy.md +++ /dev/null @@ -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`. diff --git a/docs/runtime/decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md b/docs/runtime/decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md deleted file mode 100644 index 787c5147..00000000 --- a/docs/runtime/decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md +++ /dev/null @@ -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 ` 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` diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md index 59976e06..16f4102f 100644 --- a/docs/runtime/decisions/README.md +++ b/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` diff --git a/docs/runtime/learn/README.md b/docs/runtime/learn/README.md index 3653a8fa..4be68e06 100644 --- a/docs/runtime/learn/README.md +++ b/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 diff --git a/docs/runtime/learn/retired-decisions-004-005-history.md b/docs/runtime/learn/retired-decisions-004-005-history.md new file mode 100644 index 00000000..c030cd48 --- /dev/null +++ b/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. + diff --git a/docs/runtime/specs/16a-syscall-policies.md b/docs/runtime/specs/16a-syscall-policies.md index e2501d0b..62e4782c 100644 --- a/docs/runtime/specs/16a-syscall-policies.md +++ b/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.