Update dependencies and expand README documentation

Updated test and benchmark project dependencies to latest versions (BenchmarkDotNet, coverlet.collector, MSTest, etc.). Reformatted source generator project references for consistency. Commented out most AcBinary benchmark variants in Program.cs, leaving only FastMode+Default enabled. Significantly expanded README with detailed architecture, file descriptions, and configuration for each serializer subfolder. Added LLM maintenance notes to ensure documentation stays in sync with code changes.
2026-03-20 16:42:51 +01:00 · 2026-03-20 16:42:51 +01:00 · 0e912891b1
parent 16daad2917
commit 0e912891b1
14 changed files with 392 additions and 39 deletions
--- a/AyCode.Benchmark/AyCode.Benchmark.csproj
+++ b/AyCode.Benchmark/AyCode.Benchmark.csproj
@ -16,9 +16,9 @@
  </ItemGroup>

  <ItemGroup>
-    <PackageReference Include="BenchmarkDotNet" Version="0.15.2" />
+    <PackageReference Include="BenchmarkDotNet" Version="0.15.8" />
    <PackageReference Include="MessagePack" Version="3.1.4" />
-    <PackageReference Include="Microsoft.VisualStudio.DiagnosticsHub.BenchmarkDotNetDiagnosers" Version="18.3.36812.1" />
+    <PackageReference Include="Microsoft.VisualStudio.DiagnosticsHub.BenchmarkDotNetDiagnosers" Version="18.6.37110.2" />
    <PackageReference Include="MongoDB.Bson" Version="3.5.2" />
  </ItemGroup>

@ -29,9 +29,7 @@
    <ProjectReference Include="..\AyCode.Services.Server\AyCode.Services.Server.csproj" />
    <ProjectReference Include="..\AyCode.Models.Server\AyCode.Models.Server.csproj" />
    <!-- Source Generator for [AcBinarySerializable] marked types -->
-    <ProjectReference Include="..\AyCode.Core.Serializers.SourceGenerator\AyCode.Core.Serializers.SourceGenerator.csproj" 
-                      OutputItemType="Analyzer" 
-                      ReferenceOutputAssembly="false" />
+    <ProjectReference Include="..\AyCode.Core.Serializers.SourceGenerator\AyCode.Core.Serializers.SourceGenerator.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
  </ItemGroup>

  <ItemGroup>
--- a/AyCode.Core.Serializers.Console/Program.cs
+++ b/AyCode.Core.Serializers.Console/Program.cs
@ -223,16 +223,16 @@ public static class Program
        {
            
            // AcBinary variants
-            new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.FastMode, SerializerAcBinaryFastMode),
-            //new AcBinaryBenchmark(testData.Order, binaryFastModeNoSgenOption, SerializerAcBinaryFastNoSgen),
-            new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.Default, SerializerAcBinaryDefault),
-            //new AcBinaryBenchmark(testData.Order, binaryDefaultNoSgenOption, SerializerAcBinaryDefaultNoSgen),
-            new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.WithoutReferenceHandling, SerializerAcBinaryNoRef),
-            new AcBinaryBenchmark(testData.Order, binaryNoInternOption, SerializerAcBinaryNoIntern),
+            //new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.FastMode, SerializerAcBinaryFastMode),
+            ////new AcBinaryBenchmark(testData.Order, binaryFastModeNoSgenOption, SerializerAcBinaryFastNoSgen),
+            //new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.Default, SerializerAcBinaryDefault),
+            ////new AcBinaryBenchmark(testData.Order, binaryDefaultNoSgenOption, SerializerAcBinaryDefaultNoSgen),
+            //new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.WithoutReferenceHandling, SerializerAcBinaryNoRef),
+            //new AcBinaryBenchmark(testData.Order, binaryNoInternOption, SerializerAcBinaryNoIntern),

            //new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.FastMode, SerializerAcBinaryFastMode),
            //new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.FastMode, SerializerAcBinaryFastNoSgen),
-            //new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.FastMode, SerializerAcBinaryDefault),
+            new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.FastMode, SerializerAcBinaryDefault),
            //new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.FastMode, SerializerAcBinaryDefaultNoSgen),
            //new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.FastMode, SerializerAcBinaryNoRef),
            //new AcBinaryBenchmark(testData.Order, AcBinarySerializerOptions.FastMode, SerializerAcBinaryNoIntern),
