Holon Data Loader

[evomimic]

Holon Data Loader Design Specification

---

Summary

The Holon Data Loader will convert holon data presented in JSON files into Holons and HolonRelationships that are staged and committed to a (single) MAP Space using existing MAP APIs. Because all MAP types (e.g., PropertyType, HolonType, RelationshipType) are themselves holons, the Holon Data Loader can be used to load TypeDescriptors just like any other data — eliminating the need for a separate type-specific loader. Input files are syntactically validated against a JSON Schema to ensure they represent well-formed holons, properties, relationships and, eventually, dances.

Validation of imported and holons and their properties and relationships against their Type Descriptors is triggered by standard Holochain validation callbacks. These callback functions, implemented in the holons_integrity_zome invoke shared validation functions to actually perform the validations. All Holochain dependencies are isolated in the integrity zome so that the shared validation functions have no holochain dependencies.

If the target space does not already contain all required TypeDescriptors (e.g., BookType, title, HAS_AUTHOR), they must be included as part of the import and loaded first. Since we do not yet have deployed instances of the MAP that persist data, all types and data required for an integration Test Case must be loaded as part of the test case itself. This includes importing the MAP Schema. Thus, the test case initialization includes the following steps:

1. Import MAP Meta-Schema
2. Import MAP Core Schema
3. Import Domain-Specific Type Descriptors (if any)
4. Import Domain-Specific Data (if any)

All four test steps use the same Holon Data Loader. Each step imports the type descriptors needed to validate the data imported in the subsequent step.

🧠 Design Principles

• Holonic Uniformity: Everything is a holon, including types
• Two-Pass Resolution: Prevents ordering complexity and circular errors
• Flexible Referencing: Supports structured and shorthand references
• Descriptor Integrity: TypeDescriptors must conform to Meta-Descriptors
• Import Scope: One import targets one HolonSpace; external references are supported via proxy

---

🔗 Expressing Holon Relationships Using $ref

In MAP’s JSON import format, every relationship target must be expressed using the $ref field — a concise, string-based shorthand that captures the essential reference semantics in a human-friendly format.

The $ref mechanism is the only supported way to reference other holons in the import format. Internally, the loader expands $ref values into the appropriate reference type (HolonId, temp_key, or ExternalId) for resolution.

---

🧠 Motivation: The Reference Cases We Must Support

Relationship targets may fall into one of several categories:

1. Local vs. External: The target holon may be in the same HolonSpace or a different one.
2. Saved vs. Staged: The target holon may already exist in the DHT or be included in the same import file.
3. Keyed vs. Unkeyed: If the holon has a declared key, it may be referenced by type:key. Otherwise, it must be assigned a temp_key for intra-import referencing.

The $ref string format is designed to compactly express all of these cases using a small set of idiomatic prefixes.

---

✅ Supported $ref Formats

$ref Format	Meaning	Example
"#key"	Local, staged or saved holon referenced by key	"#Emerging World"
"#Type:Key"	Local saved holon by HolonType and key	"BookType:future-primal"
"id:<HolonId>"	Local saved holon by ActionHash (HolonId)	"id:uhCAkYmv..."
"@ProxyName:Type:Key"	External holon by proxy name + type + key	"@Library:ArticleType:climate-effects"
"ext:<ProxyId>:<LocalId>"	External holon by proxy ID and local ID	"ext:uhCAkProxy...:uhCAkLocal..."

---

🔍 $ref Parsing Rules

Prefix	Interpreted As
#	Local staged holon via temp_key
id:	Local saved holon by ActionHash
ext:	External holon via OutboundProxyId and LocalId
@	External holon via proxy name, type, and key
(default)	Local saved holon via Type:Key

The loader must interpret each $ref string according to these rules and resolve the reference accordingly.

---

📘 Example Usage

{
  "type_name": "BookType",
  "temp_key": "book-001",
  "properties": {
    "title": { "type": "MapString", "value": "Future Primal" }
  },
  "relationships": [
    {
      "name": "AUTHORED_BY",
      "target": { "$ref": "PersonType:charles-eisenstein" }
    },
    {
      "name": "MENTORED_BY",
      "target": { "$ref": "#mentor-temp-001" }
    },
    {
      "name": "CITED_IN",
      "target": { "$ref": "@ResearchLibrary:ArticleType:climate-effects-2024" }
    }
  ]
}

---

🧩 Process Overview

The following diagram shows the Holon Data Loading process.

🧭 Step-by-Step: MAP Holon Data Loader Flow

A: AirTable -> JSON Import Files

The following steps have an "A" prefix in the diagram.

1. Define Holons in Airtable -- For now, we are using Airtable as our source of truth for data imports. A user or domain expert defines holons, properties, and relationships as rows in a spreadsheet-like interface. NOTE: This is just one option — other JSON generation methods are possible.

2. Export CSV from Airtable -- Airtable exports the holon definitions into a CSV file, which contains structured tabular data for each holon, including properties, types, and relationships.

3. Convert CSV to JSON -- A Jupyter Notebook (written in Python) loads the CSV file and uses the MAP Holon JSON Generator to transform the rows into JSON-formatted Holon Definitions. These definitions conform to the MAP Holon Data Loader's expected schema.

C: JsonHolonLoaderClient

This is realized as TypeScript code within a HolonsClient Tauri container. The following steps have a "C" prefix in the diagram.

1. HolonLoader CLI -- this component provides the command-line interface for loading a bundle of holons from a set of JSON import files. See Holon Loader Man Page for details on the CLI command definition.

2 Run the JSON Schema Validator -- Before loading, the JSON input files are validated using a JSON Schema Validator. This ensures that the file:

• Is structurally valid
• Uses valid type names and relationship formats

The validated file represents well-formed Holons, Properties, and Relationships.

3. Parse and Prepare Holons -- The validated JSON is parsed into a Transient HolonLoaderBundle that contains Transient LoaderHolons as BUNDLE_MEMBERS. More precisely:

   • Upon parsing the "meta" section, use the lightweight Typescript Dance Call Service to:
     • create an empty transient HolonLoaderBundle holon via create_empty_transient_holon dance (C4/C5)
     • use with_property dances to add properties about the load as a hole (C4/C5)
   • For each holon in the holons array:
     • create LoaderHolon via create_empty_transient_holon dance (C4/C5)
     • populate its properties via with_properties dance (treat "key" as a property and add it also) (C4/C5)
     • for each of its DeclaredRelationships
       • create and populate a transient LoaderHolonReference holon for each of its targets (C4/C5)
       • create and populate a transient LoaderRelationshipReference holon (C4/C5)
       • use add_related_holons dance to add the LoaderRelationshipReference to the LoaderHolon (C4/C5)
       • handle the "type" shorthand by converting it into a declared "DescribedBy" relationship (C4/C5)
   4. Note that each of dance requests is shown as C4 in the diagram. It is issue asynchronously to the TypeScript Dance Call Service which issues a dance request across the typescript/rust boundary in the Tauri container. All of these lightweight dance requests are handled locally in the Rust Holons Client's TransientHolonManager.
   5. Results are returned to the TypeScript container via C5.

   The above process is repeated until all input files have been parsed.

