homegraph 1.1.2 → 1.2.0

package/dist/spec/db/fts.d.ts

@@ -0,0 +1,74 @@
+/**
+ * FTS5 Full-Text Search for Specs — with CJK tokenisation,
+ * weighted ranking, and multi-stage LIKE fallback.
+ *
+ * FTS5's ``unicode61`` tokeniser treats consecutive CJK characters as a
+ * single token. To support single-character / phrase queries we insert
+ * a space between each CJK codepoint before indexing *and* before
+ * searching.
+ *
+ * Weighting strategy:
+ *   Title matches are boosted over subtitle matches via post-scoring.
+ *   Both FTS5 and LIKE stages use the same score semantics:
+ *
+ *     =====  ====================
+ *     Score  Meaning
+ *     =====  ====================
+ *     3.0    exact title match
+ *     2.5    title starts with query
+ *     2.0    title contains query
+ *     1.0    keyword match in subtitles only
+ *     =====  ====================
+ *
+ *   FTS5 returns ``limit * 3`` candidates; they are re-ranked and the
+ *   top *limit* are returned.
+ *
+ * Fallback strategy (3 stages):
+ *   1. FTS5 weighted search (primary)
+ *   2. LIKE tiered scoring (same score semantics as FTS5)
+ *   3. If still no results, return most-recently-added specs as a
+ *      "discovery" fallback.
+ */
+import { SqliteDatabase } from '../../db/sqlite-adapter';
+import { SpecSearchResult } from '../types';
+/**
+ * Insert a space between adjacent CJK characters so FTS5's unicode61
+ * tokeniser can index them individually.
+ */
+export declare function segmentCjk(text: string): string;
+/**
+ * Escape / pre-process a user query for FTS5.
+ *
+ * 1. Segment CJK runs by inserting spaces.
+ * 2. Quote each token so FTS5 treats it as a literal term.
+ */
+export declare function escapeFtsQuery(query: string): string;
+/**
+ * Combined FTS5 + LIKE fallback search for specs.
+ *
+ * Strategy:
+ *   1. FTS5 weighted search (title 3× boost).
+ *   2. If fewer than *limit* results, backfill with LIKE tiered scoring.
+ *   3. If still no results, return most-recently-added specs as a
+ *      discovery fallback.
+ *
+ * Every result contains ``id, title, subtitles, _score`` and
+ * optionally ``_method`` (``"fts5"`` | ``"like"`` | ``"all"`` | ``"discovery"``)
+ * and ``_tier`` (for LIKE matches).
+ */
+export declare function searchSpecs(db: SqliteDatabase, query: string, limit?: number): SpecSearchResult[];
+/**
+ * Search code fragment diffs by entity name or keyword.
+ *
+ * Uses FTS5 on the ``code_fragments_fts`` virtual table to find fragments
+ * whose ``code_diff`` text matches the query. This is used to bridge
+ * code-entity names (e.g. ``validatePassword``) to Specs when the entity
+ * name does not appear in the Spec's title/subtitles.
+ *
+ * @param db     Active SQLite database handle.
+ * @param query  Entity name or keyword to search for in code diffs.
+ * @param limit  Maximum number of fragment IDs to return (default 50).
+ * @returns Array of matching fragment IDs, ordered by FTS5 rank.
+ */
+export declare function searchCodeFragments(db: SqliteDatabase, query: string, limit?: number): string[];
+//# sourceMappingURL=fts.d.ts.map

package/dist/spec/db/fts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts.d.ts","sourceRoot":"","sources":["../../../src/spec/db/fts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAS5C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQpD;AA8MD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAW,GACjB,gBAAgB,EAAE,CA8CpB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,EAClB,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,MAAW,GACjB,MAAM,EAAE,CAqBV"}

