Skip to content

API_REFERENCE.md

Latest commit

 

History

History
1456 lines (1227 loc) · 59.5 KB

API_REFERENCE.md

File metadata and controls

1456 lines (1227 loc) · 59.5 KB
Raw

Nondominium API Reference

Generated: 2025-12-17 · Resource / governance input structs re-synced against source 2026-08-29 (post-#132) Version: 3.1 (Updated with Current Implementation) Scope: Complete function documentation for all zomes based on actual codebase

🎯 API Overview

Nondominium implements a comprehensive REST-like API through Holochain zome functions, organized into three main zomes with distinct responsibilities. All functions follow consistent patterns for input validation, error handling, and DHT integration.

API Conventions

  • Input Types: Structured input parameters with validation
  • Return Types: ExternResult<T> with comprehensive error handling
  • Authentication: Agent identity automatically verified via agent_info()
  • Authorization: Role-based access control enforced at function level
  • Auditing: All operations create immutable audit trails

🔐 zome_person - Identity & Access Management

Person Profile Management

create_person(input: PersonInput) -> ExternResult<Record>

Purpose: Create a new agent profile with discovery anchors Authorization: Any agent can create their own profile Input:

pub struct PersonInput {
    pub name: String,
    pub avatar_url: Option<String>,
    pub bio: Option<String>,
}

Returns: Record containing the created Person entry Side Effects:

  • Creates Person entry with agent public key
  • Creates discovery anchor links for agent findability
  • Links agent pubkey to person entry Error Cases:
  • PersonError::PersonExists - Agent already has a profile
  • Network/DHT errors during entry creation

get_latest_person_record(original_action_hash: ActionHash) -> ExternResult<Option<Record>>

Purpose: Retrieve the most recent version of a person record Authorization: Public access (person data is public) Input: ActionHash of the original person entry Returns: Latest Record entry or None if not found Error Cases:

  • PersonError::PersonNotFound - No person entry found
  • Network/DHT errors during retrieval

get_latest_person(original_action_hash: ActionHash) -> ExternResult<Person>

Purpose: Retrieve the most recent version of a person entry Authorization: Public access (person data is public) Input: ActionHash of the original person entry Returns: Latest Person entry with all current fields Error Cases:

  • PersonError::PersonNotFound - No person entry found
  • PersonError::SerializationError - Record parsing failed

update_person(input: UpdatePersonInput) -> ExternResult<Record>

Purpose: Update an existing person profile Authorization: Only profile owner can update Input:

pub struct UpdatePersonInput {
    pub original_action_hash: ActionHash,
    pub name: Option<String>,
    pub avatar: Option<String>,
    pub bio: Option<String>,
    pub location: Option<String>,
    pub tags: Option<Vec<String>>,
}

Returns: Updated Record with new version Side Effects:

  • Creates new entry version with update links
  • Updates discovery anchors if needed
  • Maintains audit trail of changes Error Cases:
  • PersonError::Unauthorized - Not profile owner
  • PersonError::PersonNotFound - Original entry not found

get_all_persons(()) -> ExternResult<GetAllPersonsOutput>

Purpose: Discover all agents in the network Authorization: Public access for discovery Returns:

pub struct GetAllPersonsOutput {
    pub persons: Vec<PersonProfile>,
}

Performance: Uses anchor-based traversal for efficient discovery

get_person_profile(agent_pubkey: AgentPubKey) -> ExternResult<PersonProfileOutput>

Purpose: Get comprehensive profile information for a specific agent Authorization: Public access Returns:

pub struct PersonProfileOutput {
    pub person: Option<Person>,
    pub role: Option<PersonRole>,
    pub capability_level: String,
}

get_my_person_profile(()) -> ExternResult<PersonProfileOutput>

Purpose: Get current agent's complete profile Authorization: Current agent only Returns: Full profile including private information Performance: Optimized for current agent access patterns

get_agent_person_links(agent_pubkey: AgentPubKey) -> ExternResult<Vec<Link>>

Purpose: Get all links between an agent and person entries Authorization: Public access Returns: Vector of links showing agent-person relationships Use Case: Multi-device support and relationship management

get_agent_person(agent_pubkey: AgentPubKey) -> ExternResult<Option<ActionHash>>

Purpose: Get the primary person associated with an agent Authorization: Public access Returns: ActionHash of person entry if association exists Use Case: Agent-to-person lookup for profile access

get_person_agents(person_hash: ActionHash) -> ExternResult<Vec<AgentPubKey>>

Purpose: Get all agents associated with a person Authorization: Public access Returns: Vector of agent public keys Use Case: Multi-device support and agent management

add_agent_to_person(input: (AgentPubKey, ActionHash)) -> ExternResult<bool>

Purpose: Associate an additional agent with a person (multi-device support) Authorization: Person owner only Input: Tuple of (agent_pubkey, person_hash) Returns: Success status Use Case: Adding new devices to existing person profile

remove_agent_from_person(input: (AgentPubKey, ActionHash)) -> ExternResult<bool>

Purpose: Remove agent association from a person Authorization: Person owner only Input: Tuple of (agent_pubkey, person_hash) Returns: Success status Use Case: Removing lost or deactivated devices

is_agent_associated_with_person(input: (AgentPubKey, ActionHash)) -> ExternResult<bool>

Purpose: Check if agent is associated with person Authorization: Public access Input: Tuple of (agent_pubkey, person_hash) Returns: Boolean indicating association status Use Case: Authorization checks and validation

get_hrea_agents(hashes: Vec<ActionHash>) -> ExternResult<Vec<Option<Record>>>

Purpose: Retrieve ReaAgent records from the hREA DNA by action hashes Authorization: Public access Input: Vector of ActionHash values (typically from Person.hrea_agent_hash) Returns: Vector of optional Records (None if a hash is not found in hREA) Use Case: Resolve agent names and avatars from hREA without duplicating data in the Nondominium DNA. Part of the Phase 1 hREA bridge — see hREA/integration-strategy.md Pattern 5.

promote_agent_to_accountable(input: PromoteAgentInput) -> ExternResult<String>

Purpose: Promote an agent to accountable status with validation Authorization: Governance role required Input:

pub struct PromoteAgentInput {
    pub agent: AgentPubKey,
    pub first_resource_hash: ActionHash,
}

Returns: String indicating new capability level Use Case: Agent promotion workflow

Private Data Management

store_private_person_data(input: PrivatePersonDataInput) -> ExternResult<Record>

Purpose: Store private personal data with encryption Authorization: Current agent only Input:

pub struct PrivatePersonDataInput {
    pub legal_name: String,
    pub email: String,
    pub phone: Option<String>,
    pub address: Option<String>,
    pub emergency_contact: Option<String>,
    pub time_zone: Option<String>,
    pub location: Option<String>,
}

Returns: Encrypted Record with private data Security: Data encrypted before storage in DHT

update_private_person_data(input: UpdatePrivatePersonDataInput) -> ExternResult<Record>

Purpose: Update existing private personal data Authorization: Current agent only Input: Similar to PrivatePersonDataInput with optional fields for updates Returns: Updated encrypted Record Security: Data encrypted before storage in DHT

get_my_private_person_data(()) -> ExternResult<Option<PrivatePersonData>>

Purpose: Retrieve current agent's private data Authorization: Current agent only Returns: Decrypted private data if available Security: Automatic decryption for authorized access

`get_agent_private_data(

agent_pubkey: AgentPubKey,
required_fields: Vec<String>,

) -> ExternResult<Option>` Purpose: Access another agent's private data with authorization Authorization: Requires valid capability grant Input: Tuple of (agent_pubkey, required_fields) Returns: Private data if access authorized Security: Enforces capability-based access control

Device Management

register_device_for_person(input: RegisterDeviceInput) -> ExternResult<Record>

Purpose: Register a new device for a person (multi-device support) Authorization: Device owner or person representative Input:

pub struct RegisterDeviceInput {
    pub device_id: String,
    pub device_name: String,
    pub device_type: String, // "mobile", "desktop", "tablet", "web", "server"
    pub person_hash: ActionHash,
}

Returns: Created Device entry record Side Effects: Creates device-person relationship links

get_devices_for_person(person_hash: ActionHash) -> ExternResult<Vec<DeviceInfo>>

Purpose: Get all devices registered for a specific person Authorization: Person owner or authorized agent Returns: Vector of device information structures Use Case: Multi-device management and security

get_device_info(device_id: String) -> ExternResult<Option<DeviceInfo>>

Purpose: Get detailed information about a specific device Authorization: Device owner or authorized agent Returns: Device information if device exists Use Case: Device verification and management

update_device_activity(device_id: String) -> ExternResult<bool>

Purpose: Update the last active timestamp for a device Authorization: Any authenticated request for the device Returns: Success status Use Case: Device activity tracking and security monitoring

deactivate_device(device_id: String) -> ExternResult<bool>

Purpose: Deactivate a device (revoke access) Authorization: Device owner or person representative Returns: Success status Security: Prevents further access from deactivated device

get_my_devices(()) -> ExternResult<Vec<DeviceInfo>>

Purpose: Get all devices for the current agent Authorization: Current agent only Returns: Vector of device information for current agent Use Case: Device management interface for users

Capability-Based Sharing

grant_private_data_access(input: GrantPrivateDataAccessInput) -> ExternResult<GrantPrivateDataAccessOutput>

Purpose: Grant another agent access to specific private data fields Authorization: Data owner only Input:

pub struct GrantPrivateDataAccessInput {
    pub agent_to_grant: AgentPubKey,
    pub fields_allowed: Vec<String>,
    pub context: String,
    pub expires_in_days: Option<u32>,
}

Returns:

pub struct GrantPrivateDataAccessOutput {
    pub grant_hash: ActionHash,
    pub cap_secret: CapSecret,
}

Security: Creates granular, field-level access control

create_private_data_cap_claim(input: CreatePrivateDataCapClaimInput) -> ExternResult<Record>

Purpose: Create capability claim for private data access (for grantee) Authorization: Any agent can create claims Input:

pub struct CreatePrivateDataCapClaimInput {
    pub grantor: AgentPubKey,
    pub fields: Vec<String>,
    pub purpose: String,
    pub expires_at: Option<Timestamp>,
}

Returns: Capability claim record Security: Creates cryptographically secure capability claim

get_private_data_with_capability(input: GetPrivateDataWithCapabilityInput) -> ExternResult<FilteredPrivateData>

Purpose: Access private data using capability claim Authorization: Valid capability claim required Input:

pub struct GetPrivateDataWithCapabilityInput {
    pub target_agent: AgentPubKey,
    pub cap_claim: CapClaim,
    pub cap_secret: CapSecret,
    pub requested_fields: Vec<String>,
}

Returns: Filtered private data based on authorized fields Security: Cryptographic verification of capability claim

get_my_capability_grants(()) -> ExternResult<Vec<PrivateDataCapabilityMetadata>>

Purpose: List all active capability grants issued by current agent Authorization: Current agent only Returns: List of capability grants with metadata Utility: For managing and revoking access permissions

create_transferable_private_data_access(input: CreateTransferableAccessInput) -> ExternResult<Record>

Purpose: Create transferable access capability for delegation Authorization: Data owner only Input:

pub struct CreateTransferableAccessInput {
    pub agent_pubkey: AgentPubKey,
    pub fields: Vec<String>,
    pub context: String,
    pub expires_at: Option<Timestamp>,
}

Security: Enables controlled delegation of access rights Use Case: Service providers needing temporary access to client data

revoke_private_data_access(grant_hash: ActionHash) -> ExternResult<()>

Purpose: Revoke previously granted private data access Authorization: Grant owner only Input: ActionHash of the capability grant to revoke Security: Immediately terminates access permissions Use Case: Security incident response and access management

validate_capability_grant(grant_hash: ActionHash) -> ExternResult<bool>

Purpose: Validate if a capability grant is still active and valid Authorization: Public access Input: ActionHash of the capability grant to validate Returns: Boolean indicating grant validity Use Case: Pre-access validation and security checks

grant_role_based_private_data_access(input: RoleBasedAccessInput) -> ExternResult<Record>

Purpose: Grant private data access based on role assignment Authorization: System or governance role required Input:

pub struct RoleBasedAccessInput {
    pub role_name: String,
    pub fields: Vec<String>,
    pub context: String,
    pub expires_at: Option<Timestamp>,
}

Security: Role-based access control for private data Use Case: Organizational data access policies

validate_agent_private_data(input: ValidationDataRequest) -> ExternResult<ValidationResult>

Purpose: Validate an agent's request for private data access Authorization: Validation service or authorized validator Input:

pub struct ValidationDataRequest {
    pub requesting_agent: AgentPubKey,
    pub target_agent: AgentPubKey,
    pub requested_fields: Vec<String>,
    pub context: String,
}

Returns:

pub struct ValidationResult {
    pub is_valid: bool,
    pub granted_fields: Vec<String>,
    pub reason: Option<String>,
}

Security: Structured validation with reasoning

validate_agent_private_data_with_grant(input: ValidationWithGrantRequest) -> ExternResult<ValidationResult>

Purpose: Validate private data access with specific capability grant Authorization: Validation service or authorized validator Input: Validation request with specific grant information Returns: Validation result with grant-specific reasoning Security: Grant-specific validation for audit trails

Role Management

assign_person_role(input: PersonRoleInput) -> ExternResult<Record>

Purpose: Assign a role to an agent Authorization: System or governance role required Input:

pub struct PersonRoleInput {
    pub agent_pubkey: AgentPubKey,
    pub role_name: String,
    pub description: Option<String>,
}

Returns: Role assignment record Security: Role assignments create capability implications

get_latest_person_role_record(original_action_hash: ActionHash) -> ExternResult<Option<Record>>

Purpose: Retrieve the most recent version of a person role record Authorization: Public access for role verification Returns: Latest role record or None if not found Use Case: Role history and validation

get_latest_person_role(original_action_hash: ActionHash) -> ExternResult<PersonRole>

Purpose: Retrieve the most recent version of a person role Authorization: Public access for role verification Returns: Latest PersonRole entry Error Cases: Role not found, record parsing failed

update_person_role(input: UpdatePersonRoleInput) -> ExternResult<Record>

Purpose: Update an existing person role Authorization: System or governance role required Input:

pub struct UpdatePersonRoleInput {
    pub original_action_hash: ActionHash,
    pub previous_action_hash: ActionHash,
    pub role_name: Option<String>,
    pub description: Option<String>,
}

Returns: Updated role assignment record Security: Maintains audit trail of role changes

get_person_roles(agent_pubkey: AgentPubKey) -> ExternResult<GetPersonRolesOutput>

Purpose: Retrieve all roles assigned to an agent Authorization: Public access for role verification Returns:

pub struct GetPersonRolesOutput {
    pub roles: Vec<PersonRole>,
}

get_my_person_roles(()) -> ExternResult<GetPersonRolesOutput>

Purpose: Get current agent's roles with validation details Authorization: Current agent only Returns: Complete role information including validation metadata

get_person_capability_level(agent_pubkey: AgentPubKey) -> ExternResult<String>

Purpose: Determine agent's capability level based on roles Authorization: Public access for capability verification Returns: String capability level ("Simple Agent", "Accountable Agent", "Primary Accountable Agent", etc.) Logic:

  • "Simple Agent" - Basic agent capabilities
  • "Accountable Agent" - Resource access and management
  • "Primary Accountable Agent" - Process initiation and coordination
  • Specialized roles: "Transport Agent", "Repair Agent", "Storage Agent"

has_person_role_capability(input: (AgentPubKey, String)) -> ExternResult<bool>

Purpose: Check if agent has specific role capability Authorization: Public access for role verification Input: Tuple of (agent_pubkey, role_name) Returns: Boolean indicating role presence

Role Promotion Workflow

promote_agent_with_validation(input: PromoteAgentInput) -> ExternResult<Record>

Purpose: Promote an agent with validation and PPR generation Authorization: Governance role required Input:

pub struct PromoteAgentInput {
    pub agent: AgentPubKey,
    pub first_resource_hash: ActionHash,
}

Returns: Role promotion record with validation metadata Side Effects: Generates PPRs for promotion validation Security: Comprehensive validation with reputation assessment

request_role_promotion(input: RolePromotionRequest) -> ExternResult<ActionHash>

Purpose: Request role promotion for current agent Authorization: Any agent can request promotion Input:

pub struct RolePromotionRequest {
    pub desired_role: String,
    pub evidence: Option<String>,
    pub context: String,
}

Returns: ActionHash of the promotion request Use Case: Self-initiated promotion requests

approve_role_promotion(input: ApprovePromotionInput) -> ExternResult<Record>

Purpose: Approve a role promotion request Authorization: Governance role required Input:

pub struct ApprovePromotionInput {
    pub request_hash: ActionHash,
    pub validator_notes: Option<String>,
    pub assigned_role: String,
}

Returns: Approved role promotion record Side Effects: Creates PPRs for successful promotion Security: Multi-validator approval process

🏗️ zome_resource - Resource Lifecycle Management

NDO (NondominiumIdentity) Layer 0 Management

create_ndo(input: NdoInput) -> ExternResult<NdoOutput>

Purpose: Create a new Nondominium Identity (Layer 0 anchor) for a resource Authorization: Any agent Input:

pub struct NdoInput {
    pub name: String,
    pub property_regime: PropertyRegime,
    pub resource_nature: ResourceNature,
    pub lifecycle_stage: LifecycleStage, // any non-terminal stage
    pub description: Option<String>,
}

Returns: NdoOutput { action_hash, entry } — action_hash is the permanent Layer 0 identity PropertyRegime: seven canonical variants — Private, Commons, Collective, Pool, CommonPool, Public, Nondominium Side Effects: Creates AllNdos, AgentToNdo, NdoByLifecycleStage, NdoByNature, and NdoByPropertyRegime links Error Cases: Empty name, terminal initial stage (Hibernating, Deprecated, EndOfLife)

get_ndo(original_action_hash: ActionHash) -> ExternResult<Option<NondominiumIdentity>>

Purpose: Retrieve the latest version of an NDO by its stable Layer 0 identity hash Authorization: Public Returns: Latest NondominiumIdentity entry or None if not found on DHT

update_lifecycle_stage(input: UpdateLifecycleStageInput) -> ExternResult<ActionHash>

Purpose: Transition an NDO's lifecycle stage through the state machine Authorization: Initiator only Input:

pub struct UpdateLifecycleStageInput {
    pub original_action_hash: ActionHash,
    pub new_stage: LifecycleStage,
    pub successor_ndo_hash: Option<ActionHash>,    // required when new_stage == Deprecated
    pub transition_event_hash: Option<ActionHash>, // optional EconomicEvent reference
}

Returns: New ActionHash (original remains the stable Layer 0 identity) Side Effects: Moves NdoByLifecycleStage link to new stage anchor; conditionally creates NdoToSuccessor and NdoToTransitionEvent links Error Cases: Unauthorized, invalid state machine transition, missing successor_ndo_hash when entering Deprecated

get_all_ndos(()) -> ExternResult<GetAllNdosOutput>

Purpose: Discover all NDOs in the network Authorization: Public Returns: GetAllNdosOutput { ndos: Vec<NdoOutput> } — resolved to latest versions; unavailable entries silently skipped

get_my_ndos(()) -> ExternResult<GetAllNdosOutput>

Purpose: Retrieve all NDOs created by the calling agent Authorization: Any agent (scoped to caller) Returns: GetAllNdosOutput { ndos: Vec<NdoOutput> } — resolved to latest versions; unavailable entries silently skipped

get_ndos_by_lifecycle_stage(stage: LifecycleStage) -> ExternResult<GetAllNdosOutput>

Purpose: Query NDOs currently at a specific lifecycle stage Authorization: Public Returns: GetAllNdosOutput { ndos: Vec<NdoOutput> } — uses NdoByLifecycleStage anchor; silently skips unavailable entries Requirements: REQ-NDO-L0-05, REQ-NDO-L0-07

get_ndos_by_nature(nature: ResourceNature) -> ExternResult<GetAllNdosOutput>

Purpose: Query NDOs of a specific resource nature Authorization: Public Returns: GetAllNdosOutput { ndos: Vec<NdoOutput> } — uses NdoByNature anchor; silently skips unavailable entries Requirements: REQ-NDO-L0-05, REQ-NDO-L0-07

get_ndos_by_property_regime(regime: PropertyRegime) -> ExternResult<GetAllNdosOutput>

Purpose: Query NDOs under a specific property regime Authorization: Public Returns: GetAllNdosOutput { ndos: Vec<NdoOutput> } — uses NdoByPropertyRegime anchor; silently skips unavailable entries Requirements: REQ-NDO-L0-05, REQ-NDO-L0-07

Resource Specification Management

create_resource_specification(input: ResourceSpecificationInput) -> ExternResult<CreateResourceSpecificationOutput>

Purpose: Activate NDO Layer 1 — define the resource's form and its typed governance rules Authorization: Any agent; the target NDO must be at lifecycle stage Specification through Active Input:

pub struct ResourceSpecificationInput {
    pub name: String,
    pub description: String,
    pub category: String,
    pub image_url: Option<String>,
    pub tags: Vec<String>,
    pub scope: ResourceScope,          // Project | Network | Public
    pub ndo_identity_hash: ActionHash, // Layer 0 NDO this spec activates
    pub governance_rules: Vec<NestedGovernanceRuleInput>,
}

pub struct NestedGovernanceRuleInput {
    pub rule_data: RuleData,
    pub enforced_by: Option<String>,
}

Returns: CreateResourceSpecificationOutput { spec_hash, spec, governance_rule_hashes } Side Effects:

  • Creates the specification entry with discovery anchors (Project scope skips the global anchor)
  • Creates the NdoToSpecification link — this is Layer 1 activation
  • Creates each nested GovernanceRule and links it via SpecificationToGovernanceRule, so rules are never orphaned
  • Creates category and tag-based discovery links

get_latest_resource_specification(original_action_hash: ActionHash) -> ExternResult<ResourceSpecification>

Purpose: Retrieve most recent resource specification version Authorization: Public access Returns: Latest ResourceSpecification with all properties Error Cases: Specification not found, record corruption

update_resource_specification(input: UpdateResourceSpecificationInput) -> ExternResult<Record>

Purpose: Update resource specification with version tracking Authorization: Specification owner only Input:

pub struct UpdateResourceSpecificationInput {
    pub original_action_hash: ActionHash,
    pub name: Option<String>,
    pub description: Option<String>,
    pub resource_class: Option<String>,
    pub default_unit: Option<String>,
    pub custom_properties: Option<HashMap<String, PropertyValue>>,
    pub behavior: Option<String>,
    pub conforming: Option<bool>,
    pub image: Option<String>,
    pub category: Option<String>,
    pub tags: Option<Vec<String>>,
    pub governance_rules: Option<Vec<ActionHash>>,
}

Returns: Updated specification with version tracking

get_all_resource_specifications(()) -> ExternResult<GetAllResourceSpecificationsOutput>

Purpose: Discover all resource specifications in network Authorization: Public access Returns: GetAllResourceSpecificationsOutput { specifications, action_hashes } — parallel vectors of same length and order. action_hashes[i] is the original creation ActionHash for specifications[i], suitable for use as a stable route identifier (e.g. /ndo/[id]).

get_resource_specification_profile(action_hash: ActionHash) -> ExternResult<ResourceSpecificationProfile>

Purpose: Get comprehensive specification profile with metadata Authorization: Public access Returns: Specification with creation metadata and governance rules

get_resource_specifications_by_category(category: String) -> ExternResult<Vec<Record>>

Purpose: Find specifications by category classification Authorization: Public access Performance: Category-based anchor traversal for efficiency

get_resource_specifications_by_tag(tag: String) -> ExternResult<Vec<Record>>

Purpose: Find specifications with specific tags Authorization: Public access Utility: Tag-based resource discovery

get_my_resource_specifications(()) -> ExternResult<Vec<Link>>

Purpose: List specifications created by current agent Authorization: Current agent only Returns: Links to created specifications

Economic Resource Management

create_economic_resource(input: EconomicResourceInput) -> ExternResult<Record>

Purpose: Create resource instance from specification Authorization: Any agent can create resources Input:

pub struct EconomicResourceInput {
    pub resource_specification: ActionHash,
    pub name: String,
    pub accounting_quantity: Option<f64>,
    pub unit_of_effort: Option<String>,
    pub current_quantity: f64,
    pub primary_accountable: AgentPubKey,
    pub classified_as: Vec<String>,
    pub unit_of_resource: String,
    pub stage: Option<String>,
    pub state: Option<String>,
    pub location: Option<String>,
    pub note: Option<String>,
    pub image: Option<String>,
}

Returns: Created EconomicResource entry Side Effects:

  • Creates resource with lifecycle tracking
  • Links to specification for type validation
  • Establishes custody relationships
  • Creates economic event for resource creation

get_latest_economic_resource(original_action_hash: ActionHash) -> ExternResult<EconomicResource>

Purpose: Retrieve most recent resource state Authorization: Public access for resource discovery Returns: Current EconomicResource with state and metadata

update_economic_resource(input: UpdateEconomicResourceInput) -> ExternResult<Record>

Purpose: Update resource properties and state Authorization: Primary accountable agent or authorized role Input:

pub struct UpdateEconomicResourceInput {
    pub original_action_hash: ActionHash,
    pub name: Option<String>,
    pub accounting_quantity: Option<f64>,
    pub unit_of_effort: Option<String>,
    pub current_quantity: Option<f64>,
    pub primary_accountable: Option<AgentPubKey>,
    pub classified_as: Option<Vec<String>>,
    pub unit_of_resource: Option<String>,
    pub stage: Option<String>,
    pub state: Option<String>,
    pub location: Option<String>,
    pub note: Option<String>,
    pub image: Option<String>,
}

Returns: Updated resource with audit trail Security: Role-based authorization for resource updates

get_all_economic_resources(()) -> ExternResult<GetAllEconomicResourcesOutput>

Purpose: Discover all economic resources in network Authorization: Public access Performance: Anchor-based discovery with pagination support

get_economic_resource_profile(action_hash: ActionHash) -> ExternResult<EconomicResourceProfile>

Purpose: Get comprehensive resource profile with history Authorization: Public access Returns: Resource with specification details and lifecycle events

get_resources_by_specification(spec_hash: ActionHash) -> ExternResult<Vec<Record>>

Purpose: Find all resources of a specific type Authorization: Public access Utility: Resource browsing and discovery

get_my_economic_resources(()) -> ExternResult<Vec<Link>>

Purpose: List resources where current agent has custody or ownership Authorization: Current agent only Returns: Links to resources with relationship metadata

get_agent_economic_resources(agent_pubkey: AgentPubKey) -> ExternResult<Vec<Link>>

Purpose: List resources associated with specific agent Authorization: Public access Returns: Resources where agent has accountability or custody

update_operational_state(input: UpdateOperationalStateInput) -> ExternResult<Record>

Purpose: Update EconomicResource.operational_state (REQ-NDO-OS-01) Authorization: Current agent (interim; governance-zome ownership deferred per REQ-NDO-OS-02) Input:

pub struct UpdateOperationalStateInput {
    pub resource_hash: ActionHash,
    pub new_operational_state: OperationalState,
}

Returns: Updated EconomicResource record; moves ResourcesByOperationalState anchor link

get_resources_by_operational_state(state: OperationalState) -> ExternResult<Vec<Record>>

Purpose: Faceted discovery of economic resources by operational state (REQ-NDO-OS-06) Authorization: Public read Returns: Records linked from ndo.opstate.{state} anchor

Governance Rules Management

create_governance_rule(input: GovernanceRuleInput) -> ExternResult<Record>

Purpose: Create a typed governance rule bound to an NDO's classification Authorization: Any agent; check_rule_data_permitted rejects rules the NDO's PropertyRegime / ResourceNature forbid Input:

pub struct GovernanceRuleInput {
    pub rule_data: RuleData,           // AccessRequirement | UsageLimit | TransferCondition | MaintenanceSchedule
    pub enforced_by: Option<String>,
    pub ndo_identity_hash: ActionHash,
    pub property_regime: PropertyRegime,
    pub resource_nature: ResourceNature,
    pub rivalry_override: Option<Rivalry>,
    /// Set this to link the rule to a spec. Omitting it creates an orphan rule
    /// that `get_resource_specification_with_rules` cannot surface.
    pub specification_hash: Option<ActionHash>,
}

Returns: Created GovernanceRule entry Purpose: Embed compliance rules directly in resource definitions

get_latest_governance_rule(original_action_hash: ActionHash) -> ExternResult<GovernanceRule>

Purpose: Retrieve governance rule details Authorization: Public access for compliance verification Returns: Complete governance rule with validation logic

update_governance_rule(input: UpdateGovernanceRuleInput) -> ExternResult<Record>

Purpose: Update governance rule with version tracking Authorization: Governance role required Returns: Updated rule with audit trail

get_all_governance_rules(()) -> ExternResult<GetAllGovernanceRulesOutput>

Purpose: Discover all governance rules Authorization: Public access Returns: Array of all active governance rules

get_governance_rules_by_type(rule_type: String) -> ExternResult<Vec<Record>>

Purpose: Find governance rules by type classification Authorization: Public access Utility: Rule discovery and compliance checking

🏛️ zome_gouvernance - Governance & Reputation

Commitment Management

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

Purpose: Retrieve all commitments in the network Authorization: Public access for commitment discovery Returns: Array of all commitment entries Use Case: Finding available commitment opportunities

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

Purpose: Find commitments involving specific agent Authorization: Public access Returns: Commitments where agent is provider or receiver Utility: Agent reputation and capability assessment

Claim Management

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

Purpose: Retrieve all claims in the network Authorization: Public access Returns: Array of all claim entries Purpose: Claim discovery and verification

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

Purpose: Find claims related to specific commitment Authorization: Public access Returns: Claims providing evidence for commitment fulfillment Use Case: Commitment validation and reputation assessment

Economic Event Management

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

Purpose: Retrieve all economic events for transparency Authorization: Public access Returns: Array of all economic events Purpose: Complete economic activity audit trail

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

Purpose: Get economic history of specific resource Authorization: Public access Returns: Events affecting resource state and ownership Utility: Resource lifecycle tracking and provenance

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

Purpose: Get economic activity for specific agent Authorization: Public access Returns: Events where agent participated as provider or receiver Use Case: Agent economic reputation and activity assessment

PPR (Private Participation Receipt) System

get_my_participation_claims(input: GetMyParticipationClaimsInput) -> ExternResult<ParticipationClaimBundle>

Purpose: Retrieve current agent's PPR claims for reputation assessment Authorization: Current agent only Input:

pub struct GetMyParticipationClaimsInput {
    pub categories: Option<Vec<ParticipationClaimType>>,
    pub time_range: Option<TimeRange>,
    pub include_expired: bool,
}

Returns:

pub struct ParticipationClaimBundle {
    pub claims: Vec<ParticipationClaim>,
    pub summary: ReputationSummary,
    pub verification_contexts: Vec<VerificationContext>,
}

Security: Cryptographic verification of all PPR claims

create_service_commitment_pprs(commitment_hash: ActionHash) -> ExternResult<Vec<Record>>

Purpose: Automatically issue PPRs when service commitments are created Authorization: System function based on commitment creation Returns: Created PPR entries for commitment initiation Logic: Issues PPRs to both provider and potential receivers

create_service_fulfillment_pprs(commitment_hash: ActionHash) -> ExternResult<Vec<Record>>

Purpose: Issue PPRs upon successful commitment fulfillment Authorization: System function triggered by fulfillment validation Returns: PPR entries documenting successful service delivery Categories: Service-specific PPR categories based on commitment type

Validation System

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

Purpose: Create validation receipt for resource, service, or commitment Authorization: Validator role required Input:

pub struct CreateValidationReceiptInput {
    pub validated_item: ActionHash,
    pub validation_type: String,
    pub validator: AgentPubKey,
    pub assessment: String,
    pub confidence: f64,
    pub evidence: Option<String>,
    pub metrics: Option<HashMap<String, f64>>,
}

Returns: Validation receipt with cryptographic signature Purpose: Create evidence for PPR issuance and reputation building

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

Purpose: Retrieve complete validation history for any item Authorization: Public access Returns: All validation receipts for the specified item Use Case: Multi-reviewer validation and quality assessment

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

Purpose: Discover all validation receipts in network Authorization: Public access Returns: Array of all validation receipts Utility: Validator discovery and reputation assessment

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

Purpose: Create comprehensive resource validation with multi-reviewer process Authorization: Resource owner or authorized validator Input:

pub struct CreateResourceValidationInput {
    pub resource_hash: ActionHash,
    pub validation_type: String,
    pub required_reviewers: u32,
    pub validation_criteria: String,
    pub deadline: Option<u64>,
    pub incentive: Option<f64>,
}

Returns: Resource validation workflow setup Process: Initiates multi-reviewer validation workflow

Private Data Validation

get_validation_requirements(process_type: String) -> ExternResult<Vec<String>>

Purpose: Get required private data fields for economic process validation Authorization: Public access Returns: List of required private data fields Use Case: Process compliance and data access planning

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

Purpose: Create validation that requires access to private data Authorization: Authorized validator with capability grants Input:

pub struct CreateValidationWithPrivateDataInput {
    pub validated_item: ActionHash,
    pub validation_type: String,
    pub required_private_data: Vec<String>,
    pub validator: AgentPubKey,
    pub assessment: String,
    pub confidence: f64,
    pub data_access_grants: Vec<CapClaim>,
}

Returns: Validation with private data access verification Security: Requires valid capability grants for all accessed private data

NDO Federation Extensions

Added in PR #103. Implements REQ-NDO-EXT-01–16 from post-mvp/lobby-dna.md.

create_ndo_hard_link(input: CreateNdoHardLinkInput) -> ExternResult<ActionHash>

Purpose: Create a permanent, immutable OVN-licensed structural link between two NDOs Authorization: Any agent (immutability enforced at integrity layer) Input:

pub struct CreateNdoHardLinkInput {
    pub from_ndo_identity_hash: ActionHash,
    pub to_ndo_dna_hash: DnaHash,
    pub to_ndo_identity_hash: ActionHash,
    pub link_type: NdoLinkType, // Component | DerivedFrom | Supersedes
    pub fulfillment_hash: ActionHash,
}

Returns: ActionHash of the new NdoHardLink entry Use Case: Recording that one NDO is a component of, fork of, or supersedes another NDO

get_ndo_hard_links(ndo_identity_hash: ActionHash) -> ExternResult<Vec<NdoHardLinkRecord>>

Purpose: Retrieve all hard links originating from an NDO Authorization: Any agent (public DHT) Returns: Vec<NdoHardLinkRecord> via NdoToHardLinks anchor

get_ndo_hard_links_by_type(input: GetNdoHardLinksByTypeInput) -> ExternResult<Vec<NdoHardLinkRecord>>

Purpose: Retrieve hard links filtered by NdoLinkType Authorization: Any agent (public DHT) Returns: Filtered Vec<NdoHardLinkRecord>

validate_contribution(input: ValidateContributionInput) -> ExternResult<ActionHash>

Purpose: Record and peer-validate a work contribution (Work | Modify | Cite) on an NDO Authorization: Any agent; calling agent becomes first validator Input:

pub struct ValidateContributionInput {
    pub provider: AgentPubKey,
    pub action: VfAction,      // Work | Modify | Cite only
    pub ndo_identity_hash: ActionHash,
    pub note: String,
    pub effort_quantity: Option<f64>,
    pub has_point_in_time: Timestamp,
    // ... optional work log / process / fulfillment references
}

Returns: ActionHash of the Contribution entry Use Case: Recording that an agent performed design, development, or citation work on an NDO

get_ndo_contributions(ndo_identity_hash: ActionHash) -> ExternResult<Vec<ContributionRecord>>

Purpose: Retrieve all contributions for a given NDO Authorization: Any agent (public DHT) Returns: Vec<ContributionRecord> via NdoToContributions anchor

get_agent_contributions(provider: AgentPubKey) -> ExternResult<Vec<ContributionRecord>>

Purpose: Retrieve all contributions from a given provider agent Authorization: Any agent (public DHT) Returns: Vec<ContributionRecord> via AgentToContributions anchor

create_agreement(input: CreateAgreementInput) -> ExternResult<ActionHash>

Purpose: Create the first benefit redistribution Agreement (v1) for an NDO Authorization: Any agent; primary_accountable list declares governance signatories Input:

pub struct CreateAgreementInput {
    pub ndo_identity_hash: ActionHash,
    pub clauses: Vec<BenefitClause>,
    pub primary_accountable: Vec<AgentPubKey>,
}

Returns: ActionHash of the Agreement entry Use Case: Defining how economic benefits (monetary, governance weight, access rights) are distributed among NDO contributors

update_agreement(input: UpdateAgreementInput) -> ExternResult<ActionHash>

Purpose: Update an existing Agreement, incrementing version monotonically Authorization: Any agent; integrity enforces version = previous + 1 Returns: ActionHash of the updated Agreement entry

get_current_agreement(ndo_identity_hash: ActionHash) -> ExternResult<Option<AgreementRecord>>

Purpose: Retrieve the latest version of the Agreement for an NDO Authorization: Any agent (public DHT) Returns: Option<AgreementRecord> resolving the full update chain

Lobby DNA Functions (zome_lobby_coordinator)

Global discovery and federation layer. Uses canonical network_seed: nondominium-lobby-v1.

Agent Profile Functions

upsert_lobby_agent_profile(input: LobbyAgentProfileInput) -> ExternResult<ActionHash>

Purpose: Create or update the calling agent's Lobby profile (upsert pattern via update chain) Authorization: Any agent Returns: ActionHash of the new or updated entry Note: Creates two links on first call — global AllLobbyAgents (path anchor) and per-agent AgentToLobbyProfile (agent pubkey anchor, used for lookup and update detection)

get_lobby_agent_profile(agent: AgentPubKey) -> ExternResult<Option<LobbyAgentProfile>>

Purpose: Retrieve a specific agent's current Lobby profile (resolves update chain) Authorization: Any agent (public DHT) Returns: Option<LobbyAgentProfile>

get_all_lobby_agents(_: ()) -> ExternResult<Vec<LobbyAgentProfileRecord>>

Purpose: Retrieve all Lobby agent profiles via global path anchor Authorization: Any agent (public DHT) Returns: Vec<LobbyAgentProfileRecord>

Group Registry Functions

NDO discoverability flows through the Group layer, not the Lobby (Lobby → Groups → NDOs). The Lobby hosts the group registry; groups host NDOs.

announce_group(input: AnnounceGroupInput) -> ExternResult<Record>

Purpose: Register a group cloned cell in the Lobby DHT so other agents can discover it and obtain its DnaHash for CellId addressing Authorization: Any agent Input: { group_name, group_dna_hash: DnaHash, network_seed, description } Returns: Record of the created GroupAnnouncement entry

get_all_group_announcements(_: ()) -> ExternResult<Vec<Record>>

Purpose: Enumerate all group announcements via the lobby.groups path anchor Authorization: Any agent (public DHT)

get_my_group_announcements(_: ()) -> ExternResult<Vec<Record>>

Purpose: Return group announcements registered by the calling agent Authorization: Any agent (public DHT)

get_group_announcement_by_dna_hash(dna_hash: DnaHash) -> ExternResult<Option<Record>>

Purpose: Look up a group announcement by its cloned cell DNA hash Authorization: Any agent (public DHT)

get_my_groups(_: ()) -> ExternResult<Vec<GroupDescriptorStub>>

Purpose: Return lightweight stubs for the calling agent's announced groups Returns: Vec<GroupDescriptorStub> derived from get_my_group_announcements

🔗 Cross-Zome Integration Functions

Agent Capability Assessment

These functions combine data from multiple zomes to provide comprehensive capability assessment:

// Combined capability evaluation (pseudo-code)
fn evaluate_agent_capability(agent: AgentPubKey) -> CapabilityAssessment {
    let person_info = zome_person::get_person_capability_level(agent)?;
    let reputation = zome_gouvernance::get_my_participation_claims(agent)?;
    let resources = zome_resource::get_agent_economic_resources(agent)?;

    CapabilityAssessment {
        level: person_info.capability_level,
        reputation_score: reputation.summary.overall_score,
        resource_count: resources.len(),
        eligible_processes: calculate_eligible_processes(person_info, reputation),
    }
}

Economic Process Validation

Cross-zome validation ensures process compliance across all domains:

// Process authorization validation (pseudo-code)
fn validate_process_authorization(
    agent: AgentPubKey,
    process_type: EconomicProcess
) -> AuthorizationResult {
    let capability = zome_person::get_person_capability_level(agent)?;
    let reputation = zome_gouvernance::derive_reputation_score(agent)?;

    match process_type {
        UseProcess => {
            require_capability_level(capability, "stewardship")?;
            validate_reputation_threshold(reputation, USE_PROCESS_THRESHOLD)?;
        },
        TransportProcess | StorageProcess | RepairProcess => {
            require_capability_level(capability, "coordination")?;
            validate_reputation_threshold(reputation, ADVANCED_PROCESS_THRESHOLD)?;
            validate_specialized_role(agent, process_type)?;
        }
    }
}

🛡️ Security & Authorization Patterns

1. Capability-Based Access Control

All API functions enforce capability-based authorization:

// Standard authorization pattern
fn check_authorization(agent: AgentPubKey, required_level: &str) -> Result<(), AuthorizationError> {
    let current_level = get_person_capability_level(agent)?;
    if !capability_sufficient(&current_level, required_level) {
        return Err(AuthorizationError::InsufficientCapability);
    }
    Ok(())
}

2. Private Data Protection

Private data functions implement field-level access control:

// Private data access pattern
fn authorize_private_data_access(
    requestor: AgentPubKey,
    target: AgentPubKey,
    fields: Vec<String>
) -> Result<DataAccessGrant, AccessError> {
    let grant = validate_capability_claim(requestor, target, fields)?;
    ensure_grant_not_expired(&grant)?;
    ensure_field_authorized(&grant, fields)?;
    Ok(grant)
}

3. PPR Cryptographic Verification

PPR functions implement cryptographic verification:

// PPR verification pattern
fn verify_ppr_authenticity(ppr: &ParticipationClaim) -> Result<VerificationResult, VerificationError> {
    let signature_valid = verify_signature(&ppr.signature, &ppr.issuer, &ppr.content)?;
    let context_valid = verify_verification_context(&ppr.verification_context)?;
    let not_expired = check_expiration(&ppr.expires_at)?;

    Ok(VerificationResult {
        signature_valid,
        context_valid,
        not_expired,
        overall_trust_score: calculate_trust_score(ppr),
    })
}

📊 Performance & Optimization

DHT Optimization Patterns

  • Anchor-Based Discovery: All discovery functions use anchor paths for efficient DHT traversal
  • Link Caching: Frequently accessed link queries are cached at the conductor level
  • Batch Operations: Multi-entry operations minimize DHT round trips

Memory Management

  • Lazy Loading: Large data structures are loaded on-demand
  • Reference Counting: Shared data structures use reference counting to prevent memory leaks
  • Cleanup Strategies: Expired capabilities and outdated entries are periodically cleaned up

Network Efficiency

  • Compression: Large data payloads are compressed before DHT storage
  • Validation Caching: Validation results are cached to reduce redundant computations
  • Async Processing: Long-running operations use async patterns to prevent blocking

🔮 API Evolution & Extensibility

Versioning Strategy

  • Semantic Versioning: API versions follow semantic versioning (MAJOR.MINOR.PATCH)
  • Backward Compatibility: Deprecated functions remain supported for at least one major version
  • Migration Paths: Clear migration guidelines provided for breaking changes

Extension Points

  • Custom Validation: Pluggable validation modules for domain-specific requirements
  • New PPR Categories: Extensible PPR system for new reputation dimensions
  • Process Types: Economic process system supports new process type definitions

Integration APIs

Future API extensions will include:

  • External System Integration: Webhook and event streaming capabilities
  • Analytics APIs: Advanced reputation and economic analytics
  • Governance APIs: Dynamic rule management and democratic governance features

📋 Error Handling Reference

Common Error Types

// Person Management Errors (actual implementation)
pub enum PersonError {
    PersonAlreadyExists,
    PersonNotFound(String),
    PrivateDataNotFound,
    RoleNotFound(String),
    NotAuthor,
    SerializationError(String),
    EntryOperationFailed(String),
    LinkOperationFailed(String),
    InvalidInput(String),
    InsufficientCapability(String),
}

// Resource Management Errors (actual implementation)
pub enum ResourceError {
    ResourceSpecNotFound(String),
    EconomicResourceNotFound(String),
    GovernanceRuleNotFound(String),
    NotAuthor,
    NotCustodian,
    SerializationError(String),
    EntryOperationFailed(String),
    LinkOperationFailed(String),
    InvalidInput(String),
    GovernanceViolation(String),
}

// Governance Errors (actual implementation)
pub enum GovernanceError {
    ValidationReceiptNotFound(String),
    EconomicEventNotFound(String),
    ResourceValidationNotFound(String),
    CommitmentNotFound(String),
    NotAuthorizedValidator,
    InsufficientCapability(String),
    ValidationAlreadyExists(String),
    InvalidValidationScheme(String),
    SerializationError(String),
    EntryOperationFailed(String),
    LinkOperationFailed(String),
    InvalidInput(String),
    CrossZomeCallFailed(String),
}

Error Response Format

All API functions return ExternResult<T> with comprehensive error information:

pub struct ErrorDetails {
    pub error_type: String,
    pub error_code: u32,
    pub message: String,
    pub details: Option<String>,
    pub retry_possible: bool,
    pub suggested_actions: Vec<String>,
}

🏘️ zome_group — Per-Group Coordination (Group DNA, cloned cell)

Full documentation: zomes/group_zome.md

Each group occupies its own cloned cell. Functions below operate within the calling cell's isolated DHT. The TypeScript GroupService uses CellId (DnaHash + AgentPubKey) to address the correct cloned cell — the group_dna_hash in the Lobby's GroupAnnouncement is used to resolve the CellId via getGroupCellHandle(client, dnaHash).

Group Profile

create_group(input: GroupProfileInput) -> ExternResult<Record>

Input: { name: String, description: Option<String> } Returns: Created GroupProfile record. Also creates the all_groups anchor link. Validation: name non-empty, ≤ 100 characters. Note: Initiator and created_at come from the action header (record.action().author() / record.action().timestamp()), not from entry fields.

get_group(group_hash: ActionHash) -> ExternResult<Option<Record>>

Retrieves a GroupProfile by action hash.

get_my_group() -> ExternResult<Option<Record>>

Returns the single GroupProfile in this cloned cell (one group per cell). Use this instead of get_all_groups — in the one-group-per-cell model, it's always 0 or 1 results.

update_group(input: UpdateGroupInput) -> ExternResult<Record>

Input: { previous_action_hash: ActionHash, original_action_hash: ActionHash, updated_name: String, updated_description: Option<String> } Updates the group name and/or description. Only the original initiator may update. Creates a GroupUpdates link from original_action_hash to the new version's action hash.

Membership

join_group(group_hash: ActionHash) -> ExternResult<Record>

Creates a GroupMembership entry and GroupToMembers + MemberToGroups links. Guard: Returns GroupError::AlreadyMember if agent already has a membership entry.

leave_group(group_hash: ActionHash) -> ExternResult<()>

Deletes the GroupToMembers and MemberToGroups links for the calling agent. The GroupMembership entry is intentionally retained on-chain as an audit trail.

get_group_members(group_hash: ActionHash) -> ExternResult<Vec<AgentPubKey>>

Returns the AgentPubKey of every current member, read from each GroupToMembers link's author in a single get_links round-trip (does not get each GroupMembership record, which may be absent from the local shard before sync).

is_member(input: (AgentPubKey, ActionHash)) -> ExternResult<bool>

Predicate: does the given agent appear in get_group_members?

Work Logs

log_work(input: WorkLogInput) -> ExternResult<Record>

Input: { group_hash: ActionHash, description: String, hours: f32 } Creates a WorkLog entry with GroupToWorkLogs and AgentToWorkLogs links. Validation: description non-empty; hours > 0.

get_work_logs(group_hash: ActionHash) -> ExternResult<Vec<Record>>

Returns Records for all WorkLog entries in the group. Author = record.action().author().

get_my_work_logs() -> ExternResult<Vec<Record>>

Returns Records for WorkLog entries authored by the calling agent (via AgentToWorkLogs links).

Soft Links

Note: SoftLinks are no longer the Group → NDO pointer — see NDO Anchors below. They remain available for planning-level links.

create_soft_link(input: SoftLinkInput) -> ExternResult<Record>

Input: { group_hash: ActionHash, target_ndo_hash: ActionHash, description: Option<String> } Creates a SoftLink entry — a planning-level Group → NDO relationship. No PPRs generated (ADR-GROUP-04). Creator = action author.

get_soft_links(group_hash: ActionHash) -> ExternResult<Vec<Record>>

Returns Records for all SoftLink entries in the group. Creator = record.action().author().

NDO Anchors

The authoritative Group → NDO pointer in the Lobby → Groups → NDOs hierarchy (ADR-011). Each NDO is its own cloned ndo cell (ADR-010); the anchor carries the coordinates needed to re-derive, verify, and join that cell, plus cached fields so browsing never joins it. Rationale: documentation/specifications/adr/ADR-010-013-per-ndo-cells.md.

create_ndo_anchor(input: NdoAnchorInput) -> ExternResult<Record>

Input: { group_hash: ActionHash, name: String, description: Option<String>, ndo_dna_hash: DnaHash, network_seed: String, identity_action_hash: ActionHash, initiator: AgentPubKey, ndo_created_at: Timestamp, lifecycle_stage: LifecycleStage, property_regime: PropertyRegime, resource_nature: ResourceNature } Creates an NdoAnchor and links it from the group (GroupToNdoAnchors). Anchor author and timestamp come from the action header. The same NDO may be anchored in several groups.

get_ndo_anchors(group_hash: ActionHash) -> ExternResult<Vec<Record>>

Returns the latest Record for every anchor in the group, resolving the NdoAnchorUpdates chain so cached descriptor fields reflect the most recent sync.

update_ndo_anchor(input: UpdateNdoAnchorInput) -> ExternResult<Record>

Input: { original_action_hash: ActionHash, previous_action_hash: ActionHash, updated_name: String, updated_description: Option<String>, updated_lifecycle_stage: LifecycleStage } Refreshes an anchor's cached descriptor. Identity coordinates are copied from the original entry, and integrity rejects any update that changes them (validate_ndo_anchor_update), so an update can never repoint a group at a different NDO cell.

refresh_ndo_anchor_lifecycle_stage(input: RefreshAnchorLifecycleInput) -> ExternResult<Option<Record>>

Input: { group_hash: ActionHash, identity_action_hash: ActionHash, updated_lifecycle_stage: LifecycleStage } Re-syncs one anchor's cached lifecycle_stage after an NDO lifecycle transition, resolving the anchor by NDO identity rather than by action hash — the client knows the NDO, while the original-vs-latest anchor action hashes belong to the group's link graph. Returns Ok(None) when no anchor in this group points at that NDO (a no-op, not an error).

This API reference represents the complete current functionality of the Nondominium system based on actual codebase analysis. Function signatures and behaviors evolve with implementation improvements and community feedback.

🔄 Updates in Version 3.0 (2025-12-17)

Major Corrections:

  • ✅ PersonInput structure: Corrected avatar → avatar_url, removed non-existent location and tags fields
  • ✅ Function signatures: Updated all function signatures to match actual implementation
  • ✅ Error types: Replaced with actual error enums from the codebase

New Function Categories Added:

  • 🆕 Device Management (6 functions): Multi-device support with registration, deactivation, activity tracking
  • 🆕 Advanced Capability Sharing (4 functions): Grant revocation, validation, role-based access
  • 🆕 Role Promotion Workflow (3 functions): Request/approve/promotion with PPR integration

Missing Functions Now Included:

  • Person Management: Added 8 missing functions for agent-person relationships and promotion
  • Private Data: Added store_private_person_data and corrected get_agent_private_data signature
  • Capability System: Added grant_private_data_access, revoke_private_data_access, validation functions

Accuracy Improvements:

  • Capability Levels: Updated to reflect actual role types ("Simple Agent", "Accountable Agent", etc.)
  • Security Patterns: Corrected to match actual implementation patterns
  • Data Structures: All input/output structures now match actual code