Skip to content

governance_zome.md

Latest commit

 

History

History
860 lines (638 loc) · 34.6 KB

governance_zome.md

File metadata and controls

860 lines (638 loc) · 34.6 KB

Governance Zome (zome_gouvernance) Documentation

The Governance zome implements the core economic coordination and validation infrastructure for the nondominium ecosystem, providing ValueFlows-compliant economic event logging, commitment management, Private Participation Receipt (PPR) reputation system, and comprehensive agent validation workflows. It serves as the governance backbone enabling decentralized resource sharing with embedded accountability and cryptographically-secured reputation tracking.

Post-MVP (target architecture): unified transition evaluation is specified to optionally enforce Unyt economic closure (EconomicAgreement rules, rave_hash; documentation/requirements/ndo_prima_materia.md §6.6) and Flowsta identity checks (IdentityVerification, FlowstaIdentity; §6.7). See documentation/archives/governance.md §3.7, documentation/requirements/post-mvp/unyt-integration.md, and documentation/requirements/post-mvp/flowsta-integration.md. MVP coordinator paths (e.g. promotion validation) precede that consolidation.

Core Data Structures

VfAction Enum

pub enum VfAction {
    // Standard ValueFlows transfer actions
    Transfer,        // Transfer ownership/custody
    Move,           // Move a resource from one location to another

    // Standard ValueFlows production/consumption actions
    Use,            // Use a resource without consuming it
    Consume,        // Consume/destroy a resource
    Produce,        // Create/produce a new resource
    Work,           // Apply work/labor to a resource

    // Standard ValueFlows modification actions
    Modify,         // Modify an existing resource
    Combine,        // Combine multiple resources
    Separate,       // Separate one resource into multiple

    // Standard ValueFlows quantity adjustment actions
    Raise,          // Increase quantity/value of a resource
    Lower,          // Decrease quantity/value of a resource

    // Standard ValueFlows citation/reference actions
    Cite,           // Reference or cite a resource
    Accept,         // Accept delivery or responsibility

    // nondominium-specific actions
    InitialTransfer, // First transfer by a Simple Agent
    AccessForUse,    // Request access to use a resource
    TransferCustody, // Transfer custody (nondominium specific)
}

ValueFlows Compliance: Complete economic action vocabulary supporting all standard and nondominium-specific actions Type Safety: Replaces string-based actions with compile-time validation Helper Methods: Resource validation, quantity modification, custody change detection

VfAction Helper Methods

impl VfAction {
    pub fn requires_existing_resource(&self) -> bool;  // Resource validation
    pub fn creates_resource(&self) -> bool;            // New resource detection
    pub fn modifies_quantity(&self) -> bool;           // Quantity change detection
    pub fn changes_custody(&self) -> bool;             // Custody transfer detection
}

ValidationReceipt Entry

pub struct ValidationReceipt {
    pub validator: AgentPubKey,           // Agent providing validation
                                          // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP.
                                          // For collective/bot validators, the signing authority is the designated
                                          // operator key. The governance evaluation must resolve AgentContext →
                                          // effective AgentPubKey before capability token validation.
    pub validated_item: ActionHash,       // Item being validated (Resource, Event, etc.)
    pub validation_type: String,          // Type: "resource_approval", "agent_promotion", "role_validation"
    pub approved: bool,                   // Validation result
    pub notes: Option<String>,            // Optional validation notes
    pub validated_at: Timestamp,          // Validation timestamp
}

Governance: Core validation infrastructure for all governance workflows Audit Trail: Complete tracking of all community validations Flexibility: Supports multiple validation types with contextual notes

EconomicEvent Entry

pub struct EconomicEvent {
    pub action: VfAction,                 // Economic action performed
    pub provider: AgentPubKey,            // Agent providing the resource/service
                                          // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP.
    pub receiver: AgentPubKey,            // Agent receiving the resource/service
                                          // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP.
    pub resource_inventoried_as: ActionHash, // Link to the EconomicResource
    pub affects: ActionHash,              // Link to the affected EconomicResource
    pub resource_quantity: f64,           // Quantity involved in the event
    pub event_time: Timestamp,            // When the event occurred
    pub note: Option<String>,             // Optional event description
}

ValueFlows Compliance: Complete economic event specification Resource Tracking: Links to affected resources for audit trails Action Integration: Uses type-safe VfAction enum

Commitment Entry

