@veewo/gitnexus 1.3.9 → 1.3.11-rc.1

package/dist/benchmark/analyze-memory-sampler.d.ts

@@ -0,0 +1,10 @@
+export declare function buildAnalyzeMemoryReport(input: any): {
+    capturedAt: string;
+    summary: {
+        analyzeRealSec: any;
+        analyzeMaxRssBytes: any;
+        coldResourceBindings: any;
+        warmResourceBindings: any;
+    };
+    input: any;
+};

package/dist/benchmark/analyze-memory-sampler.js

@@ -0,0 +1,12 @@
+export function buildAnalyzeMemoryReport(input) {
+    return {
+        capturedAt: new Date().toISOString(),
+        summary: {
+            analyzeRealSec: input.analyze.realSec,
+            analyzeMaxRssBytes: input.analyze.maxRssBytes,
+            coldResourceBindings: input.queryCold.resourceBindings,
+            warmResourceBindings: input.queryWarm.resourceBindings,
+        },
+        input,
+    };
+}

package/dist/benchmark/analyze-memory-sampler.test.js

@@ -0,0 +1,12 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { buildAnalyzeMemoryReport } from './analyze-memory-sampler.js';
+test('buildAnalyzeMemoryReport summarizes analyze and query measurements', () => {
+    const report = buildAnalyzeMemoryReport({
+        analyze: { realSec: 10, maxRssBytes: 1024, phases: { pipelineSec: 3, kuzuSec: 5, ftsSec: 1 } },
+        queryCold: { realSec: 2, maxRssBytes: 512, resourceBindings: 4, unityDiagnostics: [] },
+        queryWarm: { realSec: 1, maxRssBytes: 256, resourceBindings: 4, unityDiagnostics: [] },
+    });
+    assert.equal(report.summary.analyzeRealSec, 10);
+    assert.equal(report.summary.coldResourceBindings, 4);
+});

package/dist/benchmark/io.test.js