package/dist/spec/db/fts.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * FTS5 Full-Text Search for Specs — with CJK tokenisation,
+ * weighted ranking, and multi-stage LIKE fallback.
+ *
+ * FTS5's ``unicode61`` tokeniser treats consecutive CJK characters as a
+ * single token. To support single-character / phrase queries we insert
+ * a space between each CJK codepoint before indexing *and* before
+ * searching.
+ *
+ * Weighting strategy:
+ *   Title matches are boosted over subtitle matches via post-scoring.
+ *   Both FTS5 and LIKE stages use the same score semantics:
+ *
+ *     =====  ====================
+ *     Score  Meaning
+ *     =====  ====================
+ *     3.0    exact title match
+ *     2.5    title starts with query
+ *     2.0    title contains query
+ *     1.0    keyword match in subtitles only
+ *     =====  ====================
+ *
+ *   FTS5 returns ``limit * 3`` candidates; they are re-ranked and the
+ *   top *limit* are returned.
+ *
+ * Fallback strategy (3 stages):
+ *   1. FTS5 weighted search (primary)
+ *   2. LIKE tiered scoring (same score semantics as FTS5)
+ *   3. If still no results, return most-recently-added specs as a
+ *      "discovery" fallback.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.segmentCjk = segmentCjk;
+exports.escapeFtsQuery = escapeFtsQuery;
+exports.searchSpecs = searchSpecs;
+exports.searchCodeFragments = searchCodeFragments;
+// ===========================================================================
+// CJK Segmentation
+// ===========================================================================
+/** Regex matching a CJK Unified Ideograph (U+4E00–U+9FFF). */
+const CJK_RANGE = /[\u4e00-\u9fff]+/g;
+/**
+ * Insert a space between adjacent CJK characters so FTS5's unicode61
+ * tokeniser can index them individually.
+ */
+function segmentCjk(text) {
+    return text.replace(CJK_RANGE, (m) => m.split('').join(' '));
+}
+/**
+ * Escape / pre-process a user query for FTS5.
+ *
+ * 1. Segment CJK runs by inserting spaces.
+ * 2. Quote each token so FTS5 treats it as a literal term.
+ */
+function escapeFtsQuery(query) {
+    const trimmed = query.trim();
+    if (!trimmed)
+        return '""';
+    const segmented = segmentCjk(trimmed);
+    const tokens = segmented.split(/\s+/).filter(Boolean);
+    // Escape embedded double-quotes: inside FTS5 quoted phrases, " is escaped as ""
+    return tokens.map((t) => `"${t.replace(/"/g, '""')}"`).join(' ') || '""';
+}
+// ===========================================================================
+// Weighted Scoring
+// ===========================================================================
+/**
+ * Compute a title-match boost factor.
+ *
+ *   3.0 — exact match
+ *   2.5 — title starts with query
+ *   2.0 — title contains query
+ *   1.0 — no title match (subtitles only)
+ */
+function scoreTitleMatch(title, query) {
+    const q = query.toLowerCase().trim();
+    const t = title.toLowerCase();
+    if (q === t)
+        return 3.0;
+    if (t.startsWith(q))
+        return 2.5;
+    if (t.includes(q))
+        return 2.0;
+    return 1.0;
+}
+/**
+ * LIKE tiered scoring.
+ *
+ * Returns ``[score, tierLabel]`` where higher score = more relevant.
+ * Score semantics are aligned with ``scoreTitleMatch`` so cross-stage
+ * re-ranking works correctly.
+ */
+function likeScore(title, query) {
+    const t = title.toLowerCase().trim();
+    const q = query.toLowerCase().trim();
+    if (t === q)
+        return [3.0, 'exact_title'];
+    if (t.startsWith(q))
+        return [2.5, 'starts_with_title'];
+    if (t.includes(q))
+        return [2.0, 'contains_title'];
+    return [1.0, 'contains_subtitle'];
+}
+// ===========================================================================
+// Stage 1: FTS5 Weighted Search
+// ===========================================================================
+/**
+ * Weighted FTS5 search with title boost.
+ *
+ * Fetches ``limit * oversample`` candidates from FTS5, re-ranks by
+ * weighted score, and returns the top *limit*.
+ */
+function searchSpecsFts(db, query, limit, oversample = 3) {
+    const escaped = escapeFtsQuery(query);
+    const rawLimit = limit * oversample;
+    let rows;
+    try {
+        rows = db
+            .prepare(`SELECT s.id, s.title, s.subtitles
+         FROM specs_fts f
+         JOIN spec_nodes s ON s.id = f.id
+         WHERE specs_fts MATCH ?
+         ORDER BY rank LIMIT ?`)
+            .all(escaped, rawLimit);
+    }
+    catch {
+        return [];
+    }
+    const scored = [];
+    for (const row of rows) {
+        let subtitles;
+        try {
+            subtitles = JSON.parse(row.subtitles || '[]');
+        }
+        catch {
+            subtitles = [];
+        }
+        const boost = scoreTitleMatch(row.title, query);
+        scored.push({
+            score: boost,
+            result: {
+                id: row.id,
+                title: row.title,
+                subtitles,
+                _score: boost,
+                _method: 'fts5',
+            },
+        });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit).map((s) => s.result);
+}
+// ===========================================================================
+// Stage 2: LIKE Tiered Fallback
+// ===========================================================================
+/**
+ * LIKE fallback search with tiered scoring.
+ *
+ * Skips any spec whose id appears in *excludeIds* (to avoid
+ * duplicating FTS5 results).
+ */
+function searchSpecsLike(db, query, limit, excludeIds) {
+    // Escape LIKE metacharacters so '%' and '_' are treated as literals
+    const escaped = query.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
+    const likePat = `%${escaped}%`;
+    const rows = db
+        .prepare(`SELECT id, title, subtitles FROM spec_nodes
+       WHERE title LIKE ? ESCAPE '\\' OR subtitles LIKE ? ESCAPE '\\'
+       ORDER BY id LIMIT ?`)
+        .all(likePat, likePat, limit * 3);
+    const scored = [];
+    for (const row of rows) {
+        if (excludeIds.has(row.id))
+            continue;
+        let subtitles;
+        try {
+            subtitles = JSON.parse(row.subtitles || '[]');
+        }
+        catch {
+            subtitles = [];
+        }
+        const [score, tier] = likeScore(row.title, query);
+        scored.push({
+            score,
+            tier,
+            result: {
+                id: row.id,
+                title: row.title,
+                subtitles,
+                _score: score,
+                _method: 'like',
+                _tier: tier,
+            },
+        });
+    }
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.tier.localeCompare(b.tier);
+    });
+    return scored.slice(0, limit).map((s) => s.result);
+}
+// ===========================================================================
+// Stage 3: Discovery Fallback
+// ===========================================================================
+/**
+ * Return the most-recently-added specs when all searches produce
+ * no results — so the caller always gets something.
+ */
+function discoveryFallback(db, limit) {
+    const rows = db
+        .prepare('SELECT id, title, subtitles FROM spec_nodes ORDER BY timestamp DESC LIMIT ?')
+        .all(limit);
+    return rows.map((row) => {
+        let subtitles;
+        try {
+            subtitles = JSON.parse(row.subtitles || '[]');
+        }
+        catch {
+            subtitles = [];
+        }
+        return {
+            id: row.id,
+            title: row.title,
+            subtitles,
+            _score: 0.0,
+            _method: 'discovery',
+        };
+    });
+}
+// ===========================================================================
+// Combined Search (public API)
+// ===========================================================================
+/**
+ * Combined FTS5 + LIKE fallback search for specs.
+ *
+ * Strategy:
+ *   1. FTS5 weighted search (title 3× boost).
+ *   2. If fewer than *limit* results, backfill with LIKE tiered scoring.
+ *   3. If still no results, return most-recently-added specs as a
+ *      discovery fallback.
+ *
+ * Every result contains ``id, title, subtitles, _score`` and
+ * optionally ``_method`` (``"fts5"`` | ``"like"`` | ``"all"`` | ``"discovery"``)
+ * and ``_tier`` (for LIKE matches).
+ */
+function searchSpecs(db, query, limit = 10) {
+    // Empty query — return all specs (recent first)
+    if (!query.trim()) {
+        const rows = db
+            .prepare('SELECT id, title, subtitles FROM spec_nodes ORDER BY id LIMIT ?')
+            .all(limit);
+        return rows.map((row) => {
+            let subtitles;
+            try {
+                subtitles = JSON.parse(row.subtitles || '[]');
+            }
+            catch {
+                subtitles = [];
+            }
+            return {
+                id: row.id,
+                title: row.title,
+                subtitles,
+                _score: 0.0,
+                _method: 'all',
+            };
+        });
+    }
+    // Stage 1: FTS5 weighted search
+    const ftsResults = searchSpecsFts(db, query, limit);
+    if (ftsResults.length >= limit) {
+        return ftsResults;
+    }
+    // Stage 2: LIKE fallback
+    const seenIds = new Set(ftsResults.map((r) => r.id));
+    const needed = limit - ftsResults.length;
+    const likeResults = searchSpecsLike(db, query, needed, seenIds);
+    // Cross-stage re-sort: LIKE and FTS5 share the same score semantics
+    const combined = [...ftsResults, ...likeResults];
+    combined.sort((a, b) => (b._score ?? 0) - (a._score ?? 0));
+    // Stage 3: discovery fallback — no matches at all
+    if (combined.length === 0) {
+        return discoveryFallback(db, limit);
+    }
+    return combined.slice(0, limit);
+}
+// ===========================================================================
+// Code Fragment FTS5 Search
+// ===========================================================================
+/**
+ * Search code fragment diffs by entity name or keyword.
+ *
+ * Uses FTS5 on the ``code_fragments_fts`` virtual table to find fragments
+ * whose ``code_diff`` text matches the query. This is used to bridge
+ * code-entity names (e.g. ``validatePassword``) to Specs when the entity
+ * name does not appear in the Spec's title/subtitles.
+ *
+ * @param db     Active SQLite database handle.
+ * @param query  Entity name or keyword to search for in code diffs.
+ * @param limit  Maximum number of fragment IDs to return (default 50).
+ * @returns Array of matching fragment IDs, ordered by FTS5 rank.
+ */
+function searchCodeFragments(db, query, limit = 50) {
+    const trimmed = query.trim();
+    if (!trimmed)
+        return [];
+    // Escape FTS5 special characters and quote each token for literal matching
+    const escaped = escapeFtsQuery(trimmed);
+    let rows;
+    try {
+        rows = db
+            .prepare(`SELECT id FROM code_fragments_fts
+         WHERE code_fragments_fts MATCH ?
+         ORDER BY rank LIMIT ?`)
+            .all(escaped, limit);
+    }
+    catch {
+        return [];
+    }
+    return rows.map((r) => r.id);
+}
+//# sourceMappingURL=fts.js.map