pub struct Commitment {
    pub action: VfAction,                 // Economic action committed to
    pub provider: AgentPubKey,            // Provider of the commitment
                                          // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP.
    pub receiver: AgentPubKey,            // Receiver of the commitment
                                          // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP.
    pub resource_inventoried_as: Option<ActionHash>, // Specific resource if applicable
    pub resource_conforms_to: Option<ActionHash>,    // Resource specification if general
    pub input_of: Option<ActionHash>,     // Optional link to a Process
    pub due_date: Timestamp,              // Commitment due date
    pub note: Option<String>,             // Optional commitment description
    pub committed_at: Timestamp,          // When commitment was made
}

Planning: Economic planning and commitment tracking Flexibility: Supports both specific and general resource commitments Due Date Management: Time-bound commitments with expiry

Claim Entry

pub struct Claim {
    pub fulfills: ActionHash,             // References the Commitment
    pub fulfilled_by: ActionHash,         // References the resulting EconomicEvent
    pub claimed_at: Timestamp,            // When claim was made
    pub note: Option<String>,             // Optional claim description
}

Fulfillment Tracking: Links commitments to their actual execution Accountability: Creates audit trail of promise vs. delivery Performance Data: Basis for reputation calculation

ResourceValidation Entry

pub struct ResourceValidation {
    pub resource: ActionHash,             // Link to the EconomicResource being validated
    pub validation_scheme: String,        // e.g., "2-of-3", "simple_majority"
    pub required_validators: u32,         // Number of validators required
    pub current_validators: u32,          // Number of validators who have validated
    pub status: String,                   // "pending", "approved", "rejected"
    pub created_at: Timestamp,            // Validation creation time
    pub updated_at: Timestamp,            // Last update time
}

Multi-Reviewer Validation: Support for complex validation schemes Progress Tracking: Monitor validation progress in real-time Configurable Schemes: Flexible validation requirements

Private Participation Receipt (PPR) System

ParticipationClaimType Enum

pub enum ParticipationClaimType {
    // Genesis Role - Network Entry
    ResourceCreation,         // Creator receives this for successful resource contribution
    ResourceValidation,       // Validator receives this for network validation performed

    // Core Usage Role - Custodianship
    CustodyTransfer,         // Outgoing custodian receives this for responsible custody transfer
    CustodyAcceptance,       // Incoming custodian receives this for custody acceptance

    // Intermediate Roles - Specialized Services
    MaintenanceCommitmentAccepted, // Maintenance agent receives this for accepted commitment
    MaintenanceFulfillmentCompleted, // Maintenance agent receives this for completed fulfillment
    StorageCommitmentAccepted,     // Storage agent receives this for accepted commitment
    StorageFulfillmentCompleted,   // Storage agent receives this for completed fulfillment
    TransportCommitmentAccepted,   // Transport agent receives this for accepted commitment
    TransportFulfillmentCompleted, // Transport agent receives this for completed fulfillment
    GoodFaithTransfer,            // Custodian receives this for good faith transfer to service provider

    // Network Governance
    DisputeResolutionParticipation, // For constructive participation in conflict resolution
    ValidationActivity,            // For performing validation duties beyond specific transactions
    RuleCompliance,               // For consistent adherence to governance protocols

    // Resource End-of-Life Management
    EndOfLifeDeclaration,         // Declaring agent receives this for end-of-life declaration
    EndOfLifeValidation,          // Expert validator receives this for end-of-life validation

    // TODO (G6, REQ-GOV-15 — post-MVP): add new claim types for governance ceremonies:
    //   AffiliationRecordSigned,   // Issued when agent signs AffiliationRecord (ToP ceremony)
    //   GovernanceRoleGranted,     // Issued when collective agent is granted a governance role
    // These extend PPR tracking to cover formal governance participation beyond economic events.
}

Comprehensive Coverage: 16 claim types covering all economic interactions Role-Based Categories: Claims organized by agent roles and interaction types Reputation Foundation: Each claim type contributes to reputation calculation

PerformanceMetrics Structure

pub struct PerformanceMetrics {
    pub timeliness: f64,              // Punctuality score (0.0 to 1.0)
    pub quality: f64,                 // Task quality score (0.0 to 1.0)
    pub reliability: f64,             // Commitment fulfillment reliability (0.0 to 1.0)
    pub communication: f64,           // Communication effectiveness (0.0 to 1.0)
    pub overall_satisfaction: f64,    // Counterparty satisfaction (0.0 to 1.0)
    pub notes: Option<String>,        // Optional contextual notes
}

