@ibgib/vcs-gib 0.0.6

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

@@ -0,0 +1,378 @@
+/**
+ * @module index-helper
+ * 
+ * B2tFS Index Helper functions: space-qualified address formatting and branch index tracking.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { getUUID, extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { ROOT } from '@ibgib/ts-gib/dist/V1/constants.mjs';
+import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { MetaspaceService } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { putInSpace, persistTransformResult } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import { SpaceQualifiedIbGibAddr, B2tFSIndexIbGib_V1, B2tFSIndexData_V1, B2tFSIndexRel8ns_V1 } from './index-types.mjs';
+
+const lcFile = `[index-helper]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export const SOFT_ADDR_DATA_KEY_PREFIX = '@';
+export const SOFT_ADDR_DATA_KEY_PREFIX_SPACE_QUALIFIED = '$@';
+
+/**
+ * Returns a space-qualified address string.
+ * Format: `v:1^spaceId:<spaceId>^<ibGibAddr>`
+ */
+export function getSpaceQualifiedIbGibAddr(
+    optsOrSpaceId: { spaceId: string; ibGibAddr: string } | string,
+    rawIbGibAddr?: string,
+): SpaceQualifiedIbGibAddr {
+    if (typeof optsOrSpaceId === 'object' && optsOrSpaceId !== null) {
+        return `v:1^spaceId:${optsOrSpaceId.spaceId}^${optsOrSpaceId.ibGibAddr}`;
+    }
+    return `v:1^spaceId:${optsOrSpaceId}^${rawIbGibAddr}`;
+}
+
+/**
+ * Parses a space-qualified address string into version, spaceId, ibGibAddr, ib, and gib.
+ */
+export function parseSpaceQualifiedIbGibAddr(
+    optsOrSqAddr: { spaceQualifiedAddr: string } | { sqAddr: string } | string,
+): { version: number; spaceId: string; ibGibAddr: string; ib: string; gib: string } | null {
+    let sqAddr: string | undefined;
+    if (typeof optsOrSqAddr === 'string') {
+        sqAddr = optsOrSqAddr;
+    } else if (typeof optsOrSqAddr === 'object' && optsOrSqAddr !== null) {
+        sqAddr = (optsOrSqAddr as any).spaceQualifiedAddr || (optsOrSqAddr as any).sqAddr;
+    }
+
+    if (!sqAddr || typeof sqAddr !== 'string') {
+        return null;
+    }
+
+    const match = sqAddr.match(/^v:(\d+)\^spaceId:([^\^]+)\^(.+)$/);
+    if (!match) {
+        return null;
+    }
+
+    const version = parseInt(match[1], 10);
+    const spaceId = match[2];
+    const ibGibAddr = match[3];
+
+    const lastCaretIndex = ibGibAddr.lastIndexOf('^');
+    if (lastCaretIndex === -1) {
+        return null;
+    }
+
+    const ib = ibGibAddr.substring(0, lastCaretIndex);
+    const gib = ibGibAddr.substring(lastCaretIndex + 1);
+
+    if (!ib || !gib) {
+        return null;
+    }
+
+    return {
+        version,
+        spaceId,
+        ibGibAddr,
+        ib,
+        gib,
+    };
+}
+
+/**
+ * Helper to extract branch name from space-qualified address or raw atom ib string.
+ */
+export function extractBranchNameFromAddr(addr: string): string | null {
+    if (!addr) {
+        return null;
+    }
+    const sq = parseSpaceQualifiedIbGibAddr(addr);
+    const ib = sq ? sq.ib : (addr.includes('^') ? addr.substring(0, addr.lastIndexOf('^')) : addr);
+    if (ib && ib.startsWith('b2tfs_branch ')) {
+        const parts = ib.split(' ');
+        if (parts.length >= 2 && parts[1]) {
+            return parts[1];
+        }
+    }
+    return null;
+}
+
+/**
+ * Deduplicates branch entries by branch name and merges new branch addresses into existing addresses
+ * without dropping other registered branches.
+ */
+export function mergeBranchAddrs(
+    existingAddrs: string[] = [],
+    newAddrs: string[] = [],
+): string[] {
+    const map = new Map<string, string>();
+    for (const addr of existingAddrs) {
+        if (!addr) {
+            continue;
+        }
+        const bName = extractBranchNameFromAddr(addr) || addr;
+        map.set(bName, addr);
+    }
+    for (const addr of newAddrs) {
+        if (!addr) {
+            continue;
+        }
+        const bName = extractBranchNameFromAddr(addr) || addr;
+        map.set(bName, addr);
+    }
+    return Array.from(map.values());
+}
+
+/**
+ * Creates a new B2tFSIndexIbGib special meta object for a space.
+ */
+export async function createB2tFSIndexIbGib({
+    spaceId,
+    activeSpaceId,
+    activeBranch,
+    space,
+    metaspace,
+    branchAddr,
+}: {
+    spaceId: string;
+    activeSpaceId: string;
+    activeBranch?: string;
+    space: IbGibSpaceAny;
+    metaspace: MetaspaceService;
+    branchAddr?: string;
+}): Promise<B2tFSIndexIbGib_V1> {
+    const lc = `${lcFile}[${createB2tFSIndexIbGib.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d)`);
+        }
+
+        const uuid = await getUUID();
+        const data: B2tFSIndexData_V1 = {
+            mySpaceId: spaceId,
+            activeSpaceId,
+            activeBranch,
+            uuid,
+            classname: 'B2tFSIndexIbGib_V1',
+            '$@branch': [],
+            stagedPaths: {},
+            staged_item: [],
+        };
+
+        const rel8ns: B2tFSIndexRel8ns_V1 = {};
+        if (branchAddr) {
+            const sqBranchAddr = branchAddr.startsWith('v:1^spaceId:')
+                ? branchAddr
+                : getSpaceQualifiedIbGibAddr({
+                    spaceId: space.data?.spaceSubPath || space.data?.name || spaceId,
+                    ibGibAddr: branchAddr,
+                });
+            rel8ns.branch = [sqBranchAddr];
+            rel8ns.branch_tjp = [sqBranchAddr];
+        }
+
+        const res = await Factory_V1.firstGen({
+            parentIbGib: ROOT,
+            ib: `meta special b2tfs_index ${uuid}`,
+            data,
+            rel8ns: Object.keys(rel8ns).length > 0 ? rel8ns : undefined,
+        });
+
+        const indexIbGib = res.newIbGib as B2tFSIndexIbGib_V1;
+        await persistTransformResult({ resTransform: res, space });
+        await metaspace.registerNewIbGib({ ibGib: indexIbGib });
+
+        if (logalot) {
+            console.log(`${lc} Created index IbGib: ${indexIbGib.ib} (I: 4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e)`);
+        }
+
+        return indexIbGib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a)`);
+        }
+    }
+}
+
+/**
+ * Retrieves authoritative B2tFSIndexIbGib_V1 from space.
+ */
+export async function getB2tFSIndexIbGib({
+    space,
+    vcsPath,
+}: {
+    space: IbGibSpaceAny;
+    vcsPath?: string;
+}): Promise<B2tFSIndexIbGib_V1 | undefined> {
+    const lc = `${lcFile}[${getB2tFSIndexIbGib.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b)`);
+        }
+
+        if (!vcsPath) {
+            return undefined;
+        }
+
+        const projPath = path.join(vcsPath, 'vcs_index_projection.json');
+        let indexAddr: string | undefined;
+        try {
+            const raw = await fs.readFile(projPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            indexAddr = parsed.indexAddr;
+        } catch {
+            return undefined;
+        }
+
+        if (!indexAddr) {
+            return undefined;
+        }
+
+        const ibgibs = await getIbGibsFromCache_fallbackToSpaces({
+            addrs: [indexAddr],
+            space,
+        });
+
+        const indexIbGib = ibgibs?.at(0) as B2tFSIndexIbGib_V1;
+        return indexIbGib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d)`);
+        }
+    }
+}
+
+/**
+ * Updates B2tFSIndexIbGib_V1 in space and updates local projection cache.
+ */
+export async function updateB2tFSIndexIbGib({
+    space,
+    metaspace,
+    indexIbGib,
+    dataToUpdate,
+    rel8nsToUpdate,
+    vcsPath,
+}: {
+    space: IbGibSpaceAny;
+    metaspace: MetaspaceService;
+    indexIbGib: B2tFSIndexIbGib_V1;
+    dataToUpdate?: Partial<B2tFSIndexData_V1>;
+    rel8nsToUpdate?: Partial<B2tFSIndexRel8ns_V1>;
+    vcsPath?: string;
+}): Promise<B2tFSIndexIbGib_V1> {
+    const lc = `${lcFile}[${updateB2tFSIndexIbGib.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e)`);
+        }
+
+        const mergedData: B2tFSIndexData_V1 = {
+            ...(indexIbGib.data || {
+                mySpaceId: space.data?.uuid || '',
+                activeSpaceId: '',
+                uuid: await getUUID(),
+            }),
+            ...dataToUpdate,
+        };
+
+        const mergedRel8ns: B2tFSIndexRel8ns_V1 = {
+            ...(indexIbGib.rel8ns || {}),
+            ...rel8nsToUpdate,
+        };
+
+        if (rel8nsToUpdate?.branch || indexIbGib.rel8ns?.branch) {
+            mergedRel8ns.branch = mergeBranchAddrs(
+                indexIbGib.rel8ns?.branch || [],
+                rel8nsToUpdate?.branch || [],
+            );
+        }
+
+        if (rel8nsToUpdate?.branch_tjp || indexIbGib.rel8ns?.branch_tjp) {
+            mergedRel8ns.branch_tjp = mergeBranchAddrs(
+                indexIbGib.rel8ns?.branch_tjp || [],
+                rel8nsToUpdate?.branch_tjp || [],
+            );
+        }
+
+        delete mergedRel8ns.past;
+
+        const res = await Factory_V1.firstGen({
+            parentIbGib: ROOT,
+            ib: indexIbGib.ib,
+            data: mergedData,
+            rel8ns: mergedRel8ns,
+        });
+
+        const newIndexIbGib = res.newIbGib as B2tFSIndexIbGib_V1;
+        await persistTransformResult({ resTransform: res, space });
+        await metaspace.registerNewIbGib({ ibGib: newIndexIbGib });
+
+        if (vcsPath) {
+            await writeVcsIndexProjection({ vcsPath, indexIbGib: newIndexIbGib });
+        }
+
+        return newIndexIbGib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a)`);
+        }
+    }
+}
+
+/**
+ * Writes read-only JSON projection cache of repository index.
+ */
+export async function writeVcsIndexProjection({
+    vcsPath,
+    indexIbGib,
+}: {
+    vcsPath: string;
+    indexIbGib: B2tFSIndexIbGib_V1;
+}): Promise<void> {
+    const lc = `${lcFile}[${writeVcsIndexProjection.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b)`);
+        }
+
+        await fs.mkdir(vcsPath, { recursive: true });
+
+        const indexAddr = getIbGibAddr({ ibGib: indexIbGib });
+        const projectionObj = {
+            _isReadOnlyProjection: true,
+            _comment: 'STRICTLY READ-ONLY PROJECTION GENERATED FROM B2TFSINDEXIBGIB_V1 IN LOCALSPACE',
+            indexAddr,
+            spaceId: indexIbGib.data?.mySpaceId,
+            activeBranch: indexIbGib.data?.activeBranch || 'main',
+            stagedCount: (indexIbGib.data?.staged_item || []).length,
+            stagedPaths: indexIbGib.data?.stagedPaths || {},
+            updatedAt: new Date().toISOString(),
+        };
+
+        const projFile = path.join(vcsPath, 'vcs_index_projection.json');
+        await fs.writeFile(projFile, JSON.stringify(projectionObj, null, 2), 'utf8');
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d)`);
+        }
+    }
+}

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

