@veewo/gitnexus 1.3.10 → 1.3.11

package/dist/mcp/local/unity-enrichment.js

@@ -2,30 +2,65 @@ import { extractAssetRefPathReferences } from '../../core/unity/resolver.js';
 export async function loadUnityContext(_repoId, symbolId, execute) {
     const escapedSymbolId = symbolId.replace(/'/g, "''");
     const rows = await execute(`
-    MATCH (symbol {id: '${escapedSymbolId}'})-[r:CodeRelation]->(component:CodeElement)
-    WHERE r.type IN ['UNITY_COMPONENT_INSTANCE', 'UNITY_SERIALIZED_TYPE_IN']
-    RETURN component.filePath AS resourcePath, component.description AS payload, r.type AS relationType, r.reason AS relationReason
-    ORDER BY component.filePath, component.id
+    MATCH (symbol {id: '${escapedSymbolId}'})-[r:CodeRelation]->(target)
+    WHERE r.type IN ['UNITY_COMPONENT_INSTANCE', 'UNITY_SERIALIZED_TYPE_IN', 'UNITY_RESOURCE_SUMMARY']
+    RETURN target.filePath AS resourcePath,
+      CASE WHEN r.type = 'UNITY_RESOURCE_SUMMARY' THEN '' ELSE target.description END AS payload,
+      r.type AS relationType,
+      r.reason AS relationReason
+    ORDER BY target.filePath, target.id
   `);
     return projectUnityBindings(rows);
 }
+export function formatLazyHydrationBudgetDiagnostic(elapsedMs) {
+    return `lazy-expand budget exceeded after ${elapsedMs}ms`;
+}
 export function projectUnityBindings(rows) {
     const resourceBindings = [];
     const scalarFields = [];
     const referenceFields = [];
     const unityDiagnostics = [];
     for (const row of rows) {
+        const relationType = String(row?.relationType || '');
+        const relationReason = String(row?.relationReason || '');
+        const resourcePath = row?.resourcePath || row?.[0] || '';
         const rawPayload = row?.payload ?? row?.description ?? row?.[1];
+        if (relationType === 'UNITY_RESOURCE_SUMMARY') {
+            const summary = parseUnityResourceSummaryReason(relationReason);
+            const bindingKinds = summary.bindingKinds.length > 0
+                ? summary.bindingKinds
+                : ['direct'];
+            const resourceType = summary.resourceType || inferResourceType(resourcePath);
+            for (const bindingKind of bindingKinds) {
+                resourceBindings.push({
+                    resourcePath,
+                    resourceType,
+                    bindingKind,
+                    componentObjectId: 'summary',
+                    lightweight: summary.lightweight,
+                    evidence: buildSyntheticEvidence(row),
+                    serializedFields: { scalarFields: [], referenceFields: [] },
+                    resolvedReferences: [],
+                    assetRefPaths: [],
+                });
+            }
+            continue;
+        }
         if (typeof rawPayload !== 'string' || rawPayload.length === 0) {
             continue;
         }
         try {
             const parsed = JSON.parse(rawPayload);
+            const lightweight = Boolean(parsed.lightweight)
+                || (String(parsed.componentObjectId || '').startsWith('line-')
+                    && ((parsed.serializedFields?.scalarFields?.length || 0) === 0)
+                    && ((parsed.serializedFields?.referenceFields?.length || 0) === 0));
             const binding = {
-                resourcePath: parsed.resourcePath || row?.resourcePath || row?.[0] || '',
+                resourcePath: parsed.resourcePath || resourcePath,
                 resourceType: parsed.resourceType || inferResourceType(parsed.resourcePath || row?.resourcePath || row?.[0] || ''),
                 bindingKind: parsed.bindingKind || 'direct',
                 componentObjectId: parsed.componentObjectId || '',
+                lightweight,
                 evidence: parsed.evidence || buildSyntheticEvidence(row),
                 serializedFields: parsed.serializedFields || { scalarFields: [], referenceFields: [] },
                 resolvedReferences: parsed.resolvedReferences || [],
@@ -48,6 +83,35 @@ export function projectUnityBindings(rows) {
         unityDiagnostics,
     };
 }
+function parseUnityResourceSummaryReason(input) {
+    const fallback = {
+        resourceType: 'scene',
+        bindingKinds: [],
+        lightweight: true,
+    };
+    if (!input)
+        return fallback;
+    try {
+        const parsed = JSON.parse(input);
+        const bindingKinds = Array.isArray(parsed.bindingKinds)
+            ? parsed.bindingKinds
+                .map((value) => String(value || '').trim())
+                .filter((value) => (value === 'direct'
+                || value === 'prefab-instance'
+                || value === 'nested'
+                || value === 'variant'
+                || value === 'scene-override'))
+            : [];
+        return {
+            resourceType: parsed.resourceType || fallback.resourceType,
+            bindingKinds,
+            lightweight: true,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
 function inferResourceType(resourcePath) {
     if (resourcePath.endsWith('.prefab'))
         return 'prefab';

package/dist/mcp/local/unity-enrichment.test.js

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { loadUnityContext, projectUnityBindings } from './unity-enrichment.js';
+import { formatLazyHydrationBudgetDiagnostic, loadUnityContext, projectUnityBindings } from './unity-enrichment.js';
 test('projectUnityBindings restores graph-native Unity payload rows', () => {
     const out = projectUnityBindings([
         {
@@ -128,3 +128,71 @@ _actorPrefabRef:
     assert.equal(refs[1]?.fieldName, '_actorPrefabRef');
     assert.equal(refs[1]?.isSprite, false);
 });
+test('projectUnityBindings preserves lightweight marker from payload', () => {
+    const out = projectUnityBindings([
+        {
+            resourcePath: 'Assets/Scene/LargeScene.unity',
+            payload: JSON.stringify({
+                resourcePath: 'Assets/Scene/LargeScene.unity',
+                resourceType: 'scene',
+                bindingKind: 'direct',
+                componentObjectId: 'line-200',
+                lightweight: true,
+                serializedFields: { scalarFields: [], referenceFields: [] },
+            }),
+        },
+    ]);
+    assert.equal(out.resourceBindings.length, 1);
+    assert.equal(out.resourceBindings[0]?.lightweight, true);
+});
+test('projectUnityBindings infers lightweight marker from legacy line-* component id', () => {
+    const out = projectUnityBindings([
+        {
+            resourcePath: 'Assets/Scene/LargeScene.unity',
+            payload: JSON.stringify({
+                resourcePath: 'Assets/Scene/LargeScene.unity',
+                resourceType: 'scene',
+                bindingKind: 'direct',
+                componentObjectId: 'line-54558',
+                serializedFields: { scalarFields: [], referenceFields: [] },
+                resolvedReferences: [],
+            }),
+        },
+    ]);
+    assert.equal(out.resourceBindings.length, 1);
+    assert.equal(out.resourceBindings[0]?.lightweight, true);
+});
+test('projectUnityBindings restores compact component payload rows without embedded resourcePath', () => {
+    const out = projectUnityBindings([
+        {
+            resourcePath: 'Assets/A.prefab',
+            payload: JSON.stringify({
+                bindingKind: 'direct',
+                componentObjectId: '114',
+                serializedFields: { scalarFields: [], referenceFields: [] },
+            }),
+        },
+    ]);
+    assert.equal(out.resourceBindings.length, 1);
+    assert.equal(out.resourceBindings[0]?.resourcePath, 'Assets/A.prefab');
+    assert.equal(out.resourceBindings[0]?.bindingKind, 'direct');
+    assert.deepEqual(out.unityDiagnostics, []);
+});
+test('loadUnityContext can project UNITY_RESOURCE_SUMMARY rows before hydration', async () => {
+    const out = await loadUnityContext('repo-id', 'Class:Assets/Scripts/DoorObj.cs:DoorObj', async () => [
+        {
+            relationType: 'UNITY_RESOURCE_SUMMARY',
+            relationReason: JSON.stringify({ resourceType: 'prefab', bindingKinds: ['direct'], lightweight: true }),
+            resourcePath: 'Assets/Doors/Door.prefab',
+            payload: '',
+        },
+    ]);
+    assert.equal(out.resourceBindings.length, 1);
+    assert.equal(out.resourceBindings[0]?.resourcePath, 'Assets/Doors/Door.prefab');
+    assert.equal(out.resourceBindings[0]?.lightweight, true);
+});
+test('formatLazyHydrationBudgetDiagnostic returns stable budget warning', () => {
+    const message = formatLazyHydrationBudgetDiagnostic(17);
+    assert.match(message, /budget exceeded/i);
+    assert.match(message, /17ms/);
+});

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

@@ -0,0 +1,6 @@
+export interface UnityLazyConfig {
+    maxPendingPathsPerRequest: number;
+    batchSize: number;
+    maxHydrationMs: number;
+}
+export declare function resolveUnityLazyConfig(env: NodeJS.ProcessEnv): UnityLazyConfig;

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

@@ -0,0 +1,7 @@
+export function resolveUnityLazyConfig(env) {
+    return {
+        maxPendingPathsPerRequest: Number(env.GITNEXUS_UNITY_LAZY_MAX_PATHS || 120),
+        batchSize: Number(env.GITNEXUS_UNITY_LAZY_BATCH_SIZE || 30),
+        maxHydrationMs: Number(env.GITNEXUS_UNITY_LAZY_MAX_MS || 5000),
+    };
+}

package/dist/mcp/local/unity-lazy-config.test.d.ts

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

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

@@ -0,0 +1,9 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveUnityLazyConfig } from './unity-lazy-config.js';
+test('resolveUnityLazyConfig provides safe defaults', () => {
+    const cfg = resolveUnityLazyConfig({});
+    assert.equal(cfg.maxPendingPathsPerRequest, 120);
+    assert.equal(cfg.batchSize, 30);
+    assert.equal(cfg.maxHydrationMs, 5000);
+});

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

@@ -0,0 +1,15 @@
+import type { ResolvedUnityBinding } from '../../core/unity/resolver.js';
+import type { UnityLazyConfig } from './unity-lazy-config.js';
+export interface HydrateLazyBindingsInput {
+    pendingPaths: string[];
+    config: UnityLazyConfig;
+    resolveBatch: (paths: string[]) => Promise<Map<string, ResolvedUnityBinding[]>>;
+    dedupeKey?: string;
+}
+export interface HydrateLazyBindingsOutput {
+    resolvedByPath: Map<string, ResolvedUnityBinding[]>;
+    timedOut: boolean;
+    elapsedMs: number;
+    diagnostics: string[];
+}
+export declare function hydrateLazyBindings(input: HydrateLazyBindingsInput): Promise<HydrateLazyBindingsOutput>;

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

@@ -0,0 +1,43 @@
+const inFlightHydration = new Map();
+export async function hydrateLazyBindings(input) {
+    if (!input.dedupeKey) {
+        return runHydration(input);
+    }
+    const existing = inFlightHydration.get(input.dedupeKey);
+    if (existing) {
+        return existing;
+    }
+    const pending = runHydration(input).finally(() => {
+        inFlightHydration.delete(input.dedupeKey);
+    });
+    inFlightHydration.set(input.dedupeKey, pending);
+    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 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) {
+            timedOut = true;
+            break;
+        }
+        const chunk = pending.slice(i, i + batchSize);
+        const resolved = await input.resolveBatch(chunk);
+        for (const [resourcePath, bindings] of resolved.entries()) {
+            resolvedByPath.set(resourcePath, bindings);
+        }
+    }
+    if (timedOut) {
+        diagnostics.push(`lazy-expand budget exceeded after ${Date.now() - startedAt}ms`);
+    }
+    return {
+        resolvedByPath,
+        timedOut,
+        elapsedMs: Date.now() - startedAt,
+        diagnostics,
+    };
+}

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

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

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

@@ -0,0 +1,66 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { hydrateLazyBindings } from './unity-lazy-hydrator.js';
+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 },
+        resolveBatch: async (paths) => {
+            calls.push(paths);
+            return new Map();
+        },
+    });
+    assert.deepEqual(calls, [['a', 'b'], ['c', 'd']]);
+});
+test('parallel requests dedupe same hydration work', async () => {
+    let resolveCalls = 0;
+    const sharedInput = {
+        pendingPaths: ['Assets/A.prefab'],
+        config: { maxPendingPathsPerRequest: 10, batchSize: 5, maxHydrationMs: 5000 },
+        dedupeKey: 'symbol:door::Assets/A.prefab',
+        resolveBatch: async (_paths) => {
+            resolveCalls += 1;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+            return new Map();
+        },
+    };
+    await Promise.all([
+        hydrateLazyBindings(sharedInput),
+        hydrateLazyBindings(sharedInput),
+    ]);
+    assert.equal(resolveCalls, 1);
+});
+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 },
+        resolveBatch: async (paths) => {
+            await new Promise((resolve) => setTimeout(resolve, 5));
+            return new Map(paths.map((p) => [p, []]));
+        },
+    });
+    assert.equal(out.resolvedByPath.size, 2);
+    assert.match((out.diagnostics || []).join('\n'), /budget exceeded/i);
+});
+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 },
+        resolveBatch: async () => new Map([
+            ['Assets/Doors/Door.prefab', [{
+                        resourcePath: 'Assets/Doors/Door.prefab',
+                        resourceType: 'prefab',
+                        bindingKind: 'direct',
+                        componentObjectId: '114',
+                        serializedFields: {
+                            scalarFields: [{ name: 'Shows', value: '1', sourceLayer: 'prefab' }],
+                            referenceFields: [],
+                        },
+                        resolvedReferences: [],
+                        evidence: { line: 12, lineText: 'm_Script: ...' },
+                    }]],
+        ]),
+    });
+    assert.equal(out.resolvedByPath.get('Assets/Doors/Door.prefab')?.[0]?.serializedFields.scalarFields[0]?.name, 'Shows');
+});

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