Quantitative Assessment: Numerical scores for objective reputation calculation Weighted Average: Customizable weights for different aspects of performance Validation: All scores must be within valid range (0.0 to 1.0)

CryptographicSignature Structure

pub struct CryptographicSignature {
    pub recipient_signature: Signature,     // Signature from PPR owner
    pub counterparty_signature: Signature,   // Signature from counterparty
    pub signed_data_hash: [u8; 32],        // Hash of signed data for verification
    pub signed_at: Timestamp,              // When signatures were created
}

Bilateral Authentication: Both parties sign to acknowledge the interaction Cryptographic Security: Tamper-evident signatures for reputation integrity Verification Support: Complete context for signature verification

PrivateParticipationClaim Entry

pub struct PrivateParticipationClaim {
    // Standard ValueFlows fields
    pub fulfills: ActionHash,           // References the commitment fulfilled
    pub fulfilled_by: ActionHash,       // References the economic event
    pub claimed_at: Timestamp,

    // PPR-specific extensions
    pub claim_type: ParticipationClaimType,
    pub performance_metrics: PerformanceMetrics,
    pub bilateral_signature: CryptographicSignature,

    // Additional context
    pub counterparty: AgentPubKey,      // The other agent involved in the interaction
                                        // TODO (G1, REQ-GOV-16): replace AgentPubKey with AgentContext post-MVP.
                                        // Bot agents generate PPRs with their operator's AgentPubKey as the
                                        // accountable counterparty.
    pub resource_hash: Option<ActionHash>, // Optional link to the resource involved
    pub notes: Option<String>,          // Optional contextual notes
}

Privacy: Stored as private entry, accessible only to the claim owner Complete Context: Links commitment, event, performance, and cryptographic proof Reputation Data: Foundation for trust and reputation calculation

ReputationSummary Structure

pub struct ReputationSummary {
    pub total_claims: u32,              // Total number of participation claims
    pub average_performance: f64,       // Average performance score across all claims
    pub creation_claims: u32,           // Resource creation and validation claims
    pub custody_claims: u32,            // Custody-related claims
    pub service_claims: u32,            // Service provision claims
    pub governance_claims: u32,          // Governance participation claims
    pub end_of_life_claims: u32,        // End-of-life management claims
    pub period_start: Timestamp,        // Time period this summary covers
    pub period_end: Timestamp,          // End of time period
    pub agent: AgentPubKey,             // Agent this summary belongs to
    pub generated_at: Timestamp,        // When summary was generated
}

Privacy-Preserving: Share reputation without revealing individual claims Category Breakdown: Reputation scores by interaction type Time-Period Based: Configurable time windows for reputation calculation

API Functions

Economic Event Management

log_economic_event(input: LogEconomicEventInput) -> ExternResult<LogEconomicEventOutput>

Logs an economic event to the distributed ledger.

Input:

pub struct LogEconomicEventInput {
    pub action: VfAction,
    pub provider: AgentPubKey,
    pub receiver: AgentPubKey,
    pub resource_inventoried_as: ActionHash,
    pub affects: ActionHash,
    pub resource_quantity: f64,
    pub note: Option<String>,
}

Business Logic:

  • Validates action compatibility with resource state
  • Creates economic event with timestamp
  • Links to affected resource for audit trail
  • Triggers PPR generation if applicable

Integration: Automatically generates appropriate PPR claims Validation: Cross-zome validation with resource and person zomes

log_initial_transfer(input: LogInitialTransferInput) -> ExternResult<LogEconomicEventOutput>

Special function for Simple Agent's first resource transfer.

Business Logic: Handles special case for agent progression Validation: Validates this is the agent's first transfer Integration: May trigger Simple Agent promotion workflow

get_all_economic_events() -> ExternResult<Vec<EconomicEvent>>

Retrieves all economic events (with appropriate access control).

Privacy: Filters events based on participant access rights Performance: Efficient query via economic event anchors

get_events_for_resource(resource_hash: ActionHash) -> ExternResult<Vec<EconomicEvent>>

Gets all economic events affecting a specific resource.

Pattern: Follows resource-to-events link chain Use Case: Complete resource lifecycle and history

get_events_for_agent(agent: AgentPubKey) -> ExternResult<Vec<EconomicEvent>>

