@gmickel/gno 1.18.0 → 1.20.0

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

@@ -0,0 +1,564 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/ask@1.0",
+  "title": "GNO Ask Response",
+  "description": "Response from gno ask command",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["query", "mode", "results", "meta"],
+  "allOf": [
+    {
+      "if": {
+        "properties": { "verification": {} },
+        "required": ["verification"]
+      },
+      "then": {
+        "required": ["answer", "citations"],
+        "properties": {
+          "answer": {},
+          "citations": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": { "evidenceId": {} },
+              "required": ["evidenceId"]
+            }
+          },
+          "meta": {
+            "type": "object",
+            "required": ["verificationRequested", "abstained"],
+            "properties": {
+              "verificationRequested": { "const": true },
+              "abstained": {}
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "meta": {
+            "type": "object",
+            "required": ["verificationRequested"],
+            "properties": { "verificationRequested": { "const": true } }
+          }
+        },
+        "required": ["meta"]
+      },
+      "then": {
+        "properties": { "verification": {} },
+        "required": ["verification"]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "verification": {
+            "type": "object",
+            "properties": {
+              "claims": {
+                "type": "object",
+                "properties": { "answerStatus": { "const": "abstained" } },
+                "required": ["answerStatus"]
+              }
+            },
+            "required": ["claims"]
+          }
+        },
+        "required": ["verification"]
+      },
+      "then": {
+        "properties": {
+          "citations": { "type": "array", "maxItems": 0 },
+          "meta": {
+            "type": "object",
+            "properties": { "abstained": { "const": true } }
+          }
+        }
+      },
+      "else": {
+        "if": {
+          "properties": { "verification": {} },
+          "required": ["verification"]
+        },
+        "then": {
+          "properties": {
+            "citations": { "type": "array", "minItems": 1 },
+            "meta": {
+              "type": "object",
+              "properties": { "abstained": { "const": false } }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$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)",
+          "pattern": "^gno://[^/]+/.+"
+        },
+        "title": {
+          "type": "string",
+          "description": "Extracted document title (optional)"
+        },
+        "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"]
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "Original query"
+    },
+    "mode": {
+      "type": "string",
+      "description": "Retrieval mode used",
+      "enum": ["hybrid", "bm25_only"]
+    },
+    "queryLanguage": {
+      "type": "string",
+      "description": "Detected or specified query language",
+      "default": "auto"
+    },
+    "answer": {
+      "type": "string",
+      "description": "Grounded answer (present only if --answer and generation available)"
+    },
+    "citations": {
+      "type": "array",
+      "description": "Citations for the answer",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["docid", "uri"],
+        "properties": {
+          "evidenceId": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "docid": {
+            "type": "string",
+            "description": "Document ID",
+            "pattern": "^#[a-f0-9]{6,8}$"
+          },
+          "uri": {
+            "type": "string",
+            "description": "Document URI",
+            "pattern": "^gno://[^/]+/.+"
+          },
+          "startLine": {
+            "type": "integer",
+            "description": "Citation start line",
+            "minimum": 1
+          },
+          "endLine": {
+            "type": "integer",
+            "description": "Citation end line",
+            "minimum": 1
+          }
+        }
+      }
+    },
+    "results": {
+      "type": "array",
+      "description": "Search results (same shape as query results)",
+      "items": {
+        "$ref": "#/$defs/searchResult"
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "mode",
+        "capsule",
+        "freshness",
+        "claims",
+        "semantic"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "1.0" },
+        "mode": { "const": "closed_capsule" },
+        "capsule": {
+          "$ref": "gno://schemas/context-capsule-v1@1.0"
+        },
+        "freshness": {
+          "$ref": "gno://schemas/context-capsule-verification@1.0"
+        },
+        "claims": {
+          "$ref": "gno://schemas/claim-verification@1.0"
+        },
+        "semantic": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "status",
+            "reason",
+            "schemaRequested",
+            "schemaEnforced",
+            "modelFingerprint",
+            "configFingerprint",
+            "verifierFingerprint",
+            "candidateClaims",
+            "verifiedClaims",
+            "unresolvedClaims",
+            "modelCalls",
+            "durationMs"
+          ],
+          "properties": {
+            "status": {
+              "enum": ["completed", "unavailable", "failed"]
+            },
+            "reason": {
+              "enum": [
+                "verified",
+                "no_candidates",
+                "verifier_unavailable",
+                "structured_output_unavailable",
+                "input_limit_exceeded",
+                "generation_failed",
+                "invalid_output"
+              ]
+            },
+            "schemaRequested": { "type": "boolean" },
+            "schemaEnforced": { "type": "boolean" },
+            "modelFingerprint": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "pattern": "^[a-f0-9]{64}$"
+                },
+                { "type": "null" }
+              ]
+            },
+            "configFingerprint": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            },
+            "verifierFingerprint": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "pattern": "^[a-f0-9]{64}$"
+                },
+                { "type": "null" }
+              ]
+            },
+            "candidateClaims": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "verifiedClaims": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "unresolvedClaims": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "modelCalls": { "enum": [0, 1] },
+            "durationMs": { "type": "number", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Retrieval metadata",
+      "required": ["expanded", "reranked", "vectorsUsed"],
+      "properties": {
+        "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"
+        },
+        "intent": {
+          "type": "string",
+          "description": "Disambiguating context used to steer retrieval without being searched directly"
+        },
+        "candidateLimit": {
+          "type": "integer",
+          "description": "Max candidates sent to reranking (if applicable)",
+          "minimum": 1
+        },
+        "exclude": {
+          "type": "array",
+          "description": "Explicit exclusion terms applied",
+          "items": { "type": "string" }
+        },
+        "queryModes": {
+          "type": "object",
+          "description": "Summary of structured query modes applied",
+          "required": ["term", "intent", "hyde"],
+          "properties": {
+            "term": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "intent": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "hyde": {
+              "type": "boolean"
+            }
+          }
+        },
+        "answerGenerated": {
+          "type": "boolean",
+          "description": "Whether an answer was generated"
+        },
+        "verificationRequested": {
+          "type": "boolean"
+        },
+        "abstained": {
+          "type": "boolean"
+        },
+        "totalResults": {
+          "type": "integer",
+          "description": "Number of results returned",
+          "minimum": 0
+        },
+        "answerContext": {
+          "type": "object",
+          "description": "Answer context selection explain payload",
+          "required": [
+            "strategy",
+            "targetSources",
+            "facets",
+            "selected",
+            "dropped"
+          ],
+          "properties": {
+            "strategy": {
+              "type": "string",
+              "enum": ["adaptive_coverage_v1"]
+            },
+            "targetSources": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "facets": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "selected": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "docid",
+                  "uri",
+                  "score",
+                  "queryTokenHits",
+                  "facetHits",
+                  "reason"
+                ],
+                "properties": {
+                  "docid": {
+                    "type": "string",
+                    "pattern": "^#[a-f0-9]{6,8}$"
+                  },
+                  "uri": {
+                    "type": "string",
+                    "pattern": "^gno://[^/]+/.+"
+                  },
+                  "score": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "queryTokenHits": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "facetHits": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "reason": {
+                    "type": "string"
+                  }
+                }
+              }
+            },
+            "dropped": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "docid",
+                  "uri",
+                  "score",
+                  "queryTokenHits",
+                  "facetHits",
+                  "reason"
+                ],
+                "properties": {
+                  "docid": {
+                    "type": "string",
+                    "pattern": "^#[a-f0-9]{6,8}$"
+                  },
+                  "uri": {
+                    "type": "string",
+                    "pattern": "^gno://[^/]+/.+"
+                  },
+                  "score": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  },
+                  "queryTokenHits": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "facetHits": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "reason": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,131 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/backlinks@1.0",
+  "title": "GNO Backlinks",
+  "description": "List of documents linking to a target document",
+  "type": "object",
+  "required": ["backlinks", "meta"],
+  "properties": {
+    "backlinks": {
+      "type": "array",
+      "description": "List of documents linking to this one",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "required": ["sourceDocid", "sourceUri", "startLine", "startCol"],
+            "additionalProperties": false,
+            "properties": {
+              "sourceDocid": {
+                "type": "string",
+                "description": "Source document ID"
+              },
+              "sourceUri": {
+                "type": "string",
+                "description": "Source document URI"
+              },
+              "sourceTitle": {
+                "type": "string",
+                "description": "Source document title"
+              },
+              "linkText": {
+                "type": "string",
+                "description": "Link display text"
+              },
+              "startLine": {
+                "type": "integer",
+                "description": "1-based line number in source",
+                "minimum": 1
+              },
+              "startCol": {
+                "type": "integer",
+                "description": "1-based column in source",
+                "minimum": 1
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "sourceDocid",
+              "sourceUri",
+              "edgeType",
+              "confidence",
+              "edgeSource"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "sourceDocid": {
+                "type": "string",
+                "description": "Source document ID"
+              },
+              "sourceUri": {
+                "type": "string",
+                "description": "Source document URI"
+              },
+              "sourceTitle": {
+                "type": "string",
+                "description": "Source 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", "totalBacklinks"],
+      "properties": {
+        "docid": {
+          "type": "string",
+          "description": "Target document ID"
+        },
+        "uri": {
+          "type": "string",
+          "description": "Target document URI"
+        },
+        "title": {
+          "type": "string",
+          "description": "Target document title"
+        },
+        "totalBacklinks": {
+          "type": "integer",
+          "description": "Total number of backlinks",
+          "minimum": 0
+        },
+        "collection": {
+          "type": "string",
+          "description": "Collection filter applied"
+        },
+        "edgeTypeFilter": {
+          "type": "string",
+          "description": "Semantic edge-type filter applied"
+        },
+        "relationFilter": {
+          "type": "string",
+          "description": "Semantic relation filter applied"
+        },
+        "semantic": {
+          "type": "boolean",
+          "description": "Whether backlinks came from the semantic edge layer"
+        }
+      }
+    }
+  }
+}