4. Invoke the Holon Data Loader -- Once all parsing is complete, the TypeScript Loader Controller issues a load dance request to the Dance Caller.

5. Delegate Dance Call to Guest -- The load dance is forwarded to the Guest via the Rust Clients' Dance Call Service. This is a heavier-weight protocol that ships session_state (StagedHolons and TransientHolons) to the Guest as part of the Dance Request.

6. Handle Dance Response -- the response includes session_state used to "re-inflate" the Guests Nursery and TransientHolonManager

7. The Rust client then issues an async response back to the JsonHolonLoaderClient indicating the status of the load request. Note that session_state is NOT included in this response. Details on the load dance response remain in the Rust Client's TransientHolonManager.

D: Guest-Side Dancing

1. The load dance request (with session_state) is receive by the Guest Dancer. Session state is used to initialize a Guest Context that includes a Nursery inflated from the StagedHolons in the session_state and a TransientHolonManager inflated from the TransientHolons in the session_state.
2. The Dancer dispatches the dance request to the Holon Dance Adapter's load_holons function.
3. The adapter then delegates the actual loading to the native functionality provided by the HolonLoader module's LoaderController.

G: Guest-Side Holon Loader Processing

The Holon Loader Controller choreographs the loading process in three phases.
Phase 1: Stage Holons and Queue LoadRelationshipReferences
Phase 2: Resolve and Stage Relationships
Phase 3: Commit

1. Map LoaderHolons to Holons -- In Phase 1, the LoaderController passes LoaderHolons to the import_mapper.
2. Stage Holons -- The import_mapper uses information pulled from LoaderHolons to stage and populate the properties of the actual holons to load. LoaderRelationshipReferences are queued for processing in Phase 2. Note that staging requests are delegate by the Reference Layer to the Shared Objects Layer's Nursery.
3. Phase 2 -- In Phase 2, the loader's reference_resolver resolves HolonReferences (and the LoaderRelationshipReferences that depend on them).
4. Resolve LoaderHolonReferences -- Note that resolving Holon references requires requests to the reference layer which delegates to the Nursery (to resolve references to StagedHolons) or the HolonsCache (to resolve references to SavedHolons). If the latter are found in the Cache, the saved holon is fetched from the Persistence Layer (such requests are not numbered in the diagram).
5. Stage Relationships -- Once the LoaderHolonReferences have been resolved to HolonReferences, add_related_holons calls on references to the holons staged in Phase 1 can populate their Declared Relationships.
6. Commit -- Once all LoaderRelationshipReferences have been resolved, if no errors were encountered the loader_controller issues a commit request to the reference layer.
7. Persist to DHT -- This request is delegated to the persistence layer which, itself, initiates a 4-stage commit process. (1) Write Holon Nodes, (2) Write SmartLinks for Relationships, (3) Validation, (4) Finalize. These steps are described elsewhere and not depicted in the diagram.
8. Results -- The loader_controller returns a Result<TransientReference, HolonError>. On success, the TransientReference points to a HolonLoadResponse (DanceResponseType) populated with ResponseStatusCode, HolonsStaged, HolonsCommitted, ErrorCount, and optional DanceSummary, with any per-item errors attached as HAS_LOAD_ERROR → HolonError. System-level failures use the Err(HolonError) path.

V: Validation

1. Trigger Validation -- As part of the commit, the Holochain Conductor invokes validation actions. These hit the HolonNode Validation Hooks in the holons_integrity_zome. The implementation of these hook functions converts the data into "holochain-independent" data structures in order to invoke the shared validation functions.

2. Run Shared Validation Logic The hooks delegate to the Shared Holons Validator, which contains:

• Validation against TypeDescriptors
• Enforcement of required properties and cardinalities
• No direct Holochain dependencies — enabling reuse of these validations from holons_core without pulling in holochain and its dependencies.

---

🧪 Validation and Error Handling

• Each $ref must resolve to a valid holon by the end of Pass 2 (after all staged holons are registered).
• If the referenced holon has no declared key, it must be assigned a temp_key and referenced via "#temp-key".
• External references must correspond to valid space proxy entries in the local HolonSpace — either by name or by ID.

---

✅ Validation Strategy

The diagram shows validation via Integrity Zome validation hooks. However, we have determined that only a very limited form of validation is possible here. The proper validation architecture is broader than just Holon Loader Validation and it is being addressed elsewhere.

---

🔮 Future Enhancements

• JSON Schema for validating HolonImportSpec and $ref strings
• Streaming import and partial updates
• Reference diagnostic logs
• Preview mode for validating without committing
• Support for symbolic cross-space lookups via Dance requests

[owleyeview]

As discussed in a July 7 meeting:
JSON Holon Spec Generator is a better name for the JSON Holon Loader.
JSON Holon Spec Generator is more accurate and avoids confusion with the Holon Data Loader.

[evomimic]

Revised Holon Loader Design

If we assume tauri/Conductora client architecture we have ability to leverage the Nursery and Transient Holon Manager on the client-side via a (new) Conductora Dance interface. This interface essentially wraps the holons_core api in lightweight dances.

Let's say JSON Parser maps JSON to Transient Holons that are created through Conductora Dances (whose dancer is client-side). Three Holon Types: LoaderHolon, LoaderHolonReference, LoaderRelationshipReference (described below). It feeds these types to the Rust LoaderController (in Tauri client) that uses the ImportMapper to transform TransientReferences to LoaderHolons into Staged References to staged "real" Holons, while queuing LoaderHolonReferences and LoaderRelationshipReferences for later resolution. Once EOF is reached on the last "loads_with" file, client gives "load" signal.

LoaderController then iterates through its queue of LoaderRelationshipReferences, uses holon_resolver to get HolonReference for each Source and Target Holon. Once all relationships resolved (assuming no errors that would cause abort), LoaderController uses standard "commit" dance that is forwarded by Conductora to holons_guest for persisting in the DHT.

The Loader types and LoaderController have only holons_core dependencies, so they can run in either client or guest. Since resolution of references to saved holons could be to either local or external holon's, it's probably best that reference resolution happens on the guest-side. Staging of mapped LoaderHolons can still happen on the client-side, but the "resolve" phase is a dance request to the guest that leverages the ping-pong of session state from client to guest (this includes both StagedHolons in Nursery and Transient Holons representing References to be resolved).

Loader Schema

The parsed JSON input is represented as Holons and Holon Relationships described by the types that are components of the HolonLoaderSchema. The JSON definition of these types is included as independently maintained comments on this Discussion.

This schema defines three HolonTypes:

