Capability definition updates

Author: cmtonkinson

Makefile

@@ -10,6 +10,9 @@ GLOSSARY_GEN    := scripts/generate_glossary_docs.py
 SERVICE_API_DOC := docs/service-api.md
 SERVICE_API_GEN := scripts/generate_service_api_docs.py
 SERVICE_API_SRC := $(shell find services -type f -path 'services/*/*/service.py' | sort)
+CAPABILITY_DOC  := docs/capabilities.md
+CAPABILITY_GEN  := scripts/generate_capability_docs.py
+CAPABILITY_SRC  := $(shell find capabilities -type f | sort)
 DIAGRAM_SRC     := img/diagrams.drawio
 DIAGRAM_GEN     := img/export-diagrams.sh
 DIAGRAM_PNGS    := \
@@ -62,14 +65,17 @@ test: check
 integration:
 	:
 
-docs: $(GLOSSARY_DOC) $(SERVICE_API_DOC) $(DIAGRAM_PNGS)
+docs: $(GLOSSARY_DOC) $(SERVICE_API_DOC) $(CAPABILITY_DOC) $(DIAGRAM_PNGS)
 
 $(GLOSSARY_DOC): $(GLOSSARY_SRC) $(GLOSSARY_GEN)
 	$(PY) $(GLOSSARY_GEN)
 
 $(SERVICE_API_DOC): $(SERVICE_API_SRC) $(SERVICE_API_GEN)
 	$(PY) $(SERVICE_API_GEN)
 
+$(CAPABILITY_DOC): $(CAPABILITY_SRC) $(CAPABILITY_GEN)
+	$(PY) $(CAPABILITY_GEN)
+
 $(DIAGRAM_PNGS): $(DIAGRAM_SRC) $(DIAGRAM_GEN)
 	$(DIAGRAM_GEN) $(DIAGRAM_SRC)
 

capabilities/cache/cache-delete-value/capability.json

@@ -7,7 +7,6 @@
   "autonomy": 0,
   "requires_approval": true,
   "side_effects": ["writes_cache"],
-  "required_capabilities": [],
   "input_schema": {
     "component_id": "string | The canonical component id namespace for the cache key.",
     "key": "string | The cache key within the component namespace."

capabilities/cache/cache-get-value/capability.json

@@ -7,7 +7,6 @@
   "autonomy": 0,
   "requires_approval": false,
   "side_effects": [],
-  "required_capabilities": [],
   "input_schema": {
     "component_id": "string | The canonical component id namespace for the cache key.",
     "key": "string | The cache key within the component namespace."

capabilities/cache/cache-peek-queue/capability.json

@@ -7,7 +7,6 @@
   "autonomy": 0,
   "requires_approval": false,
   "side_effects": [],
-  "required_capabilities": [],
   "input_schema": {
     "component_id": "string | The canonical component id namespace for the queue.",
     "queue": "string | The queue name within the component namespace."

capabilities/cache/cache-pop-queue/capability.json

@@ -7,7 +7,6 @@
   "autonomy": 0,
   "requires_approval": false,
   "side_effects": [],
-  "required_capabilities": [],
   "input_schema": {
     "component_id": "string | The canonical component id namespace for the queue.",
     "queue": "string | The queue name within the component namespace."

capabilities/cache/cache-push-queue/capability.json

@@ -7,7 +7,6 @@
   "autonomy": 0,
   "requires_approval": true,
   "side_effects": ["writes_cache"],
-  "required_capabilities": [],
   "input_schema": {
     "component_id": "string | The canonical component id namespace for the queue.",
     "queue": "string | The queue name within the component namespace.",

capabilities/cache/cache-set-value/capability.json

@@ -7,7 +7,6 @@
   "autonomy": 0,
   "requires_approval": true,
   "side_effects": ["writes_cache"],
-  "required_capabilities": [],
   "input_schema": {
     "component_id": "string | The canonical component id namespace for the cache key.",
     "key": "string | The cache key within the component namespace.",

capabilities/demo-echo/capability.json

@@ -7,7 +7,6 @@
   "autonomy": 0,
   "requires_approval": false,
   "side_effects": [],
-  "required_capabilities": [],
   "input_schema": null,
   "output_schema": "string | Returns the static string 'Hello, World!'."
 }

capabilities/embedding/embedding-upsert-document-batch/README.md

@@ -0,0 +1,13 @@
+# embedding-upsert-document-batch
+
+Persist a batch of embedding vectors for chunk and spec pairs.
+
+## Parameters
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `items` | `list[UpsertEmbeddingVectorInput]` | yes | — | Batch of chunk/spec/vector inputs to persist. |
+
+## Returns
+
+`list[EmbeddingRecord]` — persisted embedding materialization records.

capabilities/embedding/embedding-upsert-document-batch/capability.json

@@ -0,0 +1,82 @@
+{
+  "capability_id": "embedding-upsert-document-batch",
+  "kind": "native_op",
+  "version": "1.0.0",
+  "summary": "Persist a batch of embedding vectors for chunk and spec pairs.",
+  "enabled": true,
+  "autonomy": 0,
+  "requires_approval": false,
+  "side_effects": ["writes_embeddings"],
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "items": {
+        "type": "array",
+        "description": "Batch of chunk/spec/vector inputs to persist.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "chunk_id": {
+              "type": "string"
+            },
+            "spec_id": {
+              "type": "string"
+            },
+            "vector": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              }
+            }
+          },
+          "required": ["chunk_id", "spec_id", "vector"]
+        }
+      }
+    },
+    "required": ["items"],
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "type": "array",
+    "description": "Persisted embedding materialization records.",
+    "items": {
+      "type": "object",
+      "properties": {
+        "chunk_id": {
+          "type": "string"
+        },
+        "spec_id": {
+          "type": "string"
+        },
+        "content_hash": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "indexed", "failed"]
+        },
+        "error_detail": {
+          "type": "string"
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "required": [
+        "chunk_id",
+        "spec_id",
+        "content_hash",
+        "status",
+        "error_detail",
+        "created_at",
+        "updated_at"
+      ]
+    }
+  },
+  "call_target": "service_embedding_authority.upsert_embedding_vectors"
+}