@gmickel/gno 1.9.0 → 1.10.0

package/src/sdk/documents.ts

@@ -13,8 +13,8 @@ import type {
   MultiGetResponse,
   SkippedDoc,
 } from "../cli/commands/multi-get";
-import type { ParsedRef } from "../cli/commands/ref-parser";
 import type { Config } from "../config/types";
+import type { ParsedRef } from "../core/ref-parser";
 import type { DocumentRow, StorePort } from "../store/types";
 import type {
   GnoGetOptions,
@@ -22,8 +22,8 @@ import type {
   GnoMultiGetOptions,
 } from "./types";
 
-import { isGlobPattern, parseRef, splitRefs } from "../cli/commands/ref-parser";
 import { getDocumentCapabilities } from "../core/document-capabilities";
+import { isGlobPattern, parseRef, splitRefs } from "../core/ref-parser";
 import { sdkError } from "./errors";
 
 const URI_PREFIX_PATTERN = /^gno:\/\/[^/]+\//;

package/src/serve/routes/api.ts

@@ -35,6 +35,10 @@ import {
   removeCollection,
   updateCollection,
 } from "../../collection";
+import {
+  fingerprintContentTypeRules,
+  normalizeContentTypes,
+} from "../../config";
 import {
   buildCaptureReceipt,
   listCaptureDiskRelPaths,
@@ -100,6 +104,7 @@ import {
   generateGroundedAnswer,
   processAnswerResult,
 } from "../../pipeline/answer";
+import { diagnoseQueryTarget } from "../../pipeline/diagnose";
 import { searchHybrid } from "../../pipeline/hybrid";
 import { validateQueryModes } from "../../pipeline/query-modes";
 import { searchBm25 } from "../../pipeline/search";
@@ -192,6 +197,10 @@ export interface QueryRequestBody {
   tagsAny?: string;
 }
 
+export interface QueryDiagnoseRequestBody extends QueryRequestBody {
+  target?: string;
+}
+
 export interface AskRequestBody {
   query: string;
   limit?: number;
@@ -3517,6 +3526,191 @@ export async function handleQuery(
   return jsonResponse(result.value);
 }
 
+/**
+ * POST /api/query/diagnose
+ * Body: { query, target, limit?, minScore?, collection?, lang?, queryModes?, noExpand?, noRerank?, graph? }
+ * Returns targeted retrieval diagnostics for one document.
+ */
+export async function handleQueryDiagnose(
+  ctx: ServerContext,
+  req: Request
+): Promise<Response> {
+  let body: QueryDiagnoseRequestBody;
+  try {
+    body = (await req.json()) as QueryDiagnoseRequestBody;
+  } catch {
+    return errorResponse("VALIDATION", "Invalid JSON body");
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return errorResponse("VALIDATION", "JSON body must be an object");
+  }
+
+  if (!body.query || typeof body.query !== "string") {
+    return errorResponse("VALIDATION", "Missing or invalid query");
+  }
+  if (!body.target || typeof body.target !== "string") {
+    return errorResponse("VALIDATION", "Missing or invalid target");
+  }
+
+  const rawQuery = body.query.trim();
+  const target = body.target.trim();
+  if (!rawQuery) {
+    return errorResponse("VALIDATION", "Query cannot be empty");
+  }
+  if (!target) {
+    return errorResponse("VALIDATION", "target cannot be empty");
+  }
+
+  if (
+    body.limit !== undefined &&
+    (typeof body.limit !== "number" || body.limit < 1)
+  ) {
+    return errorResponse("VALIDATION", "limit must be a positive integer");
+  }
+  if (
+    body.minScore !== undefined &&
+    (typeof body.minScore !== "number" ||
+      body.minScore < 0 ||
+      body.minScore > 1)
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      "minScore must be a number between 0 and 1"
+    );
+  }
+  if (body.since !== undefined && typeof body.since !== "string") {
+    return errorResponse("VALIDATION", "since must be a string");
+  }
+  if (body.until !== undefined && typeof body.until !== "string") {
+    return errorResponse("VALIDATION", "until must be a string");
+  }
+  if (body.intent !== undefined && typeof body.intent !== "string") {
+    return errorResponse("VALIDATION", "intent must be a string");
+  }
+  if (body.exclude !== undefined && typeof body.exclude !== "string") {
+    return errorResponse(
+      "VALIDATION",
+      "exclude must be a comma-separated string"
+    );
+  }
+  if (
+    body.candidateLimit !== undefined &&
+    (typeof body.candidateLimit !== "number" || body.candidateLimit < 1)
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      "candidateLimit must be a positive integer"
+    );
+  }
+  if (body.category !== undefined && typeof body.category !== "string") {
+    return errorResponse(
+      "VALIDATION",
+      "category must be a comma-separated string"
+    );
+  }
+  if (body.author !== undefined && typeof body.author !== "string") {
+    return errorResponse("VALIDATION", "author must be a string");
+  }
+
+  const { queryModes, error: queryModesError } = parseQueryModesInput(
+    body.queryModes
+  );
+  if (queryModesError) {
+    return queryModesError;
+  }
+
+  const {
+    query,
+    queryModes: normalizedQueryModes,
+    error: structuredQueryError,
+  } = normalizeStructuredQueryBody(rawQuery, queryModes);
+  if (structuredQueryError) {
+    return structuredQueryError;
+  }
+  const normalizedQuery = query ?? rawQuery;
+
+  let tagsAll: string[] | undefined;
+  let tagsAny: string[] | undefined;
+
+  if (body.tagsAll) {
+    try {
+      tagsAll = parseAndValidateTagFilter(body.tagsAll);
+    } catch (e) {
+      return errorResponse(
+        "VALIDATION",
+        e instanceof Error ? e.message : "Invalid tagsAll"
+      );
+    }
+  }
+
+  if (body.tagsAny) {
+    try {
+      tagsAny = parseAndValidateTagFilter(body.tagsAny);
+    } catch (e) {
+      return errorResponse(
+        "VALIDATION",
+        e instanceof Error ? e.message : "Invalid tagsAny"
+      );
+    }
+  }
+
+  const categories = body.category
+    ? parseCommaSeparatedValues(body.category)
+    : undefined;
+  const exclude = body.exclude
+    ? parseCommaSeparatedValues(body.exclude)
+    : undefined;
+  const author = body.author?.trim() || undefined;
+  const contentTypeRules = normalizeContentTypes(
+    ctx.config.contentTypes ?? []
+  ).rules;
+
+  const result = await diagnoseQueryTarget(
+    {
+      store: ctx.store,
+      config: ctx.config,
+      vectorIndex: ctx.vectorIndex,
+      embedPort: ctx.embedPort,
+      expandPort: ctx.expandPort,
+      rerankPort: ctx.rerankPort,
+    },
+    normalizedQuery,
+    {
+      target,
+      limit: Math.min(body.limit ?? 20, 50),
+      minScore: body.minScore,
+      collection: body.collection,
+      lang: body.lang,
+      intent: body.intent?.trim() || undefined,
+      candidateLimit:
+        body.candidateLimit !== undefined
+          ? Math.min(body.candidateLimit, 100)
+          : undefined,
+      exclude,
+      queryModes: normalizedQueryModes,
+      noExpand: body.noExpand,
+      noRerank: body.noRerank,
+      graph: body.graph === true,
+      noGraph: body.noGraph,
+      tagsAll,
+      tagsAny,
+      since: body.since,
+      until: body.until,
+      categories,
+      author,
+      contentTypeRules,
+      contentTypeRulesFingerprint:
+        fingerprintContentTypeRules(contentTypeRules),
+    }
+  );
+
+  if (!result.ok) {
+    return errorResponse("RUNTIME", result.error.message, 500);
+  }
+
+  return jsonResponse(result.value);
+}
+
 /**
  * POST /api/ask
  * Body: { query, limit?, collection?, lang?, maxAnswerTokens? }

package/src/serve/routes/graph.ts

@@ -4,8 +4,17 @@
  * @module src/serve/routes/graph
  */
 
+import type { Config } from "../../config/types";
 import type { SqliteAdapter } from "../../store/sqlite/adapter";
-import type { GetGraphOptions, GraphResult } from "../../store/types";
+import type {
+  GetGraphOptions,
+  GraphQueryDirection,
+  GraphQueryResult,
+  GraphResult,
+} from "../../store/types";
+
+import { normalizeContentTypes } from "../../config";
+import { diagnoseGraphQuery } from "../../core/graph-query";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -13,6 +22,21 @@ import type { GetGraphOptions, GraphResult } from "../../store/types";
 
 export interface GraphResponse extends GraphResult {}
 
+export interface GraphQueryResponse extends GraphQueryResult {}
+
+interface GraphQueryRequestBody {
+  doc?: string;
+  root?: string;
+  direction?: GraphQueryDirection;
+  edgeType?: string;
+  relation?: string;
+  maxDepth?: number;
+  depth?: number;
+  maxNodes?: number;
+  frontierLimit?: number;
+  visitedLimit?: number;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -67,6 +91,29 @@ function parseThreshold(
   return { ok: true, value: parsed };
 }
 
+function parseBodyPositiveInt(
+  name: string,
+  value: number | undefined,
+  defaultValue: number,
+  min: number,
+  max: number
+): ParseResult {
+  if (value === undefined) return { ok: true, value: defaultValue };
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    return {
+      ok: false,
+      message: `${name} must be an integer between ${min} and ${max}`,
+    };
+  }
+  if (value < min || value > max) {
+    return {
+      ok: false,
+      message: `${name} must be between ${min} and ${max}`,
+    };
+  }
+  return { ok: true, value };
+}
+
 /**
  * Parse boolean query param (true if "true" or "1", false otherwise).
  */
@@ -160,3 +207,128 @@ export async function handleGraph(
 
   return jsonResponse(result.value satisfies GraphResponse);
 }
+
+/**
+ * POST /api/graph/query
+ * Returns bounded typed-edge traversal from one resolved root document.
+ */
+export async function handleGraphQuery(
+  store: SqliteAdapter,
+  config: Config,
+  req: Request
+): Promise<Response> {
+  let body: GraphQueryRequestBody;
+  try {
+    body = (await req.json()) as GraphQueryRequestBody;
+  } catch {
+    return errorResponse("VALIDATION", "Invalid JSON body", 400);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return errorResponse("VALIDATION", "JSON body must be an object", 400);
+  }
+
+  const docRef = body.doc ?? body.root;
+  if (!docRef || typeof docRef !== "string") {
+    return errorResponse("VALIDATION", "Missing or invalid doc", 400);
+  }
+  const rootRef = docRef.trim();
+  if (!rootRef) {
+    return errorResponse("VALIDATION", "doc cannot be empty", 400);
+  }
+
+  const direction = body.direction ?? "both";
+  if (!["out", "in", "both"].includes(direction)) {
+    return errorResponse(
+      "VALIDATION",
+      "direction must be 'out', 'in', or 'both'",
+      400
+    );
+  }
+
+  if (body.edgeType !== undefined && typeof body.edgeType !== "string") {
+    return errorResponse("VALIDATION", "edgeType must be a string", 400);
+  }
+  if (body.relation !== undefined && typeof body.relation !== "string") {
+    return errorResponse("VALIDATION", "relation must be a string", 400);
+  }
+  const edgeTypeValue = body.edgeType?.trim();
+  const relationValue = body.relation?.trim();
+  const edgeType = edgeTypeValue || relationValue || undefined;
+  if (
+    (body.edgeType !== undefined || body.relation !== undefined) &&
+    !edgeType
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      "edgeType/relation cannot be empty",
+      400
+    );
+  }
+  if (edgeTypeValue && relationValue && edgeTypeValue !== relationValue) {
+    return errorResponse(
+      "VALIDATION",
+      "edgeType and relation are aliases and must match when both are provided",
+      400
+    );
+  }
+
+  const maxDepthResult = parseBodyPositiveInt(
+    "maxDepth",
+    body.maxDepth ?? body.depth,
+    2,
+    1,
+    6
+  );
+  if (!maxDepthResult.ok) {
+    return errorResponse("VALIDATION", maxDepthResult.message, 400);
+  }
+  const maxNodesResult = parseBodyPositiveInt(
+    "maxNodes",
+    body.maxNodes,
+    100,
+    1,
+    1000
+  );
+  if (!maxNodesResult.ok) {
+    return errorResponse("VALIDATION", maxNodesResult.message, 400);
+  }
+  const frontierLimitResult = parseBodyPositiveInt(
+    "frontierLimit",
+    body.frontierLimit,
+    100,
+    1,
+    1000
+  );
+  if (!frontierLimitResult.ok) {
+    return errorResponse("VALIDATION", frontierLimitResult.message, 400);
+  }
+  const visitedLimitResult = parseBodyPositiveInt(
+    "visitedLimit",
+    body.visitedLimit,
+    500,
+    1,
+    5000
+  );
+  if (!visitedLimitResult.ok) {
+    return errorResponse("VALIDATION", visitedLimitResult.message, 400);
+  }
+
+  const result = await diagnoseGraphQuery(store, rootRef, {
+    direction,
+    edgeType,
+    maxDepth: maxDepthResult.value,
+    maxNodes: maxNodesResult.value,
+    frontierLimit: frontierLimitResult.value,
+    visitedLimit: visitedLimitResult.value,
+    contentTypeRules: normalizeContentTypes(config.contentTypes ?? []).rules,
+  });
+  if (!result.success) {
+    return errorResponse(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error,
+      result.isValidation ? 400 : 500
+    );
+  }
+
+  return jsonResponse(result.data satisfies GraphQueryResponse);
+}