• LoaderHolon -- the parsed representation of a Holon
• LoaderRelationshipReference -- the parsed representation of an (unresolved) relationship
• LoaderHolonReference -- the parsed representation of a reference to a Holon (e.g., via its key, id,

✅ Updated Loader Architecture Overview

Client (Tauri App)

• Responsibility: JSON parsing, transient holon creation, initial mapping
• Uses:
  • Conductora dances for CreateTransientHolon, with_properties, add_related_holons (to tie LoaderRelationshipReferences to LoaderHolonReferences).
  • Maintains Nursery of StagedHolons and TransientReferences
• Actions:
  • Parses JSON into LoaderHolon, LoaderHolonReference, and LoaderRelationshipReference (all Transient Holons)
  • Runs ImportMapper to map LoaderHolon → StagedHolon (only property-level)
  • Sends ResolveLoaderReferences dance to guest, including:
    • All staged StagedHolons from the Nursery
    • All transient Loader*Reference holons (for reference resolution)

---

Guest (holons_guest)

• Responsibility: Resolves references and commits holons
• Uses:
  • HolonResolver: Resolves each LoaderHolonReference to actual HolonReference
  • LoaderController: Connects resolved references into complete holon relationships
  • HolonCommitService: Commits completed holons to the DHT
• Triggered by:
  • ResolveLoaderReferences dance
• Actions:
  • Validates and resolves all source/target references
  • Converts queued LoaderRelationshipReferences into fully linked relationships
  • On success: returns a LoaderResponse summary
  • On failure: returns LoaderError holons identifying issues (e.g., unresolved reference)

---

💡 Why This Works Well

Concern	Handled On	Reason
JSON Parsing	Client	Leverages native JSON tooling, keeps guest-side lean
Holon Construction (property map)	Client	No external dependencies; uses holons_core
Holon Reference Resolution	Guest	Needs access to DHT + local/foreign resolution logic
Final Relationship Wiring	Guest	Requires resolved HolonReferences
Commit to DHT	Guest	Requires access to holochain commit logic (holons_guest)
Session State Transfer	Client → Guest	Uses Conductora to ping-pong session state and transient holons

---

🔁 Reference Resolution Dance

The ResolveLoaderReferences dance:

• Initiated by the client after receiving eof = true
• Runs guest-side LoaderController
• Accepts:
  • Transient LoaderHolonReference and LoaderRelationshipReference holons
  • All StagedHolons currently held in the Nursery
• Guest:
  • Resolves references (both local and foreign)
  • Connects all declared/inverse relationships
  • Validates everything
  • Commits all valid holons
  • Returns a structured LoaderResponse with status and errors (if any)

[owleyeview]

Per our conversation this morning:
We won't be mapping transient LoaderHolon's to Staged "real" holons on the client side.
The client will handle parsing of the JSON into loader types and pass those to the guest for mapping and relationship reference resolution.

[evomimic]

Loader Property Types

{
  "meta": {
    "description": "Supporting Property and Relationship Types used by the LoaderHolon architecture.",
    "generator": "Holon Loader Architecture — September 2025"
  },
  "holons": [
    {
      "key": "Key.Property",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "Key",
        "type_name_plural": "Keys",
        "display_name": "key",
        "display_name_plural": "keys",
        "description": "Optional key to identify the holon instance within the import set.",
        "instance_type_kind": "Property",
        "is_abstract_type": false
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#PropertyType" } },
        { "name": "ValueType", "target": { "$ref": "#MapStringValueType" } }
      ]
    },
    {
      "key": "RelationshipName.Property",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "RelationshipName",
        "type_name_plural": "RelationshipNames",
        "display_name": "relationship_name",
        "display_name_plural": "relationship_names",
        "description": "Name of the relationship as declared in the JSON input.",
        "instance_type_kind": "Property",
        "is_abstract_type": false
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#PropertyType" } },
        { "name": "ValueType", "target": { "$ref": "#MapStringValueType" } }
      ]
    },
    {
      "key": "IsDeclared.Property",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "IsDeclared",
        "type_name_plural": "IsDeclaredFlags",
        "display_name": "is_declared",
        "display_name_plural": "is_declared_flags",
        "description": "Whether the relationship is declared (`true`) or inverse (`false`).",
        "instance_type_kind": "Property",
        "is_abstract_type": false
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#PropertyType" } },
        { "name": "ValueType", "target": { "$ref": "#MapBooleanValueType" } }
      ]
    },
    {
      "key": "HolonKey.Property",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HolonKey",
        "type_name_plural": "HolonKeys",
        "display_name": "holon_key",
        "display_name_plural": "holon_keys",
        "description": "Local key for the referenced holon.",
        "instance_type_kind": "Property",
        "is_abstract_type": false
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#PropertyType" } },
        { "name": "ValueType", "target": { "$ref": "#MapStringValueType" } }
      ]
    },
    {
      "key": "HolonId.Property",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HolonId",
        "type_name_plural": "HolonIds",
        "display_name": "holon_id",
        "display_name_plural": "holon_ids",
        "description": "ActionHash identifier of a referenced holon.",
        "instance_type_kind": "Property",
        "is_abstract_type": false
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#PropertyType" } },
        { "name": "ValueType", "target": { "$ref": "#MapIdValueType" } }
      ]
    },
    {
      "key": "ProxyKey.Property",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "ProxyKey",
        "type_name_plural": "ProxyKeys",
        "display_name": "proxy_key",
        "display_name_plural": "proxy_keys",
        "description": "Key of the ProxySpace through which this external reference is routed.",
        "instance_type_kind": "Property",
        "is_abstract_type": false
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#PropertyType" } },
        { "name": "ValueType", "target": { "$ref": "#MapStringValueType" } }
      ]
    },
    {
      "key": "ProxyId.Property",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "ProxyId",
        "type_name_plural": "ProxyIds",
        "display_name": "proxy_id",
        "display_name_plural": "proxy_ids",
        "description": "ActionHash of the ProxySpace holon, used to route external references.",
        "instance_type_kind": "Property",
        "is_abstract_type": false
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#PropertyType" } },
        { "name": "ValueType", "target": { "$ref": "#MapIdValueType" } }
      ]
    }
  ]
}

[evomimic]

Loader Relationship Types

