@rigour-labs/core 4.2.3 → 4.3.1

package/dist/gates/side-effect-rules.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Side-Effect Analysis Rules
+ *
+ * Pattern definitions for detecting unbounded side effects that cause
+ * real-world consequences: process spawns, resource exhaustion, circular
+ * triggers, missing circuit breakers.
+ *
+ * Each rule has:
+ * - regex patterns per language
+ * - a check function that verifies context (surrounding lines)
+ * - severity and description
+ *
+ * @since v4.3.0
+ */
+export type SideEffectLang = 'js' | 'ts' | 'py' | 'go' | 'rs' | 'cs' | 'java' | 'rb';
+export interface SideEffectViolation {
+    rule: string;
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    file: string;
+    line: number;
+    match: string;
+    description: string;
+    hint: string;
+}
+export declare const LANG_MAP: Record<string, SideEffectLang>;
+export declare const FILE_GLOBS: string[];
+export declare const TIMER_CREATE_PATTERNS: Record<string, RegExp[]>;
+export declare const TIMER_CLEANUP_PATTERNS: Record<string, RegExp[]>;
+export declare const PROCESS_SPAWN_PATTERNS: Record<string, RegExp[]>;
+export declare const PROCESS_EXIT_PATTERNS: Record<string, RegExp[]>;
+export declare const UNBOUNDED_LOOP_PATTERNS: Record<string, RegExp[]>;
+export declare const IO_PATTERNS: Record<string, RegExp[]>;
+export declare const RETRY_PATTERNS: Record<string, RegExp[]>;
+export declare const MAX_RETRY_INDICATORS: RegExp[];
+export declare const WATCHER_PATTERNS: Record<string, RegExp[]>;
+export declare const WRITE_PATTERNS: Record<string, RegExp[]>;
+export declare const RESOURCE_OPEN_PATTERNS: Record<string, RegExp[]>;
+export declare const RESOURCE_CLOSE_PATTERNS: Record<string, RegExp[]>;
+export declare const AUTO_RESTART_PATTERNS: Record<string, RegExp[]>;

package/dist/gates/side-effect-rules.js

