@jagilber-org/index-server 1.19.1

package/dist/services/storage/sqliteSchema.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * SQLite schema DDL for instruction storage.
+ *
+ * Uses Node.js built-in node:sqlite (DatabaseSync). No third-party packages.
+ * WAL mode enabled for concurrent read performance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRAGMAS = exports.FTS5_DDL = exports.INSTRUCTIONS_DDL = exports.SCHEMA_VERSION = void 0;
+exports.SCHEMA_VERSION = '1';
+exports.INSTRUCTIONS_DDL = `
+CREATE TABLE IF NOT EXISTS instructions (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  body TEXT NOT NULL,
+  rationale TEXT,
+  priority INTEGER NOT NULL DEFAULT 50,
+  audience TEXT NOT NULL DEFAULT 'all',
+  requirement TEXT NOT NULL DEFAULT 'recommended',
+  categories TEXT NOT NULL DEFAULT '[]',
+  content_type TEXT NOT NULL DEFAULT 'instruction',
+  primary_category TEXT,
+  source_hash TEXT NOT NULL DEFAULT '',
+  schema_version TEXT NOT NULL DEFAULT '4',
+  deprecated_by TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  version TEXT DEFAULT '1.0.0',
+  status TEXT DEFAULT 'approved',
+  owner TEXT,
+  priority_tier TEXT,
+  classification TEXT DEFAULT 'public',
+  last_reviewed_at TEXT,
+  next_review_due TEXT,
+  review_interval_days INTEGER,
+  change_log TEXT DEFAULT '[]',
+  supersedes TEXT,
+  archived_at TEXT,
+  workspace_id TEXT,
+  user_id TEXT,
+  team_ids TEXT DEFAULT '[]',
+  semantic_summary TEXT,
+  created_by_agent TEXT,
+  source_workspace TEXT,
+  risk_score REAL,
+  usage_count INTEGER DEFAULT 0,
+  first_seen_ts TEXT,
+  last_used_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_instructions_content_type ON instructions(content_type);
+CREATE INDEX IF NOT EXISTS idx_instructions_status ON instructions(status);
+CREATE INDEX IF NOT EXISTS idx_instructions_priority ON instructions(priority);
+CREATE INDEX IF NOT EXISTS idx_instructions_priority_tier ON instructions(priority_tier);
+CREATE INDEX IF NOT EXISTS idx_instructions_audience ON instructions(audience);
+
+CREATE TABLE IF NOT EXISTS usage (
+  instruction_id TEXT PRIMARY KEY,
+  usage_count INTEGER DEFAULT 0,
+  first_seen_ts TEXT,
+  last_used_at TEXT,
+  last_action TEXT,
+  last_signal TEXT,
+  last_comment TEXT
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+  id TEXT PRIMARY KEY,
+  channel TEXT NOT NULL,
+  sender TEXT NOT NULL,
+  recipients TEXT NOT NULL DEFAULT '[]',
+  body TEXT NOT NULL,
+  priority TEXT DEFAULT 'normal',
+  tags TEXT DEFAULT '[]',
+  parent_id TEXT,
+  persistent INTEGER DEFAULT 0,
+  ttl_seconds INTEGER,
+  requires_ack INTEGER DEFAULT 0,
+  ack_by_seconds INTEGER,
+  read_by TEXT DEFAULT '[]',
+  payload TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_channel ON messages(channel);
+CREATE INDEX IF NOT EXISTS idx_messages_sender ON messages(sender);
+CREATE INDEX IF NOT EXISTS idx_messages_parent_id ON messages(parent_id);
+CREATE INDEX IF NOT EXISTS idx_messages_created_at ON messages(created_at);
+
+CREATE TABLE IF NOT EXISTS metadata (
+  key TEXT PRIMARY KEY,
+  value TEXT
+);
+`;
+/** FTS5 virtual table for full-text search. Created separately since it needs content sync. */
+exports.FTS5_DDL = `
+CREATE VIRTUAL TABLE IF NOT EXISTS instructions_fts USING fts5(
+  id, title, body, categories,
+  content='instructions',
+  content_rowid='rowid'
+);
+
+-- Triggers to keep FTS5 in sync with instructions table
+CREATE TRIGGER IF NOT EXISTS instructions_ai AFTER INSERT ON instructions BEGIN
+  INSERT INTO instructions_fts(rowid, id, title, body, categories) VALUES (new.rowid, new.id, new.title, new.body, new.categories);
+END;
+CREATE TRIGGER IF NOT EXISTS instructions_ad AFTER DELETE ON instructions BEGIN
+  INSERT INTO instructions_fts(instructions_fts, rowid, id, title, body, categories) VALUES('delete', old.rowid, old.id, old.title, old.body, old.categories);
+END;
+CREATE TRIGGER IF NOT EXISTS instructions_au AFTER UPDATE ON instructions BEGIN
+  INSERT INTO instructions_fts(instructions_fts, rowid, id, title, body, categories) VALUES('delete', old.rowid, old.id, old.title, old.body, old.categories);
+  INSERT INTO instructions_fts(rowid, id, title, body, categories) VALUES (new.rowid, new.id, new.title, new.body, new.categories);
+END;
+`;
+/** Enable WAL mode and recommended pragmas. */
+exports.PRAGMAS = `
+PRAGMA journal_mode=WAL;
+PRAGMA busy_timeout=5000;
+PRAGMA synchronous=NORMAL;
+PRAGMA foreign_keys=ON;
+`;

