@ibgib/vcs-gib 0.0.17 → 0.0.18

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

@@ -0,0 +1,725 @@
+/**
+ * @module b2tfs-3way-merge-strategy
+ *
+ * Extensible Graft Merge Strategy for 3-way B2tFS filesystem snapshot trees and text files.
+ */
+
+import crypto from 'node:crypto';
+
+import { extractErrorMsg, hash } 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';
+import { rel8 } from '@ibgib/ts-gib/dist/V1/transforms/rel8.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+
+import { GraftMergeStrategyBase_V1 } from '@ibgib/core-gib/dist/sync/graft-info/graft-merge-strategy-base-v1.mjs';
+import { GraftContext, GraftPreference, GraftStrategy, GraftTimelinesResult, GraftMergeContext, GraftMergeResult } from '@ibgib/core-gib/dist/sync/graft-info/graft-info-types.mjs';
+import { FlatIbGibGraph } from '@ibgib/core-gib/dist/common/other/graph-types.mjs';
+
+
+import { getFromSpace, persistTransformResult, registerNewIbGib, putInSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+import { getBinIb, getIbGibsFromCache_fallbackToSpaces, getTimelinesGroupedByTjp, getTimestampInfo, splitPerTjpAndOrDna } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+
+import { applyTransforms, getUniqueDnas } from '@ibgib/core-gib/dist/witness/space/reconciliation-space/reconciliation-space-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 { BinIbGib_V1 } from '@ibgib/core-gib/dist/common/bin/bin-types.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 { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME, BINARY_REL8N_NAME } from '../item/item-types.mjs';
+import { evolveB2tFSItemIbGib } from '../item/item-helper.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+
+const lcFile = `[b2tfs-3way-merge-strategy]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * 3-way text line diff merge result.
+ */
+export interface Text3WayMergeResult {
+    mergedText: string;
+    hasConflict: boolean;
+}
+
+/**
+ * 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,
+}: {
+    textLCA: string;
+    textBase: string;
+    textOrphan: string;
+}): Text3WayMergeResult {
+    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: string[] = [];
+
+    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 implements GraftStrategy {
+    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';
+    }
+
+    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;
+            }
+            const tipAddrA = timelineAddrsA.at(-1);
+            const tipAddrB = timelineAddrsB.at(-1);
+            if (!tipAddrA || !tipAddrB) { return false; }
+
+            const [tipA, tipB] = await getIbGibsFromCache_fallbackToSpaces({
+                addrs: [tipAddrA, tipAddrB],
+                readCache_graph: ibGibReadCache,
+                space,
+            });
+
+            return this.isB2tFSNode(tipA) || this.isB2tFSNode(tipB);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)} (E: 8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e)`);
+            return false;
+        }
+    }
+
+    async graft(context: GraftContext): Promise<GraftTimelinesResult> {
+        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 }));
+
+            // 3. Replay orphan branch transforms onto base tip
+            const [latestCommonFrameIbGib] = await getIbGibsFromCache_fallbackToSpaces({
+                addrs: [latestCommonFrameAddr],
+                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));
+            }
+
+            const dnaIbGibsToApply = await getIbGibsFromCache_fallbackToSpaces({
+                addrs: dnaAddrsToApply,
+                readCache_graph: ibGibReadCache,
+                space,
+            });
+
+            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 (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 });
+                    }
+                }
+            }
+
+            // 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 });
+
+            let mergedRootItem: B2tFSItemIbGib_V1 | undefined;
+            if (lcaItem || baseItem || orphanItem) {
+                mergedRootItem = await this.mergeTreeNodes({
+                    lcaItem,
+                    baseItem,
+                    orphanItem,
+                    space,
+                    readCache_graph: ibGibReadCache,
+                    newGraftDnaIbGibs,
+                    newGraftedIntermediateIbGibs_ordered,
+                });
+            }
+
+
+            // 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;
+                    }
+                }
+            }
+
+            // 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,
+                latestCommonFrameAddr,
+                baseAddrsSinceLCA: baseBranchAddrs,
+                orphanAddrsSinceLCA: orphanBranchAddrs,
+                dnaAddrsApplied: dnaAddrsToApply,
+            });
+
+            if (space) {
+                await putInSpace({ ibGib: graftInfo, space });
+            }
+            const graftInfoAddr = getIbGibAddr({ ibGib: graftInfo });
+            const resRel8GraftInfo = await rel8({
+                src: currentGraftTip,
+                rel8nsToAddByAddr: {
+                    [GRAFT_INFO_REL8N_NAME]: [graftInfoAddr],
+                },
+                dna: true,
+                nCounter: !!currentGraftTip.data?.n,
+            });
+
+            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;
+
+            return {
+                dnasReplayed: dnaIbGibsToApply,
+                dnasCreatedInGraft: newGraftDnaIbGibs,
+                intermediateIbGibsCreatedInGraft: newGraftedIntermediateIbGibs_ordered,
+                newGraftTip: finalGraftTip,
+                graftInfoCreated: graftInfo,
+            };
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)} (E: 7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e)`);
+            throw error;
+        } finally {
+            if (logalot) {
+                console.log(`${lc} complete. (I: 6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f)`);
+            }
+        }
+    }
+
+    private async fetchIbGib({
+        addr,
+        space,
+        readCache_graph,
+    }: {
+        addr?: string;
+        space?: IbGibSpaceAny;
+        readCache_graph?: FlatIbGibGraph;
+    }): Promise<IbGib_V1 | undefined> {
+        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]; }
+        }
+        if (!space) { return undefined; }
+        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: any) => !!x);
+                if (found) { return found; }
+            }
+        } catch {
+            // Suppress fetch error if address not found
+        }
+        return undefined;
+    }
+
+
+    private async resolveRootItemNode({
+        nodeOrAddr,
+        space,
+        readCache_graph,
+    }: {
+        nodeOrAddr: IbGib_V1 | string | undefined;
+        space?: any;
+        readCache_graph?: FlatIbGibGraph;
+    }): Promise<B2tFSItemIbGib_V1 | undefined> {
+        if (!nodeOrAddr) { return undefined; }
+        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.ib?.startsWith('b2tfs_item') || node.data?.classname === 'B2tFSItemIbGib_V1') {
+            return node as B2tFSItemIbGib_V1;
+        }
+
+        return undefined;
+    }
+
+    private async getFilePayloadBuffer({
+        fileItem,
+        space,
+        readCache_graph,
+    }: {
+        fileItem?: B2tFSItemIbGib_V1;
+        space?: any;
+        readCache_graph?: FlatIbGibGraph;
+    }): Promise<{ buffer: Uint8Array; binIbGib?: IbGib_V1 } | undefined> {
+        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 || binIbGib.data === undefined) { return undefined; }
+
+        let fileData: Uint8Array;
+        const dataObj = binIbGib.data as any;
+        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 as Uint8Array;
+        } 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 as object);
+                fileData = new Uint8Array(vals as number[]);
+            }
+        } else {
+            fileData = new Uint8Array(0);
+        }
+
+
+        return { buffer: fileData, binIbGib };
+    }
+
+    private async getChildItemsMap({
+        folderItem,
+        space,
+        readCache_graph,
+    }: {
+        folderItem?: B2tFSItemIbGib_V1;
+        space?: any;
+        readCache_graph?: FlatIbGibGraph;
+    }): Promise<Map<string, B2tFSItemIbGib_V1>> {
+        const map = new Map<string, B2tFSItemIbGib_V1>();
+        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 }) as B2tFSItemIbGib_V1;
+            if (childNode && childNode.data?.name) {
+                map.set(childNode.data.name, childNode);
+            }
+        }
+        return map;
+    }
+
+    private async mergeTreeNodes({
+        lcaItem,
+        baseItem,
+        orphanItem,
+        space,
+        readCache_graph,
+        newGraftDnaIbGibs,
+        newGraftedIntermediateIbGibs_ordered,
+    }: {
+        lcaItem?: B2tFSItemIbGib_V1;
+        baseItem?: B2tFSItemIbGib_V1;
+        orphanItem?: B2tFSItemIbGib_V1;
+        space?: any;
+        readCache_graph?: FlatIbGibGraph;
+        newGraftDnaIbGibs: IbGib_V1[];
+        newGraftedIntermediateIbGibs_ordered: IbGib_V1[];
+    }): Promise<B2tFSItemIbGib_V1 | undefined> {
+        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') {
+            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;
+        }
+
+        return baseItem;
+    }
+}
+
+export const B2tFSItem3WayMergeStrategy = B2tFS3WayGraftStrategy;