@ibgib/vcs-gib 0.0.23 → 0.0.29

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

@@ -1,6 +1,18 @@
 /**
  * @module b2tfs-3way-graft-strategy
  *
+ * ============================================================================
+ * ⚠️ 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.
@@ -13,14 +25,15 @@
 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 { GraftMergeStrategyBase_V1 } from '@ibgib/core-gib/dist/sync/graft-info/graft-merge-strategy-base-v1.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 } from '@ibgib/core-gib/dist/common/other/ibgib-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';
@@ -151,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]';
@@ -211,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 {
@@ -360,16 +389,67 @@ export class B2tFS3WayGraftStrategy extends GraftMergeStrategyBase_V1 implements
             };
             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 } : {}),
                 },
             });
 
@@ -438,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,
             };
@@ -462,17 +542,16 @@ 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] });
-            if (res && res.ibGibs && res.ibGibs.length > 0) {
-                const found = res.ibGibs.find((x: any) => !!x);
+            if (res) {
+                const found = res.ibGibs?.find((x: any) => !!x) || (res.rawResultIbGib as any)?.ibGibs?.find((x: any) => !!x);
                 if (found) { return found; }
             }
         } catch {

package/src/engine/merge/b2tfs-sync-comments.respec.mts

@@ -0,0 +1,399 @@
+/**
+ * @module b2tfs-sync-comments.respec.node
+ *
+ * Direct in-memory sync & dependency graph verification for B2tFS items and comments.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import {
+    respecfully, ifWe, ifWeMight, iReckon, firstOfEach
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+
+import { clone, hash, getUUID } 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 { SyncSagaCoordinator } from '@ibgib/core-gib/dist/sync/sync-saga-coordinator.mjs';
+import { SyncPeerInnerspace_V1 } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-innerspace/sync-peer-innerspace-v1.mjs';
+import { SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1 } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-innerspace/sync-peer-innerspace-constants.mjs';
+import { SyncConflictStrategy } from '@ibgib/core-gib/dist/sync/sync-constants.mjs';
+import { GraftPreference } from '@ibgib/core-gib/dist/sync/graft-info/graft-info-types.mjs';
+import { GraftStrategyService } from '@ibgib/core-gib/dist/sync/graft-info/graft-strategy-service.mjs';
+import { getDependencyGraph } from '@ibgib/core-gib/dist/common/other/graph-helper.mjs';
+import { createCommentIbGib } from '@ibgib/core-gib/dist/common/comment/comment-helper.mjs';
+import { getBinIb } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { BinIbGib_V1 } from '@ibgib/core-gib/dist/common/bin/bin-types.mjs';
+import { putInSpace, persistTransformResult, registerNewIbGib, getFromSpace, getLatestAddrs } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+
+import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
+import { getOrCreateBranchSpace } from '../branch/branch-space-helper.mjs';
+import { createB2tFSItemIbGib, evolveB2tFSItemIbGib } from '../item/item-helper.mjs';
+import { B2tFSItemIbGib_V1, BINARY_REL8N_NAME } from '../item/item-types.mjs';
+import { B2tFS3WayGraftStrategy } from './b2tfs-3way-graft-strategy.mjs';
+
+const lc = `[apps/vcs-gib/src/engine/merge/b2tfs-sync-comments.respec.node.mts]`;
+const graftStrategySvc = GraftStrategyService.instance;
+
+async function createFileWithBinAndComment({
+    name,
+    content,
+    commentText,
+    space,
+}: {
+    name: string;
+    content: string;
+    commentText?: string;
+    space: any;
+}): Promise<{ fileItem: B2tFSItemIbGib_V1; commentAddr?: string }> {
+    const fileHash = await hash({ s: content });
+    const fileExt = name.includes('.') ? name.split('.').pop() || 'txt' : 'txt';
+    const binIb = getBinIb({ binHash: fileHash, binExt: fileExt, binEncoding: 'utf8' });
+    const binIbGib: BinIbGib_V1 = {
+        ib: binIb,
+        data: Buffer.from(content, 'utf8'),
+        rel8ns: {},
+    };
+    binIbGib.gib = await getGib({ ibGib: binIbGib, hasTjp: false });
+    await putInSpace({ space, ibGib: binIbGib });
+    await registerNewIbGib({ space, ibGib: binIbGib });
+    const binAddr = getIbGibAddr({ ibGib: binIbGib });
+
+    let commentAddr: string | undefined;
+    const rel8nsToAdd: any = {
+        [BINARY_REL8N_NAME]: [binAddr],
+    };
+
+    if (commentText) {
+        const commentRes = await createCommentIbGib({
+            text: commentText,
+        });
+        await persistTransformResult({ resTransform: commentRes, space });
+        await registerNewIbGib({ ibGib: commentRes.newIbGib, space });
+        commentAddr = getIbGibAddr({ ibGib: commentRes.newIbGib });
+        rel8nsToAdd.comment = [commentAddr];
+    }
+
+    const itemRes = await createB2tFSItemIbGib({
+        fsType: 'file',
+        name,
+        rel8ns: rel8nsToAdd,
+    });
+    await persistTransformResult({ resTransform: itemRes, space });
+    await registerNewIbGib({ ibGib: itemRes.newIbGib, space });
+
+    return { fileItem: itemRes.newIbGib as B2tFSItemIbGib_V1, commentAddr };
+}
+
+async function evolveFileWithBinAndComment({
+    existingItem,
+    newContent,
+    commentText,
+    space,
+}: {
+    existingItem: B2tFSItemIbGib_V1;
+    newContent: string;
+    commentText?: string;
+    space: any;
+}): Promise<{ evolvedItem: B2tFSItemIbGib_V1; commentAddr?: string }> {
+    const fileHash = await hash({ s: newContent });
+    const fileExt = existingItem.data?.fileExt || (existingItem.data?.name?.includes('.') ? existingItem.data.name.split('.').pop() || 'txt' : 'txt');
+    const binIb = getBinIb({ binHash: fileHash, binExt: fileExt, binEncoding: 'utf8' });
+    const binIbGib: BinIbGib_V1 = {
+        ib: binIb,
+        data: Buffer.from(newContent, 'utf8'),
+        rel8ns: {},
+    };
+    binIbGib.gib = await getGib({ ibGib: binIbGib, hasTjp: false });
+    await putInSpace({ space, ibGib: binIbGib });
+    await registerNewIbGib({ space, ibGib: binIbGib });
+    const binAddr = getIbGibAddr({ ibGib: binIbGib });
+
+    let commentAddr: string | undefined;
+    const rel8nsToAdd: any = {
+        [BINARY_REL8N_NAME]: [binAddr],
+    };
+
+    if (commentText) {
+        const commentRes = await createCommentIbGib({
+            text: commentText,
+        });
+        await persistTransformResult({ resTransform: commentRes, space });
+        await registerNewIbGib({ ibGib: commentRes.newIbGib, space });
+        commentAddr = getIbGibAddr({ ibGib: commentRes.newIbGib });
+        rel8nsToAdd.comment = [commentAddr];
+    }
+
+    const evolvedRes = await evolveB2tFSItemIbGib({
+        existingItem,
+        rel8nsToUpdate: rel8nsToAdd,
+    });
+    await persistTransformResult({ resTransform: evolvedRes, space });
+    await registerNewIbGib({ ibGib: evolvedRes.newIbGib, space });
+
+    return { evolvedItem: evolvedRes.newIbGib as B2tFSItemIbGib_V1, commentAddr };
+}
+
+await respecfully(lc, `B2tFS Item & Comment Sync Graph Integrity`, async () => {
+
+    firstOfEach(lc, async () => {
+        graftStrategySvc.reset();
+        graftStrategySvc.registerStrategy(new B2tFS3WayGraftStrategy());
+    });
+
+    await ifWe(lc, `transfers single b2tfs item and its attached comment from Space A to Space B`, async () => {
+        const testDir = path.join(process.cwd(), '.test_sync_comments_1');
+        const vcsFolderName = '.vcsgib_test_1';
+        try {
+            const { metaspace, vcsPath } = await bootstrapVcsMetaspace({
+                repoPath: testDir,
+                vcsFolderName,
+            });
+            const { space: spaceA } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_a' });
+            const { space: spaceB } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_b' });
+
+            // 1. Create file item with comment in Space A
+            const { fileItem } = await createFileWithBinAndComment({
+                name: 'app.ts',
+                content: 'const x = 1;',
+                commentText: 'Initial commit comment in Space A',
+                space: spaceA,
+            });
+
+            // 2. Sync A -> B
+            const peer = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
+            await peer.initialized;
+            await peer.initializeOpts({
+                localMetaspace: metaspace,
+                localSpace: spaceA,
+                receiverSpace: spaceB,
+                receiverCoordinator: new SyncSagaCoordinator(),
+                receiverMetaspace: metaspace,
+            });
+
+            const senderCoordinator = new SyncSagaCoordinator();
+            const syncSaga = await senderCoordinator.sync({
+                peer,
+                localSpace: spaceA,
+                metaspace,
+                domainIbGibs: [fileItem],
+                conflictStrategy: SyncConflictStrategy.optimisticWithLCS,
+            });
+            await syncSaga.done;
+
+            // 3. Verify getDependencyGraph in Space B alone without metaspace
+            const fileAddr = getIbGibAddr({ ibGib: fileItem });
+            const resB = await getFromSpace({ addr: fileAddr, space: spaceB });
+            const fileInB = resB.ibGibs?.at(0);
+            iReckon(lc, fileInB).isGonnaBeTruthy();
+
+            const depGraphInB = await getDependencyGraph({
+                ibGib: fileInB,
+                space: spaceB,
+            });
+
+            const graphValues = Object.values(depGraphInB);
+            const commentInGraph = graphValues.find(x => (x.data as any)?.text === 'Initial commit comment in Space A');
+            iReckon(lc, commentInGraph).isGonnaBeTruthy();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `syncs accreted comments bidirectionally between Space A and Space B`, async () => {
+        const testDir = path.join(process.cwd(), '.test_sync_comments_2');
+        const vcsFolderName = '.vcsgib_test_2';
+        try {
+            const { metaspace, vcsPath } = await bootstrapVcsMetaspace({
+                repoPath: testDir,
+                vcsFolderName,
+            });
+            const { space: spaceA } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_a' });
+            const { space: spaceB } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_b' });
+
+            // 1. Create file with comment 1 in Space A
+            const { fileItem: fileItemA1 } = await createFileWithBinAndComment({
+                name: 'app.ts',
+                content: 'const x = 1;',
+                commentText: 'Comment 1 from Space A',
+                space: spaceA,
+            });
+
+            // 2. Sync A -> B
+            const peerA2B = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
+            await peerA2B.initialized;
+            await peerA2B.initializeOpts({
+                localMetaspace: metaspace,
+                localSpace: spaceA,
+                receiverSpace: spaceB,
+                receiverCoordinator: new SyncSagaCoordinator(),
+                receiverMetaspace: metaspace,
+            });
+
+            const senderA = new SyncSagaCoordinator();
+            const sagaA = await senderA.sync({
+                peer: peerA2B,
+                localSpace: spaceA,
+                metaspace,
+                domainIbGibs: [fileItemA1],
+                conflictStrategy: SyncConflictStrategy.optimisticWithLCS,
+            });
+            await sagaA.done;
+
+            // 3. Evolve file in Space B with comment 2
+            const fileAddrA1 = getIbGibAddr({ ibGib: fileItemA1 });
+            const fileInB1 = (await getFromSpace({ addr: fileAddrA1, space: spaceB })).ibGibs?.at(0) as B2tFSItemIbGib_V1;
+            const { evolvedItem: fileInB2 } = await evolveFileWithBinAndComment({
+                existingItem: fileInB1,
+                newContent: 'const x = 2;',
+                commentText: 'Comment 2 from Space B',
+                space: spaceB,
+            });
+
+            // 4. Sync B -> A
+            const peerB2A = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
+            await peerB2A.initialized;
+            await peerB2A.initializeOpts({
+                localMetaspace: metaspace,
+                localSpace: spaceB,
+                receiverSpace: spaceA,
+                receiverCoordinator: new SyncSagaCoordinator(),
+                receiverMetaspace: metaspace,
+            });
+
+            const senderB = new SyncSagaCoordinator();
+            const sagaB = await senderB.sync({
+                peer: peerB2A,
+                localSpace: spaceB,
+                metaspace,
+                domainIbGibs: [fileInB2],
+                conflictStrategy: SyncConflictStrategy.optimisticWithLCS,
+            });
+            await sagaB.done;
+
+            // 5. Verify Space A has full graph containing both comments
+            const fileAddrB2 = getIbGibAddr({ ibGib: fileInB2 });
+            const fileInA2 = (await getFromSpace({ addr: fileAddrB2, space: spaceA })).ibGibs?.at(0);
+            iReckon(lc, fileInA2).isGonnaBeTruthy();
+
+            const depGraphInA = await getDependencyGraph({
+                ibGib: fileInA2,
+                space: spaceA,
+            });
+
+            const graphValuesA = Object.values(depGraphInA);
+            const comment1 = graphValuesA.find(x => (x.data as any)?.text === 'Comment 1 from Space A');
+            const comment2 = graphValuesA.find(x => (x.data as any)?.text === 'Comment 2 from Space B');
+            iReckon(lc, comment1).isGonnaBeTruthy();
+            iReckon(lc, comment2).isGonnaBeTruthy();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `preserves and transfers all comments in full 3-way graft merge`, async () => {
+        const testDir = path.join(process.cwd(), '.test_sync_comments_3');
+        const vcsFolderName = '.vcsgib_test_3';
+        try {
+            const { metaspace, vcsPath } = await bootstrapVcsMetaspace({
+                repoPath: testDir,
+                vcsFolderName,
+            });
+            const { space: spaceA } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_a' });
+            const { space: spaceB } = await getOrCreateBranchSpace({ metaspace, vcsPath, branchName: 'branch_b' });
+
+            // 1. Initial base file in Space A
+            const { fileItem: lcaFile } = await createFileWithBinAndComment({
+                name: 'app.ts',
+                content: 'const a = 1;\nconst b = 2;\n',
+                commentText: 'Base commit comment',
+                space: spaceA,
+            });
+
+            // 2. Sync base file from A -> B so both spaces share the LCA
+            const peerA2B = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
+            await peerA2B.initialized;
+            await peerA2B.initializeOpts({
+                localMetaspace: metaspace,
+                localSpace: spaceA,
+                receiverSpace: spaceB,
+                receiverCoordinator: new SyncSagaCoordinator(),
+                receiverMetaspace: metaspace,
+            });
+            const senderA = new SyncSagaCoordinator();
+            const initSaga = await senderA.sync({
+                peer: peerA2B,
+                localSpace: spaceA,
+                metaspace,
+                domainIbGibs: [lcaFile],
+                conflictStrategy: SyncConflictStrategy.optimisticWithLCS,
+            });
+            await initSaga.done;
+
+            // 3. Branch A: evolve file in Space A with comment A
+            const { evolvedItem: fileA } = await evolveFileWithBinAndComment({
+                existingItem: lcaFile,
+                newContent: 'const a = 100;\nconst b = 2;\n',
+                commentText: 'Branch A comment (updated a to 100)',
+                space: spaceA,
+            });
+
+            // 4. Branch B: evolve file in Space B with comment B
+            const lcaInB = (await getFromSpace({ addr: getIbGibAddr({ ibGib: lcaFile }), space: spaceB })).ibGibs?.at(0) as B2tFSItemIbGib_V1;
+            const { evolvedItem: fileB } = await evolveFileWithBinAndComment({
+                existingItem: lcaInB,
+                newContent: 'const a = 1;\nconst b = 200;\n',
+                commentText: 'Branch B comment (updated b to 200)',
+                space: spaceB,
+            });
+
+            // 5. Merge Branch A into Branch B (Space A -> Space B) with 3-way graft
+            const peerMerge = new SyncPeerInnerspace_V1(clone(SYNC_PEER_INNERSPACE_DEFAULT_DATA_V1));
+            await peerMerge.initialized;
+            await peerMerge.initializeOpts({
+                localMetaspace: metaspace,
+                localSpace: spaceA,
+                receiverSpace: spaceB,
+                receiverCoordinator: new SyncSagaCoordinator(),
+                receiverMetaspace: metaspace,
+            });
+            const mergeCoordinator = new SyncSagaCoordinator();
+            const mergeSaga = await mergeCoordinator.sync({
+                peer: peerMerge,
+                localSpace: spaceA,
+                metaspace,
+                domainIbGibs: [fileA],
+                conflictStrategy: SyncConflictStrategy.optimisticWithLCS,
+                graftPreference: GraftPreference.receiver,
+            });
+            await mergeSaga.done;
+
+            // 6. Inspect grafted tip in Space B
+            const tjpAddr = fileB.rel8ns?.tjp?.at(0) || getIbGibAddr({ ibGib: fileB });
+            const resLatestInB = await getLatestAddrs({ addrs: [tjpAddr], space: spaceB });
+            const latestAddrInB = (resLatestInB?.data as any)?.latestAddrsMap?.[tjpAddr];
+            iReckon(lc, latestAddrInB).isGonnaBeTruthy();
+
+            const resGraftedInB = await getFromSpace({ addr: latestAddrInB, space: spaceB });
+            const graftedTipInB = resGraftedInB.ibGibs?.at(0);
+            iReckon(lc, graftedTipInB).isGonnaBeTruthy();
+
+            // 7. Verify getDependencyGraph strictly inside spaceB
+            const depGraphB = await getDependencyGraph({
+                ibGib: graftedTipInB,
+                space: spaceB,
+            });
+
+            const graphValuesB = Object.values(depGraphB);
+            const commentBase = graphValuesB.find(x => (x.data as any)?.text === 'Base commit comment');
+            const commentA = graphValuesB.find(x => (x.data as any)?.text === 'Branch A comment (updated a to 100)');
+            const commentB = graphValuesB.find(x => (x.data as any)?.text === 'Branch B comment (updated b to 200)');
+
+            iReckon(lc, commentBase).isGonnaBeTruthy();
+            iReckon(lc, commentA).isGonnaBeTruthy();
+            iReckon(lc, commentB).isGonnaBeTruthy();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+});