actrova 0.0.1__py3-none-any.whl

actrova/__init__.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+"""ACTROVA — assurance de execução para agentes.
+
+    Autorize a ação. Prove o resultado.
+
+O que esta biblioteca faz, em uma frase: separa **o que o agente disse que
+fez** de **o que a fonte de verdade confirma que aconteceu**, e guarda a
+diferença numa cadeia de recibos em que **toda alteração deixa marca**.
+
+⚠️ "Deixa marca" e não "é impossível": ver o limite honesto em `recibo.py`.
+
+    from actrova import Escopo
+
+    escopo = Escopo(politicas="politicas", dados="dados")
+
+    @escopo.guarda(agente="jarvis.ceo", acao="source.disable", alvos="fontes")
+    def desabilitar(fontes): ...
+
+⚠️ Padrão é `observe`: registra tudo, não interrompe nada.
+"""
+from .nucleo import (AcaoBloqueada, Alcance, Assegura, CanarioInterrompido,
+                     Cobertura, Contagem, comparar_cobertura,
+                     Custo, Decisao, Divergencia, Efeito, EscopoDaAfirmacao,
+                     Estado, Evidencia, Finalidade, IndependenciaDaFonte,
+                     Intencao, Modo, Prova, Relacao, SemEfeito, TipoCusto,
+                     Veredito, comparar_efeito, impressao,
+                     nova_execucao, normalizar_custo,
+                     normalizar_evidencias)
+from .contrato import (Contrato, ContratoInvalido, Execucao,
+                       EvidenciaExigida, carregar, carregar_diretorio)
+from .avaliador import Avaliador, AvaliadorSimples, validar_ordem
+from .recibo import CadeiaQuebrada, Livro, Recibo, renderizar
+from .verificacao import (Fila, PlanoDeVerificacao, Registro,
+                          Verificador)
+from .guarda import OMITIDO, Escopo, portao_de_evidencia
+from .maturidade import prontidao, relatorio
+from .evento import (Evento, EventSink, SinkDeArquivos, SinkEmMemoria,
+                     novo_id)
+from .trabalhador import Trabalhador
+from .conformidade import CENARIOS, Relatorio, conformar
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "Escopo", "AcaoBloqueada", "CanarioInterrompido", "Decisao", "Efeito",
+    "Estado", "Evidencia", "Execucao", "Intencao", "SemEfeito", "Contagem",
+    "Custo", "TipoCusto", "normalizar_custo",
+    "Relacao", "Divergencia", "comparar_efeito", "nova_execucao",
+    # os três eixos de QUANTO a prova prova — ver `Assegura`
+    "Assegura", "EscopoDaAfirmacao", "IndependenciaDaFonte",
+    "Finalidade",
+    # prova de QUÊ, e o que ficou fora — ver `Alcance`
+    "Cobertura", "Alcance", "comparar_cobertura",
+    "Modo", "Prova", "Veredito", "Contrato", "ContratoInvalido",
+    "EvidenciaExigida", "carregar", "carregar_diretorio", "Avaliador",
+    "AvaliadorSimples", "validar_ordem", "CadeiaQuebrada", "Livro", "Recibo",
+    "renderizar", "Fila", "PlanoDeVerificacao", "Registro",
+    "Verificador", "portao_de_evidencia",
+    "impressao", "normalizar_evidencias", "prontidao", "relatorio",
+    "conformar", "CENARIOS", "Relatorio",
+    "Evento", "EventSink", "SinkEmMemoria", "SinkDeArquivos", "novo_id",
+    "Trabalhador",
+    "OMITIDO",
+    "__version__",
+]

actrova/__main__.py

