Implement pure-function GovernanceEngine for state transition evaluation

[Soushi888]

Summary

Implement a GovernanceEngine with pure-function evaluation logic that determines whether a requested state transition should be approved or rejected. This is the core decision-making component of the governance-as-operator pattern.

Context

Currently, governance operations (economic events, commitments, validation receipts) are independent CRUD functions. The governance-as-operator architecture requires a centralized evaluation engine that:

• Checks agent permissions and roles
• Evaluates applicable governance rules
• Validates state transition legality
• Returns a comprehensive decision with rationale

The engine must be a pure function (no side effects) so it can be unit tested independently.

Technical Implementation

1. GovernanceEngine Core

pub struct GovernanceEngine;

impl GovernanceEngine {
    /// Pure function: evaluates state transition without side effects
    pub fn evaluate_transition(
        request: &GovernanceTransitionRequest,
        rules: &[GovernanceRule],
        agent_permissions: &AgentPermissions,
    ) -> ExternResult<TransitionEvaluation> {
        // 1. Validate agent permissions
        // 2. Evaluate applicable governance rules
        // 3. Check state transition validity
        // 4. Combine all evaluations into final decision
    }
}

2. Permission Evaluation

• Check agent roles against action requirements using existing role system
• Map VfAction variants to required roles (already partially defined in get_required_roles_for_action)
• Return structured permission results

3. Rule Evaluation

• Load governance rules from resource specification
• Evaluate each rule type: access_requirement, usage_limit, transfer_conditions, custody_requirement, location_restriction
• Return per-rule pass/fail results with reasons

4. State Transition Validation

• Validate action compatibility with current resource state (e.g., can't use a retired resource)
• Calculate new resource state based on action and context
• Validate quantity changes are within bounds

5. Exported Zome Function

#[hdk_extern]
pub fn evaluate_state_transition(
    request: GovernanceTransitionRequest,
) -> ExternResult<GovernanceTransitionResult> {
    let rules = load_applicable_rules(&request.resource)?;
    let permissions = check_agent_permissions(&request.requesting_agent, &request.action)?;
    let evaluation = GovernanceEngine::evaluate_transition(&request, &rules, &permissions)?;
    // ... build and return GovernanceTransitionResult
}

Acceptance Criteria

• GovernanceEngine::evaluate_transition() implemented as a pure function
• Permission evaluation checks agent roles against action requirements
• Rule evaluation supports at least: access requirements, usage limits, transfer conditions
• State transition validation rejects invalid action/state combinations
• evaluate_state_transition hdk_extern function exposed for cross-zome calls
• Comprehensive unit tests for the pure function (permission checks, rule evaluation, state validation)
• Tests cover: approved transitions, permission denials, rule violations, invalid state transitions
• Rejection results include actionable rejection_reasons and next_steps

Dependencies

• Define cross-zome interface types for governance-as-operator protocol #41 (Cross-zome interface types)

Definition of Done

• GovernanceEngine implemented and tested
• All unit tests pass
• Integration with existing role system verified
• Code review completed