mxrb 0.1.3 → 0.1.4

data/docs/pt-BR/runtime-ruby.md

@@ -0,0 +1,108 @@
+# Runtime sem Java
+
+O modo Ruby executa o backend sem iniciar o Mendix Runtime Java. Ao abrir uma
+aplicação exportada, o MXRB migra automaticamente um banco SQLite por ambiente,
+abre o interpretador de microflows, registra lifecycle hooks, aplica segurança e
+inicia os scheduled events.
+
+```text
+config/environments/
+├── development.env
+├── qa.env
+├── staging.env
+└── production.env
+```
+
+A precedência é `ENV do processo > config/environments/<ambiente>.env >
+.env.<ambiente> > .env`. Selecione o perfil com `--environment qa` ou
+`MXRB_ENV=qa`. `mxrb env . --environment qa` lista somente nomes de chaves e
+fontes; valores nunca são impressos.
+
+```bash
+mxrb run . --environment qa
+mxrb test App.mpr smoke.rb --native --environment qa
+```
+
+Cada perfil usa, por padrão, `.mxrb/runtime/<ambiente>.sqlite3`. O schema deriva
+de entidades, atributos, associações e system members; mudanças aditivas são
+aplicadas de forma idempotente e mudanças incompatíveis usam rebuild
+transacional. Entidades não persistentes continuam somente em memória.
+
+A API Ruby oferece login e tokens bearer, sessão, schema, navigation, pages,
+microflows, CRUD e published REST. Regras de página/microflow, access rules de
+entidade, direitos por member e o subconjunto seguro de XPath são verificados em
+cada requisição. Credenciais vêm de `MXRB_USERS_JSON` e `MXRB_AUTH_TOKENS`; use
+arquivos locais ignorados pelo Git ou o secret manager do deployment.
+
+Scheduled events usam o scheduler stdlib do MXRB, com intervalos de minuto,
+hora e dia, prevenção de overlap e encerramento supervisionado. Falhas ficam
+disponíveis no scheduler e não derrubam silenciosamente o servidor. Zonas IANA,
+como `America/Boa_Vista`, usam `tzinfo`, inclusive nas transições de horário de
+verão. Zonas desconhecidas geram erro em vez de cair silenciosamente para UTC;
+`UTC`, `local` e offsets numéricos como `-04:00` também são aceitos.
+
+Sessões e coordenação do scheduler usam por padrão o SQLite nativo compartilhado
+`.mxrb/runtime/<ambiente>-shared.sqlite3`, sem serviço externo. Múltiplas
+instâncias devem apontar `MXRB_SHARED_STORE_PATH` para o mesmo arquivo. Claims
+idempotentes por evento/janela e leases de sobreposição renovados por heartbeat
+são atômicos; um claim inacabado pode ser retomado após a expiração. O lease
+padrão é de 300 segundos e pode ser alterado com `MXRB_SCHEDULER_LEASE_TTL`.
+Use `:memory:`, `memory` ou `local` para ativar explicitamente o modo por processo.
+
+Java Custom Actions não iniciam uma JVM. Cada ação permitida deve ter um adapter
+Ruby explícito, registrado pelo nome qualificado em `config/adapters.rb`:
+
+```ruby
+Mxrb::RubyApp::Registry.register_java_custom_action('Pedidos.CalcularTotal') do |arguments|
+  Calculador.call(
+    itens: arguments.fetch('Itens'),
+    desconto: arguments.fetch('Desconto')
+  )
+end
+```
+
+As chaves são os nomes dos parâmetros no modelo Mendix. Valores básicos são
+avaliados no contexto do microflow; referências de entidade, microflow e
+mappings são entregues como nomes qualificados. O retorno alimenta a variável
+de resultado apenas quando `UseReturnVariable` está ativo (ou no formato legado
+que declara somente `ResultVariableName`). Uma ação sem registro falha fechado
+com seu nome e a instrução de registro; não há descoberta de classes, execução
+de JAR nem fallback para a JVM. REST, app services, SOAP, mappings e geração de
+documentos continuam usando os adapters Ruby por tipo. O frontend permanece
+JavaScript/React no navegador, servido pelo backend Ruby sem Runtime Java.
+
+## Certificação Ruby → Mendix → Ruby
+
+O cenário reproduzível de certificação fica em
+[`spec/fixtures/flymetothemoon/project.rb`](../../spec/fixtures/flymetothemoon/project.rb).
+Ele modela em Ruby clientes, produtos, pedidos e itens, incluindo enumeração,
+índices, associações, microflows, nanoflow, scheduled event e uma página com
+data grid. O teste
+[`spec/flymetothemoon_roundtrip_spec.rb`](../../spec/flymetothemoon_roundtrip_spec.rb)
+verifica estes casos de uso:
+
+- gerar e validar um MPR Mendix 11.12.1 a partir da DSL Ruby;
+- exportar pelo CLI real com `--mode ruby --flymetothemoon`;
+- garantir que o preset contenha Sinatra, Puma, ActiveRecord e RSpec, sem
+  arquivos Java, JAR ou bytecode;
+- executar criação, contagem, decisão, CRUD e metadados de página no Runtime
+  Ruby com SQLite;
+- recompilar sem alterações e comparar o MPR estruturalmente com a origem;
+- adicionar um atributo e substituir um microflow por Ruby idiomático;
+- exportar novamente e provar que código Ruby e modelo Mendix sobrevivem a um
+  segundo round-trip estruturalmente idêntico.
+
+Execute o caso isolado com:
+
+```bash
+bundle exec rspec spec/flymetothemoon_roundtrip_spec.rb
+```
+
+Para interfaces geradas, o cenário declarativo
+[`spec/fixtures/frontend_browser/sudoku_full_flow.json`](../../spec/fixtures/frontend_browser/sudoku_full_flow.json)
+é executado pelo runner `script/frontend_browser_acceptance` em Chromium real.
+Ele cobre as posições 73 e 74 do tabuleiro, seleção, preenchimento e troca entre
+Easy, Medium e Hard. Cada clique crítico aguarda a cadeia POST do microflow + GET
+da associação e deve concluir em até 250 ms. A consulta da galeria é filtrada no
+SQLite pelo contexto; objetos carregados pela associação inversa preservam o
+vínculo quando somente atributos são salvos.