package/dist/spec/db/fts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts.js","sourceRoot":"","sources":["../../../src/spec/db/fts.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;AAgBH,gCAEC;AAQD,wCAQC;AA2ND,kCAkDC;AAmBD,kDAyBC;AAtVD,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,8DAA8D;AAC9D,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC;;;GAGG;AACH,SAAgB,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,KAAa;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtD,gFAAgF;IAChF,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;AAC3E,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,KAAa,EAAE,KAAa;IACnD,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAC9B,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACxB,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IAChC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,GAAG,CAAC;IAC9B,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,SAAS,SAAS,CAAC,KAAa,EAAE,KAAa;IAC7C,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IACvD,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;IAClD,OAAO,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;AACpC,CAAC;AAYD,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E;;;;;GAKG;AACH,SAAS,cAAc,CACrB,EAAkB,EAClB,KAAa,EACb,KAAa,EACb,aAAqB,CAAC;IAEtB,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;IAEpC,IAAI,IAAkB,CAAC;IACvB,IAAI,CAAC;QACH,IAAI,GAAG,EAAE;aACN,OAAO,CACN;;;;+BAIuB,CACxB;aACA,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAiB,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAuD,EAAE,CAAC;IACtE,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,SAAmB,CAAC;QACxB,IAAI,CAAC;YACH,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,GAAG,EAAE,CAAC;QACjB,CAAC;QAED,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAChD,MAAM,CAAC,IAAI,CAAC;YACV,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE;gBACN,EAAE,EAAE,GAAG,CAAC,EAAE;gBACV,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,SAAS;gBACT,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,MAAM;aAChB;SACF,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC;AAED,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E;;;;;GAKG;AACH,SAAS,eAAe,CACtB,EAAkB,EAClB,KAAa,EACb,KAAa,EACb,UAAuB;IAEvB,oEAAoE;IACpE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACvF,MAAM,OAAO,GAAG,IAAI,OAAO,GAAG,CAAC;IAE/B,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CACN;;2BAEqB,CACtB;SACA,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,GAAG,CAAC,CAAiB,CAAC;IAEpD,MAAM,MAAM,GAAqE,EAAE,CAAC;IACpF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,SAAS;QAErC,IAAI,SAAmB,CAAC;QACxB,IAAI,CAAC;YACH,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,GAAG,EAAE,CAAC;QACjB,CAAC;QAED,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAClD,MAAM,CAAC,IAAI,CAAC;YACV,KAAK;YACL,IAAI;YACJ,MAAM,EAAE;gBACN,EAAE,EAAE,GAAG,CAAC,EAAE;gBACV,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,SAAS;gBACT,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,MAAM;gBACf,KAAK,EAAE,IAAiC;aACzC;SACF,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACnB,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;YAAE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAClD,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC;AAED,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,iBAAiB,CAAC,EAAkB,EAAE,KAAa;IAC1D,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CACN,6EAA6E,CAC9E;SACA,GAAG,CAAC,KAAK,CAAiB,CAAC;IAE9B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACtB,IAAI,SAAmB,CAAC;QACxB,IAAI,CAAC;YACH,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,GAAG,EAAE,CAAC;QACjB,CAAC;QACD,OAAO;YACL,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,SAAS;YACT,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,WAAoB;SAC9B,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,SAAgB,WAAW,CACzB,EAAkB,EAClB,KAAa,EACb,QAAgB,EAAE;IAElB,gDAAgD;IAChD,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB,MAAM,IAAI,GAAG,EAAE;aACZ,OAAO,CAAC,iEAAiE,CAAC;aAC1E,GAAG,CAAC,KAAK,CAAiB,CAAC;QAE9B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YACtB,IAAI,SAAmB,CAAC;YACxB,IAAI,CAAC;gBACH,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;YAChD,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS,GAAG,EAAE,CAAC;YACjB,CAAC;YACD,OAAO;gBACL,EAAE,EAAE,GAAG,CAAC,EAAE;gBACV,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,SAAS;gBACT,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE,KAAc;aACxB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED,gCAAgC;IAChC,MAAM,UAAU,GAAG,cAAc,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAEpD,IAAI,UAAU,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;QAC/B,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,yBAAyB;IACzB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC;IACzC,MAAM,WAAW,GAAG,eAAe,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhE,oEAAoE;IACpE,MAAM,QAAQ,GAAG,CAAC,GAAG,UAAU,EAAE,GAAG,WAAW,CAAC,CAAC;IACjD,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;IAE3D,kDAAkD;IAClD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,iBAAiB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAClC,CAAC;AAED,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,SAAgB,mBAAmB,CACjC,EAAkB,EAClB,KAAa,EACb,QAAgB,EAAE;IAElB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,2EAA2E;IAC3E,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAExC,IAAI,IAA2B,CAAC;IAChC,IAAI,CAAC;QACH,IAAI,GAAG,EAAE;aACN,OAAO,CACN;;+BAEuB,CACxB;aACA,GAAG,CAAC,OAAO,EAAE,KAAK,CAA0B,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC/B,CAAC"}

