@ibgib/vcs-gib 0.0.21 → 0.0.26

package/src/engine/merge/{b2tfs-3way-merge-strategy.mts → b2tfs-3way-graft-strategy.mts}

@@ -1,42 +1,53 @@
 /**
- * @module b2tfs-3way-merge-strategy
+ * @module b2tfs-3way-graft-strategy
  *
- * Extensible Graft Merge Strategy for 3-way B2tFS filesystem snapshot trees and text files.
+ * ============================================================================
+ * ⚠️ CRITICAL GRAFT STRATEGY GUIDANCE WARNING ⚠️
+ * BEFORE MAKING ANY CHANGES TO THIS FILE, YOU MUST CONSULT AND CAREFULLY READ:
+ *   libs/core-gib/src/sync/GRAFT_STRATEGY_GUIDANCE.md
+ *
+ * Graft strategies must strictly fulfill the `GraftTimelinesResult` contract,
+ * ensure timeline `n` monotonicity (using Math.max over base/orphan branch frames),
+ * and include ALL newly referenced ancillary dependency nodes (comments, binary
+ * stones, DNAs) in `ancillaryIbGibsCreated` so that the destination branch
+ * space is completely self-contained.
+ * ============================================================================
+ *
+ * 3-way text line diff graft strategy for B2tFS file item timelines.
+ * Reconciles diverging file content via 3-way line diff (LCA, Base, Orphan)
+ * and inserts Git conflict markers when line edits collide.
+ *
+ * Non-text binaries and non-file items return early / false in `canGraft` and
+ * fall through to `DefaultDnaReplayGraftStrategy`.
+ * Folder hierarchies are re-synchronized post-merge via `reifyB2tFSHierarchy`.
  */
 
-import crypto from 'node:crypto';
-
-import { extractErrorMsg, hash, pretty } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+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 { getGib, isDna } 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 { GraftContext, GraftStrategy, GraftTimelinesResult } 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 { getBinIb, getIbGibsFromCache_fallbackToSpaces, splitPerTjpAndOrDna, getTimelinesGroupedByTjp } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { getDependencyGraph } from '@ibgib/core-gib/dist/common/other/graph-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 { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.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, B2tFSType } from '../item/item-types.mjs';
+import { B2tFSItemIbGib_V1, 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';
+import { B2tFS3WayAddlGraftDetails } from './b2tfs-3way-graft-types.mjs';
 
-const lcFile = `[b2tfs-3way-merge-strategy]`;
-const logalot = GLOBAL_LOG_A_LOT || true;
+const lcFile = `[b2tfs-3way-graft-strategy]`;
+const logalot = GLOBAL_LOG_A_LOT;
 const mergeDiag = `[MERGE DIAGNOSTIC]`;
 
 /**
@@ -61,9 +72,6 @@ export function perform3WayTextLineMerge({
     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 };
     }
@@ -74,7 +82,6 @@ export function perform3WayTextLineMerge({
         return { mergedText: textBase, hasConflict: false };
     }
 
-
     const linesLCA = textLCA.split(/\r?\n/);
     const linesBase = textBase.split(/\r?\n/);
     const linesOrphan = textOrphan.split(/\r?\n/);
@@ -157,6 +164,12 @@ export function perform3WayTextLineMerge({
     };
 }
 
+/**
+ * 3-way text line diff graft strategy for B2tFS file item timelines.
+ *
+ * ⚠️ **IMPORTANT**: Before making ANY changes to this class or its methods, consult:
+ * `libs/core-gib/src/sync/GRAFT_STRATEGY_GUIDANCE.md`.
+ */
 export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements GraftStrategy {
     readonly strategyId: string = 'B2tFS3WayGraftStrategy';
     private lc = '[B2tFS3WayGraftStrategy]';
@@ -164,12 +177,7 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
     /**
      * 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> {
@@ -177,19 +185,16 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         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 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 */
+                return false;
             }
 
             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 */
+                if (logalot) { console.log(`${lc} we don't have two tip addrs? (I: b20b6de462c35e0e74360cc8d317f126)`); }
+                return false;
             }
 
             const [tipA, tipB] = await getIbGibsFromCache_fallbackToSpaces({
@@ -198,26 +203,26 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
                 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)`); }
+            if (!tipA) { throw new Error(`(UNEXPECTED) tipA falsy? (E: 752101026888140f074614e893531826)`); }
+            if (!tipB) { throw new Error(`(UNEXPECTED) tipB falsy? (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)`)
+                    console.error(`${lc}${mergeDiag} (UNEXPECTED)(NOT THROWN) only tipA or tipB but not both are b2tfs items? (E: cacb38796da881268898e9d1af245826)`);
                 }
-                return false; /* <<<< returns early */
+                return false;
             }
 
-            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)`); }
+            if (tipA.data.fsType !== tipB.data.fsType) {
+                throw new Error(`(UNEXPECTED) tipA.data.fsType (${tipA.data.fsType}) !== tipB.data.fsType (${tipB.data.fsType})? (E: c01c1885ac738f679813117852c48426)`);
+            }
 
