Especificação

Documento normativo do AI Parlance (v0.1). Define gramática, semântica, builtins, políticas e níveis de estabilidade dos blocos. Visão geral: Introdução. Sintaxe: Sintaxe.

Glossário

Termo	Significado
AI Parlance	Linguagem declarativa AI-first usada como IR entre intenção e código gerado.
Bloco	Construção de topo (`entity`, `workflow`, …).
Transpilador	Gerador que converte AI Parlance (+ AST) em artefatos de um alvo (Go, SQL, …).
AST	Árvore sintática produzida pelo parser a partir do texto `.aip`.
Builtin	Função ou comando reservado (`now()`, `notify()`, …).
Predicado	Expressão booleana em `policy` (`authenticated`, `role(admin)`, …).

Escopo e limites

AI Parlance cobre hoje:

modelagem de dados e API (CRUD)
autorização declarativa
workflows e eventos de domínio limitados

Não substitui:

UI custom ou design system
algoritmos complexos ou otimizações manuais
integrações ad hoc sem bloco dedicado
SQL imperativo escrito à mão (bloco custom reservado para o futuro; fora do v0.1)

Ferramenta	Foco	AI Parlance
OpenAPI / AsyncAPI	Contratos HTTP / eventos	Modelo + comportamento + policy numa spec
Prisma / DBML	Schema de dados	Entidades + relações + migrations multi-target
OPA / Cedar	Autorização	`policy` integrada ao modelo de entidades
Temporal / Cadence	Orquestração imperativa	`workflow` declarativo para regras comuns

Pipeline

Prompt ou edição humana
↓
Texto .aip
↓
Parser → AST
↓
Validador semântico
↓
Transpiladores (por alvo)
↓
Go, SQL, OpenAPI, workers, …

O texto .aip é a fonte; a AST é representação interna. Ferramentas de referência (v0.1): parser, validador v0.1 completo (Core + Infra + Security + Behavior) e emitters em prévia na matriz (aip parse / aip validate / aip emit …) estão no monorepo. Este documento é a fonte normativa em prosa; gramática em spec/v0.1/grammar.ebnf e marcos em ROADMAP.md.

Bloco `app` obrigatório

Toda spec v0.1 deve começar com exatamente um bloco app (recomendado @0.1):

app MinhaApp @0.1 {
  database postgres
}

Inclua auth ao usar authenticated, role ou permission em policy. Exemplo mínimo: examples/minimal.aip.

Gramática (EBNF resumida)

Gramática normativa completa: spec/v0.1/grammar.ebnf. Resumo:

program        = app_block , { block } ;
block          = entity_block | crud_stmt | policy_block
               | index_block | api_block | workflow_block | event_block
               | lifecycle_block | seed_block | job_block | queue_block
               | ai_context_block | validation_block ;

app_block      = "app" IDENT [ "@" version ] "{" { app_member } "}" ;
entity_block   = "entity" IDENT "{" { field_decl | entity_modifier } "}" ;
field_decl     = IDENT ":" type_expr [ field_modifier { field_modifier } ] ;
crud_stmt      = "crud" IDENT ;
workflow_block = "workflow" IDENT "{" when_clause { stmt } "}" ;
when_clause    = "when" IDENT "." lifecycle_event ;

Exatamente um app_block é obrigatório e deve aparecer primeiro. Ordem de modificadores: required | optional → unique → default(...). Comentários de linha: // até o fim da linha.

Níveis de estabilidade

Nível	Blocos	Status v0.1
Core	`app`, `entity`, `crud`, validação inline e bloco `validation`; tipos `enum(…)` inline; relações `belongs_to` inline	Estável
Infra	`index`, `api`, migrations, `seed`, naming; modificadores `timestamps`, `soft_delete` em `entity`	Estável
Security	`auth` (em `app`), `policy`, predicados	Beta
Behavior	`workflow`, `event`, `lifecycle`, `job`, `queue`, `ai_context`; statements em workflow (`emit`, `create`, …)	Beta

Blocos de topo enum { } / relation { } e has_one / has_many / many_to_many estão no roadmap, não no v0.1. Blocos beta podem mudar entre releases v0.x menores. O Core é estável dentro do v0.1; a linguagem permanece rascunho (ferramentas de referência em prévia no monorepo — ainda não é v1.0 congelada). Ver ROADMAP.

Campos implícitos

Toda entity recebe automaticamente (salvo id: uuid explícito):

Campo	Tipo	Notas
`id`	`uuid`	Primary key
`created_at`	`datetime`	Sempre injetado (padrão Core)
`updated_at`	`datetime`	Sempre injetado (padrão Core)

O modificador timestamps em entity é documentação opcional; não desativa esses campos. soft_delete em entity adiciona deleted_at: datetime optional.

Builtins

