Nondominium Architecture Overview

This document provides a comprehensive overview of the Nondominium Holochain application architecture, focusing on the cross-zome integration patterns, shared infrastructure, and development status. It reflects the implementation of resource management, Private Participation Receipt (PPR) reputation system, capability-based private data sharing, and governance workflows.

System Architecture

Nondominium is a 3-zome Holochain hApp implementing ValueFlows-compliant resource sharing with embedded governance rules, cryptographically-secured reputation tracking through Private Participation Receipts (PPRs), and agent capability progression:

  • zome_person: Agent identity, profiles, roles, capability-based private data sharing, PPR integration, access control
  • zome_resource: Resource specifications, Economic Resources, governance rules, lifecycle management, custody transfers
  • zome_gouvernance: Economic events, commitments, claims, validation workflows, PPR issuance, agent validation. NDO federation extensions (PR #103) added three entry types: NdoHardLink (immutable OVN-licensed cross-NDO link backed by an EconomicEvent), Contribution (peer-validated work record; VF: vf:EconomicEvent/Work), and Agreement (versioned benefit redistribution agreement; VF: vf:Agreement). See documentation/zomes/governance_zome.md §NDO Federation Extensions for API details.
  • zome_lobby (Lobby DNA, separate network seed nondominium-lobby-v1): Global NDO discovery, agent presence, group membership stubs. Entry types: LobbyAgentProfile, NdoAnnouncement.

Technology Foundation

  • Backend: Rust (Holochain HDK ^0.6.0 / HDI ^0.7.0), WASM compilation
  • Data Model: Agent-centric with public/private separation, progressive trust model (Simple → Accountable → Primary Accountable Agent)
  • Security: Progressive capability-based access using Holochain capability tokens (general → restricted → full) with automatic advancement based on PPR milestones
  • Compliance: ValueFlows standard for economic resource management with nondominium extensions (VfAction enum, Economic Processes)
  • Governance: Embedded rules, multi-reviewer validation (2-of-3, N-of-M, simple_majority), cryptographically-signed reputation tracking through PPRs
  • Economic Processes: Four structured workflows (Use, Transport, Storage, Repair) with role-based access control and specialized validation requirements
  • Private Data Sharing: Request/grant workflows with time-limited grants (30-day maximum per capability metadata; shorter UI defaults possible), field-specific control, and Economic Process coordination integration
  • Reputation System: 16 PPR categories, bi-directional receipt issuance, cryptographic signatures, privacy-preserving reputation derivation

Cross-Zome Integration Patterns

Enhanced Agent Capability Progression System

#![allow(unused)]
fn main() {
// Progressive trust model integration across all zomes with PPR milestone tracking
let agent_capability = get_person_capability_level(agent_pubkey)?;
let agent_reputation = derive_reputation_summary(agent_pubkey)?;

match agent_capability.as_str() {
    "member" => {
        // Simple Agent: general capability token
        // Can create resources, make first transaction (InitialTransfer)
        // PPR eligibility: ResourceContribution upon resource validation
        // Promotion path: First transaction validation → Accountable Agent
    },
    "stewardship" => {
        // Accountable Agent: restricted capability token
        // Can access resources, validate others, initiate Use processes
        // PPR eligibility: Service processes, validation activities
        // Promotion path: PPR milestones + specialized role validation → Primary Accountable Agent
    },
    "coordination" | "governance" => {
        // Primary Accountable Agent: full capability token
        // Can hold custody, validate specialized roles, initiate all processes (Transport, Storage, Repair)
        // PPR eligibility: All 16 categories, including custodianship and governance participation
        // Advanced capabilities: Dispute resolution, end-of-life validation
    }
}

// Automatic capability token advancement based on PPR milestones
if agent_reputation.total_interactions >= 5 && agent_reputation.completion_rate >= 0.8 {
    // Trigger capability token upgrade
    upgrade_capability_token(agent_pubkey, "restricted_access")?;
}
}

Enhanced Economic Process Role Enforcement

#![allow(unused)]
fn main() {
// Cross-zome role validation for specialized processes with validation history
let process_type = "Transport"; // Use, Transport, Storage, Repair
let required_role = match process_type {
    "Use" => None, // Accessible to all Accountable Agents
    "Transport" => Some("Transport"),
    "Storage" => Some("Storage"),
    "Repair" => Some("Repair"),
    _ => return Err(ProcessError::InvalidProcessType),
};

if let Some(role) = required_role {
    // Check specialized role capability
    let has_role = has_person_role_capability((agent_pubkey, role.to_string()))?;
    if !has_role {
        return Err(ProcessError::InsufficientRole(role.to_string()));
    }

    // Validate role was properly validated by governance
    let role_validation = call(
        CallTargetCell::Local,
        "zome_gouvernance",
        "get_specialized_role_validation".into(),
        None,
        &GetRoleValidationInput {
            agent: agent_pubkey,
            role: role.to_string(),
        },
    )?;

    if !role_validation.is_valid_and_current() {
        return Err(ProcessError::InvalidRoleValidation(role.to_string()));
    }
}

// Additional Economic Process workflow integration
let process_creation_result = call(
    CallTargetCell::Local,
    "zome_resource",
    "initiate_economic_process".into(),
    None,
    &EconomicProcessInput {
        process_type: process_type.to_string(),
        name: format!("{} process for resource", process_type),
        resource_hashes: vec![resource_hash],
        location: Some(resource_location),
    },
)?;
}

Enhanced Private Data Sharing Integration

#![allow(unused)]
fn main() {
// Automatic private data coordination for Economic Processes
pub fn coordinate_process_private_data(
    process_hash: ActionHash,
    participants: Vec<AgentPubKey>,
    process_type: &str,
) -> ExternResult<Vec<ActionHash>> {
    let mut coordination_requests = Vec::new();

    for participant in participants {
        // Determine required coordination fields based on process type
        let required_fields = match process_type {
            "Transport" => vec!["email", "phone", "location"],
            "Storage" => vec!["email", "phone", "emergency_contact"],
            "Repair" => vec!["email", "phone", "time_zone"],
            "Use" => vec!["email"], // Minimal coordination for use processes
            _ => vec![],
        };

        if !required_fields.is_empty() {
            let request = call(
                CallTargetCell::Local,
                "zome_person",
                "request_private_data_access".into(),
                None,
                &DataAccessRequestInput {
                    requested_from: participant,
                    fields_requested: required_fields.iter().map(|s| s.to_string()).collect(),
                    context: format!("{}_process_coordination", process_type),
                    resource_hash: Some(resource_hash),
                    justification: format!("Coordination required for {} process", process_type),
                },
            )?;
            coordination_requests.push(request.request_hash);
        }
    }

    Ok(coordination_requests)
}

// Automatic grant approval for trusted Economic Process participants
pub fn auto_approve_process_coordination(
    request_hash: ActionHash,
    requester: AgentPubKey,
) -> ExternResult<Option<ActionHash>> {
    // Check requester reputation and role validation
    let reputation = call(
        CallTargetCell::Local,
        "zome_gouvernance",
        "derive_reputation_summary".into(),
        None,
        &DeriveReputationSummaryInput {
            time_range: None,
            role_filter: None,
            include_recent_activity: false,
        },
    )?;

    // Auto-approve for high-reputation, validated agents
    if reputation.completion_rate >= 0.9 && reputation.total_interactions >= 10 {
        let grant = call(
            CallTargetCell::Local,
            "zome_person",
            "respond_to_data_request".into(),
            None,
            &RespondToDataRequestInput {
                request_hash,
                approve: true,
                duration_days: Some(7), // Standard Economic Process coordination period
            },
        )?;
        return Ok(grant);
    }

    Ok(None) // Requires manual approval
}
}

Enhanced PPR Integration Pattern

#![allow(unused)]
fn main() {
// Comprehensive PPR generation with 16 categories and bilateral signatures
let ppr_result = call(
    CallTargetCell::Local,
    "zome_gouvernance",
    "issue_participation_receipts".into(),
    None,
    &IssueParticipationReceiptsInput {
        commitment_hash: commitment.hash(),
        event_hash: economic_event.hash(),
        counterparty: commitment.receiver,
        performance_metrics: calculate_performance_metrics(&commitment, &event)?,
        interaction_context: determine_interaction_context(&commitment.action, &process_context)?,
        role_context: get_role_context(&process_context)?,
    },
)?;

// Bi-directional PPR issuance with cryptographic signatures
let provider_ppr = PrivateParticipationClaim {
    fulfills: commitment_hash,
    fulfilled_by: event_hash,
    claimed_at: sys_time()?,
    claim_type: determine_provider_claim_type(&commitment.action, &process_context)?,
    counterparty: commitment.receiver,
    performance_metrics: ppr_result.provider_metrics,
    bilateral_signature: ppr_result.provider_signature,
    interaction_context: ppr_result.interaction_context,
    role_context: ppr_result.role_context,
    resource_reference: Some(commitment.resource_inventoried_as),
};

let receiver_ppr = PrivateParticipationClaim {
    fulfills: commitment_hash,
    fulfilled_by: event_hash,
    claimed_at: sys_time()?,
    claim_type: determine_receiver_claim_type(&commitment.action, &process_context)?,
    counterparty: commitment.provider,
    performance_metrics: ppr_result.receiver_metrics,
    bilateral_signature: ppr_result.receiver_signature,
    interaction_context: ppr_result.interaction_context,
    role_context: ppr_result.role_context,
    resource_reference: Some(commitment.resource_inventoried_as),
};

// PPRs stored as private entries, accessible only to owning agents
// No DHT links created for privacy preservation
}

PPR Category Determination Logic

#![allow(unused)]
fn main() {
// Comprehensive PPR category assignment based on Economic Process context
pub fn determine_ppr_categories(
    action: &VfAction,
    process_type: &str,
    agent_role: &str,
    interaction_context: &str,
) -> (ParticipationClaimType, ParticipationClaimType) {
    match (action, process_type, agent_role, interaction_context) {
        // Genesis Role - Network Entry
        (VfAction::InitialTransfer, _, "Simple Agent", "resource_creation") => (
            ParticipationClaimType::ResourceContribution,
            ParticipationClaimType::NetworkValidation,
        ),

        // Core Usage Role - Custodianship
        (VfAction::TransferCustody, _, _, "custody_transfer") => (
            ParticipationClaimType::ResponsibleTransfer,
            ParticipationClaimType::CustodyAcceptance,
        ),

        // Specialized Economic Processes
        (VfAction::Use, "Use", _, _) => (
            ParticipationClaimType::ServiceCommitmentAccepted,
            ParticipationClaimType::ServiceFulfillmentCompleted,
        ),
        (VfAction::Work, "Transport", "Transport", _) => (
            ParticipationClaimType::TransportFulfillment,
            ParticipationClaimType::ServiceCommitmentAccepted,
        ),
        (VfAction::Work, "Storage", "Storage", _) => (
            ParticipationClaimType::StorageFulfillment,
            ParticipationClaimType::ServiceCommitmentAccepted,
        ),
        (VfAction::Modify, "Repair", "Repair", _) => (
            ParticipationClaimType::MaintenanceFulfillment,
            ParticipationClaimType::ServiceFulfillmentCompleted,
        ),

        // Network Governance
        (_, _, _, "validation_activity") => (
            ParticipationClaimType::NetworkValidation,
            ParticipationClaimType::GovernanceCompliance,
        ),
        (_, _, _, "end_of_life") => (
            ParticipationClaimType::EndOfLifeDeclaration,
            ParticipationClaimType::EndOfLifeValidation,
        ),
        (_, _, _, "dispute_resolution") => (
            ParticipationClaimType::DisputeResolutionParticipation,
            ParticipationClaimType::GovernanceCompliance,
        ),

        // Default case
        _ => (
            ParticipationClaimType::ServiceCommitmentAccepted,
            ParticipationClaimType::ServiceFulfillmentCompleted,
        ),
    }
}
}

Resource-Governance Integration

#![allow(unused)]
fn main() {
// Resource validation triggering governance workflows
let resource_validation = ResourceValidation {
    resource: resource_hash,
    validation_scheme: "2-of-3".to_string(),
    required_validators: 2,
    current_validators: 0,
    status: "pending".to_string(),
};

// Cross-zome validation coordination
let governance_result = call(
    CallTargetCell::Local,
    "zome_gouvernance",
    "initiate_resource_validation".into(),
    None,
    &resource_validation,
)?;

// Automatic PPR issuance for validation participation
let validation_pprs = call(
    CallTargetCell::Local,
    "zome_gouvernance",
    "issue_validation_participation_receipts".into(),
    None,
    &ValidationPPRInput {
        resource_hash,
        validator: agent_pubkey,
        validation_type: "resource_approval".to_string(),
    },
)?;
}

Shared Infrastructure

Signal Architecture

Enhanced Multi-Zome Signals

#![allow(unused)]
fn main() {
pub enum Signal {
    // Resource lifecycle signals
    EntryCreated { action, app_entry },
    EntryUpdated { action, app_entry, original_app_entry },
    EntryDeleted { action, original_app_entry },
    LinkCreated { action, link_type },
    LinkDeleted { action, link_type },

    // Economic Process signals
    ProcessInitiated { process_hash, process_type, agent },
    ProcessCompleted { process_hash, completion_event, performance_metrics },
    ProcessValidated { process_hash, validator, approved },

    // PPR system signals
    PPRIssued { recipient, claim_type, counterparty },
    ReputationUpdated { agent, new_summary },

    // Governance workflow signals
    ValidationRequired { item_hash, validation_type, scheme },
    ValidationCompleted { item_hash, result, validators },
    AgentPromoted { agent, from_level, to_level },
}
}

Real-time Updates: Enables UI reactivity to all system changes Cross-Zome Coordination: Supports complex workflows spanning multiple zomes PPR Integration: Real-time reputation updates and participation tracking Process Management: Live updates on Economic Process status and completion

Discovery Performance

Anchor Path Strategy

  • Categorized Discovery: O(1) lookup by category/tag
  • Agent-Centric Queries: Direct agent -> owned resources links
  • Versioning: Efficient latest version resolution
  • Bulk Operations: Optimized for large result sets
#![allow(unused)]
fn main() {
// Category-based discovery with tag metadata
create_link(
    category_path.path_entry_hash()?,
    spec_hash.clone(),
    LinkTypes::SpecsByCategory,
    LinkTag::new(category_name.as_str()),
)?;
}

Performance: Link tags enable efficient filtering without record retrieval

Common Patterns

Entry Creation Pattern

All zomes follow this standardized pattern for creating entries:

#![allow(unused)]
fn main() {
// Standard entry creation with discovery links
let entry = EntryType {
    field: value,
    agent_pub_key: agent_info.agent_initial_pubkey,
    created_at: sys_time()?,
};
let hash = create_entry(&EntryTypes::EntryType(entry.clone()))?;

// Create discovery anchor links
let path = Path::from("anchor_name");
create_link(path.path_entry_hash()?, hash.clone(), LinkTypes::AnchorType, LinkTag::new("tag"))?;
}

Versioning Pattern

#![allow(unused)]
fn main() {
// Update pattern with version history tracking
let updated_entry = update_entry(input.previous_action_hash, &updated_data)?;
create_link(
    input.original_action_hash,
    updated_entry.clone(),
    LinkTypes::EntryUpdates,
    (),
)?;
}

Discovery Pattern

#![allow(unused)]
fn main() {
// Efficient anchor-based discovery
let path = Path::from("discovery_anchor");
let links = get_links(
    GetLinksInputBuilder::try_new(path.path_entry_hash()?, LinkTypes::DiscoveryType)?.build(),
)?;
}

Privacy Architecture

Four-Layer Privacy Model

1. Public Data Layer

  • Person entries: Name, avatar, bio (discoverable by all agents)
  • Role assignments: Role name, assignment metadata (auditable governance)
  • Resource specifications: Name, description, category (community discovery)
  • Economic events: Public record of economic activities (audit trail)
  • Validation receipts: Public governance validation records

2. Private Data Layer

  • PrivatePersonData entries: PII, contact info (owner-only access)
  • PrivateParticipationClaims: Cryptographically-signed reputation receipts (private entries)
  • Holochain Security: Private entry visibility enforced by conductor

3. Access-Controlled Layer

  • Role-based permissions: Capability-driven resource access
  • Governance rules: Community-managed access controls
  • Custodian permissions: Resource-specific access rights
  • Process validation: Specialized role validation for Economic Processes

4. Derived Data Layer

  • Reputation summaries: Calculated from private PPRs, selectively shared
  • Performance metrics: Aggregated from participation claims
  • Trust scores: Derived reputation indicators for decision-making

Access Control Implementation

#![allow(unused)]
fn main() {
// Four-tier access pattern with PPR integration
match access_level {
    Public => {
        // Anyone can read public entries
        get_public_data(entry_hash)
    },
    Private => {
        // Only owner can access private entries (PPRs, PII)
        if caller == owner {
            get_private_data(entry_hash)
        } else {
            Err(NotAuthorized)
        }
    },
    RoleBased => {
        // Check role-based permissions for processes
        let has_permission = check_role_capability(caller, required_role)?;
        if has_permission {
            get_controlled_data(entry_hash)
        } else {
            Err(InsufficientCapability)
        }
    },
    ReputationBased => {
        // Access based on derived reputation metrics
        let reputation = get_agent_reputation_summary(caller)?;
        if reputation.meets_threshold(required_threshold) {
            get_reputation_gated_data(entry_hash)
        } else {
            Err(InsufficientReputation)
        }
    }
}
}

Private Participation Receipt (PPR) System

PPR Infrastructure Architecture

#![allow(unused)]
fn main() {
// PPR lifecycle: automatic generation for every economic interaction
pub struct PPRGenerationWorkflow {
    // 1. Commitment created
    commitment: Commitment,

    // 2. Economic event occurs
    event: EconomicEvent,

    // 3. Claim links commitment to event (public governance record)
    claim: Claim,

    // 4. Bi-directional PPRs automatically generated (private entries)
    provider_ppr: PrivateParticipationClaim,
    receiver_ppr: PrivateParticipationClaim,
}

// Cross-zome PPR coordination
impl PPRGenerationWorkflow {
    pub fn execute(&self) -> ExternResult<(ActionHash, ActionHash)> {
        // 1. Generate performance metrics
        let metrics = self.calculate_performance_metrics()?;

        // 2. Create cryptographic signatures
        let signatures = self.create_bilateral_signatures()?;

        // 3. Store PPRs as private entries in zome_person
        let provider_ppr_hash = self.store_provider_ppr(metrics.clone(), signatures.provider)?;
        let receiver_ppr_hash = self.store_receiver_ppr(metrics, signatures.receiver)?;

        // 4. Update agent reputation caches
        self.update_reputation_summaries()?;

        // 5. Emit signals for real-time UI updates
        self.emit_ppr_signals()?;

        Ok((provider_ppr_hash, receiver_ppr_hash))
    }
}
}

PPR Categories and Issuance Patterns

#![allow(unused)]
fn main() {
// PPR issuance based on economic interaction context
pub fn determine_ppr_category(
    action: &VfAction,
    process_type: &str,
    agent_role: &str,
) -> Vec<ParticipationClaimType> {
    match (action, process_type, agent_role) {
        // Simple Agent first transaction
        (VfAction::InitialTransfer, _, "Simple Agent") => vec![
            ParticipationClaimType::ResourceContribution,
            ParticipationClaimType::NetworkValidation,
        ],

        // Core Use process
        (VfAction::Use, "Use", _) => vec![
            ParticipationClaimType::ServiceCommitmentAccepted,
            ParticipationClaimType::ServiceFulfillmentCompleted,
        ],

        // Specialized Transport process
        (VfAction::Work, "Transport", "Transport") => vec![
            ParticipationClaimType::TransportFulfillment,
            ParticipationClaimType::CustodyAcceptance,
        ],

        // Specialized Repair process
        (VfAction::Modify, "Repair", "Repair") => vec![
            ParticipationClaimType::MaintenanceFulfillment,
            ParticipationClaimType::ServiceFulfillmentCompleted,
        ],

        // Custody transfer
        (VfAction::TransferCustody, _, _) => vec![
            ParticipationClaimType::ResponsibleTransfer,
            ParticipationClaimType::CustodyAcceptance,
        ],

        // Validation activities
        (_, _, "Validator") => vec![
            ParticipationClaimType::NetworkValidation,
            ParticipationClaimType::GovernanceCompliance,
        ],

        _ => vec![], // No PPR generation for this combination
    }
}
}

Reputation Derivation and Selective Sharing

#![allow(unused)]
fn main() {
// Privacy-preserving reputation calculation
pub fn calculate_reputation_summary(agent: AgentPubKey) -> ExternResult<ReputationSummary> {
    // Access agent's private PPR collection
    let pprs = get_my_participation_claims()?;

    let mut summary = ReputationSummary {
        agent,
        total_interactions: pprs.len() as u32,
        average_timeliness: 0.0,
        average_quality: 0.0,
        average_reliability: 0.0,
        average_communication: 0.0,
        completion_rate: 0.0,
        role_performance: HashMap::new(),
        recent_activity: Vec::new(),
        calculated_at: sys_time()?,
    };

    // Aggregate metrics from private claims
    for ppr in pprs {
        summary.aggregate_metrics(&ppr.performance_metrics)?;
        summary.update_role_performance(&ppr)?;
        summary.track_recent_activity(&ppr)?;
    }

    summary.finalize_calculations();
    Ok(summary)
}

// Selective reputation sharing
pub fn share_reputation_summary(
    target_agent: AgentPubKey,
    sharing_scope: ReputationSharingScope,
) -> ExternResult<SelectiveReputationShare> {
    let full_summary = calculate_reputation_summary(agent_info()?.agent_initial_pubkey)?;

    match sharing_scope {
        ReputationSharingScope::Basic => {
            // Share only overall scores and completion rate
            SelectiveReputationShare::basic(full_summary)
        },
        ReputationSharingScope::RoleSpecific(role) => {
            // Share detailed metrics for specific role
            SelectiveReputationShare::role_specific(full_summary, role)
        },
        ReputationSharingScope::Comprehensive => {
            // Share detailed breakdown (requires higher trust level)
            SelectiveReputationShare::comprehensive(full_summary)
        },
    }
}
}

ValueFlows Compliance

Enhanced Agent-Centric Model

  • Agents as Economic Actors: Every participant is an autonomous economic agent with progressive capability levels
  • Identity and Reputation: Comprehensive agent profiles with role-based capabilities and cryptographically-signed reputation tracking
  • Decentralized Coordination: No central authority, community-governed resource sharing with embedded governance rules
  • Process-Aware Interactions: All economic activities occur within structured Economic Processes

Comprehensive Economic Resource Management

  • Resource Specifications: Templates defining resource types, embedded governance rules, and process requirements
  • Economic Resources: Actual resource instances with clear custodianship and lifecycle tracking
  • Economic Processes: Structured activities (Use, Transport, Storage, Repair) with role-based access control
  • Economic Events: VfAction-based event tracking with automatic PPR generation
  • Governance Rules: Community-defined access and usage policies enforced programmatically

VfAction Enum Implementation

#![allow(unused)]
fn main() {
// Type-safe ValueFlows action representation with nondominium extensions
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize)]
pub enum VfAction {
    // Standard ValueFlows actions
    Transfer, Move, Use, Consume, Produce, Work, Modify,
    Combine, Separate, Raise, Lower, Cite, Accept,

