@ibgib/vcs-gib 0.0.17 → 0.0.20

package/dist/engine/merge/b2tfs-3way-merge-strategy.mjs

@@ -0,0 +1,741 @@
+/**
+ * @module b2tfs-3way-merge-strategy
+ *
+ * Extensible Graft Merge Strategy for 3-way B2tFS filesystem snapshot trees and text files.
+ */
+import { extractErrorMsg, hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { getGib } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+import { rel8 } from '@ibgib/ts-gib/dist/V1/transforms/rel8.mjs';
+import { GraftMergeStrategyBase_V1 } from '@ibgib/core-gib/dist/sync/graft-info/graft-merge-strategy-base-v1.mjs';
+import { getFromSpace, persistTransformResult, registerNewIbGib, putInSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { getBinIb, getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { createGraftInfo } from '@ibgib/core-gib/dist/sync/graft-info/graft-info-helpers.mjs';
+import { GRAFT_INFO_REL8N_NAME } from '@ibgib/core-gib/dist/sync/graft-info/graft-info-constants.mjs';
+import { SyncConflictStrategy } from '@ibgib/core-gib/dist/sync/sync-constants.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { isBinaryBuffer, decodeToLines, computeLineLcsDiff } from '../diff/line-diff-helper.mjs';
+import { B2TFS_CHILD_ITEM_REL8N_NAME, BINARY_REL8N_NAME, B2tFSType } from '../item/item-types.mjs';
+import { evolveB2tFSItemIbGib, isB2tFSItemIbGib } from '../item/item-helper.mjs';
+const lcFile = `[b2tfs-3way-merge-strategy]`;
+const logalot = GLOBAL_LOG_A_LOT || true;
+const mergeDiag = `[MERGE DIAGNOSTIC]`;
+/**
+ * Performs 3-way line diff merging across LCA, Base, and Orphan text lines.
+ * Inserts Git conflict markers (`<<<<<<< HEAD`, `=======`, `>>>>>>>`) when overlapping
+ * line changes conflict.
+ */
+export function perform3WayTextLineMerge({ textLCA, textBase, textOrphan, }) {
+    console.log(`[DEBUG 3WAY] textLCA: ${JSON.stringify(textLCA)}`);
+    console.log(`[DEBUG 3WAY] textBase: ${JSON.stringify(textBase)}`);
+    console.log(`[DEBUG 3WAY] textOrphan: ${JSON.stringify(textOrphan)}`);
+    if (textBase === textOrphan) {
+        return { mergedText: textBase, hasConflict: false };
+    }
+    if (textBase === textLCA) {
+        return { mergedText: textOrphan, hasConflict: false };
+    }
+    if (textOrphan === textLCA) {
+        return { mergedText: textBase, hasConflict: false };
+    }
+    const linesLCA = textLCA.split(/\r?\n/);
+    const linesBase = textBase.split(/\r?\n/);
+    const linesOrphan = textOrphan.split(/\r?\n/);
+    const chunksBase = computeLineLcsDiff(linesLCA, linesBase);
+    const chunksOrphan = computeLineLcsDiff(linesLCA, linesOrphan);
+    if (chunksBase.length === 0) {
+        return { mergedText: textOrphan, hasConflict: false };
+    }
+    if (chunksOrphan.length === 0) {
+        return { mergedText: textBase, hasConflict: false };
+    }
+    let hasConflict = false;
+    const outputLines = [];
+    let lcaIdx = 0;
+    let baseChunkIdx = 0;
+    let orphanChunkIdx = 0;
+    while (lcaIdx < linesLCA.length || baseChunkIdx < chunksBase.length || orphanChunkIdx < chunksOrphan.length) {
+        const nextBaseChunk = chunksBase[baseChunkIdx];
+        const nextOrphanChunk = chunksOrphan[orphanChunkIdx];
+        const baseAtLca = nextBaseChunk && nextBaseChunk.old_i === lcaIdx;
+        const orphanAtLca = nextOrphanChunk && nextOrphanChunk.old_i === lcaIdx;
+        if (baseAtLca && orphanAtLca) {
+            const bLines = nextBaseChunk.newLines;
+            const oLines = nextOrphanChunk.newLines;
+            const bOldLen = nextBaseChunk.oldLines.length;
+            const oOldLen = nextOrphanChunk.oldLines.length;
+            if (bLines.join('\n') === oLines.join('\n') && bOldLen === oOldLen) {
+                outputLines.push(...bLines);
+            }
+            else {
+                hasConflict = true;
+                outputLines.push('<<<<<<< HEAD');
+                outputLines.push(...bLines);
+                outputLines.push('=======');
+                outputLines.push(...oLines);
+                outputLines.push('>>>>>>>');
+            }
+            const consumedLca = Math.max(bOldLen, oOldLen, 1);
+            lcaIdx += consumedLca;
+            baseChunkIdx++;
+            orphanChunkIdx++;
+        }
+        else if (baseAtLca) {
+            outputLines.push(...nextBaseChunk.newLines);
+            const consumedLca = Math.max(nextBaseChunk.oldLines.length, 1);
+            lcaIdx += consumedLca;
+            baseChunkIdx++;
+        }
+        else if (orphanAtLca) {
+            outputLines.push(...nextOrphanChunk.newLines);
+            const consumedLca = Math.max(nextOrphanChunk.oldLines.length, 1);
+            lcaIdx += consumedLca;
+            orphanChunkIdx++;
+        }
+        else {
+            if (lcaIdx < linesLCA.length) {
+                outputLines.push(linesLCA[lcaIdx]);
+                lcaIdx++;
+            }
+            else {
+                if (nextBaseChunk && baseChunkIdx < chunksBase.length) {
+                    outputLines.push(...nextBaseChunk.newLines);
+                    baseChunkIdx++;
+                }
+                if (nextOrphanChunk && orphanChunkIdx < chunksOrphan.length) {
+                    outputLines.push(...nextOrphanChunk.newLines);
+                    orphanChunkIdx++;
+                }
+            }
+        }
+    }
+    return {
+        mergedText: outputLines.join('\n'),
+        hasConflict,
+    };
+}
+export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 {
+    strategyId = 'B2tFS3WayGraftStrategy';
+    lc = '[B2tFS3WayGraftStrategy]';
+    /**
+     * 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) {
+        const lc = `${this.lc}[${this.canGraft.name}]`;
+        try {
+            const { conflictStrategy, timelineAddrsA, timelineAddrsB, ibGibReadCache, space } = context;
+            // todo: refactor conflict strategy to be more generic: 'graft' | 'abort' | maybe something else.
+            const hasRelevantStrategy = conflictStrategy === SyncConflictStrategy.optimisticWithLCS || conflictStrategy === '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) {
+                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],
+                readCache_graph: ibGibReadCache,
+                space,
+            });
+            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) {
+        const lc = `${lcFile}[${this.strategyId}][${this.graft.name}]`;
+        try {
+            if (logalot) {
+                console.log(`${lc} starting 3-way B2tFS snapshot graft... (I: 91a82b3c4d5e6f7a8b9c0d1e2f3a4b5c)`);
+            }
+            const { conflictStrategy, timelineAddrsA, timelineAddrsB, latestCommonFrameAddr, ibGibReadCache, space, graftPreference, } = context;
+            // 1. Fetch branch slices since LCA (timeline A = Sender, timeline B = Receiver)
+            const indexLCA_A = timelineAddrsA.lastIndexOf(latestCommonFrameAddr);
+            const addrsA_sinceLCA = timelineAddrsA.slice(indexLCA_A + 1);
+            const branchA_sender_sinceLCA = await getIbGibsFromCache_fallbackToSpaces({
+                readCache_graph: ibGibReadCache,
+                addrs: addrsA_sinceLCA,
+                space,
+            });
+            const tipA_sender = branchA_sender_sinceLCA.at(-1);
+            const indexLCA_B = timelineAddrsB.lastIndexOf(latestCommonFrameAddr);
+            const addrsB_sinceLCA = timelineAddrsB.slice(indexLCA_B + 1);
+            const branchB_receiver_sinceLCA = await getIbGibsFromCache_fallbackToSpaces({
+                readCache_graph: ibGibReadCache,
+                addrs: addrsB_sinceLCA,
+                space,
+            });
+            const tipB_receiver = branchB_receiver_sinceLCA.at(-1);
+            // 2. Base & Orphan tip determination (directional preference) via DRY base helper
+            const { baseTip, baseBranch, orphanTip, orphanBranch, } = this.resolveBaseAndOrphan({
+                graftPreference,
+                tipA_sender,
+                branchA_sender_sinceLCA,
+                tipB_receiver,
+                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({
+                addrs: [latestCommonFrameAddr],
+                space,
+            });
+            // 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)`);
+            }
+            if (fsType !== B2tFSType.file) {
+                throw new Error(`(UNEXPECTED) fsType (${fsType}) is not a file? (E: 272418fe2067ea3e16dac028e86d1a26)`);
+            }
+            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 (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 */
+            }
+            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}`);
+            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 = {
+                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 });
+            const fnGetN = (item) => {
+                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;
+            const newItemAddr = getIbGibAddr({ ibGib: newItemWithNewBinPayload });
+            if (logalot) {
+                console.log(`${lc} newItemAddr: ${newItemAddr} (I: d23eef651b88be1248ee29ca179eff26)`);
+            }
+            const newGraftDnaIbGibs = [];
+            const newGraftedIntermediateIbGibs_ordered = [];
+            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 = {
+                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: `Merged orphan tip text with the baseTip as a starting point.`,
+                addlGraftDetails: [b2tfsAddlGraftDetails],
+                latestCommonFrameAddr,
+                baseAddrsSinceLCA: baseBranchAddrs,
+                orphanAddrsSinceLCA: orphanBranchAddrs,
+                dnaAddrsApplied: [],
+            });
+            await putInSpace({ ibGib: graftInfo, space });
+            await registerNewIbGib({ ibGib: graftInfo, space });
+            const graftInfoAddr = getIbGibAddr({ ibGib: graftInfo });
+            const resRel8GraftInfo = await rel8({
+                src: newItemWithNewBinPayload,
+                rel8nsToAddByAddr: {
+                    [GRAFT_INFO_REL8N_NAME]: [graftInfoAddr],
+                },
+                dna: true,
+                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)`);
+            }
+            newGraftedIntermediateIbGibs_ordered.push(newItemWithNewBinPayload);
+            for (const dna of resRel8GraftInfo.dnas) {
+                newGraftDnaIbGibs.push(dna);
+            }
+            await persistTransformResult({ resTransform: resRel8GraftInfo, space });
+            await registerNewIbGib({ ibGib: finalGraftTip, space });
+            return {
+                dnasReplayed: [],
+                dnasCreatedInGraft: newGraftDnaIbGibs,
+                intermediateIbGibsCreatedInGraft: newGraftedIntermediateIbGibs_ordered,
+                ancillaryIbGibsCreated: [binIbGib],
+                newGraftTip: finalGraftTip,
+                graftInfoCreated: graftInfo,
+            };
+        }
+        catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)} (E: 7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e)`);
+            throw error;
+        }
+        finally {
+            if (logalot) {
+                console.log(`${lc} complete. (I: 6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f)`);
+            }
+        }
+    }
+    async fetchIbGib({ addr, space, readCache_graph, }) {
+        if (!addr) {
+            return undefined;
+        }
+        const cleanAddr = addr.includes('^') ? addr.split('^')[0] : addr;
+        if (readCache_graph) {
+            if (readCache_graph[cleanAddr]) {
+                return readCache_graph[cleanAddr];
+            }
+            if (readCache_graph[addr]) {
+                return readCache_graph[addr];
+            }
+            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];
+            }
+        }
+        try {
+            const res = await getFromSpace({ space, addrs: [addr, cleanAddr] });
+            if (res && res.success && res.ibGibs && res.ibGibs.length > 0) {
+                const found = res.ibGibs.find((x) => !!x);
+                if (found) {
+                    return found;
+                }
+            }
+        }
+        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;
+    }
+    async resolveRootItemNode({ nodeOrAddr, space, readCache_graph, }) {
+        if (!nodeOrAddr) {
+            throw new Error(`(UNEXPECTED) nodeOrAddr falsy? (E: 524108327b9caa00586207ea399f7226)`);
+        }
+        let node;
+        if (typeof nodeOrAddr === 'string') {
+            node = await this.fetchIbGib({ addr: nodeOrAddr, space, readCache_graph });
+        }
+        else {
+            node = nodeOrAddr;
+        }
+        if (!node) {
+            throw new Error(`(UNEXPECTED) node falsy? couldn't get node? (E: bd7d1c3b4a3881ff882746281869d826)`);
+        }
+        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)`);
+        }
+    }
+    async getFilePayloadBuffer({ fileItem, space, readCache_graph, }) {
+        if (!fileItem || !fileItem.rel8ns) {
+            return undefined;
+        }
+        const binAddrs = fileItem.rel8ns[BINARY_REL8N_NAME] || [];
+        const latestBinAddr = binAddrs.at(-1);
+        if (!latestBinAddr) {
+            return undefined;
+        }
+        const binIbGib = await this.fetchIbGib({ addr: latestBinAddr, space, readCache_graph });
+        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;
+        const dataObj = binIbGib.data;
+        if (dataObj && typeof dataObj === 'object' && dataObj._dataType === 'Uint8Array_Base64' && typeof dataObj.value === 'string') {
+            fileData = Buffer.from(dataObj.value, 'base64');
+        }
+        else if (typeof dataObj === 'string') {
+            fileData = Buffer.from(dataObj, 'utf8');
+        }
+        else if (dataObj instanceof Uint8Array || Buffer.isBuffer(dataObj)) {
+            fileData = dataObj;
+        }
+        else if (typeof dataObj === 'object' && dataObj !== null) {
+            if (typeof dataObj.text === 'string') {
+                fileData = Buffer.from(dataObj.text, 'utf8');
+            }
+            else if (typeof dataObj.data === 'string') {
+                fileData = Buffer.from(dataObj.data, 'utf8');
+            }
+            else {
+                const vals = Object.values(dataObj);
+                fileData = new Uint8Array(vals);
+            }
+        }
+        else {
+            fileData = new Uint8Array(0);
+        }
+        return { buffer: fileData, binIbGib };
+    }
+    async getChildItemsMap({ folderItem, space, readCache_graph, }) {
+        const map = new Map();
+        if (!folderItem || !folderItem.rel8ns) {
+            return map;
+        }
+        const childAddrs = folderItem.rel8ns[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
+        for (const addr of childAddrs) {
+            const childNode = await this.fetchIbGib({ addr, space, readCache_graph });
+            if (childNode && childNode.data?.name) {
+                map.set(childNode.data.name, childNode);
+            }
+        }
+        return map;
+    }
+    async mergeTreeNodes({ lcaItem, baseItem, orphanItem, space, readCache_graph, newGraftDnaIbGibs, newGraftedIntermediateIbGibs_ordered, }) {
+        const lc = `${lcFile}[${this.mergeTreeNodes.name}]`;
+        const baseAddr = baseItem ? getIbGibAddr({ ibGib: baseItem }) : undefined;
+        const orphanAddr = orphanItem ? getIbGibAddr({ ibGib: orphanItem }) : undefined;
+        const lcaAddr = lcaItem ? getIbGibAddr({ ibGib: lcaItem }) : undefined;
+        if (baseAddr && orphanAddr && baseAddr === orphanAddr) {
+            return baseItem;
+        }
+        if (lcaAddr && baseAddr && baseAddr === lcaAddr && orphanItem) {
+            return orphanItem;
+        }
+        if (lcaAddr && orphanAddr && orphanAddr === lcaAddr && baseItem) {
+            return baseItem;
+        }
+        if (!baseItem && !orphanItem) {
+            return undefined;
+        }
+        if (baseItem && !orphanItem) {
+            if (lcaAddr && baseAddr === lcaAddr) {
+                return undefined;
+            }
+            return baseItem;
+        }
+        if (orphanItem && !baseItem) {
+            if (lcaAddr && orphanAddr === lcaAddr) {
+                return undefined;
+            }
+            return orphanItem;
+        }
+        if (!baseItem || !orphanItem) {
+            throw new Error(`(UNEXPECTED) baseItem or orphanItem missing in 3-way merge branch (E: 5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a)`);
+        }
+        const fsType = baseItem.data?.fsType || orphanItem.data?.fsType;
+        if (fsType === 'file') {
+        }
+        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 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;
+    }
+}
+export const B2tFSItem3WayMergeStrategy = B2tFS3WayGraftStrategy;
+//# sourceMappingURL=b2tfs-3way-merge-strategy.mjs.map