conatus 0.1.0

package/dist/knowledge/vector-index.d.ts

@@ -0,0 +1,65 @@
+import type { IEmbeddingClient } from "./embedding-client.js";
+import type { EmbeddingEntry, VectorSearchResult } from "../types/embedding.js";
+export declare class VectorIndex {
+    private readonly indexPath;
+    private readonly embeddingClient;
+    private readonly entries;
+    constructor(indexPath: string, embeddingClient: IEmbeddingClient);
+    /**
+     * Factory method: constructs a VectorIndex and loads existing data from disk.
+     */
+    static create(indexPath: string, embeddingClient: IEmbeddingClient): Promise<VectorIndex>;
+    /**
+     * Embed text and add an entry to the index.
+     */
+    add(id: string, text: string, metadata?: Record<string, unknown>): Promise<EmbeddingEntry>;
+    /**
+     * Embed a query string and search for the most similar entries.
+     */
+    search(query: string, topK?: number, threshold?: number): Promise<VectorSearchResult[]>;
+    /**
+     * Search using a pre-computed vector.
+     */
+    searchByVector(queryVector: number[], topK?: number, threshold?: number): VectorSearchResult[];
+    /**
+     * Remove an entry by id. Returns true if removed, false if not found.
+     */
+    remove(id: string): Promise<boolean>;
+    /**
+     * Return the number of entries in the index.
+     */
+    get size(): number;
+    /**
+     * Retrieve a single entry by id.
+     */
+    getEntry(id: string): EmbeddingEntry | undefined;
+    /**
+     * Alias for getEntry — returns a single entry by id.
+     */
+    getEntryById(id: string): EmbeddingEntry | undefined;
+    /**
+     * Embed a query string and return id + similarity + metadata only (no text).
+     * Useful for Progressive Disclosure: fetch metadata first, then load full text
+     * only for selected candidates.
+     */
+    searchMetadata(query: string, topK?: number, threshold?: number): Promise<Array<{
+        id: string;
+        similarity: number;
+        metadata: Record<string, unknown>;
+    }>>;
+    /**
+     * Search using a pre-computed vector; returns id + similarity + metadata only.
+     */
+    searchMetadataByVector(queryVector: number[], topK?: number, threshold?: number): Array<{
+        id: string;
+        similarity: number;
+        metadata: Record<string, unknown>;
+    }>;
+    /**
+     * Remove all entries from the index and persist.
+     */
+    clear(): Promise<void>;
+    _load(): Promise<void>;
+    private _save;
+}
+//# sourceMappingURL=vector-index.d.ts.map

package/dist/knowledge/vector-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-index.d.ts","sourceRoot":"","sources":["../../src/knowledge/vector-index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAIhF,qBAAa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAJlC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;gBAG/C,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,gBAAgB;IAMpD;;OAEG;WACU,MAAM,CACjB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,gBAAgB,GAChC,OAAO,CAAC,WAAW,CAAC;IAMvB;;OAEG;IACG,GAAG,CACP,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO,CAAC,cAAc,CAAC;IAe1B;;OAEG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAU,EAChB,SAAS,GAAE,MAAY,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAKhC;;OAEG;IACH,cAAc,CACZ,WAAW,EAAE,MAAM,EAAE,EACrB,IAAI,GAAE,MAAU,EAChB,SAAS,GAAE,MAAY,GACtB,kBAAkB,EAAE;IAmBvB;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS1C;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIhD;;OAEG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIpD;;;;OAIG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAW,EACjB,SAAS,GAAE,MAAY,GACtB,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAKxF;;OAEG;IACH,sBAAsB,CACpB,WAAW,EAAE,MAAM,EAAE,EACrB,IAAI,GAAE,MAAW,EACjB,SAAS,GAAE,MAAY,GACtB,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAY/E;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAkBd,KAAK;CASpB"}

package/dist/knowledge/vector-index.js

