@gmickel/gno 0.6.0 → 0.6.1

package/src/llm/cache.ts

@@ -5,18 +5,24 @@
  * @module src/llm/cache
  */
 
-import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+// node:crypto: createHash for safe lock filenames
+import { createHash } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm, stat } from 'node:fs/promises';
 // node:path: join for path construction, isAbsolute for cross-platform path detection
 import { isAbsolute, join } from 'node:path';
 // node:url: fileURLToPath for proper file:// URL handling
 import { fileURLToPath } from 'node:url';
 import { getModelsCachePath } from '../app/constants';
 import {
+  autoDownloadDisabledError,
   downloadFailedError,
   invalidUriError,
+  lockFailedError,
   modelNotCachedError,
   modelNotFoundError,
 } from './errors';
+import { getLockPath, getManifestLockPath, withLock } from './lockfile';
+import type { DownloadPolicy } from './policy';
 import type {
   DownloadProgress,
   LlmResult,
@@ -306,6 +312,85 @@ export class ModelCache {
     }
   }
 
+  /**
+   * Ensure a model is available, downloading if necessary.
+   * Uses double-check locking pattern for concurrent safety.
+   *
+   * @param uri - Model URI (hf: or file:)
+   * @param type - Model type for manifest
+   * @param policy - Download policy (offline, allowDownload)
+   * @param onProgress - Optional progress callback
+   */
+  async ensureModel(
+    uri: string,
+    type: ModelType,
+    policy: DownloadPolicy,
+    onProgress?: ProgressCallback
+  ): Promise<LlmResult<string>> {
+    // Fast path: check if already cached
+    const cached = await this.getCachedPath(uri);
+    if (cached) {
+      return { ok: true, value: cached };
+    }
+
+    // Parse and validate URI
+    const parsed = parseModelUri(uri);
+    if (!parsed.ok) {
+      return { ok: false, error: invalidUriError(uri, parsed.error) };
+    }
+
+    // Local files: just verify existence (no download needed)
+    if (parsed.value.scheme === 'file') {
+      const exists = await this.fileExists(parsed.value.file);
+      if (!exists) {
+        return {
+          ok: false,
+          error: modelNotFoundError(
+            uri,
+            `File not found: ${parsed.value.file}`
+          ),
+        };
+      }
+      return { ok: true, value: parsed.value.file };
+    }
+
+    // HF models: check policy
+    if (policy.offline) {
+      return { ok: false, error: modelNotCachedError(uri, type) };
+    }
+
+    if (!policy.allowDownload) {
+      return { ok: false, error: autoDownloadDisabledError(uri) };
+    }
+
+    // Acquire lock for download (prevents concurrent downloads of same model)
+    // Use hash for lock filename to avoid collisions and path issues
+    await mkdir(this.dir, { recursive: true });
+    const lockName = createHash('sha256')
+      .update(uri)
+      .digest('hex')
+      .slice(0, 32);
+    const lockPath = getLockPath(join(this.dir, lockName));
+
+    const result = await withLock(lockPath, async () => {
+      // Double-check: another process may have downloaded while we waited
+      const cachedNow = await this.getCachedPath(uri);
+      if (cachedNow) {
+        return { ok: true as const, value: cachedNow };
+      }
+
+      // Download with progress
+      return this.download(uri, type, onProgress);
+    });
+
+    // withLock returns null if lock acquisition failed
+    if (result === null) {
+      return { ok: false, error: lockFailedError(uri) };
+    }
+
+    return result;
+  }
+
   /**
    * Check if a model is cached/available.
    * For file: URIs, checks if file exists on disk.
@@ -368,6 +453,7 @@ export class ModelCache {
    * If types provided, only clears models of those types.
    */
   async clear(types?: ModelType[]): Promise<void> {
+    // First, read manifest to get paths to delete (outside lock for IO)
     const manifest = await this.loadManifest();
 
     const toRemove = types
@@ -382,14 +468,14 @@ export class ModelCache {
       }
     }
 