@@ -0,0 +1,66 @@
+/**
+ * @module index-types
+ * 
+ * Space-qualified address and B2tFS index type definitions.
+ */
+
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { IbGibData_V1, IbGibRel8ns_V1, IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+
+/**
+ * Format: v:1^spaceId:<spaceId>^<ibGibAddr>
+ */
+export type SpaceQualifiedIbGibAddr = string;
+
+export interface B2tFSStagedItemRecord {
+    itemAddr: string;
+    binAddr?: string;
+    fileHash?: string;
+    fsType: 'file' | 'folder';
+    stagedAt: string;
+}
+
+export interface B2tFSIndexData_V1 extends IbGibData_V1 {
+    /**
+     * Space UUID containing this index
+     */
+    mySpaceId: string;
+    /**
+     * Currently active branch space UUID
+     */
+    activeSpaceId: string;
+    /**
+     * Active branch name (e.g. 'main')
+     */
+    activeBranch?: string;
+    /**
+     * Space UUID from which this space forked
+     */
+    ancestorSpaceId?: string;
+    /**
+     * Soft references to branch TJPs: $@branch = [SpaceQualifiedIbGibAddr, ...]
+     */
+    '$@branch'?: SpaceQualifiedIbGibAddr[];
+    /**
+     * Staged paths lookup table
+     */
+    stagedPaths?: { [relPath: string]: B2tFSStagedItemRecord };
+    /**
+     * Staged candidate item addresses
+     */
+    staged_item?: IbGibAddr[];
+}
+
+export interface B2tFSIndexRel8ns_V1 extends IbGibRel8ns_V1 {
+    /**
+     * Local branch TJP address for this space
+     */
+    branch_tjp?: IbGibAddr[];
+    /**
+     * Active or registered branch IbGib addresses
+     */
+    branch?: IbGibAddr[];
+}
+
+export interface B2tFSIndexIbGib_V1 extends IbGib_V1<B2tFSIndexData_V1, B2tFSIndexRel8ns_V1> {
+}

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

@@ -0,0 +1,30 @@
+/**
+ * @module item-atom-helper
+ * 
+ * Helper functions enforcing canonical space-delimited `ib` atom formulas.
+ * 
+ * Formula: `[atom] [fsType] [saferName] [saferNameVersion] [nameHash]`
+ * Example: `b2tfs_item file index_mts v1 a745323851634de188beaebdcb85cbb9`
+ */
+
+export const B2TFS_ITEM_ATOM = 'b2tfs_item';
+export const B2TFS_ITEM_SAFER_NAME_VERSION_V1 = 'v1';
+
+export function getB2tFSItemSaferName(rawName: string): string {
+    if (!rawName) { return 'unnamed'; }
+    // Clean to alphanumeric and underscores/dashes/dots
+    const safe = rawName.replace(/[^a-zA-Z0-9_\-\.]/g, '_');
+    return safe.slice(0, 32);
+}
+
+/**
+ * Returns canonical `ib` metadata string for a B2tFS item.
+ * 
+ * @param fsType 'file' or 'folder'
+ * @param name raw file/folder name
+ * @param nameHash SHA-256 hash of name
+ */
+export function getB2tFSItemIb(fsType: 'file' | 'folder', name: string, nameHash: string): string {
+    const saferName = getB2tFSItemSaferName(name);
+    return `${B2TFS_ITEM_ATOM} ${fsType} ${saferName} ${B2TFS_ITEM_SAFER_NAME_VERSION_V1} ${nameHash}`;
+}

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

@@ -0,0 +1,239 @@
+/**
+ * @module item-helper
+ * 
+ * B2tFS Item Helper functions: graph diff generation, filesystem projection materialization,
+ * and two-pass transform application.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { MetaspaceService } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { putInSpace, persistTransformResult, getFromSpace } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+
+import { parseSpaceQualifiedIbGibAddr } from '../index/index-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+import {
+    B2tFSItemIbGib_V1, B2TFS_CHILD_ITEM_REL8N_NAME, BINARY_REL8N_NAME, B2tFSItemDiffInfo
+} from './item-types.mjs';
+
+const lcFile = `[item-helper]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+function getSpacesArray(metaAny: any): IbGibSpaceAny[] {
+    if (!metaAny || !metaAny.spaces) {
+        return [];
+    }
+    if (metaAny.spaces instanceof Map) {
+        return Array.from(metaAny.spaces.values());
+    }
+    if (Array.isArray(metaAny.spaces)) {
+        return metaAny.spaces;
+    }
+    if (typeof metaAny.spaces === 'object') {
+        return Object.values(metaAny.spaces);
+    }
+    return [];
+}
+
+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];
+        }
+    } catch {
+        // Suppress missing address error
+    }
+    return undefined;
+}
+
+/**
+ * Retrieves an ibgib node by address, searching space first, then falling back to metaspace spaces if available.
+ */
+export async function getIbGibWithMetaspaceFallback({
+    addr,
+    space,
+    metaspace,
+}: {
+    addr: string;
+    space: IbGibSpaceAny;
+    metaspace?: MetaspaceService;
+}): Promise<any> {
+    const parsedSq = parseSpaceQualifiedIbGibAddr(addr);
+    const targetAddr = parsedSq ? parsedSq.ibGibAddr : addr;
+
+    if (parsedSq && metaspace) {
+        try {
+            const spaceList = (await metaspace.getLocalUserSpaces({ lock: false })) || [];
+            let targetSpace = spaceList.find(s =>
+                s?.data?.uuid === parsedSq.spaceId ||
+                s?.data?.spaceId === parsedSq.spaceId ||
+                s?.data?.name === parsedSq.spaceId ||
+                s?.ib === parsedSq.spaceId ||
+                s?.data?.spaceSubPath === parsedSq.spaceId
+            );
+
+            if (!targetSpace) {
+                try {
+                    targetSpace = await metaspace.getLocalUserSpace({ localSpaceId: parsedSq.spaceId, lock: false });
+                } catch {
+                    // Suppress lookup error
+                }
+            }
+
+            if (targetSpace) {
+                const found = await fetchFromSpaceSilently(targetSpace, targetAddr);
+                if (found) {
+                    return found;
+                }
+            }
+        } catch {
+            // Suppress space lookup errors
+        }
+    }
+
+    const primaryFound = await fetchFromSpaceSilently(space, targetAddr);
+    if (primaryFound) {
+        return primaryFound;
+    }
+
+    if (metaspace) {
+        let spaceList: IbGibSpaceAny[] = [];
+        try {
+            spaceList = (await metaspace.getLocalUserSpaces({ lock: false })) || [];
+        } catch {
+            // Ignore bootstrap lookup error
+        }
+
+        const metaAny = metaspace as any;
+
+        // Try zero space if distinct
+        if (metaspace.zeroSpace && metaspace.zeroSpace !== space) {
+            const zeroFound = await fetchFromSpaceSilently(metaspace.zeroSpace, targetAddr);
+            if (zeroFound) {
+                return zeroFound;
+            }
+        }
+
+        if (metaAny.activeSpace && metaAny.activeSpace !== space && metaAny.activeSpace !== metaspace.zeroSpace) {
+            const activeFound = await fetchFromSpaceSilently(metaAny.activeSpace, targetAddr);
+            if (activeFound) {
+                return activeFound;
+            }
+        }
+
+        for (const s of spaceList) {
+            if (s && s !== space && s !== metaAny.activeSpace && s !== metaspace.zeroSpace) {
+                const sFound = await fetchFromSpaceSilently(s, targetAddr);
+                if (sFound) {
+                    return sFound;
+                }
+            }
+        }
+    }
+
+    return undefined;
+}
+
+/**
+ * Projects a B2tFS item graph back onto the physical filesystem directory.
+ */
+export async function writeB2tFSItemToFS(opts: {
+    item: B2tFSItemIbGib_V1;
+    destPath: string;
+    space: IbGibSpaceAny;
+    metaspace: MetaspaceService;
+}): Promise<void> {
+    const lc = `${lcFile}[${writeB2tFSItemToFS.name}]`;
+    const { item, destPath, space, metaspace } = opts;
+
+    if (!item || !item.data) {
+        throw new Error(`Invalid B2tFS item provided (E: 32a09c81b29e4d58)`);
+    }
+
+    const { fsType, name } = item.data;
+    const targetPath = path.join(destPath, name);
+
+    if (fsType === 'folder') {
+        await fs.mkdir(targetPath, { recursive: true });
+        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) {
+                await writeB2tFSItemToFS({
+                    item: childItem,
+                    destPath: targetPath,
+                    space,
+                    metaspace,
+                });
+            }
+        }
+    } else if (fsType === 'file') {
+        const binAddrs = item.rel8ns?.[BINARY_REL8N_NAME] || [];
+        const latestBinAddr = binAddrs.at(-1);
+
+        if (latestBinAddr) {
+            const binIbGib = await getIbGibWithMetaspaceFallback({
+                addr: latestBinAddr,
+                space,
+                metaspace,
+            });
+
+            if (binIbGib && binIbGib.data) {
+                let fileData: Uint8Array;
+                if (typeof binIbGib.data === 'string') {
+                    fileData = Buffer.from(binIbGib.data, 'base64');
+                } else if (binIbGib.data instanceof Uint8Array || Buffer.isBuffer(binIbGib.data)) {
+                    fileData = binIbGib.data as Uint8Array;
+                } else if (typeof binIbGib.data === 'object') {
+                    const vals = Object.values(binIbGib.data as object);
+                    fileData = new Uint8Array(vals);
+                } else {
+                    fileData = new Uint8Array(0);
+                }
+
+                await fs.writeFile(targetPath, fileData);
+            }
+        }
+    }
+}
+
+/**
+ * Executes two-pass application of diff transform results:
+ * 1. Persists all child and parent transform results to space.
+ * 2. Registers new IbGib pointers with metaspace to advance timeline tips.
+ */
+export async function applyB2tFSItemDiff(opts: {
+    diff: B2tFSItemDiffInfo;
+    space: IbGibSpaceAny;
+    metaspace: MetaspaceService;
+}): Promise<void> {
+    const lc = `${lcFile}[${applyB2tFSItemDiff.name}]`;
+    const { diff, space, metaspace } = opts;
+
+    if (diff.childDiffs && diff.childDiffs.length > 0) {
+        for (const childDiff of diff.childDiffs) {
+            await applyB2tFSItemDiff({ diff: childDiff, space, metaspace });
+        }
+    }
+
+    const results = diff.transformResults || [];
+    for (const tr of results) {
+        await persistTransformResult({ resTransform: tr, space });
+    }
+
+    for (const tr of results) {
+        if (tr.newIbGib) {
+            await metaspace.registerNewIbGib({ ibGib: tr.newIbGib });
+        }
+    }
+}