@@ -1,9 +1,14 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import path from 'node:path';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { loadBenchmarkDataset } from './io.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(here, '../..');
 test('loadBenchmarkDataset parses thresholds and jsonl rows', async () => {
-    const root = path.resolve('../benchmarks/unity-baseline/v1');
+    const root = path.resolve(projectRoot, '../benchmarks/unity-baseline/v1');
     const ds = await loadBenchmarkDataset(root);
     assert.equal(typeof ds.thresholds.query.precisionMin, 'number');
     assert.ok(ds.symbols.length > 0);
@@ -11,11 +16,41 @@ test('loadBenchmarkDataset parses thresholds and jsonl rows', async () => {
     assert.ok(ds.tasks.length > 0);
 });
 test('loadBenchmarkDataset rejects missing required fields', async () => {
-    const badRoot = path.resolve('src/benchmark/__fixtures__/bad-dataset');
-    await assert.rejects(() => loadBenchmarkDataset(badRoot), /missing required field/i);
+    const badRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-bad-dataset-'));
+    try {
+        await fs.writeFile(path.join(badRoot, 'thresholds.json'), JSON.stringify({
+            query: { precisionMin: 0.7, recallMin: 0.7, avgLatencyMsMax: 200, p95LatencyMsMax: 400 },
+            context: { coverageMin: 0.7, latencyMsMax: 400 },
+            impact: { recallMin: 0.7, avgLatencyMsMax: 400 },
+        }), 'utf-8');
+        await fs.writeFile(path.join(badRoot, 'symbols.jsonl'), `${JSON.stringify({
+            symbol_uid: 'Class:Foo',
+            file_path: 'Assets/Foo.cs',
+            symbol_name: 'Foo',
+            symbol_type: 'Class',
+            start_line: 1,
+            end_line: 10,
+        })}\n`, 'utf-8');
+        await fs.writeFile(path.join(badRoot, 'relations.jsonl'), `${JSON.stringify({
+            src_uid: 'Class:Foo',
+            edge_type: 'CALLS',
+            dst_uid: 'Method:Bar',
+            must_exist: true,
+        })}\n`, 'utf-8');
+        await fs.writeFile(path.join(badRoot, 'tasks.jsonl'), `${JSON.stringify({
+            tool: 'query',
+            input: {},
+            must_hit_uids: [],
+            // intentionally omit must_not_hit_uids
+        })}\n`, 'utf-8');
+        await assert.rejects(() => loadBenchmarkDataset(badRoot), /missing required field/i);
+    }
+    finally {
+        await fs.rm(badRoot, { recursive: true, force: true });
+    }
 });
 test('loadBenchmarkDataset parses neonspark-v1 dataset', async () => {
-    const root = path.resolve('../benchmarks/unity-baseline/neonspark-v1');
+    const root = path.resolve(projectRoot, '../benchmarks/unity-baseline/neonspark-v1');
     const ds = await loadBenchmarkDataset(root);
     assert.equal(ds.symbols.length, 20);
     assert.ok(ds.relations.length > 0);
@@ -24,7 +59,7 @@ test('loadBenchmarkDataset parses neonspark-v1 dataset', async () => {
     assert.ok(ds.tasks.some((t) => t.tool === 'impact'));
 });
 test('loadBenchmarkDataset parses neonspark-v2 dataset', async () => {
-    const root = path.resolve('../benchmarks/unity-baseline/neonspark-v2');
+    const root = path.resolve(projectRoot, '../benchmarks/unity-baseline/neonspark-v2');
     const ds = await loadBenchmarkDataset(root);
     assert.ok(ds.symbols.length >= 40 && ds.symbols.length <= 60);
     assert.ok(ds.relations.length > 0);
@@ -33,3 +68,11 @@ test('loadBenchmarkDataset parses neonspark-v2 dataset', async () => {
     assert.ok(ds.tasks.some((t) => t.tool === 'context'));
     assert.ok(ds.tasks.some((t) => t.tool === 'impact'));
 });
+test('latest unity hydration gate report includes hydrationMetaSummary schema', async () => {
+    const reportPath = path.resolve(projectRoot, 'docs/reports/2026-03-15-unity-hydration-gates.json');
+    const raw = await fs.readFile(reportPath, 'utf-8');
+    const report = JSON.parse(raw);
+    assert.ok(report.hydrationMetaSummary);
+    assert.equal(typeof report.hydrationMetaSummary.compactNeedsRetryRate, 'number');
+    assert.equal(typeof report.hydrationMetaSummary.parityCompleteRate, 'number');
+});

package/dist/benchmark/u2-e2e/config.d.ts

@@ -17,6 +17,7 @@ export interface SymbolScenario {
     kind: 'component' | 'scriptableobject' | 'serializable-class' | 'partial-component';
     objectives: string[];
     contextFileHint?: string;
+    contextUnityHydration?: 'compact' | 'parity';
     deepDivePlan: Array<{
         tool: 'query' | 'context' | 'impact' | 'cypher';
         input: Record<string, unknown>;

package/dist/benchmark/u2-e2e/retrieval-runner.js

@@ -53,12 +53,29 @@ function hasDeepDiveEvidence(output) {
     const outgoingRefs = countRefs(output?.outgoing);
     return processSymbols + definitions + candidates + rows + byDepth + impacted + incomingRefs + outgoingRefs > 0;
 }
-function assertScenario(scenario, contextOnOutput, deepDiveOutputs) {
+function assertScenario(scenario, contextOnOutput, deepDiveOutputs, contextUnityHydration) {
     const failures = [];
     const bindings = Array.isArray(contextOnOutput?.resourceBindings) ? contextOnOutput.resourceBindings : [];
     const hasBindings = bindings.length > 0;
     const hasResolvedReferences = bindings.some((binding) => Array.isArray(binding?.resolvedReferences) && binding.resolvedReferences.length > 0);
     const hasAssetTypeBinding = bindings.some((binding) => typeof binding?.resourceType === 'string' && binding.resourceType.length > 0);
+    const hydrationMeta = contextOnOutput?.hydrationMeta && typeof contextOnOutput.hydrationMeta === 'object'
+        ? contextOnOutput.hydrationMeta
+        : null;
+    if (!hydrationMeta) {
+        failures.push(`${scenario.symbol}: context(on) must include hydrationMeta`);
+    }
+    else if (contextUnityHydration === 'compact') {
+        if (typeof hydrationMeta.needsParityRetry !== 'boolean') {
+            failures.push(`${scenario.symbol}: context(on) hydrationMeta.needsParityRetry must be boolean`);
+        }
+        if (hydrationMeta.isComplete === false && hydrationMeta.needsParityRetry !== true) {
+            failures.push(`${scenario.symbol}: context(on) incomplete compact response must set hydrationMeta.needsParityRetry=true`);
+        }
+    }
+    else if (hydrationMeta.isComplete !== true) {
+        failures.push(`${scenario.symbol}: context(on) parity response must set hydrationMeta.isComplete=true`);
+    }
     if (scenario.symbol === 'MainUIManager' || scenario.symbol === 'PlayerActor') {
         if (!hasBindings) {
             failures.push(`${scenario.symbol}: context(on) must include resourceBindings`);
@@ -142,7 +159,12 @@ export async function runSymbolScenario(runner, scenario, repo) {
     const t0 = performance.now();
     const contextOff = await runContextWithDisambiguation(runner, scenario, contextOffInput);
     steps.push(buildMetric('context-off', 'context', performance.now() - t0, contextOffInput, contextOff));
-    const contextOnInput = { ...baseContextInput, unity_resources: 'on' };
+    const contextUnityHydration = scenario.contextUnityHydration === 'parity' ? 'parity' : 'compact';
+    const contextOnInput = {
+        ...baseContextInput,
+        unity_resources: 'on',
+        unity_hydration_mode: contextUnityHydration,
+    };
     const t1 = performance.now();
     const contextOn = await runContextWithDisambiguation(runner, scenario, contextOnInput);
     steps.push(buildMetric('context-on', 'context', performance.now() - t1, contextOnInput, contextOn));
@@ -161,6 +183,6 @@ export async function runSymbolScenario(runner, scenario, repo) {
     return {
         symbol: scenario.symbol,
         steps,
-        assertions: assertScenario(scenario, contextOn, deepDiveOutputs),
+        assertions: assertScenario(scenario, contextOn, deepDiveOutputs, contextUnityHydration),
     };
 }

package/dist/benchmark/u2-e2e/retrieval-runner.test.js

@@ -8,6 +8,12 @@ test('runSymbolScenario executes context off/on + deepDive and records metrics',
             if (input.unity_resources === 'on') {
                 return {
                     status: 'found',
+                    hydrationMeta: {
+                        requestedMode: 'compact',
+                        effectiveMode: 'compact',
+                        isComplete: false,
+                        needsParityRetry: true,
+                    },
                     resourceBindings: [
                         {
                             resourcePath: 'Assets/Prefabs/UI.prefab',
@@ -36,7 +42,11 @@ test('runSymbolScenario executes context off/on + deepDive and records metrics',
 });
 test('AssetRef requires context(on) resourceBindings after serializable-class coverage', async () => {
     const noEvidenceRunner = {
-        context: async () => ({ status: 'found', resourceBindings: [] }),
+        context: async () => ({
+            status: 'found',
+            hydrationMeta: { requestedMode: 'compact', effectiveMode: 'compact', isComplete: false, needsParityRetry: true },
+            resourceBindings: [],
+        }),
         query: async () => ({ process_symbols: [] }),
         impact: async () => ({ impactedCount: 0 }),
         cypher: async () => ({ rows: [] }),
@@ -54,6 +64,7 @@ test('AssetRef requires deep-dive evidence even when context(on) has resourceBin
     const noDeepDiveEvidenceRunner = {
         context: async () => ({
             status: 'found',
+            hydrationMeta: { requestedMode: 'compact', effectiveMode: 'compact', isComplete: false, needsParityRetry: true },
             resourceBindings: [{ resourcePath: 'Assets/Data/Unlock.asset', resourceType: 'asset' }],
         }),
         query: async () => ({ process_symbols: [] }),
@@ -73,6 +84,7 @@ test('AssetRef passes when context(on) bindings and deep-dive evidence are both
     const satisfiedRunner = {
         context: async () => ({
             status: 'found',
+            hydrationMeta: { requestedMode: 'compact', effectiveMode: 'compact', isComplete: false, needsParityRetry: true },
             resourceBindings: [{ resourcePath: 'Assets/Data/Unlock.asset', resourceType: 'asset' }],
         }),
         query: async () => ({ process_symbols: [{ id: 'Class:Assets/Scripts/UnlockContent.cs:UnlockContent' }] }),
@@ -107,6 +119,12 @@ test('runSymbolScenario retries context with file hint when response is ambiguou
             if (input.file_path === hint) {
                 return {
                     status: 'found',
+                    hydrationMeta: {
+                        requestedMode: 'compact',
+                        effectiveMode: 'compact',
+                        isComplete: false,
+                        needsParityRetry: true,
+                    },
                     resourceBindings: [
                         {
                             resourcePath: 'Assets/Prefabs/Player.prefab',
@@ -143,3 +161,28 @@ test('runSymbolScenario retries context with file hint when response is ambiguou
     assert.equal(out.steps[1]?.output?.status, 'found');
     assert.equal(out.assertions.pass, true);
 });
+test('runSymbolScenario fails when compact context hydrationMeta.needsParityRetry is missing', async () => {
+    const runner = {
+        context: async (input) => {
+            if (input.unity_resources === 'on') {
+                return {
+                    status: 'found',
+                    hydrationMeta: { requestedMode: 'compact', effectiveMode: 'compact', isComplete: false },
+                    resourceBindings: [{ resourcePath: 'Assets/Prefabs/A.prefab', resourceType: 'prefab' }],
+                };
+            }
+            return { status: 'found' };
+        },
+        query: async () => ({ process_symbols: [{ id: 'Class:A' }] }),
+        impact: async () => ({ impactedCount: 1 }),
+        cypher: async () => ({ rows: [] }),
+    };
+    const out = await runSymbolScenario(runner, {
+        symbol: 'MainUIManager',
+        kind: 'component',
+        objectives: ['verify hydration contract'],
+        deepDivePlan: [{ tool: 'query', input: { query: 'MainUIManager' } }],
+    });
+    assert.equal(out.assertions.pass, false);
+    assert.ok(out.assertions.failures.some((f) => f.includes('hydrationMeta.needsParityRetry')));
+});

package/dist/benchmark/unity-lazy-context-sampler.d.ts

@@ -0,0 +1,58 @@
+export interface UnityLazyContextMetrics {
+    coldMs: number;
+    warmMs: number;
+    coldMaxRssBytes: number;
+    warmMaxRssBytes: number;
+}
+export interface UnityLazyContextThresholds {
+    coldMsMax?: number;
+    warmMsMax?: number;
+    coldMaxRssBytesMax?: number;
+    warmMaxRssBytesMax?: number;
+}
+export interface UnityLazyThresholdVerdict {
+    pass: boolean;
+    checks: Record<string, {
+        pass: boolean;
+        actual: number;
+        expected: number;
+    }>;
+}
+export interface UnityLazyContextSample {
+    durationMs: number;
+    maxRssBytes: number;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    hydrationMeta?: {
+        requestedMode?: string;
+        effectiveMode?: string;
+        isComplete?: boolean;
+        needsParityRetry?: boolean;
+    };
+}
+export interface UnityHydrationMetaSummary {
+    compactSamples: number;
+    paritySamples: number;
+    compactNeedsRetryRate: number;
+    parityCompleteRate: number;
+}
+export interface UnityLazyContextSamplerConfig {
+    targetPath: string;
+    repo: string;
+    symbol: string;
+    file: string;
+    unityHydration?: 'compact' | 'parity';
+    thresholds?: UnityLazyContextThresholds;
+}
+export type UnityLazyContextRunner = (input: UnityLazyContextSamplerConfig & {
+    warm: boolean;
+}) => Promise<UnityLazyContextSample>;
+export declare function evaluateUnityLazyContextThresholds(metrics: UnityLazyContextMetrics, thresholds?: UnityLazyContextThresholds): UnityLazyThresholdVerdict;
+export declare function runUnityLazyContextSampler(runner: UnityLazyContextRunner, config: UnityLazyContextSamplerConfig): Promise<{
+    capturedAt: string;
+    config: Omit<UnityLazyContextSamplerConfig, 'thresholds'>;
+    metrics: UnityLazyContextMetrics;
+    hydrationMetaSummary: UnityHydrationMetaSummary;
+    thresholdVerdict: UnityLazyThresholdVerdict;
+}>;

package/dist/benchmark/unity-lazy-context-sampler.js

@@ -0,0 +1,217 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+export function evaluateUnityLazyContextThresholds(metrics, thresholds) {
+    const verdict = { pass: true, checks: {} };
+    if (!thresholds) {
+        return verdict;
+    }
+    const checks = [
+        ['coldMs', metrics.coldMs, thresholds.coldMsMax],
+        ['warmMs', metrics.warmMs, thresholds.warmMsMax],
+        ['coldMaxRssBytes', metrics.coldMaxRssBytes, thresholds.coldMaxRssBytesMax],
+        ['warmMaxRssBytes', metrics.warmMaxRssBytes, thresholds.warmMaxRssBytesMax],
+    ];
+    for (const [name, actual, expected] of checks) {
+        if (typeof expected !== 'number')
+            continue;
+        const pass = actual <= expected;
+        verdict.checks[name] = { pass, actual, expected };
+        if (!pass)
+            verdict.pass = false;
+    }
+    return verdict;
+}
+export async function runUnityLazyContextSampler(runner, config) {
+    const cold = await runner({ ...config, warm: false });
+    if (cold.exitCode !== 0) {
+        throw new Error(`Cold run failed: ${cold.stderr || cold.stdout}`);
+    }
+    const warm = await runner({ ...config, warm: true });
+    if (warm.exitCode !== 0) {
+        throw new Error(`Warm run failed: ${warm.stderr || warm.stdout}`);
+    }
+    const metrics = {
+        coldMs: round1(cold.durationMs),
+        warmMs: round1(warm.durationMs),
+        coldMaxRssBytes: cold.maxRssBytes,
+        warmMaxRssBytes: warm.maxRssBytes,
+    };
+    const hydrationMetaSummary = summarizeHydrationMeta([cold, warm]);
+    return {
+        capturedAt: new Date().toISOString(),
+        config: {
+            targetPath: config.targetPath,
+            repo: config.repo,
+            symbol: config.symbol,
+            file: config.file,
+            unityHydration: config.unityHydration || 'compact',
+        },
+        metrics,
+        hydrationMetaSummary,
+        thresholdVerdict: evaluateUnityLazyContextThresholds(metrics, config.thresholds),
+    };
+}
+async function runCliContextSample(input) {
+    const thisFile = fileURLToPath(import.meta.url);
+    const thisDir = path.dirname(thisFile);
+    const cliPath = path.resolve(thisDir, '../cli/index.js');
+    const args = [
+        '-l',
+        'node',
+        cliPath,
+        'context',
+        input.symbol,
+        '--repo',
+        input.repo,
+        '--file',
+        input.file,
+        '--unity-resources',
+        'auto',
+        '--unity-hydration',
+        input.unityHydration || 'compact',
+    ];
+    const startedAt = Date.now();
+    const proc = spawn('/usr/bin/time', args, { cwd: input.targetPath, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+    proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+    const exitCode = await new Promise((resolve) => {
+        proc.on('close', (code) => resolve(code ?? 1));
+    });
+    const rssMatch = stderr.match(/maximum resident set size[^0-9]*([0-9]+)|([0-9]+)\s+maximum resident set size/i);
+    const maxRssBytes = rssMatch ? Number(rssMatch[1] || rssMatch[2] || 0) : 0;
+    const parsedPayload = extractFirstJsonObject(stdout) || extractFirstJsonObject(stderr);
+    const hydrationMeta = parsedPayload && typeof parsedPayload === 'object' && parsedPayload.hydrationMeta
+        ? parsedPayload.hydrationMeta
+        : undefined;
+    return {
+        durationMs: Date.now() - startedAt,
+        maxRssBytes,
+        exitCode,
+        stdout,
+        stderr,
+        hydrationMeta,
+    };
+}
+function parseArgs(argv) {
+    const get = (name) => {
+        const index = argv.indexOf(name);
+        if (index === -1 || index + 1 >= argv.length)
+            return undefined;
+        return argv[index + 1];
+    };
+    const targetPath = get('--target-path');
+    const repo = get('--repo');
+    const symbol = get('--symbol');
+    const file = get('--file');
+    const unityHydrationRaw = String(get('--unity-hydration') || 'compact').trim().toLowerCase();
+    const unityHydration = unityHydrationRaw === 'parity' ? 'parity' : 'compact';
+    if (!targetPath)
+        throw new Error('Missing required arg: --target-path <path>');
+    if (!repo)
+        throw new Error('Missing required arg: --repo <repo>');
+    if (!symbol)
+        throw new Error('Missing required arg: --symbol <symbol>');
+    if (!file)
+        throw new Error('Missing required arg: --file <file>');
+    return {
+        targetPath: path.resolve(targetPath),
+        repo,
+        symbol,
+        file,
+        unityHydration,
+        thresholds: get('--thresholds') ? path.resolve(get('--thresholds')) : undefined,
+        report: get('--report') ? path.resolve(get('--report')) : undefined,
+    };
+}
+function round1(value) {
+    return Number(value.toFixed(1));
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const thresholds = args.thresholds
+        ? JSON.parse(await fs.readFile(args.thresholds, 'utf-8'))
+        : undefined;
+    const report = await runUnityLazyContextSampler(runCliContextSample, {
+        targetPath: args.targetPath,
+        repo: args.repo,
+        symbol: args.symbol,
+        file: args.file,
+        unityHydration: args.unityHydration,
+        thresholds,
+    });
+    const payload = JSON.stringify(report, null, 2);
+    if (args.report) {
+        await fs.mkdir(path.dirname(args.report), { recursive: true });
+        await fs.writeFile(args.report, payload, 'utf-8');
+        console.log(`[unity-lazy-context-sampler] report written: ${args.report}`);
+    }
+    console.log(payload);
+    if (!report.thresholdVerdict.pass) {
+        process.exitCode = 1;
+    }
+}
+const modulePath = process.argv[1] ? path.resolve(process.argv[1]) : '';
+if (import.meta.url === `file://${modulePath}`) {
+    main().catch((error) => {
+        console.error(`[unity-lazy-context-sampler] failed: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    });
+}
+function summarizeHydrationMeta(samples) {
+    let compactSamples = 0;
+    let compactNeedsRetry = 0;
+    let paritySamples = 0;
+    let parityComplete = 0;
+    for (const sample of samples) {
+        const mode = String(sample.hydrationMeta?.effectiveMode || '').toLowerCase();
+        if (mode === 'parity') {
+            paritySamples += 1;
+            if (sample.hydrationMeta?.isComplete === true) {
+                parityComplete += 1;
+            }
+            continue;
+        }
+        if (mode === 'compact') {
+            compactSamples += 1;
+            if (sample.hydrationMeta?.needsParityRetry === true) {
+                compactNeedsRetry += 1;
+            }
+        }
+    }
+    return {
+        compactSamples,
+        paritySamples,
+        compactNeedsRetryRate: compactSamples > 0 ? round1(compactNeedsRetry / compactSamples) : 0,
+        parityCompleteRate: paritySamples > 0 ? round1(parityComplete / paritySamples) : 0,
+    };
+}
+function extractFirstJsonObject(text) {
+    if (!text)
+        return null;
+    const start = text.indexOf('{');
+    if (start < 0)
+        return null;
+    let depth = 0;
+    for (let i = start; i < text.length; i += 1) {
+        const char = text[i];
+        if (char === '{')
+            depth += 1;
+        if (char === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                const candidate = text.slice(start, i + 1);
+                try {
+                    return JSON.parse(candidate);
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/benchmark/unity-lazy-context-sampler.test.js

@@ -0,0 +1,32 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runUnityLazyContextSampler } from './unity-lazy-context-sampler.js';
+test('sampler emits cold/warm latency and rss metrics with threshold verdict', async () => {
+    const fakeRunner = async ({ warm }) => ({
+        durationMs: warm ? 420 : 6200,
+        maxRssBytes: warm ? 650 * 1024 * 1024 : 1700 * 1024 * 1024,
+        exitCode: 0,
+        stdout: '',
+        stderr: '',
+        hydrationMeta: warm
+            ? { requestedMode: 'compact', effectiveMode: 'parity', isComplete: true, needsParityRetry: false }
+            : { requestedMode: 'compact', effectiveMode: 'compact', isComplete: false, needsParityRetry: true },
+    });
+    const report = await runUnityLazyContextSampler(fakeRunner, {
+        targetPath: '/tmp/repo',
+        repo: 'neonnew-core',
+        symbol: 'DoorObj',
+        file: 'Assets/NEON/Code/Game/Doors/DoorObj.cs',
+        thresholds: {
+            coldMsMax: 7000,
+            warmMsMax: 1000,
+            coldMaxRssBytesMax: 2 * 1024 * 1024 * 1024,
+            warmMaxRssBytesMax: 1 * 1024 * 1024 * 1024,
+        },
+    });
+    assert.ok(report.metrics.coldMs > 0);
+    assert.equal(typeof report.hydrationMetaSummary.compactNeedsRetryRate, 'number');
+    assert.equal(typeof report.hydrationMetaSummary.parityCompleteRate, 'number');
+    assert.ok(typeof report.thresholdVerdict.pass === 'boolean');
+    assert.equal(report.thresholdVerdict.pass, true);
+});

package/dist/cli/ai-context.js

@@ -38,7 +38,7 @@ This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} s
 2. **Match your task to a skill below** and **read that skill file**
 3. **Follow the skill's workflow and checklist**
 
-> If step 1 warns the index is stale, run \`npx gitnexus analyze\` in the terminal first.
+> If step 1 warns the index is stale, ask user whether to rebuild index via \`npx -y gitnexus analyze\` first (it reuses previous analyze scope/options by default; add \`--no-reuse-options\` to reset). If user declines, explicitly warn that retrieval may not reflect current codebase. For build/analyze/test commands, use a 10-30 minute timeout; on failure/timeout, report exact tool output and do not auto-retry or silently fall back to glob/grep.
 
 ## Skills
 

package/dist/cli/analyze-close-policy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Kuzu native close may segfault on some macOS environments.
+ * We skip explicit close on analyze exit there, unless force-enabled.
+ */
+export declare function shouldCloseKuzuOnAnalyzeExit(platform?: NodeJS.Platform, forceCloseOnExit?: string | undefined): boolean;

package/dist/cli/analyze-close-policy.js

@@ -0,0 +1,9 @@
+/**
+ * Kuzu native close may segfault on some macOS environments.
+ * We skip explicit close on analyze exit there, unless force-enabled.
+ */
+export function shouldCloseKuzuOnAnalyzeExit(platform = process.platform, forceCloseOnExit = process.env.GITNEXUS_FORCE_KUZU_CLOSE_ON_EXIT) {
+    if (forceCloseOnExit === '1')
+        return true;
+    return platform !== 'darwin';
+}

package/dist/cli/analyze-close-policy.test.js

@@ -0,0 +1,12 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { shouldCloseKuzuOnAnalyzeExit } from './analyze-close-policy.js';
+test('shouldCloseKuzuOnAnalyzeExit skips close on darwin by default', () => {
+    assert.equal(shouldCloseKuzuOnAnalyzeExit('darwin', undefined), false);
+});
+test('shouldCloseKuzuOnAnalyzeExit closes on non-darwin platforms', () => {
+    assert.equal(shouldCloseKuzuOnAnalyzeExit('linux', undefined), true);
+});
+test('shouldCloseKuzuOnAnalyzeExit can be force-enabled on darwin', () => {
+    assert.equal(shouldCloseKuzuOnAnalyzeExit('darwin', '1'), true);
+});

package/dist/cli/analyze-multi-scope-regression.test.js

@@ -27,6 +27,6 @@ test('pipeline forwards extension-filtered scoped paths to unity enrich', { time
         includeExtensions: ['.cs'],
         scopeRules: ['Assets'],
     });
-    assert.equal(result.unityResult?.bindingCount, 0);
+    assert.ok((result.unityResult?.bindingCount || 0) > 0);
     assert.ok(result.unityResult?.diagnostics.some((message) => message.includes('scanContext:')));
 });

package/dist/cli/analyze-options.d.ts

@@ -2,6 +2,25 @@ export interface AnalyzeScopeOptions {
     scopeManifest?: string;
     scopePrefix?: string[] | string;
 }
+export interface StoredAnalyzeOptions {
+    includeExtensions?: string[];
+    scopeRules?: string[];
+    repoAlias?: string;
+    embeddings?: boolean;
+}
+export interface ResolveAnalyzeOptionsInput extends AnalyzeScopeOptions {
+    extensions?: string;
+    repoAlias?: string;
+    embeddings?: boolean;
+    reuseOptions?: boolean;
+}
+export interface EffectiveAnalyzeOptions {
+    includeExtensions: string[];
+    scopeRules: string[];
+    repoAlias?: string;
+    embeddings: boolean;
+}
 export declare function parseExtensionList(rawExtensions?: string): string[];
 export declare function normalizeRepoAlias(repoAlias?: string): string | undefined;
 export declare function resolveAnalyzeScopeRules(options?: AnalyzeScopeOptions): Promise<string[]>;
+export declare function resolveEffectiveAnalyzeOptions(options?: ResolveAnalyzeOptionsInput, stored?: StoredAnalyzeOptions): Promise<EffectiveAnalyzeOptions>;