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

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:

Input.pad().up().hold()

Possivel lowering:

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