data/docs/pt-BR/runtime-schema-migrations.md

@@ -0,0 +1,40 @@
+# Migrações do schema do runtime Ruby
+
+`Mxrb::Runtime::SchemaMigrator` identifica entidades, atributos e associações pelo GUID de
+armazenamento Mendix. Renomear um artefato mantendo o GUID preserva a tabela ou coluna e os
+dados existentes.
+
+## Política segura
+
+- Criação de tabela e adição de atributo opcional são automáticas e idempotentes.
+- Atributos `required` são criados como `NOT NULL`.
+- Tornar um atributo existente obrigatório reconstrói a tabela dentro de uma transação. Se
+  houver `NULL`, a migração usa o valor default declarado; sem default, ela é recusada.
+- Adicionar um atributo obrigatório a uma tabela populada exige default. Em tabela vazia, a
+  migração pode reconstruir o schema sem backfill.
+- Alterações compatíveis preservam os dados e as linhas das associações.
+- Remover entidade, atributo ou associação é considerado destrutivo. Por padrão a migração
+  lança `Mxrb::Runtime::UnsafeSchemaMigrationError`, com os itens em `error.changes`, e não
+  altera o banco.
+- Depois de backup e revisão do plano, a limpeza pode ser autorizada explicitamente com
+  `allow_destructive: true`. Somente tabelas e colunas registradas nos metadados do MXRB são
+  removidas; tabelas externas não são inferidas nem apagadas.
+
+Aplicações Ruby exportadas mantêm essa opção desligada. Para uma execução controlada após o
+backup, configure `MXRB_ALLOW_DESTRUCTIVE_MIGRATIONS=true` no perfil de ambiente. Qualquer
+outro valor, inclusive variável ausente, mantém o modo fail-closed.
+
+```ruby
+database = SQLite3::Database.new('runtime.sqlite3')
+migrator = Mxrb::Runtime::SchemaMigrator.new(
+  project,
+  database: database,
+  allow_destructive: true
+)
+result = migrator.migrate!
+puts migrator.migration_plan.changes
+```
+
+DDL, cópia de dados, atualização dos metadados e limpeza destrutiva pertencem à mesma
+transação SQLite. Qualquer violação de `NOT NULL`, unicidade ou outro erro reverte a migração
+inteira.

data/docs/pt-BR/validation-matrix.md

@@ -2,7 +2,7 @@
 
 **Português** · [English](../en-US/validation-matrix.md) · [Deutsch](../de-DE/validation-matrix.md)
 
