diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index db4ac79..98e8cce 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -22,3 +22,6 @@ 10. Do not suggest removal/rollback as a solution — find a fix for the problem. 11. Extension methods over instance methods for CRUD operations (see DbSets pattern). 12. Session pattern for reads, Transaction pattern for writes (see DataLayers). +13. **Target framework is net9.0** (set in AyCode.Core.targets). The SourceGenerator targets netstandard2.0. Consuming projects (AyCode.Blazor, FruitBankHybridApp UI) may target net10.0 but reference AyCode.Core DLLs built as net9.0. +14. **No redundant code** — before writing new logic, search for existing methods. Reuse or extract shared logic into smaller methods rather than duplicating. If an existing method does most of what you need, split it into composable parts. +15. **Keep all .md files in sync** — when you modify code, update any affected .md file (README.md, docs/, GLOSSARY, ARCHITECTURE, CONVENTIONS, BINARY_FORMAT, SCHEMA, etc.). If you notice any .md content does not match the current code, fix it automatically. diff --git a/AyCode.Benchmark/README.md b/AyCode.Benchmark/README.md index 0980147..3e8fdfd 100644 --- a/AyCode.Benchmark/README.md +++ b/AyCode.Benchmark/README.md @@ -21,7 +21,3 @@ BenchmarkDotNet-based performance benchmarking console app. Compares AcBinary se | `BenchmarkDotNet` | Benchmarking framework | | `MessagePack` | Serialization comparison target | | `MongoDB.Bson` | BSON comparison target | - ---- - -> **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. diff --git a/AyCode.Core.Serializers.Console/README.md b/AyCode.Core.Serializers.Console/README.md index b19aef4..1827386 100644 --- a/AyCode.Core.Serializers.Console/README.md +++ b/AyCode.Core.Serializers.Console/README.md @@ -28,7 +28,3 @@ Standalone benchmark console application for comparing serializer performance. T | `MemoryPack` | Competitor benchmark | | `MessagePack` | Competitor benchmark | | `Newtonsoft.Json` | Competitor benchmark | - ---- - -> **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. diff --git a/AyCode.Core.Serializers.SourceGenerator/README.md b/AyCode.Core.Serializers.SourceGenerator/README.md index f0444b0..fdb949d 100644 --- a/AyCode.Core.Serializers.SourceGenerator/README.md +++ b/AyCode.Core.Serializers.SourceGenerator/README.md @@ -28,7 +28,3 @@ Disabled features eliminate corresponding code blocks from generated output (zer |---|---| | `Microsoft.CodeAnalysis.CSharp` | Roslyn syntax/semantic APIs | | `Microsoft.CodeAnalysis.Analyzers` | Analyzer best practices | - ---- - -> **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. diff --git a/AyCode.Core.Server/Loggers/README.md b/AyCode.Core.Server/Loggers/README.md index 70b14f7..be0ebd7 100644 --- a/AyCode.Core.Server/Loggers/README.md +++ b/AyCode.Core.Server/Loggers/README.md @@ -5,7 +5,3 @@ Provides a singleton `GlobalLogger` for application-wide logging with multiple s ## Key Files - **`GlobalLogger.cs`** — Singleton static logger that delegates to `AcLoggerBase`. Supports category names, caller member tracking, and configurable `LogLevel` and `AppType`. - ---- - -> **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. diff --git a/AyCode.Core.Server/README.md b/AyCode.Core.Server/README.md index 547350a..a5c6dc5 100644 --- a/AyCode.Core.Server/README.md +++ b/AyCode.Core.Server/README.md @@ -21,7 +21,3 @@ Server-side extension of AyCode.Core. Provides server-specific implementations t | `MessagePack` | MessagePack serialization | | `Newtonsoft.Json` | JSON serialization | | `Microsoft.Extensions.Logging.Abstractions` | Logging abstractions | - ---- - -> **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. diff --git a/AyCode.Core.Tests.Internal/Entities/README.md b/AyCode.Core.Tests.Internal/Entities/README.md index ed38f42..f11ca33 100644 --- a/AyCode.Core.Tests.Internal/Entities/README.md +++ b/AyCode.Core.Tests.Internal/Entities/README.md @@ -16,7 +16,3 @@ Concrete entity implementations inheriting from AyCode.Entities abstract generic ## Relationships User ↔ Company (many-to-many via UserToCompany), User → Profile → Address (one-to-one chain), EmailMessage → EmailRecipient (one-to-many). - ---- - -> **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. diff --git a/AyCode.Core.Tests.Internal/README.md b/AyCode.Core.Tests.Internal/README.md index cfe89c1..4f7adfb 100644 --- a/AyCode.Core.Tests.Internal/README.md +++ b/AyCode.Core.Tests.Internal/README.md @@ -15,7 +15,3 @@ Concrete entity implementations for database integration testing. Exposes types | `MSTest` | Test framework | | `AyCode.Core.Tests` | Shared test utilities | | `AyCode.Entities` / `AyCode.Entities.Server` | Abstract entity base classes | - ---- - -> **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. diff --git a/AyCode.Core.Tests/Compression/README.md b/AyCode.Core.Tests/Compression/README.md index 027143f..9e0593c 100644 --- a/AyCode.Core.Tests/Compression/README.md +++ b/AyCode.Core.Tests/Compression/README.md @@ -5,7 +5,3 @@ GZip compression utility tests. ## Key Files - **`GzipHelperTests.cs`** — Tests GzipHelper.Compress(), DecompressToString(), DecompressToRentedBuffer() (ArrayPool), IsGzipCompressed() (magic byte detection). - ---- - -> **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. diff --git a/AyCode.Core.Tests/GeneratedWriters/README.md b/AyCode.Core.Tests/GeneratedWriters/README.md index daf1a8d..f04beab 100644 --- a/AyCode.Core.Tests/GeneratedWriters/README.md +++ b/AyCode.Core.Tests/GeneratedWriters/README.md @@ -5,7 +5,3 @@ Hand-written examples of the code pattern that the AcBinarySerializable source g ## Key Files - **`TestOrderWriter.cs`** — Example IGeneratedBinaryWriter: direct property access (no reflection), alphabetical order, value types inline, complex types delegate to runtime. Demonstrates ICache-friendly pattern (~500B vs 27KB runtime). - ---- - -> **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. diff --git a/AyCode.Core.Tests/README.md b/AyCode.Core.Tests/README.md index 9d3509e..c3d81b0 100644 --- a/AyCode.Core.Tests/README.md +++ b/AyCode.Core.Tests/README.md @@ -25,7 +25,3 @@ MSTest unit tests for AyCode.Core serialization, compression, and utilities. Cov | `MessagePack` | Serialization comparison | | `MemoryPack` | Serialization comparison | | `MongoDB.Bson` | BSON comparison | - ---- - -> **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. diff --git a/AyCode.Core.Tests/Serialization/README.md b/AyCode.Core.Tests/Serialization/README.md index 7d997a5..df865cd 100644 --- a/AyCode.Core.Tests/Serialization/README.md +++ b/AyCode.Core.Tests/Serialization/README.md @@ -30,7 +30,3 @@ Comprehensive test suite for binary and JSON serialization: round-trips, referen - **`GeneratedSerializerIntegrationTests.cs`** — Verifies generated writer types implement IGeneratedBinaryWriter. - **`QuickBenchmark.cs`** — Performance comparison: AcBinary vs MessagePack. - **`AcSerializerTestHelper.cs`** — Factory methods for test data. - ---- - -> **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. diff --git a/AyCode.Core.Tests/TestModels/README.md b/AyCode.Core.Tests/TestModels/README.md index be2f502..89d4903 100644 --- a/AyCode.Core.Tests/TestModels/README.md +++ b/AyCode.Core.Tests/TestModels/README.md @@ -11,7 +11,3 @@ Shared test entities, enums, data factories, and SignalR test infrastructure. Us - **`TestDataFactory.cs`** — Centralized factory with ID sequencing: CreateTag(), CreateCategory(), CreateUser(), CreateOrder(), CreateOrderItem(). - **`SignalRTestInfrastructure.cs`** — SignalRMessageFactory, DTOs, CommonSignalRTags, SignalRBenchmarkData. - **`TestLogger.cs`** — Logger with capture for assertions: HasErrorLogs, HasWarningLogs, GetErrorMessages(). - ---- - -> **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. diff --git a/AyCode.Core.sln b/AyCode.Core.sln index 54c8305..e4df6cf 100644 --- a/AyCode.Core.sln +++ b/AyCode.Core.sln @@ -1,4 +1,4 @@ - + Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio Version 18 VisualStudioVersion = 18.0.11222.15 @@ -44,6 +44,9 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution AyCode.Core.targets = AyCode.Core.targets RunQuickBenchmark.bat = RunQuickBenchmark.bat RunQuickBenchmark.ps1 = RunQuickBenchmark.ps1 + .github\copilot-instructions.md = .github\copilot-instructions.md + CLAUDE.md = CLAUDE.md + README.md = README.md ToonExtendedInfo.txt = ToonExtendedInfo.txt EndProjectSection EndProject @@ -55,6 +58,14 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AyCode.Core.Serializers.Sou EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AyCode.Core.Serializers.Console", "AyCode.Core.Serializers.Console\AyCode.Core.Serializers.Console.csproj", "{6AB7CE43-3C98-1D54-9ABD-E5E9364541E7}" EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{D4B2E9F1-A6C3-4F7E-8D5B-3E2A1C4F6B8D}" + ProjectSection(SolutionItems) = preProject + docs\ARCHITECTURE.md = docs\ARCHITECTURE.md + docs\BINARY_FORMAT.md = docs\BINARY_FORMAT.md + docs\CONVENTIONS.md = docs\CONVENTIONS.md + docs\GLOSSARY.md = docs\GLOSSARY.md + EndProjectSection +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU diff --git a/AyCode.Core/Compression/README.md b/AyCode.Core/Compression/README.md index ac9f9a4..d1903e6 100644 --- a/AyCode.Core/Compression/README.md +++ b/AyCode.Core/Compression/README.md @@ -22,7 +22,3 @@ Three compression algorithms with a unified static API. All implementations use - `System.IO.Compression` (Brotli, GZip) - `System.Buffers` (ArrayPool) - ---- - -> **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. diff --git a/AyCode.Core/Consts/README.md b/AyCode.Core/Consts/README.md index 350026e..56edf88 100644 --- a/AyCode.Core/Consts/README.md +++ b/AyCode.Core/Consts/README.md @@ -9,7 +9,3 @@ Project-wide constants, error codes, environment configuration, regex patterns, - **`AcErrorCode.cs`** — Byte enum with 60+ error codes (0=UnknownError ... 255=Unset). Used across the entire API layer. - **`AcRegExpression.cs`** — Compile-time generated regex via `[GeneratedRegex]`: `EmailRegex()` (RFC-compliant), `PhoneNumberRegex()` (E.164 format). - **`AcValidate.cs`** — Input validation methods returning `bool` + `out AcErrorCode`: email, password, username, player name, phone, domain, user token format checks. - ---- - -> **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. diff --git a/AyCode.Core/Enums/README.md b/AyCode.Core/Enums/README.md index a8cb63d..a3ed084 100644 --- a/AyCode.Core/Enums/README.md +++ b/AyCode.Core/Enums/README.md @@ -7,7 +7,3 @@ Shared enums used across the platform. All are `byte`-based for compact serializ - **`AppType.cs`** — Identifies application type: None(0), Server(1), Relay(5), Game(10), Web(15), Mobile(20), Dissonance(25), TestUnit(255). - **`MessageContextType.cs`** — Message routing context: Unset(0), System(5), Private(10), Group(15), Transfer(20), Product(25), Company(30). - **`TrackingState.cs`** — Entity change tracking: None(0), Get(1), GetAll(2), Add(3), Update(4), Remove(5). - ---- - -> **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. diff --git a/AyCode.Core/Extensions/README.md b/AyCode.Core/Extensions/README.md index a9622ae..fb36af0 100644 --- a/AyCode.Core/Extensions/README.md +++ b/AyCode.Core/Extensions/README.md @@ -16,7 +16,3 @@ Extension methods for collections, serialization, and common utilities. - **`EnumExtensions.cs`** — `GetDisplayName()` via `DisplayAttribute` reflection. - **`ExceptionExtensions.cs`** — `GetCategoryAndMemberNameFromStackTraceString()` for structured caller info extraction. - **`GuidExtensions.cs`** — `IsNullOrEmpty()` for `Guid` and `Guid?` with `[NotNullWhen]` annotations. - ---- - -> **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. diff --git a/AyCode.Core/Helpers/README.md b/AyCode.Core/Helpers/README.md index e790609..9ca67e0 100644 --- a/AyCode.Core/Helpers/README.md +++ b/AyCode.Core/Helpers/README.md @@ -17,7 +17,3 @@ Utility classes for token generation, observable collections, type metadata, pas - **`PasswordHasher.cs`** — PBKDF2-HMAC-SHA512 with 10,000 iterations. **Critical: do not modify `GenerateDynamicSalt()` or `GenerateFinallySalt()` — login will break.** Format: `$bcrypt$v=1$salt=...base64...$hash=...base64...` - **`PropertyHelper.cs`** — `CopyPublicValueTypeProperties()` for DTO/entity mapping via reflection. - **`TaskHelper.cs`** — `WaitTo()`/`WaitToAsync()` (poll predicate with timeout using `PeriodicTimer`), `Forget()` (fire-and-forget), `RunOnThreadPool()`. - ---- - -> **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. diff --git a/AyCode.Core/Interfaces/README.md b/AyCode.Core/Interfaces/README.md index 3a91d21..f94c102 100644 --- a/AyCode.Core/Interfaces/README.md +++ b/AyCode.Core/Interfaces/README.md @@ -10,7 +10,3 @@ Core interfaces used throughout the framework. - `IForeignCollection` — generic collection navigation marker (`T : IEnumerable`) - `IForeignCollection` — non-generic variant - **`IAcSerializableToJson.cs`** — Empty marker interface tagging types that can serialize to JSON. Used for query-time type filtering. - ---- - -> **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. diff --git a/AyCode.Core/Loggers/README.md b/AyCode.Core/Loggers/README.md index d122cce..b25176a 100644 --- a/AyCode.Core/Loggers/README.md +++ b/AyCode.Core/Loggers/README.md @@ -32,7 +32,3 @@ IAcLogWriterBase ### Supporting - **`IAcLogItemClient.cs`** — Structured log item DTO for remote transmission. - **`LogLevel.cs`** — Byte enum: Detail(0), Trace(5), Debug(10), Info(15), Suggest(17), Warning(20), Error(25), Disabled(255). **Must match the database LogLevel table.** - ---- - -> **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. diff --git a/AyCode.Core/README.md b/AyCode.Core/README.md index c7e86f3..793b127 100644 --- a/AyCode.Core/README.md +++ b/AyCode.Core/README.md @@ -30,7 +30,3 @@ Core library for the AyCode platform. Targets .NET 10. Provides serialization (B | `Newtonsoft.Json` | JSON serialization (legacy, alongside System.Text.Json) | | `Microsoft.Extensions.Configuration.*` | appsettings.json + environment variable support | | `Microsoft.Extensions.Logging.Abstractions` | Logging abstractions | - ---- - -> **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. diff --git a/AyCode.Core/Serializers/Attributes/README.md b/AyCode.Core/Serializers/Attributes/README.md index 03a70f3..8f330f0 100644 --- a/AyCode.Core/Serializers/Attributes/README.md +++ b/AyCode.Core/Serializers/Attributes/README.md @@ -21,7 +21,3 @@ public class MyType - 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. diff --git a/AyCode.Core/Serializers/Binaries/README.md b/AyCode.Core/Serializers/Binaries/README.md index 5b2f9c7..a7e3894 100644 --- a/AyCode.Core/Serializers/Binaries/README.md +++ b/AyCode.Core/Serializers/Binaries/README.md @@ -27,6 +27,8 @@ The serializer is generic over `TOutput` for strategy selection (`ArrayBinaryOut | 144+ | **Headers** — Metadata, RefHandling, CacheCount flags | | 192–255 | **Tiny ints** — Single-byte encoding for values -16 to 47 | +For the complete wire format specification (encoding rules, header format, interning protocol), see [`../../../../docs/BINARY_FORMAT.md`](../../../../docs/BINARY_FORMAT.md). + ## Key Files ### Serialization @@ -75,22 +77,25 @@ The serializer is generic over `TOutput` for strategy selection (`ArrayBinaryOut ## 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 | +| Option | Type | Default | Wire format impact | +|---|---|---|---| +| `WireMode` | Compact/Fast | Compact | Compact: VarInt+UTF-8. Fast: fixed-width+UTF-16 memcpy | +| `ReferenceHandling` | None/OnlyId/All | All | Controls scan pass, `ObjectRefFirst(70)`/`ObjectRef(65)` markers | +| `UseMetadata` | bool | false | Adds FNV-1a property hashes, enables `ObjectWithMetadata(69)` markers | +| `UseStringInterning` | None/Attribute/All | Attribute | Controls `StringInternFirst(94)`/`StringInterned(92)` deduplication | +| `MaxDepth` | byte | 255 | Nested objects beyond depth written as `Null(76)` | +| `UseCompression` | None/Block/BlockArray | None | Post-serialization LZ4 compression (transparent wrapper) | +| `PropertyFilter` | delegate? | null | Exclude properties from stream entirely | +| `ThrowOnCircularReference` | bool | true | Cycle detection behavior when ref handling enabled | -**Presets:** `Default`, `FastMode`, `ShallowCopy`, `WasmOptimized`. +**Key rule:** `ReferenceHandling=None` + `UseStringInterning=None` = no scan pass (fastest, single-phase). + +**Presets:** `Default` (All refs, Attribute interning), `FastMode` (no refs, no interning), `ShallowCopy` (depth=0), `WasmOptimized` (+string caching). + +For detailed option documentation with code branches and interactions, see [`../../../../docs/BINARY_FORMAT.md`](../../../../docs/BINARY_FORMAT.md#configuration-options). ## 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. diff --git a/AyCode.Core/Serializers/Expressions/README.md b/AyCode.Core/Serializers/Expressions/README.md index 0552299..94ff961 100644 --- a/AyCode.Core/Serializers/Expressions/README.md +++ b/AyCode.Core/Serializers/Expressions/README.md @@ -19,7 +19,3 @@ Serialization support for LINQ Expression trees and `IQueryable` objects. Conver - `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. diff --git a/AyCode.Core/Serializers/Jsons/README.md b/AyCode.Core/Serializers/Jsons/README.md index 20dc267..d8b2437 100644 --- a/AyCode.Core/Serializers/Jsons/README.md +++ b/AyCode.Core/Serializers/Jsons/README.md @@ -46,7 +46,3 @@ Custom JSON serialization/deserialization built on `System.Text.Json`'s `Utf8Jso - 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. diff --git a/AyCode.Core/Serializers/README.md b/AyCode.Core/Serializers/README.md index f5468a3..2fa239f 100644 --- a/AyCode.Core/Serializers/README.md +++ b/AyCode.Core/Serializers/README.md @@ -71,7 +71,3 @@ AcSerializerContextBase | `None` | No tracking, fastest path | | `OnlyId` | Only `IId` 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. diff --git a/AyCode.Core/Serializers/Toons/README.md b/AyCode.Core/Serializers/Toons/README.md index 7b9e215..f1b078f 100644 --- a/AyCode.Core/Serializers/Toons/README.md +++ b/AyCode.Core/Serializers/Toons/README.md @@ -74,7 +74,3 @@ Token-Oriented Object Notation (Toon) — an LLM-optimized serialization format - 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. diff --git a/AyCode.Database.Tests.Internal/README.md b/AyCode.Database.Tests.Internal/README.md index e7128c1..ceeb5d9 100644 --- a/AyCode.Database.Tests.Internal/README.md +++ b/AyCode.Database.Tests.Internal/README.md @@ -12,7 +12,3 @@ Concrete database integration tests using entity implementations from AyCode.Cor - **`DatabaseTestBase.cs`** — Concrete [TestClass] with Setup/TearDown, implements AcDatabaseTestBase. - **`appsettings.json`** — Test database connection configuration. - ---- - -> **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. diff --git a/AyCode.Database.Tests.Internal/Users/README.md b/AyCode.Database.Tests.Internal/Users/README.md index 32c82fc..93bcfcd 100644 --- a/AyCode.Database.Tests.Internal/Users/README.md +++ b/AyCode.Database.Tests.Internal/Users/README.md @@ -7,7 +7,3 @@ Concrete user database test implementations with real EF Core DbContext and DAL. - **`UserDbContext.cs`** — Sealed `AcUserDbContextBase` with 8 concrete entity types, lazy loading proxies, detailed EF errors. - **`UserDal.cs`** — Sealed `AcUserDalBase` providing concrete DAL for tests. - **`UserDalTests.cs`** — Concrete tests: GetUserByEmail, GetUserById, AddUser (with profile + address). Currently disabled. - ---- - -> **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. diff --git a/AyCode.Database.Tests/README.md b/AyCode.Database.Tests/README.md index 29d817c..5060cc7 100644 --- a/AyCode.Database.Tests/README.md +++ b/AyCode.Database.Tests/README.md @@ -13,7 +13,3 @@ MSTest base classes for database layer testing. Provides abstract test foundatio - **`GlobalUsings.cs`** — Global MSTest using. - **`AcDatabaseTestModelBase.cs`** — Generic base: pooled DAL access or direct DbContext access. - **`AcDatabaseTestBase.cs`** — Abstract test class with `DatabaseExistsTest()` connectivity validation. - ---- - -> **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. diff --git a/AyCode.Database.Tests/Users/README.md b/AyCode.Database.Tests/Users/README.md index a6e1175..9cb4fe3 100644 --- a/AyCode.Database.Tests/Users/README.md +++ b/AyCode.Database.Tests/Users/README.md @@ -5,7 +5,3 @@ Abstract base for comprehensive user DAL testing. ## Key Files - **`AcUserDalTestBase.cs`** — 8 generic type parameters. Tests: GetUserById (validates nested profile/address), GetUserByEmail, GetUserModelDtoDetailById, GetUserByEmailAsync, AddUserTest (full object graph with profile + address, then cleanup). - ---- - -> **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. diff --git a/AyCode.Database/DataLayers/README.md b/AyCode.Database/DataLayers/README.md index e5f8a67..05a6e68 100644 --- a/AyCode.Database/DataLayers/README.md +++ b/AyCode.Database/DataLayers/README.md @@ -13,7 +13,3 @@ Generic Data Access Layer (DAL) abstraction with mutex-protected session/transac | Folder | Purpose | |---|---| | [`Users/`](Users/README.md) | User-specific DAL with authentication and CRUD | - ---- - -> **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. diff --git a/AyCode.Database/DataLayers/Users/README.md b/AyCode.Database/DataLayers/Users/README.md index b9de90f..5292a73 100644 --- a/AyCode.Database/DataLayers/Users/README.md +++ b/AyCode.Database/DataLayers/Users/README.md @@ -6,7 +6,3 @@ User-specific DAL extending AcDalBase with authentication, CRUD, and email valid - **`AcUserDalBase.cs`** — GetUserById/ByEmail, AddUser, RemoveUser, UpdateUser, AuthenticateUser (with password verification + refresh token), GetUserModelDto (sync + async). - **`AcUserDalExtension.cs`** — Reserved for future user DAL extensions (currently contains commented legacy code). - ---- - -> **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. diff --git a/AyCode.Database/DbContexts/Loggers/README.md b/AyCode.Database/DbContexts/Loggers/README.md index 91cb2c8..325ca68 100644 --- a/AyCode.Database/DbContexts/Loggers/README.md +++ b/AyCode.Database/DbContexts/Loggers/README.md @@ -6,7 +6,3 @@ Logger-specific EF Core DbContext with NoTracking query behavior for read perfor - **`IAcLoggerDbContextBase.cs`** — Interface for log item DbSet. - **`AcLoggerDbContextBase.cs`** — Implementation with NoTracking default, optimized for log reads. - ---- - -> **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. diff --git a/AyCode.Database/DbContexts/README.md b/AyCode.Database/DbContexts/README.md index 758bb1b..a0de686 100644 --- a/AyCode.Database/DbContexts/README.md +++ b/AyCode.Database/DbContexts/README.md @@ -15,7 +15,3 @@ EF Core DbContext base classes with automatic timestamp management, UTC conversi |---|---| | [`Users/`](Users/README.md) | User-specific DbContext with DbSets for User, Profile, Address, Company, UserToken, EmailMessage | | [`Loggers/`](Loggers/README.md) | Logger DbContext with NoTracking for read performance | - ---- - -> **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. diff --git a/AyCode.Database/DbContexts/Users/README.md b/AyCode.Database/DbContexts/Users/README.md index 67b37f3..f1608c3 100644 --- a/AyCode.Database/DbContexts/Users/README.md +++ b/AyCode.Database/DbContexts/Users/README.md @@ -7,7 +7,3 @@ User-specific EF Core DbContext definitions. - **`IAcUserDbContextBase.cs`** — Interface declaring DbSets for Users, Profiles, Addresses, Companies, UserTokens, EmailMessages. - **`AcUserDbContextBase.cs`** — Implementation with lazy loading, auto timestamps, and entity configurations. - **`IAcUserTokenDbContextBase.cs`** — Interface for UserToken DbSet access. - ---- - -> **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. diff --git a/AyCode.Database/DbSets/Addresses/README.md b/AyCode.Database/DbSets/Addresses/README.md index 22c34bf..e3fb7d9 100644 --- a/AyCode.Database/DbSets/Addresses/README.md +++ b/AyCode.Database/DbSets/Addresses/README.md @@ -6,7 +6,3 @@ Address entity CRUD operations. - **`IAcAddressDbSetBase.cs`** — Address DbSet interface. - **`AcAddressDbSetExtensions.cs`** — GetAddressById, UpdateAddress, RemoveAddress. - ---- - -> **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. diff --git a/AyCode.Database/DbSets/Companies/README.md b/AyCode.Database/DbSets/Companies/README.md index f151dba..fb822b6 100644 --- a/AyCode.Database/DbSets/Companies/README.md +++ b/AyCode.Database/DbSets/Companies/README.md @@ -6,7 +6,3 @@ Company/ServiceProvider CRUD with profile and user-to-company relationship manag - **`IAcCompanyDbSetBase.cs`** — Hierarchical interfaces with Profile and Address relations. - **`AcCompanyDbSetExtensions.cs`** — AddCompany, UpdateCompany, RemoveCompany, GetCompanyById, GetCompaniesByOwnerId. Handles profile and user-to-company relationships. - ---- - -> **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. diff --git a/AyCode.Database/DbSets/Loggers/README.md b/AyCode.Database/DbSets/Loggers/README.md index c6e02d0..a815a47 100644 --- a/AyCode.Database/DbSets/Loggers/README.md +++ b/AyCode.Database/DbSets/Loggers/README.md @@ -5,7 +5,3 @@ Log item DbSet interface. ## Key Files - **`IAcLogItemDbSetBase.cs`** — Interface for LogItem DbSet. - ---- - -> **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. diff --git a/AyCode.Database/DbSets/Messages/README.md b/AyCode.Database/DbSets/Messages/README.md index 92ef764..5452e2d 100644 --- a/AyCode.Database/DbSets/Messages/README.md +++ b/AyCode.Database/DbSets/Messages/README.md @@ -6,7 +6,3 @@ Email message querying and CRUD operations with sender/recipient/context filteri - **`IAcEmailMessageDbSet.cs`** — EmailMessage DbSet interface. - **`AcEmailMessageDbSetExtension.cs`** — GetEmailMessageById, GetEmailMessagesByContextId/SenderId, filter by sender/recipient, AddEmailMessage, UpdateEmailMessage, RemoveEmailMessage. - ---- - -> **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. diff --git a/AyCode.Database/DbSets/Profiles/README.md b/AyCode.Database/DbSets/Profiles/README.md index a1268a4..f401853 100644 --- a/AyCode.Database/DbSets/Profiles/README.md +++ b/AyCode.Database/DbSets/Profiles/README.md @@ -6,7 +6,3 @@ Profile CRUD operations with address relationship support. - **`IAcProfileDbSetBase.cs`** — Interface with Address dependency. - **`AcProfileDbSetExtensions.cs`** — GetProfileById, AddProfile, UpdateProfile, RemoveProfile. - ---- - -> **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. diff --git a/AyCode.Database/DbSets/README.md b/AyCode.Database/DbSets/README.md index 284d105..d412e0c 100644 --- a/AyCode.Database/DbSets/README.md +++ b/AyCode.Database/DbSets/README.md @@ -16,7 +16,3 @@ Generic DbSet interfaces with extension method-based CRUD operations. Each entit | [`Companies/`](Companies/README.md) | Company CRUD with profile and user-to-company relations | | [`Messages/`](Messages/README.md) | Email message querying and CRUD | | [`Loggers/`](Loggers/README.md) | Log item DbSet interface | - ---- - -> **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. diff --git a/AyCode.Database/DbSets/Users/README.md b/AyCode.Database/DbSets/Users/README.md index a079b9c..f800ede 100644 --- a/AyCode.Database/DbSets/Users/README.md +++ b/AyCode.Database/DbSets/Users/README.md @@ -10,7 +10,3 @@ User entity CRUD operations, authentication, and JWT token management via extens - **`AcUserTokenDbSetExtensions.cs`** — CreateUserToken, GetActiveUserToken, IsValidToken, DeactivateTokens, ChangePassword. - **`IAcUserChangePasswordDbSet.cs`** — Combined interface for password change operations. - **`IAcUserToCompanyDbSetBase.cs`** — UserToCompany mapping interface. - ---- - -> **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. diff --git a/AyCode.Database/Extensions/README.md b/AyCode.Database/Extensions/README.md index c1b5485..9bc2395 100644 --- a/AyCode.Database/Extensions/README.md +++ b/AyCode.Database/Extensions/README.md @@ -8,7 +8,3 @@ Database utility extensions for DTO conversion, read-only sessions, and transact - **`AcDbSessionExtension.cs`** — Session/SessionAsync for read-only operations with error logging. - **`AcDbTransactionExtension.cs`** — Transaction/TransactionAsync with auto-rollback on failure, OpenTransaction/CommitTransaction helpers. - **`AcDalExtension.cs`** — DAL-level mutex-locked session/transaction wrappers, UpdateSafe/UpdateSafeAsync for optimistic updates with optional callbacks. - ---- - -> **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. diff --git a/AyCode.Database/ModelBuilders/Profiles/README.md b/AyCode.Database/ModelBuilders/Profiles/README.md index 800dad1..6aeef2d 100644 --- a/AyCode.Database/ModelBuilders/Profiles/README.md +++ b/AyCode.Database/ModelBuilders/Profiles/README.md @@ -6,7 +6,3 @@ EF Core entity type configuration for Profile↔Address relationship. - **`AcProfileEntityTypeConfigurations.cs`** — Default config mapping Profile to Address. - **`AcProfileEntityTypeBuilderExtensions.cs`** — BuildEntityToAddressRelation (one-to-one). - ---- - -> **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. diff --git a/AyCode.Database/ModelBuilders/README.md b/AyCode.Database/ModelBuilders/README.md index 8a2247b..7da594c 100644 --- a/AyCode.Database/ModelBuilders/README.md +++ b/AyCode.Database/ModelBuilders/README.md @@ -8,7 +8,3 @@ EF Core Fluent API configurations for entity relationships (one-to-one, many-to- |---|---| | [`Users/`](Users/README.md) | User↔Profile and User↔Company relationship configs | | [`Profiles/`](Profiles/README.md) | Profile↔Address relationship config | - ---- - -> **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. diff --git a/AyCode.Database/ModelBuilders/Users/README.md b/AyCode.Database/ModelBuilders/Users/README.md index 25fc338..6a45590 100644 --- a/AyCode.Database/ModelBuilders/Users/README.md +++ b/AyCode.Database/ModelBuilders/Users/README.md @@ -6,7 +6,3 @@ EF Core entity type configurations for User and Company relationships. - **`AcUserEntityTypeConfigurations.cs`** — Default configs: User↔Profile (one-to-one), Company↔Profile with auto-include navigation. - **`AcUserEntityTypeBuilderExtensions.cs`** — BuildEntityToProfileRelation (cascade delete), BuildEntityToServiceProviderRelation (many-to-many via UsingEntity). - ---- - -> **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. diff --git a/AyCode.Database/README.md b/AyCode.Database/README.md index 650b3c8..b3f5d27 100644 --- a/AyCode.Database/README.md +++ b/AyCode.Database/README.md @@ -24,7 +24,3 @@ Entity Framework Core data access layer with generic DAL pattern, session/transa | `Microsoft.EntityFrameworkCore.SqlServer` | SQL Server EF Core provider | | `MessagePack` | Serialization annotations | | `Newtonsoft.Json` | JSON support | - ---- - -> **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. diff --git a/AyCode.Entities.Server/LogItems/README.md b/AyCode.Entities.Server/LogItems/README.md index 3f02413..d269ca0 100644 --- a/AyCode.Entities.Server/LogItems/README.md +++ b/AyCode.Entities.Server/LogItems/README.md @@ -6,7 +6,3 @@ Server-side log item entity and interface, extending the client-side `AcLogItemC - **`IAcLogItem.cs`** — Interface extending `IAcLogItemClient` and `IEntityInt`, adding a `LogHeaderId` property. - **`AcLogItem.cs`** — Entity class mapped to the `LogItem` database table with MessagePack serialization. Provides `Id` (auto-generated) and `LogHeaderId`. - ---- - -> **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. diff --git a/AyCode.Entities.Server/README.md b/AyCode.Entities.Server/README.md index 3534fae..6433a31 100644 --- a/AyCode.Entities.Server/README.md +++ b/AyCode.Entities.Server/README.md @@ -16,7 +16,3 @@ Server-side entity implementations extending `AyCode.Entities`. Currently contai | `AyCode.Entities` | `AcLogItemClient` base class | | `AyCode.Utils` | Shared utilities | | `MessagePack.Annotations` | `[MessagePackObject]`, `[Key]` for 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. diff --git a/AyCode.Entities/Addresses/README.md b/AyCode.Entities/Addresses/README.md index e1cf823..76d0e5e 100644 --- a/AyCode.Entities/Addresses/README.md +++ b/AyCode.Entities/Addresses/README.md @@ -5,7 +5,3 @@ Abstract base entity for physical addresses, storing geocoordinates and address ## Key Files - **`AcAddress.cs`** — Abstract class implementing `IAcAddress` with `Latitude`, `Longitude`, `AddressText`, and validity flags (`IsValid`, `IsHelper`). Uses a non-database-generated `Guid` primary key. - ---- - -> **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. diff --git a/AyCode.Entities/Groups/README.md b/AyCode.Entities/Groups/README.md index 5a1d9f4..d0977f0 100644 --- a/AyCode.Entities/Groups/README.md +++ b/AyCode.Entities/Groups/README.md @@ -5,7 +5,3 @@ Abstract base entity for groups with public/private visibility. Implements `IGro ## Key Files - **`GroupBase.cs`** — Abstract class with `Id` (Guid), `IsPublic` flag, and `Created`/`Modified` timestamps. Provides constructors for creating groups with optional explicit IDs. - ---- - -> **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. diff --git a/AyCode.Entities/Locations/README.md b/AyCode.Entities/Locations/README.md index 7b77e7a..a49a3ca 100644 --- a/AyCode.Entities/Locations/README.md +++ b/AyCode.Entities/Locations/README.md @@ -5,7 +5,3 @@ Abstract base entity for geographic locations with longitude, latitude, and an o ## Key Files - **`LocationBase.cs`** — Abstract class with `Id` (Guid), `Longitude`, `Latitude`, and `Address` properties. Provides constructors that auto-generate IDs or accept explicit ones. - ---- - -> **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. diff --git a/AyCode.Entities/LogItems/README.md b/AyCode.Entities/LogItems/README.md index 1867718..4422c63 100644 --- a/AyCode.Entities/LogItems/README.md +++ b/AyCode.Entities/LogItems/README.md @@ -5,7 +5,3 @@ Client-side log item entity used for structured logging. Serialized with Message ## Key Files - **`AcLogItemClient.cs`** — Implements `IAcLogItemClient` with fields for `AppType`, `LogLevel`, `ThreadId`, `CategoryName`, `CallerName`, `Text`, and exception details. Uses `[MessagePackObject]` serialization with explicit key indices. - ---- - -> **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. diff --git a/AyCode.Entities/Messages/README.md b/AyCode.Entities/Messages/README.md index bac4601..1c8147a 100644 --- a/AyCode.Entities/Messages/README.md +++ b/AyCode.Entities/Messages/README.md @@ -6,7 +6,3 @@ Abstract base entities for email messaging, covering both messages and their rec - **`AcEmailMessage.cs`** — Generic abstract class (`AcEmailMessage`) implementing `IAcEmailMessage`. Holds sender, context, subject, body text, email address, read status, and a list of recipients. - **`AcEmailRecipient.cs`** — Generic abstract class (`AcEmailRecipient`) implementing `IAcEmailRecipient`. Links a recipient to an email message via `EmailMessageId` with navigation back to the message entity. - ---- - -> **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. diff --git a/AyCode.Entities/Profiles/README.md b/AyCode.Entities/Profiles/README.md index 30abcc8..9f753cf 100644 --- a/AyCode.Entities/Profiles/README.md +++ b/AyCode.Entities/Profiles/README.md @@ -5,7 +5,3 @@ Abstract base entity for user/company profiles with name, contact info, and a li ## Key Files - **`AcProfile.cs`** — Generic abstract class (`AcProfile`) implementing `IAcProfile`. Contains `Name`, `FirstName`, `LastName`, `EmailAddress`, `Description`, `ThumbnailUrl`, and a foreign-key relationship to an `Address` entity. Provides `SetAddress()` and `GetFullName()` helpers with language-aware name ordering. - ---- - -> **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. diff --git a/AyCode.Entities/README.md b/AyCode.Entities/README.md index 2013a55..9f81121 100644 --- a/AyCode.Entities/README.md +++ b/AyCode.Entities/README.md @@ -34,7 +34,3 @@ Abstract base entity implementations for the AyCode domain model. All entities a |---|---| | `AyCode.Interfaces` | Interface contracts this project implements | | `MessagePack.Annotations` | `[MessagePackObject]` on `AcLogItemClient` | - ---- - -> **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. diff --git a/AyCode.Entities/ServiceProviders/README.md b/AyCode.Entities/ServiceProviders/README.md index 078b51f..ac10589 100644 --- a/AyCode.Entities/ServiceProviders/README.md +++ b/AyCode.Entities/ServiceProviders/README.md @@ -5,7 +5,3 @@ Abstract base entity for companies/service providers, linking owners, profiles, ## Key Files - **`AcCompany.cs`** — Generic abstract class (`AcCompany`) implementing `IAcCompany`. Holds `Name`, `OwnerId`, `CommissionPercent`, `AffiliateId`, `ReferralId`, and navigation properties to `Profile`, `Users`, and `UserToServiceProviders`. Provides `SetProfile()`, `HasUser()`, and `AddUser()` helper methods. - ---- - -> **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. diff --git a/AyCode.Entities/Users/README.md b/AyCode.Entities/Users/README.md index 46b73ae..011bf1c 100644 --- a/AyCode.Entities/Users/README.md +++ b/AyCode.Entities/Users/README.md @@ -7,7 +7,3 @@ Abstract base entities for user accounts, authentication tokens, and user-to-com - **`AcUser.cs`** — Generic abstract class (`AcUser`) implementing `IAcUser`. Holds email, password, phone, refresh token, affiliate/referral IDs, and navigation properties to `Profile`, `ServiceProviders`, and `UserToServiceProviders`. - **`AcUserTokenBase.cs`** — Abstract class for user verification tokens with `Token`, `IsActive`, `TokenSent`, and `TokenExpiration` fields. Uses an auto-incremented `int` primary key. - **`AcUserToCompany.cs`** — Generic abstract class (`AcUserToCompany`) implementing `IAcUserToCompany`. Many-to-many join entity linking users to companies with a `Permissions` field. - ---- - -> **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. diff --git a/AyCode.Interfaces.Server/Logins/README.md b/AyCode.Interfaces.Server/Logins/README.md index edc2387..e9fd5fe 100644 --- a/AyCode.Interfaces.Server/Logins/README.md +++ b/AyCode.Interfaces.Server/Logins/README.md @@ -7,7 +7,3 @@ Server-side login interfaces defining contracts for login DTOs, authenticated se - **`IAcLoginDtoBase.cs`** — Empty marker interface for login DTO types. - **`IAcLoggedInModelBase.cs`** — Generic interface for authenticated session state, exposing `IsLoggedIn`, `LoggedInUser`, `AccessToken`, and `LoginErrorCode`, with methods for login and logout. - **`IAcLoginServiceServer.cs`** — Server login service interface with `Login`/`LoginAsync` and `UpdatePassword` methods, generic over user, token, profile, and company types. - ---- - -> **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. diff --git a/AyCode.Interfaces.Server/README.md b/AyCode.Interfaces.Server/README.md index a2670bd..662e7a2 100644 --- a/AyCode.Interfaces.Server/README.md +++ b/AyCode.Interfaces.Server/README.md @@ -18,7 +18,3 @@ Server-side interface contracts extending `AyCode.Interfaces`. Defines authentic | `AyCode.Core.Server` | Server-side core | | `AyCode.Entities` | Entity base classes | | `AyCode.Entities.Server` | Server-side entities | - ---- - -> **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. diff --git a/AyCode.Interfaces/Addresses/Dtos/README.md b/AyCode.Interfaces/Addresses/Dtos/README.md index 4e6473d..badecfa 100644 --- a/AyCode.Interfaces/Addresses/Dtos/README.md +++ b/AyCode.Interfaces/Addresses/Dtos/README.md @@ -5,7 +5,3 @@ Data transfer object interface for address data, defining the minimal address sh ## Key Files - **`IAcAddressDtoBase.cs`** — Base address DTO interface with `IsValid`, `IsHelper`, `Latitude`, `Longitude`, and `AddressText` properties. Extends `IEntityGuid`. - ---- - -> **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. diff --git a/AyCode.Interfaces/Addresses/README.md b/AyCode.Interfaces/Addresses/README.md index f2eab5f..e32eb3a 100644 --- a/AyCode.Interfaces/Addresses/README.md +++ b/AyCode.Interfaces/Addresses/README.md @@ -7,7 +7,3 @@ Interfaces for address entities, including the full address model, foreign key c - **`IAcAddress.cs`** — Full address interface combining `IAcAddressDtoBase` with `ITimeStampInfo`. - **`IAcAddressRelation.cs`** — Generic navigation property interface for entities that hold an `Address` reference. - **`IAcAddressForeignKey.cs`** — Foreign key contract exposing `AddressId` (Guid), extends `IForeignKey`. - ---- - -> **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. diff --git a/AyCode.Interfaces/Entities/README.md b/AyCode.Interfaces/Entities/README.md index 60a87e8..6420ce0 100644 --- a/AyCode.Interfaces/Entities/README.md +++ b/AyCode.Interfaces/Entities/README.md @@ -10,7 +10,3 @@ Core entity interfaces that define primary key contracts and soft-delete behavio - **`IAcSoftRemoveEntity.cs`** — Adds a `Deleted` boolean flag for soft-delete support. - **`IAcSoftRemoveEntityInt.cs`** — Soft-delete entity with `int` key. - **`IAcSoftRemoveEntityGuid.cs`** — Soft-delete entity with `Guid` key. - ---- - -> **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. diff --git a/AyCode.Interfaces/EntityComment/README.md b/AyCode.Interfaces/EntityComment/README.md index 080109f..20e108d 100644 --- a/AyCode.Interfaces/EntityComment/README.md +++ b/AyCode.Interfaces/EntityComment/README.md @@ -5,7 +5,3 @@ Interface for entities that support a comment/note field. ## Key Files - **`IEntityComment.cs`** — Defines a single `Comment` string property for attaching comments to entities. - ---- - -> **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. diff --git a/AyCode.Interfaces/Enums/README.md b/AyCode.Interfaces/Enums/README.md index d760126..ff1ef1f 100644 --- a/AyCode.Interfaces/Enums/README.md +++ b/AyCode.Interfaces/Enums/README.md @@ -5,7 +5,3 @@ Interface defining message type enumerations used across the messaging system. ## Key Files - **`IMessageTypes.cs`** — Contains the `IMessageTypes` interface with a nested `MessageTypesEnum` enum placeholder. - ---- - -> **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. diff --git a/AyCode.Interfaces/Groups/README.md b/AyCode.Interfaces/Groups/README.md index 0608a66..e5177be 100644 --- a/AyCode.Interfaces/Groups/README.md +++ b/AyCode.Interfaces/Groups/README.md @@ -5,7 +5,3 @@ Interface for group entities with identity and timestamp support. ## Key Files - **`IGroupBase.cs`** — Base group interface extending `IEntityGuid` and `ITimeStampInfo`. - ---- - -> **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. diff --git a/AyCode.Interfaces/Locations/README.md b/AyCode.Interfaces/Locations/README.md index 38ea1b6..8c9adea 100644 --- a/AyCode.Interfaces/Locations/README.md +++ b/AyCode.Interfaces/Locations/README.md @@ -5,7 +5,3 @@ Interface for location entities providing geographic coordinates and address tex ## Key Files - **`ILocationBase.cs`** — Defines `Longitude`, `Latitude`, and `Address` properties. Extends `IEntityGuid`. - ---- - -> **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. diff --git a/AyCode.Interfaces/Logins/README.md b/AyCode.Interfaces/Logins/README.md index 17269a5..7a57cbb 100644 --- a/AyCode.Interfaces/Logins/README.md +++ b/AyCode.Interfaces/Logins/README.md @@ -7,7 +7,3 @@ Interfaces for authentication and login service contracts, covering login state, - **`IAcLoginServiceBase.cs`** — Base login service with `IsLoggedIn` and `LoggedInUser` properties, generic over user/profile/company types. - **`IAcLoginServiceCommon.cs`** — Extends the base with `Logout`, `Registration`, `ChangePassword`, and `ForgotPassword` methods (sync and async). - **`IAcLoginServiceClient.cs`** — Client-side login service marker interface extending `IAcLoginServiceCommon`. - ---- - -> **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. diff --git a/AyCode.Interfaces/MediaInfo/README.md b/AyCode.Interfaces/MediaInfo/README.md index 2ed5f20..b6694d6 100644 --- a/AyCode.Interfaces/MediaInfo/README.md +++ b/AyCode.Interfaces/MediaInfo/README.md @@ -7,7 +7,3 @@ Interfaces for media-related properties such as thumbnail URLs and user media id - **`IMediaInfo.cs`** — Composite interface combining `IMediaThumbnailUrl` and `IMediaUserMediaId`. - **`IMediaThumbnailUrl.cs`** — Defines an optional `ThumbnailUrl` string property. - **`IMediaUserMediaId.cs`** — Defines an optional `UserMediaId` (Guid?) property. - ---- - -> **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. diff --git a/AyCode.Interfaces/Messages/README.md b/AyCode.Interfaces/Messages/README.md index 53a560e..7fc651c 100644 --- a/AyCode.Interfaces/Messages/README.md +++ b/AyCode.Interfaces/Messages/README.md @@ -12,7 +12,3 @@ Interfaces for the email/messaging system, covering message entities, recipients - **`IAcEmailRecipientsRelation.cs`** — Navigation property exposing a `List` collection. - **`IAcEmailMessageForeignKey.cs`** — Foreign key contract for `EmailMessageId` (generic and Guid variants). - **`IAcMessageSenderService.cs`** — Service interface with `SendMessageAsync` for dispatching messages. - ---- - -> **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. diff --git a/AyCode.Interfaces/Profiles/Dtos/README.md b/AyCode.Interfaces/Profiles/Dtos/README.md index 4c097d7..b4ef13e 100644 --- a/AyCode.Interfaces/Profiles/Dtos/README.md +++ b/AyCode.Interfaces/Profiles/Dtos/README.md @@ -7,7 +7,3 @@ DTO interfaces for profile data, defining name fields and the base profile DTO s - **`IAcFullName.cs`** — Defines `FullName` (read-only), `FirstName`, and `LastName` properties. - **`IAcProfileName.cs`** — Extends `IAcFullName` with a `Name` property. - **`IAcProfileDtoBase.cs`** — Base profile DTO with `EmailAddress`, `Description`, media info, and address foreign key. Generic variant adds an address relation. - ---- - -> **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. diff --git a/AyCode.Interfaces/Profiles/README.md b/AyCode.Interfaces/Profiles/README.md index 52e6c81..b61891e 100644 --- a/AyCode.Interfaces/Profiles/README.md +++ b/AyCode.Interfaces/Profiles/README.md @@ -7,7 +7,3 @@ Interfaces for user/company profile entities, including navigation relations and - **`IAcProfile.cs`** — Full profile interface with `GetFullName` and `SetAddress` methods, extends `IAcProfileDtoBase` and `ITimeStampInfo`. - **`IAcProfileRelation.cs`** — Generic navigation property for entities holding a `Profile` reference. - **`IAcProfileForeignKey.cs`** — Foreign key contract exposing `ProfileId` (Guid), extends `IForeignKey`. - ---- - -> **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. diff --git a/AyCode.Interfaces/README.md b/AyCode.Interfaces/README.md index 9f3c4bf..a3a8da3 100644 --- a/AyCode.Interfaces/README.md +++ b/AyCode.Interfaces/README.md @@ -40,7 +40,3 @@ Domain interface contracts for the AyCode platform. Defines the shape of entitie | Dependency | Purpose | |---|---| | `AyCode.Core` | Core library (`IId`, `IForeignKey`, enums, error codes) | - ---- - -> **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. diff --git a/AyCode.Interfaces/ServiceProviders/README.md b/AyCode.Interfaces/ServiceProviders/README.md index 44c943d..1b553e7 100644 --- a/AyCode.Interfaces/ServiceProviders/README.md +++ b/AyCode.Interfaces/ServiceProviders/README.md @@ -8,7 +8,3 @@ Interfaces for company/service provider entities, covering base properties, prof - **`IAcCompany.cs`** — Multiple generic variants linking a company to its profile, address, and user collections. - **`IAcCompanyRelation.cs`** — Navigation property for entities holding `ServiceProviders` and `UserToServiceProviders` lists. - **`IAcCompanyForeignKey.cs`** — Foreign key contract exposing `ServiceProviderId` (Guid). - ---- - -> **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. diff --git a/AyCode.Interfaces/StorageHandlers/README.md b/AyCode.Interfaces/StorageHandlers/README.md index 05d0a9a..c5b4a25 100644 --- a/AyCode.Interfaces/StorageHandlers/README.md +++ b/AyCode.Interfaces/StorageHandlers/README.md @@ -5,7 +5,3 @@ Interface for secure key-value storage operations (save, get, delete, clear). ## Key Files - **`ISecureStorageHandler.cs`** — Async methods: `SaveToSecureStorageAsync`, `GetFromSecureStorageAsync`, `DeleteFromSecureStorageAsync`, and `ClearAllSecureStorageAsync`. - ---- - -> **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. diff --git a/AyCode.Interfaces/TimeStampInfo/README.md b/AyCode.Interfaces/TimeStampInfo/README.md index cbd9e97..a4d75b2 100644 --- a/AyCode.Interfaces/TimeStampInfo/README.md +++ b/AyCode.Interfaces/TimeStampInfo/README.md @@ -8,7 +8,3 @@ Interfaces for entity timestamp tracking (created/modified) and a marker to disa - **`ITimeStampModified.cs`** — Defines a `Modified` DateTime property. - **`ITimeStampInfo.cs`** — Composite interface combining `ITimeStampCreated` and `ITimeStampModified`. - **`ITimeStampDisableAutoSet.cs`** — Marker interface to opt out of automatic timestamp population. - ---- - -> **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. diff --git a/AyCode.Interfaces/Users/Dtos/README.md b/AyCode.Interfaces/Users/Dtos/README.md index bbba420..9615ae5 100644 --- a/AyCode.Interfaces/Users/Dtos/README.md +++ b/AyCode.Interfaces/Users/Dtos/README.md @@ -7,7 +7,3 @@ DTO interfaces for user data at different detail levels -- minimal, base, and de - **`IAcUserDtoMinBase.cs`** — Minimal user DTO with `AffiliateId`. Generic variant adds a profile relation. - **`IAcUserDtoBase.cs`** — Base user DTO extending the minimal DTO. Generic variants add profile and company relations. - **`IAcUserDtoDetailBase.cs`** — Detailed user DTO combining `IAcUserBase` with DTO base interfaces. Generic variants add profile, company, and address type parameters. - ---- - -> **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. diff --git a/AyCode.Interfaces/Users/README.md b/AyCode.Interfaces/Users/README.md index 3efbe53..cafc2a9 100644 --- a/AyCode.Interfaces/Users/README.md +++ b/AyCode.Interfaces/Users/README.md @@ -17,7 +17,3 @@ Interfaces for user entities, covering base properties, authentication fields, c - **`IAcUserToServiceProviderRelation.cs`** — Relation linking a user to a service provider. - **`IAcUserModelDtoMinBase.cs`** — Minimal user model DTO marker extending `IAcModelDtoBase`. - **`IAcUserForeignKey.cs`** — Foreign key contract exposing `UserId` (Guid). - ---- - -> **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. diff --git a/AyCode.Models.Server/DynamicMethods/README.md b/AyCode.Models.Server/DynamicMethods/README.md index 1a70a07..233360f 100644 --- a/AyCode.Models.Server/DynamicMethods/README.md +++ b/AyCode.Models.Server/DynamicMethods/README.md @@ -7,7 +7,3 @@ Reflection-based infrastructure for dynamically dispatching method calls by mess - **`AcMethodInfoModel.cs`** — Wraps a `MethodInfo` and its `TagAttribute` with cached parameter metadata. - **`AcDynamicMethodCallModel.cs`** — Binds an object instance to its attributed methods, using a static `ConcurrentDictionary` and `FrozenDictionary` cache keyed by message tag. Reflection runs once per type. - **`AcDynamicMethodRegistry.cs`** — Registry with lazy method lookup across multiple registered instances. Caches discovered methods statically by message tag and resolves instances per request. - ---- - -> **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. diff --git a/AyCode.Models.Server/Logins/README.md b/AyCode.Models.Server/Logins/README.md index e2ea7c4..f428b8a 100644 --- a/AyCode.Models.Server/Logins/README.md +++ b/AyCode.Models.Server/Logins/README.md @@ -5,7 +5,3 @@ Server-side implementation of the logged-in session model, managing user authent ## Key Files - **`AcLoggedInModelServer.cs`** — Generic implementation of `IAcLoggedInModelBase`. Tracks `LoggedInUser`, `AccessToken`, and `LoginErrorCode`, with `AddLoggedInUser` and `Logout` methods. - ---- - -> **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. diff --git a/AyCode.Models.Server/README.md b/AyCode.Models.Server/README.md index 27eb4cc..8471d34 100644 --- a/AyCode.Models.Server/README.md +++ b/AyCode.Models.Server/README.md @@ -31,7 +31,3 @@ Server-side models: authentication state and dynamic method dispatch for SignalR | `AyCode.Interfaces.Server` | `IAcLoggedInModelBase` | | `AyCode.Models` | Shared models | | `AyCode.Services` | `TagAttribute` for SignalR method tagging | - ---- - -> **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. diff --git a/AyCode.Models/Enums/README.md b/AyCode.Models/Enums/README.md index 278d2c5..b370e03 100644 --- a/AyCode.Models/Enums/README.md +++ b/AyCode.Models/Enums/README.md @@ -6,7 +6,3 @@ Enumerations for messaging-related types used across the application models. - **`MessageContentType.cs`** — Defines content types for messages: Text, Image, Video, Audio, File, Location, Contact, Sticker, Gif, VoiceNote, System. - **`MessageTypesEnum.cs`** — Defines message delivery channels: email (1), sms (2), push (3), chat (4). - ---- - -> **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. diff --git a/AyCode.Models/Messages/README.md b/AyCode.Models/Messages/README.md index 0449ef7..9104501 100644 --- a/AyCode.Models/Messages/README.md +++ b/AyCode.Models/Messages/README.md @@ -5,7 +5,3 @@ Placeholder namespace for message models. The `EmailMessage` class is currently ## Key Files - **`EmailMessage.cs`** — Contains a commented-out `EmailMessage` class (with Subject and HtmlContent properties) that previously extended `NoticeBase`. Currently inactive. - ---- - -> **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. diff --git a/AyCode.Models/README.md b/AyCode.Models/README.md index 07fbbc3..00fb0eb 100644 --- a/AyCode.Models/README.md +++ b/AyCode.Models/README.md @@ -35,7 +35,3 @@ Shared DTOs (Data Transfer Objects) and view models for the AyCode platform. Bri | `AyCode.Core` | Core types | | `AyCode.Entities` | Entity base classes for DTO-entity mapping | | `AyCode.Interfaces` | Interface contracts implemented by DTOs | - ---- - -> **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. diff --git a/AyCode.Models/Users/README.md b/AyCode.Models/Users/README.md index b026896..5fde556 100644 --- a/AyCode.Models/Users/README.md +++ b/AyCode.Models/Users/README.md @@ -10,7 +10,3 @@ Abstract base DTOs for user data transfer, including minimal, standard, and deta - **`AcPasswordDtoBase.cs`** — Base class for password operations with a `NewPassword` property. - **`AcChangePasswordDto.cs`** — Extends `AcPasswordDtoBase` with `UserId` and `OldPassword` for password change requests. - **`AcForgotPasswordDto.cs`** — Extends `AcPasswordDtoBase` with `Email` for forgot-password flows. - ---- - -> **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. diff --git a/AyCode.Services.Server.Tests/LoginServices/README.md b/AyCode.Services.Server.Tests/LoginServices/README.md index 1a2c62b..e6f3f52 100644 --- a/AyCode.Services.Server.Tests/LoginServices/README.md +++ b/AyCode.Services.Server.Tests/LoginServices/README.md @@ -5,7 +5,3 @@ Abstract base for login service integration tests. ## Key Files - **`AcLoginServiceServerTestBase.cs`** — 10 generic type parameters. Tests: RegisterUser (create + validate + cleanup), LoginUser (valid, wrong email, wrong password with error codes), ChangePassword (change + verify + restore). - ---- - -> **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. diff --git a/AyCode.Services.Server.Tests/README.md b/AyCode.Services.Server.Tests/README.md index a0a430e..3ebccd1 100644 --- a/AyCode.Services.Server.Tests/README.md +++ b/AyCode.Services.Server.Tests/README.md @@ -13,7 +13,3 @@ Comprehensive server-side tests for SignalR communication, DataSource operations - **`TestLogger.cs`** — Re-exports TestLogger from AyCode.Core.Tests. - **`InvokeMethodExtensionTests.cs`** — Tests MethodInfo.InvokeMethod: sync, async Task unwrapping, Task.FromResult (production bug fix), non-generic Task, complex objects. - ---- - -> **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. diff --git a/AyCode.Services.Server.Tests/SignalRs/README.md b/AyCode.Services.Server.Tests/SignalRs/README.md index 7d3c089..946417e 100644 --- a/AyCode.Services.Server.Tests/SignalRs/README.md +++ b/AyCode.Services.Server.Tests/SignalRs/README.md @@ -16,7 +16,3 @@ Full SignalR client→hub→service test infrastructure with testable components | Folder | Purpose | |---|---| | [`SignalRDatasources/`](SignalRDatasources/README.md) | DataSource CRUD and collection tests | - ---- - -> **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. diff --git a/AyCode.Services.Server.Tests/SignalRs/SignalRDatasources/README.md b/AyCode.Services.Server.Tests/SignalRs/SignalRDatasources/README.md index 9f613ac..873e010 100644 --- a/AyCode.Services.Server.Tests/SignalRs/SignalRDatasources/README.md +++ b/AyCode.Services.Server.Tests/SignalRs/SignalRDatasources/README.md @@ -24,7 +24,3 @@ DataSource CRUD, collection, tracking, and filter tests. Tested with List and Ac ### Test DataSources - **`TestOrderItemListDataSource.cs`** — DataSource with List. - **`TestOrderItemObservableDataSource.cs`** — DataSource with AcObservableCollection. - ---- - -> **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. diff --git a/AyCode.Services.Server/Emails/README.md b/AyCode.Services.Server/Emails/README.md index cc40eca..3eaf0ed 100644 --- a/AyCode.Services.Server/Emails/README.md +++ b/AyCode.Services.Server/Emails/README.md @@ -5,7 +5,3 @@ Server-side email delivery via SendGrid. ## Key Files - **`AcEmailServiceServer.cs`** — Implements `IAcEmailServiceServer`. Uses `SendGridClient` to send templated emails. Methods: `SendLostPasswordEmailAsync()` (password reset with token), `SendRegistrationEmailAsync()` (confirmation with token). - ---- - -> **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. diff --git a/AyCode.Services.Server/Logins/README.md b/AyCode.Services.Server/Logins/README.md index 6d597da..2ebab3b 100644 --- a/AyCode.Services.Server/Logins/README.md +++ b/AyCode.Services.Server/Logins/README.md @@ -5,7 +5,3 @@ Server-side login service with JWT token management. ## Key Files - **`AcLoginServiceServer.cs`** — Heavily generic class extending `AcLoginServiceBase`, implementing `IAcLoginServiceServer`. Full authentication flow: `Login()`, `Logout()`, `Registration()`, `ChangePassword()`, `ForgotPassword()`. JWT methods: `GenerateAccessToken()`, `GenerateRefreshToken()`, `GetPrincipalFromExpiredToken()`. Uses DAL for database access. - ---- - -> **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. diff --git a/AyCode.Services.Server/README.md b/AyCode.Services.Server/README.md index c594fa7..3147e75 100644 --- a/AyCode.Services.Server/README.md +++ b/AyCode.Services.Server/README.md @@ -25,7 +25,3 @@ Server-side service implementations: JWT authentication, SendGrid email delivery | `Microsoft.AspNetCore.SignalR.*` | SignalR server | | `Microsoft.AspNetCore.Cryptography.KeyDerivation` | Password hashing | | `Microsoft.AspNetCore.Authentication.JwtBearer` | JWT auth (transitive) | - ---- - -> **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. diff --git a/AyCode.Services.Server/SignalRs/README.md b/AyCode.Services.Server/SignalRs/README.md index 2a10697..5fabe41 100644 --- a/AyCode.Services.Server/SignalRs/README.md +++ b/AyCode.Services.Server/SignalRs/README.md @@ -20,7 +20,3 @@ Server-side SignalR hub infrastructure: hub base class, session management, data ### Utilities - **`ExtensionMethods.cs`** — `InvokeMethod()` — invokes methods and unwraps `Task`/`Task`/`ValueTask` results. - **`TrackingItemHelpers.cs`** — Deep clone helpers: `JsonClone()`, `ReflectionClone()`. - ---- - -> **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. diff --git a/AyCode.Services.Tests/README.md b/AyCode.Services.Tests/README.md index 8547958..658aef9 100644 --- a/AyCode.Services.Tests/README.md +++ b/AyCode.Services.Tests/README.md @@ -11,7 +11,3 @@ MSTest project for service layer testing. Focuses on SignalR message serializati ## Key Files (Root) - **`MSTestSettings.cs`** — Assembly-level parallel test execution (MethodLevel scope). - ---- - -> **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. diff --git a/AyCode.Services.Tests/SignalRs/README.md b/AyCode.Services.Tests/SignalRs/README.md index a58036a..013607f 100644 --- a/AyCode.Services.Tests/SignalRs/README.md +++ b/AyCode.Services.Tests/SignalRs/README.md @@ -5,7 +5,3 @@ SignalR message serialization and full round-trip tests. ## Key Files - **`PostJsonDataMessageTests.cs`** — Full pipeline test: client creates message → binary serialize → server deserialize → parameter extract → service result → response create → binary response → client deserialize → type convert. Covers int, string, bool with [DataRow]. - ---- - -> **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. diff --git a/AyCode.Services/Loggers/README.md b/AyCode.Services/Loggers/README.md index 3c97cac..22bb0f0 100644 --- a/AyCode.Services/Loggers/README.md +++ b/AyCode.Services/Loggers/README.md @@ -9,7 +9,3 @@ Remote log writers for sending log items over HTTP, SignalR, or to the browser c - **`AcSignaRClientLogItemWriter.cs`** — Sends `AcLogItemClient` items to a SignalR hub. Manages `HubConnection` lifecycle with `StartConnection()`/`StopConnection()`. All three implement `IAcLogWriterClientBase`. - ---- - -> **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. diff --git a/AyCode.Services/Logins/README.md b/AyCode.Services/Logins/README.md index fb2b161..d0f28b1 100644 --- a/AyCode.Services/Logins/README.md +++ b/AyCode.Services/Logins/README.md @@ -6,7 +6,3 @@ Base and client-side login service implementations. - **`AcLoginServiceBase.cs`** — Abstract generic base implementing `IAcLoginServiceBase`. Provides `IsLoggedIn` and `LoggedInUser` properties. Heavily constrained generics (TUser, TProfile, TCompany, TUserToServiceProvider, TProfileAddress). - **`AcLoginServiceClient.cs`** — Client-side login service extending `AcLoginServiceBase`, implementing `IAcLoginServiceClient`. Provides stubs for `Login`, `Logout`, `Registration`, `ChangePassword`, `ForgotPassword` (sync + async variants). - ---- - -> **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. diff --git a/AyCode.Services/README.md b/AyCode.Services/README.md index b0feb41..afd12d3 100644 --- a/AyCode.Services/README.md +++ b/AyCode.Services/README.md @@ -21,7 +21,3 @@ Shared service implementations: SignalR communication (custom binary protocol), | `Microsoft.AspNetCore.SignalR.Client` | SignalR client | | `Microsoft.AspNetCore.SignalR.Common` | `IHubProtocol` for custom binary protocol | | `Microsoft.AspNetCore.Authentication.JwtBearer` | JWT authentication | - ---- - -> **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. diff --git a/AyCode.Services/SignalRs/README.md b/AyCode.Services/SignalRs/README.md index 940a117..80e112a 100644 --- a/AyCode.Services/SignalRs/README.md +++ b/AyCode.Services/SignalRs/README.md @@ -21,7 +21,3 @@ Custom binary SignalR protocol, client infrastructure, message tagging, and seri ### Serialization & Pooling - **`SignalRSerializationHelper.cs`** — Static helpers: `SerializeToBinary()`, `DeserializeFromBinary()`, compressed JSON variants, `CreateResponseData()`. - **`SignalRRequestModel.cs`** — Poolable (`IResettable`) request tracking model with `ObjectPool` for reuse. - ---- - -> **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. diff --git a/AyCode.Utils.Server/README.md b/AyCode.Utils.Server/README.md index f5dc7d9..f8a51d9 100644 --- a/AyCode.Utils.Server/README.md +++ b/AyCode.Utils.Server/README.md @@ -5,7 +5,3 @@ Server-side utility library placeholder. Currently empty — reserved for future ## Dependencies None. - ---- - -> **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. diff --git a/AyCode.Utils/Extensions/README.md b/AyCode.Utils/Extensions/README.md index 5169441..37576c0 100644 --- a/AyCode.Utils/Extensions/README.md +++ b/AyCode.Utils/Extensions/README.md @@ -7,7 +7,3 @@ String, DateTime, and lock utility extensions. - **`StringExtensions.cs`** — `IsNullOrEmpty()`, `IsNullOrWhiteSpace()` (with `[NotNullWhen]`), `FirstLetterToUpper()`, `MixCharacters()` (interleaves two char sequences: ABC+DEF→ADBECF). - **`DateTimeExtension.cs`** — `IsNullOrEmpty()` for `DateTime`/`DateTime?`, `IsEqualSqlDateTime2()` for SQL Server datetime2 precision comparison. - **`LockExtensions.cs`** — `using` pattern for locks: `mutex.UseWaitOne()`, `semaphore.UseWait()`, `semaphore.UseWaitAsync()`. Returns `IDisposable` wrappers that auto-release on dispose. - ---- - -> **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. diff --git a/AyCode.Utils/README.md b/AyCode.Utils/README.md index c9e950a..679d610 100644 --- a/AyCode.Utils/README.md +++ b/AyCode.Utils/README.md @@ -15,7 +15,3 @@ Low-level utility library with zero project dependencies. Provides string/dateti |---|---| | `JetBrains.Annotations` | `[ContractAnnotation]` for nullability hints | | `Microsoft.AspNetCore.Cryptography.KeyDerivation` | Key derivation (available to dependents) | - ---- - -> **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. diff --git a/AyCode.Utils/Wrappers/README.md b/AyCode.Utils/Wrappers/README.md index a35cca1..d4e1a14 100644 --- a/AyCode.Utils/Wrappers/README.md +++ b/AyCode.Utils/Wrappers/README.md @@ -8,7 +8,3 @@ Disposable wrappers enabling `using` pattern for synchronization primitives. - **`ReleaseWrapperSemaphore.cs`** — `IDisposable` wrapper for `SemaphoreSlim`. Calls `Release()` on dispose. Used via `semaphore.UseWait()` / `UseWaitAsync()`. Both are idempotent (safe to dispose multiple times via `_isDisposed` flag). - ---- - -> **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. diff --git a/README.md b/README.md index cf5ea19..61c012a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AyCode.Core Solution -.NET 10 core framework providing serialization (Binary, JSON, Toon), entity abstractions, database access, services, and shared utilities. Used as the foundation layer for AyCode applications. +.NET 9 core framework providing serialization (Binary, JSON, Toon), entity abstractions, database access, services, and shared utilities. Used as the foundation layer for AyCode applications. ## LLM Context @@ -45,7 +45,3 @@ Detailed docs: [`docs/`](docs/) — GLOSSARY.md, ARCHITECTURE.md, CONVENTIONS.md | [`AyCode.Database.Tests.Internal`](AyCode.Database.Tests.Internal/README.md) | Concrete database integration tests | [README](AyCode.Database.Tests.Internal/README.md) | | [`AyCode.Services.Tests`](AyCode.Services.Tests/README.md) | Service layer tests | [README](AyCode.Services.Tests/README.md) | | [`AyCode.Services.Server.Tests`](AyCode.Services.Server.Tests/README.md) | Server-side SignalR and service tests | [README](AyCode.Services.Server.Tests/README.md) | - ---- - -> **LLM Maintenance:** If you modify this solution's structure, 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. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9165455..6469b50 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -64,7 +64,3 @@ class User : AcUser { ... } ``` This allows the framework to define relationships without knowing concrete types. - ---- - -> **LLM Maintenance:** If you modify the project structure or dependency graph, update this document. diff --git a/docs/BINARY_FORMAT.md b/docs/BINARY_FORMAT.md new file mode 100644 index 0000000..e551aad --- /dev/null +++ b/docs/BINARY_FORMAT.md @@ -0,0 +1,387 @@ +# AcBinary Wire Format + +Complete wire format specification for the AcBinary serializer. Source of truth: [`AyCode.Core/Serializers/Binaries/BinaryTypeCode.cs`](../AyCode.Core/Serializers/Binaries/BinaryTypeCode.cs). + +## Stream Layout + +``` +[version : 1 byte] [flags : 1 byte] [cacheCount : VarUInt?] [payload...] +``` + +- **version** — `FormatVersion = 1` (current). +- **flags** — See [Header Flags](#header-flags). +- **cacheCount** — Present only when `HeaderFlag_HasCacheCount` is set. Number of type wrapper slots used by serializer. + +## Header Flags + +The flags byte uses `0x90` (144) as base with bit flags in the lower nibble: + +| Bit | Mask | Flag | Meaning | +|-----|------|------|---------| +| 0 | `0x01` | Metadata | Property hash metadata included (cross-type deserialization) | +| 1 | `0x02` | RefHandling_OnlyId | Reference tracking for `IId` objects only | +| 2 | `0x04` | RefHandling_All | Reference tracking for all objects (always combined with bit 1) | +| 3 | `0x08` | HasCacheCount | VarUInt cache count follows the flags byte | + +**Reference handling modes:** None = `0x00`, OnlyId = `0x02`, All = `0x06` (bits 1+2). + +## Variable-Length Encoding + +### VarUInt (unsigned) + +LEB128: 7 data bits per byte, MSB = continuation flag. + +``` +value < 128 → 1 byte [0xxxxxxx] +value < 16384 → 2 bytes [1xxxxxxx] [0xxxxxxx] +value < 2097152 → 3 bytes ... +(max 5 bytes for uint32) +``` + +### VarInt (signed) + +ZigZag encoding maps signed to unsigned, then LEB128: + +``` +encode: (value << 1) ^ (value >> 31) +decode: (raw >> 1) ^ -(raw & 1) +``` + +Maps: `0 → 0`, `-1 → 1`, `1 → 2`, `-2 → 3`, etc. + +### VarULong (unsigned 64-bit) + +Same LEB128 encoding, max 10 bytes for uint64. + +## Type Markers + +All markers defined in `BinaryTypeCode.cs`. `SlotCount = 64`. + +### FixObj (0–63) + +Single-byte object type. The marker byte **is** the type slot index — no additional type identifier needed. + +``` +[FixObj(N)] [properties...] +``` + +**Slot allocation:** Slots 0–63 are reserved for runtime polymorphic types, assigned dynamically on first encounter during serialization. Source-generated (SGen) types receive slots starting at 64+ via `AllocateWrapperSlot()` (sequential, `Interlocked.Increment`). SGen slots are compile-time stable; runtime slots depend on serialization order. + +### Complex Types (64–71) + +| Code | Name | Wire format | +|------|------|-------------| +| 64 | Object | `[64] [VarUInt typeIndex] [properties...]` | +| 65 | ObjectRef | `[65] [VarUInt refCacheIndex]` | +| 66 | Array | `[66] [VarUInt count] [elements...]` | +| 67 | Dictionary | `[67] [VarUInt count] [key, value pairs...]` | +| 68 | ByteArray | `[68] [VarUInt length] [raw bytes]` | +| 69 | ObjectWithMetadata | `[69] [VarUInt typeIndex] [VarUInt hashCount] [hashes...] [properties...]` | +| 70 | ObjectRefFirst | `[70] [VarUInt refCacheIndex] [object body...]` | +| 71 | ObjectWithMetadataRefFirst | `[71] [VarUInt refCacheIndex] [metadata + properties...]` | + +### Polymorphic Types (72–75) + +Used when runtime type differs from declared property type and `UseMetadata=false`. + +| Code | Name | Wire format | +|------|------|-------------| +| 72 | ObjectWithTypeName | `[72] [UTF8 typeName] [inner marker] [body...]` — prefix, inner Object/Array/Dict follows | +| 73 | ObjectWithTypeNameRefFirst | `[73] [UTF8 typeName] [VarUInt refCacheIndex] [properties...]` — combined, no inner marker | +| 74 | ObjectWithTypeIndex | `[74] [VarUInt typeIndex] [inner marker] [body...]` — prefix | +| 75 | ObjectWithTypeIndexRefFirst | `[75] [VarUInt typeIndex] [VarUInt refCacheIndex] [properties...]` — combined | + +Second occurrence of a referenced polymorphic object uses plain `ObjectRef(65)` — no polymorphic prefix needed. + +### Primitives (76–90) + +| Code | Name | Wire format | +|------|------|-------------| +| 76 | Null | `[76]` — no payload | +| 77 | True | `[77]` — no payload | +| 78 | False | `[78]` — no payload | +| 79 | Int8 | `[79] [1 byte]` | +| 80 | UInt8 | `[80] [1 byte]` | +| 81 | Int16 | `[81] [VarInt]` | +| 82 | UInt16 | `[82] [VarUInt]` | +| 83 | Int32 | `[83] [VarInt]` | +| 84 | UInt32 | `[84] [VarUInt]` | +| 85 | Int64 | `[85] [VarLong]` | +| 86 | UInt64 | `[86] [VarULong]` | +| 87 | Float32 | `[87] [4 bytes IEEE 754]` | +| 88 | Float64 | `[88] [8 bytes IEEE 754]` | +| 89 | Decimal | `[89] [16 bytes]` | +| 90 | Char | `[90] [VarUInt]` | + +### Strings (91–94) + +| Code | Name | Wire format | +|------|------|-------------| +| 91 | String | `[91] [VarUInt byteLength] [UTF-8 bytes]` | +| 92 | StringInterned | `[92] [VarUInt cacheIndex]` — 2nd+ occurrence | +| 93 | StringEmpty | `[93]` — no payload | +| 94 | StringInternFirst | `[94] [VarUInt cacheIndex] [VarUInt byteLength] [UTF-8 bytes]` — 1st occurrence | + +### Date/Time (95–98) + +| Code | Name | Wire format | +|------|------|-------------| +| 95 | DateTime | `[95] [8 bytes ticks]` | +| 96 | DateTimeOffset | `[96] [8 bytes ticks] [VarInt offsetMinutes]` | +| 97 | TimeSpan | `[97] [VarLong ticks]` | +| 98 | Guid | `[98] [16 bytes]` | + +### Other Markers + +| Code | Name | Wire format | +|------|------|-------------| +| 99 | Enum | `[99] [VarInt underlyingValue]` | +| 100 | MetadataHeader | Legacy: implies `RefHandling=true` + metadata present | +| 101 | NoMetadataHeader | Legacy: implies `RefHandling=true`, no metadata | +| 102 | PropertySkip | `[102]` — marks skipped property (default/null value) | + +### FixStr (103–134) + +Short ASCII strings encoded in a single marker byte + raw bytes (no length prefix): + +``` +[FixStrBase + byteLength] [ASCII bytes] +``` + +- Length range: 0–31 bytes (`FixStrBase=103`, `FixStrMax=134`) +- Saves 1 byte vs `String` marker + VarUInt length +- Falls back to `String(91)` if content is non-ASCII + +### TinyInt (192–255) + +Single-byte integer encoding for small values: + +``` +value = marker - 192 - 16 (range: -16 to 47) +marker = value + 16 + 192 (64 values total) +``` + +Saves 2+ bytes vs `Int32(83)` + VarInt for frequently occurring small integers. + +## Compact Encoding Selection + +The serializer applies compact encodings automatically: + +| Data | Condition | Encoding | Savings | +|------|-----------|----------|---------| +| Integer | −16 ≤ v ≤ 47 | TinyInt (1 byte) | 2–5 bytes | +| String | ≤31 bytes, ASCII | FixStr (1+N bytes) | 1 byte (no length prefix) | +| Object | type index < 64 | FixObj (1 byte) | 1–5 bytes (no VarUInt index) | +| String | empty | StringEmpty (1 byte) | 1+ bytes | +| Bool | — | True/False (1 byte) | no payload | + +## String Interning Protocol + +Controls deduplication of repeated string values. + +**Modes** (`StringInterningMode`): +- `None` — all strings inline, no overhead +- `Attribute` — only `[AcStringIntern]` properties interned (default) +- `All` — all strings within length limits interned + +**Length limits:** `MinStringInternLength=4`, `MaxStringInternLength=64` (configurable). + +**Wire protocol:** +1. Serializer pre-scans all eligible strings to build a plan (which strings repeat) +2. First occurrence: `[StringInternFirst(94)] [VarUInt cacheIndex] [VarUInt byteLength] [UTF-8 bytes]` +3. Subsequent: `[StringInterned(92)] [VarUInt cacheIndex]` +4. Single-occurrence strings: written as normal `String`/`FixStr` (no interning overhead) + +## Reference Tracking + +Prevents infinite loops and preserves object identity for repeated references. + +**Modes** (`ReferenceHandlingMode`): +- `None` — no tracking (fastest, use when graph is a tree) +- `OnlyId` — track only `IId` objects (matched by ID value) +- `All` — track all reference types (two-phase scan required) + +**Two-phase process:** +1. **Scan pass** (`ScanPass.cs`) — walks the object graph, detects multi-referenced objects and repeated strings. Builds a `WriteDuplicateEntry[]` array (the "write plan") containing `VisitIndex`, `CacheMapIndex`, `IsFirst`, and `Value` for each duplicate. +2. **Sort** — write plan entries are sorted by `VisitIndex` to match the write pass traversal order. +3. **Serialize pass** — consumes the sorted write plan via `TryConsumeWritePlanEntry()`. A cursor (`_nextWritePlanVisitIndex`) advances through the plan in O(1) — no dictionary lookups during serialization. + +**Wire protocol:** +- First occurrence: `[ObjectRefFirst(70)] [VarUInt refCacheIndex] [object body...]` +- Subsequent: `[ObjectRef(65)] [VarUInt refCacheIndex]` + +## Property Ordering + +Properties are serialized in a deterministic order defined by `TypeMetadataBase.GetUnfilteredProperties()`: + +1. Walk the inheritance chain from **derived → base** (`currentType.BaseType` loop) +2. At each level, collect declared public instance properties +3. Sort **alphabetically** (`StringComparer.Ordinal`) within each level +4. Result: **base properties first, then derived, alphabetical within each level** + +This order is stable across serializer/deserializer as long as the type hierarchy doesn't change. + +### Cross-Type Deserialization (UseMetadata) + +When `UseMetadata=true`, property name hashes (FNV-1a via `FnvHash.ComputeString`) are written per type, enabling schema evolution: + +- **Serializer** writes property hashes in the metadata section (`ObjectWithMetadata(69)`) +- **Deserializer** builds an index mapping array (`GetIndexMapping()`) that maps source property indices to destination indices by matching FNV-1a hashes +- This allows deserialization even when source and destination types have different property sets or ordering + +When `UseMetadata=false`, properties are matched by **positional index only** — source and destination must have identical property layouts. + +## Configuration Options + +Options defined in `AcBinarySerializerOptions` (inherits `AcSerializerOptions`). Each option controls which code paths execute and how the wire format changes. + +### WireMode + +| Value | Integers | Strings | Output size | Speed | +|-------|----------|---------|-------------|-------| +| `Compact` (default) | VarInt/VarUInt (1–5 bytes) | UTF-8 with speculative ASCII fast path | Smaller | Slightly slower | +| `Fast` | Fixed-width raw bytes (4/8 bytes) | UTF-16 memcpy (`charCount * 2` bytes) | Larger | Fastest encode/decode | + +**Format difference for strings:** +- Compact: `[VarUInt byteLength] [UTF-8 bytes]` — speculative ASCII (1 pass if all ASCII, rewind+UTF-8 fallback otherwise) +- Fast: `[VarUInt charCount] [raw UTF-16 bytes]` — zero-encoding memcpy + +**Code branch:** `context.FastWire` flag set at `context.Reset()`. Checked in `WriteStringUtf8()` and integer write methods. FixStr optimization is skipped in Fast mode (UTF-8 specific). + +### ReferenceHandling + +| Value | Tracked objects | Scan pass | Header flags | Wire markers | +|-------|----------------|-----------|--------------|-------------| +| `None` | Nothing | Skipped | `0x00` | Standard object markers only | +| `OnlyId` | `IId` objects only (by ID value) | Partial | `0x02` | `ObjectRefFirst(70)` + `ObjectRef(65)` | +| `All` (default) | All reference types | Full graph walk | `0x06` | `ObjectRefFirst(70)` + `ObjectRef(65)` | + +**Format impact:** When enabled, multi-referenced objects are written once with `ObjectRefFirst(70) + VarUInt(refCacheIndex)` on first encounter, then replaced by `ObjectRef(65) + VarUInt(refCacheIndex)` on subsequent encounters. Header `HasCacheCount` flag is set and cache count written. + +**Interaction with `ThrowOnCircularReference` (default: `true`):** +- `true` + ref handling enabled: all objects tracked for cycle detection, throws `InvalidOperationException` on circular reference +- `false` + ref handling enabled: only IId types tracked for deduplication, non-IId circular refs silently truncated at `MaxDepth` + +### UseMetadata + +| Value | Wire markers | Property matching | Overhead | +|-------|-------------|-------------------|----------| +| `false` (default) | `FixObj`/`Object` | Positional index only — types must match | None | +| `true` | `ObjectWithMetadata(69)` / `ObjectWithMetadataRefFirst(71)` | FNV-1a property name hashes | 4 bytes per property per type | + +**Format impact:** When enabled, each type's first occurrence writes `[VarUInt hashCount] [FNV-1a hash × N]` before properties. Deserializer uses hashes to build source→destination index mapping, enabling cross-type deserialization (different property sets/ordering). + +**Code branch:** `context.UseMetadata` controls whether `ObjectWithMetadata(69)` or plain `Object(64)` markers are used. When `false`, `IsDirectObjectWrite=true` allows source-generated writers to bypass `WriteObject` entirely and inline property writes. + +**Related:** `CheckDuplicatePropName` (default: `true`) — throws if FNV-1a hash collision detected between property names of the same type. Disable in production for performance. + +### UseStringInterning + +| Value | Eligible strings | Scan overhead | Wire markers | +|-------|-----------------|---------------|-------------| +| `None` | Nothing | None | `String(91)` / `FixStr` only | +| `Attribute` (default) | Properties with `[AcStringIntern(true)]` | Scans marked properties | `StringInternFirst(94)` + `StringInterned(92)` | +| `All` | All strings within length limits | Scans all strings | `StringInternFirst(94)` + `StringInterned(92)` | + +**Length limits:** `MinStringInternLength` (default: 4) and `MaxStringInternLength` (default: 64, 0=unlimited). Strings outside this range are always written inline. + +**Format impact:** Interned strings on first occurrence: `[StringInternFirst(94)] [VarUInt cacheIndex] [string data]`. Subsequent: `[StringInterned(92)] [VarUInt cacheIndex]` (1–2 bytes vs full string). Single-occurrence strings are never interned — no overhead for unique strings. + +**Code branch:** `context.StringInternEligible` flag set per-property before `WriteString`. Scan pass builds a `WriteDuplicateEntry[]` plan; write pass consumes it via cursor. + +### MaxDepth + +| Value | Behavior | +|-------|----------| +| `255` (default) | Effectively unlimited nesting | +| `0` | Root level only — nested objects/collections written as `Null(76)` | +| `N` | Objects deeper than N levels written as `Null(76)` | + +**Format impact:** Depth-exceeded values appear as `Null(76)` in the stream — indistinguishable from actual null values. No special marker. + +**Code branch:** Checked at entry of every object/collection write: `if (depth > MaxDepth) { WriteByte(Null); return; }`. + +### UseCompression + +| Value | Method | Granularity | Memory | +|-------|--------|-------------|--------| +| `None` (default) | No compression | — | — | +| `Block` | LZ4 single block | Entire payload | Full buffer in memory | +| `BlockArray` | LZ4 chunked | 64KB chunks | Streaming-friendly, lower peak memory | + +**Format impact:** Compression is applied **post-serialization** as a transparent wrapper — the inner wire format is unchanged. Both modes are pure managed C# (WASM-compatible, no native dependencies). + +**Code branch:** Applied in `AcBinarySerializer.Serialize()` after the serialization context produces the raw buffer: `if (UseCompression != None) Lz4.Compress(buffer, mode)`. Decompression is automatic on deserialize. + +### PropertyFilter + +Optional delegate `BinaryPropertyFilter?` (default: `null`). When set, invoked for each property to decide inclusion. + +``` +delegate bool BinaryPropertyFilter(in BinaryPropertyFilterContext context); +``` + +**BinaryPropertyFilterContext fields:** `DeclaringType`, `PropertyName`, `PropertyType`, `Instance` (null during metadata phase), `IsMetadataPhase`, `GetValue()` (lazy). + +**Format impact:** Excluded properties are completely absent from the stream — no marker, no placeholder. The deserializer must use `UseMetadata=true` or identical filter to correctly match property indices. + +**Code branch:** `context.HasPropertyFilter` checked in `ShouldSerializeProperty()`. Called twice: once during metadata registration (`Instance=null`), once during write phase. + +### PropertyMapper + +Optional delegate `PropertyMapperDelegate?` (default: `null`) for cross-type deserialization property remapping. + +``` +delegate PropertyInfo? PropertyMapperDelegate(PropertyInfo sourceProperty, Type destinationType); +``` + +**Purpose:** Maps properties between different class hierarchies (renamed properties, external DTOs). Result is cached — zero overhead on same-type operations (`Deserialize`). + +### WASM Options + +| Option | Default | Purpose | +|--------|---------|---------| +| `IsWasm` | `OperatingSystem.IsBrowser()` | Auto-detect WASM environment | +| `UseStringCaching` | follows `IsWasm` | Cache short strings during deserialization to reduce GC pressure | +| `MaxCachedStringLength` | 64 | Max string length to cache | + +**Format impact:** None — these are deserialization-only optimizations. When `UseStringCaching=true`, the deserializer maintains an intern cache for strings ≤ `MaxCachedStringLength` chars. Disabled automatically when `StringInternFirst` marker is encountered (interning takes precedence). + +### Other Options + +| Option | Type | Default | Purpose | +|--------|------|---------|---------| +| `UseGeneratedCode` | bool | `true` | Use source-generated writers/readers when available | +| `InitialBufferCapacity` | int | 4096 | Starting buffer size (bytes) for serialization output | +| `RemoveOrphanedItems` | bool | `false` | During `PopulateMerge`: remove destination collection items with no matching source ID | +| `UseAsync` | bool | `false` | Async context pool return via ThreadPool. Auto-disabled in WASM and when `ReferenceHandling=None` | +| `MaxContextPoolSize` | int | 8 | Max serialization contexts kept in pool | + +## Presets + +| Preset | WireMode | Metadata | StringInterning | RefHandling | MaxDepth | Compression | Other | +|--------|----------|----------|-----------------|-------------|----------|-------------|-------| +| `Default` | Compact | false | Attribute | All | 255 | None | — | +| `FastMode` | Compact | false | None | None | 255 | None | No scan pass | +| `ShallowCopy` | Compact | false | None | None | **0** | None | Root level only | +| `WasmOptimized` | Compact | false | Attribute | All | 255 | None | +StringCaching | +| `WithoutReferenceHandling` | Compact | false | Attribute | **None** | 255 | None | No scan pass | +| `WithoutMetadata` | Compact | **false** | Attribute | All | 255 | None | — | + +**Performance implication of presets:** +- `Default` / `WasmOptimized` — two-phase (scan + serialize) due to `ReferenceHandling=All` +- `FastMode` / `ShallowCopy` — single-phase (no scan pass) since both interning and refs are disabled +- The scan pass adds ~20-30% overhead; disable it when the object graph is a simple tree + +## Option Interactions + +Key interdependencies that affect which code branches execute: + +| Combination | Effect | +|-------------|--------| +| `ReferenceHandling=None` + `UseStringInterning=None` | **No scan pass** — fastest path, single-phase serialization | +| `ReferenceHandling=All` + `UseMetadata=true` | Uses `ObjectWithMetadataRefFirst(71)` marker — combined ref + metadata | +| `UseMetadata=false` + `UseGeneratedCode=true` | `IsDirectObjectWrite=true` — generated code inlines property writes, bypasses `WriteObject` | +| `UseMetadata=true` + `PropertyFilter` set | Filter invoked twice (metadata phase + write phase); filter results must be stable | +| `WireMode=Fast` + `UseStringInterning!=None` | Interned strings still use the fast string path (UTF-16 for first occurrence, VarUInt index for subsequent) | +| `UseCompression!=None` + any other option | Compression is orthogonal — applied post-serialization, inner format unchanged | diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md index 86cfd4c..de24725 100644 --- a/docs/CONVENTIONS.md +++ b/docs/CONVENTIONS.md @@ -29,13 +29,16 @@ - **TestDataFactory** for centralized test data creation with ID sequencing. - **Testable infrastructure** for SignalR: `TestableSignalRClient2`, `TestableSignalRHub2` bypass real connections. +## Code Reuse + +- Before writing new code, search the codebase for existing implementations. +- If a method does most of what you need, extract the shared part into a smaller reusable method rather than copying and modifying. +- Prefer composing existing helpers over creating parallel implementations. +- When adding a variation of existing logic, refactor the original into composable pieces that both call sites can use. + ## Critical Rules - **Never modify PasswordHasher salt/iteration logic** — breaks existing password verification. - **Never renumber LogLevel enum values** — synchronized with database. - **Never fix "Finnished" spelling** — intentional legacy typo in consuming projects. - **Never suggest removal as a solution** — find a fix instead. - ---- - -> **LLM Maintenance:** If you establish new conventions or patterns, document them here. diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 1597754..e6bac79 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -19,7 +19,21 @@ Core terminology for the AyCode framework. Read this before working on unfamilia | **Toon** | Token-Oriented Object Notation. LLM-optimized format with @meta (schema) and @data (values) sections. Designed for maximum LLM comprehension accuracy. | | **AcJson** | Newtonsoft.Json wrapper with $id/$ref reference handling, IId-based resolution, and chain deserialization API. | | **Chain API** | Fluent deserialization: `CreateDeserializeChain().ThenDeserialize()...Execute()`. Resolves cross-references across multiple types. | -| **String Interning** | Binary serializer deduplicates repeated strings. Controlled via `[AcStringIntern]` attribute or `enableInternString` flag. | +| **String Interning** | Binary serializer deduplicates repeated strings. Controlled via `[AcStringIntern]` attribute or `StringInterningMode`. See [BINARY_FORMAT.md](BINARY_FORMAT.md#string-interning-protocol). | + +## Binary Wire Format + +For full specification see [`BINARY_FORMAT.md`](BINARY_FORMAT.md). + +| Term | Definition | +|---|---| +| **BinaryTypeCode** | Single-byte marker that identifies the type of the next value in the binary stream. 100+ codes defined in `BinaryTypeCode.cs`. | +| **FixObj** | Compact object marker (0–63). The byte itself is the type slot index — no additional identifier needed. | +| **FixStr** | Compact string marker (103–134). Encodes type + length in one byte for ASCII strings ≤31 bytes. | +| **TinyInt** | Compact integer marker (192–255). Encodes small integers (−16 to 47) in a single byte. | +| **VarInt / VarUInt** | Variable-length integer encoding. LEB128 for unsigned, ZigZag + LEB128 for signed. | +| **HeaderFlags** | Byte at stream position 1 encoding serialization options: metadata, reference handling mode, cache count presence. Base `0x90`. | +| **Two-Phase Serialization** | Scan pass detects multi-referenced objects, serialize pass writes output using reference table. Required for `ReferenceHandling.All`. | ## Serialization Attributes @@ -56,7 +70,3 @@ Core terminology for the AyCode framework. Read this before working on unfamilia |---|---| | **AcLoggerBase** | Custom logger with Detail(0)→Debug(1)→Info(2)→Warning(3)→Suggest(4)→Error(5)→Disabled(255). Values are DB-synced — do not renumber. | | **GlobalLogger** | Server-side singleton (`AcGlobalLogger`) for cross-service logging. | - ---- - -> **LLM Maintenance:** If you modify code that changes terminology or introduces new abstractions, update this glossary.