@ibgib/core-gib 0.1.27 → 0.1.28

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

@@ -31,8 +31,9 @@ import {
     SYNC_CONFLICT_STRATEGY_VALID_VALUES, HandleSagaResponseContextResult,
     SyncExecutionContext,
     SYNC_EXECUTION_CONTEXT_VALID_VALUES,
+    SyncSagaFrameDependencyGraph,
 } from "./sync-types.mjs";
-import { getExecutionContext, getSyncIb, getTempSpaceName, isPastFrame } from "./sync-helpers.mjs";
+import { getExecutionContext, getFullSyncSagaHistory, getSyncIb, getTempSpaceName, isPastFrame, putInSpace_dnasThenNonDnas, validateFullSyncSagaHistory } from "./sync-helpers.mjs";
 import { getDeltaDependencyGraph, getDependencyGraph, toFlatGraph } from "../common/other/graph-helper.mjs";
 import {
     SyncSagaMessageData_V1, SyncSagaMessageInitData_V1,
@@ -76,10 +77,10 @@ const lcControlDomain = '[ControlDomain]';
  * to a specific Saga session, not fixed node identities.
  */
 export class SyncSagaCoordinator {
-    protected lc: string = `[${SyncSagaCoordinator.name}]`;
+    private lc: string = `[${SyncSagaCoordinator.name}]`;
 
     constructor(
-        protected keystone: KeystoneService_V1
+        private keystone: KeystoneService_V1
     ) {
 
     }
@@ -240,7 +241,11 @@ export class SyncSagaCoordinator {
 
             if (!contextResult) {
                 if (logalot) { console.log(`${lc} Handler returned null (Saga End). (I: 43da8bb6c846b1fe7766332643be0e26)`); }
-                return null;
+                // does this ever hit now?
+                return null; /* <<<< returns early */
+            } else if (contextResult.nextFrameInfo?.sagaComplete) {
+                // this is the current proper workflow I believe as of 01/22/2026
+                return null; /* <<<< returns early */
             }
 
             // #region error conditions throw
@@ -248,8 +253,6 @@ export class SyncSagaCoordinator {
                 throw new Error(`Couldn't handle response saga context. errorMsg: ${contextResult.errorMsg} (E: 7b41a183cf3cb58a5859c803800cf826)`);
             } else if (!contextResult.nextFrameInfo) {
                 throw new Error(`(UNEXPECTED) contextResult.nextFrameInfo falsy? (E: 5740542f5eb8ccb41dfec188d87c1e26)`);
-            } else if (contextResult.nextFrameInfo?.responseWasNull) {
-                throw new Error(`(UNEXPECTED) contextResult.nextFrameInfo.responseWasNull? logic flow should not have gotten here. (E: ae06748d8c0c5e70c92322c8fb0cb426)`);
             }
             // #endregion error conditions throw
 
@@ -278,7 +281,7 @@ export class SyncSagaCoordinator {
         }
     }
 
-    protected async getSessionIdentity({
+    private async getSessionIdentity({
         sagaId,
         metaspace,
         tempSpace,
@@ -329,7 +332,7 @@ export class SyncSagaCoordinator {
      * the NEXT request context.
      * When the Peer responds with data (in the response context), it is resolved and put into `tempSpace`.
      */
-    protected async executeSagaLoop({
+    private async executeSagaLoop({
         initFrame,
         initDomainGraph,
         peer,
@@ -511,8 +514,8 @@ export class SyncSagaCoordinator {
                 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)`);
+            } else if (contextResult.nextFrameInfo?.sagaComplete) {
+                throw new Error(`(UNEXPECTED) contextResult.nextFrameInfo.sagaComplete? logic flow should not have gotten here. (E: 104a32381db816b7183435e805b3d626)`);
             }
             // #endregion error conditions throw
 
@@ -610,7 +613,7 @@ export class SyncSagaCoordinator {
         }
     }
 
-    protected async analyzeDomainIbGibs({
+    private async analyzeDomainIbGibs({
         domainIbGibs,
         space,
     }: {
@@ -656,7 +659,7 @@ 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.
      */
-    protected async createInitFrame({
+    private async createInitFrame({
         sagaId,
         sessionIdentity,
         domainIbGibs,
@@ -739,7 +742,7 @@ export class SyncSagaCoordinator {
      *
      * @returns when all {@link expectedAddrs} are done being transmitted.
      */
-    protected async pollForDomainPayloads({
+    private async pollForDomainPayloads({
         expectedAddrs,
         pollIntervalMs,
         domainPayloadsMap,
@@ -824,7 +827,7 @@ export class SyncSagaCoordinator {
      *
      * This is a one-off on the receiver.
      */
-    public async handleResponseSagaContext({
+    private async handleResponseSagaContext({
         sagaContext,
         initDomainGraph,
         mySpace,
@@ -940,7 +943,7 @@ export class SyncSagaCoordinator {
      * 3.  Identifies what Receiver needs (`deltaRequestAddrInfos`).
      * 4.  Returns an `Ack` frame containing these lists.
      */
-    protected async handleInitFrame({
+    private async handleInitFrame({
         sagaIbGib,
         messageData,
         mySpace,
@@ -1289,7 +1292,7 @@ export class SyncSagaCoordinator {
      *
      * Returns a `Delta` frame.
      */
-    protected async handleAckFrame({
+    private async handleAckFrame({
         sagaContext,
         sagaIbGib,
         initDomainGraph,
@@ -1565,70 +1568,6 @@ export class SyncSagaCoordinator {
         }
     }
 
-    private async getPayloadsForRequestedInfos({
-        deltaRequestAddrInfos,
-        mySpace,
-    }: {
-        deltaRequestAddrInfos: SyncSagaRequestAddrInfo[];
-        mySpace: IbGibSpaceAny;
-    }): Promise<IbGib_V1[]> {
-        const lc = `${this.lc}[${this.getPayloadsForRequestedInfos.name}]`;
-        try {
-            if (logalot) { console.log(`${lc} starting... (I: 4fe13d0d80050f20a8b74ba80cee5826)`); }
-            /**
-             * graph of ibgibs we will send to the receiver. addr-based, so will
-             * already be unique (no need to call `unique` on the domains
-             * ibgibs)
-             */
-            const outgoingPayloadIbGibsDomainGraph: FlatIbGibGraph = {};
-            for (const { addr, latestAddrAlreadyHave } of deltaRequestAddrInfos) {
-                let deltaDepGraph: FlatIbGibGraph;
-                if (latestAddrAlreadyHave) {
-                    // already has some, so only get the delta
-                    // remember: if we didn't have the other's latest addr, then
-                    // this would be in the conflicts not requested addrs
-                    deltaDepGraph = await getDeltaDependencyGraph({
-                        ibGibAddr: addr,
-                        latestCommonFrameAddr: latestAddrAlreadyHave,
-                        space: mySpace,
-                        live: true,
-                    });
-                } else {
-                    // doesn't have anything, so get the entire dependency graph
-                    // INEFFICIENT: we've already gotten all of the domain
-                    // dependencies in initDomainGraph, but getDependencyGraph
-                    // only works against a space so we are going to rerun this.
-                    // an optimization would be to adapt/create a new
-                    // getDependencyGraph to work against an existing flat ibgib
-                    // map.
-                    deltaDepGraph = await getDependencyGraph({
-                        ibGibAddr: addr,
-                        space: mySpace,
-                        live: true,
-                    });
-                }
-
-                const depGraphSize = Object.keys(deltaDepGraph).length;
-                if (depGraphSize === 0) {
-                    throw new Error(`(UNEXPECTED) couldn't get requested addrs in mySpace (${mySpace.ib})? How did the receiver know to ask for these addrs if they weren't in our original graph? (E: 281eaebcdf77dd73e8245b2872100826)`);
-                } else {
-                    // we have dependencies!
-                    Object.values(deltaDepGraph).forEach(x => {
-                        outgoingPayloadIbGibsDomainGraph[getIbGibAddr({ ibGib: x })] = x;
-                    });
-                }
-            }
-
-            const result = Object.values(outgoingPayloadIbGibsDomainGraph);
-            return result;
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
-        } finally {
-            if (logalot) { console.log(`${lc} complete.`); }
-        }
-    }
-
     /**
      * Handles the `Delta` frame.
      *
@@ -1639,7 +1578,7 @@ export class SyncSagaCoordinator {
      * 2.  **Fulfillment**: Checks `requests`. If Peer requested data, gathers it and prepares `outgoingPayload`.
      * 3.  **Completion**: If no more requests, transitions to `Commit`.
      */
-    protected async handleDeltaFrame({
+    private async handleDeltaFrame({
         sagaContext,
         sagaIbGib,
         srcGraph,
@@ -1701,27 +1640,32 @@ export class SyncSagaCoordinator {
                 // V1 timelines carry full history in `past`.
                 const pastAddrs = sagaIbGib.rel8ns?.past || [];
                 console.log(`${lc} [TEST DEBUG] pastAddrs count: ${pastAddrs.length}`);
-                let ackData: SyncSagaMessageAckData_V1 | undefined;
-
-                if (pastAddrs.length > 0) {
-                    // Batch fetch all past frames
-                    const resPast = await getFromSpace({ addrs: pastAddrs, space: myTempSpace });
-                    if (resPast.success && resPast.ibGibs) {
-                        // Iterate backwards (most recent first) to find the latest Ack
-                        for (let i = resPast.ibGibs.length - 1; i >= 0; i--) {
-                            const pastFrame = resPast.ibGibs[i];
-                            const messageStone = await getSyncSagaMessageFromFrame({
-                                frameIbGib: pastFrame,
-                                space: myTempSpace
-                            });
-                            if (messageStone?.data?.stage === SyncStage.ack) {
-                                ackData = messageStone.data as SyncSagaMessageAckData_V1;
-                                console.log(`${lc} [TEST DEBUG] Found Ack Frame. Conflicts: ${ackData.conflicts?.length || 0}`);
-                                break;
-                            }
-                        }
-                    }
+
+                const sagaHistory = await getFullSyncSagaHistory({
+                    sagaIbGib,
+                    space: mySpace,
+                });
+                // #region validate/sanity sagaHistory
+                if (sagaHistory.length === 0) { throw new Error(`(UNEXPECTED) sagaHistory.length is 0? We're in handleDeltaFrame. So we should have at least init and ack. (E: 815735c9cf756b275719bf434f180826)`); }
+                if (sagaHistory.length === 1) { throw new Error(`(UNEXPECTED) sagaHistory.length is 1? We're in handleDeltaFrame. So we should have at least init and ack. (E: 0e4ef8e3ed088e83b2cdcd18ecea9826)`); }
+                // #endregion validate/sanity sagaHistory
+
+                const ackGraphs = sagaHistory.filter(x =>
+                    x.msgStones.at(0)!.data!.stage === SyncStage.ack
+                );
+                // #region validate/sanity ackGraphs
+                if (ackGraphs.length > 1) {
+                    throw new Error(`(UNEXPECTED) more than one ack stage found in sagaHistory? we're expecting exactly one. (E: 7150983bb3a841caf8acd60826ba4f26)`);
+                } else if (ackGraphs.length === 0) {
+                    throw new Error(`(UNEXPECTED) couldn't find ack stage in sagaHistory? (E: 7d2da859196b86de28e7c8183af1e826)`);
+                }
+                if (ackGraphs[0].msgStones.length !== 1) {
+                    throw new Error(`(UNEXPECTED) ackGraph has more than one msg stone? only one expected right now. (E: f07d388abff8d26f98cbf6e8d3932826)`);
                 }
+                // #endregion validate/sanity ackGraphs
+
+                const ackData = ackGraphs[0].msgStones[0].data as SyncSagaMessageAckData_V1;
+                if (!ackData) { throw new Error(`(UNEXPECTED) ackData falsy? (E: f9af88427f66a8db1ba868b810e8b826)`); }
 
                 if (ackData && ackData.conflicts) {
                     const optimisticConflicts = ackData.conflicts.filter(c => !c.terminal);
@@ -1785,20 +1729,8 @@ export class SyncSagaCoordinator {
                     stage: SyncStage.delta,
                     payloadAddrs: outgoingPayload.map(p => getIbGibAddr({ ibGib: p })),
                     requests: hasMyRequests ? myRequests : undefined,
-                    proposeCommit: !hasMyRequests // If we are sending data but have no requests, we VALIDATE PROPOSAL?
-                    // Wait. If we send data, we are NOT committing yet.
-                    // We are sending data. The OTHER side must ingest it.
-                    // So proposeCommit = true?
-                    // "Here is the data. I'm done. If you are good, let's commit."
-                    // Yes.
                 };
 
-                // BUT if `peerProposesCommit` was true, and we are sending data, we are effectively rejecting/delaying it.
-                // We just send the Delta. Peer receives it, ingests, sees ProposeCommit=True (from us), and then Commits.
-
-                // So yes, proposeCommit = true.
-                responseDeltaData.proposeCommit = true;
-
                 const deltaStone = await this.createSyncMsgStone({
                     data: responseDeltaData,
                     localSpace: mySpace,
@@ -1813,42 +1745,45 @@ export class SyncSagaCoordinator {
                     metaspace,
                 });
 
-                // Build control payloads: frame + its dependencies (msg stone, identity)
-                const payloadIbGibsControl: IbGib_V1[] = [deltaFrame, deltaStone];
-                if (identity) { payloadIbGibsControl.push(identity); }
-
-                // return { frame: deltaFrame, payloadIbGibsControl, payloadIbGibsDomain: outgoingPayload };
                 return { frame: deltaFrame, payloadIbGibsDomain: outgoingPayload };
-                // throw new Error(`not implemented (E: 2b38a8afb6d84efcee5ab51673387826)`);
-
             } else {
                 // We have nothing to send.
 
                 if (peerProposesCommit) {
                     // Peer is done. We are done. -> Commit.
-                    const commitData: SyncSagaMessageCommitData_V1 = {
-                        sagaId: deltaData.sagaId,
-                        stage: SyncStage.commit,
-                        success: true,
-                    };
-
-                    const commitStone = await this.createSyncMsgStone({
-                        data: commitData,
-                        localSpace: mySpace,
-                        metaspace
+                    // one last validate entire history?
+                    const history = await getFullSyncSagaHistory({
+                        sagaIbGib,
+                        space: mySpace,
                     });
+                    const validationErrors = await validateFullSyncSagaHistory({
+                        history,
+                    });
+                    if (validationErrors.length > 0) {
+                        const errorCommitFrame = await this.createCommitFrame({
+                            sagaIbGib,
+                            errors: validationErrors,
+                            metaspace, mySpace,
+                            identity,
+                        });
+                        return { frame: errorCommitFrame, }; /* <<<< returns early */
+                    }
 
-                    const commitFrame = await this.evolveSyncSagaIbGib({
-                        prevSagaIbGib: sagaIbGib,
-                        msgStones: [commitStone],
-                        sessionIdentity: identity,
+                    await this.executeLocalCommit({
+                        sagaHistory: history,
+                        deltaFrame: sagaIbGib,
+                        localTempSpace: myTempSpace,
                         localSpace: mySpace,
-                        metaspace
-                    });
+                        metaspace,
+                    })
 
-                    // Build control payloads for commit
-                    const commitCtrlPayloads: IbGib_V1[] = [commitFrame, commitStone];
-                    if (identity) { commitCtrlPayloads.push(identity); }
+                    const commitFrame = await this.createCommitFrame({
+                        sagaIbGib,
+                        errors: undefined,
+                        metaspace,
+                        mySpace,
+                        identity,
+                    });
 
                     return { frame: commitFrame, };
 
@@ -1924,9 +1859,190 @@ export class SyncSagaCoordinator {
         }
 
     }
+    /**
+     * should throw if fails
+     */
+    private async executeLocalCommit({
+        deltaFrame,
+        sagaHistory,
+        metaspace, localSpace, localTempSpace,
+        identity,
+    }: {
+        deltaFrame: SyncIbGib_V1;
+        sagaHistory: SyncSagaFrameDependencyGraph[];
+        metaspace: MetaspaceService;
+        localSpace: IbGibSpaceAny;
+        localTempSpace: IbGibSpaceAny;
+        identity?: KeystoneIbGib_V1;
+    }): Promise<void> {
+        const lc = `${this.lc}[${this.executeLocalCommit.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 6734980446b86a63c1af6e2e206de826)`); }
+
+            // #region validate/sanity
+            if (!deltaFrame.data) { throw new Error(`(UNEXPECTED) deltaFrame.data falsy? (E: a8be68d48668d93d992d793834823826)`); }
+            // #endregion validate/sanity
 
+            // * move all payload addrs from temp space to local space
+            // * register each and every iteration of each timeline (including
+            //   stones, which are like their own sealed timeline of length 1)
+
+            const allPayloadAddrsDomainTransferred: IbGibAddr[] = [];
+            const fnAddPayloadAddr = (addr: IbGibAddr) => {
+                if (!allPayloadAddrsDomainTransferred.includes(addr)) {
+                    allPayloadAddrsDomainTransferred.push(addr);
+                }
+            }
 
-    protected async handleCommitFrame({
+            sagaHistory.forEach(x => {
+                if (!x.sagaIbGib.data) { throw new Error(`(UNEXPECTED) sagaIbGib.data falsy? (E: 34d7f8cdee14717ce828878d98f89826)`); }
+                x.msgStones.forEach(msgStone => {
+                    if (!msgStone.data) { throw new Error(`(UNEXPECTED) msgStone.data falsy? (E: 21406101f91847514cc759c8a7382f26)`); }
+                    if (msgStone.data.stage === SyncStage.ack) {
+                        const ackData = msgStone.data as SyncSagaMessageAckData_V1;
+                        if (ackData.pushOfferInfos && ackData.pushOfferInfos.length > 0) {
+                            ackData.pushOfferInfos.forEach(info => {
+                                info.addrs.forEach(addr => fnAddPayloadAddr(addr));
+                            });
+                        }
+                    } else if (msgStone.data.stage === SyncStage.delta) {
+                        const deltaData = msgStone.data as SyncSagaMessageDeltaData_V1;
+                        if (deltaData.payloadAddrsDomain && deltaData.payloadAddrsDomain.length > 0) {
+                            deltaData.payloadAddrsDomain.forEach(addr => fnAddPayloadAddr(addr));
+                        }
+                    }
+                })
+            });
+
+            // at this point, we have a list of ALL payload addrs retrieved.
+            let allPayloadIbGibsDomainTransferred: IbGib_V1[] = [];
+            const resGetAllTransferred =
+                await getFromSpace({ addrs: allPayloadAddrsDomainTransferred, space: localTempSpace });
+            if (resGetAllTransferred.success && resGetAllTransferred.ibGibs && resGetAllTransferred.ibGibs.length === allPayloadAddrsDomainTransferred.length) {
+                allPayloadIbGibsDomainTransferred = resGetAllTransferred.ibGibs.concat();
+            } else {
+                // errored out, gather info
+                if (!resGetAllTransferred.rawResultIbGib) { throw new Error(`(UNEXPECTED) !resGetAllTransferred.rawResultIbGib falsy? (E: dc6cf8729668f4fbe8c024f887d97a26)`); }
+                const { addrsNotFound, addrsErrored, errors } = resGetAllTransferred.rawResultIbGib.data as IbGibSpaceResultData;
+                throw new Error(`(UNEXPECTED) we couldn't get all addrs transferred throughout the saga from the tempspace (${localTempSpace.ib})? addrsNotFound: ${addrsNotFound ?? []}. addrsErrored: ${addrsErrored ?? []}. errors: ${errors ?? []}(E: 222e341e634862b4d88ae7282584d826)`);
+            }
+
+            // now we have all ibgibs transferred, first put them all the local space
+
+            const { payload_Dnas, payload_NonDnas } =
+                await putInSpace_dnasThenNonDnas({
+                    ibGibs: allPayloadIbGibsDomainTransferred,
+                    space: localSpace
+                });
+
+            const { mapWithTjp_NoDna, mapWithTjp_YesDna, mapWithoutTjps } =
+                splitPerTjpAndOrDna({ ibGibs: payload_NonDnas, filterPrimitives: true });
+
+            // first register all non-tjp stones
+            const nontjps = Object.values(mapWithoutTjps);
+            for (const nontjp of nontjps) {
+                await metaspace.registerNewIbGib({
+                    ibGib: nontjp,
+                    space: localSpace,
+                });
+            }
+
+            // next register each timeline in order...
+
+            // ...first the ones without dna...
+            const timelinesByTjpAddr_NoDna =
+                getTimelinesGroupedByTjp({ ibGibs: Object.values(mapWithTjp_NoDna) });
+            const tjpAddrs_NoDna = Object.keys(timelinesByTjpAddr_NoDna);
+            for (const tjpAddr_NoDna of tjpAddrs_NoDna) {
+                const timelineIbGibs = timelinesByTjpAddr_NoDna[tjpAddr_NoDna];
+                for (const ibGib of timelineIbGibs) {
+                    await metaspace.registerNewIbGib({
+                        ibGib,
+                        space: localSpace,
+                    });
+                }
+            }
+
+            // ...then the ones WITH dna.
+            const timelinesByTjpAddr_YesDna =
+                getTimelinesGroupedByTjp({ ibGibs: Object.values(mapWithTjp_YesDna) });
+            const tjpAddrs_YesDna = Object.keys(timelinesByTjpAddr_YesDna);
+            for (const tjpAddr_YesDna of tjpAddrs_YesDna) {
+                const timelineIbGibs = timelinesByTjpAddr_YesDna[tjpAddr_YesDna];
+                for (const ibGib of timelineIbGibs) {
+                    await metaspace.registerNewIbGib({
+                        ibGib,
+                        space: localSpace,
+                    });
+                }
+            }
+
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    private async createCommitFrame({
+        sagaIbGib,
+        errors,
+        metaspace,
+        mySpace,
+        identity,
+    }: {
+        sagaIbGib: SyncIbGib_V1,
+        /**
+         * if truthy and non-empty, will create an errored commit frame (data
+         * has `success: false`)
+         */
+        errors?: string[],
+        metaspace: MetaspaceService,
+        mySpace: IbGibSpaceAny,
+        identity: KeystoneIbGib_V1 | undefined,
+    }): Promise<SyncIbGib_V1> {
+        const lc = `[${this.createCommitFrame.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 48fc57c023f80122135a284855757526)`); }
+            const commitData: SyncSagaMessageCommitData_V1 = errors && errors.length > 0 ?
+                {
+                    // errored
+                    sagaId: sagaIbGib.data!.uuid,
+                    stage: SyncStage.commit,
+                    success: false,
+                    errors,
+                } :
+                {
+                    // not errored
+                    sagaId: sagaIbGib.data!.uuid,
+                    stage: SyncStage.commit,
+                    success: true,
+                };
+
+            const commitStone = await this.createSyncMsgStone({
+                data: commitData,
+                localSpace: mySpace,
+                metaspace
+            });
+            const commitFrame = await this.evolveSyncSagaIbGib({
+                prevSagaIbGib: sagaIbGib,
+                msgStones: [commitStone],
+                sessionIdentity: identity,
+                localSpace: mySpace,
+                metaspace,
+            });
+            return commitFrame;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    private async handleCommitFrame({
         sagaIbGib,
         mySpace,
         myTempSpace,
@@ -1943,7 +2059,7 @@ export class SyncSagaCoordinator {
         try {
             if (logalot) { console.log(`${lc} starting... (I: e179573bdd881202f8ba3168da1c3826)`); }
 
-
+            let resNextSagaFrameInfo: NextSagaFrameInfo;
 
             // Sender Logic (Finalizing):
             // If we are here, we received a Commit frame from the Peer.
@@ -1951,15 +2067,52 @@ export class SyncSagaCoordinator {
             // We should now:
             // 1. Validate (implicitly done by receiving valid frame)
             // 2. Perform our own cleanup (Temp -> Dest, if applicable)
-            // 3. Return null to signal saga completion.
+            // 3. Return saga completion.
 
-            // Note: Currently we don't have explicit cleanup logic implemented here yet (TODO).
+            // one last validate entire history?
+            const history = await getFullSyncSagaHistory({
+                sagaIbGib,
+                space: mySpace,
+            });
+            const validationErrors = await validateFullSyncSagaHistory({
+                history,
+            });
+            if (validationErrors.length > 0) {
+                const errorCommitFrame = await this.createCommitFrame({
+                    sagaIbGib,
+                    metaspace,
+                    mySpace,
+                    identity,
+                    errors: validationErrors,
+                });
+                return { frame: errorCommitFrame, }; /* <<<< returns early */
+            }
+
+            await this.executeLocalCommit({
+                deltaFrame: sagaIbGib,
+                sagaHistory: history,
+                localSpace: mySpace,
+                localTempSpace: myTempSpace,
+                metaspace,
+            });
+
+            // todo: implement explicit cleanup logic here and in peer
+            console.error(`${lc} NAG ERROR (NOT THROWN): implement cleanup logic, including add a cleanup method to the peer (E: 3a9a24befb98a981a88fbdbf52920e26)`);
             if (logalot) { console.log(`${lc} Peer committed. Finalizing saga locally. Saga Complete.`); }
 
-            return { responseWasNull: true };
+            // the holy grail!
+            return { sagaComplete: true };
         } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`);
-            throw error;
+            const emsg = `${lc} ${extractErrorMsg(error)}`;
+            console.error(emsg);
+            const errorCommitFrame = await this.createCommitFrame({
+                sagaIbGib,
+                errors: [emsg],
+                metaspace,
+                mySpace,
+                identity,
+            });
+            return { frame: errorCommitFrame }
         } finally {
             if (logalot) { console.log(`${lc} complete.`); }
         }
@@ -1968,7 +2121,7 @@ export class SyncSagaCoordinator {
 
     // #endregion Handlers
 
-    protected async createSyncMsgStone<TStoneData extends SyncSagaMessageData_V1>({
+    private async createSyncMsgStone<TStoneData extends SyncSagaMessageData_V1>({
         data,
         localSpace,
         metaspace,
@@ -2000,11 +2153,75 @@ export class SyncSagaCoordinator {
         }
     }
 
+    private async getPayloadsForRequestedInfos({
+        deltaRequestAddrInfos,
+        mySpace,
+    }: {
+        deltaRequestAddrInfos: SyncSagaRequestAddrInfo[];
+        mySpace: IbGibSpaceAny;
+    }): Promise<IbGib_V1[]> {
+        const lc = `${this.lc}[${this.getPayloadsForRequestedInfos.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 4fe13d0d80050f20a8b74ba80cee5826)`); }
+            /**
+             * graph of ibgibs we will send to the receiver. addr-based, so will
+             * already be unique (no need to call `unique` on the domains
+             * ibgibs)
+             */
+            const outgoingPayloadIbGibsDomainGraph: FlatIbGibGraph = {};
+            for (const { addr, latestAddrAlreadyHave } of deltaRequestAddrInfos) {
+                let deltaDepGraph: FlatIbGibGraph;
+                if (latestAddrAlreadyHave) {
+                    // already has some, so only get the delta
+                    // remember: if we didn't have the other's latest addr, then
+                    // this would be in the conflicts not requested addrs
+                    deltaDepGraph = await getDeltaDependencyGraph({
+                        ibGibAddr: addr,
+                        latestCommonFrameAddr: latestAddrAlreadyHave,
+                        space: mySpace,
+                        live: true,
+                    });
+                } else {
+                    // doesn't have anything, so get the entire dependency graph
+                    // INEFFICIENT: we've already gotten all of the domain
+                    // dependencies in initDomainGraph, but getDependencyGraph
+                    // only works against a space so we are going to rerun this.
+                    // an optimization would be to adapt/create a new
+                    // getDependencyGraph to work against an existing flat ibgib
+                    // map.
+                    deltaDepGraph = await getDependencyGraph({
+                        ibGibAddr: addr,
+                        space: mySpace,
+                        live: true,
+                    });
+                }
+
+                const depGraphSize = Object.keys(deltaDepGraph).length;
+                if (depGraphSize === 0) {
+                    throw new Error(`(UNEXPECTED) couldn't get requested addrs in mySpace (${mySpace.ib})? How did the receiver know to ask for these addrs if they weren't in our original graph? (E: 281eaebcdf77dd73e8245b2872100826)`);
+                } else {
+                    // we have dependencies!
+                    Object.values(deltaDepGraph).forEach(x => {
+                        outgoingPayloadIbGibsDomainGraph[getIbGibAddr({ ibGib: x })] = x;
+                    });
+                }
+            }
+
+            const result = Object.values(outgoingPayloadIbGibsDomainGraph);
+            return result;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
 
     /**
      * Evolves the saga timeline with a new frame.
      */
-    protected async evolveSyncSagaIbGib({
+    private async evolveSyncSagaIbGib({
         prevSagaIbGib,
         conflictStrategy,
         msgStones,
@@ -2128,7 +2345,7 @@ export class SyncSagaCoordinator {
         }
     }
 
-    protected async getStageAndPayloadFromFrame({
+    private async getStageAndPayloadFromFrame({
         sagaFrame,
         space
     }: {
@@ -2164,7 +2381,7 @@ export class SyncSagaCoordinator {
         }
     }
 
-    protected sortTimelinesTopologically(timelines: { [tjp: string]: IbGib_V1[] }): string[] {
+    private sortTimelinesTopologically(timelines: { [tjp: string]: IbGib_V1[] }): string[] {
         const lc = `${this.lc}[${this.sortTimelinesTopologically.name}]`;
         const tjps = Object.keys(timelines);
         if (tjps.length === 0) { return []; }