@veewo/gitnexus 1.3.10 → 1.3.11

package/dist/mcp/local/local-backend.js

@@ -8,8 +8,16 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { initKuzu, executeQuery, closeKuzu, isKuzuReady } from '../core/kuzu-adapter.js';
-import { parseUnityResourcesMode } from '../../core/unity/options.js';
-import { loadUnityContext } from './unity-enrichment.js';
+import { parseUnityHydrationMode, parseUnityResourcesMode } from '../../core/unity/options.js';
+import { buildUnityScanContext, buildUnityScanContextFromSeed } from '../../core/unity/scan-context.js';
+import { resolveUnityBindings } from '../../core/unity/resolver.js';
+import { formatLazyHydrationBudgetDiagnostic, loadUnityContext, } from './unity-enrichment.js';
+import { resolveUnityLazyConfig } from './unity-lazy-config.js';
+import { hydrateLazyBindings } from './unity-lazy-hydrator.js';
+import { readUnityOverlayBindings, upsertUnityOverlayBindings } from './unity-lazy-overlay.js';
+import { readUnityParityCache, upsertUnityParityCache } from './unity-parity-cache.js';
+import { createParityWarmupQueue } from './unity-parity-warmup-queue.js';
+import { loadUnityParitySeed } from './unity-parity-seed-loader.js';
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at MCP server startup — crashes on unsupported Node ABI versions (#89)
 // git utilities available if needed
@@ -30,6 +38,91 @@ function isTestFilePath(filePath) {
         p.endsWith('_test.go') || p.endsWith('_test.py') ||
         p.includes('/test_') || p.includes('/conftest.'));
 }
