@rigour-labs/core 6.2.4 → 6.2.5

package/dist/inference/index.d.ts

@@ -4,8 +4,12 @@
 export type { InferenceProvider, InferenceOptions, DeepFinding, DeepAnalysisResult, ModelTier, ModelInfo } from './types.js';
 export { MODELS } from './types.js';
 export { SidecarProvider } from './sidecar-provider.js';
+export type { ActiveModel } from './sidecar-provider.js';
+export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG } from './llama-engine.js';
+export type { ProbeResult } from './llama-engine.js';
 export { CloudProvider } from './cloud-provider.js';
-export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir } from './model-manager.js';
+export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir, getCachedModel } from './model-manager.js';
+export type { CachedModel } from './model-manager.js';
 import type { InferenceProvider } from './types.js';
 import type { DeepOptions } from '../types/index.js';
 /**

package/dist/inference/index.js

@@ -1,7 +1,8 @@
 export { MODELS } from './types.js';
 export { SidecarProvider } from './sidecar-provider.js';
+export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG } from './llama-engine.js';
 export { CloudProvider } from './cloud-provider.js';
-export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir } from './model-manager.js';
+export { ensureModel, isModelCached, getModelPath, getModelInfo, downloadModel, getModelsDir, getCachedModel } from './model-manager.js';
 import { SidecarProvider } from './sidecar-provider.js';
 import { CloudProvider } from './cloud-provider.js';
 /**

package/dist/inference/llama-engine.d.ts

@@ -0,0 +1,27 @@
+import { type HttpGet } from './http-download.js';
+export declare const LLAMA_RELEASE_TAG = "b5604";
+export declare function llamaBinaryName(): string;
+/** Install directory for the pinned release: ~/.rigour/bin/llama-<tag>. */
+export declare function managedEngineDir(): string;
+export declare function managedEnginePath(): string;
+export declare function releaseAssetFor(platformKey: string): string | undefined;
+export interface ProbeResult {
+    ok: boolean;
+    version?: string;
+    error?: string;
+}
+/**
+ * Run `<binary> --version` and accept it only if it exits 0. A placeholder
+ * script (such as an unbundled brain package) or a binary missing its shared
+ * libraries fails here instead of on every inference call.
+ */
+export declare function probeBinary(binaryPath: string): Promise<ProbeResult>;
+/** Forget cached probe results, e.g. after installing a new engine. */
+export declare function resetProbeCache(): void;
+/**
+ * Download the pinned release for this platform and install its whole bin
+ * folder into managedEngineDir(). Returns the verified binary path.
+ */
+export declare function installLlamaEngine(onProgress?: (message: string) => void, get?: HttpGet): Promise<string>;
+/** Copy the folder that contains llama-cli (binary + shared libraries) into place. */
+export declare function installBinFolder(extractedRoot: string, installDir: string): Promise<void>;

package/dist/inference/llama-engine.js