Gets all economic events involving a specific agent.

Pattern: Queries agent participation in economic activities Use Case: Agent's economic activity history

Commitment Management

propose_commitment(input: ProposeCommitmentInput) -> ExternResult<ProposeCommitmentOutput>

Creates a new economic commitment.

Input:

pub struct ProposeCommitmentInput {
    pub action: VfAction,
    pub provider: AgentPubKey,
    pub receiver: AgentPubKey,
    pub resource_conforms_to: Option<ActionHash>,
    pub input_of: Option<ActionHash>,
    pub due_date: Timestamp,
    pub note: Option<String>,
}

Business Logic:

  • Validates commitment feasibility
  • Creates commitment with automatic expiration
  • Links to resource specification if applicable
  • Sets up claim fulfillment tracking

Integration: Creates framework for PPR generation upon fulfillment

get_all_commitments() -> ExternResult<Vec<Commitment>>

Retrieves all commitments (with appropriate access control).

Privacy: Filters commitments based on participant access rights

get_commitments_for_agent(agent: AgentPubKey) -> ExternResult<Vec<Commitment>>

Gets all commitments involving a specific agent.

Pattern: Queries agent as provider or receiver Use Case: Agent's commitment portfolio and obligations

claim_commitment(input: ClaimCommitmentInput) -> ExternResult<ClaimCommitmentOutput>

Claims fulfillment of a commitment, creating the link to an economic event.

Business Logic:

  • Validates economic event fulfills commitment requirements
  • Creates claim linking commitment to event
  • Triggers PPR generation for both parties
  • Updates reputation metrics

Integration: Core mechanism for PPR generation

get_all_claims() -> ExternResult<Vec<Claim>>

Retrieves all claims (with appropriate access control).

get_claims_for_commitment(commitment_hash: ActionHash) -> ExternResult<Vec<Claim>>

Gets all claims for a specific commitment.

Pattern: Track commitment fulfillment history Use Case: Commitment performance analysis

Validation System

create_validation_receipt(input: CreateValidationReceiptInput) -> ExternResult<Record>

Creates a validation receipt for any validated item.

Input:

pub struct CreateValidationReceiptInput {
    pub validated_item: ActionHash,
    pub validation_type: String,
    pub approved: bool,
    pub notes: Option<String>,
}

Business Logic:

  • Records validator's assessment
  • Links to validated item for audit trail
  • Creates validation history
  • May trigger PPR generation for validation activity

get_validation_history(item_hash: ActionHash) -> ExternResult<Vec<ValidationReceipt>>

Gets complete validation history for an item.

Pattern: Follows validated_item_to_receipt links Use Case: Comprehensive validation audit trail

get_all_validation_receipts() -> ExternResult<Vec<ValidationReceipt>>

Retrieves all validation receipts (with appropriate access control).

create_resource_validation(input: CreateResourceValidationInput) -> ExternResult<Record>

Creates a resource validation workflow.

Input:

pub struct CreateResourceValidationInput {
    pub resource: ActionHash,
    pub validation_scheme: String,        // "2-of-3", "simple_majority", etc.
    pub required_validators: u32,
}

Business Logic:

  • Creates validation workflow with specified scheme
  • Tracks validation progress
  • Manages validator assignments
  • Determines final validation outcome

check_validation_status(validation_hash: ActionHash) -> ExternResult<String>

Checks the current status of a validation workflow.

Returns: "pending" | "approved" | "rejected" Use Case: Monitor validation progress

validate_new_resource(input: ValidateNewResourceInput) -> ExternResult<ValidationResult>

Validates a new resource according to community standards.

Cross-Zome Integration: Works with resource zome for validation Validation Logic: Applies governance rules and community standards Outcome: May approve resource or require further validation

Agent Validation and Promotion

validate_agent_identity(input: ValidateAgentIdentityInput) -> ExternResult<ValidationResult>

Validates agent identity and private information for promotion.

Input:

pub struct ValidateAgentIdentityInput {
    pub agent: AgentPubKey,
    pub resource_hash: ActionHash,
    pub private_data_hash: Option<ActionHash>,
}

Business Logic:

  • Cross-zome call to person zome for private data access
  • Validates agent meets promotion requirements
  • Creates validation receipt for audit trail
  • May trigger agent promotion workflow

Privacy: Respects private data access controls