-    // Update manifest
-    if (types) {
-      manifest.models = manifest.models.filter((m) => !types.includes(m.type));
-    } else {
-      manifest.models = [];
-    }
-
-    await this.saveManifest(manifest);
+    // Update manifest under lock
+    await this.updateManifest((m) => {
+      if (types) {
+        m.models = m.models.filter((model) => !types.includes(model.type));
+      } else {
+        m.models = [];
+      }
+    });
   }
 
   // ───────────────────────────────────────────────────────────────────────────
@@ -410,58 +496,122 @@ export class ModelCache {
       return this.manifest;
     }
 
+    this.manifest = await this.readManifestFromDisk();
+    return this.manifest;
+  }
+
+  /**
+   * Read manifest from disk without cache (for use under lock).
+   */
+  private async readManifestFromDisk(): Promise<Manifest> {
     try {
       const content = await readFile(this.manifestPath, 'utf-8');
-      this.manifest = JSON.parse(content) as Manifest;
-      return this.manifest;
+      return JSON.parse(content) as Manifest;
     } catch {
       // No manifest or invalid - create empty
-      this.manifest = { version: MANIFEST_VERSION, models: [] };
-      return this.manifest;
+      return { version: MANIFEST_VERSION, models: [] };
     }
   }
 
-  private async saveManifest(manifest: Manifest): Promise<void> {
+  /**
+   * Atomically update manifest under lock.
+   * Uses read-modify-write pattern with cross-process locking to prevent lost updates.
+   */
+  private async updateManifest(
+    mutator: (manifest: Manifest) => void
+  ): Promise<void> {
     await mkdir(this.dir, { recursive: true });
-    await writeFile(this.manifestPath, JSON.stringify(manifest, null, 2));
-    this.manifest = manifest;
+
+    const lockPath = getManifestLockPath(this.dir);
+    const result = await withLock(lockPath, async () => {
+      // Read current manifest from disk (not cache) under lock
+      const manifest = await this.readManifestFromDisk();
+
+      // Apply mutation
+      mutator(manifest);
+
+      // Write atomically
+      await this.writeManifestAtomically(manifest);
+
+      // Update cache
+      this.manifest = manifest;
+      return true;
+    });
+
+    if (result === null) {
+      throw new Error('Failed to acquire manifest lock');
+    }
+  }
+
+  /**
+   * Atomically write manifest with fsync for durability.
+   * Uses write-to-temp + fsync + rename pattern.
+   * Must be called under manifest lock.
+   */
+  private async writeManifestAtomically(manifest: Manifest): Promise<void> {
+    const tmpPath = `${this.manifestPath}.${process.pid}.tmp`;
+    const content = JSON.stringify(manifest, null, 2);
+
+    // Write to temp file with fsync
+    const fh = await open(tmpPath, 'w');
+    try {
+      await fh.writeFile(content);
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+
+    // Atomic rename
+    await rename(tmpPath, this.manifestPath);
+
+    // Fsync parent directory for rename durability (best-effort, not supported on Windows)
+    if (process.platform !== 'win32') {
+      try {
+        const dirFh = await open(this.dir, 'r');
+        try {
+          await dirFh.sync();
+        } finally {
+          await dirFh.close();
+        }
+      } catch {
+        // Best-effort durability
+      }
+    }
   }
 
   private async addToManifest(
     uri: string,
     type: ModelType,
-    path: string
+    modelPath: string
   ): Promise<void> {
-    const manifest = await this.loadManifest();
-
-    // Get file size and compute checksum
+    // Get file size outside lock (IO-bound, doesn't need protection)
     let size = 0;
     try {
-      const stats = await stat(path);
+      const stats = await stat(modelPath);
       size = stats.size;
     } catch {
       // Ignore
     }
 
-    // Remove existing entry if present
-    manifest.models = manifest.models.filter((m) => m.uri !== uri);
-
-    // Add new entry
-    manifest.models.push({
-      uri,
-      type,
-      path,
-      size,
-      checksum: '', // TODO: compute SHA-256 for large files
-      cachedAt: new Date().toISOString(),
+    await this.updateManifest((manifest) => {
+      // Remove existing entry if present
+      manifest.models = manifest.models.filter((m) => m.uri !== uri);
+
+      // Add new entry
+      manifest.models.push({
+        uri,
+        type,
+        path: modelPath,
+        size,
+        checksum: '', // TODO: compute SHA-256 for large files
+        cachedAt: new Date().toISOString(),
+      });
     });
-
-    await this.saveManifest(manifest);
   }
 
   private async removeFromManifest(uri: string): Promise<void> {
-    const manifest = await this.loadManifest();
-    manifest.models = manifest.models.filter((m) => m.uri !== uri);
-    await this.saveManifest(manifest);
+    await this.updateManifest((manifest) => {
+      manifest.models = manifest.models.filter((m) => m.uri !== uri);
+    });
   }
 }

package/src/llm/errors.ts

@@ -18,7 +18,9 @@ export type LlmErrorCode =
   | 'INFERENCE_FAILED'
   | 'TIMEOUT'
   | 'OUT_OF_MEMORY'
-  | 'INVALID_URI';
+  | 'INVALID_URI'
+  | 'LOCK_FAILED'
+  | 'AUTO_DOWNLOAD_DISABLED';
 
 export interface LlmError {
   code: LlmErrorCode;
@@ -91,9 +93,12 @@ export function llmError(
  * Check if error is retryable.
  */
 export function isRetryable(code: LlmErrorCode): boolean {
-  return ['MODEL_DOWNLOAD_FAILED', 'TIMEOUT', 'INFERENCE_FAILED'].includes(
-    code
-  );
+  return [
+    'MODEL_DOWNLOAD_FAILED',
+    'TIMEOUT',
+    'INFERENCE_FAILED',
+    'LOCK_FAILED',
+  ].includes(code);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -189,3 +194,21 @@ export function invalidUriError(uri: string, details: string): LlmError {
     retryable: false,
   });
 }
+
+export function lockFailedError(uri: string): LlmError {
+  return llmError('LOCK_FAILED', {
+    message: `Failed to acquire lock for model download: ${uri}`,
+    modelUri: uri,
+    retryable: true,
+    suggestion: 'Another process may be downloading. Wait and retry.',
+  });
+}
+
+export function autoDownloadDisabledError(uri: string): LlmError {
+  return llmError('AUTO_DOWNLOAD_DISABLED', {
+    message: `Model not cached and auto-download disabled: ${uri}`,
+    modelUri: uri,
+    retryable: false,
+    suggestion: "Run 'gno models pull' to download models manually.",
+  });
+}

package/src/llm/lockfile.ts

@@ -0,0 +1,216 @@
+/**
+ * Cross-process lockfile for model cache operations.
+ * Uses O_EXCL create + stale lock recovery pattern.
+ *
+ * @module src/llm/lockfile
+ */
+
+import { open, rename, rm, stat } from 'node:fs/promises';
+// node:os: hostname and user for lock ownership
+import { hostname, userInfo } from 'node:os';
+// node:path: join for manifest lock path
+import { join } from 'node:path';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Default lock TTL in milliseconds (24 hours - long to avoid stealing during slow downloads) */
+const DEFAULT_LOCK_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Retry delay for lock acquisition (ms) */
+const LOCK_RETRY_DELAY_MS = 500;
+
+/** Max retries before giving up (~10 minutes for multi-GB downloads) */
+const LOCK_MAX_RETRIES = 1200;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface LockMeta {
+  pid: number;
+  hostname: string;
+  user: string;
+  createdAt: string;
+}
+
+export interface LockHandle {
+  /** Release the lock */
+  release: () => Promise<void>;
+  /** Path to lock file */
+  path: string;
+}
+
+export interface LockOptions {
+  /** Lock TTL in milliseconds (see DEFAULT_LOCK_TTL_MS) */
+  ttlMs?: number;
+  /** Max retries before giving up (see LOCK_MAX_RETRIES) */
+  maxRetries?: number;
+  /** Delay between retries in ms (see LOCK_RETRY_DELAY_MS) */
+  retryDelayMs?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function getLockMeta(): LockMeta {
+  return {
+    pid: process.pid,
+    hostname: hostname(),
+    user: userInfo().username,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Check if a lockfile is stale (older than TTL or owner process dead).
+ */
+async function isLockStale(lockPath: string, ttlMs: number): Promise<boolean> {
+  try {
+    const stats = await stat(lockPath);
+    const age = Date.now() - stats.mtimeMs;
+
+    // Lock older than TTL is definitely stale
+    if (age > ttlMs) {
+      return true;
+    }
+
+    // TODO: Could also check if PID is alive on same hostname
+    // For now, just use TTL-based staleness
+    return false;
+  } catch {
+    // Lock doesn't exist or can't be read
+    return true;
+  }
+}
+
+/**
+ * Create lock file exclusively (O_EXCL).
+ * Fails if file already exists.
+ */
+async function createLockExclusive(
+  lockPath: string,
+  meta: LockMeta
+): Promise<void> {
+  const content = JSON.stringify(meta, null, 2);
+
+  // Create lock file with O_EXCL - fails if exists
+  const fh = await open(lockPath, 'wx');
+  try {
+    await fh.writeFile(content);
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main API
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Acquire a lock on a path.
+ * Returns a handle that must be released when done.
+ *
+ * @param lockPath - Path to the lock file (usually model path + '.lock')
+ * @param options - Lock options
+ * @returns Lock handle or null if acquisition failed
+ */
+export async function acquireLock(
+  lockPath: string,
+  options?: LockOptions
+): Promise<LockHandle | null> {
+  const ttlMs = options?.ttlMs ?? DEFAULT_LOCK_TTL_MS;
+  const maxRetries = options?.maxRetries ?? LOCK_MAX_RETRIES;
+  const retryDelayMs = options?.retryDelayMs ?? LOCK_RETRY_DELAY_MS;
+
+  let retries = 0;
+
+  while (retries < maxRetries) {
+    try {
+      // Try to create lock file exclusively
+      const meta = getLockMeta();
+      await createLockExclusive(lockPath, meta);
+
+      // Success! Return handle
+      return {
+        path: lockPath,
+        release: async () => {
+          await rm(lockPath, { force: true }).catch(() => undefined);
+        },
+      };
+    } catch (e) {
+      // EEXIST means lock exists
+      if (e && typeof e === 'object' && 'code' in e && e.code === 'EEXIST') {
+        // Check if stale
+        const stale = await isLockStale(lockPath, ttlMs);
+
+        if (stale) {
+          // Atomic stale recovery: rename to .stale, then try again
+          const stalePath = `${lockPath}.stale.${process.pid}`;
+          try {
+            await rename(lockPath, stalePath);
+            // Clean up stale file (ignore errors)
+            await rm(stalePath, { force: true }).catch(() => undefined);
+            // Try again immediately
+            continue;
+          } catch {
+            // Someone else grabbed it - retry with backoff
+          }
+        }
+
+        // Lock is held - wait and retry
+        retries++;
+        await sleep(retryDelayMs);
+        continue;
+      }
+
+      // Other error (permissions, etc.)
+      throw e;
+    }
+  }
+
+  // Failed to acquire after max retries
+  return null;
+}
+
+/**
+ * Execute a function while holding a lock.
+ * Automatically releases lock when done.
+ */
+export async function withLock<T>(
+  lockPath: string,
+  fn: () => Promise<T>,
+  options?: LockOptions
+): Promise<T | null> {
+  const lock = await acquireLock(lockPath, options);
+  if (!lock) {
+    return null;
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await lock.release();
+  }
+}
+
+/**
+ * Get the lock path for a model file path.
+ */
+export function getLockPath(modelPath: string): string {
+  return `${modelPath}.lock`;
+}
+
+/**
+ * Get the manifest lock path for a cache directory.
+ */
+export function getManifestLockPath(cacheDir: string): string {
+  return join(cacheDir, 'manifest.lock');
+}

package/src/llm/nodeLlamaCpp/adapter.ts

@@ -7,11 +7,13 @@
 
 import type { Config } from '../../config/types';
 import { ModelCache } from '../cache';
+import type { DownloadPolicy } from '../policy';
 import { getActivePreset, getModelConfig } from '../registry';
 import type {
   EmbeddingPort,
   GenerationPort,
   LlmResult,
+  ProgressCallback,
   RerankPort,
 } from '../types';
 import { NodeLlamaCppEmbedding } from './embedding';
@@ -19,6 +21,20 @@ import { NodeLlamaCppGeneration } from './generation';
 import { getModelManager, type ModelManager } from './lifecycle';
 import { NodeLlamaCppRerank } from './rerank';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CreatePortOptions {
+  /** Download policy (offline, allowDownload) */
+  policy?: DownloadPolicy;
+  /** Progress callback for downloads */
+  onProgress?: ProgressCallback;
+}
+
+/** Default policy: no auto-download (backwards compatible) */
+const DEFAULT_POLICY: DownloadPolicy = { offline: false, allowDownload: false };
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Adapter
 // ─────────────────────────────────────────────────────────────────────────────
@@ -37,15 +53,23 @@ export class LlmAdapter {
 
   /**
    * Create an embedding port.
+   * With options.policy.allowDownload=true, auto-downloads if not cached.
    */
   async createEmbeddingPort(
-    modelUri?: string
+    modelUri?: string,
+    options?: CreatePortOptions
   ): Promise<LlmResult<EmbeddingPort>> {
     const preset = getActivePreset(this.config);
     const uri = modelUri ?? preset.embed;
-
-    // Resolve model path from cache
-    const resolved = await this.cache.resolve(uri, 'embed');
+    const policy = options?.policy ?? DEFAULT_POLICY;
+
+    // Ensure model is available (downloads if policy allows)
+    const resolved = await this.cache.ensureModel(
+      uri,
+      'embed',
+      policy,
+      options?.onProgress
+    );
     if (!resolved.ok) {
       return resolved;
     }
@@ -58,15 +82,23 @@ export class LlmAdapter {
 
   /**
    * Create a generation port.
+   * With options.policy.allowDownload=true, auto-downloads if not cached.
    */
   async createGenerationPort(
-    modelUri?: string
+    modelUri?: string,
+    options?: CreatePortOptions
   ): Promise<LlmResult<GenerationPort>> {
     const preset = getActivePreset(this.config);
     const uri = modelUri ?? preset.gen;
-
-    // Resolve model path from cache
-    const resolved = await this.cache.resolve(uri, 'gen');
+    const policy = options?.policy ?? DEFAULT_POLICY;
+
+    // Ensure model is available (downloads if policy allows)
+    const resolved = await this.cache.ensureModel(
+      uri,
+      'gen',
+      policy,
+      options?.onProgress
+    );
     if (!resolved.ok) {
       return resolved;
     }
@@ -79,13 +111,23 @@ export class LlmAdapter {
 
   /**
    * Create a rerank port.
+   * With options.policy.allowDownload=true, auto-downloads if not cached.
    */
-  async createRerankPort(modelUri?: string): Promise<LlmResult<RerankPort>> {
+  async createRerankPort(
+    modelUri?: string,
+    options?: CreatePortOptions
+  ): Promise<LlmResult<RerankPort>> {
     const preset = getActivePreset(this.config);
     const uri = modelUri ?? preset.rerank;
-
-    // Resolve model path from cache
-    const resolved = await this.cache.resolve(uri, 'rerank');
+    const policy = options?.policy ?? DEFAULT_POLICY;
+
+    // Ensure model is available (downloads if policy allows)
+    const resolved = await this.cache.ensureModel(
+      uri,
+      'rerank',
+      policy,
+      options?.onProgress
+    );
     if (!resolved.ok) {
       return resolved;
     }