- Introduced `.github/copilot-instructions.md` as the single source of truth for domain rules, conventions, and pitfalls in each solution.
- Added `CLAUDE.md` to guide Claude to read domain rules, glossary, and README before code generation.
- Updated all solution and project `README.md` files to document project purpose, structure, key files, and LLM context (Copilot/Claude/Cursor).
- Added or revised `docs/ARCHITECTURE.md`, `docs/CONVENTIONS.md`, and `docs/GLOSSARY.md` to clarify dependency graphs, naming, patterns, and terminology.
- For FruitBankHybridApp, added `docs/SCHEMA.md` (Toon format) and expanded the glossary with business/measurement terms and common traps.
- Updated all subfolder READMEs to list key files, conventions, and LLM maintenance notes.
- Ensured all documentation is cross-referenced, up-to-date, and includes explicit instructions for LLMs to keep docs in sync with code and avoid suggesting removal/rollback as a solution.
- Standardized documentation and onboarding for maintainability and LLM/code quality across all solutions.
Added comprehensive README.md documentation to every project and subfolder in the solution. Each README describes the purpose, key files, structure, dependencies, and design patterns for its area. This improves codebase navigability and maintainability, and includes a maintenance note to keep docs in sync with future code changes.
Added detailed README files for the root AyCode.Core library and each major subfolder (Compression, Consts, Enums, Extensions, Helpers, Interfaces, Loggers). Each README outlines folder purpose, key files, APIs, and critical notes, with tables and architecture diagrams where relevant. Included explicit instructions for LLM-based maintenance. This greatly improves project documentation and developer onboarding.
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.
Added HasScanWork and related methods to determine at compile time if a property requires scan work. EmitScanProp now skips code generation for properties proven to not need scan logic, improving efficiency and reducing unnecessary code output.
Major refactor of binary serialization codegen and runtime:
- Added property writer bridge methods for markerless/metadata paths
- Centralized object marker logic via new bridge methods
- Simplified SGen output: single bridge call replaces branching
- FixObj slot markers now supported in serialization/deserialization
- Refactored collection/dictionary element serialization
- Removed redundant WritePropertyMarkerless method
- Improved tests: use BinaryTypeCode constants, FixObj parsing
- Added InternalsVisibleTo for test project access
- Annotated TestSimpleClass for SGen support
Reduces generated code size, improves maintainability, and ensures correct handling of new binary format features.
Split WriteObjectProperties into markerless and metadata variants for clarity and performance. Adjust method inlining attributes to favor hot path optimization. Comment out WritePropertyValue and some AcBinaryBenchmark variants to streamline code and benchmarks. Improves maintainability and serialization efficiency.
Split hot/cold paths for polymorphic and reference-tracked object serialization. Introduce dedicated cold-path methods for polymorphic and IId reference handling, and new helpers for writing reference indices. Extract property writing loop for reuse. Simplify WriteObject and update property dispatch logic to reduce branching and clarify marker handling.
Refactored BinaryTypeCode to reserve 0..63 for FixObj slot indices, enabling direct array access for object wrappers. Introduced a new polymorphic type prefix system for properties whose runtime type differs from their declared type, with first/repeated occurrence markers and combined ref-tracking support. Unified wrapper slot caching for SGen and runtime types, improving performance and eliminating dictionary lookups in hot paths. Updated code generation, tests, and constants to use the new slot system. Added new settings and utility scripts. Overall, serialization is now faster, more robust, and extensible.
Changed default WireMode to Compact and string interning to Attribute in AcBinarySerializerOptions. Added Bash commands in settings.local.json for fetching and processing Cysharp/MemoryPack files via GitHub API and curl/python scripts.
Refactored property enumeration in AcBinarySourceGenerator to match runtime ordering and filtering using a new helper. Null checks for reference types are now unconditional in generated code. Changed default string interning mode to All. Added InternalsVisibleTo for FruitBank.Common. Writer attribute checks now only apply to source-defined types.
- Introduced IEntityComment interface for entity comments.
- Changed SignalR client message serialization to binary.
- Updated SignalResponseDataMessage docs for GZip (was Brotli).
- Refactored GetResponseData<T> for GZip decompression and improved error handling.
- Added necessary using statements for new interface and features.
- Changed default SignalR message serialization from JSON to binary.
- Updated AcSerializerType enum values: Binary=0, Json=1.
- Disabled string caching when intern table is present.
- Replaced Brotli with GZip for JSON compression in comments and logic.
- Refactored SignalResponseDataMessage deserialization for improved error handling.
Activate FastWire encoding for both serialization and deserialization, using UTF-16 and fixed-width lengths for strings. WireMode is now public and defaults to FastWire. Removes unused ObjectEnd marker, clarifying object end handling. This improves string (de)serialization speed at the cost of larger output.
Introduce ReadProperties to IGeneratedBinaryReader and generated readers, enabling property population into existing instances. Refactor ReadObject to delegate to ReadProperties. Update codegen for complex objects, collections, and dictionaries to use inline property deserialization. Improves efficiency and flexibility for parent-driven instance creation and cache management. Update documentation and comments to reflect new pattern.
Refactor serialization context to use precomputed boolean flags
(HasRefHandling, HasAllRefHandling, HasStringInterning) for faster
reference and string interning checks, replacing repeated enum
comparisons. Update source generator to emit code using these flags.
Add AcBinarySerializer.ScanOnly for isolated scan benchmarking.
Set MaxDepth in test options. Improves performance and maintainability.
Switch from caching next entry object to caching VisitIndex for write plan tracking in binary serialization. Updates TryConsumeWritePlanEntry and related logic for improved simplicity and performance. Comments revised to match new approach.
Pre-compute InternBit and reference handling flags in context to avoid repeated field access and shifting. Refactor all intern mode checks to use InternBit, improving performance and code clarity in generated code, property accessors, and scan/write passes. Optimize write plan entry access for faster serialization.
Refactored EmitReadString to use a switch for O(1) dispatch of string wire formats, improving performance and clarity. Updated comments to document the new approach and its benefits. Removed the UseGeneratedCode property from AcBinarySerializerOptions.
Optimized AcBinarySourceGenerator to emit direct code for dictionary property serialization and scanning. Added PropInfo fields for dictionary value type metadata, scan requirements, and FNV-1a hashes. Specialized code now handles string interning, complex value reference tracking, and metadata inline, reducing runtime overhead and improving performance. Fallback to runtime methods only for unsupported types.
Enable optimized codegen for Dictionary<TKey, TValue> and IDictionary<TKey, TValue> properties. The generator now analyzes key/value types and emits direct binary read loops for primitive, string, enum, and complex types with generated readers. PropInfo is extended with dictionary metadata. Improves performance and type safety by eliminating reflection and runtime type dispatch for supported dictionary types. Also refactors collection reading logic and updates dependency graph and scanning for dictionary value types.
Added compile-time cycle detection for [AcBinarySerializable] types in AcBinarySourceGenerator, reporting ACBIN001 warnings to guide reference handling. Increased depth increment for nested serialization to improve max depth enforcement. Refactored collection element depth checks for clarity. Updated tests to conditionally assign Parent and commented out a redundant assertion. Simplified slot bounds check in AcSerializerContextBase.
Detect circular references at compile time in source gen
Added DFS-based cycle detection to AcBinarySourceGenerator, reporting ACBIN001 warnings for circular reference chains among [AcBinarySerializable] types. Increased depth increment for nested serialization from +1 to +2 to improve handling of deep/circular structures. Adjusted null-check logic for collections to respect MaxDepth. Updated tests to conditionally set circular references and commented out assertions for Parent when not applicable. Minor slot bounds check fix in AcSerializerContextBase.
Changed AcBinarySerializerOptions defaults: UseMetadata is now false, UseGeneratedCode is now true. Improved IId reference tests by adding UseMetadata option, new null and reference identity assertions, and refactored assertion order for clarity. These changes ensure more robust test coverage and align default serializer behavior with expected usage.
Refactor test methods to use [DataRow] for parameterized testing of UseSgen and UseMeta combinations. Dynamically set AcBinarySerializerOptions in tests and add diagnostic output. Swap default values in AcBinarySerializerOptions: UseMetadata is now true, UseGeneratedCode is now false. This affects default serializer behavior across tests and usages.
- Emit special serialization logic for properties declared as System.Object, using value.GetType() and writing type name metadata for correct polymorphic deserialization.
- Add IsObjectDeclaredType to PropInfo to support this logic.
- Update scan pass to use runtime type for object properties.
- Adjust IId reference test to ensure circular reference coverage.
- Default UseGeneratedCode to true in serializer options.
Enable serialization of runtime type info for System.Object properties using new ObjectWithTypeName markers. Serializer now writes the runtime type name inline; deserializer resolves and instantiates the correct type. Added IsObjectDeclaredType property for detection, refactored WriteObject methods, and registered new deserialization logic. This ensures robust polymorphic (de)serialization even without metadata. Also includes minor cleanup of unused usings.
Introduce new test models for circular refs, update tests to stress reference handling, and enhance deserializer to support ObjectRefFirst/WithMetadataRefFirst type codes. Fix intern cache index assignment, track generated readers in TypeMetadataWrapper, and disable UseGeneratedCode by default. Update benchmarks for reliability and diagnostics. These changes strengthen reference resolution, circular ref support, and performance.
- Refined collection kind mapping: IList<T>/IReadOnlyList<T> now treated as "IndexedCollection" for codegen, distinct from List<T>
- Generated code uses CollectionsMarshal.AsSpan for List<T> iteration, improving performance
- Updated generated read/write logic for collections to match new distinctions
- Added System.Runtime.InteropServices to generated code for span support
- Increased test iteration count in Program.cs for more robust benchmarks
- Enabled source-generated binary serialization for all test models by setting [AcBinarySerializable(true)]
Added capacity-check-free "unsafe" write methods to BinarySerializationContext for all primitive and specialized types, plus ReserveCapacity for bulk writes. Introduced MinWriteSize property in BinarySerializeTypeMetadata to precompute worst-case buffer requirements per type. Improved documentation and added Copilot instructions to discourage code removal as a solution.
Introduced source-generated binary readers for all serializable types, alongside writers. Added IGeneratedBinaryReader interface and registry for fast lookup in deserializer. Generated readers eliminate runtime overhead by directly reading properties, bypassing wrapper and delegate calls. Updated test models to disable metadata for markerless mode. Integrated fast path in deserializer for improved performance.
Refactored binary serializer to use a single wrapper slot per SGen type for both metadata registration and reference tracking. Removed slot-based IdentityMap arrays and scan pass tracking methods, replacing them with wrapper-based TryTrack logic. Updated generated code to use wrapper slots for all slot-based operations. Changed UseMetadata registration to use a MetadataSeen flag on the wrapper. Added fast slot-indexed wrapper access in context base. Default UseMetadata option is now false. Simplifies and optimizes SGen tracking, reducing dictionary lookups and unifying tracking logic.
- Set `[AcBinarySerializable(true)]` on all SharedTestModels types
- Default `UseMetadata` to true for property hash footer
- Reset slotted ID maps and cache indices in serializer context
- Reduce test iterations for DEBUG builds to speed up runs
- Add debug comments in context `Clear()` method
Added compile-time scan requirement flags to SerializableClassInfo and PropInfo, and implemented recursive analysis to determine if scan work is needed for reference tracking and string interning. Updated code generation to emit scan code only when necessary, with runtime guards based on compile-time analysis. Changed AcBinarySerializerOptions.UseMetadata default to false. Increased JIT wait in Program.cs for more reliable benchmarking. These changes reduce unnecessary scan calls and improve performance.
Adds EnableMetadataFeature to [AcBinarySerializable], allowing types to opt out of inline metadata even when global UseMetadata is enabled. Source generator, serializer, and deserializer now respect this flag for child and element types. Default UseMetadata is set to true. Enables fine-grained control over serialization overhead and compatibility.
AcBinarySourceGenerator now reads feature flags from [AcBinarySerializable], enabling selective code generation for ID tracking, reference handling, and string interning. Property ordering is always alphabetical, removing "Id"-first sorting for IId types. Reference tracking code is only emitted when features are enabled. TypeMetadataBase and AcBinarySerializer runtime logic now respect these flags. Default options updated: ReferenceHandlingMode is All, UseMetadata is false. Test models explicitly disable all features. Comments and code structure improved for clarity.
Implements a fully source-generated scan pass for duplicate/reference tracking in SGen binary serialization. The generator now emits ScanObject and ScanForDuplicates methods for each writer, handling null/depth checks, slot-based ref tracking (by Id or object hash), and recursive property scanning (strings, complex types, collections). String interning and reference tracking are feature-flagged via attributes. The runtime scan path now delegates to generated code when available, eliminating reflection and delegate overhead. Adds slot-based IdentityMap arrays to the serialization context for efficient duplicate detection. Also updates metadata, attributes, and test stubs to support these features.
Implements inline type metadata emission in the source generator, matching runtime TypeMetadataBase. Computes FNV-1a hashes for type and property names, stores them in generated code, and emits metadata when UseMetadata is enabled. Adds per-type slot allocation and tracking for first/repeated metadata writes. Removes runtime fallback for UseMetadata, ensuring all logic is handled inline. Updates property filtering/order to match runtime, and optimizes Int32/Int64 skip logic. Thread-safe slot allocation is used for metadata tracking.
Improve generated serialization code to match runtime behavior for metadata emission and reference tracking. Markerless types now respect UseMetadata, ensuring type markers are written when required. Ref tracking guards for IId and non-IId types are unified to match scan pass logic. Generated writers are always used when available. Default UseMetadata is now true for consistent metadata output.
- Generate writers for nested types using flat class names (Outer_Inner_Leaf) to ensure uniqueness and validity.
- Apply property filters in generated code for all non-markerless properties, matching runtime behavior.
- Emit skip labels for each property in generated code for correct control flow.
- Remove PropertyFilter check from IsDirectObjectWrite; generated code now handles filtering.
- Change default ReferenceHandlingMode to All.
- Make BinaryPropertyFilterContext constructor public.
- Increase release warmup iterations in Program.cs from 3000 to 5000.
All FastWire-related code paths, fields, and options have been commented out in both AcBinarySerializer and AcBinaryDeserializer. This removes support for fixed-width integer and UTF-16 encoding, forcing the use of compact VarInt and UTF-8 encoding exclusively. The WireMode option is also commented out, so FastWire can no longer be selected. This change reduces output size and simplifies the codebase, but may impact serialization/deserialization speed for some scenarios.
Introduces a WireMode enum to select between Compact (VarInt + UTF-8) and Fast (fixed-width + UTF-16) wire formats for binary serialization. Updates AcBinarySerializerOptions to include a WireMode property (default: Fast). Serialization and deserialization logic now conditionally uses fixed-width or variable-length encoding for integers and strings based on the selected mode, enabling a tradeoff between output size and performance.
Extend serializer/deserializer to efficiently handle arrays and lists of short, ushort, uint, ulong, sbyte, char, DateTimeOffset, and TimeSpan. Improve enum collection handling and support ICollection-based collections. Update source generator to distinguish between indexable and counted collections, generating optimal serialization code for each. These changes enhance performance and coverage for a broader range of collection types.
Enhance AcBinarySourceGenerator to emit direct write loops for List<T>/T[] where T is a complex type with a generated writer. This bypasses per-element runtime dispatch, improving serialization performance. PropInfo now tracks collection element metadata, enabling this optimization. Falls back to generic handling for other cases.
- Always write length prefix before ASCII and UTF-8 strings in AcBinarySerializer for consistency and correctness.
- Increase release warmup iterations from 2000 to 3000 in Program.cs.
Introduces direct object write mode in source-generated binary serialization, allowing generated writers to bypass the runtime WriteObject pipeline for eligible complex properties. Adds detection of generated writer presence and IId<T> implementation, inlines reference tracking logic, and replaces .GetType() with typeof() for type safety. String interning attribute detection and precomputed interning flags ensure safe cursor alignment. Expands PropInfo structure and enables fast path for all generated writers. Improves serialization performance, correctness, and reduces runtime overhead. Adds new web fetch domains to settings.
Add WriteObjectGenerated to AcBinarySerializer for direct, efficient serialization of complex objects in source-generated code. Update AcBinarySourceGenerator to use this method, including proper handling of nullable properties, to reduce runtime overhead and avoid unnecessary type dispatch.
Refactor AcBinarySerializer to use ReadOnlySpan<T> for bulk writing of primitive arrays and List<T>, replacing multiple specialized methods with a single TryWritePrimitiveCollection. This improves efficiency and reduces code duplication. Change default string interning mode to Attribute (opt-in). Update generated code path to allow reference tracking but not string interning. Adjust benchmarks to test correct serializer options. Reorder options for clarity.
- Integrated MemoryPack as a serializer in the benchmark suite
- Added [MemoryPackable] and [MemoryPackIgnore] to test models
- Enabled AcBinary source generation by default
- Updated benchmark app to include MemoryPack and focus on key serializers
- Added MemoryPack NuGet references to projects
- Refactored AcBinarySerializer.WriteString flag handling
Introduce [AcStringIntern] for selective string interning on properties. Update serializer to use a per-property eligibility flag, improving efficiency and control over which string fields participate in interning during binary serialization. Update test models and internal context accordingly.
Loretta
Adam