@@ -0,0 +1,152 @@
+/**
+ * llama.cpp engine: install from the pinned GitHub release and verify that a
+ * candidate binary actually runs.
+ *
+ * The release archives link llama-cli against shared libraries next to it
+ * (@rpath → @loader_path on macOS), so the whole bin folder is installed; a
+ * lone llama-cli fails with "Library not loaded: @rpath/libllama.dylib".
+ */
+import os from 'os';
+import path from 'path';
+import fs from 'fs-extra';
+import { RIGOUR_DIR } from '../storage/db.js';
+import { downloadToFile } from './http-download.js';
+import { runProcess } from './llama-process.js';
+export const LLAMA_RELEASE_TAG = 'b5604';
+const LLAMA_RELEASE_BASE = `https://github.com/ggml-org/llama.cpp/releases/download/${LLAMA_RELEASE_TAG}`;
+const PROBE_TIMEOUT_MS = 5_000;
+const EXTRACT_TIMEOUT_MS = 120_000;
+/** Platform → llama.cpp release asset. linux-arm64 has no published build. */
+const LLAMA_RELEASE_ASSETS = {
+    'darwin-arm64': `llama-${LLAMA_RELEASE_TAG}-bin-macos-arm64.zip`,
+    'darwin-x64': `llama-${LLAMA_RELEASE_TAG}-bin-macos-x64.zip`,
+    'linux-x64': `llama-${LLAMA_RELEASE_TAG}-bin-ubuntu-x64.zip`,
+    'win32-x64': `llama-${LLAMA_RELEASE_TAG}-bin-win-cpu-x64.zip`,
+};
+export function llamaBinaryName() {
+    return os.platform() === 'win32' ? 'llama-cli.exe' : 'llama-cli';
+}
+/** Install directory for the pinned release: ~/.rigour/bin/llama-<tag>. */
+export function managedEngineDir() {
+    return path.join(RIGOUR_DIR, 'bin', `llama-${LLAMA_RELEASE_TAG}`);
+}
+export function managedEnginePath() {
+    return path.join(managedEngineDir(), llamaBinaryName());
+}
+export function releaseAssetFor(platformKey) {
+    return LLAMA_RELEASE_ASSETS[platformKey];
+}
+const probeCache = new Map();
+/**
+ * Run `<binary> --version` and accept it only if it exits 0. A placeholder
+ * script (such as an unbundled brain package) or a binary missing its shared
+ * libraries fails here instead of on every inference call.
+ */
+export function probeBinary(binaryPath) {
+    let cached = probeCache.get(binaryPath);
+    if (!cached) {
+        cached = runProbe(binaryPath);
+        probeCache.set(binaryPath, cached);
+    }
+    return cached;
+}
+/** Forget cached probe results, e.g. after installing a new engine. */
+export function resetProbeCache() {
+    probeCache.clear();
+}
+async function runProbe(binaryPath) {
+    if (!(await fs.pathExists(binaryPath)))
+        return { ok: false, error: 'not found' };
+    try {
+        const { code, stdout, stderr } = await runProcess(binaryPath, ['--version'], { timeoutMs: PROBE_TIMEOUT_MS });
+        const output = `${stdout}\n${stderr}`;
+        if (code !== 0)
+            return { ok: false, error: lastLine(output) || `exit code ${code}` };
+        const version = output.match(/version:\s*([^\s]+)/)?.[1];
+        return { ok: true, version };
+    }
+    catch (error) {
+        return { ok: false, error: error?.message ?? String(error) };
+    }
+}
+function lastLine(text) {
+    return text.trim().split(/\r?\n/).pop()?.trim() ?? '';
+}
+/**
+ * Download the pinned release for this platform and install its whole bin
+ * folder into managedEngineDir(). Returns the verified binary path.
+ */
+export async function installLlamaEngine(onProgress, get) {
+    const platformKey = `${os.platform()}-${os.arch()}`;
+    const asset = releaseAssetFor(platformKey);
+    if (!asset) {
+        throw new Error(`No llama.cpp ${LLAMA_RELEASE_TAG} build is published for ${platformKey}. Install llama-cli on PATH or use a cloud provider.`);
+    }
+    const installDir = managedEngineDir();
+    const workDir = `${installDir}.partial`;
+    const zipPath = path.join(path.dirname(installDir), asset);
+    await fs.ensureDir(path.dirname(installDir));
+    await fs.remove(workDir);
+    onProgress?.(`⬇ Downloading inference engine (llama.cpp ${LLAMA_RELEASE_TAG})...`);
+    try {
+        await downloadToFile(`${LLAMA_RELEASE_BASE}/${asset}`, zipPath, { get });
+        onProgress?.('  Extracting...');
+        await extractZip(zipPath, workDir);
+        await installBinFolder(workDir, installDir);
+    }
+    finally {
+        await fs.remove(zipPath).catch(() => undefined);
+        await fs.remove(workDir).catch(() => undefined);
+    }
+    resetProbeCache();
+    const binary = managedEnginePath();
+    const probe = await probeBinary(binary);
+    if (!probe.ok) {
+        throw new Error(`Installed llama-cli does not run: ${probe.error}`);
+    }
+    onProgress?.(`✓ Inference engine ready (llama.cpp ${probe.version ?? LLAMA_RELEASE_TAG})`);
+    return binary;
+}
+async function extractZip(zipPath, destDir) {
+    await fs.ensureDir(destDir);
+    const result = os.platform() === 'win32'
+        ? await runProcess('powershell', ['-NoProfile', '-Command', `Expand-Archive -LiteralPath ${psQuote(zipPath)} -DestinationPath ${psQuote(destDir)} -Force`], { timeoutMs: EXTRACT_TIMEOUT_MS })
+        : await runProcess('unzip', ['-q', '-o', zipPath, '-d', destDir], { timeoutMs: EXTRACT_TIMEOUT_MS });
+    if (result.code !== 0) {
+        throw new Error(`Could not extract ${path.basename(zipPath)}: ${lastLine(result.stderr) || `exit code ${result.code}`}`);
+    }
+}
+/** PowerShell single-quoted literal: a quote inside is escaped by doubling it. */
+function psQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Copy the folder that contains llama-cli (binary + shared libraries) into place. */
+export async function installBinFolder(extractedRoot, installDir) {
+    const binary = await findFileRecursive(extractedRoot, llamaBinaryName());
+    if (!binary)
+        throw new Error(`${llamaBinaryName()} not found in the llama.cpp release archive`);
+    await fs.remove(installDir);
+    await fs.copy(path.dirname(binary), installDir);
+    if (os.platform() !== 'win32') {
+        await fs.chmod(path.join(installDir, llamaBinaryName()), 0o755);
+    }
+}
+/** Release archives nest the binary at most a few folders deep (build/bin/). */
+const MAX_ARCHIVE_DEPTH = 6;
+async function findFileRecursive(dir, filename, depth = 0) {
+    if (depth > MAX_ARCHIVE_DEPTH)
+        return null;
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const found = await findFileRecursive(fullPath, filename, depth + 1);
+            if (found)
+                return found;
+        }
+        else if (entry.name === filename) {
+            return fullPath;
+        }
+    }
+    return null;
+}

