RFC-014: Contract Governor Shared Infrastructure — 7. Runtime Integration

AIGP Specification › RFC-014: Contract Governor Shared Infrastructure › 7. Runtime Integration

← 6. Version Management · Section index · 8. Testing →

7. Runtime Integration

7.1 Singleton Initialization

Each amigo initializes the validator once at startup. The validator is a singleton one instance per application process, cached for the lifetime of the process.

from contract_governor import ContractGovernor, StipulationConfig
from contract_governor.core.registry import InMemoryContractRegistry

# Load once at startup
_validator: ContractGovernor | None = None

def get_validator() -> ContractGovernor:
    """Singleton accessor  initialized once, cached forever."""
    global _validator
    if _validator is None:
        registry = InMemoryContractRegistry()
        stipulations = load_stipulations("ingredients/stipulation-gandalf-v1.yaml")
        _validator = ContractGovernor(
            registry=registry,
            stipulations=stipulations,
        )
        # Load the contract
        _validator.registry.store_raw_contract(
            load_yaml("ingredients/gandalf-api.yaml")
        )
    return _validator

7.2 Pre-Operation Validation

Every Gandalf action calls validate_operation() before execution:

async def execute_gandalf_action(operation_id: str, payload: dict) -> dict:
    """Every Gandalf action is validated before execution."""
    validator = get_validator()

    # Validate the operation against the contract and stipulations
    result: ValidationResult = validator.validate_operation(
        operation_id=operation_id,
        payload=payload,
    )

    if not result.valid:
        raise StipulationViolationError(
            f"Operation '{operation_id}' blocked by stipulation: {result.errors}"
        )

    # Operation is allowed  proceed
    return await run_operation(operation_id, payload)

7.3 Integration Points

Amigo	Integration Point	When
identity-service	FastAPI middleware / dependency	Before every /api/v1/ingredients/* handler
analytics-service	FastAPI middleware / dependency	Before every /api/v1/* handler
governance-server	Internal validation layer	Before policy evaluation
runbook-service	Execution orchestrator	Before dispatching any agent action

7.4 Lifecycle

Application Start

   Load contract (ingredients/gandalf-api.yaml)
   Load stipulations (ingredients/stipulation-*.yaml)
   Initialize ContractGovernor singleton
   Validate contract against stipulations (fail-fast)


Application Running

   Request arrives
   validator.validate_operation(operation_id, payload)
   If valid  execute
   If invalid  reject with StipulationViolationError


Application Shutdown

   Singleton garbage collected (no cleanup needed)

---

← 6. Version Management · Section index · 8. Testing →