@ibgib/core-gib 0.1.21 → 0.1.22

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

@@ -1,24 +1,27 @@
 import { extractErrorMsg, getUUID, // so our timestamp in ticks as a string are uniform
-pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+pretty, } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
 import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
-import { splitPerTjpAndOrDna, getTimelinesGroupedByTjp } from "../common/other/ibgib-helper.mjs";
+import { splitPerTjpAndOrDna, getTimelinesGroupedByTjp, isIbGib } from "../common/other/ibgib-helper.mjs";
 import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
-import { GLOBAL_LOG_A_LOT } from "../core-constants.mjs";
 import { putInSpace, getLatestAddrs, getFromSpace } from "../witness/space/space-helper.mjs";
-import { SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME } from "./sync-constants.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 } from "./sync-helpers.mjs";
+import { getSyncSagaDependencyGraph as getSyncSagaDependencyGraphForThisFrameOnly } from "./sync-helpers.mjs";
 import { getDependencyGraph } from "../common/other/graph-helper.mjs";
 import { getSyncSagaMessageIb } from "./sync-saga-message/sync-saga-message-helpers.mjs";
 import { SYNC_SAGA_MSG_ATOM } from "./sync-saga-message/sync-saga-message-constants.mjs";
-import { SyncSagaContextCmd } from "./sync-saga-context/sync-saga-context-types.mjs";
 import { createSyncSagaContext } from "./sync-saga-context/sync-saga-context-helpers.mjs";
