@gmickel/gno 1.17.0 → 1.19.0

package/spec/output-schemas/graph.schema.json

@@ -0,0 +1,371 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/graph@1.0",
+  "title": "GNO Graph",
+  "description": "Knowledge graph of document links",
+  "type": "object",
+  "required": ["nodes", "links", "report", "meta"],
+  "properties": {
+    "nodes": {
+      "type": "array",
+      "description": "Graph nodes representing documents",
+      "items": {
+        "type": "object",
+        "required": ["id", "uri", "collection", "relPath", "degree"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Document ID (#hex)"
+          },
+          "uri": {
+            "type": "string",
+            "description": "Document URI (gno://collection/path)"
+          },
+          "title": {
+            "type": ["string", "null"],
+            "description": "Document title"
+          },
+          "collection": {
+            "type": "string",
+            "description": "Collection name"
+          },
+          "relPath": {
+            "type": "string",
+            "description": "Relative path within collection"
+          },
+          "degree": {
+            "type": "integer",
+            "description": "Total degree (in + out unique neighbors)",
+            "minimum": 0
+          },
+          "communityId": {
+            "type": "string",
+            "description": "Optional deterministic community id"
+          }
+        }
+      }
+    },
+    "links": {
+      "type": "array",
+      "description": "Graph edges between documents",
+      "items": {
+        "type": "object",
+        "required": [
+          "source",
+          "target",
+          "type",
+          "weight",
+          "confidence",
+          "audit"
+        ],
+        "properties": {
+          "source": {
+            "type": "string",
+            "description": "Source node ID (docid)"
+          },
+          "target": {
+            "type": "string",
+            "description": "Target node ID (docid)"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["wiki", "markdown", "similar"],
+            "description": "Edge type"
+          },
+          "weight": {
+            "type": "number",
+            "description": "Edge weight (link count or similarity score)",
+            "minimum": 0
+          },
+          "confidence": {
+            "type": "string",
+            "enum": ["explicit", "inferred", "ambiguous", "similarity"],
+            "description": "Trust classification for retrieval and agent audit"
+          },
+          "audit": {
+            "type": "object",
+            "description": "Metadata explaining how the edge was derived",
+            "required": ["resolution"],
+            "properties": {
+              "resolution": {
+                "type": "string",
+                "enum": [
+                  "exact-title",
+                  "exact-path",
+                  "path-fallback",
+                  "ambiguous-fallback",
+                  "similarity"
+                ]
+              },
+              "matchCount": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "score": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              }
+            }
+          }
+        }
+      }
+    },
+    "report": {
+      "type": "object",
+      "description": "Graph health and topology report",
+      "required": [
+        "hubs",
+        "bridgeCandidates",
+        "isolated",
+        "unresolvedLinks",
+        "edgeTypes",
+        "edgeConfidence",
+        "audit",
+        "communities"
+      ],
+      "properties": {
+        "hubs": {
+          "type": "array",
+          "description": "Highest-degree documents",
+          "items": { "$ref": "#/definitions/reportNode" }
+        },
+        "bridgeCandidates": {
+          "type": "array",
+          "description": "Bridge-like documents with both incoming and outgoing links",
+          "items": { "$ref": "#/definitions/reportNode" }
+        },
+        "isolated": {
+          "type": "object",
+          "required": ["total", "examples"],
+          "properties": {
+            "total": {
+              "type": "integer",
+              "description": "Total isolated active documents in scope",
+              "minimum": 0
+            },
+            "examples": {
+              "type": "array",
+              "description": "Example isolated documents",
+              "items": { "$ref": "#/definitions/reportNode" }
+            }
+          }
+        },
+        "unresolvedLinks": {
+          "type": "object",
+          "required": ["total", "byType"],
+          "properties": {
+            "total": {
+              "type": "integer",
+              "description": "Total unresolved wiki/markdown links in scope",
+              "minimum": 0
+            },
+            "byType": {
+              "type": "object",
+              "required": ["wiki", "markdown"],
+              "properties": {
+                "wiki": { "type": "integer", "minimum": 0 },
+                "markdown": { "type": "integer", "minimum": 0 }
+              }
+            }
+          }
+        },
+        "edgeTypes": {
+          "type": "object",
+          "required": ["wiki", "markdown", "similar"],
+          "properties": {
+            "wiki": { "type": "integer", "minimum": 0 },
+            "markdown": { "type": "integer", "minimum": 0 },
+            "similar": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "edgeConfidence": {
+          "type": "object",
+          "description": "Edge confidence counts before edge-limit truncation",
+          "required": ["explicit", "inferred", "ambiguous", "similarity"],
+          "properties": {
+            "explicit": { "type": "integer", "minimum": 0 },
+            "inferred": { "type": "integer", "minimum": 0 },
+            "ambiguous": { "type": "integer", "minimum": 0 },
+            "similarity": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "audit": {
+          "type": "object",
+          "description": "Graph audit rollups for fallback and similarity edges",
+          "required": ["inferredEdges", "ambiguousEdges", "similarityEdges"],
+          "properties": {
+            "inferredEdges": { "type": "integer", "minimum": 0 },
+            "ambiguousEdges": { "type": "integer", "minimum": 0 },
+            "similarityEdges": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "communities": {
+          "type": "object",
+          "description": "Deterministic community analysis over returned nodes",
+          "required": ["total", "algorithm", "skipped", "assignments", "top"],
+          "properties": {
+            "total": { "type": "integer", "minimum": 0 },
+            "algorithm": {
+              "type": "string",
+              "enum": ["deterministic-label-propagation"]
+            },
+            "skipped": { "type": "boolean" },
+            "assignments": {
+              "type": "object",
+              "additionalProperties": { "type": "string" }
+            },
+            "top": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/community" }
+            }
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "required": [
+        "nodeLimit",
+        "edgeLimit",
+        "totalNodes",
+        "totalEdges",
+        "totalEdgesUnresolved",
+        "returnedNodes",
+        "returnedEdges",
+        "truncated",
+        "linkedOnly",
+        "includedSimilar",
+        "similarAvailable",
+        "similarTopK",
+        "similarTruncatedByComputeBudget",
+        "warnings"
+      ],
+      "properties": {
+        "collection": {
+          "type": ["string", "null"],
+          "description": "Collection filter applied"
+        },
+        "nodeLimit": {
+          "type": "integer",
+          "description": "Node limit applied",
+          "minimum": 1
+        },
+        "edgeLimit": {
+          "type": "integer",
+          "description": "Edge limit applied",
+          "minimum": 1
+        },
+        "totalNodes": {
+          "type": "integer",
+          "description": "Total nodes before truncation",
+          "minimum": 0
+        },
+        "totalEdges": {
+          "type": "integer",
+          "description": "Total edges before truncation",
+          "minimum": 0
+        },
+        "totalEdgesUnresolved": {
+          "type": "integer",
+          "description": "Edges dropped due to unresolved targets",
+          "minimum": 0
+        },
+        "returnedNodes": {
+          "type": "integer",
+          "description": "Nodes actually returned",
+          "minimum": 0
+        },
+        "returnedEdges": {
+          "type": "integer",
+          "description": "Edges actually returned",
+          "minimum": 0
+        },
+        "truncated": {
+          "type": "boolean",
+          "description": "Whether results were truncated"
+        },
+        "linkedOnly": {
+          "type": "boolean",
+          "description": "Whether linkedOnly filter was applied"
+        },
+        "includedSimilar": {
+          "type": "boolean",
+          "description": "Whether similarity edges were included"
+        },
+        "similarAvailable": {
+          "type": "boolean",
+          "description": "Whether similarity search is available"
+        },
+        "similarTopK": {
+          "type": "integer",
+          "description": "Similar top-K value used",
+          "minimum": 1
+        },
+        "similarTruncatedByComputeBudget": {
+          "type": "boolean",
+          "description": "Whether similarity was truncated by compute budget"
+        },
+        "warnings": {
+          "type": "array",
+          "description": "Warning messages",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "reportNode": {
+      "type": "object",
+      "required": ["id", "uri", "collection", "relPath", "degree"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Document ID (#hex)"
+        },
+        "uri": {
+          "type": "string",
+          "description": "Document URI (gno://collection/path)"
+        },
+        "title": {
+          "type": ["string", "null"],
+          "description": "Document title"
+        },
+        "collection": {
+          "type": "string",
+          "description": "Collection name"
+        },
+        "relPath": {
+          "type": "string",
+          "description": "Relative path within collection"
+        },
+        "degree": {
+          "type": "integer",
+          "description": "Total degree (in + out unique neighbors)",
+          "minimum": 0
+        },
+        "communityId": {
+          "type": "string",
+          "description": "Optional deterministic community id"
+        }
+      }
+    },
+    "community": {
+      "type": "object",
+      "required": ["id", "label", "size", "edgeCount", "density", "topNodes"],
+      "properties": {
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "size": { "type": "integer", "minimum": 1 },
+        "edgeCount": { "type": "integer", "minimum": 0 },
+        "density": { "type": "number", "minimum": 0 },
+        "topNodes": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/reportNode" }
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/links-list.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/links-list@1.1",
+  "title": "GNO Links List",
+  "description": "List of outgoing links from a document",
+  "type": "object",
+  "required": ["links", "meta"],
+  "properties": {
+    "links": {
+      "type": "array",
+      "description": "List of outgoing links",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["targetRef", "linkType", "startLine", "startCol"],
+            "additionalProperties": false,
+            "properties": {
+              "targetRef": {
+                "type": "string",
+                "description": "Target reference (path or wiki name)"
+              },
+              "targetRefNorm": {
+                "type": "string",
+                "description": "Normalized target reference for matching"
+              },
+              "targetAnchor": {
+                "type": "string",
+                "description": "Target anchor/fragment without #"
+              },
+              "targetCollection": {
+                "type": "string",
+                "description": "Explicit collection prefix"
+              },
+              "linkType": {
+                "type": "string",
+                "enum": ["wiki", "markdown"],
+                "description": "Link type"
+              },
+              "linkText": {
+                "type": "string",
+                "description": "Display text (truncated 256 graphemes)"
+              },
+              "startLine": {
+                "type": "integer",
+                "description": "1-based line number",
+                "minimum": 1
+              },
+              "startCol": {
+                "type": "integer",
+                "description": "1-based column",
+                "minimum": 1
+              },
+              "endLine": {
+                "type": "integer",
+                "description": "1-based end line",
+                "minimum": 1
+              },
+              "endCol": {
+                "type": "integer",
+                "description": "1-based end column",
+                "minimum": 1
+              },
+              "source": {
+                "type": "string",
+                "enum": ["parsed", "user", "suggested"],
+                "description": "Source of the positional link"
+              },
+              "resolved": {
+                "type": "boolean",
+                "description": "Whether target document exists in index"
+              },
+              "resolvedDocid": {
+                "type": "string",
+                "description": "Docid of resolved target document"
+              },
+              "resolvedUri": {
+                "type": "string",
+                "description": "URI of resolved target document"
+              },
+              "resolvedTitle": {
+                "type": "string",
+                "description": "Title of resolved target document"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "targetDocid",
+              "targetUri",
+              "edgeType",
+              "confidence",
+              "edgeSource"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "targetDocid": {
+                "type": "string",
+                "description": "Target document ID"
+              },
+              "targetUri": {
+                "type": "string",
+                "description": "Target document URI"
+              },
+              "targetTitle": {
+                "type": "string",
+                "description": "Target document title"
+              },
+              "edgeType": {
+                "type": "string",
+                "description": "Semantic relationship type"
+              },
+              "relationType": {
+                "type": "string",
+                "description": "Alias of edgeType"
+              },
+              "confidence": {
+                "type": "string",
+                "enum": ["parsed", "configured", "manual", "inferred"]
+              },
+              "edgeSource": {
+                "type": "string",
+                "enum": ["wikilink", "markdown-link", "frontmatter-relation"]
+              }
+            }
+          }
+        ]
+      }
+    },
+    "meta": {
+      "type": "object",
+      "required": [
+        "docid",
+        "totalLinks",
+        "resolvedCount",
+        "resolutionAvailable"
+      ],
+      "properties": {
+        "docid": {
+          "type": "string",
+          "description": "Source document ID"
+        },
+        "uri": {
+          "type": "string",
+          "description": "Source document URI"
+        },
+        "title": {
+          "type": "string",
+          "description": "Source document title"
+        },
+        "totalLinks": {
+          "type": "integer",
+          "description": "Total number of outgoing links",
+          "minimum": 0
+        },
+        "resolvedCount": {
+          "type": "integer",
+          "description": "Number of links that resolved to existing documents",
+          "minimum": 0
+        },
+        "resolutionAvailable": {
+          "type": "boolean",
+          "description": "Whether link resolution completed successfully"
+        },
+        "typeFilter": {
+          "type": "string",
+          "enum": ["wiki", "markdown"],
+          "description": "Link type filter applied"
+        },
+        "edgeTypeFilter": {
+          "type": "string",
+          "description": "Semantic edge-type filter applied"
+        },
+        "relationFilter": {
+          "type": "string",
+          "description": "Semantic relation filter applied"
+        },
+        "semantic": {
+          "type": "boolean",
+          "description": "Whether links came from the semantic edge layer"
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/mcp-add-collection-result.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/mcp-add-collection-result@1.0",
+  "title": "GNO MCP Add Collection Result",
+  "description": "Result payload for gno_add_collection",
+  "type": "object",
+  "required": ["jobId", "collection", "status"],
+  "properties": {
+    "jobId": {
+      "type": "string",
+      "description": "Job identifier"
+    },
+    "collection": {
+      "type": "string",
+      "description": "Normalized collection name"
+    },
+    "status": {
+      "type": "string",
+      "description": "Job status",
+      "enum": ["started"]
+    }
+  }
+}