# 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`) |
