noteconnection 1.6.8 → 1.8.0

package/dist/src/learning/vectorAccelerationAdapter.test.js

@@ -0,0 +1,382 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vectorAccelerationAdapter_1 = require("./vectorAccelerationAdapter");
+describe('vector acceleration adapter', () => {
+    const originalFetch = globalThis.fetch;
+    const baseSelectionInput = {
+        atomCount: 180,
+        queryTokens: ['retrieval', 'mastery'],
+        queryWeights: new Map([
+            ['retrieval', 1.2],
+            ['mastery', 0.8],
+        ]),
+        topK: 4,
+        tokenToAtomIds: new Map([
+            ['retrieval', Array.from({ length: 60 }, (_v, index) => `atom_${index}`)],
+            ['mastery', Array.from({ length: 40 }, (_v, index) => `atom_${index + 20}`)],
+        ]),
+        signatureBuckets: new Map(),
+        annPrefilterEnabled: true,
+        representationVersion: 'local-vector-representation-v1',
+        embeddingModelId: 'local-semantic-tfidf-v1',
+        embeddingDimension: 512,
+        indexSignature: 'idx_sig_abc123',
+    };
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        jest.restoreAllMocks();
+    });
+    test('normalizes acceleration adapter provider aliases', () => {
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('local')).toBe('local');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('external_stub')).toBe('external_stub');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('external-stub')).toBe('external_stub');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('stub')).toBe('external_stub');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('external_http')).toBe('external_http');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('external-http')).toBe('external_http');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('http')).toBe('external_http');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('unknown')).toBe('local');
+    });
+    test('returns undefined adapter for local provider', () => {
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('local');
+        expect(adapter).toBeUndefined();
+    });
+    test('external stub adapter selects token-based candidates for large corpus', async () => {
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_stub');
+        expect(adapter).toBeDefined();
+        expect(adapter?.id).toBe('external-stub-vector-acceleration-v1');
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        expect(selection?.used).toBe(true);
+        expect(selection?.mode).toBe('token_prefilter');
+        expect((selection?.candidateAtomIds || []).length).toBeGreaterThan(0);
+    });
+    test('external stub adapter returns full scan when prefilter is disabled', async () => {
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_stub');
+        const selection = await adapter?.selectCandidates({
+            ...baseSelectionInput,
+            queryTokens: ['retrieval'],
+            queryWeights: new Map([['retrieval', 1.0]]),
+            tokenToAtomIds: new Map([['retrieval', ['atom_a', 'atom_b']]]),
+            annPrefilterEnabled: false,
+        });
+        expect(selection?.used).toBe(false);
+        expect(selection?.mode).toBe('full_scan');
+        expect(selection?.candidateAtomIds).toEqual([]);
+    });
+    test('external http adapter throws endpoint-missing error when endpoint is not configured', async () => {
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http');
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('external_http_endpoint_missing');
+        expect(adapter?.getHealth?.().status).toBe('unavailable');
+        expect(String(adapter?.getHealth?.().message || '')).toContain('external_http_endpoint_missing');
+        expect(Number(adapter?.getHealth?.().failureCount || 0)).toBeGreaterThanOrEqual(1);
+        expect(adapter?.getHealth?.().representationVersion).toBe('local-vector-representation-v1');
+        expect(adapter?.getHealth?.().embeddingModelId).toBe('local-semantic-tfidf-v1');
+        expect(adapter?.getHealth?.().representationStatus).toBe('unknown');
+    });
+    test('external http adapter forwards selection request and normalizes connector response', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_10', 'atom_21'],
+                representationVersion: 'local-vector-representation-v1',
+                embeddingModelId: 'local-semantic-tfidf-v1',
+                embeddingDimension: 512,
+                indexSignature: 'idx_sig_abc123',
+                representationStatus: 'aligned',
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                timeoutMs: 450,
+            },
+        });
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(String(fetchMock.mock.calls[0]?.[0] || '')).toContain('/select-candidates');
+        const requestOptions = fetchMock.mock.calls[0]?.[1];
+        const requestHeaders = requestOptions?.headers || {};
+        const requestBody = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body || '{}'));
+        expect(String(requestHeaders['x-request-id'] || '')).toContain('nc-vector-accel-');
+        expect(String(requestHeaders['x-correlation-id'] || '')).toBe(String(requestHeaders['x-request-id'] || ''));
+        expect(String(requestBody.representationVersion || '')).toBe('local-vector-representation-v1');
+        expect(String(requestBody.embeddingModelId || '')).toBe('local-semantic-tfidf-v1');
+        expect(Number(requestBody.embeddingDimension || 0)).toBe(512);
+        expect(String(requestBody.indexSignature || '')).toBe('idx_sig_abc123');
+        expect(selection?.used).toBe(true);
+        expect(selection?.mode).toBe('token_prefilter');
+        expect(selection?.candidateAtomIds).toEqual(['atom_10', 'atom_21']);
+        expect(selection?.representation?.validated).toBe(true);
+        expect(selection?.prefilterMetrics?.candidatesReturned).toBe(2);
+        expect(Number(selection?.prefilterMetrics?.totalAtomsInScope || 0)).toBeGreaterThan(0);
+        expect(adapter?.getHealth?.().status).toBe('ready');
+        expect(String(adapter?.getHealth?.().lastRequestId || '')).toContain('nc-vector-accel-');
+        expect(adapter?.getHealth?.().representationStatus).toBe('aligned');
+        expect(adapter?.getHealth?.().representationVersion).toBe('local-vector-representation-v1');
+        expect(adapter?.getHealth?.().embeddingModelId).toBe('local-semantic-tfidf-v1');
+        expect(Number(adapter?.getHealth?.().embeddingDimension || 0)).toBe(512);
+    });
+    test('external http adapter syncs remote index and caches matching signatures', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            headers: {
+                get: (name) => {
+                    if (String(name || '').toLowerCase() === 'x-request-id') {
+                        return 'connector-sync-success';
+                    }
+                    return '';
+                },
+            },
+            json: async () => ({
+                synced: true,
+                atomCount: 180,
+                indexSignature: 'idx_sig_abc123',
+                representationVersion: 'local-vector-representation-v1',
+                embeddingModelId: 'local-semantic-tfidf-v1',
+                embeddingDimension: 512,
+                representationStatus: 'aligned',
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+            },
+        });
+        const syncResult = await adapter?.syncIndex?.(baseSelectionInput);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(String(fetchMock.mock.calls[0]?.[0] || '')).toContain('/sync-index');
+        const requestBody = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body || '{}'));
+        expect(Number(requestBody.atomCount || 0)).toBe(180);
+        expect(String(requestBody.indexSignature || '')).toBe('idx_sig_abc123');
+        expect(Array.isArray(requestBody.tokenToAtomIds)).toBe(true);
+        expect(Array.isArray(requestBody.signatureBuckets)).toBe(true);
+        expect(syncResult?.synced).toBe(true);
+        expect(syncResult?.indexSignature).toBe('idx_sig_abc123');
+        const healthAfterSync = adapter?.getHealth?.();
+        expect(healthAfterSync?.status).toBe('ready');
+        expect(healthAfterSync?.indexSyncStatus).toBe('ready');
+        expect(healthAfterSync?.syncRequestCount).toBe(1);
+        expect(healthAfterSync?.syncSuccessCount).toBe(1);
+        expect(healthAfterSync?.syncFailureCount).toBe(0);
+        expect(healthAfterSync?.syncedIndexSignature).toBe('idx_sig_abc123');
+        expect(healthAfterSync?.syncedAtomCount).toBe(180);
+        const cachedSyncResult = await adapter?.syncIndex?.(baseSelectionInput);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(cachedSyncResult?.synced).toBe(true);
+        expect(adapter?.getHealth?.().indexSyncStatus).toBe('ready');
+    });
+    test('external http adapter filters out-of-scope candidate ids and keeps only valid ids', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_999', 'atom_10', 'atom_10'],
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+            },
+        });
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        expect(selection?.used).toBe(true);
+        expect(selection?.candidateAtomIds).toEqual(['atom_10']);
+        expect(selection?.prefilterMetrics?.candidatesReturned).toBe(1);
+        expect(selection?.prefilterMetrics?.prefilterRatio).toBeGreaterThan(0);
+        expect(String(adapter?.getHealth?.().representationStatusReason || '')).toContain('candidate_ids_out_of_scope');
+    });
+    test('external http adapter infers representation mismatch when connector metadata drifts', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_10'],
+                representationVersion: 'remote-vector-representation-v2',
+                embeddingModelId: 'local-semantic-tfidf-v1',
+                embeddingDimension: 512,
+                indexSignature: 'idx_sig_abc123',
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+            },
+        });
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        expect(selection?.used).toBe(true);
+        expect(adapter?.getHealth?.().representationStatus).toBe('mismatch');
+        expect(String(adapter?.getHealth?.().representationStatusReason || '')).toContain('representation_version');
+    });
+    test('external http adapter retries transient status failures and recovers', async () => {
+        const fetchMock = jest
+            .fn()
+            .mockResolvedValueOnce({
+            ok: false,
+            status: 503,
+            headers: {
+                get: (name) => {
+                    const normalized = String(name || '').toLowerCase();
+                    if (normalized === 'retry-after') {
+                        return '0.03';
+                    }
+                    if (normalized === 'x-request-id') {
+                        return 'connector-retry-503';
+                    }
+                    return '';
+                },
+            },
+            json: async () => ({}),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            headers: {
+                get: (name) => {
+                    if (String(name || '').toLowerCase() === 'x-request-id') {
+                        return 'connector-retry-success';
+                    }
+                    return '';
+                },
+            },
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_22'],
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const originalSetTimeout = global.setTimeout;
+        const recordedTimeoutDelays = [];
+        const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation(((handler, timeout, ...args) => {
+            recordedTimeoutDelays.push(Math.floor(Number(timeout || 0)));
+            return originalSetTimeout(handler, timeout, ...args);
+        }));
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 2,
+                retryDelayMs: 0,
+            },
+        });
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        setTimeoutSpy.mockRestore();
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(selection?.used).toBe(true);
+        expect(selection?.candidateAtomIds).toEqual(['atom_22']);
+        expect(adapter?.getHealth?.().status).toBe('ready');
+        expect(recordedTimeoutDelays.some((delay) => delay >= 30)).toBe(true);
+        expect(String(adapter?.getHealth?.().lastRequestId || '')).toBe('connector-retry-success');
+        expect(String(adapter?.getHealth?.().lastErrorCode || '')).toBe('');
+        expect(Number(adapter?.getHealth?.().lastRetryAfterMs || 0)).toBe(30);
+    });
+    test('external http adapter does not retry non-transient status failures', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: false,
+            status: 400,
+            json: async () => ({}),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 3,
+                retryDelayMs: 0,
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('external_http_status_400');
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(adapter?.getHealth?.().status).toBe('unavailable');
+    });
+    test('external http adapter retries transient network failures up to max retries', async () => {
+        const fetchMock = jest.fn().mockRejectedValue(new Error('socket_hang_up'));
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 2,
+                retryDelayMs: 0,
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        expect(fetchMock).toHaveBeenCalledTimes(3);
+        expect(adapter?.getHealth?.().status).toBe('degraded');
+    });
+    test('external http adapter propagates connector failures and marks degraded health', async () => {
+        const fetchMock = jest.fn().mockRejectedValue(new Error('socket_hang_up'));
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        expect(adapter?.getHealth?.().status).toBe('degraded');
+        expect(String(adapter?.getHealth?.().message || '')).toContain('socket_hang_up');
+    });
+    test('external http adapter opens circuit after consecutive failures and short-circuits requests', async () => {
+        const fetchMock = jest.fn().mockRejectedValue(new Error('socket_hang_up'));
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 0,
+                retryDelayMs: 0,
+                circuitFailureThreshold: 2,
+                circuitCooldownMs: 10000,
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('external_http_circuit_open');
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(adapter?.getHealth?.().status).toBe('unavailable');
+        expect(String(adapter?.getHealth?.().message || '')).toContain('external_http_circuit_open');
+    });
+    test('external http adapter enters half-open after cooldown and closes on successful probe', async () => {
+        const fetchMock = jest
+            .fn()
+            .mockRejectedValueOnce(new Error('socket_hang_up'))
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_23'],
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        let nowMs = 1000;
+        jest.spyOn(Date, 'now').mockImplementation(() => nowMs);
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 0,
+                retryDelayMs: 0,
+                circuitFailureThreshold: 1,
+                circuitCooldownMs: 500,
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('external_http_circuit_open');
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        nowMs += 600;
+        const recovered = await adapter?.selectCandidates(baseSelectionInput);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(recovered?.used).toBe(true);
+        expect(recovered?.candidateAtomIds).toEqual(['atom_23']);
+        expect(adapter?.getHealth?.().status).toBe('ready');
+        expect(String(adapter?.getHealth?.().message || '')).toContain('circuit=closed');
+    });
+});

