@ibgib/vcs-gib 0.0.18 → 0.0.21

package/src/engine/merge/b2tfs-3way-merge-strategy.mts

@@ -6,7 +6,7 @@
 
 import crypto from 'node:crypto';
 
-import { extractErrorMsg, hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { extractErrorMsg, hash, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 import { getGib } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
@@ -29,12 +29,15 @@ import { SyncConflictStrategy } from '@ibgib/core-gib/dist/sync/sync-constants.m
 
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
 import { isBinaryBuffer, decodeToLines, computeLineLcsDiff } from '../diff/line-diff-helper.mjs';
-import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME, BINARY_REL8N_NAME } from '../item/item-types.mjs';
-import { evolveB2tFSItemIbGib } from '../item/item-helper.mjs';
+import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME, BINARY_REL8N_NAME, B2tFSType } from '../item/item-types.mjs';
+import { evolveB2tFSItemIbGib, isB2tFSItemIbGib } from '../item/item-helper.mjs';
 import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { B2TFS_ITEM_ATOM } from '../item/item-atom-helper.mjs';
+import { B2tFS3WayAddlGraftDetails } from './b2tfs-3way-merge-types.mjs';
 
 const lcFile = `[b2tfs-3way-merge-strategy]`;
-const logalot = GLOBAL_LOG_A_LOT;
+const logalot = GLOBAL_LOG_A_LOT || true;
+const mergeDiag = `[MERGE DIAGNOSTIC]`;
 
 /**
  * 3-way text line diff merge result.
@@ -158,24 +161,36 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
     readonly strategyId: string = 'B2tFS3WayGraftStrategy';
     private lc = '[B2tFS3WayGraftStrategy]';
 
-    private isB2tFSNode(ibGib?: IbGib_V1): boolean {
-        if (!ibGib || !ibGib.ib) { return false; }
-        return ibGib.ib.startsWith('b2tfs_item') ||
-            ibGib.ib.startsWith('b2tfs_branch') ||
-            ibGib.data?.classname === 'B2tFSItemIbGib_V1' ||
-            ibGib.data?.classname === 'B2tFSBranchIbGib_V1';
-    }
-
+    /**
+     * Returns true only if the graft context has two tips that are text-based file b2tfs item ibgibs.
+     *
+     * ## notes
+     *
+     * atow (08/12/2026) implementation is guantlet style: if cannot graft, return early
+     *
+     * @param context info about the divergent timelines {@link GraftContext}
+     *
+     * @returns true if it's a text file item ibgib, else false
+     */
     async canGraft(context: GraftContext): Promise<boolean> {
         const lc = `${this.lc}[${this.canGraft.name}]`;
         try {
             const { conflictStrategy, timelineAddrsA, timelineAddrsB, ibGibReadCache, space } = context;
-            if (conflictStrategy === SyncConflictStrategy.optimisticWithLCS || (conflictStrategy as string) === 'b2tfs3WayMerge') {
-                return true;
+
+            // todo: refactor conflict strategy to be more generic: 'graft' | 'abort' | maybe something else.
+            const hasRelevantStrategy = conflictStrategy === SyncConflictStrategy.optimisticWithLCS || (conflictStrategy as string) === 'b2tfs3WayMerge';
+            if (!hasRelevantStrategy) {
+                // immediately return false because we are not the chosen strategy.
+                // todo: after refactor, really this should be out of the hands of the implementation and we should have a discriminator as part of the strategy interface. So the graft strategy pipeline executor can just check that first, and then if multiple found, it will delegate to this `canGraft` method.
+                return false; /* <<<< returns early */
             }
+
             const tipAddrA = timelineAddrsA.at(-1);
             const tipAddrB = timelineAddrsB.at(-1);
-            if (!tipAddrA || !tipAddrB) { return false; }
+            if (!tipAddrA || !tipAddrB) {
+                if (logalot) { console.log(`${lc} we don't have two tip addrs? how was a graft decided upon? (I: b20b6de462c35e0e74360cc8d317f126)`); }
+                return false; /* <<<< returns early */
+            }
 
             const [tipA, tipB] = await getIbGibsFromCache_fallbackToSpaces({
                 addrs: [tipAddrA, tipAddrB],
@@ -183,14 +198,34 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
                 space,
             });
 
-            return this.isB2tFSNode(tipA) || this.isB2tFSNode(tipB);
+            if (!tipA) { throw new Error(`(UNEXPECTED) tipA falsy? couldn't get tipA? should have been available to us in the temp space or cache.(E: 752101026888140f074614e893531826)`); }
+            if (!tipB) { throw new Error(`(UNEXPECTED) tipB falsy? couldn't get tipB? should have been available to us in the temp space or cache. (E: d4d4a876cad8c7869830d33832bfde26)`); }
+
+            const bothTipsAreB2tFSNodes = isB2tFSItemIbGib(tipA) && isB2tFSItemIbGib(tipB);
+
+            if (!bothTipsAreB2tFSNodes) {
+                // at this point, we're returning false. But I'm being extra defensive since this algorithm is so difficult to implement. So throw if somehow only one is a b2tfs item
+                if (isB2tFSItemIbGib(tipA) || isB2tFSItemIbGib(tipB)) {
+                    console.error(`${lc}${mergeDiag} (UNEXPECTED)(NOT THROWN) only tipA or tipB but not both are b2tfs items? (E: cacb38796da881268898e9d1af245826)`)
+                }
+                return false; /* <<<< returns early */
+            }
+
+            if (tipA.data.fsType !== tipB.data.fsType) { throw new Error(`(UNEXPECTED) tipA.data.fsType (${tipA.data.fsType}) !== tipB.data.fsType (${tipB.data.fsType})? both tips are expected to be the same B2tFSType. (E: c01c1885ac738f679813117852c48426)`); }
+
+            // only do files. folders can use the replay dna strategy.
+            const isFile = tipA.data.fsType === B2tFSType.file;
+            if (!isFile) { return false; /* <<<< returns early */ }
+
+            // passed gauntlet, we have a b2tfs file item that we can merge
+            return true;
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)} (E: 8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e)`);
             return false;
         }
     }
 
-    async graft(context: GraftContext): Promise<GraftTimelinesResult> {
+    async graft(context: GraftContext): Promise<GraftTimelinesResult | undefined> {
         const lc = `${lcFile}[${this.strategyId}][${this.graft.name}]`;
         try {
             if (logalot) {
@@ -241,12 +276,12 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
                 branchB_receiver_sinceLCA,
             });
 
-
-
             const baseTipAddr = getIbGibAddr({ ibGib: baseTip });
             const baseBranchAddrs = baseBranch.map(x => getIbGibAddr({ ibGib: x }));
             const orphanTipAddr = getIbGibAddr({ ibGib: orphanTip });
             const orphanBranchAddrs = orphanBranch.map(x => getIbGibAddr({ ibGib: x }));
+            if (logalot) { console.log(`${lc} baseBranchAddrs:\n${baseBranchAddrs.join('\n')}\n(I: 2cad420d7bc822f798b8a8785f1f8c26)`); }
+            if (logalot) { console.log(`${lc} orphanBranchAddrs:\n${orphanBranchAddrs.join('\n')}\n(I: cc86489d6737e2aced42b585cba13526)`); }
 
             // 3. Replay orphan branch transforms onto base tip
             const [latestCommonFrameIbGib] = await getIbGibsFromCache_fallbackToSpaces({
@@ -254,138 +289,302 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
                 space,
             });
 
-            const dnaAddrsAlreadyAccountedFor: IbGibAddr[] = (latestCommonFrameIbGib?.rel8ns?.dna ?? []).concat();
-            const dnaAddrsToApply: IbGibAddr[] = [];
-            for (const orphanFrame of orphanBranch) {
-                const orphanDnaAddrsToApply = getUniqueDnas({
-                    base: dnaAddrsAlreadyAccountedFor,
-                    extended: orphanFrame.rel8ns?.dna ?? [],
-                    throwIfExtendedDoesntContainBase: true,
-                });
-                orphanDnaAddrsToApply.forEach(x => dnaAddrsAlreadyAccountedFor.push(x));
-                orphanDnaAddrsToApply.forEach(x => dnaAddrsToApply.push(x));
+            // It is non-trivial and not at all obvious, but the following approach is WRONG!!
+            //
+            // This is not a generic timeline, rather, this is a timeline that
+            // is restricted to a b2tfs node, which itself has two
+            // possibilities: file or folder. So we can't replay dna blindly
+            // between the two branches and then try to do some kind of text
+            // merge later. We must analyze each branch and decide how to handle
+            // each change.
+            //
+            // NOTE: I have tweaked canGraft to only return true on
+            // B2tFSType.file and not folders, to see if the dna replay is good
+            // enough for folders, so we can concentrate on just files. Keep
+            // that in mind when I discuss the following notes.
+            //
+            // what we know at this point:
+            // * graft was invoked, so the sync engine detected divergence in
+            //   the two spaces, i.e., our two branches (branch-per-space)
+            //   * IOW, this is NOT a FF merge. That would have already been
+            //     applied and not triggered this graft.
+            // * This is either a file or a folder b2tfs item.
+            // * If it is a folder...
+            //   * How does git handle two folders merging, or does it?
+            //   * git is file-based, and handles folders only secondarily.
+            //   * How does our current vcs-gib diffing engine even detect if a
+            //     folder has moved? does it?
+            // * If it is a file...
+            //   * Is there anything that can happen besides the related binary file changing?
+            //   * If there are multiple changes to the binary file, should we
+            //     do each of those file changes in the graft?
+            //     * we need to game out multiple scenarios to answer this.
+            //     * What about multiple changes to each branch? Do we squash
+            //       the orphan to a single change and then merge the final?
+            //     * It is possible we can even parameterize this in this
+            //       strategy object, but the caller would need to configure
+            //       this strategy ahead of each sync call if that is the case I
+            //       think.
+            //       * One thing to parameterize would be how to handle graft
+            //         points, as I just realized in the context of version
+            //         control systems, it is possible that we may want to
+            //         configure the sync/merge to drop/do something with large
+            //         binaries (or just files in general) in a specific way.
+
+            // const dnaAddrsAlreadyAccountedFor: IbGibAddr[] = (latestCommonFrameIbGib?.rel8ns?.dna ?? []).concat();
+            // const dnaAddrsToApply: IbGibAddr[] = [];
+            // for (const orphanFrame of orphanBranch) {
+            //     if (!orphanFrame.rel8ns) { throw new Error(`(UNEXPECTED) orphanFrame.rel8ns falsy? (E: bc9a78ef8dbcd9748305d898bf1b2826)`); }
+            //     // I don't know if this is expected or not, but seems like if
+            //     // we're doing a merge, we are expecting the ibgib frames to
+            //     // have dna
+            //     if (!orphanFrame.rel8ns.dna || orphanFrame.rel8ns.dna.length === 0) {
+            //         throw new Error(`(UNEXPECTED) !orphanFrame.rel8ns.dna || orphanFrame.rel8ns.dna.length === 0? How can we be grafting when the orphan slice has no dna? (E: 7e58797aa2f98dfa811e8fa88c693826)`);
+            //     }
+            //     const orphanDnaAddrsToApply = getUniqueDnas({
+            //         base: dnaAddrsAlreadyAccountedFor,
+            //         extended: orphanFrame.rel8ns.dna,
+            //         throwIfExtendedDoesntContainBase: true,
+            //     });
+            //     orphanDnaAddrsToApply.forEach(x => dnaAddrsAlreadyAccountedFor.push(x));
+            //     orphanDnaAddrsToApply.forEach(x => dnaAddrsToApply.push(x));
+            // }
+
+            // const dnaIbGibsToApply = await getIbGibsFromCache_fallbackToSpaces({
+            //     addrs: dnaAddrsToApply,
+            //     readCache_graph: ibGibReadCache,
+            //     space,
+            // });
+
+            // if (logalot) { console.log(`${lc}${mergeDiag} dnaAddrsToApply addrs (${dnaAddrsToApply.length}): ${dnaAddrsToApply}  (I: 78a8a82f540d520682664aa806f1b826)`); }
+
+            // const createdIbGibs_Running: IbGib_V1[] = [];
+            // const newGraftedIntermediateIbGibs_ordered: IbGib_V1[] = [];
+            // const newGraftDnaIbGibs: IbGib_V1[] = [];
+
+            // let currentGraftTip = await applyTransforms({
+            //     src: baseTip,
+            //     dnaAddrsToApplyToStoreVersion_MUTATES_IN_PLACE: dnaAddrsToApply.concat(),
+            //     allLocalIbGibs: dnaIbGibsToApply,
+            //     createdIbGibs_Running,
+            // });
+
+            // if (createdIbGibs_Running.length > 0) {
+            //     await putInSpace({ space, ibGibs: createdIbGibs_Running });
+            //     const { mapWithTjp_YesDna: newGraftedIbGibsMap } = splitPerTjpAndOrDna({ ibGibs: createdIbGibs_Running });
+            //     const newGraftedIbGibs_orderNotGuaranteed = Object.values(newGraftedIbGibsMap);
+            //     const newGraftedIbGibsByTjp = getTimelinesGroupedByTjp({ ibGibs: newGraftedIbGibs_orderNotGuaranteed });
+            //     if (Object.keys(newGraftedIbGibsByTjp).length > 0) {
+            //         Object.values(newGraftedIbGibsByTjp)[0].forEach(x => newGraftedIntermediateIbGibs_ordered.push(x));
+            //         for (const item of newGraftedIntermediateIbGibs_ordered) {
+            //             await registerNewIbGib({ ibGib: item, space });
+            //         }
+            //     }
+            // }
+
+            // 4. Perform 3-way filesystem tree merge across lcaItem, baseItem, orphanItem
+            const lcaNode = await this.fetchIbGib({ addr: latestCommonFrameAddr, space, readCache_graph: ibGibReadCache });
+            if (!lcaNode) { throw new Error(`(UNEXPECTED) lcaNode falsy? (E: a8b2d80dc4f8ba1448fa280d89dfb626)`); }
+            const lcaItem = await this.resolveRootItemNode({ nodeOrAddr: lcaNode, space, readCache_graph: ibGibReadCache });
+            if (!lcaItem) { throw new Error(`(UNEXPECTED) lcaItem falsy? (E: 0944f88dde58cbabf82342b814955826)`); }
+            const baseItem = await this.resolveRootItemNode({ nodeOrAddr: baseTip, space, readCache_graph: ibGibReadCache });
+            if (!baseItem) { throw new Error(`(UNEXPECTED) baseItem falsy? (E: fac3087884cbebc7083e580514002826)`); }
+            const orphanItem = await this.resolveRootItemNode({ nodeOrAddr: orphanTip, space, readCache_graph: ibGibReadCache });
+            if (!orphanItem) { throw new Error(`(UNEXPECTED) orphanItem falsy? (E: 8e7e383753a8814f283280ee82156826)`); }
+
+            if (lcaItem.data.fsType !== baseItem.data.fsType) { throw new Error(`(UNEXPECTED) lcaItem.data.fsType !== baseItem.data.fsType? (E: 794608f3e678a399ed670388629a6826)`); }
+            if (lcaItem.data.fsType !== orphanItem.data.fsType) { throw new Error(`(UNEXPECTED) lcaItem.data.fsType !== orphanItem.data.fsType? (E: 2813981c8c422b41f85a02fd8aa88226)`); }
+            // all three fsTypes are equal
+
+            const fsType = lcaItem.data.fsType;
+            if (fsType === B2tFSType.folder) {
+                throw new Error(`(UNEXPECTED) fsType === B2tFSType.folder? I have tweaked the canGraft so we should only be handling files atow (08/11/2026) (E: b282b8f77b18575378edb902bd80a826)`);
             }
 
-            const dnaIbGibsToApply = await getIbGibsFromCache_fallbackToSpaces({
-                addrs: dnaAddrsToApply,
-                readCache_graph: ibGibReadCache,
-                space,
-            });
+            if (fsType !== B2tFSType.file) { throw new Error(`(UNEXPECTED) fsType (${fsType}) is not a file? (E: 272418fe2067ea3e16dac028e86d1a26)`); }
 
-            const createdIbGibs_Running: IbGib_V1[] = [];
-            const newGraftedIntermediateIbGibs_ordered: IbGib_V1[] = [];
-            const newGraftDnaIbGibs: IbGib_V1[] = [];
 
-            let currentGraftTip = await applyTransforms({
-                src: baseTip,
-                dnaAddrsToApplyToStoreVersion_MUTATES_IN_PLACE: dnaAddrsToApply.concat(),
-                allLocalIbGibs: dnaIbGibsToApply,
-                createdIbGibs_Running,
+            const lcaPayload = await this.getFilePayloadBuffer({
+                fileItem: lcaItem, space, readCache_graph: ibGibReadCache
+            });
+            if (lcaPayload === undefined) {
+                if (logalot) { console.log(`${lc}${mergeDiag} lcaPayload undefined? (I: 59b25835cce856cea883cf989ceb3826)`); }
+            }
+            const basePayload = await this.getFilePayloadBuffer({
+                fileItem: baseItem, space, readCache_graph: ibGibReadCache
+            });
+            if (basePayload === undefined) {
+                if (logalot) { console.log(`${lc}${mergeDiag} basePayload undefined? (I: 54f05406dca85eb98821b79f7325c826)`); }
+            }
+            const orphanPayload = await this.getFilePayloadBuffer({
+                fileItem: orphanItem, space, readCache_graph: ibGibReadCache
             });
+            if (orphanPayload === undefined) {
+                if (logalot) { console.log(`${lc}${mergeDiag} orphanPayload undefined? (I: cd8b785875b43fc6684c65d818edd826)`); }
+            }
+
+            const isBaseBin = basePayload ? isBinaryBuffer(basePayload.buffer) : false;
+            const isOrphanBin = orphanPayload ? isBinaryBuffer(orphanPayload.buffer) : false;
+            const isLcaBin = lcaPayload ? isBinaryBuffer(lcaPayload.buffer) : false;
 
-            if (space && createdIbGibs_Running.length > 0) {
-                await putInSpace({ space, ibGibs: createdIbGibs_Running });
-                const { mapWithTjp_YesDna: newGraftedIbGibsMap } = splitPerTjpAndOrDna({ ibGibs: createdIbGibs_Running });
-                const newGraftedIbGibs_orderNotGuaranteed = Object.values(newGraftedIbGibsMap);
-                const newGraftedIbGibsByTjp = getTimelinesGroupedByTjp({ ibGibs: newGraftedIbGibs_orderNotGuaranteed });
-                if (Object.keys(newGraftedIbGibsByTjp).length > 0) {
-                    Object.values(newGraftedIbGibsByTjp)[0].forEach(x => newGraftedIntermediateIbGibs_ordered.push(x));
-                    for (const item of newGraftedIntermediateIbGibs_ordered) {
-                        await registerNewIbGib({ ibGib: item, space });
-                    }
+            if (isBaseBin || isOrphanBin || isLcaBin) {
+                if (logalot) {
+                    console.log(`${lc} Non-text binary file detected (${baseItem.data?.name}). Skipping 3-way line diff. (I: 4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b)`);
                 }
+
+                // even though we've gotten this far into this `graft` method,
+                // we can still return `undefined` early if we decide we can't
+                // handle it and we haven't persisted/registered any ibgibs. In
+                // this particular case of 3-way text merges, we don't graft
+                // non-text binary divergences, e.g., pics, sound files, etc.
+
+                return undefined; /* <<<< returns early */
             }
 
-            // 4. Perform 3-way filesystem tree merge across lcaItem, baseItem, orphanItem
-            const lcaNode = await this.fetchIbGib({ addr: latestCommonFrameAddr, space, readCache_graph: ibGibReadCache });
-            const lcaItem = await this.resolveRootItemNode({ nodeOrAddr: lcaNode, space, readCache_graph: ibGibReadCache });
-            const baseItem = await this.resolveRootItemNode({ nodeOrAddr: baseTip, space, readCache_graph: ibGibReadCache });
-            const orphanItem = await this.resolveRootItemNode({ nodeOrAddr: orphanTip, space, readCache_graph: ibGibReadCache });
+            if (!lcaPayload) { throw new Error(`(UNEXPECTED) lcaPayload falsy? By this point in code, we have guaranteed that we are dealing with a text payload. (E: 0b82892204482f5538a430b8915b7826)`); }
+            if (!basePayload) { throw new Error(`(UNEXPECTED) basePayload falsy? By this point in code, we have guaranteed that we are dealing with a text payload. (E: af1f68a020280b3a5d6ed4a812acd426)`); }
+            if (!orphanPayload) { throw new Error(`(UNEXPECTED) orphanPayload falsy? By this point in code, we have guaranteed that we are dealing with a text payload. (E: 6a521b684763862c3a2e0ca315d62826)`); }
+
+            const textLCA = decodeToLines(lcaPayload.buffer).join('\n');
+            const textBase = decodeToLines(basePayload.buffer).join('\n');
+            const textOrphan = decodeToLines(orphanPayload.buffer).join('\n');
+
+            console.log(`${lc}${mergeDiag} file: ${baseItem.data.name}`);
+            console.log(`${lc}${mergeDiag} textLCA:\n${textLCA}`);
+            console.log(`${lc}${mergeDiag} textBase:\n${textBase}`);
+            console.log(`${lc}${mergeDiag} textOrphan:\n${textOrphan}`);
+
+            const { mergedText } = perform3WayTextLineMerge({ textLCA, textBase, textOrphan });
+            console.log(`${lc}${mergeDiag} mergedText:\n${mergedText}`);
 
-            let mergedRootItem: B2tFSItemIbGib_V1 | undefined;
-            if (lcaItem || baseItem || orphanItem) {
-                mergedRootItem = await this.mergeTreeNodes({
-                    lcaItem,
-                    baseItem,
-                    orphanItem,
-                    space,
-                    readCache_graph: ibGibReadCache,
-                    newGraftDnaIbGibs,
-                    newGraftedIntermediateIbGibs_ordered,
-                });
+            const dataBuffer = Buffer.from(mergedText, 'utf8');
+            const fileHash = await hash({ s: mergedText });
+
+            if (baseItem.data.fileExt !== orphanItem.data.fileExt) {
+                console.warn(`${lc} baseItem.data.fileExt (${baseItem.data.fileExt}) !== orphanItem.data.fileExt (${orphanItem.data.fileExt})? Using baseItem.data.fileExt for merged fileExt (W: a999b54235bb231fa49224842e212326)`);
             }
 
+            const fileExt = baseItem.data.fileExt;
+            const binIb = getBinIb({
+                binHash: fileHash,
+                binExt: fileExt,
+                binEncoding: 'utf8',
+            });
+            const binIbGib: BinIbGib_V1 = {
+                ib: binIb,
+                data: dataBuffer,
+            };
+            binIbGib.gib = await getGib({ ibGib: binIbGib, hasTjp: false });
+
+            const binAddr = getIbGibAddr({ ibGib: binIbGib });
+
+            // at this point, we are committed to performing the 3-way merge.
+            await putInSpace({ ibGib: binIbGib, space });
+            await registerNewIbGib({ ibGib: binIbGib, space });
+
 
-            // 5. Evolve currentGraftTip if root item changed
-            if (mergedRootItem) {
-                const mergedRootAddr = getIbGibAddr({ ibGib: mergedRootItem });
-                const currentRootAddr = baseItem ? getIbGibAddr({ ibGib: baseItem }) : undefined;
-
-                if (currentGraftTip.ib?.startsWith('b2tfs_branch') || currentGraftTip.data?.classname === 'B2tFSBranchIbGib_V1') {
-                    if (mergedRootAddr !== currentRootAddr) {
-                        const resRel8Branch = await rel8({
-                            src: currentGraftTip,
-                            rel8nsToAddByAddr: {
-                                b2tfs_item: [mergedRootAddr],
-                            },
-                            dna: true,
-                            nCounter: true,
-                        });
-
-                        const newGraftTip = await this.applyTransformAndRegister({
-                            resTransform: resRel8Branch,
-                            space,
-                            newGraftDnaIbGibs,
-                            newGraftedIntermediateIbGibs_ordered,
-                        });
-
-                        currentGraftTip = newGraftTip;
-                    }
-                } else if (currentGraftTip.ib?.startsWith('b2tfs_item') || currentGraftTip.data?.classname === 'B2tFSItemIbGib_V1') {
-                    if (mergedRootAddr !== getIbGibAddr({ ibGib: currentGraftTip })) {
-                        currentGraftTip = mergedRootItem;
-                    }
+            const fnGetN: (item: B2tFSItemIbGib_V1) => number = (item: B2tFSItemIbGib_V1) => {
+                if (item.data.n || item.data.n === 0) {
+                    return item.data.n!;
+                } else {
+                    throw new Error(`(UNEXPECTED) item.data.n not a number? (E: 896ceae089c83ca67817fff826be5826)`);
                 }
             }
+            const baseItemDataN = fnGetN(baseItem);
+            const orphanItemDataN = fnGetN(orphanItem);
+            const lowestDataN = baseItemDataN <= orphanItemDataN ?
+                baseItemDataN :
+                orphanItemDataN;
+
+            const evolveRes = await evolveB2tFSItemIbGib({
+                existingItem: baseItem,
+                dataToUpdate: {
+                    fileHash,
+                    n: lowestDataN + 1,
+                },
+                rel8nsToUpdate: {
+                    [BINARY_REL8N_NAME]: [binAddr],
+                },
+            });
+
+            // sanity checks
+            if (!evolveRes.dnas) { throw new Error(`(UNEXPECTED) evolveRes.dnas falsy? We should be using dna when working with B2tFS items. (E: e640e892cc76c77f98f3881301035826)`); }
+            if (!evolveRes.newIbGib) { throw new Error(`(UNEXPECTED) evolveRes.newIbGib falsy? we just did the merge, so this should be truthy. (E: 9e488d07772827b66a2aff4801905426)`); }
+            const newItemWithNewBinPayload = evolveRes.newIbGib as B2tFSItemIbGib_V1;
+            const newItemAddr = getIbGibAddr({ ibGib: newItemWithNewBinPayload });
+            if (logalot) { console.log(`${lc} newItemAddr: ${newItemAddr} (I: d23eef651b88be1248ee29ca179eff26)`); }
+
+            const newGraftDnaIbGibs: IbGib_V1[] = [];
+            const newGraftedIntermediateIbGibs_ordered: IbGib_V1[] = [];
+
+            newGraftDnaIbGibs.push(...evolveRes.dnas);
+            if (evolveRes.intermediateIbGibs) {
+                // todo: when we have this completed, we should know whether or not there are intermediate ibgibs in all cases, some cases, or no cases (never). we should change this from an `if` block with no else to throw an unexpected error (assertion) if it is indeed unexpected
+                evolveRes.intermediateIbGibs.forEach(x => newGraftedIntermediateIbGibs_ordered.push(x));
+            }
+
+            await persistTransformResult({ resTransform: evolveRes, space });
+            await registerNewIbGib({ ibGib: evolveRes.newIbGib, space });
+
+            const baseItemAddr = getIbGibAddr({ ibGib: baseItem });
+            const mergedRootAddr = getIbGibAddr({ ibGib: newItemWithNewBinPayload });
+            const currentRootAddr = baseItem ? getIbGibAddr({ ibGib: baseItem }) : undefined;
+
+            /**
+             * stupid word "details" is plural and I have this set to be an
+             * array. don't have the ability to refactor right now, so this will
+             * be mildly confusing unfortunately. Agents should not try to just
+             * refactor this on the fly.
+             */
+            const b2tfsAddlGraftDetails: B2tFS3WayAddlGraftDetails = {
+                baseTextB2tFSItemAddr: baseTipAddr,
+                baseTextBinAddr: basePayload.binIbGib ? getIbGibAddr({ ibGib: basePayload.binIbGib }) : undefined,
+                orphanTextB2tFSItemAddr: orphanTipAddr,
+                orphanTextBinAddr: orphanPayload.binIbGib ? getIbGibAddr({ ibGib: orphanPayload.binIbGib }) : undefined,
+            }
 
             // 6. Attach GraftInfo frame
             const graftInfo = await createGraftInfo({
                 conflictStrategy,
-                details: `Replayed ${dnaAddrsToApply.length} transforms from orphan (${orphanTipAddr}) onto base (${baseTipAddr}) with 3-way B2tFS tree merge.`,
-                addlGraftDetails: undefined,
+                details: `Merged orphan tip text with the baseTip as a starting point.`,
+                addlGraftDetails: [b2tfsAddlGraftDetails],
                 latestCommonFrameAddr,
                 baseAddrsSinceLCA: baseBranchAddrs,
                 orphanAddrsSinceLCA: orphanBranchAddrs,
-                dnaAddrsApplied: dnaAddrsToApply,
+                dnaAddrsApplied: [],
             });
 
-            if (space) {
-                await putInSpace({ ibGib: graftInfo, space });
-            }
+            await putInSpace({ ibGib: graftInfo, space });
+            await registerNewIbGib({ ibGib: graftInfo, space });
             const graftInfoAddr = getIbGibAddr({ ibGib: graftInfo });
+
             const resRel8GraftInfo = await rel8({
-                src: currentGraftTip,
+                src: newItemWithNewBinPayload,
                 rel8nsToAddByAddr: {
                     [GRAFT_INFO_REL8N_NAME]: [graftInfoAddr],
                 },
                 dna: true,
-                nCounter: !!currentGraftTip.data?.n,
+                nCounter: true,
             });
+            if (!resRel8GraftInfo.dnas) { throw new Error(`(UNEXPECTED) resRel8GraftInfo.dnas falsy? (E: f3f4a83d3a08bd8de84250c389aed826)`); }
+            const finalGraftTip = resRel8GraftInfo.newIbGib;
+            const finalGraftTipAddr = getIbGibAddr({ ibGib: finalGraftTip });
+            if (logalot) { console.log(`${lc} finalGraftTipAddr: ${finalGraftTipAddr} (I: 583ac81fb0a84827b85c3076ffeeaf26)`); }
 
-            for (const dna of resRel8GraftInfo.dnas ?? []) {
+            newGraftedIntermediateIbGibs_ordered.push(newItemWithNewBinPayload);
+
+            for (const dna of resRel8GraftInfo.dnas) {
                 newGraftDnaIbGibs.push(dna);
             }
-            if (space) {
-                await persistTransformResult({ resTransform: resRel8GraftInfo, space });
-                await registerNewIbGib({ ibGib: resRel8GraftInfo.newIbGib, space });
-            }
 
-            const finalGraftTip = resRel8GraftInfo.newIbGib;
+            await persistTransformResult({ resTransform: resRel8GraftInfo, space });
+            await registerNewIbGib({ ibGib: finalGraftTip, space });
 
             return {
-                dnasReplayed: dnaIbGibsToApply,
+                dnasReplayed: [],
                 dnasCreatedInGraft: newGraftDnaIbGibs,
                 intermediateIbGibsCreatedInGraft: newGraftedIntermediateIbGibs_ordered,
+                ancillaryIbGibsCreated: [binIbGib],
                 newGraftTip: finalGraftTip,
                 graftInfoCreated: graftInfo,
             };
@@ -405,7 +604,7 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         readCache_graph,
     }: {
         addr?: string;
-        space?: IbGibSpaceAny;
+        space: IbGibSpaceAny;
         readCache_graph?: FlatIbGibGraph;
     }): Promise<IbGib_V1 | undefined> {
         if (!addr) { return undefined; }
@@ -416,7 +615,6 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
             const matchingKey = Object.keys(readCache_graph).find(k => k === cleanAddr || k.startsWith(cleanAddr + '^') || (k.includes('^') && k.split('^')[0] === cleanAddr));
             if (matchingKey) { return readCache_graph[matchingKey]; }
         }
-        if (!space) { return undefined; }
         try {
             const res = await getFromSpace({ space, addrs: [addr, cleanAddr] });
             if (res && res.success && res.ibGibs && res.ibGibs.length > 0) {
@@ -425,6 +623,8 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
             }
         } catch {
             // Suppress fetch error if address not found
+            // why suppress? any ibgibs available to us here should be in space
+            // (the temp space of the sync receiver)
         }
         return undefined;
     }
@@ -436,32 +636,26 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         readCache_graph,
     }: {
         nodeOrAddr: IbGib_V1 | string | undefined;
-        space?: any;
+        space: IbGibSpaceAny;
         readCache_graph?: FlatIbGibGraph;
     }): Promise<B2tFSItemIbGib_V1 | undefined> {
-        if (!nodeOrAddr) { return undefined; }
+        if (!nodeOrAddr) { throw new Error(`(UNEXPECTED) nodeOrAddr falsy? (E: 524108327b9caa00586207ea399f7226)`); }
+
         let node: IbGib_V1 | undefined;
         if (typeof nodeOrAddr === 'string') {
             node = await this.fetchIbGib({ addr: nodeOrAddr, space, readCache_graph });
         } else {
             node = nodeOrAddr;
         }
-        if (!node) { return undefined; }
-
-        if (node.ib?.startsWith('b2tfs_branch') || node.data?.classname === 'B2tFSBranchIbGib_V1') {
-            const rootItemAddr = node.rel8ns?.b2tfs_item?.at(-1);
-            if (rootItemAddr) {
-                const rootNode = await this.fetchIbGib({ addr: rootItemAddr, space, readCache_graph });
-                return rootNode as B2tFSItemIbGib_V1;
-            }
-            return undefined;
-        }
+        if (!node) { throw new Error(`(UNEXPECTED) node falsy? couldn't get node? (E: bd7d1c3b4a3881ff882746281869d826)`); }
 
-        if (node.ib?.startsWith('b2tfs_item') || node.data?.classname === 'B2tFSItemIbGib_V1') {
-            return node as B2tFSItemIbGib_V1;
+        if (isB2tFSItemIbGib(node)) {
+            // it's an item ibgib
+            return node;
+        } else {
+            // not an item ibgib
+            throw new Error(`(UNEXPECTED) node is not a B2tFSItemIbGib_V1? canGraft should have returned false then and we should never have gotten here. (E: ddabb281ccb2fb1a181109a82046b826)`);
         }
-
-        return undefined;
     }
 
     private async getFilePayloadBuffer({
@@ -470,7 +664,7 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         readCache_graph,
     }: {
         fileItem?: B2tFSItemIbGib_V1;
-        space?: any;
+        space: IbGibSpaceAny;
         readCache_graph?: FlatIbGibGraph;
     }): Promise<{ buffer: Uint8Array; binIbGib?: IbGib_V1 } | undefined> {
         if (!fileItem || !fileItem.rel8ns) { return undefined; }
@@ -479,7 +673,8 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         if (!latestBinAddr) { return undefined; }
 
         const binIbGib = await this.fetchIbGib({ addr: latestBinAddr, space, readCache_graph });
-        if (!binIbGib || binIbGib.data === undefined) { return undefined; }
+        if (!binIbGib) { throw new Error(`(UNEXPECTED) couldn't fetch binIbGib? latestBinAddr: ${latestBinAddr}. space.ib: ${space.ib} (E: 3d1238b3a348924038a79f88264d8226)`); }
+        if (binIbGib.data === undefined) { return undefined; } // what if it's an empty file. will data be undefined? do we handle this at the b2tfs item level for fsType === 'file'?
 
         let fileData: Uint8Array;
         const dataObj = binIbGib.data as any;
@@ -512,7 +707,7 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         readCache_graph,
     }: {
         folderItem?: B2tFSItemIbGib_V1;
-        space?: any;
+        space: IbGibSpaceAny;
         readCache_graph?: FlatIbGibGraph;
     }): Promise<Map<string, B2tFSItemIbGib_V1>> {
         const map = new Map<string, B2tFSItemIbGib_V1>();
@@ -539,7 +734,7 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         lcaItem?: B2tFSItemIbGib_V1;
         baseItem?: B2tFSItemIbGib_V1;
         orphanItem?: B2tFSItemIbGib_V1;
-        space?: any;
+        space: IbGibSpaceAny;
         readCache_graph?: FlatIbGibGraph;
         newGraftDnaIbGibs: IbGib_V1[];
         newGraftedIntermediateIbGibs_ordered: IbGib_V1[];
@@ -588,134 +783,66 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         const fsType = baseItem.data?.fsType || orphanItem.data?.fsType;
 
         if (fsType === 'file') {
-            const lcaPayload = await this.getFilePayloadBuffer({ fileItem: lcaItem, space, readCache_graph });
-            const basePayload = await this.getFilePayloadBuffer({ fileItem: baseItem, space, readCache_graph });
-            const orphanPayload = await this.getFilePayloadBuffer({ fileItem: orphanItem, space, readCache_graph });
-
-            const isBaseBin = basePayload ? isBinaryBuffer(basePayload.buffer) : false;
-            const isOrphanBin = orphanPayload ? isBinaryBuffer(orphanPayload.buffer) : false;
-            const isLcaBin = lcaPayload ? isBinaryBuffer(lcaPayload.buffer) : false;
-
-            if (isBaseBin || isOrphanBin || isLcaBin) {
-                if (logalot) {
-                    console.log(`${lc} Non-text binary file detected (${baseItem.data?.name}). Skipping 3-way line diff. (I: 4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b)`);
-                }
-                return baseItem;
-            }
-
-            const textLCA = lcaPayload ? decodeToLines(lcaPayload.buffer).join('\n') : '';
-            const textBase = basePayload ? decodeToLines(basePayload.buffer).join('\n') : '';
-            const textOrphan = orphanPayload ? decodeToLines(orphanPayload.buffer).join('\n') : '';
-
-            console.log(`${lc} [MERGE DIAGNOSTIC] file: ${baseItem.data?.name}`);
-            console.log(`${lc} [MERGE DIAGNOSTIC] textLCA:\n${textLCA}`);
-            console.log(`${lc} [MERGE DIAGNOSTIC] textBase:\n${textBase}`);
-            console.log(`${lc} [MERGE DIAGNOSTIC] textOrphan:\n${textOrphan}`);
-
-            const { mergedText } = perform3WayTextLineMerge({ textLCA, textBase, textOrphan });
-            console.log(`${lc} [MERGE DIAGNOSTIC] mergedText:\n${mergedText}`);
-
-            const dataBuffer = Buffer.from(mergedText, 'utf8');
-            const fileHash = await hash({ s: mergedText });
-
-
-            const fileExt = baseItem.data?.fileExt || (baseItem.data?.name?.includes('.') ? baseItem.data.name.split('.').pop() || 'txt' : 'txt');
-            const binIb = getBinIb({
-                binHash: fileHash,
-                binExt: fileExt,
-                binEncoding: 'utf8',
-            });
-
-            const binIbGib: BinIbGib_V1 = {
-                ib: binIb,
-                data: dataBuffer,
-            };
-            binIbGib.gib = await getGib({ ibGib: binIbGib, hasTjp: false });
-
-            const binAddr = getIbGibAddr({ ibGib: binIbGib });
-            if (space) {
-                await putInSpace({ ibGib: binIbGib, space });
-                await registerNewIbGib({ ibGib: binIbGib, space });
-            }
-
-            const evolveRes = await evolveB2tFSItemIbGib({
-                existingItem: baseItem,
-                dataToUpdate: {
-                    fileHash,
-                },
-                rel8nsToUpdate: {
-                    [BINARY_REL8N_NAME]: [binAddr],
-                },
-            });
-
-            if (evolveRes.dnas) { newGraftDnaIbGibs.push(...evolveRes.dnas); }
-            if (evolveRes.newIbGib) { newGraftedIntermediateIbGibs_ordered.push(evolveRes.newIbGib); }
-            if (space) {
-                await persistTransformResult({ resTransform: evolveRes, space });
-                await registerNewIbGib({ ibGib: evolveRes.newIbGib, space });
-            }
-
-            return evolveRes.newIbGib as B2tFSItemIbGib_V1;
         } else if (fsType === 'folder') {
-            const lcaChildrenMap = await this.getChildItemsMap({ folderItem: lcaItem, space, readCache_graph });
-            const baseChildrenMap = await this.getChildItemsMap({ folderItem: baseItem, space, readCache_graph });
-            const orphanChildrenMap = await this.getChildItemsMap({ folderItem: orphanItem, space, readCache_graph });
-
-            const allNames = new Set([
-                ...lcaChildrenMap.keys(),
-                ...baseChildrenMap.keys(),
-                ...orphanChildrenMap.keys(),
-            ]);
-
-            const mergedChildAddrs: string[] = [];
-
-            for (const name of allNames) {
-                const childLCA = lcaChildrenMap.get(name);
-                const childBase = baseChildrenMap.get(name);
-                const childOrphan = orphanChildrenMap.get(name);
-
-                const mergedChild = await this.mergeTreeNodes({
-                    lcaItem: childLCA,
-                    baseItem: childBase,
-                    orphanItem: childOrphan,
-                    space,
-                    readCache_graph,
-                    newGraftDnaIbGibs,
-                    newGraftedIntermediateIbGibs_ordered,
-                });
-
-
-                if (mergedChild) {
-                    mergedChildAddrs.push(getIbGibAddr({ ibGib: mergedChild }));
-                }
-            }
-
-            const currentChildAddrs = baseItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
-            const addrsChanged = mergedChildAddrs.length !== currentChildAddrs.length ||
-                mergedChildAddrs.some((addr, idx) => addr !== currentChildAddrs[idx]);
-
-            if (!addrsChanged) {
-                return baseItem;
-            }
-
-            const evolveRes = await evolveB2tFSItemIbGib({
-                existingItem: baseItem,
-                rel8nsToUpdate: {
-                    [B2TFS_CHILD_ITEM_REL8N_NAME]: mergedChildAddrs,
-                },
-                rel8nsToRemove: {
-                    [B2TFS_CHILD_ITEM_REL8N_NAME]: baseItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [],
-                },
-            });
-
-            if (evolveRes.dnas) { newGraftDnaIbGibs.push(...evolveRes.dnas); }
-            if (evolveRes.newIbGib) { newGraftedIntermediateIbGibs_ordered.push(evolveRes.newIbGib); }
-            if (space) {
-                await persistTransformResult({ resTransform: evolveRes, space });
-                await registerNewIbGib({ ibGib: evolveRes.newIbGib, space });
-            }
-
-            return evolveRes.newIbGib as B2tFSItemIbGib_V1;
+            // const lcaChildrenMap = await this.getChildItemsMap({ folderItem: lcaItem, space, readCache_graph });
+            // const baseChildrenMap = await this.getChildItemsMap({ folderItem: baseItem, space, readCache_graph });
+            // const orphanChildrenMap = await this.getChildItemsMap({ folderItem: orphanItem, space, readCache_graph });
+
+            // const allChildAddrs = new Set([
+            //     ...lcaChildrenMap.keys(),
+            //     ...baseChildrenMap.keys(),
+            //     ...orphanChildrenMap.keys(),
+            // ]);
+
+            // const mergedChildAddrs: string[] = [];
+
+            // for (const childItemAddr of allChildAddrs) {
+            //     const childLCA = lcaChildrenMap.get(childItemAddr);
+            //     const childBase = baseChildrenMap.get(childItemAddr);
+            //     const childOrphan = orphanChildrenMap.get(childItemAddr);
+
+            //     const mergedChild = await this.mergeTreeNodes({
+            //         lcaItem: childLCA,
+            //         baseItem: childBase,
+            //         orphanItem: childOrphan,
+            //         space,
+            //         readCache_graph,
+            //         newGraftDnaIbGibs,
+            //         newGraftedIntermediateIbGibs_ordered,
+            //     });
+
+
+            //     if (mergedChild) {
+            //         mergedChildAddrs.push(getIbGibAddr({ ibGib: mergedChild }));
+            //     }
+            // }
+
+            // const currentChildAddrs = baseItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+            // const addrsChanged = mergedChildAddrs.length !== currentChildAddrs.length ||
+            //     mergedChildAddrs.some((addr, idx) => addr !== currentChildAddrs[idx]);
+
+            // if (!addrsChanged) {
+            //     return baseItem;
+            // }
+
+            // const evolveRes = await evolveB2tFSItemIbGib({
+            //     existingItem: baseItem,
+            //     rel8nsToUpdate: {
+            //         [B2TFS_CHILD_ITEM_REL8N_NAME]: mergedChildAddrs,
+            //     },
+            //     rel8nsToRemove: {
+            //         [B2TFS_CHILD_ITEM_REL8N_NAME]: baseItem.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [],
+            //     },
+            // });
+
+            // if (evolveRes.dnas) { newGraftDnaIbGibs.push(...evolveRes.dnas); }
+            // if (evolveRes.newIbGib) { newGraftedIntermediateIbGibs_ordered.push(evolveRes.newIbGib); }
+            // if (space) {
+            //     await persistTransformResult({ resTransform: evolveRes, space });
+            //     await registerNewIbGib({ ibGib: evolveRes.newIbGib, space });
+            // }
+
+            // return evolveRes.newIbGib as B2tFSItemIbGib_V1;
         }
 
         return baseItem;