@ibgib/core-gib 0.1.29 → 0.1.30

package/src/sync/strategies/conflict-optimistic.mts

@@ -1,8 +1,8 @@
 /**
  * @module conflict-optimistic
- * 
+ *
  * Implements the Optimistic Conflict Resolution Strategy.
- * 
+ *
  * Logic:
  * 1. findLCA: Traverses `past` to find common ancestor.
  * 2. mergeDivergentTimelines: Replays DNA to create a merged tip.
@@ -10,11 +10,12 @@
 
 import { IbGib_V1, IbGibRel8ns_V1, IbGibData_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+
 import { IbGibSpaceAny } from '../../witness/space/space-base-v1.mjs';
 import { getFromSpace, putInSpace } from '../../witness/space/space-helper.mjs';
 import { mut8Timeline } from '../../timeline/timeline-api.mjs';
 
-const lc = `[conflict-optimistic]`;
+const logalot = GLOBAL_LOG_A_LOT || true;
 
 export interface LCAResult {
     lcaAddr: string;
@@ -22,9 +23,42 @@ export interface LCAResult {
     branchB: IbGib_V1[]; // Path from LCA to Tip B (exclusive of LCA)
 }
 
+export interface TimelinesAnalysis {
+    latestCommonAddr: IbGibAddr;
+    uniqueBranchA
+}
+
+/**
+ * gets a quick analysis comparing/contrasting two timeline addrs.
+ *
+ * This does not do in-depth analysis that would involve retrieving ibgibs
+ from
+ * any spaces.
+ */
+export function analyzeTimelinesShallow({
+    a,
+    b,
+}: {
+    a: IbGibAddr[],
+    b: IbGibAddr[],
+}
+): IbGibAddr {
+    const lc = `[${analyzeTimelinesShallow.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 1f65b883a2089948842c927c6a08c826)`); }
+
+        throw new Error(`not implemented (E: eab7ac95806ff9c60dafa22eb59cb926)`);
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
 /**
  * Finds the Last Common Ancestor (LCA) between two divergent timelines.
- * 
+ *
  * Note: simplistic implementation assuming simple linear divergence.
  * Complex DAGs might require more robust graph traversal.
  */
