@gmickel/gno 1.4.2 → 1.5.0

package/src/store/sqlite/adapter.ts

@@ -30,6 +30,10 @@ import type {
   FtsResult,
   FtsSearchOptions,
   GetGraphOptions,
+  GraphEdgeConfidence,
+  GraphEdgeAudit,
+  GraphLinkType,
+  GraphReportNode,
   GraphResult,
   IndexStatus,
   IngestErrorInput,
@@ -45,6 +49,7 @@ import type {
 import type { SqliteDbProvider } from "./types";
 
 import { buildUri, deriveDocid, stripUriIndex } from "../../app/constants";
+import { analyzeGraphCommunities } from "../../core/graph-analysis";
 import { normalizeWikiName, stripWikiMdExt } from "../../core/links";
 import { migrations, runMigrations } from "../migrations";
 import { err, ok } from "../types";
@@ -807,6 +812,59 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     }
   }
 
+  async getDocumentsByDocids(
+    docids: string[],
+    options: {
+      collection?: string;
+      activeOnly?: boolean;
+    } = {}
+  ): Promise<StoreResult<DocumentRow[]>> {
+    try {
+      if (docids.length === 0) {
+        return ok([]);
+      }
+
+      const uniqueDocids = [
+        ...new Set(docids.filter((docid) => docid.trim().length > 0)),
+      ];
+      if (uniqueDocids.length === 0) {
+        return ok([]);
+      }
+
+      const db = this.ensureOpen();
+      const rows: DbDocumentRow[] = [];
+      const SQL_PARAM_LIMIT = options.collection ? 899 : 900;
+
+      for (let i = 0; i < uniqueDocids.length; i += SQL_PARAM_LIMIT) {
+        const batch = uniqueDocids.slice(i, i + SQL_PARAM_LIMIT);
+        const placeholders = batch.map(() => "?").join(",");
+        const clauses = [`docid IN (${placeholders})`];
+        const params: string[] = [...batch];
+
+        if (options.activeOnly ?? true) {
+          clauses.push("active = 1");
+        }
+        if (options.collection) {
+          clauses.push("collection = ?");
+          params.push(options.collection);
+        }
+
+        const sql = `SELECT * FROM documents WHERE ${clauses.join(" AND ")} ORDER BY id`;
+        rows.push(...db.query<DbDocumentRow, string[]>(sql).all(...params));
+      }
+
+      return ok(rows.map(mapDocumentRow));
+    } catch (cause) {
+      return err(
+        "QUERY_FAILED",
+        cause instanceof Error
+          ? cause.message
+          : "Failed to get documents by docids",
+        cause
+      );
+    }
+  }
+
   async listDocumentsPaginated(options: {
     collection?: string;
     limit: number;
@@ -2333,17 +2391,43 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
           )
         ORDER BY t.id LIMIT 1
       `;
+
+      const wikiBestRank = (
+        collectionExpr: string,
+        targetRefExpr: string
+      ): string => `
+        SELECT MIN(${wikiOrder("t", targetRefExpr)}) FROM documents t
+        WHERE t.active = 1
+          AND t.collection = ${collectionExpr}
+          AND ${wikiMatch("t", targetRefExpr)}
+      `;
+
+      const wikiBestRankMatchCount = (
+        collectionExpr: string,
+        targetRefExpr: string
+      ): string => `
+        SELECT COUNT(*) FROM documents t
+        WHERE t.active = 1
+          AND t.collection = ${collectionExpr}
+          AND ${wikiMatch("t", targetRefExpr)}
+          AND ${wikiOrder("t", targetRefExpr)} = (${wikiBestRank(
+            collectionExpr,
+            targetRefExpr
+          )})
+      `;
       interface ResolvedEdgeRow {
         source_id: number;
         source_docid: string;
         target_id: number;
         target_docid: string;
         link_type: "wiki" | "markdown";
-        weight: number;
+        match_rank: number | null;
+        match_count: number | null;
       }
 
-      interface UnresolvedCountRow {
-        unresolved: number | null;
+      interface UnresolvedByTypeRow {
+        link_type: "wiki" | "markdown";
+        unresolved: number;
       }
 
       interface NodeMetaRow {
@@ -2369,7 +2453,20 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
           tgt.id as target_id,
           tgt.docid as target_docid,
           dl.link_type,
-          COUNT(*) as weight
+          CASE dl.link_type
+            WHEN 'wiki' THEN (${wikiBestRank(
+              "COALESCE(dl.target_collection, src.collection)",
+              "dl.target_ref_norm"
+            )})
+            WHEN 'markdown' THEN 5
+          END as match_rank,
+          CASE dl.link_type
+            WHEN 'wiki' THEN (${wikiBestRankMatchCount(
+              "COALESCE(dl.target_collection, src.collection)",
+              "dl.target_ref_norm"
+            )})
+            WHEN 'markdown' THEN 1
+          END as match_count
         FROM documents src
         JOIN doc_links dl ON dl.source_doc_id = src.id
         JOIN documents tgt ON tgt.id = CASE dl.link_type
@@ -2387,8 +2484,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
         END
         WHERE src.active = 1 AND tgt.active = 1
           ${edgeCollectionClause}
-        GROUP BY src.id, src.docid, tgt.id, tgt.docid, dl.link_type
-        ORDER BY weight DESC, src.id ASC, tgt.id ASC
+        ORDER BY src.id ASC, tgt.id ASC, dl.link_type ASC
       `;
 
       const resolvedEdgeRows = db
@@ -2403,9 +2499,11 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
       }
       const unresolvedQuery = `
         SELECT
-          SUM(CASE WHEN target_id IS NULL THEN 1 ELSE 0 END) as unresolved
+          link_type,
+          COUNT(*) as unresolved
         FROM (
           SELECT
+            dl.link_type,
             CASE dl.link_type
               WHEN 'wiki' THEN (
                 ${wikiBestMatch(
@@ -2426,11 +2524,21 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
           WHERE src.active = 1
             ${unresolvedCollectionClause}
         )
+        WHERE target_id IS NULL
+        GROUP BY link_type
       `;