[
  {
    "key": "HasRelationshipReference.RelationshipType",
    "type": "#TypeDescriptor",
    "properties": {
      "type_name": "HasRelationshipReference",
      "type_name_plural": "HasRelationshipReferences",
      "display_name": "has relationship reference",
      "display_name_plural": "has relationship references",
      "description": "Declared relationship from a LoaderHolon to each unresolved relationship reference it contains.",
      "instance_type_kind": "Relationship",
      "deletion_semantic": "Allow",
      "is_definitional": false,
      "is_ordered": true,
      "allows_duplicates": false,
      "min_cardinality": 0,
      "max_cardinality": 32767
    },
    "relationships": [
      { "name": "Extends", "target": { "$ref": "#DeclaredRelationshipType" } },
      { "name": "SourceType", "target": { "$ref": "#LoaderHolon.Type" } },
      { "name": "TargetType", "target": { "$ref": "#LoaderRelationshipReference.Type" } }
    ]
  },
  {
    "key": "IsRelationshipReferenceOf.RelationshipType",
    "type": "#TypeDescriptor",
    "properties": {
      "type_name": "IsRelationshipReferenceOf",
      "type_name_plural": "IsRelationshipReferenceOfs",
      "display_name": "is relationship reference of",
      "display_name_plural": "is relationship references of",
      "description": "Inverse of HasRelationshipReference. Points from LoaderRelationshipReference back to the originating LoaderHolon.",
      "instance_type_kind": "Relationship",
      "deletion_semantic": "Allow",
      "is_definitional": false,
      "is_ordered": false,
      "allows_duplicates": false,
      "min_cardinality": 0,
      "max_cardinality": 1
    },
    "relationships": [
      { "name": "Extends", "target": { "$ref": "#InverseRelationshipType" } },
      { "name": "SourceType", "target": { "$ref": "#LoaderRelationshipReference.Type" } },
      { "name": "TargetType", "target": { "$ref": "#LoaderHolon.Type" } },
      { "name": "InverseOf", "target": { "$ref": "#HasRelationshipReference.RelationshipType" } }
    ]
  },
  {
    "key": "ReferenceSource.RelationshipType",
    "type": "#TypeDescriptor",
    "properties": {
      "type_name": "ReferenceSource",
      "type_name_plural": "ReferenceSources",
      "display_name": "reference source",
      "display_name_plural": "reference sources",
      "description": "Declared relationship from a LoaderRelationshipReference to the holon that acts as the relationship source.",
      "instance_type_kind": "Relationship",
      "deletion_semantic": "Allow",
      "is_definitional": true,
      "is_ordered": false,
      "allows_duplicates": false,
      "min_cardinality": 1,
      "max_cardinality": 1
    },
    "relationships": [
      { "name": "Extends", "target": { "$ref": "#DeclaredRelationshipType" } },
      { "name": "SourceType", "target": { "$ref": "#LoaderRelationshipReference.Type" } },
      { "name": "TargetType", "target": { "$ref": "#LoaderHolonReference.Type" } }
    ]
  },
  {
    "key": "IsReferenceSourceOf.RelationshipType",
    "type": "#TypeDescriptor",
    "properties": {
      "type_name": "IsReferenceSourceOf",
      "type_name_plural": "IsReferenceSourceOfs",
      "display_name": "is reference source of",
      "display_name_plural": "is reference sources of",
      "description": "Inverse of ReferenceSource. Points from LoaderHolonReference to the LoaderRelationshipReference where it acts as the source.",
      "instance_type_kind": "Relationship",
      "deletion_semantic": "Allow",
      "is_definitional": true,
      "is_ordered": false,
      "allows_duplicates": false,
      "min_cardinality": 0,
      "max_cardinality": 32767
    },
    "relationships": [
      { "name": "Extends", "target": { "$ref": "#InverseRelationshipType" } },
      { "name": "SourceType", "target": { "$ref": "#LoaderHolonReference.Type" } },
      { "name": "TargetType", "target": { "$ref": "#LoaderRelationshipReference.Type" } },
      { "name": "InverseOf", "target": { "$ref": "#ReferenceSource.RelationshipType" } }
    ]
  },
  {
    "key": "ReferenceTarget.RelationshipType",
    "type": "#TypeDescriptor",
    "properties": {
      "type_name": "ReferenceTarget",
      "type_name_plural": "ReferenceTargets",
      "display_name": "reference target",
      "display_name_plural": "reference targets",
      "description": "Declared relationship from a LoaderRelationshipReference to the holons that act as relationship targets.",
      "instance_type_kind": "Relationship",
      "deletion_semantic": "Allow",
      "is_definitional": true,
      "is_ordered": true,
      "allows_duplicates": false,
      "min_cardinality": 1,
      "max_cardinality": 32767
    },
    "relationships": [
      { "name": "Extends", "target": { "$ref": "#DeclaredRelationshipType" } },
      { "name": "SourceType", "target": { "$ref": "#LoaderRelationshipReference.Type" } },
      { "name": "TargetType", "target": { "$ref": "#LoaderHolonReference.Type" } }
    ]
  },
  {
    "key": "IsReferenceTargetOf.RelationshipType",
    "type": "#TypeDescriptor",
    "properties": {
      "type_name": "IsReferenceTargetOf",
      "type_name_plural": "IsReferenceTargetOfs",
      "display_name": "is reference target of",
      "display_name_plural": "is reference targets of",
      "description": "Inverse of ReferenceTarget. Points from LoaderHolonReference to the LoaderRelationshipReference where it acts as a target.",
      "instance_type_kind": "Relationship",
      "deletion_semantic": "Cascade",
      "is_definitional": true,
      "is_ordered": false,
      "allows_duplicates": false,
      "min_cardinality": 0,
      "max_cardinality": 32767
    },
    "relationships": [
      { "name": "Extends", "target": { "$ref": "#InverseRelationshipType" } },
      { "name": "SourceType", "target": { "$ref": "#LoaderHolonReference.Type" } },
      { "name": "TargetType", "target": { "$ref": "#LoaderRelationshipReference.Type" } },
      { "name": "InverseOf", "target": { "$ref": "#ReferenceTarget.RelationshipType" } }
    ]
  }
]

[evomimic]

Loader Holon Types

{
  "meta": {
    "description": "Core Holon Loader Types used for transient parsing and reference resolution in the MAP Holon Data Loader pipeline.",
    "generator": "Holon Loader Architecture — September 2025"
  },
  "holons": [
    {
      "key": "LoaderHolon.Type",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "LoaderHolon",
        "type_name_plural": "LoaderHolons",
        "display_name": "Loader Holon",
        "display_name_plural": "Loader Holons",
        "description": "Representation of a parsed holon from JSON input, including properties and unresolved references.",
        "instance_type_kind": "Holon",
        "is_abstract_type": false,
        "additional_properties": true,
        "additional_relationships": true
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#HolonType" } },
        { "name": "InstanceProperties", "target": { "$ref": "#Key.Property" } },
        { "name": "DeclaredRelationships", "target": { "$ref": "#HasLoaderRelationshipReference.RelationshipType" } }
      ]
    },

    {
      "key": "LoaderRelationshipReference.Type",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "LoaderRelationshipReference",
        "type_name_plural": "LoaderRelationshipReferences",
        "display_name": "Loader Relationship Reference",
        "display_name_plural": "Loader Relationship References",
        "description": "Represents an unresolved relationship reference from a LoaderHolon, including source/target references.",
        "instance_type_kind": "Holon",
        "is_abstract_type": false,
        "additional_properties": false,
        "additional_relationships": false
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#HolonType" } },
        { "name": "InstanceProperties", "target": { "$ref": "#RelationshipName.Property" } },
        { "name": "InstanceProperties", "target": { "$ref": "#IsDeclared.Property" } },
        { "name": "DeclaredRelationships", "target": { "$ref": "#LoaderSource.RelationshipType" } },
        { "name": "DeclaredRelationships", "target": { "$ref": "#LoaderTarget.RelationshipType" } }
      ]
    },

    {
      "key": "LoaderHolonReference.Type",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "LoaderHolonReference",
        "type_name_plural": "LoaderHolonReferences",
        "display_name": "Loader Holon Reference",
        "display_name_plural": "Loader Holon References",
        "description": "Represents an unresolved reference to a holon, either local (by key or ID) or external (via proxy + key/ID).",
        "instance_type_kind": "Holon",
        "is_abstract_type": false,
        "additional_properties": false,
        "additional_relationships": false
      },
      "relationships": [
        { "name": "Extends", "target": { "$ref": "#HolonType" } },
        { "name": "InstanceProperties", "target": { "$ref": "#HolonKey.Property" } },
        { "name": "InstanceProperties", "target": { "$ref": "#HolonId.Property" } },
        { "name": "InstanceProperties", "target": { "$ref": "#ProxyKey.Property" } },
        { "name": "InstanceProperties", "target": { "$ref": "#ProxyId.Property" } },
        { "name": "DeclaredRelationships", "target": { "$ref": "#EmbeddedHolon.RelationshipType" } }
      ]
    }
  ]
}