@@ -0,0 +1,3 @@
+import type { ResolvedUnityBinding } from '../../core/unity/resolver.js';
+export declare function readUnityOverlayBindings(storagePath: string, indexedCommit: string, symbolUid: string, resourcePaths: string[]): Promise<Map<string, ResolvedUnityBinding[]>>;
+export declare function upsertUnityOverlayBindings(storagePath: string, indexedCommit: string, symbolUid: string, byResourcePath: Map<string, ResolvedUnityBinding[]>): Promise<void>;

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

@@ -0,0 +1,89 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+const OVERLAY_DIRNAME = 'unity-lazy-overlay';
+function buildKey(symbolUid, resourcePath) {
+    return `${symbolUid}::${resourcePath}`;
+}
+function shardKeyForEntry(symbolUid, resourcePath) {
+    const key = buildKey(symbolUid, resourcePath);
+    return createHash('sha1').update(key).digest('hex').slice(0, 2);
+}
+function getShardPath(storagePath, shardKey) {
+    return path.join(storagePath, OVERLAY_DIRNAME, `${shardKey}.json`);
+}
+async function readOverlayDocument(storagePath, indexedCommit, shardKey) {
+    const overlayPath = getShardPath(storagePath, shardKey);
+    try {
+        const raw = await fs.readFile(overlayPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || parsed.version !== 1 || !parsed.entries || typeof parsed.entries !== 'object') {
+            return { version: 1, indexedCommit, entries: {} };
+        }
+        if (parsed.indexedCommit !== indexedCommit) {
+            return { version: 1, indexedCommit, entries: {} };
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { version: 1, indexedCommit, entries: {} };
+        }
+        throw error;
+    }
+}
+async function writeOverlayDocument(storagePath, shardKey, doc) {
+    const overlayDir = path.join(storagePath, OVERLAY_DIRNAME);
+    const overlayPath = getShardPath(storagePath, shardKey);
+    const tmpPath = `${overlayPath}.tmp-${process.pid}-${Date.now()}`;
+    await fs.mkdir(overlayDir, { recursive: true });
+    await fs.writeFile(tmpPath, JSON.stringify(doc), 'utf-8');
+    await fs.rename(tmpPath, overlayPath);
+}
+export async function readUnityOverlayBindings(storagePath, indexedCommit, symbolUid, resourcePaths) {
+    const output = new Map();
+    const shardToPaths = new Map();
+    for (const resourcePath of resourcePaths) {
+        const shardKey = shardKeyForEntry(symbolUid, resourcePath);
+        const list = shardToPaths.get(shardKey) || [];
+        list.push(resourcePath);
+        shardToPaths.set(shardKey, list);
+    }
+    for (const [shardKey, paths] of shardToPaths.entries()) {
+        const doc = await readOverlayDocument(storagePath, indexedCommit, shardKey);
+        for (const resourcePath of paths) {
+            const key = buildKey(symbolUid, resourcePath);
+            const entry = doc.entries[key];
+            if (entry && Array.isArray(entry.bindings)) {
+                output.set(resourcePath, entry.bindings);
+            }
+        }
+    }
+    return output;
+}
+export async function upsertUnityOverlayBindings(storagePath, indexedCommit, symbolUid, byResourcePath) {
+    if (byResourcePath.size === 0) {
+        return;
+    }
+    const now = new Date().toISOString();
+    const shardToEntries = new Map();
+    for (const [resourcePath, bindings] of byResourcePath.entries()) {
+        const shardKey = shardKeyForEntry(symbolUid, resourcePath);
+        const rows = shardToEntries.get(shardKey) || [];
+        rows.push([resourcePath, bindings]);
+        shardToEntries.set(shardKey, rows);
+    }
+    for (const [shardKey, rows] of shardToEntries.entries()) {
+        const doc = await readOverlayDocument(storagePath, indexedCommit, shardKey);
+        for (const [resourcePath, bindings] of rows) {
+            const key = buildKey(symbolUid, resourcePath);
+            doc.entries[key] = {
+                symbolUid,
+                resourcePath,
+                bindings,
+                updatedAt: now,
+            };
+        }
+        await writeOverlayDocument(storagePath, shardKey, doc);
+    }
+}

