hREA ValueFlows 1.0 Compliance Analysis

Branch: vendor/hrea — detached HEAD at fc3b5e78 VF Spec Version: 1.0.0 (CC-BY-SA 4.0) VF Ontology source: https://w3id.org/valueflows/ont/vf# Analysis date: 2026-03-25 Analysts: Soushi888, SoushAI

Table of Contents

1. Executive Summary
2. Methodology
3. Overall Compliance Score
4. Missing Entity Types
5. Field-Level Gaps by Entity
6. Action Model Gaps
7. Validation Gaps
8. Naming and Structural Observations
9. Recommendations
10. Appendix: Full Field Mapping Tables

Executive Summary

hREA main-0.6 implements the structural core of the ValueFlows 1.0 ontology competently: the foundational economic flow cycle (Agent, EconomicResource, EconomicEvent, Process) is present and linked correctly. The planning layer (Intent, Commitment, Plan, Proposal) and the knowledge layer (ResourceSpecification, ProcessSpecification, Recipe*) are scaffolded with correct relational structure.

However, five VF 1.0 entity classes are entirely absent, the Action model covers only 4 of 10 effect dimensions, all entry validation functions are stubs with no business rule enforcement, and several field-level gaps break round-trip interoperability with other VF-compliant systems (e.g., Bonfire).

Overall estimated compliance: ~65%

The most consequential gap for immediate interoperability is the absence of vf:Claim and the missing effortQuantity on EconomicEvent. The most consequential gap for long-term correctness is the wholesale absence of validation logic.

Methodology

Analysis performed by:

1. Reading the VF 1.0 TTL ontology via the HTML rendering at http://ontprox.dev.opensourceecology.de/?uri=https://codeberg.org/valueflows/pages/raw/branch/main/assets/all_vf.TTL extracting all class definitions, properties, ranges, and named individuals.

2. Reading every Rust integrity zome struct in vendor/hrea/dnas/hrea/zomes/integrity/hrea/src/ cataloguing all fields and their types.

3. Reading the coordinator zome public function signatures in vendor/hrea/dnas/hrea/zomes/coordinator/hrea/src/

4. Reading the action builtins in vendor/hrea/dnas/hrea/zomes/coordinator/hrea/vf_actions/src/builtins.rs

5. Cross-referencing hREA struct fields against VF 1.0 property names and ranges.

No compilation or runtime testing was performed. All findings are structural (type-level) only.

Overall Compliance Score

Missing Entity Types

These VF 1.0 classes have no corresponding entry type in hREA main-0.6.

1. vf:Claim (P0 — Critical)

VF 1.0 definition: "A claim for future economic event(s) in reciprocity for events already occurred."

Key properties:

• vf:triggeredBy (EconomicEvent) — the event that triggers the claim
• vf:settles on EconomicEvent — the event that settles an open claim

Impact on hREA: ReaEconomicEvent has no settles field. Any VF workflow using claim-based reciprocity (invoicing, contribution tracking in OVNs) cannot be expressed. This breaks Nondominium's planned contribution accounting workflow.

Implementation path: Add ReaClaim integrity entry type; add settles: Option<Vec<ActionHash>> to ReaEconomicEvent.

2. vf:SpatialThing (P1)

VF 1.0 definition: "Data locating something relative to Earth, usually fixed location."

Key properties: latitude, longitude, altitude, mappableAddress, hasDetailedGeometry

Current hREA state: All location fields across all entry types (ReaEconomicEvent.at_location, ReaEconomicResource.current_location, ReaProcess implied) are Option<String>. This is a plain text field, not a structured location object.

Impact: Interoperability with location-aware VF clients or Bonfire's SpatialThing support is broken. Cross-system queries on location cannot be typed.

Implementation path: Add ReaSpatialThing entry type. Replace *_location: Option<String> fields with *_location: Option<ActionHash> referencing a ReaSpatialThing.

3. vf:BatchLotRecord (P2)

VF 1.0 definition: "Document containing detail related to production of particular batch or lot."

Key properties: batchLotCode (string), expirationDate (dateTimeStamp)

Current hREA state: ReaEconomicResource.lot: Option<String> — stores just a code string. Expiration date is not present.

Impact: Perishable goods tracking, pharmaceutical lot tracking, and any time-bounded batch workflow cannot express lot expiration.

Implementation path: Add ReaBatchLotRecord entry type. Change lot: Option<String> to of_batch_lot: Option<ActionHash> on ReaEconomicResource.

4. vf:AgreementBundle (P2)

VF 1.0 definition: "Grouping of agreements for bundled line item reciprocity."

