# ViceSharp Architecture

## Design Philosophy

ViceSharp is a **library-first** emulator: the emulation engine is a set of composable .NET libraries. UI shells (console, Avalonia desktop, and the platform host shells) are thin consumers.

### Core Principles

1. **POCO model**: All emulator state lives in plain C# structs and records. No base classes, no ORM, no serialization attributes on hot-path types.
2. **Zero-allocation hot path**: The per-cycle emulation loop allocates zero managed objects. All transient data uses stack allocation, spans, or arena-pooled buffers.
3. **Deterministic**: Given identical initial state and input sequence, execution is bit-exact reproducible. This enables snapshot comparison, replay, and regression testing.
4. **Trim-aware managed runtime**: No reflection on the hot path. Source generators replace runtime discovery where useful. Supported desktop packaging is self-contained JIT + ReadyToRun rather than native ahead-of-time publishing.
5. **MVVM**: ViewModels reference only `ViceSharp.Abstractions`. Views contain zero logic. The emulation engine has no UI dependencies.
6. **Host/UI boundary**: UI control, media, session, input, snapshot, capture, and diagnostic operations communicate with `ViceSharp.Host` through versioned gRPC services or narrow gRPC-backed client abstractions. The host owns emulator sessions, devices, media, snapshots, diagnostics, and local render-source composition.

## Assembly Structure

```
ViceSharp.Abstractions     50 interface files: interfaces, value types, attributes
    |
    +-- ViceSharp.Core         Bus, clock, mutation queue, pub/sub, snapshots, media recorders
    |       |
    |       +-- ViceSharp.Chips          CPU, VIC-II, SID, CIA, VIA, PLA implementations
    |       |
    |       +-- ViceSharp.Architectures  Machine definitions (C64, C1541 drive, ad-hoc/multisystem)
    |
    +-- ViceSharp.SourceGen    Roslyn source generator (device registration)
    |
    +-- ViceSharp.Monitor      Debugger/monitor engine
    |
    +-- ViceSharp.Host         Composition boundary: emulator sessions, service registration, gRPC host surface
    |       |
    |       +-- ViceSharp.Host.Android / .iOS / .MacOS           Platform host shells
    |
    +-- ViceSharp.Protocol     gRPC/protobuf contracts and generated client/server types
    |
    +-- ViceSharp.Launcher     VICE-style command-line parsing and machine topology building
    |
    +-- ViceSharp.Console      CLI/reference shell
    |
    +-- ViceSharp.Avalonia     Desktop UI (Avalonia 12.x)
    |
    +-- ViceSharp.AdhocHelper  Ad-hoc machine configuration helper UI (Avalonia)
    |
    +-- ViceSharp.RomFetch     ROM download/validation tool
    |
    +-- ViceSharp.Core.Package Packaging shell for the ViceSharp.Core NuGet bundle
                               (Abstractions + Chips + RomFetch + Core + Architectures)
```

## Host/UI gRPC Boundary

`ViceSharp.Host` is the composition boundary for UI-facing emulator sessions. It creates machines from architecture descriptors, owns media and state services, and exposes control, remote output, input, media, snapshot, capture, and diagnostic operations through TR-GRPC-BOUNDARY-001.

UI control clients consume the nine proto services defined in `src/ViceSharp.Protocol/Protos/emulator_host.proto`:
- `EmulatorHost`: session lifecycle and execution control (create session, status, start/pause/resume, cold/warm reset, autostart, step/rewind by cycle or frame, limiter rate, shutdown).
- `SettingsService`: settings profiles (list, get, update) and resource validation.
- `MediaService`: disk/tape/cartridge attach, eject, listing, and media status streaming.
- `VideoService`: video status, single-frame fetch, and frame streaming for remote UIs.
- `InputService`: normalized keyboard/joystick state, input state queries, and keyboard-map selection.
- `MonitorService`: debugger surface (monitor commands, registers, disassembly, breakpoints, memory read/write, tick-history and at-tick state queries).
- `SnapshotService`: snapshot capture and restore.
- `CaptureService`: screenshots, sound recording, and video recording (see Media Capture below).
- `DiagnosticsService`: host info, session enumeration, and performance snapshots/streams.

The in-process Avalonia renderer is a narrow host-owned exception for frame presentation: it may bind directly to a local emulator/frame source so local rendering does not have to route frame buffers through gRPC. That binding belongs in the host/composition or render-surface layer, not in ViewModels, and it does not allow UI code to mutate emulator devices.

External or remote UIs use the gRPC video service/stream APIs where direct in-process rendering is unavailable. The UI control layer does not hold direct references to live core devices. Generated gRPC clients are adapted behind ViewModel-facing abstractions so TR-MVVM-001 remains enforceable.

## Device Model

Every hardware component is an `IDevice` with a unique `DeviceId`. Devices are registered with the bus and optionally subscribe to the system clock.

```
IDevice
    IClockedDevice          - receives clock ticks
    IAddressSpace           - maps address ranges on the bus
    IInterruptSource        - can raise IRQ/NMI
    IPeripheral             - external device (drive, datasette)
```

Devices are wired together by an `IArchitecture` which describes:
- Which devices exist
- Address space mappings (including bank-switched overlays)
- Clock divisors and phase relationships
- Interrupt routing

## Bus and Address Decoding

The `IBus` provides a flat 64KB address space. Address decoding is performed by the architecture's PLA/banking logic, which routes reads and writes to the correct `IAddressSpace` implementor.

