@ibgib/vcs-gib 0.0.23 → 0.0.26

package/src/cli/commands/status-cmd.mts

@@ -7,30 +7,16 @@
 
 import path from 'node:path';
 import fs from 'node:fs/promises';
-import { Dirent } from 'node:fs';
-import crypto from 'node:crypto';
 
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
-
 import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
-import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
-import { B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME } from '../../engine/item/item-types.mjs';
-import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
-import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
-import { isPathFiltered, parseFilterFileContent } from '../../engine/filter/glob-helper.mjs';
-import { getB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
-import { B2tFSStagedItemRecord } from '../../engine/index/index-types.mjs';
 import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { getRepoStatus, VcsStatusItem, PendingCommentInfo } from '../../engine/status/status-helper.mjs';
 
 const lcFile = `[status-cmd]`;
 const logalot = GLOBAL_LOG_A_LOT;
 
-export interface VcsStatusItem {
-    path: string;
-    fsType: 'file' | 'folder';
-    status: 'untracked' | 'modified' | 'deleted' | 'staged';
-}
+export { VcsStatusItem, PendingCommentInfo };
 
 export interface StatusCmdResult {
     branchName: string;
@@ -38,18 +24,21 @@ export interface StatusCmdResult {
     modified: VcsStatusItem[];
     deleted: VcsStatusItem[];
     untracked: VcsStatusItem[];
+    pendingComments: PendingCommentInfo[];
 }
 
 export interface StatusCmdOpts {
     targetDir?: string;
     vcsFolderName?: string;
     quiet?: boolean;
+    comments?: boolean;
 }
 
 export async function executeStatusCmd({
     targetDir = process.cwd(),
     vcsFolderName = '.vcsgib',
     quiet = false,
+    comments = false,
 }: StatusCmdOpts = {}): Promise<StatusCmdResult> {
     const lc = `${lcFile}[${executeStatusCmd.name}]`;
 
@@ -72,170 +61,88 @@ export async function executeStatusCmd({
             throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 4d5e6f7a8b9c10d11e12f13a14b15c6d)`);
         }
 
-        // 1. Fetch authoritative B2tFSIndexIbGib_V1 directly from localSpace
-        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
-        const branchName = indexIbGib?.data?.activeBranch || 'main';
-
-        const activeWorktreeDir = branchName === 'main' ? repoRoot : path.join(repoRoot, 'b', branchName);
-
-        // Target active branch space b2s_<activeBranch>
-        const { space: activeBranchSpace } = await getOrCreateBranchSpace({
+        const statusRes = await getRepoStatus({
             metaspace,
+            localSpace,
             vcsPath,
-            branchName,
-        });
-
-        // 2. Extract staged items directly from in-band B2tFSIndexIbGib_V1 data
-        const stagedMap = new Map<string, B2tFSStagedItemRecord>();
-        const indexStagedPaths = indexIbGib?.data?.stagedPaths || {};
-        for (const [relPath, itemRec] of Object.entries(indexStagedPaths)) {
-            stagedMap.set(relPath, itemRec);
-        }
-
-        // 3. Find active branch root item address from in-band branch graph node
-        let rootItemAddr: string | undefined;
-        const branchAddrs = [
-            ...(indexIbGib?.rel8ns?.branch || []),
-            ...(indexIbGib?.rel8ns?.branch_tjp || []),
-        ];
-
-        if (branchAddrs.length > 0) {
-            let branchIbGibs: B2tFSBranchIbGib_V1[] = [];
-            for (const bAddr of branchAddrs) {
-                const bIbGib = await getIbGibWithMetaspaceFallback({
-                    addr: bAddr,
-                    space: activeBranchSpace,
-                    metaspace,
-                });
-                if (bIbGib) {
-                    branchIbGibs.push(bIbGib as B2tFSBranchIbGib_V1);
-                }
-            }
-
-            const activeBranchIbGib = branchIbGibs.find(
-                (b) => (b as B2tFSBranchIbGib_V1)?.data?.name === branchName,
-            ) as B2tFSBranchIbGib_V1 || (branchIbGibs.at(0) as B2tFSBranchIbGib_V1);
-
-            rootItemAddr = activeBranchIbGib?.rel8ns?.b2tfs_item?.at(0);
-        }
-
-        // Read .ibgibignore patterns
-        let filterPatterns: string[] = [];
-        const ignorePath = path.join(activeWorktreeDir, '.ibgibignore');
-        try {
-            const ignoreContent = await fs.readFile(ignorePath, 'utf8');
-            filterPatterns = parseFilterFileContent(ignoreContent);
-        } catch {
-            // Ignore file missing is fine
-        }
-
-        // 4. Walk active branch graph items
-        const branchItemsMap = new Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>();
-
-        if (rootItemAddr) {
-            const rootItem = await getIbGibWithMetaspaceFallback({
-                addr: rootItemAddr,
-                space: activeBranchSpace,
-                metaspace,
-            }) as B2tFSItemIbGib_V1;
-
-            if (rootItem) {
-                await statusCmd_walkBranchGraph({
-                    item: rootItem,
-                    space: activeBranchSpace,
-                    metaspace,
-                    currentRelPath: '',
-                    outMap: branchItemsMap,
-                });
-            }
-        }
-
-        // 5. Scan physical workspace
-        const physicalItemsMap = new Map<string, { relPath: string; fullPath: string; isDirectory: boolean; fileHash?: string }>();
-        await statusCmd_scanPhysicalWorkspace({
-            dirPath: activeWorktreeDir,
-            baseDir: activeWorktreeDir,
+            repoRoot,
             vcsFolderName,
-            filterPatterns,
-            outMap: physicalItemsMap,
         });
 
-        // 6. Categorize items into staged, modified, deleted, untracked
-        const staged: VcsStatusItem[] = [];
-        const modified: VcsStatusItem[] = [];
-        const deleted: VcsStatusItem[] = [];
-        const untracked: VcsStatusItem[] = [];
-
-        // Add staged items
-        for (const [relPath, stagedRec] of stagedMap.entries()) {
-            staged.push({
-                path: relPath,
-                fsType: stagedRec.fsType || 'file',
-                status: 'staged',
-            });
-        }
-
-        // Compare physical items against branch items and staged
-        for (const [relPath, physItem] of physicalItemsMap.entries()) {
-            if (stagedMap.has(relPath)) {
-                continue; // Staged item already reported
-            }
-
-            const branchItem = branchItemsMap.get(relPath);
-            if (!branchItem) {
-                // Not in active branch snapshot and not staged => untracked
-                untracked.push({
-                    path: relPath,
-                    fsType: physItem.isDirectory ? 'folder' : 'file',
-                    status: 'untracked',
-                });
-            } else {
-                // Tracked in branch -> check if modified
-                if (!physItem.isDirectory && physItem.fileHash && branchItem.fileHash && physItem.fileHash !== branchItem.fileHash) {
-                    modified.push({
-                        path: relPath,
-                        fsType: 'file',
-                        status: 'modified',
-                    });
-                }
-            }
-        }
+        const { branchName, staged, modified, deleted, untracked, pendingComments } = statusRes;
 
-        // Check for deleted items (in branch snapshot, but not in physical workspace and not staged)
-        for (const [relPath, branchItem] of branchItemsMap.entries()) {
-            if (!relPath || relPath === '.' || relPath === '') { continue; }
-            if (!physicalItemsMap.has(relPath) && !stagedMap.has(relPath)) {
-                deleted.push({
-                    path: relPath,
-                    fsType: branchItem.fsType,
-                    status: 'deleted',
-                });
-            }
+        const commentsByTarget = new Map<string, PendingCommentInfo[]>();
+        for (const c of pendingComments) {
+            const list = commentsByTarget.get(c.targetRelPath) || [];
+            list.push(c);
+            commentsByTarget.set(c.targetRelPath, list);
         }
 
         if (!quiet) {
             console.log(`On branch ${branchName} (I: 9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b)`);
+
             if (staged.length > 0) {
                 console.log('\nChanges to be committed:');
                 for (const item of staged) {
+                    const itemComments = commentsByTarget.get(item.path) || [];
                     console.log(`  staged:   ${item.path}`);
+                    if (itemComments.length === 0) {
+                        console.log(`    (hint: no comment file found for ${item.path} - run 'vcs gmsg')`);
+                    } else if (comments) {
+                        for (const comm of itemComments) {
+                            console.log(`    [comment: ${comm.commentRelPath}]`);
+                            const lines = comm.content.trim().split('\n');
+                            for (const line of lines) {
+                                console.log(`      ${line}`);
+                            }
+                        }
+                    }
                 }
             }
+
             if (modified.length > 0 || deleted.length > 0) {
                 console.log('\nChanges not staged for commit:');
                 for (const item of modified) {
+                    const itemComments = commentsByTarget.get(item.path) || [];
                     console.log(`  modified: ${item.path}`);
+                    if (comments && itemComments.length > 0) {
+                        for (const comm of itemComments) {
+                            console.log(`    [comment: ${comm.commentRelPath}]`);
+                            const lines = comm.content.trim().split('\n');
+                            for (const line of lines) {
+                                console.log(`      ${line}`);
+                            }
+                        }
+                    }
                 }
                 for (const item of deleted) {
                     console.log(`  deleted:  ${item.path}`);
                 }
             }
+
             if (untracked.length > 0) {
                 console.log('\nUntracked files:');
                 for (const item of untracked) {
                     console.log(`  untracked:${item.path}`);
                 }
             }
+
+            // Pending folder-level comments
+            const folderComments = pendingComments.filter(c => c.targetType === 'folder');
+            if (folderComments.length > 0) {
+                console.log('\nPending folder comments:');
+                for (const fc of folderComments) {
+                    const folderLabel = fc.targetRelPath ? fc.targetRelPath : '(root)';
+                    console.log(`  folder: ${folderLabel} [${fc.commentRelPath}]`);
+                    if (comments) {
+                        const lines = fc.content.trim().split('\n');
+                        for (const line of lines) {
+                            console.log(`      ${line}`);
+                        }
+                    }
+                }
+            }
+
             if (staged.length === 0 && modified.length === 0 && deleted.length === 0 && untracked.length === 0) {
                 console.log('nothing to commit, working tree clean');
             }
@@ -247,6 +154,7 @@ export async function executeStatusCmd({
             modified,
             deleted,
             untracked,
+            pendingComments,
         };
     } catch (error) {
         console.error(`${lc} ${extractErrorMsg(error)} (E: 5e6f7a8b9c10d11e12f13a14b15c6d7e)`);
@@ -257,110 +165,3 @@ export async function executeStatusCmd({
         }
     }
 }
-
-// #region statusCmd_walkBranchGraph
-async function statusCmd_walkBranchGraph({
-    item,
-    space,
-    metaspace,
-    currentRelPath,
-    outMap,
-}: {
-    item: B2tFSItemIbGib_V1;
-    space: any;
-    metaspace?: any;
-    currentRelPath: string;
-    outMap: Map<string, { relPath: string; fileHash?: string; fsType: 'file' | 'folder' }>;
-}): Promise<void> {
-    if (!item || !item.data) { return; }
-
-    const { fsType, fileHash } = item.data;
-    if (currentRelPath) {
-        outMap.set(currentRelPath, { relPath: currentRelPath, fileHash, fsType });
-    }
-
-    if (fsType === 'folder') {
-        const childAddrs = item.rel8ns?.[B2TFS_CHILD_ITEM_REL8N_NAME] || [];
-        for (const childAddr of childAddrs) {
-            const childItem = await getIbGibWithMetaspaceFallback({
-                addr: childAddr,
-                space,
-                metaspace,
-            }) as B2tFSItemIbGib_V1;
-            if (childItem && childItem.data) {
-                const childRelPath = currentRelPath
-                    ? `${currentRelPath}/${childItem.data.name}`
-                    : childItem.data.name;
-                await statusCmd_walkBranchGraph({
-                    item: childItem,
-                    space,
-                    metaspace,
-                    currentRelPath: childRelPath,
-                    outMap,
-                });
-            }
-        }
-    }
-}
-// #endregion statusCmd_walkBranchGraph
-
-// #region statusCmd_scanPhysicalWorkspace
-async function statusCmd_scanPhysicalWorkspace({
-    dirPath,
-    baseDir,
-    vcsFolderName,
-    filterPatterns,
-    outMap,
-}: {
-    dirPath: string;
-    baseDir: string;
-    vcsFolderName: string;
-    filterPatterns: string[];
-    outMap: Map<string, { relPath: string; fullPath: string; isDirectory: boolean; fileHash?: string }>;
-}): Promise<void> {
-    let entries: Dirent[] = [];
-    try {
-        entries = await fs.readdir(dirPath, { withFileTypes: true });
-    } catch {
-        return;
-    }
-
-    for (const entry of entries) {
-        const fullEntryPath = path.join(dirPath, entry.name);
-        const relPath = path.relative(baseDir, fullEntryPath).replace(/\\/g, '/');
-
-        // Ignore vcs storage folder, .git, and worktrees folder b
-        if (
-            relPath === vcsFolderName || relPath.startsWith(vcsFolderName + '/') ||
-            relPath === '.git' || relPath.startsWith('.git/') ||
-            relPath === 'b' || relPath.startsWith('b/')
-        ) {
-            continue;
-        }
-
-        if (isPathFiltered({ relativePath: relPath, isDirectory: entry.isDirectory(), filterPatterns })) {
-            continue;
-        }
-
-        if (entry.isDirectory()) {
-            outMap.set(relPath, { relPath, fullPath: fullEntryPath, isDirectory: true });
-            await statusCmd_scanPhysicalWorkspace({
-                dirPath: fullEntryPath,
-                baseDir,
-                vcsFolderName,
-                filterPatterns,
-                outMap,
-            });
-        } else if (entry.isFile()) {
-            let fileHash: string | undefined;
-            try {
-                const fileData = await fs.readFile(fullEntryPath);
-                fileHash = crypto.createHash('sha256').update(fileData).digest('hex');
-            } catch {
-                // File unreadable
-            }
-            outMap.set(relPath, { relPath, fullPath: fullEntryPath, isDirectory: false, fileHash });
-        }
-    }
-}
-// #endregion statusCmd_scanPhysicalWorkspace

package/src/cli/vcs-cli-main.mts

@@ -20,6 +20,7 @@ import { executeCheckoutCmd } from './commands/checkout-cmd.mjs';
 import { executeMergeCmd } from './commands/merge-cmd.mjs';
 import { executeResetCmd } from './commands/reset-cmd.mjs';
 import { executeRestoreCmd } from './commands/restore-cmd.mjs';
+import { executeGenerateCommentCmd } from './commands/generate-comment-cmd.mjs';
 import { AUTO_GENERATED_VERSION } from '../AUTO-GENERATED-version.mjs';
 import { GLOBAL_LOG_A_LOT } from '../vcs-gib-constants.mjs';
 
@@ -39,7 +40,8 @@ Usage:
 
 Commands:
   init [dir]            Initialize a new ibgib repository
-  status                Show repository working tree status
+  status                Show repository working tree status (-c, --comments for comment text)
+  generate-comment      Generate .ib.<file>.md metadata comment templates (synonyms: gmsg, gcomm, gen-msg, gen-comment)
   add <path...>         Stage file/folder changes (-a, --all to stage all)
   commit -m "message"   Record snapshot changes to the repository
   log                   Show commit logs
@@ -54,6 +56,7 @@ Flags:
   -v, --version         Show version information
   -m <message>          Commit message
   -b <branch>           Target branch name
+  -c, --comments        Show full comment content in status
   -a, --all             Stage all tracked/untracked files (for add/reset)
   -s, --staged          Unstage specified files from index (for restore)
   -w, --worktree        Revert physical working tree files (for restore)
@@ -91,7 +94,20 @@ export async function main({
             }
             case VCS_SUBCOMMANDS.STATUS: {
                 const targetDir = parsed.positionals[0] || process.cwd();
-                await executeStatusCmd({ targetDir });
+                await executeStatusCmd({
+                    targetDir,
+                    comments: parsed.flags.comments,
+                });
+                break;
+            }
+            case VCS_SUBCOMMANDS.GENERATE_COMMENT:
+            case VCS_SUBCOMMANDS.GEN_COMMENT:
+            case VCS_SUBCOMMANDS.GEN_MSG:
+            case VCS_SUBCOMMANDS.GCOMM:
+            case VCS_SUBCOMMANDS.GMSG: {
+                await executeGenerateCommentCmd({
+                    paths: parsed.positionals,
+                });
                 break;
             }
             case VCS_SUBCOMMANDS.ADD: {
@@ -108,8 +124,13 @@ export async function main({
                 break;
             }
             case VCS_SUBCOMMANDS.LOG: {
-                const targetDir = parsed.positionals[0] || process.cwd();
-                await executeLogCmd({ targetDir });
+                const targetDir = process.cwd();
+                const filePath = parsed.positionals[0];
+                await executeLogCmd({
+                    targetDir,
+                    filePath,
+                    allComments: parsed.flags.all,
+                });
                 break;
             }
             case VCS_SUBCOMMANDS.BRANCH: {

package/src/engine/index/index-helper.mts

@@ -321,6 +321,9 @@ export async function updateB2tFSIndexIbGib({
 
         const newIndexIbGib = res.newIbGib as B2tFSIndexIbGib_V1;
         await persistTransformResult({ resTransform: res, space });
+        if (metaspace.zeroSpace && metaspace.zeroSpace !== space) {
+            await persistTransformResult({ resTransform: res, space: metaspace.zeroSpace });
+        }
         await metaspace.registerNewIbGib({ ibGib: newIndexIbGib });
 
         if (vcsPath) {

package/src/engine/item/item-helper.mts

@@ -242,8 +242,11 @@ function getSpacesArray(metaAny: any): IbGibSpaceAny[] {
 async function fetchFromSpaceSilently(spaceToQuery: IbGibSpaceAny, addrToGet: string): Promise<any> {
     try {
         const resGet = await getFromSpace({ space: spaceToQuery, addrs: [addrToGet] });
-        if (resGet && resGet.success && resGet.ibGibs && resGet.ibGibs.length > 0) {
-            return resGet.ibGibs[0];
+        if (resGet) {
+            const found = resGet.ibGibs?.find(x => !!x) || (resGet.rawResultIbGib as any)?.ibGibs?.find((x: any) => !!x);
+            if (found) {
+                return found;
+            }
         }
     } catch {
         // Suppress missing address error

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 {