    // nondominium-specific extensions
    InitialTransfer,    // Simple Agent first transaction
    AccessForUse,       // Request access commitment
    TransferCustody,    // Primary Accountable Agent custody transfer
}

impl VfAction {
    // Process-aware action classification
    pub fn requires_specialized_role(&self, process_type: &str) -> Option<String> {
        match (self, process_type) {
            (VfAction::Work, "Transport") => Some("Transport".to_string()),
            (VfAction::Work, "Storage") => Some("Storage".to_string()),
            (VfAction::Modify, "Repair") => Some("Repair".to_string()),
            (VfAction::Use, _) => None, // Accessible to all Accountable Agents
            _ => None,
        }
    }

    // PPR integration
    pub fn triggers_ppr_generation(&self) -> bool {
        matches!(self,
            VfAction::InitialTransfer | VfAction::Use |
            VfAction::Work | VfAction::Modify |
            VfAction::TransferCustody
        )
    }
}
}

Enhanced Compliance Implementation

#![allow(unused)]
fn main() {
// Comprehensive ValueFlows compliance with nondominium extensions
pub struct EconomicResource {
    pub conforms_to: ActionHash,         // ResourceSpecification compliance
    pub quantity: f64,                   // Measurable resource quantity
    pub unit: String,                   // Standard measurement unit
    pub custodian: AgentPubKey,         // Primary Accountable Agent
    pub current_location: Option<String>, // Resource location tracking
    // TODO: split into LifecycleStage (NondominiumIdentity Layer 0) + OperationalState (EconomicResource Layer 2)
    pub state: ResourceState,           // Currently conflated; pending split per ndo_prima_materia.md Section 5
    pub governance_rules: Vec<GovernanceRule>, // Embedded governance
    pub validation_status: String,      // Peer validation status
    pub process_history: Vec<ActionHash>, // Economic Process audit trail
}

pub struct EconomicProcess {
    pub process_type: String,           // Use, Transport, Storage, Repair
    pub required_role: String,          // Role-based access control
    pub inputs: Vec<ActionHash>,        // Input resources
    pub outputs: Vec<ActionHash>,       // Output resources
    pub status: ProcessStatus,          // Process lifecycle state
    pub validation_requirements: ProcessValidationRequirements,
}

pub struct EconomicEvent {
    pub action: VfAction,               // Type-safe ValueFlows action
    pub provider: AgentPubKey,          // Agent providing
    pub receiver: AgentPubKey,          // Agent receiving
    pub resource_inventoried_as: ActionHash, // Affected resource
    pub input_of: Option<ActionHash>,   // Parent Economic Process
    pub ppr_generated: bool,            // Automatic PPR issuance flag
}
}