-            // only do files. folders can use the replay dna strategy.
+            // only do files. folders and other containers fall back to DefaultDnaReplayGraftStrategy.
             const isFile = tipA.data.fsType === B2tFSType.file;
-            if (!isFile) { return false; /* <<<< returns early */ }
+            if (!isFile) { return false; }
 
-            // passed gauntlet, we have a b2tfs file item that we can merge
             return true;
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)} (E: 8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e)`);
@@ -225,6 +230,16 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         }
     }
 
+    /**
+     * Executes 3-way line diff text graft across LCA, Base, and Orphan file items.
+     *
+     * ⚠️ **CRITICAL CONTRACT**: Before modifying this method, review:
+     * `libs/core-gib/src/sync/GRAFT_STRATEGY_GUIDANCE.md`
+     * Ensure:
+     * 1. Monotonic `n` counter (`highestDataN = Math.max(...)`)
+     * 2. Full dependency graph inclusion in `ancillaryIbGibsCreated` (comments, bin stones, DNAs)
+     * 3. Self-contained destination branch space
+     */
     async graft(context: GraftContext): Promise<GraftTimelinesResult | undefined> {
         const lc = `${lcFile}[${this.strategyId}][${this.graft.name}]`;
         try {
@@ -242,7 +257,6 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
                 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);
@@ -262,7 +276,7 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
             });
             const tipB_receiver = branchB_receiver_sinceLCA.at(-1)!;
 
-            // 2. Base & Orphan tip determination (directional preference) via DRY base helper
+            // 2. Base & Orphan resolution via DRY helper
             const {
                 baseTip,
                 baseBranch,
@@ -280,109 +294,13 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
             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,
-            });
+            if (logalot) {
+                console.log(`${lc} baseBranchAddrs:\n${baseBranchAddrs.join('\n')} (I: 2cad420d7bc822f798b8a8785f1f8c26)`);
+                console.log(`${lc} orphanBranchAddrs:\n${orphanBranchAddrs.join('\n')} (I: cc86489d6737e2aced42b585cba13526)`);
+            }
 
-            // 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
+            // 3. 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 });
@@ -394,68 +312,49 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
 
             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)`);
+                throw new Error(`(UNEXPECTED) fsType === B2tFSType.folder? Folders fall back to DefaultDnaReplayGraftStrategy and reification. (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)`); }
+            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 });
+            const basePayload = await this.getFilePayloadBuffer({ fileItem: baseItem, space, readCache_graph: ibGibReadCache });
+            const orphanPayload = await this.getFilePayloadBuffer({ fileItem: orphanItem, space, readCache_graph: ibGibReadCache });
+
             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)`);
+                    console.log(`${lc} Non-text binary file detected (${baseItem.data?.name}). Skipping 3-way line diff and falling through. (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 */
+                return undefined;
             }
 
-            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)`); }
+            if (!lcaPayload) { throw new Error(`(UNEXPECTED) lcaPayload falsy? (E: 0b82892204482f5538a430b8915b7826)`); }
+            if (!basePayload) { throw new Error(`(UNEXPECTED) basePayload falsy? (E: af1f68a020280b3a5d6ed4a812acd426)`); }
+            if (!orphanPayload) { throw new Error(`(UNEXPECTED) orphanPayload falsy? (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}`);
+            if (logalot) {
+                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}`);
+            if (logalot) {
+                console.log(`${lc}${mergeDiag} mergedText:\n${mergedText}`);
+            }
 
             const dataBuffer = Buffer.from(mergedText, 'utf8');
             const fileHash = await hash({ s: mergedText });