package/src/serve/server.ts

@@ -46,6 +46,7 @@ import {
   handlePublishExport,
   handlePresets,
   handleQuery,
+  handleQueryDiagnose,
   handleRefactorPlan,
   handleRenameDoc,
   handleRevealDoc,
@@ -58,7 +59,7 @@ import {
   handleUpdateCollection,
   handleUpdateDoc,
 } from "./routes/api";
-import { handleGraph } from "./routes/graph";
+import { handleGraph, handleGraphQuery } from "./routes/graph";
 import {
   handleDocBacklinks,
   handleDocLinks,
@@ -489,6 +490,17 @@ export async function startServer(
             );
           },
         },
+        "/api/query/diagnose": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            return withSecurityHeaders(
+              await handleQueryDiagnose(ctxHolder.current, req),
+              isDev
+            );
+          },
+        },
         "/api/ask": {
           POST: async (req: Request) => {
             if (!isRequestAllowed(req, port)) {
@@ -653,6 +665,17 @@ export async function startServer(
             return withSecurityHeaders(await handleGraph(store, url), isDev);
           },
         },
+        "/api/graph/query": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            return withSecurityHeaders(
+              await handleGraphQuery(store, ctxHolder.config, req),
+              isDev
+            );
+          },
+        },
       },
     });
   } catch (e) {

package/src/store/migrations/010-typed-edges.ts

@@ -0,0 +1,67 @@
+/**
+ * Migration: typed semantic document edges.
+ *
+ * @module src/store/migrations/010-typed-edges
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+const TABLE_INFO_DOCUMENTS = "PRAGMA table_info(documents)";
+
+interface TableInfoRow {
+  name: string;
+}
+
+function getDocumentColumns(db: Database): Set<string> {
+  const rows = db.query<TableInfoRow, []>(TABLE_INFO_DOCUMENTS).all();
+  return new Set(rows.map((row) => row.name));
+}
+
+export const migration: Migration = {
+  version: 10,
+  name: "typed_edges",
+
+  up(db: Database): void {
+    const columns = getDocumentColumns(db);
+    if (!columns.has("content_type_source")) {
+      db.exec("ALTER TABLE documents ADD COLUMN content_type_source TEXT");
+    }
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS doc_edges (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        src_doc_id INTEGER NOT NULL,
+        dst_doc_id INTEGER NOT NULL,
+        edge_type TEXT NOT NULL,
+        confidence TEXT NOT NULL CHECK (confidence IN ('parsed', 'configured', 'manual', 'inferred')),
+        source TEXT NOT NULL CHECK (source IN ('wikilink', 'markdown-link', 'frontmatter-relation')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(src_doc_id, dst_doc_id, edge_type, source),
+        FOREIGN KEY (src_doc_id) REFERENCES documents(id) ON DELETE CASCADE,
+        FOREIGN KEY (dst_doc_id) REFERENCES documents(id) ON DELETE CASCADE
+      )
+    `);
+
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_doc_edges_src_type
+      ON doc_edges(src_doc_id, edge_type)
+    `);
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_doc_edges_dst_type
+      ON doc_edges(dst_doc_id, edge_type)
+    `);
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_documents_content_type_source
+      ON documents(content_type_source)
+    `);
+  },
+
+  down(db: Database): void {
+    db.exec("DROP INDEX IF EXISTS idx_documents_content_type_source");
+    db.exec("DROP INDEX IF EXISTS idx_doc_edges_dst_type");
+    db.exec("DROP INDEX IF EXISTS idx_doc_edges_src_type");
+    // Keep table/column on rollback; SQLite column drop requires rebuild.
+  },
+};

package/src/store/migrations/011-doc-edge-traversal-indexes.ts

@@ -0,0 +1,30 @@
+/**
+ * Migration: covering indexes for bounded typed-edge traversal.
+ *
+ * @module src/store/migrations/011-doc-edge-traversal-indexes
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 11,
+  name: "doc_edge_traversal_indexes",
+
+  up(db: Database): void {
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_doc_edges_src_type_dst_id
+      ON doc_edges(src_doc_id, edge_type, dst_doc_id, id)
+    `);
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_doc_edges_dst_type_src_id
+      ON doc_edges(dst_doc_id, edge_type, src_doc_id, id)
+    `);
+  },
+
+  down(db: Database): void {
+    db.exec("DROP INDEX IF EXISTS idx_doc_edges_dst_type_src_id");
+    db.exec("DROP INDEX IF EXISTS idx_doc_edges_src_type_dst_id");
+  },
+};

package/src/store/migrations/index.ts

@@ -23,6 +23,8 @@ import { migration as m006 } from "./006-document-metadata";
 import { migration as m007 } from "./007-document-date-fields";
 import { migration as m008 } from "./008-vector-fingerprints";
 import { migration as m009 } from "./009-content-type-rule-fingerprint";
+import { migration as m010 } from "./010-typed-edges";
+import { migration as m011 } from "./011-doc-edge-traversal-indexes";
 
 /** All migrations in order */
 export const migrations = [
@@ -35,4 +37,6 @@ export const migrations = [
   m007,
   m008,
   m009,
+  m010,
+  m011,
 ];