Multi-Layered Ontology Support

#![allow(unused)]
fn main() {
// ValueFlows three-layer ontology implementation
pub enum OntologyLayer {
    Knowledge {
        // Resource specifications, governance rules, process templates
        resource_specs: Vec<ResourceSpecification>,
        governance_rules: Vec<GovernanceRule>,
        process_templates: Vec<ProcessTemplate>,
    },
    Plan {
        // Commitments, process initiations, validation workflows
        commitments: Vec<Commitment>,
        planned_processes: Vec<EconomicProcess>,
        validation_schemes: Vec<ValidationScheme>,
    },
    Observation {
        // Economic events, completed processes, issued PPRs
        economic_events: Vec<EconomicEvent>,
        completed_processes: Vec<CompletedProcess>,
        validation_receipts: Vec<ValidationReceipt>,
        participation_claims: Vec<PrivateParticipationClaim>,
    },
}
}

Development Status

Phase 1: Foundation Layer ✅ COMPLETED (Existing Working Code)

  • ✅ Agent Identity & Role System: Comprehensive identity with sophisticated three-tier privacy layers and 8-level role hierarchy
  • ✅ Progressive Capability System: Complete Simple → Accountable → Primary Accountable Agent progression
  • ✅ Resource Specifications: ValueFlows-compliant resource templates with embedded governance rules and process requirements
  • ✅ Discovery Patterns: Optimized anchor-based queries with performance optimization and multi-dimensional filtering
  • ✅ Governance Foundation: Multi-reviewer validation schemes (2-of-3, N-of-M, simple_majority) and rule enforcement framework
  • ✅ Cross-Zome Integration: Complete authorization and capability checking across all three zomes
  • ✅ VfAction Enum: Type-safe ValueFlows action implementation with nondominium extensions and helper methods
  • ✅ Economic Resource Lifecycle: Complete resource instance management with state tracking and custody transfers
  • ✅ Basic Governance Infrastructure: ValidationReceipt creation, economic event logging, cross-zome validation functions