-      const unresolvedRow = db
-        .query<UnresolvedCountRow, string[]>(unresolvedQuery)
-        .get(...unresolvedParams);
-      const totalEdgesUnresolved = unresolvedRow?.unresolved ?? 0;
+      const unresolvedRows = db
+        .query<UnresolvedByTypeRow, string[]>(unresolvedQuery)
+        .all(...unresolvedParams);
+      const unresolvedByType: Record<"wiki" | "markdown", number> = {
+        wiki: 0,
+        markdown: 0,
+      };
+      for (const row of unresolvedRows) {
+        unresolvedByType[row.link_type] = row.unresolved;
+      }
+      const totalEdgesUnresolved =
+        unresolvedByType.wiki + unresolvedByType.markdown;
 
       const outNeighbors = new Map<number, Set<number>>();
       const inNeighbors = new Map<number, Set<number>>();
@@ -2481,6 +2589,46 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
         .filter((row): row is NodeMetaRow & { degree: number } => row !== null)
         .sort((a, b) => b.degree - a.degree || a.id - b.id);
 
+      const toReportNode = (
+        row: NodeMetaRow & { degree: number }
+      ): GraphReportNode => ({
+        id: row.docid,
+        uri: row.uri,
+        title: row.title,
+        collection: row.collection,
+        relPath: row.rel_path,
+        degree: row.degree,
+      });
+
+      const isolatedBaseParams: (string | number)[] = [];
+      const isolatedBaseConditions = ["active = 1"];
+      if (collection) {
+        isolatedBaseConditions.push("collection = ?");
+        isolatedBaseParams.push(collection);
+      }
+      if (connectedIdList.length > 0) {
+        const placeholders = connectedIdList.map(() => "?").join(",");
+        isolatedBaseConditions.push(`id NOT IN (${placeholders})`);
+        isolatedBaseParams.push(...connectedIdList);
+      }
+      const isolatedWhereClause = isolatedBaseConditions.join(" AND ");
+      const isolatedCountRow = db
+        .query<{ cnt: number }, (string | number)[]>(
+          `SELECT COUNT(*) as cnt FROM documents WHERE ${isolatedWhereClause}`
+        )
+        .get(...isolatedBaseParams);
+      const isolatedTotal = isolatedCountRow?.cnt ?? 0;
+      const isolatedExampleRows = db
+        .query<NodeMetaRow, (string | number)[]>(
+          `SELECT id, docid, uri, title, collection, rel_path
+           FROM documents
+           WHERE ${isolatedWhereClause}
+           ORDER BY id ASC
+           LIMIT 10`
+        )
+        .all(...isolatedBaseParams)
+        .map((row) => ({ ...row, degree: 0 }));
+
       let totalNodes = linkedOnly ? connectedNodes.length : 0;
       if (!linkedOnly) {
         const countParams: string[] = [];
@@ -2542,9 +2690,95 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
       const selectedDocids = new Set(nodes.map((node) => node.id));
       const nodeDocids = new Set(nodes.map((node) => node.id));
 
+      const confidenceRank: Record<GraphEdgeConfidence, number> = {
+        explicit: 1,
+        inferred: 2,
+        ambiguous: 3,
+        similarity: 4,
+      };
+      const classifyResolvedEdge = (
+        linkType: "wiki" | "markdown",
+        matchRank: number | null,
+        matchCount: number | null
+      ): { confidence: GraphEdgeConfidence; audit: GraphEdgeAudit } => {
+        if (linkType === "markdown") {
+          return {
+            confidence: "explicit",
+            audit: { resolution: "exact-path", matchCount: 1 },
+          };
+        }
+
+        const count = matchCount ?? 0;
+        if (count > 1) {
+          return {
+            confidence: "ambiguous",
+            audit: {
+              resolution: "ambiguous-fallback",
+              matchCount: count,
+            },
+          };
+        }
+
+        if (matchRank === 1 || matchRank === 2) {
+          return {
+            confidence: "explicit",
+            audit: { resolution: "exact-title", matchCount: count || 1 },
+          };
+        }
+        if (matchRank === 5 || matchRank === 6) {
+          return {
+            confidence: "explicit",
+            audit: { resolution: "exact-path", matchCount: count || 1 },
+          };
+        }
+
+        return {
+          confidence: "inferred",
+          audit: { resolution: "path-fallback", matchCount: count || 1 },
+        };
+      };
+      const mergeAudit = (
+        current: {
+          type: GraphLinkType;
+          weight: number;
+          confidence: GraphEdgeConfidence;
+          audit: GraphEdgeAudit;
+        },
+        nextConfidence: GraphEdgeConfidence,
+        nextAudit: GraphEdgeAudit
+      ): void => {
+        if (
+          confidenceRank[nextConfidence] < confidenceRank[current.confidence]
+        ) {
+          current.confidence = nextConfidence;
+          current.audit = {
+            ...nextAudit,
+            matchCount: Math.max(
+              current.audit.matchCount ?? 0,
+              nextAudit.matchCount ?? 0
+            ),
+          };
+          return;
+        }
+        if (
+          nextAudit.matchCount !== undefined &&
+          (current.audit.matchCount ?? 0) < nextAudit.matchCount
+        ) {
+          current.audit = {
+            ...current.audit,
+            matchCount: nextAudit.matchCount,
+          };
+        }
+      };
+
       const edgeMap = new Map<
         string,
-        { type: "wiki" | "markdown" | "similar"; weight: number }
+        {
+          type: GraphLinkType;
+          weight: number;
+          confidence: GraphEdgeConfidence;
+          audit: GraphEdgeAudit;
+        }
       >();
       for (const row of resolvedEdgeRows) {
         if (
@@ -2554,7 +2788,23 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
           continue;
         }
         const key = `${row.source_docid}:${row.target_docid}:${row.link_type}`;
-        edgeMap.set(key, { type: row.link_type, weight: row.weight });
+        const { confidence, audit } = classifyResolvedEdge(
+          row.link_type,
+          row.match_rank,
+          row.match_count
+        );
+        const existing = edgeMap.get(key);
+        if (existing) {
+          existing.weight += 1;
+          mergeAudit(existing, confidence, audit);
+        } else {
+          edgeMap.set(key, {
+            type: row.link_type,
+            weight: 1,
+            confidence,
+            audit,
+          });
+        }
       }
 
       // Phase 3: Similarity edges (if requested)
@@ -2661,7 +2911,12 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
               // Keep max score
               const existing = edgeMap.get(key);
               if (!existing || clampedScore > existing.weight) {
-                edgeMap.set(key, { type: "similar", weight: clampedScore });
+                edgeMap.set(key, {
+                  type: "similar",
+                  weight: clampedScore,
+                  confidence: "similarity",
+                  audit: { resolution: "similarity", score: clampedScore },
+                });
               }
             }
           } catch {
@@ -2687,9 +2942,39 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
           target: parts[1] ?? "",
           type: val.type,
           weight: val.weight,
+          confidence: val.confidence,
+          audit: val.audit,
         };
       });
 
