Nondominium Project Documentation Index

Updated: 2026-08-13

Annotated guide to the documentation set. For the topic-grouped hub see README.md; for a flat table of contents see SUMMARY.md.

🎯 Project Overview

Nondominium is a ValueFlows-compliant Holochain application implementing distributed, agent-centric resource management with embedded governance, capability-based security, and cryptographically-secured reputation tracking through Private Participation Receipts (PPRs).

Quick Navigation

• Getting Started - Development setup & quick start
• Architecture - System design & zome interactions
• API Documentation - Complete function reference
• Testing - Test strategy & execution
• Implementation Status - Current development progress

🚀 Getting Started

Prerequisites & Setup

git submodule update --init --recursive  # Initialize the hREA submodule (REQUIRED)
nix develop                              # Enter reproducible environment (REQUIRED)
bun install                              # Install dependencies

Key Documentation:

• 🎯 TELOS - Project vision, mission, philosophy, and AI operating principles
• 📋 Main README - Complete project overview & setup guide
• 🔧 Development Environment - Development patterns & commands

Essential Commands

# Development
bun run start            # Start 2-agent development network with UIs
AGENTS=3 bun run network # Custom agent network

# Testing — Sweettest (Rust, primary)
bun run sweettest        # build:happ + all nondominium Sweettest tests
bun run sweettest:only   # skip the build step

# Testing — E2E (Playwright + real conductors)
bun run e2e
bun run e2e:ui

# Build
bun run build:zomes     # Compile Rust zomes to WASM
bun run build:happ      # Build zomes + hREA, pack all DNAs into the .happ bundle
bun run package         # Create final .webhapp distribution

Canonical command reference for every suite: TEST_COMMANDS.md.

Note: Tryorama (TypeScript) tests in tests/ are deprecated. All new tests use Sweettest (Rust). See tests/DEPRECATED.md.

🏗️ Architecture Overview

System Architecture

nondominium implements a Governance-as-Operator architecture that separates data management from business logic enforcement:

• Framework: Holochain HDK ^0.6.0 / HDI ^0.7.0 (Rust + WASM)
• Frontend: SvelteKit 2 + Svelte 5 + TypeScript + Vite 7
• Testing: Sweettest (Rust, primary) — Tryorama (TypeScript) deprecated
• Client: @holochain/client ^0.20.0
• Package Management: Bun for dependency management and build orchestration

Zome Structure

Governance-as-Operator Architecture

Key Design Principles:

• Modular Design: Resource zome manages data, governance zome enforces rules
• Swappable Governance: Different governance schemes can be applied to same resources
• Pure Function Governance: Stateless evaluation with deterministic outputs
• Event-Driven State Changes: All transitions generate audit events
• Cross-Zome Interface: Well-defined communication protocol

Documentation:

• Governance Operator Architecture - Technical architecture and design patterns
• Governance Implementation Guide - Detailed implementation with code examples
• Cross-Zome API - Complete API specifications

Key Concepts

• 🔐 Capability-Based Security: Progressive trust model (Simple → Accountable → Primary Accountable Agent)
• 📋 Private Participation Receipts (PPRs): Cryptographic reputation tracking across 16 categories
• 🔄 Economic Processes: Structured workflows (Use, Transport, Storage, Repair) with role-based access
• 🛡️ Private Data Sharing: Request/grant workflows with field-level control and time-limited grants (30-day maximum per PrivateDataCapabilityMetadata; shorter defaults may apply in UI flows — see person_zome.md)

📚 Core Documentation

Project Requirements

Architecture & Roadmap

Technical Specifications

Post-MVP Requirements

Testing & Infrastructure

Applications & Use Cases

🔧 API Documentation

Full reference: API Reference

Person Zome API

Core Identity & Access Management

• create_person() - Create agent profile with discovery anchors
• get_person() - Retrieve profile by hash
• get_all_persons() - Discover all agents via anchor traversal
• update_person() - Update profile with validation
• delete_person() - Soft deletion with cleanup

Capability & Security

• create_capability_token() - Issue capability tokens with role restrictions
• get_agent_capability_level() - Query current trust level
• promote_agent_capability() - Advance trust based on PPR milestones

Private Data Sharing