Current hREA state: No equivalent. ReaAgreement has no bundledIn field.

Impact: Multi-party trade agreements with line items cannot be grouped. Nondominium's multi-resource governance commitments may require this.

Implementation path: Add ReaAgreementBundle entry type; add bundled_in: Option<ActionHash> to ReaAgreement.

5. vf:ProposalList (P2)

VF 1.0 definition: "Grouping of proposals for publishing."

Current hREA state: No equivalent. ReaProposal has no listed_in field.

Impact: Marketplace-style proposal catalogues (e.g., hAppenings Requests & Offers grouped by category) cannot be expressed at the VF ontology level.

Implementation path: Add ReaProposalList entry type; add listed_in: Option<ActionHash> to ReaProposal.

Field-Level Gaps by Entity

vf:EconomicEvent / ReaEconomicEvent

Gaps: effortQuantity (P0), reciprocalRealizationOf (P1), settles (blocked by Claim). Extra hREA field: agreed_in: Option<String> — not in VF 1.0 ontology.

vf:EconomicResource / ReaEconomicResource

Extra hREA fields: name, image, note — supplementary, not in VF core ontology.

vf:Commitment / ReaCommitment

Gap: reciprocalClauseOf (P1).

vf:Agent / ReaAgent

Extra hREA fields: name (required), image, classified_as, note.

Structural observation: VF 1.0 defines Agent as an abstract class with three concrete subclasses. hREA uses a single ReaAgent with agent_type: String (e.g., "Person", "Organization"). This is pragmatic for Holochain (avoids three entry types with near-identical structure), but breaks strict ontology alignment. A VF-compliant GraphQL layer must map these correctly.

vf:ResourceSpecification / ReaResourceSpecification

Impact: Currency tokens and fungibility cannot be expressed. Nondominium's Unyt integration (§6.6 in NDO spec) depends on mediumOfExchange.

vf:Intent / ReaIntent

Intent is one of the more complete implementations. Extra hREA fields: image, agreed_in, in_scope_of.

vf:Proposal / ReaProposal

Extra hREA fields: name, has_beginning, has_end, created, note.

vf:Agreement / ReaAgreement

hREA ReaAgreement has only name, created, note. Agreement is severely under-specified relative to VF 1.0. Bilateral exchange workflows (standard in OVN contexts) cannot be fully expressed.

vf:Plan / ReaPlan

Plan is relatively well-implemented. Extra hREA fields: name, due, note, in_scope_of, created.

vf:Process / ReaProcess

Process is well-implemented. Extra hREA fields: before, after, classified_as, planned_within, note.

vf:RecipeProcess / ReaRecipeProcess

vf:Unit / ReaUnit

Extra hREA field: label (human-readable name) — not in VF core but harmless.

Action Model Gaps

VF 1.0 defines the vf:Action class with 10 effect properties. hREA implements 4.

Impact: The missing action effects mean that rule-based resource mutation (auto-updating location, stage, state, containment when an event is recorded) cannot be derived from the action definition alone. Systems consuming hREA must hardcode these rules outside the action model.

This is particularly impactful for transfer_custody (no locationEffect to auto-update current_location) and modify/accept (no stageEffect or stateEffect).

Validation Gaps

Every integrity zome validation function in vendor/hrea that should enforce VF business rules is a stub:

#![allow(unused)]
fn main() {
// TODO: add the appropriate validation rules
Ok(ValidateCallbackResult::Valid)
}

This affects all entry types for create, update, and delete operations.

Specific rules that are absent at the DHT validation level:

Architectural note: Holochain's validation layer (integrity zome) is the correct place for these rules because validation runs deterministically on every peer. Leaving these as stubs means: (a) corrupted state can be written to the DHT by non-compliant clients, and (b) hREA cannot claim DHT-level VF correctness guarantees.

Naming and Structural Observations

These are not gaps but noteworthy observations for maintainers.

rea_ prefix vs vf: namespace. All hREA types use a ReaX / rea_x naming convention. This is internal to the Holochain zome layer and is correctly abstracted away by the GraphQL module. The GraphQL types should map to VF names (EconomicEvent, not ReaEconomicEvent). Verify this mapping is complete in modules/vf-graphql-holochain/.

agreed_in: Option<String> on EconomicEvent and Commitment. This field does not appear in the VF 1.0 ontology. It appears to be a legacy field or a custom extension. Its semantics overlap with realization_of (Agreement). Clarify intent and either map it to a proper VF property or document it as an hREA extension.