@@ -478,38 +377,84 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
 
             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: B2tFSItemIbGib_V1) => number = (item: B2tFSItemIbGib_V1) => {
+            const fnGetN = (item: B2tFSItemIbGib_V1): number => {
                 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 highestDataN = Math.max(baseItemDataN, orphanItemDataN);
+
+            const lcaCommentAddrs = lcaItem.rel8ns?.comment || [];
+            const lcaCommentAddrsSet = new Set(lcaCommentAddrs);
+            const mergedCommentAddrsSinceLCA_base = (baseItem.rel8ns?.comment || []).filter(addr => !lcaCommentAddrsSet.has(addr));
+            const mergedCommentAddrsSinceLCA_orphan = (orphanItem.rel8ns?.comment || []).filter(addr => !lcaCommentAddrsSet.has(addr));
+            const newCommentAddrs = Array.from(new Set([...mergedCommentAddrsSinceLCA_base, ...mergedCommentAddrsSinceLCA_orphan]));
+            const allMergedCommentAddrs = Array.from(new Set([...lcaCommentAddrs, ...newCommentAddrs]));
+
+            const commentDepIbGibs: IbGib_V1[] = [];
+            if (newCommentAddrs.length > 0) {
+                for (const cAddr of newCommentAddrs) {
+                    const cIb = await this.fetchIbGib({ addr: cAddr, space, readCache_graph: ibGibReadCache });
+                    if (!cIb) {
+                        throw new Error(`(UNEXPECTED) Comment ibgib for address '${cAddr}' not found in cache or space (E: a1b2c3d4e5f67a8b9c0d1e2f3a4b5c6d)`);
+                    }
+                    commentDepIbGibs.push(cIb);
+                    const cDepGraph = await getDependencyGraph({
+                        ibGib: cIb,
+                        space,
+                        ibGibs: ibGibReadCache ? Object.values(ibGibReadCache) : undefined,
+                    });
+                    for (const depNode of Object.values(cDepGraph)) {
+                        const depAddr = getIbGibAddr({ ibGib: depNode });
+                        if (!commentDepIbGibs.some(x => getIbGibAddr({ ibGib: x }) === depAddr)) {
+                            commentDepIbGibs.push(depNode);
+                        }
+                    }
+                }
+
+                const { mapWithTjp_YesDna, mapWithoutTjps } = splitPerTjpAndOrDna({ ibGibs: commentDepIbGibs });
+
+                // Put DNA and non-timeline stones into space with isDna flag
+                for (const dnaOrStone of Object.values(mapWithoutTjps)) {
+                    if (space) {
+                        await putInSpace({ ibGib: dnaOrStone, space, isDna: isDna({ ibGib: dnaOrStone }) });
+                    }
+                }
+
+                // Register timeline frames in order
+                const timelinesByTjp = getTimelinesGroupedByTjp({ ibGibs: Object.values(mapWithTjp_YesDna) });
+                for (const tjpAddr of Object.keys(timelinesByTjp)) {
+                    const timeline = timelinesByTjp[tjpAddr];
+                    for (const frame of timeline) {
+                        if (space) {
+                            await putInSpace({ ibGib: frame, space });
+                            await registerNewIbGib({ ibGib: frame, space });
+                        }
+                    }
+                }
+            }
 
             const evolveRes = await evolveB2tFSItemIbGib({
                 existingItem: baseItem,
                 dataToUpdate: {
                     fileHash,
-                    n: lowestDataN + 1,
+                    n: highestDataN + 1,
                 },
                 rel8nsToUpdate: {
                     [BINARY_REL8N_NAME]: [binAddr],
+                    ...(allMergedCommentAddrs.length > 0 ? { comment: allMergedCommentAddrs } : {}),
                 },
             });
 
-            // 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)`); }
+            if (!evolveRes.dnas) { throw new Error(`(UNEXPECTED) evolveRes.dnas falsy? (E: e640e892cc76c77f98f3881301035826)`); }
+            if (!evolveRes.newIbGib) { throw new Error(`(UNEXPECTED) evolveRes.newIbGib falsy? (E: 9e488d07772827b66a2aff4801905426)`); }
             const newItemWithNewBinPayload = evolveRes.newIbGib as B2tFSItemIbGib_V1;
             const newItemAddr = getIbGibAddr({ ibGib: newItemWithNewBinPayload });
             if (logalot) { console.log(`${lc} newItemAddr: ${newItemAddr} (I: d23eef651b88be1248ee29ca179eff26)`); }
@@ -519,31 +464,20 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
 
             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
+            // 4. Attach GraftInfo frame
             const graftInfo = await createGraftInfo({
                 conflictStrategy,
                 details: `Merged orphan tip text with the baseTip as a starting point.`,
@@ -584,7 +518,7 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
                 dnasReplayed: [],
                 dnasCreatedInGraft: newGraftDnaIbGibs,
                 intermediateIbGibsCreatedInGraft: newGraftedIntermediateIbGibs_ordered,
-                ancillaryIbGibsCreated: [binIbGib],
+                ancillaryIbGibsCreated: [binIbGib, ...commentDepIbGibs],
                 newGraftTip: finalGraftTip,
                 graftInfoCreated: graftInfo,
             };
@@ -608,28 +542,24 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         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));
+            const gib = addr.includes('^') ? addr.substring(addr.lastIndexOf('^') + 1) : addr;
+            const matchingKey = Object.keys(readCache_graph).find(k => k === addr || (gib && k.endsWith('^' + gib)));
             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: any) => !!x);
+            const res = await getFromSpace({ space, addrs: [addr] });
+            if (res) {
+                const found = res.ibGibs?.find((x: any) => !!x) || (res.rawResultIbGib as any)?.ibGibs?.find((x: any) => !!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;
     }
 
-
     private async resolveRootItemNode({
         nodeOrAddr,
         space,
@@ -650,11 +580,9 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
         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)`);
+            throw new Error(`(UNEXPECTED) node is not a B2tFSItemIbGib_V1? (E: ddabb281ccb2fb1a181109a82046b826)`);
         }
     }
 
@@ -674,7 +602,7 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
 
         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'?
+        if (binIbGib.data === undefined) { return undefined; }
 
         let fileData: Uint8Array;
         const dataObj = binIbGib.data as any;
@@ -697,156 +625,6 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
             fileData = new Uint8Array(0);
         }
 
-
         return { buffer: fileData, binIbGib };
     }
-
-    private async getChildItemsMap({
-        folderItem,
-        space,
-        readCache_graph,
-    }: {
-        folderItem?: B2tFSItemIbGib_V1;
-        space: IbGibSpaceAny;
-        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: IbGibSpaceAny;
-        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') {
-        } 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;