@veewo/gitnexus 1.4.11-rc.2 → 1.5.0-rc.2

package/dist/mcp/local/unity-evidence-view.d.ts

@@ -0,0 +1,26 @@
+import type { UnityEvidenceMode } from '../../core/unity/options.js';
+import type { ResolvedUnityBinding, UnitySerializedFields } from '../../core/unity/resolver.js';
+export interface UnityEvidenceMeta {
+    truncated: boolean;
+    omitted_count: number;
+    next_fetch_hint?: string;
+    filter_exhausted?: boolean;
+    minimum_evidence_satisfied: boolean;
+    verifier_minimum_evidence_satisfied?: boolean;
+}
+export interface UnityEvidenceViewResult {
+    resourceBindings: ResolvedUnityBinding[];
+    serializedFields: UnitySerializedFields;
+    evidence_meta: UnityEvidenceMeta;
+    filter_diagnostics: string[];
+}
+export interface UnityEvidenceViewInput {
+    resourceBindings: ResolvedUnityBinding[];
+    mode?: UnityEvidenceMode;
+    scopePreset?: string;
+    resourcePathPrefix?: string;
+    bindingKind?: string;
+    maxBindings?: number;
+    maxReferenceFields?: number;
+}
+export declare function buildUnityEvidenceView(input: UnityEvidenceViewInput): UnityEvidenceViewResult;

package/dist/mcp/local/unity-evidence-view.js

