TANGEUL — Regras Escritas em Markdown, Auditadas por Humanos

Imagem: gerada por IA

O toulmin calcula contratos. As regras são funções Go, as exceções são declaradas como um grafo de derrota (defeat graph), e um h-Categoriser transforma o grafo em um veredicto. O problema é que a pessoa que de fato precisa auditar o contrato normalmente não sabe ler Go.

Um contador auditando uma política de crédito. Um dono de pequeno negócio verificando uma regra de controle de acesso. Um funcionário de banco revisando a lógica de compensação de uma transferência. Nenhum deles consegue olhar para func(ctx Context, specs Specs) (bool, any) e dizer “sim, isto está correto”. Por mais sólida que seja a matemática do motor, se o leitor não sabe ler o código, a auditoria é teatro.

A IA escreve, um humano lê

TANGL (Toulmin Amgoud Nute Graph Language) fecha essa lacuna. Você escreve frases em markdown, e essas frases são o código executável.

## tangl:Cases
- in case of `can access`
  - `user` is required
  - `authenticate` is a general rule
  - `block ip` is a counter rule using `policy`.`IsIPBlocked` with `blocklist`
  - don't `authenticate` when `block ip`
  - do `policy`.`Allow` when `authenticate`

Estas cinco linhas são o grafo toulmin inteiro — Rule, Counter, Attacks e a aresta de execução. Não há uma etapa de compilação separada em que o autor precise pensar: a cadeia de ferramentas tangl analisa este markdown diretamente para *ast.Document, e validate/effects/gen rodam sobre ele sem alteração. O autor é uma IA, o verificador é uma pessoa — essa assimetria é o ponto central. A IA só precisa seguir uma gramática canônica estrita; o humano só precisa ler uma frase em seu próprio idioma.

Uma semântica, muitas superfícies

A semântica do TANGL é definida uma única vez, na gramática em inglês: a dualidade Evaluate/Run, once (idempotência de tick), undo (compensação), timing de cascata, ordem de execução determinística. Qualquer edição por localidade — coreano, ou qualquer que venha a seguir — não redefine nada disso. Ela apenas troca a tabela de palavras-chave e ordem das palavras que fica por cima do mesmo AST. Uma frase em coreano mapeia 1:1 para uma frase em inglês, e ambas analisam para o nó de AST idêntico.

Isso não é uma camada de tradução aparafusada por conveniência — é estrutural. Os leitores reais do TANGL na Coreia são auditores não desenvolvedores: 소상공인, 세무사. Palavras-chave em inglês como don't X when Y ou is a general rule não permitem que um não desenvolvedor confirme “sim, isto se lê corretamente”. Se o leitor é coreano, a superfície precisa ser coreana para que a auditoria de fato funcione — e o inverso vale simetricamente para leitores de inglês.

Construir a edição coreana revelou algo não óbvio a partir da gramática em inglês sozinha: a ordem SOV do coreano não é um fardo de tradução, é um encaixe melhor para regras condicionais. `Y`면 `X` 실행한다 (aproximadamente, “quando Y, faça X”) se lê de forma mais natural que do X when Y em coreano — condição primeiro, predicado por último é simplesmente como o idioma é estruturado desde o início. A política de partículas do coreano leva isso ainda mais longe: partículas (은/는/이/가/을/를 …) são tokens opcionais que o lexer descarta, mas a forma canônica escrita pela IA sempre as inclui de qualquer maneira — para o leitor humano, não para o parser. Como a IA é a única autora, o parser nunca tem de aceitar ordem livre de palavras ou variação falada; ele só tem de analisar uma forma canônica. Essa assimetria é o que torna tratável uma superfície de linguagem natural não trivial.

Sete seções

Subject → See → Definitions → Rules → Cases → Provides → Internal

Cada construção só é válida em sua própria seção — a mesma disciplina de escopo que qualquer edição por localidade herda sem alteração. As instruções se leem como frases completas que nomeiam seu próprio tipo: is a general rule, don't ... when, do ... once when, undo ... when, run ... when.

Exemplo: um robô de café

Veja como a semântica de execução do TANGL — a dualidade Evaluate/Run, once, cascateamento — aparece como frases ordinárias de markdown.

## tangl:Cases
- in case of `can place cup`
  - `order received` is a general rule using `sensor`.`isOrdered`
  - `no cup` is a counter rule using `sensor`.`noCupAvailable`
  - don't `order received` when `no cup`
  - do `arm`.`placeCup` once when `order received`
  - run `can pour water` when `order received`

- in case of `can pour water`
  - `cup placed` is a general rule using `sensor`.`cupIsPlaced`
  - do `arm`.`pourWater` once when `cup placed`
  - run `can brew espresso` when `cup placed`

## tangl:Provides
- provides `make coffee`
  - run `can place cup`

## tangl:Internal
- every 1s until `can serve coffee`
  - run `can place cup`

Um auditor lê isto como: “Assim que o copo puder ser colocado — se o pedido foi recebido, coloque o copo uma vez e passe a servir a água. Se não houver copo, o pedido é anulado. Para fazer café, comece por colocar o copo, e tente novamente a cada segundo até que possa ser servido.”

Sem once, o braço colocaria um copo novo a cada tick enquanto o pedido permanecesse ativo — a palavra é a razão inteira pela qual uma atualização lenta do sensor não se transforma em uma reexecução fisicamente insegura. Um auditor confirma a segurança de reexecução a partir dessa única frase, sem nunca ler uma cláusula de guarda em Go.

