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/AyCode.Core/docs/BINARY/BINARY_FEATURES.md.

Binary Wire Format

For full specification see AyCode.Core/AyCode.Core/docs/BINARY/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/README.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/SIGNALR_DATASOURCE.md.
AcBinaryHubProtocol	Unsealed base IHubProtocol replacing SignalR's JSON+Base64 with AcBinarySerializer. Protocol name: "acbinary" (configurable). Options-based ctor: new AcBinaryHubProtocol(AcBinaryHubProtocolOptions). Write: BufferWriterBinaryOutput / AsyncPipeWriterOutput zero-copy to pipe. Read: ArrayBinaryInput via GetArgBytes (zero-copy single-seg / pool-rent multi-seg) for non-chunked; chunked receive via SegmentBufferReader + SegmentBufferReaderInput with platform-aware fallback.
AyCodeBinaryHubProtocol	Consumer-specific derived protocol (per-message header with DataFlags, IsRawBytesData, type resolution). Registered via services.AddSignalR().AddAcBinaryProtocol(...) on the server and hubBuilder.AddAcBinaryProtocol(...) on the client.
AcBinaryHubProtocolOptions	Mutable config class for protocol registration. Properties: SerializerOptions, ProtocolMode, BufferSize, WaitForFlush, FlushTimeout, Name, Logger. Validate() enforces invariants (incl. WASM + AsyncSegment block). Clone() for DI IOptions<T> safety.
AcSignalRProtocolExtensions	DI extension class: AddAcBinaryProtocol(ISignalRServerBuilder, Action<AcBinaryHubProtocolOptions>?) for server, AddAcBinaryProtocol(IHubConnectionBuilder, Action<...>?) for client. DI IOptions<T> + inline-configure override chain.
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/AyCode.Core/docs/LOGGING/README.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).