cfa-kernel 0.1.0__py3-none-any.whl

cfa/execution/state_projection.py

@@ -0,0 +1,216 @@
+"""
+CFA State Projection Protocol
+==============================
+Projects execution outcomes into the Context Registry.
+
+After every execution (successful, partial, or failed), the State Projection
+Protocol updates the Context Registry to reflect "what state is the data in now".
+
+This is Invariant I4: Mandatory Projection — the Context Registry MUST be updated
+after every execution. Invariant I6 (Safe Execution) takes precedence: if execution
+was rolled back, the projection reflects that.
+
+The protocol:
+1. Reads execution outcome (PartialExecutionState or SandboxResult)
+2. Projects dataset states (committed, quarantined, rolled_back, degraded)
+3. Updates Context Registry with new dataset states
+4. Takes a snapshot for reproducibility (Invariant I8)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cfa.audit.context import ContextRegistry
+from cfa.execution.partial import PartialExecutionState, PublishState
+from cfa.types import StateSignature, _utcnow
+
+# ── Projection Result ───────────────────────────────────────────────────────
+
+
+@dataclass
+class ProjectionResult:
+    """Result of projecting execution state into the Context Registry."""
+
+    projected: bool
+    snapshot_version: str = ""
+    dataset_states_updated: list[str] = None  # type: ignore[assignment]
+    projection_type: str = ""  # "full", "partial", "rollback", "degraded"
+    audit_only: bool = False
+
+    def __post_init__(self) -> None:
+        if self.dataset_states_updated is None:
+            self.dataset_states_updated = []
+
+
+# ── State Projection Protocol ───────────────────────────────────────────────
+
+
+class StateProjectionProtocol:
+    """
+    Projects execution outcomes into the Context Registry (Invariant I4).
+
+    Called by the Kernel after sandbox execution completes.
+    Always creates a snapshot for reproducibility.
+    """
+
+    def __init__(self, context_registry: ContextRegistry) -> None:
+        self.registry = context_registry
+
+    def project(
+        self,
+        signature: StateSignature,
+        execution_state: PartialExecutionState,
+    ) -> ProjectionResult:
+        """Project execution state into the Context Registry."""
+        now = _utcnow().isoformat()
+        target_scope = [signature.target_dataset_name]
+
+        match execution_state.publish_state:
+            case PublishState.PUBLISHED:
+                return self._project_published(signature, execution_state, target_scope, now)
+
+            case PublishState.DEGRADED:
+                return self._project_degraded(signature, execution_state, target_scope, now)
+
+            case PublishState.COMMITTED_NOT_PUBLISHED:
+                return self._project_committed_not_published(
+                    signature, execution_state, target_scope, now
+                )
+
+            case PublishState.QUARANTINED:
+                return self._project_quarantined(signature, execution_state, target_scope, now)
+
+            case PublishState.ROLLED_BACK:
+                return self._project_rolled_back(signature, execution_state, target_scope, now)
+
+            case _:
+                return ProjectionResult(projected=False, projection_type="unknown")
+
+    def _project_published(
+        self,
+        signature: StateSignature,
+        execution_state: PartialExecutionState,
+        datasets: list[str],
+        timestamp: str,
+    ) -> ProjectionResult:
+        metrics = {}
+        if execution_state.sandbox_result:
+            m = execution_state.sandbox_result.aggregate_metrics
+            metrics = {
+                "rows_output": m.rows_output,
+                "cost_dbu": m.cost_dbu,
+                "duration_seconds": m.duration_seconds,
+            }
+
+        for ds_name in datasets:
+            self.registry.set_dataset_state(ds_name, {
+                "state": "published",
+                "signature_hash": signature.signature_hash,
+                "target_layer": signature.target_layer.value,
+                "last_updated": timestamp,
+                "metrics": metrics,
+            })
+
+        snapshot_id = self.registry.snapshot()
+        return ProjectionResult(
+            projected=True,
+            snapshot_version=snapshot_id,
+            dataset_states_updated=datasets,
+            projection_type="full",
+        )
+
+    def _project_degraded(
+        self,
+        signature: StateSignature,
+        execution_state: PartialExecutionState,
+        datasets: list[str],
+        timestamp: str,
+    ) -> ProjectionResult:
+        updated = []
+        for ds_name in datasets:
+            self.registry.set_dataset_state(ds_name, {
+                "state": "degraded",
+                "signature_hash": signature.signature_hash,
+                "target_layer": signature.target_layer.value,
+                "last_updated": timestamp,
+                "quarantined_steps": execution_state.quarantined_steps,
+                "committed_steps": execution_state.committed_steps,
+            })
+            updated.append(ds_name)
+
+        snapshot_id = self.registry.snapshot()
+        return ProjectionResult(
+            projected=True,
+            snapshot_version=snapshot_id,
+            dataset_states_updated=updated,
+            projection_type="degraded",
+        )
+
+    def _project_committed_not_published(
+        self,
+        signature: StateSignature,
+        execution_state: PartialExecutionState,
+        datasets: list[str],
+        timestamp: str,
+    ) -> ProjectionResult:
+        updated = []
+        for ds_name in datasets:
+            self.registry.set_dataset_state(ds_name, {
+                "state": "committed_not_published",
+                "signature_hash": signature.signature_hash,
+                "target_layer": signature.target_layer.value,
+                "last_updated": timestamp,
+                "committed_steps": execution_state.committed_steps,
+                "quarantined_steps": execution_state.quarantined_steps,
+            })
+            updated.append(ds_name)
+
+        snapshot_id = self.registry.snapshot()
+        return ProjectionResult(
+            projected=True,
+            snapshot_version=snapshot_id,
+            dataset_states_updated=updated,
+            projection_type="partial",
+        )
+
+    def _project_quarantined(
+        self,
+        signature: StateSignature,
+        execution_state: PartialExecutionState,
+        datasets: list[str],
+        timestamp: str,
+    ) -> ProjectionResult:
+        updated = []
+        for ds_name in datasets:
+            self.registry.set_dataset_state(ds_name, {
+                "state": "quarantined",
+                "signature_hash": signature.signature_hash,
+                "target_layer": signature.target_layer.value,
+                "last_updated": timestamp,
+                "quarantined_steps": execution_state.quarantined_steps,
+            })
+            updated.append(ds_name)
+
+        snapshot_id = self.registry.snapshot()
+        return ProjectionResult(
+            projected=True,
+            snapshot_version=snapshot_id,
+            dataset_states_updated=updated,
+            projection_type="quarantine",
+        )
+
+    def _project_rolled_back(
+        self,
+        signature: StateSignature,
+        execution_state: PartialExecutionState,
+        datasets: list[str],
+        timestamp: str,
+    ) -> ProjectionResult:
+        return ProjectionResult(
+            projected=False,
+            snapshot_version="",
+            dataset_states_updated=[],
+            projection_type="rollback",
+            audit_only=True,
+        )

cfa/governance/__init__.py

@@ -0,0 +1,76 @@
+"""
+cfa.governance -- Governanca standalone
+========================================
+Valida operacoes de dados contra regras de governanca SEM precisar de LLM,
+SEM executar codigo, SEM infraestrutura.
+
+Funciona em cima de qualquer pipeline existente (Airflow, Dagster, scripts).
+Voce monta a StateSignature a mao e valida.
+
+Uso:
+    from cfa.governance import PolicyEngine, StaticValidator, StateSignature
+
+    # Monta a signature do que voce quer fazer
+    sig = StateSignature(
+        domain="fiscal",
+        intent="reconciliation",
+        target_layer=TargetLayer.SILVER,
+        datasets=(DatasetRef("nfe", DatasetClassification.HIGH_VOLUME),),
+        constraints=SignatureConstraints(partition_by=("processing_date",)),
+        execution_context=ExecutionContext("v1", "c1", "r1"),
+    )
+
+    # Valida contra regras de governanca
+    engine = PolicyEngine()
+    result = engine.evaluate(sig)
+    if result.action == PolicyAction.BLOCK:
+        raise Exception(f"Blocked: {result.reasoning}")
+
+    # Valida codigo gerado (opcional)
+    validator = StaticValidator()
+    sv = validator.validate(code, sig)
+    if not sv.passed:
+        raise Exception(f"Static validation failed: {sv.fault_codes}")
+"""
+
+from cfa.policy.engine import PolicyEngine, PolicyRule, build_default_ruleset
+from cfa.types import (
+    DatasetClassification,
+    DatasetRef,
+    ExecutionContext,
+    Fault,
+    FaultFamily,
+    FaultSeverity,
+    PolicyAction,
+    PolicyResult,
+    SignatureConstraints,
+    StateSignature,
+    TargetLayer,
+)
+from cfa.validation.runtime import RuntimeThresholds, RuntimeValidationResult, RuntimeValidator
+from cfa.validation.static import StaticValidationResult, StaticValidator
+
+__all__ = [
+    # Types
+    "DatasetClassification",
+    "DatasetRef",
+    "ExecutionContext",
+    "Fault",
+    "FaultFamily",
+    "FaultSeverity",
+    "PolicyAction",
+    "PolicyResult",
+    "SignatureConstraints",
+    "StateSignature",
+    "TargetLayer",
+    # Policy
+    "PolicyEngine",
+    "PolicyRule",
+    "build_default_ruleset",
+    # Validation
+    "StaticValidator",
+    "StaticValidationResult",
+    "RuntimeValidator",
+    "RuntimeThresholds",
+    "RuntimeValidationResult",
+]

cfa/lifecycle/__init__.py

@@ -0,0 +1,51 @@
+"""
+cfa.lifecycle -- Lifecycle de intencoes
+========================================
+Indices (IFo, IFs, IFg, IDI) e Promotion/Demotion Engine.
+Transforma intencoes repetitivas em skills industrializadas.
+
+Uso:
+    from cfa.lifecycle import (
+        PromotionEngine, PromotionPolicy,
+        IndexCalculator, ExecutionRecord,
+        SkillState,
+    )
+
+    engine = PromotionEngine(policy=PromotionPolicy(min_executions=5))
+
+    # Registrar execucoes
+    engine.record_execution(ExecutionRecord(
+        signature_hash="abc123",
+        timestamp=datetime.now(timezone.utc),
+        success=True,
+        cost_dbu=5.0,
+        duration_seconds=30.0,
+    ))
+
+    # Avaliar promocao
+    skill, scores = engine.evaluate("abc123")
+    print(f"State: {skill.state.value}")
+    print(f"IFo={scores.ifo:.2f} IFs={scores.ifs:.2f} IFg={scores.ifg} IDI={scores.idi:.2f}")
+"""
+
+from cfa.observability.indices import ExecutionRecord, IndexCalculator, IndexScores
+from cfa.observability.promotion import (
+    PromotionEngine,
+    PromotionPolicy,
+    SkillGenerationMetadata,
+    SkillRecord,
+    SkillState,
+)
+
+__all__ = [
+    # Indices
+    "ExecutionRecord",
+    "IndexCalculator",
+    "IndexScores",
+    # Promotion
+    "PromotionEngine",
+    "PromotionPolicy",
+    "SkillGenerationMetadata",
+    "SkillRecord",
+    "SkillState",
+]

cfa/mcp/__init__.py

@@ -0,0 +1,347 @@
+"""
+CFA MCP Server
+==============
+Model Context Protocol server exposing CFA governance tools to AI agents.
+
+Tools exposed:
+- cfa_evaluate_signature  — Evaluate a StateSignature against policy
+- cfa_describe_rules      — List all active policy rules
+- cfa_explain_fault       — Explain a fault code with remediation
+- cfa_audit_check         — Verify audit chain integrity
+- cfa_list_backends       — List registered codegen backends
+
+Zero external dependencies — pure stdlib JSON-RPC over stdio.
+Compatible with Claude Desktop, Cursor, Windsurf, Copilot, and any MCP client.
+
+Usage:
+    python -m cfa.mcp          # run as stdio server
+    cfa-mcp                    # via console script (pip install)
+
+Config (claude_desktop_config.json):
+    {
+      "mcpServers": {
+        "cfa": {
+          "command": "python", "args": ["-m", "cfa.mcp"]
+        }
+      }
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from cfa.policy.bundle import PolicyBundle
+from cfa.policy.engine import PolicyEngine
+from cfa.types import StateSignature
+
+from ..backends import BackendRegistry
+
+SERVER_NAME = "cfa-mcp"
+SERVER_VERSION = "1.0.0"
+
+# ── Tool implementations ─────────────────────────────────────────────────────
+
+
+def tool_evaluate_signature(args: dict[str, Any]) -> dict[str, Any]:
+    """Evaluate a StateSignature JSON against the active policy bundle."""
+    sig_data = args.get("signature")
+    if not sig_data:
+        return {"error": "Missing required argument: signature"}
+
+    try:
+        from cfa.types import (
+            DatasetClassification,
+            DatasetRef,
+            ExecutionContext,
+            SignatureConstraints,
+            TargetLayer,
+        )
+        layer_map = {"bronze": TargetLayer.BRONZE, "silver": TargetLayer.SILVER, "gold": TargetLayer.GOLD}
+        cls_map = {
+            "public": DatasetClassification.PUBLIC, "internal": DatasetClassification.INTERNAL,
+            "sensitive": DatasetClassification.SENSITIVE, "high_volume": DatasetClassification.HIGH_VOLUME,
+        }
+
+        datasets = tuple(
+            DatasetRef(
+                name=d["name"],
+                classification=cls_map.get(d.get("classification", "internal"), DatasetClassification.INTERNAL),
+                size_gb=d.get("size_gb", 0.0),
+                pii_columns=tuple(d.get("pii_columns", [])),
+                partition_column=d.get("partition_column"),
+            )
+            for d in sig_data.get("datasets", [])
+        )
+
+        c = sig_data.get("constraints", {})
+        constraints = SignatureConstraints(
+            no_pii_raw=c.get("no_pii_raw", True),
+            merge_key_required=c.get("merge_key_required", True),
+            enforce_types=c.get("enforce_types", True),
+            partition_by=tuple(c.get("partition_by", [])),
+            max_cost_dbu=c.get("max_cost_dbu"),
+        )
+
+        ctx = sig_data.get("execution_context", {})
+        execution_context = ExecutionContext(
+            policy_bundle_version=ctx.get("policy_bundle_version", "mcp"),
+            catalog_snapshot_version=ctx.get("catalog_snapshot_version", "mcp"),
+            context_registry_version_id=ctx.get("context_registry_version_id", "mcp"),
+        )
+
+        signature = StateSignature(
+            domain=sig_data.get("domain", ""),
+            intent=sig_data.get("intent", ""),
+            target_layer=layer_map.get(sig_data.get("target_layer", "silver"), TargetLayer.SILVER),
+            datasets=datasets,
+            constraints=constraints,
+            execution_context=execution_context,
+        )
+    except Exception as e:
+        return {"error": f"Invalid signature: {e}"}
+
+    policy_bundle = args.get("policy_bundle", "")
+    if policy_bundle:
+        try:
+            bundle = PolicyBundle.from_yaml(policy_bundle) if policy_bundle.endswith((".yaml", ".yml")) else PolicyBundle.from_json(policy_bundle)
+            engine = PolicyEngine(rules=bundle.rules, policy_bundle_version=bundle.version)
+        except Exception as e:
+            return {"error": f"Failed to load policy bundle: {e}"}
+    else:
+        engine = PolicyEngine()
+
+    result = engine.evaluate(signature)
+
+    return {
+        "action": result.action.value,
+        "passed": result.action.value == "approve",
+        "faults": [
+            {
+                "code": f.code,
+                "severity": f.severity.value,
+                "message": f.message,
+                "remediation": list(f.remediation),
+            }
+            for f in result.faults
+        ],
+        "reasoning": result.reasoning,
+        "replan_count": result.replan_count,
+    }
+
+
+def tool_describe_rules(args: dict[str, Any]) -> dict[str, Any]:
+    """List all active policy rules."""
+    policy_bundle = args.get("policy_bundle", "")
+    if policy_bundle:
+        try:
+            bundle = PolicyBundle.from_yaml(policy_bundle) if policy_bundle.endswith((".yaml", ".yml")) else PolicyBundle.from_json(policy_bundle)
+            engine = PolicyEngine(rules=bundle.rules, policy_bundle_version=bundle.version)
+        except Exception as e:
+            return {"error": f"Failed to load policy bundle: {e}"}
+    else:
+        engine = PolicyEngine()
+
+    return {
+        "policy_bundle_version": engine.policy_bundle_version,
+        "rule_count": len(engine.rules),
+        "rules": engine.describe_rules(),
+    }
+
+
+def tool_explain_fault(args: dict[str, Any]) -> dict[str, Any]:
+    """Explain a fault code with details and remediation steps."""
+    code = args.get("fault_code", "")
+    if not code:
+        return {"error": "Missing required argument: fault_code"}
+
+    engine = PolicyEngine()
+    for r in engine.rules:
+        if r.fault_code == code:
+            return {
+                "fault_code": r.fault_code,
+                "rule_name": r.name,
+                "action": r.action.value,
+                "severity": r.severity.value,
+                "family": r.fault_family.value,
+                "message": r.message,
+                "remediation": list(r.remediation),
+            }
+    return {"error": f"Unknown fault code: {code}"}
+
+
+def tool_audit_check(args: dict[str, Any]) -> dict[str, Any]:
+    """Verify audit chain integrity."""
+    from cfa.audit.trail import AuditTrail
+    trail = AuditTrail()
+    intent_id = args.get("intent_id", "")
+    if intent_id:
+        events = trail.get_events_for_intent(intent_id)
+        chain_ok = trail.verify_chain()
+        return {
+            "intent_id": intent_id,
+            "event_count": len(events),
+            "chain_intact": chain_ok,
+        }
+    chain_ok = trail.verify_chain()
+    return {
+        "total_events": trail.event_count,
+        "chain_intact": chain_ok,
+    }
+
+
+def tool_list_backends(args: dict[str, Any]) -> dict[str, Any]:
+    """List registered codegen backends with capabilities."""
+    registry = BackendRegistry.singleton()
+    names = registry.list()
+    backends: list[dict[str, Any]] = []
+    for name in names:
+        factory = registry.get(name)
+        backend = factory()
+        caps = backend.get_capabilities() if hasattr(backend, "get_capabilities") else None
+        backends.append({
+            "name": name,
+            "supports_merge": caps.supports_merge if caps else False,
+            "supports_anonymization": caps.supports_anonymization if caps else False,
+            "supports_partition_overwrite": caps.supports_partition_overwrite if caps else False,
+            "cost_model_available": caps.cost_model_available if caps else False,
+            "supported_languages": caps.supported_languages if caps else [],
+        })
+    return {"backends": backends}
+
+
+# ── Tool registry ────────────────────────────────────────────────────────────
+
+TOOLS = {
+    "cfa_evaluate_signature": {
+        "description": "Evaluate a StateSignature JSON against the active CFA policy bundle. Returns APPROVE, REPLAN, or BLOCK with faults and remediation.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "signature": {"type": "object", "description": "StateSignature JSON with domain, intent, target_layer, datasets, constraints"},
+                "policy_bundle": {"type": "string", "description": "Optional path to YAML/JSON policy bundle file"},
+            },
+            "required": ["signature"],
+        },
+        "handler": tool_evaluate_signature,
+    },
+    "cfa_describe_rules": {
+        "description": "List all active CFA policy rules with descriptions and severities.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "policy_bundle": {"type": "string", "description": "Optional path to YAML/JSON policy bundle file"},
+            },
+        },
+        "handler": tool_describe_rules,
+    },
+    "cfa_explain_fault": {
+        "description": "Explain a CFA fault code: what it means, why it occurs, and how to fix it.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "fault_code": {"type": "string", "description": "Fault code to explain, e.g. GOVERNANCE_RAW_PII_IN_PROTECTED_LAYER"},
+            },
+            "required": ["fault_code"],
+        },
+        "handler": tool_explain_fault,
+    },
+    "cfa_audit_check": {
+        "description": "Verify the integrity of the CFA audit trail hash chain.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "intent_id": {"type": "string", "description": "Optional: check audit trail for a specific intent ID"},
+            },
+        },
+        "handler": tool_audit_check,
+    },
+    "cfa_list_backends": {
+        "description": "List all registered CFA codegen backends with their capabilities.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+        },
+        "handler": tool_list_backends,
+    },
+}
+
+
+# ── JSON-RPC Server ──────────────────────────────────────────────────────────
+
+
+def _rpc_error(id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": id, "error": {"code": code, "message": message}}
+
+
+def _rpc_response(id: Any, result: Any) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": id, "result": result}
+
+
+def _handle_request(req: dict[str, Any]) -> dict[str, Any] | None:
+    method = req.get("method", "")
+    req_id = req.get("id")
+
+    if method == "initialize":
+        return _rpc_response(req_id, {
+            "protocolVersion": "2024-11-05",
+            "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION},
+            "capabilities": {"tools": {}},
+        })
+
+    if method == "notifications/initialized":
+        return None  # No response for notifications
+
+    if method == "tools/list":
+        tools_list = [
+            {
+                "name": name,
+                "description": info["description"],
+                "inputSchema": info["inputSchema"],
+            }
+            for name, info in TOOLS.items()
+        ]
+        return _rpc_response(req_id, {"tools": tools_list})
+
+    if method == "tools/call":
+        tool_name = req.get("params", {}).get("name", "")
+        tool_args = req.get("params", {}).get("arguments", {})
+
+        tool = TOOLS.get(tool_name)
+        if not tool:
+            return _rpc_error(req_id, -32601, f"Unknown tool: {tool_name}")
+
+        try:
+            result = tool["handler"](tool_args)
+            return _rpc_response(req_id, {
+                "content": [{"type": "text", "text": json.dumps(result, indent=2, default=str)}]
+            })
+        except Exception as e:
+            return _rpc_error(req_id, -32603, f"Tool error: {e}")
+
+    if method == "ping":
+        return _rpc_response(req_id, {})
+
+    return _rpc_error(req_id, -32601, f"Method not found: {method}")
+
+
+def serve() -> None:
+    """Run the MCP server on stdio (stdin/stdout JSON-RPC)."""
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        resp = _handle_request(req)
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp) + "\n")
+            sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    serve()

cfa/mcp/__main__.py

@@ -0,0 +1,4 @@
+"""Entry point for python -m cfa.mcp"""
+from cfa.mcp import serve
+
+serve()