package/dist/mcp/local/unity-lazy-overlay.test.d.ts

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

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

@@ -0,0 +1,83 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs/promises';
+import { readUnityOverlayBindings, upsertUnityOverlayBindings } from './unity-lazy-overlay.js';
+test('unity lazy overlay reads and writes by symbol/resource key', async () => {
+    const storagePath = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-unity-overlay-'));
+    try {
+        const before = await readUnityOverlayBindings(storagePath, 'abc123', 'Class:Foo', ['Assets/A.prefab']);
+        assert.equal(before.size, 0);
+        await upsertUnityOverlayBindings(storagePath, 'abc123', 'Class:Foo', new Map([
+            ['Assets/A.prefab', [{
+                        resourcePath: 'Assets/A.prefab',
+                        resourceType: 'prefab',
+                        bindingKind: 'direct',
+                        componentObjectId: '100',
+                        serializedFields: { scalarFields: [], referenceFields: [] },
+                        resolvedReferences: [],
+                        evidence: { line: 1, lineText: 'm_Script: ...' },
+                    }]],
+        ]));
+        const after = await readUnityOverlayBindings(storagePath, 'abc123', 'Class:Foo', ['Assets/A.prefab']);
+        assert.equal(after.size, 1);
+        assert.equal(after.get('Assets/A.prefab')?.[0]?.componentObjectId, '100');
+    }
+    finally {
+        await fs.rm(storagePath, { recursive: true, force: true });
+    }
+});
+test('unity lazy overlay invalidates entries on indexed commit change', async () => {
+    const storagePath = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-unity-overlay-'));
+    try {
+        await upsertUnityOverlayBindings(storagePath, 'old-commit', 'Class:Foo', new Map([
+            ['Assets/A.prefab', [{
+                        resourcePath: 'Assets/A.prefab',
+                        resourceType: 'prefab',
+                        bindingKind: 'direct',
+                        componentObjectId: '100',
+                        serializedFields: { scalarFields: [], referenceFields: [] },
+                        resolvedReferences: [],
+                        evidence: { line: 1, lineText: 'm_Script: ...' },
+                    }]],
+        ]));
+        const stale = await readUnityOverlayBindings(storagePath, 'new-commit', 'Class:Foo', ['Assets/A.prefab']);
+        assert.equal(stale.size, 0);
+    }
+    finally {
+        await fs.rm(storagePath, { recursive: true, force: true });
+    }
+});
+test('overlay persists entries in shard files and supports atomic replace', async () => {
+    const storagePath = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-unity-overlay-'));
+    try {
+        await upsertUnityOverlayBindings(storagePath, 'abc123', 'Class:Foo', new Map([
+            ['Assets/A.prefab', [{
+                        resourcePath: 'Assets/A.prefab',
+                        resourceType: 'prefab',
+                        bindingKind: 'direct',
+                        componentObjectId: '101',
+                        serializedFields: { scalarFields: [], referenceFields: [] },
+                        resolvedReferences: [],
+                        evidence: { line: 1, lineText: 'm_Script: ...' },
+                    }]],
+            ['Assets/B.prefab', [{
+                        resourcePath: 'Assets/B.prefab',
+                        resourceType: 'prefab',
+                        bindingKind: 'direct',
+                        componentObjectId: '102',
+                        serializedFields: { scalarFields: [], referenceFields: [] },
+                        resolvedReferences: [],
+                        evidence: { line: 1, lineText: 'm_Script: ...' },
+                    }]],
+        ]));
+        const shardsDir = path.join(storagePath, 'unity-lazy-overlay');
+        const shards = await fs.readdir(shardsDir);
+        assert.ok(shards.length > 0);
+        assert.ok(shards.every((name) => name.endsWith('.json')));
+    }
+    finally {
+        await fs.rm(storagePath, { recursive: true, force: true });
+    }
+});