package/dist/src/lfs.asset.policy.contract.test.js

@@ -0,0 +1,153 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+describe('LFS asset policy contracts', () => {
+    const repoRoot = path.resolve(__dirname, '..');
+    const packageJsonPath = path.join(repoRoot, 'package.json');
+    const gitattributesPath = path.join(repoRoot, '.gitattributes');
+    const deadNodeSidecarPath = path.join(repoRoot, 'src-tauri', 'bin', 'node-x86_64-pc-windows-msvc.exe');
+    const deadGraphPayloadPaths = [
+        path.join(repoRoot, 'src', 'frontend', 'data.js'),
+        path.join(repoRoot, 'src', 'frontend', 'graph_data.json'),
+    ];
+    const policyUtilsPath = path.join(repoRoot, 'scripts', 'lfs-asset-policy-utils.js');
+    let policyUtils;
+    function readJson(filePath) {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    beforeAll(() => {
+        policyUtils = require(policyUtilsPath);
+    });
+    test('repository head no longer keeps removed LFS residues for dead node sidecar or bundled graph payloads', () => {
+        const gitattributes = fs.readFileSync(gitattributesPath, 'utf8');
+        expect(gitattributes).not.toContain('src-tauri/bin/node-x86_64-pc-windows-msvc.exe');
+        expect(gitattributes).not.toContain('src/frontend/data.js');
+        expect(gitattributes).not.toContain('src/frontend/graph_data.json');
+        expect(fs.existsSync(deadNodeSidecarPath)).toBe(false);
+        deadGraphPayloadPaths.forEach((filePath) => {
+            expect(fs.existsSync(filePath)).toBe(false);
+        });
+    });
+    test('unexpected-only mode tolerates current legacy protected entries while keeping protected roots explicit', () => {
+        const result = policyUtils.evaluateLfsAssetPolicy({
+            gitattributesText: [
+                'src-tauri/bin/server-x86_64-pc-windows-msvc.exe filter=lfs diff=lfs merge=lfs -text',
+                'src-tauri/bin/server-x86_64-unknown-linux-gnu filter=lfs diff=lfs merge=lfs -text',
+                'src-tauri/bin/server-aarch64-apple-darwin filter=lfs diff=lfs merge=lfs -text',
+                'src-tauri/bin/godot-x86_64-pc-windows-msvc.exe filter=lfs diff=lfs merge=lfs -text',
+                'assets/demo-large.zip filter=lfs diff=lfs merge=lfs -text',
+            ].join('\n'),
+            lfsLsFilesText: [
+                'bbbbbbbbbb - src-tauri/bin/server-x86_64-unknown-linux-gnu',
+            ].join('\n'),
+            mode: 'unexpected-only',
+        });
+        expect(policyUtils.PROTECTED_LFS_ROOTS).toEqual(['src/frontend/', 'src-tauri/bin/']);
+        expect(result.unexpectedProtectedPaths).toEqual([]);
+        expect(result.legacyProtectedPaths).toEqual([
+            'src-tauri/bin/godot-x86_64-pc-windows-msvc.exe',
+            'src-tauri/bin/server-aarch64-apple-darwin',
+            'src-tauri/bin/server-x86_64-pc-windows-msvc.exe',
+            'src-tauri/bin/server-x86_64-unknown-linux-gnu',
+        ]);
+    });
+    test('unexpected-only mode flags new protected LFS paths outside the approved legacy allowlist', () => {
+        const result = policyUtils.evaluateLfsAssetPolicy({
+            gitattributesText: [
+                'src-tauri/bin/new-helper.exe filter=lfs diff=lfs merge=lfs -text',
+            ].join('\n'),
+            mode: 'unexpected-only',
+        });
+        expect(result.unexpectedProtectedPaths).toEqual(['src-tauri/bin/new-helper.exe']);
+    });
+    test('unexpected-only mode now treats bundled graph payload LFS paths as drift to be removed', () => {
+        const result = policyUtils.evaluateLfsAssetPolicy({
+            gitattributesText: [
+                'src/frontend/data.js filter=lfs diff=lfs merge=lfs -text',
+                'src/frontend/graph_data.json filter=lfs diff=lfs merge=lfs -text',
+            ].join('\n'),
+            mode: 'unexpected-only',
+        });
+        expect(result.unexpectedProtectedPaths).toEqual([
+            'src/frontend/data.js',
+            'src/frontend/graph_data.json',
+        ]);
+    });
+    test('deleted working-tree residues listed by git lfs ls-files are ignored once the rule and file are gone', () => {
+        const result = policyUtils.evaluateLfsAssetPolicy({
+            gitattributesText: '',
+            lfsLsFilesText: 'aaaaaaaaaa - src-tauri/bin/node-x86_64-pc-windows-msvc.exe',
+            existingRepoPaths: [],
+            mode: 'unexpected-only',
+        });
+        expect(result.protectedTrackedPaths).toEqual([]);
+        expect(result.unexpectedProtectedPaths).toEqual([]);
+    });
+    test('strict mode is ready for the future no-LFS end state', () => {
+        const result = policyUtils.evaluateLfsAssetPolicy({
+            gitattributesText: 'src/frontend/data.js filter=lfs diff=lfs merge=lfs -text',
+            mode: 'strict',
+        });
+        expect(result.strictViolations).toEqual(['src/frontend/data.js']);
+    });
+    test('package scripts expose local policy verification and future strict mode', () => {
+        const packageJson = readJson(packageJsonPath);
+        const scripts = packageJson.scripts || {};
+        expect(scripts['verify:lfs:policy']).toBe('node scripts/verify-lfs-asset-policy.js');
+        expect(scripts['verify:lfs:policy:strict']).toBe('node scripts/verify-lfs-asset-policy.js --strict');
+    });
+    test('legacy allowlist no longer preserves the unused node sidecar path', () => {
+        expect(policyUtils.LEGACY_ALLOWED_PROTECTED_LFS_PATHS).not.toContain('src-tauri/bin/node-x86_64-pc-windows-msvc.exe');
+        expect(policyUtils.LEGACY_ALLOWED_PROTECTED_LFS_PATHS).not.toContain('src/frontend/data.js');
+        expect(policyUtils.LEGACY_ALLOWED_PROTECTED_LFS_PATHS).not.toContain('src/frontend/graph_data.json');
+    });
+    test('current legacy LFS scope is limited to desktop binary placeholders rather than markdown-worker or bridge source', () => {
+        const gitattributes = fs.readFileSync(gitattributesPath, 'utf8');
+        const tracked = policyUtils.evaluateLfsAssetPolicy({
+            gitattributesText: gitattributes,
+            mode: 'unexpected-only',
+        });
+        expect(tracked.legacyProtectedPaths).toEqual([
+            'src-tauri/bin/godot-x86_64-pc-windows-msvc.exe',
+            'src-tauri/bin/server-aarch64-apple-darwin',
+            'src-tauri/bin/server-x86_64-pc-windows-msvc.exe',
+            'src-tauri/bin/server-x86_64-unknown-linux-gnu',
+        ]);
+        expect(gitattributes).not.toContain('src-tauri/bin/markdown-worker');
+        expect(gitattributes).not.toContain('src/core/PathBridge.ts');
+    });
+});

package/dist/src/license.policy.contract.test.js

@@ -0,0 +1,66 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+describe('license policy contract', () => {
+    const repoRoot = path.resolve(__dirname, '..');
+    const packageJsonPath = path.join(repoRoot, 'package.json');
+    const tauriCargoTomlPath = path.join(repoRoot, 'src-tauri', 'Cargo.toml');
+    const licensePath = path.join(repoRoot, 'LICENSE');
+    const readmePath = path.join(repoRoot, 'README.md');
+    test('root package manifest is pinned to GPL-3.0-only', () => {
+        const pkg = readJson(packageJsonPath);
+        expect(pkg.license).toBe('GPL-3.0-only');
+    });
+    test('tauri crate manifest is pinned to GPL-3.0-only', () => {
+        const cargoToml = fs.readFileSync(tauriCargoTomlPath, 'utf8');
+        expect(cargoToml).toContain('license = "GPL-3.0-only"');
+    });
+    test('repository license artifact ships GNU GPL v3 text', () => {
+        const license = fs.readFileSync(licensePath, 'utf8');
+        expect(license).toContain('GNU GENERAL PUBLIC LICENSE');
+        expect(license).toContain('Version 3, 29 June 2007');
+    });
+    test('README license section advertises GPL-3.0-only in both locales', () => {
+        const readme = fs.readFileSync(readmePath, 'utf8');
+        expect(readme).toContain('License / 开源许可');
+        expect(readme).toContain('GNU General Public License v3.0 (GPL-3.0-only)');
+        expect(readme).toContain('GNU General Public License v3.0（GPL-3.0-only）');
+    });
+});