# 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 `010`, `011` e `017` 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

- agenda `010-input-intrinsics-surface.md` deve considerar input v1 fechado;
- agenda `011-input-frame-semantics-and-portability.md` deve considerar semantica base fechada;
- agenda `017-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`