frame_suite

Module virtuals

Source
Expand description

Virtual struct system mapping discriminants (ZSTs) to behavior via trait-driven schemas.

Traditional Rust data structures require committing upfront to:

  • a fixed shape (Option<T>, Vec<T>, [T; N], struct fields)
  • a fixed cardinality (single vs multiple)
  • a fixed storage layout

This makes evolution difficult:

  • structure and storage are tightly coupled
  • generic abstractions often hit coherence limits
  • external composition (plugins, schemas) is hard
  • changing a field (None -> Some -> Many) requires redesign

This module introduces a system where structure, interpretation, and storage are decoupled, and resolved through types.

§Mental Model: Virtual Structs

Think in terms of a virtual struct, whose fields are not stored directly, but defined through traits and discriminants:

ⓘ
struct <T as Trait>::Struct<K> {
    FieldTag: T::Field, // virtual field (identified by discriminant)
    ExtTag: K,          // virtual extension (identified by discriminant)
}

This is not a concrete struct. Instead:

  • fields are accessed via trait implementations
  • each field is identified by a discriminant (type-level key)
  • storage is abstracted or external

§Discriminants (Field Identifiers)

ⓘ
struct FieldTag;
struct ExtTag;

Discriminants are zero-sized types used as type-level field keys.

They act as:

  • field identifiers in the virtual struct
  • selectors for behavior and interpretation
  • disambiguators for generic implementations

This ensures:

  • multiple fields can coexist without ambiguity
  • overlapping generic impls remain coherence-safe

§Trait as Schema

ⓘ
pub trait Trait {
    type Struct: VirtualDynField<FieldTag, Some = Self::Field>
                + VirtualDynExtension<ExtTag>;

    type Field;
}
  • Struct is the container (virtual struct)
  • FieldTag identifies a logical field
  • ExtTag identifies an extension slot
  • Field defines the logical type of the field

Traits define the schema, not the storage.

§Field Behavior (Cardinality Abstraction)

A virtual field supports:

  • None - no value
  • Some - one value
  • Many - multiple values

This replaces fixed representations like:

ⓘ
Option<T> / Vec<T>

with a single abstraction that can evolve without redesign.

§Key Insight

A virtual struct is not a fixed layout, but a composition of discriminant-keyed behaviors, where:

  • discriminants -> field identifiers
  • traits -> schema (what exists)
  • implementations -> storage (how/where it exists)

Structure is resolved by types, not encoded directly.

§Core Primitives

The system is built from:

§Virtual Fields

§Virtual Extensions

§Schemas & Bounds

§Concrete Representations

§Design Principles

§Discriminant-Keyed Design

All components are keyed by a DiscriminantTag.

This:

  • avoids ambiguity in generic implementations
  • enables multiple independent fields on the same container
  • ensures coherence-safe extensibility

§Tagged Conversions

Instead of From / Into, the system uses:

Conversions are disambiguated by discriminants:

This avoids overlapping implementations in generic contexts.

§Layered Model

The system separates:

  • Type-level layer

    • defines structure, schema, and behavior

  • Value-level layer

    • represents None, Some, Many

This enables abstract structure with concrete representations.

§Dynamic vs Static

§Dynamic (Runtime Flexible)
  • vector-like semantics
  • runtime bounds (Get<u32>)
  • growable/shrinkable collections
§Static (Compile-Time Fixed)
  • array-like semantics
  • compile-time bounds (const)
  • zero-overhead representations

§Helpers

Ergonomic helpers are provided for working with virtual components:

§Summary

This system enables:

  • evolving data shapes without redesign
  • discriminant-keyed field composition
  • external composition via schemas and extensions
  • reuse of storage across multiple logical fields
  • coherence-safe generic abstractions

It provides a type-level virtualization layer where:

A virtual struct is a mapping from discriminants -> behaviors, resolved through traits and implemented via storage.

Structs§

ManyTag
A discriminant representing multiple values in tagged conversions.
NoneTag
A discriminant representing the absence of a value in tagged conversions.
SomeTag
A discriminant representing a single value in tagged conversions.

Enums§

SumDynType
A concrete representation of field cardinality: zero, one, or many values.
SumStaticType
A statically shaped representation of field cardinality.

Traits§

DelegateVirtualDynBound
Delegates bound resolution to an external VirtualDynBound provider.
DelegateVirtualDynExtension
Constraint for delegating a virtual extension to an external schema.
DelegateVirtualStaticBound
Delegates bound resolution to an external VirtualStaticBound provider.
DelegateVirtualStaticExtension
Constraint for delegating a virtual extension to an external VirtualStaticExtensionSchema.
DiscriminantTag
Marker trait for type-level discriminants.
DynExtHelpers
Helper methods for accessing and mutating values in a VirtualDynExtension.
DynFieldHelpers
Helper methods for accessing and mutating values in a VirtualDynField.
FromTag
Converts a value T into Self under a given discriminant.
IntoTag
Converts self into another representation under a given discriminant.
StaticExtHelpers
Helper methods for accessing and mutating values in a VirtualStaticExtension.
StaticFieldHelpers
Helper methods for accessing and mutating values in a VirtualStaticField.
TryFromTag
Fallible version of FromTag.
TryIntoTag
Fallible version of IntoTag.
VirtualCollector
A virtual collector for values of type T under a discriminant.
VirtualDynBound
Provides the bounds associated with a VirtualDynField<Discriminant>.
VirtualDynExtension
Allocation interface for virtual extensions whose type and schema are defined externally.
VirtualDynExtensionSchema
Defines the schema for a VirtualDynExtension identified by a Discriminant.
VirtualDynField
A discriminant-keyed virtual field abstraction with flexible cardinality (None, Some, or Many).
VirtualDynFieldWithDelegatedBounds
Constraint describing a virtual field whose bounds are delegated to an external VirtualDynBound provider.
VirtualError
Defines the error type associated with a virtual component identified by a Discriminant.
VirtualMap
A storage-backed virtual map owned by a container in the virtual structure system.
VirtualNMap
A storage-backed virtual n-map owned by a container in the virtual structure system.
VirtualStaticBound
Provides the bounds associated with a VirtualStaticField<Discriminant>.
VirtualStaticExtension
Allocation interface for virtual extensions whose type and schema are defined externally and fully determined at compile time.
VirtualStaticExtensionSchema
Defines the schema for a VirtualStaticExtension identified by a Discriminant.
VirtualStaticField
A discriminant-keyed virtual field abstraction with statically determined cardinality.
VirtualStaticFieldWithDelegatedBounds
Constraint describing a virtual field whose bounds are delegated to an external VirtualStaticBound provider.

Functions§

set_index 🔒
Sets the value at a given index in a collection.