package/dist/spec/db/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Spec Database Layer — Barrel Export
+ *
+ * Re-exports all CRUD operations, schema initialisation, and FTS5
+ * search so consumers can `import { ... } from '../spec/db'`.
+ */
+export { initSpecSchema, getCurrentSpecVersion, runSpecMigrations, CURRENT_SPEC_SCHEMA_VERSION } from './schema';
+export { insertSpecNode, findSpecById, updateSpecStatus, updateSpecVersion, deleteSpec, listAllSpecs, countSpecsByStatus, } from './spec-node';
+export { insertCommitNode, findCommitByHash, listAllCommits, countCommits, } from './commit-node';
+export { insertCodeFragment, findFragmentById, findFragmentsByCommit, countFragments, } from './fragment-node';
+export { insertSpecCommitRelation, findCommitsBySpec, transferSpecCommitRelations, insertCommitFragmentRelation, insertSpecSpecRelation, deleteSimilarToRelations, transferSpecSpecRelations, countAllRelations, } from './relations';
+export { searchSpecs, escapeFtsQuery, segmentCjk, } from './fts';
+//# sourceMappingURL=index.d.ts.map

package/dist/spec/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spec/db/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAGjH,OAAO,EACL,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,GACb,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,GACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,2BAA2B,EAC3B,4BAA4B,EAC5B,sBAAsB,EACtB,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,WAAW,EACX,cAAc,EACd,UAAU,GACX,MAAM,OAAO,CAAC"}

