@ibgib/core-gib 0.1.28 → 0.1.30

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

@@ -2,12 +2,13 @@ import { extractErrorMsg, getUUID, // so our timestamp in ticks as a string are
 pretty, delay, } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
 import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
 import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
+import { GLOBAL_LOG_A_LOT } from "../core-constants.mjs";
 import { putInSpace, getLatestAddrs, getFromSpace } from "../witness/space/space-helper.mjs";
 import { SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN, } from "./sync-constants.mjs";
-import { appendToTimeline, createTimeline } from "../timeline/timeline-api.mjs";
+import { appendToTimeline, createTimeline, getHistoryAddrs } from "../timeline/timeline-api.mjs";
 import { SyncConflictStrategy, SyncMode, SYNC_CONFLICT_STRATEGY_VALID_VALUES, } from "./sync-types.mjs";
-import { getFullSyncSagaHistory, getSyncIb, getTempSpaceName, isPastFrame, putInSpace_dnasThenNonDnas, validateFullSyncSagaHistory } from "./sync-helpers.mjs";
-import { getDeltaDependencyGraph, getDependencyGraph, toFlatGraph } from "../common/other/graph-helper.mjs";
+import { getSyncSagaFrameOrigin, getFullSyncSagaHistory, getSyncIb, getTempSpaceName, isPastFrame, putInSpace_dnasThenNonDnas, validateFullSyncSagaHistory } from "./sync-helpers.mjs";
+import { getDeltaDependencyGraph, 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 { splitPerTjpAndOrDna, getTimelinesGroupedByTjp, isIbGib } from "../common/other/ibgib-helper.mjs";
@@ -16,9 +17,8 @@ import { newupSubject, } from "../common/pubsub/subject/subject-helper.mjs";
 import { mergeDivergentTimelines } from "./strategies/conflict-optimistic.mjs";
 import { getSyncSagaMessageFromFrame } from "./sync-saga-message/sync-saga-message-helpers.mjs";
 import { fnObs } from "../common/pubsub/observer/observer-helper.mjs";
-// const logalot = GLOBAL_LOG_A_LOT || true;
-const logalot = true;
-const logalotControlDomain = true;
+const logalot = GLOBAL_LOG_A_LOT;
+const logalotControlDomain = false;
 const lcControlDomain = '[ControlDomain]';
 /**
  * Orchestrates the synchronization process between two spaces (Source and Destination).
@@ -407,8 +407,13 @@ export class SyncSagaCoordinator {
                 metaspace,
             });
             if (!contextResult) {
+                // should this ever hit?
+                console.error(`${lc} NAG ERROR (DOES NOT THROW): does this ever hit now? (E: e04d02efc2a8e72a88b79f1f0f95ca26)`);
+                break;
+            }
+            else if (contextResult.nextFrameInfo?.sagaComplete) {
                 if (logalot) {
-                    console.log(`${lc} Handler returned null (Saga End). (I: faae22abc818ba9b28ac6d2881cd7826)`);
+                    console.log(`${lc} Handler returned null (Saga End). (I: 123bf9e7dca8886de72553a8d4f29e26)`);
                 }
                 break;
             }
@@ -419,9 +424,6 @@ export class SyncSagaCoordinator {
             else if (!contextResult.nextFrameInfo) {
                 throw new Error(`(UNEXPECTED) contextResult.nextFrameInfo falsy? (E: c287a82e823e662a77923278e2418826)`);
             }
-            else if (contextResult.nextFrameInfo?.sagaComplete) {
-                throw new Error(`(UNEXPECTED) contextResult.nextFrameInfo.sagaComplete? logic flow should not have gotten here. (E: 104a32381db816b7183435e805b3d626)`);
-            }
             // #endregion error conditions throw
             // we have another frame to process and send out, with possibly
             // payload domain ibgibs as well
@@ -439,11 +441,11 @@ export class SyncSagaCoordinator {
         }
     }
     /**
-     * Helper to get Knowledge Vector for specific domain ibGibs or TJPs.
+     * Helper to get Knowledge Map for specific domain ibGibs or TJPs.
      * Useful for testing and external validation.
      */
-    async getKnowledgeVector({ space, metaspace, domainIbGibs, tjpAddrs, }) {
-        const lc = `${this.lc}[${this.getKnowledgeVector.name}]`;
+    async getKnowledgeMap({ space, metaspace, domainIbGibs, tjpAddrs, }) {
+        const lc = `${this.lc}[${this.getKnowledgeMap.name}]`;
         try {
             if (logalot) {
                 console.log(`${lc} starting... (I: e184f8a7818666febfbbd2d841ed3826)`);
@@ -484,7 +486,7 @@ export class SyncSagaCoordinator {
             else {
                 // No info provided. Return empty? Or throw?
                 // User test context implied "everything", but implementation requires scope.
-                console.warn(`${lc} No domainIbGibs or tjpAddrs provided. Returning empty KV.`);
+                console.warn(`${lc} No domainIbGibs or tjpAddrs provided. Returning empty Knowledge.`);
                 return {};
             }
             if (tjps.length === 0) {
@@ -538,7 +540,7 @@ export class SyncSagaCoordinator {
      * @remarks
      * **Execution Context**: **Sender (Local)**.
      *
-     * Generates the first frame containing the Knowledge Vector of the Local Space.
+     * Generates the first frame containing the Knowledge Map of the Local Space.
      * This is sent to the Receiver to begin Gap Analysis.
      */
     async createInitFrame({ sagaId, sessionIdentity, domainIbGibs, conflictStrategy, metaspace, localSpace, tempSpace, }) {
@@ -553,17 +555,17 @@ export class SyncSagaCoordinator {
             const { timelinesMap: srcTimelinesMap, fullGraph, stones: srcStones, } = analysis;
             // we need to store the fullGraph in our tempSpace for later...
             await putInSpace({ ibGibs: Object.values(fullGraph), space: tempSpace });
-            // populate our knowledge vector with tjp -> latest addr/tip in timeline
-            const knowledgeVector = {};
+            // populate our knowledge map with tjp -> latest addr/tip in timeline
+            const knowledgeMap = {};
             Object.keys(srcTimelinesMap).forEach(tjp => {
                 const timeline = srcTimelinesMap[tjp];
                 const tip = timeline.at(-1);
-                knowledgeVector[tjp] = getIbGibAddr({ ibGib: tip });
+                knowledgeMap[tjp] = getIbGibAddr({ ibGib: tip });
             });
             const initData = {
                 sagaId,
                 stage: SyncStage.init,
-                knowledgeVector,
+                knowledgeMap: knowledgeMap,
                 identity: sessionIdentity, // KeystoneIbGib is already public data
                 mode: SyncMode.sync,
                 stones: srcStones.map(s => getIbGibAddr({ ibGib: s })),
@@ -670,16 +672,21 @@ export class SyncSagaCoordinator {
      *
      * ## 1. Sender
      *
-     * On the sender, this is called within the {@link executeSagaLoop} which
-     * initiates and drives the sync.
+     * On the sender, this is called repeatedly within the the sync saga
+     * coordinator's {@link executeSagaLoop} which initiates and drives the
+     * overall sync process. This loop continues until there are no more frames
+     * to be exchanged between endpoints.
      *
      * ## 2. Receiver
      *
-     * On the receiver, this is called directly by the receiving endpoint. That
-     * endpoint's job is basically to get these things collocated and prepared
-     * to make this call.
+     * On the receiver, this is called directly from {@link continueSync}, which
+     * itself is called either directly by the concrete sync peer or from within
+     * the receiving node endpoint. That endpoint's job is basically to get
+     * these things collocated and prepared to make this call.
      *
-     * This is a one-off on the receiver.
+     * In contrast to the sender, this can be thought of as a one-off on the
+     * receiver, since the sender's {@link executeSagaLoop} is what actually
+     * drives the ping-pong process.
      */
     async handleResponseSagaContext({ sagaContext, initDomainGraph, mySpace, myTempSpace, identity, identitySecret, metaspace, }) {
         const lc = `${this.lc}[${this.handleResponseSagaContext.name}]`;
@@ -699,10 +706,6 @@ export class SyncSagaCoordinator {
             if (logalot) {
                 console.log(`${lc} handling frame stage: ${stage}`);
             }
-            /**
-             * don't like this name, need to refactor
-             */
-            const srcGraph = toFlatGraph({ ibGibs: sagaContext.payloadIbGibsDomain }) ?? {};
             let nextFrameInfo;
             switch (stage) {
                 case SyncStage.init:
@@ -729,15 +732,19 @@ export class SyncSagaCoordinator {
                     nextFrameInfo = await this.handleDeltaFrame({
                         sagaContext,
                         sagaIbGib,
-                        srcGraph,
-                        metaspace,
-                        mySpace,
-                        myTempSpace,
+                        metaspace, mySpace, myTempSpace,
                         identity,
                     });
                     break;
                 case SyncStage.commit:
-                    nextFrameInfo = await this.handleCommitFrame({ sagaIbGib, metaspace, mySpace: mySpace, myTempSpace: myTempSpace, identity, });
+                    if (logalot) {
+                        console.log(`${lc}[${getSyncSagaFrameOrigin({ sagaFrame: sagaIbGib })}] mySpace.ib: ${mySpace.ib} (I: 5b270996d848907238d817fffa64a126)`);
+                    }
+                    nextFrameInfo = await this.handleCommitFrame({
+                        sagaIbGib,
+                        metaspace, mySpace, myTempSpace,
+                        identity,
+                    });
                     break;
                 default:
                     throw new Error(`${lc} (UNEXPECTED) Unknown sync stage: ${stage} (E: 9c2b4c8a6d34469f8263544710183355)`);
@@ -766,7 +773,7 @@ export class SyncSagaCoordinator {
      * **Execution Context**: **Receiver (Remote)**.
      *
      * The Receiver performs Gap Analysis here:
-     * 1.  Compares Sender's Knowledge Vector (in `sagaIbGib`) vs Receiver's Local KV.
+     * 1.  Compares Sender's Knowledge Map (in `sagaIbGib`) vs Receiver's Local Knowledge Map.
      * 2.  Identifies what Sender needs (`pushOfferAddrs`).
      * 3.  Identifies what Receiver needs (`deltaRequestAddrInfos`).
      * 4.  Returns an `Ack` frame containing these lists.
@@ -779,15 +786,17 @@ export class SyncSagaCoordinator {
             if (logalot) {
                 console.log(`${lc} starting... (I: 9d88dcad0408c029e898a4bcf3b08426)`);
             }
-            console.log(`${lc} [TEST DEBUG] Receiver mySpace: ${mySpace.ib}`);
+            if (logalot) {
+                console.log(`${lc} [TEST DEBUG] Receiver mySpace: ${mySpace.ib}`);
+            }
             // Extract Init Data
             const initData = messageData; // Using renamed variable for clarity
             if (initData.stage !== SyncStage.init) {
                 throw new Error(`${lc} Invalid init frame: initData.stage !== SyncStage.init (E: c91be82970e4decc58f56bf8fc1ffc26)`);
             }
             // if (logalot) { console.log(`${lc} initData: ${pretty(initData)} (I: 46b0f8441b96ad7a388f1ce3239dd826)`); }
-            if (!initData || !initData.knowledgeVector) {
-                throw new Error(`${lc} Invalid init frame: missing knowledgeVector (E: ed02c869e028d2d06841b9c7f80f2826)`);
+            if (!initData || !initData.knowledgeMap) {
+                throw new Error(`${lc} Invalid init frame: missing knowledgeMap (E: ed02c869e028d2d06841b9c7f80f2826)`);
             }
             // Determine Strategy from Saga Data (since V1 stores it in root)
             const conflictStrategy = sagaIbGib.data.conflictStrategy || SyncConflictStrategy.abort;
@@ -822,12 +831,14 @@ export class SyncSagaCoordinator {
             /**
              * "remote" is sender in this case
              */
-            const remoteKV = initData.knowledgeVector;
+            const remoteKnowledge = initData.knowledgeMap;
             if (logalot) {
-                console.log(`${lc} remoteKV: ${pretty(remoteKV)} (I: 9f957862356dfeae183c200854e86e26)`);
+                console.log(`${lc} remoteKnowledge: ${pretty(remoteKnowledge)} (I: 9f957862356dfeae183c200854e86e26)`);
+            }
+            const remoteTjps = Object.keys(remoteKnowledge);
+            if (logalot) {
+                console.log(`${lc} [TEST DEBUG] remoteTjps: ${JSON.stringify(remoteTjps)}`);
             }
-            const remoteTjps = Object.keys(remoteKV);
-            console.log(`${lc} [TEST DEBUG] remoteTjps: ${JSON.stringify(remoteTjps)}`);
             if (logalot) {
                 console.log(`${lc} remoteTjps: ${pretty(remoteTjps)} (I: 86ea4c53db0dc184c8b253386c402126)`);
             }
@@ -846,18 +857,22 @@ export class SyncSagaCoordinator {
                     throw new Error(`(UNEXPECTED) resGetLatestAddrs.data.latestAddrsMap falsy? (E: 16bc386dd51d0ff53a49620b1e641826)`);
                 }
                 localLatestAddrsMap = resGetLatestAddrs.data.latestAddrsMap;
-                console.log(`${lc} [TEST DEBUG] localKV: ${JSON.stringify(localLatestAddrsMap)}`);
                 if (logalot) {
-                    console.log(`${lc} localKV: ${pretty(localLatestAddrsMap)} (I: 980975642cbccd8018cf0cd808d30826)`);
+                    console.log(`${lc} [TEST DEBUG] localKnowledge: ${JSON.stringify(localLatestAddrsMap)}`);
+                }
+                if (logalot) {
+                    console.log(`${lc} localKnowledge: ${pretty(localLatestAddrsMap)} (I: 980975642cbccd8018cf0cd808d30826)`);
                 }
             }
             // 2. Gap Analysis
             for (const tjp of remoteTjps) {
-                const remoteAddr = remoteKV[tjp];
+                const remoteAddr = remoteKnowledge[tjp];
                 const localAddr = localLatestAddrsMap[tjp];
                 if (!localAddr) {
                     // We (Receiver) don't have this timeline at all. Request it.
-                    console.log(`${lc} [TEST DEBUG] Missing local timeline for TJP: ${tjp}. Requesting remoteAddr: ${remoteAddr}`);
+                    if (logalot) {
+                        console.log(`${lc} [TEST DEBUG] Missing local timeline for TJP: ${tjp}. Requesting remoteAddr: ${remoteAddr}`);
+                    }
                     deltaRequestAddrInfos.push({
                         addr: remoteAddr,
                         tjpAddr: tjp,
@@ -869,10 +884,14 @@ export class SyncSagaCoordinator {
                 // we do have this timeline...
                 if (localAddr === remoteAddr) {
                     // ...already synced
-                    console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Synced (localAddr === remoteAddr)`);
+                    if (logalot) {
+                        console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Synced (localAddr === remoteAddr)`);
+                    }
                     continue;
                 }
-                console.log(`${lc} [TEST DEBUG] TJP ${tjp}: localAddr=${localAddr}, remoteAddr=${remoteAddr} - checking for divergence...`);
+                if (logalot) {
+                    console.log(`${lc} [TEST DEBUG] TJP ${tjp}: localAddr=${localAddr}, remoteAddr=${remoteAddr} - checking for divergence...`);
+                }
                 // we have this timeline but it's not synced...
                 // We're executing on receiver. Check if Remote (Sender) is in
                 // our past, and if so, we are ahead and need to push the delta
@@ -885,7 +904,9 @@ export class SyncSagaCoordinator {
                 if (remoteIsInPast) {
                     // we're ahead, so push the delta of what the sender doesn't
                     // have (we have full knowledge)
-                    console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Remote (sender) is in past - offering push`);
+                    if (logalot) {
+                        console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Remote (sender) is in past - offering push`);
+                    }
                     const deltaGraph = await getDeltaDependencyGraph({
                         ibGibAddr: localAddr,
                         live: false, // always live: false right?
@@ -906,7 +927,6 @@ export class SyncSagaCoordinator {
                      */
                     let localIsInPast = false;
                     try {
-                        // we could
                         localIsInPast = await isPastFrame({
                             olderAddr: localAddr,
                             newerAddr: remoteAddr,
@@ -921,7 +941,9 @@ export class SyncSagaCoordinator {
                     }
                     if (localIsInPast) {
                         // Fast-Forward: We update to remote's tip.
-                        console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Local is in past - requesting delta`);
+                        if (logalot) {
+                            console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Local is in past - requesting delta`);
+                        }
                         deltaRequestAddrInfos.push({
                             addr: remoteAddr,
                             tjpAddr: tjp,
@@ -930,7 +952,9 @@ export class SyncSagaCoordinator {
                     }
                     else {
                         // DIVERGENCE: Both have changes the other doesn't know about.
-                        console.log(`${lc} [TEST DEBUG] TJP ${tjp}: DIVERGENCE DETECTED! conflictStrategy=${conflictStrategy}`);
+                        if (logalot) {
+                            console.log(`${lc} [TEST DEBUG] TJP ${tjp}: DIVERGENCE DETECTED! conflictStrategy=${conflictStrategy}`);
+                        }
                         if (conflictStrategy === 'abort') {
                             // Abort Strategy: We will treat this as terminal.
                             // But for Unified Ack, we just mark it terminal in the list?
@@ -944,26 +968,23 @@ export class SyncSagaCoordinator {
                                 reason: 'divergence',
                                 terminal: true
                             });
+                            // todo: create error saga frame for when aborting or other terminal error
                         }
                         else if (conflictStrategy === 'optimistic') {
                             // Optimistic: We want resolve this.
                             // We need to send our history to the Sender so they can Merge.
                             // Fetch Full History for Local Timeline
-                            // Note: We might optimize this to only send "recent" history if we had a KV?
-                            // But for now, get full past.
-                            // Optimization: localKV might not have full history.
-                            // We need to inspect the 'past' of the local tip.
-                            // We need the ACTUAL object to get the past.
-                            // We have localAddr.
                             const resLocalTip = await getFromSpace({ space: mySpace, addr: localAddr });
                             if (!resLocalTip.success || resLocalTip.ibGibs?.length !== 1) {
-                                throw new Error(`couldn't get local tip (${localAddr}) from space (${mySpace.ib}) (E: 83cb88a767e22bbda99c6788bec50526)`);
+                                throw new Error(`couldn't get local tip (${localAddr}) from space (${mySpace.ib}). errorMsg: ${resLocalTip.errorMsg ?? '[unknown error (E: b3c3d823276300aa384ebdba4a8eb826)]'} (E: 83cb88a767e22bbda99c6788bec50526)`);
                             }
                             const localTip = resLocalTip.ibGibs[0];
-                            if (!localTip) {
-                                throw new Error(`${lc} Failed to load local tip for conflict resolution. (E: c39448ad6b3a72af78339ad877a56826)`);
-                            }
-                            const timelineAddrs = [...(localTip.rel8ns?.past ?? []), localAddr];
+                            const pastAddrs = await getHistoryAddrs({
+                                timeline: localTip,
+                                space: mySpace,
+                                metaspace,
+                            });
+                            const timelineAddrs = [...pastAddrs, localAddr];
                             conflicts.push({
                                 tjpAddr: tjp,
                                 localAddr,
@@ -1134,15 +1155,21 @@ export class SyncSagaCoordinator {
             // #region sanity/validation
             // 1. Check for Conflicts
             const conflicts = ackData.conflicts || [];
-            console.log(`${lc} [CONFLICT DEBUG] Received conflicts from Ack: ${conflicts.length}`);
-            if (conflicts.length > 0) {
+            if (logalot) {
+                console.log(`${lc} [CONFLICT DEBUG] Received conflicts from Ack: ${conflicts.length}`);
+            }
+            if (logalot && conflicts.length > 0) {
                 console.log(`${lc} [CONFLICT DEBUG] Conflicts detail: ${JSON.stringify(conflicts, null, 2)}`);
             }
             const terminalConflicts = conflicts.filter(c => c.terminal);
             if (terminalConflicts.length > 0) {
-                console.warn(`${lc} Received terminal conflicts from Ack: ${JSON.stringify(terminalConflicts)}`);
-                // Terminal failure. Sender should probably Commit(Fail) or just Abort.
-                // For now, throw to trigger abort.
+                if (logalot) {
+                    console.warn(`${lc} Received terminal conflicts from Ack: ${JSON.stringify(terminalConflicts)}`);
+                }
+                // Terminal failure. Sender should probably Commit(Fail) or just
+                // Abort. For now, throw to trigger abort. the incoming ack
+                // frame has already been persisted in local durable space by
+                // now.
                 throw new Error(`${lc} Peer reported terminal conflicts. (E: 23a0096ee05a2ccfa89334e8f156b426)`);
             }
             // at this point, if we have conflicts, they are non-terminal
@@ -1153,7 +1180,9 @@ export class SyncSagaCoordinator {
              */
             const outgoingDeltaAddrRequestInfos = []; // Additional requests for merging
             if (conflicts.length > 0) {
-                console.log(`${lc} [CONFLICT DEBUG] Processing ${conflicts.length} non-terminal conflicts`);
+                if (logalot) {
+                    console.log(`${lc} [CONFLICT DEBUG] Processing ${conflicts.length} non-terminal conflicts`);
+                }
                 // We need to resolve these.
                 // Strategy:
                 // 1. Analyze Divergence (Sender vs Receiver)
@@ -1261,10 +1290,14 @@ export class SyncSagaCoordinator {
                     //     console.log(`${lc} [CONFLICT DEBUG] No receiver-only frames found for this conflict`);
                     // }
                 }
-                console.log(`${lc} [CONFLICT DEBUG] Finished processing ${conflicts.length} conflicts. outgoingDeltaAddrRequestInfos: ${outgoingDeltaAddrRequestInfos.length}`);
+                if (logalot) {
+                    console.log(`${lc} [CONFLICT DEBUG] Finished processing ${conflicts.length} conflicts. outgoingDeltaAddrRequestInfos: ${outgoingDeltaAddrRequestInfos.length}`);
+                }
             }
             else {
-                console.log(`${lc} [CONFLICT DEBUG] No optimistic conflicts to process`);
+                if (logalot) {
+                    console.log(`${lc} [CONFLICT DEBUG] No optimistic conflicts to process`);
+                }
             }
             // 2. Prepare Delta Payload (What Receiver Requesting + Our Conflict Logic)
             /**
@@ -1345,7 +1378,7 @@ export class SyncSagaCoordinator {
      * 2.  **Fulfillment**: Checks `requests`. If Peer requested data, gathers it and prepares `outgoingPayload`.
      * 3.  **Completion**: If no more requests, transitions to `Commit`.
      */
-    async handleDeltaFrame({ sagaContext, sagaIbGib, srcGraph, mySpace, myTempSpace, metaspace, identity, }) {
+    async handleDeltaFrame({ sagaContext, sagaIbGib, mySpace, myTempSpace, metaspace, identity, }) {
         const lc = `${this.lc}[${this.handleDeltaFrame.name}]`;
         try {
             if (logalot) {
@@ -1364,32 +1397,44 @@ export class SyncSagaCoordinator {
                 console.log(`${lc} deltaData: ${pretty(deltaData)} (I: a76008681df458cfbcdc4848f825a826)`);
             }
             // #endregion validate/sanity
-            console.log(`${lc} [CONFLICT DEBUG] deltaData.payloadAddrs count: ${deltaData.payloadAddrs?.length || 0}`);
+            if (logalot) {
+                console.log(`${lc} [CONFLICT DEBUG] deltaData.payloadAddrs count: ${deltaData.payloadAddrs?.length || 0}`);
+            }
             const peerProposesCommit = deltaData.proposeCommit || false;
             /**
              * these are already in the local temp space
              */
             const receivedPayloadIbGibs = sagaContext.payloadIbGibsDomain ?? [];
             // 2. Fulfill Peer Requests (Outgoing Payload with Delta Dependencies)
-            console.log(`${lc} [CONFLICT DEBUG] Fulfilling ${(deltaData.deltaRequestAddrInfos || []).length} peer requests`);
+            if (logalot) {
+                console.log(`${lc} [CONFLICT DEBUG] Fulfilling ${(deltaData.deltaRequestAddrInfos || []).length} peer requests`);
+            }
             const outgoingPayload = await this.getPayloadsForRequestedInfos({
                 deltaRequestAddrInfos: deltaData.deltaRequestAddrInfos || [],
                 mySpace,
             });
-            console.log(`${lc} [CONFLICT DEBUG] Outgoing payload size (with deps): ${outgoingPayload.length}`);
+            if (logalot) {
+                console.log(`${lc} [CONFLICT DEBUG] Outgoing payload size (with deps): ${outgoingPayload.length}`);
+            }
             // 3. Execute Merges (If applicable)
             // Check if we have pending conflicts that we CAN resolve now that we have data.
             // We look at the Saga History (Ack Frame) to find conflicts.
             // Optimization: Do this only if we received payloads.
             const mergeResultIbGibs = [];
-            console.log(`${lc} [CONFLICT DEBUG] Checking for merge. receivedPayloadIbGibs.length: ${receivedPayloadIbGibs.length}`);
+            if (logalot) {
+                console.log(`${lc} [CONFLICT DEBUG] Checking for merge. receivedPayloadIbGibs.length: ${receivedPayloadIbGibs.length}`);
+            }
             if (receivedPayloadIbGibs.length > 0) {
-                console.log(`${lc} [TEST DEBUG] Received Payloads (${receivedPayloadIbGibs.length}). Checking for conflicts/merges...`);
+                if (logalot) {
+                    console.log(`${lc} [TEST DEBUG] Received Payloads (${receivedPayloadIbGibs.length}). Checking for conflicts/merges...`);
+                }
                 // Find the Ack frame in history to get conflicts
                 // Optimization: Batch fetch history from `sagaIbGib.rel8ns.past`
                 // V1 timelines carry full history in `past`.
                 const pastAddrs = sagaIbGib.rel8ns?.past || [];
-                console.log(`${lc} [TEST DEBUG] pastAddrs count: ${pastAddrs.length}`);
+                if (logalot) {
+                    console.log(`${lc} [TEST DEBUG] pastAddrs count: ${pastAddrs.length}`);
+                }
                 const sagaHistory = await getFullSyncSagaHistory({
                     sagaIbGib,
                     space: mySpace,
@@ -1428,9 +1473,13 @@ export class SyncSagaCoordinator {
                         // We blindly attempt merge if we have both tips accessible?
                         // We need `receiverTip` (localAddr in Ack) and `senderTip` (remoteAddr).
                         // Check if we have receiverTip in space
-                        console.log(`${lc} [CONFLICT DEBUG] Attempting merge for conflict. ReceiverTip: ${receiverTip}, SenderTip: ${senderTip}`);
+                        if (logalot) {
+                            console.log(`${lc} [CONFLICT DEBUG] Attempting merge for conflict. ReceiverTip: ${receiverTip}, SenderTip: ${senderTip}`);
+                        }
                         const resRecTip = await getFromSpace({ addr: receiverTip, space: myTempSpace }); // Check myTempSpace for incoming data
-                        console.log(`${lc} [CONFLICT DEBUG] ReceiverTip found in myTempSpace: ${!!resRecTip.ibGibs?.[0]}`);
+                        if (logalot) {
+                            console.log(`${lc} [CONFLICT DEBUG] ReceiverTip found in myTempSpace: ${!!resRecTip.ibGibs?.[0]}`);
+                        }
                         if (resRecTip.success && resRecTip.ibGibs?.[0]) {
                             // We have the tip!
                             // Do we have the full history?
@@ -1445,7 +1494,9 @@ export class SyncSagaCoordinator {
                                     metaspace,
                                 });
                                 if (mergeResult) {
-                                    console.log(`${lc} [TEST DEBUG] Merge success! New Tip: ${getIbGibAddr({ ibGib: mergeResult })}`);
+                                    if (logalot) {
+                                        console.log(`${lc} [TEST DEBUG] Merge success! New Tip: ${getIbGibAddr({ ibGib: mergeResult })}`);
+                                    }
                                     if (logalot) {
                                         console.log(`${lc} Merge success! New Tip: ${getIbGibAddr({ ibGib: mergeResult })}`);
                                     }
@@ -1454,7 +1505,7 @@ export class SyncSagaCoordinator {
                                 }
                             }
                             catch (e) {
-                                console.error(`${lc} Merge failed: ${e}`);
+                                console.error(`${lc} (NOT THROWN) Merge failed: ${e} (E: 491b464fc6f4857f52ff3df213105826)`);
                                 // If merge fails, we might Abort or just continue?
                             }
                         }
@@ -1602,15 +1653,47 @@ export class SyncSagaCoordinator {
     /**
      * should throw if fails
      */
-    async executeLocalCommit({ deltaFrame, sagaHistory, metaspace, localSpace, localTempSpace, identity, }) {
+    async executeLocalCommit({ deltaFrame, commitFrame, sagaHistory, metaspace, localSpace, localTempSpace, identity, }) {
         const lc = `${this.lc}[${this.executeLocalCommit.name}]`;
         try {
             if (logalot) {
                 console.log(`${lc} starting... (I: 6734980446b86a63c1af6e2e206de826)`);
             }
+            if (!deltaFrame && !commitFrame) {
+                throw new Error(`(UNEXPECTED) !deltaFrame && !commitFrame? we're expecting to execute the commit based off of EITHER a delta OR a commit frame. (E: 10cae319a2685a672866f5583514e326)`);
+            }
+            else if (deltaFrame && commitFrame) {
+                throw new Error(`(UNEXPECTED) deltaFrame && commitFrame? we're expecting to execute the commit based off of EITHER a delta OR a commit frame. (E: b9037b1ed6d8684ac8a5d01328bad826)`);
+            }
+            /**
+             * Sync has a two-stage commit. The first is from a delta frame with
+             * `proposeCommit: true`. That produces a commit frame, which on the
+             * other end triggers the second leg.
+             */
+            const isFirstCommitLeg = !!deltaFrame;
+            const currentFrame = isFirstCommitLeg ? deltaFrame : commitFrame;
+            if (!currentFrame) {
+                throw new Error(`(UNEXPECTED) !currentFrame? something wrong with my logic. (E: 4ec0ce6625cc1d677bc902c839ca1a26)`);
+            }
+            /**
+             * we only want to register new ibgibs from the other end, so we
+             * will compare the history payloads/push offers with the context
+             * that provided those payloads.
+             *
+             * So we will filter out the history that we produced, which should
+             * leave us only with externally created payload addrs.
+             *
+             *  NOTE: I have this at the beginning of the function PURELY to get
+             *  a log value in to understand the context of this function's
+             *  output.
+             */
+            const currentFrameOrigin = getSyncSagaFrameOrigin({ sagaFrame: currentFrame });
+            if (logalot) {
+                console.log(`${lc} currentFrameOrigin: ${currentFrameOrigin} (I: 3add8f8390c89743ae554bd3cc60b826)`);
+            }
             // #region validate/sanity
-            if (!deltaFrame.data) {
-                throw new Error(`(UNEXPECTED) deltaFrame.data falsy? (E: a8be68d48668d93d992d793834823826)`);
+            if (!currentFrame.data) {
+                throw new Error(`(UNEXPECTED) currentFrame.data falsy? (E: a8be68d48668d93d992d793834823826)`);
             }
             // #endregion validate/sanity
             // * move all payload addrs from temp space to local space
@@ -1622,10 +1705,16 @@ export class SyncSagaCoordinator {
                     allPayloadAddrsDomainTransferred.push(addr);
                 }
             };
-            sagaHistory.forEach(x => {
+            sagaHistory.filter(x => {
+                const frameExecutionContext = getSyncSagaFrameOrigin({ sagaFrame: x.sagaIbGib });
+                return currentFrameOrigin === frameExecutionContext;
+            }).forEach(x => {
                 if (!x.sagaIbGib.data) {
                     throw new Error(`(UNEXPECTED) sagaIbGib.data falsy? (E: 34d7f8cdee14717ce828878d98f89826)`);
                 }
+                if (logalot) {
+                    console.log(`${lc}[${currentFrameOrigin}] history slice: ${pretty(x)} (I: e5a9436fb66b0df3183bd6d81be2ca26)`);
+                }
                 x.msgStones.forEach(msgStone => {
                     if (!msgStone.data) {
                         throw new Error(`(UNEXPECTED) msgStone.data falsy? (E: 21406101f91847514cc759c8a7382f26)`);
@@ -1646,58 +1735,101 @@ export class SyncSagaCoordinator {
                     }
                 });
             });
+            if (logalot) {
+                console.log(`${lc}[${currentFrameOrigin}] allPayloadAddrsDomainTransferred: ${allPayloadAddrsDomainTransferred.length > 0 ? allPayloadAddrsDomainTransferred.join(', ') : 'none'} (I: a1950eb3ca95bdc9ec18a4b8823e9826)`);
+            }
             // at this point, we have a list of ALL payload addrs retrieved.
             let allPayloadIbGibsDomainTransferred = [];
-            const resGetAllTransferred = await getFromSpace({ addrs: allPayloadAddrsDomainTransferred, space: localTempSpace });
-            if (resGetAllTransferred.success && resGetAllTransferred.ibGibs && resGetAllTransferred.ibGibs.length === allPayloadAddrsDomainTransferred.length) {
-                allPayloadIbGibsDomainTransferred = resGetAllTransferred.ibGibs.concat();
-            }
-            else {
-                // errored out, gather info
-                if (!resGetAllTransferred.rawResultIbGib) {
-                    throw new Error(`(UNEXPECTED) !resGetAllTransferred.rawResultIbGib falsy? (E: dc6cf8729668f4fbe8c024f887d97a26)`);
+            if (allPayloadAddrsDomainTransferred.length > 0) {
+                const resGetAllTransferred = await getFromSpace({ addrs: allPayloadAddrsDomainTransferred, space: localTempSpace });
+                if (resGetAllTransferred.success && resGetAllTransferred.ibGibs && resGetAllTransferred.ibGibs.length === allPayloadAddrsDomainTransferred.length) {
+                    allPayloadIbGibsDomainTransferred = resGetAllTransferred.ibGibs.concat();
+                }
+                else {
+                    // errored out, gather info
+                    if (!resGetAllTransferred.rawResultIbGib) {
+                        throw new Error(`(UNEXPECTED) !resGetAllTransferred.rawResultIbGib falsy? (E: dc6cf8729668f4fbe8c024f887d97a26)`);
+                    }
+                    const { addrsNotFound, addrsErrored, errors } = resGetAllTransferred.rawResultIbGib.data;
+                    throw new Error(`(UNEXPECTED) we couldn't get all addrs transferred throughout the saga from the tempspace (${localTempSpace.ib})? addrsNotFound: ${addrsNotFound ?? []}. addrsErrored: ${addrsErrored ?? []}. errors: ${errors ?? []}(E: 222e341e634862b4d88ae7282584d826)`);
                 }
-                const { addrsNotFound, addrsErrored, errors } = resGetAllTransferred.rawResultIbGib.data;
-                throw new Error(`(UNEXPECTED) we couldn't get all addrs transferred throughout the saga from the tempspace (${localTempSpace.ib})? addrsNotFound: ${addrsNotFound ?? []}. addrsErrored: ${addrsErrored ?? []}. errors: ${errors ?? []}(E: 222e341e634862b4d88ae7282584d826)`);
             }
             // now we have all ibgibs transferred, first put them all the local space
-            const { payload_Dnas, payload_NonDnas } = await putInSpace_dnasThenNonDnas({
-                ibGibs: allPayloadIbGibsDomainTransferred,
-                space: localSpace
-            });
-            const { mapWithTjp_NoDna, mapWithTjp_YesDna, mapWithoutTjps } = splitPerTjpAndOrDna({ ibGibs: payload_NonDnas, filterPrimitives: true });
-            // first register all non-tjp stones
-            const nontjps = Object.values(mapWithoutTjps);
-            for (const nontjp of nontjps) {
-                await metaspace.registerNewIbGib({
-                    ibGib: nontjp,
-                    space: localSpace,
-                });
-            }
-            // next register each timeline in order...
-            // ...first the ones without dna...
-            const timelinesByTjpAddr_NoDna = getTimelinesGroupedByTjp({ ibGibs: Object.values(mapWithTjp_NoDna) });
-            const tjpAddrs_NoDna = Object.keys(timelinesByTjpAddr_NoDna);
-            for (const tjpAddr_NoDna of tjpAddrs_NoDna) {
-                const timelineIbGibs = timelinesByTjpAddr_NoDna[tjpAddr_NoDna];
-                for (const ibGib of timelineIbGibs) {
-                    await metaspace.registerNewIbGib({
-                        ibGib,
-                        space: localSpace,
-                    });
+            if (allPayloadIbGibsDomainTransferred.length === 0) {
+                // nothing was synced
+                if (logalot) {
+                    console.log(`${lc}[${currentFrameOrigin}] no changes on this end (I: fa30d18e83a87ee9e8487fbb5d632b26)`);
                 }
             }
-            // ...then the ones WITH dna.
-            const timelinesByTjpAddr_YesDna = getTimelinesGroupedByTjp({ ibGibs: Object.values(mapWithTjp_YesDna) });
-            const tjpAddrs_YesDna = Object.keys(timelinesByTjpAddr_YesDna);
-            for (const tjpAddr_YesDna of tjpAddrs_YesDna) {
-                const timelineIbGibs = timelinesByTjpAddr_YesDna[tjpAddr_YesDna];
-                for (const ibGib of timelineIbGibs) {
+            else {
+                if (logalot) {
+                    console.log(`${lc}[${currentFrameOrigin}] ${allPayloadIbGibsDomainTransferred.length} changes detected (I: fa30d18e83a87ee9e8487fbb5d632b26)`);
+                }
+                if (logalot) {
+                    console.log(`${lc} put all into localSpace (${localSpace.ib}) starting... (I: d5e0d9870e380b61e80c729660058826)`);
+                }
+                const { payload_Dnas, payload_NonDnas } = await putInSpace_dnasThenNonDnas({
+                    ibGibs: allPayloadIbGibsDomainTransferred,
+                    space: localSpace
+                });
+                if (logalot) {
+                    console.log(`${lc} put all into localSpace (${localSpace.ib}) complete. (I: d5e0d9870e380b61e80c729660058826)`);
+                }
+                const { mapWithTjp_NoDna, mapWithTjp_YesDna, mapWithoutTjps } = splitPerTjpAndOrDna({ ibGibs: payload_NonDnas, filterPrimitives: true });
+                // first register all non-tjp stones
+                if (logalot) {
+                    console.log(`${lc} register mapWithoutTjps starting... (I: 2b84d8f8dda85adde88696d8419bf726)`);
+                }
+                const nontjps = Object.values(mapWithoutTjps);
+                for (const nontjp of nontjps) {
+                    if (logalot) {
+                        console.log(`${lc} registering ${getIbGibAddr({ ibGib: nontjp })} (I: 4647b4f42d27cffe0fbfce8846755826)`);
+                    }
                     await metaspace.registerNewIbGib({
-                        ibGib,
+                        ibGib: nontjp,
                         space: localSpace,
                     });
                 }
+                if (logalot) {
+                    console.log(`${lc} mapWithoutTjps complete. (I: 2b84d8f8dda85adde88696d8419bf726)`);
+                }
+                // next register each timeline in order...
+                // ...first the ones without dna...
+                if (logalot) {
+                    console.log(`${lc} register mapWithTjp_NoDna starting... (I: 96e648e4db382499b8bfaa1b37c24826)`);
+                }
+                const timelinesByTjpAddr_NoDna = getTimelinesGroupedByTjp({ ibGibs: Object.values(mapWithTjp_NoDna) });
+                const tjpAddrs_NoDna = Object.keys(timelinesByTjpAddr_NoDna);
+                for (const tjpAddr_NoDna of tjpAddrs_NoDna) {
+                    const timelineIbGibs = timelinesByTjpAddr_NoDna[tjpAddr_NoDna];
+                    for (const ibGib of timelineIbGibs) {
+                        await metaspace.registerNewIbGib({
+                            ibGib,
+                            space: localSpace,
+                        });
+                    }
+                }
+                if (logalot) {
+                    console.log(`${lc} register mapWithTjp_NoDna complete. (I: 96e648e4db382499b8bfaa1b37c24826)`);
+                }
+                // ...then the ones WITH dna.
+                if (logalot) {
+                    console.log(`${lc} register mapWithTjp_YesDna starting... (I: d54a820e9442dee4681f6228a6795926)`);
+                }
+                const timelinesByTjpAddr_YesDna = getTimelinesGroupedByTjp({ ibGibs: Object.values(mapWithTjp_YesDna) });
+                const tjpAddrs_YesDna = Object.keys(timelinesByTjpAddr_YesDna);
+                for (const tjpAddr_YesDna of tjpAddrs_YesDna) {
+                    const timelineIbGibs = timelinesByTjpAddr_YesDna[tjpAddr_YesDna];
+                    for (const ibGib of timelineIbGibs) {
+                        await metaspace.registerNewIbGib({
+                            ibGib,
+                            space: localSpace,
+                        });
+                    }
+                }
+                if (logalot) {
+                    console.log(`${lc} register mapWithTjp_YesDna complete. (I: d54a820e9442dee4681f6228a6795926)`);
+                }
             }
         }
         catch (error) {
@@ -1760,46 +1892,55 @@ export class SyncSagaCoordinator {
             if (logalot) {
                 console.log(`${lc} starting... (I: e179573bdd881202f8ba3168da1c3826)`);
             }
-            let resNextSagaFrameInfo;
-            // Sender Logic (Finalizing):
-            // If we are here, we received a Commit frame from the Peer.
-            // This implies the Peer has successfully committed.
-            // We should now:
-            // 1. Validate (implicitly done by receiving valid frame)
-            // 2. Perform our own cleanup (Temp -> Dest, if applicable)
-            // 3. Return saga completion.
-            // one last validate entire history?
-            const history = await getFullSyncSagaHistory({
-                sagaIbGib,
-                space: mySpace,
-            });
-            const validationErrors = await validateFullSyncSagaHistory({
-                history,
-            });
-            if (validationErrors.length > 0) {
-                const errorCommitFrame = await this.createCommitFrame({
+            if (!sagaIbGib.data) {
+                throw new Error(`(UNEXPECTED) sagaIbGib.data falsy? (E: cbc31dbb7d28b5b8c8cddb510d7d2826)`);
+            }
+            if (sagaIbGib.data.errors && sagaIbGib.data.errors.length > 0) {
+                // our saga errored out but we already committed the darn
+                // changes previously
+                throw new Error(`not implemented...saga errored out on other end but we've already committed our changes. we need to implement undoing our changes, i.e., rollback commit, which basically is deleting all the payloads that we already put in in our previous commit. (E: e8eb789e0c08f0b3cf93607cb73e9f26)`);
+            }
+            else {
+                // Sender Logic (Finalizing):
+                // If we are here, we received a Commit frame from the Peer.
+                // This implies the Peer has successfully committed.
+                // We should now:
+                // 1. Validate (implicitly done by receiving valid frame)
+                // 2. Perform our own cleanup (Temp -> Dest, if applicable)
+                // 3. Return saga completion.
+                // one last validate entire history ?
+                const history = await getFullSyncSagaHistory({
                     sagaIbGib,
+                    space: mySpace,
+                });
+                const validationErrors = await validateFullSyncSagaHistory({
+                    history,
+                });
+                if (validationErrors.length > 0) {
+                    const errorCommitFrame = await this.createCommitFrame({
+                        sagaIbGib,
+                        metaspace,
+                        mySpace,
+                        identity,
+                        errors: validationErrors,
+                    });
+                    return { frame: errorCommitFrame, }; /* <<<< returns early */
+                }
+                await this.executeLocalCommit({
+                    commitFrame: sagaIbGib,
+                    sagaHistory: history,
+                    localSpace: mySpace,
+                    localTempSpace: myTempSpace,
                     metaspace,
-                    mySpace,
-                    identity,
-                    errors: validationErrors,
                 });
-                return { frame: errorCommitFrame, }; /* <<<< returns early */
-            }
-            await this.executeLocalCommit({
-                deltaFrame: sagaIbGib,
-                sagaHistory: history,
-                localSpace: mySpace,
-                localTempSpace: myTempSpace,
-                metaspace,
-            });
-            // todo: implement explicit cleanup logic here and in peer
-            console.error(`${lc} NAG ERROR (NOT THROWN): implement cleanup logic, including add a cleanup method to the peer (E: 3a9a24befb98a981a88fbdbf52920e26)`);
-            if (logalot) {
-                console.log(`${lc} Peer committed. Finalizing saga locally. Saga Complete.`);
+                // todo: implement explicit cleanup logic here and in peer
+                console.error(`${lc} NAG ERROR (NOT THROWN): implement cleanup logic, including add a cleanup method to the peer (E: 3a9a24befb98a981a88fbdbf52920e26)`);
+                if (logalot) {
+                    console.log(`${lc} Peer committed. Finalizing saga locally. Saga Complete.`);
+                }
+                // the holy grail!
+                return { sagaComplete: true };
             }
-            // the holy grail!
-            return { sagaComplete: true };
         }
         catch (error) {
             const emsg = `${lc} ${extractErrorMsg(error)}`;