MAP Runtime Shared Types¶

Purpose and authority¶

This document defines the canonical runtime representations and shared contracts reused across higher-level MAP surfaces. It is the runtime authority for the shared type family; exact schema declarations remain authoritative in the Core Schema TDL corpus.

For the broader representation architecture that situates these types between Integrity representations, shared objects, references, and typed wrappers, see the Holon Layered Representation Design Spec.

For the structural type model and descriptor semantics, see schema-design-spec.md and descriptor-semantics-rules.md.

These types are shared across surfaces such as:

commands
dances
queries
SDK-facing result shapes where appropriate

Runtime shared types are not:

descriptor holons or descriptor categories;
substitutes for schema declarations; or
surface-owned runtime envelopes.

They also do not force every surface to use the same internal execution carrier. For example, the current MAP query design uses HolonCollection as its primary internal holon result carrier while retaining scalar and row-shaped types as projection or boundary contracts.

Under Schema 2.0, a persisted runtime holon has exactly one DescribedBy target that is a concrete, non-abstract subtype of TypeDescriptor, such as Book.HolonType or ExecutionPlan.HolonType. Descriptor classification and runtime value carriage remain distinct concerns.

1. Core Posture¶

MAP runtime shared types have two coordinated subfamilies:

primary bound runtime shared types
secondary materialized projection and result types

The key rule is:

Runtime shared types should be holon-bound first and projection-shaped second.

This means:

intermediate execution should preserve identity-bearing holon-backed types as long as possible
projection should be deferred until a contract, operator boundary, or serialization need requires it
materialized scalar and row-shaped types remain important, but they are secondary relative to the bound side of the family

`Focal Space`¶

Focal Space is the HolonSpace that provides the default runtime context for an interaction when no narrower or explicit space is supplied.

It is usually the participant's current I-Space or selected We-Space.

Focal Space is shared runtime context, not a query-only concept. It may be used by:

commands, as the default target or interpretation context
dances, as the default affordance discovery or execution context
queries, as the default seed scope
SDK-facing flows, as the current interaction space

Focal Space does not override:

an explicit command target
an explicit dance subject
an explicit query ExecutionDomain
a holon's Home Space
TrustChannel policy
transaction or snapshot boundaries

Related distinctions:

Focal Space is the current default interaction context.
ExecutionDomain is the set of spaces allowed to participate in a query seed operation.
Home Space is the authoritative owner of a holon and its adjacency.

2. Primary Holon-Backed Runtime Shared Types¶

Primary holon-backed runtime shared types are the main identity-preserving runtime-carried types shared across commands, dances, navigation operation dances, and SDK-facing surfaces.

They are:

identity-bearing
reference-layer-aligned
projection-deferred by default

`HolonReference`¶

HolonReference is the foundational singular bound runtime shared type.

It is the correct opaque handle for holon-bound execution because it:

preserves transaction-relative behavior
hides transient vs staged vs saved distinctions
routes reads through the correct backing implementation
avoids exposing fetch timing to call sites

Use HolonReference when a runtime shared type needs to refer to a singular holon-bound object without forcing property projection.

`HolonCollection`¶

HolonCollection is the canonical plural holon-backed runtime carrier for the current MAP implementation posture.

Because HolonCollection.HolonType is a concrete Schema 2.0 holon type, a persisted collection may also be the target of an ordinary HolonReference.

This creates an important read-side simplification opportunity:

collection-bearing reads do not always need to be treated as bespoke plural payloads
in many cases, a caller may resolve a HolonReference to a collection holon and then inflate an ergonomic HolonCollection view from its descriptor and related collection semantics
collection identity, collection semantics, and collection membership can increasingly be modeled through ordinary persisted holons and relationships

This document therefore distinguishes:

persisted collection holons, which are first-class schema-recognized holons
HolonCollection as the runtime shared type used to carry or expose plural holon-backed state ergonomically in memory

MAP already defines:

pub struct HolonCollection {
    state: CollectionState,
    members: Vec<HolonReference>,
    keyed_index: BTreeMap<MapString, usize>,
}

This gives MAP the shape needed for holon-oriented navigation:

collection lifecycle state
ordered holon references
keyed lookup
continued navigation through HolonReference

Use HolonCollection when a runtime shared type needs to carry a plural holon-backed result without collapsing it into projected rows.

Variables, output binding names, and derivation structure should not be embedded in HolonCollection. Those belong to operation intent, ExecutionPlan holons, InteractiveNavigationSession, or result holons.

Read-Side Semantic Accessors¶