Nome	Uso	Efeito
`now()`	expressões	Data/hora UTC atual
`available_seller()`	workflow	Retorna `User` seller disponível
`assign`	`assign Lead.seller seller`	Atribui FK / relação
`notify(recipient, message)`	workflow	Notificação; `recipient` é variável `User`, campo ou literal
`LeadExists(phone)`	condição	Duplicidade por telefone normalizado
`normalize_phone(value)`	expressão	Normaliza telefone
`emit EventName { … }`	workflow	Publica evento de domínio
`create Entity { … }`	workflow	Cria registro da entidade
`reject "msg"`	workflow	Erro de negócio
`dispatch JobName`	workflow	Enfileira job

Builtins não listados são inválidos.

Ciclo de vida

Eventos de sistema (gatilhos de when):

created | updated | deleted

lifecycle Lead {
  on created -> workflow LeadReceived
  before create {
    normalize_phone(Lead.phone)
  }
  after update {
    notify(Lead.seller, "Lead atualizado")
  }
}

when Lead.created em workflow equivale a on created em lifecycle. Prefira lifecycle com vários ganchos na mesma entidade.

Statements de workflow (v0.1)

Dentro de workflow / ganchos de lifecycle: var, if / reject, assign, create, emit, notify, dispatch (opcional after + duração). Durações: 15m, 1h, 1d — ver Workflows. Referências forward são válidas: emit e create podem usar event / entity declarados depois no arquivo.

Políticas

Predicado	Significado
`public`	Sem autenticação
`authenticated`	JWT/sessão válida
`role(name)`	Papel global
`permission(name)`	Permissão concedida
`owner(field)`	Usuário autenticado igual a `field`
`owner_or_manager(field)`	`owner` ou `role(manager)` ou `role(admin)`

policy Lead {
  read owner_or_manager(Lead.seller)
}

Requer Lead.seller como belongs_to User.

Acesso padrão

Entidades sem policy: transpiladores devem usar authenticated no CRUD quando app tem auth, ou public sem auth. policy explícita prevalece.

Propostos (fora da gramática v0.1)

Declaração top-level permission nome
Blocos endpoint para rate limit por rota

Preview em Segurança até entrarem na gramática.

Validação

O validador deve rejeitar:

ausência ou duplicata do bloco app
referência a entity / event / job inexistente
policy sem auth no app quando usar authenticated ou role
owner(field) com campo inexistente
workflow sem when
modificadores duplicados ou fora de ordem (warning vs error por regra)
builtins não registrados

Matriz de transpiladores

Alvo	Artefatos	Status v0.1
PostgreSQL	DDL, índices, seeds, migrations init up/down	Prévia (`aip emit sql`)
MySQL	DDL, índices, seeds	Prévia (`aip emit mysql`)
Go	structs, handlers, stubs de middleware JWT	Prévia (`aip emit go`)
TypeScript	interfaces, Zod, CRUD em memória	Prévia (`aip emit typescript`)
Python	models / dataclasses MVP	Prévia (`aip emit python`)
PHP	classes MVP	Prévia (`aip emit php`)
OpenAPI	paths, schemas, security de policy	Prévia (`aip emit openapi`)
Docs	Markdown / referência API	Prévia (`aip emit docs`)
Testes	fixtures CRUD	Prévia (`aip emit tests`)
Workers	filas, jobs	Prévia (`aip emit workers`)

Custo de inferência LLM incide na edição do .aip, não na transpilação offline.

Specs de referência

Arquivo	Papel
examples/minimal.aip	Spec Core mínima válida
examples/crm-reference.aip	CRM (policy, API, workflow)
examples/ops-reference.aip	Extras Infra + Behavior (`seed`, `lifecycle`, `job`, …)

Capítulos de domínio (Banco, Segurança, Workflows) documentam extensões em relação a este arquivo.

Visão geral

Exemplos

Emitters

Referência

Domínios

IA

Especificação

Especificação

Glossário

Escopo e limites

Pipeline

Bloco `app` obrigatório

Gramática (EBNF resumida)

Níveis de estabilidade

Campos implícitos

Builtins

Ciclo de vida

Statements de workflow (v0.1)

Políticas

Acesso padrão

Propostos (fora da gramática v0.1)

Validação

Matriz de transpiladores

Specs de referência

​Especificação

​Glossário

​Escopo e limites

​Pipeline

​Bloco app obrigatório

​Gramática (EBNF resumida)

​Níveis de estabilidade

​Campos implícitos

​Builtins

​Ciclo de vida

​Statements de workflow (v0.1)

​Políticas

​Acesso padrão

​Propostos (fora da gramática v0.1)

​Validação

​Matriz de transpiladores

​Specs de referência

Especificação

Glossário

Escopo e limites

Pipeline

Bloco `app` obrigatório

Gramática (EBNF resumida)

Níveis de estabilidade

Campos implícitos

Builtins

Ciclo de vida

Statements de workflow (v0.1)

Políticas

Acesso padrão

Propostos (fora da gramática v0.1)

Validação

Matriz de transpiladores

Specs de referência