@@ -0,0 +1,392 @@
+# -*- coding: utf-8 -*-
+"""__main__.py -- a suíte de conformidade na mão de quem não escreveu a Actrova.
+
+⚠️ POR QUE ISTO EXISTE.
+
+A `conformar()` já sabia testar o verificador de um estranho. Só que para
+CHEGAR nela o estranho precisava importar o pacote, instanciar a classe certa,
+montar um dicionário de cenários aninhado e descobrir sozinho que
+`Estado.INVERIFICAVEL` é o que se espera quando a fonte cai.
+
+📌 **Isso é uma barreira de dez minutos antes do primeiro resultado, e a
+pergunta que a Actrova precisa responder — "outro desenvolvedor de agentes tem
+esse problema?" — morre nesses dez minutos.** Ninguém escreve um arquivo de
+fixtures para um produto que ainda não sabe se serve.
+
+O comando existe para inverter a ordem: **primeiro o resultado sobre o código
+DELE, depois o convite.**
+
+    python3 -m actrova conformar meu_modulo.py:MeuVerificador
+
+⚠️ E rodar SEM cenário nenhum é um caminho de primeira classe, não um erro de
+uso. A saída mostra o que já dá para afirmar sem fixture (as invariantes do
+caminho de erro), mostra o que falta, e **se recusa a certificar** — porque a
+pergunta que decide tudo é a única que a suíte não consegue simular:
+
+    o seu `_consultar` LEVANTA quando a fonte cai, ou devolve {}?
+"""
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+from .conformidade import CENARIOS, OBRIGATORIO, conformar
+
+# ── códigos de saída ──────────────────────────────────────────────────────
+# ⚠️ 1 e 2 são DIFERENTES de propósito. "violou uma invariante" e "não foi
+# perguntado" são coisas distintas, e a CI de quem usa isto precisa poder
+# tratá-las diferente. Colapsar as duas em "falhou" repete, no shell, o mesmo
+# achatamento que o projeto inteiro existe para desfazer.
+SAIDA_CONFORME = 0
+SAIDA_NAO_CONFORME = 1
+SAIDA_SEM_CERTIFICADO = 2
+SAIDA_ERRO_DE_USO = 3
+
+USO = """\
+actrova — assurance de execução para agentes
+
+  python3 -m actrova iniciar NOME     esqueleto rodável em 10 minutos
+  python3 -m actrova conformar ALVO [--cenarios FONTE]
+  python3 -m actrova exemplo [> cenarios.py]
+
+ALVO      onde mora o seu verificador, no formato `onde:Nome`
+            meu_modulo.py:MeuVerificador     caminho de arquivo
+            meu_pacote.verificadores:Stripe  módulo importável
+          `Nome` pode ser a classe (instanciada sem argumentos), uma
+          instância já pronta, ou uma função que devolve uma.
+
+--cenarios  as fixtures que só você consegue montar, porque só você sabe que
+            contexto faz a SUA fonte responder cada coisa.
+              cenarios.py:CENARIOS   dicionário Python (recomendado)
+              cenarios.json          se os contextos forem só JSON
+
+Sem `--cenarios` o comando roda assim mesmo e diz o que já dá para afirmar.
+Ele só não emite certificado — `não testado não é aprovado`.
+
+  saída 0  conforme sob as fixtures fornecidas
+        1  NÃO conforme — alguma invariante foi violada
+        2  sem certificado — algo não foi testado
+        3  erro de uso
+"""
+
+MODELO = '''\
+# -*- coding: utf-8 -*-
+"""cenarios.py -- as três situações que só VOCÊ consegue montar.
+
+A suíte testa sozinha o caminho de erro (exceção, tipo errado, asserção
+vazia). O que ela não consegue descobrir de fora é como a SUA fonte se
+comporta — e é aí que mora o bug que originou a Actrova.
+
+Cada cenário é o par `{contexto, espera}` que você passaria ao verificador:
+`contexto` é o que o executor sabe sobre a ação, `espera` é o que o
+contrato afirmou que deveria ser verdade.
+"""
+
+CENARIOS = {
+    # a fonte confirma que a ação aconteceu  → VERIFIED (ou PARTIAL)
+    "sucesso": {
+        "contexto": {},
+        "espera": {},
+    },
+
+    # a fonte responde, e diz que NÃO aconteceu  → FAILED (ou PARTIAL)
+    "divergente": {
+        "contexto": {},
+        "espera": {},
+    },
+
+    # ⚠️ O QUE DECIDE TUDO. A fonte está fora: rede caída, 500, timeout.
+    #
+    # Aponte o contexto para algo que faça o SEU `_consultar` falhar de
+    # verdade: host inexistente, porta fechada, token vazio.
+    #
+    # ⚠️ Não simule devolvendo {} — o ponto é justamente descobrir se o
+    # seu código distingue "não consegui consultar" de "consultei e não
+    # tem nada". Fingir a queda da fonte é testar a fixture, não o código.
+    #
+    # Esperado: UNVERIFIABLE. Nunca VERIFIED, nunca FAILED.
+    "fonte_fora": {
+        "contexto": {},
+        "espera": {},
+    },
+}
+'''
+
+
+def _iniciar(argumentos: list) -> int:
+    """Escreve um projeto que RODA antes de ser editado.
+
+    ⚠️ POR QUE A ORDEM IMPORTA. Dois pilotos disseram sim e ficaram parados
+    porque o primeiro passo era *"escreva um `Verificador`"* — e ninguém
+    escreve uma classe abstrata de um produto que ainda não viu funcionar.
+    **Pedia-se fé antes de resultado.**
+
+    📌 O esqueleto usa uma fonte de mentira de propósito: a pessoa vê a FORMA
+    do recibo, com cadeia real, antes de ligar no sistema dela. Depois troca
+    um método só."""
+    from . import _modelos
+
+    nome = (argumentos[0] if argumentos else "verificador").strip()
+    if not nome.replace("_", "").isalnum() or nome[0].isdigit():
+        return _erro(f"{nome!r} não serve como nome de módulo Python — "
+                     f"use letras, números e `_`, sem começar com número")
+    resto = argumentos[1:]
+    destino = Path(resto[1]).expanduser() if len(resto) > 1 and \
+        resto[0] == "--em" else Path.cwd()
+
+    classe = "Verificador" + "".join(
+        p.capitalize() for p in nome.split("_") if p) or "VerificadorNovo"
+
+    arquivos = {
+        destino / "politicas" / "contrato.yaml": _modelos.CONTRATO,
+        destino / f"{nome}.py": _modelos.VERIFICADOR.format(
+            nome=nome, classe=classe),
+        destino / "app.py": _modelos.APP.format(nome=nome, classe=classe),
+    }
+
+    # ⚠️ NÃO SOBRESCREVE NADA. Escrever por cima do código de alguém para
+    # "facilitar o começo" é exatamente o tipo de ajuda que ninguém pediu.
+    existentes = [a for a in arquivos if a.exists()]
+    if existentes:
+        return _erro("estes arquivos já existem e eu não vou por cima:\n   "
+                     + "\n   ".join(str(a) for a in existentes))
+
+    for caminho, conteudo in arquivos.items():
+        caminho.parent.mkdir(parents=True, exist_ok=True)
+        caminho.write_text(conteudo, encoding="utf-8")
+
+    print(f"""✅ escrito em {destino}
+
+   politicas/contrato.yaml   o que a ação pode fazer, e como provar
+   {nome}.py{' ' * max(1, 25 - len(nome) - 3)}o verificador — troque o `_consultar`
+   app.py                    ⚠️ RODE ISTO AGORA, antes de editar
+
+   python3 app.py
+
+   Ele usa uma fonte de mentira de propósito. Você vê a forma do recibo,
+   com cadeia real, antes de ligar no seu sistema.
+
+📌 Depois de trocar o `_consultar` pela sua fonte:
+
+   python3 -m actrova conformar {nome}.py:{classe}
+
+   Isso diz se o seu código transforma "a fonte caiu" em "a fonte disse
+   que não" — que é o bug que este produto existe para pegar.
+""")
+    return SAIDA_CONFORME
+
+
+def _erro(msg: str) -> int:
+    print(f"❌ {msg}", file=sys.stderr)
+    return SAIDA_ERRO_DE_USO
+
+
+def _carregar(alvo: str):
+    """`arquivo.py:Nome` ou `pacote.modulo:Nome` → o objeto.
+
+    ⚠️ O caminho de arquivo existe porque é o que a pessoa tem na mão. Exigir
+    módulo importável é exigir que ela entenda `sys.path` antes de ver
+    qualquer resultado, e ninguém paga esse pedágio por curiosidade.
+    """
+    if ":" not in alvo:
+        raise ValueError(
+            f"falta o `:Nome` em {alvo!r} — o formato é `onde:Nome`, por "
+            f"exemplo `{alvo}:MeuVerificador`")
+    onde, _, nome = alvo.rpartition(":")
+    if not onde or not nome:
+        raise ValueError(f"não entendi {alvo!r} — o formato é `onde:Nome`")
+
+    if onde.endswith(".py") or "/" in onde or "\\" in onde:
+        caminho = Path(onde).expanduser().resolve()
+        if not caminho.is_file():
+            raise ValueError(f"não achei o arquivo {caminho}")
+        # ⚠️ O diretório do arquivo entra no path ANTES de importar: um
+        # verificador quase sempre importa vizinhos dele.
+        sys.path.insert(0, str(caminho.parent))
+        spec = importlib.util.spec_from_file_location(caminho.stem, caminho)
+        modulo = importlib.util.module_from_spec(spec)
+        sys.modules[caminho.stem] = modulo
+        spec.loader.exec_module(modulo)
+    else:
+        modulo = importlib.import_module(onde)
+
+    if not hasattr(modulo, nome):
+        publicos = [n for n in vars(modulo) if not n.startswith("_")]
+        raise ValueError(
+            f"`{nome}` não existe em {onde}. Achei: "
+            + (", ".join(sorted(publicos)[:12]) or "nada público"))
+    return getattr(modulo, nome)
+
+
+def _instanciar(obj, alvo: str):
+    """Classe → instância; instância → ela mesma; fábrica → o que devolver."""
+    if isinstance(obj, type):
+        try:
+            return obj()
+        except TypeError as e:
+            raise ValueError(
+                f"`{alvo}` é uma classe que não instancia sem argumentos "
+                f"({e}). Exponha uma instância já pronta ou uma função sem "
+                f"argumentos que devolva uma, e aponte para ela.") from e
+    if callable(obj) and not hasattr(obj, "verificar"):
+        return obj()
+    return obj
+
+
+def _cenarios(fonte: str) -> dict:
+    if fonte.endswith(".json"):
+        caminho = Path(fonte).expanduser().resolve()
+        if not caminho.is_file():
+            raise ValueError(f"não achei o arquivo {caminho}")
+        dados = json.loads(caminho.read_text(encoding="utf-8"))
+    else:
+        dados = _carregar(fonte)
+        if callable(dados):
+            dados = dados()
+
+    if not isinstance(dados, dict):
+        raise ValueError(
+            f"os cenários precisam ser um dicionário "
+            f"`{{nome: {{contexto, espera}}}}`, e vieram {type(dados).__name__}")
+
+    # ⚠️ NOME ERRADO TEM QUE GRITAR. `"fonte-fora"` com hífen, ou
+    # `"fonte_fora "` com espaço, hoje cairia silenciosamente em "não
+    # fornecido" — e a pessoa leria `SEM CERTIFICADO` achando que escreveu a
+    # fixture mais importante. Ausência disfarçada de presença é, de novo, a
+    # doença da casa.
+    desconhecidos = sorted(set(dados) - set(CENARIOS))
+    if desconhecidos:
+        raise ValueError(
+            f"cenário(s) que a suíte não conhece: "
+            f"{', '.join(repr(d) for d in desconhecidos)}. "
+            f"Os nomes são exatamente: {', '.join(sorted(CENARIOS))}")
+
+    for nome, c in dados.items():
+        if not isinstance(c, dict) or not set(c) <= {"contexto", "espera"}:
+            raise ValueError(
+                f"o cenário {nome!r} precisa ser "
+                f"`{{'contexto': {{...}}, 'espera': {{...}}}}`")
+    return dados
+
+
+def _conselho(rel, fornecidos) -> list:
+    """O que fazer a seguir, em vez de só o veredito.
+
+    ⚠️ Um relatório que diz `NÃO CONFORME` e para por aí transfere para quem
+    está de fora o trabalho de descobrir o que a Actrova já sabe.
+    """
+    linhas = []
+    faltando = [n for n in CENARIOS if n not in fornecidos]
+    if OBRIGATORIO in faltando:
+        linhas += [
+            "",
+            "  📌 PRÓXIMO PASSO — a pergunta que decide tudo ainda não foi feita:",
+            "",
+            "       o seu `_consultar` LEVANTA quando a fonte cai,",
+            "       ou devolve {} ?",
+            "",
+            "     De fora, um `{}` de falha é idêntico a um `{}` de fonte que",
+            "     respondeu vazio. Essa confusão exata é o bug que originou",
+            "     este projeto, e é a única coisa que a suíte não consegue",
+            "     descobrir sozinha.",
+            "",
+            "       python3 -m actrova exemplo > cenarios.py",
+            "       python3 -m actrova conformar ALVO --cenarios cenarios.py:CENARIOS",
+        ]
+    elif faltando:
+        linhas += [
+            "",
+            f"  📌 falta(m) o(s) cenário(s): {', '.join(faltando)}",
+        ]
+    if rel.reprovados:
+        linhas += [
+            "",
+            "  📌 cada ❌ acima é um caminho pelo qual o seu verificador pode",
+            "     afirmar mais do que a fonte disse. Não é estilo — é a",
+            "     diferença entre um recibo que vale e um que mente.",
+        ]
+    return linhas
+
+
+def _conformar(argumentos: list) -> int:
+    if not argumentos:
+        return _erro("falta o ALVO. Exemplo:\n"
+                     "   python3 -m actrova conformar meu_modulo.py:MeuVerificador")
+
+    alvo, fonte = argumentos[0], None
+    resto = argumentos[1:]
+    while resto:
+        if resto[0] in ("--cenarios", "--cenários"):
+            if len(resto) < 2:
+                return _erro("`--cenarios` precisa de um valor "
+                             "(`cenarios.py:CENARIOS` ou `cenarios.json`)")
+            fonte, resto = resto[1], resto[2:]
+        else:
+            return _erro(f"não conheço a opção {resto[0]!r}")
+
+    try:
+        verificador = _instanciar(_carregar(alvo), alvo)
+    except ValueError as e:
+        return _erro(str(e))
+    except Exception as e:                            # noqa: BLE001
+        return _erro(f"não consegui carregar {alvo!r} — "
+                     f"{type(e).__name__}: {e}")
+
+    if not hasattr(verificador, "verificar"):
+        return _erro(
+            f"`{alvo}` não parece um Verificador: não tem `verificar()`.\n"
+            f"   Ele precisa herdar de `actrova.Verificador` — é a classe base "
+            f"que impõe\n   a invariante, e herdar dela é metade do que esta "
+            f"suíte confere.")
+
+    try:
+        fixtures = _cenarios(fonte) if fonte else {}
+    except ValueError as e:
+        return _erro(str(e))
+    except Exception as e:                            # noqa: BLE001
+        return _erro(f"não consegui ler os cenários — {type(e).__name__}: {e}")
+
+    relatorio = conformar(verificador, fixtures)
+    print(relatorio.texto())
+    for linha in _conselho(relatorio, set(fixtures)):
+        print(linha)
+    print()
+
+    if relatorio.conforme:
+        return SAIDA_CONFORME
+    if relatorio.reprovados:
+        return SAIDA_NAO_CONFORME
+    return SAIDA_SEM_CERTIFICADO
+
+
+def principal(argumentos: list | None = None) -> int:
+    argumentos = list(sys.argv[1:] if argumentos is None else argumentos)
+
+    # ⚠️ O diretório de onde a pessoa chamou entra no path. Sem isto,
+    # `meu_pacote.verificadores:X` só funciona para quem já instalou o
+    # próprio projeto — e a primeira tentativa de todo mundo é de dentro da
+    # pasta do projeto, sem instalar nada.
+    if "" not in sys.path and str(Path.cwd()) not in sys.path:
+        sys.path.insert(0, str(Path.cwd()))
+
+    if not argumentos or argumentos[0] in ("-h", "--help", "ajuda"):
+        print(USO)
+        return SAIDA_CONFORME
+
+    comando, resto = argumentos[0], argumentos[1:]
+    if comando == "iniciar":
+        return _iniciar(resto)
+    if comando == "conformar":
+        return _conformar(resto)
+    if comando == "exemplo":
+        print(MODELO)
+        return SAIDA_CONFORME
+    return _erro(f"não conheço o comando {comando!r}. "
+                 f"São três: `iniciar`, `conformar` e `exemplo`.")
+
+
+if __name__ == "__main__":
+    sys.exit(principal())

