From 09fb87168f449635c3aea4b6f3aea5c1f1d42f79 Mon Sep 17 00:00:00 2001
From: Meta Vens <rwvens@hotmail.com>
Date: Sat, 31 Oct 2026 06:36:57 +0100
Subject: [PATCH] schemas: publish SearchSources and Sources (derived from the
 wire types)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .../huginn.mind_request.v1.schema.json        | 54 ++++++++++++
 .../huginn.mind_response.v1.schema.json       | 88 +++++++++++++++++++
 2 files changed, 142 insertions(+)

diff --git a/schemas/cultnet/huginn.mind_request.v1.schema.json b/schemas/cultnet/huginn.mind_request.v1.schema.json
index 0059e46..bbd18d7 100644
--- a/schemas/cultnet/huginn.mind_request.v1.schema.json
+++ b/schemas/cultnet/huginn.mind_request.v1.schema.json
@@ -132,6 +132,31 @@
       "required": [
         "PersonaPut"
       ]
+    },
+    {
+      "description": "Semantic search over the source index: the public forge repos' code and\ndocs, which no mind holds. The daemon embeds the text and asks the\nindex it does not write.",
+      "type": "object",
+      "properties": {
+        "SearchSources": {
+          "type": "object",
+          "properties": {
+            "instance": {
+              "$ref": "#/$defs/Slug"
+            },
+            "query": {
+              "$ref": "#/$defs/SourceQuery"
+            }
+          },
+          "required": [
+            "instance",
+            "query"
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "SearchSources"
+      ]
     }
   ],
   "$defs": {
@@ -1894,6 +1919,34 @@
       "type": "string",
       "maxLength": 64
     },
+    "SourceQuery": {
+      "description": "A source search: the text to find chunks near, how many, and optionally the\none forge repo (by name) to look in.",
+      "type": "object",
+      "properties": {
+        "repo": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Short"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "text": {
+          "$ref": "#/$defs/Line"
+        },
+        "top_k": {
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        }
+      },
+      "required": [
+        "text",
+        "top_k"
+      ]
+    },
     "StructuralDelta": {
       "type": "object",
       "properties": {
@@ -2046,6 +2099,7 @@
         },
         "pins": {
           "$ref": "#/$defs/Line"
+ygg-verify: exit 0
         }
       },
       "required": [
diff --git a/schemas/cultnet/huginn.mind_response.v1.schema.json b/schemas/cultnet/huginn.mind_response.v1.schema.json
index 0303dfc..111109f 100644
--- a/schemas/cultnet/huginn.mind_response.v1.schema.json
+++ b/schemas/cultnet/huginn.mind_response.v1.schema.json
@@ -101,6 +101,18 @@
         "PersonaPut"
       ]
     },
+    {
+      "type": "object",
+      "properties": {
+        "Sources": {
+          "$ref": "#/$defs/SourceHits"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "Sources"
+      ]
+    },
     {
       "description": "The answer did not fit one send and is being held for the client to\nfetch. Nothing in a mind produces this: the daemon's serve module does,\nin place of an answer, and the answer it stands for is the named\nMessagePack of the `HuginnMindResponse` the mind gave.",
       "type": "object",
@@ -4150,6 +4162,82 @@
       "type": "string",
       "maxLength": 64
     },
+    "SourceHit": {
+      "description": "One chunk the index holds, as the index holds it: the repo it belongs to,\nthe path in that repo, the commit whose blob it was cut from, its 1-based\ninclusive line range, and its text.",
+      "type": "object",
+      "properties": {
+        "commit": {
+          "type": "string"
+        },
+        "line_end": {
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        },
+        "line_start": {
+          "type": "integer",
+          "format": "uint32",
+          "minimum": 0
+        },
+        "path": {
+          "type": "string"
+        },
+        "repo": {
+          "type": "string"
+        },
+        "score": {
+          "type": "number",
+          "format": "float"
+        },
+        "text": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "repo",
+        "path",
+        "commit",
+        "line_start",
+        "line_end",
+        "score",
+        "text"
+      ]
+    },
+    "SourceHits": {
+      "description": "The answer to a source search, nearest first.",
+      "type": "object",
+      "properties": {
+        "hits": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/SourceHit"
+          }
+        },
+        "indexed_under": {
+          "$ref": "#/$defs/SourceModel"
+        }
+      },
+      "required": [
+        "indexed_under",
+        "hits"
+      ]
+    },
+    "SourceModel": {
+      "description": "The model a source collection was built under, and so the one a query must\nbe embedded by. The address of the embedder is no part of it.",
+      "type": "object",
+      "properties": {
+        "digest": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "digest"
+      ]
+    },
     "StructuralDelta": {
       "type": "object",
       "properties": {