Some read-side callers have schema-backed expectations about collection shape and should be able to express those expectations directly rather than manually inspecting members.

Highly likely accessors include:

impl HolonCollection {
    pub fn expect_required_single(
        &self,
        context: CollectionContext,
    ) -> Result<&HolonReference, CollectionShapeError>;

    pub fn expect_optional_single(
        &self,
        context: CollectionContext,
    ) -> Result<Option<&HolonReference>, CollectionShapeError>;
}

Semantics:

expect_required_single(...) succeeds only when the collection contains exactly one member and returns that member
expect_optional_single(...) succeeds when the collection contains zero or one member and returns None or that sole member
both accessors fail when the actual member count violates the expected shape
errors should include enough context to identify the relationship, property, or access path that expected the shape

These accessors are appropriate where:

the caller already has a schema-backed cardinality expectation
the caller would otherwise index into members or manually inspect length
a domain-specific invariant error is more appropriate than an incidental empty or out-of-bounds error

Examples of likely early consumers include relationships whose schema semantics already imply a single target, such as DescribedBy.

This document specifies these accessors as likely runtime shared API surface, but their implementation should remain on demand:

the signatures and semantics may be specified in advance
a concrete enhancement may pull one or more accessors into scope when it has an immediate need
accessors should be introduced when they simplify a real call site with a real schema-backed expectation, not as speculative upfront API inventory

These accessors do not require HolonCollection to become an enum or trait family. They can be introduced against the existing struct representation and preserved if the internal representation evolves later.

Deferred Write-Side Use¶

Typed write-side HolonCollection input remains a valid future direction, but it is not part of the current runtime contract.

This deferment is intentional:

the blast radius of end-to-end write-side command, wire, runtime, and SDK changes is large
the immediate payoff from HolonCollection.HolonType is read-side simplification through first-class collection identity and ordinary reference resolution
future write-side work should be reconsidered after that read-side simplification has been better explored

`BoundHolonCollection`¶

BoundHolonCollection is a deferred candidate, not a canonical runtime shared type in the current design.

Do not introduce BoundHolonCollection unless a future contract needs lifecycle or semantic obligations that HolonCollection plus surrounding plan/session/result structure cannot represent.

Examples of future obligations that might justify a distinct type:

a collection must itself be a persisted holon with independent lifecycle
a collection must carry descriptor-owned collection semantics beyond membership
a cross-surface contract needs a first-class collection reference rather than an inline collection value
a result-set artifact must be independently shared, authorized, or versioned

Until then, named plural bindings are represented by:

ExecutionPlan holon variables
NavigationExecutionBindings
Navigation Operation or Dance result metadata
HolonCollection values

`SmartReference`¶

SmartReference remains a runtime shared type where smart-link-aware behavior is contract-significant.

Use SmartReference directly only when the contract surface genuinely benefits from exposing:

smart-link identity
smart-link-cached property access
smart-link-specific lifecycle or navigation semantics

Otherwise, prefer the broader HolonReference.

3. Secondary Materialized Projection and Result Types¶

These remain runtime shared types, but they are secondary relative to the primary bound types.

They are used when a contract, operator, ABI, or serialization boundary requires materialized projection forms.

`BaseValue`¶

BaseValue is the canonical scalar runtime shared type.

Use BaseValue for:

scalar payloads
parameter atoms
single field results
explicitly materialized scalar outputs

BaseValue is already the MAP runtime scalar substrate, so no additional Value layer is introduced here.

BaseValue is a runtime representation, not a value type descriptor. A property descriptor uses a ValueType relationship to name the semantic value type, and the corresponding property value is carried at runtime as a BaseValue variant.

`Row`¶

Row is a single materialized row-shaped projection keyed by projection labels serialized as strings.

Keys are not descriptor-backed property identifiers in this slice.

Use Row when a result or parameter shape needs multiple named scalar fields in one projection object.

A Row is a shared materialized projection type, not necessarily the engine's primary binding representation.

`RowSet`¶

RowSet is an ordered collection of rows.

Use RowSet when a contract needs a collection of row-shaped projections.

RowSet preserves row order but does not imply uniqueness, schema, cursoring, streaming, or planner semantics.

A RowSet is a materialized projection and result type, not the same thing as a plural holon-native carrier such as HolonCollection.

4. Restricted Runtime Shared Type¶

`Holon`¶

Holon is not a general-purpose runtime shared type for new business-level cross-surface contracts.

It remains legitimate only for narrow infrastructure-level full-state transfer, especially:

cache hydration
internal full-state retrieval paths whose purpose is to populate in-memory cache on a cache miss

This means:

Holon remains allowed where the goal is explicit infrastructure hydration
Holon should not be used as the default request or result shape for general commands, dances, or queries

When a general cross-surface contract needs to expose data, the preferred choices are:

HolonReference
HolonCollection
BaseValue
Row
RowSet

5. Deferred Projection Rule¶

The runtime shared type family preserves deferred projection explicitly.

This means:

intermediate execution may retain HolonReference-backed or HolonCollection-backed state
properties and relationships should be resolved through the Reference Layer and descriptor-backed structure as needed
BaseValue, Row, and RowSet should be materialized only when projection, filtering, ordering, aggregation, ABI exchange, or serialization requires those forms

So:

Row is a valid runtime shared type
RowSet is a valid runtime shared type
neither implies that all intermediate execution state should be eagerly row-native

6. Specialized Type Exception Rule¶

Higher-level surfaces should prefer the canonical runtime shared types where appropriate, but they may retain narrower specialized types where those types encode real legality or lifecycle constraints more precisely than the broader shared family.

Examples include:

TransientReference
appropriate when an action is valid only for transient sources
SmartReference
appropriate when an action is valid only for smart-reference-backed version lineage or smart-link semantics
LocalId
appropriate when a local deletion or mutation action should not force the caller to first materialize a broader holon reference

This rule preserves contract precision while still minimizing the overall runtime shared type set.

7. Relationship to Runtime Envelopes¶

Runtime shared types are not runtime envelopes.

Runtime envelopes remain surface-owned containers such as:

command request and response wrappers
dance invocation and outcome wrappers
navigation operation, execution plan, or declarative-query wrappers where those surfaces exist
trust-channel capsules
guest-to-hub outbound dispatch wrappers

Those envelope types should remain documented in their corresponding surface directories.

Commands, Dances, and navigation/query-related capabilities may wrap or invoke one another, but their envelopes should not be flattened into a single generic wrapper. For example, MapIpcRequest is a Commands ingress wrapper, not a Dance or Query envelope.

8. Appendix: Type Disposition Table¶

This appendix is intentionally limited to runtime shared types and closely related legacy or helper types that affect the shared runtime type posture.

Surface-owned envelopes and their legacy predecessors should be classified only in their corresponding surface documents.

Type	Classification	Permitted use	Notes
`HolonReference`	Canonical runtime shared type	General-purpose singular bound type across surfaces	Primary singular bound type
`HolonCollection`	Canonical runtime shared type	General-purpose plural holon-backed result carrier	Primary plural holon-backed type
`BoundHolonCollection`	Deferred candidate	None until a concrete lifecycle or contract need cannot be represented by `HolonCollection` plus surrounding plan, session, or result structure	Introduce only from a concrete cross-surface requirement
`SmartReference`	Canonical specialized runtime type	Contracts where smart-link-aware behavior is significant	Prefer `HolonReference` otherwise
`BaseValue`	Canonical runtime shared type	General-purpose scalar or projection atom	Runtime scalar substrate
`Row`	Canonical runtime shared type	Materialized named projection result	Secondary projection type
`RowSet`	Canonical runtime shared type	Materialized ordered collection of rows	Secondary projection type
`Record`	Deferred candidate	None currently	Possible richer result family
`RecordStream`	Deferred candidate	None currently	Possible streaming result family
`Holon`	Restricted runtime shared type	Internal full-state transfer and cache hydration	Not a general cross-surface business type
`Vec<HolonReference>`	Implementation helper	Low-level internal collection handling	Not a canonical cross-surface contract type

MAP Runtime Shared Types¶

Purpose and authority¶

1. Core Posture¶

Focal Space¶

2. Primary Holon-Backed Runtime Shared Types¶

HolonReference¶

HolonCollection¶

Read-Side Semantic Accessors¶

Deferred Write-Side Use¶

BoundHolonCollection¶

SmartReference¶

3. Secondary Materialized Projection and Result Types¶

BaseValue¶

Row¶

RowSet¶

4. Restricted Runtime Shared Type¶

Holon¶

5. Deferred Projection Rule¶

6. Specialized Type Exception Rule¶

7. Relationship to Runtime Envelopes¶

8. Appendix: Type Disposition Table¶

`Focal Space`¶

`HolonReference`¶

`HolonCollection`¶

`BoundHolonCollection`¶

`SmartReference`¶

`BaseValue`¶

`Row`¶

`RowSet`¶

`Holon`¶