--- a/AyCode.Core.Tests.Internal/AyCode.Core.Tests.Internal.csproj
+++ b/AyCode.Core.Tests.Internal/AyCode.Core.Tests.Internal.csproj
@ -8,15 +8,15 @@
 	<Import Project="..//AyCode.Core.targets" />

 	<ItemGroup>
-		<PackageReference Include="coverlet.collector" Version="6.0.4">
+		<PackageReference Include="coverlet.collector" Version="8.0.1">
 			<PrivateAssets>all</PrivateAssets>
 			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 		</PackageReference>
 		<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.11" />
 		<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.11" />
-		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
-		<PackageReference Include="MSTest.TestAdapter" Version="4.0.2" />
-		<PackageReference Include="MSTest.TestFramework" Version="4.0.2" />
+		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+		<PackageReference Include="MSTest.TestAdapter" Version="4.1.0" />
+		<PackageReference Include="MSTest.TestFramework" Version="4.1.0" />
 		<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
 	</ItemGroup>

--- a/AyCode.Core.Tests/AyCode.Core.Tests.csproj
+++ b/AyCode.Core.Tests/AyCode.Core.Tests.csproj
@ -15,11 +15,11 @@
 		<PackageReference Include="MessagePack" Version="3.1.4" />
 		<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.11" />
 		<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.11" />
-		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
+		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
 		<PackageReference Include="MongoDB.Bson" Version="3.5.2" />
-		<PackageReference Include="MSTest.TestAdapter" Version="4.0.2" />
-		<PackageReference Include="MSTest.TestFramework" Version="4.0.2" />
-		<PackageReference Include="coverlet.collector" Version="6.0.4">
+		<PackageReference Include="MSTest.TestAdapter" Version="4.1.0" />
+		<PackageReference Include="MSTest.TestFramework" Version="4.1.0" />
+		<PackageReference Include="coverlet.collector" Version="8.0.1">
 			<PrivateAssets>all</PrivateAssets>
 			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 		</PackageReference>
@ -29,9 +29,7 @@
 	<ItemGroup>
 		<ProjectReference Include="..\AyCode.Core.Server\AyCode.Core.Server.csproj" />
 		<ProjectReference Include="..\AyCode.Core\AyCode.Core.csproj" />
-		<ProjectReference Include="..\AyCode.Core.Serializers.SourceGenerator\AyCode.Core.Serializers.SourceGenerator.csproj" 
-						  OutputItemType="Analyzer" 
-						  ReferenceOutputAssembly="false" />
+		<ProjectReference Include="..\AyCode.Core.Serializers.SourceGenerator\AyCode.Core.Serializers.SourceGenerator.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
 		<ProjectReference Include="..\AyCode.Entities.Server\AyCode.Entities.Server.csproj" />
 		<ProjectReference Include="..\AyCode.Entities\AyCode.Entities.csproj" />
 		<ProjectReference Include="..\AyCode.Interfaces.Server\AyCode.Interfaces.Server.csproj" />