package/dist/inference/llama-engine.test.d.ts

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

package/dist/inference/llama-engine.test.js

@@ -0,0 +1,51 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { installBinFolder, llamaBinaryName, probeBinary, resetProbeCache } from './llama-engine.js';
+const isWindows = process.platform === 'win32';
+async function writeScript(file, body) {
+    await fs.outputFile(file, `#!/bin/sh\n${body}\n`);
+    await fs.chmod(file, 0o755);
+}
+describe.skipIf(isWindows)('probeBinary', () => {
+    let dir;
+    beforeEach(async () => {
+        dir = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-engine-'));
+        resetProbeCache();
+    });
+    afterEach(async () => { await fs.remove(dir); });
+    it('accepts a binary that reports its version', async () => {
+        const bin = path.join(dir, 'llama-cli');
+        await writeScript(bin, 'echo "version: 5604 (228f34c9)" >&2; exit 0');
+        expect(await probeBinary(bin)).toEqual({ ok: true, version: '5604' });
+    });
+    it('rejects the placeholder brain script', async () => {
+        const bin = path.join(dir, 'rigour-brain');
+        await writeScript(bin, 'echo "rigour-brain is a placeholder." >&2; exit 1');
+        const result = await probeBinary(bin);
+        expect(result.ok).toBe(false);
+        expect(result.error).toContain('placeholder');
+    });
+    it('rejects a missing binary', async () => {
+        expect((await probeBinary(path.join(dir, 'nope'))).ok).toBe(false);
+    });
+});
+describe('installBinFolder', () => {
+    let dir;
+    beforeEach(async () => { dir = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-engine-')); });
+    afterEach(async () => { await fs.remove(dir); });
+    it('installs the binary together with the shared libraries next to it', async () => {
+        const extracted = path.join(dir, 'extract', 'build', 'bin');
+        await fs.outputFile(path.join(extracted, llamaBinaryName()), 'bin');
+        await fs.outputFile(path.join(extracted, 'libllama.dylib'), 'lib');
+        await fs.outputFile(path.join(extracted, 'ggml-metal.metal'), 'metal');
+        const installDir = path.join(dir, 'llama-b5604');
+        await installBinFolder(path.join(dir, 'extract'), installDir);
+        expect((await fs.readdir(installDir)).sort()).toEqual(['ggml-metal.metal', 'libllama.dylib', llamaBinaryName()].sort());
+    });
+    it('fails clearly when the archive has no llama-cli', async () => {
+        await fs.outputFile(path.join(dir, 'extract', 'README.md'), 'x');
+        await expect(installBinFolder(path.join(dir, 'extract'), path.join(dir, 'out'))).rejects.toThrow('not found');
+    });
+});

package/dist/inference/llama-process.d.ts

@@ -0,0 +1,72 @@
+export interface ProcessResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export interface RunProcessOptions {
+    timeoutMs: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare class ProcessTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/**
+ * Run a binary with stdin closed, collecting stdout/stderr. Rejects on spawn
+ * errors and timeouts; a non-zero exit resolves with its code.
+ */
+export declare function runProcess(command: string, args: string[], options: RunProcessOptions): Promise<ProcessResult>;
+export interface LlamaArgsInput {
+    modelPath: string;
+    prompt: string;
+    maxTokens: number;
+    threads: number;
+    temperature: number;
+    schemaPath?: string;
+}
+export declare function buildLlamaArgs(input: LlamaArgsInput): string[];
+/**
+ * Context window large enough for prompt + output, rounded up to 1024 and
+ * clamped to what Qwen2.5-Coder was trained on. The b5604 default is 4096,
+ * which silently truncates code-bearing prompts.
+ */
+export declare function contextSizeFor(prompt: string, maxTokens: number): number;
+/** Remove llama-cli's end-of-generation marker from stdout. */
+export declare function cleanLlamaOutput(stdout: string): string;
+/** JSON schema matching DeepFinding, used to constrain local generation. */
+export declare const FINDINGS_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly findings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly category: {
+                        readonly type: "string";
+                    };
+                    readonly severity: {
+                        readonly type: "string";
+                        readonly enum: readonly ["critical", "high", "medium", "low", "info"];
+                    };
+                    readonly file: {
+                        readonly type: "string";
+                    };
+                    readonly line: {
+                        readonly type: readonly ["integer", "null"];
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly suggestion: {
+                        readonly type: "string";
+                    };
+                    readonly confidence: {
+                        readonly type: "number";
+                    };
+                };
+                readonly required: readonly ["category", "severity", "file", "description", "suggestion", "confidence"];
+            };
+        };
+    };
+    readonly required: readonly ["findings"];
+};

