Colocando o SDK em Dia Antes que Pudesse Se Desviar

Paridade construída no início de um projeto custa mil vezes menos que paridade retrofitada depois que ele já foi lançado. Os bindings da RakuAI são co-desenvolvidos com o runtime, controlados em cada PR - para que sua escolha de binding nunca te tranque fora de uma funcionalidade depois.

Já nervoso com um modo de falha específico que vi matar projetos multi-repositório antes, e esse era o estado inicial deste sábado de manhã. O runtime adiciona uma funcionalidade em um fim de semana e o SDK não se atualiza até o mês seguinte. Os exemplos em um binding funcionam e os exemplos no outro binding regridem silenciosamente. Os números de versão param de bater. A CI em cada repositório está verde e a integração entre eles está quebrada.

Esse filme termina com uma reconstrução de plataforma dois anos depois. Não estou construindo a Raku desse jeito. O plano para este fim de semana era colocar o SDK em dia com o runtime antes que a lacuna pudesse se formar, e deixar infraestrutura suficiente para que a lacuna nunca pudesse se formar de novo.

O que entrou do lado do SDK

O SDK teve um grande fim de semana. O lado do runtime ficou mais quieto (a maior parte do seu grande empurrão aconteceu no fim de semana anterior com o PR #104 trazendo VIO/SLAM, o Escalonador de QoS, o Harness de Performance, e o pipeline de telemetria). Este foi o fim de semana de colocar os bindings em dia.

Destaques:

• SDK v0.2.0 com paridade Unity + Unreal, com validação abrangente
• Exemplos HelloAR nos dois bindings, com demonstrações explícitas de failover
• Interações aprimoradas do exemplo Unity com suporte a múltiplos objetos e tutoriais interativos
• Documentação de API do Unreal aprimorada com exemplos de uso abrangentes
• Workflow de Agent-Queue Seeder portado para o repositório do SDK
• Pipeline de CI/CD para publicação do pacote SDK v0.2 com versionamento semântico e automação de release
• Documentação e guia rápido do SDK v0.2 com página inicial do repositório e integração de wiki
• Epic #42: Infraestrutura de Teste de Paridade entre SDK e Runtime concluída

O trabalho do Epic #42 é o destaque. É um conjunto de testes que exercita os dois bindings contra os mesmos cenários canônicos e confirma que se comportam da mesma forma. Unity HelloAR e Unreal HelloAR carregam um modelo cada, ancoram-no a um marcador, renderizam-no, e reportam telemetria. O teste de paridade confirma que a telemetria que os dois bindings reportam está dentro da tolerância, e que o mesmo modelo carrega corretamente nos dois. Se uma mudança no runtime alguma vez quebrar um binding sem quebrar o outro, o teste de paridade pega isso.

Por que teste de paridade importa nesta fase

O SDK da Raku ainda não está sendo lançado. Não há release público. Estamos a meses de qualquer pessoa fora do time escrever código contra isso. Então por que se importar com paridade agora?

Porque teste de paridade construído no início de um projeto custa mil vezes menos do que teste de paridade retrofitado em um projeto que já foi lançado. Toda API C nova que o runtime adiciona é exercitada através dos dois bindings no dia um. Todo PR que toca a superfície pública precisa ou mostrar que o teste de paridade ainda passa ou explicar por que não passa. O custo é alguns minutos por PR. A economia é meses de triagem rio abaixo quando um parceiro reporta um problema que só se reproduz no Unreal e o time tem que descobrir por quê.

A outra razão é que teste de paridade revela problemas arquiteturais. Quando uma funcionalidade é fácil de expor na Unity e difícil na Unreal, o problema geralmente não está nos bindings. Está na API C do runtime. A assimetria é um sinal. Neste fim de semana os testes de paridade revelaram duas assimetrias assim, e a correção nos dois casos foi mudar a superfície de API do runtime em vez de contornar a assimetria em um dos bindings.

Como funciona o fluxo de trabalho de dois fluxos

O padrão ao qual cheguei para desenvolvimento multi-repositório com agentes:

Uma fila de agente por repositório. O runtime tem sua própria fila de issues, o SDK tem sua própria fila de issues, a documentação tem a sua própria. Cada agente trabalha dentro do seu repositório. Nenhum agente único tenta abranger a costura entre dois repositórios em um único PR.

Coordenação entre repositórios no nível da issue. Quando uma funcionalidade requer mudanças nos dois repositórios, duas issues acopladas são registradas ao mesmo tempo, com referências cruzadas. O PR do runtime entra primeiro. O PR do SDK fica retido até o PR do runtime ser mesclado. Então o PR do SDK é atualizado contra o novo build do runtime, re-testado, e mesclado em questão de horas.

Um conjunto canônico de exemplos em cada binding. Unity HelloAR e Unreal HelloAR são os veículos de teste canônicos. Toda mudança na API C precisa ser exercitada nos dois. Os exemplos não são pensamentos tardios. São parte da superfície pública.

Testes de paridade como gate de CI. A infraestrutura de teste de paridade que entrou neste fim de semana como Epic #42 agora roda em todo PR que toca qualquer um dos repositórios. Se uma mudança no runtime não exercita os dois bindings, o PR fica bloqueado de mesclar até que o teste de paridade demonstre que a mudança funciona nos dois lados.

O que isso viabiliza para construtores

Se você é um desenvolvedor Unity pensando em construir sobre a Raku eventualmente, o binding está sendo co-desenvolvido com o runtime, não perseguindo-o depois. A API Unity não vai ficar atrasada. Os exemplos vão funcionar hoje e vão funcionar na versão 1.0.

Se você é um desenvolvedor Unreal, o mesmo é verdade. O binding Unreal tem prioridade idêntica ao de Unity. Os testes de paridade provam isso.

Se você está decidindo com qual binding começar, a resposta é aquele que combina com as habilidades já existentes do seu time. O teste de paridade é o que me permite prometer que a escolha de binding não vai te trancar fora de funcionalidades depois.

Se você é um parceiro pensando em como este motor se integra à sua stack, a superfície vai ser API C mais binding Unity mais binding Unreal mais eventualmente mais alguns (Godot está no roadmap, web-nativo está no roadmap). Cada novo binding precisa entregar seus próprios testes de paridade contra o conjunto canônico antes de ser lançado. A disciplina já vem embutida.

Honesto sobre o que ainda está rústico

Os testes de paridade cobrem o básico. Ancoragem baseada em marcador funciona nos dois bindings. HelloAR carrega e renderiza nos dois. A telemetria reporta corretamente nos dois. As questões de paridade mais difíceis, rastreamento completo de mãos, pipeline de voz, sincronização de pose multiplayer, essas ainda não têm teste de paridade porque o lado do runtime não está pronto. Vão entrar sob o mesmo gate quando estiverem.

O pipeline de CI para publicação do SDK v0.2 está no ar, mas o pacote publicado de verdade ainda não está estável o suficiente para recomendar integração contra ele. Trate o SDK como em desenvolvimento até outubro. Em novembro os testes de paridade vão estar profundos o suficiente para que a recomendação seja diferente.

O que eu quero lembrar deste fim de semana

Duas coisas.

Paridade multi-repositório é uma disciplina, não uma funcionalidade. O fim de semana em que o SDK se atualizou com o runtime é um fim de semana sem nenhuma funcionalidade nova e brilhante no runtime. Nada demonstrável aconteceu. O que aconteceu foi que o SDK deixou de ficar atrasado. Esse é o tipo de trabalho que, negligenciado, mata um projeto multi-repositório. Quero registrar isso para não esquecer quando a próxima grande funcionalidade do runtime chegar.

A fila de agente escala por repositório. Rodar uma única fila abrangendo os dois repositórios no mesmo workflow produziu uma versão inicial da bagunça de conflito de merge que descrevi no fim de semana passado no nível do runtime. Separar as filas por repositório eliminou quase toda ela. Os agentes param de tropeçar um no outro quando seus espaços de problema são adequadamente esculpidos.

Sábado à noite, o SDK e o runtime estão em paridade. Grande fim de semana. O tipo certo de fim de semana.