@ibgib/core-gib 0.1.22 → 0.1.25

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

@@ -1,23 +1,21 @@
 import { extractErrorMsg, getUUID, // so our timestamp in ticks as a string are uniform
-pretty, } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+pretty, delay, } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
 import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
-import { splitPerTjpAndOrDna, getTimelinesGroupedByTjp, isIbGib } from "../common/other/ibgib-helper.mjs";
 import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
 import { putInSpace, getLatestAddrs, getFromSpace } from "../witness/space/space-helper.mjs";
 import { SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN } from "./sync-constants.mjs";
 import { appendToTimeline, createTimeline } from "../timeline/timeline-api.mjs";
-import { SyncMode, } from "./sync-types.mjs";
-import { getSyncIb, isPastFrame } from "./sync-helpers.mjs";
-import { getSyncSagaDependencyGraph as getSyncSagaDependencyGraphForThisFrameOnly } from "./sync-helpers.mjs";
-import { getDependencyGraph } from "../common/other/graph-helper.mjs";
+import { SyncConflictStrategy, SyncMode, SYNC_CONFLICT_STRATEGY_VALID_VALUES, } from "./sync-types.mjs";
+import { getSyncIb, getTempSpaceName, isPastFrame } from "./sync-helpers.mjs";
+import { getDeltaDependencyGraph, getDependencyGraph, toFlatGraph } from "../common/other/graph-helper.mjs";
 import { getSyncSagaMessageIb } from "./sync-saga-message/sync-saga-message-helpers.mjs";
 import { SYNC_SAGA_MSG_ATOM } from "./sync-saga-message/sync-saga-message-constants.mjs";
-import { createSyncSagaContext } from "./sync-saga-context/sync-saga-context-helpers.mjs";
+import { splitPerTjpAndOrDna, getTimelinesGroupedByTjp, isIbGib } from "../common/other/ibgib-helper.mjs";
+import { createSyncSagaContext, validateContextAndSagaFrame } from "./sync-saga-context/sync-saga-context-helpers.mjs";
 import { newupSubject, } from "../common/pubsub/subject/subject-helper.mjs";
 import { mergeDivergentTimelines } from "./strategies/conflict-optimistic.mjs";
 import { getSyncSagaMessageFromFrame } from "./sync-saga-message/sync-saga-message-helpers.mjs";
 import { fnObs } from "../common/pubsub/observer/observer-helper.mjs";
-import { SyncPeerInnerspace_V1 } from "./sync-peer/sync-peer-innerspace/sync-peer-innerspace-v1.mjs";
 // const logalot = GLOBAL_LOG_A_LOT || true;
 const logalot = false;
 const logalotControlDomain = true;