package/dist/inference/llama-process.js

@@ -0,0 +1,126 @@
+/**
+ * Process runner and argument builder for llama-cli (llama.cpp b5604).
+ *
+ * Flags verified against b5604:
+ * - `-st` applies the model's chat template for one turn, then exits. Without
+ *   it an instruct model starts an interactive chat and waits on stdin;
+ *   `-no-cnv` avoids that but treats the prompt as raw text to continue.
+ * - `--json-schema-file` constrains output to the findings schema. There is
+ *   no `--json` flag; b5604 rejects it.
+ * - `--log-disable` is NOT used: in b5604 it also suppresses the generated
+ *   text, so stdout comes back empty.
+ * - `--seed` is fixed: llama.cpp otherwise draws a random seed per run, so
+ *   the same file could pass one CI run and fail the next.
+ */
+import { spawn } from 'child_process';
+const MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
+const MIN_CONTEXT = 4096;
+const MAX_CONTEXT = 32768;
+/** Conservative characters-per-token for code and JSON-ish prompts. */
+const CHARS_PER_TOKEN = 3;
+const FIXED_SEED = 42;
+export class ProcessTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`timed out after ${timeoutMs / 1000}s`);
+        this.name = 'ProcessTimeoutError';
+    }
+}
+/**
+ * Run a binary with stdin closed, collecting stdout/stderr. Rejects on spawn
+ * errors and timeouts; a non-zero exit resolves with its code.
+ */
+export function runProcess(command, args, options) {
+    const isWindowsScript = process.platform === 'win32' && /\.(cmd|bat)$/i.test(command);
+    const [bin, argv] = isWindowsScript
+        ? ['cmd.exe', ['/d', '/s', '/c', [command, ...args].map(quoteCmdArg).join(' ')]]
+        : [command, args];
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, argv, { stdio: ['ignore', 'pipe', 'pipe'], env: options.env, windowsHide: true });
+        const stdout = new BoundedBuffer();
+        const stderr = new BoundedBuffer();
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new ProcessTimeoutError(options.timeoutMs));
+        }, options.timeoutMs);
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout: stdout.toString(), stderr: stderr.toString() });
+        });
+    });
+}
+class BoundedBuffer {
+    chunks = [];
+    size = 0;
+    push(chunk) {
+        if (this.size >= MAX_OUTPUT_BYTES)
+            return;
+        this.chunks.push(chunk);
+        this.size += chunk.length;
+    }
+    toString() {
+        return Buffer.concat(this.chunks).toString('utf8');
+    }
+}
+function quoteCmdArg(value) {
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+export function buildLlamaArgs(input) {
+    const args = [
+        '--model', input.modelPath,
+        '--prompt', input.prompt,
+        '--n-predict', String(input.maxTokens),
+        '--threads', String(input.threads),
+        '--temp', String(input.temperature),
+        '--seed', String(FIXED_SEED),
+        '--ctx-size', String(contextSizeFor(input.prompt, input.maxTokens)),
+        '--no-display-prompt',
+        '-st',
+        '--simple-io',
+    ];
+    if (input.schemaPath)
+        args.push('--json-schema-file', input.schemaPath);
+    return args;
+}
+/**
+ * Context window large enough for prompt + output, rounded up to 1024 and
+ * clamped to what Qwen2.5-Coder was trained on. The b5604 default is 4096,
+ * which silently truncates code-bearing prompts.
+ */
+export function contextSizeFor(prompt, maxTokens) {
+    const needed = Math.ceil(prompt.length / CHARS_PER_TOKEN) + maxTokens + 256;
+    const rounded = Math.ceil(needed / 1024) * 1024;
+    return Math.min(MAX_CONTEXT, Math.max(MIN_CONTEXT, rounded));
+}
+/** Remove llama-cli's end-of-generation marker from stdout. */
+export function cleanLlamaOutput(stdout) {
+    return stdout.replace(/\s*\[end of text\]\s*$/, '').trim();
+}
+/** JSON schema matching DeepFinding, used to constrain local generation. */
+export const FINDINGS_JSON_SCHEMA = {
+    type: 'object',
+    properties: {
+        findings: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    category: { type: 'string' },
+                    severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'] },
+                    file: { type: 'string' },
+                    line: { type: ['integer', 'null'] },
+                    description: { type: 'string' },
+                    suggestion: { type: 'string' },
+                    confidence: { type: 'number' },
+                },
+                required: ['category', 'severity', 'file', 'description', 'suggestion', 'confidence'],
+            },
+        },
+    },
+    required: ['findings'],
+};