-Última atualização: 5 de agosto de 2026.
+Última atualização: 11 de agosto de 2026.
 
 O pipeline validado é:
 
@@ -21,6 +21,22 @@ Os originais nunca são modificados.
 | TreeviewDemo | 5.21.4 | v1 | passou |
 | GridViewPlayground | 6.10.8 | v1 | passou |
 
+Em 11 de agosto, `script/validate_matrix` repetiu a matriz com **6/6 passes**:
+1.506 units, 1.734 artefatos e 3.388 referências em 16,381 s.
+
+## Inventário adicional local
+
+`script/certify_mprs --cycles 2 --repair-hashes` certificou outros sete MPRs
+em 14 roundtrips consecutivos: **7/7 passes**, 2.799 units, 3.238 artefatos e
+4.819 referências. Foram cobertos LearnNow, SLATaskApp, SLATaskAppNative,
+MyFirstModule, CourseManager, RubyBridgeSandbox e VetClinic.
+
+SLATaskApp tinha um hash de conteúdo obsoleto e RubyBridgeSandbox tinha dois.
+O gate reparou somente `Unit.ContentsHash` em cópias temporárias, registrou os
+UUIDs alterados e preservou os bytes BSON originais. Os arquivos-fonte não
+foram modificados. O segundo roundtrip também detectou e corrigiu tipos de
+widgets nativos desserializados como strings.
+
 ## Cobertura profunda editável
 
 O comparador cobre metadados, segurança, árvore de units, entidades, access
@@ -55,6 +71,27 @@ todo metamodelo Mendix. Encodings `.mxunit` desconhecidos são rejeitados em vez
 de adivinhados. A validação exata do 5.21 em Studio Pro/Windows continua sendo
 um limite explícito.
 
+## Certificação de widgets
+
+`script/certify_widgets --browser-report REPORT.json App.mpr` é o gate para
+widgets do compilador web nativo e Marketplace realmente usados. Ele exige,
+em conjunto:
+
+- compilação sem fallback de todas as páginas e layouts web;
+- resolução de cada ID pluggable para um `.mjs` dentro de MPK, com SHA-256;
+- materialização do modelo e build Rspack nativo da versão Mendix;
+- relatório Chromium aprovado, sem exceção/fallback visível, declarando todos
+  os IDs e tipos de widget exercitados pelo cenário.
+
+Importar um MPK ou concluir o bundle isoladamente não certifica comportamento.
+Widgets que exigem datasource, atributo ou posição específica — por exemplo,
+filtros dentro de Data Grid/Gallery — só passam quando o cenário os exercita
+nesse contexto válido. Pacotes futuros ou ainda não exercitados falham como
+evidência ausente, em vez de herdarem uma promessa genérica de compatibilidade.
+O frontend React/TypeScript de `--mode ruby` tem uma trilha separada: seu
+relatório Chromium certifica os widgets sem afirmar que os componentes
+pluggable equivalentes também passaram no Runtime Mendix.
+
 ## Índice semântico
 
 Os seis MPRs produziram **1.778 artefatos** e **3.387 referências**. Consultas
@@ -63,9 +100,9 @@ sem MDL.
 
 ## Avaliações, cobertura e runtime
 
-- 1.039 exemplos, zero falhas;
-- 100% das linhas: 17.224/17.224;
-- 100% dos branches: 6.811/6.811;
+- 1.329 exemplos, zero falhas;
+- 100% das linhas: 23.771/23.771;
+- 100% dos branches: 9.704/9.704;
 - avaliação Sudoku: 7/7 checks;
 - testes funcionais Sudoku: 3/3 localmente em 34,16 s;
 - testes funcionais Sudoku: 3/3 no Docker em 39,52 s.
@@ -80,7 +117,7 @@ e logout real. Os scaffolds `page --chain` também materializam e passam
 preflight nos três caminhos suportados; `page --template` foi exercitado em
 Runtime para dashboard e formulário vertical com CSS computado auditado.
 
-`script/validate_matrix` repetiu os seis round-trips, 1.506 units, em 14,760 s.
+`script/validate_matrix` repetiu os seis round-trips, 1.506 units, em 16,381 s.
 `script/benchmark` mediu o pipeline Sudoku completo em 6,8463 s. O fuzzing
 determinístico cobre 250 documentos BSON aninhados e 50 arquivos `.mxunit`
 atômicos, inclusive valores binários.