fazflow-policy-gate 0.1.0__tar.gz

fazflow_policy_gate-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: fazflow-policy-gate
+Version: 0.1.0
+Summary: Governança de agentes de IA: decide cada ação antes que ela aconteça. Binding sobre o artefato WASM, sem lógica de decisão.
+License: Apache-2.0
+Project-URL: Homepage, https://fazflow.com
+Project-URL: Repository, https://github.com/JulioCesar1582/FazFlow-IA
+Project-URL: Issues, https://github.com/JulioCesar1582/FazFlow-IA/issues
+Keywords: ai-agents,authorization,policy,cedar,governance,audit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Natural Language :: Portuguese (Brazilian)
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: wasmtime>=25
+
+# fazflow-policy-gate
+
+Decide cada ação de um agente de IA **antes** que ela aconteça, e registra a
+decisão numa cadeia verificável.
+
+A decisão é local: o motor roda dentro do seu processo, e os argumentos da
+requisição nunca saem da sua infraestrutura.
+
+## Instalar
+
+```bash
+pip install fazflow-policy-gate
+```
+
+O artefato WebAssembly viaja dentro do pacote. Não há passo de download.
+
+## Usar
+
+```python
+from fazflow_policy_gate import PolicyGate
+
+gate = PolicyGate.load()
+gate.load_bundle({"versao": "v1", "politicas": fonte_cedar})
+
+d = gate.evaluate({
+    "user": 'User::"u_8891"',
+    "agent": 'Agent::"copiloto"',
+    "action": "Tool::query",
+    "resource": 'Dataset::"notas"',
+    "context": contexto,   # os 14 campos
+    "entities": entidades, # User, Agent, Workload e o recurso
+})
+
+if d["verdict"] == "Deny":
+    raise RuntimeError(d["reason_code"])
+```
+
+## Duas camadas
+
+A política é avaliada em duas camadas — a do usuário e a do agente — e **as
+duas precisam permitir**. Uma política só com `principal is Agent` responde
+`Deny` com `DeniedNoUserPermit`, e é o erro mais comum do primeiro dia.
+
+## Obrigações
+
+Quando o veredito é `Transform`, `d["obligations"]` traz o que precisa ser
+feito — `mascarar:cpf,email`, `truncar:100`. **Aplicá-las é responsabilidade de
+quem chamou.** O SDK não toca no dado: ele não viu o conteúdo e não está no
+caminho da resposta.
+
+Ignorar uma obrigação é o modo de falha mais silencioso do sistema: o log
+registra que a máscara foi exigida, a auditoria vê que foi exigida, e o dado
+saiu inteiro.
+
+## Concorrência
+
+Cada instância WASM é single-threaded. Sob concorrência use `PolicyGatePool`,
+que mantém uma instância por thread lógica. Não chame métodos da instância crua
+enquanto outra thread avalia — os buffers são compartilhados.
+
+## O hash
+
+`gate.version()["artefato_hash"]` é o `sha256` do artefato que foi de fato
+instanciado, e é o mesmo valor que entra em cada decisão como `engine_hash`.
+Compará-lo com o que o painel mostra prova que o binário que decidiu é o que
+você conferiu.
+
+## Licença
+
+Apache-2.0

fazflow_policy_gate-0.1.0/README.md

@@ -0,0 +1,70 @@
+# fazflow-policy-gate
+
+Decide cada ação de um agente de IA **antes** que ela aconteça, e registra a
+decisão numa cadeia verificável.
+
+A decisão é local: o motor roda dentro do seu processo, e os argumentos da
+requisição nunca saem da sua infraestrutura.
+
+## Instalar
+
+```bash
+pip install fazflow-policy-gate
+```
+
+O artefato WebAssembly viaja dentro do pacote. Não há passo de download.
+
+## Usar
+
+```python
+from fazflow_policy_gate import PolicyGate
+
+gate = PolicyGate.load()
+gate.load_bundle({"versao": "v1", "politicas": fonte_cedar})
+
+d = gate.evaluate({
+    "user": 'User::"u_8891"',
+    "agent": 'Agent::"copiloto"',
+    "action": "Tool::query",
+    "resource": 'Dataset::"notas"',
+    "context": contexto,   # os 14 campos
+    "entities": entidades, # User, Agent, Workload e o recurso
+})
+
+if d["verdict"] == "Deny":
+    raise RuntimeError(d["reason_code"])
+```
+
+## Duas camadas
+
+A política é avaliada em duas camadas — a do usuário e a do agente — e **as
+duas precisam permitir**. Uma política só com `principal is Agent` responde
+`Deny` com `DeniedNoUserPermit`, e é o erro mais comum do primeiro dia.
+
+## Obrigações
+
+Quando o veredito é `Transform`, `d["obligations"]` traz o que precisa ser
+feito — `mascarar:cpf,email`, `truncar:100`. **Aplicá-las é responsabilidade de
+quem chamou.** O SDK não toca no dado: ele não viu o conteúdo e não está no
+caminho da resposta.
+
+Ignorar uma obrigação é o modo de falha mais silencioso do sistema: o log
+registra que a máscara foi exigida, a auditoria vê que foi exigida, e o dado
+saiu inteiro.
+
+## Concorrência
+
+Cada instância WASM é single-threaded. Sob concorrência use `PolicyGatePool`,
+que mantém uma instância por thread lógica. Não chame métodos da instância crua
+enquanto outra thread avalia — os buffers são compartilhados.
+
+## O hash
+
+`gate.version()["artefato_hash"]` é o `sha256` do artefato que foi de fato
+instanciado, e é o mesmo valor que entra em cada decisão como `engine_hash`.
+Compará-lo com o que o painel mostra prova que o binário que decidiu é o que
+você conferiu.
+
+## Licença
+
+Apache-2.0