[owleyeview]

I noticed that ProxyId and HolonId properties above use a MapIdValueType that we have not yet defined. I'm setting the value type to MapBytesValueType for the first refinement of the loader types but we might want to implement a MapIdValueType as an extension of MapBytesValueType with added constraints. Here's a suggested definition from Chat-GPT:

{
  "key": "MapIdValueType",
  "type": "#TypeDescriptor",
  "properties": {
    "type_name": "MapIdValueType",
    "type_name_plural": "MapIdValueTypes",
    "display_name": "MAP ID (39 bytes)",
    "display_name_plural": "MAP IDs (39 bytes)",
    "description": "A 39-byte identifier (e.g., Holochain ActionHash/AgentPubKey raw form). Carries bytes, not text.",
    "instance_type_kind": "Value"
  },
  "relationships": [
    { "name": "Extends", "target": { "$ref": "#MapBytesValueType" } },
    { "name": "InstanceProperties", "target": [
      { "$ref": "#MinLength.Property" },
      { "$ref": "#MaxLength.Property" },
      { "$ref": "#JsonEncoding.Property" },
      { "$ref": "#FormatHint.Property" },
      { "$ref": "#RegexPattern.Property" }
    ] }
  ]
}

[owleyeview]

Here's the output of these types after being input into our source of truth in Airtable and processed back into JSON:
Edited to add allow_additional_properties and allow_additional_relationships boolean properties