--- a/AyCode.Core/Serializers/Attributes/README.md
+++ b/AyCode.Core/Serializers/Attributes/README.md
@ -0,0 +1,27 @@
+# Attributes
+
+Marker attributes for the serialization framework's source generation features.
+
+## Key Files
+
+- **`AcBinarySerializableAttribute.cs`** — Marks types for binary serialization source generation. When applied to a class/struct, the source generator produces optimized `IGeneratedBinaryWriter`/`IGeneratedBinaryReader` implementations, avoiding runtime reflection. Used in conjunction with `Binaries/IGeneratedBinaryWriter.cs` and `Binaries/IGeneratedBinaryReader.cs`.
+
+## Usage
+
+```csharp
+[AcBinarySerializable]
+public class MyType
+{
+    public int Id { get; set; }
+    public string Name { get; set; }
+}
+```
+
+## Dependencies
+
+- None (standalone attribute definitions)
+- Consumed by the source generator and `Binaries/` serializer at runtime via `TypeMetadataWrapper` registry lookup.
+
+---
+
+> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code.
--- a/AyCode.Core/Serializers/Binaries/README.md
+++ b/AyCode.Core/Serializers/Binaries/README.md
@ -0,0 +1,96 @@
+# Binaries
+
+High-performance binary serialization/deserialization with two-phase processing, multiple wire modes, string interning, and source generation support. The primary goal is **speed**: every design decision prioritizes minimal latency and maximum throughput.
+
+## Architecture
+
+### Two-Phase Serialization
+
+1. **Scan Pass** (`AcBinarySerializer.ScanPass.cs`) — Walks the object graph to detect multi-referenced objects and build the reference table.
+2. **Serialize Pass** (`AcBinarySerializer.BinarySerializationContext.cs`) — Writes the binary output using the reference table from the scan pass.
+
+The serializer is generic over `TOutput` for strategy selection (`ArrayBinaryOutput` vs `BufferWriterBinaryOutput`).
+
+### Wire Format
+
+`BinaryTypeCode.cs` defines 100+ type markers:
+
+| Range | Purpose |
+|---|---|
+| 0–63 | **FixObj** — Compiled type slot indices |
+| 64–71 | **Complex types** — Object, ObjectRef, Array, Dictionary, ByteArray (with/without metadata) |
+| 72–75 | **Polymorphic** — ObjectWithTypeName, ObjectWithTypeIndex (with/without RefFirst) |
+| 76–90 | **Primitives** — Null, Bool, Int8–64, Float32–64, Decimal, Char |
+| 91–94 | **Strings** — String, StringInterned, StringEmpty, StringInternFirst |
+| 95–98 | **Date/Time** — DateTime, DateTimeOffset, TimeSpan, Guid |
+| 103–134 | **FixStr** — Short strings with length encoded in marker |
+| 144+ | **Headers** — Metadata, RefHandling, CacheCount flags |
+| 192–255 | **Tiny ints** — Single-byte encoding for values -16 to 47 |
+
+## Key Files
+
+### Serialization
+- **`AcBinarySerializer.cs`** — Main serializer entry point, context pool management.
+- **`AcBinarySerializer.BinarySerializationContext.cs`** — Core serialization logic, object graph traversal, type writing.
+- **`AcBinarySerializer.BinarySerializationContext.PropertyWriters.cs`** — Per-type property write methods.
+- **`AcBinarySerializer.BinarySerializationResult.cs`** — Result wrapper (byte[] or IBufferWriter output).
+- **`AcBinarySerializer.BinarySerializeTypeMetadata.cs`** — Cached type metadata for serialization.
+- **`AcBinarySerializer.ScanPass.cs`** — Reference scanning phase.
+
+### Deserialization
+- **`AcBinaryDeserializer.cs`** — Main deserializer entry point.
+- **`AcBinaryDeserializer.BinaryDeserializationContext.cs`** — Core deserialization logic.
+- **`AcBinaryDeserializer.BinaryDeserializationContext.Read.cs`** — Primitive read operations.
+- **`AcBinaryDeserializer.BinaryDeserializeTypeMetadata.cs`** — Cached type metadata for deserialization.
+- **`AcBinaryDeserializer.CrossType.cs`** — Cross-type deserialization (schema evolution).
+- **`AcBinaryDeserializer.Populate.cs`** — Object population and merge operations.
+
+### I/O Strategies
+- **`BinaryOutputBase.cs`** — Output interface.
+- **`ArrayBinaryOutput.cs`** — `ArrayPool`-backed output, fastest for `byte[]` result.
+- **`BufferWriterBinaryOutput.cs`** — `IBufferWriter<byte>`-backed output for streaming.
+- **`ArrayPooledBufferWriter.cs`** — Concrete `IBufferWriter` implementation.
+- **`IBinaryInputBase.cs`** — Input interface.
+- **`ArrayBinaryInput.cs`** — Single contiguous `byte[]` input.
+- **`SequenceBinaryInput.cs`** — Multi-segment `ReadOnlySequence<byte>` input.
+
+### Configuration & Types
+- **`AcBinarySerializerOptions.cs`** — All configuration options and presets.
+- **`BinaryTypeCode.cs`** — Wire format type markers.
+- **`StringInterningMode.cs`** — Enum: `None`, `Attribute`, `All`.
+- **`AcStringInternAttribute.cs`** — Property-level string interning control.
+- **`TypeConversionInfo.cs`** — Type conversion tracking for cross-type scenarios.
+- **`BinaryPropertyFilterContext.cs`** — Instance-dependent property filtering.
+
+### Property Handling
+- **`BinaryPropertyAccessorBase.cs`** — Property accessor for serialization.
+- **`BinaryPropertySetterBase.cs`** — Property setter for deserialization.
+
+### Source Generation
+- **`IGeneratedBinaryWriter.cs`** — Interface for source-generated writers.
+- **`IGeneratedBinaryReader.cs`** — Interface for source-generated readers.
+
+### Exceptions
+- **`AcBinaryDeserializationException.cs`** — Rich exception with binary offset context.
+
+## Configuration Options
+
+| Option | Values | Description |
+|---|---|---|
+| `UseMetadata` | bool | Property hash metadata for cross-type deserialization |
+| `UseStringInterning` | None/Attribute/All | String deduplication strategy |
+| `ReferenceHandling` | None/OnlyId/All | Circular reference support |
+| `WireMode` | Compact/Fast | VarInt+UTF-8 vs fixed-width+UTF-16 |
+| `UseCompression` | None/Block/BlockArray | LZ4 compression support |
+
+**Presets:** `Default`, `FastMode`, `ShallowCopy`, `WasmOptimized`.
+
+## Dependencies
+
+- Base classes from parent `Serializers/` folder (`AcSerializerContextBase`, `TypeMetadataBase`, `IdentityMap`, etc.)
+- `System.Buffers` (ArrayPool, IBufferWriter)
+- LZ4 (optional compression)
+
+---
+
+> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code.
--- a/AyCode.Core/Serializers/Expressions/README.md
+++ b/AyCode.Core/Serializers/Expressions/README.md
@ -0,0 +1,25 @@
+# Expressions
+
+Serialization support for LINQ Expression trees and `IQueryable` objects. Converts expressions to a format-agnostic DTO (`AcExpressionNode`) that can be serialized by any of the three serializer formats.
+
+## Key Files
+
+- **`AcExpressionNode.cs`** — DTO representing any Expression node. Contains `ConstantValueType` enum (20+ values) for typed constant representation. Recursive structure mirrors the expression tree.
+- **`AcExpressionConverter.cs`** — Converts `Expression` → `AcExpressionNode`. Handles all expression types (lambda, binary, member access, method call, etc.).
+- **`AcExpressionRebuilder.cs`** — Converts `AcExpressionNode` → `Expression`. Reconstructs the full expression tree from the DTO.
+- **`AcExpressionHelper.cs`** — Expression utilities shared across the module.
+
+## Integration
+
+- Automatically triggered in JSON and Toon serializers when an `Expression` or `IQueryable` is encountered during serialization.
+- Binary serializer supports expressions via compiled expression delegates.
+- `AcSerializerCommon.cs` (parent folder) provides expression type checking helpers (`ExpressionType`, `ExpressionGenericType`).
+
+## Dependencies
+
+- `System.Linq.Expressions`
+- `AcSerializerCommon` from parent `Serializers/` folder
+
+---
+
+> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code.
--- a/AyCode.Core/Serializers/Jsons/README.md
+++ b/AyCode.Core/Serializers/Jsons/README.md
@ -0,0 +1,52 @@
+# Jsons
+
+Custom JSON serialization/deserialization built on `System.Text.Json`'s `Utf8JsonWriter`/`Utf8JsonReader`, optimized for `IId` reference handling and polymorphic types.
+
+## Architecture
+
+- Reference scanning phase (pre-visit) detects multi-referenced objects before serialization.
+- Uses `$id`/`$ref` JSON properties for circular reference handling (JSON standard).
+- Polymorphic type hints via typename property.
+- Context pooling for allocation efficiency.
+
+## Key Files
+
+### Serialization
+- **`AcJsonSerializer.cs`** — Main serializer entry point, context pool management.
+- **`AcJsonSerializer.JsonSerializationContext.cs`** — Core serialization logic with `Utf8JsonWriter`.
+- **`AcJsonSerializer.JsonSerializeTypeMetadata.cs`** — Cached type metadata for serialization.
+- **`AcJsonSerializerOptions.cs`** — Configuration and presets.
+
+### Deserialization
+- **`AcJsonDeserializer.cs`** — Main deserializer entry point.
+- **`AcJsonDeserializer.JsonDeserializationContext.cs`** — Core deserialization logic.
+- **`AcJsonDeserializer.JsonDeserializeTypeMetadata.cs`** — Cached type metadata for deserialization.
+- **`AcJsonDeserializer.JsonElement.cs`** — `JsonElement` processing.
+- **`AcJsonDeserializer.Primitives.cs`** — Primitive type conversions.
+- **`AcJsonDeserializer.Utf8Reader.cs`** — `Utf8JsonReader` operations.
+
+### Supporting
+- **`AcJsonContextBase.cs`** — Base context shared between serializer and deserializer.
+- **`JsonPropertyAccessorBase.cs`** — Property accessor for serialization.
+- **`JsonPropertySetterBase.cs`** — Property setter for deserialization.
+- **`MergeContractResolver.cs`** — Contract resolution for merge/populate operations.
+- **`AcJsonDeserializationException.cs`** — Rich exception with JSON context, type info, and original exception.
+
+## Configuration
+
+| Option | Description |
+|---|---|
+| `ReferenceHandling` | `All` required — `OnlyId` not fully implemented for JSON |
+| `MaxDepth` | Maximum object graph depth |
+| `ThrowOnCircularReference` | Throw vs silently handle circular refs |
+
+**Presets:** `Default` (with refs), `ShallowCopy`, `WithMaxDepth`, `WithoutReferenceHandling`.
+
+## Dependencies
+
+- Base classes from parent `Serializers/` folder
+- `System.Text.Json` (`Utf8JsonWriter`, `Utf8JsonReader`, `JsonElement`)
+
+---
+
+> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code.
--- a/AyCode.Core/Serializers/README.md
+++ b/AyCode.Core/Serializers/README.md
@ -0,0 +1,77 @@
+# Serializers
+
+High-performance serialization framework supporting three formats — Binary, JSON, and Toon — built on a 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-performance 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`) |
+
+---
+
+> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code.
--- a/AyCode.Core/Serializers/Toons/README.md
+++ b/AyCode.Core/Serializers/Toons/README.md
@ -0,0 +1,80 @@
+# Toons
+
+Token-Oriented Object Notation (Toon) — an LLM-optimized serialization format with separate schema (@meta) and data (@data) sections. The primary goal is **LLM accuracy**: maximizing the precision and correctness of LLM responses by providing structured, unambiguous context. Designed for human and LLM readability with minimal token usage.
+
+## Architecture
+
+### Serialization Modes
+
+| Mode | Description |
+|---|---|
+| `Full` | Both @meta (schema) and @data (values) — default |
+| `MetaOnly` | Only @meta section (send schema once, reuse across conversation) |
+| `DataOnly` | Only @data section (when schema already sent) |
+
+### Output Sections
+
+- **@meta** — Type definitions, property descriptions, navigation info, constraints.
+- **@types** — Per-type schema with constraints and examples.
+- **@data** — Actual object values with optional type hints.
+
+### Key Features
+
+- Triple-quote syntax for multi-line strings.
+- Topological sorting for complex type relationships.
+- Navigation property tracking (foreign keys and relationships).
+- Type relation understanding (inheritance, interfaces).
+
+## Key Files
+
+### Core
+- **`AcToonSerializer.cs`** — Main serializer entry point and orchestration.
+- **`AcToonSerializer.ToonSerializationContext.cs`** — Serialization context.
+- **`AcToonSerializer.ToonSerializeTypeMetadata.cs`** — Cached type metadata.
+- **`AcToonSerializerOptions.cs`** — Configuration and presets.
+- **`AcToonContextBase.cs`** — Base context.
+
+### Output Generation (partial classes of AcToonSerializer)
+- **`AcToonSerializer.MetaWriter.cs`** — @meta section generation.
+- **`AcToonSerializer.TypeDefinitions.cs`** — @types section generation.
+- **`AcToonSerializer.DataSection.cs`** — @data section generation.
+- **`AcToonSerializer.Descriptions.cs`** — Property description generation.
+
+### Type Analysis
+- **`AcToonSerializer.TopologicalSort.cs`** — Dependency-aware type ordering.
+- **`AcToonSerializer.Navigation.cs`** — Navigation property discovery.
+- **`AcToonSerializer.ForeignKeys.cs`** — Foreign key relationship detection.
+- **`AcToonSerializer.Validation.cs`** — Output validation.
+- **`AcToonSerializer.Placeholders.cs`** — Placeholder value generation.
+
+### Attributes & Metadata
+- **`AcToonSerializer.Attributes.cs`** — Attribute processing.
+- **`AcToonSerializer.AttributeExtraction.cs`** — Attribute value extraction.
+- **`ToonDescriptionAttribute.cs`** — Per-property description attribute.
+- **`AcNavigationPropertyInfo.cs`** — Navigation property metadata.
+- **`ToonTypeRelation.cs`** — Type relationship tracking (inheritance, interfaces).
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `Mode` | Full | Full/MetaOnly/DataOnly |
+| `UseIndentation` | true | Readability control |
+| `UseInlineTypeHints` | false | Type hints in data section |
+| `UseInlineComments` | false | Comments in data section |
+| `ShowCollectionCount` | true | Collection sizes |
+| `UseMultiLineStrings` | true | Triple-quote long strings |
+| `UseEnhancedMetadata` | true | Rich property metadata |
+| `OmitDefaultValues` | true | Skip null/default values |
+| `WriteTypeNames` | true | Root type names in data |
+
+**Presets:** `Default`, `MetaOnly`, `DataOnly`, `Compact`, `Verbose`.
+
+## Dependencies
+
+- Base classes from parent `Serializers/` folder
+- Expression utilities from `Expressions/` folder (for queryable serialization)
+
+---
+
+> **LLM Maintenance:** If you modify code in this folder, update this README to reflect the changes. If you notice the README content does not match the current code, automatically update the README to match the code.
--- a/AyCode.Database.Tests.Internal/AyCode.Database.Tests.Internal.csproj
+++ b/AyCode.Database.Tests.Internal/AyCode.Database.Tests.Internal.csproj
@ -18,15 +18,15 @@
 	</ItemGroup>

 	<ItemGroup>
-		<PackageReference Include="coverlet.collector" Version="6.0.4">
+		<PackageReference Include="coverlet.collector" Version="8.0.1">
 			<PrivateAssets>all</PrivateAssets>
 			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 		</PackageReference>
 		<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.11" />
 		<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.11" />
-		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
-		<PackageReference Include="MSTest.TestAdapter" Version="4.0.2" />
-		<PackageReference Include="MSTest.TestFramework" Version="4.0.2" />
+		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+		<PackageReference Include="MSTest.TestAdapter" Version="4.1.0" />
+		<PackageReference Include="MSTest.TestFramework" Version="4.1.0" />
 	</ItemGroup>

 	<ItemGroup>
--- a/AyCode.Database.Tests/AyCode.Database.Tests.csproj
+++ b/AyCode.Database.Tests/AyCode.Database.Tests.csproj
@ -11,10 +11,10 @@
 		<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.11" />
 		<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.11" />
 		<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.11" />
-		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
-		<PackageReference Include="MSTest.TestAdapter" Version="4.0.2" />
-		<PackageReference Include="MSTest.TestFramework" Version="4.0.2" />
-		<PackageReference Include="coverlet.collector" Version="6.0.4">
+		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+		<PackageReference Include="MSTest.TestAdapter" Version="4.1.0" />
+		<PackageReference Include="MSTest.TestFramework" Version="4.1.0" />
+		<PackageReference Include="coverlet.collector" Version="8.0.1">
 			<PrivateAssets>all</PrivateAssets>
 			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 		</PackageReference>
--- a/AyCode.Services.Server.Tests/AyCode.Services.Server.Tests.csproj
+++ b/AyCode.Services.Server.Tests/AyCode.Services.Server.Tests.csproj
@ -8,16 +8,16 @@
 	<Import Project="..//AyCode.Core.targets" />

 	<ItemGroup>
-		<PackageReference Include="coverlet.collector" Version="6.0.4">
+		<PackageReference Include="coverlet.collector" Version="8.0.1">
 			<PrivateAssets>all</PrivateAssets>
 			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
 		</PackageReference>
 		<PackageReference Include="Microsoft.AspNetCore.Cryptography.KeyDerivation" Version="9.0.11" />
 		<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.11" />
 		<PackageReference Include="Microsoft.Extensions.Configuration.Json" Version="9.0.11" />
-		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
-		<PackageReference Include="MSTest.TestAdapter" Version="4.0.2" />
-		<PackageReference Include="MSTest.TestFramework" Version="4.0.2" />
+		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+		<PackageReference Include="MSTest.TestAdapter" Version="4.1.0" />
+		<PackageReference Include="MSTest.TestFramework" Version="4.1.0" />
 	</ItemGroup>

 	<ItemGroup>
--- a/AyCode.Services.Tests/AyCode.Services.Tests.csproj
+++ b/AyCode.Services.Tests/AyCode.Services.Tests.csproj
@ -12,13 +12,13 @@
  <Import Project="..//AyCode.Core.targets" />

  <ItemGroup>
-    <PackageReference Include="coverlet.collector" Version="6.0.4">
+    <PackageReference Include="coverlet.collector" Version="8.0.1">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
-    <PackageReference Include="MSTest.TestAdapter" Version="4.0.2" />
-    <PackageReference Include="MSTest.TestFramework" Version="4.0.2" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
+    <PackageReference Include="MSTest.TestAdapter" Version="4.1.0" />
+    <PackageReference Include="MSTest.TestFramework" Version="4.1.0" />
  </ItemGroup>

  <ItemGroup>