Phase 2: Enhanced Governance & Process Integration ✅ COMPLETED

  • ✅ Enhanced Private Data Sharing: Complete DataAccessRequest/Grant workflows with time-limited grants (30-day cap) and field-specific control
  • ✅ Economic Process Infrastructure: Four structured processes (Use, Transport, Storage, Repair) with role-based access control
  • ✅ Private Participation Receipt (PPR) System: Complete 14-category PPR system with bi-directional receipt issuance
  • ✅ Agent Capability Progression: Complete Simple → Accountable → Primary Accountable Agent advancement with PPR integration
  • ✅ Cross-Zome Coordination: Seamless coordination across person, resource, and governance zomes for complete workflows
  • ✅ Validation Workflows: Resource validation, agent promotion, and specialized role validation fully operational
  • ✅ Cryptographic Integrity: All PPRs cryptographically signed with bilateral authentication
  • ✅ Performance Metrics Integration: Quantitative performance tracking embedded in all economic interactions
  • ✅ Role-Based Process Access: Specialized roles (Transport, Repair, Storage) enabling restricted Economic Process participation
  • ✅ Process-Aware Governance: Economic Process validation with quality assurance and completion validation
  • ✅ Reputation Derivation: Privacy-preserving reputation calculation with selective disclosure control
  • ✅ Economic Event Integration: Complete VfAction-based event tracking with automatic PPR generation

