@rigour-labs/core 6.2.4 → 6.3.0

package/dist/gates/side-effect-helpers/pattern-detection.js

@@ -71,7 +71,7 @@ export function pathsOverlap(watchPath, writePath) {
 // ═══════════════════════════════════════════════════════════════════
 // LOOP & RECURSION ANALYSIS — Context-aware body extraction
 // ═══════════════════════════════════════════════════════════════════
-import { findBlockEndBrace, findBlockEndIndent } from './scope-analysis.js';
+import { findBlockEndBrace, findBlockEndIndent, findExpressionEnd } from './scope-analysis.js';
 /**
  * Extract loop body with correct scope tracking.
  * Uses brace/indent matching (not just "next N lines").
@@ -122,13 +122,24 @@ export function extractFunctionDefs(lines, lang) {
                 ? findBlockEndIndent(lines, i)
                 : lang === 'rb'
                     ? findBlockEndRuby(lines, i)
-                    : findBlockEndBrace(lines, i);
+                    : isExpressionArrow(lines, i, stripped, m.index) ? findExpressionEnd(lines, i) : findBlockEndBrace(lines, i);
             defs.push({ name, start: i, end, params: lines[i] });
             break;
         }
     }
     return defs;
 }
+/** An arrow whose body is an expression, not a `{ ... }` block. */
+function isExpressionArrow(lines, line, stripped, matchAt) {
+    const arrow = stripped.indexOf('=>', matchAt);
+    if (arrow < 0)
+        return false;
+    const rest = stripped.slice(arrow + 2).trim();
+    if (rest !== '')
+        return !rest.startsWith('{');
+    const next = lines.slice(line + 1).find(l => l.trim() !== '');
+    return next !== undefined && !next.trim().startsWith('{');
+}
 function getFuncDefPatterns(lang) {
     switch (lang) {
         case 'py': return [/^\s*(?:async\s+)?def\s+(\w+)\s*\(/];
@@ -297,11 +308,24 @@ export function hasCatchWithContinue(body, lang) {
 // ═══════════════════════════════════════════════════════════════════
 // PROCESS & TIMER OPERATIONS
 // ═══════════════════════════════════════════════════════════════════
+/**
+ * Drop a trailing line comment (and whole comment lines) so prose such as
+ * "ported from the fork (verified …)" is not read as code. Strings are
+ * already blanked, so `//` inside a URL string is gone before this runs.
+ */
+function stripLineComment(line, lang) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('*') || trimmed.startsWith('/*'))
+        return '';
+    const marker = lang === 'py' || lang === 'rb' ? '#' : '//';
+    const at = line.indexOf(marker);
+    return at === -1 ? line : line.slice(0, at);
+}
 /**
  * Check if a line contains a process spawn call.
  */
 export function isProcessSpawn(line, lang) {
-    const stripped = stripStrings(line);
+    const stripped = stripLineComment(stripStrings(line), lang);
     const patterns = getSpawnPatterns(lang);
     for (const pat of patterns) {
         const m = pat.exec(stripped);
@@ -314,9 +338,13 @@ function getSpawnPatterns(lang) {
     switch (lang) {
         case 'js':
         case 'ts':
+            // A bare call (from a child_process import) or a call on a
+            // child_process namespace; `re.exec(src)` or `db.exec(sql)` is not a
+            // spawn. *Sync variants finish before returning, so they cannot orphan.
             return [
-                /\b(?:spawn|exec|execFile|fork|execa)\s*\(/,
-                /\bchild_process\.\w+\s*\(/,
+                /(?<![.\w$])(?:spawn|exec|execFile|fork)\s*\(/,
+                /(?<![.\w$])(?:execa|execaCommand)\s*\(/,
+                /\b(?:child_process|childProcess|cp)\.(?:spawn|exec|execFile|fork)\s*\(/,
             ];
         case 'py':
             return [
@@ -354,9 +382,9 @@ function getTimerCreatePatterns(lang) {
     switch (lang) {
         case 'js':
         case 'ts':
+            // setTimeout fires once and cannot run unbounded; only setInterval repeats.
             return [
                 [/\bsetInterval\s*\(/, 'setInterval'],
-                [/\bsetTimeout\s*\(/, 'setTimeout'],
             ];
         case 'py':
             return [
@@ -410,7 +438,7 @@ export function getProcessCleanupPatterns(lang) {
         case 'js':
         case 'ts':
             return [
-                /\.on\s*\(\s*['"](?:exit|close)['"]/,
+                /\.(?:on|once|addListener)\s*\(\s*['"](?:exit|close)['"]/,
                 /\.kill\s*\(/,
                 /\.disconnect\s*\(/,
             ];

package/dist/gates/side-effect-helpers/resource-tracking.js

@@ -39,8 +39,8 @@ export function extractVariableBinding(line, lang) {
     const jsMatch = stripped.match(/^(?:const|let|var|final|auto|val)\s+(\w+)\s*=\s*/);
     if (jsMatch)
         return jsMatch[1];
-    // Member assignment: `this.timer = ...`, `self.timer = ...`
-    const memberMatch = stripped.match(/^(?:this|self)\.([\w]+)\s*=\s*/);
+    // Member assignment: `this.timer = ...`, `self.timer = ...`, `this.#timer = ...`
+    const memberMatch = stripped.match(/^(?:this|self)\.(#?[\w]+)\s*=\s*/);
     if (memberMatch)
         return memberMatch[1];
     // Simple assignment: `timer = ...`
@@ -68,26 +68,33 @@ export function hasCleanupForVariable(lines, varName, scopeStart, scopeEnd, clea
     const scope = lines.slice(scopeStart, scopeEnd);
     for (let i = 0; i < scope.length; i++) {
         const stripped = stripStrings(scope[i]);
-        // Check cleanup patterns that reference the specific variable
+        // Check cleanup patterns that reference the specific variable. Some
+        // patterns need the quoted event name (`.once('exit', …)`), which
+        // stripStrings blanks, so they are also tried on the raw line.
         for (const pat of cleanupPatterns) {
-            if (!pat.test(stripped))
+            if (!pat.test(stripped) && !pat.test(scope[i]))
                 continue;
-            // The cleanup call should reference our variable
-            const escapedVar = varName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            const varRef = new RegExp(`\\b${escapedVar}\\b`);
-            if (varRef.test(stripped))
+            // The cleanup call should reference our variable. Lookarounds, not
+            // \b, so a private field such as `#timer` matches too.
+            if (variableReference(varName).test(stripped))
                 return true;
             // Also check method calls on the variable: timer.close(), timer.stop()
             // The pattern might match a generic .close() — check if it's on our var
         }
         // Direct method cleanup on the variable: varName.close(), varName.Stop()
-        const escapedVar = varName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        const methodCleanup = new RegExp(`\\b${escapedVar}\\.(?:close|stop|destroy|kill|terminate|dispose|cancel|shutdown|unsubscribe|disconnect|end|release|Clear|Stop|Dispose|Close|Cancel)\\s*\\(`);
+        const escapedVar = escapeRegExp(varName);
+        const methodCleanup = new RegExp(`(?<![\\w$#])${escapedVar}\\.(?:close|stop|destroy|kill|terminate|dispose|cancel|shutdown|unsubscribe|disconnect|end|release|Clear|Stop|Dispose|Close|Cancel)\\s*\\(`);
         if (methodCleanup.test(stripped))
             return true;
     }
     return false;
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function variableReference(varName) {
+    return new RegExp(`(?<![\\w$#])${escapeRegExp(varName)}(?![\\w$])`);
+}
 /**
  * Check if a line is inside a cleanup/teardown context.
  *

package/dist/gates/side-effect-helpers/scope-analysis.d.ts

@@ -14,6 +14,12 @@ export declare function findEnclosingFunction(lines: string[], lineIdx: number,
  * Find the end of a brace-delimited block starting at `start`.
  */
 export declare function findBlockEndBrace(lines: string[], start: number): number;
+/**
+ * Find the end of an expression-bodied arrow (`const f = (x) => x + 1;`):
+ * the first line where brackets balance and the expression does not
+ * continue. Scanning for a `{` instead would run into the next block.
+ */
+export declare function findExpressionEnd(lines: string[], start: number): number;
 /**
  * Find the end of an indentation-delimited block (Python).
  */

package/dist/gates/side-effect-helpers/scope-analysis.js

@@ -95,6 +95,26 @@ export function findBlockEndBrace(lines, start) {
     }
     return maxScan;
 }
+/**
+ * Find the end of an expression-bodied arrow (`const f = (x) => x + 1;`):
+ * the first line where brackets balance and the expression does not
+ * continue. Scanning for a `{` instead would run into the next block.
+ */
+export function findExpressionEnd(lines, start) {
+    let depth = 0;
+    const maxScan = Math.min(lines.length, start + 300);
+    for (let j = start; j < maxScan; j++) {
+        const stripped = stripStrings(lines[j]);
+        depth += bracketDelta(stripped);
+        const continues = /(?:=>|[=+\-*/%&|?:,.(])\s*$/.test(stripped.trimEnd());
+        if (depth <= 0 && !continues)
+            return j + 1;
+    }
+    return maxScan;
+}
+function bracketDelta(text) {
+    return (text.match(/[([{]/g)?.length ?? 0) - (text.match(/[)\]}]/g)?.length ?? 0);
+}
 /**
  * Find the end of an indentation-delimited block (Python).
  */

package/dist/gates/style-drift.js

@@ -24,6 +24,7 @@ import { FileScanner } from '../utils/scanner.js';
 import { Logger } from '../utils/logger.js';
 import { languageAdapters } from './language-adapters/index.js';
 import { extractComparableJsNames } from './js-style-context.js';
+import { isScoped } from '../utils/scope.js';
 import { TRY_CATCH_PATTERN, CATCH_PATTERN, RESULT_TYPE_PATTERN, NAMED_IMPORT_PATTERN, WILDCARD_IMPORT_PATTERN, SIDE_EFFECT_IMPORT_PATTERN, DEFAULT_IMPORT_PATTERN, countQuotes, } from './style-drift-rules.js';
 import fs from 'fs-extra';
 import path from 'path';
@@ -79,6 +80,8 @@ export class StyleDriftGate extends Gate {
                 Logger.debug('Failed to load style baseline, will create new one');
             }
         }
+        if (!baseline && isScoped(context.patterns))
+            return []; // never baseline from a subset of files
         if (!baseline) {
             // First scan: create per-language baseline
             baseline = await this.computePerLanguageBaseline(context, filesByLang);

package/dist/index.d.ts

@@ -9,6 +9,9 @@ export { RetryLoopBreakerGate } from './gates/retry-loop-breaker.js';
 export { SideEffectAnalysisGate } from './gates/side-effect-analysis/index.js';
 export { FrontendSecretExposureGate } from './gates/frontend-secret-exposure.js';
 export * from './utils/logger.js';
+export { normalizeScopePatterns, isScoped } from './utils/scope.js';
+export { deepAnalysisError } from './utils/deep-status.js';
+export { parseDiff, changedLinesByFile } from './utils/diff.js';
 export { FileScanner } from './utils/scanner.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
@@ -18,7 +21,9 @@ export { DeepAnalysisGate } from './gates/deep-analysis.js';
 export { createProvider } from './inference/index.js';
 export type { InferenceProvider, DeepFinding, DeepAnalysisResult, ModelTier } from './inference/types.js';
 export { MODELS } from './inference/types.js';
-export { isModelCached, getModelsDir, getModelInfo } from './inference/model-manager.js';
+export { isModelCached, getModelsDir, getModelInfo, getCachedModel, ensureModel } from './inference/model-manager.js';
+export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG } from './inference/llama-engine.js';
+export { SidecarProvider } from './inference/sidecar-provider.js';
 export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 export type { RigourDB, CompactResult } from './storage/index.js';
@@ -26,7 +31,7 @@ export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './stor
 export type { ProjectStats } from './storage/index.js';
 export { recordInteractionEvidence, countInteractionEvidence, recordInteractionLesson, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId, queueLocalLessonsForTeam } from './storage/index.js';
 export type { ApplicableLessons, InteractionEvidence, LessonRecord, LessonState, LessonVisibility, LocalLessonImportOptions, LocalLessonImportResult } from './storage/index.js';
-export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, } from './storage/index.js';
+export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, explainTeamConnectionError, } from './storage/index.js';
 export type { TeamConfiguration, TeamSemanticConfiguration, TeamModeStatus, TeamDoctorResult, SemanticKnowledgeCandidate, SemanticKnowledgeResult, } from './storage/index.js';
 export { generateTemporalDriftReport, formatDriftSummary } from './services/temporal-drift.js';
 export type { TemporalDriftReport, ProvenanceStream, MonthlyBucket, WeeklyBucket, DriftDirection } from './services/temporal-drift.js';
@@ -46,4 +51,8 @@ export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';
 export * from './firewall/index.js';
+export { learnFromFix, type LearnReport, type Rejection } from './semantic/learn/learn.js';
+export { extractFixTrees, type FixTrees } from './semantic/learn/git-trees.js';
+export { saveLearnedRule, loadLearnedRules, LEARNED_RULES_DIR } from './semantic/learn/store.js';
+export type { LearnedRule, LearnedPattern } from './semantic/learn/types.js';
 export { recordContextEvent, recordModelUsage, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics, } from './storage/index.js';

package/dist/index.js

@@ -9,6 +9,9 @@ export { RetryLoopBreakerGate } from './gates/retry-loop-breaker.js';
 export { SideEffectAnalysisGate } from './gates/side-effect-analysis/index.js';
 export { FrontendSecretExposureGate } from './gates/frontend-secret-exposure.js';
 export * from './utils/logger.js';
+export { normalizeScopePatterns, isScoped } from './utils/scope.js';
+export { deepAnalysisError } from './utils/deep-status.js';
+export { parseDiff, changedLinesByFile } from './utils/diff.js';
 export { FileScanner } from './utils/scanner.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
@@ -18,14 +21,16 @@ export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getPro
 export { DeepAnalysisGate } from './gates/deep-analysis.js';
 export { createProvider } from './inference/index.js';
 export { MODELS } from './inference/types.js';
-export { isModelCached, getModelsDir, getModelInfo } from './inference/model-manager.js';
+export { isModelCached, getModelsDir, getModelInfo, getCachedModel, ensureModel } from './inference/model-manager.js';
+export { installLlamaEngine, probeBinary, managedEnginePath, LLAMA_RELEASE_TAG } from './inference/llama-engine.js';
+export { SidecarProvider } from './inference/sidecar-provider.js';
 export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
 // Storage (SQLite Brain)
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 // Local Project Memory (hybrid intelligence — SQLite-backed per-project learning)
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';
 export { recordInteractionEvidence, countInteractionEvidence, recordInteractionLesson, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId, queueLocalLessonsForTeam } from './storage/index.js';
-export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, } from './storage/index.js';
+export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, explainTeamConnectionError, } from './storage/index.js';
 // Temporal Drift Engine (v5 — cross-session trend analysis + per-provenance EWMA)
 export { generateTemporalDriftReport, formatDriftSummary } from './services/temporal-drift.js';
 // Adaptive Thresholds (v5 — Z-score + per-provenance trends)
@@ -45,6 +50,9 @@ export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';
 export * from './firewall/index.js';
+export { learnFromFix } from './semantic/learn/learn.js';
+export { extractFixTrees } from './semantic/learn/git-trees.js';
+export { saveLearnedRule, loadLearnedRules, LEARNED_RULES_DIR } from './semantic/learn/store.js';
 export { recordContextEvent, recordModelUsage, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics, } from './storage/index.js';
 // Pattern Index is intentionally NOT exported here to prevent
 // native dependency issues (sharp/transformers) from leaking into

package/dist/inference/http-download.d.ts

@@ -0,0 +1,22 @@
+import { type Readable } from 'stream';
+export interface HttpResponse {
+    statusCode: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: Readable;
+}
+export type HttpGet = (url: string, headers: Record<string, string>, timeoutMs: number) => Promise<HttpResponse>;
+export interface DownloadOptions {
+    onProgress?: (downloadedBytes: number, totalBytes: number | null) => void;
+    stallTimeoutMs?: number;
+    /** Resume from an existing partial file at `destPath` (default true). */
+    resume?: boolean;
+    /** Transport override for tests. */
+    get?: HttpGet;
+}
+export interface DownloadResult {
+    sha256: string;
+    bytes: number;
+    /** ETag seen on any hop; Hugging Face exposes the LFS SHA-256 as x-linked-etag. */
+    etag: string | null;
+}
+export declare function downloadToFile(url: string, destPath: string, options?: DownloadOptions): Promise<DownloadResult>;

package/dist/inference/http-download.js

@@ -0,0 +1,132 @@
+/**
+ * Streaming HTTPS download for large binaries (models, engine archives).
+ *
+ * Uses node:https rather than global fetch: on large Hugging Face downloads
+ * undici's fetch measured ~1.7 MB/s where node:https reached ~17 MB/s on the
+ * same host and byte range, which made the first-run model download exceed
+ * any reasonable setup window.
+ *
+ * - follows at most MAX_REDIRECTS redirects, https only
+ * - resumes a kept partial file with a Range request (the prefix is re-hashed
+ *   so the SHA-256 still covers the whole file)
+ * - aborts when no bytes arrive for `stallTimeoutMs` instead of imposing a
+ *   wall-clock limit that a slow but healthy connection cannot meet
+ */
+import https from 'https';
+import fs from 'fs-extra';
+import { createHash } from 'crypto';
+import { Transform } from 'stream';
+import { pipeline } from 'stream/promises';
+const MAX_REDIRECTS = 5;
+const DEFAULT_STALL_TIMEOUT_MS = 30_000;
+export async function downloadToFile(url, destPath, options = {}) {
+    const stallMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+    const get = options.get ?? httpsGet;
+    let existing = options.resume === false ? 0 : await partialSize(destPath);
+    let { response, etag } = await followRedirects(url, rangeFrom(existing), get, stallMs);
+    if (response.statusCode === 416 && existing > 0) {
+        // The partial is already at or past the end: start over once, from zero.
+        response.body.resume();
+        await fs.remove(destPath);
+        existing = 0;
+        ({ response, etag } = await followRedirects(url, rangeFrom(0), get, stallMs));
+    }
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+        response.body.resume();
+        throw new Error(`HTTP ${response.statusCode} for ${url}`);
+    }
+    const resumed = response.statusCode === 206 && existing > 0;
+    const hash = createHash('sha256');
+    if (resumed)
+        await hashFilePrefix(destPath, hash);
+    const startBytes = resumed ? existing : 0;
+    const total = contentLength(response.headers, startBytes);
+    const bytes = await writeBody(response.body, destPath, hash, {
+        append: resumed, startBytes, total, stallMs, onProgress: options.onProgress,
+    });
+    return { sha256: hash.digest('hex'), bytes, etag };
+}
+function rangeFrom(offset) {
+    return offset > 0 ? { Range: `bytes=${offset}-` } : {};
+}
+async function partialSize(filePath) {
+    try {
+        return (await fs.stat(filePath)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+async function followRedirects(url, headers, get, timeoutMs) {
+    let current = url;
+    let etag = null;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        if (new URL(current).protocol !== 'https:') {
+            throw new Error(`Refusing non-https download URL: ${current}`);
+        }
+        const response = await get(current, headers, timeoutMs);
+        etag = etag ?? headerValue(response.headers, 'x-linked-etag') ?? headerValue(response.headers, 'etag');
+        const location = headerValue(response.headers, 'location');
+        if (response.statusCode >= 300 && response.statusCode < 400 && location) {
+            response.body.resume();
+            current = new URL(location, current).toString();
+            continue;
+        }
+        return { response, etag };
+    }
+    throw new Error(`Too many redirects downloading ${url}`);
+}
+async function writeBody(body, destPath, hash, opts) {
+    let downloaded = opts.startBytes;
+    let stallTimer;
+    const armStall = () => {
+        clearTimeout(stallTimer);
+        stallTimer = setTimeout(() => {
+            body.destroy(new Error(`Download stalled: no data for ${opts.stallMs / 1000}s`));
+        }, opts.stallMs);
+    };
+    const tap = new Transform({
+        transform(chunk, _encoding, callback) {
+            armStall();
+            hash.update(chunk);
+            downloaded += chunk.length;
+            opts.onProgress?.(downloaded, opts.total);
+            callback(null, chunk);
+        },
+    });
+    armStall();
+    try {
+        await pipeline(body, tap, fs.createWriteStream(destPath, { flags: opts.append ? 'a' : 'w' }));
+    }
+    finally {
+        clearTimeout(stallTimer);
+    }
+    return downloaded;
+}
+async function hashFilePrefix(filePath, hash) {
+    const stream = fs.createReadStream(filePath);
+    try {
+        for await (const chunk of stream)
+            hash.update(chunk);
+    }
+    finally {
+        stream.destroy();
+    }
+}
+function contentLength(headers, offset) {
+    const value = Number(headerValue(headers, 'content-length'));
+    return Number.isFinite(value) && value > 0 ? value + offset : null;
+}
+function headerValue(headers, name) {
+    const value = headers[name];
+    if (Array.isArray(value))
+        return value[0] ?? null;
+    return value ?? null;
+}
+const httpsGet = (url, headers, timeoutMs) => new Promise((resolve, reject) => {
+    const request = https.get(url, { headers: { 'user-agent': 'rigour-cli', ...headers } }, (res) => {
+        resolve({ statusCode: res.statusCode ?? 0, headers: res.headers, body: res });
+    });
+    request.setTimeout(timeoutMs, () => request.destroy(new Error(`No response from ${new URL(url).host} after ${timeoutMs / 1000}s`)));
+    request.on('error', reject);
+});

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

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

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

@@ -0,0 +1,109 @@
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { createHash } from 'crypto';
+import { Readable, PassThrough } from 'stream';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { downloadToFile } from './http-download.js';
+const PAYLOAD = Buffer.from('0123456789abcdefghijklmnopqrstuvwxyz');
+const sha = (b) => createHash('sha256').update(b).digest('hex');
+function response(statusCode, body = Buffer.alloc(0), headers = {}) {
+    return { statusCode, headers, body: Buffer.isBuffer(body) ? Readable.from([body]) : body };
+}
+/** Serves PAYLOAD, honouring Range unless told not to. */
+function server(opts = {}) {
+    const calls = [];
+    const get = async (url, headers) => {
+        calls.push({ url, headers });
+        const range = headers.Range?.match(/bytes=(\d+)-/);
+        if (range && opts.honourRange !== false) {
+            const start = Number(range[1]);
+            if (start >= PAYLOAD.length)
+                return response(416);
+            return response(206, PAYLOAD.subarray(start), { 'content-length': String(PAYLOAD.length - start) });
+        }
+        return response(200, PAYLOAD, { 'content-length': String(PAYLOAD.length), etag: opts.etag });
+    };
+    return { get, calls };
+}
+describe('downloadToFile', () => {
+    let dir;
+    let dest;
+    beforeEach(async () => {
+        dir = await fs.mkdtemp(path.join(os.tmpdir(), 'rigour-dl-'));
+        dest = path.join(dir, 'model.gguf.download');
+    });
+    afterEach(async () => { await fs.remove(dir); });
+    it('downloads the full body and hashes it', async () => {
+        const { get } = server({ etag: '"abc"' });
+        const result = await downloadToFile('https://host/model', dest, { get });
+        expect(await fs.readFile(dest)).toEqual(PAYLOAD);
+        expect(result).toEqual({ sha256: sha(PAYLOAD), bytes: PAYLOAD.length, etag: '"abc"' });
+    });
+    it('follows redirects and keeps the x-linked-etag from the first hop', async () => {
+        const { get: origin, calls } = server();
+        const get = async (url, headers, timeout) => {
+            if (url === 'https://hub/model') {
+                return response(302, Buffer.alloc(0), { location: 'https://cdn/model', 'x-linked-etag': '"lfs-sha"' });
+            }
+            return origin(url, headers, timeout);
+        };
+        const result = await downloadToFile('https://hub/model', dest, { get });
+        expect(calls.map(c => c.url)).toEqual(['https://cdn/model']);
+        expect(result.etag).toBe('"lfs-sha"');
+    });
+    it('resumes a partial file with a Range request and hashes the whole file', async () => {
+        await fs.writeFile(dest, PAYLOAD.subarray(0, 10));
+        const { get, calls } = server();
+        const result = await downloadToFile('https://host/model', dest, { get });
+        expect(calls[0].headers.Range).toBe('bytes=10-');
+        expect(await fs.readFile(dest)).toEqual(PAYLOAD);
+        expect(result.sha256).toBe(sha(PAYLOAD));
+        expect(result.bytes).toBe(PAYLOAD.length);
+    });
+    it('restarts from zero when the server ignores Range', async () => {
+        await fs.writeFile(dest, Buffer.from('stale-bytes'));
+        const { get } = server({ honourRange: false });
+        const result = await downloadToFile('https://host/model', dest, { get });
+        expect(await fs.readFile(dest)).toEqual(PAYLOAD);
+        expect(result.sha256).toBe(sha(PAYLOAD));
+    });
+    it('restarts when the partial is already past the end (416)', async () => {
+        await fs.writeFile(dest, Buffer.concat([PAYLOAD, Buffer.from('extra')]));
+        const { get, calls } = server();
+        await downloadToFile('https://host/model', dest, { get });
+        expect(calls).toHaveLength(2);
+        expect(await fs.readFile(dest)).toEqual(PAYLOAD);
+    });
+    it('rejects non-success responses without creating the file', async () => {
+        const get = async () => response(401);
+        await expect(downloadToFile('https://host/model', dest, { get })).rejects.toThrow('HTTP 401');
+        expect(await fs.pathExists(dest)).toBe(false);
+    });
+    it('refuses non-https URLs, including redirects to them', async () => {
+        const { get } = server();
+        await expect(downloadToFile('http://host/model', dest, { get })).rejects.toThrow('non-https');
+        const redirecting = async () => response(302, Buffer.alloc(0), { location: 'http://evil/model' });
+        await expect(downloadToFile('https://host/model', dest, { get: redirecting })).rejects.toThrow('non-https');
+    });
+    it('stops after too many redirects', async () => {
+        const loop = async (url) => response(302, Buffer.alloc(0), { location: `${url}x` });
+        await expect(downloadToFile('https://host/m', dest, { get: loop })).rejects.toThrow('Too many redirects');
+    });
+    it('aborts a stalled body and keeps the partial for the next resume', async () => {
+        const body = new PassThrough();
+        body.write(PAYLOAD.subarray(0, 5));
+        const get = async () => response(200, body, { 'content-length': String(PAYLOAD.length) });
+        await expect(downloadToFile('https://host/model', dest, { get, stallTimeoutMs: 50 })).rejects.toThrow('stalled');
+        // The partial file is kept for the next resume (how many bytes reached disk is up to the OS).
+        expect(await fs.pathExists(dest)).toBe(true);
+        expect((await fs.stat(dest)).size).toBeLessThanOrEqual(5);
+    });
+    it('reports progress against the full size when resuming', async () => {
+        await fs.writeFile(dest, PAYLOAD.subarray(0, 10));
+        const { get } = server();
+        const seen = [];
+        await downloadToFile('https://host/model', dest, { get, onProgress: (d, t) => seen.push([d, t]) });
+        expect(seen.at(-1)).toEqual([PAYLOAD.length, PAYLOAD.length]);
+    });
+});

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>;