@ibgib/core-gib 0.1.12 → 0.1.14

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

@@ -2,70 +2,21 @@ import { extractErrorMsg, getUUID } from "@ibgib/helper-gib/dist/helpers/utils-h
 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, getSpaceArgMetadata } 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";
-const logalot = GLOBAL_LOG_A_LOT;
+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;
@@ -74,187 +25,242 @@ 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 }) {
+    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
-            // ---------------------------------------------------------
-            // We want a live dependency graph to ensure we get the latest
-            // states of timelines.
-            const graph = await getDependencyGraph({
-                ibGibs: domainIbGibs,
-                live: true,
-                space: source,
-            });
-            const validGraph = graph && Object.keys(graph).length > 0;
-            if (logalot) {
-                console.log(`${lc} graph generated. nodes: ${validGraph ? Object.keys(graph).length : 0}`);
-            }
-            // 2. Classification
-            // We differentiate between "Stones" (Immutable, no timeline) and "Living" (Timelines).
-            // Stones can be synced in bulk without ordering.
-            // Living ibGibs must be grouped by timeline and ordered.
-            const ibGibs = validGraph ? Object.values(graph) : [];
-            const { mapWithTjp_YesDna, mapWithTjp_NoDna, mapWithoutTjps } = splitPerTjpAndOrDna({ ibGibs });
-            // "Stones" come from mapWithoutTjps
-            const stones = Object.values(mapWithoutTjps);
-            // "Living" come from both TJP maps
-            // We combine them to group by TJP
-            const living = [...Object.values(mapWithTjp_YesDna), ...Object.values(mapWithTjp_NoDna)];
-            if (logalot) {
-                console.log(`${lc} classification results (count):`);
-                console.log(`stones: ${stones.length}`);
-                console.log(`living: ${living.length}`);
-            }
-            // 3. Timeline Ordering
-            // Group living ibGibs by TJP to identify distinct timelines.
-            // The helper returns them sorted by 'n' ascending.
-            const timelinesMap = getTimelinesGroupedByTjp({ ibGibs: living });
-            // todo: perform topological sort on timelinesMap based on inter-timeline references.
-            // For now, we sync independent timelines.
-            const payloadAddrs = [];
-            payloadAddrs.push(...stones.map(x => getIbGibAddr({ ibGib: x })));
-            // 3. Timeline Ordering (Topological Sort)
-            // Living ibGibs are grouped by timeline (TJP).
-            // We need to order these timelines based on dependencies.
-            const sortedTjps = this.sortTimelinesTopologically(timelinesMap);
-            // Add ordered timelines to payload
-            sortedTjps.forEach(tjp => {
-                const timeline = timelinesMap[tjp];
-                payloadAddrs.push(...timeline.map(x => getIbGibAddr({ ibGib: x })));
-            });
-            // 2. INIT & Phase 2: Knowledge Exchange
-            const srcKnowledgeVector = {};
-            Object.keys(timelinesMap).forEach(tjp => {
-                const timeline = timelinesMap[tjp];
-                const tip = timeline[timeline.length - 1];
-                srcKnowledgeVector[tjp] = getIbGibAddr({ ibGib: tip });
-            });
-            const initData = {
-                knowledgeVector: srcKnowledgeVector,
-                identity: identity,
-                mode: 'push'
-            };
-            // Get Source Knowledge (Time -> Latest)
-            const srcTjps = Object.keys(timelinesMap);
-            // Get Dest Knowledge
-            const destKnowledge = await this.getLatestAddrsFromSpace({ space: dest, tjpAddrs: srcTjps });
-            const conflicts = [];
-            for (const tjp of srcTjps) {
-                const srcTimeline = timelinesMap[tjp];
-                const srcTip = srcTimeline[srcTimeline.length - 1];
-                const srcTipAddr = getIbGibAddr({ ibGib: srcTip });
-                const destTipAddr = destKnowledge[tjp];
-                if (destTipAddr && destTipAddr !== srcTipAddr) {
-                    // Divergence found. Check if Source knows Dest's tip.
-                    if (graph[destTipAddr]) {
-                        // Fast-Forward: Dest tip IS in our graph, so we are ahead.
-                        // No action needed, proceed to push.
-                    }
-                    else {
-                        // Conflict: Dest has a tip we don't know about.
-                        conflicts.push(tjp);
-                    }
-                }
+        if (logalot) {
+            console.log(`${lc} starting...`);
+        }
+        // 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
             }
-            // 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,
+        });
+        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
                 });
