@open-skills-hub/core 1.0.0

package/src/storage/sqlite.ts

@@ -0,0 +1,1838 @@
+/**
+ * Open Skills Hub - SQLite Storage Implementation (using sql.js)
+ */
+
+import initSqlJs, { Database as SqlJsDatabase, SqlValue } from 'sql.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  IStorage,
+  PaginatedResult,
+  SkillQueryOptions,
+  VersionQueryOptions,
+  AuditQueryOptions,
+  FeedbackQueryOptions,
+  QueueQueryOptions,
+  PaginationOptions,
+} from './interface.js';
+import type {
+  Skill,
+  Version,
+  ScanRecord,
+  ScanIssue,
+  Feedback,
+  FeedbackQueueItem,
+  AuditLog,
+  CacheMetadata,
+  UseRecord,
+} from '../models/types.js';
+import { now } from '../utils/helpers.js';
+import { logger } from '../utils/logger.js';
+
+// Type alias for SQL parameters
+type SqlParams = SqlValue[];
+
+// ============================================================================
+// SQLite Schema
+// ============================================================================
+
+const SCHEMA = `
+-- Skills table
+CREATE TABLE IF NOT EXISTS skills (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  scope TEXT,
+  full_name TEXT UNIQUE NOT NULL,
+  
+  owner_id TEXT,
+  owner_type TEXT DEFAULT 'user',
+  
+  display_name TEXT,
+  description TEXT NOT NULL,
+  category TEXT,
+  keywords TEXT DEFAULT '[]',
+  license TEXT,
+  
+  repository TEXT,
+  homepage TEXT,
+  
+  derived_from TEXT,
+  
+  latest_version TEXT,
+  latest_version_id TEXT,
+  
+  visibility TEXT DEFAULT 'public',
+  status TEXT DEFAULT 'active',
+  deprecated_message TEXT,
+  
+  security_score INTEGER,
+  security_level TEXT,
+  last_scan_at TEXT,
+  
+  stats TEXT DEFAULT '{"totalUses":0,"weeklyUses":0,"monthlyUses":0,"versionCount":0,"derivationCount":0}',
+  rating TEXT DEFAULT '{"average":0,"count":0}',
+  
+  searchable_text TEXT,
+  
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  published_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_skills_name ON skills(name);
+CREATE INDEX IF NOT EXISTS idx_skills_full_name ON skills(full_name);
+CREATE INDEX IF NOT EXISTS idx_skills_category ON skills(category);
+CREATE INDEX IF NOT EXISTS idx_skills_visibility ON skills(visibility);
+CREATE INDEX IF NOT EXISTS idx_skills_owner ON skills(owner_id);
+
+-- Versions table
+CREATE TABLE IF NOT EXISTS versions (
+  id TEXT PRIMARY KEY,
+  skill_id TEXT NOT NULL REFERENCES skills(id) ON DELETE CASCADE,
+  
+  version TEXT NOT NULL,
+  tag TEXT,
+  
+  content TEXT NOT NULL,
+  
+  package_url TEXT NOT NULL,
+  package_size INTEGER NOT NULL,
+  package_hash TEXT NOT NULL,
+  
+  changelog TEXT,
+  
+  scan_record_id TEXT,
+  security_score INTEGER,
+  security_level TEXT,
+  
+  status TEXT DEFAULT 'published',
+  deprecated_message TEXT,
+  
+  published_by TEXT,
+  uses INTEGER DEFAULT 0,
+  
+  created_at TEXT DEFAULT (datetime('now')),
+  published_at TEXT DEFAULT (datetime('now')),
+  deprecated_at TEXT,
+  
+  UNIQUE(skill_id, version)
+);
+
+CREATE INDEX IF NOT EXISTS idx_versions_skill ON versions(skill_id);
+CREATE INDEX IF NOT EXISTS idx_versions_tag ON versions(skill_id, tag);
+
+-- Scan records table
+CREATE TABLE IF NOT EXISTS scan_records (
+  id TEXT PRIMARY KEY,
+  
+  skill_id TEXT REFERENCES skills(id) ON DELETE SET NULL,
+  version_id TEXT REFERENCES versions(id) ON DELETE SET NULL,
+  user_id TEXT,
+  
+  input_type TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  content_size INTEGER NOT NULL,
+  
+  score INTEGER,
+  level TEXT,
+  issue_count TEXT DEFAULT '{"high":0,"medium":0,"low":0}',
+  
+  scanner_version TEXT,
+  rules_version TEXT,
+  rules_applied INTEGER,
+  duration INTEGER,
+  
+  status TEXT DEFAULT 'pending',
+  error_message TEXT,
+  
+  created_at TEXT DEFAULT (datetime('now')),
+  completed_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_scan_records_skill ON scan_records(skill_id);
+
+-- Scan issues table
+CREATE TABLE IF NOT EXISTS scan_issues (
+  id TEXT PRIMARY KEY,
+  scan_record_id TEXT NOT NULL REFERENCES scan_records(id) ON DELETE CASCADE,
+  
+  rule_id TEXT NOT NULL,
+  rule_name TEXT NOT NULL,
+  rule_category TEXT NOT NULL,
+  
+  severity TEXT NOT NULL,
+  
+  file TEXT,
+  line INTEGER,
+  column_num INTEGER,
+  end_line INTEGER,
+  end_column INTEGER,
+  
+  content TEXT NOT NULL,
+  context TEXT,
+  message TEXT NOT NULL,
+  suggestion TEXT,
+  
+  acknowledged INTEGER DEFAULT 0,
+  acknowledged_at TEXT,
+  acknowledged_by TEXT,
+  acknowledged_reason TEXT,
+  
+  created_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_scan_issues_record ON scan_issues(scan_record_id);
+
+-- Feedbacks table
+CREATE TABLE IF NOT EXISTS feedbacks (
+  id TEXT PRIMARY KEY,
+  skill_id TEXT NOT NULL REFERENCES skills(id) ON DELETE CASCADE,
+  skill_version TEXT NOT NULL,
+  
+  feedback_type TEXT NOT NULL,
+  rating INTEGER NOT NULL CHECK (rating BETWEEN 1 AND 5),
+  comment TEXT,
+  
+  context TEXT DEFAULT '{}',
+  
+  status TEXT DEFAULT 'pending',
+  reviewer_notes TEXT,
+  reviewed_at TEXT,
+  reviewed_by TEXT,
+  
+  source_ip_hash TEXT,
+  created_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_feedbacks_skill ON feedbacks(skill_id);
+CREATE INDEX IF NOT EXISTS idx_feedbacks_type ON feedbacks(feedback_type);
+CREATE INDEX IF NOT EXISTS idx_feedbacks_status ON feedbacks(status);
+
+-- Feedback queue table
+CREATE TABLE IF NOT EXISTS feedback_queue (
+  id TEXT PRIMARY KEY,
+  skill_name TEXT NOT NULL,
+  skill_version TEXT NOT NULL,
+  feedback TEXT NOT NULL,
+  
+  status TEXT DEFAULT 'pending',
+  
+  attempts INTEGER DEFAULT 0,
+  max_attempts INTEGER DEFAULT 5,
+  last_attempt_at TEXT,
+  next_retry_at TEXT,
+  last_error TEXT,
+  
+  base_delay INTEGER DEFAULT 1000,
+  current_delay INTEGER DEFAULT 1000,
+  max_delay INTEGER DEFAULT 3600000,
+  
+  created_at TEXT DEFAULT (datetime('now')),
+  processed_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_feedback_queue_status ON feedback_queue(status);
+CREATE INDEX IF NOT EXISTS idx_feedback_queue_next_retry ON feedback_queue(next_retry_at);
+
+-- Audit logs table
+CREATE TABLE IF NOT EXISTS audit_logs (
+  id TEXT PRIMARY KEY,
+  timestamp TEXT DEFAULT (datetime('now')),
+  
+  event_type TEXT NOT NULL,
+  
+  actor TEXT NOT NULL,
+  resource TEXT NOT NULL,
+  
+  action TEXT NOT NULL,
+  result TEXT NOT NULL,
+  
+  details TEXT,
+  changes TEXT,
+  
+  error_code TEXT,
+  error_message TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_logs_timestamp ON audit_logs(timestamp);
+CREATE INDEX IF NOT EXISTS idx_audit_logs_event_type ON audit_logs(event_type);
+
+-- Cache metadata table
+CREATE TABLE IF NOT EXISTS cache_metadata (
+  id TEXT PRIMARY KEY,
+  skill_name TEXT NOT NULL,
+  version TEXT NOT NULL,
+  
+  cached_at TEXT DEFAULT (datetime('now')),
+  expires_at TEXT,
+  
+  size INTEGER,
+  hit_count INTEGER DEFAULT 0,
+  last_hit_at TEXT,
+  
+  source TEXT,
+  integrity_hash TEXT,
+  
+  UNIQUE(skill_name, version)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cache_metadata_expires ON cache_metadata(expires_at);
+
+-- Use records table
+CREATE TABLE IF NOT EXISTS use_records (
+  id TEXT PRIMARY KEY,
+  skill_id TEXT NOT NULL REFERENCES skills(id) ON DELETE CASCADE,
+  version_id TEXT REFERENCES versions(id),
+  user_id TEXT,
+  
+  source TEXT NOT NULL,
+  cache_hit INTEGER DEFAULT 0,
+  client_version TEXT,
+  
+  platform TEXT,
+  arch TEXT,
+  
+  ip TEXT NOT NULL,
+  user_agent TEXT,
+  country TEXT,
+  region TEXT,
+  
+  created_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_use_records_skill ON use_records(skill_id, created_at);
+`;
+
+// ============================================================================
+// SQLite Storage Implementation
+// ============================================================================
+
+export class SQLiteStorage implements IStorage {
+  private db: SqlJsDatabase | null = null;
+  private dbPath: string;
+  private saveInterval: ReturnType<typeof setInterval> | null = null;
+  private isDirty = false;
+
+  constructor(dbPath: string) {
+    this.dbPath = dbPath;
+  }
+
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+
+  async initialize(): Promise<void> {
+    try {
+      const SQL = await initSqlJs();
+      
+      // Load existing database or create new one
+      if (fs.existsSync(this.dbPath)) {
+        const buffer = fs.readFileSync(this.dbPath);
+        this.db = new SQL.Database(buffer);
+      } else {
+        // Ensure directory exists
+        const dir = path.dirname(this.dbPath);
+        if (!fs.existsSync(dir)) {
+          fs.mkdirSync(dir, { recursive: true });
+        }
+        this.db = new SQL.Database();
+      }
+
+      // Enable foreign keys and run schema
+      this.db.run('PRAGMA foreign_keys = ON;');
+      this.db.run(SCHEMA);
+      
+      // Save periodically (every 5 seconds if dirty)
+      this.saveInterval = setInterval(() => {
+        if (this.isDirty) {
+          this.persist();
+        }
+      }, 5000);
+
+      logger.info('SQLite storage initialized', { path: this.dbPath });
+    } catch (error) {
+      logger.error('Failed to initialize SQLite storage', { error });
+      throw error;
+    }
+  }
+
+  private persist(): void {
+    if (this.db && this.isDirty) {
+      const data = this.db.export();
+      const buffer = Buffer.from(data);
+      fs.writeFileSync(this.dbPath, buffer);
+      this.isDirty = false;
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.saveInterval) {
+      clearInterval(this.saveInterval);
+      this.saveInterval = null;
+    }
+    if (this.db) {
+      this.persist();
+      this.db.close();
+      this.db = null;
+      logger.info('SQLite storage closed');
+    }
+  }
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      this.getDb().exec('SELECT 1');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async sync(): Promise<void> {
+    this.persist();
+    logger.debug('SQLite storage synced to disk');
+  }
+
+  /**
+   * Reload the database from disk file
+   * This is useful when external processes (like CLI) have updated the database
+   */
+  async reload(): Promise<void> {
+    try {
+      // First persist any pending changes
+      this.persist();
+      
+      // Check if database file exists
+      if (!fs.existsSync(this.dbPath)) {
+        logger.warn('Database file not found during reload', { path: this.dbPath });
+        return;
+      }
+      
+      // Read the updated file
+      const buffer = fs.readFileSync(this.dbPath);
+      
+      // Get SQL.js constructor
+      const SQL = await initSqlJs();
+      
+      // Create new database from file
+      const newDb = new SQL.Database(buffer);
+      newDb.run('PRAGMA foreign_keys = ON;');
+      
+      // Close old database
+      if (this.db) {
+        this.db.close();
+      }
+      
+      // Replace with new database
+      this.db = newDb;
+      this.isDirty = false;
+      
+      logger.info('Database reloaded from disk', { path: this.dbPath });
+    } catch (error) {
+      logger.error('Failed to reload database', { error });
+      throw error;
+    }
+  }
+
+  private getDb(): SqlJsDatabase {
+    if (!this.db) {
+      throw new Error('Database not initialized');
+    }
+    return this.db;
+  }
+
+  private run(sql: string, params?: Record<string, unknown>): void {
+    const db = this.getDb();
+    if (params) {
+      db.run(sql, params as Record<string, string | number | null | Uint8Array>);
+    } else {
+      db.run(sql);
+    }
+    this.isDirty = true;
+  }
+
+  private get<T>(sql: string, params?: SqlParams): T | undefined {
+    const db = this.getDb();
+    const stmt = db.prepare(sql);
+    if (params) {
+      stmt.bind(params);
+    }
+    if (stmt.step()) {
+      const columns = stmt.getColumnNames();
+      const values = stmt.get();
+      stmt.free();
+      const row: Record<string, unknown> = {};
+      columns.forEach((col, i) => {
+        row[col] = values[i];
+      });
+      return row as T;
+    }
+    stmt.free();
+    return undefined;
+  }
+
+  private all<T>(sql: string, params?: SqlParams): T[] {
+    const db = this.getDb();
+    const stmt = db.prepare(sql);
+    if (params) {
+      stmt.bind(params);
+    }
+    const results: T[] = [];
+    const columns = stmt.getColumnNames();
+    while (stmt.step()) {
+      const values = stmt.get();
+      const row: Record<string, unknown> = {};
+      columns.forEach((col, i) => {
+        row[col] = values[i];
+      });
+      results.push(row as T);
+    }
+    stmt.free();
+    return results;
+  }
+
+  // -------------------------------------------------------------------------
+  // Skills
+  // -------------------------------------------------------------------------
+
+  async createSkill(skill: Skill): Promise<Skill> {
+    const searchableText = [
+      skill.name,
+      skill.displayName,
+      skill.description,
+      skill.keywords.join(' '),
+    ].filter(Boolean).join(' ');
+
+    this.run(`
+      INSERT INTO skills (
+        id, name, scope, full_name, owner_id, owner_type,
+        display_name, description, category, keywords, license,
+        repository, homepage, derived_from, latest_version, latest_version_id,
+        visibility, status, deprecated_message, security_score, security_level,
+        last_scan_at, stats, rating, searchable_text, created_at, updated_at, published_at
+      ) VALUES (
+        $id, $name, $scope, $fullName, $ownerId, $ownerType,
+        $displayName, $description, $category, $keywords, $license,
+        $repository, $homepage, $derivedFrom, $latestVersion, $latestVersionId,
+        $visibility, $status, $deprecatedMessage, $securityScore, $securityLevel,
+        $lastScanAt, $stats, $rating, $searchableText, $createdAt, $updatedAt, $publishedAt
+      )
+    `, {
+      $id: skill.id,
+      $name: skill.name,
+      $scope: skill.scope ?? null,
+      $fullName: skill.fullName,
+      $ownerId: skill.ownerId ?? null,
+      $ownerType: skill.ownerType,
+      $displayName: skill.displayName ?? null,
+      $description: skill.description,
+      $category: skill.category ?? null,
+      $keywords: JSON.stringify(skill.keywords),
+      $license: skill.license ?? null,
+      $repository: skill.repository ?? null,
+      $homepage: skill.homepage ?? null,
+      $derivedFrom: skill.derivedFrom ? JSON.stringify(skill.derivedFrom) : null,
+      $latestVersion: skill.latestVersion,
+      $latestVersionId: skill.latestVersionId ?? null,
+      $visibility: skill.visibility,
+      $status: skill.status,
+      $deprecatedMessage: skill.deprecatedMessage ?? null,
+      $securityScore: skill.securityScore ?? null,
+      $securityLevel: skill.securityLevel ?? null,
+      $lastScanAt: skill.lastScanAt ?? null,
+      $stats: JSON.stringify(skill.stats),
+      $rating: JSON.stringify(skill.rating),
+      $searchableText: searchableText,
+      $createdAt: skill.createdAt,
+      $updatedAt: skill.updatedAt,
+      $publishedAt: skill.publishedAt ?? null,
+    });
+
+    return skill;
+  }
+
+  async getSkillById(id: string): Promise<Skill | null> {
+    const row = this.get<Record<string, unknown>>('SELECT * FROM skills WHERE id = ?', [id]);
+    return row ? this.rowToSkill(row) : null;
+  }
+
+  async getSkillByName(fullName: string): Promise<Skill | null> {
+    const row = this.get<Record<string, unknown>>('SELECT * FROM skills WHERE full_name = ?', [fullName]);
+    return row ? this.rowToSkill(row) : null;
+  }
+
+  async updateSkill(id: string, updates: Partial<Skill>): Promise<Skill | null> {
+    const existing = await this.getSkillById(id);
+    if (!existing) return null;
+
+    const updated = { ...existing, ...updates, updatedAt: now() };
+    
+    const searchableText = [
+      updated.name,
+      updated.displayName,
+      updated.description,
+      updated.keywords.join(' '),
+    ].filter(Boolean).join(' ');
+
+    this.run(`
+      UPDATE skills SET
+        name = $name,
+        scope = $scope,
+        full_name = $fullName,
+        owner_id = $ownerId,
+        owner_type = $ownerType,
+        display_name = $displayName,
+        description = $description,
+        category = $category,
+        keywords = $keywords,
+        license = $license,
+        repository = $repository,
+        homepage = $homepage,
+        derived_from = $derivedFrom,
+        latest_version = $latestVersion,
+        latest_version_id = $latestVersionId,
+        visibility = $visibility,
+        status = $status,
+        deprecated_message = $deprecatedMessage,
+        security_score = $securityScore,
+        security_level = $securityLevel,
+        last_scan_at = $lastScanAt,
+        stats = $stats,
+        rating = $rating,
+        searchable_text = $searchableText,
+        updated_at = $updatedAt,
+        published_at = $publishedAt
+      WHERE id = $id
+    `, {
+      $id: updated.id,
+      $name: updated.name,
+      $scope: updated.scope ?? null,
+      $fullName: updated.fullName,
+      $ownerId: updated.ownerId ?? null,
+      $ownerType: updated.ownerType,
+      $displayName: updated.displayName ?? null,
+      $description: updated.description,
+      $category: updated.category ?? null,
+      $keywords: JSON.stringify(updated.keywords),
+      $license: updated.license ?? null,
+      $repository: updated.repository ?? null,
+      $homepage: updated.homepage ?? null,
+      $derivedFrom: updated.derivedFrom ? JSON.stringify(updated.derivedFrom) : null,
+      $latestVersion: updated.latestVersion,
+      $latestVersionId: updated.latestVersionId ?? null,
+      $visibility: updated.visibility,
+      $status: updated.status,
+      $deprecatedMessage: updated.deprecatedMessage ?? null,
+      $securityScore: updated.securityScore ?? null,
+      $securityLevel: updated.securityLevel ?? null,
+      $lastScanAt: updated.lastScanAt ?? null,
+      $stats: JSON.stringify(updated.stats),
+      $rating: JSON.stringify(updated.rating),
+      $searchableText: searchableText,
+      $updatedAt: updated.updatedAt,
+      $publishedAt: updated.publishedAt ?? null,
+    });
+
+    return updated;
+  }
+
+  async deleteSkill(id: string): Promise<boolean> {
+    const before = this.get<{ count: number }>('SELECT COUNT(*) as count FROM skills WHERE id = ?', [id]);
+    this.run('DELETE FROM skills WHERE id = ?', { $id: id });
+    const after = this.get<{ count: number }>('SELECT COUNT(*) as count FROM skills WHERE id = ?', [id]);
+    return (before?.count ?? 0) > (after?.count ?? 0);
+  }
+
+  async searchSkills(options: SkillQueryOptions): Promise<PaginatedResult<Skill>> {
+    const limit = Math.min(options.limit ?? 20, 100);
+    const conditions: string[] = ["visibility = 'public'", "status = 'active'"];
+    const params: SqlParams = [];
+
+    // Basic search using LIKE (sql.js doesn't support FTS5)
+    if (options.query) {
+      conditions.push('(name LIKE ? OR display_name LIKE ? OR description LIKE ? OR searchable_text LIKE ?)');
+      const searchTerm = `%${options.query}%`;
+      params.push(searchTerm, searchTerm, searchTerm, searchTerm);
+    }
+
+    if (options.category) {
+      conditions.push('category = ?');
+      params.push(options.category);
+    }
+    if (options.author) {
+      conditions.push('owner_id = ?');
+      params.push(options.author);
+    }
+    if (options.visibility) {
+      // Override the default public visibility
+      conditions[0] = 'visibility = ?';
+      params.unshift(options.visibility);
+    }
+
+    // Sorting
+    const sortField = options.sort ?? 'updated';
+    const sortOrder = options.order ?? 'desc';
+    const sortMap: Record<string, string> = {
+      relevance: 'updated_at',
+      uses: "json_extract(stats, '$.totalUses')",
+      updated: 'updated_at',
+      created: 'created_at',
+      name: 'name',
+    };
+
+    let query = `SELECT * FROM skills WHERE ${conditions.join(' AND ')}`;
+    let countQuery = `SELECT COUNT(*) as count FROM skills WHERE ${conditions.join(' AND ')}`;
+
+    if (options.cursor) {
+      query += ' AND id > ?';
+      params.push(options.cursor);
+    }
+
+    query += ` ORDER BY ${sortMap[sortField]} ${sortOrder.toUpperCase()} LIMIT ?`;
+    params.push(limit + 1);
+
+    const rows = this.all<Record<string, unknown>>(query, params);
+    const countParams = options.cursor ? params.slice(0, -2) : params.slice(0, -1);
+    const countResult = this.get<{ count: number }>(countQuery, countParams);
+
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit).map(row => this.rowToSkill(row));
+
+    return {
+      items,
+      pagination: {
+        total: countResult?.count ?? 0,
+        limit,
+        hasMore,
+        cursor: options.cursor,
+        nextCursor: hasMore && items.length > 0 ? items[items.length - 1]?.id : undefined,
+      },
+    };
+  }
+
+  async getSkillsByOwner(ownerId: string, options?: PaginationOptions): Promise<PaginatedResult<Skill>> {
+    const limit = Math.min(options?.limit ?? 20, 100);
+    const params: SqlParams = [ownerId];
+
+    let query = 'SELECT * FROM skills WHERE owner_id = ?';
+
+    if (options?.cursor) {
+      query += ' AND id > ?';
+      params.push(options.cursor);
+    }
+
+    query += ' ORDER BY created_at DESC LIMIT ?';
+    params.push(limit + 1);
+
+    const rows = this.all<Record<string, unknown>>(query, params);
+    const countResult = this.get<{ count: number }>('SELECT COUNT(*) as count FROM skills WHERE owner_id = ?', [ownerId]);
+
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit).map(row => this.rowToSkill(row));
+
+    return {
+      items,
+      pagination: {
+        total: countResult?.count ?? 0,
+        limit,
+        hasMore,
+        cursor: options?.cursor,
+        nextCursor: hasMore && items.length > 0 ? items[items.length - 1]?.id : undefined,
+      },
+    };
+  }
+
+  async getDerivedSkills(skillId: string, options?: PaginationOptions): Promise<PaginatedResult<Skill>> {
+    const limit = Math.min(options?.limit ?? 20, 100);
+    const params: SqlParams = [skillId];
+
+    let query = "SELECT * FROM skills WHERE json_extract(derived_from, '$.skillId') = ?";
+
+    if (options?.cursor) {
+      query += ' AND id > ?';
+      params.push(options.cursor);
+    }
+
+    query += ' ORDER BY created_at DESC LIMIT ?';
+    params.push(limit + 1);
+
+    const rows = this.all<Record<string, unknown>>(query, params);
+    const countResult = this.get<{ count: number }>(
+      "SELECT COUNT(*) as count FROM skills WHERE json_extract(derived_from, '$.skillId') = ?",
+      [skillId]
+    );
+
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit).map(row => this.rowToSkill(row));
+
+    return {
+      items,
+      pagination: {
+        total: countResult?.count ?? 0,
+        limit,
+        hasMore,
+        cursor: options?.cursor,
+        nextCursor: hasMore && items.length > 0 ? items[items.length - 1]?.id : undefined,
+      },
+    };
+  }
+
+  async incrementSkillUses(id: string): Promise<void> {
+    this.run(`
+      UPDATE skills 
+      SET stats = json_set(stats, '$.totalUses', json_extract(stats, '$.totalUses') + 1)
+      WHERE id = ?
+    `, { $id: id });
+  }
+
+  // -------------------------------------------------------------------------
+  // Versions
+  // -------------------------------------------------------------------------
+
+  async createVersion(version: Version): Promise<Version> {
+    this.run(`
+      INSERT INTO versions (
+        id, skill_id, version, tag, content, package_url, package_size, package_hash,
+        changelog, scan_record_id, security_score, security_level, status,
+        deprecated_message, published_by, uses, created_at, published_at, deprecated_at
+      ) VALUES (
+        $id, $skillId, $version, $tag, $content, $packageUrl, $packageSize, $packageHash,
+        $changelog, $scanRecordId, $securityScore, $securityLevel, $status,
+        $deprecatedMessage, $publishedBy, $uses, $createdAt, $publishedAt, $deprecatedAt
+      )
+    `, {
+      $id: version.id,
+      $skillId: version.skillId,
+      $version: version.version,
+      $tag: version.tag ?? null,
+      $content: JSON.stringify(version.content),
+      $packageUrl: version.packageUrl,
+      $packageSize: version.packageSize,
+      $packageHash: version.packageHash,
+      $changelog: version.changelog ?? null,
+      $scanRecordId: version.scanRecordId ?? null,
+      $securityScore: version.securityScore ?? null,
+      $securityLevel: version.securityLevel ?? null,
+      $status: version.status,
+      $deprecatedMessage: version.deprecatedMessage ?? null,
+      $publishedBy: version.publishedBy ?? null,
+      $uses: version.uses,
+      $createdAt: version.createdAt,
+      $publishedAt: version.publishedAt,
+      $deprecatedAt: version.deprecatedAt ?? null,
+    });
+
+    return version;
+  }
+
+  async getVersionById(id: string): Promise<Version | null> {
+    const row = this.get<Record<string, unknown>>('SELECT * FROM versions WHERE id = ?', [id]);
+    return row ? this.rowToVersion(row) : null;
+  }
+
+  async getVersion(skillId: string, version: string): Promise<Version | null> {
+    const row = this.get<Record<string, unknown>>(
+      'SELECT * FROM versions WHERE skill_id = ? AND version = ?',
+      [skillId, version]
+    );
+    return row ? this.rowToVersion(row) : null;
+  }
+
+  async getLatestVersion(skillId: string): Promise<Version | null> {
+    let row = this.get<Record<string, unknown>>(
+      "SELECT * FROM versions WHERE skill_id = ? AND tag = 'latest' LIMIT 1",
+      [skillId]
+    );
+    
+    if (!row) {
+      row = this.get<Record<string, unknown>>(
+        'SELECT * FROM versions WHERE skill_id = ? ORDER BY published_at DESC LIMIT 1',
+        [skillId]
+      );
+    }
+    
+    return row ? this.rowToVersion(row) : null;
+  }
+
+  async getVersions(skillId: string, options?: VersionQueryOptions): Promise<PaginatedResult<Version>> {
+    const limit = Math.min(options?.limit ?? 20, 100);
+    const params: SqlParams = [skillId];
+
+    let query = 'SELECT * FROM versions WHERE skill_id = ?';
+
+    if (!options?.includeDeprecated) {
+      query += " AND status != 'deprecated'";
+    }
+
+    if (options?.cursor) {
+      query += ' AND id > ?';
+      params.push(options.cursor);
+    }
+
+    query += ' ORDER BY published_at DESC LIMIT ?';
+    params.push(limit + 1);
+
+    const rows = this.all<Record<string, unknown>>(query, params);
+    const countResult = this.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM versions WHERE skill_id = ?',
+      [skillId]
+    );
+
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit).map(row => this.rowToVersion(row));
+
+    return {
+      items,
+      pagination: {
+        total: countResult?.count ?? 0,
+        limit,
+        hasMore,
+        cursor: options?.cursor,
+        nextCursor: hasMore && items.length > 0 ? items[items.length - 1]?.id : undefined,
+      },
+    };
+  }
+
+  async updateVersion(id: string, updates: Partial<Version>): Promise<Version | null> {
+    const existing = await this.getVersionById(id);
+    if (!existing) return null;
+
+    const updated = { ...existing, ...updates };
+
+    this.run(`
+      UPDATE versions SET
+        tag = $tag,
+        changelog = $changelog,
+        scan_record_id = $scanRecordId,
+        security_score = $securityScore,
+        security_level = $securityLevel,
+        status = $status,
+        deprecated_message = $deprecatedMessage,
+        uses = $uses,
+        deprecated_at = $deprecatedAt
+      WHERE id = $id
+    `, {
+      $id: updated.id,
+      $tag: updated.tag ?? null,
+      $changelog: updated.changelog ?? null,
+      $scanRecordId: updated.scanRecordId ?? null,
+      $securityScore: updated.securityScore ?? null,
+      $securityLevel: updated.securityLevel ?? null,
+      $status: updated.status,
+      $deprecatedMessage: updated.deprecatedMessage ?? null,
+      $uses: updated.uses,
+      $deprecatedAt: updated.deprecatedAt ?? null,
+    });
+
+    return updated;
+  }
+
+  async deleteVersion(id: string): Promise<boolean> {
+    const before = this.get<{ count: number }>('SELECT COUNT(*) as count FROM versions WHERE id = ?', [id]);
+    this.run('DELETE FROM versions WHERE id = ?', { $id: id });
+    const after = this.get<{ count: number }>('SELECT COUNT(*) as count FROM versions WHERE id = ?', [id]);
+    return (before?.count ?? 0) > (after?.count ?? 0);
+  }
+
+  async deprecateVersion(id: string, message: string): Promise<Version | null> {
+    return this.updateVersion(id, {
+      status: 'deprecated',
+      deprecatedMessage: message,
+      deprecatedAt: now(),
+    });
+  }
+
+  async incrementVersionUses(id: string): Promise<void> {
+    this.run('UPDATE versions SET uses = uses + 1 WHERE id = ?', { $id: id });
+  }
+
+  // -------------------------------------------------------------------------
+  // Scan Records
+  // -------------------------------------------------------------------------
+
+  async createScanRecord(record: ScanRecord): Promise<ScanRecord> {
+    this.run(`
+      INSERT INTO scan_records (
+        id, skill_id, version_id, user_id, input_type, content_hash, content_size,
+        score, level, issue_count, scanner_version, rules_version, rules_applied,
+        duration, status, error_message, created_at, completed_at
+      ) VALUES (
+        $id, $skillId, $versionId, $userId, $inputType, $contentHash, $contentSize,
+        $score, $level, $issueCount, $scannerVersion, $rulesVersion, $rulesApplied,
+        $duration, $status, $errorMessage, $createdAt, $completedAt
+      )
+    `, {
+      $id: record.id,
+      $skillId: record.skillId ?? null,
+      $versionId: record.versionId ?? null,
+      $userId: record.userId ?? null,
+      $inputType: record.inputType,
+      $contentHash: record.contentHash,
+      $contentSize: record.contentSize,
+      $score: record.score ?? null,
+      $level: record.level ?? null,
+      $issueCount: JSON.stringify(record.issueCount),
+      $scannerVersion: record.scannerVersion ?? null,
+      $rulesVersion: record.rulesVersion ?? null,
+      $rulesApplied: record.rulesApplied ?? null,
+      $duration: record.duration ?? null,
+      $status: record.status,
+      $errorMessage: record.errorMessage ?? null,
+      $createdAt: record.createdAt,
+      $completedAt: record.completedAt ?? null,
+    });
+
+    return record;
+  }
+
+  async getScanRecordById(id: string): Promise<ScanRecord | null> {
+    const row = this.get<Record<string, unknown>>('SELECT * FROM scan_records WHERE id = ?', [id]);
+    return row ? this.rowToScanRecord(row) : null;
+  }
+
+  async getScanRecords(skillId: string, options?: PaginationOptions): Promise<PaginatedResult<ScanRecord>> {
+    const limit = Math.min(options?.limit ?? 20, 100);
+    const params: SqlParams = [skillId];
+
+    let query = 'SELECT * FROM scan_records WHERE skill_id = ?';
+
+    if (options?.cursor) {
+      query += ' AND id > ?';
+      params.push(options.cursor);
+    }
+
+    query += ' ORDER BY created_at DESC LIMIT ?';
+    params.push(limit + 1);
+
+    const rows = this.all<Record<string, unknown>>(query, params);
+    const countResult = this.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM scan_records WHERE skill_id = ?',
+      [skillId]
+    );
+
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit).map(row => this.rowToScanRecord(row));
+
+    return {
+      items,
+      pagination: {
+        total: countResult?.count ?? 0,
+        limit,
+        hasMore,
+        cursor: options?.cursor,
+        nextCursor: hasMore && items.length > 0 ? items[items.length - 1]?.id : undefined,
+      },
+    };
+  }
+
+  async updateScanRecord(id: string, updates: Partial<ScanRecord>): Promise<ScanRecord | null> {
+    const existing = await this.getScanRecordById(id);
+    if (!existing) return null;
+
+    const updated = { ...existing, ...updates };
+
+    this.run(`
+      UPDATE scan_records SET
+        score = $score,
+        level = $level,
+        issue_count = $issueCount,
+        scanner_version = $scannerVersion,
+        rules_version = $rulesVersion,
+        rules_applied = $rulesApplied,
+        duration = $duration,
+        status = $status,
+        error_message = $errorMessage,
+        completed_at = $completedAt
+      WHERE id = $id
+    `, {
+      $id: updated.id,
+      $score: updated.score ?? null,
+      $level: updated.level ?? null,
+      $issueCount: JSON.stringify(updated.issueCount),
+      $scannerVersion: updated.scannerVersion ?? null,
+      $rulesVersion: updated.rulesVersion ?? null,
+      $rulesApplied: updated.rulesApplied ?? null,
+      $duration: updated.duration ?? null,
+      $status: updated.status,
+      $errorMessage: updated.errorMessage ?? null,
+      $completedAt: updated.completedAt ?? null,
+    });
+
+    return updated;
+  }
+
+  // -------------------------------------------------------------------------
+  // Scan Issues
+  // -------------------------------------------------------------------------
+
+  async createScanIssues(issues: ScanIssue[]): Promise<ScanIssue[]> {
+    for (const issue of issues) {
+      this.run(`
+        INSERT INTO scan_issues (
+          id, scan_record_id, rule_id, rule_name, rule_category, severity,
+          file, line, column_num, end_line, end_column, content, context,
+          message, suggestion, acknowledged, acknowledged_at, acknowledged_by,
+          acknowledged_reason, created_at
+        ) VALUES (
+          $id, $scanRecordId, $ruleId, $ruleName, $ruleCategory, $severity,
+          $file, $line, $column, $endLine, $endColumn, $content, $context,
+          $message, $suggestion, $acknowledged, $acknowledgedAt, $acknowledgedBy,
+          $acknowledgedReason, $createdAt
+        )
+      `, {
+        $id: issue.id,
+        $scanRecordId: issue.scanRecordId,
+        $ruleId: issue.ruleId,
+        $ruleName: issue.ruleName,
+        $ruleCategory: issue.ruleCategory,
+        $severity: issue.severity,
+        $file: issue.file ?? null,
+        $line: issue.line ?? null,
+        $column: issue.column ?? null,
+        $endLine: issue.endLine ?? null,
+        $endColumn: issue.endColumn ?? null,
+        $content: issue.content,
+        $context: issue.context ?? null,
+        $message: issue.message,
+        $suggestion: issue.suggestion ?? null,
+        $acknowledged: issue.acknowledged ? 1 : 0,
+        $acknowledgedAt: issue.acknowledgedAt ?? null,
+        $acknowledgedBy: issue.acknowledgedBy ?? null,
+        $acknowledgedReason: issue.acknowledgedReason ?? null,
+        $createdAt: issue.createdAt,
+      });
+    }
+
+    return issues;
+  }
+
+  async getScanIssues(scanRecordId: string): Promise<ScanIssue[]> {
+    const rows = this.all<Record<string, unknown>>(
+      'SELECT * FROM scan_issues WHERE scan_record_id = ? ORDER BY severity DESC, line ASC',
+      [scanRecordId]
+    );
+    return rows.map(row => this.rowToScanIssue(row));
+  }
+
+  async acknowledgeIssue(id: string, userId: string, reason?: string): Promise<ScanIssue | null> {
+    this.run(`
+      UPDATE scan_issues SET
+        acknowledged = 1,
+        acknowledged_at = $acknowledgedAt,
+        acknowledged_by = $acknowledgedBy,
+        acknowledged_reason = $acknowledgedReason
+      WHERE id = $id
+    `, {
+      $id: id,
+      $acknowledgedAt: now(),
+      $acknowledgedBy: userId,
+      $acknowledgedReason: reason ?? null,
+    });
+
+    const row = this.get<Record<string, unknown>>('SELECT * FROM scan_issues WHERE id = ?', [id]);
+    return row ? this.rowToScanIssue(row) : null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Feedback
+  // -------------------------------------------------------------------------
+
+  async createFeedback(feedback: Feedback): Promise<Feedback> {
+    this.run(`
+      INSERT INTO feedbacks (
+        id, skill_id, skill_version, feedback_type, rating, comment,
+        context, status, reviewer_notes, reviewed_at, reviewed_by,
+        source_ip_hash, created_at
+      ) VALUES (
+        $id, $skillId, $skillVersion, $feedbackType, $rating, $comment,
+        $context, $status, $reviewerNotes, $reviewedAt, $reviewedBy,
+        $sourceIpHash, $createdAt
+      )
+    `, {
+      $id: feedback.id,
+      $skillId: feedback.skillId,
+      $skillVersion: feedback.skillVersion,
+      $feedbackType: feedback.feedbackType,
+      $rating: feedback.rating,
+      $comment: feedback.comment ?? null,
+      $context: JSON.stringify(feedback.context),
+      $status: feedback.status,
+      $reviewerNotes: feedback.reviewerNotes ?? null,
+      $reviewedAt: feedback.reviewedAt ?? null,
+      $reviewedBy: feedback.reviewedBy ?? null,
+      $sourceIpHash: feedback.sourceIpHash ?? null,
+      $createdAt: feedback.createdAt,
+    });
+
+    return feedback;
+  }
+
+  async getFeedbackById(id: string): Promise<Feedback | null> {
+    const row = this.get<Record<string, unknown>>('SELECT * FROM feedbacks WHERE id = ?', [id]);
+    return row ? this.rowToFeedback(row) : null;
+  }
+
+  async getFeedbacks(skillId: string, options?: FeedbackQueryOptions): Promise<PaginatedResult<Feedback>> {
+    const limit = Math.min(options?.limit ?? 20, 100);
+    const params: SqlParams = [skillId];
+    const conditions: string[] = ['skill_id = ?'];
+
+    if (options?.feedbackType) {
+      conditions.push('feedback_type = ?');
+      params.push(options.feedbackType);
+    }
+
+    if (options?.status) {
+      conditions.push('status = ?');
+      params.push(options.status);
+    }
+
+    if (options?.cursor) {
+      conditions.push('id > ?');
+      params.push(options.cursor);
+    }
+
+    const whereClause = conditions.join(' AND ');
+    const query = `SELECT * FROM feedbacks WHERE ${whereClause} ORDER BY created_at DESC LIMIT ?`;
+    params.push(limit + 1);
+
+    const rows = this.all<Record<string, unknown>>(query, params);
+    const countResult = this.get<{ count: number }>(
+      'SELECT COUNT(*) as count FROM feedbacks WHERE skill_id = ?',
+      [skillId]
+    );
+
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit).map(row => this.rowToFeedback(row));
+
+    return {
+      items,
+      pagination: {
+        total: countResult?.count ?? 0,
+        limit,
+        hasMore,
+        cursor: options?.cursor,
+        nextCursor: hasMore && items.length > 0 ? items[items.length - 1]?.id : undefined,
+      },
+    };
+  }
+
+  async updateFeedback(id: string, updates: Partial<Feedback>): Promise<Feedback | null> {
+    const existing = await this.getFeedbackById(id);
+    if (!existing) return null;
+
+    const updated = { ...existing, ...updates };
+
+    this.run(`
+      UPDATE feedbacks SET
+        status = $status,
+        reviewer_notes = $reviewerNotes,
+        reviewed_at = $reviewedAt,
+        reviewed_by = $reviewedBy
+      WHERE id = $id
+    `, {
+      $id: updated.id,
+      $status: updated.status,
+      $reviewerNotes: updated.reviewerNotes ?? null,
+      $reviewedAt: updated.reviewedAt ?? null,
+      $reviewedBy: updated.reviewedBy ?? null,
+    });
+
+    return updated;
+  }
+
+  // -------------------------------------------------------------------------
+  // Feedback Queue
+  // -------------------------------------------------------------------------
+
+  async enqueueFeedback(item: FeedbackQueueItem): Promise<FeedbackQueueItem> {
+    this.run(`
+      INSERT INTO feedback_queue (
+        id, skill_name, skill_version, feedback, status, attempts, max_attempts,
+        last_attempt_at, next_retry_at, last_error, base_delay, current_delay,
+        max_delay, created_at, processed_at
+      ) VALUES (
+        $id, $skillName, $skillVersion, $feedback, $status, $attempts, $maxAttempts,
+        $lastAttemptAt, $nextRetryAt, $lastError, $baseDelay, $currentDelay,
+        $maxDelay, $createdAt, $processedAt
+      )
+    `, {
+      $id: item.id,
+      $skillName: item.skillName,
+      $skillVersion: item.skillVersion,
+      $feedback: JSON.stringify(item.feedback),
+      $status: item.status,
+      $attempts: item.attempts,
+      $maxAttempts: item.maxAttempts,
+      $lastAttemptAt: item.lastAttemptAt ?? null,
+      $nextRetryAt: item.nextRetryAt ?? null,
+      $lastError: item.lastError ?? null,
+      $baseDelay: item.baseDelay,
+      $currentDelay: item.currentDelay,
+      $maxDelay: item.maxDelay,
+      $createdAt: item.createdAt,
+      $processedAt: item.processedAt ?? null,
+    });
+
+    return item;
+  }
+
+  async getPendingQueueItems(options?: QueueQueryOptions): Promise<FeedbackQueueItem[]> {
+    const limit = options?.limit ?? 10;
+
+    let query: string;
+    let params: SqlParams;
+
+    if (options?.status) {
+      query = `
+        SELECT * FROM feedback_queue 
+        WHERE status = ?
+          AND (next_retry_at IS NULL OR next_retry_at <= datetime('now'))
+        ORDER BY created_at ASC LIMIT ?
+      `;
+      params = [options.status, limit];
+    } else {
+      query = `
+        SELECT * FROM feedback_queue 
+        WHERE status IN ('pending', 'retrying')
+          AND (next_retry_at IS NULL OR next_retry_at <= datetime('now'))
+        ORDER BY created_at ASC LIMIT ?
+      `;
+      params = [limit];
+    }
+
+    const rows = this.all<Record<string, unknown>>(query, params);
+    return rows.map(row => this.rowToQueueItem(row));
+  }
+
+  async updateQueueItem(id: string, updates: Partial<FeedbackQueueItem>): Promise<FeedbackQueueItem | null> {
+    const row = this.get<Record<string, unknown>>('SELECT * FROM feedback_queue WHERE id = ?', [id]);
+    if (!row) return null;
+
+    const existing = this.rowToQueueItem(row);
+    const updated = { ...existing, ...updates };
+
+    this.run(`
+      UPDATE feedback_queue SET
+        status = $status,
+        attempts = $attempts,
+        last_attempt_at = $lastAttemptAt,
+        next_retry_at = $nextRetryAt,
+        last_error = $lastError,
+        current_delay = $currentDelay,
+        processed_at = $processedAt
+      WHERE id = $id
+    `, {
+      $id: updated.id,
+      $status: updated.status,
+      $attempts: updated.attempts,
+      $lastAttemptAt: updated.lastAttemptAt ?? null,
+      $nextRetryAt: updated.nextRetryAt ?? null,
+      $lastError: updated.lastError ?? null,
+      $currentDelay: updated.currentDelay,
+      $processedAt: updated.processedAt ?? null,
+    });
+
+    return updated;
+  }
+
+  async removeFromQueue(id: string): Promise<boolean> {
+    const before = this.get<{ count: number }>('SELECT COUNT(*) as count FROM feedback_queue WHERE id = ?', [id]);
+    this.run('DELETE FROM feedback_queue WHERE id = ?', { $id: id });
+    const after = this.get<{ count: number }>('SELECT COUNT(*) as count FROM feedback_queue WHERE id = ?', [id]);
+    return (before?.count ?? 0) > (after?.count ?? 0);
+  }
+
+  async getQueueSize(): Promise<number> {
+    const result = this.get<{ count: number }>(
+      "SELECT COUNT(*) as count FROM feedback_queue WHERE status IN ('pending', 'retrying')"
+    );
+    return result?.count ?? 0;
+  }
+
+  async getDeadLetterItems(options?: PaginationOptions): Promise<PaginatedResult<FeedbackQueueItem>> {
+    const limit = Math.min(options?.limit ?? 20, 100);
+    const params: SqlParams = [];
+
+    let query = "SELECT * FROM feedback_queue WHERE status = 'dead_letter'";
+
+    if (options?.cursor) {
+      query += ' AND id > ?';
+      params.push(options.cursor);
+    }
+
+    query += ' ORDER BY created_at DESC LIMIT ?';
+    params.push(limit + 1);
+
+    const rows = this.all<Record<string, unknown>>(query, params);
+    const countResult = this.get<{ count: number }>(
+      "SELECT COUNT(*) as count FROM feedback_queue WHERE status = 'dead_letter'"
+    );
+
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit).map(row => this.rowToQueueItem(row));
+
+    return {
+      items,
+      pagination: {
+        total: countResult?.count ?? 0,
+        limit,
+        hasMore,
+        cursor: options?.cursor,
+        nextCursor: hasMore && items.length > 0 ? items[items.length - 1]?.id : undefined,
+      },
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Audit Logs
+  // -------------------------------------------------------------------------
+
+  async createAuditLog(log: AuditLog): Promise<AuditLog> {
+    this.run(`
+      INSERT INTO audit_logs (
+        id, timestamp, event_type, actor, resource, action, result,
+        details, changes, error_code, error_message
+      ) VALUES (
+        $id, $timestamp, $eventType, $actor, $resource, $action, $result,
+        $details, $changes, $errorCode, $errorMessage
+      )
+    `, {
+      $id: log.id,
+      $timestamp: log.timestamp,
+      $eventType: log.eventType,
+      $actor: JSON.stringify(log.actor),
+      $resource: JSON.stringify(log.resource),
+      $action: log.action,
+      $result: log.result,
+      $details: log.details ? JSON.stringify(log.details) : null,
+      $changes: log.changes ? JSON.stringify(log.changes) : null,
+      $errorCode: log.errorCode ?? null,
+      $errorMessage: log.errorMessage ?? null,
+    });
+
+    return log;
+  }
+
+  async getAuditLogs(options?: AuditQueryOptions): Promise<PaginatedResult<AuditLog>> {
+    const limit = Math.min(options?.limit ?? 50, 100);
+    const conditions: string[] = ['1=1'];
+    const params: SqlParams = [];
+
+    if (options?.eventType) {
+      conditions.push('event_type = ?');
+      params.push(options.eventType);
+    }
+
+    if (options?.actor) {
+      conditions.push("json_extract(actor, '$.id') = ?");
+      params.push(options.actor);
+    }
+
+    if (options?.resourceType) {
+      conditions.push("json_extract(resource, '$.type') = ?");
+      params.push(options.resourceType);
+    }
+
+    if (options?.resourceName) {
+      conditions.push("json_extract(resource, '$.name') = ?");
+      params.push(options.resourceName);
+    }
+
+    if (options?.from) {
+      conditions.push('timestamp >= ?');
+      params.push(options.from);
+    }
+
+    if (options?.to) {
+      conditions.push('timestamp <= ?');
+      params.push(options.to);
+    }
+
+    if (options?.cursor) {
+      conditions.push('id > ?');
+      params.push(options.cursor);
+    }
+
+    const whereClause = conditions.join(' AND ');
+    const countQuery = `SELECT COUNT(*) as count FROM audit_logs WHERE ${whereClause}`;
+    const query = `SELECT * FROM audit_logs WHERE ${whereClause} ORDER BY timestamp DESC LIMIT ?`;
+
+    const countParams = [...params];
+    params.push(limit + 1);
+
+    const rows = this.all<Record<string, unknown>>(query, params);
+    const countResult = this.get<{ count: number }>(countQuery, countParams);
+
+    const hasMore = rows.length > limit;
+    const items = rows.slice(0, limit).map(row => this.rowToAuditLog(row));
+
+    return {
+      items,
+      pagination: {
+        total: countResult?.count ?? 0,
+        limit,
+        hasMore,
+        cursor: options?.cursor,
+        nextCursor: hasMore && items.length > 0 ? items[items.length - 1]?.id : undefined,
+      },
+    };
+  }
+
+  async getResourceAuditLogs(
+    resourceType: string,
+    resourceId: string,
+    options?: PaginationOptions
+  ): Promise<PaginatedResult<AuditLog>> {
+    return this.getAuditLogs({
+      ...options,
+      resourceType,
+      resourceName: resourceId,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Cache Metadata
+  // -------------------------------------------------------------------------
+
+  async setCacheMetadata(metadata: CacheMetadata): Promise<CacheMetadata> {
+    this.run(`
+      INSERT OR REPLACE INTO cache_metadata (
+        id, skill_name, version, cached_at, expires_at, size,
+        hit_count, last_hit_at, source, integrity_hash
+      ) VALUES (
+        $id, $skillName, $version, $cachedAt, $expiresAt, $size,
+        $hitCount, $lastHitAt, $source, $integrityHash
+      )
+    `, {
+      $id: metadata.id,
+      $skillName: metadata.skillName,
+      $version: metadata.version,
+      $cachedAt: metadata.cachedAt,
+      $expiresAt: metadata.expiresAt ?? null,
+      $size: metadata.size ?? null,
+      $hitCount: metadata.hitCount,
+      $lastHitAt: metadata.lastHitAt ?? null,
+      $source: metadata.source ?? null,
+      $integrityHash: metadata.integrityHash ?? null,
+    });
+
+    return metadata;
+  }
+
+  async getCacheMetadata(skillName: string, version: string): Promise<CacheMetadata | null> {
+    const row = this.get<Record<string, unknown>>(
+      'SELECT * FROM cache_metadata WHERE skill_name = ? AND version = ?',
+      [skillName, version]
+    );
+    return row ? this.rowToCacheMetadata(row) : null;
+  }
+
+  async getAllCacheMetadata(): Promise<CacheMetadata[]> {
+    const rows = this.all<Record<string, unknown>>('SELECT * FROM cache_metadata ORDER BY cached_at DESC');
+    return rows.map(row => this.rowToCacheMetadata(row));
+  }
+
+  async deleteCacheMetadata(skillName: string, version?: string): Promise<boolean> {
+    const before = version
+      ? this.get<{ count: number }>('SELECT COUNT(*) as count FROM cache_metadata WHERE skill_name = ? AND version = ?', [skillName, version])
+      : this.get<{ count: number }>('SELECT COUNT(*) as count FROM cache_metadata WHERE skill_name = ?', [skillName]);
+
+    if (version) {
+      this.run('DELETE FROM cache_metadata WHERE skill_name = ? AND version = ?', { $skillName: skillName, $version: version });
+    } else {
+      this.run('DELETE FROM cache_metadata WHERE skill_name = ?', { $skillName: skillName });
+    }
+
+    const after = version
+      ? this.get<{ count: number }>('SELECT COUNT(*) as count FROM cache_metadata WHERE skill_name = ? AND version = ?', [skillName, version])
+      : this.get<{ count: number }>('SELECT COUNT(*) as count FROM cache_metadata WHERE skill_name = ?', [skillName]);
+
+    return (before?.count ?? 0) > (after?.count ?? 0);
+  }
+
+  async incrementCacheHit(skillName: string, version: string): Promise<void> {
+    this.run(`
+      UPDATE cache_metadata SET
+        hit_count = hit_count + 1,
+        last_hit_at = datetime('now')
+      WHERE skill_name = ? AND version = ?
+    `, { $skillName: skillName, $version: version });
+  }
+
+  async getExpiredCacheEntries(): Promise<CacheMetadata[]> {
+    const rows = this.all<Record<string, unknown>>(
+      "SELECT * FROM cache_metadata WHERE expires_at IS NOT NULL AND expires_at <= datetime('now')"
+    );
+    return rows.map(row => this.rowToCacheMetadata(row));
+  }
+
+  // -------------------------------------------------------------------------
+  // Use Records
+  // -------------------------------------------------------------------------
+
+  async createUseRecord(record: UseRecord): Promise<UseRecord> {
+    this.run(`
+      INSERT INTO use_records (
+        id, skill_id, version_id, user_id, source, cache_hit, client_version,
+        platform, arch, ip, user_agent, country, region, created_at
+      ) VALUES (
+        $id, $skillId, $versionId, $userId, $source, $cacheHit, $clientVersion,
+        $platform, $arch, $ip, $userAgent, $country, $region, $createdAt
+      )
+    `, {
+      $id: record.id,
+      $skillId: record.skillId,
+      $versionId: record.versionId ?? null,
+      $userId: record.userId ?? null,
+      $source: record.source,
+      $cacheHit: record.cacheHit ? 1 : 0,
+      $clientVersion: record.clientVersion ?? null,
+      $platform: record.platform ?? null,
+      $arch: record.arch ?? null,
+      $ip: record.ip,
+      $userAgent: record.userAgent ?? null,
+      $country: record.country ?? null,
+      $region: record.region ?? null,
+      $createdAt: record.createdAt,
+    });
+
+    return record;
+  }
+
+  async getSkillUseStats(skillId: string, days: number): Promise<{
+    total: number;
+    bySource: Record<string, number>;
+    cacheHitRate: number;
+    daily: { date: string; count: number }[];
+  }> {
+    const fromDate = new Date();
+    fromDate.setDate(fromDate.getDate() - days);
+    const fromDateStr = fromDate.toISOString();
+
+    // Total uses
+    const totalResult = this.get<{ count: number }>(`
+      SELECT COUNT(*) as count FROM use_records 
+      WHERE skill_id = ? AND created_at >= ?
+    `, [skillId, fromDateStr]);
+
+    // By source
+    const sourceRows = this.all<{ source: string; count: number }>(`
+      SELECT source, COUNT(*) as count FROM use_records
+      WHERE skill_id = ? AND created_at >= ?
+      GROUP BY source
+    `, [skillId, fromDateStr]);
+
+    const bySource: Record<string, number> = {};
+    sourceRows.forEach(row => {
+      bySource[row.source] = row.count;
+    });
+
+    // Cache hit rate
+    const cacheHitResult = this.get<{ hits: number; total: number }>(`
+      SELECT 
+        SUM(cache_hit) as hits,
+        COUNT(*) as total
+      FROM use_records
+      WHERE skill_id = ? AND created_at >= ?
+    `, [skillId, fromDateStr]);
+
+    const cacheHitRate = (cacheHitResult?.total ?? 0) > 0
+      ? (cacheHitResult?.hits ?? 0) / (cacheHitResult?.total ?? 1)
+      : 0;
+
+    // Daily breakdown
+    const dailyRows = this.all<{ date: string; count: number }>(`
+      SELECT 
+        date(created_at) as date,
+        COUNT(*) as count
+      FROM use_records
+      WHERE skill_id = ? AND created_at >= ?
+      GROUP BY date(created_at)
+      ORDER BY date ASC
+    `, [skillId, fromDateStr]);
+
+    return {
+      total: totalResult?.count ?? 0,
+      bySource,
+      cacheHitRate,
+      daily: dailyRows,
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Row Converters
+  // -------------------------------------------------------------------------
+
+  private rowToSkill(row: Record<string, unknown>): Skill {
+    return {
+      id: row['id'] as string,
+      name: row['name'] as string,
+      scope: row['scope'] as string | undefined,
+      fullName: row['full_name'] as string,
+      ownerId: row['owner_id'] as string | undefined,
+      ownerType: (row['owner_type'] as 'user' | 'organization') ?? 'user',
+      displayName: row['display_name'] as string | undefined,
+      description: row['description'] as string,
+      category: row['category'] as string | undefined,
+      keywords: JSON.parse(row['keywords'] as string || '[]'),
+      license: row['license'] as string | undefined,
+      repository: row['repository'] as string | undefined,
+      homepage: row['homepage'] as string | undefined,
+      derivedFrom: row['derived_from'] ? JSON.parse(row['derived_from'] as string) : undefined,
+      latestVersion: row['latest_version'] as string,
+      latestVersionId: row['latest_version_id'] as string | undefined,
+      visibility: (row['visibility'] as 'public' | 'private' | 'unlisted') ?? 'public',
+      status: (row['status'] as 'active' | 'deprecated' | 'deleted') ?? 'active',
+      deprecatedMessage: row['deprecated_message'] as string | undefined,
+      securityScore: row['security_score'] as number | undefined,
+      securityLevel: row['security_level'] as 'safe' | 'low' | 'medium' | 'high' | undefined,
+      lastScanAt: row['last_scan_at'] as string | undefined,
+      stats: JSON.parse(row['stats'] as string || '{}'),
+      rating: JSON.parse(row['rating'] as string || '{"average":0,"count":0}'),
+      createdAt: row['created_at'] as string,
+      updatedAt: row['updated_at'] as string,
+      publishedAt: row['published_at'] as string | undefined,
+    };
+  }
+
+  private rowToVersion(row: Record<string, unknown>): Version {
+    return {
+      id: row['id'] as string,
+      skillId: row['skill_id'] as string,
+      version: row['version'] as string,
+      tag: row['tag'] as string | undefined,
+      content: JSON.parse(row['content'] as string),
+      packageUrl: row['package_url'] as string,
+      packageSize: row['package_size'] as number,
+      packageHash: row['package_hash'] as string,
+      changelog: row['changelog'] as string | undefined,
+      scanRecordId: row['scan_record_id'] as string | undefined,
+      securityScore: row['security_score'] as number | undefined,
+      securityLevel: row['security_level'] as 'safe' | 'low' | 'medium' | 'high' | undefined,
+      status: (row['status'] as 'published' | 'deprecated' | 'yanked') ?? 'published',
+      deprecatedMessage: row['deprecated_message'] as string | undefined,
+      publishedBy: row['published_by'] as string | undefined,
+      uses: row['uses'] as number,
+      createdAt: row['created_at'] as string,
+      publishedAt: row['published_at'] as string,
+      deprecatedAt: row['deprecated_at'] as string | undefined,
+    };
+  }
+
+  private rowToScanRecord(row: Record<string, unknown>): ScanRecord {
+    return {
+      id: row['id'] as string,
+      skillId: row['skill_id'] as string | undefined,
+      versionId: row['version_id'] as string | undefined,
+      userId: row['user_id'] as string | undefined,
+      inputType: row['input_type'] as 'publish' | 'manual' | 'scheduled' | 'api' | 'cache',
+      contentHash: row['content_hash'] as string,
+      contentSize: row['content_size'] as number,
+      score: row['score'] as number | undefined,
+      level: row['level'] as 'safe' | 'low' | 'medium' | 'high' | undefined,
+      issueCount: JSON.parse(row['issue_count'] as string || '{"high":0,"medium":0,"low":0}'),
+      scannerVersion: row['scanner_version'] as string | undefined,
+      rulesVersion: row['rules_version'] as string | undefined,
+      rulesApplied: row['rules_applied'] as number | undefined,
+      duration: row['duration'] as number | undefined,
+      status: (row['status'] as 'pending' | 'scanning' | 'completed' | 'failed') ?? 'pending',
+      errorMessage: row['error_message'] as string | undefined,
+      createdAt: row['created_at'] as string,
+      completedAt: row['completed_at'] as string | undefined,
+    };
+  }
+
+  private rowToScanIssue(row: Record<string, unknown>): ScanIssue {
+    return {
+      id: row['id'] as string,
+      scanRecordId: row['scan_record_id'] as string,
+      ruleId: row['rule_id'] as string,
+      ruleName: row['rule_name'] as string,
+      ruleCategory: row['rule_category'] as 'command' | 'secret' | 'injection' | 'resource' | 'privacy' | 'network',
+      severity: row['severity'] as 'high' | 'medium' | 'low',
+      file: row['file'] as string | undefined,
+      line: row['line'] as number | undefined,
+      column: row['column_num'] as number | undefined,
+      endLine: row['end_line'] as number | undefined,
+      endColumn: row['end_column'] as number | undefined,
+      content: row['content'] as string,
+      context: row['context'] as string | undefined,
+      message: row['message'] as string,
+      suggestion: row['suggestion'] as string | undefined,
+      acknowledged: !!row['acknowledged'],
+      acknowledgedAt: row['acknowledged_at'] as string | undefined,
+      acknowledgedBy: row['acknowledged_by'] as string | undefined,
+      acknowledgedReason: row['acknowledged_reason'] as string | undefined,
+      createdAt: row['created_at'] as string,
+    };
+  }
+
+  private rowToFeedback(row: Record<string, unknown>): Feedback {
+    return {
+      id: row['id'] as string,
+      skillId: row['skill_id'] as string,
+      skillVersion: row['skill_version'] as string,
+      feedbackType: row['feedback_type'] as 'success' | 'failure' | 'suggestion' | 'bug',
+      rating: row['rating'] as number,
+      comment: row['comment'] as string | undefined,
+      context: JSON.parse(row['context'] as string || '{}'),
+      status: (row['status'] as 'pending' | 'reviewed' | 'accepted' | 'rejected') ?? 'pending',
+      reviewerNotes: row['reviewer_notes'] as string | undefined,
+      reviewedAt: row['reviewed_at'] as string | undefined,
+      reviewedBy: row['reviewed_by'] as string | undefined,
+      sourceIpHash: row['source_ip_hash'] as string | undefined,
+      createdAt: row['created_at'] as string,
+    };
+  }
+
+  private rowToQueueItem(row: Record<string, unknown>): FeedbackQueueItem {
+    return {
+      id: row['id'] as string,
+      skillName: row['skill_name'] as string,
+      skillVersion: row['skill_version'] as string,
+      feedback: JSON.parse(row['feedback'] as string),
+      status: (row['status'] as 'pending' | 'retrying' | 'failed' | 'dead_letter') ?? 'pending',
+      attempts: row['attempts'] as number,
+      maxAttempts: row['max_attempts'] as number,
+      lastAttemptAt: row['last_attempt_at'] as string | undefined,
+      nextRetryAt: row['next_retry_at'] as string | undefined,
+      lastError: row['last_error'] as string | undefined,
+      baseDelay: row['base_delay'] as number,
+      currentDelay: row['current_delay'] as number,
+      maxDelay: row['max_delay'] as number,
+      createdAt: row['created_at'] as string,
+      processedAt: row['processed_at'] as string | undefined,
+    };
+  }
+
+  private rowToAuditLog(row: Record<string, unknown>): AuditLog {
+    return {
+      id: row['id'] as string,
+      timestamp: row['timestamp'] as string,
+      eventType: row['event_type'] as AuditLog['eventType'],
+      actor: JSON.parse(row['actor'] as string),
+      resource: JSON.parse(row['resource'] as string),
+      action: row['action'] as string,
+      result: row['result'] as 'success' | 'failure',
+      details: row['details'] ? JSON.parse(row['details'] as string) : undefined,
+      changes: row['changes'] ? JSON.parse(row['changes'] as string) : undefined,
+      errorCode: row['error_code'] as string | undefined,
+      errorMessage: row['error_message'] as string | undefined,
+    };
+  }
+
+  private rowToCacheMetadata(row: Record<string, unknown>): CacheMetadata {
+    return {
+      id: row['id'] as string,
+      skillName: row['skill_name'] as string,
+      version: row['version'] as string,
+      cachedAt: row['cached_at'] as string,
+      expiresAt: row['expires_at'] as string | undefined,
+      size: row['size'] as number | undefined,
+      hitCount: row['hit_count'] as number,
+      lastHitAt: row['last_hit_at'] as string | undefined,
+      source: row['source'] as 'remote' | 'local' | undefined,
+      integrityHash: row['integrity_hash'] as string | undefined,
+    };
+  }
+}