# Symmetric Sync Protocol Architecture

This document details the architecture of the `ibgib` Symmetric Sync Protocol. It describes the "Saga" model, the state machine, and the data structures used to ensure robust, audit-trail-based synchronization.

## 1. Core Principles

### 1.1 The Saga Model
Synchronization is not a stateless request/response. It is a **Saga**: a durable, linear timeline of immutable frames that represents the conversation between two peers.
*   **Audit Trail**: The Saga Timeline (`SyncIbGib`) records every step (`Init`, `Ack`, `Delta`, `Commit`).
*   **Symmetry**: Both peers (Alice and Bob) run the exact same `SyncSagaCoordinator`. There is no "Client" or "Server" code, only "Initiator" and "Reactor".

### 1.2 Smart Diff (Partial Updates)
To optimize bandwidth, the protocol exchanges "Knowledge Maps" to calculate the precise difference between peers.
*   **Knowledge Map**: A summary of what a peer knows (Timelines, Tips, and Ancestors).
*   **Space-Side Dependency Graph**: The `Space.getDependencyGraph` capability allows the "Network" layer to request *only* the new nodes in a graph, skipping everything the receiver already has.

## 2. Protocol Workflow (The State Machine)

The `SyncSagaCoordinator` drives a Finite State Machine (FSM) via the `handleSagaFrame` method.

### 2.1 The Ping-Pong Flow

1.  **Start (Initiator)**:
    *   Initiator (Alice) calls `startSaga`.
    *   Generates `Init` frame containing her `KnowledgeMap` and `Mode` (Push/Pull/Sync).
    *   Sends `Init` to Bob.

2.  **Gap Analysis (`handleInitFrame`)**:
    *   Reactor (Bob) receives `Init`.
    *   Bob compares Alice's `KnowledgeMap` against his own local space.
    *   **Identifies Gaps**:
        *   **Delta Request**: "Alice has `X`, I don't. Send me `X`."
        *   **Push Offer**: "I have `Y` (newer than Alice's). Do you want `Y`?"
    *   Bob sends `Ack` frame containing `deltaReqAddrs` and `pushOfferAddrs`.

3.  **Payload Generation (`handleAckFrame`)**:
    *   Alice receives `Ack`.
    *   **Process Requests**: Iterates `deltaReqAddrs` (what Bob wants).
    *   **Smart Diff**: Uses Bob's `KnowledgeMap` (sent in Ack) to exclude all shared history.
    *   **Payload**: Generates a bundle of new ibGibs.
    *   Alice sends `Delta` frame containing the payload.

4.  **Convergence (`handleDeltaFrame`)**:
    *   Bob receives `Delta`.
    *   **Verifies**: Checks hashes (`ib` vs `gib`) and signatures.
    *   **Merges**: Puts data into his local space.
    *   Bob sends `Commit` frame.

5.  **Completion (`handleCommitFrame`)**:
    *   Alice receives `Commit`.
    *   Saga ends.

## 3. Data Structures

### 3.1 SyncSagaMessage
All frames are `SyncIbGib`s carrying specific data payloads.

*   `sagaId`: Unique UUID for the session.
*   `stage`: `init` | `ack` | `delta` | `commit` | `conflict`.
*   `knowledgeMap`: `{ [tjpAddr]: [tipAddr, ...ancestors] }`.

### 3.2 Constants vs Timelines
The protocol supports two types of data:
*   **Timelines**: Mutable data with a "Temporal Junction Point" (TJP). Syncing involves finding the "Latest" tip.
*   **Stones (Constants)**: Immutable data without a history (e.g., Code lists, Configs). Syncing involves simple existence checks.

## 4. Security & Identity
*   **Session Keystone**: Each Saga typically generates an ephemeral identity to sign frames, linked to a master identity.
*   **Trust Chain**: Each frame points to the previous one (`past` rel8n), creating a hash-linked chain of custody.
