Referência da linguagem BIA

Esta página é gerada no mesmo build do guia a partir da especificação canônica docs/bia/LANGUAGE_SPEC.md, da versão raiz do compilador e de uma fixture que atravessa o gate real. Se essas fontes divergirem, o build da documentação falha em vez de publicar uma referência stale.

Versões e identidade#

  • Compilador publicado nesta referência: v3.1372.0
  • Versão declarada pela especificação: v3.1372.0
  • Política: compatibilidade por versão exata; mudar a versão cria outro candidato e exige novos checks e receipt.

Estruturas fundamentais#

A BIA é uma linguagem tipada para descrever entidades, DTOs, enums, serviços e regras observáveis. Os tipos primitivos publicados pela especificação são string, int, decimal, float, bool, datetime, uuid, void e Map; Type[] representa coleções.

bia 
entity User {
    string name;
    int age;
}

dto UserOutput {
    string name;
    int age;
}

@post("/users")
service UserOutput createUser(string name, int age) {
    UserOutput output = new UserOutput();
    output.name = name;
    output.age = age;
    return output;
}

Exemplo executável#

O arquivo abaixo é uma cópia byte a byte da fixture canônica validada pelo compilador no gate de release. O teste do site compara o download à fonte e o teste de release o compila novamente; “exemplo” aqui não significa pseudocódigo.

Baixar main.bia

bia 
entity User {
    string name;
    int age;
}

dto UserOutput {
    string name;
    int age;
}

@post("/users")
service UserOutput createUser(string name, int age) {
    UserOutput output = new UserOutput();
    output.name = name;
    output.age = age;
    return output;
}

Política de compatibilidade#

Estado público atual: compatibilidade por versão exata, com corpus retroativo bloqueante.

O source, o artefato e o comprovante de entrega registram a versão do compilador que os produziu. Um candidato só pode ser chamado de verificado quando todos os checks declarados usam essa identidade exata; recompilar com outra versão cria um candidato novo e exige outro receipt.

O que conta como breaking change#

Uma mudança é breaking quando pode alterar um projeto existente em qualquer destes pontos:

  • sintaxe aceita ou significado semântico;
  • tipo, auth, status ou payload de API;
  • bytes/estrutura do backend ou do Sofia gerados;
  • comportamento de runtime, módulo ou stdlib;
  • schema/migração de dados;
  • identidade exigida pelo receipt, deploy ou toolchain.

O número v3.x.y identifica o release do toolchain histórico; ele não autoriza inferir compatibilidade apenas pela semelhança do número. A evidência é o corpus e o receipt.

Regra de evolução#

  1. Uma construção substituída entra em depreciação com diagnóstico, alternativa e documentação antes da remoção.
  2. A remoção precisa de entrada explícita no corpus com migration_required, expressões de diagnóstico estáveis e um guia em docs/bia/migrations/.
  3. Projeto histórico classificado como pass precisa continuar compilando. Uma falha nova, um digest de source inesperado ou uma migração sem o diagnóstico previsto bloqueia o release.
  4. migration_required não significa compatível: significa que o upgrade é recusado de forma conhecida e acionável. O projeto só volta a pass depois de migrado e revalidado.
  5. Mudança de codegen que não quebra o source ainda cria bytes novos. Portanto, passa por F0/F1, canary e novo receipt; nunca reutiliza a prova anterior.
  6. Rollback promove os bytes verificados anteriores. Não recompila source antigo com o compilador novo no caminho de recuperação.

Corpus e gate#

docs/bia/language-compatibility-corpus.json fixa projetos/snapshots reais, versão de origem, commit, digest e resultado esperado. O gate scripts/tests/language-compatibility-corpus-test.mjs:

  • recalcula o digest de todo input relevante;
  • compila cada projeto com o compiler atual;
  • exige sucesso dos casos pass;
  • exige falha e todos os hints de migração dos casos migration_required;
  • falha fechado em resultado, versão, source ou documento divergente.

O corpus inicial cobre projetos introduzidos nas versões v3.379.0, v3.932.0, v3.987.0, v3.1000.0 e a remoção de @html em v3.1222.0. Ele cresce junto com toda nova construção ou breaking change; não é uma amostra escolhida depois da regressão.

Janela pública#

Enquanto o canary progressivo de T8.2.2 não estiver operacional:

  • não existe promessa pública de compatibilidade automática entre versões;
  • projetos permanecem fixados à identidade registrada no receipt;
  • atualizar exige corpus verde, gates aplicáveis e novo receipt;
  • ausência de diagnóstico/evidência bloqueia promoção;
  • nenhuma copy pode prometer compatibilidade além do que o corpus mede.

Quando houver canary real, a janela pública será derivada dos resultados versionados — nunca declarada por intenção.

Fonte completa#

Esta página é a porta de entrada pública e não substitui a especificação completa. A referência publicada preserva o vínculo de versão e exemplos executáveis; o manual canônico continua sendo a fonte normativa usada pelos gates e pelo cérebro do coder.