• request_private_data_access() - Request access to specific fields
• grant_private_data_access() - Grant time-limited access (subject to 30-day maximum enforced in capability metadata)
• get_private_data() - Retrieve authorized private data
• revoke_private_data_access() - Revoke granted permissions

Role Management

• assign_role() - Assign roles with validation metadata
• get_agent_roles() - Query current role assignments
• validate_role_requirements() - Check role qualification status

Resource Zome API (Data Model Only)

Resource Specification Management

• create_resource_specification() - Define resource types and properties
• get_resource_specification() - Retrieve specification details
• get_all_resource_specifications() - Discover all specifications
• update_resource_specification() - Modify specifications with validation

Economic Resource Management

• create_economic_resource() - Create resource instances with initial state
• get_economic_resource() - Retrieve resource current state and history
• get_economic_resource_with_state() - Retrieve resource with full state transitions
• update_operational_state() - Update EconomicResource.operational_state
• get_my_resources() - Discover resources where calling agent is custodian
• get_resources_by_specification() - Find resources conforming to specification
• get_resources_by_operational_state() - Query resources by operational state

Cross-Zome State Transitions

• request_resource_transition() - Request state change through governance evaluation
• batch_state_transitions() - Process multiple state transitions efficiently

Governance Zome API (State Transition Operator)

State Transition Evaluation

• evaluate_state_transition() - Evaluate governance rules for state changes
• get_applicable_rules() - Retrieve governance rules for resource/action
• evaluate_rule() - Evaluate individual governance rule
• check_agent_permissions() - Verify agent has required permissions
• get_agent_roles() - Retrieve agent's current role assignments

Economic Event Generation

• generate_economic_event() - Create audit events for state transitions
• validate_transition_chain() - Validate sequence of state changes
• get_transition_history() - Retrieve complete audit trail

Governance Rule Management

• create_governance_rule() - Create new governance rules
• update_governance_rule() - Modify existing rules
• get_governance_rules() - Retrieve applicable rules

Legacy Commitment Management (PPR System)

• create_commitment() - Create commitments with validation rules
• get_commitment() - Retrieve commitment details
• fulfill_commitment() - Mark commitments as fulfilled

PPR System

• issue_ppr() - Issue Private Participation Receipt (16 categories)
• get_ppr_summary() - Retrieve reputation summary across categories
• validate_ppr_eligibility() - Check qualification requirements
• derive_reputation_score() - Calculate cryptographic reputation metrics

Multi-Reviewer Validation

• create_validation_workflow() - Set up validation (2-of-3, N-of-M, simple_majority)
• submit_validation_review() - Submit validation assessments
• check_validation_consensus() - Determine validation outcomes

Agent Promotion

• evaluate_agent_promotion() - Assess readiness for capability advancement
• promote_to_accountable_agent() - Promote based on transaction validation
• promote_to_primary_accountable_agent() - Promote based on PPR milestones

🧪 Testing Infrastructure

Test Architecture

All new tests use Sweettest (Rust) in dnas/nondominium/tests/src/. Tryorama (TypeScript) tests in tests/ are deprecated.

# Prerequisites
bun run build:happ

# Run all tests
CARGO_TARGET_DIR=target/native-tests cargo test --package nondominium_sweettest

# Run a specific module
CARGO_TARGET_DIR=target/native-tests cargo test --package nondominium_sweettest --test person

# Verbose output
CARGO_TARGET_DIR=target/native-tests cargo test --package nondominium_sweettest -- --nocapture

Shared Setup Utilities

• setup_two_agents() — two conductors with nondominium DNA
• setup_three_agents() — three conductors with nondominium DNA
• setup_dual_dna_two_agents() — two conductors with nondominium + hREA DNAs

Development Tips

• Use warn! macro in Rust zome functions to log debugging information visible in test output
• Use #[ignore] on tests not yet ready for execution
• DHT sync between agents: await_consistency_20_s([&cell_a, &cell_b]).await.unwrap() (pass the array by value, not &[...])

📊 Implementation Status

✅ Phase 1 Complete: Foundation System

• Person Management: Agent profiles, roles, and basic capability tokens
• Identity System: Pseudonymous identity with public/private separation
• Basic Access Control: Role-based access with validation metadata
• hREA Bridge: Person/ReaAgent bridge for ValueFlows compliance

✅ MVP Complete: Advanced Governance & UI

