@ibgib/core-gib 0.1.23 → 0.1.25

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

@@ -23,14 +23,18 @@ import { SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMA
 import { appendToTimeline, createTimeline, getHistory, Rel8nInfo, Rel8nRemovalInfo } from "../timeline/timeline-api.mjs";
 import {
     SyncData_V1, SyncIbGib_V1, SyncConflictStrategy, SyncMode, SyncOptions,
-    SyncRel8ns_V1, DomainIbGibAnalysisInfo, HandleSagaFrameResult,
+    SyncRel8ns_V1, DomainIbGibAnalysisInfo, NextSagaFrameInfo,
+    SYNC_CONFLICT_STRATEGY_VALID_VALUES,
+    HandleSagaResponseContextResult,
 } from "./sync-types.mjs";
 import { getSyncIb, getTempSpaceName, isPastFrame } from "./sync-helpers.mjs";
-import { getDependencyGraph, toFlatGraph } from "../common/other/graph-helper.mjs";
+import { getDeltaDependencyGraph, getDependencyGraph, toFlatGraph } from "../common/other/graph-helper.mjs";
 import {
     SyncSagaMessageData_V1, SyncSagaMessageInitData_V1,
     SyncSagaMessageAckData_V1, SyncSagaMessageDeltaData_V1,
     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";
 import { SYNC_SAGA_MSG_ATOM } from "./sync-saga-message/sync-saga-message-constants.mjs";
@@ -38,7 +42,7 @@ import { SyncSagaInfo } from "./sync-types.mjs";
 import { splitPerTjpAndOrDna, getTimelinesGroupedByTjp, isIbGib } from "../common/other/ibgib-helper.mjs";
 import { SyncPeerWitness } from "./sync-peer/sync-peer-types.mjs";
 import { SyncSagaContextIbGib_V1, } from "./sync-saga-context/sync-saga-context-types.mjs";
-import { createSyncSagaContext } from "./sync-saga-context/sync-saga-context-helpers.mjs";
+import { createSyncSagaContext, validateContextAndSagaFrame } from "./sync-saga-context/sync-saga-context-helpers.mjs";
 import { newupSubject, } from "../common/pubsub/subject/subject-helper.mjs";
 import { SubjectWitness } from "../common/pubsub/subject/subject-types.mjs";
 import { mergeDivergentTimelines } from "./strategies/conflict-optimistic.mjs";
@@ -58,14 +62,14 @@ const lcControlDomain = '[ControlDomain]';
 
 /**
  * Orchestrates the synchronization process between two spaces (Source and Destination).
- * 
+ *
  * ## Execution Contexts
- * 
+ *
  * The methods in this class are designed to be run on specific nodes in the sync topology:
- * 
+ *
  * *   **Sender/Local Node**: The node *initiating* the sync (calling `sync()`).
  * *   **Receiver/Remote Node**: The node *accepting* the sync request (the Peer).
- * 
+ *
  * Note that in a peer-to-peer architecture, "Sender" and "Receiver" are roles relative
  * to a specific Saga session, not fixed node identities.
  */
@@ -80,11 +84,11 @@ export class SyncSagaCoordinator {
 
     /**
      * Executes a synchronization saga using the Symmetric Sync Protocol.
-     * 
+     *
      * @remarks
      * **Execution Context**: **Sender (Local)**.
      * This method is the entry point for starting a sync session.
-     * 
+     *
      * @param opts.peer - The remote peer witness to communicate with.
      * @param opts.localSpace - The local space that will be read from and written to.
      * @param opts.metaspace - Service for creating temp spaces and managing ibgibs.
@@ -140,14 +144,14 @@ export class SyncSagaCoordinator {
         (async () => {
             try {
 
-                // 2. BOOTSTRAP IDENTITY (Session Keystone)
+                // BOOTSTRAP IDENTITY (Session Keystone)
                 const sessionIdentity = useSessionIdentity
                     ? await this.getSessionIdentity({ sagaId, metaspace, tempSpace })
                     : undefined;
                 // if (logalot) { console.log(`${lc} sessionIdentity: ${sessionIdentity ? pretty(sessionIdentity) : 'undefined'} (I: abc01872800b3a66b819a05898bba826)`); }
 
-                // 3. CREATE INITIAL FRAME (Stage.init)
-                const { sagaFrame: initFrame, initialDomainGraph } = await this.createInitFrame({
+                // CREATE INITIAL FRAME (Stage.init)
+                const { initFrame, initDomainGraph } = await this.createInitFrame({
                     sagaId,
                     sessionIdentity,
                     domainIbGibs,
@@ -155,17 +159,16 @@ export class SyncSagaCoordinator {
                     metaspace, localSpace, tempSpace,
                 });
 
-                // 4. KICK OFF THE PING-PONG SAGA LOOP (FSM)
-                // commented to compile
-                // await this.executeSagaLoop({
-                //     initialFrame: initFrame,
-                //     peer,
-                //     sessionIdentity,
-                //     updates$,
-                //     localSpace,
-                //     tempSpace,
-                //     metaspace
-                // });
+                // KICK OFF THE PING-PONG SAGA LOOP (FSM)
+                await this.executeSagaLoop({
+                    initFrame, initDomainGraph,
+                    peer,
+                    sessionIdentity,
+                    updates$,
+                    localSpace,
+                    tempSpace,
+                    metaspace
+                });
 
                 resolveDone();
                 if (!updates$.complete) { throw new Error(`(UNEXPECTED) updates$.complete falsy? (E: d24cd82184aec130c89a320819b39126)`); }
@@ -226,13 +229,13 @@ export class SyncSagaCoordinator {
 
     /**
      * Drives the FSM loop of the Saga.
-     * 
+     *
      * @remarks
      * **Execution Context**: **Sender (Local)**.
-     * 
+     *
      * This method manages the "Ping Pong" request-response cycle on the Sender.
      * It sends frames via the Peer Witness and processes the responses using `handleSagaResponseContext`.
-     * 
+     *
      * **Data Transport Note**:
      * Actual ibGib data (payloads) are transported via `SyncSagaContext.rel8ns.payload`.
      * When `handleSagaResponseContext` returns a `nextPayloadIbGibs` (data to send), this loop injects it into
@@ -240,8 +243,8 @@ export class SyncSagaCoordinator {
      * When the Peer responds with data (in the response context), it is resolved and put into `tempSpace`.
      */
     protected async executeSagaLoop({
-        initialFrame,
-        initialDomainGraph,
+        initFrame,
+        initDomainGraph,
         peer,
         sessionIdentity,
         updates$,
@@ -249,8 +252,8 @@ export class SyncSagaCoordinator {
         tempSpace,
         metaspace
     }: {
-        initialFrame: SyncIbGib_V1,
-        initialDomainGraph: FlatIbGibGraph,
+        initFrame: SyncIbGib_V1,
+        initDomainGraph: FlatIbGibGraph,
         peer: SyncPeerWitness,
         sessionIdentity?: KeystoneIbGib_V1,
         updates$: SubjectWitness<SyncSagaContextIbGib_V1>,
@@ -260,44 +263,23 @@ export class SyncSagaCoordinator {
     }): Promise<void> {
         const lc = `${this.lc}[${this.executeSagaLoop.name}]`;
 
-        // The current frame we just generated (e.g., Init or Delta Request)
-        let currentFrame: SyncIbGib_V1 | null = initialFrame;
-        // The payload we need to attach to the message (data we are sending)
+        /** The current frame we just generated (e.g., Init or Delta Request) */
+        let currentFrame: SyncIbGib_V1 | null = initFrame;
+        /** The **domain** payload we need to transmit (data we are sending) */
         let nextDomainIbGibs: IbGib_V1[] = [];
 
-        // First, inject local/tempSpace into peer so it can pull as
-        // needed...code smell?
-        peer.senderSpace = localSpace;
-        peer.senderTempSpace = tempSpace;
-
         while (currentFrame) {
-            // A. Create Context (Request)
-            // 1. Calculate Full Dependency Graph (including Ancestors/DNA)
-            // We must do this BEFORE creating the Context so we can list them
-            // all in payloadAddrsDomain and payloadAddrsControl.
-            const nextDomainIbGibsAndDeps: IbGib_V1[] = [];
-
-            // A. Payload (Standard Deep Deps)
-            // TODO: THIS IS EXTREMELY INEFFICIENT. adjust this algorithm to
-            // only do the dependencies that the other end doesn't need (diff
-            // between tip and LCA). This can be done using the information in
-            // the ack's conflicts array.
-            for (const nextDomainIbGib of nextDomainIbGibs) {
-                let nextDomainIbGibGraph = await getDependencyGraph({ ibGib: nextDomainIbGib, space: localSpace });
-                if (!nextDomainIbGibGraph) {
-                    nextDomainIbGibGraph = await getDependencyGraph({ ibGib: nextDomainIbGib, space: tempSpace });
-                }
-                if (nextDomainIbGibGraph) {
-                    nextDomainIbGibsAndDeps.push(...Object.values(nextDomainIbGibGraph));
-                } else {
-                    throw new Error(`(UNEXPECTED) we couldn't get the graph for a known domain ibgib? nextDomainIbGib addr: ${getIbGibAddr({ ibGib: nextDomainIbGib })} (E: 01b3e4db8768b5b77db72e486f4f7826)`);
-                }
-            }
-            if (logalot) { console.log(`${lc} payloadIbGibsDomain count: ${nextDomainIbGibsAndDeps.length} (I: 2beda8ca7dc5ac0f48ed9e25e704b826)`); }
+            // first, prepare for context transmission...
 
-            // 2. Create Context (Envelope)
-            // set up subscription for response's payload ibgibs (if any)
+            /**
+             * this is used later in pollForDomainPayloads **iif** payloads are
+             * received **in the response**, i.e., on the return trip. So if we
+             * request addrs, the response should have these addrs and their
+             * dependencies. The ibgibs corresponding to these addrs will be
+             * streamed and placed into this map.
+             */
             const domainPayloadsMap = new Map<string, IbGib_V1>();
+            // #region set up peer observable for any domainPayloadsMap
             const sublc = `${lc}[peer.payloadIbGibsDomainReceived$]`;
             const subscription = await peer.payloadIbGibsDomainReceived$.subscribe(fnObs({
                 next: async (ibgib: IbGib_V1) => {
@@ -319,43 +301,49 @@ export class SyncSagaCoordinator {
                     await subscription.unsubscribe();
                 },
             }));
+            // #endregion set up peer observable for any domainPayloadsMap
 
-            // Create the Request Context...
+            // ...create/compose the Request Context itself...
             const requestCtx = await createSyncSagaContext({
                 sagaFrame: currentFrame,
                 sessionKeystones: sessionIdentity ? [sessionIdentity] : undefined,
-
                 /**
                  * init frame: empty
-                 * 
+                 * ack frame: possible push offers
+                 * delta frame: requested ibgibs or commit offer
+                 * commit frame: empty
                  */
-                payloadIbGibsDomain: nextDomainIbGibsAndDeps,
+                payloadIbGibsDomain: nextDomainIbGibs,
                 localSpace,
             });
 
-            // Log what we're sending
+            // #region Log what we're sending
             if (logalotControlDomain) {
-                const domainAddrs = nextDomainIbGibsAndDeps.map(p => getIbGibAddr({ ibGib: p }));
-                console.log(`${lc}${lcControlDomain} SENDER TRANSMIT -> peer.witness (I: b3c4d5e6f7a8b9c0)`);
+                const domainAddrs = nextDomainIbGibs.map(p => getIbGibAddr({ ibGib: p }));
+                console.log(`${lc}${lcControlDomain} SENDER TRANSMIT -> peer.witness (I: 5b0081803698770f0bf64992220b312)`);
                 console.log(`${lc}${lcControlDomain}   Context: ${getIbGibAddr({ ibGib: requestCtx })}`);
                 console.log(`${lc}${lcControlDomain}   Frame: ${getIbGibAddr({ ibGib: currentFrame })}`);
                 console.log(`${lc}${lcControlDomain}   DOMAIN Payloads (${domainAddrs.length}): ${domainAddrs.join(', ') || '(none)'}`);
             }
+            // #endregion Log what we're sending
 
             // update our saga listeners...
             // if (logalot) { console.log(`${lc} transmitting... requestCtx: ${pretty(requestCtx)} (I: 8cf20817c66899abdb1e76df50356826)`); }
-            updates$.next(requestCtx); // spins off 
+            updates$.next(requestCtx); // spins off for saga UI updates
 
-            // ...And send the context
+            // ...And send the context.
+            peer.setOptionalOpts({ senderSpace: localSpace, senderTempSpace: tempSpace, });
             const responseCtx = await peer.witness(requestCtx);
 
-            // C. Handle Response
+            // the send returned, but a peer can return a falsy responseCtx, if
+            // we just sent a commit to them and they're done. If so, there will
+            // necessarily be no payload to wait to receive
             if (!responseCtx) {
                 if (currentFrame) {
                     // Check for Commit (Peer silence expected)
                     const msg = await getSyncSagaMessageFromFrame({ frameIbGib: currentFrame, space: localSpace });
                     if (msg?.data?.stage === SyncStage.commit) {
-                        if (logalot) { console.log(`${lc} Sender sent Commit. Peer returned no response. Saga Complete.`); }
+                        if (logalot) { console.log(`${lc} Sender sent Commit. Peer returned no response. Saga Complete. (I: 26f9ee073858ca78b8284753368b5226)`); }
                         currentFrame = null;
                         break;
                     } else {
@@ -366,19 +354,21 @@ export class SyncSagaCoordinator {
                 }
             }
 
-            // ---------------------------------------------------------------------
-            // 2d. HANDLE RESPONSE
-            // ---------------------------------------------------------------------
-            // at this point, we have received the response context ibgib, but
+            // at this point, we did indeed receive a response to analyze. BUT!
+            // we have only necessarily received the response context ibgib.
             // if there were payloads expected to be transferred, they may not
             // be done yet.
+
             if (!responseCtx.data) { throw new Error(`(UNEXPECTED) responseCtx.data falsy? (E: a969992bae53ab18a827ec58aec15826)`); }
-            updates$.next(responseCtx); // spins off -- don't remove this comment!
+            updates$.next(responseCtx); // spins off for saga UI updating
+
+            // validate context
+            await validateContextAndSagaFrame
 
             // Extract expected domain addresses from response context
             const responsePayloadAddrsDomain = responseCtx.data[SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN] as string[] || [];
 
-            // Poll for them if needed
+            // Poll for them if needed. see above jsdocs for domainPayloadsMap
             if (responsePayloadAddrsDomain.length > 0) {
                 responseCtx.payloadIbGibsDomain = await this.pollForDomainPayloads({
                     expectedAddrs: responsePayloadAddrsDomain,
@@ -388,51 +378,61 @@ export class SyncSagaCoordinator {
                 });
             }
 
-            // at this point, we have received the context AND **all** of the
-            // domain payloads (if applicable), so we are ready to do the next 
-            // iteration in the saga loop
-
-            // Log what we received back
+            // #region Log what we received back
             if (!responseCtx.sagaFrame) { throw new Error(`(UNEXPECTED) responseCtx.sagaFrame falsy? the Peer should have set this when it got the response back from the remote. (E: e650adadf9a2063ec6764a1e31d3d826)`); }
             if (logalotControlDomain) {
                 const responseControlAddrs = responseCtx.data?.['@payloadAddrsControl'] as string[] || [];
-                console.log(`${lc}${lcControlDomain} SENDER RECEIVED <- peer.witness (I: c4d5e6f7a8b9c0d1)`);
+                console.log(`${lc}${lcControlDomain} SENDER RECEIVED <- peer.witness (I: 3dc76a9744d89a4fc3e2f076c2be4826)`);
                 console.log(`${lc}${lcControlDomain}   Response Context: ${getIbGibAddr({ ibGib: responseCtx })}`);
                 console.log(`${lc}${lcControlDomain}   Response Saga Frame: ${getIbGibAddr({ ibGib: responseCtx.sagaFrame })}`);
                 console.log(`${lc}${lcControlDomain}   CONTROL Payloads (${responseControlAddrs.length}): ${responseControlAddrs.join(', ') || '(none)'}`);
                 console.log(`${lc}${lcControlDomain}   DOMAIN Payloads (${responsePayloadAddrsDomain.length}): ${responsePayloadAddrsDomain.join(', ') || '(none)'}`);
             }
+            // #endregion Log what we received back
 
-            // Handle Response Frame
-            // interface HandleSagaFrameResult {
-            //     frame: SyncIbGib_V1;
-            //     payloadIbGibsDomain?: IbGib_V1[];
-            //     conflictInfos?: SyncSagaConflictInfo;
-            // }
-            const handleResult = await this.handleSagaContext({
+            // at this point, we have received the context AND **all** of the
+            // domain payloads (if applicable), so we are ready to do the next
+            // iteration in the saga loop
+
+            // this is the part that drives the FSM forward, i.e., when we
+            // evolve the sync saga ibgib itself to the next frame if we aren't
+            // finished/errored out.
+            const contextResult = await this.handleResponseSagaContext({
                 sagaContext: responseCtx,
                 mySpace: localSpace,
                 myTempSpace: tempSpace,
                 metaspace,
             });
 
-            if (!handleResult) {
-                if (logalot) { console.log(`${lc} Handler returned null (Saga End).`); }
+            if (!contextResult) {
+                if (logalot) { console.log(`${lc} Handler returned null (Saga End). (I: faae22abc818ba9b28ac6d2881cd7826)`); }
                 break;
             }
 
-            currentFrame = handleResult.frame;
+            // #region error conditions throw
+            if (contextResult.errorMsg) {
+                throw new Error(`Couldn't handle response saga context. errorMsg: ${contextResult.errorMsg} (E: c948e81d513b2a0eb8b8afa878edc626)`);
+            } else if (!contextResult.nextFrameInfo) {
+                throw new Error(`(UNEXPECTED) contextResult.nextFrameInfo falsy? (E: c287a82e823e662a77923278e2418826)`);
+            } else if (contextResult.nextFrameInfo?.responseWasNull) {
+                throw new Error(`(UNEXPECTED) contextResult.nextFrameInfo.responseWasNull? logic flow should not have gotten here. (E: 104a32381db816b7183435e805b3d626)`);
+            }
+            // #endregion error conditions throw
 
-            // Collect next DOMAIN payloads for the NEXT request
-            nextDomainIbGibs = [...(handleResult.payloadIbGibsDomain || [])];
+            // we have another frame to process and send out, with possibly
+            // payload domain ibgibs as well
+            const { frame, payloadIbGibsDomain, } = contextResult.nextFrameInfo;
+            currentFrame = frame;
+            nextDomainIbGibs = [...(payloadIbGibsDomain || [])];
 
-            // Log handler output for next iteration
+            // #region Log handler output for next iteration
             if (logalotControlDomain) {
                 const handlerDomainAddrs = nextDomainIbGibs.map(p => getIbGibAddr({ ibGib: p }));
-                console.log(`${lc}${lcControlDomain} HANDLER RESULT -> next iteration (I: d5e6f7a8b9c0d1e2)`);
+                console.log(`${lc}${lcControlDomain} HANDLER RESULT -> next iteration (I: 6b0d88c4c28857ccd812381515bd7826)`);
                 console.log(`${lc}${lcControlDomain}   Next Frame: ${getIbGibAddr({ ibGib: currentFrame })}`);
                 console.log(`${lc}${lcControlDomain}   DOMAIN for next (${handlerDomainAddrs.length}): ${handlerDomainAddrs.join(', ') || '(none)'}`);
             }
+            // #endregion Log handler output for next iteration
         }
     }
 
@@ -499,7 +499,7 @@ export class SyncSagaCoordinator {
 
             const res = await getLatestAddrs({ space, tjpAddrs: tjps });
             if (!res.data || !res.data.latestAddrsMap) {
-                throw new Error(`${lc} Failed to get latest addrs. (E: 7a8b9c0d)`);
+                throw new Error(`${lc} Failed to get latest addrs. (E: 7d395940c0e1419165c5196c39c6c826)`);
             }
 
             // if (false) { console.log(`${lc}[TEST DEBUG] res.data.latestAddrsMap: ${JSON.stringify(res.data.latestAddrsMap)} (I: a8e128bdf80898ac2e6d8021a5bff726)`); }
@@ -552,10 +552,10 @@ export class SyncSagaCoordinator {
 
     /**
      * Creates the Initial Saga Frame (Init Stage).
-     * 
+     *
      * @remarks
      * **Execution Context**: **Sender (Local)**.
-     * 
+     *
      * Generates the first frame containing the Knowledge Vector of the Local Space.
      * This is sent to the Receiver to begin Gap Analysis.
      */
@@ -575,14 +575,14 @@ export class SyncSagaCoordinator {
         metaspace: MetaspaceService,
         localSpace: IbGibSpaceAny,
         tempSpace: IbGibSpaceAny,
-    }): Promise<{ sagaFrame: SyncIbGib_V1, initialDomainGraph: { [addr: string]: IbGib_V1 } }> {
+    }): Promise<{ initFrame: SyncIbGib_V1, initDomainGraph: { [addr: string]: IbGib_V1 } }> {
         const lc = `${this.lc}[${this.createInitFrame.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting... (I: 551af8b411ae9be712ce3358d43ee726)`); }
 
             // Analyze Timelines & Stones
             const analysis = await this.analyzeDomainIbGibs({ domainIbGibs, space: localSpace });
-            // if (logalot) { console.log(`${lc} analysis: ${pretty(analysis)}(I: cd00e2be5eccc8976879c888ff2dfb26)`); } 
+            // if (logalot) { console.log(`${lc} analysis: ${pretty(analysis)}(I: cd00e2be5eccc8976879c888ff2dfb26)`); }
             const { timelinesMap: srcTimelinesMap, fullGraph, stones: srcStones, } = analysis;
 
             // we need to store the fullGraph in our tempSpace for later...
@@ -627,7 +627,7 @@ export class SyncSagaCoordinator {
 
             // if (logalot) { console.log(`${lc} sagaFrame (init): ${pretty(sagaFrame)} (I: b3d6a8be69248f18713cc3073cb08626)`); }
 
-            return { sagaFrame, initialDomainGraph: fullGraph };
+            return { initFrame: sagaFrame, initDomainGraph: fullGraph };
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;
@@ -639,7 +639,7 @@ export class SyncSagaCoordinator {
     /**
      * Helper to poll for streaming domain payloads and put them in the
      * local {@link tempSpace}.
-     * 
+     *
      * @returns when all {@link expectedAddrs} are done being transmitted.
      */
     protected async pollForDomainPayloads({
@@ -662,7 +662,7 @@ export class SyncSagaCoordinator {
             let pending = [...expectedAddrs];
             const start = Date.now();
             /**
-             * This needs 
+             * This needs
              */
             const timeoutMs = 5 * 60 * 1000; // 5 minutes...arbitrary at this point. This needs to be pulled out and improved eesh.
 
@@ -710,23 +710,23 @@ 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.
-     * 
+     *
      * This is called in two places:
-     * 
+     *
      * ## 1. Sender
-     * 
+     *
      * On the sender, this is called within the {@link executeSagaLoop} which
-     * initiates and drives the sync. 
-     * 
+     * initiates and drives the sync.
+     *
      * ## 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 
+     * endpoint's job is basically to get these things collocated and prepared
      * to make this call.
-     * 
+     *
      * This is a one-off on the receiver.
      */
-    public async handleSagaContext({
+    public async handleResponseSagaContext({
         sagaContext,
         mySpace,
         myTempSpace,
@@ -746,8 +746,8 @@ export class SyncSagaCoordinator {
         identity?: KeystoneIbGib_V1,
         identitySecret?: string,
         metaspace: MetaspaceService,
-    }): Promise<HandleSagaFrameResult | null> {
-        const lc = `${this.lc}[${this.handleSagaContext.name}]`;
+    }): Promise<HandleSagaResponseContextResult | null> {
+        const lc = `${this.lc}[${this.handleResponseSagaContext.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting... (I: 5deec8a1f7a6d263c88cd458ad990826)`); }
 
@@ -765,9 +765,10 @@ export class SyncSagaCoordinator {
              */
             const srcGraph = toFlatGraph({ ibGibs: sagaContext.payloadIbGibsDomain }) ?? {};
 
+            let nextFrameInfo: NextSagaFrameInfo;
             switch (stage) {
                 case SyncStage.init:
-                    return await this.handleInitFrame({
+                    nextFrameInfo = await this.handleInitFrame({
                         sagaIbGib,
                         messageData: messageData as SyncSagaMessageInitData_V1,
                         metaspace,
@@ -776,22 +777,30 @@ export class SyncSagaCoordinator {
                         identity,
                         identitySecret
                     });
+                    break;
 
                 case SyncStage.ack:
-                    return await this.handleAckFrame({ sagaIbGib, srcGraph, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity });
+                    nextFrameInfo = await this.handleAckFrame({ sagaIbGib, srcGraph, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity });
+                    break;
 
                 case SyncStage.delta:
-                    return await this.handleDeltaFrame({ sagaIbGib, srcGraph, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity, });
+                    nextFrameInfo = await this.handleDeltaFrame({ sagaIbGib, srcGraph, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity, });
+                    break;
 
                 case SyncStage.commit:
-                    return await this.handleCommitFrame({ sagaIbGib, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity, });
+                    nextFrameInfo = await this.handleCommitFrame({ sagaIbGib, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity, });
+                    break;
 
                 default:
                     throw new Error(`${lc} (UNEXPECTED) Unknown sync stage: ${stage} (E: 9c2b4c8a6d34469f8263544710183355)`);
             }
+
+            return { errorMsg: undefined, nextFrameInfo, }
+
         } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
+            const errorMsg = `${lc} ${extractErrorMsg(error)}`;
+            console.error(errorMsg);
+            return { errorMsg }
         } finally {
             if (logalot) { console.log(`${lc} complete.`); }
         }
@@ -801,10 +810,10 @@ export class SyncSagaCoordinator {
 
     /**
      * Handles the `Init` frame.
-     * 
+     *
      * @remarks
      * **Execution Context**: **Receiver (Remote)**.
-     * 
+     *
      * 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`).
@@ -828,7 +837,7 @@ export class SyncSagaCoordinator {
         mySpace: IbGibSpaceAny,
         /**
          * Local temp space relative to the execution context's POV.
-         * 
+         *
          * NOTE: Since this always executes on the receiver's end, this should
          * be the receiver's temp space.
          */
@@ -836,18 +845,17 @@ export class SyncSagaCoordinator {
         metaspace: MetaspaceService,
         identity?: KeystoneIbGib_V1,
         identitySecret?: string,
-    }): Promise<HandleSagaFrameResult | null> {
+    }): Promise<NextSagaFrameInfo> {
         const lc = `${this.lc}[${this.handleInitFrame.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting... (I: 9d88dcad0408c029e898a4bcf3b08426)`); }
 
-            console.log(`${lc} [TEST DEBUG] Received destSpace: ${mySpace.data?.name || mySpace.ib} (uuid: ${mySpace.data?.uuid || '[no uuid]'})`);
-            if (logalot) { console.log(`${lc} starting...`); }
+            console.log(`${lc} [TEST DEBUG] Receiver mySpace: ${mySpace.ib}`);
 
             // Extract Init Data
             const initData = messageData as SyncSagaMessageInitData_V1; // Using renamed variable for clarity
             if (initData.stage !== SyncStage.init) {
-                throw new Error(`${lc} Invalid init frame: initData.stage !== SyncStage.init (E: 8a2b3c4d5e6f7g8h)`);
+                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) {
@@ -859,8 +867,8 @@ export class SyncSagaCoordinator {
 
             // 2. Gap Analysis
             const conflicts: SyncSagaConflictInfo[] = [];
-            const deltaReqAddrs: string[] = [];
-            const pushOfferAddrs: string[] = [];
+            const deltaRequestAddrInfos: SyncSagaRequestAddrInfo[] = [];
+            const pushOfferInfos: SyncSagaPushOfferInfo[] = [];
 
             // First do the consant stones (Non-TJPs)
             const stones = initData.stones || [];
@@ -874,13 +882,15 @@ export class SyncSagaCoordinator {
                 if (addrsNotFound && addrsNotFound.length > 0) {
                     if (logalot) { console.log(`${lc} stones missing (requesting): ${addrsNotFound.length}`); }
                     addrsNotFound.forEach(addr => {
-                        if (!deltaReqAddrs.includes(addr)) { deltaReqAddrs.push(addr); }
+                        if (!deltaRequestAddrInfos.some(x => x.addr === addr)) {
+                            deltaRequestAddrInfos.push({ addr }); // no tjpAddr
+                        }
                     });
                 }
             }
 
             /**
-             * "remote" local to receiver's context is the sender
+             * "remote" is sender in this case
              */
             const remoteKV = initData.knowledgeVector;
             if (logalot) { console.log(`${lc} remoteKV: ${pretty(remoteKV)} (I: 9f957862356dfeae183c200854e86e26)`); }
@@ -889,7 +899,7 @@ export class SyncSagaCoordinator {
             if (logalot) { console.log(`${lc} remoteTjps: ${pretty(remoteTjps)} (I: 86ea4c53db0dc184c8b253386c402126)`); }
 
             // 1. Get Local Latest Addrs for all TJPs
-            let localKV: { [tjp: string]: string | null } = {};
+            let localLatestAddrsMap: { [tjp: string]: string | null } = {};
             if (remoteTjps.length > 0) {
                 // Batch get latest addrs for the TJPs
                 const resGetLatestAddrs = await getLatestAddrs({
@@ -898,56 +908,91 @@ export class SyncSagaCoordinator {
                 });
                 if (!resGetLatestAddrs.data) { throw new Error(`(UNEXPECTED) resGetLatestAddrs.data falsy? (E: b180d813c088042b38e1e02e06a16926)`); }
                 if (!resGetLatestAddrs.data.latestAddrsMap) { throw new Error(`(UNEXPECTED) resGetLatestAddrs.data.latestAddrsMap falsy? (E: 16bc386dd51d0ff53a49620b1e641826)`); }
-                localKV = resGetLatestAddrs.data.latestAddrsMap;
-                console.log(`${lc} [TEST DEBUG] localKV: ${JSON.stringify(localKV)}`);
-                if (logalot) { console.log(`${lc} localKV: ${pretty(localKV)} (I: 980975642cbccd8018cf0cd808d30826)`); }
+                localLatestAddrsMap = resGetLatestAddrs.data.latestAddrsMap;
+                console.log(`${lc} [TEST DEBUG] localKV: ${JSON.stringify(localLatestAddrsMap)}`);
+                if (logalot) { console.log(`${lc} localKV: ${pretty(localLatestAddrsMap)} (I: 980975642cbccd8018cf0cd808d30826)`); }
             }
 
             // 2. Gap Analysis
             for (const tjp of remoteTjps) {
                 const remoteAddr = remoteKV[tjp];
-                const localAddr = localKV[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}`);
-                    deltaReqAddrs.push(remoteAddr);
+                    deltaRequestAddrInfos.push({
+                        addr: remoteAddr,
+                        tjpAddr: tjp,
+                        // we don't have this timeline at all
+                        // latestAddrAlreadyHave: undefined
+                    });
                     continue;
                 }
 
+                // we do have this timeline...
+
                 if (localAddr === remoteAddr) {
-                    // Synced
+                    // ...already synced
                     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...`);
 
-                // Check if Remote is in Local's PAST (Local is Ahead -> Push Offer)
-                // (Sender has older version, Receiver has newer) -> Receiver Offers Push
-                const isRemoteInPast = await isPastFrame({
+                // 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
+                // to remote
+                const remoteIsInPast = await isPastFrame({
                     olderAddr: remoteAddr,
                     newerAddr: localAddr,
                     space: mySpace,
                 });
 
-                if (isRemoteInPast) {
-                    console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Remote is in past - offering push`);
-                    pushOfferAddrs.push(localAddr);
+                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`);
+                    const deltaGraph = await getDeltaDependencyGraph({
+                        ibGibAddr: localAddr,
+                        live: false, // always live: false right?
+                        latestCommonFrameAddr: remoteAddr,
+                        space: mySpace,
+                    });
+                    pushOfferInfos.push({ tjpAddr: tjp, addrs: Object.keys(deltaGraph), });
                 } else {
-                    // Remote is not in our past. 
-                    // Either Remote is ahead (Fast-Backward) OR Diverged.
+                    // Remote tip is not in our past.  So, either Remote is
+                    // ahead (we're in THEIR past, i.e., Fast-Backward) OR
+                    // Diverged/conflict (we've both made edits).
 
                     // Check if Local is in Remote's PAST (Remote is Ahead -> Delta Request)
-                    const isLocalInPast = await isPastFrame({
-                        olderAddr: localAddr,
-                        newerAddr: remoteAddr,
-                        space: mySpace,
-                    });
+                    /**
+                     * we could first check for existence of remoteAddr in
+                     * mySpace, but this is quick and easy. If it throws, we
+                     * don't have it so it can't be in the past.
+                     */
+                    let localIsInPast = false;
+                    try {
+                        // we could
+                        localIsInPast = await isPastFrame({
+                            olderAddr: localAddr,
+                            newerAddr: remoteAddr,
+                            space: mySpace,
+                        });
+                    } catch (error) {
+                        // couldn't get one of them, so localIsInPast remains false.
+                        if (logalot) { console.log(`${lc} expected error if we don't have remote. verbose logging error though: ${extractErrorMsg(error)} (I: 47ea08d0b418cf4aa8a502a7bcb80826)`); }
+                    }
 
-                    if (isLocalInPast) {
+                    if (localIsInPast) {
                         // Fast-Forward: We update to remote's tip.
                         console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Local is in past - requesting delta`);
-                        deltaReqAddrs.push(remoteAddr);
+                        deltaRequestAddrInfos.push({
+                            addr: remoteAddr,
+                            tjpAddr: tjp,
+                            latestAddrAlreadyHave: localAddr,
+                        });
                     } else {
                         // DIVERGENCE: Both have changes the other doesn't know about.
                         console.log(`${lc} [TEST DEBUG] TJP ${tjp}: DIVERGENCE DETECTED! conflictStrategy=${conflictStrategy}`);
@@ -966,7 +1011,7 @@ export class SyncSagaCoordinator {
                                 terminal: true
                             });
                         } else if (conflictStrategy === 'optimistic') {
-                            // Optimistic: We want to resolving this.
+                            // Optimistic: We want resolve this.
                             // We need to send our history to the Sender so they can Merge.
 
                             // Fetch Full History for Local Timeline
@@ -979,10 +1024,10 @@ export class SyncSagaCoordinator {
                             // 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: ff06ff849fa8e8dba32ce09807411226)`);
+                                throw new Error(`couldn't get local tip (${localAddr}) from space (${mySpace.ib}) (E: 83cb88a767e22bbda99c6788bec50526)`);
                             }
                             const localTip = resLocalTip.ibGibs[0];
-                            if (!localTip) { throw new Error(`${lc} Failed to load local tip for conflict resolution. (E: 8f9b2c3d4e5f6g7h)`); }
+                            if (!localTip) { throw new Error(`${lc} Failed to load local tip for conflict resolution. (E: c39448ad6b3a72af78339ad877a56826)`); }
 
                             const timelineAddrs = [...(localTip.rel8ns?.past ?? []), localAddr];
 
@@ -994,9 +1039,8 @@ export class SyncSagaCoordinator {
                                 reason: 'divergence',
                                 terminal: false
                             });
-
                         } else {
-                            throw new Error(`${lc} Unsupported conflict strategy: ${conflictStrategy} (E: 2a9b3c4d5e6f7g8h9i0j)`);
+                            throw new Error(`${lc} Unsupported conflict strategy: ${conflictStrategy}. Only these currently implemented: ${SYNC_CONFLICT_STRATEGY_VALID_VALUES} (E: 8f12384180f8a718a983a749fe0adf26)`);
                         }
                     }
                 }
@@ -1012,57 +1056,15 @@ export class SyncSagaCoordinator {
                 throw new Error(`the saga has terminal conflicts. conflicts: ${JSON.stringify(conflicts)} (E: f2edbe93cc07a63b38bfc013d2213b26)`);
             }
 
-            // 3. Build Knowledge Vector (Full History for known timelines)
-            // [NEW] Smart Diff
-            // We iterate over all relevant addresses (deltas we are requesting OR push offers we might have newer versions of).
-            // Since we are "reacting" to Init, we primarily want to tell the Sender what we DO have for the things they talked about.
-
-            /**
-             * we will put this in {@link SyncSagaMessageAckData_V1.knowledgeVector}
-             */
-            const knowledgeVector: { [groupKey: string]: string[] } = {};
-
-            // [Smart Diff] Populate knowledge from timelines identified by Sender
-            for (const tjp of remoteTjps) {
-                const localAddr = localKV[tjp];
-                if (localAddr) {
-                    const res = await getFromSpace({ addr: localAddr, space: mySpace });
-                    if (res.success && res.ibGibs?.[0]) {
-                        const ibGib = res.ibGibs[0];
-                        const realTjp = ibGib.rel8ns?.tjp?.[0] || getIbGibAddr({ ibGib }); // Should match `tjp` if normalized 
-                        if (!knowledgeVector[realTjp]) {
-                            const past = ibGib.rel8ns?.past || [];
-                            knowledgeVector[realTjp] = [getIbGibAddr({ ibGib }), ...past];
-                        }
-                    }
-                }
-            }
-
-            // Also populate from `knowledgeVector` in Init if we want bidirectional? 
-            // No, `Init` doesn't have `knowledgeVector` in `SyncSagaMessageInitData` yet (it has `SyncInitData` generic props).
-            // Let's assume standard flow:
-            // 1. Sender says "I have X"
-            // 2. Receiver says "I don't have X. But if I did have Y (ancestor), I'd tell you." 
-            // Problem: Receiver doesn't know X is related to Y without X.
-
-            // SOLUTION:
-            // The *Sender* must include TJP mappings or we rely on `knowledgeVector` in `Init`?
-            // `SyncSagaMessageInitData_V1` extends `SyncInitData`.
-            // `SyncInitData` has `knowledgeVector`.
-            // If Sender populates `knowledgeVector` in `Init`, Receiver can use keys (TJPs) to look up its own state!
-
-            // Let's implement Sender populating `Init.knowledgeVector`.
-            // But `SyncSagaCoordinator.startSaga` creates Init.
-
             // 3. Create Ack Frame
-            const sagaId = sagaIbGib.data!.uuid;
+            if (!sagaIbGib.data) { throw new Error(`(UNEXPECTED) sagaIbGib.data falsy? (E: 24203af4600fb226ae6c1afbde442826)`); }
+            const sagaId = sagaIbGib.data.uuid;
             // Create Payload Stone
             const ackData: SyncSagaMessageAckData_V1 = {
                 sagaId,
                 stage: SyncStage.ack,
-                deltaReqAddrs,
-                pushOfferAddrs,
-                knowledgeVector,
+                deltaRequestAddrInfos,
+                pushOfferInfos,
             };
             if (conflicts?.length > 0) { ackData.conflicts = conflicts; }
 
@@ -1090,14 +1092,63 @@ export class SyncSagaCoordinator {
              */
             // let payloadIbGibsDomain: IbGib_V1[] | undefined = await getPushOffers
 
-            if (pushOfferAddrs.length > 0) {
+            let payloadIbGibsDomain: IbGib_V1[] | undefined;
+            if (pushOfferInfos.length > 0) {
+                const searchSecondSpaceAddrs: IbGibAddr[] = [];
+                payloadIbGibsDomain = [];
+                const domainAddrs: IbGibAddr[] = pushOfferInfos.flatMap(x => x.addrs);
+                const resGet = await getFromSpace({ addrs: domainAddrs, space: mySpace, });
+                const resGetRawData = resGet.rawResultIbGib?.data as IbGibSpaceResultData | undefined;
+                if (!resGetRawData) { throw new Error(`(UNEXPECTED) resGet.rawResultIbGib.data falsy? (E: 1a2cc8cb99a1ffa60837e45a8229b826)`); }
+                const addrsNotFound = resGetRawData.addrsNotFound ?? [];
+                const addrsErrored = resGetRawData.addrsErrored ?? [];
+                if (resGet.ibGibs && resGet.ibGibs.length === domainAddrs.length) {
+                    // found all of them
+                    resGet.ibGibs.forEach(x => { payloadIbGibsDomain!.push(x) })
+                } else if (resGet.ibGibs && resGet.ibGibs.length > 0) {
+                    // found some of them
+                    resGet.ibGibs.forEach(x => { payloadIbGibsDomain!.push(x) })
+                    const foundPlusNotFoundCount =
+                        payloadIbGibsDomain.length +
+                        addrsNotFound.length +
+                        addrsErrored.length;
+                    if (foundPlusNotFoundCount === domainAddrs.length) {
+                        // we can still conceivably get the remaining addrs
+                        addrsNotFound.forEach(x => searchSecondSpaceAddrs.push(x));
+                        addrsErrored.forEach(x => searchSecondSpaceAddrs.push(x));
+                    } else if (addrsNotFound.length === 0 && addrsErrored.length === 0) {
+                        throw new Error(`(UNEXPECTED) found some but not all addrs but addrsNotFound and addrsErrored both empty? (E: ef1b2cf5bab8de2298ec507abe04e826)`);
+                    } else {
+                        throw new Error(`(UNEXPECTED) found some but not all addrs but addrsNotFound and addrsErrored don't contain the addrs not found? (E: ae9e015109f8c3c3a813da584cd98826)`);
+                    }
+                } else {
+                    // found none of them(?)
+                    console.warn(`${lc} we were expecting all domainAddrs in mySpace (${mySpace.ib}) but we couldn't get all of them. addrsNotFound: ${addrsNotFound ?? []}. addrsErrored: ${addrsErrored ?? []}. Trying temp space (${myTempSpace.ib}). (W: f61908e264f8dddd2e3fb9084463d826)`);
+                    domainAddrs.forEach(x => searchSecondSpaceAddrs.push(x));
+                }
+                if (searchSecondSpaceAddrs.length > 0) {
+                    if (logalot) { console.log(`${lc} couldn't get all addrs in mySpace (${mySpace.ib}). searchSecondSpaceAddrs: ${searchSecondSpaceAddrs} (I: 233fd954dbd84e51bca02fa8eed5f826)`); }
+                    const resGet2 = await getFromSpace({ addrs: searchSecondSpaceAddrs, space: myTempSpace, });
+                    if (resGet2.success && resGet2.ibGibs && resGet2.ibGibs.length === searchSecondSpaceAddrs.length) {
+                        // got them all the second try
+                        resGet2.ibGibs.forEach(x => payloadIbGibsDomain!.push(x));
+                    } else {
+                        resGet2.ibGibs?.forEach(x => payloadIbGibsDomain!.push(x));
+                        const addrsFailed = domainAddrs.filter(x =>
+                            !payloadIbGibsDomain!.map(pid => getIbGibAddr({ ibGib: pid })).includes(x)
+                        );
+                        throw new Error(`couldn't get some or all of addrs from either mySpace (${mySpace.ib}) or myTempSpace (${myTempSpace.ib}). addrsFailed: ${addrsFailed} (E: 1394d412c4ffa4dd085f269b43338826)`);
+                    }
+                }
+                // we have now populated payloadIbGibsDomain
             }
 
-            return {
-                frame: ackFrame,
-                // conflictInfos,
-                // payloadIbGibsDomain,
-            };
+            throw new Error(`not implemented (E: ed3f98abb0988c5ae8038bb8d741fb26)`);
+            // return {
+            //     frame: ackFrame,
+            //     // conflictInfos,
+            //     payloadIbGibsDomain,
+            // };
 
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -1109,14 +1160,14 @@ export class SyncSagaCoordinator {
 
     /**
      * Handles the `Ack` frame.
-     * 
+     *
      * @remarks
      * **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).
-     * 
+     *
      * Returns a `Delta` frame.
      */
     protected async handleAckFrame({
@@ -1133,7 +1184,7 @@ export class SyncSagaCoordinator {
         tempSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,
         identity?: KeystoneIbGib_V1,
-    }): Promise<HandleSagaFrameResult | null> {
+    }): Promise<NextSagaFrameInfo> {
         const lc = `${this.lc}[${this.handleAckFrame.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting... (I: 605b6860e898267a5b50c6d85704be26)`); }
@@ -1161,7 +1212,7 @@ export class SyncSagaCoordinator {
                 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.
-                throw new Error(`${lc} Peer reported terminal conflicts. (E: a1b2c3d4e5f6g7h8i9j0k)`);
+                throw new Error(`${lc} Peer reported terminal conflicts. (E: 23a0096ee05a2ccfa89334e8f156b426)`);
             }
 
             const optimisticConflicts = conflicts.filter(c => !c.terminal);
@@ -1189,7 +1240,7 @@ export class SyncSagaCoordinator {
                 // Standard Saga: Init(Push) -> Ack(Pull Reqs) -> Delta(Push Data).
 
                 // If Sender needs data, we might need a "Reverse Delta" or "Pull" phase?
-                // Or we just proceed to Delta (sending what Receiver wants), 
+                // Or we just proceed to Delta (sending what Receiver wants),
                 // AND we piggyback our own requests?
                 // OR: We treat the Conflict Resolution as a sub-saga or side-effect?
 
@@ -1218,7 +1269,7 @@ export class SyncSagaCoordinator {
                     // 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: 9c8d7e6f5g4h3i2j1k0l)`); }
+                    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.
@@ -1303,24 +1354,25 @@ export class SyncSagaCoordinator {
 
             // 2. Prepare Delta Payload (What Receiver Requesting + Our Conflict Logic)
 
-            const deltaReqAddrs = ackData.deltaReqAddrs || [];
-            const pushOfferAddrs = ackData.pushOfferAddrs || [];
+            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);
-                }
+                // 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));
+                    // addrs.forEach(a => skipAddrs.add(a));
                 });
             }
 
@@ -1328,24 +1380,24 @@ export class SyncSagaCoordinator {
             // 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)`);
-                }
+                // 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? 
+            // 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.
 
@@ -1420,7 +1472,8 @@ export class SyncSagaCoordinator {
             if (identity) { payloadIbGibsControl.push(identity); }
 
             // return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: payloadIbGibs };
-            return { frame: deltaFrame, payloadIbGibsDomain: payloadIbGibs };
+            // return { frame: deltaFrame, payloadIbGibsDomain: payloadIbGibs };
+            throw new Error(`not implemented (E: 62e1e2a408e8bfa2982b2f87e8843826)`);
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;
@@ -1431,10 +1484,10 @@ export class SyncSagaCoordinator {
 
     /**
      * Handles the `Delta` frame.
-     * 
+     *
      * @remarks
      * **Execution Context**: **Both**.
-     * 
+     *
      * 1.  **Ingestion**: Receives data sent by Peer (`payloadAddrs`). Resolves them from `Rel8ns.payload` (implicitly via space/context) and returns them in `receivedPayload` to be saved.
      * 2.  **Fulfillment**: Checks `requests`. If Peer requested data, gathers it and prepares `outgoingPayload`.
      * 3.  **Completion**: If no more requests, transitions to `Commit`.
@@ -1453,7 +1506,7 @@ export class SyncSagaCoordinator {
         tempSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,
         identity?: KeystoneIbGib_V1,
-    }): Promise<HandleSagaFrameResult | null> {
+    }): Promise<NextSagaFrameInfo> {
         const lc = `${this.lc}[${this.handleDeltaFrame.name}]`;
         if (logalot) { console.log(`${lc} starting...`); }
 
@@ -1466,7 +1519,7 @@ export class SyncSagaCoordinator {
         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: 8d7e6f5g4h3i2j1k0l9m)`); }
+        if (logalot) { console.log(`${lc} deltaData: ${pretty(deltaData)} (I: a76008681df458cfbcdc4848f825a826)`); }
 
         console.log(`${lc} [CONFLICT DEBUG] deltaData.payloadAddrs count: ${deltaData.payloadAddrs?.length || 0}`);
 
@@ -1477,8 +1530,8 @@ export class SyncSagaCoordinator {
         // 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` 
+            // 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`.
@@ -1506,7 +1559,7 @@ export class SyncSagaCoordinator {
             // Get the requested ibGib
             let ibGib = srcGraph[addr];
             if (!ibGib) {
-                const res = await getFromSpace({ addr, space: destSpace }); // Query from destSpace  
+                const res = await getFromSpace({ addr, space: destSpace }); // Query from destSpace
                 if (res.ibGibs && res.ibGibs.length > 0) {
                     ibGib = res.ibGibs[0];
                 }
@@ -1602,7 +1655,7 @@ export class SyncSagaCoordinator {
                     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? 
+                        // 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.
 
@@ -1648,9 +1701,9 @@ export class SyncSagaCoordinator {
                 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. 
+                // Wait. If we send data, we are NOT committing yet.
                 // We are sending data. The OTHER side must ingest it.
-                // So proposeCommit = true? 
+                // So proposeCommit = true?
                 // "Here is the data. I'm done. If you are good, let's commit."
                 // Yes.
             };
@@ -1680,7 +1733,8 @@ export class SyncSagaCoordinator {
             if (identity) { payloadIbGibsControl.push(identity); }
 
             // return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: outgoingPayload };
-            return { frame: deltaFrame, payloadIbGibsDomain: outgoingPayload };
+            // return { frame: deltaFrame, payloadIbGibsDomain: outgoingPayload };
+            throw new Error(`not implemented (E: 2b38a8afb6d84efcee5ab51673387826)`);
 
         } else {
             // We have nothing to send.
@@ -1712,7 +1766,8 @@ export class SyncSagaCoordinator {
                 if (identity) { commitCtrlPayloads.push(identity); }
 
                 // return { frame: commitFrame, payloadIbGibsControl: commitCtrlPayloads };
-                return { frame: commitFrame, };
+                // 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).
@@ -1770,7 +1825,8 @@ export class SyncSagaCoordinator {
                     if (identity) { commitCtrlPayloads2.push(identity); }
 
                     // return { frame: commitFrame, payloadIbGibsControl: commitCtrlPayloads2 };
-                    return { frame: commitFrame, };
+                    // return { frame: commitFrame, };
+                    throw new Error(`not implemented (E: 27514878585889e531ef21f1abbef826)`);
                 }
 
                 // Build control payloads for delta propose
@@ -1778,7 +1834,8 @@ export class SyncSagaCoordinator {
                 if (identity) { deltaCtrlPayloads.push(identity); }
 
                 // return { frame: deltaFrame, payloadIbGibsControl: deltaCtrlPayloads };
-                return { frame: deltaFrame, };
+                // return { frame: deltaFrame, };
+                throw new Error(`not implemented (E: ff35584696b6fcb3ad6dd7c5cade2f26)`);
             }
         }
     }
@@ -1796,7 +1853,7 @@ export class SyncSagaCoordinator {
         tempSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,
         identity?: KeystoneIbGib_V1,
-    }): Promise<HandleSagaFrameResult | null> {
+    }): Promise<NextSagaFrameInfo> {
         const lc = `${this.lc}[${this.handleCommitFrame.name}]`;
         if (logalot) { console.log(`${lc} Commit received.`); }
 
@@ -1811,7 +1868,8 @@ export class SyncSagaCoordinator {
         // 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 null;
+        // return { responseWasNull: true };
+        throw new Error(`not implemented (E: 4d7f878bcc45ad3dd9c4b8573f3aa826)`);
     }
 
     // #endregion Handlers
@@ -1909,7 +1967,7 @@ export class SyncSagaCoordinator {
                     rel8nInfos.push({ rel8nName: 'identity', ibGibs: [sessionIdentity], });
                 }
 
-                // remove the existing sync msg stones' addrs 
+                // remove the existing sync msg stones' addrs
                 if (!prevSagaIbGib.rel8ns) { throw new Error(`(UNEXPECTED) prevSagaIbGib.rel8ns falsy? (E: 81375841aff85b1e48ea42ca218e6826)`); }
                 if (!prevSagaIbGib.rel8ns[SYNC_MSG_REL8N_NAME] || prevSagaIbGib.rel8ns[SYNC_MSG_REL8N_NAME].length === 0) {
                     throw new Error(`(UNEXPECTED) prevSagaIbGib.rel8ns[SYNC_MSG_REL8N_NAME] falsy/empty? (E: 15156baad26fcccda80aa3a31718c726)`);