@ibgib/core-gib 0.1.13 → 0.1.14

package/dist/sync/sync-saga-coordinator.mjs

@@ -1,72 +1,22 @@
-import { extractErrorMsg, getUUID, // so our timestamp in ticks as a string are uniform
-pretty, clone } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { extractErrorMsg, getUUID } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
 import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
 import { splitPerTjpAndOrDna, getTimelinesGroupedByTjp } from "../common/other/ibgib-helper.mjs";
 import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
-import { isPrimitive } from "@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs";
 import { GLOBAL_LOG_A_LOT } from "../core-constants.mjs";
-import { putInSpace, lockSpace, unlockSpace, getLatestAddrs, getFromSpace } from "../witness/space/space-helper.mjs";
-import { SyncStage, SYNC_ATOM } from "./sync-constants.mjs";
-import { getSyncIb } from "./sync-helpers.mjs";
+import { putInSpace, getFromSpace } from "../witness/space/space-helper.mjs";
+import { SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME } from "./sync-constants.mjs";
+import { appendToTimeline, createTimeline } from "../timeline/timeline-api.mjs";
+import { SyncMode, } from "./sync-types.mjs";
+import { getSyncIb, isPastFrame } from "./sync-helpers.mjs";
 import { getDependencyGraph } from "../common/other/graph-helper.mjs";