-import { newupSubject } from "../common/pubsub/subject/subject-helper.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";
-const logalot = GLOBAL_LOG_A_LOT || true;
+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;
+const lcControlDomain = '[ControlDomain]';
 /**
  * Orchestrates the synchronization process between two spaces (Source and Destination).
  *
@@ -115,6 +118,14 @@ export class SyncSagaCoordinator {
                     conflictStrategy
                 });
                 // 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,
@@ -207,74 +218,123 @@ export class SyncSagaCoordinator {
         // 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)
-        let nextPayloadIbGibs = [];
+        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)
-            // We must do this BEFORE creating the Context so we can list them all in payloadAddrs.
-            const allDeps = [];
+            // 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 item of nextPayloadIbGibs) {
-                let graph = await getDependencyGraph({ ibGib: item, space: localSpace });
-                if (!graph) {
-                    graph = await getDependencyGraph({ ibGib: item, space: tempSpace });
+            for (const nextDomainIbGib of nextDomainIbGibs) {
+                let nextDomainIbGibGraph = await getDependencyGraph({ ibGib: nextDomainIbGib, space: localSpace });
+                if (!nextDomainIbGibGraph) {
+                    nextDomainIbGibGraph = await getDependencyGraph({ ibGib: nextDomainIbGib, space: tempSpace });
                 }
-                if (graph) {
-                    allDeps.push(...Object.values(graph));
+                if (nextDomainIbGibGraph) {
+                    payloadIbGibsDomain.push(...Object.values(nextDomainIbGibGraph));
                 }
                 else {
-                    allDeps.push(item);
+                    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} allDeps count: ${allDeps.length}`);
+                console.log(`${lc} payloadIbGibsDomain count: ${payloadIbGibsDomain.length} (I: 2beda8ca7dc5ac0f48ed9e25e704b826)`);
             }
             // B. Frames (Shallow Sync Deps)
             if (currentFrame) {
-                const deps = await getSyncSagaDependencyGraph({ ibGib: currentFrame, space: tempSpace });
-                if (deps)
-                    allDeps.push(...deps);
+                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)
-            // Use the FULL dependency list as the payload manifest
-            const payloadAddrs = allDeps.map(p => getIbGibAddr({ ibGib: p }));
+            const domainPayloadsMap = new Map();
+            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 requestCtx = await createSyncSagaContext({
-                cmd: SyncSagaContextCmd.process,
                 sagaFrame: currentFrame,
                 sessionKeystones: sessionIdentity ? [sessionIdentity] : undefined,
-                payloadAddrs: payloadAddrs.length > 0 ? payloadAddrs : undefined,
+                payloadIbGibsDomain,
             });
-            // Add Context Deps
-            if (requestCtx) {
-                const deps = await getSyncSagaDependencyGraph({ ibGib: requestCtx, space: tempSpace });
-                if (deps)
-                    allDeps.push(...deps);
+            // 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)`);
+                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) {
-                allDeps.push(sessionIdentity);
+                payloadIbGibsControl.push(sessionIdentity);
             }
-            if (allDeps.length > 0) {
-                await putInSpace({
-                    space: localSpace,
-                    ibGibs: allDeps
-                });
+            // 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
             // if (logalot) { console.log(`${lc} transmitting... requestCtx: ${pretty(requestCtx)} (I: 8cf20817c66899abdb1e76df50356826)`); }
-            updates$.next(requestCtx);
+            updates$.next(requestCtx); // spins off (don't remove this comment!)
             const responseCtx = await peer.witness(requestCtx);
             // C. Handle Response
             if (!responseCtx) {
-                // Check if we just sent a Commit frame. If so, peer's silence is success/expected.
                 if (currentFrame) {
+                    // Check for Commit (Peer silence expected)
                     const msg = await getSyncSagaMessageFromFrame({ frameIbGib: currentFrame, space: localSpace });
-                    if (logalot) {
-                        console.log(`${lc} Checking currentFrame stage: ${msg?.data?.stage} (Expected: ${SyncStage.commit})`);
-                    }
                     if (msg?.data?.stage === SyncStage.commit) {
                         if (logalot) {
                             console.log(`${lc} Sender sent Commit. Peer returned no response. Saga Complete.`);
@@ -282,57 +342,85 @@ export class SyncSagaCoordinator {
                         currentFrame = null;
                         break;
                     }
+                    else {
+                        throw new Error(`(UNEXPECTED) responseCtx falsy and currentFrame truthy, but we're not in the commit stage? This may be expected ultimately, but atow I am not seeing this as being expected. (E: cc34498962bd370deeff351fac939f26)`);
+                    }
+                }
+                else {
+                    throw new Error(`(UNEXPECTED) no response and currentFrame falsy? (E: 8d1085ea2f28cfc3f9c922649864a826)`);
                 }
-                throw new Error(`responseCtx falsy. Peer returned no response context (E: c099d8073b48d85e881f917835158f26)`);
-                // console.warn(`${lc} Peer returned no response context. Ending loop.`);
-                // currentFrame = null;
-                // break;
             }
-            if (logalot) {
-                console.log(`${lc} received responseCtx: ${pretty(responseCtx)} (I: 8f35c8b7a9e886aa9743d38bee907826)`);
-            }
-            updates$.next(responseCtx);
-            // D. Extract Remote Frame & React
-            const remoteFrameAddr = responseCtx.rel8ns?.sagaFrame?.[0];
-            if (!remoteFrameAddr) {
-                // If the remote didn't send a saga frame, we can't continue the protocol.
-                throw new Error(`${lc} Peer response has no sagaFrame. Ending loop. (E: 0224e84a83e1c7ee288aaed6bdc40826)`);
-            }
-            // We look in localSpace first (where Peer delivers), then tempSpace.
-            let resRemoteFrame = await getFromSpace({ addr: remoteFrameAddr, space: localSpace });
-            if (!resRemoteFrame.success || !resRemoteFrame.ibGibs?.length) {
-                // Fallback to tempSpace just in case
-                resRemoteFrame = await getFromSpace({ addr: remoteFrameAddr, space: tempSpace });
-            }
-            const remoteFrame = resRemoteFrame.ibGibs?.[0];
-            if (!remoteFrame) {
-                throw new Error(`Could not resolve remote frame: ${remoteFrameAddr}`);
-            }
-            // if (logalot) { console.log(`${lc} remoteFrame: ${pretty(remoteFrame)}`); } // leave this in for later use if needed
-            // Ensure remote frame and its dependencies are in tempSpace
-            // The Peer delivered them to localSpace, but handleSagaFrame works in tempSpace.
-            const remoteDeps = await getSyncSagaDependencyGraph({ ibGib: remoteFrame, space: localSpace });
-            if (remoteDeps && remoteDeps.length > 0) {
-                await putInSpace({ space: tempSpace, ibGibs: remoteDeps });
-            }
-            // React (Reducer)
-            // This processes the FRAME we just got from the peer.
-            // i.e., We Sent Init -> Got Ack. This calls handleAckFrame.
-            // i.e., We Sent Delta -> Got Delta. This calls handleDeltaFrame.
-            const result = await this.handleSagaFrame({
-                sagaIbGib: remoteFrame,
-                srcGraph,
-                destSpace: localSpace, // Query existing data from localSpace (Source)
-                tempSpace: tempSpace, // Transaction space for saga frames
-                identity: sessionIdentity,
-                metaspace
-            });
-            currentFrame = result?.frame || null;
-            nextPayloadIbGibs = result?.payloadIbGibs || []; // Payload to send in NEXT Ping
-            if (result?.receivedPayloadIbGibs) {
-                // Keep track of what we received for final merge
-                allReceivedIbGibs.push(...result.receivedPayloadIbGibs);
+            // ---------------------------------------------------------------------
+            // 2d. HANDLE RESPONSE
+            // ---------------------------------------------------------------------
+            if (!responseCtx.data) {
+                throw new Error(`(UNEXPECTED) responseCtx.data falsy? (E: a969992bae53ab18a827ec58aec15826)`);
+            }
+            updates$.next(responseCtx); // spins off -- don't remove this comment!
+            // 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
+            if (responsePayloadAddrsDomain.length > 0) {
+                await this.pollForDomainPayloads({
+                    expectedAddrs: responsePayloadAddrsDomain,
+                    domainPayloadsMap,
+                    tempSpace,
+                });
             }
+            // Extract Response Frame
+            const responseFrameAddr = responseCtx.rel8ns?.sagaFrame?.[0];
+            if (!responseFrameAddr) {
+                throw new Error(`${lc} Peer response missing sagaFrame (E: 83a0)`);
+            }
+            // 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}   Response Context: ${getIbGibAddr({ ibGib: responseCtx })}`);
+                console.log(`${lc}${lcControlDomain}   Response Frame: ${responseFrameAddr}`);
+                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,
+                metaspace,
+                domainPayloadsMap,
+                expectedDomainAddrs: responsePayloadAddrsDomain,
+            });
+            if (!handleResult) {
+                if (logalot) {
+                    console.log(`${lc} Handler returned null (Saga End).`);
+                }
+                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
+            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}   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.
         }
         return allReceivedIbGibs;
     }
@@ -346,7 +434,7 @@ export class SyncSagaCoordinator {
             if (logalot) {
                 console.log(`${lc} starting... (I: e184f8a7818666febfbbd2d841ed3826)`);
             }
-            console.dir(space);
+            // console.dir(space);
             if (!(domainIbGibs && domainIbGibs.length > 0) &&
                 !(tjpAddrs && tjpAddrs.length > 0)) {
                 throw new Error(`(UNEXPECTED) domainIbGibs and tjpAddrs falsy/empty? we need one or the other (E: f674285111c8648398cd79d8c08ec826)`);
@@ -361,23 +449,21 @@ export class SyncSagaCoordinator {
             }
             else if (domainIbGibs && domainIbGibs.length > 0) {
                 // Extract TJPs from domain Ibgibs
-                if (logalot) {
-                    console.log(`${lc} domainIbGibs (${domainIbGibs.length}) provided.  (I: a378995a0658af1f086ac1f297486c26)`);
-                }
+                // if (false) { console.log(`${lc} domainIbGibs (${domainIbGibs.length}) provided.  (I: a378995a0658af1f086ac1f297486c26)`); }
                 const { mapWithTjp_YesDna, mapWithTjp_NoDna } = splitPerTjpAndOrDna({ ibGibs: domainIbGibs });
-                if (logalot) {
+                if (false) {
                     console.log(`${lc}[TEST DEBUG] mapWithTjp_YesDna: ${JSON.stringify(mapWithTjp_YesDna)} (I: 287e22897148298e185712c8d50cfb26)`);
                 }
-                if (logalot) {
+                if (false) {
                     console.log(`${lc}[TEST DEBUG] mapWithTjp_NoDna: ${JSON.stringify(mapWithTjp_NoDna)} (I: 1bdc62656294aed0f9df334647dc7326)`);
                 }
                 const allWithTjp = [...Object.values(mapWithTjp_YesDna), ...Object.values(mapWithTjp_NoDna)];
                 const timelineMap = getTimelinesGroupedByTjp({ ibGibs: allWithTjp });
-                if (logalot) {
+                if (false) {
                     console.log(`${lc}[TEST DEBUG] timelineMap: ${JSON.stringify(timelineMap)} (I: 2cc04898e5f85179fb1ac7f827abc426)`);
                 }
                 tjps = Object.keys(timelineMap);
-                if (logalot) {
+                if (false) {
                     console.log(`${lc}[TEST DEBUG] tjps: ${tjps} (I: 3dd548667cbd967c68e57c88dc570826)`);
                 }
             }
@@ -390,16 +476,14 @@ export class SyncSagaCoordinator {
             if (tjps.length === 0) {
                 return {};
             }
-            if (logalot) {
+            if (false) {
                 console.log(`${lc} getting latest addrs for tjps: ${tjps} (I: d4e7080b8ba8187c583b82fd91ac0626)`);
             }
             const res = await getLatestAddrs({ space, tjpAddrs: tjps });
             if (!res.data || !res.data.latestAddrsMap) {
                 throw new Error(`${lc} Failed to get latest addrs. (E: 7a8b9c0d)`);
             }
-            if (logalot) {
-                console.log(`${lc}[TEST DEBUG] res.data.latestAddrsMap: ${JSON.stringify(res.data.latestAddrsMap)} (I: a8e128bdf80898ac2e6d8021a5bff726)`);
-            }
+            // if (false) { console.log(`${lc}[TEST DEBUG] res.data.latestAddrsMap: ${JSON.stringify(res.data.latestAddrsMap)} (I: a8e128bdf80898ac2e6d8021a5bff726)`); }
             return res.data.latestAddrsMap;
         }
         catch (error) {
@@ -503,18 +587,55 @@ export class SyncSagaCoordinator {
         }
     }
     /**
-     * Reacts to an incoming saga frame and dispatches to appropriate handler.
-     *
-     * @remarks
-     * **Execution Context**: **Universal (Both Sender and Receiver)**.
-     *
-     * This method acts as the "Reducer" for the Sync FSM. It determines the current stage
-     * based on the incoming frame and delegates to the appropriate handler.
-     *
-     * *   If running on **Receiver**: Handles `Init` (via `handleInitFrame`).
-     * *   If running on **Sender**: Handles `Ack` (via `handleAckFrame`).
-     * *   If running on **Either**: Handles `Delta` (via `handleDeltaFrame`) or `Commit`.
+     * Helper to poll for streaming domain payloads and put them in the
+     * local {@link tempSpace}.
      */