@@ -0,0 +1,153 @@
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { EmbeddingEntrySchema } from "../types/embedding.js";
+import { cosineSimilarity } from "./embedding-client.js";
+export class VectorIndex {
+    indexPath;
+    embeddingClient;
+    entries = new Map();
+    constructor(indexPath, embeddingClient) {
+        this.indexPath = indexPath;
+        this.embeddingClient = embeddingClient;
+        // Sync loading removed. Use VectorIndex.create() for async load on construction,
+        // or call _load() manually after construction.
+    }
+    /**
+     * Factory method: constructs a VectorIndex and loads existing data from disk.
+     */
+    static async create(indexPath, embeddingClient) {
+        const index = new VectorIndex(indexPath, embeddingClient);
+        await index._load();
+        return index;
+    }
+    /**
+     * Embed text and add an entry to the index.
+     */
+    async add(id, text, metadata = {}) {
+        const vector = await this.embeddingClient.embed(text);
+        const entry = EmbeddingEntrySchema.parse({
+            id,
+            text,
+            vector,
+            model: "embedding",
+            created_at: new Date().toISOString(),
+            metadata,
+        });
+        this.entries.set(id, entry);
+        await this._save();
+        return entry;
+    }
+    /**
+     * Embed a query string and search for the most similar entries.
+     */
+    async search(query, topK = 5, threshold = 0.0) {
+        const queryVector = await this.embeddingClient.embed(query);
+        return this.searchByVector(queryVector, topK, threshold);
+    }
+    /**
+     * Search using a pre-computed vector.
+     */
+    searchByVector(queryVector, topK = 5, threshold = 0.0) {
+        const results = [];
+        for (const entry of this.entries.values()) {
+            const similarity = cosineSimilarity(queryVector, entry.vector);
+            if (similarity >= threshold) {
+                results.push({
+                    id: entry.id,
+                    text: entry.text,
+                    similarity,
+                    metadata: entry.metadata,
+                });
+            }
+        }
+        results.sort((a, b) => b.similarity - a.similarity);
+        return results.slice(0, topK);
+    }
+    /**
+     * Remove an entry by id. Returns true if removed, false if not found.
+     */
+    async remove(id) {
+        const existed = this.entries.has(id);
+        if (existed) {
+            this.entries.delete(id);
+            await this._save();
+        }
+        return existed;
+    }
+    /**
+     * Return the number of entries in the index.
+     */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Retrieve a single entry by id.
+     */
+    getEntry(id) {
+        return this.entries.get(id);
+    }
+    /**
+     * Alias for getEntry — returns a single entry by id.
+     */
+    getEntryById(id) {
+        return this.entries.get(id);
+    }
+    /**
+     * Embed a query string and return id + similarity + metadata only (no text).
+     * Useful for Progressive Disclosure: fetch metadata first, then load full text
+     * only for selected candidates.
+     */
+    async searchMetadata(query, topK = 20, threshold = 0.0) {
+        const queryVector = await this.embeddingClient.embed(query);
+        return this.searchMetadataByVector(queryVector, topK, threshold);
+    }
+    /**
+     * Search using a pre-computed vector; returns id + similarity + metadata only.
+     */
+    searchMetadataByVector(queryVector, topK = 20, threshold = 0.0) {
+        const results = [];
+        for (const entry of this.entries.values()) {
+            const similarity = cosineSimilarity(queryVector, entry.vector);
+            if (similarity >= threshold) {
+                results.push({ id: entry.id, similarity, metadata: entry.metadata ?? {} });
+            }
+        }
+        results.sort((a, b) => b.similarity - a.similarity);
+        return results.slice(0, topK);
+    }
+    /**
+     * Remove all entries from the index and persist.
+     */
+    async clear() {
+        this.entries.clear();
+        await this._save();
+    }
+    async _load() {
+        try {
+            await fsp.access(this.indexPath);
+        }
+        catch {
+            return;
+        }
+        try {
+            const raw = await fsp.readFile(this.indexPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            for (const item of parsed) {
+                const entry = EmbeddingEntrySchema.parse(item);
+                this.entries.set(entry.id, entry);
+            }
+        }
+        catch {
+            // Corrupt or empty file — start fresh
+        }
+    }
+    async _save() {
+        const dir = path.dirname(this.indexPath);
+        await fsp.mkdir(dir, { recursive: true });
+        const data = JSON.stringify(Array.from(this.entries.values()), null, 2);
+        const tmpPath = `${this.indexPath}.tmp`;
+        await fsp.writeFile(tmpPath, data, "utf-8");
+        await fsp.rename(tmpPath, this.indexPath);
+    }
+}
+//# sourceMappingURL=vector-index.js.map

package/dist/knowledge/vector-index.js.map

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

package/dist/knowledge-graph.d.ts

@@ -0,0 +1,70 @@
+import { type KnowledgeEdge } from "./types/knowledge.js";
+interface KnowledgeGraphNode {
+    entry_id: string;
+    goal_id: string;
+    tags: string[];
+    added_at: string;
+}
+/**
+ * KnowledgeGraph stores cross-goal concept relationships as a directed graph.
+ * Nodes represent KnowledgeEntry IDs; edges carry typed semantic relations.
+ *
+ * Persisted as JSON at graphPath: { nodes: [...], edges: [...] }
+ */
+export declare class KnowledgeGraph {
+    private readonly graphPath;
+    private nodes;
+    private edges;
+    constructor(graphPath: string);
+    /**
+     * Add a node for a KnowledgeEntry. If a node with the same entry_id already
+     * exists, it is replaced (update semantics).
+     */
+    addNode(entryId: string, goalId: string, tags: string[]): void;
+    /**
+     * Remove a node and all edges that reference it.
+     */
+    removeNode(entryId: string): void;
+    getNode(entryId: string): KnowledgeGraphNode | undefined;
+    getAllNodes(): KnowledgeGraphNode[];
+    /**
+     * Add an edge. created_at is set automatically to the current timestamp.
+     * Duplicate edges (same from_id, to_id, relation) are replaced.
+     */
+    addEdge(edge: Omit<KnowledgeEdge, "created_at">): void;
+    /**
+     * Remove all edges between fromId and toId (regardless of relation type).
+     */
+    removeEdge(fromId: string, toId: string): void;
+    getEdgesFrom(entryId: string): KnowledgeEdge[];
+    getEdgesTo(entryId: string): KnowledgeEdge[];
+    getAllEdges(): KnowledgeEdge[];
+    /**
+     * Returns all nodes reachable from entryId via a single outgoing edge,
+     * paired with the connecting edge.
+     */
+    getRelated(entryId: string): {
+        node: KnowledgeGraphNode;
+        edge: KnowledgeEdge;
+    }[];
+    /**
+     * Returns all edges with relation = "contradicts".
+     */
+    getContradictions(): KnowledgeEdge[];
+    /**
+     * Detect all simple cycles in the directed graph.
+     * Returns an array of node-ID arrays, each representing one cycle.
+     * Uses DFS with a recursion stack.
+     */
+    detectCycles(): string[][];
+    get nodeCount(): number;
+    get edgeCount(): number;
+    private save;
+    private load;
+    /**
+     * Remove all nodes and edges and persist the empty state.
+     */
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=knowledge-graph.d.ts.map

package/dist/knowledge-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-graph.d.ts","sourceRoot":"","sources":["../src/knowledge-graph.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,sBAAsB,CAAC;AAE/E,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAOD;;;;;GAKG;AACH,qBAAa,cAAc;IAIb,OAAO,CAAC,QAAQ,CAAC,SAAS;IAHtC,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,KAAK,CAAuB;gBAEP,SAAS,EAAE,MAAM;IAM9C;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAW9D;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IASjC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIxD,WAAW,IAAI,kBAAkB,EAAE;IAMnC;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,GAAG,IAAI;IAkBtD;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAU9C,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE;IAI9C,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE;IAI5C,WAAW,IAAI,aAAa,EAAE;IAM9B;;;OAGG;IACH,UAAU,CACR,OAAO,EAAE,MAAM,GACd;QAAE,IAAI,EAAE,kBAAkB,CAAC;QAAC,IAAI,EAAE,aAAa,CAAA;KAAE,EAAE;IAYtD;;OAEG;IACH,iBAAiB,IAAI,aAAa,EAAE;IAMpC;;;;OAIG;IACH,YAAY,IAAI,MAAM,EAAE,EAAE;IAuC1B,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAID,OAAO,CAAC,IAAI;IAeZ,OAAO,CAAC,IAAI;IAsBZ;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd"}

package/dist/knowledge-graph.js

@@ -0,0 +1,194 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { KnowledgeEdgeSchema } from "./types/knowledge.js";
+/**
+ * KnowledgeGraph stores cross-goal concept relationships as a directed graph.
+ * Nodes represent KnowledgeEntry IDs; edges carry typed semantic relations.
+ *
+ * Persisted as JSON at graphPath: { nodes: [...], edges: [...] }
+ */
+export class KnowledgeGraph {
+    graphPath;
+    nodes = new Map();
+    edges = [];
+    constructor(graphPath) {
+        this.graphPath = graphPath;
+        this.load();
+    }
+    // ─── Node CRUD ───
+    /**
+     * Add a node for a KnowledgeEntry. If a node with the same entry_id already
+     * exists, it is replaced (update semantics).
+     */
+    addNode(entryId, goalId, tags) {
+        const node = {
+            entry_id: entryId,
+            goal_id: goalId,
+            tags: [...tags],
+            added_at: new Date().toISOString(),
+        };
+        this.nodes.set(entryId, node);
+        this.save();
+    }
+    /**
+     * Remove a node and all edges that reference it.
+     */
+    removeNode(entryId) {
+        if (!this.nodes.has(entryId))
+            return;
+        this.nodes.delete(entryId);
+        this.edges = this.edges.filter((e) => e.from_id !== entryId && e.to_id !== entryId);
+        this.save();
+    }
+    getNode(entryId) {
+        return this.nodes.get(entryId);
+    }
+    getAllNodes() {
+        return Array.from(this.nodes.values());
+    }
+    // ─── Edge CRUD ───
+    /**
+     * Add an edge. created_at is set automatically to the current timestamp.
+     * Duplicate edges (same from_id, to_id, relation) are replaced.
+     */
+    addEdge(edge) {
+        // Remove existing edge with same from/to/relation to avoid duplicates
+        this.edges = this.edges.filter((e) => !(e.from_id === edge.from_id &&
+            e.to_id === edge.to_id &&
+            e.relation === edge.relation));
+        const full = KnowledgeEdgeSchema.parse({
+            ...edge,
+            created_at: new Date().toISOString(),
+        });
+        this.edges.push(full);
+        this.save();
+    }
+    /**
+     * Remove all edges between fromId and toId (regardless of relation type).
+     */
+    removeEdge(fromId, toId) {
+        const before = this.edges.length;
+        this.edges = this.edges.filter((e) => !(e.from_id === fromId && e.to_id === toId));
+        if (this.edges.length !== before) {
+            this.save();
+        }
+    }
+    getEdgesFrom(entryId) {
+        return this.edges.filter((e) => e.from_id === entryId);
+    }
+    getEdgesTo(entryId) {
+        return this.edges.filter((e) => e.to_id === entryId);
+    }
+    getAllEdges() {
+        return [...this.edges];
+    }
+    // ─── Queries ───
+    /**
+     * Returns all nodes reachable from entryId via a single outgoing edge,
+     * paired with the connecting edge.
+     */
+    getRelated(entryId) {
+        const outgoing = this.getEdgesFrom(entryId);
+        const result = [];
+        for (const edge of outgoing) {
+            const node = this.nodes.get(edge.to_id);
+            if (node) {
+                result.push({ node, edge });
+            }
+        }
+        return result;
+    }
+    /**
+     * Returns all edges with relation = "contradicts".
+     */
+    getContradictions() {
+        return this.edges.filter((e) => e.relation === "contradicts");
+    }
+    // ─── Cycle Detection (DFS) ───
+    /**
+     * Detect all simple cycles in the directed graph.
+     * Returns an array of node-ID arrays, each representing one cycle.
+     * Uses DFS with a recursion stack.
+     */
+    detectCycles() {
+        const visited = new Set();
+        const recStack = new Set();
+        const cycles = [];
+        const path = [];
+        const dfs = (nodeId) => {
+            visited.add(nodeId);
+            recStack.add(nodeId);
+            path.push(nodeId);
+            for (const edge of this.getEdgesFrom(nodeId)) {
+                const neighbor = edge.to_id;
+                if (!visited.has(neighbor)) {
+                    dfs(neighbor);
+                }
+                else if (recStack.has(neighbor)) {
+                    // Found a cycle: extract the cycle portion from path
+                    const cycleStart = path.indexOf(neighbor);
+                    if (cycleStart !== -1) {
+                        cycles.push([...path.slice(cycleStart), neighbor]);
+                    }
+                }
+            }
+            path.pop();
+            recStack.delete(nodeId);
+        };
+        for (const nodeId of this.nodes.keys()) {
+            if (!visited.has(nodeId)) {
+                dfs(nodeId);
+            }
+        }
+        return cycles;
+    }
+    // ─── Stats ───
+    get nodeCount() {
+        return this.nodes.size;
+    }
+    get edgeCount() {
+        return this.edges.length;
+    }
+    // ─── Persistence ───
+    save() {
+        const dir = path.dirname(this.graphPath);
+        fs.mkdirSync(dir, { recursive: true });
+        const data = {
+            nodes: Array.from(this.nodes.values()),
+            edges: this.edges,
+        };
+        const json = JSON.stringify(data, null, 2);
+        const tmpPath = `${this.graphPath}.tmp`;
+        fs.writeFileSync(tmpPath, json, "utf-8");
+        fs.renameSync(tmpPath, this.graphPath);
+    }
+    load() {
+        if (!fs.existsSync(this.graphPath))
+            return;
+        try {
+            const raw = fs.readFileSync(this.graphPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            this.nodes.clear();
+            this.edges = [];
+            for (const node of parsed.nodes ?? []) {
+                this.nodes.set(node.entry_id, node);
+            }
+            for (const edge of parsed.edges ?? []) {
+                const validated = KnowledgeEdgeSchema.parse(edge);
+                this.edges.push(validated);
+            }
+        }
+        catch {
+            // Corrupt or empty file — start fresh
+        }
+    }
+    /**
+     * Remove all nodes and edges and persist the empty state.
+     */
+    clear() {
+        this.nodes.clear();
+        this.edges = [];
+        this.save();
+    }
+}
+//# sourceMappingURL=knowledge-graph.js.map

package/dist/knowledge-graph.js.map

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

package/dist/knowledge-manager.d.ts

@@ -0,0 +1,110 @@
+import { StateManager } from "./state-manager.js";
+import type { ILLMClient } from "./llm/llm-client.js";
+import type { Task } from "./types/task.js";
+import type { KnowledgeEntry, KnowledgeGapSignal, ContradictionResult, SharedKnowledgeEntry, DomainStability } from "./types/knowledge.js";
+import type { VectorIndex } from "./vector-index.js";
+import type { IEmbeddingClient } from "./embedding-client.js";
+/**
+ * KnowledgeManager detects knowledge gaps, generates research tasks,
+ * and persists/retrieves domain knowledge entries.
+ *
+ * File layout:
+ *   <base>/goals/<goal_id>/domain_knowledge.json
+ *   <base>/memory/shared-knowledge/entries.json  (Phase 2 shared KB)
+ */
+export declare class KnowledgeManager {
+    private readonly stateManager;
+    private readonly llmClient;
+    private readonly vectorIndex?;
+    private readonly embeddingClient?;
+    constructor(stateManager: StateManager, llmClient: ILLMClient, vectorIndex?: VectorIndex, embeddingClient?: IEmbeddingClient);
+    /**
+     * Detect whether the given context reveals a knowledge gap.
+     *
+     * Fast-path heuristics:
+     *   - confidence < 0.3 → interpretation_difficulty
+     *   - strategies empty  → strategy_deadlock
+     *
+     * Otherwise, delegate to LLM for deeper analysis.
+     */
+    detectKnowledgeGap(context: {
+        observations: unknown[];
+        strategies: unknown[] | null | undefined;
+        confidence: number;
+    }): Promise<KnowledgeGapSignal | null>;
+    /**
+     * Generate a knowledge acquisition Task for the given signal and goal.
+     * The task will have task_category: "knowledge_acquisition", 3-5 research
+     * questions, and explicit scope limits.
+     */
+    generateAcquisitionTask(signal: KnowledgeGapSignal, goalId: string): Promise<Task>;
+    /**
+     * Persist a KnowledgeEntry to ~/.motiva/goals/<goal_id>/domain_knowledge.json
+     */
+    saveKnowledge(goalId: string, entry: KnowledgeEntry): Promise<void>;
+    /**
+     * Load knowledge entries for a goal, optionally filtered by tags (exact match).
+     *
+     * An entry matches if ALL provided tags appear in the entry's tags array.
+     */
+    loadKnowledge(goalId: string, tags?: string[]): Promise<KnowledgeEntry[]>;
+    /**
+     * Check whether a new entry contradicts existing same-tag entries.
+     * Uses LLM to compare answers for entries sharing tags with the new entry.
+     */
+    checkContradiction(goalId: string, newEntry: KnowledgeEntry): Promise<ContradictionResult>;
+    /**
+     * Returns knowledge entries whose tags include the given dimension name.
+     */
+    getRelevantKnowledge(goalId: string, dimensionName: string): Promise<KnowledgeEntry[]>;
+    /**
+     * Semantic search within a single goal's knowledge entries via VectorIndex.
+     * Falls back to an empty array when no VectorIndex is configured.
+     */
+    searchKnowledge(query: string, topK?: number): Promise<KnowledgeEntry[]>;
+    /**
+     * Cross-goal semantic search. Leverages the VectorIndex which is global
+     * across all goals. Returns entries from any goal ordered by similarity.
+     * Falls back to an empty array when no VectorIndex is configured.
+     */
+    searchAcrossGoals(query: string, topK?: number): Promise<KnowledgeEntry[]>;
+    /**
+     * Save a KnowledgeEntry into the shared knowledge base, associating it with
+     * the given goalId. If VectorIndex is available the entry is also embedded
+     * and the embedding_id is stored on the returned SharedKnowledgeEntry.
+     */
+    saveToSharedKnowledgeBase(entry: KnowledgeEntry, goalId: string): Promise<SharedKnowledgeEntry>;
+    /**
+     * Query the shared knowledge base by tags (AND logic).
+     * Optionally filter to entries contributed by a specific goal.
+     */
+    querySharedKnowledge(tags: string[], goalId?: string): SharedKnowledgeEntry[];
+    /**
+     * Semantic search across the shared knowledge base using VectorIndex.
+     * Falls back to an empty array when no VectorIndex is configured.
+     */
+    searchByEmbedding(query: string, topK?: number): Promise<{
+        entry: SharedKnowledgeEntry;
+        similarity: number;
+    }[]>;
+    /**
+     * Classify the domain stability of a set of knowledge entries via LLM.
+     * Returns "stable", "moderate", or "volatile".
+     */
+    classifyDomainStability(domain: string, entries: KnowledgeEntry[]): Promise<DomainStability>;
+    /**
+     * Return shared knowledge entries whose revalidation_due_at is in the past.
+     */
+    getStaleEntries(): SharedKnowledgeEntry[];
+    /**
+     * Generate KnowledgeAcquisitionTask-style Task objects for each stale entry,
+     * re-asking the original question.
+     */
+    generateRevalidationTasks(staleEntries: SharedKnowledgeEntry[]): Promise<Task[]>;
+    /** Load all SharedKnowledgeEntries from the shared KB file. */
+    private _loadSharedEntries;
+    /** Compute revalidation due date based on stability and a base date. */
+    private _computeRevalidationDue;
+    private loadDomainKnowledge;
+}
+//# sourceMappingURL=knowledge-manager.d.ts.map

package/dist/knowledge-manager.d.ts.map

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