package/dist/spec/db/index.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Spec Database Layer — Barrel Export
+ *
+ * Re-exports all CRUD operations, schema initialisation, and FTS5
+ * search so consumers can `import { ... } from '../spec/db'`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.segmentCjk = exports.escapeFtsQuery = exports.searchSpecs = exports.countAllRelations = exports.transferSpecSpecRelations = exports.deleteSimilarToRelations = exports.insertSpecSpecRelation = exports.insertCommitFragmentRelation = exports.transferSpecCommitRelations = exports.findCommitsBySpec = exports.insertSpecCommitRelation = exports.countFragments = exports.findFragmentsByCommit = exports.findFragmentById = exports.insertCodeFragment = exports.countCommits = exports.listAllCommits = exports.findCommitByHash = exports.insertCommitNode = exports.countSpecsByStatus = exports.listAllSpecs = exports.deleteSpec = exports.updateSpecVersion = exports.updateSpecStatus = exports.findSpecById = exports.insertSpecNode = exports.CURRENT_SPEC_SCHEMA_VERSION = exports.runSpecMigrations = exports.getCurrentSpecVersion = exports.initSpecSchema = void 0;
+// Schema
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "initSpecSchema", { enumerable: true, get: function () { return schema_1.initSpecSchema; } });
+Object.defineProperty(exports, "getCurrentSpecVersion", { enumerable: true, get: function () { return schema_1.getCurrentSpecVersion; } });
+Object.defineProperty(exports, "runSpecMigrations", { enumerable: true, get: function () { return schema_1.runSpecMigrations; } });
+Object.defineProperty(exports, "CURRENT_SPEC_SCHEMA_VERSION", { enumerable: true, get: function () { return schema_1.CURRENT_SPEC_SCHEMA_VERSION; } });
+// Entity CRUD
+var spec_node_1 = require("./spec-node");
+Object.defineProperty(exports, "insertSpecNode", { enumerable: true, get: function () { return spec_node_1.insertSpecNode; } });
+Object.defineProperty(exports, "findSpecById", { enumerable: true, get: function () { return spec_node_1.findSpecById; } });
+Object.defineProperty(exports, "updateSpecStatus", { enumerable: true, get: function () { return spec_node_1.updateSpecStatus; } });
+Object.defineProperty(exports, "updateSpecVersion", { enumerable: true, get: function () { return spec_node_1.updateSpecVersion; } });
+Object.defineProperty(exports, "deleteSpec", { enumerable: true, get: function () { return spec_node_1.deleteSpec; } });
+Object.defineProperty(exports, "listAllSpecs", { enumerable: true, get: function () { return spec_node_1.listAllSpecs; } });
+Object.defineProperty(exports, "countSpecsByStatus", { enumerable: true, get: function () { return spec_node_1.countSpecsByStatus; } });
+var commit_node_1 = require("./commit-node");
+Object.defineProperty(exports, "insertCommitNode", { enumerable: true, get: function () { return commit_node_1.insertCommitNode; } });
+Object.defineProperty(exports, "findCommitByHash", { enumerable: true, get: function () { return commit_node_1.findCommitByHash; } });
+Object.defineProperty(exports, "listAllCommits", { enumerable: true, get: function () { return commit_node_1.listAllCommits; } });
+Object.defineProperty(exports, "countCommits", { enumerable: true, get: function () { return commit_node_1.countCommits; } });
+var fragment_node_1 = require("./fragment-node");
+Object.defineProperty(exports, "insertCodeFragment", { enumerable: true, get: function () { return fragment_node_1.insertCodeFragment; } });
+Object.defineProperty(exports, "findFragmentById", { enumerable: true, get: function () { return fragment_node_1.findFragmentById; } });
+Object.defineProperty(exports, "findFragmentsByCommit", { enumerable: true, get: function () { return fragment_node_1.findFragmentsByCommit; } });
+Object.defineProperty(exports, "countFragments", { enumerable: true, get: function () { return fragment_node_1.countFragments; } });
+// Relations
+var relations_1 = require("./relations");
+Object.defineProperty(exports, "insertSpecCommitRelation", { enumerable: true, get: function () { return relations_1.insertSpecCommitRelation; } });
+Object.defineProperty(exports, "findCommitsBySpec", { enumerable: true, get: function () { return relations_1.findCommitsBySpec; } });
+Object.defineProperty(exports, "transferSpecCommitRelations", { enumerable: true, get: function () { return relations_1.transferSpecCommitRelations; } });
+Object.defineProperty(exports, "insertCommitFragmentRelation", { enumerable: true, get: function () { return relations_1.insertCommitFragmentRelation; } });
+Object.defineProperty(exports, "insertSpecSpecRelation", { enumerable: true, get: function () { return relations_1.insertSpecSpecRelation; } });
+Object.defineProperty(exports, "deleteSimilarToRelations", { enumerable: true, get: function () { return relations_1.deleteSimilarToRelations; } });
+Object.defineProperty(exports, "transferSpecSpecRelations", { enumerable: true, get: function () { return relations_1.transferSpecSpecRelations; } });
+Object.defineProperty(exports, "countAllRelations", { enumerable: true, get: function () { return relations_1.countAllRelations; } });
+// FTS5 Search
+var fts_1 = require("./fts");
+Object.defineProperty(exports, "searchSpecs", { enumerable: true, get: function () { return fts_1.searchSpecs; } });
+Object.defineProperty(exports, "escapeFtsQuery", { enumerable: true, get: function () { return fts_1.escapeFtsQuery; } });
+Object.defineProperty(exports, "segmentCjk", { enumerable: true, get: function () { return fts_1.segmentCjk; } });
+//# sourceMappingURL=index.js.map