package/dist/inference/llama-process.test.d.ts

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

package/dist/inference/llama-process.test.js

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { buildLlamaArgs, cleanLlamaOutput, contextSizeFor, runProcess } from './llama-process.js';
+const base = { modelPath: '/m.gguf', prompt: 'hello', maxTokens: 1024, threads: 4, temperature: 0.1 };
+describe('buildLlamaArgs', () => {
+    it('uses flags llama.cpp b5604 accepts and that keep generated text on stdout', () => {
+        const args = buildLlamaArgs(base);
+        expect(args).toContain('-st');
+        expect(args).toContain('--simple-io');
+        expect(args).toContain('--no-display-prompt');
+        expect(args).not.toContain('--json');
+        expect(args).not.toContain('--log-disable');
+    });
+    it('fixes the seed so a run is reproducible', () => {
+        const args = buildLlamaArgs(base);
+        expect(args[args.indexOf('--seed') + 1]).toBe('42');
+    });
+    it('constrains output with the findings schema file when given', () => {
+        const args = buildLlamaArgs({ ...base, schemaPath: '/schema.json' });
+        expect(args.slice(-2)).toEqual(['--json-schema-file', '/schema.json']);
+        expect(buildLlamaArgs(base)).not.toContain('--json-schema-file');
+    });
+    it('passes a context size that fits the prompt', () => {
+        const args = buildLlamaArgs({ ...base, prompt: 'x'.repeat(30_000) });
+        expect(Number(args[args.indexOf('--ctx-size') + 1])).toBe(contextSizeFor('x'.repeat(30_000), 1024));
+    });
+});
+describe('contextSizeFor', () => {
+    it('never goes below the 4096 default', () => {
+        expect(contextSizeFor('short', 512)).toBe(4096);
+    });
+    it('grows with the prompt, rounded up to 1024', () => {
+        const size = contextSizeFor('x'.repeat(30_000), 1024);
+        expect(size).toBeGreaterThanOrEqual(10_000 + 1024);
+        expect(size % 1024).toBe(0);
+    });
+    it('is capped at the model training context', () => {
+        expect(contextSizeFor('x'.repeat(1_000_000), 1024)).toBe(32768);
+    });
+});
+describe('cleanLlamaOutput', () => {
+    it('strips the end-of-generation marker', () => {
+        expect(cleanLlamaOutput('{"findings": []} [end of text]\n\n')).toBe('{"findings": []}');
+    });
+});
+describe('runProcess', () => {
+    it('collects stdout and stderr and returns the exit code', async () => {
+        const result = await runProcess(process.execPath, ['-e', 'process.stdout.write("out");process.stderr.write("err");process.exit(3)'], { timeoutMs: 10_000 });
+        expect(result).toEqual({ code: 3, stdout: 'out', stderr: 'err' });
+    });
+    it('runs with stdin closed so an interactive binary cannot wait on it', async () => {
+        const result = await runProcess(process.execPath, ['-e', 'process.stdin.on("end",()=>process.stdout.write("eof")).resume()'], { timeoutMs: 10_000 });
+        expect(result.stdout).toBe('eof');
+    });
+    it('kills and rejects on timeout', async () => {
+        await expect(runProcess(process.execPath, ['-e', 'setTimeout(()=>{}, 10_000)'], { timeoutMs: 100 }))
+            .rejects.toThrow('timed out');
+    });
+    it('rejects when the binary cannot be spawned', async () => {
+        await expect(runProcess('/nonexistent/llama-cli', [], { timeoutMs: 1_000 })).rejects.toThrow();
+    });
+});

