AyCode.Core/AyCode.Core/Serializers/README.md

Serializers

High-performance serialization framework — Binary, JSON, Toon — on shared infrastructure.

Folder Structure

Folder	Purpose
Binaries/	High-performance binary serialization with two-phase scan+serialize
Jsons/	Custom JSON serialization using Utf8JsonWriter/Utf8JsonReader
Toons/	LLM-optimized Token-Oriented Object Notation with @meta/@data sections
Expressions/	Expression tree serialization (LINQ Expression ↔ DTO)
Attributes/	Source generator marker attributes

Shared Infrastructure (Root Files)

Core Base Classes

• AcSerializerContextBase.cs — Generic base context AcSerializerContextBase<TMetadata, TOptions> with metadata caching, wrapper slot management, and context pooling. All three serializers derive from this.
• AcSerializerOptions.cs — Base options: reference handling mode, max depth, custom property mapping, ThrowOnCircularReference.
• TypeMetadataBase.cs — Cached type analysis: readable/writable properties, IId detection, complexity flags (HasComplexProperties, NeedsReferenceTracking, IsCollection).
• TypeMetadataWrapper.cs — Wraps metadata with per-context tracking state: typed IdentityMap instances (Int32/Int64/Guid), SmallIdBitmap, polymorphic cache, source-gen reader/writer registry lookup.

Serialization/Deserialization Bases

• SerializationContextBase.cs — Base for serialization contexts.
• DeserializationContextBase.cs — Base for deserialization contexts.
• SerializeTypeMetadataBase.cs — Base for format-specific serialize metadata.
• DeserializeTypeMetadataBase.cs — Base for format-specific deserialize metadata.
• DeserializeChainBase.cs — Deserialization chain pattern.
• DeserializeCrossTypeBase.cs — Cross-type deserialization support.

Property Handling

• PropertyAccessorBase.cs — Base for reading property values during serialization.
• PropertySetterBase.cs — Base for writing property values during deserialization.
• PropertyMetadataBase.cs — Base property metadata shared across formats.

Utilities

• AcSerializerCommon.cs — Expression type checking, queryable type refs, ThreadLocal cache helpers, compiled constructor creation.
• IdentityMap.cs — High-perf hash table optimized for small int keys (bitmap) + chaining for large keys. Used for reference tracking.
• FnvHash.cs — Deterministic FNV-1a property name hashing (used in Binary UseMetadata mode).
• ReferenceTracker.cs — ReferenceEqualityComparer for object identity-based tracking dictionaries.
• IIdCollectionMergeHelper.cs — Collection merge operations during PopulateMerge (handles orphaned item removal).

Architecture

Generic Specialization Pattern

AcSerializerContextBase<TMetadata, TOptions>
├─ BinarySerializationContext  <BinarySerializeTypeMetadata,  AcBinarySerializerOptions>
├─ JsonSerializationContext    <JsonSerializeTypeMetadata,     AcJsonSerializerOptions>
└─ ToonSerializationContext    <ToonSerializeTypeMetadata,     AcToonSerializerOptions>

Key Design Decisions

• Sealed derived classes — All context implementations are sealed for JIT direct calling (no virtual dispatch on hot paths).
• Context pooling — Contexts are reused across serializations via thread-safe pools. ResetTracking() clears reference maps on pool return.
• Property ordering — Hierarchy-aware (base→derived) then alphabetical. Ensures stable property indices across type versions.
• Typed reference access — No boxing for common ID types. Pre-cast delegates: RefIdGetterInt32, RefIdGetterInt64, RefIdGetterGuid.
• Zero-allocation hot paths — Buffer owned by context, Span-based operations, ArrayPool for large allocations.
• Global metadata cache — Thread-safe per TMetadata type, shared across all contexts of that serializer type.

Reference Handling Modes

Mode	Description
None	No tracking, fastest path
OnlyId	Only IId<T> types tracked (Binary only)
All	All reference types tracked (required for JSON $ref)