+function normalizePath(filePath) {
+    return String(filePath || '').replace(/\\/g, '/');
+}
+function bindingIdentity(binding) {
+    return [
+        normalizePath(binding.resourcePath),
+        binding.bindingKind,
+        binding.componentObjectId,
+    ].join('|');
+}
+export function mergeUnityBindings(baseBindings, resolvedByPath) {
+    const merged = [];
+    const expandedPaths = new Set();
+    for (const binding of baseBindings) {
+        const resourcePath = normalizePath(binding.resourcePath);
+        if (!binding.lightweight) {
+            merged.push(binding);
+            continue;
+        }
+        const expanded = resolvedByPath.get(resourcePath);
+        if (expanded && expanded.length > 0) {
+            if (!expandedPaths.has(resourcePath)) {
+                merged.push(...expanded.map((row) => ({ ...row, lightweight: false })));
+                expandedPaths.add(resourcePath);
+            }
+            continue;
+        }
+        merged.push(binding);
+    }
+    return merged;
+}
+export function mergeParityUnityBindings(baseNonLightweightBindings, resolvedBindings) {
+    const merged = [];
+    const seen = new Set();
+    for (const row of [...baseNonLightweightBindings, ...resolvedBindings]) {
+        const key = bindingIdentity(row);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push({ ...row, lightweight: false });
+    }
+    return merged;
+}
+export function attachUnityHydrationMeta(payload, input) {
+    const { hasExpandableBindings, ...metaInput } = input;
+    const reasons = [];
+    if (metaInput.effectiveMode === 'compact' && hasExpandableBindings) {
+        reasons.push('mode_compact');
+    }
+    if (metaInput.fallbackToCompact) {
+        reasons.push('fallback_to_compact');
+    }
+    if (hasExpandableBindings) {
+        reasons.push('lightweight_bindings_remaining');
+    }
+    if (payload.unityDiagnostics.some((diag) => /budget exceeded/i.test(String(diag || '')))) {
+        reasons.push('budget_exceeded');
+    }
+    const isComplete = reasons.length === 0;
+    const needsParityRetry = !isComplete && metaInput.effectiveMode === 'compact';
+    return {
+        ...payload,
+        hydrationMeta: {
+            ...metaInput,
+            resourceBindingCount: payload.resourceBindings.length,
+            unityDiagnosticsCount: payload.unityDiagnostics.length,
+            isComplete,
+            completenessReason: reasons,
+            needsParityRetry,
+            ...(needsParityRetry ? { retryHint: 'rerun_with_unity_hydration=parity' } : {}),
+        },
+    };
+}
+const inFlightParityHydration = new Map();
+const parityWarmupQueue = createParityWarmupQueue({
+    maxParallel: resolveParityWarmupMaxParallel(process.env),
+});
+function resolveParityWarmupMaxParallel(env) {
+    const raw = String(env.GITNEXUS_UNITY_PARITY_WARMUP_MAX_PARALLEL || '').trim();
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+        return parsed;
+    }
+    return 2;
+}
 /** Valid KuzuDB node labels for safe Cypher query construction */
 const VALID_NODE_LABELS = new Set([
     'File', 'Folder', 'Function', 'Class', 'Interface', 'Method', 'CodeElement',
@@ -288,6 +381,7 @@ export class LocalBackend {
         const maxSymbolsPerProcess = params.max_symbols || 10;
         const includeContent = params.include_content ?? false;
         const unityResourcesMode = parseUnityResourcesMode(params.unity_resources);
+        const unityHydrationMode = parseUnityHydrationMode(params.unity_hydration_mode);
         const searchQuery = params.query.trim();
         // Step 1: Run hybrid search to get matching symbols
         const searchLimit = processLimit * maxSymbolsPerProcess; // fetch enough raw results
@@ -387,7 +481,13 @@ export class LocalBackend {
                 ...(module ? { module } : {}),
                 ...(includeContent && content ? { content } : {}),
                 ...((unityResourcesMode !== 'off' && sym.nodeId && sym.type === 'Class')
-                    ? await loadUnityContext(repo.id, sym.nodeId, (query) => executeQuery(repo.id, query))
+                    ? await this.hydrateUnityContext(repo, {
+                        symbolUid: sym.nodeId,
+                        symbolName: sym.name || '',
+                        symbolFilePath: sym.filePath || '',
+                        payload: await loadUnityContext(repo.id, sym.nodeId, (query) => executeQuery(repo.id, query)),
+                        hydrationMode: unityHydrationMode,
+                    })
                     : {}),
             };
             if (processRows.length === 0) {
@@ -803,6 +903,7 @@ export class LocalBackend {
         await this.ensureInitialized(repo.id);
         const { name, uid, file_path, include_content } = params;
         const unityResourcesMode = parseUnityResourcesMode(params.unity_resources);
+        const unityHydrationMode = parseUnityHydrationMode(params.unity_hydration_mode);
         if (!name && !uid) {
             return { error: 'Either "name" or "uid" parameter is required.' };
         }
@@ -976,7 +1077,15 @@ export class LocalBackend {
             })),
         };
         if (unityResourcesMode !== 'off' && symNodeId && symKind === 'Class') {
-            Object.assign(result, await loadUnityContext(repo.id, symNodeId, (query) => executeQuery(repo.id, query)));
+            const unityContext = await loadUnityContext(repo.id, symNodeId, (query) => executeQuery(repo.id, query));
+            const hydratedUnityContext = await this.hydrateUnityContext(repo, {
+                symbolUid: symNodeId,
+                symbolName: getRowValue(sym, 'name', 1) || '',
+                symbolFilePath: symFilePath,
+                payload: unityContext,
+                hydrationMode: unityHydrationMode,
+            });
+            Object.assign(result, hydratedUnityContext);
         }
         return result;
     }
@@ -1063,6 +1172,213 @@ export class LocalBackend {
         }
         return { error: 'Invalid type. Use: symbol, cluster, or process' };
     }