package/dist/services/storage/sqliteStore.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SqliteStore — SQLite storage backend using Node.js built-in node:sqlite.
+ *
+ * ⚠️  EXPERIMENTAL — LIMITED TESTING PERFORMED.
+ * This backend is behind the INDEX_SERVER_STORAGE_BACKEND=sqlite feature flag
+ * and should NOT be used in production without thorough validation.
+ * Data loss, migration issues, or compatibility problems may occur.
+ *
+ * Uses DatabaseSync (synchronous API) — zero third-party dependencies.
+ * Requires Node.js >= 22.5.0.
+ *
+ * Implements IInstructionStore for the storage abstraction layer.
+ */
+import { InstructionEntry } from '../../models/instruction.js';
+import type { IInstructionStore, ListOptions, QueryOptions, ScopedListOptions, SearchOptions, SearchResult, LoadResult } from './types.js';
+export declare class SqliteStore implements IInstructionStore {
+    private db;
+    private loaded;
+    private cache;
+    constructor(dbPath: string);
+    private initSchema;
+    load(): LoadResult;
+    close(): void;
+    get(id: string): InstructionEntry | null;
+    write(entry: InstructionEntry): void;
+    remove(id: string): void;
+    list(opts?: ListOptions): InstructionEntry[];
+    query(opts: QueryOptions): InstructionEntry[];
+    listScoped(opts: ScopedListOptions): InstructionEntry[];
+    search(opts: SearchOptions): SearchResult[];
+    categories(): Map<string, number>;
+    /**
+     * Full-text search using FTS5 with BM25 ranking.
+     * More efficient than in-memory scan for large instruction sets.
+     * Falls back to in-memory search if FTS5 is unavailable.
+     */
+    searchFts(opts: SearchOptions): SearchResult[];
+    computeHash(): string;
+    count(): number;
+    private ensureLoaded;
+}

package/dist/services/storage/sqliteStore.js