fazflow_policy_gate-0.1.0/fazflow_policy_gate/__init__.py

@@ -0,0 +1,288 @@
+"""M4 — binding Python sobre o artefato WASM.
+
+> **R29 — Bindings sao finos.** Os SDKs TS e Python NAO DEVEM conter logica de
+> decisao, valor padrao, tratamento de campo ausente ou normalizacao. Apenas
+> serializar, chamar, desserializar.
+
+Superficie identica a do SDK TypeScript, com nomes idiomaticos de cada
+linguagem. Nenhuma funcionalidade existe em uma e nao na outra — e o que
+permite que M6 rode o mesmo corpus nos dois e exija saida byte a byte igual.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from wasmtime import Engine, Instance, Linker, Module, Store
+
+__all__ = ["PolicyGate", "PolicyGateError"]
+
+#: O artefato que viaja dentro do pacote.
+#:
+#: `PolicyGate.load()` sem argumento usa este caminho, e e isso que faz
+#: `pip install fazflow-policy-gate` funcionar sem mais nenhum passo. Sem
+#: ele, a primeira coisa que o pacote pediria e que a pessoa fosse buscar
+#: um `.wasm` em outro lugar — que e exatamente o beco que este SDK existe
+#: para evitar.
+#:
+#: O arquivo NAO esta no git: ele e colocado aqui no momento da publicacao.
+#: Quem roda a partir do codigo-fonte passa o caminho a mao.
+ARTEFATO_EMBUTIDO = Path(__file__).parent / "policycore_wasm.wasm"
+
+
+class PolicyGateError(Exception):
+    """Erro de politica ou de fronteira.
+
+    O `codigo` vem do WASM sem traducao — o SDK nao renomeia nada.
+    """
+
+    def __init__(self, codigo: str, detalhe: str) -> None:
+        super().__init__(f"{codigo}: {detalhe}")
+        self.codigo = codigo
+        self.detalhe = detalhe
+
+
+class PolicyGate:
+    """Motor de decisao carregado a partir do artefato WASM."""
+
+    def __init__(self, store: Store, instancia: Instance, artefato_hash: str) -> None:
+        self._store = store
+        self._i = instancia
+        self._artefato_hash = artefato_hash
+        self._handle = 0
+        e = instancia.exports(store)
+        self._memoria = e["memory"]
+        self._entrada_reservar = e["fz_entrada_reservar"]
+        self._saida_ptr = e["fz_saida_ptr"]
+        self._saida_len = e["fz_saida_len"]
+        self._carregar = e["fz_carregar_bundle"]
+        self._descarregar = e["fz_descarregar_bundle"]
+        self._avaliar = e["fz_avaliar"]
+        self._versao = e["fz_versao"]
+
+    # -- carga -------------------------------------------------------
+
+    @classmethod
+    def load(cls, caminho_wasm: str | Path | None = None) -> "PolicyGate":
+        """Carrega o artefato WASM.
+
+        Sem argumento, usa o `.wasm` que viaja dentro do pacote.
+
+        R27 — instanciado com um `Linker` **vazio**. Nenhuma capacidade de
+        host: sem WASI, sem relogio, sem entropia, sem filesystem, sem rede.
+        Se o modulo um dia passar a exigir um import, esta chamada falha — que
+        e o comportamento desejado, e nao algo a consertar concedendo a
+        capacidade.
+        """
+        caminho = Path(caminho_wasm) if caminho_wasm is not None else ARTEFATO_EMBUTIDO
+        try:
+            bytes_wasm = caminho.read_bytes()
+        except OSError as e:
+            # A mensagem precisa dizer QUAL caminho falhou e o que fazer.
+            #
+            # Sem isto, quem instalou de um pacote sem o artefato recebe um
+            # `FileNotFoundError` cru apontando para dentro de `site-packages`,
+            # e a conclusao natural e que o pacote esta quebrado — quando o que
+            # falta e um passo de publicacao.
+            raise PolicyGateError(
+                "ArtefatoAusente",
+                f"nao consegui ler o artefato WASM em `{caminho}`: {e}. "
+                "Se voce instalou este pacote de um indice, isto e defeito da "
+                "publicacao; se esta rodando do codigo-fonte, passe o caminho: "
+                'PolicyGate.load("./policycore_wasm.wasm").',
+            ) from e
+
+        # R28 — o hash do artefato acompanha toda decisao, calculado sobre os
+        # bytes que foram de fato instanciados.
+        artefato_hash = "sha256:" + hashlib.sha256(bytes_wasm).hexdigest()
+
+        engine = Engine()
+        store = Store(engine)
+        modulo = Module(engine, bytes_wasm)
+        linker = Linker(engine)
+        instancia = linker.instantiate(store, modulo)
+        return cls(store, instancia, artefato_hash)
+
+    @property
+    def artefato_hash(self) -> str:
+        return self._artefato_hash
+
+    # -- memoria -----------------------------------------------------
+
+    def _escrever_entrada(self, texto: str) -> int:
+        dados = texto.encode("utf-8")
+        ptr = self._entrada_reservar(self._store, len(dados))
+        self._memoria.write(self._store, dados, ptr)
+        return len(dados)
+
+    def _ler_saida(self, n: int) -> str:
+        ptr = self._saida_ptr(self._store)
+        return self._memoria.read(self._store, ptr, ptr + n).decode("utf-8")
+
+    # -- API ---------------------------------------------------------
+
+    def memoria_em_bytes(self) -> int:
+        """Quantos bytes a memoria linear do WASM ocupa agora.
+
+        Paridade com `memoriaEmBytes()` do SDK TypeScript. Existe para
+        responder "este gate esta crescendo?" sem entregar a instancia inteira
+        — com ela em maos daria para chamar `fz_descarregar_bundle` e deixar o
+        gate sem politica, que e poder demais para uma pergunta de
+        observabilidade.
+
+        A memoria linear do WASM so CRESCE: ela nao devolve pagina ao sistema.
+        Um numero que sobe a cada rollout de politica e vazamento, e nao carga.
+        """
+        return self._memoria.data_len(self._store)
+
+    def load_bundle(self, bundle: dict[str, str]) -> int:
+        n = self._escrever_entrada(json.dumps(bundle))
+        handle = self._carregar(self._store, n)
+        if handle == 0:
+            erro = json.loads(self._ler_saida(self._saida_len(self._store)))
+            raise PolicyGateError(erro["erro"], erro["detalhe"])
+
+        # O bundle anterior sai da memoria do WASM.
+        #
+        # `fz_descarregar_bundle` ja estava ligado na linha 50 e so era usado
+        # pelo `close()`. Aqui, `self._handle = handle` sobrescrevia a
+        # referencia e o bundle antigo continuava dentro do modulo, alcancavel
+        # por handle e impossivel de liberar depois — o unico handle que
+        # existia estava nesta variavel.
+        #
+        # Um processo de vida longa que acompanha rollout carrega um bundle
+        # novo a cada publicacao. A memoria linear do WASM so CRESCE, entao o
+        # vazamento e permanente, e o sintoma aparece semanas depois como "o
+        # gate foi ficando pesado" — sem relacao obvia com publicar politica.
+        #
+        # A descarga vem DEPOIS de o carregamento dar certo: descarregar antes
+        # deixaria o gate sem bundle nenhum se o novo fosse invalido, trocando
+        # um vazamento por uma indisponibilidade.
+        if self._handle != 0 and self._handle != handle:
+            self._descarregar(self._store, self._handle)
+
+        self._handle = handle
+        return handle
+
+    def evaluate(self, requisicao: dict[str, Any]) -> dict[str, Any]:
+        """Avalia uma requisicao.
+
+        A requisicao vai como o chamador a escreveu. O SDK nao preenche campo
+        ausente nem normaliza nada: se falta um campo do contexto, o WASM
+        devolve `ContextoInvalido`, que e o que M2/R12 quer que aconteca.
+        """
+        saida = json.loads(self.evaluate_raw(json.dumps(requisicao)))
+        if "erro" in saida:
+            raise PolicyGateError(saida["erro"], saida["detalhe"])
+        return saida
+
+    def evaluate_raw(self, requisicao_json: str) -> str:
+        """A mesma avaliacao, devolvendo o JSON **cru**.
+
+        Existe para M6/R40: a suite compara byte a byte, e desserializar e
+        reserializar reordenaria chaves, destruindo exatamente o que ela mede.
+        """
+        if self._handle == 0:
+            raise PolicyGateError("SemBundle", "chame load_bundle antes de evaluate")
+        n = self._escrever_entrada(requisicao_json)
+        return self._ler_saida(self._avaliar(self._store, self._handle, n))
+
+    def version(self) -> dict[str, Any]:
+        n = self._escrever_entrada(self._artefato_hash)
+        return json.loads(self._ler_saida(self._versao(self._store, n)))
+
+    def unload_bundle(self) -> bool:
+        if self._handle == 0:
+            return False
+        existia = self._descarregar(self._store, self._handle) == 1
+        self._handle = 0
+        return existia
+
+
+class PolicyGatePool:
+    """R26 — pool de instancias.
+
+    > **R26 — Pool de instancias.** WASM nao tem threads. Concorrencia DEVE
+    > ser atendida por pool de instancias, uma por thread logica, cada uma com
+    > o mesmo bundle. O tamanho do pool e configuravel; o padrao DEVE ser o
+    > numero de CPUs.
+
+    Cada instancia WASM tem sua propria memoria linear e e single-threaded.
+    Compartilhar uma entre threads corromperia os buffers de entrada e saida —
+    duas requisicoes escreveriam na mesma area. O pool resolve isso do jeito
+    mais simples que funciona: N instancias independentes, uma por thread em
+    voo, cada uma com o mesmo bundle carregado.
+
+    Nenhuma instancia guarda estado entre chamadas (R25), entao qual delas
+    atende qual requisicao e irrelevante para o resultado — e A54 prova isso
+    comparando o resultado concorrente com o serial.
+    """
+
+    def __init__(self, caminho_wasm: str | Path, bundle: dict[str, str], tamanho: int | None = None) -> None:
+        import os
+        import queue
+
+        self._tamanho = tamanho if tamanho is not None else (os.cpu_count() or 1)
+        self._livres: "queue.Queue[PolicyGate]" = queue.Queue()
+        self._todas: list[PolicyGate] = []
+
+        for _ in range(self._tamanho):
+            gate = PolicyGate.load(caminho_wasm)
+            gate.load_bundle(bundle)
+            self._todas.append(gate)
+            self._livres.put(gate)
+
+    @property
+    def tamanho(self) -> int:
+        return self._tamanho
+
+    def evaluate(self, requisicao: dict[str, Any]) -> dict[str, Any]:
+        gate = self._livres.get()
+        try:
+            return gate.evaluate(requisicao)
+        finally:
+            self._livres.put(gate)
+
+    def evaluate_raw(self, requisicao_json: str) -> str:
+        gate = self._livres.get()
+        try:
+            return gate.evaluate_raw(requisicao_json)
+        finally:
+            self._livres.put(gate)
+
+    def version(self) -> dict[str, Any]:
+        """A versao do motor, pedida a uma instancia LIVRE.
+
+        Isto era `return self._todas[0].version()`, e o comentario do proprio
+        pool explica por que aquilo estava errado:
+
+          > Cada instancia WASM tem sua propria memoria linear e e
+          > single-threaded. Compartilhar uma entre threads corromperia os
+          > buffers de entrada e saida — duas requisicoes escreveriam na mesma
+          > area.
+
+        `self._todas[0]` alcanca a instancia 0 sem passar pela fila de livres.
+        Enquanto uma thread avalia uma decisao nela, outra chamando `version()`
+        escreve na MESMA area de saida — e a decisao que volta e a que ficou
+        por ultimo. Nao ha erro, nao ha excecao: sai um veredito trocado, ou um
+        JSON meio de cada, de forma intermitente e sob carga.
+
+        Um painel que mostra a versao do motor ao lado das decisoes basta para
+        disparar isso, e o sintoma nao aponta para lugar nenhum.
+
+        O conserto e usar a mesma disciplina de `evaluate_raw`: pegar da fila,
+        devolver no `finally`. `version()` e barata, e a alternativa —
+        memoizar a versao no construtor — economizaria uma passagem pela fila
+        ao custo de o pool poder mentir sobre o que esta carregado.
+        """
+        gate = self._livres.get()
+        try:
+            return gate.version()
+        finally:
+            self._livres.put(gate)
+
+
+__all__.append("PolicyGatePool")

fazflow_policy_gate-0.1.0/fazflow_policy_gate.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: fazflow-policy-gate
+Version: 0.1.0
+Summary: Governança de agentes de IA: decide cada ação antes que ela aconteça. Binding sobre o artefato WASM, sem lógica de decisão.
+License: Apache-2.0
+Project-URL: Homepage, https://fazflow.com
+Project-URL: Repository, https://github.com/JulioCesar1582/FazFlow-IA
+Project-URL: Issues, https://github.com/JulioCesar1582/FazFlow-IA/issues
+Keywords: ai-agents,authorization,policy,cedar,governance,audit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Natural Language :: Portuguese (Brazilian)
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: wasmtime>=25
+
+# fazflow-policy-gate
+
+Decide cada ação de um agente de IA **antes** que ela aconteça, e registra a
+decisão numa cadeia verificável.
+
+A decisão é local: o motor roda dentro do seu processo, e os argumentos da
+requisição nunca saem da sua infraestrutura.
+
+## Instalar
+
+```bash
+pip install fazflow-policy-gate
+```
+
+O artefato WebAssembly viaja dentro do pacote. Não há passo de download.
+
+## Usar
+
+```python
+from fazflow_policy_gate import PolicyGate
+
+gate = PolicyGate.load()
+gate.load_bundle({"versao": "v1", "politicas": fonte_cedar})
+
+d = gate.evaluate({
+    "user": 'User::"u_8891"',
+    "agent": 'Agent::"copiloto"',
+    "action": "Tool::query",
+    "resource": 'Dataset::"notas"',
+    "context": contexto,   # os 14 campos
+    "entities": entidades, # User, Agent, Workload e o recurso
+})
+
+if d["verdict"] == "Deny":
+    raise RuntimeError(d["reason_code"])
+```
+
+## Duas camadas
+
+A política é avaliada em duas camadas — a do usuário e a do agente — e **as
+duas precisam permitir**. Uma política só com `principal is Agent` responde
+`Deny` com `DeniedNoUserPermit`, e é o erro mais comum do primeiro dia.
+
+## Obrigações
+
+Quando o veredito é `Transform`, `d["obligations"]` traz o que precisa ser
+feito — `mascarar:cpf,email`, `truncar:100`. **Aplicá-las é responsabilidade de
+quem chamou.** O SDK não toca no dado: ele não viu o conteúdo e não está no
+caminho da resposta.
+
+Ignorar uma obrigação é o modo de falha mais silencioso do sistema: o log
+registra que a máscara foi exigida, a auditoria vê que foi exigida, e o dado
+saiu inteiro.
+
+## Concorrência
+
+Cada instância WASM é single-threaded. Sob concorrência use `PolicyGatePool`,
+que mantém uma instância por thread lógica. Não chame métodos da instância crua
+enquanto outra thread avalia — os buffers são compartilhados.
+
+## O hash
+
+`gate.version()["artefato_hash"]` é o `sha256` do artefato que foi de fato
+instanciado, e é o mesmo valor que entra em cada decisão como `engine_hash`.
+Compará-lo com o que o painel mostra prova que o binário que decidiu é o que
+você conferiu.
+
+## Licença
+
+Apache-2.0

fazflow_policy_gate-0.1.0/fazflow_policy_gate.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+fazflow_policy_gate/__init__.py
+fazflow_policy_gate/policycore_wasm.wasm
+fazflow_policy_gate.egg-info/PKG-INFO
+fazflow_policy_gate.egg-info/SOURCES.txt
+fazflow_policy_gate.egg-info/dependency_links.txt
+fazflow_policy_gate.egg-info/requires.txt
+fazflow_policy_gate.egg-info/top_level.txt
+tests/test_gate.py

fazflow_policy_gate-0.1.0/fazflow_policy_gate.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fazflow_policy_gate-0.1.0/fazflow_policy_gate.egg-info/requires.txt

@@ -0,0 +1 @@
+wasmtime>=25

fazflow_policy_gate-0.1.0/fazflow_policy_gate.egg-info/top_level.txt

@@ -0,0 +1 @@
+fazflow_policy_gate

fazflow_policy_gate-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "fazflow-policy-gate"
+version = "0.1.0"
+description = "Governança de agentes de IA: decide cada ação antes que ela aconteça. Binding sobre o artefato WASM, sem lógica de decisão."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+keywords = ["ai-agents", "authorization", "policy", "cedar", "governance", "audit"]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Natural Language :: Portuguese (Brazilian)",
+]
+
+# `wasmtime` e a unica. O SDK TypeScript tem zero dependencias porque o Node
+# traz `WebAssembly` embutido; o Python nao traz, e um runtime WASM precisa vir
+# de algum lugar.
+dependencies = ["wasmtime>=25"]
+
+[project.urls]
+Homepage = "https://fazflow.com"
+Repository = "https://github.com/JulioCesar1582/FazFlow-IA"
+Issues = "https://github.com/JulioCesar1582/FazFlow-IA/issues"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["fazflow_policy_gate*"]
+
+# O artefato viaja DENTRO do pacote.
+#
+# Sem isto, `pip install` entregaria um SDK que na primeira chamada pede um
+# arquivo que a pessoa nao tem — e o beco que este pacote existe para evitar
+# seria o primeiro passo dele.
+[tool.setuptools.package-data]
+fazflow_policy_gate = ["*.wasm"]

fazflow_policy_gate-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fazflow_policy_gate-0.1.0/tests/test_gate.py

@@ -0,0 +1,315 @@
+"""M4 — testes do binding Python.
+
+A51 (paridade entre SDKs) vive em `conformance/diferencial.py`, que compara a
+saida crua deste SDK com a dos outros. Aqui ficam os casos do binding em si,
+mais A54, que so e testavel numa linguagem com threads de verdade.
+
+    python -m pytest sdk/py/tests -q
+    python sdk/py/tests/test_gate.py     (sem pytest)
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import time
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+RAIZ = Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(RAIZ / "sdk" / "py"))
+
+from fazflow_policy_gate import PolicyGate, PolicyGateError, PolicyGatePool  # noqa: E402
+
+WASM = RAIZ / "target" / "wasm32-unknown-unknown" / "release" / "policycore_wasm.wasm"
+
+BUNDLE = {
+    "versao": "v-teste",
+    "politicas": """
+        @id("u-leitura")
+        permit (principal is User, action == Action::"Tool::query", resource is Dataset);
+        @id("a-leitura")
+        permit (principal is Agent, action == Action::"Tool::query", resource is Dataset);
+        @id("mascara")
+        @obligation("mascarar:cpf,email")
+        permit (principal is User, action == Action::"Tool::query", resource is Dataset)
+        when { resource.contem_pessoal };
+    """,
+}
+
+
+def requisicao(**extra):
+    contexto = {
+        "agora_epoch": 1754661600,
+        "hora_local": 14,
+        "assurance": 2,
+        "delegation_depth": 1,
+        "delegation_chain": ["u_8891"],
+        "delegation_unique": 1,
+        "manifest_hash": "sha256:abc",
+        "classificacao": 1,
+        "contem_pessoal": False,
+        "injection_score": 2,
+        "grounding_score": 95,
+        "custo_mes_centavos": 1000,
+        "origem_input": "usuario",
+        "ambiente": "prod",
+    }
+    contexto.update(extra)
+    return {
+        "user": 'User::"u_8891"',
+        "agent": 'Agent::"bioman-analise"',
+        "action": "Tool::query",
+        "resource": 'Dataset::"notas"',
+        "context": contexto,
+        "entities": [
+            {"uid": {"type": "User", "id": "u_8891"},
+             "attrs": {"departamento": "x", "nivel": 3, "grupos": []}, "parents": []},
+            {"uid": {"type": "Workload", "id": "wl"},
+             "attrs": {"tier": 2, "agentes_permitidos": []}, "parents": []},
+            {"uid": {"type": "Agent", "id": "bioman-analise"},
+             "attrs": {"dono": "u_8891", "manifest_hash": "sha256:abc",
+                       "workload": {"__entity": {"type": "Workload", "id": "wl"}},
+                       "modo": "enforcing"}, "parents": []},
+            {"uid": {"type": "Dataset", "id": "notas"},
+             "attrs": {"classificacao": 1, "contem_pessoal": False}, "parents": []},
+        ],
+    }
+
+
+def abrir():
+    gate = PolicyGate.load(WASM)
+    gate.load_bundle(BUNDLE)
+    return gate
+
+
+def test_caminho_feliz():
+    d = abrir().evaluate(requisicao())
+    assert d["verdict"] == "Allow"
+    assert d["reason_code"] == "PermittedByBoth"
+    assert d["matched_user_rules"] == ["u-leitura"]
+    assert d["matched_agent_rules"] == ["a-leitura"]
+    assert d["obligations"] == []
+
+
+def test_a57_float_na_fronteira():
+    try:
+        abrir().evaluate(requisicao(grounding_score=0.7))
+    except PolicyGateError as e:
+        assert e.codigo == "FloatNaFronteira"
+    else:
+        raise AssertionError("R24 — float deveria ser recusado")
+
+
+def test_a53_bundle_malformado():
+    gate = PolicyGate.load(WASM)
+    try:
+        gate.load_bundle({"versao": "v1", "politicas": "isto nao e cedar"})
+    except PolicyGateError as e:
+        assert e.codigo == "BundleInvalido"
+    else:
+        raise AssertionError("bundle invalido deveria ser recusado")
+
+
+def test_r29_campo_ausente_vira_erro_nunca_default():
+    req = requisicao()
+    del req["context"]["grounding_score"]
+    try:
+        abrir().evaluate(req)
+    except PolicyGateError as e:
+        assert e.codigo == "ContextoInvalido"
+    else:
+        raise AssertionError(
+            "o binding NAO DEVE preencher campo ausente: e assim que producao "
+            "passa a decidir diferente do que o dev testou"
+        )
+
+
+def test_a56_r28_hash_do_artefato():
+    gate = abrir()
+    v = gate.version()
+    esperado = "sha256:" + hashlib.sha256(WASM.read_bytes()).hexdigest()
+    assert v["artefato_hash"] == esperado
+    assert v["schema"] == 1
+
+
+def test_a54_r26_cem_avaliacoes_concorrentes_batem_com_o_serial():
+    """A54 — 100 avaliacoes concorrentes (pool 8) identicas ao serial.
+
+    Este e o caso que so faz sentido numa linguagem com threads de verdade.
+    Se o pool compartilhasse uma instancia, os buffers de entrada e saida se
+    embaralhariam entre threads e o resultado sairia trocado — e o teste
+    pegaria, porque compara com o resultado serial de cada requisicao.
+    """
+    requisicoes = [
+        json.dumps(requisicao(classificacao=i % 3, injection_score=i))
+        for i in range(100)
+    ]
+
+    serial = abrir()
+    esperado = [serial.evaluate_raw(r) for r in requisicoes]
+
+    pool = PolicyGatePool(WASM, BUNDLE, tamanho=8)
+    assert pool.tamanho == 8
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=8) as ex:
+        obtido = list(ex.map(pool.evaluate_raw, requisicoes))
+
+    assert obtido == esperado, "R26 — o pool DEVE dar o mesmo resultado do serial"
+
+
+def test_r26_tamanho_padrao_e_o_numero_de_cpus():
+    import os
+
+    pool = PolicyGatePool(WASM, BUNDLE)
+    assert pool.tamanho == (os.cpu_count() or 1)
+
+
+def test_r25_chamadas_intercaladas():
+    gate = abrir()
+    a = json.dumps(requisicao())
+    esperado = gate.evaluate_raw(a)
+    outra = json.dumps(requisicao(classificacao=3))
+    for i in range(200):
+        gate.evaluate_raw(outra)
+        assert gate.evaluate_raw(a) == esperado, f"R25 quebrou na iteracao {i}"
+
+
+def test_evaluate_sem_bundle():
+    try:
+        PolicyGate.load(WASM).evaluate(requisicao())
+    except PolicyGateError as e:
+        assert e.codigo == "SemBundle"
+    else:
+        raise AssertionError("deveria exigir bundle")
+
+
+
+
+def test_r26_version_nao_corrompe_avaliacao_concorrente():
+    """R26 — `version()` nao pode entrar numa instancia que outra thread usa.
+
+    Era `self._todas[0].version()`, alcancando a instancia 0 sem passar pela
+    fila de livres. Enquanto uma thread avalia nela, outra chamando `version()`
+    escreve na MESMA area de saida do WASM — e o que volta e o que ficou por
+    ultimo. Sem erro e sem excecao: veredito trocado, intermitente, sob carga.
+
+    Um painel que mostra a versao do motor ao lado das decisoes basta.
+    """
+    import threading
+
+    pool = PolicyGatePool(WASM, BUNDLE, tamanho=2)
+    erros = []
+    parar = threading.Event()
+
+    # O valor certo, obtido em serie, sem concorrencia nenhuma. Tudo que
+    # divergir disto sob carga saiu corrompido.
+    esperado = pool.version()
+
+    def decidindo():
+        while not parar.is_set():
+            try:
+                d = pool.evaluate(requisicao())
+                # O veredito deste pedido e conhecido e fixo. Qualquer outra
+                # coisa significa que a saida veio corrompida.
+                if d.get("verdict") not in ("Allow", "Transform", "Deny", "RequireApproval"):
+                    erros.append(f"veredito irreconhecivel: {d!r}")
+                elif "bundle_version" not in d:
+                    erros.append(f"decisao sem bundle_version: {d!r}")
+            except Exception as e:  # noqa: BLE001 — o teste existe para pegar isto
+                erros.append(f"avaliacao levantou {type(e).__name__}: {e}")
+                return
+
+    def perguntando():
+        while not parar.is_set():
+            try:
+                v = pool.version()
+                if v != esperado:
+                    erros.append(f"version() divergiu do serial: {v!r}")
+            except Exception as e:  # noqa: BLE001
+                erros.append(f"version() levantou {type(e).__name__}: {e}")
+                return
+
+    threads = [threading.Thread(target=decidindo) for _ in range(3)]
+    threads += [threading.Thread(target=perguntando) for _ in range(3)]
+    for t in threads:
+        t.start()
+    time.sleep(1.5)
+    parar.set()
+    for t in threads:
+        t.join(timeout=10)
+
+    assert not erros, (
+        "R26 — `version()` e `evaluate()` concorrentes se atropelaram na mesma "
+        f"instancia WASM. Primeiros erros: {erros[:3]}"
+    )
+
+
+def test_r23_rollout_repetido_nao_vaza_bundle_no_wasm():
+    """R23 — trocar de bundle nao pode deixar o anterior dentro do WASM.
+
+    Paridade com o mesmo teste do SDK TypeScript, que mediu 5,7 MB -> 25,2 MB
+    em 35 rollouts. `load_bundle` fazia `self._handle = handle` e pronto: o
+    bundle antigo continuava no registro do modulo, alcancavel por um handle
+    que ninguem mais tinha. `fz_descarregar_bundle` ja estava ligado e so era
+    usado pelo `close()`.
+
+    Mede memoria de verdade, e nao intencao: a memoria linear do WASM so
+    CRESCE — nao devolve pagina ao sistema —, entao o vazamento e permanente e
+    o sintoma aparece semanas depois como "o gate foi ficando pesado".
+    """
+    gate = abrir()
+
+    def grande(n: int) -> dict[str, str]:
+        regras = []
+        for i in range(200):
+            nivel = (i % 3) + 1
+            regras.append(
+                '@id("r%d-%d")\n'
+                'permit (principal is User, action == Action::"Tool::query", '
+                "resource is Dataset)\n"
+                "when { context.classificacao <= %d };" % (n, i, nivel)
+            )
+        return {"versao": "v%d" % n, "politicas": "\n".join(regras)}
+
+    for i in range(5):
+        gate.load_bundle(grande(i))
+    aquecido = gate.memoria_em_bytes()
+
+    for i in range(5, 40):
+        gate.load_bundle(grande(i))
+    depois = gate.memoria_em_bytes()
+
+    assert depois == aquecido, (
+        "R23 — 35 rollouts a mais levaram a memoria do WASM de %d para %d bytes. "
+        "Cada bundle fica no registro do modulo se o anterior nao for "
+        "descarregado, e a memoria linear nunca encolhe." % (aquecido, depois)
+    )
+
+    # E o gate continua decidindo com o bundle mais recente: descarregar cedo
+    # demais trocaria um vazamento por uma indisponibilidade.
+    assert gate.evaluate(requisicao()).get("verdict")
+
+
+# O descobridor fica no FIM do arquivo, e nao no meio.
+#
+# Python executa o modulo de cima para baixo: com este bloco na linha 188, todo
+# `def test_` escrito DEPOIS dele nunca entrava em `globals()` a tempo de ser
+# coletado. O teste era escrito, o arquivo rodava, a contagem subia um a menos,
+# e nada acusava — a mesma classe de defeito que fazia `npm test` ignorar
+# arquivo novo em `app/`.
+#
+# Um teste que a suite nao executa e um teste que nao existe.
+if __name__ == "__main__":
+    testes = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    falhas = 0
+    for t in testes:
+        try:
+            t()
+            print(f"  ok    {t.__name__}")
+        except Exception as e:  # noqa: BLE001
+            falhas += 1
+            print(f"  FALHA {t.__name__}: {e}")
+    print(f"\n{len(testes) - falhas}/{len(testes)} passaram")
+    raise SystemExit(1 if falhas else 0)