@ibgib/core-gib 0.1.59 → 0.1.60

package/src/sync/docs/ping_pong_plan.md

@@ -1,147 +0,0 @@
-# Phase 3: Ping Pong Sync with Identity Plan
-
-This document details the step-by-step execution flow, space-routing rules, and verification requirements for implementing Phase 3 (Basic Single-Timeline Sync with Identity).
-
-## Core Concepts & Terms
-*   **Durable Space**: Persistent local database/filesystem storage (`localSpace`).
-*   **Temporary Space**: In-memory or transient storage (`tempSpace`) used during the sync saga to accumulate uncommitted domain data.
-*   **Control/Saga IbGibs**: The sync saga timeline, saga message stones, context envelopes, and session identity evolutions. These represent the protocol communication and auditing trail.
-*   **Domain IbGibs**: The actual user timelines, files, or payload data being synchronized.
-*   **Sender (Alice / Initiator)**: The node that generates and signs all request turns using the ephemeral Session Keystone ($S$).
-*   **Receiver (Bob / Sovereign Broker / Reactor)**: The node that validates the sender's cryptographic turns and replies with unsigned contexts echoing the same session identity.
-
-### Note on "Domain" Overloaded Term
-
-The term "domain" is overloaded at this point WRT sync and identity contexts. In this sync context, "domain" refers to ibgibs in the business logic domain, i.e., the actual data we're working with. This is in contrast to the identity context, in which "domain" means the identity boundary created with a main identity keystone. Neither usage is easily refactorable in code, hence the term overloading.
-
-**TL;DR - Sync: "domain" vs "control". Identity: "domain" keystone vs. "session" keystone**
-
----
-
-## Storage & Routing Rules (Security Boundary)
-
-| IbGib Category | Target Space (Validation Phase) | Target Space (Commit Phase) | Rationale |
-| :--- | :--- | :--- | :--- |
-| **Control / Saga** | Durable Space (`localSpace`) | Durable Space (`localSpace`) | Must be persisted ASAP after authentication/validation per exchange between endpoints to maintain a tamper-evident audit trail, even if the sync fails midway. |
-| **Domain Payloads** | Temporary Space (`tempSpace`) | Durable Space (`localSpace`) | Avoids polluting the durable space with unverified or partial data before a transaction successfully commits. |
-
----
-
-## Detailed Leg-by-Leg Execution Flow
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor Alice as Sender (Alice)
-    actor Bob as Receiver (Bob)
-
-    Note over Alice: Leg 1: Init (Sign & Post)
-    Alice->>Alice: Sign/Evolve S -> S_init
-    Alice->>Alice: Bind context.rel8ns.sessionIdentity = S_genesis
-    Alice->>Alice: Bind context.signedSessionIdentity = S_init
-    Alice->>Bob: Send Context (with S_init frame)
-    Note over Bob: Authenticate S_init independently
-    Bob->>Bob: Save Context & S_init to Durable Space
-
-    Note over Bob: Leg 2: Ack (Passive Validation)
-    Bob->>Bob: Prepare Ack context
-    Bob->>Bob: Bind context.rel8ns.sessionIdentity = S_init
-    Note over Bob: (No new evolution / signedSessionIdentity = undefined)
-    Bob->>Alice: Return Ack Context
-
-    Note over Alice: Leg 3: Delta (Sign & Payload)
-    Alice->>Alice: Process Ack requests
-    Alice->>Alice: Sign/Evolve S_init -> S_delta
-    Alice->>Alice: Bind context.rel8ns.sessionIdentity = S_init
-    Alice->>Alice: Bind context.signedSessionIdentity = S_delta
-    Alice->>Bob: Send Delta Context + Domain Payloads
-    Note over Bob: Authenticate S_delta independently
-    Bob->>Bob: Save Context & S_delta to Durable Space
-    Bob->>Bob: Save Domain Payloads to Temp Space
-
-    Note over Bob: Leg 4: Commit (Passive Verification)
-    Bob->>Bob: Prepare Commit context
-    Bob->>Bob: Bind context.rel8ns.sessionIdentity = S_delta
-    Bob->>Alice: Return Commit Context
-    Bob->>Bob: Move Domain Payloads (Temp -> Durable)
-    Alice->>Alice: Move Domain Payloads (Temp -> Durable)
-```
-
-### Leg 1: Init (Sender $\to$ Receiver)
-1. **Sender (Alice)**:
-   * [ ] Generates the `Init` message frame.
-   * [ ] Signs and evolves the session identity from $S_{genesis}$ to $S_{init}$ using the `sync` pool, targeting the `Init` context ibgib.
-   * [ ] Wraps the saga in a context:
-     * `context.rel8ns.sessionIdentity = [S_genesis_addr]`
-     * `context.signedSessionIdentity = S_init`
-   * [ ] Transmits the context to the peer. Note: We only transmit the single evolved `S_init` frame inside `signedSessionIdentity`.
-2. **Receiver (Bob)**:
-   * [ ] Receives the context.
-   * [ ] **Authentication**: Run `authenticateContext`.
-     * [ ] Retrieve the previous keystone frame ($S_{genesis}$) independently from Bob's own local registry (using the session identity address obtained via $I_1$'s claim), rather than trusting any path/history Alice sends.
-     * [ ] Validate the cryptographic evolution from $S_{genesis}$ to the incoming $S_{init}$ (sequential counters, signature verification).
-     * [ ] Verify the signature in $S_{init}$ targets the exact context address.
-   * [ ] **Persistence**: Ensure $S_{init}$ is saved to the durable space alongside the context/saga control ibgibs (already handled by the coordinator's sync state saving mechanism, but needs to include the new session identity frame).
-
-### Leg 2: Ack (Receiver $\to$ Sender)
-1. **Receiver (Bob)**:
-   * [ ] Creates the `Ack` message frame.
-   * [ ] Wraps it in an `Ack` context:
-     * `context.rel8ns.sessionIdentity = [S_init_addr]`
-     * `context.signedSessionIdentity = undefined` (Bob does *not* sign or evolve $S$).
-   * [ ] Transmits the `Ack` context to Alice.
-2. **Sender (Alice)**:
-   * [ ] Receives the `Ack` context.
-   * [ ] Processes the gap requests and prepares domain payloads.
-
-### Leg 3: Delta (Sender $\to$ Receiver)
-1. **Sender (Alice)**:
-   * [ ] Creates the `Delta` message frame.
-   * [ ] Signs and evolves the session identity from $S_{init}$ to $S_{delta}$, targeting the `Delta` context ibgib.
-   * [ ] Wraps it in a `Delta` context:
-     * `context.rel8ns.sessionIdentity = [S_init_addr]`
-     * `context.signedSessionIdentity = S_delta`
-   * [ ] Transmits the `Delta` context and the domain payloads.
-2. **Receiver (Bob)**:
-   * [ ] Receives the context and domain payloads.
-   * [ ] **Authentication**: Run `authenticateContext`.
-     * [ ] Retrieve $S_{init}$ independently from Bob's own local registry.
-     * [ ] Validate transition from $S_{init}$ to $S_{delta}$.
-     * [ ] Verify signature targets the `Delta` context address.
-   * [ ] **Persistence**:
-     * [ ] Ensure $S_{delta}$ is saved to the durable space alongside the control ibgibs.
-     * [ ] Save incoming domain payloads to **Temporary Space** (`tempSpace`).
-
-### Leg 4: Commit (Receiver $\to$ Sender)
-1. **Receiver (Bob)**:
-   * [ ] Creates the `Commit` message frame and context.
-   * [ ] Returns the `Commit` context to Alice.
-   * [ ] Commits the sync session: transfers all domain payloads from `tempSpace` to `localSpace` (Durable).
-2. **Sender (Alice)**:
-   * [ ] Receives the `Commit` context.
-   * [ ] Commits the sync session: transfers accumulated domain payloads from `tempSpace` to `localSpace` (Durable).
-
----
-
-## Phase 3A: Step-by-Step Testing Plan
-
-To prevent complexity explosion, we will implement this incrementally using a new test file: `libs/core-gib/src/sync/sync-withid.pingpong.respec.mts`.
-
-### Step 1: Scaffold & Establish
-* [ ] Initialize a basic sync saga setup (two spaces, two coordinators, custom in-memory peer).
-* [ ] Perform Phase 1 establish to load the sender identity $I$ and session identity $S_{genesis}$ into the spaces.
-* [ ] Trigger `sync(...)`. Assert that the saga fails on Leg 1 due to unimplemented identity checks on the receiver.
-
-### Step 2: Implement Leg 1 Validation
-* [ ] Implement `authenticateContext` on the sync peer receiver (or as a helper).
-* [ ] Wire `authenticateContext` into the coordinator/peer incoming frame handler.
-* [ ] Verify that Leg 1 completes without error and that the receiver successfully writes the saga/session frames to durable space.
-
-### Step 3: Implement Leg 2 & Leg 3 Validation
-* [ ] Verify Alice processes the Ack and produces a Delta.
-* [ ] Implement Alice's second evolution to $S_{delta}$ and verification of it by Bob.
-* [ ] Verify domain payloads are successfully written to `tempSpace` during the Delta stage.
-
-### Step 4: Transactional Commit
-* [ ] Implement the commit phase logic that transfers domain payloads from `tempSpace` to `localSpace` upon receipt/emission of the `Commit` frame.
-* [ ] Assert that the final domain graphs on both sides are completely equivalent.