+      const edgeTypes: Record<GraphLinkType, number> = {
+        wiki: 0,
+        markdown: 0,
+        similar: 0,
+      };
+      for (const edge of allEdges) {
+        edgeTypes[edge.type] += 1;
+      }
+      const edgeConfidence: Record<GraphEdgeConfidence, number> = {
+        explicit: 0,
+        inferred: 0,
+        ambiguous: 0,
+        similarity: 0,
+      };
+      for (const edge of allEdges) {
+        edgeConfidence[edge.confidence] += 1;
+      }
+
+      const communityAnalysis = analyzeGraphCommunities(nodes, allEdges);
+      warnings.push(...communityAnalysis.warnings);
+      const nodesWithCommunities = nodes.map((node) => {
+        const communityId = communityAnalysis.assignments[node.id];
+        return communityId ? { ...node, communityId } : node;
+      });
+      const communityByNodeId = new Map(
+        Object.entries(communityAnalysis.assignments)
+      );
+
       const truncatedEdges = allEdges.length > limitEdges;
       const links = allEdges.slice(0, limitEdges);
 
@@ -2702,8 +2987,50 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
       }
 
       return ok({
-        nodes,
+        nodes: nodesWithCommunities,
         links,
+        report: {
+          hubs: connectedNodes.slice(0, 10).map((node) => ({
+            ...toReportNode(node),
+            communityId: communityByNodeId.get(node.docid),
+          })),
+          bridgeCandidates: connectedNodes
+            .filter(
+              (row) =>
+                (inNeighbors.get(row.id)?.size ?? 0) > 0 &&
+                (outNeighbors.get(row.id)?.size ?? 0) > 0
+            )
+            .slice(0, 10)
+            .map((node) => ({
+              ...toReportNode(node),
+              communityId: communityByNodeId.get(node.docid),
+            })),
+          isolated: {
+            total: isolatedTotal,
+            examples: isolatedExampleRows.map((node) => ({
+              ...toReportNode(node),
+              communityId: communityByNodeId.get(node.docid),
+            })),
+          },
+          unresolvedLinks: {
+            total: totalEdgesUnresolved,
+            byType: unresolvedByType,
+          },
+          edgeTypes,
+          edgeConfidence,
+          audit: {
+            inferredEdges: edgeConfidence.inferred,
+            ambiguousEdges: edgeConfidence.ambiguous,
+            similarityEdges: edgeConfidence.similarity,
+          },
+          communities: {
+            total: communityAnalysis.total,
+            algorithm: communityAnalysis.algorithm,
+            skipped: communityAnalysis.skipped,
+            assignments: communityAnalysis.assignments,
+            top: communityAnalysis.communities,
+          },
+        },
         meta: {
           collection,
           nodeLimit: limitNodes,
@@ -2712,7 +3039,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
           // totalEdges = collapsed edge count within selected nodes (matches allEdges)
           totalEdges: allEdges.length,
           totalEdgesUnresolved,
-          returnedNodes: nodes.length,
+          returnedNodes: nodesWithCommunities.length,
           returnedEdges: links.length,
           truncated: truncatedNodes || truncatedEdges,
           linkedOnly,

package/src/store/types.ts

@@ -418,6 +418,28 @@ export interface EmbeddingCleanupStats {
 /** Graph link type (wiki, markdown, or similarity) */
 export type GraphLinkType = "wiki" | "markdown" | "similar";
 
+/** Trust classification for graph edges */
+export type GraphEdgeConfidence =
+  | "explicit"
+  | "inferred"
+  | "ambiguous"
+  | "similarity";
+
+/** Audit metadata explaining how an edge was derived */
+export interface GraphEdgeAudit {
+  /** Resolution path used to create the edge */
+  resolution:
+    | "exact-title"
+    | "exact-path"
+    | "path-fallback"
+    | "ambiguous-fallback"
+    | "similarity";
+  /** Number of equally ranked target candidates, when applicable */
+  matchCount?: number;
+  /** Similarity score copied from weight for similarity edges */
+  score?: number;
+}
+
 /** Graph node representing a document */
 export interface GraphNode {
   /** Document ID (#hex) - primary identifier */
@@ -432,6 +454,42 @@ export interface GraphNode {
   relPath: string;
   /** Total degree (in + out unique neighbors) */
   degree: number;
+  /** Optional deterministic community id from graph analysis */
+  communityId?: string;
+}
+
+/** Compact graph report node summary */
+export interface GraphReportNode {
+  /** Document ID (#hex) */
+  id: string;
+  /** Document URI (gno://collection/path) */
+  uri: string;
+  /** Document title */
+  title: string | null;
+  /** Collection name */
+  collection: string;
+  /** Relative path within collection */
+  relPath: string;
+  /** Total degree (in + out unique neighbors) */
+  degree: number;
+  /** Optional deterministic community id from graph analysis */
+  communityId?: string;
+}
+
+/** Deterministic graph community summary */
+export interface GraphCommunity {
+  /** Stable community id within this graph response */
+  id: string;
+  /** Human-readable label derived from the highest-degree member */
+  label: string;
+  /** Number of returned nodes assigned to this community */
+  size: number;
+  /** Internal edge count before edge-limit truncation */
+  edgeCount: number;
+  /** Internal density, 0-1 */
+  density: number;
+  /** Highest-degree example nodes in the community */
+  topNodes: GraphReportNode[];
 }
 
 /** Graph link (edge) between two nodes */
@@ -444,6 +502,55 @@ export interface GraphLink {
   type: GraphLinkType;
   /** Edge weight (link count for wiki/md, similarity score for similar) */
   weight: number;
+  /** Trust classification for retrieval and agent audit */
+  confidence: GraphEdgeConfidence;
+  /** Audit metadata for how this edge was resolved */
+  audit: GraphEdgeAudit;
+}
+
+/** Graph report summary over the current graph result */
+export interface GraphReport {
+  /** Highest-degree documents */
+  hubs: GraphReportNode[];
+  /** Bridge-like documents with both incoming and outgoing links */
+  bridgeCandidates: GraphReportNode[];
+  /** Isolated documents with no resolved explicit graph links */
+  isolated: {
+    /** Total isolated active documents in scope */
+    total: number;
+    /** First isolated documents by stable document id order */
+    examples: GraphReportNode[];
+  };
+  /** Unresolved explicit links */
+  unresolvedLinks: {
+    /** Total unresolved wiki/markdown links in scope */
+    total: number;
+    /** Unresolved links by type */
+    byType: Record<Exclude<GraphLinkType, "similar">, number>;
+  };
+  /** Edge breakdown by type before edge-limit truncation */
+  edgeTypes: Record<GraphLinkType, number>;
+  /** Edge confidence breakdown before edge-limit truncation */
+  edgeConfidence: Record<GraphEdgeConfidence, number>;
+  /** Explicit links resolved through fallback or ambiguous matching */
+  audit: {
+    inferredEdges: number;
+    ambiguousEdges: number;
+    similarityEdges: number;
+  };
+  /** Optional deterministic community/cluster analysis over returned nodes */
+  communities: {
+    /** Number of detected communities */
+    total: number;
+    /** Algorithm used for deterministic cluster labels */
+    algorithm: "deterministic-label-propagation";
+    /** Whether community detection was skipped for graph size */
+    skipped: boolean;
+    /** Node docid to community id map */
+    assignments: Record<string, string>;
+    /** Top communities by size */
+    top: GraphCommunity[];
+  };
 }
 
 /** Graph metadata with truncation info */
@@ -484,6 +591,7 @@ export interface GraphMeta {
 export interface GraphResult {
   nodes: GraphNode[];
   links: GraphLink[];
+  report: GraphReport;
   meta: GraphMeta;
 }
 
@@ -641,6 +749,18 @@ export interface StorePort {
     }
   ): Promise<StoreResult<DocumentRow[]>>;
 
+  /**
+   * Fetch documents by docids in batch.
+   * Useful for graph traversal pipelines to avoid per-node document lookups.
+   */
+  getDocumentsByDocids(
+    docids: string[],
+    options?: {
+      collection?: string;
+      activeOnly?: boolean;
+    }
+  ): Promise<StoreResult<DocumentRow[]>>;
+
   /**
    * List documents with pagination support.
    * Returns documents and total count for efficient browsing.