@gmickel/gno 1.17.0 → 1.19.0

package/spec/output-schemas/retrieval-trace-summary.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/retrieval-trace-summary@1.0",
+  "title": "GNO Retrieval Trace Summary",
+  "definitions": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "textShape": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["characters", "terms"],
+      "properties": {
+        "characters": { "type": "integer", "minimum": 0 },
+        "terms": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "fingerprints": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pipeline", "model", "config", "index"],
+      "properties": {
+        "pipeline": { "$ref": "#/definitions/sha256" },
+        "model": { "$ref": "#/definitions/sha256" },
+        "config": { "$ref": "#/definitions/sha256" },
+        "index": { "$ref": "#/definitions/sha256" }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "traceId",
+    "schemaVersion",
+    "redactionMode",
+    "replayCapable",
+    "status",
+    "queryShape",
+    "goalShape",
+    "fingerprints",
+    "createdAtMs",
+    "updatedAtMs",
+    "expiresAtMs",
+    "byteSize",
+    "creationDigest"
+  ],
+  "properties": {
+    "traceId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "schemaVersion": { "const": "1.0" },
+    "redactionMode": { "enum": ["metadata", "replay"] },
+    "replayCapable": { "type": "boolean" },
+    "status": {
+      "enum": ["open", "completed", "partial", "failed", "cancelled"]
+    },
+    "queryShape": { "$ref": "#/definitions/textShape" },
+    "goalShape": { "$ref": "#/definitions/textShape" },
+    "fingerprints": { "$ref": "#/definitions/fingerprints" },
+    "createdAtMs": { "type": "integer", "minimum": 0 },
+    "updatedAtMs": { "type": "integer", "minimum": 0 },
+    "expiresAtMs": { "type": "integer", "minimum": 0 },
+    "byteSize": { "type": "integer", "minimum": 0 },
+    "creationDigest": { "$ref": "#/definitions/sha256" }
+  }
+}