validate_agent_for_promotion(input: ValidateAgentForPromotionInput) -> ExternResult<ValidationResult>

Comprehensive validation for agent promotion to higher capability levels.

Validation Logic:

  • Checks resource creation requirements
  • Validates community participation
  • Evaluates PPR-based reputation
  • Assesses governance understanding

validate_agent_for_custodianship(input: ValidateAgentForCustodianshipInput) -> ExternResult<ValidationResult>

Validates agent suitability for resource custodianship.

Validation Logic:

  • Capability level validation
  • PPR reputation assessment
  • Custody history review
  • Community standing evaluation

validate_specialized_role(input: ValidateSpecializedRoleInput) -> ExternResult<ValidationResult>

Validates agent for specialized roles (Transport, Repair, Storage).

Role-Specific Validation:

  • Technical capability assessment
  • Equipment/facility requirements
  • Safety and compliance validation
  • Performance history review

Private Participation Receipt (PPR) System

issue_participation_receipts(input: IssueParticipationReceiptsInput) -> ExternResult<IssueParticipationReceiptsOutput>

Issues PPRs to both parties involved in an economic interaction.

Input:

pub struct IssueParticipationReceiptsInput {
    pub fulfills: ActionHash,
    pub fulfilled_by: ActionHash,
    pub provider: AgentPubKey,
    pub receiver: AgentPubKey,
    pub claim_types: Vec<ParticipationClaimType>,
    pub provider_metrics: PerformanceMetrics,
    pub receiver_metrics: PerformanceMetrics,
    pub resource_hash: Option<ActionHash>,
    pub notes: Option<String>,
}

Business Logic:

  • Creates private PPR entries for both parties
  • Generates bilateral cryptographic signatures
  • Links to commitment and economic event
  • Stores performance metrics for reputation calculation

Privacy: Private entries accessible only to respective owners Security: Cryptographic signatures prevent tampering

sign_participation_claim(input: SignParticipationClaimInput) -> ExternResult<SignParticipationClaimOutput>

Signs a participation claim with bilateral authentication.

Cryptography: Creates cryptographic signatures for both parties Verification: Supports signature verification for authenticity Integration: Used in PPR creation and validation workflows

validate_participation_claim_signature(input: ValidateParticipationClaimSignatureInput) -> ExternResult<bool>

Validates the cryptographic signatures on a participation claim.

Security: Ensures claim authenticity and integrity Verification: Supports cross-agent claim verification

validate_participation_claim_signature_enhanced(input: ValidateParticipationClaimSignatureInput) -> ExternResult<EnhancedValidationResult>

Enhanced signature validation with detailed verification results.

Additional Features:

  • Signature timestamp validation
  • Agent verification status
  • Claim context validation
  • Detailed security assessment

get_my_participation_claims(filter: Option<PPRFilter>) -> ExternResult<Vec<PrivateParticipationClaim>>

Retrieves the calling agent's participation claims.

Privacy: Only returns claims owned by the calling agent Filtering: Optional filtering by claim type, time period, counterparty Use Case: Agent's reputation portfolio and history

derive_reputation_summary(input: DeriveReputationSummaryInput) -> ExternResult<ReputationSummary>

Derives a privacy-preserving reputation summary from participation claims.

Input:

pub struct DeriveReputationSummaryInput {
    pub period_start: Timestamp,
    pub period_end: Timestamp,
    pub include_categories: Option<Vec<String>>, // Optional category filtering
}

Business Logic:

  • Calculates weighted average performance scores
  • Categorizes claims by type
  • Generates privacy-preserving summary
  • Supports time-period based analysis

Privacy: Can be shared without revealing individual claim details

Private Data Validation

request_agent_validation_data(input: AgentValidationInput) -> ExternResult<ValidationResult>

Requests private data validation for agent validation workflows.

Input:

pub struct AgentValidationInput {
    pub agent_to_validate: AgentPubKey,
    pub validation_type: String,
    pub requesting_validator: AgentPubKey,
    pub validation_context: ActionHash,
}

Business Logic:

  • Cross-zome call to person zome for private data access
  • Validates specific data requirements based on validation type
  • Creates validation receipt for audit trail
  • Respects privacy and consent requirements

create_validation_with_private_data(input: CreateValidationWithPrivateDataInput) -> ExternResult<Record>

Creates validation with explicit private data access.