For the C64:
- RAM underlays the entire 64KB
- ROM (BASIC, KERNAL, CHARGEN) overlays configurable regions
- I/O area ($D000-$DFFF) maps to VIC-II, SID, CIA1, CIA2, color RAM
- PLA control lines (from CPU port at $0000/$0001) select the active configuration

## Mutation Queue

All state changes flow through an `IMutationQueue`. Each mutation is a small struct describing: source device, target address/field, old value, new value, cycle timestamp.

Benefits:
- **Auditing**: full history of every state change
- **Undo**: reverse mutations for debugging
- **Determinism**: replay mutations to reproduce exact state
- **Networking**: serialize mutation stream for netplay

The queue is double-buffered: the emulation thread writes to the active buffer while consumers (UI, debugger, recorder) read the committed buffer.

## Pub/Sub and Message Pool

High-frequency inter-device communication (interrupt signals, DMA requests, bus contention notifications) uses a lock-free pub/sub system.

- `IMessagePool`: pre-allocates message slots to avoid allocation
- `PayloadArena`: bump allocator for variable-size payloads within a frame
- `MessageHandle`: reference-counted handle into the pool
- `IPubSub`: topic-based publish/subscribe with zero-copy delivery

The pool and arena reset at frame boundaries, making per-frame allocation effectively free.

## State and Snapshots

The `ISnapshot` interface captures the complete machine state as a flat byte array. Snapshots are:
- **Serializable**: save/load to disk
- **Comparable**: byte-exact comparison for determinism testing

The `StateWindow` concept (configurable snapshot interval, history depth, and memory budget) is an unimplemented design proposal; see `docs/StateWindow.md`. The shipped rewind surface is the tick-history write-delta capture (`TickHistoryRecorder` in `ViceSharp.Host`, exposed through `MonitorService`).

## Clock and Timing

The system clock drives all cycle-accurate behavior. Each `IClockedDevice` receives ticks at its configured rate (which may differ from the master clock via divisors).

For the C64:
- Master clock: ~985,248 Hz (PAL) or ~1,022,727 Hz (NTSC)
- CPU: master / 1 (same as master)
- VIC-II: master / 1 (interleaved with CPU via bus phases)
- SID: master / 1 (but updates at its own internal rate)
- CIA timers: count CPU cycles or external events

## Architecture Registration

Architectures are defined as `IArchitectureDescriptor` implementations. The `IArchitectureBuilder` is the assembly boundary between the selected system core and concrete chip instances. It constructs a running `IMachine` from a descriptor:

1. Select the machine profile's system-core definition
2. Instantiate devices listed in the descriptor
3. Wire chips, address spaces, buses, interrupt lines, clocks, ROM, and peripherals according to that system-core policy
4. Register the system core and chips in the machine device registry
5. Validate (no overlapping address ranges, required devices present)

The `IArchitectureValidator` catches configuration errors at build time, not runtime.

## Media Capture

ViceSharp exports emulator output through one gRPC `CaptureService` surface
(`GetCaptureCapabilities`, `CaptureFrame`, `StartCapture`, `StopCapture`,
`ListCaptures`). The host implementation (`CaptureServiceHost`) routes each request
to a concrete recorder in `ViceSharp.Core.Media`:

| Facility | Format(s) | Recorder | Tee point |
|----------|-----------|----------|-----------|
| Screenshot (one-shot) | `png`, `bmp` | `FrameCapture.CaptureBgraAsync` | reads the committed frame buffer |
| Video (frame sequence) | `bmpseq` (numbered 24-bit BMPs) | `FrameSequenceCapture` (`AllFrames` / `UniqueFrames`) | `EmulatorRuntimeSession.CommitFrame` |
| Video (muxed, with sound) | `mp4`, `mkv`, `avi` | `FfmpegVideoRecorder` (external ffmpeg) | `CommitFrame` (video) + `CaptureAudioTap` (audio) |
| Sound | `wav` (16-bit PCM) | `WavAudioRecorder` | `CaptureAudioTap` in the SID -> output path |

Key design points:

- **Two tee points, one worker thread.** Completed frames are teed from
  `CommitFrame` and SID samples from `CaptureAudioTap`, both on the emulation
  worker. A capture-only lock (`_captureSync`) keeps this off the lock-free UI
  frame-read path, and a recorder fault can never propagate onto the worker.
- **`IVideoCaptureSink`** unifies the BMP-sequence and ffmpeg recorders so the
  session drives either through one surface. The ffmpeg recorder also implements
  `IAudioRecorder`, so a single object receives both video frames and audio.
- **External ffmpeg, not libav.** `FfmpegVideoRecorder` mirrors VICE's
  `ffmpegexedrv`: it opens two loopback TCP servers, launches `ffmpeg` as a client
  of both, and streams raw BGRA video + s16le PCM for muxing into the chosen
  container. `FfmpegLocator` finds the binary (PATH or `VICESHARP_FFMPEG`), and the
  muxed formats are advertised by `GetCaptureCapabilities` only when ffmpeg is
  present. Launch happens off the session lock.
- **Parity-preserving audio tap.** `CaptureAudioTap` is installed in the SID audio
  path only when a real audio device exists, so headless and test hosts keep the
  SID silent (no timing perturbation) and simply advertise no sound/muxed-video
  capture.

The capture client surface is exposed to the Avalonia UI through
`IHostProtocolClient` (Snapshot menu: Save screenshot, Record sound, Record video).