+    async hydrateUnityContext(repo, input) {
+        const startedAt = Date.now();
+        if (input.hydrationMode === 'compact') {
+            const compactPayload = await this.hydrateUnityContextCompact(repo, input);
+            const withMeta = attachUnityHydrationMeta(compactPayload, {
+                requestedMode: 'compact',
+                effectiveMode: 'compact',
+                elapsedMs: Date.now() - startedAt,
+                fallbackToCompact: false,
+                hasExpandableBindings: compactPayload.resourceBindings.some((binding) => binding.lightweight || binding.componentObjectId === 'summary'),
+            });
+            if (withMeta.hydrationMeta?.needsParityRetry) {
+                this.scheduleParityWarmup(repo, input);
+            }
+            return withMeta;
+        }
+        const parityResult = await this.hydrateUnityContextParity(repo, input);
+        return attachUnityHydrationMeta(parityResult.payload, {
+            requestedMode: 'parity',
+            effectiveMode: parityResult.effectiveMode,
+            elapsedMs: Date.now() - startedAt,
+            fallbackToCompact: parityResult.fallbackToCompact,
+            hasExpandableBindings: parityResult.payload.resourceBindings.some((binding) => binding.lightweight || binding.componentObjectId === 'summary'),
+        });
+    }
+    buildParityWarmupKey(repo, symbolUid) {
+        return `${repo.storagePath}::${repo.lastCommit}::${symbolUid}`;
+    }
+    scheduleParityWarmup(repo, input) {
+        if (!this.shouldEnableParityWarmup()) {
+            return;
+        }
+        if (!input.symbolUid || !input.symbolName || !input.symbolFilePath) {
+            return;
+        }
+        void parityWarmupQueue.run(() => this.getOrRunParityHydration(repo, input))
+            .then(() => undefined)
+            .catch(() => undefined);
+    }
+    shouldEnableParityWarmup() {
+        const raw = String(process.env.GITNEXUS_UNITY_PARITY_WARMUP || '').trim().toLowerCase();
+        return raw === '1' || raw === 'true' || raw === 'on';
+    }
+    async getOrRunParityHydration(repo, input) {
+        const key = this.buildParityWarmupKey(repo, input.symbolUid);
+        const existing = inFlightParityHydration.get(key);
+        if (existing) {
+            return existing;
+        }
+        const pending = (async () => {
+            const cached = await readUnityParityCache(repo.storagePath, repo.lastCommit, input.symbolUid);
+            if (cached) {
+                return cached;
+            }
+            const payload = await this.computeParityPayload(repo, input);
+            await upsertUnityParityCache(repo.storagePath, repo.lastCommit, input.symbolUid, payload);
+            return payload;
+        })().finally(() => {
+            inFlightParityHydration.delete(key);
+        });
+        inFlightParityHydration.set(key, pending);
+        return pending;
+    }
+    async computeParityPayload(repo, input) {
+        const symbolDeclarations = [{ symbol: input.symbolName, scriptPath: input.symbolFilePath }];
+        const paritySeed = await loadUnityParitySeed(repo.storagePath);
+        const seededScanContext = paritySeed
+            ? buildUnityScanContextFromSeed({
+                seed: paritySeed,
+                symbolDeclarations,
+            })
+            : null;
+        let resolved = await resolveUnityBindings({
+            repoRoot: repo.repoPath,
+            symbol: input.symbolName,
+            scanContext: seededScanContext || await buildUnityScanContext({
+                repoRoot: repo.repoPath,
+                symbolDeclarations,
+            }),
+            deepParseLargeResources: true,
+        });
+        if (seededScanContext
+            && resolved.resourceBindings.length === 0
+            && input.payload.resourceBindings.length > 0) {
+            const fallbackScanContext = await buildUnityScanContext({
+                repoRoot: repo.repoPath,
+                symbolDeclarations,
+            });
+            resolved = await resolveUnityBindings({
+                repoRoot: repo.repoPath,
+                symbol: input.symbolName,
+                scanContext: fallbackScanContext,
+                deepParseLargeResources: true,
+            });
+        }
+        if (resolved.resourceBindings.length === 0 && input.payload.resourceBindings.length > 0) {
+            throw new Error('parity-expand returned zero bindings');
+        }
+        const baseNonLightweight = input.payload.resourceBindings.filter((binding) => !binding.lightweight && binding.componentObjectId !== 'summary');
+        const mergedBindings = mergeParityUnityBindings(baseNonLightweight, resolved.resourceBindings);
+        return this.toUnityContextPayload(mergedBindings, [
+            ...input.payload.unityDiagnostics,
+            ...resolved.unityDiagnostics,
+        ]);
+    }
+    async hydrateUnityContextParity(repo, input) {
+        try {
+            return {
+                payload: await this.getOrRunParityHydration(repo, input),
+                effectiveMode: 'parity',
+                fallbackToCompact: false,
+            };
+        }
+        catch (error) {
+            const compactFallback = await this.hydrateUnityContextCompact(repo, input);
+            const message = String(error instanceof Error ? error.message : error);
+            return {
+                payload: {
+                    ...compactFallback,
+                    unityDiagnostics: [
+                        ...compactFallback.unityDiagnostics,
+                        /parity-expand returned zero bindings/i.test(message)
+                            ? 'parity-expand returned zero bindings; fell back to compact hydration'
+                            : `parity-expand failed: ${message}`,
+                    ],
+                },
+                effectiveMode: 'compact',
+                fallbackToCompact: true,
+            };
+        }
+    }
+    async hydrateUnityContextCompact(repo, input) {
+        const lightweightPaths = [...new Set(input.payload.resourceBindings
+                .filter((binding) => binding.lightweight || binding.componentObjectId === 'summary')
+                .map((binding) => normalizePath(binding.resourcePath))
+                .filter((value) => value.length > 0))];
+        if (lightweightPaths.length === 0) {
+            return input.payload;
+        }
+        const overlayHits = await readUnityOverlayBindings(repo.storagePath, repo.lastCommit, input.symbolUid, lightweightPaths);
+        const pendingPaths = lightweightPaths.filter((resourcePath) => !overlayHits.has(resourcePath));
+        const resolvedByPath = new Map(overlayHits);
+        const unityDiagnostics = [...input.payload.unityDiagnostics];
+        if (pendingPaths.length > 0) {
+            try {
+                const cfg = resolveUnityLazyConfig(process.env);
+                const hydration = await hydrateLazyBindings({
+                    pendingPaths,
+                    config: cfg,
+                    dedupeKey: `${input.symbolUid}::${pendingPaths.slice().sort().join('|')}`,
+                    resolveBatch: async (resourcePaths) => {
+                        const scopedPaths = [
+                            input.symbolFilePath,
+                            `${input.symbolFilePath}.meta`,
+                            ...resourcePaths,
+                            ...resourcePaths.map((resourcePath) => `${resourcePath}.meta`),
+                        ].map(normalizePath);
+                        const scanContext = await buildUnityScanContext({
+                            repoRoot: repo.repoPath,
+                            scopedPaths,
+                            symbolDeclarations: [{ symbol: input.symbolName, scriptPath: input.symbolFilePath }],
+                        });
+                        const resolved = await resolveUnityBindings({
+                            repoRoot: repo.repoPath,
+                            symbol: input.symbolName,
+                            scanContext,
+                            resourcePathAllowlist: resourcePaths,
+                            deepParseLargeResources: true,
+                        });
+                        unityDiagnostics.push(...resolved.unityDiagnostics);
+                        const byPath = new Map();
+                        for (const resourcePath of resourcePaths) {
+                            byPath.set(resourcePath, resolved.resourceBindings.filter((binding) => normalizePath(binding.resourcePath) === normalizePath(resourcePath)));
+                        }
+                        return byPath;
+                    },
+                });
+                const freshByPath = hydration.resolvedByPath;
+                if (hydration.timedOut) {
+                    unityDiagnostics.push(formatLazyHydrationBudgetDiagnostic(hydration.elapsedMs));
+                }
+                const hydrationExtras = hydration.diagnostics.filter((diag) => !/budget exceeded/i.test(diag));
+                if (hydrationExtras.length > 0) {
+                    unityDiagnostics.push(...hydrationExtras);
+                }
+                await upsertUnityOverlayBindings(repo.storagePath, repo.lastCommit, input.symbolUid, freshByPath);
+                for (const [resourcePath, bindings] of freshByPath.entries()) {
+                    resolvedByPath.set(resourcePath, bindings);
+                }
+            }
+            catch (error) {
+                unityDiagnostics.push(`lazy-expand failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const mergedBindings = mergeUnityBindings(input.payload.resourceBindings, resolvedByPath);
+        return this.toUnityContextPayload(mergedBindings, unityDiagnostics);
+    }
+    toUnityContextPayload(resourceBindings, unityDiagnostics) {
+        return {
+            resourceBindings,
+            serializedFields: {
+                scalarFields: resourceBindings.flatMap((binding) => binding.serializedFields.scalarFields),
+                referenceFields: resourceBindings.flatMap((binding) => binding.serializedFields.referenceFields),
+            },
+            unityDiagnostics,
+        };
+    }
     /**
      * Detect changes — git-diff based impact analysis.
      * Maps changed lines to indexed symbols, then finds affected processes.

package/dist/mcp/local/local-backend.unity-merge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/local/local-backend.unity-merge.test.js

@@ -0,0 +1,261 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { projectUnityBindings } from './unity-enrichment.js';
+import { hydrateLazyBindings } from './unity-lazy-hydrator.js';
+import { attachUnityHydrationMeta, mergeParityUnityBindings, mergeUnityBindings } from './local-backend.js';
+test('summary-only rows hydrate and merge into full bindings with preserved field coverage', async () => {
+    const projected = projectUnityBindings([
+        {
+            relationType: 'UNITY_RESOURCE_SUMMARY',
+            relationReason: JSON.stringify({ resourceType: 'prefab', bindingKinds: ['direct', 'nested'], lightweight: true }),
+            resourcePath: 'Assets/Doors/Door.prefab',
+            payload: '',
+        },
+        {
+            relationType: 'UNITY_RESOURCE_SUMMARY',
+            relationReason: JSON.stringify({ resourceType: 'prefab', bindingKinds: ['prefab-instance'], lightweight: true }),
+            resourcePath: 'Assets/Doors/Boss.prefab',
+            payload: '',
+        },
+        {
+            resourcePath: 'Assets/Scene/Test.unity',
+            relationType: 'UNITY_COMPONENT_INSTANCE',
+            relationReason: 'scene-override',
+            payload: JSON.stringify({
+                resourcePath: 'Assets/Scene/Test.unity',
+                resourceType: 'scene',
+                bindingKind: 'scene-override',
+                componentObjectId: '11400000',
+                evidence: { line: 9, lineText: 'm_Script: ...' },
+                serializedFields: {
+                    scalarFields: [{ name: 'needPause', value: '1', valueType: 'number', sourceLayer: 'scene' }],
+                    referenceFields: [],
+                },
+            }),
+        },
+    ]);
+    const pendingPaths = [...new Set(projected.resourceBindings
+            .filter((binding) => binding.lightweight)
+            .map((binding) => binding.resourcePath))];
+    const hydration = await hydrateLazyBindings({
+        pendingPaths,
+        config: { maxPendingPathsPerRequest: 10, batchSize: 10, maxHydrationMs: 5000 },
+        resolveBatch: async () => new Map([
+            ['Assets/Doors/Door.prefab', [
+                    {
+                        resourcePath: 'Assets/Doors/Door.prefab',
+                        resourceType: 'prefab',
+                        bindingKind: 'direct',
+                        componentObjectId: '114',
+                        lightweight: false,
+                        evidence: { line: 12, lineText: 'm_Script: ...' },
+                        serializedFields: {
+                            scalarFields: [{ name: 'Shows', value: '1', valueType: 'number', sourceLayer: 'prefab' }],
+                            referenceFields: [],
+                        },
+                        resolvedReferences: [],
+                        assetRefPaths: [],
+                    },
+                    {
+                        resourcePath: 'Assets/Doors/Door.prefab',
+                        resourceType: 'prefab',
+                        bindingKind: 'nested',
+                        componentObjectId: '115',
+                        lightweight: false,
+                        evidence: { line: 33, lineText: 'm_Script: ...' },
+                        serializedFields: {
+                            scalarFields: [{ name: 'ToSecretRoom', value: '0', valueType: 'number', sourceLayer: 'prefab' }],
+                            referenceFields: [],
+                        },
+                        resolvedReferences: [],
+                        assetRefPaths: [],
+                    },
+                ]],
+            ['Assets/Doors/Boss.prefab', [
+                    {
+                        resourcePath: 'Assets/Doors/Boss.prefab',
+                        resourceType: 'prefab',
+                        bindingKind: 'prefab-instance',
+                        componentObjectId: '210',
+                        lightweight: false,
+                        evidence: { line: 19, lineText: 'm_Script: ...' },
+                        serializedFields: { scalarFields: [], referenceFields: [] },
+                        resolvedReferences: [],
+                        assetRefPaths: [],
+                    },
+                ]],
+        ]),
+    });
+    const merged = mergeUnityBindings(projected.resourceBindings, hydration.resolvedByPath);
+    assert.equal(merged.length, 4);
+    assert.equal(merged.filter((row) => row.resourcePath === 'Assets/Doors/Door.prefab').length, 2);
+    assert.equal(merged.filter((row) => row.resourcePath === 'Assets/Doors/Boss.prefab').length, 1);
+    assert.equal(merged.filter((row) => row.resourcePath === 'Assets/Scene/Test.unity').length, 1);
+    assert.equal(merged.some((row) => row.componentObjectId === 'summary'), false);
+    assert.equal(merged.some((row) => row.lightweight), false);
+    const scalarFieldNames = merged.flatMap((row) => row.serializedFields.scalarFields.map((field) => field.name));
+    assert.equal(scalarFieldNames.includes('Shows'), true);
+    assert.equal(scalarFieldNames.includes('ToSecretRoom'), true);
+    assert.equal(scalarFieldNames.includes('needPause'), true);
+});
+test('mergeUnityBindings keeps lightweight summaries when hydration has no expanded rows', async () => {
+    const projected = projectUnityBindings([
+        {
+            relationType: 'UNITY_RESOURCE_SUMMARY',
+            relationReason: JSON.stringify({ resourceType: 'prefab', bindingKinds: ['direct'], lightweight: true }),
+            resourcePath: 'Assets/Doors/Unresolved.prefab',
+            payload: '',
+        },
+    ]);
+    const merged = mergeUnityBindings(projected.resourceBindings, new Map());
+    assert.equal(merged.length, 1);
+    assert.equal(merged[0]?.resourcePath, 'Assets/Doors/Unresolved.prefab');
+    assert.equal(merged[0]?.lightweight, true);
+    assert.equal(merged[0]?.componentObjectId, 'summary');
+});
+test('mergeParityUnityBindings prefers full resolved rows and preserves non-lightweight base evidence', () => {
+    const merged = mergeParityUnityBindings([
+        {
+            resourcePath: 'Assets/Doors/Legacy.prefab',
+            resourceType: 'prefab',
+            bindingKind: 'direct',
+            componentObjectId: 'legacy-1',
+            lightweight: false,
+            evidence: { line: 1, lineText: 'legacy' },
+            serializedFields: { scalarFields: [], referenceFields: [] },
+            resolvedReferences: [],
+            assetRefPaths: [],
+        },
+    ], [
+        {
+            resourcePath: 'Assets/Doors/New.prefab',
+            resourceType: 'prefab',
+            bindingKind: 'direct',
+            componentObjectId: 'new-1',
+            lightweight: false,
+            evidence: { line: 2, lineText: 'new' },
+            serializedFields: { scalarFields: [], referenceFields: [] },
+            resolvedReferences: [],
+            assetRefPaths: [],
+        },
+        {
+            resourcePath: 'Assets/Doors/New.prefab',
+            resourceType: 'prefab',
+            bindingKind: 'direct',
+            componentObjectId: 'new-1',
+            lightweight: false,
+            evidence: { line: 2, lineText: 'new' },
+            serializedFields: { scalarFields: [], referenceFields: [] },
+            resolvedReferences: [],
+            assetRefPaths: [],
+        },
+    ]);
+    assert.equal(merged.length, 2);
+    assert.equal(merged.some((row) => row.componentObjectId === 'legacy-1'), true);
+    assert.equal(merged.some((row) => row.componentObjectId === 'new-1'), true);
+    assert.equal(merged.some((row) => row.lightweight), false);
+});
+test('attachUnityHydrationMeta annotates payload with requested/effective mode and counts', () => {
+    const payload = projectUnityBindings([
+        {
+            relationType: 'UNITY_RESOURCE_SUMMARY',
+            relationReason: JSON.stringify({ resourceType: 'prefab', bindingKinds: ['direct'], lightweight: true }),
+            resourcePath: 'Assets/Doors/Door.prefab',
+            payload: '',
+        },
+    ]);
+    const out = attachUnityHydrationMeta(payload, {
+        requestedMode: 'parity',
+        effectiveMode: 'compact',
+        elapsedMs: 42,
+        fallbackToCompact: true,
+        hasExpandableBindings: true,
+    });
+    assert.equal(out.hydrationMeta?.requestedMode, 'parity');
+    assert.equal(out.hydrationMeta?.effectiveMode, 'compact');
+    assert.equal(out.hydrationMeta?.elapsedMs, 42);
+    assert.equal(out.hydrationMeta?.fallbackToCompact, true);
+    assert.equal(out.hydrationMeta?.resourceBindingCount, 1);
+    assert.equal(out.hydrationMeta?.unityDiagnosticsCount, 0);
+    assert.equal(out.hydrationMeta?.isComplete, false);
+    assert.equal(out.hydrationMeta?.needsParityRetry, true);
+    assert.equal(out.hydrationMeta?.retryHint, 'rerun_with_unity_hydration=parity');
+    assert.equal(out.hydrationMeta?.completenessReason.includes('mode_compact'), true);
+    assert.equal(out.hydrationMeta?.completenessReason.includes('fallback_to_compact'), true);
+    assert.equal(out.hydrationMeta?.completenessReason.includes('lightweight_bindings_remaining'), true);
+});
+test('attachUnityHydrationMeta marks parity payload complete when no fallback/diagnostics remain', () => {
+    const payload = projectUnityBindings([
+        {
+            resourcePath: 'Assets/Scene/Test.unity',
+            relationType: 'UNITY_COMPONENT_INSTANCE',
+            relationReason: 'scene-override',
+            payload: JSON.stringify({
+                resourcePath: 'Assets/Scene/Test.unity',
+                resourceType: 'scene',
+                bindingKind: 'scene-override',
+                componentObjectId: '11400000',
+                evidence: { line: 9, lineText: 'm_Script: ...' },
+                serializedFields: { scalarFields: [], referenceFields: [] },
+            }),
+        },
+    ]);
+    const out = attachUnityHydrationMeta(payload, {
+        requestedMode: 'parity',
+        effectiveMode: 'parity',
+        elapsedMs: 12,
+        fallbackToCompact: false,
+        hasExpandableBindings: false,
+    });
+    assert.equal(out.hydrationMeta?.isComplete, true);
+    assert.equal(out.hydrationMeta?.needsParityRetry, false);
+    assert.equal(out.hydrationMeta?.retryHint, undefined);
+    assert.deepEqual(out.hydrationMeta?.completenessReason, []);
+});
+test('attachUnityHydrationMeta marks compact payload complete when no expandable bindings remain', () => {
+    const payload = projectUnityBindings([
+        {
+            resourcePath: 'Assets/Scene/Test.unity',
+            relationType: 'UNITY_COMPONENT_INSTANCE',
+            relationReason: 'scene-override',
+            payload: JSON.stringify({
+                resourcePath: 'Assets/Scene/Test.unity',
+                resourceType: 'scene',
+                bindingKind: 'scene-override',
+                componentObjectId: '11400000',
+                evidence: { line: 9, lineText: 'm_Script: ...' },
+                serializedFields: { scalarFields: [], referenceFields: [] },
+            }),
+        },
+    ]);
+    const out = attachUnityHydrationMeta(payload, {
+        requestedMode: 'compact',
+        effectiveMode: 'compact',
+        elapsedMs: 5,
+        fallbackToCompact: false,
+        hasExpandableBindings: false,
+    });
+    assert.equal(out.hydrationMeta?.isComplete, true);
+    assert.equal(out.hydrationMeta?.needsParityRetry, false);
+    assert.deepEqual(out.hydrationMeta?.completenessReason, []);
+});
+test('attachUnityHydrationMeta marks compact payload incomplete when expandable bindings remain', () => {
+    const payload = projectUnityBindings([
+        {
+            relationType: 'UNITY_RESOURCE_SUMMARY',
+            relationReason: JSON.stringify({ resourceType: 'prefab', bindingKinds: ['direct'], lightweight: true }),
+            resourcePath: 'Assets/Doors/Door.prefab',
+            payload: '',
+        },
+    ]);
+    const out = attachUnityHydrationMeta(payload, {
+        requestedMode: 'compact',
+        effectiveMode: 'compact',
+        elapsedMs: 5,
+        fallbackToCompact: false,
+        hasExpandableBindings: true,
+    });
+    assert.equal(out.hydrationMeta?.isComplete, false);
+    assert.equal(out.hydrationMeta?.needsParityRetry, true);
+    assert.equal(out.hydrationMeta?.completenessReason.includes('mode_compact'), true);
+});

package/dist/mcp/local/unity-enrichment.d.ts

@@ -1,6 +1,21 @@
 import type { ResolveOutput } from '../../core/unity/resolver.js';
+import type { UnityHydrationMode } from '../../core/unity/options.js';
+export interface UnityHydrationMeta {
+    requestedMode: UnityHydrationMode;
+    effectiveMode: UnityHydrationMode;
+    elapsedMs: number;
+    fallbackToCompact: boolean;
+    resourceBindingCount: number;
+    unityDiagnosticsCount: number;
+    isComplete: boolean;
+    completenessReason: string[];
+    needsParityRetry: boolean;
+    retryHint?: string;
+}
 export interface UnityContextPayload extends Pick<ResolveOutput, 'resourceBindings' | 'serializedFields' | 'unityDiagnostics'> {
+    hydrationMeta?: UnityHydrationMeta;
 }
 export type ExecuteQuery = (query: string) => Promise<any[]>;
 export declare function loadUnityContext(_repoId: string, symbolId: string, execute: ExecuteQuery): Promise<UnityContextPayload>;
+export declare function formatLazyHydrationBudgetDiagnostic(elapsedMs: number): string;
 export declare function projectUnityBindings(rows: any[]): UnityContextPayload;