Privacy: Requires explicit consent for private data access Security: Creates audit trail of private data access Compliance: Ensures privacy requirements are met

Link Architecture

Economic Event Links

  • AllEconomicEvents: economic_events anchor -> event_hash - Global discovery
  • ResourceToEvents: resource_hash -> event_hash - Resource history
  • AgentToEvents: agent_pubkey -> event_hash - Agent participation
  • EventToPrivateParticipationClaims: event_hash -> claim_hash - PPR generation

Commitment Links

  • AllCommitments: commitments anchor -> commitment_hash - Global discovery
  • CommitmentToClaims: commitment_hash -> claim_hash - Fulfillment tracking
  • CommitmentToPrivateParticipationClaims: commitment_hash -> claim_hash - PPR tracking

Validation Links

  • AllValidationReceipts: validation_receipts anchor -> receipt_hash - Global discovery
  • ValidatedItemToReceipt: validated_item -> receipt_hash - Validation history
  • ResourceToValidation: resource_hash -> validation_hash - Resource validation
  • AllResourceValidations: resource_validations anchor -> validation_hash - Validation discovery

PPR System Links

  • AgentToPrivateParticipationClaims: agent_pubkey -> claim_hash - Agent PPR portfolio
  • EventToPrivateParticipationClaims: event_hash -> claim_hash - Event to PPR mapping
  • CommitmentToPrivateParticipationClaims: commitment_hash -> claim_hash - Commitment to PPR mapping
  • ResourceToPrivateParticipationClaims: resource_hash -> claim_hash - Resource to PPR mapping

Signal Architecture

The Governance zome emits signals for real-time UI updates:

pub enum Signal {
    LinkCreated { action },
    LinkDeleted { action },
    EntryCreated { action },
    EntryUpdated { action },
    EntryDeleted { action },
}

Real-time Updates: Enables UI reactivity to governance changes Cross-Zome Coordination: Supports complex workflows with other zomes

Error Handling

GovernanceError Types

GovernanceError is defined in crates/utils/src/errors.rs and imported by zome_gouvernance.

pub enum GovernanceError {
    ValidationReceiptNotFound(String),     // Validation lookup failures
    EconomicEventNotFound(String),       // Event lookup failures
    ResourceValidationNotFound(String),  // Resource validation lookup failures
    CommitmentNotFound(String),          // Commitment lookup failures
    NotAuthorizedValidator,              // Authorization failures
    InsufficientCapability(String),      // Capability level restrictions
    ValidationAlreadyExists(String),     // Duplicate validation prevention
    InvalidValidationScheme(String),     // Validation scheme validation
    SerializationError(String),          // Data serialization issues
    EntryOperationFailed(String),       // DHT operation failures
    LinkOperationFailed(String),        // Link operation failures
    InvalidInput(String),               // Input validation failures
    CrossZomeCallFailed(String),        // Cross-zome communication failures
}

Pattern: Comprehensive error coverage with descriptive messages Integration: Converts to WasmError for Holochain compatibility

Privacy and Security Model

Private Data Protection

  • Private Participation Claims: Stored as private entries, owner-only access
  • Performance Metrics: Only accessible to claim owner
  • Signature Verification: Cryptographic proof without revealing private data
  • Reputation Summaries: Privacy-preserving reputation sharing

Cryptographic Security

  • Bilateral Signatures: Both parties authenticate each interaction
  • Tamper Evidence: Cryptographic hashes prevent undetected modifications
  • Non-Repudiation: Agents cannot deny their participation in interactions
  • Verification Support: Complete context for signature verification

Access Control

  • Role-Based Access: Different functions require different capability levels
  • Cross-Zome Validation: Private data access requires explicit validation
  • Context-Aware Permissions: Access granted based on specific contexts and needs
  • Audit Trails: Complete logging of all validation and access requests

Integration with Other Zomes

Resource Zome Integration

// Create economic event for resource custody transfer
let event_output = call(
    CallTargetCell::Local,
    "zome_gouvernance",
    "log_economic_event".into(),
    None,
    &LogEconomicEventInput {
        action: VfAction::TransferCustody,
        provider: current_custodian,
        receiver: new_custodian,
        resource_inventoried_as: resource_hash,
        affects: resource_hash,
        resource_quantity: 1.0,
        note: Some("Custody transfer completed".to_string()),
    },
)?;

Person Zome Integration

