Define cross-zome interface types for governance-as-operator protocol

[Soushi888]

Summary

Define the shared data structures that enable the governance-as-operator pattern: the Resource Zome requests state transitions, the Governance Zome evaluates and decides, and the Resource Zome applies approved changes.

These types form the communication contract between the resource and governance zomes.

Context

The governance-as-operator architecture (see documentation/specifications/governance/governance-operator-architecture.md) establishes a clear separation where:

• Resource Zome = pure data model (CRUD, no business logic)
• Governance Zome = state transition operator (rule evaluation, permission validation)

This issue creates the foundational types that both zomes depend on.

Technical Implementation

1. Core Request/Result Types

Define in a shared location (e.g., nondominium_utils or a new shared types crate):

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct GovernanceTransitionRequest {
    pub action: VfAction,
    pub resource: EconomicResource,
    pub requesting_agent: AgentPubKey,
    pub context: TransitionContext,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct TransitionContext {
    pub target_location: Option<String>,
    pub quantity_change: Option<f64>,
    pub target_custodian: Option<AgentPubKey>,
    pub process_notes: Option<String>,
    pub process_context: Option<ActionHash>,
}

#[derive(Serialize, Deserialize, Debug)]
pub struct GovernanceTransitionResult {
    pub success: bool,
    pub new_resource_state: Option<EconomicResource>,
    pub economic_event: Option<EconomicEvent>,
    pub validation_receipts: Vec<ValidationReceipt>,
    pub rejection_reasons: Option<Vec<String>>,
    pub next_steps: Option<Vec<String>>,
}

2. Governance Decision Tracking

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct GovernanceDecision {
    pub approved: bool,
    pub evaluated_rules: Vec<ActionHash>,
    pub role_permissions: Vec<RolePermissionResult>,
    pub validation_constraints: Vec<ValidationConstraint>,
    pub rationale: String,
}

#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ResourceStateChange {
    pub original_resource_hash: ActionHash,
    pub new_resource_hash: ActionHash,
    pub triggering_action: VfAction,
    pub initiated_by: AgentPubKey,
    pub governance_decision: GovernanceDecision,
    pub economic_event: EconomicEvent,
    pub changed_at: Timestamp,
}

3. Error Types

#[derive(Debug, Serialize, Deserialize)]
pub enum GovernanceOperatorError {
    PermissionDenied(String),
    RuleViolation(String),
    InvalidStateTransition(String),
    ResourceNotFound(String),
    CrossZomeCallFailed(String),
    ValidationError(String),
}

4. Placement Decision

Decide whether to:

• Extend nondominium_utils crate with these types
• Create a new nondominium_types shared crate
• Place in governance integrity zome and import from resource zome

Acceptance Criteria

• GovernanceTransitionRequest and TransitionContext defined and serializable
• GovernanceTransitionResult defined with all fields
• GovernanceDecision and ResourceStateChange defined
• GovernanceOperatorError enum covers cross-zome failure modes
• Types are accessible from both resource and governance zomes
• Serde serialization/deserialization works across zome boundaries
• Unit tests for serialization round-trips
• Types documented with rustdoc comments

Dependencies

• None (foundational types)

Definition of Done

• Types compile and are importable from both zomes
• Serialization tests pass
• Documentation updated
• Code review completed