-                // todo: Implement Pull & Merge here
-                // 1. Pull delta from Dest (destTip -> ... -> common ancestor)
-                // 2. Merge locally
-                // 3. Update graph/timelinesMap with merged result
-                if (logalot) {
-                    console.warn(`${lc} Merge not fully implemented yet. Releasing lock.`);
-                }
-                await unlockSpace({
-                    space: dest,
-                    scope: tjp,
-                    instanceId: uuid,
+                // 3. CREATE INITIAL FRAME (Stage.init)
+                const { sagaFrame: initFrame, srcGraph } = await this.createInitFrame({
+                    sagaId,
+                    sessionIdentity,
+                    localSpace,
+                    domainIbGibs,
+                    tempSpace,
+                    metaspace,
                 });
-            }
-            const initFrame = await this.createSyncFrame({
-                uuid,
-                stage: SyncStage.init,
-                payload: initData,
-                identity
-            });
-            // Persist Init to Dest (Handshake)
-            await putInSpace({ space: dest, ibGib: initFrame });
-            // 3. DELTA
-            // const payloadAddrs = [getIbGibAddr({ ibGib: identity })]; // Already computed above
-            const deltaData = {
-                payloadAddrs
-            };
-            const deltaFrame = await this.createSyncFrame({
-                uuid,
-                stage: SyncStage.delta,
-                payload: deltaData,
-                identity
-            });
-            await putInSpace({ space: dest, ibGib: deltaFrame });
-            // 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 = graph[addr];
-                    if (!ibGib) {
-                        throw new Error(`(UNEXPECTED) addr not found in graph: ${addr} (E: 8a402324057849318625aa85721665a5)`);
-                    }
-                    return ibGib;
-                })
-                    .filter(ibGib => !isPrimitive({ ibGib }));
-                if (chunkIbGibs.length > 0) {
+                // 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} streaming batch ${Math.ceil(i / BATCH_SIZE) + 1} (${chunkIbGibs.length} ibGibs)...`);
+                        console.log(`${lc} Merging ${syncedIbGibs.length} synced ibGibs to localSpace...`);
                     }
-                    // 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 });
+                    await putInSpace({ space: localSpace, ibGibs: syncedIbGibs });
                 }
+                resolveDone();
+                updates$.complete();
             }
-            // 4. COMMIT
-            const commitData = {
-                success: true
-            };
-            const commitFrame = await this.createSyncFrame({
-                uuid,
-                stage: SyncStage.commit,
-                payload: commitData,
-                identity
+            catch (error) {
+                console.error(`${lc} ${extractErrorMsg(error)}`);
+                rejectDone(error);
+                updates$.error(error);
+            }
+            finally {
+                await cleanup();
+            }
+        })();
+        return {
+            sagaId,
+            updates$,
+            done
+        };
+    }
+    /**
+     * 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,
             });
-            await putInSpace({ space: dest, ibGib: commitFrame });
+            // 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({
+            ibGibs: domainIbGibs,
+            live: true,
+            space,
+        });
+        const srcGraphIsValid = srcGraph && Object.keys(srcGraph).length > 0;
+        if (logalot) {
+            console.log(`${lc} graph generated. nodes: ${srcGraphIsValid ? Object.keys(srcGraph).length : 0}`);
+        }
+        const srcIbGibs = srcGraphIsValid ? Object.values(srcGraph) : [];
+        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)];
+        const srcTimelinesMap = getTimelinesGroupedByTjp({ ibGibs: srcLiving });
+        const srcSortedTjps = this.sortTimelinesTopologically(srcTimelinesMap);
+        return { srcStones, srcTimelinesMap, srcSortedTjps, srcGraph };
+    }
+    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)`);
+            }
         }
         catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -266,76 +272,346 @@ export class SyncSagaCoordinator {
             }
         }
     }
-    async createSyncFrame({ uuid, stage, payload, identity }) {
-        const data = {
-            uuid,
-            stage,
-            payload
+    // #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 {
+                deltaReqAddrs.push(remoteAddr);
+            }
+        }
+        // 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];
+                }
+            }
+            if (ibGib) {
+                payloadIbGibs.push(ibGib);
+            }
+            else {
+                console.warn(`${lc} Requested addr not found: ${addr}`);
+            }
+        }
+        // 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 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 }),
+        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 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',
+                }
+            });
+            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];
+                }
+            }
+            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 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) {
-                return {};
+            // Validation
+            if (!msgStones || msgStones.length === 0) {
+                throw new Error(`${lc} msgStones required (E: d13f8afcfb8816aeb26baae7df3ef726)`);
             }
-            // 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 = {};
-            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];
-                    }
+            const firstStoneData = msgStones[0].data;
+            if (!firstStoneData?.sagaId || !firstStoneData?.stage) {
+                throw new Error(`${lc} Invalid stone data (missing sagaId or stage) (E: c004f85ce8f8958b11839f8d68c38826)`);
+            }
+            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)`);
                 }
-                else {
-                    console.warn(`${lc} result addrs length mismatch. requested: ${tjpAddrs.length}, got: ${result.data.addrs.length}. Mapping might be unsafe.`);
+                if (d.stage !== stage) {
+                    throw new Error(`${lc} Mismatched stage in stones. Expected ${stage}, got ${d.stage} (E: d12c6571b0882f762921b60880c3f826)`);
                 }
             }
-            return map;
+            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 {
+                // 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}]`;