@ibgib/core-gib 0.1.19 → 0.1.20

package/src/common/other/ibgib-helper.mts

@@ -14,9 +14,61 @@ import { GLOBAL_LOG_A_LOT, IB_REGEXP_DEFAULT } from '../../core-constants.mjs';
 import { SpecialIbGibType } from './other-types.mjs';
 import { INVALID_DATE_STRING, SPECIAL_IBGIB_TYPE_REGEXP } from './other-constants.mjs';
 import { CONFIG_KEY_ATOM } from './ibgib-constants.mjs';
+import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
+import { getFromSpace } from '../../witness/space/space-helper.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT || false;
 
+/**
+ * Gets ibgibs that are directly related to the given `ibGib` via `rel8nNames`.
+ *
+ * @returns map of rel8nName -> ibgibs that are related.
+ */
+export async function getRel8dIbGibs({
+    ibGib,
+    rel8nNames,
+    space,
+}: {
+    ibGib: IbGib_V1,
+    rel8nNames?: string[],
+    space: IbGibSpaceAny,
+}): Promise<{ [rel8nName: string]: IbGib_V1[] }> {
+    const lc = `[${getRel8dIbGibs.name}]`;
+    try {
+        if (!ibGib) { throw new Error(`ibGib required (E: a3c1b2d4e5f6a7b8c9d0e1f2a3b4c5d6)`); }
+        if (!space) { throw new Error(`space required (E: b4d2c3e4f5a6b7c8d9e0f1a2b3c4d5e6)`); }
+
+        // Default to all rel8n names if none provided
+        if (!rel8nNames) {
+            rel8nNames = Object.keys(ibGib.rel8ns || {});
+        }
+
+        const rel8dIbGibs: { [rel8nName: string]: IbGib_V1[] } = {};
+
+        for (const rel8nName of rel8nNames) {
+            const rel8dAddrs = ibGib.rel8ns?.[rel8nName] || [];
+
+            if (rel8dAddrs.length > 0) {
+                const resGet = await getFromSpace({ addrs: rel8dAddrs, space });
+                if (resGet.success && resGet.ibGibs?.length === rel8dAddrs.length) {
+                    rel8dIbGibs[rel8nName] = resGet.ibGibs.concat();
+                } else {
+                    // Start logging warnings instead of throwing immediately?
+                    // For now, consistent with user request to adapt legacy code
+                    throw new Error(`Problem getting rel8d ibgibs for rel8nName: ${rel8nName}. ${resGet.errorMsg || 'Unknown error'} (E: c5e3d4f5a6b7c8d9e0f1a2b3c4d5e6)`);
+                }
+            } else {
+                rel8dIbGibs[rel8nName] = [];
+            }
+        }
+
+        return rel8dIbGibs;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
 /**
  * Utility function to generate hard-coded ibgibs to use at runtime "on-chain" but
  * written at compile-time in (for now) "off-chain" source code.

package/src/keystone/README.md

@@ -1,162 +1,20 @@
 # keystone-gib
 
-"Keystones" are a new ibgib-specific identity mechanism that leverages ibgib's unique Merkle-based DLT structure. These combine the aspect of the general CS concept of a "key" with the ibgib concept of a "stone", i.e., a non-living entity without `dna`.
+"Keystones" are a new ibgib-specific identity mechanism that leverages ibgib's unique Merkle-based DLT structure.
 
-## ibgib and keystones - how identity propagates through spacetime
+## 📚 Documentation
+*   **[Architecture](./docs/architecture.md)**: Detailed design of the Policy Engine, Hash-Based Cryptography, and Lifecycle.
 
-To understand Keystones, you must understand the environment they live in. ibgib is a **Spacetime Distributed Ledger**. Data does not just "exist"; it propagates through **Spaces** (persistence layers like local storage, cloud nodes, or p2p relays).
+## Overview
+A **Keystone** is a "Stone" (ibgib without `dna`) used for Identity. It is a graph of ibgib frames that evolves over time but maintains a strict, verifiable lineage.
 
-In this universe, data falls into two categories based on how it handles time:
+Validation in this system is **Auditability**: to verify an identity (e.g., "Is this Alice?"), one "replays" the Keystone timeline from its Genesis to the current Frame, verifying the cryptographic proofs at every step.
 
-1.  **"Living" Data:** These ibgibs have `dna` relations pointing to the transforms (mutations) that created them. They behave like CRDTs (Conflict-free Replicated Data Types) and can be merged, forked, and reconciled across different timelines.
-2.  **"Stones":** These are ibgibs **without** `dna`. They are fixed points in the causal graph. They do not merge; they only accrete. They are effectively constants.
+## Principles
+1.  **DRY**: Leverages the ubiquity of ibgib's existing crypto hypergraph.
+2.  **Non-Evil Root**: Prioritizes security/correctness over pre-optimization (signing speed).
+3.  **Hash-based**: Uses hash pre-imaging for quantum resistance (`hash-reveal-v1`).
+4.  **Merkle Graphs**: Efficient communication by only transmitting missing graph nodes.
 
-A **Keystone** is a "Stone". It is an identity timeline (a graph of ibgib frames) that must remain historically intact to be valid. It does not support CRDT-style merging.
-
-*   **Validation is Replay:** In traditional PKI, a Certificate Authority (CA) acts as a centralized trust anchor to establish a secure channel. In ibgib, validation is **Auditability**. To verify an identity (e.g., "Is this Alice?"), one "replays" the Keystone timeline from its Genesis to the current Frame, verifying the cryptographic proofs at every step.
-*   **Propagation as Witnessing:** When a Keystone Frame is transmitted from Alice's Space to Bob's Space, Bob "witnesses" it. By accepting it into his Space, he effectively votes on its validity. If it is invalid, it is rejected and does not propagate.
-
-## principles
-
-### DRY - leverage the ubiquity of ibgib's already-existing crypto hypergraph
-
-Ibgib already provides the foundations of hypergraph generation dynamics. This is core to the very being of all data within ibgib. Therefore, we do not need a separate library/algorithm that only works with specialized Merkle-based technologies like many NIST-approved technologies. We leverage the existing ibgib mechanism without having to maintain two codebases for things that do essentially the same thing.
-
-With ibgib, keystones are one reified use case of the more general ibgib timeline dynamics.
-
-### Non-Evil Root - ignore signing pre-optimization
-
-Similar to the slowness of some blockchains, like Bitcoin, we prioritize security first over other optimization dimensions like signing speed or size of keys.
-
-The "speed" of the security can occur in what I call "scoping", but this assumes a relatively small number of connections. This is not designed for general-purpose internet traffic, where signing size/rates are paramount.
-
-### Hash-based - pre-imaging is hard
-
-If this is not true, then the security of keystones fails. This does not mean that all hashes are equal of course, but the general principle exists.
-
-Note that, similar to PoW, hash-based challenges must be hard only for the time of the keystone's proximal use case. The keystones themselves must be spread with witnessing protocols to make them durable beyond that proximal window.
-
-### The need for `ib` - collisions in our future
-
-We are nearing a future where hash-spaces may seem large to us now, much like our previous beliefs that 1 MB of RAM was a lot. But this is misleading of course. With the amount of hashes that will be used (not only in ibgib, but other technologies as well as this will be the primary addressing mechanism across all software) these hash spaces will shrink precipitously. It's a small world after all.
-
-This is why ibgib's addressing mechanism has a per-use-case `ib` component, to reduce accidental collisions in a world of ubiquitous hashing.
-
-### Merkle graphs - inherently optimal communication
-
-A keystone is an entire dependency graph, not a single ibgib frame. This is like thinking, in today's understanding, of a keystone as an entire repo and not a single commit. Though, due to the coolness of Merkle graphs, we do not always need to transmit the entire dependency graph, just as we do not need to push/pull an entire repo every time. This is an inherent quality of Merkle graph transmission and is heavily relied upon.
-
-## current implementation
-
-The v1 implementation creates a pure TypeScript, isomorphic, hash-based identity system. It is designed to be "Non-Evil" (prioritizing security/correctness over bandwidth) and "Graph-Native" (the signature is part of the DAG).
-
-### jargon - the language of the stone
-
-*   **Stone:** Any ibgib without `dna`. A constant or fixed point in the graph.
-*   **Keystone:** A specific type of Stone used for Identity. It is a graph of ibgib frames that evolves over time but maintains a strict, verifiable lineage.
-*   **Challenge Pool:** A collection of puzzles stored in a Keystone Frame.
-*   **Challenge/Solution:** An abstract pair where the `Challenge` is public and the `Solution` is private. Revealing the Solution proves authorization.
-*   **Claim:** The semantic intent of a signature. Composed of a `target` (ibgib addr), `verb` (e.g., "post"), and optional `scope`.
-*   **Proof:** The structure linking a `Claim` to a set of revealed `Solutions`.
-*   **Policy:** The strict rules determining *which* challenges must be solved to authorize a specific Claim.
-
-### policy engine - selection and mitigation
-
-Why do we need complex selection logic?
-
-In a Keystone system, authorizing a frame involves **publicly revealing** solutions to challenges. Once revealed, a solution is known to the network. If a Man-In-The-Middle (MITM) isolates a victim, they might attempt to **replay** these known solutions to forge new frames.
-
-Our policy engine enforces a multi-layered challenge selection pipeline to mitigate this. To sign a claim, the challenges consumed must satisfy **ALL** of the following layers (without double-dipping):
-
-1.  **Mandatory Demands (The "Alice" Layer):**
-    *   *Mechanism:* The verifier (or context) explicitly demands specific `challengeIds`.
-    *   *Why:* Enables parties to proactively include challenges if they think the existing layers are insufficient, e.g., Alice can demand Bob select certain challenges that Alice thinks may be stronger/more secure (for whatever reason).
-2.  **Target Binding (The "Content" Layer):**
-    *   *Mechanism:* Challenges are explicitly mapped to buckets (e.g., Hex Characters), and the first N number of characters in the target `ibgib.gib` (frame's hash) are required to be solved.
-    *   *Why:* **Content-Dependent Binding.** A revealed solution for "Target A" with first 5 characters of "a1c04" cannot be used to sign "a40d9", because they only overlap with "a" and "0". The attacker has to forge an ibgib frame whose hash matches the target binded characters in the target addr, which is hard, similar to existing PoW leading-zero hashing. This becomes harder with more binding characters required.
-3.  **FIFO (The "Order" Layer):**
-    *   *Mechanism:* Must consume $N$ challenges from the "front" of the pool.
-    *   *Why:* Enables lower security but faster keystones.
-4.  **Stochastic (The "Chaos" Layer):**
-    *   *Mechanism:* Randomly select $N$ additional challenges from the remainder.
-    *   *Why:* Mitigates pre-computation attacks and grinding.
-
-#### replenishment - sustaining the timeline
-
-Once challenges are consumed to sign a frame, the pool must react. This dictates the longevity and bandwidth profile of the identity.
-
-*   **Top-Up (Standard):**
-    *   *Mechanism:* Generate $N$ new challenges to replace the $N$ consumed ones.
-    *   *Use Case:* Long-lived identities (e.g., User Profiles). Maintains a constant pool size and consistent entropy.
-*   **Replace-All (Paranoid):**
-    *   *Mechanism:* Discard *all* remaining challenges in the pool and generate a completely fresh set.
-    *   *Use Case:* High-security contexts where one desires total forward secrecy for the entire pool after any usage. High bandwidth cost.
-*   **Consume (Burn):**
-    *   *Mechanism:* Remove consumed challenges. Do *not* add new ones.
-    *   *Use Case:* Revocation (Scorched Earth) or One-Time-Use ephemeral identities. When the pool is empty, the capability associated with that pool is permanently disabled.
-
-### cryptographic engine - `strategy` is a concrete challenge/solution discriminator
-
-While the Policy Engine handles *selection*, the Cryptographic Engine handles the concrete specifics.
-
-We currently implement the `hash-reveal-v1` strategy, with other possibilities on the horizon:
-
-* simpler math challenges
-  * for testing
-  * for low/no-security
-  * for other non-security-based requirements (captcha)
-* encryption-based solutions
-  * must decrypt with known qualities
-  * can be much more novel, such as decrypt challenge text to a sonnet verified by an agent
-* PoW-style solutions
-  * config qualities like leading/trailing 0s
-  * not necessarily known ahead of time/at time of challenge-generation
-
-#### `strategy: 'hash-reveal-v1'`
-
-In the `hash-reveal-v1` strategy, we do not use RSA or Elliptic Curves. We use
-**Hash-Based Cryptography** preimages for quantum resistance and simplicity.
-These are configurable in algorithm and number of recursive rounds.
-
-*   **The Mechanism:** A variation of a Sigma protocol.
-    *   Alice commits to a value $H$ (The Challenge) in Frame $N$.
-    *   To authorize Frame $N+1$, Alice reveals the pre-image $S$ (The Challenge's Solution) such that $Hash(S) = H$ (with `$Hash` being parameterizable in algo/rounds).
-*   **Key Derivation (The Salted Wrap):**
-    *   To prevent exposure of the Master Secret, we use a derivation chain:
-    *   `MasterSecret` + `PoolSalt` $\to$ `PoolSecret`
-    *   `PoolSecret` + `ChallengeID` $\to$ `Solution`
-    *   `Solution` $\to$ `Challenge`
-    *   *Note:* We use a "Salted Wrap" technique (hashing `salt + secret + salt`) to act as a rudimentary Key Derivation Function without external dependencies that mitigates against length extension attacks.
-
-### spacetime integration - the service facade
-
-The `KeystoneService_V1` acts as a consumer's API for keystone manipulations. These include both the cryptographic requirements, as well as persistence in ibgib spaces via the metaspace. It ensures that every cryptographic action is executed and atomically persisted to the local Space.
-
-#### 1. genesis (creation)
-*   **Input:** A Master Secret and Pool Configs.
-*   **Process:** Generates the initial challenges and the Genesis Frame.
-*   **Persistence:** The new Identity is immediately `put` into the local `Space`.
-
-#### 2. sign (evolution)
-*   **Input:** The Latest Keystone, Master Secret, Claim, and optional Demands.
-*   **Process:**
-    1.  **Auto-Routing:** Locates the correct Pool based on the Claim's Verb (e.g., routing "revoke" to the revocation pool).
-    2.  **Selection:** Runs the Policy Engine (Binding -> FIFO -> Stochastic) to select challenges.
-    3.  **Solving:** Generates solutions using the Master Secret.
-    4.  **Replenishment:** Tops up the pool with fresh challenges (or burns them, depending on strategy).
-*   **Persistence:** The new Frame (containing the Proof) is persisted to the local `Space`. The `target` address is now cryptographically linked to this new frame.
-
-#### 3. validate (audit)
-*   **Input:** The Previous Frame and the Current Frame.
-*   **Process:**
-    1.  **Policy Check:** Reconstructs the deterministic requirements (Demands, Binding, FIFO) and ensures the Proof satisfies them.
-    2.  **Crypto Check:** Verifies the revealed Solutions match the Challenges in the Previous Frame.
-*   **Result:** If valid, the Current Frame is accepted as the legitimate successor.
-
-#### 4. revoke (kill switch)
-*   **Input:** The Latest Keystone and Master Secret.
-*   **Process:**
-    1.  Locates the specialized **Revocation Pool**.
-    2.  Consumes **ALL** challenges in that pool ("Scorched Earth").
-    3.  Sets the `revocationInfo` on the new frame.
-*   **Result:** The Identity is permanently marked as dead. No further valid frames can be generated because the revocation pool (required for the 'revoke' verb) is empty.
+## Implementation
+The v1 implementation creates a pure TypeScript, isomorphic, hash-based identity system. It is designed to be "Non-Evil" and "Graph-Native".

package/src/keystone/docs/architecture.md

@@ -0,0 +1,55 @@
+# Keystone Identity Architecture
+
+"Keystones" combine the concept of a cryptographic key with the ibgib concept of a "stone" (immutable data) to create an audit-trail-based identity system.
+
+## 1. Principles
+
+*   **Auditability as Validation**: Validation is not checking a certificate authority; it is replaying the history of the Keystone timeline to verify the cryptographic proofs from Genesis to present.
+*   **Propagation as Witnessing**: When a Space accepts a Keystone frame, it "witnesses" it, effectively voting on its validity.
+*   **Hash-Based (Post-Quantum)**: Security relies on hash pre-imaging difficulty (`hash-reveal-v1`) rather than RSA/ECC, leveraging the intrinsic properties of the ibgib DAG.
+
+## 2. Core Concepts
+
+*   **Keystone**: An identity timeline. A graph of ibgib frames evolving over time.
+*   **Challenge Pool**: A collection of puzzles stored in each Keystone Frame.
+*   **Constraint/Policy Engine**: Logic that determines *which* challenges must be solved to authorize a specific action (Binding, FIFO, Stochastic).
+
+## 3. Policy Engine (Selection & Mitigation)
+
+To prevent replay attacks by Man-in-the-Middle (MITM) actors, the challenges required to sign a frame are selected via a multi-layered pipeline:
+
+1.  **Mandatory Demands**: The verifier explicitly requests specific challenge IDs.
+2.  **Target Binding**: Challenges are mapped to buckets (e.g., hex characters). Signing a target `a1c04...` requires solving challenges in the `a`, `1`, `c` buckets. This creates **Content-Dependent Binding**.
+3.  **FIFO**: Consumes $N$ challenges from the "front" of the pool (Performance).
+4.  **Stochastic**: Randomly selects $N$ additional challenges (Anti-Grinding).
+
+## 4. Cryptographic Strategy (`hash-reveal-v1`)
+
+A variation of a Sigma protocol using Hash-Based Cryptography.
+
+*   **Commit**: Alice publishes $H = Hash(S)$ in Frame $N$.
+*   **Reveal**: To authorize Frame $N+1$, Alice reveals $S$.
+*   **Derived Secrets**:
+    *   `MasterSecret` + `PoolSalt` -> `PoolSecret`
+    *   `PoolSecret` + `ChallengeID` -> `Solution`
+    *   `Solution` -> `Challenge`
+
+## 5. Lifecycle
+
+### 5.1 Genesis
+Inputs: `MasterSecret`, `PoolConfig`.
+Generates initial challenges and the Genesis Frame. Persists to local Space.
+
+### 5.2 Sign (Evolution)
+Inputs: `LatestKeystone`, `Claim`, `MasterSecret`.
+1.  **Auto-Routing**: Selects pool based on Verb (e.g., 'revoke').
+2.  **Selection**: Runs Policy Engine.
+3.  **Solving**: Generates solutions.
+4.  **Replenishment**: Adds new challenges (Top-Up) or burns them.
+
+### 5.3 Validate
+Inputs: `PreviousFrame`, `CurrentFrame`.
+Re-runs the Policy Engine to ensure the correct challenges were solved and verifies the hash pre-images.
+
+### 5.4 Revoke
+Consumes **ALL** challenges in the revocation pool ("Scorched Earth"). The identity can no longer evolve.

package/src/sync/README.md

@@ -11,45 +11,40 @@ The synchronization process is modeled as a "Saga" — a linear but distributed
 *   **[SyncPeerWitness](file:./sync-peer/sync-peer-types.mts)**: The interface for the "Transport Layer". It abstracts the communication channel (Method Call, HTTP, WebSocket) into a standard Witness pattern.
     *   **[SyncPeer_V1](file:./sync-peer/sync-peer-v1.mts)** provides the base plumbing.
     *   Concrete implementations (e.g., in-memory) handle the actual byte transfer.
-*   **[SyncSagaContextIbGib_V1](file:./sync-saga-context/sync-saga-context-types.mts)**: The "Transport Envelope". This is the payload passed to the Witness. It contains the current Saga Frame, the Message Stones (Data), and any cryptographic proofs required for the step.
-
-> **Note**: Ephemeral Identity/Keystone implementation for session signing is currently pending. The architecture supports it (via `claims` and `sessionKeystone` fields), but it is not yet enforced.
-
-## Architecture
-
-The protocol is designed as a **Ping-Pong** exchange of immutable frames.
-
-1.  **Init**: Initiator creates an `Init` frame/stone proposing a sync (with their Knowledge Vector).
-2.  **Ack**: Receiver calculates a Diff and responds with an `Ack` frame/stone containing specific requests (`deltaReqAddrs`).
-3.  **Process/Delta**: Initiator fulfills the request by bundling the data into a `Delta` frame (or just payloads) and sending it.
-4.  **Commit**: Receiver verifies data integrity and finalizes the saga with a `Commit` frame.
-
-Usage of the [SyncSagaCoordinator](file:./sync-saga-coordinator.mts) drives this entire flow, transparently handling the persistence of the audit trail in both the `tempSpace` (Transactional) and `localSpace` (Persistent).
-
-## Test Matrix & Verification Plan
-
-We are rigorously testing the Sync Protocol using `InnerSpace` (In-Memory) simulation to verify all permutations of logic before deploying to network transports.
-
-### 1. Basic Scenarios (Happy Paths)
-*   [x] **Push (Source -> Dest)**: Single timeline (Root + Child) synced from Source to empty Dest.
-*   [ ] **Pull (Dest -> Source)**: Dest requests data from Source (Reverse Sync).
-*   [ ] **Fast-Forward (Remote Newer)**:
-    *   Remote has `n=5`. Local has `n=3`.
-    *   Local initiates Sync.
-    *   Receiver (Remote) sees outdated Local KV.
-    *   Receiver "Pushes" update via `Ack` (Offer) or forces Local to Pull.
-
-### 2. Complex Graph Scenarios
-*   [ ] **Multiple Timelines**: Syncing a graph with multiple unrelated timelines.
-*   [ ] **Deep Updates**: Syncing a Timeline with history (Branch -> Edit -> Merge).
-*   [ ] **Graph Referencing**: Syncing a Timeline that links to other Timelines (ensuring deep dependency resolution).
-
-### 3. Failure & Abort Scenarios
-*   [ ] **Invalid Identity**: Man-in-the-Middle check (Signature Fail).
-*   [ ] **Integrity Check Fail**: Data corruption detection (`ib != gib`).
-*   [ ] **Timeout/TTL**: Handling dropped connections (Saga Expiry).
-
-### 4. Conflict Resolution (Optimistic)
-*   [ ] **Simple Branch (Divergent)**: Handling trivial forks.
-*   [ ] **Mixed Edits**: Concurrent modifications to the same timeline.
-*   [ ] **Optimistic Merge**: Automatic reconciliation of non-conflicting branches.
+*   **[SyncSagaContextIbGib_V1](file:./sync-saga-context/sync-saga-context-types.mts)**: The "Transport Envelope". This is the payload passed to the Witness. It contains the current Saga Frame, the Message Stones (Data), and any cryptographic proofs required for the step.## Conflict Resolution & Protocol Refinements
+
+### Unified Ack Protocol
+To optimize the handshake, the `Ack` frame now carries both synchronization data (requests/offers) AND conflict information.
+*   **Conflicts**: If the Receiver detects divergence (multiple timeline tips), it includes a `conflicts` array in the `Ack`.
+*   **Structure**: Each conflict includes the `tjpAddr`, `localAddr` (Receiver's Tip), `remoteAddr` (Sender's Tip), and crucially `timelineAddrs` (History).
+
+### Iterative Delta Protocol (Ping-Pong)
+The `Delta` phase is no longer a single push. It is an iterative negotiation:
+1.  **Symmetrical**: Both Sender and Receiver can send `Delta` frames.
+2.  **Payloads**: Frames carry `payloadAddrs` (manifest) and the actual data is persisted to the peer's space.
+3.  **Requests**: A Delta can include `requests` (e.g., asking for missing conflict history).
+4.  **Merge**: If a peer resolves a conflict locally (using `optimistic` strategies), the resulting **Merge Frame** is added to the outgoing payload.
+5.  **Completion**: A `Delta` frame includes a `proposeCommit` flag. If one peer sets this and the other has nothing to add, the session transitions to `Commit`.
+
+### Commit Phase
+*   **Persistence**: The `Commit` frame signals success.
+*   **Cleanup**: The `SyncPeer` is responsible for moving verified `ibGibs` from the temporary saga space to the persistent domain space.
+
+### Ephemeral Identity (`useSessionIdentity`)
+The sync protocol can optionally generate an ephemeral Keystone Identity for the duration of the saga.
+*   **Purpose**: Allows secure, signed exchanges even if the Node doesn't have a long-lived identity, or wishes to isolate the sync session.
+*   **Mechanism**: If `useSessionIdentity: true` (default) is passed to `sync()`, a new Keystone frame is generated and linked to the Saga.
+*   **Pending Work**: Full verification of these ephemeral signatures is currently pending implementation.
+
+## 📚 Documentation
+*   **[Architecture](./docs/architecture.md)**: Detailed design of the Saga Protocol, State Machine, and Smart Diff logic.
+*   **[Verification](./docs/verification.md)**: Test matrix, scenarios, and verification results.
+
+## Features
+*   **Symmetric Design**: No distinct "Client" or "Server" logic.
+*   **Smart Diff**: Efficient "Knowledge Vector" exchange to transfer only missing deltas.
+*   **Constants & Timelines**: Support for syncing both mutable histories and immutable stones.
+*   **Optimistic Concurrency**: (In Progress) Branch detection and merge strategies.
+
+## Verification
+We rely on rigorous In-Memory Simulation (`InnerSpace`) to verify complex graph scenarios. See **[Verification](./docs/verification.md)** for the full status.

package/src/sync/docs/architecture.md

@@ -0,0 +1,69 @@
+# 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 Vectors" to calculate the precise difference between peers.
+*   **Knowledge Vector**: 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 `KnowledgeVector` and `Mode` (Push/Pull/Sync).
+    *   Sends `Init` to Bob.
+
+2.  **Gap Analysis (`handleInitFrame`)**:
+    *   Reactor (Bob) receives `Init`.
+    *   Bob compares Alice's `KnowledgeVector` 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 `KnowledgeVector` (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`.
+*   `knowledgeVector`: `{ [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.

package/src/sync/docs/verification.md

@@ -0,0 +1,43 @@
+# Sync Protocol Verification
+
+This document outlines the testing strategy and verification results for the Symmetric Sync Protocol.
+
+## Testing Strategy
+We use `respec-gib` (a BDD-style framework) with **In-Memory Simulation (`InnerSpace`)** to verify logic. This allows us to test complex graph scenarios without network or disk I/O overhead.
+
+### Key Test Files
+*   `sync-innerspace.respec.mts`: Basic Push/Pull scenarios.
+*   `sync-innerspace-multiple-timelines.respec.mts`: Handling multiple independent timelines in one Saga.
+*   `sync-innerspace-deep-updates.respec.mts`: Syncing timelines with extensive history (ensuring `past` links are traversed).
+*   `sync-innerspace-partial-update.respec.mts`: **Smart Diff** verification (Sender uses Receiver's context to send only deltas).
+*   `sync-innerspace-dest-ahead.respec.mts`: Verifying "Fast-Backward" or "Push Offer" logic (Sender offers update, Receiver accepts).
+*   `sync-innerspace-constants.respec.mts`: Verifying synchronization of **Stones** (Constants/Non-TJPs).
+
+## Verification Matrix
+
+### 1. Basic Scenarios
+| Feature | Description | Status | Test File |
+| :--- | :--- | :--- | :--- |
+| **Push** | Source syncs a new timeline to an empty Dest. | ✅ Verified | `sync-innerspace.respec.mts` |
+| **Pull** | Dest requests data from Source (Reverse Sync). | ⏳ Pending | `sync-innerspace.respec.mts` |
+| **Dest Ahead** | Dest has newer data; Source offers Push. | ✅ Verified | `sync-innerspace-dest-ahead.respec.mts` |
+
+### 2. Complex Graph Scenarios
+| Feature | Description | Status | Test File |
+| :--- | :--- | :--- | :--- |
+| **Multi-Timeline** | Syncing multiple separate timelines. | ✅ Verified | `sync-innerspace-multiple-timelines.respec.mts` |
+| **Deep Updates** | Syncing deep dependency chains (Ancestors). | ✅ Verified | `sync-innerspace-deep-updates.respec.mts` |
+| **Smart Diff** | Sender skips data Receiver already has. | ✅ Verified | `sync-innerspace-partial-update.respec.mts` |
+| **Constants** | Syncing immutable stones (no TJP). | ✅ Verified | `sync-innerspace-constants.respec.mts` |
+
+### 3. Failure & Edge Cases
+| Feature | Description | Status | Test File |
+| :--- | :--- | :--- | :--- |
+| **Validation** | Verifying Integrity Checks (ib/gib). | ⏳ Pending | - |
+| **Conflicts** | Divergent branches (Merge Strategy). | ⏳ Pending | - |
+
+## Recent Verifications
+### Sync Constants (2026-01-08)
+*   **Goal**: Ensure constants (ibGibs without `tjp` or `past`) are synced.
+*   **Result**: Passed.
+*   **Fixes**: Updated `handleInitFrame` to request missing stones; updated `handleAckFrame` to include "tip" stones in payload even without dependencies.

package/src/sync/merge-info/merge-info-constants.mts

@@ -0,0 +1 @@
+export const MERGE_INFO_ATOM = 'merge_info';

package/src/sync/merge-info/merge-info-helpers.mts

@@ -0,0 +1,134 @@
+import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+
+import { MetaspaceService } from "../../witness/space/metaspace/metaspace-types.mjs";
+import { MERGE_INFO_ATOM } from "./merge-info-constants.mjs";
+import { MergeInfoData_V1, MergeInfoIbGib_V1, MergeInfoIb_V1 } from "./merge-info-types.mjs";
+import { IbGibSpaceAny } from "../../witness/space/space-base-v1.mjs";
+
+const lc = `[merge-info-helpers]`;
+
+/**
+ * Validates and constructs the `ib` object for a Merge Info ibGib.
+ */
+export async function getMergeInfoIb({
+    data
+}: {
+    data: MergeInfoData_V1
+}): Promise<string> {
+    if (!data.algo) { throw new Error(`(UNEXPECTED) data.algo required for MergeInfoIb (E: 8a9b0c1d2e3f4g5h)`); }
+
+    // merge_info algo
+    return [MERGE_INFO_ATOM, data.algo].join(' ');
+}
+
+/**
+ * Parses a standard Merge Info 'ib' string.
+ */
+export async function parseMergeInfoIb({
+    ib
+}: {
+    ib: string
+}): Promise<MergeInfoIb_V1> {
+    try {
+        const parts = ib.split(' ');
+        if (parts[0] !== MERGE_INFO_ATOM) { throw new Error(`Atom mismatch. Expected ${MERGE_INFO_ATOM} (E: 8f03c92a95144b618821915632599266)`); }
+        if (parts.length < 2) { throw new Error(`Invalid merge info ib. Expected at least 2 parts. (E: 9c2b4c8a6d34469f8263544710183355)`); }
+
+        const algo = parts.slice(1).join(' '); // allow spaces in algo? usually single word but safe to join.
+
+        return {
+            atom: MERGE_INFO_ATOM,
+            algo,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
+/**
+ * Creates a new MergeInfo ibGib.
+ */
+export async function createMergeInfo({
+    algo,
+    ancestors,
+    details,
+}: {
+    algo: string,
+    ancestors: IbGib_V1[],
+    details?: string,
+}): Promise<MergeInfoIbGib_V1> {
+    const data: MergeInfoData_V1 = {
+        algo,
+        details,
+    };
+
+    const ib = await getMergeInfoIb({ data });
+
+    const rel8ns: any = {};
+    if (ancestors && ancestors.length > 0) {
+        rel8ns.ancestors = ancestors.map(a => getIbGibAddr({ ibGib: a }));
+    }
+
+    const res = await Factory_V1.stone({
+        ib,
+        data,
+        rel8ns,
+        parentPrimitiveIb: MERGE_INFO_ATOM,
+        uuid: true, // Should be unique per merge event? Yes.
+    });
+
+    // Unwrapping if necessary, though recent checking suggests Factory returns ibGib directly.
+    // Wait, recent check in SyncSagaCoordinator showed Factory_V1.stone returns the ibGib directly.
+    // But check the implementation plan/previous learnings.
+    // Confirmed: Factory_V1.stone returns the ibGib directly.
+    return res as MergeInfoIbGib_V1;
+}
+
+/**
+ * Naive text merge. 
+ * Strategies:
+ * 1. Concat (A + B)
+ * 2. structured diff (not impl)
+ */
+export async function mergeText({
+    textA,
+    textB,
+}: {
+    textA: string,
+    textB: string,
+}): Promise<string> {
+    // Very naive: Just concat with a marker for now.
+    // User wants "best effort at being non-destructive".
+    if (textA === textB) { return textA; }
+    return `${textA}\n\n>>> MERGE SEPARATOR <<<\n\n${textB}`;
+}
+
+/**
+ * Combines two divergent timelines by applying missing DNA from one branch to another.
+ * 
+ * Logic:
+ * 1. Identify missing DNA (transforms) in `targetTip` that exist in `sourceTip` (relative to LCA).
+ * 2. Replay those transforms onto `targetTip`.
+ * 3. Create a MergeInfo stone describing this operation.
+ * 4. Relate the new tip to the MergeInfo.
+ */
+export async function combineDivergentTimelines({
+    targetTip,
+    sourceTip,
+    lca,
+    space,
+    metaspace,
+}: {
+    targetTip: IbGib_V1,
+    sourceTip: IbGib_V1,
+    lca: IbGib_V1,
+    space: IbGibSpaceAny,
+    metaspace: MetaspaceService,
+}): Promise<IbGib_V1> {
+    // stub implementation
+    return targetTip;
+}