Exemplo: compensação — o mundo permanece íntegro mesmo em caso de falha

undo não é o mesmo que uma rejeição. Uma rejeição é um ramo normal do grafo; undo é compensação para uma execução que morreu no meio do caminho.

- do `bank`.`withdraw` once when `balance sufficient`
- undo `bank`.`refund` when `balance sufficient`
- run `can deposit` when `balance sufficient`

“Se o saldo for suficiente, saque uma vez; se qualquer coisa a jusante falhar, reverta via reembolso; e continue para o depósito.” Em caso de falha, a ordenação é determinística:

1. withdraw succeeds        → refund is armed on the compensation stack
2. deposit errors           → the Run aborts immediately
3. stack unwinds LIFO       → refund fires, the money comes back
4. the original error is reported — the transfer failed, and the world looks like it never happened

Se o próprio refund falhar, as compensações restantes param e a transação inteira é escalada para um portão de revisão humana (REVIEW) — o sistema decide por si mesmo que uma transferência meio executada não é algo a ser encoberto automaticamente.

Onde o texto deixa de ser a fonte da verdade — TANGEUL

Tudo acima é TANGL: texto markdown analisado e executado diretamente. Mas o texto ser a entrada de execução é uma conveniência, não uma necessidade. No momento em que uma linguagem tem duas superfícies — inglês e coreano — surge a pergunta “qual delas é canônica?”. Agora a resposta é “inglês, por convenção”. Isso é uma decisão, não uma garantia estrutural.

TANGEUL elimina a pergunta, e já é distribuído como a fonte única da verdade binária pkg/tangeul para a cadeia de ferramentas tangl. O artefato de execução canônico é um fluxo de grafo binário (.tangeul) sobre o qual check/ast/effects/gen rodam diretamente; os arquivos markdown em inglês e coreano são codecs de superfície que absorvem para dentro, e renderizam de volta a partir, desse mesmo grafo.

 EN .md ──[EN codec]──┐                        ┌──[mode 1]── verbatim byte-identical round trip
                      ├──> .tangeul (SSOT) ────┤
 KO .md ──[KO codec]──┘                        └──[mode 2]── normalized EN/KO rendering

• Modo 1 (verbatim): reproduz os bytes autorais exatamente, de modo que a saída de decodificação é byte a byte idêntica ao .md original — verificado pelo teste de round-trip da CLI.
• Modo 2 (regenerado): decode --locale en|ko re-renderiza cada instrução através do codec da localidade alvo, reproduzindo os trechos de prosa verbatim. Um documento escrito em coreano pode ser renderizado para um auditor de inglês, e vice-versa.

A superfície de autoria de um documento é fixada a uma única localidade (misturar seções em inglês e coreano em um mesmo arquivo é rejeitado), mas o próprio fluxo .tangeul não sabe qual localidade o escreveu. Ele pode ser renderizado em qualquer um dos idiomas sob demanda precisamente porque o artefato canônico é um grafo, não um parágrafo.

Todo o conhecimento em nível de bits fica em quarentena em dois pacotes — word (palavras de 16 bits, cabeçalhos de frame) e codebook (valores de código append-only) — de modo que as camadas acima deles (packets, stream, o contêiner de documento) permaneçam estáveis não importa como a codificação evolua:

pkg/tangeul/
├── word/       // 16-bit words, frame headers — bit-level knowledge stops here
├── codebook/   // NodeType/PropCode/Control codes, append-only
├── packet/     // Node/Edge/Control/Text packets
├── stream/     // Doc ↔ .tangeul serialization
└── doc/        // Doc container + VerifyTiling + the surface Codec interface

VerifyTiling é o portão de integridade: os blocos registrados devem ladrilhar o texto-fonte exatamente, e ele roda em cada carregamento e em cada saída do encoder. Testes de paridade afirmam que o AST carregado de um fluxo .tangeul é igual ao AST que o parser produz a partir do .md original (a menos dos números de linha). Redirecionar para binário não é sobre mudar o que o código faz — o grafo, e portanto a saída gerada, é idêntico; é sobre remover estruturalmente a possibilidade de deriva entre múltiplas cópias do mesmo texto.

Contratos auditáveis

A conclusão do toulmin foi que um veredicto é calculado por uma fórmula, não decidido por uma pessoa. TANGL acrescenta mais uma linha a isso: o cálculo é legível por alguém que nunca escreveu a fórmula.

• Warrant (uma regra) = uma frase, `n` is a ... rule
• Rebuttal = uma frase, don't `X` when `Y`
• Ground (evidência) = uma chamada a uma função de pacote referenciado
• Veredicto = a fórmula do h-Categoriser

E TANGEUL é o trabalho de garantir, em nível de bytes, que essas frases apontem para o mesmo grafo independentemente de em qual idioma são escritas. A pessoa que escreve a regra e a pessoa que a audita não precisam mais compartilhar um idioma.

MIT License. github.com/park-jun-woo/toulmin — pkg/tangl, pkg/tangeul, cmd/tangl.

Fontes

• TANGL — a gramática de markdown executável (TANGEUL.en.md)
• pkg/tangeul — o formato SSOT binário (README)
• park-jun-woo/toulmin — o motor de regras e a cadeia de ferramentas tangl

Changelog

• 2026-07-03: Primeira edição