Aplicações Ruby descritas como um grafo verificável.

O Vetra é um framework web em desenvolvimento para Ruby 4 e PostgreSQL. Entidades, comandos, consultas, permissões e eventos formam um modelo explícito da aplicação: o Grafo da Aplicação.

Esse modelo permite conferir contratos, dependências e regras declarativas, identificar inconsistências e revisar mudanças de arquitetura junto com o código.

Estado atual: protótipo da fase 0. O repositório entrega um compilador experimental, ferramentas de validação, diff e vinculação de implementações. A execução dos comandos de negócio, o servidor web e a persistência ainda não existem. Veja a situação do projeto para acompanhar entregas, pendências e evidências.

O compilador transforma declarações Ruby em uma representação intermediária (IR) versionada, gravada em .vetra/graph.json. O artefato usa JSON canônico, inclui hashes dos fontes e faz parte da revisão no Git.

flowchart LR
    A["DSL Ruby"] --> B["IR 0.4 validada"]
    B --> C["Diff arquitetural"]
    B --> D["Vinculação Ruby"]

O guia da fase 0 detalha o DSL suportado e o alcance da análise estática dos blocos Ruby.

Use Ruby 4.0.9, conforme .ruby-version, e Bundler. A compilação dos exemplos e a suíte do compilador funcionam sem um banco de dados. As sondas de PostgreSQL têm requisitos próprios, descritos nos ADRs.

Na raiz do repositório:

bundle install
bundle exec bin/vetra graph:build --root examples/blog
bundle exec bin/vetra graph:check --root examples/blog
bundle exec bin/vetra graph:validate --root examples/blog --sources
bundle exec bin/vetra graph:link --root examples/blog

O build grava examples/blog/.vetra/graph.json. O check compara esse arquivo com os fontes; o link confere o pacote e associa as implementações aos blocos declarados. Essas etapas não iniciam um servidor nem executam o comando publish_post.

Para comparar o grafo atual com o que está no último commit:

bundle exec bin/vetra graph:diff git:HEAD examples/blog/.vetra/graph.json --root examples/blog

Este é o comando de publicação do exemplo de blog. Sua entidade e suas políticas estão em post.rb e roles.rb.

# app/domains/blog/publish_post.rb
command :publish_post do
  input :post_id, :id
  returns :post
  authorize :update, :post, record: :post_id
  uses :posts, :clock
  emits "blog.post.published", with: %i[id]

  call do |input, posts, clock|
    post = posts.lock!(input.post_id)
    fail! :status, "só rascunhos podem ser publicados" unless post.status == "draft"
    posts.update!(post, status: "published", published_at: clock.now)
  end

  expose http: "POST /posts/:post_id/publish"
end

uses declara as capacidades recebidas pelo bloco. returns identifica o contrato de saída; authorize registra a ação e o registro a autorizar; emits declara o evento. A exposição HTTP aponta para essa mesma operação. O compilador registra e verifica essas relações; a execução depende do futuro motor de operações.

Os diretórios contêm recortes compiláveis da fase 0. Autenticação, telas, persistência e entrega em tempo real continuam pendentes. Troque --root examples/blog pelo diretório desejado para inspecionar outro exemplo.

As árvores “Estrutura em Vetra” dos PDFs descrevem a organização prevista para as aplicações, com pastas resumidas e alguns componentes gerados omitidos. Elas incluem funcionalidades futuras; o conteúdo disponível para compilar hoje está nos diretórios acima.

A base definida nos ADRs reúne quatro componentes:

1. Grafo da Aplicação: modelo compilado e versionado, implementado parcialmente nesta fase.
2. Motor de operações: comandos e consultas com contratos, autorização e adaptadores para cada superfície.
3. Motor de autorização: execução das políticas e dos escopos declarados no grafo.
4. Vetra Data: persistência com Sequel e PostgreSQL, isolamento de linhas (RLS) e contexto assinado.

Sobre essa base, o projeto prevê consultas reativas, workflows duráveis, recursos de privacidade e auditoria, UI e operações MCP com identidade delegada. A adoção planejada começa em aplicações Rails existentes, um domínio por vez. A integração com Rails também está pendente. Ruby::Box e execução com Ractors são extensões opcionais; o compilador atual funciona sem elas.

O próximo trabalho está detalhado na situação do projeto. A matriz de aceitação da fase 0 registra as evidências e os critérios ainda parciais.

Execute a suíte completa com a verificação de cobertura dos códigos de diagnóstico:

bundle exec rake test:diagnostics

Essa também é a tarefa padrão de bundle exec rake. A CI verifica os testes, os artefatos dos exemplos, a vinculação e o diff arquitetural em PRs e pushes na main, além das sondas de banco no PostgreSQL 17 e 18. As mudanças entram direto na main, sem PR; o fluxo de integração descreve o gate que roda antes do push e o registro de quebras intencionais por digest.

Ao alterar o modelo de um exemplo, reconstrua seu grafo com graph:build, revise o graph:diff e inclua o artefato atualizado na mudança. Acrescente casos de erro às novas regras e mantenha a documentação e a situação do projeto coerentes com o código. O guia da fase 0 explica o DSL suportado e os limites da análise.

O ADR-001 define o contrato do grafo, e o ADR-016 define o ciclo de vida das operações.

Os PDFs preservam a proposta e suas revisões; os ADRs registram as decisões posteriores:

• Proposta técnica.
• Comparações com Rails: Mini CRM, Blog e Chat.
• Histórico de revisões e pendências da rodada 7.

MIT. A governança do projeto ainda está em aberto (veja as questões em aberto na proposta).