@@ -114,6 +148,9 @@ export async function findLCA({
 }
 
 import { graftTimelines, mergeTextLCS } from '../graft-info/graft-info-helpers.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib';
+import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 
 /**
  * Optimistically grafts two divergent timelines by inspecting DNA and replaying transforms.

package/src/sync/sync-conflict.respec.mts

@@ -166,7 +166,7 @@ await respecfully(sir, `Sync Conflict Resolution`, async () => {
         // This ensures the conflict precondition exists.
         await ifWe(sir, 'verify receiver KV pre-sync', async () => {
             try {
-                const destKV = await receiverCoordinator.getKnowledgeVector({
+                const destKV = await receiverCoordinator.getKnowledgeMap({
                     space: destSpace,
                     metaspace,
                     domainIbGibs: [v1_Dest]
@@ -186,7 +186,7 @@ await respecfully(sir, `Sync Conflict Resolution`, async () => {
 
             } catch (error) {
                 console.error(`${lc} ${extractErrorMsg(error)}`);
-                iReckon(sir, true).asTo('getKnowledgeVector errored out').isGonnaBeFalse();
+                iReckon(sir, true).asTo('getKnowledgeMap errored out').isGonnaBeFalse();
             }
         });
 
@@ -251,7 +251,7 @@ await respecfully(sir, `Sync Conflict Resolution`, async () => {
 
             try {
                 // Get the KV for the Source Space
-                const sourceKV = await senderCoordinator.getKnowledgeVector({
+                const sourceKV = await senderCoordinator.getKnowledgeMap({
                     space: sourceSpace,
                     metaspace,
                     domainIbGibs: [testRoot] // We want to know the tip of this timeline
@@ -260,7 +260,7 @@ await respecfully(sir, `Sync Conflict Resolution`, async () => {
                     getTjpAddr({ ibGib: testRoot, defaultIfNone: 'incomingAddr' }) ??
                     getIbGibAddr({ ibGib: testRoot });
 
-                if (logalot) { console.log(`${lc} getKnowledgeVector returned. sourceKV: ${pretty(sourceKV)} (I: e8780cda37c8b2a46eeb85786874e926)`); }
+                if (logalot) { console.log(`${lc} getKnowledgeMap returned. sourceKV: ${pretty(sourceKV)} (I: e8780cda37c8b2a46eeb85786874e926)`); }
 
                 const sourceTipAddr = sourceKV[tjpAddr];
                 if (!sourceTipAddr) {
@@ -319,7 +319,7 @@ await respecfully(sir, `Sync Conflict Resolution`, async () => {
                 }
             } catch (error) {
                 console.error(`${lc} ${extractErrorMsg(error)}`);
-                iReckon(sir, true).asTo('getKnowledgeVector errored out').isGonnaBeFalse();
+                iReckon(sir, true).asTo('getKnowledgeMap errored out').isGonnaBeFalse();
             }
 
         });

package/src/sync/sync-innerspace-deep-updates.respec.mts

@@ -128,7 +128,7 @@ await respecfully(sir, `Sync InnerSpaces (Deep Updates)`, async () => {
         // 5. Verify Dest
         console.log(`${lc} Verifying Destination...`);
 
-        await ifWeMight(sir, `verify deep timeline present`, async () => {
+        await ifWe(sir, `verify deep timeline present`, async () => {
             // Verify Tip (V2)
             const getV2 = await getFromSpace({ space: destSpace, addr: addrV2 });
             iReckon(sir, getV2.success).asTo('Tip V2 present').isGonnaBeTrue();

package/src/sync/sync-innerspace-dest-ahead.respec.mts

@@ -11,10 +11,10 @@ import {
 const maam = `[${import.meta.url}]`, sir = maam;
 import { clone, delay, extractErrorMsg, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { getDependencyGraph } from '../common/other/graph-helper.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 
 import { SyncSagaCoordinator } from './sync-saga-coordinator.mjs';
-import { putInSpace, getFromSpace } from '../witness/space/space-helper.mjs';
+import { putInSpace, getFromSpace, registerNewIbGib } from '../witness/space/space-helper.mjs';
 import { Metaspace_Innerspace } from '../witness/space/metaspace/metaspace-innerspace/metaspace-innerspace.mjs';
 import { InnerSpace_V1 } from '../witness/space/inner-space/inner-space-v1.mjs';
 import { createTimelineRootHelper, getTestKeystoneServiceHelper } from '../agent-helpers.mjs';
@@ -23,6 +23,8 @@ import { DEFAULT_INNER_SPACE_DATA_V1 } from '../witness/space/inner-space/inner-
 import { toDto } from '../common/other/ibgib-helper.mjs';
 import { SyncPeerInnerspace_V1 } from './sync-peer/sync-peer-innerspace/sync-peer-innerspace-v1.mjs';
 import { SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1 } from './sync-peer/sync-peer-innerspace/sync-peer-innerspace-constants.mjs';
+import { GetIbGibResult } from '../common/other/other-types.mjs';
+import { IbGibSpaceAny } from '../witness/space/space-base-v1.mjs';
 
 const logalot = true;
 const lc = `[sync-innerspace-dest-ahead.respec]`;
@@ -73,22 +75,43 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
         // Root -> V1 (Shared) -> V2 (Dest has New)
         // Source only has V1.
 
-        const root = await createTimelineRootHelper<TestData>({
+        const v0 = await createTimelineRootHelper<TestData>({
             ib: 'timeline_root_ff',
             data: { type: 'root', label: 'Root' },
             space: sourceSpace,
         });
+        const addrV0 = getIbGibAddr({ ibGib: v0 });
+        console.log(pretty(v0));
+
+        console.log('0000000000000')
+        console.log('0000000000000')
+        console.log('0000000000000')
+        console.log('0000000000000')
+        console.log('0000000000000')
 
         // V1 (Both have it, but we create in source and copy to dest)
         const v1 = await mut8Timeline<TestData>({
-            timeline: root,
+            timeline: v0,
             mut8Opts: { dataToAddOrPatch: { type: 'comment', label: 'V1' } },
             metaspace,
             space: sourceSpace,
         });
+        const addrV1 = getIbGibAddr({ ibGib: v1 });
+        console.log(pretty(v1));
+
 
         // Transfer Root & V1 to Dest
-        await putInSpace({ space: destSpace, ibGibs: [root, v1] }); // Naive seeding
+        await putInSpace({ space: destSpace, ibGibs: [v0, v1] }); // Naive seeding
+        await registerNewIbGib({ space: destSpace, ibGib: v0 });
+        await registerNewIbGib({ space: destSpace, ibGib: v1 });
+
+        console.log('1111111111111111111111111111111')
+        console.log('1111111111111111111111111111111')
+        console.log('1111111111111111111111111111111')
+        console.log('1111111111111111111111111111111')
+        console.log('1111111111111111111111111111111')
+        console.log('1111111111111111111111111111111')
+        console.log('1111111111111111111111111111111')
 
         // V2 (Created in Dest ONLY)
         const v2 = await mut8Timeline<TestData>({
@@ -98,12 +121,31 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
             space: destSpace, // Mutate in Dest
         });
         const addrV2 = getIbGibAddr({ ibGib: v2 });
+        console.log(pretty(v2));
+
+        const fnAddrExistsInSpace = async (addr: IbGibAddr, space: IbGibSpaceAny) => {
+            const resGet = await getFromSpace({ addr, space });
+            return resGet.success && resGet.ibGibs && resGet.ibGibs.length === 1;
+        }
+
+        console.log('22222222222')
+        console.log('22222222222')
+        console.log('22222222222')
+        console.log('22222222222')
+        console.log('22222222222')
+        console.log('22222222222')
+        console.log('22222222222')
+
 
         await ifWeMight(sir, 'verify setup', async () => {
             // Ensure V2 is ONLY in Dest (it is, per `space: destSpace`)
             // Ensure Source does NOT have V2
-            const checkV2InSource = await getFromSpace({ space: sourceSpace, addr: addrV2 });
-            iReckon(sir, checkV2InSource.success && !!checkV2InSource.ibGibs?.length).asTo('Source has V2').isGonnaBeFalse();
+            iReckon(sir, await fnAddrExistsInSpace(addrV0, sourceSpace)).asTo('source has V0').isGonnaBeTrue();
+            iReckon(sir, await fnAddrExistsInSpace(addrV1, sourceSpace)).asTo('source has V1').isGonnaBeTrue();
+            iReckon(sir, await fnAddrExistsInSpace(addrV2, sourceSpace)).asTo('source has V2').isGonnaBeFalse();
+            iReckon(sir, await fnAddrExistsInSpace(addrV0, destSpace)).asTo('dest has V0').isGonnaBeTrue();
+            iReckon(sir, await fnAddrExistsInSpace(addrV1, destSpace)).asTo('dest has V1').isGonnaBeTrue();
+            iReckon(sir, await fnAddrExistsInSpace(addrV2, destSpace)).asTo('dest has V2').isGonnaBeTrue();
         });
 
         // 3. Setup Sync
@@ -119,6 +161,14 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
             receiverCoordinator,
             receiverMetaspace: metaspace,
         });
+        console.log('333333333')
+        console.log('333333333')
+        console.log('333333333')
+        console.log('333333333')
+        console.log('333333333')
+        console.log('333333333')
+        console.log('333333333')
+
 
         // 4. Run Sync (Source Pushes V1)
         console.log(`${lc} Running Sync...`);
@@ -132,13 +182,27 @@ await respecfully(sir, `Sync InnerSpaces (Dest Ahead)`, async () => {
 
         await resSync.done;
 
-        // 5. Verify Dest (Should still have V2 as latest)
+        console.log('444444444')
+        console.log('444444444')
+        console.log('444444444')
+        console.log('444444444')
+        console.log('444444444')
+        console.log('444444444')
+        console.log('444444444')
+
+        // 5. Verify Sync (v2 should be in both source and dest now)
         console.log(`${lc} Verifying Destination...`);
 
         await ifWeMight(sir, `verify dest stays ahead`, async () => {
             // Verify Tip (V2)
             const getV2 = await getFromSpace({ space: destSpace, addr: addrV2 });
-            iReckon(sir, getV2.success).asTo('V2 still present in Dest').isGonnaBeTrue();
+
+            iReckon(sir, await fnAddrExistsInSpace(addrV0, sourceSpace)).asTo('source has V0').isGonnaBeTrue();
+            iReckon(sir, await fnAddrExistsInSpace(addrV1, sourceSpace)).asTo('source has V1').isGonnaBeTrue();
+            iReckon(sir, await fnAddrExistsInSpace(addrV2, sourceSpace)).asTo('source has V2').isGonnaBeTrue();
+            iReckon(sir, await fnAddrExistsInSpace(addrV0, destSpace)).asTo('dest has V0').isGonnaBeTrue();
+            iReckon(sir, await fnAddrExistsInSpace(addrV1, destSpace)).asTo('dest has V1').isGonnaBeTrue();
+            iReckon(sir, await fnAddrExistsInSpace(addrV2, destSpace)).asTo('dest has V2').isGonnaBeTrue();
 
             // Verify V2 points to V1
             const v2IbGib = getV2.ibGibs![0];

package/src/sync/sync-innerspace-multiple-timelines.respec.mts

@@ -130,7 +130,7 @@ await respecfully(sir, `Sync InnerSpaces (Multiple Timelines)`, async () => {
         // 5. Verify Dest
         console.log(`${lc} Verifying Destination...`);
 
-        await ifWeMight(sir, `verify timelines present`, async () => {
+        await ifWe(sir, `verify timelines present`, async () => {
             // Verify A
             const getA = await getFromSpace({ space: destSpace, addr: addrA });
             iReckon(sir, getA.success).asTo('Timeline A present').isGonnaBeTrue();

package/src/sync/sync-innerspace-partial-update.respec.mts

@@ -98,7 +98,7 @@ await respecfully(sir, `Sync InnerSpaces (Partial Update)`, async () => {
         // Transfer Root & V1 to Dest (Simulate previous sync)
         await putInSpace({ space: destSpace, ibGibs: [root, v1] });
 
-        await ifWeMight(sir, 'verify setup', async () => {
+        await ifWe(sir, 'verify setup', async () => {
             // Verify Dest has V1
             const checkV1 = await getFromSpace({ space: destSpace, addr: getIbGibAddr({ ibGib: v1 }) });
             iReckon(sir, checkV1.success).asTo('Dest has V1').isGonnaBeTrue();
@@ -137,7 +137,7 @@ await respecfully(sir, `Sync InnerSpaces (Partial Update)`, async () => {
         // 5. Verify Dest (Should now have V2)
         console.log(`${lc} Verifying Destination...`);
 
-        await ifWeMight(sir, `verify dest updated`, async () => {
+        await ifWe(sir, `verify dest updated`, async () => {
             // Verify Tip (V2)
             const getV2 = await getFromSpace({ space: destSpace, addr: addrV2 });
             iReckon(sir, getV2.success).asTo('V2 present in Dest').isGonnaBeTrue();

package/src/sync/sync-innerspace.respec.mts

@@ -154,18 +154,18 @@ await respecfully(sir, `Sync InnerSpaces`, async () => {
         try {
             const getChildInDest = await getFromSpace({ space: destSpace, addr: childAddr });
 
-            await ifWeMight(sir, `verify success getChildInDest`, async () => {
+            await ifWe(sir, `verify success getChildInDest`, async () => {
                 iReckon(sir, getChildInDest.success).asTo('Child present in Dest').isGonnaBeTrue();
             });
 
-            await ifWeMight(sir, `verify getChildInDest.ibGibs`, async () => {
+            await ifWe(sir, `verify getChildInDest.ibGibs`, async () => {
                 const firstChild = getChildInDest.ibGibs?.[0];
                 if (logalot) { console.log(`${lc} firstChild: ${pretty(firstChild)}`); }
                 iReckon(sir, firstChild?.data?.n).asTo('Child content matches').isGonnaBe(2);
             });
 
         } catch (error) {
-            await ifWeMight(sir, `doh`, async () => {
+            await ifWe(sir, `doh`, async () => {
                 // hack here I'm getting tired...
                 iReckon(sir, true).asTo(`error: ${extractErrorMsg(error)}`).isGonnaBeFalse();
             });

package/src/sync/sync-peer/sync-peer-innerspace/sync-peer-innerspace-v1.mts

@@ -245,6 +245,17 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<InitializeSyncPeerInnersp
             }
 
             // spin off the payloads, as that may take a long time
+            if (responseCtx.payloadIbGibsDomain?.length ?? 0 > 0) {
+                // i guess this only will hit once we have conflicts, because
+                // it's the return trip, i.e., from the receiver. The initial
+                // ack frame does it through push offers?
+                await delay(2000);
+                console.warn(`${lc} this delay does hit (W: 3940d47d2a7433833837af4cef171126)`)
+                for (let i = 0; i < 100; i++) {
+                    const element = 100;
+                    console.log(`THIS HITS`)
+                }
+            }
             const payloadIbGibsDomain_response = responseCtx.payloadIbGibsDomain;
             if (payloadIbGibsDomain_response) {
                 new Promise<void>(async (resolve, reject) => {
@@ -253,13 +264,12 @@ export class SyncPeerInnerspace_V1 extends SyncPeer_V1<InitializeSyncPeerInnersp
                         if (logalot) { console.log(`${lcPut} starting... (I: 4133e736b4c80d2cf94448b87b206826)`); }
 
                         // 2 seconds...i want to see huge blocks of logs entries for this to see this happening
-                        const delayMs = 200;
+                        const delayMs = 2000;
                         for (let i = 0; i < 10; i++) {
                             console.warn(`${lc} ARTIFICIALLY DELAYING PAYLOADS TO MIMIC TRANSFER LATENCY. REMOVE THIS DELAY!! (W: 5e7b28f1daa82d955897e9d8cdb16f26)`)
                             await delay(delayMs);
                         }
 
-
                         await putInSpace_dnasThenNonDnas({
                             ibGibs: payloadIbGibsDomain_response,
                             space: senderTempSpace,

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

@@ -23,7 +23,7 @@ import {
     SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN,
 } from "./sync-constants.mjs";
 import {
-    appendToTimeline, createTimeline, Rel8nInfo, Rel8nRemovalInfo
+    appendToTimeline, createTimeline, getHistory, getHistoryAddrs, Rel8nInfo, Rel8nRemovalInfo
 } from "../timeline/timeline-api.mjs";
 import {
     SyncData_V1, SyncIbGib_V1, SyncConflictStrategy, SyncMode, SyncOptions,
@@ -536,10 +536,10 @@ export class SyncSagaCoordinator {
     }
 
     /**
-     * Helper to get Knowledge Vector for specific domain ibGibs or TJPs.
+     * Helper to get Knowledge Map for specific domain ibGibs or TJPs.
      * Useful for testing and external validation.
      */
-    public async getKnowledgeVector({
+    public async getKnowledgeMap({
         space,
         metaspace,
         domainIbGibs,
@@ -550,7 +550,7 @@ export class SyncSagaCoordinator {
         domainIbGibs?: IbGib_V1[],
         tjpAddrs?: string[],
     }): Promise<{ [tjp: string]: string | null }> {
-        const lc = `${this.lc}[${this.getKnowledgeVector.name}]`;
+        const lc = `${this.lc}[${this.getKnowledgeMap.name}]`;
         try {
             if (logalot) { console.log(`${lc} starting... (I: e184f8a7818666febfbbd2d841ed3826)`); }
             // console.dir(space);
@@ -588,7 +588,7 @@ export class SyncSagaCoordinator {
             } else {
                 // No info provided. Return empty? Or throw?
                 // User test context implied "everything", but implementation requires scope.
-                console.warn(`${lc} No domainIbGibs or tjpAddrs provided. Returning empty KV.`);
+                console.warn(`${lc} No domainIbGibs or tjpAddrs provided. Returning empty Knowledge.`);
                 return {};
             }
 
@@ -655,7 +655,7 @@ export class SyncSagaCoordinator {
      * @remarks
      * **Execution Context**: **Sender (Local)**.
      *
-     * Generates the first frame containing the Knowledge Vector of the Local Space.
+     * Generates the first frame containing the Knowledge Map of the Local Space.
      * This is sent to the Receiver to begin Gap Analysis.
      */
     private async createInitFrame({
@@ -687,17 +687,17 @@ export class SyncSagaCoordinator {
             // 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: { [tjp: string]: IbGibAddr } = {};
+            // populate our knowledge map with tjp -> latest addr/tip in timeline
+            const knowledgeMap: { [tjp: string]: IbGibAddr } = {};
             Object.keys(srcTimelinesMap).forEach(tjp => {
                 const timeline = srcTimelinesMap[tjp];
                 const tip = timeline.at(-1)!;
-                knowledgeVector[tjp] = getIbGibAddr({ ibGib: tip });
+                knowledgeMap[tjp] = getIbGibAddr({ ibGib: tip });
             });
             const initData: SyncSagaMessageInitData_V1 = {
                 sagaId,
                 stage: SyncStage.init,
-                knowledgeVector,
+                knowledgeMap: knowledgeMap,
                 identity: sessionIdentity, // KeystoneIbGib is already public data
                 mode: SyncMode.sync,
                 stones: srcStones.map(s => getIbGibAddr({ ibGib: s })),
@@ -815,16 +815,21 @@ export class SyncSagaCoordinator {
      *
      * ## 1. Sender
      *
-     * On the sender, this is called within the {@link executeSagaLoop} which
-     * initiates and drives the sync.
+     * On the sender, this is called repeatedly within the the sync saga
+     * coordinator's {@link executeSagaLoop} which initiates and drives the
+     * overall sync process. This loop continues until there are no more frames
+     * to be exchanged between endpoints.
      *
      * ## 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.
+     * On the receiver, this is called directly from {@link continueSync}, which
+     * itself is called either directly by the concrete sync peer or from within
+     * the receiving node 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.
+     * In contrast to the sender, this can be thought of as a one-off on the
+     * receiver, since the sender's {@link executeSagaLoop} is what actually
+     * drives the ping-pong process.
      */
     private async handleResponseSagaContext({
         sagaContext,
@@ -868,11 +873,6 @@ export class SyncSagaCoordinator {
 
             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: NextSagaFrameInfo;
             switch (stage) {
                 case SyncStage.init:
@@ -899,7 +899,6 @@ export class SyncSagaCoordinator {
                     nextFrameInfo = await this.handleDeltaFrame({
                         sagaContext,
                         sagaIbGib,
-                        srcGraph,
                         metaspace, mySpace, myTempSpace,
                         identity,
                     });
@@ -940,7 +939,7 @@ export class SyncSagaCoordinator {
      * **Execution Context**: **Receiver (Remote)**.
      *
      * The Receiver performs Gap Analysis here:
-     * 1.  Compares Sender's Knowledge Vector (in `sagaIbGib`) vs Receiver's Local KV.
+     * 1.  Compares Sender's Knowledge Map (in `sagaIbGib`) vs Receiver's Local Knowledge Map.
      * 2.  Identifies what Sender needs (`pushOfferAddrs`).
      * 3.  Identifies what Receiver needs (`deltaRequestAddrInfos`).
      * 4.  Returns an `Ack` frame containing these lists.
@@ -983,8 +982,8 @@ export class SyncSagaCoordinator {
                 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)`);
+            if (!initData || !initData.knowledgeMap) {
+                throw new Error(`${lc} Invalid init frame: missing knowledgeMap (E: ed02c869e028d2d06841b9c7f80f2826)`);
             }
 
             // Determine Strategy from Saga Data (since V1 stores it in root)
@@ -1017,9 +1016,9 @@ export class SyncSagaCoordinator {
             /**
              * "remote" is sender in this case
              */
-            const remoteKV = initData.knowledgeVector;
-            if (logalot) { console.log(`${lc} remoteKV: ${pretty(remoteKV)} (I: 9f957862356dfeae183c200854e86e26)`); }
-            const remoteTjps = Object.keys(remoteKV);
+            const remoteKnowledge = initData.knowledgeMap;
+            if (logalot) { console.log(`${lc} remoteKnowledge: ${pretty(remoteKnowledge)} (I: 9f957862356dfeae183c200854e86e26)`); }
+            const remoteTjps = Object.keys(remoteKnowledge);
             if (logalot) { console.log(`${lc} [TEST DEBUG] remoteTjps: ${JSON.stringify(remoteTjps)}`); }
             if (logalot) { console.log(`${lc} remoteTjps: ${pretty(remoteTjps)} (I: 86ea4c53db0dc184c8b253386c402126)`); }
 
@@ -1034,13 +1033,13 @@ export class SyncSagaCoordinator {
                 if (!resGetLatestAddrs.data) { throw new Error(`(UNEXPECTED) resGetLatestAddrs.data falsy? (E: b180d813c088042b38e1e02e06a16926)`); }
                 if (!resGetLatestAddrs.data.latestAddrsMap) { throw new Error(`(UNEXPECTED) resGetLatestAddrs.data.latestAddrsMap falsy? (E: 16bc386dd51d0ff53a49620b1e641826)`); }
                 localLatestAddrsMap = resGetLatestAddrs.data.latestAddrsMap;
-                if (logalot) { console.log(`${lc} [TEST DEBUG] localKV: ${JSON.stringify(localLatestAddrsMap)}`); }
-                if (logalot) { console.log(`${lc} localKV: ${pretty(localLatestAddrsMap)} (I: 980975642cbccd8018cf0cd808d30826)`); }
+                if (logalot) { console.log(`${lc} [TEST DEBUG] localKnowledge: ${JSON.stringify(localLatestAddrsMap)}`); }
+                if (logalot) { console.log(`${lc} localKnowledge: ${pretty(localLatestAddrsMap)} (I: 980975642cbccd8018cf0cd808d30826)`); }
             }
 
             // 2. Gap Analysis
             for (const tjp of remoteTjps) {
-                const remoteAddr = remoteKV[tjp];
+                const remoteAddr = remoteKnowledge[tjp];
                 const localAddr = localLatestAddrsMap[tjp];
 
                 if (!localAddr) {
@@ -1099,7 +1098,6 @@ export class SyncSagaCoordinator {
                      */
                     let localIsInPast = false;
                     try {
-                        // we could
                         localIsInPast = await isPastFrame({
                             olderAddr: localAddr,
                             newerAddr: remoteAddr,
@@ -1135,27 +1133,23 @@ export class SyncSagaCoordinator {
                                 reason: 'divergence',
                                 terminal: true
                             });
+                            // todo: create error saga frame for when aborting or other terminal error
                         } 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)`);
+                                throw new Error(`couldn't get local tip (${localAddr}) from space (${mySpace.ib}). errorMsg: ${resLocalTip.errorMsg ?? '[unknown error (E: b3c3d823276300aa384ebdba4a8eb826)]'} (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];
-
+                            const pastAddrs = await getHistoryAddrs({
+                                timeline: localTip,
+                                space: mySpace,
+                                metaspace,
+                            });
+                            const timelineAddrs = [...pastAddrs, localAddr];
                             conflicts.push({
                                 tjpAddr: tjp,
                                 localAddr,
@@ -1349,8 +1343,10 @@ export class SyncSagaCoordinator {
             const terminalConflicts = conflicts.filter(c => c.terminal);
             if (terminalConflicts.length > 0) {
                 if (logalot) { 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.
+                // Terminal failure. Sender should probably Commit(Fail) or just
+                // Abort. For now, throw to trigger abort. the incoming ack
+                // frame has already been persisted in local durable space by
+                // now.
                 throw new Error(`${lc} Peer reported terminal conflicts. (E: 23a0096ee05a2ccfa89334e8f156b426)`);
             }
 
@@ -1583,7 +1579,6 @@ export class SyncSagaCoordinator {
     private async handleDeltaFrame({
         sagaContext,
         sagaIbGib,
-        srcGraph,
         mySpace,
         myTempSpace,
         metaspace,
@@ -1591,7 +1586,6 @@ export class SyncSagaCoordinator {
     }: {
         sagaContext: SyncSagaContextIbGib_V1,
         sagaIbGib: SyncIbGib_V1,
-        srcGraph: { [addr: string]: IbGib_V1 },
         mySpace: IbGibSpaceAny,
         myTempSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,

package/src/sync/sync-saga-message/sync-saga-message-types.mts

@@ -40,7 +40,7 @@ export interface SyncSagaMessageIbGib_V1 extends IbGib_V1<SyncSagaMessageData_V1
 /**
  * The "Hello" of the sync protocol.
  *
- * Exchanges knowledge vectors (what I have) and identity (who I am).
+ * Exchanges knowledge maps (what I have) and identity (who I am).
  */
 export interface SyncSagaMessageInitData_V1 extends SyncSagaMessageData_V1 {
     stage: typeof SyncStage.init;
@@ -51,7 +51,7 @@ export interface SyncSagaMessageInitData_V1 extends SyncSagaMessageData_V1 {
      *
      * IOW, this is a map of the starting and end points of an ibGib's timeline.
      */
-    knowledgeVector: { [tjp: string]: IbGibAddr };
+    knowledgeMap: { [tjp: string]: IbGibAddr };
 
     /**
      * The Keystone Identity of the sender.
@@ -149,7 +149,7 @@ export interface SyncSagaMessageAckData_V1 extends SyncSagaMessageData_V1 {
     /**
      * Infos regarding ibgibs that the receiver (generator of this ack)
      * knows/believes that the sender does NOT have (after looking at knowledge
-     * vector of sender).
+     * map of sender).
      *
      * This includes addrs that will correspond to the context.payloadAddrsDomain
      *