# AyCode.Core — Domain Rules

@repo {
  type = "framework"
  layer = 0
  own-dep-repos = []
}

> This is the **single source of truth** for domain rules. Do not duplicate these elsewhere.
> For detailed docs see: `README.md` → `docs/`

## Key Abstractions
1. **IId<T>** is the foundation interface — almost every entity implements it. Always preserve ID integrity.
2. **Generic entity hierarchy**: Interfaces (`AyCode.Interfaces`) → Entities (`AyCode.Entities`) → Models (`AyCode.Models`). Entities are abstract generics; concrete types live in consuming projects.
3. **TrackingState** enum (Added/Modified/Deleted/Unchanged) drives client-side change tracking, not EF Core.

## Serialization
4. **Toon** (Token-Oriented Object Notation) — primary goal is **LLM accuracy**. @meta/@data sections.
5. **AcBinary** — primary goal is **speed**. Two-phase scan+serialize, reference tracking, string interning.
6. **AcJson** — Newtonsoft.Json wrapper with $id/$ref, IId-based reference resolution, and chain API.

## SignalR
7. **Single-method transport** — all SignalR communication uses `OnReceiveMessage(tag, bytes, requestId)`. Tags are `int` constants resolved via `DynamicMethodRegistry`. Never add conventional hub methods.
8. **AcSignalRDataSource** — generic `IList<T>` with change tracking, CRUD via `SignalRCrudTags`, binary merge, rollback. See `AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md`. Transport docs: `AyCode.Services/docs/SIGNALR.md`.
9. **JSON-in-Binary tech debt** — client→server request parameters are currently JSON inside a Binary envelope (`SignalPostJsonDataMessage`). Do NOT attempt to fix as a side effect — requires coordinated changes across all consuming projects.

## Critical Warnings
10. **PasswordHasher** — PBKDF2-HMAC-SHA512. Do NOT modify the salt logic or iteration count — existing passwords become unverifiable.
11. **MeasuringStatus.Finnished** — intentional legacy typo in consuming projects. Do NOT fix the spelling.
12. **LogLevel enum values** — synchronized with database. Do NOT renumber.

## Conventions
13. Do not suggest removal/rollback as a solution — find a fix for the problem.
14. Extension methods over instance methods for CRUD operations (see DbSets pattern).
15. Session pattern for reads, Transaction pattern for writes (see DataLayers).
16. **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.
17. **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.
18. **Keep all .md files in sync** — when you modify code, update any affected .md file in the same area. If you already read an .md file during your work and notice it contradicts the current code, fix the discrepancy — but do NOT proactively scan or open .md files just to check for issues.
19. **Documentation layering** — write `.md` documentation at the **defining layer** (where the code lives). Higher-layer `.md` files reference the base docs (e.g. `see AyCode.Core/docs/SIGNALR.md`) and document only project-specific overrides or extensions. Never duplicate base-layer descriptions in consumer-level docs.