• Capability-Based Sharing: Complete request/grant workflows with time-limited grants (30-day cap)
• PPR System: 16-category reputation tracking with cryptographic signatures
• Economic Processes: Four structured processes (Use, Transport, Storage, Repair)
• Multi-Reviewer Validation: 2-of-3, N-of-M, and simple majority validation
• Agent Promotion: Progressive trust model with automatic advancement
• NDO Layer 0: NondominiumIdentity permanent identity anchor with lifecycle transitions
• MVP UI: Lobby → Group → NDO three-level hierarchy, NDO creation, lifecycle browser, fork friction modal

🔄 Phase 2 (In Progress): Economic Processes & PPR Generation

• Economic processes (Use/Transport/Storage/Repair) backend
• PPR receipt generation from Commitment/Claim/Event cycles
• Governance-as-operator full implementation
• Agent promotion workflows

📋 Post-MVP

• Group DNA backend, NDO cell cloning
• PPR reputation UI
• Unyt/Flowsta integrations
• Collective agent types, affiliation spectrum

🔍 Advanced Features

Private Participation Receipt (PPR) System

16 PPR Categories:

Genesis Roles (Network Entry):

1. ResourceCreation - Recognition for successful resource contributions
2. ResourceValidation - Credit for network validation activities

Core Usage Roles (Custodianship): 3. CustodyTransfer - Outgoing custodian recognition 4. CustodyAcceptance - Incoming custodian validation

Intermediate Roles (Specialized Services): 5. MaintenanceCommitmentAccepted - Maintenance agreement recognition 6. MaintenanceFulfillmentCompleted - Maintenance service completion 7. StorageCommitmentAccepted - Storage service agreement 8. StorageFulfillmentCompleted - Storage service completion 9. TransportCommitmentAccepted - Transport service agreement 10. TransportFulfillmentCompleted - Transport service completion 11. GoodFaithTransfer - Trust-based transfer recognition

Network Governance: 12. DisputeResolutionParticipation - Constructive conflict resolution 13. ValidationActivity - Ongoing validation duties 14. RuleCompliance - Consistent governance adherence

Resource End-of-Life: 15. EndOfLifeDeclaration - Responsible lifecycle management 16. EndOfLifeValidation - Expert validation services

Economic Processes with Role-Based Access

Progressive Trust Model

Simple Agent (member)
├── General capability token
├── Can create resources & make first transaction
├── PPR eligibility: ResourceContribution upon validation
└── Promotion: First validated transaction → Accountable Agent

Accountable Agent (stewardship)
├── Restricted capability token
├── Can access resources & validate others
├── PPR eligibility: Service processes & validation
└── Promotion: PPR milestones + role validation → Primary Agent

Primary Accountable Agent (coordination/governance)
├── Full capability token
├── Can hold custody & validate specialized roles
├── PPR eligibility: All 16 categories
└── Advanced: Dispute resolution & end-of-life validation

🔗 External References

Technology Stack

• Holochain - Distributed application framework
• ValueFlows - Economic coordination ontology
• hREA - Holochain implementation of ValueFlows
• @holochain/client - UI client library
• Holochain Playground - Development tools

Development Tools

• hc CLI - Holochain development tool
• Svelte - Frontend framework
• Vite - Build tool and development server

📝 Development Notes

Code Patterns

• Entry Creation: All zomes follow consistent create/get/update/delete patterns
• Anchor Links: Discovery anchors for all major entry types
• Validation: Comprehensive validation with role-based access control
• Privacy: Public/private data separation with capability-based access

Testing Patterns

• Multi-Agent: All tests support 2+ distributed agents
• DHT Sync: Use await_consistency_20_s with the timeout wrapper
• Debug Support: Verbose logging with warn! macro for Rust debugging
• Isolation: Test isolation with proper cleanup between scenarios

Performance Considerations

• WASM Compilation: Rust zomes compiled to WASM for efficiency
• DHT Optimization: Efficient link traversal for discovery operations
• Validation Caching: Role and capability validation caching
• PPR System: Optimized reputation calculation with cryptographic proofs

🔄 Document Maintenance

Last Updated: 2026-05-04 Maintainers: Development Team

Update Process

1. Code changes → Update relevant API documentation
2. Feature completion → Update implementation status
3. Architecture changes → Update architecture overview
4. Test additions → Update testing documentation