Phase 3: Advanced Security & Cross-Zome Coordination 🔄 IN PROGRESS

  • 🔄 Progressive Capability Tokens: Automatic capability token progression based on PPR milestones (implementation underway)
  • 🔄 Economic Process Access Control: Role-validated access to specialized processes with reputation influence
  • 🔄 Transaction Consistency: Atomic operations across all three zomes with comprehensive rollback mechanisms
  • 📋 Advanced Validation Schemes: PPR-weighted validator selection and reputation-based consensus
  • 📋 Dispute Resolution: Edge-based conflict resolution with PPR context and private data coordination

Phase 3 — Agent Ontology Expansion 📋 PLANNED (see documentation/archives/agent.md)

TODO: The following agent-layer gaps were identified against the OVN wiki ontology (15 years of commons-based peer production practice). The current implementation models only individual agents. The items below must be incorporated into Phase 3 planning. See documentation/zomes/person_zome.md Future Enhancements section and documentation/implementation_plan.md Phase 3 for detailed task breakdowns.

Phase 3 Agent Items:

  • 📋 [G1] AgentEntityType field: Distinguish Individual, Collective, Project, Network, Bot, ExternalOrganisation agents (REQ-AGENT-01)
  • 📋 [G15] CapabilitySlot on Person: Stigmergic attachment surface for DID documents, credential wallets, reputation oracles (REQ-AGENT-11)
  • 📋 [G3] Composable AgentProfile view: Assembled from Person + ReputationSummary + Roles + CapabilitySlots + affiliations (REQ-AGENT-07)
  • 📋 [G4] AgentRelationship link type: Bidirectional typed private peer relationships (REQ-AGENT-08)
  • 📋 [G5] Network affiliation links: Cross-NDO membership from Person hash to NDO instance hashes (REQ-AGENT-09)
  • 📋 [G14] Configurable role taxonomy: Replace closed RoleType enum with a community-configurable role registry (REQ-AGENT-06)