package/dist/spec/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/spec/db/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,SAAS;AACT,mCAAiH;AAAxG,wGAAA,cAAc,OAAA;AAAE,+GAAA,qBAAqB,OAAA;AAAE,2GAAA,iBAAiB,OAAA;AAAE,qHAAA,2BAA2B,OAAA;AAE9F,cAAc;AACd,yCAQqB;AAPnB,2GAAA,cAAc,OAAA;AACd,yGAAA,YAAY,OAAA;AACZ,6GAAA,gBAAgB,OAAA;AAChB,8GAAA,iBAAiB,OAAA;AACjB,uGAAA,UAAU,OAAA;AACV,yGAAA,YAAY,OAAA;AACZ,+GAAA,kBAAkB,OAAA;AAGpB,6CAKuB;AAJrB,+GAAA,gBAAgB,OAAA;AAChB,+GAAA,gBAAgB,OAAA;AAChB,6GAAA,cAAc,OAAA;AACd,2GAAA,YAAY,OAAA;AAGd,iDAKyB;AAJvB,mHAAA,kBAAkB,OAAA;AAClB,iHAAA,gBAAgB,OAAA;AAChB,sHAAA,qBAAqB,OAAA;AACrB,+GAAA,cAAc,OAAA;AAGhB,YAAY;AACZ,yCASqB;AARnB,qHAAA,wBAAwB,OAAA;AACxB,8GAAA,iBAAiB,OAAA;AACjB,wHAAA,2BAA2B,OAAA;AAC3B,yHAAA,4BAA4B,OAAA;AAC5B,mHAAA,sBAAsB,OAAA;AACtB,qHAAA,wBAAwB,OAAA;AACxB,sHAAA,yBAAyB,OAAA;AACzB,8GAAA,iBAAiB,OAAA;AAGnB,cAAc;AACd,6BAIe;AAHb,kGAAA,WAAW,OAAA;AACX,qGAAA,cAAc,OAAA;AACd,iGAAA,UAAU,OAAA"}