@@ -0,0 +1,96 @@
+function normalizePath(value) {
+    return String(value || '').replace(/\\/g, '/').toLowerCase();
+}
+function parsePositiveInt(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    const parsed = Number.parseInt(String(raw), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return undefined;
+    return parsed;
+}
+function resolveModeDefaults(mode) {
+    if (mode === 'summary') {
+        return { maxBindings: 1, maxReferenceFields: 1 };
+    }
+    if (mode === 'focused') {
+        return { maxBindings: 5, maxReferenceFields: 5 };
+    }
+    return {};
+}
+function aggregateSerializedFields(resourceBindings) {
+    return {
+        scalarFields: resourceBindings.flatMap((binding) => binding.serializedFields.scalarFields),
+        referenceFields: resourceBindings.flatMap((binding) => binding.serializedFields.referenceFields),
+    };
+}
+export function buildUnityEvidenceView(input) {
+    const diagnostics = [];
+    const originalCount = input.resourceBindings.length;
+    let filtered = [...input.resourceBindings];
+    if (input.scopePreset === 'unity-gameplay') {
+        filtered = filtered.filter((binding) => {
+            const p = normalizePath(binding.resourcePath);
+            return p.startsWith('assets/')
+                && !p.startsWith('assets/plugins/')
+                && !p.startsWith('packages/')
+                && !p.startsWith('library/');
+        });
+    }
+    const prefix = normalizePath(String(input.resourcePathPrefix || ''));
+    if (prefix) {
+        filtered = filtered.filter((binding) => normalizePath(binding.resourcePath).startsWith(prefix));
+    }
+    const bindingKind = String(input.bindingKind || '').trim();
+    if (bindingKind) {
+        filtered = filtered.filter((binding) => String(binding.bindingKind) === bindingKind);
+    }
+    const filterExhausted = filtered.length === 0 && originalCount > 0;
+    if (filterExhausted) {
+        diagnostics.push('filter_exhausted');
+    }
+    const modeDefaults = resolveModeDefaults(input.mode);
+    const maxBindings = parsePositiveInt(input.maxBindings) ?? modeDefaults.maxBindings;
+    const maxReferenceFields = parsePositiveInt(input.maxReferenceFields) ?? modeDefaults.maxReferenceFields;
+    const beforeBindingTrim = filtered.length;
+    if (maxBindings !== undefined) {
+        filtered = filtered.slice(0, maxBindings);
+    }
+    let omittedCount = Math.max(0, beforeBindingTrim - filtered.length);
+    if (maxReferenceFields !== undefined) {
+        filtered = filtered.map((binding) => {
+            const referenceFields = binding.serializedFields.referenceFields;
+            const referenceTrimmed = referenceFields.length > maxReferenceFields;
+            if (referenceTrimmed) {
+                omittedCount += referenceFields.length - maxReferenceFields;
+            }
+            return {
+                ...binding,
+                serializedFields: {
+                    ...binding.serializedFields,
+                    referenceFields: referenceTrimmed
+                        ? referenceFields.slice(0, maxReferenceFields)
+                        : referenceFields,
+                },
+                resolvedReferences: binding.resolvedReferences.length > (maxReferenceFields || 0)
+                    ? binding.resolvedReferences.slice(0, maxReferenceFields)
+                    : binding.resolvedReferences,
+            };
+        });
+    }
+    const truncated = omittedCount > 0;
+    const evidence_meta = {
+        truncated,
+        omitted_count: omittedCount,
+        ...(truncated ? { next_fetch_hint: 'Rerun with unity_evidence_mode=full to fetch complete evidence.' } : {}),
+        ...(filterExhausted ? { filter_exhausted: true } : {}),
+        minimum_evidence_satisfied: !truncated && filtered.length > 0,
+        verifier_minimum_evidence_satisfied: filtered.length > 0,
+    };
+    return {
+        resourceBindings: filtered,
+        serializedFields: aggregateSerializedFields(filtered),
+        evidence_meta,
+        filter_diagnostics: diagnostics,
+    };
+}

package/dist/mcp/local/unity-evidence-view.test.d.ts

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

package/dist/mcp/local/unity-evidence-view.test.js

@@ -0,0 +1,39 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { buildUnityEvidenceView } from './unity-evidence-view.js';
+test('unity evidence view emits truncation metadata and fetch hint', () => {
+    const out = buildUnityEvidenceView({
+        resourceBindings: [
+            {
+                resourcePath: 'Assets/A.prefab',
+                resourceType: 'prefab',
+                bindingKind: 'direct',
+                componentObjectId: '1',
+                evidence: { line: 1, lineText: 'x' },
+                serializedFields: {
+                    scalarFields: [],
+                    referenceFields: [
+                        { name: 'r1', sourceLayer: 'base' },
+                        { name: 'r2', sourceLayer: 'base' },
+                    ],
+                },
+                resolvedReferences: [],
+            },
+            {
+                resourcePath: 'Assets/B.prefab',
+                resourceType: 'prefab',
+                bindingKind: 'direct',
+                componentObjectId: '2',
+                evidence: { line: 2, lineText: 'y' },
+                serializedFields: { scalarFields: [], referenceFields: [] },
+                resolvedReferences: [],
+            },
+        ],
+        mode: 'summary',
+        maxBindings: 1,
+        maxReferenceFields: 1,
+    });
+    assert.equal(out.evidence_meta.truncated, true);
+    assert.ok(out.evidence_meta.omitted_count > 0);
+    assert.match(out.evidence_meta.next_fetch_hint || '', /unity_evidence_mode=full/i);
+});

package/dist/mcp/local/unity-lazy-hydrator.d.ts

@@ -1,8 +1,8 @@
 import type { ResolvedUnityBinding } from '../../core/unity/resolver.js';
-import type { UnityLazyConfig } from './unity-lazy-config.js';
+import type { UnityConfig } from '../../core/config/unity-config.js';
 export interface HydrateLazyBindingsInput {
     pendingPaths: string[];
-    config: UnityLazyConfig;
+    config: Pick<UnityConfig, 'lazyMaxPaths' | 'lazyBatchSize' | 'lazyMaxMs'>;
     resolveBatch: (paths: string[]) => Promise<Map<string, ResolvedUnityBinding[]>>;
     dedupeKey?: string;
 }

package/dist/mcp/local/unity-lazy-hydrator.js

@@ -14,14 +14,14 @@ export async function hydrateLazyBindings(input) {
     return pending;
 }
 async function runHydration(input) {
-    const pending = input.pendingPaths.slice(0, Math.max(0, input.config.maxPendingPathsPerRequest));
-    const batchSize = Math.max(1, input.config.batchSize);
+    const pending = input.pendingPaths.slice(0, Math.max(0, input.config.lazyMaxPaths));
+    const batchSize = Math.max(1, input.config.lazyBatchSize);
     const startedAt = Date.now();
     const resolvedByPath = new Map();
     let timedOut = false;
     const diagnostics = [];
     for (let i = 0; i < pending.length; i += batchSize) {
-        if (Date.now() - startedAt > input.config.maxHydrationMs) {
+        if (Date.now() - startedAt > input.config.lazyMaxMs) {
             timedOut = true;
             break;
         }

package/dist/mcp/local/unity-lazy-hydrator.test.js

@@ -5,7 +5,7 @@ test('hydrateLazyBindings processes pending paths in bounded chunks', async () =
     const calls = [];
     await hydrateLazyBindings({
         pendingPaths: ['a', 'b', 'c', 'd', 'e'],
-        config: { maxPendingPathsPerRequest: 4, batchSize: 2, maxHydrationMs: 5000 },
+        config: { lazyMaxPaths: 4, lazyBatchSize: 2, lazyMaxMs: 5000 },
         resolveBatch: async (paths) => {
             calls.push(paths);
             return new Map();
@@ -17,7 +17,7 @@ test('parallel requests dedupe same hydration work', async () => {
     let resolveCalls = 0;
     const sharedInput = {
         pendingPaths: ['Assets/A.prefab'],
-        config: { maxPendingPathsPerRequest: 10, batchSize: 5, maxHydrationMs: 5000 },
+        config: { lazyMaxPaths: 10, lazyBatchSize: 5, lazyMaxMs: 5000 },
         dedupeKey: 'symbol:door::Assets/A.prefab',
         resolveBatch: async (_paths) => {
             resolveCalls += 1;
@@ -34,7 +34,7 @@ test('parallel requests dedupe same hydration work', async () => {
 test('context lazy hydration returns partial results when budget exceeded and reports diagnostics', async () => {
     const out = await hydrateLazyBindings({
         pendingPaths: ['a', 'b', 'c', 'd'],
-        config: { maxPendingPathsPerRequest: 4, batchSize: 2, maxHydrationMs: 1 },
+        config: { lazyMaxPaths: 4, lazyBatchSize: 2, lazyMaxMs: 1 },
         resolveBatch: async (paths) => {
             await new Promise((resolve) => setTimeout(resolve, 5));
             return new Map(paths.map((p) => [p, []]));
@@ -46,7 +46,7 @@ test('context lazy hydration returns partial results when budget exceeded and re
 test('summary-only Unity analyze persistence still returns full bindings after lazy hydration', async () => {
     const out = await hydrateLazyBindings({
         pendingPaths: ['Assets/Doors/Door.prefab'],
-        config: { maxPendingPathsPerRequest: 10, batchSize: 5, maxHydrationMs: 5000 },
+        config: { lazyMaxPaths: 10, lazyBatchSize: 5, lazyMaxMs: 5000 },
         resolveBatch: async () => new Map([
             ['Assets/Doors/Door.prefab', [{
                         resourcePath: 'Assets/Doors/Door.prefab',

package/dist/mcp/local/unity-parity-cache.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
+import { resolveUnityConfig } from '../../core/config/unity-config.js';
 const PARITY_CACHE_DIRNAME = 'unity-parity-cache';
 const DEFAULT_MAX_PARITY_CACHE_ENTRIES = 500;
 function buildKey(symbolUid) {
@@ -66,12 +67,7 @@ function resolveMaxEntries(options) {
     if (Number.isFinite(options?.maxEntries) && Number(options?.maxEntries) > 0) {
         return Math.floor(Number(options?.maxEntries));
     }
-    const raw = String(process.env.GITNEXUS_UNITY_PARITY_CACHE_MAX_ENTRIES || '').trim();
-    const parsed = Number.parseInt(raw, 10);
-    if (Number.isFinite(parsed) && parsed > 0) {
-        return parsed;
-    }
-    return DEFAULT_MAX_PARITY_CACHE_ENTRIES;
+    return resolveUnityConfig().config.parityCacheMaxEntries ?? DEFAULT_MAX_PARITY_CACHE_ENTRIES;
 }
 function pruneOldestEntries(entries, maxEntries) {
     const rows = Object.entries(entries);

package/dist/mcp/local/unity-parity-seed-loader.d.ts

@@ -1,6 +1,7 @@
 import type { UnityParitySeed } from '../../core/ingestion/unity-parity-seed.js';
 interface LoadUnityParitySeedOptions {
     indexedCommit?: string;
+    idleMsOverride?: number;
 }
 export declare function loadUnityParitySeed(storagePath: string, options?: LoadUnityParitySeedOptions): Promise<UnityParitySeed | null>;
 export declare function __resetUnityParitySeedLoaderCacheForTest(): void;

package/dist/mcp/local/unity-parity-seed-loader.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { resolveUnityConfig } from '../../core/config/unity-config.js';
 const SEED_FILENAME = 'unity-parity-seed.json';
 const DEFAULT_IDLE_MS = 30_000;
 const DEFAULT_MAX_ENTRIES = 2;
@@ -32,7 +33,7 @@ export async function loadUnityParitySeed(storagePath, options) {
             throw error;
         }
         const parsed = parseSeed(raw);
-        setCacheEntry(cacheKey, parsed);
+        setCacheEntry(cacheKey, parsed, options?.idleMsOverride);
         return parsed;
     })().finally(() => {
         inFlightLoads.delete(cacheKey);
@@ -69,7 +70,7 @@ async function buildSeedCacheKey(seedPath, storagePath, indexedCommit) {
         throw error;
     }
 }
-function setCacheEntry(cacheKey, value) {
+function setCacheEntry(cacheKey, value, idleMsOverride) {
     const now = Date.now();
     const existing = seedCache.get(cacheKey);
     if (existing?.idleTimer) {
@@ -78,9 +79,10 @@ function setCacheEntry(cacheKey, value) {
     const entry = {
         value,
         lastAccessMs: now,
+        idleMsOverride,
     };
     seedCache.set(cacheKey, entry);
-    scheduleEviction(cacheKey, entry);
+    scheduleEviction(cacheKey, entry, idleMsOverride);
     pruneOldestEntries(resolveMaxEntries());
 }
 function touchCacheEntry(cacheKey, entry) {
@@ -88,10 +90,10 @@ function touchCacheEntry(cacheKey, entry) {
     if (entry.idleTimer) {
         clearTimeout(entry.idleTimer);
     }
-    scheduleEviction(cacheKey, entry);
+    scheduleEviction(cacheKey, entry, entry.idleMsOverride);
 }
-function scheduleEviction(cacheKey, entry) {
-    const idleMs = resolveIdleMs();
+function scheduleEviction(cacheKey, entry, idleMsOverride) {
+    const idleMs = idleMsOverride ?? resolveIdleMs();
     entry.idleTimer = setTimeout(() => {
         const current = seedCache.get(cacheKey);
         if (!current || current !== entry) {
@@ -116,18 +118,10 @@ function pruneOldestEntries(maxEntries) {
     }
 }
 function resolveIdleMs() {
-    const parsed = Number.parseInt(String(process.env.GITNEXUS_UNITY_PARITY_SEED_CACHE_IDLE_MS || '').trim(), 10);
-    if (Number.isFinite(parsed) && parsed > 0) {
-        return parsed;
-    }
-    return DEFAULT_IDLE_MS;
+    return resolveUnityConfig().config.paritySeedCacheIdleMs ?? DEFAULT_IDLE_MS;
 }
 function resolveMaxEntries() {
-    const parsed = Number.parseInt(String(process.env.GITNEXUS_UNITY_PARITY_SEED_CACHE_MAX_ENTRIES || '').trim(), 10);
-    if (Number.isFinite(parsed) && parsed > 0) {
-        return parsed;
-    }
-    return DEFAULT_MAX_ENTRIES;
+    return resolveUnityConfig().config.paritySeedCacheMaxEntries ?? DEFAULT_MAX_ENTRIES;
 }
 export function __resetUnityParitySeedLoaderCacheForTest() {
     for (const entry of seedCache.values()) {

package/dist/mcp/local/unity-parity-seed-loader.test.js

@@ -54,9 +54,6 @@ test('loadUnityParitySeed deduplicates concurrent requests for same storage key'
 });
 test('loadUnityParitySeed evicts idle cache entry after ttl', async (t) => {
     const storagePath = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-seed-loader-'));
-    const idleEnvKey = 'GITNEXUS_UNITY_PARITY_SEED_CACHE_IDLE_MS';
-    const previousIdle = process.env[idleEnvKey];
-    process.env[idleEnvKey] = '15';
     try {
         await writeSeed(storagePath, 'IdleSymbol');
         const readFileOriginal = fs.readFile.bind(fs);
@@ -65,21 +62,15 @@ test('loadUnityParitySeed evicts idle cache entry after ttl', async (t) => {
             readFileCalls += 1;
             return readFileOriginal(...args);
         });
-        await loadUnityParitySeed(storagePath);
-        await loadUnityParitySeed(storagePath);
+        await loadUnityParitySeed(storagePath, { idleMsOverride: 15 });
+        await loadUnityParitySeed(storagePath, { idleMsOverride: 15 });
         assert.equal(readFileCalls, 1);
         await new Promise((resolve) => setTimeout(resolve, 30));
-        await loadUnityParitySeed(storagePath);
+        await loadUnityParitySeed(storagePath, { idleMsOverride: 15 });
         assert.equal(readFileCalls, 2);
     }
     finally {
         __resetUnityParitySeedLoaderCacheForTest();
-        if (previousIdle === undefined) {
-            delete process.env[idleEnvKey];
-        }
-        else {
-            process.env[idleEnvKey] = previousIdle;
-        }
         await fs.rm(storagePath, { recursive: true, force: true });
     }
 });

package/dist/mcp/local/unity-runtime-hydration.d.ts

@@ -2,7 +2,7 @@ import { buildUnityScanContext, buildUnityScanContextFromSeed } from '../../core
 import { resolveUnityBindings, type ResolvedUnityBinding } from '../../core/unity/resolver.js';
 import type { UnityHydrationMode } from '../../core/unity/options.js';
 import { type UnityContextPayload, type UnityHydrationMeta } from './unity-enrichment.js';
-import { resolveUnityLazyConfig } from './unity-lazy-config.js';
+import { resolveUnityConfig } from '../../core/config/unity-config.js';
 import { hydrateLazyBindings, type HydrateLazyBindingsInput } from './unity-lazy-hydrator.js';
 import { readUnityOverlayBindings, upsertUnityOverlayBindings } from './unity-lazy-overlay.js';
 import { readUnityParityCache, upsertUnityParityCache } from './unity-parity-cache.js';
@@ -28,7 +28,7 @@ export interface HydrateUnityInput {
 interface HydrationRuntime {
     now: () => number;
     queue: ParityWarmupQueue;
-    resolveLazyConfig: typeof resolveUnityLazyConfig;
+    resolveLazyConfig: () => Pick<ReturnType<typeof resolveUnityConfig>['config'], 'lazyMaxPaths' | 'lazyBatchSize' | 'lazyMaxMs'>;
     hydrateLazyBindings: (input: HydrateLazyBindingsInput) => ReturnType<typeof hydrateLazyBindings>;
     readOverlayBindings: typeof readUnityOverlayBindings;
     upsertOverlayBindings: typeof upsertUnityOverlayBindings;
@@ -45,6 +45,7 @@ export declare function mergeParityUnityBindings(baseNonLightweightBindings: Res
 export declare function attachUnityHydrationMeta(payload: UnityContextPayload, input: Pick<UnityHydrationMeta, 'requestedMode' | 'effectiveMode' | 'elapsedMs' | 'fallbackToCompact'> & {
     hasExpandableBindings: boolean;
 }): UnityContextPayload;
+export declare function buildMissingEvidenceFromHydrationMeta(meta?: UnityHydrationMeta): string[];
 export declare function hydrateUnityForSymbol(input: HydrateUnityInput): Promise<UnityContextPayload>;
 export declare function __resetUnityRuntimeHydrationStateForTest(): void;
 export {};

package/dist/mcp/local/unity-runtime-hydration.js

@@ -1,7 +1,7 @@
 import { buildUnityScanContext, buildUnityScanContextFromSeed } from '../../core/unity/scan-context.js';
 import { resolveUnityBindings } from '../../core/unity/resolver.js';
 import { formatLazyHydrationBudgetDiagnostic, } from './unity-enrichment.js';
-import { resolveUnityLazyConfig } from './unity-lazy-config.js';
+import { resolveUnityConfig } from '../../core/config/unity-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';
@@ -9,16 +9,8 @@ import { createParityWarmupQueue } from './unity-parity-warmup-queue.js';
 import { loadUnityParitySeed } from './unity-parity-seed-loader.js';
 const inFlightParityHydration = new Map();
 const parityWarmupQueue = createParityWarmupQueue({
-    maxParallel: resolveParityWarmupMaxParallel(process.env),
+    maxParallel: resolveUnityConfig().config.parityWarmupMaxParallel ?? 2,
 });
-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;
-}
 function normalizePath(filePath) {
     return String(filePath || '').replace(/\\/g, '/');
 }
@@ -92,6 +84,12 @@ export function attachUnityHydrationMeta(payload, input) {
         },
     };
 }
+export function buildMissingEvidenceFromHydrationMeta(meta) {
+    if (!meta || meta.isComplete) {
+        return [];
+    }
+    return [...new Set((meta.completenessReason || []).map((value) => String(value || '').trim()).filter(Boolean))];
+}
 export async function hydrateUnityForSymbol(input) {
     const runtime = resolveRuntime(input.runtime);
     const startedAt = runtime.now();
@@ -122,7 +120,7 @@ function resolveRuntime(overrides) {
     return {
         now: () => Date.now(),
         queue: parityWarmupQueue,
-        resolveLazyConfig: resolveUnityLazyConfig,
+        resolveLazyConfig: () => resolveUnityConfig().config,
         hydrateLazyBindings,
         readOverlayBindings: readUnityOverlayBindings,
         upsertOverlayBindings: upsertUnityOverlayBindings,
@@ -153,9 +151,8 @@ function scheduleParityWarmup(input, runtime) {
         .then(() => undefined)
         .catch(() => undefined);
 }
-function shouldEnableWarmup(env) {
-    const raw = String(env.GITNEXUS_UNITY_PARITY_WARMUP || '').trim().toLowerCase();
-    return raw === '1' || raw === 'true' || raw === 'on';
+function shouldEnableWarmup(_env) {
+    return resolveUnityConfig().config.parityWarmup ?? false;
 }
 async function getOrRunParityHydration(input, runtime) {
     const key = buildParityWarmupKey(input);
@@ -256,7 +253,7 @@ async function runCompactHydration(input, runtime) {
     const unityDiagnostics = [...input.basePayload.unityDiagnostics];
     if (pendingPaths.length > 0) {
         try {
-            const cfg = runtime.resolveLazyConfig(process.env);
+            const cfg = runtime.resolveLazyConfig();
             const hydration = await runtime.hydrateLazyBindings({
                 pendingPaths,
                 config: cfg,
@@ -315,7 +312,7 @@ function toUnityContextPayload(resourceBindings, unityDiagnostics) {
             scalarFields: resourceBindings.flatMap((binding) => binding.serializedFields.scalarFields),
             referenceFields: resourceBindings.flatMap((binding) => binding.serializedFields.referenceFields),
         },
-        unityDiagnostics,
+        unityDiagnostics: [...new Set(unityDiagnostics)],
     };
 }
 export function __resetUnityRuntimeHydrationStateForTest() {

package/dist/mcp/local/unity-runtime-hydration.test.js

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { hydrateUnityForSymbol } from './unity-runtime-hydration.js';
+import { buildMissingEvidenceFromHydrationMeta, hydrateUnityForSymbol } from './unity-runtime-hydration.js';
 test('hydrateUnityForSymbol(compact) marks needsParityRetry when lightweight bindings remain', async () => {
     const out = await hydrateUnityForSymbol({
         mode: 'compact',
@@ -106,3 +106,17 @@ test('hydrateUnityForSymbol(parity) sets isComplete=true on parity success', asy
     assert.equal(out.hydrationMeta?.effectiveMode, 'parity');
     assert.equal(out.hydrationMeta?.isComplete, true);
 });
+test('buildMissingEvidenceFromHydrationMeta maps incomplete reasons', () => {
+    const missing = buildMissingEvidenceFromHydrationMeta({
+        requestedMode: 'compact',
+        effectiveMode: 'compact',
+        elapsedMs: 1,
+        fallbackToCompact: false,
+        resourceBindingCount: 1,
+        unityDiagnosticsCount: 0,
+        isComplete: false,
+        completenessReason: ['lightweight_bindings_remaining', 'budget_exceeded'],
+        needsParityRetry: true,
+    });
+    assert.deepEqual(missing, ['lightweight_bindings_remaining', 'budget_exceeded']);
+});

package/dist/mcp/resources.js

@@ -4,6 +4,7 @@
  * Provides structured on-demand data to AI agents.
  * All resources use repo-scoped URIs: gitnexus://repo/{name}/context
  */
+import { getDerivedProcessDetailResource } from './local/derived-process-reader.js';
 import { checkStaleness } from './staleness.js';
 import { loadCLIConfig } from '../storage/repo-manager.js';
 import { buildNpxCommand, resolveCliSpec } from '../config/cli-spec.js';
@@ -67,6 +68,12 @@ export function getResourceTemplates() {
             description: 'Step-by-step execution trace with lifecycle subtype and step evidence when available',
             mimeType: 'text/yaml',
         },
+        {
+            uriTemplate: 'gitnexus://repo/{name}/derived-process/{id}',
+            name: 'Derived Process Trace',
+            description: 'Readable trace metadata for derived process references',
+            mimeType: 'text/yaml',
+        },
     ];
 }
 /**
@@ -88,6 +95,9 @@ function parseUri(uri) {
         if (rest.startsWith('process/')) {
             return { repoName, resourceType: 'process', param: decodeURIComponent(rest.replace('process/', '')) };
         }
+        if (rest.startsWith('derived-process/')) {
+            return { repoName, resourceType: 'derived-process', param: decodeURIComponent(rest.replace('derived-process/', '')) };
+        }
         return { repoName, resourceType: rest };
     }
     throw new Error(`Unknown resource URI: ${uri}`);
@@ -119,6 +129,8 @@ export async function readResource(uri, backend) {
             return getClusterDetailResource(parsed.param, backend, repoName);
         case 'process':
             return getProcessDetailResource(parsed.param, backend, repoName);
+        case 'derived-process':
+            return getDerivedProcessDetailResource(parsed.param, backend, repoName);
         default:
             throw new Error(`Unknown resource: ${uri}`);
     }
@@ -202,6 +214,7 @@ async function getContextResource(backend, repoName) {
     lines.push(`  - gitnexus://repo/${context.projectName}/processes: All execution flows`);
     lines.push(`  - gitnexus://repo/${context.projectName}/cluster/{name}: Module details`);
     lines.push(`  - gitnexus://repo/${context.projectName}/process/{name}: Process trace`);
+    lines.push(`  - gitnexus://repo/${context.projectName}/derived-process/{id}: Derived process trace metadata`);
     return lines.join('\n');
 }
 /**