+    async pollForDomainPayloads({ expectedAddrs, domainPayloadsMap, tempSpace, }) {
+        const lc = `${this.lc}[${this.pollForDomainPayloads.name}]`;
+        try {
+            if (logalot) {
+                console.log(`${lc} starting... (I: 26dce86bfca572939885798802d6e926)`);
+            }
+            let pending = [...expectedAddrs];
+            const start = Date.now();
+            /**
+             * This needs
+             */
+            const timeoutMs = 5 * 60 * 1000; // 5 minutes...arbitrary at this point. This needs to be pulled out and improved eesh.
+            while (pending.length > 0) {
+                if (Date.now() - start > timeoutMs) {
+                    throw new Error(`Timeout waiting for payloads: ${pending.join(', ')} (E: 46e1683c9578095261aaf798bd5e1826)`);
+                }
+                const stillPending = [];
+                const found = [];
+                for (const addr of pending) {
+                    if (domainPayloadsMap.has(addr)) {
+                        found.push(domainPayloadsMap.get(addr));
+                        domainPayloadsMap.delete(addr);
+                    }
+                    else {
+                        stillPending.push(addr);
+                    }
+                }
+                if (found.length > 0) {
+                    await putInSpace({ space: tempSpace, ibGibs: found });
+                }
+                pending = stillPending;
+                if (pending.length > 0) {
+                    await new Promise(resolve => setTimeout(resolve, 50));
+                }
+            }
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+        finally {
+            if (logalot) {
+                console.log(`${lc} complete.`);
+            }
+        }
+    }
     async handleSagaFrame({ sagaIbGib, srcGraph, destSpace, tempSpace, identity, identitySecret, metaspace, }) {
         const lc = `${this.lc}[${this.handleSagaFrame.name}]`;
         try {
@@ -838,7 +959,12 @@ export class SyncSagaCoordinator {
         // 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)`); }
-        return { frame: ackFrame };
+        // Build control payloads: frame + its dependencies (msg stone, identity)
+        const payloadIbGibsControl = [ackFrame, ackStone];
+        if (identity) {
+            payloadIbGibsControl.push(identity);
+        }
+        return { frame: ackFrame, payloadIbGibsControl };
     }
     /**
      * Handles the `Ack` frame.
@@ -938,50 +1064,7 @@ export class SyncSagaCoordinator {
                         // PULL these frames from Peer into Local Space
                         // (Validation: We trust peer for now / verification happens on put)
                         for (const addr of receiverOnlyAddrs) {
-                            // This 'pull' is a sync-peer method?
-                            // The Coordinator 'peer' passed in 'sync()' might be needed here?
-                            // Wait, `handleAckFrame` doesn't have reference to `peer`?
-                            // It only has `space`, `metaspace`.
-                            // The `peer` is held by the `executeSagaLoop`.
-                            // PROBLEM: `handleAckFrame` is pure logic on the Space/Data?
-                            // No, it's a method on Coordinator. 
-                            // But `executeSagaLoop` calls it.
-                            // We might need to return "Requirements" to the loop?
-                            // Checking return type: `{ frame: SyncIbGib_V1, payloadIbGibs?: ... }`
-                            // It returns the NEXT frame (Delta).
-                            // If we need to fetch data, we are blocked.
-                            // We can't easily "Pull" here without the Peer reference.
-                            // OPTION A: Pass `peer` to `handleAckFrame`.
-                            // OPTION B: Return a strict list of "MissingDeps" and let Loop handle it.
-                            // Let's assume we can resolve this by adding `peer` to signature or using `metaspace` if it's a peer-witness?
-                            // No, Peer is ephemeral connection.
-                            // Let's add `peer` to `handleAckFrame` signature?
-                            // It breaks the pattern of just handling frame + space.
-                            // ALTERNATIVE: Use the `Delta` frame to request data?
-                            // `SyncSagaMessageDeltaData` has `requests?: string[]`.
-                            // Sender sends Delta Frame.
-                            // Does Receiver handle Delta Requests?
-                            // `handleDeltaFrame` (Receiver) -> checks `requests`.
-                            // YES.
-                            // So Sender puts `receiverOnlyAddrs` into `deltaFrame.requests`.
-                            // Receiver sees them, fetches them, and includes them in the Response (Commit?).
-                            // Wait, Init->Ack->Delta->Commit.
-                            // If Receiver sends data in Commit, that's "too late" for Sender to Merge in THIS saga round?
-                            // Unless Commit is not the end?
-                            // Or we do a "Delta 2" loop?
-                            // "Iterative Resolution Loop" from plan.
-                            // If we request data in Delta, Receiver sends it in Commit (or Delta-Response).
-                            // Sender gets Commit. Sees data. Merges.
-                            // Then Sender needs to Send the MERGE result.
-                            // Needs another Push/Delta.
-                            // REFINED FLOW:
-                            // 1. Sender sends Delta Frame with `requests: [receiverOnlyAddrs]`.
-                            // 2. Receiver responds (Commit? or Ack 2?) with Payload (Divergent Frames).
-                            // 3. Sender handles response -> Merges.
-                            // 4. Sender sends Commit (containing Merge Frame).
-                            // Issue: Current state machine is Init->Ack->Delta->Commit.
-                            // We need to keep Saga open.
-                            // If Sender sends Delta with requests, does it transition to Commit?
+                            console.error(`${lc} [CONFLICT DEBUG] NOT IMPLEMENTED (E: e6bf1a9d2758c469bb2f97514062d826)`);
                         }
                         // Compute DELTA dependencies for each receiver-only frame
                         // Find LCA to determine what dependencies we already have
@@ -1153,7 +1236,12 @@ export class SyncSagaCoordinator {
             if (logalot) {
                 console.log(`${lc} Delta Frame created. Rel8ns: ${JSON.stringify(deltaFrame.rel8ns)}`);
             }
-            return { frame: deltaFrame, payloadIbGibs };
+            // Build control payloads: frame + its dependencies (msg stone, identity)
+            const payloadIbGibsControl = [deltaFrame, deltaStone];
+            if (identity) {
+                payloadIbGibsControl.push(identity);
+            }
+            return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: payloadIbGibs };
         }
         catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -1378,7 +1466,12 @@ export class SyncSagaCoordinator {
             });
             // IMMEDIATELY persist to both spaces for audit trail
             await this.ensureSagaFrameInBothSpaces({ frame: deltaFrame, destSpace, tempSpace, metaspace });
-            return { frame: deltaFrame, payloadIbGibs: outgoingPayload, receivedPayloadIbGibs };
+            // Build control payloads: frame + its dependencies (msg stone, identity)
+            const payloadIbGibsControl = [deltaFrame, deltaStone];
+            if (identity) {
+                payloadIbGibsControl.push(identity);
+            }
+            return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: outgoingPayload };
         }
         else {
             // We have nothing to send.
@@ -1403,7 +1496,12 @@ export class SyncSagaCoordinator {
                 });
                 // IMMEDIATELY persist to both spaces for audit trail
                 await this.ensureSagaFrameInBothSpaces({ frame: commitFrame, destSpace, tempSpace, metaspace });
-                return { frame: commitFrame, receivedPayloadIbGibs };
+                // Build control payloads for commit
+                const commitCtrlPayloads = [commitFrame, commitStone];
+                if (identity) {
+                    commitCtrlPayloads.push(identity);
+                }
+                return { frame: commitFrame, payloadIbGibsControl: commitCtrlPayloads };
             }
             else {
                 // peer did NOT propose commit (maybe they just sent data/requests and didn't ready flag).
@@ -1455,9 +1553,19 @@ export class SyncSagaCoordinator {
                     });
                     // IMMEDIATELY persist to both spaces for audit trail
                     await this.ensureSagaFrameInBothSpaces({ frame: commitFrame, destSpace, tempSpace, metaspace });
-                    return { frame: commitFrame, receivedPayloadIbGibs };
+                    // Build control payloads for commit
+                    const commitCtrlPayloads2 = [commitFrame, commitStone];
+                    if (identity) {
+                        commitCtrlPayloads2.push(identity);
+                    }
+                    return { frame: commitFrame, payloadIbGibsControl: commitCtrlPayloads2 };
+                }
+                // Build control payloads for delta propose
+                const deltaCtrlPayloads = [deltaFrame, deltaStone];
+                if (identity) {
+                    deltaCtrlPayloads.push(identity);
                 }
-                return { frame: deltaFrame, receivedPayloadIbGibs };
+                return { frame: deltaFrame, payloadIbGibsControl: deltaCtrlPayloads };
             }
         }
     }