{
  "meta": {
    "generator": "MAP CSV->JSON Notebook (row-wise SchemaType detection)",
    "generated_at": "2025-09-24T13:39:34",
    "export_mode": "by-file",
    "source_files": [
      "MAP Meta-Schema 0.0.3-metaschema-loader-schema.csv"
    ],
    "load_with": []
  },
  "holons": [
    {
      "key": "LoaderHolon.HolonType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "LoaderHolon",
        "type_name_plural": "LoaderHolons",
        "display_name": "Loader Holon",
        "display_name_plural": "Loader Holons",
        "instance_type_kind": "Holon",
        "description": "Representation of a parsed holon from JSON input, including properties and unresolved references.",
        "is_abstract_type": false,
        "allows_additional_properties": true,
        "allows_additional_relationships": true
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#HolonType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "InstanceProperties",
          "target": {
            "$ref": "#Key.PropertyType"
          }
        },
        {
          "name": "InstanceRelationships",
          "target": {
            "$ref": "#(LoaderHolon.HolonType)-[HasRelationshipReference]->(LoaderRelationshipReference.HolonType)"
          }
        }
      ]
    },
    {
      "key": "LoaderRelationshipReference.HolonType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "LoaderRelationshipReference",
        "type_name_plural": "LoaderRelationshipReferences",
        "display_name": "Loader Relationship Reference",
        "display_name_plural": "Loader Relationship References",
        "instance_type_kind": "Holon",
        "description": "Represents an unresolved relationship reference from a LoaderHolon, including source/target references.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#HolonType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "InstanceProperties",
          "target": [
            {
              "$ref": "#RelationshipName.PropertyType"
            },
            {
              "$ref": "#IsDeclared.PropertyType"
            }
          ]
        },
        {
          "name": "InstanceRelationships",
          "target": [
            {
              "$ref": "#(LoaderRelationshipReference.HolonType)-[ReferenceSource]->(LoaderHolonReference.HolonType)"
            },
            {
              "$ref": "#(LoaderRelationshipReference.HolonType)-[ReferenceTarget]->(LoaderHolonReference.HolonType)"
            }
          ]
        }
      ]
    },
    {
      "key": "LoaderHolonReference.HolonType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "LoaderHolonReference",
        "type_name_plural": "LoaderHolonReferences",
        "display_name": "Loader Holon Reference",
        "display_name_plural": "Loader Holon References",
        "instance_type_kind": "Holon",
        "description": "Represents an unresolved reference to a holon, either local (by key or ID) or external (via proxy + key/ID).",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#HolonType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "InstanceProperties",
          "target": [
            {
              "$ref": "#HolonKey.PropertyType"
            },
            {
              "$ref": "#HolonId.PropertyType"
            },
            {
              "$ref": "#ProxyKey.PropertyType"
            },
            {
              "$ref": "#ProxyId.PropertyType"
            }
          ]
        }
      ]
    },
    {
      "key": "HolonLoaderBundle.HolonType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HolonLoaderBundle",
        "type_name_plural": "HolonLoaderBundles",
        "display_name": "HolonLoaderBundle",
        "display_name_plural": "HolonLoaderBundles",
        "instance_type_kind": "Holon",
        "description": "Container holon for a collection of LoaderHolons supplied by the loader client.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#HolonType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "InstanceRelationships",
          "target": {
            "$ref": "#(HolonLoaderBundle.HolonType)-[BundleMembers]->(LoaderHolon.HolonType)"
          }
        }
      ]
    },
    {
      "key": "HolonLoadResponse.DanceResponseType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HolonLoadResponse",
        "type_name_plural": "HolonLoadResponses",
        "display_name": "HolonLoadResponse",
        "display_name_plural": "HolonLoadResponses",
        "instance_type_kind": "Holon",
        "description": "Message-only holon summarizing the outcome of a holon load operation (not persisted by the loader commit).",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#DanceResponseType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "InstanceProperties",
          "target": [
            {
              "$ref": "#ResponseStatusCode.PropertyType"
            },
            {
              "$ref": "#HolonsStaged.PropertyType"
            },
            {
              "$ref": "#HolonsCommitted.PropertyType"
            },
            {
              "$ref": "#ErrorCount.PropertyType"
            },
            {
              "$ref": "#DanceSummary.PropertyType"
            }
          ]
        }
      ]
    },
    {
      "key": "(LoaderHolon.HolonType)-[HasRelationshipReference]->(LoaderRelationshipReference.HolonType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HasRelationshipReference",
        "type_name_plural": "HasRelationshipReferences",
        "display_name": "HasRelationshipReference",
        "display_name_plural": "HasRelationshipReference Relationships",
        "instance_type_kind": "Relationship",
        "description": "Declared relationship from a LoaderHolon to each unresolved relationship reference it contains.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Allow",
        "is_definitional": false,
        "is_ordered": true,
        "allows_duplicates": false,
        "min_cardinality": 0,
        "max_cardinality": 32767
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#DeclaredRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#LoaderHolon.HolonType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#LoaderRelationshipReference.HolonType"
          }
        }
      ]
    },
    {
      "key": "(LoaderRelationshipReference.HolonType)-[RelationshipReferenceOf]->(LoaderHolon.HolonType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "RelationshipReferenceOf",
        "type_name_plural": "RelationshipReferenceOfs",
        "display_name": "RelationshipReferenceOf",
        "display_name_plural": "RelationshipReferenceOf Relationships",
        "instance_type_kind": "Relationship",
        "description": "Inverse of HasRelationshipReference. Points from LoaderRelationshipReference back to the originating LoaderHolon.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Allow",
        "is_definitional": false,
        "is_ordered": false,
        "allows_duplicates": false,
        "min_cardinality": 0,
        "max_cardinality": 1
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#InverseRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "InverseOf",
          "target": {
            "$ref": "#(LoaderHolon.HolonType)-[HasRelationshipReference]->(LoaderRelationshipReference.HolonType)"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#LoaderRelationshipReference.HolonType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#LoaderHolon.HolonType"
          }
        }
      ]
    },
    {
      "key": "(LoaderRelationshipReference.HolonType)-[ReferenceSource]->(LoaderHolonReference.HolonType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "ReferenceSource",
        "type_name_plural": "ReferenceSources",
        "display_name": "ReferenceSource",
        "display_name_plural": "ReferenceSource Relationships",
        "instance_type_kind": "Relationship",
        "description": "Declared relationship from a LoaderRelationshipReference to the holon that acts as the relationship source.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Allow",
        "is_definitional": true,
        "is_ordered": false,
        "allows_duplicates": false,
        "min_cardinality": 1,
        "max_cardinality": 1
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#DeclaredRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#LoaderRelationshipReference.HolonType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#LoaderHolonReference.HolonType"
          }
        }
      ]
    },
    {
      "key": "(LoaderHolonReference.HolonType)-[ReferenceSourceOf]->(LoaderRelationshipReference.HolonType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "ReferenceSourceOf",
        "type_name_plural": "ReferenceSourceOfs",
        "display_name": "ReferenceSourceOf",
        "display_name_plural": "ReferenceSourceOf Relationships",
        "instance_type_kind": "Relationship",
        "description": "Inverse of ReferenceSource. Points from LoaderHolonReference to the LoaderRelationshipReference where it acts as the source.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Allow",
        "is_definitional": false,
        "is_ordered": false,
        "allows_duplicates": false,
        "min_cardinality": 0,
        "max_cardinality": 32767
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#InverseRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "InverseOf",
          "target": {
            "$ref": "#(LoaderRelationshipReference.HolonType)-[ReferenceSource]->(LoaderHolonReference.HolonType)"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#LoaderHolonReference.HolonType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#LoaderRelationshipReference.HolonType"
          }
        }
      ]
    },
    {
      "key": "(LoaderRelationshipReference.HolonType)-[ReferenceTarget]->(LoaderHolonReference.HolonType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "ReferenceTarget",
        "type_name_plural": "ReferenceTargets",
        "display_name": "ReferenceTarget",
        "display_name_plural": "ReferenceTarget Relationships",
        "instance_type_kind": "Relationship",
        "description": "Declared relationship from a LoaderRelationshipReference to the holons that act as relationship targets.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Allow",
        "is_definitional": true,
        "is_ordered": true,
        "allows_duplicates": false,
        "min_cardinality": 1,
        "max_cardinality": 32767
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#DeclaredRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#LoaderRelationshipReference.HolonType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#LoaderHolonReference.HolonType"
          }
        }
      ]
    },
    {
      "key": "(LoaderHolonReference.HolonType)-[ReferenceTargetOf]->(LoaderRelationshipReference.HolonType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "ReferenceTargetOf",
        "type_name_plural": "ReferenceTargetOfs",
        "display_name": "ReferenceTargetOf",
        "display_name_plural": "ReferenceTargetOf Relationships",
        "instance_type_kind": "Relationship",
        "description": "Inverse of ReferenceTarget. Points from LoaderHolonReference to the LoaderRelationshipReference where it acts as a target.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Cascade",
        "is_definitional": false,
        "is_ordered": false,
        "allows_duplicates": false,
        "min_cardinality": 0,
        "max_cardinality": 32767
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#InverseRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "InverseOf",
          "target": {
            "$ref": "#(LoaderRelationshipReference.HolonType)-[ReferenceTarget]->(LoaderHolonReference.HolonType)"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#LoaderHolonReference.HolonType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#LoaderRelationshipReference.HolonType"
          }
        }
      ]
    },
    {
      "key": "(HolonLoaderBundle.HolonType)-[BundleMembers]->(LoaderHolon.HolonType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "BundleMembers",
        "type_name_plural": "BundleMembers",
        "display_name": "BundleMembers",
        "display_name_plural": "BundleMembers Relationships",
        "instance_type_kind": "Relationship",
        "description": "Declared relationship from a HolonLoaderBundle to each LoaderHolon it contains.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Allow",
        "is_definitional": false,
        "is_ordered": false,
        "allows_duplicates": false,
        "min_cardinality": 0,
        "max_cardinality": 32767
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#DeclaredRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#HolonLoaderBundle.HolonType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#LoaderHolon.HolonType"
          }
        }
      ]
    },
    {
      "key": "(LoaderHolon.HolonType)-[BundleMemberOf]->(HolonLoaderBundle.HolonType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "BundleMemberOf",
        "type_name_plural": "BundleMemberOfs",
        "display_name": "BundleMemberOf",
        "display_name_plural": "BundleMemberOf Relationships",
        "instance_type_kind": "Relationship",
        "description": "Inverse of BundleMembers. Points from LoaderHolon back to the containing HolonLoaderBundle.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Allow",
        "is_definitional": false,
        "is_ordered": false,
        "allows_duplicates": false,
        "min_cardinality": 0,
        "max_cardinality": 1
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#InverseRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "InverseOf",
          "target": {
            "$ref": "#(HolonLoaderBundle.HolonType)-[BundleMembers]->(LoaderHolon.HolonType)"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#LoaderHolon.HolonType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#HolonLoaderBundle.HolonType"
          }
        }
      ]
    },
    {
      "key": "(HolonLoadResponse.DanceResponseType)-[HasLoadError]->(HolonErrorType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HasLoadError",
        "type_name_plural": "HasLoadErrors",
        "display_name": "HasLoadError",
        "display_name_plural": "HasLoadError Relationships",
        "instance_type_kind": "Relationship",
        "description": "Declared relationship from a HolonLoadResponse to one or more HolonError holons.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Allow",
        "is_definitional": false,
        "is_ordered": false,
        "allows_duplicates": false,
        "min_cardinality": 0,
        "max_cardinality": 32767
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#DeclaredRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#HolonLoadResponse.DanceResponseType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#HolonErrorType"
          }
        }
      ]
    },
    {
      "key": "(HolonErrorType)-[LoadErrorOf]->(HolonLoadResponse.DanceResponseType)",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "LoadErrorOf",
        "type_name_plural": "LoadErrorOfs",
        "display_name": "LoadErrorOf",
        "display_name_plural": "LoadErrorOf Relationships",
        "instance_type_kind": "Relationship",
        "description": "Inverse of HasLoadError. Points from HolonError back to the response that reported it.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false,
        "deletion_semantic": "Allow",
        "is_definitional": false,
        "is_ordered": false,
        "allows_duplicates": false,
        "min_cardinality": 0,
        "max_cardinality": 1
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#InverseRelationshipType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#RelationshipRule.KeyRuleType"
          }
        },
        {
          "name": "InverseOf",
          "target": {
            "$ref": "#(HolonLoadResponse.DanceResponseType)-[HasLoadError]->(HolonErrorType)"
          }
        },
        {
          "name": "SourceType",
          "target": {
            "$ref": "#HolonErrorType"
          }
        },
        {
          "name": "TargetType",
          "target": {
            "$ref": "#HolonLoadResponse.DanceResponseType"
          }
        }
      ]
    },
    {
      "key": "Key.PropertyType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "Key",
        "type_name_plural": "Keys",
        "display_name": "key",
        "display_name_plural": "keys",
        "instance_type_kind": "Property",
        "description": "Optional key to identify the holon instance within the import set.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#PropertyType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "ValueType",
          "target": {
            "$ref": "#MapStringValueType"
          }
        }
      ]
    },
    {
      "key": "RelationshipName.PropertyType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "RelationshipName",
        "type_name_plural": "RelationshipNames",
        "display_name": "relationship_name",
        "display_name_plural": "relationship_names",
        "instance_type_kind": "Property",
        "description": "Name of the relationship as declared in the JSON input.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#PropertyType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "ValueType",
          "target": {
            "$ref": "#MapStringValueType"
          }
        }
      ]
    },
    {
      "key": "IsDeclared.PropertyType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "IsDeclared",
        "type_name_plural": "IsDeclaredFlags",
        "display_name": "is_declared",
        "display_name_plural": "is_declared_flags",
        "instance_type_kind": "Property",
        "description": "Whether the relationship is declared (`true`) or inverse (`false`).",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#PropertyType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "ValueType",
          "target": {
            "$ref": "#MapBooleanValueType"
          }
        }
      ]
    },
    {
      "key": "HolonKey.PropertyType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HolonKey",
        "type_name_plural": "HolonKeys",
        "display_name": "holon_key",
        "display_name_plural": "holon_keys",
        "instance_type_kind": "Property",
        "description": "Local key for the referenced holon.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#PropertyType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "ValueType",
          "target": {
            "$ref": "#MapStringValueType"
          }
        }
      ]
    },
    {
      "key": "HolonId.PropertyType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HolonId",
        "type_name_plural": "HolonIds",
        "display_name": "holon_id",
        "display_name_plural": "holon_ids",
        "instance_type_kind": "Property",
        "description": "ActionHash identifier of a referenced holon.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#PropertyType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "ValueType",
          "target": {
            "$ref": "#MapBytesValueType"
          }
        }
      ]
    },
    {
      "key": "ProxyKey.PropertyType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "ProxyKey",
        "type_name_plural": "ProxyKeys",
        "display_name": "proxy_key",
        "display_name_plural": "proxy_keys",
        "instance_type_kind": "Property",
        "description": "Key of the ProxySpace through which this external reference is routed.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#PropertyType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "ValueType",
          "target": {
            "$ref": "#MapStringValueType"
          }
        }
      ]
    },
    {
      "key": "ProxyId.PropertyType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "ProxyId",
        "type_name_plural": "ProxyId",
        "display_name": "proxy_id",
        "display_name_plural": "proxy_ids",
        "instance_type_kind": "Property",
        "description": "ActionHash of the ProxySpace holon, used to route external references.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#PropertyType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "ValueType",
          "target": {
            "$ref": "#MapBytesValueType"
          }
        }
      ]
    },
    {
      "key": "HolonsStaged.PropertyType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HolonsStaged",
        "type_name_plural": "HolonsStageds",
        "display_name": "holons_staged",
        "display_name_plural": "holons_stageds",
        "instance_type_kind": "Property",
        "description": "Number of holons staged during the load operation.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#PropertyType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "ValueType",
          "target": {
            "$ref": "#MapIntegerValueType"
          }
        }
      ]
    },
    {
      "key": "HolonsCommitted.PropertyType",
      "type": "#TypeDescriptor",
      "properties": {
        "type_name": "HolonsCommitted",
        "type_name_plural": "HolonsCommitteds",
        "display_name": "holons_committed",
        "display_name_plural": "holons_committeds",
        "instance_type_kind": "Property",
        "description": "Number of holons successfully committed.",
        "is_abstract_type": false,
        "allows_additional_properties": false,
        "allows_additional_relationships": false
      },
      "relationships": [
        {
          "name": "ComponentOf",
          "target": {
            "$ref": "#MAP Metaschema-v0.0.2"
          }
        },
        {
          "name": "Extends",
          "target": {
            "$ref": "#PropertyType"
          }
        },
        {
          "name": "UsesKeyRule",
          "target": {
            "$ref": "#ExtendedTypeRule.KeyRuleType"
          }
        },
        {
          "name": "ValueType",
          "target": {
            "$ref": "#MapIntegerValueType"
          }
        }
      ]
    }
  ]
}