package/dist/inference/model-download.test.d.ts

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

package/dist/inference/model-download.test.js

@@ -0,0 +1,73 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { createHash } from 'crypto';
+import { Readable } from 'stream';
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+const home = vi.hoisted(() => {
+    const p = require('path');
+    const o = require('os');
+    return p.join(o.tmpdir(), `rigour-models-${process.pid}-${Date.now()}`);
+});
+vi.mock('../storage/db.js', () => ({ RIGOUR_DIR: home }));
+const { downloadModel, getCachedModel } = await import('./model-manager.js');
+const { FALLBACK_MODELS, MODELS } = await import('./types.js');
+const modelsDir = path.join(home, 'models');
+const PAYLOAD = Buffer.from('gguf-model-bytes');
+const PAYLOAD_SHA = createHash('sha256').update(PAYLOAD).digest('hex');
+function ok(body, sha) {
+    return Promise.resolve({ statusCode: 200, headers: { 'x-linked-etag': `"${sha}"` }, body: Readable.from([body]) });
+}
+const unauthorized = Promise.resolve({ statusCode: 401, headers: {}, body: Readable.from([]) });
+describe('downloadModel', () => {
+    beforeEach(async () => {
+        await fs.remove(home);
+        // A fresh version check: no network call to Hugging Face.
+        await fs.outputJson(path.join(modelsDir, '.latest_version.json'), { version: '2.0.0', checkedAt: new Date().toISOString() });
+    });
+    afterAll(async () => { await fs.remove(home); });
+    it('falls back to the stock model when the fine-tuned model is unavailable, and says so', async () => {
+        const requested = [];
+        const get = (url) => {
+            requested.push(url);
+            return url.includes('rigour-labs/') ? unauthorized : ok(PAYLOAD, PAYLOAD_SHA);
+        };
+        const messages = [];
+        const modelPath = await downloadModel('lite', m => messages.push(m), get);
+        expect(requested).toEqual([MODELS.lite.url, FALLBACK_MODELS.lite.url]);
+        expect(path.basename(modelPath)).toBe(FALLBACK_MODELS.lite.filename);
+        expect(messages.some(m => m.includes('Fine-tuned model unavailable (HTTP 401'))).toBe(true);
+        const meta = await fs.readJson(`${modelPath}.meta.json`);
+        expect(meta).toMatchObject({ sha256: PAYLOAD_SHA, sizeBytes: PAYLOAD.length, sourceUrl: FALLBACK_MODELS.lite.url });
+    });
+    it('rejects a checksum mismatch and deletes the partial download', async () => {
+        const get = () => ok(PAYLOAD, 'f'.repeat(64));
+        await expect(downloadModel('lite', undefined, get)).rejects.toThrow('Checksum mismatch');
+        expect(await fs.pathExists(path.join(modelsDir, `${FALLBACK_MODELS.lite.filename}.download`))).toBe(false);
+        expect(await fs.pathExists(path.join(modelsDir, FALLBACK_MODELS.lite.filename))).toBe(false);
+    });
+});
+describe('getCachedModel', () => {
+    beforeEach(async () => { await fs.remove(home); });
+    async function cacheFile(filename, sizeBytes) {
+        const file = path.join(modelsDir, filename);
+        await fs.ensureDir(modelsDir);
+        await fs.writeFile(file, '');
+        await fs.truncate(file, sizeBytes); // sparse: no real disk use
+        await fs.writeJson(`${file}.meta.json`, {
+            sha256: 'a'.repeat(64), sizeBytes, verifiedAt: new Date(Date.now() + 1000).toISOString(), sourceUrl: 'https://x',
+        });
+    }
+    it('returns null when nothing is cached', async () => {
+        expect(await getCachedModel('deep')).toBeNull();
+    });
+    it('reports the stock fallback when only it is cached', async () => {
+        await cacheFile(FALLBACK_MODELS.deep.filename, FALLBACK_MODELS.deep.sizeBytes);
+        const cached = await getCachedModel('deep');
+        expect(cached).toMatchObject({ fallback: true, info: { filename: FALLBACK_MODELS.deep.filename } });
+    });
+    it('ignores a file without verified metadata', async () => {
+        await fs.ensureDir(modelsDir);
+        await fs.writeFile(path.join(modelsDir, FALLBACK_MODELS.deep.filename), 'partial');
+        expect(await getCachedModel('deep')).toBeNull();
+    });
+});