Phase 2 Agent Items (earlier priority):

  • 📋 [G13] Fix request_role_promotion stub: Real queryable RolePromotionRequest entry with discovery links (REQ-AGENT-16)
  • 📋 [G6] AffiliationRecord entry: Formal Terms of Participation ceremony (REQ-AGENT-05)
  • 📋 [G2] Derived affiliation state: Computed from PPR activity — UnaffiliatedStranger → CloseAffiliate → ActiveAffiliate → CoreAffiliate → InactiveAffiliate (REQ-AGENT-04)

Phase 4: Network Maturity & Advanced Features 📋 PLANNED

  • 📋 Advanced Process Workflows: Multi-step process chaining with automated agent selection based on PPR reputation
  • 📋 AI-Enhanced Reputation: Machine learning-based trust prediction and context-aware weighting
  • 📋 Cross-Network Integration: PPR portability and federated identity management across multiple nondominium networks
  • 📋 Performance Optimization: Large-scale network operation with predictive scaling and efficiency optimization
  • 📋 Community Governance: Reputation-weighted validation and automated role progression based on performance metrics

Phase 4 Agent Items (see documentation/implementation_plan.md Phase 4):

  • 📋 [G8] PortableCredential: Bilaterally-signed, cross-network verifiable credential export (REQ-AGENT-12)
  • 📋 [G7] ZKP capability proofs: Prove eligibility without raw data disclosure (REQ-AGENT-13)
  • 📋 [G9] Sybil resistance: Social vouching / Proof-of-Personhood configurable membrane proof (REQ-AGENT-15)
  • 📋 [G10] Pseudonymous participation mode: Ephemeral key contribution, unlinkable to Person (REQ-AGENT-14)
  • 📋 [G11] AI/bot delegation: DelegatedAgent relationship for scoped AI/bot acting on behalf of Person (REQ-AGENT-03)
  • 📋 [G12] AgentNeedsWants: Optional profile extension for resource matching (REQ-AGENT-10)

