feat: add decision runtime conformance with optional OPA adapter

[marcialwushu]

Contexto

O PRD as a Code já possui DecisionSpec, evaluateDecision(), casos de decisão e o roadmap de comparação diferencial. Este PR formaliza esse comportamento como uma semântica de referência e adiciona um primeiro runtime candidato: OPA/Rego.

A intenção não é transformar OPA na autoridade semântica do produto nem adicionar um policy server. O objetivo é provar que uma decisão especificada no framework pode ser portada para outro runtime sem alterar o comportamento declarado.

O que muda

• adiciona a porta DecisionRuntime;
• formaliza ReferenceDecisionRuntime sobre o evaluateDecision() existente;
• adiciona conformDecision() para comparar casos declarados entre reference e runtime candidato;
• adiciona um gerador Rego limitado ao subconjunto atual de dmn-table/v1;
• adiciona OpaDecisionRuntime, executado por opa eval;
• adiciona:

  prd conformance decision DEC-001 --runtime reference
  prd conformance decision DEC-001 --runtime opa
  

• adiciona testes de conformidade e detecção de divergência;
• documenta explicitamente que OPA é opcional e não expande a semântica DMN atual.

Limites intencionais

Este PR não:

• muda Decision.schema.json;
• adiciona operadores novos;
• executa BusinessRule SBVR;
• adiciona servidor OPA;
• baixa o binário OPA;
• adiciona Fact Resolver;
• adiciona execução de aplicação/step definitions.

O DecisionSpec atual continua sendo a representação executável da v0.3 e evaluateDecision() continua sendo a referência.

Arquitetura

Decision YAML
     |
 DecisionSpec
     |
     +---------------------+
     |                     |
Reference Runtime       OPA Adapter
evaluateDecision()          |
     |                    Rego
     |                      |
     |                     OPA
     +----------+-----------+
                |
          Conformance

Próximo PR proposto

Adicionar uma porta/protocolo de Fact Resolver conformance, permitindo testar:

raw fixture -> resolver externo -> canonical Decision input

sem introduzir SQL/Mongo/Redis no core do framework.

Verificação

• novos testes cobrem runtime de referência;
• runtime candidato propositalmente divergente é detectado;
• gerador Rego é testado sem exigir OPA instalado no CI;
• OPA real é dependência opcional para o comando --runtime opa.

[Copilot]

Copilot review overview

🟡 Changes recommended

Runtime failures are misreported as divergences, scalar equality changes existing semantics, and the OPA process protocol lacks tests.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Avoid signed-zero mismatches in decision comparison · New
• Propagate OPA runtime errors instead of reporting divergence · New
• Add process-boundary tests for OPA adapter failures · New

What changed in this PR

Adds a reference decision-runtime contract and optional OPA/Rego adapter for conformance testing.

Changes:

• Introduces runtime and conformance APIs.
• Adds reference and OPA implementations plus CLI integration.
• Adds tests, capability declarations, and documentation.

File	Description
src/​application/​ports/​decision-runtime.ts	Defines the runtime contract.
src/​application/​decision-conformance.ts	Compares declared cases across runtimes.
src/​infrastructure/​reference/​reference-decision-runtime.ts	Wraps native decision evaluation.
src/​infrastructure/​opa/​rego-generator.ts	Generates Rego policies.
src/​infrastructure/​opa/​opa-decision-runtime.ts	Executes decisions through OPA.
src/​interfaces/​cli/​main.ts	Adds conformance commands.
src/​index.ts	Exports the new APIs.
tests/​conformance.test.mjs	Tests conformance and generation.
framework/​capabilities.json	Declares runtime capabilities.
README.md	Documents CLI usage.
docs/​TESTING.md	Documents conformance testing.
docs/​ROADMAP.md	Updates planned runtime work.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[marcialwushu]

Revisado