[owleyeview]

@evomimic I noticed you've been adding ".Type" or ".PropertyType" to most of your example TypeDescriptor definitions, so I used the ExtendedTypeRule.KeyRuleType for the non-relationship loader types. I generally like this pattern, but it makes relationship keys a bit unwieldy. We should think about whether we actually need the "Type" in the key of descriptors in the metaschema.

[evomimic]

Let's stick with this for now -- the suffix allows the type_names themselves to be shorter. I don't mind longer keys.

[evomimic]

@owleyeview : I arrived at what I think is a good solution to the issue we discussed this morning of somehow conveying the fact that LoaderHolons will have properties and relationships not enumerated in the LoaderHolon TypeDescriptor (because, literally ANY type of Holon can be imported).

Proposed Solution

I propose we follow the precedent of JSON Schema and OpenAPI and add a couple of boolean properties to HolonType definitions that indicate whether instances of that HolonType are allowed to include additional properties or additional relationships beyond those explicitly listed as InstanceProperties or InstanceRelationships for that HolonType.

Extend our Metaschema

• define two new boolean properties types: additional_properties and additional_relationships. These should default to false
• add these two new properties as InstanceProperties on the HolonType

Update Definition of LoaderHolon Type.

I've updated the definition of the HolonTypes for the LoaderSchema (see comment above) -- LoaderHolon sets both additional_properties and additional_relationships to true. The other two HolonTypes set these properties to false.

[owleyeview]

@evomimic I updated my generated JSON above.
A couple changes to note:

• I renamed the new properties to allow_additional_properties and allow_additional_relationships to be more descriptive and align with our current boolean property names.
• I added the properties to TypeDescriptor, not HolonType. These properties don't apply to instance holons, only to type descriptors.

[owleyeview]

@evomimic I noticed that the loader types listed here don't include HolonLoadSegment or the HolonsToLoad relationship. Am I correct that we need the one HolonLoadSegment to wrap the loader holons because a dance only accepts one holon? Or can my load function accept a Vec of transient references to LoaderHolons instead?

[evomimic]

Yea. I was just thinking about that also. What do you think about adding a HolonLoaderBundle HolonType with a LOADER_QUEUE relationship to LoaderHolon?

[owleyeview]

Ok. I do like HolonLoaderBundle better. Not sure about LOADER_QUEUE as that implies an ordered list...

[owleyeview]

What about HAS_LOADER_HOLON or BUNDLE_MEMBERS?

[evomimic]

BUNDLE_MEMBERS

[owleyeview]

@evomimic I need some clarification around the LoaderRelationshipReference.
I'm wondering if it is meant to represent a single link, or a 1:many relationship.