Performance Considerations

Scalability Patterns

  • Anchor-Based Discovery: O(1) category and tag lookups
  • Agent-Centric Links: Direct ownership queries without scanning
  • Lazy Loading: On-demand data retrieval for large datasets
  • Batch Operations: Efficient bulk data processing

Optimization Strategies

  • Link Tag Metadata: Rich link information without record retrieval
  • Caching Strategies: Strategic data caching for frequent queries
  • Pagination Support: Large result set management
  • Selective Loading: Component-based data loading

Security Model

Holochain Security Features

  • Agent Identity: Cryptographic agent verification
  • Entry Validation: Comprehensive validation rules per entry type
  • Private Entries: Conductor-enforced privacy
  • Capability Tokens: Fine-grained access control (planned)

Application Security Layers

  • Role-Based Authorization: Hierarchical capability system
  • Governance Rule Validation: Community-enforced access controls
  • Cross-Zome Verification: Multi-zome authorization checks
  • Audit Trails: Complete action history and attribution

Error Handling Strategy

Comprehensive Error Types

Each zome implements domain-specific error enums with:

  • Descriptive Messages: Clear error descriptions for debugging
  • Error Categories: Logical grouping of related failures
  • Recovery Guidance: Information for error resolution
  • Cross-Zome Compatibility: Consistent error handling patterns