package/dist/mcp/local/unity-parity-cache.d.ts

@@ -0,0 +1,7 @@
+import type { UnityContextPayload } from './unity-enrichment.js';
+interface UnityParityCacheOptions {
+    maxEntries?: number;
+}
+export declare function readUnityParityCache(storagePath: string, indexedCommit: string, symbolUid: string): Promise<UnityContextPayload | null>;
+export declare function upsertUnityParityCache(storagePath: string, indexedCommit: string, symbolUid: string, payload: UnityContextPayload, options?: UnityParityCacheOptions): Promise<void>;
+export {};

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

@@ -0,0 +1,88 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+const PARITY_CACHE_DIRNAME = 'unity-parity-cache';
+const DEFAULT_MAX_PARITY_CACHE_ENTRIES = 500;
+function buildKey(symbolUid) {
+    return symbolUid;
+}
+function shardKeyForEntry(symbolUid) {
+    return createHash('sha1').update(buildKey(symbolUid)).digest('hex').slice(0, 2);
+}
+function getShardPath(storagePath, shardKey) {
+    return path.join(storagePath, PARITY_CACHE_DIRNAME, `${shardKey}.json`);
+}
+async function readParityCacheDocument(storagePath, indexedCommit, shardKey) {
+    const cachePath = getShardPath(storagePath, shardKey);
+    try {
+        const raw = await fs.readFile(cachePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || parsed.version !== 1 || !parsed.entries || typeof parsed.entries !== 'object') {
+            return { version: 1, indexedCommit, entries: {} };
+        }
+        if (parsed.indexedCommit !== indexedCommit) {
+            return { version: 1, indexedCommit, entries: {} };
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { version: 1, indexedCommit, entries: {} };
+        }
+        throw error;
+    }
+}
+async function writeParityCacheDocument(storagePath, shardKey, doc) {
+    const cacheDir = path.join(storagePath, PARITY_CACHE_DIRNAME);
+    const cachePath = getShardPath(storagePath, shardKey);
+    const tmpPath = `${cachePath}.tmp-${process.pid}-${Date.now()}`;
+    await fs.mkdir(cacheDir, { recursive: true });
+    await fs.writeFile(tmpPath, JSON.stringify(doc), 'utf-8');
+    await fs.rename(tmpPath, cachePath);
+}
+export async function readUnityParityCache(storagePath, indexedCommit, symbolUid) {
+    const shardKey = shardKeyForEntry(symbolUid);
+    const doc = await readParityCacheDocument(storagePath, indexedCommit, shardKey);
+    const key = buildKey(symbolUid);
+    const entry = doc.entries[key];
+    if (!entry || !entry.payload) {
+        return null;
+    }
+    return entry.payload;
+}
+export async function upsertUnityParityCache(storagePath, indexedCommit, symbolUid, payload, options) {
+    const shardKey = shardKeyForEntry(symbolUid);
+    const doc = await readParityCacheDocument(storagePath, indexedCommit, shardKey);
+    const key = buildKey(symbolUid);
+    doc.entries[key] = {
+        symbolUid,
+        payload,
+        updatedAt: new Date().toISOString(),
+    };
+    doc.entries = pruneOldestEntries(doc.entries, resolveMaxEntries(options));
+    await writeParityCacheDocument(storagePath, shardKey, doc);
+}
+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;
+}
+function pruneOldestEntries(entries, maxEntries) {
+    const rows = Object.entries(entries);
+    if (rows.length <= maxEntries) {
+        return entries;
+    }
+    rows.sort(([, a], [, b]) => toMillis(a.updatedAt) - toMillis(b.updatedAt));
+    const keep = rows.slice(rows.length - maxEntries);
+    return Object.fromEntries(keep);
+}
+function toMillis(updatedAt) {
+    const ts = Date.parse(updatedAt);
+    return Number.isFinite(ts) ? ts : 0;
+}

package/dist/mcp/local/unity-parity-cache.test.d.ts

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