BaseTypes and BaseValues

🧩 MAP Extensibility — Defining New Types

Each BaseType (except ValueType) has a corresponding definer function, named define_<BaseTypeName>_type, which creates new types derived from that base. Examples include:

• define_holon_type
• define_property_type
• define_string_type

Each definer accepts a specification struct, conventionally named <BaseTypeName>Spec, which includes the property values and relationships needed to define the new type. This struct provides the type-specific fields needed to characterize the new type.

---

🧾 MAP TypeHeader

Every MAP type is represented by a TypeHeader holon and an associated <BaseTypeName>Type holon that specifies base-type-specific details.

Together, the TypeHeader and <BaseTypeName>Type holons define the identity, structure, and constraints of a given type.

The TypeHeader holon:

• Is a Holon described by the TypeHeader Core HolonType
• Is OWNED_BY a HolonSpace
• Is a COMPONENT_OF a Schema
• Includes shared properties such as:
  • type_name
  • label
  • description
  • base_type (a BaseType variant)

The <BaseTypeName>Type holon:

• Contains type-specific metadata or constraints
  e.g. min/max for an integer, allowed variants for an enum, source/target types for a relationship

Together, they fully characterize the type and are created as a pair by the relevant definer function.

---

🧮 MAP Value Types and Their Role in Type Descriptors

For types that involve scalar values, a third holon may participate in defining the type: a ValueType holon.

A complete type descriptor for a value-bearing type may involve:

• TypeHeader Holon — defines the identity and shared metadata (e.g., name, schema, ownership)
• <BaseTypeName>Type Holon — defines type-specific structure (e.g., constraints)
• ValueType Holon — identifies the type as a scalar value type and serves as the target for relationships like VALUE_TYPE_FOR used in properties

This triad ensures that type definitions are:

• Modular (each aspect is clearly isolated)
• Compositional (components can be reused and extended)
• Queryable (all aspects live as holons with relationships)

---

PRIOR VERSION

The MAP Type System: Layered Architecture

The MAP Type System is structured in five layers, each building upon the one below it. This layered approach allows the system to evolve from simple, portable primitives into semantically rich, application-specific types — while preserving portability, extensibility, and validation guarantees.

Type System Summary

Layer	Role	Examples
Layer 1	Portable, low-level types & runtime values	BaseType::Value(String), MapInteger
Layer 2	Semantically meaningful core primitives	HolonId, PropertyName, ValueType
Layer 3	Metadata & constraints for validating Layer 1/2	IntegerDescriptorType, StringDescriptorType
Layer 4	Reserved descriptors required by the MAP core	PropertyNameType, SemanticVersionType
Layer 5	Agent-defined extension descriptors	Custom enum types, string formats, etc

This multi-layered design enables strong typing, semantic expressiveness, and schema extensibility — from core infrastructure to custom applications.

🔹 Layer 1: Base Types

Definition

BaseType and BaseValue represent the most primitive and portable types in the MAP system. These types form the foundation of all other types.

BaseType

The BaseType enum specifies the full range of types the MAP is capable of storing and manipulating. This includes both structural and scalar types.

Variants include:

• Holon
• Collection
• Property
• Relationship
• EnumVariant
• Value(ValueType)
• ValueArray(ValueType)

These are used in the description of a type to declare the intended storage representation for instances of the described type.

BaseValue

The BaseValue enum holds actual values of scalar ValueTypes:

• StringValue(MapString)
• IntegerValue(MapInteger)
• BooleanValue(MapBoolean)
• EnumValue(MapEnumValue)

Each variant wraps a strongly-typed struct, ensuring consistent formatting, serialization, and conversion.

---

🔹 Layer 2: Core Types

Definition

CoreTypes build upon BaseTypes to define semantically meaningful types used within the MAP core code.

Characteristics

• Always built using a BaseType to ensure portability.
• Represent common, semantically enriched primitives, such as names and identifiers.
• Used to parameterize descriptors, holon types, or system APIs.

Examples

