# BINARY — AcBinary serializer

AcBinary serialization system. Primary goal: **speed** (two-phase scan+serialize, reference tracking, string interning).

## Files in this folder

- [`BINARY_WHYUSE.md`](BINARY_WHYUSE.md) — Architectural framing: why AcBinary exists (category vs wire-only serializers, three-pillar value proposition, fit/not-fit decision lists, benchmark reading guide)
- [`BINARY_FEATURES.md`](BINARY_FEATURES.md) — High-level features and capabilities
- [`BINARY_FORMAT.md`](BINARY_FORMAT.md) — Wire format specification
- [`BINARY_OPTIONS.md`](BINARY_OPTIONS.md) — Configuration options (`AcBinaryOptions`)
- [`BINARY_IMPLEMENTATION.md`](BINARY_IMPLEMENTATION.md) — Internal implementation details
- [`BINARY_WRITERS.md`](BINARY_WRITERS.md) — Writer internals (streaming, buffering)
- [`BINARY_SGEN.md`](BINARY_SGEN.md) — Source generator (`AyCode.Core.Serializers.SourceGenerator`)
- [`BINARY_ISSUES.md`](BINARY_ISSUES.md) — Known issues and limitations (binary serializer core)
- [`BINARY_TODO.md`](BINARY_TODO.md) — Planned work / open tickets (binary serializer core)
- [`BINARY_ASYNCPIPE_ISSUES.md`](BINARY_ASYNCPIPE_ISSUES.md) — Known issues and limitations (streaming I/O layer: `AsyncPipeReaderInput` + `AsyncPipeWriterOutput`)
- [`BINARY_ASYNCPIPE_TODO.md`](BINARY_ASYNCPIPE_TODO.md) — Planned work / open tickets (streaming I/O layer)

## Start here

Start with [`BINARY_WHYUSE.md`](BINARY_WHYUSE.md) (architectural framing — why this serializer over the alternatives), then [`BINARY_FEATURES.md`](BINARY_FEATURES.md) (feature overview), then [`BINARY_FORMAT.md`](BINARY_FORMAT.md) (wire-level). [`BINARY_SGEN.md`](BINARY_SGEN.md) covers build-time code-gen integration.

## Cross-references

- **Serialization overview** (Toon vs AcBinary vs AcJson, shared infrastructure): `../../Serializers/README.md`
- **SignalR binary transport** (uses this serializer): `../../AyCode.Services/docs/SIGNALR_BINARY_PROTOCOL/README.md`
- **ASP.NET Core MVC formatter** (uses this serializer): `../../AyCode.Services/docs/MVC/README.md`
- **Glossary terms**: `../../../docs/GLOSSARY.md`

## Related ADRs

- [`AyCode.Core/docs/adr/0003-acbinary-streaming-receive-architecture.md`](../../../docs/adr/0003-acbinary-streaming-receive-architecture.md) — Receive-side streaming architecture (Status: Accepted 2026-05-03, partially executed). Delivered: `SegmentBufferReader` + `SegmentBufferReaderInput` consolidated into a single `AsyncPipeReaderInput` primitive (mirrors send-side `AsyncPipeWriterOutput`); SignalR receive-side migration completed. Dropped during execution: NamedPipe + FileStream helpers (Steps 4 & 5) — framework stays consumer-implements-transport, exposes only generic `PipeWriter` / `PipeReader` primitives.