The cardinality constraints of the ReferenceSource and ReferenceTarget relationships make it seem like a 1:many relationship, but I'm not sure if that can work.

A LoaderRelationshipReference can represent an inverse relationship (it has the IsDeclared property), and it seems like that could make the cardinality constraints more complicated.

I think it would be simplest for each LoaderRelationshipReference to represent one link and constrain the ReferenceTarget to 1 target, but maybe there's something I'm missing.

What do you think?

[evomimic]

A single LoaderRelationshipReference can have multiple HolonReferences. DeclaredRelationships will have 1 ReferenceSource and possibly many ReferenceTargets. InverseRelationships are turned into DeclaredRelationships. If they >1 Source, you'll have to iterate through them to add_related_holons to the source. I acknowledge there can be some potential implementation complexity with that. If it feels unworkable, let's discuss.

[owleyeview]

I won't be adding related holons to the source of an inverse relationship. I will first find the declared counterpart and end up adding related holons to the target of the inverse relationship. The problem with this arrangement is that the ReferenceSource relationship has a max cardinality of 1. Maybe it should have the same cardinality as ReferenceTarget so they can be interchangeable?

[evomimic]

I won't be adding related holons to the source of an inverse relationship. I will first find the declared counterpart and end up adding related holons to the target of the inverse relationship. The problem with this arrangement is that the ReferenceSource relationship has a max cardinality of 1. Maybe it should have the same cardinality as ReferenceTarget so they can be interchangeable?

I know. You can only add related holons to a declared relationship. This means for inverse relationships, you have to find their inverse ( which will be a declared relationship whose source is the target of the inverse. Since count of targets can be > 1, you will have to iterate through this set of holons and call add_related_holons once per member of this set.

[owleyeview]

Thanks! One more question @evomimic :
The ReferenceTarget relationship has "is_ordered": true. Is that appropriate here? How is that order determined? Is that relevant at this point? Do we need to add some sort of positional property type to the metaschema?

[evomimic]

Great question. You can ignore for now. We're not yet supporting manually ordered relationships.

[nphias]

ok I would like help build a feature to upload the core schemas on startup for the tauri app..
i am seeing the JsonHolonLoaderClient as being built in rust under the Holons_client responsibility and processing the bundled JSON schema files for all the core-types etc. Ideally the loader would only need to run once for the core-schemas because they would be persisted to disc rather than just in memory..

a feature to upload schemas via UI typescript interface using the same JsonHolonLoaderClient is a separate issue for me ..

[owleyeview]

I don't understand why we would need a load-on-startup feature. Once the core schema is loaded, shouldn't it be persisted to a DHT and available to everyone? Is there something I'm missing?

I do see how saving a cache of holons to local disk would be helpful.

[evomimic]

Thanks for opening the conversation here, @nphias. I'll first provide a quick status update on the Holon Data Loader. Then I'll offer my thoughts on your specific proposal.

Holon Data Loader Status Update

TL/DR: everything is either complete or the implementation is in progress except for the JSON Parser (Issue #292) and the Validator (Issue #269) (which is on hold).

The diagram at the top of this discussion for reference is still an accurate depiction of the current design.

• Airtable Source of Truth -- Status: COMPLETE pending integration test.

  The Airtable component that serves as the source of truth for holons to load is stable and includes definitions for the MAP Metaschema and Loader Schema. Note the AirTable can contain Types (i.e., schemas) AND also Data (i.e., instances of Holon Types) -- they are represented the same way, because Types are, themselves, just Holons.

• JSON File Generator -- Status: COMPLETE pending integration test.

  This component has been built and used to generate the JSON files for the MAP Metaschema and Loader Schema. These JSON files have been loaded into our map-holons repo under the import_files folder.

• Issue Json Data Loader Client #292 -- Status: DESIGNED (initial).

  Think of this component as the JSON Parser. It is responsible for parsing a set of JSON input files, turning them into a transient HolonLoaderBundle that contains LoaderHolons, LoaderRelationshipReferences andLoaderHolonReferences. It will use existing dance types (with_properties, add_related_holons) plus two new ones being implemented via Issue Holon Loader Dance #293: new_holon (to create empty transient holons) and load_holons (to stage and commit once parsing is complete).

• Issue Holon Loader Dance #293 -- Status: Implementation in Progress.

  The dance request/dance response have been specified in the issue and @owleyeview is adding dispatch and implementation of the load_holons dance as a separate guest-resident crate. Also in scope for this enhancement is to add load_holons to the HolonServiceApi trait with a simple dance delegation implementation in client_holon_service and a dispatch function in the guest-side implementation.

• Issue JSON Data Importer #272 -- Status: COMPLETE pending integration test.

  This is the component that turns the LoaderHolons, LoaderRelationshipReferences and LoaderHolonReferences created by the JSON Parser into resolved holons that are staged and then committed to the DHT.

• Issue Generic Holon Validator #269 -- Status: ON HOLD Pending completion of full holon loader functionality.

  Our validation design depends on TypeDescriptors being loaded.

Comments on Feature to upload the core schemas on startup for the tauri app

I have both architectural and practical concerns about this proposal.

Architectural Concerns

• Agent-Centric Architecture

  • In MAP, apps don’t own data — agents do.
  • Each agent has an I-Space and may participate in shared We-Spaces. Every agent is also part of the Planetary We-Space.
  • Starting a Tauri container has no architectural relationship to loading data into a DHT. Schema installation belongs to the space installation process, not app startup.

• Core schema stewardship:

  The MAP Core Schema will live in its own dedicated Core Schema Space, stewarded collectively.
  Individual agent spaces (I-Spaces) or community spaces (We-Spaces) should only hold references to core schema elements — not the schema holons themselves. So if anything is “loaded” when a new I-Space is created, it should just be references to these shared schema holons. So we couldn't run an automated I-Space initialization load until AFTER the initial data load (via CLI or HI) is complete. In other words, implementing an auto-load script first doesn't make sense.

Practical Concerns

• Premature complexity:

Introducing app-startup schema loading adds significant unknowns before we’ve completed the core loader pipeline. Our immediate milestone is demonstrating end-to-end loading of both types and instances via the existing Holon Data Loader.

• Limited scope:

Even if an auto-loader worked for the core schema, it wouldn’t yet solve loading of domain or instance data. We’d still need the full loader capability. Delivering 2a or 2b covers BOTH initial schema load and ad hoc loads.

⸻

Options for delivery of Issue #292

I want to tease apart two things:

1. The essential functionality of parsing a set of JSON input files, turning them into a transient HolonLoaderBundle, then invoking the load_holons dance to stage and commit the contents of the bundle to a DHT.
2. The packaging of that functionality into some sort of executable container. This could be:
   a. Command-Line Interface (CLI)
   b. Tauri hosted Human-Interface (HI),
   c. "loader job" that could be automatically triggered.

Item 1 needs to be implemented regardless of packaging scenario.

The loader job (2c) is problematic for the reasons noted above. But I'm fine with either (2a) or (2b), whichever is easiest. For that matter, I'm also neutral on whether (2a) or (2b) is implemented in TypeScript or Rust (client) . It can't be implemented in Rust Guest, because the WASM sandbox doesn't allow access to the local file system.