// Validate agent private data for promotion
let validation_result = call(
    CallTargetCell::Local,
    "zome_gouvernance",
    "validate_agent_identity".into(),
    None,
    &ValidateAgentIdentityInput {
        agent: agent_to_validate,
        resource_hash: first_resource_hash,
        private_data_hash: Some(private_data_hash),
    },
)?;

Implementation Status

✅ Completed Features

  • Economic Event Logging: Complete ValueFlows-compliant economic event system
  • Commitment Management: Full commitment lifecycle with claim tracking
  • Validation System: Comprehensive validation workflows with receipt tracking
  • PPR System: Complete Private Participation Receipt system with 16 claim types
  • Reputation Management: Privacy-preserving reputation calculation and sharing
  • Agent Validation: Comprehensive agent promotion and capability validation
  • Cryptographic Security: Bilateral signatures and tamper-evident claims
  • Private Data Protection: Secure private data validation workflows
  • Cross-Zome Integration: Full integration with person and resource zomes

🔧 Current Limitations

  • Basic Validation Schemes: Limited to simple approval, no complex multi-reviewer schemes
  • No Economic Processes: Structured process workflows not implemented
  • Limited Governance Rules: Basic rule enforcement without complex logic
  • No Dispute Resolution: Structured dispute resolution workflows not implemented

📋 Future Enhancement Opportunities

  • Advanced Validation Schemes: Implementation of 2-of-3, N-of-M, weighted voting
  • Economic Process Integration: Structured workflows for Use, Transport, Storage, Repair
  • Dispute Resolution System: Formal dispute resolution with mediator selection
  • Smart Contract Integration: Automated rule enforcement and trigger conditions
  • Reputation Analytics: Advanced reputation analysis and prediction
  • Multi-Network Reputation: Cross-network reputation portability and validation

TODO (post-MVP — configurable GovernanceProcess, governance.md §6.2): Economic Process types (Use, Transport, Storage, Repair) are currently hardcoded strings. Post-MVP, introduce a GovernanceProcess entry type so communities can define custom process types with their own role requirements, validation schemes, and operational state transitions. The current four process types become default instances, not compile-time constants.

TODO (post-MVP — temporal governance, governance.md §4.8): Extend GovernanceRule with an optional expires_at: Timestamp field. The governance evaluation engine must skip expired rules during evaluate_transition. Enables sunset clauses, seasonal access, and time-limited governance experiments.

TODO (post-MVP — governance weight dampening, governance.md §6.4): When governance_weight(agent) incorporates unyt_credit_capacity, apply logarithmic dampening (e.g., log(1 + credit_capacity)) to prevent a feedback loop where high reputation → high credit → higher governance weight → even higher reputation.

The Governance zome provides the foundational economic coordination infrastructure for the nondominium ecosystem, enabling ValueFlows-compliant resource sharing with comprehensive validation, cryptographically-secured reputation tracking, and sophisticated governance workflows.

Post-MVP Governance Architecture Gaps

The following TODOs summarise all governance-related post-MVP structural changes identified across governance.md, agent.md, and the requirements suite. Use these as the canonical cross-reference index when implementing each phase.

Gap ID Description Affected Field(s) Requirement(s) governance.md ref
G1 Collective/Bot agent governance ValidationReceipt.validator, EconomicEvent.provider/receiver, Commitment.provider/receiver, PrivateParticipationClaim.counterparty, GovernanceTransitionRequest.requesting_agent, ResourceStateChange.initiated_by REQ-GOV-16 §3.6.1, §6.6
G2 AffiliationState governance gate GovernanceRule.rule_data["min_affiliation"]; governance evaluate_transition REQ-GOV-14 §3.6.2, §6.4
G6 AffiliationRecord ceremony New create_affiliation_record() + AffiliationRecordSigned PPR claim type REQ-GOV-15 §3.6.3, §4.4
G9 Sybil resistance for governance Role promotion: N-of-M vouching or proof-of-personhood REQ-GOV-17 §5.3
G10 Pseudonymous governance participation Pseudonymous path to ActiveAffiliate; block from legal-accountability roles REQ-GOV-18 §5.3
G11 Bot governance scope Bot participation limited to declared capabilities; operator is accountable — §6.6

All fields marked with TODO (G1, REQ-GOV-16) inline above must be migrated to AgentContext in Phase 3 of the implementation plan. See implementation_plan.md §Phase 3 — Governance Agent Ontology Integration for detailed checklists.