41 · Regras sem Colang: 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 toda verificação que lê um rulebook lê uma planilha exatamente como lê Colang. Este capítulo é a planilha, construção por construção, e o que acontece quando uma planilha diz algo que o compilador não consegue declarar exatamente.

Uma planilha¶

# As regras da loja, como uma planilha que uma pessoa consegue ler em voz alta.
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

Uma regra por ação. Cada regra nomeia a sua action, uma ferramenta do seu catálogo, e diz uma ou mais destas coisas:

Chave	O que diz	O Colang a que equivale
`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 condição vira um contexto que a verificação de ferramentas calcula a partir dos argumentos da chamada verificada, então o host não pode defini-lo
`never: true`	a ação nunca roda	um fluxo que a recusa incondicionalmente
`requires_confirmation: true`	uma pessoa confirma cada chamada	fora do rulebook: uma confirmação que o catálogo declara, e que a verificação de ferramentas aplica
`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 do catálogo, 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, nas palavras que toda condição de um agent.yaml usa: um valor, uma lista ou o que uma ferramenta anterior devolveu	as condições da própria ferramenta, somadas às que o catálogo declara; a verificação de ferramentas as decide, e um valor que ela não consegue ler recusa a chamada

As confirmações, as regras de ordem e as verificações de uma planilha não estão no rulebook, porque o rulebook decide se uma ação pode acontecer, e elas decidem quando e como. Elas voltam como uma camada sobre o seu catálogo, e a verificação de ferramentas as aplica como qualquer declaração (capítulo 32).

Compilando¶

$ stalwart rules compile rules.yaml --out-dir rules     # compilada; nada é guardado

O serviço compila a planilha na política Colang a que ela equivale, e o front end Colang por onde passa toda política emite o rulebook a partir dela. Uma planilha e o Colang a que ela equivale são, portanto, um mesmo portão, e todo veredito sobre um é um veredito sobre o outro. --out-dir escreve o que o compilador produziu: rule_sheet.co, o Colang; rulebook.ir.json, o rulebook; e catalogue_overlay.json, as confirmações, a ordem e as verificações que a planilha define. Essa pasta é o que um guardrail ou um gateway lê como as suas regras.

Nada da planilha fica guardado no serviço. Mantenha-a como um arquivo ao lado do seu agente e indique-a, ou a pasta compilada a partir dela, como o rulebook: do agente (capítulo 45): o agente compila uma planilha uma vez, ao começar, põe as confirmações, a ordem e as verificações dela por cima do seu catálogo, e toda verificação de ferramentas as leva a partir de então.

A página Rules do console é um formulário sobre a mesma planilha: ela compila na própria página e não salva nada (capítulo 5). Por HTTP, POST /v1/rule-sheets/compile compila, e não guarda nada. Ele precisa da permissão catalogue.

Os avisos¶

A planilha é conferida contra o seu catálogo onde o seu catálogo está -- pelo guardrail e pelo gateway quando leem as suas regras, e pelo stalwart verify --, e cada problema é um aviso, não uma falha:

rule_action_unknown: a planilha tem uma regra para uma ação que o catálogo não tem;
write_ungoverned: uma escrita que o catálogo tem e que a planilha nunca nomeia, para que uma escrita nova nunca fique sem regra por omissão.

O que todo modo lê¶

O rulebook em que uma planilha compila é o que a verificação de ferramentas aplica em tempo de execução, o que o stalwart verify e o caçador de bugs varrem, e o que um job guardrail verifica quando você envia o rulebook compilado como rulebook_ir. Cada um responde sobre ele exatamente como sobre um rulebook vindo do Colang.

Recusada, nunca aproximada: `rule_sheet_unsupported`¶

Uma planilha que o compilador não consegue declarar exatamente é recusada, nomeando a sua linha e o motivo, e nada é escrito. Os motivos são concretos:

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

$ stalwart rules compile unsupported.yaml
unsupported.yaml:4: rule_sheet_unsupported: line 4: `refund_card` has a rule already: one rule per action, so how two would combine is never guessed. The sheet was not compiled; nothing was changed.
$ echo $?
1

Uma planilha é recusada em vez de aproximada porque uma aproximação seria uma regra que você não escreveu, aplicada como se tivesse escrito. O stalwart rules compile sai com 1 numa recusa, 0 numa planilha que compilou, 2 quando o arquivo não pôde ser lido e 3 quando o serviço não pôde ser alcançado. O motivo da recusa é impresso em inglês, como o serviço o escreve.

De uma regra redigida a uma planilha¶

Uma regra que a Escrita de Guardrails redigiu e verificou é Colang. Quando a sua regra tem uma das formas acima, ela pode ser reescrita como uma planilha que um revisor lê com mais facilidade, e as duas compilam num mesmo portão: compile as duas e compare os rulebooks, ou verifique a mesma obrigação sobre cada uma.

Os limites¶

Uma planilha declara o que as suas construções expressam e nada mais. Uma regra que precisa de uma construção que a planilha não tem é escrita em Colang.
Os contextos que uma planilha exige (requires) são definidos pelos seus sistemas em tempo de execução; a planilha prova que a ação espera por eles, não que eles são definidos com verdade.
Os avisos são conselhos. Uma planilha com avisos compila mesmo assim; lê-los é como uma escrita nova não fica sem regra.