package/dist/inference/model-manager.d.ts

@@ -1,3 +1,4 @@
+import { type HttpGet } from './http-download.js';
 import { type ModelTier, type ModelInfo } from './types.js';
 export declare function extractSha256FromEtag(etag: string | null): string | null;
 export declare function hashFileSha256(filePath: string): Promise<string>;
@@ -5,8 +6,20 @@ export declare function hashFileSha256(filePath: string): Promise<string>;
  * Check if any model for this tier is cached (fine-tuned or fallback).
  */
 export declare function isModelCached(tier: ModelTier): Promise<boolean>;
+export interface CachedModel {
+    path: string;
+    info: ModelInfo;
+    /** True when the stock fallback is in use because the fine-tuned model is not cached. */
+    fallback: boolean;
+}
+/**
+ * The verified model file for a tier, preferring the fine-tuned model over
+ * the stock fallback. Null when neither is cached and verified.
+ */
+export declare function getCachedModel(tier: ModelTier): Promise<CachedModel | null>;
 /**
  * Get the path to a cached model (prefers fine-tuned over fallback).
+ * Existence only; use getCachedModel() for a verified file.
  */
 export declare function getModelPath(tier: ModelTier): string;
 /**
@@ -25,7 +38,7 @@ export declare function checkForUpdates(onProgress?: (message: string, percent?:
  * Download a model from HuggingFace CDN.
  * Checks for updates first, then tries fine-tuned model, falls back to stock Qwen.
  */
-export declare function downloadModel(tier: ModelTier, onProgress?: (message: string, percent?: number) => void): Promise<string>;
+export declare function downloadModel(tier: ModelTier, onProgress?: (message: string, percent?: number) => void, get?: HttpGet): Promise<string>;
 /**
  * Ensure a model is available, downloading if needed.
  */