homegraph 1.1.2 → 1.2.0

package/dist/spec/db/relations.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Relation CRUD — persistence operations for the three relation tables:
+ *
+ *   - ``spec_commit_relations``   (Spec ↔ Commit)
+ *   - ``commit_fragment_relations`` (Commit ↔ CodeFragment)
+ *   - ``spec_spec_relations``     (Spec ↔ Spec)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.insertSpecCommitRelation = insertSpecCommitRelation;
+exports.findCommitsBySpec = findCommitsBySpec;
+exports.transferSpecCommitRelations = transferSpecCommitRelations;
+exports.insertCommitFragmentRelation = insertCommitFragmentRelation;
+exports.insertSpecSpecRelation = insertSpecSpecRelation;
+exports.deleteSimilarToRelations = deleteSimilarToRelations;
+exports.transferSpecSpecRelations = transferSpecSpecRelations;
+exports.countAllRelations = countAllRelations;
+// ===========================================================================
+// Spec ↔ Commit Relations
+// ===========================================================================
+/**
+ * Insert a relation between a Spec and a Commit.
+ * `INSERT OR IGNORE` — duplicates are silently skipped.
+ */
+function insertSpecCommitRelation(db, specId, commitHash, relationType) {
+    db.prepare(`
+    INSERT OR IGNORE INTO spec_commit_relations
+      (spec_id, commit_hash, relation_type)
+    VALUES (@specId, @commitHash, @relationType)
+  `).run({ specId, commitHash, relationType });
+}
+/**
+ * Find all commits linked to a spec, ordered by commit timestamp
+ * (oldest first — matches Commit4Spec's mining pipeline sort).
+ */
+function findCommitsBySpec(db, specId) {
+    const rows = db.prepare(`
+    SELECT r.commit_hash, r.relation_type,
+           c.message, c.author, c.timestamp
+    FROM spec_commit_relations r
+    JOIN commit_nodes c ON c.hash = r.commit_hash
+    WHERE r.spec_id = ?
+    ORDER BY c.timestamp ASC
+  `).all(specId);
+    return rows.map(r => ({
+        specId,
+        commitHash: r.commit_hash,
+        relationType: r.relation_type,
+        message: r.message,
+        author: r.author,
+        timestamp: r.timestamp,
+    }));
+}
+/**
+ * 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.
+ */
+function transferSpecCommitRelations(db, fromSpecId, toSpecId) {
+    db.prepare(`
+    UPDATE spec_commit_relations
+    SET spec_id = @toSpecId
+    WHERE spec_id = @fromSpecId
+  `).run({ fromSpecId, toSpecId });
+}
+// ===========================================================================
+// Commit ↔ CodeFragment Relations
+// ===========================================================================
+/**
+ * Link a commit to a code fragment.
+ * `INSERT OR IGNORE` — duplicates are silently skipped.
+ */
+function insertCommitFragmentRelation(db, commitHash, fragmentId) {
+    db.prepare(`
+    INSERT OR IGNORE INTO commit_fragment_relations
+      (commit_hash, fragment_id)
+    VALUES (@commitHash, @fragmentId)
+  `).run({ commitHash, fragmentId });
+}
+// ===========================================================================
+// Spec ↔ Spec Relations
+// ===========================================================================
+/**
+ * Insert a relation between two specs (SIMILAR_TO or EVOLVED_FROM).
+ * `INSERT OR IGNORE` — duplicates are silently skipped.
+ */
+function insertSpecSpecRelation(db, sourceId, targetId, relationType) {
+    db.prepare(`
+    INSERT OR IGNORE INTO spec_spec_relations
+      (source_id, target_id, relation_type)
+    VALUES (@sourceId, @targetId, @relationType)
+  `).run({ sourceId, targetId, relationType });
+}
+/**
+ * Remove all SIMILAR_TO relations involving a spec.
+ * Called when a spec is deprecated (similarity links become stale).
+ */
+function deleteSimilarToRelations(db, specId) {
+    db.prepare(`
+    DELETE FROM spec_spec_relations
+    WHERE relation_type = 'SIMILAR_TO'
+      AND (source_id = ? OR target_id = ?)
+  `).run(specId, specId);
+}
+/**
+ * Transfer all spec–spec relations from one spec to another.
+ * Used during self-evolve versioning (old spec's relations move to
+ * the deprecated record).
+ */
+function transferSpecSpecRelations(db, fromSpecId, toSpecId) {
+    // No transaction wrapper — callers (e.g. applyUpdate) manage
+    // their own explicit BEGIN/COMMIT boundaries.
+    // Delete rows at `toSpecId` that would collide with the rows being
+    // transferred, so the UPDATE below cannot trigger a PRIMARY KEY conflict.
+    db.prepare(`
+    DELETE FROM spec_spec_relations
+    WHERE source_id = @toSpecId
+      AND (target_id, relation_type) IN (
+        SELECT target_id, relation_type FROM spec_spec_relations
+        WHERE source_id = @fromSpecId
+      )
+  `).run({ fromSpecId, toSpecId });
+    db.prepare(`
+    DELETE FROM spec_spec_relations
+    WHERE target_id = @toSpecId
+      AND (source_id, relation_type) IN (
+        SELECT source_id, relation_type FROM spec_spec_relations
+        WHERE target_id = @fromSpecId
+      )
+  `).run({ fromSpecId, toSpecId });
+    db.prepare(`
+    UPDATE spec_spec_relations SET source_id = @toSpecId WHERE source_id = @fromSpecId
+  `).run({ fromSpecId, toSpecId });
+    db.prepare(`
+    UPDATE spec_spec_relations SET target_id = @toSpecId WHERE target_id = @fromSpecId
+  `).run({ fromSpecId, toSpecId });
+}
+// ===========================================================================
+// Stats
+// ===========================================================================
+/**
+ * Count total rows across all three relation tables.
+ */
+function countAllRelations(db) {
+    let total = 0;
+    for (const table of [
+        'spec_commit_relations',
+        'commit_fragment_relations',
+        'spec_spec_relations',
+    ]) {
+        const row = db
+            .prepare(`SELECT COUNT(*) as cnt FROM ${table}`)
+            .get();
+        total += row?.cnt ?? 0;
+    }
+    return total;
+}
+//# sourceMappingURL=relations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relations.js","sourceRoot":"","sources":["../../../src/spec/db/relations.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,33 @@
+/**
+ * Spec Schema — DDL Initialisation
+ *
+ * Reads `schema.sql` and executes all statements idempotently
+ * (`CREATE IF NOT EXISTS`). Follows the same pattern as HomeGraph's
+ * `DatabaseConnection.initialize()` in `src/db/index.ts`.
+ */
+import { SqliteDatabase } from '../../db/sqlite-adapter';
+/**
+ * The latest schema version this module knows about.
+ * Bump this when adding migrations.
+ */
+export declare const CURRENT_SPEC_SCHEMA_VERSION = 2;
+/**
+ * Execute all DDL statements from `schema.sql`.
+ *
+ * Idempotent — can be called multiple times safely (every statement
+ * uses `CREATE IF NOT EXISTS`).
+ */
+export declare function initSpecSchema(db: SqliteDatabase): void;
+/**
+ * Get the current spec schema version from the database.
+ * Returns 0 if the table doesn't exist yet.
+ */
+export declare function getCurrentSpecVersion(db: SqliteDatabase): number;
+/**
+ * Run pending migrations.
+ *
+ * v1 → v2: Create code_fragments_fts virtual table and populate it
+ * from existing code_fragment_nodes data.
+ */
+export declare function runSpecMigrations(db: SqliteDatabase, fromVersion: number): void;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/spec/db/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAIzD;;;GAGG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAMvD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,cAAc,GAAG,MAAM,CAShE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAwC/E"}

