Skip to content

MAP Type Loading Approach

Jump to bottom
Steve Melville edited this page Apr 28, 2025 · 1 revision

📦 MAP Type Loading

The MAP Type System is dynamic and extensible — but it still needs a consistent and reliable way to load type definitions at runtime.

Type loading involves a two-phase, modular strategy:

1️⃣ Schema Loader

The Schema Loader is responsible for loading all types that belong to a given schema — whether Core Types or agent-defined schemas.

It operates in two passes:

Pass Description
1 Create all type holons from Specs (no cross-links yet)
2 Queue and apply structural relationships (e.g., PROPERTY_OF, SOURCE_FOR)

This two-phase strategy ensures:

  • Holons exist before links reference them
  • Schema graphs are consistent even with cycles or forward references
  • Schema loaders can operate incrementally (e.g., partial schema upgrades)

🧠 Why two passes?
Without Pass 1 ensuring holon existence, cross-linking in Pass 2 could fail due to missing targets.

📈 Schema Loading Flow

flowchart TD
    A[Specs loaded (Rust or JSON)]
    B[Pass 1: Create Type Holons]
    C[Pass 2: Link Relationships]
    D[Schema Graph Ready]

    A --> B --> C --> D
Loading

2️⃣ TypeKind Definers

Each TypeKind has a corresponding TypeKind Definer — a module or struct that knows how to:

  • Build the appropriate type holon (e.g., PropertyType, RelationshipType)
  • Immediately stage (save) the descriptor
  • Queue up any relationship definitions for Pass 2 linking

This ensures:

  • Staging happens immediately
  • Linking happens once all types are available

Each definer function uses:

  • A Spec struct (Rust or JSON input)
  • Validation and consistency rules
  • Schema ownership metadata
Example TypeKind Definer Module
PropertyType PropertyTypeDefiner
RelationshipType RelationshipTypeDefiner
HolonType HolonTypeDefiner

🛠️ Each TypeKind has a definer that handles its full lifecycle — creation, validation, and linking.

3️⃣ TypeKind Spec Inputs: Rust or JSON

To define a type, you must supply a Spec that describes its required fields and optional constraints.

Specs can be provided in two formats:

Format Use Case
Rust Struct Used when defining types programmatically inside Rust code
JSON Object Used when loading agent-defined schemas at runtime

Each Spec typically includes:

  • Type name
  • Label and description
  • Value type (for PropertyType)
  • Structural links (PROPERTY_OF, SOURCE_FOR, TARGET_FOR)
  • Constraint fields (e.g., min_length, max_cardinality)

📄 Rust or JSON — the loader treats them uniformly after parsing into internal representations.

4️⃣ JSON Schema Definitions for Specs

Every TypeKind has a corresponding JSON Schema file that validates the structure of its Specs.

This ensures:

  • Runtime schema validation (before types are loaded)
  • Consistency across agents and environments
  • Easier tooling integration (e.g., forms, codegen)
TypeKind JSON Schema Filename
PropertyType property_type_spec.schema.json
RelationshipType relationship_type_spec.schema.json
HolonType holon_type_spec.schema.json
EnumVariantType enum_variant_type_spec.schema.json

🧩 Validating specs early prevents type graph corruption later.

5️⃣ Core Types Loading

MAP itself depends on a set of Core Types that must be present at runtime for essential operations.

These are loaded using:

  • Core Type JSON Specs stored in a known directory (e.g., core_types/definitions/*.json)
  • A specialized Core Schema Loader following the same two-pass strategy
  • Enforcement of known relationships (DESCRIBED_BY, HAS_ASPECT, etc.)

During startup:

  1. The core loader loads core type specs from JSON
  2. Stages the Core Type holons
  3. Links required relationships
  4. Verifies system integrity
Core Type Example Role
PropertyName Classifies property names (e.g., "title")
RelationshipName Classifies relationship names (e.g., "AUTHORED_BY")
SchemaName Classifies schemas

📚 Even system-critical types are treated holonically and loaded dynamically.

📜 Summary

Layer Role
Schema Loader Orchestrates full schema loading in two passes
TypeKind Definers Handle creation and staging of type holons per TypeKind
TypeKind Specs Define input fields for type creation (Rust or JSON)
JSON Schema Validation Ensures runtime specs are valid and complete
Core Types Loader Loads required system types from JSON to bootstrap MAP logic

🧠 MAP’s type loading strategy balances safety, flexibility, and openness — allowing types to be created programmatically or dynamically, while guaranteeing graph integrity and type validity.

MAP Holons

Clone this wiki locally