@@ -0,0 +1,302 @@
+/**
+ * Side-Effect Analysis Rules
+ *
+ * Pattern definitions for detecting unbounded side effects that cause
+ * real-world consequences: process spawns, resource exhaustion, circular
+ * triggers, missing circuit breakers.
+ *
+ * Each rule has:
+ * - regex patterns per language
+ * - a check function that verifies context (surrounding lines)
+ * - severity and description
+ *
+ * @since v4.3.0
+ */
+// ── Language detection ──
+export const LANG_MAP = {
+    '.ts': 'ts', '.tsx': 'ts', '.mts': 'ts',
+    '.js': 'js', '.jsx': 'js', '.mjs': 'js', '.cjs': 'js',
+    '.py': 'py',
+    '.go': 'go',
+    '.rs': 'rs',
+    '.cs': 'cs',
+    '.java': 'java',
+    '.rb': 'rb',
+};
+export const FILE_GLOBS = [
+    '**/*.{ts,tsx,mts,js,jsx,mjs,cjs}',
+    '**/*.py',
+    '**/*.go',
+    '**/*.rs',
+    '**/*.cs',
+    '**/*.java',
+    '**/*.rb',
+];
+// ── Timer patterns (setInterval/setTimeout without cleanup) ──
+export const TIMER_CREATE_PATTERNS = {
+    js: [
+        /\bsetInterval\s*\(/,
+        /\bsetTimeout\s*\(/,
+    ],
+    ts: [
+        /\bsetInterval\s*\(/,
+        /\bsetTimeout\s*\(/,
+    ],
+    py: [
+        /\bscheduler\.enter\s*\(/,
+        /\bTimer\s*\(/,
+        /\bschedule\.every\b/,
+    ],
+    go: [
+        /\btime\.NewTicker\s*\(/,
+        /\btime\.Tick\s*\(/,
+    ],
+    java: [
+        /\bScheduledExecutorService\b/,
+        /\bTimer\(\)\.schedule\b/,
+        /\bTimer\(\)\.scheduleAtFixedRate\b/,
+    ],
+    rs: [],
+    cs: [
+        /\bnew\s+Timer\s*\(/,
+        /\bSetInterval\s*\(/,
+    ],
+    rb: [],
+};
+export const TIMER_CLEANUP_PATTERNS = {
+    js: [/\bclearInterval\s*\(/, /\bclearTimeout\s*\(/],
+    ts: [/\bclearInterval\s*\(/, /\bclearTimeout\s*\(/],
+    py: [/\.cancel\s*\(/],
+    go: [/\.Stop\s*\(/],
+    java: [/\.shutdown\s*\(/, /\.cancel\s*\(/],
+    rs: [],
+    cs: [/\.Dispose\s*\(/, /\.Stop\s*\(/],
+    rb: [],
+};
+// ── Process spawn patterns ──
+export const PROCESS_SPAWN_PATTERNS = {
+    js: [
+        /\bchild_process\.\w+\s*\(/,
+        /\bspawn\s*\(/,
+        /\bexec\s*\(/,
+        /\bexecFile\s*\(/,
+        /\bfork\s*\(/,
+        /\bexeca\s*\(/,
+    ],
+    ts: [
+        /\bchild_process\.\w+\s*\(/,
+        /\bspawn\s*\(/,
+        /\bexec\s*\(/,
+        /\bexecFile\s*\(/,
+        /\bfork\s*\(/,
+        /\bexeca\s*\(/,
+    ],
+    py: [
+        /\bsubprocess\.\w+\s*\(/,
+        /\bPopen\s*\(/,
+        /\bos\.system\s*\(/,
+        /\bos\.exec\w*\s*\(/,
+        /\bos\.spawn\w*\s*\(/,
+    ],
+    go: [
+        /\bexec\.Command\s*\(/,
+        /\bos\/exec\b/,
+        /\bcmd\.Start\s*\(/,
+        /\bcmd\.Run\s*\(/,
+    ],
+    java: [
+        /\bProcessBuilder\b/,
+        /\bRuntime\.getRuntime\(\)\.exec\s*\(/,
+    ],
+    rs: [
+        /\bCommand::new\s*\(/,
+        /\bstd::process::Command\b/,
+    ],
+    cs: [
+        /\bProcess\.Start\s*\(/,
+        /\bnew\s+ProcessStartInfo\b/,
+    ],
+    rb: [
+        /\bsystem\s*\(/,
+        /\bspawn\s*\(/,
+        /\b`[^`]+`/,
+        /\bIO\.popen\s*\(/,
+    ],
+};
+export const PROCESS_EXIT_PATTERNS = {
+    js: [/\.on\s*\(\s*['"](?:exit|close)['"]/, /\.kill\s*\(/, /\.disconnect\s*\(/],
+    ts: [/\.on\s*\(\s*['"](?:exit|close)['"]/, /\.kill\s*\(/, /\.disconnect\s*\(/],
+    py: [/\.wait\s*\(/, /\.terminate\s*\(/, /\.kill\s*\(/, /\.communicate\s*\(/],
+    go: [/\.Wait\s*\(/, /cmd\.Process\.Kill\s*\(/],
+    java: [/\.waitFor\s*\(/, /\.destroy\s*\(/, /\.destroyForcibly\s*\(/],
+    rs: [/\.wait\s*\(/, /\.kill\s*\(/],
+    cs: [/\.WaitForExit\s*\(/, /\.Kill\s*\(/, /\.Close\s*\(/],
+    rb: [/Process\.wait\b/, /Process\.kill\b/],
+};
+// ── Unbounded loop patterns ──
+export const UNBOUNDED_LOOP_PATTERNS = {
+    js: [/\bwhile\s*\(\s*true\s*\)/, /\bwhile\s*\(\s*1\s*\)/, /\bfor\s*\(\s*;\s*;\s*\)/],
+    ts: [/\bwhile\s*\(\s*true\s*\)/, /\bwhile\s*\(\s*1\s*\)/, /\bfor\s*\(\s*;\s*;\s*\)/],
+    py: [/\bwhile\s+True\s*:/, /\bwhile\s+1\s*:/],
+    go: [/\bfor\s*\{/, /\bfor\s+\{/], // bare `for {` in Go = infinite loop
+    java: [/\bwhile\s*\(\s*true\s*\)/, /\bfor\s*\(\s*;\s*;\s*\)/],
+    rs: [/\bloop\s*\{/],
+    cs: [/\bwhile\s*\(\s*true\s*\)/, /\bfor\s*\(\s*;\s*;\s*\)/],
+    rb: [/\bloop\s+do\b/, /\bwhile\s+true\b/],
+};
+// I/O operations inside loops that indicate resource impact
+export const IO_PATTERNS = {
+    js: [
+        /\bfs\.\w+/, /\bfetch\s*\(/, /\baxios\.\w+/, /\bhttp\.\w+/,
+        /\.write\s*\(/, /\.send\s*\(/, /\bchild_process\./,
+        /\bconsole\.\w+/, /\bprocess\.stdout/,
+    ],
+    ts: [
+        /\bfs\.\w+/, /\bfetch\s*\(/, /\baxios\.\w+/, /\bhttp\.\w+/,
+        /\.write\s*\(/, /\.send\s*\(/, /\bchild_process\./,
+    ],
+    py: [
+        /\bopen\s*\(/, /\brequests\.\w+/, /\burllib\.\w+/,
+        /\bsubprocess\./, /\bos\.\w+/, /\bsocket\.\w+/,
+        /\.write\s*\(/, /\bprint\s*\(/,
+    ],
+    go: [
+        /\bos\.\w+/, /\bnet\.\w+/, /\bhttp\.\w+/,
+        /\bio\.\w+/, /\bfmt\.Fprint/, /\bioutil\.\w+/,
+        /\bexec\.Command/,
+    ],
+    java: [
+        /\bnew\s+File\w*\(/, /\bHttpClient\b/, /\bSocket\b/,
+        /\.write\s*\(/, /\bRuntime\.getRuntime\(\)/,
+    ],
+    rs: [
+        /\bstd::fs::/, /\bstd::net::/, /\bstd::process::/,
+        /\.write\s*\(/, /\btokio::\w+/,
+    ],
+    cs: [
+        /\bFile\.\w+/, /\bHttpClient\b/, /\bProcess\.Start/,
+        /\.Write\s*\(/, /\bSocket\b/,
+    ],
+    rb: [
+        /\bFile\.\w+/, /\bNet::HTTP\b/, /\bIO\.\w+/,
+        /\.write\s*\(/, /\bsystem\s*\(/,
+    ],
+};
+// ── Retry without limit patterns ──
+export const RETRY_PATTERNS = {
+    js: [/\bcatch\s*\([^)]*\)\s*\{/, /\.catch\s*\(/],
+    ts: [/\bcatch\s*\([^)]*\)\s*\{/, /\.catch\s*\(/],
+    py: [/\bexcept\s+\w+/, /\bexcept\s*:/],
+    go: [/\bif\s+err\s*!=\s*nil\b/],
+    java: [/\bcatch\s*\(\w+\s+\w+\)/, /\bcatch\s*\(\s*Exception\b/],
+    rs: [/\.unwrap_or_else\s*\(/, /\bif\s+let\s+Err\b/],
+    cs: [/\bcatch\s*\(\w+\b/, /\bcatch\s*\{/],
+    rb: [/\brescue\b/],
+};
+export const MAX_RETRY_INDICATORS = [
+    /max.?retries?/i,
+    /retry.?count/i,
+    /retry.?limit/i,
+    /attempt/i,
+    /retries?\s*[<>=!]+\s*\d+/,
+    /count\s*[<>=!]+\s*\d+/,
+    /MAX_/,
+    /backoff/i,
+    /circuit.?breaker/i,
+];
+// ── File watcher patterns (circular trigger detection) ──
+export const WATCHER_PATTERNS = {
+    js: [
+        /\bfs\.watch\s*\(/, /\bfs\.watchFile\s*\(/,
+        /\bchokidar\.watch\s*\(/, /\bnodemon\b/,
+        /\bnew\s+FSWatcher\b/,
+    ],
+    ts: [
+        /\bfs\.watch\s*\(/, /\bfs\.watchFile\s*\(/,
+        /\bchokidar\.watch\s*\(/,
+        /\bnew\s+FSWatcher\b/,
+    ],
+    py: [
+        /\bwatchdog\b/, /\bObserver\s*\(/,
+        /\binotify\b/, /\bwatchfiles\b/,
+    ],
+    go: [
+        /\bfsnotify\.\w+/, /\bNewWatcher\s*\(/,
+    ],
+    java: [
+        /\bWatchService\b/, /\bWatchKey\b/,
+    ],
+    rs: [
+        /\bnotify::/, /\bRecommendedWatcher\b/,
+    ],
+    cs: [
+        /\bFileSystemWatcher\b/, /\bnew\s+FileSystemWatcher\b/,
+    ],
+    rb: [
+        /\bListen\.\w+/, /\brb-inotify\b/,
+    ],
+};
+export const WRITE_PATTERNS = {
+    js: [/\bfs\.writeFile/, /\bfs\.appendFile/, /\bfs\.createWriteStream/, /\.write\s*\(/],
+    ts: [/\bfs\.writeFile/, /\bfs\.appendFile/, /\bfs\.createWriteStream/, /\.write\s*\(/],
+    py: [/\bopen\s*\([^)]*['"][wa]['"]/, /\.write\s*\(/, /\bshutil\.\w+/],
+    go: [/\bos\.WriteFile/, /\bos\.Create/, /\bio\.WriteString/, /\.Write\s*\(/],
+    java: [/\bFileWriter\b/, /\bBufferedWriter\b/, /\.write\s*\(/],
+    rs: [/\bfs::write/, /\bFile::create/, /\.write_all\s*\(/],
+    cs: [/\bFile\.Write/, /\bStreamWriter\b/, /\.Write\s*\(/],
+    rb: [/\bFile\.write/, /\bFile\.open\s*\([^)]*['"]w['"]/, /\.write\s*\(/],
+};
+// ── Resource lifecycle patterns (open without close) ──
+export const RESOURCE_OPEN_PATTERNS = {
+    js: [/\bfs\.open\s*\(/, /\bfs\.createReadStream\s*\(/, /\bfs\.createWriteStream\s*\(/],
+    ts: [/\bfs\.open\s*\(/, /\bfs\.createReadStream\s*\(/, /\bfs\.createWriteStream\s*\(/],
+    py: [/\bopen\s*\(/],
+    go: [/\bos\.Open\s*\(/, /\bos\.Create\s*\(/, /\bos\.OpenFile\s*\(/],
+    java: [/\bnew\s+FileInputStream\b/, /\bnew\s+FileOutputStream\b/, /\bnew\s+BufferedReader\b/],
+    rs: [/\bFile::open\s*\(/, /\bFile::create\s*\(/],
+    cs: [/\bFile\.Open\s*\(/, /\bnew\s+FileStream\b/, /\bnew\s+StreamReader\b/],
+    rb: [/\bFile\.open\s*\(/],
+};
+export const RESOURCE_CLOSE_PATTERNS = {
+    js: [/\.close\s*\(/, /\.destroy\s*\(/, /\.end\s*\(/],
+    ts: [/\.close\s*\(/, /\.destroy\s*\(/, /\.end\s*\(/],
+    py: [/\.close\s*\(/, /\bwith\s+open\b/], // `with` auto-closes
+    go: [/\.Close\s*\(/, /\bdefer\b/], // defer auto-closes
+    java: [/\.close\s*\(/, /\btry\s*\(/], // try-with-resources
+    rs: [/\bdrop\s*\(/, /\}$/], // Rust auto-drops
+    cs: [/\.Close\s*\(/, /\.Dispose\s*\(/, /\busing\s*\(/], // using auto-disposes
+    rb: [/\.close\b/, /\bFile\.open\s*\([^)]*\)\s*do\b/], // block form auto-closes
+};
+// ── Auto-restart / self-respawn patterns ──
+export const AUTO_RESTART_PATTERNS = {
+    js: [
+        /process\.on\s*\(\s*['"](?:exit|uncaughtException|SIGTERM)['"]\s*,\s*(?:function|\(|=>).*(?:spawn|exec|fork)/,
+        /process\.on\s*\(\s*['"]exit['"]/,
+    ],
+    ts: [
+        /process\.on\s*\(\s*['"](?:exit|uncaughtException|SIGTERM)['"]\s*,\s*(?:function|\(|=>).*(?:spawn|exec|fork)/,
+        /process\.on\s*\(\s*['"]exit['"]/,
+    ],
+    py: [
+        /\batexit\.register\s*\(/,
+        /\bsignal\.signal\s*\(\s*signal\.SIG\w+\s*,/,
+    ],
+    go: [
+        /\bsignal\.Notify\s*\(/,
+        /\bos\.Exit\s*\(/,
+    ],
+    java: [
+        /\bRuntime\.getRuntime\(\)\.addShutdownHook\b/,
+    ],
+    rs: [
+        /\bctrlc::set_handler\b/,
+        /\bsignal::ctrl_c\b/,
+    ],
+    cs: [
+        /\bAppDomain\.CurrentDomain\.ProcessExit\b/,
+    ],
+    rb: [
+        /\bat_exit\b/,
+        /\btrap\s*\(/,
+    ],
+};

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './templates/index.js';
 export * from './types/fix-packet.js';
 export { Gate, GateContext } from './gates/base.js';
 export { RetryLoopBreakerGate } from './gates/retry-loop-breaker.js';
+export { SideEffectAnalysisGate } from './gates/side-effect-analysis.js';
 export * from './utils/logger.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
@@ -17,5 +18,7 @@ export type { InferenceProvider, DeepFinding, DeepAnalysisResult, ModelTier } fr
 export { MODELS } from './inference/types.js';
 export { isModelCached, getModelsDir, getModelInfo } from './inference/model-manager.js';
 export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
-export { openDatabase, isSQLiteAvailable, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
-export type { RigourDB } from './storage/index.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';
+export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';
+export type { ProjectStats } from './storage/index.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './templates/index.js';
 export * from './types/fix-packet.js';
 export { Gate } from './gates/base.js';
 export { RetryLoopBreakerGate } from './gates/retry-loop-breaker.js';
+export { SideEffectAnalysisGate } from './gates/side-effect-analysis.js';
 export * from './utils/logger.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
@@ -18,7 +19,9 @@ export { MODELS } from './inference/types.js';
 export { isModelCached, getModelsDir, getModelInfo } from './inference/model-manager.js';
 export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
 // Storage (SQLite Brain)
-export { openDatabase, isSQLiteAvailable, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
+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';
 // Pattern Index is intentionally NOT exported here to prevent
 // native dependency issues (sharp/transformers) from leaking into
 // non-AI parts of the system.

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

@@ -2,11 +2,11 @@ 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>;
 /**
- * Check if a model is already downloaded and valid.
+ * Check if any model for this tier is cached (fine-tuned or fallback).
  */
 export declare function isModelCached(tier: ModelTier): Promise<boolean>;
 /**
- * Get the path to a cached model.
+ * Get the path to a cached model (prefers fine-tuned over fallback).
  */
 export declare function getModelPath(tier: ModelTier): string;
 /**
@@ -15,7 +15,7 @@ export declare function getModelPath(tier: ModelTier): string;
 export declare function getModelInfo(tier: ModelTier): ModelInfo;
 /**
  * Download a model from HuggingFace CDN.
- * Calls onProgress with status updates.
+ * Tries fine-tuned model first, falls back to stock Qwen if unavailable.
  */
 export declare function downloadModel(tier: ModelTier, onProgress?: (message: string, percent?: number) => void): Promise<string>;
 /**

package/dist/inference/model-manager.js

@@ -6,11 +6,11 @@ import path from 'path';
 import fs from 'fs-extra';
 import { createHash } from 'crypto';
 import { RIGOUR_DIR } from '../storage/db.js';
-import { MODELS } from './types.js';
+import { MODELS, FALLBACK_MODELS } from './types.js';
 const MODELS_DIR = path.join(RIGOUR_DIR, 'models');
 const SHA256_RE = /^[a-f0-9]{64}$/i;
-function getModelMetadataPath(tier) {
-    return path.join(MODELS_DIR, MODELS[tier].filename + '.meta.json');
+function getModelMetadataPath(filename) {
+    return path.join(MODELS_DIR, filename + '.meta.json');
 }
 function isValidMetadata(raw) {
     return !!raw &&
@@ -34,17 +34,15 @@ export async function hashFileSha256(filePath) {
     }
     return hash.digest('hex');
 }
-async function writeModelMetadata(tier, metadata) {
-    const metadataPath = getModelMetadataPath(tier);
-    await fs.writeJson(metadataPath, metadata, { spaces: 2 });
+async function writeModelMeta(filename, metadata) {
+    await fs.writeJson(getModelMetadataPath(filename), metadata, { spaces: 2 });
 }
-async function readModelMetadata(tier) {
-    const metadataPath = getModelMetadataPath(tier);
-    if (!(await fs.pathExists(metadataPath))) {
+async function readModelMeta(filename) {
+    const p = getModelMetadataPath(filename);
+    if (!(await fs.pathExists(p)))
         return null;
-    }
     try {
-        const raw = await fs.readJson(metadataPath);
+        const raw = await fs.readJson(p);
         return isValidMetadata(raw) ? raw : null;
     }
     catch {
@@ -52,17 +50,15 @@ async function readModelMetadata(tier) {
     }
 }
 /**
- * Check if a model is already downloaded and valid.
+ * Check if a single model file is cached and valid.
  */
-export async function isModelCached(tier) {
-    const model = MODELS[tier];
+async function isFileCached(model) {
     const modelPath = path.join(MODELS_DIR, model.filename);
     if (!(await fs.pathExists(modelPath)))
         return false;
-    const metadata = await readModelMetadata(tier);
+    const metadata = await readModelMeta(model.filename);
     if (!metadata)
         return false;
-    // Size check + "changed since verification" check.
     const stat = await fs.stat(modelPath);
     const tolerance = model.sizeBytes * 0.1;
     if (stat.size <= model.sizeBytes - tolerance)
@@ -74,10 +70,22 @@ export async function isModelCached(tier) {
     return true;
 }
 /**
- * Get the path to a cached model.
+ * Check if any model for this tier is cached (fine-tuned or fallback).
+ */
+export async function isModelCached(tier) {
+    if (await isFileCached(MODELS[tier]))
+        return true;
+    const fb = FALLBACK_MODELS[tier];
+    return fb.url !== MODELS[tier].url && await isFileCached(fb);
+}
+/**
+ * Get the path to a cached model (prefers fine-tuned over fallback).
  */
 export function getModelPath(tier) {
-    return path.join(MODELS_DIR, MODELS[tier].filename);
+    const primary = path.join(MODELS_DIR, MODELS[tier].filename);
+    if (fs.pathExistsSync(primary))
+        return primary;
+    return path.join(MODELS_DIR, FALLBACK_MODELS[tier].filename);
 }
 /**
  * Get model info for a tier.
@@ -86,73 +94,73 @@ export function getModelInfo(tier) {
     return MODELS[tier];
 }
 /**
- * Download a model from HuggingFace CDN.
- * Calls onProgress with status updates.
+ * Stream a response body to disk with progress + SHA256.
+ * Returns { sha256, downloaded } on success.
  */
-export async function downloadModel(tier, onProgress) {
-    const model = MODELS[tier];
+async function streamToDisk(response, tempPath, model, onProgress) {
+    const contentLength = parseInt(response.headers.get('content-length') || '0', 10);
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('No response body');
+    const writeStream = fs.createWriteStream(tempPath);
+    const hash = createHash('sha256');
+    let downloaded = 0;
+    let lastPct = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        const chunk = Buffer.from(value);
+        writeStream.write(chunk);
+        hash.update(chunk);
+        downloaded += value.length;
+        if (contentLength > 0) {
+            const pct = Math.round((downloaded / contentLength) * 100);
+            if (pct >= lastPct + 5) {
+                lastPct = pct;
+                onProgress?.(`Downloading ${model.name}: ${pct}%`, pct);
+            }
+        }
+    }
+    writeStream.end();
+    await new Promise((resolve, reject) => {
+        writeStream.on('finish', resolve);
+        writeStream.on('error', reject);
+    });
+    return { sha256: hash.digest('hex'), downloaded };
+}
+/**
+ * Verify SHA256 against ETag, allowing LFS OID mismatches
+ * if the download size is reasonable.
+ */
+function verifySha256(expectedSha256, actualSha256, downloaded, model) {
+    if (!expectedSha256 || actualSha256 === expectedSha256)
+        return;
+    const tolerance = model.sizeBytes * 0.1;
+    if (downloaded < model.sizeBytes - tolerance) {
+        throw new Error(`Checksum mismatch for ${model.name}: ` +
+            `expected ${expectedSha256}, got ${actualSha256} ` +
+            `(undersized: ${downloaded} bytes)`);
+    }
+    // Size OK — ETag likely a Git LFS OID, not content SHA256
+}
+/**
+ * Download a specific model from its URL, write to disk, save metadata.
+ */
+async function downloadFromUrl(tier, model, onProgress) {
     const destPath = path.join(MODELS_DIR, model.filename);
     const tempPath = destPath + '.download';
-    fs.ensureDirSync(MODELS_DIR);
-    // Already cached
-    if (await isModelCached(tier)) {
-        onProgress?.(`Model ${model.name} already cached`, 100);
-        return destPath;
-    }
-    onProgress?.(`Downloading ${model.name} (${model.sizeHuman})...`, 0);
     try {
         const response = await fetch(model.url);
         if (!response.ok) {
             throw new Error(`HTTP ${response.status}: ${response.statusText}`);
         }
-        const expectedSha256 = extractSha256FromEtag(response.headers.get('etag'));
-        const contentLength = parseInt(response.headers.get('content-length') || '0', 10);
-        const reader = response.body?.getReader();
-        if (!reader)
-            throw new Error('No response body');
-        const writeStream = fs.createWriteStream(tempPath);
-        const hash = createHash('sha256');
-        let downloaded = 0;
-        let lastProgressPercent = 0;
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            const chunk = Buffer.from(value);
-            writeStream.write(chunk);
-            hash.update(chunk);
-            downloaded += value.length;
-            if (contentLength > 0) {
-                const percent = Math.round((downloaded / contentLength) * 100);
-                if (percent >= lastProgressPercent + 5) { // Report every 5%
-                    lastProgressPercent = percent;
-                    onProgress?.(`Downloading ${model.name}: ${percent}%`, percent);
-                }
-            }
-        }
-        writeStream.end();
-        await new Promise((resolve, reject) => {
-            writeStream.on('finish', resolve);
-            writeStream.on('error', reject);
-        });
-        const actualSha256 = hash.digest('hex');
-        if (expectedSha256 && actualSha256 !== expectedSha256) {
-            // HuggingFace ETags for LFS files may contain the Git LFS OID (pointer hash)
-            // rather than the SHA256 of the actual served bytes. This is common when
-            // CDN/Cloudfront serves the file. Only hard-fail if the download is also
-            // suspiciously small (likely corrupt). Otherwise warn and proceed — the
-            // actual content hash is still recorded in metadata for future verification.
-            const tolerance = model.sizeBytes * 0.1;
-            if (downloaded < model.sizeBytes - tolerance) {
-                throw new Error(`Model checksum mismatch for ${model.name}: expected ${expectedSha256}, got ${actualSha256} (download also undersized: ${downloaded} bytes)`);
-            }
-            // Download size is reasonable — ETag likely a Git LFS OID, not content SHA256
-        }
-        // Atomic rename
+        const expectedSha = extractSha256FromEtag(response.headers.get('etag'));
+        const { sha256, downloaded } = await streamToDisk(response, tempPath, model, onProgress);
+        verifySha256(expectedSha, sha256, downloaded, model);
         fs.renameSync(tempPath, destPath);
-        await writeModelMetadata(tier, {
-            sha256: actualSha256,
-            sizeBytes: downloaded,
+        await writeModelMeta(model.filename, {
+            sha256, sizeBytes: downloaded,
             verifiedAt: new Date().toISOString(),
             sourceUrl: model.url,
             sourceEtag: response.headers.get('etag') || undefined,
@@ -161,11 +169,35 @@ export async function downloadModel(tier, onProgress) {
         return destPath;
     }
     catch (error) {
-        // Clean up temp file on failure
         fs.removeSync(tempPath);
         throw error;
     }
 }
+/**
+ * Download a model from HuggingFace CDN.
+ * Tries fine-tuned model first, falls back to stock Qwen if unavailable.
+ */
+export async function downloadModel(tier, onProgress) {
+    fs.ensureDirSync(MODELS_DIR);
+    if (await isModelCached(tier)) {
+        onProgress?.(`Model ${MODELS[tier].name} already cached`, 100);
+        return getModelPath(tier);
+    }
+    const model = MODELS[tier];
+    onProgress?.(`Downloading ${model.name} (${model.sizeHuman})...`, 0);
+    try {
+        return await downloadFromUrl(tier, model, onProgress);
+    }
+    catch (error) {
+        // Fine-tuned model not available — try stock fallback
+        const fallback = FALLBACK_MODELS[tier];
+        if (fallback && fallback.url !== model.url) {
+            onProgress?.(`Fine-tuned model unavailable, using ${fallback.name}`, 0);
+            return downloadFromUrl(tier, fallback, onProgress);
+        }
+        throw error;
+    }
+}
 /**
  * Ensure a model is available, downloading if needed.
  */

package/dist/inference/types.d.ts

@@ -73,5 +73,16 @@ export interface ModelInfo {
     sizeBytes: number;
     sizeHuman: string;
 }
+/**
+ * Model version — bump when new fine-tuned GGUF is published.
+ * The RLAIF pipeline uploads new models to HuggingFace, and
+ * model-manager checks this version to auto-update.
+ */
+export declare const MODEL_VERSION = "1";
 /** All supported model definitions */
 export declare const MODELS: Record<ModelTier, ModelInfo>;
+/**
+ * Fallback stock models — used when fine-tuned model is not yet
+ * available on HuggingFace (initial setup / first-time users).
+ */
+export declare const FALLBACK_MODELS: Record<ModelTier, ModelInfo>;