🔍 Example: PropertyName

PropertyName is a CoreType used throughout the MAP to name properties in a holon schema.

• BaseType: Value(ValueType::String)
• ValueType: String
• Stored as: BaseValue::StringValue(MapString)

This means:

• It is a scalar value, validated and constrained as a string.
• Its underlying value is stored using the MapString wrapper.
• It can have additional constraints (like format or length) defined via a corresponding DescriptorType.

In short: PropertyName is a ValueType::String type whose values are stored as BaseValue::StringValue(MapString).

🔍 Example: MaxLength

MaxLength is a CorePropertyType used to define the maximum allowed length of a string-based value type (e.g., StringValueType).

• BaseType: Property
• ValueType: Integer
• Stored as: BaseValue::IntegerValue(MapInteger)

This means:

• It defines a property on a DescriptorType holon, not on a user-facing data holon.
• The value stored is an integer wrapped in MapInteger.
• It is typically used within a StringDescriptorType to constrain MapString values.

In short: MaxLength is a property whose values are stored as BaseValue::IntegerValue(MapInteger) and apply to types that are ValueType::String.

---

🔍 Example: SourceHolonType

SourceHolonType is a CoreRelationshipType used in a relationship descriptor to define which holon type is allowed to appear on the source side of a relationship.

• BaseType: Relationship
• Target Type: HolonType
• Cardinality: Typically exactly one (but defined per descriptor)

This means:

• The relationship originates from a relationship descriptor and points to a specific holon type (i.e., the type of the source holon in an actual relationship instance).
• It enables the MAP to validate whether a given relationship is well-formed based on its direction and endpoint types.
• It supports schema introspection: "What types of holons can originate this relationship?"

In short: SourceHolonType is a relationship from a RelationshipDescriptor to a HolonType, used to define valid sources for that relationship.

CoreType Enum

CoreTypes are grouped by their function using the CoreType enum. Numbers in parentheses indicate the current number of types per group:

• DanceType (TBD)
• EnumVariantType (16)
• HolonType (24)
• IndexedType (2)
• PropertyType (24)
• RelationshipType (27)
• ValueType (8)

---

🔹 Layer 3: Descriptor Types

Definition

DescriptorTypes specify metadata and constraints for types defined in Layers 1 and 2. Every BaseType has a corresponding DescriptorType.

Characteristics

• Describe how to validate and render values of a given type.
• Support properties like:
  • Minimum/maximum length or value
  • Formatting or pattern constraints
  • Human-readable names, descriptions, and labels

Examples

• IntegerDescriptorType: defines min_value, max_value for integers.
• StringDescriptorType: defines min_length, max_length, string_format.

---

🔹 Layer 4: Core Descriptor Types

Definition

CoreDescriptorTypes are reserved descriptor types that are required by the MAP core. They define constraints and metadata for types like HolonId, PropertyName, and SemanticVersion.

Characteristics

• Not user-extensible.
• Used internally to ensure system-wide consistency and compatibility.
• Often reused across multiple CoreTypes.

Example

pub enum CoreStringDescriptorType {
    #[default]
    MapStringType,
    PropertyNameType,
    RelationshipNameType,
    SemanticVersionType,
}

---

🔹 Layer 5: Extension Descriptor Types

Definition

ExtensionDescriptorTypes allow developers to define custom, agent-specific types dynamically — without modifying or recompiling the MAP core.

Key Characteristics

✅ Agent-Defined

• Created and managed by agents to support their own data and application logic.
• Not part of the MAP core and do not require core approval or versioning.

✅ Dynamic

• Can be added or updated without recompilation of MAP code or schema migrations.
• Live as holons in the MAP just like core descriptors.

✅ Flexible

• Support user-defined:
  • Metadata
  • Validation rules
  • Semantic annotations
  • Relationships to other types or schemas

❗ Reserved Name Protection

• Agents cannot reuse names of any CoreDescriptorType (e.g., PropertyNameType) to avoid namespace collisions.

---