actrova/_modelos.py

@@ -0,0 +1,162 @@
+# -*- coding: utf-8 -*-
+"""_modelos.py -- o esqueleto que `actrova iniciar` escreve.
+
+⚠️ POR QUE ISTO EXISTE, E POR QUE ELE RODA ANTES DE SER EDITADO.
+
+Dois pilotos disseram sim e ficaram parados porque o primeiro passo era
+*"escreva um `Verificador`"* — e ninguém escreve uma classe abstrata de um
+produto que ainda não viu funcionar. **A ordem estava invertida: pedia-se fé
+antes de resultado.**
+
+📌 Por isso o esqueleto é RODÁVEL no instante em que é escrito. Ele produz um
+recibo de verdade, com cadeia de verdade, contra uma fonte de mentira — e a
+pessoa vê a forma da coisa antes de ligar no sistema dela. Depois ela troca a
+fonte de mentira pela real, que é um método só.
+"""
+
+CONTRATO = """\
+# O contrato declara O QUE a ação pode fazer e COMO provar que fez.
+# ⚠️ Ele é lido por quem NÃO escreveu o código — por isso YAML, e não Python.
+
+agente: meu.agente
+acao: pedido.cancelar
+versao: v1
+autoridade: L2
+
+# ⚠️ `observe` NÃO bloqueia nada. Registra o veredito e deixa a ação seguir.
+# É assim que se descobre quais políticas importam antes de deixar uma delas
+# parar a operação de alguém. Só vire `enforce` depois de semanas de recibo.
+modo: observe
+
+regras:
+  - id: lote_grande
+    se: {campo: quantidade, op: ">", valor: 10}
+    entao: HOLD
+    motivo: >-
+      cancelar mais de 10 pedidos de uma vez precisa de gente olhando.
+
+verificacao:
+  verificador: meu.verificador
+  # ⚠️ Quem confere, contra o quê, e por quanto tempo insiste. Sem isto,
+  # `PENDING` é uma promessa que ninguém consegue cobrar.
+  espera:
+    status: cancelado
+  tentativas: 3
+  # ⚠️ A PRIMEIRA ESPERA É 0 de propósito: tenta na hora, e só então recua.
+  # Verificação quase nunca é síncrona — reembolso liquida depois, e-mail
+  # entrega depois — mas insistir com espera crescente só faz sentido DEPOIS
+  # de uma primeira tentativa que pode muito bem já responder.
+  espera_segundos: [0, 30, 120]
+"""
+
+VERIFICADOR = '''\
+# -*- coding: utf-8 -*-
+"""{nome}.py -- prova que a ação aconteceu, perguntando a quem sabe.
+
+⚠️ A ÚNICA REGRA QUE IMPORTA AQUI, e ela é a razão de este produto existir:
+
+    `_consultar` DEVE LEVANTAR quando não conseguir falar com a fonte.
+
+Devolver `{{}}` numa falha faz "não consegui perguntar" virar "perguntei e não
+tem nada" — e essas duas coisas levam a decisões opostas. Foi assim que um
+agente real desabilitou 36 fontes de conteúdo porque uma consulta ao banco
+falhou e o código leu vazio como zero.
+
+📌 Se você levantar, a classe base devolve INVERIFICAVEL. Se você engolir,
+ela não tem como saber, e vai devolver FALHOU com toda a confiança do mundo.
+"""
+from actrova import Verificador
+
+
+class FonteIndisponivel(Exception):
+    """Não deu para falar com a fonte de verdade."""
+
+
+class {classe}(Verificador):
+    nome = "meu.verificador"
+
+    def _consultar(self, contexto: dict) -> dict:
+        """Vá à fonte REAL e devolva o que ela disse.
+
+        ⚠️ TROQUE ESTE CORPO pelo seu banco, sua API, seu CRM. O que não muda
+        é o `raise`: qualquer falha de comunicação tem que subir como exceção.
+
+            resposta = requests.get(..., timeout=10)
+            resposta.raise_for_status()          # ← NÃO engula isto
+            return resposta.json()
+        """
+        # --- fonte de mentira, só para o esqueleto rodar. Troque. ---
+        #
+        # 📌 `contexto` é o que o executor sabe sobre ESTA ação. Por padrão ele
+        # traz `alvos` — a lista que a sua função recebeu. É com ela que você
+        # vai perguntar à fonte real sobre as entidades CERTAS.
+        alvos = contexto.get("alvos") or []
+        if not alvos:
+            # ⚠️ Repare que isto LEVANTA em vez de devolver vazio. Sem alvo
+            # não há o que perguntar, e responder mesmo assim seria inventar.
+            raise FonteIndisponivel(
+                "o contexto não trouxe `alvos` — sem eles não há o que "
+                "perguntar à fonte")
+        return {{"pedidos": list(alvos), "status": "cancelado"}}
+
+    # ⚠️ OPCIONAL: implemente `_contar` se a sua ação mexe em LOTE. Quem
+    # implementa ganha `PARCIAL` de graça — "3 de 5 confirmados" — e o estado
+    # é DERIVADO dos números, nunca escolhido à mão.
+    #
+    # def _contar(self, observado, espera):
+    #     from actrova import Contagem
+    #     return Contagem(pedidos=..., confirmados=..., falhos=...)
+
+    # ⚠️ OPCIONAL: implemente `_efeito_observado` para responder a pergunta
+    # seguinte — "aconteceu exatamente o que foi AUTORIZADO?". Devolva
+    # (dicionário canônico, "complete" | "partial").
+    #
+    # `complete` significa "esta é a lista INTEIRA do que existe". Diga
+    # `partial` se a fonte paginou ou filtrou: é isso que decide se a AUSÊNCIA
+    # de um alvo pode ser afirmada.
+    #
+    # def _efeito_observado(self, observado, contexto):
+    #     return {{"pedidos": observado["cancelados"]}}, "complete"
+'''
+
+APP = '''\
+# -*- coding: utf-8 -*-
+"""app.py -- rode isto AGORA, antes de editar qualquer coisa.
+
+    python3 app.py
+
+⚠️ Ele usa uma fonte de mentira de propósito. A ideia é você ver a FORMA do
+recibo antes de ligar no seu sistema — e só depois trocar o `_consultar`.
+"""
+from actrova import Escopo, renderizar
+from {nome} import {classe}
+
+escopo = Escopo(politicas="politicas", dados="dados")
+escopo.registrar_verificador({classe}())
+
+
+@escopo.guarda(agente="meu.agente", acao="pedido.cancelar", alvos="pedidos")
+def cancelar(pedidos):
+    """A SUA função. A ACTROVA não muda o que ela faz — só registra."""
+    return {{"ok": True, "cancelados": pedidos}}
+
+
+if __name__ == "__main__":
+    cancelar(["pedido-8821"])
+
+    # ⚠️ A verificação NÃO acontece junto com a ação, e isso é deliberado:
+    # reembolso leva tempo para liquidar, e-mail leva tempo para entregar.
+    # Num sistema real, isto roda num laço, de tempos em tempos.
+    escopo.processar_verificacoes()
+
+    for recibo in escopo.livro.ler():
+        print(renderizar(recibo))
+        print("-" * 70)
+
+    integra, problemas = escopo.livro.verificar_cadeia()
+    print(f"cadeia íntegra: {{integra}}  {{problemas or ''}}")
+    print()
+    print("📌 Agora troque o `_consultar` de {nome}.py pela sua fonte real.")
+    print("   E rode `python3 -m actrova conformar {nome}.py:{classe}`")
+    print("   para conferir se ele mente quando a fonte cai.")
+'''