Error Propagation Pattern

#![allow(unused)]
fn main() {
// Standardized error handling across zomes
match operation_result {
    Ok(data) => Ok(data),
    Err(domain_error) => {
        error!("Operation failed: {:?}", domain_error);
        Err(WasmError::from(domain_error))
    }
}
}

Testing Architecture

Comprehensive Four-Layer Testing Strategy

  1. Foundation Tests: Basic zome function calls, connectivity, and individual component validation
  2. Integration Tests: Cross-zome interactions, multi-agent scenarios, and PPR generation workflows
  3. Scenario Tests: Complete user journeys, Economic Process workflows, and governance validation cycles
  4. Performance Tests: Load and stress testing for large-scale deployment (in progress)

Test Coverage Areas

  • ✅ Person Management: Profiles, roles, privacy controls, PPR storage and retrieval
  • ✅ Identity Storage: Public/private data separation, selective sharing mechanisms
  • ✅ Role Assignment: Capability validation, specialized role validation, agent progression
  • ✅ Resource Management: Specifications, Economic Resources, lifecycle management, embedded governance
  • ✅ Governance Processes: Rule enforcement, validation workflows, multi-reviewer schemes
  • ✅ Economic Processes: Use, Transport, Storage, Repair processes with role-based access control
  • ✅ PPR System: Bi-directional receipt generation, cryptographic signatures, reputation derivation
  • ✅ Agent Progression: Simple Agent promotion workflows, validation participation
  • 🔄 End-of-Life Management: Resource decommissioning with enhanced security validation
  • 🔄 Dispute Resolution: Edge-based conflict resolution mechanisms
  • 📋 Performance Optimization: Large-scale network behavior and efficiency testing

This comprehensive architecture provides a production-ready, sophisticated foundation for ValueFlows-compliant resource sharing with advanced governance capabilities, Economic Process management, and privacy-preserving reputation tracking, including:

Core System Capabilities

  • Progressive Trust Model: Three-tier agent capability system (Simple → Accountable → Primary Accountable Agent) with automatic PPR-based advancement
  • Economic Process Management: Four structured workflows (Use, Transport, Storage, Repair) with role-based access control and specialized validation requirements
  • Privacy-Preserving Reputation: 14-category PPR system with cryptographically-signed bilateral receipts enabling trust without compromising privacy
  • Enhanced Private Data Sharing: Request/grant workflows with time-limited grants (30-day cap), field-specific control, and Economic Process coordination integration
  • Embedded Governance: Community-defined rules enforced programmatically across all interactions with multi-reviewer validation schemes
  • Cross-Zome Integration: Seamless coordination between identity, resource, and governance systems with atomic transaction support

Advanced Features

  • Type-Safe Operations: VfAction enum with helper methods ensuring ValueFlows compliance with compile-time validation
  • Cryptographic Integrity: All PPRs cryptographically signed with bilateral authentication for authenticity and non-repudiation
  • Performance Metrics Integration: Quantitative performance tracking embedded in all economic interactions for quality assurance
  • Scalable Infrastructure: Optimized discovery patterns, efficient anchor-based queries, and performance considerations for large-scale deployment
  • Comprehensive Audit Trails: Complete tracking of all economic activities, governance decisions, and agent progression with privacy preservation
  • Process-Aware Governance: Economic Process validation with completion requirements, state change validation, and automatic PPR generation

Production-Ready Implementation

The system demonstrates how decentralized, agent-centric architectures can support sophisticated governance models while maintaining the core principles of nondominium resources: organization-agnostic, capture-resistant, and permissionless access under transparent community governance.

With the completion of Phase 2, the system provides a comprehensive ecosystem for:

  • Decentralized Resource Sharing with embedded governance and Economic Process support
  • Privacy-Preserving Accountability through the PPR reputation system with selective disclosure
  • Progressive Agent Capability advancement based on validated performance and community participation
  • Sophisticated Economic Coordination through structured processes with role-based access control
  • Cross-Zome Transaction Integrity ensuring atomic operations and comprehensive error handling
  • Community-Driven Validation with configurable schemes and reputation-weighted participation

The nondominium hApp represents a mature, comprehensive implementation of ValueFlows principles extended with Economic Process management, private reputation tracking, and sophisticated governance workflows, providing a robust foundation for decentralized commons-based resource management at scale.