A planilha de regras

Uma planilha de regras (rule sheet) declara as regras sobre as suas ferramentas como um YAML que uma pessoa consegue ler em voz alta: um reembolso acima de 200 precisa da aprovação de um supervisor; fechar uma conta espera o cliente confirmar; ninguém apaga um cliente. Ela compila para o mesmo rulebook em que uma política Colang se transforma, então o guardrail lê uma planilha exatamente como lê Colang.

Uma planilha

rules:
  - action: refund_card
    requires: [supervisor_approved]
    when: { amount_over: 200 }
  - action: charge_card
    requires_confirmation: true
  - action: send_receipt
    after: [charge_card]
    at_most: 1

Todas as chaves

Uma regra por ação. Cada regra nomeia a sua action, uma das suas ferramentas, e diz uma ou mais destas coisas:

Chave	O que diz	Para o que compila
`requires: [a, b]`	a ação só roda onde todo contexto nomeado vale	um fluxo que nega por padrão para a ação, protegido por `$a and $b`
`when: {amount_over: 200}`	quando os requisitos se aplicam, como condições sobre os próprios argumentos da chamada: `<argumento>_over`, `_under`, `_at_least`, `_at_most` ou `_is`	a proteção só vale onde a condição vale; a verificação de ferramentas calcula a condição a partir dos argumentos da chamada, então o host não pode defini-la
`never: true`	a ação nunca roda	um fluxo que a recusa incondicionalmente
`requires_confirmation: true`	uma pessoa confirma cada chamada	uma confirmação que o catálogo declara, aplicada pela verificação de ferramentas
`confirmation: "…"`	o mesmo, com as palavras que são perguntadas à pessoa	como acima, com o texto
`after: [ferramenta]`	a ação só roda depois de cada ferramenta nomeada, na mesma sessão	a regra de ordem, aplicada pela verificação de ferramentas
`not_after: [ferramenta]`	a ação nunca roda depois de uma ferramenta nomeada	como acima
`at_most: 3`	a ação roda no máximo esse número de vezes numa sessão	como acima
`check: [{field: quantity, at_most: {from: check_stock.in_stock}}]`	condições sobre a chamada, todas as quais precisam valer: um valor, uma lista ou o que uma ferramenta anterior devolveu	as condições da própria ferramenta; um valor que a verificação de ferramentas não consegue ler recusa a chamada

Confirmações, ordem e condições são colocadas sobre as suas ferramentas; o rulebook decide se uma ação pode acontecer. No guardrail, a barreira se chama your_rules (o rulebook, condições, limites e gastos), order ou, numa confirmação, a chamada espera pela pessoa.

Compilando

O serviço compila uma planilha; as decisões são tomadas depois na sua máquina.

$ stalwart rules compile rules.yaml --out-dir compiled

grava rulebook.ir.json, catalogue_overlay.json e rule_sheet.co (o Colang a que equivale) em compiled/. Passe a pasta como Guardrail(..., rules="compiled"). O caminho de uma planilha também serve (rules="rules.yaml"): ela é compilada quando o guardrail é criado, com QLS_API_KEY.

No stalwart mcp: compile_rules("rules.yaml") grava a mesma pasta, e as outras ferramentas a leem.

Os avisos

A planilha é verificada contra as suas ferramentas, e cada problema é um aviso, não uma falha:

rule_action_unknown: uma regra para uma ferramenta que você não tem;
write_ungoverned: uma escrita que a planilha nunca nomeia, para que uma escrita nova nunca fique sem regra por esquecimento.

lint_rules("rules.yaml") no stalwart mcp os lista contra as ferramentas que o guardrail verifica.

O que é recusado

Uma planilha que o compilador não consegue declarar exatamente é recusada, nomeando a sua linha, e nada é gravado:

uma chave que não é uma das acima;
uma segunda regra para a mesma ação: como duas se combinariam nunca é adivinhado;
never com qualquer coisa ao lado;
when numa regra que não exige nada;
uma condição sem comparação que o compilador consiga declarar, ou um número comparado com algo que não é número;
YAML fora do subconjunto da planilha: tabulações, uma lista em bloco, um valor na linha abaixo da chave, um segundo documento.

Uma planilha é recusada em vez de aproximada: uma aproximação seria uma regra que você não escreveu, aplicada como se tivesse escrito.

Os limites

Uma planilha declara o que as suas chaves expressam e nada mais; uma regra que precisa de mais é escrita em Colang.
Os contextos que uma planilha requires são definidos pelos seus sistemas em tempo de execução; o guardrail faz a ação esperar por eles, não garante que sejam definidos com verdade.
Os avisos são conselhos. Lê-los é como uma escrita nova não fica sem regra.
Suas regras são tão completas quanto você as escreveu: hunt procura um caminho por elas.