+import { getSyncSagaMessageIb } from "./sync-saga-message/sync-saga-message-helpers.mjs";
+import { SYNC_SAGA_MSG_ATOM } from "./sync-saga-message/sync-saga-message-constants.mjs";
+import { Subject_V1 } from "../common/pubsub/subject/subject-v1.mjs";
+import { SyncSagaContextCmd } from "./sync-saga-context/sync-saga-context-types.mjs";
+import { createSyncSagaContext } from "./sync-saga-context/sync-saga-context-helpers.mjs";
 const logalot = GLOBAL_LOG_A_LOT || true;
 /**
  * Orchestrates the synchronization process between two spaces (Source and Destination).
- *
- * ## Architecture: Dependency Graph Synchronization
- *
- * Instead of a naive file-by-file sync or a holistic "Space" sync, this coordinator operates
- * on a **Dependency Graph** derived from specific "Domain Roots" (e.g., a specific tag,
- * folder, or application root).
- *
- * ### Workflow Pipeline
- *
- * 1.  **Graph Generation**:
- *     *   Generates a `FlatIbGibGraph` using `getDependencyGraph({ live: true })` starting
- *         from the provided `domainIbGibs`.
- *     *   This ensures we capture the *latest* reachable state of all relevant timelines.
- *
- * 2.  **Classification (`splitPerTjpAndOrDna`)**:
- *     *   **Stones**: Immutable, non-living ibGibs (no TJP/DNA). Trivial to sync (copy if missing).
- *     *   **Living**: Evolving timelines (TJP + DNA). Complex to sync (require ordering & merging).
- *
- * 3.  **Timeline Ordering (`getTimelinesGroupedByTjp`)**:
- *     *   Living ibGibs are grouped into timelines.
- *     *   A "Timeline Dependency Graph" is built. Use Case: If a Comment Timeline refers to a
- *         Post Timeline, the Post Timeline must be synced *before* the Comment Timeline to
- *         ensure referential integrity at the destination.
- *     *   **Topological Sort** determines the execution order. Circular dependencies are
- *         treated as siblings.
- *
- * 4.  **Saga Execution ("Smart Coordinator, Dumb Space")**:
- *     *   The Coordinator (running on the Client/Source) drives the entire process via a
- *         "Pull-Merge-Push" strategy to resolve conflicts.
- *
- *     *   **Phase 1: Knowledge Exchange (Init)**
- *         *   Generates a "Knowledge Vector" (Map<Tjp, LatestAddr>) of the Source's graph.
- *         *   Sends `SyncStage.Init` to Dest.
- *         *   Dest responds with its own Knowledge Vector for overlapping timelines.
- *
- *     *   **Phase 2: Gap Analysis & Conflict Resolution**
- *         *   Coordinator compares Source vs. Dest knowledge.
- *         *   **Fast-Forward**: Source is strictly ahead of Dest. Mark new frames for PUSH.
- *         *   **Fast-Backward**: Dest is strictly ahead of Source. Mark frames for PULL (to update Local).
- *         *   **Conflict/Divergence**: Both have new frames from a common ancestor.
- *             *   **LOCK**: `lockSpace({ scope: tjpGib })` on Dest to prevent race conditions.
- *             *   **PULL**: Download conflicting branch from Dest.
- *             *   **MERGE**: Execute merge logic locally (creating a new merge frame `A_merge`).
- *             *   **PUSH**: Mark `A_merge` (and dependencies) for PUSH.
- *             *   **UNLOCK**: Release Dest lock.
- *
- *     *   **Phase 3: Batch Streaming (Delta)**
- *         *   **Stones**: Batch `putInSpace` all missing "Stone" ibGibs first.
- *         *   **Timelines**: Batch `putInSpace` Living Timelines in topological order.
- *         *   *Note*: The `SyncFrame` (Init/Delta/Commit) tracks protocol state, but data transfer
- *             happens via standard `putInSpace`.
- *
- *     *   **Phase 4: Commit**
- *         *   Update Local Index (register new latests).
- *         *   Send `SyncStage.Commit` to Dest to finalize session.
  */
 export class SyncSagaCoordinator {
     keystone;
@@ -75,116 +25,156 @@ export class SyncSagaCoordinator {
         this.keystone = keystone;
     }
     /**
-     * Executes a synchronization saga.
-     *
-     * @param opts.source The local space (Client) driving the sync.
-     * @param opts.dest The remote space (Server/Other Peer) to sync with.
-     * @param opts.identity The Keystone Identity performing the sync.
-     * @param opts.domainIbGibs The root ibGibs that define the scope of the sync (the "Dependency Graph").
-     * @param opts.identitySecret Optional secret if needed (usually handled by `keystone` service).
+     * Executes a synchronization saga using the Symmetric Sync Protocol.
      */
-    async sync({ source, dest, identity, domainIbGibs, identitySecret, conflictStrategy }) {
+    async sync({ peer, localSpace, metaspace, primaryIdentity, primaryIdentitySecret, domainIbGibs, }) {
         const lc = `${this.lc}[${this.sync.name}]`;
-        try {
-            if (logalot) {
-                console.log(`${lc} starting...`);
-            }
-            // 1. Generate UUID for this saga
-            // const uuid = await Factory_V1.primitive({ ib: "genuuid" }); // Hacky usage of primitive helper if available, or just UUID lib
-            // if we don't have a uuid, we can generate one here.
-            // but usually this is passed in.
-            // atow we are just generating one.
-            const uuid = await getUUID();
-            // ---------------------------------------------------------
-            // 1. Graph Generation & Classification
-            // ---------------------------------------------------------
-            const { srcStones, srcTimelinesMap, srcSortedTjps, srcGraph } = await this.analyzeTimelines({
-                domainIbGibs,
-                space: source
-            });
-            // ---------------------------------------------------------
-            // 2. Knowledge Exchange (Init) & 3. Conflict Resolution
-            // ---------------------------------------------------------
-            // Phase 1: Init Data
-            const srcKnowledgeVector = {};
-            Object.keys(srcTimelinesMap).forEach(tjp => {
-                const timeline = srcTimelinesMap[tjp];
-                const tip = timeline.at(-1);
-                srcKnowledgeVector[tjp] = getIbGibAddr({ ibGib: tip });
-            });
-            // Need to determine mode correctly. Just defaulting to push for now
-            // as per original impl instructions (or TODO)
-            const initData = {
-                knowledgeVector: srcKnowledgeVector,
-                identity: identity,
-                mode: 'push'
-            };
-            const initFrame = await this.createSyncFrame({
-                uuid,
-                stage: SyncStage.init,
-                payload: initData,
-                identity
-            });
-            await putInSpace({ space: dest, ibGib: initFrame });
-            // Phase 2: Resolving Conflicts (Pull/Merge)
-            await this.resolveConflicts({
-                source,
-                dest,
-                srcTimelinesMap,
-                srcKnowledgeVector,
-                srcGraph,
-                uuid,
-                conflictStrategy: conflictStrategy || 'abort',
-            });
-            // ---------------------------------------------------------
-            // 4. Batch Stream (Delta)
-            // ---------------------------------------------------------
-            const payloadAddrs = [];
-            payloadAddrs.push(...srcStones.map(x => getIbGibAddr({ ibGib: x })));
-            srcSortedTjps.forEach(tjp => {
-                const timeline = srcTimelinesMap[tjp];
-                payloadAddrs.push(...timeline.map(x => getIbGibAddr({ ibGib: x })));
-            });
-            const deltaData = { payloadAddrs };
-            const deltaFrame = await this.createSyncFrame({
-                uuid,
-                stage: SyncStage.delta,
-                payload: deltaData,
-                identity
-            });
-            await putInSpace({ space: dest, ibGib: deltaFrame });
-            // Streaming Logic
-            await this.processBatchStream({
-                dest,
-                payloadAddrs,
-                srcGraph
-            });
-            // ---------------------------------------------------------
-            // 5. Commit
-            // ---------------------------------------------------------
-            const commitData = { success: true };
-            const commitFrame = await this.createSyncFrame({
-                uuid,
-                stage: SyncStage.commit,
-                payload: commitData,
-                identity
-            });
-            await putInSpace({ space: dest, ibGib: commitFrame });
-        }
-        catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
+        if (logalot) {
+            console.log(`${lc} starting...`);
         }
-        finally {
-            if (logalot) {
-                console.log(`${lc} complete.`);
+        // 1. SETUP SAGA METADATA
+        const sagaId = await getUUID();
+        // Setup Observable & Promise
+        const updates$ = new Subject_V1();
+        let resolveDone;
+        let rejectDone;
+        const done = new Promise((resolve, reject) => {
+            resolveDone = resolve;
+            rejectDone = reject;
+        });
+        // WORKING CONTEXT (Transactional)
+        const tempSpace = await metaspace.createNewLocalSpace({
+            opts: {
+                allowCancel: false,
+                spaceName: undefined,
+                getFnPrompt: metaspace.getFnPrompt,
+                logalot
             }
+        });
+        if (!tempSpace) {
+            throw new Error(`Failed to create temp space (E: 8f4e2f3d6c1b4b1a8f4e2f3d6c1b4b1a)`);
         }
+        const cleanup = async () => {
+            // In-memory temp space cleanup if needed (e.g. if we used a specialized disposable space)
+            // await tempSpace.destroy();
+        };
+        // Async execution wrapper
+        (async () => {
+            try {
+                // 2. BOOTSTRAP IDENTITY (Session Keystone)
+                const config = {
+                    id: 'default',
+                    type: 'hash-reveal-v1',
+                    salt: sagaId,
+                    behavior: { size: 10, replenish: 'top-up', selectSequentially: 1, selectRandomly: 1, targetBindingChars: 0 },
+                    algo: 'SHA-256', rounds: 1
+                };
+                const sessionIdentity = await this.keystone.genesis({
+                    masterSecret: sagaId,
+                    configs: [config],
+                    metaspace,
+                    space: tempSpace
+                });
+                // 3. CREATE INITIAL FRAME (Stage.init)
+                const { sagaFrame: initFrame, srcGraph } = await this.createInitFrame({
+                    sagaId,
+                    sessionIdentity,
+                    localSpace,
+                    domainIbGibs,
+                    tempSpace,
+                    metaspace,
+                });
+                // 4. EXECUTE SAGA LOOP (FSM)
+                const syncedIbGibs = await this.executeSagaLoop({
+                    initialFrame: initFrame,
+                    srcGraph,
+                    peer,
+                    sessionIdentity,
+                    updates$,
+                    tempSpace,
+                    metaspace
+                });
+                // 5. MERGE RESULT (Optimistic Commit)
+                if (syncedIbGibs && syncedIbGibs.length > 0) {
+                    if (logalot) {
+                        console.log(`${lc} Merging ${syncedIbGibs.length} synced ibGibs to localSpace...`);
+                    }
+                    await putInSpace({ space: localSpace, ibGibs: syncedIbGibs });
+                }
+                resolveDone();
+                updates$.complete();
+            }
+            catch (error) {
+                console.error(`${lc} ${extractErrorMsg(error)}`);
+                rejectDone(error);
+                updates$.error(error);
+            }
+            finally {
+                await cleanup();
+            }
+        })();
+        return {
+            sagaId,
+            updates$,
+            done
+        };
     }
     /**
-     * Analyses the timelines in the provided graph, classifying them into stones and living timelines,
-     * and performing topological sort on the timelines.
+     * Drives the FSM loop of the Saga.
+     * Use "Ping Pong" style: Send Request -> Wait Response -> React (Handle) -> Repeat.
      */
+    async executeSagaLoop({ initialFrame, srcGraph, peer, sessionIdentity, updates$, tempSpace, metaspace }) {
+        const lc = `${this.lc}[${this.executeSagaLoop.name}]`;
+        let currentFrame = initialFrame;
+        let nextPayload = [];
+        const allReceivedIbGibs = [];
+        while (currentFrame) {
+            // A. Create Context (Request)
+            const payloadAddrs = nextPayload.map(p => getIbGibAddr({ ibGib: p }));
+            const requestCtx = await createSyncSagaContext({
+                cmd: SyncSagaContextCmd.process,
+                sagaFrame: currentFrame,
+                msgs: [],
+                sessionKeystones: [sessionIdentity],
+                payload: payloadAddrs.length > 0 ? payloadAddrs : undefined,
+            });
+            // B. Transmit
+            updates$.next(requestCtx);
+            const responseCtx = await peer.witness(requestCtx);
+            // C. Handle Response
+            if (!responseCtx) {
+                console.warn(`${lc} Peer returned no response context. Ending loop.`);
+                currentFrame = null;
+                break;
+            }
+            updates$.next(responseCtx);
+            // D. Extract Remote Frame & React
+            const remoteFrameAddr = responseCtx.rel8ns?.sagaFrame?.[0];
+            if (!remoteFrameAddr) {
+                console.warn(`${lc} Peer response has no sagaFrame. Ending loop.`);
+                currentFrame = null;
+                break;
+            }
+            const remoteFrame = await getFromSpace({ addr: remoteFrameAddr, space: tempSpace });
+            if (!remoteFrame) {
+                throw new Error(`Could not resolve remote frame: ${remoteFrameAddr}`);
+            }
+            // React (Reducer)
+            const result = await this.handleSagaFrame({
+                sagaIbGib: remoteFrame,
+                srcGraph,
+                space: tempSpace,
+                identity: sessionIdentity,
+                metaspace
+            });
+            currentFrame = result?.frame || null;
+            nextPayload = result?.payload || [];
+            if (result?.receivedPayload) {
+                allReceivedIbGibs.push(...result.receivedPayload);
+            }
+        }
+        return allReceivedIbGibs;
+    }
     async analyzeTimelines({ domainIbGibs, space, }) {
         const lc = `${this.lc}[${this.analyzeTimelines.name}]`;
         const srcGraph = await getDependencyGraph({
@@ -200,302 +190,428 @@ export class SyncSagaCoordinator {
         const { mapWithTjp_YesDna: srcMapWithTjp_YesDna, mapWithTjp_NoDna: srcMapWithTjp_NoDna, mapWithoutTjps: src_MapWithoutTjps } = splitPerTjpAndOrDna({ ibGibs: srcIbGibs });
         const srcStones = Object.values(src_MapWithoutTjps);
         const srcLiving = [...Object.values(srcMapWithTjp_YesDna), ...Object.values(srcMapWithTjp_NoDna)];
-        if (logalot) {
-            console.log(`${lc} classification results (count):`);
-            console.log(`srcStones.length: ${srcStones.length}`);
-            console.log(`srcLiving.length: ${srcLiving.length}`);
-        }
         const srcTimelinesMap = getTimelinesGroupedByTjp({ ibGibs: srcLiving });
         const srcSortedTjps = this.sortTimelinesTopologically(srcTimelinesMap);
         return { srcStones, srcTimelinesMap, srcSortedTjps, srcGraph };
     }
-    async resolveConflicts({ source, dest, srcTimelinesMap, srcKnowledgeVector, srcGraph, uuid, conflictStrategy, }) {
-        const lc = `${this.lc}[${this.resolveConflicts.name}]`;
-        const srcTjps = Object.keys(srcTimelinesMap);
-        if (logalot) {
-            console.log(`${lc} getting latest addrs from space as destKnowledge. srcTjps: ${srcTjps} (I: a954369f2b58843a6773b00dd18eb325)`);
+    async resolveConflicts() {
+        throw new Error("resolveConflicts is no longer supported.");
+    }
+    async processBatchStream() {
+        // Deprecated by payload in SyncSagaContext
+        throw new Error("processBatchStream is no longer supported.");
+    }
+    /**
+     * Creates the Initial Saga Frame (Init Stage).
+     */
+    async createInitFrame({ sagaId, sessionIdentity, localSpace, domainIbGibs, tempSpace, metaspace }) {
+        const initData = {
+            sagaId,
+            stage: SyncStage.init,
+            knowledgeVector: {},
+            identity: sessionIdentity, // KeystoneIbGib is already public data
+            mode: SyncMode.sync,
+        };
+        // Populate Knowledge Vector
+        const { srcTimelinesMap, srcGraph } = await this.analyzeTimelines({ domainIbGibs, space: localSpace });
+        Object.keys(srcTimelinesMap).forEach(tjp => {
+            const timeline = srcTimelinesMap[tjp];
+            const tip = timeline.at(-1);
+            initData.knowledgeVector[tjp] = getIbGibAddr({ ibGib: tip });
+        });
+        const initStone = await this.createSyncMsgStone({
+            data: initData,
+            space: tempSpace,
+            metaspace
+        });
+        const sagaFrame = await this.evolveSyncSagaIbGib({
+            msgStones: [initStone],
+            identity: sessionIdentity,
+            space: tempSpace,
+            metaspace
+        });
+        return { sagaFrame, srcGraph };
+    }
+    /**
+     * Reacts to an incoming saga frame and dispatches to appropriate handler.
+     */
+    async handleSagaFrame({ sagaIbGib, srcGraph, space, identity, identitySecret, metaspace, }) {
+        const lc = `${this.lc}[${this.handleSagaFrame.name}]`;
+        try {
+            if (logalot) {
+                console.log(`${lc} starting... (I: 5deec8a1f7a6d263c88cd458ad990826)`);
+            }
+            if (!sagaIbGib.data) {
+                throw new Error(`(UNEXPECTED) sagaIbGib.data falsy? (E: 71b938adf1d87c2527bfd4f86dfd0826)`);
+            }
+            if (logalot) {
+                console.log(`${lc} handling frame stage: ${sagaIbGib.data.stage}`);
+            }
+            // Get Stage from Stone (or Frame for Init fallback)
+            const { stage, payload } = await this.getStageAndPayloadFromFrame({ ibGib: sagaIbGib, space });
+            switch (stage) {
+                case SyncStage.init:
+                    return await this.handleInitFrame({ sagaIbGib, payload, space, metaspace, identity, identitySecret });
+                case SyncStage.ack:
+                    return await this.handleAckFrame({ sagaIbGib, srcGraph, space, metaspace, identity });
+                case SyncStage.delta:
+                    return await this.handleDeltaFrame({ sagaIbGib, srcGraph, space, identity, metaspace });
+                case SyncStage.commit:
+                    return await this.handleCommitFrame({ sagaIbGib, space });
+                default:
+                    throw new Error(`${lc} (UNEXPECTED) Unknown sync stage: ${stage} (E: 9c2b4c8a6d34469f8263544710183355)`);
+            }
         }
-        // Get Dest Knowledge
-        const destKnowledge = await this.getLatestAddrsFromSpace({ space: dest, tjpAddrs: srcTjps });
-        if (logalot) {
-            console.log(`${lc} destKnowledge:\n${pretty(destKnowledge)} (I: f76108b5f228f4e2e1e79ad387deb325)`);
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
         }
-        const conflicts = [];
-        for (const tjp of srcTjps) {
-            const srcTimeline = srcTimelinesMap[tjp];
-            const srcTip = srcTimeline[srcTimeline.length - 1];
-            const srcTipAddr = getIbGibAddr({ ibGib: srcTip });
-            const destTipAddr = destKnowledge[tjp];
+        finally {
             if (logalot) {
-                console.log(`${lc} Checking TJP: ${tjp}`);
-                console.log(`${lc}   Source Tip: ${srcTipAddr}`);
-                console.log(`${lc}   Dest Tip:   ${destTipAddr}`);
+                console.log(`${lc} complete.`);
             }
-            if (destTipAddr && destTipAddr !== srcTipAddr) {
-                if (logalot) {
-                    console.log(`${lc} Divergence found. Check if Source knows Dest's tip. (I: d084d8abb6a84cc4a8301b51dec98825)`);
-                }
-                if (srcGraph[destTipAddr]) {
-                    // Fast-Forward: Dest tip IS in our graph, so we are ahead.
-                    // No action needed, proceed to push.
-                    if (logalot) {
-                        console.log(`${lc}   Fast-Forward (Source is ahead).`);
-                    }
-                }
-                else {
-                    // Conflict: Dest has a tip we don't know about.
-                    conflicts.push(tjp);
-                    if (logalot) {
-                        console.log(`${lc}   CONFLICT detected (Desc is ahead/divergent).`);
-                    }
+        }
+    }
+    // #region Handlers
+    async handleInitFrame({ sagaIbGib, payload, space, metaspace, identity, identitySecret, }) {
+        const lc = `${this.lc}[${this.handleInitFrame.name}]`;
+        if (logalot) {
+            console.log(`${lc} starting...`);
+        }
+        // Extract Init Data
+        const initData = sagaIbGib.data.payload;
+        if (!initData || !initData.knowledgeVector) {
+            throw new Error(`${lc} Invalid init frame: missing knowledgeVector (E: ed02c869e028d2d06841b9c7f80f2826)`);
+        }
+        const remoteKV = initData.knowledgeVector;
+        const remoteTjps = Object.keys(remoteKV);
+        // 1. Get Local Latest Addrs for all TJPs
+        let localKV = {};
+        if (remoteTjps.length > 0) {
+            // Batch get latest addrs for the TJPs
+            const arg = await space.argy({
+                argData: {
+                    cmd: 'get',
+                    cmdModifiers: ['latest', 'tjps'], // interprets input addrs as TJPs
+                    ibGibAddrs: remoteTjps,
                 }
+            });
+            const res = await space.witness(arg);
+            if (res?.data?.latestAddrsMap) {
+                localKV = res.data.latestAddrsMap;
+            }
+        }
+        // 2. Gap Analysis
+        const deltaReqAddrs = [];
+        const pushOfferAddrs = [];
+        // const divergentTjps: string[] = []; // Handle later
+        for (const tjp of remoteTjps) {
+            const remoteAddr = remoteKV[tjp];
+            const localAddr = localKV[tjp];
+            if (!localAddr) {
+                deltaReqAddrs.push(remoteAddr);
+                continue;
+            }
+            if (localAddr === remoteAddr) {
+                continue;
+            }
+            // Check if Remote is in Local's PAST (Local is Ahead -> Push Offer)
+            const isRemoteInPast = await isPastFrame({
+                olderAddr: remoteAddr,
+                newerAddr: localAddr,
+                space,
+            });
+            if (isRemoteInPast) {
+                pushOfferAddrs.push(localAddr);
             }
             else {
-                if (logalot) {
-                    console.log(`${lc}   No divergence detected (Tips match or Dest unknown).`);
-                }
+                deltaReqAddrs.push(remoteAddr);
             }
         }
-        // Lock conflicts
-        for (const tjp of conflicts) {
-            if (logalot) {
-                console.log(`${lc} Conflict detected for TJP ${tjp}. Acquiring lock...`);
-            }
-            // Lock VALIDITY: 60 seconds?
-            await lockSpace({
-                space: dest,
-                scope: tjp,
-                secondsValid: 60,
-                instanceId: uuid,
-            });
-            // Pull & Merge Logic
-            try {
-                const destTipAddr = destKnowledge[tjp];
-                if (!destTipAddr) {
-                    console.warn(`${lc} destTipAddr falsy in conflict loop? skipping. (W: 1a2b3c)`);
-                    continue;
-                }
-                const srcTipAddr = srcKnowledgeVector[tjp];
-                if (logalot) {
-                    console.log(`${lc} Pulling TJP ${tjp} from Dest...`);
-                }
-                // 1. Get Delta from Dest
-                // We want everything from Dest's tip back to what Source has.
-                // We can use getDependencyGraph with 'skipAddrs' if we know what to skip.
-                // Or just get the graph for the tip and filter?
-                // Graph helper is robust. Let's try to get the graph stopping at Source's tip.
-                // Optimization: We can't easily pass "stop at" to getDependencyGraph directly like "stopAt: [srcTipAddr]",
-                // but we can pass `gotten` or `skipAddrs`.
-                // If we pass `skipAddrs: [srcTipAddr]`, it should prune the graph traversal beyond that point?
-                // Actually `skipAddrs` prevents retrieving that node AND its past. So yes!
-                const skipAddrs = [];
-                if (srcTipAddr) {
-                    skipAddrs.push(srcTipAddr);
-                }
-                const deltaGraph = await getDependencyGraph({
-                    space: dest,
-                    ibGibs: [],
-                    ibGibAddrs: [destTipAddr],
-                    live: false, // We usually just want the static graph back to the divergence point for now? Or live? Live is safer but slower. 
-                    // If Dest is ahead, its tip IS the latest.
-                    skipAddrs,
-                });
-                if (logalot) {
-                    console.log(`${lc} Delta graph size: ${Object.keys(deltaGraph).length}`);
-                }
-                // 2. Put Delta into Source
-                const deltaIbGibs = Object.values(deltaGraph);
-                if (deltaIbGibs.length > 0) {
-                    if (logalot) {
-                        console.log(`${lc} Putting ${deltaIbGibs.length} ibGibs into Source (UUID: ${source.data?.uuid})...`);
-                        console.log(`${lc} Delta addrs: ${deltaIbGibs.map(x => getIbGibAddr({ ibGib: x })).join(', ')}`);
-                    }
-                    await putInSpace({ space: source, ibGibs: deltaIbGibs });
-                    if (logalot) {
-                        console.log(`${lc} Put complete.`);
-                    }
-                }
-                // 3. Re-evaluate / Merge
-                // Now Source has destTipAddr.
-                // If Source was strictly behind, srcTipAddr was an ancestor of destTipAddr.
-                // Source is now effectively fast-forwarded to destTipAddr.
-                // We need to check if we need to do a "Merge" (i.e. if Source HAD changes that are not in Dest).
-                // If srcTipAddr was in deltaGraph (Wait, we skipped it), or rather if srcTipAddr is an ancestor of destTip.
-                // If `skipAddrs` worked, we stopped AT srcTipAddr.
-                // Ideally check if `destTipAddr` reaches `srcTipAddr`.
-                // For now, in "Dest Ahead" scenario, we just assume we updated Source.
-                // We update our local tracking to proceed with potential Pushing back (if we were merging).
-                // If we simply pulled, do we need to push back?
-                // If Dest was strictly ahead, Source catch up. Source == Dest. No Push needed.
-                // Logic:
-                // If Source now has destTipAddr as Latest, we are good.
-                // TODO: Handle actual DIVERGENCE (Merge). 
-                // This implementation covers "Dest Ahead" (Fast-Backward).
-                // But if we truly diverged (Source has changes not in Dest, and Dest has changes not in Source),
-                // checks are needed.
-                // If conflictStrategy is abort, we should probably check if `srcTipAddr` is an ancestor of `destTipAddr`.
-                // If `srcTipAddr` is NOT an ancestor, then we have a divergence. 
-                // Getting ancestry is expensive without graph traversal.
-                // But we just pulled `deltaGraph`. If `srcTipAddr` was `skipped` during traversal,
-                // it implies it WAS reachable from `destTipAddr`.
-                // Wait, `skipAddrs` just stops traversal. It doesn't confirm reachability if we assume it stops *at* the addr.
-                // Actually `getDependencyGraph` with `skipAddrs` stops descending if it hits a skipped addr.
-                // If it hits it, it means `srcTipAddr` IS an ancestor.
-                // If it never hits it, `srcTipAddr` might NOT be an ancestor (divergence).
-                // Or `srcTipAddr` is just disjoint?
-                // Let's rely on the fact that if we simply "Pull", we are essentially overwriting Source's "Latest" pointer 
-                // if we don't do anything else.
-                // If Source had 'A', and Dest had 'B', and we pull 'B'. Source now has 'A' and 'B'.
-                // If we don't merge, Source is now just "containing" B.
-                if (conflictStrategy === 'abort') {
-                    // Verify if it's a true divergence or just a Fast-Forward we haven't tracked yet.
-                    // If srcTipAddr is an ancestor of destTipAddr, it is a valid FF.
-                    if (srcTipAddr) {
-                        const isFF = await this.isAncestor({
-                            ancestorAddr: srcTipAddr,
-                            descendantAddr: destTipAddr,
-                            space: source
-                        });
-                        if (isFF) {
-                            if (logalot) {
-                                console.log(`${lc} Verified Fast-Forward/Pull (srcTip is ancestor). No abort.`);
-                            }
-                        }
-                        else {
-                            throw new Error(`Sync Aborted: Divergence detected on TJP ${tjp}. Source Tip: ${srcTipAddr}, Dest Tip: ${destTipAddr}. Strategy is 'abort'.`);
-                        }
-                    }
-                    else {
-                        // source has no tip (new timeline for source), so it's a valid pull.
-                    }
-                }
-                else if (conflictStrategy === 'optimistic') {
-                    console.warn(`${lc} Optimistic merge not yet fully implemented. Proceeding with Pulled data but Source Tip is still the effective 'latest' for this session unless merged. (W: todo_merge)`);
+        // 3. Create Ack Frame
+        const sagaId = sagaIbGib.data.uuid;
+        // Create Payload Stone
+        const ackData = {
+            sagaId,
+            stage: SyncStage.ack,
+            deltaReqAddrs,
+            pushOfferAddrs,
+        };
+        const ackStone = await this.createSyncMsgStone({
+            data: ackData,
+            space,
+            metaspace,
+        });
+        // Evolve Saga
+        const ackFrame = await this.evolveSyncSagaIbGib({
+            prevSagaIbGib: sagaIbGib,
+            msgStones: [ackStone],
+            identity,
+            space,
+            metaspace,
+        });
+        return { frame: ackFrame };
+    }
+    async handleAckFrame({ sagaIbGib, srcGraph, space, metaspace, identity, }) {
+        const lc = `${this.lc}[${this.handleAckFrame.name}]`;
+        if (logalot) {
+            console.log(`${lc} starting...`);
+        }
+        const { payload } = await this.getStageAndPayloadFromFrame({ ibGib: sagaIbGib, space });
+        const ackData = payload;
+        if (!ackData || ackData.stage !== SyncStage.ack) {
+            throw new Error(`${lc} Invalid ack frame (E: 2e8b0a94b5954a66a6a1a7a0b3f5b7a1)`);
+        }
+        const deltaReqAddrs = ackData.deltaReqAddrs || [];
+        const pushOfferAddrs = ackData.pushOfferAddrs || [];
+        // 1. Process Push Offers (Pull Requests) (Naive: Accept all if missing)
+        const pullReqAddrs = [];
+        for (const addr of pushOfferAddrs) {
+            const existing = srcGraph[addr] || (await getFromSpace({ addr, space })).ibGibs?.[0];
+            if (!existing) {
+                pullReqAddrs.push(addr);
+            }
+        }
+        // 2. Process Delta Requests (Push Payload)
+        const payloadIbGibs = [];
+        for (const addr of deltaReqAddrs) {
+            let ibGib = srcGraph[addr];
+            if (!ibGib) {
+                const res = await getFromSpace({ addr, space });
+                if (res.ibGibs && res.ibGibs.length > 0) {
+                    ibGib = res.ibGibs[0];
                 }
             }
-            catch (err) {
-                console.error(`${lc} Error dealing with conflict/pull for TJP ${tjp}: ${extractErrorMsg(err)}`);
-                if (conflictStrategy === 'abort')
-                    throw err;
+            if (ibGib) {
+                payloadIbGibs.push(ibGib);
+            }
+            else {
+                console.warn(`${lc} Requested addr not found: ${addr}`);
             }
-            await unlockSpace({
-                space: dest,
-                scope: tjp,
-                instanceId: uuid,
-            });
         }
+        // 3. Create Delta Frame
+        const sagaId = ackData.sagaId;
+        const deltaData = {
+            sagaId,
+            stage: SyncStage.delta,
+            payloadAddrs: payloadIbGibs.map(p => getIbGibAddr({ ibGib: p })),
+            requests: pullReqAddrs.length > 0 ? pullReqAddrs : undefined,
+        };
+        const deltaStone = await this.createSyncMsgStone({
+            data: deltaData,
+            space,
+            metaspace,
+        });
+        const deltaFrame = await this.evolveSyncSagaIbGib({
+            prevSagaIbGib: sagaIbGib,
+            msgStones: [deltaStone],
+            identity,
+            space,
+            metaspace,
+        });
+        return { frame: deltaFrame, payload: payloadIbGibs };
     }
-    async processBatchStream({ dest, payloadAddrs, srcGraph }) {
-        const lc = `${this.lc}[${this.processBatchStream.name}]`;
-        // 3.1 Stream the actual data (Batch Stream)
-        // We must preserve the order in payloadAddrs to respect dependencies.
-        // We batch them to improve throughput.
-        const BATCH_SIZE = 20;
-        for (let i = 0; i < payloadAddrs.length; i += BATCH_SIZE) {
-            const chunkAddrs = payloadAddrs.slice(i, i + BATCH_SIZE);
-            const chunkIbGibs = chunkAddrs
-                .map(addr => {
-                const ibGib = srcGraph[addr];
-                if (!ibGib) {
-                    throw new Error(`(UNEXPECTED) addr not found in graph: ${addr} (E: 8a402324057849318625aa85721665a5)`);
+    async handleDeltaFrame({ sagaIbGib, srcGraph, space, metaspace, identity, }) {
+        const lc = `${this.lc}[${this.handleDeltaFrame.name}]`;
+        if (logalot) {
+            console.log(`${lc} starting...`);
+        }
+        const { payload } = await this.getStageAndPayloadFromFrame({ ibGib: sagaIbGib, space });
+        const deltaData = payload;
+        if (!deltaData || deltaData.stage !== SyncStage.delta) {
+            throw new Error(`${lc} Invalid delta frame (E: 7c28c8d8f08a4421b8344e6727271421)`);
+        }
+        const payloadAddrs = deltaData.payloadAddrs || [];
+        const requests = deltaData.requests || [];
+        // 1. Process Received Payload
+        const receivedPayload = [];
+        if (payloadAddrs.length > 0) {
+            const res = await space.witness({
+                attribute: 'ibGibs',
+                arg: {
+                    ibGibAddrs: payloadAddrs,
+                    cmd: 'get',
                 }
-                return ibGib;
-            })
-                .filter(ibGib => !isPrimitive({ ibGib }));
-            if (chunkIbGibs.length > 0) {
-                if (logalot) {
-                    console.log(`${lc} streaming batch ${Math.ceil(i / BATCH_SIZE) + 1} (${chunkIbGibs.length} ibGibs)...`);
+            });
+            if (res.data?.ibGibs) {
+                receivedPayload.push(...res.data.ibGibs);
+            }
+        }
+        // 2. Fulfill Requests (Outgoing Payload)
+        const outgoingPayload = [];
+        for (const addr of requests) {
+            let ibGib = srcGraph[addr];
+            if (!ibGib) {
+                const res = await getFromSpace({ addr, space });
+                if (res.ibGibs && res.ibGibs.length > 0) {
+                    ibGib = res.ibGibs[0];
                 }
-                // We don't set isDna: true here because the batch might contain mixed types.
-                // The Space implementation should handle routing based on internal metadata if needed.
-                await putInSpace({ space: dest, ibGibs: chunkIbGibs });
+            }
+            if (ibGib) {
+                outgoingPayload.push(ibGib);
             }
         }
+        // 3. Determine Next Stage
+        if (requests.length > 0) {
+            // They requested more data -> Send Delta
+            const sagaId = deltaData.sagaId;
+            const responseDeltaData = {
+                sagaId,
+                stage: SyncStage.delta,
+                payloadAddrs: outgoingPayload.map(p => getIbGibAddr({ ibGib: p })),
+            };
+            const deltaStone = await this.createSyncMsgStone({
+                data: responseDeltaData,
+                space,
+                metaspace
+            });
+            const deltaFrame = await this.evolveSyncSagaIbGib({
+                prevSagaIbGib: sagaIbGib,
+                msgStones: [deltaStone],
+                identity,
+                space,
+                metaspace
+            });
+            return { frame: deltaFrame, payload: outgoingPayload, receivedPayload };
+        }
+        else {
+            // No requests -> Commit
+            const sagaId = deltaData.sagaId;
+            const commitData = {
+                sagaId,
+                stage: SyncStage.commit,
+                success: true,
+            };
+            const commitStone = await this.createSyncMsgStone({
+                data: commitData,
+                space,
+                metaspace
+            });
+            const commitFrame = await this.evolveSyncSagaIbGib({
+                prevSagaIbGib: sagaIbGib,
+                msgStones: [commitStone],
+                identity,
+                space,
+                metaspace
+            });
+            return { frame: commitFrame, receivedPayload };
+        }
     }
-    async createSyncFrame({ uuid, stage, payload, identity }) {
-        const data = {
-            uuid,
-            stage,
-            payload
-        };
-        const ib = await getSyncIb({ data });
-        // Create the ibGib using Factory? Or manually?
-        // Factory_V1.firstGen usually.
-        const res = await Factory_V1.firstGen({
-            parentIbGib: Factory_V1.primitive({ ib: SYNC_ATOM }),
+    async handleCommitFrame({ sagaIbGib, space, }) {
+        const lc = `${this.lc}[${this.handleCommitFrame.name}]`;
+        if (logalot) {
+            console.log(`${lc} Commit received. Saga complete.`);
+        }
+        return null;
+    }
+    // #endregion Handlers
+    async createSyncMsgStone({ data, space, metaspace, }) {
+        const ib = await getSyncSagaMessageIb({ data });
+        const stone = await Factory_V1.stone({
             ib,
+            parentPrimitiveIb: SYNC_SAGA_MSG_ATOM,
             data,
-            rel8ns: {
-                identity: [getIbGibAddr({ ibGib: identity })]
-            },
-            /**
-             * dna is used for merging dynamic timelines, a la a CRDT-like
-             * mechanism that looks somewhat like event sourcing but using
-             * crypto primitives. in our particular case, the sync should be a
-             * single, one-off timeline (not to be used for any future merging),
-             * so we don't need dna.
-             */
-            dna: false,
-            tjp: {
-                timestamp: true,
-                /**
-                 * we'll use the uuid passed in
-                 */
-                uuid: false
-            },
-            nCounter: true,
+            uuid: true, // we want the stone to have its own uniqueness
         });
-        return res.newIbGib;
+        await putInSpace({ space, ibGib: stone });
+        await metaspace.registerNewIbGib({ ibGib: stone });
+        return stone;
     }
-    async getLatestAddrsFromSpace({ space, tjpAddrs, }) {
-        const lc = `${this.lc}[${this.getLatestAddrsFromSpace.name}]`;
+    /**
+     * Evolves the saga timeline with a new frame.
+     */
+    async evolveSyncSagaIbGib({ prevSagaIbGib, msgStones, identity, space, metaspace, }) {
+        const lc = `${this.lc}[${this.evolveSyncSagaIbGib.name}]`;
         try {
-            if (tjpAddrs.length === 0) {
-                console.warn(`${lc} getting latest addrs for empty tjpAddrs? this may be reasonable but sounds odd. (W: 2f57c6d7c195034e982dfd38201db825)`);
-                return {};
+            // Validation
+            if (!msgStones || msgStones.length === 0) {
+                throw new Error(`${lc} msgStones required (E: d13f8afcfb8816aeb26baae7df3ef726)`);
             }
-            let map = {};
-            const resLatest = await getLatestAddrs({
-                tjpAddrs,
-                space,
-            });
-            if (!resLatest.data) {
-                throw new Error(`(UNEXPECTED) resLatest.data falsy? (E: 289dd61a79fa33a4f87baaa83e3c0825)`);
+            const firstStoneData = msgStones[0].data;
+            if (!firstStoneData?.sagaId || !firstStoneData?.stage) {
+                throw new Error(`${lc} Invalid stone data (missing sagaId or stage) (E: c004f85ce8f8958b11839f8d68c38826)`);
             }
-            if (resLatest.data.success) {
-                map = clone(resLatest.data.latestAddrsMap);
+            const sagaId = firstStoneData.sagaId;
+            const stage = firstStoneData.stage;
+            // Ensure all stones match sagaId and stage
+            for (const stone of msgStones) {
+                const d = stone.data;
+                if (d.sagaId !== sagaId) {
+                    throw new Error(`${lc} Mismatched sagaId in stones. Expected ${sagaId}, got ${d.sagaId} (E: 29e02719e426ecbbf8ee66887a2be226)`);
+                }
+                if (d.stage !== stage) {
+                    throw new Error(`${lc} Mismatched stage in stones. Expected ${stage}, got ${d.stage} (E: d12c6571b0882f762921b60880c3f826)`);
+                }
+            }
+            const identityAddr = getIbGibAddr({ ibGib: identity });
+            if (prevSagaIbGib) {
+                // Append to existing timeline
+                const resAppend = await appendToTimeline({
+                    timeline: prevSagaIbGib,
+                    rel8nInfos: [
+                        {
+                            rel8nName: SYNC_MSG_REL8N_NAME,
+                            ibGibs: msgStones,
+                        },
+                        {
+                            rel8nName: 'identity',
+                            ibGibs: [identity],
+                        }
+                    ],
+                    metaspace,
+                    space,
+                    noDna: true, // Explicitly no DNA for sync frames
+                });
+                const newFrame = resAppend;
+                return newFrame;
             }
             else {
-                tjpAddrs.forEach(x => { map[x] = null; });
-            }
-            // Using the space's witness/argy pattern to invoke 'get' with 'latest' modifier
-            // const arg = await space.argy({
-            //     ibMetadata: getSpaceArgMetadata({ space }),
-            //     argData: {
-            //         cmd: 'get',
-            //         cmdModifiers: ['latest', 'addrs'],
-            //         ibGibAddrs: tjpAddrs,
-            //     }
-            // });
-            // const result = await space.witness(arg);
-            // const map: { [tjp: string]: string } = {};
-            // if (result?.data?.success && result.data.addrs) {
-            //     // assume 1-to-1 mapping order as per convention if successful
-            //     // verification is hard without specific return map
-            //     if (result.data.addrs.length === tjpAddrs.length) {
-            //         for (let i = 0; i < tjpAddrs.length; i++) {
-            //             map[tjpAddrs[i]] = result.data.addrs[i];
-            //         }
-            //     } else {
-            //         console.warn(`${lc} result addrs length mismatch. requested: ${tjpAddrs.length}, got: ${result.data.addrs.length}. Mapping might be unsafe.`);
-            //     }
-            // }
-            return map;
+                // Create New Timeline (Root Frame)
+                const data = {
+                    uuid: sagaId,
+                    stage,
+                    payload: undefined, // Data in stone
+                };
+                const ib = await getSyncIb({ data });
+                const stoneAddrs = msgStones.map(s => getIbGibAddr({ ibGib: s }));
+                const resNew = await createTimeline({
+                    space,
+                    metaspace,
+                    ib,
+                    data,
+                    rel8ns: {
+                        [SYNC_MSG_REL8N_NAME]: stoneAddrs,
+                        identity: [identityAddr],
+                    },
+                    parentIb: SYNC_ATOM, // "sync"
+                    noDna: true,
+                });
+                return resNew.newIbGib;
+            }
         }
         catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
-            return {}; // fail safe
+            throw error;
+        }
+    }
+    async getStageAndPayloadFromFrame({ ibGib, space }) {
+        // 1. Try Stone (Primary)
+        const stoneAddrs = ibGib.rel8ns?.[SYNC_MSG_REL8N_NAME];
+        if (stoneAddrs && stoneAddrs.length > 0) {
+            const stoneAddr = stoneAddrs[0];
+            const res = await getFromSpace({ addr: stoneAddr, space });
+            if (res.ibGibs && res.ibGibs.length > 0) {
+                const stone = res.ibGibs[0];
+                if (stone.data && stone.data.stage) {
+                    return { stage: stone.data.stage, payload: stone.data };
+                }
+            }
+        }
+        // 2. Fallback to Frame Data (Legacy/Init compatibility)
+        if (ibGib.data && ibGib.data.stage) {
+            return { stage: ibGib.data.stage, payload: ibGib.data.payload };
         }
+        throw new Error(`Could not determine stage from frame ${getIbGibAddr({ ibGib })}`);
     }
     sortTimelinesTopologically(timelines) {
         const lc = `${this.lc}[${this.sortTimelinesTopologically.name}]`;
@@ -555,38 +671,5 @@ export class SyncSagaCoordinator {
         });
         return sorted;
     }
-    /**
-     * Checks if an address is an ancestor of another by traversing `past` relations.
-     * Uses BFS. Returns true if `ancestorAddr` is found in the history of `descendantAddr`.
-     */
-    async isAncestor({ ancestorAddr, descendantAddr, space, }) {
-        if (ancestorAddr === descendantAddr)
-            return true;
-        const queue = [descendantAddr];
-        const visited = new Set();
-        while (queue.length > 0) {
-            const currentAddr = queue.shift();
-            if (visited.has(currentAddr))
-                continue;
-            visited.add(currentAddr);
-            if (currentAddr === ancestorAddr)
-                return true;
-            // Get node to find past
-            const res = await getFromSpace({ space, addr: currentAddr });
-            if (!res.success || !res.ibGibs || res.ibGibs.length === 0) {
-                continue;
-            }
-            const node = res.ibGibs[0];
-            if (node.rel8ns && node.rel8ns.past) {
-                // Check pasts
-                for (const pastAddr of node.rel8ns.past) {
-                    if (!visited.has(pastAddr)) {
-                        queue.push(pastAddr);
-                    }
-                }
-            }
-        }
-        return false;
-    }
 }
 //# sourceMappingURL=sync-saga-coordinator.mjs.map