package/dist/spec/db/schema.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Spec Schema — DDL Initialisation
+ *
+ * Reads `schema.sql` and executes all statements idempotently
+ * (`CREATE IF NOT EXISTS`). Follows the same pattern as HomeGraph's
+ * `DatabaseConnection.initialize()` in `src/db/index.ts`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_SPEC_SCHEMA_VERSION = void 0;
+exports.initSpecSchema = initSpecSchema;
+exports.getCurrentSpecVersion = getCurrentSpecVersion;
+exports.runSpecMigrations = runSpecMigrations;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * The latest schema version this module knows about.
+ * Bump this when adding migrations.
+ */
+exports.CURRENT_SPEC_SCHEMA_VERSION = 2;
+/**
+ * Execute all DDL statements from `schema.sql`.
+ *
+ * Idempotent — can be called multiple times safely (every statement
+ * uses `CREATE IF NOT EXISTS`).
+ */
+function initSpecSchema(db) {
+    db.pragma('foreign_keys = ON');
+    const schemaPath = path.join(__dirname, 'schema.sql');
+    const schema = fs.readFileSync(schemaPath, 'utf-8');
+    db.exec(schema);
+}
+/**
+ * Get the current spec schema version from the database.
+ * Returns 0 if the table doesn't exist yet.
+ */
+function getCurrentSpecVersion(db) {
+    try {
+        const row = db
+            .prepare('SELECT MAX(version) as version FROM spec_schema_versions')
+            .get();
+        return row?.version ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Run pending migrations.
+ *
+ * v1 → v2: Create code_fragments_fts virtual table and populate it
+ * from existing code_fragment_nodes data.
+ */
+function runSpecMigrations(db, fromVersion) {
+    if (fromVersion < 2) {
+        // Create the FTS5 virtual table — the IF NOT EXISTS in schema.sql
+        // handles the case where DDL already ran, but we explicitly run it
+        // here for databases that existed before this migration was added.
+        db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS code_fragments_fts USING fts5(
+          id,
+          file_path,
+          code_diff
+      );
+    `);
+        // Populate FTS from existing code_fragment_nodes data
+        const count = db.prepare('SELECT COUNT(*) as cnt FROM code_fragments_fts').get().cnt;
+        if (count === 0) {
+            const rows = db
+                .prepare('SELECT id, file_path, code_diff FROM code_fragment_nodes')
+                .all();
+            if (rows.length > 0) {
+                const insert = db.prepare('INSERT INTO code_fragments_fts (id, file_path, code_diff) VALUES (?, ?, ?)');
+                const insertMany = db.transaction((fragments) => {
+                    for (const f of fragments) {
+                        insert.run(f.id, f.file_path, f.code_diff);
+                    }
+                });
+                insertMany(rows);
+            }
+        }
+        // Record migration
+        db.prepare("INSERT OR IGNORE INTO spec_schema_versions (version, applied_at, description) VALUES (2, strftime('%s', 'now') * 1000, 'Add code_fragments_fts for content-based fragment search')").run();
+    }
+}
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/spec/db/schema.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkBH,wCAMC;AAMD,sDASC;AAQD,8CAwCC;AApFD,uCAAyB;AACzB,2CAA6B;AAE7B;;;GAGG;AACU,QAAA,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,EAAkB;IAC/C,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAE/B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACpD,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,EAAkB;IACtD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE;aACX,OAAO,CAAC,0DAA0D,CAAC;aACnE,GAAG,EAA4C,CAAC;QACnD,OAAO,GAAG,EAAE,OAAO,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,EAAkB,EAAE,WAAmB;IACvE,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,kEAAkE;QAClE,mEAAmE;QACnE,mEAAmE;QACnE,EAAE,CAAC,IAAI,CAAC;;;;;;KAMP,CAAC,CAAC;QAEH,sDAAsD;QACtD,MAAM,KAAK,GACT,EAAE,CAAC,OAAO,CAAC,gDAAgD,CAAC,CAAC,GAAG,EACjE,CAAC,GAAG,CAAC;QACN,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,MAAM,IAAI,GAAG,EAAE;iBACZ,OAAO,CAAC,0DAA0D,CAAC;iBACnE,GAAG,EAAiE,CAAC;YAExE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CACvB,4EAA4E,CAC7E,CAAC;gBACF,MAAM,UAAU,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,SAAsE,EAAE,EAAE;oBAC3G,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;wBAC1B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;oBAC7C,CAAC;gBACH,CAAC,CAAC,CAAC;gBACH,UAAU,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QAED,mBAAmB;QACnB,EAAE,CAAC,OAAO,CACR,oLAAoL,CACrL,CAAC,GAAG,EAAE,CAAC;IACV,CAAC;AACH,CAAC"}

package/dist/spec/db/schema.sql

@@ -0,0 +1,117 @@
+-- Commit4Spec Schema for HomeGraph
+-- Version 2
+--
+-- Independent tables that coexist alongside HomeGraph's `nodes`/`edges`
+-- core graph. These tables form a three-layer Spec→Commit→CodeFragment
+-- relationship model — a higher-level semantic overlay on the code graph.
+--
+-- FTS5 uses a standalone virtual table (not external content) because
+-- Spec text needs CJK character-level segmentation before indexing.
+
+-- =============================================================================
+-- Entity Tables
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS spec_nodes (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    subtitles TEXT NOT NULL,        -- JSON array of markdown heading + preview
+    status TEXT NOT NULL DEFAULT 'active',  -- 'active' | 'deprecated'
+    version INTEGER NOT NULL DEFAULT 1,
+    file_path TEXT NOT NULL,
+    timestamp INTEGER NOT NULL      -- Unix epoch milliseconds
+);
+
+CREATE TABLE IF NOT EXISTS commit_nodes (
+    hash TEXT PRIMARY KEY,          -- Full 40-char commit hash
+    message TEXT NOT NULL,          -- First line of commit message
+    author TEXT NOT NULL,
+    timestamp INTEGER NOT NULL      -- Unix epoch milliseconds
+);
+
+CREATE TABLE IF NOT EXISTS code_fragment_nodes (
+    id TEXT PRIMARY KEY,            -- 12-char hex UUID prefix
+    change_type TEXT NOT NULL,      -- 'ADD' | 'MODIFY' | 'DELETE'
+    file_path TEXT NOT NULL,
+    start_line INTEGER NOT NULL,
+    end_line INTEGER NOT NULL,
+    code_diff TEXT NOT NULL         -- Unified diff text
+);
+
+-- =============================================================================
+-- Relation Tables
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS spec_commit_relations (
+    spec_id TEXT NOT NULL,
+    commit_hash TEXT NOT NULL,
+    relation_type TEXT NOT NULL,    -- 'GENERATE' | 'SUMMARIZED_FROM'
+    PRIMARY KEY (spec_id, commit_hash, relation_type),
+    FOREIGN KEY (spec_id) REFERENCES spec_nodes(id) ON DELETE CASCADE,
+    FOREIGN KEY (commit_hash) REFERENCES commit_nodes(hash) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS commit_fragment_relations (
+    commit_hash TEXT NOT NULL,
+    fragment_id TEXT NOT NULL,
+    PRIMARY KEY (commit_hash, fragment_id),
+    FOREIGN KEY (commit_hash) REFERENCES commit_nodes(hash) ON DELETE CASCADE,
+    FOREIGN KEY (fragment_id) REFERENCES code_fragment_nodes(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS spec_spec_relations (
+    source_id TEXT NOT NULL,
+    target_id TEXT NOT NULL,
+    relation_type TEXT NOT NULL,    -- 'SIMILAR_TO' | 'EVOLVED_FROM'
+    PRIMARY KEY (source_id, target_id, relation_type),
+    FOREIGN KEY (source_id) REFERENCES spec_nodes(id) ON DELETE CASCADE,
+    FOREIGN KEY (target_id) REFERENCES spec_nodes(id) ON DELETE CASCADE
+);
+
+-- =============================================================================
+-- Full-Text Search (standalone — CJK-segmented on insert)
+-- =============================================================================
+
+CREATE VIRTUAL TABLE IF NOT EXISTS specs_fts USING fts5(
+    id,
+    title,
+    subtitles
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS code_fragments_fts USING fts5(
+    id,
+    file_path,
+    code_diff
+);
+
+-- =============================================================================
+-- Indexes
+-- =============================================================================
+
+CREATE INDEX IF NOT EXISTS idx_spec_nodes_status ON spec_nodes(status);
+CREATE INDEX IF NOT EXISTS idx_spec_nodes_file_path ON spec_nodes(file_path);
+CREATE INDEX IF NOT EXISTS idx_commit_nodes_timestamp ON commit_nodes(timestamp);
+CREATE INDEX IF NOT EXISTS idx_code_fragment_file_path ON code_fragment_nodes(file_path);
+CREATE INDEX IF NOT EXISTS idx_code_fragment_path_lines ON code_fragment_nodes(file_path, start_line, end_line);
+CREATE INDEX IF NOT EXISTS idx_scr_spec_id ON spec_commit_relations(spec_id);
+CREATE INDEX IF NOT EXISTS idx_scr_commit_hash ON spec_commit_relations(commit_hash);
+CREATE INDEX IF NOT EXISTS idx_cfr_commit_hash ON commit_fragment_relations(commit_hash);
+CREATE INDEX IF NOT EXISTS idx_cfr_fragment_id ON commit_fragment_relations(fragment_id);
+CREATE INDEX IF NOT EXISTS idx_ssr_source ON spec_spec_relations(source_id);
+CREATE INDEX IF NOT EXISTS idx_ssr_target ON spec_spec_relations(target_id);
+
+-- =============================================================================
+-- Schema Version
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS spec_schema_versions (
+    version INTEGER PRIMARY KEY,
+    applied_at INTEGER NOT NULL,
+    description TEXT
+);
+
+INSERT OR IGNORE INTO spec_schema_versions (version, applied_at, description)
+VALUES (1, strftime('%s', 'now') * 1000, 'Initial Commit4Spec schema');
+
+INSERT OR IGNORE INTO spec_schema_versions (version, applied_at, description)
+VALUES (2, strftime('%s', 'now') * 1000, 'Add code_fragments_fts for content-based fragment search');

package/dist/spec/db/spec-node.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SpecNode CRUD — persistence operations for ``spec_nodes``.
+ *
+ * Every insert also updates the standalone FTS5 index with CJK-segmented
+ * text (see `fts.ts` for the segmentation logic).
+ */
+import { SqliteDatabase } from '../../db/sqlite-adapter';
+import { SpecNode } from '../types';
+/**
+ * Insert or replace a SpecNode. Also updates the standalone FTS5 index
+ * with CJK-segmented text.
+ */
+export declare function insertSpecNode(db: SqliteDatabase, node: SpecNode): SpecNode;
+/**
+ * Look up a SpecNode by primary key. Returns null when not found.
+ */
+export declare function findSpecById(db: SqliteDatabase, specId: string): SpecNode | null;
+/**
+ * Update the status of a Spec (e.g. mark as deprecated).
+ */
+export declare function updateSpecStatus(db: SqliteDatabase, specId: string, status: SpecNode['status']): void;
+/**
+ * Update the version field of a Spec.
+ */
+export declare function updateSpecVersion(db: SqliteDatabase, specId: string, version: number): void;
+/**
+ * Delete a Spec and its FTS5 entry.
+ */
+export declare function deleteSpec(db: SqliteDatabase, specId: string): void;
+/**
+ * List every spec, ordered by id.
+ */
+export declare function listAllSpecs(db: SqliteDatabase): SpecNode[];
+/**
+ * Count specs by status.
+ */
+export declare function countSpecsByStatus(db: SqliteDatabase): {
+    active: number;
+    deprecated: number;
+};
+//# sourceMappingURL=spec-node.d.ts.map

package/dist/spec/db/spec-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-node.d.ts","sourceRoot":"","sources":["../../../src/spec/db/spec-node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AA2CpC;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ,CA2B3E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAMhF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,CAErG;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE3F;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAGnE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,cAAc,GAAG,QAAQ,EAAE,CAK3D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,cAAc,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAW7F"}

package/dist/spec/db/spec-node.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * SpecNode CRUD — persistence operations for ``spec_nodes``.
+ *
+ * Every insert also updates the standalone FTS5 index with CJK-segmented
+ * text (see `fts.ts` for the segmentation logic).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.insertSpecNode = insertSpecNode;
+exports.findSpecById = findSpecById;
+exports.updateSpecStatus = updateSpecStatus;
+exports.updateSpecVersion = updateSpecVersion;
+exports.deleteSpec = deleteSpec;
+exports.listAllSpecs = listAllSpecs;
+exports.countSpecsByStatus = countSpecsByStatus;
+const fts_1 = require("./fts");
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function rowToSpec(row) {
+    let subtitles;
+    try {
+        subtitles = JSON.parse(row.subtitles || '[]');
+    }
+    catch {
+        subtitles = [];
+    }
+    return {
+        id: row.id,
+        title: row.title,
+        subtitles,
+        status: row.status,
+        version: row.version,
+        filePath: row.file_path,
+        timestamp: row.timestamp,
+    };
+}
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+/**
+ * Insert or replace a SpecNode. Also updates the standalone FTS5 index
+ * with CJK-segmented text.
+ */
+function insertSpecNode(db, node) {
+    const subtitlesJson = JSON.stringify(node.subtitles);
+    db.prepare(`
+    INSERT OR REPLACE INTO spec_nodes
+      (id, title, subtitles, status, version, file_path, timestamp)
+    VALUES (@id, @title, @subtitles, @status, @version, @filePath, @timestamp)
+  `).run({
+        id: node.id,
+        title: node.title,
+        subtitles: subtitlesJson,
+        status: node.status,
+        version: node.version,
+        filePath: node.filePath,
+        timestamp: node.timestamp,
+    });
+    // Update FTS5 index with CJK-segmented text
+    const segmentedTitle = (0, fts_1.segmentCjk)(node.title);
+    const segmentedSubtitles = (0, fts_1.segmentCjk)(subtitlesJson);
+    db.prepare('DELETE FROM specs_fts WHERE id = ?').run(node.id);
+    db.prepare('INSERT INTO specs_fts(id, title, subtitles) VALUES (?, ?, ?)').run(node.id, segmentedTitle, segmentedSubtitles);
+    return node;
+}
+/**
+ * Look up a SpecNode by primary key. Returns null when not found.
+ */
+function findSpecById(db, specId) {
+    const row = db.prepare('SELECT id, title, subtitles, status, version, file_path, timestamp FROM spec_nodes WHERE id = ?').get(specId);
+    return row ? rowToSpec(row) : null;
+}
+/**
+ * Update the status of a Spec (e.g. mark as deprecated).
+ */
+function updateSpecStatus(db, specId, status) {
+    db.prepare('UPDATE spec_nodes SET status = ? WHERE id = ?').run(status, specId);
+}
+/**
+ * Update the version field of a Spec.
+ */
+function updateSpecVersion(db, specId, version) {
+    db.prepare('UPDATE spec_nodes SET version = ? WHERE id = ?').run(version, specId);
+}
+/**
+ * Delete a Spec and its FTS5 entry.
+ */
+function deleteSpec(db, specId) {
+    db.prepare('DELETE FROM spec_nodes WHERE id = ?').run(specId);
+    db.prepare('DELETE FROM specs_fts WHERE id = ?').run(specId);
+}
+/**
+ * List every spec, ordered by id.
+ */
+function listAllSpecs(db) {
+    const rows = db.prepare('SELECT id, title, subtitles, status, version, file_path, timestamp FROM spec_nodes ORDER BY id').all();
+    return rows.map(rowToSpec);
+}
+/**
+ * Count specs by status.
+ */
+function countSpecsByStatus(db) {
+    const rows = db.prepare('SELECT status, COUNT(*) as cnt FROM spec_nodes GROUP BY status').all();
+    const counts = { active: 0, deprecated: 0 };
+    for (const row of rows) {
+        if (row.status === 'active')
+            counts.active = row.cnt;
+        else if (row.status === 'deprecated')
+            counts.deprecated = row.cnt;
+    }
+    return counts;
+}
+//# sourceMappingURL=spec-node.js.map

package/dist/spec/db/spec-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-node.js","sourceRoot":"","sources":["../../../src/spec/db/spec-node.ts"],"names":[],"mappings":"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"}

package/dist/spec/evolve/impact-locator.d.ts

@@ -0,0 +1,13 @@
+import { SqliteDatabase } from '../../db/sqlite-adapter';
+/**
+ * Find specs affected by the given list of file paths.
+ *
+ * Each file path should already be clean (no `a/` or `b/` prefix) — paths
+ * sourced from `DiffFragment.filePath` via diff-parser already have prefixes
+ * stripped.
+ *
+ * Queries the spec knowledge graph for specs whose code fragments match the
+ * path, returns deduplicated, alphabetically sorted spec IDs.
+ */
+export declare function locateAffectedSpecs(db: SqliteDatabase, filePaths: string[]): string[];
+//# sourceMappingURL=impact-locator.d.ts.map

package/dist/spec/evolve/impact-locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-locator.d.ts","sourceRoot":"","sources":["../../../src/spec/evolve/impact-locator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAGzD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,EAClB,SAAS,EAAE,MAAM,EAAE,GAClB,MAAM,EAAE,CAWV"}

package/dist/spec/evolve/impact-locator.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.locateAffectedSpecs = locateAffectedSpecs;
+const queries_1 = require("../graph/queries");
+/**
+ * Find specs affected by the given list of file paths.
+ *
+ * Each file path should already be clean (no `a/` or `b/` prefix) — paths
+ * sourced from `DiffFragment.filePath` via diff-parser already have prefixes
+ * stripped.
+ *
+ * Queries the spec knowledge graph for specs whose code fragments match the
+ * path, returns deduplicated, alphabetically sorted spec IDs.
+ */
+function locateAffectedSpecs(db, filePaths) {
+    const specIds = new Set();
+    for (const fp of filePaths) {
+        const matches = (0, queries_1.findSpecsByFragmentPath)(db, fp);
+        for (const specId of matches) {
+            specIds.add(specId);
+        }
+    }
+    return Array.from(specIds).sort();
+}
+//# sourceMappingURL=impact-locator.js.map

package/dist/spec/evolve/impact-locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-locator.js","sourceRoot":"","sources":["../../../src/spec/evolve/impact-locator.ts"],"names":[],"mappings":";;AAaA,kDAcC;AA1BD,8CAA2D;AAE3D;;;;;;;;;GASG;AACH,SAAgB,mBAAmB,CACjC,EAAkB,EAClB,SAAmB;IAEnB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,IAAA,iCAAuB,EAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAChD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;AACpC,CAAC"}