AyCode.Core/docs/GLOSSARY.md

Glossary

Core terminology for the AyCode framework. Read this before working on unfamiliar areas.

Core Abstractions

Term	Definition
IId	Generic identity interface (T = Guid or int). Foundation of the entity system.
TrackingState	Client-side change tracking enum: Added, Modified, Deleted, Unchanged. Not related to EF Core tracking.
IForeignKey	Marker interface for navigation property foreign keys.
IForeignCollection	Marker for collection navigation properties.

Serialization Formats

Term	Definition
AcBinary	High-performance binary serializer. Two-phase: scan (collect metadata) then serialize. Supports reference tracking, string interning, ID-based deduplication.
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<T>().ThenDeserialize<U>()...Execute(). Resolves cross-references across multiple types.
String Interning	Binary serializer deduplicates repeated strings. Controlled via [AcStringIntern] attribute or StringInterningMode. See AyCode.Core/docs/BINARY_FEATURES.md.

Binary Wire Format

For full specification see AyCode.Core/docs/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.
SequenceBinaryInput	struct : IBinaryInputBase for reading from ReadOnlySequence<byte> (multi-segment pipe data). Lazy iteration via TryGet — zero constructor allocation. Context _buffer points directly to segment backing byte[] (zero-copy). Cross-boundary values use ArrayPool-rented scratch buffer (rent once, reuse, Release() returns). N-segment loop handles values spanning any number of segments.
ArrayBinaryInput	struct : IBinaryInputBase for reading from contiguous byte[]. Zero-copy when pipe is single-segment. Default fast-path for deserialization.
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

Attribute	Purpose
[AcBinarySerializable]	Marks type for source generator. Feature flags: enableMetadata, enableIdTracking, enableRefHandling, enableInternString.
[AcStringIntern]	Marks string property for deduplication during binary serialization.
[ToonDescription]	Per-property description for Toon @meta output.

Architecture Layers

Layer	Projects	Role
Interfaces	AyCode.Interfaces, .Server	Contracts only — no implementation
Entities	AyCode.Entities, .Server	Abstract generic base classes
Models	AyCode.Models, .Server	DTOs, view models
Services	AyCode.Services, .Server	Business logic, SignalR
Database	AyCode.Database	EF Core DAL with Session/Transaction pattern
Core	AyCode.Core, .Server	Serializers, compression, logging, constants
Utils	AyCode.Utils, .Server	Zero-dependency utilities

Database Patterns

Term	Definition
DAL (Data Access Layer)	AcDalBase — mutex-protected, supports Session (read) and Transaction (write) patterns.
PooledDal	Singleton pool managing DAL instances by SessionId/PlayerId.
Session	Read-only database operation pattern. No transaction, no mutex lock on DbContext.
Transaction	Write operation pattern with auto-rollback on failure.

SignalR Infrastructure

For full architecture see AyCode.Services/docs/SIGNALR.md.

