unity-open-mcp 0.6.1 → 0.8.2

package/dist/offline/api.js

@@ -18,7 +18,7 @@ import { cleanScalar, findGUIDs, readGUIDField } from "./primitives.js";
 import { parseAsset } from "./parse.js";
 import { displayFieldName } from "./names.js";
 import { buildAssetModel, buildJsonAssetModel, runYamlIntegrityChecks, } from "./model.js";
-import { buildGUIDIndex, buildScriptIndex, buildScriptIndexForQuery, collectFiles, resolveGUIDPaths, safeReadMetaGUID, scriptGUIDs, walkFiles, walkMeta, } from "./index-builders.js";
+import { buildGUIDIndex, buildScriptIndexForQuery, buildGuidAndScriptIndex, collectFiles, collectMetaTriples, parallelMap, resolveGUIDPaths, safeReadMetaGUID, scriptGUIDs, walkFiles, } from "./index-builders.js";
 import { toAssetPath, relativeDir } from "./paths.js";
 import { OVERRIDE_LABEL_HELPERS } from "./references.js";
 import { setLabelHelpers } from "./overrides.js";
@@ -75,12 +75,14 @@ export async function readAssetOffline(assetPath, opts) {
     parsed.path = assetPath;
     parsed.kind = kind;
     parsed.guid = guid;
+    // M31-optimizations Plan 2 / H5 — build both the script (.cs subset) and
+    // field-GUID indices in a SINGLE meta walk by unioning the wanted sets.
+    // Previously this was buildScriptIndex (which itself walks the meta tree
+    // via buildGUIDIndex) followed by another buildGUIDIndex walk — every cold
+    // read_asset paid two back-to-back walks of the same tree.
     const wantedScripts = scriptGUIDs(parsed);
-    const scriptIndex = await buildScriptIndex(opts.projectRoot, wantedScripts);
     const wantedGUIDs = collectFieldGUIDs(parsed);
-    const guidIndex = await buildGUIDIndex(opts.projectRoot, wantedGUIDs);
-    for (const [g, p] of scriptIndex)
-        guidIndex.set(g, p);
+    const { guidIndex, scriptIndex } = await buildGuidAndScriptIndex(opts.projectRoot, wantedGUIDs, wantedScripts);
     const integrity = runYamlIntegrityChecks(parsed, guidIndex);
     return {
         model: { ...buildAssetModel(parsed, scriptIndex, guidIndex, opts.fieldLimit), ...(integrity ? { integrity } : {}) },
@@ -109,8 +111,23 @@ export async function searchAssetsOffline(opts) {
     const guidQuery = (opts.guid ?? "").trim().toLowerCase();
     const typeFilter = opts.type ? parseKindSet(opts.type) : null;
     const folder = opts.folder ?? "Assets";
-    const maxResults = opts.maxResults ?? 50;
+    // M1 — `0` (and any negative) is the documented "unlimited (for paging)"
+    // sentinel forwarded by compressible-router.ts when the caller supplies a
+    // page_size; `??` does not treat 0 as absent, so the previous
+    // `opts.maxResults ?? 50` made `0` a hard cap and the loop broke on the
+    // first file (`0 >= 0`). Treat `<= 0` as unlimited, mirroring
+    // dependenciesOffline (`maxResults > 0 && totalCount > maxResults`) and
+    // renderSearchSummary (`matchLimit > 0 ? ... : all.length`).
+    const maxResults = (typeof opts.maxResults === "number" && opts.maxResults > 0)
+        ? opts.maxResults
+        : Number.POSITIVE_INFINITY;
     const searchDir = join(opts.projectRoot, folder);
+    // M31-optimizations Plan 2 / L2 — when a component query is present, build
+    // the script-name → guid → path index from the same single walk that would
+    // already populate the guid + script indices. Previously this was a
+    // separate buildScriptIndexForQuery walk. The guid-query path still uses
+    // resolveGUIDPaths (its early-exit-on-first-match optimization is worth
+    // more than collapsing its walk into this one).
     const scriptIndex = componentQuery
         ? await buildScriptIndexForQuery(opts.projectRoot, componentQuery)
         : new Map();
@@ -188,8 +205,16 @@ function checkMatch(parsed, scriptIndex, guidIndex, assetPath, kind, guid, crite
             reasons.push("guid");
     }
     const hierarchy = buildHierarchy(parsed);
+    // M31-optimizations Plan 3 / L3 — flatten the hierarchy exactly once per
+    // asset and reuse the flattened list for both the name-query and component-
+    // query scans. Previously checkMatch called flattenHierarchy(hierarchy)
+    // twice (once per query branch), each producing a fresh flattened array.
+    // componentsFor now also consults the per-asset goID→components cache built
+    // during buildHierarchy above, so each node's component set is an O(1)
+    // Map lookup instead of a linear scan over all objects.
+    const flatNodes = flattenHierarchy(hierarchy);
     if (nameQuery) {
-        for (const node of flattenHierarchy(hierarchy)) {
+        for (const node of flatNodes) {
             if (node.gameObject.name.toLowerCase().includes(nameQuery)) {
                 const comps = componentsFor(parsed, node.gameObject.id, scriptIndex);
                 objects.push({ path: node.path, components: comps.map((c) => c.name) });
@@ -200,7 +225,7 @@ function checkMatch(parsed, scriptIndex, guidIndex, assetPath, kind, guid, crite
     }
     if (componentQuery) {
         let componentMatch = false;
-        for (const node of flattenHierarchy(hierarchy)) {
+        for (const node of flatNodes) {
             const comps = componentsFor(parsed, node.gameObject.id, scriptIndex);
             const matching = comps.filter((c) => c.name.toLowerCase().includes(componentQuery) ||
                 (c.scriptPath && c.scriptPath.toLowerCase().includes(componentQuery)));
@@ -325,7 +350,15 @@ export async function listAssetsOffline(opts) {
 const REFERENCEABLE_EXTENSIONS = OFFLINE_PARSEABLE_EXTENSIONS;
 export async function findReferencesOffline(opts) {
     const detail = (opts.detail ?? "normal");
-    const maxResults = opts.maxResults ?? 100;
+    // M2 — `0` (and any negative) is the documented "unlimited (for paging)"
+    // sentinel forwarded by tool-router.ts when the caller supplies a
+    // page_size; `??` does not treat 0 as absent, so the previous
+    // `opts.maxResults ?? 100` made `0` a hard cap and `displayHits.slice(0,0)`
+    // returned an empty list (page_size:1 → referencedBy:[]). Treat `<= 0` as
+    // unlimited, mirroring dependenciesOffline and searchAssetsOffline.
+    const maxResults = (typeof opts.maxResults === "number" && opts.maxResults > 0)
+        ? opts.maxResults
+        : Number.POSITIVE_INFINITY;
     const maxPerFile = opts.maxPerFile ?? 5;
     const patternThreshold = opts.patternThreshold ?? 0;
     // Resolve target GUID + path.
@@ -369,7 +402,8 @@ export async function findReferencesOffline(opts) {
         catch {
             continue;
         }
-        // Fast filter: skip files that don't mention the GUID at all.
+        // Fast filter: skip files that don't mention the GUID at all. This stays
+        // on the joined content (the cheap fast-reject before any per-line work).
         if (!content.includes(targetGuid))
             continue;
         const assetPath = toAssetPath(opts.projectRoot, absPath);
@@ -386,7 +420,14 @@ export async function findReferencesOffline(opts) {
             folder,
         };
         if (detail === "verbose") {
-            entry.locations = extractReferenceLocations(content, targetGuid, maxPerFile);
+            // M31-optimizations Plan 2 / L4 — split content into lines ONCE and
+            // pass the line array downstream. Previously extractReferenceLocations
+            // re-split the same content it was given; now the single split is
+            // visible at the call site and the per-line scan reuses it. The
+            // substring pre-filter above already ran on the joined content (the
+            // fast-reject), so this is the ONLY split for the verbose path.
+            const lines = content.split("\n");
+            entry.locations = extractReferenceLocationsFromLines(lines, targetGuid, maxPerFile);
         }
         hits.push(entry);
     }
@@ -444,9 +485,15 @@ export async function findReferencesOffline(opts) {
         truncated,
     };
 }
-function extractReferenceLocations(content, targetGuid, maxPerFile) {
+/**
+ * M31-optimizations Plan 2 / L4 — extract field-location labels for a target
+ * GUID from a pre-split line array. The caller ({@link findReferencesOffline})
+ * splits the content once and passes the lines here so the verbose path does
+ * not re-split the same content downstream. The per-line scan iterates the
+ * array directly.
+ */
+function extractReferenceLocationsFromLines(lines, targetGuid, maxPerFile) {
     const locations = [];
-    const lines = content.split("\n");
     for (let i = 0; i < lines.length; i++) {
         if (!lines[i].includes(targetGuid))
             continue;
@@ -528,22 +575,57 @@ export async function dependenciesOffline(opts) {
             forwardSkipped = err instanceof Error ? err.message : String(err);
         }
     }
-    // ---- Reverse edges ---- (reuse the findReferencesOffline machinery).
-    const refResult = await findReferencesOffline({
-        assetPath: targetPath || undefined,
-        guid: targetGuid,
-        detail: "normal",
-        projectRoot: opts.projectRoot,
-    });
-    const reverseEdges = refResult.referencedBy.map((e) => ({
-        assetPath: e.assetPath,
-        guid: e.guid ?? "",
-        kind: e.kind,
-    }));
+    // ---- Reverse edges ----
+    // M31-optimizations Plan 2 / H4 + M5 — build the project-wide reverse-edge
+    // graph ONCE per dependenciesOffline call when impact is requested.
+    // Previously the single reverse-edge lookup called findReferencesOffline
+    // (one full project walk), and computeTransitiveImpact called
+    // findReferencesOffline per BFS frontier node — re-walking the whole
+    // project K times for a closure of size K (O(closure × project size)). The
+    // graph is a Map<guid, ReverseEdge[]> built in a single pass over
+    // parseable assets; both the direct reverse-edge lookup and the impact BFS
+    // consult it via pure Map.get, so no per-node project walk remains. The
+    // graph is a local variable (per-call only; root AGENTS.md forbids disk
+    // caches).
+    //
+    // When impact is NOT requested, skip the graph build — the direct reverse-
+    // edge lookup via findReferencesOffline is cheaper than building the whole
+    // project graph (it early-exits the candidate scan as soon as it has read
+    // each file once, and produces the verbose-fold fields dependenciesOffline
+    // does not need but finds cheaper to inherit than to re-derive).
+    const reverseEdgeGraph = includeImpact
+        ? await buildReverseEdgeGraph(opts.projectRoot)
+        : null;
+    const reverseEdges = reverseEdgeGraph
+        ? findReferencesFromGraph(reverseEdgeGraph.graph, targetGuid, targetPath)
+        : (await findReferencesOffline({
+            assetPath: targetPath || undefined,
+            guid: targetGuid,
+            detail: "normal",
+            // M5 — fetch the FULL reverse-edge set and let the outer cap below be
+            // the single source of truth for truncation. Previously this call
+            // omitted maxResults, so findReferencesOffline applied its inner
+            // default of 100, pre-truncated `referencedBy`, and discarded its own
+            // `truncated` count. `reverseEdges` was then silently capped at 100,
+            // `totalCount` was computed from the already-truncated list, and the
+            // outer `totalCount > maxResults` check could never fire — so an agent
+            // using `dependencies` as a pre-delete impact check got a list that
+            // claimed to be complete (`truncated: 0`) while omitting the tail.
+            // `0` is the documented "unlimited (for paging)" sentinel both layers
+            // already agree on (M2 normalized findReferencesOffline to treat `<= 0`
+            // as unlimited). The outer cap at lines below then slices + reports
+            // `truncated` correctly against the true count.
+            maxResults: 0,
+            projectRoot: opts.projectRoot,
+        })).referencedBy.map((e) => ({
+            assetPath: e.assetPath,
+            guid: e.guid ?? "",
+            kind: e.kind,
+        }));
     // ---- Transitive impact (optional) ----
     let impact;
-    if (includeImpact) {
-        impact = await computeTransitiveImpact(targetGuid, targetPath, opts.projectRoot, maxImpactDepth);
+    if (includeImpact && reverseEdgeGraph) {
+        impact = await computeTransitiveImpactFromGraph(targetGuid, targetPath, reverseEdgeGraph.graph, reverseEdgeGraph.pathToGuid, maxImpactDepth);
     }
     // ---- Apply detail + caps ----
     const displayForward = detail === "summary" ? [] : forwardEdges;
@@ -573,6 +655,7 @@ export async function dependenciesOffline(opts) {
         detail,
         truncated,
         ...(forwardSkipped ? { forwardSkipped } : {}),
+        // Inline tag is load-bearing — see the note on DependenciesOfflineResult._source.
         _source: "offline",
     };
 }
@@ -588,35 +671,55 @@ function emptyDependencies(path, guid, detail) {
         reverseCount: 0,
         detail,
         truncated: 0,
+        // Inline tag is load-bearing — see the note on DependenciesOfflineResult._source.
         _source: "offline",
     };
 }
 /** Collect the forward edges declared by a single asset. */
 function collectForwardEdges(parsed) {
-    const edges = [];
+    // M31-optimizations Plan 3 / H6 — single pass over parsed.objects.
+    // Previously this ran three separate `for (const obj of parsed.objects)`
+    // loops (one per edge kind), each re-scanning all objects (+ all lines for
+    // the pptr kind) — O(3 × objects × lines). The single pass below branches
+    // on obj.type and on whether the line declares an m_Script / m_SourcePrefab
+    // / generic guid: field, accumulating into three per-kind buffers that are
+    // concatenated at the end. The concatenation order (prefab_source, then
+    // script, then pptr) preserves the exact edge ordering the previous
+    // three-pass implementation produced, so the forwardDependencies output
+    // stays byte-identical. The shared `seen` set dedupes within each kind
+    // (a guid can appear as both a prefab_source and a pptr edge — different
+    // seen keys, same as before).
+    const prefabEdges = [];
+    const scriptEdges = [];
+    const pptrEdges = [];
     const seen = new Set();
-    // 1. PrefabInstance.m_SourcePrefab — the base-prefab edge of a variant.
     for (const obj of parsed.objects) {
-        if (obj.type !== "PrefabInstance")
-            continue;
-        const sourceGuid = readGUIDField(obj.lines, "m_SourcePrefab");
-        if (sourceGuid !== "" && seen.add(`prefab:${sourceGuid}`)) {
-            edges.push({ guid: sourceGuid, assetPath: "", kind: "prefab_source", resolved: false });
+        // 1. PrefabInstance.m_SourcePrefab — the base-prefab edge of a variant.
+        //    Read once via readGUIDField (the previous pass-1 scanner); the line
+        //    scan below still picks up target: GUIDs inside m_Modifications as
+        //    pptr edges, so variant overrides still count.
+        if (obj.type === "PrefabInstance") {
+            const sourceGuid = readGUIDField(obj.lines, "m_SourcePrefab");
+            if (sourceGuid !== "" && seen.add(`prefab:${sourceGuid}`)) {
+                prefabEdges.push({ guid: sourceGuid, assetPath: "", kind: "prefab_source", resolved: false });
+            }
         }
-    }
-    // 2. m_Script GUIDs on MonoBehaviours — the script-class edge.
-    for (const obj of parsed.objects) {
-        if (obj.type !== "MonoBehaviour")
-            continue;
-        if (obj.scriptGUID !== "" && seen.add(`script:${obj.scriptGUID}`)) {
-            edges.push({ guid: obj.scriptGUID, assetPath: "", kind: "script", resolved: false });
+        // 2. m_Script GUIDs on MonoBehaviours — the script-class edge. The
+        //    parsed object already carries scriptGUID (extracted during
+        //    finishObject), so no line re-scan is needed for this kind.
+        if (obj.type === "MonoBehaviour" && obj.scriptGUID !== "") {
+            if (seen.add(`script:${obj.scriptGUID}`)) {
+                scriptEdges.push({ guid: obj.scriptGUID, assetPath: "", kind: "script", resolved: false });
+            }
         }
-    }
-    // 3. Every other guid: field — material refs, asset refs, animation clips,
-    //    etc. m_Script is handled above; m_SourcePrefab target: GUIDs inside
-    //    PrefabInstance.m_Modifications are included here so variant overrides
-    //    count as forward edges too.
-    for (const obj of parsed.objects) {
+        // 3. Every other guid: field on every object — material refs, asset refs,
+        //    animation clips, etc. m_Script lines are excluded (handled above);
+        //    the m_SourcePrefab field's GUID is captured as a prefab_source edge
+        //    in branch 1, but a `guid:` token appearing on the m_SourcePrefab
+        //    line would ALSO match here — the original code had the same
+        //    overlap, deduped via the per-kind seen key (prefab: vs pptr:), so
+        //    the same guid legitimately produces both edges. The line.includes
+        //    fast-reject mirrors the previous pass-3 loop.
         for (const line of obj.lines) {
             if (!line.includes("guid:"))
                 continue;
@@ -625,10 +728,19 @@ function collectForwardEdges(parsed) {
             for (const g of findGUIDs(line)) {
                 if (!seen.add(`pptr:${g}`))
                     continue;
-                edges.push({ guid: g, assetPath: "", kind: "pptr", resolved: false });
+                pptrEdges.push({ guid: g, assetPath: "", kind: "pptr", resolved: false });
             }
         }
     }
+    // Concatenate in the previous implementation's kind order so the
+    // forwardDependencies array stays byte-identical.
+    const edges = [];
+    for (const e of prefabEdges)
+        edges.push(e);
+    for (const e of scriptEdges)
+        edges.push(e);
+    for (const e of pptrEdges)
+        edges.push(e);
     return edges;
 }
 /** Resolve forward edges against the GUID→path index. Mutates each edge in
@@ -672,7 +784,13 @@ async function detectCyclesOffline(startPath, startEdges, projectRoot, maxDepth)
         }
     }
     const visiting = new Set();
-    async function dfs(current, trail) {
+    // M31-optimizations Plan 3 / L12 — push/pop trail mutation. The previous
+    // recursion built the trail immutably via `[...trail, edge.assetPath]` per
+    // call (O(n²) path-build via spread). The trail is now a single mutable
+    // array pushed before recursing and popped after; the only place an
+    // immutable copy is needed is when emitting a discovered cycle (slice).
+    const trail = [];
+    async function dfs(current) {
         if (trail.length > maxDepth)
             return;
         const edges = await edgesOf(current);
@@ -680,13 +798,17 @@ async function detectCyclesOffline(startPath, startEdges, projectRoot, maxDepth)
             if (!edge.resolved || edge.assetPath === "")
                 continue;
             if (edge.assetPath === startPath) {
+                // Snapshot the trail + the closing startPath — the only immutable
+                // copy (the previous code's [...trail, startPath] at emit time).
                 cycles.push([...trail, startPath]);
                 continue;
             }
             if (visiting.has(edge.assetPath))
                 continue;
             visiting.add(edge.assetPath);
-            await dfs(edge.assetPath, [...trail, edge.assetPath]);
+            trail.push(edge.assetPath);
+            await dfs(edge.assetPath);
+            trail.pop();
             visiting.delete(edge.assetPath);
         }
     }
@@ -695,23 +817,117 @@ async function detectCyclesOffline(startPath, startEdges, projectRoot, maxDepth)
             continue;
         visiting.clear();
         visiting.add(edge.assetPath);
-        await dfs(edge.assetPath, [startPath, edge.assetPath]);
+        // Seed the mutable trail with [startPath, edge.assetPath] — the same
+        // starting state the previous dfs(edge.assetPath, [startPath, edge.assetPath])
+        // used. Pop both before the next seed so the trail is empty again.
+        trail.length = 0;
+        trail.push(startPath, edge.assetPath);
+        await dfs(edge.assetPath);
     }
     return cycles;
 }
-/** Transitive impact closure via BFS over reverse edges. */
-async function computeTransitiveImpact(startGuid, startPath, projectRoot, maxDepth) {
+/**
+ * M31-optimizations Plan 2 / H4 + M5 — build the project-wide reverse-edge
+ * graph in a SINGLE pass over parseable assets. Returns:
+ *   - graph: Map<referenced-guid, ReverseEdge[]> — every asset that references
+ *     each guid. Each edge carries the referencing asset's path + kind + its
+ *     OWN guid (so the BFS can resolve a frontier node's guid without an
+ *     extra .meta read).
+ *   - pathToGuid: Map<asset-path, own-guid> — the inverse lookup for the BFS.
+ *
+ * Used by {@link dependenciesOffline} to serve both the direct reverse-edge
+ * lookup AND the transitive impact BFS via pure Map.get, eliminating the
+ * O(closure × project size) re-walk the previous per-node
+ * findReferencesOffline calls incurred.
+ *
+ * In-memory, per-call only (a local variable in dependenciesOffline). Root
+ * AGENTS.md forbids disk caches; this is the same category as
+ * detectCyclesOffline's edgeCache.
+ *
+ * Edge semantics mirror findReferencesOffline: a file references a guid when
+ * its content contains the guid substring. Self-references are filtered at
+ * lookup time (findReferencesFromGraph), not here, so the graph captures
+ * every edge regardless of the eventual target.
+ */
+async function buildReverseEdgeGraph(projectRoot) {
+    const graph = new Map();
+    const pathToGuid = new Map();
+    const candidates = await collectFiles(join(projectRoot, "Assets"));
+    // Read each parseable asset once. Scan it for every guid: reference and
+    // append the asset's edge to each referenced guid's edge list. Also record
+    // the asset's own guid (from its .meta) so the impact BFS can resolve a
+    // frontier node's guid without re-reading .meta per hop.
+    await parallelMap(candidates, async (absPath) => {
+        const ext = extname(absPath).toLowerCase();
+        if (!OFFLINE_PARSEABLE_EXTENSIONS.has(ext))
+            return;
+        let content;
+        try {
+            content = await readFile(absPath, "utf-8");
+        }
+        catch {
+            return;
+        }
+        if (!content.includes("guid:"))
+            return;
+        const assetPath = toAssetPath(projectRoot, absPath);
+        const kind = kindForPath(absPath);
+        // Resolve the asset's own guid once (cheap .meta read, OS-cached).
+        const ownGuid = (await safeReadMetaGUID(absPath + ".meta")).toLowerCase();
+        const edge = { assetPath, guid: ownGuid, kind };
+        if (ownGuid !== "")
+            pathToGuid.set(assetPath, ownGuid);
+        // findGUIDs returns every guid: substring in the content (lowercased).
+        // Dedup within this file via a Set so a guid referenced N times in one
+        // asset still produces one edge entry (matches findReferencesOffline,
+        // which pushes at most one entry per referencing file).
+        const referenced = new Set(findGUIDs(content));
+        for (const guid of referenced) {
+            let list = graph.get(guid);
+            if (!list) {
+                list = [];
+                graph.set(guid, list);
+            }
+            list.push(edge);
+        }
+    });
+    return { graph, pathToGuid };
+}
+/**
+ * M31-optimizations Plan 2 / H4 — consult the precomputed reverse-edge graph
+ * for a single target guid, mirroring findReferencesOffline's reverse-edge
+ * semantics (skip self-references; one entry per referencing asset). Pure
+ * Map.get — no I/O. The graph is keyed by lowercased guid; the target guid
+ * is already lowercased by dependenciesOffline's resolution path.
+ */
+function findReferencesFromGraph(graph, targetGuid, targetPath) {
+    const list = graph.get(targetGuid);
+    if (!list)
+        return [];
+    const out = [];
+    for (const edge of list) {
+        if (edge.assetPath === targetPath)
+            continue; // self-reference
+        out.push(edge);
+    }
+    return out;
+}
+/**
+ * M31-optimizations Plan 2 / H4 — graph-driven transitive impact BFS.
+ * Replaces the previous computeTransitiveImpact, which called
+ * findReferencesOffline per frontier node (re-walking the project K times
+ * for a closure of size K — O(closure × project size)). The BFS is now pure
+ * Map.get on the precomputed reverse-edge graph; the only remaining per-node
+ * work is the pathToGuid lookup (a Map.get, not a .meta read — the asset's
+ * own guid was captured once during buildReverseEdgeGraph).
+ */
+async function computeTransitiveImpactFromGraph(startGuid, startPath, graph, pathToGuid, maxDepth) {
     const affected = [];
     const seen = new Set([startPath]);
     let frontier = [];
     let truncated = false;
-    const seed = await findReferencesOffline({
-        assetPath: startPath || undefined,
-        guid: startGuid,
-        detail: "normal",
-        projectRoot,
-    });
-    for (const e of seed.referencedBy) {
+    const seed = findReferencesFromGraph(graph, startGuid, startPath);
+    for (const e of seed) {
         if (seen.has(e.assetPath))
             continue;
         seen.add(e.assetPath);
@@ -723,15 +939,16 @@ async function computeTransitiveImpact(startGuid, startPath, projectRoot, maxDep
             break;
         const next = [];
         for (const nodePath of frontier) {
-            const nodeGuid = await safeReadMetaGUID(join(projectRoot, nodePath + ".meta"));
-            if (nodeGuid === "")
+            // Resolve the frontier node's guid via the precomputed pathToGuid
+            // index — a Map.get, no .meta read. A node whose .meta was missing/
+            // blank during the graph build contributes no outgoing edges here,
+            // matching the previous safeReadMetaGUID-based path's `if (nodeGuid
+            // === "") continue;` guard.
+            const nodeGuid = pathToGuid.get(nodePath);
+            if (nodeGuid === undefined)
                 continue;
-            const res = await findReferencesOffline({
-                guid: nodeGuid,
-                detail: "normal",
-                projectRoot,
-            });
-            for (const e of res.referencedBy) {
+            const referencedByNode = findReferencesFromGraph(graph, nodeGuid, nodePath);
+            for (const e of referencedByNode) {
                 if (seen.has(e.assetPath))
                     continue;
                 seen.add(e.assetPath);
@@ -753,33 +970,52 @@ async function computeTransitiveImpact(startGuid, startPath, projectRoot, maxDep
 }
 export async function scanIntegrityOffline(opts) {
     const issues = [];
-    const assetsDir = join(opts.projectRoot, "Assets");
+    // M31-optimizations Plan 2 / H3 — single meta walk for the whole scan.
+    // Previously this walked the meta tree 4× (collectFiles, per-file
+    // safeReadMetaGUID, walkMeta for orphans, buildGUIDIndex for integrity).
+    // The triples carry everything the scan needs: guidByPath, allAssetPaths,
+    // orphan detection, and the full GUID index (no second/third walk).
+    const triples = await collectMetaTriples(opts.projectRoot);
+    // Derive guidByPath and the full GUID index from the single meta-walk pass.
+    // `t.assetPath` is absolute (collectMetaTriples strips the .meta suffix
+    // from the absolute metaPath); convert to project-relative once.
     const guidByPath = new Map();
-    const allAssetPaths = new Set();
+    const fullGuidIndex = new Map();
+    for (const t of triples) {
+        const assetRel = toAssetPath(opts.projectRoot, t.assetPath);
+        if (t.guid !== "") {
+            guidByPath.set(assetRel, t.guid);
+            fullGuidIndex.set(t.guid, assetRel);
+        }
+    }
+    // allAssetPaths: every real asset on disk (not just those with .meta), used
+    // for orphan detection (a .meta whose companion asset is missing) and the
+    // assetsScanned count. The previous implementation derived this from a
+    // collectFiles walk; that walk is NOT a meta-walk, so keeping it does not
+    // regress H3 (which only consolidates the meta walks). The collectFiles
+    // walk is bounded-parallel (Plan 2 / M4) and shares the same readdir-order
+    // traversal as collectMetaTriples, so iteration order stays byte-identical.
+    const assetsDir = join(opts.projectRoot, "Assets");
     const assetFiles = await collectFiles(assetsDir);
+    const allAssetPaths = new Set();
     for (const absPath of assetFiles) {
-        const assetPath = toAssetPath(opts.projectRoot, absPath);
-        allAssetPaths.add(assetPath);
-        const metaGuid = await safeReadMetaGUID(absPath + ".meta");
-        if (metaGuid !== "") {
-            guidByPath.set(assetPath, metaGuid);
-        }
+        allAssetPaths.add(toAssetPath(opts.projectRoot, absPath));
     }
-    const metaOnlyPaths = new Set();
-    await walkMeta(assetsDir, async (metaPath) => {
-        const assetPath = toAssetPath(opts.projectRoot, metaPath.slice(0, -5));
-        if (!allAssetPaths.has(assetPath)) {
-            metaOnlyPaths.add(assetPath);
-        }
-    });
     // ---- orphan_meta: .meta whose companion asset is gone ----
-    for (const path of metaOnlyPaths) {
-        issues.push({
-            path: path + ".meta",
-            code: "orphan_meta",
-            severity: "warning",
-            detail: `meta file has no companion asset at ${path}`,
-        });
+    // An orphan is a triple whose companion asset path is NOT in the on-disk
+    // asset file set. (Previously detected via a second walkMeta pass diffing
+    // against allAssetPaths; now derived from the single triples pass + the
+    // one collectFiles walk we already needed for the integrity loop.)
+    for (const t of triples) {
+        const assetRel = toAssetPath(opts.projectRoot, t.assetPath);
+        if (!allAssetPaths.has(assetRel)) {
+            issues.push({
+                path: assetRel + ".meta",
+                code: "orphan_meta",
+                severity: "warning",
+                detail: `meta file has no companion asset at ${assetRel}`,
+            });
+        }
     }
     // ---- duplicate_guid: GUID shared by 2+ assets ----
     const pathsByGuid = new Map();
@@ -790,6 +1026,11 @@ export async function scanIntegrityOffline(opts) {
         else
             pathsByGuid.set(guid, [assetPath]);
     }
+    // M31-optimizations Plan 2 / H3 — preserve the previous iteration order so
+    // duplicate_guid issue ordering stays byte-identical. The previous impl
+    // iterated guidByPath (Map insertion order = assetFiles walk order); the
+    // triples-derived guidByPath preserves that same order because triples
+    // are pushed in walkMeta's readdir-order walk (matching collectFiles).
     for (const [guid, paths] of pathsByGuid) {
         if (paths.length < 2)
             continue;
@@ -804,7 +1045,10 @@ export async function scanIntegrityOffline(opts) {
         }
     }
     // ---- aggregated missing references (the per-read check, project-wide) ----
-    const fullGuidIndex = await buildGUIDIndex(opts.projectRoot);
+    // fullGuidIndex was populated from the single triples pass above — no
+    // separate buildGUIDIndex walk. The asset-body reads below are inherent to
+    // scanning (each YAML asset must be parsed to surface its missing refs);
+    // this plan only collapsed the meta walks, not the body reads.
     for (const absPath of assetFiles) {
         const ext = extname(absPath).toLowerCase();
         if (!OFFLINE_PARSEABLE_EXTENSIONS.has(ext))
@@ -846,6 +1090,7 @@ export async function scanIntegrityOffline(opts) {
         byCode,
         totalIssues: issues.length,
         assetsScanned: allAssetPaths.size,
+        // Inline tag is load-bearing — see the note on IntegrityScanResult._source.
         _source: "offline",
     };
 }