package/dist/spec/db/relations.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Relation CRUD — persistence operations for the three relation tables:
+ *
+ *   - ``spec_commit_relations``   (Spec ↔ Commit)
+ *   - ``commit_fragment_relations`` (Commit ↔ CodeFragment)
+ *   - ``spec_spec_relations``     (Spec ↔ Spec)
+ */
+import { SqliteDatabase } from '../../db/sqlite-adapter';
+import { RelationType, SpecCommitRelation } from '../types';
+/**
+ * Insert a relation between a Spec and a Commit.
+ * `INSERT OR IGNORE` — duplicates are silently skipped.
+ */
+export declare function insertSpecCommitRelation(db: SqliteDatabase, specId: string, commitHash: string, relationType: RelationType): void;
+/**
+ * Find all commits linked to a spec, ordered by commit timestamp
+ * (oldest first — matches Commit4Spec's mining pipeline sort).
+ */
+export declare function findCommitsBySpec(db: SqliteDatabase, specId: string): Array<SpecCommitRelation & {
+    message: string;
+    author: string;
+    timestamp: number;
+}>;
+/**
+ * Transfer all spec–commit relations from one spec to another.
+ * Used during self-evolve when a spec is versioned:
+ * old active spec's relations move to the deprecated record.
+ */
+export declare function transferSpecCommitRelations(db: SqliteDatabase, fromSpecId: string, toSpecId: string): void;
+/**
+ * Link a commit to a code fragment.
+ * `INSERT OR IGNORE` — duplicates are silently skipped.
+ */
+export declare function insertCommitFragmentRelation(db: SqliteDatabase, commitHash: string, fragmentId: string): void;
+/**
+ * Insert a relation between two specs (SIMILAR_TO or EVOLVED_FROM).
+ * `INSERT OR IGNORE` — duplicates are silently skipped.
+ */
+export declare function insertSpecSpecRelation(db: SqliteDatabase, sourceId: string, targetId: string, relationType: RelationType): void;
+/**
+ * Remove all SIMILAR_TO relations involving a spec.
+ * Called when a spec is deprecated (similarity links become stale).
+ */
+export declare function deleteSimilarToRelations(db: SqliteDatabase, specId: string): void;
+/**
+ * Transfer all spec–spec relations from one spec to another.
+ * Used during self-evolve versioning (old spec's relations move to
+ * the deprecated record).
+ */
+export declare function transferSpecSpecRelations(db: SqliteDatabase, fromSpecId: string, toSpecId: string): void;
+/**
+ * Count total rows across all three relation tables.
+ */
+export declare function countAllRelations(db: SqliteDatabase): number;
+//# sourceMappingURL=relations.d.ts.map

package/dist/spec/db/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../../src/spec/db/relations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAM5D;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,YAAY,GACzB,IAAI,CAMN;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,MAAM,GACb,KAAK,CAAC,kBAAkB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAwBpF;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,EAAE,EAAE,cAAc,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,IAAI,CAMN;AAMD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,cAAc,EAClB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,IAAI,CAMN;AAMD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,YAAY,GACzB,IAAI,CAMN;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAMjF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,cAAc,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,IAAI,CA6BN;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,GAAG,MAAM,CAa5D"}