# Avançado

Os componentes internos. Se você estiver incorporando Phasis, pode pular esta seção. Se estiver modificando o mecanismo, todas as páginas aqui são essenciais.

## Páginas

- **[Arquitetura](https://phasis.inline0.dev/pt/docs/advanced/architecture)** — como o código-fonte se torna execução: lexer → parser → AST → compilação de bytecode → VM de bytecode com fallback para percurso da árvore. Carregador de módulos, realms e o papel de `Phasis\Engine` como limite do realm.
- **[VM de bytecode](https://phasis.inline0.dev/pt/docs/advanced/bytecode-vm)** — conjunto de opcodes, ciclo de despacho, caches em linha, caminho rápido de transpilação de código-fonte JsToPhp, heurística canSkipEnvAlloc para formas de função e quando as chamadas seguem o caminho de bytecode ou o percurso da árvore.
- **[Benchmarks](https://phasis.inline0.dev/pt/docs/advanced/benchmarks)** — números atuais de `bench/`, como interpretá-los, por que ~100× V8 é o limite estável para interpretadores que percorrem a árvore e o que reduziria essa diferença.
- **[Testes](https://phasis.inline0.dev/pt/docs/advanced/testing)** — o modelo de oráculo. Cada alteração é verificada com três oráculos independentes: Node.js (V8 como referência normativa), test262 e a suíte de igualdade de bytes de bibliotecas populares.

## Convenções para contribuições

- **Não altere o mecanismo principal sem um motivo forte.** Tudo em `src/Runtime/`, `src/Bytecode/`, `src/Lexer/`, `src/Parser/`, `src/Regex/` faz parte do caminho crítico de test262. Alterar esses componentes sem uma verificação test262 correspondente é uma receita para regressões. Os recursos integrados (`src/BuiltIn/`) são mais seguros porque as suítes específicas de test262 para cada recurso detectam problemas localmente.
- **Use traits para organizar, não classes.** Quando um arquivo ultrapassar ~2 mil linhas, divida-o em arquivos trait em um diretório irmão (`src/BuiltIn/Temporal/`, `src/Runtime/Parts/` etc.), em vez de criar novas classes — isso mantém as pesquisas de `self::` funcionando e evita quebrar a superfície de API dos métodos privados.
- **Execute `bin/verify-all` localmente antes de enviar as alterações.** Ele executa PHPStan, PHPCS, todas as suítes PHPUnit (unitária, de oráculo, de bibliotecas populares e wpt) e a regressão do oráculo. A CI executa as suítes WPT e de bibliotecas populares quando há alterações em `src/`; a matriz test262 completa é iniciada manualmente, então teste localmente as categorias test262 afetadas.
- **Para cada adição à Web API, adicione um fixture WPT.** Coloque o `.any.js` de `tests/Wpt/upstream/<area>/` em `tests/Wpt/fixtures/<category>/` e o executor o detectará.

## Veja também

- [Compatibilidade](https://phasis.inline0.dev/pt/docs/compatibility) — como as saídas do oráculo são medidas.
- [CLI referência](https://phasis.inline0.dev/pt/docs/cli) — `bin/phasis`, `bin/test262`, `bin/wpt`.