@vpxa/aikit 0.1.82 → 0.1.84

package/packages/store/dist/index.d.ts

@@ -251,18 +251,64 @@ declare class LanceStore implements IKnowledgeStore {
   private fromLanceRecord;
 }
 //#endregion
+//#region packages/store/src/sqlite-adapter.d.ts
+/**
+ * SQLite adapter abstraction — allows swapping between better-sqlite3 (native)
+ * and sql.js (WASM) without changing consumer code.
+ *
+ * Primary adapter is configurable; the other serves as automatic fallback
+ * when the primary fails to load (e.g. native binary missing on the platform).
+ */
+type SqliteAdapterType = 'better-sqlite3' | 'sql.js';
+interface ISqliteAdapter {
+  /** Which adapter implementation is active */
+  readonly type: SqliteAdapterType;
+  /** Open or create the database at the given file path */
+  open(dbPath: string): Promise<void>;
+  /** Execute DDL or multi-statement SQL (CREATE TABLE, BEGIN, COMMIT, etc.) */
+  exec(sql: string): void;
+  /** Set a PRAGMA value */
+  pragma(pragma: string): void;
+  /** Run a parameterized SELECT, return all rows */
+  queryAll<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+  /** Run a parameterized INSERT/UPDATE/DELETE */
+  run(sql: string, params?: unknown[]): void;
+  /** Flush to disk — no-op for file-backed engines, required for in-memory engines */
+  flush(): void;
+  /** Close the database connection */
+  close(): void;
+}
+interface SqliteAdapterOptions {
+  /** Which adapter to try first. Default: 'better-sqlite3' (lower memory usage) */
+  primary?: SqliteAdapterType;
+}
+/**
+ * Create a SQLite adapter with automatic fallback.
+ *
+ * Tries the primary adapter first; if it fails to load (missing native binary,
+ * unsupported platform, etc.), falls back to the other adapter transparently.
+ */
+declare function createSqliteAdapter(dbPath: string, options?: SqliteAdapterOptions): Promise<ISqliteAdapter>;
+//#endregion
 //#region packages/store/src/sqlite-graph-store.d.ts
 declare class SqliteGraphStore implements IGraphStore {
-  private db;
+  private adapter;
   private readonly dbPath;
+  private readonly adapterOptions?;
   constructor(options?: {
     path?: string;
+    sqliteAdapter?: SqliteAdapterOptions;
   });
   initialize(): Promise<void>;
-  private configureDb;
+  private configureAdapter;
   private createTables;
   private migrateSchema;
-  private getDb;
+  private getAdapter;
+  /**
+   * Ensure the adapter is open, lazily re-opening after close().
+   * Must be called from any public async method that may be invoked after close().
+   */
+  private ensureOpen;
   private query;
   private run;
   upsertNode(node: GraphNode): Promise<void>;
@@ -309,4 +355,4 @@ interface StoreConfig {
 }
 declare function createStore(config: StoreConfig): Promise<IKnowledgeStore>;
 //#endregion
-export { type DepthGroupedResult, type GraphEdge, type GraphNode, type GraphStats, type GraphTraversalOptions, type GraphTraversalResult, type GraphValidationResult, type IGraphStore, type IKnowledgeStore, LanceStore, type ProcessInfo, type SearchOptions, SqliteGraphStore, type StoreBackend, type StoreConfig, type Symbol360, createStore };
+export { type DepthGroupedResult, type GraphEdge, type GraphNode, type GraphStats, type GraphTraversalOptions, type GraphTraversalResult, type GraphValidationResult, type IGraphStore, type IKnowledgeStore, type ISqliteAdapter, LanceStore, type ProcessInfo, type SearchOptions, type SqliteAdapterOptions, type SqliteAdapterType, SqliteGraphStore, type StoreBackend, type StoreConfig, type Symbol360, createSqliteAdapter, createStore };

package/packages/store/dist/index.js

@@ -1,4 +1,4 @@
-import{t as e}from"./lance-store-jdHZp-V4.js";import{AIKIT_PATHS as t}from"../../core/dist/index.js";import{existsSync as n,mkdirSync as r}from"node:fs";import{dirname as i,join as a}from"node:path";import o from"better-sqlite3";var s=class{db=null;dbPath;constructor(e){let n=e?.path??t.data;this.dbPath=a(n,`graph.db`)}async initialize(){let e=i(this.dbPath);n(e)||r(e,{recursive:!0}),this.db=new o(this.dbPath),this.configureDb(this.db),this.createTables(this.db),this.migrateSchema(this.db)}configureDb(e){e.pragma(`journal_mode = WAL`),e.pragma(`foreign_keys = ON`)}createTables(e){e.exec(`
+import{t as e}from"./lance-store-jdHZp-V4.js";import{AIKIT_PATHS as t}from"../../core/dist/index.js";import{existsSync as n,mkdirSync as r,readFileSync as i,writeFileSync as a}from"node:fs";import{dirname as o,join as s}from"node:path";var c=class{type=`better-sqlite3`;db=null;async open(e){let t=(await import(`better-sqlite3`)).default;this.db=new t(e)}exec(e){this.getDb().exec(e)}pragma(e){this.getDb().pragma(e)}queryAll(e,t=[]){return this.getDb().prepare(e).all(...t)}run(e,t=[]){this.getDb().prepare(e).run(...t)}flush(){}close(){this.db&&=(this.db.close(),null)}getDb(){if(!this.db)throw Error(`BetterSqliteAdapter: database not opened`);return this.db}},l=class{type=`sql.js`;db=null;dbPath=``;dirty=!1;inTransaction=!1;async open(e){this.dbPath=e;let t=(await import(`sql.js`)).default,r=await t();if(n(e)){let t=i(e);this.db=new r.Database(t)}else this.db=new r.Database}exec(e){let t=e.trimStart().toUpperCase();t.startsWith(`BEGIN`)?this.inTransaction=!0:(t.startsWith(`COMMIT`)||t.startsWith(`ROLLBACK`))&&(this.inTransaction=!1),this.getDb().run(e),this.dirty=!0}pragma(e){this.getDb().exec(`PRAGMA ${e}`)}queryAll(e,t=[]){let n=this.getDb().prepare(e);t.length>0&&n.bind(t);let r=[];for(;n.step();)r.push(n.getAsObject());return n.free(),r}run(e,t=[]){let n=this.getDb(),r=e.trimStart().toUpperCase(),i=!this.inTransaction&&(r.startsWith(`INSERT`)||r.startsWith(`UPDATE`));if(i&&n.run(`SAVEPOINT fk_check`),t.length>0){let r=n.prepare(e);try{r.bind(t),r.step()}finally{r.free()}}else n.run(e);if(i){if(n.exec(`PRAGMA foreign_key_check`).length>0)throw n.run(`ROLLBACK TO fk_check`),n.run(`RELEASE fk_check`),Error(`FOREIGN KEY constraint failed`);n.run(`RELEASE fk_check`)}this.dirty=!0}flush(){if(!this.dirty||!this.db)return;let e=this.db.export();a(this.dbPath,Buffer.from(e)),this.dirty=!1}close(){this.db&&=(this.flush(),this.db.close(),null)}getDb(){if(!this.db)throw Error(`SqlJsAdapter: database not opened`);return this.db}};async function u(e,t){let n=t?.primary??`better-sqlite3`,r=[n,n===`better-sqlite3`?`sql.js`:`better-sqlite3`];for(let t of r)try{let r=t===`better-sqlite3`?new c:new l;return await r.open(e),t!==n&&console.error(`[aikit] SQLite adapter: primary "${n}" unavailable, using fallback "${t}"`),r}catch(e){let n=e instanceof Error?e.message:String(e);console.error(`[aikit] SQLite adapter "${t}" failed to load: ${n}`)}throw Error(`[aikit] No SQLite adapter available. Tried: ${r.join(`, `)}. Install either better-sqlite3 or sql.js.`)}var d=class{adapter=null;dbPath;adapterOptions;constructor(e){let n=e?.path??t.data;this.dbPath=s(n,`graph.db`),this.adapterOptions=e?.sqliteAdapter}async initialize(){let e=o(this.dbPath);n(e)||r(e,{recursive:!0}),this.adapter=await u(this.dbPath,this.adapterOptions),this.configureAdapter(this.adapter),this.createTables(this.adapter),this.migrateSchema(this.adapter),this.adapter.flush()}configureAdapter(e){e.pragma(`journal_mode = WAL`),e.pragma(`foreign_keys = ON`)}createTables(e){e.exec(`
       CREATE TABLE IF NOT EXISTS nodes (
         id TEXT PRIMARY KEY,
         type TEXT NOT NULL,
@@ -39,37 +39,37 @@ import{t as e}from"./lance-store-jdHZp-V4.js";import{AIKIT_PATHS as t}from"../..
         FOREIGN KEY (process_id) REFERENCES processes(id) ON DELETE CASCADE,
         FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
       )
-    `),e.exec(`CREATE INDEX IF NOT EXISTS idx_process_steps_node ON process_steps(node_id)`)}migrateSchema(e){for(let t of[`ALTER TABLE edges ADD COLUMN confidence REAL DEFAULT 1.0`,`ALTER TABLE nodes ADD COLUMN community TEXT`])try{e.exec(t)}catch{}e.exec(`CREATE INDEX IF NOT EXISTS idx_nodes_community ON nodes(community)`)}getDb(){return this.db||(this.db=new o(this.dbPath),this.configureDb(this.db)),this.db}query(e,t=[]){return this.getDb().prepare(e).all(...t)}run(e,t=[]){this.getDb().prepare(e).run(...t)}async upsertNode(e){this.run(`INSERT INTO nodes (id, type, name, properties, source_record_id, source_path, created_at, community)
+    `),e.exec(`CREATE INDEX IF NOT EXISTS idx_process_steps_node ON process_steps(node_id)`)}migrateSchema(e){for(let t of[`ALTER TABLE edges ADD COLUMN confidence REAL DEFAULT 1.0`,`ALTER TABLE nodes ADD COLUMN community TEXT`])try{e.exec(t)}catch{}e.exec(`CREATE INDEX IF NOT EXISTS idx_nodes_community ON nodes(community)`)}getAdapter(){if(!this.adapter)throw Error(`SqliteGraphStore not initialized — call initialize() first`);return this.adapter}async ensureOpen(){this.adapter||(this.adapter=await u(this.dbPath,this.adapterOptions),this.configureAdapter(this.adapter))}query(e,t=[]){return this.getAdapter().queryAll(e,t)}run(e,t=[]){this.getAdapter().run(e,t)}async upsertNode(e){await this.ensureOpen(),this.run(`INSERT INTO nodes (id, type, name, properties, source_record_id, source_path, created_at, community)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(id) DO UPDATE SET
          type = excluded.type, name = excluded.name, properties = excluded.properties,
          source_record_id = excluded.source_record_id, source_path = excluded.source_path,
-         community = excluded.community`,[e.id,e.type,e.name,JSON.stringify(e.properties),e.sourceRecordId??null,e.sourcePath??null,e.createdAt??new Date().toISOString(),e.community??null])}async upsertEdge(e){this.run(`INSERT INTO edges (id, from_id, to_id, type, weight, confidence, properties)
+         community = excluded.community`,[e.id,e.type,e.name,JSON.stringify(e.properties),e.sourceRecordId??null,e.sourcePath??null,e.createdAt??new Date().toISOString(),e.community??null]),this.getAdapter().flush()}async upsertEdge(e){await this.ensureOpen(),this.run(`INSERT INTO edges (id, from_id, to_id, type, weight, confidence, properties)
        VALUES (?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(id) DO UPDATE SET
          from_id = excluded.from_id, to_id = excluded.to_id,
-         type = excluded.type, weight = excluded.weight, confidence = excluded.confidence, properties = excluded.properties`,[e.id,e.fromId,e.toId,e.type,e.weight??1,e.confidence??1,JSON.stringify(e.properties??{})])}async upsertNodes(e){if(e.length===0)return;let t=this.getDb();t.exec(`BEGIN TRANSACTION`);try{for(let t of e)this.run(`INSERT INTO nodes (id, type, name, properties, source_record_id, source_path, created_at, community)
+         type = excluded.type, weight = excluded.weight, confidence = excluded.confidence, properties = excluded.properties`,[e.id,e.fromId,e.toId,e.type,e.weight??1,e.confidence??1,JSON.stringify(e.properties??{})]),this.getAdapter().flush()}async upsertNodes(e){if(e.length===0)return;await this.ensureOpen();let t=this.getAdapter();t.exec(`BEGIN TRANSACTION`);try{for(let t of e)this.run(`INSERT INTO nodes (id, type, name, properties, source_record_id, source_path, created_at, community)
            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT(id) DO UPDATE SET
              type = excluded.type, name = excluded.name, properties = excluded.properties,
              source_record_id = excluded.source_record_id, source_path = excluded.source_path,
-             community = excluded.community`,[t.id,t.type,t.name,JSON.stringify(t.properties),t.sourceRecordId??null,t.sourcePath??null,t.createdAt??new Date().toISOString(),t.community??null]);t.exec(`COMMIT`)}catch(e){throw t.exec(`ROLLBACK`),e}}async upsertEdges(e){if(e.length===0)return;let t=this.getDb();t.pragma(`foreign_keys = OFF`),t.exec(`BEGIN TRANSACTION`);try{for(let t of e)this.run(`INSERT INTO edges (id, from_id, to_id, type, weight, confidence, properties)
+             community = excluded.community`,[t.id,t.type,t.name,JSON.stringify(t.properties),t.sourceRecordId??null,t.sourcePath??null,t.createdAt??new Date().toISOString(),t.community??null]);t.exec(`COMMIT`),t.flush()}catch(e){throw t.exec(`ROLLBACK`),e}}async upsertEdges(e){if(e.length===0)return;await this.ensureOpen();let t=this.getAdapter();t.pragma(`foreign_keys = OFF`),t.exec(`BEGIN TRANSACTION`);try{for(let t of e)this.run(`INSERT INTO edges (id, from_id, to_id, type, weight, confidence, properties)
            VALUES (?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT(id) DO UPDATE SET
              from_id = excluded.from_id, to_id = excluded.to_id,
-             type = excluded.type, weight = excluded.weight, confidence = excluded.confidence, properties = excluded.properties`,[t.id,t.fromId,t.toId,t.type,t.weight??1,t.confidence??1,JSON.stringify(t.properties??{})]);t.exec(`COMMIT`)}catch(e){throw t.exec(`ROLLBACK`),e}finally{t.pragma(`foreign_keys = ON`)}}async getNode(e){let t=this.query(`SELECT * FROM nodes WHERE id = ?`,[e]);return t.length>0?l(t[0]):null}async getNeighbors(e,t){let n=t?.direction??`both`,r=t?.edgeType,i=t?.limit??50,a=[],o=[],s=new Set;if(n===`outgoing`||n===`both`){let t=`
+             type = excluded.type, weight = excluded.weight, confidence = excluded.confidence, properties = excluded.properties`,[t.id,t.fromId,t.toId,t.type,t.weight??1,t.confidence??1,JSON.stringify(t.properties??{})]);t.exec(`COMMIT`),t.flush()}catch(e){throw t.exec(`ROLLBACK`),e}finally{t.pragma(`foreign_keys = ON`)}}async getNode(e){await this.ensureOpen();let t=this.query(`SELECT * FROM nodes WHERE id = ?`,[e]);return t.length>0?p(t[0]):null}async getNeighbors(e,t){await this.ensureOpen();let n=t?.direction??`both`,r=t?.edgeType,i=t?.limit??50,a=[],o=[],s=new Set;if(n===`outgoing`||n===`both`){let t=`
           SELECT e.id AS edge_id, e.from_id, e.to_id, e.type AS edge_type, e.weight,
             e.confidence AS edge_confidence, e.properties AS edge_props,
              n.id AS node_id, n.type AS node_type, n.name AS node_name, n.properties AS node_props,
             n.source_record_id AS node_src_rec, n.source_path AS node_src_path,
             n.created_at AS node_created, n.community AS node_community
-      FROM edges e JOIN nodes n ON e.to_id = n.id WHERE e.from_id = ?`,n=[e];r&&(t+=` AND e.type = ?`,n.push(r)),t+=` LIMIT ?`,n.push(i);let c=this.query(t,n);for(let e of c)o.push(d(e)),s.has(e.node_id)||(s.add(e.node_id),a.push(f(e)))}if(n===`incoming`||n===`both`){let t=`
+      FROM edges e JOIN nodes n ON e.to_id = n.id WHERE e.from_id = ?`,n=[e];r&&(t+=` AND e.type = ?`,n.push(r)),t+=` LIMIT ?`,n.push(i);let c=this.query(t,n);for(let e of c)o.push(h(e)),s.has(e.node_id)||(s.add(e.node_id),a.push(g(e)))}if(n===`incoming`||n===`both`){let t=`
           SELECT e.id AS edge_id, e.from_id, e.to_id, e.type AS edge_type, e.weight,
             e.confidence AS edge_confidence, e.properties AS edge_props,
              n.id AS node_id, n.type AS node_type, n.name AS node_name, n.properties AS node_props,
             n.source_record_id AS node_src_rec, n.source_path AS node_src_path,
             n.created_at AS node_created, n.community AS node_community
-      FROM edges e JOIN nodes n ON e.from_id = n.id WHERE e.to_id = ?`,n=[e];r&&(t+=` AND e.type = ?`,n.push(r)),t+=` LIMIT ?`,n.push(i);let c=this.query(t,n);for(let e of c)o.push(d(e)),s.has(e.node_id)||(s.add(e.node_id),a.push(f(e)))}return{nodes:a,edges:o}}async traverse(e,t){let n=t?.maxDepth??2,r=t?.direction??`both`,i=t?.edgeType,a=t?.limit??50,o=new Map,s=new Map,c=new Set,l=[{nodeId:e,depth:0}];for(;l.length>0&&o.size<a;){let e=l.shift();if(!e||c.has(e.nodeId)||e.depth>n)continue;c.add(e.nodeId);let t=await this.getNeighbors(e.nodeId,{direction:r,edgeType:i,limit:a-o.size});for(let r of t.nodes)o.has(r.id)||(o.set(r.id,r),e.depth+1<n&&l.push({nodeId:r.id,depth:e.depth+1}));for(let e of t.edges)s.set(e.id,e)}return{nodes:[...o.values()],edges:[...s.values()]}}async findNodes(e){let t=[],n=[];e.type&&(t.push(`type = ?`),n.push(e.type)),e.namePattern&&(t.push(`name LIKE ?`),n.push(`%${e.namePattern}%`)),e.sourcePath&&(t.push(`source_path = ?`),n.push(e.sourcePath));let r=t.length>0?`WHERE ${t.join(` AND `)}`:``,i=e.limit??100;return this.query(`SELECT * FROM nodes ${r} LIMIT ?`,[...n,i]).map(e=>l(e))}async findEdges(e){let t=[],n=[];e.type&&(t.push(`type = ?`),n.push(e.type)),e.fromId&&(t.push(`from_id = ?`),n.push(e.fromId)),e.toId&&(t.push(`to_id = ?`),n.push(e.toId));let r=t.length>0?`WHERE ${t.join(` AND `)}`:``,i=e.limit??100;return this.query(`SELECT * FROM edges ${r} LIMIT ?`,[...n,i]).map(e=>u(e))}async deleteNode(e){let t=this.getDb();t.exec(`BEGIN TRANSACTION`);try{this.run(`DELETE FROM edges WHERE from_id = ? OR to_id = ?`,[e,e]),this.run(`DELETE FROM nodes WHERE id = ?`,[e]),t.exec(`COMMIT`)}catch(e){throw t.exec(`ROLLBACK`),e}}async deleteBySourcePath(e){let t=this.query(`SELECT id FROM nodes WHERE source_path = ?`,[e]);if(t.length===0)return 0;let n=this.getDb();n.exec(`BEGIN TRANSACTION`);try{for(let e of t)this.run(`DELETE FROM edges WHERE from_id = ? OR to_id = ?`,[e.id,e.id]);this.run(`DELETE FROM nodes WHERE source_path = ?`,[e]),n.exec(`COMMIT`)}catch(e){throw n.exec(`ROLLBACK`),e}return t.length}async clear(){this.run(`DELETE FROM process_steps`),this.run(`DELETE FROM processes`),this.run(`DELETE FROM edges`),this.run(`DELETE FROM nodes`)}async getStats(){let e=this.query(`SELECT COUNT(*) as count FROM nodes`)[0]?.count??0,t=this.query(`SELECT COUNT(*) as count FROM edges`)[0]?.count??0,n=this.query(`SELECT type, COUNT(*) as count FROM nodes GROUP BY type`),r={};for(let e of n)r[e.type]=e.count;let i=this.query(`SELECT type, COUNT(*) as count FROM edges GROUP BY type`),a={};for(let e of i)a[e.type]=e.count;return{nodeCount:e,edgeCount:t,nodeTypes:r,edgeTypes:a}}async validate(){let e=await this.getStats(),t=this.query(`SELECT e.id AS edgeId,
+      FROM edges e JOIN nodes n ON e.from_id = n.id WHERE e.to_id = ?`,n=[e];r&&(t+=` AND e.type = ?`,n.push(r)),t+=` LIMIT ?`,n.push(i);let c=this.query(t,n);for(let e of c)o.push(h(e)),s.has(e.node_id)||(s.add(e.node_id),a.push(g(e)))}return{nodes:a,edges:o}}async traverse(e,t){await this.ensureOpen();let n=t?.maxDepth??2,r=t?.direction??`both`,i=t?.edgeType,a=t?.limit??50,o=new Map,s=new Map,c=new Set,l=[{nodeId:e,depth:0}];for(;l.length>0&&o.size<a;){let e=l.shift();if(!e||c.has(e.nodeId)||e.depth>n)continue;c.add(e.nodeId);let t=await this.getNeighbors(e.nodeId,{direction:r,edgeType:i,limit:a-o.size});for(let r of t.nodes)o.has(r.id)||(o.set(r.id,r),e.depth+1<n&&l.push({nodeId:r.id,depth:e.depth+1}));for(let e of t.edges)s.set(e.id,e)}return{nodes:[...o.values()],edges:[...s.values()]}}async findNodes(e){await this.ensureOpen();let t=[],n=[];e.type&&(t.push(`type = ?`),n.push(e.type)),e.namePattern&&(t.push(`name LIKE ?`),n.push(`%${e.namePattern}%`)),e.sourcePath&&(t.push(`source_path = ?`),n.push(e.sourcePath));let r=t.length>0?`WHERE ${t.join(` AND `)}`:``,i=e.limit??100;return this.query(`SELECT * FROM nodes ${r} LIMIT ?`,[...n,i]).map(e=>p(e))}async findEdges(e){await this.ensureOpen();let t=[],n=[];e.type&&(t.push(`type = ?`),n.push(e.type)),e.fromId&&(t.push(`from_id = ?`),n.push(e.fromId)),e.toId&&(t.push(`to_id = ?`),n.push(e.toId));let r=t.length>0?`WHERE ${t.join(` AND `)}`:``,i=e.limit??100;return this.query(`SELECT * FROM edges ${r} LIMIT ?`,[...n,i]).map(e=>m(e))}async deleteNode(e){await this.ensureOpen();let t=this.getAdapter();t.exec(`BEGIN TRANSACTION`);try{this.run(`DELETE FROM edges WHERE from_id = ? OR to_id = ?`,[e,e]),this.run(`DELETE FROM nodes WHERE id = ?`,[e]),t.exec(`COMMIT`),t.flush()}catch(e){throw t.exec(`ROLLBACK`),e}}async deleteBySourcePath(e){await this.ensureOpen();let t=this.query(`SELECT id FROM nodes WHERE source_path = ?`,[e]);if(t.length===0)return 0;let n=this.getAdapter();n.exec(`BEGIN TRANSACTION`);try{for(let e of t)this.run(`DELETE FROM edges WHERE from_id = ? OR to_id = ?`,[e.id,e.id]);this.run(`DELETE FROM nodes WHERE source_path = ?`,[e]),n.exec(`COMMIT`),n.flush()}catch(e){throw n.exec(`ROLLBACK`),e}return t.length}async clear(){await this.ensureOpen(),this.run(`DELETE FROM process_steps`),this.run(`DELETE FROM processes`),this.run(`DELETE FROM edges`),this.run(`DELETE FROM nodes`),this.getAdapter().flush()}async getStats(){await this.ensureOpen();let e=this.query(`SELECT COUNT(*) as count FROM nodes`)[0]?.count??0,t=this.query(`SELECT COUNT(*) as count FROM edges`)[0]?.count??0,n=this.query(`SELECT type, COUNT(*) as count FROM nodes GROUP BY type`),r={};for(let e of n)r[e.type]=e.count;let i=this.query(`SELECT type, COUNT(*) as count FROM edges GROUP BY type`),a={};for(let e of i)a[e.type]=e.count;return{nodeCount:e,edgeCount:t,nodeTypes:r,edgeTypes:a}}async validate(){await this.ensureOpen();let e=await this.getStats(),t=this.query(`SELECT e.id AS edgeId,
               CASE
                 WHEN n1.id IS NULL THEN e.from_id
                 WHEN n2.id IS NULL THEN e.to_id
@@ -81,10 +81,10 @@ import{t as e}from"./lance-store-jdHZp-V4.js";import{AIKIT_PATHS as t}from"../..
        FROM nodes n
        LEFT JOIN edges e1 ON n.id = e1.from_id
        LEFT JOIN edges e2 ON n.id = e2.to_id
-       WHERE e1.id IS NULL AND e2.id IS NULL`).map(e=>e.id);return{valid:t.length===0,orphanNodes:n,danglingEdges:t,stats:e}}async setNodeCommunity(e,t){this.run(`UPDATE nodes SET community = ? WHERE id = ?`,[t,e])}async detectCommunities(){let e=this.query(`SELECT id FROM nodes`),t=new Map;for(let n of e)t.set(n.id,n.id);for(let n=0;n<10;n++){let n=!1,r=new Map(t);for(let i of e){let e=this.query(`SELECT to_id AS neighbor_id FROM edges WHERE from_id = ?
+       WHERE e1.id IS NULL AND e2.id IS NULL`).map(e=>e.id);return{valid:t.length===0,orphanNodes:n,danglingEdges:t,stats:e}}async setNodeCommunity(e,t){await this.ensureOpen(),this.run(`UPDATE nodes SET community = ? WHERE id = ?`,[t,e]),this.getAdapter().flush()}async detectCommunities(){await this.ensureOpen();let e=this.query(`SELECT id FROM nodes`),t=new Map;for(let n of e)t.set(n.id,n.id);for(let n=0;n<10;n++){let n=!1,r=new Map(t);for(let i of e){let e=this.query(`SELECT to_id AS neighbor_id FROM edges WHERE from_id = ?
            UNION
-           SELECT from_id AS neighbor_id FROM edges WHERE to_id = ?`,[i.id,i.id]),a=new Map,o=t.get(i.id)??i.id;a.set(o,1);for(let n of e){let e=t.get(n.neighbor_id)??n.neighbor_id;a.set(e,(a.get(e)??0)+1)}let s=o,c=0;for(let[e,t]of a)(t>c||t===c&&e<s)&&(c=t,s=e);o!==s&&(r.set(i.id,s),n=!0)}t.clear();for(let[e,n]of r)t.set(e,n);if(!n)break}let n=this.getDb();n.exec(`BEGIN TRANSACTION`);try{for(let[e,n]of t)this.run(`UPDATE nodes SET community = ? WHERE id = ?`,[n,e]);n.exec(`COMMIT`)}catch(e){throw n.exec(`ROLLBACK`),e}let r={};for(let[e,n]of t)r[n]||(r[n]=[]),r[n].push(e);return r}async traceProcess(e,t){let n=[],r=new Set,i=[e];for(;i.length>0;){let e=i.shift();if(!e||r.has(e))continue;r.add(e),n.push(e);let t=this.query(`SELECT to_id FROM edges WHERE from_id = ? AND type = 'calls'`,[e]);for(let e of t)r.has(e.to_id)||i.push(e.to_id)}let a=`proc_${Date.now()}_${Math.random().toString(36).slice(2,8)}`,o=new Date().toISOString(),s=this.getDb();s.exec(`BEGIN TRANSACTION`);try{this.run(`INSERT INTO processes (id, entry_node_id, label, properties, created_at)
-         VALUES (?, ?, ?, '{}', ?)`,[a,e,t,o]);for(let e=0;e<n.length;e++)this.run(`INSERT INTO process_steps (process_id, node_id, step_order) VALUES (?, ?, ?)`,[a,n[e],e]);s.exec(`COMMIT`)}catch(e){throw s.exec(`ROLLBACK`),e}return{id:a,entryNodeId:e,label:t,properties:{},steps:n,createdAt:o}}async getProcesses(e){let t;t=e?this.query(`SELECT DISTINCT p.id, p.entry_node_id, p.label, p.properties, p.created_at
+           SELECT from_id AS neighbor_id FROM edges WHERE to_id = ?`,[i.id,i.id]),a=new Map,o=t.get(i.id)??i.id;a.set(o,1);for(let n of e){let e=t.get(n.neighbor_id)??n.neighbor_id;a.set(e,(a.get(e)??0)+1)}let s=o,c=0;for(let[e,t]of a)(t>c||t===c&&e<s)&&(c=t,s=e);o!==s&&(r.set(i.id,s),n=!0)}t.clear();for(let[e,n]of r)t.set(e,n);if(!n)break}let n=this.getAdapter();n.exec(`BEGIN TRANSACTION`);try{for(let[e,n]of t)this.run(`UPDATE nodes SET community = ? WHERE id = ?`,[n,e]);n.exec(`COMMIT`),n.flush()}catch(e){throw n.exec(`ROLLBACK`),e}let r={};for(let[e,n]of t)r[n]||(r[n]=[]),r[n].push(e);return r}async traceProcess(e,t){await this.ensureOpen();let n=[],r=new Set,i=[e];for(;i.length>0;){let e=i.shift();if(!e||r.has(e))continue;r.add(e),n.push(e);let t=this.query(`SELECT to_id FROM edges WHERE from_id = ? AND type = 'calls'`,[e]);for(let e of t)r.has(e.to_id)||i.push(e.to_id)}let a=`proc_${Date.now()}_${Math.random().toString(36).slice(2,8)}`,o=new Date().toISOString(),s=this.getAdapter();s.exec(`BEGIN TRANSACTION`);try{this.run(`INSERT INTO processes (id, entry_node_id, label, properties, created_at)
+         VALUES (?, ?, ?, '{}', ?)`,[a,e,t,o]);for(let e=0;e<n.length;e++)this.run(`INSERT INTO process_steps (process_id, node_id, step_order) VALUES (?, ?, ?)`,[a,n[e],e]);s.exec(`COMMIT`),s.flush()}catch(e){throw s.exec(`ROLLBACK`),e}return{id:a,entryNodeId:e,label:t,properties:{},steps:n,createdAt:o}}async getProcesses(e){await this.ensureOpen();let t;t=e?this.query(`SELECT DISTINCT p.id, p.entry_node_id, p.label, p.properties, p.created_at
          FROM processes p
          JOIN process_steps ps ON p.id = ps.process_id
-         WHERE ps.node_id = ?`,[e]):this.query(`SELECT * FROM processes`);let n=[];for(let e of t){let t=this.query(`SELECT node_id FROM process_steps WHERE process_id = ? ORDER BY step_order`,[e.id]);n.push({id:e.id,entryNodeId:e.entry_node_id,label:e.label,properties:c(e.properties),steps:t.map(e=>e.node_id),createdAt:e.created_at})}return n}async deleteProcess(e){let t=this.getDb();t.exec(`BEGIN TRANSACTION`);try{this.run(`DELETE FROM process_steps WHERE process_id = ?`,[e]),this.run(`DELETE FROM processes WHERE id = ?`,[e]),t.exec(`COMMIT`)}catch(e){throw t.exec(`ROLLBACK`),e}}async depthGroupedTraversal(e,t=3,n){let r=n?.direction??`both`,i=n?.edgeType,a=n?.limit??100,o={},s=new Set;s.add(e);let c=[e];for(let e=1;e<=t;e++){let t=[],n=[];for(let e of c){let o=await this.getNeighbors(e,{direction:r,edgeType:i,limit:a});for(let e of o.nodes)s.has(e.id)||(s.add(e.id),t.push(e.id),n.push(e))}if(n.length>0&&(o[e]=n),c=t,c.length===0||s.size>=a)break}return o}async getCohesionScore(e){let t=this.query(`SELECT id FROM nodes WHERE community = ?`,[e]);if(t.length===0)return 0;let n=new Set(t.map(e=>e.id)),r=t.map(()=>`?`).join(`,`),i=t.map(e=>e.id),a=this.query(`SELECT from_id, to_id FROM edges WHERE from_id IN (${r}) OR to_id IN (${r})`,[...i,...i]);if(a.length===0)return 0;let o=0;for(let e of a)n.has(e.from_id)&&n.has(e.to_id)&&o++;return o/a.length}async getSymbol360(e){let t=await this.getNode(e);if(!t)throw Error(`Node '${e}' not found`);let n=await this.findEdges({toId:e}),r=await this.findEdges({fromId:e}),i=await this.getProcesses(e);return{node:t,incoming:n,outgoing:r,community:t.community??null,processes:i}}async close(){this.db&&=(this.db.close(),null)}};function c(e){if(!e)return{};try{return JSON.parse(e)}catch{return{}}}function l(e){return{id:e.id,type:e.type,name:e.name,properties:c(e.properties),sourceRecordId:e.source_record_id??void 0,sourcePath:e.source_path??void 0,createdAt:e.created_at,community:e.community??void 0}}function u(e){return{id:e.id,fromId:e.from_id,toId:e.to_id,type:e.type,weight:e.weight??1,confidence:e.confidence??1,properties:c(e.properties)}}function d(e){return{id:e.edge_id,fromId:e.from_id,toId:e.to_id,type:e.edge_type,weight:e.weight??1,confidence:e.edge_confidence??1,properties:c(e.edge_props??`{}`)}}function f(e){return{id:e.node_id,type:e.node_type,name:e.node_name,properties:c(e.node_props??`{}`),sourceRecordId:e.node_src_rec??void 0,sourcePath:e.node_src_path??void 0,createdAt:e.node_created,community:e.node_community??void 0}}async function p(e){switch(e.backend){case`lancedb`:{let{LanceStore:t}=await import(`./lance-store-jdHZp-V4.js`).then(e=>e.n);return new t({path:e.path})}default:throw Error(`Unknown store backend: "${e.backend}". Supported: lancedb`)}}export{e as LanceStore,s as SqliteGraphStore,p as createStore};
+         WHERE ps.node_id = ?`,[e]):this.query(`SELECT * FROM processes`);let n=[];for(let e of t){let t=this.query(`SELECT node_id FROM process_steps WHERE process_id = ? ORDER BY step_order`,[e.id]);n.push({id:e.id,entryNodeId:e.entry_node_id,label:e.label,properties:f(e.properties),steps:t.map(e=>e.node_id),createdAt:e.created_at})}return n}async deleteProcess(e){await this.ensureOpen();let t=this.getAdapter();t.exec(`BEGIN TRANSACTION`);try{this.run(`DELETE FROM process_steps WHERE process_id = ?`,[e]),this.run(`DELETE FROM processes WHERE id = ?`,[e]),t.exec(`COMMIT`),t.flush()}catch(e){throw t.exec(`ROLLBACK`),e}}async depthGroupedTraversal(e,t=3,n){await this.ensureOpen();let r=n?.direction??`both`,i=n?.edgeType,a=n?.limit??100,o={},s=new Set;s.add(e);let c=[e];for(let e=1;e<=t;e++){let t=[],n=[];for(let e of c){let o=await this.getNeighbors(e,{direction:r,edgeType:i,limit:a});for(let e of o.nodes)s.has(e.id)||(s.add(e.id),t.push(e.id),n.push(e))}if(n.length>0&&(o[e]=n),c=t,c.length===0||s.size>=a)break}return o}async getCohesionScore(e){let t=this.query(`SELECT id FROM nodes WHERE community = ?`,[e]);if(t.length===0)return 0;let n=new Set(t.map(e=>e.id)),r=t.map(()=>`?`).join(`,`),i=t.map(e=>e.id),a=this.query(`SELECT from_id, to_id FROM edges WHERE from_id IN (${r}) OR to_id IN (${r})`,[...i,...i]);if(a.length===0)return 0;let o=0;for(let e of a)n.has(e.from_id)&&n.has(e.to_id)&&o++;return o/a.length}async getSymbol360(e){let t=await this.getNode(e);if(!t)throw Error(`Node '${e}' not found`);let n=await this.findEdges({toId:e}),r=await this.findEdges({fromId:e}),i=await this.getProcesses(e);return{node:t,incoming:n,outgoing:r,community:t.community??null,processes:i}}async close(){this.adapter&&=(this.adapter.close(),null)}};function f(e){if(!e)return{};try{return JSON.parse(e)}catch{return{}}}function p(e){return{id:e.id,type:e.type,name:e.name,properties:f(e.properties),sourceRecordId:e.source_record_id??void 0,sourcePath:e.source_path??void 0,createdAt:e.created_at,community:e.community??void 0}}function m(e){return{id:e.id,fromId:e.from_id,toId:e.to_id,type:e.type,weight:e.weight??1,confidence:e.confidence??1,properties:f(e.properties)}}function h(e){return{id:e.edge_id,fromId:e.from_id,toId:e.to_id,type:e.edge_type,weight:e.weight??1,confidence:e.edge_confidence??1,properties:f(e.edge_props??`{}`)}}function g(e){return{id:e.node_id,type:e.node_type,name:e.node_name,properties:f(e.node_props??`{}`),sourceRecordId:e.node_src_rec??void 0,sourcePath:e.node_src_path??void 0,createdAt:e.node_created,community:e.node_community??void 0}}async function _(e){switch(e.backend){case`lancedb`:{let{LanceStore:t}=await import(`./lance-store-jdHZp-V4.js`).then(e=>e.n);return new t({path:e.path})}default:throw Error(`Unknown store backend: "${e.backend}". Supported: lancedb`)}}export{e as LanceStore,d as SqliteGraphStore,u as createSqliteAdapter,_ as createStore};

package/packages/tools/dist/index.d.ts

@@ -1,12 +1,8 @@
-import { ContentType, KnowledgeOrigin } from "../../core/dist/index.js";
+import { ContentType, KnowledgeOrigin, TokenBudget } from "../../core/dist/index.js";
 import { IEmbedder } from "../../embeddings/dist/index.js";
 import { DepthGroupedResult, GraphEdge, GraphNode, GraphStats, GraphTraversalResult, GraphValidationResult, IGraphStore, IKnowledgeStore, ProcessInfo, Symbol360 } from "../../store/dist/index.js";
 
 //#region packages/tools/src/response-envelope.d.ts
-/**
- * Standardized response envelope for AI Kit tools (E-009).
- * New tools should return KBResponse<T>. Existing tools can adopt gradually.
- */
 interface KBNextHint {
   tool: string;
   reason: string;
@@ -23,7 +19,7 @@ type KBErrorCode = 'SYMBOL_NOT_FOUND' | 'INDEX_STALE' | 'TREE_SITTER_UNAVAILABLE
 interface KBResponseMeta {
   durationMs: number;
   tokensEstimate: number;
-  detail: 'summary' | 'errors' | 'full';
+  detail: TokenBudget;
   cached: boolean;
   truncated: boolean;
   caveats?: string[];
@@ -51,8 +47,8 @@ interface AuditOptions {
   path?: string;
   /** Which checks to run (default: all) */
   checks?: AuditCheck[];
-  /** Detail level (default: 'summary') */
-  detail?: 'summary' | 'full';
+  /** Detail level (default: 'efficient') */
+  detail?: TokenBudget;
 }
 interface AuditRecommendation {
   priority: 'high' | 'medium' | 'low';
@@ -252,8 +248,8 @@ interface CheckOptions {
   skipTypes?: boolean;
   /** Skip lint */
   skipLint?: boolean;
-  /** Detail level: summary (default, minimal), errors (parsed errors), full (includes raw) */
-  detail?: 'summary' | 'errors' | 'full';
+  /** Detail level: efficient (default, minimal), normal (parsed errors), full (includes raw) */
+  detail?: TokenBudget;
 }
 interface CheckSummaryResult {
   passed: boolean;
@@ -1331,6 +1327,8 @@ interface GuideRecommendation {
   reason: string;
   order: number;
   suggestedArgs?: Record<string, unknown>;
+  /** Optional token-saving tip shown alongside the recommendation */
+  tokenTip?: string;
 }
 interface GuideResult {
   workflow: string;