@@ -0,0 +1,339 @@
+"use strict";
+/**
+ * SqliteStore — SQLite storage backend using Node.js built-in node:sqlite.
+ *
+ * ⚠️  EXPERIMENTAL — LIMITED TESTING PERFORMED.
+ * This backend is behind the INDEX_SERVER_STORAGE_BACKEND=sqlite feature flag
+ * and should NOT be used in production without thorough validation.
+ * Data loss, migration issues, or compatibility problems may occur.
+ *
+ * Uses DatabaseSync (synchronous API) — zero third-party dependencies.
+ * Requires Node.js >= 22.5.0.
+ *
+ * Implements IInstructionStore for the storage abstraction layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteStore = void 0;
+const node_sqlite_1 = require("node:sqlite");
+const hashUtils_js_1 = require("./hashUtils.js");
+const sqliteSchema_js_1 = require("./sqliteSchema.js");
+// ── Column Mapping ───────────────────────────────────────────────────────────
+/** Map DB row (snake_case) to InstructionEntry (camelCase). */
+function rowToEntry(row) {
+    return {
+        id: row.id,
+        title: row.title,
+        body: row.body,
+        rationale: row.rationale,
+        priority: row.priority,
+        audience: row.audience,
+        requirement: row.requirement,
+        categories: safeJsonParse(row.categories, []),
+        contentType: row.content_type ?? 'instruction',
+        primaryCategory: row.primary_category,
+        sourceHash: row.source_hash,
+        schemaVersion: row.schema_version,
+        deprecatedBy: row.deprecated_by,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        version: row.version,
+        status: row.status,
+        owner: row.owner,
+        priorityTier: row.priority_tier,
+        classification: row.classification,
+        lastReviewedAt: row.last_reviewed_at,
+        nextReviewDue: row.next_review_due,
+        reviewIntervalDays: row.review_interval_days,
+        changeLog: safeJsonParse(row.change_log, undefined),
+        supersedes: row.supersedes,
+        archivedAt: row.archived_at,
+        workspaceId: row.workspace_id,
+        userId: row.user_id,
+        teamIds: safeJsonParse(row.team_ids, undefined),
+        semanticSummary: row.semantic_summary,
+        createdByAgent: row.created_by_agent,
+        sourceWorkspace: row.source_workspace,
+        riskScore: row.risk_score,
+        usageCount: row.usage_count,
+        firstSeenTs: row.first_seen_ts,
+        lastUsedAt: row.last_used_at,
+    };
+}
+/** Safely parse a JSON string, returning fallback on failure. */
+function safeJsonParse(raw, fallback) {
+    if (raw == null)
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Strip undefined values from entry to avoid SQLite binding issues. */
+function val(v) {
+    return v === undefined ? null : v;
+}
+// ── SqliteStore ──────────────────────────────────────────────────────────────
+class SqliteStore {
+    db;
+    loaded = false;
+    cache = new Map();
+    constructor(dbPath) {
+        this.db = new node_sqlite_1.DatabaseSync(dbPath);
+        this.initSchema();
+    }
+    initSchema() {
+        this.db.exec(sqliteSchema_js_1.PRAGMAS);
+        this.db.exec(sqliteSchema_js_1.INSTRUCTIONS_DDL);
+        // FTS5 for full-text search (with content sync triggers)
+        try {
+            this.db.exec(sqliteSchema_js_1.FTS5_DDL);
+        }
+        catch { /* FTS5 may already exist */ }
+        // Stamp schema version if not present
+        const meta = this.db.prepare('SELECT value FROM metadata WHERE key = ?').get('schema_version');
+        if (!meta) {
+            this.db.prepare('INSERT INTO metadata (key, value) VALUES (?, ?)').run('schema_version', sqliteSchema_js_1.SCHEMA_VERSION);
+        }
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────
+    load() {
+        const rows = this.db.prepare('SELECT * FROM instructions').all();
+        const entries = [];
+        const errors = [];
+        for (const row of rows) {
+            try {
+                entries.push(rowToEntry(row));
+            }
+            catch (err) {
+                errors.push({
+                    file: row.id ?? 'unknown',
+                    error: err instanceof Error ? err.message : 'Row parse error',
+                });
+            }
+        }
+        this.cache.clear();
+        for (const e of entries) {
+            this.cache.set(e.id, e);
+        }
+        this.loaded = true;
+        return {
+            entries,
+            hash: (0, hashUtils_js_1.computeGovernanceHashFromEntries)(entries),
+            errors,
+            debug: { scanned: rows.length, accepted: entries.length, skipped: errors.length },
+            summary: {
+                scanned: rows.length,
+                accepted: entries.length,
+                skipped: errors.length,
+                reasons: errors.length > 0 ? { 'row-parse-error': errors.length } : {},
+            },
+        };
+    }
+    close() {
+        this.cache.clear();
+        this.loaded = false;
+        this.db.close();
+    }
+    // ── CRUD ───────────────────────────────────────────────────────────
+    get(id) {
+        this.ensureLoaded();
+        return this.cache.get(id) ?? null;
+    }
+    write(entry) {
+        const sql = `INSERT OR REPLACE INTO instructions (
+      id, title, body, rationale, priority, audience, requirement,
+      categories, content_type, primary_category, source_hash,
+      schema_version, deprecated_by, created_at, updated_at,
+      version, status, owner, priority_tier, classification,
+      last_reviewed_at, next_review_due, review_interval_days,
+      change_log, supersedes, archived_at, workspace_id, user_id,
+      team_ids, semantic_summary, created_by_agent, source_workspace,
+      risk_score, usage_count, first_seen_ts, last_used_at
+    ) VALUES (
+      ?, ?, ?, ?, ?, ?, ?,
+      ?, ?, ?, ?,
+      ?, ?, ?, ?,
+      ?, ?, ?, ?, ?,
+      ?, ?, ?,
+      ?, ?, ?, ?, ?,
+      ?, ?, ?, ?,
+      ?, ?, ?, ?
+    )`;
+        this.db.prepare(sql).run(entry.id, entry.title, entry.body, val(entry.rationale), val(entry.priority) ?? 0, val(entry.audience) ?? 'all', val(entry.requirement) ?? 'may', JSON.stringify(entry.categories ?? []), val(entry.contentType) ?? 'instruction', val(entry.primaryCategory), entry.sourceHash ?? '', entry.schemaVersion ?? '4', val(entry.deprecatedBy), val(entry.createdAt) ?? new Date().toISOString(), val(entry.updatedAt) ?? new Date().toISOString(), val(entry.version), val(entry.status), val(entry.owner), val(entry.priorityTier), val(entry.classification), val(entry.lastReviewedAt), val(entry.nextReviewDue), val(entry.reviewIntervalDays), JSON.stringify(entry.changeLog ?? []), val(entry.supersedes), val(entry.archivedAt), val(entry.workspaceId), val(entry.userId), JSON.stringify(entry.teamIds ?? []), val(entry.semanticSummary), val(entry.createdByAgent), val(entry.sourceWorkspace), val(entry.riskScore), val(entry.usageCount) ?? 0, val(entry.firstSeenTs), val(entry.lastUsedAt));
+        // Update in-memory cache
+        this.cache.set(entry.id, entry);
+        this.loaded = true;
+    }
+    remove(id) {
+        this.db.prepare('DELETE FROM instructions WHERE id = ?').run(id);
+        this.cache.delete(id);
+    }
+    // ── Queries ────────────────────────────────────────────────────────
+    list(opts) {
+        this.ensureLoaded();
+        let result = Array.from(this.cache.values());
+        if (opts?.category) {
+            result = result.filter(e => e.categories?.includes(opts.category));
+        }
+        if (opts?.contentType) {
+            result = result.filter(e => e.contentType === opts.contentType);
+        }
+        return result;
+    }
+    query(opts) {
+        this.ensureLoaded();
+        let result = Array.from(this.cache.values());
+        if (opts.text) {
+            const lower = opts.text.toLowerCase();
+            result = result.filter(e => e.title.toLowerCase().includes(lower) ||
+                e.body.toLowerCase().includes(lower) ||
+                (e.semanticSummary && e.semanticSummary.toLowerCase().includes(lower)));
+        }
+        if (opts.categoriesAny?.length) {
+            const set = new Set(opts.categoriesAny);
+            result = result.filter(e => e.categories?.some(c => set.has(c)));
+        }
+        if (opts.categoriesAll?.length) {
+            result = result.filter(e => opts.categoriesAll.every(c => e.categories?.includes(c)));
+        }
+        if (opts.excludeCategories?.length) {
+            const excl = new Set(opts.excludeCategories);
+            result = result.filter(e => !e.categories?.some(c => excl.has(c)));
+        }
+        if (opts.contentType) {
+            result = result.filter(e => e.contentType === opts.contentType);
+        }
+        if (opts.priorityMin !== undefined) {
+            result = result.filter(e => e.priority >= opts.priorityMin);
+        }
+        if (opts.priorityMax !== undefined) {
+            result = result.filter(e => e.priority <= opts.priorityMax);
+        }
+        if (opts.priorityTiers?.length) {
+            const tiers = new Set(opts.priorityTiers);
+            result = result.filter(e => e.priorityTier && tiers.has(e.priorityTier));
+        }
+        if (opts.requirements?.length) {
+            const reqs = new Set(opts.requirements);
+            result = result.filter(e => reqs.has(e.requirement));
+        }
+        if (opts.offset) {
+            result = result.slice(opts.offset);
+        }
+        if (opts.limit) {
+            result = result.slice(0, opts.limit);
+        }
+        return result;
+    }
+    listScoped(opts) {
+        this.ensureLoaded();
+        let result = Array.from(this.cache.values());
+        if (opts.userId) {
+            result = result.filter(e => e.userId === opts.userId || e.audience === 'all');
+        }
+        if (opts.workspaceId) {
+            result = result.filter(e => e.workspaceId === opts.workspaceId || e.audience === 'all');
+        }
+        if (opts.teamIds?.length) {
+            const teams = new Set(opts.teamIds);
+            result = result.filter(e => e.audience === 'all' ||
+                e.teamIds?.some(t => teams.has(t)));
+        }
+        return result;
+    }
+    search(opts) {
+        this.ensureLoaded();
+        const results = [];
+        for (const entry of this.cache.values()) {
+            let score = 0;
+            const titleLower = entry.title.toLowerCase();
+            const bodyLower = entry.body.toLowerCase();
+            const catStr = (entry.categories ?? []).join(' ').toLowerCase();
+            for (const kw of opts.keywords) {
+                const kwLower = opts.caseSensitive ? kw : kw.toLowerCase();
+                const title = opts.caseSensitive ? entry.title : titleLower;
+                const body = opts.caseSensitive ? entry.body : bodyLower;
+                if (title.includes(kwLower))
+                    score += 3;
+                if (body.includes(kwLower))
+                    score += 1;
+                if (opts.includeCategories && catStr.includes(kwLower))
+                    score += 2;
+            }
+            if (score > 0) {
+                results.push({ id: entry.id, score });
+            }
+        }
+        results.sort((a, b) => b.score - a.score);
+        if (opts.limit) {
+            return results.slice(0, opts.limit);
+        }
+        return results;
+    }
+    categories() {
+        this.ensureLoaded();
+        const counts = new Map();
+        for (const entry of this.cache.values()) {
+            for (const cat of entry.categories ?? []) {
+                counts.set(cat, (counts.get(cat) ?? 0) + 1);
+            }
+        }
+        return counts;
+    }
+    // ── FTS5 Search ────────────────────────────────────────────────────
+    /**
+     * Full-text search using FTS5 with BM25 ranking.
+     * More efficient than in-memory scan for large instruction sets.
+     * Falls back to in-memory search if FTS5 is unavailable.
+     */
+    searchFts(opts) {
+        this.ensureLoaded();
+        try {
+            // Build FTS5 MATCH query: OR all keywords
+            const matchTerms = opts.keywords
+                .map(kw => `"${kw.replace(/"/g, '""')}"`)
+                .join(' OR ');
+            const sql = `
+        SELECT id, bm25(instructions_fts, 0, 10.0, 5.0, 1.0) as rank
+        FROM instructions_fts
+        WHERE instructions_fts MATCH ?
+        ORDER BY rank
+        ${opts.limit ? 'LIMIT ?' : ''}
+      `;
+            const params = [matchTerms];
+            if (opts.limit)
+                params.push(opts.limit);
+            const rows = this.db.prepare(sql).all(...params);
+            return rows.map(row => {
+                const r = row;
+                return {
+                    id: r.id,
+                    // BM25 returns negative scores (lower = better), negate for positive ranking
+                    score: -r.rank,
+                };
+            });
+        }
+        catch {
+            // FTS5 unavailable — fall back to in-memory search
+            return this.search(opts);
+        }
+    }
+    // ── Integrity ──────────────────────────────────────────────────────
+    computeHash() {
+        this.ensureLoaded();
+        return (0, hashUtils_js_1.computeGovernanceHashFromEntries)(Array.from(this.cache.values()));
+    }
+    count() {
+        this.ensureLoaded();
+        return this.cache.size;
+    }
+    // ── Internal ───────────────────────────────────────────────────────
+    ensureLoaded() {
+        if (!this.loaded) {
+            this.load();
+        }
+    }
+}
+exports.SqliteStore = SqliteStore;

package/dist/services/storage/sqliteUsageStore.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SqliteUsageStore — Usage tracking backed by node:sqlite.
+ *
+ * Stores instruction usage counts, timestamps, and signals in the
+ * usage table. Provides atomic increment and bulk snapshot operations.
+ */
+export interface UsageRecord {
+    instructionId: string;
+    usageCount: number;
+    firstSeenTs: string | null;
+    lastUsedAt: string | null;
+    lastAction: string | null;
+    lastSignal: string | null;
+    lastComment: string | null;
+}
+export interface TrackOptions {
+    action?: string;
+    signal?: string;
+    comment?: string;
+}
+export declare class SqliteUsageStore {
+    private db;
+    constructor(dbPath: string);
+    /** Get usage record for an instruction. */
+    get(instructionId: string): UsageRecord | null;
+    /** Increment usage count and update timestamps/signals. */
+    increment(instructionId: string, opts?: TrackOptions): UsageRecord;
+    /** Get all usage records as a snapshot. */
+    snapshot(): Record<string, UsageRecord>;
+    /** Reset usage for a specific instruction or all. */
+    flush(instructionId?: string): void;
+    /** Count of tracked instructions. */
+    count(): number;
+    close(): void;
+}

package/dist/services/storage/sqliteUsageStore.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * SqliteUsageStore — Usage tracking backed by node:sqlite.
+ *
+ * Stores instruction usage counts, timestamps, and signals in the
+ * usage table. Provides atomic increment and bulk snapshot operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteUsageStore = void 0;
+const node_sqlite_1 = require("node:sqlite");
+const sqliteSchema_js_1 = require("./sqliteSchema.js");
+class SqliteUsageStore {
+    db;
+    constructor(dbPath) {
+        this.db = new node_sqlite_1.DatabaseSync(dbPath);
+        this.db.exec(sqliteSchema_js_1.PRAGMAS);
+        this.db.exec(sqliteSchema_js_1.INSTRUCTIONS_DDL);
+    }
+    /** Get usage record for an instruction. */
+    get(instructionId) {
+        const row = this.db.prepare('SELECT * FROM usage WHERE instruction_id = ?').get(instructionId);
+        if (!row)
+            return null;
+        return {
+            instructionId: row.instruction_id,
+            usageCount: row.usage_count ?? 0,
+            firstSeenTs: row.first_seen_ts,
+            lastUsedAt: row.last_used_at,
+            lastAction: row.last_action,
+            lastSignal: row.last_signal,
+            lastComment: row.last_comment,
+        };
+    }
+    /** Increment usage count and update timestamps/signals. */
+    increment(instructionId, opts) {
+        const now = new Date().toISOString();
+        const existing = this.get(instructionId);
+        if (existing) {
+            this.db.prepare(`
+        UPDATE usage SET
+          usage_count = usage_count + 1,
+          last_used_at = ?,
+          last_action = COALESCE(?, last_action),
+          last_signal = COALESCE(?, last_signal),
+          last_comment = COALESCE(?, last_comment)
+        WHERE instruction_id = ?
+      `).run(now, opts?.action ?? null, opts?.signal ?? null, opts?.comment ?? null, instructionId);
+        }
+        else {
+            this.db.prepare(`
+        INSERT INTO usage (instruction_id, usage_count, first_seen_ts, last_used_at, last_action, last_signal, last_comment)
+        VALUES (?, 1, ?, ?, ?, ?, ?)
+      `).run(instructionId, now, now, opts?.action ?? null, opts?.signal ?? null, opts?.comment ?? null);
+        }
+        return this.get(instructionId);
+    }
+    /** Get all usage records as a snapshot. */
+    snapshot() {
+        const rows = this.db.prepare('SELECT * FROM usage').all();
+        const result = {};
+        for (const row of rows) {
+            const r = row;
+            const id = r.instruction_id;
+            result[id] = {
+                instructionId: id,
+                usageCount: r.usage_count ?? 0,
+                firstSeenTs: r.first_seen_ts,
+                lastUsedAt: r.last_used_at,
+                lastAction: r.last_action,
+                lastSignal: r.last_signal,
+                lastComment: r.last_comment,
+            };
+        }
+        return result;
+    }
+    /** Reset usage for a specific instruction or all. */
+    flush(instructionId) {
+        if (instructionId) {
+            this.db.prepare('DELETE FROM usage WHERE instruction_id = ?').run(instructionId);
+        }
+        else {
+            this.db.exec('DELETE FROM usage');
+        }
+    }
+    /** Count of tracked instructions. */
+    count() {
+        const row = this.db.prepare('SELECT COUNT(*) as cnt FROM usage').get();
+        return row?.cnt ?? 0;
+    }
+    close() {
+        this.db.close();
+    }
+}
+exports.SqliteUsageStore = SqliteUsageStore;