Proposal embeds publishes and reciprocal inline. VF 1.0 expresses these as relationships via ProposedIntent (vf:publishedIn). hREA stores them as Vec<ActionHash> directly on Proposal. This is a denormalized approach that works but diverges from the VF graph model. ProposedIntent as a separate entity is missing.

RecipeExchange vs Recipe. VF 1.0 defines a vf:Recipe class (with recipeIncludes and primaryOutput) distinct from vf:RecipeExchange. hREA's ReaRecipeExchange maps to VF's RecipeExchange but there is no equivalent of VF's Recipe wrapper class in hREA. If recipes need a primary output specification, this wrapper is needed.

Recommendations

P0 — Critical (breaks core VF workflows)

P0-1: Add vf:Claim entry type

• Create integrity/hrea/src/rea_claim.rs with triggeredBy: ActionHash (required) and standard CRUD
• Add settles: Option<Vec<ActionHash>> to ReaEconomicEvent
• Add coordinator functions: create_rea_claim, get_latest_rea_claim, get_claims_triggered_by_event
• Required for: contribution accounting in Nondominium, invoicing workflows in hAppenings

P0-2: Add effortQuantity to ReaEconomicEvent

• Add effort_quantity: Option<QuantityValue> to the ReaEconomicEvent struct
• Required for: all work and deliverService action events, which are the primary use case in OVN contribution tracking

P1 — Important (breaks interoperability with other VF systems)

P1-1: Add reciprocalRealizationOf to ReaEconomicEvent

• Add reciprocal_realization_of: Option<ActionHash> referencing a ReaAgreement
• Required for: bilateral exchange event recording (standard trade)

P1-2: Add reciprocalClauseOf to ReaCommitment

• Add reciprocal_clause_of: Option<ActionHash> referencing a ReaAgreement
• Required for: bilateral agreement clauses (the "I commit to X in exchange for Y" pattern)

P1-3: Add mediumOfExchange and substitutable to ReaResourceSpecification

• Add medium_of_exchange: Option<bool> and substitutable: Option<bool>
• Required for: Nondominium Unyt integration (§6.6 NDO spec) and hAppenings fungible offer matching

P1-4: Implement core validation rules in integrity zome

• At minimum: action input/output constraint validation on ReaEconomicEvent creation
• Temporal constraint: has_beginning < has_end where both present
• The validate_create_rea_economic_event already validates foreign keys — extend it with action-based process link validation using get_builtin_action()

P1-5: Add purpose to ReaProposal

• Add purpose: Option<String> (using a string enum: "offer" / "request") or a proper ProposalPurpose entry type
• Required for: hAppenings Requests & Offers UI distinction between offers and requests

P2 — Significant (completes the ontology)

P2-1: Add vf:SpatialThing entry type and replace string location fields

• Create ReaSpatialThing with mappable_address, lat, lon, alt fields
• Replace at_location: Option<String> with at_location: Option<ActionHash> everywhere
• This is a breaking change — requires migration logic or a versioned approach

P2-2: Add vf:BatchLotRecord entry type

• Create ReaBatchLotRecord with batch_lot_code: String, expiration_date: Option<Timestamp>
• Replace lot: Option<String> on ReaEconomicResource with of_batch_lot: Option<ActionHash>

P2-3: Add missing Action effect fields

• Add location_effect, stage_effect, state_effect, contained_effect, create_resource, event_quantity to the Action struct
• Update builtins.rs with values from VF 1.0 spec for each action
• This enables rule-based resource mutation derivation from action definitions

P2-4: Add hasDuration and processClassifiedAs to ReaRecipeProcess

• Add has_duration: Option<QuantityValue> (time measure) and process_classified_as: Option<Vec<String>>

P2-5: Add vf:AgreementBundle and expand ReaAgreement

• Create ReaAgreementBundle entry type
• Add bundled_in: Option<ActionHash> to ReaAgreement

P2-6: Add primaryLocation to ReaAgent

• Add primary_location: Option<ActionHash> (or Option<String> if SpatialThing not yet implemented)

Appendix: Full Field Mapping Tables

Actions — 18 built-in actions present

All 18 VF 1.0 built-in actions are present. Action effect dimensions are missing (see Action Model Gaps above).

Entry Types — Presence Summary

Link Types — 30 relationship links defined

hREA defines 56 link types in the integrity zome covering: update chains (immutable), discovery anchors (AllX), process I/O links, agent-to-flow links, planning links (agreement/plan/commitment), satisfaction/fulfillment links, and recipe structure links. These are implementation-level constructs; VF 1.0 expresses these as object properties on the classes. No significant link-level gaps were identified beyond those caused by missing entry types.