@@ -54,14 +52,13 @@ 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({ peer, localSpace: _localSpace, source: _source, metaspace, domainIbGibs, conflictStrategy = 'abort', useSessionIdentity = true, }) {
+    async sync({ peer, domainIbGibs, conflictStrategy = SyncConflictStrategy.abort, useSessionIdentity = true, metaspace, localSpace, }) {
         const lc = `${this.lc}[${this.sync.name}]`;
         if (logalot) {
             console.log(`${lc} starting...`);
         }
-        const localSpace = (_source || _localSpace);
         if (!localSpace) {
-            throw new Error(`${lc} source (or localSpace) required (E: 8a9b0c1d)`);
+            throw new Error(`${lc} source (or localSpace) required (E: 25df3761f7686a1099a552f83c95d326)`);
         }
         // 1. SETUP SAGA METADATA
         const sagaId = await getUUID();
@@ -77,10 +74,6 @@ export class SyncSagaCoordinator {
             resolveDone = resolve;
             rejectDone = reject;
         });
-        async function getTempSpaceName() {
-            const uuid = await getUUID();
-            return `tmp_sync_space_${uuid.substring(0, 8)}`;
-        }
         // WORKING CONTEXT (Transactional)
         const tempSpaceName = await getTempSpaceName();
         const tempSpace = await metaspace.createNewLocalSpace({
@@ -102,33 +95,22 @@ export class SyncSagaCoordinator {
         // Async execution wrapper
         (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, srcGraph } = await this.createInitFrame({
+                // CREATE INITIAL FRAME (Stage.init)
+                const { initFrame, initDomainGraph } = await this.createInitFrame({
                     sagaId,
                     sessionIdentity,
-                    localSpace,
                     domainIbGibs,
-                    tempSpace,
-                    metaspace,
-                    conflictStrategy
+                    conflictStrategy,
+                    metaspace, localSpace, tempSpace,
                 });
-                // 4. EXECUTE SAGA LOOP (FSM)
-                // Inject tempSpace into peer so it can pull control payloads to the right place
-                // if ('opts' in peer && peer.opts) {
-                if (!peer.data) {
-                    throw new Error(`(UNEXPECTED) peer.data falsy? (E: 8546a884c82ffb1999e95d9867da2826)`);
-                }
-                if (peer.data.classname === SyncPeerInnerspace_V1.name) {
-                    // (peer as SyncPeerInnerspace_V1).senderTempSpace = tempSpace;
-                }
-                const syncedIbGibs = await this.executeSagaLoop({
-                    initialFrame: initFrame,
-                    srcGraph,
+                // KICK OFF THE PING-PONG SAGA LOOP (FSM)
+                await this.executeSagaLoop({
+                    initFrame, initDomainGraph,
                     peer,
                     sessionIdentity,
                     updates$,
@@ -136,13 +118,6 @@ export class SyncSagaCoordinator {
                     tempSpace,
                     metaspace
                 });
-                // 5. MERGE RESULT (Optimistic Commit)
-                if (syncedIbGibs && syncedIbGibs.length > 0) {
-                    if (logalot) {
-                        console.log(`${lc} Merging ${syncedIbGibs.length} synced ibGibs to localSpace...`);
-                    }
-                    await putInSpace({ space: localSpace, ibGibs: syncedIbGibs });
-                }
                 resolveDone();
                 if (!updates$.complete) {
                     throw new Error(`(UNEXPECTED) updates$.complete falsy? (E: d24cd82184aec130c89a320819b39126)`);
@@ -205,139 +180,98 @@ export class SyncSagaCoordinator {
      * **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 `handleSagaFrame`.
+     * 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 `handleSagaFrame` returns a `nextPayloadIbGibs` (data to send), this loop injects it into
+     * When `handleSagaResponseContext` returns a `nextPayloadIbGibs` (data to send), this loop injects it into
      * the NEXT request context.
      * When the Peer responds with data (in the response context), it is resolved and put into `tempSpace`.
      */
-    async executeSagaLoop({ initialFrame, srcGraph, peer, sessionIdentity, updates$, localSpace, tempSpace, metaspace }) {
+    async executeSagaLoop({ initFrame, initDomainGraph, peer, sessionIdentity, updates$, localSpace, tempSpace, metaspace }) {
         const lc = `${this.lc}[${this.executeSagaLoop.name}]`;
-        // The current frame we just generated (e.g., Init or Delta Request)
-        let currentFrame = 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 = initFrame;
+        /** The **domain** payload we need to transmit (data we are sending) */
         let nextDomainIbGibs = [];
-        // Accumulator for all data we've successfully pulled from the remote
-        const allReceivedIbGibs = [];
         while (currentFrame) {
-            // A. Create Context (Request)
-            // 1. Calculate Full Dependency Graph (including Ancestors/DNA)
-            // TODO: adjust this algorithm to only do the dependencies that the other end doesn't need (diff between tip and LCA)
-            // We must do this BEFORE creating the Context so we can list them
-            // all in payloadAddrsDomain and payloadAddrsControl.
-            // const depsDomainIbGibs: IbGib_V1[] = [];
-            // const depsControlIbGibs: IbGib_V1[] = [];
-            const payloadIbGibsControl = [];
-            const payloadIbGibsDomain = [];
-            // A. Payload (Standard Deep Deps)
-            for (const nextDomainIbGib of nextDomainIbGibs) {
-                let nextDomainIbGibGraph = await getDependencyGraph({ ibGib: nextDomainIbGib, space: localSpace });
-                if (!nextDomainIbGibGraph) {
-                    nextDomainIbGibGraph = await getDependencyGraph({ ibGib: nextDomainIbGib, space: tempSpace });
-                }
-                if (nextDomainIbGibGraph) {
-                    payloadIbGibsDomain.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: ${payloadIbGibsDomain.length} (I: 2beda8ca7dc5ac0f48ed9e25e704b826)`);
-            }
-            // B. Frames (Shallow Sync Deps)
-            if (currentFrame) {
-                const depsCurrentFrame = await getSyncSagaDependencyGraphForThisFrameOnly({ ibGib: currentFrame, space: tempSpace });
-                if (depsCurrentFrame.length > 0) {
-                    depsCurrentFrame.forEach(x => payloadIbGibsControl.push(x));
-                }
-                else {
-                    throw new Error(`(UNEXPECTED) couldn't get deps for currentFrame? currentFrame: ${JSON.stringify(currentFrame)} (E: 06344d07adc80d80b809211171444d26)`);
-                }
-            }
-            // 2. Create Context (Envelope)
+            // first, prepare for context transmission...
+            /**
+             * 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();
+            // #region set up peer observable for any domainPayloadsMap
             const sublc = `${lc}[peer.payloadIbGibsDomainReceived$]`;
-            let subscription;
-            if (peer && peer.payloadIbGibsDomainReceived$) {
-                // Subscribe to stream
-                subscription = await peer.payloadIbGibsDomainReceived$.subscribe(fnObs({
-                    next: async (ibgib) => {
-                        if (logalot) {
-                            console.log(`${sublc} next fired. (I: 2b4bdf502a38a90ba33d9711e7cb7826)`);
-                        }
-                        const addr = getIbGibAddr({ ibGib: ibgib });
-                        if (logalotControlDomain) {
-                            console.log(`${lc}${lcControlDomain} DOMAIN STREAM RECEIVED <- observable: ${addr} (I: d69ee80fcaece272483ec33b2d289826)`);
-                        }
-                        domainPayloadsMap.set(addr, ibgib);
-                    },
-                    error: async (e) => {
-                        if (isIbGib(e)) {
-                            console.error(`${sublc} error fired. error: ${JSON.stringify(e.data)} (E: 01cc08ba05ad99682831174fd7c31a26)`);
-                        }
-                        else {
-                            console.dir(e);
-                            console.error(`${sublc} error fired. error: ${extractErrorMsg(e)} (E: 73d3d61464e8e4ce4cd6efd8b9675826)`);
-                        }
-                    },
-                    complete: async () => {
-                        if (logalot) {
-                            console.log(`${sublc} complete fired. (I: a47218aa9e4433fdb97c068880a45826)`);
-                        }
-                        await subscription.unsubscribe();
-                    },
-                }));
-            }
-            // 2b. Request Context
+            const subscription = await peer.payloadIbGibsDomainReceived$.subscribe(fnObs({
+                next: async (ibgib) => {
+                    if (logalot) {
+                        console.log(`${sublc} next fired. (I: 2b4bdf502a38a90ba33d9711e7cb7826)`);
+                    }
+                    const addr = getIbGibAddr({ ibGib: ibgib });
+                    if (logalotControlDomain) {
+                        console.log(`${lc}${lcControlDomain} DOMAIN STREAM RECEIVED <- observable: ${addr} (I: d69ee80fcaece272483ec33b2d289826)`);
+                    }
+                    domainPayloadsMap.set(addr, ibgib);
+                },
+                error: async (e) => {
+                    if (isIbGib(e)) {
+                        console.error(`${sublc} error fired. error: ${JSON.stringify(e.data)} (E: 01cc08ba05ad99682831174fd7c31a26)`);
+                    }
+                    else {
+                        console.dir(e);
+                        console.error(`${sublc} error fired. error: ${extractErrorMsg(e)} (E: 73d3d61464e8e4ce4cd6efd8b9675826)`);
+                    }
+                },
+                complete: async () => {
+                    if (logalot) {
+                        console.log(`${sublc} complete fired. (I: a47218aa9e4433fdb97c068880a45826)`);
+                    }
+                    await subscription.unsubscribe();
+                },
+            }));
+            // #endregion set up peer observable for any domainPayloadsMap
+            // ...create/compose the Request Context itself...
             const requestCtx = await createSyncSagaContext({
                 sagaFrame: currentFrame,
                 sessionKeystones: sessionIdentity ? [sessionIdentity] : undefined,
-                payloadIbGibsDomain,
+                /**
+                 * init frame: empty
+                 * ack frame: possible push offers
+                 * delta frame: requested ibgibs or commit offer
+                 * commit frame: empty
+                 */
+                payloadIbGibsDomain: nextDomainIbGibs,
+                localSpace,
             });
-            // Log what we're sending
+            // #region Log what we're sending
             if (logalotControlDomain) {
-                const controlAddrs = payloadIbGibsControl.map(p => getIbGibAddr({ ibGib: p }));
-                const domainAddrs = payloadIbGibsDomain.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}   CONTROL Payloads (${controlAddrs.length}): ${controlAddrs.join(', ') || '(none)'}`);
                 console.log(`${lc}${lcControlDomain}   DOMAIN Payloads (${domainAddrs.length}): ${domainAddrs.join(', ') || '(none)'}`);
             }
-            // Add Context Deps
-            // do we need to add requestCtx to the payload ibgibs?
-            // if (requestCtx) {
-            //     const deps = await getSyncSagaDependencyGraphForThisFrameOnly({ ibGib: requestCtx, space: tempSpace });
-            //     if (deps) { deps.forEach(x => payloadIbGibsControl.push(x)); }
-            // }
-            // 3. Identity (if exists)
-            // Identity might be deep? Keystone? Usually self-contained or shallow references.
-            if (sessionIdentity) {
-                payloadIbGibsControl.push(sessionIdentity);
-            }
-            // we only put the **CONTROL** payload ibgibs in localSpace. we
-            // don't put any domain ibgibs into this durable space until the
-            // final commit phase.
-            // The requestCtx envelope itself also goes to localSpace so transfer can find it.
-            await putInSpace({ space: localSpace, ibGib: requestCtx });
-            if (payloadIbGibsControl.length > 0) {
-                await putInSpace({ space: localSpace, ibGibs: payloadIbGibsControl });
-            }
-            // B. Transmit
+            // #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 (don't remove this comment!)
+            updates$.next(requestCtx); // spins off for saga UI updates
+            // ...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.`);
+                            console.log(`${lc} Sender sent Commit. Peer returned no response. Saga Complete. (I: 26f9ee073858ca78b8284753368b5226)`);
                         }
                         currentFrame = null;
                         break;
@@ -350,79 +284,83 @@ export class SyncSagaCoordinator {
                     throw new Error(`(UNEXPECTED) no response and currentFrame falsy? (E: 8d1085ea2f28cfc3f9c922649864a826)`);
                 }
             }
-            // ---------------------------------------------------------------------
-            // 2d. HANDLE RESPONSE
-            // ---------------------------------------------------------------------
+            // 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] || [];
-            // TODO: check if we are validating the responseCtx in sync peer. I'm thinking that we must, because we can't start the domain ibgibs until we know the response's control ibgibs are valid.
-            // Poll for them if needed
+            // Poll for them if needed. see above jsdocs for domainPayloadsMap
             if (responsePayloadAddrsDomain.length > 0) {
-                await this.pollForDomainPayloads({
+                responseCtx.payloadIbGibsDomain = await this.pollForDomainPayloads({
                     expectedAddrs: responsePayloadAddrsDomain,
+                    pollIntervalMs: 20, // relatively arbitrary right now
                     domainPayloadsMap,
                     tempSpace,
                 });
             }
-            // Extract Response Frame
-            const responseFrameAddr = responseCtx.rel8ns?.sagaFrame?.[0];
-            if (!responseFrameAddr) {
-                throw new Error(`${lc} Peer response missing sagaFrame (E: 83a0)`);
+            // #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)`);
             }
-            // Log what we received back
             if (logalotControlDomain) {
                 const responseControlAddrs = responseCtx.data?.['@payloadAddrsControl'] || [];
-                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 Frame: ${responseFrameAddr}`);
+                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)'}`);
             }
-            // Get response frame from localSpace (SyncPeer puts it there)
-            let resResponseFrame = await getFromSpace({ space: localSpace, addr: responseFrameAddr });
-            if (!resResponseFrame.success || !resResponseFrame.ibGibs?.length) {
-                // Fallback to tempSpace
-                resResponseFrame = await getFromSpace({ space: tempSpace, addr: responseFrameAddr });
-            }
-            const responseFrame = resResponseFrame.ibGibs?.[0];
-            if (!responseFrame)
-                throw new Error(`${lc} Response frame not found (E: 7c2a)`);
-            // Handle Response Frame
-            const handleResult = await this.handleSagaFrame({
-                sagaIbGib: responseFrame,
-                srcGraph: {},
-                destSpace: localSpace,
-                tempSpace,
+            // #endregion Log what we received back
+            // 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,
-                domainPayloadsMap,
-                expectedDomainAddrs: responsePayloadAddrsDomain,
             });
-            if (!handleResult) {
+            if (!contextResult) {
                 if (logalot) {
-                    console.log(`${lc} Handler returned null (Saga End).`);
+                    console.log(`${lc} Handler returned null (Saga End). (I: faae22abc818ba9b28ac6d2881cd7826)`);
                 }
                 break;
             }
-            currentFrame = handleResult.frame;
-            // Collect next DOMAIN payloads for the NEXT request
-            // Control payloads are handled separately by ensureSagaFrameInBothSpaces
-            nextDomainIbGibs = [...(handleResult.payloadIbGibsDomain || [])];
-            // Log handler output for next iteration
+            // #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
+            // 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 || [])];
+            // #region Log handler output for next iteration
             if (logalotControlDomain) {
-                const handlerControlAddrs = (handleResult.payloadIbGibsControl || []).map(p => getIbGibAddr({ ibGib: p }));
                 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}   CONTROL for next (${handlerControlAddrs.length}): ${handlerControlAddrs.join(', ') || '(none)'} (saved via ensureSagaFrameInBothSpaces)`);
                 console.log(`${lc}${lcControlDomain}   DOMAIN for next (${handlerDomainAddrs.length}): ${handlerDomainAddrs.join(', ') || '(none)'}`);
             }
-            // Note: currentFrame is automatically added to dependencies at start of next loop via B. Frames logic.
+            // #endregion Log handler output for next iteration
         }
-        return allReceivedIbGibs;
     }
     /**
      * Helper to get Knowledge Vector for specific domain ibGibs or TJPs.
@@ -481,7 +419,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)`); }
             return res.data.latestAddrsMap;
@@ -496,24 +434,27 @@ export class SyncSagaCoordinator {
             }
         }
     }
-    async analyzeTimelines({ domainIbGibs, space, }) {
-        const lc = `${this.lc}[${this.analyzeTimelines.name}]`;
-        const srcGraph = await getDependencyGraph({
+    async analyzeDomainIbGibs({ domainIbGibs, space, }) {
+        const lc = `${this.lc}[${this.analyzeDomainIbGibs.name}]`;
+        if (domainIbGibs.length === 0) {
+            throw new Error(`invalid domainIbGibs. expected at least one, but array is empty. (E: 820a719bcac5a16878a2af697113b826)`);
+        }
+        const fullGraph = await getDependencyGraph({
             ibGibs: domainIbGibs,
             live: true,
             space,
         });
-        const srcGraphIsValid = srcGraph && Object.keys(srcGraph).length > 0;
+        const graphIsValid = fullGraph && Object.keys(fullGraph).length > 0;
         if (logalot) {
-            console.log(`${lc} graph generated. nodes: ${srcGraphIsValid ? Object.keys(srcGraph).length : 0}`);
+            console.log(`${lc} graph generated. nodes: ${graphIsValid ? Object.keys(fullGraph).length : 0}`);
         }
-        const srcIbGibs = srcGraphIsValid ? Object.values(srcGraph) : [];
+        const srcIbGibs = graphIsValid ? Object.values(fullGraph) : [];
         const { mapWithTjp_YesDna: srcMapWithTjp_YesDna, mapWithTjp_NoDna: srcMapWithTjp_NoDna, mapWithoutTjps: src_MapWithoutTjps } = splitPerTjpAndOrDna({ ibGibs: srcIbGibs });
-        const srcStones = Object.values(src_MapWithoutTjps);
-        const srcLiving = [...Object.values(srcMapWithTjp_YesDna), ...Object.values(srcMapWithTjp_NoDna)];
-        const srcTimelinesMap = getTimelinesGroupedByTjp({ ibGibs: srcLiving });
-        const srcSortedTjps = this.sortTimelinesTopologically(srcTimelinesMap);
-        return { srcStones, srcTimelinesMap, srcSortedTjps, srcGraph };
+        const stones = Object.values(src_MapWithoutTjps);
+        const withTimelines = [...Object.values(srcMapWithTjp_YesDna), ...Object.values(srcMapWithTjp_NoDna)];
+        const timelinesMap = getTimelinesGroupedByTjp({ ibGibs: withTimelines });
+        const topologicallySortedTjpAddrs = this.sortTimelinesTopologically(timelinesMap);
+        return { stones, timelinesMap, topologicallySortedTjpAddrs, fullGraph };
     }
     /**
      * Creates the Initial Saga Frame (Init Stage).
@@ -524,57 +465,54 @@ export class SyncSagaCoordinator {
      * Generates the first frame containing the Knowledge Vector of the Local Space.
      * This is sent to the Receiver to begin Gap Analysis.
      */
-    async createInitFrame({ sagaId, sessionIdentity, localSpace, domainIbGibs, tempSpace, metaspace, conflictStrategy, }) {
+    async createInitFrame({ sagaId, sessionIdentity, domainIbGibs, conflictStrategy, metaspace, localSpace, tempSpace, }) {
         const lc = `${this.lc}[${this.createInitFrame.name}]`;
         try {
             if (logalot) {
                 console.log(`${lc} starting... (I: 551af8b411ae9be712ce3358d43ee726)`);
             }
             // Analyze Timelines & Stones
-            const analysis = await this.analyzeTimelines({ domainIbGibs, space: localSpace });
-            // this is a lot, so uncomment this only if you want even more logging specific to this analysis
-            // if (logalot) { console.log(`${lc} analysis: ${pretty(analysis)}(I: cd00e2be5eccc8976879c888ff2dfb26)`); } 
-            const { srcTimelinesMap, srcGraph, srcStones, } = analysis;
+            const analysis = await this.analyzeDomainIbGibs({ domainIbGibs, space: localSpace });
+            // 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...
+            await putInSpace({ ibGibs: Object.values(fullGraph), space: tempSpace });
+            // populate our knowledge vector with tjp -> latest addr/tip in timeline
+            const knowledgeVector = {};
+            Object.keys(srcTimelinesMap).forEach(tjp => {
+                const timeline = srcTimelinesMap[tjp];
+                const tip = timeline.at(-1);
+                knowledgeVector[tjp] = getIbGibAddr({ ibGib: tip });
+            });
             const initData = {
                 sagaId,
                 stage: SyncStage.init,
-                knowledgeVector: {},
+                knowledgeVector,
                 identity: sessionIdentity, // KeystoneIbGib is already public data
                 mode: SyncMode.sync,
                 stones: srcStones.map(s => getIbGibAddr({ ibGib: s })),
             };
-            // Populate Knowledge Vector
-            Object.keys(srcTimelinesMap).forEach(tjp => {
-                const timeline = srcTimelinesMap[tjp];
-                const tip = timeline.at(-1);
-                initData.knowledgeVector[tjp] = getIbGibAddr({ ibGib: tip });
-            });
             if (logalot) {
                 console.log(`${lc} SyncStage.init: ${SyncStage.init}, SyncStage.commit: ${SyncStage.commit}`);
                 console.log(`${lc} initData.stage: ${initData.stage}`);
             }
+            // create the stone and save/register it
             const initStone = await this.createSyncMsgStone({
                 data: initData,
-                space: tempSpace,
-                metaspace
+                localSpace,
+                metaspace,
             });
             // if (logalot) { console.log(`${lc} initStone: ${pretty(initStone)} (I: 06e532f8a408549069474e96bed44826)`); }
+            // create the initial sync ibgib frame, save/register it
             const sagaFrame = await this.evolveSyncSagaIbGib({
                 msgStones: [initStone],
-                identity: sessionIdentity,
-                space: tempSpace,
-                metaspace,
                 conflictStrategy,
-            });
-            // IMMEDIATELY persist to both spaces for audit trail
-            await this.ensureSagaFrameInBothSpaces({
-                frame: sagaFrame,
-                destSpace: localSpace, // localSpace is the Sender's destSpace
-                tempSpace,
-                metaspace
+                sessionIdentity: sessionIdentity,
+                metaspace,
+                localSpace,
             });
             // if (logalot) { console.log(`${lc} sagaFrame (init): ${pretty(sagaFrame)} (I: b3d6a8be69248f18713cc3073cb08626)`); }
-            return { sagaFrame, srcGraph };
+            return { initFrame: sagaFrame, initDomainGraph: fullGraph };
         }
         catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -589,13 +527,16 @@ 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.
      */
-    async pollForDomainPayloads({ expectedAddrs, domainPayloadsMap, tempSpace, }) {
+    async pollForDomainPayloads({ expectedAddrs, pollIntervalMs, domainPayloadsMap, tempSpace, }) {
         const lc = `${this.lc}[${this.pollForDomainPayloads.name}]`;
         try {
             if (logalot) {
                 console.log(`${lc} starting... (I: 26dce86bfca572939885798802d6e926)`);
             }
+            let resultDomainPayloads = [];
             let pending = [...expectedAddrs];
             const start = Date.now();
             /**
@@ -619,12 +560,17 @@ export class SyncSagaCoordinator {
                 }
                 if (found.length > 0) {
                     await putInSpace({ space: tempSpace, ibGibs: found });
+                    found.forEach(x => resultDomainPayloads.push(x));
                 }
                 pending = stillPending;
                 if (pending.length > 0) {
-                    await new Promise(resolve => setTimeout(resolve, 50));
+                    await delay(pollIntervalMs);
                 }
             }
+            if (expectedAddrs.length !== resultDomainPayloads.length) {
+                throw new Error(`(UNEXPECTED) expectedAddrs.length !== resultDomainPayloads.length? at this point, we expect all of the payload ibgibs to have been received. (E: 03749a7478c4b8b28bfc86951887a826)`);
+            }
+            return resultDomainPayloads;
         }
         catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -636,12 +582,33 @@ export class SyncSagaCoordinator {
             }
         }
     }
-    async handleSagaFrame({ sagaIbGib, srcGraph, destSpace, tempSpace, identity, identitySecret, metaspace, }) {
-        const lc = `${this.lc}[${this.handleSagaFrame.name}]`;
+    /**
+     * 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.
+     *
+     * ## 2. Receiver
+     *
+     * On the receiver, this is called directly by the receiving endpoint. That
+     * endpoint's job is basically to get these things collocated and prepared
+     * to make this call.
+     *
+     * This is a one-off on the receiver.
+     */
+    async handleResponseSagaContext({ sagaContext, mySpace, myTempSpace, identity, identitySecret, metaspace, }) {
+        const lc = `${this.lc}[${this.handleResponseSagaContext.name}]`;
         try {
             if (logalot) {
                 console.log(`${lc} starting... (I: 5deec8a1f7a6d263c88cd458ad990826)`);
             }
+            const sagaIbGib = sagaContext.sagaFrame;
             if (!sagaIbGib.data) {
                 throw new Error(`(UNEXPECTED) sagaIbGib.data falsy? (E: 71b938adf1d87c2527bfd4f86dfd0826)`);
             }
@@ -649,26 +616,45 @@ export class SyncSagaCoordinator {
                 console.log(`${lc} sagaIbGib: ${pretty(sagaIbGib)} (I: 1b99d87d262e9d18d8a607a80b1a0126)`);
             }
             // Get Stage from Stone (or Frame for Init fallback)
-            const { stage, messageData } = await this.getStageAndPayloadFromFrame({ ibGib: sagaIbGib, space: tempSpace });
+            const { stage, messageData } = await this.getStageAndPayloadFromFrame({ sagaFrame: sagaIbGib, space: myTempSpace });
             if (logalot) {
                 console.log(`${lc} handling frame stage: ${stage}`);
             }
+            /**
+             * don't like this name, need to refactor
+             */
+            const srcGraph = toFlatGraph({ ibGibs: sagaContext.payloadIbGibsDomain }) ?? {};
+            let nextFrameInfo;
             switch (stage) {
                 case SyncStage.init:
-                    return await this.handleInitFrame({ sagaIbGib, messageData, metaspace, destSpace, tempSpace, identity, identitySecret });
+                    nextFrameInfo = await this.handleInitFrame({
+                        sagaIbGib,
+                        messageData: messageData,
+                        metaspace,
+                        mySpace: mySpace,
+                        myTempSpace: myTempSpace,
+                        identity,
+                        identitySecret
+                    });
+                    break;
                 case SyncStage.ack:
-                    return await this.handleAckFrame({ sagaIbGib, srcGraph, metaspace, destSpace, tempSpace, 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, tempSpace, identity, });
+                    nextFrameInfo = await this.handleDeltaFrame({ sagaIbGib, srcGraph, metaspace, destSpace: mySpace, tempSpace: myTempSpace, identity, });
+                    break;
                 case SyncStage.commit:
-                    return await this.handleCommitFrame({ sagaIbGib, metaspace, destSpace, tempSpace, 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) {
@@ -689,282 +675,332 @@ export class SyncSagaCoordinator {
      * 3.  Identifies what Receiver needs (`deltaReqAddrs`).
      * 4.  Returns an `Ack` frame containing these lists.
      */
-    async handleInitFrame({ sagaIbGib, messageData, destSpace, tempSpace, metaspace, identity, identitySecret, }) {
+    async handleInitFrame({ sagaIbGib, messageData, mySpace, myTempSpace, metaspace, identity,
+    // identitySecret,
+     }) {
         const lc = `${this.lc}[${this.handleInitFrame.name}]`;
-        console.log(`${lc} [TEST DEBUG] Received destSpace: ${destSpace.data?.name || destSpace.ib} (uuid: ${destSpace.data?.uuid || '[no uuid]'})`);
-        if (logalot) {
-            console.log(`${lc} starting...`);
-        }
-        // Extract Init Data
-        const initData = messageData; // Using renamed variable for clarity
-        if (initData.stage !== SyncStage.init) {
-            throw new Error(`${lc} Invalid init frame: initData.stage !== SyncStage.init (E: 8a2b3c4d5e6f7g8h)`);
-        }
-        // if (logalot) { console.log(`${lc} initData: ${pretty(initData)} (I: 46b0f8441b96ad7a388f1ce3239dd826)`); }
-        if (!initData || !initData.knowledgeVector) {
-            throw new Error(`${lc} Invalid init frame: missing knowledgeVector (E: ed02c869e028d2d06841b9c7f80f2826)`);
-        }
-        // Determine Strategy from Saga Data (since V1 stores it in root)
-        const conflictStrategy = sagaIbGib.data.conflictStrategy || 'abort';
-        // 2. Gap Analysis
-        const conflicts = [];
-        const deltaReqAddrs = [];
-        const pushOfferAddrs = [];
-        // Stones Analysis (Constants / Non-TJPs)
-        const stones = initData.stones || [];
-        if (stones.length > 0) {
+        try {
             if (logalot) {
-                console.log(`${lc} processing stones: ${stones.length}`);
-            }
-            // Check if we have these stones
-            const resStones = await getFromSpace({ space: destSpace, addrs: stones });
-            const addrsNotFound = resStones.rawResultIbGib?.data?.addrsNotFound;
-            if (addrsNotFound && addrsNotFound.length > 0) {
+                console.log(`${lc} starting... (I: 9d88dcad0408c029e898a4bcf3b08426)`);
+            }
+            console.log(`${lc} [TEST DEBUG] Receiver mySpace: ${mySpace.ib}`);
+            // Extract Init Data
+            const initData = messageData; // Using renamed variable for clarity
+            if (initData.stage !== SyncStage.init) {
+                throw new Error(`${lc} Invalid init frame: initData.stage !== SyncStage.init (E: c91be82970e4decc58f56bf8fc1ffc26)`);
+            }
+            // if (logalot) { console.log(`${lc} initData: ${pretty(initData)} (I: 46b0f8441b96ad7a388f1ce3239dd826)`); }
+            if (!initData || !initData.knowledgeVector) {
+                throw new Error(`${lc} Invalid init frame: missing knowledgeVector (E: ed02c869e028d2d06841b9c7f80f2826)`);
+            }
+            // Determine Strategy from Saga Data (since V1 stores it in root)
+            const conflictStrategy = sagaIbGib.data.conflictStrategy || SyncConflictStrategy.abort;
+            // 2. Gap Analysis
+            const conflicts = [];
+            const deltaRequestAddrInfos = [];
+            const pushOfferInfos = [];
+            // First do the consant stones (Non-TJPs)
+            const stones = initData.stones || [];
+            if (stones.length > 0) {
                 if (logalot) {
-                    console.log(`${lc} stones missing (requesting): ${addrsNotFound.length}`);
+                    console.log(`${lc} processing stones: ${stones.length}`);
+                }
+                // Check if we have these stones
+                const resStones = await getFromSpace({ space: mySpace, addrs: stones });
+                const rawResultIbGib = resStones.rawResultIbGib;
+                if (!rawResultIbGib.data) {
+                    throw new Error(`(UNEXPECTED) rawResultIbGib.data falsy? (E: f3c40b492adc02c3f480b998fc7a5926)`);
                 }
-                addrsNotFound.forEach(addr => {
-                    if (!deltaReqAddrs.includes(addr)) {
-                        deltaReqAddrs.push(addr);
+                const addrsNotFound = rawResultIbGib.data.addrsNotFound;
+                if (addrsNotFound && addrsNotFound.length > 0) {
+                    if (logalot) {
+                        console.log(`${lc} stones missing (requesting): ${addrsNotFound.length}`);
                     }
-                });
-            }
-        }
-        const remoteKV = initData.knowledgeVector;
-        if (logalot) {
-            console.log(`${lc} remoteKV: ${pretty(remoteKV)} (I: 9f957862356dfeae183c200854e86e26)`);
-        }
-        const remoteTjps = Object.keys(remoteKV);
-        console.log(`${lc} [TEST DEBUG] remoteTjps: ${JSON.stringify(remoteTjps)}`);
-        if (logalot) {
-            console.log(`${lc} remoteTjps: ${pretty(remoteTjps)} (I: 86ea4c53db0dc184c8b253386c402126)`);
-        }
-        // 1. Get Local Latest Addrs for all TJPs
-        let localKV = {};
-        if (remoteTjps.length > 0) {
-            // Batch get latest addrs for the TJPs
-            const resGetLatestAddrs = await getLatestAddrs({
-                space: destSpace,
-                tjpAddrs: remoteTjps,
-            });
-            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)`);
+                    addrsNotFound.forEach(addr => {
+                        if (!deltaRequestAddrInfos.some(x => x.addr === addr)) {
+                            deltaRequestAddrInfos.push({ addr }); // no tjpAddr
+                        }
+                    });
+                }
             }
-            localKV = resGetLatestAddrs.data.latestAddrsMap;
-            console.log(`${lc} [TEST DEBUG] localKV: ${JSON.stringify(localKV)}`);
+            /**
+             * "remote" is sender in this case
+             */
+            const remoteKV = initData.knowledgeVector;
             if (logalot) {
-                console.log(`${lc} localKV: ${pretty(localKV)} (I: 980975642cbccd8018cf0cd808d30826)`);
+                console.log(`${lc} remoteKV: ${pretty(remoteKV)} (I: 9f957862356dfeae183c200854e86e26)`);
             }
-        }
-        // 2. Gap Analysis
-        for (const tjp of remoteTjps) {
-            const remoteAddr = remoteKV[tjp];
-            const localAddr = localKV[tjp];
-            if (!localAddr) {
-                // We (Receiver) don't have this timeline. Request it.
-                console.log(`${lc} [TEST DEBUG] Missing local timeline for TJP: ${tjp}. Requesting remoteAddr: ${remoteAddr}`);
-                deltaReqAddrs.push(remoteAddr);
-                continue;
-            }
-            if (localAddr === remoteAddr) {
-                // 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({
-                olderAddr: remoteAddr,
-                newerAddr: localAddr,
-                space: destSpace,
-            });
-            if (isRemoteInPast) {
-                console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Remote is in past - offering push`);
-                pushOfferAddrs.push(localAddr);
+            const remoteTjps = Object.keys(remoteKV);
+            console.log(`${lc} [TEST DEBUG] remoteTjps: ${JSON.stringify(remoteTjps)}`);
+            if (logalot) {
+                console.log(`${lc} remoteTjps: ${pretty(remoteTjps)} (I: 86ea4c53db0dc184c8b253386c402126)`);
+            }
+            // 1. Get Local Latest Addrs for all TJPs
+            let localLatestAddrsMap = {};
+            if (remoteTjps.length > 0) {
+                // Batch get latest addrs for the TJPs
+                const resGetLatestAddrs = await getLatestAddrs({
+                    space: mySpace, // executing on receiver, so this is receiver's space
+                    tjpAddrs: remoteTjps,
+                });
+                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)`);
+                }
+                localLatestAddrsMap = resGetLatestAddrs.data.latestAddrsMap;
+                console.log(`${lc} [TEST DEBUG] localKV: ${JSON.stringify(localLatestAddrsMap)}`);
+                if (logalot) {
+                    console.log(`${lc} localKV: ${pretty(localLatestAddrsMap)} (I: 980975642cbccd8018cf0cd808d30826)`);
+                }
             }
-            else {
-                // Remote is not in our past. 
-                // Either Remote is ahead (Fast-Backward) OR Diverged.
-                // Check if Local is in Remote's PAST (Remote is Ahead -> Delta Request)
-                const isLocalInPast = await isPastFrame({
-                    olderAddr: localAddr,
-                    newerAddr: remoteAddr,
-                    space: destSpace,
+            // 2. Gap Analysis
+            for (const tjp of remoteTjps) {
+                const remoteAddr = remoteKV[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}`);
+                    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) {
+                    // ...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...`);
+                // 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 (isLocalInPast) {
-                    // Fast-Forward: We update to remote's tip.
-                    console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Local is in past - requesting delta`);
-                    deltaReqAddrs.push(remoteAddr);
+                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 {
-                    // DIVERGENCE: Both have changes the other doesn't know about.
-                    console.log(`${lc} [TEST DEBUG] TJP ${tjp}: DIVERGENCE DETECTED! conflictStrategy=${conflictStrategy}`);
-                    if (conflictStrategy === 'abort') {
-                        // Abort Strategy: We will treat this as terminal.
-                        // But for Unified Ack, we just mark it terminal in the list?
-                        // Or do we actually throw/abort the saga?
-                        // Current logic (below) aborts the saga if ANY conflict is terminal/abort.
-                        conflicts.push({
-                            tjpAddr: tjp,
-                            localAddr: localAddr,
-                            remoteAddr,
-                            timelineAddrs: [], // Not needed for abort
-                            reason: 'divergence',
-                            terminal: true
+                    // 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)
+                    /**
+                     * 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,
                         });
                     }
-                    else if (conflictStrategy === 'optimistic') {
-                        // Optimistic: We want to resolving this.
-                        // We need to send our history to the Sender so they can Merge.
-                        // Fetch Full History for Local Timeline
-                        // Note: We might optimize this to only send "recent" history if we had a KV?
-                        // But for now, get full past.
-                        // Optimization: localKV might not have full history.
-                        // We need to inspect the 'past' of the local tip.
-                        // We need the ACTUAL object to get the past.
-                        // We have localAddr.
-                        const resLocalTip = await getFromSpace({ space: destSpace, addr: localAddr });
-                        const localTip = resLocalTip.ibGibs?.[0];
-                        if (!localTip) {
-                            throw new Error(`${lc} Failed to load local tip for conflict resolution. (E: 8f9b2c3d4e5f6g7h)`);
+                    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)`);
                         }
-                        const timelineAddrs = [localAddr, ...(localTip.rel8ns?.past || [])];
-                        conflicts.push({
+                    }
+                    if (localIsInPast) {
+                        // Fast-Forward: We update to remote's tip.
+                        console.log(`${lc} [TEST DEBUG] TJP ${tjp}: Local is in past - requesting delta`);
+                        deltaRequestAddrInfos.push({
+                            addr: remoteAddr,
                             tjpAddr: tjp,
-                            localAddr: localAddr,
-                            remoteAddr,
-                            timelineAddrs,
-                            reason: 'divergence',
-                            terminal: false
+                            latestAddrAlreadyHave: localAddr,
                         });
                     }
                     else {
-                        throw new Error(`${lc} Unsupported conflict strategy: ${conflictStrategy} (E: 2a9b3c4d5e6f7g8h9i0j)`);
+                        // DIVERGENCE: Both have changes the other doesn't know about.
+                        console.log(`${lc} [TEST DEBUG] TJP ${tjp}: DIVERGENCE DETECTED! conflictStrategy=${conflictStrategy}`);
+                        if (conflictStrategy === 'abort') {
+                            // Abort Strategy: We will treat this as terminal.
+                            // But for Unified Ack, we just mark it terminal in the list?
+                            // Or do we actually throw/abort the saga?
+                            // Current logic (below) aborts the saga if ANY conflict is terminal/abort.
+                            conflicts.push({
+                                tjpAddr: tjp,
+                                localAddr: localAddr,
+                                remoteAddr,
+                                timelineAddrs: [], // Not needed for abort
+                                reason: 'divergence',
+                                terminal: true
+                            });
+                        }
+                        else if (conflictStrategy === 'optimistic') {
+                            // Optimistic: We want resolve this.
+                            // We need to send our history to the Sender so they can Merge.
+                            // Fetch Full History for Local Timeline
+                            // Note: We might optimize this to only send "recent" history if we had a KV?
+                            // But for now, get full past.
+                            // Optimization: localKV might not have full history.
+                            // We need to inspect the 'past' of the local tip.
+                            // We need the ACTUAL object to get the past.
+                            // We have localAddr.
+                            const resLocalTip = await getFromSpace({ space: mySpace, addr: localAddr });
+                            if (!resLocalTip.success || resLocalTip.ibGibs?.length !== 1) {
+                                throw new Error(`couldn't get local tip (${localAddr}) from space (${mySpace.ib}) (E: 83cb88a767e22bbda99c6788bec50526)`);
+                            }
+                            const localTip = resLocalTip.ibGibs[0];
+                            if (!localTip) {
+                                throw new Error(`${lc} Failed to load local tip for conflict resolution. (E: c39448ad6b3a72af78339ad877a56826)`);
+                            }
+                            const timelineAddrs = [...(localTip.rel8ns?.past ?? []), localAddr];
+                            conflicts.push({
+                                tjpAddr: tjp,
+                                localAddr,
+                                remoteAddr,
+                                timelineAddrs,
+                                reason: 'divergence',
+                                terminal: false
+                            });
+                        }
+                        else {
+                            throw new Error(`${lc} Unsupported conflict strategy: ${conflictStrategy}. Only these currently implemented: ${SYNC_CONFLICT_STRATEGY_VALID_VALUES} (E: 8f12384180f8a718a983a749fe0adf26)`);
+                        }
                     }
                 }
             }
-        }
-        // Check if we should ABORT (if any conflict is terminal)
-        const hasTerminalConflicts = conflicts.some(c => c.terminal);
-        if (hasTerminalConflicts) {
-            // Abort Strategy: Kill the saga.
+            // Check if we should ABORT (if any conflict is terminal)
+            const hasTerminalConflicts = conflicts.some(c => c.terminal);
+            if (hasTerminalConflicts) {
+                // Abort Strategy: Kill the saga.
+                if (logalot) {
+                    console.warn(`${lc} ABORTING Sync Saga due to terminal conflicts: ${JSON.stringify(conflicts)}`);
+                }
+                throw new Error(`the saga has terminal conflicts. conflicts: ${JSON.stringify(conflicts)} (E: f2edbe93cc07a63b38bfc013d2213b26)`);
+            }
+            // 3. Create Ack Frame
+            if (!sagaIbGib.data) {
+                throw new Error(`(UNEXPECTED) sagaIbGib.data falsy? (E: 24203af4600fb226ae6c1afbde442826)`);
+            }
+            const sagaId = sagaIbGib.data.uuid;
+            // Create Payload Stone
+            const ackData = {
+                sagaId,
+                stage: SyncStage.ack,
+                deltaRequestAddrInfos,
+                pushOfferInfos,
+            };
+            if (conflicts?.length > 0) {
+                ackData.conflicts = conflicts;
+            }
+            const ackStone = await this.createSyncMsgStone({
+                data: ackData,
+                localSpace: myTempSpace,
+                metaspace,
+            });
             if (logalot) {
-                console.warn(`${lc} ABORTING Sync Saga due to terminal conflicts: ${JSON.stringify(conflicts)}`);
-            }
-            // We reuse the ConflictData structure for terminal aborts?
-            // Or do we send an Ack with terminal conflicts?
-            // Original design had explicit Conflict Frame for Abort.
-            // Let's stick to that for purely terminal cases to be safe/explicit?
-            // Or Unified: Just send Ack with terminal=true conflicts. Sender sees them and aborts.
-            // Decision: Unified Ack for everything is cleaner protocol.
-            // But wait, the original code below creates a Conflict Stone.
-            // Let's preserve the explicit 'Conflict' frame for total aborts if that's easier,
-            // OR fully switch to Ack.
-            // Protocol states: Init -> Ack. If Ack contains terminal errors, Sender can Commit(Fail).
-            // Let's use Ack with conflicts.
-        }
-        // 2. Add Push Offers (Missing in Local)
-        // Check if we have them. If not, ask for them.
-        for (const addr of pushOfferAddrs) {
-            const hasIt = await getFromSpace({ addr, space: destSpace });
-            if (!hasIt.success || !hasIt.ibGibs || hasIt.ibGibs.length === 0) {
-                // If we don't have it, we put it in `deltaReqAddrs` of the Ack.
-                deltaReqAddrs.push(addr);
+                console.log(`${lc} ackStone created: ${pretty(ackStone)} (I: 313708132dd53ff946befb7833657826)`);
             }
-        }
-        // 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.
-        const knowledgeVector = {};
-        const relevantAddrs = new Set([...pushOfferAddrs, ...deltaReqAddrs]);
-        // [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: destSpace });
-                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];
+            // Evolve Saga
+            const ackFrame = await this.evolveSyncSagaIbGib({
+                prevSagaIbGib: sagaIbGib,
+                msgStones: [ackStone],
+                sessionIdentity: identity,
+                localSpace: mySpace,
+                metaspace,
+            });
+            // if (logalot) { console.log(`${lc} ackFrame created: ${pretty(ackFrame)} (I: be24480592eec478086bb3da49286826)`); }
+            /**
+             * 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;
+            if (pushOfferInfos.length > 0) {
+                const searchSecondSpaceAddrs = [];
+                payloadIbGibsDomain = [];
+                const domainAddrs = pushOfferInfos.flatMap(x => x.addrs);
+                const resGet = await getFromSpace({ addrs: domainAddrs, space: mySpace, });
+                const resGetRawData = resGet.rawResultIbGib?.data;
+                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)`);
                     }
                 }
-            }
-        }
-        // [Smart Diff] Also check individual requested addresses (Fall back for constants/unknown TJPs)
-        for (const addr of relevantAddrs) {
-            // Only process if not already covered by TJP logic above
-            // We can't really know if it's covered easily without resolving. 
-            // But if we don't have it (requesting), we won't find it here anyway.
-            // If we DO have it (push offer), we might find it.
-            const res = await getFromSpace({ addr, space: destSpace });
-            if (res.success && res.ibGibs?.[0]) {
-                const ibGib = res.ibGibs[0];
-                const tjpAddr = ibGib.rel8ns?.tjp?.[0] || getIbGibAddr({ ibGib });
-                if (!knowledgeVector[tjpAddr]) {
-                    const past = ibGib.rel8ns?.past || [];
-                    knowledgeVector[tjpAddr] = [getIbGibAddr({ ibGib }), ...past];
+                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));
                 }
-            }
-            else {
-                // We don't have `addr`.
-            }
+                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
+            }
+            throw new Error(`not implemented (E: ed3f98abb0988c5ae8038bb8d741fb26)`);
+            // return {
+            //     frame: ackFrame,
+            //     // conflictInfos,
+            //     payloadIbGibsDomain,
+            // };
         }
-        // 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;
-        // Create Payload Stone
-        const ackData = {
-            sagaId,
-            stage: SyncStage.ack,
-            deltaReqAddrs,
-            pushOfferAddrs,
-            knowledgeVector,
-            conflicts: conflicts.length > 0 ? conflicts : undefined, // Include conflicts if any detected
-        };
-        const ackStone = await this.createSyncMsgStone({
-            data: ackData,
-            space: tempSpace,
-            metaspace,
-        });
-        if (logalot) {
-            console.log(`${lc} ackStone created: ${pretty(ackStone)} (I: 313708132dd53ff946befb7833657826)`);
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
         }
-        // Evolve Saga
-        const ackFrame = await this.evolveSyncSagaIbGib({
-            prevSagaIbGib: sagaIbGib,
-            msgStones: [ackStone],
-            identity,
-            space: tempSpace,
-            metaspace,
-        });
-        // IMMEDIATELY persist to both spaces for audit trail (before any errors can occur)
-        await this.ensureSagaFrameInBothSpaces({ frame: ackFrame, destSpace, tempSpace, metaspace });
-        // if (logalot) { console.log(`${lc} ackFrame created: ${pretty(ackFrame)} (I: be24480592eec478086bb3da49286826)`); }
-        // Build control payloads: frame + its dependencies (msg stone, identity)
-        const payloadIbGibsControl = [ackFrame, ackStone];
-        if (identity) {
-            payloadIbGibsControl.push(identity);
+        finally {
+            if (logalot) {
+                console.log(`${lc} complete.`);
+            }
         }
-        return { frame: ackFrame, payloadIbGibsControl };
     }
     /**
      * Handles the `Ack` frame.
@@ -984,7 +1020,7 @@ export class SyncSagaCoordinator {
             if (logalot) {
                 console.log(`${lc} starting... (I: 605b6860e898267a5b50c6d85704be26)`);
             }
-            const { messageData, } = await this.getStageAndPayloadFromFrame({ ibGib: sagaIbGib, space: tempSpace });
+            const { messageData, } = await this.getStageAndPayloadFromFrame({ sagaFrame: sagaIbGib, space: tempSpace });
             const ackData = messageData;
             if (!ackData) {
                 throw new Error(`${lc} ackData falsy (E: 3b8415edc876084c88a25b98e2d55826)`);
@@ -1006,7 +1042,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);
             const mergeDeltaReqs = []; // Additional requests for merging
@@ -1028,7 +1064,7 @@ export class SyncSagaCoordinator {
                 // Or can we send a 'Delta Request' frame?
                 // 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?
                 // SIMPLIFICATION for V1:
@@ -1052,7 +1088,7 @@ export class SyncSagaCoordinator {
                     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)`);
+                        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.
@@ -1129,46 +1165,46 @@ export class SyncSagaCoordinator {
                 console.log(`${lc} [CONFLICT DEBUG] No optimistic conflicts to process`);
             }
             // 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 = [];
             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();
             if (ackData.knowledgeVector) {
                 Object.values(ackData.knowledgeVector).forEach(addrs => {
-                    addrs.forEach(a => skipAddrs.add(a));
+                    // addrs.forEach(a => skipAddrs.add(a));
                 });
             }
             const payloadIbGibs = [];
             // Gather all tips to sync first
             const tipsToSync = [];
             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.
             const allDepsSet = new Set();
@@ -1221,18 +1257,16 @@ export class SyncSagaCoordinator {
             }
             const deltaStone = await this.createSyncMsgStone({
                 data: deltaData,
-                space: tempSpace,
+                localSpace: tempSpace,
                 metaspace,
             });
             const deltaFrame = await this.evolveSyncSagaIbGib({
                 prevSagaIbGib: sagaIbGib,
                 msgStones: [deltaStone],
-                identity,
-                space: tempSpace,
+                sessionIdentity: identity,
+                localSpace: tempSpace,
                 metaspace,
             });
-            // IMMEDIATELY persist to both spaces for audit trail
-            await this.ensureSagaFrameInBothSpaces({ frame: deltaFrame, destSpace, tempSpace, metaspace });
             if (logalot) {
                 console.log(`${lc} Delta Frame created. Rel8ns: ${JSON.stringify(deltaFrame.rel8ns)}`);
             }
@@ -1241,7 +1275,9 @@ export class SyncSagaCoordinator {
             if (identity) {
                 payloadIbGibsControl.push(identity);
             }
-            return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: payloadIbGibs };
+            // return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: payloadIbGibs };
+            // return { frame: deltaFrame, payloadIbGibsDomain: payloadIbGibs };
+            throw new Error(`not implemented (E: 62e1e2a408e8bfa2982b2f87e8843826)`);
         }
         catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -1268,7 +1304,7 @@ export class SyncSagaCoordinator {
         if (logalot) {
             console.log(`${lc} starting...`);
         }
-        const { messageData } = await this.getStageAndPayloadFromFrame({ ibGib: sagaIbGib, space: tempSpace });
+        const { messageData } = await this.getStageAndPayloadFromFrame({ sagaFrame: sagaIbGib, space: tempSpace });
         const deltaData = messageData;
         if (!deltaData) {
             throw new Error(`${lc} deltaData falsy (E: 7c28c8d8f08a4421b8344e6727271421)`);
@@ -1277,7 +1313,7 @@ export class SyncSagaCoordinator {
             throw new Error(`${lc} Invalid delta frame: deltaData.stage !== SyncStage.delta (E: 0c28c8d8f08a4421b8344e6727271421)`);
         }
         if (logalot) {
-            console.log(`${lc} deltaData: ${pretty(deltaData)} (I: 8d7e6f5g4h3i2j1k0l9m)`);
+            console.log(`${lc} deltaData: ${pretty(deltaData)} (I: a76008681df458cfbcdc4848f825a826)`);
         }
         console.log(`${lc} [CONFLICT DEBUG] deltaData.payloadAddrs count: ${deltaData.payloadAddrs?.length || 0}`);
         const payloadAddrs = deltaData.payloadAddrs || [];
@@ -1286,8 +1322,8 @@ export class SyncSagaCoordinator {
         // 1. Process Received Payload (Ingest)
         const receivedPayloadIbGibs = [];
         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`.
@@ -1312,7 +1348,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];
                 }
@@ -1398,7 +1434,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.
                         // Perform Merge!
@@ -1442,9 +1478,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.
             };
@@ -1454,24 +1490,24 @@ export class SyncSagaCoordinator {
             responseDeltaData.proposeCommit = true;
             const deltaStone = await this.createSyncMsgStone({
                 data: responseDeltaData,
-                space: tempSpace,
+                localSpace: tempSpace,
                 metaspace
             });
             const deltaFrame = await this.evolveSyncSagaIbGib({
                 prevSagaIbGib: sagaIbGib,
                 msgStones: [deltaStone],
-                identity,
-                space: tempSpace,
+                sessionIdentity: identity,
+                localSpace: tempSpace,
                 metaspace
             });
-            // IMMEDIATELY persist to both spaces for audit trail
-            await this.ensureSagaFrameInBothSpaces({ frame: deltaFrame, destSpace, tempSpace, metaspace });
             // Build control payloads: frame + its dependencies (msg stone, identity)
             const payloadIbGibsControl = [deltaFrame, deltaStone];
             if (identity) {
                 payloadIbGibsControl.push(identity);
             }
-            return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: outgoingPayload };
+            // return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: outgoingPayload };
+            // return { frame: deltaFrame, payloadIbGibsDomain: outgoingPayload };
+            throw new Error(`not implemented (E: 2b38a8afb6d84efcee5ab51673387826)`);
         }
         else {
             // We have nothing to send.
@@ -1484,24 +1520,24 @@ export class SyncSagaCoordinator {
                 };
                 const commitStone = await this.createSyncMsgStone({
                     data: commitData,
-                    space: tempSpace,
+                    localSpace: tempSpace,
                     metaspace
                 });
                 const commitFrame = await this.evolveSyncSagaIbGib({
                     prevSagaIbGib: sagaIbGib,
                     msgStones: [commitStone],
-                    identity,
-                    space: tempSpace,
+                    sessionIdentity: identity,
+                    localSpace: tempSpace,
                     metaspace
                 });
-                // IMMEDIATELY persist to both spaces for audit trail
-                await this.ensureSagaFrameInBothSpaces({ frame: commitFrame, destSpace, tempSpace, metaspace });
                 // Build control payloads for commit
                 const commitCtrlPayloads = [commitFrame, commitStone];
                 if (identity) {
                     commitCtrlPayloads.push(identity);
                 }
-                return { frame: commitFrame, payloadIbGibsControl: commitCtrlPayloads };
+                // 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).
@@ -1515,18 +1551,16 @@ export class SyncSagaCoordinator {
                 };
                 const deltaStone = await this.createSyncMsgStone({
                     data: responseDeltaData,
-                    space: tempSpace,
+                    localSpace: tempSpace,
                     metaspace
                 });
                 const deltaFrame = await this.evolveSyncSagaIbGib({
                     prevSagaIbGib: sagaIbGib,
                     msgStones: [deltaStone],
-                    identity,
-                    space: tempSpace,
+                    sessionIdentity: identity,
+                    localSpace: tempSpace,
                     metaspace
                 });
-                // IMMEDIATELY persist to both spaces for audit trail
-                await this.ensureSagaFrameInBothSpaces({ frame: deltaFrame, destSpace, tempSpace, metaspace });
                 // Check if PEER proposed commit
                 if (deltaData.proposeCommit) {
                     if (logalot) {
@@ -1541,31 +1575,33 @@ export class SyncSagaCoordinator {
                     };
                     const commitStone = await this.createSyncMsgStone({
                         data: commitData,
-                        space: tempSpace,
+                        localSpace: tempSpace,
                         metaspace
                     });
                     const commitFrame = await this.evolveSyncSagaIbGib({
                         prevSagaIbGib: deltaFrame, // Build on top of the Delta we just created/persisted
                         msgStones: [commitStone],
-                        identity,
-                        space: tempSpace,
+                        sessionIdentity: identity,
+                        localSpace: tempSpace,
                         metaspace
                     });
-                    // IMMEDIATELY persist to both spaces for audit trail
-                    await this.ensureSagaFrameInBothSpaces({ frame: commitFrame, destSpace, tempSpace, metaspace });
                     // Build control payloads for commit
                     const commitCtrlPayloads2 = [commitFrame, commitStone];
                     if (identity) {
                         commitCtrlPayloads2.push(identity);
                     }
-                    return { frame: commitFrame, payloadIbGibsControl: commitCtrlPayloads2 };
+                    // return { frame: commitFrame, payloadIbGibsControl: commitCtrlPayloads2 };
+                    // return { frame: commitFrame, };
+                    throw new Error(`not implemented (E: 27514878585889e531ef21f1abbef826)`);
                 }
                 // Build control payloads for delta propose
                 const deltaCtrlPayloads = [deltaFrame, deltaStone];
                 if (identity) {
                     deltaCtrlPayloads.push(identity);
                 }
-                return { frame: deltaFrame, payloadIbGibsControl: deltaCtrlPayloads };
+                // return { frame: deltaFrame, payloadIbGibsControl: deltaCtrlPayloads };
+                // return { frame: deltaFrame, };
+                throw new Error(`not implemented (E: ff35584696b6fcb3ad6dd7c5cade2f26)`);
             }
         }
     }
@@ -1585,10 +1621,11 @@ export class SyncSagaCoordinator {
         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
-    async createSyncMsgStone({ data, space, metaspace, }) {
+    async createSyncMsgStone({ data, localSpace, metaspace, }) {
         const lc = `${this.lc}[${this.createSyncMsgStone.name}]`;
         try {
             if (logalot) {
@@ -1604,7 +1641,7 @@ export class SyncSagaCoordinator {
             if (logalot) {
                 console.log(`${lc} Created stone: ${getIbGibAddr({ ibGib: stone })}`);
             }
-            await putInSpace({ space, ibGib: stone });
+            await metaspace.put({ ibGib: stone, space: localSpace });
             await metaspace.registerNewIbGib({ ibGib: stone });
             return stone;
         }
@@ -1618,41 +1655,10 @@ export class SyncSagaCoordinator {
             }
         }
     }
-    /**
-     * Ensures saga frame and its msg stone(s) are in BOTH spaces for audit trail.
-     * Control ibgibs (saga frames, msg stones, identity) must be in both destSpace and tempSpace.
-     */
-    async ensureSagaFrameInBothSpaces({ frame, destSpace, tempSpace, metaspace, }) {
-        // Frame itself (already in tempSpace from creation, need in destSpace for audit)
-        await putInSpace({ space: destSpace, ibGib: frame });
-        await metaspace.registerNewIbGib({ ibGib: frame });
-        // Msg stone(s) (already in tempSpace, need in destSpace for audit)
-        const msgStoneAddrs = frame.rel8ns?.[SYNC_MSG_REL8N_NAME];
-        if (msgStoneAddrs && msgStoneAddrs.length > 0) {
-            const resMsgStones = await getFromSpace({ space: tempSpace, addrs: msgStoneAddrs });
-            if (resMsgStones.ibGibs) {
-                for (const msgStone of resMsgStones.ibGibs) {
-                    await putInSpace({ space: destSpace, ibGib: msgStone });
-                    await metaspace.registerNewIbGib({ ibGib: msgStone });
-                }
-            }
-        }
-        // Identity (if present, already in tempSpace, need in destSpace)
-        const identityAddrs = frame.rel8ns?.identity;
-        if (identityAddrs && identityAddrs.length > 0) {
-            const resIdentity = await getFromSpace({ space: tempSpace, addrs: identityAddrs });
-            if (resIdentity.ibGibs) {
-                for (const identity of resIdentity.ibGibs) {
-                    await putInSpace({ space: destSpace, ibGib: identity });
-                    await metaspace.registerNewIbGib({ ibGib: identity });
-                }
-            }
-        }
-    }
     /**
      * Evolves the saga timeline with a new frame.
      */
-    async evolveSyncSagaIbGib({ prevSagaIbGib, msgStones, identity, space, metaspace, conflictStrategy, }) {
+    async evolveSyncSagaIbGib({ prevSagaIbGib, conflictStrategy, msgStones, sessionIdentity, localSpace, metaspace, }) {
         const lc = `${this.lc}[${this.evolveSyncSagaIbGib.name}]`;
         try {
             // Validation
@@ -1675,7 +1681,7 @@ export class SyncSagaCoordinator {
                     throw new Error(`${lc} Mismatched stage in stones. Expected ${stage}, got ${d.stage} (E: d12c6571b0882f762921b60880c3f826)`);
                 }
             }
-            const identityAddr = identity ? getIbGibAddr({ ibGib: identity }) : undefined;
+            const identityAddr = sessionIdentity ? getIbGibAddr({ ibGib: sessionIdentity }) : undefined;
             if (prevSagaIbGib) {
                 /**
                  * rel8ns always include the new msg stone(s)
@@ -1687,10 +1693,10 @@ export class SyncSagaCoordinator {
                     }
                 ];
                 // if we're authenticating/signing, we'll have identity
-                if (identity) {
-                    rel8nInfos.push({ rel8nName: 'identity', ibGibs: [identity], });
+                if (sessionIdentity) {
+                    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)`);
                 }
@@ -1709,7 +1715,7 @@ export class SyncSagaCoordinator {
                     rel8nInfos,
                     rel8nRemovalInfos,
                     metaspace,
-                    space,
+                    space: localSpace,
                     noDna: true, // Explicitly no DNA for sync frames
                 });
                 const newFrame = resAppend;
@@ -1717,31 +1723,36 @@ export class SyncSagaCoordinator {
             }
             else {
                 // Create New Timeline (Root Frame)
+                // data
                 const data = {
                     uuid: sagaId,
-                    // stage, // Removed from V1
-                    payload: undefined, // Data in stone
                     n: 0,
                     isTjp: true,
                     conflictStrategy,
                 };
+                // ib
                 const ib = await getSyncIb({ data });
+                // rel8ns
                 const stoneAddrs = msgStones.map(s => getIbGibAddr({ ibGib: s }));
-                const rel8ns = {
-                    [SYNC_MSG_REL8N_NAME]: stoneAddrs,
-                };
+                const rel8ns = { [SYNC_MSG_REL8N_NAME]: stoneAddrs, };
                 if (identityAddr) {
                     rel8ns.identity = [identityAddr];
                 }
                 const resNew = await createTimeline({
-                    space,
+                    space: localSpace,
                     metaspace,
                     ib,
                     data,
                     rel8ns,
                     parentIb: SYNC_ATOM, // "sync"
+                    /**
+                     * this will squash the result into a single frame
+                     */
                     noDna: true,
                 });
+                if (!!resNew.intermediateIbGibs) {
+                    throw new Error(`(UNEXPECTED) resNew.intermediateIbGibs? we were assuming we were creating a single frame. (E: 456818147235d991ccb4d10d0bbe4826)`);
+                }
                 return resNew.newIbGib;
             }
         }
@@ -1750,16 +1761,16 @@ export class SyncSagaCoordinator {
             throw error;
         }
     }
-    async getStageAndPayloadFromFrame({ ibGib, space }) {
+    async getStageAndPayloadFromFrame({ sagaFrame, space }) {
         const lc = `${this.lc}[${this.getStageAndPayloadFromFrame.name}]`;
         try {
             if (logalot) {
                 console.log(`${lc} starting... (I: fddc287bd4d55253dc50e519fd352226)`);
             }
-            if (!ibGib.rel8ns) {
-                throw new Error(`(UNEXPECTED) ibGib.rel8ns falsy? (E: 725bc8eb5dfe5c7058907ad8e3063826)`);
+            if (!sagaFrame.rel8ns) {
+                throw new Error(`(UNEXPECTED) sagaFrame.rel8ns falsy? (E: 725bc8eb5dfe5c7058907ad8e3063826)`);
             }
-            const stoneAddrs = ibGib.rel8ns?.[SYNC_MSG_REL8N_NAME];
+            const stoneAddrs = sagaFrame.rel8ns?.[SYNC_MSG_REL8N_NAME];
             if (stoneAddrs && stoneAddrs.length > 0) {
                 const stoneAddr = stoneAddrs[0];
                 const res = await getFromSpace({ addr: stoneAddr, space });
@@ -1778,7 +1789,7 @@ export class SyncSagaCoordinator {
                 }
             }
             else {
-                throw new Error(`(UNEXPECTED) no stone addrs rel8d to sync saga ibgib frame? ibGib addr: ${getIbGibAddr(ibGib)} (E: 43eae8579e289d016741b5526052f226)`);
+                throw new Error(`(UNEXPECTED) no stone addrs rel8d to sync saga ibgib frame? sagaFrame addr: ${getIbGibAddr(sagaFrame)} (E: 43eae8579e289d016741b5526052f226)`);
             }
         }
         catch (error) {