package/spec/output-schemas/search-result.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/search-result@1.0",
+  "title": "GNO Search Result Item",
+  "description": "A single search result from gno search, vsearch, or query commands",
+  "type": "object",
+  "required": ["docid", "score", "uri", "snippet", "source"],
+  "properties": {
+    "docid": {
+      "type": "string",
+      "description": "Document ID (short hash of source)",
+      "pattern": "^#[a-f0-9]{6,8}$"
+    },
+    "score": {
+      "type": "number",
+      "description": "Relevance score (0-1 normalized)",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "uri": {
+      "type": "string",
+      "description": "Document URI (gno://collection/path, optionally with ?index= for non-default indexes)",
+      "pattern": "^gno://[^/]+/.+(\\?index=[^\\s]+)?$"
+    },
+    "line": {
+      "type": "integer",
+      "description": "Best matching/source line (1-indexed)",
+      "minimum": 1
+    },
+    "title": {
+      "type": "string",
+      "description": "Extracted document title (optional)"
+    },
+    "contentType": {
+      "type": "string",
+      "description": "Canonical inferred content type"
+    },
+    "categories": {
+      "type": "array",
+      "description": "Category filters associated with the document",
+      "items": {
+        "type": "string"
+      }
+    },
+    "snippetLanguage": {
+      "type": "string",
+      "description": "Language of snippet content (BCP-47 or 'und')"
+    },
+    "context": {
+      "type": "string",
+      "description": "Resolved user-configured retrieval guidance, ordered from global to collection to matching path prefixes"
+    },
+    "snippet": {
+      "type": "string",
+      "description": "Matching text snippet from document mirror"
+    },
+    "snippetRange": {
+      "type": "object",
+      "description": "Line range of snippet in mirror content",
+      "properties": {
+        "startLine": {
+          "type": "integer",
+          "description": "Start line (1-indexed)",
+          "minimum": 1
+        },
+        "endLine": {
+          "type": "integer",
+          "description": "End line (1-indexed, inclusive)",
+          "minimum": 1
+        }
+      },
+      "required": ["startLine", "endLine"]
+    },
+    "source": {
+      "type": "object",
+      "description": "Source file metadata",
+      "required": ["relPath", "mime", "ext"],
+      "properties": {
+        "absPath": {
+          "type": "string",
+          "description": "Absolute path (included with --source or in MCP)"
+        },
+        "relPath": {
+          "type": "string",
+          "description": "Path relative to collection root"
+        },
+        "mime": {
+          "type": "string",
+          "description": "MIME type of source file"
+        },
+        "ext": {
+          "type": "string",
+          "description": "File extension (including dot)",
+          "pattern": "^\\.[a-zA-Z0-9]+$"
+        },
+        "modifiedAt": {
+          "type": "string",
+          "description": "Last modification time (ISO 8601)",
+          "format": "date-time"
+        },
+        "sizeBytes": {
+          "type": "integer",
+          "description": "File size in bytes",
+          "minimum": 0
+        },
+        "sourceHash": {
+          "type": "string",
+          "description": "SHA-256 hash of source file"
+        }
+      }
+    },
+    "conversion": {
+      "type": "object",
+      "description": "Conversion metadata",
+      "properties": {
+        "converterId": {
+          "type": "string",
+          "description": "Converter identifier (e.g., 'adapter/markitdown-js')"
+        },
+        "converterVersion": {
+          "type": "string",
+          "description": "Converter version"
+        },
+        "mirrorHash": {
+          "type": "string",
+          "description": "SHA-256 hash of mirror content"
+        },
+        "warnings": {
+          "type": "array",
+          "description": "Conversion warnings",
+          "items": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string",
+                "enum": [
+                  "LOSSY",
+                  "TRUNCATED",
+                  "PARTIAL",
+                  "UNSUPPORTED_FEATURE",
+                  "LOW_CONFIDENCE"
+                ]
+              },
+              "message": {
+                "type": "string"
+              }
+            },
+            "required": ["code", "message"]
+          }
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/search-results.schema.json

@@ -0,0 +1,338 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/search-results@1.0",
+  "title": "GNO Search Results",
+  "description": "Array of search results with metadata",
+  "type": "object",
+  "required": ["results", "meta"],
+  "$defs": {
+    "searchResult": {
+      "type": "object",
+      "required": ["docid", "score", "uri", "snippet", "source"],
+      "properties": {
+        "docid": {
+          "type": "string",
+          "description": "Document ID (short hash of source)",
+          "pattern": "^#[a-f0-9]{6,8}$"
+        },
+        "score": {
+          "type": "number",
+          "description": "Relevance score (0-1 normalized)",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "uri": {
+          "type": "string",
+          "description": "Document URI (gno://collection/path, optionally with ?index= for non-default indexes)",
+          "pattern": "^gno://[^/]+/.+(\\?index=[^\\s]+)?$"
+        },
+        "line": {
+          "type": "integer",
+          "description": "Best matching/source line (1-indexed)",
+          "minimum": 1
+        },
+        "title": {
+          "type": "string",
+          "description": "Extracted document title (optional)"
+        },
+        "contentType": {
+          "type": "string",
+          "description": "Canonical inferred content type"
+        },
+        "categories": {
+          "type": "array",
+          "description": "Category filters associated with the document",
+          "items": {
+            "type": "string"
+          }
+        },
+        "snippetLanguage": {
+          "type": "string",
+          "description": "Language of snippet content (BCP-47 or 'und')"
+        },
+        "context": {
+          "type": "string",
+          "description": "Resolved user-configured retrieval guidance, ordered from global to collection to matching path prefixes"
+        },
+        "snippet": {
+          "type": "string",
+          "description": "Matching text snippet from document mirror"
+        },
+        "snippetRange": {
+          "type": "object",
+          "description": "Line range of snippet in mirror content",
+          "properties": {
+            "startLine": {
+              "type": "integer",
+              "description": "Start line (1-indexed)",
+              "minimum": 1
+            },
+            "endLine": {
+              "type": "integer",
+              "description": "End line (1-indexed, inclusive)",
+              "minimum": 1
+            }
+          },
+          "required": ["startLine", "endLine"]
+        },
+        "source": {
+          "type": "object",
+          "description": "Source file metadata",
+          "required": ["relPath", "mime", "ext"],
+          "properties": {
+            "absPath": {
+              "type": "string",
+              "description": "Absolute path (included with --source or in MCP)"
+            },
+            "relPath": {
+              "type": "string",
+              "description": "Path relative to collection root"
+            },
+            "mime": {
+              "type": "string",
+              "description": "MIME type of source file"
+            },
+            "ext": {
+              "type": "string",
+              "description": "File extension (including dot)",
+              "pattern": "^\\.[a-zA-Z0-9]+$"
+            },
+            "modifiedAt": {
+              "type": "string",
+              "description": "Last modification time (ISO 8601)",
+              "format": "date-time"
+            },
+            "documentDate": {
+              "type": "string",
+              "description": "Canonical frontmatter document date (ISO 8601)",
+              "format": "date-time"
+            },
+            "sizeBytes": {
+              "type": "integer",
+              "description": "File size in bytes",
+              "minimum": 0
+            },
+            "sourceHash": {
+              "type": "string",
+              "description": "SHA-256 hash of source file"
+            }
+          }
+        },
+        "conversion": {
+          "type": "object",
+          "description": "Conversion metadata",
+          "properties": {
+            "converterId": {
+              "type": "string",
+              "description": "Converter identifier (e.g., 'adapter/markitdown-js')"
+            },
+            "converterVersion": {
+              "type": "string",
+              "description": "Converter version"
+            },
+            "mirrorHash": {
+              "type": "string",
+              "description": "SHA-256 hash of mirror content"
+            },
+            "warnings": {
+              "type": "array",
+              "description": "Conversion warnings",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "LOSSY",
+                      "TRUNCATED",
+                      "PARTIAL",
+                      "UNSUPPORTED_FEATURE",
+                      "LOW_CONFIDENCE"
+                    ]
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                },
+                "required": ["code", "message"]
+              }
+            }
+          }
+        },
+        "tags": {
+          "type": "array",
+          "description": "Tags associated with the document",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "properties": {
+    "results": {
+      "type": "array",
+      "description": "Array of search result items",
+      "items": {
+        "$ref": "#/$defs/searchResult"
+      }
+    },
+    "meta": {
+      "type": "object",
+      "description": "Search metadata",
+      "required": ["query", "mode", "totalResults"],
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Original search query"
+        },
+        "mode": {
+          "type": "string",
+          "description": "Search mode used",
+          "enum": ["bm25", "vector", "hybrid", "bm25_only"]
+        },
+        "expanded": {
+          "type": "boolean",
+          "description": "Whether query expansion was used"
+        },
+        "reranked": {
+          "type": "boolean",
+          "description": "Whether reranking was applied"
+        },
+        "vectorsUsed": {
+          "type": "boolean",
+          "description": "Whether vector search was used"
+        },
+        "totalResults": {
+          "type": "integer",
+          "description": "Total number of results returned",
+          "minimum": 0
+        },
+        "collection": {
+          "type": "string",
+          "description": "Collection filter if applied"
+        },
+        "intent": {
+          "type": "string",
+          "description": "Disambiguating context used to steer retrieval without being searched directly"
+        },
+        "lang": {
+          "type": "string",
+          "description": "Language filter/hint if applied"
+        },
+        "since": {
+          "type": "string",
+          "description": "Temporal lower bound applied (ISO 8601)",
+          "format": "date-time"
+        },
+        "until": {
+          "type": "string",
+          "description": "Temporal upper bound applied (ISO 8601)",
+          "format": "date-time"
+        },
+        "categories": {
+          "type": "array",
+          "description": "Category/content-type filters applied (if any)",
+          "items": { "type": "string" }
+        },
+        "author": {
+          "type": "string",
+          "description": "Author filter applied (if any)"
+        },
+        "candidateLimit": {
+          "type": "integer",
+          "description": "Max candidates sent to reranking (if applicable)",
+          "minimum": 1
+        },
+        "graphExpansion": {
+          "type": "object",
+          "description": "Bounded one-hop graph retrieval expansion summary",
+          "required": [
+            "enabled",
+            "seedCount",
+            "candidateCount",
+            "maxCandidates",
+            "edgeConfidence",
+            "fallbackReasons"
+          ],
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Whether graph expansion added candidates"
+            },
+            "seedCount": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of top retrieval seeds used for graph expansion"
+            },
+            "candidateCount": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of graph neighbors added to the candidate set"
+            },
+            "maxCandidates": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Graph candidate cap applied"
+            },
+            "edgeConfidence": {
+              "type": "object",
+              "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 }
+              }
+            },
+            "fallbackReasons": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Reasons graph expansion did not add candidates, if any"
+            }
+          }
+        },
+        "exclude": {
+          "type": "array",
+          "description": "Explicit exclusion terms applied",
+          "items": { "type": "string" }
+        },
+        "queryLanguage": {
+          "type": "string",
+          "description": "Detected or overridden query language for prompt selection (typically BCP-47)"
+        },
+        "queryModes": {
+          "type": "object",
+          "description": "Summary of structured query modes applied",
+          "required": ["term", "intent", "hyde"],
+          "properties": {
+            "term": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of term mode entries"
+            },
+            "intent": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of intent mode entries"
+            },
+            "hyde": {
+              "type": "boolean",
+              "description": "Whether a hyde entry was provided"
+            }
+          }
+        },
+        "tagsAll": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tags ALL filter applied (if any)"
+        },
+        "tagsAny": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Tags ANY filter applied (if any)"
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/similar@1.0",
+  "title": "GNO Similar Documents",
+  "description": "List of semantically similar documents",
+  "type": "object",
+  "required": ["similar", "meta"],
+  "properties": {
+    "similar": {
+      "type": "array",
+      "description": "List of similar documents ordered by similarity score",
+      "items": {
+        "type": "object",
+        "required": ["docid", "uri", "score"],
+        "properties": {
+          "docid": {
+            "type": "string",
+            "description": "Document ID"
+          },
+          "uri": {
+            "type": "string",
+            "description": "Document URI"
+          },
+          "title": {
+            "type": "string",
+            "description": "Document title"
+          },
+          "score": {
+            "type": "number",
+            "description": "Similarity score (0-1, higher is more similar)",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "collection": {
+            "type": "string",
+            "description": "Document collection"
+          },
+          "relPath": {
+            "type": "string",
+            "description": "Relative path within collection"
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "required": ["docid", "totalResults"],
+      "properties": {
+        "docid": {
+          "type": "string",
+          "description": "Source document ID"
+        },
+        "uri": {
+          "type": "string",
+          "description": "Source document URI"
+        },
+        "title": {
+          "type": "string",
+          "description": "Source document title"
+        },
+        "totalResults": {
+          "type": "integer",
+          "description": "Number of similar documents returned",
+          "minimum": 0
+        },
+        "limit": {
+          "type": "integer",
+          "description": "Maximum results requested",
+          "minimum": 1
+        },
+        "threshold": {
+          "type": "number",
+          "description": "Minimum similarity threshold used",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "crossCollection": {
+          "type": "boolean",
+          "description": "Whether cross-collection search was enabled"
+        }
+      }
+    }
+  }
+}