@ibgib/core-gib 0.1.25 → 0.1.27

package/src/sync/sync-saga-coordinator.mts

@@ -19,21 +19,25 @@ import { putInSpace, getLatestAddrs, getFromSpace } from "../witness/space/space
 import { KeystoneIbGib_V1 } from "../keystone/keystone-types.mjs";
 import { KeystoneService_V1 } from "../keystone/keystone-service-v1.mjs";
 import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
-import { SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from "./sync-constants.mjs";
-import { appendToTimeline, createTimeline, getHistory, Rel8nInfo, Rel8nRemovalInfo } from "../timeline/timeline-api.mjs";
+import {
+    SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN,
+} from "./sync-constants.mjs";
+import {
+    appendToTimeline, createTimeline, Rel8nInfo, Rel8nRemovalInfo
+} from "../timeline/timeline-api.mjs";
 import {
     SyncData_V1, SyncIbGib_V1, SyncConflictStrategy, SyncMode, SyncOptions,
     SyncRel8ns_V1, DomainIbGibAnalysisInfo, NextSagaFrameInfo,
-    SYNC_CONFLICT_STRATEGY_VALID_VALUES,
-    HandleSagaResponseContextResult,
+    SYNC_CONFLICT_STRATEGY_VALID_VALUES, HandleSagaResponseContextResult,
+    SyncExecutionContext,
+    SYNC_EXECUTION_CONTEXT_VALID_VALUES,
 } from "./sync-types.mjs";
-import { getSyncIb, getTempSpaceName, isPastFrame } from "./sync-helpers.mjs";
+import { getExecutionContext, getSyncIb, getTempSpaceName, isPastFrame } from "./sync-helpers.mjs";
 import { getDeltaDependencyGraph, getDependencyGraph, toFlatGraph } from "../common/other/graph-helper.mjs";
 import {
     SyncSagaMessageData_V1, SyncSagaMessageInitData_V1,
     SyncSagaMessageAckData_V1, SyncSagaMessageDeltaData_V1,
-    SyncSagaMessageCommitData_V1, SyncSagaConflictInfo,
-    SyncSagaPushOfferInfo,
+    SyncSagaMessageCommitData_V1, SyncSagaConflictInfo, SyncSagaPushOfferInfo,
     SyncSagaRequestAddrInfo,
 } from "./sync-saga-message/sync-saga-message-types.mjs";
 import { getSyncSagaMessageIb } from "./sync-saga-message/sync-saga-message-helpers.mjs";
@@ -49,14 +53,12 @@ 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";
 import { ErrorIbGib_V1 } from "../common/error/error-types.mjs";
-import {
-    IbGibSpaceResultData, IbGibSpaceResultIbGib, IbGibSpaceResultRel8ns
-} from "../witness/space/space-types.mjs";
+import { IbGibSpaceResultData, IbGibSpaceResultIbGib, IbGibSpaceResultRel8ns } from "../witness/space/space-types.mjs";
 import { FlatIbGibGraph } from "../common/other/graph-types.mjs";
 
 
 // const logalot = GLOBAL_LOG_A_LOT || true;
-const logalot = false;
+const logalot = true;
 const logalotControlDomain = true;
 const lcControlDomain = '[ControlDomain]';
 
@@ -95,7 +97,7 @@ export class SyncSagaCoordinator {
      * @param opts.domainIbGibs - The root ibgibs defining the scope of the sync.
      * @param opts.useSessionIdentity - (Optional) Whether to create an ephemeral session identity. Default: true.
      */
-    async sync({
+    public async sync({
         peer,
         domainIbGibs,
         conflictStrategy = SyncConflictStrategy.abort,
@@ -191,6 +193,91 @@ export class SyncSagaCoordinator {
         };
     }
 
+    /**
+     * This is what the receiving side of the sync calls to drive the FSM to the
+     * next stage.
+     *
+     * So whereas the sender executes a saga loop and drives the entire process,
+     * this is a reactive one-off that drives just the single step that the
+     * receiver does in that saga.
+     *
+     * @returns next context result if another round, else if commit returns
+     * null
+     */
+    public async continueSync({
+        sagaContext,
+        mySpace,
+        myTempSpace,
+        identity,
+        identitySecret,
+        metaspace,
+    }: {
+        sagaContext: SyncSagaContextIbGib_V1,
+        /**
+         * Local space relative to the execution context's POV
+         */
+        mySpace: IbGibSpaceAny,
+        /**
+         * Local temp space relative to the execution context's POV
+         */
+        myTempSpace: IbGibSpaceAny,
+        identity?: KeystoneIbGib_V1,
+        identitySecret?: string,
+        metaspace: MetaspaceService,
+    }): Promise<SyncSagaContextIbGib_V1 | null> {
+        const lc = `${this.lc}[${this.continueSync.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: f64e08bf77d1425378601f380384ec26)`); }
+
+            const contextResult = await this.handleResponseSagaContext({
+                sagaContext,
+                mySpace,
+                myTempSpace,
+                identity,
+                identitySecret,
+                metaspace,
+            });
+
+            if (!contextResult) {
+                if (logalot) { console.log(`${lc} Handler returned null (Saga End). (I: 43da8bb6c846b1fe7766332643be0e26)`); }
+                return null;
+            }
+
+            // #region error conditions throw
+            if (contextResult.errorMsg) {
+                throw new Error(`Couldn't handle response saga context. errorMsg: ${contextResult.errorMsg} (E: 7b41a183cf3cb58a5859c803800cf826)`);
+            } else if (!contextResult.nextFrameInfo) {
+                throw new Error(`(UNEXPECTED) contextResult.nextFrameInfo falsy? (E: 5740542f5eb8ccb41dfec188d87c1e26)`);
+            } else if (contextResult.nextFrameInfo?.responseWasNull) {
+                throw new Error(`(UNEXPECTED) contextResult.nextFrameInfo.responseWasNull? logic flow should not have gotten here. (E: ae06748d8c0c5e70c92322c8fb0cb426)`);
+            }
+            // #endregion error conditions throw
+
+            // create the return context
+            const { frame, payloadIbGibsDomain } = contextResult.nextFrameInfo;
+
+            const responseCtx = await createSyncSagaContext({
+                sagaFrame: frame,
+                localSpace: mySpace,
+                payloadIbGibsDomain,
+                // todo: we need to thoroughly go through the identity per each step after getting basic merging
+                sessionKeystones: identity ? [identity] : undefined, // ??
+            });
+
+            const immediateValidationErrors = await validateContextAndSagaFrame({
+                context: responseCtx,
+            });
+            if (immediateValidationErrors.length > 0) { throw new Error(`(UNEXPECTED) just created sync saga context () and there were immediateValidationErrors? immediateValidationErrors: ${immediateValidationErrors} (E: c120e8e0aa98673d685267a8a36e5826)`); }
+
+            return responseCtx;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
     protected async getSessionIdentity({
         sagaId,
         metaspace,
@@ -253,6 +340,12 @@ export class SyncSagaCoordinator {
         metaspace
     }: {
         initFrame: SyncIbGib_V1,
+        /**
+         * This is the initial dependency graph of all domain ibgibs passed in
+         * to the original {@link sync} call.
+         *
+         * if we're executing on the sender, this will be populated
+         */
         initDomainGraph: FlatIbGibGraph,
         peer: SyncPeerWitness,
         sessionIdentity?: KeystoneIbGib_V1,
@@ -362,8 +455,11 @@ export class SyncSagaCoordinator {
             if (!responseCtx.data) { throw new Error(`(UNEXPECTED) responseCtx.data falsy? (E: a969992bae53ab18a827ec58aec15826)`); }
             updates$.next(responseCtx); // spins off for saga UI updating
 
-            // validate context
-            await validateContextAndSagaFrame
+            // immediately validate context/saga frame (but not payloads because
+            // we may not have those yet)
+            const contextAndSagaFrameValidationErrors =
+                await validateContextAndSagaFrame({ context: responseCtx });
+            if (contextAndSagaFrameValidationErrors.length > 0) { throw new Error(`contextAndSagaFrameValidationErrors: ${contextAndSagaFrameValidationErrors} (E: 6eebe8e7fa437c00a8cde3ada3c66826)`); }
 
             // Extract expected domain addresses from response context
             const responsePayloadAddrsDomain = responseCtx.data[SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN] as string[] || [];
@@ -399,6 +495,7 @@ export class SyncSagaCoordinator {
             // finished/errored out.
             const contextResult = await this.handleResponseSagaContext({
                 sagaContext: responseCtx,
+                initDomainGraph,
                 mySpace: localSpace,
                 myTempSpace: tempSpace,
                 metaspace,
@@ -625,7 +722,7 @@ export class SyncSagaCoordinator {
                 localSpace,
             });
 
-            // if (logalot) { console.log(`${lc} sagaFrame (init): ${pretty(sagaFrame)} (I: b3d6a8be69248f18713cc3073cb08626)`); }
+            if (logalot) { console.log(`${lc} sagaFrame (init): ${pretty(sagaFrame)} (I: b3d6a8be69248f18713cc3073cb08626)`); }
 
             return { initFrame: sagaFrame, initDomainGraph: fullGraph };
         } catch (error) {
@@ -708,6 +805,7 @@ export class SyncSagaCoordinator {
 
     /**
      * This is the heart of the "ping pong" transaction, where we send a context
+     *
      * and receive a context. IOW, this drives the FSM of the sync saga ibgib as
      * a whole.
      *
@@ -728,6 +826,7 @@ export class SyncSagaCoordinator {
      */
     public async handleResponseSagaContext({
         sagaContext,
+        initDomainGraph,
         mySpace,
         myTempSpace,
         identity,
@@ -735,6 +834,13 @@ export class SyncSagaCoordinator {
         metaspace,
     }: {
         sagaContext: SyncSagaContextIbGib_V1,
+        /**
+         * This is the initial dependency graph of all domain ibgibs passed in
+         * to the original {@link sync} call.
+         *
+         * if we're executing on the sender, this will be populated
+         */
+        initDomainGraph?: FlatIbGibGraph,
         /**
          * Local space relative to the execution context's POV
          */
@@ -746,7 +852,7 @@ export class SyncSagaCoordinator {
         identity?: KeystoneIbGib_V1,
         identitySecret?: string,
         metaspace: MetaspaceService,
-    }): Promise<HandleSagaResponseContextResult | null> {
+    }): Promise<HandleSagaResponseContextResult> {
         const lc = `${this.lc}[${this.handleResponseSagaContext.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting... (I: 5deec8a1f7a6d263c88cd458ad990826)`); }
@@ -756,7 +862,7 @@ export class SyncSagaCoordinator {
             if (logalot) { console.log(`${lc} sagaIbGib: ${pretty(sagaIbGib)} (I: 1b99d87d262e9d18d8a607a80b1a0126)`); }
 
             // Get Stage from Stone (or Frame for Init fallback)
-            const { stage, messageData } = await this.getStageAndPayloadFromFrame({ sagaFrame: sagaIbGib, space: myTempSpace });
+            const { stage, messageData } = await this.getStageAndPayloadFromFrame({ sagaFrame: sagaIbGib, space: mySpace });
 
             if (logalot) { console.log(`${lc} handling frame stage: ${stage}`); }
 
@@ -771,30 +877,44 @@ export class SyncSagaCoordinator {
                     nextFrameInfo = await this.handleInitFrame({
                         sagaIbGib,
                         messageData: messageData as SyncSagaMessageInitData_V1,
-                        metaspace,
-                        mySpace: mySpace,
-                        myTempSpace: myTempSpace,
-                        identity,
-                        identitySecret
+                        metaspace, mySpace, myTempSpace,
+                        identity, identitySecret
                     });
                     break;
 
                 case SyncStage.ack:
-                    nextFrameInfo = await this.handleAckFrame({ sagaIbGib, srcGraph, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity });
+                    if (!initDomainGraph) { throw new Error(`(UNEXPECTED) initDomainGraph falsy on the sender? (E: a3d758ad954829aba88663188eafc826)`); }
+                    nextFrameInfo = await this.handleAckFrame({
+                        sagaContext,
+                        sagaIbGib,
+                        initDomainGraph,
+                        metaspace, mySpace, myTempSpace,
+                        identity,
+                    });
                     break;
 
                 case SyncStage.delta:
-                    nextFrameInfo = await this.handleDeltaFrame({ sagaIbGib, srcGraph, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity, });
+                    nextFrameInfo = await this.handleDeltaFrame({
+                        sagaContext,
+                        sagaIbGib,
+                        srcGraph,
+                        metaspace,
+                        mySpace,
+                        myTempSpace,
+                        identity,
+                    });
                     break;
 
                 case SyncStage.commit:
-                    nextFrameInfo = await this.handleCommitFrame({ sagaIbGib, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity, });
+                    nextFrameInfo = await this.handleCommitFrame({ sagaIbGib, metaspace, mySpace: mySpace, myTempSpace: myTempSpace, identity, });
                     break;
 
                 default:
                     throw new Error(`${lc} (UNEXPECTED) Unknown sync stage: ${stage} (E: 9c2b4c8a6d34469f8263544710183355)`);
             }
 
+            if (logalot) { console.log(`${lc} nextFrameInfo: ${nextFrameInfo ? pretty(nextFrameInfo) : 'undefined'} (I: a8ad281ca8e89385686d18327a105726)`); }
+
             return { errorMsg: undefined, nextFrameInfo, }
 
         } catch (error) {
@@ -817,7 +937,7 @@ export class SyncSagaCoordinator {
      * The Receiver performs Gap Analysis here:
      * 1.  Compares Sender's Knowledge Vector (in `sagaIbGib`) vs Receiver's Local KV.
      * 2.  Identifies what Sender needs (`pushOfferAddrs`).
-     * 3.  Identifies what Receiver needs (`deltaReqAddrs`).
+     * 3.  Identifies what Receiver needs (`deltaRequestAddrInfos`).
      * 4.  Returns an `Ack` frame containing these lists.
      */
     protected async handleInitFrame({
@@ -1070,7 +1190,7 @@ export class SyncSagaCoordinator {
 
             const ackStone = await this.createSyncMsgStone({
                 data: ackData,
-                localSpace: myTempSpace,
+                localSpace: mySpace,
                 metaspace,
             });
             if (logalot) { console.log(`${lc} ackStone created: ${pretty(ackStone)} (I: 313708132dd53ff946befb7833657826)`); }
@@ -1090,8 +1210,6 @@ export class SyncSagaCoordinator {
              * we want to push ibgibs to the remote/sender if we have push
              * offers. an ack frame's payloads, if any, are those push offers
              */
-            // let payloadIbGibsDomain: IbGib_V1[] | undefined = await getPushOffers
-
             let payloadIbGibsDomain: IbGib_V1[] | undefined;
             if (pushOfferInfos.length > 0) {
                 const searchSecondSpaceAddrs: IbGibAddr[] = [];
@@ -1143,12 +1261,10 @@ export class SyncSagaCoordinator {
                 // we have now populated payloadIbGibsDomain
             }
 
-            throw new Error(`not implemented (E: ed3f98abb0988c5ae8038bb8d741fb26)`);
-            // return {
-            //     frame: ackFrame,
-            //     // conflictInfos,
-            //     payloadIbGibsDomain,
-            // };
+            return {
+                frame: ackFrame,
+                payloadIbGibsDomain,
+            };
 
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -1165,23 +1281,38 @@ export class SyncSagaCoordinator {
      * **Execution Context**: **Sender (Local)**.
      *
      * The Sender reacts to the Receiver's requirements:
-     * 1.  `deltaReqAddrs`: Receiver wants this data. Sender gathers it from `srcGraph` and puts it in `payloadIbGibs` (for next frame).
-     * 2.  `pushOfferAddrs`: Receiver has newer data. Sender acknowledges and adds them to `requests` (asking Receiver to send them).
+     * 1. `deltaRequestAddrInfos`: Receiver wants this data. Sender takes this
+     *    into account, plus gathers it from `initDomainGraph` and puts them in
+     *    `payloadIbGibs` (for next frame).
+     * 2. `pushOfferAddrs`: Receiver has newer data. these should have been
+     *    included in the incoming context from the receiver..
      *
      * Returns a `Delta` frame.
      */
     protected async handleAckFrame({
+        sagaContext,
         sagaIbGib,
-        srcGraph,
-        destSpace,
-        tempSpace,
-        metaspace,
+        initDomainGraph,
+        mySpace, myTempSpace, metaspace,
         identity,
     }: {
+        /**
+         * todo: figure out if we need to do something about incoming push offer payload domain ibgibs
+         * I'm adding this because we should be checking incoming payloads
+         * right? for push offers? This is when the receiver had new ibgibs.
+         * Not sure if I need to put this here though...
+         */
+        sagaContext: SyncSagaContextIbGib_V1,
         sagaIbGib: SyncIbGib_V1,
-        srcGraph: { [addr: string]: IbGib_V1 },
-        destSpace: IbGibSpaceAny,
-        tempSpace: IbGibSpaceAny,
+        /**
+         * This is the initial dependency graph of all domain ibgibs passed in
+         * to the original {@link sync} call.
+         *
+         * if we're executing on the sender, this will be populated
+         */
+        initDomainGraph: FlatIbGibGraph,
+        mySpace: IbGibSpaceAny,
+        myTempSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,
         identity?: KeystoneIbGib_V1,
     }): Promise<NextSagaFrameInfo> {
@@ -1189,9 +1320,10 @@ export class SyncSagaCoordinator {
         try {
             if (logalot) { console.log(`${lc} starting... (I: 605b6860e898267a5b50c6d85704be26)`); }
 
-            const { messageData, } = await this.getStageAndPayloadFromFrame({ sagaFrame: sagaIbGib, space: tempSpace });
+            const { messageData, } = await this.getStageAndPayloadFromFrame({ sagaFrame: sagaIbGib, space: mySpace });
             const ackData = messageData as SyncSagaMessageAckData_V1;
 
+            // #region sanity/validation
             if (!ackData) {
                 throw new Error(`${lc} ackData falsy (E: 3b8415edc876084c88a25b98e2d55826)`);
             }
@@ -1199,6 +1331,8 @@ export class SyncSagaCoordinator {
                 throw new Error(`${lc} Invalid ack frame: ackData.stage !== SyncStage.ack (E: 2e8b0a94b5954a66a6a1a7a0b3f5b7a1)`);
             }
             if (logalot) { console.log(`${lc} ackData: ${pretty(ackData)} (I: 7f8e9d0a1b2c3d4e5f6g7h8i9j0k)`); }
+            if (!sagaIbGib.data) { throw new Error(`(UNEXPECTED) sagaIbGib.data falsy? (E: 385e389610282aa9c5dbe4083adbde26)`); }
+            // #region sanity/validation
 
             // 1. Check for Conflicts
             const conflicts = ackData.conflicts || [];
@@ -1215,11 +1349,17 @@ export class SyncSagaCoordinator {
                 throw new Error(`${lc} Peer reported terminal conflicts. (E: 23a0096ee05a2ccfa89334e8f156b426)`);
             }
 
-            const optimisticConflicts = conflicts.filter(c => !c.terminal);
-            const mergeDeltaReqs: string[] = []; // Additional requests for merging
+            // at this point, if we have conflicts, they are non-terminal
+
+            /**
+             * at this point, we only request ibgibs for conflicted timelines.
+             * If the receiver had known of any ibgibs this sender needed, it
+             * would have been in the push offer.
+             */
+            const outgoingDeltaAddrRequestInfos: SyncSagaRequestAddrInfo[] = []; // Additional requests for merging
 
-            if (optimisticConflicts.length > 0) {
-                console.log(`${lc} [CONFLICT DEBUG] Processing ${optimisticConflicts.length} optimistic conflicts`);
+            if (conflicts.length > 0) {
+                console.log(`${lc} [CONFLICT DEBUG] Processing ${conflicts.length} non-terminal conflicts`);
                 // We need to resolve these.
                 // Strategy:
                 // 1. Analyze Divergence (Sender vs Receiver)
@@ -1228,8 +1368,8 @@ export class SyncSagaCoordinator {
                 // 4. (Later in Delta Phase) Perform Merge.
 
                 // BUT: The Delta Phase is usually generic "Send me these Addrs".
-                // If we just add to `deltaReqAddrs` (which are requests for Sender to send to Receiver?),
-                // wait. `ackData.deltaReqAddrs` are what RECEIVER wants from SENDER.
+                // If we just add to `deltaRequestAddrInfos` (which are requests for Sender to send to Receiver?),
+                // wait. `ackData.deltaRequestAddrInfos` are what RECEIVER wants from SENDER.
 
                 // We (Sender) are processing the Ack.
                 // We need to request data FROM Receiver.
@@ -1252,208 +1392,153 @@ export class SyncSagaCoordinator {
 
                 // Let's analyze and pull immediately.
 
-                for (const conflict of optimisticConflicts) {
-                    const { timelineAddrs, localAddr: receiverTip, remoteAddr: senderTip } = conflict;
-
-                    // Sender History
-                    // We need our own history for this timeline.
-                    // We know the 'senderTip' (remoteAddr in Ack).
-                    // Sender should verify it has this tip.
-
-                    // Compute Diffs
-                    // We need to find `receiverOnly` addrs.
-                    // Receiver sent us `timelineAddrs` (Full History).
-                    const receiverHistorySet = new Set(timelineAddrs);
-
-                    // We need our execution context's history for this senderTip.
-                    // We can fetch valid 'past' from space.
-                    const resSenderTip = await getFromSpace({ space: destSpace, addr: senderTip });
-                    const senderTipIbGib = resSenderTip.ibGibs?.[0];
-                    if (!senderTipIbGib) { throw new Error(`${lc} Sender missing its own tip? ${senderTip} (E: 832f3804645878869ee3c13714366726)`); }
-
-                    // Basic Diff: Find what Receiver has that we don't.
-                    // Actually, we need to traverse OUR past to find commonality.
-                    const senderHistory = [senderTip, ...(senderTipIbGib.rel8ns?.past || [])];
-
-                    const receiverOnlyAddrs = timelineAddrs.filter(addr => !senderHistory.includes(addr));
-
-                    if (receiverOnlyAddrs.length > 0) {
-                        console.log(`${lc} [CONFLICT DEBUG] Found ${receiverOnlyAddrs.length} receiver-only frames - need to pull for merge`);
-                        console.log(`${lc} [CONFLICT DEBUG] Receiver-only addrs:`, receiverOnlyAddrs);
-                        // PULL these frames from Peer into Local Space
-                        // (Validation: We trust peer for now / verification happens on put)
-                        for (const addr of receiverOnlyAddrs) {
-                            console.error(`${lc} [CONFLICT DEBUG] NOT IMPLEMENTED (E: e6bf1a9d2758c469bb2f97514062d826)`);
-                        }
-
-                        // Compute DELTA dependencies for each receiver-only frame
-                        // Find LCA to determine what dependencies we already have
-                        const lcaAddr = timelineAddrs.find(addr => senderHistory.includes(addr));
-                        console.log(`${lc} [CONFLICT DEBUG] LCA: ${lcaAddr || 'NONE'}`);
-
-                        const skipAddrsSet = new Set<string>();
-                        if (lcaAddr) {
-                            try {
-                                const lcaRes = await getFromSpace({ addr: lcaAddr, space: destSpace });
-                                const lcaIbGib = lcaRes.ibGibs?.[0];
-                                if (lcaIbGib) {
-                                    const lcaDeps = await getDependencyGraph({ ibGib: lcaIbGib, space: destSpace });
-                                    if (lcaDeps) Object.keys(lcaDeps).forEach(a => skipAddrsSet.add(a));
-                                    console.log(`${lc} [CONFLICT DEBUG] LCA deps to skip: ${skipAddrsSet.size}`);
-                                }
-                            } catch (e) {
-                                console.warn(`${lc} Error getting LCA deps: ${extractErrorMsg(e)}`);
-                            }
-                        }
-
-
-                        // For each receiver-only frame, get its DELTA dependency graph (minus LCA deps)
-                        for (const addr of receiverOnlyAddrs) {
-                            // Add the frame itself first
-                            if (!mergeDeltaReqs.includes(addr)) {
-                                mergeDeltaReqs.push(addr);
-                            }
-
-                            // Get the frame's delta dependencies (skip LCA's deps)
-                            try {
-                                const frameRes = await getFromSpace({ addr, space: destSpace });
-                                const frameIbGib = frameRes.ibGibs?.[0];
-
-                                if (frameIbGib) {
-                                    // Get dependency graph, skipping all LCA dependencies
-                                    const frameDeltaDeps = await getDependencyGraph({
-                                        ibGib: frameIbGib,
-                                        space: destSpace,
-                                        skipAddrs: Array.from(skipAddrsSet), // Skip entire LCA dep graph
-                                    });
-
-                                    if (frameDeltaDeps) {
-                                        // Add all delta dependencies (Object.keys gives us the addresses)
-                                        Object.keys(frameDeltaDeps).forEach(depAddr => {
-                                            if (!mergeDeltaReqs.includes(depAddr) && !skipAddrsSet.has(depAddr)) {
-                                                mergeDeltaReqs.push(depAddr);
-                                            }
-                                        });
-                                    }
-                                }
-                            } catch (depError) {
-                                console.warn(`${lc} [CONFLICT DEBUG] Error getting delta deps for ${addr}: ${extractErrorMsg(depError)}`);
-                            }
-                        }
-
-                        console.log(`${lc} [CONFLICT DEBUG] Total merge requests (frames + delta deps): ${mergeDeltaReqs.length}`);
-                    } else {
-                        console.log(`${lc} [CONFLICT DEBUG] No receiver-only frames found for this conflict`);
-                    }
+                for (const conflict of conflicts) {
+                    // todo: integrate conflict strategies into this point...this whole block needs to be redone, but I want to check the fast-forward/backward simpler case tests first
+
+                    throw new Error(`conflicts not (re)implemented yet (E: 3b7d0819f83842a6de3ae988819bc826)`);
+
+
+                    // const { timelineAddrs, localAddr: receiverTip, remoteAddr: senderTip } = conflict;
+
+                    // // Sender History
+                    // // We need our own history for this timeline.
+                    // // We know the 'senderTip' (remoteAddr in Ack).
+                    // // Sender should verify it has this tip.
+
+                    // // Compute Diffs
+                    // // We need to find `receiverOnly` addrs.
+                    // // Receiver sent us `timelineAddrs` (Full History).
+                    // const receiverHistorySet = new Set(timelineAddrs);
+
+                    // // We need our execution context's history for this senderTip.
+                    // // We can fetch valid 'past' from space.
+                    // const resSenderTip = await getFromSpace({ space: destSpace, addr: senderTip });
+                    // const senderTipIbGib = resSenderTip.ibGibs?.[0];
+                    // if (!senderTipIbGib) { throw new Error(`${lc} Sender missing its own tip? ${senderTip} (E: 832f3804645878869ee3c13714366726)`); }
+
+                    // // Basic Diff: Find what Receiver has that we don't.
+                    // // Actually, we need to traverse OUR past to find commonality.
+                    // const senderHistory = [senderTip, ...(senderTipIbGib.rel8ns?.past || [])];
+
+                    // const receiverOnlyAddrs = timelineAddrs.filter(addr => !senderHistory.includes(addr));
+
+                    // if (receiverOnlyAddrs.length > 0) {
+                    //     console.log(`${lc} [CONFLICT DEBUG] Found ${receiverOnlyAddrs.length} receiver-only frames - need to pull for merge`);
+                    //     console.log(`${lc} [CONFLICT DEBUG] Receiver-only addrs:`, receiverOnlyAddrs);
+                    //     // PULL these frames from Peer into Local Space
+                    //     // (Validation: We trust peer for now / verification happens on put)
+                    //     for (const addr of receiverOnlyAddrs) {
+                    //         console.error(`${lc} [CONFLICT DEBUG] NOT IMPLEMENTED (E: e6bf1a9d2758c469bb2f97514062d826)`);
+                    //     }
+
+                    //     // Compute DELTA dependencies for each receiver-only frame
+                    //     // Find LCA to determine what dependencies we already have
+                    //     const lcaAddr = timelineAddrs.find(addr => senderHistory.includes(addr));
+                    //     console.log(`${lc} [CONFLICT DEBUG] LCA: ${lcaAddr || 'NONE'}`);
+
+                    //     const skipAddrsSet = new Set<string>();
+                    //     if (lcaAddr) {
+                    //         try {
+                    //             const lcaRes = await getFromSpace({ addr: lcaAddr, space: destSpace });
+                    //             const lcaIbGib = lcaRes.ibGibs?.[0];
+                    //             if (lcaIbGib) {
+                    //                 const lcaDeps = await getDependencyGraph({ ibGib: lcaIbGib, space: destSpace });
+                    //                 if (lcaDeps) Object.keys(lcaDeps).forEach(a => skipAddrsSet.add(a));
+                    //                 console.log(`${lc} [CONFLICT DEBUG] LCA deps to skip: ${skipAddrsSet.size}`);
+                    //             }
+                    //         } catch (e) {
+                    //             console.warn(`${lc} Error getting LCA deps: ${extractErrorMsg(e)}`);
+                    //         }
+                    //     }
+
+
+                    //     // For each receiver-only frame, get its DELTA dependency graph (minus LCA deps)
+                    //     for (const addr of receiverOnlyAddrs) {
+                    //         // Add the frame itself first
+                    //         if (!outgoingDeltaAddrRequestInfos.includes(addr)) {
+                    //             outgoingDeltaAddrRequestInfos.push(addr);
+                    //         }
+
+                    //         // Get the frame's delta dependencies (skip LCA's deps)
+                    //         try {
+                    //             const frameRes = await getFromSpace({ addr, space: destSpace });
+                    //             const frameIbGib = frameRes.ibGibs?.[0];
+
+                    //             if (frameIbGib) {
+                    //                 // Get dependency graph, skipping all LCA dependencies
+                    //                 const frameDeltaDeps = await getDependencyGraph({
+                    //                     ibGib: frameIbGib,
+                    //                     space: destSpace,
+                    //                     skipAddrs: Array.from(skipAddrsSet), // Skip entire LCA dep graph
+                    //                 });
+
+                    //                 if (frameDeltaDeps) {
+                    //                     // Add all delta dependencies (Object.keys gives us the addresses)
+                    //                     Object.keys(frameDeltaDeps).forEach(depAddr => {
+                    //                         if (!outgoingDeltaAddrRequestInfos.includes(depAddr) && !skipAddrsSet.has(depAddr)) {
+                    //                             outgoingDeltaAddrRequestInfos.push(depAddr);
+                    //                         }
+                    //                     });
+                    //                 }
+                    //             }
+                    //         } catch (depError) {
+                    //             console.warn(`${lc} [CONFLICT DEBUG] Error getting delta deps for ${addr}: ${extractErrorMsg(depError)}`);
+                    //         }
+                    //     }
+
+                    //     console.log(`${lc} [CONFLICT DEBUG] Total merge requests (frames + delta deps): ${outgoingDeltaAddrRequestInfos.length}`);
+                    // } else {
+                    //     console.log(`${lc} [CONFLICT DEBUG] No receiver-only frames found for this conflict`);
+                    // }
                 }
 
-                console.log(`${lc} [CONFLICT DEBUG] Finished processing ${optimisticConflicts.length} conflicts. mergeDeltaReqs: ${mergeDeltaReqs.length}`);
+                console.log(`${lc} [CONFLICT DEBUG] Finished processing ${conflicts.length} conflicts. outgoingDeltaAddrRequestInfos: ${outgoingDeltaAddrRequestInfos.length}`);
             } else {
                 console.log(`${lc} [CONFLICT DEBUG] No optimistic conflicts to process`);
             }
 
             // 2. Prepare Delta Payload (What Receiver Requesting + Our Conflict Logic)
 
-            const deltaReqAddrs = ackData.deltaRequestAddrInfos || [];
-            const pushOfferAddrs = ackData.pushOfferInfos || [];
-
-            // 1. Process Push Offers (Pull Requests) (Naive: Accept all if missing)
-            const pullReqAddrs: string[] = [];
-            for (const addr of pushOfferAddrs) {
-                // const existing = srcGraph[addr] || (await getFromSpace({ addr, space: destSpace })).ibGibs?.[0];
-                // if (!existing) {
-                //     pullReqAddrs.push(addr);
-                // }
-            }
-
-            // 2. Process Delta Requests (Push Payload)
-            // [NEW] Smart Diff: Use knowledgeVector to skip dependencies
-            // const useThisFunction = getDeltaDependencyGraph({ ibGibAddr: '', latestCommonFrameAddr: '', space: })
-            const skipAddrs = new Set<string>();
-            if (ackData.knowledgeVector) {
-                Object.values(ackData.knowledgeVector).forEach(addrs => {
-                    // addrs.forEach(a => skipAddrs.add(a));
-                });
-            }
-
-            const payloadIbGibs: IbGib_V1[] = [];
-            // Gather all tips to sync first
-            const tipsToSync: IbGib_V1[] = [];
-            for (const addr of deltaReqAddrs) {
-                // let ibGib = srcGraph[addr];
-                // if (!ibGib) {
-                //     const res = await getFromSpace({ addr, space: destSpace });
-                //     if (res.ibGibs && res.ibGibs.length > 0) {
-                //         ibGib = res.ibGibs[0];
-                //     }
-                // }
-                // if (ibGib) {
-                //     tipsToSync.push(ibGib);
-                // } else {
-                //     throw new Error(`${lc} Requested addr not found: ${addr} (E: d41d59cff4a887f6414c3e92eabd8e26)`);
-                // }
-            }
-
-            // Calculate Dependency Graph for ALL tips, effectively utilizing common history
-            // Pass skipAddrs to `getDependencyGraph` or gather manually.
-            // `getDependencyGraph` takes a single ibGib.
-            // We can optimize by doing it for each tip and unioning the result?
-            // Or `graph-helper` could support `ibGibs: []`. It currently takes `ibGib`.
-            // We will loop.
-
-            const allDepsSet = new Set<string>();
-
-            for (const tip of tipsToSync) {
-                // Always include the tip itself
-                const tipAddr = getIbGibAddr({ ibGib: tip });
-                // Only process if not skipped (though deltaReq implies they barely just asked for it)
-                // But detailed deps might be skipped.
-
-                // Get Graph with Skips
-                // Logic: "Give me everything related to Tip, EXCEPT X, Y, Z"
-                const deps = await getDependencyGraph({
-                    ibGib: tip,
-                    space: destSpace,
-                    skipAddrs: Array.from(skipAddrs)
-                });
-
-                // [FIX] Ensure Tip is included if not in deps (e.g. constant with no rel8ns)
-                let tipIncluded = false;
-
-                if (deps) {
-                    Object.values(deps).forEach(d => {
-                        const dAddr = getIbGibAddr({ ibGib: d });
-                        if (!allDepsSet.has(dAddr)) {
-                            allDepsSet.add(dAddr);
-                            payloadIbGibs.push(d);
-                        }
-                        if (dAddr === tipAddr) { tipIncluded = true; }
-                    });
-                }
-
-                if (!tipIncluded && !skipAddrs.has(tipAddr)) {
-                    if (logalot) { console.log(`${lc} Tip not in deps, adding explicitly: ${tipAddr}`); }
-                    if (!allDepsSet.has(tipAddr)) {
-                        allDepsSet.add(tipAddr);
-                        payloadIbGibs.push(tip);
-                    }
-                }
-            }
+            /**
+             * these were requested addrs on the INCOMING frame (the ack data).
+             *
+             * This is in contrast to any OUTGOING requests we make in this
+             * method.
+             */
+            const payloadIbGibsDomain = await this.getPayloadsForRequestedInfos({
+                deltaRequestAddrInfos: ackData.deltaRequestAddrInfos || [],
+                mySpace,
+            });
 
             // 3. Create Delta Frame
-            const sagaId = ackData.sagaId;
             const deltaData: SyncSagaMessageDeltaData_V1 = {
-                sagaId: sagaIbGib.data!.uuid,
+                sagaId: sagaIbGib.data.uuid,
                 stage: SyncStage.delta,
-                payloadAddrs: payloadIbGibs.map(p => getIbGibAddr({ ibGib: p })),
-                requests: [...(pullReqAddrs || []), ...(mergeDeltaReqs || [])].length > 0 ? [...(pullReqAddrs || []), ...(mergeDeltaReqs || [])] : undefined,
+                /**
+                 * we're sending these domain ibgibs as payload (they were
+                 * requested by receiver)
+                 */
+                payloadAddrsDomain: payloadIbGibsDomain.length > 0 ?
+                    payloadIbGibsDomain.map(x => getIbGibAddr({ ibGib: x })) :
+                    undefined,
+                /**
+                 * we're asking for these addrs
+                 */
+                deltaRequestAddrInfos: outgoingDeltaAddrRequestInfos.length > 0 ?
+                    outgoingDeltaAddrRequestInfos :
+                    undefined,
+                /**
+                 * if we have no changes and request none, propose commit to
+                 * finish the sync transaction.
+                 */
+                proposeCommit: payloadIbGibsDomain.length === 0 && outgoingDeltaAddrRequestInfos.length === 0,
             };
 
             if (logalot) { console.log(`${lc} Creating Delta Stone. Data stage: ${deltaData.stage}`); }
 
             const deltaStone = await this.createSyncMsgStone({
                 data: deltaData,
-                localSpace: tempSpace,
+                localSpace: mySpace,
                 metaspace,
             });
 
@@ -1461,7 +1546,7 @@ export class SyncSagaCoordinator {
                 prevSagaIbGib: sagaIbGib,
                 msgStones: [deltaStone],
                 sessionIdentity: identity,
-                localSpace: tempSpace,
+                localSpace: mySpace,
                 metaspace,
             });
 
@@ -1471,9 +1556,71 @@ export class SyncSagaCoordinator {
             const payloadIbGibsControl: IbGib_V1[] = [deltaFrame, deltaStone];
             if (identity) { payloadIbGibsControl.push(identity); }
 
-            // return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: payloadIbGibs };
-            // return { frame: deltaFrame, payloadIbGibsDomain: payloadIbGibs };
-            throw new Error(`not implemented (E: 62e1e2a408e8bfa2982b2f87e8843826)`);
+            return { frame: deltaFrame, payloadIbGibsDomain, };
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    private async getPayloadsForRequestedInfos({
+        deltaRequestAddrInfos,
+        mySpace,
+    }: {
+        deltaRequestAddrInfos: SyncSagaRequestAddrInfo[];
+        mySpace: IbGibSpaceAny;
+    }): Promise<IbGib_V1[]> {
+        const lc = `${this.lc}[${this.getPayloadsForRequestedInfos.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 4fe13d0d80050f20a8b74ba80cee5826)`); }
+            /**
+             * graph of ibgibs we will send to the receiver. addr-based, so will
+             * already be unique (no need to call `unique` on the domains
+             * ibgibs)
+             */
+            const outgoingPayloadIbGibsDomainGraph: FlatIbGibGraph = {};
+            for (const { addr, latestAddrAlreadyHave } of deltaRequestAddrInfos) {
+                let deltaDepGraph: FlatIbGibGraph;
+                if (latestAddrAlreadyHave) {
+                    // already has some, so only get the delta
+                    // remember: if we didn't have the other's latest addr, then
+                    // this would be in the conflicts not requested addrs
+                    deltaDepGraph = await getDeltaDependencyGraph({
+                        ibGibAddr: addr,
+                        latestCommonFrameAddr: latestAddrAlreadyHave,
+                        space: mySpace,
+                        live: true,
+                    });
+                } else {
+                    // doesn't have anything, so get the entire dependency graph
+                    // INEFFICIENT: we've already gotten all of the domain
+                    // dependencies in initDomainGraph, but getDependencyGraph
+                    // only works against a space so we are going to rerun this.
+                    // an optimization would be to adapt/create a new
+                    // getDependencyGraph to work against an existing flat ibgib
+                    // map.
+                    deltaDepGraph = await getDependencyGraph({
+                        ibGibAddr: addr,
+                        space: mySpace,
+                        live: true,
+                    });
+                }
+
+                const depGraphSize = Object.keys(deltaDepGraph).length;
+                if (depGraphSize === 0) {
+                    throw new Error(`(UNEXPECTED) couldn't get requested addrs in mySpace (${mySpace.ib})? How did the receiver know to ask for these addrs if they weren't in our original graph? (E: 281eaebcdf77dd73e8245b2872100826)`);
+                } else {
+                    // we have dependencies!
+                    Object.values(deltaDepGraph).forEach(x => {
+                        outgoingPayloadIbGibsDomainGraph[getIbGibAddr({ ibGib: x })] = x;
+                    });
+                }
+            }
+
+            const result = Object.values(outgoingPayloadIbGibsDomainGraph);
+            return result;
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;
@@ -1493,313 +1640,192 @@ export class SyncSagaCoordinator {
      * 3.  **Completion**: If no more requests, transitions to `Commit`.
      */
     protected async handleDeltaFrame({
+        sagaContext,
         sagaIbGib,
         srcGraph,
-        destSpace,
-        tempSpace,
+        mySpace,
+        myTempSpace,
         metaspace,
         identity,
     }: {
+        sagaContext: SyncSagaContextIbGib_V1,
         sagaIbGib: SyncIbGib_V1,
         srcGraph: { [addr: string]: IbGib_V1 },
-        destSpace: IbGibSpaceAny,
-        tempSpace: IbGibSpaceAny,
+        mySpace: IbGibSpaceAny,
+        myTempSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,
         identity?: KeystoneIbGib_V1,
     }): Promise<NextSagaFrameInfo> {
         const lc = `${this.lc}[${this.handleDeltaFrame.name}]`;
-        if (logalot) { console.log(`${lc} starting...`); }
-
-        const { messageData } = await this.getStageAndPayloadFromFrame({ sagaFrame: sagaIbGib, space: tempSpace });
-        const deltaData = messageData as SyncSagaMessageDeltaData_V1;
-
-        if (!deltaData) {
-            throw new Error(`${lc} deltaData falsy (E: 7c28c8d8f08a4421b8344e6727271421)`);
-        }
-        if (deltaData.stage !== SyncStage.delta) {
-            throw new Error(`${lc} Invalid delta frame: deltaData.stage !== SyncStage.delta (E: 0c28c8d8f08a4421b8344e6727271421)`);
-        }
-        if (logalot) { console.log(`${lc} deltaData: ${pretty(deltaData)} (I: a76008681df458cfbcdc4848f825a826)`); }
-
-        console.log(`${lc} [CONFLICT DEBUG] deltaData.payloadAddrs count: ${deltaData.payloadAddrs?.length || 0}`);
-
-        const payloadAddrs = deltaData.payloadAddrs || [];
-        const peerRequests = deltaData.requests || [];
-        const peerProposesCommit = deltaData.proposeCommit || false;
-
-        // 1. Process Received Payload (Ingest)
-        const receivedPayloadIbGibs: IbGib_V1[] = [];
-        if (payloadAddrs.length > 0) {
-            // We use `payloadAddrs` as the manifest.
-            // The ACTUAL collection of ibGibs should be available via `getFromSpace`
-            // assuming the "Transport" layer put them there implicitly?
-            // OR, if we are local-only, we just get them.
-            // The `handleDeltaFrame` contract assumes data is reachable in `space`.
-
-            const res = await getFromSpace({
-                addrs: payloadAddrs,
-                space: tempSpace, // Incoming data is in tempSpace
-            });
-            if (res.ibGibs) {
-                receivedPayloadIbGibs.push(...res.ibGibs);
-                // Also put them? `getFromSpace` retrieves. If they are in space, they are persisted.
-                // If this is a Temp Space, they are safe.
-            } else {
-                console.warn(`${lc} Failed to retrieve payloads listed in delta: ${payloadAddrs.join(', ')}`);
-            }
-        }
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: a1d0a85eb4189466f86dfd61e3df2626)`); }
 
-        // 2. Fulfill Peer Requests (Outgoing Payload with Delta Dependencies)
-        const outgoingPayload: IbGib_V1[] = [];
-        const outgoingAddrsSet = new Set<string>(); // Track what we've added
+            const { messageData } = await this.getStageAndPayloadFromFrame({ sagaFrame: sagaIbGib, space: mySpace });
+            const deltaData = messageData as SyncSagaMessageDeltaData_V1;
 
-        console.log(`${lc} [CONFLICT DEBUG] Fulfilling ${peerRequests.length} peer requests`);
+            // #region validate/sanity
+            if (!deltaData) { throw new Error(`${lc} deltaData falsy (E: 7c28c8d8f08a4421b8344e6727271421)`); }
+            if (deltaData.stage !== SyncStage.delta) { throw new Error(`${lc} Invalid delta frame: deltaData.stage !== SyncStage.delta (E: 0c28c8d8f08a4421b8344e6727271421)`); }
+            if (logalot) { console.log(`${lc} deltaData: ${pretty(deltaData)} (I: a76008681df458cfbcdc4848f825a826)`); }
+            // #endregion validate/sanity
 
-        for (const addr of peerRequests) {
-            // Get the requested ibGib
-            let ibGib = srcGraph[addr];
-            if (!ibGib) {
-                const res = await getFromSpace({ addr, space: destSpace }); // Query from destSpace
-                if (res.ibGibs && res.ibGibs.length > 0) {
-                    ibGib = res.ibGibs[0];
-                }
-            }
+            console.log(`${lc} [CONFLICT DEBUG] deltaData.payloadAddrs count: ${deltaData.payloadAddrs?.length || 0}`);
 
-            if (ibGib) {
-                // Add the requested ibGib itself
-                const ibGibAddr = getIbGibAddr({ ibGib });
-                if (!outgoingAddrsSet.has(ibGibAddr)) {
-                    outgoingPayload.push(ibGib);
-                    outgoingAddrsSet.add(ibGibAddr);
-                }
+            const peerProposesCommit = deltaData.proposeCommit || false;
 
-                // Expand to include full dependency graph for this ibGib
-                // (Receiver needs all deps to properly process/merge)
-                try {
-                    const deps = await getDependencyGraph({
-                        ibGib,
-                        space: destSpace,
-                    });
+            /**
+             * these are already in the local temp space
+             */
+            const receivedPayloadIbGibs: IbGib_V1[] = sagaContext.payloadIbGibsDomain ?? [];
 
-                    if (deps) {
-                        Object.values(deps).forEach(depIbGib => {
-                            const depAddr = getIbGibAddr({ ibGib: depIbGib });
-                            if (!outgoingAddrsSet.has(depAddr)) {
-                                outgoingPayload.push(depIbGib);
-                                outgoingAddrsSet.add(depAddr);
+            // 2. Fulfill Peer Requests (Outgoing Payload with Delta Dependencies)
+            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}`);
+
+            // 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: IbGib_V1[] = [];
+
+            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...`);
+                // 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}`);
+                let ackData: SyncSagaMessageAckData_V1 | undefined;
+
+                if (pastAddrs.length > 0) {
+                    // Batch fetch all past frames
+                    const resPast = await getFromSpace({ addrs: pastAddrs, space: myTempSpace });
+                    if (resPast.success && resPast.ibGibs) {
+                        // Iterate backwards (most recent first) to find the latest Ack
+                        for (let i = resPast.ibGibs.length - 1; i >= 0; i--) {
+                            const pastFrame = resPast.ibGibs[i];
+                            const messageStone = await getSyncSagaMessageFromFrame({
+                                frameIbGib: pastFrame,
+                                space: myTempSpace
+                            });
+                            if (messageStone?.data?.stage === SyncStage.ack) {
+                                ackData = messageStone.data as SyncSagaMessageAckData_V1;
+                                console.log(`${lc} [TEST DEBUG] Found Ack Frame. Conflicts: ${ackData.conflicts?.length || 0}`);
+                                break;
                             }
-                        });
-                    }
-                } catch (depError) {
-                    console.warn(`${lc} [CONFLICT DEBUG] Error expanding deps for ${addr}: ${extractErrorMsg(depError)}`);
-                }
-            } else {
-                console.warn(`${lc} Requested addr not found during delta fulfillment: ${addr}`);
-            }
-        }
-
-        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: IbGib_V1[] = [];
-
-        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...`);
-            // 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}`);
-            let ackData: SyncSagaMessageAckData_V1 | undefined;
-
-            if (pastAddrs.length > 0) {
-                // Batch fetch all past frames
-                const resPast = await getFromSpace({ addrs: pastAddrs, space: tempSpace });
-                if (resPast.success && resPast.ibGibs) {
-                    // Iterate backwards (most recent first) to find the latest Ack
-                    for (let i = resPast.ibGibs.length - 1; i >= 0; i--) {
-                        const pastFrame = resPast.ibGibs[i];
-                        const messageStone = await getSyncSagaMessageFromFrame({
-                            frameIbGib: pastFrame,
-                            space: tempSpace
-                        });
-                        if (messageStone?.data?.stage === SyncStage.ack) {
-                            ackData = messageStone.data as SyncSagaMessageAckData_V1;
-                            console.log(`${lc} [TEST DEBUG] Found Ack Frame. Conflicts: ${ackData.conflicts?.length || 0}`);
-                            break;
                         }
                     }
                 }
-            }
 
-            if (ackData && ackData.conflicts) {
-                const optimisticConflicts = ackData.conflicts.filter(c => !c.terminal);
-                for (const conflict of optimisticConflicts) {
-                    const { timelineAddrs, localAddr: receiverTip, remoteAddr: senderTip } = conflict;
-                    // We are Sender (usually) here if we are merging.
-                    // Check if we have the history needed (timelineAddrs).
-                    // Specifically, we needed the `receiverOnly` parts.
-
-                    // 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}`);
-                    const resRecTip = await getFromSpace({ addr: receiverTip, space: tempSpace }); // Check tempSpace for incoming data
-                    console.log(`${lc} [CONFLICT DEBUG] ReceiverTip found in tempSpace: ${!!resRecTip.ibGibs?.[0]}`);
-                    if (resRecTip.success && resRecTip.ibGibs?.[0]) {
-                        // We have the tip!
-                        // Do we have the full history?
-                        // `mergeDivergentTimelines` in `conflict-optimistic` will attempt to fetch history.
-                        // If we just ingested the missing pieces, `getFromSpace` inside `merge` should succeed.
-
-                        // Perform Merge!
-                        try {
-                            const mergeResult = await mergeDivergentTimelines({
-                                tipA: (await getFromSpace({ addr: senderTip, space: destSpace })).ibGibs![0], // Our tip from destSpace
-                                tipB: resRecTip.ibGibs[0], // Their tip (from tempSpace)
-                                space: tempSpace, // Merge uses tempSpace
-                                metaspace,
-                            });
-                            if (mergeResult) {
-                                console.log(`${lc} [TEST DEBUG] Merge success! New Tip: ${getIbGibAddr({ ibGib: mergeResult })}`);
-                                if (logalot) { console.log(`${lc} Merge success! New Tip: ${getIbGibAddr({ ibGib: mergeResult })}`); }
-                                mergeResultIbGibs.push(mergeResult);
-                                outgoingPayload.push(mergeResult); // Send result to peer
+                if (ackData && ackData.conflicts) {
+                    const optimisticConflicts = ackData.conflicts.filter(c => !c.terminal);
+                    for (const conflict of optimisticConflicts) {
+                        const { timelineAddrs, localAddr: receiverTip, remoteAddr: senderTip } = conflict;
+                        // We are Sender (usually) here if we are merging.
+                        // Check if we have the history needed (timelineAddrs).
+                        // Specifically, we needed the `receiverOnly` parts.
+
+                        // 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}`);
+                        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 (resRecTip.success && resRecTip.ibGibs?.[0]) {
+                            // We have the tip!
+                            // Do we have the full history?
+                            // `mergeDivergentTimelines` in `conflict-optimistic` will attempt to fetch history.
+                            // If we just ingested the missing pieces, `getFromSpace` inside `merge` should succeed.
+
+                            // Perform Merge!
+                            try {
+                                const mergeResult = await mergeDivergentTimelines({
+                                    tipA: (await getFromSpace({ addr: senderTip, space: mySpace })).ibGibs![0], // Our tip from destSpace
+                                    tipB: resRecTip.ibGibs[0], // Their tip (from myTempSpace)
+                                    space: myTempSpace, // Merge uses myTempSpace
+                                    metaspace,
+                                });
+                                if (mergeResult) {
+                                    console.log(`${lc} [TEST DEBUG] Merge success! New Tip: ${getIbGibAddr({ ibGib: mergeResult })}`);
+                                    if (logalot) { console.log(`${lc} Merge success! New Tip: ${getIbGibAddr({ ibGib: mergeResult })}`); }
+                                    mergeResultIbGibs.push(mergeResult);
+                                    outgoingPayload.push(mergeResult); // Send result to peer
+                                }
+                            } catch (e) {
+                                console.error(`${lc} Merge failed: ${e}`);
+                                // If merge fails, we might Abort or just continue?
                             }
-                        } catch (e) {
-                            console.error(`${lc} Merge failed: ${e}`);
-                            // If merge fails, we might Abort or just continue?
                         }
                     }
                 }
             }
-        }
-
-        // 4. Determine Next Action
-        // We have `outgoingPayload` (Requests + Merge Results).
-        // Does Peer have outstanding requests? No, we fulfilled `peerRequests`.
-        // Do WE have outstanding requests?
-        // We might if `mergeResult` requires further sync? Usually no, result is complete.
-
-        const myRequests: string[] = []; // If we had more needs (e.g. partial payload), we'd add here.
-
-        const hasOutgoing = outgoingPayload.length > 0;
-        const hasMyRequests = myRequests.length > 0;
-
-        if (hasOutgoing || hasMyRequests) {
-            // We have business to attend to -> Send Delta
-            const responseDeltaData: SyncSagaMessageDeltaData_V1 = {
-                sagaId: deltaData.sagaId,
-                stage: SyncStage.delta,
-                payloadAddrs: outgoingPayload.map(p => getIbGibAddr({ ibGib: p })),
-                requests: hasMyRequests ? myRequests : undefined,
-                proposeCommit: !hasMyRequests // If we are sending data but have no requests, we VALIDATE PROPOSAL?
-                // Wait. If we send data, we are NOT committing yet.
-                // We are sending data. The OTHER side must ingest it.
-                // So proposeCommit = true?
-                // "Here is the data. I'm done. If you are good, let's commit."
-                // Yes.
-            };
 
-            // BUT if `peerProposesCommit` was true, and we are sending data, we are effectively rejecting/delaying it.
-            // We just send the Delta. Peer receives it, ingests, sees ProposeCommit=True (from us), and then Commits.
+            // 4. Determine Next Action
+            // We have `outgoingPayload` (Requests + Merge Results).
+            // Does Peer have outstanding requests? No, we fulfilled `peerRequests`.
+            // Do WE have outstanding requests?
+            // We might if `mergeResult` requires further sync? Usually no, result is complete.
 
-            // So yes, proposeCommit = true.
-            responseDeltaData.proposeCommit = true;
+            const myRequests: string[] = []; // If we had more needs (e.g. partial payload), we'd add here.
 
-            const deltaStone = await this.createSyncMsgStone({
-                data: responseDeltaData,
-                localSpace: tempSpace,
-                metaspace
-            });
+            const hasOutgoing = outgoingPayload.length > 0;
+            const hasMyRequests = myRequests.length > 0;
 
-            const deltaFrame = await this.evolveSyncSagaIbGib({
-                prevSagaIbGib: sagaIbGib,
-                msgStones: [deltaStone],
-                sessionIdentity: identity,
-                localSpace: tempSpace,
-                metaspace
-            });
-
-            // Build control payloads: frame + its dependencies (msg stone, identity)
-            const payloadIbGibsControl: IbGib_V1[] = [deltaFrame, deltaStone];
-            if (identity) { payloadIbGibsControl.push(identity); }
-
-            // return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: outgoingPayload };
-            // return { frame: deltaFrame, payloadIbGibsDomain: outgoingPayload };
-            throw new Error(`not implemented (E: 2b38a8afb6d84efcee5ab51673387826)`);
-
-        } else {
-            // We have nothing to send.
-
-            if (peerProposesCommit) {
-                // Peer is done. We are done. -> Commit.
-                const commitData: SyncSagaMessageCommitData_V1 = {
-                    sagaId: deltaData.sagaId,
-                    stage: SyncStage.commit,
-                    success: true,
-                };
-
-                const commitStone = await this.createSyncMsgStone({
-                    data: commitData,
-                    localSpace: tempSpace,
-                    metaspace
-                });
-
-                const commitFrame = await this.evolveSyncSagaIbGib({
-                    prevSagaIbGib: sagaIbGib,
-                    msgStones: [commitStone],
-                    sessionIdentity: identity,
-                    localSpace: tempSpace,
-                    metaspace
-                });
-
-                // Build control payloads for commit
-                const commitCtrlPayloads: IbGib_V1[] = [commitFrame, commitStone];
-                if (identity) { commitCtrlPayloads.push(identity); }
-
-                // return { frame: commitFrame, payloadIbGibsControl: commitCtrlPayloads };
-                // return { frame: commitFrame, };
-                throw new Error(`not implemented (E: dda1ddc63fdcadff06653298e0d04826)`);
-
-            } else {
-                // peer did NOT propose commit (maybe they just sent data/requests and didn't ready flag).
-                // But we are empty.
-                // So WE propose commit.
+            if (hasOutgoing || hasMyRequests) {
+                // We have business to attend to -> Send Delta
                 const responseDeltaData: SyncSagaMessageDeltaData_V1 = {
                     sagaId: deltaData.sagaId,
                     stage: SyncStage.delta,
-                    proposeCommit: true,
-                    payloadAddrs: [], // Always include empty array if sending delta
+                    payloadAddrs: outgoingPayload.map(p => getIbGibAddr({ ibGib: p })),
+                    requests: hasMyRequests ? myRequests : undefined,
+                    proposeCommit: !hasMyRequests // If we are sending data but have no requests, we VALIDATE PROPOSAL?
+                    // Wait. If we send data, we are NOT committing yet.
+                    // We are sending data. The OTHER side must ingest it.
+                    // So proposeCommit = true?
+                    // "Here is the data. I'm done. If you are good, let's commit."
+                    // Yes.
                 };
 
+                // BUT if `peerProposesCommit` was true, and we are sending data, we are effectively rejecting/delaying it.
+                // We just send the Delta. Peer receives it, ingests, sees ProposeCommit=True (from us), and then Commits.
+
+                // So yes, proposeCommit = true.
+                responseDeltaData.proposeCommit = true;
+
                 const deltaStone = await this.createSyncMsgStone({
                     data: responseDeltaData,
-                    localSpace: tempSpace,
-                    metaspace
+                    localSpace: mySpace,
+                    metaspace,
                 });
 
                 const deltaFrame = await this.evolveSyncSagaIbGib({
                     prevSagaIbGib: sagaIbGib,
                     msgStones: [deltaStone],
                     sessionIdentity: identity,
-                    localSpace: tempSpace,
-                    metaspace
+                    localSpace: mySpace,
+                    metaspace,
                 });
 
-                // Check if PEER proposed commit
-                if (deltaData.proposeCommit) {
-                    if (logalot) { console.log(`${lc} Peer proposed commit. Accepting & Committing.`); }
-                    // Peer wants to commit and has no more requests.
-                    // We should Commit.
+                // Build control payloads: frame + its dependencies (msg stone, identity)
+                const payloadIbGibsControl: IbGib_V1[] = [deltaFrame, deltaStone];
+                if (identity) { payloadIbGibsControl.push(identity); }
+
+                // return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: outgoingPayload };
+                return { frame: deltaFrame, payloadIbGibsDomain: outgoingPayload };
+                // throw new Error(`not implemented (E: 2b38a8afb6d84efcee5ab51673387826)`);
 
+            } else {
+                // We have nothing to send.
+
+                if (peerProposesCommit) {
+                    // Peer is done. We are done. -> Commit.
                     const commitData: SyncSagaMessageCommitData_V1 = {
                         sagaId: deltaData.sagaId,
                         stage: SyncStage.commit,
@@ -1808,68 +1834,136 @@ export class SyncSagaCoordinator {
 
                     const commitStone = await this.createSyncMsgStone({
                         data: commitData,
-                        localSpace: tempSpace,
+                        localSpace: mySpace,
                         metaspace
                     });
 
                     const commitFrame = await this.evolveSyncSagaIbGib({
-                        prevSagaIbGib: deltaFrame, // Build on top of the Delta we just created/persisted
+                        prevSagaIbGib: sagaIbGib,
                         msgStones: [commitStone],
                         sessionIdentity: identity,
-                        localSpace: tempSpace,
+                        localSpace: mySpace,
                         metaspace
                     });
 
                     // Build control payloads for commit
-                    const commitCtrlPayloads2: IbGib_V1[] = [commitFrame, commitStone];
-                    if (identity) { commitCtrlPayloads2.push(identity); }
+                    const commitCtrlPayloads: IbGib_V1[] = [commitFrame, commitStone];
+                    if (identity) { commitCtrlPayloads.push(identity); }
 
-                    // return { frame: commitFrame, payloadIbGibsControl: commitCtrlPayloads2 };
-                    // return { frame: commitFrame, };
-                    throw new Error(`not implemented (E: 27514878585889e531ef21f1abbef826)`);
-                }
+                    return { frame: commitFrame, };
+
+                } else {
+                    // peer did NOT propose commit (maybe they just sent data/requests and didn't ready flag).
+                    // But we are empty.
+                    // So WE propose commit.
+                    const responseDeltaData: SyncSagaMessageDeltaData_V1 = {
+                        sagaId: deltaData.sagaId,
+                        stage: SyncStage.delta,
+                        proposeCommit: true,
+                    };
+
+                    const deltaStone = await this.createSyncMsgStone({
+                        data: responseDeltaData,
+                        localSpace: mySpace,
+                        metaspace
+                    });
+
+                    const deltaFrame = await this.evolveSyncSagaIbGib({
+                        prevSagaIbGib: sagaIbGib,
+                        msgStones: [deltaStone],
+                        sessionIdentity: identity,
+                        localSpace: mySpace,
+                        metaspace
+                    });
 
-                // Build control payloads for delta propose
-                const deltaCtrlPayloads: IbGib_V1[] = [deltaFrame, deltaStone];
-                if (identity) { deltaCtrlPayloads.push(identity); }
+                    // Check if PEER proposed commit
+                    if (deltaData.proposeCommit) {
+                        if (logalot) { console.log(`${lc} Peer proposed commit. Accepting & Committing.`); }
+                        // Peer wants to commit and has no more requests.
+                        // We should Commit.
+
+                        const commitData: SyncSagaMessageCommitData_V1 = {
+                            sagaId: deltaData.sagaId,
+                            stage: SyncStage.commit,
+                            success: true,
+                        };
+
+                        const commitStone = await this.createSyncMsgStone({
+                            data: commitData,
+                            localSpace: mySpace,
+                            metaspace
+                        });
+
+                        const commitFrame = await this.evolveSyncSagaIbGib({
+                            prevSagaIbGib: deltaFrame, // Build on top of the Delta we just created/persisted
+                            msgStones: [commitStone],
+                            sessionIdentity: identity,
+                            localSpace: mySpace,
+                            metaspace
+                        });
 
-                // return { frame: deltaFrame, payloadIbGibsControl: deltaCtrlPayloads };
-                // return { frame: deltaFrame, };
-                throw new Error(`not implemented (E: ff35584696b6fcb3ad6dd7c5cade2f26)`);
+                        // Build control payloads for commit
+                        const commitCtrlPayloads2: IbGib_V1[] = [commitFrame, commitStone];
+                        if (identity) { commitCtrlPayloads2.push(identity); }
+
+                        return { frame: commitFrame, };
+                    }
+
+                    // Build control payloads for delta propose
+                    const deltaCtrlPayloads: IbGib_V1[] = [deltaFrame, deltaStone];
+                    if (identity) { deltaCtrlPayloads.push(identity); }
+
+                    return { frame: deltaFrame, payloadIbGibsDomain: outgoingPayload };
+                }
             }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
         }
+
     }
 
 
     protected async handleCommitFrame({
         sagaIbGib,
-        destSpace,
-        tempSpace,
+        mySpace,
+        myTempSpace,
         metaspace,
         identity,
     }: {
         sagaIbGib: SyncIbGib_V1,
-        destSpace: IbGibSpaceAny,
-        tempSpace: IbGibSpaceAny,
+        mySpace: IbGibSpaceAny,
+        myTempSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,
         identity?: KeystoneIbGib_V1,
     }): Promise<NextSagaFrameInfo> {
         const lc = `${this.lc}[${this.handleCommitFrame.name}]`;
-        if (logalot) { console.log(`${lc} Commit received.`); }
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: e179573bdd881202f8ba3168da1c3826)`); }
+
+
 
-        // 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 null to signal saga completion.
+            // 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 null to signal saga completion.
 
-        // Note: Currently we don't have explicit cleanup logic implemented here yet (TODO).
+            // Note: Currently we don't have explicit cleanup logic implemented here yet (TODO).
+            if (logalot) { console.log(`${lc} Peer committed. Finalizing saga locally. Saga Complete.`); }
+
+            return { responseWasNull: true };
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
 
-        if (logalot) { console.log(`${lc} Peer committed. Finalizing saga locally. Saga Complete.`); }
-        // return { responseWasNull: true };
-        throw new Error(`not implemented (E: 4d7f878bcc45ad3dd9c4b8573f3aa826)`);
     }
 
     // #endregion Handlers
@@ -1923,6 +2017,10 @@ export class SyncSagaCoordinator {
         msgStones: IbGib_V1[],
         localSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,
+        /**
+         * does NOT evolve the keystone. this should be done by the caller.
+         * (NOT IMPLEMENTED YET ANYWAY)
+         */
         sessionIdentity?: KeystoneIbGib_V1,
     }): Promise<SyncIbGib_V1> {
         const lc = `${this.lc}[${this.evolveSyncSagaIbGib.name}]`;