Term	Definition
OnReceiveMessage	The single SignalR method for all communication. Signature: (int messageTag, int? requestId, SignalParams signalParams, object data). Metadata and payload are separate hub arguments. data is typed object (protocol eagerly deserializes via SignalDataType), raw byte[] (IsRawBytesData or byte[] fast-path), or null. SignalParams.Parameters carries packed method params as byte[]. Both are independent and nullable in any direction.
SignalParams	Metadata sent alongside message payload as separate hub argument. Contains Status, DataSerializerType, Parameters (byte[]? — packed byte[][] as single blob), SignalDataType (string? — response type for eager deserialization), IsRawBytesData (bool — return raw bytes without deserialization). Typed access via SetParameterValues(object[]) / GetParameterValues(ParameterInfo[]) — PostDataJson pattern. [AcBinarySerializable]. Never null — only fields inside are nullable.
Message Tag	Integer identifier mapping to a method via [SignalR(tag)] or [SignalRSendToClient(tag)] attributes.
DynamicMethodRegistry	Resolves message tags to MethodInfo at runtime. Static ConcurrentDictionary cache with lazy scan on miss.
SignalRCrudTags	Sealed class bundling 5 independent tag integers (getAllTag, getItemTag, addTag, updateTag, removeTag) for entity CRUD. See AyCode.Services.Server/docs/SIGNALR_DATASOURCE.md.
AcBinaryHubProtocol	Unsealed base IHubProtocol replacing SignalR's JSON+Base64 with AcBinarySerializer. Protocol name: "acbinary". Write: BufferWriterBinaryOutput standalone + AcBinarySerializer.Serialize(value, output) zero-copy to pipe. Read: SequenceReader<byte> from pipe's ReadOnlySequence, three-path argument deser (byte[] fast-path, IsRawBytesData, typed via SignalDataType). _currentSignalParams captures arg[2] for type-aware arg[3] deserialization.
AyCodeBinaryHubProtocol	Derived protocol (currently empty). Exists for registration and future project-specific hooks. Register this in both client and server.
SignalResponseDataMessage	Internal DTO for client callback routing and stream wire format (not serialized as envelope on wire). RawResponseData is object? (typed object or byte[]). GetResponseData<T>() performs direct cast.
SignalPostJsonDataMessage	OBSOLETE — still exists but marked [Obsolete]. Legacy: serialized params to JSON inside Binary envelope.
AcSignalRDataSource	Generic real-time IList<T> with change tracking, CRUD via SignalRCrudTags, binary merge, rollback, sync state.
TrackingItem	Wraps a modified DataSource item with TrackingState (Add/Update/Remove) + OriginalValue for rollback.
SendToClientType	Enum controlling broadcast scope: None, Others, Caller, All.
AcWebSignalRHubBase	Abstract server hub. Receives OnReceiveMessage (with object data), dispatches via DynamicMethodRegistry, responds via SendMessageToClient (builds response SignalParams with SignalDataType + passes object responseData — protocol zero-copy serializes to pipe).
AcSignalRClientBase	Abstract client. Manages HubConnection, request/response correlation via requestId, pooled SignalRRequestModel. SendCoreAsync builds SignalParams (with IsRawBytesData when T == byte[]).
AcSessionService	ConcurrentDictionary-based session tracker for connected SignalR clients.
AcSignalRSendToClientService	Server-push service: SendMessageToAllClients, SendMessageToConnection, SendMessageToUser.
Working Reference List	DataSource feature: SetWorkingReferenceList() allows external list to become inner storage (zero-copy).

Logging

For full architecture see AyCode.Core/docs/LOGGING.md.

Term	Definition
LogLevel	Byte enum: Detail(0), Trace(5), Debug(10), Info(15), Suggest(17), Warning(20), Error(25), Disabled(255). Values are DB-synced — do NOT renumber.
AcLoggerBase	Abstract logger with multi-writer fan-out. Two-level filtering: logger-level + per-writer level. Implements both IAcLogWriterBase and MS ILogger.
AcLogWriterBase	Abstract writer base. Own LogLevel loaded from appsettings by AssemblyQualifiedName match. Two branches: text (AcTextLogWriterBase) and structured (AcLogItemWriterBase<T>).
AcTextLogWriterBase	Text formatting base. Format: [HH:mm:ss.fff] [AppType[0]] [Level] [Category->Method] [ThreadId] Text.
AcConsoleLogWriter	Colored console writer. Gray=≤Trace, Cyan=Suggest, Yellow=Warning, Red=≥Error. Thread-safe via static lock.
AcLogItemWriterBase<T>	Abstract structured writer. ThreadPool dispatch + Mutex serialization. Activator.CreateInstance<T>() factory for log items.
GlobalLogger	Server-side singleton wrapping AcGlobalLoggerBase. Static methods for all log levels. Default category: "GLOBAL_LOGGER".
AcLoggerProvider<T>	ILoggerProvider implementation with ConcurrentDictionary<string, T> per-category cache. Registered via AddAcLogger<T>() or UseOnlyAcLogger<T>().
IAcLogItemClient	Structured log item DTO interface. Fields: TimeStampUtc, AppType, LogLevel, ThreadId, CategoryName, CallerName, Text, Exception, ErrorType.
AcLogItemClient	[MessagePackObject] implementation of IAcLogItemClient. Client-side transport entity.
AcLogItem	Server-side entity extending AcLogItemClient. [Table("LogItem")] with auto-generated Id and LogHeaderId.
AcLoggerSignalRHub<T>	Server hub receiving log items via AddLogItem(AcLogItem). Simple Hub (not tag-based dispatch).
IAcLogWriterClientBase	Empty marker interface for client-side writers (: IAcLogWriterBase).