roam-research-mcp 2.4.0 → 2.13.0

package/build/shared/staged-batch.js

@@ -0,0 +1,144 @@
+/**
+ * Staged batch executor for Roam API.
+ *
+ * Solves the race condition where child blocks reference parent UIDs
+ * that are also being created in the same batch. By analyzing dependencies
+ * and executing in topological order (by level), we ensure parents exist
+ * before their children are created.
+ */
+import { batchActions } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Groups batch actions by dependency level.
+ *
+ * Level 0: Actions whose parent-uid is NOT created by another action in the batch
+ * Level 1: Actions whose parent-uid is created by a Level 0 action
+ * Level N: Actions whose parent-uid is created by a Level N-1 action
+ *
+ * @param actions - Flat array of batch actions
+ * @returns Array of action arrays, grouped by level
+ */
+export function groupActionsByDependencyLevel(actions) {
+    if (actions.length === 0)
+        return [];
+    // Build set of UIDs being created in this batch
+    const createdUids = new Set();
+    for (const action of actions) {
+        if (action.action === 'create-block' && action.block?.uid) {
+            createdUids.add(action.block.uid);
+        }
+    }
+    // Build dependency map: action index -> parent action index (or -1 if external parent)
+    const dependsOn = new Map();
+    const uidToIndex = new Map();
+    // First pass: map UIDs to action indices
+    for (let i = 0; i < actions.length; i++) {
+        const action = actions[i];
+        if (action.action === 'create-block' && action.block?.uid) {
+            uidToIndex.set(action.block.uid, i);
+        }
+    }
+    // Second pass: determine dependencies
+    for (let i = 0; i < actions.length; i++) {
+        const action = actions[i];
+        const parentUid = action.location?.['parent-uid'];
+        if (parentUid && createdUids.has(parentUid)) {
+            // This action depends on another action in the batch
+            const parentIndex = uidToIndex.get(parentUid);
+            if (parentIndex !== undefined) {
+                dependsOn.set(i, parentIndex);
+            }
+        }
+        else {
+            // External parent (already exists in Roam)
+            dependsOn.set(i, -1);
+        }
+    }
+    // Calculate levels using BFS-like approach
+    const levels = new Map(); // action index -> level
+    // Initialize: actions with external parents are level 0
+    for (let i = 0; i < actions.length; i++) {
+        if (dependsOn.get(i) === -1) {
+            levels.set(i, 0);
+        }
+    }
+    // Propagate levels
+    let changed = true;
+    let iterations = 0;
+    const maxIterations = actions.length + 1; // Prevent infinite loops
+    while (changed && iterations < maxIterations) {
+        changed = false;
+        iterations++;
+        for (let i = 0; i < actions.length; i++) {
+            if (levels.has(i))
+                continue; // Already assigned
+            const parentIndex = dependsOn.get(i);
+            if (parentIndex !== undefined && parentIndex !== -1 && levels.has(parentIndex)) {
+                levels.set(i, levels.get(parentIndex) + 1);
+                changed = true;
+            }
+        }
+    }
+    // Check for unassigned actions (circular dependencies or missing parents)
+    for (let i = 0; i < actions.length; i++) {
+        if (!levels.has(i)) {
+            // This shouldn't happen with valid input, but handle gracefully
+            // Assign to level 0 as fallback
+            levels.set(i, 0);
+        }
+    }
+    // Group by level
+    const maxLevel = Math.max(...levels.values());
+    const grouped = [];
+    for (let level = 0; level <= maxLevel; level++) {
+        grouped[level] = [];
+    }
+    for (let i = 0; i < actions.length; i++) {
+        const level = levels.get(i) ?? 0;
+        grouped[level].push(actions[i]);
+    }
+    // Filter out empty levels
+    return grouped.filter(level => level.length > 0);
+}
+/**
+ * Executes batch actions in staged order, ensuring parent blocks exist
+ * before their children are created.
+ *
+ * @param graph - Roam graph connection
+ * @param actions - Flat array of batch actions
+ * @param options - Execution options
+ * @returns Promise that resolves when all actions are complete
+ */
+export async function executeStagedBatch(graph, actions, options = {}) {
+    const { delayBetweenLevels = 100, context = 'batch operation' } = options;
+    if (actions.length === 0) {
+        return { success: true, levelsExecuted: 0, totalActions: 0 };
+    }
+    const actionsByLevel = groupActionsByDependencyLevel(actions);
+    for (let level = 0; level < actionsByLevel.length; level++) {
+        const levelActions = actionsByLevel[level];
+        if (levelActions.length === 0)
+            continue;
+        try {
+            const result = await batchActions(graph, {
+                action: 'batch-actions',
+                actions: levelActions
+            });
+            if (!result) {
+                throw new McpError(ErrorCode.InternalError, `Failed to execute ${context} at level ${level} - no result returned`);
+            }
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to execute ${context} at level ${level}: ${error.message}`);
+        }
+        // Delay between levels to ensure parent blocks are committed
+        if (level < actionsByLevel.length - 1) {
+            await new Promise(resolve => setTimeout(resolve, delayBetweenLevels));
+        }
+    }
+    return {
+        success: true,
+        levelsExecuted: actionsByLevel.length,
+        totalActions: actions.length
+    };
+}

package/build/tools/helpers/batch-utils.js

@@ -0,0 +1,57 @@
+/**
+ * Shared utilities for batch operations with consistent error handling.
+ */
+import { batchActions } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Execute batch actions with consistent error handling.
+ * Wraps batchActions call in try-catch and throws McpError on failure.
+ *
+ * @param graph - The Roam graph instance
+ * @param actions - Array of batch actions to execute
+ * @param errorContext - Description of what operation failed (e.g., "create memory block")
+ * @returns The result from batchActions
+ * @throws McpError if the operation fails
+ */
+export async function executeBatch(graph, actions, errorContext) {
+    try {
+        const result = await batchActions(graph, {
+            action: 'batch-actions',
+            actions
+        });
+        if (!result) {
+            throw new McpError(ErrorCode.InternalError, `Failed to ${errorContext}`);
+        }
+        return result;
+    }
+    catch (error) {
+        if (error instanceof McpError) {
+            throw error;
+        }
+        throw new McpError(ErrorCode.InternalError, `Failed to ${errorContext}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Execute batch actions without throwing on failure (for non-critical operations).
+ * Returns null on failure instead of throwing.
+ *
+ * @param graph - The Roam graph instance
+ * @param actions - Array of batch actions to execute
+ * @param errorContext - Description for logging on failure
+ * @returns The result from batchActions, or null on failure
+ */
+export async function executeBatchSafe(graph, actions, errorContext) {
+    try {
+        const result = await batchActions(graph, {
+            action: 'batch-actions',
+            actions
+        });
+        return result || null;
+    }
+    catch (error) {
+        if (errorContext) {
+            console.error(`Failed to ${errorContext}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return null;
+    }
+}

package/build/tools/helpers/page-resolution.js

@@ -0,0 +1,136 @@
+/**
+ * Shared utilities for page UID resolution with caching and case-insensitive matching.
+ */
+import { q, createPage } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { formatRoamDate } from '../../utils/helpers.js';
+import { pageUidCache } from '../../cache/page-uid-cache.js';
+import { capitalizeWords } from './text.js';
+/**
+ * Find a page UID by title with case variation matching and caching.
+ * Tries: original, capitalized words, lowercase.
+ * @returns The page UID or null if not found
+ */
+export async function getPageUid(graph, title) {
+    if (!title) {
+        return null;
+    }
+    const variations = [
+        title,
+        capitalizeWords(title),
+        title.toLowerCase()
+    ];
+    // Check cache first for any variation
+    for (const variation of variations) {
+        const cachedUid = pageUidCache.get(variation);
+        if (cachedUid) {
+            return cachedUid;
+        }
+    }
+    // Query database with OR clause for all variations
+    const orClause = variations.map(v => `[?e :node/title "${v}"]`).join(' ');
+    const searchQuery = `[:find ?uid .
+                      :where [?e :block/uid ?uid]
+                             (or ${orClause})]`;
+    const result = await q(graph, searchQuery, []);
+    const uid = (result === null || result === undefined) ? null : String(result);
+    if (uid) {
+        pageUidCache.set(title, uid);
+    }
+    return uid;
+}
+/**
+ * Get or create today's daily page.
+ * @returns The page UID
+ */
+export async function getOrCreateTodayPage(graph) {
+    const dateStr = formatRoamDate(new Date());
+    // Check cache first
+    const cachedUid = pageUidCache.get(dateStr);
+    if (cachedUid) {
+        return cachedUid;
+    }
+    // Try to find today's page
+    const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+    const findResults = await q(graph, findQuery, [dateStr]);
+    if (findResults && findResults.length > 0) {
+        const uid = findResults[0][0];
+        pageUidCache.set(dateStr, uid);
+        return uid;
+    }
+    // Create today's page
+    await createPage(graph, {
+        action: 'create-page',
+        page: { title: dateStr }
+    });
+    // Fetch the newly created page UID
+    const results = await q(graph, findQuery, [dateStr]);
+    if (!results || results.length === 0) {
+        throw new McpError(ErrorCode.InternalError, "Could not find created today's page");
+    }
+    const uid = results[0][0];
+    pageUidCache.onPageCreated(dateStr, uid);
+    return uid;
+}
+/**
+ * Find or create a page by title or UID with retries and caching.
+ * Tries case variations, checks if input is a UID, creates page if not found.
+ * @returns The page UID
+ */
+export async function findOrCreatePage(graph, titleOrUid, options = {}) {
+    const { maxRetries = 3, delayMs = 500 } = options;
+    const variations = [
+        titleOrUid,
+        capitalizeWords(titleOrUid),
+        titleOrUid.toLowerCase()
+    ];
+    // Check cache first for any variation
+    for (const variation of variations) {
+        const cachedUid = pageUidCache.get(variation);
+        if (cachedUid) {
+            return cachedUid;
+        }
+    }
+    const titleQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+    for (let retry = 0; retry < maxRetries; retry++) {
+        // Try each case variation
+        for (const variation of variations) {
+            const findResults = await q(graph, titleQuery, [variation]);
+            if (findResults && findResults.length > 0) {
+                const uid = findResults[0][0];
+                pageUidCache.set(titleOrUid, uid);
+                return uid;
+            }
+        }
+        // If not found as title, try as UID
+        const uidQuery = `[:find ?uid
+                      :where [?e :block/uid "${titleOrUid}"]
+                             [?e :block/uid ?uid]]`;
+        const uidResult = await q(graph, uidQuery, []);
+        if (uidResult && uidResult.length > 0) {
+            return uidResult[0][0];
+        }
+        // If still not found and this is the first retry, try to create the page
+        if (retry === 0) {
+            await createPage(graph, {
+                action: 'create-page',
+                page: { title: titleOrUid }
+            });
+            await new Promise(resolve => setTimeout(resolve, delayMs));
+            continue;
+        }
+        if (retry < maxRetries - 1) {
+            await new Promise(resolve => setTimeout(resolve, delayMs));
+        }
+    }
+    // One more attempt to find after creation attempts
+    for (const variation of variations) {
+        const findResults = await q(graph, titleQuery, [variation]);
+        if (findResults && findResults.length > 0) {
+            const uid = findResults[0][0];
+            pageUidCache.onPageCreated(titleOrUid, uid);
+            return uid;
+        }
+    }
+    throw new McpError(ErrorCode.InvalidRequest, `Failed to find or create page "${titleOrUid}" after multiple attempts`);
+}

package/build/tools/helpers/refs.js

@@ -64,3 +64,71 @@ export async function resolveRefs(graph, text, depth = 0, maxDepth = 4, seen = n
         return refMap.get(uid) ?? match;
     });
 }
+/**
+ * Recursively resolves block references for a list of RoamBlocks.
+ * Attaches referenced blocks to the `refs` property of the referencing block.
+ *
+ * @param graph - Roam graph connection
+ * @param blocksToScan - List of blocks to scan for references
+ * @param remainingDepth - Maximum depth to resolve nested refs
+ */
+export async function resolveBlockRefs(graph, blocksToScan, remainingDepth = 2) {
+    if (remainingDepth <= 0 || blocksToScan.length === 0) {
+        return;
+    }
+    const refMap = {}; // uid -> list of blocks referencing it
+    const allRefUids = new Set();
+    for (const block of blocksToScan) {
+        // Skip blocks without valid string content
+        if (typeof block.string !== 'string') {
+            continue;
+        }
+        // Reset lastIndex for REF_PATTERN reuse if using exec, or use matchAll
+        // matchAll is safer with global regex state
+        const matches = block.string.matchAll(REF_PATTERN);
+        for (const match of matches) {
+            const refUid = match[1];
+            if (!refMap[refUid]) {
+                refMap[refUid] = [];
+            }
+            refMap[refUid].push(block);
+            allRefUids.add(refUid);
+        }
+    }
+    if (allRefUids.size === 0) {
+        return;
+    }
+    const uidsToFetch = Array.from(allRefUids);
+    // Fetch referenced blocks content
+    const refsQuery = `[:find ?uid ?string ?heading
+                      :in $ [?uid ...]
+                      :where [?b :block/uid ?uid]
+                             [?b :block/string ?string]
+                             [(get-else $ ?b :block/heading 0) ?heading]]`;
+    const results = await q(graph, refsQuery, [uidsToFetch]);
+    const fetchedBlocks = [];
+    for (const [uid, string, heading] of results) {
+        const newBlock = {
+            uid,
+            string,
+            order: 0,
+            heading: heading || undefined,
+            children: [],
+            refs: []
+        };
+        fetchedBlocks.push(newBlock);
+        // Attach to parents
+        if (refMap[uid]) {
+            for (const parentBlock of refMap[uid]) {
+                if (!parentBlock.refs)
+                    parentBlock.refs = [];
+                // Avoid duplicates
+                if (!parentBlock.refs.some(r => r.uid === uid)) {
+                    parentBlock.refs.push(newBlock);
+                }
+            }
+        }
+    }
+    // Recurse for the next level of references
+    await resolveBlockRefs(graph, fetchedBlocks, remainingDepth - 1);
+}

package/build/tools/operations/batch.js

@@ -1,7 +1,8 @@
 import { batchActions as roamBatchActions } from '@roam-research/roam-api-sdk';
-import { generateBlockUid } from '../../markdown-utils.js';
+import { generateBlockUid, parseMarkdownHeadingLevel } from '../../markdown-utils.js';
 import { validateBatchActions, formatValidationErrors } from '../../shared/validation.js';
 import { isRateLimitError, createRateLimitError } from '../../shared/errors.js';
+import { ensurePagesExist } from '../../shared/page-validator.js';
 // Regex to match UID placeholders like {{uid:parent1}}, {{uid:section-a}}, etc.
 const UID_PLACEHOLDER_REGEX = /\{\{uid:([^}]+)\}\}/g;
 const DEFAULT_RATE_LIMIT_CONFIG = {
@@ -119,6 +120,35 @@ export class BatchOperations {
                 actions_attempted: 0
             };
         }
+        // Step 0.5: Validate parent pages exist (auto-creates daily pages)
+        // This uses batched queries and caching to minimize API calls
+        try {
+            const pageValidation = await ensurePagesExist(this.graph, actions, {
+                maxRetries: this.rateLimitConfig.maxRetries,
+                initialDelayMs: this.rateLimitConfig.initialDelayMs,
+                maxDelayMs: this.rateLimitConfig.maxDelayMs,
+                backoffMultiplier: this.rateLimitConfig.backoffMultiplier
+            });
+            if (pageValidation.created > 0) {
+                console.log(`[batch] Auto-created ${pageValidation.created} daily page(s), checked ${pageValidation.checked}, cached ${pageValidation.cached}`);
+            }
+        }
+        catch (error) {
+            // Page validation failed - return structured error
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                error: {
+                    code: 'PAGE_NOT_FOUND',
+                    message: errorMessage,
+                    recovery: {
+                        suggestion: 'Create the missing page(s) first with roam_create_page, or verify the parent-uid is correct'
+                    }
+                },
+                validation_passed: true, // Syntax validation passed, page validation failed
+                actions_attempted: 0
+            };
+        }
         // Step 1: Generate UIDs for all placeholders
         const uidMap = this.generateUidMap(actions);
         const hasPlaceholders = Object.keys(uidMap).length > 0;
@@ -137,12 +167,20 @@ export class BatchOperations {
                 };
             }
             const block = {};
-            if (rest.string)
-                block.string = rest.string;
+            if (rest.string) {
+                // Parse markdown heading syntax (e.g., "### Description" -> heading: 3, string: "Description")
+                const { heading_level, content } = parseMarkdownHeadingLevel(rest.string);
+                block.string = heading_level > 0 ? content : rest.string;
+                // Use parsed heading level if not explicitly overridden
+                if (heading_level > 0 && rest.heading === undefined) {
+                    block.heading = heading_level;
+                }
+            }
             if (rest.uid)
                 block.uid = rest.uid;
             if (rest.open !== undefined)
                 block.open = rest.open;
+            // Explicit heading parameter takes precedence over markdown syntax
             if (rest.heading !== undefined && rest.heading !== null && rest.heading !== 0) {
                 block.heading = rest.heading;
             }
@@ -171,6 +209,40 @@ export class BatchOperations {
         catch (error) {
             // FAILURE: Do NOT return uid_map - blocks don't exist
             const errorMessage = error instanceof Error ? error.message : String(error);
+            // Check for parent entity error - retry once after delay (Roam eventual consistency)
+            if (errorMessage.includes("Parent entity doesn't exist")) {
+                console.log('[batch] Parent entity not found, retrying after 400ms...');
+                await sleep(400);
+                try {
+                    await this.executeWithRetry(batchActions);
+                    // SUCCESS on retry
+                    const result = {
+                        success: true,
+                        validation_passed: true,
+                        actions_attempted: batchActions.length
+                    };
+                    if (hasPlaceholders) {
+                        result.uid_map = uidMap;
+                    }
+                    return result;
+                }
+                catch (retryError) {
+                    // Still failed after retry
+                    const retryErrorMessage = retryError instanceof Error ? retryError.message : String(retryError);
+                    return {
+                        success: false,
+                        error: {
+                            code: 'PARENT_ENTITY_NOT_FOUND',
+                            message: `${retryErrorMessage} (retried once after 400ms delay)`,
+                            recovery: {
+                                suggestion: 'Verify the parent block/page UID exists and is spelled correctly'
+                            }
+                        },
+                        validation_passed: true,
+                        actions_attempted: batchActions.length
+                    };
+                }
+            }
             // Check if it's a rate limit error
             if (isRateLimitError(error) || error.isRateLimit) {
                 return {

package/build/tools/operations/block-retrieval.js

@@ -1,5 +1,6 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { resolveBlockRefs } from '../helpers/refs.js';
 export class BlockRetrievalOperations {
     constructor(graph) {
         this.graph = graph;
@@ -53,19 +54,29 @@ export class BlockRetrievalOperations {
                                       [?b :block/string ?string]
                                       [?b :block/order ?order]
                                       [(get-else $ ?b :block/heading 0) ?heading]]`;
-            const rootBlockResult = await q(this.graph, rootBlockQuery, [block_uid]);
-            if (!rootBlockResult) {
+            const rootBlockResults = await q(this.graph, rootBlockQuery, [block_uid]);
+            if (!rootBlockResults || rootBlockResults.length === 0) {
                 return null;
             }
-            const [rootString, rootOrder, rootHeading] = rootBlockResult;
+            const [rootString, rootOrder, rootHeading] = rootBlockResults[0];
             const childrenMap = await fetchChildren([block_uid], 0);
-            return {
+            const rootBlock = {
                 uid: block_uid,
                 string: rootString,
                 order: rootOrder,
                 heading: rootHeading || undefined,
                 children: childrenMap[block_uid] || [],
             };
+            // Gather all blocks in the tree to scan for references
+            const allBlocks = [];
+            const traverse = (b) => {
+                allBlocks.push(b);
+                b.children.forEach(traverse);
+            };
+            traverse(rootBlock);
+            // Resolve references (max depth 2)
+            await resolveBlockRefs(this.graph, allBlocks, 2);
+            return rootBlock;
         }
         catch (error) {
             throw new McpError(ErrorCode.InternalError, `Failed to fetch block with children: ${error instanceof Error ? error.message : String(error)}`);

package/build/tools/operations/block-retrieval.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BlockRetrievalOperations } from './block-retrieval.js';
+// Mock roam-api-sdk
+vi.mock('@roam-research/roam-api-sdk', () => ({
+    q: vi.fn(),
+    Graph: vi.fn(),
+}));
+import { q } from '@roam-research/roam-api-sdk';
+describe('BlockRetrievalOperations', () => {
+    let ops;
+    let mockGraph;
+    let qMock;
+    beforeEach(() => {
+        mockGraph = {};
+        ops = new BlockRetrievalOperations(mockGraph);
+        qMock = q;
+        vi.clearAllMocks();
+    });
+    it('fetches a block with recursive reference resolution', async () => {
+        // ref UIDs must be 9 chars to match REF_PATTERN
+        const ref1Uid = 'ref1AAAAA';
+        const ref2Uid = 'ref2BBBBB';
+        // 1. Root block query: [:find ?string ?order ?heading ...]
+        qMock.mockResolvedValueOnce([[`Root Block with Ref ((${ref1Uid}))`, 0, 0]]);
+        // 2. Children query: [:find ?parentUid ?childUid ?childString ?childOrder ?childHeading ...]
+        qMock.mockResolvedValueOnce([]);
+        // 3. resolveBlockRefs query for ref1: [:find ?uid ?string ?heading ...]
+        qMock.mockResolvedValueOnce([[ref1Uid, `Ref 1 content with ((${ref2Uid}))`, 0]]);
+        // 4. resolveBlockRefs query for ref2 (depth 2)
+        qMock.mockResolvedValueOnce([[ref2Uid, 'Ref 2 content', 0]]);
+        const result = await ops.fetchBlockWithChildren('root-uid');
+        expect(result).toBeDefined();
+        expect(result?.uid).toBe('root-uid');
+        expect(result?.string).toBe(`Root Block with Ref ((${ref1Uid}))`);
+        expect(result?.refs).toBeDefined();
+        expect(result?.refs).toHaveLength(1);
+        const ref1 = result?.refs?.[0];
+        expect(ref1?.uid).toBe(ref1Uid);
+        expect(ref1?.string).toBe(`Ref 1 content with ((${ref2Uid}))`);
+        expect(ref1?.refs).toBeDefined();
+        expect(ref1?.refs).toHaveLength(1);
+        const ref2 = ref1?.refs?.[0];
+        expect(ref2?.uid).toBe(ref2Uid);
+        expect(ref2?.string).toBe('Ref 2 content');
+        // ref2 should have empty refs as it has no refs in string
+        expect(ref2?.refs).toEqual([]);
+    });
+    it('handles multiple references in same block', async () => {
+        const refAUid = 'refAAAAAA';
+        const refBUid = 'refBBBBBB';
+        // 1. Root block
+        qMock.mockResolvedValueOnce([[`Root ((${refAUid})) and ((${refBUid}))`, 0, 0]]);
+        // 2. Children
+        qMock.mockResolvedValueOnce([]);
+        // 3. resolveBlockRefs query for refA and refB
+        qMock.mockResolvedValueOnce([
+            [refAUid, 'Content A', 0],
+            [refBUid, 'Content B', 0]
+        ]);
+        // No more queries - Content A and B have no refs
+        const result = await ops.fetchBlockWithChildren('root-uid');
+        expect(result?.refs).toHaveLength(2);
+        const uids = result?.refs?.map(r => r.uid).sort();
+        expect(uids).toEqual([refAUid, refBUid].sort());
+    });
+    it('handles shared references in tree', async () => {
+        const sharedUid = 'sharedUID';
+        // 1. Root block
+        qMock.mockResolvedValueOnce([['Root', 0, 0]]);
+        // 2. Children query: Child1 and Child2 both reference 'shared'
+        qMock.mockResolvedValueOnce([
+            ['root-uid', 'child1uid', `Child 1 ((${sharedUid}))`, 0, 0],
+            ['root-uid', 'child2uid', `Child 2 ((${sharedUid}))`, 1, 0]
+        ]);
+        // 3. Children of Child1 and Child2 (empty - depth limit or no children)
+        qMock.mockResolvedValueOnce([]);
+        // 4. resolveBlockRefs query for 'shared' - fetched once, attached to both
+        qMock.mockResolvedValueOnce([[sharedUid, 'Shared Content', 0]]);
+        const result = await ops.fetchBlockWithChildren('root-uid');
+        const child1 = result?.children.find(c => c.uid === 'child1uid');
+        const child2 = result?.children.find(c => c.uid === 'child2uid');
+        expect(child1?.refs).toHaveLength(1);
+        expect(child1?.refs[0].uid).toBe(sharedUid);
+        expect(child2?.refs).toHaveLength(1);
+        expect(child2?.refs[0].uid).toBe(sharedUid);
+    });
+});